alee/dotfiles

Fork 0

Files

adlee-was-taken f6b04bf47d Auto-sync from catchthesethighs

2025-12-21 23:44:28 -05:00

14 KiB

Raw Blame History

Snapper Integration Guide

Complete guide to managing Btrfs snapshots with Snapper on Arch/CachyOS with limine bootloader integration.

Overview
Prerequisites
Installation
Basic Commands
Snapshot Management
Limine Boot Menu Integration
Automated Snapshots
Recovery Workflows
Troubleshooting
Best Practices

Overview

Snapper is a tool for creating and managing Btrfs filesystem snapshots. Combined with limine-snapper-sync, it provides:

Point-in-time recovery - Restore to specific snapshots
System rollback - Boot previous system states
Change tracking - See what changed between snapshots
Automated backups - Create snapshots on schedule or before updates

Arch/CachyOS Benefits:

Native Btrfs support
Limine bootloader integration for boot menu entries
Pre-configured subvolume layouts
Snapshots directly bootable via limine

Prerequisites

System Requirements

OS: Arch Linux or CachyOS
Filesystem: Btrfs (required for snapshots)
Bootloader: Limine (for boot menu integration)
Subvolume Layout: Standard Arch Btrfs layout

Check Your Setup

# Verify Btrfs filesystem
df -T /
# Output: Filesystem Type Mounted on
#         /dev/nvme0n1p2 btrfs /

# Check subvolumes
btrfs subvolume list /
# Output should show: @ (root), @home, @var, @cache, etc.

# Verify limine bootloader
cat /proc/cmdline | grep limine
# or check EFI boot entry
efibootmgr

Installation

1. Install Snapper

# Via pacman
sudo pacman -S snapper

# Or via AUR (paru or yay)
paru -S snapper

2. Install Limine Snapper Sync

# Via AUR
paru -S limine-snapper-sync

# Or yay
yay -S limine-snapper-sync

3. Configure Snapper

Create config for root subvolume:

sudo snapper -c root create-config /

Create config for home subvolume (optional):

sudo snapper -c home create-config /home

4. Enable Service

# Enable limine-snapper-sync service
sudo systemctl enable limine-snapper-sync.service
sudo systemctl start limine-snapper-sync.service

# Verify it's running
sudo systemctl status limine-snapper-sync.service

5. Verify Installation

snap-validate-service

Output:

✓ snapper installed
✓ limine-snapper-sync installed
✓ limine-snapper-sync enabled
✓ limine-snapper-sync running
✓ Snapper configs: root, home

Basic Commands

Create Snapshots

# Basic snapshot
snap-create "Initial setup"

# Snapshot with detailed description
snap-create "Before system upgrade - v6.13 → v6.14"

# Multiple snapshots
snap-create "Pre-AUR updates"
# ... do updates ...
snap-create "Post-AUR updates"

List Snapshots

# Show last 10 snapshots
snap-list

# Show last 20 snapshots
snap-list 20

# Show all snapshots
snap-list all

Output:

Snapper Snapshots (root):
  42   | 2025-12-21 14:30  | single   | Before system upgrade
  41   | 2025-12-21 10:15  | single   | Initial setup
  40   | 2025-12-20 23:45  | pre      | Auto-snapshot (before pacman)

View Snapshot Details

snap-show 42

Output:

Snapshot 42 (root):
  Created:        2025-12-21 14:30:14
  Type:           single
  Description:    Before system upgrade
  Filesystem:     btrfs
  Subvolume:      @
  UUID:           a1b2c3d4-e5f6...
  Space used:     2.3G

Delete Snapshots

# Delete single snapshot
snap-delete 40

# Delete multiple
snap-delete 38 39 40

# Interactive delete
snap-delete --interactive

snap-check-limine

Verifies:

Limine config up to date
All snapshots in boot menu
Limine file locations correct

Output:

✓ Limine config found
✓ 12 boot entries detected
✓ Snapshots synced: 42, 41, 40
✓ Boot menu up to date

