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 = [
+    "<your path to a directory to persist>"
+  ];
+  files = [
+    "<your path to a file to persist>"
+  ];
+};
+```
+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, ...} :
+<module code >
+```