1nsd-control(8)                     nsd 4.3.5                    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
59              reopened 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
82              removed  this  way  because  the  daemon  does  not write to the
83              nsd.conf file, you need to add such zones to the  zonelist  file
84              to be able 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
91              included 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.
107
108       notify [<zone>]
109              Send  NOTIFY  messages  to  slave  servers.   Sends  to  the  IP
110              addresses configured in the 'notify:' lists for the master zones
111              hosted  on this server.  Usually NSD sends NOTIFY messages right
112              away when a master zone serial is updated.  If a zone is  given,
113              notifies  are  sent for that zone.  These slave servers are sup‐
114              posed to initiate a zone transfer request later (to this  server
115              or  another  master), this can be allowed via the 'provide-xfr:'
116              acl list configuration.
117
118       transfer [<zone>]
119              Attempt to update slave zones that are hosted on this server  by
120              contacting   the   masters.   The  masters  are  configured  via
121              'request-xfr:' lists.  If a zone is given, that zone is updated.
122              Usually  NSD  receives a NOTIFY from the masters (configured via
123              'allow-notify:' acl list) that a  new  zone  serial  has  to  be
124              transferred.  For zones with no content, NSD may have backed off
125              from asking often because the masters did not respond, but  this
126              command  will reset the backoff to its initial timeout, for fre‐
127              quent retries.
128
129       force_transfer [<zone>]
130              Force update slave zones that are hosted on this  server.   Even
131              if  the  master hosts the same serial number of the zone, a full
132              AXFR is performed to fetch it.  If you  want  to  use  IXFR  and
133              check  that the serial number increases, use the 'transfer' com‐
134              mand.
135
136       zonestatus [<zone>]
137              Print state of the zone, the serial numbers and since when  they
138              have  been  acquired.   Also  prints the notify action (to which
139              server), and zone transfer (and from which master) if  there  is
140              activity  right now.  The state of the zone is printed as: 'mas‐
141              ter' (master zones), 'ok' (slave zone is up-to-date),  'expired'
142              (slave zone has expired), 'refreshing' (slave zone has transfers
143              active).  The serial numbers  printed  are  the  'served-serial'
144              (currently  active),  the  'commit-serial'  (is  in reload), the
145              'notified-serial' (got notify, busy  fetching  the  data).   The
146              serial  numbers  are  only  printed  if  such a serial number is
147              available.
148
149       serverpid
150              Prints the PID of the server process.  This is used for  statis‐
151              tics  (and  only  works  when  NSD  is  compiled with statistics
152              enabled).  This pid is not for sending unix signals, use the pid
153              from nsd.pid for that, that pid is also stable.
154
155       verbosity <number>
156              Change logging verbosity.
157
158       print_tsig [<key_name>]
159              print  the secret and algorithm for the TSIG key with that name.
160              Or list all the tsig keys with their name, secret and algorithm.
161
162       update_tsig <name> <secret>
163              Change existing TSIG key with  name  to  the  new  secret.   The
164              secret is a base64 encoded string.  The changes are only in-mem‐
165              ory and are gone next restart,  for  lasting  changes  edit  the
166              nsd.conf file or a file included from it.
167
168       add_tsig <name> <secret> [algo]
169              Add  a  new  TSIG key with the given name, secret and algorithm.
170              Without algorithm a default  (hmac-sha256)  algorithm  is  used.
171              The secret is a base64 encoded string.  The changes are only in-
172              memory and are gone next restart, for lasting changes  edit  the
173              nsd.conf file or a file included from it.
174
175       assoc_tsig <zone> <key_name>
176              Associate  the  zone  with  the  given tsig.  The access control
177              lists for notify, allow-notify, provide-xfr and request-xfr  are
178              adjusted to use the given key.
179
180       del_tsig <key_name>
181              Delete  the  TSIG  key with the given name.  Prints error if the
182              key is still in use by some zone.  The changes are only  in-mem‐
183              ory  and  are  gone  next  restart, for lasting changes edit the
184              nsd.conf file or a file included from it.
185

