Network Ambulance (for Linux)

image:[AGPL-3.0,link="https://www.gnu.org/licenses/agpl-3.0"] image:[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-licence"] :toc: :toclevels: 3 :icons: font :source-highlighter: rouge

Network Recovery Unit is the AmbientOps module for diagnosing and repairing internet connectivity on Linux.

It is designed as the Linux counterpart to “Complete Internet Repair”-style tooling, but implemented with AmbientOps principles: plan-first changes, receipts, and safe defaults.

Important

Project status: Re-scope / integration rewrite in progress This repo previously explored broader ambitions (traffic shaping, PAN setup, beyond-computer networking). Those are now v3 goals for AmbientOps. v1 here focuses on “get Linux online again” reliably.

Where it fits in AmbientOps

Network Recovery Unit is used by:

• A&E (System Emergency Room) for network emergencies (quick handoff)

• Operating Theatre as a procedure pack (plan → apply with receipts)

• Ward to surface calm “network health” signals (via System Weather)

• Records to package a redaction-aware network incident bundle

Design goals

• Fix common connectivity failures quickly and safely

• Work offline (as much as possible)

• Prefer non-destructive actions and reversible steps

• Produce evidence and receipts suitable for support/help forums

• Cross-distribution best-effort (Ubuntu/Debian/Fedora/Arch first)

What it does (v1 scope)

Diagnostics (no root required where possible):

• Interface status and link state

• DHCP lease and address configuration sanity

• Routing table and default gateway validation

• DNS configuration and resolution checks

• Connectivity tests (ICMP + HTTP/HTTPS where possible)

• Firewall posture inspection (best-effort: nftables/iptables/UFW/firewalld)

• Network manager state (NetworkManager/systemd-networkd where available)

Repairs (root required for most):

• Renew DHCP / reconfigure interface

• Repair default route / gateway

• Repair DNS resolver configuration

• Restart or reconcile NetworkManager/systemd-networkd (guided)

• Flush relevant caches (DNS, manager state) where appropriate

Commands (planned)

The CLI mirrors the AmbientOps “scan/plan/apply” discipline:

nru diagnose
nru plan
sudo nru apply
sudo nru apply --dry-run
nru export --bundle /path/to/incident

You may also provide targeted operations:

nru diagnose dns|iface|route|firewall|manager
sudo nru apply dns|iface|route|manager

Safety guarantees

Network Recovery Unit will never:

• delete user data

• “open ports” without explicit user consent

• disable security controls silently

• make undocumented permanent changes without a receipt

Any mutating action must:

• be represented as a plan first

• declare required privileges

• declare reversibility level

• emit a receipt and evidence pointers

Outputs

Network Recovery Unit produces artifacts aligned with system-tools-contracts:

• Evidence envelope references (diagnostics)

• Procedure plan (steps, previews, risk labels)

• Run bundle (standard folder layout)

• Receipt (human + machine)

Implementation approach (recommended)

• Core: D

  • robust CLI, orchestration, cross-distro detection

• Optional: Rust helpers

  • privileged, safety-critical execution paths (tight sandbox boundaries)

Elixir/BEAM is excellent for coordination layers, but for Linux networking repair it is less suitable than D/Rust because the work is mostly system integration and privileged operations.

Directory layout (proposed)

• src/ — main CLI + orchestration

• modules/diagnostics/ — diagnostic checks

• modules/repairs/ — repair actions (plan/apply)

• schemas/ — local copies/links to relevant contracts

• examples/ — sample bundles and receipts

• docs/ — distro notes, safety notes, troubleshooting

License

AGPL-3.0-or-later.

Roadmap

See ROADMAP.adoc.