342 lines
9.8 KiB
Groff
342 lines
9.8 KiB
Groff
.\"
|
|
.\" Copyright (C) 2000, 2001 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.
|
|
.\"
|
|
.TH "NSUPDATE" "8" "Jun 30, 2000" "BIND9" ""
|
|
.SH NAME
|
|
nsupdate \- Dynamic DNS update utility
|
|
.SH SYNOPSIS
|
|
.sp
|
|
\fBnsupdate\fR [ \fB-d\fR ] [ \fB [ -y \fIkeyname:secret\fB ] [ -k \fIkeyfile\fB ] \fR ] [ \fB-v\fR ] [ \fBfilename\fR ]
|
|
.SH "DESCRIPTION"
|
|
.PP
|
|
\fBnsupdate\fR
|
|
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
|
|
\fBnsupdate\fR
|
|
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
|
|
\fBnsupdate\fR
|
|
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
|
|
\fB-d\fR
|
|
option makes
|
|
\fBnsupdate\fR
|
|
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
|
|
\fBnsupdate\fR
|
|
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
|
|
\fBkey\fR
|
|
and
|
|
\fBserver\fR
|
|
statements would be added to
|
|
\fI/etc/named.conf\fR
|
|
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.
|
|
\fBnsupdate\fR
|
|
does not read
|
|
\fI/etc/named.conf\fR.
|
|
.PP
|
|
\fBnsupdate\fR
|
|
uses the
|
|
\fB-y\fR
|
|
or
|
|
\fB-k\fR
|
|
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
|
|
\fB-k\fR
|
|
option,
|
|
\fBnsupdate\fR
|
|
reads the shared secret from the file
|
|
\fIkeyfile\fR,
|
|
whose name is of the form
|
|
\fIK{name}.+157.+{random}.private\fR.
|
|
For historical
|
|
reasons, the file
|
|
\fIK{name}.+157.+{random}.key\fR
|
|
must also be present. When the
|
|
\fB-y\fR
|
|
option is used, a signature is generated from
|
|
\fIkeyname:secret.\fR
|
|
\fIkeyname\fR
|
|
is the name of the key,
|
|
and
|
|
\fIsecret\fR
|
|
is the base64 encoded shared secret.
|
|
Use of the
|
|
\fB-y\fR
|
|
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
|
|
\fBps\fR(1)
|
|
or in a history file maintained by the user's shell.
|
|
.PP
|
|
By default
|
|
\fBnsupdate\fR
|
|
uses UDP to send update requests to the name server.
|
|
The
|
|
\fB-v\fR
|
|
option makes
|
|
\fBnsupdate\fR
|
|
use a TCP connection.
|
|
This may be preferable when a batch of update requests is made.
|
|
.SH "INPUT FORMAT"
|
|
.PP
|
|
\fBnsupdate\fR
|
|
reads input from
|
|
\fIfilename\fR
|
|
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.
|
|
.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 (or the \fBsend\fR command) 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:
|
|
.TP
|
|
\fBserver servername [ port ]\fR
|
|
Sends all dynamic update requests to the name server
|
|
\fIservername\fR.
|
|
When no server statement is provided,
|
|
\fBnsupdate\fR
|
|
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.
|
|
\fIport\fR
|
|
is the port number on
|
|
\fIservername\fR
|
|
where the dynamic update requests get sent.
|
|
If no port number is specified, the default DNS port number of 53 is
|
|
used.
|
|
.TP
|
|
\fBlocal address [ port ]\fR
|
|
Sends all dynamic update requests using the local
|
|
\fIaddress\fR.
|
|
When no local statement is provided,
|
|
\fBnsupdate\fR
|
|
will send updates using an address and port choosen by the system.
|
|
\fIport\fR
|
|
can additionally be used to make requests come from a specific port.
|
|
If no port number is specified, the system will assign one.
|
|
.TP
|
|
\fBzone zonename\fR
|
|
Specifies that all updates are to be made to the zone
|
|
\fIzonename\fR.
|
|
If no
|
|
\fIzone\fR
|
|
statement is provided,
|
|
\fBnsupdate\fR
|
|
will attempt determine the correct zone to update based on the rest of the input.
|
|
.TP
|
|
\fBkey name secret\fR
|
|
Specifies that all updates are to be TSIG signed using the
|
|
\fIkeyname\fR \fIkeysecret\fR pair.
|
|
The \fBkey\fR command
|
|
overrides any key specified on the command line via
|
|
\fB-y\fR or \fB-k\fR.
|
|
.TP
|
|
\fBprereq nxdomain domain-name\fR
|
|
Requires that no resource record of any type exists with name
|
|
\fIdomain-name\fR.
|
|
.TP
|
|
\fBprereq yxdomain domain-name\fR
|
|
Requires that
|
|
\fIdomain-name\fR
|
|
exists (has as at least one resource record, of any type).
|
|
.TP
|
|
\fBprereq nxrrset domain-name [ class ] type\fR
|
|
Requires that no resource record exists of the specified
|
|
\fItype\fR,
|
|
\fIclass\fR
|
|
and
|
|
\fIdomain-name\fR.
|
|
If
|
|
\fIclass\fR
|
|
is omitted, IN (internet) is assumed.
|
|
.TP
|
|
\fBprereq yxrrset domain-name [ class ] type\fR
|
|
This requires that a resource record of the specified
|
|
\fItype\fR,
|
|
\fIclass\fR
|
|
and
|
|
\fIdomain-name\fR
|
|
must exist.
|
|
If
|
|
\fIclass\fR
|
|
is omitted, IN (internet) is assumed.
|
|
.TP
|
|
\fBprereq yxrrset domain-name [ class ] type data\fI...\fB\fR
|
|
The
|
|
\fIdata\fR
|
|
from each set of prerequisites of this form
|
|
sharing a common
|
|
\fItype\fR,
|
|
\fIclass\fR,
|
|
and
|
|
\fIdomain-name\fR
|
|
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
|
|
\fItype\fR,
|
|
\fIclass\fR,
|
|
and
|
|
\fIdomain-name\fR.
|
|
The
|
|
\fIdata\fR
|
|
are written in the standard text representation of the resource record's
|
|
RDATA.
|
|
.TP
|
|
\fBupdate delete domain-name [ ttl ] [ class ] [ type [ data\fI...\fB ] ]\fR
|
|
Deletes any resource records named
|
|
\fIdomain-name\fR.
|
|
If
|
|
\fItype\fR
|
|
and
|
|
\fIdata\fR
|
|
is provided, only matching resource records will be removed.
|
|
The internet class is assumed if
|
|
\fIclass\fR
|
|
is not supplied. The
|
|
\fIttl\fR
|
|
is ignored, and is only allowed for compatibility.
|
|
.TP
|
|
\fBupdate add domain-name ttl [ class ] type data\fI...\fB\fR
|
|
Adds a new resource record with the specified
|
|
\fIttl\fR,
|
|
\fIclass\fR
|
|
and
|
|
\fIdata\fR.
|
|
.TP
|
|
\fBshow\fR
|
|
Displays the current message, containing all of the prerequisites and
|
|
updates specified since the last send.
|
|
.TP
|
|
\fBsend\fR
|
|
Sends the current message. This is equivalent to entering a blank line.
|
|
.PP
|
|
Lines beginning with a semicolon are comments, and are ignored.
|
|
.SH "EXAMPLES"
|
|
.PP
|
|
The examples below show how
|
|
\fBnsupdate\fR
|
|
could be used to insert and delete resource records from the
|
|
\fBexample.com\fR
|
|
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
|
|
\fBexample.com\fR.
|
|
.sp
|
|
.nf
|
|
# nsupdate
|
|
> update delete oldhost.example.com A
|
|
> update add newhost.example.com 86400 A 172.16.1.1
|
|
>
|
|
.sp
|
|
.fi
|
|
.PP
|
|
Any A records for
|
|
\fBoldhost.example.com\fR
|
|
are deleted.
|
|
and an A record for
|
|
\fBnewhost.example.com\fR
|
|
it IP address 172.16.1.1 is added.
|
|
The newly-added record has a 1 day TTL (86400 seconds)
|
|
.sp
|
|
.nf
|
|
# nsupdate
|
|
> prereq nxdomain nickname.example.com
|
|
> update add nickname.example.com CNAME somehost.example.com
|
|
>
|
|
.sp
|
|
.fi
|
|
.PP
|
|
The prerequisite condition gets the name server to check that there
|
|
are no resource records of any type for
|
|
\fBnickname.example.com\fR.
|
|
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.)
|
|
.SH "FILES"
|
|
.TP
|
|
\fB/etc/resolv.conf\fR
|
|
used to identify default name server
|
|
.TP
|
|
\fBK{name}.+157.+{random}.key\fR
|
|
base-64 encoding of HMAC-MD5 key created by
|
|
\fBdnssec-keygen\fR(8).
|
|
.TP
|
|
\fBK{name}.+157.+{random}.private\fR
|
|
base-64 encoding of HMAC-MD5 key created by
|
|
\fBdnssec-keygen\fR(8).
|
|
.SH "SEE ALSO"
|
|
.PP
|
|
\fBRFC2136\fR,
|
|
\fBRFC3007\fR,
|
|
\fBRFC2104\fR,
|
|
\fBRFC2845\fR,
|
|
\fBRFC1034\fR,
|
|
\fBRFC2535\fR,
|
|
\fBnamed\fR(8),
|
|
\fBdnssec-keygen\fR(8).
|
|
.SH "BUGS"
|
|
.PP
|
|
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.
|