bionic (8) nsd-control.8.gz

Provided by: nsd_4.1.17-1build1_amd64 bug

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 logfile 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 connection to the port is refused), 1 on
              error, 0 if running.

       stats  Output a sequence of name=value lines with statistics information, 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 zonefile, 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 outdated).
              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 additions.

       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 supposed 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 frequent 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' command.

       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: 'master'  (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 statistics (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 success.

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.

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_control.pem).

SEE ALSO

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