This module provides some abstraction for a multi-stage build to create
a dm-verity protected NixOS repart image.
The opinionated approach realized by this module is to first create an
immutable, verity-protected nix store partition, then embed the root
hash of the corresponding verity hash partition in a UKI, that is then
injected into the ESP of the resulting image.
The UKI can then precisely identify the corresponding data from which
the entire system is bootstrapped.
The module comes with a script that checks the UKI used in the final
image corresponds to the intermediate image created in the first step.
This is necessary to notice incompatible substitutions of
non-reproducible store paths, for example when working with distributed
builds, or when offline-signing the UKI.
these changes were generated with nixq 0.0.2, by running
nixq ">> lib.mdDoc[remove] Argument[keep]" --batchmode nixos/**.nix
nixq ">> mdDoc[remove] Argument[keep]" --batchmode nixos/**.nix
nixq ">> Inherit >> mdDoc[remove]" --batchmode nixos/**.nix
two mentions of the mdDoc function remain in nixos/, both of which
are inside of comments.
Since lib.mdDoc is already defined as just id, this commit is a no-op as
far as Nix (and the built manual) is concerned.
The maximum label length is specified by UEFI and enforced/asserted by
systemd-repart. This lets evaluation fail already and give the user
some more information about what's wrong.
Also warn when the suggested label length is exceeded. This serves as a
safety mechanism for using systemd-sysupdate style A/B updates where the
version number is encoded in the label and might not be incrementable
when the maximum label size is reached.
As a follow-up to https://github.com/NixOS/nixpkgs/pull/294096 this
should further improve the flexibility around building OS images with
systemd-repart:
* Previously the attribute set `compression` needed to be fully
populated, including `algorithm` and `level` because
`compression.enable` was evaluated by bash, after being interpolated
as strings into the `buildCommand`. Now it's sufficient to pass
`compression.enable = false` to the builder, e.g. in `overrideAttrs`,
to disable the compression.
* Using mkDerivation allows for much more customization than the
previously used `runCommand`, making use of phases and pre/post hooks.
This is especially helpful for building multiple images from the same
system configuration, e.g. to build an image `Y` based on a partially
built raw image `X`, by injecting a UKI that depends on `X` into a
defered ESP.
* Before this change it was non-trivial to conduct further manipulations
on the amended repart definitions. Now, the definitions that
systemd-repart uses to build the image can be easily manipulated in
`postPatch` or `preBuild`.
Aside from this, the build is now executed in the build directory, rather
than `$out`. This allows references to relative paths in the build
environment to be used, especially for `--definitions`, which previously
required an absolute path.
Parameters passed to systemd-repart are now passed to the build script
via environment variable, which is defined as a list of strings in
combination with `__structuredAttrs = true`. This should make it easier
to customize the image build using `overrideAttrs`.
Both the script used to amend the repart definitions and the amended
definitions are now available via passthru.
The version option is needed if you want to implement partition &
systemd-boot based A/B booting where the version information is encoded
in the files on the ESP. See systemd-sysupate docs for more details on
this:
https://www.freedesktop.org/software/systemd/man/latest/sysupdate.d.html
Note, however, that this is not *only* useful for systemd-sysupdate but
also for other similar updating tools/mechanisms.
Since the repart image is built on the build platform, use
`buildPackages` to construct the image. This allows for systemd-repart
images for cross-compiled nixos configurations to work properly.
literalExpression triggers the following error when building the
manual:
Cacheable portion of option doc build failed.
Usually this means that an option attribute that ends up in documentation (eg `default` or `description`) depends on the restricted module arguments `config` or `pkgs`.
Allow giving a custom package containing the `systemd-repart` binary.
Defaults to `pkgs.systemd`. This option opens up the possibility to use
a different package for the image builder and the system configuration.
For example, someone could use this option to build an image with a
patched systemd while still using the upstream nixpkgs systemd package
(i.e., `pkgs.systemd`) for the system configuration installed to the
created image.
Output the amended repart definitions to a well-known directory in
$TMPDIR instead of using a temporary directory with a random directory
name.
The output file `repart-output.json` also contains the full path to the
repart definition file used to create the partition. As
`amend-repart-definitions.py` uses `tempfile.mkdtemp`, this introduces
an impurity:
```json
{
"type" : "root-x86-64",
"label" : "rootfs",
"uuid" : "f2fa2e49-e443-45d2-a2e2-c3754cab6363",
"file" : "/build/tmppjo7kv5o/rootfs.conf",
"node" : "image.raw2",
"offset" : 135266304,
"old_size" : 0,
"raw_size" : 1651101696,
"old_padding" : 0,
"raw_padding" : 0,
"activity" : "create",
}
```
This commit changes the parent directory of the amended repart
definitions to `/build/amended-repart.d/`.
Write the output of `systemd-repart` as a JSON file to
`$out/repart-output.json`.
Depending on the repart configuration, the output of `systemd-repart`
contains important information, for example, when creating verity
partitions:
> The verity root hash itself will be included in the output of
> systemd-repart.
See `Verity=` in repart.d(5).
