NSD 4.15.3 常用 CLI 命令详解
NSD 4.15.3 常用 CLI 命令详解：nsd/nsd-control/nsd-checkconf/nsd-checkzone/nsd-control-setup 五件套逐命令实测（-h 全量选项、status/zonestats/stats 统计、reconfig/reload/addzone/delzone 区管理、TSIG 与 Cookie 密钥闭环、stop 与 systemd Restart 陷阱、IXFR 生成）与运维组合场景。
NSD 4.15.3 常用 CLI 命令详解
目标：逐条实测讲清 NSD 4.15.3 的五个命令行工具——nsd（守护进程）、nsd-control（运行时管理核心）、nsd-checkconf（配置校验查询）、nsd-checkzone（区文件校验与 IXFR 生成）、nsd-control-setup（控制证书初始化）。每条命令给出真实回显与退出码，附运维组合场景与踩坑实录。全文在 Ubuntu 22.04.4 LTS 实测采集。
一、环境信息
| 项目 | 实测环境 |
|---|---|
| 操作系统 | Ubuntu 22.04.4 LTS（jammy），x86_64 |
| NSD 版本 | 4.15.3（源码编译安装，二进制在 /usr/local/sbin/） |
| 配置文件 | /etc/nsd/nsd.conf（服务运行中，控制证书已初始化） |
| 演示区 | example.com（主区） |
| 实测时间 | 2026-10-20（回显时间戳均为此日实测） |
安装来源与 systemd 托管见 《Ubuntu 22.04 安装 NSD 指南》；配置参数语义见 《NSD 4.15.3 配置参数详解》。本文只讲命令本身。
二、命令总览
NSD 的命令行工具共 5 个，职责划分清晰：
| 命令 | 实测路径 | 职责 |
|---|---|---|
| nsd | /usr/local/sbin/nsd | 守护进程本体，一般由 systemd 拉起 |
| nsd-control | /usr/local/sbin/nsd-control | 运行时管理入口（status/区管理/密钥/统计），经 8952/TLS 连接服务 |
| nsd-control-setup | /usr/local/sbin/nsd-control-setup | 一次性生成控制通道 4 个证书密钥文件 |
| nsd-checkconf | /usr/local/sbin/nsd-checkconf | 配置文件校验与单值查询 |
| nsd-checkzone | /usr/local/sbin/nsd-checkzone | 区文件校验、规范打印、IXFR 差异生成 |
五个命令都带版本号输出（nsd -v 或各自 -h 尾行均显示 Version 4.15.3），排障时先核对版本。
三、nsd 主命令
nsd 是守护进程本体。生产上永远通过 systemd 管理（systemctl start/stop/restart nsd），直接裸跑会脱离 systemd 的进程跟踪与自动重启保护。
3.1 版本与编译信息
nsd -v
实测回显（完整）：
NSD version 4.15.3
Written by NLnet Labs.
Configure line: --prefix=/usr/local --sysconfdir=/etc --with-configdir=/etc/nsd --with-nsd_conf_file=/etc/nsd/nsd.conf --localstatedir=/var --runstatedir=/run --with-pidfile=/run/nsd/nsd.pid --with-dbfile=/var/lib/nsd/nsd.db --with-zonesdir=/etc/nsd --with-zonelistfile=/var/lib/nsd/zone.list --with-xfrdfile=/var/lib/nsd/xfrd.state --with-user=nsd --enable-systemd --disable-dnstap
Event loop: libevent 2.1.12-stable (uses epoll)
Linked with OpenSSL 3.0.2 15 Mar 2022
Copyright (C) 2001-2024 NLnet Labs. This is free software.
There is NO warranty; not even for MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.
Configure line 一行是排障利器：编译路径、启用的特性（--enable-systemd/--disable-dnstap）一目了然。
3.2 命令行选项
nsd -h
实测输出整理：
| 选项 | 含义 |
|---|---|
| -4 / -6 | 只监听 IPv4 / IPv6 |
| -a ip-address[@port] | 指定监听地址（可多次） |
| -c configfile | 指定配置文件（默认 /etc/nsd/nsd.conf） |
| -d | 不 fork，前台运行（systemd Type=notify 必配） |
| -i identity | 指定 id.server CHAOS 应答的 identity |
| -I nsid | 指定 NSID（十六进制） |
| -l filename | 指定日志文件 |
| -N server-count | server 子进程数 |
| -n tcp-count | 每 server 最大 TCP 连接数 |
| -P pidfile | 指定 pid 文件（-P "" 禁用，交给 systemd） |
| -p port | 指定监听端口 |
| -s seconds | 周期性输出统计 |
| -t chrootdir | chroot 目录 |
| -u user | 运行用户 |
| -V level | 日志级别 |
| -v | 打印版本信息 |
命令行选项与配置文件同名参数等价，命令行优先；运维建议全部收敛到配置文件，命令行只保留 -d、-P ""（systemd 单元内），其余行为统一走 nsd.conf 便于审计。
四、nsd-control 运行时管理命令族
nsd-control 是日常运维的核心。它经 8952/TCP（TLS 双向证书）与 xfrd 主控进程通信，服务未运行或证书不匹配时连接失败。
4.1 基础用法
nsd-control -h
实测输出（完整命令清单）：
Usage: nsd-control [options] command
Remote control utility for nsd server.
Version 4.15.3. Report bugs to <https://github.com/NLnetLabs/nsd/issues or nsd-bugs@nlnetlabs.nl>.
Options:
-c file config file, default is /etc/nsd/nsd.conf
-s ip[@port] server address, if omitted config is used.
-h show this usage help.
Commands:
start start server; runs nsd(8)
stop stops the server
reload [<zone>] reload modified zonefiles from disk
reconfig reload the config file
repattern the same as reconfig
log_reopen reopen logfile (for log rotate)
status display status of server
stats print statistics
stats_noreset peek at statistics
addzone <name> <pattern> add a new zone
delzone <name> remove a zone
changezone <name> <pattern> change zone to use pattern
addzones add zone list on stdin {name space pattern newline}
delzones remove zone list on stdin {name newline}
write [<zone>] write changed zonefiles to disk
notify [<zone>] send NOTIFY messages to secondary servers
transfer [<zone>] try to update secondary zones to newer serial
force_transfer [<zone>] update secondary zones with AXFR, no serial check
zonestatus [<zone>] print state, serial, activity
serverpid get pid of server process
verbosity <number> change logging detail
print_tsig [<key_name>] print tsig with <name> the secret and algo
update_tsig <name> <secret> change existing tsig with <name> to a new <secret>
add_tsig <name> <secret> [algo] add new key with the given parameters
assoc_tsig <zone> <key_name> associate <zone> with given tsig <key_name> name
del_tsig <key_name> delete tsig <key_name> from configuration
add_cookie_secret <secret> add (or replace) a new cookie secret <secret>
drop_cookie_secret drop a staging cookie secret
activate_cookie_secret make a staging cookie secret active
print_cookie_secrets show all cookie secrets with their status
-c 可指定其他配置（多实例场景），-s ip[@port] 可直连指定控制地址（默认从配置的 control-interface/control-port 读取）。
4.2 状态查看：status / serverpid / zonestatus
nsd-control status
nsd-control serverpid
nsd-control zonestatus example.com
实测回显：
version: 4.15.3
verbosity: 1
ratelimit: 0
1412634
zone: example.com
state: primary
status三行：版本、当前日志级别、RRL 限流值（0=关闭）。serverpid：返回 server 子进程 pid（不是 systemd Main PID；主进程 pid 看 systemctl status）。zonestatus：区角色（primary）与传送活动。术语注意：4.15.x 输出state: primary，4.3.9 输出state: master（同义，版本口径差异，实测）。
4.3 统计：stats 与 stats_noreset
nsd-control stats_noreset
实测回显（节选）：
server0.queries=1
num.queries=1
time.boot=101.702640
time.elapsed=101.702640
size.db.mem=4176
size.xfrd.mem=1162776
两者的区别是是否重置计数器：stats 输出后把累计值清零（适合周期采集归档），stats_noreset 只读不清（适合 peek）。实测重启服务后 stats 显示 server0.queries=0、time.boot 从 1.1 秒起算——计数器随进程生命周期。完整输出含全记录类型计数（num.type.A/NS/SOA…）、应答码（num.rcode.NOERROR/REFUSED…）、传输协议（num.udp/tcp/tls）与区角色数量（zone.master/zone.slave，4.15.3 里字段名仍沿用 master/slave，注意与 zonestatus 的 primary 术语不一致）。
4.4 配置与区数据生效：reconfig / reload / repattern
nsd-control reconfig
nsd-control reload example.com
nsd-control repattern
实测回显：
reconfig start, read /etc/nsd/nsd.conf
reconfig completed: changes applied
ok
reconfig start, read /etc/nsd/nsd.conf
reconfig completed: no changes detected
ok
reconfig/repattern（前者别名）：重读配置文件，只对 zone/pattern/remote-control 段改动生效；server 段标量改动实测报no changes detected且不生效，需systemctl restart nsd（完整反转验证见配置篇 3.4 节）。reload [zone]：从磁盘重读 zone 文件并重建 nsd.db，进程不重启；改完 zone 文件的第一动作。
4.5 动态区管理：addzone / delzone / write
nsd-control addzone test2.com template
nsd-control zonestatus test2.com
nsd-control delzone test2.com
实测回显：
ok
zone: test2.com
pattern: template
state: primary
test2.com. 3600 IN SOA ns1.test2.com. admin.test2.com. 2026102001 7200 3600 1209600 3600
ok
addzone <区名> <pattern 名>：按 pattern 模板动态加区（pattern 的 zonefile 需用%s通配区名）；记录持久化到 zone.list，重启不丢。delzone <区名>：动态删区（配置文件里静态声明的 zone 不能这样删）。write [zone]：把从区收到的数据回写 zone 文件，实测返回 ok。- 权限坑实录：/var/lib/nsd 属主非 nsd 时 addzone 报
error could not add zonelist entry（journal 细节could not create zone list /var/lib/nsd/zone.list: Permission denied），chown -R nsd:nsd /var/lib/nsd解决（安装篇 5.4 节）。 - 批量形态：
addzones/delzones从标准输入读列表（name pattern按行），适合托管商批量导入。
4.6 主从同步触发：notify / transfer / force_transfer
nsd-control notify example.com
实测回显：
ok
notify [zone]：以 primary 身份向所有 secondary 立即发 NOTIFY，不用等 SOA 定时器。transfer [zone]：以 secondary 身份按序检查上游 SOA 并增量拉取；force_transfer跳过序列号比较强制 AXFR（上游数据损坏回滚时用）。两者仅在配置了 request-xfr 的从区上有意义，无上游时实测仅返回 ok。
4.7 日志与运行时：verbosity / log_reopen / stop / start
nsd-control verbosity 3
nsd-control status | grep verbosity
nsd-control verbosity 1
nsd-control log_reopen
实测回显：
ok
verbosity: 3
ok
ok
verbosity N：运行时调日志级别（0 静默–5 debug），排障临时调 3，完事调回 1；重启后回到配置文件初始值。log_reopen：日志轮转后（logrotate 切文件）通知 NSD 重开文件句柄。stop/start：注意 stop 有 systemd 陷阱，见 4.8。
4.8 ⚠️ stop 命令与 systemd Restart=always 的冲突（实测陷阱）
自建 systemd 单元若含 Restart=always（安装篇 5.6 节模板），nsd-control stop 后进程会被 systemd 立即拉起。实测对照：
nsd-control stop
sleep 2
systemctl is-active nsd
实测回显：
ok
active
stop 返回 ok，2 秒后服务又回到 active（serverpid 已变成新 pid），NSD 并没有停。要真正停服务必须走 systemctl：
systemctl stop nsd
systemctl is-active nsd
实测回显：
inactive
结论：nsd-control stop 只在 systemd 不管进程（手工 nsd -d 调试）时使用；systemd 托管下停服务一律 systemctl stop nsd。
4.9 TSIG 密钥管理：add_tsig / update_tsig / print_tsig / del_tsig
运行时增删改 TSIG 密钥（免改配置文件重启）。实测完整闭环：
nsd-control add_tsig d3key q1w2e3r4q1w2e3r4q1w2e3r4q1w2e3r4
nsd-control update_tsig d3key bmV3c2VjcmV0MTIzNA==
nsd-control print_tsig d3key
nsd-control del_tsig d3key
实测回显：
ok
ok
key: name: "d3key" secret: "bmV3c2VjcmV0MTIzNA==" algorithm: hmac-sha256
ok
add_tsig <名字> <secret> [algo]：默认算法 hmac-sha256。- secret 必须是 base64 格式，实测裸字符串报错：
error: the secret: n3wsecret-987654321 is not in b64 format。生成方式示例：echo -n "newsecret1234" | base64得bmV3c2VjcmV0MTIzNA==。 assoc_tsig <区名> <key 名>把密钥关联到区（配置区传送认证），update_tsig做密钥轮换，del_tsig删除。密钥存入运行配置，与 zone.list 一起持久化。
4.10 Cookie 密钥管理：add_cookie_secret / activate_cookie_secret / drop_cookie_secret / print_cookie_secrets
DNS Cookie 密钥支持平滑轮换（先暂存新密钥、等客户端缓存过期后激活、再删旧密钥）。secret 必须是 128 位十六进制串（32 个 hex 字符），实测短字符串报错：
$ nsd-control add_cookie_secret s3cr3et-cookie-abc123
invalid cookie secret: invalid argument length
please provide a 128bit hex encoded secret
完整轮换流程实测（首次添加的密钥直接成为 active；再加第二个进入 staging）：
nsd-control add_cookie_secret 11223344556677889900aabbccddeeff
nsd-control add_cookie_secret aaaabbbbccccddddeeeeffff00001111
nsd-control print_cookie_secrets
实测回显：
ok
ok
source : "/var/db/nsd/cookiesecrets.txt"
active : 11223344556677889900aabbccddeeff
staging: aaaabbbbccccddddeeeeffff00001111
nsd-control activate_cookie_secret
nsd-control print_cookie_secrets
nsd-control drop_cookie_secret
nsd-control print_cookie_secrets
实测回显：
ok
source : "/var/db/nsd/cookiesecrets.txt"
active : aaaabbbbccccddddeeeeffff00001111
staging: 11223344556677889900aabbccddeeff
ok
source : "/var/db/nsd/cookiesecrets.txt"
active : aaaabbbbccccddddeeeeffff00001111
- 密钥持久化在 /var/db/nsd/cookiesecrets.txt。权限坑实录：源码安装时 /var/db/nsd 由 make install 以 root 创建，属主为 root 时写入报
unable to open cookie secret file /var/db/nsd/cookiesecrets.txt: Permission denied，需chown -R nsd:nsd /var/db/nsd。 - 未进入轮换时
activate报error: no staging cookie secret to activate；drop只能删 staging 密钥，删 active 报error: can not drop the currently active cookie secret（两报错均实测）。
五、nsd-checkconf 配置校验与查询
配置文件校验器兼查询器，4.15.3 必须显式传配置路径（无参数直接打印 usage 并以退出码 1 结束，实测）。完整用法与报错格式已在 《NSD 4.15.3 配置参数详解》第三章逐项实测，此处给速查表：
| 选项 | 作用 | 实测示例输出 |
|---|---|---|
| （无选项） | 校验配置 | 通过时无输出、exit=0 |
| -v | 打印全量生效参数（含默认值） | 按 server/remote-control/verify/zone 分段输出 |
| -o <参数名> | 打印单参数值 | -o zonesdir /etc/nsd/nsd.conf → /etc/nsd |
| -z <区名> | 配合 -o 查 zone 级参数 | -o zonefile -z example.com /etc/nsd/nsd.conf → example.com.zone |
| -p <pattern 名> | 配合 -o 查 pattern 内参数 | -p secondary -o provide-xfr … → 192.168.146.0/24 transfer-key |
| -s <key 名> | 打印 TSIG secret | 输出 base64 blob |
| -a <key 名> | 打印 TSIG 算法 | hmac-sha256 |
| -t <tls-auth 名> | 打印 tls-auth 认证域名 | — |
| -f | 与 -o 组合，打印 chroot 后的最终路径 | — |
报错统一格式 文件:行号: error: 原因 + read <文件> failed: N errors in configuration file，退出码 2；六类典型错误实录（expected a number / syntax error / key could not be found / expected yes or no 等）见配置篇 3.5 节。
六、nsd-checkzone 区文件校验与 IXFR 生成
6.1 基本校验
nsd-checkzone example.com /etc/nsd/example.com.zone
实测回显：
zone example.com is ok
第一个参数是区名，第二个是 zone 文件路径；区名与文件内 $ORIGIN 不一致时会报错。上线前先过这道闸。
6.2 -p：规范格式打印
nsd-checkzone -p example.com /etc/nsd/example.com.zone
实测回显（节选）：
$ORIGIN com.
example 3600 IN SOA ns1.example.com. admin.example.com. (
2026102001 7200 3600 1209600 3600 )
3600 IN NS ns1.example.com.
3600 IN NS ns2.example.com.
3600 IN A 192.168.146.10
3600 IN MX 10 mail.example.com.
3600 IN TXT "v=spf1 a mx ~all"
$ORIGIN example.com.
api 3600 IN CNAME www.example.com.
mail 3600 IN A 192.168.146.12
ns1 3600 IN A 192.168.146.128
-p 按 NSD 内部规范重排输出（自动拆分 $ORIGIN、补全省略的 TTL 与区名），用于审查实际装载的区内容。
6.3 -i：从新旧 zone 文件生成 IXFR 差异
改序列号前后的两个 zone 文件可以离线生成 IXFR 增量文件（NSD 独有实用特性）：
nsd-checkzone -i zold.zone example.com znew.zone
实测回显：
zone example.com created IXFR znew.zone.ixfr
生成的 znew.zone.ixfr（597 字节）头部实测：
; IXFR data file
; zone example.com
; from_serial 2026102001
; to_serial 2026102002
; data_size 444
; IXFR created by NSD 4.15.3 for example.com. 2026102001 to 2026102002 of 444 bytes at time Tue Oct 20 17:38:32 2026
example.com. 3600 IN SOA ns1.example.com. admin.example.com. 2026102002 7200 3600 1209600 3600
example.com. 3600 IN SOA ns1.example.com. admin.example.com. 2026102001 7200 3600 1209600 3600
配套参数：-n <数量> 最多保留的 IXFR 版本数（默认 5）、-s <字节> 单个 IXFR 大小上限（默认 1048576）。
七、nsd-control-setup 控制证书初始化
一次性生成 nsd-control 控制通道的 TLS 双向证书（幂等，重复执行先清理再重建）：
nsd-control-setup
实测回显：
setup in directory /etc/nsd
removing artifacts
Setup success. Certificates created. Enable in nsd.conf file to use
产出 4 个文件：/etc/nsd/nsd_server.key、/etc/nsd/nsd_server.pem（服务端）与 /etc/nsd/nsd_control.key、/etc/nsd/nsd_control.pem（客户端），与配置 remote-control 段的四个路径一一对应。证书有效期 10 年量级，到期前轮换即可；重建证书后重启 nsd 服务保证服务端加载新证书。
八、命令组合实践
五个真实运维场景的命令组合（全部为本文实测过的命令）：
场景一：配置变更上线
nsd-checkconf /etc/nsd/nsd.conf && nsd-control reconfig
nsd-control status
dig @127.0.0.1 www.example.com A +noall +answer
先校验再生效，最后查询验证。server 段改动则把 reconfig 换成 systemctl restart nsd。
场景二：批量动态加区
printf 'test2.com template\ntest3.com template\n' | nsd-control addzones
nsd-control zonestatus test2.com
printf 'test2.com\ntest3.com\n' | nsd-control delzones
场景三：故障排查（日志调级）
nsd-control verbosity 3
journalctl -u nsd -f
nsd-control log_reopen
nsd-control verbosity 1
场景四：统计采集
nsd-control stats_noreset # 观察不影响计数
nsd-control stats # 周期采集后自动清零
场景五：主从切换后推送
nsd-control write
nsd-control notify
nsd-control zonestatus
从区升主后先回写 zone 文件，再全量 NOTIFY 通知下游。
九、常见问题（FAQ）
Q1：nsd-control stop 之后服务怎么又活了？
systemd 单元含 Restart=always 时，nsd-control stop 停掉的进程被 systemd 立即重启（实测 2 秒后 is-active 回到 active 且 pid 更新，见 4.8 节）。systemd 托管下停服务用 systemctl stop nsd。
Q2：nsd-control 提示连接失败？
服务未运行（先 systemctl status nsd）或控制证书不匹配（重新 nsd-control-setup 并重启服务）。多实例时用 nsd-control -c <配置> -s <地址>[@端口] 直连目标实例。
Q3：zonestatus 显示 state: master，手册说应该是 primary？
版本术语差异：4.15.x 输出 state: primary，4.3.9 输出 state: master（实测对照），语义相同。
Q4：add_tsig 的 secret 直接填字符串报错？
TSIG secret 要求 base64 格式（实测报 is not in b64 format）；echo -n "原文" | base64 转换后填入。Cookie 密钥则要求 128 位十六进制串（32 个 hex 字符），两者格式不要混。
Q5：add_cookie_secret 报 unable to open cookie secret file … Permission denied？
cookie 密钥文件目录属主问题：chown -R nsd:nsd /var/db/nsd 后重试（源码安装 make install 以 root 创建该目录，实测踩坑）。同类问题见安装篇 5.4 节的 /var/lib/nsd。
Q6：stats 输出里 zone.master=1 是什么？
统计输出的区角色计数字段沿用 master/slave 字段名（4.15.3 实测），与 zonestatus 的 primary/secondary 新术语并存，语义等价。
十、参考链接
10.1 官方手册（随源码/软件包）
| 手册页 | 内容 |
|---|---|
| man nsd | 守护进程与全部命令行选项 |
| man nsd-control | 控制命令全集 |
| man nsd-checkconf | 校验器选项 |
| man nsd-checkzone | 区校验与 IXFR 生成 |
| man nsd.conf | 配置文件参数全集 |
| NSD 产品页 | https://nlnetlabs.nl/projects/nsd/about/ |
| GitHub 仓库 | https://github.com/NLnetLabs/nsd |
10.2 本系列篇目
- 《NSD 4.15.3 介绍与选型指南》：定位、架构、版本节奏与同类量化对比。
- 《Ubuntu 22.04 安装 NSD 指南》：apt 与源码双方案安装、systemd 托管与排障实录。
- 《NSD 4.15.3 配置参数详解》：全量参数总览、逐项详解与生产配置模板。