RedBear-OS/local/docs/NETWORKING-IMPROVEMENT-PLAN.md

# Red Bear OS Networking and TCP/IP Stack Improvement Plan

## Purpose

This document assesses the current network and TCP/IP stack in Red Bear OS for completeness
and quality, cross-references it against the Linux 7.1 reference implementation
(`local/reference/linux-7.1/`) and upstream Redox OS activity (2024–2026), and defines the
next improvement plan in execution order.

This is the **canonical current implementation plan** for the userspace TCP/IP stack
(`netstack` / `smolnetd`), the Ethernet driver family, the POSIX socket surface in relibc,
network configuration (`netcfg`, `dhcpd`, `redbear-netctl`), and the runtime properties of
the scheme-based packet path.

When another document discusses the smolnetd daemon, `scheme:tcp` / `scheme:udp` /
`scheme:icmp` / `scheme:ip` / `scheme:netcfg`, the `driver-network` trait, the Ethernet
driver family (`e1000d`, `ixgbed`, `rtl8139d`, `rtl8168d`, `virtio-netd`), or TCP/IP
performance and protocol coverage, prefer this file for:

- the current robustness judgment,
- the current implementation order,
- the current validation/proof expectations,
- and the current language for build-visible vs runtime-proven vs hardware-validated claims.

It is grounded in the current repository state, especially:

- `local/sources/base/netstack/` (the TCP/IP daemon sources)
- `local/sources/base/drivers/net/` (Ethernet driver family + `driver-network` library)
- `local/sources/base/dhcpd/` (DHCP client)
- `local/sources/relibc/src/header/sys_socket/` and `local/sources/relibc/src/platform/redox/socket.rs`
- `local/sources/libredox/src/lib.rs` (SocketCall enum)
- `local/sources/kernel/src/scheme/{mod,user}.rs` (scheme dispatch)
- `local/recipes/drivers/redbear-iwlwifi/` (Intel Wi-Fi transport)
- `config/redbear-{netctl,wifi-experimental,bluetooth-experimental,mini,full}.toml`

Companion plans that share authority over networking-adjacent surfaces:

- `local/docs/WIFI-IMPLEMENTATION-PLAN.md` — canonical for the Wi-Fi control plane, Intel
  transport, `redbear-iwlwifi`, `linux-kpi` wireless layer, and `redbear-wifictl`.
- `local/docs/IRQ-AND-LOWLEVEL-CONTROLLERS-ENHANCEMENT-PLAN.md` — canonical for the PCI
  interrupt plumbing, MSI/MSI-X delivery, and IOMMU work that NIC drivers depend on.
- `local/docs/BLUETOOTH-IMPLEMENTATION-PLAN.md` — canonical for the Bluetooth stack.

This plan covers the **wired TCP/IP stack and the socket surface**. Where Wi-Fi intersects
with the IP datapath (for example, hooking a Wi-Fi link-layer into the `Router`), the
Wi-Fi plan owns the wireless-specific detail and this plan owns the integration contract.

## Validation States

| State | Meaning |
|---|---|
| **builds** | Compiles in-tree |
| **host-tested** | Tests pass on Linux host with synthesized fixtures |
| **qemu-proven** | Behavior confirmed in QEMU with a virtio-net or e1000 NIC |
| **validated** | Behavior confirmed on real bare-metal hardware with evidence |
| **experimental** | Available for bring-up, not support-promised |
| **missing** | No in-tree implementation |

## Current State

### Architecture at a Glance

Red Bear OS, like upstream Redox, has **zero in-kernel networking**. The kernel provides
only the scheme dispatch surface (`scheme/user.rs` proxies `open`/`read`/`write`/`dup`/
`call` to userspace daemons) and the global `event:` scheme for I/O readiness notification.
All TCP/IP logic lives in the userspace `netstack` daemon, built on **smoltcp 0.12.0**.

```
Application (POSIX socket, libstd TcpStream, curl, ssh, ...)
    │  relibc sys_socket: socket(), connect(), send(), recv(), ...
    │  → open("/scheme/tcp", ...) → dup(fd, "1.2.3.4:80")
    ▼
Kernel scheme router (kernel/src/scheme/user.rs)
    │  forwards scheme calls to the registered daemon via SQE/CQE IPC
    ▼
netstack / smolnetd (local/sources/base/netstack/src/main.rs)
    │  registers: tcp, udp, icmp, ip, netcfg
    │  owns: smoltcp::iface::Interface + SocketSet + Router + DeviceList
    ▼
Router (netstack/src/router/mod.rs) — implements smoltcp::phy::Device
    │  poll(): drains EthernetLink.recv() into rx_buffer
    │  dispatch(): RouteTable longest-prefix lookup → EthernetLink.send()
    ▼
EthernetLink (netstack/src/link/ethernet.rs)
    │  ARP cache (60s TTL), frame encode/decode, neighbor discovery
    │  synchronous read/write of raw Ethernet frames via the network scheme fd
    ▼
Ethernet driver daemon (e1000d, rtl8168d, ixgbed, rtl8139d, virtio-netd)
    │  implements driver-network::NetworkAdapter
    │  exposes scheme:network.<driver>_<bus> with raw frame read/write + /mac
    ▼
Hardware NIC (PCI MMIO + IRQ + DMA rings)
```

### Status Matrix

