1nsd-control(8)                     nsd 4.3.6                    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.
107
108       notify [<zone>]
109              Send  NOTIFY  messages  to  slave  servers.  Sends to the IP ad‐
110              dresses 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 're‐
121              quest-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 'no‐
145              tified-serial' (got notify, busy fetching the data).  The serial
146              numbers are only printed if such a serial number is available.
147
148       serverpid
149              Prints  the PID of the server process.  This is used for statis‐
150              tics (and only works when NSD is compiled  with  statistics  en‐
151              abled).   This  pid is not for sending unix signals, use the pid
152              from nsd.pid for that, that pid is also stable.
153
154       verbosity <number>
155              Change logging verbosity.
156
157       print_tsig [<key_name>]
158              print the secret and algorithm for the TSIG key with that  name.
159              Or list all the tsig keys with their name, secret and algorithm.
160
161       update_tsig <name> <secret>
162              Change  existing  TSIG key with name to the new secret.  The se‐
163              cret is a base64 encoded string.  The changes are only in-memory
164              and are gone next restart, for lasting changes edit the nsd.conf
165              file or a file included from it.
166
167       add_tsig <name> <secret> [algo]
168              Add a new TSIG key with the given name,  secret  and  algorithm.
169              Without  algorithm  a  default  (hmac-sha256) algorithm is used.
170              The secret is a base64 encoded string.  The changes are only in-
171              memory  and  are gone next restart, for lasting changes edit the
172              nsd.conf file or a file included from it.
173
174       assoc_tsig <zone> <key_name>
175              Associate the zone with the  given  tsig.   The  access  control
176              lists  for notify, allow-notify, provide-xfr and request-xfr are
177              adjusted to use the given key.
178
179       del_tsig <key_name>
180              Delete the TSIG key with the given name.  Prints  error  if  the
181              key  is still in use by some zone.  The changes are only in-mem‐
182              ory and are gone next restart,  for  lasting  changes  edit  the
183              nsd.conf file or a file included from it.
184

EXIT CODE

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

SET UP

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

STATISTIC COUNTERS

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

FILES

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

SEE ALSO

314       nsd.conf(5), nsd(8), nsd-checkconf(8)
315
316
317
318NLnet Labs                       Apr  6, 2021                   nsd-control(8)
Impressum