Native Linux Network Engine (`NativeLinuxNetworkEngine`)

The NativeLinuxNetworkEngine provides Linux network interface inspection, IPv4/IPv6 address assignment, kernel routing table synchronization, and IP packet forwarding controls.

1. Architecture & Netlink Communication

All network operations are executed in-process using RTNETLINK (NETLINK_ROUTE family) and direct /proc/sys procfs file writes:

┌────────────────────────────────────────────────────────┐
│              NativeLinuxNetworkEngine                  │
└───────────────┬────────────────────────┬───────────────┘
                │                        │
  Link, Address & Route Management       │ Kernel IP Forwarding Controls
  via RTNETLINK (NETLINK_ROUTE)          │ via direct /proc/sys writes
                │                        │
┌───────────────▼────────────────────────▼───────────────┐
│              Linux Kernel Networking                   │
└────────────────────────────────────────────────────────┘

2. Capabilities & Operations

A. Interface & Address Management

list_interfaces(): Enumerates all host network interfaces, resolving interface index (ifindex), MAC address, operational flags (IFF_UP, IFF_RUNNING, IFF_POINTOPOINT), and interface type.
set_interface_state(name, up): Modifies interface operational state flags (IFF_UP).
add_address(name, cidr) / delete_address(name, cidr): Sends RTM_NEWADDR / RTM_DELADDR Netlink messages to attach IPv4 or IPv6 subnets to interfaces.

B. Kernel Routing Table Synchronization

list_routes(): Queries active kernel routes (RTM_GETROUTE), decoding destination prefixes, gateway addresses, interface names, route metrics, and route protocols.
add_route(route): Installs a routing entry via RTM_NEWROUTE with scope RT_SCOPE_UNIVERSE or RT_SCOPE_LINK, target interface index (RTA_OIF), and route metric (RTA_PRIORITY).
delete_route(route): Removes a managed route via RTM_DELROUTE.
has_route_drift(desired_routes): Compares SQLite desired routes against active kernel routes using exact subnet, gateway, interface, and metric equality.

C. Direct Procfs IP Forwarding

Rather than executing sysctl -w net.ipv4.ip_forward=1, the engine directly inspects and updates procfs files:

IPv4: /proc/sys/net/ipv4/ip_forward
IPv6: /proc/sys/net/ipv6/conf/all/forwarding

3. Strict Resource Ownership Invariants

To guarantee safety on multi-tenant hosts running Docker, Kubernetes, Podman, or libvirt, nx9-wg enforces strict non-interference rules:

No Routing Table Flushes: nx9-wg NEVER executes ip route flush or flushes kernel routing tables.
Default Route Protection: The default gateway (0.0.0.0/0 via WAN gateway) is NEVER modified, deleted, or overridden.
Unmanaged Route Protection: Routes belonging to external interfaces (e.g., eth0, docker0, cni0, virbr0) are completely ignored during route reconciliation.
Scope-Confined Deletion: Only routes explicitly created by nx9-wg or assigned to nx9-wg interfaces are candidates for removal during drift reconciliation.

4. Route Equality & Reconciliation Logic

Two routes are evaluated as equal if and only if all of the following match:

Destination CIDR: Prefix and netmask (e.g., 192.168.50.0/24).
Gateway: Optional next-hop IP address.
Interface: Egress device name (e.g., wg0).
Metric: Route priority integer.

// Deterministic route equality check
if desired_route.destination == live_route.destination
    && desired_route.gateway == live_route.gateway
    && desired_route.interface_name == live_route.interface_name
    && desired_route.metric == live_route.metric
{
    // Route is converged (In Sync)
}

5. Non-Linux Platform Fallback

On macOS and Windows workstations, nx9-wg automatically engages SimulatedNetworkEngine to enable local application development without requiring Linux-specific Netlink sockets.

4.4 KiB Raw Blame History

Native Linux Network Engine (NativeLinuxNetworkEngine)