When SysLinuxOS no longer reaches its boot menu, reinstalling the operating system is not always necessary. If GRUB is the problem and the installation on disk is still intact, SysLinuxOS Boot Repair can inspect it from a Live session, regenerate the boot menu configuration, or reinstall the bootloader through a graphical interface.
This guide covers SysLinuxOS Boot Repair 0.3.1 for amd64, available through the SysLinuxOS Tools APT repository. Version 0.3.0 was tested successfully from SysLinuxOS Live; version 0.3.1 adds integration with the SysLinuxOS Tools menu while keeping the repair helper and graphical interface unchanged.
Original boot recovery illustration; this is not an application screenshot.
When to use SysLinuxOS Boot Repair
The tool can help when GRUB no longer appears, the computer drops into a GRUB console, the menu no longer reflects the installed system, or the bootloader needs reinstalling after changes to the disks. These symptoms can have different causes, so identify the installation and the required action before writing to disk.
Boot Repair handles GRUB recovery for an existing SysLinuxOS installation. It does not fix failing hardware or damaged filesystems, reinstall the operating system, or recover deleted partitions. If a drive reports read errors or files are missing, securing the data and diagnosing the storage should come first.
Supported configurations
| Component | Support in version 0.3.1 |
|---|---|
| Target system | A recognizable SysLinuxOS installation with a consistent mount configuration |
| Architecture | amd64; GRUB reinstallation for BIOS or 64-bit UEFI |
| Root filesystem | Btrfs with the @ root subvolume, ext4, or XFS |
| Encryption | A supported root filesystem directly inside a LUKS partition |
| Separate boot partitions | /boot and the EFI System Partition identified through the installed system’s /etc/fstab |
| Existing mounts | Reused through private mounts without unmounting the user’s original mounts |
| Outside the supported scope | LVM inside LUKS, RAID, 32-bit UEFI, nonstandard mount layouts, and other distributions require manual recovery |
A partition appearing in the list does not mean it is eligible for repair. Inspection must confirm that it contains SysLinuxOS, that the root matches fstab, and that the layout is supported.
1. Boot the Live USB in the correct firmware mode
Prepare a SysLinuxOS Live USB and boot the computer from it. Run the repair from the Live session, rather than the installed system being repaired. Before proceeding, have an up-to-date backup of important data and identify the connected drives.
The Live session’s firmware mode must match the installation. Reinstalling UEFI GRUB requires a Live session booted in 64-bit UEFI mode, with EFI variables accessible. A Live session booted in Legacy mode cannot correctly register the corresponding UEFI firmware entry.
From a terminal in the Live session, check its current boot mode:
if [ -d /sys/firmware/efi ]; then
echo "Live session booted in UEFI mode"
cat /sys/firmware/efi/fw_platform_size
else
echo "Live session booted in BIOS/Legacy mode"
fi
For UEFI, this utility expects the value 64. This check describes the running Live session; it does not by itself establish how the installation on disk was configured. If needed, reboot and choose the appropriate USB entry in the firmware’s boot menu.
2. Install Boot Repair in the Live session
With SysLinuxOS Tools already configured and a network connection available:
sudo apt update sudo apt install syslinuxos-boot-repair
If the repository is missing from the Live image you are using, follow the official SysLinuxOS Tools repository instructions. To configure it with the official installer and then install the package:
curl -fsSL https://fconidi.github.io/SysLinuxOS-Tools/client/install-repo.sh -o /tmp/syslinuxos-install-repo.sh less /tmp/syslinuxos-install-repo.sh sudo bash /tmp/syslinuxos-install-repo.sh sudo apt update sudo apt install syslinuxos-boot-repair
The repository uses suite tirreno, component main, architecture amd64, and GPG-signed indices. Check the installed and candidate versions with:
apt policy syslinuxos-boot-repair
This guide describes version 0.3.1. If the repository offers a later version, also review its changelog. On a Live USB without persistence, packages installed in the current session generally do not remain available after a reboot.
Installing from a local package
You can also copy the package to the Live environment and install it from the directory where it was saved:
sudo apt install ./syslinuxos-boot-repair_0.3.1_amd64.deb
The .deb does not bundle every dependency. If dependencies are missing from the Live environment and there is no network connection, obtain them beforehand. Installing Boot Repair changes the Live environment; the subsequent repair acts on the selected installation on disk.
3. Open the interface and identify the root partition
Open SysLinuxOS Tools in the applications menu and choose SysLinuxOS Boot Repair. Alternatively, launch it from a terminal:
syslinuxos-boot-repair-launcher
The GUI runs as the desktop user. Operations requiring privileges go through the administrative helper. Live sessions normally provide passwordless sudo; otherwise, an authentication dialog may appear.
The partition list shows the device, size, filesystem, label, disk, state, and mount locations. To compare the devices from a terminal:
lsblk -o NAME,SIZE,FSTYPE,LABEL,UUID,MOUNTPOINTS
Select the installed SysLinuxOS root partition, rather than the Live USB, @home, or the EFI System Partition. For Btrfs, the utility looks for the root in the @ subvolume. If several installations are present, carefully verify the selected system and the devices shown in the plan.
4. Choose an operation
| Operation | Effect | When to consider it |
|---|---|---|
| Inspect only | Examines the root and boot devices read-only; performs no repair | First check to identify the installation correctly |
| Regenerate the boot menu | Runs update-grub inside the installed system |
GRUB is present, but its menu configuration needs regenerating |
| Reinstall GRUB and regenerate the boot menu | Runs grub-install, followed by update-grub, inside the installed system |
The bootloader needs reinstalling as well as rebuilding the menu |
Inspect only is selected by default. Start there even if you expect to reinstall GRUB: it lets you check the system before choosing an operation that writes to disk.
5. Review the plan and confirm the repair
Click Review plan. The helper inspects the selected installation read-only and reports its root, any separate /boot, boot mode, and EFI partition. For an encrypted root, the plan also identifies the decrypted mapping and its backing LUKS container.
For BIOS, reinstallation targets the whole disk containing the selected root, such as /dev/sda, rather than /dev/sda2. Check the actual destination in the plan, especially when multiple disks are connected.
For UEFI, the EFI System Partition is found through the installed system’s /etc/fstab. Do not choose an arbitrary FAT partition: check the detected partition and confirm that the Live session has UEFI access.
For repair operations, click Confirm repair only after reviewing these details. Cancel is the default button. Inspection alone does not offer a repair confirmation. The helper validates the devices again before execution.
Wait for the result and read Details. Before a repair, an existing grub.cfg is copied to a grub.cfg.syslinuxos-backup.* file in the same directory. This backs up the GRUB configuration; it is not a disk image or a complete system backup.
LUKS roots and partitions that are already mounted
LUKS partitions remain visible whether locked or already unlocked. When you select a locked container, the GUI lets you enter its passphrase in an unlock dialog. Unlocking uses UDisks2 and may also request administrative authentication. The passphrase is not passed in command arguments or saved to disk.
An already unlocked or mounted root can be selected directly when its layout is supported. Boot Repair uses private mounts and removes the helper’s mounts when it finishes; the user’s original mounts and open mapping remain available.
The helper validates the container against the installed system’s crypttab. This accommodates different mapping names in the Live and installed environments, but it does not bypass an inconsistent configuration. LUKS headers, keyslots, crypttab, and initramfs are preserved.
When /boot is inside the encrypted root
If /boot is inside the encrypted root, GRUB must be able to read the container before loading the kernel. After confirmation, Boot Repair enables GRUB_ENABLE_CRYPTODISK=y through a dedicated GRUB defaults file.
With stock GRUB, a LUKS2 container holding /boot needs a compatible PBKDF2 keyslot. A layout containing only Argon2 keyslots is rejected before repair. The utility does not convert keyslots or modify the header to work around this restriction. A separate, unencrypted /boot avoids this specific limitation. LVM inside LUKS remains unsupported in the version described here.
Btrfs, snapshots, and rollback
Boot Repair works on the active @ root and preserves @home, @/.snapshots, Snapper configuration, and rollback backups. It does not restore snapshots or rerun snapshot setup.
Menu regeneration invokes the GRUB scripts already installed in the target system. If snapshot integration is installed and working, those scripts participate in the regeneration. Bootloader repair and snapshot rollback are separate operations: use Boot Repair for an issue with booting, and assess rollback separately when the problem concerns the installed system’s state.
Using the terminal workflow
To open the interactive workflow in your current terminal:
syslinuxos-boot-repair-launcher --cli
The following commands are examples. Replace every device path with the one verified on your own computer. To inspect a root and, if appropriate, regenerate its GRUB configuration:
sudo syslinuxos-boot-repair --plan --root /dev/nvme0n1p2 sudo syslinuxos-boot-repair --config --root /dev/nvme0n1p2
For a UEFI reinstall, boot the Live session in 64-bit UEFI mode and ensure the installed system’s fstab correctly identifies its EFI partition:
sudo syslinuxos-boot-repair --reinstall --root /dev/nvme0n1p2
For a BIOS reinstall, also specify the whole disk containing the root:
sudo syslinuxos-boot-repair --reinstall --root /dev/sda2 --disk /dev/sda
In the CLI, unlock a LUKS root first. --root accepts its open mapping or the physical LUKS partition once its direct mapping is available. If the existing mapping is actually named /dev/mapper/cryptroot, an inspection example is:
sudo syslinuxos-boot-repair --plan --root /dev/mapper/cryptroot
Terminal repairs require the entire confirmation line shown by the helper, including the literal word REPAIR in every language. Do not reuse a confirmation from another machine: it contains the current operation’s devices. In the GUI, the explicit confirmation button supplies this same confirmation to the helper.
Interface language
The interface and helper follow the Live session’s language, with English, Italian, German, French, and Spanish support. English is the fallback when the session language is unsupported. To explicitly open the GUI in English:
syslinuxos-boot-repair-launcher --language en
Output from system commands, including GRUB tools, may retain those programs’ own language settings.
Troubleshooting
The application requires SysLinuxOS Live
Reboot from the Live USB. Running the application in the installed system does not provide the recovery environment expected by the helper.
The root is not recognized or does not match fstab
Check that you selected the SysLinuxOS root rather than a home partition, another system, or the Live session itself. For Btrfs, verify that the layout uses @. Do not change UUIDs or configuration files merely to bypass the check; establish the actual partition layout first.
UEFI errors or inaccessible EFI variables
Check how the Live session was booted. UEFI reinstallation requires 64-bit UEFI mode and accessible EFI variables. Boot Repair does not implement a dedicated Secure Boot configuration or signing workflow; Secure Boot problems require separate investigation.
update-grub or grub-install is missing from the installed system
The utility uses the selected installation’s tools and does not install packages inside it. An installation with missing or damaged GRUB packages therefore needs appropriate manual recovery. Reinstalling Boot Repair in the Live session does not restore those files on the target system.
A repair ends with an error
Read and save Details before trying again. A repair may have partially completed: GRUB installation might have succeeded while menu regeneration failed. An error does not automatically undo earlier writes. The grub.cfg backup is not a complete rollback mechanism.
Checks after the repair
After a successful result, close the application and reboot, removing the USB when prompted. Verify that the firmware selects the correct drive, GRUB displays the expected entries, and SysLinuxOS boots completely. If a snapshot menu was configured, check that it is present.
On a dual-boot machine, also check the other entries without assuming reinstallation guarantees detection of every operating system. If SysLinuxOS reaches GRUB but fails while loading the kernel or mounting the root, the cause may involve components Boot Repair does not rebuild, such as initramfs or the installed system’s configuration.
The final check is a real boot of the computer. A completion message reports the outcome of the executed commands; it does not replace that check.
References
For further reading about manual recovery on the same system, see Restoring GRUB on SysLinuxOS with Btrfs subvolumes and Restoring GRUB on SysLinuxOS with LUKS encrypted partitions. Manual procedures require checking the actual layout and should not run concurrently with Boot Repair.
Official SysLinuxOS Tools repository and APT setup
SysLinuxOS project, Live distribution, and documentation
Debian Wiki: GRUB EFI recovery
Debian Wiki: using chroot
For documentation included in the package:
man syslinuxos-boot-repair man syslinuxos-boot-repair-launcher less /usr/share/doc/syslinuxos-boot-repair/README.md
SysLinuxOS Boot Repair Guide to GRUB Recovery from Live USB