impermanence/README.org

* 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

    #+begin_src nix
      {
        imports = [ /path/to/impermanence/nixos.nix ];
      }
    #+end_src

    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:

    #+begin_src nix
      {
        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"
          ];
        };
      }
    #+end_src

    - ~"/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 (only in ~/etc~ for now)

    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~.

    To use the module, import it into your configuration with

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

    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:

    #+begin_src nix
      {
        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;
        };
      }
    #+end_src

    - ~"/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 [[https://www.gnu.org/software/stow/][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~:

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

    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/ --- [[https://github.com/etu/][@etu]]'s blog post walks
     the reader through a NixOS-on-tmpfs installation.
   - https://grahamc.com/blog/erase-your-darlings --- [[https://github.com/grahamc/][@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.