Recovery

How to get into an installed MAS system from the live USB, and how to fix the most common boot problems. Read How MAS works first if you want to know why these steps work.

Passphrases cannot be recovered. If you forget one, the data in that profile is gone.

Before anything goes wrong: back up your LUKS header

The LUKS header holds the keyslots. If it gets damaged, the profile can't be unlocked even with the right passphrase. A backup lets you restore it.

The installer saves header backups to ~/mas-build/luks-headers in the live session, which is erased when you reboot. Before you reboot after installing, copy that folder to a USB drive or another computer. If you have already rebooted, make a new backup from the installed system:

sudo cryptsetup luksHeaderBackup /dev/sdX3 --header-backup-file profileA-header.img

Store the file somewhere other than the disk it protects. Anyone with the header file and your old passphrase can unlock the disk, so treat it as sensitive. Make a new backup after you change a passphrase.

Get into an installed profile from the live USB

Use this for every repair below.

Boot the MAS live USB and open a terminal.
Find your partitions:
```
lsblk -f
```
Profile A is partition 3 and Profile B is partition 4. MASBOOT is partition 2. On UEFI, partition 1 is the ESP. Use the names you see, such as /dev/sda3 or /dev/nvme0n1p3.
Unlock the profile (replace the partition name):
```
sudo cryptsetup open /dev/sdX3 mas_profile_a
```
For Profile B use /dev/sdX4 and the name mas_profile_b.

Mount it:

sudo mount -o subvol=@ /dev/mapper/mas_profile_a /mnt
sudo mount -o subvol=@snapshots /dev/mapper/mas_profile_a /mnt/.snapshots
sudo mount /dev/sdX2 /mnt/boot/grub
sudo mount /dev/sdX1 /mnt/boot/efi        # UEFI only

Enter the system:

sudo mount --bind /dev /mnt/dev
sudo mount --bind /dev/pts /mnt/dev/pts
sudo mount -t proc proc /mnt/proc
sudo mount -t sysfs sys /mnt/sys
sudo chroot /mnt /bin/bash

You are now inside your installed system as root. When you are done:

exit
sudo umount -R /mnt
sudo cryptsetup close mas_profile_a

Problems and fixes

Do the steps above for the profile you are fixing, then run the fix inside the chroot.

The GRUB menu is missing, or you land at a `grub>` or `grub rescue>` prompt

Reinstall GRUB and regenerate its config. Use the commands for your boot mode.

UEFI:

grub-install --target=x86_64-efi --efi-directory=/boot/efi --removable
update-grub

Legacy BIOS (use the whole disk, not a partition, for example /dev/sda):

grub-install --target=i386-pc --recheck /dev/sdX
update-grub

GRUB asks for the passphrase but boot then drops to an `initramfs` prompt

The initramfs can't unlock the disk. Check that /etc/crypttab has a line for this profile that matches lsblk -f:

cat /etc/crypttab
blkid /dev/sdX3

The UUID on the crypttab line must match the UUID of the LUKS partition. If it does, rebuild the initramfs:

update-initramfs -u -k all

The system asks for the passphrase twice

The keyfile didn't get set up, so the initramfs falls back to asking. It is harmless. To check, look for /etc/cryptsetup-keys.d/mas_profile_a.key and for the key path in the crypttab line. A path means the keyfile is in use. none means it isn't.

A kernel update left you unable to boot

Boot the profile's other kernel if you have one, or use the chroot and run:

update-initramfs -u -k all
update-grub

You want to go back to an earlier state

If you enabled snapshots, you can list them from the running system with sudo snapper -c root list. From a chroot, the same command works.

The LUKS header is damaged

If cryptsetup open says the device isn't a valid LUKS device, restore the header from your backup:

sudo cryptsetup luksHeaderRestore /dev/sdX3 --header-backup-file profileA-header.img

This overwrites the header, so check that the file matches this partition. The installer's own backup was taken before the boot keyfile was added, so after restoring it the system will ask for the passphrase a second time at boot. A backup you made later does not have that problem. Passphrases changed after the backup was made will not work either.

Change a passphrase

Run this on the installed system or in the chroot. It changes the passphrase in slot 0 and leaves the boot keyfile alone:

sudo cryptsetup luksChangeKey /dev/sdX3 --pbkdf pbkdf2

Keep --pbkdf pbkdf2. Without it, GRUB can't unlock the disk. Make a fresh header backup afterwards.

Still stuck

See Troubleshooting, and include the output of lsblk -f when you ask for help.