| Area | State | Detail |
|---|---|---|
| TCP/IP daemon (`netstack`/`smolnetd`) | **builds, qemu-proven** | Single-threaded event loop over `EventQueue`. Owns smoltcp 0.12.0 `Interface` + `SocketSet`. Registers `tcp`, `udp`, `icmp`, `ip`, `netcfg` schemes. Binary aliased as both `netstack` and `smolnetd` for compatibility. |
| smoltcp version | **builds** | 0.12.0 with features: `std`, `medium-ethernet`, `medium-ip`, `proto-ipv4`, `socket-raw`, `socket-icmp`, `socket-udp`, `socket-tcp`, `socket-tcp-cubic`, `iface-max-addr-count-8`. **IPv6 NOT enabled.** |
| TCP congestion control | **builds** | CUBIC only (smoltcp `socket-tcp-cubic` feature). No BBR, no DCTCP, no per-socket selection. |
| TCP feature surface | **partial** | Window scaling, MSS negotiation, RTT estimation, exponential backoff retransmission, keep-alive, Nagle, delayed ACKs (all from smoltcp). **Missing: SACK, TCP timestamps, ECN, TCP Fast Open, MPTCP, urgent pointer.** |
| UDP sockets | **builds, qemu-proven** | `scheme:udp`. Peek-and-filter model for connected UDP. Ephemeral port range 49152–65535. |
| ICMP | **builds** | `scheme:icmp`, root-only. |
| Raw IP | **builds** | `scheme:ip`, root-only. Wraps smoltcp `RawSocket`. |
| ARP | **builds** | Hand-implemented in `link/ethernet.rs`. Request/reply, neighbor cache, 60s TTL, 3 retries with 1s silence. IPv4-only (no NDP for IPv6). |
| Routing | **builds, qemu-proven** | `router/route_table.rs` — longest-prefix-match over a `Vec<Rule>`. Static routes only, configured via `scheme:netcfg/route/{add,del,list}`. No FIB trie, no policy routing, no multipath, no route daemon. |
| Network configuration (`netcfg`) | **builds** | Filesystem-like config scheme: `/resolv/nameserver`, `/route/{list,add,del}`, per-interface `ip`, `mac`, `gateway`. Backed by `BTreeMap` nodes with read/write callbacks. |
| DHCP client (`dhcpd`) | **builds, qemu-proven** | Standalone daemon. Reads/writes `scheme:netcfg` to apply leases. Init service `10_dhcpd.service` runs `dhcpd -f`. |
| Profile orchestration (`redbear-netctl`) | **builds, host-tested** | Arch-netctl-style profiles in `/etc/netctl/`. Wired/wireless, DHCP/static/bounded IP modes. Init service `12_netctl.service` applies the active profile after `smolnetd`+`dhcpd`. |
| DNS resolver | **builds** | In-process inside `netstack` via `dns-parser` crate. `scheme:netcfg/resolv/nameserver` for the recursive resolver address. Quad9 (9.9.9.9) fallback. |
| Ethernet drivers | **builds, qemu-proven** | 5 drivers: `e1000d` (Intel 8254x), `ixgbed` (Intel 10GbE 82599), `rtl8139d`, `rtl8168d` (Realtek), `virtio-netd`. All implement `driver-network::NetworkAdapter`. |
| Driver packet I/O model | **builds** | Synchronous file read/write of raw Ethernet frames. `NetworkAdapter::{read_packet, write_packet}`. IRQ-driven via `scheme:irq/{}` + `EventQueue`. No NAPI, no batched polling, no interrupt mitigation. |
| Wi-Fi IP datapath | **missing** | `redbear-iwlwifi` is control-plane/transport only (see `WIFI-IMPLEMENTATION-PLAN.md`). No 802.11 frame-to-EthernetLink bridge into `netstack`. |
| POSIX socket API (relibc) | **builds, qemu-proven** | `socket()`, `bind()`, `connect()`, `listen()`, `accept()`, `send()`, `recv()`, `sendto()`, `recvfrom()`, `sendmsg()`, `recvmsg()`, `getsockopt()`, `setsockopt()`, `shutdown()`, `socketpair()`, `getsockname()`, `getpeername()`. `AF_INET` and `AF_UNIX` only. **No `AF_INET6`.** |
| Socket multiplexing | **builds, qemu-proven** | Kernel `scheme:event` (analogous to epoll). `EventQueue` in daemons. `O_NONBLOCK` + `EAGAIN`/`EWOULDBLOCK` semantics on sockets. No `epoll_pwait2`, no io_uring equivalent. |
| Bulk FD passing | **partial** | Upstream relibc gained bulk FD passing for `recvmsg`/`sendmsg` in early 2026 (commits `94b0cfc68`, `5e61f17a3`, `1978c1aa4`). **Sync status with our local relibc fork needs verification** — see Upstream Sync. |
| Firewall / packet filtering | **missing** | No netfilter, iptables, nftables, or BPF equivalent. No hooks in the IP path. |
| Connection tracking | **missing** | No conntrack. No NAT. |
| IPv6 | **missing** | smoltcp `proto-ipv6` feature not enabled. `link/ethernet.rs` is IPv4-only (no NDP). relibc socket backend has no `AF_INET6` branch. `route_table.rs` is `IpAddress`-generic but no IPv6 routes are configured. |
| Performance offloads | **missing** | No GRO, no GSO, no TSO, no checksum offload, no zero-copy send/recv, no `MSG_ZEROCOPY`, no `sendfile`, no batched packet submission. |
| Multi-NIC | **partial** | `Router` supports a `DeviceList` and dispatches per-route, but `main.rs:get_network_adapter()` picks the **first** adapter and warns on multiple (FIXME comment). True multi-homing not wired. |
| Virtual network devices | **missing** | No bridge, VLAN, bond, tunnel, VXLAN, tun/tap scheme daemons. |
| Traffic control (qdisc) | **missing** | No shaping, policing, QoS, or scheduling discipline. |
| Network namespaces | **partial** | Scheme namespaces exist (via `setrens`), used by `smolnetd` to enter the null namespace. Not exposed as a general network isolation primitive. |
| Hardware validation (bare metal) | **qemu-proven only** | NIC drivers build and pass QEMU smoke tests. No bare-metal NIC throughput, packet loss, or long-connection validation evidence. |

### Packet Flow Detail (Receive Path)

```
1. NIC raises IRQ → driver's EventQueue wakes
2. Driver::handle_irq() → drains NIC RX ring → packet into driver-side buffer
3. NetworkScheme<T> posts fevent(EVENT_READ) on the network scheme fd
4. smolnetd's EventQueue wakes on EventSource::Network
5. smolnetd::on_network_scheme_event() → EthernetLink.recv(now)
6. EthernetLink reads raw frame via network_file.read(), parses EthernetRepr
7. If IPv4: returns payload to Router.poll() which enqueues into rx_buffer
8. If ARP: processes locally (neighbor cache update, may send reply)
9. smolnetd calls smoltcp Interface.poll(now, &mut Router, &mut SocketSet)
10. smoltcp processes IP/TCP/UDP state machines, fills socket buffers
11. Socket handlers post fevent on tcp/udp scheme fds → applications wake
12. Application calls read(fd) → kernel forwards to TcpScheme::read_buf()
13. TcpScheme::read_buf() → smoltcp TcpSocket::recv_slice()
```

### Packet Flow Detail (Transmit Path)

```
1. Application calls write(fd, data) → kernel forwards to TcpScheme::write_buf()
2. TcpScheme::write_buf() → smoltcp TcpSocket::send_slice()
3. smolnetd event loop calls smoltcp Interface.poll(now, &mut Router, &mut SocketSet)
4. smoltcp decides to transmit → Router.transmit(now) returns TxToken
5. smoltcp builds IP packet into TxToken buffer → Router.tx_buffer.enqueue()
6. smolnetd calls Router.dispatch(now)
7. Router.dispatch() parses Ipv4Packet, looks up RouteTable rule
8. If source address mismatch: rewrites src + refills checksum
9. Calls EthernetLink.send(next_hop, packet, now)
10. EthernetLink.send(): ARP neighbor cache lookup
    - Hit: builds Ethernet frame, writes to network_file
    - Miss: enqueues into waiting_packets, sends ARP request
11. Driver receives write() on network scheme → pushes to NIC TX ring → DMA → wire
```

## Gap Analysis vs Linux 7.1

Linux 7.1 (`local/reference/linux-7.1/`) is the reference for production-grade networking.
The table below maps every major Linux networking subsystem to its Red Bear equivalent and
identifies the gap.

