# BorgBackup {#module-borgbase}

*Source:* {file}`modules/services/backup/borgbackup.nix`

*Upstream documentation:* <https://borgbackup.readthedocs.io/>

[BorgBackup](https://www.borgbackup.org/) (short: Borg)
is a deduplicating backup program. Optionally, it supports compression and
authenticated encryption.

The main goal of Borg is to provide an efficient and secure way to backup
data. The data deduplication technique used makes Borg suitable for daily
backups since only changes are stored. The authenticated encryption technique
makes it suitable for backups to not fully trusted targets.

## Configuring {#module-services-backup-borgbackup-configuring}

A complete list of options for the Borgbase module may be found
[here](#opt-services.borgbackup.jobs).

## Basic usage for a local backup {#opt-services-backup-borgbackup-local-directory}

A very basic configuration for backing up to a locally accessible directory is:
```nix
{
  services.borgbackup.jobs = {
    rootBackup = {
      paths = "/";
      exclude = [
        "/nix"
        "/path/to/local/repo"
      ];
      repo = "/path/to/local/repo";
      doInit = true;
      encryption = {
        mode = "repokey";
        passphrase = "secret";
      };
      compression = "auto,lzma";
      startAt = "weekly";
    };
  };
}
```

::: {.warning}
If you do not want the passphrase to be stored in the world-readable
Nix store, use passCommand. You find an example below.
:::

## Create a borg backup server {#opt-services-backup-create-server}

You should use a different SSH key for each repository you write to,
because the specified keys are restricted to running borg serve and can only
access this single repository. You need the output of the generate pub file.

```ShellSession
# sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_my_borg_repo
# cat /run/keys/id_ed25519_my_borg_repo
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos
```

Add the following snippet to your NixOS configuration:
```nix
{
  services.borgbackup.repos = {
    my_borg_repo = {
      authorizedKeys = [
        "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos"
      ];
      path = "/var/lib/my_borg_repo";
    };
  };
}
```

## Backup to the borg repository server {#opt-services-backup-borgbackup-remote-server}

The following NixOS snippet creates an hourly backup to the service
(on the host nixos) as created in the section above. We assume
that you have stored a secret passphrasse in the file
{file}`/run/keys/borgbackup_passphrase`, which should be only
accessible by root

```nix
{
  services.borgbackup.jobs = {
    backupToLocalServer = {
      paths = [ "/etc/nixos" ];
      doInit = true;
      repo = "borg@nixos:.";
      encryption = {