path: root/nixos/doc/manual/from_md/development/activation-script.section.xml

<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 = [ &quot;etc&quot; ];
  # supportsDryActivation = true;
  text = ''
    echo &quot;Hallo i bims&quot;
  '';
};
</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.&lt;name&gt;.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.&lt;name&gt;.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>