diff options
Diffstat (limited to 'nixos/doc/manual')
25 files changed, 2435 insertions, 541 deletions
diff --git a/nixos/doc/manual/default.nix b/nixos/doc/manual/default.nix index 31b6da01c6bd0..e96bc47b4a53b 100644 --- a/nixos/doc/manual/default.nix +++ b/nixos/doc/manual/default.nix @@ -1,4 +1,13 @@ -{ pkgs, options, config, version, revision, extraSources ? [] }: +{ pkgs +, options +, config +, version +, revision +, extraSources ? [] +, baseOptionsJSON ? null +, warningsAreErrors ? true +, prefix ? ../../.. +}: with pkgs; @@ -11,11 +20,11 @@ let # # E.g. if some `options` came from modules in ${pkgs.customModules}/nix, # you'd need to include `extraSources = [ pkgs.customModules ]` - prefixesToStrip = map (p: "${toString p}/") ([ ../../.. ] ++ extraSources); + prefixesToStrip = map (p: "${toString p}/") ([ prefix ] ++ extraSources); stripAnyPrefixes = lib.flip (lib.foldr lib.removePrefix) prefixesToStrip; optionsDoc = buildPackages.nixosOptionsDoc { - inherit options revision; + inherit options revision baseOptionsJSON warningsAreErrors; transformOptions = opt: opt // { # Clean up declaration sites to not refer to the NixOS source tree. declarations = map stripAnyPrefixes opt.declarations; @@ -161,7 +170,7 @@ let in rec { inherit generatedSources; - inherit (optionsDoc) optionsJSON optionsDocBook; + inherit (optionsDoc) optionsJSON optionsNix optionsDocBook; # Generate the NixOS manual. manualHTML = runCommand "nixos-manual-html" @@ -205,7 +214,7 @@ in rec { manualEpub = runCommand "nixos-manual-epub" { inherit sources; - buildInputs = [ libxml2.bin libxslt.bin zip ]; + nativeBuildInputs = [ buildPackages.libxml2.bin buildPackages.libxslt.bin buildPackages.zip ]; } '' # Generate the epub manual. diff --git a/nixos/doc/manual/development/activation-script.section.md b/nixos/doc/manual/development/activation-script.section.md new file mode 100644 index 0000000000000..df6836624040e --- /dev/null +++ b/nixos/doc/manual/development/activation-script.section.md @@ -0,0 +1,72 @@ +# 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 incorperate 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 +possiblility 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 you 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 `ping` and `sudo` diff --git a/nixos/doc/manual/development/development.xml b/nixos/doc/manual/development/development.xml index 0b2ad60a878b0..21286cdbd2b46 100644 --- a/nixos/doc/manual/development/development.xml +++ b/nixos/doc/manual/development/development.xml @@ -12,6 +12,7 @@ <xi:include href="../from_md/development/sources.chapter.xml" /> <xi:include href="../from_md/development/writing-modules.chapter.xml" /> <xi:include href="../from_md/development/building-parts.chapter.xml" /> + <xi:include href="../from_md/development/what-happens-during-a-system-switch.chapter.xml" /> <xi:include href="../from_md/development/writing-documentation.chapter.xml" /> <xi:include href="../from_md/development/building-nixos.chapter.xml" /> <xi:include href="../from_md/development/nixos-tests.chapter.xml" /> diff --git a/nixos/doc/manual/development/meta-attributes.section.md b/nixos/doc/manual/development/meta-attributes.section.md index ca4ba007f7dc0..946c08efd0a35 100644 --- a/nixos/doc/manual/development/meta-attributes.section.md +++ b/nixos/doc/manual/development/meta-attributes.section.md @@ -5,7 +5,7 @@ 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` and `doc`. +meta-attributes are `maintainers`, `doc`, and `buildDocsInSandbox`. Each of the meta-attributes must be defined at most once per module file. @@ -24,6 +24,7 @@ file. meta = { maintainers = with lib.maintainers; [ ericsagnes ]; doc = ./default.xml; + buildDocsInSandbox = true; }; } ``` @@ -38,3 +39,28 @@ file. ```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 + `NIXOS_EXTRA_MODULE_PATH` 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). diff --git a/nixos/doc/manual/development/option-declarations.section.md b/nixos/doc/manual/development/option-declarations.section.md index be56529992ab1..fff06e1ea5ba7 100644 --- a/nixos/doc/manual/development/option-declarations.section.md +++ b/nixos/doc/manual/development/option-declarations.section.md @@ -57,6 +57,80 @@ The function `mkOption` accepts the following arguments. : A textual description of the option, in DocBook 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} +```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 shouldn’t necessarily make package options for all of your modules. You can always overwrite a specific package throughout nixpkgs by using [nixpkgs overlays](https://nixos.org/manual/nixpkgs/stable/#chap-overlays). + +The default package is specified as a list of strings representing its attribute path in nixpkgs. Because of this, you need to pass nixpkgs itself as the first argument. + +The second argument is the name of the option, used in the description "The \<name\> package to use.". You can also pass an example value, either a literal string or a package's attribute path. + +You can omit the default path if the name of the option is also attribute path in nixpkgs. + +::: {#ex-options-declarations-util-mkPackageOption .title} +Examples: + +::: {#ex-options-declarations-util-mkPackageOption-hello .example} +```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} +```nix +lib.mkPackageOption pkgs "GHC" { + default = [ "ghc" ]; + example = "pkgs.haskell.package.ghc921.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.haskell.package.ghc921.ghc.withPackages (hkgs: [ hkgs.primes ])"; + description = "The GHC package to use."; +} +``` + ## Extensible Option Types {#sec-option-declarations-eot} Extensible option types is a feature that allow to extend certain types diff --git a/nixos/doc/manual/development/option-types.section.md b/nixos/doc/manual/development/option-types.section.md index ed557206659f8..56ffa8e9d79c4 100644 --- a/nixos/doc/manual/development/option-types.section.md +++ b/nixos/doc/manual/development/option-types.section.md @@ -250,6 +250,12 @@ Composed types are types that take a type as parameter. `listOf : Ensures that type *`t`* cannot be merged. It is used to ensure option definitions are declared 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.either` *`t1 t2`* : Type *`t1`* or type *`t2`*, e.g. `with types; either int str`. 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 f872982017916..a1431859ff593 100644 --- a/nixos/doc/manual/development/running-nixos-tests-interactively.section.md +++ b/nixos/doc/manual/development/running-nixos-tests-interactively.section.md @@ -4,19 +4,19 @@ The test itself can be run interactively. This is particularly useful when developing or debugging a test: ```ShellSession -$ nix-build nixos/tests/login.nix -A driverInteractive -$ ./result/bin/nixos-test-driver --interactive -starting VDE switch for network 1 -> +$ nix-build . -A nixosTests.login.driverInteractive +$ ./result/bin/nixos-test-driver +[...] +>>> ``` 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 +>>> 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 @@ -28,7 +28,7 @@ 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 --interactive --keep-vm-state +$ ./result/bin/nixos-test-driver --keep-vm-state ``` The machine state is stored in the `$TMPDIR/vm-state-machinename` diff --git a/nixos/doc/manual/development/unit-handling.section.md b/nixos/doc/manual/development/unit-handling.section.md new file mode 100644 index 0000000000000..d477f2c860f35 --- /dev/null +++ b/nixos/doc/manual/development/unit-handling.section.md @@ -0,0 +1,57 @@ +# 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). 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. These mostly come from the `/etc/fstab` + parser. + + - `.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)). + + - 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. + + - The rest of the behavior is decided whether the unit has `X-StopIfChanged` + in the `[Service]` section set (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. + + - The last thing that is taken into account is whether the unit is a service + and socket-activated. Due to a bug, this is currently only done when + `X-StopIfChanged` is set. If the unit is socket-activated, the socket is + stopped and started, and the service is stopped and to be started by socket + activation. diff --git a/nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md b/nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md new file mode 100644 index 0000000000000..aad82831a3c24 --- /dev/null +++ b/nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md @@ -0,0 +1,53 @@ +# 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 a new mount is added, for example, the proper `.mount` unit is +marked to be started. 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`) +- Set up tmpfiles (`systemd-tmpfiles --create`) +- 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 + +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. + +```{=docbook} +<xi:include href="unit-handling.section.xml" /> +<xi:include href="activation-script.section.xml" /> +``` diff --git a/nixos/doc/manual/development/writing-nixos-tests.section.md b/nixos/doc/manual/development/writing-nixos-tests.section.md index d9749d37da79f..7de57d0d2a379 100644 --- a/nixos/doc/manual/development/writing-nixos-tests.section.md +++ b/nixos/doc/manual/development/writing-nixos-tests.section.md @@ -88,6 +88,8 @@ starting them in parallel: start_all() ``` +## Machine objects {#ssec-machine-objects} + The following methods are available on machine objects: `start` @@ -313,3 +315,52 @@ repository): # fmt: on ''; ``` + +## Failing tests early {#ssec-failing-tests-early} + +To fail tests early when certain invariables 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") + ``` diff --git a/nixos/doc/manual/from_md/development/activation-script.section.xml b/nixos/doc/manual/from_md/development/activation-script.section.xml new file mode 100644 index 0000000000000..0d9e911216efa --- /dev/null +++ b/nixos/doc/manual/from_md/development/activation-script.section.xml @@ -0,0 +1,150 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-activation-script"> + <title>Activation script</title> + <para> + The activation script is a bash script called to activate the new + configuration which resides in a NixOS system in + <literal>$out/activate</literal>. 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 + <literal>StateDirectory</literal>, + <literal>CacheDirectory</literal>, … or if that’s not possible using + <literal>preStart</literal> of the service). + </para> + <para> + Activation scripts are defined as snippets using + <xref linkend="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: + </para> + <programlisting language="bash"> +system.activationScripts.my-activation-script = { + deps = [ "etc" ]; + # supportsDryActivation = true; + text = '' + echo "Hallo i bims" + ''; +}; +</programlisting> + <para> + This example creates an activation script snippet that is run after + the <literal>etc</literal> snippet. The special variable + <literal>supportsDryActivation</literal> can be set so the snippet + is also run when <literal>nixos-rebuild dry-activate</literal> is + run. To differentiate between real and dry activation, the + <literal>$NIXOS_ACTION</literal> environment variable can be read + which is set to <literal>dry-activate</literal> when a dry + activation is done. + </para> + <para> + An activation script can write to special files instructing + <literal>switch-to-configuration</literal> to restart/reload units. + The script will take these requests into account and will + incorperate the unit configuration as described above. This means + that the activation script will <quote>fake</quote> a modified unit + file and <literal>switch-to-configuration</literal> will act + accordingly. By doing so, configuration like + <link linkend="opt-systemd.services">systemd.services.<name>.restartIfChanged</link> + is respected. Since the activation script is run + <emphasis role="strong">after</emphasis> services are already + stopped, + <link linkend="opt-systemd.services">systemd.services.<name>.stopIfChanged</link> + cannot be taken into account anymore and the unit is always + restarted instead of being stopped and started afterwards. + </para> + <para> + The files that can be written to are + <literal>/run/nixos/activation-restart-list</literal> and + <literal>/run/nixos/activation-reload-list</literal> with their + respective counterparts for dry activation being + <literal>/run/nixos/dry-activation-restart-list</literal> and + <literal>/run/nixos/dry-activation-reload-list</literal>. 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 possiblility into + account that they have to create them first. + </para> + <section xml:id="sec-activation-script-nixos-snippets"> + <title>NixOS snippets</title> + <para> + There are some snippets NixOS enables by default because disabling + them would most likely break you system. This section lists a few + of them and what they do: + </para> + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>binsh</literal> creates <literal>/bin/sh</literal> + which points to the runtime shell + </para> + </listitem> + <listitem> + <para> + <literal>etc</literal> sets up the contents of + <literal>/etc</literal>, this includes systemd units and + excludes <literal>/etc/passwd</literal>, + <literal>/etc/group</literal>, and + <literal>/etc/shadow</literal> (which are managed by the + <literal>users</literal> snippet) + </para> + </listitem> + <listitem> + <para> + <literal>hostname</literal> sets the system’s hostname in the + kernel (not in <literal>/etc</literal>) + </para> + </listitem> + <listitem> + <para> + <literal>modprobe</literal> sets the path to the + <literal>modprobe</literal> binary for module auto-loading + </para> + </listitem> + <listitem> + <para> + <literal>nix</literal> prepares the nix store and adds a + default initial channel + </para> + </listitem> + <listitem> + <para> + <literal>specialfs</literal> is responsible for mounting + filesystems like <literal>/proc</literal> and + <literal>sys</literal> + </para> + </listitem> + <listitem> + <para> + <literal>users</literal> creates and removes users and groups + by managing <literal>/etc/passwd</literal>, + <literal>/etc/group</literal> and + <literal>/etc/shadow</literal>. This also creates home + directories + </para> + </listitem> + <listitem> + <para> + <literal>usrbinenv</literal> creates + <literal>/usr/bin/env</literal> + </para> + </listitem> + <listitem> + <para> + <literal>var</literal> creates some directories in + <literal>/var</literal> that are not service-specific + </para> + </listitem> + <listitem> + <para> + <literal>wrappers</literal> creates setuid wrappers like + <literal>ping</literal> and <literal>sudo</literal> + </para> + </listitem> + </itemizedlist> + </section> +</section> diff --git a/nixos/doc/manual/from_md/development/meta-attributes.section.xml b/nixos/doc/manual/from_md/development/meta-attributes.section.xml index f535d94602bd7..1eb6e0f303682 100644 --- a/nixos/doc/manual/from_md/development/meta-attributes.section.xml +++ b/nixos/doc/manual/from_md/development/meta-attributes.section.xml @@ -8,8 +8,8 @@ <para> <literal>meta</literal> is a top level attribute like <literal>options</literal> and <literal>config</literal>. Available - meta-attributes are <literal>maintainers</literal> and - <literal>doc</literal>. + meta-attributes are <literal>maintainers</literal>, + <literal>doc</literal>, and <literal>buildDocsInSandbox</literal>. </para> <para> Each of the meta-attributes must be defined at most once per module @@ -29,6 +29,7 @@ meta = { maintainers = with lib.maintainers; [ ericsagnes ]; doc = ./default.xml; + buildDocsInSandbox = true; }; } </programlisting> @@ -51,5 +52,44 @@ $ nix-build nixos/release.nix -A manual.x86_64-linux </programlisting> </listitem> + <listitem> + <para> + <literal>buildDocsInSandbox</literal> 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 + <literal>NIXOS_EXTRA_MODULE_PATH</literal> are always built + outside of the sandbox, as has been the case in previous + releases. + </para> + <para> + 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 <literal>options</literal> and + <literal>lib</literal> module arguments and the + <literal>pkgs.formats</literal> attribute of the + <literal>pkgs</literal> argument, <literal>config</literal> and + the rest of <literal>pkgs</literal> 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 <literal>options</literal> + 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. + </para> + <para> + The default is <literal>true</literal> and should usually not be + changed; set it to <literal>false</literal> only if the module + requires access to <literal>pkgs</literal> 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). + </para> + </listitem> </itemizedlist> </section> diff --git a/nixos/doc/manual/from_md/development/option-declarations.section.xml b/nixos/doc/manual/from_md/development/option-declarations.section.xml index 2845e37659b1b..0eeffae628e1a 100644 --- a/nixos/doc/manual/from_md/development/option-declarations.section.xml +++ b/nixos/doc/manual/from_md/development/option-declarations.section.xml @@ -97,125 +97,228 @@ options = { </listitem> </varlistentry> </variablelist> - <section xml:id="sec-option-declarations-eot"> - <title>Extensible Option Types</title> - <para> - Extensible option types is a feature that allow to extend certain - types declaration through multiple module files. This feature only - work with a restricted set of types, namely - <literal>enum</literal> and <literal>submodules</literal> and any - composed forms of them. - </para> - <para> - Extensible option types can be used for <literal>enum</literal> - options that affects multiple modules, or as an alternative to - related <literal>enable</literal> options. - </para> - <para> - 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 - ...). - </para> - <para> - There are two approach to this module structure: - </para> - <itemizedlist> - <listitem> + <section xml:id="sec-option-declarations-util"> + <title>Utility functions for common option patterns</title> + <section xml:id="sec-option-declarations-util-mkEnableOption"> + <title><literal>mkEnableOption</literal></title> + <para> + Creates an Option attribute set for a boolean value option i.e + an option to be toggled on or off. + </para> + <para> + This function takes a single string argument, the name of the + thing to be toggled. + </para> + <para> + The option’s description is <quote>Whether to enable + <name>.</quote>. + </para> + <para> + For example: + </para> + <anchor xml:id="ex-options-declarations-util-mkEnableOption-magic" /> + <programlisting language="bash"> +lib.mkEnableOption "magic" +# is like +lib.mkOption { + type = lib.types.bool; + default = false; + example = true; + description = "Whether to enable magic."; +} +</programlisting> + <section xml:id="sec-option-declarations-util-mkPackageOption"> + <title><literal>mkPackageOption</literal></title> <para> - Managing the display managers independently by adding an - enable option to every display manager module backend. (NixOS) + Usage: </para> - </listitem> - <listitem> + <programlisting language="bash"> +mkPackageOption pkgs "name" { default = [ "path" "in" "pkgs" ]; example = "literal example"; } +</programlisting> <para> - Managing the display managers in the central module by adding - an option to select which display manager backend to use. + Creates an Option attribute set for an option that specifies + the package a module should use for some purpose. </para> - </listitem> - </itemizedlist> - <para> - Both approaches have problems. - </para> - <para> - Making backends independent can quickly become hard to manage. For - display managers, there can be only one enabled at a time, but the - type system can not enforce this restriction as there is no - relation between each backend <literal>enable</literal> option. As - a result, this restriction has to be done explicitely by adding - assertions in each display manager backend module. - </para> - <para> - On the other hand, managing the display managers backends in the - central module will require to change the central module option - every time a new backend is added or removed. - </para> - <para> - By using extensible option types, it is possible to create a - placeholder option in the central module - (<link linkend="ex-option-declaration-eot-service">Example: - Extensible type placeholder in the service module</link>), and to - extend it in each backend module - (<link linkend="ex-option-declaration-eot-backend-gdm">Example: - Extending - <literal>services.xserver.displayManager.enable</literal> in the - <literal>gdm</literal> module</link>, - <link linkend="ex-option-declaration-eot-backend-sddm">Example: - Extending - <literal>services.xserver.displayManager.enable</literal> in the - <literal>sddm</literal> module</link>). - </para> - <para> - As a result, <literal>displayManager.enable</literal> option - values can be added without changing the main service module file - and the type system automatically enforce that there can only be a - single display manager enabled. - </para> - <anchor xml:id="ex-option-declaration-eot-service" /> - <para> - <emphasis role="strong">Example: Extensible type placeholder in - the service module</emphasis> - </para> - <programlisting language="bash"> + <para> + <emphasis role="strong">Note</emphasis>: You shouldn’t + necessarily make package options for all of your modules. You + can always overwrite a specific package throughout nixpkgs by + using + <link xlink:href="https://nixos.org/manual/nixpkgs/stable/#chap-overlays">nixpkgs + overlays</link>. + </para> + <para> + The default package is specified as a list of strings + representing its attribute path in nixpkgs. Because of this, + you need to pass nixpkgs itself as the first argument. + </para> + <para> + The second argument is the name of the option, used in the + description <quote>The <name> package to use.</quote>. + You can also pass an example value, either a literal string or + a package’s attribute path. + </para> + <para> + You can omit the default path if the name of the option is + also attribute path in nixpkgs. + </para> + <anchor xml:id="ex-options-declarations-util-mkPackageOption" /> + <para> + Examples: + </para> + <anchor xml:id="ex-options-declarations-util-mkPackageOption-hello" /> + <programlisting language="bash"> +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."; +} +</programlisting> + <anchor xml:id="ex-options-declarations-util-mkPackageOption-ghc" /> + <programlisting language="bash"> +lib.mkPackageOption pkgs "GHC" { + default = [ "ghc" ]; + example = "pkgs.haskell.package.ghc921.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.haskell.package.ghc921.ghc.withPackages (hkgs: [ hkgs.primes ])"; + description = "The GHC package to use."; +} +</programlisting> + <section xml:id="sec-option-declarations-eot"> + <title>Extensible Option Types</title> + <para> + Extensible option types is a feature that allow to extend + certain types declaration through multiple module files. + This feature only work with a restricted set of types, + namely <literal>enum</literal> and + <literal>submodules</literal> and any composed forms of + them. + </para> + <para> + Extensible option types can be used for + <literal>enum</literal> options that affects multiple + modules, or as an alternative to related + <literal>enable</literal> options. + </para> + <para> + 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 ...). + </para> + <para> + There are two approach to this module structure: + </para> + <itemizedlist> + <listitem> + <para> + Managing the display managers independently by adding an + enable option to every display manager module backend. + (NixOS) + </para> + </listitem> + <listitem> + <para> + Managing the display managers in the central module by + adding an option to select which display manager backend + to use. + </para> + </listitem> + </itemizedlist> + <para> + Both approaches have problems. + </para> + <para> + Making backends independent can quickly become hard to + manage. For display managers, there can be only one enabled + at a time, but the type system can not enforce this + restriction as there is no relation between each backend + <literal>enable</literal> option. As a result, this + restriction has to be done explicitely by adding assertions + in each display manager backend module. + </para> + <para> + On the other hand, managing the display managers backends in + the central module will require to change the central module + option every time a new backend is added or removed. + </para> + <para> + By using extensible option types, it is possible to create a + placeholder option in the central module + (<link linkend="ex-option-declaration-eot-service">Example: + Extensible type placeholder in the service module</link>), + and to extend it in each backend module + (<link linkend="ex-option-declaration-eot-backend-gdm">Example: + Extending + <literal>services.xserver.displayManager.enable</literal> in + the <literal>gdm</literal> module</link>, + <link linkend="ex-option-declaration-eot-backend-sddm">Example: + Extending + <literal>services.xserver.displayManager.enable</literal> in + the <literal>sddm</literal> module</link>). + </para> + <para> + As a result, <literal>displayManager.enable</literal> option + values can be added without changing the main service module + file and the type system automatically enforce that there + can only be a single display manager enabled. + </para> + <anchor xml:id="ex-option-declaration-eot-service" /> + <para> + <emphasis role="strong">Example: Extensible type placeholder + in the service module</emphasis> + </para> + <programlisting language="bash"> services.xserver.displayManager.enable = mkOption { description = "Display manager to use"; type = with types; nullOr (enum [ ]); }; </programlisting> - <anchor xml:id="ex-option-declaration-eot-backend-gdm" /> - <para> - <emphasis role="strong">Example: Extending - <literal>services.xserver.displayManager.enable</literal> in the - <literal>gdm</literal> module</emphasis> - </para> - <programlisting language="bash"> + <anchor xml:id="ex-option-declaration-eot-backend-gdm" /> + <para> + <emphasis role="strong">Example: Extending + <literal>services.xserver.displayManager.enable</literal> in + the <literal>gdm</literal> module</emphasis> + </para> + <programlisting language="bash"> services.xserver.displayManager.enable = mkOption { type = with types; nullOr (enum [ "gdm" ]); }; </programlisting> - <anchor xml:id="ex-option-declaration-eot-backend-sddm" /> - <para> - <emphasis role="strong">Example: Extending - <literal>services.xserver.displayManager.enable</literal> in the - <literal>sddm</literal> module</emphasis> - </para> - <programlisting language="bash"> + <anchor xml:id="ex-option-declaration-eot-backend-sddm" /> + <para> + <emphasis role="strong">Example: Extending + <literal>services.xserver.displayManager.enable</literal> in + the <literal>sddm</literal> module</emphasis> + </para> + <programlisting language="bash"> services.xserver.displayManager.enable = mkOption { type = with types; nullOr (enum [ "sddm" ]); }; </programlisting> - <para> - The placeholder declaration is a standard - <literal>mkOption</literal> declaration, but it is important that - extensible option declarations only use the - <literal>type</literal> argument. - </para> - <para> - Extensible option types work with any of the composed variants of - <literal>enum</literal> such as - <literal>with types; nullOr (enum [ "foo" "bar" ])</literal> - or - <literal>with types; listOf (enum [ "foo" "bar" ])</literal>. - </para> + <para> + The placeholder declaration is a standard + <literal>mkOption</literal> declaration, but it is important + that extensible option declarations only use the + <literal>type</literal> argument. + </para> + <para> + Extensible option types work with any of the composed + variants of <literal>enum</literal> such as + <literal>with types; nullOr (enum [ "foo" "bar" ])</literal> + or + <literal>with types; listOf (enum [ "foo" "bar" ])</literal>. + </para> + </section> + </section> + </section> </section> </section> diff --git a/nixos/doc/manual/from_md/development/option-types.section.xml b/nixos/doc/manual/from_md/development/option-types.section.xml index c83ffa2add535..76ffb6f837c35 100644 --- a/nixos/doc/manual/from_md/development/option-types.section.xml +++ b/nixos/doc/manual/from_md/development/option-types.section.xml @@ -498,6 +498,22 @@ </varlistentry> <varlistentry> <term> + <literal>types.unique</literal> + <literal>{ message = m }</literal> + <emphasis><literal>t</literal></emphasis> + </term> + <listitem> + <para> + Ensures that type <emphasis><literal>t</literal></emphasis> + cannot be merged. Prints the message + <emphasis><literal>m</literal></emphasis>, after the line + <literal>The option <option path> is defined multiple times.</literal> + and before a list of definition locations. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> <literal>types.either</literal> <emphasis><literal>t1 t2</literal></emphasis> </term> 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 17003cbcbfdca..0e47350a0d24f 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 @@ -5,19 +5,19 @@ useful when developing or debugging a test: </para> <programlisting> -$ nix-build nixos/tests/login.nix -A driverInteractive -$ ./result/bin/nixos-test-driver --interactive -starting VDE switch for network 1 -> +$ nix-build . -A nixosTests.login.driverInteractive +$ ./result/bin/nixos-test-driver +[...] +>>> </programlisting> <para> You can then take any Python statement, e.g. </para> <programlisting language="python"> -> start_all() -> test_script() -> machine.succeed("touch /tmp/foo") -> print(machine.succeed("pwd")) # Show stdout of command +>>> start_all() +>>> test_script() +>>> machine.succeed("touch /tmp/foo") +>>> print(machine.succeed("pwd")) # Show stdout of command </programlisting> <para> The function <literal>test_script</literal> executes the entire test @@ -30,7 +30,7 @@ starting VDE switch for network 1 the <literal>--keep-vm-state</literal> flag. </para> <programlisting> -$ ./result/bin/nixos-test-driver --interactive --keep-vm-state +$ ./result/bin/nixos-test-driver --keep-vm-state </programlisting> <para> The machine state is stored in the diff --git a/nixos/doc/manual/from_md/development/unit-handling.section.xml b/nixos/doc/manual/from_md/development/unit-handling.section.xml new file mode 100644 index 0000000000000..a6a654042f6fc --- /dev/null +++ b/nixos/doc/manual/from_md/development/unit-handling.section.xml @@ -0,0 +1,119 @@ +<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-unit-handling"> + <title>Unit handling</title> + <para> + 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 + <literal>systemctl list-units</literal> shows. For each of the + units, the script goes through the following checks: + </para> + <itemizedlist> + <listitem> + <para> + Is the unit file still in the new system? If not, + <emphasis role="strong">stop</emphasis> the service unless it + sets <literal>X-StopOnRemoval</literal> in the + <literal>[Unit]</literal> section to <literal>false</literal>. + </para> + </listitem> + <listitem> + <para> + Is it a <literal>.target</literal> unit? If so, + <emphasis role="strong">start</emphasis> it unless it sets + <literal>RefuseManualStart</literal> in the + <literal>[Unit]</literal> section to <literal>true</literal> or + <literal>X-OnlyManualStart</literal> in the + <literal>[Unit]</literal> section to <literal>true</literal>. + Also <emphasis role="strong">stop</emphasis> the unit again + unless it sets <literal>X-StopOnReconfiguration</literal> to + <literal>false</literal>. + </para> + </listitem> + <listitem> + <para> + Are the contents of the unit files different? They are compared + by parsing them and comparing their contents. If they are + different but only <literal>X-Reload-Triggers</literal> in the + <literal>[Unit]</literal> section is changed, + <emphasis role="strong">reload</emphasis> the unit. The NixOS + module system allows setting these triggers with the option + <link linkend="opt-systemd.services">systemd.services.<name>.reloadTriggers</link>. + If the unit files differ in any way, the following actions are + performed: + </para> + <itemizedlist> + <listitem> + <para> + <literal>.path</literal> and <literal>.slice</literal> units + are ignored. There is no need to restart them since changes + in their values are applied by systemd when systemd is + reloaded. + </para> + </listitem> + <listitem> + <para> + <literal>.mount</literal> units are + <emphasis role="strong">reload</emphasis>ed. These mostly + come from the <literal>/etc/fstab</literal> parser. + </para> + </listitem> + <listitem> + <para> + <literal>.socket</literal> units are currently ignored. This + is to be fixed at a later point. + </para> + </listitem> + <listitem> + <para> + The rest of the units (mostly <literal>.service</literal> + units) are then <emphasis role="strong">reload</emphasis>ed + if <literal>X-ReloadIfChanged</literal> in the + <literal>[Service]</literal> section is set to + <literal>true</literal> (exposed via + <link linkend="opt-systemd.services">systemd.services.<name>.reloadIfChanged</link>). + </para> + </listitem> + <listitem> + <para> + If the reload flag is not set, some more flags decide if the + unit is skipped. These flags are + <literal>X-RestartIfChanged</literal> in the + <literal>[Service]</literal> section (exposed via + <link linkend="opt-systemd.services">systemd.services.<name>.restartIfChanged</link>), + <literal>RefuseManualStop</literal> in the + <literal>[Unit]</literal> section, and + <literal>X-OnlyManualStart</literal> in the + <literal>[Unit]</literal> section. + </para> + </listitem> + <listitem> + <para> + The rest of the behavior is decided whether the unit has + <literal>X-StopIfChanged</literal> in the + <literal>[Service]</literal> section set (exposed via + <link linkend="opt-systemd.services">systemd.services.<name>.stopIfChanged</link>). + This is set to <literal>true</literal> by default and must + be explicitly turned off if not wanted. If the flag is + enabled, the unit is + <emphasis role="strong">stop</emphasis>ped and then + <emphasis role="strong">start</emphasis>ed. If not, the unit + is <emphasis role="strong">restart</emphasis>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. + </para> + </listitem> + <listitem> + <para> + The last thing that is taken into account is whether the + unit is a service and socket-activated. Due to a bug, this + is currently only done when + <literal>X-StopIfChanged</literal> is set. If the unit is + socket-activated, the socket is stopped and started, and the + service is stopped and to be started by socket activation. + </para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> +</section> diff --git a/nixos/doc/manual/from_md/development/what-happens-during-a-system-switch.chapter.xml b/nixos/doc/manual/from_md/development/what-happens-during-a-system-switch.chapter.xml new file mode 100644 index 0000000000000..66ba792ddacb4 --- /dev/null +++ b/nixos/doc/manual/from_md/development/what-happens-during-a-system-switch.chapter.xml @@ -0,0 +1,122 @@ +<chapter 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-switching-systems"> + <title>What happens during a system switch?</title> + <para> + Running <literal>nixos-rebuild switch</literal> 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. + </para> + <para> + <literal>nixos-rebuild</literal>, like many deployment solutions, + calls <literal>switch-to-configuration</literal> which resides in a + NixOS system at <literal>$out/bin/switch-to-configuration</literal>. + The script is called with the action that is to be performed like + <literal>switch</literal>, <literal>test</literal>, + <literal>boot</literal>. There is also the + <literal>dry-activate</literal> action which does not really perform + the actions but rather prints what it would do if you called it with + <literal>test</literal>. This feature can be used to check what + service states would be changed if the configuration was switched + to. + </para> + <para> + If the action is <literal>switch</literal> or + <literal>boot</literal>, the bootloader is updated first so the + configuration will be the next one to boot. Unless + <literal>NIXOS_NO_SYNC</literal> is set to <literal>1</literal>, + <literal>/nix/store</literal> is synced to disk. + </para> + <para> + If the action is <literal>switch</literal> or + <literal>test</literal>, 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: + <literal>/etc/fstab</literal> and the current systemd status. Mounts + and swaps are read from <literal>/etc/fstab</literal> and the + corresponding actions are generated. If a new mount is added, for + example, the proper <literal>.mount</literal> unit is marked to be + started. 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. + </para> + <para> + After calculating what should be done, the actions are carried out. + The order of actions is always the same: + </para> + <itemizedlist spacing="compact"> + <listitem> + <para> + Stop units (<literal>systemctl stop</literal>) + </para> + </listitem> + <listitem> + <para> + Run activation script (<literal>$out/activate</literal>) + </para> + </listitem> + <listitem> + <para> + See if the activation script requested more units to restart + </para> + </listitem> + <listitem> + <para> + Restart systemd if needed + (<literal>systemd daemon-reexec</literal>) + </para> + </listitem> + <listitem> + <para> + Forget about the failed state of units + (<literal>systemctl reset-failed</literal>) + </para> + </listitem> + <listitem> + <para> + Reload systemd (<literal>systemctl daemon-reload</literal>) + </para> + </listitem> + <listitem> + <para> + Reload systemd user instances + (<literal>systemctl --user daemon-reload</literal>) + </para> + </listitem> + <listitem> + <para> + Set up tmpfiles (<literal>systemd-tmpfiles --create</literal>) + </para> + </listitem> + <listitem> + <para> + Reload units (<literal>systemctl reload</literal>) + </para> + </listitem> + <listitem> + <para> + Restart units (<literal>systemctl restart</literal>) + </para> + </listitem> + <listitem> + <para> + Start units (<literal>systemctl start</literal>) + </para> + </listitem> + <listitem> + <para> + Inspect what changed during these actions and print units that + failed and that were newly started + </para> + </listitem> + </itemizedlist> + <para> + 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. + </para> + <xi:include href="unit-handling.section.xml" /> + <xi:include href="activation-script.section.xml" /> +</chapter> 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 0d523681b6393..45c9c40c6095c 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 @@ -117,407 +117,413 @@ if not "Linux" in machine.succeed("uname"): <programlisting language="python"> start_all() </programlisting> - <para> - The following methods are available on machine objects: - </para> - <variablelist> - <varlistentry> - <term> - <literal>start</literal> - </term> - <listitem> - <para> - Start the virtual machine. This method is asynchronous — it - does not wait for the machine to finish booting. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>shutdown</literal> - </term> - <listitem> - <para> - Shut down the machine, waiting for the VM to exit. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>crash</literal> - </term> - <listitem> - <para> - Simulate a sudden power failure, by telling the VM to exit - immediately. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>block</literal> - </term> - <listitem> - <para> - Simulate unplugging the Ethernet cable that connects the - machine to the other machines. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>unblock</literal> - </term> - <listitem> - <para> - Undo the effect of <literal>block</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>screenshot</literal> - </term> - <listitem> - <para> - Take a picture of the display of the virtual machine, in PNG - format. The screenshot is linked from the HTML log. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>get_screen_text_variants</literal> - </term> - <listitem> - <para> - Return a list of different interpretations of what is - currently visible on the machine's screen using optical - character recognition. The number and order of the - interpretations is not specified and is subject to change, but - if no exception is raised at least one will be returned. - </para> - <note> + <section xml:id="ssec-machine-objects"> + <title>Machine objects</title> + <para> + The following methods are available on machine objects: + </para> + <variablelist> + <varlistentry> + <term> + <literal>start</literal> + </term> + <listitem> <para> - This requires passing <literal>enableOCR</literal> to the - test attribute set. + Start the virtual machine. This method is asynchronous — it + does not wait for the machine to finish booting. </para> - </note> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>get_screen_text</literal> - </term> - <listitem> - <para> - Return a textual representation of what is currently visible - on the machine's screen using optical character recognition. - </para> - <note> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>shutdown</literal> + </term> + <listitem> <para> - This requires passing <literal>enableOCR</literal> to the - test attribute set. + Shut down the machine, waiting for the VM to exit. </para> - </note> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>send_monitor_command</literal> - </term> - <listitem> - <para> - Send a command to the QEMU monitor. This is rarely used, but - allows doing stuff such as attaching virtual USB disks to a - running machine. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>send_key</literal> - </term> - <listitem> - <para> - Simulate pressing keys on the virtual keyboard, e.g., - <literal>send_key("ctrl-alt-delete")</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>send_chars</literal> - </term> - <listitem> - <para> - Simulate typing a sequence of characters on the virtual - keyboard, e.g., - <literal>send_chars("foobar\n")</literal> will type - the string <literal>foobar</literal> followed by the Enter - key. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>execute</literal> - </term> - <listitem> - <para> - Execute a shell command, returning a list - <literal>(status, stdout)</literal>. If the command detaches, - it must close stdout, as <literal>execute</literal> will wait - for this to consume all output reliably. This can be achieved - by redirecting stdout to stderr <literal>>&2</literal>, - to <literal>/dev/console</literal>, - <literal>/dev/null</literal> or a file. Examples of detaching - commands are <literal>sleep 365d &</literal>, where the - shell forks a new process that can write to stdout and - <literal>xclip -i</literal>, where the - <literal>xclip</literal> command itself forks without closing - stdout. Takes an optional parameter - <literal>check_return</literal> that defaults to - <literal>True</literal>. Setting this parameter to - <literal>False</literal> will not check for the return code - and return -1 instead. This can be used for commands that shut - down the VM and would therefore break the pipe that would be - used for retrieving the return code. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>succeed</literal> - </term> - <listitem> - <para> - Execute a shell command, raising an exception if the exit - status is not zero, otherwise returning the standard output. - Commands are run with <literal>set -euo pipefail</literal> - set: - </para> - <itemizedlist> - <listitem> - <para> - If several commands are separated by <literal>;</literal> - and one fails, the command as a whole will fail. - </para> - </listitem> - <listitem> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>crash</literal> + </term> + <listitem> + <para> + Simulate a sudden power failure, by telling the VM to exit + immediately. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>block</literal> + </term> + <listitem> + <para> + Simulate unplugging the Ethernet cable that connects the + machine to the other machines. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>unblock</literal> + </term> + <listitem> + <para> + Undo the effect of <literal>block</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>screenshot</literal> + </term> + <listitem> + <para> + Take a picture of the display of the virtual machine, in PNG + format. The screenshot is linked from the HTML log. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>get_screen_text_variants</literal> + </term> + <listitem> + <para> + Return a list of different interpretations of what is + currently visible on the machine's screen using optical + character recognition. The number and order of the + interpretations is not specified and is subject to change, + but if no exception is raised at least one will be returned. + </para> + <note> <para> - For pipelines, the last non-zero exit status will be - returned (if there is one, zero will be returned - otherwise). + This requires passing <literal>enableOCR</literal> to the + test attribute set. </para> - </listitem> - <listitem> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>get_screen_text</literal> + </term> + <listitem> + <para> + Return a textual representation of what is currently visible + on the machine's screen using optical character recognition. + </para> + <note> <para> - Dereferencing unset variables fail the command. + This requires passing <literal>enableOCR</literal> to the + test attribute set. </para> - </listitem> - <listitem> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>send_monitor_command</literal> + </term> + <listitem> + <para> + Send a command to the QEMU monitor. This is rarely used, but + allows doing stuff such as attaching virtual USB disks to a + running machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>send_key</literal> + </term> + <listitem> + <para> + Simulate pressing keys on the virtual keyboard, e.g., + <literal>send_key("ctrl-alt-delete")</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>send_chars</literal> + </term> + <listitem> + <para> + Simulate typing a sequence of characters on the virtual + keyboard, e.g., + <literal>send_chars("foobar\n")</literal> will + type the string <literal>foobar</literal> followed by the + Enter key. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>execute</literal> + </term> + <listitem> + <para> + Execute a shell command, returning a list + <literal>(status, stdout)</literal>. If the command + detaches, it must close stdout, as + <literal>execute</literal> will wait for this to consume all + output reliably. This can be achieved by redirecting stdout + to stderr <literal>>&2</literal>, to + <literal>/dev/console</literal>, + <literal>/dev/null</literal> or a file. Examples of + detaching commands are <literal>sleep 365d &</literal>, + where the shell forks a new process that can write to stdout + and <literal>xclip -i</literal>, where the + <literal>xclip</literal> command itself forks without + closing stdout. Takes an optional parameter + <literal>check_return</literal> that defaults to + <literal>True</literal>. Setting this parameter to + <literal>False</literal> will not check for the return code + and return -1 instead. This can be used for commands that + shut down the VM and would therefore break the pipe that + would be used for retrieving the return code. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>succeed</literal> + </term> + <listitem> + <para> + Execute a shell command, raising an exception if the exit + status is not zero, otherwise returning the standard output. + Commands are run with <literal>set -euo pipefail</literal> + set: + </para> + <itemizedlist> + <listitem> + <para> + If several commands are separated by + <literal>;</literal> and one fails, the command as a + whole will fail. + </para> + </listitem> + <listitem> + <para> + For pipelines, the last non-zero exit status will be + returned (if there is one, zero will be returned + otherwise). + </para> + </listitem> + <listitem> + <para> + Dereferencing unset variables fail the command. + </para> + </listitem> + <listitem> + <para> + It will wait for stdout to be closed. See + <literal>execute</literal> for the implications. + </para> + </listitem> + </itemizedlist> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>fail</literal> + </term> + <listitem> + <para> + Like <literal>succeed</literal>, but raising an exception if + the command returns a zero status. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>wait_until_succeeds</literal> + </term> + <listitem> + <para> + Repeat a shell command with 1-second intervals until it + succeeds. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>wait_until_fails</literal> + </term> + <listitem> + <para> + Repeat a shell command with 1-second intervals until it + fails. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>wait_for_unit</literal> + </term> + <listitem> + <para> + Wait until the specified systemd unit has reached the + <quote>active</quote> state. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>wait_for_file</literal> + </term> + <listitem> + <para> + Wait until the specified file exists. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>wait_for_open_port</literal> + </term> + <listitem> + <para> + Wait until a process is listening on the given TCP port (on + <literal>localhost</literal>, at least). + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>wait_for_closed_port</literal> + </term> + <listitem> + <para> + Wait until nobody is listening on the given TCP port. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>wait_for_x</literal> + </term> + <listitem> + <para> + Wait until the X11 server is accepting connections. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>wait_for_text</literal> + </term> + <listitem> + <para> + Wait until the supplied regular expressions matches the + textual contents of the screen by using optical character + recognition (see <literal>get_screen_text</literal> and + <literal>get_screen_text_variants</literal>). + </para> + <note> <para> - It will wait for stdout to be closed. See - <literal>execute</literal> for the implications. + This requires passing <literal>enableOCR</literal> to the + test attribute set. </para> - </listitem> - </itemizedlist> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>fail</literal> - </term> - <listitem> - <para> - Like <literal>succeed</literal>, but raising an exception if - the command returns a zero status. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>wait_until_succeeds</literal> - </term> - <listitem> - <para> - Repeat a shell command with 1-second intervals until it - succeeds. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>wait_until_fails</literal> - </term> - <listitem> - <para> - Repeat a shell command with 1-second intervals until it fails. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>wait_for_unit</literal> - </term> - <listitem> - <para> - Wait until the specified systemd unit has reached the - <quote>active</quote> state. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>wait_for_file</literal> - </term> - <listitem> - <para> - Wait until the specified file exists. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>wait_for_open_port</literal> - </term> - <listitem> - <para> - Wait until a process is listening on the given TCP port (on - <literal>localhost</literal>, at least). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>wait_for_closed_port</literal> - </term> - <listitem> - <para> - Wait until nobody is listening on the given TCP port. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>wait_for_x</literal> - </term> - <listitem> - <para> - Wait until the X11 server is accepting connections. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>wait_for_text</literal> - </term> - <listitem> - <para> - Wait until the supplied regular expressions matches the - textual contents of the screen by using optical character - recognition (see <literal>get_screen_text</literal> and - <literal>get_screen_text_variants</literal>). - </para> - <note> + </note> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>wait_for_console_text</literal> + </term> + <listitem> <para> - This requires passing <literal>enableOCR</literal> to the - test attribute set. + Wait until the supplied regular expressions match a line of + the serial console output. This method is useful when OCR is + not possibile or accurate enough. </para> - </note> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>wait_for_console_text</literal> - </term> - <listitem> - <para> - Wait until the supplied regular expressions match a line of - the serial console output. This method is useful when OCR is - not possibile or accurate enough. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>wait_for_window</literal> - </term> - <listitem> - <para> - Wait until an X11 window has appeared whose name matches the - given regular expression, e.g., - <literal>wait_for_window("Terminal")</literal>. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>copy_from_host</literal> - </term> - <listitem> - <para> - Copies a file from host to machine, e.g., - <literal>copy_from_host("myfile", "/etc/my/important/file")</literal>. - </para> - <para> - The first argument is the file on the host. The file needs to - be accessible while building the nix derivation. The second - argument is the location of the file on the machine. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>systemctl</literal> - </term> - <listitem> - <para> - Runs <literal>systemctl</literal> commands with optional - support for <literal>systemctl --user</literal> - </para> - <programlisting language="python"> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>wait_for_window</literal> + </term> + <listitem> + <para> + Wait until an X11 window has appeared whose name matches the + given regular expression, e.g., + <literal>wait_for_window("Terminal")</literal>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>copy_from_host</literal> + </term> + <listitem> + <para> + Copies a file from host to machine, e.g., + <literal>copy_from_host("myfile", "/etc/my/important/file")</literal>. + </para> + <para> + The first argument is the file on the host. The file needs + to be accessible while building the nix derivation. The + second argument is the location of the file on the machine. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>systemctl</literal> + </term> + <listitem> + <para> + Runs <literal>systemctl</literal> commands with optional + support for <literal>systemctl --user</literal> + </para> + <programlisting language="python"> machine.systemctl("list-jobs --no-pager") # runs `systemctl list-jobs --no-pager` machine.systemctl("list-jobs --no-pager", "any-user") # spawns a shell for `any-user` and runs `systemctl --user list-jobs --no-pager` </programlisting> - </listitem> - </varlistentry> - <varlistentry> - <term> - <literal>shell_interact</literal> - </term> - <listitem> - <para> - Allows you to directly interact with the guest shell. This - should only be used during test development, not in production - tests. Killing the interactive session with - <literal>Ctrl-d</literal> or <literal>Ctrl-c</literal> also - ends the guest session. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - To test user units declared by - <literal>systemd.user.services</literal> the optional - <literal>user</literal> argument can be used: - </para> - <programlisting language="python"> + </listitem> + </varlistentry> + <varlistentry> + <term> + <literal>shell_interact</literal> + </term> + <listitem> + <para> + Allows you to directly interact with the guest shell. This + should only be used during test development, not in + production tests. Killing the interactive session with + <literal>Ctrl-d</literal> or <literal>Ctrl-c</literal> also + ends the guest session. + </para> + </listitem> + </varlistentry> + </variablelist> + <para> + To test user units declared by + <literal>systemd.user.services</literal> the optional + <literal>user</literal> argument can be used: + </para> + <programlisting language="python"> machine.start() machine.wait_for_x() machine.wait_for_unit("xautolock.service", "x-session-user") </programlisting> - <para> - This applies to <literal>systemctl</literal>, - <literal>get_unit_info</literal>, <literal>wait_for_unit</literal>, - <literal>start_job</literal> and <literal>stop_job</literal>. - </para> - <para> - For faster dev cycles it's also possible to disable the code-linters - (this shouldn't be commited though): - </para> - <programlisting language="bash"> + <para> + This applies to <literal>systemctl</literal>, + <literal>get_unit_info</literal>, + <literal>wait_for_unit</literal>, <literal>start_job</literal> and + <literal>stop_job</literal>. + </para> + <para> + For faster dev cycles it's also possible to disable the + code-linters (this shouldn't be commited though): + </para> + <programlisting language="bash"> import ./make-test-python.nix { skipLint = true; machine = @@ -531,13 +537,13 @@ import ./make-test-python.nix { ''; } </programlisting> - <para> - 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): - </para> - <programlisting language="bash"> + <para> + 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): + </para> + <programlisting language="bash"> testScript = '' # fmt: off @@ -545,4 +551,66 @@ import ./make-test-python.nix { # fmt: on ''; </programlisting> + </section> + <section xml:id="ssec-failing-tests-early"> + <title>Failing tests early</title> + <para> + To fail tests early when certain invariables are no longer met + (instead of waiting for the build to time out), the decorator + <literal>polling_condition</literal> is provided. For example, if + we are testing a program <literal>foo</literal> that should not + quit after being started, we might write the following: + </para> + <programlisting language="python"> +@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 +</programlisting> + <para> + <literal>polling_condition</literal> takes the following + (optional) arguments: + </para> + <para> + <literal>seconds_interval</literal> + </para> + <para> + : specifies how often the condition should be polled: + </para> + <programlisting> +```py +@polling_condition(seconds_interval=10) +def foo_running(): + machine.succeed("pgrep -x foo") +``` +</programlisting> + <para> + <literal>description</literal> + </para> + <para> + : 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: + </para> + <programlisting> +```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") +``` +</programlisting> + </section> </section> diff --git a/nixos/doc/manual/from_md/installation/installing-pxe.section.xml b/nixos/doc/manual/from_md/installation/installing-pxe.section.xml index 1dd15ddacba86..94172de65ea06 100644 --- a/nixos/doc/manual/from_md/installation/installing-pxe.section.xml +++ b/nixos/doc/manual/from_md/installation/installing-pxe.section.xml @@ -7,11 +7,11 @@ <para> These instructions assume that you have an existing PXE or iPXE infrastructure and simply want to add the NixOS installer as another - option. To build the necessary files from a recent version of + option. To build the necessary files from your current version of nixpkgs, you can run: </para> <programlisting> -nix-build -A netboot.x86_64-linux nixos/release.nix +nix-build -A netboot.x86_64-linux '<nixpkgs/nixos/release.nix>' </programlisting> <para> This will create a <literal>result</literal> directory containing: * diff --git a/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml index e2bda7604e48f..59da373f38e17 100644 --- a/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml +++ b/nixos/doc/manual/from_md/release-notes/rl-2111.section.xml @@ -275,13 +275,6 @@ </listitem> <listitem> <para> - <link xlink:href="https://maddy.email">maddy</link>, a - composable all-in-one mail server. Available as - <link xlink:href="options.html#opt-services.maddy.enable">services.maddy</link>. - </para> - </listitem> - <listitem> - <para> <link xlink:href="https://sr.ht">sourcehut</link>, a collection of tools useful for software development. Available as @@ -1427,6 +1420,15 @@ Superuser created successfully. for those who want to have all RetroArch cores available. </para> </listitem> + <listitem> + <para> + The Linux kernel for security reasons now restricts access to + BPF syscalls via <literal>BPF_UNPRIV_DEFAULT_OFF=y</literal>. + Unprivileged access can be reenabled via the + <literal>kernel.unprivileged_bpf_disabled</literal> sysctl + knob. + </para> + </listitem> </itemizedlist> </section> <section xml:id="sec-release-21.11-notable-changes"> diff --git a/nixos/doc/manual/from_md/release-notes/rl-2205.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2205.section.xml index d89a0f3ba83c1..7502214c86be6 100644 --- a/nixos/doc/manual/from_md/release-notes/rl-2205.section.xml +++ b/nixos/doc/manual/from_md/release-notes/rl-2205.section.xml @@ -32,10 +32,22 @@ </listitem> <listitem> <para> - Mattermost has been updated to version 6.2. Migrations may - take a while, see the - <link xlink:href="https://docs.mattermost.com/install/self-managed-changelog.html#release-v6.2-feature-release">upgrade - notes</link>. + Mattermost has been updated to extended support release 6.3, + as the previously packaged extended support release 5.37 is + <link xlink:href="https://docs.mattermost.com/upgrade/extended-support-release.html">reaching + its end of life</link>. Migrations may take a while, see the + <link xlink:href="https://docs.mattermost.com/install/self-managed-changelog.html#release-v6-3-extended-support-release">changelog</link> + and + <link xlink:href="https://docs.mattermost.com/upgrade/important-upgrade-notes.html">important + upgrade notes</link>. + </para> + </listitem> + <listitem> + <para> + systemd services can now set + <link linkend="opt-systemd.services">systemd.services.<name>.reloadTriggers</link> + instead of <literal>reloadIfChanged</literal> for a more + granular distinction between reloads and restarts. </para> </listitem> </itemizedlist> @@ -61,6 +73,14 @@ </listitem> <listitem> <para> + <link xlink:href="https://conduit.rs/">matrix-conduit</link>, + a simple, fast and reliable chat server powered by matrix. + Available as + <link xlink:href="option.html#opt-services.matrix-conduit.enable">services.matrix-conduit</link>. + </para> + </listitem> + <listitem> + <para> <link xlink:href="https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-overview.html">filebeat</link>, a lightweight shipper for forwarding and centralizing log data. Available as @@ -69,11 +89,162 @@ </listitem> <listitem> <para> + <link xlink:href="https://github.com/linux-apfs/linux-apfs-rw">apfs</link>, + a kernel module for mounting the Apple File System (APFS). + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://frrouting.org/">FRRouting</link>, a + popular suite of Internet routing protocol daemons (BGP, BFD, + OSPF, IS-IS, VVRP and others). Available as + <link linkend="opt-services.ffr.babel.enable">services.frr</link> + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://github.com/hifi/heisenbridge">heisenbridge</link>, + a bouncer-style Matrix IRC bridge. Available as + <link xlink:href="options.html#opt-services.heisenbridge.enable">services.heisenbridge</link>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://ergo.chat">ergochat</link>, a modern + IRC with IRCv3 features. Available as + <link xlink:href="options.html#opt-services.ergochat.enable">services.ergochat</link>. + </para> + </listitem> + <listitem> + <para> <link xlink:href="https://github.com/ngoduykhanh/PowerDNS-Admin">PowerDNS-Admin</link>, a web interface for the PowerDNS server. Available at <link xlink:href="options.html#opt-services.powerdns-admin.enable">services.powerdns-admin</link>. </para> </listitem> + <listitem> + <para> + <link xlink:href="https://github.com/sezanzeb/input-remapper">input-remapper</link>, + an easy to use tool to change the mapping of your input device + buttons. Available at + <link xlink:href="options.html#opt-services.input-remapper.enable">services.input-remapper</link>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://invoiceplane.com">InvoicePlane</link>, + web application for managing and creating invoices. Available + at + <link xlink:href="options.html#opt-services.invoiceplane.enable">services.invoiceplane</link>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://maddy.email">maddy</link>, a + composable all-in-one mail server. Available as + <link xlink:href="options.html#opt-services.maddy.enable">services.maddy</link>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://github.com/mgumz/mtr-exporter">mtr-exporter</link>, + a Prometheus exporter for mtr metrics. Available as + <link xlink:href="options.html#opt-services.mtr-exporter.enable">services.mtr-exporter</link>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://tetrd.app">tetrd</link>, share your + internet connection from your device to your PC and vice versa + through a USB cable. Available at + <link linkend="opt-services.tetrd.enable">services.tetrd</link>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://github.com/mbrubeck/agate">agate</link>, + a very simple server for the Gemini hypertext protocol. + Available as + <link xlink:href="options.html#opt-services.agate.enable">services.agate</link>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://github.com/JustArchiNET/ArchiSteamFarm">ArchiSteamFarm</link>, + a C# application with primary purpose of idling Steam cards + from multiple accounts simultaneously. Available as + <link xlink:href="options.html#opt-services.archisteamfarm.enable">services.archisteamfarm</link>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://goteleport.com">teleport</link>, + allows engineers and security professionals to unify access + for SSH servers, Kubernetes clusters, web applications, and + databases across all environments. Available at + <link linkend="opt-services.teleport.enable">services.teleport</link>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://loic-sharma.github.io/BaGet/">BaGet</link>, + a lightweight NuGet and symbol server. Available at + <link linkend="opt-services.baget.enable">services.baget</link>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://moosefs.com">moosefs</link>, fault + tolerant petabyte distributed file system. Available as + <link linkend="opt-services.moosefs">moosefs</link>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://github.com/ThomasLeister/prosody-filer">prosody-filer</link>, + a server for handling XMPP HTTP Upload requests. Available at + <link linkend="opt-services.prosody-filer.enable">services.prosody-filer</link>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://github.com/audreyt/ethercalc">ethercalc</link>, + an online collaborative spreadsheet. Available as + <link xlink:href="options.html#opt-services.ethercalc.enable">services.ethercalc</link>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://timetagger.app">timetagger</link>, + an open source time-tracker with an intuitive user experience + and powerful reporting. + <link xlink:href="options.html#opt-services.timetagger.enable">services.timetagger</link>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://www.rstudio.com/products/rstudio/#rstudio-server">rstudio-server</link>, + a browser-based version of the RStudio IDE for the R + programming language. Available as + <link xlink:href="options.html#opt-services.rstudio-server.enable">services.rstudio-server</link>. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://github.com/juanfont/headscale">headscale</link>, + an Open Source implementation of the + <link xlink:href="https://tailscale.io">Tailscale</link> + Control Server. Available as + <link xlink:href="options.html#opt-services.headscale.enable">services.headscale</link> + </para> + </listitem> + <listitem> + <para> + <link xlink:href="https://0xerr0r.github.io/blocky/">blocky</link>, + fast and lightweight DNS proxy as ad-blocker for local network + with many features. + </para> + </listitem> </itemizedlist> </section> <section xml:id="sec-release-22.05-incompatibilities"> @@ -102,6 +273,36 @@ </listitem> <listitem> <para> + <literal>pkgs.ghc.withPackages</literal> as well as + <literal>haskellPackages.ghcWithPackages</literal> etc. now + needs be overridden directly, as opposed to overriding the + result of calling it. Additionally, the + <literal>withLLVM</literal> parameter has been renamed to + <literal>useLLVM</literal>. So instead of + <literal>(ghc.withPackages (p: [])).override { withLLVM = true; }</literal>, + one needs to use + <literal>(ghc.withPackages.override { useLLVM = true; }) (p: [])</literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>home-assistant</literal> module now requires + users that don’t want their configuration to be managed + declaratively to set + <literal>services.home-assistant.config = null;</literal>. + This is required due to the way default settings are handled + with the new settings style. + </para> + <para> + Additionally the default list of + <literal>extraComponents</literal> now includes the minimal + dependencies to successfully complete the + <link xlink:href="https://www.home-assistant.io/getting-started/onboarding/">onboarding</link> + procedure. + </para> + </listitem> + <listitem> + <para> <literal>pkgs.emacsPackages.orgPackages</literal> is removed because org elpa is deprecated. The packages in the top level of <literal>pkgs.emacsPackages</literal>, such as org and @@ -119,6 +320,41 @@ </listitem> <listitem> <para> + <literal>services.kubernetes.scheduler.{port,address}</literal> + now set <literal>--secure-port</literal> and + <literal>--bind-address</literal> instead of + <literal>--port</literal> and <literal>--address</literal>, + since the former have been deprecated and are no longer + functional in kubernetes>=1.23. Ensure that you are not + relying on the insecure behaviour before upgrading. + </para> + </listitem> + <listitem> + <para> + The DHCP server (<literal>services.dhcpd4</literal>, + <literal>services.dhcpd6</literal>) has been hardened. The + service is now using the systemd’s + <literal>DynamicUser</literal> mechanism to run as an + unprivileged dynamically-allocated user with limited + capabilities. The dhcpd state files are now always stored in + <literal>/var/lib/dhcpd{4,6}</literal> and the + <literal>services.dhcpd4.stateDir</literal> and + <literal>service.dhcpd6.stateDir</literal> options have been + removed. If you were depending on root privileges or + set{uid,gid,cap} binaries in dhcpd shell hooks, you may give + dhcpd more capabilities with e.g. + <literal>systemd.services.dhcpd6.serviceConfig.AmbientCapabilities</literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>mailpile</literal> email webclient + (<literal>services.mailpile</literal>) has been removed due to + its reliance on python2. + </para> + </listitem> + <listitem> + <para> The MoinMoin wiki engine (<literal>services.moinmoin</literal>) has been removed, because Python 2 is being retired from nixpkgs. @@ -155,6 +391,22 @@ </listitem> <listitem> <para> + <literal>buildGoModule</literal> was updated to use + <literal>go_1_17</literal>, third party derivations that + specify >= go 1.17 in the main <literal>go.mod</literal> + will need to regenerate their <literal>vendorSha256</literal> + hash. + </para> + </listitem> + <listitem> + <para> + The <literal>gnome-passwordsafe</literal> package updated to + <link xlink:href="https://gitlab.gnome.org/World/secrets/-/tags/6.0">version + 6.x</link> and renamed to <literal>gnome-secrets</literal>. + </para> + </listitem> + <listitem> + <para> If you previously used <literal>/etc/docker/daemon.json</literal>, you need to incorporate the changes into the new option @@ -163,6 +415,37 @@ </listitem> <listitem> <para> + Ntopng (<literal>services.ntopng</literal>) is updated to + 5.2.1 and uses a separate Redis instance if + <literal>system.stateVersion</literal> is at least + <literal>22.05</literal>. Existing setups shouldn’t be + affected. + </para> + </listitem> + <listitem> + <para> + The backward compatibility in + <literal>services.wordpress</literal> to configure sites with + the old interface has been removed. Please use + <literal>services.wordpress.sites</literal> instead. + </para> + </listitem> + <listitem> + <para> + The backward compatibility in + <literal>services.dokuwiki</literal> to configure sites with + the old interface has been removed. Please use + <literal>services.dokuwiki.sites</literal> instead. + </para> + </listitem> + <listitem> + <para> + opensmtpd-extras is no longer build with python2 scripting + support due to python2 deprecation in nixpkgs + </para> + </listitem> + <listitem> + <para> The <literal>autorestic</literal> package has been upgraded from 1.3.0 to 1.5.0 which introduces breaking changes in config file, check @@ -198,6 +481,219 @@ to your configuration. </para> </listitem> + <listitem> + <para> + Normal users (with <literal>isNormalUser = true</literal>) + which have non-empty <literal>subUidRanges</literal> or + <literal>subGidRanges</literal> set no longer have additional + implicit ranges allocated. To enable automatic allocation back + set <literal>autoSubUidGidRange = true</literal>. + </para> + </listitem> + <listitem> + <para> + <literal>idris2</literal> now requires + <literal>--package</literal> when using packages + <literal>contrib</literal> and <literal>network</literal>, + while previously these idris2 packages were automatically + loaded. + </para> + </listitem> + <listitem> + <para> + The iputils package, which is installed by default, no longer + provides the legacy tools <literal>tftpd</literal> and + <literal>traceroute6</literal>. More tools + (<literal>ninfod</literal>, <literal>rarpd</literal>, and + <literal>rdisc</literal>) are going to be removed in the next + release. See + <link xlink:href="https://github.com/iputils/iputils/releases/tag/20211215">upstream’s + release notes</link> for more details and available + replacements. + </para> + </listitem> + <listitem> + <para> + <literal>services.thelounge.private</literal> was removed in + favor of <literal>services.thelounge.public</literal>, to + follow with upstream changes. + </para> + </listitem> + <listitem> + <para> + <literal>pkgs.docbookrx</literal> was removed since it’s + unmaintained + </para> + </listitem> + <listitem> + <para> + <literal>tilp2</literal> was removed together with its module + </para> + </listitem> + <listitem> + <para> + The options + <literal>networking.interfaces.<name>.ipv4.routes</literal> + and + <literal>networking.interfaces.<name>.ipv6.routes</literal> + are no longer ignored when using networkd instead of the + default scripted network backend by setting + <literal>networking.useNetworkd</literal> to + <literal>true</literal>. + </para> + </listitem> + <listitem> + <para> + MultiMC has been replaced with the fork PolyMC due to upstream + developers being hostile to 3rd party package maintainers. + PolyMC removes all MultiMC branding and is aimed at providing + proper 3rd party packages like the one contained in Nixpkgs. + This change affects the data folder where game instances and + other save and configuration files are stored. Users with + existing installations should rename + <literal>~/.local/share/multimc</literal> to + <literal>~/.local/share/polymc</literal>. The main config + file’s path has also moved from + <literal>~/.local/share/multimc/multimc.cfg</literal> to + <literal>~/.local/share/polymc/polymc.cfg</literal>. + </para> + </listitem> + <listitem> + <para> + The terraform 0.12 compatibility has been removed and the + <literal>terraform.withPlugins</literal> and + <literal>terraform-providers.mkProvider</literal> + implementations simplified. Providers now need to be stored + under + <literal>$out/libexec/terraform-providers/<registry>/<owner>/<name>/<version>/<os>_<arch>/terraform-provider-<name>_v<version></literal> + (which mkProvider does). + </para> + <para> + This breaks back-compat so it’s not possible to mix-and-match + with previous versions of nixpkgs. In exchange, it now becomes + possible to use the providers from + <link xlink:href="https://github.com/numtide/nixpkgs-terraform-providers-bin">nixpkgs-terraform-providers-bin</link> + directly. + </para> + </listitem> + <listitem> + <para> + The existing <literal>pkgs.opentelemetry-collector</literal> + has been moved to + <literal>pkgs.opentelemetry-collector-contrib</literal> to + match the actual source being the <quote>contrib</quote> + edition. <literal>pkgs.opentelemetry-collector</literal> is + now the actual core release of opentelemetry-collector. If you + use the community contributions you should change the package + you refer to. If you don’t need them update your commands from + <literal>otelcontribcol</literal> to + <literal>otelcorecol</literal> and enjoy a 7x smaller binary. + </para> + </listitem> + <listitem> + <para> + <literal>pkgs.noto-fonts-cjk</literal> is now deprecated in + favor of <literal>pkgs.noto-fonts-cjk-sans</literal> and + <literal>pkgs.noto-fonts-cjk-serif</literal> because they each + have different release schedules. To maintain compatibility + with prior releases of Nixpkgs, + <literal>pkgs.noto-fonts-cjk</literal> is currently an alias + of <literal>pkgs.noto-fonts-cjk-sans</literal> and doesn’t + include serif fonts. + </para> + </listitem> + <listitem> + <para> + <literal>switch-to-configuration</literal> (the script that is + run when running <literal>nixos-rebuild switch</literal> for + example) has been reworked + </para> + <itemizedlist spacing="compact"> + <listitem> + <para> + The interface that allows activation scripts to restart + units has been streamlined. Restarting and reloading is + now done by a single file + <literal>/run/nixos/activation-restart-list</literal> that + honors <literal>restartIfChanged</literal> and + <literal>reloadIfChanged</literal> of the units. + </para> + <itemizedlist spacing="compact"> + <listitem> + <para> + Preferring to reload instead of restarting can still + be achieved using + <literal>/run/nixos/activation-reload-list</literal>. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + The script now uses a proper ini-file parser to parse + systemd units. Some values are now only searched in one + section instead of in the entire unit. This is only + relevant for units that don’t use the NixOS systemd moule. + </para> + <itemizedlist spacing="compact"> + <listitem> + <para> + <literal>RefuseManualStop</literal>, + <literal>X-OnlyManualStart</literal>, + <literal>X-StopOnRemoval</literal>, + <literal>X-StopOnReconfiguration</literal> are only + searched in the <literal>[Unit]</literal> section + </para> + </listitem> + <listitem> + <para> + <literal>X-ReloadIfChanged</literal>, + <literal>X-RestartIfChanged</literal>, + <literal>X-StopIfChanged</literal> are only searched + in the <literal>[Service]</literal> section + </para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + The <literal>services.bookstack.cacheDir</literal> option has + been removed, since the cache directory is now handled by + systemd. + </para> + </listitem> + <listitem> + <para> + The <literal>services.bookstack.extraConfig</literal> option + has been replaced by + <literal>services.bookstack.config</literal> which implements + a + <link xlink:href="https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md">settings-style</link> + configuration. + </para> + </listitem> + <listitem> + <para> + <literal>lib.assertMsg</literal> and + <literal>lib.assertOneOf</literal> no longer return + <literal>false</literal> if the passed condition is + <literal>false</literal>, <literal>throw</literal>ing the + given error message instead (which makes the resulting error + message less cluttered). This will not impact the behaviour of + code using these functions as intended, namely as top-level + wrapper for <literal>assert</literal> conditions. + </para> + </listitem> + <listitem> + <para> + <literal>pkgs.vimPlugins.onedark-nvim</literal> now refers to + <link xlink:href="https://github.com/navarasu/onedark.nvim">navarasu/onedark.nvim</link> + (formerly refers to + <link xlink:href="https://github.com/olimorris/onedarkpro.nvim">olimorris/onedarkpro.nvim</link>). + </para> + </listitem> </itemizedlist> </section> <section xml:id="sec-release-22.05-notable-changes"> @@ -230,6 +726,51 @@ </listitem> <listitem> <para> + The option + <link linkend="opt-virtualisation.vmVariant">virtualisation.vmVariant</link> + was added to allow users to make changes to the + <literal>nixos-rebuild build-vm</literal> configuration that + do not apply to their normal system. + </para> + <para> + The <literal>config.system.build.vm</literal> attribute now + always exists and defaults to the value from + <literal>vmVariant</literal>. Configurations that import the + <literal>virtualisation/qemu-vm.nix</literal> module + themselves will override this value, such that + <literal>vmVariant</literal> is not used. + </para> + <para> + Similarly + <link linkend="opt-virtualisation.vmVariantWithBootLoader">virtualisation.vmVariantWithBootloader</link> + was added. + </para> + </listitem> + <listitem> + <para> + The configuration portion of the <literal>nix-daemon</literal> + module has been reworked and exposed as + <link xlink:href="options.html#opt-nix-settings">nix.settings</link>: + </para> + <itemizedlist spacing="compact"> + <listitem> + <para> + Legacy options have been mapped to the corresponding + options under under + <link xlink:href="options.html#opt-nix.settings">nix.settings</link> + but may be deprecated in the future. + </para> + </listitem> + <listitem> + <para> + <link xlink:href="options.html#opt-nix.buildMachines.publicHostKey">nix.buildMachines.publicHostKey</link> + has been added. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> The <literal>writers.writePyPy2</literal>/<literal>writers.writePyPy3</literal> and corresponding @@ -240,6 +781,19 @@ </listitem> <listitem> <para> + If you are using Wayland you can choose to use the Ozone + Wayland support in Chrome and several Electron apps by setting + the environment variable <literal>NIXOS_OZONE_WL=1</literal> + (for example via + <literal>environment.sessionVariables.NIXOS_OZONE_WL = "1"</literal>). + This is not enabled by default because Ozone Wayland is still + under heavy development and behavior is not always flawless. + Furthermore, not all Electron apps use the latest Electron + versions. + </para> + </listitem> + <listitem> + <para> The <literal>influxdb2</literal> package was split into <literal>influxdb2-server</literal> and <literal>influxdb2-cli</literal>, matching the split that took @@ -272,8 +826,21 @@ </listitem> <listitem> <para> + MariaDB is now offered in several versions, not just the + newest one. So if you have a need for running MariaDB 10.4 for + example, you can now just set + <literal>services.mysql.package = pkgs.mariadb_104;</literal>. + In general, it is recommended to run the newest version, to + get the newest features, while sticking with an LTS version + will most likely provide a more stable experience. Sometimes + software is also incompatible with the newest version of + MariaDB. + </para> + </listitem> + <listitem> + <para> The option - <link linkend="opt-services.ssh.enableAskPassword">services.ssh.enableAskPassword</link> + <link linkend="opt-programs.ssh.enableAskPassword">programs.ssh.enableAskPassword</link> was added, decoupling the setting of <literal>SSH_ASKPASS</literal> from <literal>services.xserver.enable</literal>. This allows easy @@ -282,6 +849,15 @@ </listitem> <listitem> <para> + <link linkend="opt-programs.ssh.knownHosts">programs.ssh.knownHosts</link> + has gained an <literal>extraHostNames</literal> option to + replace <literal>hostNames</literal>. + <literal>hostNames</literal> is deprecated, but still + available for now. + </para> + </listitem> + <listitem> + <para> The <literal>services.stubby</literal> module was converted to a <link xlink:href="https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md">settings-style</link> @@ -295,6 +871,133 @@ files. </para> </listitem> + <listitem> + <para> + A new option + <literal>boot.initrd.extraModprobeConfig</literal> has been + added which can be used to configure kernel modules that are + loaded in the initrd. + </para> + </listitem> + <listitem> + <para> + <literal>nixos-generate-config</literal> now puts the dhcp + configuration in <literal>hardware-configuration.nix</literal> + instead of <literal>configuration.nix</literal>. + </para> + </listitem> + <listitem> + <para> + <literal>fetchFromSourcehut</literal> now allows fetching + repositories recursively using <literal>fetchgit</literal> or + <literal>fetchhg</literal> if the argument + <literal>fetchSubmodules</literal> is set to + <literal>true</literal>. + </para> + </listitem> + <listitem> + <para> + The option <literal>services.thelounge.plugins</literal> has + been added to allow installing plugins for The Lounge. Plugins + can be found in + <literal>pkgs.theLoungePlugins.plugins</literal> and + <literal>pkgs.theLoungePlugins.themes</literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>firmwareLinuxNonfree</literal> package has been + renamed to <literal>linux-firmware</literal>. + </para> + </listitem> + <listitem> + <para> + The <literal>services.mbpfan</literal> module was converted to + a + <link xlink:href="https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md">RFC + 0042</link> configuration. + </para> + </listitem> + <listitem> + <para> + The default value for + <literal>programs.spacefm.settings.graphical_su</literal> got + unset. It previously pointed to <literal>gksu</literal> which + has been removed. + </para> + </listitem> + <listitem> + <para> + A new module was added for the + <link xlink:href="https://starship.rs/">Starship</link> shell + prompt, providing the options + <literal>programs.starship.enable</literal> and + <literal>programs.starship.settings</literal>. + </para> + </listitem> + <listitem> + <para> + <literal>services.mattermost.plugins</literal> has been added + to allow the declarative installation of Mattermost plugins. + Plugins are automatically repackaged using autoPatchelf. + </para> + </listitem> + <listitem> + <para> + The <literal>zrepl</literal> package has been updated from + 0.4.0 to 0.5: + </para> + <itemizedlist spacing="compact"> + <listitem> + <para> + The RPC protocol version was bumped; all zrepl daemons in + a setup must be updated and restarted before replication + can resume. + </para> + </listitem> + <listitem> + <para> + A bug involving encrypt-on-receive has been fixed. Read + the + <link xlink:href="https://zrepl.github.io/configuration/sendrecvoptions.html#job-recv-options-placeholder">zrepl + documentation</link> and check the output of + <literal>zfs get -r encryption,zrepl:placeholder PATH_TO_ROOTFS</literal> + on the receiver. + </para> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <para> + Renamed option + <literal>services.openssh.challengeResponseAuthentication</literal> + to + <literal>services.openssh.kbdInteractiveAuthentication</literal>. + Reason is that the old name has been deprecated upstream. + Using the old option name will still work, but produce a + warning. + </para> + </listitem> + <listitem> + <para> + The option + <link linkend="opt-services.networking.networkmanager.enableFccUnlock">services.networking.networkmanager.enableFccUnlock</link> + was added to support FCC unlock procedures. Since release + 1.18.4, the ModemManager daemon no longer automatically + performs the FCC unlock procedure by default. See + <link xlink:href="https://modemmanager.org/docs/modemmanager/fcc-unlock/">the + docs</link> for more details. + </para> + </listitem> + <listitem> + <para> + <literal>programs.tmux</literal> has a new option + <literal>plugins</literal> that accepts a list of packages + from the <literal>tmuxPlugins</literal> group. The specified + packages are added to the system and loaded by + <literal>tmux</literal>. + </para> + </listitem> </itemizedlist> </section> </section> diff --git a/nixos/doc/manual/installation/installing-pxe.section.md b/nixos/doc/manual/installation/installing-pxe.section.md index 2016a258251f8..4fbd6525f8c3b 100644 --- a/nixos/doc/manual/installation/installing-pxe.section.md +++ b/nixos/doc/manual/installation/installing-pxe.section.md @@ -5,11 +5,11 @@ setup. These instructions assume that you have an existing PXE or iPXE infrastructure and simply want to add the NixOS installer as another -option. To build the necessary files from a recent version of nixpkgs, +option. To build the necessary files from your current version of nixpkgs, you can run: ```ShellSession -nix-build -A netboot.x86_64-linux nixos/release.nix +nix-build -A netboot.x86_64-linux '<nixpkgs/nixos/release.nix>' ``` This will create a `result` directory containing: \* `bzImage` -- the diff --git a/nixos/doc/manual/man-nixos-rebuild.xml b/nixos/doc/manual/man-nixos-rebuild.xml index 6c7fc57f8d83c..ab2a5d83a089f 100644 --- a/nixos/doc/manual/man-nixos-rebuild.xml +++ b/nixos/doc/manual/man-nixos-rebuild.xml @@ -453,7 +453,7 @@ Allow ad-hoc remote builders for building the new system. This requires the user executing <command>nixos-rebuild</command> (usually root) to be configured as a trusted user in the Nix daemon. This can be achieved by - using the <literal>nix.trustedUsers</literal> NixOS option. Examples + using the <literal>nix.settings.trusted-users</literal> NixOS option. Examples values for that option are described in the <literal>Remote builds chapter</literal> in the Nix manual, (i.e. <command>--builders "ssh://bigbrother x86_64-linux"</command>). By specifying an empty string diff --git a/nixos/doc/manual/release-notes/rl-2111.section.md b/nixos/doc/manual/release-notes/rl-2111.section.md index 2520d176096aa..1b59842e020bb 100644 --- a/nixos/doc/manual/release-notes/rl-2111.section.md +++ b/nixos/doc/manual/release-notes/rl-2111.section.md @@ -74,8 +74,6 @@ In addition to numerous new and upgraded packages, this release has the followin - [PeerTube](https://joinpeertube.org/), developed by Framasoft, is the free and decentralized alternative to video platforms. Available at [services.peertube](options.html#opt-services.peertube.enable). -- [maddy](https://maddy.email), a composable all-in-one mail server. Available as [services.maddy](options.html#opt-services.maddy.enable). - - [sourcehut](https://sr.ht), a collection of tools useful for software development. Available as [services.sourcehut](options.html#opt-services.sourcehut.enable). - [ucarp](https://download.pureftpd.org/pub/ucarp/README), an userspace implementation of the Common Address Redundancy Protocol (CARP). Available as [networking.ucarp](options.html#opt-networking.ucarp.enable). @@ -419,6 +417,8 @@ In addition to numerous new and upgraded packages, this release has the followin - `retroArchCores` has been removed. This means that using `nixpkgs.config.retroarch` to customize RetroArch cores is not supported anymore. Instead, use package overrides, for example: `retroarch.override { cores = with libretro; [ citra snes9x ]; };`. Also, `retroarchFull` derivation is available for those who want to have all RetroArch cores available. +- The Linux kernel for security reasons now restricts access to BPF syscalls via `BPF_UNPRIV_DEFAULT_OFF=y`. Unprivileged access can be reenabled via the `kernel.unprivileged_bpf_disabled` sysctl knob. + ## Other Notable Changes {#sec-release-21.11-notable-changes} diff --git a/nixos/doc/manual/release-notes/rl-2205.section.md b/nixos/doc/manual/release-notes/rl-2205.section.md index 6a4cd0973216f..c96f898505a2b 100644 --- a/nixos/doc/manual/release-notes/rl-2205.section.md +++ b/nixos/doc/manual/release-notes/rl-2205.section.md @@ -13,22 +13,72 @@ In addition to numerous new and upgraded packages, this release has the followin - PHP 8.1 is now available -- Mattermost has been updated to version 6.2. Migrations may take a while, - see the [upgrade notes](https://docs.mattermost.com/install/self-managed-changelog.html#release-v6.2-feature-release). +- Mattermost has been updated to extended support release 6.3, as the previously packaged extended support release 5.37 is [reaching its end of life](https://docs.mattermost.com/upgrade/extended-support-release.html). + Migrations may take a while, see the [changelog](https://docs.mattermost.com/install/self-managed-changelog.html#release-v6-3-extended-support-release) + and [important upgrade notes](https://docs.mattermost.com/upgrade/important-upgrade-notes.html). + +- systemd services can now set [systemd.services.\<name\>.reloadTriggers](#opt-systemd.services) instead of `reloadIfChanged` for a more granular distinction between reloads and restarts. ## New Services {#sec-release-22.05-new-services} - [aesmd](https://github.com/intel/linux-sgx#install-the-intelr-sgx-psw), the Intel SGX Architectural Enclave Service Manager. Available as [services.aesmd](#opt-services.aesmd.enable). + - [rootless Docker](https://docs.docker.com/engine/security/rootless/), a `systemd --user` Docker service which runs without root permissions. Available as [virtualisation.docker.rootless.enable](options.html#opt-virtualisation.docker.rootless.enable). +- [matrix-conduit](https://conduit.rs/), a simple, fast and reliable chat server powered by matrix. Available as [services.matrix-conduit](option.html#opt-services.matrix-conduit.enable). + - [filebeat](https://www.elastic.co/guide/en/beats/filebeat/current/filebeat-overview.html), a lightweight shipper for forwarding and centralizing log data. Available as [services.filebeat](#opt-services.filebeat.enable). +- [apfs](https://github.com/linux-apfs/linux-apfs-rw), a kernel module for mounting the Apple File System (APFS). + +- [FRRouting](https://frrouting.org/), a popular suite of Internet routing protocol daemons (BGP, BFD, OSPF, IS-IS, VVRP and others). Available as [services.frr](#opt-services.ffr.babel.enable) + +- [heisenbridge](https://github.com/hifi/heisenbridge), a bouncer-style Matrix IRC bridge. Available as [services.heisenbridge](options.html#opt-services.heisenbridge.enable). + +- [ergochat](https://ergo.chat), a modern IRC with IRCv3 features. Available as [services.ergochat](options.html#opt-services.ergochat.enable). + - [PowerDNS-Admin](https://github.com/ngoduykhanh/PowerDNS-Admin), a web interface for the PowerDNS server. Available at [services.powerdns-admin](options.html#opt-services.powerdns-admin.enable). +- [input-remapper](https://github.com/sezanzeb/input-remapper), an easy to use tool to change the mapping of your input device buttons. Available at [services.input-remapper](options.html#opt-services.input-remapper.enable). + +- [InvoicePlane](https://invoiceplane.com), web application for managing and creating invoices. Available at [services.invoiceplane](options.html#opt-services.invoiceplane.enable). + +- [maddy](https://maddy.email), a composable all-in-one mail server. Available as [services.maddy](options.html#opt-services.maddy.enable). + +- [mtr-exporter](https://github.com/mgumz/mtr-exporter), a Prometheus exporter for mtr metrics. Available as [services.mtr-exporter](options.html#opt-services.mtr-exporter.enable). + +- [tetrd](https://tetrd.app), share your internet connection from your device to your PC and vice versa through a USB cable. Available at [services.tetrd](#opt-services.tetrd.enable). + +- [agate](https://github.com/mbrubeck/agate), a very simple server for the Gemini hypertext protocol. Available as [services.agate](options.html#opt-services.agate.enable). + +- [ArchiSteamFarm](https://github.com/JustArchiNET/ArchiSteamFarm), a C# application with primary purpose of idling Steam cards from multiple accounts simultaneously. Available as [services.archisteamfarm](options.html#opt-services.archisteamfarm.enable). + +- [teleport](https://goteleport.com), allows engineers and security professionals to unify access for SSH servers, Kubernetes clusters, web applications, and databases across all environments. Available at [services.teleport](#opt-services.teleport.enable). + +- [BaGet](https://loic-sharma.github.io/BaGet/), a lightweight NuGet and symbol server. Available at [services.baget](#opt-services.baget.enable). + +- [moosefs](https://moosefs.com), fault tolerant petabyte distributed file system. + Available as [moosefs](#opt-services.moosefs). + +- [prosody-filer](https://github.com/ThomasLeister/prosody-filer), a server for handling XMPP HTTP Upload requests. Available at [services.prosody-filer](#opt-services.prosody-filer.enable). + +- [ethercalc](https://github.com/audreyt/ethercalc), an online collaborative + spreadsheet. Available as [services.ethercalc](options.html#opt-services.ethercalc.enable). + +- [timetagger](https://timetagger.app), an open source time-tracker with an intuitive user experience and powerful reporting. [services.timetagger](options.html#opt-services.timetagger.enable). + +- [rstudio-server](https://www.rstudio.com/products/rstudio/#rstudio-server), a browser-based version of the RStudio IDE for the R programming language. Available as [services.rstudio-server](options.html#opt-services.rstudio-server.enable). + +- [headscale](https://github.com/juanfont/headscale), an Open Source implementation of the [Tailscale](https://tailscale.io) Control Server. Available as [services.headscale](options.html#opt-services.headscale.enable) + +- [blocky](https://0xerr0r.github.io/blocky/), fast and lightweight DNS proxy as ad-blocker for local network with many features. + +<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. --> + ## Backward Incompatibilities {#sec-release-22.05-incompatibilities} - `pkgs.ghc` now refers to `pkgs.targetPackages.haskellPackages.ghc`. - This *only* makes a difference if you are cross-compiling and will + This _only_ makes a difference if you are cross-compiling and will ensure that `pkgs.ghc` always runs on the host platform and compiles for the target platform (similar to `pkgs.gcc` for example). `haskellPackages.ghc` still behaves as before, running on the build @@ -39,6 +89,21 @@ In addition to numerous new and upgraded packages, this release has the followin instead to ensure cross compilation keeps working (or switch to `haskellPackages.callPackage`). +- `pkgs.ghc.withPackages` as well as `haskellPackages.ghcWithPackages` etc. + now needs be overridden directly, as opposed to overriding the result of + calling it. Additionally, the `withLLVM` parameter has been renamed to + `useLLVM`. So instead of `(ghc.withPackages (p: [])).override { withLLVM = true; }`, + one needs to use `(ghc.withPackages.override { useLLVM = true; }) (p: [])`. + +- The `home-assistant` module now requires users that don't want their + configuration to be managed declaratively to set + `services.home-assistant.config = null;`. This is required + due to the way default settings are handled with the new settings style. + + Additionally the default list of `extraComponents` now includes the minimal + dependencies to successfully complete the [onboarding](https://www.home-assistant.io/getting-started/onboarding/) + procedure. + - `pkgs.emacsPackages.orgPackages` is removed because org elpa is deprecated. The packages in the top level of `pkgs.emacsPackages`, such as org and org-contrib, refer to the ones in `pkgs.emacsPackages.elpaPackages` and @@ -46,6 +111,15 @@ In addition to numerous new and upgraded packages, this release has the followin - `services.kubernetes.addons.dashboard` was removed due to it being an outdated version. +- `services.kubernetes.scheduler.{port,address}` now set `--secure-port` and `--bind-address` instead of `--port` and `--address`, since the former have been deprecated and are no longer functional in kubernetes>=1.23. Ensure that you are not relying on the insecure behaviour before upgrading. + +- The DHCP server (`services.dhcpd4`, `services.dhcpd6`) has been hardened. + The service is now using the systemd's `DynamicUser` mechanism to run as an unprivileged dynamically-allocated user with limited capabilities. + The dhcpd state files are now always stored in `/var/lib/dhcpd{4,6}` and the `services.dhcpd4.stateDir` and `service.dhcpd6.stateDir` options have been removed. + If you were depending on root privileges or set{uid,gid,cap} binaries in dhcpd shell hooks, you may give dhcpd more capabilities with e.g. `systemd.services.dhcpd6.serviceConfig.AmbientCapabilities`. + +- The `mailpile` email webclient (`services.mailpile`) has been removed due to its reliance on python2. + - The MoinMoin wiki engine (`services.moinmoin`) has been removed, because Python 2 is being retired from nixpkgs. - The `wafHook` hook now honors `NIX_BUILD_CORES` when `enableParallelBuilding` is not set explicitly. Packages can restore the old behaviour by setting `enableParallelBuilding=false`. @@ -56,8 +130,23 @@ In addition to numerous new and upgraded packages, this release has the followin - The `writers.writePython2` and corresponding `writers.writePython2Bin` convenience functions to create executable Python 2 scripts in the store were removed in preparation of removal of the Python 2 interpreter. Scripts have to be converted to Python 3 for use with `writers.writePython3` or `writers.writePyPy2` needs to be used. +- `buildGoModule` was updated to use `go_1_17`, third party derivations that specify >= go 1.17 in the main `go.mod` will need to regenerate their `vendorSha256` hash. + +- The `gnome-passwordsafe` package updated to [version 6.x](https://gitlab.gnome.org/World/secrets/-/tags/6.0) and renamed to `gnome-secrets`. + - If you previously used `/etc/docker/daemon.json`, you need to incorporate the changes into the new option `virtualisation.docker.daemon.settings`. +- Ntopng (`services.ntopng`) is updated to 5.2.1 and uses a separate Redis instance if `system.stateVersion` is at least `22.05`. Existing setups shouldn't be affected. + +- The backward compatibility in `services.wordpress` to configure sites with + the old interface has been removed. Please use `services.wordpress.sites` + instead. + +- The backward compatibility in `services.dokuwiki` to configure sites with the + old interface has been removed. Please use `services.dokuwiki.sites` instead. + +- opensmtpd-extras is no longer build with python2 scripting support due to python2 deprecation in nixpkgs + - The `autorestic` package has been upgraded from 1.3.0 to 1.5.0 which introduces breaking changes in config file, check [their migration guide](https://autorestic.vercel.app/migration/1.4_1.5) for more details. - For `pkgs.python3.pkgs.ipython`, its direct dependency `pkgs.python3.pkgs.matplotlib-inline` @@ -69,6 +158,68 @@ In addition to numerous new and upgraded packages, this release has the followin - `documentation.man` has been refactored to support choosing a man implementation other than GNU's `man-db`. For this, `documentation.man.manualPages` has been renamed to `documentation.man.man-db.manualPages`. If you want to use the new alternative man implementation `mandoc`, add `documentation.man = { enable = true; man-db.enable = false; mandoc.enable = true; }` to your configuration. +- Normal users (with `isNormalUser = true`) which have non-empty `subUidRanges` or `subGidRanges` set no longer have additional implicit ranges allocated. To enable automatic allocation back set `autoSubUidGidRange = true`. + +- `idris2` now requires `--package` when using packages `contrib` and `network`, while previously these idris2 packages were automatically loaded. + +- The iputils package, which is installed by default, no longer provides the + legacy tools `tftpd` and `traceroute6`. More tools (`ninfod`, `rarpd`, and + `rdisc`) are going to be removed in the next release. See + [upstream's release notes](https://github.com/iputils/iputils/releases/tag/20211215) + for more details and available replacements. + +- `services.thelounge.private` was removed in favor of `services.thelounge.public`, to follow with upstream changes. + +- `pkgs.docbookrx` was removed since it's unmaintained + +- `tilp2` was removed together with its module + +- The options `networking.interfaces.<name>.ipv4.routes` and `networking.interfaces.<name>.ipv6.routes` are no longer ignored when using networkd instead of the default scripted network backend by setting `networking.useNetworkd` to `true`. + +- MultiMC has been replaced with the fork PolyMC due to upstream developers being hostile to 3rd party package maintainers. PolyMC removes all MultiMC branding and is aimed at providing proper 3rd party packages like the one contained in Nixpkgs. This change affects the data folder where game instances and other save and configuration files are stored. Users with existing installations should rename `~/.local/share/multimc` to `~/.local/share/polymc`. The main config file's path has also moved from `~/.local/share/multimc/multimc.cfg` to `~/.local/share/polymc/polymc.cfg`. + + +- The terraform 0.12 compatibility has been removed and the `terraform.withPlugins` and `terraform-providers.mkProvider` implementations simplified. Providers now need to be stored under +`$out/libexec/terraform-providers/<registry>/<owner>/<name>/<version>/<os>_<arch>/terraform-provider-<name>_v<version>` (which mkProvider does). + + This breaks back-compat so it's not possible to mix-and-match with previous versions of nixpkgs. In exchange, it now becomes possible to use the providers from [nixpkgs-terraform-providers-bin](https://github.com/numtide/nixpkgs-terraform-providers-bin) directly. + +- The existing `pkgs.opentelemetry-collector` has been moved to + `pkgs.opentelemetry-collector-contrib` to match the actual source being the + "contrib" edition. `pkgs.opentelemetry-collector` is now the actual core + release of opentelemetry-collector. If you use the community contributions + you should change the package you refer to. If you don't need them update your + commands from `otelcontribcol` to `otelcorecol` and enjoy a 7x smaller binary. + + +- `pkgs.noto-fonts-cjk` is now deprecated in favor of `pkgs.noto-fonts-cjk-sans` + and `pkgs.noto-fonts-cjk-serif` because they each have different release + schedules. To maintain compatibility with prior releases of Nixpkgs, + `pkgs.noto-fonts-cjk` is currently an alias of `pkgs.noto-fonts-cjk-sans` and + doesn't include serif fonts. + +- `switch-to-configuration` (the script that is run when running `nixos-rebuild switch` for example) has been reworked + * The interface that allows activation scripts to restart units has been streamlined. Restarting and reloading is now done by a single file `/run/nixos/activation-restart-list` that honors `restartIfChanged` and `reloadIfChanged` of the units. + * Preferring to reload instead of restarting can still be achieved using `/run/nixos/activation-reload-list`. + * The script now uses a proper ini-file parser to parse systemd units. Some values are now only searched in one section instead of in the entire unit. This is only relevant for units that don't use the NixOS systemd moule. + * `RefuseManualStop`, `X-OnlyManualStart`, `X-StopOnRemoval`, `X-StopOnReconfiguration` are only searched in the `[Unit]` section + * `X-ReloadIfChanged`, `X-RestartIfChanged`, `X-StopIfChanged` are only searched in the `[Service]` section + +- The `services.bookstack.cacheDir` option has been removed, since the + cache directory is now handled by systemd. + +- The `services.bookstack.extraConfig` option has been replaced by + `services.bookstack.config` which implements a + [settings-style](https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md) + configuration. + +- `lib.assertMsg` and `lib.assertOneOf` no longer return `false` if the passed condition is `false`, `throw`ing the given error message instead (which makes the resulting error message less cluttered). This will not impact the behaviour of code using these functions as intended, namely as top-level wrapper for `assert` conditions. + +- `pkgs.vimPlugins.onedark-nvim` now refers to [navarasu/onedark.nvim](https://github.com/navarasu/onedark.nvim) + (formerly refers to [olimorris/onedarkpro.nvim](https://github.com/olimorris/onedarkpro.nvim)). + +<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. --> + ## Other Notable Changes {#sec-release-22.05-notable-changes} - The option [services.redis.servers](#opt-services.redis.servers) was added @@ -87,8 +238,30 @@ In addition to numerous new and upgraded packages, this release has the followin to the members of the Unix group `redis-${serverName}` through the Unix socket `/run/redis-${serverName}/redis.sock`. +- The option [virtualisation.vmVariant](#opt-virtualisation.vmVariant) was added + to allow users to make changes to the `nixos-rebuild build-vm` configuration + that do not apply to their normal system. + + The `config.system.build.vm` attribute now always exists and defaults to the + value from `vmVariant`. Configurations that import the `virtualisation/qemu-vm.nix` + module themselves will override this value, such that `vmVariant` is not used. + + Similarly [virtualisation.vmVariantWithBootloader](#opt-virtualisation.vmVariantWithBootLoader) was added. + +- The configuration portion of the `nix-daemon` module has been reworked and exposed as [nix.settings](options.html#opt-nix-settings): + * Legacy options have been mapped to the corresponding options under under [nix.settings](options.html#opt-nix.settings) but may be deprecated in the future. + * [nix.buildMachines.publicHostKey](options.html#opt-nix.buildMachines.publicHostKey) has been added. + - The `writers.writePyPy2`/`writers.writePyPy3` and corresponding `writers.writePyPy2Bin`/`writers.writePyPy3Bin` convenience functions to create executable Python 2/3 scripts using the PyPy interpreter were added. +- If you are using Wayland you can choose to use the Ozone Wayland support + in Chrome and several Electron apps by setting the environment variable + `NIXOS_OZONE_WL=1` (for example via + `environment.sessionVariables.NIXOS_OZONE_WL = "1"`). + This is not enabled by default because Ozone Wayland is + still under heavy development and behavior is not always flawless. + Furthermore, not all Electron apps use the latest Electron versions. + - The `influxdb2` package was split into `influxdb2-server` and `influxdb2-cli`, matching the split that took place upstream. A combined `influxdb2` package is still provided in this release for @@ -103,12 +276,61 @@ In addition to numerous new and upgraded packages, this release has the followin - Removing domains from `security.acme.certs._name_.extraDomainNames` will now correctly remove those domains during rebuild/renew. +- MariaDB is now offered in several versions, not just the newest one. + So if you have a need for running MariaDB 10.4 for example, you can now just set `services.mysql.package = pkgs.mariadb_104;`. + In general, it is recommended to run the newest version, to get the newest features, while sticking with an LTS version will most likely provide a more stable experience. + Sometimes software is also incompatible with the newest version of MariaDB. + - The option - [services.ssh.enableAskPassword](#opt-services.ssh.enableAskPassword) was + [programs.ssh.enableAskPassword](#opt-programs.ssh.enableAskPassword) was added, decoupling the setting of `SSH_ASKPASS` from `services.xserver.enable`. This allows easy usage in non-X11 environments, e.g. Wayland. +- [programs.ssh.knownHosts](#opt-programs.ssh.knownHosts) has gained an `extraHostNames` + option to replace `hostNames`. `hostNames` is deprecated, but still available for now. + - The `services.stubby` module was converted to a [settings-style](https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md) configuration. - The option `services.duplicati.dataDir` has been added to allow changing the location of duplicati's files. + +- A new option `boot.initrd.extraModprobeConfig` has been added which can be used to configure kernel modules that are loaded in the initrd. + +- `nixos-generate-config` now puts the dhcp configuration in `hardware-configuration.nix` instead of `configuration.nix`. + +- `fetchFromSourcehut` now allows fetching repositories recursively + using `fetchgit` or `fetchhg` if the argument `fetchSubmodules` + is set to `true`. + +- The option `services.thelounge.plugins` has been added to allow installing plugins for The Lounge. Plugins can be found in `pkgs.theLoungePlugins.plugins` and `pkgs.theLoungePlugins.themes`. + +- The `firmwareLinuxNonfree` package has been renamed to `linux-firmware`. + +- The `services.mbpfan` module was converted to a [RFC 0042](https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md) configuration. + +- The default value for `programs.spacefm.settings.graphical_su` got unset. It previously pointed to `gksu` which has been removed. + +- A new module was added for the [Starship](https://starship.rs/) shell prompt, + providing the options `programs.starship.enable` and `programs.starship.settings`. + +- `services.mattermost.plugins` has been added to allow the declarative installation of Mattermost plugins. + Plugins are automatically repackaged using autoPatchelf. + +- The `zrepl` package has been updated from 0.4.0 to 0.5: + + - The RPC protocol version was bumped; all zrepl daemons in a setup must be updated and restarted before replication can resume. + - A bug involving encrypt-on-receive has been fixed. Read the [zrepl documentation](https://zrepl.github.io/configuration/sendrecvoptions.html#job-recv-options-placeholder) and check the output of `zfs get -r encryption,zrepl:placeholder PATH_TO_ROOTFS` on the receiver. + +- Renamed option `services.openssh.challengeResponseAuthentication` to `services.openssh.kbdInteractiveAuthentication`. + Reason is that the old name has been deprecated upstream. + Using the old option name will still work, but produce a warning. + +- The option + [services.networking.networkmanager.enableFccUnlock](#opt-services.networking.networkmanager.enableFccUnlock) + was added to support FCC unlock procedures. Since release 1.18.4, the ModemManager + daemon no longer automatically performs the FCC unlock procedure by default. See + [the docs](https://modemmanager.org/docs/modemmanager/fcc-unlock/) for more details. + +- `programs.tmux` has a new option `plugins` that accepts a list of packages from the `tmuxPlugins` group. The specified packages are added to the system and loaded by `tmux`. + +<!-- To avoid merge conflicts, consider adding your item at an arbitrary place in the list instead. --> |