NetBSD/dist/bind/man/nsupdate.8

.\"     $NetBSD: nsupdate.8,v 1.5 2001/06/05 12:49:36 wiz Exp $
.\"
.\" Id: nsupdate.8,v 8.6 2000/10/30 23:06:57 cyarnell Exp
.\"
.\"Copyright (c) 1999 by 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.
.Dd March 5, 1999
.Dt NSUPDATE 8
.Os
.Sh NAME
.Nm nsupdate 
.Nd update Internet name servers interactively
.Sh SYNOPSIS
.Nm nsupdate
.Op Fl Ar k  keydir:keyname 
.Op Fl Ar d
.Op Fl Ar v
.Op Ar filename
.Sh DESCRIPTION
.Ic Nsupdate
is a program to update Internet domain name servers
supporting dynamic update.
.Ic Nsupdate
uses the DNS resolver library to pass messages
to a DNS server requesting the additional or deletion of
DNS resource records (RRs).
.Ic Nsupdate
reads input from
.Ar filename
or standard input.
.Sh ARGUMENTS
.Bl -tag -width Fl
.It Fl k
Sign updates with TSIG.
.It Fl d
Debug mode.
.It Fl v
Virtual circuit - use TCP to communication with server.
Default is UDP.
.El
.Sh INPUT FORMAT
.Ic Nsupdate
reads input records, one per line,
each line contributing a resource record to an
update request.
All domain names used in a single update request
must belong to the same DNS zone.
Updates are sent to the master server as defined in the SOA
MNAME field.
A blank line causes the accumulated
records to be formated into a single update request
and transmitted to the zone's authoritative name servers.
Additional records may follow,
which are formed into additional,
completely independent update requests.
For the last request to be transmitted, a blank line
must end the input.
.Pp
Records take one of two general forms.
.Em Prerequisite
records specify conditions that must be satisfied before
the request will be processed.
.Em Update
records specify changes to be made to the DNS database.
A update request consists of zero or more prerequisites
and one or more updates.
Each update request is processed atomically -
all prerequisites must be satisfied, then all updates
will be performed.
.Pp
.Ic Nsupdate
understands the following input record formats:
.Pp

.Bl -hang

.It Ic prereq nxdomain Va domain-name
Requires that no RR of any type exists with name
.Va domain-name .

.It Ic prereq yxdomain Va domain-name
Requires that at least one RR named
.Va domain-name
must exist.

.It Xo
.Ic prereq nxrrset Va domain-name Op class
.Va type
.Xc
Requires that no RR exists of the specified
.Va type
and
.Va domain-name .

.It Xo
.Ic prereq yxrrset
.Va domain-name Op class
.Va type Op data...
.Xc
Requires that a RR exists of the specified
.Va type
and
.Va domain-name .
If
.Va data
is specified, it must match exactly.

.It Xo
.Ic update delete
.Va domain-name Op class
.Va Op type Op data...
.Xc
Deletes RRs named
.Va domain-name .
If
.Va type
(and possibly
.Va data )
is specified,
only matching records will be deleted.

.It Xo
.Ic update add
.Va domain-name ttl Op class
.Va type data...
.Xc
Adds a new RR with specified
.Va ttl , type ,
and
.Va data .

.El

.Sh EXAMPLES
The following example illustrates the interactive use of
.Ic nsupdate
to change an IP address by deleting any existing A records
for a domain name and then inserting a new one.
Since no prerequisites are specified,
the new record will be added even if
there were no existing records to delete.
Note the
trailing blank line, required to process the request.
.Bd -literal -offset indent
$ nsupdate
> update delete test.example.com A
> update add test.example.com 3600 A 10.1.1.1
>

.Ed
.Pp
In this example, a CNAME alias is added to the database
only if there are no existing A or CNAME records for
the domain name.
.Bd -literal -offset indent
$ nsupdate
> prereq nxrrset www.example.com A
> prereq nxrrset www.example.com CNAME
> update add www.example.com 3600 CNAME test.example.com
>

.Ed
.Pp
In this example, the nsupdate will be signed with the key "mykey", which
is in the directory "/var/named/keys".
.Bd -literal -offset indent
$ nsupdate -k /var/named/keys:mykey
> update add ftp.example.com 60 A 192.168.5.1
>

.Ed

.Sh DIAGNOSTICS
.Bl -hang

.It Qq send error
Typically indicates that the authoritative nameservers could not be reached

.It Qq failed update packet
Typically indicates that the nameserver has rejected the update,
either because the nameserver doesn't support dynamic update,
or due to an authentication failure

.It Qq res_mkupdate: packet size = Va size
(and no other messages)
The update was successfully received and authenticated by the nameserver.
The prerequisites, however, may have prevented the update from actually
being performed.  The only way to determine if the update was performed
is to use debug mode
.Fl ( d )
and examine the status field in the nameserver's reply.
.El
.Sh FILES
.Bl -hang
.It Pa /etc/resolv.conf
.El
initial domain name and name server addresses
.Sh SEE ALSO
.Xr named 8 ,
.Xr resolver 3 , 
.Xr resolver 5 ;
RFC-1034,
.Dq Domain Names - Concepts and Facilities ;
RFC-1035,
.Dq Domain Names - Implementation and Specification ;
RFC-2136,
Dynamic Updates in the Domain Name System.
.Sh AUTHOR
Brent Baccala