From 5255656258ab8d5db8d59b84045e3b404b079db7 Mon Sep 17 00:00:00 2001 From: Job79 Date: Sat, 21 Nov 2026 20:37:26 +0100 Subject: [PATCH] refactor: style pass, tools tree and fixes from a test build - Follow AGENTS.md style: headers start with the file's name, short notes are full sentences, comments within 80 columns. - Build with mkosi's tools tree, pinned to the image's release (ToolsTreeRelease=%r): rawhide's repositories made the image rawhide. - Incremental builds with mkosi.cache/ for faster local rebuilds. - Hostname= instead of systemd.hostname= on the kernel command line. - mkosi.finalize: bash, no cd, and L+ for /etc/systemd. PID 1 applies the presets at first boot and made /etc/systemd/system, which blocked the link, so /etc/systemd/user (the user's D-Bus) was missing. - Disable homed, userdbd and nsresourced with presets instead of deleting their units. Drop modules the kernel has built in. - mkosi.version adds the git commit to the version. - One dev container per worktree or session in CLAUDE.md. Co-Authored-By: Claude Opus 5.5 --- .gitea/workflows/os.yml | 20 +-- .gitignore | 3 + AGENTS.md | 51 +++--- README.md | 16 +- mkosi.conf | 151 +++++++----------- mkosi.extra/etc/claude-code/CLAUDE.md | 10 +- mkosi.extra/usr/lib/repart.d/50-root.conf | 14 +- mkosi.extra/usr/lib/sysctl.d/50-agent.conf | 7 +- .../usr/lib/systemd/network/80-dhcp.network | 6 +- .../lib/systemd/system-preset/50-agent.preset | 13 +- .../usr/lib/systemd/system/claude-remote.path | 6 +- .../lib/systemd/system/claude-remote.service | 8 +- mkosi.extra/usr/lib/systemd/system/sshd.path | 9 +- .../usr/lib/sysupdate.d/10-usr.transfer | 7 +- .../lib/sysupdate.d/11-usr-verity.transfer | 6 +- .../usr/lib/sysupdate.d/20-uki.transfer | 6 +- mkosi.extra/usr/lib/sysusers.d/agent.conf | 6 +- mkosi.extra/usr/lib/tmpfiles.d/agent.conf | 7 +- mkosi.finalize | 50 +++--- mkosi.repart/00-esp.conf | 5 +- mkosi.repart/10-usr.conf | 10 +- mkosi.repart/11-usr-verity.conf | 4 +- mkosi.repart/20-usr-b.conf | 5 +- mkosi.repart/21-usr-verity-b.conf | 5 +- .../etc/yum.repos.d/claude-code.repo | 8 +- mkosi.version | 15 +- 26 files changed, 205 insertions(+), 243 deletions(-) diff --git a/.gitea/workflows/os.yml b/.gitea/workflows/os.yml index ff54d16..3c3e036 100644 --- a/.gitea/workflows/os.yml +++ b/.gitea/workflows/os.yml @@ -1,8 +1,6 @@ -# OS image -# -# Builds the OS image and publishes it as version "latest". VMs fetch the -# built images as updates (mkosi.extra/usr/lib/sysupdate.d). Runs on every -# push, weekly for package updates, and by hand for critical CVEs. +# os.yml builds the OS image and publishes it as version "latest". VMs fetch +# the built images as updates (mkosi.extra/usr/lib/sysupdate.d). It runs on +# every push, weekly for package updates, and by hand for critical CVEs. # # Required values: # - SECUREBOOT_KEY repository secret: the private key of mkosi.crt, written @@ -21,12 +19,9 @@ on: jobs: os: runs-on: linux - env: - PKG: ${{ gitea.server_url }}/api/packages/${{ gitea.repository_owner }}/generic/agent/latest - AUTH: "Authorization: token ${{ gitea.token }}" steps: - name: Install tools - run: dnf install -yq mkosi sbsigntools + run: dnf install -yq mkosi git-core - name: Check out uses: builtin:checkout - name: Build @@ -39,12 +34,14 @@ jobs: working-directory: mkosi.output run: | zstd -q --rm -9 agent_*.usr-*.raw + - name: Checksum + working-directory: mkosi.output + run: sha256sum agent_*.efi agent_*.usr-*.raw.zst > SHA256SUMS - name: Sign working-directory: mkosi.output env: KEY: ${{ secrets.SIGNING_KEY }} run: | - sha256sum agent_*.efi agent_*.usr-*.raw.zst > SHA256SUMS export GNUPGHOME=$(mktemp -d) gpg -q --batch --import <<< "$KEY" gpg -q --batch -o SHA256SUMS.gpg --detach-sign SHA256SUMS @@ -53,6 +50,9 @@ jobs: run: qemu-img convert -c -O qcow2 "$(basename agent_*.efi .efi).raw" agent.qcow2 - name: Publish working-directory: mkosi.output + env: + PKG: ${{ gitea.server_url }}/api/packages/${{ gitea.repository_owner }}/generic/agent/latest + AUTH: "Authorization: token ${{ gitea.token }}" run: | curl -fsS -H "$AUTH" -X DELETE "$PKG" || true for f in agent_*.efi agent_*.usr-*.raw.zst agent.qcow2 agent_*.manifest SHA256SUMS.gpg SHA256SUMS; do diff --git a/.gitignore b/.gitignore index c2947e3..768409f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,5 @@ mkosi.output/ mkosi.key +mkosi.cache/ +mkosi.tools/ +mkosi.tools.* diff --git a/AGENTS.md b/AGENTS.md index 7fc88aa..c336734 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,31 +5,37 @@ every change. ## Style -- Keep it simple. Prefer fewer files, fewer lines and the defaults. Delete what - isn't needed. +- Keep it simple. Prefer fewer files and fewer lines. Delete what isn't + needed. +- Follow the defaults and conventions of each tool and language. Only set an + option when the default doesn't work, and say why. - Divide code and config into parts (files, directories, sections) that each stand on their own: reading one part alone tells you what it does and why. -- Each fact lives in one place. Elsewhere, refer to it by path instead of - repeating it. +- Each fact lives in one place. Elsewhere, refer to it instead of repeating it. - Write plain English in short sentences. +- Name each part for what it does. A part without a good name holds things + that don't belong together. +- A little copying beats a little dependency. Repeat a small piece rather than + share it or pull it in from elsewhere. ### File header -Every file that allows comments starts with a header. It goes after the -shebang, if there is one: +A file starts with a header, after the shebang if there is one. Leave it out +when the name already says it all, as with `.gitignore`. A part made of +many files, like a package, needs it in only one of them. For example: ```sh -#!/bin/sh -# Image version -# -# Prints the build time in UTC (YYYYMMDDhhmm). Every build gets a higher -# version than the one before, which is how systemd-sysupdate tells that an -# update is newer. +#!/bin/bash +# mkosi.version prints the build time in UTC (YYYYMMDDhhmm) and the git +# commit. Every build gets a higher version than the one before, which is how +# systemd-sysupdate tells that an update is newer. The commit tells which +# source an image was built from. ``` -- Line 1 is a title: a few words, in sentence case, with no full stop. -- Then a line with only the comment character. -- Then what the file does and why, naming the files it works with by path. +- The first sentence starts with the name of the part the file is, and says + what it does. That is the name the language or tool uses for it, such as a + file name or a package name. +- The rest says why, naming the files it works with by path. Files that can't hold comments (JSON, `subuid`, `machine-id`) are explained in the file that uses them. @@ -38,10 +44,13 @@ the file that uses them. - Explain why, not what. Leave out comments that only repeat the code. Try to write clean code instead of many comments. -- Put a comment right above the line or block it is about. +- Put a comment right above the line or block it is about. A short note on + one line may go at the end of that line, as a full sentence too. - Write full sentences that start with the name of what they describe: `# ManifestFormat lists the packages and versions in the image.` or `# link prints the tmpfiles line for /etc/$1.` +- Separate paragraphs and lists with a line holding only the comment + character. - Wrap comments at 80 columns. ## Testing @@ -51,15 +60,13 @@ run mkosi in a privileged podman container that boots systemd: ```sh podman build -t mkosi-vm - <<'END' -FROM registry.fedoraproject.org/fedora:45 -RUN dnf install -y mkosi qemu-kvm-core edk2-ovmf systemd-repart swtpm \ - openssh-clients socat && \ - dnf install -y $(mkosi dependencies) +FROM registry.fedoraproject.org/fedora:latest +RUN dnf install -y mkosi git-core CMD ["/sbin/init"] END podman run -d --name mkosi --privileged --systemd=always -v :/repo \ -v mkosi-cache:/root/.cache/mkosi -w /repo mkosi-vm -podman exec mkosi mkosi genkey # once, if there is no mkosi.key +podman exec mkosi mkosi genkey # Run this once, if there is no mkosi.key. podman exec -d -t mkosi sh -c 'mkosi -f vm > mkosi.output/vm.log 2>&1' podman exec mkosi mkosi ssh -- systemctl --failed ``` @@ -76,5 +83,5 @@ with "has not been built yet". To boot an existing build without a rebuild, pin its version (from `mkosi.output/agent_.raw`): ```sh -mkosi --image-version 202611171816 vm +mkosi --image-version 202611171816.c80e843 vm ``` diff --git a/README.md b/README.md index 817b1d1..7f449e8 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,10 @@ claude.ai/code or the Claude app (Remote Control), or log in with ssh. Boot verifies the UKI (kernel, initrd and command line), which holds the dm-verity hash that verifies `/usr`. - **Encrypted with a TPM:** everything that isn't read-only, such as `/etc`, - `/var` and `/home`, is encrypted. The TPM unlocks it only for those signed + `/var` and `/home`, is encrypted. The TPM unlocks it only for correctly signed UKIs. +- **Easy to reset:** a factory reset wipes everything that isn't read-only, and + the VM sets itself up again as at first boot. - **Tools in containers:** Claude runs as the user `agent`, without root, and runs its toolchains in containers with podman. - **Self-updating:** the image rebuilds weekly. A bad update rolls back by @@ -28,22 +30,22 @@ claude.ai/code and the Claude app under its hostname: `agent-` and four hex digits. To start over, run `systemctl start factory-reset.target` as root. It reboots -and wipes `/etc` and `/var`, and the VM sets itself up as at first boot. +and wipes the root partition (`/etc`, `/var` and `/home`), and the VM sets +itself up as at first boot. ## Development ```sh -mkosi genkey # local test only, CI uses the SECUREBOOT_KEY secret +mkosi genkey # This is for local tests. CI uses the SECUREBOOT_KEY secret. mkosi build ``` `mkosi.output/` then holds the disk image (`agent_.raw`) and the UKI and /usr partitions that make up an update. -To build and boot a test VM (needs `qemu-kvm-core edk2-ovmf swtpm -openssh-clients socat`): +To build and boot a test VM: ```sh -mkosi -f vm # opens its console: log in as root, password root -mkosi ssh # in another terminal: ssh in as root +mkosi -f vm # This opens the console. Log in as root, password root. +mkosi ssh # This logs in as root with ssh, in another terminal. ``` diff --git a/mkosi.conf b/mkosi.conf index c1779e2..53ad108 100644 --- a/mkosi.conf +++ b/mkosi.conf @@ -1,66 +1,54 @@ -# Agent image +# mkosi.conf builds a Fedora VM image that runs Claude Code in the background. +# /usr is read-only and replaced whole by updates. The root filesystem holds +# the state. # -# A Fedora VM image that runs Claude Code in the background. mkosi.extra/ is -# copied to /, mkosi.repart/ defines the disk and mkosi.sandbox/ adds the -# Claude Code package repository. /usr is read-only and replaced whole by -# updates. The root filesystem holds the state: /var, and an /etc that is -# mostly links into /usr (mkosi.finalize). Claude can't change the OS, so it -# runs its tools in containers. -# mkosi.extra/etc/claude-code/ sets Claude Code up for that: -# managed-settings.json lets it run without permission prompts, and CLAUDE.md -# tells it about this machine. +# The other parts of the build: +# - mkosi.extra/ is copied to /. +# - mkosi.repart/ defines the disk image: the ESP and the /usr partitions. +# - mkosi.extra/usr/lib/repart.d/ makes the root partition at first boot. +# - mkosi.finalize keeps /etc in /usr, and links it into /etc at boot. +# - mkosi.sandbox/ adds the Claude Code package repository. +# - mkosi.version gives each build its version. [Distribution] Distribution=fedora Release=45 +[Build] +# ToolsTree builds with mkosi's own Fedora tools, the same on every host, +# so the host needs only mkosi and git (for mkosi.version). The tools land in +# mkosi.tools/. +ToolsTree=yes +ToolsTreeRelease=%r +Incremental=yes +CacheDirectory=mkosi.cache + [Output] Format=disk ImageId=agent OutputDirectory=mkosi.output SplitArtifacts=uki,partitions -# ManifestFormat lists the packages and versions in the image, to tell which -# builds a CVE affects. .gitea/workflows/os.yml publishes it with the image. ManifestFormat=json [Content] -Bootable=yes -Bootloader=systemd-boot -# Packages is systemd with its network services, plus: -# - kernel-core has no drivers or firmware beyond what VMs need. -# - systemd-container has systemd-pull, which systemd-sysupdate downloads with. -# - gnupg2 checks the signature of updates. -# - systemd-boot-unsigned is the boot loader, which mkosi signs. -# - util-linux and shadow-utils give the console login, the setup and -# newuidmap for rootless podman. -# - systemd-pam gives login sessions: Claude's user manager and its D-Bus, -# which rootless podman needs. -# - openssh-server lets you log in with ssh keys. -# - zram-generator-defaults sets up compressed swap in RAM. -# - podman and podman-docker run Claude's toolchains in containers. -# - claude-code comes from mkosi.sandbox/etc/yum.repos.d. -# - git-core and openssh-clients let Claude Code use git and push over ssh. -# - The rest are basic command-line tools Claude uses on the host. Packages= - kernel-core - systemd - dbus-broker - systemd-udev - systemd-networkd - systemd-resolved - systemd-container - gnupg2 - systemd-boot-unsigned - util-linux - shadow-utils - systemd-pam - openssh-server - zram-generator-defaults - podman - podman-docker - claude-code - git-core - openssh-clients + kernel-core # It has no drivers or firmware VMs don't need. + systemd # It is the init and service manager. + dbus-broker # It is D-Bus, for the user manager and podman. + systemd-udev # It has udev, sysupdate, repart and cryptsetup. + systemd-networkd # It runs DHCP on every network card. + systemd-resolved # It resolves DNS names. + systemd-container # It has systemd-pull and gnupg2 for sysupdate. + systemd-boot-unsigned # It is the boot loader, which mkosi signs. + util-linux # It has login, for the console login. + shadow-utils # It has newuidmap for rootless podman. + systemd-pam # It gives logins a session and user manager. + openssh-server # It lets you log in once there is a key. + zram-generator-defaults # It sets up compressed swap in RAM. + podman # It runs Claude's tools in containers. + claude-code # It comes from mkosi.sandbox/etc/yum.repos.d. + git-core # It brings openssh-clients to push over ssh. + # The rest are basic command-line tools Claude uses on the host. curl tar gzip @@ -72,48 +60,37 @@ Packages= iproute WithDocs=no Locale=C.UTF-8 -# UnifiedKernelImageFormat names UKIs the way systemd-sysupdate names the ones -# it installs. +# Hostname is agent- and four hex digits of the machine ID. +Hostname=agent-???? +# UnifiedKernelImageFormat names the UKI in the ESP agent_.efi, which +# matches the MatchPattern= of mkosi.extra/usr/lib/sysupdate.d/20-uki.transfer. UnifiedKernelImageFormat=%i_%v -# KernelCommandLine sets: -# - console= shows the console on the serial port and the screen. The last -# one, the screen, is /dev/console, where systemd-firstboot asks for the root -# password at first boot. -# - rw mounts the root filesystem writable. The initrd finds it by its -# partition type (mkosi.extra/usr/lib/repart.d/50-root.conf). -# - systemd.hostname= names each machine agent- and four hex digits from its -# machine ID, from the initrd on. It wins over /etc/hostname, so hostnamectl -# renames only until the next boot. -# - systemd.image_policy= makes the initrd use only an encrypted root -# filesystem (or none yet, at first boot) and a verity-checked /usr. -# Otherwise someone with the disk could put in a plain root filesystem with -# their own /etc. Our UKI would boot it, and with PCR 11 unchanged, their -# code could unseal the key of the real one. -# - SYSTEMD_DEFAULT_MOUNT_RATE_LIMIT_BURST lets systemd handle more mount -# changes per second. At the default of 5, it holds back mounts at boot and -# delays / and /usr by up to a second each. The kernel passes it to systemd -# as environment. KernelCommandLine= + # The console shows on the serial port and the screen. The screen + # comes last, so systemd-firstboot asks for the root password there. console=ttyS0,115200n8 console=tty0 quiet + # The initrd finds the root filesystem by its partition type + # (mkosi.extra/usr/lib/repart.d/50-root.conf) and mounts it writable. rw - systemd.hostname=agent-???? + # The image policy only accepts an encrypted root filesystem (or none, + # at first boot) and a verity-checked /usr. Otherwise someone with the + # disk could swap in a plain root filesystem. Our UKI would boot it, and + # their code could unseal the key of the real one. systemd.image_policy=root=encrypted+absent:usr=verity:esp=unprotected + # The mount rate limit is raised from 5, which holds back mounts at + # boot and delays / and /usr by up to a second each. SYSTEMD_DEFAULT_MOUNT_RATE_LIMIT_BURST=50 # KernelInitrdModules are the modules the initrd needs to find the disks of a -# VM, mount /usr and make, unlock and mount the root filesystem. +# VM, mount /usr and unlock the root filesystem. The kernel has virtio_blk, +# sd_mod, the TPM drivers and btrfs built in. KernelInitrdModules= - virtio_blk virtio_scsi - sd_mod nvme - tpm_tis - tpm_crb dm-verity dm-crypt erofs - btrfs # KernelModules keeps all modules but the hardware drivers, then the drivers a # VM needs (disks, network, screen) and those of rootless podman's networks # (pasta). The last matching line wins. Keyboard, USB and a basic screen are @@ -126,7 +103,6 @@ KernelModules= /drivers/md/* nvme virtio_scsi - sd_mod virtio_net qemu_fw_cfg bochs @@ -135,42 +111,29 @@ KernelModules= tun # RemoveFiles drops what the image doesn't use: # - System.map is only for debugging the kernel. -# - The udev hwdb holds hardware names and quirks, nothing a VM needs. -# - homed, userdbd and nsresourced are unused services. +# - The udev hwdb holds hardware names and quirks, nothing a VM needs. Without +# hwdb.d, systemd-hwdb-update can't build it again at boot. RemoveFiles= /usr/lib/modules/*/System.map /usr/lib/udev/hwdb.bin /usr/lib/udev/hwdb.d - /usr/lib/systemd/system/systemd-homed* - /usr/lib/systemd/system/systemd-userdbd.* - /usr/lib/systemd/system/systemd-nsresourced.* [Validation] # SecureBoot signs systemd-boot and the UKI, and puts our keys on the ESP. # systemd-boot enrolls them at first boot if the firmware is in setup mode (no -# keys enrolled; in Proxmox, an EFI disk without pre-enrolled keys). mkosi.key -# is the SECUREBOOT_KEY secret, which .gitea/workflows/os.yml writes. +# keys enrolled). SecureBoot=yes -SecureBootKey=mkosi.key -SecureBootCertificate=mkosi.crt # SignExpectedPcr signs the PCR 11 values that each UKI will measure, with # mkosi.key. The TPM then unlocks the root filesystem only for UKIs we signed, # also after updates (mkosi.extra/usr/lib/repart.d/50-root.conf). SignExpectedPcr=yes [Runtime] -# Runtime sets up the test VM of mkosi vm (AGENTS.md). Ephemeral boots a copy, -# so test runs don't change the built image. Credentials sets the root -# password, and systemd.firstboot=no skips the questions at first boot, such -# as the offer of a recovery key. mkosi ssh logs in as root with mkosi.key, -# which mkosi also authorizes for root in the VM. +# Runtime sets up the test VM of mkosi vm. Ephemeral=yes CPUs=4 -RAM=8G +RAM=4G RuntimeSize=40G -# QemuArgs joins the serial port to the console mkosi vm shows (hvc0). The UKI -# doesn't use hvc0: with Secure Boot, systemd-stub ignores the console= mkosi -# passes. QemuArgs=-serial chardev:console Credentials=passwd.plaintext-password.root=root KernelCommandLineExtra=systemd.firstboot=no diff --git a/mkosi.extra/etc/claude-code/CLAUDE.md b/mkosi.extra/etc/claude-code/CLAUDE.md index 01d5b60..09503e6 100644 --- a/mkosi.extra/etc/claude-code/CLAUDE.md +++ b/mkosi.extra/etc/claude-code/CLAUDE.md @@ -3,11 +3,13 @@ You run on a small Fedora VM made for you, as the user `claude`, without root. - **The OS is read-only**: you can't install anything on it. Run toolchains, languages and - services in containers, with rootless `podman` (also as `docker`). For quick commands: + services in containers, with rootless `podman`. For quick commands: `podman run --rm -v "$PWD:/w" -w /w docker.io/library/python:3 python script.py`. - For longer work, keep a dev container you can install into: - `podman run -d --name dev -v ~:/w -w /w quay.io/fedora/fedora:45 sleep infinity`, then - `podman exec dev dnf install -y gcc` and `podman exec dev make`. + For longer work, keep one dev container per worktree or session, named after its directory, + that you install into: + `podman run -d --name "${PWD##*/}" -v "$PWD:$PWD" -w "$PWD" quay.io/fedora/fedora:latest sleep infinity`, + then `podman exec "${PWD##*/}" dnf install -y gcc` and `podman exec "${PWD##*/}" make`. + Remove it with `podman rm -f` when the work is done. - On the host: git, ssh, curl, tar/gzip/xz/zstd, find, diff, ps, ip. - **Your files survive reboots**: your home (/home/claude), containers and images stay. /tmp is wiped at every boot. The VM may reboot at about 04:10 to update. diff --git a/mkosi.extra/usr/lib/repart.d/50-root.conf b/mkosi.extra/usr/lib/repart.d/50-root.conf index b9f8db2..fe48695 100644 --- a/mkosi.extra/usr/lib/repart.d/50-root.conf +++ b/mkosi.extra/usr/lib/repart.d/50-root.conf @@ -1,11 +1,9 @@ -# Root filesystem -# -# systemd-repart makes it in the initrd at first boot, from the free space -# after /usr, and grows it when the disk grows. It holds all state: /etc -# (mkosi.finalize) and /var, which is its own btrfs subvolume. It is encrypted -# with a key in the TPM, so a TPM is required. The key is sealed to the signed -# PCR 11 policy of our UKIs (SignExpectedPcr= in mkosi.conf), and the initrd -# unlocks it at every boot. +# 50-root.conf makes the root filesystem in the initrd at first boot, from the +# free space after /usr, and grows it when the disk grows. It holds all state: +# /etc (mkosi.finalize) and /var, which is its own btrfs subvolume. It is +# encrypted with a key in the TPM, so a TPM is required. The key is sealed to +# the signed PCR 11 policy of our UKIs (SignExpectedPcr= in mkosi.conf), and +# the initrd unlocks it at every boot. # # FactoryReset makes a factory reset wipe it: root runs systemctl start # factory-reset.target, and at the next boot it is made anew, as at first boot. diff --git a/mkosi.extra/usr/lib/sysctl.d/50-agent.conf b/mkosi.extra/usr/lib/sysctl.d/50-agent.conf index 3653ac2..d6edb46 100644 --- a/mkosi.extra/usr/lib/sysctl.d/50-agent.conf +++ b/mkosi.extra/usr/lib/sysctl.d/50-agent.conf @@ -1,5 +1,4 @@ -# Kernel settings -# -# Containers (file watchers, systemd in containers) run out of Fedora's 128 -# inotify instances per user. 8192 is common on Kubernetes nodes. +# 50-agent.conf raises the inotify instances per user. Containers (file +# watchers, systemd in containers) run out of Fedora's 128. 8192 is common on +# Kubernetes nodes. fs.inotify.max_user_instances = 8192 diff --git a/mkosi.extra/usr/lib/systemd/network/80-dhcp.network b/mkosi.extra/usr/lib/systemd/network/80-dhcp.network index 531ec36..39fab5a 100644 --- a/mkosi.extra/usr/lib/systemd/network/80-dhcp.network +++ b/mkosi.extra/usr/lib/systemd/network/80-dhcp.network @@ -1,7 +1,5 @@ -# Network -# -# DHCP on the real network cards. Kind=!* skips virtual links such as those of -# containers. +# 80-dhcp.network turns on DHCP on the real network cards. Kind=!* skips +# virtual links such as those of containers. [Match] Type=ether Kind=!* diff --git a/mkosi.extra/usr/lib/systemd/system-preset/50-agent.preset b/mkosi.extra/usr/lib/systemd/system-preset/50-agent.preset index 0c3ae2a..e837376 100644 --- a/mkosi.extra/usr/lib/systemd/system-preset/50-agent.preset +++ b/mkosi.extra/usr/lib/systemd/system-preset/50-agent.preset @@ -1,7 +1,6 @@ -# Enabled services -# -# mkosi runs systemctl preset-all, which applies this file. It sorts before -# Fedora's presets, so it wins where they disagree. +# 50-agent.preset enables the services of the image. mkosi runs systemctl +# preset-all, which applies it. It sorts before Fedora's presets, so it wins +# where they disagree. enable systemd-networkd.service enable systemd-resolved.service @@ -18,3 +17,9 @@ enable systemd-sysupdate-reboot.timer # authselect-apply-changes would rewrite /etc/authselect, which links into the # read-only /usr (mkosi.finalize), and fails. disable authselect-apply-changes.service +# systemd-homed, systemd-userdbd and systemd-nsresourced are unused here. +# Fedora enables them. +disable systemd-homed.service +disable systemd-homed-activate.service +disable systemd-userdbd.socket +disable systemd-nsresourced.socket diff --git a/mkosi.extra/usr/lib/systemd/system/claude-remote.path b/mkosi.extra/usr/lib/systemd/system/claude-remote.path index 0ffd0f7..16449f1 100644 --- a/mkosi.extra/usr/lib/systemd/system/claude-remote.path +++ b/mkosi.extra/usr/lib/systemd/system/claude-remote.path @@ -1,7 +1,5 @@ -# Start Claude when logged in -# -# Starts claude-remote.service once Claude has a login: at boot, or as soon as -# the user first logs in. +# claude-remote.path starts claude-remote.service once Claude has a login: at +# boot, or as soon as the user first logs in. [Unit] Description=Start Claude Remote Control once logged in diff --git a/mkosi.extra/usr/lib/systemd/system/claude-remote.service b/mkosi.extra/usr/lib/systemd/system/claude-remote.service index a1ac01e..a537610 100644 --- a/mkosi.extra/usr/lib/systemd/system/claude-remote.service +++ b/mkosi.extra/usr/lib/systemd/system/claude-remote.service @@ -1,8 +1,6 @@ -# Claude Remote Control -# -# Runs Claude Code in the background, as the user agent in its home, so it can -# be used from claude.ai/code or the Claude app. claude-remote.path starts it -# once Claude is logged in. +# claude-remote.service runs Claude Code in the background, as the user agent +# in its home, so it can be used from claude.ai/code or the Claude app. +# claude-remote.path starts it once Claude is logged in. [Unit] Description=Claude Code Remote Control Wants=network-online.target user@1000.service diff --git a/mkosi.extra/usr/lib/systemd/system/sshd.path b/mkosi.extra/usr/lib/systemd/system/sshd.path index 1a3926e..602a227 100644 --- a/mkosi.extra/usr/lib/systemd/system/sshd.path +++ b/mkosi.extra/usr/lib/systemd/system/sshd.path @@ -1,8 +1,7 @@ -# Start sshd once there is a key -# -# sshd starts only once root or the user agent has an ssh key, so a new VM -# has no open port. Root adds the keys after the first boot (README.md). The -# ssh.authorized_keys.root credential also fills root's, such as for mkosi ssh. +# sshd.path starts sshd only once root or the user agent has an ssh key, so a +# new VM has no open port. Root adds the keys after the first boot +# (README.md). The ssh.authorized_keys.root credential also fills root's, such +# as for mkosi ssh. [Unit] Description=Start sshd once an ssh key is set diff --git a/mkosi.extra/usr/lib/sysupdate.d/10-usr.transfer b/mkosi.extra/usr/lib/sysupdate.d/10-usr.transfer index 0f413de..a0223f6 100644 --- a/mkosi.extra/usr/lib/sysupdate.d/10-usr.transfer +++ b/mkosi.extra/usr/lib/sysupdate.d/10-usr.transfer @@ -1,9 +1,8 @@ -# /usr update +# 10-usr.transfer writes the next version of /usr to the unused /usr +# partition. The files come from .gitea/workflows/os.yml. # -# Writes the next version of /usr to the unused /usr partition. -# Verify=yes: SHA256SUMS.gpg must be signed by a key in +# Verify=yes requires SHA256SUMS.gpg to be signed by a key in # /usr/lib/systemd/import-pubring.pgp, and SHA256SUMS checks each download. -# The files come from .gitea/workflows/os.yml. [Transfer] ProtectVersion=%A Verify=yes diff --git a/mkosi.extra/usr/lib/sysupdate.d/11-usr-verity.transfer b/mkosi.extra/usr/lib/sysupdate.d/11-usr-verity.transfer index f8129bf..7a86681 100644 --- a/mkosi.extra/usr/lib/sysupdate.d/11-usr-verity.transfer +++ b/mkosi.extra/usr/lib/sysupdate.d/11-usr-verity.transfer @@ -1,7 +1,5 @@ -# /usr verity update -# -# Writes the dm-verity hashes that go with 10-usr.transfer, which explains -# Verify=yes. +# 11-usr-verity.transfer writes the dm-verity hashes that go with +# 10-usr.transfer, which explains Verify=yes. [Transfer] ProtectVersion=%A Verify=yes diff --git a/mkosi.extra/usr/lib/sysupdate.d/20-uki.transfer b/mkosi.extra/usr/lib/sysupdate.d/20-uki.transfer index d84e64b..d9bbea0 100644 --- a/mkosi.extra/usr/lib/sysupdate.d/20-uki.transfer +++ b/mkosi.extra/usr/lib/sysupdate.d/20-uki.transfer @@ -1,7 +1,5 @@ -# UKI update -# -# Installs the next UKI, which systemd-boot then boots by default. For -# Verify=yes, see 10-usr.transfer. +# 20-uki.transfer installs the next UKI, which systemd-boot then boots by +# default. For Verify=yes, see 10-usr.transfer. # # The new UKI gets three tries (boot counting: the +@l-@d in its name). # systemd-bless-boot marks it good once a boot reaches boot-complete.target. diff --git a/mkosi.extra/usr/lib/sysusers.d/agent.conf b/mkosi.extra/usr/lib/sysusers.d/agent.conf index 6f7156d..e90d818 100644 --- a/mkosi.extra/usr/lib/sysusers.d/agent.conf +++ b/mkosi.extra/usr/lib/sysusers.d/agent.conf @@ -1,5 +1,3 @@ -# Agent user -# -# The user Claude runs as. /etc/subuid and /etc/subgid give it the ids that -# rootless podman needs. +# agent.conf adds the user agent, which Claude runs as. /etc/subuid and +# /etc/subgid give it the ids that rootless podman needs. u agent 1000 "Agent" /home/agent /bin/bash diff --git a/mkosi.extra/usr/lib/tmpfiles.d/agent.conf b/mkosi.extra/usr/lib/tmpfiles.d/agent.conf index bd8da8b..97669dd 100644 --- a/mkosi.extra/usr/lib/tmpfiles.d/agent.conf +++ b/mkosi.extra/usr/lib/tmpfiles.d/agent.conf @@ -1,7 +1,6 @@ -# Agent home -# -# The home of the user agent (mkosi.extra/usr/lib/sysusers.d/agent.conf), with -# Claude's login and podman storage. +# agent.conf makes the home of the user agent +# (mkosi.extra/usr/lib/sysusers.d/agent.conf), with Claude's login and podman +# storage. d /home/agent 0700 agent agent - # linger starts the user manager of agent at boot, for rootless podman and # Claude's own services. diff --git a/mkosi.finalize b/mkosi.finalize index baa587c..dfc07a1 100755 --- a/mkosi.finalize +++ b/mkosi.finalize @@ -1,42 +1,48 @@ -#!/bin/sh -# Factory /etc -# -# The image ships only /usr (mkosi.repart), so this keeps the /etc that the -# packages and mkosi.extra/etc made in /usr/share/factory/etc. It writes -# /usr/lib/tmpfiles.d/factory-etc.conf, with which systemd-tmpfiles links each -# entry into the writable, empty /etc at boot. Updates to /usr then take -# effect in /etc too. /etc itself holds only what the machine writes: passwd, -# shadow, group, hostname, machine-id and the ssh host keys. -set -eu +#!/bin/bash +# mkosi.finalize keeps the /etc that the packages and mkosi.extra/etc made in +# /usr/share/factory/etc, because the image ships only /usr (mkosi.repart). It +# writes /usr/lib/tmpfiles.d/factory-etc.conf, with which systemd-tmpfiles +# links each entry into the writable, empty /etc at boot. Updates to /usr then +# take effect in /etc too. /etc itself holds only what the machine writes: +# passwd, shadow, group, machine-id and the ssh host keys. +set -euo pipefail factory=$BUILDROOT/usr/share/factory/etc cp -a --no-target-directory --update=none "$BUILDROOT/etc" "$factory" # skip holds what /etc keeps for itself, and what other tmpfiles.d files # already set up, such as /etc/os-release. -skip=$(printf '%s\n' passwd group shadow gshadow hostname machine-id ssh +skip=$(printf '%s\n' passwd group shadow gshadow machine-id ssh sed -n 's|^[^#][^ ]* */etc/\([^/ ]*\).*|\1|p' "$BUILDROOT"/usr/lib/tmpfiles.d/*.conf) # link prints the tmpfiles line for /etc/$1. Some entries are copied instead: # a symlink, because a relative one would point somewhere else from the # factory, and subuid and subgid, because shadow-utils won't read them through # a link. +# +# systemd gets L+, which replaces a directory. At first boot, PID 1 applies the +# presets before systemd-tmpfiles runs, and so makes /etc/systemd/system. That +# would block the link, and with it /etc/systemd/user and later updates. link() { - case "$1" in - subuid|subgid) echo "C /etc/$1" ;; - *) if [ -L "$factory/$1" ]; then echo "C /etc/$1"; else echo "L /etc/$1"; fi ;; - esac + if [[ $1 == subuid || $1 == subgid || -L $factory/$1 ]]; then + echo "C /etc/$1" + elif [[ $1 == systemd ]]; then + echo "L+ /etc/$1" + else + echo "L /etc/$1" + fi } { echo "# Generated by mkosi.finalize." - for f in $(ls -A "$factory"); do - case "$f" in *-|.*) continue ;; esac - echo "$skip" | grep -qxF "$f" || link "$f" + # Entries ending in - are backups, such as passwd-. + for path in "$factory"/*; do + f=${path##*/} + [[ $f == *- ]] || grep -qxF "$f" <<< "$skip" || link "$f" done - # /etc/ssh is a directory of its own, because sshd-keygen writes the host - # keys there. + # /etc/ssh is a writable directory instead of one link, because sshd-keygen + # writes the host keys there at first boot. Its other entries are linked one + # by one, so they still get updates from /usr. echo "d /etc/ssh 0755" - for f in $(ls -A "$factory/ssh"); do link "ssh/$f"; done + for path in "$factory"/ssh/*; do link "ssh/${path##*/}"; done } > "$BUILDROOT/usr/lib/tmpfiles.d/factory-etc.conf" - diff --git a/mkosi.repart/00-esp.conf b/mkosi.repart/00-esp.conf index 3c0bc10..b67cfcf 100644 --- a/mkosi.repart/00-esp.conf +++ b/mkosi.repart/00-esp.conf @@ -1,6 +1,5 @@ -# EFI system partition -# -# Holds systemd-boot and the UKIs, two versions at most. +# 00-esp.conf defines the EFI system partition. It holds systemd-boot and the +# UKIs, two versions at most. [Partition] Type=esp Format=vfat diff --git a/mkosi.repart/10-usr.conf b/mkosi.repart/10-usr.conf index 8959193..e74bf78 100644 --- a/mkosi.repart/10-usr.conf +++ b/mkosi.repart/10-usr.conf @@ -1,9 +1,7 @@ -# /usr, slot A -# -# The OS as read-only erofs, protected by dm-verity (usrhash= in the UKI). -# Updates replace it whole. The image holds nothing else but the ESP: the -# initrd makes the root filesystem, with /etc and /var, at first boot -# (mkosi.extra/usr/lib/repart.d/50-root.conf). +# 10-usr.conf defines /usr in slot A: the OS as read-only erofs, protected by +# dm-verity (usrhash= in the UKI). Updates replace it whole. The image holds +# nothing else but the ESP: the initrd makes the root filesystem, with /etc +# and /var, at first boot (mkosi.extra/usr/lib/repart.d/50-root.conf). [Partition] Type=usr Label=%M_%A diff --git a/mkosi.repart/11-usr-verity.conf b/mkosi.repart/11-usr-verity.conf index 217a455..948f1af 100644 --- a/mkosi.repart/11-usr-verity.conf +++ b/mkosi.repart/11-usr-verity.conf @@ -1,6 +1,4 @@ -# /usr verity, slot A -# -# The dm-verity hashes of /usr in 10-usr.conf. +# 11-usr-verity.conf holds the dm-verity hashes of /usr in 10-usr.conf. [Partition] Type=usr-verity Label=%M_%A_verity diff --git a/mkosi.repart/20-usr-b.conf b/mkosi.repart/20-usr-b.conf index abcee2d..9d04d72 100644 --- a/mkosi.repart/20-usr-b.conf +++ b/mkosi.repart/20-usr-b.conf @@ -1,6 +1,5 @@ -# /usr, slot B -# -# Empty until systemd-sysupdate writes the next version to it. +# 20-usr-b.conf defines /usr in slot B. It stays empty until systemd-sysupdate +# writes the next version to it. [Partition] Type=usr Label=_empty diff --git a/mkosi.repart/21-usr-verity-b.conf b/mkosi.repart/21-usr-verity-b.conf index 22cf9d1..af4686f 100644 --- a/mkosi.repart/21-usr-verity-b.conf +++ b/mkosi.repart/21-usr-verity-b.conf @@ -1,6 +1,5 @@ -# /usr verity, slot B -# -# The dm-verity hashes for 20-usr-b.conf, empty until the next update. +# 21-usr-verity-b.conf holds the dm-verity hashes for 20-usr-b.conf, empty +# until the next update. [Partition] Type=usr-verity Label=_empty diff --git a/mkosi.sandbox/etc/yum.repos.d/claude-code.repo b/mkosi.sandbox/etc/yum.repos.d/claude-code.repo index 78c81dd..ab77581 100644 --- a/mkosi.sandbox/etc/yum.repos.d/claude-code.repo +++ b/mkosi.sandbox/etc/yum.repos.d/claude-code.repo @@ -1,8 +1,6 @@ -# Claude Code repository -# -# Anthropic's package repository, stable channel. mkosi uses it to install the -# claude-code package (mkosi.conf). The key's fingerprint is -# 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE. +# claude-code.repo adds Anthropic's package repository, stable channel. mkosi +# uses it to install the claude-code package (mkosi.conf). The key's +# fingerprint is 31DDDE24DDFAB679F42D7BD2BAA929FF1A7ECACE. [claude-code] name=Claude Code baseurl=https://downloads.claude.ai/claude-code/rpm/stable diff --git a/mkosi.version b/mkosi.version index 8fc03e7..0e5573e 100755 --- a/mkosi.version +++ b/mkosi.version @@ -1,7 +1,8 @@ -#!/bin/sh -# Image version -# -# Prints the build time in UTC (YYYYMMDDhhmm). Every build gets a higher -# version than the one before, which is how systemd-sysupdate tells that an -# update is newer. -date -u +%Y%m%d%H%M +#!/bin/bash +# mkosi.version prints the build time in UTC (YYYYMMDDhhmm) and the git +# commit. Every build gets a higher version than the one before, which is how +# systemd-sysupdate tells that an update is newer. The commit tells which +# source an image was built from. +set -euo pipefail +commit=$(git rev-parse --short HEAD) +echo "$(date -u +%Y%m%d%H%M).$commit"