From c027937d9aaed7c96e3b13b5cdf8b60c0f43d51b Mon Sep 17 00:00:00 2001 From: Niklaus Giger Date: Tue, 31 Mar 2020 09:38:59 +0200 Subject: [PATCH] borgbackup: Moved documentation to NixOS manual and added examples for * creating a local backup * creating a borgbackup server * backing up to a borgbackup server * hints about the Vorta graphical desktop application * Added documentation about Vorta desktop client Tested the examples locally and with my borgbase.com account. --- nixos/modules/services/backup/borgbackup.nix | 28 ++- nixos/modules/services/backup/borgbackup.xml | 227 +++++++++++++++++++ 2 files changed, 254 insertions(+), 1 deletion(-) create mode 100644 nixos/modules/services/backup/borgbackup.xml diff --git a/nixos/modules/services/backup/borgbackup.nix b/nixos/modules/services/backup/borgbackup.nix index a2eb80c55a8c..599a2cf7f20d 100644 --- a/nixos/modules/services/backup/borgbackup.nix +++ b/nixos/modules/services/backup/borgbackup.nix @@ -189,6 +189,7 @@ let in { meta.maintainers = with maintainers; [ dotlambda ]; + meta.doc = ./borgbackup.xml; ###### interface @@ -197,10 +198,11 @@ in { Deduplicating backups using BorgBackup. Adding a job will cause a borg-job-NAME wrapper to be added to your system path, so that you can perform maintenance easily. + See also the chapter about BorgBackup in the NixOS manual. ''; default = { }; example = literalExample '' - { + { # for a local backup rootBackup = { paths = "/"; exclude = [ "/nix" ]; @@ -213,6 +215,23 @@ in { startAt = "weekly"; }; } + { # Root backing each day up to a remote backup server. We assume that you have + # * created a password less key: ssh-keygen -N '' -t ed25519 -f /path/to/ssh_key + # best practices are: use -t ed25519, /path/to = /run/keys + # * the passphrase is in the file /run/keys/borgbackup_passphrase + # * you have initialized the repository manually + paths = [ "/etc" "/home" ]; + exclude = [ "/nix" "'**/.cache'" ]; + doInit = false; + repo = "user3@arep.repo.borgbase.com:repo"; + encryption = { + mode = "repokey-blake2"; + passCommand = "cat /path/to/passphrase"; + }; + environment = { BORG_RSH = "ssh -i /path/to/ssh_key"; }; + compression = "auto,lzma"; + startAt = "daily"; + }; ''; type = types.attrsOf (types.submodule (let globalConfig = config; in { name, config, ... }: { @@ -268,6 +287,8 @@ in { 7. If you do not want the backup to start automatically, use [ ]. + It will generate a systemd service borgbackup-job-NAME. + You may trigger it manually via systemctl restart borgbackup-job-NAME. ''; }; @@ -303,6 +324,10 @@ in { you to specify a or a . ''; + example = '' + encryption.mode = "repokey-blake2" ; + encryption.passphrase = "mySecretPassphrase" ; + ''; }; encryption.passCommand = mkOption { @@ -538,6 +563,7 @@ in { description = '' Serve BorgBackup repositories to given public SSH keys, restricting their access to the repository only. + See also the chapter about BorgBackup in the NixOS manual. Also, clients do not need to specify the absolute path when accessing the repository, i.e. user@machine:. is enough. (Note colon and dot.) ''; diff --git a/nixos/modules/services/backup/borgbackup.xml b/nixos/modules/services/backup/borgbackup.xml new file mode 100644 index 000000000000..bef7db608f82 --- /dev/null +++ b/nixos/modules/services/backup/borgbackup.xml @@ -0,0 +1,227 @@ + + BorgBackup + + Source: + modules/services/backup/borgbackup.nix + + + Upstream documentation: + + + + BorgBackup (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 + + A complete list of options for the Borgbase module may be found + here. + +
+
+ Basic usage for a local backup + + + A very basic configuration for backing up to a locally accessible directory + is: + +{ + 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"; + }; + } + }; +} + + + + 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 + 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. + + + +# 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: + +{ + 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 + 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 + /run/keys/borgbackup_passphrase, which should be only + accessible by root + + + +{ + 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"; + }; + }; +}; + + The following few commands (run as root) let you test your backup. + +> 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] + +
+ +
+ Backup to a hosting service + + + Several companies offer (paid) + hosting services for Borg repositories. + + + To backup your home directory to borgbase you have to: + + + + + Generate a SSH key without a password, to access the remote server. E.g. + + + sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_borgbase + + + + + Create the repository on the server by following the instructions for your + hosting server. + + + + + Initialize the repository on the server. Eg. + +sudo borg init --encryption=repokey-blake2 \ + -rsh "ssh -i /run/keys/id_ed25519_borgbase" \ + zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo + + + +Add it to your NixOS configuration, e.g. + +{ + 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"; + }; + }; +}} + + + +
+
+ Vorta backup client for the desktop + + 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. + + + It is available as a flatpak package. To enable it you must set the + following two configuration items. + + + +services.flatpak.enable = true ; +# next line is needed to avoid the Error +# Error deploying: GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown: +services.accounts-daemon.enable = true; + + + As a normal user you must first install, then run vorta using the + following commands: + +flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo +flatpak install flathub com.borgbase.Vorta +flatpak run --branch=stable --arch=x86_64 --command=vorta com.borgbase.Vorta + + After running flatpak install you can start Vorta also via + the KDE application menu. + + + Details about using Vorta can be found under https://vorta.borgbase.com + . + +
+