snapshot-chroot

A focused Btrfs/Snapper recovery utility for assembling a writable chroot around a selected nested root snapshot from a live environment.

Version 2.0.0

snapshot-chroot discovers the installed Btrfs filesystem, offers its default nested snapshot as the initial recovery choice, and lets the user select another snapshot when needed. It derives the root subvolume name and required mounts from the selected system instead of relying on saved state or machine-specific device names.

It does not perform a rollback, change the Btrfs default subvolume, or choose what will boot next.

What Version 2.0 Changes

Version 2.0 removes the companion save-last-snapshot.sh script and last_snapshot state file. The recovery script now:

• Discovers Btrfs filesystems containing nested root snapshots.
• Reads the filesystem's current default subvolume.
• Offers the default snapshot first when it matches a supported nested snapshot path.
• Allows a different snapshot number to be selected.
• Derives root names such as @, @rootfs, @btrfs, or another safe nested root path.
• Reads the separate /home layout and EFI System Partition from the selected snapshot's /etc/fstab.
• Uses /home from the root snapshot when no separate /home entry exists.
• Mounts Btrfs subvolumes by numeric ID and verifies the resulting filesystem-root path.
• Shows the complete discovered layout for approval before making the selected snapshot writable or assembling the chroot.

No per-user boot-time helper or saved snapshot record is required.

Supported Storage Model

The installed root filesystem must use nested Snapper snapshots:

<root-subvolume>/.snapshots/<snapshot-number>/snapshot

Supported root names are discovered from the subvolume tree. Examples include:

@/.snapshots/8/snapshot
@rootfs/.snapshots/1/snapshot
@btrfs/.snapshots/42/snapshot

Home handling is based on the selected system's /etc/fstab:

• If an exact /home entry identifies a Btrfs subvolume on the root filesystem, snapshot-chroot discovers and mounts it.
• If no exact /home entry exists, snapshot-chroot creates no separate home mount. The chroot sees the /home path provided by the selected root snapshot.

A /home filesystem stored on another device is not supported in Version 2.0.

Version 2.0 requires UEFI boot and an EFI System Partition defined at /boot/efi in the selected snapshot's /etc/fstab.

Requirements

Run snapshot-chroot from a Linux live environment that provides:

• Bash
• Btrfs tools
• findmnt and lsblk
• mount, umount, and chroot
• Access to the installed Btrfs filesystem and EFI System Partition

The script performs privileged mount, Btrfs, and chroot operations and must be run as root.

Usage

From the live environment:

sudo ./snapshot-chroot.sh

When one eligible Btrfs filesystem is found, it is selected automatically. If more than one is found, the script presents a numbered device list.

If the Btrfs default subvolume is a supported nested root snapshot, it becomes the initial choice:

Btrfs default snapshot: 1
Default subvolume path: @/.snapshots/1/snapshot

Use default snapshot 1 for the recovery chroot? [Y/n]

Press Enter or answer y to repair the default snapshot. Answer n to enter another snapshot number.

If the default subvolume is not a supported nested snapshot, the script asks for a snapshot number directly.

Discovery and Approval

After snapshot selection, snapshot-chroot:

1. Finds the exact matching root snapshot and rejects missing or ambiguous matches.
2. Resolves the root snapshot and snapshot-store subvolume IDs.
3. Reads the selected snapshot's /etc/fstab.
4. Discovers and validates a separate Btrfs /home mount when one is defined.
5. Creates no separate home mount when no exact /home entry is defined.
6. Discovers and validates the EFI System Partition.
7. Reads the selected snapshot's Btrfs read-only property.
8. Displays the complete recovery layout.

Example with a separate home subvolume:

Discovered Recovery Layout
--------------------------
Root Device      : /dev/nvme0n1p2
Root Subvolume   : @
Snapshot Store   : @/.snapshots
Snapshot         : 8 (ID 312)
Home Device      : /dev/nvme0n1p2
Home Subvolume   : @home
EFI Device       : /dev/nvme0n1p1
Recovery Mount   : /mnt

When no separate /home entry exists, the summary reports:

Home Mount       : No separate fstab entry

The script requires approval of this layout before any writable action.

Read-only Snapshots

A recovery target must be writable for repair work. If the selected snapshot is read-only, snapshot-chroot asks before changing its Btrfs ro property to false.

Declining leaves the snapshot unchanged and cancels recovery. The script does not restore the read-only property after the chroot exits.

Recovery Environment

After approval, the script mounts:

selected root snapshot  -> /mnt
root snapshot store     -> /mnt/.snapshots
separate home, if used  -> /mnt/home
EFI System Partition    -> /mnt/boot/efi

It also bind-mounts:

/dev
/dev/pts
/proc
/sys
/run

The selected root, snapshot store, and optional home subvolume are mounted by numeric Btrfs subvolume ID. Each Btrfs mount is verified against its expected filesystem-root path before recovery continues.

The resulting writable chroot can be used for repairs such as rebuilding an initramfs, repairing packages, regenerating GRUB configuration, or inspecting other snapshots. Commands available inside the chroot depend on the installed system.

Exit the shell normally when finished. The cleanup trap unmounts the recovery environment.

Optional Overrides

Automatic discovery is the default. Advanced users may set these values near the top of snapshot-chroot.sh:

ROOT_PARTITION=""
EFI_PARTITION=""
MOUNT_POINT="/mnt"

• ROOT_PARTITION bypasses automatic root-device selection while retaining Btrfs validation.
• EFI_PARTITION overrides EFI device discovery while retaining block-device validation.
• MOUNT_POINT changes the temporary recovery root.

Blank values use discovery.

Safety

snapshot-chroot stops when required state is missing, ambiguous, or inconsistent. Its safeguards include:

• Read-only top-level discovery mounts.
• Exact nested-snapshot matching.
• Safe root-path validation.
• Numeric subvolume-ID mounts with filesystem-root verification.
• Selected-system /etc/fstab discovery for home and EFI.
• Explicit layout approval before writable actions.
• Explicit approval before changing a snapshot's read-only property.
• Refusal to use an occupied recovery mount point.
• Cleanup on normal completion and early failure.

The utility intentionally does not change the Btrfs default subvolume or boot configuration.

Compatibility and Validation

Version 2.0.0 completed regression testing with matching live and installed distributions.

Family	Distribution	Recovery chroot
Debian/Ubuntu-based	Debian	Passed
Debian/Ubuntu-based	Kubuntu	Passed
Debian/Ubuntu-based	TUXEDO OS	Passed
Arch-based	Manjaro	Passed
Arch-based	CachyOS	Passed
Arch-based	EndeavourOS	Passed

Additional compatibility testing verified an @rootfs nested root with no separate /home fstab entry. Discovery, writable mounting, chroot entry, exit, and reboot all passed.

Compatibility depends on the documented filesystem and fstab state rather than the distribution name.

Development Files

Development and regression tests are kept under dev/. They are not required to run or operate snapshot-chroot. See dev/README.md for the local test command.

Project Files

snapshot-chroot/
├── snapshot-chroot.sh
├── README.md
├── ARCHITECTURE.md
├── CHANGELOG.md
├── LICENSE
└── dev/
    ├── README.md
    └── tests/

License

snapshot-chroot is licensed under the GNU General Public License v3.0 or later.

See LICENSE for the complete license text.