update firstboot examples in docs and tests

.github/workflows/test.yml

@@ -20,8 +20,10 @@ jobs:
         run: nix flake check --log-format raw-with-logs --no-build ./tests
       - name: default test
         run: nix build --log-format raw-with-logs -L ./tests#checks.x86_64-linux.default
-      - name: firstboot test
-        run: nix build --log-format raw-with-logs -L ./tests#checks.x86_64-linux.firstboot
+      - name: firstboot-bind-mount test
+        run: nix build --log-format raw-with-logs -L ./tests#checks.x86_64-linux.firstboot-bind-mount
+      - name: firstboot-symlink test
+        run: nix build --log-format raw-with-logs -L ./tests#checks.x86_64-linux.firstboot-symlink
 
 env:
   FORCE_COLOR: 1

docs/src/examples.md

@@ -40,11 +40,16 @@ See [Configuration Options](./configuration-options.md) for all available option
 
 ## Compatibility with systemd's `ConditionFirstBoot`
 
-In this example the machine-id is preserved on the persistent volume via symlink
-instead of a bind-mount. The option `configureParent` causes the parent directory
-of the symlink's target, i.e. `/persistent/etc/` to be created.
-Additionally, `systemd-machine-id-commit.service` is adapted to persist the tmpfs
-mount created by system to the persistent volume.
+To preserve correct [systemd first boot semantics](https://www.freedesktop.org/software/systemd/man/latest/machine-id.html#First%20Boot%20Semantics),
+additional configuration is required.
+
+The following two configuration examples are compatible with first boot semantics.
+
+### Symlink approach
+
+Since systemd v258, systemd no longer creates missing symlink targets automatically
+(see [this issue](https://github.com/nix-community/preservation/issues/22)).
+Therefore, the target must exist ahead of time and contain an `uninitialized` machine-id.
 
 ```nix
 # configuration.nix
@@ -60,7 +65,13 @@ mount created by system to the persistent volume.
     preserveAt."/persistent" = {
       files = [
         # auto-generated machine ID
-        { file = "/etc/machine-id"; inInitrd = true; how = "symlink"; configureParent = true; }
+        {
+          file = "/etc/machine-id";
+          inInitrd = true;
+          how = "symlink";
+          configureParent = true;
+          createLinkTarget = true;
+        }
         # ...
       ];
       directories = [
@@ -69,11 +80,9 @@ mount created by system to the persistent volume.
     };
   };
 
-  # systemd-machine-id-commit.service would fail, but it is not relevant
-  # in this specific setup for a persistent machine-id so we disable it
-  #
-  # see the firstboot example below for an alternative approach
-  systemd.suppressedSystemUnits = [ "systemd-machine-id-commit.service" ];
+  boot.initrd.systemd.tmpfiles.settings.preservation."/sysroot/persistent/etc/machine-id".f = {
+    argument = "uninitialized";
+  };
 
   # let the service commit the transient ID to the persistent volume
   systemd.services.systemd-machine-id-commit = {
@@ -90,6 +99,48 @@ mount created by system to the persistent volume.
 ```
 
 
+### Bind-mount approach
+
+Alternatively, one can use a bind-mount. As with the symlink approach, the target
+must exist ahead of time and contain an `uninitialized` machine-id.
+
+However, note that since `/etc/machine-id` becomes a bind-mounted path,
+`systemd-machine-id-commit` will see `ConditionPathIsMountPoint=/etc/machine-id`
+as true on every boot.
+
+To avoid committing on every boot, `ConditionFirstBoot=true` must be added.
+
+```nix
+# configuration.nix
+{
+  config,
+  lib,
+  pkgs,
+  ...
+}:
+{
+  preservation = {
+    enable = true;
+    preserveAt."/persistent" = {
+      files = [
+        # auto-generated machine ID
+        { file = "/etc/machine-id"; inInitrd = true; }
+        # ...
+      ];
+      directories = [
+        # ...
+      ];
+    };
+  };
+
+  boot.initrd.systemd.tmpfiles.settings.preservation."/sysroot/persistent/etc/machine-id".f = {
+    argument = "uninitialized";
+  };
+
+  systemd.services.systemd-machine-id-commit.unitConfig.ConditionFirstBoot = true;
+}
+```
+
 
 ## Complex
 

tests/appliance-image-verity.nix

@@ -17,11 +17,21 @@ pkgs:
         enable = true;
         preserveAt."/persistent" = {
           files = [
-            { file = "/etc/machine-id"; inInitrd = true; how = "symlink"; configureParent = true; }
+            {
+              file = "/etc/machine-id";
+              inInitrd = true;
+              how = "symlink";
+              configureParent = true;
+              createLinkTarget = true;
+            }
           ];
         };
       };
 
+      boot.initrd.systemd.tmpfiles.settings.preservation."/sysroot/persistent/etc/machine-id".f = {
+        argument = "uninitialized";
+      };
+
       systemd.services.systemd-machine-id-commit = {
         unitConfig.ConditionPathIsMountPoint = [
           "" "/persistent/etc/machine-id"
@@ -82,31 +92,27 @@ pkgs:
         passwordFilesLocation = "/persistent/etc";
       };
 
+      fileSystems = {
+        "/" = {
+          fsType = "tmpfs";
+          options = [ "mode=0755" ];
+        };
+        "/persistent" = {
+          device = "/dev/vdb";
+          fsType = "ext4";
+          neededForBoot = true;
+          autoFormat = true;
+        };
+      };
+
       virtualisation = {
         memorySize = 2048;
         emptyDiskImages = [ 23 ];
         directBoot.enable = false;
         mountHostNixStore = false;
         useEFIBoot = true;
-        fileSystems = lib.mkVMOverride {
-          "/" = {
-            fsType = "tmpfs";
-            options = [ "mode=0755" ];
-          };
-          "/nix/store" = {
-            device = "/usr/nix/store";
-            options = [ "bind" ];
-          };
-          "/persistent" = {
-            device = "/dev/vdb";
-            fsType = "ext4";
-            neededForBoot = true;
-            autoFormat = true;
-          };
-        };
+        fileSystems = lib.mkVMOverride { };
       };
-
-      nixpkgs.hostPlatform = pkgs.stdenv.hostPlatform;
     };
 
   testScript =
@@ -125,7 +131,7 @@ pkgs:
         "-f",
         "qcow2",
         "-b",
-        "${nodes.machine.system.build.finalImage}/${nodes.machine.image.fileName}",
+        "${nodes.machine.system.build.image}/${nodes.machine.image.fileName}",
         "-F",
         "raw",
         tmp_disk_image.name,
@@ -152,6 +158,8 @@ pkgs:
       with subtest("Machine ID linked and populated"):
         machine.succeed("test -L /etc/machine-id")
         machine.succeed("test -s /persistent/etc/machine-id")
+        machine_id = machine.succeed("cat /etc/machine-id")
+        t.assertNotEqual("uninitialized", machine_id, "machine id not populated")
 
       with subtest("Machine ID persisted"):
         first_id = machine.succeed("cat /etc/machine-id")

tests/basic.nix

@@ -128,6 +128,7 @@ in
     /* python */
     ''
       import json
+      import os
 
       initrd_files = json.loads('${initrdJSON}')
       all_files = json.loads('${allJSON}')

tests/firstboot.nix → tests/firstboot-bind-mount.nix

@@ -1,6 +1,6 @@
 pkgs:
 {
-  name = "preservation-firstboot";
+  name = "preservation-firstboot-bind-mount";
 
   nodes.machine =
     { pkgs, ... }:
@@ -9,22 +9,19 @@ pkgs:
 
       preservation = {
         enable = true;
-        preserveAt."/state" = {
+        preserveAt."/persistent" = {
           files = [
-            { file = "/etc/machine-id"; inInitrd = true; how = "symlink"; configureParent = true; }
+            { file = "/etc/machine-id"; inInitrd = true; }
           ];
         };
       };
 
-      systemd.services.systemd-machine-id-commit = {
-        unitConfig.ConditionPathIsMountPoint = [
-          "" "/state/etc/machine-id"
-        ];
-        serviceConfig.ExecStart = [
-          "" "systemd-machine-id-setup --commit --root /state"
-        ];
+      boot.initrd.systemd.tmpfiles.settings.preservation."/sysroot/persistent/etc/machine-id".f = {
+        argument = "uninitialized";
       };
 
+      systemd.services.systemd-machine-id-commit.unitConfig.ConditionFirstBoot = true;
+
       # test-specific configuration below
       boot.initrd.systemd.enable = true;
 
@@ -34,7 +31,7 @@ pkgs:
         memorySize = 2048;
         # separate block device for preserved state
         emptyDiskImages = [ 23 ];
-        fileSystems."/state" = {
+        fileSystems."/persistent" = {
           device = "/dev/vdb";
           fsType = "ext4";
           neededForBoot = true;
@@ -54,9 +51,10 @@ pkgs:
       with subtest("Initial boot meets ConditionFirstBoot"):
         machine.require_unit_state("first-boot-complete.target","active")
 
-      with subtest("Machine ID linked and populated"):
-        machine.succeed("test -L /etc/machine-id")
-        machine.succeed("test -s /state/etc/machine-id")
+      with subtest("Machine ID populated"):
+        machine.succeed("test -s /persistent/etc/machine-id")
+        machine_id = machine.succeed("cat /etc/machine-id")
+        t.assertNotEqual("uninitialized", machine_id, "machine id not populated")
 
       with subtest("Machine ID persisted"):
         first_id = machine.succeed("cat /etc/machine-id")

tests/firstboot-symlink.nix

@@ -0,0 +1,85 @@
+pkgs:
+{
+  name = "preservation-firstboot-symlink";
+
+  nodes.machine =
+    { pkgs, ... }:
+    {
+      imports = [ ../module.nix ];
+
+      preservation = {
+        enable = true;
+        preserveAt."/persistent" = {
+          files = [
+            {
+              file = "/etc/machine-id";
+              inInitrd = true;
+              how = "symlink";
+              configureParent = true;
+              createLinkTarget = true;
+            }
+          ];
+        };
+      };
+
+      boot.initrd.systemd.tmpfiles.settings.preservation."/sysroot/persistent/etc/machine-id".f = {
+        argument = "uninitialized";
+      };
+
+      systemd.services.systemd-machine-id-commit = {
+        unitConfig.ConditionPathIsMountPoint = [
+          "" "/persistent/etc/machine-id"
+        ];
+        serviceConfig.ExecStart = [
+          "" "systemd-machine-id-setup --commit --root /persistent"
+        ];
+      };
+
+      # test-specific configuration below
+      boot.initrd.systemd.enable = true;
+
+      networking.useNetworkd = true;
+
+      virtualisation = {
+        memorySize = 2048;
+        # separate block device for preserved state
+        emptyDiskImages = [ 23 ];
+        fileSystems."/persistent" = {
+          device = "/dev/vdb";
+          fsType = "ext4";
+          neededForBoot = true;
+          autoFormat = true;
+        };
+      };
+
+    };
+
+  testScript =
+    { nodes, ... }:
+    # python
+    ''
+      machine.start(allow_reboot=True)
+      machine.wait_for_unit("default.target")
+
+      with subtest("Initial boot meets ConditionFirstBoot"):
+        machine.require_unit_state("first-boot-complete.target","active")
+
+      with subtest("Machine ID linked and populated"):
+        machine.succeed("test -L /etc/machine-id")
+        machine.succeed("test -s /persistent/etc/machine-id")
+        machine_id = machine.succeed("cat /etc/machine-id")
+        t.assertNotEqual("uninitialized", machine_id, "machine id not populated")
+
+      with subtest("Machine ID persisted"):
+        first_id = machine.succeed("cat /etc/machine-id")
+        machine.reboot()
+        machine.wait_for_unit("default.target")
+        second_id = machine.succeed("cat /etc/machine-id")
+        t.assertEqual(first_id, second_id, "machine-id changed")
+
+      with subtest("Second boot does not meet ConditionFirstBoot"):
+        machine.require_unit_state("first-boot-complete.target", "inactive")
+
+      machine.shutdown()
+    '';
+}