Networking

A small stack with a shared receive pump.

The NIC and the protocol stack live in the kernel; ring-3 commands drive them through SYS_NET_* and SYS_TCP_*. Packet-level commands still take the receiver exclusively through SYS_NET_ACQUIRE, while up to twelve processes can hold a TCP client connection at the same time. Every stack syscall drains the NIC through net_pump(), so downloads overlap without sharing one connection or one receive queue.

ARP · ICMP · UDP · TCP DHCP · DNS · NTP TLS 1.3 · X25519 netconsole + netkexec

Protocol stack

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; net_pump() 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.

NebOS network stack 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. curl · browser · websrv · ping · dhcp · settime ring-3 programs uhttp · tls.c HTTP/1.1 · redirects · chunked · TLS 1.3 kernel services sys_fs for WebDAV · netlog · netkexec SYS_NET_* · SYS_TCP_* · SYS_DNS_RESOLVE · SYS_DHCP_RUN · SYS_NTP_SYNC raw owner for packet commands · shared net_pump for TCP/DNS/ARP tcp.c · dns.c · dhcp.c TCP client table + listener · one pending A query · DISCOVER/OFFER/REQUEST/ACK IPv4 · ARP · ICMP · UDP · netdev registry · NIC driver
Thin kernel, thick command. 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.

NIC drivers

netdev.c keeps a registry of struct netdev drivers; the first one whose probe succeeds becomes active. All drivers are polled and share the same transmit, receive, register-dump and reset interface. netdev with no argument shows the active driver; netdev rndis or netdev asix switches to a named one, leaving the current driver untouched if the probe fails.

The top-bar network icon opens ucmd_netmenu.c. It asks the kernel for every present driver through SYS_NET_DEVLIST (111), so an RNDIS phone or a USB Ethernet dongle that was not the boot-time winner still appears. Selecting one calls SYS_NET_SELECT (112) and then runs DHCP. The same window lists scanned WiFi networks; selecting a WPA2 network asks for the passphrase and starts the existing wifi supplicant, which opens the data port and runs DHCP itself. Mesh/repeater BSSIDs sharing one SSID are collapsed to the strongest entry (the active BSSID wins when connected), and hidden SSIDs are omitted because the menu cannot join them.

rndis.c is the USB tethering path, not a WiFi driver: an Android phone (or QEMU's usb-net) is parsed for an RNDIS control/data interface pair, initialized with RNDIS INIT/QUERY/SET messages, and then presented as an ordinary Ethernet NIC. netdev rndis selects it and dhcp obtains the phone's tethering address. QEMU has no phone dependency: make run-rndis boots with qemu-xhci and usb-net on slirp. RNDIS only; CDC-ECM/NCM, IPv6 and automatic DHCP after a hotplug are not implemented.

wifi.c is the built-in WiFi of the Chromebook (Intel 7265D/3165) and of the ThinkPad X201 (Intel 6200/6300), or a Realtek RTL8821AU USB stick when one is plugged in, see the driver page). It is last in the registry, so the boot probe only makes it active when nothing wired is present (a later wifi connect can still select it over a wired NIC whose cable is unplugged), and it reports link_up() = 0 until it is connected: the boot DHCP checks that optional hook and skips the 4 s attempt. The wifi command scans, associates, runs the WPA2-PSK handshake in ring 3 and then calls SYS_WIFI_AUTHORIZE, which opens the data port and selects the wifi netdev. Data frames are converted between Ethernet and non-QoS 802.11 + LLC/SNAP; EAPOL (ethertype 0x888e) never reaches net_pump() and is queued for the supplicant instead. The top-bar menu starts the same supplicant through wifi connectfile <path>: it stages the SSID, passphrase and BSSID in a small /share/netmenu.wifi record because a SYS_SPAWN argument is limited to VFS_PATH_MAX (64) bytes. The helper removes the file after reading it.

