pyrox.dev
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)
8is a deduplicating backup program. Optionally, it supports compression and
9authenticated encryption.
10
11The main goal of Borg is to provide an efficient and secure way to backup
12data. The data deduplication technique used makes Borg suitable for daily
13backups since only changes are stored. The authenticated encryption technique
14makes it suitable for backups to not fully trusted targets.
15
16## Configuring {#module-services-backup-borgbackup-configuring}
17
18A 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
23A very basic configuration for backing up to a locally accessible directory is:
24```nix
25{
26 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}
44If you do not want the passphrase to be stored in the world-readable
45Nix store, use passCommand. You find an example below.
46:::
47
48## Create a borg backup server {#opt-services-backup-create-server}
49
50You should use a different SSH key for each repository you write to,
51because the specified keys are restricted to running borg serve and can only
52access 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
57ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos
58```
59
60Add 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
76The following NixOS snippet creates an hourly backup to the service
77(on the host nixos) as created in the section above. We assume
78that you have stored a secret passphrasse in the file
79{file}`/run/keys/borgbackup_passphrase`, which should be only
80accessible 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
101The 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=topSecret
109> borg list --rsh='ssh -i /run/keys/id_ed25519_my_borg_repo' borg@nixos:.
110nixos-backupToLocalServer-2020-03-30T21:46:17 Mon, 2020-03-30 21:46:19 [84feb97710954931ca384182f5f3cb90665f35cef214760abd7350fb064786ac]
111nixos-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
116Several companies offer [(paid) hosting services](https://www.borgbackup.org/support/commercial.html)
117for Borg repositories.
118
119To 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
154Vorta is a backup client for macOS and Linux desktops. It integrates the
155mighty BorgBackup with your desktop environment to protect your data from
156disk failure, ransomware and theft.
157
158It can be installed in NixOS e.g. by adding `pkgs.vorta`
159to [](#opt-environment.systemPackages).
160
161Details about using Vorta can be found under
162[https://vorta.borgbase.com](https://vorta.borgbase.com/usage) .