pyrox.dev
1<chapter xmlns="http://docbook.org/ns/docbook"
2 xmlns:xlink="http://www.w3.org/1999/xlink"
3 xmlns:xi="http://www.w3.org/2001/XInclude"
4 version="5.0"
5 xml:id="module-borgbase">
6 <title>BorgBackup</title>
7 <para>
8 <emphasis>Source:</emphasis>
9 <filename>modules/services/backup/borgbackup.nix</filename>
10 </para>
11 <para>
12 <emphasis>Upstream documentation:</emphasis>
13 <link xlink:href="https://borgbackup.readthedocs.io/"/>
14 </para>
15 <para>
16 <link xlink:href="https://www.borgbackup.org/">BorgBackup</link> (short: Borg)
17 is a deduplicating backup program. Optionally, it supports compression and
18 authenticated encryption.
19 </para>
20 <para>
21 The main goal of Borg is to provide an efficient and secure way to backup
22 data. The data deduplication technique used makes Borg suitable for daily
23 backups since only changes are stored. The authenticated encryption technique
24 makes it suitable for backups to not fully trusted targets.
25 </para>
26 <section xml:id="module-services-backup-borgbackup-configuring">
27 <title>Configuring</title>
28 <para>
29 A complete list of options for the Borgbase module may be found
30 <link linkend="opt-services.borgbackup.jobs">here</link>.
31 </para>
32</section>
33 <section xml:id="opt-services-backup-borgbackup-local-directory">
34 <title>Basic usage for a local backup</title>
35
36 <para>
37 A very basic configuration for backing up to a locally accessible directory
38 is:
39<programlisting>
40{
41 opt.services.borgbackup.jobs = {
42 { rootBackup = {
43 paths = "/";
44 exclude = [ "/nix" "/path/to/local/repo" ];
45 repo = "/path/to/local/repo";
46 doInit = true;
47 encryption = {
48 mode = "repokey";
49 passphrase = "secret";
50 };
51 compression = "auto,lzma";
52 startAt = "weekly";
53 };
54 }
55 };
56}</programlisting>
57 </para>
58 <warning>
59 <para>
60 If you do not want the passphrase to be stored in the world-readable
61 Nix store, use passCommand. You find an example below.
62 </para>
63 </warning>
64 </section>
65<section xml:id="opt-services-backup-create-server">
66 <title>Create a borg backup server</title>
67 <para>You should use a different SSH key for each repository you write to,
68 because the specified keys are restricted to running borg serve and can only
69 access this single repository. You need the output of the generate pub file.
70 </para>
71 <para>
72<screen>
73<prompt># </prompt>sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_my_borg_repo
74<prompt># </prompt>cat /run/keys/id_ed25519_my_borg_repo
75ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos</screen>
76 </para>
77 <para>
78 Add the following snippet to your NixOS configuration:
79 <programlisting>
80{
81 services.borgbackup.repos = {
82 my_borg_repo = {
83 authorizedKeys = [
84 "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos"
85 ] ;
86 path = "/var/lib/my_borg_repo" ;
87 };
88 };
89}</programlisting>
90 </para>
91</section>
92
93 <section xml:id="opt-services-backup-borgbackup-remote-server">
94 <title>Backup to the borg repository server</title>
95 <para>The following NixOS snippet creates an hourly backup to the service
96 (on the host nixos) as created in the section above. We assume
97 that you have stored a secret passphrasse in the file
98 <code>/run/keys/borgbackup_passphrase</code>, which should be only
99 accessible by root
100 </para>
101 <para>
102 <programlisting>
103{
104 services.borgbackup.jobs = {
105 backupToLocalServer = {
106 paths = [ "/etc/nixos" ];
107 doInit = true;
108 repo = "borg@nixos:." ;
109 encryption = {
110 mode = "repokey-blake2";
111 passCommand = "cat /run/keys/borgbackup_passphrase";
112 };
113 environment = { BORG_RSH = "ssh -i /run/keys/id_ed25519_my_borg_repo"; };
114 compression = "auto,lzma";
115 startAt = "hourly";
116 };
117 };
118};</programlisting>
119 </para>
120 <para>The following few commands (run as root) let you test your backup.
121 <programlisting>
122> nixos-rebuild switch
123...restarting the following units: polkit.service
124> systemctl restart borgbackup-job-backupToLocalServer
125> sleep 10
126> systemctl restart borgbackup-job-backupToLocalServer
127> export BORG_PASSPHRASE=topSecrect
128> borg list --rsh='ssh -i /run/keys/id_ed25519_my_borg_repo' borg@nixos:.
129nixos-backupToLocalServer-2020-03-30T21:46:17 Mon, 2020-03-30 21:46:19 [84feb97710954931ca384182f5f3cb90665f35cef214760abd7350fb064786ac]
130nixos-backupToLocalServer-2020-03-30T21:46:30 Mon, 2020-03-30 21:46:32 [e77321694ecd160ca2228611747c6ad1be177d6e0d894538898de7a2621b6e68]</programlisting>
131 </para>
132</section>
133
134 <section xml:id="opt-services-backup-borgbackup-borgbase">
135 <title>Backup to a hosting service</title>
136
137 <para>
138 Several companies offer <link
139 xlink:href="https://www.borgbackup.org/support/commercial.html">(paid)
140 hosting services</link> for Borg repositories.
141 </para>
142 <para>
143 To backup your home directory to borgbase you have to:
144 </para>
145 <itemizedlist>
146 <listitem>
147 <para>
148 Generate a SSH key without a password, to access the remote server. E.g.
149 </para>
150 <para>
151 <programlisting>sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_borgbase</programlisting>
152 </para>
153 </listitem>
154 <listitem>
155 <para>
156 Create the repository on the server by following the instructions for your
157 hosting server.
158 </para>
159 </listitem>
160 <listitem>
161 <para>
162 Initialize the repository on the server. Eg.
163 <programlisting>
164sudo borg init --encryption=repokey-blake2 \
165 -rsh "ssh -i /run/keys/id_ed25519_borgbase" \
166 zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo</programlisting>
167 </para>
168 </listitem>
169 <listitem>
170<para>Add it to your NixOS configuration, e.g.
171<programlisting>
172{
173 services.borgbackup.jobs = {
174 my_Remote_Backup = {
175 paths = [ "/" ];
176 exclude = [ "/nix" "'**/.cache'" ];
177 repo = "zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo";
178 encryption = {
179 mode = "repokey-blake2";
180 passCommand = "cat /run/keys/borgbackup_passphrase";
181 };
182 BORG_RSH = "ssh -i /run/keys/id_ed25519_borgbase";
183 compression = "auto,lzma";
184 startAt = "daily";
185 };
186 };
187}}</programlisting>
188 </para>
189 </listitem>
190</itemizedlist>
191 </section>
192 <section xml:id="opt-services-backup-borgbackup-vorta">
193 <title>Vorta backup client for the desktop</title>
194 <para>
195 Vorta is a backup client for macOS and Linux desktops. It integrates the
196 mighty BorgBackup with your desktop environment to protect your data from
197 disk failure, ransomware and theft.
198 </para>
199 <para>
200 It can be installed in NixOS e.g. by adding <package>pkgs.vorta</package>
201 to <xref linkend="opt-environment.systemPackages" />.
202 </para>
203 <para>
204 Details about using Vorta can be found under <link
205 xlink:href="https://vorta.borgbase.com/usage">https://vorta.borgbase.com
206 </link>.
207 </para>
208 </section>
209</chapter>