NixOS Bootspec 深入指南:RFC-0125 引导规范、Schema 验证与扩展机制
NixOS Bootspec 深入指南:RFC-0125 引导规范、Schema 验证与扩展机制
本文以 NixOS 手册中 Bootspec 章节 为骨架,结合仓库内 nixos/modules/system/activation/、nixos/modules/system/boot/loader/ 的源码与测试,系统讲解 Bootspec 的由来、boot.json 文档结构、Schema 验证、boot.bootspec.extensions 扩展机制,以及通过 boot.loader.external.installHook 接入自定义引导器的完整方案。读完本文,你将掌握 Bootspec 文档的生成与校验原理,能够为 SecureBoot 等高级引导工作流编写自己的扩展,并能独立开发外部引导器后端。
Bootspec 是什么:标准化的引导描述文档
Bootspec 是 NixOS 在 RFC-0125 中引入的一项特性,其目的是标准化引导器(bootloader)支持,并为 SecureBoot 等高级引导工作流铺路。在此之前,每个引导器(GRUB、systemd-boot、U-Boot……)都各自实现一套"读懂系统代(generation)"的逻辑,彼此之间缺乏统一的数据接口。
Bootspec 的解决思路非常直接:在每次构建系统 toplevel 时,同时产出一份名为 boot.json 的机器可读文档,描述该代系统的内核、initrd、内核参数、标签等关键引导属性。任何引导器——无论是 NixOS 内置的还是第三方自定义的——都可以通过读取这份文档来生成对应的启动菜单项,从而摆脱对特定引导器内部实现的依赖。
从源码结构看,Bootspec 文档的生成在 nixos/modules/system/activation/bootspec.nix 中完成,并通过 nixos/modules/system/activation/top-level.nix 中的系统构建器(systemBuilder)被写入 toplevel 输出目录:
# nixos/modules/system/activation/top-level.nix 中与 bootspec 相关的构建步骤
${config.boot.bootspec.writer}
${optionalString config.boot.bootspec.enableValidation ''${config.boot.bootspec.validator} "$out/${config.boot.bootspec.filename}"''}
即先运行 writer 生成 $out/boot.json,若开启了 enableValidation 则再调用 validator 对文档做 Schema 校验。
默认启用,不可关闭
手册明确指出:"The creation of bootspec documents is enabled by default"(Bootspec 文档的生成默认启用)。在 bootspec.nix 中,这一设计被固化为一个"已移除选项"声明:
imports = [
(lib.mkRemovedOptionModule [ "boot" "bootspec" "enable" ] ''
Bootspec is now always generated and can no longer be disabled.
'')
];
也就是说,boot.bootspec.enable 选项已被移除,任何旧配置中使用该选项都会收到"Bootspec 现在始终生成且无法禁用"的明确报错。这保证了外部工具可以放心依赖这份文档的存在。
文档内容:org.nixos.bootspec.v1 命名空间结构
要理解 Bootspec,先要理解它的命名空间设计。boot.json 的顶层是一系列带命名空间的键,其中 org.nixos.bootspec.v1 是 NixOS 官方保留的核心命名空间,存放标准引导属性。
其字段由 bootspec.nix 中的 schemas.v1 定义生成,条件性地包含以下内容:
| 字段 | 类型 | 含义与触发条件 |
|---|---|---|
system |
string | 目标系统平台字符串,取自 config.boot.kernelPackages.stdenv.hostPlatform.system |
label |
string | 系统标签,形如 NixOS 25.05.20260919 (Linux 6.x.y),由发行版名、代号、标签与内核版本拼接 |
kernel |
string | 内核可执行文件路径,仅当 boot.kernel.enable 时存在 |
kernelParams |
[string] | 内核启动参数列表,仅当 boot.kernel.enable 时存在 |
initrd |
string | initrd 镜像路径,仅当 boot.initrd.enable 时存在 |
initrdSecrets |
string | initrd 密钥追加脚本路径,仅当配置了 boot.initrd.secrets(至少一个密钥)时存在 |
toplevel |
string | 系统 toplevel 的 Nix store 路径,由 toplevel 注入器在构建时填充 |
init |
string | toplevel 下 init 可执行文件的路径($out/init),同样由注入器填充 |
其中 toplevel 与 init 两个字段比较特殊:它们依赖 $out 指向 toplevel 自身,因此只能在 toplevel 构建过程中注入。源码中的 toplevelInjector(bootspec.nix)正是为此设计——它使用 jq 在生成阶段把当前输出路径写进文档:
jq '.org.nixos.bootspec.v1.toplevel = $toplevel |
.org.nixos.bootspec.v1.init = $init' \
--sort-keys --arg toplevel "$out" --arg init "$out/init" < boot.json
此外,specialisationInjector(bootspec.nix)会把配置中声明的所有 specialisation(特化系统配置)作为 org.nixos.specialisation.v1 键下的映射灌入父文档,形成树状结构。
一份真实的 boot.json 示例
综合上述生成逻辑,一个启用了 initrd、且声明了一个 specialisation 的系统,其 /run/current-system/boot.json 大致长这样:
{
"org.nixos.bootspec.v1": {
"init": "/nix/store/xxxx-init",
"initrd": "/nix/store/yyyy-initrd/initrd",
"kernel": "/nix/store/zzzz-linux-6.x.y/bzImage",
"kernelParams": [
"init=/nix/store/xxxx-init/init"
],
"label": "NixOS 25.05.20260919 (Linux 6.x.y)",
"system": "x86_64-linux",
"toplevel": "/nix/store/xxxx-system"
},
"org.nixos.specialisation.v1": {
"something": {
"org.nixos.bootspec.v1": { }
}
}
}
注意顶层 kernel 字段存放的是内核 store 路径,而 kernelParams 中会追加 init=... 指向 toplevel 的 init 程序——这正是 systemd-boot-builder.py 中 get_bootspec 读取文档后构造启动项的核心数据来源(见下文"引导器如何消费 boot.json")。
Schema 与校验:以 CUE 为事实来源
Bootspec 文档不是松散的自由格式 JSON,而是有版本、有 Schema、可校验的结构化数据。手册明确指出:Schema 使用 CUE 语言编写,并"应被视为你的应用程序的事实来源"(source of truth)。
当前版本对应的 Schema 文件位于 nixos/modules/system/activation/bootspec.cue,其核心定义如下:
#BootspecV1: {
system: string
init: string
initrd?: string
initrdSecrets?: string
kernel: string
kernelParams: [...string]
label: string
toplevel: string
}
#RestrictedDocument: struct.MinFields(1) & {
"org.nixos.bootspec.v1": #BootspecV1
[=~"^"]: #BootspecExtension
}
#BootspecSpecialisationV1: [string]: #RestrictedDocument
#BootspecExtension: {...}
Document: #RestrictedDocument & {
"org.nixos.specialisation.v1"?: #BootspecSpecialisationV1
}
Schema 的要点值得拆解:
#BootspecV1定义了 v1 版本核心字段的类型:system、init、kernel、kernelParams、label、toplevel为必填,initrd、initrdSecrets可选。有趣的是 CUE 中kernel被定义为必填,而 Nix 生成逻辑里它受boot.kernel.enable条件约束——两者配合意味着"启用内核引导的系统必须产出完整字段"。#RestrictedDocument约束"受限文档":至少包含 1 个字段(struct.MinFields(1)),org.nixos.bootspec.v1必须符合#BootspecV1,其余所有键([=~"^"])都必须是合法的 Bootspec 扩展。#BootspecSpecialisationV1表明 specialisation 是一张"名称 → 受限文档"的映射,且每个 specialisation 内部不允许再嵌套官方 specialisation 信息,以此避免"递归特化"(注释明确说明这是刻意的限制)。Document是顶层文档的完整定义:在受限文档基础上,允许出现org.nixos.specialisation.v1保留键。
enableValidation:开启构建期校验
boot.bootspec.enableValidation 选项(bootspec.nix)用于开启每次构建时对 bootspec 文档的校验。选项描述中特别提醒:开启它会在构建期闭包中引入 Go 运行时——因为校验依赖 Cuelang 工具链。
其默认值由一个 lib.mkEnableOption 定义,默认关闭(未启用)。构建时校验器通过 pkgs.writeCueValidator ./bootspec.cue { document = "Document"; } 生成,以 Document 作为入口类型,因而是一个"能校验任何版本文档"的通用校验器——只要文档正确声明了对应的 schema 版本。
Extensions 扩展机制:向 boot.json 注入任意数据
Bootspec 无法穷尽所有使用场景——这是手册反复强调的前提。为此,Bootspec 提供了通用的扩展设施 boot.bootspec.extensions,允许开发者把任意与自身应用相关的数据注入 bootspec 文档。
选项定义
该选项在 bootspec.nix 中定义:
extensions = lib.mkOption {
type = lib.types.attrsOf lib.types.anything; # <namespace>: { ...namespace-specific fields }
default = { };
description = ''
User-defined data that extends the bootspec document.
To reduce incompatibility and prevent names from clashing
between applications, it is **highly recommended** to use a
unique namespace for your extensions.
'';
};
要点:
- 类型为
attrsOf anything,即"命名空间 → 任意值"的映射,扩展内容本身可以是任意结构; - 默认空集
{ }; - 选项描述与手册一致地强调:强烈建议使用唯一命名空间,以降低不兼容风险、防止不同应用间的键名冲突。
生成时的合并顺序(安全细节)
扩展的注入位置不是随意的。在 bootspec.nix 中,文档的 JSON 是这样组装的:
json = pkgs.writeText filename (
builtins.toJSON
# Merge extensions first to not let them shadow NixOS bootspec data.
(
cfg.extensions
// {
"org.nixos.bootspec.v1" = { ... };
}
)
);
注释揭示了关键设计:扩展先合并,NixOS 官方数据后合并覆盖——也就是官方数据总是优先,用户扩展永远不能遮蔽(shadow) org.nixos.bootspec.v1 等保留命名空间。这保证了第三方扩展无论如何书写,都无法伪造或篡改核心引导数据,是一个重要的安全性约束。
官方示例:SecureBoot 下的 os-release 注入
手册给出的示例场景是 SecureBoot:为了把 /etc/os-release 烘进统一内核镜像(unified kernel image),需要把该文件在 Nix store 中的路径写进 bootspec:
{ config, lib, ... }:
{
boot.bootspec.extensions = {
"org.secureboot.osRelease" = config.environment.etc."os-release".source;
};
}
该配置会在 boot.json 中产生形如 "org.secureboot.osRelease": "/nix/store/...-os-release" 的条目(值会以字符串形式序列化)。后续 SecureBoot 工具链在构建统一内核镜像时,即可从 bootspec 文档中读取该路径、把 os-release 内容嵌入镜像。
测试验证:extensions 端到端链路
仓库在 nixos/tests/bootspec.nix 中提供了 extensions 测试用例,完整验证了这一机制:
boot.bootspec.extensions = {
"org.nix-tests.product" = {
osRelease = config.environment.etc."os-release".source;
};
};
测试脚本先启动机器、等待 multi-user.target,然后断言:
- 通过
jq -r '."org.nix-tests.product".osRelease' /run/current-system/boot.json取出扩展指向的 store 路径; - 读取该路径指向的文件内容;
- 断言其与系统当前
/etc/os-release内容完全一致。
这个测试用例印证了扩展机制的真实语义:扩展中存放的是 store 路径,消费方(如 SecureBoot 工具)应去读取路径指向的文件,而非直接使用 JSON 中的值本身。
命名空间建议
由于 boot.json 的所有顶层键共享同一命名空间池,不同应用之间极易撞名。手册与选项描述给出的约定是:使用反向域名风格(reverse-DNS style)的唯一命名空间,例如 org.secureboot.osRelease、org.nix-tests.product。NixOS 官方保留命名空间 org.nixos.bootspec.v1 与 org.nixos.specialisation.v1 不可占用;从 CUE Schema 可见,扩展键必须能匹配 [=~"^"] 模式(即非空字符串),任意结构都通过 #BootspecExtension: {...} 校验。
外部引导器:boot.loader.external.installHook
除了扩展数据,Bootspec 还配套解决了"如何接入自己的引导器"的问题:通过 boot.loader.external.installHook 可以启用自定义引导器,其语义是包装(wrap)现有引导器安装流程的钩子。
选项与默认行为
该选项实现在 nixos/modules/system/boot/loader/external/external.nix 中:
options.boot.loader.external = {
enable = mkEnableOption "using an external tool to install your bootloader";
installHook = mkOption {
type = with types; path;
description = ''
The full path to a program of your choosing which performs the bootloader installation process.
The program will be called with an argument pointing to the output of the system's toplevel.
'';
};
};
关键行为:
installHook类型为path,即一个可执行程序/脚本的完整路径;- 该程序被调用时,会收到一个参数——系统 toplevel 的输出路径(
$out对应的 toplevel store 路径),由此可以访问$toplevel/boot.json等产物; - 启用
boot.loader.external.enable后,配置会自动施加mkDefault默认值:关闭 GRUB、关闭 systemd-boot、关闭 initrd secrets 支持,避免与内置引导器冲突(external.nix); system.build.installBootLoader被直接指向cfg.installHook,即该钩子成为系统的引导安装器。
手册同时给出一个直观的接入示例:假设你打包了一个名为 FooBoot 的引导器,它提供一个 fooboot-install 程序、以系统闭包路径为唯一参数,则这样启用:
{ pkgs, ... }:
{
boot.loader.external = {
enable = true;
installHook = "${pkgs.fooboot}/bin/fooboot-install";
};
}
当前限制与开发建议
手册对现状做了诚实说明:目前尚不存在"组合既有引导器来增强其功能"的良好方案(例如给现有引导器叠加 SecureBoot 支持)。因此外部引导器往往需要重新实现或复用现有的部分代码。配套的 external.md 还专门给出"Developing Custom Bootloader Backends"一节,明确要求:开发自定义引导器后端时,应当遵循 RFC-0125 的 Bootspec 格式与合成工具(synthesis tools)来识别可引导系统代的关键属性——这正是把 Bootspec 当作引导器之间通用契约的实践落地。
引导器如何消费 boot.json:以 systemd-boot 为例
Bootspec 的价值最终体现在消费端。仓库中的 systemd-boot-builder.py 是从 systemd-boot 迁移到 Bootspec 的典型实现,其 get_bootspec 函数展示了完整的读取链路:
def get_bootspec(profile: str | None, generation: int) -> BootSpec | None:
boot_json_path = (system_directory / "boot.json").resolve()
...
bootspec_json = json.load(f)
return bootspec_from_json(bootspec_json)
bootspec_from_json 则逐层解包:
- 读取
org.nixos.specialisation.v1并递归构造各特化的 BootSpec; - 读取引导器自身命名空间下的扩展,如
org.nixos.systemd-boot与org.nixos.extra-initrd.v1; - 最终从
org.nixos.bootspec.v1提取kernel、initrd、initrdSecrets、devicetree、kernelParams、init、label等字段,拼装出启动菜单项(Generation {n} {label}, built on ...)与内核命令行(init=...前缀拼接kernelParams)。
这印证了架构闭环:NixOS 在构建期写入 boot.json(writer),可选地校验(validator),引导器在安装期读取并渲染启动项——三方都以 RFC-0125 的 Schema 为共同语言。
端到端验证:仓库测试矩阵
nixos/tests/bootspec.nix 用一组 NixOS VM 测试覆盖了 Bootspec 的各个角落,是理解各字段行为最直接的实验依据:
| 测试名 | 场景 | 断言要点 |
|---|---|---|
basic |
systemd-boot + UEFI | 启动后 /run/current-system/boot.json 存在 |
grub |
GRUB + UEFI | boot.json 存在(GRUB 同样产出 bootspec) |
legacy-boot |
GRUB + legacy BIOS | boot.json 存在(无 UEFI 也能产出) |
initrd |
显式启用 initrd | org.nixos.bootspec.v1 含 initrd;未配置 secrets 时不含 initrdSecrets |
initrd-secrets |
配置 boot.initrd.secrets |
文档中出现 initrdSecrets 字段 |
specialisation |
声明一个特化 | 父文档 org.nixos.specialisation.v1.something 与 /run/current-system/specialisation/something/boot.json 的内容一致 |
extensions |
注入 org.nix-tests.product 扩展 |
扩展指向的文件内容与 /etc/os-release 一致 |
这套测试从实际行为层面验证了手册描述的字段条件存在性(initrd、initrdSecrets 何时出现)、特化的文档树结构,以及扩展的 store 路径语义,可以作为你自行实验和排查问题的参照模板。
总结:一份文档,统一所有引导器
Bootspec 为 NixOS 的引导生态确立了一个简单而稳固的契约:
- 构建期:toplevel 构建时无条件生成
boot.json(v1 命名空间),可选地用 CUE Schema 校验; - 扩展期:任何应用可通过
boot.bootspec.extensions在保留命名空间之外注入自有数据,但官方数据优先、不可被遮蔽; - 消费期:内置引导器(systemd-boot、GRUB)与外部引导器(
boot.loader.external.installHook)统一读取boot.json渲染启动项。
对于希望深入引导工作流的开发者,建议依次阅读 手册原文、生成实现、CUE Schema,并以 测试文件 为实验模板,就能快速验证自己在 SecureBoot、统一内核镜像等场景下的扩展方案。