git.iko.soy/typeable/nixpkgs
on master help sign in
Merge pull request #83529 from ngiger/83525

borgbackup: Improve documentation

commit61e6520d8c00af9a9f626dea63eca194a5d663ea authorJörg Thalheim <Mic92@users.noreply.github.com> dateThu 2 Apr 2020, 12:27 (7 years ago) parentf71c9e8c027937
2 files changed+254−1
nixos/modules/services/backup/borgbackup.nix+27−1 nixos/modules/services/backup/borgbackup.xml+227
nixos/modules/services/backup/borgbackup.nix+27−1
@@ -189,6 +189,7 @@ let
189189
190190in {
191191 meta.maintainers = with maintainers; [ dotlambda ];
192+ meta.doc = ./borgbackup.xml;
192193
193194 ###### interface
194195
@@ -197,10 +198,11 @@ in {
197198 Deduplicating backups using BorgBackup.
198199 Adding a job will cause a borg-job-NAME wrapper to be added
199200 to your system path, so that you can perform maintenance easily.
201+ See also the chapter about BorgBackup in the NixOS manual.
200202 '';
201203 default = { };
202204 example = literalExample ''
203− {
205+ { # for a local backup
204206 rootBackup = {
205207 paths = "/";
206208 exclude = [ "/nix" ];
@@ -213,6 +215,23 @@ in {
213215 startAt = "weekly";
214216 };
215217 }
218+ { # Root backing each day up to a remote backup server. We assume that you have
219+ # * created a password less key: ssh-keygen -N '' -t ed25519 -f /path/to/ssh_key
220+ # best practices are: use -t ed25519, /path/to = /run/keys
221+ # * the passphrase is in the file /run/keys/borgbackup_passphrase
222+ # * you have initialized the repository manually
223+ paths = [ "/etc" "/home" ];
224+ exclude = [ "/nix" "'**/.cache'" ];
225+ doInit = false;
226+ repo = "user3@arep.repo.borgbase.com:repo";
227+ encryption = {
228+ mode = "repokey-blake2";
229+ passCommand = "cat /path/to/passphrase";
230+ };
231+ environment = { BORG_RSH = "ssh -i /path/to/ssh_key"; };
232+ compression = "auto,lzma";
233+ startAt = "daily";
234+ };
216235 '';
217236 type = types.attrsOf (types.submodule (let globalConfig = config; in
218237 { name, config, ... }: {
@@ -268,6 +287,8 @@ in {
268287 <manvolnum>7</manvolnum></citerefentry>.
269288 If you do not want the backup to start
270289 automatically, use <literal>[ ]</literal>.
290+ It will generate a systemd service borgbackup-job-NAME.
291+ You may trigger it manually via systemctl restart borgbackup-job-NAME.
271292 '';
272293 };
273294
@@ -303,6 +324,10 @@ in {
303324 you to specify a <option>passCommand</option>
304325 or a <option>passphrase</option>.
305326 '';
327+ example = ''
328+ encryption.mode = "repokey-blake2" ;
329+ encryption.passphrase = "mySecretPassphrase" ;
330+ '';
306331 };
307332
308333 encryption.passCommand = mkOption {
@@ -538,6 +563,7 @@ in {
538563 description = ''
539564 Serve BorgBackup repositories to given public SSH keys,
540565 restricting their access to the repository only.
566+ See also the chapter about BorgBackup in the NixOS manual.
541567 Also, clients do not need to specify the absolute path when accessing the repository,
542568 i.e. <literal>user@machine:.</literal> is enough. (Note colon and dot.)
543569 '';
nixos/modules/services/backup/borgbackup.xmlnew file+227
@@ -0,0 +1,227 @@
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+ <programlisting>
73+# sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_my_borg_repo
74+# cat /run/keys/id_ed25519_my_borg_repo
75+ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos</programlisting>
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:.
129+nixos-backupToLocalServer-2020-03-30T21:46:17 Mon, 2020-03-30 21:46:19 [84feb97710954931ca384182f5f3cb90665f35cef214760abd7350fb064786ac]
130+nixos-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>
164+sudo 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 is available as a flatpak package. To enable it you must set the
201+ following two configuration items.
202+ </para>
203+ <para>
204+ <programlisting>
205+services.flatpak.enable = true ;
206+# next line is needed to avoid the Error
207+# Error deploying: GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown:
208+services.accounts-daemon.enable = true;
209+ </programlisting>
210+ </para>
211+ <para>As a normal user you must first install, then run vorta using the
212+ following commands:
213+ <programlisting>
214+flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
215+flatpak install flathub com.borgbase.Vorta
216+flatpak run --branch=stable --arch=x86_64 --command=vorta com.borgbase.Vorta
217+</programlisting>
218+ After running <code>flatpak install</code> you can start Vorta also via
219+ the KDE application menu.
220+ </para>
221+ <para>
222+ Details about using Vorta can be found under <link
223+ xlink:href="https://vorta.borgbase.com/usage">https://vorta.borgbase.com
224+ </link>.
225+ </para>
226+ </section>
227+</chapter>