Btrfs Snapper

---
name: btrfs-snapper
description: "Btrfs filesystem and Snapper snapshot management on SUSE Linux Enterprise Server: Copy-on-Write architecture, subvolume management, RAID profiles, snapshot creation and rollback, compression (zstd/lzo/zlib), quota groups (qgroups), Snapper retention policies, GRUB snapshot integration, btrfs send/receive, maintenance (scrub, balance, defragment), and ENOSPC/fragmentation/qgroup troubleshooting. Use when: \"Btrfs\", \"btrfs\", \"Snapper\", \"snapper\", \"snapshot\", \"rollback\", \"subvolume\", \"CoW\", \"copy-on-write\", \"btrfs balance\", \"btrfs scrub\", \"qgroup\". Do NOT use for enterprise SAN/NAS storage, dedup, or non-SLES Btrfs deployments — use the storage plugin. Do NOT use for general SLES administration — use the `sles` skill."
license: MIT
---

# Btrfs and Snapper (SLES)

This skill covers Btrfs filesystem management and Snapper snapshot operations on SUSE Linux Enterprise Server. It provides deep knowledge of:

- Copy-on-Write (CoW) architecture: B-tree forest, atomic writes, write amplification
- Subvolume management: SLES default flat layout, mounting, nesting strategies
- RAID profiles: RAID 1, RAID 10, single, dup; RAID 5/6 write hole warning
- Snapshot creation, management, and space accounting (shared vs exclusive extents)
- Compression: zstd, lzo, zlib algorithms with per-file and per-mount configuration
- Quota groups (qgroups): per-subvolume space accounting and limits
- Snapper configuration: retention policies, timeline/number/empty-pre-post cleanup
- Zypper integration: automatic pre/post snapshot pairs for package operations
- System rollback: Snapper rollback workflow, GRUB snapshot boot entries
- Btrfs send/receive: incremental backup and disaster recovery
- Maintenance: scrub (data integrity), balance (space reclamation), defragmentation
- Troubleshooting: ENOSPC, metadata saturation, fragmentation, qgroup overhead, corruption recovery

When a question involves general SLES administration, defer to the `sles` skill.

## How to Approach Tasks

Route by request type: **troubleshooting** → `references/diagnostics.md`; **architecture** → `references/architecture.md`; **best practices/config** → `references/best-practices.md`; **health check** → the diagnostic scripts.

**Identify the Btrfs/Snapper context first** — single vs multi-device layout, default subvolume layout, whether Snapper is configured, and whether qgroups are enabled. Reason from CoW implications, snapshot space accounting, and the metadata vs data block group distinction. Warn before destructive operations (balance on production, defragment with snapshots). Validate with `btrfs device stats`, scrub status, and `snapper list`.

## Core Expertise

### Copy-on-Write (CoW)

Every write creates a new copy of modified data at a new location. The old location is freed only after the new write is committed. The on-disk format is a forest of B-trees updated atomically via the superblock.

**Performance implications**: CoW introduces write amplification for random write workloads. Mitigation: use `nodatacow` mount option or `chattr +C` per file/directory for VM images and databases.

**Fragmentation**: Files fragment as CoW writes scatter extents. Defragmentation with `btrfs filesystem defragment` breaks CoW sharing between snapshots -- verify space impact first.

**Checksums**: Every data and metadata block has a checksum. Supported algorithms: crc32c, xxhash (SLES 15 SP3+), sha256, blake2b. Set at mkfs time.

**Self-healing**: On RAID 1/10/DUP with checksum failure, Btrfs reads the good copy and rewrites it to the corrupt location transparently.

### Subvolumes

A subvolume is an independently mountable B-tree within the Btrfs filesystem. SLES uses a flat layout where all subvolumes are children of the top-level container (subvolid=5).

```bash
btrfs subvolume list /                    # List all subvolumes
btrfs subvolume show /home                # Details on a subvolume
btrfs subvolume create /data              # Create new subvolume
btrfs subvolume delete /data              # Delete subvolume
btrfs subvolume get-default /             # Current default subvolume
```

Key design: `/var`, `/home`, `/tmp` are excluded from root snapshots via separate subvolumes. Only OS and configuration in `/etc`, `/usr`, `/boot` are rolled back.

### SLES Default Subvolume Layout

```
/                   → subvolume @          (snapshotted by Snapper)
/home               → subvolume @/home     (excluded from snapshots)
/var                → subvolume @/var      (excluded)
/var/log            → subvolume @/var/log  (excluded)
/opt                → subvolume @/opt      (excluded)
/srv                → subvolume @/srv      (excluded)
/tmp                → subvolume @/tmp      (excluded)
/usr/local          → subvolume @/usr/local (excluded)
/.snapshots         → subvolume            (Snapper storage)
```

### RAID Profiles

| Profile | Min Devices | Production Ready |
|---|---|---|
| single | 1 | Yes |
| dup | 1 | Yes (metadata default) |
| RAID 1 | 2 | Yes |
| RAID 1C3 | 3 | Yes |
| RAID 10 | 4 | Yes |
| RAID 5 | 3 | NO -- write hole bug |
| RAID 6 | 4 | NO -- write hole bug |

**Never use RAID 5/6 in production.** Use Linux MD RAID (mdadm) underneath Btrfs if parity RAID is required.

