pyrox.dev
1# What happens during a system switch? {#sec-switching-systems}
2
3Running `nixos-rebuild switch` is one of the more common tasks under NixOS.
4This chapter explains some of the internals of this command to make it simpler
5for new module developers to configure their units correctly and to make it
6easier to understand what is happening and why for curious administrators.
7
8`nixos-rebuild`, like many deployment solutions, calls `switch-to-configuration`
9which resides in a NixOS system at `$out/bin/switch-to-configuration`. The
10script is called with the action that is to be performed like `switch`, `test`,
11`boot`. There is also the `dry-activate` action which does not really perform
12the actions but rather prints what it would do if you called it with `test`.
13This feature can be used to check what service states would be changed if the
14configuration was switched to.
15
16If the action is `switch` or `boot`, the bootloader is updated first so the
17configuration will be the next one to boot. Unless `NIXOS_NO_SYNC` is set to
18`1`, `/nix/store` is synced to disk.
19
20If the action is `switch` or `test`, the currently running system is inspected
21and the actions to switch to the new system are calculated. This process takes
22two data sources into account: `/etc/fstab` and the current systemd status.
23Mounts and swaps are read from `/etc/fstab` and the corresponding actions are
24generated. If the options of a mount are modified, for example, the proper `.mount`
25unit is reloaded (or restarted if anything else changed and it's neither the root
26mount or the nix store). The current systemd state is inspected, the difference
27between the current system and the desired configuration is calculated and
28actions are generated to get to this state. There are a lot of nuances that can
29be controlled by the units which are explained here.
30
31After calculating what should be done, the actions are carried out. The order
32of actions is always the same:
33- Stop units (`systemctl stop`)
34- Run activation script (`$out/activate`)
35- See if the activation script requested more units to restart
36- Restart systemd if needed (`systemd daemon-reexec`)
37- Forget about the failed state of units (`systemctl reset-failed`)
38- Reload systemd (`systemctl daemon-reload`)
39- Reload systemd user instances (`systemctl --user daemon-reload`)
40- Reactivate sysinit (`systemctl restart sysinit-reactivation.target`)
41- Reload units (`systemctl reload`)
42- Restart units (`systemctl restart`)
43- Start units (`systemctl start`)
44- Inspect what changed during these actions and print units that failed and
45 that were newly started
46
47By default, some units are filtered from the outputs to make it less spammy.
48This can be disabled for development or testing by setting the environment variable
49`STC_DISPLAY_ALL_UNITS=1`
50
51Most of these actions are either self-explaining but some of them have to do
52with our units or the activation script. For this reason, these topics are
53explained in the next sections.
54
55```{=include=} sections
56unit-handling.section.md
57activation-script.section.md
58non-switchable-systems.section.md
59etc-overlay.section.md
60```