Yadifa 3.0.10 常用 CLI 命令详解

Yadifa 3.0.10 常用 CLI 命令详解：yadifad 服务端选项、yadifa ctrl 管理命令全集（15 条逐一实测）、zone 管理 reload/freeze/notify 闭环、跨服务器远程管理、dig 调试组合拳（TSIG AXFR/DNSSEC/元查询）与 yakeyrolld，附排障实录。

YadifaDNS服务器网络2026/10/26

Yadifa 3.0.10 常用 CLI 命令详解

目标：覆盖 Yadifa 3.0.10 日常运维的完整命令面——服务端 yadifad 的启动选项、管理客户端 yadifa ctrl 全部 15 条子命令（含真实回显）、区域管理的标准动作闭环、跨服务器远程管理、dig 调试组合拳与密钥滚动器 yakeyrolld。全部命令在 Ubuntu 22.04 双机环境实测（主 10.89.60.2 / 从 10.89.60.3，区域 example.test），回显逐行照抄。

一、环境信息

  • 软件版本：yadifad / yadifa / yakeyrolld 均为 3.0.10-11788 (2026-05-13)（源码编译安装于 /opt/yadifa，安装过程见《Ubuntu 22.04 安装 Yadifa 3.0.10 指南》）
  • 操作系统：Ubuntu 22.04 LTS；dig 版本 9.18.39（dnsutils）
  • 实测拓扑：双机主从——主服务器 ns1（10.89.60.2，primary + DNSSEC 策略签名）、从服务器 ns2（10.89.60.3，secondary，AXFR/IXFR 同步）；区域 example.test
  • 管理面：<control> enabled true，TSIG 密钥 admin-key（hmac-sha256）用于控制通道、primary-secondary（hmac-sha256）用于区域传输；客户端配置 /opt/yadifa/etc/yadifa.conf 指向 127.0.0.1
  • 配置细节与参数语义见《Yadifa 3.0.10 配置参数详解》；本文专注命令与回显

二、CLI 工具全景

Yadifa 的命令面由四个可执行程序组成（前缀按安装位置，本文为 /opt/yadifa）：

工具路径职责何时用
yadifadsbin/yadifad权威 DNS 服务守护进程安装、启动、版本确认、配置策略预检
yadifabin/yadifa管理客户端（ctrl 命令族）reload/notify/freeze/shutdown 等运维操作
yakeyrolldsbin/yakeyrolldDNSSEC 密钥滚动计划器按策略生成/推进密钥生命周期的独立守护进程
dig系统（dnsutils 包）DNS 查询调试全部查询面与区域传输验证

分工记忆法：yadifad 管"跑"，yadifa 管"改"，yakeyrolld 管"滚"，dig 管"查"。

三、yadifad 服务端命令行选项

3.1 选项全集

yadifad -h 实测回显（逐行照抄）：

/opt/yadifa/sbin/yadifad [-c configurationfile] [...]


    -c, --config                        :  sets the configuration file to use
                                           (default: /opt/yadifa/etc/yadifad.conf)
    -d, --daemon                        :  daemonize the server (equivalent to "daemon" in the configuration file)
        --nodaemon                      :  doesn't daemonize the server (equivalent to "nodaemon" in the configuration file)
    -L, --log                           :  sets the logging in the standard output
    -u, --uid <uid>                     :  sets the user id of the server process (equivalent to "user" in the configuration file)
    -g, --gid <gid>                     :  sets the group id of the server process (equivalent to "group" in the configuration file)
    -P, --port <port>                   :  sets the network port to use (equivalent to "port" in the configuration file)
        --check-policies                :  check the policy keys schedule and exit
    -h, --help                          :  gives this help
    -V, --version                       :  prints the version

逐项速记：-c 指定配置（多实例时必用）；-d/--nodaemon 控制是否后台化（systemd 单元用 --nodaemon）；-L 把日志打到标准输出（前台排障神器）；-u/-g 覆盖降权身份；-P 覆盖端口；--check-policies 是 3.x 新增的 DNSSEC 策略预检。

