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/1.2 · X25519/P-256 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/1.2 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 right top-bar status area (network, battery, clock and temperature) is one button that opens ucmd_netmenu.c, the control panel. The network settings stay collapsed until its Network pill is clicked; the section then 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 popover 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 control panel 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) adds the network to a most-recently-used list of up to WIFI_CFG_MAX (16) SSID/passphrase records in /data/WIFI.CFG on the persistent NEBOSDATA partition. The control panel marks every scanned SSID that is in the list as saved, joins it with the stored passphrase without asking again, and its Saved view lists the records with a Forget button each. The wifi saved command prints the same list and wifi forget [ssid] removes one network (or all of them without an SSID).

After the boot DHCP attempt and the storage scan, the bootscan thread 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 scan and join the strongest network present whose SSID is in the saved list, trying the other saved networks found if one fails and rescanning once after three seconds. An existing WiFi link is left alone. The file is a plaintext 8.3 FAT file (one list header plus fixed-size records, most recently used first); no BSSID is stored, so the strongest AP advertising a saved 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/8168 family (RTL8111E on the 970A-DS3P)PCIe 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 and 1.2

tls.c is a ring-3 client with a deliberately narrow cipher set: TLS 1.3 TLS_CHACHA20_POLY1305_SHA256 with X25519, plus a TLS 1.2 fallback for servers without 1.3. 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. While the receive owns the NIC it keeps answering ARP/ICMP for that NIC, so the host's neighbour entry cannot expire in the middle of a long upload; the host gives up after 10 s without the offset advancing and reports a checksum rejection as a failure. 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 /data/CHAT.CFG when the persistent /data volume is mounted, or /share/chat.cfg (RAM-only) otherwise; another path can be given as the argument or on the login screen, and a session left in the old /share file is copied over once. The config 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.

Message image attachments, link-preview images and profile pictures are fetched through the same uhttp connection and cookie jar, one per main-loop pass, and decoded by the in-tree image library (PNG, JPEG, GIF first frame, BMP, TGA, PNM, ICO and PAM). Message images are scaled to at most 480x320 and cached in a 16-entry, 6 MB LRU; avatars are 32x32 with a 64-entry cache and a circular alpha mask, and fall back to initials until they load or when the account has no picture. The fetch is capped at 4 MB and the decoder at 4 MP / 12 MB of scratch.

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 /data/CHAT.CFG, or /share/chat.cfg without a /data mountA bearer credential on disk while /data is mounted, otherwise 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.CFGUp to 16 SSID/passphrase pairs are stored in an 8.3 FAT file (most recently used first) so wifi autoconnect can join any known network at boot; anyone who can read the disk can read the passphrases. wifi forget [ssid] and the menu's Saved view remove records.
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