| Linux 7.1 Subsystem | Linux Location | Red Bear Equivalent | Gap Severity |
|---|---|---|---|
| **In-kernel TCP/IP** | `net/ipv4/`, `net/ipv6/` (~80k LoC) | Userspace `netstack` daemon (smoltcp) | Architectural difference, not a gap per se. Microkernel design. |
| **`sk_buff` packet metadata** | `include/linux/skbuff.h` (5,462 LoC) | Raw `[u8]` buffers, no metadata struct | **High** — no zero-copy across layers, no per-packet metadata propagation. |
| **NAPI (interrupt→poll)** | `include/linux/netdevice.h:381`, `napi_schedule()` | IRQ-per-packet + `EventQueue` wake | **High** — interrupt storm risk under load. No batched polling. |
| **GRO / GSO / TSO** | `net/core/gro.c`, `net/core/gso.c`, NIC driver offload | None | **High** — every packet traverses the full stack individually. |
| **BIG TCP (512KB GSO/GRO)** | `net/ipv6/ip6_output.c`, `net/ipv4/ip_output.c` | None | Medium — relevant only at 100GbE+, not near-term. |
| **Pluggable congestion control** | `include/net/tcp.h:1325` `struct tcp_congestion_ops`, `net/ipv4/tcp_cubic.c`, `tcp_bbr.c`, `tcp_dctcp.c` | smoltcp `socket-tcp-cubic` feature (CUBIC only) | **High** — no BBR for WAN throughput, no DCTCP for datacenter, no per-socket selection. |
| **SACK (Selective ACK)** | `net/ipv4/tcp_input.c` | Not in smoltcp | Medium — hurts lossy links. |
| **TCP timestamps** | `net/ipv4/tcp_output.c` | Not in smoltcp | Low — RTT estimation works without them but less precisely. |
| **ECN (Explicit Congestion Notification)** | `net/ipv4/tcp_input.c` | Not in smoltcp | Medium — datacenter relevance. |
| **MSG_ZEROCOPY send** | `net/ipv4/tcp.c:1140-1326`, `net/core/skbuff.c:1719-1806` | None | **High** — every send copies user→kernel→daemon. |
| **sendfile / splice** | `net/core/skbuff.c:3257` `skb_splice_bits()` | None | Medium — relevant for static file servers. |
| **io_uring zero-copy receive** | `io_uring/zcrx.c`, `IORING_OP_RECV_ZC` (`include/uapi/linux/io_uring.h:314`) | None | Low (long-term) — Linux 7.x reaches 187 Gbps with this; not near-term for Red Bear. |
| **epoll** | `fs/eventpoll.c` (~3,000 LoC), `ep_poll_callback()` | Kernel `scheme:event` + `EventQueue` | Medium — functionally equivalent but less optimized; no ready-list integration with socket wakeup path. |
| **XDP / AF_XDP** | `net/xdp/xsk.c`, BPF programs in driver context | None | Low (long-term) — line-rate BPF filtering. |
| **eBPF everywhere** | `net/core/filter.c`, `bpf_tcp_ca.c`, XDP, TC, socket filter | None | Medium — no programmable packet processing. |
| **Netfilter (5 hooks)** | `include/uapi/linux/netfilter.h:43`, `struct nf_hook_ops` | None | **High** — no firewall, no NAT, no packet interception layer. |
| **Conntrack** | `net/netfilter/nf_conntrack_core.c` (2,790 LoC), `struct nf_conn` | None | **High** — no stateful firewall, no NAT. |
| **nftables / iptables** | `net/netfilter/nf_tables_api.c`, `xt_*.c` | None | High — no user-facing firewall CLI. |
| **FIB (LC-trie routing)** | `include/net/ip_fib.h`, `net/ipv4/fib_trie.c`, `fib_semantics.c` | `router/route_table.rs` — `Vec<Rule>` linear scan | Medium — fine for tens of routes; inadequate for full BGP table. |
| **Policy routing / multipath** | `net/ipv4/fib_rules.c`, `fib_select_multipath()` | None | Low — niche outside routers. |
| **IPv6 (full stack)** | `net/ipv6/` (40+ .c files), built-in only in 7.1 | Not enabled (smoltcp `proto-ipv6` off, no NDP, no `AF_INET6`) | **Critical** — IPv6 is mandatory for modern networking. |
| **cfg80211 / mac80211 / nl80211** | `include/net/cfg80211.h` (10,995 LoC), `net/mac80211/` (60+ files), `include/uapi/linux/nl80211.h` | `linux-kpi` wireless shim (Rust), `redbear-iwlwifi` transport (C), `redbear-wifictl` scheme | See `WIFI-IMPLEMENTATION-PLAN.md`. **Control-plane only; no IP datapath bridge yet.** |
| **`net_device` + `net_device_ops`** | `include/linux/netdevice.h:2139` (5,737 LoC), ~50 ops | `driver-network::NetworkAdapter` trait (4 methods) | **High** — no features negotiation, no offload reporting, no statistics, no queue selection. |
| **Multi-queue / RSS / RPS / RFS / XPS** | `net/core/dev.c`, per-CPU queues | None | Medium — relevant for >1Gbps. |
| **`page_pool` memory recycling** | `net/core/page_pool.c` | None | Medium — allocator overhead on RX. |
| **Cacheline-aware structs** | `include/linux/netdevice.h` `_cacheline_group` annotations | None | Low — micro-optimization. |
| **Network namespaces** | 67 namespace-aware subdirs under `net/` | Scheme namespaces (partial) | Medium — relevant for container story. |
| **Bridge / VLAN / bond / tunnel** | `net/bridge/`, `net/8021q/`, `net/bonding/`, `net/ipv4/ip_tunnel.c` | None | Medium — virtualization/networking appliance relevance. |
| **Traffic control (qdisc)** | `net/sched/` (100+ files), `include/net/sch_generic.h` | None | Low — QoS is niche for a desktop OS. |
| **MPTCP** | `net/mptcp/` | Not in smoltcp | Low — niche. |
| **Hardware offloads (checksum, TSO, LRO, TLS, IPsec)** | NIC driver `features`, `include/linux/netdevice.h` NETIF_F_* | None | Medium — drivers don't even advertise capabilities. |
| **Routing daemons (BGP/OSPF/RIP)** | Userspace (FRRouting, bird) | None | Low — not a kernel/daemon gap. |
| **Drop reasons / observability** | `include/net/dropreason.h`, `skb->drop_reason` | Logging only | Low — debugging aid. |

### Severity Summary

- **Critical (blocks modern use):** IPv6, firewall/NAT (netfilter equivalent).
- **High (major performance or functionality gap):** `sk_buff`-equivalent metadata, NAPI-style polling, GRO/GSO/TSO, MSG_ZEROCOPY, pluggable congestion control, multi-NIC.
- **Medium (matters for specific workloads):** SACK, ECN, FIB scaling, multi-queue, virtual devices, observability.
- **Low (long-tail polish):** TCP timestamps, policy routing, MPTCP, io_uring ZC, qdisc.

## Upstream Redox Sync Opportunities (2024–2026)

Red Bear OS is forked from a frozen Redox snapshot. Upstream Redox has been actively evolving
its networking stack. The following upstream commits should be evaluated for import into the
Red Bear local forks. **Per the Golden Rule (Red Bear adapts to upstream, never the reverse),
these are imports to track and apply, not workarounds.**

### Already in Red Bear (verified)

- ✅ smoltcp 0.12.0 with `socket-tcp-cubic` (upstream `b92be2e7d`, `d7c128684`, 2025-03-09)
- ✅ Named network adapters via `scheme:network.<driver>_<bus>` (upstream `f9b3170f0`, 2024-02-28)
- ✅ `netstack` merged into `base` recipe (upstream `c06e5b14e`, 2025-03-10)
- ✅ MAC address fetched from network scheme (upstream `674f5b6d7`, 2024-02-28)
- ✅ `dhcpd` moved into `base` (upstream `b68e5a685`, 2026-04-11)
- ✅ New scheme format, no legacy paths (upstream `bafdb3b66`, 2024-07-11)

### To Evaluate for Import

| Upstream Commit | Date | Description | Red Bear Action |
|---|---|---|---|
| `redox-os/drivers@ad9305bf9` | 2024-02-28 | Unified network drivers under `net/` with shared scheme | Verify our driver layout matches. |
| `redox-os/drivers@921c6b07f` | 2024-12-26 | `driver-network` migrated to `redox-scheme` crate | **Import** — modernizes the scheme protocol. |
| `redox-os/drivers@0f24975ff` | 2025-11-29 | PCI interrupts rework: dedup vector handling for RTL drivers | **Import** — IRQ quality (see IRQ plan). |
| `redox-os/drivers@dd41c4f13` | 2025-11-23 | Net: scheme created and daemon ready before device init | **Import** — fixes race on early opens. |
| `redox-os/drivers@407533201` | 2025-09-24 | Add ThinkPad T60 ethernet to `e1000d` PCI IDs | **Import** — broader hardware. |
| `redox-os/relibc@94b0cfc68` | 2026-02-08 | Reimplement `recvmsg`/`sendmsg` using bulk FD passing | **Verify + import** — check our relibc fork has this; critical for `SCM_RIGHTS`. |
| `redox-os/relibc@5e61f17a3` | 2026-02-08 | `MSG_CMSG_CLOEXEC` handling in `recvmsg` | **Import** alongside the above. |
| `redox-os/relibc@1978c1aa4` | 2026-03-25 | Full `recvmsg` implementation | **Import**. |
| `redox-os/relibc@cab002146` | 2026-02-28 | Move protocols into `libredox` | **Major refactor — evaluate carefully.** Affects SocketCall enum location. |
| `redox-os/relibc@443145fde` | 2025-11-07 | Use `recvmsg`/`sendmsg` when `recvfrom`/`sendto` has flags | **Import**. |
| `redox-os/relibc@9eaa9e82b` | 2025-11-08 | Pass through all `SOL_SOCKET` options, fix `getsockopt` option_len | **Import** — fixes option handling bugs. |
| `redox-os/relibc@6a455159a` | 2026-01-22 | Fix `getaddrinfo` infinite loop hang | **Critical import** — known crash. |
| `redox-os/relibc@726a0fb1a` | 2025-09-15 | `getaddrinfo` NULL nodename, `AI_PASSIVE`, `AI_NUMERICHOST` | **Import**. |
| `redox-os/relibc@5334455a2` | 2025-08-20 | `getnameinfo` + `getaddrinfo` loopback | **Import**. |
| `redox-os/relibc@d44010170` | 2025-07-18 | UDS `bind`/`connect` with RedoxFS integration | **Import** — fixes Unix domain sockets. |
| `redox-os/relibc@6dd10a1f1` | 2025-08-01 | Fix `connect` on Redox | **Import**. |
| `redox-os/relibc@9c6701802` | 2026-01-07 | Add `sys_socket` tests | **Import** — regression coverage. |
| `redox-os/syscall@7a1409a91` | 2026-05-27 | Multiple FDs variant for `call` and `std_fs_call` | **Import** — enables bulk FD passing. |
| `redox-os/syscall@178461f6f` | 2025-12-27 | Remove remnants of old packet format | **Import** — cleanup. |
| `redox-os/kernel@c089667ad` | 2025-12-13 | Remove legacy packet user schemes | **Import** — kernel side of the above. |
| `redox-os/kernel@6c3d5d28c` | 2026-07-01 | Move FD allocation logic into userspace | **Major refactor — evaluate carefully.** Most recent kernel change. |
| `redox-os/kernel@08ea1da2f` | 2025-07-05 | Trigger read event for user schemes on fd close | **Import** — fixes socket cleanup races. |
| `redox-os/kernel@4ff82ad8b` | 2025-11-27 | Fix user scheme deadlocks in `call_extended_inner` | **Critical import** — fixes hangs under load. |
| `redox-os/kernel@99ff55ee1` | 2026-02-08 | Demux results as soon as received from user scheme | **Import** — latency improvement. |
| `redox-os/redox@85b62fd85` | 2026-03-01 | Support networking in all configs | **Reference** — verify our configs cover networking in all targets. |
| `redox-os/redox@193e81897` | 2026-02-17 | ~115 WIP networking recipes (HTTP, FTP, SSH, VPN, P2P) | **Cherry-pick** — many of these are now relevant for `cub`. |
| `redox-os/netutils@6df5af955` | 2024-11-27 | Basic `ifconfig` command | **Reference** — `redbear-netstat` covers this, but compare APIs. |
| `redox-os/netutils@62f96a4b5` | 2026-05-22 | Fix `nc` listener exiting on stdin EOF | **Import if we ship nc.** |

