Nebula VPN 1.11.2 常用 CLI 命令详解

Nebula VPN 1.11.2 CLI 命令详解：nebula 主程序（-version/-config/-test/运行期信号）与 nebula-cert 全命令树（ca/keygen/sign/print/verify）逐条实测，含离线签发、过期校验、错误证书链等真实回显与 FAQ。

Nebula VPNVPNCLI命令运维2026/10/20

Nebula VPN 1.11.2 常用 CLI 命令详解

目标：逐条讲清 Nebula VPN 1.11.2 的两个二进制的命令行用法——nebula 主程序与 nebula-cert 证书工具，全部子命令与参数帮助均在本机实测采集，回显逐字照抄（执行日期 2026-10-20）。参数生效方式与组网行为见《Nebula VPN 1.11.2 配置参数详解》（https://www.quzuo.net/document/XSxgqonBfRXI），安装步骤见《Ubuntu 22.04 安装 Nebula VPN 指南》（https://www.quzuo.net/document/q9aNBLxK6Apa）。

一、环境信息

  • 操作系统：Ubuntu 22.04.4 LTS（x86_64）
  • 软件版本：Nebula VPN 1.11.2（官方二进制，nebula 与 nebula-cert 均实测）
  • 实测路径：二进制 /usr/local/bin/{nebula,nebula-cert}，PKI 目录 /etc/nebula/（CA 名 Quzuo Nebula CA，节点 lighthouse/client）
  • 测试用例覆盖：正常签发、重复签发拒绝、错误 CA 链校验、过期证书校验、离线公钥签发、QR 输出、配置校验与热加载

二、工具概览

Nebula 发布件包含两个二进制，职责完全分开：

二进制职责运行方式
nebula守护进程：握手、加解密、防火墙、TUN 收包常驻，读配置启动
nebula-cert证书工具：CA/证书签发、打印、校验按需执行，跑完即退

nebula-cert 不带参数运行会给出完整模式列表（实测）：

nebula-cert

实测输出：

Error: No mode was provided

Usage of nebula-cert <global flags> <mode>:
  Global flags:
    -version: Prints the version
    -h, -help: Prints this help message

  Modes:
    ca <flags>: create a self signed certificate authority
    keygen <flags>: create a public/private key pair. the public key can be passed to `nebula-cert sign`
    sign <flags>: create and sign a certificate
    print <flags>: prints details about a certificate
    verify <flags>: verifies a certificate isn't expired and was signed by a trusted authority.

  To see usage for a given mode, use nebula-cert <mode> -h

即 v1.11.2 的证书工具只有 ca / keygen / sign / print / verify 五个模式，每个模式用 nebula-cert <mode> -h 看用法（本文五~九节逐个展开）。

三、前置条件

  1. 已按 B1 篇安装两个二进制并确认 nebula -version / nebula-cert -version 回显 Version: 1.11.2；
  2. 证书签发建议在独立的运维机/签发机上执行，节点只分发 ca.crt 与自身证书私钥，避免 CA 私钥扩散；
  3. 所有路径类参数支持 -（stdin/stdout），官方帮助首行统一标注：Pass "-" to any path flag to read from stdin or write to stdout.。

四、nebula 主程序命令详解

4.1 -version 与 -help

nebula -version
nebula -help

实测输出：

Version: 1.11.2
Usage of nebula:
  -config string
    	Path to either a file or directory to load configuration from
  -help
    	Print command line usage
  -test
    	Test the config and print the end result. Non zero exit indicates a faulty config
  -version
    	Print version

主程序只有 4 个 flag，没有子命令。-config 的值既可以是单个文件，也可以是目录（官方帮助原文 "Path to either a file or directory"）。

4.2 -config：指定配置启动

nebula -config /etc/nebula/config.yaml

前台启动即进入常驻运行（生产用 systemd 托管，单元文件见 B1 篇 4.6 节）。启动成功的关键日志行（实测）：

time=2026-10-20T18:21:28.491+08:00 level=INFO msg=listening addr=0.0.0.0:4242
time=2026-10-20T18:21:28.491+08:00 level=INFO msg="Nebula interface is active" interface=nebula0 networks=[10.99.0.1/24] build=1.11.2 udpAddr=0.0.0.0:4242 boringcrypto=false

端口被占用时的失败形态（实测，先打 listening 再报 bind 错误并以非零退出）：

