colin/nixpkgs
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #83529 from ngiger/83525

Browse Source 
borgbackup: Improve documentation
This commit is contained in:
Jörg Thalheim 2020-04-02 12:27:38 +01:00 committed by GitHub
commit 61e6520d8c
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 254 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
nixos/modules/services/backup/borgbackup.nix
View File

@ -189,6 +189,7 @@ let
in {
meta.maintainers = with maintainers; [ dotlambda ];
meta.doc = ./borgbackup.xml;
###### interface
@ -197,10 +198,11 @@ in {
Deduplicating backups using BorgBackup.
Adding a job will cause a borg-job-NAME wrapper to be added
to your system path, so that you can perform maintenance easily.
See also the chapter about BorgBackup in the NixOS manual.
'';
default = { };
example = literalExample ''
{
{ # for a local backup
rootBackup = {
paths = "/";
exclude = [ "/nix" ];
@ -213,6 +215,23 @@ in {
startAt = "weekly";
};
}
{ # Root backing each day up to a remote backup server. We assume that you have
# * created a password less key: ssh-keygen -N '' -t ed25519 -f /path/to/ssh_key
# best practices are: use -t ed25519, /path/to = /run/keys
# * the passphrase is in the file /run/keys/borgbackup_passphrase
# * you have initialized the repository manually
paths = [ "/etc" "/home" ];
exclude = [ "/nix" "'**/.cache'" ];
doInit = false;
repo = "user3@arep.repo.borgbase.com:repo";
encryption = {
mode = "repokey-blake2";
passCommand = "cat /path/to/passphrase";
};
environment = { BORG_RSH = "ssh -i /path/to/ssh_key"; };
compression = "auto,lzma";
startAt = "daily";
};
'';
type = types.attrsOf (types.submodule (let globalConfig = config; in
{ name, config, ... }: {
@ -268,6 +287,8 @@ in {
<manvolnum>7</manvolnum></citerefentry>.
If you do not want the backup to start
automatically, use <literal>[ ]</literal>.
It will generate a systemd service borgbackup-job-NAME.
You may trigger it manually via systemctl restart borgbackup-job-NAME.
'';
};
@ -303,6 +324,10 @@ in {
you to specify a <option>passCommand</option>
or a <option>passphrase</option>.
'';
example = ''
encryption.mode = "repokey-blake2" ;
encryption.passphrase = "mySecretPassphrase" ;
'';
};
encryption.passCommand = mkOption {
@ -538,6 +563,7 @@ in {
description = ''
Serve BorgBackup repositories to given public SSH keys,
restricting their access to the repository only.
See also the chapter about BorgBackup in the NixOS manual.
Also, clients do not need to specify the absolute path when accessing the repository,
i.e. <literal>user@machine:.</literal> is enough. (Note colon and dot.)
'';

227
nixos/modules/services/backup/borgbackup.xml Normal file
View File

@ -0,0 +1,227 @@
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="module-borgbase">
<title>BorgBackup</title>
<para>
<emphasis>Source:</emphasis>
<filename>modules/services/backup/borgbackup.nix</filename>
</para>
<para>
<emphasis>Upstream documentation:</emphasis>
<link xlink:href="https://borgbackup.readthedocs.io/"/>
</para>
<para>
<link xlink:href="https://www.borgbackup.org/">BorgBackup</link> (short: Borg)
is a deduplicating backup program. Optionally, it supports compression and
authenticated encryption.
</para>
<para>
The main goal of Borg is to provide an efficient and secure way to backup
data. The data deduplication technique used makes Borg suitable for daily
backups since only changes are stored. The authenticated encryption technique
makes it suitable for backups to not fully trusted targets.
</para>
<section xml:id="module-services-backup-borgbackup-configuring">
<title>Configuring</title>
<para>
A complete list of options for the Borgbase module may be found
<link linkend="opt-services.borgbackup.jobs">here</link>.
</para>
</section>
<section xml:id="opt-services-backup-borgbackup-local-directory">
<title>Basic usage for a local backup</title>
<para>
A very basic configuration for backing up to a locally accessible directory
is:
<programlisting>
{
opt.services.borgbackup.jobs = {
{ rootBackup = {
paths = "/";
exclude = [ "/nix" "/path/to/local/repo" ];
repo = "/path/to/local/repo";
doInit = true;
encryption = {
mode = "repokey";
passphrase = "secret";
};
compression = "auto,lzma";
startAt = "weekly";
};
}
};
}</programlisting>
</para>
<warning>
<para>
If you do not want the passphrase to be stored in the world-readable
Nix store, use passCommand. You find an example below.
</para>
</warning>
</section>
<section xml:id="opt-services-backup-create-server">
<title>Create a borg backup server</title>
<para>You should use a different SSH key for each repository you write to,
because the specified keys are restricted to running borg serve and can only
access this single repository. You need the output of the generate pub file.
</para>
<para>
<programlisting>
# sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_my_borg_repo
# cat /run/keys/id_ed25519_my_borg_repo
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos</programlisting>
</para>
<para>
Add the following snippet to your NixOS configuration:
<programlisting>
{
services.borgbackup.repos = {
my_borg_repo = {
authorizedKeys = [
"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos"
] ;
path = "/var/lib/my_borg_repo" ;
};
};
}</programlisting>
</para>
</section>
<section xml:id="opt-services-backup-borgbackup-remote-server">
<title>Backup to the borg repository server</title>
<para>The following NixOS snippet creates an hourly backup to the service
(on the host nixos) as created in the section above. We assume
that you have stored a secret passphrasse in the file
<code>/run/keys/borgbackup_passphrase</code>, which should be only
accessible by root
</para>
<para>
<programlisting>
{
services.borgbackup.jobs = {
backupToLocalServer = {
paths = [ "/etc/nixos" ];
doInit = true;
repo = "borg@nixos:." ;
encryption = {
mode = "repokey-blake2";
passCommand = "cat /run/keys/borgbackup_passphrase";
};
environment = { BORG_RSH = "ssh -i /run/keys/id_ed25519_my_borg_repo"; };
compression = "auto,lzma";
startAt = "hourly";
};
};
};</programlisting>
</para>
<para>The following few commands (run as root) let you test your backup.
<programlisting>
> nixos-rebuild switch
...restarting the following units: polkit.service
> systemctl restart borgbackup-job-backupToLocalServer
> sleep 10
> systemctl restart borgbackup-job-backupToLocalServer
> export BORG_PASSPHRASE=topSecrect
> borg list --rsh='ssh -i /run/keys/id_ed25519_my_borg_repo' borg@nixos:.
nixos-backupToLocalServer-2020-03-30T21:46:17 Mon, 2020-03-30 21:46:19 [84feb97710954931ca384182f5f3cb90665f35cef214760abd7350fb064786ac]
nixos-backupToLocalServer-2020-03-30T21:46:30 Mon, 2020-03-30 21:46:32 [e77321694ecd160ca2228611747c6ad1be177d6e0d894538898de7a2621b6e68]</programlisting>
</para>
</section>
<section xml:id="opt-services-backup-borgbackup-borgbase">
<title>Backup to a hosting service</title>
<para>
Several companies offer <link
xlink:href="https://www.borgbackup.org/support/commercial.html">(paid)
hosting services</link> for Borg repositories.
</para>
<para>
To backup your home directory to borgbase you have to:
</para>
<itemizedlist>
<listitem>
<para>
Generate a SSH key without a password, to access the remote server. E.g.
</para>
<para>
<programlisting>sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_borgbase</programlisting>
</para>
</listitem>
<listitem>
<para>
Create the repository on the server by following the instructions for your
hosting server.
</para>
</listitem>
<listitem>
<para>
Initialize the repository on the server. Eg.
<programlisting>
sudo borg init --encryption=repokey-blake2 \
-rsh "ssh -i /run/keys/id_ed25519_borgbase" \
zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo</programlisting>
</para>
</listitem>
<listitem>
<para>Add it to your NixOS configuration, e.g.
<programlisting>
{
services.borgbackup.jobs = {
my_Remote_Backup = {
paths = [ "/" ];
exclude = [ "/nix" "'**/.cache'" ];
repo = "zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo";
encryption = {
mode = "repokey-blake2";
passCommand = "cat /run/keys/borgbackup_passphrase";
};
BORG_RSH = "ssh -i /run/keys/id_ed25519_borgbase";
compression = "auto,lzma";
startAt = "daily";
};
};
}}</programlisting>
</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="opt-services-backup-borgbackup-vorta">
<title>Vorta backup client for the desktop</title>
<para>
Vorta is a backup client for macOS and Linux desktops. It integrates the
mighty BorgBackup with your desktop environment to protect your data from
disk failure, ransomware and theft.
</para>
<para>
It is available as a flatpak package. To enable it you must set the
following two configuration items.
</para>
<para>
<programlisting>
services.flatpak.enable = true ;
# next line is needed to avoid the Error
# Error deploying: GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown:
services.accounts-daemon.enable = true;
</programlisting>
</para>
<para>As a normal user you must first install, then run vorta using the
following commands:
<programlisting>
flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
flatpak install flathub com.borgbase.Vorta
flatpak run --branch=stable --arch=x86_64 --command=vorta com.borgbase.Vorta
</programlisting>
After running <code>flatpak install</code> you can start Vorta also via
the KDE application menu.
</para>
<para>
Details about using Vorta can be found under <link
xlink:href="https://vorta.borgbase.com/usage">https://vorta.borgbase.com
</link>.
</para>
</section>
</chapter>