Differences

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

--- manuals:distributions:nixos:impermanence [2024/10/16 09:13] – aither
+++ manuals:distributions:nixos:impermanence [2026/03/12 11:19] (current) – nix flakes 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]].
-===== 1. Create a NixOS VPS =====
+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 impermanence 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
+flake-based NixOS configuration will be deployed to ''/etc/nixos'', see ''/etc/nixos/flake.nix''
+and ''/etc/nixos/configuration.nix''. The template also writes ''/etc/nixos/flake.lock'', so
+versions of vpsAdminOS, ''nixpkgs'' and impermanence are pinned together.
+Impermanence is included as a flake input. To update it, update the flake lock and rebuild
+the system:
+<code bash>
+cd /etc/nixos
+nix flake lock --update-input impermanence
+nixos-rebuild switch --flake /etc/nixos#vps
+</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 =====
+==== 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.
+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 =====
+==== 3. Create VPS subdataset for the Nix store ====
-In VPS details, create dataset ''nix'', which will be mounted to ''/nix'' (this is why we didn't
+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 be shrinking the root dataset.
+able to create the dataset, you can do that by shrinking the root dataset.
-===== 4. Move the Nix store to the subdataset =====
+==== 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
@@ Line 27: / Line 59: @@
 </code>
-===== 5. Mount root dataset to /persistent =====
+==== 5. Mount root dataset to /persistent ====
-In the impermanence mode, your root filesystem will be temporarily and cleared on
+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
@@ Line 34: / Line 66: @@
 (its name is the VPS ID) and mount it to ''/persistent''.
-===== 6. Restart the VPS =====
+==== 6. Restart the VPS ====
 Now restart the VPS, you will leave the rescue mode.
-===== 7. Edit your configuration and add the impermanence module =====
+==== 7. Edit your flake configuration and add impermanence ====
-Clone the impermanence module repository into ''/etc/nixos''. This requires git, if you
+vpsAdminOS templates enable flakes by default. Create ''/etc/nixos/flake.nix'' and
-don't have it in your system, you can use e.g. ''nix-shell -p git''.
+keep your local settings in ''/etc/nixos/configuration.nix''. The example below follows the
+stable ''nixpkgs'' branch used by vpsAdminOS. If you're using another stable release, use the
+matching ''nixos-YY.MM'' branch. If you're using NixOS unstable, replace
+''github:NixOS/nixpkgs/nixos-25.11'' with ''github:NixOS/nixpkgs/nixos-unstable'' and
+replace the stable container module line in the example with
+''vpsadminos.nixosModules.containerUnstable''.
-<code bash>
+<file nix /etc/nixos/flake.nix>
-cd /etc/nixos
+{
-git clone https://github.com/nix-community/impermanence.git
+  inputs = {
-</code>
+    vpsadminos.url = "github:vpsfreecz/vpsadminos";
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-25.11";
+    impermanence.url = "github:nix-community/impermanence";
+  };
-Extend your configuration and add the impermanence module:
+  outputs = { nixpkgs, vpsadminos, impermanence, ... }:
+    let
+      containerModule = "container_${builtins.replaceStrings [ "." ] [ "_" ] nixpkgs.lib.trivial.release}";
+    in
+    {
+      nixosConfigurations.vps = nixpkgs.lib.nixosSystem {
+        system = "x86_64-linux";
+        modules = [
+          vpsadminos.nixosModules.${containerModule}
+          impermanence.nixosModules.impermanence
+          ./configuration.nix
+        ];
+      };
+    };
+}
+</file>
+Then extend your configuration and add the persistence settings:
 <file nix /etc/nixos/configuration.nix>
-{ config, ... }:
+{ ... }:
 {
-  imports = [
-    ./impermanence/nixos.nix
-  ];
   environment.persistence."/persistent" = {
     hideMounts = true;
@@ Line 68: / Line 121: @@
 }
 </file>
+Ensure flakes are enabled, for example:
+<code nix>
+nix.settings.experimental-features = [
+  "nix-command"
+  "flakes"
+];
+</code>
 Note that ''/persistent'' must match the dataset mountpoint, but you can choose an arbitrary name
@@ Line 76: / Line 138: @@
 <code bash>
-nixos-rebuild boot
+nixos-rebuild boot --flake /etc/nixos#vps
 </code>
-===== 8. Turn on impermanence feature =====
+==== 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
@@ Line 96: / Line 158: @@
 ''/'' 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