You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
150 lines
6.0 KiB
150 lines
6.0 KiB
<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-activation-script">
|
|
<title>Activation script</title>
|
|
<para>
|
|
The activation script is a bash script called to activate the new
|
|
configuration which resides in a NixOS system in
|
|
<literal>$out/activate</literal>. Since its contents depend on your
|
|
system configuration, the contents may differ. This chapter explains
|
|
how the script works in general and some common NixOS snippets.
|
|
Please be aware that the script is executed on every boot and system
|
|
switch, so tasks that can be performed in other places should be
|
|
performed there (for example letting a directory of a service be
|
|
created by systemd using mechanisms like
|
|
<literal>StateDirectory</literal>,
|
|
<literal>CacheDirectory</literal>, … or if that’s not possible using
|
|
<literal>preStart</literal> of the service).
|
|
</para>
|
|
<para>
|
|
Activation scripts are defined as snippets using
|
|
<xref linkend="opt-system.activationScripts" />. They can either be
|
|
a simple multiline string or an attribute set that can depend on
|
|
other snippets. The builder for the activation script will take
|
|
these dependencies into account and order the snippets accordingly.
|
|
As a simple example:
|
|
</para>
|
|
<programlisting language="bash">
|
|
system.activationScripts.my-activation-script = {
|
|
deps = [ "etc" ];
|
|
# supportsDryActivation = true;
|
|
text = ''
|
|
echo "Hallo i bims"
|
|
'';
|
|
};
|
|
</programlisting>
|
|
<para>
|
|
This example creates an activation script snippet that is run after
|
|
the <literal>etc</literal> snippet. The special variable
|
|
<literal>supportsDryActivation</literal> can be set so the snippet
|
|
is also run when <literal>nixos-rebuild dry-activate</literal> is
|
|
run. To differentiate between real and dry activation, the
|
|
<literal>$NIXOS_ACTION</literal> environment variable can be read
|
|
which is set to <literal>dry-activate</literal> when a dry
|
|
activation is done.
|
|
</para>
|
|
<para>
|
|
An activation script can write to special files instructing
|
|
<literal>switch-to-configuration</literal> to restart/reload units.
|
|
The script will take these requests into account and will
|
|
incorperate the unit configuration as described above. This means
|
|
that the activation script will <quote>fake</quote> a modified unit
|
|
file and <literal>switch-to-configuration</literal> will act
|
|
accordingly. By doing so, configuration like
|
|
<link linkend="opt-systemd.services">systemd.services.<name>.restartIfChanged</link>
|
|
is respected. Since the activation script is run
|
|
<emphasis role="strong">after</emphasis> services are already
|
|
stopped,
|
|
<link linkend="opt-systemd.services">systemd.services.<name>.stopIfChanged</link>
|
|
cannot be taken into account anymore and the unit is always
|
|
restarted instead of being stopped and started afterwards.
|
|
</para>
|
|
<para>
|
|
The files that can be written to are
|
|
<literal>/run/nixos/activation-restart-list</literal> and
|
|
<literal>/run/nixos/activation-reload-list</literal> with their
|
|
respective counterparts for dry activation being
|
|
<literal>/run/nixos/dry-activation-restart-list</literal> and
|
|
<literal>/run/nixos/dry-activation-reload-list</literal>. Those
|
|
files can contain newline-separated lists of unit names where
|
|
duplicates are being ignored. These files are not create
|
|
automatically and activation scripts must take the possiblility into
|
|
account that they have to create them first.
|
|
</para>
|
|
<section xml:id="sec-activation-script-nixos-snippets">
|
|
<title>NixOS snippets</title>
|
|
<para>
|
|
There are some snippets NixOS enables by default because disabling
|
|
them would most likely break your system. This section lists a few
|
|
of them and what they do:
|
|
</para>
|
|
<itemizedlist spacing="compact">
|
|
<listitem>
|
|
<para>
|
|
<literal>binsh</literal> creates <literal>/bin/sh</literal>
|
|
which points to the runtime shell
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>etc</literal> sets up the contents of
|
|
<literal>/etc</literal>, this includes systemd units and
|
|
excludes <literal>/etc/passwd</literal>,
|
|
<literal>/etc/group</literal>, and
|
|
<literal>/etc/shadow</literal> (which are managed by the
|
|
<literal>users</literal> snippet)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>hostname</literal> sets the system’s hostname in the
|
|
kernel (not in <literal>/etc</literal>)
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>modprobe</literal> sets the path to the
|
|
<literal>modprobe</literal> binary for module auto-loading
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>nix</literal> prepares the nix store and adds a
|
|
default initial channel
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>specialfs</literal> is responsible for mounting
|
|
filesystems like <literal>/proc</literal> and
|
|
<literal>sys</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>users</literal> creates and removes users and groups
|
|
by managing <literal>/etc/passwd</literal>,
|
|
<literal>/etc/group</literal> and
|
|
<literal>/etc/shadow</literal>. This also creates home
|
|
directories
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>usrbinenv</literal> creates
|
|
<literal>/usr/bin/env</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>var</literal> creates some directories in
|
|
<literal>/var</literal> that are not service-specific
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<literal>wrappers</literal> creates setuid wrappers like
|
|
<literal>ping</literal> and <literal>sudo</literal>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</section>
|
|
|