diff options
Diffstat (limited to 'nixos/modules/services/backup/borgbackup.xml')
| -rw-r--r-- | nixos/modules/services/backup/borgbackup.xml | 209 |
1 files changed, 209 insertions, 0 deletions
diff --git a/nixos/modules/services/backup/borgbackup.xml b/nixos/modules/services/backup/borgbackup.xml new file mode 100644 index 00000000000..8f623c93656 --- /dev/null +++ b/nixos/modules/services/backup/borgbackup.xml @@ -0,0 +1,209 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="module-borgbase"> + <title>BorgBackup</title> + <para> + <emphasis>Source:</emphasis> + <filename>modules/services/backup/borgbackup.nix</filename> + </para> + <para> + <emphasis>Upstream documentation:</emphasis> + <link xlink:href="https://borgbackup.readthedocs.io/"/> + </para> + <para> + <link xlink:href="https://www.borgbackup.org/">BorgBackup</link> (short: Borg) + is a deduplicating backup program. Optionally, it supports compression and + authenticated encryption. + </para> + <para> + 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. + </para> + <section xml:id="module-services-backup-borgbackup-configuring"> + <title>Configuring</title> + <para> + A complete list of options for the Borgbase module may be found + <link linkend="opt-services.borgbackup.jobs">here</link>. + </para> +</section> + <section xml:id="opt-services-backup-borgbackup-local-directory"> + <title>Basic usage for a local backup</title> + + <para> + A very basic configuration for backing up to a locally accessible directory + is: +<programlisting> +{ + opt.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"; + }; + } + }; +}</programlisting> + </para> + <warning> + <para> + If you do not want the passphrase to be stored in the world-readable + Nix store, use passCommand. You find an example below. + </para> + </warning> + </section> +<section xml:id="opt-services-backup-create-server"> + <title>Create a borg backup server</title> + <para>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. + </para> + <para> +<screen> +<prompt># </prompt>sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_my_borg_repo +<prompt># </prompt>cat /run/keys/id_ed25519_my_borg_repo +ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos</screen> + </para> + <para> + Add the following snippet to your NixOS configuration: + <programlisting> +{ + services.borgbackup.repos = { + my_borg_repo = { + authorizedKeys = [ + "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos" + ] ; + path = "/var/lib/my_borg_repo" ; + }; + }; +}</programlisting> + </para> +</section> + + <section xml:id="opt-services-backup-borgbackup-remote-server"> + <title>Backup to the borg repository server</title> + <para>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 + <code>/run/keys/borgbackup_passphrase</code>, which should be only + accessible by root + </para> + <para> + <programlisting> +{ + services.borgbackup.jobs = { + backupToLocalServer = { + paths = [ "/etc/nixos" ]; + doInit = true; + repo = "borg@nixos:." ; + encryption = { + mode = "repokey-blake2"; + passCommand = "cat /run/keys/borgbackup_passphrase"; + }; + environment = { BORG_RSH = "ssh -i /run/keys/id_ed25519_my_borg_repo"; }; + compression = "auto,lzma"; + startAt = "hourly"; + }; + }; +};</programlisting> + </para> + <para>The following few commands (run as root) let you test your backup. + <programlisting> +> nixos-rebuild switch +...restarting the following units: polkit.service +> systemctl restart borgbackup-job-backupToLocalServer +> sleep 10 +> systemctl restart borgbackup-job-backupToLocalServer +> export BORG_PASSPHRASE=topSecrect +> borg list --rsh='ssh -i /run/keys/id_ed25519_my_borg_repo' borg@nixos:. +nixos-backupToLocalServer-2020-03-30T21:46:17 Mon, 2020-03-30 21:46:19 [84feb97710954931ca384182f5f3cb90665f35cef214760abd7350fb064786ac] +nixos-backupToLocalServer-2020-03-30T21:46:30 Mon, 2020-03-30 21:46:32 [e77321694ecd160ca2228611747c6ad1be177d6e0d894538898de7a2621b6e68]</programlisting> + </para> +</section> + + <section xml:id="opt-services-backup-borgbackup-borgbase"> + <title>Backup to a hosting service</title> + + <para> + Several companies offer <link + xlink:href="https://www.borgbackup.org/support/commercial.html">(paid) + hosting services</link> for Borg repositories. + </para> + <para> + To backup your home directory to borgbase you have to: + </para> + <itemizedlist> + <listitem> + <para> + Generate a SSH key without a password, to access the remote server. E.g. + </para> + <para> + <programlisting>sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_borgbase</programlisting> + </para> + </listitem> + <listitem> + <para> + Create the repository on the server by following the instructions for your + hosting server. + </para> + </listitem> + <listitem> + <para> + Initialize the repository on the server. Eg. + <programlisting> +sudo borg init --encryption=repokey-blake2 \ + -rsh "ssh -i /run/keys/id_ed25519_borgbase" \ + zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo</programlisting> + </para> + </listitem> + <listitem> +<para>Add it to your NixOS configuration, e.g. +<programlisting> +{ + services.borgbackup.jobs = { + my_Remote_Backup = { + paths = [ "/" ]; + exclude = [ "/nix" "'**/.cache'" ]; + repo = "zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo"; + encryption = { + mode = "repokey-blake2"; + passCommand = "cat /run/keys/borgbackup_passphrase"; + }; + BORG_RSH = "ssh -i /run/keys/id_ed25519_borgbase"; + compression = "auto,lzma"; + startAt = "daily"; + }; + }; +}}</programlisting> + </para> + </listitem> +</itemizedlist> + </section> + <section xml:id="opt-services-backup-borgbackup-vorta"> + <title>Vorta backup client for the desktop</title> + <para> + Vorta is a backup client for macOS and Linux desktops. It integrates the + mighty BorgBackup with your desktop environment to protect your data from + disk failure, ransomware and theft. + </para> + <para> + It can be installed in NixOS e.g. by adding <package>pkgs.vorta</package> + to <xref linkend="opt-environment.systemPackages" />. + </para> + <para> + Details about using Vorta can be found under <link + xlink:href="https://vorta.borgbase.com/usage">https://vorta.borgbase.com + </link>. + </para> + </section> +</chapter> |