From ed07b584f5a4917a4be02e0e243045085e214482 Mon Sep 17 00:00:00 2001 From: Dennis Frieberg Date: Sun, 1 Oct 2023 11:54:35 +0200 Subject: [PATCH] added impermanence documentation --- README.md | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/README.md b/README.md index 853b2e5..80a62ee 100644 --- a/README.md +++ b/README.md @@ -235,3 +235,46 @@ Afterwards the secret should be available in `/run/secrets/example-key`. If the accessing process is not root it must be member of the group `config.users.groups.keys` for systemd services this can be archived by setting `serviceConfig.SupplementaryGroups = [ config.users.groups.keys.name ];` it the service configuration. + +## impermanence + +These machines are setup with `"/"` as a tmpfs. This is there to keep the machines clean. So no clutter in home +directories, no weird ad-hoc solutions of botching something into `/opt/` or something like this. All will be +gone at reboot. + +But there are some files that we want to survive reboots, for example logs or ssh keys. The solution to this is +to have a persistent storage mounted at `/persist` and automatically bind mount the paths of persistent things +to the right places. To set this up we are using the impermanence module. In our configuration this is loaded with +some default files to bind mount (ssh keys, machine-id some nixos specific things). That we have on all machines. + +If you keep your application data (like recommended) on a separate partition, the chances are you don't need +to interact with this, as most configuration files will be in the nix store anyway. If the application wants these nix +store files in certain directories you should use `environment.etc` family of options (consult the nixos documentation +for this). This is for mutable files that are not core application data. (Like ssh keys, for a mailserver one could +think about the hash files (not the db files) of an alias map (if one don't want to manage that with +the nix store), things like that). + +This should not be (but could be) used for large application databases. It would be more appropriate to mount +its own filesystem for things like that. For small configuration files that are not in the nix-store, +that might be the appropriate solution. + +By default the storage is called `persist` and the default path for it is `/persist`. These can be changed +with the `impermanence.name` and `impermanence.storagePath` options. To add paths to this storage you do the +following. + +``` +environment.persistence.${config.impermanence.name} = { + directories = [ + "" + ]; + files = [ + "" + ]; +}; +``` +For this to work `config` must be binded by the function arguments of you module. So the start of your module looks +something like this: +``` +{lib, pkgs, config, ...} : + +```