pyrox.dev
1# Unit handling {#sec-unit-handling}
2
3To figure out what units need to be started/stopped/restarted/reloaded, the
4script first checks the current state of the system, similar to what `systemctl
5list-units` shows. For each of the units, the script goes through the following
6checks:
7
8- Is the unit file still in the new system? If not, **stop** the service unless
9 it sets `X-StopOnRemoval` in the `[Unit]` section to `false`.
10
11- Is it a `.target` unit? If so, **start** it unless it sets
12 `RefuseManualStart` in the `[Unit]` section to `true` or `X-OnlyManualStart`
13 in the `[Unit]` section to `true`. Also **stop** the unit again unless it
14 sets `X-StopOnReconfiguration` to `false`.
15
16- Are the contents of the unit files different? They are compared by parsing
17 them and comparing their contents. If they are different but only
18 `X-Reload-Triggers` in the `[Unit]` section is changed, **reload** the unit.
19 The NixOS module system allows setting these triggers with the option
20 [systemd.services.\<name\>.reloadTriggers](#opt-systemd.services). There are
21 some additional keys in the `[Unit]` section that are ignored as well. If the
22 unit files differ in any way, the following actions are performed:
23
24 - `.path` and `.slice` units are ignored. There is no need to restart them
25 since changes in their values are applied by systemd when systemd is
26 reloaded.
27
28 - `.mount` units are **reload**ed. These mostly come from the `/etc/fstab`
29 parser.
30
31 - `.socket` units are currently ignored. This is to be fixed at a later
32 point.
33
34 - The rest of the units (mostly `.service` units) are then **reload**ed if
35 `X-ReloadIfChanged` in the `[Service]` section is set to `true` (exposed
36 via [systemd.services.\<name\>.reloadIfChanged](#opt-systemd.services)).
37 A little exception is done for units that were deactivated in the meantime,
38 for example because they require a unit that got stopped before. These
39 are **start**ed instead of reloaded.
40
41 - If the reload flag is not set, some more flags decide if the unit is
42 skipped. These flags are `X-RestartIfChanged` in the `[Service]` section
43 (exposed via
44 [systemd.services.\<name\>.restartIfChanged](#opt-systemd.services)),
45 `RefuseManualStop` in the `[Unit]` section, and `X-OnlyManualStart` in the
46 `[Unit]` section.
47
48 - Further behavior depends on the unit having `X-StopIfChanged` in the
49 `[Service]` section set to `true` (exposed via
50 [systemd.services.\<name\>.stopIfChanged](#opt-systemd.services)). This is
51 set to `true` by default and must be explicitly turned off if not wanted.
52 If the flag is enabled, the unit is **stop**ped and then **start**ed. If
53 not, the unit is **restart**ed. The goal of the flag is to make sure that
54 the new unit never runs in the old environment which is still in place
55 before the activation script is run. This behavior is different when the
56 service is socket-activated, as outlined in the following steps.
57
58 - The last thing that is taken into account is whether the unit is a service
59 and socket-activated. If `X-StopIfChanged` is **not** set, the service
60 is **restart**ed with the others. If it is set, both the service and the
61 socket are **stop**ped and the socket is **start**ed, leaving socket
62 activation to start the service when it's needed.