Differences

This shows you the differences between two versions of the page.

--- manuals:distributions:nixos:impermanence [2024/10/15 19:42] – created aither
+++ manuals:distributions:nixos:impermanence [2024/10/29 17:03] (current) – aither
@@ Line 1: / Line 1: @@
+<page>manuals:distributions:nixos:impermanence</page>
 ====== NixOS Impermanence ======
-<note warning>
+This page describes usage of [[https://github.com/nix-community/impermanence|NixOS Impermanence]] module
-This is a work in progress
+at vpsFree.cz. We support impermanence with root filesystem in a temporary ZFS dataset that is
-</note>
+provided by our platform. It is necessary to move the Nix store to a subdataset, which can be
+done automatically [[#using_os_template|using the OS template for impermanence]], or you can
+set it up [[#manual_configuration|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.
+===== Using OS template =====
+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:
+<code>
+cd /etc/nixos
+rm -rf impermanence
+git clone https://github.com/nix-community/impermanence
+</code>
+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|manual configuration]] if you'd like to
+enable impermanence on an existing VPS.
+===== Manual configuration =====
+==== 1. Create a NixOS VPS ====
+Create a new VPS and let it start. You can also reuse your existing NixOS VPS.
+==== 2. Start the VPS in rescue mode ====
+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.
+==== 3. Create VPS subdataset for the Nix store ====
+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.
+==== 4. Move the Nix store to the subdataset ====
+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.
-===== 1. Create a NixOS VPS =====
-===== 2. Start the VPS in rescue mode =====
-===== 3. Create VPS subdataset for the Nix store =====
-===== 4. Move the Nix store to the subdataset =====
 <code bash>
 mv /mnt/vps/nix/* /nix/
 </code>
-===== 5. Mount root file system to /persistent =====
+==== 5. Mount root dataset to /persistent ====
-===== 6. Restart the VPS =====
+In the impermanence mode, your root file system will be temporary and cleared on
-===== 7. Edit your configuration and add the impermanence module =====
+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''.
+==== 6. Restart the VPS ====
+Now restart the VPS, you will leave the rescue mode.
+==== 7. Edit your configuration and add the impermanence module ====
 Clone the impermanence module repository into ''/etc/nixos''. This requires git, if you
-don't have it in your system, you can use ''nix-shell -p git''.
+don't have it in your system, you can use e.g. ''nix-shell -p git''.
 <code bash>
@@ Line 23: / Line 75: @@
 git clone https://github.com/nix-community/impermanence.git
 </code>
+Extend your configuration and add the impermanence module:
 <file nix /etc/nixos/configuration.nix>
@@ Line 44: / Line 98: @@
 }
 </file>
-===== 8. Turn on impermanence feature =====
+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:
+<code bash>
+nixos-rebuild boot
+</code>
+==== 8. Turn on impermanence feature ====
+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:
+<code>
+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
+</code>
+''/'' is based in a temporary dataset, ''11327'' is used for ''/persistent'' and ''11327/nix''
+contains the Nix store.

Knowledge base

User Tools

Site Tools

Differences

Page Tools