将 IronFlockOS 写入驱动器

ironflock os flash 准备新设备启动所用的驱动器。它将 IronFlockOS 和设备配置文件（.flock）写入驱动器，设备在首次启动时注册：它作为该 .flock 文件所对应的设备连接到 IronFlock。您可以准备：

• 设备从中启动的 U 盘、SD 卡或外置磁盘；
• 将 IronFlockOS 安装到 PC 内部磁盘上的安装 U 盘；
• 虚拟机从中启动的磁盘镜像文件。

FlockFlasher 是完成同样工作的桌面应用。如何获取设备的 .flock 文件，参见连接设备。

典型流程

# 1. 插入 U 盘或 SD 卡，然后列出可以写入的驱动器
ironflock os drives
# 2. 可选：列出目录提供的镜像
ironflock os images
# 3. 将 IronFlockOS 和设备的 .flock 文件写入驱动器
sudo ironflock os flash -c device.flock -d /dev/sdb

os flash 会显示其计划，并在擦除驱动器之前询问。完成后，将驱动器插入设备，并让设备从它启动。

ironflock os images

列出可写入驱动器的 IronFlockOS 镜像。默认列出生产通道上发布版本的镜像。

ironflock os images [flags]

可在 Linux 和 macOS 上运行。无需 root。不询问任何内容。

标志

每个命令都接受的标志参见标志、输出与退出码。

执行过程

列表来自下载服务器上已签名的 IronFlockOS 目录 <download base>/ironflockos/manifest.json。只有当目录的 Ed25519 签名能用 ironflock 内置的目录密钥验证通过时，ironflock 才会使用它。FlockFlasher 和设备代理程序固定使用同一密钥。没有任何标志或环境变量能关闭这项检查。除非您指定其他下载基址，否则下载基址为 IronFlock 云，参见下载基址。

上一次验证通过的目录保存在缓存文件夹中，每个下载基址一份副本：

无法访问下载服务器时，由保存的副本代替，并在 stderr 上给出说明。同一下载基址的目录如果比保存的副本旧，会被拒绝。

镜像以其硬件目标、变体和内核命名：ironflockos-<target>-<variant>，实时内核再加上 -rt。ironflockos-amd64-efi-base-rt 是带实时内核的基础系统，适用于带 UEFI 的 x86-64 PC。硬件目标如下：

• amd64-efi — 带 UEFI 的 x86-64 PC
• arm64-efi — 带 UEFI 的 ARM64 机器
• rpi-arm64 — Raspberry Pi 4、400 和 CM4；Raspberry Pi 5 和 CM5

变体有 base、nvidia 和 installer。安装程序镜像用于制作 U 盘，该 U 盘会将它所携带的镜像之一安装到从它启动的机器的磁盘上。此 ironflock 不认识的变体、内核或架构的镜像（来自较新的发布版本）会被略去，并在 stderr 上给出说明。

示例

# 当前生产发布版本的镜像
ironflock os images
# 只列出 Raspberry Pi 镜像
ironflock os images --target rpi-arm64
# 测试通道的镜像，以 JSON 形式输出
ironflock os images --channel test --json

结果

IMAGE                            VERSION  SIZE      HARDWARE
ironflockos-amd64-efi-base       0.13.0   638.1 MB  x86-64 PC with UEFI
ironflockos-amd64-efi-base-rt    0.13.0   650.4 MB  x86-64 PC with UEFI
ironflockos-amd64-efi-nvidia     0.13.0   1.0 GB    x86-64 PC with UEFI
ironflockos-amd64-efi-installer  0.13.0   2.5 GB    x86-64 PC with UEFI, installer stick for base, base-rt, nvidia
ironflockos-arm64-efi-base       0.13.0   582.4 MB  ARM64 machine with UEFI
ironflockos-arm64-efi-base-rt    0.13.0   594.1 MB  ARM64 machine with UEFI
ironflockos-arm64-efi-installer  0.13.0   1.5 GB    ARM64 machine with UEFI, installer stick for base, base-rt
ironflockos-rpi-arm64-base       0.13.0   639.4 MB  Raspberry Pi 4, 400 and CM4; Raspberry Pi 5 and CM5

