1nsd-control(8)                     nsd 4.3.9                    nsd-control(8)
2
3
4

NAME

6       nsd-control, nsd-control-setup - NSD remote server control utility.
7

SYNOPSIS

9       nsd-control [-c cfgfile] [-s server] command
10

DESCRIPTION

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
16       The available options are:
17
18       -h     Show the version and commandline option help.
19
20       -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
24       -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

COMMANDS

29       There are several commands that the server understands.
30
31       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
36       stop   Stop the server. The server daemon exits.
37
38       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
43       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
53       repattern
54              Same as the reconfig option.
55
56       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
61       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
64       stats  Output a sequence of name=value lines with  statistics  informa‐
65              tion, requires NSD to be compiled with this option enabled.
66
67       stats_noreset
68              Same as stats, but does not zero the counters.
69
70       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
77       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
86       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
93       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
98       delzones
99              Remove  zones read from stdin of nsd-control.  Input is one name
100              per line.  For bulk removals.
101
102       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
110       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
121       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
133       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
141       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
155       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
161       verbosity <number>
162              Change logging verbosity.
163
164       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
168       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
174       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
181       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
186       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
192       add_cookie_secret <secret>
193              Add or replace a cookie secret persistently. <secret>  needs  to
194              be an 128 bit hex string.
195
196              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
202              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
207              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
215              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
220       drop_cookie_secret
221              Drop the staging cookie secret.
222
223       activate_cookie_secret
224              Make  the  current staging cookie secret active, and the current
225              active cookie secret staging.
226
227       print_cookie_secrets
228              Show the current configured cookie secrets with their status.
229

EXIT CODE

231       The nsd-control program exits with status code 1 on error,  0  on  suc‐
232       cess.
233

SET UP

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

STATISTIC COUNTERS

244       The stats command shows a number of statistic counters.
245
246       num.queries
247              number  of  queries received (the tls, tcp and udp queries added
248              up).
249
250       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
254       time.boot
255              uptime in seconds since the server was started.  With fractional
256              seconds.
257
258       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
264       size.db.disk
265              size of nsd.db on disk, in bytes.
266
267       size.db.mem
268              size of the DNS database in memory, in bytes.
269
270       size.xfrd.mem
271              size  of memory for zone transfers and notifies in xfrd process,
272              excludes TSIG data, in bytes.
273
274       size.config.disk
275              size of zonelist file on disk, excludes the  nsd.conf  size,  in
276              bytes.
277
278       size.config.mem
279              size  of  config  data  in memory, kept twice in server and xfrd
280              process, in bytes.
281
282       num.type.X
283              number of queries with this query type.
284
285       num.opcode.X
286              number of queries with this opcode.
287
288       num.class.X
289              number of queries with this query class.
290
291       num.rcode.X
292              number of answers that carried this return code.
293
294       num.edns
295              number of queries with EDNS OPT.
296
297       num.ednserr
298              number of queries which failed EDNS parse.
299
300       num.udp
301              number of queries over UDP ip4.
302
303       num.udp6
304              number of queries over UDP ip6.
305
306       num.tcp
307              number of connections over TCP ip4.
308
309       num.tcp6
310              number of connections over TCP ip6.
311
312       num.tls
313              number of connections over TLS ip4.  TLS queries are not part of
314              num.tcp.
315
316       num.tls6
317              number of connections over TLS ip6.  TLS queries are not part of
318              num.tcp6.
319
320       num.answer_wo_aa
321              number of answers with NOERROR rcode and without AA  flag,  this
322              includes the referrals.
323
324       num.rxerr
325              number of queries for which the receive failed.
326
327       num.txerr
328              number of answers for which the transmit failed.
329
330       num.raxfr
331              number  of  AXFR requests from clients (that got served with re‐
332              ply).
333
334       num.truncated
335              number of answers with TC flag set.
336
337       num.dropped
338              number of queries that were dropped because they  failed  sanity
339              check.
340
341       zone.master
342              number  of  master  zones  served.  These are zones with no 're‐
343              quest-xfr:' entries.
344
345       zone.slave
346              number of  slave  zones  served.   These  are  zones  with  're‐
347              quest-xfr' entries.
348

FILES

350       /etc/nsd/nsd.conf
351              nsd configuration file.
352
353       /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

SEE ALSO

359       nsd.conf(5), nsd(8), nsd-checkconf(8)
360
361
362
363NLnet Labs                       Dec  9, 2021                   nsd-control(8)
Impressum