time=2026-10-20T18:44:39.490+08:00 level=INFO msg=listening addr=0.0.0.0:4242
time=2026-10-20T18:44:39.500+08:00 level=ERROR msg="Failed to open udp listener" queue=0 error="unable to bind to socket: address already in use"

4.3 -test：配置校验（不启动）

nebula -test -config /etc/nebula/config.yaml
echo "exit=$?"

实测输出节选（实测尾部；首行为整份生效配置的单行回显）：

time=2026-10-20T18:21:10.771+08:00 level=INFO msg="Firewall started" firewallHashes=SHA:498215dec4e5687a2353f51c10838c113bd1af35ef72b8e8c9f536986ada5417,FNV:2782948616
time=2026-10-20T18:21:10.771+08:00 level=INFO msg="Main HostMap created" preferredRanges=[]
time=2026-10-20T18:21:10.771+08:00 level=INFO msg="punchy enabled"
exit=0

故障配置时 exit=1 并给出具体原因（实测：证书路径不存在 + 端口非法）：

time=2026-10-20T18:21:10.785+08:00 level=ERROR msg="Could not load client cert" error="unable to read pki.cert file /etc/nebula/missing.crt: open /etc/nebula/missing.crt: no such file or directory"
exit=1

任何配置变更后的标准流程：先 -test 看回显，再决定 HUP 热加载还是 restart。

4.4 运行期信号

信号行为（实测）
SIGHUP重载配置：日志 Caught HUP, reloading config；防火墙立即重装（New firewall has been installed ... rulesVersion=1）；stats 监听可热起（Starting prometheus stats listener addr=127.0.0.1:9801）
SIGTERM干净退出：systemctl stop nebula 后 is-active 回显 inactive、UDP 4242 监听消失、TUN 网卡随之删除（ip link show nebula0 回显 Device "nebula0" does not exist.）

systemd 场景发 HUP 的推荐写法（实测）：

kill -HUP $(systemctl show -p MainPID --value nebula)

五、nebula-cert ca：创建 CA

5.1 用法与参数

nebula-cert ca -h

实测输出（完整参数表）：

Usage of nebula-cert ca <flags>: create a self signed certificate authority
  Pass "-" to any path flag to read from stdin or write to stdout.
  -argon-iterations uint
    	Optional: Argon2 iterations parameter used for encrypted private key passphrase (default 1)
  -argon-memory uint
    	Optional: Argon2 memory parameter (in KiB) used for encrypted private key passphrase (default 2097152)
  -argon-parallelism uint
    	Optional: Argon2 parallelism parameter used for encrypted private key passphrase (default 4)
  -curve string
    	EdDSA/ECDSA Curve (25519, P256) (default "25519")
  -duration duration
    	Optional: amount of time the certificate should be valid for. Valid time units are seconds: "s", minutes: "m", hours: "h" (default 8760h0m0s)
  -encrypt
    	Optional: prompt for passphrase and write out-key in an encrypted format
  -groups string
    	Optional: comma separated list of groups. This will limit which groups subordinate certs can use
  -ips string
    	Deprecated, see -networks
  -name string
    	Required: name of the certificate authority
  -networks string
    	Optional: comma separated list of ip address and network in CIDR notation. This will limit which ip addresses and networks subordinate certs can use in networks
  -out-crt string
    	Optional: path to write the certificate to (default "ca.crt")
  -out-key string
    	Optional: path to write the private key to (default "ca.key")
  -out-qr string
    	Optional: output a qr code image (png) of the certificate
  -subnets string
    	Deprecated, see -unsafe-networks
  -unsafe-networks string
    	Optional: comma separated list of ip address and network in CIDR notation. This will limit which ip addresses and networks subordinate certs can use in unsafe networks
  -version uint
    	Optional: version of the certificate format to use (default 2)

5.2 实测创建

mkdir -p /etc/nebula
nebula-cert ca -name "Quzuo Nebula CA" -duration 87600h -out-crt /etc/nebula/ca.crt -out-key /etc/nebula/ca.key
echo "exit=$?"
ls -l /etc/nebula/

实测输出（命令静默成功；ls 回显如下，文件权限自动 0600）：

exit=0
total 8
-rw------- 1 root root 261 10月 20 18:20 ca.crt
-rw------- 1 root root 174 10月 20 18:20 ca.key