3.2 版本与策略预检实测

/opt/yadifa/sbin/yadifad -V

实测回显：

yadifad 3.0.10-11788 (2026-05-13)

--check-policies 用于不上线就检查 <key-roll> 时间表未来十年的排程（实测节选，exit=0）：

key-roll: never-roll: testing policy sets of dates from 2026-10-26 05:29:00 to 2036-10-25 17:29:00
key-roll: never-roll: creation at 2026-01-01 00:00:00U, publication at 2026-01-01 01:00:00U, activation at 2026-01-01 02:00:00U, deactivation at 2027-01-01 03:00:00U, removal at 2027-01-01 04:00:00U,   12.2 months
key-roll: never-roll: creation at 2027-01-01 00:00:00U, publication at 2027-01-01 01:00:00U, ...

每次 KSK/ZSK 轮换变更策略后，先跑 --check-policies 核对密钥交接期（避免签名真空）再重启，是 3.x 用户的必备习惯。

四、yadifa 管理客户端与 ctrl 命令全集

4.1 客户端配置（yadifa.conf）

管理客户端读取独立的 yadifad.conf 同目录文件 yadifa.conf（实测配置）：

<yadifa-ctrl>
   server 127.0.0.1
   tsig-key-name "admin-key"
</yadifa-ctrl>

include "keys.conf"

<yadifa-ctrl> 指定默认目标服务器与 TSIG 密钥名（密钥定义来自 include 的 keys.conf）。省得每条命令都敲 -s/-y。

4.2 通用选项

yadifa -h 实测回显（节选，控制相关部分）：

    ctrl subcommand:  directly followed by the command
      commands:  cfgreload | freeze [<zone>] | freezeall | loglevel <level>[0;15] | logreopen | notify [<zone>] | querylog [enable|disable] | reload <zone> | shutdown | sync [<zone>] [clean] | thaw | thawall | unfreeze | unfreezeall | zonecfgreload [<zone>]
      alternative: -t <command> : sets the command
                   (SHUTDOWN,RELOAD,LOGREOPEN,QUERYLOG,LOGLEVEL,FREEZE,UNFREEZE,FREEZEALL,UNFREEZEALL,SYNC,ZONENOTIFY,CFGRELOAD,CFGLOAD,ZONECFGRELOAD,ZONECFGRELOADALL)
    options: -c, --config <config>  :  sets the yadifa configuration file
             -s <host>, @<host>     :  sets the host to send the command to
             -p, --port <port>      :  sets the port the host is listening to
             -K <key-name>          :  sets the tsig key to use
             -y [hmac:]name:key     :  sets the tsig key material to use
             -h, --help             :  gives this help
             -V, --version          :  prints the version
    alternative: -q, --qname <zone> :  sets the zone parameter of a command

两条实测得出的关键用法（不看清手册最容易栽在这里）：

  • ⚠️ 命令参数（zone 名、querylog 的 enable/disable、loglevel 的级别）必须用 -q 传递，直接缀在命令后面会解析失败。实测对比：
yadifa ctrl reload example.test      # 错误形态

实测回显：

command line: CONFIG_PARSE_UNKNOWN_KEYWORD at example.test

yadifa ctrl -q example.test reload   # 正确形态

实测回显（无输出，退出码 0）。

  • ⚠️ -y 传的密钥不要与客户端配置里已 include 的同名密钥重复，否则先报 TSIG_DUPLICATE_REGISTRATION 再以 NOTAUTH 失败（排障实录见第九章 E3）。

4.3 ctrl 子命令速查表（15 条）

