Skip to content

About

Shared Aurora Linux first-boot, encryption and installer image integration

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Aurora first boot

Shared first-boot integration for Fedora Aurora Remix, Aurora ALARM and Aurora NixOS. This is distribution support code, separate from the native macOS installer. The native app records the encryption choice on the target EFI partition; Linux creates a separate owner account and password.

The image contract uses a Btrfs root subvolume named root, an ext4 boot filesystem, and the EFI partition handed off by Aura in the device tree. /etc/aurora/image-layout contains only version 1, the root filesystem UUID, the boot filesystem UUID and the root subvolume. Image production supplies it and copies it into every initrd; installing this package alone does not arm conversion. A fresh image also supplies /usr/lib/aurora/image-format (aurora-btrfs-v1) and /var/lib/aurora/firstboot/pending.

aurora-initrd-root adapts the captured conversion state machine to those identities and mounts. It verifies that all target filesystems belong to the handed-off EFI disk, records the root GPT identity before conversion, and retains the resumable phase journal. Every initrd includes the unlock service, so the normal root filesystem UUID remains valid after opening its LUKS container. The first-boot account wizard replaces the temporary key with the Linux password, verifies unlock, retires the temporary key copies and releases the login services. NixOS persists the account declaration and a private password-hash file outside the public Nix store.

Desktop and text setup

On desktop images the owner account is created by the desktop's own graphical setup: Plasma Setup on KDE, GNOME Initial Setup on GNOME. The password chosen there also becomes the disk password; first boot asks for nothing else. aurora-firstboot runs before the desktop's setup, enables sudo for wheel, and arms one PAM hook per greeter (plasmalogin, sddm, gdm-password). A vendor-only PAM file (/usr/lib/pam.d, as Fedora 44 ships plasmalogin) gets a temporary /etc/pam.d copy carrying the hook. When the owner first signs in with a password, aurora-password-hook checks it with unix_chkpwd and hands it, in a root-only file under /run, to aurora-disk-rekey.service. That service enrolls it in key slot 1, proves it unlocks, destroys both copies of the temporary key and removes the hooks again. Plasma Setup signs the new owner in automatically once. While the disk still opens with its temporary key, a gate on the greeter's automatic login (plasmalogin-autologin, sddm-autologin) fails the owner's automatic login, so the greeter asks for the new password. GNOME Initial Setup signs the owner in with the password itself. A distribution whose PAM configuration is generated (NixOS) declares the same hooks itself and says so in /etc/aurora/password-hooks. Where neither is possible, the disk password is asked for on the text console.

On the MacBook Neo the boot splash stops updating once the installed system has started. Nothing is therefore asked on the splash after the initrd: the text wizard and the console fallback release it first. The splash still asks for the disk password in the initrd at every later start.

Desktop mode is chosen when the default target is graphical, a display manager exists, no person account exists, and either plasma-setup.service is enabled, GDM has GNOME Initial Setup, or the distribution declares its own wiring with /etc/aurora/desktop-account-setup. Everything else, including minimal images, uses the text wizard on tty1, where one password protects both the account and the disk. aurora.firstboot=text on the kernel command line forces the text wizard, and starts it for recovery when no owner exists, for example if a desktop's setup cannot run. Plasma Setup waits for this service through plasma-setup.service.d/aurora-firstboot.conf and is skipped, never failed, while setup is pending or after the text wizard has created the owner.

The temporary disk key

In-place encryption in the initrd runs before any person has chosen a password, so the converter formats the root with a random 64-byte temporary key in key slot 0. Two plain-file copies exist: /boot/omarchy/luks-key on the unencrypted ext4 boot filesystem, from which the initrd opens the root without asking, and /var/lib/aurora/firstboot/luks-key inside the encrypted root. An interrupted conversion that needed recovery also leaves /boot/omarchy/luks-header-before-recovery.bin, a header backup that still holds the temporary keyslot.

Exposure window. From the end of the conversion until the owner's password replaces the key, anyone who starts the Mac, or reads the boot partition, can open the root: the disk is encrypted but not yet protected. On desktop images the window ends at the owner's first password sign-in at the greeter, which normally follows Plasma Setup or GNOME Initial Setup within the same session, because the autologin gate refuses the new owner's automatic login while the key exists. If the Mac is switched off before that sign-in, the window stays open, and the hooks stay armed across starts, until the first password sign-in. The text wizard and the console fallback close it before any account exists.

Retirement. aurora-disk-rekey.service (or the wizard) enrolls the password in slot 1 and proves it opens the disk. It then removes the slot the temporary key opens with luksKillSlot, authorised by the new password, so cryptsetup refuses unless another slot still works; it never removes slot 1, checks that the key no longer opens anything, and proves slot 1 again. Only then are both key copies and the header backup overwritten and unlinked, the journal set to finished and /var/lib/aurora/firstboot/disk-rekeyed written. An owner slot that already holds a different password is never replaced, and the temporary slot then stays. Overwriting is best effort (Btrfs copies on write, flash storage remaps blocks); what retires the key is the removed keyslot, after which no copy of the key and no later header opens the disk. The header backup is removed for that reason: with a surviving key copy it would open the disk indefinitely.

PAM hooks. Once disk-rekeyed exists, aurora-password-hook returns at once, without reading the password, and the autologin gate passes. Fedora and ALARM remove the hook lines in the same step. NixOS declares its hooks in the generated PAM configuration, so the rekey also adds aurora.firstboot.passwordHooks = false; to the factory /etc/nixos/owner.nix (the text wizard writes it into the owner.nix it creates). The next rebuild drops the hooks from PAM; an owner.nix edited by hand is left alone and the journal says what to add. Until that rebuild the marker keeps the hooks inert, and a rebuild never re-arms them.

