NixOS Impermanence

This page describes usage of NixOS Impermanence module at vpsFree.cz. We support impermanence with root filesystem in a temporary ZFS dataset that is provided by our platform. It is necessary to move the Nix store to a subdataset, which can be done automatically using the OS template for impermanence, or you can set it up manually.

Please note that when you enable impermanence, the root file system is indeed temporary and its data reset on each VPS start. The temporary dataset also isn't backed up. Be mindful of where you store your data. If it isn't in a persistent location, it will be lost.

vpsAdmin contains OS templates where the impermanence module is preconfigured. When creating a new VPS, choose the appropriate template (impermanence is in its name). The new VPS will have /nix separated in a subdataset. The root dataset will be mounted to /persistent and initial impermanence configuration will be deployed. See /etc/nixos/configuration.nix. Copy of the impermanence module is stored at /etc/nixos/impermanence, you might want to update it to the latest version, e.g. by cloning the git repository to the same path:

cd /etc/nixos
rm -rf impermanence
git clone https://github.com/nix-community/impermanence

Note that reinstalling the VPS will be ineffective, as reinstall changes only the root dataset. It will not touch the Nix store when it is moved to a subdataset. For the same reason, you cannot convert an existing VPS to impermanence using reinstall. The OS template will auto-configure the VPS only on creation. See manual configuration if you'd like to enable impermanence on an existing VPS.

Create a new VPS and let it start. You can also reuse your existing NixOS VPS.

In VPS details, use form Boot VPS from template (rescue mode). It's best to choose a different distribution than NixOS, so that there's no /nix directory. Use e.g. Alpine or Debian.

In VPS details, create subdataset nix, which will be mounted to /nix (this is why we didn't want to boot into NixOS in the previous step). You might have to free some diskspace in order to be able to create the dataset, you can do that by shrinking the root dataset.

Login to the VPS while in rescue mode, either over SSH or use the remote console. The root dataset is mounted at /mnt/vps and our new subdataset nix is mounted at /nix. We want to move the Nix store from the root dataset to the subdataset.

mv /mnt/vps/nix/* /nix/

In the impermanence mode, your root file system will be temporary and cleared on every start. We must mount our persistent storage to /persistent. This can be either the root dataset, or you can create another subdataset for that purpose. We'll use the root dataset. In VPS details, click on Mount link of the first listed dataset (its name is the VPS ID) and mount it to /persistent.

Now restart the VPS, you will leave the rescue mode.

Clone the impermanence module repository into /etc/nixos. This requires git, if you don't have it in your system, you can use e.g. nix-shell -p git.

cd /etc/nixos
git clone https://github.com/nix-community/impermanence.git

Extend your configuration and add the impermanence module:

/etc/nixos/configuration.nix

{ config, ... }:
{
  imports = [
    ./impermanence/nixos.nix
  ];
 
  environment.persistence."/persistent" = {
    hideMounts = true;
    directories = [
      "/etc/nixos"
      "/var/log"
      "/var/lib/nixos"
    ];
    files = [
      "/etc/machine-id"
    ];
  };
}

Note that /persistent must match the dataset mountpoint, but you can choose an arbitrary name if you like. The datasets will be mounted by vpsAdminOS, so you don't have to configure fileSystems entries yourself.

When you're done, deploy the new configuration for the next restart:

nixos-rebuild boot

In VPS details, enable the NixOS Impermanence feature. This will configure your VPS so that it is started with a clean, temporary dataset. Its contents will be lost on every reboot and it's not backed up. Turning on the feature will cause the VPS to restart into the configuration we've prepared in step 7.

Inside the VPS, you can check the mounted filesystems:

root@nixos:/# df -hT | grep zfs
tank/ct/11327.impermanence-c5a8b7 zfs     10G  768K   10G   1% /
tank/ct/11327/nix                 zfs     20G  1.1G   19G   6% /nix
tank/ct/11327                     zfs    100G  7.7M  120G   1% /persistent

/ is based in a temporary dataset, 11327 is used for /persistent and 11327/nix contains the Nix store.