使用 --json 时（这里带 --target rpi-arm64）：

{"issued_at":"2026-11-10T09:41:47Z","key_id":"036ef3bd","from_cache":false,"channels":{"production":"0.13.0","test":"0.13.0"},"images":[{"image_id":"ironflockos-rpi-arm64-base","version":"0.13.0","channels":["production","test"],"target":"rpi-arm64","variant":"base","kernel":"std","architecture":"arm64","boards":["raspberrypi4","raspberrypi5"],"hardware":["Raspberry Pi 4, 400 and CM4","Raspberry Pi 5 and CM5"],"file":"ironflockos-rpi-arm64-base-0.13.0.img.gz","url":"https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-rpi-arm64-base-0.13.0.img.gz","size":639408901,"sha256":"9abd17f2098dfa236d440005222d0a6b583546ea9768e5eca8807c4e24ec88db"}]}

issued_at 和 key_id 描述目录，channels 给出每个通道的发布版本，下载服务器没有响应时 from_cache 为 true。每个镜像都有其 file，以及该文件的 url、size 和 sha256。boards 是 .flock 文件所指定的板卡型号（board.model），hardware 是它们的名称。安装程序镜像还有 payloads，即它所携带镜像的 id。

失败的情况

• 退出码 2 — 同时给出 --channel 和 --version、格式不是版本号的版本，或者目录中没有的通道、发布版本、硬件目标、变体或内核。错误会列出目录中有的内容。
• 退出码 1 — 目录验证不通过、大于 64 KiB、不是此 ironflock 能读取的目录，或者比保存的副本旧；或者无法获取目录，且没有保存的副本。

ironflock os drives

列出这台机器上可以写入 IronFlockOS 镜像的驱动器：U 盘、SD 卡、外置磁盘。它不写入、不卸载，也不打开任何驱动器。

ironflock os drives [flags]

可在 Linux 和 macOS 上运行。无需 root。不询问任何内容。在 Linux 上，它运行 lsblk（来自 util-linux），并读取 /proc 和 /sys。在 macOS 上，它运行 diskutil list、diskutil info 和 hdiutil info。

标志

每个命令都接受的标志参见标志、输出与退出码。

哪些驱动器会被拒绝

os flash 拒绝 os drives 所拒绝的驱动器，原因相同。驱动器在以下情况下会被拒绝（显示的是第一个适用的原因）：

1. 是分区，例如 /dev/sdb1。拒绝信息会指出它所在的磁盘：镜像要写入整个磁盘。
2. 不是磁盘：光驱、内存中的磁盘（zram）、建立在其他驱动器之上的卷（LVM、dm-crypt、RAID、device-mapper；在 macOS 上为 APFS 容器、AppleRAID 集或其他合成磁盘），或者命令不认识的设备类型（nbd、mtdblock）。
3. 承载着正在运行的系统的一部分：/、/boot、/efi、/usr、/var、/etc 或它们之下的挂载点（位于 /boot/efi 的 EFI 分区、位于 /var/lib/docker 的 Docker 数据）、/home、/opt、/srv、/data、交换空间，或者 Live 系统的介质。无论系统以何种方式位于驱动器上，都是如此：在分区中，通过 LVM、dm-crypt、RAID 或 device-mapper，在跨多个驱动器的 btrfs 文件系统中，在 ZFS 池中，在 overlay 中，或者在由 loop 设备读取的文件中。在 macOS 上：/ 以及 /System 之下的卷，经由其 APFS 容器一直追溯到承载它们的磁盘。
4. 正在被使用：被 LVM、dm-crypt、RAID 或 device-mapper 使用，被挂载了数据集的 ZFS 池使用，或者被读取其上某个文件的 loop 设备使用。在 macOS 上，还包括被其上的 APFS 容器、AppleRAID 集、文件位于其上的磁盘镜像使用，或者被未附加的 Core Storage、AppleRAID 或 APFS 容器使用。只有在 U 盘被抹掉之后，macOS 才会释放带有 APFS 容器的 U 盘，因此原因中会给出抹掉它的命令，例如 diskutil eraseDisk FAT32 IRONFLOCK MBR /dev/disk6（或磁盘工具中的“抹掉”）。
5. 是机器的内部磁盘：SATA 或 NVMe 磁盘、板卡的 eMMC。驱动器只要不是通过 USB 或其他设备可拔出的总线连接，就算作内部磁盘。内置读卡器属于内部设备，但其中的 SD 卡是可移动介质，会作为可写入的驱动器列出，在 Mac 上也是如此。在 macOS 上，没有说明自身位置的磁盘算作内部磁盘。如果没有其他原因拒绝它，os flash --allow-internal 会写入 --drive 所指定的内部磁盘。
6. 可能承载着正在运行的系统的一部分：当正在运行的系统的某一部分无法追溯到某个驱动器时，所有驱动器都会被拒绝。在容器中就是这种情况，因为容器的系统位于其主机上；在 macOS 上，系统所在的卷不对应任何物理磁盘时（例如 Core Storage）也是如此。
7. 是只读的，例如锁定的 SD 卡。
8. 没有介质，例如没有插卡的读卡器。

