olmokramer / impermanence

Modules to help you handle persistent state on systems with ephemeral root storage [maintainer=@talyz]

Impermanence

Modules to help you handle persistent state on systems with ephemeral root storage.

The premises of the modules are that you

1. have a root filesystem which somehow gets wiped on reboot - e.g. using tmpfs on /
2. have a mount point where state is kept between reboots
3. want to create links from temporary storage to persistent storage, so that specified files and folders persist between reboots

There are currently two modules: one for NixOS and one for home-manager.

NixOS

To use the module, import it into your configuration with

{
  imports = [ /path/to/impermanence/nixos.nix ];
}

This adds the environment.persistence option, which is an attribute set of submodules, where the attribute name is the path to persistent storage.

Usage is shown best with an example:

{
  environment.persistence."/persistent" = {
    directories = [
      "/var/log"
      "/var/lib/bluetooth"
      "/var/lib/systemd/coredump"
      "/etc/NetworkManager/system-connections"
    ];
    files = [
      "/etc/machine-id"
      "/etc/nix/id_rsa"
    ];
  };
}

• ~”/persistent”~ is the path to your persistent storage location
• directories are all directories you want to bind mount to persistent storage
• files are all files you want to link to persistent storage

This allows for multiple different persistent storage locations. If you, for example, have one location you back up and one you don’t, you can use both by defining two separate attributes under environment.persistence.

Important note: Make sure your persistent volumes are marked with neededForBoot, otherwise you will run into problems.

home-manager

Usage of the home-manager module is very similar to the one of the NixOS module - the key differences are that the persistence option is now under home, rather than environment, and the addition of the submodule option removePrefixDirectory.

Important note: You have to use the home-manager NixOS module (in the nixos directory of home-manager’s repo) in order for this module to work as intended.

To use the module, import it into your configuration with

{
  imports = [ /path/to/impermanence/home-manager.nix ];
}

This adds the home.persistence option, which is an attribute set of submodules, where the attribute name is the path to persistent storage.

Usage is shown best with an example:

{
  home.persistence."/persistent/home/talyz" = {
    directories = [
      "Downloads"
      "Music"
      "Pictures"
      "Documents"
      "Videos"
      "VirtualBox VMs"
      ".gnupg"
      ".ssh"
      ".nixops"
      ".local/share/keyrings"
      ".local/share/direnv"
    ];
    files = [
      ".screenrc"
    ];
    allowOther = true;
  };
}

• ~”/persistent/home/talyz”~ is the path to your persistent storage location
• directories are all directories you want to link to persistent storage
• files are all files you want to link to persistent storage
• allowOther allows other users, such as root, to access files through the bind mounted directories listed in directories. Useful for sudo operations, Docker, etc. Requires the NixOS configuration programs.fuse.userAllowOther = true.

Additionally, the home-manager module allows for compatibility with dotfiles repos structured for use with GNU Stow, where the files linked to are one level deeper than where they should end up. This can be achieved by setting removePrefixDirectory to true:

{
  home.persistence."/etc/nixos/home-talyz-nixpkgs/dotfiles" = {
    removePrefixDirectory = true;
    files = [
      "screen/.screenrc"
    ];
    directories = [
      "fish/.config/fish"
    ];
  };
}

In the example, the .screenrc file and .config/fish directory should be linked to from the home directory; removePrefixDirectory removes the first part of the path when deciding where to put the links.

Note: Since this module uses the bindfs fuse filesystem for directories, the names of the directories you add will be visible in the /etc/mtab file and in the output of mount to all users.

Further reading

The following blog posts provide more information on the concept of ephemeral roots:

• https://elis.nu/blog/2020/05/nixos-tmpfs-as-root/ — @etu’s blog post walks the reader through a NixOS-on-tmpfs installation.
• https://grahamc.com/blog/erase-your-darlings — @grahamc’s blog post details why one would want to erase their state at every boot, as well as how to achieve this using ZFS snapshots.

About the name

Impermanence, also known as the philosophical problem of change, is a
philosophical concept that is addressed in a variety of religions and
philosophies. In Eastern philosophy it is best known for its role in the
Buddhist three marks of existence. It also is an element of Hinduism.