Detailed Snapshot Info

snap-info

Shows breakdown by type:

Pre-snapshots (before package operations)
Post-snapshots (after package operations)
Manual snapshots
Timeline snapshots (if enabled)

snap-sync

Manually trigger sync if you suspect desync between snapshots and boot menu.

Snapshot Management

Pre-configured Configs

Snapper comes with configs for different subvolumes. Manage them:

# List all configs
sudo snapper list-configs

# View config details
sudo snapper get-config root
sudo snapper get-config home

Automatic Pre/Post Snapshots

Snapper automatically creates snapshots before/after pacman operations.

Before update:

sudo pacman -Syu
# Snapper auto-creates "pre" snapshot
# ... pacman runs ...
# Snapper auto-creates "post" snapshot

View pre/post pairs:

snap-list | grep "pre\|post"

Timeline Snapshots (Optional)

Enable hourly/daily/monthly snapshots (not enabled by default):

# Edit snapper config
sudo nano /etc/snapper/configs/root

# Find TIMELINE settings:
TIMELINE_CREATE="yes"
TIMELINE_CLEANUP="yes"

# Set cleanup policy
TIMELINE_MIN_AGE="1800"        # Min 30 min between timeline snapshots
TIMELINE_LIMIT_HOURLY="10"     # Keep 10 hourly
TIMELINE_LIMIT_DAILY="7"       # Keep 7 daily
TIMELINE_LIMIT_WEEKLY="0"      # Disable weekly
TIMELINE_LIMIT_MONTHLY="12"    # Keep 12 monthly
TIMELINE_LIMIT_YEARLY="10"     # Keep 10 yearly

Enable timeline service:

sudo systemctl enable snapper-timeline.timer
sudo systemctl start snapper-timeline.timer

Cleanup Policies

Configure what snapshots to keep (in /etc/snapper/configs/root):

# Keep this many... after cleanup runs
ALLOW_USERS=""
ALLOW_GROUPS=""

SYNC_ACL="no"

AUTODETECT_FILESYSTEMS="yes"

BTRFS_QGROUPS=""

BACKGROUND_COMPARISON="yes"

FSTYPE="btrfs"

SUBVOLUME="/"

NUMBER_CLEANUP="yes"
NUMBER_LIMIT="50"
NUMBER_LIMIT_IMPORTANT="10"

TIMELINE_CLEANUP="yes"
TIMELINE_MIN_AGE="1800"
TIMELINE_LIMIT_HOURLY="10"
TIMELINE_LIMIT_DAILY="7"
TIMELINE_LIMIT_WEEKLY="0"
TIMELINE_LIMIT_MONTHLY="12"
TIMELINE_LIMIT_YEARLY="10"

EMPTY_PRE_POST_CLEANUP="yes"
EMPTY_PRE_POST_CLEANUP_AGE="604800"

Then run cleanup:

sudo snapper -c root cleanup number
sudo snapper -c root cleanup timeline
sudo snapper -c home cleanup number

How It Works

limine-snapper-sync automatically:

Detects all Snapper snapshots
Creates boot menu entries for each
Updates Limine configuration
Manages entries (adds/removes as snapshots change)

After syncing, your limine boot menu will show:

Limine Boot Menu
────────────────────────────
1. Current System (Arch Linux)
   └─ @ (default)
   
2. Snapshot 42: Before system upgrade
   └─ @/.snapshots/42/snapshot
   
3. Snapshot 41: Initial setup
   └─ @/.snapshots/41/snapshot
   
4. Snapshot 40: Auto-snapshot (before pacman)
   └─ @/.snapshots/40/snapshot

Boot from Snapshot

Restart computer
At Limine menu, select snapshot
System boots from snapshot subvolume
All changes since snapshot are not visible

Important: This is read-only unless you manually mount it writable.

Differences Between Subvolume Types

