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

doc/man/bin/host.1

+.\" 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: host.1,v 1.5 2000/08/22 17:02:49 gson Exp $
+.\"
+.Dd Jun 30, 2000
+.Dt HOST 1
+.Os BIND9 9
+.ds vT BIND9 Programmer's Manual
+.Sh NAME
+.Nm host
+.Nd DNS lookup utility
+.Sh SYNOPSIS
+.Nm host
+.Op Fl aCdlnrTwv
+.Op Fl c Ar class
+.Op Fl N Ar ndots
+.Op Fl R Ar number
+.Op Fl t Ar type
+.Op Fl W Ar wait
+.Ar name
+.Op Ar server
+.Sh DESCRIPTION
+.Nm host
+is a simple utility for performing DNS lookups.
+It is normally used to convert names to IP addresses and vice versa.
+When no arguments or options are given,
+.Nm host
+prints a short summary of its command line arguments and options.
+.Pp
+.Ar name
+is the domain name that is to be looked up.
+It can also be a dotted-decimal IPv4 address
+or a colon-delimited IPv6 address,
+in which case
+.Nm host
+will by default perform a reverse lookup for that address.
+.Ar server
+is an optional argument which is either the name or IP address of the
+name server that
+.Nm host
+should query instead of the server or servers listed in
+.Pa /etc/resolv.conf .
+.Pp
+The
+.Fl a
+(all) option is equivalent to setting the
+.Fl v
+option and asking
+.Nm host
+to make a query of type ANY.
+.Pp
+When the
+.Fl C
+option is used,
+.Nm host
+will attempt to display the SOA records for zone
+.Ar name
+from all the listed authoritative name servers for that zone.
+The list of name servers is defined by the NS records that are found for
+the zone.
+.Pp
+The
+.Fl c
+option instructs to make a DNS query of class
+.Ar class .
+This can be used to lookup Hesiod or Chaosnet class resource records.
+The default class is IN: Internet.
+.Pp
+Verbose output is generated by
+.Nm host
+when the
+.Fl d
+or
+.Fl v
+option is used.
+The two options are equivalent.
+They have been provided for backwards compatibility.
+In previous versions, the
+.Fl d
+option switched on debugging traces and
+.Fl v
+enabled verbose output.
+.Pp
+List mode is selected by the
+.Fl l
+option.
+This makes
+.Nm host
+perform a zone transfer for zone
+.Ar name .
+The argument is provided for compatibility with older implemementations.
+This option is equivalent to making a query of type AXFR.
+.Pp
+The
+.Fl n
+option specifies that reverse lookups of IPv6 addresses should
+use the IP6.INT domain and "nibble" labels as defined in RFC1886.
+The default is to use IP6.ARPA and binary labels as defined in RFC2874.
+.Pp
+The
+.Fl N
+option sets the number of dots that have to be in
+.Ar name
+for it to be considered absolute.  The default value is that
+defined using the ndots statement in
+.Pa /etc/resolv.conf ,
+or 1 if no ndots statement is present.  Names with fewer
+dots are interpreted as relative names and will be searched 
+for in the domains listed in the 
+.Dv search
+or
+.Dv domain
+directive in
+.Pa /etc/resolv.conf .
+.Pp
+The number of UDP retries for a lookup can be changed with the
+.Fl R
+option.
+.Ar number
+indicates how many times
+.Nm host
+will repeat a query that does not get answered.
+The default number of retries is 1.
+If
+.Ar number
+is negative or zero, the number of retries will default to 1.
+.Pp
+Non-recursive queries can be made via the
+.Fl r
+option.
+Setting this option clears the
+.Dv RD
+- recursion desired - bit in the query which
+.Nm host
+makes.
+This should mean that the name server receiving the query will not attempt
+to resolve
+.Ar name .
+The
+.Fl r
+option enables
+.Nm host
+to mimic the behaviour of a name server by making non-recursive queries
+and expecting to receive answers to those queries that are usually
+referrals to other name servers.
+.Pp
+By default
+.Nm host
+uses UDP when making queries.
+The
+.Fl T
+option makes it use a TCP connection when querying the name server.
+TCP will be automatically selected for queries that require it, 
+such as zone transfer (AXFR) requests.
+.Pp
+The
+.Fl t
+option is used to select the query type.
+.Ar type
+can be any recognised query type: CNAME, NS, SOA, SIG, KEY, AXFR, etc.
+When no query type is specified,
+.Nm host
+automatically selects an appropriate query type.
+By default it looks for A records, but if the
+.Fl C
+option was given, queries will be made for SOA records,
+and if
+.Ar name
+is a dotted-decimal IPv4 address or colon-delimited IPv6 address,
+.Nm host
+will query for PTR records.
+.Pp
+The time to wait for a reply can be controlled through the
+.Fl W
+and
+.Fl w
+options.
+The
+.Fl W
+option makes
+.Nm host
+wait for
+.Ar wait
+seconds.
+If
+.Ar wait
+is less than one,
+the wait interval is set to one second.
+When the
+.Fl w
+option is used,
+.Nm host
+will effectively wait forever for a reply.
+The time to wait for a response will be set to the number of seconds
+given by the hardware's maximum value for an integer quantity.
+.Sh FILES
+.Pa /etc/resolv.conf
+.Sh SEE ALSO
+.Xr dig 1 ,
+.Xr resolver 5
+.Xr named 8 .

doc/man/bin/nsupdate.8

+.\" 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.