borgbackup: Moved documentation to NixOS manual and added examples for
* creating a local backup * creating a borgbackup server * backing up to a borgbackup server * hints about the Vorta graphical desktop application * Added documentation about Vorta desktop client Tested the examples locally and with my borgbase.com account.
This commit is contained in:
Niklaus Giger
parent
99a2467722
commit
c027937d9a
@ -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
227
nixos/modules/services/backup/borgbackup.xml
Normal 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>
|
||||
Loading…
Reference in New Issue
Block a user