Subvolume	Path	Bootable	Writable
Root (`@`)	`/`	Yes	Yes
Snapshot	`@/.snapshots/42/snapshot`	Yes	No (default)
Read-only snapshot	`@/.snapshots/42/snapshot`	Yes	No

Automated Snapshots

Before System Updates

# Snapper automatically creates pre-snapshot
sudo pacman -Syu
# After update completes, post-snapshot created

# View the pair
snap-list | tail -2

Custom Aliases for Common Operations

# Before AUR updates
alias aur-update='snap-create "Before AUR update" && paru -Syu && snap-create "After AUR update"'

# Before kernel update
alias kernel-update='snap-create "Before kernel update" && sudo pacman -S linux && snap-create "After kernel update"'

Systemd Unit for Scheduled Snapshots

Create /etc/systemd/system/snapper-daily.service:

[Unit]
Description=Daily Snapper Snapshot
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/bin/snapper -c root create -d "Daily snapshot"
ExecStart=/usr/bin/snapper -c home create -d "Daily snapshot (home)"

Create /etc/systemd/system/snapper-daily.timer:

[Unit]
Description=Daily Snapper Snapshot Timer
Requires=snapper-daily.service

[Timer]
OnCalendar=daily
OnCalendar=*-*-* 02:00:00

[Install]
WantedBy=timers.target

Enable:

sudo systemctl daemon-reload
sudo systemctl enable snapper-daily.timer
sudo systemctl start snapper-daily.timer

# Check status
sudo systemctl list-timers

Recovery Workflows

Scenario 1: System Won't Boot After Update

Steps:

At Limine menu:
- Select pre-update snapshot
- Boot from snapshot

Once booted from snapshot:

# Now in read-only snapshot environment
# Make notes of what failed

# If you want to apply fixes, remount writable
sudo mount -o remount,rw /

# Fix issues (reinstall package, etc)
sudo pacman -S broken_package

Restore full system from snapshot:

# Option A: Copy snapshot to live root
sudo btrfs subvolume snapshot /.snapshots/40/snapshot /@.restore

# Option B: Boot live, restore via btrfs
sudo btrfs subvolume delete /
sudo btrfs subvolume snapshot /.snapshots/40/snapshot /

Reboot:
```
sudo reboot
```

Scenario 2: Configuration Accidental Overwrite

Steps:

Identify when file changed:
```
snap-list | grep -B5 -A5 "Some change"
```
Find the snapshot before change:
```
snap-show 42
snap-show 41
```

Mount specific snapshot:

sudo mkdir -p /mnt/snapshot42
sudo mount -t btrfs -o subvol=@/.snapshots/42/snapshot /dev/nvme0n1p2 /mnt/snapshot42

Recover file:

sudo cp /mnt/snapshot42/etc/nginx/nginx.conf ~/.config/

# Or view diff
diff /mnt/snapshot42/etc/nginx/nginx.conf /etc/nginx/nginx.conf

Cleanup:

sudo umount /mnt/snapshot42
sudo rmdir /mnt/snapshot42

Scenario 3: Rollback Entire System

Complete recovery from snapshot:

# Boot from Limine snapshot menu
# At snapshot, create new snapshot of current state (optional backup)
snap-create "Pre-rollback backup"

# Restore from specific snapshot
sudo btrfs subvolume delete @
sudo btrfs subvolume snapshot /.snapshots/40/snapshot @

# Reboot
sudo reboot

After reboot:

System is fully restored to snapshot state
All post-snapshot changes are gone
Snapshots still exist (you can rollback again)

Troubleshooting

Verify Snapper Installation

snap-validate-service

Check Snapper Configs

sudo snapper list-configs

# Detailed config
sudo snapper -c root get-config

# Manual sync
sudo snapper list-configs
snap-sync

# Check limine service
sudo systemctl status limine-snapper-sync.service

# View logs
sudo journalctl -u limine-snapper-sync.service -n 20

Can't Mount Snapshot

# Create temporary mount point
sudo mkdir -p /mnt/snap

# Identify snapshot subvolume
btrfs subvolume list /

