From e1fe7bdffd1e6c933c3f3109ef32fe75a2bd54ac Mon Sep 17 00:00:00 2001 From: adlee-was-taken Date: Sun, 21 Dec 2025 23:44:55 -0500 Subject: [PATCH] Auto-sync from catchthesethighs --- docs/SNAPPER (1).md | 732 -------------------------------------------- 1 file changed, 732 deletions(-) delete mode 100644 docs/SNAPPER (1).md diff --git a/docs/SNAPPER (1).md b/docs/SNAPPER (1).md deleted file mode 100644 index e908323..0000000 --- a/docs/SNAPPER (1).md +++ /dev/null @@ -1,732 +0,0 @@ -# Snapper Integration Guide - -Complete guide to managing Btrfs snapshots with Snapper on Arch/CachyOS with limine bootloader integration. - -## Table of Contents - -- [Overview](#overview) -- [Prerequisites](#prerequisites) -- [Installation](#installation) -- [Basic Commands](#basic-commands) -- [Snapshot Management](#snapshot-management) -- [Limine Boot Menu Integration](#limine-boot-menu-integration) -- [Automated Snapshots](#automated-snapshots) -- [Recovery Workflows](#recovery-workflows) -- [Troubleshooting](#troubleshooting) -- [Best Practices](#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 - -```bash -# 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 - -```bash -# Via pacman -sudo pacman -S snapper - -# Or via AUR (paru or yay) -paru -S snapper -``` - -### 2. Install Limine Snapper Sync - -```bash -# Via AUR -paru -S limine-snapper-sync - -# Or yay -yay -S limine-snapper-sync -``` - -### 3. Configure Snapper - -Create config for root subvolume: - -```bash -sudo snapper -c root create-config / -``` - -Create config for home subvolume (optional): - -```bash -sudo snapper -c home create-config /home -``` - -### 4. Enable Service - -```bash -# 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 - -```bash -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 - -```bash -# 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 - -```bash -# 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 - -```bash -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 - -```bash -# Delete single snapshot -snap-delete 40 - -# Delete multiple -snap-delete 38 39 40 - -# Interactive delete -snap-delete --interactive -``` - -### Check Boot Menu Sync - -```bash -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 - -```bash -snap-info -``` - -Shows breakdown by type: -- Pre-snapshots (before package operations) -- Post-snapshots (after package operations) -- Manual snapshots -- Timeline snapshots (if enabled) - -### Manually Sync with Boot Menu - -```bash -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: - -```bash -# 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:** -```bash -sudo pacman -Syu -# Snapper auto-creates "pre" snapshot -# ... pacman runs ... -# Snapper auto-creates "post" snapshot -``` - -**View pre/post pairs:** -```bash -snap-list | grep "pre\|post" -``` - -### Timeline Snapshots (Optional) - -Enable hourly/daily/monthly snapshots (not enabled by default): - -```bash -# 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: - -```bash -sudo systemctl enable snapper-timeline.timer -sudo systemctl start snapper-timeline.timer -``` - -### Cleanup Policies - -Configure what snapshots to keep (in `/etc/snapper/configs/root`): - -```bash -# 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: - -```bash -sudo snapper -c root cleanup number -sudo snapper -c root cleanup timeline -sudo snapper -c home cleanup number -``` - ---- - -## Limine Boot Menu Integration - -### How It Works - -`limine-snapper-sync` automatically: -1. Detects all Snapper snapshots -2. Creates boot menu entries for each -3. Updates Limine configuration -4. Manages entries (adds/removes as snapshots change) - -### Boot Menu Entries - -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 - -1. Restart computer -2. At Limine menu, select snapshot -3. System boots from snapshot subvolume -4. 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 - -```bash -# 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 - -```bash -# 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`: - -```ini -[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`: - -```ini -[Unit] -Description=Daily Snapper Snapshot Timer -Requires=snapper-daily.service - -[Timer] -OnCalendar=daily -OnCalendar=*-*-* 02:00:00 - -[Install] -WantedBy=timers.target -``` - -Enable: - -```bash -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:** - -1. **At Limine menu:** - - Select pre-update snapshot - - Boot from snapshot - -2. **Once booted from snapshot:** - ```bash - # 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 - ``` - -3. **Restore full system from snapshot:** - ```bash - # 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 / - ``` - -4. **Reboot:** - ```bash - sudo reboot - ``` - -### Scenario 2: Configuration Accidental Overwrite - -**Steps:** - -1. **Identify when file changed:** - ```bash - snap-list | grep -B5 -A5 "Some change" - ``` - -2. **Find the snapshot before change:** - ```bash - snap-show 42 - snap-show 41 - ``` - -3. **Mount specific snapshot:** - ```bash - sudo mkdir -p /mnt/snapshot42 - sudo mount -t btrfs -o subvol=@/.snapshots/42/snapshot /dev/nvme0n1p2 /mnt/snapshot42 - ``` - -4. **Recover file:** - ```bash - sudo cp /mnt/snapshot42/etc/nginx/nginx.conf ~/.config/ - - # Or view diff - diff /mnt/snapshot42/etc/nginx/nginx.conf /etc/nginx/nginx.conf - ``` - -5. **Cleanup:** - ```bash - sudo umount /mnt/snapshot42 - sudo rmdir /mnt/snapshot42 - ``` - -### Scenario 3: Rollback Entire System - -**Complete recovery from snapshot:** - -```bash -# 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 - -```bash -snap-validate-service -``` - -### Check Snapper Configs - -```bash -sudo snapper list-configs - -# Detailed config -sudo snapper -c root get-config -``` - -### Boot Menu Not Updating - -```bash -# 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 - -```bash -# 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 - -```bash -# 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 - -```bash -# 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 - -```bash -# 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 - -```bash -# 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): - -```bash -# 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 - -```bash -# 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 - -```bash -# 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 | - ---- - -## See Also - -- [README.md](../README.md) - Main documentation -- [SETUP_GUIDE.md](SETUP_GUIDE.md) - Installation guide -- [Snapper Documentation](https://github.com/openSUSE/snapper) -- [Limine Snapper Sync](https://github.com/terrapkg/limine-snapper-sync)