Run DNS Update (NSUPDATE)

The Run DNS Update (RUNDNSUPD) command, or its alias NSUPDATE, is used to submit Dynamic Updates requests to a Domain Name System (DNS) 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.

Zones that are under dynamic control via RUNDNSUPD or a DHCP server should not be edited by hand. Manual edits could conflict with dynamic updates and cause data to be lost.

The resource records that are dynamically added or removed with RUNDNSUPD have to be in the same zone. Requests are sent to the zones master server. This is identified by the MNAME field of the zones SOA record.

This utility will be run in interactive mode if *NONE is specified for the Batch input file (BCHFILE) parameter. To run this utility in non-interactive mode, specify a file name for the BCHFILE parameter.

Restrictions:

• You must have execute (*X) authority to the directories in the path of the batch input file.
• You must have read (*R) authority to the batch input file.
• You must have execute (*X) authority to the directories in the path of the key file.
• You must have read (*R) authority to the key file.
• You must have execute (*X) authority to the directories in the path of the output file.
• You must have write (*W) authority to the output file if it already exists.
• You must have read, write and execute (*RWX) authority to the output file's parent directory if the output file does not already exist.

Parameters

Batch input file (BCHFILE)

Specifies a stream file with all update commands to be used as batch input.

Each command in the file 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.

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 send command) causes the accumulated commands to be sent as one Dynamic DNS update request to the name server.

The command formats are as follows. Lines in the file beginning with a semicolon are considered comments and are ignored:

server {servername} [port]
local {address} [port]
zone {zonename}
class {classname}
key {name} {secret}
prereq nxdomain {domain-name}
prereq yxdomain {domain-name}
prereq nxrrset  {domain-name}       [class] {type}
prereq yxrrset  {domain-name}       [class] {type}
prereq yxrrset  {domain-name}       [class] {type} {data...}
update delete   {domain-name} [ttl] [class] [type [data...]]
update add      {domain-name} {ttl} [class] {type} {data...}
show
send
answer
quit

See the examples for descriptions of these commands.

*NONE

Do not use a batch file. This will enter interactive mode. To return from interactive mode, you must enter the command 'quit'.

Note: This value is only valid if the command is run in an interactive job.

path-name

Specify the path for a stream file from which input is read. You must have read (*R) authority to this file.

Show debug information (DEBUG)

Specifies whether or not to turn debugging mode on. More information is displayed about the packet sent to the server and the resulting answer when debugging mode is on.

*NO

Turn off debugging messages.

*YES

Turn on debugging messages.

Key name (KEYNAME)

Specifies a Transaction Signature (TSIG) key to sign the DNS queries. The only message digest algorithm currently used for TSIG is HMAC-MD5, although others may be added later. The TSIG key is a base-64 encoded string, typically generated by the Generate DNS Key (GENDNSKEY) command. The DNS server that is queried needs to be configured with the TSIG key and algorithm that is being used or the transaction will fail. See RFC 2845 for TSIG.

*NONE

Do not specify a key name.

character-value

Specify the Transaction Signature key. The format is 'name:key' where name is the key name, and key is the actual key as a base-64 encoded string. Example:

my-tsig-key:JNvcpnxysbJ2hsdOqQ5qrQ==

The key name in this case is 'my-tsig-key' and the base-64 encoded key is 'JNvcpnxysbJ2hsdOqQ5qrQ=='.

The DNS server being queried needs to include this key and algorithm in its configuration in order to accept this TSIG key from clients.

Key file (KEYFILE)

Specifies a file containing a SIG(0) key used to authenticate Dynamic DNS update requests. In this case, the key specified is not an HMAC-MD5 key. SIG(0) uses public key cryptography. To use a SIG(0) key, the public key must be stored in a KEY record in a zone served by the name server. See RFC 3535 and RFC 2931 for SIG(0).

Note: If a value other than *NONE is specified for this parameter, do not specify a value for the KEYNAME parameter.

*NONE

Do not specify a key file.

path-name

Specify the path for a stream file containing key information. For example, '/home/myprofile/my-key-file' could be specified.

Update timeout (TIMEOUT)

Specifies the maximum time an update request can take before it is aborted.

300

The default timeout is 300 seconds.

*NOMAX

The update request timeout is disabled.

1-300

Specify a valid timeout value in seconds.

UDP timeout (UDPRTYITV)

Specifies the interval, in seconds, between UDP retries.

3

A retry interval of 3 seconds is used.

*CALC

The retry interval is calculated by the utility based on the values specified for the Update timeout (TIMEOUT) parameter and the UDP retry (UDPNBRRTY) parameter.

1-65535

Specify the number of seconds to use between UDP retries.

UDP retry (UDPNBRRTY)

Specifies the number of UDP retries.

3

Three UDP retries will be used.

0-100

Specify the number of UDP retries. If zero is specified, only one update request will be made.

Network protocol (PROTOCOL)

Specified whether to use TCP or UDP when sending requests to the server.

*UDP

Use UDP to send the query. However, TCP will be automatically selected for queries that require it, such as zone transfer (AXFR) requests.