# Mount specific snapshot
sudo mount -t btrfs -o subvol=@/.snapshots/42/snapshot /dev/nvme0n1p2 /mnt/snap

# Verify
ls /mnt/snap

# Cleanup when done
sudo umount /mnt/snap

Snapper Disk Usage Growing

# Check snapshot usage
btrfs filesystem usage /

# Cleanup old snapshots
sudo snapper -c root cleanup number
sudo snapper -c home cleanup number

# Verify disk usage decreased
btrfs filesystem usage /

Service Won't Start

# Check errors
sudo systemctl start limine-snapper-sync.service
sudo journalctl -xe

# Manually sync
sudo /usr/bin/snapper-limine-sync

# Check limine configuration
ls -la /boot/limine/
cat /boot/limine/limine.conf

Best Practices

Before Major Operations

# Always snapshot before:
snap-create "Before AUR package X"
snap-create "Before kernel update"
snap-create "Before major configuration change"

# Then perform the operation
# Monitor for issues

# If issues: boot snapshot via Limine
# If success: keep snapshot for point-in-time recovery

Naming Conventions

# Good names
snap-create "Before pacman system update"
snap-create "After successful AUR update"
snap-create "Backup before /etc/nginx config change"

# Bad names
snap-create "snapshot"
snap-create "test"
snap-create "backup"

Regular Cleanup

Schedule cleanup (weekly):

# Add to crontab
0 3 * * 0 /usr/bin/snapper -c root cleanup number
0 4 * * 0 /usr/bin/snapper -c home cleanup number
0 5 * * 0 /usr/bin/snapper-limine-sync

Documentation

# Keep notes of major changes and snapshots
# In ~/Documents/snapshot-history.txt

# 2025-12-21 Snapshot 42: System upgrade 6.13→6.14
# 2025-12-20 Snapshot 41: Initial setup complete
# 2025-12-19 Snapshot 40: Base installation

Backup Critical Data

# Don't rely only on snapshots
# Backup critical data separately

# Snapshots are for:
# - System recovery
# - Configuration recovery
# - Point-in-time rollback

# Backups are for:
# - Off-site redundancy
# - Long-term retention
# - Disaster recovery

Quick Reference

Command	Purpose
`snap-create`	Create snapshot
`snap-list`	List snapshots
`snap-show`	Show snapshot details
`snap-delete`	Delete snapshot
`snap-check-limine`	Verify boot menu sync
`snap-sync`	Manual sync to boot menu
`snap-validate-service`	Verify service health
`snap-info`	Show snapshot breakdown

14 KiB Raw Blame History

Snapper Integration Guide

Table of Contents

Overview

Prerequisites

System Requirements

Check Your Setup

Installation

1. Install Snapper

2. Install Limine Snapper Sync

3. Configure Snapper

4. Enable Service

5. Verify Installation

Basic Commands

Create Snapshots

List Snapshots

View Snapshot Details

Delete Snapshots

Check Boot Menu Sync

Detailed Snapshot Info

Manually Sync with Boot Menu

Snapshot Management

Pre-configured Configs

Automatic Pre/Post Snapshots

Timeline Snapshots (Optional)

Cleanup Policies

Limine Boot Menu Integration

How It Works

Boot Menu Entries

Boot from Snapshot

Differences Between Subvolume Types

Automated Snapshots

Before System Updates

Custom Aliases for Common Operations

Systemd Unit for Scheduled Snapshots

Recovery Workflows

Scenario 1: System Won't Boot After Update

Scenario 2: Configuration Accidental Overwrite

Scenario 3: Rollback Entire System

Troubleshooting

Verify Snapper Installation

Check Snapper Configs

Boot Menu Not Updating

Can't Mount Snapshot

Snapper Disk Usage Growing

Service Won't Start

Best Practices

Before Major Operations

Naming Conventions

Regular Cleanup

Documentation

Backup Critical Data

Quick Reference

See Also

14 KiB

Raw Blame History