nixos/lib/systemd-unit-options.nix

   1 { lib, systemdUtils }:
   2
   3 with systemdUtils.lib;
   4 with lib;
   5
   6 let
   7   checkService = checkUnitConfig "Service" [
   8     (assertValueOneOf "Type" [
   9       "exec" "simple" "forking" "oneshot" "dbus" "notify" "idle"
  10     ])
  11     (assertValueOneOf "Restart" [
  12       "no" "on-success" "on-failure" "on-abnormal" "on-abort" "always"
  13     ])
  14   ];
  15
  16 in rec {
  17
  18   unitOption = mkOptionType {
  19     name = "systemd option";
  20     merge = loc: defs:
  21       let
  22         defs' = filterOverrides defs;
  23       in
  24         if isList (head defs').value
  25         then concatMap (def:
  26           if builtins.typeOf def.value == "list"
  27           then def.value
  28           else
  29             throw "The definitions for systemd unit options should be either all lists, representing repeatable options, or all non-lists, but for the option ${showOption loc}, the definitions are a mix of list and non-list ${lib.options.showDefs defs'}"
  30         ) defs'
  31
  32         else mergeEqualOption loc defs';
  33   };
  34
  35   sharedOptions = {
  36
  37     enable = mkOption {
  38       default = true;
  39       type = types.bool;
  40       description = lib.mdDoc ''
  41         If set to false, this unit will be a symlink to
  42         /dev/null. This is primarily useful to prevent specific
  43         template instances
  44         (e.g. `serial-getty@ttyS0`) from being
  45         started. Note that `enable=true` does not
  46         make a unit start by default at boot; if you want that, see
  47         `wantedBy`.
  48       '';
  49     };
  50
  51     overrideStrategy = mkOption {
  52       default = "asDropinIfExists";
  53       type = types.enum [ "asDropinIfExists" "asDropin" ];
  54       description = lib.mdDoc ''
  55         Defines how unit configuration is provided for systemd:
  56
  57         `asDropinIfExists` creates a unit file when no unit file is provided by the package
  58         otherwise a drop-in file name `overrides.conf`.
  59
  60         `asDropin` creates a drop-in file named `overrides.conf`.
  61         Mainly needed to define instances for systemd template units (e.g. `systemd-nspawn@mycontainer.service`).
  62
  63         See also {manpage}`systemd.unit(5)`.
  64       '';
  65     };
  66
  67     requiredBy = mkOption {
  68       default = [];
  69       type = types.listOf unitNameType;
  70       description = lib.mdDoc ''
  71         Units that require (i.e. depend on and need to go down with) this unit.
  72         As discussed in the `wantedBy` option description this also creates
  73         `.requires` symlinks automatically.
  74       '';
  75     };
  76
  77     wantedBy = mkOption {
  78       default = [];
  79       type = types.listOf unitNameType;
  80       description = lib.mdDoc ''
  81         Units that want (i.e. depend on) this unit. The default method for
  82         starting a unit by default at boot time is to set this option to
  83         `["multi-user.target"]` for system services. Likewise for user units
  84         (`systemd.user.<name>.*`) set it to `["default.target"]` to make a unit
  85         start by default when the user `<name>` logs on.
  86
  87         This option creates a `.wants` symlink in the given target that exists
  88         statelessly without the need for running `systemctl enable`.
  89         The `[Install]` section described in {manpage}`systemd.unit(5)` however is
  90         not supported because it is a stateful process that does not fit well
  91         into the NixOS design.
  92       '';
  93     };
  94
  95     aliases = mkOption {
  96       default = [];
  97       type = types.listOf unitNameType;
  98       description = lib.mdDoc "Aliases of that unit.";
  99     };
 100
 101   };
 102
 103   concreteUnitOptions = sharedOptions // {
 104
 105     text = mkOption {
 106       type = types.nullOr types.str;
 107       default = null;
 108       description = lib.mdDoc "Text of this systemd unit.";
 109     };
 110
 111     unit = mkOption {
 112       internal = true;
 113       description = lib.mdDoc "The generated unit.";
 114     };
 115
 116   };
 117
 118   commonUnitOptions = {
 119     options = sharedOptions // {
 120
 121       description = mkOption {
 122         default = "";
 123         type = types.singleLineStr;
 124         description = lib.mdDoc "Description of this unit used in systemd messages and progress indicators.";
 125       };
 126
 127       documentation = mkOption {
 128         default = [];
 129         type = types.listOf types.str;
 130         description = lib.mdDoc "A list of URIs referencing documentation for this unit or its configuration.";
 131       };
 132
 133       requires = mkOption {
 134         default = [];
 135         type = types.listOf unitNameType;
 136         description = lib.mdDoc ''
 137           Start the specified units when this unit is started, and stop
 138           this unit when the specified units are stopped or fail.
 139         '';
 140       };
 141
 142       wants = mkOption {
 143         default = [];
 144         type = types.listOf unitNameType;
 145         description = lib.mdDoc ''
 146           Start the specified units when this unit is started.
 147         '';
 148       };
 149
 150       after = mkOption {
 151         default = [];
 152         type = types.listOf unitNameType;
 153         description = lib.mdDoc ''
 154           If the specified units are started at the same time as
 155           this unit, delay this unit until they have started.
 156         '';
 157       };
 158
 159       before = mkOption {
 160         default = [];
 161         type = types.listOf unitNameType;
 162         description = lib.mdDoc ''
 163           If the specified units are started at the same time as
 164           this unit, delay them until this unit has started.
 165         '';
 166       };
 167
 168       bindsTo = mkOption {
 169         default = [];
 170         type = types.listOf unitNameType;
 171         description = lib.mdDoc ''
 172           Like ‘requires’, but in addition, if the specified units
 173           unexpectedly disappear, this unit will be stopped as well.
 174         '';
 175       };
 176
 177       partOf = mkOption {
 178         default = [];
 179         type = types.listOf unitNameType;
 180         description = lib.mdDoc ''
 181           If the specified units are stopped or restarted, then this
 182           unit is stopped or restarted as well.
 183         '';
 184       };
 185
 186       conflicts = mkOption {
 187         default = [];
 188         type = types.listOf unitNameType;
 189         description = lib.mdDoc ''
 190           If the specified units are started, then this unit is stopped
 191           and vice versa.
 192         '';
 193       };
 194
 195       requisite = mkOption {
 196         default = [];
 197         type = types.listOf unitNameType;
 198         description = lib.mdDoc ''
 199           Similar to requires. However if the units listed are not started,
 200           they will not be started and the transaction will fail.
 201         '';
 202       };
 203
 204       unitConfig = mkOption {
 205         default = {};
 206         example = { RequiresMountsFor = "/data"; };
 207         type = types.attrsOf unitOption;
 208         description = lib.mdDoc ''
 209           Each attribute in this set specifies an option in the
 210           `[Unit]` section of the unit.  See
 211           {manpage}`systemd.unit(5)` for details.
 212         '';
 213       };
 214
 215       onFailure = mkOption {
 216         default = [];
 217         type = types.listOf unitNameType;
 218         description = lib.mdDoc ''
 219           A list of one or more units that are activated when
 220           this unit enters the "failed" state.
 221         '';
 222       };
 223
 224       onSuccess = mkOption {
 225         default = [];
 226         type = types.listOf unitNameType;
 227         description = lib.mdDoc ''
 228           A list of one or more units that are activated when
 229           this unit enters the "inactive" state.
 230         '';
 231       };
 232
 233       startLimitBurst = mkOption {
 234          type = types.int;
 235          description = lib.mdDoc ''
 236            Configure unit start rate limiting. Units which are started
 237            more than startLimitBurst times within an interval time
 238            interval are not permitted to start any more.
 239          '';
 240       };
 241
 242       startLimitIntervalSec = mkOption {
 243          type = types.int;
 244          description = lib.mdDoc ''
 245            Configure unit start rate limiting. Units which are started
 246            more than startLimitBurst times within an interval time
 247            interval are not permitted to start any more.
 248          '';
 249       };
 250
 251     };
 252   };
 253
 254   stage2CommonUnitOptions = {
 255     imports = [
 256       commonUnitOptions
 257     ];
 258
 259     options = {
 260       restartTriggers = mkOption {
 261         default = [];
 262         type = types.listOf types.unspecified;
 263         description = lib.mdDoc ''
 264           An arbitrary list of items such as derivations.  If any item
 265           in the list changes between reconfigurations, the service will
 266           be restarted.
 267         '';
 268       };
 269
 270       reloadTriggers = mkOption {
 271         default = [];
 272         type = types.listOf unitOption;
 273         description = lib.mdDoc ''
 274           An arbitrary list of items such as derivations.  If any item
 275           in the list changes between reconfigurations, the service will
 276           be reloaded.  If anything but a reload trigger changes in the
 277           unit file, the unit will be restarted instead.
 278         '';
 279       };
 280     };
 281   };
 282   stage1CommonUnitOptions = commonUnitOptions;
 283
 284   serviceOptions = { name, config, ... }: {
 285     options = {
 286
 287       environment = mkOption {
 288         default = {};
 289         type = with types; attrsOf (nullOr (oneOf [ str path package ]));
 290         example = { PATH = "/foo/bar/bin"; LANG = "nl_NL.UTF-8"; };
 291         description = lib.mdDoc "Environment variables passed to the service's processes.";
 292       };
 293
 294       path = mkOption {
 295         default = [];
 296         type = with types; listOf (oneOf [ package str ]);
 297         description = lib.mdDoc ''
 298           Packages added to the service's {env}`PATH`
 299           environment variable.  Both the {file}`bin`
 300           and {file}`sbin` subdirectories of each
 301           package are added.
 302         '';
 303       };
 304
 305       serviceConfig = mkOption {
 306         default = {};
 307         example =
 308           { RestartSec = 5;
 309           };
 310         type = types.addCheck (types.attrsOf unitOption) checkService;
 311         description = lib.mdDoc ''
 312           Each attribute in this set specifies an option in the
 313           `[Service]` section of the unit.  See
 314           {manpage}`systemd.service(5)` for details.
 315         '';
 316       };
 317
 318       script = mkOption {
 319         type = types.lines;
 320         default = "";
 321         description = lib.mdDoc "Shell commands executed as the service's main process.";
 322       };
 323
 324       scriptArgs = mkOption {
 325         type = types.str;
 326         default = "";
 327         example = "%i";
 328         description = lib.mdDoc ''
 329           Arguments passed to the main process script.
 330           Can contain specifiers (`%` placeholders expanded by systemd, see {manpage}`systemd.unit(5)`).
 331         '';
 332       };
 333
 334       preStart = mkOption {
 335         type = types.lines;
 336         default = "";
 337         description = lib.mdDoc ''
 338           Shell commands executed before the service's main process
 339           is started.
 340         '';
 341       };
 342
 343       postStart = mkOption {
 344         type = types.lines;
 345         default = "";
 346         description = lib.mdDoc ''
 347           Shell commands executed after the service's main process
 348           is started.
 349         '';
 350       };
 351
 352       reload = mkOption {
 353         type = types.lines;
 354         default = "";
 355         description = lib.mdDoc ''
 356           Shell commands executed when the service's main process
 357           is reloaded.
 358         '';
 359       };
 360
 361       preStop = mkOption {
 362         type = types.lines;
 363         default = "";
 364         description = lib.mdDoc ''
 365           Shell commands executed to stop the service.
 366         '';
 367       };
 368
 369       postStop = mkOption {
 370         type = types.lines;
 371         default = "";
 372         description = lib.mdDoc ''
 373           Shell commands executed after the service's main process
 374           has exited.
 375         '';
 376       };
 377
 378       jobScripts = mkOption {
 379         type = with types; coercedTo path singleton (listOf path);
 380         internal = true;
 381         description = lib.mdDoc "A list of all job script derivations of this unit.";
 382         default = [];
 383       };
 384
 385     };
 386
 387     config = mkMerge [
 388       (mkIf (config.preStart != "") rec {
 389         jobScripts = makeJobScript "${name}-pre-start" config.preStart;
 390         serviceConfig.ExecStartPre = [ jobScripts ];
 391       })
 392       (mkIf (config.script != "") rec {
 393         jobScripts = makeJobScript "${name}-start" config.script;
 394         serviceConfig.ExecStart = jobScripts + " " + config.scriptArgs;
 395       })
 396       (mkIf (config.postStart != "") rec {
 397         jobScripts = (makeJobScript "${name}-post-start" config.postStart);
 398         serviceConfig.ExecStartPost = [ jobScripts ];
 399       })
 400       (mkIf (config.reload != "") rec {
 401         jobScripts = makeJobScript "${name}-reload" config.reload;
 402         serviceConfig.ExecReload = jobScripts;
 403       })
 404       (mkIf (config.preStop != "") rec {
 405         jobScripts = makeJobScript "${name}-pre-stop" config.preStop;
 406         serviceConfig.ExecStop = jobScripts;
 407       })
 408       (mkIf (config.postStop != "") rec {
 409         jobScripts = makeJobScript "${name}-post-stop" config.postStop;
 410         serviceConfig.ExecStopPost = jobScripts;
 411       })
 412     ];
 413
 414   };
 415
 416   stage2ServiceOptions = {
 417     imports = [
 418       stage2CommonUnitOptions
 419       serviceOptions
 420     ];
 421
 422     options = {
 423       restartIfChanged = mkOption {
 424         type = types.bool;
 425         default = true;
 426         description = lib.mdDoc ''
 427           Whether the service should be restarted during a NixOS
 428           configuration switch if its definition has changed.
 429         '';
 430       };
 431
 432       reloadIfChanged = mkOption {
 433         type = types.bool;
 434         default = false;
 435         description = lib.mdDoc ''
 436           Whether the service should be reloaded during a NixOS
 437           configuration switch if its definition has changed.  If
 438           enabled, the value of {option}`restartIfChanged` is
 439           ignored.
 440
 441           This option should not be used anymore in favor of
 442           {option}`reloadTriggers` which allows more granular
 443           control of when a service is reloaded and when a service
 444           is restarted.
 445         '';
 446       };
 447
 448       stopIfChanged = mkOption {
 449         type = types.bool;
 450         default = true;
 451         description = lib.mdDoc ''
 452           If set, a changed unit is restarted by calling
 453           {command}`systemctl stop` in the old configuration,
 454           then {command}`systemctl start` in the new one.
 455           Otherwise, it is restarted in a single step using
 456           {command}`systemctl restart` in the new configuration.
 457           The latter is less correct because it runs the
 458           `ExecStop` commands from the new
 459           configuration.
 460         '';
 461       };
 462
 463       startAt = mkOption {
 464         type = with types; either str (listOf str);
 465         default = [];
 466         example = "Sun 14:00:00";
 467         description = lib.mdDoc ''
 468           Automatically start this unit at the given date/time, which
 469           must be in the format described in
 470           {manpage}`systemd.time(7)`.  This is equivalent
 471           to adding a corresponding timer unit with
 472           {option}`OnCalendar` set to the value given here.
 473         '';
 474         apply = v: if isList v then v else [ v ];
 475       };
 476     };
 477   };
 478
 479   stage1ServiceOptions = {
 480     imports = [
 481       stage1CommonUnitOptions
 482       serviceOptions
 483     ];
 484   };
 485
 486
 487   socketOptions = {
 488     options = {
 489
 490       listenStreams = mkOption {
 491         default = [];
 492         type = types.listOf types.str;
 493         example = [ "0.0.0.0:993" "/run/my-socket" ];
 494         description = lib.mdDoc ''
 495           For each item in this list, a `ListenStream`
 496           option in the `[Socket]` section will be created.
 497         '';
 498       };
 499
 500       listenDatagrams = mkOption {
 501         default = [];
 502         type = types.listOf types.str;
 503         example = [ "0.0.0.0:993" "/run/my-socket" ];
 504         description = lib.mdDoc ''
 505           For each item in this list, a `ListenDatagram`
 506           option in the `[Socket]` section will be created.
 507         '';
 508       };
 509
 510       socketConfig = mkOption {
 511         default = {};
 512         example = { ListenStream = "/run/my-socket"; };
 513         type = types.attrsOf unitOption;
 514         description = lib.mdDoc ''
 515           Each attribute in this set specifies an option in the
 516           `[Socket]` section of the unit.  See
 517           {manpage}`systemd.socket(5)` for details.
 518         '';
 519       };
 520     };
 521
 522   };
 523
 524   stage2SocketOptions = {
 525     imports = [
 526       stage2CommonUnitOptions
 527       socketOptions
 528     ];
 529   };
 530
 531   stage1SocketOptions = {
 532     imports = [
 533       stage1CommonUnitOptions
 534       socketOptions
 535     ];
 536   };
 537
 538
 539   timerOptions = {
 540     options = {
 541
 542       timerConfig = mkOption {
 543         default = {};
 544         example = { OnCalendar = "Sun 14:00:00"; Unit = "foo.service"; };
 545         type = types.attrsOf unitOption;
 546         description = lib.mdDoc ''
 547           Each attribute in this set specifies an option in the
 548           `[Timer]` section of the unit.  See
 549           {manpage}`systemd.timer(5)` and
 550           {manpage}`systemd.time(7)` for details.
 551         '';
 552       };
 553
 554     };
 555   };
 556
 557   stage2TimerOptions = {
 558     imports = [
 559       stage2CommonUnitOptions
 560       timerOptions
 561     ];
 562   };
 563
 564   stage1TimerOptions = {
 565     imports = [
 566       stage1CommonUnitOptions
 567       timerOptions
 568     ];
 569   };
 570
 571
 572   pathOptions = {
 573     options = {
 574
 575       pathConfig = mkOption {
 576         default = {};
 577         example = { PathChanged = "/some/path"; Unit = "changedpath.service"; };
 578         type = types.attrsOf unitOption;
 579         description = lib.mdDoc ''
 580           Each attribute in this set specifies an option in the
 581           `[Path]` section of the unit.  See
 582           {manpage}`systemd.path(5)` for details.
 583         '';
 584       };
 585
 586     };
 587   };
 588
 589   stage2PathOptions = {
 590     imports = [
 591       stage2CommonUnitOptions
 592       pathOptions
 593     ];
 594   };
 595
 596   stage1PathOptions = {
 597     imports = [
 598       stage1CommonUnitOptions
 599       pathOptions
 600     ];
 601   };
 602
 603
 604   mountOptions = {
 605     options = {
 606
 607       what = mkOption {
 608         example = "/dev/sda1";
 609         type = types.str;
 610         description = lib.mdDoc "Absolute path of device node, file or other resource. (Mandatory)";
 611       };
 612
 613       where = mkOption {
 614         example = "/mnt";
 615         type = types.str;
 616         description = lib.mdDoc ''
 617           Absolute path of a directory of the mount point.
 618           Will be created if it doesn't exist. (Mandatory)
 619         '';
 620       };
 621
 622       type = mkOption {
 623         default = "";
 624         example = "ext4";
 625         type = types.str;
 626         description = lib.mdDoc "File system type.";
 627       };
 628
 629       options = mkOption {
 630         default = "";
 631         example = "noatime";
 632         type = types.commas;
 633         description = lib.mdDoc "Options used to mount the file system.";
 634       };
 635
 636       mountConfig = mkOption {
 637         default = {};
 638         example = { DirectoryMode = "0775"; };
 639         type = types.attrsOf unitOption;
 640         description = lib.mdDoc ''
 641           Each attribute in this set specifies an option in the
 642           `[Mount]` section of the unit.  See
 643           {manpage}`systemd.mount(5)` for details.
 644         '';
 645       };
 646
 647     };
 648   };
 649
 650   stage2MountOptions = {
 651     imports = [
 652       stage2CommonUnitOptions
 653       mountOptions
 654     ];
 655   };
 656
 657   stage1MountOptions = {
 658     imports = [
 659       stage1CommonUnitOptions
 660       mountOptions
 661     ];
 662   };
 663
 664   automountOptions = {
 665     options = {
 666
 667       where = mkOption {
 668         example = "/mnt";
 669         type = types.str;
 670         description = lib.mdDoc ''
 671           Absolute path of a directory of the mount point.
 672           Will be created if it doesn't exist. (Mandatory)
 673         '';
 674       };
 675
 676       automountConfig = mkOption {
 677         default = {};
 678         example = { DirectoryMode = "0775"; };
 679         type = types.attrsOf unitOption;
 680         description = lib.mdDoc ''
 681           Each attribute in this set specifies an option in the
 682           `[Automount]` section of the unit.  See
 683           {manpage}`systemd.automount(5)` for details.
 684         '';
 685       };
 686
 687     };
 688   };
 689
 690   stage2AutomountOptions = {
 691     imports = [
 692       stage2CommonUnitOptions
 693       automountOptions
 694     ];
 695   };
 696
 697   stage1AutomountOptions = {
 698     imports = [
 699       stage1CommonUnitOptions
 700       automountOptions
 701     ];
 702   };
 703
 704   sliceOptions = {
 705     options = {
 706
 707       sliceConfig = mkOption {
 708         default = {};
 709         example = { MemoryMax = "2G"; };
 710         type = types.attrsOf unitOption;
 711         description = lib.mdDoc ''
 712           Each attribute in this set specifies an option in the
 713           `[Slice]` section of the unit.  See
 714           {manpage}`systemd.slice(5)` for details.
 715         '';
 716       };
 717
 718     };
 719   };
 720
 721   stage2SliceOptions = {
 722     imports = [
 723       stage2CommonUnitOptions
 724       sliceOptions
 725     ];
 726   };
 727
 728   stage1SliceOptions = {
 729     imports = [
 730       stage1CommonUnitOptions
 731       sliceOptions
 732     ];
 733   };
 734
 735 }