nsd-control(8)                    nsd 4.1.15                    nsd-control(8)



NAME
       nsd-control, nsd-control-setup - NSD remote server control utility.

SYNOPSIS
       nsd-control [-c cfgfile] [-s server] command

DESCRIPTION
       nsd-control  performs  remote  administration on the nsd(8) DNS server.
       It reads the configuration file, contacts  the  nsd  server  over  SSL,
       sends the command and displays the result.

       The available options are:

       -h     Show the version and commandline option help.

       -c cfgfile
              The config file to read with settings.  If not given the default
              config file /etc/nsd/nsd.conf is used.

       -s server[@port]
              IPv4 or IPv6 address of the server to contact.   If  not  given,
              the address is read from the config file.

COMMANDS
       There are several commands that the server understands.

       start  Start  the  server.  Simply execs nsd(8).  The nsd executable is
              searched for in the PATH set in the environment.  It is  started
              with  the  config  file specified using -c or the default config
              file.

       stop   Stop the server. The server daemon exits.

       reload [<zone>]
              Reload zonefiles and reopen  logfile.   Without  argument  reads
              changed  zonefiles.   With  argument  reads the zonefile for the
              given zone and loads it.

       reconfig
              Reload nsd.conf and apply changes to TSIG keys and configuration
              patterns, and apply the changes to add and remove zones that are
              mentioned in the config.  Other changes are not applied, such as
              listening  ip  address and port and chroot.  The pattern updates
              means that the configuration  options  for  zones  (request-xfr,
              zonefile,  notify,  ...)  are  updated.   Also  new patterns are
              available for use with the addzone command.

       repattern
              Same as the reconfig option.

       log_reopen
              Reopen the logfile, for log rotate that wants to move  the  log-
              file  away  and  create  a  new  logfile.   The  log can also be
              reopened with kill -HUP (which also reloads all zonefiles).

       status Display server status. Exit code 3 if not running  (the  connec-
              tion to the port is refused), 1 on error, 0 if running.

       stats  Output  a  sequence of name=value lines with statistics informa-
              tion, requires NSD to be compiled with this option enabled.

       stats_noreset
              Same as stats, but does not zero the counters.

       addzone <zone name> <pattern name>
              Add a new zone to the running server.  The zone is added to  the
              zonelist file on disk, so it stays after a restart.  The pattern
              name determines the options for the new zone.  For slave zones a
              zone  transfer is immediately attempted.  For zones with a zone-
              file, the zone file is attempted to be read in.

       delzone <zone name>
              Remove the zone from the running server.  The  zone  is  removed
              from  the  zonelist  file on disk, from the nsd.db file and from
              the memory.  If it had a zonefile, this remains (but may be out-
              dated).   Zones  configured  inside  nsd.conf  itself  cannot be
              removed this way because  the  daemon  does  not  write  to  the
              nsd.conf  file,  you need to add such zones to the zonelist file
              to be able to delete them with the delzone command.

       addzones
              Add zones read from stdin of nsd-control.   Input  is  read  per
              line,  with  name  space  patternname on a line.  For bulk addi-
              tions.

       delzones
              Remove zones read from stdin of nsd-control.  Input is one  name
              per line.  For bulk removals.

       write [<zone>]
              Write  zonefiles  to disk, or the given zonefile to disk.  Zones
              that have changed (via AXFR or IXFR)  are  written,  or  if  the
              zonefile has not been created yet then it is created.  Directory
              components of the zonefile path are created if necessary.

       notify [<zone>]
              Send  NOTIFY  messages  to  slave  servers.   Sends  to  the  IP
              addresses configured in the 'notify:' lists for the master zones
              hosted on this server.  Usually NSD sends NOTIFY messages  right
              away  when a master zone serial is updated.  If a zone is given,
              notifies are sent for that zone.  These slave servers  are  sup-
              posed  to initiate a zone transfer request later (to this server
              or another master), this can be allowed via  the  'provide-xfr:'
              acl list configuration.

       transfer [<zone>]
              Attempt  to update slave zones that are hosted on this server by
              contacting  the  masters.   The  masters  are   configured   via
              'request-xfr:' lists.  If a zone is given, that zone is updated.
              Usually NSD receives a NOTIFY from the masters  (configured  via
              'allow-notify:'  acl  list)  that  a  new  zone serial has to be
              transferred.  For zones with no content, NSD may have backed off
              from  asking often because the masters did not respond, but this
              command will reset the backoff to its initial timeout, for  fre-
              quent retries.

       force_transfer [<zone>]
              Force  update  slave zones that are hosted on this server.  Even
              if the master hosts the same serial number of the zone,  a  full
              AXFR  is  performed  to  fetch  it.  If you want to use IXFR and
              check that the serial number increases, use the 'transfer'  com-
              mand.

       zonestatus [<zone>]
              Print  state of the zone, the serial numbers and since when they
              have been acquired.  Also prints the  notify  action  (to  which
              server),  and  zone transfer (and from which master) if there is
              activity right now.  The state of the zone is printed as:  'mas-
              ter'  (master zones), 'ok' (slave zone is up-to-date), 'expired'
              (slave zone has expired), 'refreshing' (slave zone has transfers
              active).   The  serial  numbers  printed are the 'served-serial'
              (currently active), the  'commit-serial'  (is  in  reload),  the
              'notified-serial'  (got  notify,  busy  fetching the data).  The
              serial numbers are only printed  if  such  a  serial  number  is
              available.

       serverpid
              Prints  the PID of the server process.  This is used for statis-
              tics (and only  works  when  NSD  is  compiled  with  statistics
              enabled).  This pid is not for sending unix signals, use the pid
              from nsd.pid for that, that pid is also stable.

       verbosity <number>
              Change logging verbosity.

