pyrox.dev
1<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-unit-handling">
2 <title>Unit handling</title>
3 <para>
4 To figure out what units need to be
5 started/stopped/restarted/reloaded, the script first checks the
6 current state of the system, similar to what
7 <literal>systemctl list-units</literal> shows. For each of the
8 units, the script goes through the following checks:
9 </para>
10 <itemizedlist>
11 <listitem>
12 <para>
13 Is the unit file still in the new system? If not,
14 <emphasis role="strong">stop</emphasis> the service unless it
15 sets <literal>X-StopOnRemoval</literal> in the
16 <literal>[Unit]</literal> section to <literal>false</literal>.
17 </para>
18 </listitem>
19 <listitem>
20 <para>
21 Is it a <literal>.target</literal> unit? If so,
22 <emphasis role="strong">start</emphasis> it unless it sets
23 <literal>RefuseManualStart</literal> in the
24 <literal>[Unit]</literal> section to <literal>true</literal> or
25 <literal>X-OnlyManualStart</literal> in the
26 <literal>[Unit]</literal> section to <literal>true</literal>.
27 Also <emphasis role="strong">stop</emphasis> the unit again
28 unless it sets <literal>X-StopOnReconfiguration</literal> to
29 <literal>false</literal>.
30 </para>
31 </listitem>
32 <listitem>
33 <para>
34 Are the contents of the unit files different? They are compared
35 by parsing them and comparing their contents. If they are
36 different but only <literal>X-Reload-Triggers</literal> in the
37 <literal>[Unit]</literal> section is changed,
38 <emphasis role="strong">reload</emphasis> the unit. The NixOS
39 module system allows setting these triggers with the option
40 <link linkend="opt-systemd.services">systemd.services.<name>.reloadTriggers</link>.
41 There are some additional keys in the <literal>[Unit]</literal>
42 section that are ignored as well. If the unit files differ in
43 any way, the following actions are performed:
44 </para>
45 <itemizedlist>
46 <listitem>
47 <para>
48 <literal>.path</literal> and <literal>.slice</literal> units
49 are ignored. There is no need to restart them since changes
50 in their values are applied by systemd when systemd is
51 reloaded.
52 </para>
53 </listitem>
54 <listitem>
55 <para>
56 <literal>.mount</literal> units are
57 <emphasis role="strong">reload</emphasis>ed. These mostly
58 come from the <literal>/etc/fstab</literal> parser.
59 </para>
60 </listitem>
61 <listitem>
62 <para>
63 <literal>.socket</literal> units are currently ignored. This
64 is to be fixed at a later point.
65 </para>
66 </listitem>
67 <listitem>
68 <para>
69 The rest of the units (mostly <literal>.service</literal>
70 units) are then <emphasis role="strong">reload</emphasis>ed
71 if <literal>X-ReloadIfChanged</literal> in the
72 <literal>[Service]</literal> section is set to
73 <literal>true</literal> (exposed via
74 <link linkend="opt-systemd.services">systemd.services.<name>.reloadIfChanged</link>).
75 A little exception is done for units that were deactivated
76 in the meantime, for example because they require a unit
77 that got stopped before. These are
78 <emphasis role="strong">start</emphasis>ed instead of
79 reloaded.
80 </para>
81 </listitem>
82 <listitem>
83 <para>
84 If the reload flag is not set, some more flags decide if the
85 unit is skipped. These flags are
86 <literal>X-RestartIfChanged</literal> in the
87 <literal>[Service]</literal> section (exposed via
88 <link linkend="opt-systemd.services">systemd.services.<name>.restartIfChanged</link>),
89 <literal>RefuseManualStop</literal> in the
90 <literal>[Unit]</literal> section, and
91 <literal>X-OnlyManualStart</literal> in the
92 <literal>[Unit]</literal> section.
93 </para>
94 </listitem>
95 <listitem>
96 <para>
97 Further behavior depends on the unit having
98 <literal>X-StopIfChanged</literal> in the
99 <literal>[Service]</literal> section set to
100 <literal>true</literal> (exposed via
101 <link linkend="opt-systemd.services">systemd.services.<name>.stopIfChanged</link>).
102 This is set to <literal>true</literal> by default and must
103 be explicitly turned off if not wanted. If the flag is
104 enabled, the unit is
105 <emphasis role="strong">stop</emphasis>ped and then
106 <emphasis role="strong">start</emphasis>ed. If not, the unit
107 is <emphasis role="strong">restart</emphasis>ed. The goal of
108 the flag is to make sure that the new unit never runs in the
109 old environment which is still in place before the
110 activation script is run. This behavior is different when
111 the service is socket-activated, as outlined in the
112 following steps.
113 </para>
114 </listitem>
115 <listitem>
116 <para>
117 The last thing that is taken into account is whether the
118 unit is a service and socket-activated. If
119 <literal>X-StopIfChanged</literal> is
120 <emphasis role="strong">not</emphasis> set, the service is
121 <emphasis role="strong">restart</emphasis>ed with the
122 others. If it is set, both the service and the socket are
123 <emphasis role="strong">stop</emphasis>ped and the socket is
124 <emphasis role="strong">start</emphasis>ed, leaving socket
125 activation to start the service when it’s needed.
126 </para>
127 </listitem>
128 </itemizedlist>
129 </listitem>
130 </itemizedlist>
131</section>