要点解读：

  • -duration 87600h = 10 年；不写则默认 1 年（帮助回显 default 8760h0m0s）。CA 有效期上限决定了所有子证书的有效期上限；
  • -curve 默认 25519（Ed25519/curve25519），兼容旧网络才选 P256；
  • -version 默认 2（当前证书格式，networks/unsafeNetworks 字段即 v2 术语）；
  • -encrypt 可用 Argon2 口令加密 CA 私钥（-argon-* 三参为 KDF 调参）；
  • -networks/-unsafe-networks 可在 CA 层面限制子证书能用的网段；-groups 限制子证书能用的组。-ips/-subnets 已废弃。

六、nebula-cert keygen：生成密钥对

6.1 用法

Usage of nebula-cert keygen <flags>: create a public/private key pair. the public key can be passed to `nebula-cert sign`
  Pass "-" to any path flag to read from stdin or write to stdout.
  -curve string
    	ECDH Curve (25519, P256) (default "25519")
  -out-key string
    	Required: path to write the private key to
  -out-pub string
    	Required: path to write the public key to

6.2 实测

nebula-cert keygen -out-key device.key -out-pub device.pub
echo "exit=$?"
ls -l device.key device.pub
cat device.pub

实测输出：

exit=0
-rw------- 1 root root 127 10月 20 18:35 device.key
-rw------- 1 root root 125 10月 20 18:35 device.pub
-----BEGIN NEBULA X25519 PUBLIC KEY-----
vJUWCgAfAEWenenxggIzdlk8jSYngaR2fXjzdVd8mwY=
-----END NEBULA X25519 PUBLIC KEY-----

keygen 只造密钥不造证书，公钥交给签发方走 sign -in-pub（见十、10.1），是「私钥不出设备」安全签发流程的基础。

七、nebula-cert sign：签发节点证书

7.1 用法与参数

Usage of nebula-cert sign <flags>: create and sign a certificate
  Pass "-" to any path flag to read from stdin or write to stdout.
  -ca-crt string
    	Optional: path to the signing CA cert (default "ca.crt")
  -ca-key string
    	Optional: path to the signing CA key (default "ca.key")
  -duration duration
    	Optional: how long the cert should be valid for. The default is 1 second before the signing cert expires. Valid time units are seconds: "s", minutes: "m", hours: "h"
  -groups string
    	Optional: comma separated list of groups
  -in-pub string
    	Optional (if out-key not set): path to read a previously generated public key
  -ip string
    	Deprecated, see -networks
  -name string
    	Required: name of the cert, usually a hostname
  -networks string
    	Required: comma separated list of ip address and network in CIDR notation to assign to this cert
  -out-crt string
    	Optional: path to write the certificate to
  -out-key string
    	Optional (if in-pub not set): path to write the private key to
  -out-qr string
    	Optional: output a qr code image (png) of the certificate
  -subnets string
    	Deprecated, see -unsafe-networks
  -unsafe-networks string
    	Optional: comma separated list of ip address and network in CIDR notation. Unsafe networks this cert can route for
  -version uint
    	Optional: version of the certificate format to use. The default is to match the version of the signing CA

注意 -networks 是 Required（老教程里的 -ip 已废弃）；-duration 不写时默认「签发 CA 到期前 1 秒」（即跟随 CA）。

7.2 实测签发

nebula-cert sign -name lighthouse -networks "10.99.0.1/24" -groups "lighthouse" -ca-crt /etc/nebula/ca.crt -ca-key /etc/nebula/ca.key -out-crt /etc/nebula/host.crt -out-key /etc/nebula/host.key
echo "exit=$?"

实测输出：

exit=0

签发成功是静默的；产物权限 0600（实测 ls -l /etc/nebula 回显 -rw------- 1 root root 326 ... host.crt 与 -rw------- 1 root root 127 ... host.key）。

7.3 重复签发会被拒绝

同一 -out-crt/-out-key 再签一次（实测）：

Error: refusing to overwrite existing cert: dup.crt

（exit=1。）覆盖保护意味着轮换证书必须写新文件名，实践上用带日期命名（如 host-2026q4.crt）+ 配置切换的方式最稳。

八、nebula-cert print：查看证书

8.1 用法

Usage of nebula-cert print <flags>: prints details about a certificate
  Pass "-" to any path flag to read from stdin or write to stdout.
  -json
    	Optional: outputs certificates in json format
  -out-qr string
    	Optional: output a qr code image (png) of the certificate
  -path string
    	Required: path to the certificate

8.2 实测：CA 证书

nebula-cert print -path /etc/nebula/ca.crt

实测输出（默认即为缩进 JSON）：

