Docs: recsetup

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

Warning
Installation finishes with root B as a copy of root A. After personalization, 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 inspect describes the target and lists what can be chosen: time zones, locales, keymaps, shells, groups and services.
  • recsetup plan checks a request against the target and prints the exact commands, in order, without running anything.
  • recsetup apply runs 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:

Text
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

See what the target offers
recsetup inspect --root /mnt
Preview the configuration (changes nothing)
recsetup plan --root /mnt --timezone Europe/Amsterdam --locale en_US.UTF-8 --keymap us --hostname mypc --root-password --user yourname
Apply it; the passwords come from stdin, one name:password line each
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
Install systemd-boot and the A/B boot layout (use the root devices recpart reported)
recsetup apply --root /mnt --boot ab --slot-a /dev/nvme0n1p2 --slot-b /dev/nvme0n1p3 --machine-id
Mutable layout: one boot entry for the root partition
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.

Text
{
  "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.

Stepsystemd (LevitateOS)OpenRC (AcornOS)
Time zone/etc/localtime link into /usr/share/zoneinfoSame
LocaleLANG in /etc/locale.conf (systemd reads it itself)LANG in /etc/locale.conf (exported by /etc/profile.d/locale.sh)
KeymapKEYMAP in /etc/vconsole.confkeymap in /etc/conf.d/loadkeys and rc-update add loadkeys boot
Hostname/etc/hostname and /etc/hostsSame
Usersuseradd -m -s SHELL -G wheel,…adduser -D -s SHELL, then addgroup for each group
Adminwheel; the sudo rule in /etc/sudoers.d/10-wheel ships with the systemwheel; the doas rule in /etc/doas.conf ships with the system
Passwordschpasswd in the targetSame (busybox chpasswd)
Bootloaderbootctl install --esp-path=/boot --no-variablescopy systemd-boot's EFI binary to EFI/BOOT and EFI/systemd
A/B entriesrecab init with both roots and the initramfsSame
Mutable entrykernel and initramfs on the ESP, one entry with root=PARTUUIDSame
Machine idsystemd-machine-id-setupa random /etc/machine-id, unless one exists
Servicessystemctl 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.

Note
Users that already exist are left as they are (with a warning), so applying the same request again is safe. The clock (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:

CodeMeaning
E029The target's init system is neither systemd nor OpenRC (nothing extracted there?)
E030The request is invalid: a bad hostname or user name, a missing root device, unknown JSON fields
E031The target cannot provide a choice: a time zone, locale, keymap, shell, group, service or tool it lacks
E032The passwords on stdin do not match the plan, or --passwords-stdin is missing
E033A boot file is missing: the kernel, the initramfs, /boot, or systemd-boot itself
E034A 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