movefasta/nixpkgs
0
0
Fork 0
mirror of https://github.com/NixOS/nixpkgs.git synced 2025-07-13 21:50:33 +03:00
Code Activity

nixos/borgbackup: convert manual chapter to MD

Browse source
This commit is contained in:
pennae 2023-01-02 23:56:45 +01:00
parent 53935b445f
commit 1ce4fde27b
3 changed files with 314 additions and 154 deletions
Download patch file Download diff file Expand all files Collapse all files

163
nixos/modules/services/backup/borgbackup.md Normal file
View file

@ -0,0 +1,163 @@
# BorgBackup {#module-borgbase}
*Source:* {file}`modules/services/backup/borgbackup.nix`
*Upstream documentation:* <https://borgbackup.readthedocs.io/>
[BorgBackup](https://www.borgbackup.org/) (short: Borg)
is a deduplicating backup program. Optionally, it supports compression and
authenticated encryption.
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.
## Configuring {#module-services-backup-borgbackup-configuring}
A complete list of options for the Borgbase module may be found
[here](#opt-services.borgbackup.jobs).
## Basic usage for a local backup {#opt-services-backup-borgbackup-local-directory}
A very basic configuration for backing up to a locally accessible directory is:
```
{
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";
};
}
};
}
```
::: {.warning}
If you do not want the passphrase to be stored in the world-readable
Nix store, use passCommand. You find an example below.
:::
## Create a borg backup server {#opt-services-backup-create-server}
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.
```ShellSession
# 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
```
Add the following snippet to your NixOS configuration:
```
{
services.borgbackup.repos = {
my_borg_repo = {
authorizedKeys = [
"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos"
] ;
path = "/var/lib/my_borg_repo" ;
};
};
}
```
## Backup to the borg repository server {#opt-services-backup-borgbackup-remote-server}
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
{file}`/run/keys/borgbackup_passphrase`, which should be only
accessible by root
```
{
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";
};
};
};
```
The following few commands (run as root) let you test your backup.
```
> 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]
```
## Backup to a hosting service {#opt-services-backup-borgbackup-borgbase}
Several companies offer [(paid) hosting services](https://www.borgbackup.org/support/commercial.html)
for Borg repositories.
To backup your home directory to borgbase you have to:
- Generate a SSH key without a password, to access the remote server. E.g.
sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_borgbase
- Create the repository on the server by following the instructions for your
hosting server.
- Initialize the repository on the server. Eg.
sudo borg init --encryption=repokey-blake2 \
-rsh "ssh -i /run/keys/id_ed25519_borgbase" \
zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo
- Add it to your NixOS configuration, e.g.
{
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";
};
environment = { BORG_RSH = "ssh -i /run/keys/id_ed25519_borgbase"; };
compression = "auto,lzma";
startAt = "daily";
};
};
}}
## Vorta backup client for the desktop {#opt-services-backup-borgbackup-vorta}
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.
It can be installed in NixOS e.g. by adding `pkgs.vorta`
to [](#opt-environment.systemPackages).
Details about using Vorta can be found under
[https://vorta.borgbase.com](https://vorta.borgbase.com/usage) .

2
nixos/modules/services/backup/borgbackup.nix
View file

@ -226,6 +226,8 @@ let
in { in {
meta.maintainers = with maintainers; [ dotlambda ]; meta.maintainers = with maintainers; [ dotlambda ];
# Don't edit the docbook xml directly, edit the md and generate it:
# `pandoc borgbackup.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > borgbackup.xml`
meta.doc = ./borgbackup.xml; meta.doc = ./borgbackup.xml;
###### interface ###### interface

303
nixos/modules/services/backup/borgbackup.xml
View file

@ -1,218 +1,213 @@
<chapter xmlns="http://docbook.org/ns/docbook" <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-borgbase">
xmlns:xlink="http://www.w3.org/1999/xlink" <title>BorgBackup</title>
xmlns:xi="http://www.w3.org/2001/XInclude"
version="5.0"
xml:id="module-borgbase">
<title>BorgBackup</title>
<para> <para>
<emphasis>Source:</emphasis> <emphasis>Source:</emphasis>
<filename>modules/services/backup/borgbackup.nix</filename> <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>
<para> <para>
The main goal of Borg is to provide an efficient and secure way to backup <emphasis>Upstream documentation:</emphasis>
data. The data deduplication technique used makes Borg suitable for daily <link xlink:href="https://borgbackup.readthedocs.io/" role="uri">https://borgbackup.readthedocs.io/</link>
backups since only changes are stored. The authenticated encryption technique </para>
makes it suitable for backups to not fully trusted targets. <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"> <section xml:id="module-services-backup-borgbackup-configuring">
<title>Configuring</title> <title>Configuring</title>
<para> <para>
A complete list of options for the Borgbase module may be found A complete list of options for the Borgbase module may be found
<link linkend="opt-services.borgbackup.jobs">here</link>. <link linkend="opt-services.borgbackup.jobs">here</link>.
</para> </para>
</section> </section>
<section xml:id="opt-services-backup-borgbackup-local-directory"> <section xml:id="opt-services-backup-borgbackup-local-directory">
<title>Basic usage for a local backup</title> <title>Basic usage for a local backup</title>
<para>
<para> A very basic configuration for backing up to a locally accessible
A very basic configuration for backing up to a locally accessible directory directory is:
is: </para>
<programlisting> <programlisting>
{ {
opt.services.borgbackup.jobs = { opt.services.borgbackup.jobs = {
{ rootBackup = { { rootBackup = {
paths = "/"; paths = &quot;/&quot;;
exclude = [ "/nix" "/path/to/local/repo" ]; exclude = [ &quot;/nix&quot; &quot;/path/to/local/repo&quot; ];
repo = "/path/to/local/repo"; repo = &quot;/path/to/local/repo&quot;;
doInit = true; doInit = true;
encryption = { encryption = {
mode = "repokey"; mode = &quot;repokey&quot;;
passphrase = "secret"; passphrase = &quot;secret&quot;;
}; };
compression = "auto,lzma"; compression = &quot;auto,lzma&quot;;
startAt = "weekly"; startAt = &quot;weekly&quot;;
}; };
} }
}; };
} }
</programlisting> </programlisting>
</para> <warning>
<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> <para>
If you do not want the passphrase to be stored in the world-readable You should use a different SSH key for each repository you write
Nix store, use passCommand. You find an example below. 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>
</warning> <programlisting>
</section> # sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_my_borg_repo
<section xml:id="opt-services-backup-create-server"> # cat /run/keys/id_ed25519_my_borg_repo
<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>
<screen>
<prompt># </prompt>sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_my_borg_repo
<prompt># </prompt>cat /run/keys/id_ed25519_my_borg_repo
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos
</screen> </programlisting>
</para>
<para> <para>
Add the following snippet to your NixOS configuration: Add the following snippet to your NixOS configuration:
<programlisting> </para>
<programlisting>
{ {
services.borgbackup.repos = { services.borgbackup.repos = {
my_borg_repo = { my_borg_repo = {
authorizedKeys = [ authorizedKeys = [
"ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos" &quot;ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos&quot;
] ; ] ;
path = "/var/lib/my_borg_repo" ; path = &quot;/var/lib/my_borg_repo&quot; ;
}; };
}; };
} }
</programlisting> </programlisting>
</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
<filename>/run/keys/borgbackup_passphrase</filename>, which should
be only accessible by root
</para> </para>
</section> <programlisting>
<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
<filename>/run/keys/borgbackup_passphrase</filename>, which should be only
accessible by root
</para>
<para>
<programlisting>
{ {
services.borgbackup.jobs = { services.borgbackup.jobs = {
backupToLocalServer = { backupToLocalServer = {
paths = [ "/etc/nixos" ]; paths = [ &quot;/etc/nixos&quot; ];
doInit = true; doInit = true;
repo = "borg@nixos:." ; repo = &quot;borg@nixos:.&quot; ;
encryption = { encryption = {
mode = "repokey-blake2"; mode = &quot;repokey-blake2&quot;;
passCommand = "cat /run/keys/borgbackup_passphrase"; passCommand = &quot;cat /run/keys/borgbackup_passphrase&quot;;
}; };
environment = { BORG_RSH = "ssh -i /run/keys/id_ed25519_my_borg_repo"; }; environment = { BORG_RSH = &quot;ssh -i /run/keys/id_ed25519_my_borg_repo&quot;; };
compression = "auto,lzma"; compression = &quot;auto,lzma&quot;;
startAt = "hourly"; startAt = &quot;hourly&quot;;
}; };
}; };
}; };
</programlisting> </programlisting>
</para> <para>
<para>The following few commands (run as root) let you test your backup. The following few commands (run as root) let you test your backup.
<programlisting> </para>
> nixos-rebuild switch <programlisting>
&gt; nixos-rebuild switch
...restarting the following units: polkit.service ...restarting the following units: polkit.service
> systemctl restart borgbackup-job-backupToLocalServer &gt; systemctl restart borgbackup-job-backupToLocalServer
> sleep 10 &gt; sleep 10
> systemctl restart borgbackup-job-backupToLocalServer &gt; systemctl restart borgbackup-job-backupToLocalServer
> export BORG_PASSPHRASE=topSecrect &gt; export BORG_PASSPHRASE=topSecrect
> borg list --rsh='ssh -i /run/keys/id_ed25519_my_borg_repo' borg@nixos:. &gt; 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:17 Mon, 2020-03-30 21:46:19 [84feb97710954931ca384182f5f3cb90665f35cef214760abd7350fb064786ac]
nixos-backupToLocalServer-2020-03-30T21:46:30 Mon, 2020-03-30 21:46:32 [e77321694ecd160ca2228611747c6ad1be177d6e0d894538898de7a2621b6e68] nixos-backupToLocalServer-2020-03-30T21:46:30 Mon, 2020-03-30 21:46:32 [e77321694ecd160ca2228611747c6ad1be177d6e0d894538898de7a2621b6e68]
</programlisting> </programlisting>
</para> </section>
</section> <section xml:id="opt-services-backup-borgbackup-borgbase">
<title>Backup to a hosting service</title>
<section xml:id="opt-services-backup-borgbackup-borgbase"> <para>
<title>Backup to a hosting service</title> Several companies offer
<link xlink:href="https://www.borgbackup.org/support/commercial.html">(paid)
<para>
Several companies offer <link
xlink:href="https://www.borgbackup.org/support/commercial.html">(paid)
hosting services</link> for Borg repositories. 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>
<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>
<programlisting> <programlisting>
sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_borgbase sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_borgbase
</programlisting> </programlisting>
</para> </listitem>
</listitem> <listitem>
<listitem> <para>
<para> Create the repository on the server by following the
Create the repository on the server by following the instructions for your instructions for your hosting server.
hosting server. </para>
</para> </listitem>
</listitem> <listitem>
<listitem> <para>
<para> Initialize the repository on the server. Eg.
Initialize the repository on the server. Eg. </para>
<programlisting> <programlisting>
sudo borg init --encryption=repokey-blake2 \ sudo borg init --encryption=repokey-blake2 \
-rsh "ssh -i /run/keys/id_ed25519_borgbase" \ -rsh &quot;ssh -i /run/keys/id_ed25519_borgbase&quot; \
zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo
</programlisting> </programlisting>
</para> </listitem>
</listitem> <listitem>
<listitem> <para>
<para>Add it to your NixOS configuration, e.g. Add it to your NixOS configuration, e.g.
<programlisting> </para>
<programlisting>
{ {
services.borgbackup.jobs = { services.borgbackup.jobs = {
my_Remote_Backup = { my_Remote_Backup = {
paths = [ "/" ]; paths = [ &quot;/&quot; ];
exclude = [ "/nix" "'**/.cache'" ]; exclude = [ &quot;/nix&quot; &quot;'**/.cache'&quot; ];
repo = "zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo"; repo = &quot;zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo&quot;;
encryption = { encryption = {
mode = "repokey-blake2"; mode = &quot;repokey-blake2&quot;;
passCommand = "cat /run/keys/borgbackup_passphrase"; passCommand = &quot;cat /run/keys/borgbackup_passphrase&quot;;
}; };
environment = { BORG_RSH = "ssh -i /run/keys/id_ed25519_borgbase"; }; environment = { BORG_RSH = &quot;ssh -i /run/keys/id_ed25519_borgbase&quot;; };
compression = "auto,lzma"; compression = &quot;auto,lzma&quot;;
startAt = "daily"; startAt = &quot;daily&quot;;
}; };
}; };
}} }}
</programlisting> </programlisting>
</para> </listitem>
</listitem> </itemizedlist>
</itemizedlist> </section>
</section>
<section xml:id="opt-services-backup-borgbackup-vorta"> <section xml:id="opt-services-backup-borgbackup-vorta">
<title>Vorta backup client for the desktop</title> <title>Vorta backup client for the desktop</title>
<para> <para>
Vorta is a backup client for macOS and Linux desktops. It integrates the Vorta is a backup client for macOS and Linux desktops. It
mighty BorgBackup with your desktop environment to protect your data from integrates the mighty BorgBackup with your desktop environment to
disk failure, ransomware and theft. protect your data from disk failure, ransomware and theft.
</para> </para>
<para> <para>
It can be installed in NixOS e.g. by adding <literal>pkgs.vorta</literal> It can be installed in NixOS e.g. by adding
to <xref linkend="opt-environment.systemPackages" />. <literal>pkgs.vorta</literal> to
</para> <xref linkend="opt-environment.systemPackages"></xref>.
<para> </para>
Details about using Vorta can be found under <link <para>
xlink:href="https://vorta.borgbase.com/usage">https://vorta.borgbase.com Details about using Vorta can be found under
</link>. <link xlink:href="https://vorta.borgbase.com/usage">https://vorta.borgbase.com</link>
</para> .
</section> </para>
</section>
</chapter> </chapter>