Network Working Group P. Vixie, Editor Request for Comments: 2136 ISC Updates: 1035 S. Thomson Category: Standards Track Bellcore Y. Rekhter Cisco J. Bound DEC April 1997
This document specifies an Internet standards track protocol for the Internet community, and requests discussion and suggestions for improvements. Please refer to the current edition of the "Internet Official Protocol Standards" (STD 1) for the standardization state and status of this protocol. Distribution of this memo is unlimited.
The Domain Name System was originally designed to support queries of a statically configured database. While the data was expected to change, the frequency of those changes was expected to be fairly low, and all updates were made as external edits to a zone's Master File.
Using this specification of the UPDATE opcode, it is possible to add or delete RRs or RRsets from a specified zone. Prerequisites are specified separately from update operations, and can specify a dependency upon either the previous existence or nonexistence of an RRset, or the existence of a single RR.
UPDATE is atomic, i.e., all prerequisites must be satisfied or else no update operations will take place. There are no data dependent error conditions defined after the prerequisites have been met.
This document intentionally gives more definition to the roles of "Master," "Slave," and "Primary Master" servers, and their enumeration in NS RRs, and the SOA MNAME field. In that sense, the following server type definitions can be considered an addendum to [RFC1035], and are intended to be consistent with [RFC1996]:
Slave an authoritative server that uses AXFR or IXFR to retrieve the zone and is named in the zone's NS RRset.
Master an authoritative server configured to be the source of AXFR or IXFR data for one or more slave servers.
Primary Master master server at the root of the AXFR/IXFR dependency graph. The primary master is named in the zone's SOA MNAME field and optionally by an NS RR. There is by definition only one primary master server per zone.
A domain name identifies a node within the domain name space tree structure. Each node has a set (possibly empty) of Resource Records (RRs). All RRs having the same NAME, CLASS and TYPE are called a Resource Record Set (RRset).
The pseudocode used in this document is for example purposes only. If it is found to disagree with the text, the text shall be considered authoritative. If the text is found to be ambiguous, the pseudocode can be used to help resolve the ambiguity.
SOA compare only NAME, CLASS and TYPE -- it is not possible to have more than one SOA per zone, even if any of the data fields differ. WKS compare only NAME, CLASS, TYPE, ADDRESS, and PROTOCOL -- only one WKS RR is possible for this tuple, even if the services masks differ.
CNAME compare only NAME, CLASS, and TYPE -- it is not possible to have more than one CNAME RR, even if their data fields differ.
For the purpose of determining whether a domain name used in the UPDATE protocol is contained within a specified zone, a domain name is "in" a zone if it is owned by that zone's domain name. See section 7.18 for details.
CLASS = NONE (254)
RCODE = YXDOMAIN (6)
RCODE = YXRRSET (7)
RCODE = NXRRSET (8)
RCODE = NOTAUTH (9)
RCODE = NOTZONE (10)
Opcode = UPDATE (5)
The DNS Message Format is defined by [RFC1035 4.1]. Some extensions are necessary (for example, more error codes are possible under UPDATE than under QUERY) and some fields must be overloaded (see description of CLASS fields below).
The overall format of an UPDATE message is, following [ibid]:
+---------------------+ | Header | +---------------------+ | Zone | specifies the zone to be updated +---------------------+ | Prerequisite | RRs or RRsets which must (not) preexist +---------------------+ | Update | RRs or RRsets to be added or deleted +---------------------+ | Additional Data | additional data +---------------------+
The Header Section specifies that this message is an UPDATE, and describes the size of the other sections. The Zone Section names the zone that is to be updated by this message. The Prerequisite Section specifies the starting invariants (in terms of zone content) required for this update. The Update Section contains the edits to be made, and the Additional Data Section contains data which may be necessary to complete, but is not part of, this update.
An update transaction may be carried in a UDP datagram, if the request fits, or in a TCP connection (at the discretion of the requestor). When TCP is used, the message is in the format described in [RFC1035 4.2.2].
The header of the DNS Message Format is defined by [RFC 1035 4.1]. Not all opcodes define the same set of flag bits, though as a practical matter most of the bits defined for QUERY (in [ibid]) are identically defined by the other opcodes. UPDATE uses only one flag bit (QR).
The DNS Message Format specifies record counts for its four sections (Question, Answer, Authority, and Additional). UPDATE uses the same fields, and the same section formats, but the naming and use of these sections differs as shown in the following modified header, after [RFC1035 4.1.1]:
1 1 1 1 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | ID | +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ |QR| Opcode | Z | RCODE | +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | ZOCOUNT | +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | PRCOUNT | +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | UPCOUNT | +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | ADCOUNT | +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
These fields are used as follows:
ID A 16-bit identifier assigned by the entity that generates any kind of request. This identifier is copied in the corresponding reply and can be used by the requestor to match replies to outstanding requests, or by the server to detect duplicated requests from some requestor. QR A one bit field that specifies whether this message is a request (0), or a response (1).
Opcode A four bit field that specifies the kind of request in this message. This value is set by the originator of a request and copied into the response. The Opcode value that identifies an UPDATE message is five (5).
Z Reserved for future use. Should be zero (0) in all requests and responses. A non-zero Z field should be ignored by implementations of this specification. RCODE Response code - this four bit field is undefined in requests and set in responses. The values and meanings of this field within responses are as follows: Mneumonic Value Description ------------------------------------------------------------ NOERROR 0 No error condition. FORMERR 1 The name server was unable to interpret the request due to a format error. SERVFAIL 2 The name server encountered an internal failure while processing this request, for example an operating system error or a forwarding timeout. NXDOMAIN 3 Some name that ought to exist, does not exist. NOTIMP 4 The name server does not support the specified Opcode. REFUSED 5 The name server refuses to perform the specified operation for policy or security reasons. YXDOMAIN 6 Some name that ought not to exist, does exist. YXRRSET 7 Some RRset that ought not to exist, does exist. NXRRSET 8 Some RRset that ought to exist, does not exist.
NOTAUTH 9 The server is not authoritative for the zone named in the Zone Section. NOTZONE 10 A name used in the Prerequisite or Update Section is not within the zone denoted by the Zone Section.
ZOCOUNT The number of RRs in the Zone Section.
PRCOUNT The number of RRs in the Prerequisite Section.
UPCOUNT The number of RRs in the Update Section.
ADCOUNT The number of RRs in the Additional Data Section.
The Zone Section has the same format as that specified in [RFC1035 4.1.2], with the fields redefined as follows:
1 1 1 1 1 1
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | | / ZNAME / / / +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | ZTYPE | +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+ | ZCLASS | +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
UPDATE uses this section to denote the zone of the records being updated. All records to be updated must be in the same zone, and therefore the Zone Section is allowed to contain exactly one record. The ZNAME is the zone name, the ZTYPE must be SOA, and the ZCLASS is the zone's class.
This section contains a set of RRset prerequisites which must be satisfied at the time the UPDATE packet is received by the primary master server. The format of this section is as specified by [RFC1035 4.1.3]. There are five possible sets of semantics that can be expressed here, summarized as follows and then explained below.
(1) RRset exists (value independent). At least one RR with a specified NAME and TYPE (in the zone and class specified by the Zone Section) must exist.
(2) RRset exists (value dependent). A set of RRs with a specified NAME and TYPE exists and has the same members with the same RDATAs as the RRset specified here in this Section.
(3) RRset does not exist. No RRs with a specified NAME and TYPE (in the zone and class denoted by the Zone Section) can exist.
(4) Name is in use. At least one RR with a specified NAME (in the zone and class specified by the Zone Section) must exist. Note that this prerequisite is NOT satisfied by empty nonterminals.
(5) Name is not in use. No RR of any type is owned by a specified NAME. Note that this prerequisite IS satisfied by empty nonterminals.
The syntax of these is as follows:
At least one RR with a specified NAME and TYPE (in the zone and class specified in the Zone Section) must exist.
For this prerequisite, a requestor adds to the section a single RR whose NAME and TYPE are equal to that of the zone RRset whose existence is required. RDLENGTH is zero and RDATA is therefore empty. CLASS must be specified as ANY to differentiate this condition from that of an actual RR whose RDLENGTH is naturally zero (0) (e.g., NULL). TTL is specified as zero (0).
A set of RRs with a specified NAME and TYPE exists and has the same members with the same RDATAs as the RRset specified here in this section. While RRset ordering is undefined and therefore not significant to this comparison, the sets be identical in their extent.
For this prerequisite, a requestor adds to the section an entire RRset whose preexistence is required. NAME and TYPE are that of the RRset being denoted. CLASS is that of the zone. TTL must be specified as zero (0) and is ignored when comparing RRsets for identity.
No RRs with a specified NAME and TYPE (in the zone and class denoted by the Zone Section) can exist.
For this prerequisite, a requestor adds to the section a single RR whose NAME and TYPE are equal to that of the RRset whose nonexistence is required. The RDLENGTH of this record is zero (0), and RDATA field is therefore empty. CLASS must be specified as NONE in order to distinguish this condition from a valid RR whose RDLENGTH is naturally zero (0) (for example, the NULL RR). TTL must be specified as zero (0).
Name is in use. At least one RR with a specified NAME (in the zone and class specified by the Zone Section) must exist. Note that this prerequisite is NOT satisfied by empty nonterminals.
For this prerequisite, a requestor adds to the section a single RR whose NAME is equal to that of the name whose ownership of an RR is required. RDLENGTH is zero and RDATA is therefore empty. CLASS must be specified as ANY to differentiate this condition from that of an actual RR whose RDLENGTH is naturally zero (0) (e.g., NULL). TYPE must be specified as ANY to differentiate this case from that of an RRset existence test. TTL is specified as zero (0).
Name is not in use. No RR of any type is owned by a specified NAME. Note that this prerequisite IS satisfied by empty nonterminals.
For this prerequisite, a requestor adds to the section a single RR whose NAME is equal to that of the name whose nonownership of any RRs is required. RDLENGTH is zero and RDATA is therefore empty. CLASS must be specified as NONE. TYPE must be specified as ANY. TTL must be specified as zero (0).
This section contains RRs to be added to or deleted from the zone. The format of this section is as specified by [RFC1035 4.1.3]. There are four possible sets of semantics, summarized below and with details to follow.
(1) Add RRs to an RRset.
(2) Delete an RRset.
(3) Delete all RRsets from a name.
(4) Delete an RR from an RRset.
The syntax of these is as follows:
RRs are added to the Update Section whose NAME, TYPE, TTL, RDLENGTH and RDATA are those being added, and CLASS is the same as the zone class. Any duplicate RRs will be silently ignored by the primary master.
One RR is added to the Update Section whose NAME and TYPE are those of the RRset to be deleted. TTL must be specified as zero (0) and is otherwise not used by the primary master. CLASS must be specified as ANY. RDLENGTH must be zero (0) and RDATA must therefore be empty. If no such RRset exists, then this Update RR will be silently ignored by the primary master.
One RR is added to the Update Section whose NAME is that of the name to be cleansed of RRsets. TYPE must be specified as ANY. TTL must be specified as zero (0) and is otherwise not used by the primary master. CLASS must be specified as ANY. RDLENGTH must be zero (0) and RDATA must therefore be empty. If no such RRsets exist, then this Update RR will be silently ignored by the primary master.
RRs to be deleted are added to the Update Section. The NAME, TYPE, RDLENGTH and RDATA must match the RR being deleted. TTL must be specified as zero (0) and will otherwise be ignored by the primary master. CLASS must be specified as NONE to distinguish this from an RR addition. If no such RRs exist, then this Update RR will be silently ignored by the primary master.
This section contains RRs which are related to the update itself, or to new RRs being added by the update. For example, out of zone glue (A RRs referred to by new NS RRs) should be presented here. The server can use or ignore out of zone glue, at the discretion of the server implementor. The format of this section is as specified by [RFC1035 4.1.3].
A server, upon receiving an UPDATE request, will signal NOTIMP to the requestor if the UPDATE opcode is not recognized or if it is recognized but has not been implemented. Otherwise, processing continues as follows.
if (zcount != 1 || ztype != SOA)
return (FORMERR)
if (zone_type(zname, zclass) == SLAVE)
return forward()
if (zone_type(zname, zclass) == MASTER)
return update()
return (NOTAUTH)
Sections 3.2 through 3.8 describe the primary master's behaviour, whereas Section 6 describes a forwarder's behaviour.
Next, the Prerequisite Section is checked to see that all prerequisites are satisfied by the current state of the zone. Using the definitions expressed in Section 1.2, if any RR's NAME is not within the zone specified in the Zone Section, signal NOTZONE to the requestor.
CLASS TYPE RDATA Meaning ------------------------------------------------------------ ANY ANY empty Name is in use ANY rrset empty RRset exists (value independent) NONE ANY empty Name is not in use NONE rrset empty RRset does not exist zone rrset rr RRset exists (value dependent)
for rr in prerequisites
if (rr.ttl != 0)
return (FORMERR)
if (zone_of(rr.name) != ZNAME)
return (NOTZONE);
if (rr.class == ANY)
if (rr.rdlength != 0)
return (FORMERR)
if (rr.type == ANY)
if (!zone_name<rr.name>)
return (NXDOMAIN)
else
if (!zone_rrset<rr.name, rr.type>)
return (NXRRSET)
if (rr.class == NONE)
if (rr.rdlength != 0)
return (FORMERR)
if (rr.type == ANY)
if (zone_name<rr.name>)
return (YXDOMAIN)
else
if (zone_rrset<rr.name, rr.type>)
return (YXRRSET)
if (rr.class == zclass)
temp<rr.name, rr.type> += rr
else
return (FORMERR)
for rrset in temp
if (zone_rrset<rrset.name, rrset.type> != rrset)
return (NXRRSET)
if (security policy exists)
if (this update is not permitted)
if (local option)
log a message about permission problem
if (local option)
return (REFUSED)
Next, the Update Section is processed as follows.
The Update Section is parsed into RRs and each RR's CLASS is checked to see if it is ANY, NONE, or the same as the Zone Class, else signal a FORMERR to the requestor. Using the definitions in Section 1.2, each RR's NAME must be in the zone specified by the Zone Section, else signal NOTZONE to the requestor.
[rr] for rr in updates
if (zone_of(rr.name) != ZNAME)
return (NOTZONE);
if (rr.class == zclass)
if (rr.type & ANY|AXFR|MAILA|MAILB)
return (FORMERR)
elsif (rr.class == ANY)
if (rr.ttl != 0 || rr.rdlength != 0
|| rr.type & AXFR|MAILA|MAILB) return (FORMERR) elsif (rr.class == NONE) if (rr.ttl != 0 || rr.type & ANY|AXFR|MAILA|MAILB) return (FORMERR) else return (FORMERR)
The Update Section is parsed into RRs and these RRs are processed in order.
CLASS TYPE RDATA Meaning --------------------------------------------------------- ANY ANY empty Delete all RRsets from a name ANY rrset empty Delete an RRset NONE rrset rr Delete an RR from an RRset zone rrset rr Add to an RRset
[rr] for rr in updates
if (rr.class == zclass)
if (rr.type == CNAME)
if (zone_rrset<rr.name, ~CNAME>)
next [rr]
elsif (zone_rrset<rr.name, CNAME>)
next [rr]
if (rr.type == SOA)
if (!zone_rrset<rr.name, SOA> ||
zone_rr<rr.name, SOA>.serial > rr.soa.serial)
next [rr]
for zrr in zone_rrset<rr.name, rr.type>
if (rr.type == CNAME || rr.type == SOA ||
(rr.type == WKS && rr.proto == zrr.proto &&
rr.address == zrr.address) ||
rr.rdata == zrr.rdata)
zrr = rr
next [rr]
zone_rrset<rr.name, rr.type> += rr
elsif (rr.class == ANY)
if (rr.type == ANY)
if (rr.name == zname)
zone_rrset<rr.name, ~(SOA|NS)> = Nil
else
zone_rrset<rr.name, *> = Nil
elsif (rr.name == zname &&
(rr.type == SOA || rr.type == NS))
next [rr]
else
zone_rrset<rr.name, rr.type> = Nil
elsif (rr.class == NONE)
if (rr.type == SOA)
next [rr]
if (rr.type == NS && zone_rrset<rr.name, NS> == rr)
next [rr]
zone_rr<rr.name, rr.type, rr.data> = Nil
return (NOERROR)
When a zone is modified by an UPDATE operation, the server must commit the change to nonvolatile storage before sending a response to the requestor or answering any queries or transfers for the modified zone. It is reasonable for a server to store only the update records as long as a system reboot or power failure will cause these update records to be incorporated into the zone the next time the server is started. It is also reasonable for the server to copy the entire modified zone to nonvolatile storage after each update operation, though this would have suboptimal performance for large zones.
If the zone's SOA SERIAL is changed by an update operation, that change must be in a positive direction (using modulo 2**32 arithmetic as specified by [RFC1982]). Attempts to replace an SOA with one whose SERIAL is less than the current one will be silently ignored by the primary master server.
If the zone's SOA's SERIAL is not changed as a result of an update operation, then the server shall increment it automatically before the SOA or any changed name or RR or RRset is included in any response or transfer. The primary master server's implementor might choose to autoincrement the SOA SERIAL if any of the following events occurs:
(1) Each update operation.
(2) A name, RR or RRset in the zone has changed and has subsequently been visible to a DNS client since the unincremented SOA was visible to a DNS client, and the SOA is about to become visible to a DNS client.
(3) A configurable period of time has elapsed since the last update operation. This period shall be less than or equal to one third of the zone refresh time, and the default shall be the lesser of that maximum and 300 seconds.
(4) A configurable number of updates has been applied since the last SOA change. The default value for this configuration parameter shall be one hundred (100).
It is imperative that the zone's contents and the SOA's SERIAL be tightly synchronized. If the zone appears to change, the SOA must appear to change as well.
During the processing of an UPDATE transaction, the server must ensure atomicity with respect to other (concurrent) UPDATE or QUERY transactions. No two transactions can be processed concurrently if either depends on the final results of the other; in particular, a QUERY should not be able to retrieve RRsets which have been partially modified by a concurrent UPDATE, and an UPDATE should not be able to start from prerequisites that might not still hold at the completion of some other concurrent UPDATE. Finally, if two UPDATE transactions would modify the same names, RRs or RRsets, then such UPDATE transactions must be serialized.
At the end of UPDATE processing, a response code will be known. A response message is generated by copying the ID and Opcode fields from the request, and either copying the ZOCOUNT, PRCOUNT, UPCOUNT, and ADCOUNT fields and associated sections, or placing zeros (0) in the these "count" fields and not including any part of the original update. The QR bit is set to one (1), and the response is sent back to the requestor. If the requestor used UDP, then the response will be sent to the requestor's source UDP port. If the requestor used TCP, then the response will be sent back on the requestor's open TCP connection.
ID: (new) Opcode: UPDATE Zone zcount: 1 Zone zname: (zone name) Zone zclass: (zone class) Zone ztype: T_SOA Prerequisite Section: (see previous text) Update Section: (see previous text) Additional Data Section: (empty)
and updates were the object of the transaction. If the transaction succeeds, the requestor knows that the RRs being changed were not otherwise altered by any other requestor.
When a zone slave forwards an UPDATE message upward toward the zone's primary master server, it must allocate a new ID and prepare to enter the role of "forwarding server," which is a requestor with respect to the forward server.
Some of the principles which guided the design of this UPDATE specification are as follows. Note that these are not part of the formal specification and any disagreement between this section and any other section of this document should be resolved in favour of the other section.
<NOERROR,ANCOUNT=0> rather than NXDOMAIN if queried for an RRset at this name, while UPDATE's prerequisite condition [Section 2.4.4] would NOT be satisfied.
We would like to thank the IETF DNSIND working group for their input and assistance, in particular, Rob Austein, Randy Bush, Donald Eastlake, Masataka Ohta, Mark Andrews, and Robert Elz. Special thanks to Bill Simpson, Ken Wallich and Bob Halley for reviewing this document.
[RFC1035]
Mockapetris, P., "Domain Names - Implementation and
Specification", STD 13, RFC 1035, USC/Information Sciences
Institute, November 1987.
[RFC1982]
Elz, R., "Serial Number Arithmetic", RFC 1982, University of
Melbourne, August 1996.
[RFC1995]
Ohta, M., "Incremental Zone Transfer", RFC 1995, Tokyo Institute
of Technology, August 1996.
[RFC1996]
Vixie, P., "A Mechanism for Prompt Notification of Zone Changes",
RFC 1996, Internet Software Consortium, August 1996.
[RFC2065]
Eastlake, D., and C. Kaufman, "Domain Name System Protocol
Security Extensions", RFC 2065, January 1997.
[RFC2137]
Eastlake, D., "Secure Domain Name System Dynamic Update", RFC
2137, April 1997.
Yakov Rekhter
Cisco Systems
170 West Tasman Drive
San Jose, CA 95134-1706
Phone: +1 914 528 0090
EMail: yakov@cisco.com
Susan Thomson
Bellcore
445 South Street
Morristown, NJ 07960
Phone: +1 201 829 4514
EMail: set@thumper.bellcore.com
Jim Bound
Digital Equipment Corp.
110 Spitbrook Rd ZK3-3/U14
Nashua, NH 03062-2698
Phone: +1 603 881 0400
EMail: bound@zk3.dec.com
Paul Vixie
Internet Software Consortium
Star Route Box 159A
Woodside, CA 94062
Phone: +1 415 747 0204
EMail: paul@vix.com