### Upstream Gaps Red Bear Fills Independently

These exist in Red Bear but **not** in upstream Redox:

- Wi-Fi driver support (`redbear-iwlwifi`, `linux-kpi` wireless layer, `redbear-wifictl`)
- `redbear-netctl` profile orchestration (Arch netctl-style)
- `redbear-netstat`, `redbear-mtr`, `redbear-nmap`, `redbear-traceroute`
- AMD GPU networking offload path (via `redox-drm`)

## Improvement Plan

The plan is organized into six phases. Each phase has a clear success criterion, dependencies,
and validation target. Phases are ordered by **dependency** (early phases unblock later ones)
and by **impact** (critical gaps first).

### Phase 0: Upstream Sync and Foundation Hardening

**Goal:** Bring the Red Bear local forks to current upstream networking state before adding
new features. This avoids building on stale foundations.

**Duration:** 2–3 weeks.

**Workstreams:**

0.1 **relibc socket fixes.** Apply the upstream commits listed in "To Evaluate for Import"
   that touch relibc's `sys_socket`, `getaddrinfo`, `getnameinfo`, `recvmsg`/`sendmsg`,
   `connect`, `bind`, and `SOL_SOCKET` option pass-through. **Priority: the `getaddrinfo`
   infinite loop fix (`6a455159a`).** Verify against the `sys_socket` test suite.

0.2 **Kernel scheme dispatch fixes.** Apply `4ff82ad8b` (deadlock fix), `08ea1da2f`
   (close event), `99ff55ee1` (latency). These are direct kernel-fork patches.

0.3 **Driver-side modernization.** Apply `921c6b07f` (`driver-network` → `redox-scheme`),
   `dd41c4f13` (scheme-before-device-init race fix), `0f24975ff` (PCI interrupts rework).
   Test each driver in QEMU after applying.

0.4 **Config audit.** Verify all `redbear-*.toml` targets that should have networking
   actually pull in `redbear-netctl`, `smolnetd`, `dhcpd`, and a NIC driver. Reference
   upstream `85b62fd85`.

0.5 **Bulk FD passing verification.** Check whether the local relibc fork already has
   commits `94b0cfc68` and `1978c1aa4`. If not, import them. Validate `SCM_RIGHTS`
   works end-to-end with a test daemon.

**Success Criteria:**
- All listed upstream commits either applied or documented as "intentionally skipped" with
  a reason.
- `redbear-mini` boots in QEMU, acquires DHCP, and `curl http://example.com/` succeeds.
- `redbear-netstat` shows the TCP connection in `ESTABLISHED` state.
- `sys_socket` tests pass on the relibc fork.

**Validation target:** qemu-proven.

---

### Phase 1: Multi-NIC and Driver Feature Surface

**Goal:** Remove the single-NIC FIXME and give the stack visibility into driver capabilities.

**Duration:** 3–4 weeks.

**Dependencies:** Phase 0 complete.

**Workstreams:**

1.1 **Multi-NIC in `netstack`.** Replace `get_network_adapter()` (which picks the first NIC
   and warns) with proper multi-interface support. The `Router` already has a `DeviceList`;
   the gap is in `main.rs` initialization and in `EthernetLink` instantiation per adapter.
   Reference Linux's `net_device` list semantics. Each NIC gets its own `EthernetLink` in
   the `DeviceList`, with its own ARP cache and MAC.

1.2 **`NetworkAdapter` trait expansion.** The current trait is 4 methods:
   ```rust
   pub trait NetworkAdapter {
       fn mac_address(&mut self) -> [u8; 6];
       fn available_for_read(&mut self) -> usize;
       fn read_packet(&mut self, buf: &mut [u8]) -> Result<Option<usize>>;
       fn write_packet(&mut self, buf: &[u8]) -> Result<usize>;
   }
   ```
   Expand to expose capabilities and statistics, modeled on Linux's
   `struct net_device_ops` and `ethtool_ops`:
   ```rust
   pub trait NetworkAdapter {
       fn mac_address(&mut self) -> [u8; 6];
       fn available_for_read(&mut self) -> usize;
       fn read_packet(&mut self, buf: &mut [u8]) -> Result<Option<usize>>;
       fn write_packet(&mut self, buf: &[u8]) -> Result<usize>;

       // New: capability negotiation
       fn capabilities(&self) -> NicCapabilities;       // MTU, offloads, max queues
       fn mtu(&self) -> usize { 1500 }
       fn link_state(&self) -> LinkState;               // Up / Down / Unknown
       fn statistics(&self) -> NicStatistics;           // rx/tx bytes, packets, errors, drops
   }
   ```
   Wire `NicCapabilities` into `netstack` so `Router` knows the real MTU (currently
   hardcoded to 1486 in `router/mod.rs:42`).

1.3 **`scheme:netcfg` interface enumeration.** Expose `netcfg/ifaces` listing all
   `DeviceList` entries with their MAC, IP, link state, statistics, and MTU. This gives
   `redbear-netstat` and `redbear-netctl` a proper interface table.

1.4 **Per-driver statistics.** Each driver (`e1000d`, `rtl8168d`, etc.) should expose
   RX/TX byte/packet/error counters through the new `statistics()` method. Reference
   Linux's `ndo_get_stats64`.

**Success Criteria:**
- `redbear-netstat -i` lists all NICs present (in QEMU: just `virtio-net` or `e1000`; on
  bare metal: all detected NICs).
- A second NIC can be brought up with a static IP via `redbear-netctl` and routes traffic.
- `Router::MTU` is no longer a hardcoded constant — it derives from the active NIC's
  reported MTU.
- Driver statistics are non-zero after a ping flood.

**Validation target:** qemu-proven for multi-NIC (two virtio-net interfaces); host-tested
for the trait expansion (unit tests on the new trait).

---

### Phase 2: IPv6

**Goal:** Bring the stack to modern IP standards. IPv6 is no longer optional for a
general-purpose OS.

**Duration:** 4–6 weeks.

**Dependencies:** Phase 1.1 (multi-NIC) helpful but not strictly required. Phase 0
(relibc freshness) required.

**Workstreams:**

2.1 **Enable smoltcp IPv6.** In `netstack/Cargo.toml`, add `"proto-ipv6"` to the smoltcp
   features list. Audit the build for new warnings/errors — smoltcp's IPv6 surface is
   large. Reference: smoltcp `wire` module already has full IPv6 parsing.

