nixos/modules/services/backup/borgbackup.md

   1 # BorgBackup {#module-borgbase}
   2
   3 *Source:* {file}`modules/services/backup/borgbackup.nix`
   4
   5 *Upstream documentation:* <https://borgbackup.readthedocs.io/>
   6
   7 [BorgBackup](https://www.borgbackup.org/) (short: Borg)
   8 is a deduplicating backup program. Optionally, it supports compression and
   9 authenticated encryption.
  10
  11 The main goal of Borg is to provide an efficient and secure way to backup
  12 data. The data deduplication technique used makes Borg suitable for daily
  13 backups since only changes are stored. The authenticated encryption technique
  14 makes it suitable for backups to not fully trusted targets.
  15
  16 ## Configuring {#module-services-backup-borgbackup-configuring}
  17
  18 A complete list of options for the Borgbase module may be found
  19 [here](#opt-services.borgbackup.jobs).
  20
  21 ## Basic usage for a local backup {#opt-services-backup-borgbackup-local-directory}
  22
  23 A very basic configuration for backing up to a locally accessible directory is:
  24 ```nix
  25 {
  26     opt.services.borgbackup.jobs = {
  27       rootBackup = {
  28         paths = "/";
  29         exclude = [ "/nix" "/path/to/local/repo" ];
  30         repo = "/path/to/local/repo";
  31         doInit = true;
  32         encryption = {
  33           mode = "repokey";
  34           passphrase = "secret";
  35         };
  36         compression = "auto,lzma";
  37         startAt = "weekly";
  38       };
  39     };
  40 }
  41 ```
  42
  43 ::: {.warning}
  44 If you do not want the passphrase to be stored in the world-readable
  45 Nix store, use passCommand. You find an example below.
  46 :::
  47
  48 ## Create a borg backup server {#opt-services-backup-create-server}
  49
  50 You should use a different SSH key for each repository you write to,
  51 because the specified keys are restricted to running borg serve and can only
  52 access this single repository. You need the output of the generate pub file.
  53
  54 ```ShellSession
  55 # sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_my_borg_repo
  56 # cat /run/keys/id_ed25519_my_borg_repo
  57 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos
  58 ```
  59
  60 Add the following snippet to your NixOS configuration:
  61 ```nix
  62 {
  63   services.borgbackup.repos = {
  64     my_borg_repo = {
  65       authorizedKeys = [
  66         "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos"
  67       ] ;
  68       path = "/var/lib/my_borg_repo" ;
  69     };
  70   };
  71 }
  72 ```
  73
  74 ## Backup to the borg repository server {#opt-services-backup-borgbackup-remote-server}
  75
  76 The following NixOS snippet creates an hourly backup to the service
  77 (on the host nixos) as created in the section above. We assume
  78 that you have stored a secret passphrasse in the file
  79 {file}`/run/keys/borgbackup_passphrase`, which should be only
  80 accessible by root
  81
  82 ```nix
  83 {
  84   services.borgbackup.jobs = {
  85     backupToLocalServer = {
  86       paths = [ "/etc/nixos" ];
  87       doInit = true;
  88       repo =  "borg@nixos:." ;
  89       encryption = {
  90         mode = "repokey-blake2";
  91         passCommand = "cat /run/keys/borgbackup_passphrase";
  92       };
  93       environment = { BORG_RSH = "ssh -i /run/keys/id_ed25519_my_borg_repo"; };
  94       compression = "auto,lzma";
  95       startAt = "hourly";
  96     };
  97   };
  98 }
  99 ```
 100
 101 The following few commands (run as root) let you test your backup.
 102 ```
 103 > nixos-rebuild switch
 104 ...restarting the following units: polkit.service
 105 > systemctl restart borgbackup-job-backupToLocalServer
 106 > sleep 10
 107 > systemctl restart borgbackup-job-backupToLocalServer
 108 > export BORG_PASSPHRASE=topSecrect
 109 > borg list --rsh='ssh -i /run/keys/id_ed25519_my_borg_repo' borg@nixos:.
 110 nixos-backupToLocalServer-2020-03-30T21:46:17 Mon, 2020-03-30 21:46:19 [84feb97710954931ca384182f5f3cb90665f35cef214760abd7350fb064786ac]
 111 nixos-backupToLocalServer-2020-03-30T21:46:30 Mon, 2020-03-30 21:46:32 [e77321694ecd160ca2228611747c6ad1be177d6e0d894538898de7a2621b6e68]
 112 ```
 113
 114 ## Backup to a hosting service {#opt-services-backup-borgbackup-borgbase}
 115
 116 Several companies offer [(paid) hosting services](https://www.borgbackup.org/support/commercial.html)
 117 for Borg repositories.
 118
 119 To backup your home directory to borgbase you have to:
 120
 121   - Generate a SSH key without a password, to access the remote server. E.g.
 122
 123         sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_borgbase
 124
 125   - Create the repository on the server by following the instructions for your
 126     hosting server.
 127   - Initialize the repository on the server. Eg.
 128
 129         sudo borg init --encryption=repokey-blake2  \
 130             --rsh "ssh -i /run/keys/id_ed25519_borgbase" \
 131             zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo
 132
 133   - Add it to your NixOS configuration, e.g.
 134
 135         {
 136             services.borgbackup.jobs = {
 137             my_Remote_Backup = {
 138                 paths = [ "/" ];
 139                 exclude = [ "/nix" "'**/.cache'" ];
 140                 repo =  "zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo";
 141                   encryption = {
 142                   mode = "repokey-blake2";
 143                   passCommand = "cat /run/keys/borgbackup_passphrase";
 144                 };
 145                 environment = { BORG_RSH = "ssh -i /run/keys/id_ed25519_borgbase"; };
 146                 compression = "auto,lzma";
 147                 startAt = "daily";
 148             };
 149           };
 150         }}
 151
 152 ## Vorta backup client for the desktop {#opt-services-backup-borgbackup-vorta}
 153
 154 Vorta is a backup client for macOS and Linux desktops. It integrates the
 155 mighty BorgBackup with your desktop environment to protect your data from
 156 disk failure, ransomware and theft.
 157
 158 It can be installed in NixOS e.g. by adding `pkgs.vorta`
 159 to [](#opt-environment.systemPackages).
 160
 161 Details about using Vorta can be found under
 162 [https://vorta.borgbase.com](https://vorta.borgbase.com/usage) .