挂载了文件系统的驱动器会作为可写入的驱动器列出；mounted 列出这些文件系统，os flash 会在写入之前卸载它们。loop 设备以及 macOS 上已附加的磁盘镜像不会被列出，但 os flash 会写入 --drive 所指定的这类设备。

在运行 IronFlockOS 的设备上，命令会在 stderr 和 warnings 中给出警告：同一硬件目标的每个 IronFlockOS 镜像都具有相同的分区 UUID，因此当连接着第二个 IronFlockOS 驱动器时，正在运行的系统无法区分自己的分区和该驱动器的分区。

示例

# 可以写入的驱动器
ironflock os drives
# 所有驱动器，并附上每个被拒绝驱动器的原因
ironflock os drives --all
# 以 JSON 形式输出驱动器
ironflock os drives --json

结果

在 Linux 上：

DEVICE        SIZE     BUS  MODEL
/dev/sdb      15.9 GB  usb  SanDisk Ultra
/dev/mmcblk0  31.9 GB  mmc  SD32G

使用 --all 时：

DEVICE        SIZE     BUS   MODEL                    WRITABLE
/dev/sda      2.0 TB   sata  WDC WD20EZBX-00AYRA0     no: is an internal disk of this machine
/dev/sdb      15.9 GB  usb   SanDisk Ultra            yes
/dev/mmcblk0  31.9 GB  mmc   SD32G                    yes
/dev/nvme0n1  1.0 TB   nvme  Samsung SSD 980 PRO 1TB  no: holds / of the running system

在 Mac 上，使用 --all 时：

DEVICE      SIZE      BUS             MODEL                 WRITABLE
/dev/disk0  500.3 GB  Apple Fabric    APPLE SSD AP0512R     no: holds / of the running system
/dev/disk1  524.3 MB  Apple Fabric    APPLE SSD AP0512R     no: is a volume (APFS container), not a disk
/dev/disk2  5.4 GB    Apple Fabric    APPLE SSD AP0512R     no: is a volume (APFS container), not a disk
/dev/disk3  494.4 GB  Apple Fabric    APPLE SSD AP0512R     no: is a volume (APFS container), not a disk
/dev/disk5  15.9 GB   Secure Digital  Built In SDXC Reader  yes

使用 --json 时（有所缩减）：

{"drives":[{"device":"/dev/sdb","kind":"disk","size":15931539456,"bus":"usb","removable":true,"internal":false,"read_only":false,"vendor":"SanDisk","model":"Ultra","serial":"4C530001230812115352","mounted":[{"device":"/dev/sdb1","mountpoint":"/media/anna/STICK"}],"system":[],"maybe_system":[],"holders":[],"writable":true},{"device":"/dev/mmcblk0",...}],"warnings":[]}

没有可写入的驱动器时，文本会说明这一点，drives 为空，退出码为 0。

失败的情况

• 退出码 3 — 在 Linux 上没有安装 lsblk；或者命令在 Linux 和 macOS 以外的系统上运行。

ironflock os flash