A successful wifi connect (from the CLI or the menu) also saves the SSID and passphrase to /data/WIFI.CFG on the persistent NEBOSDATA partition. After the boot DHCP attempt kernel_main spawns wifi autoconnect when that file exists. It samples the active NIC's link_up() state: a wired cable that is physically up keeps the Ethernet path, while no wired link lets WiFi associate and run DHCP. An existing WiFi link is left alone. wifi forget removes the saved record. The file is a plaintext 8.3 FAT file with the BSSID zeroed so the strongest AP advertising that SSID is used.

DriverHardwareTransportNotes
e1000e.cIntel 82540EM, 82577LM, 82578, 82579PCI MMIOPCI INTx disabled before MMIO; PCH D0; skips the global MAC reset while the link is up; extended RX descriptors only when RFCTL.EXTEN reads back set; the 82540EM (0x100E) is pinned to legacy descriptors, because it has no RFCTL but QEMU stores the register, so EXTEN reads back set.
r8168.cRTL8111/8168PCIe MMIOC+ mode, 64-entry RX ring, polled.
ne2000.cRTL8029ISA / QEMU PCISimple DP8390 path used by make run-net.
asix.cAX88772USB bulkRuns over the USB core; usable on EHCI/xHCI dongles.
rndis.cAndroid USB tethering, QEMU usb-netUSB control + bulkRNDIS INIT/QUERY/packet filter; presents the phone's tethering link as an Ethernet netdev.
wifi.cIntel 7265D / 3165 (Chromebook), 6200 / 6300 (X201), Realtek RTL8821AU USB stickPCIe (firmware) or USBOpen and WPA2-PSK/CCMP; firmware loaded on first use; link down until wifi connect.

The management NIC used by netlog and netkexec prefers the ASIX dongle so a direct debug link survives netdev e1000e; otherwise it falls back to the active driver. netregs dumps registers and decoded interrupt status; netloop runs a PHY loopback self-test; netreset re-initialises the active NIC.

Link & IP layer

The static default address is 192.168.178.240. At boot, when the active NIC reports a physical link, a DHCP client runs with a 4-second budget (requesting the current address); if no server answers, the static address stays, and a cable that is not plugged in skips the wait so the saved WiFi network can be tried. 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.

DHCP, DNS & NTP

DHCP

dhcp.c is a minimal client: DISCOVER → OFFER → REQUEST → ACK. It learns the mask, gateway and DNS server (option 6), and dhcp re-runs it on demand. The configuration is retained across kexec through the boot-info BOOTINFO_FLAG_NET fields.

DNS

dns.c 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. netdns shows or sets the server; host <name> resolves. Numeric hosts skip DNS entirely.

NTP

ntp.c 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 pool.ntp.org. 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 struct sys_datetime (with the 2036 era wrap handled). SYS_NTP_SYNC returns that value to ring 3; the Date & Time editor then writes it through SYS_RTC_SET. The service owns the raw receiver for the duration, so it reports SYS_NTP_EBUSY while another raw command or a TCP client is active.

NTP is unauthenticated. 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.

TCP

tcp.c implements a small client table, not a general socket layer: each process may hold one connect/send/receive/ close connection, and up to TCP_CLIENT_MAX (twelve) connections can be active. Every connection owns a receive queue (64 KB from the frame allocator, with 32/16 KB fallbacks), 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.

New SYNs and data are also handed to tcp_srv_input() from the active connection's receive/send poll loops, not only between requests, so parallel gvfs clients make progress.

TLS 1.3

tls.c is a ring-3 client with a deliberately narrow cipher suite: TLS_CHACHA20_POLY1305_SHA256 and X25519 only. It is stream-oriented over the existing TCP connection and prints the leaf SHA-256 fingerprint for manual comparison.

Do not treat HTTPS as secure authentication. 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.

sys_net ABI & ownership

sys_net.c 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.

Netconsole & netkexec

netlog.c mirrors the serial console and terminal output to UDP port 19290. The mirror is on by default and broadcasts; netconsole host <laptop-ip> narrows it, netconsole off/on toggles it, and netlog <text> 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.

