nsd-control(8) nsd 4.8.0 nsd-control(8)

nsd-control(8) nsd 4.8.0 nsd-control(8) #

nsd-control(8) nsd 4.8.0 nsd-control(8)

NNAAMMEE #

 nnssdd--ccoonnttrrooll,, nnssdd--ccoonnttrrooll--sseettuupp - NSD remote server control utility.

SSYYNNOOPPSSIISS #

 nnssdd--ccoonnttrrooll [--cc _c_f_g_f_i_l_e] [--ss _s_e_r_v_e_r] _c_o_m_m_a_n_d

DDEESSCCRRIIPPTTIIOONN #

 nnssdd--ccoonnttrrooll performs remote administration on the _n_s_d(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:

 --hh     Show the version and commandline option help.

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

 --ss _s_e_r_v_e_r_[_@_p_o_r_t_]
        IPv4 or IPv6 address of the server to contact.  If not given, the
        address is read from the config file.

CCOOMMMMAANNDDSS #

 There are several commands that the server understands.

 ssttaarrtt  Start the server. Simply execs _n_s_d(8).  The nsd executable is not
        searched for in the PPAATTHH set in the environment.  Instead the
        default location relative to the installation prefix specified at
        compile-time.  The executable location can be overridden by
        setting _N_S_D___P_A_T_H in the environment.  It is started with the
        config file specified using _-_c or the default config file.

 ssttoopp   Stop the server. The server daemon exits.

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

 rreeccoonnffiigg
        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, also per-zone statistics
        are not applied.  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.

 rreeppaatttteerrnn
        Same as the reconfig option.

 lloogg__rreeooppeenn
        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).

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

 ssttaattss  Output a sequence of name=value lines with statistics information,
        requires NSD to be compiled with this option enabled.

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

 aaddddzzoonnee <<zzoonnee nnaammee>> <<ppaatttteerrnn nnaammee>>
        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.

 ddeellzzoonnee <<zzoonnee nnaammee>>
        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.

 cchhaannggeezzoonnee <<zzoonnee nnaammee>> <<ppaatttteerrnn nnaammee>>
        Change a zone to use the pattern for options.  The zone is deleted
        and added in one operation, changing it to use the new pattern for
        the zone options.  Zones configured in nsd.conf cannot be changed
        like this, instead edit the nsd.conf (or the included file in
        nsd.conf) and reconfig.

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

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

 wwrriittee [[<<zzoonnee>>]]
        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. With
        argument that zone is written if it was modified, without
        argument, all modified zones are written.

 nnoottiiffyy [[<<zzoonnee>>]]
        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.
        With argument that zone is processed, without argument, all zones
        are processed.

 ttrraannssffeerr [[<<zzoonnee>>]]
        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. With argument that zone is transferred, without
        argument, all zones are transferred.

 ffoorrccee__ttrraannssffeerr [[<<zzoonnee>>]]
        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. With
        argument that zone is transferred, without argument, all zones are
        transferred.

 zzoonneessttaattuuss [[<<zzoonnee>>]]
        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. With argument that
        zone is printed, without argument, all zones are printed.

 sseerrvveerrppiidd
        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.

 vveerrbboossiittyy <<nnuummbbeerr>>
        Change logging verbosity.

 pprriinntt__ttssiigg [[<<kkeeyy__nnaammee>>]]
        print the secret and algorithm for the TSIG key with that name.
        Or list all the tsig keys with their name, secret and algorithm.

 uuppddaattee__ttssiigg <<nnaammee>> <<sseeccrreett>>
        Change existing TSIG key with name to the new secret.  The secret
        is a base64 encoded string.  The changes are only in-memory and
        are gone next restart, for lasting changes edit the nsd.conf file
        or a file included from it.

 aadddd__ttssiigg <<nnaammee>> <<sseeccrreett>> [[aallggoo]]
        Add a new TSIG key with the given name, secret and algorithm.
        Without algorithm a default (hmac-sha256) algorithm is used.  The
        secret is a base64 encoded string.  The changes are only in-memory
        and are gone next restart, for lasting changes edit the nsd.conf
        file or a file included from it.

 aassssoocc__ttssiigg <<zzoonnee>> <<kkeeyy__nnaammee>>
        Associate the zone with the given tsig.  The access control lists
        for notify, allow-notify, provide-xfr and request-xfr are adjusted
        to use the given key.

 ddeell__ttssiigg <<kkeeyy__nnaammee>>
        Delete the TSIG key with the given name.  Prints error if the key
        is still in use by some zone.  The changes are only in-memory and
        are gone next restart, for lasting changes edit the nsd.conf file
        or a file included from it.

 aadddd__ccooookkiiee__sseeccrreett <<sseeccrreett>>
        Add or replace a cookie secret persistently. <secret> needs to be
        an 128 bit hex string.

        Cookie secrets can be either _a_c_t_i_v_e or _s_t_a_g_i_n_g. _A_c_t_i_v_e cookie
        secrets are used to create DNS Cookies, but verification of a DNS
        Cookie succeeds with any of the _a_c_t_i_v_e or _s_t_a_g_i_n_g cookie secrets.
        The state of the current cookie secrets can be printed with the
        pprriinntt__ccooookkiiee__sseeccrreettss command.

        When there are no cookie secrets configured yet, the <secret> is
        added as _a_c_t_i_v_e. If there is already an _a_c_t_i_v_e cookie secret, the
        <secret> is added as _s_t_a_g_i_n_g or replacing an existing _s_t_a_g_i_n_g
        secret.

        To "roll" a cookie secret used in an anycast set. The new secret
        has to be added as staging secret to aallll nodes in the anycast set.
        When aallll nodes can verify DNS Cookies with the new secret, the new
        secret can be activated with the aaccttiivvaattee__ccooookkiiee__sseeccrreett command.
        After aallll nodes have the new secret _a_c_t_i_v_e for at least one hour,
        the previous secret can be dropped with the ddrroopp__ccooookkiiee__sseeccrreett
        command.

        Persistence is accomplished by writing to a file which if
        configured with the ccooookkiiee--sseeccrreett--ffiillee option in the server
        section of the config file.  The default value for that is:
        /var/nsd/etc/nsd_cookiesecrets.txt .

 ddrroopp__ccooookkiiee__sseeccrreett
        Drop the _s_t_a_g_i_n_g cookie secret.

 aaccttiivvaattee__ccooookkiiee__sseeccrreett
        Make the current _s_t_a_g_i_n_g cookie secret _a_c_t_i_v_e, and the current
        _a_c_t_i_v_e cookie secret _s_t_a_g_i_n_g.

 pprriinntt__ccooookkiiee__sseeccrreettss
        Show the current configured cookie secrets with their status.