2.2 **`link/ethernet.rs` IPv6 support.** Currently the link layer is IPv4-only: the ARP
   cache uses `Ipv4Address`, `process_arp` only handles `ArpRepr::EthernetIpv4`, and
   `send_to` only handles `IpAddress::Ipv4`. Add NDP (Neighbor Discovery Protocol,
   RFC 4861) for IPv6 neighbor discovery, mirroring the ARP logic. Use smoltcp's
   `wire::{Icmpv6Repr, Icmpv6Packet, NdiscRepr}` types.

2.3 **`router/route_table.rs` IPv6.** The `Rule` struct already uses `IpCidr` and
   `IpAddress`, which are version-generic. The gap is in `dispatch()` (which only does
   `Ipv4Packet::new_checked`) and in `set_src_addr` checksum refill. Add an IPv6 branch.
   IPv6 has no header checksum (unlike IPv4), so the checksum logic is simpler — only
   transport-layer pseudo-header checksums need attention.

2.4 **relibc `AF_INET6`.** In `local/sources/relibc/src/platform/redox/socket.rs`, add a
   branch for `AF_INET6` that opens `/scheme/tcp` and `/scheme/udp` with IPv6-encoded
   addresses. The scheme path encoding `dup(fd, "[2001:db8::1]:443")` should work once
   `netstack` parses IPv6 endpoints (smoltcp's `parse_endpoint` already does).

2.5 **`netcfg` IPv6 surfaces.** Add `netcfg/resolv/nameserver6`, per-interface IPv6
   address configuration, and IPv6 route add/del. Reference: Linux `addrconf.c`
   (SLAAC) and `ndisc.c` (router advertisements).

2.6 **DHCPv6.** Either extend `dhcpd` or add a sibling `dhcpv6d` daemon. DHCPv6 (RFC 8415)
   is a separate protocol from DHCPv4 — UDP port 546 (client) / 547 (server), different
   message format. Alternatively, implement SLAAC (RFC 4862) as the default IPv6
   autoconfiguration method.

2.7 **`redbear-netctl` IPv6 profiles.** Extend the profile format to support `IP6=dhcp`,
   `IP6=slaac`, `IP6=static`, `Address6=`, `Gateway6=`, `DNS6=`.

2.8 **Validation.** Boot `redbear-mini` in QEMU with `qemu-system-x86_64 ... -netdev
   user,id=n0,ipv6=on -device virtio-net,netdev=n0`. Verify `ping6 ::1`, `curl -6
   https://ipv6.google.com`, and a dual-stack SSH connection.

**Success Criteria:**
- `socket(AF_INET6, SOCK_STREAM, 0)` returns a valid fd.
- `ping6 <router-advertised-address>` succeeds.
- A dual-stack TCP server accepts both IPv4 and IPv6 connections.
- `redbear-netstat -r` shows both IPv4 and IPv6 routes.

**Validation target:** qemu-proven for basic IPv6; host-tested for NDP and DHCPv6
protocol correctness.

**Risk:** This is the largest single workstream. The `link/ethernet.rs` IPv6 work is
non-trivial because NDP is more complex than ARP (solicitation-node multicast, router
discovery, prefix information options). Consider implementing NDP as a separate
`link/ndp.rs` module rather than complicating `ethernet.rs`.

---

### Phase 3: TCP Performance and Congestion Control

**Goal:** Bring TCP throughput and latency into the same order of magnitude as Linux for
common workloads.

**Duration:** 6–8 weeks.

**Dependencies:** Phase 1 (capabilities surface) for any hardware offload wiring.

**Workstreams:**

3.1 **Buffer pool audit.** `netstack/src/buffer_pool.rs` exists but its usage should be
   audited. TCP socket buffers are currently `vec![0; 0xffff]` (64KB) per socket in
   `scheme/tcp.rs:80-83`. For high-bandwidth connections, this is a throughput cap.
   Make the buffer size configurable via `setsockopt(SO_SNDBUF/SO_RCVBUF)` (the scheme
   already has stubs at `tcp.rs:14-15` but `set_setting` returns `Ok(0)`). Reference
   Linux's `tcp_rmem`/`tcp_wmem` sysctl defaults.

3.2 **Pluggable congestion control interface.** smoltcp 0.12 has `socket-tcp-cubic` as a
   feature flag but no runtime selection. Two options:
   
   **Option A (recommended):** Add `setsockopt(TCP_CONGESTION, "cubic")` support to the
   TCP scheme, backed by a `congestion_control` field on `SocketFile`. Since smoltcp
   compiles CC at build time via features, this requires either (a) compiling both
   Reno and CUBIC and switching at runtime (if smoltcp supports it), or (b) forking
   smoltcp to expose a `CongestionController` trait object. Check whether smoltcp 0.12's
   `socket-tcp-cubic` is additive to the default Reno controller.
   
   **Option B:** Contribute a BBR-style controller upstream to smoltcp and enable it
   via a Red Bear patch. This is higher-effort but higher-impact.

3.3 **SACK (Selective Acknowledgment).** smoltcp does not implement SACK (RFC 2018).
   On lossy links (wireless, WAN), SACK dramatically improves throughput by allowing the
   receiver to acknowledge non-contiguous blocks. This requires either (a) upstreaming
   SACK to smoltcp, or (b) carrying a Red Bear patch against smoltcp. Given the Golden
   Rule (prefer upstream), the path is: contribute to smoltcp, carry a local patch
   until merged. Reference: Linux `net/ipv4/tcp_sack.c`.

3.4 **Receive batching (NAPI-equivalent).** The current receive path processes one packet
   per `EventSource::Network` event. Under load, this means one scheme-IPC round-trip
   per packet. Add a drain loop in `on_network_scheme_event()` that reads packets until
   `available_for_read()` returns 0 (or a budget cap). This mirrors Linux's NAPI
   `budget` parameter. Reference: Linux `napi_complete_done()` and the `budget` pattern
   in `include/linux/netdevice.h`.

3.5 **Transmit batching.** Similarly, `Router::dispatch()` already drains `tx_buffer`
   in a loop, but each `dev.send()` is a synchronous write to the network scheme fd.
   Batch multiple frames into a single write if the driver supports it (requires the
   `capabilities()` expansion from Phase 1.2).

3.6 **`MSG_ZEROCOPY` investigation.** True zero-copy requires shared memory between the
   application and `netstack`. This is architecturally significant in a microkernel —
   it means the scheme IPC must support passing buffer references, not just data copies.
   This is a research workstream: evaluate whether the kernel's `scheme:memory` can be
   used to establish a shared ring buffer between an application and `netstack`.
   Reference: Linux `msg_zerocopy_alloc()` and the `ubuf_info` mechanism, and the
   Redox "ring buffers" NLnet-funded project mentioned in the Development Priorities
   2025/26 document. **Do not implement in this phase — produce a design doc.**

**Success Criteria:**
- `iperf3` (port the recipe) between two QEMU VMs shows ≥100 Mbps on virtio-net
  (current baseline unknown — establish it first).
- `setsockopt(SO_RCVBUF, ...)` affects the actual receive buffer size (verify with
  `getsockopt`).
- SACK enabled connections recover from induced packet loss (use `tc netem` in a
  Linux-to-RedBear bridge, or a QEMU packet loss model).
- A design doc for zero-copy exists at `local/docs/NETWORK-ZEROCOPY-DESIGN.md`.

**Validation target:** qemu-proven for throughput and buffer sizing; host-tested for
SACK protocol correctness.

---

### Phase 4: Firewall and Packet Filtering

**Goal:** Provide a firewall and NAT capability, respecting the microkernel
everything-is-a-scheme design.

**Duration:** 6–10 weeks.

**Dependencies:** Phase 1 (interface awareness). Phase 2 (IPv6) for dual-stack filtering.

**Workstreams:**

4.1 **Architecture decision.** In Linux, netfilter hooks live inside the kernel IP path.
   In Red Bear, the IP path is in `netstack`'s `Router` and `EthernetLink`. The
   microkernel-aligned approach is to add **filter hooks in `netstack`'s `Router`**
   that consult a `scheme:firewall` (or `scheme:nf`) daemon. This keeps policy in
   userspace and matches Redox's design philosophy. Two designs to evaluate:

   **Design A (in-process):** Add a `FirewallEngine` inside `netstack` that reads rules
   from `scheme:netcfg/firewall/{rules,chains}`. Simpler, faster (no IPC per packet),
   but couples policy to the stack daemon.

   **Design B (out-of-process):** `netstack` calls out to a `firewalld` daemon via
   scheme IPC for each packet. Cleaner separation but adds latency per packet.
   Mitigated by a rule cache in `netstack` with invalidation via fevent.

   **Recommendation:** Design A for the hot path (rule lookup), with rules managed by a
   separate `scheme:firewall` daemon that writes to `netcfg/firewall/*`. This matches
   how `route` and `resolv` already work (config via `netcfg`, enforced in `netstack`).

4.2 **Hook points.** Define 5 hook points mirroring Linux netfilter, adapted to the
   `Router`/`EthernetLink` boundary:
   - `PRE_ROUTING` — after `EthernetLink::recv()`, before `Router` enqueue.
   - `LOCAL_IN` — after `Router` decides packet is for this host.
   - `FORWARD` — after `Router` decides packet is to be forwarded (requires IP forwarding
     support, currently missing — see Phase 6).
   - `LOCAL_OUT` — after `Router::dispatch()` dequeues, before `EthernetLink::send()`.
   - `POST_ROUTING` — just before `EthernetLink::send()`.

4.3 **Rule format.** Define a TOML or filesystem-based rule format under
   `netcfg/firewall/`. Example:
   ```toml
   # /etc/firewall/rules.toml (or via scheme:netcfg/firewall/rules)
   [[chain]]
   name = "input"
   [[chain.rule]]
   action = "accept"
   proto = "tcp"
   dest_port = 22
   source = "192.168.0.0/16"
   [[chain.rule]]
   action = "drop"
   proto = "tcp"
   dest_port = 22
   ```

4.4 **Connection tracking (conntrack).** For stateful rules (`ACCEPT ESTABLISHED,
   RELATED`), implement a connection tracker inside `netstack` (or a separate daemon).
   Track `(src_ip, src_port, dst_ip, dst_port, proto, state)` tuples with timeouts.
   Reference: Linux `struct nf_conn` (`include/net/netfilter/nf_conntrack.h:74`).

4.5 **NAT.** Build on conntrack. Source NAT (masquerade) rewrites `src_addr` in
   `Router::dispatch()` and records the mapping in conntrack. Destination NAT (port
   forwarding) rewrites `dst_addr` in `PRE_ROUTING`. This requires the checksum refill
   logic that already exists for IPv4 src rewrites — extend it to handle dst rewrites
   and (eventually) port rewrites in the transport pseudo-header.

4.6 **`redbear-firewall` CLI.** A `redbear-firewall` tool (or extend `redbear-netctl`)
   that reads/writes `scheme:netcfg/firewall/*` and provides `iptables`-like or
   `nft`-like ergonomics. Reference: Linux `iptables(8)` and `nft(8)`.

4.7 **Validation.** Tests: (a) drop all inbound TCP except 22, verify only SSH connects;
   (b) masquerade a Red Bear VM behind another Red Bear VM's NAT, verify outbound
   connections work and inbound connections to the inner VM fail without port forward;
   (c) port-forward 8080 to an inner VM's 80, verify a curl to the gateway:8080 reaches
   the inner VM.

**Success Criteria:**
- A basic ruleset (accept loopback, accept established, accept SSH, drop rest) can be
  loaded via `redbear-firewall` and is enforced.
- SNAT masquerade works for outbound traffic from a NAT'd subnet.
- DNAT port-forwarding works for at least one TCP port.
- `redbear-netstat -t` shows conntrack entries for active connections.

**Validation target:** qemu-proven for all three test scenarios; host-tested for
conntrack state machine correctness.

---

### Phase 5: Driver Coverage and Hardware Validation

**Goal:** Expand the Ethernet driver family to cover common bare-metal hardware and
validate the stack on real NICs.

**Duration:** Ongoing (parallel with Phases 2–4).

**Dependencies:** Phase 0 (driver modernization). Phase 1 (capabilities surface).

**Workstreams:**

5.1 **Import upstream `alxd`.** Upstream Redox has an `alxd` driver (Atheros L2 Fast
   Ethernet) that Red Bear does not. Import it. Reference: `redox-os/drivers/net/alxd/`.

5.2 **Common consumer NIC coverage.** The current family misses several common consumer
   chipsets. Prioritize by deployment frequency:
   - **`igb` / `igc`** (Intel I219/I225 on modern laptops — NUC, ThinkPad, Dell) —
     **High priority.** The `e1000d` PCI ID list (`10ec:1004, 100e, 100f, 109a, 1503`)
     does not cover the I219/I225 (PCI IDs `8086:15d8`, `8086:15f2`, etc.). Either
     extend `e1000d` or add a new `igbd` driver.
   - **`r8125`** (Realtek 2.5GbE on modern motherboards) — Medium priority.
     `rtl8168d` covers 8168/8169 but not 8125 (`10ec:8125`).
   - **`e1000e`** (Intel I219/I218 Gigabit) — the PCI IDs `8086:1502, 1503, 1559`
     overlap with `e1000d` but the register interface differs. Verify coverage.

5.3 **Bare-metal validation harness.** Establish a bare-metal test bench with:
   - An Intel NIC (e1000 or igb) and a Realtek NIC (rtl8168) on the same machine.
   - A Linux host on the other end of the link for `iperf3`, `tcpdump`, and packet
     injection.
   - Test matrix: boot, DHCP acquire, ping, iperf3 TCP throughput, iperf3 UDP packet
     loss, long-running TCP connection (1 hour), rapid connection churn (1000
     connects/sec).

5.4 **Wi-Fi IP datapath bridge.** Once `redbear-iwlwifi` reaches runtime validation
   (per `WIFI-IMPLEMENTATION-PLAN.md`), add the datapath bridge: a Wi-Fi link-layer
   adapter that implements `driver-network::NetworkAdapter` and feeds 802.11 frames
   (after 802.11-to-Ethernet header conversion) into `netstack`'s `DeviceList`. This
   makes Wi-Fi a first-class `Router` device. Coordinate with the Wi-Fi plan.

**Success Criteria:**
- `alxd` builds and is packaged.
- At least one modern Intel NIC (I219 or I225) is supported and validated.
- Bare-metal iperf3 throughput is documented for at least one NIC.
- (Stretch) Wi-Fi TCP connection works end-to-end through `netstack`.

**Validation target:** validated for at least one bare-metal NIC.

---

### Phase 6: Forwarding, Virtual Devices, and Advanced Features

**Goal:** Bring the stack to feature parity with a general-purpose Linux networking
appliance for the features that matter.

**Duration:** 8–16 weeks (parallel, long-term).

**Dependencies:** Phases 2 (IPv6), 4 (firewall/conntrack for NAT foundation).

**Workstreams:**

6.1 **IP forwarding.** When `netstack` receives a packet whose destination is not a local
   IP, it currently drops it (no `FORWARD` hook in the `Router`). Add a forwarding path:
   look up the destination in the route table, and if the next-hop is via a different
   interface than the ingress interface, re-queue the packet for that interface. Decrement
   the IPv4 TTL (or IPv6 Hop Limit) and drop at 0. Reference: Linux `ip_forward()` in
   `net/ipv4/ip_forward.c`. Gate behind a `netcfg/forwarding` enable flag.

6.2 **Bridge scheme daemon.** A `bridged` userspace daemon that implements an L2 learning
   bridge (MAC learning table, STP optionally). Exposes `scheme:bridge/<name>` and
   connects multiple `scheme:network/*` devices. The bridge itself registers as a
   `scheme:network/bridge0` so `netstack` treats it like any other NIC. Reference:
   Linux `net/bridge/br_device.c` and `struct net_bridge`.

6.3 **VLAN support.** Add 802.1Q VLAN tag parsing in `EthernetLink` (or a separate
   `VlanLink` wrapper). Expose `scheme:network/<iface>.<vlan>` virtual devices. Reference:
   Linux `net/8021q/`.

6.4 **Bonding / link aggregation.** A `bondd` daemon implementing LACP (802.3ad) or
   active-backup. Higher-effort; defer until multi-NIC (Phase 1) is solid.

6.5 **TUN/TAP scheme daemon.** A `tund`/`tapd` that exposes a virtual interface to
   userspace — read/write packets from an application. Useful for VPN daemons (WireGuard,
   OpenVPN). Reference: Linux `drivers/net/tun.c`.

6.6 **Routing daemon support.** Once the FIB/route table supports sufficient scale, port
   a routing daemon (bird or FRRouting) so Red Bear can participate in dynamic routing.
   This is userspace-only work; no `netstack` changes needed beyond performance.

6.7 **`sk_buff`-equivalent metadata struct.** Introduce a `Packet` struct in `netstack`
   that carries metadata (ingress interface, VLAN tag, receive timestamp, mark/label for
   firewall) alongside the raw bytes. This replaces the current `[u8]`-only model and
   enables future features (QoS marking, policy routing on metadata, observability).
   Reference: Linux `struct sk_buff` (`include/linux/skbuff.h`). **This is a significant
   internal refactor and should be staged carefully.**

**Success Criteria:**
- A Red Bear VM routes packets between two subnets at >100 Mbps.
- A bridge connects two VMs on the same L2 segment.
- VLAN-tagged traffic is correctly classified.
- (Stretch) WireGuard establishes a tunnel between two Red Bear VMs.

**Validation target:** qemu-proven for forwarding, bridge, VLAN; experimental for bonding
and TUN/TAP.

## Cross-Cutting Concerns

### Observability

Throughout all phases, maintain and extend the `redbear-netstat` tool to surface new
state:
- Phase 1: per-interface statistics table.
- Phase 2: IPv6 neighbor cache (`ndp -a` equivalent), IPv6 routes.
- Phase 3: TCP socket details (cwnd, rtt, retransmits — from smoltcp socket introspection).
- Phase 4: conntrack table (`conntrack -L` equivalent), firewall rule hit counters.
- Phase 6: bridge MAC table, VLAN mappings.

Add a `redbear-tcpdump` or `scheme:netcfg/pcap` capability for packet capture. A
userspace packet capture daemon that taps the `PRE_ROUTING` hook (Phase 4) and writes
pcap files would be invaluable for debugging.

### Testing

- **Host-tested:** smoltcp already has extensive upstream tests. Add Red Bear-specific
  tests for: NDP state machine, firewall rule evaluation, conntrack state transitions,
  NAT mapping correctness.
- **QEMU-tested:** Establish a standard QEMU networking test image with two NICs,
  configurable network topology, and a test runner that boots Red Bear, runs a series
  of network commands, and checks output. Reference: Linux's `tools/testing/selftests/net/`.
- **Bare-metal validated:** The Phase 5 harness. Document results in
  `local/docs/networking-validation-log.md`.

### Documentation

This plan should be updated when:
- A phase is started or completed (update the status matrix).
- An upstream commit is imported or intentionally skipped (update the sync table).
- A design decision is made (e.g., the zero-copy design doc from Phase 3.6).
- A validation milestone is reached.

## Validation Evidence Requirements

Per the project's evidence policy, claims in this plan are not complete without:

| Claim Type | Required Evidence |
|---|---|
| "builds" | `repo cook recipes/core/base` succeeds; `netstack` binary present in stage. |
| "qemu-proven" | QEMU boot log showing the daemon start, the scheme registration, and the test command succeeding (e.g., `curl -v` output). |
| "host-tested" | `cargo test` output from the relevant crate (relibc, netstack, redbear-netctl). |
| "validated" | Bare-metal test report: hardware model, NIC model, kernel/driver versions, test commands, and results. Stored in `local/docs/networking-validation-log.md`. |

## Risk Register

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| smoltcp 0.12 IPv6 surface incomplete | Medium | High (blocks Phase 2) | Spike first: enable `proto-ipv6`, audit compilation errors and missing APIs before committing to Phase 2. |
| SACK requires smoltcp fork | High | Medium (Phase 3.3) | Engage upstream smoltcp maintainers early. Carry a local patch as fallback. |
| Zero-copy incompatible with scheme IPC | Medium | High (Phase 3.6) | Treat as research only in Phase 3. Do not block other Phase 3 work on it. |
| Firewall in-process vs out-of-process debate stalls Phase 4 | Medium | High | Decision criterion: rule-lookup latency. Benchmark Design A vs Design B with a 1000-rule ruleset before committing. |
| Bare-metal NIC unavailable for Phase 5 | Medium | Medium | Prioritize QEMU validation. Document bare-metal as stretch. |
| Upstream relibc refactor (`cab002146` "move protocols into libredox") conflicts with local patches | Medium | High | Evaluate early in Phase 0. If the refactor is large, defer to a dedicated sync sprint rather than mixing with feature work. |

## Execution Order Summary

```
Phase 0 (upstream sync, 2-3w) ──┬── Phase 1 (multi-NIC, capabilities, 3-4w) ──┬── Phase 3 (TCP perf, CC, 6-8w)
                                │                                              │
                                │                                              ├── Phase 5 (drivers, HW validation, ongoing)
                                │                                              │
                                └── Phase 2 (IPv6, 4-6w) ──────────────────────┤
                                                                               │
                                                                               └── Phase 4 (firewall, NAT, 6-10w)
                                                                                       │
                                                                                       └── Phase 6 (forwarding, virtual devices, 8-16w)
```

**Critical path:** Phase 0 → Phase 1 → Phase 3 (TCP perf is the highest user-visible impact).
**Parallel track:** Phase 2 (IPv6) can proceed alongside Phase 3 once Phase 0 is done.
**Enabling track:** Phase 4 (firewall) unblocks Phase 6 (forwarding/NAT).
**Long tail:** Phase 5 (hardware validation) and Phase 6 (virtual devices) run continuously.

## Appendix A: File Inventory

### TCP/IP Stack Core (`local/sources/base/netstack/`)

| File | Purpose |
|---|---|
| `src/main.rs` | Daemon entry: event loop, scheme fd setup, `Smolnetd::new()` |
| `src/scheme/mod.rs` | `Smolnetd` struct: owns `Interface`, `SocketSet`, `Router`, all scheme handlers |
| `src/scheme/socket.rs` | Generic `SocketScheme<SocketT>`: open/dup/read/write/fcntl/fevent |
| `src/scheme/tcp.rs` | `TcpScheme` over smoltcp `TcpSocket`. Port range 49152–65535. |
| `src/scheme/udp.rs` | `UdpScheme` over smoltcp `UdpSocket`. Connected-UDP peek filter. |
| `src/scheme/icmp.rs` | `IcmpScheme` over smoltcp `IcmpSocket`. Root-only. |
| `src/scheme/ip.rs` | `IpScheme` over smoltcp `RawSocket`. Root-only. |
| `src/scheme/netcfg/mod.rs` | `NetCfgScheme`: filesystem-like config (routes, DNS, interfaces). |
| `src/scheme/netcfg/nodes.rs` | `cfg_node!` macro for declaring config tree nodes. |
| `src/scheme/netcfg/notifier.rs` | fevent notification on config change. |
| `src/link/mod.rs` | `LinkDevice` trait + `DeviceList` container. |
| `src/link/ethernet.rs` | `EthernetLink`: ARP, neighbor cache (60s TTL), frame I/O. **IPv4-only.** |
| `src/link/loopback.rs` | Loopback `LinkDevice`. |
| `src/router/mod.rs` | `Router`: smoltcp `phy::Device` impl. RX/TX packet buffers. MTU=1486. |
| `src/router/route_table.rs` | `RouteTable`: `Vec<Rule>` longest-prefix-match. |
| `src/buffer_pool.rs` | Buffer pool (audit usage). |
| `src/port_set.rs` | Ephemeral port allocation (49152–65535). |
| `src/error.rs` | Error types. |
| `src/logger.rs` | `redox_log` integration. Logger name: `"smolnetd"`. |
| `Cargo.toml` | smoltcp 0.12.0 features, redox-scheme/daemon/event deps. |

### Driver Family (`local/sources/base/drivers/net/`)

| File | Purpose |
|---|---|
| `driver-network/src/lib.rs` | `NetworkAdapter` trait (4 methods) + `NetworkScheme<T>` wrapper. |
| `e1000d/src/{main,device}.rs` | Intel 8254x. PCI BAR0 MMIO. IRQ-driven. |
| `e1000d/config.toml` | PCI IDs: 8086:1004, 100e, 100f, 109a, 1503. |
| `ixgbed/src/{main,device}.rs` | Intel 82599 10GbE. |
| `rtl8139d/src/{main,device}.rs` | Realtek RTL8139. |
| `rtl8168d/src/{main,device}.rs` | Realtek RTL8168/8169. |
| `virtio-netd/src/{main,scheme}.rs` | VirtIO net. DMA-backed rx/tx queues. |

### Socket Layer (`local/sources/relibc/`)

| File | Purpose |
|---|---|
| `src/header/sys_socket/mod.rs` | POSIX socket API: socket/bind/connect/listen/accept/send/recv/... |
| `src/header/sys_socket/constants.rs` | SOCK_STREAM, SOCK_DGRAM, AF_INET, SOL_SOCKET, SO_* constants. |
| `src/platform/redox/socket.rs` | Redox backend: AF_INET→`/scheme/tcp`, dup-based connect/bind. |
| `src/header/netdb/mod.rs` | getaddrinfo, getnameinfo, gethostbyname, h_errno. |

### Protocol Layer (`local/sources/libredox/`)

| File | Purpose |
|---|---|
| `src/lib.rs:909` | `SocketCall` enum: Bind/Connect/SetSockOpt/GetSockOpt/SendMsg/RecvMsg/Unbind/GetToken/GetPeerName/Shutdown. |

### Kernel Scheme Dispatch (`local/sources/kernel/`)

| File | Purpose |
|---|---|
| `src/scheme/mod.rs` | Scheme registry: global schemes + UserScheme dispatch. |
| `src/scheme/user.rs` | `UserScheme`: forwards open/read/write/dup/call to userspace daemons. |

### Configuration

| File | Purpose |
|---|---|
| `config/redbear-netctl.toml` | Netctl profile examples (wired-DHCP, wired-static, wifi-dhcp, wifi-open). Init service `12_netctl.service`. |
| `config/redbear-wifi-experimental.toml` | Wi-Fi experimental target (includes `redbear-iwlwifi`). |
| `config/redbear-mini.toml` | Mini target: includes `redbear-netctl`, `redbear-netstat`, `redbear-wifictl`, `smolnetd` service. |
| `config/redbear-full.toml` | Full desktop target. |
| `/etc/init.d/10_smolnetd.service` | smolnetd (notify type). Requires `00_pcid-spawner`. |
| `/etc/init.d/10_dhcpd.service` | dhcpd (oneshot_async). Requires `10_smolnetd`. |

### Custom Red Bear Networking Tools (`local/recipes/system/`)

| Package | Purpose |
|---|---|
| `redbear-netctl` | Network profile orchestration (Arch netctl-style). |
| `redbear-netctl-console` | TUI frontend for `redbear-netctl`. |
| `redbear-netstat` | Socket/interface/routing statistics. |
| `redbear-wifictl` | Wi-Fi control daemon + scheme. |
| `redbear-mtr` | MTR (traceroute + ping). |
| `redbear-nmap` | Port scanner. |
| `redbear-traceroute` | Traceroute. |

## Appendix B: Linux 7.1 Reference File Map

For cross-referencing during implementation, the key Linux 7.1 source locations:

| Subsystem | Linux Path |
|---|---|
| Socket layer | `net/socket.c` (3,822 LoC) |
| TCP | `net/ipv4/tcp.c` (5,382 LoC), `tcp_input.c`, `tcp_output.c` |
| UDP | `net/ipv4/udp.c` (3,892 LoC) |
| IP input/output | `net/ipv4/ip_input.c`, `ip_output.c` |
| IPv6 | `net/ipv6/` (40+ files), always built-in in 7.1 |
| FIB routing | `net/ipv4/fib_trie.c`, `fib_semantics.c`, `include/net/ip_fib.h` |
| Netfilter hooks | `include/uapi/linux/netfilter.h:43`, `struct nf_hook_ops` |
| Conntrack | `net/netfilter/nf_conntrack_core.c`, `include/net/netfilter/nf_conntrack.h:74` |
| nftables | `net/netfilter/nf_tables_api.c`, 57+ `nft_*.c` |
| Congestion control | `include/net/tcp.h:1325` `struct tcp_congestion_ops`, `tcp_cubic.c`, `tcp_bbr.c` |
| NAPI | `include/linux/netdevice.h:381` `struct napi_struct` |
| GRO/GSO | `net/core/gro.c`, `net/core/gso.c` |
| Zero-copy send | `net/ipv4/tcp.c:1140`, `net/core/skbuff.c:1719` |
| `sk_buff` | `include/linux/skbuff.h` (5,462 LoC) |
| `net_device` | `include/linux/netdevice.h:2139` (5,737 LoC) |
| `net_device_ops` | `include/linux/netdevice.h:1443` |
| Wireless (cfg80211) | `include/net/cfg80211.h` (10,995 LoC), `net/wireless/core.c` |
| Wireless (mac80211) | `net/mac80211/` (60+ files) |
| nl80211 | `include/uapi/linux/nl80211.h` (9,080 LoC) |
| epoll | `fs/eventpoll.c` (~3,000 LoC) |
| io_uring networking | `io_uring/net.c`, `io_uring/zcrx.c`, `IORING_OP_RECV_ZC` |

## Appendix C: Upstream Redox Networking Activity (2024–2026)

Selected high-relevance commits from `redox-os/*` repositories. Full list maintained in the
sync tracking issue.

### Kernel

- `6c3d5d28c` (2026-07-01) Move FD allocation logic into userspace
- `c089667ad` (2025-12-13) Remove legacy packet user schemes
- `4ff82ad8b` (2025-11-27) Fix user scheme deadlocks in `call_extended_inner`
- `08ea1da2f` (2025-07-05) Trigger read event for user schemes on fd close
- `99ff55ee1` (2026-02-08) Demux results as soon as received from user scheme

### Netstack (now in `base`)

- `b92be2e7d` (2025-03-09) Update to smoltcp 0.12
- `d7c128684` (2025-03-09) Use CUBIC as TCP congestion controller
- `640e54897` (2024-09-04) Use 0.0.0.0 as default IP (DHCP fix)
- `49abe218a` (2024-11-26) ARP fix: respond only to device's broadcast/unicast
- `8e2d02232` (2024-03-18) Switch to libredox and redox-event
- `bafdb3b66` (2024-07-11) New scheme format, no legacy paths
- `f9b3170f0` (2024-02-28) Named network adapters
- `c06e5b14e` (2025-03-10) Netstack moved to base repo

### Drivers

- `ad9305bf9` (2024-02-28) Unify network drivers under `net/`
- `921c6b07f` (2024-12-26) driver-network migrated to redox-scheme
- `dd41c4f13` (2025-11-23) Net: scheme created before device init
- `0f24975ff` (2025-11-29) PCI interrupts rework5 (RTL dedup)
- `407533201` (2025-09-24) Add ThinkPad T60 ethernet to e1000d

### relibc

- `94b0cfc68` (2026-02-08) Reimplement recvmsg/sendmsg with bulk FD passing
- `1978c1aa4` (2026-03-25) Full recvmsg implementation
- `cab002146` (2026-02-28) Move protocols into libredox
- `6a455159a` (2026-01-22) Fix getaddrinfo infinite loop hang
- `726a0fb1a` (2025-09-15) getaddrinfo NULL nodename, AI_PASSIVE
- `5334455a2` (2025-08-20) getnameinfo + getaddrinfo loopback
- `9eaa9e82b` (2025-11-08) Pass through all SOL_SOCKET options
- `d44010170` (2025-07-18) UDS bind/connect with RedoxFS
- `9c6701802` (2026-01-07) Add sys_socket tests

### syscall

- `7a1409a91` (2026-05-27) Multiple FDs variant for call (bulk FD passing)
- `178461f6f` (2025-12-27) Remove remnants of old packet format

### Build/config

- `85b62fd85` (2026-03-01) Support networking in all configs
- `193e81897` (2026-02-17) ~115 WIP networking recipes
- `b68e5a685` (2026-04-11) Move dhcpd from netutils to base

---

**Document version:** 1.0 (2026-07-07)
**Authority:** Canonical for TCP/IP stack, socket surface, Ethernet drivers, and network
configuration. See companion plans for Wi-Fi, IRQ, and Bluetooth.