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.
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.
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), 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.
| Driver | Hardware | Transport | Notes |
|---|---|---|---|
| e1000e.c | Intel 82540EM, 82577LM, 82578, 82579 | PCI MMIO | PCI 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.c | RTL8111/8168 | PCIe MMIO | C+ mode, 64-entry RX ring, polled. |
| ne2000.c | RTL8029 | ISA / QEMU PCI | Simple DP8390 path used by make run-net. |
| asix.c | AX88772 | USB bulk | Runs over the USB core; usable on EHCI/xHCI dongles. |
| rndis.c | Android USB tethering, QEMU usb-net | USB control + bulk | RNDIS INIT/QUERY/packet filter; presents the phone's tethering link as an Ethernet netdev. |
| wifi.c | Intel 7265D / 3165 (Chromebook), 6200 / 6300 (X201) | PCIe (firmware) | Open 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
- Ethernet decode recognises IPv4, ARP and IPv6 frame types (IPv6 is not implemented).
- ARP resolves a next hop with three tries, one second apart;
net_arp_resolve()polls the active NIC and the caller must own it. Cache entries live five minutes and their age slides on every hit, so a DNS or gateway entry does not expire during a long page load. Stack waits drain the receiver in short bursts so a full driver ring can reset and recover. - Routing sends off-subnet traffic to the gateway when one is known;
net_next_hop()is shared by ping, DNS and TCP. - ICMP echo backs
ping, with ARP resolution and round-trip timing. - UDP has send and parse helpers; DNS, DHCP, NTP and netlog are its users.
- Checksums use the Internet one's-complement sum, with a TCP pseudo-header variant.
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.
- Demultiplexing.
net_pump()feeds every received frame totcp_client_input(), which matches the destination IP and port pair and updates that connection's sequence state. - MSS / window. Our MSS is 1460 bytes and clients advertise up to a 64 KB window (the connection's receive queue; no window scaling). At a 30 ms round trip that is ~2 MB/s per connection instead of the old 4 KB window's ~133 KB/s.
- Close.
tcp_client_close()sends FIN and frees the slot immediately instead of waiting for the peer's FIN; every send is synchronous, so no data is outstanding, and a late FIN matches no client and is dropped.uhttpalso skips the TLS close_notify when a redirect leaves the origin, so a redirect hop costs no extra round trips. - Retransmit. A 500 ms retry timer with a small retry count carries the connection through loss; there is no full congestion-control state machine.
- Listener. 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
tcp_srv_accept()runs. - Bursts. Responses go out in up to four-segment bursts with a cumulative ACK, rather than one segment per ACK.
- No keep-alive. 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.
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.
- Not verified. Phase A provides encryption without authentication; a MITM is undetected.
curlwarns, and the browser marks HTTPS as unverified. - Weak DRBG. tls_rng.c mixes RDTSC jitter, ticks and the MAC; it is not a hardware-backed CSPRNG.
- Host tests. The crypto files are pure freestanding C with host vectors (
make test-crypto,tls_test.c).
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.
- Raw owner.
SYS_NET_ACQUIREtakes 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. - Mode gates. A raw acquire fails while any TCP client socket is open, and
SYS_TCP_CONNECTfails while a raw owner exists. This keeps packet commands and the shared pump from stealing each other's frames. - Reaper safety. If a raw owner dies,
sys_net_reapforce-releases the receiver throughnetdev_release_all(); sockets and a pending DNS query owned by the dead process are closed separately. - Wait semantics. Stack waits now yield with
process_sleep_ms()and re-enable interrupts for driver TX timeouts; the syscall stub enters with interrupts off. - One connection per process. The connection state lives in the kernel, keyed by the calling pid.
SYS_TCP_CONNECT/SEND/RECV/CLOSEkeep their ABI, so uhttp and the TLS layer did not need a socket handle.
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
- curl —
http://orhttps://GET with DNS, ARP, redirects (up to five hops), chunked decoding, status/headers/body dump and a TLS warning. - uhttp — shared ring-3 HTTP/1.1 client used by curl, the browser and chat: URL parsing, redirects (up to eight hops; 1 KB paths and 1.5 KB header lines, enough for OIDC URLs), chunked decoding, timeouts and TLS. Requests and bodies of any size are split into pieces the transport accepts (1024-byte TLS records, one peer MSS for plain TCP). Optional per-request fields set the
Acceptheader, extra header lines and a cookie jar; 1xx/204/304 responses are treated as bodyless so keep-alive does not wait for an idle timeout. - uhttp_cookie — the cookie jar (uhttp_cookie.c, 24 cookies of up to 768 bytes). Every
Set-Cookie, including those on redirect responses, is stored; matching cookies are sent on every request and redirect hop. Cookies are host-only (Domainis ignored),Pathis a prefix match,Securecookies only go over https, andMax-Age<=0or a 1970Expiresdeletes a cookie. The jar outlives the connection, so a cross-origin redirect that reconnects keeps the session. - browser — runs network fetches in up to four headless
curl __serveworkers, each with its own request/body/meta files under/share/bf<session>_<slot>*. The session id comes from the browser pid, so multiple browser windows do not share queue files. Stylesheet and external-script bodies are downloaded in parallel but parsed/executed in document order; one image starts before the script phase, and the remaining 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; idle helpers stay warm across navigations (a cross-origin job just drops the old connection, and only busy helpers are killed), and helpers also exit after ten idle seconds or when the window loses focus. A DNS failure is retried once after tearing the helpers down. The helpers' DNS/TLS log lines go to a private tty that the browser drains and discards from every poll loop; a full tty ring blocks its writers, so an undrained one used to hang every helper after about sixteen TLS connections. The status bar reports the page's total, header and first-byte times. - websrv — the server side, speaking HTTP/1.1 + WebDAV over the TCP listener; see Filesystems → WebDAV.
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:
GET <server>/auth/loginfollows 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.- The page's
<script id="cloudron-config">JSON names a relativesubmitUrl(a plain"submitUrl":"…"scan is the fallback). No config means external SSO: the client offers the cookie screen. 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"}.- Following
redirectToends at/auth/callbackon the Chat host, which setsconnect.sid. The consent interaction on the way is a bare auto-submit form (nocloudron-config): its<form action="/openid/interaction/<uid>/confirm">is posted like the web UI does, and an/abortform or page means the account has no access.GET /api/mevalidates 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
| Surface | State | Consequence |
|---|---|---|
| TLS certificates | Not verified | Encryption without authentication; MITM is undetected. |
| TLS DRBG | Weak (RDTSC/ticks/MAC) | Not suitable for high-value secrets. |
| WebDAV | No authentication | Anyone on the LAN can read mounts and write /share. |
| Chat session | Cookie saved in /share/chat.cfg | A bearer credential in RAM until sign-out; the password is sent over unverified TLS and never stored. |
| WiFi WPA2 | PSK/CCMP, handshake in ring 3 | The 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 credentials | Plaintext /data/WIFI.CFG | The 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. |
| NTP | Unauthenticated SNTP | Anyone who can answer for the server name can set the clock. |
| NIC ownership | Raw lease for packet commands; shared TCP client table | Raw commands are mutually exclusive; up to twelve processes can hold one TCP connection each. A killed owner is force-released. |
| Kernel/user isolation | None (identity map) | A ring-3 bug can reach any mapped kernel page. |
Source map
netdev.c,netdev.h— registrye1000e.c,r8168.c,ne2000.c,asix.c,rndis.cwifi.c,iwl_fw.c,iwl_mvm.c,iwl_dvm.c,iwl_trans.c— Intel 7265D/3165 and 6200/6300 WiFiwpa.c,wpa_crypto.c,ucmd_wifi.c— WPA2-PSK supplicant and thewificommand (make test-wpa)ucmd_netmenu.c,wifi_cfg.h— top-bar network menu and its staged WiFi connect requestnet.c,net.h— ARP cache/ICMP/UDP/IPnetcore.c,netcore.h— shared receive pump and IRQ helpersdhcp.c,dns.c,ntp.ctcp.c,tcp.h— client table + listenertls.c,tls_*.c— TLS 1.3sys_net.c— ring-3 servicenetlog.c,netkexec.cuhttp.c,ucmd_curl.c,ucmd_websrv.cuhttp_cookie.c,ujson.c— cookie jar, JSON parserchat_login.c,ucmd_chat.c— OIDC login driver, chat clienttools/mock_chat.py,tools/qmp_chat_test.py— mock server, QEMU end-to-end test