| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391 |
- <!doctype html>
- <html lang="en">
- <head>
- <meta charset="utf-8">
- <meta name="viewport" content="width=device-width, initial-scale=1">
- <title>Networking | NebOS Architecture</title>
- <meta name="description" content="NebOS networking: the netdev registry and NIC drivers, ARP/ICMP/UDP, DHCP, DNS, NTP, the TCP client and listener, TLS 1.3, sys_net ownership, netconsole and netkexec.">
- <link rel="icon" href="favicon.svg" type="image/svg+xml">
- <link rel="stylesheet" href="style.css">
- </head>
- <body>
- <a class="skip" href="#main">Skip to content</a>
- <header class="site-header">
- <a class="brand" href="index.html">
- <span class="brand-mark" aria-hidden="true"></span>
- <span>NebOS <span class="brand-sub">Architecture</span></span>
- </a>
- <nav class="site-nav" aria-label="Architecture sections">
- <a href="index.html">Overview</a>
- <a href="boot.html">Boot</a>
- <a href="memory.html">Memory</a>
- <a href="cpu.html">CPU</a>
- <a href="drivers.html">Drivers</a>
- <a href="filesystems.html">Filesystems</a>
- <a href="graphics.html">Graphics</a>
- <a href="network.html" aria-current="page">Network</a>
- <a href="userland.html">Userland</a>
- <a href="development.html">Development</a>
- </nav>
- </header>
- <main id="main" class="page">
- <div class="page-head">
- <p class="kicker">Networking</p>
- <h1>A small stack with a shared receive pump.</h1>
- <p class="lede">
- The NIC and the protocol stack live in the kernel; ring-3 commands
- drive them through <code>SYS_NET_*</code> and <code>SYS_TCP_*</code>.
- Packet-level commands still take the receiver exclusively through
- <code>SYS_NET_ACQUIRE</code>, while up to twelve processes can hold a
- TCP client connection at the same time. Every stack syscall drains
- the NIC through <code>net_pump()</code>, so downloads overlap without
- sharing one connection or one receive queue.
- </p>
- <div class="meta">
- <span class="pill">ARP · ICMP · UDP · TCP</span>
- <span class="pill">DHCP · DNS · NTP</span>
- <span class="pill">TLS 1.3 · X25519</span>
- <span class="pill">netconsole + netkexec</span>
- </div>
- </div>
- <nav class="toc" aria-label="On this page">
- <h2>On this page</h2>
- <ul>
- <li><a href="#stack">Protocol stack</a></li>
- <li><a href="#netdev">NIC drivers</a></li>
- <li><a href="#core">Link & IP layer</a></li>
- <li><a href="#dhcp">DHCP, DNS & NTP</a></li>
- <li><a href="#tcp">TCP</a></li>
- <li><a href="#tls">TLS</a></li>
- <li><a href="#abi">sys_net ABI</a></li>
- <li><a href="#console">Netconsole & netkexec</a></li>
- <li><a href="#http">HTTP clients</a></li>
- <li><a href="#security">Security posture</a></li>
- <li><a href="#sources">Source map</a></li>
- </ul>
- </nav>
- <section id="stack">
- <h2>Protocol stack</h2>
- <p>
- NebOS does not expose a general socket API. A ring-3 program asks the
- kernel for info and configuration, then either acquires the receiver
- for raw frame paths or opens one TCP client connection. Each
- connection has its own receive queue and is owned by one process;
- <code>net_pump()</code> dispatches frames to every active client, the
- WebDAV listener, a pending DNS query and the ARP cache. HTTP and TLS
- are libraries linked into the command, not kernel services.
- </p>
- <figure class="figure">
- <svg viewBox="0 0 920 380" role="img" aria-labelledby="net-title net-desc">
- <title id="net-title">NebOS network stack</title>
- <desc id="net-desc">Ring-3 curl, browser and websrv use uhttp and TLS, then sys_net syscalls, then TCP/DNS/DHCP/NTP, IPv4/ARP/ICMP, netdev drivers and the NIC.</desc>
- <rect class="svg-box accent" x="70" y="18" width="780" height="58" rx="9"/>
- <text class="svg-text" x="92" y="43">curl · browser · websrv · ping · dhcp · settime</text>
- <text class="svg-sub" x="92" y="63">ring-3 programs</text>
- <path class="svg-line" d="M460 76v20"/>
- <path class="svg-line" d="M454 90l6 7 6-7"/>
- <rect class="svg-box blue" x="70" y="98" width="380" height="58" rx="9"/>
- <text class="svg-text" x="92" y="123">uhttp · tls.c</text>
- <text class="svg-sub" x="92" y="143">HTTP/1.1 · redirects · chunked · TLS 1.3</text>
- <rect class="svg-box" x="470" y="98" width="380" height="58" rx="9"/>
- <text class="svg-text" x="492" y="123">kernel services</text>
- <text class="svg-sub" x="492" y="143">sys_fs for WebDAV · netlog · netkexec</text>
- <path class="svg-line blue" d="M260 156v18"/>
- <path class="svg-line blue" d="M254 168l6 7 6-7"/>
- <path class="svg-line" d="M660 156v18"/>
- <path class="svg-line" d="M654 168l6 7 6-7"/>
- <rect class="svg-box green" x="70" y="176" width="780" height="58" rx="9"/>
- <text class="svg-text" x="92" y="201">SYS_NET_* · SYS_TCP_* · SYS_DNS_RESOLVE · SYS_DHCP_RUN · SYS_NTP_SYNC</text>
- <text class="svg-sub" x="92" y="221">raw owner for packet commands · shared net_pump for TCP/DNS/ARP</text>
- <path class="svg-line green" d="M460 234v20"/>
- <path class="svg-line green" d="M454 248l6 7 6-7"/>
- <rect class="svg-box" x="70" y="256" width="780" height="58" rx="9"/>
- <text class="svg-text" x="92" y="281">tcp.c · dns.c · dhcp.c</text>
- <text class="svg-sub" x="92" y="301">TCP client table + listener · one pending A query · DISCOVER/OFFER/REQUEST/ACK</text>
- <path class="svg-line" d="M460 314v16"/>
- <path class="svg-line" d="M454 324l6 7 6-7"/>
- <rect class="svg-box blue" x="70" y="332" width="780" height="44" rx="9"/>
- <text class="svg-text" x="92" y="359">IPv4 · ARP · ICMP · UDP · netdev registry · NIC driver</text>
- </svg>
- <figcaption>
- <strong>Thin kernel, thick command.</strong> The kernel owns
- addressing, ARP, routing and the shared TCP client table. HTTP,
- TLS and WebDAV run in ring 3, so a protocol bug kills a command
- rather than the kernel.
- </figcaption>
- </figure>
- </section>
- <section id="netdev">
- <h2>NIC drivers</h2>
- <p>
- <span class="file">netdev.c</span> keeps a registry of
- <code>struct netdev</code> drivers; the first one whose probe succeeds
- becomes active. All drivers are polled and share the same transmit,
- receive, register-dump and reset interface. <code>netdev</code> with
- no argument shows the active driver; <code>netdev rndis</code> or
- <code>netdev asix</code> switches to a named one, leaving the current
- driver untouched if the probe fails.
- </p>
- <p>
- <span class="file">rndis.c</span> is the USB tethering path, not a
- WiFi driver: an Android phone (or QEMU's <code>usb-net</code>) is
- parsed for an RNDIS control/data interface pair, initialized with
- RNDIS INIT/QUERY/SET messages, and then presented as an ordinary
- Ethernet NIC. <code>netdev rndis</code> selects it and
- <code>dhcp</code> obtains the phone's tethering address. QEMU has no
- phone dependency: <code>make run-rndis</code> boots with
- <code>qemu-xhci</code> and <code>usb-net</code> on slirp. RNDIS only;
- CDC-ECM/NCM, IPv6 and automatic DHCP after a hotplug are not
- implemented.
- </p>
- <div class="table-wrap">
- <table>
- <thead>
- <tr><th>Driver</th><th>Hardware</th><th>Transport</th><th>Notes</th></tr>
- </thead>
- <tbody>
- <tr><td><span class="file">e1000e.c</span></td><td>Intel 82540EM, 82577LM, 82578, 82579</td><td>PCI MMIO</td><td>PCI INTx disabled before MMIO; PCH D0; skips the global MAC reset while the link is up.</td></tr>
- <tr><td><span class="file">r8168.c</span></td><td>RTL8111/8168</td><td>PCIe MMIO</td><td>C+ mode, 64-entry RX ring, polled.</td></tr>
- <tr><td><span class="file">ne2000.c</span></td><td>RTL8029</td><td>ISA / QEMU PCI</td><td>Simple DP8390 path used by <code>make run-net</code>.</td></tr>
- <tr><td><span class="file">asix.c</span></td><td>AX88772</td><td>USB bulk</td><td>Runs over the USB core; usable on EHCI/xHCI dongles.</td></tr>
- <tr><td><span class="file">rndis.c</span></td><td>Android USB tethering, QEMU <code>usb-net</code></td><td>USB control + bulk</td><td>RNDIS INIT/QUERY/packet filter; presents the phone's tethering link as an Ethernet netdev.</td></tr>
- </tbody>
- </table>
- </div>
- <p>
- The management NIC used by netlog and netkexec prefers the ASIX dongle
- so a direct debug link survives <code>netdev e1000e</code>; otherwise
- it falls back to the active driver. <code>netregs</code> dumps registers
- and decoded interrupt status; <code>netloop</code> runs a PHY loopback
- self-test; <code>netreset</code> re-initialises the active NIC.
- </p>
- </section>
- <section id="core">
- <h2>Link & IP layer</h2>
- <ul>
- <li><strong>Ethernet decode</strong> recognises IPv4, ARP and IPv6 frame types (IPv6 is not implemented).</li>
- <li><strong>ARP</strong> resolves a next hop with three tries, one second apart; <code>net_arp_resolve()</code> polls the active NIC and the caller must own it.</li>
- <li><strong>Routing</strong> sends off-subnet traffic to the gateway when one is known; <code>net_next_hop()</code> is shared by ping, DNS and TCP.</li>
- <li><strong>ICMP echo</strong> backs <code>ping</code>, with ARP resolution and round-trip timing.</li>
- <li><strong>UDP</strong> has send and parse helpers; DNS, DHCP, NTP and netlog are its users.</li>
- <li><strong>Checksums</strong> use the Internet one's-complement sum, with a TCP pseudo-header variant.</li>
- </ul>
- <p>
- The static default address is <code>192.168.178.240</code>. At boot,
- with a NIC present, a DHCP client runs with a 4-second budget
- (requesting the current address); if no server answers, the static
- address stays. The idle WM loop answers ARP/ICMP for the board's IP
- even when no command is running, so the board is reachable and
- MAC-resolvable.
- </p>
- </section>
- <section id="dhcp">
- <h2>DHCP, DNS & NTP</h2>
- <h3>DHCP</h3>
- <p>
- <span class="file">dhcp.c</span> is a minimal client:
- DISCOVER → OFFER → REQUEST → ACK. It learns the mask, gateway and DNS
- server (option 6), and <code>dhcp</code> re-runs it on demand. The
- configuration is retained across kexec through the boot-info
- <code>BOOTINFO_FLAG_NET</code> fields.
- </p>
- <h3>DNS</h3>
- <p>
- <span class="file">dns.c</span> sends one recursive A query over UDP
- and handles name compression in the response. One query is in
- flight at a time; parallel stack callers wait for it and then hit a
- small five-minute A-record cache, so three browser workers asking
- for the same host cause one DNS query, not three. <code>netdns</code>
- shows or sets the server; <code>host <name></code> resolves.
- Numeric hosts skip DNS entirely.
- </p>
- <h3>NTP</h3>
- <p>
- <span class="file">ntp.c</span> is a minimal SNTP (RFC 4330)
- client: one 48-byte request to UDP port 123, three one-second
- tries, DNS unless the server is a dotted address, and the shared
- ARP/router path. An empty name uses <code>pool.ntp.org</code>.
- A reply is accepted only when it comes from the
- resolved server to the ephemeral source port, is a server/broadcast
- reply with a valid stratum, and echoes the request's origin
- timestamp; the transmit timestamp is converted from NTP's 1900 epoch
- to a UTC <code>struct sys_datetime</code> (with the 2036 era wrap
- handled). <code>SYS_NTP_SYNC</code> returns that value to ring 3;
- the Date & Time editor then writes it through
- <code>SYS_RTC_SET</code>. The service owns the raw receiver for the
- duration, so it reports <code>SYS_NTP_EBUSY</code> while another raw
- command or a TCP client is active.
- </p>
- <div class="warn">
- <p><strong>NTP is unauthenticated.</strong> The origin-timestamp
- check rejects unrelated datagrams but does not authenticate the
- server; anyone who can answer for the configured name can set the
- board's clock. There is no NTS, no leap-second handling and no
- delay/dispersion estimation — the CMOS RTC only resolves seconds.</p>
- </div>
- </section>
- <section id="tcp">
- <h2>TCP</h2>
- <p>
- <span class="file">tcp.c</span> implements a small client table, not a
- general socket layer: each process may hold one connect/send/receive/
- close connection, and up to <code>TCP_CLIENT_MAX</code> (twelve)
- connections can be active. Every connection owns a 4 KB receive
- queue, so one socket's data can never be read or reset by another.
- The window update is sent whenever the application drains the queue,
- so a full queue cannot deadlock until the peer's zero-window probe.
- </p>
- <ul>
- <li><strong>Demultiplexing.</strong> <code>net_pump()</code> feeds every received frame to <code>tcp_client_input()</code>, which matches the destination IP and port pair and updates that connection's sequence state.</li>
- <li><strong>MSS / window.</strong> Our MSS is 1460 bytes and the advertised window is 4 KB.</li>
- <li><strong>Retransmit.</strong> A 500 ms retry timer with a small retry count carries the connection through loss; there is no full congestion-control state machine.</li>
- <li><strong>Listener.</strong> The server side has one active connection plus three backlog/closing slots. SYN-ACK advertises a zero window while queued; a queued connection may hold 1 KB of early request, and the window opens when <code>tcp_srv_accept()</code> runs.</li>
- <li><strong>Bursts.</strong> Responses go out in up to four-segment bursts with a cumulative ACK, rather than one segment per ACK.</li>
- <li><strong>No keep-alive.</strong> The WebDAV listener still has one active connection; an idle persistent connection would block the parallel connections Nautilus opens. Client keep-alive is per helper process and does not hold the raw lease.</li>
- </ul>
- <p>
- New SYNs and data are also handed to <code>tcp_srv_input()</code> from
- the active connection's receive/send poll loops, not only between
- requests, so parallel gvfs clients make progress.
- </p>
- </section>
- <section id="tls">
- <h2>TLS 1.3</h2>
- <p>
- <span class="file">tls.c</span> is a ring-3 client with a deliberately
- narrow cipher suite: <code>TLS_CHACHA20_POLY1305_SHA256</code> and
- X25519 only. It is stream-oriented over the existing TCP connection
- and prints the leaf SHA-256 fingerprint for manual comparison.
- </p>
- <ul>
- <li><strong>Not verified.</strong> Phase A provides encryption without authentication; a MITM is undetected. <code>curl</code> warns, and the browser marks HTTPS as unverified.</li>
- <li><strong>Weak DRBG.</strong> <span class="file">tls_rng.c</span> mixes RDTSC jitter, ticks and the MAC; it is not a hardware-backed CSPRNG.</li>
- <li><strong>Host tests.</strong> The crypto files are pure freestanding C with host vectors (<code>make test-crypto</code>, <code>tls_test.c</code>).</li>
- </ul>
- <div class="warn">
- <p><strong>Do not treat HTTPS as secure authentication.</strong> The
- cipher suite is real, but without certificate verification the
- connection authenticates nothing. Use it for confidentiality on a
- trusted network, not for secrets against an active attacker.</p>
- </div>
- </section>
- <section id="abi">
- <h2>sys_net ABI & ownership</h2>
- <p>
- <span class="file">sys_net.c</span> exposes NIC info, MAC/IP/mask/
- gateway/DNS getters and setters, raw frame TX/RX, decode, reply,
- loopback, register dump, reset, speed and MAC overrides. It also
- exposes the DNS, DHCP and NTP clients and the TCP/HTTP helpers.
- </p>
- <ul>
- <li><strong>Raw owner.</strong> <code>SYS_NET_ACQUIRE</code> takes the receiver for a packet-level command; the background kexec watcher pauses while one owns it. TCP clients do not take this lease, so they can run alongside each other.</li>
- <li><strong>Mode gates.</strong> A raw acquire fails while any TCP client socket is open, and <code>SYS_TCP_CONNECT</code> fails while a raw owner exists. This keeps packet commands and the shared pump from stealing each other's frames.</li>
- <li><strong>Reaper safety.</strong> If a raw owner dies, <code>sys_net_reap</code> force-releases the receiver through <code>netdev_release_all()</code>; sockets and a pending DNS query owned by the dead process are closed separately.</li>
- <li><strong>Wait semantics.</strong> Stack waits now yield with <code>process_sleep_ms()</code> and re-enable interrupts for driver TX timeouts; the syscall stub enters with interrupts off.</li>
- <li><strong>One connection per process.</strong> The connection state lives in the kernel, keyed by the calling pid. <code>SYS_TCP_CONNECT/SEND/RECV/CLOSE</code> keep their ABI, so uhttp and the TLS layer did not need a socket handle.</li>
- </ul>
- </section>
- <section id="console">
- <h2>Netconsole & netkexec</h2>
- <p>
- <span class="file">netlog.c</span> mirrors the serial console and
- terminal output to UDP port 19290. The mirror is on by default and
- broadcasts; <code>netconsole host <laptop-ip></code> narrows it,
- <code>netconsole off</code>/<code>on</code> toggles it, and
- <code>netlog <text></code> sends an ad-hoc line. The producer
- never blocks: a full buffer drops characters and reports it. The
- flush pauses while a raw command owns the receiver or a TCP/stack
- operation is active, so its broadcast traffic cannot compete with
- DNS/ARP replies.
- </p>
- <p>
- <span class="file">netkexec.c</span> receives a new kernel/rootfs over
- UDP port 19288 using <code>KXN2</code>, and a runtime command pack
- using <code>KXNP</code>. Datagrams are acknowledged with the next
- expected offset and verified with a 32-bit checksum before the jump
- or pack swap. On the host, <code>make netmon</code> and
- <code>make net-dev</code> wrap these protocols.
- </p>
- </section>
- <section id="http">
- <h2>HTTP clients</h2>
- <ul>
- <li><strong>curl</strong> — <code>http://</code> or <code>https://</code> GET with DNS, ARP, redirects (up to five hops), chunked decoding, status/headers/body dump and a TLS warning.</li>
- <li><strong>uhttp</strong> — shared ring-3 HTTP/1.1 client used by curl and the browser: URL parsing, redirects, chunked decoding, timeouts and TLS.</li>
- <li><strong>browser</strong> — runs network fetches in up to three headless <code>curl __serve</code> workers, each with its own request/body/meta files under <code>/share/bf<session>_<slot>*</code>. The session id comes from the browser pid, so multiple browser windows do not share queue files. Images are prefetched in parallel and decoded as jobs complete, so the UI keeps drawing and scrolling. Each worker keeps its own TCP/TLS connection.</li>
- <li><strong>websrv</strong> — the server side, speaking HTTP/1.1 + WebDAV over the TCP listener; see <a href="filesystems.html#webdav">Filesystems → WebDAV</a>.</li>
- </ul>
- <p>
- The browser's helper requests identity encoding because inflating
- multi-megabyte pages in the UI process stalled. If a server still
- sends gzip, the browser's inflate hook pumps the UI while decoding.
- </p>
- </section>
- <section id="security">
- <h2>Security posture</h2>
- <div class="table-wrap">
- <table>
- <thead>
- <tr><th>Surface</th><th>State</th><th>Consequence</th></tr>
- </thead>
- <tbody>
- <tr><td>TLS certificates</td><td>Not verified</td><td>Encryption without authentication; MITM is undetected.</td></tr>
- <tr><td>TLS DRBG</td><td>Weak (RDTSC/ticks/MAC)</td><td>Not suitable for high-value secrets.</td></tr>
- <tr><td>WebDAV</td><td>No authentication</td><td>Anyone on the LAN can read mounts and write <code>/share</code>.</td></tr>
- <tr><td>NTP</td><td>Unauthenticated SNTP</td><td>Anyone who can answer for the server name can set the clock.</td></tr>
- <tr><td>NIC ownership</td><td>Raw lease for packet commands; shared TCP client table</td><td>Raw commands are mutually exclusive; up to twelve processes can hold one TCP connection each. A killed owner is force-released.</td></tr>
- <tr><td>Kernel/user isolation</td><td>None (identity map)</td><td>A ring-3 bug can reach any mapped kernel page.</td></tr>
- </tbody>
- </table>
- </div>
- </section>
- <section id="sources">
- <h2>Source map</h2>
- <ul class="filelist">
- <li><code>netdev.c</code>, <code>netdev.h</code> — registry</li>
- <li><code>e1000e.c</code>, <code>r8168.c</code>, <code>ne2000.c</code>, <code>asix.c</code>, <code>rndis.c</code></li>
- <li><code>net.c</code>, <code>net.h</code> — ARP cache/ICMP/UDP/IP</li>
- <li><code>netcore.c</code>, <code>netcore.h</code> — shared receive pump and IRQ helpers</li>
- <li><code>dhcp.c</code>, <code>dns.c</code>, <code>ntp.c</code></li>
- <li><code>tcp.c</code>, <code>tcp.h</code> — client table + listener</li>
- <li><code>tls.c</code>, <code>tls_*.c</code> — TLS 1.3</li>
- <li><code>sys_net.c</code> — ring-3 service</li>
- <li><code>netlog.c</code>, <code>netkexec.c</code></li>
- <li><code>uhttp.c</code>, <code>ucmd_curl.c</code>, <code>ucmd_websrv.c</code></li>
- </ul>
- </section>
- </main>
- <footer class="site-footer">
- <div class="inner">
- <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
- <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
- </div>
- </footer>
- </body>
- </html>
|