pyrox.dev
1# Activation script {#sec-activation-script}
2
3The activation script is a bash script called to activate the new
4configuration which resides in a NixOS system in `$out/activate`. Since its
5contents depend on your system configuration, the contents may differ.
6This chapter explains how the script works in general and some common NixOS
7snippets. Please be aware that the script is executed on every boot and system
8switch, so tasks that can be performed in other places should be performed
9there (for example letting a directory of a service be created by systemd using
10mechanisms like `StateDirectory`, `CacheDirectory`, ... or if that's not
11possible using `preStart` of the service).
12
13Activation scripts are defined as snippets using
14[](#opt-system.activationScripts). They can either be a simple multiline string
15or an attribute set that can depend on other snippets. The builder for the
16activation script will take these dependencies into account and order the
17snippets 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
31This example creates an activation script snippet that is run after the `etc`
32snippet. The special variable `supportsDryActivation` can be set so the snippet
33is also run when `nixos-rebuild dry-activate` is run. To differentiate between
34real and dry activation, the `$NIXOS_ACTION` environment variable can be
35read which is set to `dry-activate` when a dry activation is done.
36
37An activation script can write to special files instructing
38`switch-to-configuration` to restart/reload units. The script will take these
39requests into account and will incorporate the unit configuration as described
40above. This means that the activation script will "fake" a modified unit file
41and `switch-to-configuration` will act accordingly. By doing so, configuration
42like [systemd.services.\<name\>.restartIfChanged](#opt-systemd.services) is
43respected. Since the activation script is run **after** services are already
44stopped, [systemd.services.\<name\>.stopIfChanged](#opt-systemd.services)
45cannot be taken into account anymore and the unit is always restarted instead
46of being stopped and started afterwards.
47
48The files that can be written to are `/run/nixos/activation-restart-list` and
49`/run/nixos/activation-reload-list` with their respective counterparts for
50dry activation being `/run/nixos/dry-activation-restart-list` and
51`/run/nixos/dry-activation-reload-list`. Those files can contain
52newline-separated lists of unit names where duplicates are being ignored. These
53files are not create automatically and activation scripts must take the
54possibility into account that they have to create them first.
55
56## NixOS snippets {#sec-activation-script-nixos-snippets}
57
58There are some snippets NixOS enables by default because disabling them would
59most likely break your system. This section lists a few of them and what they
60do:
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`