Modular Services

Additional arguments passed to each module in addition to ones like lib, config, and pkgs, modulesPath.

This option is also available to all submodules. Submodules do not inherit args from their parent module, nor do they provide args to their parent module or sibling submodules. The sole exception to this is the argument name which is provided by parent modules to a submodule and contains the attribute name the submodule is bound to, or a unique generated name if it is not bound to an attribute.

Some arguments are already passed by default, of which the following cannot be changed with this option:

For NixOS, the default value for this option includes at least this argument:

Type: lazy attribute set of raw value

Default:

{ }

Declared by:

Configuration data files for the service

These files are made available to the service and can be updated without restarting the service process, enabling configuration reloading. The service manager implementation determines how these files are exposed to the service (e.g., via a specific directory path). This path is available in the path sub-option for each configData.<name> entry.

This is particularly useful for services that support configuration reloading via signals (e.g., SIGHUP) or which pick up changes automatically, so that no downtime is required in order to reload the service.

Type: lazy attribute set of (submodule)

Default:

{ }

Example:

{
  "server.conf" = {
    text = ''
      port = 8080
      workers = 4
    '';
  };
  "ssl/cert.pem" = {
    source = ./cert.pem;
  };
}

Declared by:

Whether this configuration file should be generated. This option allows specific configuration files to be disabled.

Type: boolean

Default:

true

Declared by:

Name of the configuration file (relative to the service’s configuration directory). Defaults to the attribute name.

Type: string

Declared by:

The actual path where this configuration file will be available. This is determined by the service manager implementation.

On NixOS it is an absolute path. Other service managers may provide a relative path, in order to be unprivileged and/or relocatable.

Type: string (read only)

Declared by:

Path of the source file.

Type: absolute path

Declared by:

Text content of the configuration file.

Type: null or strings concatenated with “\n”

Default:

null

Declared by:

List of maintainers of each module. This option should be defined at most once per module.

The option value is not a list of maintainers, but an attribute set that maps module file names to lists of maintainers.

Type: list of lib.maintainers

Default:

[ ]

Example:

[ lib.maintainers.alice lib.maintainers.bob ]

Declared by:

List of team maintainers of each module. This option should be defined at most once per module.

Type: list of lib.teams

Default:

[ ]

Example:

[ lib.teams.acme lib.teams.haskell ]

Declared by:

Notification protocol that this service supports with the underlying service manager.

Type: submodule

Declared by:

Whether to enable Whether the service supports s6-notify…

Type: boolean

Default:

false

Example:

true

Declared by:

Whether to enable Whether the service supports systemd-notify…

Type: boolean

Default:

false

Example:

true

Declared by:

Command filename and arguments for starting this service. This is a raw command-line that should not contain any shell escaping. If expansion of environmental variables is required then use a shell script or importas from pkgs.execline.

When flags are set, the arguments rendered from them are merged into argv. See flags for how the two are ordered against each other.

Type: list of (string or absolute path convertible to it)

Default:

[ ]

Example:

[ (lib.getExe config.package) "--nobackground" ]

Declared by:

Function mapping flag names to option format specs for lib.cli.toCommandLine.

Receives the flag name and returns { option, sep, explicitBool, formatArg? }.

Type: function that evaluates to a(n) attribute set of anything

Default:

<function>

Example:

name: {
  option = name;
  sep = "=";
  explicitBool = false;
}

Declared by:

Flags to pass to the service process. The key is the flag name (e.g. "--port"), the value is the flag value.

Each name = value pair is rendered via lib.cli.toCommandLine using flagFormat.

To pass the same flag multiple times, use the list form with repeated keys, e.g. [ { "--host" = "a"; } { "--host" = "b"; } ].

The rendered arguments are merged into argv, so argv and flags share a single lib.mkOrder space:

Because 1250 is substituted for flags that carry no ordering property, lib.mkOrder 1000 on a flag is indistinguishable from leaving that flag unadorned. To order a flag around plain argv entries, pick a priority next to 1000, such as 999 or 1001.

Type: attribute list of (null or boolean or signed integer or (string or absolute path convertible to it))

Default:

{ }

Example:

{
  "--port" = "8080";
  "--verbose" = true;
  # ordered ahead of the unadorned flags above
  "--config" = lib.mkOrder 1100 "/etc/foo.conf";
}
# or, for repeated flags:
[
  { "--host" = "localhost"; }
  { "--host" = "0.0.0.0"; }
]

