An independent Linux distribution whose goal is to be as boring as possible for the person using it. Three things about it are new; everything else is ordinary (glibc, systemd, a usr-merged file system, GNOME).
- Transactional upgrades on a system that is not immutable. An upgrade is applied to a btrfs snapshot and takes effect on reboot. If the new system does not boot, the machine returns to the previous one by itself. The running root stays an ordinary writable file system.
- dave, a package manager written in Zig with a PubGrub solver, designed around that update model from the start.
- A security model for root. A privileged process runs only code that the distribution has signed, cannot generate code at run time, and is held to the operations its program declares. One kernel security module enforces it.
The idea of snapshot-based upgrades without immutability comes from Arch-silverblue.
joe Linux builds from source into two systems that boot in a virtual machine:
- a console system, with sudo, an editor, the
manual and ssh, whose upgrade, rollback and recovery behaviour is exercised
end to end by
make test-joe; - a GNOME desktop: GDM, GNOME Shell on Wayland,
Firefox, Files, Terminal, Text Editor, Settings and the usual small
applications (documents, images, video, music, archives, disks, maps,
weather, clocks, calculator), with fonts for most scripts, spell checking
and the common media codecs, and printing, Bluetooth (headsets included)
and mobile broadband.
make test-desktopstarts every one of them, with the security module both logging and enforcing. It is laid out like Windows, entirely with upstream GNOME Shell extensions and ordinary settings: a taskbar along the bottom (Dash to Panel) with a start menu (ArcMenu) and tray icons (AppIndicator), icons on the desktop (DING), minimize and maximize buttons, Papirus icons, GTK 3 applications styled to match the rest (adw-gtk3), and joe's teal accent and wallpaper. Each piece is an ordinary extension or setting, whichgnome-extensions disableor Settings turns back to plain GNOME.
The repository also provides packages beyond those images, a dave install
away. That covers development tools and
toolchains (gdb, valgrind, Go, Zig, OpenJDK, GHC, uv, ripgrep, ShellCheck),
servers (PostgreSQL, BIND, unbound, nginx, Samba, NFS, WireGuard, nftables)
and applications such as LibreOffice, GIMP, Inkscape, VLC, Audacity,
Remmina and KeePassXC.
Optional servers are off by default on new systems. After configuring one,
use systemctl enable --now UNIT to opt in; installing its package alone
does not start it. Core services, SSH and the GNOME desktop have explicit
defaults.
The desktop can be lived in as a virtual machine that keeps its disk: the first boot asks who you are, and upgrades come from the build machine. See Living in it. It can also be installed, from a live medium whose installer puts it beside Windows (or another system) in free space, or on a whole disk; see Installing. Real computers are a work in progress; see Not done yet.
dave install tree Installs now. The system as it was is kept as a
bootable deployment first, so there is a way back. When
more would change than you named (dependencies come in,
other packages are upgraded or removed), dave shows the
plan and asks first; -y answers for you.
dave upgrade Works out and downloads the upgrade and proves it applies
cleanly to a copy of the system. Changes nothing you can
see. The upgrade is applied when the machine shuts down.
dave upgrade --check What an upgrade would change, without preparing it.
dave rollback The previous system starts on the next boot, and on every
boot after it. Says so if someone has been given an
account since that system was made: accounts live in
/etc, which belongs to each system.
dave status What is running, what will start next, what is pending.
dave info tree Installed and available versions, licence, sizes, what it
needs, what needs it, and why it is installed.
dave search a b The packages matching every word; name matches first.
dave why zlib The shortest chain from something you asked for.
dave owns /bin/sh The package a file belongs to, resolving /bin and /lib
as the system does. dave files lists a package's files.
dave help install Every command explains itself; dave(8) has the rest, and
bash, zsh and fish complete commands and package names.
Only changing the system needs root: status, list, info, search, files, owns,
why, deployments and upgrade --check work for everyone. Before anything
changes, dave shows the plan:
Install
babl 0.1.128-r1 (dependency)
gegl 0.4.72-r2 (dependency)
gimp 3.2.8-r2
3 to install. 27.0 MiB to download; 112.4 MiB more disk space will be used.
Continue? [Y/n]
On a terminal there is colour, and a line that shows downloads and progress
as they happen; NO_COLOR turns the colour off. Output to a pipe or a file
stays plain lines.
When a request cannot be satisfied, dave says why:
dave: this cannot be done.
Because editor 1.0-r1 depends on libui >=2 and editor has no version other than 1.0-r1, editor requires libui >=2.
And because no version of libui matches >=2, editor cannot be installed.
So, because you asked for editor, what you asked for cannot be installed.
Deployments. The root file system is a btrfs subvolume joe/deploy/<id>.
/home and /var are separate subvolumes shared by every deployment; /etc
belongs to the deployment, so configuration rolls back with the system. dave's
database lives under /usr/lib/dave/db, inside the deployment, so each
snapshot carries the database that describes exactly its own contents.
Upgrades lose nothing. dave upgrade only records a plan. At shutdown,
dave-finalize.service snapshots the root as it is at that moment and
applies the plan to the snapshot. Anything changed between dave upgrade and
the reboot is therefore in the new system; there is no merge step. The boot
entry for the new deployment is written last, so a power cut at any earlier
point boots the old system with the upgrade still pending. A newer
systemd-boot in the upgraded system replaces the one on the EFI system
partition at the same moment, and only ever a newer one, because every
deployment is started by the same loader. Package triggers run in the new
deployment with an empty tmpfs on /var and /home, where the shared
subvolumes will be mounted, so nothing they write is left hidden under them.
The boot loader keeps the health record. Each deployment has one
systemd-boot entry. Entries are ordered by a priority that is bumped whenever a
deployment is chosen, so activating an upgrade and rolling back are the same
operation, and a rollback is persistent. A new deployment starts with three
boot attempts. dave-boot-check.service runs before systemd marks the boot
good; if the check fails the machine reboots, and when the attempts run out
systemd-boot returns to whatever was chosen before. A root that cannot be
mounted at all takes the same path through the kernel's panic timeout.
Packages are zstd-compressed tar files beginning with a manifest that is authoritative for all file metadata. Repositories are signed with Ed25519; the signed index carries the SHA-256 of every package. They are fetched over HTTPS (checked against the system's certificate store), HTTP, or from a local directory; the signature is what is trusted either way. Packages have no install scripts: a package may declare a trigger (rebuild the linker cache when libraries change), and that is all.
Seals. Every packaged file that is not configuration is sealed when it is installed: fs-verity makes its contents immutable and gives the kernel a digest of them, and an extended attribute carries a signature over that digest together with the operations the package declares for the file. The public half of the signing key is compiled into the kernel. A sealed file can be replaced or deleted, never modified.
What the security module does. It concerns privileged processes only: any user id of 0, or any capability, in the initial user namespace. Ordinary users are not affected.
-
Sealed code only. The program, every library it maps, every kernel module it loads and every script it runs must be sealed. bash and Python ask the module before reading a script file; commands typed at a prompt and
-cstrings are not files and are allowed. -
No code made at run time. No anonymous executable memory, no writable executable mappings, no making modified memory executable. A just-in-time compiler cannot work under these rules, so none can run as root. A debugger cannot write another process's executable pages either: ptrace, process-vm and
/proc/PID/memwrites are covered as well asmmapandmprotect. -
Declared operations. A recipe states what its privileged programs do: which capabilities, whether the network, where they write, what they run.
.operations = .{ .{ .programs = .{"usr/bin/mount"}, .allow = .{ "mount", "cap:sys_admin" } }, },The declaration is part of what is signed, and the module refuses the rest.
root-ipccovers signals and SysV IPC between root processes.noneis an explicit empty declaration. A program no declaration covers isundeclared: anallcaller gives itall, and otherwise it is reported and refused when enforcing. Global root stays confined when it creates a user namespace. A process whose only global privilege is its capability set cannot create one, because replacing that set would discard its confinement.
The module logs by default and enforces when booted with joe=enforce. One
consequence worth knowing: a root shell does not read /etc/profile or
~/.bashrc, because files you can edit are not sealed.
Today the distribution declares all for the programs where privilege
starts: systemd's PID 1 and the executor that starts every service, root's
bash, sudo, dave, the programs the kernel itself starts (modprobe,
systemd-coredump, request-key), and every set-uid program. Everything else
is undeclared, so it acts with the authority of the shell or service that
runs it. Narrower declarations for each service are the next step.
The details are in the source, which is commented for readers: packages/linux/joe-lsm/joe.c, dave/src/seal.zig, dave/src/deploy.zig, dave/src/boot.zig, dave/src/txn.zig, dave/src/solver/pubgrub.zig.
GitHub Actions runs dave's existing unit tests on pull requests and pushes to
main, using Zig 0.17.1 on Ubuntu. To run the same checks locally:
cd dave && zig build test --summary all (requires zstd). Tests that need
btrfs or fs-verity skip when those features are unavailable. This workflow
does not run the command-line or VM suites below.
Requirements on the build machine: Zig 0.17.1, a C toolchain, QEMU with KVM, OVMF firmware, btrfs-progs 6.12 or newer, bubblewrap, and a build directory on btrfs. Nothing needs root.
make test unit tests and command-line tests, in seconds
make test-boot-contract what the design assumes about systemd-boot, in a VM
make test-deployments upgrade, rollback, power loss and recovery, in a VM
Those two VM tests use a scaffold: a throwaway image made from the build machine's kernel and a stock Arch userspace, so the deployment mechanics can be exercised without building a distribution first. Nothing from it ships.
make bootstrap cross toolchain and temporary tools
make packages every recipe in packages/, into build/repo
make image a bootable image, build/images/joe.img
make run boot it in QEMU on this terminal (leave with Ctrl-A X)
make test-joe the same deployment tests on that image
make test-security the security module's three rules
make audit-security package seal and declaration audit
make desktop-image a GNOME image, build/images/joe-desktop.img
make run-desktop boot it in a QEMU window (user joe, password joe)
make test-desktop session, every application, a web page; logging and enforcing
Building the desktop packages takes several hours the first time; LLVM, Rust, Firefox, Node.js and SpiderMonkey are the long ones.
These are test images: root is logged in on the serial console without a password, and the desktop image has a ready-made user, because that is how the tests look inside. The release image below has neither.
make iso build/images/joe-live.iso, the installation medium
make test-live boot it as a CD and as a USB stick, in a VM
make test-install install from it onto an empty disk, then boot that
The medium is a hybrid ISO for UEFI computers (Secure Boot off): write it to a USB stick or attach it to a virtual machine as a CD. It starts a GNOME session from a compressed image of the desktop (SquashFS, xz), with a layer in memory for changes, and opens the installer. The installer asks which disk to use, and how:
- Beside another system, in the disk's largest free space (22 GB or more). Nothing that is there is moved, shrunk or erased, so the room is made first, in the other system: Windows' Disk Management shrinks its volume. joe shares the disk's EFI system partition, adding only systemd-boot to it (never replacing Windows' files, the firmware's fallback loader included), and keeps its kernels and boot entries on a boot partition of its own (XBOOTLDR) at the start of the free space. The boot menu then lists joe and Windows, which systemd-boot finds by itself, for five seconds; joe starts unless another is chosen.
- On the whole disk, erased: a new GPT with an EFI system partition and a btrfs root laid out exactly as an image's.
The packages are installed from the medium itself, by one dave transaction, and sealed as they are installed. The medium carries each package once: the transaction copies it out of the live session's own root image, where it is installed already, and checks every file against the package's manifest, as it would a file from a package. The few files the live session changes (its host name, its automatic login, the accounts it adds) are on the medium as packaged as well. The installed system boots without an initramfs, like every joe system, and its first boot runs GNOME's initial setup.
The installer (installer/) is a Qt Quick front end; all of its work is done by
dave install-system, which can be run by hand on the medium:
dave install-system --list the disks, and what each allows
dave install-system --disk /dev/nvme0n1 --beside install in its free space
dave install-system --disk /dev/nvme0n1 erase it and install
Images and media are described by specifications in image/*.zon and built by
dave image build; each Makefile target above names one. The build machine
publishes the medium with the repository (see infra/build-machine).
joe's command line, with dave to install the rest, is also a container image
(image/container.zon, an OCI image of one layer):
docker run -it ghcr.io/thejoelinuxfoundation/joe
dave install git
make container builds it from build/repo as build/images/joe-container.tar
(docker load -i or podman load -i it). The published image is built from
the published repository by a GitHub workflow, .github/workflows/container.yml,
run by hand after a release. A container is not a deployment, so dave
installs into it directly, without a snapshot to return to.
A release is named JX-Y-Z, with a stage such as -alpha1 before it
is final:
| Part | Is | In J1-7.3.1-0.2.1-alpha3 |
|---|---|---|
| J | joe, the distribution | J |
| X | the system revision | 1 |
| Y | the kernel's version | 7.3.1 |
| Z | dave's version | 0.2.1 |
packages/joe-release writes the name into os-release and the build machine
names the installation medium after it. Its package version is the revision
and stage alone (1alpha3), which dave orders before the final 1.
make release-image the desktop as a person gets it, build/images/joe-release.img
make test-release its first boot: disk growth, first-run setup, sound, shared folder
make vm a virtual machine with a 64G disk of its own, in build/vm
make run-vm boot it; what you do in it is still there next time
make serve-repo offer build/repo to that machine
The release image has no accounts and root has no password. On the first boot
GDM starts GNOME's initial setup, which asks for a language, keyboard layout
and time zone and creates your account. That account is an administrator (a
member of wheel), so sudo works. The root file system grows to fill the
disk it finds itself on.
make run-vm uses the host's GPU for the guest's 3D when QEMU can (virgl),
gives the guest a sound card, and takes options through VM_ARGS: --share DIR shares a host directory (mount -t virtiofs host /mnt in the guest),
--sound virtio, --no-gl, --memory, --cpus. Delete build/vm to start
again from the image.
To change the system you are running, as its developer:
edit packages/NAME, bump .release in its package.zon
bootstrap/build-packages.sh NAME on the build machine
make serve-repo leave it running
sudo dave upgrade in the virtual machine
reboot
dave install NAME in the machine takes a package from the same place.
The bootstrap follows Linux From Scratch, and the desktop Beyond Linux From Scratch (systemd, development branches), with the same package versions. Recipes are described in packages/README.md.
| Path | What it is |
|---|---|
dave/ |
The package manager and deployment tool |
packages/ |
One recipe per package, and the build order |
bootstrap/ |
Scripts that build the first toolchain and then every package |
system/ |
dave's systemd units |
image/ |
Image and live medium specifications, and the scaffold's scripts |
installer/ |
The graphical installer |
tests/ |
Command-line tests and VM scenarios |
- Declarations for each service. The mechanism of rule 3 is tested, and
the base system's entry points and set-uid programs declare
all, but services still receiveallfrom systemd instead of holding studied declarations of their own.dave repo audit build/repolists the undeclared programs and any invalid or missing seals. - The rest of the trust chain. Kernel modules are checked by the module but not by the kernel's own signature enforcement; there is no kernel lockdown and no Secure Boot, so root can still replace the kernel or its command line. There is no way yet to sign software built on the machine. Interpreters other than bash and Python (awk, sed, perl) do not ask before running a script.
- Real hardware. Firmware, processor microcode, Wi-Fi (through NetworkManager and wpa_supplicant) and the Intel, AMD and NVIDIA graphics drivers are there, but have been tried on few machines. Mesa also supplies Vulkan drivers for Intel, AMD, virtio and software rendering. The lavapipe software path has been smoke-tested; hardware Vulkan remains unverified. Video is decoded on the GPU through VA-API with Mesa's drivers (AMD, nouveau, virtual machines), but Intel's VA-API driver is not packaged. The kernel boots without an initramfs, which is enough for internal disks but not for encrypted or multi-device roots. The installer neither encrypts nor resizes: beside another system it needs free space made beforehand. There is no Secure Boot.
- Desktop gaps. No graphical front end to dave. Only the English (US) locale is built, so that is the one language the first-run setup offers. No HEIF or AVIF images and no mail client. LibreOffice is in the repository but not installed by default.
- Split packages. A package is everything its upstream installs, so the base image carries the compiler because programs need its run-time libraries.
- Builds are not isolated from each other. Every recipe builds in one shared build root. A fresh, minimal build root per package, chosen by the solver, comes later. Fifteen packages fetch their locked Rust, Go or Haskell dependencies from the network while building. Rust, Go, GHC and OpenJDK are each first compiled by a prebuilt compiler: their upstream's, or for OpenJDK the book's. The TypeScript compiler (needed to build one application) is its upstream's already-compiled release, and bun is upstream's binary, repackaged.
- Building dave inside joe. joe packages Zig 0.17.1 now, but the dave package is still the static binary cross-built on the build machine.
- Virtual packages (
provides), and changing the kernel on a running system (usedave upgrade).
joe Linux's own code is under the MIT License. The security module is GPL-2.0-only, as part of the kernel, and the patches to bash, Python and GNOME Settings are under those projects' licences. The recipes follow Linux From Scratch and Beyond LFS. THIRD-PARTY-NOTICES.md has the details, including what to know before distributing an image built from these recipes.