Unverified Commit 951f81c0 authored by Jörg Thalheim's avatar Jörg Thalheim Committed by GitHub
Browse files

nixos/systemd-unit-options: document correct wantedBy default for user units (#199007) 



Until this commit, the documentation suggested `multi-user.target`
as `wantedBy` for all services.
Since `multi-user.target` is not available for user services,
propose a different default for those in the documentation.

Co-authored-by: default avatarNaïm Favier <n@monade.li>
Co-authored-by: default avatarFlorian Warzecha <liketechnik@disroot.org>
parent 17847f29

nixos/lib/systemd-unit-options.nix

+14 −14
Original line number Diff line number Diff line
@@ -68,10 +68,9 @@ in rec { 
      default = [];

      type = types.listOf unitNameType;

      description = lib.mdDoc ''

        Units that require (i.e. depend on and need to go down with)

        this unit. The discussion under `wantedBy`

        applies here as well: inverse `.requires`

        symlinks are established.

        Units that require (i.e. depend on and need to go down with) this unit.

        As discussed in the `wantedBy` option description this also creates

        `.requires` symlinks automatically.

      '';

    };
@@ -79,16 +78,17 @@ in rec { 
      default = [];

      type = types.listOf unitNameType;

      description = lib.mdDoc ''

        Units that want (i.e. depend on) this unit. The standard way

        to make a unit start by default at boot is to set this option

        to `[ "multi-user.target" ]`. That's despite

        the fact that the systemd.unit(5) manpage says this option

        goes in the `[Install]` section that controls

        the behaviour of `systemctl enable`. Since

        such a process is stateful and thus contrary to the design of

        NixOS, setting this option instead causes the equivalent

        inverse `.wants` symlink to be present,

        establishing the same desired relationship in a stateless way.

        Units that want (i.e. depend on) this unit. The default method for

        starting a unit by default at boot time is to set this option to

        '["multi-user.target"]' for system services. Likewise for user units

        (`systemd.user.<name>.*`) set it to `["default.target"]` to make a unit

        start by default when the user `<name>` logs on.



        This option creates a `.wants` symlink in the given target that exists

        statelessly without the need for running `systemctl enable`.

        The in systemd.unit(5) manpage described `[Install]` section however is

        not supported because it is a stateful process that does not fit well

        into the NixOS design.

      '';

    };