]> ISC DHCP References Collection Internet Systems Consortium, Inc.
950 Charter Street Redwood City CA 94063 +1 650 423 1300 David_Hankins@isc.org
Copyright (c) 2006-2007,2009 by Internet Systems Consortium, Inc. ("ISC") 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 ISC DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC 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. ISC DHCP Reference Implementation This document describes a collection of Reference material that ISC DHCP has been implemented to.
As a little historical anecdote, ISC DHCP once packaged all the relevant RFCs and standards documents along with the software package. Until one day when a voice was heard from one of the many fine institutions that build and distribute this software... they took issue with the IETF's copyright on the RFC's. It seems the IETF's copyrights don't allow modification of RFC's (except for translation purposes). Our main purpose in providing the RFCs is to aid in documentation, but since RFCs are now available widely from many points of distribution on the Internet, there is no real need to provide the documents themselves. So, this document has been created in their stead, to list the various IETF RFCs one might want to read, and to comment on how well (or poorly) we have managed to implement them.
ISC DHCP, much like its other cousins in ISC software, is self-described as a 'Reference Implementation.' There has been a great deal of confusion about this term. Some people seem to think that this term applies to any software that once passed a piece of reference material on its way to market (but may do quite a lot of things that aren't described in any reference, or may choose to ignore the reference it saw entirely). Other folks get confused by the word 'reference' and understand that to mean that there is some special status applied to the software - that the software itself is the reference by which all other software is measured. Something along the lines of being "The DHCP Protocol's Reference Clock," it is supposed. The truth is actually quite a lot simpler. Reference implementations are software packages which were written to behave precisely as appears in reference material. They are written "to match reference." If the software has a behaviour that manifests itself externally (whether it be something as simple as the 'wire format' or something higher level, such as a complicated behaviour that arises from multiple message exchanges), that behaviour must be found in a reference document. Anything else is a bug, the only question is whether the bug is in reference or software (failing to implement the reference). This means: To produce new externally-visible behaviour, one must first provide a reference. Before changing externally visible behaviour to work around simple incompatibilities in any other implementation, one must first provide a reference. That is the lofty goal, at any rate. It's well understood that, especially because the ISC DHCP Software package has not always been held to this standard (but not entirely due to it), there are many non-referenced behaviours within ISC DHCP. The primary goal of reference implementation is to prove the reference material. If the reference material is good, then you should be able to sit down and write a program that implements the reference, to the word, and come to an implementation that is distinguishable from others in the details, but not in the facts of operating the protocol. This means that there is no need for 'special knowledge' to work around arcane problems that were left undocumented. No secret handshakes need to be learned to be imparted with the necessary "real documentation". Also, by accepting only reference as the guidebook for ISC DHCP's software implementation, anyone who can make an impact on the color texture or form of that reference has a (somewhat indirect) voice in ISC DHCP's software design. As the IETF RFC's have been selected as the source of reference, that means everyone on the Internet with the will to participate has a say.
It may surprise you to realize that ISC DHCP implements 802.1 'Ethernet' framing, Token Ring, and FDDI. In order to bridge the gap there between these physical and DHCP layers, it must also implement IP and UDP framing. The reason for this stems from Unix systems' handling of BSD sockets (the general way one might engage in transmission of UDP packets) on unconfigured interfaces, or even the handling of broadcast addressing on configured interfaces. There are a few things that DHCP servers, relays, and clients all need to do in order to speak the DHCP protocol in strict compliance with RFC2131. Transmit a UDP packet from IP:0.0.0.0 Ethernet:Self, destined to IP:255.255.255.255 LinkLayer:Broadcast on an unconfigured (no IP address yet) interface. Receive a UDP packet from IP:remote-system LinkLayer:remote-system, destined to IP:255.255.255.255 LinkLayer:Broadcast, again on an unconfigured interface. Transmit a UDP packet from IP:Self, Ethernet:Seelf, destined to IP:remote-system LinkLayer:remote-system, without transmitting a single ARP. And of course the simple case, a regular IP unicast that is routed via the usual means (so it may be direct to a local system, with ARP providing the glue, or it may be to a remote system via one or more routers as normal). In this case, the interfaces are always configured. The above isn't as simple as it sounds on a regular BSD socket. Many unix implementations will transmit broadcasts not to 255.255.255.255, but to x.y.z.255 (where x.y.z is the system's local subnet). Such packets are not received by several known DHCP client implementations - and it's not their fault, RFC2131 very explicitly demands that these packets' IP destination addresses be set to 255.255.255.255. Receiving packets sent to 255.255.255.255 isn't a problem on most modern unixes...so long as the interface is configured. When there is no IPv4 address on the interface, things become much more murky. So, for this convoluted and unfortunate state of affairs in the unix systems of the day ISC DHCP was manufactured, in order to do what it needs not only to implement the reference but to interoperate with other implementations, the software must create some form of raw socket to operate on. What it actually does is create, for each interface detected on the system, a Berkeley Packet Filter socket (or equivalent), and program it with a filter that brings in only DHCP packets. A "fallback" UDP Berkeley socket is generally also created, a single one no matter how many interfaces. Should the software need to transmit a contrived packet to the local network the packet is formed piece by piece and transmitted via the BPF socket. Hence the need to implement many forms of Link Layer framing and above. The software gets away with not having to implement IP routing tables as well by simply utilizing the aforementioned 'fallback' UDP socket when unicasting between two configured systems is the need. Modern unixes have opened up some facilities that diminish how much of this sort of nefarious kludgery is necessary, but have not found the state of affairs absolutely absolved. In particular, one might now unicast without ARP by inserting an entry into the ARP cache prior to transmitting. Unconfigured interfaces remain the sticking point, however...on virtually no modern unixes is it possible to receive broadcast packets unless a local IPv4 address has been configured, unless it is done with raw sockets.
ISC DHCP Implements Ethernet Version 2 ("DIX"), which is a variant of IEEE 802.2. No good reference of this framing is known to exist at this time, but it is vaguely described in RFC894 (see the section titled "Packet format"), and the following URL is also thought to be useful. http://en.wikipedia.org/wiki/DIX
IEEE 802.5 defines the Token Ring framing format used by ISC DHCP.
RFC1188 is the most helpful reference ISC DHCP has used to form FDDI packets.
RFC760 fundamentally defines the bare IPv4 protocol which ISC DHCP implements.
RFC768 defines the User Datagram Protocol that ultimately carries the DHCP or BOOTP protocol. The destination DHCP server port is 67, the client port is 68. Source ports are irrelevant.
The DHCP Protocol is strange among protocols in that it is grafted over the top of another protocol - BOOTP (but we don't call it "DHCP over BOOTP" like we do, say "TCP over IP"). BOOTP and DHCP share UDP packet formats - DHCP is merely a conventional use of both BOOTP header fields and the trailing 'options' space. The ISC DHCP server supports BOOTP clients conforming to RFC951 and RFC1542.
"The DHCP[v4] Protocol" is not defined in a single document. The following collection of references of what ISC DHCP terms "The DHCPv4 Protocol".
RFC2131 defines the protocol format and procedures. ISC DHCP is not known to diverge from this document in any way. There are, however, a few points on which different implementations have arisen out of vagueries in the document. DHCP Clients exist which, at one time, present themselves as using a Client Identifier Option which is equal to the client's hardware address. Later, the client transmits DHCP packets with no Client Identifier Option present - essentially identifying themselves using the hardware address. Some DHCP Servers have been developed which identify this client as a single client. ISC has interpreted RFC2131 to indicate that these clients must be treated as two separate entities (and hence two, separate addresses). Client behaviour (Embedded Windows products) has developed that relies on the former implementation, and hence is incompatible with the latter. Also, RFC2131 demands explicitly that some header fields be zeroed upon certain message types. The ISC DHCP Server instead copies many of these fields from the packet received from the client or relay, which may not be zero. It is not known if there is a good reason for this that has not been documented. RFC2132 defines the initial set of DHCP Options and provides a great deal of guidance on how to go about formatting and processing options. The document unfortunately waffles to a great extent about the NULL termination of DHCP Options, and some DHCP Clients (Windows 95) have been implemented that rely upon DHCP Options containing text strings to be NULL-terminated (or else they crash). So, ISC DHCP detects if clients null-terminate the host-name option and, if so, null terminates any text options it transmits to the client. It also removes NULL termination from any known text option it receives prior to any other processing.
For now there is only one document that specifies the DHCPv6 protocol (there have been no updates yet), RFC3315. Support for DHCPv6 was added first in version 4.0.0. The server and client support only IA_NA. While the server does support multiple IA_NAs within one packet from the client, our client only supports sending one. There is no relay support. DHCPv6 introduces some new and uncomfortable ideas to the common software library. Options of zero length are normal in DHCPv6. Currently, all ISC DHCP software treats zero-length options as errors. Options sometimes may appear multiple times. The common library used to treat all appearance of multiple options as specified in RFC2131 - to be concatenated. DHCPv6 options may sometimes appear multiple times (such as with IA_NA or IAADDR), but often must not. The same option space appears in DHCPv6 packets multiple times. If the packet was got via a relay, then the client's packet is stored to an option within the relay's packet...if there were two relays, this recurses. At each of these steps, the root "DHCPv6 option space" is used. Further, a client packet may contain an IA_NA, which may contain an IAADDR - but really, in an abstract sense, this is again re-encapsulation of the DHCPv6 option space beneath options it also contains. Precisely how to correctly support the above conundrums has not quite yet been settled, so support is incomplete.
RFC2241 defines options for Novell Directory Services. RFC2242 defines an encapsulated option space for NWIP configuration. RFC2485 defines the Open Group's UAP option. RFC2610 defines options for the Service Location Protocol (SLP). RFC2937 defines the Name Service Search Option (not to be confused with the domain-search option). The Name Service Search Option allows eg nsswitch.conf to be reconfigured via dhcp. The ISC DHCP server implements this option, and the ISC DHCP client is compatible...but does not by default install this option's value. One would need to make their relevant dhclient-script process this option in a way that is suitable for the system. RFC3004 defines the User-Class option. Note carefully that ISC DHCP currently does not implement to this reference, but has (inexplicably) selected an incompatible format: a plain text string. RFC3011 defines the Subnet-Selection plain DHCPv4 option. Do not confuse this option with the relay agent "link selection" sub-option, although their behaviour is similar. RFC3319 defines the SIP server options for DHCPv6. RFC3396 documents both how long options may be encoded in DHCPv4 packets, and also how multiple instances of the same option code within a DHCPv4 packet will be decoded by receivers. RFC3397 documents the Domain-Search Option, which allows the configuration of the /etc/resolv.conf 'search' parameter in a way that is RFC1035 wire format compatible (in fact, it uses the RFC1035 wire format). ISC DHCP has both client and server support, and supports RFC1035 name compression. RFC3646 documents the DHCPv6 name-servers and domain-search options. RFC3633 documents the Identity Association Prefix Delegation, which is included here for protocol wire reference, but which is not supported by ISC DHCP. RFC3679 documents a number of options that were documented earlier in history, but were not made use of. RFC3898 documents four NIS options for delivering NIS servers and domain information in DHCPv6. RFC3925 documents a pair of Enterprise-ID delimited option spaces for vendors to use in order to inform servers of their "vendor class" (sort of like 'uname' or 'who and what am I'), and a means to deliver vendor-specific and vendor-documented option codes and values. RFC3942 redefined the 'site local' option space. RFC4075 defines the DHCPv6 SNTP Servers option. RFC4242 defines the Information Refresh Time option, which advises DHCPv6 Information-Request clients to return for updated information. RFC4280 defines two BCMS server options. RFC4388 defined the DHCPv4 LEASEQUERY message type and a number of suitable response messages, for the purpose of sharing information about DHCP served addresses and clients. RFC4580 defines a DHCPv6 subscriber-id option, which is similar in principle to the DHCPv4 relay agent option of the same name. RFC4649 defines a DHCPv6 remote-id option, which is similar in principle to the DHCPv4 relay agent remote-id.
RFC3046 defines the Relay Agent Information Option and provides a number of sub-option definitions. RFC3256 defines the DOCSIS Device Class sub-option. RFC3527 defines the Link Selection sub-option.
The collection of documents that describe the standards-based method to update dns names of DHCP clients starts most easily with RFC4703 to define the overall architecture, travels through RFCs 4702 and 4704 to describe the DHCPv4 and DHCPv6 FQDN options (to carry the client name), and ends up at RFC4701 which describes the DHCID RR used in DNS to perform a kind of atomic locking. ISC DHCP adoped early versions of these documents, and has not yet synched up with the final standards versions. For RFCs 4702 and 4704, the 'N' bit is not yet supported. The result is that it is always set zero, and is ignored if set. For RFC4701, which is used to match client identities with names in the DNS as part of name conflict resolution. Note that ISC DHCP's implementation of DHCIDs vary wildly from this specification. First, ISC DHCP uses a TXT record in which the contents are stored in hexadecimal. Second, there is a flaw in the selection of the 'Identifier Type', which results in a completely different value being selected than was defined in an older revision of this document...also this field is one byte prior to hexadecimal encoding rather than two. Third, ISC DHCP does not use a digest type code. Rather, all values for such TXT records are reached via an MD5 sum. In short, nothing is compatible, but the principle of the TXT record is the same as the standard DHCID record. However, for DHCPv6 FQDN, we do use DHCID type code '2', as no other value really makes sense in our context.
The Failover Protocol defines a means by which two DHCP Servers can share all the relevant information about leases granted to DHCP clients on given networks, so that one of the two servers may fail and be survived by a server that can act responsibly. Unfortunately it has been quite some years since the last time this document was edited, and the authors no longer show any interest in fielding comments or improving the document. The status of this protocol is very unsure, but ISC's implementation of it has proven stable and suitable for use in sizable production environments. draft-ietf-dhc-failover-12.txt describes the Failover Protocol. In addition to what is described in this document, ISC DHCP has elected to make some experimental changes that may be revoked in a future version of ISC DHCP (if the draft authors do not adopt the new behaviour). Specifically, ISC DHCP's POOLREQ behaviour differs substantially from what is documented in the draft, and the server also implements a form of 'MAC Address Affinity' which is not described in the failover document. The full nature of these changes have been described on the IETF DHC WG mailing list (which has archives), and also in ISC DHCP's manual pages. Also note that although this document references a RECOVER-WAIT state, it does not document a protocol number assignment for this state. As a consequence, ISC DHCP has elected to use the value 254. RFC3074 describes the Load Balancing Algorithm (LBA) that ISC DHCP uses in concert with the Failover protocol. Note that versions 3.0.* are known to misimplement the hash algorithm (it will only use the low 4 bits of every byte of the hash bucket array).
RFC2939 explains how to go about obtaining a new DHCP Option code assignment.
&rfc760; &rfc768; &rfc894; &rfc951; &rfc1035; &rfc1188; &rfc1542; &rfc2131; &rfc2132; &rfc2241; &rfc2242; &rfc2485; &rfc2610; &rfc2937; &rfc2939; &rfc3004; &rfc3011; &rfc3046; &rfc3074; &rfc3256; &rfc3315; &rfc3319; &rfc3396; &rfc3397; &rfc3527; &rfc3633; &rfc3646; &rfc3679; &rfc3898; &rfc3925; &rfc3942; &rfc4075; &rfc4242; &rfc4280; &rfc4388; &rfc4580; &rfc4649; &rfc4701; &rfc4702; &rfc4703; &rfc4704; DHCP Failover Protocol Cisco Systems