diff options
Diffstat (limited to 'nixos/doc/manual/from_md/development/activation-script.section.xml')
| -rw-r--r-- | nixos/doc/manual/from_md/development/activation-script.section.xml | 150 |
1 files changed, 150 insertions, 0 deletions
diff --git a/nixos/doc/manual/from_md/development/activation-script.section.xml b/nixos/doc/manual/from_md/development/activation-script.section.xml new file mode 100644 index 00000000000..0d9e911216e --- /dev/null +++ b/nixos/doc/manual/from_md/development/activation-script.section.xml @@ -0,0 +1,150 @@ +<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 you 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> |