unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-3.6)
Page:
Section:
Apropos / Subsearch:
optional field



NSUPDATE(8)                                           NSUPDATE(8)


NAME
       nsupdate - Dynamic DNS update utility

SYNOPSIS
       nsupdate  [ -d ]  [  [ -y keyname:secret ]  [ -k keyfile ]
       ]  [ -v ]  [ filename ]

DESCRIPTION
       nsupdate is used to submit Dynamic DNS Update requests  as
       defined in RFC2136 to a name server.  This allows resource
       records to be added or removed from a zone  without  manu-
       ally  editing  the zone file.  A single update request can
       contain requests to add or remove more than  one  resource
       record.

       Zones  that  are  under  dynamic control via nsupdate or a
       DHCP server should not be edited by  hand.   Manual  edits
       could  conflict  with dynamic updates and cause data to be
       lost.

       The resource records that are dynamically added or removed
       with  nsupdate  have to be in the same zone.  Requests are
       sent to the zone's master server.  This is  identified  by
       the MNAME field of the zone's SOA record.

       The  -d option makes nsupdate operate in debug mode.  This
       provides tracing information  about  the  update  requests
       that  are  made  and  the  replies  received from the name
       server.

       Transaction signatures can be  used  to  authenticate  the
       Dynamic  DNS  updates.  These use the TSIG resource record
       type described in  RFC2845.   The  signatures  rely  on  a
       shared  secret  that  should only be known to nsupdate and
       the name server.  Currently, the only supported encryption
       algorithm  for  TSIG  is HMAC-MD5, which is defined in RFC
       2104.  Once other algorithms are defined for TSIG,  appli-
       cations  will  need  to ensure they select the appropriate
       algorithm as well as  the  key  when  authenticating  each
       other.   For  instance  suitable key and server statements
       would be added to /etc/named.conf so that the name  server
       can  associate  the  appropriate  secret key and algorithm
       with the IP address of the client application that will be
       using   TSIG   authentication.   nsupdate  does  not  read
       /etc/named.conf.

       nsupdate uses the -y or -k option to  provide  the  shared
       secret needed to generate a TSIG record for authenticating
       Dynamic DNS update requests.  These options  are  mutually
       exclusive.   With the -k option, nsupdate reads the shared
       secret from the file keyfile, whose name is  of  the  form
       K{name}.+157.+{random}.private.   For  historical reasons,
       the file K{name}.+157.+{random}.key must also be  present.
       When  the -y option is used, a signature is generated from



BIND9                      Jun 30, 2000                         1





NSUPDATE(8)                                           NSUPDATE(8)


       keyname:secret.  keyname is  the  name  of  the  key,  and
       secret is the base64 encoded shared secret.  Use of the -y
       option is discouraged because the shared  secret  is  sup-
       plied  as a command line argument in clear text.  This may
       be visible in the output from ps(1) or in a  history  file
       maintained by the user's shell.

       By  default  nsupdate  uses UDP to send update requests to
       the name server.  The -v option makes nsupdate use  a  TCP
       connection.  This may be preferable when a batch of update
       requests is made.

INPUT FORMAT
       nsupdate reads input  from  filename  or  standard  input.
       Each  command  is  supplied  on exactly one line of input.
       Some commands are for administrative purposes.  The others
       are  either  update instructions or prerequisite checks on
       the contents of the zone.   These  checks  set  conditions
       that  some  name or set of resource records (RRset) either
       exists or is absent from the zone.  These conditions  must
       be  met  if  the  entire  update  request  is  to succeed.
       Updates will be rejected if the tests for the prerequisite
       conditions fail.

       Every  update  request  consists of zero or more prerequi-
       sites and zero or more updates.  This  allows  a  suitably
       authenticated  update request to proceed if some specified
       resource records are present or missing from the zone.   A
       blank  input line (or the send command) causes the accumu-
       lated commands to  be  sent  as  one  Dynamic  DNS  update
       request to the name server.

       The command formats and their meaning are as follows:

       server servername [ port ]
              Sends  all  dynamic  update  requests  to  the name
              server servername.  When  no  server  statement  is
              provided,  nsupdate will send updates to the master
              server of the correct zone.   The  MNAME  field  of
              that  zone's  SOA  record  will identify the master
              server for that zone.  port is the port  number  on
              servername  where  the  dynamic update requests get
              sent.  If no port number is specified, the  default
              DNS port number of 53 is used.

       local address [ port ]
              Sends  all  dynamic update requests using the local
              address.  When  no  local  statement  is  provided,
              nsupdate  will  send  updates  using an address and
              port chosen by the system.  port  can  additionally
              be used to make requests come from a specific port.
              If no port number is  specified,  the  system  will
              assign one.




