NSD 4.15.3 配置参数详解

目标：以实测方式讲透 NSD 4.15.3 的 /etc/nsd/nsd.conf 全部常用参数——先用 nsd-checkconf 建立「查看 → 校验 → 生效」的工作流，再按分组给出全量参数总览（默认值实测口径）与逐项详解，最后给出通过校验的生产配置模板。全部取值、报错与行为均在 Ubuntu 22.04 + NSD 4.15.3 实测采集。

一、环境信息

本文的「默认值」一律以 nsd-checkconf -v 打印的生效值为口径（未在演示配置中显式设置的参数即为官方默认值），并在关键处辅以行为级实测（dig 查询、进程视图）交叉验证。

二、前置条件

按 《Ubuntu 22.04 安装 NSD 指南》任一方案完成安装，并满足：

• NSD 服务运行中：systemctl is-active nsd 返回 active。
• 控制证书已初始化：nsd-control-setup 已执行（4 个证书文件在 /etc/nsd/）。
• 可用的验证工具：nsd-checkconf（本文主角）、nsd-control（生效与状态）、dig（行为验证）。

三、参数查看与修改方式

改参数前先掌握三件事：怎么查当前生效值、怎么校验改动、怎么让改动生效。NSD 4.15.3 的配套工具链完全覆盖这三步，本章全部实测。

3.1 nsd-checkconf：校验器与查询器

nsd-checkconf 既是配置校验器也是配置查询器。注意 4.15.3 必须显式传入配置文件路径，无参数调用只会打印用法（实测）：

$ nsd-checkconf
usage: nsd-checkconf [-v|-h] [-o option] [-z zonename]
                     [-s keyname] [-t tlsauthname] <configfilename>
       Checks NSD configuration file for errors.
       Version 4.15.3. Report bugs to <https://github.com/NLnetLabs/nsd/issues or nsd-bugs@nlnetlabs.nl>.

Use with a configfile as argument to check syntax.
Use with -o, -z, -t or -s options to query the configuration.

-v                      Verbose, echo settings that take effect to std output.
-h                      Print this help information.
-f                      Use with -o to print final pathnames, ie. with chroot.
-o option               Print value of the option specified to stdout.
-p pattern              Print option value for the pattern given.
-z zonename             Print option value for the zone given.
-a keyname              Print algorithm name for the TSIG key.
-s keyname              Print base64 secret blob for the TSIG key.
-t tls-auth-name        Print auth domain name for the tls-auth clause.
（exit=1）

配置校验通过时无任何输出、退出码 0：

nsd-checkconf /etc/nsd/nsd.conf
echo $?

实测回显：

0

3.2 -v：打印全量生效参数

nsd-checkconf -v /etc/nsd/nsd.conf

实测输出（节选头部，完整值见第四章总览表）：

# Read file /etc/nsd/nsd.conf: 1 patterns, 1 fixed-zones, 0 keys, 0 tls-auth.
# Config settings.
server:
	debug-mode: no
	ip-transparent: no
	ip-freebind: no
	reuseport: no
	do-ip4: yes
	do-ip6: yes
	...
	username: "nsd"
	zonesdir: "/etc/nsd"
	...
verbosity: 1
ip-address: 127.0.0.1
ip-address: 192.168.146.128

输出解读：第一行汇总配置文件结构（pattern/固定 zone/key/tls-auth 数量）；随后按 server/remote-control/verify/zone 分段打印全部生效值——显式设置的与默认的混排在一起，正是生产核查「到底什么在生效」的工具。注意少数行以 # 前缀输出（如 #version:、#logfile:），表示该选项未设置（无值的字符串型选项），默认值以其注释行内容为准（如 #cookie-secret-file: "/var/db/nsd/cookiesecrets.txt" 给出了默认路径）。

3.3 -o/-z/-p/-s/-a：单值提取

脚本化取值时用单值查询（注意：配置文件路径是最后一个参数）：

3.4 修改生效的两条路径（重要实测结论）

参数改动分两类生效路径，实测结论：

• zone 段、pattern 段、remote-control 段改动：nsd-control reconfig 即时生效，输出 reconfig start, read /etc/nsd/nsd.conf + reconfig completed: changes applied，进程不重启。
• server 段标量参数改动（如 hide-version、refuse-any、verbosity 初始值等）：实测 nsd-control reconfig 返回 reconfig completed: no changes detected，改动并不生效，必须 systemctl restart nsd。

反转验证实录（hide-version 由 yes 改为 no、refuse-any 由 no 改为 yes 后）：

