Update DNS API (QTOBUPDT)

The Update DNS API (QTOBUPDT) allows the caller to send one or more update instructions to an iSeries dynamic DNS (Domain Name System) server. The instructions allow for adding or deleting DNS Resource Records (RRs). The instructions can optionally include any number of prerequisite conditions that must be true for the actual updates to take place. This API is based on the Berkeley Internet Name Domain (BIND) version 8.2.x implementation of dynamic DNS updates. Therefore, it also can be used to send update requests to DNS servers running on other operating system platforms that conform to BIND Version 8 update protocols.

i5/OS Option 31 (Domain Name System) must be installed to use this API.

Authorities and Locks

If an Integrated File System (IFS) stream file name is specified for any of the parameters that allow it, then the user will need *R authority to the stream file and *X authority to the directories in the path of the stream file.

Required Parameter Group

Update instructions

INPUT; CHAR(*)

One or more instructions that define which DNS resource records should be updated (added or deleted) for a specific DNS domain, as well as any prerequistes that must be true for those updates to take place. Depending on which format name for this parameter is chosen, this parameter will either contain the actual update instructions themselves or the name of an Integrated File System file that contains the update instructions.

The syntax for the update instructions themselves is the same as that defined by BIND 8.2.3 for dynamic DNS updates, which it uses as input to its nsupdate program. Please see Update Instructions Syntax for descriptions of the update instructions themselves.

Length of update instructions

INPUT; BINARY(4)

The length of the data passed in the Update instructions parameter. If the length is larger than the size of the Update instructions parameter, the results may not be predictable.

Format name of update instructions

INPUT; CHAR(8)

The format of the data being passed in the Update instructions parameter.

DNSU0100	Data passed represents the actual data the API should use.
DNSU0200	Data passed represents the path name of an Integrated File System file that contains the data the API should use.
DNSU0300	Data passed represents the name of a file that contains the data the API should use. The file name is in an i5/OS API path name structure. For the format of this structure, see Path name format.

Update key override

INPUT; CHAR(*)

This API automatically searches the default DNS dynamic update directory /QIBM/UserData/OS400/DNS/_DYN for a dynamic update transaction signature (TSIG) key for the specific domain being updated. The caller can override the default logic and provide a transaction signature key directly to the API by using this Update key override parameter. Depending on which format name for this parameter is chosen, this parameter will either contain the actual key itself or the path name of an Integrated File System file that contains the key.

Length of update key override

INPUT; BINARY(4)

The length of the data passed in the Update key override parameter. If the length is larger than the size of the Update key override parameter, the results may not be predictable.

Format name of update key override

INPUT; CHAR(8)

The format of the data being passed in the Update key override parameter.

DNSU0100	Data passed represents the actual data the API should use.
DNSU0200	Data passed represents the path name of an Integrated File System (IFS) file that contains the data the API should use.
DNSU0300	Data passed represents the name of a file that contains the data the API should use. The file name is in an i5/OS API path name structure. For the format of this structure, see Path name format.

Update key name

INPUT; CHAR(*)

If the caller is providing a transaction signature key in the update key override parameter, then the update key name parameter must contain the name of the update key.

Length of update key name

INPUT; BINARY(4)

The length of the data passed in the Update key name parameter. If the length is larger than the size of the Update key name parameter, the results may not be predictable.

IP address of DNS server

INPUT; CHAR(15)

The IP address, in dotted decimal form, of the DNS server where the API should start searching for the primary master DNS server for the zone being updated. The parameter must be right padded with blanks if the data does not take up the entire length.

If this parameter is all blanks on input, the API will automatically search the network to determine where the primary master DNS server is located for the zone that contains the domain being updated.

Miscellaneous attributes

INPUT; CHAR(*)

Optional miscellaneous runtime attributes.

Length of miscellaneous attributes

INPUT; BINARY(4)

The length of the data passed in the Miscellaneous attributes parameter. If the length is larger than the size of the Miscellaneous attributes parameter, the results may not be predictable.

Format name of miscellaneous attributes

INPUT; CHAR(8)

