pyrox.dev
1<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-activation-script">
2 <title>Activation script</title>
3 <para>
4 The activation script is a bash script called to activate the new
5 configuration which resides in a NixOS system in
6 <literal>$out/activate</literal>. Since its contents depend on your
7 system configuration, the contents may differ. This chapter explains
8 how the script works in general and some common NixOS snippets.
9 Please be aware that the script is executed on every boot and system
10 switch, so tasks that can be performed in other places should be
11 performed there (for example letting a directory of a service be
12 created by systemd using mechanisms like
13 <literal>StateDirectory</literal>,
14 <literal>CacheDirectory</literal>, … or if that’s not possible using
15 <literal>preStart</literal> of the service).
16 </para>
17 <para>
18 Activation scripts are defined as snippets using
19 <xref linkend="opt-system.activationScripts" />. They can either be
20 a simple multiline string or an attribute set that can depend on
21 other snippets. The builder for the activation script will take
22 these dependencies into account and order the snippets accordingly.
23 As a simple example:
24 </para>
25 <programlisting language="bash">
26system.activationScripts.my-activation-script = {
27 deps = [ "etc" ];
28 # supportsDryActivation = true;
29 text = ''
30 echo "Hallo i bims"
31 '';
32};
33</programlisting>
34 <para>
35 This example creates an activation script snippet that is run after
36 the <literal>etc</literal> snippet. The special variable
37 <literal>supportsDryActivation</literal> can be set so the snippet
38 is also run when <literal>nixos-rebuild dry-activate</literal> is
39 run. To differentiate between real and dry activation, the
40 <literal>$NIXOS_ACTION</literal> environment variable can be read
41 which is set to <literal>dry-activate</literal> when a dry
42 activation is done.
43 </para>
44 <para>
45 An activation script can write to special files instructing
46 <literal>switch-to-configuration</literal> to restart/reload units.
47 The script will take these requests into account and will
48 incorperate the unit configuration as described above. This means
49 that the activation script will <quote>fake</quote> a modified unit
50 file and <literal>switch-to-configuration</literal> will act
51 accordingly. By doing so, configuration like
52 <link linkend="opt-systemd.services">systemd.services.<name>.restartIfChanged</link>
53 is respected. Since the activation script is run
54 <emphasis role="strong">after</emphasis> services are already
55 stopped,
56 <link linkend="opt-systemd.services">systemd.services.<name>.stopIfChanged</link>
57 cannot be taken into account anymore and the unit is always
58 restarted instead of being stopped and started afterwards.
59 </para>
60 <para>
61 The files that can be written to are
62 <literal>/run/nixos/activation-restart-list</literal> and
63 <literal>/run/nixos/activation-reload-list</literal> with their
64 respective counterparts for dry activation being
65 <literal>/run/nixos/dry-activation-restart-list</literal> and
66 <literal>/run/nixos/dry-activation-reload-list</literal>. Those
67 files can contain newline-separated lists of unit names where
68 duplicates are being ignored. These files are not create
69 automatically and activation scripts must take the possiblility into
70 account that they have to create them first.
71 </para>
72 <section xml:id="sec-activation-script-nixos-snippets">
73 <title>NixOS snippets</title>
74 <para>
75 There are some snippets NixOS enables by default because disabling
76 them would most likely break your system. This section lists a few
77 of them and what they do:
78 </para>
79 <itemizedlist spacing="compact">
80 <listitem>
81 <para>
82 <literal>binsh</literal> creates <literal>/bin/sh</literal>
83 which points to the runtime shell
84 </para>
85 </listitem>
86 <listitem>
87 <para>
88 <literal>etc</literal> sets up the contents of
89 <literal>/etc</literal>, this includes systemd units and
90 excludes <literal>/etc/passwd</literal>,
91 <literal>/etc/group</literal>, and
92 <literal>/etc/shadow</literal> (which are managed by the
93 <literal>users</literal> snippet)
94 </para>
95 </listitem>
96 <listitem>
97 <para>
98 <literal>hostname</literal> sets the system’s hostname in the
99 kernel (not in <literal>/etc</literal>)
100 </para>
101 </listitem>
102 <listitem>
103 <para>
104 <literal>modprobe</literal> sets the path to the
105 <literal>modprobe</literal> binary for module auto-loading
106 </para>
107 </listitem>
108 <listitem>
109 <para>
110 <literal>nix</literal> prepares the nix store and adds a
111 default initial channel
112 </para>
113 </listitem>
114 <listitem>
115 <para>
116 <literal>specialfs</literal> is responsible for mounting
117 filesystems like <literal>/proc</literal> and
118 <literal>sys</literal>
119 </para>
120 </listitem>
121 <listitem>
122 <para>
123 <literal>users</literal> creates and removes users and groups
124 by managing <literal>/etc/passwd</literal>,
125 <literal>/etc/group</literal> and
126 <literal>/etc/shadow</literal>. This also creates home
127 directories
128 </para>
129 </listitem>
130 <listitem>
131 <para>
132 <literal>usrbinenv</literal> creates
133 <literal>/usr/bin/env</literal>
134 </para>
135 </listitem>
136 <listitem>
137 <para>
138 <literal>var</literal> creates some directories in
139 <literal>/var</literal> that are not service-specific
140 </para>
141 </listitem>
142 <listitem>
143 <para>
144 <literal>wrappers</literal> creates setuid wrappers like
145 <literal>ping</literal> and <literal>sudo</literal>
146 </para>
147 </listitem>
148 </itemizedlist>
149 </section>
150</section>