nixos/activation/bootspec: add bootspec chapter in NixOS manual
This commit is contained in:
Raito Bezarius
Cole Helbling
parent
9832e3e9b9
commit
11dfbee0a4
36
nixos/doc/manual/development/bootspec.chapter.md
Normal file
36
nixos/doc/manual/development/bootspec.chapter.md
Normal 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.
|
||||
@ -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" />
|
||||
|
||||
73
nixos/doc/manual/from_md/development/bootspec.chapter.xml
Normal file
73
nixos/doc/manual/from_md/development/bootspec.chapter.xml
Normal 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 = {
|
||||
"org.secureboot.osRelease" = config.environment.etc."os-release".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>
|
||||
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user