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: Naïm Favier <n@monade.li>
Co-authored-by: Florian Warzecha <liketechnik@disroot.org>

Changed files
+14 -14
nixos
+14 -14
nixos/lib/systemd-unit-options.nix
···
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.
'';
};
···
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.
'';
};