pyrox.dev
1<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">
2 <title>What happens during a system switch?</title>
3 <para>
4 Running <literal>nixos-rebuild switch</literal> is one of the more
5 common tasks under NixOS. This chapter explains some of the
6 internals of this command to make it simpler for new module
7 developers to configure their units correctly and to make it easier
8 to understand what is happening and why for curious administrators.
9 </para>
10 <para>
11 <literal>nixos-rebuild</literal>, like many deployment solutions,
12 calls <literal>switch-to-configuration</literal> which resides in a
13 NixOS system at <literal>$out/bin/switch-to-configuration</literal>.
14 The script is called with the action that is to be performed like
15 <literal>switch</literal>, <literal>test</literal>,
16 <literal>boot</literal>. There is also the
17 <literal>dry-activate</literal> action which does not really perform
18 the actions but rather prints what it would do if you called it with
19 <literal>test</literal>. This feature can be used to check what
20 service states would be changed if the configuration was switched
21 to.
22 </para>
23 <para>
24 If the action is <literal>switch</literal> or
25 <literal>boot</literal>, the bootloader is updated first so the
26 configuration will be the next one to boot. Unless
27 <literal>NIXOS_NO_SYNC</literal> is set to <literal>1</literal>,
28 <literal>/nix/store</literal> is synced to disk.
29 </para>
30 <para>
31 If the action is <literal>switch</literal> or
32 <literal>test</literal>, the currently running system is inspected
33 and the actions to switch to the new system are calculated. This
34 process takes two data sources into account:
35 <literal>/etc/fstab</literal> and the current systemd status. Mounts
36 and swaps are read from <literal>/etc/fstab</literal> and the
37 corresponding actions are generated. If a new mount is added, for
38 example, the proper <literal>.mount</literal> unit is marked to be
39 started. The current systemd state is inspected, the difference
40 between the current system and the desired configuration is
41 calculated and actions are generated to get to this state. There are
42 a lot of nuances that can be controlled by the units which are
43 explained here.
44 </para>
45 <para>
46 After calculating what should be done, the actions are carried out.
47 The order of actions is always the same:
48 </para>
49 <itemizedlist spacing="compact">
50 <listitem>
51 <para>
52 Stop units (<literal>systemctl stop</literal>)
53 </para>
54 </listitem>
55 <listitem>
56 <para>
57 Run activation script (<literal>$out/activate</literal>)
58 </para>
59 </listitem>
60 <listitem>
61 <para>
62 See if the activation script requested more units to restart
63 </para>
64 </listitem>
65 <listitem>
66 <para>
67 Restart systemd if needed
68 (<literal>systemd daemon-reexec</literal>)
69 </para>
70 </listitem>
71 <listitem>
72 <para>
73 Forget about the failed state of units
74 (<literal>systemctl reset-failed</literal>)
75 </para>
76 </listitem>
77 <listitem>
78 <para>
79 Reload systemd (<literal>systemctl daemon-reload</literal>)
80 </para>
81 </listitem>
82 <listitem>
83 <para>
84 Reload systemd user instances
85 (<literal>systemctl --user daemon-reload</literal>)
86 </para>
87 </listitem>
88 <listitem>
89 <para>
90 Set up tmpfiles (<literal>systemd-tmpfiles --create</literal>)
91 </para>
92 </listitem>
93 <listitem>
94 <para>
95 Reload units (<literal>systemctl reload</literal>)
96 </para>
97 </listitem>
98 <listitem>
99 <para>
100 Restart units (<literal>systemctl restart</literal>)
101 </para>
102 </listitem>
103 <listitem>
104 <para>
105 Start units (<literal>systemctl start</literal>)
106 </para>
107 </listitem>
108 <listitem>
109 <para>
110 Inspect what changed during these actions and print units that
111 failed and that were newly started
112 </para>
113 </listitem>
114 </itemizedlist>
115 <para>
116 Most of these actions are either self-explaining but some of them
117 have to do with our units or the activation script. For this reason,
118 these topics are explained in the next sections.
119 </para>
120 <xi:include href="unit-handling.section.xml" />
121 <xi:include href="activation-script.section.xml" />
122</chapter>