nixos/borgbackup: convert manual chapter to MD

3 files changed, 312 insertions, 152 deletions

diff --git a/nixos/modules/services/backup/borgbackup.md b/nixos/modules/services/backup/borgbackup.md
new file mode 100644
index 0000000000000..e86ae593bbd62
--- /dev/null
+++ b/nixos/modules/services/backup/borgbackup.md
@@ -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) .
diff --git a/nixos/modules/services/backup/borgbackup.nix b/nixos/modules/services/backup/borgbackup.nix
index c5fc09dcea028..6c79cc601c6d8 100644
--- a/nixos/modules/services/backup/borgbackup.nix
+++ b/nixos/modules/services/backup/borgbackup.nix
@@ -226,6 +226,8 @@ let
 
 in {
   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;
 
   ###### interface
diff --git a/nixos/modules/services/backup/borgbackup.xml b/nixos/modules/services/backup/borgbackup.xml
index 5051289882b78..26ba6b1e63c80 100644
--- a/nixos/modules/services/backup/borgbackup.xml
+++ b/nixos/modules/services/backup/borgbackup.xml
@@ -1,218 +1,213 @@
-<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>
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" 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.
+    <emphasis>Source:</emphasis>
+    <filename>modules/services/backup/borgbackup.nix</filename>
   </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>
+    <emphasis>Upstream documentation:</emphasis>
+    <link xlink:href="https://borgbackup.readthedocs.io/" role="uri">https://borgbackup.readthedocs.io/</link>
+  </para>
   <para>
-   A complete list of options for the Borgbase module may be found
-   <link linkend="opt-services.borgbackup.jobs">here</link>.
+    <link xlink:href="https://www.borgbackup.org/">BorgBackup</link>
+    (short: Borg) is a deduplicating backup program. Optionally, it
+    supports compression and authenticated encryption.
   </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>
+    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:
+    </para>
+    <programlisting>
 {
     opt.services.borgbackup.jobs = {
       { rootBackup = {
-          paths = "/";
-          exclude = [ "/nix" "/path/to/local/repo" ];
-          repo = "/path/to/local/repo";
+          paths = &quot;/&quot;;
+          exclude = [ &quot;/nix&quot; &quot;/path/to/local/repo&quot; ];
+          repo = &quot;/path/to/local/repo&quot;;
           doInit = true;
           encryption = {
-            mode = "repokey";
-            passphrase = "secret";
+            mode = &quot;repokey&quot;;
+            passphrase = &quot;secret&quot;;
           };
-          compression = "auto,lzma";
-          startAt = "weekly";
+          compression = &quot;auto,lzma&quot;;
+          startAt = &quot;weekly&quot;;
         };
       }
     };
 }
 </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>
-        If you do not want the passphrase to be stored in the world-readable
-        Nix store, use passCommand. You find an example below.
+      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>
-  </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>
-<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
+    <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
-</screen>
-    </para>
+</programlisting>
     <para>
       Add the following snippet to your NixOS configuration:
-      <programlisting>
+    </para>
+    <programlisting>
 {
   services.borgbackup.repos = {
     my_borg_repo = {
       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>
+  </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>
-</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>
-      <programlisting>
+    <programlisting>
 {
   services.borgbackup.jobs = {
     backupToLocalServer = {
-      paths = [ "/etc/nixos" ];
+      paths = [ &quot;/etc/nixos&quot; ];
       doInit = true;
-      repo =  "borg@nixos:." ;
+      repo =  &quot;borg@nixos:.&quot; ;
       encryption = {
-        mode = "repokey-blake2";
-        passCommand = "cat /run/keys/borgbackup_passphrase";
+        mode = &quot;repokey-blake2&quot;;
+        passCommand = &quot;cat /run/keys/borgbackup_passphrase&quot;;
       };
-      environment = { BORG_RSH = "ssh -i /run/keys/id_ed25519_my_borg_repo"; };
-      compression = "auto,lzma";
-      startAt = "hourly";
+      environment = { BORG_RSH = &quot;ssh -i /run/keys/id_ed25519_my_borg_repo&quot;; };
+      compression = &quot;auto,lzma&quot;;
+      startAt = &quot;hourly&quot;;
     };
   };
 };
 </programlisting>
-  </para>
-  <para>The following few commands (run as root) let you test your backup.
-      <programlisting>
-> nixos-rebuild switch
+    <para>
+      The following few commands (run as root) let you test your backup.
+    </para>
+    <programlisting>
+&gt; 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:.
+&gt; systemctl restart borgbackup-job-backupToLocalServer
+&gt; sleep 10
+&gt; systemctl restart borgbackup-job-backupToLocalServer
+&gt; export BORG_PASSPHRASE=topSecrect
+&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: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>
+  </section>
+  <section xml:id="opt-services-backup-borgbackup-borgbase">
+    <title>Backup to a hosting service</title>
     <para>
-      Generate a SSH key without a password, to access the remote server. E.g.
+      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>
         <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>
+      </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.
+        </para>
+        <programlisting>
 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
 </programlisting>
-  </para>
-  </listitem>
-  <listitem>
-<para>Add it to your NixOS configuration, e.g.
-<programlisting>
+      </listitem>
+      <listitem>
+        <para>
+          Add it to your NixOS configuration, e.g.
+        </para>
+        <programlisting>
 {
     services.borgbackup.jobs = {
     my_Remote_Backup = {
-        paths = [ "/" ];
-        exclude = [ "/nix" "'**/.cache'" ];
-        repo =  "zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo";
+        paths = [ &quot;/&quot; ];
+        exclude = [ &quot;/nix&quot; &quot;'**/.cache'&quot; ];
+        repo =  &quot;zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo&quot;;
           encryption = {
-          mode = "repokey-blake2";
-          passCommand = "cat /run/keys/borgbackup_passphrase";
+          mode = &quot;repokey-blake2&quot;;
+          passCommand = &quot;cat /run/keys/borgbackup_passphrase&quot;;
         };
-        environment = { BORG_RSH = "ssh -i /run/keys/id_ed25519_borgbase"; };
-        compression = "auto,lzma";
-        startAt = "daily";
+        environment = { BORG_RSH = &quot;ssh -i /run/keys/id_ed25519_borgbase&quot;; };
+        compression = &quot;auto,lzma&quot;;
+        startAt = &quot;daily&quot;;
     };
   };
 }}
 </programlisting>
-  </para>
-  </listitem>
-</itemizedlist>
- </section>
+      </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 can be installed in NixOS e.g. by adding <literal>pkgs.vorta</literal>
-   to <xref linkend="opt-environment.systemPackages" />.
-  </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>
+    <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 can be installed in NixOS e.g. by adding
+      <literal>pkgs.vorta</literal> to
+      <xref linkend="opt-environment.systemPackages"></xref>.
+    </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>