diff options
author | Janne Heß <janne@hess.ooo> | 2023-08-13 14:35:44 +0200 |
---|---|---|
committer | Janne Heß <janne@hess.ooo> | 2023-08-13 14:40:25 +0200 |
commit | da6c61cc196cd41986a80e1efb3af57ec4d2206b (patch) | |
tree | 5c5903d66591c63023b7d465e10b0303c0d0ad48 /nixos/doc | |
parent | d995da11d830a62862f2bd098504baf74061c261 (diff) |
nixos/manual: Add chapter about instance unit overrides
Diffstat (limited to 'nixos/doc')
-rw-r--r-- | nixos/doc/manual/administration/service-mgmt.chapter.md | 30 |
1 files changed, 30 insertions, 0 deletions
diff --git a/nixos/doc/manual/administration/service-mgmt.chapter.md b/nixos/doc/manual/administration/service-mgmt.chapter.md index 674c737416805..bc9bdbe3708bc 100644 --- a/nixos/doc/manual/administration/service-mgmt.chapter.md +++ b/nixos/doc/manual/administration/service-mgmt.chapter.md @@ -118,3 +118,33 @@ the symlink, and this path is in `/nix/store/.../lib/systemd/user/`. Hence [garbage collection](#sec-nix-gc) will remove that file and you will wind up with a broken symlink in your systemd configuration, which in turn will not make the service / timer start on login. + +## Template units {#sect-nixos-systemd-template-units} + +systemd supports templated units where a base unit can be started multiple +times with a different parameter. The syntax to accomplish this is +`service-name@instance-name.service`. Units get the instance name passed to +them (see `systemd.unit(5)`). NixOS has support for these kinds of units and +for template-specific overrides. A service needs to be defined twice, once +for the base unit and once for the instance. All instances must include +`overrideStrategy = "asDropin"` for the change detection to work. This +example illustrates this: +```nix +{ + systemd.services = { + "base-unit@".serviceConfig = { + ExecStart = "..."; + User = "..."; + }; + "base-unit@instance-a" = { + overrideStrategy = "asDropin"; # needed for templates to work + wantedBy = [ "multi-user.target" ]; # causes NixOS to manage the instance + }; + "base-unit@instance-b" = { + overrideStrategy = "asDropin"; # needed for templates to work + wantedBy = [ "multi-user.target" ]; # causes NixOS to manage the instance + serviceConfig.User = "root"; # also override something for this specific instance + }; + }; +} +``` |