nixos/doc/manual/from_md/development/bootspec.chapter.xml


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
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>