nsupdate Command

Purpose

Updates a DNS server dynamically.

Syntax

Description

The nsupdate command submits Dynamic DNS Update requests, as defined in RFC 2136, to a name server. This command 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.

Zones that are dynamically controlled by using the nsupdate command or a DHCP server must not be edited manually. Manual edits might conflict with dynamic updates and cause data loss.

The resource records that are dynamically added or removed by using the nsupdate command must be in the same zone. Requests are sent to the primary server of the zone, which is identified by the MNAME field in the start of authority (SOA) record of the zone.

Transaction signatures (TSIG) can be used to authenticate the Dynamic DNS updates. The transaction signatures use the TSIG resource record type as described in RFC 2845, the SIG(0) record as described in RFC 2535 and RFC 2931, or GSS-TSIG as described in RFC 3645.

TSIG relies on a shared secret that must be known only to the nsupdate command and the name server. For instance, suitable key and server statements are added to the /etc/named.conf file so that the name server can associate the appropriate secret key and algorithm with the IP address of the client application that is using TSIG authentication. The ddns-confgen command can generate suitable configuration fragments. The nsupdate command uses the -y or -k options to specify the TSIG shared secret. These options are mutually exclusive.

The SIG(0) key uses public key cryptography. To use a SIG(0) key, the public key must be stored in a KEY record in a zone that is served by the name server. Generic Security Service Algorithm - Transaction Signature (GSS-TSIG) uses Kerberos credentials. Standard GSS-TSIG mode is enabled by using the -g flag.

Flags

-4

Indicates that only IPv4 must be used.

-6

Indicates that only IPv6 must be used.

-d

Sets a debug mode that provides tracing information about the update requests and the replies that are received from the name server.

-D

Sets extra debug mode.

-g

Enables the standard GSS-TSIG mode.

-i

Forces interactive mode, even when standard input is not a terminal.

-k keyfile

Indicates the file that contains the TSIG authentication key. Key files can be in the following formats:

A single file that contains a named.conf-format key statement, which can be generated automatically by the ddns-confgen command.
A pair of files whose names are of the format K{name}.+157.+{random}.key and K{name}.+157.+{random}.private, which can be generated by using the dnssec-keygen command.

You can also use the -k flag to specify a SIG(0) key that is used to authenticate dynamic DNS update requests. In this case, the specified key is not an HMAC-MD5 key.

-l

Sets a local-host only mode, which sets the server address to localhost (disabling the server so that the server address cannot be overridden). Connections to the local server use a TSIG key that is found in the /var/run/named/session.key file, which is automatically generated by the named daemon if any local primary zone has set the update-policy option to local. The location of this key file can be overridden by using the -k option.

-L level

Sets the debug logging level. If the value is zero, the logging operation is disabled.

-o

Enables a non-standards-compliant variant of GSS-TSIG used by Windows 2000.

-p port

Sets the port that must be used for connecting to a name server. The default value is 53.

-P

Prints the list of private BIND-specific resource record types whose format is identified by the nsupdate command. Also, see the -T option.

-r udpretries

Sets the number of User Datagram Protocol (UDP) retries. The default value is 3. If the value is zero, only one update request is processed.

-t timeout

Sets the maximum time that an update request can take before it is aborted. The default value is 300 seconds. If the value is zero, the timeout operation is disabled for the Transmission Control Protocol (TCP) mode. For UDP mode, the -u option takes precedence over the -t option, unless the -u option is set to zero. If the -u option is set to zero, the interval is computed from the value of timeout that is provided with the -t option and the number of UDP retries. For UDP mode, the timeout cannot be disabled, and is rounded up to 1 second in case if both -t and -u options are set to zero.

-T

Prints the list of Internet Assigned Numbers Authority (IANA) standard resource record types whose format is identified by the nsupdate command. The nsupdate command exits after the lists are printed. You can combine the -T option with the -P option.

Other types can be entered by using TYPEXXXXX where XXXXX is the decimal value of the type with no leading zeros. The rdata value, if present, is parsed by using the UNKNOWN rdata format. Th UNKNOWN rdata format is <backslash> <hash> <space> <length> <space> <hexstring>.

-u udptimeout

Sets the UDP retry interval. The default value is 3 seconds. If the value is zero, the interval is computed from the timeout interval and number of UDP retries.

-v

Specifies that TCP must be used even for small update requests. By default, the nsupdate command uses UDP to send update requests to the name server unless a UDP request cannot be used, in which case TCP is used. TCP is preferable when a batch of update requests is received.

-V

Prints the version number and exits.

-y [hmac:]keyname:secret

Sets the literal TSIG authentication key. The keyname is the name of the key, and secret is the Base64 encoded shared secret. The hmac argument is the name of the key algorithm. The following algorithms are the valid key algorithms:

hmac-md5
hmac-sha1
hmac-sha224
hmac-sha256
hmac-sha384
hmac-sha512

If the hmac option is not specified, the default value is hmac-md5, or if MD5 is disabled, the default value is hmac-sha256.

Note: Use the -y flag sparingly because the shared secret is specified as a command-line argument in clear text. The shared secret might be visible in the output from the ps1 prompt or in a history file that is maintained by the shell of the user.

Input format

