Initial commit

.envrc

@@ -0,0 +1 @@
+use flake

.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: Run nix flake check
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  build:
+    name: Flake Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DeterminateSystems/nix-installer-action@v15
+        with:
+          diagnostic-endpoint: ""
+          source-url: "https://install.lix.systems/lix/lix-installer-x86_64-linux"
+      - uses: DeterminateSystems/magic-nix-cache-action@v8
+        with:
+          diagnostic-endpoint: ""
+      - run: nix flake check --log-format raw-with-logs -L
+
+env:
+  FORCE_COLOR: 1

.gitignore

@@ -0,0 +1,12 @@
+.vscode
+result*
+.direnv/
+.pre-commit-config.yaml
+.nixos-test-history
+TODO.MD
+
+# Local debugging
+img
+*.raw
+mnt/
+tree/

README.md

@@ -0,0 +1,44 @@
+# naext: Nix Appliance Extension Tools
+
+Extending Appliance Images.
+
+NixOS allows for building [Appliance Images](https://nixos.org/manual/nixos/unstable/#sec-image-repart-appliance). Since Appliance Images are immutable they typically contain everything necessary to make use of such an image.
+
+## Problem
+
+Appliances are usually built generically. To be useful an appliance is augmented with specifics (think of configuration, programs) for a certain use case.
+
+## Offered Solution
+
+This project offers solutions to extend immutable appliances in a lightweight manner leveraging technologies provided by systemd and the kernel.
+
+### `naext` Module
+
+Allows for building extension images (`sysext`, `confext`).
+
+#### Example
+
+Create a confext image that provides the file `/etc/test` containing `Hello`.
+
+```nix
+naext = {
+  seed = "12345678-1234-1234-1234-123456789123";
+  extensions = {
+    "hello" = {
+      extensionType = "confext";
+      imageFormat = "raw";
+      files = {
+        "/etc/test".source = pkgs.writeText "example" ''Hello'';
+      };
+    };
+  };
+};
+```
+
+## Tour
+
+Check out:
+
+- [Building an Image](./examples/basic.nix) with `nix-build ./examples/basic.nix`
+- [Basic Integration Test](./nix/tests/basic.nix) with `nix-build ./examples/basic.nix`
+- [Integration Test with verity protected extension image](./nix/tests/basic.nix) with `nix-build ./examples/basic.nix`

default.nix

@@ -0,0 +1,14 @@
+{
+  system ? builtins.currentSystem,
+}:
+let
+  sources = import ./nix/sources.nix;
+  pkgs = import sources.nixpkgs {
+    inherit system;
+    config.allowAliases = false;
+  };
+  outputs = import ./nix/outputs.nix { inherit pkgs; };
+in
+{
+  inherit (outputs) checks;
+}

examples/basic.nix

@@ -0,0 +1,33 @@
+{
+  system ? builtins.currentSystem,
+}:
+let
+  sources = import ../nix/sources.nix;
+  pkgs = import sources.nixpkgs {
+    inherit system;
+    config.allowAliases = false;
+  };
+  outputs = import ../nix/outputs.nix { inherit pkgs; };
+in
+(pkgs.lib.evalModules {
+  modules = [
+    outputs.nixosModules.default
+    (_: {
+      naext = {
+        seed = "12345678-1234-1234-1234-123456789123";
+        extensions = {
+          "hello" = {
+            extensionType = "confext";
+            imageFormat = "raw";
+            files = {
+              "/etc/test".source = pkgs.writeText "example" ''Hello'';
+            };
+          };
+        };
+      };
+    })
+  ];
+  specialArgs = {
+    inherit pkgs;
+  };
+}).config.naext.extensions."hello".image

flake.nix

@@ -0,0 +1,106 @@
+{
+  description = "Extension Images built with Nix";
+
+  inputs = {
+    flake-compat = {
+      url = "github:edolstra/flake-compat";
+      flake = false;
+    };
+    flake-parts = {
+      url = "github:hercules-ci/flake-parts";
+      inputs.nixpkgs-lib.follows = "nixpkgs";
+    };
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    pre-commit-hooks-nix = {
+      url = "github:cachix/pre-commit-hooks.nix";
+      inputs = {
+        nixpkgs.follows = "nixpkgs";
+        flake-compat.follows = "flake-compat";
+      };
+    };
+    systems.url = "github:nix-systems/default";
+  };
+  outputs =
+
+    inputs:
+    inputs.flake-parts.lib.mkFlake { inherit inputs; } {
+      systems = import inputs.systems;
+      imports = [ inputs.pre-commit-hooks-nix.flakeModule ];
+      flake.nixosModules = {
+        naext = import ./nix/module.nix;
+        dm-verity = import ./nix/dm-verity.nix;
+      };
+      perSystem =
+        {
+          config,
+          pkgs,
+          ...
+        }:
+        {
+          checks =
+            { }
+            // (import ./nix/tests {
+              inherit (inputs.self) nixosModules;
+              inherit pkgs;
+              enableHeavyTests = false;
+            });
+
+          pre-commit = {
+            check.enable = true;
+            settings = {
+              hooks = {
+                nixfmt-rfc-style.enable = true;
+                statix.enable = true;
+              };
+            };
+          };
+          devShells.default =
+            let
+              example-basic-mount =
+                pkgs.writeShellScriptBin "example-basic-mount" # bash
+                  ''
+                    partition=p1 # assume the data partition is p1
+                    top=$(git rev-parse --show-toplevel)
+                    set -eux
+
+                    # Build the example image and mount it as a loop device
+                    nix-build $top/examples/basic.nix --out-link $top/result "$@"
+                    cp -rL $top/result $top/basic.raw
+                    loopdev=$(systemd-dissect --attach $top/basic.raw)
+
+                    # Wait until the data partition becomes available
+                    while [ ! -e "''\${loopdev}''\${partition}" ]; do
+                      sleep 0.1 # adjust the delay as necessary
+                    done
+
+                    # Create the mount point
+                    if [ ! -e $top/mnt ]; then
+                      mkdir $top/mnt
+                    fi
+                    mount "''\${loopdev}''\${partition}" $top/mnt
+                  '';
+              example-basic-umount =
+                pkgs.writeShellScriptBin "example-basic-umount" # bash
+                  ''
+                    top=$(git rev-parse --show-toplevel)
+                    set -eux
+                    umount $top/mnt
+                    systemd-dissect --detach $top/basic.raw
+                    rm $top/result $top/basic.raw
+                  '';
+            in
+            pkgs.mkShell {
+              shellHook = ''
+                ${config.pre-commit.installationScript}
+              '';
+              packages = with pkgs; [
+                example-basic-mount
+                example-basic-umount
+                nixfmt-rfc-style
+                statix
+                util-linux
+              ];
+            };
+        };
+    };
+}