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