Document backups module and options

barrucadu · Oct 15, 2023 · 1ea1bfd · 1ea1bfd
1 parent 87fe2e9
commit 1ea1bfd
Show file tree

Hide file tree

Showing 2 changed files with 119 additions and 10 deletions.
diff --git a/shared/backups/default.nix b/shared/backups/default.nix
@@ -1,3 +1,27 @@
+# Manage regular incremental and full backups with [Duplicity][].
+#
+# Backups are encrypted and uploaded to the `barrucadu-backups` s3 bucket,
+# [defined in the ops repo][].
+#
+# Check the status of a backup collection with:
+#
+# ```bash
+# nix run .#backups                   # for the current host
+# nix run .#backups status            # for the current host
+# nix run .#backups status <hostname> # for another host
+# ```
+#
+# Restore a backup to `/tmp/backup-restore` with:
+#
+# ```bash
+# nix run .#backups restore            # for the current host
+# nix run .#backups restore <hostname> # for another host
+# ```
+#
+# Change the restore target by setting `$RESTORE_DIR`.
+#
+# [Duplicity]: https://duplicity.gitlab.io/
+# [defined in the ops repo]: https://github.com/barrucadu/ops/blob/master/aws/backups.tf
 { config, lib, pkgs, ... }:
 
 with lib;

diff --git a/shared/backups/options.nix b/shared/backups/options.nix
@@ -4,22 +4,107 @@ with lib;
 
 {
   options.nixfiles.backups = {
-    enable = mkOption { type = types.bool; default = false; };
-    scripts = mkOption { type = types.attrsOf types.str; default = { }; };
-    pythonScripts = mkOption { type = types.attrsOf types.str; default = { }; };
+    enable = mkOption {
+      type = types.bool;
+      default = false;
+      description = mdDoc ''
+        Enable the backup service.
+      '';
+    };
+
+    scripts = mkOption {
+      type = types.attrsOf types.str;
+      default = { };
+      description = mdDoc ''
+        Attrset of bash scripts to run.  The name is the name of the script's
+        working directory.
+      '';
+    };
+
+    pythonScripts = mkOption {
+      type = types.attrsOf types.str;
+      default = { };
+      description = mdDoc ''
+        Attrset of python scripts to run.  The name is the name of the script's
+        working directory.
+      '';
+    };
+
     sudoRules = mkOption {
       type = types.listOf (types.submodule {
         options = {
-          command = mkOption { type = types.str; };
-          runAs = mkOption { type = types.str; default = "ALL:ALL"; };
+          command = mkOption {
+            type = types.str;
+            description = mdDoc ''
+              The command for which the rule applies.
+            '';
+          };
+          runAs = mkOption {
+            type = types.str;
+            default = "ALL:ALL";
+            description = mdDoc ''
+              The user / group under which the command is allowed to run.
+
+              A user can be specified using just the username: `"foo"`. It is
+              also possible to specify a user/group combination using
+              `"foo:bar"` or to only allow running as a specific group with
+              `":bar"`.
+            '';
+          };
         };
       });
       default = { };
+      description = mdDoc ''
+        List of additional sudo rules to grant the backup user.
+      '';
+    };
+
+    environmentFile = mkOption {
+      type = types.str;
+      description = mdDoc ''
+        Environment file to be passed to the systemd services.  This needs to contain:
+
+        - `PASSPHRASE` - the password duplicity uses to encrypt the files
+        - `AWS_ACCESS_KEY` / `AWS_SECRET_ACCESS_KEY` / `AWS_DEFAULT_REGION` -
+          the AWS credentials used to upload the backup to s3 and publish to the
+          SNS topic
+        - `TOPIC_ARN` - the SNS topic to publish to if an error occurs
+
+        If any of the `scripts` or `pythonScripts` need secrets, those should be
+        specified here.
+      '';
+    };
+
+    onCalendarFull = mkOption {
+      type = types.str;
+      default = "monthly";
+      description = mdDoc ''
+        The cadence of the full backup job.
+      '';
+    };
+
+    onCalendarIncr = mkOption {
+      type = types.str;
+      default = "Mon, 04:00";
+      description = mdDoc ''
+        The cadence of the incremental backup job.
+      '';
+    };
+
+    user = mkOption {
+      type = types.str;
+      default = "barrucadu";
+      description = mdDoc ''
+        The user to generate the backup as.
+      '';
+    };
+
+    group = mkOption {
+      type = types.str;
+      default = "users";
+      description = mdDoc ''
+        The group to generate the backup as.
+      '';
     };
-    environmentFile = mkOption { type = types.str; };
-    onCalendarFull = mkOption { type = types.str; default = "monthly"; };
-    onCalendarIncr = mkOption { type = types.str; default = "Mon, 04:00"; };
-    user = mkOption { type = types.str; default = "barrucadu"; };
-    group = mkOption { type = types.str; default = "users"; };
   };
 }