btrbk: Backup and Snapshot Tool for Btrfs

btrbk: Backup and Snapshot Tool for Btrfs

A pragmatic guide to using btrbk to manage snapshots and remote backups for btrfs subvolumes. Start with the essential commands, then learn through concrete examples and watch for common pitfalls.

Quickstart: what you can do at a glance

  • Print current statistics about configured subvolumes and snapshots:
sudo btrbk stats
  • List configured subvolumes and snapshots:
sudo btrbk list
  • See what would happen without making changes (dry run):
sudo btrbk --verbose dryrun
  • Run backups with progress and verbose output:
sudo btrbk --progress --verbose run
  • Create only snapshots for configured subvolumes:
sudo btrbk snapshot

Note: You typically need sudo because btrbk operates on subvolumes and may access system directories.

Quickstart: example workflows

1) Check configuration and current state

  • List what’s configured and what’s currently snapshotted:
sudo btrbk list
  • If you’re unsure what will happen during a run, perform a verbose dry run:
sudo btrbk --verbose dryrun

2) Do a full backup run with visibility

  • Run the backup routines with a progress bar and verbose logging:
sudo btrbk --progress --verbose run
  • After a run, print updated statistics to verify changes:
sudo btrbk stats

3) Snapshot-only operation

  • Create new snapshots for all configured subvolumes without invoking backups:
sudo btrbk snapshot

Common pitfalls and how to avoid them

  • Running without sudo or proper permissions: btrbk needs access to subvolumes and backup destinations.
  • Misconfigured subvolumes or missing btrfs root: verify with btrfs subvolume list / and ensure paths in your config exist.
  • Relying on stale cache: the cache may be out of date; consider updating or re-running a dryrun to see current expectations.
  • Not validating remote backups: ensure your backup destination is reachable and writable, and test restores regularly.
  • Forgetting to check logs: if things go wrong, check system logs or btrbk output for error details.

Best practices

  • Start with a dry run to understand changes before committing to a real run.
  • Keep snapshots tidy by pruning old ones as needed.
  • Regularly verify backups and ensure the remote destination is accessible.
  • Automate with cron/systemd timers but monitor the job output so failures don’t go unnoticed.

Troubleshooting quick references

  • “Permission denied” errors: confirm you’re using sudo and that your user has appropriate access to the subvolumes and backup destinations.
  • “No such file or directory” for subvolumes: double-check paths in the btrbk configuration and ensure subvolumes exist.
  • Backup not progressing: inspect --progress output and check the remote destination’s availability; test connectivity and credentials.

Where to learn more

See Also