systemd: better document enabled, wantedBy, and requiredBy (#29453)

the systemd.unit(5) discussion of wantedBy and requiredBy is in the
[Install] section, and thus focused on stateful 'systemctl enable'.
so, clarify that in NixOS, wantedBy & requiredBy are still what most
users want, and not to be confused with enabled.

1 files changed, 23 insertions, 4 deletions

diff --git a/nixos/modules/system/boot/systemd-unit-options.nix b/nixos/modules/system/boot/systemd-unit-options.nix
index 9be10a8283e..43a9c28bb69 100644
--- a/nixos/modules/system/boot/systemd-unit-options.nix
+++ b/nixos/modules/system/boot/systemd-unit-options.nix
@@ -35,21 +35,40 @@ in rec {
       description = ''
         If set to false, this unit will be a symlink to
         /dev/null. This is primarily useful to prevent specific
-        template instances (e.g. <literal>serial-getty@ttyS0</literal>)
-        from being started.
+        template instances
+        (e.g. <literal>serial-getty@ttyS0</literal>) from being
+        started. Note that <literal>enable=true</literal> does not
+        make a unit start by default at boot; if you want that, see
+        <literal>wantedBy</literal>.
       '';
     };
 
     requiredBy = mkOption {
       default = [];
       type = types.listOf types.str;
-      description = "Units that require (i.e. depend on and need to go down with) this unit.";
+      description = ''
+        Units that require (i.e. depend on and need to go down with)
+        this unit. The discussion under <literal>wantedBy</literal>
+        applies here as well: inverse <literal>.requires</literal>
+        symlinks are established.
+      '';
     };
 
     wantedBy = mkOption {
       default = [];
       type = types.listOf types.str;
-      description = "Units that want (i.e. depend on) this unit.";
+      description = ''
+        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 <literal>[ "multi-user.target" ]</literal>. That's despite
+        the fact that the systemd.unit(5) manpage says this option
+        goes in the <literal>[Install]</literal> section that controls
+        the behaviour of <literal>systemctl enable</literal>. Since
+        such a process is stateful and thus contrary to the design of
+        NixOS, setting this option instead causes the equivalent
+        inverse <literal>.wants</literal> symlink to be present,
+        establishing the same desired relationship in a stateless way.
+      '';
     };
 
     aliases = mkOption {