1 files changed, 30 insertions, 14 deletions

diff --git a/nixos/lib/systemd-unit-options.nix b/nixos/lib/systemd-unit-options.nix
index 1c56b1b9aa049..44f26572a23ba 100644
--- a/nixos/lib/systemd-unit-options.nix
+++ b/nixos/lib/systemd-unit-options.nix
@@ -48,14 +48,29 @@ in rec {
       '';
     };
 
+    overrideStrategy = mkOption {
+      default = "asDropinIfExists";
+      type = types.enum [ "asDropinIfExists" "asDropin" ];
+      description = lib.mdDoc ''
+        Defines how unit configuration is provided for systemd:
+
+        `asDropinIfExists` creates a unit file when no unit file is provided by the package
+        otherwise a drop-in file name `overrides.conf`.
+
+        `asDropin` creates a drop-in file named `overrides.conf`.
+        Mainly needed to define instances for systemd template units (e.g. `systemd-nspawn@mycontainer.service`).
+
+        See also systemd.unit(1).
+      '';
+    };
+
     requiredBy = mkOption {
       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.
       '';
     };
 
@@ -63,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.
       '';
     };