nixos/modules/services/backup/borgbackup.xml

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