将 IronFlockOS 写入驱动器（U 盘、SD 卡、外置磁盘），并将设备的 .flock 文件放入驱动器的 IRONFLOCKOS 分区，即每个 IronFlockOS 驱动器都有的同名 FAT32 分区。设备在首次启动时用该文件注册。使用 --output 时，它改为将同样的内容写入供虚拟机使用的磁盘镜像文件。

警告：驱动器上的所有内容都会被擦除。写入之前，请用 ironflock os drives 核对驱动器名称。os flash 绝不会自行选择驱动器。

ironflock os flash -c <device.flock> (-d <drive> | --output <file>) [flags]

没有 root 时，错误会给出应输入的命令行，前面带有 sudo。在 macOS 上，有权写入驱动器原始设备的用户无需 root：即附加了磁盘镜像的用户，或者机器所有者将驱动器交给的用户，例如通过 sudo chown <user> /dev/disk4 /dev/rdisk4。使用 --output 时，命令无需 root。另请参见 Root 权限。

标志

每个命令都接受的标志参见标志、输出与退出码。

执行过程

1. 检查驱动器。 它解析 --drive，遇到 os drives 所列的拒绝原因时拒绝该驱动器，这发生在读取、获取或询问任何内容之前。不带 --drive（也不带 --output）时，它列出可以写入的驱动器，并以退出码 2 结束。
2. 读取 .flock 文件。 它必须是名为 *.flock、最大 5 MiB 的文件，内容是一个带有 secret 和 device_key 的 JSON 对象，其 name 和 serial_number 是普通名称。
3. 从已签名的目录中选择镜像，目录的获取和验证方式与 os images 相同。它采用 --image 所指定的镜像，否则采用 .flock 文件所指定硬件的默认镜像（base 变体、标准内核）：依据其 board.model，否则依据其 architecture（当目录中该架构只有一种硬件时）。使用 --installer 时，它采用该硬件中携带此镜像的安装 U 盘。
4. 在 stderr 上显示计划：镜像、其文件的来源、.flock 文件（按名称）、WiFi、驱动器，以及它要卸载的驱动器上的文件系统。然后询问。默认选中“No”，因此直接按 Enter 不会擦除任何内容。
5. 获取镜像文件：--image-file 的文件，否则为缓存中的副本，再否则下载到缓存中，从之前下载中断处续传。以 root 身份运行时，缓存在 Linux 上为 /var/cache/ironflock/images，在 macOS 上为 /var/root/Library/Caches/ironflock/images。下载写入 .part 文件。每个文件只有在其大小和 SHA-256 与目录中的一致时才会写入。一分钟内没有收到任何字节的下载尝试会结束，连续三次这样的尝试之后，下载放弃。
6. 再次检查驱动器。 它必须是计划中显示的驱动器，并且仍未被拒绝：同一设备、大小、序列号和介质。在 Linux 上，还包括厂商、型号、总线，以及每个分区及其文件系统、卷标、UUID 和大小。在 macOS 上（它不提供序列号），检查的是型号、总线、在设备树中的位置，以及各分区及其 UUID。自计划显示以来被拔出的 U 盘会将其名称让给下一个插入的驱动器；这样的驱动器不会被写入，也不会卸载任何内容。然后，命令卸载计划中列出的文件系统，且仅卸载这些，并以独占方式打开驱动器进行写入。在 macOS 上，它通过原始设备（/dev/rdisk4）写入，第二个 os flash 无法同时打开该设备。
7. 写入镜像，然后回读驱动器并进行比较。
8. 将 .flock 文件写入 IRONFLOCKOS 分区的根文件夹，不挂载该分区。安装 U 盘还会得到 installer.conf。使用 --wifi-ssid 时，驱动器上的副本指定该网络；.flock 文件本身不会更改。
9. 在 macOS 上弹出驱动器（diskutil eject），以便您取出它。弹出失败时，驱动器照样已写入：命令会给出警告，请在 Finder 中弹出驱动器后再取出。

以 root 身份运行时，命令只使用满足以下条件的缓存文件夹：它是文件夹而不是链接，属于 root，并且其他任何人都不能写入。缺少时，它以权限 0700 创建该文件夹；遇到任何其他情况，它会在读取、删除或下载那里的任何内容之前停止。在获取目录中的镜像之前，它会删除缓存中目录不再列出的镜像文件，以及它们未下载完的部分。

