btrfs-backup-ng-restore - Man Page

restore snapshots from backup location

Synopsis

btrfs-backup-ng restore [Options] SOURCE DESTINATION btrfs-backup-ng restore --list SOURCE btrfs-backup-ng restore --volume PATH --to DESTINATION btrfs-backup-ng restore --list-volumes btrfs-backup-ng restore --status SOURCE

Description

Pull snapshots from backup storage back to a local system. This command enables disaster recovery, migration between machines, and point-in-time restoration.

The restore command automatically handles incremental chains, ensuring all parent snapshots required for a successful restore are transferred.

Arguments

SOURCE: Backup location to restore from. Can be a local path (e.g., /mnt/backup/home) or an SSH URL (e.g., ssh://user@host:/path/to/backup).
DESTINATION: Local path to restore snapshots to. Must be on a btrfs filesystem.

Options

Listing and Selection

-l, --list: List available snapshots at backup location without restoring.
-s, --snapshot NAME: Restore a specific snapshot by name.
--before DATETIME: Restore the snapshot closest to the specified time. Format: YYYY-MM-DD or YYYY-MM-DD HH:MM:SS.
-a, --all: Restore all snapshots from the backup location (full mirror).
-i, --interactive: Interactively select which snapshot to restore from a list.

Transfer Options

--dry-run: Show what would be restored without making any changes.
--no-incremental: Force full transfers instead of incremental. Use when incremental chain is broken.
--compress METHOD: Compression method for transfers. Valid methods: none, zstd, gzip, lz4, pigz, lzop.
--rate-limit RATE: Bandwidth limit for transfers. Examples: 10M, 1G, 500K.
--progress: Show progress bars during transfers.
--no-progress: Disable progress bars.

Safety Options

--overwrite: Overwrite existing snapshots at destination instead of skipping them.
--in-place: Restore to the original location. This is dangerous and requires --yes-i-know-what-i-am-doing.
--yes-i-know-what-i-am-doing: Confirm dangerous operations like in-place restore.

SSH Options

--ssh-sudo: Use sudo for btrfs commands on the remote host.
--ssh-key FILE: Path to SSH private key file.

Other Options

--prefix PREFIX: Filter snapshots by prefix (e.g., "home-" to only show home snapshots).
--no-fs-checks: Skip btrfs subvolume verification. Needed when backup directories are regular directories rather than btrfs subvolumes.

Config-Driven Restore Options

-c, --config FILE: Path to configuration file.
--volume PATH: Restore backups for volume defined in config (e.g., /home). Uses the backup target(s) configured for that volume.
--target INDEX: Target index to restore from (0-based). Default: first target (0). Use with --volume to select which backup target to restore from.
--to PATH: Destination path for config-driven restore. Required when using --volume.
--list-volumes: List volumes and their backup targets from the configuration file.

Recovery Options

--status: Show status of locks and incomplete restores at the backup location.
--unlock [LOCK_ID]: Unlock stuck restore sessions. Use "all" to unlock all restore locks, or specify a specific lock ID.
--cleanup: Clean up partial/incomplete snapshot restores at the destination.

Restore Strategies

Strategy 1: Direct Restore (Default)

Restore the latest snapshot directly:

btrfs-backup-ng restore /mnt/backup/home /mnt/restore \
    --prefix "home-" --no-fs-checks

Strategy 2: Specific Snapshot

Restore a specific point in time:

btrfs-backup-ng restore /mnt/backup/home /mnt/restore \
    --snapshot home-20260101-120000 --no-fs-checks

Strategy 3: Interactive Selection

Choose from a list:

btrfs-backup-ng restore /mnt/backup/home /mnt/restore \
    --interactive --no-fs-checks

Strategy 4: Full Mirror

Restore all snapshots:

btrfs-backup-ng restore /mnt/backup/home /mnt/restore \
    --all --no-fs-checks

Examples

List available snapshots:: btrfs-backup-ng restore --list /mnt/backup/home --no-fs-checks
Restore latest snapshot from local backup:: btrfs-backup-ng restore /mnt/backup/home /mnt/restore --no-fs-checks
Restore from SSH backup with sudo:: btrfs-backup-ng restore ssh://backup@server:/backups/home /mnt/restore --ssh-sudo
Restore specific snapshot:: btrfs-backup-ng restore /mnt/backup/home /mnt/restore --snapshot home-20260101-120000
Restore snapshot closest to a date:: btrfs-backup-ng restore /mnt/backup/home /mnt/restore --before 2026-01-01 12:00
Check for stuck locks:: btrfs-backup-ng restore --status /mnt/backup/home --no-fs-checks
Unlock all stuck restore sessions:: btrfs-backup-ng restore --unlock all /mnt/backup/home --no-fs-checks
Clean up partial restores:: btrfs-backup-ng restore --cleanup /mnt/restore
List configured volumes and targets:: btrfs-backup-ng restore --list-volumes
List snapshots for a configured volume:: btrfs-backup-ng restore --volume /home --list
Restore using config (knows backup location):: btrfs-backup-ng restore --volume /home --to /mnt/restore
Restore from second configured target:: btrfs-backup-ng restore --volume /home --target 1 --to /mnt/restore

Incremental Chains

When restoring a snapshot that was created incrementally, all parent snapshots in the chain must also be restored. The restore command automatically detects and transfers the required chain.

Example chain:

snap-1 (full) -> snap-2 (incr) -> snap-3 (incr) -> snap-4 (incr)

To restore snap-4, snapshots 1, 2, 3, and 4 are all transferred.

Recovery from Failures

If a restore is interrupted:

Check status: btrfs-backup-ng restore --status SOURCE
Unlock any stuck sessions: btrfs-backup-ng restore --unlock all SOURCE
Clean up partial restores: btrfs-backup-ng restore --cleanup DESTINATION
Retry the restore

Referenced By

btrfs-backup-ng(1), btrfs-backup-ng-snapper(1), btrfs-backup-ng-verify(1).

January 2026 btrfs-backup-ng