netkexec.c receives a new kernel/rootfs over UDP port 19288 using KXN2, a runtime command pack using KXNP, and a persistent install using KXI2. Datagrams are acknowledged with the next expected offset and verified with a 32-bit checksum. KXN2/KXNP jump or swap only in RAM. KXI2 carries a 16-byte target name; the board writes P2, then the P1 kernel, patches the exact kernel_sectors, verifies the disk, sends ACK_INSTALLED/ACK_INSTALL_FAIL, and jumps. It never touches P4 (/data) or the MBR. On the host, make netmon, make net-dev and make net-install wrap these protocols.

HTTP clients

The browser's helper requests gzip; inflating a multi-megabyte page in the UI process uses an inflate progress hook that pumps the UI while decoding.

Chat client & OIDC login

chat (ucmd_chat.c) is a native client for Cloudron Chat built on uhttp, the cookie jar, the ujson.c arena JSON parser (fixed node pool, escapes, surrogate pairs) and ngui. The web login is a Vue ES-module SPA the browser cannot run, so chat_login.c drives the API underneath:

  1. GET <server>/auth/login follows the redirect to the Cloudron OIDC provider's /openid/interaction/<uid> page, collecting the PKCE pre-session cookie on the Chat host and the interaction cookies on the provider.
  2. The page's <script id="cloudron-config"> JSON names a relative submitUrl (a plain "submitUrl":"…" scan is the fallback). No config means external SSO: the client offers the cookie screen.
  3. POST submitUrl {"username","password","totpToken"} answers 401 with a message, {"twoFactorRequired":true,"totpRequired":true} (the client asks for the code and reposts), totpRequired:false (passkey-only: cookie screen) or {"redirectTo"}.
  4. Following redirectTo ends at /auth/callback on the Chat host, which sets connect.sid. The consent interaction on the way is a bare auto-submit form (no cloudron-config): its <form action="/openid/interaction/<uid>/confirm"> is posted like the web UI does, and an /abort form or page means the account has no access. GET /api/me validates the session.

The password lives only in the form field and the request buffer; both are wiped after the attempt. The Chat host's cookie header is saved with the server address in /share/chat.cfg (RAM-only; another path can be given as the argument or on the login screen) and is re-saved when the server rolls the cookie. The saved cookie is a bearer credential. Passkey and external-SSO accounts paste a connect.sid cookie from a signed-in browser instead.

There is no WebSocket: the open conversation is polled with GET /api/channels/:id/messages?after=<newest> every 2 s (5 s while the window is unfocused) and the directory (/api/channels, /api/dms) every 12 s (20 s), and polling waits 1 s after keyboard or pointer input. Errors back off 2/5/10/30 s. Sends carry a clientId so a retried POST cannot duplicate a message. An open TCP socket pauses the board's netkexec watcher, so the client only keeps its keep-alive connection while its window is focused and the user was active in the last 30 s; otherwise it closes it after each poll. Other clients see the NebOS user as offline (presence is WebSocket-based).

Security posture

SurfaceStateConsequence
TLS certificatesNot verifiedEncryption without authentication; MITM is undetected.
TLS DRBGWeak (RDTSC/ticks/MAC)Not suitable for high-value secrets.
WebDAVNo authenticationAnyone on the LAN can read mounts and write /share.
Chat sessionCookie saved in /share/chat.cfgA bearer credential in RAM until sign-out; the password is sent over unverified TLS and never stored.
WiFi WPA2PSK/CCMP, handshake in ring 3The SNonce comes from the weak TLS DRBG. The PTK/replay are kept in the kernel (SYS_WIFI_SET_PTK/SYS_WIFI_GET_PTK) and fetched by the wifi __keep helper by connection ID for group rekeys; no WPA3/PMF.
Saved WiFi credentialsPlaintext /data/WIFI.CFGThe SSID and passphrase are stored in an 8.3 FAT file so wifi autoconnect can reconnect at boot; anyone who can read the disk can read the passphrase. wifi forget removes it.
NTPUnauthenticated SNTPAnyone who can answer for the server name can set the clock.
NIC ownershipRaw lease for packet commands; shared TCP client tableRaw commands are mutually exclusive; up to twelve processes can hold one TCP connection each. A killed owner is force-released.
Kernel/user isolationNone (identity map)A ring-3 bug can reach any mapped kernel page.

Source map