Declared by:

Command used for reloading in the underlying service manager to reload.

Type: null or string

Default:

null

Example:

"${pkgs.coreutils}/bin/kill -HUP $MAINPID"

Declared by:

Configures the reload signal to send to the service manager.

Type: null or string

Default:

null

Example:

"HUP"

Declared by:

A collection of modular services that are configured in one go.

You could consider the sub-service relationship to be an ownership relation. It does not automatically create any other relationship between services (e.g. systemd slices), unless perhaps such a behavior is explicitly defined and enabled in another option.

Type: attribute set of (submodule)

Default:

{ }

Declared by:

Additional arguments passed to each module in addition to ones like lib, config, and pkgs, modulesPath.

This option is also available to all submodules. Submodules do not inherit args from their parent module, nor do they provide args to their parent module or sibling submodules. The sole exception to this is the argument name which is provided by parent modules to a submodule and contains the attribute name the submodule is bound to, or a unique generated name if it is not bound to an attribute.

Some arguments are already passed by default, of which the following cannot be changed with this option:

For NixOS, the default value for this option includes at least this argument:

Type: lazy attribute set of raw value

Default:

{ }

Declared by:

Library functions for working with systemd services.

Available functions:

Type: lazy attribute set of raw value (read only)

Default:

{ }

Declared by:

Main command line for systemd’s ExecReload with systemd’s specifier and environment variable substitution enabled.

This option sets the primary ExecReload entry, and is the way to extend the command line derived from process.reloadCommand.

This option allows you to use systemd specifiers like %n (unit name), %i (instance), %t (runtime directory), and environment variables using ${VAR} syntax in your command line.

By default, it is set to process.reloadCommand. Because process.reloadCommand is already a command line (not an argument list), it is used verbatim so that references like $MAINPID are preserved.

When process.reloadCommand is unset, this option is null and no ExecReload is emitted; a service may then set systemd.service.serviceConfig.ExecReload itself.

To extend process.reloadCommand with systemd specifiers, you can append to the command line:

systemd.mainExecReload =
  config.process.reloadCommand + " --systemd-unit %n";

This pattern allows you to pass the unit name (or other systemd specifiers) as additional arguments.

See systemd.service(5) (section “COMMAND LINES”) for details on variable substitution and systemd.unit(5) (section “SPECIFIERS”) for available specifiers like %n, %i, %t.

Type: null or string

Default:

config.process.reloadCommand

Declared by:

Main command line for systemd’s ExecStart with systemd’s specifier and environment variable substitution enabled.

This option sets the primary ExecStart entry. Additional ExecStart entries can be added via systemd.service.serviceConfig.ExecStart with lib.mkBefore or lib.mkAfter.

This option allows you to use systemd specifiers like %n (unit name), %i (instance), %t (runtime directory), and environment variables using ${VAR} syntax in your command line.

By default, this is set to the escaped version of process.argv to prevent systemd substitution. Set this option explicitly to enable systemd’s substitution features.

To extend process.argv with systemd specifiers, you can append to the escaped arguments:

systemd.mainExecStart =
  config.systemd.lib.escapeSystemdExecArgs config.process.argv + " --systemd-unit %n";

This pattern allows you to pass the unit name (or other systemd specifiers) as additional arguments while keeping the base command from process.argv properly escaped.

See systemd.service(5) (section “COMMAND LINES”) for details on variable substitution and systemd.unit(5) (section “SPECIFIERS”) for available specifiers like %n, %i, %t.

Type: string

Default:

config.systemd.lib.escapeSystemdExecArgs config.process.argv

Declared by:

Alias of systemd.services."".

Type: submodule

Declared by:

This module configures systemd services, with the notable difference that their unit names will be prefixed with the abstract service name.

This option’s value is not suitable for reading, but you can define a module here that interacts with just the unit configuration in the host system configuration.

Note that this option contains deferred modules. This means that the module has not been combined with the system configuration yet, no values can be read from this option. What you can do instead is define a module that reads from the module arguments (such as config) that are available when the module is merged into the system configuration.

Type: lazy attribute set of module

Default:

{ }

Declared by:

Alias of systemd.sockets."".

Type: submodule

Declared by:

Declares systemd socket units. Names will be prefixed by the service name / path.

See systemd.services.

Type: lazy attribute set of module

Default:

{ }

Declared by: