■ erXos · release notes
01 / 0.1

erXos 0.1, a preview.

0.1 is a development preview for the Raspberry Pi 4 and for QEMU virt. It is not a release for use.

Every boot prints development build: trusted code only. Run only code you trust on it, on a network you trust. Nothing in a development build enforces isolation between its domains, and the limitations below say what else a user of 0.1 is exposed to.

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.

  • 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.
  • SSH to rc. ssh -p 2222 root@HOST gives root's command shell, with ps and top, and erl's erx:domains() lists every domain of the machine. Your key comes from authorized_keys on the card's ERXOS volume, which the first boot copies into /root/.ssh/authorized_keys.
  • The clock. It starts at the build's date at each boot, so HTTPS works at once; on the Pi 4 ntpd then sets it from pool.ntp.org, and root can set it with date.
  • Files that survive. /data is a littlefs volume on the card: a file you synced survives a power cut. 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. The Pi 4 card and the QEMU release medium carry Doom: type doom in rc; the browser demo does not. On QEMU it takes keys from the virtio keyboard; on the Pi, which has no keyboard in 0.1, it runs its demo loop. 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. 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 set the time.

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. A development build enforces no isolation between domains (the downsides of Fiasco).
  • Any key in authorized_keys is root. The key opens root's rc over the network.
  • 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).
  • Whoever can write the card can become root. Before the first boot they can add their key to the card's authorized_keys, and at any time they can write root's home copy on the data partition.
  • A root login can keep itself. Root's keys are /root/.ssh/authorized_keys, which root's session can write, so anything running as root, or anyone logged in as root, can add a key that lasts across boots (login keys).
  • 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).
  • DMA. The evidence of how each board's firmware leaves its DMA-capable devices at handover is not recorded.

Behavior.

  • The clock is approximate. It starts at the build's date at each boot and no network time sets it. Until root runs date, a certificate that expired after the build is still accepted, and you set the time again after every boot.
  • SSH is on port 2222, not 22, and gives an interactive session only: a command given to ssh is refused.
  • Requested power-off. On the Pi a requested power-off halts the board in the firmware and the watchdog restarts it about 4 seconds later. Only cutting the power turns it off.
  • 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 only runs its demo loop, 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.