apollo-netd

apollo-netd is a standalone Linux networking reconciler for isolated endpoints. A trusted local orchestrator submits desired endpoint state through a bounded Unix-socket protocol; netd persists that intent, provisions the Linux dataplane, verifies the result, and repairs owned drift.

Responsibilities

• Manage network namespaces, veth pairs, routes, and dual-stack local IPAM.
• Apply endpoint-scoped nftables policy and optional IPv4 masquerade.
• Reserve TCP/UDP host ports and configure endpoint forwarding.
• Apply owned traffic-control limits and report interface counters.
• Persist desired state, leases, ownership, generations, and operation replay.
• Expose a versioned local protocol plus the apollo-netctl client.

Trusted orchestrator / apollo-netctl
                │
                ▼
      authenticated Unix socket
                │
                ▼
       durable reconciler ─────► redb state
                │
                ├──────────────► namespaces / veth / routes
                ├──────────────► nftables policy and NAT
                └──────────────► traffic control and counters

Netd has no control-plane, cloud API, database server, message broker, container runtime, or customer-code execution dependency. Scheduling, workload lifecycle, DNS, TLS, application logs, billing, BGP, service mesh, and Kubernetes CNI are outside its scope.

Build and verify

Rust 1.96 is pinned in rust-toolchain.toml. Linux is required to operate and qualify the daemon.

cargo build --locked --release --bins
scripts/lint.sh

The lint script checks rustfmt and strict Clippy across the main workspace and both fuzz workspaces. In the Apollo Open-Source workspace it also applies the shared source-spacing formatter before checking. The release binaries are target/release/apollo-netd and target/release/apollo-netctl.

Configure and run

Start from examples/config.toml. Configure explicit trusted peer UIDs, non-overlapping address pools, writable state/runtime paths, and optional IPv4 NAT uplinks. The host needs Linux network namespaces, rtnetlink, nftables, traffic control, IPv4/IPv6 forwarding, CAP_NET_ADMIN, and CAP_SYS_ADMIN.

sudo install -m 0755 target/release/apollo-netd target/release/apollo-netctl /usr/bin/
sudo install -d -m 0750 /etc/apollo-netd
sudo install -m 0600 examples/config.toml /etc/apollo-netd/config.toml
sudo install -m 0644 packaging/systemd/apollo-netd.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now apollo-netd.service
sudo apollo-netctl --json doctor
sudo apollo-netctl --json capabilities

The default socket is /run/apollo-netd/netd.sock; durable state defaults to /var/lib/apollo-netd. Review the operations guide before installation, especially the forwarding, socket-access, persistent namespace, and upgrade requirements.

Use the client

The example specification is default-deny and requests automatic IPv4 and IPv6 allocation.

sudo apollo-netctl endpoint plan examples/endpoint.json
sudo apollo-netctl endpoint apply examples/endpoint.json
sudo apollo-netctl endpoint get example-endpoint
sudo apollo-netctl endpoint list

Mutations print an operation ID. Preserve it and pass it back with --operation-id when retrying an uncertain delivery. Generations belong to the caller and fence stale control processes.

Security and documentation

The socket is a privileged local control surface authenticated with Linux peer credentials. Do not expose it to workloads or network proxies. Netd deletes or replaces kernel objects only after proving durable ownership; administrator objects with colliding names fail closed.

• Architecture
• Protocol
• Security model
• Recovery
• Operations
• Integration

Report vulnerabilities privately as described in SECURITY.md.

License

Licensed under the MIT License. The Cargo packages are intentionally marked publish = false; this repository distributes source and binaries, not crates.io packages.