diff options
Diffstat (limited to 'nixos/doc/manual')
11 files changed, 741 insertions, 4 deletions
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 00000000000..df683662404 --- /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 0b2ad60a878..21286cdbd2b 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/unit-handling.section.md b/nixos/doc/manual/development/unit-handling.section.md new file mode 100644 index 00000000000..d477f2c860f --- /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 00000000000..aad82831a3c --- /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/from_md/development/activation-script.section.xml b/nixos/doc/manual/from_md/development/activation-script.section.xml new file mode 100644 index 00000000000..0d9e911216e --- /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/unit-handling.section.xml b/nixos/doc/manual/from_md/development/unit-handling.section.xml new file mode 100644 index 00000000000..a6a654042f6 --- /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 00000000000..66ba792ddac --- /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/installation/installing-pxe.section.xml b/nixos/doc/manual/from_md/installation/installing-pxe.section.xml index 1dd15ddacba..94172de65ea 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-2205.section.xml b/nixos/doc/manual/from_md/release-notes/rl-2205.section.xml index 5d0a9dc76ea..7502214c86b 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 @@ -42,6 +42,14 @@ 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> </section> <section xml:id="sec-release-22.05-new-services"> @@ -116,6 +124,14 @@ </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 @@ -146,6 +162,14 @@ </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 @@ -170,6 +194,13 @@ </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>. @@ -207,6 +238,13 @@ <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"> @@ -235,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 @@ -252,6 +320,17 @@ </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 @@ -312,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 @@ -523,6 +618,15 @@ 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> @@ -777,6 +881,13 @@ </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 @@ -869,6 +980,17 @@ </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 diff --git a/nixos/doc/manual/installation/installing-pxe.section.md b/nixos/doc/manual/installation/installing-pxe.section.md index 2016a258251..4fbd6525f8c 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/release-notes/rl-2205.section.md b/nixos/doc/manual/release-notes/rl-2205.section.md index 7846513c607..c96f898505a 100644 --- a/nixos/doc/manual/release-notes/rl-2205.section.md +++ b/nixos/doc/manual/release-notes/rl-2205.section.md @@ -17,6 +17,8 @@ In addition to numerous new and upgraded packages, this release has the followin 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). @@ -37,6 +39,8 @@ In addition to numerous new and upgraded packages, this release has the followin - [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). @@ -45,12 +49,17 @@ In addition to numerous new and upgraded packages, this release has the followin - [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 @@ -62,6 +71,8 @@ In addition to numerous new and upgraded packages, this release has the followin - [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} @@ -78,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 @@ -85,6 +111,8 @@ 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. @@ -102,6 +130,10 @@ 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. @@ -168,6 +200,7 @@ In addition to numerous new and upgraded packages, this release has the followin - `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 @@ -263,6 +296,8 @@ In addition to numerous new and upgraded packages, this release has the followin - 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`. @@ -290,6 +325,12 @@ In addition to numerous new and upgraded packages, this release has the followin 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. --> |