如果 --image 所指的硬件与 .flock 文件所指定的不同，镜像会在计划中给出警告后写入：设备将无法运行其应用。在运行 IronFlockOS 的设备上，计划会像 os drives 那样给出警告。使用 --allow-internal 时，计划会警告该驱动器是内部磁盘。

--yes 以“是”回答询问。没有终端（管道、脚本）且未给出 --yes 时，命令不询问，并以退出码 4 结束。--json 同样不询问任何内容，因此需要 --yes 才能写入驱动器。使用 --json 时，不输出计划：stderr 只承载进度事件，警告位于结果中。参见询问与确认和输出与 JSON。

WiFi

设备加入其 .flock 文件所指定的 WiFi。--wifi-ssid 为它指定另一个网络。IronFlockOS 只加入带密码的 WiFi，因此 --wifi-ssid 和 --wifi-password-file 总是同时使用。密码来自文件或管道，绝不来自命令行，因为 ps 和 shell 历史记录会显示命令行。命令不会在任何地方输出密码。驱动器上的 .flock 文件副本在 wlanssid 和 password 中指定该网络。

注意：密码通过 /dev/stdin 传入时，stdin 不是终端，因此命令无法询问。请加上 --yes。

安装 U 盘

使用 --installer 时，驱动器成为带 UEFI 的 PC（amd64-efi、arm64-efi）的安装 U 盘；ironflock os images --variant installer 列出安装程序镜像。该 U 盘携带其硬件的多个镜像；U 盘上的 installer.conf 指定它要安装的镜像（payload，按第 3 步的方式选择），并保存您给出的 --installer-* 标志。PC 从该 U 盘启动时，安装程序会：

1. 按 --installer-disk 选择磁盘：最大的磁盘（默认）、磁盘 /dev/<name>，或 id 为 by-id:<id> 的磁盘。只有带 --installer-allow-usb yes 时，它才会写入 USB 磁盘。
2. 在写入之前在 PC 的控制台上询问，除非给出了 --installer-confirm no。
3. 将镜像和设备的 .flock 文件写入该磁盘。
4. 关闭 PC（默认），或者在给出 --installer-after reboot 时重启 PC。

取出 U 盘，让 PC 从其内部磁盘启动。设备在首次启动时注册。

警告：用 --installer-confirm no 写入的 U 盘会不经询问地擦除每台从它启动的 PC 的磁盘。请给这样的 U 盘贴上标签，并让它远离其他机器。

要在不用 U 盘的情况下替换正在运行的机器上的 Linux，参见用 IronFlockOS 替换 Linux。

预先下载的镜像文件

--image-file 写入您之前下载的镜像文件，例如在无法下载目录中镜像文件的机器上。文件的地址取自 os images --json 的 url。只有当文件的大小和 SHA-256 与目录中该镜像的一致时，才会写入。

命令仍然需要已签名的目录来检查文件。它会获取目录；无法访问下载服务器时，则使用上一次同一下载基址的目录验证通过时保存的副本。该副本按用户保存：以 root 身份运行时，使用的是 root 的副本。您自己的服务器同样可用：使用其他下载基址（--download-base 或 IRONFLOCK_DL_BASE）时，命令从 <download base>/ironflockos/manifest.json 获取目录，从 <download base>/ironflockos/<version>/<file> 获取镜像文件。

注意：文件在写入时会再读取一次，其 SHA-256 要到写入之后才能再次确认。请将文件放在其他用户无法更改的位置。

用于虚拟机的镜像文件

--output <file> 将镜像和设备的文件写入普通文件，而不是驱动器：即虚拟机作为其磁盘启动所用的原始磁盘镜像。镜像、对它的检查以及 IRONFLOCKOS 中的文件都与写入驱动器时相同。命令不查找、不卸载也不打开任何驱动器，因此无需 root。--image、--image-file、--installer 及其标志，以及 --wifi-ssid 的作用与写入驱动器时相同。