The nsupdate command reads input from the specified filename or standard input. Each command is specified on exactly one line of input. Some commands are used for administrative purposes. Other commands are either update instructions or are used to perform prerequisite checks on the contents of the zone. These checks set conditions that some specific name or a set of resource records (RRset) either exists or is absent in the zone. These conditions must be met to complete the entire update request. Updates are rejected if the tests for the prerequisite conditions fail.

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

The following commands are included in the input file:

server servername port: This command sends all dynamic update requests to the name server servername. If a server statement is not specified, the nsupdate command sends updates to the primary server of the correct zone. The MNAME field of the SOA record of that zone identifies the primary server for that zone. The port is the port number on the server name where the dynamic update requests are sent. If a port number is not specified, the default DNS port number of 53 is used.
local address port: This command sends all dynamic update requests by using the local address. When a local statement is not specified, the nsupdate command sends updates by using an address and port that is chosen by the system. The port can also be used to force requests from a specific port. If a port number is not specified, the system assigns a port.
zone zonename: This command specifies that all updates must be made to the zone zonename. If a zone statement is not specified, the nsupdate command attempts to determine the correct zone to update based on the input.
class classname: This command specifies the default class. If a class is not specified, the default class is IN (Internet).
ttl seconds: This command specifies the default time-to-live (TTL), in seconds, for records that are added. The value none clears the default TTL.
key hmac:keyname secret: This command specifies that all updates must be TSIG-signed by using the keyname-secret pair. If hmac is specified, it sets the signing algorithm. The default value is hmac-md5. If MD5 is disabled, the default value is hmac-sha256. The key command overrides any key that is specified on the command line by using the -y or -k flag.
gsstsig: This command uses GSS-TSIG to sign the updates. This command is equivalent to specifying the -g flag on the command line.
oldgsstsig: This command uses the Windows 2000 version of GSS-TSIG to sign the updates. This command is equivalent to specifying the -o flag on the command line.
realm [realm_name]: When you use GSS-TSIG, this command specifies the realm_name parameter instead of the default realm in the krb5.conf file. If realm is not specified, the saved realm is cleared.
check-names [yes|no]: This command turns on or turns off check-names processing on records that are added. Check-names does not affect prerequisites or records that you want to delete. By default, check-names processing is turned on. If the check-names command fails to run, the record is not added to the UPDATE message.
prereq nxdomain domain-name: This command asserts a prerequisite that no resource record of any type exists with the name domain-name.
prereq yxdomain domain-name: This command asserts a prerequisite that the domain-name must exist (at least one resource record, of any type).
prereq nxrrset domain-name class type: This command requires that no resource record exist of the specified type, class, and domain-name. If class is omitted, IN (Internet) is assumed.
prereq yxrrset domain-name class type: This command requires that a resource record of the specified type, class, and domain-name exist. If class is omitted, IN is assumed.
prereq yxrrset domain-name class type data: By using this command, the data from each set of prerequisites of this form that shares 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 for the specified type, class, and domain-name. The data is written in the standard text representation of the resource record’s RDATA.
update delete domain-name ttl class type data: This command deletes any resource records named domain-name. If type and data are specified, matching resource records are removed. The IN class is assumed if class is not specified. The ttl is ignored, and it is only allowed for compatibility.
update add domain-name ttl class type data: This command adds a resource record with the specified TTL, class, and data.
show: This command displays the current message that contains all the prerequisites and updates that are specified since the last send operation.
send: This command sends the current message. This operation is equivalent to entering a blank line.
answer: This command displays the answer.
debug: This command turns on debugging.
version: This command prints the version number.
help: This command prints a list of commands.

Lines beginning with a semicolon (;) are comments and are ignored.

Examples

The following examples show the nsupdate command usage to insert and delete resource records from the example.com zone. The input in each example contains a trailing blank line so that a group of commands can be specified as one dynamic update request to the primary name server, example.com.

To delete resource records from an existing zone and to add a resource record to a new zone, enter the following command:
```
# nsupdate
> update delete oldhost.example.com A
> update add newhost.example.com 86400 A 172.16.1.1
> send
```
Any A records for oldhost.example.com are deleted, and an A record for newhost.example.com with IP address 172.16.1.1 is added. The new record has a TTL of 1 day (86400 seconds).
To specify a prerequisite condition before updating the DNS server, enter the following command:
```
# nsupdate
> prereq nxdomain nickname.example.com
> update add nickname.example.com 86400 CNAME somehost.example.com
> send
```
The prerequisite condition specifies the name server to verify that no resource records of any type exist for nickname.example.com. If the zone has resource records, the update request fails. If this name does not exist, a CNAME is added, which ensures that the prerequisite condition cannot conflict with the long-standing rule that is specified in RFC 1034. The rule that is specified in RFC 1034 states that a name must not exist as any other record type if it exists as a CNAME.
Note: The rule is updated for DNSSEC in RFC 2535 to allow CNAMEs to have RRSIG, DNSKEY, and NSEC resource records.

Files

/etc/resolv.conf: Used to identify the default name server.
/var/run/named/session.key: Sets the default TSIG key that must be used in local-only mode.
K{name}.+157.+{random}.key: Base-64 encoding of the HMAC-MD5 key created by the dnssec-keygen command.
K{name}.+157.+{random}.private: Base-64 encoding of the HMAC-MD5 key created by the dnssec-keygen command.