btrfs-backup-ng-snapper - Man Page
back up and restore snapper-managed snapshots
Synopsis
btrfs-backup-ng snapper detect [--json]
btrfs-backup-ng snapper list [--config NAME] [--type TYPE] [--json]
btrfs-backup-ng snapper backup CONFIG TARGET [OPTIONS]
btrfs-backup-ng snapper restore SOURCE [--list | --snapshot NUM | --all] CONFIG
btrfs-backup-ng snapper status [--config NAME] [--target PATH] [--json]
btrfs-backup-ng snapper generate-config [CONFIG...] [OPTIONS]
Description
Back up and restore snapshots managed by Snapper. This integration enables btrfs-backup-ng to work with existing Snapper configurations, preserving Snapper's metadata (info.xml) and directory structure.
Snapper is a tool for managing btrfs snapshots, commonly used on openSUSE, Fedora, and Arch Linux. When you use Snapper for local snapshot management, this command allows you to replicate those snapshots to remote backup storage.
Subcommands
detect
Discover Snapper configurations on the system.
btrfs-backup-ng snapper detect [--json]
Scans /etc/snapper/configs/ for Snapper configurations and displays their subvolumes, snapshot directories, and validity status.
- --json
Output in JSON format for scripting.
list
List snapshots for one or all Snapper configurations.
- --config NAME
List snapshots only for the specified Snapper config. If omitted, lists snapshots for all configs.
- --type TYPE
Filter by snapshot type. Can be specified multiple times. Valid types: single (standalone/timeline), pre (before package operations), post (after package operations).
- --json
Output in JSON format.
backup
Back up Snapper snapshots to a target location.
btrfs-backup-ng snapper backup CONFIG TARGET [OPTIONS]
- CONFIG
Snapper configuration name (e.g., "root", "home").
- TARGET
Destination path. Can be local (e.g., /mnt/backup/root) or SSH (e.g., ssh://user@host:/backups/root).
Options:
- --snapshot NUM
Back up only the specified snapshot number.
- --type TYPE
Filter by snapshot type. Can be specified multiple times.
- --min-age DURATION
Skip snapshots younger than the specified age. Format: 30m, 1h, 1d. Useful to avoid backing up incomplete pre/post pairs.
- --compress METHOD
Compression for remote transfers. Valid: none, zstd, gzip, lz4, pigz, lzop. Default: zstd for SSH targets, none for local.
- --rate-limit RATE
Bandwidth limit for transfers. Examples: 10M, 1G, 500K.
- --dry-run
Show what would be backed up without making changes.
- -v, --verbose
Enable verbose output.
restore
Restore Snapper snapshots from a backup location.
btrfs-backup-ng snapper restore SOURCE [OPTIONS] CONFIG
- SOURCE
Backup location to restore from. Can be local or SSH URL.
- CONFIG
Local Snapper configuration name to restore into.
Options:
- -l, --list
List available backups at the source location.
- --snapshot NUM
Restore specific snapshot number. Can be specified multiple times.
- -a, --all
Restore all available backups.
- --dry-run
Show what would be restored without making changes.
- --json
Output in JSON format (with --list).
status
Show backup status for Snapper configurations.
btrfs-backup-ng snapper status [--config NAME] [--target PATH] [--json]
- --config NAME
Show status for specific config only.
- --target PATH
Check backup status at the specified target. Shows which snapshots are backed up vs pending.
- --json
Output in JSON format.
generate-config
Generate TOML configuration for Snapper volumes.
btrfs-backup-ng snapper generate-config [CONFIG...] [OPTIONS]
- CONFIG
Snapper configuration names to include. If omitted, generates for all configs.
Options:
- --target PATH
Target path for backups. The config name will be appended (e.g., /mnt/backup becomes /mnt/backup/root for the root config).
- --type TYPE
Snapshot types to include. Can be specified multiple times. Default: single.
- --min-age DURATION
Minimum snapshot age. Default: 0.
- -o, --output FILE
Write configuration to file.
- --append FILE
Append to existing configuration file.
- --ssh-sudo
Add ssh_sudo = true to SSH targets.
- --json
Output in JSON format.
Backup Directory Layout
Snapper backups preserve the native Snapper directory structure:
/backups/root/.snapshots/
├── 559/
│ ├── info.xml # Snapper metadata
│ └── snapshot/ # btrfs subvolume
├── 560/
│ ├── info.xml
│ └── snapshot/
└── 561/
├── info.xml
└── snapshot/This layout enables direct restoration back into Snapper-managed volumes.
Configuration
For automated backups, add Snapper volumes to your config.toml:
[[volumes]] path = "/" source = "snapper" [volumes.snapper] config_name = "root" include_types = ["single", "pre", "post"] min_age = "1h" [[volumes.targets]] path = "ssh://backup@server:/backups/root" ssh_sudo = true compress = "zstd"
Then run: btrfs-backup-ng run
Configuration Options
- config_name
Snapper config name (e.g., "root", "home") or "auto" to detect.
- include_types
Snapshot types to include: "single", "pre", "post".
- exclude_cleanup
Cleanup algorithms to skip: "number", "timeline", "empty-pre-post".
- min_age
Minimum snapshot age before backing up (e.g., "30m", "1h", "1d").
Snapshot Types
- single
Standalone snapshots created manually or by timeline (e.g., hourly snapshots).
- pre
Snapshots created before package manager operations (zypper, dnf, etc.).
- post
Snapshots created after package manager operations.
Examples
- Detect Snapper configurations:
btrfs-backup-ng snapper detect
- List all snapshots for root config:
btrfs-backup-ng snapper list --config root
- List only timeline snapshots:
btrfs-backup-ng snapper list --type single
- Backup root config to local drive:
sudo btrfs-backup-ng snapper backup root /mnt/backup/root
- Backup to remote server with compression:
sudo btrfs-backup-ng snapper backup root ssh://backup@server:/backups/root
- Backup specific snapshot:
sudo btrfs-backup-ng snapper backup root /mnt/backup/root --snapshot 559
- Backup only timeline snapshots older than 1 hour:
sudo btrfs-backup-ng snapper backup root /mnt/backup --type single --min-age 1h
- Dry run to see what would be backed up:
sudo btrfs-backup-ng snapper backup root /mnt/backup --dry-run
- List backups at a location:
btrfs-backup-ng snapper restore --list /mnt/backup/root
- Restore a specific snapshot:
sudo btrfs-backup-ng snapper restore /mnt/backup/root --snapshot 559 root
- Restore all backups:
sudo btrfs-backup-ng snapper restore /mnt/backup/root --all root
- Check backup status:
btrfs-backup-ng snapper status --target /mnt/backup/root
- Generate config for root:
btrfs-backup-ng snapper generate-config root --target ssh://server:/backups
- Generate and save config:
btrfs-backup-ng snapper generate-config root --target /mnt/backup -o snapper.toml
- Append to existing config:
btrfs-backup-ng snapper generate-config root --append ~/.config/btrfs-backup-ng/config.toml
Incremental Transfers
Both backup and restore operations use incremental btrfs send/receive when possible. The commands automatically detect available parent snapshots and use the most efficient transfer method:
Snapshot 559: 2.1 GB (full, no parent available) Snapshot 560: 156 MB (incremental from 559) Snapshot 561: 89 MB (incremental from 560)
Exit Status
- 0
Success
- 1
Failure (Snapper not found, config not found, transfer error, etc.)
Files
- /etc/snapper/configs/
Snapper configuration files
- /.snapshots/
Default snapshot directory for root config
- /home/.snapshots/
Default snapshot directory for home config
- .snapshots/{num}/info.xml
Snapper metadata file for each snapshot
- .snapshots/{num}/snapshot/
The actual btrfs snapshot subvolume
See Also
btrfs-backup-ng(1), btrfs-backup-ng-restore(1), snapper(8), btrfs-send(8), btrfs-receive(8)
Notes
Snapper must be installed and configured on the source system. The backup destination can be any btrfs filesystem - Snapper is not required there.
Restored snapshots are assigned new snapshot numbers by Snapper on the destination system. The original metadata (type, description, date) is preserved in info.xml.