{
	"curve": "CURVE25519",
	"details": {
		"groups": null,
		"isCa": true,
		"issuer": "",
		"name": "Quzuo Nebula CA",
		"networks": null,
		"notAfter": "2036-10-17T18:20:16+08:00",
		"notBefore": "2026-10-20T18:20:16+08:00",
		"unsafeNetworks": null
	},
	"fingerprint": "d3fc0ec8573301be67e8224b622b19022ba555b63d0d6820f58dc2799b3163ce",
	"publicKey": "d25bb54e2b357db8a5b09f91e99544c1dbd1f85b3d8bfd371887a03bf5b096bc",
	"signature": "c0e1f5ae07df7d03a80dcc397d9f848812fab25689e53fb523218621e8a2601fbedccebdcb39bc7485010314a3da4b8108d0c4f7ca8c4227083d69f03d0fe90a",
	"version": 2
}

8.3 实测：节点证书

nebula-cert print -path /etc/nebula/host.crt

实测输出（与 CA 的区别：isCa: false、issuer 为 CA 指纹、networks 写明 overlay 网段、groups 带组）：

{
	"curve": "CURVE25519",
	"details": {
		"groups": [
			"lighthouse"
		],
		"isCa": false,
		"issuer": "d3fc0ec8573301be67e8224b622b19022ba555b63d0d6820f58dc2799b3163ce",
		"name": "lighthouse",
		"networks": [
			"10.99.0.1/24"
		],
		"notAfter": "2036-10-17T18:20:15+08:00",
		"notBefore": "2026-10-20T18:20:16+08:00",
		"unsafeNetworks": null
	},
	"fingerprint": "6ba4197fd96fa91cb41bd5c74881ad61c460459e6b1f64d8e81b870d4bb5c998",
	"publicKey": "b829fdaecb633023b0ead1bfd73fa53c531e1699ecf1df6578e79b1fbc6b483a",
	"signature": "0d09ef3a71101caf29f8ca376e0f925f83160c5dc74a13d95371f0b4221586a18993d5c274360704bca0dd44fbc78efd4c0ff08a233b4c464e1d1e2d4a330d0d",
	"version": 2
}

8.4 -json 紧凑输出

nebula-cert print -path /etc/nebula/ca.crt -json

实测输出（单行数组，适合脚本解析）：

[{"curve":"CURVE25519","details":{"groups":null,"isCa":true,"issuer":"","name":"Quzuo Nebula CA","networks":null,"notAfter":"2036-10-17T18:20:16+08:00","notBefore":"2026-10-20T18:20:16+08:00","unsafeNetworks":null},"fingerprint":"d3fc0ec8573301be67e8224b622b19022ba555b63d0d6820f58dc2799b3163ce","publicKey":"d25bb54e2b357db8a5b09f91e99544c1dbd1f85b3d8bfd371887a03bf5b096bc","signature":"c0e1f5ae07df7d03a80dcc397d9f848812fab25689e53fb523218621e8a2601fbedccebdcb39bc7485010314a3da4b8108d0c4f7ca8c4227083d69f03d0fe90a","version":2}]

运维中最常用的两个提取：fingerprint（吊销列表与防火墙 ca_sha 规则用）与 notAfter（到期告警）。

九、nebula-cert verify：校验证书

9.1 用法

Usage of nebula-cert verify <flags>: verifies a certificate isn't expired and was signed by a trusted authority.
  Pass "-" to any path flag to read from stdin or write to stdout.
  -ca string
    	Required: path to a file containing one or more ca certificates
  -crt string
    	Required: path to a file containing a single certificate

9.2 实测：信任链正常

nebula-cert verify -ca /etc/nebula/ca.crt -crt /etc/nebula/host.crt
echo "exit=$?"

实测输出：

exit=0

校验通过时无任何输出（静默 + 退出码 0），脚本判定以退出码为准。

9.3 实测：CA 不匹配

用另一张 CA 校验 lighthouse 证书（实测）：

Error: error while verifying certificate v2 lighthouse with issuer d3fc0ec8573301be67e8224b622b19022ba555b63d0d6820f58dc2799b3163ce: could not find ca for the certificate

（exit=1。issuer 即证书的签发 CA 指纹，与 -ca 提供的 CA 对不上就报 could not find ca。）

9.4 实测：证书过期

签一张 2 秒寿命的证书再校验（-duration 2s）：

Error: error while verifying certificate {
	"curve": "CURVE25519",
	"details": {
		...
		"name": "shortlived",
		"notAfter": "2026-10-20T18:35:40+08:00",
		...
	}
}: certificate is expired

