This commit was manufactured by cvs2git to create tag 'v9_0_0rc3'.

doc/man/bin/nsupdate.8

@@ -0,0 +1,340 @@
+.\" Copyright (C) 2000  Internet Software Consortium.
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND INTERNET SOFTWARE CONSORTIUM
+.\" DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL
+.\" INTERNET SOFTWARE CONSORTIUM BE LIABLE FOR ANY SPECIAL, DIRECT,
+.\" INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
+.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
+.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
+.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.\" $Id: nsupdate.8,v 1.7 2000/08/15 20:15:49 gson Exp $
+.\"
+.Dd Jun 30, 2000
+.Dt NSUPDATE 8
+.Os BIND9 9
+.ds vT BIND9 Programmer's Manual
+.Sh NAME
+.Nm nsupdate
+.Nd Dynamic DNS update utility
+.Sh SYNOPSIS
+.Nm nsupdate
+.Op Fl d
+.Oo
+.Fl y Ar keyname:secret |
+.Fl k Ar keyfile
+.Oc
+.Op Fl v
+.Sh DESCRIPTION
+.Nm 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 manually editing the zone file.
+A single update request can contain requests to add or remove more than one
+resource record.
+.Pp
+Zones that are under dynamic control via
+.Nm nsupdate
+or a DHCP server should not be edited by hand.
+Manual edits could
+conflict with dynamic updates and cause data to be lost.
+.Pp
+The resource records that are dynamically added or removed with
+.Nm 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.
+.Pp
+The
+.Fl d
+option makes
+.Nm nsupdate
+operate in debug mode.
+This provides tracing information about the update requests that are
+made and the replies received from the name server.
+.Pp
+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
+.Nm 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, applications will need to
+ensure they select the appropriate algorithm as well as the key when
+authenticating each other.
+For instance suitable
+.Dv key{}
+and
+.Dv server{}
+statements would be added to
+.Pa /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.
+.Nm nsupdate
+does not read
+.Pa /etc/named.conf .
+.Pp
+.Nm nsupdate
+uses the
+.Fl y
+or
+.Fl 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
+.Fl k
+option,
+.Nm nsupdate
+reads the shared secret from the file
+.Ar keyfile ,
+whose name is of the form 
+.Pa K{name}.+157.+{random}.private .
+For historical
+reasons, the file 
+.Pa K{name}.+157.+{random}.key
+must also be present.  When the
+.Fl y
+option is used, a signature is generated from
+.Ar keyname:secret.
+.Ar keyname
+is the name of the key,
+and
+.Ar secret
+is the base64 encoded shared secret.
+Use of the
+.Fl y
+option is discouraged because the shared secret is supplied as a command
+line argument in clear text.
+This may be visible in the output from
+.Xr ps 1
+or in a history file maintained by the user's shell.
+.Pp
+By default
+.Nm nsupdate
+uses UDP to send update requests to the name server.
+The
+.Fl v
+option makes
+.Nm nsupdate
+use a TCP connection.
+This may be preferable when a batch of update requests is made.
+.Sh INPUT FORMAT
+.Nm nsupdate
+reads commands from its 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.
+.Pp
+Every update request consists of zero or more prerequisites
+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 causes the accumulated commands to be sent as one Dynamic
+DNS update request to the name server.
+.Pp
+The command formats and their meaning are as follows:
+.Bl -ohang indent
+.It Xo
+.Ic server Va servername Op port
+.Xc
+.sp 1
+Sends all dynamic update requests to the name server
+.Va servername .
+When no server statement is provided,
+.Nm 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.
+.Va port
+is the port number on
+.Va servername
+where the dynamic update requests get sent.
+If no port number is specified, the default DNS port number of 53 is
+used.
+.It Xo
+.Ic zone Va zonename
+.Xc
+.sp 1
+Specifies that all updates are to be made to the zone
+.Va zonename .
+If no
+.Va zone
+statement is provided,
+.Nm nsupdate
+will attempt determine the correct zone to update based on the rest of the input.
+.It Xo
+.Ic prereq nxdomain Va domain-name
+.Xc
+.sp 1
+Requires that no resource record of any type exists with name
+.Va domain-name .
+.It Xo
+.Ic prereq yxdomain Va domain-name
+.Xc
+.sp 1
+Requires that
+.Va domain-name
+exists (has as at least one resource record, of any type).
+.It Xo
+.Ic prereq nxrrset Va domain-name Op class
+.Va type
+.Xc
+.sp 1
+Requires that no resource record exists of the specified
+.Va type ,
+.Va class
+and
+.Va domain-name .
+If
+.Va class
+is omitted, IN (internet) is assumed.
+.It Xo
+.Ic prereq yxrrset
+.Va domain-name Op class
+.Va type
+.Xc
+.sp 1
+This requires that a resource record of the specified
+.Va type ,
+.Va class
+and
+.Va domain-name
+must exist.
+If
+.Va class
+is omitted, IN (internet) is assumed.
+.It Xo
+.Ic prereq yxrrset
+.Va domain-name Op class
+.Va type data...
+.Xc
+.sp 1
+The
+.Va data
+from each set of prerequisites of this form
+sharing a common
+.Va type ,
+.Va class ,
+and 
+.Va 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 
+.Va type ,
+.Va class ,
+and 
+.Va domain-name .
+The
+.Va data
+are written in the standard text representation of the resource record's
+RDATA.
+.It Xo
+.Ic update delete
+.Va domain-name Op class
+.Va Op type Op data...
+.Xc
+.sp 1
+Deletes any resource records named
+.Va domain-name .
+If
+.Va type
+and
+.Va data
+is provided, only matching resource records will be removed.
+The internet class is assumed if
+.Va class
+is not supplied.
+.It Xo
+.Ic update add
+.Va domain-name ttl Op class
+.Va type data..
+.Xc
+.sp 1
+Adds a new resource record with the specified
+.Va ttl ,
+.Va class
+and
+.Va data .
+.El
+.Sh EXAMPLES
+The examples below show how
+.Nm nsupdate
+could be used to insert and delete resource records from the
+.Dv 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
+.Dv example.com .
+.Bd -literal -offset indent
+# nsupdate
+> update delete oldhost.example.com A
+> update add newhost.example.com 86400 A 172.16.1.1
+>
+.Ed
+.Pp
+Any A records for
+.Dv oldhost.example.com
+are deleted.
+and an A record for
+.Dv newhost.example.com
+it IP address 172.16.1.1 is added.
+The newly-added record has a 1 day TTL (86400 seconds)
+.Bd -literal -offset indent
+# nsupdate
+> prereq nxdomain nickname.example.com
+> update add nickname.example.com CNAME somehost.example.com
+>
+.Ed
+.Pp
+The prerequisite condition gets the name server to check that there
+are no resource records of any type for
+.Dv nickname.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 conflict 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.)
+.Pp
+.Sh FILES
+.Bl -tag -width K{name}.+157.+{random}.private -compact
+.It Pa /etc/resolv.conf
+used to identify default name server
+.It Pa K{name}.+157.+{random}.key
+base-64 encoding of HMAC-MD5 key created by
+.Xr dnssec-keygen 8 .
+.It Pa K{name}.+157.+{random}.private
+base-64 encoding of HMAC-MD5 key created by
+.Xr dnssec-keygen 8 .
+.El
+.Sh SEE ALSO
+.Xr RFC2136 ,
+.Xr RFC2137 ,
+.Xr RFC2104 ,
+.Xr RFC2845 ,
+.Xr RFC1034 ,
+.Xr RFC2535 ,
+.Xr named 8 ,
+.Xr dnssec-keygen 8 .
+.Sh 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.