■ erXos · release notes
01 / 0.1

erXos 0.1, a preview.

0.1 is a development preview of erXos for the Raspberry Pi 4 and QEMU virt.

The downloads, and the build record beside each, name the commit they were built from and the SHA-256 of every file.

02 / Works

What works.

  • Erlang all the way up. Above the kernel, the system is Erlang on OTP 29 in user mode: the system services, the drivers, the network stack, the file systems and the shell.
  • Domains. Storage, network, display and each login session run their own Erlang runtime in an address space of their own, and message each other as Erlang nodes do.
  • A network stack in Erlang. A redesign of FreeBSD's: Ethernet, ARP, IPv4, IPv6 neighbour discovery, ICMP, UDP, TCP and DHCP, with ifconfig, ping, host and gen_tcp.
  • Drivers in Erlang. Each driver is a supervised Erlang process over a thin device shim: the serial console, virtio block, net, gpu, keyboard and tablet on QEMU, and the SD card, GENET Ethernet and framebuffer on the Pi 4.
  • SSH in Erlang. OTP's SSH daemon logs root in to the command shell over the network.
  • HTTPS. OTP's ssl and inets, with a trust store, in every domain.
  • Network time. ntpd sets the clock at boot, and ntpctl steps it or shows its status.
  • Graphics. A window server serves windows as files; clients draw with Plan 9's draw protocol, and apps build their interface from LVGL widgets.
  • The kiosk. The screen shows a clock and a panel of live quotes fetched over HTTPS, on QEMU's virtio-gpu and on the Pi's HDMI0 through the firmware's framebuffer.
  • rc, in Erlang. The command shell has job control, text pipes and commands that follow FreeBSD's output (ls, grep, ps, top, dmesg and more), and runs native programs in pipelines with them. erl starts the Erlang shell.
  • A live machine. /proc, erx:i() and erx:trace/1 show processes, domains and kernel objects as they run.
  • Verified system files. The system partition is an EROFS image whose blocks are checked against a dm-verity tree as they are read.
  • Reproducible. The same commit builds byte-identical images.
  • SSH to rc. ssh -p 2222 root@HOST gives root's command shell, with ps, top and erl. Your key comes from authorized_keys on the card's ERXOS volume, which the first boot copies into /root/.ssh/authorized_keys.
  • The clock. On QEMU virt it is read from the machine's real-time clock at boot. The Pi 4 has none, so its clock starts at the build's date at each boot, which lets HTTPS work at once, and ntpd then sets it from pool.ntp.org. Root can set it with date.
  • Files that survive. /data is a littlefs volume on the card: a file survives a power cut once it is closed. Home directories are /root and /home/NAME.
  • Recovery. A fault of the system domain resets the board, which boots back to the kiosk. On the Pi 4 the hardware watchdog resets a hang of the kernel or the root within about 4 seconds.
  • Doom. Type doom in rc. It is an example, not part of erXos.
03 / Start

Getting started.

The steps are in the README's Getting started. In short:

  1. Download the Raspberry Pi 4 card, check its SHA-256, and write it to a microSD card of at least 4 GB (xz -dc card.img.xz | sudo dd of=/dev/rdiskN bs=4m on macOS). The Pi's bootloader must be from 2022-12-01 or later.
  2. Copy your public key, an ssh-ed25519 line, to a file named authorized_keys in the root of the card's ERXOS volume. On macOS, insert the card again and run cp ~/.ssh/id_ed25519.pub /Volumes/ERXOS/authorized_keys, then diskutil eject /Volumes/ERXOS. The published images carry no key, so without this file no login works. The first boot copies the keys into root's /root/.ssh/authorized_keys, and from then on SSH reads only that copy.
  3. Put the card in the Pi with an Ethernet cable and a screen on HDMI0, and power it. The banner and the % prompt appear on the serial console (115200 baud) within a minute, then the kiosk on the screen.
  4. ssh -p 2222 root@HOST, then date to see the time ntpd set.

For QEMU, from a clone run make pack PLATFORM=qemu-virt, then tools/erx boot --medium build/production-image/qemu-virt/medium.img: QEMU shows the display in its window with the virtio keyboard and tablet, the serial console is on your terminal, and your port 2222 reaches the guest's SSH. Add --print for the plain qemu-system-aarch64 command. The page does not offer the medium for download yet.

04 / Limits

Known limitations.

Security. Each item names where the project records it.

  • Trusted code only. Domains run in address spaces of their own, but a development build carries development-only grants, and its isolation is hardened and reviewed only for 0.2.
  • SSH runs in root's session. OTP's SSH daemon, its transport and authentication included, runs with root's authority, so a flaw in it that is reached before login is root's session. A separate SSH domain comes in 0.2 (stages).
  • The login keys are readable in root's session. Root's session holds a read-only grant of the card's keys for its first-boot import, until 0.2's SSH domain removes it (H8).
  • The host key may be weak. When a boot's random seed is only a counter, the SSH host key made at first boot comes from a weak seed (host keys).
  • Network time is not authenticated. The NTP server ntpd uses, or anyone on the path to it, sets the Pi's clock, so it can hold it at the build's date and keep a certificate that expired after the build accepted for the whole boot (time).
  • DMA. The evidence of how each board's firmware leaves its DMA-capable devices at handover is not recorded.

Behavior.

  • The Pi 4's clock is approximate until ntpd sets it. It starts at the build's date at each boot, and ntpd sets it from pool.ntp.org once the network is up. Until then, and for as long as no NTP server answers, a certificate that expired after the build is still accepted, and the time ntpd sets is not authenticated (Security above); root can set the time with date, which is not kept across a reboot.
  • SSH is on port 2222, not 22, and gives an interactive session only: a command given to ssh is refused.
  • Power-off. On the Pi, halt stops the board; cycle the power to start it again.
  • Recovery gaps. A hang before the root's watchdog starts stays hung until the power is cycled, and a kernel panic that early loops instead of resetting.
  • Updates are by reflashing the card, which erases /data. There is no update service and no trial boot.
  • The Pi has no USB keyboard in 0.1, so Doom there runs its demo loop, slowly, and no WiFi.
  • Left to 0.2 and later. The release build without the development banner, a login on the console, untrusted apps, the vault, installing an app at run time (unless it lands first), the desktop and toybox's applets.
05 / Licenses

Licenses.

erXos's own code is BSD-2-Clause. Every image carries a NOTICES file with the third-party notices. The Pi 4's device tree is GPL-2.0, shipped with its source; the Raspberry Pi firmware is under Broadcom's license. The kernel, a modified Fiasco, is MIT, except its debugger's object listing, which is GPL-2.0; the debugger is built in for this preview. The browser demo's notices are in v64/NOTICES.txt. Imported source trees in the repository each keep their notices and an ORIGIN.md with where they came from. Doom is GPL-2.0-or-later and its Freedoom data BSD-3-Clause; its source is erXos's fork of doomgeneric at commit 5d58740fb0022a43d6bb9066d535768c220f43aa, the one the images are built from. Each download links the erXos source it was built from.