SysLinuxOS – Snapshot Management Guide

1. Introduction

SysLinuxOS 13.2 uses btrfs as its default filesystem and integrates snapper, grub-btrfs, and the syslinuxos-rollback helper to provide automatic, GRUB-bootable filesystem snapshots.

Every time the system is updated or a snapshot is created manually, a copy of the root filesystem is stored in /.snapshots. These snapshots appear as boot entries in the GRUB menu, making it possible to boot into a previous state without losing data or needing a live ISO.

This guide covers the commands you will use day-to-day to inspect, create, delete, and restore snapshots on SysLinuxOS.

2. Requirements

The following packages must be installed and active (default in SysLinuxOS):

• syslinuxos-snapshots — provides syslinuxos-rollback, the grub.d helpers, and the setup script
• snapper >= 0.10
• grub-btrfs >= 4.14
• btrfs-progs

To verify the setup is complete:

sudo snapper -c root list
systemctl status snapper-timeline.timer snapper-cleanup.timer grub-btrfsd.service

If /.snapshots is missing or the snapper config does not exist, re-run the setup:

sudo /usr/sbin/syslinuxos-snapshots-setup

3. Viewing Snapshots

List all existing snapshots:

sudo snapper -c root list

The output shows the snapshot number, type (single, pre, post), date, description, and whether the snapshot is read-only. Row 0 is always the current live state and is not a real snapshot.

To show detailed information about a specific snapshot:

sudo snapper -c root info N

Replace N with the snapshot number.

4. Creating a Snapshot

Create a manual single snapshot with a description:

sudo snapper -c root create --description "before kernel upgrade" --type single

Create a pre/post pair around an operation (for example a package install):

sudo snapper -c root create --type pre --description "pre apt upgrade"
sudo apt upgrade
sudo snapper -c root create --type post --description "post apt upgrade"

5. Deleting Snapshots

Delete a single snapshot by number:

sudo snapper -c root delete N

Delete a range of snapshots:

sudo snapper -c root delete N-M

Snapper also runs automatic cleanup via the snapper-cleanup.timer service. The active limits are:

• Maximum regular snapshots kept: 5
• Maximum important snapshots kept: 5
• Daily timeline snapshots kept: 7
• GRUB snapshot entries shown: 8

These values are set by syslinuxos-snapshots-setup and can be overridden manually:

sudo snapper -c root set-config "NUMBER_LIMIT=10"
sudo snapper -c root set-config "TIMELINE_LIMIT_DAILY=14"

6. Automatic Snapshots (Timeline)

The timeline creates one snapshot per hour and keeps the most recent daily snapshots according to the configured limits. This is handled by two systemd timers:

systemctl status snapper-timeline.timer
systemctl status snapper-cleanup.timer

To check the timeline configuration:

sudo snapper -c root get-config

Timeline creation is enabled by default (TIMELINE_CREATE="yes"). To disable it:

sudo snapper -c root set-config "TIMELINE_CREATE=no"

7. Booting from a Snapshot (GRUB)

At boot, the GRUB menu includes a submenu named SysLinuxOS — snapshots. Select a snapshot entry to boot the system in the state it was at the time the snapshot was taken.

The system boots from a read-only copy of the snapshot. From this temporary state you can verify the system works and then decide whether to proceed with the rollback.

The submenu is generated by grub-btrfsd, which monitors /.snapshots and updates /boot/grub/grub-btrfs.cfg automatically when snapshots are created or deleted. To regenerate it manually:

sudo update-grub

8. Rolling Back to a Snapshot

Rolling back replaces the current root subvolume (@) with a read-write copy of the chosen snapshot. The previous @ is preserved as @.rollback-bak-<timestamp> on the btrfs top-level volume for recovery purposes.

8.1 Method 1 — From a Booted Snapshot (Recommended)

Boot into the snapshot you want to restore via the GRUB snapshot submenu, then run:

sudo syslinuxos-rollback

The tool auto-detects the snapshot number from the current subvolume path.

8.2 Method 2 — From the Running System or a Live ISO

Pass the snapshot number explicitly:

sudo syslinuxos-rollback N

In both cases the tool asks for confirmation before making any changes, then prints the steps it will execute:

1. Rename @ to @.rollback-bak-<timestamp>
2. Create a new read-write @ from snapshot N
3. Recreate @/.snapshots as an empty btrfs subvolume (snapper resumes normally)

After the tool completes, reboot:

sudo reboot

After verifying the rolled-back system works correctly, you can delete the backup subvolume (see the next section).

9. Cleaning Up Rollback Backups

Each rollback leaves a @.rollback-bak-<timestamp> subvolume on the btrfs top-level volume. These are kept intentionally as a safety net and do not appear in the GRUB snapshot menu.

To list and remove them:

sudo mkdir -p /mnt/tmp
sudo mount -o subvolid=5 /dev/sdXN /mnt/tmp
ls /mnt/tmp | grep rollback-bak
sudo btrfs subvolume delete -R -c /mnt/tmp/@.rollback-bak-<timestamp>
sudo umount /mnt/tmp

Replace /dev/sdXN with your btrfs partition (visible with lsblk).

10. Accessing Snapshots from Another SysLinuxOS Install

If multiple SysLinuxOS installs are present on different partitions, the GRUB menu includes two additional sections generated by the syslinuxos-snapshots package:

• Other Linux installs on btrfs: top-level entry for each secondary install plus an Advanced options submenu with all available kernels and recovery entries. This replaces the missing os-prober detection for btrfs @ layouts (Debian bugs 921004, 940710).
• SysLinuxOS — Snapshots of other installs: a submenu that chainloads the grub-btrfs.cfg of each secondary install. Selecting an entry boots that install’s specific snapshot.

Both sections are generated by /etc/grub.d/13_syslinuxos-btrfs-otheros and /etc/grub.d/14_syslinuxos-snapshots-otheros. They can be disabled individually in /etc/default/grub:

GRUB_DISABLE_BTRFS_OTHEROS=true
GRUB_DISABLE_BTRFS_SNAPSHOTS_OTHEROS=true

After changing these variables, regenerate the GRUB configuration:

sudo update-grub

11. Re-running Setup

The setup script is idempotent and safe to re-run at any time. It will skip steps that are already complete and only apply what is missing:

sudo /usr/sbin/syslinuxos-snapshots-setup

Use this after a manual change to the snapper configuration, after a failed snapper-boot.service, or when setting up a system that was installed without the syslinuxos-snapshots package.