NixOS Bootspec 深入指南:RFC-0125 引导规范、Schema 验证与扩展机制

原创2026-09-19 09:02:271,847 阅读
文章标签:操作系统包管理器

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,然后断言:

  1. 通过 jq -r '."org.nix-tests.product".osRelease' /run/current-system/boot.json 取出扩展指向的 store 路径;
  2. 读取该路径指向的文件内容;
  3. 断言其与系统当前 /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、统一内核镜像等场景下的扩展方案。

登录后查看全文
nixpkgs