View source for Btrbk

[https://digint.ch/btrbk/ Btrbk], a tool for creating snapshots and remote backups of [[btrfs]] subvolumes.

== Setup ==

When transferring backups of root filesystem snapshots using Btrbk, it is recommended to mount the root Btrfs drive with subvolume id 5 (in this example <code>/dev/sda1</code>) to a specific mountpoint where Btrbk can operate with. So in this case all subvolumes will be available as a subdirectory in <code>/btr_pool</code>.

{{file|/etc/nixos/hardware-configuration.nix|nix|<nowiki>
fileSystems = {
  "/btr_pool" = {
    device = "/dev/sda1";
    fsType = "btrfs";
    options = [ "subvolid=5" ];
  };
};
</nowiki>}}

== Configuration ==

=== Basic example ===
Following example configuration will create a weekly incremental backup of a local Btrfs subvolume called <code>nixos</code> and sends it compressed to the remote host <code>myhost</code>. The mount point <code>/btr_pool</code>, as referenced above, contains the subvolume.

The user <code>btrbk</code> together with the private key <code>/etc/btrbk_key</code> is used for authentication.

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
services.btrbk = {
  instances."remote_myhost" = {
    onCalendar = "weekly";
    settings = {
      ssh_identity = "/etc/btrbk_key"; # NOTE: must be readable by user/group btrbk
      ssh_user = "btrbk";
      stream_compress = "lz4";
      volume."/btr_pool" = {
        target = "ssh://myhost/mnt/mybackups";
        subvolume = "nixos";
        # "nixos" could instead be an attribute set with other volumes to
        # back up and to give subvolume specific configuration.
        # See man btrbk.conf for possible options.
        /*
        subvolume = {
          home = { snapshot_create = "always"; };
          nixos = {};
        };
        */
      };
    };
  };
};
</nowiki>}}

For the remote host, configure SSH access for Btrbk:

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
services.btrbk = {
  sshAccess = [
    {
      key = "ssh-ed25519 blah";
      roles = [
        "target"
        "info"
        "receive"
      ];
    }
  ];
};
</nowiki>}}

=== Local <code>/home</code> Snapshots ===
{{Warning|This is not a backup solution alone. If the entire disk fails, local snapshots will be lost along with it.}}

If <code>/home</code> is its own subvolume and important files are backed up separately or combined with the above section, this configuration takes snapshots hourly, retains them for at least a week, and keeps weekly snapshots for two weeks under <code>/snapshots</code>.

{{file|/etc/nixos/configuration.nix|nix|<nowiki>
services.btrbk = {
  instances."home" = {
    onCalendar = "hourly";
    settings = {
      snapshot_preserve_min = "1w";
      snapshot_preserve = "2w";
      volume = {
          "/" = {
            snapshot_dir = "/snapshots";
            subvolume = "home";
          };
        };
      };
  };
};
# Btrbk does not create snapshot directories automatically, so create one here.
systemd.tmpfiles.rules = [
  "d /snapshots 0755 root root"
];
</nowiki>}}

=== Retention policy ===
The following example takes daily snapshot but won't store them forever with the given retention policy:

* '''7d''': For the most recent week, you will have a '''daily snapshot''' stored from each day.
* '''4w''': After a week, you'll only keep one snapshot per week for the next 4 weeks (so older daily snapshots get removed).
* '''12m''': After a month, the policy will keep only '''monthly snapshots''' for the next 12 months.

The option <code>snapshot_preserve_min</code>ensures that all daily snapshots from the last 7 days are preserved, regardless of the other retention rules. It's a safety net to guarantee that no daily snapshot from the past week is deleted prematurely.<syntaxhighlight lang="nix">
services.btrbk.instances."remote_myhost" = {
  onCalendar = "daily";
  settings = {
      snapshot_preserve = "7d 4w 12m";
      snapshot_preserve_min = "7d";
      target_preserve = "7d 4w 12m";
  };
};
</syntaxhighlight>This retention policy will ensure you have a balance between recent, frequent backups (daily) and older, more spaced-out backups (weekly/monthly) while preserving space.

== Manual usage ==

Manually dry running and testing a btrbk configuration

<syntaxhighlight lang="bash">
btrbk -c /etc/btrbk/remote_myhost.conf --dry-run --progress --verbose run
</syntaxhighlight>

The filename <code>remote_myhost.conf</code> references the instance name choosen in the example configuration above.

[[Category:Applications]]
[[Category:Backup]]