### Snapshots and Snapper

```bash
# Snapper operations
snapper list                              # List all snapshots
snapper create -d "Before change"         # Manual snapshot
snapper status 42..43                     # Files changed between snapshots
snapper diff 42..43                       # Unified diff
snapper rollback 42                       # Roll back to snapshot 42
snapper undochange 42..43 /etc/file       # Undo specific file changes
snapper delete 40-45                      # Delete range
snapper cleanup number                    # Run number cleanup now
snapper cleanup timeline                  # Run timeline cleanup now
```

Snapper integrates with zypper (automatic pre/post pairs) and GRUB (boot-time snapshot selection).

### Compression

```bash
# Mount-level compression (new writes)
mount -o compress=zstd:3 /dev/sda2 /

# Per-subvolume default property
btrfs property set / compression zstd

# Check compression ratio
compsize /usr                             # Requires btrfs-compsize package
```

Recommended: `compress=zstd:3` for most workloads. Use `chattr +m` or `nodatacow` for already-compressed data.

### Quota Groups (qgroups)

```bash
btrfs quota enable /                      # Enable qgroup accounting
btrfs quota rescan /                      # Rebuild accounting
btrfs qgroup show -reF /                  # Per-subvolume exclusive usage
btrfs qgroup limit 10G 0/256 /           # Set 10G limit on subvolume 256
```

**Performance warning**: Qgroups add 10-30% write overhead on systems with many snapshots. Disable with `btrfs quota disable /` if snapshot size reporting is not needed.

### System Rollback

Two rollback paths:
1. **Online** (system boots): `snapper rollback <N>` then reboot
2. **Offline** (system broken): Boot from GRUB snapshot entry, then `snapper rollback`

How rollback works:
1. Current writable root is snapshot as read-only backup
2. Target snapshot is snapshot again as new writable subvolume
3. Btrfs default subvolume updated to the new writable copy
4. System reboots into the restored state

### Btrfs send/receive (Backup)

```bash
# Full send to backup device
btrfs send /.snapshots/42/snapshot | btrfs receive /mnt/backup/

# Incremental send (parent must exist on destination)
btrfs send -p /.snapshots/41/snapshot /.snapshots/42/snapshot | btrfs receive /mnt/backup/

# Over SSH
btrfs send -p /.snapshots/41/snapshot /.snapshots/42/snapshot | \
  ssh backup-host "btrfs receive /mnt/backup/"
```

**Critical**: Snapshots are NOT backups. They reside on the same physical device. Always maintain off-device copies.

## Troubleshooting Decision Tree

```
1. "No space left" but df shows free space?
   → Metadata saturation: btrfs filesystem usage /
   → Fix: btrfs balance start -musage=50 /

2. Slow write performance?
   → Check qgroup overhead: btrfs qgroup show / | wc -l
   → Check snapshot count: btrfs subvolume list / | wc -l
   → Fix: btrfs quota disable / or snapper cleanup number

3. Scrub found errors?
   → Check device stats: btrfs device stats /
   → If RAID 1: btrfs replace start /dev/bad /dev/new /
   → If single: restore from backup

4. System won't boot after update?
   → Boot GRUB snapshot entry
   → Run: snapper rollback && reboot

5. GRUB snapshot entries missing?
   → rpm -q grub2-snapper-plugin
   → grub2-mkconfig -o /boot/grub2/grub.cfg
```

## Common Pitfalls

**1. Running btrfs filesystem defragment on subvolumes with active snapshots**
Defragmentation breaks CoW sharing. Files that were shared between snapshots become unshared, potentially doubling disk usage. Verify space impact before defragmenting.

**2. Using Btrfs RAID 5/6 in production**
Write hole bug can cause silent data corruption during power failure. Use mdadm RAID underneath Btrfs instead.

**3. Ignoring qgroup overhead on high-IOPS systems**
Each write must update qgroup accounting trees. On systems with 50+ snapshots, consider disabling qgroups.

**4. Not monitoring metadata block group usage separately from data**
`df` reports total filesystem space, not per-block-group. Metadata can fill independently, causing ENOSPC with apparent free space. Monitor with `btrfs filesystem usage /`.

**5. Assuming snapshots protect against hardware failure**
Snapshots reside on the same device. Use `btrfs send/receive` or rsync to separate media for actual backup.

## Reference Files

- `references/architecture.md` -- CoW, subvolumes, RAID, compression, qgroups. Read for "how does X work" questions.
- `references/best-practices.md` -- Snapshot policies, maintenance schedules, backup integration. Read for configuration and planning.
- `references/diagnostics.md` -- Health monitoring, ENOSPC troubleshooting, fragmentation, qgroup overhead, corruption recovery. Read when troubleshooting.

## Diagnostic Scripts

| Script | Purpose |
|---|---|
| `scripts/01-btrfs-status.sh` | Filesystem info, device stats, allocation, compression ratio, error counters |
| `scripts/02-snapshot-inventory.sh` | Snapper snapshot list, age distribution, space usage, cleanup config |
| `scripts/03-rollback-test.sh` | Rollback readiness: default subvolume, GRUB entries, snapshot chain |
| `scripts/04-maintenance.sh` | Scrub status, balance recommendation, timer health, cleanup actions |