firectl全命令行选项速查表：Firecracker microVM内核、磁盘、网络、CPU、内存参数一次讲透
【免费下载链接】firectlfirectl is a command-line tool to run Firecracker microVMs项目地址: https://gitcode.com/gh_mirrors/fi/firectl
firectl 是一个用于运行 Firecracker microVM的命令行工具，一条命令即可拉起带控制台、磁盘读写和网络连接功能的轻量级虚拟机。这篇文章把它的全部命令行选项按内核、磁盘、网络、CPU、内存、日志、Jailer 七个类别做成速查表，帮你一次讲透每个参数的含义、默认值和常见坑点。
30秒了解 firectl
- ⚡定位：纯命令行运行 Firecracker microVM，支持 console 交互、根文件系统读写、TAP 网络
- 📦版本：当前版本
0.2.0，兼容 Firecracker1.0.0（定义在version.go） - 🛠构建：需要 Go 1.23+，执行
make即可；环境不方便装 Go 时可用make build-in-docker - 🐧前置条件：firecracker 二进制、未压缩的内核镜像
vmlinux、根文件系统镜像
快速开始：构建与最小化启动
git clone https://gitcode.com/gh_mirrors/fi/firectl cd firectl make # 或 make build-in-docker最简启动只需要内核和根磁盘两个参数：
./firectl \ --kernel=hello-vmlinux.bin \ --root-drive=hello-rootfs.ext4如果系统 PATH 中找不到 firecracker，可用--firecracker-binary显式指定二进制路径（查找逻辑见main.go中的runVMM）。
全选项速查总表
参数定义集中在
options.go的options结构体中，下表与其一一对应。
1️⃣ 内核类参数
| 选项 | 缩写 | 默认值 | 说明 |
|---|---|---|---|
--kernel | - | ./vmlinux | 内核镜像路径（未压缩的 vmlinux） |
--kernel-opts | - | ro console=ttyS0 noapic reboot=k panic=1 pci=off nomodules | 内核命令行参数 |
--initrd-path | - | 无 | initrd 路径（0.2.0 版本新增） |
💡要点：--kernel-opts默认以ro（只读）启动，若需要写入文件系统记得改成rw；console=ttyS0是控制台能正常输出的关键。
2️⃣ 磁盘类参数
| 选项 | 缩写 | 默认值 | 说明 |
|---|---|---|---|
--root-drive | - | 无 | 根磁盘镜像路径，可加:ro或:rw后缀 |
--root-partition | - | 无 | 根分区 UUID（partuuid） |
--add-drive | - | 无 | 附加磁盘，必须带:ro/:rw后缀，可多次指定 |
💡要点：
- 根磁盘的 Drive ID 固定为
1，附加磁盘从2开始自动编号（见options.go中getBlockDevices） - 附加磁盘缺少
:ro/:rw后缀会直接报错退出 - 根磁盘的只读/读写切换是 0.2.0 版本才加入的能力
3️⃣ 网络类参数
| 选项 | 缩写 | 默认值 | 说明 |
|---|---|---|---|
--tap-device | - | 无 | TAP 网卡，格式DEVICE/MAC，可多次指定 |
--vsock-device | - | 无 | vsock 设备，格式PATH:CID，可多次指定 |
--metadata | - | 无 | MMDS 元数据，JSON 格式 |
💡要点：
--tap-device必须写成DEVICE/MACADDR两段，例如tap0/52:54:00:12:34:56，否则报格式错误--vsock-device的 CID 必须是数字，格式为unix-socket路径:CID- 只要传了合法的
--metadata，firectl 会自动为网卡开启 MMDS（见options.go中getNetwork）
4️⃣ CPU 与内存参数
| 选项 | 缩写 | 默认值 | 说明 |
|---|---|---|---|
--ncpus | -c | 1 | vCPU 数量 |
--memory | -m | 512 | 内存大小，单位MiB |
--disable-smt | -t | 关闭 | 禁用超线程（SMT） |
--cpu-template | - | 无 | CPU 模板，仅支持C3或T2 |
💡要点：microVM 追求极简，默认 1 vCPU + 512 MiB 即可跑通大多数测试场景；-t常与--cpu-template搭配，用于复现特定硬件行为。
5️⃣ 日志与调试参数
| 选项 | 缩写 | 默认值 | 说明 |
|---|---|---|---|
--vmm-log-fifo | - | 无 | VMM 日志 FIFO 路径 |
--log-level | - | Debug | 日志级别 |
--metrics-fifo | - | 无 | 指标输出 FIFO 路径 |
--firecracker-log | -l | 无 | 把 FIFO 内容重定向到指定日志文件 |
--socket-path | -s | 自动生成 | Firecracker API socket 路径 |
--debug | -d | 关闭 | 启用 firectl 自身的调试输出 |
💡要点：
- 不指定 socket 时，firectl 会在
$HOME或临时目录中自动生成一个随机.firecracker.sock文件 - FIFO 文件通常成对出现，只给其中一个时另一个会自动生成在临时目录
fcfifo*下，退出时自动清理 - ⚠️
--vmm-log-fifo与--firecracker-log不能同时使用，会直接报错
6️⃣ Jailer 沙箱参数
Jailer 是 Firecracker 的权限隔离器，0.2.0 版本起 firectl 完整支持（--jailer非空时自动启用，见options.go）：
| 选项 | 缩写 | 说明 |
|---|---|---|
--jailer | - | Jailer 二进制路径（指定即启用沙箱模式） |
--id | - | Jailer VMM ID |
--exec-file | - | Jailer 要执行的文件 |
--uid/--gid | - | 降权运行的 UID / GID |
--node | - | 绑定的 NUMA 节点 |
--chroot-base-dir | - | chroot 基础目录 |
--daemonize | - | 以后台守护进程方式运行 |
7️⃣ 基础参数
| 选项 | 缩写 | 说明 |
|---|---|---|
--firecracker-binary | - | firecracker 二进制路径，默认在 PATH 中查找 |
--version | - | 输出版本号与支持的 Firecracker 版本 |
--help | -h | 打印帮助信息（无参数运行时也会打印） |
实战：一个覆盖多类参数的完整示例
官方 README 中的典型用法，一次用到了 CPU 模板、日志、内核参数、vsock 和 MMDS 元数据：
firectl \ --kernel=~/bin/vmlinux \ --root-drive=/images/image-debootstrap.img -t \ --cpu-template=T2 \ --firecracker-log=~/firecracker-vmm.log \ --kernel-opts="console=ttyS0 noapic reboot=k panic=1 pci=off nomodules rw" \ --vsock-device=root:3 \ --metadata='{"foo":"bar"}'常见报错速查 🩺
以下报错均定义在errors.go，对照选项即可快速定位：
| 报错信息 | 原因与解决 |
|---|---|
NIC config wasn't of the form DEVICE/MACADDR | --tap-device未写成设备名/MAC两段 |
invalid drive specification. Must have :rw or :ro suffix | 附加磁盘漏写:ro/:rw后缀 |
invalid drive specification. Must have path | 后缀前没有给出磁盘路径 |
unable to parse vsock devices/...parse vsock CID as a number | vsock 格式应为PATH:数字CID |
vmm-log-fifo and firecracker-log cannot be used together | 两个日志选项互斥，二选一 |
invalid metadata, unable to parse as json | --metadata不是合法 JSON |
源码结构导航 📂
options.go：全部选项定义、参数解析与 Firecracker 配置转换的核心main.go：参数解析入口、firecracker 二进制检查、VMM 启动与信号处理errors.go：所有可预期错误的定义version.go：版本号0.2.0与兼容版本Makefile：build/build-in-docker/install等构建目标CHANGELOG.md：0.2.0 版本新增 initrd、根磁盘只读、Jailer、多网卡等能力
一页纸记忆清单 ✅
| 场景 | 关键选项 |
|---|---|
| 最简启动 | --kernel+--root-drive |
| 需要写盘 | --root-drive=xxx.img:rw或--kernel-opts改rw |
| 加磁盘 | --add-drive=path:ro（可重复） |
| 上网 | --tap-device=tap0/52:54:00:xx:xx:xx |
| 宿主直连 | --vsock-device=sockpath:CID+--metadata |
| 规格调整 | -cCPU 数、-m内存 MiB、-t关超线程 |
| 排障 | -l落盘日志、-d调试输出、--log-level |
掌握这张速查表后，你就能用 firectl 在命令行上灵活拉起任意规格的 Firecracker microVM 了。
【免费下载链接】firectlfirectl is a command-line tool to run Firecracker microVMs项目地址: https://gitcode.com/gh_mirrors/fi/firectl
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
