Documentation
recsetup
Configure and boot an extracted system: time zone, locale, keymap, hostname, accounts, systemd-boot, boot entries, machine id and services. It plans first, shows every command, then applies them.
A/B Installation Contract
recab init copies root A to root B, writes both boot entries and makes A the boot default. Completion requires verification of both roots.Overview
recsetup does the install's configuration and boot steps against the system that recstrap extracted. system-setup runs it for the configuration step as a helper; the Boot step, which writes the boot files and entries, is typed in the install terminal.
recsetup inspectdescribes the target and lists what can be chosen: time zones, locales, keymaps, shells, groups and services.recsetup planchecks a request against the target and prints the exact commands, in order, without running anything.recsetup applyruns them in order and stops at the first that fails. Each step's result is recorded: done, failed or not run.
Every section of a request is optional. The setup step asks for the time zone, locale, keymap, hostname and accounts, and the boot step asks for --boot, the machine id and services. Add --json for machine-readable output (errors go to stderr).
On the release medium, which carries the default software set, every plan starts with the software step: recipe --system --root <target> --recipes-path /usr/lib/recsetup/default-set/recipes install <the default set>, which installs each group recipe through Recipe, offline from the medium's package cache, with a receipt, and then rebuilds the target's caches once. It comes before the accounts (so users join the groups the software brings) and before the boot step (so on A/B both roots get it). A test medium has no default set and installs the base system alone.
Usage
Options as printed by recsetup --help; recsetup plan --help lists the request flags:
Set up an extracted system: time zone, locale, keymap, hostname, accounts, boot and services
Usage: recsetup [OPTIONS] <COMMAND>
Commands:
inspect Describe the target and list what can be chosen (time zones, locales, keymaps, ...)
plan Check a request and print the exact commands, without running them
apply Run the plan's commands in order, stopping at the first failure
help Print this message or the help of the given subcommand(s)
Options:
--json Emit machine-readable JSON (errors too, on stderr)
-h, --help Print help
-V, --version Print version
Start here:
recsetup inspect --root /mnt
recsetup inspect --root /mnt --list timezones
recsetup plan --root /mnt --hostname my-pc --timezone Europe/Brussels
recsetup apply --root /mnt --hostname my-pc --timezone Europe/Brussels
inspect and plan leave the target unchanged. apply runs the requested changes.
For users/passwords and boot options: recsetup apply --help Examples
recsetup inspect --root /mnt recsetup plan --root /mnt --timezone Europe/Amsterdam --locale en_US.UTF-8 --keymap us --hostname mypc --root-password --user yourname read -rs -p "root password: " RP; echo; read -rs -p "yourname password: " UP; echo
printf 'root:%s\nyourname:%s\n' "$RP" "$UP" | recsetup apply --root /mnt --timezone Europe/Amsterdam --locale en_US.UTF-8 --keymap us --hostname mypc --root-password --user yourname --passwords-stdin recsetup apply --root /mnt --boot ab --slot-a /dev/nvme0n1p2 --slot-b /dev/nvme0n1p3 --machine-id recsetup apply --root /mnt --boot mutable --root-device /dev/nvme0n1p2 --machine-id Request File
A front end passes the same choices as JSON with --request setup.json; flags override or add to it. Unknown fields are refused. Users default to admin: true (member of wheel) and password: true.
{
"timezone": "Europe/Amsterdam",
"locale": "en_US.UTF-8",
"keymap": "us",
"hostname": "mypc",
"root_password": true,
"users": [{ "name": "yourname", "groups": ["audio"], "shell": "/bin/bash" }],
"boot": { "mode": "ab", "slot_a": "/dev/nvme0n1p2", "slot_b": "/dev/nvme0n1p3", "options": "console=ttyS0,115200n8" },
"machine_id": true,
"services": ["sshd"]
} boot.kernel defaults to the live media's /run/live-media/boot/vmlinuz. boot.initrd defaults to /run/live-media/boot/initramfs-installed.img, the installed-system initramfs for both distros. Immutable A/B boot requires that initramfs; --no-initrd is not supported for A/B. The live medium's initramfs.img is refused (E030), because it finds the live medium and ignores root=.
Passwords
Passwords never go on the command line. apply --passwords-stdin reads one name:password line for root (with --root-password) and for each user whose password is set, and hands them to chpasswd in the target. Apply checks the lines before it changes anything: a missing, extra, repeated or empty password stops it with E032.
How It Decides
recsetup reads the target, not the live system: the init system from openrc-run or /usr/lib/systemd/systemd, the libc from musl's loader, and each command from what the target ships. inspect --json reports what it found. The machine settings (time zone, locale, keymap, hostname, users, machine id and services) are applied by the target's own setup program, /usr/libexec/recipe-system-setup, which the system recipe installs; recsetup checks each choice and runs it through recchroot. The bootloader and boot entries are recsetup's and recab's.
| Step | systemd (LevitateOS) | OpenRC (AcornOS) |
|---|---|---|
| Time zone | /etc/localtime link into /usr/share/zoneinfo | Same |
| Locale | LANG in /etc/locale.conf (systemd reads it itself) | LANG in /etc/locale.conf (exported by /etc/profile.d/locale.sh) |
| Keymap | KEYMAP in /etc/vconsole.conf | keymap in /etc/conf.d/loadkeys and rc-update add loadkeys boot |
| Hostname | /etc/hostname and /etc/hosts | Same |
| Users | useradd -m -s SHELL -G wheel,… | adduser -D -s SHELL, then addgroup for each group |
| Admin | wheel; the sudo rule in /etc/sudoers.d/10-wheel ships with the system | wheel; the doas rule in /etc/doas.conf ships with the system |
| Passwords | chpasswd in the target | Same (busybox chpasswd) |
| Bootloader | bootctl install --esp-path=/boot --no-variables | copy systemd-boot's EFI binary to EFI/BOOT and EFI/systemd |
| A/B entries | recab init with both roots and the initramfs | Same |
| Mutable entry | kernel and initramfs on the ESP, one entry with root=PARTUUID | Same |
| Machine id | systemd-machine-id-setup | a random /etc/machine-id, unless one exists |
| Services | systemctl enable (offline) | rc-update add … default |
A choice the target cannot provide is refused before anything runs (E031). For example, a target without time zone data offers only UTC, which it sets by removing /etc/localtime. Paths are resolved inside the root, so a symlink in the target never leads to the live system's files.
hwclock), the network configuration, unmounting and the reboot stay manual.Error Codes
Every failure prints a code and a fix; the number is also the exit status. recsetup shares the error table of recstrap, recchroot and recfstab (tools/recstrap/src/error.rs). Its own codes:
| Code | Meaning |
|---|---|
| E029 | The target's init system is neither systemd nor OpenRC (nothing extracted there?) |
| E030 | The request is invalid: a bad hostname or user name, a missing root device, unknown JSON fields |
| E031 | The target cannot provide a choice: a time zone, locale, keymap, shell, group, service or tool it lacks |
| E032 | The passwords on stdin do not match the plan, or --passwords-stdin is missing |
| E033 | A boot file is missing: the kernel, the initramfs, /boot, or systemd-boot itself |
| E034 | A path in the target is unsafe: a symlink loop, or a directory where a file goes |
It also uses shared ones: E008 (apply needs root), E010 (a protected path such as / as the root), E023 (a step's command failed; its output is in the result), and E027 (no PARTUUID for the mutable root).
See Also
- Configuration - Steps 10-14 by hand
- Bootloader & Finish - Steps 15-18 by hand
- recpart - Partitions, and the root devices for
--boot ab - recab - The two A/B roots