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:

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:

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:

# /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.