子命令参数作用影响面
cfgreload无重读 yadifad.conf 主配置全局
zonecfgreload-q <zone>重读某区域的配置段（类型/ACL/策略变更）单区域
reload-q <zone>重载区域文件内容（serial +1 后的数据变更用这个）单区域
notify-q <zone>立即向所有从服务器发 NOTIFY单区域
sync-q <zone> [clean]把内存中的区域刷写到磁盘 journal/文件单区域
freeze / unfreeze-q <zone>冻结/解冻单区域（暂停其更新与传输）单区域
freezeall / unfreezeall / thaw / thawall无全区域冻结/解冻（freeze/unfreeze 的全量别名）全局
querylog-q enable|disable动态开关查询日志（等价于热改 queries-log-type）全局
loglevel-q <level>[0;15]动态调整运行日志级别全局
logreopen无重开日志文件（配合 logrotate 切割）全局
shutdown无停止 yadifad 服务全局

五、zone 管理实战（修改-验证闭环）

5.1 改记录 → reload → dig 验证

标准动作链（真实服务器上的完整操作）：

# 1. 修改区域文件：serial 递增 + 追加记录
sed -i "s/2026102602/2026102603/; /api     IN  CNAME www.example.test./a\\docs    IN  A   10.89.60.30" \
    /opt/yadifa/var/zones/primaries/example.test.zone

# 2. 通过控制通道热重载（不重启服务）
yadifa ctrl -q example.test reload

# 3. dig 验证新记录
dig @127.0.0.1 docs.example.test A +noall +answer

实测回显：

docs.example.test.	86400	IN	A	10.89.60.30

⚠️ 顺序提醒：手工编辑区域文件必须先 serial +1 再 reload——Yadifa 按 SOA serial 判断新旧（与 BIND 一致）；漏改 serial 时 reload 不报错但新记录不生效。

5.2 notify 触发从服务器同步

yadifa ctrl -q example.test notify

实测回显（无输出，退出码 0）。从服务器侧随即在 server.log 出现实测记录：

secondary: example.test.: got AXFR from primary at 10.89.60.2#53, serial is 2026102603

从服务器 dig 验证（实测）：

dig @10.89.60.3 news.example.test A +noall +answer

news.example.test.	86400	IN	A	10.89.60.40

5.3 freeze/unfreeze 的真实语义

⚠️ 实测澄清一个普遍误解：freeze 冻结的是"写入"不是"查询"。冻结期间 dig 依旧正常应答（实测回显）：

yadifa ctrl -q example.test freeze
dig @127.0.0.1 www.example.test A +noall +answer
yadifa ctrl -q example.test thaw

实测回显（freeze 与 thaw 之间执行 dig）：

www.example.test.	86400	IN	A	10.89.60.10

freeze 的实际用途：动态更新/区域传输维护窗口——比如从服务器要整体重建 journal 时先 freeze 再操作。freezeall/thawall 是全区域版本，实测均返回退出码 0。

5.4 日志动态开关实测

yadifa ctrl -q disable querylog   # 关闭查询流水
yadifa ctrl -q enable querylog    # 重新打开
yadifa ctrl logreopen             # 配合 logrotate 切割后重开文件句柄

三条实测均无输出、退出码 0。querylog 与 logreopen 是日志运维最高频的两条——logrotate 配置里 postrotate 段放 yadifa ctrl logreopen 即可完成无缝切割。

六、跨服务器远程管理

控制命令的 -s <host>（或 @<host>）可以直接把命令打到另一台服务器——只要目标机的 <control> 已启用且持有同一把管理密钥（从服务器 keys.conf 同样定义了 admin-key 并配置 allow-control controller）。实测在主服务器上直接管理从服务器：

yadifa ctrl -s 10.89.60.3 logreopen

实测回显（无输出，退出码 0）。

由此可组合出轻量级批量管理（在管理机上循环多台服务器执行同一条 ctrl 命令），无需在每个节点登录操作。从服务器的客户端配置同样可用 yadifa ctrl -s 10.89.60.2 ... 反向管理主服务器——控制通道是点对点的，与主从角色无关。

七、dig 调试组合拳