$ nsd-control reconfig
reconfig start, read /etc/nsd/nsd.conf
reconfig completed: no changes detected
ok
$ dig @127.0.0.1 version.server ch txt +noall +answer
（无应答——hide-version 仍为 yes，改动未生效）
$ systemctl restart nsd && sleep 1
$ dig @127.0.0.1 version.server ch txt +noall +answer
version.server.         0       CH      TXT     "NSD 4.15.3"
（restart 后生效，版本号暴露——随后改回 hide-version: yes）

💡 实操建议：改完配置先 nsd-checkconf 校验；仅动了 zone/pattern/remote-control 就 nsd-control reconfig；动了 server 段就直接 systemctl restart nsd，不要指望 reconfig。

3.5 报错格式与退出码

配置错误的统一格式：文件名:行号: error: 原因，随后一行 read <文件> failed: N errors in configuration file，退出码 2。六类典型错误实测（每例都是最小复现配置）：

每例完整回显均为三行（报错行 + failed 行 + exit=2），例如：

c1-err1.conf:4: error: expected a number
read c1-err1.conf failed: 1 errors in configuration file

四、参数总览

以下总览来自 nsd-checkconf -v /etc/nsd/nsd.conf 实测整理，除标注「演示所设」的少数项外均为 NSD 4.15.3 默认值。参数详解见第五章对应小节。

server 段——基础开关

server 段——身份与指纹

server 段——进程与并发

server 段——日志与统计

server 段——监听与端口

server 段——文件与目录

server 段——应答行为与缓冲

server 段——RRL 限流

server 段——Prometheus 指标（4.15.0+）

remote-control 段

verify 段

五、核心参数分类详解

本章对高频参数逐项展开：默认值、语义、实测证据。每小节均可在第三章工作流下复现。

5.1 监听地址与端口（ip-address、port、do-ip4/do-ip6）

• ip-address：监听地址，可多行叠加。实测 nsd-checkconf -o ip-address 逐行输出两个地址；ss -ltnp 实测两个地址均在 53 端口监听。不设置时绑定 0.0.0.0/[::]，与 systemd-resolved 的 127.0.0.53 stub 冲突是首启失败最常见原因（排障实录见安装篇 4.3 节）。
• port：查询端口，默认 "53"，一般不改。
• do-ip4/do-ip6：协议开关；纯内网环境可 do-ip6: no 关闭 IPv6 监听。
• reuseport：开启后每个 server 子进程独立 socket 分流，高并发场景提升吞吐；只接受 yes/no，实测 reuseport: 4 报 expected yes or no。

5.2 进程与并发（server-count、tcp-count）

• server-count：server 子进程数，默认 1。实测改为 2 后 systemctl status nsd 的 CGroup 从 3 个进程变为 4 个（1 主控 + 2 server + 1 辅助），恢复默认后回到 3 个；并发查询能力随子进程数扩展，建议设为 CPU 核数。
• tcp-count：并发 TCP 连接上限（默认 100）；tcp-query-count 单连接查询数（0=不限制）；tcp-timeout 空闲超时 120 秒。tcp-mss/outgoing-tcp-mss 用于 VPN/隧道场景调 MSS，默认 0 不设置。
• xfrd-tcp-max 128 / xfrd-tcp-pipeline 128：区传送连接与管道并发，从区数量大时适当调大。

5.3 身份与指纹（hide-version、identity）

• hide-version: yes 实测行为：CHAOS 类 version.server 查询被拒绝（REFUSED + EDE 18 Prohibited），版本信息不外泄：

$ dig @127.0.0.1 version.server ch txt +noall +comments
;; ->>HEADER<<- opcode: QUERY, status: REFUSED, id: 52314
;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 1232
; EDE: 18 (Prohibited)

改为 hide-version: no 后同一查询返回：

version.server.         0       CH      TXT     "NSD 4.15.3"

• identity：自定义 identity 应答字符串；hide-identity: no 时 CHAOS id.server 查询返回该值。nsid 未设置时不响应 NSID。

5.4 日志与统计（verbosity、log-only-syslog）

• verbosity：0（静默）–5（debug）五级。默认 1。运行中可用 nsd-control verbosity N 动态调整（实测 3 后 status 显示 3，调回 1 显示 1），重启用配置文件初始值。
• log-only-syslog: yes：日志全部交 syslog（journalctl -u nsd 查看）；独立 logfile 与该参数互斥使用。
• statistics: 0：周期统计输出间隔秒数，0=关闭周期输出（统计仍可随时 nsd-control stats 主动拉取）。生产建议 3600。

5.5 文件与目录（zonesdir、zonefiles-write）

