nixos/doc/manual/development/activation-script.section.md

   1 # Activation script {#sec-activation-script}
   2
   3 The activation script is a bash script called to activate the new
   4 configuration which resides in a NixOS system in `$out/activate`. Since its
   5 contents depend on your system configuration, the contents may differ.
   6 This chapter explains how the script works in general and some common NixOS
   7 snippets. Please be aware that the script is executed on every boot and system
   8 switch, so tasks that can be performed in other places should be performed
   9 there (for example letting a directory of a service be created by systemd using
  10 mechanisms like `StateDirectory`, `CacheDirectory`, ... or if that's not
  11 possible using `preStart` of the service).
  12
  13 Activation scripts are defined as snippets using
  14 [](#opt-system.activationScripts). They can either be a simple multiline string
  15 or an attribute set that can depend on other snippets. The builder for the
  16 activation script will take these dependencies into account and order the
  17 snippets accordingly. As a simple example:
  18
  19 ```nix
  20 {
  21   system.activationScripts.my-activation-script = {
  22     deps = [ "etc" ];
  23     # supportsDryActivation = true;
  24     text = ''
  25       echo "Hallo i bims"
  26     '';
  27   };
  28 }
  29 ```
  30
  31 This example creates an activation script snippet that is run after the `etc`
  32 snippet. The special variable `supportsDryActivation` can be set so the snippet
  33 is also run when `nixos-rebuild dry-activate` is run. To differentiate between
  34 real and dry activation, the `$NIXOS_ACTION` environment variable can be
  35 read which is set to `dry-activate` when a dry activation is done.
  36
  37 An activation script can write to special files instructing
  38 `switch-to-configuration` to restart/reload units. The script will take these
  39 requests into account and will incorporate the unit configuration as described
  40 above. This means that the activation script will "fake" a modified unit file
  41 and `switch-to-configuration` will act accordingly. By doing so, configuration
  42 like [systemd.services.\<name\>.restartIfChanged](#opt-systemd.services) is
  43 respected. Since the activation script is run **after** services are already
  44 stopped, [systemd.services.\<name\>.stopIfChanged](#opt-systemd.services)
  45 cannot be taken into account anymore and the unit is always restarted instead
  46 of being stopped and started afterwards.
  47
  48 The files that can be written to are `/run/nixos/activation-restart-list` and
  49 `/run/nixos/activation-reload-list` with their respective counterparts for
  50 dry activation being `/run/nixos/dry-activation-restart-list` and
  51 `/run/nixos/dry-activation-reload-list`. Those files can contain
  52 newline-separated lists of unit names where duplicates are being ignored. These
  53 files are not create automatically and activation scripts must take the
  54 possibility into account that they have to create them first.
  55
  56 ## NixOS snippets {#sec-activation-script-nixos-snippets}
  57
  58 There are some snippets NixOS enables by default because disabling them would
  59 most likely break your system. This section lists a few of them and what they
  60 do:
  61
  62 - `binsh` creates `/bin/sh` which points to the runtime shell
  63 - `etc` sets up the contents of `/etc`, this includes systemd units and
  64   excludes `/etc/passwd`, `/etc/group`, and `/etc/shadow` (which are managed by
  65   the `users` snippet)
  66 - `hostname` sets the system's hostname in the kernel (not in `/etc`)
  67 - `modprobe` sets the path to the `modprobe` binary for module auto-loading
  68 - `nix` prepares the nix store and adds a default initial channel
  69 - `specialfs` is responsible for mounting filesystems like `/proc` and `sys`
  70 - `users` creates and removes users and groups by managing `/etc/passwd`,
  71   `/etc/group` and `/etc/shadow`. This also creates home directories
  72 - `usrbinenv` creates `/usr/bin/env`
  73 - `var` creates some directories in `/var` that are not service-specific
  74 - `wrappers` creates setuid wrappers like `sudo`