Keyboard layout and the disk password

The disk password is typed at the initrd prompt with the console keymap, which dracut's i18n module and mkinitcpio's sd-vconsole hook copy from /etc/vconsole.conf when the initrd is built, and NixOS from console.keyMap. The greeter uses the desktop's XKB layout. When the two differ, the same keys type different characters, and the password enrolled from the greeter would not unlock the disk.

  • Before enrolling the password, the rekey reads the desktop layout (XKBLAYOUT in vconsole.conf with systemd 255 and later, else /etc/X11/xorg.conf.d/00-keyboard.conf, or /etc/aurora/keyboard where the distribution declares it). A console keymap still at the image default (unset or us) follows that layout with localectl --no-convert set-keymap, using the keymap systemd-localed would choose (an XKB-converted keymap from kbd, else kbd-model-map). A keymap set on purpose is kept. Any remaining difference is logged at warning priority (journalctl -t aurora-firstboot -p warning); there is no desktop notification path at that point of the first sign-in.
  • aurora-initrd-keymap.path watches /etc/vconsole.conf. aurora-initrd-keymap.service (also started after the rekey) reads the keymap each initrd carries (lsinitrd, lsinitcpio) and rebuilds them (dracut --regenerate-all --force, mkinitcpio -P) only when it differs, and only on an encrypted Aurora install. The initrd unlock service orders after systemd-vconsole-setup.service, so the keymap is loaded before the prompt.
  • NixOS derives a console keymap from services.xserver.xkb with mkDefault priority, so an explicit console.keyMap or console.useXkbConfig still wins, and declares the layout in /etc/aurora/keyboard.

These changes keep the door open for a single prompt at every start (the initrd's systemd-ask-password caching the passphrase in the kernel keyring for pam_systemd_loadkey): that design depends on the initrd and the greeter typing the same characters, which the keymap work above provides, and the hook retirement only concerns the first-boot hooks.

Console, splash and recovery

The unit never takes tty1: systemd's terminal reset and hangup cut Plymouth off its keyboard, so a splash prompt would never see a keystroke. The text wizard opens tty1 itself after asking Plymouth to quit with a time bound, and stops a splash that does not answer, so the wizard can never stay hidden behind it; the console is cleared, and systemd status lines and kernel messages are muted while the prompts are on screen. Input mistakes are asked again in place. Any other failure shows its cause (on desktops the splash is released to show it) and offers a retry in the same boot; the owner and encryption journals make every attempt resumable, including an account created without its password. In the text wizard the disk is rekeyed before the account password is set, so the two never diverge. While setup is pending the greeter and login prompts are skipped rather than failed.

The initrd wrapper keeps the converter byte-preserved and overrides only its presentation: the splash message carries the percentage (Encrypting your drive... 37%), because many Plymouth themes ignore system-update progress, and the message is replaced, not stacked, ending with Your drive is encrypted. Starting Aurora....

SELinux (Fedora)

/usr/lib is lib_t in Fedora's policy, and systemd runs a lib_t program in its own init_t domain, where tools such as chpasswd are denied. selinux/aurora_firstboot.fc labels /usr/lib/aurora/aurora-* as bin_t, so systemd starts these programs in unconfined_service_t. Fedora builds and loads this module with make install-selinux; the wizard restores the policy label of every file it creates. tests/selinux-policy loads the module into real Fedora targeted policy and checks the labels and domain rules.

GRUB

U-Boot exposes every NVMe namespace of the internal disk, and probing the extra ones can wedge it. GRUB's search probes every filesystem on every disk once its hints miss. images/harden-grub.py (installed as /usr/lib/aurora/aurora-harden-grub) rewrites the EFI stub so it finds the boot filesystem only on the disk GRUB started from, with a UUID-named marker file on Fedora and probe in Aurora's Arch core image, before a single exact-hint lookup fills GRUB's cache. The main configuration's lookups name the same disk, and its EFI partition is the one GRUB was loaded from. A missing boot filesystem stops with a message instead of a scan. finalize-image applies it to images; Fedora's package reapplies it after GRUB updates.

The imported converter is byte-preserved under vendor/, with its exact content digest and source provenance. Aurora's wrapper and distro integrations are new work. Source checks and disposable native loop-device tests are separate from real initrd keyboard, reboot, interruption and hardware qualification. No new distribution installation is qualified by this repository yet.

The converter requires cryptsetup 2.8 or newer, matching the target Fedora 44 and current ALARM packages; the native conversion CI uses that target userspace. Older Ubuntu 24.04 cryptsetup rejects the bounded conversion arguments and is not a supported runtime.

Run unprivileged checks with python3 -m unittest discover -s tests. tests/loop-conversion requires root in a disposable native CI worker and is restricted to its own newly created loop-backed disk. It must not be run on a user's ordinary disk.

tests/loop-rekey runs aurora-firstboot --rekey against its own small loop-backed LUKS2 disk under the same rules: it checks the enrolment, the temporary keyslot and key file retirement, an occupied owner slot that must keep the temporary slot, a resumed rekey, and the hook retirement.

The privileged conversion test shares the worker's IPC namespace with its udev daemon. Device-mapper uses IPC semaphores for udev completion; a private container IPC namespace can leave cryptsetup open waiting after successful conversion. This affects the disposable container test environment; the installed initrd retains ordinary udev synchronization. See Red Hat's documented container cryptsetup issue.

About

Shared Aurora Linux first-boot, encryption and installer image integration

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages