btrbk

Print statistics about configured subvolumes and snapshots

$ sudo btrbk stats

$ sudo btrbk list

$ sudo btrbk [[-v|--verbose]] dryrun

$ sudo btrbk --progress [[-v|--verbose]] run

$ sudo btrbk snapshot

btrbk [OPTIONS] <COMMAND> [ARGS]

Commands:
  run [OPTIONS]                      Perform backup operations as configured.
  list <TYPE> [OPTIONS]                List snapshots or backups.
  archive [OPTIONS]                  Perform archiving of expired snapshots.
  dryrun [OPTIONS]                   Show what btrbk would do without making changes.
  config dump                    Dump the parsed configuration.
  subvolume create <PATH>            Create a new Btrfs subvolume.
  subvolume destroy <PATH>          Destroy a Btrfs subvolume.
  help                             Show help message.

--config <file>
    Specifies an alternative configuration file to use.

--override <key>=<value>
    Overrides a configuration parameter directly from the command line.

--btrfs-path <path>
    Specifies the path to the btrfs executable.

--ssh-path <path>
    Specifies the path to the ssh executable for remote operations.

--verbose, -v
    Increases the verbosity of output messages.

--quiet, -q
    Suppresses most output messages, showing only errors or critical information.

--dry-run, -n
    Performs a trial run with no changes made to the system, showing what btrbk would do.

--no-backup
    Prevents btrbk from performing any actual backup (send/receive) operations.

--no-snapshot
    Prevents btrbk from creating any new snapshots.

--no-mount
    Prevents btrbk from mounting any filesystems defined in the configuration.

--force, -f
    Forces certain operations, such as destroying existing snapshots even if they are parents to others.

--compress
    Enables compression for the btrfs send stream.

--compress-force
    Forces compression for the btrfs send stream, even if not negotiated.

--preserve-uuid
    Preserves the UUID of the destination subvolume during btrfs receive.

--debug
    Activates debug output, useful for troubleshooting.

--version
    Displays the btrbk version and exits.

btrbk is a specialized backup tool designed exclusively for the Btrfs filesystem. It automates the process of creating and managing incremental backups of Btrfs subvolumes, leveraging Btrfs's native snapshotting and send/receive capabilities. Its primary function is to provide a robust and efficient solution for local and remote backups, ensuring data integrity and allowing for easy restoration.

The tool operates based on a configuration file, defining source subvolumes, target destinations, and retention policies. It automatically creates read-only snapshots of source subvolumes, then incrementally sends these snapshots to the configured backup locations (either local directories or remote hosts via SSH). btrbk handles the detection of common parent snapshots, ensuring that only the changed data is transferred, making backups highly efficient. It also manages the pruning of old snapshots according to user-defined retention rules, preventing excessive disk space consumption. Its atomic operations and Btrfs-specific design make it a reliable choice for Btrfs data protection.

btrbk is tightly coupled with the Btrfs filesystem. It is not a general-purpose backup tool and will not work on other filesystems. Proper understanding of Btrfs subvolumes, snapshots, and send/receive functionality is beneficial for effective use. Configuration is critical; errors in the configuration file can lead to unexpected behavior or data loss if not handled carefully. Root privileges are typically required for most operations, especially snapshot creation and subvolume management.

The heart of btrbk operation is its configuration file (typically `/etc/btrbk.conf`). This file defines all aspects of the backup strategy, including source subvolumes (e.g., @home, @rootfs), target destinations (local paths or remote SSH locations), and retention policies (e.g., keep 7 daily, 4 weekly, 12 monthly snapshots). It supports hierarchical definitions and includes directives for specifying global options, volume groups, and individual subvolumes. A well-structured configuration file is essential for effective and automated backups.

btrbk implements an intelligent incremental backup strategy. For each configured source subvolume, it first creates a read-only snapshot. It then determines the most recent common parent snapshot between the source and the backup destination. Using btrfs send/receive, only the changes relative to this common parent are transferred, minimizing bandwidth and storage requirements for subsequent backups. This ensures atomic and consistent backups, as the source data is static during the transfer from the snapshot. The retention policies specified in the configuration file dictate how long snapshots are kept on both the source and destination, allowing for flexible recovery points.

btrbk was created by Axel Neumann to address the need for a robust and automated backup solution specifically for the Btrfs filesystem. Developed in the early 2010s, it quickly gained traction within the Btrfs community due to its efficiency, reliability, and close integration with Btrfs native features like incremental send/receive. It provides a user-friendly abstraction over complex Btrfs commands, simplifying the creation and management of sophisticated backup strategies. The project continues to be actively maintained and is a cornerstone for many Btrfs users requiring automated snapshotting and off-site backups.

btrfs(8), ssh(1), cron(8), systemd.timer(5)