nixos/activation/bootspec: add bootspec chapter in NixOS manual

This commit is contained in:
Raito Bezarius 2022-11-30 18:12:13 +01:00 committed by Cole Helbling
parent 9832e3e9b9
commit 11dfbee0a4
4 changed files with 111 additions and 1 deletions

View File

@ -0,0 +1,36 @@
# Experimental feature: Bootspec {#sec-experimental-bootspec}
Bootspec is a experimental feature, introduced in the [RFC-0125 proposal](https://github.com/NixOS/rfcs/pull/125), the reference implementation can be found [there](https://github.com/NixOS/nixpkgs/pull/172237) in order to standardize bootloader support
and advanced boot workflows such as SecureBoot and potentially more.
You can enable the creation of bootspec documents through [`boot.bootspec.enable = true`](options.html#opt-boot.bootspec.enable), which will prompt a warning until [RFC-0125](https://github.com/NixOS/rfcs/pull/125) is officially merged.
## Schema {#sec-experimental-bootspec-schema}
The bootspec schema is versioned and validated against [a CUE schema file](https://cuelang.org/) which should considered as the source of truth for your applications.
You will find the current version [here](../../../modules/system/activation/bootspec.cue).
## Extensions mechanism {#sec-experimental-bootspec-extensions}
Bootspec cannot account for all usecases.
For this purpose, Bootspec offers a generic extension facility [`boot.bootspec.extensions`](options.html#opt-boot.bootspec.extensions) which can be used to inject any data needed for your usecases.
An example for SecureBoot is to get the Nix store path to `/etc/os-release` in order to bake it into a unified kernel image:
```nix
{ config, lib, ... }: {
boot.bootspec.extensions = {
"org.secureboot.osRelease" = config.environment.etc."os-release".source;
};
}
```
To reduce incompatibility and prevent names from clashing between applications, it is **highly recommended** to use a unique namespace for your extensions.
## External bootloaders {#sec-experimental-bootspec-external-bootloaders}
It is possible to enable your own bootloader through [`boot.loader.external.installHook`](options.html#opt-boot.loader.external.installHook) which can wrap an existing bootloader.
Currently, there is no good story to compose existing bootloaders to enrich their features, e.g. SecureBoot, etc. It will be necessary to reimplement or reuse existing parts.

View File

@ -12,6 +12,7 @@
<xi:include href="../from_md/development/sources.chapter.xml" />
<xi:include href="../from_md/development/writing-modules.chapter.xml" />
<xi:include href="../from_md/development/building-parts.chapter.xml" />
<xi:include href="../from_md/development/bootspec.chapter.xml" />
<xi:include href="../from_md/development/what-happens-during-a-system-switch.chapter.xml" />
<xi:include href="../from_md/development/writing-documentation.chapter.xml" />
<xi:include href="../from_md/development/nixos-tests.chapter.xml" />

View File

@ -0,0 +1,73 @@
<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-experimental-bootspec">
<title>Experimental feature: Bootspec</title>
<para>
Bootspec is a experimental feature, introduced in the
<link xlink:href="https://github.com/NixOS/rfcs/pull/125">RFC-0125
proposal</link>, the reference implementation can be found
<link xlink:href="https://github.com/NixOS/nixpkgs/pull/172237">there</link>
in order to standardize bootloader support and advanced boot
workflows such as SecureBoot and potentially more.
</para>
<para>
You can enable the creation of bootspec documents through
<link xlink:href="options.html#opt-boot.bootspec.enable"><literal>boot.bootspec.enable = true</literal></link>,
which will prompt a warning until
<link xlink:href="https://github.com/NixOS/rfcs/pull/125">RFC-0125</link>
is officially merged.
</para>
<section xml:id="sec-experimental-bootspec-schema">
<title>Schema</title>
<para>
The bootspec schema is versioned and validated against
<link xlink:href="https://cuelang.org/">a CUE schema file</link>
which should considered as the source of truth for your
applications.
</para>
<para>
You will find the current version
<link xlink:href="../../../modules/system/activation/bootspec.cue">here</link>.
</para>
</section>
<section xml:id="sec-experimental-bootspec-extensions">
<title>Extensions mechanism</title>
<para>
Bootspec cannot account for all usecases.
</para>
<para>
For this purpose, Bootspec offers a generic extension facility
<link xlink:href="options.html#opt-boot.bootspec.extensions"><literal>boot.bootspec.extensions</literal></link>
which can be used to inject any data needed for your usecases.
</para>
<para>
An example for SecureBoot is to get the Nix store path to
<literal>/etc/os-release</literal> in order to bake it into a
unified kernel image:
</para>
<programlisting language="bash">
{ config, lib, ... }: {
boot.bootspec.extensions = {
&quot;org.secureboot.osRelease&quot; = config.environment.etc.&quot;os-release&quot;.source;
};
}
</programlisting>
<para>
To reduce incompatibility and prevent names from clashing between
applications, it is <emphasis role="strong">highly
recommended</emphasis> to use a unique namespace for your
extensions.
</para>
</section>
<section xml:id="sec-experimental-bootspec-external-bootloaders">
<title>External bootloaders</title>
<para>
It is possible to enable your own bootloader through
<link xlink:href="options.html#opt-boot.loader.external.installHook"><literal>boot.loader.external.installHook</literal></link>
which can wrap an existing bootloader.
</para>
<para>
Currently, there is no good story to compose existing bootloaders
to enrich their features, e.g. SecureBoot, etc. It will be
necessary to reimplement or reuse existing parts.
</para>
</section>
</chapter>

View File

@ -87,7 +87,7 @@ in
config = lib.mkIf (cfg.enable) {
warnings = [
''RFC-0125 is not merged yet, this is a feature preview of bootspec.
Schema is not definitive and features are not stabilized until RFC-0125 is merged.
The schema is not definitive and features are not guaranteed to be stable until RFC-0125 is merged.
See:
- https://github.com/NixOS/nixpkgs/pull/172237 to track merge status in nixpkgs.
- https://github.com/NixOS/rfcs/pull/125 to track RFC status.