• 大小 — 计划会给出文件及其大小：即镜像解压后的大小。如果镜像尚待下载，这一行在下载之后输出。
• 询问 — 新文件不会擦除任何内容，命令不询问。已存在的文件会被替换：计划会说明这一点，命令会先询问。
• 先用另一个名称 — 镜像写入同一文件夹中的一个新文件 <file>.<number>.part。只有当它包含完整镜像、已回读、且其 IRONFLOCKOS 分区中有设备的文件时，它才会得到名称 <file>。写入失败或被中断时会删除 .part 文件，该名称下要么什么都没有，要么是原来的文件，保持不变。kill -9 或断电可能会留下 .part 文件。
• 私密 — 与 .flock 文件一样，该文件包含设备的机密。它的权限为 0600，替换权限更宽松的文件时也是如此。
• 稀疏 — 镜像中整块为零的地方（以 4 MiB 为块），在支持空洞的文件系统上，文件中会留下空洞。读取结果相同，但占用的空间更少。

# 为虚拟机写入磁盘镜像文件，无需 root
ironflock os flash -c device.flock --output device.img

IronFlockOS catalog of 2026-11-10T09:41:47Z, signed with key 036ef3bd.
Image:        ironflockos-amd64-efi-base 0.13.0, for x86-64 PC with UEFI
Image file:   https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-amd64-efi-base-0.13.0.img.gz (638.1 MB), downloaded and checked against the catalog
Device file:  device.flock, for the device kitchen-pc
WiFi:         Office (from the .flock)
Output:       device.img, a new file: the image, unpacked; its size is known once the image is downloaded
(the progress of downloading, checking)
Unpacked, the image has 4.6 GB: the size of device.img.
(the progress of writing, reading back)
Done: IronFlockOS 0.13.0 (ironflockos-amd64-efi-base) is in device.img and read back, with device.flock in its IRONFLOCKOS partition.
Grow the file to the size of the virtual machine's disk before the machine starts from it (truncate -s 20G device.img): on its first boot IronFlockOS makes slot B and /data in that space, and the device enrolls as kitchen-pc.

该镜像包含 IRONFLOCKOS 分区，以及 IronFlockOS 轮流更新的两个系统槽位中的第一个（槽位 A）。首次启动时，IronFlockOS 会创建与槽位 A 同样大小的槽位 B，并用磁盘的其余空间创建数据分区 /data。请在虚拟机首次从该文件启动之前扩大文件：base 至少 10 GiB，nvidia 至少 18 GiB。文件增加的部分全是零，文件系统将其保存为空洞。接受原始磁盘的 Hypervisor 可以直接使用该文件。如需其他格式，请转换扩大后的文件，例如用 qemu-img convert -f raw -O qcow2 device.img device.qcow2。

amd64-efi 和 arm64-efi 的镜像可以在 QEMU 中启动；Raspberry Pi 的镜像（rpi-arm64）不能。对于 amd64-efi，在带 KVM 的 Linux 上使用软件包 ovmf（Debian、Ubuntu）提供的 UEFI 固件：

# 扩大文件，复制固件的变量，然后启动机器
truncate -s 20G device.img
cp /usr/share/OVMF/OVMF_VARS_4M.fd device-vars.fd
qemu-system-x86_64 -machine q35 -accel kvm -cpu host -m 2048 -smp 2 \
  -drive if=pflash,format=raw,unit=0,readonly=on,file=/usr/share/OVMF/OVMF_CODE_4M.fd \
  -drive if=pflash,format=raw,unit=1,file=device-vars.fd \
  -drive file=device.img,format=raw,if=virtio \
  -netdev user,id=net0 -device virtio-net-pci,netdev=net0 \
  -device i6300esb \
  -nographic

• -nographic 将第一个串口接到终端上，GRUB 和内核会输出到那里。Ctrl-A X 结束 QEMU。
• -device i6300esb 是一个看门狗，IronFlockOS 通过它重启卡死的机器。
• -netdev user 为机器提供主机的网络，设备经由它访问 IronFlock。
• 没有 KVM 时（没有 /dev/kvm，或者主机是其他架构），请去掉 -accel kvm 并使用 -cpu max。此时 QEMU 会模拟整台机器，速度要慢得多。