BIND9                      Jun 30, 2000                         2





NSUPDATE(8)                                           NSUPDATE(8)


       zone zonename
              Specifies  that  all  updates are to be made to the
              zone zonename.  If no zone statement  is  provided,
              nsupdate will attempt determine the correct zone to
              update based on the rest of the input.

       key name secret
              Specifies that all updates are to  be  TSIG  signed
              using  the keyname keysecret pair.  The key command
              overrides any key specified on the command line via
              -y or -k.

       prereq nxdomain domain-name
              Requires that no resource record of any type exists
              with name domain-name.

       prereq yxdomain domain-name
              Requires that domain-name exists (has as  at  least
              one resource record, of any type).

       prereq nxrrset domain-name [ class ]  type
              Requires  that  no  resource  record  exists of the
              specified type, class and domain-name.  If class is
              omitted, IN (internet) is assumed.

       prereq yxrrset domain-name [ class ]  type
              This  requires that a resource record of the speci-
              fied type, class and domain-name  must  exist.   If
              class is omitted, IN (internet) is assumed.

       prereq yxrrset domain-name [ class ]  type data...
              The  data  from  each  set of prerequisites of this
              form sharing a common type, class, and  domain-name
              are  combined to form a set of RRs. This set of RRs
              must exactly match the set of RRs existing  in  the
              zone  at  the  given  type, class, and domain-name.
              The data are written in the standard text represen-
              tation of the resource record's RDATA.

       update delete domain-name [ ttl ]  [ class ]  [ type  [
       data... ] ]
              Deletes any resource records named domain-name.  If
              type and data is provided, only  matching  resource
              records  will  be  removed.   The internet class is
              assumed if  class  is  not  supplied.  The  ttl  is
              ignored, and is only allowed for compatibility.

       update add domain-name ttl [ class ]  type data...
              Adds  a new resource record with the specified ttl,
              class and data.

       show   Displays the current message, containing all of the
              prerequisites  and updates specified since the last
              send.



BIND9                      Jun 30, 2000                         3





NSUPDATE(8)                                           NSUPDATE(8)


       send   Sends the current message. This  is  equivalent  to
              entering a blank line.

       Lines  beginning  with  a  semicolon are comments, and are
       ignored.

EXAMPLES
       The examples below show how  nsupdate  could  be  used  to
       insert  and  delete  resource records from the example.com
       zone.  Notice that the input in each  example  contains  a
       trailing  blank  line so that a group of commands are sent
       as one dynamic update request to the  master  name  server
       for example.com.

       # nsupdate
       > update delete oldhost.example.com A
       > update add newhost.example.com 86400 A 172.16.1.1
       >


       Any A records for oldhost.example.com are deleted.  and an
       A record for newhost.example.com it IP address  172.16.1.1
       is  added.   The newly-added record has a 1 day TTL (86400
       seconds)

       # nsupdate
       > prereq nxdomain nickname.example.com
       > update add nickname.example.com 86400 CNAME somehost.example.com
       >


       The prerequisite condition gets the name server  to  check
       that  there  are no resource records of any type for nick-
       name.example.com.  If there are, the update request fails.
       If  this  name  does  not  exist, a CNAME for it is added.
       This ensures that when the CNAME is added, it cannot  con-
       flict  with  the long-standing rule in RFC1034 that a name
       must not exist as any other record type if it exists as  a
       CNAME.   (The  rule has been updated for DNSSEC in RFC2535
       to allow CNAMEs to have SIG, KEY and NXT records.)

FILES
       /etc/resolv.conf
              used to identify default name server

       K{name}.+157.+{random}.key
              base-64 encoding of HMAC-MD5 key created by dnssec-
              keygen(8).

       K{name}.+157.+{random}.private
              base-64 encoding of HMAC-MD5 key created by dnssec-
              keygen(8).





BIND9                      Jun 30, 2000                         4





NSUPDATE(8)                                           NSUPDATE(8)


SEE ALSO
       RFC2136,  RFC3007,  RFC2104,  RFC2845,  RFC1034,  RFC2535,
       named(8), dnssec-keygen(8).

BUGS
       The  TSIG key is redundantly stored in two separate files.
       This is a consequence of nsupdate using  the  DST  library
       for its cryptographic operations, and may change in future
       releases.
















































BIND9                      Jun 30, 2000                         5