7.1 服务器元信息三件套

dig @127.0.0.1 version.yadifa CH TXT +noall +answer
dig @127.0.0.1 hostname.bind CH TXT +noall +answer
dig @127.0.0.1 id.server CH TXT +noall +answer

实测回显（应答值来自 yadifad.conf 的 version/hostname/serverid）：

version.yadifa.		0	CH	TXT	"3.0.10"
hostname.bind.		0	CH	TXT	"ns1.example.test"
id.server.		0	CH	TXT	"yadifad-ns1"

多节点排障时先跑这三条确认"连到的是哪台、什么版本"。⚠️ 安全提示：生产对外服务建议把 version 留空，不向公网暴露具体版本号。

7.2 AXFR 与 TSIG 认证（一正一反两次实测）

未携带 TSIG 的全量传输被 ACL 拒绝（allow-transfer key primary-secondary 生效实证）：

dig @10.89.60.2 example.test AXFR +noall +answer 2>&1 | head -3

实测回显：

; Transfer failed.

携带正确 TSIG 密钥（-y <算法>:<名称>:<base64密钥>）成功拉取全区域（实测完整应答 11 条）：

dig -y hmac-sha256:primary-secondary:LAq/NfcgYNcqfz6gbneLfxsmEr6FVxorOUrb98k2EZU= \
    @10.89.60.2 example.test AXFR +noall +answer

实测回显：

example.test.		86400	IN	SOA	ns1.example.test. admin.example.test. 2026102602 10800 3600 604800 86400
example.test.		86400	IN	NS	ns1.example.test.
example.test.		86400	IN	NS	ns2.example.test.
example.test.		86400	IN	A	10.89.60.20
ns1.example.test.	86400	IN	A	10.89.60.2
ns2.example.test.	86400	IN	A	10.89.60.3
www.example.test.	86400	IN	A	10.89.60.10
api.example.test.	86400	IN	CNAME	www.example.test.
docs.example.test.	86400	IN	A	10.89.60.30
example.test.		86400	IN	MX	10 mail.example.test.
mail.example.test.	86400	IN	A	10.89.60.25
example.test.		86400	IN	SOA	ns1.example.test. admin.example.test. 2026102602 10800 3600 604800 86400

SOA 头尾各一次是 AXFR 协议规定。⚠️ 安全提示：-y 会把密钥材料留在 shell 历史里，生产操作优先把密钥放配置文件用 -K <name> 引用。

7.3 DNSSEC 签名验证

dig @127.0.0.1 example.test DNSKEY +noall +answer | cut -c1-90
dig @127.0.0.1 www.example.test A +dnssec +noall +answer | grep RRSIG | cut -c1-130

实测回显：

example.test.		86400	IN	DNSKEY	256 3 8 [key id = 54354]
example.test.		86400	IN	DNSKEY	257 3 8 [key id = 47629]
www.example.test.	86400	IN	RRSIG	A 8 3 86400 20261124052511 20261025050310 54354 example.test. LlwCuIn5wccy4wY4+4OndNOe8kYdG07GPl2

解读：256/257 是 DNSKEY 标志位（ZSK/KSK），8 为 RSASHA256 算法号，RRSIG 中间字段依次为算法/类型位图/原始 TTL/到期/生效时间/key tag——54354 与 ZSK 的 key tag 对应说明 www 的 A 记录由 ZSK 签名。加 +dnssec 任何时候都能看到应答自带的 RRSIG。

7.4 其他实用选项

  • +tcp：强制走 TCP（验证 max-tcp-queries 上限与防火墙 53/TCP 放行）；
  • +edns：查看应答通告的 EDNS0 载荷上限（实测 ; EDNS: version: 0, flags:; udp: 4096）；
  • +dnssec：要求并显示 DNSSEC 记录；
  • +nsid：请求 NSID（仅在服务器配置了 <nsid> 区块时有附加输出，实测环境未配置故无变化）；
  • +short：只要答案数据（脚本化场景）。

