alee/dotfiles
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Auto-sync from catchthesethighs

Browse Source
This commit is contained in:
adlee-was-taken
2025-12-21 23:44:55 -05:00
parent f6b04bf47d
commit e1fe7bdffd
1 changed files with 0 additions and 732 deletions
Download Patch File Download Diff File Expand all files Collapse all files

732
docs/SNAPPER (1).md
View File

@@ -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)