The format of the data being passed in the Miscellaneous attributes parameter.

DNSA0100

Miscellaneous runtime attributes. Refer to DNSA0100 Format for details on the format.

Result code

OUTPUT; BINARY(4)

Whether the API processed successfully or not, and if not, what type of problem was encountered. Any code that is not 0 means that the updates were not completely successful.

0	Successful.
1	Send error. The authoritative name server could not be reached.
2	Failed update packet. The name server has rejected the update, either because it does not support dynamic update or due to an authentication failure.
3	Prerequisite failure. The update was successfully received and authenticated by the name server. The prerequisites, however, prevented the update from actually being performed.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

Update Instructions Syntax

The syntax of the update instructions for the QTOBUPDT API is the same as the syntax of the update instructions that are input to the BIND (Berkeley Internet Name Domain) Version 8.2.x program known as nsupdate. It is a stream file-based input format that requires carriage-return(<cr>) linefeed (<lf>) characters to define distinct "lines" of input.

In addition to accepting these instructions using stream files, like nsupdate, the QTOBUPDT API has added the ability (by specifying format DNSU0100) for an application program to build the lines of input in memory and pass them directly to the API without first having to write them to a file. It is important to note, however, that this method still requires that you build the input lines exactly as you would if you were going to write them to a stream file; that is, separated by the same <cr><lf> characters that are described below.

QTOBUPDT reads input records, one per line, each line contributing a resource record directive to a single update request. As described below, the directives can be either prerequisite checks or actual resource record (RR) data update directives. All domain names used in an update request must belong to the same DNS zone. A blank line causes the accumulated records to be formatted 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 that domain. For any given call to the API, multiple update requests can be made, but each group of lines belonging to each single update request must be separated by a blank line. For the last request to be transmitted, you must remember to include a blank line as the last line of your input.

Records take one of two general forms. Prerequisite records specify conditions that must be satisfied before the request will be processed. Update records specify actual data changes to be made to the DNS database. An "update request" consists of zero or more prerequisites, and one or more updates. Each update request is processed atomically; that is, all prerequisites must be satisfied, then all updates are performed. If any of the prerequisites within the specific update request fail, the actual data update directives following them will not be attempted.

QTOBUPDT API understands the following input record formats:

EXAMPLES

1. The following example illustrates a set of update instructions that could be sent to the QTOBUPDT API to change an IP address by deleting any existing A records for a domain name, and then inserting a new A record. Since no prerequisites are specified, the new record will be added even if there were no existing records to delete. The trailing blank line is required to process the request.
   
   
   • record 1: update delete test.test.com A <cr><lf>
   • record 2: update add test.test.com 3600 A 10.1.1.1 <cr><lf>
   • record 3: <cr><lf>
   
   
2. 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.
   
   
   • record 1: prereq nxrrset www.test.com A <cr><lf>
   • record 2: prereq nxrrset www.test.com CNAME <cr><lf>
   • record 3: update add www.test.com 3600 CNAME test.test.com <cr><lf>
   • record 4: <cr><lf>
   
   
3. To accomplish both of the above independent update requests in a single call to the QTOBUPDT API, the update instructions submitted would be:
   
   
   • record 1: update delete test.test.com A <cr><lf>
   • record 2: update add test.test.com 3600 A 10.1.1.1 <cr><lf>
   • record 3: <cr><lf>
   • record 4: prereq nxrrset www.test.com A <cr><lf>
   • record 5: prereq nxrrset www.test.com CNAME <cr><lf>
   • record 6: update add www.test.com 3600 CNAME test.test.com <cr><lf>
   • record 7: <cr><lf>

DNSA0100 Format

The following is the format used for passing miscellaneous runtime attributes to the dynamic DNS update API. For detailed descriptions of the fields in this table, see Field Descriptions.

Field Descriptions

Debug flag. If set on, tells the API to create a spooled print file (QPRINT) to the caller's userid.

Reserved for future use. A reserved field that must be set to hexadecimal zeros.

Virtual circuit flag. If set on, tells the API to use a TCP connection instead of the default UDP packets.

Error Messages

API introduced: V5R1