1nsd-control(8) nsd 4.3.9 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 searched for in the PATH set in the environment. It is started
33 with the config file specified using -c or the default config
34 file.
35 stop Stop the server. The server daemon exits.
37 reload [<zone>]
39 Reload zonefiles and reopen logfile. Without argument reads
40 changed zonefiles. With argument reads the zonefile for the
41 given zone and loads it.
42 reconfig
44 Reload nsd.conf and apply changes to TSIG keys and configuration
45 patterns, and apply the changes to add and remove zones that are
46 mentioned in the config. Other changes are not applied, such as
47 listening ip address and port and chroot, also per-zone statis‐
48 tics are not applied. The pattern updates means that the con‐
49 figuration options for zones (request-xfr, zonefile, notify,
50 ...) are updated. Also new patterns are available for use with
51 the addzone command.
52 repattern
54 Same as the reconfig option.
55 log_reopen
57 Reopen the logfile, for log rotate that wants to move the log‐
58 file away and create a new logfile. The log can also be re‐
59 opened with kill -HUP (which also reloads all zonefiles).
60 status Display server status. Exit code 3 if not running (the connec‐
62 tion to the port is refused), 1 on error, 0 if running.
63 stats Output a sequence of name=value lines with statistics informa‐
65 tion, requires NSD to be compiled with this option enabled.
66 stats_noreset
68 Same as stats, but does not zero the counters.
69 addzone <zone name> <pattern name>
71 Add a new zone to the running server. The zone is added to the
72 zonelist file on disk, so it stays after a restart. The pattern
73 name determines the options for the new zone. For slave zones a
74 zone transfer is immediately attempted. For zones with a zone‐
75 file, the zone file is attempted to be read in.
76 delzone <zone name>
78 Remove the zone from the running server. The zone is removed
79 from the zonelist file on disk, from the nsd.db file and from
80 the memory. If it had a zonefile, this remains (but may be out‐
81 dated). Zones configured inside nsd.conf itself cannot be re‐
82 moved this way because the daemon does not write to the nsd.conf
83 file, you need to add such zones to the zonelist file to be able
84 to delete them with the delzone command.
85 changezone <zone name> <pattern name>
87 Change a zone to use the pattern for options. The zone is
88 deleted and added in one operation, changing it to use the new
89 pattern for the zone options. Zones configured in nsd.conf can‐
90 not be changed like this, instead edit the nsd.conf (or the in‐
91 cluded file in nsd.conf) and reconfig.
92 addzones
94 Add zones read from stdin of nsd-control. Input is read per
95 line, with name space patternname on a line. For bulk addi‐
96 tions.
97 delzones
99 Remove zones read from stdin of nsd-control. Input is one name
100 per line. For bulk removals.
101 write [<zone>]
103 Write zonefiles to disk, or the given zonefile to disk. Zones
104 that have changed (via AXFR or IXFR) are written, or if the
105 zonefile has not been created yet then it is created. Directory
106 components of the zonefile path are created if necessary. With
107 argument that zone is written if it was modified, without argu‐
108 ment, all modified zones are written.
109 notify [<zone>]
111 Send NOTIFY messages to slave servers. Sends to the IP ad‐
112 dresses configured in the 'notify:' lists for the master zones
113 hosted on this server. Usually NSD sends NOTIFY messages right
114 away when a master zone serial is updated. If a zone is given,
115 notifies are sent for that zone. These slave servers are sup‐
116 posed to initiate a zone transfer request later (to this server
117 or another master), this can be allowed via the 'provide-xfr:'
118 acl list configuration. With argument that zone is processed,
119 without argument, all zones are processed.
120 transfer [<zone>]
122 Attempt to update slave zones that are hosted on this server by
123 contacting the masters. The masters are configured via 're‐
124 quest-xfr:' lists. If a zone is given, that zone is updated.
125 Usually NSD receives a NOTIFY from the masters (configured via
126 'allow-notify:' acl list) that a new zone serial has to be
127 transferred. For zones with no content, NSD may have backed off
128 from asking often because the masters did not respond, but this
129 command will reset the backoff to its initial timeout, for fre‐
130 quent retries. With argument that zone is transferred, without
131 argument, all zones are transferred.
132 force_transfer [<zone>]
134 Force update slave zones that are hosted on this server. Even
135 if the master hosts the same serial number of the zone, a full
136 AXFR is performed to fetch it. If you want to use IXFR and
137 check that the serial number increases, use the 'transfer' com‐
138 mand. With argument that zone is transferred, without argument,
139 all zones are transferred.
140 zonestatus [<zone>]
142 Print state of the zone, the serial numbers and since when they
143 have been acquired. Also prints the notify action (to which
144 server), and zone transfer (and from which master) if there is
145 activity right now. The state of the zone is printed as: 'mas‐
146 ter' (master zones), 'ok' (slave zone is up-to-date), 'expired'
147 (slave zone has expired), 'refreshing' (slave zone has transfers
148 active). The serial numbers printed are the 'served-serial'
149 (currently active), the 'commit-serial' (is in reload), the 'no‐
150 tified-serial' (got notify, busy fetching the data). The serial
151 numbers are only printed if such a serial number is available.
152 With argument that zone is printed, without argument, all zones
153 are printed.
154 serverpid
156 Prints the PID of the server process. This is used for statis‐
157 tics (and only works when NSD is compiled with statistics en‐
158 abled). This pid is not for sending unix signals, use the pid
159 from nsd.pid for that, that pid is also stable.
160 verbosity <number>
162 Change logging verbosity.
163 print_tsig [<key_name>]
165 print the secret and algorithm for the TSIG key with that name.
166 Or list all the tsig keys with their name, secret and algorithm.
167 update_tsig <name> <secret>
169 Change existing TSIG key with name to the new secret. The se‐
170 cret is a base64 encoded string. The changes are only in-memory
171 and are gone next restart, for lasting changes edit the nsd.conf
172 file or a file included from it.
173 add_tsig <name> <secret> [algo]
175 Add a new TSIG key with the given name, secret and algorithm.
176 Without algorithm a default (hmac-sha256) algorithm is used.
177 The secret is a base64 encoded string. The changes are only in-
178 memory and are gone next restart, for lasting changes edit the
179 nsd.conf file or a file included from it.
180 assoc_tsig <zone> <key_name>
182 Associate the zone with the given tsig. The access control
183 lists for notify, allow-notify, provide-xfr and request-xfr are
184 adjusted to use the given key.
185 del_tsig <key_name>
187 Delete the TSIG key with the given name. Prints error if the
188 key is still in use by some zone. The changes are only in-mem‐
189 ory and are gone next restart, for lasting changes edit the
190 nsd.conf file or a file included from it.
191 add_cookie_secret <secret>
193 Add or replace a cookie secret persistently. <secret> needs to
194 be an 128 bit hex string.
195 Cookie secrets can be either active or staging. Active cookie
197 secrets are used to create DNS Cookies, but verification of a
198 DNS Cookie succeeds with any of the active or staging cookie se‐
199 crets. The state of the current cookie secrets can be printed
200 with the print_cookie_secrets command.
201 When there are no cookie secrets configured yet, the <secret> is
203 added as active. If there is already an active cookie secret,
204 the <secret> is added as staging or replacing an existing stag‐
205 ing secret.
206 To "roll" a cookie secret used in an anycast set. The new secret
208 has to be added as staging secret to all nodes in the anycast
209 set. When all nodes can verify DNS Cookies with the new secret,
210 the new secret can be activated with the activate_cookie_secret
211 command. After all nodes have the new secret active for at least
212 one hour, the previous secret can be dropped with the
213 drop_cookie_secret command.
214 Persistence is accomplished by writing to a file which if con‐
216 figured with the cookie-secret-file option in the server section
217 of the config file. The default value for that is:
218 /etc/nsd/nsd_cookiesecrets.txt .
219 drop_cookie_secret
221 Drop the staging cookie secret.
222 activate_cookie_secret
224 Make the current staging cookie secret active, and the current
225 active cookie secret staging.
226 print_cookie_secrets
228 Show the current configured cookie secrets with their status.
229
231 The nsd-control program exits with status code 1 on error, 0 on suc‐
232 cess.
233
235 The setup requires a self-signed certificate and private keys for both
236 the server and client. The script nsd-control-setup generates these in
237 the default run directory, or with -d in another directory. If you
238 change the access control permissions on the key files you can decide
239 who can use nsd-control, by default owner and group but not all users.
240 The script preserves private keys present in the directory. After run‐
241 ning the script as root, turn on control-enable in nsd.conf.
242
244 The stats command shows a number of statistic counters.
245 num.queries
247 number of queries received (the tls, tcp and udp queries added
248 up).
249 serverX.queries
251 number of queries handled by the server process. The number of
252 server processes is set with the config statement server-count.
253 time.boot
255 uptime in seconds since the server was started. With fractional
256 seconds.
257 time.elapsed
259 time since the last stats report, in seconds. With fractional
260 seconds. Can be zero if polled quickly and the previous stats
261 command resets the counters, so that the next gets a fully zero,
262 and zero elapsed time, report.
263 size.db.disk
265 size of nsd.db on disk, in bytes.
266 size.db.mem
268 size of the DNS database in memory, in bytes.
269 size.xfrd.mem
271 size of memory for zone transfers and notifies in xfrd process,
272 excludes TSIG data, in bytes.
273 size.config.disk
275 size of zonelist file on disk, excludes the nsd.conf size, in
276 bytes.
277 size.config.mem
279 size of config data in memory, kept twice in server and xfrd
280 process, in bytes.
281 num.type.X
283 number of queries with this query type.
284 num.opcode.X
286 number of queries with this opcode.
287 num.class.X
289 number of queries with this query class.
290 num.rcode.X
292 number of answers that carried this return code.
293 num.edns
295 number of queries with EDNS OPT.
296 num.ednserr
298 number of queries which failed EDNS parse.
299 num.udp
301 number of queries over UDP ip4.
302 num.udp6
304 number of queries over UDP ip6.
305 num.tcp
307 number of connections over TCP ip4.
308 num.tcp6
310 number of connections over TCP ip6.
311 num.tls
313 number of connections over TLS ip4. TLS queries are not part of
314 num.tcp.
315 num.tls6
317 number of connections over TLS ip6. TLS queries are not part of
318 num.tcp6.
319 num.answer_wo_aa
321 number of answers with NOERROR rcode and without AA flag, this
322 includes the referrals.
323 num.rxerr
325 number of queries for which the receive failed.
326 num.txerr
328 number of answers for which the transmit failed.
329 num.raxfr
331 number of AXFR requests from clients (that got served with re‐
332 ply).
333 num.truncated
335 number of answers with TC flag set.
336 num.dropped
338 number of queries that were dropped because they failed sanity
339 check.
340 zone.master
342 number of master zones served. These are zones with no 're‐
343 quest-xfr:' entries.
344 zone.slave
346 number of slave zones served. These are zones with 're‐
347 quest-xfr' entries.
348
350 /etc/nsd/nsd.conf
351 nsd configuration file.
352 /etc/nsd
354 directory with private keys (nsd_server.key and nsd_control.key)
355 and self-signed certificates (nsd_server.pem and nsd_con‐
356 trol.pem).
357
359 nsd.conf(5), nsd(8), nsd-checkconf(8)
360NLnet Labs Dec 9, 2021 nsd-control(8)