Module network 

Native container networking — N1 (loopback) and N2 (veth + bridge).

Architecture

• N1 loopback: bring_up_loopback is called inside the container’s pre_exec closure, after unshare(CLONE_NEWNET), using ioctl(SIOCSIFFLAGS) to set IFF_UP on lo. The kernel then automatically activates 127.0.0.1.

• N2 bridge: setup_bridge_network is called by the parent before fork(). It creates a named network namespace (ip netns add), fully configures it (veth pair, IP, routes, bridge attachment), then returns. The child’s pre_exec joins the named netns via setns().

Why named netns (not /proc/{pid}/ns/net)?

The primary reason is debuggability: named netns are visible via ip netns list and inspectable with ip netns exec pelagos-foo ip addr from the host. Anonymous namespaces via /proc/{pid}/ns/net offer none of that visibility.

There are also two practical problems with /proc/{pid}/ns/net given our current use of std::process::Command, though neither is fundamental:

1. Race with fast exit: if the container runs e.g. exit 0, the child can terminate before the parent opens /proc/{pid}/ns/net. This isn’t truly fatal — a dead container doesn’t need networking — but it does require the parent to handle “PID gone” gracefully rather than treating it as an error.

2. CLOEXEC deadlock: adding a sync pipe so the child blocks in pre_exec while the parent configures networking deadlocks because std::process::Command::spawn() itself blocks on an internal CLOEXEC fail-pipe until exec(). The child can’t exec() while blocked on our pipe, and the parent can’t signal our pipe until spawn() returns. This is a Rust stdlib limitation — a raw fork()/exec() implementation could synchronize freely.

Named netns sidestep both issues (created before fork, no coordination needed) and give us host-side observability for free.

Teardown removes the host-side veth (ip link del) and the named netns (ip netns del).

Structs

Ipv4Net

A compact IPv4 network (address + prefix length), e.g. 10.88.1.0/24.

NetworkConfig

Network configuration for a container.

NetworkDef

Persistent definition of a named network (stored in config dir).

NetworkSetup

Runtime state from setting up bridge networking; needed for teardown.

PastaSetup

Runtime state for a pasta-backed container; holds the pasta process for teardown.

Enums

NetworkMode

PortProto

Container network mode. Protocol for a port-forward mapping.

Constants

BRIDGE_GW

Gateway IP for the default network.

BRIDGE_NAME

Bridge name for the default network.

Functions

attach_network_to_netns

Attach an additional bridge network to an existing named netns.

bootstrap_default_network

Bootstrap or load the default pelagos0 network definition.

bring_up_loopback

Bring up the loopback interface (lo) inside the current network namespace.

ensure_network

Ensure a named network exists, creating it if necessary.

generate_ns_name

Generate a unique name for a container network namespace.

is_pasta_available

Returns true if pasta is on PATH and responds to --version.

load_network_def

Load a network definition by name.

setup_bridge_network

Set up full bridge networking for a container using a named network namespace.

setup_pasta_network

Spawn pasta attached to an already-running container’s network namespace.

teardown_network

Remove the container’s veth pair and named network namespace.

teardown_pasta_network

Kill the pasta relay process and collect its stdout+stderr output for diagnostics.

teardown_secondary_network

Remove a secondary network’s veth pair.