81 lines
4.4 KiB
Markdown
81 lines
4.4 KiB
Markdown
# 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:
|
|
|
|
1. **No Routing Table Flushes**: `nx9-wg` NEVER executes `ip route flush` or flushes kernel routing tables.
|
|
2. **Default Route Protection**: The default gateway (`0.0.0.0/0` via WAN gateway) is NEVER modified, deleted, or overridden.
|
|
3. **Unmanaged Route Protection**: Routes belonging to external interfaces (e.g., `eth0`, `docker0`, `cni0`, `virbr0`) are completely ignored during route reconciliation.
|
|
4. **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.
|
|
|
|
```rust
|
|
// 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.
|