nixos/modules/services/backup/znapzend.nix

   1 {
   2   config,
   3   lib,
   4   pkgs,
   5   ...
   6 }:
   7 let
   8
   9   planDescription = ''
  10     The znapzend backup plan to use for the source.
  11
  12     The plan specifies how often to backup and for how long to keep the
  13     backups. It consists of a series of retention periods to interval
  14     associations:
  15
  16     ```
  17       retA=>intA,retB=>intB,...
  18     ```
  19
  20     Both intervals and retention periods are expressed in standard units
  21     of time or multiples of them. You can use both the full name or a
  22     shortcut according to the following listing:
  23
  24     ```
  25       second|sec|s, minute|min, hour|h, day|d, week|w, month|mon|m, year|y
  26     ```
  27
  28     See {manpage}`znapzendzetup(1)` for more info.
  29   '';
  30   planExample = "1h=>10min,1d=>1h,1w=>1d,1m=>1w,1y=>1m";
  31
  32   # A type for a string of the form number{b|k|M|G}
  33   mbufferSizeType = lib.types.str // {
  34     check = x: lib.types.str.check x && builtins.isList (builtins.match "^[0-9]+[bkMG]$" x);
  35     description = "string of the form number{b|k|M|G}";
  36   };
  37
  38   enabledFeatures = lib.concatLists (
  39     lib.mapAttrsToList (name: enabled: lib.optional enabled name) cfg.features
  40   );
  41
  42   # Type for a string that must contain certain other strings (the list parameter).
  43   # Note that these would need regex escaping.
  44   stringContainingStrings =
  45     list:
  46     let
  47       matching = s: map (str: builtins.match ".*${str}.*" s) list;
  48     in
  49     lib.types.str
  50     // {
  51       check = x: lib.types.str.check x && lib.all lib.isList (matching x);
  52       description = "string containing all of the characters ${lib.concatStringsSep ", " list}";
  53     };
  54
  55   timestampType = stringContainingStrings [
  56     "%Y"
  57     "%m"
  58     "%d"
  59     "%H"
  60     "%M"
  61     "%S"
  62   ];
  63
  64   destType =
  65     srcConfig:
  66     lib.types.submodule (
  67       { name, ... }:
  68       {
  69         options = {
  70
  71           label = lib.mkOption {
  72             type = lib.types.str;
  73             description = "Label for this destination. Defaults to the attribute name.";
  74           };
  75
  76           plan = lib.mkOption {
  77             type = lib.types.str;
  78             description = planDescription;
  79             example = planExample;
  80           };
  81
  82           dataset = lib.mkOption {
  83             type = lib.types.str;
  84             description = "Dataset name to send snapshots to.";
  85             example = "tank/main";
  86           };
  87
  88           host = lib.mkOption {
  89             type = lib.types.nullOr lib.types.str;
  90             description = ''
  91               Host to use for the destination dataset. Can be prefixed with
  92               `user@` to specify the ssh user.
  93             '';
  94             default = null;
  95             example = "john@example.com";
  96           };
  97
  98           presend = lib.mkOption {
  99             type = lib.types.nullOr lib.types.str;
 100             description = ''
 101               Command to run before sending the snapshot to the destination.
 102               Intended to run a remote script via {command}`ssh` on the
 103               destination, e.g. to bring up a backup disk or server or to put a
 104               zpool online/offline. See also {option}`postsend`.
 105             '';
 106             default = null;
 107             example = "ssh root@bserv zpool import -Nf tank";
 108           };
 109
 110           postsend = lib.mkOption {
 111             type = lib.types.nullOr lib.types.str;
 112             description = ''
 113               Command to run after sending the snapshot to the destination.
 114               Intended to run a remote script via {command}`ssh` on the
 115               destination, e.g. to bring up a backup disk or server or to put a
 116               zpool online/offline. See also {option}`presend`.
 117             '';
 118             default = null;
 119             example = "ssh root@bserv zpool export tank";
 120           };
 121         };
 122
 123         config = {
 124           label = lib.mkDefault name;
 125           plan = lib.mkDefault srcConfig.plan;
 126         };
 127       }
 128     );
 129
 130   srcType = lib.types.submodule (
 131     { name, config, ... }:
 132     {
 133       options = {
 134
 135         enable = lib.mkOption {
 136           type = lib.types.bool;
 137           description = "Whether to enable this source.";
 138           default = true;
 139         };
 140
 141         recursive = lib.mkOption {
 142           type = lib.types.bool;
 143           description = "Whether to do recursive snapshots.";
 144           default = false;
 145         };
 146
 147         mbuffer = {
 148           enable = lib.mkOption {
 149             type = lib.types.bool;
 150             description = "Whether to use {command}`mbuffer`.";
 151             default = false;
 152           };
 153
 154           port = lib.mkOption {
 155             type = lib.types.nullOr lib.types.ints.u16;
 156             description = ''
 157               Port to use for {command}`mbuffer`.
 158
 159               If this is null, it will run {command}`mbuffer` through
 160               ssh.
 161
 162               If this is not null, it will run {command}`mbuffer`
 163               directly through TCP, which is not encrypted but faster. In that
 164               case the given port needs to be open on the destination host.
 165             '';
 166             default = null;
 167           };
 168
 169           size = lib.mkOption {
 170             type = mbufferSizeType;
 171             description = ''
 172               The size for {command}`mbuffer`.
 173               Supports the units b, k, M, G.
 174             '';
 175             default = "1G";
 176             example = "128M";
 177           };
 178         };
 179
 180         presnap = lib.mkOption {
 181           type = lib.types.nullOr lib.types.str;
 182           description = ''
 183             Command to run before snapshots are taken on the source dataset,
 184             e.g. for database locking/flushing. See also
 185             {option}`postsnap`.
 186           '';
 187           default = null;
 188           example = lib.literalExpression ''
 189             '''''${pkgs.mariadb}/bin/mysql -e "set autocommit=0;flush tables with read lock;\\! ''${pkgs.coreutils}/bin/sleep 600" &  ''${pkgs.coreutils}/bin/echo $! > /tmp/mariadblock.pid ; sleep 10'''
 190           '';
 191         };
 192
 193         postsnap = lib.mkOption {
 194           type = lib.types.nullOr lib.types.str;
 195           description = ''
 196             Command to run after snapshots are taken on the source dataset,
 197             e.g. for database unlocking. See also {option}`presnap`.
 198           '';
 199           default = null;
 200           example = lib.literalExpression ''
 201             "''${pkgs.coreutils}/bin/kill `''${pkgs.coreutils}/bin/cat /tmp/mariadblock.pid`;''${pkgs.coreutils}/bin/rm /tmp/mariadblock.pid"
 202           '';
 203         };
 204
 205         timestampFormat = lib.mkOption {
 206           type = timestampType;
 207           description = ''
 208             The timestamp format to use for constructing snapshot names.
 209             The syntax is `strftime`-like. The string must
 210             consist of the mandatory `%Y %m %d %H %M %S`.
 211             Optionally  `- _ . :`  characters as well as any
 212             alphanumeric character are allowed. If suffixed by a
 213             `Z`, times will be in UTC.
 214           '';
 215           default = "%Y-%m-%d-%H%M%S";
 216           example = "znapzend-%m.%d.%Y-%H%M%SZ";
 217         };
 218
 219         sendDelay = lib.mkOption {
 220           type = lib.types.int;
 221           description = ''
 222             Specify delay (in seconds) before sending snaps to the destination.
 223             May be useful if you want to control sending time.
 224           '';
 225           default = 0;
 226           example = 60;
 227         };
 228
 229         plan = lib.mkOption {
 230           type = lib.types.str;
 231           description = planDescription;
 232           example = planExample;
 233         };
 234
 235         dataset = lib.mkOption {
 236           type = lib.types.str;
 237           description = "The dataset to use for this source.";
 238           example = "tank/home";
 239         };
 240
 241         destinations = lib.mkOption {
 242           type = lib.types.attrsOf (destType config);
 243           description = "Additional destinations.";
 244           default = { };
 245           example = lib.literalExpression ''
 246             {
 247               local = {
 248                 dataset = "btank/backup";
 249                 presend = "zpool import -N btank";
 250                 postsend = "zpool export btank";
 251               };
 252               remote = {
 253                 host = "john@example.com";
 254                 dataset = "tank/john";
 255               };
 256             };
 257           '';
 258         };
 259       };
 260
 261       config = {
 262         dataset = lib.mkDefault name;
 263       };
 264
 265     }
 266   );
 267
 268   ### Generating the configuration from here
 269
 270   cfg = config.services.znapzend;
 271
 272   onOff = b: if b then "on" else "off";
 273   nullOff = b: if b == null then "off" else toString b;
 274   stripSlashes = lib.replaceStrings [ "/" ] [ "." ];
 275
 276   attrsToFile =
 277     config: lib.concatStringsSep "\n" (builtins.attrValues (lib.mapAttrs (n: v: "${n}=${v}") config));
 278
 279   mkDestAttrs =
 280     dst:
 281     with dst;
 282     lib.mapAttrs' (n: v: lib.nameValuePair "dst_${label}${n}" v) (
 283       {
 284         "" = lib.optionalString (host != null) "${host}:" + dataset;
 285         _plan = plan;
 286       }
 287       // lib.optionalAttrs (presend != null) {
 288         _precmd = presend;
 289       }
 290       // lib.optionalAttrs (postsend != null) {
 291         _pstcmd = postsend;
 292       }
 293     );
 294
 295   mkSrcAttrs =
 296     srcCfg:
 297     with srcCfg;
 298     {
 299       enabled = onOff enable;
 300       # mbuffer is not referenced by its full path to accommodate non-NixOS systems or differing mbuffer versions between source and target
 301       mbuffer =
 302         with mbuffer;
 303         if enable then "mbuffer" + lib.optionalString (port != null) ":${toString port}" else "off";
 304       mbuffer_size = mbuffer.size;
 305       post_znap_cmd = nullOff postsnap;
 306       pre_znap_cmd = nullOff presnap;
 307       recursive = onOff recursive;
 308       src = dataset;
 309       src_plan = plan;
 310       tsformat = timestampFormat;
 311       zend_delay = toString sendDelay;
 312     }
 313     // lib.foldr (a: b: a // b) { } (map mkDestAttrs (builtins.attrValues destinations));
 314
 315   files = lib.mapAttrs' (
 316     n: srcCfg:
 317     let
 318       fileText = attrsToFile (mkSrcAttrs srcCfg);
 319     in
 320     {
 321       name = srcCfg.dataset;
 322       value = pkgs.writeText (stripSlashes srcCfg.dataset) fileText;
 323     }
 324   ) cfg.zetup;
 325
 326 in
 327 {
 328   options = {
 329     services.znapzend = {
 330       enable = lib.mkEnableOption "ZnapZend ZFS backup daemon";
 331
 332       logLevel = lib.mkOption {
 333         default = "debug";
 334         example = "warning";
 335         type = lib.types.enum [
 336           "debug"
 337           "info"
 338           "warning"
 339           "err"
 340           "alert"
 341         ];
 342         description = ''
 343           The log level when logging to file. Any of debug, info, warning, err,
 344           alert. Default in daemonized form is debug.
 345         '';
 346       };
 347
 348       logTo = lib.mkOption {
 349         type = lib.types.str;
 350         default = "syslog::daemon";
 351         example = "/var/log/znapzend.log";
 352         description = ''
 353           Where to log to (syslog::\<facility\> or \<filepath\>).
 354         '';
 355       };
 356
 357       mailErrorSummaryTo = lib.mkOption {
 358         type = lib.types.singleLineStr;
 359         default = "";
 360         description = ''
 361           Email address to send a summary to if "send task(s) failed".
 362         '';
 363       };
 364
 365       noDestroy = lib.mkOption {
 366         type = lib.types.bool;
 367         default = false;
 368         description = "Does all changes to the filesystem except destroy.";
 369       };
 370
 371       autoCreation = lib.mkOption {
 372         type = lib.types.bool;
 373         default = false;
 374         description = "Automatically create the destination dataset if it does not exist.";
 375       };
 376
 377       zetup = lib.mkOption {
 378         type = lib.types.attrsOf srcType;
 379         description = "Znapzend configuration.";
 380         default = { };
 381         example = lib.literalExpression ''
 382           {
 383             "tank/home" = {
 384               # Make snapshots of tank/home every hour, keep those for 1 day,
 385               # keep every days snapshot for 1 month, etc.
 386               plan = "1d=>1h,1m=>1d,1y=>1m";
 387               recursive = true;
 388               # Send all those snapshots to john@example.com:rtank/john as well
 389               destinations.remote = {
 390                 host = "john@example.com";
 391                 dataset = "rtank/john";
 392               };
 393             };
 394           };
 395         '';
 396       };
 397
 398       pure = lib.mkOption {
 399         type = lib.types.bool;
 400         description = ''
 401           Do not persist any stateful znapzend setups. If this option is
 402           enabled, your previously set znapzend setups will be cleared and only
 403           the ones defined with this module will be applied.
 404         '';
 405         default = false;
 406       };
 407
 408       features.oracleMode = lib.mkEnableOption ''
 409         destroying snapshots one by one instead of using one long argument list.
 410         If source and destination are out of sync for a long time, you may have
 411         so many snapshots to destroy that the argument gets is too long and the
 412         command fails
 413       '';
 414       features.recvu = lib.mkEnableOption ''
 415         recvu feature which uses `-u` on the receiving end to keep the destination
 416         filesystem unmounted
 417       '';
 418       features.compressed = lib.mkEnableOption ''
 419         compressed feature which adds the options `-Lce` to
 420         the {command}`zfs send` command. When this is enabled, make
 421         sure that both the sending and receiving pool have the same relevant
 422         features enabled. Using `-c` will skip unnecessary
 423         decompress-compress stages, `-L` is for large block
 424         support and -e is for embedded data support. see
 425         {manpage}`znapzend(1)`
 426         and {manpage}`zfs(8)`
 427         for more info
 428       '';
 429       features.sendRaw = lib.mkEnableOption ''
 430         sendRaw feature which adds the options `-w` to the
 431         {command}`zfs send` command. For encrypted source datasets this
 432         instructs zfs not to decrypt before sending which results in a remote
 433         backup that can't be read without the encryption key/passphrase, useful
 434         when the remote isn't fully trusted or not physically secure. This
 435         option must be used consistently, raw incrementals cannot be based on
 436         non-raw snapshots and vice versa
 437       '';
 438       features.skipIntermediates = lib.mkEnableOption ''
 439         the skipIntermediates feature to send a single increment
 440         between latest common snapshot and the newly made one. It may skip
 441         several source snaps if the destination was offline for some time, and
 442         it should skip snapshots not managed by znapzend. Normally for online
 443         destinations, the new snapshot is sent as soon as it is created on the
 444         source, so there are no automatic increments to skip
 445       '';
 446       features.lowmemRecurse = lib.mkEnableOption ''
 447         use lowmemRecurse on systems where you have too many datasets, so a
 448         recursive listing of attributes to find backup plans exhausts the
 449         memory available to {command}`znapzend`: instead, go the slower
 450         way to first list all impacted dataset names, and then query their
 451         configs one by one
 452       '';
 453       features.zfsGetType = lib.mkEnableOption ''
 454         using zfsGetType if your {command}`zfs get` supports a
 455         `-t` argument for filtering by dataset type at all AND
 456         lists properties for snapshots by default when recursing, so that there
 457         is too much data to process while searching for backup plans.
 458         If these two conditions apply to your system, the time needed for a
 459         `--recursive` search for backup plans can literally
 460         differ by hundreds of times (depending on the amount of snapshots in
 461         that dataset tree... and a decent backup plan will ensure you have a lot
 462         of those), so you would benefit from requesting this feature
 463       '';
 464     };
 465   };
 466
 467   config = lib.mkIf cfg.enable {
 468     environment.systemPackages = [ pkgs.znapzend ];
 469
 470     systemd.services = {
 471       znapzend = {
 472         description = "ZnapZend - ZFS Backup System";
 473         wantedBy = [ "zfs.target" ];
 474         after = [ "zfs.target" ];
 475
 476         path = with pkgs; [
 477           zfs
 478           mbuffer
 479           openssh
 480         ];
 481
 482         preStart =
 483           lib.optionalString cfg.pure ''
 484             echo Resetting znapzend zetups
 485             ${pkgs.znapzend}/bin/znapzendzetup list \
 486               | grep -oP '(?<=\*\*\* backup plan: ).*(?= \*\*\*)' \
 487               | xargs -I{} ${pkgs.znapzend}/bin/znapzendzetup delete "{}"
 488           ''
 489           + lib.concatStringsSep "\n" (
 490             lib.mapAttrsToList (dataset: config: ''
 491               echo Importing znapzend zetup ${config} for dataset ${dataset}
 492               ${pkgs.znapzend}/bin/znapzendzetup import --write ${dataset} ${config} &
 493             '') files
 494           )
 495           + ''
 496             wait
 497           '';
 498
 499         serviceConfig = {
 500           # znapzendzetup --import apparently tries to connect to the backup
 501           # host 3 times with a timeout of 30 seconds, leading to a startup
 502           # delay of >90s when the host is down, which is just above the default
 503           # service timeout of 90 seconds. Increase the timeout so it doesn't
 504           # make the service fail in that case.
 505           TimeoutStartSec = 180;
 506           # Needs to have write access to ZFS
 507           User = "root";
 508           ExecStart =
 509             let
 510               args = lib.concatStringsSep " " [
 511                 "--logto=${cfg.logTo}"
 512                 "--loglevel=${cfg.logLevel}"
 513                 (lib.optionalString cfg.noDestroy "--nodestroy")
 514                 (lib.optionalString cfg.autoCreation "--autoCreation")
 515                 (lib.optionalString (cfg.mailErrorSummaryTo != "") "--mailErrorSummaryTo=${cfg.mailErrorSummaryTo}")
 516                 (lib.optionalString (
 517                   enabledFeatures != [ ]
 518                 ) "--features=${lib.concatStringsSep "," enabledFeatures}")
 519               ];
 520             in
 521             "${pkgs.znapzend}/bin/znapzend ${args}";
 522           ExecReload = "${pkgs.coreutils}/bin/kill -HUP $MAINPID";
 523           Restart = "on-failure";
 524         };
 525       };
 526     };
 527   };
 528
 529   meta.maintainers = with lib.maintainers; [ SlothOfAnarchy ];
 530 }