（实测节选，错误信息中部内嵌整张证书 JSON 故略去部分字段；exit=1，尾部给出 certificate is expired。）

十、证书运维实战组合

10.1 离线签发（私钥不出设备）

节点自造密钥 → 只交公钥 → 运维机签发 → 回传证书（全部实测）：

# 节点上
nebula-cert keygen -out-key device.key -out-pub device.pub
# 把 device.pub 交给运维机后：
nebula-cert sign -name device1 -networks "10.99.0.30/24" -in-pub device.pub -ca-crt /etc/nebula/ca.crt -ca-key /etc/nebula/ca.key -out-crt device.crt
echo "exit=$?"
ls -l device.crt device.key

实测输出：

exit=0
-rw------- 1 root root 306 10月 20 18:35 device.crt
-rw------- 1 root root 127 10月 20 18:35 device.key

device.key 全程留在节点，运维机接触不到私钥；证书回传后打印复核（实测片段）：

		"name": "device1",
		"networks": [
			"10.99.0.30/24"

10.2 证书轮换

步骤（每步行为均有实测依据）：① 新文件名签发（sign 拒绝覆盖旧文件，见 7.3）；② 新证书先 print 核对 networks/groups/notAfter（见八）；③ verify 确认信任链（见九）；④ 节点配置 pki.cert/pki.key 指向新文件或替换同名文件后 HUP/重启（支持行为见 C1 篇 5.1/3.2）；⑤ 旧证书指纹加入 pki.blocklist 吊销（C1 篇 5.1）。

10.3 吊销

nebula-cert print 拿到证书指纹 → 写入全网节点的 pki.blocklist（配置段与生效方式见 C1 篇 5.1）→ HUP 生效。CA 证书泄露属灾难场景：换新 CA 重签全网是唯一稳妥解。

10.4 QR 码输出

ca 与 sign 都支持 -out-qr（实测）：

nebula-cert sign -name qrnode -networks "10.99.0.40/24" -ca-crt /etc/nebula/ca.crt -ca-key /etc/nebula/ca.key -out-crt qr.crt -out-key qr.key -out-qr qr.png
echo "exit=$?"
file qr.png

实测输出：

exit=0
qr.png: PNG image data, 385 x 385, 1-bit colormap, non-interlaced

产出的 PNG 是证书内容的二维码，配合移动端 App 扫码导入（print -out-qr 可对已有证书补出二维码）。

十一、注意事项

  1. CA 私钥即最高权限：拿到 ca.key 就能签出任意身份的证书，务必离线/加密保管（-encrypt + Argon2 可给私钥加口令）。
  2. 有效期上限传递：子证书不能比 CA 活得久（sign 的 duration 默认「CA 到期前 1 秒」，见帮助回显），CA 将到期时要提前重签并全网滚动。
  3. v2 证书字段名：v1.11.2 默认 -version 2，术语是 networks/unsafeNetworks；老教程的 -ip/-subnets 参数还在但已废弃，新脚本一律用 -networks/-unsafe-networks。
  4. 默认曲线 25519：新旧节点混跑 P256 的旧网络才需要 -curve P256，新网络保持默认即可。
  5. 文件权限：签发产物自动 0600（实测），手工搬运证书时别用会放宽权限的中转方式。
  6. 覆盖保护：sign 到已存在路径必被拒绝（见 7.3），不要指望 -f 之类参数——v1.11.2 的帮助里没有覆盖开关。
  7. 脚本化判定：verify 成功无输出、失败走 stderr，一律以退出码判定；print -json 的单行输出适合 jq 抽取字段。

十二、常见问题

  1. nebula-cert 直接回车报什么？ Error: No mode was provided 并列出五个模式（见二、概览实测），不是报错故障。
  2. sign 报 refusing to overwrite existing cert？ 目标文件已存在，见 7.3；换文件名或先删旧文件。
  3. verify 报 could not find ca for the certificate？ 证书的 issuer（签发 CA 指纹）与所给 CA 不符，见 9.3——先确认拿对了 CA 文件。
  4. verify 报 certificate is expired？ 证书超过 notAfter，见 9.4；节点侧表现为握手被拒，重新签发轮换即可。
  5. 证书没问题但两节点永远握手超时？ 证书链与有效期排查完还没好，去查 cipher 双端钉死是否冲突与 UDP 4242 放行（现象与修法见 C1 篇 5.5 与 B1 篇 8.4）。

十三、参考链接