diff options
Diffstat (limited to 'nixos/doc/manual')
9 files changed, 334 insertions, 129 deletions
diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index d61bbaddf76..ecd62eb4e84 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -13,6 +13,8 @@ with pkgs; let + inherit (lib) hasPrefix removePrefix; + lib = pkgs.lib; docbook_xsl_ns = pkgs.docbook-xsl-ns.override { @@ -36,6 +38,33 @@ let }; }; + nixos-lib = import ../../lib { }; + + testOptionsDoc = let + eval = nixos-lib.evalTest { + # Avoid evaluating a NixOS config prototype. + config.node.type = lib.types.deferredModule; + options._module.args = lib.mkOption { internal = true; }; + }; + in buildPackages.nixosOptionsDoc { + inherit (eval) options; + inherit (revision); + transformOptions = opt: opt // { + # Clean up declaration sites to not refer to the NixOS source tree. + declarations = + map + (decl: + if hasPrefix (toString ../../..) (toString decl) + then + let subpath = removePrefix "/" (removePrefix (toString ../../..) (toString decl)); + in { url = "https://github.com/NixOS/nixpkgs/blob/master/${subpath}"; name = subpath; } + else decl) + opt.declarations; + }; + documentType = "none"; + variablelistId = "test-options-list"; + }; + sources = lib.sourceFilesBySuffices ./. [".xml"]; modulesDoc = builtins.toFile "modules.xml" '' @@ -50,6 +79,7 @@ let mkdir $out ln -s ${modulesDoc} $out/modules.xml ln -s ${optionsDoc.optionsDocBook} $out/options-db.xml + ln -s ${testOptionsDoc.optionsDocBook} $out/test-options-db.xml printf "%s" "${version}" > $out/version ''; diff --git a/nixos/doc/manual/development/running-nixos-tests-interactively.section.md b/nixos/doc/manual/development/running-nixos-tests-interactively.section.md index a1431859ff5..d9c316f4b13 100644 --- a/nixos/doc/manual/development/running-nixos-tests-interactively.section.md +++ b/nixos/doc/manual/development/running-nixos-tests-interactively.section.md @@ -24,6 +24,8 @@ 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). +## 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. @@ -33,3 +35,15 @@ $ ./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](#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](#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`. diff --git a/nixos/doc/manual/development/running-nixos-tests.section.md b/nixos/doc/manual/development/running-nixos-tests.section.md index 1bec023b613..33076f5dc2a 100644 --- a/nixos/doc/manual/development/running-nixos-tests.section.md +++ b/nixos/doc/manual/development/running-nixos-tests.section.md @@ -2,22 +2,11 @@ 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 just do: +you do: ```ShellSession -$ nix-build '<nixpkgs/nixos/tests/login.nix>' -``` - -or, if you don't want to rely on `NIX_PATH`: - -```ShellSession -$ cd /my/nixpkgs/nixos/tests -$ nix-build login.nix -… -running the VM test script -machine: QEMU running (pid 8841) -… -6 out of 6 tests succeeded +$ cd /my/git/clone/of/nixpkgs +$ nix-build -A nixosTests.login ``` After building/downloading all required dependencies, this will perform diff --git a/nixos/doc/manual/development/writing-nixos-tests.section.md b/nixos/doc/manual/development/writing-nixos-tests.section.md index 6934bb0face..99704ec3c14 100644 --- a/nixos/doc/manual/development/writing-nixos-tests.section.md +++ b/nixos/doc/manual/development/writing-nixos-tests.section.md @@ -1,9 +1,9 @@ # Writing Tests {#sec-writing-nixos-tests} -A NixOS test is a Nix expression that has the following structure: +A NixOS test is a module that has the following structure: ```nix -import ./make-test-python.nix { +{ # One or more machines: nodes = @@ -21,10 +21,13 @@ import ./make-test-python.nix { } ``` -The attribute `testScript` is a bit of Python code that executes the +We refer to the whole test above as a test module, whereas the values +in [`nodes.<name>`](#opt-nodes) are NixOS modules themselves. + +The option [`testScript`](#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 attribute `nodes`. +the option [`nodes`](#opt-nodes). An example of a single-node test is [`login.nix`](https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix). @@ -34,7 +37,54 @@ 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. -There are a few special NixOS configuration options for test VMs: +## 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 instantiate the test by first importing the NixOS library, + +```nix +let nixos-lib = import (nixpkgs + "/nixos/lib") { }; +in + +nixos-lib.runTest { + imports = [ ./test.nix ]; + hostPkgs = pkgs; # the Nixpkgs package set used outside the VMs + defaults.services.foo.package = mypkg; +} +``` + +`runTest` 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` @@ -121,7 +171,7 @@ The following methods are available on machine objects: least one will be returned. ::: {.note} - This requires passing `enableOCR` to the test attribute set. + This requires [`enableOCR`](#opt-enableOCR) to be set to `true`. ::: `get_screen_text` @@ -130,7 +180,7 @@ The following methods are available on machine objects: machine\'s screen using optical character recognition. ::: {.note} - This requires passing `enableOCR` to the test attribute set. + This requires [`enableOCR`](#opt-enableOCR) to be set to `true`. ::: `send_monitor_command` @@ -241,7 +291,7 @@ The following methods are available on machine objects: `get_screen_text` and `get_screen_text_variants`). ::: {.note} - This requires passing `enableOCR` to the test attribute set. + This requires [`enableOCR`](#opt-enableOCR) to be set to `true`. ::: `wait_for_console_text` @@ -304,7 +354,7 @@ For faster dev cycles it\'s also possible to disable the code-linters (this shouldn\'t be commited though): ```nix -import ./make-test-python.nix { +{ skipLint = true; nodes.machine = { config, pkgs, ... }: @@ -336,7 +386,7 @@ Similarly, the type checking of test scripts can be disabled in the following way: ```nix -import ./make-test-python.nix { +{ skipTypeCheck = true; nodes.machine = { config, pkgs, ... }: @@ -400,7 +450,6 @@ added using the parameter `extraPythonPackages`. For example, you could add `numpy` like this: ```nix -import ./make-test-python.nix { extraPythonPackages = p: [ p.numpy ]; @@ -417,3 +466,11 @@ import ./make-test-python.nix ``` In that case, `numpy` is chosen from the generic `python3Packages`. + +## Test Options Reference {#sec-test-options-reference} + +The following options can be used when writing tests. + +```{=docbook} +<xi:include href="../../generated/test-options-db.xml" xpointer="test-options-list"/> +``` diff --git a/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml b/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml index 0e47350a0d2..35d9bbd1c1f 100644 --- a/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml +++ b/nixos/doc/manual/from_md/development/running-nixos-tests-interactively.section.xml @@ -25,15 +25,40 @@ $ ./result/bin/nixos-test-driver completion. This allows you to inspect the state of the VMs after the test (e.g. to debug the test script). </para> - <para> - You can re-use the VM states coming from a previous run by setting - the <literal>--keep-vm-state</literal> flag. - </para> - <programlisting> + <section xml:id="sec-nixos-test-reuse-vm-state"> + <title>Reuse VM state</title> + <para> + You can re-use the VM states coming from a previous run by setting + the <literal>--keep-vm-state</literal> flag. + </para> + <programlisting> $ ./result/bin/nixos-test-driver --keep-vm-state </programlisting> - <para> - The machine state is stored in the - <literal>$TMPDIR/vm-state-machinename</literal> directory. - </para> + <para> + The machine state is stored in the + <literal>$TMPDIR/vm-state-machinename</literal> directory. + </para> + </section> + <section xml:id="sec-nixos-test-interactive-configuration"> + <title>Interactive-only test configuration</title> + <para> + The <literal>.driverInteractive</literal> attribute combines the + regular test configuration with definitions from the + <link linkend="opt-interactive"><literal>interactive</literal> + submodule</link>. This gives you a more usable, graphical, but + slightly different configuration. + </para> + <para> + You can add your own interactive-only test configuration by adding + extra configuration to the + <link linkend="opt-interactive"><literal>interactive</literal> + submodule</link>. + </para> + <para> + To interactively run only the regular configuration, build the + <literal><test>.driver</literal> attribute instead, and call + it with the flag + <literal>result/bin/nixos-test-driver --interactive</literal>. + </para> + </section> </section> diff --git a/nixos/doc/manual/from_md/development/running-nixos-tests.section.xml b/nixos/doc/manual/from_md/development/running-nixos-tests.section.xml index da2e5076c95..23abb546899 100644 --- a/nixos/doc/manual/from_md/development/running-nixos-tests.section.xml +++ b/nixos/doc/manual/from_md/development/running-nixos-tests.section.xml @@ -4,22 +4,11 @@ You can run tests using <literal>nix-build</literal>. For example, to run the test <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/login.nix"><literal>login.nix</literal></link>, - you just do: + you do: </para> <programlisting> -$ nix-build '<nixpkgs/nixos/tests/login.nix>' -</programlisting> - <para> - or, if you don’t want to rely on <literal>NIX_PATH</literal>: - </para> - <programlisting> -$ cd /my/nixpkgs/nixos/tests -$ nix-build login.nix -… -running the VM test script -machine: QEMU running (pid 8841) -… -6 out of 6 tests succeeded +$ cd /my/git/clone/of/nixpkgs +$ nix-build -A nixosTests.login </programlisting> <para> After building/downloading all required dependencies, this will diff --git a/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml b/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml index d6f4f61c064..32f5fdb77f5 100644 --- a/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml +++ b/nixos/doc/manual/from_md/development/writing-nixos-tests.section.xml @@ -1,10 +1,10 @@ -<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-writing-nixos-tests"> +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" xml:id="sec-writing-nixos-tests"> <title>Writing Tests</title> <para> - A NixOS test is a Nix expression that has the following structure: + A NixOS test is a module that has the following structure: </para> <programlisting language="bash"> -import ./make-test-python.nix { +{ # One or more machines: nodes = @@ -22,10 +22,18 @@ import ./make-test-python.nix { } </programlisting> <para> - The attribute <literal>testScript</literal> is a bit 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 attribute <literal>nodes</literal>. + We refer to the whole test above as a test module, whereas the + values in + <link linkend="opt-nodes"><literal>nodes.<name></literal></link> + are NixOS modules themselves. + </para> + <para> + The option + <link linkend="opt-testScript"><literal>testScript</literal></link> + 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 + <link linkend="opt-nodes"><literal>nodes</literal></link>. </para> <para> An example of a single-node test is @@ -38,78 +46,138 @@ import ./make-test-python.nix { It uses two client nodes to test correct locking across server crashes. </para> - <para> - There are a few special NixOS configuration options for test VMs: - </para> - <variablelist> - <varlistentry> - <term> - <literal>virtualisation.memorySize</literal> - </term> - <listitem> - <para> - The memory of the VM in megabytes. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>virtualisation.vlans</literal> - </term> - <listitem> - <para> - The virtual networks to which the VM is connected. See - <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nat.nix"><literal>nat.nix</literal></link> - for an example. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>virtualisation.writableStore</literal> - </term> - <listitem> - <para> - 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. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - For more options, see the module - <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/qemu-vm.nix"><literal>qemu-vm.nix</literal></link>. - </para> - <para> - 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 <literal>name</literal> if this is also the - identifier of the machine in the declarative config. If you - specified a node <literal>nodes.machine</literal>, 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: - </para> - <programlisting language="python"> + <section xml:id="sec-calling-nixos-tests"> + <title>Calling a test</title> + <para> + Tests are invoked differently depending on whether the test is + part of NixOS or lives in a different project. + </para> + <section xml:id="sec-call-nixos-test-in-nixos"> + <title>Testing within NixOS</title> + <para> + Tests that are part of NixOS are added to + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/all-tests.nix"><literal>nixos/tests/all-tests.nix</literal></link>. + </para> + <programlisting language="bash"> + hostname = runTest ./hostname.nix; +</programlisting> + <para> + Overrides can be added by defining an anonymous module in + <literal>all-tests.nix</literal>. + </para> + <programlisting language="bash"> + hostname = runTest { + imports = [ ./hostname.nix ]; + defaults.networking.firewall.enable = false; + }; +</programlisting> + <para> + You can run a test with attribute name + <literal>hostname</literal> in + <literal>nixos/tests/all-tests.nix</literal> by invoking: + </para> + <programlisting> +cd /my/git/clone/of/nixpkgs +nix-build -A nixosTests.hostname +</programlisting> + </section> + <section xml:id="sec-call-nixos-test-outside-nixos"> + <title>Testing outside the NixOS project</title> + <para> + Outside the <literal>nixpkgs</literal> repository, you can + instantiate the test by first importing the NixOS library, + </para> + <programlisting language="bash"> +let nixos-lib = import (nixpkgs + "/nixos/lib") { }; +in + +nixos-lib.runTest { + imports = [ ./test.nix ]; + hostPkgs = pkgs; # the Nixpkgs package set used outside the VMs + defaults.services.foo.package = mypkg; +} +</programlisting> + <para> + <literal>runTest</literal> returns a derivation that runs the + test. + </para> + </section> + </section> + <section xml:id="sec-nixos-test-nodes"> + <title>Configuring the nodes</title> + <para> + There are a few special NixOS options for test VMs: + </para> + <variablelist> + <varlistentry> + <term> + <literal>virtualisation.memorySize</literal> + </term> + <listitem> + <para> + The memory of the VM in megabytes. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>virtualisation.vlans</literal> + </term> + <listitem> + <para> + The virtual networks to which the VM is connected. See + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/tests/nat.nix"><literal>nat.nix</literal></link> + for an example. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>virtualisation.writableStore</literal> + </term> + <listitem> + <para> + 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. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + For more options, see the module + <link xlink:href="https://github.com/NixOS/nixpkgs/blob/master/nixos/modules/virtualisation/qemu-vm.nix"><literal>qemu-vm.nix</literal></link>. + </para> + <para> + 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 <literal>name</literal> if this is also the + identifier of the machine in the declarative config. If you + specified a node <literal>nodes.machine</literal>, 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: + </para> + <programlisting language="python"> machine.start() machine.wait_for_unit("default.target") if not "Linux" in machine.succeed("uname"): raise Exception("Wrong OS") </programlisting> - <para> - The first line is technically unnecessary; machines are implicitly - started when you first execute an action on them (such as - <literal>wait_for_unit</literal> or <literal>succeed</literal>). If - you have multiple machines, you can speed up the test by starting - them in parallel: - </para> - <programlisting language="python"> + <para> + The first line is technically unnecessary; machines are implicitly + started when you first execute an action on them (such as + <literal>wait_for_unit</literal> or <literal>succeed</literal>). + If you have multiple machines, you can speed up the test by + starting them in parallel: + </para> + <programlisting language="python"> start_all() </programlisting> + </section> <section xml:id="ssec-machine-objects"> <title>Machine objects</title> <para> @@ -194,8 +262,9 @@ start_all() </para> <note> <para> - This requires passing <literal>enableOCR</literal> to the - test attribute set. + This requires + <link linkend="opt-enableOCR"><literal>enableOCR</literal></link> + to be set to <literal>true</literal>. </para> </note> </listitem> @@ -211,8 +280,9 @@ start_all() </para> <note> <para> - This requires passing <literal>enableOCR</literal> to the - test attribute set. + This requires + <link linkend="opt-enableOCR"><literal>enableOCR</literal></link> + to be set to <literal>true</literal>. </para> </note> </listitem> @@ -451,8 +521,9 @@ start_all() </para> <note> <para> - This requires passing <literal>enableOCR</literal> to the - test attribute set. + This requires + <link linkend="opt-enableOCR"><literal>enableOCR</literal></link> + to be set to <literal>true</literal>. </para> </note> </listitem> @@ -563,7 +634,7 @@ machine.wait_for_unit("xautolock.service", "x-session-user") code-linters (this shouldn't be commited though): </para> <programlisting language="bash"> -import ./make-test-python.nix { +{ skipLint = true; nodes.machine = { config, pkgs, ... }: @@ -595,7 +666,7 @@ import ./make-test-python.nix { the following way: </para> <programlisting language="bash"> -import ./make-test-python.nix { +{ skipTypeCheck = true; nodes.machine = { config, pkgs, ... }: @@ -669,7 +740,6 @@ def foo_running(): <literal>numpy</literal> like this: </para> <programlisting language="bash"> -import ./make-test-python.nix { extraPythonPackages = p: [ p.numpy ]; @@ -689,4 +759,11 @@ import ./make-test-python.nix <literal>python3Packages</literal>. </para> </section> + <section xml:id="sec-test-options-reference"> + <title>Test Options Reference</title> + <para> + The following options can be used when writing tests. + </para> + <xi:include href="../../generated/test-options-db.xml" xpointer="test-options-list"/> + </section> </section> diff --git a/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml index 566001c06bf..009b57bad86 100644 --- a/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml +++ b/nixos/doc/manual/from_md/release-notes/rl-2211.section.xml @@ -719,6 +719,21 @@ </listitem> <listitem> <para> + systemd-oomd is enabled by default. Depending on which systemd + units have <literal>ManagedOOMSwap=kill</literal> or + <literal>ManagedOOMMemoryPressure=kill</literal>, systemd-oomd + will SIGKILL all the processes under the appropriate + descendant cgroups when the configured limits are exceeded. + NixOS does currently not configure cgroups with oomd by + default, this can be enabled using + <link xlink:href="options.html#opt-systemd.oomd.enableRootSlice">systemd.oomd.enableRootSlice</link>, + <link xlink:href="options.html#opt-systemd.oomd.enableSystemSlice">systemd.oomd.enableSystemSlice</link>, + and + <link xlink:href="options.html#opt-systemd.oomd.enableUserServices">systemd.oomd.enableUserServices</link>. + </para> + </listitem> + <listitem> + <para> The <literal>pass-secret-service</literal> package now includes systemd units from upstream, so adding it to the NixOS <literal>services.dbus.packages</literal> option will diff --git a/nixos/doc/manual/release-notes/rl-2211.section.md b/nixos/doc/manual/release-notes/rl-2211.section.md index 8ab9f27edb9..b4e051a841f 100644 --- a/nixos/doc/manual/release-notes/rl-2211.section.md +++ b/nixos/doc/manual/release-notes/rl-2211.section.md @@ -235,6 +235,15 @@ Available as [services.patroni](options.html#opt-services.patroni.enable). - Add udev rules for the Teensy family of microcontrollers. +- systemd-oomd is enabled by default. Depending on which systemd units have + `ManagedOOMSwap=kill` or `ManagedOOMMemoryPressure=kill`, systemd-oomd will + SIGKILL all the processes under the appropriate descendant cgroups when the + configured limits are exceeded. NixOS does currently not configure cgroups + with oomd by default, this can be enabled using + [systemd.oomd.enableRootSlice](options.html#opt-systemd.oomd.enableRootSlice), + [systemd.oomd.enableSystemSlice](options.html#opt-systemd.oomd.enableSystemSlice), + and [systemd.oomd.enableUserServices](options.html#opt-systemd.oomd.enableUserServices). + - The `pass-secret-service` package now includes systemd units from upstream, so adding it to the NixOS `services.dbus.packages` option will make it start automatically as a systemd user service when an application tries to talk to the libsecret D-Bus API. - There is a new module for AMD SEV CPU functionality, which grants access to the hardware. |