*TCP

Use TCP to send the query.

Local host only mode (LOCALHOST)

Specifies whether or not to connect to local host. Connections to the local server will use a transaction signature (TSIG) key found in /QIBM/UserData/OS400/DNS/_DYN/nnnnn/session.key (nnnnn is DNS instance name), which is automatically generated by a DNS server if any local master zone has set update-policy to local. The location of this key file can be overridden with the Key file (KEYFILE) parameter. To enable local host only mode, the DNS instance nnnnn must listen on the localhost(127.0.0.1) already.

*NO

Do not run in local host only mode.

*YES

Run in local host only mode.

Output file (TOSTMF)

Specifies the name of a stream file where all command output is written.

*STDOUT

All command output goes to the standard output device (normally the display).

path-name

Specify the path name for a stream file where output should be written.

Examples

The command formats and their meaning are as follows:

server {servername} [port]

Sends all dynamic update requests to the DNS server servername. When no server statement is provided, RUNDNSUPD will send updates to the master server of the correct zone. The MNAME field of that zones SOA record will identify the master server for that zone. port is the port number on servername where the dynamic update requests get sent. If no port number is specified, the default DNS port number of 53 is used.

local {address} [port]

Sends all dynamic update requests using the local address. When no local statement is provided, RUNDNSUPD will send updates using an address and port chosen by the system. port can additionally be used to make requests come from a specific port. If no port number is specified, the system will assign one.

zone {zonename}

Specifies that all updates are to be made to the zone zonename. If no zone statement is provided, RUNDNSUPD will attempt determine the correct zone to update based on the rest of the input.

class {classname}

Specify the default class. If no class is specified the default class is IN.

key {name} {secret}

Specifies that all updates are to be TSIG signed using the keyname keysecret pair. The key command overrides any key specified on the command line via -y or -k.

prereq nxdomain {domain-name}

Requires that no resource record of any type exists with name domain-name.

prereq yxdomain {domain-name}

Requires that domain-name exists (has as at least one resource record, of any type).

prereq nxrrset {domain-name} [class] {type}

Requires that no resource record exists of the specified type, class and domain-name. If class is omitted, IN (internet) is assumed.

prereq yxrrset {domain-name} [class] {type}

This requires that a resource record of the specified type, class and domain-name must exist. If class is omitted, IN (internet) is assumed.

prereq yxrrset {domain-name} [class] {type} {data...}

The data from each set of prerequisites of this form sharing 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 at the given type, class, and domain-name. The data are written in the standard text representation of the resource records RDATA.

update delete {domain-name} [ttl] [class] [type [data...]]

Deletes any resource records named domain-name. If type and data is provided, only matching resource records will be removed. The internet class is assumed if class is not supplied. The ttl is ignored, and is only allowed for compatibility.

update add {domain-name} {ttl} [class] {type} {data...}

Adds a new resource record with the specified ttl, class and data.

show

Displays the current message, containing all of the prerequisites and updates specified since the last send.

send

Sends the current message. This is equivalent to entering a blank line.

answer

Displays the answer.

quit

Exit interactive mode.

Example 1: Update Example

RUNDNSUPD   BCHFILE(*NONE)
> update delete oldhost.example.com A
> update add newhost.example.com 86400 A 172.16.1.1
> send
> quit

This command will start the interactive mode for the update utility. The lines that have the '>' prefix are interactive commands.

Insert and delete resource records from the '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 DNS server for example.com.

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 newly-added record has a 1 day TTL (86400 seconds)

Example 2: Pre-requisite Example

RUNDNSUPD
> prereq nxdomain nickname.example.com
> update add nickname.example.com 86400 CNAME somehost.example.com
> send
> quit

The prerequisite condition gets the DNS server to check that there are no resource records of any type for 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 RRSIG, DNSKEY and NSEC records.)

Example 3: Batch File Example

RUNDNSUPD   BCHFILE('/home/ibmuser/my-updates')

This command sends the updates in the file '/home/ibmuser/my-updates' to the server defined in the files server command. For example, the contents of the file might look like this:

server myserver.i5os.ibm.com 53
zone i5os.ibm.com
class in
prereq yxdomain box1.i5os.ibm.com.
update delete box1.i5os.ibm.com. A
update add box1.i5os.ibm.com. 3600 A 10.9.9.9
prereq yxdomain box2.i5os.ibm.com.
update delete box2.i5os.ibm.com. A
update add box2.i5os.ibm.com. 3600 A 10.9.9.10

And the results displayed on the screen might look like this:

; TSIG error with server: tsig indicates error
update failed: NOTAUTH(BADKEY)

Or the results displayed on the screen might look like this:

; TSIG error with server: tsig indicates error
update failed: REFUSED

The first example represent the case when the key in the file is not valid. The second example represents the case when the server is not allowing dynamic updates from you. No output or blank output only means the update was successful.

Error messages

*ESCAPE Messages

DNS0013

Error processing command parameters.

DNS0065

Option 33 of i5/OS is required, but is not installed.

TCP7124

Program &1 in library &2 type *PGM ended abnormally.