How MAS works

This page explains what the installer builds and how a MAS machine boots. You don't need it to use MAS, but it helps a lot when something goes wrong. See also Recovery.

Disk layout

The installer wipes the disk and creates a GPT partition table.

With two profiles, the space left after partition 2 is split 50/50 between A and B.

Partitions 1 and 2 are the only unencrypted parts. MASBOOT holds GRUB's modules and its menu (grub.cfg) and nothing else. The kernel and the initramfs are not on it. They live inside each profile's encrypted volume.

On NVMe disks the partition names carry a p, for example /dev/nvme0n1p3.

Inside a profile

Each profile is a LUKS2 container, mapped as mas_profile_a or mas_profile_b. Inside is a btrfs filesystem with two subvolumes:

• @ mounted at /
• @snapshots mounted at /.snapshots, used by snapper for rollbacks

/etc/fstab mounts the root subvolume, the snapshots subvolume, MASBOOT at /boot/grub, and (on UEFI) the ESP at /boot/efi.

How the system gets installed

1. Base system. debootstrap downloads a minimal Debian 13 into a folder in the live session.
2. Copy. The disk is partitioned and encrypted, and the base is copied onto Profile A with rsync.
3. Configure in a chroot. The installer enters the new system and runs apt to install the kernel, GRUB packages, the initramfs tools, your drivers, and the privacy options. It then installs KDE Plasma, creates users, and rebuilds the initramfs.
4. Clone for Profile B (two profiles only). See below.
5. Bootloader. GRUB is installed and its menu is written.

Steps 1 and 3 download from Debian's mirrors, which is why the install needs internet.

How a boot works

1. The firmware loads GRUB. On UEFI it starts from the ESP, where GRUB was installed with --removable (the fallback path EFI/BOOT/BOOTX64.EFI). On BIOS it starts from the MBR and the bios_grub partition.
2. GRUB reads its modules and grub.cfg from MASBOOT. The menu appears with no password.
3. You pick a profile. GRUB runs cryptomount on that profile's LUKS partition and asks for its passphrase.
4. GRUB reads /@/boot/vmlinuz and /@/boot/initrd.img from inside the unlocked volume and starts the kernel. These are symlinks that Debian keeps pointing at the newest installed kernel, so a kernel update needs no change to the menu.
5. The initramfs unlocks the volume again, this time with a keyfile, so you type the passphrase only once.
6. The system mounts the btrfs root and boots.

Because the menu is written as fixed entries, with the profile's LUKS and filesystem UUIDs, GRUB never has to scan for systems. Only the profile you pick is ever unlocked.

Keys

Each profile's LUKS header has two keyslots:

• The keyfile sits at /etc/cryptsetup-keys.d/<mapper>.key, inside the encrypted volume, and is copied into the initramfs. The initramfs is also inside the encrypted volume, and it is readable by root only. So the keyfile can't be read until you have unlocked the disk.
• The passphrase slot uses PBKDF2, not LUKS2's default Argon2. GRUB can't compute Argon2, so without PBKDF2 it couldn't unlock the disk.
• The keyfile slot uses a low iteration count on purpose. It is random data, not a human-chosen password, so slow key stretching adds nothing and would only slow your boot.
• If you leave the passphrase blank, no keyfile is made and the volume has an empty passphrase. That means no real protection.

Two profiles

Profile B is built by cloning the finished Profile A, which is much faster than installing twice.

Copied from A: the whole system, including kernel, desktop, drivers and settings.

Not copied, and created fresh for B:

• A's keyfile (B gets its own, with its own passphrase)
• The initramfs (rebuilt after B's crypttab is fixed)
• fstab and crypttab (rewritten for B's UUIDs)
• The machine ID (generated on first boot)
• The hostname (<name>-b)
• Root and admin credentials (the ones you entered for Profile B)
• A's snapshots, and the contents of the ESP and /boot/grub

Nothing is shared between profiles except the two small unencrypted partitions. The two LUKS volumes have separate headers and keys, and each profile has its own swap and snapshots.

To switch, mas-switch-profile runs grub-reboot for the other profile's menu entry (mas-profile-a or mas-profile-b) and restarts. GRUB boots that entry once.

Install checkpoints

The installer works in stages: partition, deploy_a, desktop_a, clone_b, bootloader. After each stage it saves a checkpoint with a fingerprint of the settings that stage depended on.

If an install fails and you start the installer again, it offers to resume. A stage is skipped only if its fingerprint still matches, so if you change an option that affects it, that stage and the ones after it run again.

The checkpoint and your saved answers (including passwords) are kept in ~/mas-build in the live session, with owner-only permissions, and are deleted when the install succeeds. They live in memory, so they are gone if you reboot the USB.

Privacy options at a glance

The toggles on the privacy screen are applied inside the chroot during install. See Privacy and security options for what each does.