kaffa/obsidian
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: move nixos-manual to reference/ + graphifyignore

Browse Source
This commit is contained in:
heimdall
2026-04-16 13:43:03 +09:00
parent b303243511
commit 3f9727f3ac
146 changed files with 4 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
reference/nixos-manual/development/activation-script.section.md Normal file
View File

@@ -0,0 +1,74 @@
# Activation script {#sec-activation-script}
The activation script is a bash script called to activate the new
configuration which resides in a NixOS system in `$out/activate`. Since its
contents depend on your system configuration, the contents may differ.
This chapter explains how the script works in general and some common NixOS
snippets. Please be aware that the script is executed on every boot and system
switch, so tasks that can be performed in other places should be performed
there (for example letting a directory of a service be created by systemd using
mechanisms like `StateDirectory`, `CacheDirectory`, ... or if that's not
possible using `preStart` of the service).
Activation scripts are defined as snippets using
[](#opt-system.activationScripts). They can either be a simple multiline string
or an attribute set that can depend on other snippets. The builder for the
activation script will take these dependencies into account and order the
snippets accordingly. As a simple example:
```nix
{
system.activationScripts.my-activation-script = {
deps = [ "etc" ];
# supportsDryActivation = true;
text = ''
echo "Hallo i bims"
'';
};
}
```
This example creates an activation script snippet that is run after the `etc`
snippet. The special variable `supportsDryActivation` can be set so the snippet
is also run when `nixos-rebuild dry-activate` is run. To differentiate between
real and dry activation, the `$NIXOS_ACTION` environment variable can be
read which is set to `dry-activate` when a dry activation is done.
An activation script can write to special files instructing
`switch-to-configuration` to restart/reload units. The script will take these
requests into account and will incorporate the unit configuration as described
above. This means that the activation script will "fake" a modified unit file
and `switch-to-configuration` will act accordingly. By doing so, configuration
like [systemd.services.\<name\>.restartIfChanged](#opt-systemd.services) is
respected. Since the activation script is run **after** services are already
stopped, [systemd.services.\<name\>.stopIfChanged](#opt-systemd.services)
cannot be taken into account anymore and the unit is always restarted instead
of being stopped and started afterwards.
The files that can be written to are `/run/nixos/activation-restart-list` and
`/run/nixos/activation-reload-list` with their respective counterparts for
dry activation being `/run/nixos/dry-activation-restart-list` and
`/run/nixos/dry-activation-reload-list`. Those files can contain
newline-separated lists of unit names where duplicates are being ignored. These
files are not create automatically and activation scripts must take the
possibility into account that they have to create them first.
## NixOS snippets {#sec-activation-script-nixos-snippets}
There are some snippets NixOS enables by default because disabling them would
most likely break your system. This section lists a few of them and what they
do:
- `binsh` creates `/bin/sh` which points to the runtime shell
- `etc` sets up the contents of `/etc`, this includes systemd units and
excludes `/etc/passwd`, `/etc/group`, and `/etc/shadow` (which are managed by
the `users` snippet)
- `hostname` sets the system's hostname in the kernel (not in `/etc`)
- `modprobe` sets the path to the `modprobe` binary for module auto-loading
- `nix` prepares the nix store and adds a default initial channel
- `specialfs` is responsible for mounting filesystems like `/proc` and `sys`
- `users` creates and removes users and groups by managing `/etc/passwd`,
`/etc/group` and `/etc/shadow`. This also creates home directories
- `usrbinenv` creates `/usr/bin/env`
- `var` creates some directories in `/var` that are not service-specific
- `wrappers` creates setuid wrappers like `sudo`

45
reference/nixos-manual/development/assertions.section.md Normal file
View File

@@ -0,0 +1,45 @@
# Warnings and Assertions {#sec-assertions}
When configuration problems are detectable in a module, it is a good idea to write an assertion or warning. Doing so provides clear feedback to the user and prevents errors after the build.
Although Nix has the `abort` and `builtins.trace` [functions](https://nixos.org/nix/manual/#ssec-builtins) to perform such tasks, they are not ideally suited for NixOS modules. Instead of these functions, you can declare your warnings and assertions using the NixOS module system.
## Warnings {#sec-assertions-warnings}
This is an example of using `warnings`.
```nix
{ config, lib, ... }:
{
config = lib.mkIf config.services.foo.enable {
warnings =
if config.services.foo.bar then
[
''
You have enabled the bar feature of the foo service.
This is known to cause some specific problems in certain situations.
''
]
else
[ ];
};
}
```
## Assertions {#sec-assertions-assetions}
This example, extracted from the [`syslogd` module](https://github.com/NixOS/nixpkgs/blob/release-17.09/nixos/modules/services/logging/syslogd.nix) shows how to use `assertions`. Since there can only be one active syslog daemon at a time, an assertion is useful to prevent such a broken system from being built.
```nix
{ config, lib, ... }:
{
config = lib.mkIf config.services.syslogd.enable {
assertions = [
{
assertion = !config.services.rsyslogd.enable;
message = "rsyslogd conflicts with syslogd";
}
];
};
}
```

38
reference/nixos-manual/development/bootspec.chapter.md Normal file
View File

@@ -0,0 +1,38 @@
# Bootspec {#sec-bootspec}
Bootspec is a feature introduced in [RFC-0125](https://github.com/NixOS/rfcs/pull/125) in order to standardize bootloader support and advanced boot workflows such as SecureBoot and potentially more.
The reference implementation can be found [here](https://github.com/NixOS/nixpkgs/pull/172237).
The creation of bootspec documents is enabled by default.
## Schema {#sec-bootspec-schema}
The bootspec schema is versioned and validated against [a CUE schema file](https://cuelang.org/) which should considered as the source of truth for your applications.
You will find the current version [here](../../../modules/system/activation/bootspec.cue).
## Extensions mechanism {#sec-bootspec-extensions}
Bootspec cannot account for all usecases.
For this purpose, Bootspec offers a generic extension facility [`boot.bootspec.extensions`](options.html#opt-boot.bootspec.extensions) which can be used to inject any data needed for your usecases.
An example for SecureBoot is to get the Nix store path to `/etc/os-release` in order to bake it into a unified kernel image:
```nix
{ config, lib, ... }:
{
boot.bootspec.extensions = {
"org.secureboot.osRelease" = config.environment.etc."os-release".source;
};
}
```
To reduce incompatibility and prevent names from clashing between applications, it is **highly recommended** to use a unique namespace for your extensions.
## External bootloaders {#sec-bootspec-external-bootloaders}
It is possible to enable your own bootloader through [`boot.loader.external.installHook`](options.html#opt-boot.loader.external.installHook) which can wrap an existing bootloader.
Currently, there is no good story to compose existing bootloaders to enrich their features, e.g. SecureBoot, etc.
It will be necessary to reimplement or reuse existing parts.

74
reference/nixos-manual/development/building-parts.chapter.md Normal file
View File

@@ -0,0 +1,74 @@
# Building Specific Parts of NixOS {#sec-building-parts}
With the command `nix-build`, you can build specific parts of your NixOS
configuration. This is done as follows:
```ShellSession
$ cd /path/to/nixpkgs/nixos
$ nix-build -A config.option
```
where `option` is a NixOS option with type "derivation" (i.e. something
that can be built). Attributes of interest include:
`system.build.toplevel`
: The top-level option that builds the entire NixOS system. Everything
else in your configuration is indirectly pulled in by this option.
This is what `nixos-rebuild` builds and what `/run/current-system`
points to afterwards.
A shortcut to build this is:
```ShellSession
$ nix-build -A system
```
`system.build.manual.manualHTML`
: The NixOS manual.
`system.build.etc`
: A tree of symlinks that form the static parts of `/etc`.
`system.build.initialRamdisk` , `system.build.kernel`
: The initial ramdisk and kernel of the system. This allows a quick
way to test whether the kernel and the initial ramdisk boot
correctly, by using QEMU's `-kernel` and `-initrd` options:
```ShellSession
$ nix-build -A config.system.build.initialRamdisk -o initrd
$ nix-build -A config.system.build.kernel -o kernel
$ qemu-system-x86_64 -kernel ./kernel/bzImage -initrd ./initrd/initrd -hda /dev/null
```
`system.build.nixos-rebuild` , `system.build.nixos-install` , `system.build.nixos-generate-config`
: These build the corresponding NixOS commands.
`systemd.units.unit-name.unit`
: This builds the unit with the specified name. Note that since unit
names contain dots (e.g. `httpd.service`), you need to put them
between quotes, like this:
```ShellSession
$ nix-build -A 'config.systemd.units."httpd.service".unit'
```
You can also test individual units, without rebuilding the whole
system, by putting them in `/run/systemd/system`:
```ShellSession
$ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \
/run/systemd/system/tmp-httpd.service
# systemctl daemon-reload
# systemctl start tmp-httpd.service
```
Note that the unit must not have the same name as any unit in
`/etc/systemd/system` since those take precedence over
`/run/systemd/system`. That's why the unit is installed as
`tmp-httpd.service` here.

45
reference/nixos-manual/development/developing-the-test-driver.chapter.md Normal file
View File

@@ -0,0 +1,45 @@
# Developing the NixOS Test Driver {#chap-developing-the-test-driver}
The NixOS test framework is a project of its own.
It consists of roughly the following components:
- `nixos/lib/test-driver`: The Python framework that sets up the test and runs the [`testScript`](#test-opt-testScript)
- `nixos/lib/testing`: The Nix code responsible for the wiring, written using the (NixOS) Module System.
These components are exposed publicly through:
- `nixos/lib/default.nix`: The public interface that exposes the `nixos/lib/testing` entrypoint.
- `flake.nix`: Exposes the `lib.nixos`, including the public test interface.
Beyond the test driver itself, its integration into NixOS and Nixpkgs is important.
- `pkgs/top-level/all-packages.nix`: Defines the `nixosTests` attribute, used
by the package `tests` attributes and OfBorg.
- `nixos/release.nix`: Defines the `tests` attribute built by Hydra, independently, but analogous to `nixosTests`
- `nixos/release-combined.nix`: Defines which tests are channel blockers.
Finally, we have legacy entrypoints that users should move away from, but are cared for on a best effort basis.
These include `pkgs.nixosTest`, `testing-python.nix` and `make-test-python.nix`.
## Testing changes to the test framework {#sec-test-the-test-framework}
We currently have limited unit tests for the framework itself. You may run these with `nix-build -A nixosTests.nixos-test-driver`.
When making significant changes to the test framework, we run the tests on Hydra, to avoid disrupting the larger NixOS project.
For this, we use the `python-test-refactoring` branch in the `NixOS/nixpkgs` repository, and its [corresponding Hydra jobset](https://hydra.nixos.org/jobset/nixos/python-test-refactoring).
This branch is used as a pointer, and not as a feature branch.
1. Rebase the PR onto a recent, good evaluation of `nixos-unstable`
2. Create a baseline evaluation by force-pushing this revision of `nixos-unstable` to `python-test-refactoring`.
3. Note the evaluation number (we'll call it `<previous>`)
4. Push the PR to `python-test-refactoring` and evaluate the PR on Hydra
5. Create a comparison URL by navigating to the latest build of the PR and adding to the URL `?compare=<previous>`. This is not necessary for the evaluation that comes right after the baseline.
Review the removed tests and newly failed tests using the constructed URL; otherwise you will accidentally compare iterations of the PR instead of changes to the PR base.
As we currently have some flaky tests, newly failing tests are expected, but should be reviewed to make sure that
- The number of failures did not increase significantly.
- All failures that do occur can reasonably be assumed to fail for a different reason than the changes.

16
reference/nixos-manual/development/development.md Normal file
View File

@@ -0,0 +1,16 @@
# Development {#ch-development}
This chapter describes how you can modify and extend NixOS.
```{=include=} chapters
sources.chapter.md
writing-modules.chapter.md
building-parts.chapter.md
bootspec.chapter.md
what-happens-during-a-system-switch.chapter.md
writing-documentation.chapter.md
nixos-tests.chapter.md
developing-the-test-driver.chapter.md
testing-installer.chapter.md
modular-services.md
```

36
reference/nixos-manual/development/etc-overlay.section.md Normal file
View File

@@ -0,0 +1,36 @@
# `/etc` via overlay filesystem {#sec-etc-overlay}
::: {.note}
This is experimental and requires a kernel version >= 6.6 because it uses
new overlay features and relies on the new mount API.
:::
Instead of using a custom perl script to activate `/etc`, you activate it via an
overlay filesystem:
```nix
{ system.etc.overlay.enable = true; }
```
Using an overlay has two benefits:
1. it removes a dependency on perl
2. it makes activation faster (up to a few seconds)
By default, the `/etc` overlay is mounted writable (i.e. there is a writable
upper layer). However, you can also mount `/etc` immutably (i.e. read-only) by
setting:
```nix
{ system.etc.overlay.mutable = false; }
```
The overlay is atomically replaced during system switch. However, files that
have been modified will NOT be overwritten. This is the biggest change compared
to the perl-based system.
If you manually make changes to `/etc` on your system and then switch to a new
configuration where `system.etc.overlay.mutable = false;`, you will not be able
to see the previously made changes in `/etc` anymore. However the changes are
not completely gone, they are still in the upperdir of the previous overlay in
`/.rw-etc/upper`.

79
reference/nixos-manual/development/freeform-modules.section.md Normal file
View File

@@ -0,0 +1,79 @@
# Freeform modules {#sec-freeform-modules}
Freeform modules allow you to define values for option paths that have
not been declared explicitly. This can be used to add attribute-specific
types to what would otherwise have to be `attrsOf` options in order to
accept all attribute names.
This feature can be enabled by using the attribute `freeformType` to
define a freeform type. By doing this, all assignments without an
associated option will be merged using the freeform type and combined
into the resulting `config` set. Since this feature nullifies name
checking for entire option trees, it is only recommended for use in
submodules.
::: {#ex-freeform-module .example}
### Freeform submodule
The following shows a submodule assigning a freeform type that allows
arbitrary attributes with `str` values below `settings`, but also
declares an option for the `settings.port` attribute to have it
type-checked and assign a default value. See
[Example: Declaring a type-checked `settings` attribute](#ex-settings-typed-attrs)
for a more complete example.
```nix
{ lib, config, ... }:
{
options.settings = lib.mkOption {
type = lib.types.submodule {
freeformType = with lib.types; attrsOf str;
# We want this attribute to be checked for the correct type
options.port = lib.mkOption {
type = lib.types.port;
# Declaring the option also allows defining a default value
default = 8080;
};
};
};
}
```
And the following shows what such a module then allows
```nix
{
# Not a declared option, but the freeform type allows this
settings.logLevel = "debug";
# Not allowed because the freeform type only allows strings
# settings.enable = true;
# Allowed because there is a port option declared
settings.port = 80;
# Not allowed because the port option doesn't allow strings
# settings.port = "443";
}
```
:::
::: {.note}
Freeform attributes cannot depend on other attributes of the same set
without infinite recursion:
```nix
{
# This throws infinite recursion encountered
settings.logLevel = lib.mkIf (config.settings.port == 80) "debug";
}
```
To prevent this, declare options for all attributes that need to depend
on others. For above example this means to declare `logLevel` to be an
option.
:::

23
reference/nixos-manual/development/importing-modules.section.md Normal file
View File

@@ -0,0 +1,23 @@
# Importing Modules {#sec-importing-modules}
Sometimes NixOS modules need to be used in configuration but exist
outside of Nixpkgs. These modules can be imported:
```nix
{
config,
lib,
pkgs,
...
}:
{
imports = [
# Use a locally-available module definition in
# ./example-module/default.nix
./example-module
];
services.exampleModule.enable = true;
}
```

6
reference/nixos-manual/development/linking-nixos-tests-to-packages.section.md Normal file
View File

@@ -0,0 +1,6 @@
# Linking NixOS tests to packages {#sec-linking-nixos-tests-to-packages}
You can link NixOS module tests to the packages that they exercised,
so that the tests can be run automatically during code review when the package gets changed.
This is
[described in the nixpkgs manual](https://nixos.org/manual/nixpkgs/stable/#ssec-nixos-tests-linking).

73
reference/nixos-manual/development/meta-attributes.section.md Normal file
View File

@@ -0,0 +1,73 @@
# Meta Attributes {#sec-meta-attributes}
Like Nix packages, NixOS modules can declare meta-attributes to provide
extra information. Module meta attributes are defined in the `meta.nix`
special module.
`meta` is a top level attribute like `options` and `config`. Available
meta-attributes are `maintainers`, `doc`, and `buildDocsInSandbox`.
Each of the meta-attributes must be defined at most once per module
file.
```nix
{
config,
lib,
pkgs,
...
}:
{
options = {
# ...
};
config = {
# ...
};
meta = {
maintainers = with lib.maintainers; [ ];
doc = ./default.md;
buildDocsInSandbox = true;
};
}
```
- `maintainers` contains a list of the module maintainers.
- `doc` points to a valid [Nixpkgs-flavored CommonMark](
https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup
) file containing the module
documentation. Its contents is automatically added to
[](#ch-configuration). Changes to a module documentation have to
be checked to not break building the NixOS manual:
```ShellSession
$ nix-build nixos/release.nix -A manual.x86_64-linux
```
- `buildDocsInSandbox` indicates whether the option documentation for the
module can be built in a derivation sandbox. This option is currently only
honored for modules shipped by nixpkgs. User modules and modules taken from
`extraModules` are always built outside of the sandbox, as has
been the case in previous releases.
Building NixOS option documentation in a sandbox allows caching of the built
documentation, which greatly decreases the amount of time needed to evaluate
a system configuration that has NixOS documentation enabled. The sandbox also
restricts which attributes may be referenced by documentation attributes
(such as option descriptions) to the `options` and `lib` module arguments and
the `pkgs.formats` attribute of the `pkgs` argument, `config` and the rest of
`pkgs` are disallowed and will cause doc build failures when used. This
restriction is necessary because we cannot reproduce the full nixpkgs
instantiation with configuration and overlays from a system configuration
inside the sandbox. The `options` argument only includes options of modules
that are also built inside the sandbox, referencing an option of a module
that isn't built in the sandbox is also forbidden.
The default is `true` and should usually not be changed; set it to `false`
only if the module requires access to `pkgs` in its documentation (e.g.
because it loads information from a linked package to build an option type)
or if its documentation depends on other modules that also aren't sandboxed
(e.g. by using types defined in the other module).

111
reference/nixos-manual/development/modular-services.md Normal file
View File

@@ -0,0 +1,111 @@
# Modular Services {#modular-services}
Status: in development. This functionality is new in NixOS 25.11, and significant changes should be expected. We'd love to hear your feedback in <https://github.com/NixOS/nixpkgs/pull/372170>
Traditionally, NixOS services were defined using sets of options *in* modules, not *as* modules. This made them non-modular, resulting in problems with composability, reuse, and portability.
A configuration management framework is an application of `evalModules` with the `class` and `specialArgs` input attribute set to particular values.
NixOS is such a configuration management framework, and so are [Home Manager](https://github.com/nix-community/home-manager) and [`nix-darwin`](https://github.com/lnl7/nix-darwin).
The service management component of a configuration management framework is the set of module options that connects Nix expressions with the underlying service (or process) manager.
For NixOS this is the module wrapping [`systemd`](https://systemd.io/), on `nix-darwin` this is the module wrapping [`launchd`](https://en.wikipedia.org/wiki/Launchd).
A *modular service* is a [module] that defines values for a core set of options declared in the service management component of a configuration management framework, including which program to run.
Since it's a module, it can be composed with other modules via `imports` to extend its functionality.
NixOS provides two options into which such modules can be plugged:
- `system.services.<name>`
- an option for user services (TBD)
Crucially, these options have the type [`attrsOf`] [`submodule`].
The name of the service is the attribute name corresponding to `attrsOf`.
<!-- ^ This is how composition is *always* provided, instead of a difficult thing (but this is reference docs, not a changelog) -->
The `submodule` is pre-loaded with two modules:
- a generic module that is intended to be portable
- a module with systemd-specific options, whose values or defaults derive from the generic module's option values.
So note that the default value of `system.services.<name>` is not a complete service. It requires that the user provide a value, and this is typically done by importing a module. For example:
<!-- Not using typical example syntax, because reading this is *not* optional, and should it should not be folded closed. -->
```nix
{
system.services.my-service-instance = {
imports = [ pkgs.some-application.services.some-service-module ];
foo.settings = {
# ...
};
};
}
```
## Portability {#modular-service-portability}
It is possible to write service modules that are portable. This is done by either avoiding the `systemd` option tree, or by defining process-manager-specific definitions in an optional way:
```nix
{
config,
options,
lib,
...
}:
{
_class = "service";
config = {
process.argv = [ (lib.getExe config.foo.program) ];
}
// lib.optionalAttrs (options ? systemd) {
# ... systemd-specific definitions ...
};
}
```
This way, the module can be loaded into a configuration manager that does not use systemd, and the `systemd` definitions will be ignored.
Similarly, other configuration managers can declare their own options for services to customize.
## Composition and Ownership {#modular-service-composition}
Compared to traditional services, modular services are inherently more composable, by virtue of being modules and receiving a user-provided name when imported.
However, composition can not end there, because services need to be able to interact with each other.
This can be achieved in two ways:
1. Users can link services together by providing the necessary NixOS configuration.
2. Services can be compositions of other services.
These aren't mutually exclusive. In fact, it is a good practice when developing services to first write them as individual services, and then compose them into a higher-level composition. Each of these services is a valid modular service, including their composition.
## Migration {#modular-service-migration}
Many services could be migrated to the modular service system, but even when the modular service system is mature, it is not necessary to migrate all services.
For instance, many system-wide services are a mandatory part of a desktop system, and it doesn't make sense to have multiple instances of them.
Moving their logic into separate Nix files may still be beneficial for the efficient evaluation of configurations that don't use those services, but that is a rather minor benefit, unless modular services potentially become the standard way to define services.
<!-- TODO example of a single-instance service -->
## Writing and Reviewing a Modular Service {#modular-service-review}
A typical service module consists of the following:
For more details, refer to the contributor documentation in [`nixos/README-modular-services.md`](https://github.com/NixOS/nixpkgs/blob/master/nixos/README-modular-services.md).
## Portable Service Options {#modular-service-options-portable}
```{=include=} options
id-prefix: service-opt-
list-id: service-options
source: @PORTABLE_SERVICE_OPTIONS@
```
## Systemd-specific Service Options {#modular-service-options-systemd}
```{=include=} options
id-prefix: systemd-service-opt-
list-id: systemd-service-options
source: @SYSTEMD_SERVICE_OPTIONS@
```
[module]: https://nixos.org/manual/nixpkgs/stable/index.html#module-system
<!-- TODO: more anchors -->
[`attrsOf`]: #sec-option-types-composed
[`submodule`]: #sec-option-types-submodule

14
reference/nixos-manual/development/nixos-tests.chapter.md Normal file
View File

@@ -0,0 +1,14 @@
# NixOS Tests {#sec-nixos-tests}
When you add some feature to NixOS, you should write a test for it.
NixOS tests are kept in the directory `nixos/tests`, and are executed
(using Nix) by a testing framework that automatically starts one or more
virtual machines containing the NixOS system(s) required for the test.
```{=include=} sections
writing-nixos-tests.section.md
running-nixos-tests.section.md
running-nixos-tests-interactively.section.md
linking-nixos-tests-to-packages.section.md
testing-hardware-features.section.md
```

22
reference/nixos-manual/development/non-switchable-systems.section.md Normal file
View File

@@ -0,0 +1,22 @@
# Non Switchable Systems {#sec-non-switchable-system}
In certain systems, most notably image based appliances, updates are handled
outside the system. This means that you do not need to rebuild your
configuration on the system itself anymore.
If you want to build such a system, you can use the `image-based-appliance`
profile:
```nix
{ modulesPath, ... }:
{
imports = [ "${modulesPath}/profiles/image-based-appliance.nix" ];
}
```
The most notable deviation of this profile from a standard NixOS configuration
is that after building it, you cannot switch *to* the configuration anymore.
The profile sets `config.system.switch.enable = false;`, which excludes
`switch-to-configuration`, the central script called by `nixos-rebuild`, from
your system. Removing this script makes the image lighter and slightly more
secure.

269
reference/nixos-manual/development/option-declarations.section.md Normal file
View File

@@ -0,0 +1,269 @@
# Option Declarations {#sec-option-declarations}
An option declaration specifies the name, type and description of a
NixOS configuration option. It is invalid to define an option that
hasn't been declared in any module. An option declaration generally
looks like this:
```nix
{
options = {
name = mkOption {
type = type specification;
default = default value;
example = example value;
description = "Description for use in the NixOS manual.";
};
};
}
```
The attribute names within the `name` attribute path must be camel
cased in general but should, as an exception, match the [ package
attribute name](https://nixos.org/nixpkgs/manual/#sec-package-naming)
when referencing a Nixpkgs package. For example, the option
`services.nix-serve.bindAddress` references the `nix-serve` Nixpkgs
package.
The function `mkOption` accepts the following arguments.
`type`
: The type of the option (see [](#sec-option-types)). This
argument is mandatory for nixpkgs modules. Setting this is highly
recommended for the sake of documentation and type checking. In case it is
not set, a fallback type with unspecified behavior is used.
`default`
: The default value used if no value is defined by any module. A
default is not required; but if a default is not given, then users
of the module will have to define the value of the option, otherwise
an error will be thrown.
`defaultText`
: A textual representation of the default value to be rendered verbatim in
the manual. Useful if the default value is a complex expression or depends
on other values or packages.
Use `lib.literalExpression` for a Nix expression, `lib.literalMD` for
a plain English description in [Nixpkgs-flavored Markdown](
https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format.
`example`
: An example value that will be shown in the NixOS manual.
You can use `lib.literalExpression` and `lib.literalMD` in the same way
as in `defaultText`.
`description`
: A textual description of the option in [Nixpkgs-flavored Markdown](
https://nixos.org/nixpkgs/manual/#sec-contributing-markup) format that will be
included in the NixOS manual.
## Utility functions for common option patterns {#sec-option-declarations-util}
### `mkEnableOption` {#sec-option-declarations-util-mkEnableOption}
Creates an Option attribute set for a boolean value option i.e an
option to be toggled on or off.
This function takes a single string argument, the name of the thing to be toggled.
The option's description is "Whether to enable \<name\>.".
For example:
::: {#ex-options-declarations-util-mkEnableOption-magic .example}
### `mkEnableOption` usage
```nix
lib.mkEnableOption "magic"
# is like
lib.mkOption
{
type = lib.types.bool;
default = false;
example = true;
description = "Whether to enable magic.";
}
```
:::
### `mkPackageOption` {#sec-option-declarations-util-mkPackageOption}
Usage:
```nix
mkPackageOption pkgs "name" {
default = [
"path"
"in"
"pkgs"
];
example = "literal example";
}
```
Creates an Option attribute set for an option that specifies the package a module should use for some purpose.
**Note**: You should make package options for your modules, where applicable. While one can always overwrite a specific package throughout nixpkgs by using [nixpkgs overlays](https://nixos.org/manual/nixpkgs/stable/#chap-overlays), they slow down nixpkgs evaluation significantly and are harder to debug when issues arise.
The package is specified in the third argument under `default` as a list of strings
representing its attribute path in nixpkgs (or another package set).
Because of this, you need to pass nixpkgs itself (or a subset) as the first argument.
The second argument may be either a string or a list of strings.
It provides the display name of the package in the description of the generated option
(using only the last element if the passed value is a list)
and serves as the fallback value for the `default` argument.
To include extra information in the description, pass `extraDescription` to
append arbitrary text to the generated description.
You can also pass an `example` value, either a literal string or an attribute path.
The default argument can be omitted if the provided name is
an attribute of pkgs (if name is a string) or a
valid attribute path in pkgs (if name is a list).
If you wish to explicitly provide no default, pass `null` as `default`.
[]{#ex-options-declarations-util-mkPackageOption}
Examples:
::: {#ex-options-declarations-util-mkPackageOption-hello .example}
### Simple `mkPackageOption` usage
```nix
lib.mkPackageOption pkgs "hello" { }
# is like
lib.mkOption
{
type = lib.types.package;
default = pkgs.hello;
defaultText = lib.literalExpression "pkgs.hello";
description = "The hello package to use.";
}
```
:::
::: {#ex-options-declarations-util-mkPackageOption-ghc .example}
### `mkPackageOption` with explicit default and example
```nix
lib.mkPackageOption pkgs "GHC"
{
default = [ "ghc" ];
example = "pkgs.haskellPackages.ghc.withPackages (hkgs: [ hkgs.primes ])";
}
# is like
lib.mkOption
{
type = lib.types.package;
default = pkgs.ghc;
defaultText = lib.literalExpression "pkgs.ghc";
example = lib.literalExpression "pkgs.haskellPackages.ghc.withPackages (hkgs: [ hkgs.primes ])";
description = "The GHC package to use.";
}
```
:::
::: {#ex-options-declarations-util-mkPackageOption-extraDescription .example}
### `mkPackageOption` with additional description text
```nix
mkPackageOption pkgs [ "python312Packages" "torch" ]
{
extraDescription = "This is an example and doesn't actually do anything.";
}
# is like
lib.mkOption
{
type = lib.types.package;
default = pkgs.python312Packages.torch;
defaultText = lib.literalExpression "pkgs.python312Packages.torch";
description = "The pytorch package to use. This is an example and doesn't actually do anything.";
}
```
:::
## Extensible Option Types {#sec-option-declarations-eot}
Extensible option types is a feature that allows to extend certain types
declaration through multiple module files. This feature only work with a
restricted set of types, namely `enum` and `submodules` and any composed
forms of them.
Extensible option types can be used for `enum` options that affects
multiple modules, or as an alternative to related `enable` options.
As an example, we will take the case of display managers. There is a
central display manager module for generic display manager options and a
module file per display manager backend (sddm, gdm ...).
There are two approaches we could take with this module structure:
- Configuring the display managers independently by adding an enable
option to every display manager module backend. (NixOS)
- Configuring the display managers in the central module by adding
an option to select which display manager backend to use.
Both approaches have problems.
Making backends independent can quickly become hard to manage. For
display managers, there can only be one enabled at a time, but the
type system cannot enforce this restriction as there is no relation
between each backend's `enable` option. As a result, this restriction
has to be done explicitly by adding assertions in each display manager
backend module.
On the other hand, managing the display manager backends in the
central module will require changing the central module option every
time a new backend is added or removed.
By using extensible option types, it is possible to create a placeholder
option in the central module
([Example: Extensible type placeholder in the service module](#ex-option-declaration-eot-service)),
and to extend it in each backend module
([Example: Extending `services.xserver.displayManager.enable` in the `gdm` module](#ex-option-declaration-eot-backend-gdm),
[Example: Extending `services.xserver.displayManager.enable` in the `sddm` module](#ex-option-declaration-eot-backend-sddm)).
As a result, `displayManager.enable` option values can be added without
changing the main service module file and the type system automatically
enforces that there can only be a single display manager enabled.
::: {#ex-option-declaration-eot-service .example}
### Extensible type placeholder in the service module
```nix
{
services.xserver.displayManager.enable = mkOption {
description = "Display manager to use";
type = with types; nullOr (enum [ ]);
};
}
```
:::
::: {#ex-option-declaration-eot-backend-gdm .example}
### Extending `services.xserver.displayManager.enable` in the `gdm` module
```nix
{
services.xserver.displayManager.enable = mkOption { type = with types; nullOr (enum [ "gdm" ]); };
}
```
:::
::: {#ex-option-declaration-eot-backend-sddm .example}
### Extending `services.xserver.displayManager.enable` in the `sddm` module
```nix
{
services.xserver.displayManager.enable = mkOption { type = with types; nullOr (enum [ "sddm" ]); };
}
```
:::
The placeholder declaration is a standard `mkOption` declaration, but it
is important that extensible option declarations only use the `type`
argument.
Extensible option types work with any of the composed variants of `enum`
such as `with types; nullOr (enum [ "foo" "bar" ])` or `with types;
listOf (enum [ "foo" "bar" ])`.

204
reference/nixos-manual/development/option-def.section.md Normal file
View File

@@ -0,0 +1,204 @@
# Option Definitions {#sec-option-definitions}
Option definitions are generally straight-forward bindings of values to
option names, like
```nix
{
config = {
services.httpd.enable = true;
};
}
```
However, sometimes you need to wrap an option definition or set of
option definitions in a *property* to achieve certain effects:
## Delaying Conditionals {#sec-option-definitions-delaying-conditionals}
If a set of option definitions is conditional on the value of another
option, you may need to use `mkIf`. Consider, for instance:
```nix
{
config =
if config.services.httpd.enable then
{
environment.systemPackages = [
# ...
];
# ...
}
else
{ };
}
```
This definition will cause Nix to fail with an "infinite recursion"
error. Why? Because the value of `config.services.httpd.enable` depends
on the value being constructed here. After all, you could also write the
clearly circular and contradictory:
```nix
{
config =
if config.services.httpd.enable then
{
services.httpd.enable = false;
}
else
{
services.httpd.enable = true;
};
}
```
The solution is to write:
```nix
{
config = mkIf config.services.httpd.enable {
environment.systemPackages = [
# ...
];
# ...
};
}
```
The special function `mkIf` causes the evaluation of the conditional to
be "pushed down" into the individual definitions, as if you had written:
```nix
{
config = {
environment.systemPackages =
if config.services.httpd.enable then
[
# ...
]
else
[ ];
# ...
};
}
```
## Setting Priorities {#sec-option-definitions-setting-priorities}
A module can override the definitions of an option in other modules by
setting an *override priority*. All option definitions that do not have the lowest
priority value are discarded. By default, option definitions have
priority 100 and option defaults have priority 1500.
You can specify an explicit priority by using `mkOverride`, e.g.
```nix
{ services.openssh.enable = mkOverride 10 false; }
```
This definition causes all other definitions with priorities above 10 to
be discarded. The function `mkForce` is equal to `mkOverride 50`, and
`mkDefault` is equal to `mkOverride 1000`.
## Ordering Definitions {#sec-option-definitions-ordering}
It is also possible to influence the order in which the definitions for an option are
merged by setting an *order priority* with `mkOrder`. The default order priority is 1000.
The functions `mkBefore` and `mkAfter` are equal to `mkOrder 500` and `mkOrder 1500`, respectively.
As an example,
```nix
{ hardware.firmware = mkBefore [ myFirmware ]; }
```
This definition ensures that `myFirmware` comes before other unordered
definitions in the final list value of `hardware.firmware`.
Note that this is different from [override priorities](#sec-option-definitions-setting-priorities):
setting an order does not affect whether the definition is included or not.
## Merging Configurations {#sec-option-definitions-merging}
In conjunction with `mkIf`, it is sometimes useful for a module to
return multiple sets of option definitions, to be merged together as if
they were declared in separate modules. This can be done using
`mkMerge`:
```nix
{
config = mkMerge [
# Unconditional stuff.
{
environment.systemPackages = [
# ...
];
}
# Conditional stuff.
(mkIf config.services.bla.enable {
environment.systemPackages = [
# ...
];
})
];
}
```
## Free-floating definitions {#sec-option-definitions-definitions}
:::{.note}
The module system internally transforms module syntax into definitions. This always happens internally.
:::
It is possible to create first class definitions which are not transformed _again_ into definitions by the module system.
Usually the file location of a definition is implicit and equal to the file it came from.
However, when manipulating definitions, it may be useful for them to be completely self-contained (or "free-floating").
A free-floating definition is created with `mkDefinition { file = ...; value = ...; }`.
Preserving the file location creates better error messages, for example when copying definitions from one option to another.
Other properties like `mkOverride` `mkMerge` `mkAfter` can be used in the `value` attribute but not on the entire definition.
This is what would work
```nix
mkDefinition {
value = mkForce 42;
file = "somefile.nix";
}
```
While this would NOT work.
```nix
mkForce (mkDefinition {
value = 42;
file = "somefile.nix";
})
```
The following shows an example configuration that yields an error with the custom position information:
```nix
{
_file = "file.nix";
options.foo = mkOption { default = 13; };
config.foo = lib.mkDefinition {
file = "custom place";
# mkOptionDefault creates a conflict with the option foo's `default = 1` on purpose
# So we see the error message below contains the conflicting values and different positions
value = lib.mkOptionDefault 42;
};
}
```
evaluating the module yields the following error:
```
error: Cannot merge definitions of `foo'. Definition values:
- In `file.nix': 13
- In `custom place': 42
```
To set the file location for all definitions in a module, you may add the `_file` module syntax attribute, which has a similar effect to using `mkDefinition` on all definitions in the module, without the hassle.

795
reference/nixos-manual/development/option-types.section.md Normal file
View File

@@ -0,0 +1,795 @@
# Options Types {#sec-option-types}
Option types are a way to put constraints on the values a module option
can take. Types are also responsible of how values are merged in case of
multiple value definitions.
## Basic types {#sec-option-types-basic}
Basic types are the simplest available types in the module system. Basic
types include multiple string types that mainly differ in how definition
merging is handled.
`types.bool`
: A boolean, its values can be `true` or `false`.
All definitions must have the same value, after priorities. An error is thrown in case of a conflict.
`types.boolByOr`
: A boolean, its values can be `true` or `false`.
The result is `true` if _any_ of multiple definitions is `true`.
In other words, definitions are merged with the logical _OR_ operator.
`types.path`
: A filesystem path that starts with a slash. Even if derivations can be
considered as paths, the more specific `types.package` should be preferred.
`types.pathInStore`
: A path that is contained in the Nix store. This can be a top-level store
path like `pkgs.hello` or a descendant like `"${pkgs.hello}/bin/hello"`.
`types.externalPath`
: A path that is not contained in the Nix store. Typical use cases are:
secrets, password or any other external file.
::: {.warning}
This type only validates that the path is not *currently* in the Nix store.
It does NOT prevent the value from being copied to the store later when:
- Referenced in a derivation
- Used in certain path operations (e.g., `${path}` interpolation)
- Passed to functions that copy to the store
Users must still be careful about how they reference these paths.
:::
`types.pathWith` { *`inStore`* ? `null`, *`absolute`* ? `null` }
: A filesystem path. Either a string or something that can be coerced
to a string.
**Parameters**
`inStore` (`Boolean` or `null`, default `null`)
: Whether the path must be in the store (`true`), must not be in the store
(`false`), or it doesn't matter (`null`)
`absolute` (`Boolean` or `null`, default `null`)
: Whether the path must be absolute (`true`), must not be absolute
(`false`), or it doesn't matter (`null`)
**Behavior**
- `pathWith { inStore = true; }` is equivalent to `pathInStore`
- `pathWith { absolute = true; }` is equivalent to `path`
- `pathWith { inStore = false; absolute = true; }` requires an absolute
path that is not in the store. Useful for password files that shouldn't be
leaked into the store.
`types.package`
: A top-level store path. This can be an attribute set pointing
to a store path, like a derivation or a flake input.
`types.enum` *`l`*
: One element of the list *`l`*, e.g. `types.enum [ "left" "right" ]`.
Multiple definitions cannot be merged.
If you want to pair these values with more information, possibly of
distinct types, consider using a [sum type](#sec-option-types-sums).
`types.anything`
: A type that accepts any value and recursively merges attribute sets
together. This type is recommended when the option type is unknown.
::: {#ex-types-anything .example}
### `types.anything`
Two definitions of this type like
```nix
{
str = lib.mkDefault "foo";
pkg.hello = pkgs.hello;
fun.fun = x: x + 1;
}
```
```nix
{
str = lib.mkIf true "bar";
pkg.gcc = pkgs.gcc;
fun.fun = lib.mkForce (x: x + 2);
}
```
will get merged to
```nix
{
str = "bar";
pkg.gcc = pkgs.gcc;
pkg.hello = pkgs.hello;
fun.fun = x: x + 2;
}
```
:::
`types.raw`
: A type which doesn't do any checking, merging or nested evaluation. It
accepts a single arbitrary value that is not recursed into, making it
useful for values coming from outside the module system, such as package
sets or arbitrary data. Options of this type are still evaluated according
to priorities and conditionals, so `mkForce`, `mkIf` and co. still work on
the option value itself, but not for any value nested within it. This type
should only be used when checking, merging and nested evaluation are not
desirable.
`types.optionType`
: The type of an option's type. Its merging operation ensures that nested
options have the correct file location annotated, and that if possible,
multiple option definitions are correctly merged together. The main use
case is as the type of the `_module.freeformType` option.
`types.attrs`
: A free-form attribute set.
::: {.warning}
This type will be deprecated in the future because it doesn't
recurse into attribute sets, silently drops earlier attribute
definitions, and doesn't discharge `lib.mkDefault`, `lib.mkIf`
and co. For allowing arbitrary attribute sets, prefer
`types.attrsOf types.anything` instead which doesn't have these
problems.
:::
`types.pkgs`
: A type for the top level Nixpkgs package set.
### Numeric types {#sec-option-types-numeric}
`types.int`
: A signed integer.
`types.ints.{s8, s16, s32}`
: Signed integers with a fixed length (8, 16 or 32 bits). They go from
−2^n/2 to
2^n/2−1 respectively (e.g. `−128` to
`127` for 8 bits).
`types.ints.unsigned`
: An unsigned integer (that is >= 0).
`types.ints.{u8, u16, u32}`
: Unsigned integers with a fixed length (8, 16 or 32 bits). They go
from 0 to 2^n−1 respectively (e.g. `0`
to `255` for 8 bits).
`types.ints.between` *`lowest highest`*
: An integer between *`lowest`* and *`highest`* (both inclusive).
`types.ints.positive`
: A positive integer (that is > 0).
`types.port`
: A port number. This type is an alias to
`types.ints.u16`.
`types.float`
: A floating point number.
::: {.warning}
Converting a floating point number to a string with `toString` or `toJSON`
may result in [precision loss](https://github.com/NixOS/nix/issues/5733).
:::
`types.number`
: Either a signed integer or a floating point number. No implicit conversion
is done between the two types, and multiple equal definitions will only be
merged if they have the same type.
`types.numbers.between` *`lowest highest`*
: An integer or floating point number between *`lowest`* and *`highest`* (both inclusive).
`types.numbers.nonnegative`
: A nonnegative integer or floating point number (that is >= 0).
`types.numbers.positive`
: A positive integer or floating point number (that is > 0).
### String types {#sec-option-types-string}
`types.str`
: A string. Multiple definitions cannot be merged.
`types.separatedString` *`sep`*
: A string. Multiple definitions are concatenated with *`sep`*, e.g.
`types.separatedString "|"`.
`types.lines`
: A string. Multiple definitions are concatenated with a new line
`"\n"`.
`types.commas`
: A string. Multiple definitions are concatenated with a comma `","`.
`types.envVar`
: A string. Multiple definitions are concatenated with a colon `":"`.
`types.strMatching`
: A string matching a specific regular expression. Multiple
definitions cannot be merged. The regular expression is processed
using `builtins.match`.
### Specialised types {#sec-option-types-specialised}
`types.luaInline`
: A string wrapped using `lib.mkLuaInline`. Allows embedding lua expressions
inline within generated lua. Multiple definitions cannot be merged.
## Submodule types {#sec-option-types-submodule}
Submodules are detailed in [Submodule](#section-option-types-submodule).
`types.submodule` *`o`*
: A set of sub options *`o`*. *`o`* can be an attribute set, a function
returning an attribute set, or a path to a file containing such a
value. Submodules are used in composed types to create modular
options. This is equivalent to
`types.submoduleWith { modules = toList o; shorthandOnlyDefinesConfig = true; }`.
`types.submoduleWith` { *`modules`*, *`specialArgs`* ? {}, *`shorthandOnlyDefinesConfig`* ? false }
: Like `types.submodule`, but more flexible and with better defaults.
It has parameters
- *`modules`* A list of modules to use by default for this
submodule type. This gets combined with all option definitions
to build the final list of modules that will be included.
::: {.note}
Only options defined with this argument are included in rendered
documentation.
:::
- *`specialArgs`* An attribute set of extra arguments to be passed
to the module functions. The option `_module.args` should be
used instead for most arguments since it allows overriding.
*`specialArgs`* should only be used for arguments that can't go
through the module fixed-point, because of infinite recursion or
other problems. An example is overriding the `lib` argument,
because `lib` itself is used to define `_module.args`, which
makes using `_module.args` to define it impossible.
- *`shorthandOnlyDefinesConfig`* Whether definitions of this type
should default to the `config` section of a module (see
[Example: Structure of NixOS Modules](#ex-module-syntax))
if it is an attribute set. Enabling this only has a benefit
when the submodule defines an option named `config` or `options`.
In such a case it would allow the option to be set with
`the-submodule.config = "value"` instead of requiring
`the-submodule.config.config = "value"`. This is because
only when modules *don't* set the `config` or `options`
keys, all keys are interpreted as option definitions in the
`config` section. Enabling this option implicitly puts all
attributes in the `config` section.
With this option enabled, defining a non-`config` section
requires using a function:
`the-submodule = { ... }: { options = { ... }; }`.
`types.deferredModule`
: Whereas `submodule` represents an option tree, `deferredModule` represents
a module value, such as a module file or a configuration.
It can be set multiple times.
Module authors can use its value in `imports`, in `submoduleWith`'s `modules`
or in `evalModules`' `modules` parameter, among other places.
Note that `imports` must be evaluated before the module fixpoint. Because
of this, deferred modules can only be imported into "other" fixpoints, such
as submodules.
One use case for this type is the type of a "default" module that allow the
user to affect all submodules in an `attrsOf submodule` at once. This is
more convenient and discoverable than expecting the module user to
type-merge with the `attrsOf submodule` option.
## Union types {#sec-option-types-unions}
A union of types is a type such that a value is valid when it is valid for at least one of those types.
If some values are instances of more than one of the types, it is not possible to distinguish which type they are meant to be instances of. If that's needed, consider using a [sum type](#sec-option-types-sums).
<!-- SYNC WITH oneOf BELOW -->
`types.either` *`t1 t2`*
: Type *`t1`* or type *`t2`*, e.g. `with types; either int str`.
Multiple definitions cannot be merged.
::: {.warning}
`either` and `oneOf` eagerly decide the active type based on the passed types' shallow check method. For composite types like `attrsOf` and `submodule`, which both match all attribute set definitions, the first type argument will be chosen for the returned option value, and this therefore also decides how nested values are checked and merged. For example, `either (attrsOf int) (submodule {...})` will always use `attrsOf int` for any attribute set value, even if it was intended as a submodule. This behavior is a trade-off that keeps the implementation simple and the evaluation order predictable, avoiding unexpected strictness problems such as infinite recursions. When proper type discrimination is needed, consider using a [sum type](#sec-option-types-sums) like `attrTag` instead.
:::
<!-- SYNC WITH either ABOVE -->
`types.oneOf` \[ *`t1 t2`* ... \]
: Type *`t1`* or type *`t2`* and so forth, e.g.
`with types; oneOf [ int str bool ]`. Multiple definitions cannot be
merged.
::: {.warning}
`either` and `oneOf` eagerly decide the active type based on the passed types' shallow check method. For composite types like `attrsOf` and `submodule`, which both match all attribute set definitions, the first matching type in the list will be chosen for the returned option value, and this therefore also decides how nested values are checked and merged. For example, `oneOf [ (attrsOf int) (submodule {...}) ]` will always use `attrsOf int` for any attribute set value, even if it was intended as a submodule. This behavior is a trade-off that keeps the implementation simple and the evaluation order predictable, avoiding unexpected strictness problems such as infinite recursions. When proper type discrimination is needed, consider using a [sum type](#sec-option-types-sums) like `attrTag` instead.
:::
`types.nullOr` *`t`*
: `null` or type *`t`*. Multiple definitions are merged according to
type *`t`*.
This is mostly equivalent to `either (enum [ null ]) t`, but `nullOr` provides a `null` fallback for attribute values with `mkIf false` definitions in `lazyAttrsOf (nullOr t)`, whereas `either` would throw an error when the attribute is accessed.
## Sum types {#sec-option-types-sums}
A sum type can be thought of, conceptually, as a *`types.enum`* where each valid item is paired with at least a type, through some value syntax.
Nix does not have a built-in syntax for this pairing of a label and a type or value, so sum types may be represented in multiple ways.
If the you're interested in can be distinguished without a label, you may simplify your value syntax with a [union type](#sec-option-types-unions) instead.
`types.attrTag` *`{ attr1 = option1; attr2 = option2; ... }`*
: An attribute set containing one attribute, whose name must be picked from
the attribute set (`attr1`, etc) and whose value consists of definitions that are valid for the corresponding option (`option1`, etc).
This type appears in the documentation as _attribute-tagged union_.
Example:
```nix
{ lib, ... }:
let inherit (lib) type mkOption;
in {
options.toyRouter.rules = mkOption {
description = ''
Rules for a fictional packet routing service.
'';
type = types.attrsOf (
types.attrTag {
bounce = mkOption {
description = "Send back a packet explaining why it wasn't forwarded.";
type = types.submodule {
options.errorMessage = mkOption { … };
};
};
forward = mkOption {
description = "Forward the packet.";
type = types.submodule {
options.destination = mkOption { … };
};
};
drop = types.mkOption {
description = "Drop the packet without sending anything back.";
type = types.submodule {};
};
});
};
config.toyRouter.rules = {
http = {
bounce = {
errorMessage = "Unencrypted HTTP is banned. You must always use https://.";
};
};
ssh = { drop = {}; };
};
}
```
## Composed types {#sec-option-types-composed}
Composed types are types that take a type as parameter. `listOf
int` and `either int str` are examples of composed types.
`types.listOf` *`t`*
: A list of *`t`* type, e.g. `types.listOf
int`. Multiple definitions are merged with list concatenation.
`types.attrsOf` *`t`*
: An attribute set of where all the values are of *`t`* type. Multiple
definitions result in the joined attribute set.
::: {.note}
This type is *strict* in its values, which in turn means attributes
cannot depend on other attributes. See `
types.lazyAttrsOf` for a lazy version.
:::
`types.lazyAttrsOf` *`t`*
: An attribute set of where all the values are of *`t`* type. Multiple
definitions result in the joined attribute set. This is the lazy
version of `types.attrsOf
`, allowing attributes to depend on each other.
::: {.warning}
This version does not fully support conditional definitions! With an
option `foo` of this type and a definition
`foo.attr = lib.mkIf false 10`, evaluating `foo ? attr` will return
`true` even though it should be false. Accessing the value will then
throw an error. For types *`t`* that have an `emptyValue` defined,
that value will be returned instead of throwing an error. So if the
type of `foo.attr` was `lazyAttrsOf (nullOr int)`, `null` would be
returned instead for the same `mkIf false` definition.
:::
`types.attrsWith` { *`elemType`*, *`lazy`* ? false, *`placeholder`* ? "name" }
: An attribute set of where all the values are of *`elemType`* type.
**Parameters**
`elemType` (Required)
: Specifies the type of the values contained in the attribute set.
`lazy`
: Determines whether the attribute set is lazily evaluated. See: `types.lazyAttrsOf`
`placeholder` (`String`, default: `name` )
: Placeholder string in documentation for the attribute names.
The default value `name` results in the placeholder `<name>`
**Behavior**
- `attrsWith { elemType = t; }` is equivalent to `attrsOf t`
- `attrsWith { lazy = true; elemType = t; }` is equivalent to `lazyAttrsOf t`
- `attrsWith { placeholder = "id"; elemType = t; }`
Displays the option as `foo.<id>` in the manual.
`types.uniq` *`t`*
: Ensures that type *`t`* cannot be merged. It is used to ensure option
definitions are provided only once.
`types.unique` `{ message = m }` *`t`*
: Ensures that type *`t`* cannot be merged. Prints the message *`m`*, after
the line `The option <option path> is defined multiple times.` and before
a list of definition locations.
`types.coercedTo` *`from f to`*
: Type *`to`* or type *`from`* which will be coerced to type *`to`* using
function *`f`* which takes an argument of type *`from`* and return a
value of type *`to`*. Can be used to preserve backwards compatibility
of an option if its type was changed.
## Submodule {#section-option-types-submodule}
`submodule` is a very powerful type that defines a set of sub-options
that are handled like a separate module.
It takes a parameter *`o`*, that should be a set, or a function returning
a set with an `options` key defining the sub-options. Submodule option
definitions are type-checked accordingly to the `options` declarations.
Of course, you can nest submodule option definitions for even higher
modularity.
The option set can be defined directly
([Example: Directly defined submodule](#ex-submodule-direct)) or as reference
([Example: Submodule defined as a reference](#ex-submodule-reference)).
Note that even if your submodule’s options all have a default value,
you will still need to provide a default value (e.g. an empty attribute set)
if you want to allow users to leave it undefined.
::: {#ex-submodule-direct .example}
### Directly defined submodule
```nix
{
options.mod = mkOption {
description = "submodule example";
type =
with types;
submodule {
options = {
foo = mkOption { type = int; };
bar = mkOption { type = str; };
};
};
};
}
```
:::
::: {#ex-submodule-reference .example}
### Submodule defined as a reference
```nix
let
modOptions = {
options = {
foo = mkOption { type = int; };
bar = mkOption { type = int; };
};
};
in
{
options.mod = mkOption {
description = "submodule example";
type = with types; submodule modOptions;
};
}
```
:::
The `submodule` type is especially interesting when used with composed
types like `attrsOf` or `listOf`. When composed with `listOf`
([Example: Declaration of a list of submodules](#ex-submodule-listof-declaration)), `submodule` allows
multiple definitions of the submodule option set
([Example: Definition of a list of submodules](#ex-submodule-listof-definition)).
::: {#ex-submodule-listof-declaration .example}
### Declaration of a list of submodules
```nix
{
options.mod = mkOption {
description = "submodule example";
type =
with types;
listOf (submodule {
options = {
foo = mkOption { type = int; };
bar = mkOption { type = str; };
};
});
};
}
```
:::
::: {#ex-submodule-listof-definition .example}
### Definition of a list of submodules
```nix
{
config.mod = [
{
foo = 1;
bar = "one";
}
{
foo = 2;
bar = "two";
}
];
}
```
:::
When composed with `attrsOf`
([Example: Declaration of attribute sets of submodules](#ex-submodule-attrsof-declaration)), `submodule` allows
multiple named definitions of the submodule option set
([Example: Definition of attribute sets of submodules](#ex-submodule-attrsof-definition)).
::: {#ex-submodule-attrsof-declaration .example}
### Declaration of attribute sets of submodules
```nix
{
options.mod = mkOption {
description = "submodule example";
type =
with types;
attrsOf (submodule {
options = {
foo = mkOption { type = int; };
bar = mkOption { type = str; };
};
});
};
}
```
:::
::: {#ex-submodule-attrsof-definition .example}
### Definition of attribute sets of submodules
```nix
{
config.mod.one = {
foo = 1;
bar = "one";
};
config.mod.two = {
foo = 2;
bar = "two";
};
}
```
:::
## Extending types {#sec-option-types-extending}
Types are mainly characterized by their `check` and `merge` functions.
`check`
: The function to type check the value. Takes a value as parameter and
return a boolean. It is possible to extend a type check with the
`addCheck` function ([Example: Adding a type check](#ex-extending-type-check-1)),
or to fully override the check function
([Example: Overriding a type check](#ex-extending-type-check-2)).
::: {#ex-extending-type-check-1 .example}
### Adding a type check
```nix
{
byte = mkOption {
description = "An integer between 0 and 255.";
type = types.addCheck types.int (x: x >= 0 && x <= 255);
};
}
```
:::
::: {#ex-extending-type-check-2 .example}
### Overriding a type check
```nix
{
nixThings = mkOption {
description = "words that start with 'nix'";
type = types.str // {
check = (x: lib.hasPrefix "nix" x);
};
};
}
```
:::
`merge`
: Function to merge the options values when multiple values are set.
The function takes two parameters, `loc` the option path as a list
of strings, and `defs` the list of defined values as a list. It is
possible to override a type merge function for custom needs.
## Custom types {#sec-option-types-custom}
Custom types can be created with the `mkOptionType` function. As type
creation includes some more complex topics such as submodule handling,
it is recommended to get familiar with `types.nix` code before creating
a new type.
The only required parameter is `name`.
`name`
: A string representation of the type function name.
`description`
: Description of the type used in documentation. Give information of
the type and any of its arguments.
`check`
: A function to type check the definition value. Takes the definition
value as a parameter and returns a boolean indicating the type check
result, `true` for success and `false` for failure.
`merge`
: A function to merge multiple definitions values. Takes two
parameters:
*`loc`*
: The option path as a list of strings, e.g. `["boot" "loader
"grub" "enable"]`.
*`defs`*
: The list of sets of defined `value` and `file` where the value
was defined, e.g. `[ {
file = "/foo.nix"; value = 1; } { file = "/bar.nix"; value = 2 }
]`. The `merge` function should return the merged value
or throw an error in case the values are impossible or not meant
to be merged.
`getSubOptions`
: For composed types that can take a submodule as type parameter, this
function generate sub-options documentation. It takes the current
option prefix as a list and return the set of sub-options. Usually
defined in a recursive manner by adding a term to the prefix, e.g.
`prefix:
elemType.getSubOptions (prefix ++
["prefix"])` where *`"prefix"`* is the newly added prefix.
`getSubModules`
: For composed types that can take a submodule as type parameter, this
function should return the type parameters submodules. If the type
parameter is called `elemType`, the function should just recursively
look into submodules by returning `elemType.getSubModules;`.
`substSubModules`
: For composed types that can take a submodule as type parameter, this
function can be used to substitute the parameter of a submodule
type. It takes a module as parameter and return the type with the
submodule options substituted. It is usually defined as a type
function call with a recursive call to `substSubModules`, e.g for a
type `composedType` that take an `elemtype` type parameter, this
function should be defined as `m:
composedType (elemType.substSubModules m)`.
`typeMerge`
: A function to merge multiple type declarations. Takes the type to
merge `functor` as parameter. A `null` return value means that type
cannot be merged.
*`f`*
: The type to merge `functor`.
Note: There is a generic `defaultTypeMerge` that work with most of
value and composed types.
`functor`
: An attribute set representing the type. It is used for type
operations and has the following keys:
`type`
: The type function.
`wrapped`
: Holds the type parameter for composed types.
`payload`
: Holds the value parameter for value types. The types that have a
`payload` are the `enum`, `separatedString` and `submodule`
types.
`binOp`
: A binary operation that can merge the payloads of two same
types. Defined as a function that take two payloads as
parameters and return the payloads merged.

80
reference/nixos-manual/development/replace-modules.section.md Normal file
View File

@@ -0,0 +1,80 @@
# Replace Modules {#sec-replace-modules}
Modules that are imported can also be disabled. The option declarations,
config implementation and the imports of a disabled module will be
ignored, allowing another to take its place. This can be used to
import a set of modules from another channel while keeping the rest of
the system on a stable release.
`disabledModules` is a top level attribute like `imports`, `options` and
`config`. It contains a list of modules that will be disabled. This can
either be:
- the full path to the module,
- or a string with the filename relative to the modules path (eg. \<nixpkgs/nixos/modules> for nixos),
- or an attribute set containing a specific `key` attribute.
The latter allows some modules to be disabled, despite them being distributed
via attributes instead of file paths. The `key` should be globally unique, so
it is recommended to include a file path in it, or rely on a framework to do it
for you.
This example will replace the existing postgresql module with the
version defined in the nixos-unstable channel while keeping the rest of
the modules and packages from the original nixos channel. This only
overrides the module definition, this won't use postgresql from
nixos-unstable unless explicitly configured to do so.
```nix
{
config,
lib,
pkgs,
...
}:
{
disabledModules = [ "services/databases/postgresql.nix" ];
imports = [
# Use postgresql service from nixos-unstable channel.
# sudo nix-channel --add https://channels.nixos.org/nixos-unstable nixos-unstable
<nixos-unstable/nixos/modules/services/databases/postgresql.nix>
];
services.postgresql.enable = true;
}
```
This example shows how to define a custom module as a replacement for an
existing module. Importing this module will disable the original module
without having to know its implementation details.
```nix
{
config,
lib,
pkgs,
...
}:
let
inherit (lib) mkIf mkOption types;
cfg = config.programs.man;
in
{
disabledModules = [ "services/programs/man.nix" ];
options = {
programs.man.enable = mkOption {
type = types.bool;
default = true;
description = "Whether to enable manual pages.";
};
};
config = mkIf cfg.enabled {
warnings = [ "disabled manpages for production deployments." ];
};
}
```

171
reference/nixos-manual/development/running-nixos-tests-interactively.section.md Normal file
View File

@@ -0,0 +1,171 @@
# Running Tests interactively {#sec-running-nixos-tests-interactively}
The test itself can be run interactively. This is particularly useful
when developing or debugging a test:
```ShellSession
$ nix-build . -A nixosTests.login.driverInteractive
$ ./result/bin/nixos-test-driver
[...]
>>>
```
::: {.note}
By executing the test driver in this way,
the VMs executed may gain network & Internet access via their backdoor control interface,
typically recognized as `eth0`.
:::
You can then take any Python statement, e.g.
```py
>>> start_all()
>>> test_script()
>>> machine.succeed("touch /tmp/foo")
>>> print(machine.succeed("pwd")) # Show stdout of command
```
The function `test_script` executes the entire test script and drops you
back into the test driver command line upon its completion. This allows
you to inspect the state of the VMs after the test (e.g. to debug the
test script).
## Shell access in interactive mode {#sec-nixos-test-shell-access}
The function `<yourmachine>.shell_interact()` grants access to a shell running
inside a virtual machine. To use it, replace `<yourmachine>` with the name of a
virtual machine defined in the test, for example: `machine.shell_interact()`.
Keep in mind that this shell may not display everything correctly as it is
running within an interactive Python REPL, and logging output from the virtual
machine may overwrite input and output from the guest shell:
```py
>>> machine.shell_interact()
machine: Terminal is ready (there is no initial prompt):
$ hostname
machine
```
As an alternative, you can proxy the guest shell to a local TCP server by first
starting a TCP server in a terminal using the command:
```ShellSession
$ socat 'READLINE,PROMPT=$ ' tcp-listen:4444,reuseaddr
```
In the terminal where the test driver is running, connect to this server by
using:
```py
>>> machine.shell_interact("tcp:127.0.0.1:4444")
```
Once the connection is established, you can enter commands in the socat terminal
where socat is running.
## SSH Access for test machines {#sec-nixos-test-ssh-access}
An SSH-based backdoor to log into machines can be enabled with
```nix
{
name = "…";
nodes.machines = {
# …
};
interactive.sshBackdoor.enable = true;
}
```
::: {.warning}
Make sure to only enable the backdoor for interactive tests
(i.e. by using `interactive.sshBackdoor.enable`)! This is the only
supported configuration.
Running a test in a sandbox with this will fail because `/dev/vhost-vsock` isn't available
in the sandbox.
:::
This creates a [vsock socket](https://man7.org/linux/man-pages/man7/vsock.7.html)
for each VM to log in with SSH. This configures root login with an empty password.
When the VMs get started interactively with the test-driver, it's possible to
connect to `machine` with
```
$ ssh vsock/3 -o User=root
```
The socket numbers correspond to the node number of the test VM, but start
at three instead of one because that's the lowest possible
vsock number. The exact SSH commands are also printed out when starting
`nixos-test-driver`.
On non-NixOS systems you'll probably need to enable
the SSH config from {manpage}`systemd-ssh-proxy(1)` yourself.
If starting VM fails with an error like
```
qemu-system-x86_64: -device vhost-vsock-pci,guest-cid=3: vhost-vsock: unable to set guest cid: Address already in use
```
it means that the vsock numbers for the VMs are already in use. This can happen
if another interactive test with SSH backdoor enabled is running on the machine.
In that case, you need to assign another range of vsock numbers. You can pick another
offset with
```nix
{
sshBackdoor = {
enable = true;
vsockOffset = 23542;
};
}
```
## Port forwarding to NixOS test VMs {#sec-nixos-test-port-forwarding}
If your test has only a single VM, you may use e.g.
```ShellSession
$ QEMU_NET_OPTS="hostfwd=tcp:127.0.0.1:2222-:22" ./result/bin/nixos-test-driver
```
to port-forward a port in the VM (here `22`) to the host machine (here port `2222`).
This naturally does not work when multiple machines are involved,
since a single port on the host cannot forward to multiple VMs.
If the test defines multiple machines, you may opt to _temporarily_ set
`virtualisation.forwardPorts` in the test definition for debugging.
Such port forwardings connect via the VM's virtual network interface.
Thus they cannot connect to ports that are only bound to the VM's
loopback interface (`127.0.0.1`), and the VM's NixOS firewall
must be configured to allow these connections.
## Reuse VM state {#sec-nixos-test-reuse-vm-state}
You can re-use the VM states coming from a previous run by setting the
`--keep-vm-state` flag.
```ShellSession
$ ./result/bin/nixos-test-driver --keep-vm-state
```
The machine state is stored in the `$TMPDIR/vm-state-machinename`
directory.
## Interactive-only test configuration {#sec-nixos-test-interactive-configuration}
The `.driverInteractive` attribute combines the regular test configuration with
definitions from the [`interactive` submodule](#test-opt-interactive). This gives you
a more usable, graphical, but slightly different configuration.
You can add your own interactive-only test configuration by adding extra
configuration to the [`interactive` submodule](#test-opt-interactive).
To interactively run only the regular configuration, build the `<test>.driver` attribute
instead, and call it with the flag `result/bin/nixos-test-driver --interactive`.

30
reference/nixos-manual/development/running-nixos-tests.section.md Normal file
View File

@@ -0,0 +1,30 @@
# Running Tests {#sec-running-nixos-tests}
You can run tests using `nix-build`. For example, to run the test
[`login.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix),
you do:
```ShellSession
$ cd /my/git/clone/of/nixpkgs
$ nix-build -A nixosTests.login
```
After building/downloading all required dependencies, this will perform
a build that starts a QEMU/KVM virtual machine containing a NixOS
system. The virtual machine mounts the Nix store of the host; this makes
VM creation very fast, as no disk image needs to be created. Afterwards,
you can view a log of the test:
```ShellSession
$ nix-store --read-log result
```
## System Requirements {#sec-running-nixos-tests-requirements}
NixOS tests require virtualization support.
This means that the machine must have `kvm` in its [system features](https://nixos.org/manual/nix/stable/command-ref/conf-file.html?highlight=system-features#conf-system-features) list, or `apple-virt` in case of macOS.
These features are autodetected locally, but `apple-virt` is only autodetected since Nix 2.19.0.
Features of **remote builders** must additionally be configured manually on the client, e.g. on NixOS with [`nix.buildMachines.*.supportedFeatures`](https://search.nixos.org/options?show=nix.buildMachines.*.supportedFeatures&sort=alpha_asc&query=nix.buildMachines) or through general [Nix configuration](https://nixos.org/manual/nix/stable/advanced-topics/distributed-builds).
If you run the tests on a **macOS** machine, you also need a "remote" builder for Linux; possibly a VM. [nix-darwin](https://daiderd.com/nix-darwin/) users may enable [`nix.linux-builder.enable`](https://daiderd.com/nix-darwin/manual/index.html#opt-nix.linux-builder.enable) to launch such a VM.

629
reference/nixos-manual/development/settings-options.section.md Normal file
View File

@@ -0,0 +1,629 @@
# Options for Program Settings {#sec-settings-options}
Many programs have configuration files where program-specific settings
can be declared. File formats can be separated into two categories:
- Nix-representable ones: These can trivially be mapped to a subset of
Nix syntax. E.g. JSON is an example, since its values like
`{"foo":{"bar":10}}` can be mapped directly to Nix:
`{ foo = { bar = 10; }; }`. Other examples are INI, YAML and TOML.
The following section explains the convention for these settings.
- Non-nix-representable ones: These can't be trivially mapped to a
subset of Nix syntax. Most generic programming languages are in this
group, e.g. bash, since the statement `if true; then echo hi; fi`
doesn't have a trivial representation in Nix.
Currently there are no fixed conventions for these, but it is common
to have a `configFile` option for setting the configuration file
path directly. The default value of `configFile` can be an
auto-generated file, with convenient options for controlling the
contents. For example an option of type `attrsOf str` can be used
for representing environment variables which generates a section
like `export FOO="foo"`. Often it can also be useful to also include
an `extraConfig` option of type `lines` to allow arbitrary text
after the autogenerated part of the file.
## Nix-representable Formats (JSON, YAML, TOML, INI, ...) {#sec-settings-nix-representable}
By convention, formats like this are handled with a generic `settings`
option, representing the full program configuration as a Nix value. The
type of this option should represent the format. The most common formats
have a predefined type and string generator already declared under
`pkgs.formats`:
`pkgs.formats.javaProperties` { *`comment`* ? `"Generated with Nix"` }
: A function taking an attribute set with values
`comment`
: A string to put at the start of the
file in a comment. It can have multiple
lines.
It returns the `type`: `attrsOf str` and a function
`generate` to build a Java `.properties` file, taking
care of the correct escaping, etc.
`pkgs.formats.hocon` { *`generator`* ? `<derivation>`, *`validator`* ? `<derivation>`, *`doCheck`* ? true }
: A function taking an attribute set with values
`generator`
: A derivation used for converting the JSON output
from the nix settings into HOCON. This might be
useful if your HOCON variant is slightly different
from the java-based one, or for testing purposes.
`validator`
: A derivation used for verifying that the HOCON
output is correct and parsable. This might be
useful if your HOCON variant is slightly different
from the java-based one, or for testing purposes.
`doCheck`
: Whether to enable/disable the validator check.
It returns an attrset with a `type`, `generate` function,
and a `lib` attset, as specified [below](#pkgs-formats-result).
Some of the lib functions will be best understood if you have
read the reference specification. You can find this
specification here:
<https://github.com/lightbend/config/blob/main/HOCON.md>
Inside of `lib`, you will find these functions
`mkInclude`
: This is used together with a specially named
attribute `includes`, to include other HOCON
sources into the document.
The function has a shorthand variant where it
is up to the HOCON parser to figure out what type
of include is being used. The include will default
to being non-required. If you want to be more
explicit about the details of the include, you can
provide an attrset with following arguments
`required`
: Whether the parser should fail upon failure
to include the document
`type`
: Type of the source of the included document.
Valid values are `file`, `url` and `classpath`.
See upstream documentation for the semantics
behind each value
`value`
: The URI/path/classpath pointing to the source of
the document to be included.
`Example usage:`
```nix
let
format = pkgs.formats.hocon { };
hocon_file = pkgs.writeText "to_include.hocon" ''
a = 1;
'';
in {
some.nested.hocon.attrset = {
_includes = [
(format.lib.mkInclude hocon_file)
(format.lib.mkInclude "https://example.com/to_include.hocon")
(format.lib.mkInclude {
required = true;
type = "file";
value = include_file;
})
];
...
};
}
```
`mkAppend`
: This is used to invoke the `+=` operator.
This can be useful if you need to add something
to a list that is included from outside of nix.
See upstream documentation for the semantics
behind the `+=` operation.
`Example usage:`
```nix
let
format = pkgs.formats.hocon { };
hocon_file = pkgs.writeText "to_include.hocon" ''
a = [ 1 ];
b = [ 2 ];
'';
in {
_includes = [
(format.lib.mkInclude hocon_file)
];
c = 3;
a = format.lib.mkAppend 3;
b = format.lib.mkAppend (format.lib.mkSubstitution "c");
}
```
`mkSubstitution`
: This is used to make HOCON substitutions.
Similarly to `mkInclude`, this function has
a shorthand variant where you just give it
the string with the substitution value.
The substitution is not optional by default.
Alternatively, you can provide an attrset
with more options
`optional`
: Whether the parser should fail upon
failure to fetch the substitution value.
`value`
: The name of the variable to use for
substitution.
See upstream documentation for semantics
behind the substitution functionality.
`Example usage:`
```nix
let
format = pkgs.formats.hocon { };
in {
a = 1;
b = format.lib.mkSubstitution "a";
c = format.lib.mkSubstitution "SOME_ENVVAR";
d = format.lib.mkSubstitution {
value = "SOME_OPTIONAL_ENVVAR";
optional = true;
};
}
```
`Implementation notes:`
- classpath includes are not implemented in pyhocon,
which is used for validating the HOCON output. This
means that if you are using classpath includes,
you will want to either use an alternative validator
or set `doCheck = false` in the format options.
`pkgs.formats.libconfig` { *`generator`* ? `<derivation>`, *`validator`* ? `<derivation>` }
: A function taking an attribute set with values
`generator`
: A derivation used for converting the JSON output
from the nix settings into libconfig. This might be
useful if your libconfig variant is slightly different
from the original one, or for testing purposes.
`validator`
: A derivation used for verifying that the libconfig
output is correct and parsable. This might be
useful if your libconfig variant is slightly different
from the original one, or for testing purposes.
It returns an attrset with a `type`, `generate` function,
and a `lib` attset, as specified [below](#pkgs-formats-result).
Some of the lib functions will be best understood if you have
read the reference specification. You can find this
specification here:
<https://hyperrealm.github.io/libconfig/libconfig_manual.html#Configuration-Files>
Inside of `lib`, you will find these functions
`mkHex`, `mkOctal`, `mkFloat`
: Use these to specify numbers in other formats.
`Example usage:`
```nix
let
format = pkgs.formats.libconfig { };
in {
myHexValue = format.lib.mkHex "0x1FC3";
myOctalValue = format.lib.mkOctal "0027";
myFloatValue = format.lib.mkFloat "1.2E-3";
}
```
`mkArray`, `mkList`
: Use these to differentiate between whether
a nix list should be considered as a libconfig
array or a libconfig list. See the upstream
documentation for the semantics behind these types.
`Example usage:`
```nix
let
format = pkgs.formats.libconfig { };
in {
myList = format.lib.mkList [ "foo" 1 true ];
myArray = format.lib.mkArray [ 1 2 3 ];
}
```
`Implementation notes:`
- Since libconfig does not allow setting names to start with an underscore,
this is used as a prefix for both special types and include directives.
- The difference between 32bit and 64bit values became optional in libconfig
1.5, so we assume 64bit values for all numbers.
`pkgs.formats.json` { }
: A function taking an empty attribute set (for future extensibility)
and returning a set with JSON-specific attributes `type` and
`generate` as specified [below](#pkgs-formats-result).
`pkgs.formats.yaml` { }
: A function taking an empty attribute set (for future extensibility)
and returning a set with YAML-specific attributes `type` and
`generate` as specified [below](#pkgs-formats-result).
`pkgs.formats.ini` { *`listsAsDuplicateKeys`* ? false, *`listToValue`* ? null, \.\.\. }
: A function taking an attribute set with values
`listsAsDuplicateKeys`
: A boolean for controlling whether list values can be used to
represent duplicate INI keys
`listToValue`
: A function for turning a list of values into a single value.
It returns a set with INI-specific attributes `type` and `generate`
as specified [below](#pkgs-formats-result).
The type of the input is an *attrset* of sections; key-value pairs where
the key is the section name and the value is the corresponding content
which is also an *attrset* of key-value pairs for the actual key-value
mappings of the INI format.
The values of the INI atoms are subject to the above parameters (e.g. lists
may be transformed into multiple key-value pairs depending on
`listToValue`).
The attribute `lib.type.atom` contains the used INI atom.
`pkgs.formats.iniWithGlobalSection` { *`listsAsDuplicateKeys`* ? false, *`listToValue`* ? null, \.\.\. }
: A function taking an attribute set with values
`listsAsDuplicateKeys`
: A boolean for controlling whether list values can be used to
represent duplicate INI keys
`listToValue`
: A function for turning a list of values into a single value.
It returns a set with INI-specific attributes `type` and `generate`
as specified [below](#pkgs-formats-result).
The type of the input is an *attrset* of the structure
`{ sections = {}; globalSection = {}; }` where *sections* are several
sections as with *pkgs.formats.ini* and *globalSection* being just a single
attrset of key-value pairs for a single section, the global section which
precedes the section definitions.
The attribute `lib.type.atom` contains the used INI atom.
`pkgs.formats.toml` { }
: A function taking an empty attribute set (for future extensibility)
and returning a set with TOML-specific attributes `type` and
`generate` as specified [below](#pkgs-formats-result).
`pkgs.formats.xml` { format ? "badgerfish", withHeader ? true}
: A function taking an attribute set with values
and returning a set with XML-specific attributes `type` and
`generate` as specified [below](#pkgs-formats-result).
`format`
: Input format. Because XML can not be translated one-to-one, we have to use intermediate formats. Possible values:
- `"badgerfish"`: Uses [badgerfish](http://www.sklar.com/badgerfish/) conversion.
`withHeader`
: Outputs the xml with header.
`pkgs.formats.plist` { escape ? true }
: A function taking an attribute set with values
`escape`
: Whether to escape XML special characters in string values and keys.
It returns a set with Property list (plist) specific attributes `type` and `generate` as specified [below](#pkgs-formats-result).
`pkgs.formats.pythonVars` { }
: A function taking an empty attribute set (for future extensibility)
and returning a set with python variable specific attributes `type`, `lib`, and
`generate` as specified [below](#pkgs-formats-result).
The `lib` attribute contains functions to be used in settings, for
generating special Python values:
`mkRaw pythonCode`
: Outputs the given string as raw Python code
`_imports`
`_imports` is a special value you can set to specify additional modules to be
imported on top of the file.
`Example usage:`
```nix
let
format = pkgs.formats.pythonVars { };
in {
_imports = [ "re" ];
conditional = format.lib.mkRaw "1 if True else 2";
function_result = format.lib.mkRaw "re.findall(r'\\bf[a-z]*', 'which foot or hand fell fastest')";
}
```
`pkgs.formats.cdn` { }
: A function taking an empty attribute set (for future extensibility)
and returning a set with [CDN](https://github.com/dzikoysk/cdn)-specific
attributes `type` and `generate` as specified [below](#pkgs-formats-result).
`pkgs.formats.elixirConf { elixir ? pkgs.elixir }`
: A function taking an attribute set with values
`elixir`
: The Elixir package which will be used to format the generated output
It returns a set with Elixir-Config-specific attributes `type`, `lib`, and
`generate` as specified [below](#pkgs-formats-result).
The `lib` attribute contains functions to be used in settings, for
generating special Elixir values:
`mkRaw elixirCode`
: Outputs the given string as raw Elixir code
`mkGetEnv { envVariable, fallback ? null }`
: Makes the configuration fetch an environment variable at runtime
`mkAtom atom`
: Outputs the given string as an Elixir atom, instead of the default
Elixir binary string. Note: lowercase atoms still needs to be prefixed
with `:`
`mkTuple array`
: Outputs the given array as an Elixir tuple, instead of the default
Elixir list
`mkMap attrset`
: Outputs the given attribute set as an Elixir map, instead of the
default Elixir keyword list
`pkgs.formats.lua { asBindings ? false, multiline ? true, columnWidth ? 100, indentWidth ? 2, indentUsingTabs ? false }`
: A function taking an attribute set with values
`asBindings` (default `false`)
: Whether to treat attributes as variable bindings
`multiline` (default `true`)
: Whether to produce a multiline output. The output may still wrap across
multiple lines if it would otherwise exceed `columnWidth`.
`columnWidth` (default `100`)
: The column width to use to attempt to wrap lines.
`indentWidth` (default `2`)
: The width of a single indentation level.
`indentUsingTabs` (default `false`)
: Whether the indentation should use tabs instead of spaces.
`pkgs.formats.php { finalVariable }` []{#pkgs-formats-php}
: A function taking an attribute set with values
`finalVariable`
: The variable that will store generated expression (usually `config`). If set to `null`, generated expression will contain `return`.
It returns a set with PHP-Config-specific attributes `type`, `lib`, and
`generate` as specified [below](#pkgs-formats-result).
The `lib` attribute contains functions to be used in settings, for
generating special PHP values:
`mkRaw phpCode`
: Outputs the given string as raw PHP code
`mkMixedArray list set`
: Creates PHP array that contains both indexed and associative values. For example, `lib.mkMixedArray [ "hello" "world" ] { "nix" = "is-great"; }` returns `['hello', 'world', 'nix' => 'is-great']`
[]{#pkgs-formats-result}
These functions all return an attribute set with these values:
`type`
: A module system type representing a value of the format
`lib`
: Utility functions for convenience, or special interactions with the format.
This attribute is optional. It may contain inside a `types` attribute
containing types specific to this format.
`generate` *`filename jsonValue`*
: A function that can render a value of the format to a file. Returns
a file path.
::: {.note}
This function puts the value contents in the Nix store. So this
should be avoided for secrets.
:::
::: {#ex-settings-nix-representable .example}
### Module with conventional `settings` option
The following shows a module for an example program that uses a JSON
configuration file. It demonstrates how above values can be used, along
with some other related best practices. See the comments for
explanations.
```nix
{
options,
config,
lib,
pkgs,
...
}:
let
cfg = config.services.foo;
# Define the settings format used for this program
settingsFormat = pkgs.formats.json { };
in
{
options.services.foo = {
enable = lib.mkEnableOption "foo service";
settings = lib.mkOption {
# Setting this type allows for correct merging behavior
type = settingsFormat.type;
default = { };
description = ''
Configuration for foo, see
<link xlink:href="https://example.com/docs/foo"/>
for supported settings.
'';
};
};
config = lib.mkIf cfg.enable {
# We can assign some default settings here to make the service work by just
# enabling it. We use `mkDefault` for values that can be changed without
# problems
services.foo.settings = {
# Fails at runtime without any value set
log_level = lib.mkDefault "WARN";
# We assume systemd's `StateDirectory` is used, so we require this value,
# therefore no mkDefault
data_path = "/var/lib/foo";
# Since we use this to create a user we need to know the default value at
# eval time
user = lib.mkDefault "foo";
};
environment.etc."foo.json".source =
# The formats generator function takes a filename and the Nix value
# representing the format value and produces a filepath with that value
# rendered in the format
settingsFormat.generate "foo-config.json" cfg.settings;
# We know that the `user` attribute exists because we set a default value
# for it above, allowing us to use it without worries here
users.users.${cfg.settings.user} = {
isSystemUser = true;
};
# ...
};
}
```
:::
### Option declarations for attributes {#sec-settings-attrs-options}
Some `settings` attributes may deserve some extra care. They may need a
different type, default or merging behavior, or they are essential
options that should show their documentation in the manual. This can be
done using [](#sec-freeform-modules).
We extend above example using freeform modules to declare an option for
the port, which will enforce it to be a valid integer and make it show
up in the manual.
::: {#ex-settings-typed-attrs .example}
### Declaring a type-checked `settings` attribute
```nix
{
settings = lib.mkOption {
type = lib.types.submodule {
freeformType = settingsFormat.type;
# Declare an option for the port such that the type is checked and this option
# is shown in the manual.
options.port = lib.mkOption {
type = lib.types.port;
default = 8080;
description = ''
Which port this service should listen on.
'';
};
};
default = { };
description = ''
Configuration for Foo, see
<link xlink:href="https://example.com/docs/foo"/>
for supported values.
'';
};
}
```
:::

77
reference/nixos-manual/development/sources.chapter.md Normal file
View File

@@ -0,0 +1,77 @@
# Getting the Sources {#sec-getting-sources}
By default, NixOS's `nixos-rebuild` command uses the NixOS and Nixpkgs
sources provided by the `nixos` channel (kept in
`/nix/var/nix/profiles/per-user/root/channels/nixos`). To modify NixOS,
however, you should check out the latest sources from Git. This is as
follows:
```ShellSession
$ git clone https://github.com/NixOS/nixpkgs
$ cd nixpkgs
$ git remote update origin
```
This will check out the latest Nixpkgs sources to `./nixpkgs` the NixOS
sources to `./nixpkgs/nixos`. (The NixOS source tree lives in a
subdirectory of the Nixpkgs repository.) The `nixpkgs` repository has
branches that correspond to each Nixpkgs/NixOS channel (see
[](#sec-upgrading) for more information about channels). Thus, the
Git branch `origin/nixos-17.03` will contain the latest built and tested
version available in the `nixos-17.03` channel.
It's often inconvenient to develop directly on the master branch, since
if somebody has just committed (say) a change to GCC, then the binary
cache may not have caught up yet and you'll have to rebuild everything
from source. So you may want to create a local branch based on your
current NixOS version:
```ShellSession
$ nixos-version
17.09pre104379.6e0b727 (Hummingbird)
$ git checkout -b local 6e0b727
```
Or, to base your local branch on the latest version available in a NixOS
channel:
```ShellSession
$ git remote update origin
$ git checkout -b local origin/nixos-17.03
```
(Replace `nixos-17.03` with the name of the channel you want to use.)
You can use `git merge` or `git
rebase` to keep your local branch in sync with the channel, e.g.
```ShellSession
$ git remote update origin
$ git merge origin/nixos-17.03
```
You can use `git cherry-pick` to copy commits from your local branch to
the upstream branch.
If you want to rebuild your system using your (modified) sources, you
need to tell `nixos-rebuild` about them using the `-I` flag:
```ShellSession
# nixos-rebuild switch -I nixpkgs=/my/sources/nixpkgs
```
If you want `nix-env` to use the expressions in `/my/sources`, use
`nix-env -f
/my/sources/nixpkgs`, or change the default by adding a symlink in
`~/.nix-defexpr`:
```ShellSession
$ ln -s /my/sources/nixpkgs ~/.nix-defexpr/nixpkgs
```
You may want to delete the symlink `~/.nix-defexpr/channels_root` to
prevent root's NixOS channel from clashing with your own tree (this may
break the command-not-found utility though). If you want to go back to
the default state, you may just remove the `~/.nix-defexpr` directory
completely, log out and log in again and it should have been recreated
with a link to the root channels.

161
reference/nixos-manual/development/testing-hardware-features.section.md Normal file
View File

@@ -0,0 +1,161 @@
# Testing Hardware Features {#sec-nixos-test-testing-hardware-features}
This section covers how to test various features using NixOS tests that would
normally only be possible with hardware. It is designed to showcase the NixOS test
framework's flexibility when combined with various hardware simulation libraries
or kernel modules.
## Wi-Fi {#sec-nixos-test-wifi}
Use `services.vwifi` to set up a virtual Wi-Fi physical layer. Create at least two nodes
for this kind of test: one with vwifi active, and either a station or an access point.
Give each a static IP address on the test network so they will never collide.
This module likely supports other topologies too; document them if you make one.
This NixOS module leverages [vwifi](https://github.com/Raizo62/vwifi). Read the
upstream repository's documentation for more information.
### vwifi server {#sec-nixos-test-wifi-vwifi-server}
This node runs the vwifi server, and otherwise does not interact with the network.
You can run `vwifi-ctrl` on this node to control characteristics of the simulated
physical layer.
```nix
{
airgap =
{ config, ... }:
{
networking.interfaces.eth1.ipv4.addresses = lib.mkForce [
{
address = "192.168.1.2";
prefixLength = 24;
}
];
services.vwifi = {
server = {
enable = true;
ports.tcp = 8212;
# uncomment if you want to enable monitor mode on another node
# ports.spy = 8213;
openFirewall = true;
};
};
};
}
```
### AP {#sec-nixos-test-wifi-ap}
A node like this will act as a wireless access point in infrastructure mode.
```nix
{
ap =
{ config, ... }:
{
networking.interfaces.eth1.ipv4.addresses = lib.mkForce [
{
address = "192.168.1.3";
prefixLength = 24;
}
];
services.hostapd = {
enable = true;
radios.wlan0 = {
channel = 1;
networks.wlan0 = {
ssid = "NixOS Test Wi-Fi Network";
authentication = {
mode = "wpa3-sae";
saePasswords = [ { password = "supersecret"; } ];
enableRecommendedPairwiseCiphers = true;
};
};
};
};
services.vwifi = {
module = {
enable = true;
macPrefix = "74:F8:F6:00:01";
};
client = {
enable = true;
serverAddress = "192.168.1.2";
};
};
};
}
```
### Station {#sec-nixos-test-wifi-station}
A node like this acts as a wireless client.
```nix
{
station =
{ config, ... }:
{
networking.interfaces.eth1.ipv4.addresses = lib.mkForce [
{
address = "192.168.1.3";
prefixLength = 24;
}
];
networking.wireless = {
# No, really, we want it enabled!
enable = lib.mkOverride 0 true;
interfaces = [ "wlan0" ];
networks = {
"NixOS Test Wi-Fi Network" = {
psk = "supersecret";
authProtocols = [ "SAE" ];
};
};
};
services.vwifi = {
module = {
enable = true;
macPrefix = "74:F8:F6:00:02";
};
client = {
enable = true;
serverAddress = "192.168.1.2";
};
};
};
}
```
### Monitor {#sec-nixos-test-wifi-monitor}
When the monitor mode interface is enabled, this node will receive
all packets broadcast by all other nodes through the spy interface.
```nix
{
monitor =
{ config, ... }:
{
networking.interfaces.eth1.ipv4.addresses = lib.mkForce [
{
address = "192.168.1.4";
prefixLength = 24;
}
];
services.vwifi = {
module = {
enable = true;
macPrefix = "74:F8:F6:00:03";
};
client = {
enable = true;
spy = true;
serverAddress = "192.168.1.2";
};
};
};
}
```

18
reference/nixos-manual/development/testing-installer.chapter.md Normal file
View File

@@ -0,0 +1,18 @@
# Testing the Installer {#ch-testing-installer}
Building, burning, and booting from an installation CD is rather
tedious, so here is a quick way to see if the installer works properly:
```ShellSession
# mount -t tmpfs none /mnt
# nixos-generate-config --root /mnt
$ nix-build '<nixpkgs>' -A nixos-install
# ./result/bin/nixos-install
```
To start a login shell in the new NixOS installation in `/mnt`:
```ShellSession
$ nix-build '<nixpkgs>' -A nixos-enter
# ./result/bin/nixos-enter
```

111
reference/nixos-manual/development/unit-handling.section.md Normal file
View File

@@ -0,0 +1,111 @@
# Unit handling {#sec-unit-handling}
To figure out what units need to be started/stopped/restarted/reloaded, the
script first checks the current state of the system, similar to what `systemctl
list-units` shows. For each of the units, the script goes through the following
checks:
- Is the unit file still in the new system? If not, **stop** the service unless
it sets `X-StopOnRemoval` in the `[Unit]` section to `false`.
- Is it a `.target` unit? If so, **start** it unless it sets
`RefuseManualStart` in the `[Unit]` section to `true` or `X-OnlyManualStart`
in the `[Unit]` section to `true`. Also **stop** the unit again unless it
sets `X-StopOnReconfiguration` to `false`.
- Are the contents of the unit files different? They are compared by parsing
them and comparing their contents. If they are different but only
`X-Reload-Triggers` in the `[Unit]` section is changed, **reload** the unit.
The NixOS module system allows setting these triggers with the option
[systemd.services.\<name\>.reloadTriggers](#opt-systemd.services). There are
some additional keys in the `[Unit]` section that are ignored as well. If the
unit files differ in any way, the following actions are performed:
- `.path` and `.slice` units are ignored. There is no need to restart them
since changes in their values are applied by systemd when systemd is
reloaded.
- `.mount` units are **reload**ed if only their `Options` changed. If anything
else changed (like `What`), they are **restart**ed unless they are the mount
unit for `/` or `/nix` in which case they are reloaded to prevent the system
from crashing. Note that this is the case for `.mount` units and not for
mounts from `/etc/fstab`. These are explained in [](#sec-switching-systems).
- `.socket` units are currently ignored. This is to be fixed at a later
point.
- The rest of the units (mostly `.service` units) are then **reload**ed if
`X-ReloadIfChanged` in the `[Service]` section is set to `true` (exposed
via [systemd.services.\<name\>.reloadIfChanged](#opt-systemd.services)).
A little exception is done for units that were deactivated in the meantime,
for example because they require a unit that got stopped before. These
are **start**ed instead of reloaded.
- If the reload flag is not set, some more flags decide if the unit is
skipped. These flags are `X-RestartIfChanged` in the `[Service]` section
(exposed via
[systemd.services.\<name\>.restartIfChanged](#opt-systemd.services)),
`RefuseManualStop` in the `[Unit]` section, and `X-OnlyManualStart` in the
`[Unit]` section.
- Further behavior depends on the unit having `X-StopIfChanged` in the
`[Service]` section set to `true` (exposed via
[systemd.services.\<name\>.stopIfChanged](#opt-systemd.services)). This is
set to `true` by default and must be explicitly turned off if not wanted.
If the flag is enabled, the unit is **stop**ped and then **start**ed. If
not, the unit is **restart**ed. The goal of the flag is to make sure that
the new unit never runs in the old environment which is still in place
before the activation script is run. This behavior is different when the
service is socket-activated, as outlined in the following steps.
- The last thing that is taken into account is whether the unit is a
service and socket-activated. A correspondence between a
`.service` and its `.socket` unit is detected automatically, but
services can **opt out** of that detection by setting
`X-NotSocketActivated` to `yes` in their `[Service]`
section. Otherwise, if `X-StopIfChanged` is **not** set, the
service is **restart**ed with the others. If it is set, both the
service and the socket are **stop**ped and the socket is
**start**ed, leaving socket activation to start the service when
it's needed.
## Sysinit reactivation {#sec-sysinit-reactivation}
[`sysinit.target`](https://www.freedesktop.org/software/systemd/man/latest/systemd.special.html#sysinit.target)
is a systemd target that encodes system initialization (i.e. early startup). A
few units that need to run very early in the bootup process are ordered to
finish before this target is reached. Probably the most notable one of these is
`systemd-tmpfiles-setup.service`. We will refer to these units as "sysinit
units".
"Normal" systemd units, by default, are ordered AFTER `sysinit.target`. In
other words, these "normal" units expect all services ordered before
`sysinit.target` to have finished without explicitly declaring this dependency
relationship for each dependency. See the [systemd
bootup](https://www.freedesktop.org/software/systemd/man/latest/bootup.html)
for more details on the bootup process.
When restarting both a unit ordered before `sysinit.target` as well as one
after, this presents a problem because they would be started at the same time
as they do not explicitly declare their dependency relations.
To solve this, NixOS has an artificial `sysinit-reactivation.target` which
allows you to ensure that services ordered before `sysinit.target` are
restarted correctly. This applies both to the ordering between these sysinit
services as well as ensuring that sysinit units are restarted before "normal"
units.
To make an existing sysinit service restart correctly during system switch, you
have to declare:
```nix
{
systemd.services.my-sysinit = {
requiredBy = [ "sysinit-reactivation.target" ];
before = [ "sysinit-reactivation.target" ];
restartTriggers = [ config.environment.etc."my-sysinit.d".source ];
};
}
```
You need to configure appropriate `restartTriggers` specific to your service.

62
reference/nixos-manual/development/what-happens-during-a-system-switch.chapter.md Normal file
View File

@@ -0,0 +1,62 @@
# What happens during a system switch? {#sec-switching-systems}
Running `nixos-rebuild switch` is one of the more common tasks under NixOS.
This chapter explains some of the internals of this command to make it simpler
for new module developers to configure their units correctly and to make it
easier to understand what is happening and why for curious administrators.
`nixos-rebuild`, like many deployment solutions, calls `switch-to-configuration`
which resides in a NixOS system at `$out/bin/switch-to-configuration`. The
script is called with the action that is to be performed like `switch`, `test`,
`boot`. There is also the `dry-activate` action which does not really perform
the actions but rather prints what it would do if you called it with `test`.
This feature can be used to check what service states would be changed if the
configuration was switched to.
If the action is `switch` or `boot`, the bootloader is updated first so the
configuration will be the next one to boot. Unless `NIXOS_NO_SYNC` is set to
`1`, `/nix/store` is synced to disk.
If the action is `switch` or `test`, the currently running system is inspected
and the actions to switch to the new system are calculated. This process takes
two data sources into account: `/etc/fstab` and the current systemd status.
Mounts and swaps are read from `/etc/fstab` and the corresponding actions are
generated. If the options of a mount are modified, for example, the proper `.mount`
unit is reloaded (or restarted if anything else changed and it's neither the root
mount or the nix store). The current systemd state is inspected, the difference
between the current system and the desired configuration is calculated and
actions are generated to get to this state. There are a lot of nuances that can
be controlled by the units which are explained here.
After calculating what should be done, the actions are carried out. The order
of actions is always the same:
- Stop units (`systemctl stop`)
- Run activation script (`$out/activate`)
- See if the activation script requested more units to restart
- Restart systemd if needed (`systemd daemon-reexec`)
- Forget about the failed state of units (`systemctl reset-failed`)
- Reload systemd (`systemctl daemon-reload`)
- Reload systemd user instances (`systemctl --user daemon-reload`)
- Reactivate sysinit (`systemctl restart sysinit-reactivation.target`)
- Reload units (`systemctl reload`)
- Restart units (`systemctl restart`)
- Start units (`systemctl start`)
- Inspect what changed during these actions and print units that failed and
that were newly started
By default, some units are filtered from the outputs to make it less spammy.
This can be disabled for development or testing by setting the environment variable
`STC_DISPLAY_ALL_UNITS=1`.
More detailed output can be displayed by setting `STC_DEBUG=1`.
Most of these actions are either self-explaining but some of them have to do
with our units or the activation script. For this reason, these topics are
explained in the next sections.
```{=include=} sections
unit-handling.section.md
activation-script.section.md
non-switchable-systems.section.md
etc-overlay.section.md
```

31
reference/nixos-manual/development/writing-documentation.chapter.md Normal file
View File

@@ -0,0 +1,31 @@
# Writing NixOS Documentation {#sec-writing-documentation}
As NixOS grows, so too does the need for a catalogue and explanation of
its extensive functionality. Collecting pertinent information from
disparate sources and presenting it in an accessible style would be a
worthy contribution to the project.
## Building the Manual {#sec-writing-docs-building-the-manual}
The sources of the [](#book-nixos-manual) are in the
[`nixos/doc/manual`](https://github.com/NixOS/nixpkgs/tree/master/nixos/doc/manual)
subdirectory of the Nixpkgs repository.
You can quickly validate your edits with `devmode`:
```ShellSession
$ cd /path/to/nixpkgs/nixos/doc/manual
$ nix-shell
[nix-shell:~]$ devmode
```
Once you are done making modifications to the manual, it's important to
build it before committing. You can do that as follows:
```ShellSession
nix-build nixos/release.nix -A manual.x86_64-linux
```
When this command successfully finishes, it will tell you where the
manual got generated. The HTML will be accessible through the `result`
symlink at `./result/share/doc/nixos/index.html`.

223
reference/nixos-manual/development/writing-modules.chapter.md Normal file
View File

@@ -0,0 +1,223 @@
# Writing NixOS Modules {#sec-writing-modules}
NixOS has a modular system for declarative configuration. This system
combines multiple *modules* to produce the full system configuration.
One of the modules that constitute the configuration is
`/etc/nixos/configuration.nix`. Most of the others live in the
[`nixos/modules`](https://github.com/NixOS/nixpkgs/tree/master/nixos/modules)
subdirectory of the Nixpkgs tree.
Each NixOS module is a file that handles one logical aspect of the
configuration, such as a specific kind of hardware, a service, or
network settings. A module configuration does not have to handle
everything from scratch; it can use the functionality provided by other
modules for its implementation. Thus a module can *declare* options that
can be used by other modules, and conversely can *define* options
provided by other modules in its own implementation. For example, the
module
[`pam.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/security/pam.nix)
declares the option `security.pam.services` that allows other modules (e.g.
[`sshd.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/services/networking/ssh/sshd.nix))
to define PAM services; and it defines the option `environment.etc` (declared by
[`etc.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/system/etc/etc.nix))
to cause files to be created in `/etc/pam.d`.
In [](#sec-configuration-syntax), we saw the following structure of
NixOS modules:
```nix
{ config, pkgs, ... }:
{
# option definitions
}
```
This is actually an *abbreviated* form of module that only defines
options, but does not declare any. The structure of full NixOS modules
is shown in [Example: Structure of NixOS Modules](#ex-module-syntax).
::: {#ex-module-syntax .example}
### Structure of NixOS Modules
```nix
{ config, pkgs, ... }:
{
imports = [
# paths of other modules
];
options = {
# option declarations
};
config = {
# option definitions
};
}
```
:::
The meaning of each part is as follows.
- The first line makes the current Nix expression a function. The variable
`pkgs` contains Nixpkgs (by default, it takes the `nixpkgs` entry of
`NIX_PATH`, see the [Nix manual](https://nixos.org/manual/nix/stable/#sec-common-env)
for further details), while `config` contains the full system
configuration. This line can be omitted if there is no reference to
`pkgs` and `config` inside the module.
- This `imports` list enumerates the paths to other NixOS modules that
should be included in the evaluation of the system configuration. A
default set of modules is defined in the file `modules/module-list.nix`.
These don't need to be added in the import list.
- The attribute `options` is a nested set of *option declarations*
(described below).
- The attribute `config` is a nested set of *option definitions* (also
described below).
[Example: NixOS Module for the "locate" Service](#locate-example)
shows a module that handles the regular update of the "locate" database,
an index of all files in the file system. This module declares two
options that can be defined by other modules (typically the user's
`configuration.nix`): `services.locate.enable` (whether the database should
be updated) and `services.locate.interval` (when the update should be done).
It implements its functionality by defining two options declared by other
modules: `systemd.services` (the set of all systemd services) and
`systemd.timers` (the list of commands to be executed periodically by
`systemd`).
Care must be taken when writing systemd services using `Exec*` directives. By
default systemd performs substitution on `%<char>` specifiers in these
directives, expands environment variables from `$FOO` and `${FOO}`, splits
arguments on whitespace, and splits commands on `;`. All of these must be escaped
to avoid unexpected substitution or splitting when interpolating into an `Exec*`
directive, e.g. when using an `extraArgs` option to pass additional arguments to
the service. The functions `utils.escapeSystemdExecArg` and
`utils.escapeSystemdExecArgs` are provided for this, see [Example: Escaping in
Exec directives](#exec-escaping-example) for an example. When using these
functions system environment substitution should *not* be disabled explicitly.
::: {#locate-example .example}
### NixOS Module for the "locate" Service
```nix
{
config,
lib,
pkgs,
...
}:
let
inherit (lib)
concatStringsSep
mkIf
mkOption
optionalString
types
;
cfg = config.services.locate;
in
{
options.services.locate = {
enable = mkOption {
type = types.bool;
default = false;
description = ''
If enabled, NixOS will periodically update the database of
files used by the locate command.
'';
};
interval = mkOption {
type = types.str;
default = "02:15";
example = "hourly";
description = ''
Update the locate database at this interval. Updates by
default at 2:15 AM every day.
The format is described in
systemd.time(7).
'';
};
# Other options omitted for documentation
};
config = {
systemd.services.update-locatedb = {
description = "Update Locate Database";
path = [ pkgs.su ];
script = ''
mkdir -p $(dirname ${toString cfg.output})
chmod 0755 $(dirname ${toString cfg.output})
exec updatedb \
--localuser=${cfg.localuser} \
${optionalString (!cfg.includeStore) "--prunepaths='/nix/store'"} \
--output=${toString cfg.output} ${concatStringsSep " " cfg.extraFlags}
'';
};
systemd.timers.update-locatedb = mkIf cfg.enable {
description = "Update timer for locate database";
partOf = [ "update-locatedb.service" ];
wantedBy = [ "timers.target" ];
timerConfig.OnCalendar = cfg.interval;
};
};
}
```
:::
::: {#exec-escaping-example .example}
### Escaping in Exec directives
```nix
{
config,
pkgs,
utils,
...
}:
let
cfg = config.services.echo;
echoAll = pkgs.writeScript "echo-all" ''
#! ${pkgs.runtimeShell}
for s in "$@"; do
printf '%s\n' "$s"
done
'';
args = [
"a%Nything"
"lang=\${LANG}"
";"
"/bin/sh -c date"
];
in
{
systemd.services.echo = {
description = "Echo to the journal";
wantedBy = [ "multi-user.target" ];
serviceConfig.Type = "oneshot";
serviceConfig.ExecStart = ''
${echoAll} ${utils.escapeSystemdExecArgs args}
'';
};
}
```
:::
```{=include=} sections
option-declarations.section.md
option-types.section.md
option-def.section.md
assertions.section.md
meta-attributes.section.md
importing-modules.section.md
replace-modules.section.md
freeform-modules.section.md
settings-options.section.md
```

406
reference/nixos-manual/development/writing-nixos-tests.section.md Normal file
View File

@@ -0,0 +1,406 @@
# Writing Tests {#sec-writing-nixos-tests}
A NixOS test is a module that has the following structure:
```nix
{
# One or more machines:
nodes = {
machine =
{ config, pkgs, ... }:
{
# ...
};
machine2 =
{ config, pkgs, ... }:
{
# ...
};
# …
};
testScript = ''
Python code…
'';
}
```
We refer to the whole test above as a test module, whereas the values
in [`nodes.<name>`](#test-opt-nodes) are NixOS modules themselves.
The option [`testScript`](#test-opt-testScript) is a piece of Python code that executes the
test (described below). During the test, it will start one or more
virtual machines, the configuration of which is described by
the option [`nodes`](#test-opt-nodes).
An example of a single-node test is
[`login.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix).
It only needs a single machine to test whether users can log in
on the virtual console, whether device ownership is correctly maintained
when switching between consoles, and so on. An interesting multi-node test is
[`nfs/simple.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nfs/simple.nix).
It uses two client nodes to test correct locking across server crashes.
## Calling a test {#sec-calling-nixos-tests}
Tests are invoked differently depending on whether the test is part of NixOS or lives in a different project.
### Testing within NixOS {#sec-call-nixos-test-in-nixos}
Tests that are part of NixOS are added to [`nixos/tests/all-tests.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/all-tests.nix).
```nix
{ hostname = runTest ./hostname.nix; }
```
Overrides can be added by defining an anonymous module in `all-tests.nix`.
```nix
{
hostname = runTest {
imports = [ ./hostname.nix ];
defaults.networking.firewall.enable = false;
};
}
```
You can run a test with attribute name `hostname` in `nixos/tests/all-tests.nix` by invoking:
```shell
cd /my/git/clone/of/nixpkgs
nix-build -A nixosTests.hostname
```
### Testing outside the NixOS project {#sec-call-nixos-test-outside-nixos}
Outside the `nixpkgs` repository, you can use the `runNixOSTest` function from
`pkgs.testers`:
```nix
let
pkgs = import <nixpkgs> { };
in
pkgs.testers.runNixOSTest {
imports = [ ./test.nix ];
defaults.services.foo.package = mypkg;
}
```
`runNixOSTest` returns a derivation that runs the test.
## Configuring the nodes {#sec-nixos-test-nodes}
There are a few special NixOS options for test VMs:
`virtualisation.memorySize`
: The memory of the VM in MiB (1024×1024 bytes).
`virtualisation.vlans`
: The virtual networks to which the VM is connected. See
[`nat.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nat.nix)
for an example.
`virtualisation.writableStore`
: By default, the Nix store in the VM is not writable. If you enable
this option, a writable union file system is mounted on top of the
Nix store to make it appear writable. This is necessary for tests
that run Nix operations that modify the store.
For more options, see the module
[`qemu-vm.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/qemu-vm.nix).
The test script is a sequence of Python statements that perform various
actions, such as starting VMs, executing commands in the VMs, and so on.
Each virtual machine is represented as an object stored in the variable
`name` if this is also the identifier of the machine in the declarative
config. If you specified a node `nodes.machine`, the following example starts the
machine, waits until it has finished booting, then executes a command
and checks that the output is more-or-less correct:
```py
machine.start()
machine.wait_for_unit("default.target")
t.assertIn("Linux", machine.succeed("uname"), "Wrong OS")
```
The first line is technically unnecessary; machines are implicitly started
when you first execute an action on them (such as `wait_for_unit` or
`succeed`). If you have multiple machines, you can speed up the test by
starting them in parallel:
```py
start_all()
```
Under the variable `t`, all assertions from [`unittest.TestCase`](https://docs.python.org/3/library/unittest.html) are available.
If the hostname of a node contains characters that can't be used in a
Python variable name, those characters will be replaced with
underscores in the variable name, so `nodes.machine-a` will be exposed
to Python as `machine_a`.
## Machine objects {#ssec-machine-objects}
The following methods are available on machine objects:
@PYTHON_MACHINE_METHODS@
To test user units declared by `systemd.user.services` the optional
`user` argument can be used:
```py
machine.start()
machine.wait_for_x()
machine.wait_for_unit("xautolock.service", "x-session-user")
```
This applies to `systemctl`, `get_unit_info`, `wait_for_unit`,
`start_job` and `stop_job`.
For faster dev cycles it's also possible to disable the code-linters
(this shouldn't be committed though):
```nix
{
skipLint = true;
nodes.machine =
{ config, pkgs, ... }:
{
# configuration…
};
testScript = ''
Python code…
'';
}
```
This will produce a Nix warning at evaluation time. To fully disable the
linter, wrap the test script in comment directives to disable the Black
linter directly (again, don't commit this within the Nixpkgs
repository):
```nix
{
testScript = ''
# fmt: off
Python code…
# fmt: on
'';
}
```
Similarly, the type checking of test scripts can be disabled in the following
way:
```nix
{
skipTypeCheck = true;
nodes.machine =
{ config, pkgs, ... }:
{
# configuration…
};
}
```
## Failing tests early {#ssec-failing-tests-early}
To fail tests early when certain invariants are no longer met (instead of waiting for the build to time out), the decorator `polling_condition` is provided. For example, if we are testing a program `foo` that should not quit after being started, we might write the following:
```py
@polling_condition
def foo_running():
machine.succeed("pgrep -x foo")
machine.succeed("foo --start")
machine.wait_until_succeeds("pgrep -x foo")
with foo_running:
... # Put `foo` through its paces
```
`polling_condition` takes the following (optional) arguments:
`seconds_interval`
: specifies how often the condition should be polled:
```py
@polling_condition(seconds_interval=10)
def foo_running():
machine.succeed("pgrep -x foo")
```
`description`
: is used in the log when the condition is checked. If this is not provided, the description is pulled from the docstring of the function. These two are therefore equivalent:
```py
@polling_condition
def foo_running():
"check that foo is running"
machine.succeed("pgrep -x foo")
```
```py
@polling_condition(description="check that foo is running")
def foo_running():
machine.succeed("pgrep -x foo")
```
## Adding Python packages to the test script {#ssec-python-packages-in-test-script}
When additional Python libraries are required in the test script, they can be
added using the parameter `extraPythonPackages`. For example, you could add
`numpy` like this:
```nix
{
extraPythonPackages = p: [ p.numpy ];
nodes = { };
# Type checking on extra packages doesn't work yet
skipTypeCheck = true;
testScript = ''
import numpy as np
assert str(np.zeros(4)) == "[0. 0. 0. 0.]"
'';
}
```
In that case, `numpy` is chosen from the generic `python3Packages`.
## Overriding a test {#sec-override-nixos-test}
The NixOS test framework returns tests with multiple overriding methods.
`overrideTestDerivation` *function*
: Like applying `overrideAttrs` on the [test](#test-opt-test) derivation.
This is a convenience for `extend` with an override on the [`rawTestDerivationArg`](#test-opt-rawTestDerivationArg) option.
*function*
: An extension function, e.g. `finalAttrs: prevAttrs: { /* … */ }`, the result of which is passed to [`mkDerivation`](https://nixos.org/manual/nixpkgs/stable/#sec-using-stdenv).
Just as with `overrideAttrs`, an abbreviated form can be used, e.g. `prevAttrs: { /* … */ }` or even `{ /* … */ }`.
See [`lib.extends`](https://nixos.org/manual/nixpkgs/stable/#function-library-lib.fixedPoints.extends).
`extendNixOS { module = ` *module* `; specialArgs = ` *specialArgs* `; }`
: Evaluates the test with additional NixOS modules and/or arguments.
`module`
: A NixOS module to add to all the nodes in the test. Sets test option [`extraBaseModules`](#test-opt-extraBaseModules).
`specialArgs`
: An attribute set of arguments to pass to all NixOS modules. These override the existing arguments, as well as any `_module.args.<name>` that the modules may define. Sets test option [`node.specialArgs`](#test-opt-node.specialArgs).
This is a convenience function for `extend` that overrides the aforementioned test options.
:::{.example #ex-nixos-test-extendNixOS}
# Using extendNixOS in `passthru.tests` to make `(openssh.tests.overrideAttrs f).tests.nixos` coherent
```nix
mkDerivation (finalAttrs: {
# …
passthru = {
tests = {
nixos = nixosTests.openssh.extendNixOS {
module = {
services.openssh.package = finalAttrs.finalPackage;
};
};
};
};
})
```
:::
`extend { modules = ` *modules* `; specialArgs = ` *specialArgs* `; }`
: Adds new `nixosTest` modules and/or module arguments to the test, which are evaluated together with the existing modules and [built-in options](#sec-test-options-reference).
If you're only looking to extend the _NixOS_ configurations of the test, and not something else about the test, you may use the `extendNixOS` convenience function instead.
`modules`
: A list of modules to add to the test. These are added to the existing modules and then [evaluated](https://nixos.org/manual/nixpkgs/stable/index.html#module-system-lib-evalModules) together.
`specialArgs`
: An attribute of arguments to pass to the test. These override the existing arguments, as well as any `_module.args.<name>` that the modules may define. See [`evalModules`/`specialArgs`](https://nixos.org/manual/nixpkgs/stable/#module-system-lib-evalModules-param-specialArgs).
## Test Options Reference {#sec-test-options-reference}
The following options can be used when writing tests.
```{=include=} options
id-prefix: test-opt-
list-id: test-options-list
source: @NIXOS_TEST_OPTIONS_JSON@
```
## Accessing VMs in the sandbox with SSH {#sec-test-sandbox-breakpoint}
::: {.note}
For debugging with SSH access into the machines, it's recommended to try using
[the interactive driver](#sec-running-nixos-tests-interactively) with its
[SSH backdoor](#sec-nixos-test-ssh-access) first.
This feature is mostly intended to debug flaky test failures that aren't
reproducible elsewhere.
:::
As explained in [](#sec-nixos-test-ssh-access), it's possible to configure an
SSH backdoor based on AF_VSOCK. This can be used to SSH into a VM of a running
build in a sandbox.
This can be done when something in the test fails, e.g.
```nix
{
nodes.machine = { };
sshBackdoor.enable = true;
enableDebugHook = true;
testScript = ''
start_all()
machine.succeed("false") # this will fail
'';
}
```
For the AF_VSOCK feature to work, `/dev/vhost-vsock` is needed in the sandbox
which can be done with e.g.
```
nix-build -A nixosTests.foo --option sandbox-paths /dev/vhost-vsock
```
This will halt the test execution on a test-failure and print instructions
on how to enter the sandbox shell of the VM test. Inside, one can log into
e.g. `machine` with
```
ssh -F ./ssh_config vsock/3
```
As described in [](#sec-nixos-test-ssh-access), the numbers for vsock start at
`3` instead of `1`. So the first VM in the network (sorted alphabetically) can
be accessed with `vsock/3`.
Alternatively, it's possible to explicitly set a breakpoint with
`debug.breakpoint()`. This also has the benefit, that one can step through
`testScript` with `pdb` like this:
```
$ sudo /nix/store/eeeee-attach <id>
bash# telnet 127.0.0.1 4444
pdb$ …
```