1 files changed, 27 insertions, 1 deletions

diff --git a/nixos/modules/services/backup/borgbackup.nix b/nixos/modules/services/backup/borgbackup.nix
index a2eb80c55a8..be661b201f0 100644
--- a/nixos/modules/services/backup/borgbackup.nix
+++ b/nixos/modules/services/backup/borgbackup.nix
@@ -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.)
     '';