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