diff options
Diffstat (limited to 'nixos/doc/manual/development')
3 files changed, 77 insertions, 1 deletions
diff --git a/nixos/doc/manual/development/etc-overlay.section.md b/nixos/doc/manual/development/etc-overlay.section.md new file mode 100644 index 0000000000000..e6f6d8d4ca1ef --- /dev/null +++ b/nixos/doc/manual/development/etc-overlay.section.md @@ -0,0 +1,36 @@ +# `/etc` via overlay filesystem {#sec-etc-overlay} + +::: {.note} +This is experimental and requires a kernel version >= 6.6 because it uses +new overlay features and relies on the new mount API. +::: + +Instead of using a custom perl script to activate `/etc`, you activate it via an +overlay filesystem: + +```nix +system.etc.overlay.enable = true; +``` + +Using an overlay has two benefits: + +1. it removes a dependency on perl +2. it makes activation faster (up to a few seconds) + +By default, the `/etc` overlay is mounted writable (i.e. there is a writable +upper layer). However, you can also mount `/etc` immutably (i.e. read-only) by +setting: + +```nix +system.etc.overlay.mutable = false; +``` + +The overlay is atomically replaced during system switch. However, files that +have been modified will NOT be overwritten. This is the biggest change compared +to the perl-based system. + +If you manually make changes to `/etc` on your system and then switch to a new +configuration where `system.etc.overlay.mutable = false;`, you will not be able +to see the previously made changes in `/etc` anymore. However the changes are +not completely gone, they are still in the upperdir of the previous overlay in +`/.rw-etc/upper`. diff --git a/nixos/doc/manual/development/unit-handling.section.md b/nixos/doc/manual/development/unit-handling.section.md index 32d44dbfff054..d5ba6a9529d01 100644 --- a/nixos/doc/manual/development/unit-handling.section.md +++ b/nixos/doc/manual/development/unit-handling.section.md @@ -63,3 +63,42 @@ checks: is **restart**ed with the others. If it is set, both the service and the socket are **stop**ped and the socket is **start**ed, leaving socket activation to start the service when it's needed. + +## Sysinit reactivation {#sec-sysinit-reactivation} + +[`sysinit.target`](https://www.freedesktop.org/software/systemd/man/latest/systemd.special.html#sysinit.target) +is a systemd target that encodes system initialization (i.e. early startup). A +few units that need to run very early in the bootup process are ordered to +finish before this target is reached. Probably the most notable one of these is +`systemd-tmpfiles-setup.service`. We will refer to these units as "sysinit +units". + +"Normal" systemd units, by default, are ordered AFTER `sysinit.target`. In +other words, these "normal" units expect all services ordered before +`sysinit.target` to have finished without explicity declaring this dependency +relationship for each dependency. See the [systemd +bootup](https://www.freedesktop.org/software/systemd/man/latest/bootup.html) +for more details on the bootup process. + +When restarting both a unit ordered before `sysinit.target` as well as one +after, this presents a problem because they would be started at the same time +as they do not explicitly declare their dependency relations. + +To solve this, NixOS has an artificial `sysinit-reactivation.target` which +allows you to ensure that services ordered before `sysinit.target` are +restarted correctly. This applies both to the ordering between these sysinit +services as well as ensuring that sysinit units are restarted before "normal" +units. + +To make an existing sysinit service restart correctly during system switch, you +have to declare: + +```nix +systemd.services.my-sysinit = { + requiredBy = [ "sysinit-reactivation.target" ]; + before = [ "sysinit-reactivation.target" ]; + restartTriggers = [ config.environment.etc."my-sysinit.d".source ]; +}; +``` + +You need to configure appropriate `restartTriggers` specific to your service. diff --git a/nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md b/nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md index ccadb819e061d..28c06f999dac2 100644 --- a/nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md +++ b/nixos/doc/manual/development/what-happens-during-a-system-switch.chapter.md @@ -37,7 +37,7 @@ of actions is always the same: - Forget about the failed state of units (`systemctl reset-failed`) - Reload systemd (`systemctl daemon-reload`) - Reload systemd user instances (`systemctl --user daemon-reload`) -- Set up tmpfiles (`systemd-tmpfiles --create`) +- Reactivate sysinit (`systemctl restart sysinit-reactivation.target`) - Reload units (`systemctl reload`) - Restart units (`systemctl restart`) - Start units (`systemctl start`) @@ -56,4 +56,5 @@ explained in the next sections. unit-handling.section.md activation-script.section.md non-switchable-systems.section.md +etc-overlay.section.md ``` |