Recovery guide for a SysLinuxOS system installed on a LUKS-encrypted partition that no longer boots because GRUB is corrupted, overwritten, or was never installed correctly. This is the natural follow-up to Restoring GRUB on SysLinuxOS (btrfs with subvolumes): here the btrfs root lives inside a LUKS volume, so it has to be unlocked before the @ subvolume can be mounted.
When you need this
- The PC shows
error: no such deviceor drops into agrub>rescue shell, and the installed system uses LUKS for the root filesystem. - Another OS (e.g. Windows) was installed after SysLinuxOS and overwrote the boot loader shared on the ESP.
- The ESP (EFI System Partition) is shared between several installs and needs to be rewritten without losing the other NVRAM entries.
- A kernel or GRUB update was interrupted midway on a system with an encrypted root.
Prerequisites
A bootable SysLinuxOS Live USB (MATE or Gnome). The cryptsetup package must be present on the Live (it is, by default). You need the LUKS passphrase of the volume you’re restoring.
1. Unlock the LUKS volume to restore
Identify the encrypted partition with lsblk -f (it shows up as crypto_LUKS), then unlock it:
sudo cryptsetup luksOpen /dev/sdXN sdXN_crypt
sdXN_crypt is an arbitrary mapper name for this recovery session only: it doesn’t need to match what’s in the installed system’s /etc/crypttab. The decrypted volume shows up at /dev/mapper/sdXN_crypt.
2. Mount the btrfs root subvolume (@)
sudo mkdir -p /mnt/sdXN_crypt sudo mount /dev/mapper/sdXN_crypt /mnt/sdXN_crypt sudo btrfs subvolume list /mnt/sdXN_crypt # check the root subvol's name (@) sudo umount /mnt/sdXN_crypt sudo mount -o subvol=@ /dev/mapper/sdXN_crypt /mnt/sdXN_crypt
Just like in the non-encrypted case, the chroot only works when you explicitly mount subvol=@, not the top level (subvolid=5).
3. Mount the ESP and the bind mounts
If the ESP is shared with other installs (the typical multi-boot case):
sudo mount /dev/sdYM /mnt/sdXN_crypt/boot/efi sudo mount --bind /dev /mnt/sdXN_crypt/dev sudo mount --bind /proc /mnt/sdXN_crypt/proc sudo mount --bind /sys /mnt/sdXN_crypt/sys sudo mount --bind /run /mnt/sdXN_crypt/run
Binding /run matters just as much as /dev, /proc and /sys: without it, update-grub inside the chroot won’t see the LUKS device-mapper entries correctly.
4. Reinstall GRUB from the chroot
sudo chroot /mnt/sdXN_crypt /bin/bash -c " grub-install --target=x86_64-efi --efi-directory=/boot/efi --bootloader-id=SysLinuxOS --recheck "
--bootloader-id must exactly match the folder that already exists under EFI/ on the ESP (check with ls /boot/efi/EFI/ before installing): get it wrong and a new one gets created, losing the NVRAM entry shared with the other installs.
5. Unlock the other encrypted volumes (for os-prober)
If the same disk or other disks hold further SysLinuxOS installs on LUKS volumes that should appear in the GRUB menu, unlock them before regenerating the configuration:
sudo cryptsetup luksOpen /dev/sdZN other_crypt
A LUKS volume that isn’t unlocked is invisible to os-prober: if an expected entry is missing from the menu, this is the first thing to check.
6. Regenerate the full grub.cfg
sudo chroot /mnt/sdXN_crypt /bin/bash -c "update-grub"
GRUB_ENABLE_CRYPTODISK=y must already be set in the installed system’s /etc/default/grub — if not, add it and re-run both grub-install and update-grub before leaving the chroot.
7. Verify (optional)
sudo grep -n "^menuentry\|^submenu" /mnt/sdXN_crypt/boot/grub/grub.cfg
Confirm the entries for the unlocked encrypted systems are present before rebooting.
8. Unmount everything and close the LUKS volumes
sudo umount /mnt/sdXN_crypt/dev sudo umount /mnt/sdXN_crypt/proc sudo umount /mnt/sdXN_crypt/sys sudo umount /mnt/sdXN_crypt/run sudo umount /mnt/sdXN_crypt/boot/efi sudo umount /mnt/sdXN_crypt sudo cryptsetup luksClose sdXN_crypt sudo cryptsetup luksClose other_crypt
Keep the order: unmount the bind mounts before the main mount, and only run luksClose once everything is unmounted.
9. Reboot
sudo reboot
Remove the USB drive while it reboots.
Notes for reuse on other machines
- The mapper names (
sdXN_crypt,other_crypt) are arbitrary, picked for the session: they don’t need to match/etc/crypttab. - Unlocking the other encrypted volumes (step 5) is only needed if they should show up in the GRUB menu; non-encrypted btrfs volumes are already detected automatically by os-prober.
- If the multi-boot layout also includes non-encrypted
@subvolumes, the notes in Restoring GRUB on SysLinuxOS (btrfs with subvolumes) about the os-prober bug #921004/#940710 and the automatic fix insyslinuxos-snapshots≥ 0.3.0 apply here too.
A word of caution
This procedure touches the boot loader and the encrypted volumes of real systems: always double-check with lsblk -f which partition you’re unlocking and which disk grub-install is writing to, especially with several disks attached and several LUKS volumes unlocked at once.
Restoring GRUB on SysLinuxOS with Encrypted Partitions (LUKS)