nixos/btrbk: add snapshotOnly option (#369480)

Author: rhendric

doc/manpage-urls.json

@@ -3,6 +3,7 @@
   "binfmt.d(5)": "https://www.freedesktop.org/software/systemd/man/binfmt.d.html",
   "bootctl(1)": "https://www.freedesktop.org/software/systemd/man/bootctl.html",
   "bootup(7)": "https://www.freedesktop.org/software/systemd/man/bootup.html",
+  "btrbk(1)": "https://digint.ch/btrbk/doc/btrbk.1.html",
   "busctl(1)": "https://www.freedesktop.org/software/systemd/man/busctl.html",
   "cat(1)": "https://www.gnu.org/software/coreutils/manual/html_node/cat-invocation.html",
   "coredump.conf(5)": "https://www.freedesktop.org/software/systemd/man/coredump.conf.html",

nixos/modules/services/backup/btrbk.nix

@@ -185,6 +185,17 @@ in
                   Setting it to null disables the timer, thus this instance can only be started manually.
                 '';
               };
+              snapshotOnly = mkOption {
+                type = types.bool;
+                default = false;
+                description = ''
+                  Whether to run in snapshot only mode. This skips backup creation and deletion steps.
+                  Useful when you want to manually backup to an external drive that might not always be connected.
+                  Use `btrbk -c /path/to/conf resume` to trigger manual backups.
+                  More examples [here](https://github.com/digint/btrbk#example-backups-to-usb-disk).
+                  See also `snapshot` subcommand in {manpage}`btrbk(1)`.
+                '';
+              };
               settings = mkOption {
                 type = types.submodule {
                   freeformType =
@@ -353,7 +364,9 @@ in
           User = "btrbk";
           Group = "btrbk";
           Type = "oneshot";
-          ExecStart = "${pkgs.btrbk}/bin/btrbk -c /etc/btrbk/${name}.conf run";
+          ExecStart = "${pkgs.btrbk}/bin/btrbk -c /etc/btrbk/${name}.conf ${
+            if instance.snapshotOnly then "snapshot" else "run"
+          }";
           Nice = cfg.niceness;
           IOSchedulingClass = cfg.ioSchedulingClass;
           StateDirectory = "btrbk";