EEXXIITT CCOODDEE #

 The nsd-control program exits with status code 1 on error, 0 on success.

SSEETT UUPP #

 The setup requires a self-signed certificate and private keys for both
 the server and client.  The script _n_s_d_-_c_o_n_t_r_o_l_-_s_e_t_u_p 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 running
 the script as root, turn on ccoonnttrrooll--eennaabbllee in _n_s_d_._c_o_n_f.

SSTTAATTIISSTTIICC CCOOUUNNTTEERRSS #

 The _s_t_a_t_s command shows a number of statistic counters.

 _n_u_m_._q_u_e_r_i_e_s
        number of queries received (the tls, tcp and udp queries added
        up).

 _s_e_r_v_e_r_X_._q_u_e_r_i_e_s
        number of queries handled by the server process.  The number of
        server processes is set with the config statement sseerrvveerr--ccoouunntt.

 _t_i_m_e_._b_o_o_t
        uptime in seconds since the server was started.  With fractional
        seconds.

 _t_i_m_e_._e_l_a_p_s_e_d
        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.

 _s_i_z_e_._d_b_._d_i_s_k
        size of nsd.db on disk, in bytes.

 _s_i_z_e_._d_b_._m_e_m
        size of the DNS database in memory, in bytes.

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

 _s_i_z_e_._c_o_n_f_i_g_._d_i_s_k
        size of zonelist file on disk, excludes the nsd.conf size, in
        bytes.

 _s_i_z_e_._c_o_n_f_i_g_._m_e_m
        size of config data in memory, kept twice in server and xfrd
        process, in bytes.

 _n_u_m_._t_y_p_e_._X
        number of queries with this query type.

 _n_u_m_._o_p_c_o_d_e_._X
        number of queries with this opcode.

 _n_u_m_._c_l_a_s_s_._X
        number of queries with this query class.

 _n_u_m_._r_c_o_d_e_._X
        number of answers that carried this return code.

 _n_u_m_._e_d_n_s
        number of queries with EDNS OPT.

 _n_u_m_._e_d_n_s_e_r_r
        number of queries which failed EDNS parse.

 _n_u_m_._u_d_p
        number of queries over UDP ip4.

 _n_u_m_._u_d_p_6
        number of queries over UDP ip6.

 _n_u_m_._t_c_p
        number of connections over TCP ip4.

 _n_u_m_._t_c_p_6
        number of connections over TCP ip6.

 _n_u_m_._t_l_s
        number of connections over TLS ip4.  TLS queries are not part of
        num.tcp.

 _n_u_m_._t_l_s_6
        number of connections over TLS ip6.  TLS queries are not part of
        num.tcp6.

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

 _n_u_m_._r_x_e_r_r
        number of queries for which the receive failed.

 _n_u_m_._t_x_e_r_r
        number of answers for which the transmit failed.

 _n_u_m_._r_a_x_f_r
        number of AXFR requests from clients (that got served with reply).

 _n_u_m_._r_i_x_f_r
        number of IXFR requests from clients (that got served with reply).

 _n_u_m_._t_r_u_n_c_a_t_e_d
        number of answers with TC flag set.

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

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

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

FFIILLEESS #

 _/_v_a_r_/_n_s_d_/_e_t_c_/_n_s_d_._c_o_n_f
        nsd configuration file.

 _/_v_a_r_/_n_s_d_/_e_t_c
        directory with private keys (nsd_server.key and nsd_control.key)
        and self-signed certificates (nsd_server.pem and nsd_control.pem).

SSEEEE AALLSSOO #

 _n_s_d_._c_o_n_f(5), _n_s_d(8), _n_s_d_-_c_h_e_c_k_c_o_n_f(8)

NLnet Labs December 6, 2023 nsd-control(8)