EXIT CODE

187       The nsd-control program exits with status code 1 on error,  0  on  suc‐
188       cess.
189

SET UP

191       The  setup requires a self-signed certificate and private keys for both
192       the server and client.  The script nsd-control-setup generates these in
193       the  default  run  directory,  or with -d in another directory.  If you
194       change the access control permissions on the key files you  can  decide
195       who  can use nsd-control, by default owner and group but not all users.
196       The script preserves private keys present in the directory.  After run‐
197       ning the script as root, turn on control-enable in nsd.conf.
198

STATISTIC COUNTERS

200       The stats command shows a number of statistic counters.
201
202       num.queries
203              number  of  queries received (the tls, tcp and udp queries added
204              up).
205
206       serverX.queries
207              number of queries handled by the server process.  The number  of
208              server processes is set with the config statement server-count.
209
210       time.boot
211              uptime in seconds since the server was started.  With fractional
212              seconds.
213
214       time.elapsed
215              time since the last stats report, in seconds.   With  fractional
216              seconds.   Can  be zero if polled quickly and the previous stats
217              command resets the counters, so that the next gets a fully zero,
218              and zero elapsed time, report.
219
220       size.db.disk
221              size of nsd.db on disk, in bytes.
222
223       size.db.mem
224              size of the DNS database in memory, in bytes.
225
226       size.xfrd.mem
227              size  of memory for zone transfers and notifies in xfrd process,
228              excludes TSIG data, in bytes.
229
230       size.config.disk
231              size of zonelist file on disk, excludes the  nsd.conf  size,  in
232              bytes.
233
234       size.config.mem
235              size  of  config  data  in memory, kept twice in server and xfrd
236              process, in bytes.
237
238       num.type.X
239              number of queries with this query type.
240
241       num.opcode.X
242              number of queries with this opcode.
243
244       num.class.X
245              number of queries with this query class.
246
247       num.rcode.X
248              number of answers that carried this return code.
249
250       num.edns
251              number of queries with EDNS OPT.
252
253       num.ednserr
254              number of queries which failed EDNS parse.
255
256       num.udp
257              number of queries over UDP ip4.
258
259       num.udp6
260              number of queries over UDP ip6.
261
262       num.tcp
263              number of connections over TCP ip4.
264
265       num.tcp6
266              number of connections over TCP ip6.
267
268       num.tls
269              number of connections over TLS ip4.  TLS queries are not part of
270              num.tcp.
271
272       num.tls6
273              number of connections over TLS ip6.  TLS queries are not part of
274              num.tcp6.
275
276       num.answer_wo_aa
277              number of answers with NOERROR rcode and without AA  flag,  this
278              includes the referrals.
279
280       num.rxerr
281              number of queries for which the receive failed.
282
283       num.txerr
284              number of answers for which the transmit failed.
285
286       num.raxfr
287              number  of  AXFR  requests  from  clients  (that got served with
288              reply).
289
290       num.truncated
291              number of answers with TC flag set.
292
293       num.dropped
294              number of queries that were dropped because they  failed  sanity
295              check.
296
297       zone.master
298              number  of  master  zones  served.   These  are  zones  with  no
299              'request-xfr:' entries.
300
301       zone.slave
302              number  of  slave  zones   served.    These   are   zones   with
303              'request-xfr' entries.
304

FILES

306       /etc/nsd/nsd.conf
307              nsd configuration file.
308
309       /etc/nsd
310              directory with private keys (nsd_server.key and nsd_control.key)
311              and  self-signed  certificates  (nsd_server.pem   and   nsd_con‐
312              trol.pem).
313

SEE ALSO

315       nsd.conf(5), nsd(8), nsd-checkconf(8)
316
317
318
319NLnet Labs                       Jan 26, 2021                   nsd-control(8)
Impressum