Backup & Restore

This guide explains how to set up and manage BorgBackup for secure, efficient backups in a clan network. BorgBackup provides:

Space efficient storage of backups with deduplication
Secure, authenticated encryption
Compression: lz4, zstd, zlib, lzma or none
Mountable backups with FUSE
Easy installation on multiple platforms: Linux, macOS, BSD, …
Free software (BSD license).
Backed by a large and active open-source community.

Borgbackup Example

inventory.instances = {
  borgbackup = {
    module = {
      name = "borgbackup";
      input = "clan";
    };
    roles.client.machines."jon".settings = {
      destinations."storagebox" = {
        repo = "username@$hostname:/./borgbackup";
        rsh = ''ssh -oPort=23 -i /run/secrets/vars/borgbackup/borgbackup.ssh'';
      };
    };
    roles.server.machines = { };
  };
};

The input should be named according to your flake input. Jon is configured as a client machine with a destination pointing to a Hetzner Storage Box.

To see a list of all possible options go to borgbackup clan service

Roles

A Clan Service can have multiple roles, each role applies different nix config to the machine.

1. Client

Clients are machines that create and send backups to various destinations. Each client can have multiple backup destinations configured.

2. Server

Servers act as backup repositories, receiving and storing backups from client machines. They can be dedicated backup servers within your clan network.

Backup destinations

This service allows you to perform backups to multiple destinations. Destinations can be:

Local: Local disk storage
Server: Your own borgbackup server (using the server role)
Third-party services: Such as Hetzner's Storage Box

State management

Backups are based on states. A state defines which files should be backed up and how these files are obtained through pre/post backup and restore scripts.

Here's an example for a user application linkding:

In this example:

/data/podman/linkding is the application's data directory
/var/backup/linkding is the staging directory where data is copied for backup

clan.core.state.linkding = {
  folders = [ "/var/backup/linkding" ];

  preBackupScript = ''
    export PATH=${
      lib.makeBinPath [
        config.systemd.package
        pkgs.coreutils
        pkgs.rsync
      ]
    }

    service_status=$(systemctl is-active podman-linkding)

    if [ "$service_status" = "active" ]; then
      systemctl stop podman-linkding
      rsync -avH --delete --numeric-ids "/data/podman/linkding/" /var/backup/linkding/
      systemctl start podman-linkding
    fi
  '';

  postRestoreScript = ''
    export PATH=${
      lib.makeBinPath [
        config.systemd.package
        pkgs.coreutils
        pkgs.rsync
      ]
    }

    service_status="$(systemctl is-active podman-linkding)"

    if [ "$service_status" = "active" ]; then
      systemctl stop podman-linkding

      # Backup locally current linkding data
      cp -rp "/data/podman/linkding" "/data/podman/linkding.bak"

      # Restore from borgbackup
      rsync -avH --delete --numeric-ids /var/backup/linkding/ "/data/podman/linkding/"

      systemctl start podman-linkding
    fi
  '';
};

Managing backups

In this section we go over how to manage your collection of backups with the clan command.

Listing states

To see which files (states) will be backed up on a specific machine, use:

clan state list jon

This will show all configured states for the machine jon, for example:

· service: linkding
  folders:
  - /var/backup/linkding
  preBackupCommand: pre-backup-linkding
  postRestoreCommand: post-restore-linkding

· service: zerotier
  folders:
  - /var/lib/zerotier-one

Creating backups

To create a backup of a machine (e.g., jon), run:

clan backups create jon

This will backup all configured states (zerotier and linkding in this example) from the machine jon.

Listing available backups

To see all available backups, use:

clan backups list

This will display all backups with their timestamps:

storagebox::username@username.your-storagebox.de:/./borgbackup::jon-jon-2025-07-22T19:40:10
storagebox::username@username.your-storagebox.de:/./borgbackup::jon-jon-2025-07-23T01:00:00
storagebox::username@username.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T01:00:00
storagebox::username@username.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35

Restoring backups

For restoring a backup you have two options.

Full restoration

To restore all services from a backup:

clan backups restore jon borgbackup storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35

Partial restoration

To restore only a specific service (e.g., linkding):

clan backups restore --service linkding jon borgbackup storagebox::u444061@u444061.your-storagebox.de:/./borgbackup::jon-storagebox-2025-07-24T06:02:35