arm64-efi 用 qemu-system-aarch64 -machine virt 和软件包 qemu-efi-aarch64 的固件（/usr/share/AAVMF/AAVMF_CODE.fd，以及 AAVMF_VARS.fd 的副本）启动，不带看门狗。在使用 Apple 芯片的 Mac 上，Homebrew 的 QEMU 用 -accel hvf -cpu host 和固件 /opt/homebrew/share/qemu/edk2-aarch64-code.fd（以及 edk2-arm-vars.fd 的副本）启动它。

示例

# 将适用于 .flock 文件所指定硬件的默认镜像写入 U 盘
sudo ironflock os flash -c device.flock -d /dev/sdb
# 写入安装 U 盘，它会在 PC 上安装 NVIDIA 镜像
sudo ironflock os flash -c device.flock -d /dev/sdb --image amd64-efi-nvidia --installer
# 为加入 WiFi “Workshop” 的设备写入 SD 卡
sudo ironflock os flash -c device.flock -d /dev/mmcblk0 --wifi-ssid Workshop --wifi-password-file wifi.txt
# 在 Mac 上写入 U 盘
sudo ironflock os flash -c device.flock -d /dev/disk4

结果

计划和进度输出到 stderr；最后几行是结果。在 Linux 上：

IronFlockOS catalog of 2026-11-10T09:41:47Z, signed with key 036ef3bd.
Image:        ironflockos-amd64-efi-base 0.13.0, for x86-64 PC with UEFI
Image file:   https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-amd64-efi-base-0.13.0.img.gz (638.1 MB), downloaded and checked against the catalog
Device file:  device.flock, for the device kitchen-pc
WiFi:         Office (from the .flock)
Drive:        /dev/sdb: SanDisk Ultra, 15.9 GB, usb, serial 4C530001230812115352
Everything on /dev/sdb is erased. Unmounted first: /media/anna/STICK.
(the progress of downloading, checking, writing, reading back)
Done: IronFlockOS 0.13.0 (ironflockos-amd64-efi-base) is on /dev/sdb and read back, with device.flock in its IRONFLOCKOS partition.
Start the device from it: it enrolls as kitchen-pc on its first boot.

在 Mac 上，先不用 root，再用 sudo：

$ ironflock os flash -c pi.flock -d /dev/disk5
Error: "ironflock os flash" must run as root (sudo) to write a drive: sudo ironflock os flash -c pi.flock -d /dev/disk5
$ sudo ironflock os flash -c pi.flock -d /dev/disk5 --yes
IronFlockOS catalog of 2026-11-10T16:41:54Z, signed with key 036ef3bd.
Image:        ironflockos-rpi-arm64-base 0.14.0, for Raspberry Pi 4, 400 and CM4
Image file:   https://instance-registry.ironflock.com/dl/ironflockos/0.14.0/ironflockos-rpi-arm64-base-0.14.0.img.gz (640.1 MB), downloaded and checked against the catalog
Device file:  pi.flock, for the device pi-workshop
WiFi:         Office (from the .flock)
Drive:        /dev/disk5: Built In SDXC Reader, 15.9 GB, Secure Digital
Everything on /dev/disk5 is erased. Unmounted first: /Volumes/UNTITLED.
(the progress of downloading, checking, writing, reading back)
Done: IronFlockOS 0.14.0 (ironflockos-rpi-arm64-base) is on /dev/disk5 and read back, with pi.flock in its IRONFLOCKOS partition.
/dev/disk5 is ejected and can be taken out.
Start the device from it: it enrolls as pi-workshop on its first boot.

使用 --json 时，这里以安装 U 盘为例（--installer --installer-confirm no --yes --json）：

