RedBear-OS/local/docs/NETWORKING-STACK-STATE.md

Red Bear OS Networking Stack — Current State (2026-07-09)

Overview

The userspace TCP/IP stack (netstack / smolnetd) runs as a Redox scheme daemon implementing the full IP stack in Rust on top of smoltcp 0.12.0.

Architecture

┌──────────────────────────────────────────────────────────────────────┐
│                        smolnetd (netstack)                           │
│                                                                      │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐               │
│  │  scheme: │ │  scheme: │ │  scheme: │ │  scheme: │  ...          │
│  │  tcp     │ │  udp     │ │  icmp    │ │  netcfg  │               │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘               │
│       │             │           │            │                      │
│  ┌────┴─────────────┴───────────┴────────────┴─────┐               │
│  │              SocketSet (smoltcp)                  │               │
│  └────────────────────────┬──────────────────────────┘               │
│                           │                                         │
│  ┌────────────────────────┴──────────────────────────┐               │
│  │                   Router + Filter                   │               │
│  │  ┌─────────┐ ┌──────────┐ ┌──────────┐             │               │
│  │  │ Filter   │ │ NAT      │ │Conntrack │             │               │
│  │  │ (rules)  │ │(snat/dnat)│ │ (states) │             │               │
│  │  └─────────┘ └──────────┘ └──────────┘             │               │
│  └────────────────────────┬──────────────────────────┘               │
│                           │                                         │
│  ┌────────────────────────┴──────────────────────────┐               │
│  │               Ethernet / Loopback / Tunnel          │               │
│  └────────────────────────────────────────────────────┘               │
└──────────────────────────────────────────────────────────────────────┘

Feature Checklist

Transport Layer

• TCP: Full scheme server, listen/accept, connect, close, send/recv
• TCP: Socket options (SO_KEEPALIVE, TCP_NODELAY, TCP_KEEPIDLE, TCP_INFO, SO_LINGER)
• TCP: SYN flood protection (100 SYN/sec per source)
• UDP: Scheme server, bind, connect(), send, recv
• UDP: sendto()/sendmsg() on unconnected sockets (R65)
• UDP: Socket options (SO_REUSEADDR, SO_BROADCAST, IP_TTL)
• ICMP: Echo request/reply (ping)
• ICMP: ICMP error reception (Udp socket type for IP_RECVERR-style notifications)

Network Layer

• IPv4: Full routing, forwarding, dispatch
• IPv6: Routing, NDP, SLAAC address formation, RS/RA exchange
• Route table: Longest-prefix match, metric support, direct routes, flush
• Route types: Unicast, Blackhole, Unreachable, Prohibit
• ARP: Request/reply, cache with 1024-entry LRU limit, statistics
• NDP: Neighbor Solicitation/Advertisement, router solicitation
• ICMP errors: Port Unreachable, Time Exceeded generation
• IP forwarding toggle: sysctl net.ipv4.ip_forward rw

Firewall & Security

• Filter: 5 netfilter hooks, rule evaluation, per-chain counters
• Rule format: iptables-style (ACCEPT input -p tcp --dport 80 --ctstate ESTABLISHED)
• Verdicts: ACCEPT, DROP, LOG, REJECT
• Conntrack: Full TCP state machine (None→SynSent→SynRecv→Established→FinWait→TimeWait→Close)
• Conntrack: UDP/ICMP tracking, ICMP error→Related matching
• Conntrack: SYN/ICMP echo rate limiting per source
• Conntrack: Max entries limit (65536), per-protocol/per-state statistics
• NAT: SNAT/DNAT rules, IPv4 rewrite, checksum recomputation
• NAT: Active binding tracking and display

Virtual Devices

• Bridge: MAC learning, aging (300s), STP 802.1D, FDB
• VLAN: 802.1Q tag insertion/stripping, parent device forwarding
• TUN: L3 tunnel, scheme interface, event loop integration
• VXLAN: Encapsulation/decapsulation, parent forwarding
• GRE: Encapsulation/decapsulation with key support
• IPIP: IP-in-IP tunnel, parent forwarding
• Bond: Round-robin forwarding to slaves

Traffic Control

• Qdisc: TokenBucket rate limiter, PriorityQueue 3-band pfifo_fast
• Qdisc: Configurable per-interface via netcfg

Monitoring & Diagnostics

• Interface stats: rx/tx bytes/packets, errors, drops (RFC 1213 MIB-II)
• ARP stats: Requests, replies, cache hits/misses per interface
• Conntrack stats: Per-protocol/per-TCP-state breakdown
• Connection list: TCP sockets with state, addresses, queue sizes
• Packet capture: Ring buffer with BPF-style filter (proto + port)
• netdiag: CLI tool with live bandwidth monitoring
• Help: Self-documenting API at /scheme/netcfg/help
• NAT display: Per-rule match counts, active binding display

Management

• netcfg: Full scheme for interface config, routing, DNS, capture
• netfilter: Scheme for firewall rules, NAT rules, policy, counters
• sysctl: net.ipv4.ip_forward toggle
• Interface config: MAC, IP, MTU, enable/disable, promiscuous

Testing

• 31 unit tests across filter, conntrack, NAT, bridge, STP, SLAAC, ICMP error
• Regression tests for critical bugs (verdict, ICMP offset, SYN detection, STP panic)

Known Limitations

• No TCP SACK (smoltcp limitation)
• No ECN support
• No IP fragmentation offload
• No hardware checksum offload
• No multicast/IGMP/MLD
• No IPsec/VPN
• VXLAN/GRE/IPIP send path works but there's no automatic inbound RX wiring (packets must be pushed via push_received() externally)