EXIT CODE
       The nsd-control program exits with status code 1 on error,  0  on  suc-
       cess.

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

STATISTIC COUNTERS
       The stats command shows a number of statistic counters.

       num.queries
              number of queries received (the tcp and udp queries added up).

       serverX.queries
              number  of queries handled by the server process.  The number of
              server processes is set with the config statement  server-count.

       time.boot
              uptime in seconds since the server was started.  With fractional
              seconds.

       time.elapsed
              time since the last stats report, in seconds.   With  fractional
              seconds.   Can  be zero if polled quickly and the previous stats
              command resets the counters, so that the next gets a fully zero,
              and zero elapsed time, report.

       size.db.disk
              size of nsd.db on disk, in bytes.

       size.db.mem
              size of the DNS database in memory, in bytes.

       size.xfrd.mem
              size  of memory for zone transfers and notifies in xfrd process,
              excludes TSIG data, in bytes.

       size.config.disk
              size of zonelist file on disk, excludes the  nsd.conf  size,  in
              bytes.

       size.config.mem
              size  of  config  data  in memory, kept twice in server and xfrd
              process, in bytes.

       num.type.X
              number of queries with this query type.

       num.opcode.X
              number of queries with this opcode.

       num.class.X
              number of queries with this query class.

       num.rcode.X
              number of answers that carried this return code.

       num.edns
              number of queries with EDNS OPT.

       num.ednserr
              number of queries which failed EDNS parse.

       num.udp
              number of queries over UDP ip4.

       num.udp6
              number of queries over UDP ip6.

       num.tcp
              number of connections over TCP ip4.

       num.tcp6
              number of connections over TCP ip6.

       num.answer_wo_aa
              number of answers with NOERROR rcode and without AA  flag,  this
              includes the referrals.

       num.rxerr
              number of queries for which the receive failed.

       num.txerr
              number of answers for which the transmit failed.

       num.raxfr
              number  of  AXFR  requests  from  clients  (that got served with
              reply).

       num.truncated
              number of answers with TC flag set.

       num.dropped
              number of queries that were dropped because they  failed  sanity
              check.

       zone.master
              number  of  master  zones  served.   These  are  zones  with  no
              'request-xfr:' entries.

       zone.slave
              number  of  slave  zones   served.    These   are   zones   with
              'request-xfr' entries.

FILES
       /etc/nsd/nsd.conf
              nsd configuration file.

       /etc/nsd
              directory with private keys (nsd_server.key and nsd_control.key)
              and  self-signed  certificates  (nsd_server.pem   and   nsd_con-
              trol.pem).

SEE ALSO
       nsd.conf(5), nsd(8), nsd-checkconf(8)



NLnet Labs                       Feb 16, 2017                   nsd-control(8)

Thu Feb 16 2017

© Stichting NLnet Labs

Science Park 400, 1098 XH Amsterdam, The Netherlands

labs@nlnetlabs.nl, subsidised by NLnet and SIDN.