八、yakeyrolld 密钥滚动守护进程

yakeyrolld 是 DNSSEC 密钥生命周期的独立执行器（版本与主程序同步：实测 yakeyrolld -V 回显 yakeyrolld 3.0.10-11788 (2026-05-13)）。它读取独立的 yakeyrolld.conf，按 <key-roll> 的时间表推进密钥的 generate/publish/activate/inactive/remove。

yakeyrolld -h 实测回显（节选）：

/opt/yadifa/sbin/yakeyrolld [-c configurationfile] [...]

    -c, --config                        :  sets the configuration file to use
                                           (default: /opt/yadifa/etc/yakeyrolld.conf)
    -m, --mode                          :  sets the program mode
                                           (generate,play,playloop,print,print-json,genauthtoken)
    --domain fqdn                       :  the domain name, overrides the domains from the configuration file
    -p, --path directory                :  the directory where to store the keys
    -s, --server address                :  the address of the server
    --reset                             :  start by removing all the keys, create a new KSK and a new ZSK
    --policy                            :  name of the policy to use
    --from time                         :  at what time the plan starts (e.g. : now, -1y, YYYYMMDDHHSS in UTC).

实用组合：-m print / -m print-json 输出当前滚动计划（脚本化巡检用），--reset 重建全套密钥（演练环境用，⚠️ 生产禁用）。策略时间表本身的预检用 yadifad --check-policies（见 3.2）。本文实测的策略化自动签名（密钥生成与 NSEC 链）由 yadifad 内建完成，yakeyrolld 用于更复杂的跨时间排程场景。

九、常见问题与排障实录

以下错误均在实测中真实出现，按"现象回显 → 原因 → 处置"整理：

E1：CONFIG_PARSE_UNKNOWN_KEYWORD at example.test 现象：yadifa ctrl reload example.test 报错（4.2 实测）。原因：ctrl 命令的位置参数必须走 -q。处置：yadifa ctrl -q example.test reload。同族：querylog 的 enable/disable、loglevel 的级别值都要用 -q 传。

E2：command to 127.0.0.1#53 failed: NOTAUTH 现象：控制命令认证失败。原因：密钥不一致，或 -y 命令行密钥与配置文件同名密钥重复注册（此场景下还会先出现 error: failed to read the configuration ... TSIG_DUPLICATE_REGISTRATION，实测回显）。处置：两端 keys.conf 的 secret 核对一致；命令行传密钥改用 -K <name> 引用配置内密钥。

E3：error: yadifad already running with pid: xxx / PID_LOCKED 现象：重启时报。原因：异常退出后 pidfile 残留。处置：确认无进程后 rm -f /opt/yadifa/var/run/yadifad.pid 再启动；生产环境由 systemd 托管（systemctl restart yadifad）不会触发。

E4：shutdown 之后进程变僵尸/再次启动失败 现象：非 systemd 环境手工验证时观察到旧进程 defunct、pidfile 未清理。原因：PID 1 进程不回收子进程的特殊环境（真实服务器有 systemd 回收，不发生）。处置：kill -9 <pid>; rm -f /opt/yadifa/var/run/yadifad.pid 后重启。

E5：notify 发了但从服务器不动 现象：从服务器 zone.log 出现实测记录 notify: secondary: example.test.: 10.89.60.2#34447: not authorised。原因：从服务器 allow-notify 配了 TSIG key，但 NOTIFY 报文不带签名。处置：allow-notify 改为主服务器 IP（TSIG 的正确位置是 primary 行，见配置篇 9.2）。

E6：Transfer failed. 现象：dig @10.89.60.2 example.test AXFR 无数据（7.2 实测）。原因：服务器 ACL 限制区域传输（这是正确行为）。处置：带 TSIG 重试或核对 allow-transfer；若是主→从同步失败则核对从区域 primary 行的 key <name>。

十、参考链接