1nsd-control(8) nsd 4.7.0 nsd-control(8)
2
6 nsd-control, nsd-control-setup - NSD remote server control utility.
7
9 nsd-control [-c cfgfile] [-s server] command
10
12 nsd-control performs remote administration on the nsd(8) DNS server.
13 It reads the configuration file, contacts the nsd server over SSL,
14 sends the command and displays the result.
15 The available options are:
17 -h Show the version and commandline option help.
19 -c cfgfile
21 The config file to read with settings. If not given the default
22 config file /etc/nsd/nsd.conf is used.
23 -s server[@port]
25 IPv4 or IPv6 address of the server to contact. If not given,
26 the address is read from the config file.
27
29 There are several commands that the server understands.
30 start Start the server. Simply execs nsd(8). The nsd executable is
32 not searched for in the PATH set in the environment. Instead
33 the default location relative to the installation prefix speci‐
34 fied at compile-time. The executable location can be overridden
35 by setting NSD_PATH in the environment. It is started with the
36 config file specified using -c or the default config file.
37 stop Stop the server. The server daemon exits.
39 reload [<zone>]
41 Reload zonefiles and reopen logfile. Without argument reads
42 changed zonefiles. With argument reads the zonefile for the
43 given zone and loads it.
44 reconfig
46 Reload nsd.conf and apply changes to TSIG keys and configuration
47 patterns, and apply the changes to add and remove zones that are
48 mentioned in the config. Other changes are not applied, such as
49 listening ip address and port and chroot, also per-zone statis‐
50 tics are not applied. The pattern updates means that the con‐
51 figuration options for zones (request-xfr, zonefile, notify,
52 ...) are updated. Also new patterns are available for use with
53 the addzone command.
54 repattern
56 Same as the reconfig option.
57 log_reopen
59 Reopen the logfile, for log rotate that wants to move the log‐
60 file away and create a new logfile. The log can also be re‐
61 opened with kill -HUP (which also reloads all zonefiles).
62 status Display server status. Exit code 3 if not running (the connec‐
64 tion to the port is refused), 1 on error, 0 if running.
65 stats Output a sequence of name=value lines with statistics informa‐
67 tion, requires NSD to be compiled with this option enabled.
68 stats_noreset
70 Same as stats, but does not zero the counters.
71 addzone <zone name> <pattern name>
73 Add a new zone to the running server. The zone is added to the
74 zonelist file on disk, so it stays after a restart. The pattern
75 name determines the options for the new zone. For slave zones a
76 zone transfer is immediately attempted. For zones with a zone‐
77 file, the zone file is attempted to be read in.
78 delzone <zone name>
80 Remove the zone from the running server. The zone is removed
81 from the zonelist file on disk, from the nsd.db file and from
82 the memory. If it had a zonefile, this remains (but may be out‐
83 dated). Zones configured inside nsd.conf itself cannot be re‐
84 moved this way because the daemon does not write to the nsd.conf
85 file, you need to add such zones to the zonelist file to be able
86 to delete them with the delzone command.
87 changezone <zone name> <pattern name>
89 Change a zone to use the pattern for options. The zone is
90 deleted and added in one operation, changing it to use the new
91 pattern for the zone options. Zones configured in nsd.conf can‐
92 not be changed like this, instead edit the nsd.conf (or the in‐
93 cluded file in nsd.conf) and reconfig.
94 addzones
96 Add zones read from stdin of nsd-control. Input is read per
97 line, with name space patternname on a line. For bulk addi‐
98 tions.
99 delzones
101 Remove zones read from stdin of nsd-control. Input is one name
102 per line. For bulk removals.
103 write [<zone>]
105 Write zonefiles to disk, or the given zonefile to disk. Zones
106 that have changed (via AXFR or IXFR) are written, or if the
107 zonefile has not been created yet then it is created. Directory
108 components of the zonefile path are created if necessary. With
109 argument that zone is written if it was modified, without argu‐
110 ment, all modified zones are written.
111 notify [<zone>]
113 Send NOTIFY messages to slave servers. Sends to the IP ad‐
114 dresses configured in the 'notify:' lists for the master zones
115 hosted on this server. Usually NSD sends NOTIFY messages right
116 away when a master zone serial is updated. If a zone is given,
117 notifies are sent for that zone. These slave servers are sup‐
118 posed to initiate a zone transfer request later (to this server
119 or another master), this can be allowed via the 'provide-xfr:'
120 acl list configuration. With argument that zone is processed,
121 without argument, all zones are processed.
122 transfer [<zone>]
124 Attempt to update slave zones that are hosted on this server by
125 contacting the masters. The masters are configured via 're‐
126 quest-xfr:' lists. If a zone is given, that zone is updated.
127 Usually NSD receives a NOTIFY from the masters (configured via
128 'allow-notify:' acl list) that a new zone serial has to be
129 transferred. For zones with no content, NSD may have backed off
130 from asking often because the masters did not respond, but this
131 command will reset the backoff to its initial timeout, for fre‐
132 quent retries. With argument that zone is transferred, without
133 argument, all zones are transferred.
134 force_transfer [<zone>]
136 Force update slave zones that are hosted on this server. Even
137 if the master hosts the same serial number of the zone, a full
138 AXFR is performed to fetch it. If you want to use IXFR and
139 check that the serial number increases, use the 'transfer' com‐
140 mand. With argument that zone is transferred, without argument,
141 all zones are transferred.
142 zonestatus [<zone>]
144 Print state of the zone, the serial numbers and since when they
145 have been acquired. Also prints the notify action (to which
146 server), and zone transfer (and from which master) if there is
147 activity right now. The state of the zone is printed as: 'mas‐
148 ter' (master zones), 'ok' (slave zone is up-to-date), 'expired'
149 (slave zone has expired), 'refreshing' (slave zone has transfers
150 active). The serial numbers printed are the 'served-serial'
151 (currently active), the 'commit-serial' (is in reload), the 'no‐
152 tified-serial' (got notify, busy fetching the data). The serial
153 numbers are only printed if such a serial number is available.
154 With argument that zone is printed, without argument, all zones
155 are printed.
156 serverpid
158 Prints the PID of the server process. This is used for statis‐
159 tics (and only works when NSD is compiled with statistics en‐
160 abled). This pid is not for sending unix signals, use the pid
161 from nsd.pid for that, that pid is also stable.
162 verbosity <number>
164 Change logging verbosity.
165 print_tsig [<key_name>]
167 print the secret and algorithm for the TSIG key with that name.
168 Or list all the tsig keys with their name, secret and algorithm.
169 update_tsig <name> <secret>
171 Change existing TSIG key with name to the new secret. The se‐
172 cret is a base64 encoded string. The changes are only in-memory
173 and are gone next restart, for lasting changes edit the nsd.conf
174 file or a file included from it.
175 add_tsig <name> <secret> [algo]
177 Add a new TSIG key with the given name, secret and algorithm.
178 Without algorithm a default (hmac-sha256) algorithm is used.
179 The secret is a base64 encoded string. The changes are only in-
180 memory and are gone next restart, for lasting changes edit the
181 nsd.conf file or a file included from it.
182 assoc_tsig <zone> <key_name>
184 Associate the zone with the given tsig. The access control
185 lists for notify, allow-notify, provide-xfr and request-xfr are
186 adjusted to use the given key.
187 del_tsig <key_name>
189 Delete the TSIG key with the given name. Prints error if the
190 key is still in use by some zone. The changes are only in-mem‐
191 ory and are gone next restart, for lasting changes edit the
192 nsd.conf file or a file included from it.
193 add_cookie_secret <secret>
195 Add or replace a cookie secret persistently. <secret> needs to
196 be an 128 bit hex string.
197 Cookie secrets can be either active or staging. Active cookie
199 secrets are used to create DNS Cookies, but verification of a
200 DNS Cookie succeeds with any of the active or staging cookie se‐
201 crets. The state of the current cookie secrets can be printed
202 with the print_cookie_secrets command.
203 When there are no cookie secrets configured yet, the <secret> is
205 added as active. If there is already an active cookie secret,
206 the <secret> is added as staging or replacing an existing stag‐
207 ing secret.
208 To "roll" a cookie secret used in an anycast set. The new secret
210 has to be added as staging secret to all nodes in the anycast
211 set. When all nodes can verify DNS Cookies with the new secret,
212 the new secret can be activated with the activate_cookie_secret
213 command. After all nodes have the new secret active for at least
214 one hour, the previous secret can be dropped with the
215 drop_cookie_secret command.
216 Persistence is accomplished by writing to a file which if con‐
218 figured with the cookie-secret-file option in the server section
219 of the config file. The default value for that is:
220 /etc/nsd/nsd_cookiesecrets.txt .
221 drop_cookie_secret
223 Drop the staging cookie secret.
224 activate_cookie_secret
226 Make the current staging cookie secret active, and the current
227 active cookie secret staging.
228 print_cookie_secrets
230 Show the current configured cookie secrets with their status.
231
233 The nsd-control program exits with status code 1 on error, 0 on suc‐
234 cess.
235
237 The setup requires a self-signed certificate and private keys for both
238 the server and client. The script nsd-control-setup generates these in
239 the default run directory, or with -d in another directory. If you
240 change the access control permissions on the key files you can decide
241 who can use nsd-control, by default owner and group but not all users.
242 The script preserves private keys present in the directory. After run‐
243 ning the script as root, turn on control-enable in nsd.conf.
244
246 The stats command shows a number of statistic counters.
247 num.queries
249 number of queries received (the tls, tcp and udp queries added
250 up).
251 serverX.queries
253 number of queries handled by the server process. The number of
254 server processes is set with the config statement server-count.
255 time.boot
257 uptime in seconds since the server was started. With fractional
258 seconds.
259 time.elapsed
261 time since the last stats report, in seconds. With fractional
262 seconds. Can be zero if polled quickly and the previous stats
263 command resets the counters, so that the next gets a fully zero,
264 and zero elapsed time, report.
265 size.db.disk
267 size of nsd.db on disk, in bytes.
268 size.db.mem
270 size of the DNS database in memory, in bytes.
271 size.xfrd.mem
273 size of memory for zone transfers and notifies in xfrd process,
274 excludes TSIG data, in bytes.
275 size.config.disk
277 size of zonelist file on disk, excludes the nsd.conf size, in
278 bytes.
279 size.config.mem
281 size of config data in memory, kept twice in server and xfrd
282 process, in bytes.
283 num.type.X
285 number of queries with this query type.
286 num.opcode.X
288 number of queries with this opcode.
289 num.class.X
291 number of queries with this query class.
292 num.rcode.X
294 number of answers that carried this return code.
295 num.edns
297 number of queries with EDNS OPT.
298 num.ednserr
300 number of queries which failed EDNS parse.
301 num.udp
303 number of queries over UDP ip4.
304 num.udp6
306 number of queries over UDP ip6.
307 num.tcp
309 number of connections over TCP ip4.
310 num.tcp6
312 number of connections over TCP ip6.
313 num.tls
315 number of connections over TLS ip4. TLS queries are not part of
316 num.tcp.
317 num.tls6
319 number of connections over TLS ip6. TLS queries are not part of
320 num.tcp6.
321 num.answer_wo_aa
323 number of answers with NOERROR rcode and without AA flag, this
324 includes the referrals.
325 num.rxerr
327 number of queries for which the receive failed.
328 num.txerr
330 number of answers for which the transmit failed.
331 num.raxfr
333 number of AXFR requests from clients (that got served with re‐
334 ply).
335 num.rixfr
337 number of IXFR requests from clients (that got served with re‐
338 ply).
339 num.truncated
341 number of answers with TC flag set.
342 num.dropped
344 number of queries that were dropped because they failed sanity
345 check.
346 zone.master
348 number of master zones served. These are zones with no 're‐
349 quest-xfr:' entries.
350 zone.slave
352 number of slave zones served. These are zones with 're‐
353 quest-xfr' entries.
354
356 /etc/nsd/nsd.conf
357 nsd configuration file.
358 /etc/nsd
360 directory with private keys (nsd_server.key and nsd_control.key)
361 and self-signed certificates (nsd_server.pem and nsd_con‐
362 trol.pem).
363
365 nsd.conf(5), nsd(8), nsd-checkconf(8)
366NLnet Labs Jun 7, 2023 nsd-control(8)