• zonesdir：zone 文件基准目录，zonefile 用相对路径时基于它解析（zonefile: "example.com.zone" → /etc/nsd/example.com.zone）。
• zonefiles-write: 3600：从区数据落盘周期；zonefiles-check: yes：启动/reload 时按 mtime 检查 zone 文件变化。
• xfrdir /tmp：区传送临时文件目录；安全要求高的环境可移到专用目录。

5.6 应答行为（refuse-any、answer-cookie、minimal-responses）

• ANY 查询的内置极小化（RFC 8482）：4.15.3 对 ANY 查询默认只回一个 RRset（源码 query.c 明示 "Minimize response size for ANY, with one RRset according to RFC 8482(4.1)"）。原始 UDP 报文实测：QTYPE=255 → rcode=0、ANCOUNT=1、75 字节，与 refuse-any 取值无关。
• refuse-any: yes 的确切行为（实测 + 源码双证）：仅对 UDP 的 ANY 查询返回 TC=1 的空 NOERROR（12 字节，仅报文头），引导客户端转 TCP 重试；TCP 查询不受影响。原始报文对比实测：

• minimal-responses：极小化附加段（authority/additional 里少放粘合记录），no 时完整给出。
• answer-cookie：DNS Cookie 支持。默认 no——实测 dig +cookie 应答的 OPT PSEUDOSECTION 无 COOKIE 选项；开启后回显 client cookie 并附加 server cookie（密钥由 cookie-secret 系列参数管理，默认存 /var/db/nsd/cookiesecrets.txt）。
• round-robin：同名同类型多记录轮询应答；confine-to-zone：限制越区附加段；drop-updates：丢弃 UPDATE 类查询。

5.7 RRL 响应速率限制（rrl-ratelimit）

• rrl-ratelimit: 0 默认关闭。开启后按 rrl-ipv4-prefix-length: 24（/24 聚合）与 rrl-ipv6-prefix-length: 64（/64 聚合）分桶限速；超限响应按 rrl-slip: 2 比率放行 slip 应答（每 2 个超限响应放行 1 个截断应答，给合法客户端恢复线索）。
• 版本默认值差异实测：4.3.9 的 nsd-control status 显示 ratelimit: 200（旧版内置默认），4.15.3 显示 ratelimit: 0——跨版本迁移时注意显式设置该参数。
• 生产对外权威建议 rrl-ratelimit: 200 起步，配合 rrl-size: 1000000。

5.8 remote-control 段（控制通道）

• control-enable: yes + control-interface: 127.0.0.1 + control-port: 8952：nsd-control 经 TLS 双向证书认证连接。四个证书文件由 nsd-control-setup 生成（安装篇 4.5/5.5 节实测）。control-interface 也可设 0.0.0.0 远程管理，但必须配防火墙限制来源。
• 证书文件默认路径：/etc/nsd/nsd_server.key/.pem 与 /etc/nsd/nsd_control.key/.pem，与 nsd-control-setup 的产出一致。

5.9 key 段与访问控制 ACL（provide-xfr、notify）

TSIG 密钥定义（key 段）与 ACL 引用：

key:
        name: "transfer-key"
        algorithm: hmac-sha256
        secret: "q1w2e3r4q1w2e3r4q1w2e3r4q1w2e3r4"

pattern:
        name: "secondary"
        provide-xfr: 192.168.146.0/24 transfer-key

• ACL 四兄弟语义：provide-xfr（允许谁来做区传送拉取）、request-xfr（向谁拉取，从区用）、notify（向谁发 NOTIFY）、allow-notify（接受谁的 NOTIFY）。
• 语法铁律（实测）：每行 ACL 必须是「IP 或 CIDR + 空格 + key 名或 NOKEY」，缺后半段直接语法错误（error: syntax error）；引用未定义的 key 名报 key ghost-key in pattern template could not be found。
• algorithm 支持 hmac-sha256/hmac-sha1 等；secret 为 base64 串。生产环境不要用演示弱密钥，用 tsig-keygen（BIND 工具）或 openssl 生成随机串。

5.10 zone 段与动态区管理（pattern、addzone/delzone）

• zone 段最小形态：name（区名）+ zonefile（相对 zonesdir 或绝对路径）。固定 zone 直接写在配置里（-v 汇总显示 1 fixed-zones）。
• pattern 段：模板块，zonefile 支持 %s 通配区名（如 zonefile: "%s.zone"）；动态加区时引用：

nsd-control addzone test2.com template
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

• 动态区记录持久化在 zonelistfile（/var/lib/nsd/zone.list）。权限排障实录：/var/lib/nsd 属主为 root 时 addzone 失败——journal 报 could not create zone list /var/lib/nsd/zone.list: Permission denied，控制端报 error could not add zonelist entry；chown -R nsd:nsd /var/lib/nsd 后恢复（详见安装篇 5.4 节）。

