| TOC |
|
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.
This document describes a collection of Reference material that ISC DHCP has been implemented to.
1.
Introduction
2.
Definition: Reference Implementation
3.
Low Layer References
3.1.
Ethernet Protocol References
3.2.
Token Ring Protocol References
3.3.
FDDI Protocol References
3.4.
Internet Protocol Version 4 References
3.5.
Unicast Datagram Protocol References
4.
BOOTP Protocol References
5.
DHCP Protocol References
5.1.
DHCPv4 Protocol
5.1.1.
Core Protocol References
5.2.
DHCPv6 Protocol References
5.3.
DHCP Option References
5.3.1.
Relay Agent Information Option Options
5.3.2.
Dynamic DNS Updates References
5.3.3.
Experimental: Failover References
5.4.
DHCP Procedures
6.
References
§
Author's Address
| TOC |
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.
| TOC |
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:
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.
| TOC |
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 (Droms, R., “Dynamic Host Configuration Protocol,” March 1997.) [RFC2131].
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 (Droms, R., “Dynamic Host Configuration Protocol,” March 1997.) [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.
| TOC |
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 (Hornig, C., “Standard for the transmission of IP datagrams over Ethernet networks,” April 1984.) [RFC0894] (see the section titled "Packet format"), and the following URL is also thought to be useful.
http://en.wikipedia.org/wiki/DIX
| TOC |
IEEE 802.5 defines the Token Ring framing format used by ISC DHCP.
| TOC |
RFC1188 (Katz, D., “Proposed Standard for the Transmission of IP Datagrams over FDDI Networks,” October 1990.) [RFC1188] is the most helpful reference ISC DHCP has used to form FDDI packets.
| TOC |
RFC760 (Postel, J., “DoD standard Internet Protocol,” January 1980.) [RFC0760] fundamentally defines the bare IPv4 protocol which ISC DHCP implements.
| TOC |
RFC768 (Postel, J., “User Datagram Protocol,” August 1980.) [RFC0768] 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.
| TOC |
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 (Croft, B. and J. Gilmore, “Bootstrap Protocol,” September 1985.) [RFC0951] and RFC1542 (Wimer, W., “Clarifications and Extensions for the Bootstrap Protocol,” October 1993.) [RFC1542].
| TOC |
| TOC |
"The DHCP[v4] Protocol" is not defined in a single document. The following collection of references of what ISC DHCP terms "The DHCPv4 Protocol".
| TOC |
RFC2131 (Droms, R., “Dynamic Host Configuration Protocol,” March 1997.) [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 (Alexander, S. and R. Droms, “DHCP Options and BOOTP Vendor Extensions,” March 1997.) [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.
| TOC |
For now there is only one document that specifies the DHCPv6 protocol (there have been no updates yet), RFC3315 (Droms, R., Bound, J., Volz, B., Lemon, T., Perkins, C., and M. Carney, “Dynamic Host Configuration Protocol for IPv6 (DHCPv6),” July 2003.) [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.
Precisely how to correctly support the above conundrums has not quite yet been settled, so support is incomplete.
| TOC |
RFC2241 (Provan, D., “DHCP Options for Novell Directory Services,” November 1997.) [RFC2241] defines options for Novell Directory Services.
RFC2242 (Droms, R. and K. Fong, “NetWare/IP Domain Name and Information,” November 1997.) [RFC2242] defines an encapsulated option space for NWIP configuration.
RFC2485 (Drach, S., “DHCP Option for The Open Group's User Authentication Protocol,” January 1999.) [RFC2485] defines the Open Group's UAP option.
RFC2610 (Perkins, C. and E. Guttman, “DHCP Options for Service Location Protocol,” June 1999.) [RFC2610] defines options for the Service Location Protocol (SLP).
RFC2937 (Smith, C., “The Name Service Search Option for DHCP,” September 2000.) [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 (Stump, G., Droms, R., Gu, Y., Vyaghrapuri, R., Demirtjis, A., Beser, B., and J. Privat, “The User Class Option for DHCP,” November 2000.) [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 (Waters, G., “The IPv4 Subnet Selection Option for DHCP,” November 2000.) [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 (Schulzrinne, H. and B. Volz, “Dynamic Host Configuration Protocol (DHCPv6) Options for Session Initiation Protocol (SIP) Servers,” July 2003.) [RFC3319] defines the SIP server options for DHCPv6.
RFC3396 (Lemon, T. and S. Cheshire, “Encoding Long Options in the Dynamic Host Configuration Protocol (DHCPv4),” November 2002.) [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 (Aboba, B. and S. Cheshire, “Dynamic Host Configuration Protocol (DHCP) Domain Search Option,” November 2002.) [RFC3397] documents the Domain-Search Option, which allows the configuration of the /etc/resolv.conf 'search' parameter in a way that is RFC1035 (Mockapetris, P., “Domain names - implementation and specification,” November 1987.) [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 (Droms, R., “DNS Configuration options for Dynamic Host Configuration Protocol for IPv6 (DHCPv6),” December 2003.) [RFC3646] documents the DHCPv6 name-servers and domain-search options.
RFC3633 (Troan, O. and R. Droms, “IPv6 Prefix Options for Dynamic Host Configuration Protocol (DHCP) version 6,” December 2003.) [RFC3633] documents the Identity Association Prefix Delegation, which is included here for protocol wire reference, but which is not supported by ISC DHCP.
RFC3679 (Droms, R., “Unused Dynamic Host Configuration Protocol (DHCP) Option Codes,” January 2004.) [RFC3679] documents a number of options that were documented earlier in history, but were not made use of.
RFC3898 (Kalusivalingam, V., “Network Information Service (NIS) Configuration Options for Dynamic Host Configuration Protocol for IPv6 (DHCPv6),” October 2004.) [RFC3898] documents four NIS options for delivering NIS servers and domain information in DHCPv6.
RFC3925 (Littlefield, J., “Vendor-Identifying Vendor Options for Dynamic Host Configuration Protocol version 4 (DHCPv4),” October 2004.) [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 (Volz, B., “Reclassifying Dynamic Host Configuration Protocol version 4 (DHCPv4) Options,” November 2004.) [RFC3942] redefined the 'site local' option space.
RFC4075 (Kalusivalingam, V., “Simple Network Time Protocol (SNTP) Configuration Option for DHCPv6,” May 2005.) [RFC4075] defines the DHCPv6 SNTP Servers option.
RFC4242 (Venaas, S., Chown, T., and B. Volz, “Information Refresh Time Option for Dynamic Host Configuration Protocol for IPv6 (DHCPv6),” November 2005.) [RFC4242] defines the Information Refresh Time option, which advises DHCPv6 Information-Request clients to return for updated information.
RFC4280 (Chowdhury, K., Yegani, P., and L. Madour, “Dynamic Host Configuration Protocol (DHCP) Options for Broadcast and Multicast Control Servers,” November 2005.) [RFC4280] defines two BCMS server options.
RFC4388 (Woundy, R. and K. Kinnear, “Dynamic Host Configuration Protocol (DHCP) Leasequery,” February 2006.) [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 (Volz, B., “Dynamic Host Configuration Protocol for IPv6 (DHCPv6) Relay Agent Subscriber-ID Option,” June 2006.) [RFC4580] defines a DHCPv6 subscriber-id option, which is similar in principle to the DHCPv4 relay agent option of the same name.
RFC4649 (Volz, B., “Dynamic Host Configuration Protocol for IPv6 (DHCPv6) Relay Agent Remote-ID Option,” August 2006.) [RFC4649] defines a DHCPv6 remote-id option, which is similar in principle to the DHCPv4 relay agent remote-id.
| TOC |
RFC3046 (Patrick, M., “DHCP Relay Agent Information Option,” January 2001.) [RFC3046] defines the Relay Agent Information Option and provides a number of sub-option definitions.
RFC3256 (Jones, D. and R. Woundy, “The DOCSIS (Data-Over-Cable Service Interface Specifications) Device Class DHCP (Dynamic Host Configuration Protocol) Relay Agent Information Sub-option,” April 2002.) [RFC3256] defines the DOCSIS Device Class sub-option.
RFC3527 (Kinnear, K., Stapp, M., Johnson, R., and J. Kumarasamy, “Link Selection sub-option for the Relay Agent Information Option for DHCPv4,” April 2003.) [RFC3527] defines the Link Selection sub-option.
| TOC |
The collection of documents that describe the standards-based method to update dns names of DHCP clients starts most easily with RFC4703 (Stapp, M. and B. Volz, “Resolution of Fully Qualified Domain Name (FQDN) Conflicts among Dynamic Host Configuration Protocol (DHCP) Clients,” October 2006.) [RFC4703] to define the overall architecture, travels through RFCs 4702 (Stapp, M., Volz, B., and Y. Rekhter, “The Dynamic Host Configuration Protocol (DHCP) Client Fully Qualified Domain Name (FQDN) Option,” October 2006.) [RFC4702] and 4704 (Volz, B., “The Dynamic Host Configuration Protocol for IPv6 (DHCPv6) Client Fully Qualified Domain Name (FQDN) Option,” October 2006.) [RFC4704] to describe the DHCPv4 and DHCPv6 FQDN options (to carry the client name), and ends up at RFC4701 (Stapp, M., Lemon, T., and A. Gustafsson, “A DNS Resource Record (RR) for Encoding Dynamic Host Configuration Protocol (DHCP) Information (DHCID RR),” October 2006.) [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.
| TOC |
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 (Droms, R., “DHCP Failover Protocol,” March 2003.) [draft‑failover] 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 (Volz, B., Gonczi, S., Lemon, T., and R. Stevens, “DHC Load Balancing Algorithm,” February 2001.) [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).
| TOC |
RFC2939 (Droms, R., “Procedures and IANA Guidelines for Definition of New DHCP Options and Message Types,” September 2000.) [RFC2939] explains how to go about obtaining a new DHCP Option code assignment.
| TOC |
| TOC |
| David W. Hankins | |
| Internet Systems Consortium, Inc. | |
| 950 Charter Street | |
| Redwood City, CA 94063 | |
| Phone: | +1 650 423 1300 |
| Email: | David_Hankins@isc.org |