{"action":"flashed","device":"kitchen-pc","device_file":"device.flock","hardware":"x86-64 PC with UEFI","image":{"image_id":"ironflockos-amd64-efi-installer","version":"0.13.0","file":"ironflockos-amd64-efi-installer-0.13.0.img.gz","url":"https://instance-registry.ironflock.com/dl/ironflockos/0.13.0/ironflockos-amd64-efi-installer-0.13.0.img.gz","size":2512345678,"sha256":"..."},"installer":{"payload":"ironflockos-amd64-efi-base","disk":"largest","confirm":"no","after":"poweroff","allow_usb":"no"},"wifi":{"ssid":"Office","from":"flock"},"drive":{"device":"/dev/sdb","size":15931539456,"bus":"usb","model":"SanDisk Ultra","serial":"4C530001230812115352","internal":false},"source":"download","unmounted":["/media/anna/STICK"],"bytes":6442450944,"verified":true,"ejected":false,"files":["device.flock","installer.conf"],"catalog":{"issued_at":"2026-11-10T09:41:47Z","key_id":"036ef3bd","from_cache":false,"notes":[]},"warnings":[]}

使用 --output 时，结果中用 output 代替 drive，例如 "output":{"file":"/home/anna/device.img","replaced":true}。

拒绝执行的情况

退出码 3，不写入任何内容：

• 驱动器属于 os drives 会拒绝的驱动器；错误会给出原因，--yes 不会改变这一点。唯一的例外是这台机器的内部磁盘：当 --drive 指定它时，--allow-internal 会写入它；如果该标志能让驱动器变为可写入，错误会指出该标志。该标志不会解除其他任何拒绝，也不会回答询问。
• 驱动器在计划和写入之间发生了变化，或者在那时被拒绝。错误会说明变化的内容。
• 打开驱动器时，它正在被使用：挂载了计划中未列出的文件系统、某个文件系统无法卸载，或者有程序占用着驱动器。
• 命令不是以 root 身份运行（或者在 macOS 上，不是以有权写入驱动器原始设备的用户身份运行）。错误会给出带 sudo 的命令行。
• 使用 --output 时：该名称不是普通文件（设备、文件夹、命名管道或任何符号链接），或者其所在文件夹不存在，这会在读取或获取任何内容之前被拒绝。不能创建新文件的文件夹（没有权限、只读文件系统）会在计划之后、下载之前被拒绝。如果计划中指定的是新文件，而在写入镜像期间有文件占用了该名称，该文件不会被替换。

退出码 2，错误的命令行：

• 既没有 --drive 也没有 --output，即使带有 --allow-internal。--output 与 --drive 或 --allow-internal 同用、没有名称或名称为 -。--output 指定的是 -c 的 .flock 文件或 --image-file 的文件。
• 没有 --installer 却给出了 --installer-* 标志，或者给出了安装程序不接受的值。
• 有 --wifi-ssid 却没有 --wifi-password-file，或者反过来。
• .flock 文件没有说明它适用于哪种硬件；此时由 --image 选择镜像。
• 目录中没有的镜像、不携带该镜像的安装 U 盘，或者没有安装 U 盘的硬件。
• 使用 --host 时的 --image-file 和 --output，因为 --host 不会把镜像文件复制到另一台机器上，也不会把文件带回。请在本机不带 --host 运行该命令，或者直接在那台机器上运行。.flock 文件和密码文件则会一并发送。

退出码 4：询问被回答为“否”（直接按 Enter 或按 Esc），或者无法询问且未给出 --yes。

退出码 1，命令失败：

• .flock 文件或密码文件无效，或者镜像文件不是目录中的文件。
• 目录无法使用，原因与 os images 失败的原因相同。
• 下载、写入或回读失败。在第一个数据块之后失败的写入（I/O 错误、驱动器比镜像小）会说明驱动器现在只有镜像的一部分，无法启动任何东西：请重新写入。
• 镜像已写入驱动器并已回读，但 .flock 文件无法写入 IRONFLOCKOS。没有它，设备不会注册；同一命令会再次写入两者。
• 使用 --output 时：文件系统已满、设备的文件无法放入镜像，或者在写入镜像期间 .part 文件在文件夹中的条目被替换。此时该名称保持原样。

退出码 130：在下载、写入或回读镜像时按下 Ctrl-C。被中断的下载尚未写入任何内容，同一命令会续传它。写入或回读会在下一个数据块处停止，错误会说明驱动器中有什么。一旦回读完最后一个数据块，命令会完成最后几个简短步骤，并以 0 结束。再按一次 Ctrl-C 会立即结束命令；使用 --output 时，可能会留下 .part 文件。