5.11 加密传输与指标（tls-service-*、metrics-enable）

• DoT 服务端：tls-service-key/tls-service-pem 指定证书，tls-port: 853 监听；客户端过来的 PROXYv2 连接用 allow-proxy ACL（4.15.2+）。
• Prometheus 指标：metrics-enable: yes 后在 metrics-port: 9100 的 metrics-path: /metrics 暴露指标（4.15.0 起支持，zonestats 以 label 形式输出）。
• tls-auth 段：区传送走 TLS（XoT）时的对端认证配置，与 tls-service-* 是两回事。

六、生产配置模板

以下模板在 4.15.3 上以 nsd-checkconf production.conf 实测通过（exit=0），适合对外权威服务起步；按需增删。

# NSD 生产配置模板（NSD 4.15.3，nsd-checkconf 实测通过）
server:
        username: nsd
        log-only-syslog: yes
        verbosity: 1
        hide-version: yes
        identity: "auth-dns-prod"
        ip-address: 127.0.0.1
        ip-address: 192.168.146.128
        server-count: 2
        tcp-count: 100
        statistics: 3600
        zonefiles-write: 3600
        answer-cookie: yes
        rrl-size: 1000000
        rrl-ratelimit: 200
        rrl-slip: 2

remote-control:
        control-enable: yes
        control-interface: 127.0.0.1
        control-port: 8952
        server-key-file: "/etc/nsd/nsd_server.key"
        server-cert-file: "/etc/nsd/nsd_server.pem"
        control-key-file: "/etc/nsd/nsd_control.key"
        control-cert-file: "/etc/nsd/nsd_control.pem"

# DNS over TLS 服务端（证书文件就位后取消注释）
# tls-service-key: "/etc/nsd/tls.key"
# tls-service-pem: "/etc/nsd/tls.pem"
# tls-port: 853

zone:
        name: "example.com"
        zonefile: "example.com.zone"

模板要点解读：双监听地址（本机 + 内网）规避通配绑定冲突；server-count: 2 提升并发；statistics: 3600 每小时输出统计周期；rrl-ratelimit: 200 开启基础限流；answer-cookie 开启 Cookie；hide-version 收紧指纹。内存基线实测：server-count: 1 时进程组常驻约 38M，server-count: 2 时约 70M，按区数据量与并发线性增长。

七、常见问题（FAQ）

Q1：nsd-control reconfig 后参数没生效？

server 段标量参数（hide-version、refuse-any 等）不随 reconfig 生效，实测 reconfig 返回 reconfig completed: no changes detected；执行 systemctl restart nsd 即可。只有 zone/pattern/remote-control 段改动才走 reconfig 即时生效路径（3.4 节实测）。

Q2：provide-xfr 写了 IP 却报 syntax error？

ACL 语法必须是「地址 + key 名或 NOKEY」成对出现，裸 IP 不合法（实测 c1-err3.conf:7: error: syntax error）。允许无认证传送时写 provide-xfr: 192.0.2.1 NOKEY。

Q3：配置里写了 outbound-msg-retry 报错？

NSD 4.15.3 无此参数，实测报 at 'outbound-msg-retry:': error: syntax error。查阅参数是否存在于当前版本，以 nsd-checkconf -h 配套的 man nsd.conf(5) 为准。

Q4：reuseport 想设成 4？

不支持数字。reuseport 只接受 yes/no（实测 reuseport: 4 报 expected yes or no），开启后分流行为由内核与 server-count 决定。

Q5：nsd-checkconf 不带参数直接打印 usage？

4.15.3 要求显式传配置路径（实测无参数 exit=1 打印用法）。习惯 nsd-checkconf /etc/nsd/nsd.conf && nsd-control reconfig 的组合。

Q6：checkconf -v 输出里 # 开头的行是什么？

表示该选项未设置（字符串型且无默认展示），其后引号内是潜在默认值（如 #cookie-secret-file: "/var/db/nsd/cookiesecrets.txt"）。核对默认值时不要把注释行当生效值。

Q7：53 端口被占或 addzone 报权限错误？

均为安装期高频问题，排障实录见 《Ubuntu 22.04 安装 NSD 指南》：前者见其 4.3–4.4 节（53 端口冲突），后者见 5.4 节（/var/lib/nsd 属主 chown）。

八、参考链接

8.1 官方链接

8.2 本系列篇目

• 《NSD 4.15.3 介绍与选型指南》：定位、架构与选型对比。
• 《Ubuntu 22.04 安装 NSD 指南》：双方案安装与排障实录。
• 《NSD 4.15.3 常用 CLI 命令详解》：五件套命令逐条实测与运维组合场景。