nixos/modules/services/backup/syncoid.nix

   1 { config, lib, pkgs, ... }:
   2
   3 with lib;
   4
   5 let
   6   cfg = config.services.syncoid;
   7   inherit (config.networking) nftables;
   8
   9   # Extract local dasaset names (so no datasets containing "@")
  10   localDatasetName = d: optionals (d != null) (
  11     let m = builtins.match "([^/@]+[^@]*)" d; in
  12     optionals (m != null) m
  13   );
  14
  15   # Escape as required by: https://www.freedesktop.org/software/systemd/man/systemd.unit.html
  16   escapeUnitName = name:
  17     lib.concatMapStrings (s: if lib.isList s then "-" else s)
  18       (builtins.split "[^a-zA-Z0-9_.\\-]+" name);
  19
  20   # Function to build "zfs allow" commands for the filesystems we've
  21   # delegated permissions to. It also checks if the target dataset
  22   # exists before delegating permissions, if it doesn't exist we
  23   # delegate it to the parent dataset. This should solve the case of
  24   # provisoning new datasets.
  25   buildAllowCommand = permissions: dataset: (
  26     "-+${pkgs.writeShellScript "zfs-allow-${dataset}" ''
  27       set -eux
  28       # Run a ZFS list on the dataset to check if it exists
  29       if zfs list ${lib.escapeShellArg dataset} >/dev/null 2>/dev/null; then
  30         zfs allow "$USER" ${lib.escapeShellArgs [
  31           (concatStringsSep "," permissions)
  32           dataset
  33         ]}
  34       else
  35         zfs allow "$USER" ${lib.escapeShellArgs [
  36           (concatStringsSep "," permissions)
  37           # Remove the last part of the path
  38           (builtins.dirOf dataset)
  39         ]}
  40       fi
  41     ''}"
  42   );
  43
  44   # Function to build "zfs unallow" commands for the filesystems we've
  45   # delegated permissions to. Here we unallow both the target and
  46   # the parent dataset because at this stage we have no way of
  47   # knowing if the allow command did execute on the parent dataset or
  48   # not in the pre-hook. We can't run the same if-then-else in the post hook
  49   # since the dataset should have been created at this point.
  50   buildUnallowCommand = dataset: (
  51     "-+${pkgs.writeShellScript "zfs-unallow-${dataset}" ''
  52       set -eux
  53       zfs unallow "$USER" ${lib.escapeShellArg dataset}
  54       zfs unallow "$USER" ${lib.escapeShellArg (builtins.dirOf dataset)}
  55     ''}"
  56   );
  57 in
  58 {
  59
  60   # Interface
  61
  62   options.services.syncoid = {
  63     enable = mkEnableOption "Syncoid ZFS synchronization service";
  64
  65     interval = mkOption {
  66       type = types.str;
  67       default = "hourly";
  68       example = "*-*-* *:15:00";
  69       description = ''
  70         Run syncoid at this interval. The default is to run hourly.
  71
  72         The format is described in
  73         <citerefentry><refentrytitle>systemd.time</refentrytitle>
  74         <manvolnum>7</manvolnum></citerefentry>.
  75       '';
  76     };
  77
  78     sshKey = mkOption {
  79       type = types.nullOr types.path;
  80       # Prevent key from being copied to store
  81       apply = mapNullable toString;
  82       default = null;
  83       description = ''
  84         SSH private key file to use to login to the remote system. Can be
  85         overridden in individual commands.
  86         For more SSH tuning, you may use syncoid's <literal>--sshoption</literal>
  87         in <link linkend="opt-services.syncoid.commonArgs">commonArgs</link>
  88         and/or in the <literal>extraArgs<literal> of a specific command.
  89       '';
  90     };
  91
  92     localSourceAllow = mkOption {
  93       type = types.listOf types.str;
  94       # Permissions snapshot and destroy are in case --no-sync-snap is not used
  95       default = [ "bookmark" "hold" "send" "snapshot" "destroy" ];
  96       description = ''
  97         Permissions granted for the syncoid user for local source datasets.
  98         See <link xlink:href="https://openzfs.github.io/openzfs-docs/man/8/zfs-allow.8.html"/>
  99         for available permissions.
 100       '';
 101     };
 102
 103     localTargetAllow = mkOption {
 104       type = types.listOf types.str;
 105       default = [ "change-key" "compression" "create" "mount" "mountpoint" "receive" "rollback" ];
 106       example = [ "create" "mount" "receive" "rollback" ];
 107       description = ''
 108         Permissions granted for the syncoid user for local target datasets.
 109         See <link xlink:href="https://openzfs.github.io/openzfs-docs/man/8/zfs-allow.8.html"/>
 110         for available permissions.
 111         Make sure to include the <literal>change-key</literal> permission if you send raw encrypted datasets,
 112         the <literal>compression</literal> permission if you send raw compressed datasets, and so on.
 113         For remote target datasets you'll have to set your remote user permissions by yourself.
 114       '';
 115     };
 116
 117     commonArgs = mkOption {
 118       type = types.listOf types.str;
 119       default = [ ];
 120       example = [ "--no-sync-snap" ];
 121       description = ''
 122         Arguments to add to every syncoid command, unless disabled for that
 123         command. See
 124         <link xlink:href="https://github.com/jimsalterjrs/sanoid/#syncoid-command-line-options"/>
 125         for available options.
 126       '';
 127     };
 128
 129     service = mkOption {
 130       type = types.attrs;
 131       default = { };
 132       description = ''
 133         Systemd configuration common to all syncoid services.
 134       '';
 135     };
 136
 137     commands = mkOption {
 138       type = types.attrsOf (types.submodule ({ name, ... }: {
 139         options = {
 140           source = mkOption {
 141             type = types.str;
 142             example = "pool/dataset";
 143             description = ''
 144               Source ZFS dataset. Can be either local or remote. Defaults to
 145               the attribute name.
 146             '';
 147           };
 148
 149           target = mkOption {
 150             type = types.str;
 151             example = "user@server:pool/dataset";
 152             description = ''
 153               Target ZFS dataset. Can be either local
 154               (<replaceable>pool/dataset</replaceable>) or remote
 155               (<replaceable>user@server:pool/dataset</replaceable>).
 156             '';
 157           };
 158
 159           recursive = mkEnableOption ''the transfer of child datasets'';
 160
 161           sshKey = mkOption {
 162             type = types.nullOr types.path;
 163             # Prevent key from being copied to store
 164             apply = mapNullable toString;
 165             description = ''
 166               SSH private key file to use to login to the remote system.
 167               Defaults to <option>services.syncoid.sshKey</option> option.
 168             '';
 169           };
 170
 171           localSourceAllow = mkOption {
 172             type = types.listOf types.str;
 173             description = ''
 174               Permissions granted for the <option>services.syncoid.user</option> user
 175               for local source datasets. See
 176               <link xlink:href="https://openzfs.github.io/openzfs-docs/man/8/zfs-allow.8.html"/>
 177               for available permissions.
 178               Defaults to <option>services.syncoid.localSourceAllow</option> option.
 179             '';
 180           };
 181
 182           localTargetAllow = mkOption {
 183             type = types.listOf types.str;
 184             description = ''
 185               Permissions granted for the <option>services.syncoid.user</option> user
 186               for local target datasets. See
 187               <link xlink:href="https://openzfs.github.io/openzfs-docs/man/8/zfs-allow.8.html"/>
 188               for available permissions.
 189               Make sure to include the <literal>change-key</literal> permission if you send raw encrypted datasets,
 190               the <literal>compression</literal> permission if you send raw compressed datasets, and so on.
 191               For remote target datasets you'll have to set your remote user permissions by yourself.
 192             '';
 193           };
 194
 195           sendOptions = mkOption {
 196             type = types.separatedString " ";
 197             default = "";
 198             example = "Lc e";
 199             description = ''
 200               Advanced options to pass to zfs send. Options are specified
 201               without their leading dashes and separated by spaces.
 202             '';
 203           };
 204
 205           recvOptions = mkOption {
 206             type = types.separatedString " ";
 207             default = "";
 208             example = "ux recordsize o compression=lz4";
 209             description = ''
 210               Advanced options to pass to zfs recv. Options are specified
 211               without their leading dashes and separated by spaces.
 212             '';
 213           };
 214
 215           useCommonArgs = mkEnableOption ''
 216             configured common arguments to this command
 217           '' // { default = true; };
 218
 219           service = mkOption {
 220             type = types.attrs;
 221             default = { };
 222             description = ''
 223               Systemd configuration specific to this syncoid service.
 224             '';
 225           };
 226
 227           extraArgs = mkOption {
 228             type = types.listOf types.str;
 229             default = [ ];
 230             example = [ "--sshport 2222" ];
 231             description = "Extra syncoid arguments for this command.";
 232           };
 233         };
 234         config = {
 235           source = mkDefault name;
 236           sshKey = mkDefault cfg.sshKey;
 237           localSourceAllow = mkDefault cfg.localSourceAllow;
 238           localTargetAllow = mkDefault cfg.localTargetAllow;
 239         };
 240       }));
 241       default = { };
 242       example = literalExample ''
 243         {
 244           "pool/test".target = "root@target:pool/test";
 245         }
 246       '';
 247       description = "Syncoid commands to run.";
 248     };
 249   };
 250
 251   # Implementation
 252
 253   config = mkIf cfg.enable {
 254     systemd.services = mapAttrs'
 255       (name: c:
 256         nameValuePair "syncoid-${escapeUnitName name}" (mkMerge [
 257           {
 258             description = "Syncoid ZFS synchronization from ${c.source} to ${c.target}";
 259             after = [ "zfs.target" ];
 260             startAt = cfg.interval;
 261             # Here we explicitly use the booted system to guarantee the stable API needed by ZFS.
 262             # Moreover syncoid may need zpool to get feature@extensible_dataset.
 263             path = [ "/run/booted-system/sw" ];
 264             serviceConfig = {
 265               ExecStartPre =
 266                 (map (buildAllowCommand c.localSourceAllow) (localDatasetName c.source)) ++
 267                 (map (buildAllowCommand c.localTargetAllow) (localDatasetName c.target)) ++
 268                 optional nftables.enable "+${pkgs.nftables}/bin/nft add element inet filter nixos-syncoid-uids { $USER }";
 269               ExecStopPost =
 270                 (map buildUnallowCommand (localDatasetName c.source)) ++
 271                 (map buildUnallowCommand (localDatasetName c.target)) ++
 272                 optional nftables.enable "+${pkgs.nftables}/bin/nft delete element inet filter nixos-syncoid-uids { $USER }";
 273               ExecStart = lib.escapeShellArgs ([ "${pkgs.sanoid}/bin/syncoid" ]
 274                 ++ optionals c.useCommonArgs cfg.commonArgs
 275                 ++ optional c.recursive "--recursive"
 276                 ++ optionals (c.sshKey != null) [ "--sshkey" "\${CREDENTIALS_DIRECTORY}/ssh-key" ]
 277                 ++ c.extraArgs
 278                 ++ [
 279                 "--sendoptions"
 280                 c.sendOptions
 281                 "--recvoptions"
 282                 c.recvOptions
 283                 "--no-privilege-elevation"
 284                 c.source
 285                 c.target
 286               ]);
 287               DynamicUser = true;
 288               LoadCredential = [ "ssh-key:${c.sshKey}" ];
 289               # Prevent SSH control sockets of different syncoid services from interfering
 290               PrivateTmp = true;
 291               # Permissive access to /proc because syncoid
 292               # calls ps(1) to detect ongoing `zfs receive`.
 293               ProcSubset = "all";
 294               ProtectProc = "default";
 295
 296               # The following options are only for optimizing:
 297               # systemd-analyze security | grep syncoid-'*'
 298               AmbientCapabilities = "";
 299               CapabilityBoundingSet = "";
 300               DeviceAllow = [ "/dev/zfs" ];
 301               LockPersonality = true;
 302               MemoryDenyWriteExecute = true;
 303               NoNewPrivileges = true;
 304               PrivateDevices = true;
 305               PrivateMounts = true;
 306               PrivateNetwork = mkDefault false;
 307               PrivateUsers = true;
 308               ProtectClock = true;
 309               ProtectControlGroups = true;
 310               ProtectHome = true;
 311               ProtectHostname = true;
 312               ProtectKernelLogs = true;
 313               ProtectKernelModules = true;
 314               ProtectKernelTunables = true;
 315               ProtectSystem = "strict";
 316               RemoveIPC = true;
 317               RestrictAddressFamilies = [ "AF_UNIX" "AF_INET" "AF_INET6" ];
 318               RestrictNamespaces = true;
 319               RestrictRealtime = true;
 320               RestrictSUIDSGID = true;
 321               RootDirectory = "/run/syncoid/${escapeUnitName name}";
 322               RootDirectoryStartOnly = true;
 323               BindPaths = [ "/dev/zfs" ];
 324               BindReadOnlyPaths = [ builtins.storeDir "/etc" "/run" "/bin/sh"
 325                 # A custom LD_LIBRARY_PATH is needed to access in `getent passwd`
 326                 # the systemd's entry about the DynamicUser=,
 327                 # so that ssh won't fail with: "No user exists for uid $UID".
 328                 # Unfortunately, Bash is incompatible with libnss_systemd.so:
 329                 # https://www.mail-archive.com/bug-bash@gnu.org/msg24306.html
 330                 # Hence the wrapping of ssh is done here as a mounted path,
 331                 # because Nixpkgs' wrapping of syncoid enforces the use
 332                 # of the ${pkgs.openssh}/bin/ssh path.
 333                 # This problem does not arise on NixOS systems where stdenv.hostPlatform.libc == "musl",
 334                 # because then Bash is built with --without-bash-malloc
 335                 ("${pkgs.writeShellScript "ssh-with-support-for-DynamicUser" ''
 336                   export LD_LIBRARY_PATH="${config.system.nssModules.path}"
 337                   exec -a ${pkgs.openssh}/bin/ssh /bin/ssh "$@"
 338                 ''}:${pkgs.openssh}/bin/ssh")
 339                 "${pkgs.openssh}/bin/ssh:/bin/ssh"
 340               ];
 341               # Avoid useless mounting of RootDirectory= in the own RootDirectory= of ExecStart='s mount namespace.
 342               InaccessiblePaths = [ "-+/run/syncoid/${escapeUnitName name}" ];
 343               MountAPIVFS = true;
 344               # Create RootDirectory= in the host's mount namespace.
 345               RuntimeDirectory = [ "syncoid/${escapeUnitName name}" ];
 346               RuntimeDirectoryMode = "700";
 347               SystemCallFilter = [
 348                 "@system-service"
 349                 # Groups in @system-service which do not contain a syscall listed by:
 350                 # perf stat -x, 2>perf.log -e 'syscalls:sys_enter_*' syncoid …
 351                 # awk >perf.syscalls -F "," '$1 > 0 {sub("syscalls:sys_enter_","",$3); print $3}' perf.log
 352                 # systemd-analyze syscall-filter | grep -v -e '#' | sed -e ':loop; /^[^ ]/N; s/\n //; t loop' | grep $(printf ' -e \\<%s\\>' $(cat perf.syscalls)) | cut -f 1 -d ' '
 353                 "~@aio"
 354                 "~@chown"
 355                 "~@keyring"
 356                 "~@memlock"
 357                 "~@privileged"
 358                 "~@resources"
 359                 "~@setuid"
 360                 "~@timer"
 361               ];
 362               SystemCallArchitectures = "native";
 363               # This is for BindPaths= and BindReadOnlyPaths=
 364               # to allow traversal of directories they create in RootDirectory=.
 365               UMask = "0066";
 366             };
 367           }
 368           cfg.service
 369           c.service
 370         ]))
 371       cfg.commands;
 372     networking.nftables.ruleset = ''
 373       # A set containing the dynamic UIDs of the syncoid services currently active
 374       add set inet filter nixos-syncoid-uids { type uid; }
 375       # Example of use (assuming fw2net is being called by the output chain):
 376       #add rule inet filter fw2net meta skuid @nixos-syncoid-uids meta l4proto tcp accept
 377     '';
 378   };
 379
 380   meta.maintainers = with maintainers; [ julm lopsided98 ];
 381 }