From ac41c7a480990bfb2ef335f6f892ead5db48f8de Mon Sep 17 00:00:00 2001 From: Kyle Isom Date: Tue, 2 May 2023 23:33:14 +0000 Subject: [PATCH] Starting DHCP packets. --- config/config.go | 36 +- config/path.go | 2 + dhcp/BUILD.bazel | 15 + dhcp/options.go | 46 + dhcp/packet.go | 143 +++ docs/rfc2131.txt | 2523 ++++++++++++++++++++++++++++++++++++++++++++ docs/rfc2132.txt | 1907 +++++++++++++++++++++++++++++++++ docs/rfc3203.txt | 339 ++++++ docs/rfc3397.txt | 451 ++++++++ docs/rfc3442.txt | 507 +++++++++ docs/rfc3942.txt | 395 +++++++ docs/rfc4388.txt | 1515 ++++++++++++++++++++++++++ docs/rfc6926.txt | 2299 ++++++++++++++++++++++++++++++++++++++++ docs/rfc7724.txt | 1571 +++++++++++++++++++++++++++ kdhcpd.yaml | 6 +- server/BUILD.bazel | 1 + server/server.go | 19 +- 17 files changed, 11743 insertions(+), 32 deletions(-) create mode 100644 dhcp/BUILD.bazel create mode 100644 dhcp/options.go create mode 100644 dhcp/packet.go create mode 100644 docs/rfc2131.txt create mode 100644 docs/rfc2132.txt create mode 100644 docs/rfc3203.txt create mode 100644 docs/rfc3397.txt create mode 100644 docs/rfc3442.txt create mode 100644 docs/rfc3942.txt create mode 100644 docs/rfc4388.txt create mode 100644 docs/rfc6926.txt create mode 100644 docs/rfc7724.txt diff --git a/config/config.go b/config/config.go index baac7a5..13f35ee 100644 --- a/config/config.go +++ b/config/config.go @@ -5,7 +5,6 @@ import ( "fmt" "io/ioutil" "net" - "strconv" "git.wntrmute.dev/kyle/kdhcp/log" "gopkg.in/yaml.v2" @@ -42,6 +41,7 @@ func (r *IPRange) ensureV4() (err error) { } type Network struct { + IP net.IP `yaml:"address"` Gateway net.IP `yaml:"gateway"` Mask net.IP `yaml:"mask"` Broadcast net.IP `yaml:"broadcast"` @@ -50,6 +50,11 @@ type Network struct { } func (n *Network) ensureV4() (err error) { + n.IP, err = ensureV4(n.IP) + if err != nil { + return fmt.Errorf("config: IP %w", err) + } + n.Gateway, err = ensureV4(n.Gateway) if err != nil { return fmt.Errorf("config: gateway %w", err) @@ -80,11 +85,10 @@ type ConfigFile struct { } type Config struct { - Version int `yaml:"version"` - Interface string `yaml:"interface"` - Address string `yaml:"address"` - IP net.IP - Port int + Version int `yaml:"version"` + Interface string `yaml:"interface"` + Address string `yaml:"address"` + Port int `yaml:"port"` LeaseFile string `yaml:"lease_file"` Network *Network `yaml:"network"` Pools map[string]*IPRange `yaml:"pools"` @@ -104,26 +108,6 @@ func (cfg *Config) process() (err error) { return fmt.Errorf("config: while looking up interface %s: %w", cfg.Interface, err) } - ip, port, err := net.SplitHostPort(cfg.Address) - if err != nil { - return err - } - - cfg.IP = net.ParseIP(ip) - if cfg.IP == nil { - return fmt.Errorf("config: parsing IP from address %s: %w", cfg.Address, err) - } - - cfg.IP, err = ensureV4(cfg.IP) - if err != nil { - return fmt.Errorf("config: address %w", err) - } - - cfg.Port, err = strconv.Atoi(port) - if err != nil { - return fmt.Errorf("config: invalid port %s: %w", port, err) - } - err = cfg.Network.ensureV4() if err != nil { return err diff --git a/config/path.go b/config/path.go index e0c42e9..3ed5bae 100644 --- a/config/path.go +++ b/config/path.go @@ -13,6 +13,7 @@ func FindConfigPath() string { user, err := user.Current() if err == nil { if homedir := user.HomeDir; homedir != "" { + paths = append(paths, filepath.Join(homedir, "code", "kdhcp", "kdhcpd.yaml")) paths = append(paths, filepath.Join(homedir, ".config", "kdhcp", "kdhcpd.yaml")) } } @@ -20,6 +21,7 @@ func FindConfigPath() string { paths = append(paths, "/etc/kdhcp/kdhcpd.yaml") for _, path := range paths { + log.Debugf("config: looking for config file at %s", path) _, err = os.Stat(path) if os.IsNotExist(err) { continue diff --git a/dhcp/BUILD.bazel b/dhcp/BUILD.bazel new file mode 100644 index 0000000..105bf56 --- /dev/null +++ b/dhcp/BUILD.bazel @@ -0,0 +1,15 @@ +load("@io_bazel_rules_go//go:def.bzl", "go_library") + +go_library( + name = "dhcp", + srcs = [ + "options.go", + "packet.go", + ], + importpath = "git.wntrmute.dev/kyle/kdhcp/dhcp", + visibility = ["//visibility:public"], + deps = [ + "//log", + "@com_github_davecgh_go_spew//spew", + ], +) diff --git a/dhcp/options.go b/dhcp/options.go new file mode 100644 index 0000000..7c8b8dd --- /dev/null +++ b/dhcp/options.go @@ -0,0 +1,46 @@ +package dhcp + +import ( + "errors" + "io" +) + +type OptionTag uint8 + +type Option func(req *BootRequest, r io.Reader) error + +const ( + OptionTagPadding OptionTag = 0 + OptionTagHostName = 12 + OptionTagMessageType = 53 + OptionTagParameterRequestList = 55 + OptionTagEnd = 255 +) + +var optionRegistry = map[OptionTag]Option{ + OptionTagPadding: OptionTag, + OptionTagHostName: OptionHostName, + OptionTagMessageType: OptionMessageType, + OptionTagParameterRequestList: OptionParameterRequestList, + OptionTagEnd: OptionEnd, +} + +func OptionPad(req *BootRequest, r io.Reader) error { + return nil +} + +func OptionHostName(req *BootRequest, r io.Reader) error { + return errors.New("dhcp: option not implemented yet") +} + +func OptionMessageType(req *BootRequest, r io.Reader) error { + return errors.New("dhcp: option not implemented yet") +} + +func OptionParameterRequestList(req *BootRequest, r io.Reader) error { + return errors.New("dhcp: option not implemented yet") +} + +func OptionEnd(req *BootRequest, r io.Reader) error { + return errors.New("dhcp: option not implemented yet") +} diff --git a/dhcp/packet.go b/dhcp/packet.go new file mode 100644 index 0000000..49d9ba5 --- /dev/null +++ b/dhcp/packet.go @@ -0,0 +1,143 @@ +package dhcp + +import ( + "bytes" + "encoding/binary" + "fmt" + "net" + "strings" + + "git.wntrmute.dev/kyle/kdhcp/log" + "github.com/davecgh/go-spew/spew" +) + +const ( + maxHardwareAddrLen = 16 + maxServerName = 64 + maxFileName = 128 +) + +var anyAddr = net.IP([]byte{0, 0, 0, 0}) + +func formatMAC(mac []byte) string { + s := []string{} + for i := 0; i < len(mac); i++ { + s = append(s, fmt.Sprintf("%0x", mac[i:i+1])) + } + + return strings.Join(s, ":") +} + +type BootRequest struct { + MessageType uint8 + HardwareType uint8 + HardwareAddress []byte + Hops uint8 + TransactionID uint32 + SecondsElapsed uint16 + Flags uint16 + ServerName string + FileName string + + ClientIP net.IP + YourIP net.IP + NextIP net.IP + RelayIP net.IP + + DHCPType uint8 // option 53 + HostName string // option 12 + ParameterRequests []string +} + +func (req *BootRequest) Read(packet []byte) error { + buf := bytes.NewBuffer(packet) + read := func(v any) error { + return binary.Read(buf, binary.BigEndian, v) + } + + if err := read(&req.MessageType); err != nil { + return err + } + + if err := read(&req.HardwareType); err != nil { + return err + } + + var hwaLength uint8 + if err := read(&hwaLength); err != nil { + return err + } + + if err := read(&req.Hops); err != nil { + return err + } + + if err := read(&req.TransactionID); err != nil { + return err + } + + if err := read(&req.SecondsElapsed); err != nil { + return err + } + + if err := read(&req.Flags); err != nil { + return err + } + + req.ClientIP = anyAddr[:] + if _, err := buf.Read(req.ClientIP); err != nil { + return err + } + + req.YourIP = anyAddr[:] + if _, err := buf.Read(req.YourIP); err != nil { + return err + } + + req.NextIP = anyAddr[:] + if _, err := buf.Read(req.NextIP); err != nil { + return err + } + + req.RelayIP = anyAddr[:] + if _, err := buf.Read(req.RelayIP); err != nil { + return err + } + + req.HardwareAddress = make([]byte, int(hwaLength)) + if _, err := buf.Read(req.HardwareAddress); err != nil { + return err + } + + hwaPad := make([]byte, maxHardwareAddrLen-hwaLength) + if _, err := buf.Read(hwaPad); err != nil { + return err + } + log.Debugf("padding: %x", hwaPad) + + tempBuf := make([]byte, maxServerName) + if _, err := buf.Read(tempBuf); err != nil { + return err + } + req.ServerName = string(bytes.Trim(tempBuf, "\x00")) + + tempBuf = make([]byte, maxFileName) + if _, err := buf.Read(tempBuf); err != nil { + return err + } + req.FileName = string(bytes.Trim(tempBuf, "\x00")) + + spew.Dump(*req) + return nil +} + +func ReadRequest(pkt []byte) (*BootRequest, error) { + req := &BootRequest{} + err := req.Read(pkt) + if err != nil { + return nil, err + } + + log.Debugf("dhcp: BOOTP request with txid %d for %s", req.TransactionID, formatMAC(req.HardwareAddress)) + return req, nil +} diff --git a/docs/rfc2131.txt b/docs/rfc2131.txt new file mode 100644 index 0000000..f45d9b8 --- /dev/null +++ b/docs/rfc2131.txt @@ -0,0 +1,2523 @@ + + + + + + +Network Working Group R. Droms +Request for Comments: 2131 Bucknell University +Obsoletes: 1541 March 1997 +Category: Standards Track + + Dynamic Host Configuration Protocol + +Status of this memo + + 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. + +Abstract + + The Dynamic Host Configuration Protocol (DHCP) provides a framework + for passing configuration information to hosts on a TCPIP network. + DHCP is based on the Bootstrap Protocol (BOOTP) [7], adding the + capability of automatic allocation of reusable network addresses and + additional configuration options [19]. DHCP captures the behavior of + BOOTP relay agents [7, 21], and DHCP participants can interoperate + with BOOTP participants [9]. + +Table of Contents + + 1. Introduction. . . . . . . . . . . . . . . . . . . . . . . . . 2 + 1.1 Changes to RFC1541. . . . . . . . . . . . . . . . . . . . . . 3 + 1.2 Related Work. . . . . . . . . . . . . . . . . . . . . . . . . 4 + 1.3 Problem definition and issues . . . . . . . . . . . . . . . . 4 + 1.4 Requirements. . . . . . . . . . . . . . . . . . . . . . . . . 5 + 1.5 Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 1.6 Design goals. . . . . . . . . . . . . . . . . . . . . . . . . 6 + 2. Protocol Summary. . . . . . . . . . . . . . . . . . . . . . . 8 + 2.1 Configuration parameters repository . . . . . . . . . . . . . 11 + 2.2 Dynamic allocation of network addresses . . . . . . . . . . . 12 + 3. The Client-Server Protocol. . . . . . . . . . . . . . . . . . 13 + 3.1 Client-server interaction - allocating a network address. . . 13 + 3.2 Client-server interaction - reusing a previously allocated + network address . . . . . . . . . . . . . . . . . . . . . . . 17 + 3.3 Interpretation and representation of time values. . . . . . . 20 + 3.4 Obtaining parameters with externally configured network + address . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 + 3.5 Client parameters in DHCP . . . . . . . . . . . . . . . . . . 21 + 3.6 Use of DHCP in clients with multiple interfaces . . . . . . . 22 + 3.7 When clients should use DHCP. . . . . . . . . . . . . . . . . 22 + 4. Specification of the DHCP client-server protocol. . . . . . . 22 + + + +Droms Standards Track [Page 1] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + 4.1 Constructing and sending DHCP messages. . . . . . . . . . . . 22 + 4.2 DHCP server administrative controls . . . . . . . . . . . . . 25 + 4.3 DHCP server behavior. . . . . . . . . . . . . . . . . . . . . 26 + 4.4 DHCP client behavior. . . . . . . . . . . . . . . . . . . . . 34 + 5. Acknowledgments. . . . . . . . . . . . . . . . . . . . . . . .42 + 6. References . . . . . . . . . . . . . . . . . . . . . . . . . .42 + 7. Security Considerations. . . . . . . . . . . . . . . . . . . .43 + 8. Author's Address . . . . . . . . . . . . . . . . . . . . . . .44 + A. Host Configuration Parameters . . . . . . . . . . . . . . . .45 +List of Figures + 1. Format of a DHCP message . . . . . . . . . . . . . . . . . . . 9 + 2. Format of the 'flags' field. . . . . . . . . . . . . . . . . . 11 + 3. Timeline diagram of messages exchanged between DHCP client and + servers when allocating a new network address. . . . . . . . . 15 + 4. Timeline diagram of messages exchanged between DHCP client and + servers when reusing a previously allocated network address. . 18 + 5. State-transition diagram for DHCP clients. . . . . . . . . . . 34 +List of Tables + 1. Description of fields in a DHCP message. . . . . . . . . . . . 10 + 2. DHCP messages. . . . . . . . . . . . . . . . . . . . . . . . . 14 + 3. Fields and options used by DHCP servers. . . . . . . . . . . . 28 + 4. Client messages from various states. . . . . . . . . . . . . . 33 + 5. Fields and options used by DHCP clients. . . . . . . . . . . . 37 + +1. Introduction + + The Dynamic Host Configuration Protocol (DHCP) provides configuration + parameters to Internet hosts. DHCP consists of two components: a + protocol for delivering host-specific configuration parameters from a + DHCP server to a host and a mechanism for allocation of network + addresses to hosts. + + DHCP is built on a client-server model, where designated DHCP server + hosts allocate network addresses and deliver configuration parameters + to dynamically configured hosts. Throughout the remainder of this + document, the term "server" refers to a host providing initialization + parameters through DHCP, and the term "client" refers to a host + requesting initialization parameters from a DHCP server. + + A host should not act as a DHCP server unless explicitly configured + to do so by a system administrator. The diversity of hardware and + protocol implementations in the Internet would preclude reliable + operation if random hosts were allowed to respond to DHCP requests. + For example, IP requires the setting of many parameters within the + protocol implementation software. Because IP can be used on many + dissimilar kinds of network hardware, values for those parameters + cannot be guessed or assumed to have correct defaults. Also, + distributed address allocation schemes depend on a polling/defense + + + +Droms Standards Track [Page 2] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + mechanism for discovery of addresses that are already in use. IP + hosts may not always be able to defend their network addresses, so + that such a distributed address allocation scheme cannot be + guaranteed to avoid allocation of duplicate network addresses. + + DHCP supports three mechanisms for IP address allocation. In + "automatic allocation", DHCP assigns a permanent IP address to a + client. In "dynamic allocation", DHCP assigns an IP address to a + client for a limited period of time (or until the client explicitly + relinquishes the address). In "manual allocation", a client's IP + address is assigned by the network administrator, and DHCP is used + simply to convey the assigned address to the client. A particular + network will use one or more of these mechanisms, depending on the + policies of the network administrator. + + Dynamic allocation is the only one of the three mechanisms that + allows automatic reuse of an address that is no longer needed by the + client to which it was assigned. Thus, dynamic allocation is + particularly useful for assigning an address to a client that will be + connected to the network only temporarily or for sharing a limited + pool of IP addresses among a group of clients that do not need + permanent IP addresses. Dynamic allocation may also be a good choice + for assigning an IP address to a new client being permanently + connected to a network where IP addresses are sufficiently scarce + that it is important to reclaim them when old clients are retired. + Manual allocation allows DHCP to be used to eliminate the error-prone + process of manually configuring hosts with IP addresses in + environments where (for whatever reasons) it is desirable to manage + IP address assignment outside of the DHCP mechanisms. + + The format of DHCP messages is based on the format of BOOTP messages, + to capture the BOOTP relay agent behavior described as part of the + BOOTP specification [7, 21] and to allow interoperability of existing + BOOTP clients with DHCP servers. Using BOOTP relay agents eliminates + the necessity of having a DHCP server on each physical network + segment. + +1.1 Changes to RFC 1541 + + This document updates the DHCP protocol specification that appears in + RFC1541. A new DHCP message type, DHCPINFORM, has been added; see + section 3.4, 4.3 and 4.4 for details. The classing mechanism for + identifying DHCP clients to DHCP servers has been extended to include + "vendor" classes as defined in sections 4.2 and 4.3. The minimum + lease time restriction has been removed. Finally, many editorial + changes have been made to clarify the text as a result of experience + gained in DHCP interoperability tests. + + + + +Droms Standards Track [Page 3] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + +1.2 Related Work + + There are several Internet protocols and related mechanisms that + address some parts of the dynamic host configuration problem. The + Reverse Address Resolution Protocol (RARP) [10] (through the + extensions defined in the Dynamic RARP (DRARP) [5]) explicitly + addresses the problem of network address discovery, and includes an + automatic IP address assignment mechanism. The Trivial File Transfer + Protocol (TFTP) [20] provides for transport of a boot image from a + boot server. The Internet Control Message Protocol (ICMP) [16] + provides for informing hosts of additional routers via "ICMP + redirect" messages. ICMP also can provide subnet mask information + through the "ICMP mask request" message and other information through + the (obsolete) "ICMP information request" message. Hosts can locate + routers through the ICMP router discovery mechanism [8]. + + BOOTP is a transport mechanism for a collection of configuration + information. BOOTP is also extensible, and official extensions [17] + have been defined for several configuration parameters. Morgan has + proposed extensions to BOOTP for dynamic IP address assignment [15]. + The Network Information Protocol (NIP), used by the Athena project at + MIT, is a distributed mechanism for dynamic IP address assignment + [19]. The Resource Location Protocol RLP [1] provides for location + of higher level services. Sun Microsystems diskless workstations use + a boot procedure that employs RARP, TFTP and an RPC mechanism called + "bootparams" to deliver configuration information and operating + system code to diskless hosts. (Sun Microsystems, Sun Workstation + and SunOS are trademarks of Sun Microsystems, Inc.) Some Sun + networks also use DRARP and an auto-installation mechanism to + automate the configuration of new hosts in an existing network. + + In other related work, the path minimum transmission unit (MTU) + discovery algorithm can determine the MTU of an arbitrary internet + path [14]. The Address Resolution Protocol (ARP) has been proposed + as a transport protocol for resource location and selection [6]. + Finally, the Host Requirements RFCs [3, 4] mention specific + requirements for host reconfiguration and suggest a scenario for + initial configuration of diskless hosts. + +1.3 Problem definition and issues + + DHCP is designed to supply DHCP clients with the configuration + parameters defined in the Host Requirements RFCs. After obtaining + parameters via DHCP, a DHCP client should be able to exchange packets + with any other host in the Internet. The TCP/IP stack parameters + supplied by DHCP are listed in Appendix A. + + + + + +Droms Standards Track [Page 4] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + Not all of these parameters are required for a newly initialized + client. A client and server may negotiate for the transmission of + only those parameters required by the client or specific to a + particular subnet. + + DHCP allows but does not require the configuration of client + parameters not directly related to the IP protocol. DHCP also does + not address registration of newly configured clients with the Domain + Name System (DNS) [12, 13]. + + DHCP is not intended for use in configuring routers. + +1.4 Requirements + + Throughout this document, the words that are used to define the + significance of particular requirements are capitalized. These words + are: + + o "MUST" + + This word or the adjective "REQUIRED" means that the + item is an absolute requirement of this specification. + + o "MUST NOT" + + This phrase means that the item is an absolute prohibition + of this specification. + + o "SHOULD" + + This word or the adjective "RECOMMENDED" means that there + may exist valid reasons in particular circumstances to ignore + this item, but the full implications should be understood and + the case carefully weighed before choosing a different course. + + o "SHOULD NOT" + + This phrase means that there may exist valid reasons in + particular circumstances when the listed behavior is acceptable + or even useful, but the full implications should be understood + and the case carefully weighed before implementing any behavior + described with this label. + + + + + + + + + +Droms Standards Track [Page 5] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + o "MAY" + + This word or the adjective "OPTIONAL" means that this item is + truly optional. One vendor may choose to include the item + because a particular marketplace requires it or because it + enhances the product, for example; another vendor may omit the + same item. + +1.5 Terminology + + This document uses the following terms: + + o "DHCP client" + + A DHCP client is an Internet host using DHCP to obtain + configuration parameters such as a network address. + + o "DHCP server" + + A DHCP server is an Internet host that returns configuration + parameters to DHCP clients. + + o "BOOTP relay agent" + + A BOOTP relay agent or relay agent is an Internet host or router + that passes DHCP messages between DHCP clients and DHCP servers. + DHCP is designed to use the same relay agent behavior as specified + in the BOOTP protocol specification. + + o "binding" + + A binding is a collection of configuration parameters, including + at least an IP address, associated with or "bound to" a DHCP + client. Bindings are managed by DHCP servers. + +1.6 Design goals + + The following list gives general design goals for DHCP. + + o DHCP should be a mechanism rather than a policy. DHCP must + allow local system administrators control over configuration + parameters where desired; e.g., local system administrators + should be able to enforce local policies concerning allocation + and access to local resources where desired. + + + + + + + +Droms Standards Track [Page 6] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + o Clients should require no manual configuration. Each client + should be able to discover appropriate local configuration + parameters without user intervention and incorporate those + parameters into its own configuration. + + o Networks should require no manual configuration for individual + clients. Under normal circumstances, the network manager + should not have to enter any per-client configuration + parameters. + + o DHCP should not require a server on each subnet. To allow for + scale and economy, DHCP must work across routers or through the + intervention of BOOTP relay agents. + + o A DHCP client must be prepared to receive multiple responses + to a request for configuration parameters. Some installations + may include multiple, overlapping DHCP servers to enhance + reliability and increase performance. + + o DHCP must coexist with statically configured, non-participating + hosts and with existing network protocol implementations. + + o DHCP must interoperate with the BOOTP relay agent behavior as + described by RFC 951 and by RFC 1542 [21]. + + o DHCP must provide service to existing BOOTP clients. + + The following list gives design goals specific to the transmission of + the network layer parameters. DHCP must: + + o Guarantee that any specific network address will not be in + use by more than one DHCP client at a time, + + o Retain DHCP client configuration across DHCP client reboot. A + DHCP client should, whenever possible, be assigned the same + configuration parameters (e.g., network address) in response + to each request, + + o Retain DHCP client configuration across server reboots, and, + whenever possible, a DHCP client should be assigned the same + configuration parameters despite restarts of the DHCP mechanism, + + o Allow automated assignment of configuration parameters to new + clients to avoid hand configuration for new clients, + + o Support fixed or permanent allocation of configuration + parameters to specific clients. + + + + +Droms Standards Track [Page 7] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + +2. Protocol Summary + + From the client's point of view, DHCP is an extension of the BOOTP + mechanism. This behavior allows existing BOOTP clients to + interoperate with DHCP servers without requiring any change to the + clients' initialization software. RFC 1542 [2] details the + interactions between BOOTP and DHCP clients and servers [9]. There + are some new, optional transactions that optimize the interaction + between DHCP clients and servers that are described in sections 3 and + 4. + + Figure 1 gives the format of a DHCP message and table 1 describes + each of the fields in the DHCP message. The numbers in parentheses + indicate the size of each field in octets. The names for the fields + given in the figure will be used throughout this document to refer to + the fields in DHCP messages. + + There are two primary differences between DHCP and BOOTP. First, + DHCP defines mechanisms through which clients can be assigned a + network address for a finite lease, allowing for serial reassignment + of network addresses to different clients. Second, DHCP provides the + mechanism for a client to acquire all of the IP configuration + parameters that it needs in order to operate. + + DHCP introduces a small change in terminology intended to clarify the + meaning of one of the fields. What was the "vendor extensions" field + in BOOTP has been re-named the "options" field in DHCP. Similarly, + the tagged data items that were used inside the BOOTP "vendor + extensions" field, which were formerly referred to as "vendor + extensions," are now termed simply "options." + + + + + + + + + + + + + + + + + + + + + +Droms Standards Track [Page 8] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | op (1) | htype (1) | hlen (1) | hops (1) | + +---------------+---------------+---------------+---------------+ + | xid (4) | + +-------------------------------+-------------------------------+ + | secs (2) | flags (2) | + +-------------------------------+-------------------------------+ + | ciaddr (4) | + +---------------------------------------------------------------+ + | yiaddr (4) | + +---------------------------------------------------------------+ + | siaddr (4) | + +---------------------------------------------------------------+ + | giaddr (4) | + +---------------------------------------------------------------+ + | | + | chaddr (16) | + | | + | | + +---------------------------------------------------------------+ + | | + | sname (64) | + +---------------------------------------------------------------+ + | | + | file (128) | + +---------------------------------------------------------------+ + | | + | options (variable) | + +---------------------------------------------------------------+ + + Figure 1: Format of a DHCP message + + DHCP defines a new 'client identifier' option that is used to pass an + explicit client identifier to a DHCP server. This change eliminates + the overloading of the 'chaddr' field in BOOTP messages, where + 'chaddr' is used both as a hardware address for transmission of BOOTP + reply messages and as a client identifier. The 'client identifier' + is an opaque key, not to be interpreted by the server; for example, + the 'client identifier' may contain a hardware address, identical to + the contents of the 'chaddr' field, or it may contain another type of + identifier, such as a DNS name. The 'client identifier' chosen by a + DHCP client MUST be unique to that client within the subnet to which + the client is attached. If the client uses a 'client identifier' in + one message, it MUST use that same identifier in all subsequent + messages, to ensure that all servers correctly identify the client. + + + + +Droms Standards Track [Page 9] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + DHCP clarifies the interpretation of the 'siaddr' field as the + address of the server to use in the next step of the client's + bootstrap process. A DHCP server may return its own address in the + 'siaddr' field, if the server is prepared to supply the next + bootstrap service (e.g., delivery of an operating system executable + image). A DHCP server always returns its own address in the 'server + identifier' option. + + FIELD OCTETS DESCRIPTION + ----- ------ ----------- + + op 1 Message op code / message type. + 1 = BOOTREQUEST, 2 = BOOTREPLY + htype 1 Hardware address type, see ARP section in "Assigned + Numbers" RFC; e.g., '1' = 10mb ethernet. + hlen 1 Hardware address length (e.g. '6' for 10mb + ethernet). + hops 1 Client sets to zero, optionally used by relay agents + when booting via a relay agent. + xid 4 Transaction ID, a random number chosen by the + client, used by the client and server to associate + messages and responses between a client and a + server. + secs 2 Filled in by client, seconds elapsed since client + began address acquisition or renewal process. + flags 2 Flags (see figure 2). + ciaddr 4 Client IP address; only filled in if client is in + BOUND, RENEW or REBINDING state and can respond + to ARP requests. + yiaddr 4 'your' (client) IP address. + siaddr 4 IP address of next server to use in bootstrap; + returned in DHCPOFFER, DHCPACK by server. + giaddr 4 Relay agent IP address, used in booting via a + relay agent. + chaddr 16 Client hardware address. + sname 64 Optional server host name, null terminated string. + file 128 Boot file name, null terminated string; "generic" + name or null in DHCPDISCOVER, fully qualified + directory-path name in DHCPOFFER. + options var Optional parameters field. See the options + documents for a list of defined options. + + Table 1: Description of fields in a DHCP message + + The 'options' field is now variable length. A DHCP client must be + prepared to receive DHCP messages with an 'options' field of at least + length 312 octets. This requirement implies that a DHCP client must + be prepared to receive a message of up to 576 octets, the minimum IP + + + +Droms Standards Track [Page 10] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + datagram size an IP host must be prepared to accept [3]. DHCP + clients may negotiate the use of larger DHCP messages through the + 'maximum DHCP message size' option. The options field may be further + extended into the 'file' and 'sname' fields. + + In the case of a client using DHCP for initial configuration (before + the client's TCP/IP software has been completely configured), DHCP + requires creative use of the client's TCP/IP software and liberal + interpretation of RFC 1122. The TCP/IP software SHOULD accept and + forward to the IP layer any IP packets delivered to the client's + hardware address before the IP address is configured; DHCP servers + and BOOTP relay agents may not be able to deliver DHCP messages to + clients that cannot accept hardware unicast datagrams before the + TCP/IP software is configured. + + To work around some clients that cannot accept IP unicast datagrams + before the TCP/IP software is configured as discussed in the previous + paragraph, DHCP uses the 'flags' field [21]. The leftmost bit is + defined as the BROADCAST (B) flag. The semantics of this flag are + discussed in section 4.1 of this document. The remaining bits of the + flags field are reserved for future use. They MUST be set to zero by + clients and ignored by servers and relay agents. Figure 2 gives the + format of the 'flags' field. + + 1 1 1 1 1 1 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + |B| MBZ | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + B: BROADCAST flag + + MBZ: MUST BE ZERO (reserved for future use) + + Figure 2: Format of the 'flags' field + +2.1 Configuration parameters repository + + The first service provided by DHCP is to provide persistent storage + of network parameters for network clients. The model of DHCP + persistent storage is that the DHCP service stores a key-value entry + for each client, where the key is some unique identifier (for + example, an IP subnet number and a unique identifier within the + subnet) and the value contains the configuration parameters for the + client. + + For example, the key might be the pair (IP-subnet-number, hardware- + address) (note that the "hardware-address" should be typed by the + + + +Droms Standards Track [Page 11] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + type of hardware to accommodate possible duplication of hardware + addresses resulting from bit-ordering problems in a mixed-media, + bridged network) allowing for serial or concurrent reuse of a + hardware address on different subnets, and for hardware addresses + that may not be globally unique. Alternately, the key might be the + pair (IP-subnet-number, hostname), allowing the server to assign + parameters intelligently to a DHCP client that has been moved to a + different subnet or has changed hardware addresses (perhaps because + the network interface failed and was replaced). The protocol defines + that the key will be (IP-subnet-number, hardware-address) unless the + client explicitly supplies an identifier using the 'client + identifier' option. A client can query the DHCP service to + retrieve its configuration parameters. The client interface to the + configuration parameters repository consists of protocol messages to + request configuration parameters and responses from the server + carrying the configuration parameters. + +2.2 Dynamic allocation of network addresses + + The second service provided by DHCP is the allocation of temporary or + permanent network (IP) addresses to clients. The basic mechanism for + the dynamic allocation of network addresses is simple: a client + requests the use of an address for some period of time. The + allocation mechanism (the collection of DHCP servers) guarantees not + to reallocate that address within the requested time and attempts to + return the same network address each time the client requests an + address. In this document, the period over which a network address + is allocated to a client is referred to as a "lease" [11]. The + client may extend its lease with subsequent requests. The client may + issue a message to release the address back to the server when the + client no longer needs the address. The client may ask for a + permanent assignment by asking for an infinite lease. Even when + assigning "permanent" addresses, a server may choose to give out + lengthy but non-infinite leases to allow detection of the fact that + the client has been retired. + + In some environments it will be necessary to reassign network + addresses due to exhaustion of available addresses. In such + environments, the allocation mechanism will reuse addresses whose + lease has expired. The server should use whatever information is + available in the configuration information repository to choose an + address to reuse. For example, the server may choose the least + recently assigned address. As a consistency check, the allocating + server SHOULD probe the reused address before allocating the address, + e.g., with an ICMP echo request, and the client SHOULD probe the + newly received address, e.g., with ARP. + + + + + +Droms Standards Track [Page 12] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + +3. The Client-Server Protocol + + DHCP uses the BOOTP message format defined in RFC 951 and given in + table 1 and figure 1. The 'op' field of each DHCP message sent from + a client to a server contains BOOTREQUEST. BOOTREPLY is used in the + 'op' field of each DHCP message sent from a server to a client. + + The first four octets of the 'options' field of the DHCP message + contain the (decimal) values 99, 130, 83 and 99, respectively (this + is the same magic cookie as is defined in RFC 1497 [17]). The + remainder of the 'options' field consists of a list of tagged + parameters that are called "options". All of the "vendor extensions" + listed in RFC 1497 are also DHCP options. RFC 1533 gives the + complete set of options defined for use with DHCP. + + Several options have been defined so far. One particular option - + the "DHCP message type" option - must be included in every DHCP + message. This option defines the "type" of the DHCP message. + Additional options may be allowed, required, or not allowed, + depending on the DHCP message type. + + Throughout this document, DHCP messages that include a 'DHCP message + type' option will be referred to by the type of the message; e.g., a + DHCP message with 'DHCP message type' option type 1 will be referred + to as a "DHCPDISCOVER" message. + +3.1 Client-server interaction - allocating a network address + + The following summary of the protocol exchanges between clients and + servers refers to the DHCP messages described in table 2. The + timeline diagram in figure 3 shows the timing relationships in a + typical client-server interaction. If the client already knows its + address, some steps may be omitted; this abbreviated interaction is + described in section 3.2. + + 1. The client broadcasts a DHCPDISCOVER message on its local physical + subnet. The DHCPDISCOVER message MAY include options that suggest + values for the network address and lease duration. BOOTP relay + agents may pass the message on to DHCP servers not on the same + physical subnet. + + 2. Each server may respond with a DHCPOFFER message that includes an + available network address in the 'yiaddr' field (and other + configuration parameters in DHCP options). Servers need not + reserve the offered network address, although the protocol will + work more efficiently if the server avoids allocating the offered + network address to another client. When allocating a new address, + servers SHOULD check that the offered network address is not + + + +Droms Standards Track [Page 13] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + already in use; e.g., the server may probe the offered address + with an ICMP Echo Request. Servers SHOULD be implemented so that + network administrators MAY choose to disable probes of newly + allocated addresses. The server transmits the DHCPOFFER message + to the client, using the BOOTP relay agent if necessary. + + Message Use + ------- --- + + DHCPDISCOVER - Client broadcast to locate available servers. + + DHCPOFFER - Server to client in response to DHCPDISCOVER with + offer of configuration parameters. + + DHCPREQUEST - Client message to servers either (a) requesting + offered parameters from one server and implicitly + declining offers from all others, (b) confirming + correctness of previously allocated address after, + e.g., system reboot, or (c) extending the lease on a + particular network address. + + DHCPACK - Server to client with configuration parameters, + including committed network address. + + DHCPNAK - Server to client indicating client's notion of network + address is incorrect (e.g., client has moved to new + subnet) or client's lease as expired + + DHCPDECLINE - Client to server indicating network address is already + in use. + + DHCPRELEASE - Client to server relinquishing network address and + cancelling remaining lease. + + DHCPINFORM - Client to server, asking only for local configuration + parameters; client already has externally configured + network address. + + Table 2: DHCP messages + + + + + + + + + + + + +Droms Standards Track [Page 14] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + Server Client Server + (not selected) (selected) + + v v v + | | | + | Begins initialization | + | | | + | _____________/|\____________ | + |/DHCPDISCOVER | DHCPDISCOVER \| + | | | + Determines | Determines + configuration | configuration + | | | + |\ | ____________/ | + | \________ | /DHCPOFFER | + | DHCPOFFER\ |/ | + | \ | | + | Collects replies | + | \| | + | Selects configuration | + | | | + | _____________/|\____________ | + |/ DHCPREQUEST | DHCPREQUEST\ | + | | | + | | Commits configuration + | | | + | | _____________/| + | |/ DHCPACK | + | | | + | Initialization complete | + | | | + . . . + . . . + | | | + | Graceful shutdown | + | | | + | |\ ____________ | + | | DHCPRELEASE \| + | | | + | | Discards lease + | | | + v v v + Figure 3: Timeline diagram of messages exchanged between DHCP + client and servers when allocating a new network address + + + + + + + +Droms Standards Track [Page 15] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + 3. The client receives one or more DHCPOFFER messages from one or more + servers. The client may choose to wait for multiple responses. + The client chooses one server from which to request configuration + parameters, based on the configuration parameters offered in the + DHCPOFFER messages. The client broadcasts a DHCPREQUEST message + that MUST include the 'server identifier' option to indicate which + server it has selected, and that MAY include other options + specifying desired configuration values. The 'requested IP + address' option MUST be set to the value of 'yiaddr' in the + DHCPOFFER message from the server. This DHCPREQUEST message is + broadcast and relayed through DHCP/BOOTP relay agents. To help + ensure that any BOOTP relay agents forward the DHCPREQUEST message + to the same set of DHCP servers that received the original + DHCPDISCOVER message, the DHCPREQUEST message MUST use the same + value in the DHCP message header's 'secs' field and be sent to the + same IP broadcast address as the original DHCPDISCOVER message. + The client times out and retransmits the DHCPDISCOVER message if + the client receives no DHCPOFFER messages. + + 4. The servers receive the DHCPREQUEST broadcast from the client. + Those servers not selected by the DHCPREQUEST message use the + message as notification that the client has declined that server's + offer. The server selected in the DHCPREQUEST message commits the + binding for the client to persistent storage and responds with a + DHCPACK message containing the configuration parameters for the + requesting client. The combination of 'client identifier' or + 'chaddr' and assigned network address constitute a unique + identifier for the client's lease and are used by both the client + and server to identify a lease referred to in any DHCP messages. + Any configuration parameters in the DHCPACK message SHOULD NOT + conflict with those in the earlier DHCPOFFER message to which the + client is responding. The server SHOULD NOT check the offered + network address at this point. The 'yiaddr' field in the DHCPACK + messages is filled in with the selected network address. + + If the selected server is unable to satisfy the DHCPREQUEST message + (e.g., the requested network address has been allocated), the + server SHOULD respond with a DHCPNAK message. + + A server MAY choose to mark addresses offered to clients in + DHCPOFFER messages as unavailable. The server SHOULD mark an + address offered to a client in a DHCPOFFER message as available if + the server receives no DHCPREQUEST message from that client. + + 5. The client receives the DHCPACK message with configuration + parameters. The client SHOULD perform a final check on the + parameters (e.g., ARP for allocated network address), and notes the + duration of the lease specified in the DHCPACK message. At this + + + +Droms Standards Track [Page 16] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + point, the client is configured. If the client detects that the + address is already in use (e.g., through the use of ARP), the + client MUST send a DHCPDECLINE message to the server and restarts + the configuration process. The client SHOULD wait a minimum of ten + seconds before restarting the configuration process to avoid + excessive network traffic in case of looping. + + If the client receives a DHCPNAK message, the client restarts the + configuration process. + + The client times out and retransmits the DHCPREQUEST message if the + client receives neither a DHCPACK or a DHCPNAK message. The client + retransmits the DHCPREQUEST according to the retransmission + algorithm in section 4.1. The client should choose to retransmit + the DHCPREQUEST enough times to give adequate probability of + contacting the server without causing the client (and the user of + that client) to wait overly long before giving up; e.g., a client + retransmitting as described in section 4.1 might retransmit the + DHCPREQUEST message four times, for a total delay of 60 seconds, + before restarting the initialization procedure. If the client + receives neither a DHCPACK or a DHCPNAK message after employing the + retransmission algorithm, the client reverts to INIT state and + restarts the initialization process. The client SHOULD notify the + user that the initialization process has failed and is restarting. + + 6. The client may choose to relinquish its lease on a network address + by sending a DHCPRELEASE message to the server. The client + identifies the lease to be released with its 'client identifier', + or 'chaddr' and network address in the DHCPRELEASE message. If the + client used a 'client identifier' when it obtained the lease, it + MUST use the same 'client identifier' in the DHCPRELEASE message. + +3.2 Client-server interaction - reusing a previously allocated network + address + + If a client remembers and wishes to reuse a previously allocated + network address, a client may choose to omit some of the steps + described in the previous section. The timeline diagram in figure 4 + shows the timing relationships in a typical client-server interaction + for a client reusing a previously allocated network address. + + + + + + + + + + + +Droms Standards Track [Page 17] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + 1. The client broadcasts a DHCPREQUEST message on its local subnet. + The message includes the client's network address in the + 'requested IP address' option. As the client has not received its + network address, it MUST NOT fill in the 'ciaddr' field. BOOTP + relay agents pass the message on to DHCP servers not on the same + subnet. If the client used a 'client identifier' to obtain its + address, the client MUST use the same 'client identifier' in the + DHCPREQUEST message. + + 2. Servers with knowledge of the client's configuration parameters + respond with a DHCPACK message to the client. Servers SHOULD NOT + check that the client's network address is already in use; the + client may respond to ICMP Echo Request messages at this point. + + Server Client Server + + v v v + | | | + | Begins | + | initialization | + | | | + | /|\ | + | _________ __/ | \__________ | + | /DHCPREQU EST | DHCPREQUEST\ | + |/ | \| + | | | + Locates | Locates + configuration | configuration + | | | + |\ | /| + | \ | ___________/ | + | \ | / DHCPACK | + | \ _______ |/ | + | DHCPACK\ | | + | Initialization | + | complete | + | \| | + | | | + | (Subsequent | + | DHCPACKS | + | ignored) | + | | | + | | | + v v v + + Figure 4: Timeline diagram of messages exchanged between DHCP + client and servers when reusing a previously allocated + network address + + + +Droms Standards Track [Page 18] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + If the client's request is invalid (e.g., the client has moved + to a new subnet), servers SHOULD respond with a DHCPNAK message to + the client. Servers SHOULD NOT respond if their information is not + guaranteed to be accurate. For example, a server that identifies a + request for an expired binding that is owned by another server SHOULD + NOT respond with a DHCPNAK unless the servers are using an explicit + mechanism to maintain coherency among the servers. + + If 'giaddr' is 0x0 in the DHCPREQUEST message, the client is on + the same subnet as the server. The server MUST + broadcast the DHCPNAK message to the 0xffffffff broadcast address + because the client may not have a correct network address or subnet + mask, and the client may not be answering ARP requests. + Otherwise, the server MUST send the DHCPNAK message to the IP + address of the BOOTP relay agent, as recorded in 'giaddr'. The + relay agent will, in turn, forward the message directly to the + client's hardware address, so that the DHCPNAK can be delivered even + if the client has moved to a new network. + + 3. The client receives the DHCPACK message with configuration + parameters. The client performs a final check on the parameters + (as in section 3.1), and notes the duration of the lease specified + in the DHCPACK message. The specific lease is implicitly identified + by the 'client identifier' or 'chaddr' and the network address. At + this point, the client is configured. + + If the client detects that the IP address in the DHCPACK message + is already in use, the client MUST send a DHCPDECLINE message to the + server and restarts the configuration process by requesting a + new network address. This action corresponds to the client + moving to the INIT state in the DHCP state diagram, which is + described in section 4.4. + + If the client receives a DHCPNAK message, it cannot reuse its + remembered network address. It must instead request a new + address by restarting the configuration process, this time + using the (non-abbreviated) procedure described in section + 3.1. This action also corresponds to the client moving to + the INIT state in the DHCP state diagram. + + The client times out and retransmits the DHCPREQUEST message if + the client receives neither a DHCPACK nor a DHCPNAK message. The + client retransmits the DHCPREQUEST according to the retransmission + algorithm in section 4.1. The client should choose to retransmit + the DHCPREQUEST enough times to give adequate probability of + contacting the server without causing the client (and the user of + that client) to wait overly long before giving up; e.g., a client + retransmitting as described in section 4.1 might retransmit the + + + +Droms Standards Track [Page 19] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + DHCPREQUEST message four times, for a total delay of 60 seconds, + before restarting the initialization procedure. If the client + receives neither a DHCPACK or a DHCPNAK message after employing + the retransmission algorithm, the client MAY choose to use the + previously allocated network address and configuration parameters + for the remainder of the unexpired lease. This corresponds to + moving to BOUND state in the client state transition diagram shown + in figure 5. + + 4. The client may choose to relinquish its lease on a network + address by sending a DHCPRELEASE message to the server. The + client identifies the lease to be released with its + 'client identifier', or 'chaddr' and network address in the + DHCPRELEASE message. + + Note that in this case, where the client retains its network + address locally, the client will not normally relinquish its + lease during a graceful shutdown. Only in the case where the + client explicitly needs to relinquish its lease, e.g., the client + is about to be moved to a different subnet, will the client send + a DHCPRELEASE message. + +3.3 Interpretation and representation of time values + + A client acquires a lease for a network address for a fixed period of + time (which may be infinite). Throughout the protocol, times are to + be represented in units of seconds. The time value of 0xffffffff is + reserved to represent "infinity". + + As clients and servers may not have synchronized clocks, times are + represented in DHCP messages as relative times, to be interpreted + with respect to the client's local clock. Representing relative + times in units of seconds in an unsigned 32 bit word gives a range of + relative times from 0 to approximately 100 years, which is sufficient + for the relative times to be measured using DHCP. + + The algorithm for lease duration interpretation given in the previous + paragraph assumes that client and server clocks are stable relative + to each other. If there is drift between the two clocks, the server + may consider the lease expired before the client does. To + compensate, the server may return a shorter lease duration to the + client than the server commits to its local database of client + information. + +3.4 Obtaining parameters with externally configured network address + + If a client has obtained a network address through some other means + (e.g., manual configuration), it may use a DHCPINFORM request message + + + +Droms Standards Track [Page 20] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + to obtain other local configuration parameters. Servers receiving a + DHCPINFORM message construct a DHCPACK message with any local + configuration parameters appropriate for the client without: + allocating a new address, checking for an existing binding, filling + in 'yiaddr' or including lease time parameters. The servers SHOULD + unicast the DHCPACK reply to the address given in the 'ciaddr' field + of the DHCPINFORM message. + + The server SHOULD check the network address in a DHCPINFORM message + for consistency, but MUST NOT check for an existing lease. The + server forms a DHCPACK message containing the configuration + parameters for the requesting client and sends the DHCPACK message + directly to the client. + +3.5 Client parameters in DHCP + + Not all clients require initialization of all parameters listed in + Appendix A. Two techniques are used to reduce the number of + parameters transmitted from the server to the client. First, most of + the parameters have defaults defined in the Host Requirements RFCs; + if the client receives no parameters from the server that override + the defaults, a client uses those default values. Second, in its + initial DHCPDISCOVER or DHCPREQUEST message, a client may provide the + server with a list of specific parameters the client is interested + in. If the client includes a list of parameters in a DHCPDISCOVER + message, it MUST include that list in any subsequent DHCPREQUEST + messages. + + The client SHOULD include the 'maximum DHCP message size' option to + let the server know how large the server may make its DHCP messages. + The parameters returned to a client may still exceed the space + allocated to options in a DHCP message. In this case, two additional + options flags (which must appear in the 'options' field of the + message) indicate that the 'file' and 'sname' fields are to be used + for options. + + The client can inform the server which configuration parameters the + client is interested in by including the 'parameter request list' + option. The data portion of this option explicitly lists the options + requested by tag number. + + In addition, the client may suggest values for the network address + and lease time in the DHCPDISCOVER message. The client may include + the 'requested IP address' option to suggest that a particular IP + address be assigned, and may include the 'IP address lease time' + option to suggest the lease time it would like. Other options + representing "hints" at configuration parameters are allowed in a + DHCPDISCOVER or DHCPREQUEST message. However, additional options may + + + +Droms Standards Track [Page 21] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + be ignored by servers, and multiple servers may, therefore, not + return identical values for some options. The 'requested IP address' + option is to be filled in only in a DHCPREQUEST message when the + client is verifying network parameters obtained previously. The + client fills in the 'ciaddr' field only when correctly configured + with an IP address in BOUND, RENEWING or REBINDING state. + + If a server receives a DHCPREQUEST message with an invalid 'requested + IP address', the server SHOULD respond to the client with a DHCPNAK + message and may choose to report the problem to the system + administrator. The server may include an error message in the + 'message' option. + +3.6 Use of DHCP in clients with multiple interfaces + + A client with multiple network interfaces must use DHCP through each + interface independently to obtain configuration information + parameters for those separate interfaces. + +3.7 When clients should use DHCP + + A client SHOULD use DHCP to reacquire or verify its IP address and + network parameters whenever the local network parameters may have + changed; e.g., at system boot time or after a disconnection from the + local network, as the local network configuration may change without + the client's or user's knowledge. + + If a client has knowledge of a previous network address and is unable + to contact a local DHCP server, the client may continue to use the + previous network address until the lease for that address expires. + If the lease expires before the client can contact a DHCP server, the + client must immediately discontinue use of the previous network + address and may inform local users of the problem. + +4. Specification of the DHCP client-server protocol + + In this section, we assume that a DHCP server has a block of network + addresses from which it can satisfy requests for new addresses. Each + server also maintains a database of allocated addresses and leases in + local permanent storage. + +4.1 Constructing and sending DHCP messages + + DHCP clients and servers both construct DHCP messages by filling in + fields in the fixed format section of the message and appending + tagged data items in the variable length option area. The options + area includes first a four-octet 'magic cookie' (which was described + in section 3), followed by the options. The last option must always + + + +Droms Standards Track [Page 22] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + be the 'end' option. + + DHCP uses UDP as its transport protocol. DHCP messages from a client + to a server are sent to the 'DHCP server' port (67), and DHCP + messages from a server to a client are sent to the 'DHCP client' port + (68). A server with multiple network address (e.g., a multi-homed + host) MAY use any of its network addresses in outgoing DHCP messages. + + The 'server identifier' field is used both to identify a DHCP server + in a DHCP message and as a destination address from clients to + servers. A server with multiple network addresses MUST be prepared + to to accept any of its network addresses as identifying that server + in a DHCP message. To accommodate potentially incomplete network + connectivity, a server MUST choose an address as a 'server + identifier' that, to the best of the server's knowledge, is reachable + from the client. For example, if the DHCP server and the DHCP client + are connected to the same subnet (i.e., the 'giaddr' field in the + message from the client is zero), the server SHOULD select the IP + address the server is using for communication on that subnet as the + 'server identifier'. If the server is using multiple IP addresses on + that subnet, any such address may be used. If the server has + received a message through a DHCP relay agent, the server SHOULD + choose an address from the interface on which the message was + recieved as the 'server identifier' (unless the server has other, + better information on which to make its choice). DHCP clients MUST + use the IP address provided in the 'server identifier' option for any + unicast requests to the DHCP server. + + DHCP messages broadcast by a client prior to that client obtaining + its IP address must have the source address field in the IP header + set to 0. + + If the 'giaddr' field in a DHCP message from a client is non-zero, + the server sends any return messages to the 'DHCP server' port on the + BOOTP relay agent whose address appears in 'giaddr'. If the 'giaddr' + field is zero and the 'ciaddr' field is nonzero, then the server + unicasts DHCPOFFER and DHCPACK messages to the address in 'ciaddr'. + If 'giaddr' is zero and 'ciaddr' is zero, and the broadcast bit is + set, then the server broadcasts DHCPOFFER and DHCPACK messages to + 0xffffffff. If the broadcast bit is not set and 'giaddr' is zero and + 'ciaddr' is zero, then the server unicasts DHCPOFFER and DHCPACK + messages to the client's hardware address and 'yiaddr' address. In + all cases, when 'giaddr' is zero, the server broadcasts any DHCPNAK + messages to 0xffffffff. + + If the options in a DHCP message extend into the 'sname' and 'file' + fields, the 'option overload' option MUST appear in the 'options' + field, with value 1, 2 or 3, as specified in RFC 1533. If the + + + +Droms Standards Track [Page 23] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + 'option overload' option is present in the 'options' field, the + options in the 'options' field MUST be terminated by an 'end' option, + and MAY contain one or more 'pad' options to fill the options field. + The options in the 'sname' and 'file' fields (if in use as indicated + by the 'options overload' option) MUST begin with the first octet of + the field, MUST be terminated by an 'end' option, and MUST be + followed by 'pad' options to fill the remainder of the field. Any + individual option in the 'options', 'sname' and 'file' fields MUST be + entirely contained in that field. The options in the 'options' field + MUST be interpreted first, so that any 'option overload' options may + be interpreted. The 'file' field MUST be interpreted next (if the + 'option overload' option indicates that the 'file' field contains + DHCP options), followed by the 'sname' field. + + The values to be passed in an 'option' tag may be too long to fit in + the 255 octets available to a single option (e.g., a list of routers + in a 'router' option [21]). Options may appear only once, unless + otherwise specified in the options document. The client concatenates + the values of multiple instances of the same option into a single + parameter list for configuration. + + DHCP clients are responsible for all message retransmission. The + client MUST adopt a retransmission strategy that incorporates a + randomized exponential backoff algorithm to determine the delay + between retransmissions. The delay between retransmissions SHOULD be + chosen to allow sufficient time for replies from the server to be + delivered based on the characteristics of the internetwork between + the client and the server. For example, in a 10Mb/sec Ethernet + internetwork, the delay before the first retransmission SHOULD be 4 + seconds randomized by the value of a uniform random number chosen + from the range -1 to +1. Clients with clocks that provide resolution + granularity of less than one second may choose a non-integer + randomization value. The delay before the next retransmission SHOULD + be 8 seconds randomized by the value of a uniform number chosen from + the range -1 to +1. The retransmission delay SHOULD be doubled with + subsequent retransmissions up to a maximum of 64 seconds. The client + MAY provide an indication of retransmission attempts to the user as + an indication of the progress of the configuration process. + + The 'xid' field is used by the client to match incoming DHCP messages + with pending requests. A DHCP client MUST choose 'xid's in such a + way as to minimize the chance of using an 'xid' identical to one used + by another client. For example, a client may choose a different, + random initial 'xid' each time the client is rebooted, and + subsequently use sequential 'xid's until the next reboot. Selecting + a new 'xid' for each retransmission is an implementation decision. A + client may choose to reuse the same 'xid' or select a new 'xid' for + each retransmitted message. + + + +Droms Standards Track [Page 24] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + Normally, DHCP servers and BOOTP relay agents attempt to deliver + DHCPOFFER, DHCPACK and DHCPNAK messages directly to the client using + uicast delivery. The IP destination address (in the IP header) is + set to the DHCP 'yiaddr' address and the link-layer destination + address is set to the DHCP 'chaddr' address. Unfortunately, some + client implementations are unable to receive such unicast IP + datagrams until the implementation has been configured with a valid + IP address (leading to a deadlock in which the client's IP address + cannot be delivered until the client has been configured with an IP + address). + + A client that cannot receive unicast IP datagrams until its protocol + software has been configured with an IP address SHOULD set the + BROADCAST bit in the 'flags' field to 1 in any DHCPDISCOVER or + DHCPREQUEST messages that client sends. The BROADCAST bit will + provide a hint to the DHCP server and BOOTP relay agent to broadcast + any messages to the client on the client's subnet. A client that can + receive unicast IP datagrams before its protocol software has been + configured SHOULD clear the BROADCAST bit to 0. The BOOTP + clarifications document discusses the ramifications of the use of the + BROADCAST bit [21]. + + A server or relay agent sending or relaying a DHCP message directly + to a DHCP client (i.e., not to a relay agent specified in the + 'giaddr' field) SHOULD examine the BROADCAST bit in the 'flags' + field. If this bit is set to 1, the DHCP message SHOULD be sent as + an IP broadcast using an IP broadcast address (preferably 0xffffffff) + as the IP destination address and the link-layer broadcast address as + the link-layer destination address. If the BROADCAST bit is cleared + to 0, the message SHOULD be sent as an IP unicast to the IP address + specified in the 'yiaddr' field and the link-layer address specified + in the 'chaddr' field. If unicasting is not possible, the message + MAY be sent as an IP broadcast using an IP broadcast address + (preferably 0xffffffff) as the IP destination address and the link- + layer broadcast address as the link-layer destination address. + +4.2 DHCP server administrative controls + + DHCP servers are not required to respond to every DHCPDISCOVER and + DHCPREQUEST message they receive. For example, a network + administrator, to retain stringent control over the clients attached + to the network, may choose to configure DHCP servers to respond only + to clients that have been previously registered through some external + mechanism. The DHCP specification describes only the interactions + between clients and servers when the clients and servers choose to + interact; it is beyond the scope of the DHCP specification to + describe all of the administrative controls that system + administrators might want to use. Specific DHCP server + + + +Droms Standards Track [Page 25] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + implementations may incorporate any controls or policies desired by a + network administrator. + + In some environments, a DHCP server will have to consider the values + of the vendor class options included in DHCPDISCOVER or DHCPREQUEST + messages when determining the correct parameters for a particular + client. + + A DHCP server needs to use some unique identifier to associate a + client with its lease. The client MAY choose to explicitly provide + the identifier through the 'client identifier' option. If the client + supplies a 'client identifier', the client MUST use the same 'client + identifier' in all subsequent messages, and the server MUST use that + identifier to identify the client. If the client does not provide a + 'client identifier' option, the server MUST use the contents of the + 'chaddr' field to identify the client. It is crucial for a DHCP + client to use an identifier unique within the subnet to which the + client is attached in the 'client identifier' option. Use of + 'chaddr' as the client's unique identifier may cause unexpected + results, as that identifier may be associated with a hardware + interface that could be moved to a new client. Some sites may choose + to use a manufacturer's serial number as the 'client identifier', to + avoid unexpected changes in a clients network address due to transfer + of hardware interfaces among computers. Sites may also choose to use + a DNS name as the 'client identifier', causing address leases to be + associated with the DNS name rather than a specific hardware box. + + DHCP clients are free to use any strategy in selecting a DHCP server + among those from which the client receives a DHCPOFFER message. The + client implementation of DHCP SHOULD provide a mechanism for the user + to select directly the 'vendor class identifier' values. + +4.3 DHCP server behavior + + A DHCP server processes incoming DHCP messages from a client based on + the current state of the binding for that client. A DHCP server can + receive the following messages from a client: + + o DHCPDISCOVER + + o DHCPREQUEST + + o DHCPDECLINE + + o DHCPRELEASE + + o DHCPINFORM + + + + +Droms Standards Track [Page 26] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + Table 3 gives the use of the fields and options in a DHCP message by + a server. The remainder of this section describes the action of the + DHCP server for each possible incoming message. + +4.3.1 DHCPDISCOVER message + + When a server receives a DHCPDISCOVER message from a client, the + server chooses a network address for the requesting client. If no + address is available, the server may choose to report the problem to + the system administrator. If an address is available, the new address + SHOULD be chosen as follows: + + o The client's current address as recorded in the client's current + binding, ELSE + + o The client's previous address as recorded in the client's (now + expired or released) binding, if that address is in the server's + pool of available addresses and not already allocated, ELSE + + o The address requested in the 'Requested IP Address' option, if that + address is valid and not already allocated, ELSE + + o A new address allocated from the server's pool of available + addresses; the address is selected based on the subnet from which + the message was received (if 'giaddr' is 0) or on the address of + the relay agent that forwarded the message ('giaddr' when not 0). + + As described in section 4.2, a server MAY, for administrative + reasons, assign an address other than the one requested, or may + refuse to allocate an address to a particular client even though free + addresses are available. + + Note that, in some network architectures (e.g., internets with more + than one IP subnet assigned to a physical network segment), it may be + the case that the DHCP client should be assigned an address from a + different subnet than the address recorded in 'giaddr'. Thus, DHCP + does not require that the client be assigned as address from the + subnet in 'giaddr'. A server is free to choose some other subnet, + and it is beyond the scope of the DHCP specification to describe ways + in which the assigned IP address might be chosen. + + While not required for correct operation of DHCP, the server SHOULD + NOT reuse the selected network address before the client responds to + the server's DHCPOFFER message. The server may choose to record the + address as offered to the client. + + The server must also choose an expiration time for the lease, as + follows: + + + +Droms Standards Track [Page 27] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + o IF the client has not requested a specific lease in the + DHCPDISCOVER message and the client already has an assigned network + address, the server returns the lease expiration time previously + assigned to that address (note that the client must explicitly + request a specific lease to extend the expiration time on a + previously assigned address), ELSE + + o IF the client has not requested a specific lease in the + DHCPDISCOVER message and the client does not have an assigned + network address, the server assigns a locally configured default + lease time, ELSE + + o IF the client has requested a specific lease in the DHCPDISCOVER + message (regardless of whether the client has an assigned network + address), the server may choose either to return the requested + lease (if the lease is acceptable to local policy) or select + another lease. + +Field DHCPOFFER DHCPACK DHCPNAK +----- --------- ------- ------- +'op' BOOTREPLY BOOTREPLY BOOTREPLY +'htype' (From "Assigned Numbers" RFC) +'hlen' (Hardware address length in octets) +'hops' 0 0 0 +'xid' 'xid' from client 'xid' from client 'xid' from client + DHCPDISCOVER DHCPREQUEST DHCPREQUEST + message message message +'secs' 0 0 0 +'ciaddr' 0 'ciaddr' from 0 + DHCPREQUEST or 0 +'yiaddr' IP address offered IP address 0 + to client assigned to client +'siaddr' IP address of next IP address of next 0 + bootstrap server bootstrap server +'flags' 'flags' from 'flags' from 'flags' from + client DHCPDISCOVER client DHCPREQUEST client DHCPREQUEST + message message message +'giaddr' 'giaddr' from 'giaddr' from 'giaddr' from + client DHCPDISCOVER client DHCPREQUEST client DHCPREQUEST + message message message +'chaddr' 'chaddr' from 'chaddr' from 'chaddr' from + client DHCPDISCOVER client DHCPREQUEST client DHCPREQUEST + message message message +'sname' Server host name Server host name (unused) + or options or options +'file' Client boot file Client boot file (unused) + name or options name or options +'options' options options + + + +Droms Standards Track [Page 28] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + +Option DHCPOFFER DHCPACK DHCPNAK +------ --------- ------- ------- +Requested IP address MUST NOT MUST NOT MUST NOT +IP address lease time MUST MUST (DHCPREQUEST) MUST NOT + MUST NOT (DHCPINFORM) +Use 'file'/'sname' fields MAY MAY MUST NOT +DHCP message type DHCPOFFER DHCPACK DHCPNAK +Parameter request list MUST NOT MUST NOT MUST NOT +Message SHOULD SHOULD SHOULD +Client identifier MUST NOT MUST NOT MAY +Vendor class identifier MAY MAY MAY +Server identifier MUST MUST MUST +Maximum message size MUST NOT MUST NOT MUST NOT +All others MAY MAY MUST NOT + + Table 3: Fields and options used by DHCP servers + + Once the network address and lease have been determined, the server + constructs a DHCPOFFER message with the offered configuration + parameters. It is important for all DHCP servers to return the same + parameters (with the possible exception of a newly allocated network + address) to ensure predictable client behavior regardless of which + server the client selects. The configuration parameters MUST be + selected by applying the following rules in the order given below. + The network administrator is responsible for configuring multiple + DHCP servers to ensure uniform responses from those servers. The + server MUST return to the client: + + o The client's network address, as determined by the rules given + earlier in this section, + + o The expiration time for the client's lease, as determined by the + rules given earlier in this section, + + o Parameters requested by the client, according to the following + rules: + + -- IF the server has been explicitly configured with a default + value for the parameter, the server MUST include that value + in an appropriate option in the 'option' field, ELSE + + -- IF the server recognizes the parameter as a parameter + defined in the Host Requirements Document, the server MUST + include the default value for that parameter as given in the + Host Requirements Document in an appropriate option in the + 'option' field, ELSE + + -- The server MUST NOT return a value for that parameter, + + + +Droms Standards Track [Page 29] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + The server MUST supply as many of the requested parameters as + possible and MUST omit any parameters it cannot provide. The + server MUST include each requested parameter only once unless + explicitly allowed in the DHCP Options and BOOTP Vendor + Extensions document. + + o Any parameters from the existing binding that differ from the Host + Requirements Document defaults, + + o Any parameters specific to this client (as identified by + the contents of 'chaddr' or 'client identifier' in the DHCPDISCOVER + or DHCPREQUEST message), e.g., as configured by the network + administrator, + + o Any parameters specific to this client's class (as identified + by the contents of the 'vendor class identifier' + option in the DHCPDISCOVER or DHCPREQUEST message), + e.g., as configured by the network administrator; the parameters + MUST be identified by an exact match between the client's vendor + class identifiers and the client's classes identified in the + server, + + o Parameters with non-default values on the client's subnet. + + The server MAY choose to return the 'vendor class identifier' used to + determine the parameters in the DHCPOFFER message to assist the + client in selecting which DHCPOFFER to accept. The server inserts + the 'xid' field from the DHCPDISCOVER message into the 'xid' field of + the DHCPOFFER message and sends the DHCPOFFER message to the + requesting client. + +4.3.2 DHCPREQUEST message + + A DHCPREQUEST message may come from a client responding to a + DHCPOFFER message from a server, from a client verifying a previously + allocated IP address or from a client extending the lease on a + network address. If the DHCPREQUEST message contains a 'server + identifier' option, the message is in response to a DHCPOFFER + message. Otherwise, the message is a request to verify or extend an + existing lease. If the client uses a 'client identifier' in a + DHCPREQUEST message, it MUST use that same 'client identifier' in all + subsequent messages. If the client included a list of requested + parameters in a DHCPDISCOVER message, it MUST include that list in + all subsequent messages. + + + + + + + +Droms Standards Track [Page 30] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + Any configuration parameters in the DHCPACK message SHOULD NOT + conflict with those in the earlier DHCPOFFER message to which the + client is responding. The client SHOULD use the parameters in the + DHCPACK message for configuration. + + Clients send DHCPREQUEST messages as follows: + + o DHCPREQUEST generated during SELECTING state: + + Client inserts the address of the selected server in 'server + identifier', 'ciaddr' MUST be zero, 'requested IP address' MUST be + filled in with the yiaddr value from the chosen DHCPOFFER. + + Note that the client may choose to collect several DHCPOFFER + messages and select the "best" offer. The client indicates its + selection by identifying the offering server in the DHCPREQUEST + message. If the client receives no acceptable offers, the client + may choose to try another DHCPDISCOVER message. Therefore, the + servers may not receive a specific DHCPREQUEST from which they can + decide whether or not the client has accepted the offer. Because + the servers have not committed any network address assignments on + the basis of a DHCPOFFER, servers are free to reuse offered + network addresses in response to subsequent requests. As an + implementation detail, servers SHOULD NOT reuse offered addresses + and may use an implementation-specific timeout mechanism to decide + when to reuse an offered address. + + o DHCPREQUEST generated during INIT-REBOOT state: + + 'server identifier' MUST NOT be filled in, 'requested IP address' + option MUST be filled in with client's notion of its previously + assigned address. 'ciaddr' MUST be zero. The client is seeking to + verify a previously allocated, cached configuration. Server SHOULD + send a DHCPNAK message to the client if the 'requested IP address' + is incorrect, or is on the wrong network. + + Determining whether a client in the INIT-REBOOT state is on the + correct network is done by examining the contents of 'giaddr', the + 'requested IP address' option, and a database lookup. If the DHCP + server detects that the client is on the wrong net (i.e., the + result of applying the local subnet mask or remote subnet mask (if + 'giaddr' is not zero) to 'requested IP address' option value + doesn't match reality), then the server SHOULD send a DHCPNAK + message to the client. + + + + + + + +Droms Standards Track [Page 31] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + If the network is correct, then the DHCP server should check if + the client's notion of its IP address is correct. If not, then the + server SHOULD send a DHCPNAK message to the client. If the DHCP + server has no record of this client, then it MUST remain silent, + and MAY output a warning to the network administrator. This + behavior is necessary for peaceful coexistence of non- + communicating DHCP servers on the same wire. + + If 'giaddr' is 0x0 in the DHCPREQUEST message, the client is on + the same subnet as the server. The server MUST broadcast the + DHCPNAK message to the 0xffffffff broadcast address because the + client may not have a correct network address or subnet mask, and + the client may not be answering ARP requests. + + If 'giaddr' is set in the DHCPREQUEST message, the client is on a + different subnet. The server MUST set the broadcast bit in the + DHCPNAK, so that the relay agent will broadcast the DHCPNAK to the + client, because the client may not have a correct network address + or subnet mask, and the client may not be answering ARP requests. + + o DHCPREQUEST generated during RENEWING state: + + 'server identifier' MUST NOT be filled in, 'requested IP address' + option MUST NOT be filled in, 'ciaddr' MUST be filled in with + client's IP address. In this situation, the client is completely + configured, and is trying to extend its lease. This message will + be unicast, so no relay agents will be involved in its + transmission. Because 'giaddr' is therefore not filled in, the + DHCP server will trust the value in 'ciaddr', and use it when + replying to the client. + + A client MAY choose to renew or extend its lease prior to T1. The + server may choose not to extend the lease (as a policy decision by + the network administrator), but should return a DHCPACK message + regardless. + + o DHCPREQUEST generated during REBINDING state: + + 'server identifier' MUST NOT be filled in, 'requested IP address' + option MUST NOT be filled in, 'ciaddr' MUST be filled in with + client's IP address. In this situation, the client is completely + configured, and is trying to extend its lease. This message MUST + be broadcast to the 0xffffffff IP broadcast address. The DHCP + server SHOULD check 'ciaddr' for correctness before replying to + the DHCPREQUEST. + + + + + + +Droms Standards Track [Page 32] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + The DHCPREQUEST from a REBINDING client is intended to accommodate + sites that have multiple DHCP servers and a mechanism for + maintaining consistency among leases managed by multiple servers. + A DHCP server MAY extend a client's lease only if it has local + administrative authority to do so. + +4.3.3 DHCPDECLINE message + + If the server receives a DHCPDECLINE message, the client has + discovered through some other means that the suggested network + address is already in use. The server MUST mark the network address + as not available and SHOULD notify the local system administrator of + a possible configuration problem. + +4.3.4 DHCPRELEASE message + + Upon receipt of a DHCPRELEASE message, the server marks the network + address as not allocated. The server SHOULD retain a record of the + client's initialization parameters for possible reuse in response to + subsequent requests from the client. + +4.3.5 DHCPINFORM message + + The server responds to a DHCPINFORM message by sending a DHCPACK + message directly to the address given in the 'ciaddr' field of the + DHCPINFORM message. The server MUST NOT send a lease expiration time + to the client and SHOULD NOT fill in 'yiaddr'. The server includes + other parameters in the DHCPACK message as defined in section 4.3.1. + +4.3.6 Client messages + + Table 4 details the differences between messages from clients in + various states. + + --------------------------------------------------------------------- + | |INIT-REBOOT |SELECTING |RENEWING |REBINDING | + --------------------------------------------------------------------- + |broad/unicast |broadcast |broadcast |unicast |broadcast | + |server-ip |MUST NOT |MUST |MUST NOT |MUST NOT | + |requested-ip |MUST |MUST |MUST NOT |MUST NOT | + |ciaddr |zero |zero |IP address |IP address| + --------------------------------------------------------------------- + + Table 4: Client messages from different states + + + + + + + +Droms Standards Track [Page 33] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + +4.4 DHCP client behavior + + Figure 5 gives a state-transition diagram for a DHCP client. A + client can receive the following messages from a server: + + o DHCPOFFER + + o DHCPACK + + o DHCPNAK + + The DHCPINFORM message is not shown in figure 5. A client simply + sends the DHCPINFORM and waits for DHCPACK messages. Once the client + has selected its parameters, it has completed the configuration + process. + + Table 5 gives the use of the fields and options in a DHCP message by + a client. The remainder of this section describes the action of the + DHCP client for each possible incoming message. The description in + the following section corresponds to the full configuration procedure + previously described in section 3.1, and the text in the subsequent + section corresponds to the abbreviated configuration procedure + described in section 3.2. + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Droms Standards Track [Page 34] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + -------- ------- +| | +-------------------------->| |<-------------------+ +| INIT- | | +-------------------->| INIT | | +| REBOOT |DHCPNAK/ +---------->| |<---+ | +| |Restart| | ------- | | + -------- | DHCPNAK/ | | | + | Discard offer | -/Send DHCPDISCOVER | +-/Send DHCPREQUEST | | | + | | | DHCPACK v | | + ----------- | (not accept.)/ ----------- | | +| | | Send DHCPDECLINE | | | +| REBOOTING | | | | SELECTING |<----+ | +| | | / | | |DHCPOFFER/ | + ----------- | / ----------- | |Collect | + | | / | | | replies | +DHCPACK/ | / +----------------+ +-------+ | +Record lease, set| | v Select offer/ | +timers T1, T2 ------------ send DHCPREQUEST | | + | +----->| | DHCPNAK, Lease expired/ | + | | | REQUESTING | Halt network | + DHCPOFFER/ | | | | + Discard ------------ | | + | | | | ----------- | + | +--------+ DHCPACK/ | | | + | Record lease, set -----| REBINDING | | + | timers T1, T2 / | | | + | | DHCPACK/ ----------- | + | v Record lease, set ^ | + +----------------> ------- /timers T1,T2 | | + +----->| |<---+ | | + | | BOUND |<---+ | | + DHCPOFFER, DHCPACK, | | | T2 expires/ DHCPNAK/ + DHCPNAK/Discard ------- | Broadcast Halt network + | | | | DHCPREQUEST | + +-------+ | DHCPACK/ | | + T1 expires/ Record lease, set | | + Send DHCPREQUEST timers T1, T2 | | + to leasing server | | | + | ---------- | | + | | |------------+ | + +->| RENEWING | | + | |----------------------------+ + ---------- + Figure 5: State-transition diagram for DHCP clients + + + + + + + +Droms Standards Track [Page 35] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + +4.4.1 Initialization and allocation of network address + + The client begins in INIT state and forms a DHCPDISCOVER message. + The client SHOULD wait a random time between one and ten seconds to + desynchronize the use of DHCP at startup. The client sets 'ciaddr' + to 0x00000000. The client MAY request specific parameters by + including the 'parameter request list' option. The client MAY + suggest a network address and/or lease time by including the + 'requested IP address' and 'IP address lease time' options. The + client MUST include its hardware address in the 'chaddr' field, if + necessary for delivery of DHCP reply messages. The client MAY + include a different unique identifier in the 'client identifier' + option, as discussed in section 4.2. If the client included a list + of requested parameters in a DHCPDISCOVER message, it MUST include + that list in all subsequent messages. + + The client generates and records a random transaction identifier and + inserts that identifier into the 'xid' field. The client records its + own local time for later use in computing the lease expiration. The + client then broadcasts the DHCPDISCOVER on the local hardware + broadcast address to the 0xffffffff IP broadcast address and 'DHCP + server' UDP port. + + If the 'xid' of an arriving DHCPOFFER message does not match the + 'xid' of the most recent DHCPDISCOVER message, the DHCPOFFER message + must be silently discarded. Any arriving DHCPACK messages must be + silently discarded. + + The client collects DHCPOFFER messages over a period of time, selects + one DHCPOFFER message from the (possibly many) incoming DHCPOFFER + messages (e.g., the first DHCPOFFER message or the DHCPOFFER message + from the previously used server) and extracts the server address from + the 'server identifier' option in the DHCPOFFER message. The time + over which the client collects messages and the mechanism used to + select one DHCPOFFER are implementation dependent. + + + + + + + + + + + + + + + + +Droms Standards Track [Page 36] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + +Field DHCPDISCOVER DHCPREQUEST DHCPDECLINE, + DHCPINFORM DHCPRELEASE +----- ------------ ----------- ----------- +'op' BOOTREQUEST BOOTREQUEST BOOTREQUEST +'htype' (From "Assigned Numbers" RFC) +'hlen' (Hardware address length in octets) +'hops' 0 0 0 +'xid' selected by client 'xid' from server selected by + DHCPOFFER message client +'secs' 0 or seconds since 0 or seconds since 0 + DHCP process started DHCP process started +'flags' Set 'BROADCAST' Set 'BROADCAST' 0 + flag if client flag if client + requires broadcast requires broadcast + reply reply +'ciaddr' 0 (DHCPDISCOVER) 0 or client's 0 (DHCPDECLINE) + client's network address client's network + network address (BOUND/RENEW/REBIND) address + (DHCPINFORM) (DHCPRELEASE) +'yiaddr' 0 0 0 +'siaddr' 0 0 0 +'giaddr' 0 0 0 +'chaddr' client's hardware client's hardware client's hardware + address address address +'sname' options, if options, if (unused) + indicated in indicated in + 'sname/file' 'sname/file' + option; otherwise option; otherwise + unused unused +'file' options, if options, if (unused) + indicated in indicated in + 'sname/file' 'sname/file' + option; otherwise option; otherwise + unused unused +'options' options options (unused) + + + + + + + + + + + + + + + + +Droms Standards Track [Page 37] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + +Option DHCPDISCOVER DHCPREQUEST DHCPDECLINE, + DHCPINFORM DHCPRELEASE +------ ------------ ----------- ----------- +Requested IP address MAY MUST (in MUST + (DISCOVER) SELECTING or (DHCPDECLINE), + MUST NOT INIT-REBOOT) MUST NOT + (INFORM) MUST NOT (in (DHCPRELEASE) + BOUND or + RENEWING) +IP address lease time MAY MAY MUST NOT + (DISCOVER) + MUST NOT + (INFORM) +Use 'file'/'sname' fields MAY MAY MAY +DHCP message type DHCPDISCOVER/ DHCPREQUEST DHCPDECLINE/ + DHCPINFORM DHCPRELEASE +Client identifier MAY MAY MAY +Vendor class identifier MAY MAY MUST NOT +Server identifier MUST NOT MUST (after MUST + SELECTING) + MUST NOT (after + INIT-REBOOT, + BOUND, RENEWING + or REBINDING) +Parameter request list MAY MAY MUST NOT +Maximum message size MAY MAY MUST NOT +Message SHOULD NOT SHOULD NOT SHOULD +Site-specific MAY MAY MUST NOT +All others MAY MAY MUST NOT + + Table 5: Fields and options used by DHCP clients + + If the parameters are acceptable, the client records the address of + the server that supplied the parameters from the 'server identifier' + field and sends that address in the 'server identifier' field of a + DHCPREQUEST broadcast message. Once the DHCPACK message from the + server arrives, the client is initialized and moves to BOUND state. + The DHCPREQUEST message contains the same 'xid' as the DHCPOFFER + message. The client records the lease expiration time as the sum of + the time at which the original request was sent and the duration of + the lease from the DHCPACK message. The client SHOULD perform a + check on the suggested address to ensure that the address is not + already in use. For example, if the client is on a network that + supports ARP, the client may issue an ARP request for the suggested + request. When broadcasting an ARP request for the suggested address, + the client must fill in its own hardware address as the sender's + hardware address, and 0 as the sender's IP address, to avoid + confusing ARP caches in other hosts on the same subnet. If the + + + +Droms Standards Track [Page 38] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + network address appears to be in use, the client MUST send a + DHCPDECLINE message to the server. The client SHOULD broadcast an ARP + reply to announce the client's new IP address and clear any outdated + ARP cache entries in hosts on the client's subnet. + +4.4.2 Initialization with known network address + + The client begins in INIT-REBOOT state and sends a DHCPREQUEST + message. The client MUST insert its known network address as a + 'requested IP address' option in the DHCPREQUEST message. The client + may request specific configuration parameters by including the + 'parameter request list' option. The client generates and records a + random transaction identifier and inserts that identifier into the + 'xid' field. The client records its own local time for later use in + computing the lease expiration. The client MUST NOT include a + 'server identifier' in the DHCPREQUEST message. The client then + broadcasts the DHCPREQUEST on the local hardware broadcast address to + the 'DHCP server' UDP port. + + Once a DHCPACK message with an 'xid' field matching that in the + client's DHCPREQUEST message arrives from any server, the client is + initialized and moves to BOUND state. The client records the lease + expiration time as the sum of the time at which the DHCPREQUEST + message was sent and the duration of the lease from the DHCPACK + message. + +4.4.3 Initialization with an externally assigned network address + + The client sends a DHCPINFORM message. The client may request + specific configuration parameters by including the 'parameter request + list' option. The client generates and records a random transaction + identifier and inserts that identifier into the 'xid' field. The + client places its own network address in the 'ciaddr' field. The + client SHOULD NOT request lease time parameters. + + The client then unicasts the DHCPINFORM to the DHCP server if it + knows the server's address, otherwise it broadcasts the message to + the limited (all 1s) broadcast address. DHCPINFORM messages MUST be + directed to the 'DHCP server' UDP port. + + Once a DHCPACK message with an 'xid' field matching that in the + client's DHCPINFORM message arrives from any server, the client is + initialized. + + If the client does not receive a DHCPACK within a reasonable period + of time (60 seconds or 4 tries if using timeout suggested in section + 4.1), then it SHOULD display a message informing the user of the + problem, and then SHOULD begin network processing using suitable + + + +Droms Standards Track [Page 39] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + defaults as per Appendix A. + +4.4.4 Use of broadcast and unicast + + The DHCP client broadcasts DHCPDISCOVER, DHCPREQUEST and DHCPINFORM + messages, unless the client knows the address of a DHCP server. The + client unicasts DHCPRELEASE messages to the server. Because the + client is declining the use of the IP address supplied by the server, + the client broadcasts DHCPDECLINE messages. + + When the DHCP client knows the address of a DHCP server, in either + INIT or REBOOTING state, the client may use that address in the + DHCPDISCOVER or DHCPREQUEST rather than the IP broadcast address. + The client may also use unicast to send DHCPINFORM messages to a + known DHCP server. If the client receives no response to DHCP + messages sent to the IP address of a known DHCP server, the DHCP + client reverts to using the IP broadcast address. + +4.4.5 Reacquisition and expiration + + The client maintains two times, T1 and T2, that specify the times at + which the client tries to extend its lease on its network address. + T1 is the time at which the client enters the RENEWING state and + attempts to contact the server that originally issued the client's + network address. T2 is the time at which the client enters the + REBINDING state and attempts to contact any server. T1 MUST be + earlier than T2, which, in turn, MUST be earlier than the time at + which the client's lease will expire. + + To avoid the need for synchronized clocks, T1 and T2 are expressed in + options as relative times [2]. + + At time T1 the client moves to RENEWING state and sends (via unicast) + a DHCPREQUEST message to the server to extend its lease. The client + sets the 'ciaddr' field in the DHCPREQUEST to its current network + address. The client records the local time at which the DHCPREQUEST + message is sent for computation of the lease expiration time. The + client MUST NOT include a 'server identifier' in the DHCPREQUEST + message. + + Any DHCPACK messages that arrive with an 'xid' that does not match + the 'xid' of the client's DHCPREQUEST message are silently discarded. + When the client receives a DHCPACK from the server, the client + computes the lease expiration time as the sum of the time at which + the client sent the DHCPREQUEST message and the duration of the lease + in the DHCPACK message. The client has successfully reacquired its + network address, returns to BOUND state and may continue network + processing. + + + +Droms Standards Track [Page 40] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + If no DHCPACK arrives before time T2, the client moves to REBINDING + state and sends (via broadcast) a DHCPREQUEST message to extend its + lease. The client sets the 'ciaddr' field in the DHCPREQUEST to its + current network address. The client MUST NOT include a 'server + identifier' in the DHCPREQUEST message. + + Times T1 and T2 are configurable by the server through options. T1 + defaults to (0.5 * duration_of_lease). T2 defaults to (0.875 * + duration_of_lease). Times T1 and T2 SHOULD be chosen with some + random "fuzz" around a fixed value, to avoid synchronization of + client reacquisition. + + A client MAY choose to renew or extend its lease prior to T1. The + server MAY choose to extend the client's lease according to policy + set by the network administrator. The server SHOULD return T1 and + T2, and their values SHOULD be adjusted from their original values to + take account of the time remaining on the lease. + + In both RENEWING and REBINDING states, if the client receives no + response to its DHCPREQUEST message, the client SHOULD wait one-half + of the remaining time until T2 (in RENEWING state) and one-half of + the remaining lease time (in REBINDING state), down to a minimum of + 60 seconds, before retransmitting the DHCPREQUEST message. + + If the lease expires before the client receives a DHCPACK, the client + moves to INIT state, MUST immediately stop any other network + processing and requests network initialization parameters as if the + client were uninitialized. If the client then receives a DHCPACK + allocating that client its previous network address, the client + SHOULD continue network processing. If the client is given a new + network address, it MUST NOT continue using the previous network + address and SHOULD notify the local users of the problem. + +4.4.6 DHCPRELEASE + + If the client no longer requires use of its assigned network address + (e.g., the client is gracefully shut down), the client sends a + DHCPRELEASE message to the server. Note that the correct operation + of DHCP does not depend on the transmission of DHCPRELEASE messages. + + + + + + + + + + + + +Droms Standards Track [Page 41] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + +5. Acknowledgments + + The author thanks the many (and too numerous to mention!) members of + the DHC WG for their tireless and ongoing efforts in the development + of DHCP and this document. + + The efforts of J Allard, Mike Carney, Dave Lapp, Fred Lien and John + Mendonca in organizing DHCP interoperability testing sessions are + gratefully acknowledged. + + The development of this document was supported in part by grants from + the Corporation for National Research Initiatives (CNRI), Bucknell + University and Sun Microsystems. + +6. References + + [1] Acetta, M., "Resource Location Protocol", RFC 887, CMU, December + 1983. + + [2] Alexander, S., and R. Droms, "DHCP Options and BOOTP Vendor + Extensions", RFC 1533, Lachman Technology, Inc., Bucknell + University, October 1993. + + [3] Braden, R., Editor, "Requirements for Internet Hosts -- + Communication Layers", STD 3, RFC 1122, USC/Information Sciences + Institute, October 1989. + + [4] Braden, R., Editor, "Requirements for Internet Hosts -- + Application and Support, STD 3, RFC 1123, USC/Information + Sciences Institute, October 1989. + + [5] Brownell, D, "Dynamic Reverse Address Resolution Protocol + (DRARP)", Work in Progress. + + [6] Comer, D., and R. Droms, "Uniform Access to Internet Directory + Services", Proc. of ACM SIGCOMM '90 (Special issue of Computer + Communications Review), 20(4):50--59, 1990. + + [7] Croft, B., and J. Gilmore, "Bootstrap Protocol (BOOTP)", RFC 951, + Stanford and SUN Microsystems, September 1985. + + [8] Deering, S., "ICMP Router Discovery Messages", RFC 1256, Xerox + PARC, September 1991. + + [9] Droms, D., "Interoperation between DHCP and BOOTP", RFC 1534, + Bucknell University, October 1993. + + + + + +Droms Standards Track [Page 42] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + [10] Finlayson, R., Mann, T., Mogul, J., and M. Theimer, "A Reverse + Address Resolution Protocol", RFC 903, Stanford, June 1984. + + [11] Gray C., and D. Cheriton, "Leases: An Efficient Fault-Tolerant + Mechanism for Distributed File Cache Consistency", In Proc. of + the Twelfth ACM Symposium on Operating Systems Design, 1989. + + [12] Mockapetris, P., "Domain Names -- Concepts and Facilities", STD + 13, RFC 1034, USC/Information Sciences Institute, November 1987. + + [13] Mockapetris, P., "Domain Names -- Implementation and + Specification", STD 13, RFC 1035, USC/Information Sciences + Institute, November 1987. + + [14] Mogul J., and S. Deering, "Path MTU Discovery", RFC 1191, + November 1990. + + [15] Morgan, R., "Dynamic IP Address Assignment for Ethernet Attached + Hosts", Work in Progress. + + [16] Postel, J., "Internet Control Message Protocol", STD 5, RFC 792, + USC/Information Sciences Institute, September 1981. + + [17] Reynolds, J., "BOOTP Vendor Information Extensions", RFC 1497, + USC/Information Sciences Institute, August 1993. + + [18] Reynolds, J., and J. Postel, "Assigned Numbers", STD 2, RFC 1700, + USC/Information Sciences Institute, October 1994. + + [19] Jeffrey Schiller and Mark Rosenstein. A Protocol for the Dynamic + Assignment of IP Addresses for use on an Ethernet. (Available + from the Athena Project, MIT), 1989. + + [20] Sollins, K., "The TFTP Protocol (Revision 2)", RFC 783, NIC, + June 1981. + + [21] Wimer, W., "Clarifications and Extensions for the Bootstrap + Protocol", RFC 1542, Carnegie Mellon University, October 1993. + +7. Security Considerations + + DHCP is built directly on UDP and IP which are as yet inherently + insecure. Furthermore, DHCP is generally intended to make + maintenance of remote and/or diskless hosts easier. While perhaps + not impossible, configuring such hosts with passwords or keys may be + difficult and inconvenient. Therefore, DHCP in its current form is + quite insecure. + + + + +Droms Standards Track [Page 43] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + + Unauthorized DHCP servers may be easily set up. Such servers can + then send false and potentially disruptive information to clients + such as incorrect or duplicate IP addresses, incorrect routing + information (including spoof routers, etc.), incorrect domain + nameserver addresses (such as spoof nameservers), and so on. + Clearly, once this seed information is in place, an attacker can + further compromise affected systems. + + Malicious DHCP clients could masquerade as legitimate clients and + retrieve information intended for those legitimate clients. Where + dynamic allocation of resources is used, a malicious client could + claim all resources for itself, thereby denying resources to + legitimate clients. + +8. Author's Address + + Ralph Droms + Computer Science Department + 323 Dana Engineering + Bucknell University + Lewisburg, PA 17837 + + Phone: (717) 524-1145 + EMail: droms@bucknell.edu + + + + + + + + + + + + + + + + + + + + + + + + + + + +Droms Standards Track [Page 44] + +RFC 2131 Dynamic Host Configuration Protocol March 1997 + + +A. Host Configuration Parameters + + IP-layer_parameters,_per_host:_ + + Be a router on/off HRC 3.1 + Non-local source routing on/off HRC 3.3.5 + Policy filters for + non-local source routing (list) HRC 3.3.5 + Maximum reassembly size integer HRC 3.3.2 + Default TTL integer HRC 3.2.1.7 + PMTU aging timeout integer MTU 6.6 + MTU plateau table (list) MTU 7 + IP-layer_parameters,_per_interface:_ + IP address (address) HRC 3.3.1.6 + Subnet mask (address mask) HRC 3.3.1.6 + MTU integer HRC 3.3.3 + All-subnets-MTU on/off HRC 3.3.3 + Broadcast address flavor 0x00000000/0xffffffff HRC 3.3.6 + Perform mask discovery on/off HRC 3.2.2.9 + Be a mask supplier on/off HRC 3.2.2.9 + Perform router discovery on/off RD 5.1 + Router solicitation address (address) RD 5.1 + Default routers, list of: + router address (address) HRC 3.3.1.6 + preference level integer HRC 3.3.1.6 + Static routes, list of: + destination (host/subnet/net) HRC 3.3.1.2 + destination mask (address mask) HRC 3.3.1.2 + type-of-service integer HRC 3.3.1.2 + first-hop router (address) HRC 3.3.1.2 + ignore redirects on/off HRC 3.3.1.2 + PMTU integer MTU 6.6 + perform PMTU discovery on/off MTU 6.6 + + Link-layer_parameters,_per_interface:_ + Trailers on/off HRC 2.3.1 + ARP cache timeout integer HRC 2.3.2.1 + Ethernet encapsulation (RFC 894/RFC 1042) HRC 2.3.3 + + TCP_parameters,_per_host:_ + TTL integer HRC 4.2.2.19 + Keep-alive interval integer HRC 4.2.3.6 + Keep-alive data size 0/1 HRC 4.2.3.6 + +Key: + + MTU = Path MTU Discovery (RFC 1191, Proposed Standard) + RD = Router Discovery (RFC 1256, Proposed Standard) + + + +Droms Standards Track [Page 45] + diff --git a/docs/rfc2132.txt b/docs/rfc2132.txt new file mode 100644 index 0000000..e9c4f4b --- /dev/null +++ b/docs/rfc2132.txt @@ -0,0 +1,1907 @@ + + + + + + +Network Working Group S. Alexander +Request for Comments: 2132 Silicon Graphics, Inc. +Obsoletes: 1533 R. Droms +Category: Standards Track Bucknell University + March 1997 + + DHCP Options and BOOTP Vendor Extensions + +Status of this memo + + 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. + +Abstract + + The Dynamic Host Configuration Protocol (DHCP) [1] provides a + framework for passing configuration information to hosts on a TCP/IP + network. Configuration parameters and other control information are + carried in tagged data items that are stored in the 'options' field + of the DHCP message. The data items themselves are also called + "options." + + This document specifies the current set of DHCP options. Future + options will be specified in separate RFCs. The current list of + valid options is also available in ftp://ftp.isi.edu/in- + notes/iana/assignments [22]. + + All of the vendor information extensions defined in RFC 1497 [2] may + be used as DHCP options. The definitions given in RFC 1497 are + included in this document, which supersedes RFC 1497. All of the + DHCP options defined in this document, except for those specific to + DHCP as defined in section 9, may be used as BOOTP vendor information + extensions. + +Table of Contents + + 1. Introduction .............................................. 2 + 2. BOOTP Extension/DHCP Option Field Format .................. 4 + 3. RFC 1497 Vendor Extensions ................................ 5 + 4. IP Layer Parameters per Host .............................. 11 + 5. IP Layer Parameters per Interface ........................ 13 + 6. Link Layer Parameters per Interface ....................... 16 + 7. TCP Parameters ............................................ 17 + 8. Application and Service Parameters ........................ 18 + 9. DHCP Extensions ........................................... 25 + + + +Alexander & Droms Standards Track [Page 1] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + 10. Defining new extensions ................................... 31 + 11. Acknowledgements .......................................... 31 + 12. References ................................................ 32 + 13. Security Considerations ................................... 33 + 14. Authors' Addresses ........................................ 34 + +1. Introduction + + This document specifies options for use with both the Dynamic Host + Configuration Protocol and the Bootstrap Protocol. + + The full description of DHCP packet formats may be found in the DHCP + specification document [1], and the full description of BOOTP packet + formats may be found in the BOOTP specification document [3]. This + document defines the format of information in the last field of DHCP + packets ('options') and of BOOTP packets ('vend'). The remainder of + this section defines a generalized use of this area for giving + information useful to a wide class of machines, operating systems and + configurations. Sites with a single DHCP or BOOTP server that is + shared among heterogeneous clients may choose to define other, site- + specific formats for the use of the 'options' field. + + Section 2 of this memo describes the formats of DHCP options and + BOOTP vendor extensions. Section 3 describes options defined in + previous documents for use with BOOTP (all may also be used with + DHCP). Sections 4-8 define new options intended for use with both + DHCP and BOOTP. Section 9 defines options used only in DHCP. + + References further describing most of the options defined in sections + 2-6 can be found in section 12. The use of the options defined in + section 9 is described in the DHCP specification [1]. + + Information on registering new options is contained in section 10. + + This document updates the definition of DHCP/BOOTP options that + appears in RFC1533. The classing mechanism has been extended to + include vendor classes as described in section 8.4 and 9.13. The new + procedure for defining new DHCP/BOOTP options in described in section + 10. Several new options, including NIS+ domain and servers, Mobile + IP home agent, SMTP server, TFTP server and Bootfile server, have + been added. Text giving definitions used throughout the document has + been added in section 1.1. Text emphasizing the need for uniqueness + of client-identifiers has been added to section 9.14. + + + + + + + + +Alexander & Droms Standards Track [Page 2] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + +1.1 Requirements + + Throughout this document, the words that are used to define the + significance of particular requirements are capitalized. These words + are: + + o "MUST" + + This word or the adjective "REQUIRED" means that the item is an + absolute requirement of this specification. + + o "MUST NOT" + + This phrase means that the item is an absolute prohibition of + this specification. + + o "SHOULD" + + This word or the adjective "RECOMMENDED" means that there may + exist valid reasons in particular circumstances to ignore this + item, but the full implications should be understood and the case + carefully weighed before choosing a different course. + + o "SHOULD NOT" + + This phrase means that there may exist valid reasons in + particular circumstances when the listed behavior is acceptable + or even useful, but the full implications should be understood + and the case carefully weighed before implementing any behavior + described with this label. + + o "MAY" + + This word or the adjective "OPTIONAL" means that this item is + truly optional. One vendor may choose to include the item + because a particular marketplace requires it or because it + enhances the product, for example; another vendor may omit the + same item. + +1.2 Terminology + + This document uses the following terms: + + o "DHCP client" + + A DHCP client or "client" is an Internet host using DHCP to + obtain configuration parameters such as a network address. + + + + +Alexander & Droms Standards Track [Page 3] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + o "DHCP server" + + A DHCP server of "server"is an Internet host that returns + configuration parameters to DHCP clients. + + o "binding" + + A binding is a collection of configuration parameters, including + at least an IP address, associated with or "bound to" a DHCP + client. Bindings are managed by DHCP servers. + +2. BOOTP Extension/DHCP Option Field Format + + + DHCP options have the same format as the BOOTP 'vendor extensions' + defined in RFC 1497 [2]. Options may be fixed length or variable + length. All options begin with a tag octet, which uniquely + identifies the option. Fixed-length options without data consist of + only a tag octet. Only options 0 and 255 are fixed length. All + other options are variable-length with a length octet following the + tag octet. The value of the length octet does not include the two + octets specifying the tag and length. The length octet is followed + by "length" octets of data. Options containing NVT ASCII data SHOULD + NOT include a trailing NULL; however, the receiver of such options + MUST be prepared to delete trailing nulls if they exist. The + receiver MUST NOT require that a trailing null be included in the + data. In the case of some variable-length options the length field + is a constant but must still be specified. + + Any options defined subsequent to this document MUST contain a length + octet even if the length is fixed or zero. + + All multi-octet quantities are in network byte-order. + + When used with BOOTP, the first four octets of the vendor information + field have been assigned to the "magic cookie" (as suggested in RFC + 951). This field identifies the mode in which the succeeding data is + to be interpreted. The value of the magic cookie is the 4 octet + dotted decimal 99.130.83.99 (or hexadecimal number 63.82.53.63) in + network byte order. + + All of the "vendor extensions" defined in RFC 1497 are also DHCP + options. + + Option codes 128 to 254 (decimal) are reserved for site-specific + options. + + + + + +Alexander & Droms Standards Track [Page 4] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + Except for the options in section 9, all options may be used with + either DHCP or BOOTP. + + Many of these options have their default values specified in other + documents. In particular, RFC 1122 [4] specifies default values for + most IP and TCP configuration parameters. + + Many options supply one or more 32-bit IP address. Use of IP + addresses rather than fully-qualified Domain Names (FQDNs) may make + future renumbering of IP hosts more difficult. Use of these + addresses is discouraged at sites that may require renumbering. + +3. RFC 1497 Vendor Extensions + + This section lists the vendor extensions as defined in RFC 1497. + They are defined here for completeness. + +3.1. Pad Option + + The pad option can be used to cause subsequent fields to align on + word boundaries. + + The code for the pad option is 0, and its length is 1 octet. + + Code + +-----+ + | 0 | + +-----+ + +3.2. End Option + + The end option marks the end of valid information in the vendor + field. Subsequent octets should be filled with pad options. + + The code for the end option is 255, and its length is 1 octet. + + Code + +-----+ + | 255 | + +-----+ + +3.3. Subnet Mask + + The subnet mask option specifies the client's subnet mask as per RFC + 950 [5]. + + If both the subnet mask and the router option are specified in a DHCP + reply, the subnet mask option MUST be first. + + + +Alexander & Droms Standards Track [Page 5] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + The code for the subnet mask option is 1, and its length is 4 octets. + + Code Len Subnet Mask + +-----+-----+-----+-----+-----+-----+ + | 1 | 4 | m1 | m2 | m3 | m4 | + +-----+-----+-----+-----+-----+-----+ + +3.4. Time Offset + + The time offset field specifies the offset of the client's subnet in + seconds from Coordinated Universal Time (UTC). The offset is + expressed as a two's complement 32-bit integer. A positive offset + indicates a location east of the zero meridian and a negative offset + indicates a location west of the zero meridian. + + The code for the time offset option is 2, and its length is 4 octets. + + Code Len Time Offset + +-----+-----+-----+-----+-----+-----+ + | 2 | 4 | n1 | n2 | n3 | n4 | + +-----+-----+-----+-----+-----+-----+ + +3.5. Router Option + + The router option specifies a list of IP addresses for routers on the + client's subnet. Routers SHOULD be listed in order of preference. + + The code for the router option is 3. The minimum length for the + router option is 4 octets, and the length MUST always be a multiple + of 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 3 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +3.6. Time Server Option + + The time server option specifies a list of RFC 868 [6] time servers + available to the client. Servers SHOULD be listed in order of + preference. + + The code for the time server option is 4. The minimum length for + this option is 4 octets, and the length MUST always be a multiple of + 4. + + + + + + +Alexander & Droms Standards Track [Page 6] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 4 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +3.7. Name Server Option + + The name server option specifies a list of IEN 116 [7] name servers + available to the client. Servers SHOULD be listed in order of + preference. + + The code for the name server option is 5. The minimum length for + this option is 4 octets, and the length MUST always be a multiple of + 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 5 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +3.8. Domain Name Server Option + + The domain name server option specifies a list of Domain Name System + (STD 13, RFC 1035 [8]) name servers available to the client. Servers + SHOULD be listed in order of preference. + + The code for the domain name server option is 6. The minimum length + for this option is 4 octets, and the length MUST always be a multiple + of 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 6 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +3.9. Log Server Option + + The log server option specifies a list of MIT-LCS UDP log servers + available to the client. Servers SHOULD be listed in order of + preference. + + The code for the log server option is 7. The minimum length for this + option is 4 octets, and the length MUST always be a multiple of 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 7 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + + + +Alexander & Droms Standards Track [Page 7] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + +3.10. Cookie Server Option + + The cookie server option specifies a list of RFC 865 [9] cookie + servers available to the client. Servers SHOULD be listed in order + of preference. + + The code for the log server option is 8. The minimum length for this + option is 4 octets, and the length MUST always be a multiple of 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 8 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +3.11. LPR Server Option + + The LPR server option specifies a list of RFC 1179 [10] line printer + servers available to the client. Servers SHOULD be listed in order + of preference. + + The code for the LPR server option is 9. The minimum length for this + option is 4 octets, and the length MUST always be a multiple of 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 9 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +3.12. Impress Server Option + + The Impress server option specifies a list of Imagen Impress servers + available to the client. Servers SHOULD be listed in order of + preference. + + The code for the Impress server option is 10. The minimum length for + this option is 4 octets, and the length MUST always be a multiple of + 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 10 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +3.13. Resource Location Server Option + + This option specifies a list of RFC 887 [11] Resource Location + servers available to the client. Servers SHOULD be listed in order + of preference. + + + +Alexander & Droms Standards Track [Page 8] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + The code for this option is 11. The minimum length for this option + is 4 octets, and the length MUST always be a multiple of 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 11 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +3.14. Host Name Option + + This option specifies the name of the client. The name may or may + not be qualified with the local domain name (see section 3.17 for the + preferred way to retrieve the domain name). See RFC 1035 for + character set restrictions. + + The code for this option is 12, and its minimum length is 1. + + Code Len Host Name + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 12 | n | h1 | h2 | h3 | h4 | h5 | h6 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +3.15. Boot File Size Option + + This option specifies the length in 512-octet blocks of the default + boot image for the client. The file length is specified as an + unsigned 16-bit integer. + + The code for this option is 13, and its length is 2. + + Code Len File Size + +-----+-----+-----+-----+ + | 13 | 2 | l1 | l2 | + +-----+-----+-----+-----+ + +3.16. Merit Dump File + + This option specifies the path-name of a file to which the client's + core image should be dumped in the event the client crashes. The + path is formatted as a character string consisting of characters from + the NVT ASCII character set. + + The code for this option is 14. Its minimum length is 1. + + Code Len Dump File Pathname + +-----+-----+-----+-----+-----+-----+--- + | 14 | n | n1 | n2 | n3 | n4 | ... + +-----+-----+-----+-----+-----+-----+--- + + + +Alexander & Droms Standards Track [Page 9] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + +3.17. Domain Name + + This option specifies the domain name that client should use when + resolving hostnames via the Domain Name System. + + The code for this option is 15. Its minimum length is 1. + + Code Len Domain Name + +-----+-----+-----+-----+-----+-----+-- + | 15 | n | d1 | d2 | d3 | d4 | ... + +-----+-----+-----+-----+-----+-----+-- + +3.18. Swap Server + + This specifies the IP address of the client's swap server. + + The code for this option is 16 and its length is 4. + + Code Len Swap Server Address + +-----+-----+-----+-----+-----+-----+ + | 16 | n | a1 | a2 | a3 | a4 | + +-----+-----+-----+-----+-----+-----+ + +3.19. Root Path + + This option specifies the path-name that contains the client's root + disk. The path is formatted as a character string consisting of + characters from the NVT ASCII character set. + + The code for this option is 17. Its minimum length is 1. + + Code Len Root Disk Pathname + +-----+-----+-----+-----+-----+-----+--- + | 17 | n | n1 | n2 | n3 | n4 | ... + +-----+-----+-----+-----+-----+-----+--- + +3.20. Extensions Path + + A string to specify a file, retrievable via TFTP, which contains + information which can be interpreted in the same way as the 64-octet + vendor-extension field within the BOOTP response, with the following + exceptions: + + - the length of the file is unconstrained; + - all references to Tag 18 (i.e., instances of the + BOOTP Extensions Path field) within the file are + ignored. + + + + +Alexander & Droms Standards Track [Page 10] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + The code for this option is 18. Its minimum length is 1. + + Code Len Extensions Pathname + +-----+-----+-----+-----+-----+-----+--- + | 18 | n | n1 | n2 | n3 | n4 | ... + +-----+-----+-----+-----+-----+-----+--- + +4. IP Layer Parameters per Host + + This section details the options that affect the operation of the IP + layer on a per-host basis. + +4.1. IP Forwarding Enable/Disable Option + + This option specifies whether the client should configure its IP + layer for packet forwarding. A value of 0 means disable IP + forwarding, and a value of 1 means enable IP forwarding. + + The code for this option is 19, and its length is 1. + + Code Len Value + +-----+-----+-----+ + | 19 | 1 | 0/1 | + +-----+-----+-----+ + +4.2. Non-Local Source Routing Enable/Disable Option + + This option specifies whether the client should configure its IP + layer to allow forwarding of datagrams with non-local source routes + (see Section 3.3.5 of [4] for a discussion of this topic). A value + of 0 means disallow forwarding of such datagrams, and a value of 1 + means allow forwarding. + + The code for this option is 20, and its length is 1. + + Code Len Value + +-----+-----+-----+ + | 20 | 1 | 0/1 | + +-----+-----+-----+ + +4.3. Policy Filter Option + + This option specifies policy filters for non-local source routing. + The filters consist of a list of IP addresses and masks which specify + destination/mask pairs with which to filter incoming source routes. + + Any source routed datagram whose next-hop address does not match one + of the filters should be discarded by the client. + + + +Alexander & Droms Standards Track [Page 11] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + See [4] for further information. + + The code for this option is 21. The minimum length of this option is + 8, and the length MUST be a multiple of 8. + + Code Len Address 1 Mask 1 + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+ + | 21 | n | a1 | a2 | a3 | a4 | m1 | m2 | m3 | m4 | + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+ + Address 2 Mask 2 + +-----+-----+-----+-----+-----+-----+-----+-----+--- + | a1 | a2 | a3 | a4 | m1 | m2 | m3 | m4 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+--- + +4.4. Maximum Datagram Reassembly Size + + This option specifies the maximum size datagram that the client + should be prepared to reassemble. The size is specified as a 16-bit + unsigned integer. The minimum value legal value is 576. + + The code for this option is 22, and its length is 2. + + Code Len Size + +-----+-----+-----+-----+ + | 22 | 2 | s1 | s2 | + +-----+-----+-----+-----+ + +4.5. Default IP Time-to-live + + This option specifies the default time-to-live that the client should + use on outgoing datagrams. The TTL is specified as an octet with a + value between 1 and 255. + + The code for this option is 23, and its length is 1. + + Code Len TTL + +-----+-----+-----+ + | 23 | 1 | ttl | + +-----+-----+-----+ + +4.6. Path MTU Aging Timeout Option + + This option specifies the timeout (in seconds) to use when aging Path + MTU values discovered by the mechanism defined in RFC 1191 [12]. The + timeout is specified as a 32-bit unsigned integer. + + The code for this option is 24, and its length is 4. + + + + +Alexander & Droms Standards Track [Page 12] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + Code Len Timeout + +-----+-----+-----+-----+-----+-----+ + | 24 | 4 | t1 | t2 | t3 | t4 | + +-----+-----+-----+-----+-----+-----+ + +4.7. Path MTU Plateau Table Option + + This option specifies a table of MTU sizes to use when performing + Path MTU Discovery as defined in RFC 1191. The table is formatted as + a list of 16-bit unsigned integers, ordered from smallest to largest. + The minimum MTU value cannot be smaller than 68. + + The code for this option is 25. Its minimum length is 2, and the + length MUST be a multiple of 2. + + Code Len Size 1 Size 2 + +-----+-----+-----+-----+-----+-----+--- + | 25 | n | s1 | s2 | s1 | s2 | ... + +-----+-----+-----+-----+-----+-----+--- + +5. IP Layer Parameters per Interface + + This section details the options that affect the operation of the IP + layer on a per-interface basis. It is expected that a client can + issue multiple requests, one per interface, in order to configure + interfaces with their specific parameters. + +5.1. Interface MTU Option + + This option specifies the MTU to use on this interface. The MTU is + specified as a 16-bit unsigned integer. The minimum legal value for + the MTU is 68. + + The code for this option is 26, and its length is 2. + + Code Len MTU + +-----+-----+-----+-----+ + | 26 | 2 | m1 | m2 | + +-----+-----+-----+-----+ + +5.2. All Subnets are Local Option + + This option specifies whether or not the client may assume that all + subnets of the IP network to which the client is connected use the + same MTU as the subnet of that network to which the client is + directly connected. A value of 1 indicates that all subnets share + the same MTU. A value of 0 means that the client should assume that + some subnets of the directly connected network may have smaller MTUs. + + + +Alexander & Droms Standards Track [Page 13] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + The code for this option is 27, and its length is 1. + + Code Len Value + +-----+-----+-----+ + | 27 | 1 | 0/1 | + +-----+-----+-----+ + +5.3. Broadcast Address Option + + This option specifies the broadcast address in use on the client's + subnet. Legal values for broadcast addresses are specified in + section 3.2.1.3 of [4]. + + The code for this option is 28, and its length is 4. + + Code Len Broadcast Address + +-----+-----+-----+-----+-----+-----+ + | 28 | 4 | b1 | b2 | b3 | b4 | + +-----+-----+-----+-----+-----+-----+ + +5.4. Perform Mask Discovery Option + + This option specifies whether or not the client should perform subnet + mask discovery using ICMP. A value of 0 indicates that the client + should not perform mask discovery. A value of 1 means that the + client should perform mask discovery. + + The code for this option is 29, and its length is 1. + + Code Len Value + +-----+-----+-----+ + | 29 | 1 | 0/1 | + +-----+-----+-----+ + +5.5. Mask Supplier Option + + This option specifies whether or not the client should respond to + subnet mask requests using ICMP. A value of 0 indicates that the + client should not respond. A value of 1 means that the client should + respond. + + The code for this option is 30, and its length is 1. + + Code Len Value + +-----+-----+-----+ + | 30 | 1 | 0/1 | + +-----+-----+-----+ + + + + +Alexander & Droms Standards Track [Page 14] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + +5.6. Perform Router Discovery Option + + This option specifies whether or not the client should solicit + routers using the Router Discovery mechanism defined in RFC 1256 + [13]. A value of 0 indicates that the client should not perform + router discovery. A value of 1 means that the client should perform + router discovery. + + The code for this option is 31, and its length is 1. + + Code Len Value + +-----+-----+-----+ + | 31 | 1 | 0/1 | + +-----+-----+-----+ + +5.7. Router Solicitation Address Option + + This option specifies the address to which the client should transmit + router solicitation requests. + + The code for this option is 32, and its length is 4. + + Code Len Address + +-----+-----+-----+-----+-----+-----+ + | 32 | 4 | a1 | a2 | a3 | a4 | + +-----+-----+-----+-----+-----+-----+ + +5.8. Static Route Option + + This option specifies a list of static routes that the client should + install in its routing cache. If multiple routes to the same + destination are specified, they are listed in descending order of + priority. + + The routes consist of a list of IP address pairs. The first address + is the destination address, and the second address is the router for + the destination. + + The default route (0.0.0.0) is an illegal destination for a static + route. See section 3.5 for information about the router option. + + The code for this option is 33. The minimum length of this option is + 8, and the length MUST be a multiple of 8. + + + + + + + + +Alexander & Droms Standards Track [Page 15] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + Code Len Destination 1 Router 1 + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+ + | 33 | n | d1 | d2 | d3 | d4 | r1 | r2 | r3 | r4 | + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+ + Destination 2 Router 2 + +-----+-----+-----+-----+-----+-----+-----+-----+--- + | d1 | d2 | d3 | d4 | r1 | r2 | r3 | r4 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+--- + +6. Link Layer Parameters per Interface + + This section lists the options that affect the operation of the data + link layer on a per-interface basis. + +6.1. Trailer Encapsulation Option + + This option specifies whether or not the client should negotiate the + use of trailers (RFC 893 [14]) when using the ARP protocol. A value + of 0 indicates that the client should not attempt to use trailers. A + value of 1 means that the client should attempt to use trailers. + + The code for this option is 34, and its length is 1. + + Code Len Value + +-----+-----+-----+ + | 34 | 1 | 0/1 | + +-----+-----+-----+ + +6.2. ARP Cache Timeout Option + + This option specifies the timeout in seconds for ARP cache entries. + The time is specified as a 32-bit unsigned integer. + + The code for this option is 35, and its length is 4. + + Code Len Time + +-----+-----+-----+-----+-----+-----+ + | 35 | 4 | t1 | t2 | t3 | t4 | + +-----+-----+-----+-----+-----+-----+ + +6.3. Ethernet Encapsulation Option + + This option specifies whether or not the client should use Ethernet + Version 2 (RFC 894 [15]) or IEEE 802.3 (RFC 1042 [16]) encapsulation + if the interface is an Ethernet. A value of 0 indicates that the + client should use RFC 894 encapsulation. A value of 1 means that the + client should use RFC 1042 encapsulation. + + + + +Alexander & Droms Standards Track [Page 16] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + The code for this option is 36, and its length is 1. + + Code Len Value + +-----+-----+-----+ + | 36 | 1 | 0/1 | + +-----+-----+-----+ + +7. TCP Parameters + + This section lists the options that affect the operation of the TCP + layer on a per-interface basis. + +7.1. TCP Default TTL Option + + This option specifies the default TTL that the client should use when + sending TCP segments. The value is represented as an 8-bit unsigned + integer. The minimum value is 1. + + The code for this option is 37, and its length is 1. + + Code Len TTL + +-----+-----+-----+ + | 37 | 1 | n | + +-----+-----+-----+ + +7.2. TCP Keepalive Interval Option + + This option specifies the interval (in seconds) that the client TCP + should wait before sending a keepalive message on a TCP connection. + The time is specified as a 32-bit unsigned integer. A value of zero + indicates that the client should not generate keepalive messages on + connections unless specifically requested by an application. + + The code for this option is 38, and its length is 4. + + Code Len Time + +-----+-----+-----+-----+-----+-----+ + | 38 | 4 | t1 | t2 | t3 | t4 | + +-----+-----+-----+-----+-----+-----+ + +7.3. TCP Keepalive Garbage Option + + This option specifies the whether or not the client should send TCP + keepalive messages with a octet of garbage for compatibility with + older implementations. A value of 0 indicates that a garbage octet + should not be sent. A value of 1 indicates that a garbage octet + should be sent. + + + + +Alexander & Droms Standards Track [Page 17] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + The code for this option is 39, and its length is 1. + + Code Len Value + +-----+-----+-----+ + | 39 | 1 | 0/1 | + +-----+-----+-----+ + +8. Application and Service Parameters + + This section details some miscellaneous options used to configure + miscellaneous applications and services. + +8.1. Network Information Service Domain Option + + This option specifies the name of the client's NIS [17] domain. The + domain is formatted as a character string consisting of characters + from the NVT ASCII character set. + + The code for this option is 40. Its minimum length is 1. + + Code Len NIS Domain Name + +-----+-----+-----+-----+-----+-----+--- + | 40 | n | n1 | n2 | n3 | n4 | ... + +-----+-----+-----+-----+-----+-----+--- + +8.2. Network Information Servers Option + + This option specifies a list of IP addresses indicating NIS servers + available to the client. Servers SHOULD be listed in order of + preference. + + The code for this option is 41. Its minimum length is 4, and the + length MUST be a multiple of 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 41 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +8.3. Network Time Protocol Servers Option + + This option specifies a list of IP addresses indicating NTP [18] + servers available to the client. Servers SHOULD be listed in order + of preference. + + The code for this option is 42. Its minimum length is 4, and the + length MUST be a multiple of 4. + + + + +Alexander & Droms Standards Track [Page 18] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 42 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +8.4. Vendor Specific Information + + This option is used by clients and servers to exchange vendor- + specific information. The information is an opaque object of n + octets, presumably interpreted by vendor-specific code on the clients + and servers. The definition of this information is vendor specific. + The vendor is indicated in the vendor class identifier option. + Servers not equipped to interpret the vendor-specific information + sent by a client MUST ignore it (although it may be reported). + Clients which do not receive desired vendor-specific information + SHOULD make an attempt to operate without it, although they may do so + (and announce they are doing so) in a degraded mode. + + If a vendor potentially encodes more than one item of information in + this option, then the vendor SHOULD encode the option using + "Encapsulated vendor-specific options" as described below: + + The Encapsulated vendor-specific options field SHOULD be encoded as a + sequence of code/length/value fields of identical syntax to the DHCP + options field with the following exceptions: + + 1) There SHOULD NOT be a "magic cookie" field in the encapsulated + vendor-specific extensions field. + + 2) Codes other than 0 or 255 MAY be redefined by the vendor within + the encapsulated vendor-specific extensions field, but SHOULD + conform to the tag-length-value syntax defined in section 2. + + 3) Code 255 (END), if present, signifies the end of the + encapsulated vendor extensions, not the end of the vendor + extensions field. If no code 255 is present, then the end of + the enclosing vendor-specific information field is taken as the + end of the encapsulated vendor-specific extensions field. + + The code for this option is 43 and its minimum length is 1. + + Code Len Vendor-specific information + +-----+-----+-----+-----+--- + | 43 | n | i1 | i2 | ... + +-----+-----+-----+-----+--- + + + + + + +Alexander & Droms Standards Track [Page 19] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + When encapsulated vendor-specific extensions are used, the + information bytes 1-n have the following format: + + Code Len Data item Code Len Data item Code + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+ + | T1 | n | d1 | d2 | ... | T2 | n | D1 | D2 | ... | ... | + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+ + +8.5. NetBIOS over TCP/IP Name Server Option + + The NetBIOS name server (NBNS) option specifies a list of RFC + 1001/1002 [19] [20] NBNS name servers listed in order of preference. + + The code for this option is 44. The minimum length of the option is + 4 octets, and the length must always be a multiple of 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+---- + | 44 | n | a1 | a2 | a3 | a4 | b1 | b2 | b3 | b4 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+---- + +8.6. NetBIOS over TCP/IP Datagram Distribution Server Option + + The NetBIOS datagram distribution server (NBDD) option specifies a + list of RFC 1001/1002 NBDD servers listed in order of preference. The + code for this option is 45. The minimum length of the option is 4 + octets, and the length must always be a multiple of 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+---- + | 45 | n | a1 | a2 | a3 | a4 | b1 | b2 | b3 | b4 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+---- + +8.7. NetBIOS over TCP/IP Node Type Option + + The NetBIOS node type option allows NetBIOS over TCP/IP clients which + are configurable to be configured as described in RFC 1001/1002. The + value is specified as a single octet which identifies the client type + as follows: + + Value Node Type + ----- --------- + 0x1 B-node + 0x2 P-node + 0x4 M-node + 0x8 H-node + + + + + +Alexander & Droms Standards Track [Page 20] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + In the above chart, the notation '0x' indicates a number in base-16 + (hexadecimal). + + The code for this option is 46. The length of this option is always + 1. + + Code Len Node Type + +-----+-----+-----------+ + | 46 | 1 | see above | + +-----+-----+-----------+ + +8.8. NetBIOS over TCP/IP Scope Option + + The NetBIOS scope option specifies the NetBIOS over TCP/IP scope + parameter for the client as specified in RFC 1001/1002. See [19], + [20], and [8] for character-set restrictions. + + The code for this option is 47. The minimum length of this option is + 1. + + Code Len NetBIOS Scope + +-----+-----+-----+-----+-----+-----+---- + | 47 | n | s1 | s2 | s3 | s4 | ... + +-----+-----+-----+-----+-----+-----+---- + +8.9. X Window System Font Server Option + + This option specifies a list of X Window System [21] Font servers + available to the client. Servers SHOULD be listed in order of + preference. + + The code for this option is 48. The minimum length of this option is + 4 octets, and the length MUST be a multiple of 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+--- + | 48 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+--- + +8.10. X Window System Display Manager Option + + This option specifies a list of IP addresses of systems that are + running the X Window System Display Manager and are available to the + client. + + Addresses SHOULD be listed in order of preference. + + + + + +Alexander & Droms Standards Track [Page 21] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + The code for the this option is 49. The minimum length of this option + is 4, and the length MUST be a multiple of 4. + + Code Len Address 1 Address 2 + + +-----+-----+-----+-----+-----+-----+-----+-----+--- + | 49 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+--- + +8.11. Network Information Service+ Domain Option + + This option specifies the name of the client's NIS+ [17] domain. The + domain is formatted as a character string consisting of characters + from the NVT ASCII character set. + + The code for this option is 64. Its minimum length is 1. + + Code Len NIS Client Domain Name + +-----+-----+-----+-----+-----+-----+--- + | 64 | n | n1 | n2 | n3 | n4 | ... + +-----+-----+-----+-----+-----+-----+--- + +8.12. Network Information Service+ Servers Option + + This option specifies a list of IP addresses indicating NIS+ servers + available to the client. Servers SHOULD be listed in order of + preference. + + The code for this option is 65. Its minimum length is 4, and the + length MUST be a multiple of 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 65 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +8.13. Mobile IP Home Agent option + + This option specifies a list of IP addresses indicating mobile IP + home agents available to the client. Agents SHOULD be listed in + order of preference. + + The code for this option is 68. Its minimum length is 0 (indicating + no home agents are available) and the length MUST be a multiple of 4. + It is expected that the usual length will be four octets, containing + a single home agent's address. + + + + + +Alexander & Droms Standards Track [Page 22] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + Code Len Home Agent Addresses (zero or more) + +-----+-----+-----+-----+-----+-----+-- + | 68 | n | a1 | a2 | a3 | a4 | ... + +-----+-----+-----+-----+-----+-----+-- + +8.14. Simple Mail Transport Protocol (SMTP) Server Option + + The SMTP server option specifies a list of SMTP servers available to + the client. Servers SHOULD be listed in order of preference. + + The code for the SMTP server option is 69. The minimum length for + this option is 4 octets, and the length MUST always be a multiple of + 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 69 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +8.15. Post Office Protocol (POP3) Server Option + + The POP3 server option specifies a list of POP3 available to the + client. Servers SHOULD be listed in order of preference. + + The code for the POP3 server option is 70. The minimum length for + this option is 4 octets, and the length MUST always be a multiple of + 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 70 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +8.16. Network News Transport Protocol (NNTP) Server Option + + The NNTP server option specifies a list of NNTP available to the + client. Servers SHOULD be listed in order of preference. + + The code for the NNTP server option is 71. The minimum length for + this option is 4 octets, and the length MUST always be a multiple of + 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 71 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + + + + + +Alexander & Droms Standards Track [Page 23] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + +8.17. Default World Wide Web (WWW) Server Option + + The WWW server option specifies a list of WWW available to the + client. Servers SHOULD be listed in order of preference. + + The code for the WWW server option is 72. The minimum length for + this option is 4 octets, and the length MUST always be a multiple of + 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 72 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +8.18. Default Finger Server Option + + The Finger server option specifies a list of Finger available to the + client. Servers SHOULD be listed in order of preference. + + The code for the Finger server option is 73. The minimum length for + this option is 4 octets, and the length MUST always be a multiple of + 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 73 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +8.19. Default Internet Relay Chat (IRC) Server Option + + The IRC server option specifies a list of IRC available to the + client. Servers SHOULD be listed in order of preference. + + The code for the IRC server option is 74. The minimum length for + this option is 4 octets, and the length MUST always be a multiple of + 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 74 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +8.20. StreetTalk Server Option + + The StreetTalk server option specifies a list of StreetTalk servers + available to the client. Servers SHOULD be listed in order of + preference. + + + + +Alexander & Droms Standards Track [Page 24] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + The code for the StreetTalk server option is 75. The minimum length + for this option is 4 octets, and the length MUST always be a multiple + of 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 75 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +8.21. StreetTalk Directory Assistance (STDA) Server Option + + The StreetTalk Directory Assistance (STDA) server option specifies a + list of STDA servers available to the client. Servers SHOULD be + listed in order of preference. + + The code for the StreetTalk Directory Assistance server option is 76. + The minimum length for this option is 4 octets, and the length MUST + always be a multiple of 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 76 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + +9. DHCP Extensions + + This section details the options that are specific to DHCP. + +9.1. Requested IP Address + + This option is used in a client request (DHCPDISCOVER) to allow the + client to request that a particular IP address be assigned. + + The code for this option is 50, and its length is 4. + + Code Len Address + +-----+-----+-----+-----+-----+-----+ + | 50 | 4 | a1 | a2 | a3 | a4 | + +-----+-----+-----+-----+-----+-----+ + +9.2. IP Address Lease Time + + This option is used in a client request (DHCPDISCOVER or DHCPREQUEST) + to allow the client to request a lease time for the IP address. In a + server reply (DHCPOFFER), a DHCP server uses this option to specify + the lease time it is willing to offer. + + + + + +Alexander & Droms Standards Track [Page 25] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + The time is in units of seconds, and is specified as a 32-bit + unsigned integer. + + The code for this option is 51, and its length is 4. + + Code Len Lease Time + +-----+-----+-----+-----+-----+-----+ + | 51 | 4 | t1 | t2 | t3 | t4 | + +-----+-----+-----+-----+-----+-----+ + +9.3. Option Overload + + This option is used to indicate that the DHCP 'sname' or 'file' + fields are being overloaded by using them to carry DHCP options. A + DHCP server inserts this option if the returned parameters will + exceed the usual space allotted for options. + + If this option is present, the client interprets the specified + additional fields after it concludes interpretation of the standard + option fields. + + The code for this option is 52, and its length is 1. Legal values + for this option are: + + Value Meaning + ----- -------- + 1 the 'file' field is used to hold options + 2 the 'sname' field is used to hold options + 3 both fields are used to hold options + + Code Len Value + +-----+-----+-----+ + | 52 | 1 |1/2/3| + +-----+-----+-----+ + +9.4 TFTP server name + + This option is used to identify a TFTP server when the 'sname' field + in the DHCP header has been used for DHCP options. + + The code for this option is 66, and its minimum length is 1. + + Code Len TFTP server + +-----+-----+-----+-----+-----+--- + | 66 | n | c1 | c2 | c3 | ... + +-----+-----+-----+-----+-----+--- + + + + + +Alexander & Droms Standards Track [Page 26] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + +9.5 Bootfile name + + This option is used to identify a bootfile when the 'file' field in + the DHCP header has been used for DHCP options. + + The code for this option is 67, and its minimum length is 1. + + Code Len Bootfile name + +-----+-----+-----+-----+-----+--- + | 67 | n | c1 | c2 | c3 | ... + +-----+-----+-----+-----+-----+--- + +9.6. DHCP Message Type + + This option is used to convey the type of the DHCP message. The code + for this option is 53, and its length is 1. Legal values for this + option are: + + Value Message Type + ----- ------------ + 1 DHCPDISCOVER + 2 DHCPOFFER + 3 DHCPREQUEST + 4 DHCPDECLINE + 5 DHCPACK + 6 DHCPNAK + 7 DHCPRELEASE + 8 DHCPINFORM + + Code Len Type + +-----+-----+-----+ + | 53 | 1 | 1-9 | + +-----+-----+-----+ + +9.7. Server Identifier + + This option is used in DHCPOFFER and DHCPREQUEST messages, and may + optionally be included in the DHCPACK and DHCPNAK messages. DHCP + servers include this option in the DHCPOFFER in order to allow the + client to distinguish between lease offers. DHCP clients use the + contents of the 'server identifier' field as the destination address + for any DHCP messages unicast to the DHCP server. DHCP clients also + indicate which of several lease offers is being accepted by including + this option in a DHCPREQUEST message. + + The identifier is the IP address of the selected server. + + The code for this option is 54, and its length is 4. + + + +Alexander & Droms Standards Track [Page 27] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + Code Len Address + +-----+-----+-----+-----+-----+-----+ + | 54 | 4 | a1 | a2 | a3 | a4 | + +-----+-----+-----+-----+-----+-----+ + +9.8. Parameter Request List + + This option is used by a DHCP client to request values for specified + configuration parameters. The list of requested parameters is + specified as n octets, where each octet is a valid DHCP option code + as defined in this document. + + The client MAY list the options in order of preference. The DHCP + server is not required to return the options in the requested order, + but MUST try to insert the requested options in the order requested + by the client. + + The code for this option is 55. Its minimum length is 1. + + Code Len Option Codes + +-----+-----+-----+-----+--- + | 55 | n | c1 | c2 | ... + +-----+-----+-----+-----+--- + +9.9. Message + + This option is used by a DHCP server to provide an error message to a + DHCP client in a DHCPNAK message in the event of a failure. A client + may use this option in a DHCPDECLINE message to indicate the why the + client declined the offered parameters. The message consists of n + octets of NVT ASCII text, which the client may display on an + available output device. + + The code for this option is 56 and its minimum length is 1. + + Code Len Text + +-----+-----+-----+-----+--- + | 56 | n | c1 | c2 | ... + +-----+-----+-----+-----+--- + +9.10. Maximum DHCP Message Size + + This option specifies the maximum length DHCP message that it is + willing to accept. The length is specified as an unsigned 16-bit + integer. A client may use the maximum DHCP message size option in + DHCPDISCOVER or DHCPREQUEST messages, but should not use the option + in DHCPDECLINE messages. + + + + +Alexander & Droms Standards Track [Page 28] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + The code for this option is 57, and its length is 2. The minimum + legal value is 576 octets. + + Code Len Length + +-----+-----+-----+-----+ + | 57 | 2 | l1 | l2 | + +-----+-----+-----+-----+ + +9.11. Renewal (T1) Time Value + + This option specifies the time interval from address assignment until + the client transitions to the RENEWING state. + + The value is in units of seconds, and is specified as a 32-bit + unsigned integer. + + The code for this option is 58, and its length is 4. + + Code Len T1 Interval + +-----+-----+-----+-----+-----+-----+ + | 58 | 4 | t1 | t2 | t3 | t4 | + +-----+-----+-----+-----+-----+-----+ + +9.12. Rebinding (T2) Time Value + + This option specifies the time interval from address assignment until + the client transitions to the REBINDING state. + + The value is in units of seconds, and is specified as a 32-bit + unsigned integer. + + The code for this option is 59, and its length is 4. + + Code Len T2 Interval + +-----+-----+-----+-----+-----+-----+ + | 59 | 4 | t1 | t2 | t3 | t4 | + +-----+-----+-----+-----+-----+-----+ + +9.13. Vendor class identifier + + This option is used by DHCP clients to optionally identify the vendor + type and configuration of a DHCP client. The information is a string + of n octets, interpreted by servers. Vendors may choose to define + specific vendor class identifiers to convey particular configuration + or other identification information about a client. For example, the + identifier may encode the client's hardware configuration. Servers + not equipped to interpret the class-specific information sent by a + client MUST ignore it (although it may be reported). Servers that + + + +Alexander & Droms Standards Track [Page 29] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + respond SHOULD only use option 43 to return the vendor-specific + information to the client. + + The code for this option is 60, and its minimum length is 1. + + Code Len Vendor class Identifier + +-----+-----+-----+-----+--- + | 60 | n | i1 | i2 | ... + +-----+-----+-----+-----+--- + +9.14. Client-identifier + + This option is used by DHCP clients to specify their unique + identifier. DHCP servers use this value to index their database of + address bindings. This value is expected to be unique for all + clients in an administrative domain. + + Identifiers SHOULD be treated as opaque objects by DHCP servers. + + The client identifier MAY consist of type-value pairs similar to the + 'htype'/'chaddr' fields defined in [3]. For instance, it MAY consist + of a hardware type and hardware address. In this case the type field + SHOULD be one of the ARP hardware types defined in STD2 [22]. A + hardware type of 0 (zero) should be used when the value field + contains an identifier other than a hardware address (e.g. a fully + qualified domain name). + + For correct identification of clients, each client's client- + identifier MUST be unique among the client-identifiers used on the + subnet to which the client is attached. Vendors and system + administrators are responsible for choosing client-identifiers that + meet this requirement for uniqueness. + + The code for this option is 61, and its minimum length is 2. + + Code Len Type Client-Identifier + +-----+-----+-----+-----+-----+--- + | 61 | n | t1 | i1 | i2 | ... + +-----+-----+-----+-----+-----+--- + + + + + + + + + + + + +Alexander & Droms Standards Track [Page 30] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + +10. Defining new extensions + + The author of a new DHCP option will follow these steps to obtain + acceptance of the option as a part of the DHCP Internet Standard: + + 1. The author devises the new option. + 2. The author requests a number for the new option from IANA by + contacting: + Internet Assigned Numbers Authority (IANA) + USC/Information Sciences Institute + 4676 Admiralty Way + Marina del Rey, California 90292-6695 + + or by email as: iana@iana.org + + 3. The author documents the new option, using the newly obtained + option number, as an Internet Draft. + 4. The author submits the Internet Draft for review through the IETF + standards process as defined in "Internet Official Protocol + Standards" (STD 1). The new option will be submitted for eventual + acceptance as an Internet Standard. + 5. The new option progresses through the IETF standards process; the + new option will be reviewed by the Dynamic Host Configuration + Working Group (if that group still exists), or as an Internet + Draft not submitted by an IETF working group. + 6. If the new option fails to gain acceptance as an Internet + Standard, the assigned option number will be returned to IANA for + reassignment. + + This procedure for defining new extensions will ensure that: + + * allocation of new option numbers is coordinated from a single + authority, + * new options are reviewed for technical correctness and + appropriateness, and + * documentation for new options is complete and published. + +11. Acknowledgements + + The author thanks the many (and too numerous to mention!) members of + the DHC WG for their tireless and ongoing efforts in the development + of DHCP and this document. + + The efforts of J Allard, Mike Carney, Dave Lapp, Fred Lien and John + Mendonca in organizing DHCP interoperability testing sessions are + gratefully acknowledged. + + + + + +Alexander & Droms Standards Track [Page 31] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + The development of this document was supported in part by grants from + the Corporation for National Research Initiatives (CNRI), Bucknell + University and Sun Microsystems. + +12. References + + [1] Droms, R., "Dynamic Host Configuration Protocol", RFC 2131, + Bucknell University, March 1997. + + [2] Reynolds, J., "BOOTP Vendor Information Extensions", RFC 1497, + USC/Information Sciences Institute, August 1993. + + [3] Croft, W., and J. Gilmore, "Bootstrap Protocol", RFC 951, + Stanford University and Sun Microsystems, September 1985. + + [4] Braden, R., Editor, "Requirements for Internet Hosts - + Communication Layers", STD 3, RFC 1122, USC/Information Sciences + Institute, October 1989. + + [5] Mogul, J., and J. Postel, "Internet Standard Subnetting + Procedure", STD 5, RFC 950, USC/Information Sciences Institute, + August 1985. + + [6] Postel, J., and K. Harrenstien, "Time Protocol", STD 26, RFC + 868, USC/Information Sciences Institute, SRI, May 1983. + + [7] Postel, J., "Name Server", IEN 116, USC/Information Sciences + Institute, August 1979. + + [8] Mockapetris, P., "Domain Names - Implementation and + Specification", STD 13, RFC 1035, USC/Information Sciences + Institute, November 1987. + + [9] Postel, J., "Quote of the Day Protocol", STD 23, RFC 865, + USC/Information Sciences Institute, May 1983. + + [10] McLaughlin, L., "Line Printer Daemon Protocol", RFC 1179, The + Wollongong Group, August 1990. + + [11] Accetta, M., "Resource Location Protocol", RFC 887, CMU, + December 1983. + + [12] Mogul, J. and S. Deering, "Path MTU Discovery", RFC 1191, + DECWRL, Stanford University, November 1990. + + [13] Deering, S., "ICMP Router Discovery Messages", RFC 1256, + Xerox PARC, September 1991. + + + + +Alexander & Droms Standards Track [Page 32] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + + [14] Leffler, S. and M. Karels, "Trailer Encapsulations", RFC 893, + U. C. Berkeley, April 1984. + + [15] Hornig, C., "Standard for the Transmission of IP Datagrams over + Ethernet Networks", RFC 894, Symbolics, April 1984. + + [16] Postel, J. and J. Reynolds, "Standard for the Transmission of + IP Datagrams Over IEEE 802 Networks", RFC 1042, USC/Information + Sciences Institute, February 1988. + + [17] Sun Microsystems, "System and Network Administration", March + 1990. + + [18] Mills, D., "Internet Time Synchronization: The Network Time + Protocol", RFC 1305, UDEL, March 1992. + + [19] NetBIOS Working Group, "Protocol Standard for a NetBIOS Service + on a TCP/UDP transport: Concepts and Methods", STD 19, RFC 1001, + March 1987. + + [20] NetBIOS Working Group, "Protocol Standard for a NetBIOS Service + on a TCP/UDP transport: Detailed Specifications", STD 19, RFC + 1002, March 1987. + + [21] Scheifler, R., "FYI On the X Window System", FYI 6, RFC 1198, + MIT Laboratory for Computer Science, January 1991. + + [22] Reynolds, J., and J. Postel, "Assigned Numbers", STD 2, RFC 1700, + USC/Information Sciences Institute, July 1992. + +13. Security Considerations + + Security issues are not discussed in this memo. + + + + + + + + + + + + + + + + + + +Alexander & Droms Standards Track [Page 33] + +RFC 2132 DHCP Options and BOOTP Vendor Extensions March 1997 + + +14. Authors' Addresses + + Steve Alexander + Silicon Graphics, Inc. + 2011 N. Shoreline Boulevard + Mailstop 510 + Mountain View, CA 94043-1389 + + Phone: (415) 933-6172 + EMail: sca@engr.sgi.com + + + Ralph Droms + Bucknell University + Lewisburg, PA 17837 + + Phone: (717) 524-1145 + EMail: droms@bucknell.edu + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Alexander & Droms Standards Track [Page 34] + diff --git a/docs/rfc3203.txt b/docs/rfc3203.txt new file mode 100644 index 0000000..5f5b567 --- /dev/null +++ b/docs/rfc3203.txt @@ -0,0 +1,339 @@ + + + + + + +Network Working Group Y. T'Joens +Request for Comments: 3203 C. Hublet +Category: Standards Track Alcatel + P. De Schrijver + Mind + December 2001 + + + DHCP reconfigure extension + +Status of this Memo + + 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. + +Copyright Notice + + Copyright (C) The Internet Society (2001). All Rights Reserved. + +Abstract + + This document defines extensions to DHCP (Dynamic Host Configuration + Protocol) to allow dynamic reconfiguration of a single host triggered + by the DHCP server (e.g., a new IP address and/or local configuration + parameters). This is achieved by introducing a unicast FORCERENEW + message which forces the client to the RENEW state. The behaviour + for hosts using the DHCP INFORM message to obtain configuration + information is also described. + +1. Introduction + + The procedures as described within this document allow the dynamic + reconfiguration of individual hosts. + +1.1 Conventions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC2119]. + +2. DHCP force renew + + This section describes the FORCERENEW message extension. + + + + + +T'Joens, et al. Standards Track [Page 1] + +RFC 3203 DHCP reconfigure extension December 2001 + + +2.1 Terminology + + DHCP client : host to be reconfigured using DHCP. + + DHCP server : server which configured the DHCP client. + +2.2 Force renew procedures + + The DHCP server sends a unicast FORCERENEW message to the client. + Upon receipt of the unicast FORCERENEW message, the client will + change its state to the RENEW state, and will then try to renew its + lease according to normal DHCP procedures. If the server wants to + assign a new IP address to the client, it will reply to the DHCP + REQUEST with a DHCP NAK. The client will then go back to the init + state and broadcast a DHCP DISCOVER message. The server can now + assign a new IP address to the client by replying with a DHCP OFFER. + If the FORCERENEW message is lost, the DHCP server will not receive a + DHCP REQUEST from the client and it should retransmit the FORCERENEW + message using an exponential backoff algorithm. Depending on the + bandwidth of the network between server and client, the server should + choose a delay. This delay grows exponentially as retransmissions + fail. The amount of retransmissions should be limited. + + The procedures described above assume the server to send a unicast + FORCERENEW message to the client. Receipt of a multicast FORCERENEW + message by the client should be silently discarded. + + It can be that a client has obtained a network address through some + other means (e.g., manual configuration) and has used a DHCP INFORM + request to obtain other local configuration parameters. Such clients + should respond to the receipt of a unicast FORCERENEW message with a + new DHCP INFORM request so as to obtain a potential new set of local + configuration parameters. Note that the usage of these procedures + are limited to the set of options that are eligible for configuration + by DHCP and should not override manually configured parameters. + + Note further that usage of the FORCERENEW message to reconfigure a + client address or local configuration parameters can lead to the + interruption of active sessions, and that as such these procedures + should be used in controlled circumstances. + + + + + + + + + + + +T'Joens, et al. Standards Track [Page 2] + +RFC 3203 DHCP reconfigure extension December 2001 + + +2.3 Example usage + +2.3.1 Embedded DHCP clients + + The autoconfiguration of home gateways (more generically Network + Termination equipment) for public networking purposes can be achieved + through means of DHCP, as described in [DSL_autoconf]. In order to + allow service changes or service interruption, the FORCERENEW message + can trigger the home gateway to contact the DHCP server, prior to the + expiry of the lease. + +2.3.2 Hospitality service scenario + + In self provisioned networks, e.g., hotel rooms, the hotel owned DHCP + server can hand out limited use IP addresses, that allows the + customer to consume local services or select external services from a + web browser interface. In order to allow external services through + other service providers, e.g., global internet services or enterprise + VPN services, the DHCP server can trigger the client to ask for a new + DHCP initialization session so as to obtain e.g., a globally routed + IP address. + +2.3.3 Network renumbering + + Under tightly controlled conditions, the FORCERENEW procedures can be + used to brute force the renumbering of entire subnets, client per + client, under control of a DHCP server. + +2.4 Rationale + + The approach as described in this document has a number of + advantages. It does not require new states to be added to the DHCP + client implementation. This minimizes the amount of code to be + changed. It also allows lease RENEWAL to be driven by the server, + which can be used to optimize network usage or DHCP server load. + + + + + + + + + + + + + + + + +T'Joens, et al. Standards Track [Page 3] + +RFC 3203 DHCP reconfigure extension December 2001 + + +3. Extended DHCP state diagram + ++--------+ +------+ +| Init / | +-->+ Init +<---------------+-------------------+ +| Reboot | | +--+---+ | | ++---+----+ DHCPNAK/ -/Send DHCPDISCOVER | | + | Restart | (broadcast) | | + | | v v-------------+ | | + -/Send DHCPREQUEST| +----+------+ DHCPOFFER/DHCPDECLINE | + | (broadcast)| | Selecting |----------+ | | + v | +----+------+ | | ++---+----+ | DHCPOFFER/DHCPREQUEST | | +| Reboot +---------+ (broadcast) | | ++---+----+ v | | + | +----+-------+ DHCPNAK /halt network + | + Requesting | | lease expired + DHCPACK/ +----+-------+ | | + Record lease | | | + set timers DHCPACK/Record lease | | + | v Set T1 & T2 | | + | +--+----+DHCPFORCE +---+---+ +----+---+ + +----------------->+ Bound +---------->+ Renew +--------->+ Rebind | + +--+-+--+T1 expires +-+-+---+T2 expires+----+---+ + ^ /DHCPREQUEST | | /broadcast | + DHCPACK to leasing | | DHCPREQUEST | + | server | | | + +----------------------------------------+ + +4. Message layout + + The FORCERENEW message makes use of the normal DHCP message layout + with the introduction of a new DHCP message type. DHCP option 53 + (DHCP message type) is extended with a new value: DHCPFORCERENEW (9) + +5. IANA Considerations + + The new value for DHCP option 53 (DHCP message type) to indicate a + DHCPFORCERENEW message is 9. + +6. Security Considerations + + As in some network environments FORCERENEW can be used to snoop and + spoof traffic, the FORCERENEW message MUST be authenticated using the + procedures as described in [DHCP-AUTH]. FORCERENEW messages failing + the authentication should be silently discarded by the client. + + + + + + +T'Joens, et al. Standards Track [Page 4] + +RFC 3203 DHCP reconfigure extension December 2001 + + +6.1 Protocol vulnerabilities + + The mechanism described in this document is vulnerable to a denial of + service attack through flooding a client with bogus FORCERENEW + messages. The calculations involved in authenticating the bogus + FORECERENEW messages may overwhelm the device on which the client is + running. + +7. References + + [DHCP] Droms, R., "Dynamic Host Configuration Protocol", RFC + 2131, March 1997. + + [DHCP-AUTH] Droms, R. and W. Arbaugh, "Authentication for DHCP + Messages", RFC 3118, June 2001. + + [DSL_autoconf] Technical Report TR-044, "Auto-Configuration for Basic + Internet (IP-based) Services", DSL Forum, November + 2001 + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + +8. Acknowledgements + + The authors would like to thank David Allan, Nortel, for the + constructive comments to these procedures. + +9. Authors' Addresses + + Yves T'joens + Alcatel Network Strategy Group + Francis Wellesplein 1, 2018 Antwerp, Belgium + Phone: +32 3 240 7890 + EMail: yves.tjoens@alcatel.be + + + Peter De Schrijver + Mind NV + Vaartkom 11 + 3000 Leuven + EMail: p2@mind.be + + + Alcatel Broadband Networking Division + Veldkant 33b, 2550 Kontich, Belgium + Phone: +32 3 450 3322 + EMail: Christian.Hublet@alcatel.be + + + +T'Joens, et al. Standards Track [Page 5] + +RFC 3203 DHCP reconfigure extension December 2001 + + +10. Full Copyright Statement + + Copyright (C) The Internet Society (2001). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +T'Joens, et al. Standards Track [Page 6] + diff --git a/docs/rfc3397.txt b/docs/rfc3397.txt new file mode 100644 index 0000000..d8cb7f5 --- /dev/null +++ b/docs/rfc3397.txt @@ -0,0 +1,451 @@ + + + + + + +Network Working Group B. Aboba +Request for Comments: 3397 Microsoft +Category: Standards Track S. Cheshire + Apple Computer, Inc. + November 2002 + + + Dynamic Host Configuration Protocol (DHCP) Domain Search Option + +Status of this Memo + + 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. + +Copyright Notice + + Copyright (C) The Internet Society (2002). All Rights Reserved. + +Abstract + + This document defines a new Dynamic Host Configuration Protocol + (DHCP) option which is passed from the DHCP Server to the DHCP Client + to specify the domain search list used when resolving hostnames using + DNS. + +Table of Contents + + 1. Introduction ................................................ 2 + 1.1 Terminology ............................................ 2 + 1.2 Requirements Language .................................. 2 + 2. Domain Search Option Format ................................. 2 + 3. Example ..................................................... 3 + 4. Security Considerations ..................................... 4 + 5. Normative References ........................................ 5 + 6. Informative References ...................................... 5 + 7. IANA Considerations ......................................... 6 + 8. Acknowledgments ............................................. 6 + 9. Intellectual Property Statement ............................. 6 + 10. Authors' Addresses .......................................... 7 + 11. Full Copyright Statement .................................... 8 + + + + + + + + +Aboba & Cheshire Standards Track [Page 1] + +RFC 3397 DHCP Domain Search Option November 2002 + + +1. Introduction + + The Dynamic Host Configuration Protocol (DHCP) [RFC2131] provides a + mechanism for host configuration. [RFC2132] and [RFC2937] allow DHCP + servers to pass name service configuration information to DHCP + clients. In some circumstances, it is useful for the DHCP client to + be configured with the domain search list. This document defines a + new DHCP option which is passed from the DHCP Server to the DHCP + Client to specify the domain search list used when resolving + hostnames with DNS. This option applies only to DNS and does not + apply to other name resolution mechanisms. + +1.1. Terminology + + This document uses the following terms: + + DHCP client + A DHCP client or "client" is an Internet host using DHCP to + obtain configuration parameters such as a network address. + + DHCP server + A DHCP server or "server" is an Internet host that returns + configuration parameters to DHCP clients. + +1.2. Requirements Language + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in "Key words for use in + RFCs to Indicate Requirement Levels" [RFC2119]. + +2. Domain Search Option Format + + The code for this option is 119. + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | 119 | Len | Searchstring... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Searchstring... + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + In the above diagram, Searchstring is a string specifying the + searchlist. If the length of the searchlist exceeds the maximum + permissible within a single option (255 octets), then multiple + options MAY be used, as described in "Encoding Long Options in the + Dynamic Host Configuration Protocol (DHCPv4)" [RFC3396]. + + + +Aboba & Cheshire Standards Track [Page 2] + +RFC 3397 DHCP Domain Search Option November 2002 + + + To enable the searchlist to be encoded compactly, searchstrings in + the searchlist MUST be concatenated and encoded using the technique + described in section 4.1.4 of "Domain Names - Implementation And + Specification" [RFC1035]. In this scheme, an entire domain name or a + list of labels at the end of a domain name is replaced with a pointer + to a prior occurrence of the same name. Despite its complexity, this + technique is valuable since the space available for encoding DHCP + options is limited, and it is likely that a domain searchstring will + contain repeated instances of the same domain name. Thus the DNS + name compression is both useful and likely to be effective. + + For use in this specification, the pointer refers to the offset + within the data portion of the DHCP option (not including the + preceding DHCP option code byte or DHCP option length byte). + + If multiple Domain Search Options are present, then the data portions + of all the Domain Search Options are concatenated together as + specified in "Encoding Long DHCP Options in the Dynamic Host + Configuration Protocol (DHCPv4)" [RFC3396] and the pointer indicates + an offset within the complete aggregate block of data. + +3. Example + + Below is an example encoding of a search list consisting of + "eng.apple.com." and "marketing.apple.com.": + + +---+---+---+---+---+---+---+---+---+---+---+ + |119| 9 | 3 |'e'|'n'|'g'| 5 |'a'|'p'|'p'|'l'| + +---+---+---+---+---+---+---+---+---+---+---+ + + +---+---+---+---+---+---+---+---+---+---+---+ + |119| 9 |'e'| 3 |'c'|'o'|'m'| 0 | 9 |'m'|'a'| + +---+---+---+---+---+---+---+---+---+---+---+ + + +---+---+---+---+---+---+---+---+---+---+---+ + |119| 9 |'r'|'k'|'e'|'t'|'i'|'n'|'g'|xC0|x04| + +---+---+---+---+---+---+---+---+---+---+---+ + + Note: + + i. The encoding has been split (for this example) into three + Domain Search Options. All Domain Search Options are logically + concatenated into one block of data before being interpreted by + the client. + + ii. The encoding of "eng.apple.com." ends with a zero, the null + root label, to mark the end of the name, as required by RFC + 1035. + + + +Aboba & Cheshire Standards Track [Page 3] + +RFC 3397 DHCP Domain Search Option November 2002 + + + iii. The encoding of "marketing" (for "marketing.apple.com.") ends + with the two-octet compression pointer C004 (hex), which points + to offset 4 in the complete aggregated block of Domain Search + Option data, where another validly encoded domain name can be + found to complete the name ("apple.com."). + + Every search domain name must end either with a zero or with a two- + octet compression pointer. If the receiver is part-way through + decoding a search domain name when it reaches the end of the complete + aggregated block of the searchlist option data, without finding a + zero or a valid two-octet compression pointer, then the partially + read name MUST be discarded as invalid. + +4. Security Considerations + + Potential attacks on DHCP are discussed in section 7 of the DHCP + protocol specification [RFC2131], as well as in the DHCP + authentication specification [RFC3118]. In particular, using the + domain search option, a rogue DHCP server might be able to redirect + traffic to another site. + + For example, a user requesting a connection to "myhost", expecting to + reach "myhost.bigco.com" might instead be directed to + "myhost.roguedomain.com". Note that support for DNSSEC [RFC2535] + will not avert this attack, since the resource records for + "myhost.roguedomain.com" might be legitimately signed. This makes + the domain search option a more fruitful avenue of attack for a rogue + DHCP server than providing an illegitimate DNS server option + (described in [RFC2132]). + + The degree to which a host is vulnerable to attack via an invalid + domain search option is determined in part by DNS resolver behavior. + [RFC1535] discusses security weaknesses related to implicit as well + as explicit domain searchlists, and provides recommendations relating + to resolver searchlist processing. [RFC1536] section 6 also + addresses this vulnerability, and recommends that resolvers: + + [1] Use searchlists only when explicitly specified; no implicit + searchlists should be used. + + [2] Resolve a name that contains any dots by first trying it as an + FQDN and if that fails, with the local domain name (or + searchlist if specified) appended. + + [3] Resolve a name containing no dots by appending with the + searchlist right away, but once again, no implicit searchlists + should be used. + + + + +Aboba & Cheshire Standards Track [Page 4] + +RFC 3397 DHCP Domain Search Option November 2002 + + + In order to minimize potential vulnerabilities it is recommended + that: + + [a] Hosts implementing the domain search option SHOULD also + implement the searchlist recommendations of [RFC1536], section + 6. + + [b] Where DNS parameters such as the domain searchlist or DNS + servers have been manually configured, these parameters SHOULD + NOT be overridden by DHCP. + + [c] Domain search option implementations MAY require DHCP + authentication [RFC3118] prior to accepting a domain search + option. + +5. Normative References + + [RFC1035] Mockapetris, P., "Domain Names - Implementation and + Specification", STD 13, RFC 1035, November 1987. + + [RFC1536] Kumar, A., Postel, J., Neuman, C., Danzig, P. and S. + Miller, "Common DNS Implementation Errors and Suggested + Fixes", RFC 1536, October 1993. + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", RFC + 2131, March 1997. + + [RFC3118] Droms, R. and W. Arbaugh, "Authentication for DHCP + Messages", RFC 3118, June 2001. + + [RFC3396] Lemon, T. and S. Cheshire, "Encoding Long Options in the + Dynamic Host Configuration Protocol (DHCPv4)", RFC 3396, + November 2002. + +6. Informative References + + [RFC1535] Gavron, E., "A Security Problem and Proposed Correction + With Widely Deployed DNS Software", RFC 1535, October + 1993. + + [RFC2132] Alexander, S. and R. Droms, "DHCP Options and BOOTP + Vendor Extensions", RFC 2132, March 1997. + + + + + + +Aboba & Cheshire Standards Track [Page 5] + +RFC 3397 DHCP Domain Search Option November 2002 + + + [RFC2535] Eastlake, D., "Domain Name System Security Extensions", + RFC 2535, March 1999. + + [RFC2937] Smith, C., "The Name Service Search Option for DHCP", RFC + 2937, September 2000. + +7. IANA Considerations + + The IANA has assigned DHCP option code 119 to the Domain Search + Option. + +8. Acknowledgments + + The authors would like to thank Michael Patton, Erik Guttman, Olafur + Gudmundsson, Thomas Narten, Mark Andrews, Erik Nordmark, Myron + Hattig, Keith Moore, and Bill Manning for comments on this memo. + +9. Intellectual Property Statement + + The IETF takes no position regarding the validity or scope of any + intellectual property or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; neither does it represent that it + has made any effort to identify any such rights. Information on the + IETF's procedures with respect to rights in standards-track and + standards-related documentation can be found in BCP-11. Copies of + claims of rights made available for publication and any assurances of + licenses to be made available, or the result of an attempt made to + obtain a general license or permission for the use of such + proprietary rights by implementors or users of this specification can + be obtained from the IETF Secretariat. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights which may cover technology that may be required to practice + this standard. Please address the information to the IETF Executive + Director. + + + + + + + + + + + + + +Aboba & Cheshire Standards Track [Page 6] + +RFC 3397 DHCP Domain Search Option November 2002 + + +10. Authors' Addresses + + Bernard Aboba + Microsoft Corporation + One Microsoft Way + Redmond, WA 98052 + + Phone: +1 425 706 6605 + EMail: bernarda@microsoft.com + + + Stuart Cheshire + Apple Computer, Inc. + 1 Infinite Loop + Cupertino + California 95014 + USA + + Phone: +1 408 974 3207 + EMail: rfc@stuartcheshire.org + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Aboba & Cheshire Standards Track [Page 7] + +RFC 3397 DHCP Domain Search Option November 2002 + + +11. Full Copyright Statement + + Copyright (C) The Internet Society (2002). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Aboba & Cheshire Standards Track [Page 8] + diff --git a/docs/rfc3442.txt b/docs/rfc3442.txt new file mode 100644 index 0000000..5dc778c --- /dev/null +++ b/docs/rfc3442.txt @@ -0,0 +1,507 @@ + + + + + + +Network Working Group T. Lemon +Request for Comments: 3442 Nominum, Inc. +Updates: 2132 S. Cheshire +Category: Standards Track Apple Computer, Inc. + B. Volz + Ericsson + December 2002 + + + The Classless Static Route Option for + Dynamic Host Configuration Protocol (DHCP) version 4 + +Status of this Memo + + 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. + +Copyright Notice + + Copyright (C) The Internet Society (2002). All Rights Reserved. + +Abstract + + This document defines a new Dynamic Host Configuration Protocol + (DHCP) option which is passed from the DHCP Server to the DHCP Client + to configure a list of static routes in the client. The network + destinations in these routes are classless - each routing table entry + includes a subnet mask. + +Introduction + + This option obsoletes the Static Route option (option 33) defined in + RFC 2132 [4]. + + The IP protocol [1] uses routers to transmit packets from hosts + connected to one IP subnet to hosts connected to a different IP + subnet. When an IP host (the source host) wishes to transmit a + packet to another IP host (the destination), it consults its routing + table to determine the IP address of the router that should be used + to forward the packet to the destination host. + + The routing table on an IP host can be maintained in a variety of + ways - using a routing information protocol such as RIP [8], ICMP + router discovery [6,9] or using the DHCP Router option, defined in + RFC 2132 [4]. + + + +Lemon, et. al. Standards Track [Page 1] + +RFC 3442 Classless Static Route Option for DHCPv4 December 2002 + + + In a network that already provides DHCP service, using DHCP to update + the routing table on a DHCP client has several virtues. It is + efficient, since it makes use of messages that would have been sent + anyway. It is convenient - the DHCP server configuration is already + being maintained, so maintaining routing information, at least on a + relatively stable network, requires little extra work. If DHCP + service is already in use, no additional infrastructure need be + deployed. + + The DHCP protocol as defined in RFC 2131 [3] and the options defined + in RFC 2132 [4] only provide a mechanism for installing a default + route or installing a table of classful routes. Classful routes are + routes whose subnet mask is implicit in the subnet number - see + section 3.2 of STD 5, RFC 791 [1] for details on classful routing. + + Classful routing is no longer in common use, so the DHCP Static Route + option is no longer useful. Currently, classless routing [7, 10] is + the most commonly-deployed form of routing on the Internet. In + classless routing, IP addresses consist of a network number (the + combination of the network number and subnet number described in RFC + 950 [7]) and a host number. + + In classful IP, the network number and host number are derived from + the IP address using a bitmask whose value is determined by the first + few bits of the IP address. In classless IP, the network number and + host number are derived from the IP address using a separate + quantity, the subnet mask. In order to determine the network to + which a given route applies, an IP host must know both the network + number AND the subnet mask for that network. + + The Static Routes option (option 33) does not provide a subnet mask + for each route - it is assumed that the subnet mask is implicit in + whatever network number is specified in each route entry. The + Classless Static Routes option does provide a subnet mask for each + entry, so that the subnet mask can be other than what would be + determined using the algorithm specified in STD 5, RFC 791 [1] and + STD 5, RFC 950 [7]. + +Definitions + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" and "OPTIONAL" in this + document are to be interpreted as described in BCP 14, RFC 2119 [2]. + + + + + + + + +Lemon, et. al. Standards Track [Page 2] + +RFC 3442 Classless Static Route Option for DHCPv4 December 2002 + + + This document also uses the following terms: + + "DHCP client" + + DHCP client or "client" is an Internet host using DHCP to + obtain configuration parameters such as a network address. + + "DHCP server" + + A DHCP server or "server" is an Internet host that returns + configuration parameters to DHCP clients. + + "link" + + Any set of network attachment points that will all receive a + link-layer broadcast sent on any one of the attachment points. + This term is used in DHCP because in some cases more than one + IP subnet may be configured on a link. DHCP uses a local- + network (all-ones) broadcast, which is not subnet-specific, and + will therefore reach all nodes connected to the link, + regardless of the IP subnet or subnets on which they are + configured. + + A "link" is sometimes referred to as a broadcast domain or + physical network segment. + +Classless Route Option Format + + The code for this option is 121, and its minimum length is 5 bytes. + This option can contain one or more static routes, each of which + consists of a destination descriptor and the IP address of the router + that should be used to reach that destination. + + Code Len Destination 1 Router 1 + +-----+---+----+-----+----+----+----+----+----+ + | 121 | n | d1 | ... | dN | r1 | r2 | r3 | r4 | + +-----+---+----+-----+----+----+----+----+----+ + + Destination 2 Router 2 + +----+-----+----+----+----+----+----+ + | d1 | ... | dN | r1 | r2 | r3 | r4 | + +----+-----+----+----+----+----+----+ + + In the above example, two static routes are specified. + + + + + + + +Lemon, et. al. Standards Track [Page 3] + +RFC 3442 Classless Static Route Option for DHCPv4 December 2002 + + + Destination descriptors describe the IP subnet number and subnet mask + of a particular destination using a compact encoding. This encoding + consists of one octet describing the width of the subnet mask, + followed by all the significant octets of the subnet number. + + The width of the subnet mask describes the number of one bits in the + mask, so for example a subnet with a subnet number of 10.0.127.0 and + a netmask of 255.255.255.0 would have a subnet mask width of 24. + + The significant portion of the subnet number is simply all of the + octets of the subnet number where the corresponding octet in the + subnet mask is non-zero. The number of significant octets is the + width of the subnet mask divided by eight, rounding up, as shown in + the following table: + + Width of subnet mask Number of significant octets + 0 0 + 1- 8 1 + 9-16 2 + 17-24 3 + 25-32 4 + + The following table contains some examples of how various subnet + number/mask combinations can be encoded: + + Subnet number Subnet mask Destination descriptor + 0 0 0 + 10.0.0.0 255.0.0.0 8.10 + 10.0.0.0 255.255.255.0 24.10.0.0 + 10.17.0.0 255.255.0.0 16.10.17 + 10.27.129.0 255.255.255.0 24.10.27.129 + 10.229.0.128 255.255.255.128 25.10.229.0.128 + 10.198.122.47 255.255.255.255 32.10.198.122.47 + +Local Subnet Routes + + In some cases more than one IP subnet may be configured on a link. + In such cases, a host whose IP address is in one IP subnet in the + link could communicate directly with a host whose IP address is in a + different IP subnet on the same link. In cases where a client is + being assigned an IP address on an IP subnet on such a link, for each + IP subnet in the link other than the IP subnet on which the client + has been assigned the DHCP server MAY be configured to specify a + router IP address of 0.0.0.0. + + + + + + + +Lemon, et. al. Standards Track [Page 4] + +RFC 3442 Classless Static Route Option for DHCPv4 December 2002 + + + For example, consider the case where there are three IP subnets + configured on a link: 10.0.0/24, 192.168.0/24, 10.0.21/24. If the + client is assigned an IP address of 10.0.21.17, then the server could + include a route with a destination of 10.0.0/24 and a router address + of 0.0.0.0, and also a route with a destination of 192.168.0/24 and a + router address of 0.0.0.0. + + A DHCP client whose underlying TCP/IP stack does not provide this + capability MUST ignore routes in the Classless Static Routes option + whose router IP address is 0.0.0.0. Please note that the behavior + described here only applies to the Classless Static Routes option, + not to the Static Routes option nor the Router option. + +DHCP Client Behavior + + DHCP clients that do not support this option MUST ignore it if it is + received from a DHCP server. DHCP clients that support this option + MUST install the routes specified in the option, except as specified + in the Local Subnet Routes section. DHCP clients that support this + option MUST NOT install the routes specified in the Static Routes + option (option code 33) if both a Static Routes option and the + Classless Static Routes option are provided. + + DHCP clients that support this option and that send a DHCP Parameter + Request List option MUST request both this option and the Router + option [4] in the DHCP Parameter Request List. + + DHCP clients that support this option and send a parameter request + list MAY also request the Static Routes option, for compatibility + with older servers that don't support Classless Static Routes. The + Classless Static Routes option code MUST appear in the parameter + request list prior to both the Router option code and the Static + Routes option code, if present. + + If the DHCP server returns both a Classless Static Routes option and + a Router option, the DHCP client MUST ignore the Router option. + + Similarly, if the DHCP server returns both a Classless Static Routes + option and a Static Routes option, the DHCP client MUST ignore the + Static Routes option. + + After deriving a subnet number and subnet mask from each destination + descriptor, the DHCP client MUST zero any bits in the subnet number + where the corresponding bit in the mask is zero. In other words, the + subnet number installed in the routing table is the logical AND of + the subnet number and subnet mask given in the Classless Static + Routes option. For example, if the server sends a route with a + destination of 129.210.177.132 (hexadecimal 81D4B184) and a subnet + + + +Lemon, et. al. Standards Track [Page 5] + +RFC 3442 Classless Static Route Option for DHCPv4 December 2002 + + + mask of 255.255.255.128 (hexadecimal FFFFFF80), the client will + install a route with a destination of 129.210.177.128 (hexadecimal + 81D4B180). + +Requirements to Avoid Sizing Constraints + + Because a full routing table can be quite large, the standard 576 + octet maximum size for a DHCP message may be too short to contain + some legitimate Classless Static Route options. Because of this, + clients implementing the Classless Static Route option SHOULD send a + Maximum DHCP Message Size [4] option if the DHCP client's TCP/IP + stack is capable of receiving larger IP datagrams. In this case, the + client SHOULD set the value of this option to at least the MTU of the + interface that the client is configuring. The client MAY set the + value of this option higher, up to the size of the largest UDP packet + it is prepared to accept. (Note that the value specified in the + Maximum DHCP Message Size option is the total maximum packet size, + including IP and UDP headers.) + + DHCP clients requesting this option, and DHCP servers sending this + option, MUST implement DHCP option concatenation [5]. In the + terminology of RFC 3396 [5], the Classless Static Route Option is a + concatenation-requiring option. + +DHCP Server Administrator Responsibilities + + Many clients may not implement the Classless Static Routes option. + DHCP server administrators should therefore configure their DHCP + servers to send both a Router option and a Classless Static Routes + option, and should specify the default router(s) both in the Router + option and in the Classless Static Routes option. + + When a DHCP client requests the Classless Static Routes option and + also requests either or both of the Router option and the Static + Routes option, and the DHCP server is sending Classless Static Routes + options to that client, the server SHOULD NOT include the Router or + Static Routes options. + +Security Considerations + + Potential exposures to attack in the DHCP protocol are discussed in + section 7 of the DHCP protocol specification [3] and in + Authentication for DHCP Messages [11]. + + The Classless Static Routes option can be used to misdirect network + traffic by providing incorrect IP addresses for routers. This can be + either a Denial of Service attack, where the router IP address given + is simply invalid, or can be used to set up a man-in-the-middle + + + +Lemon, et. al. Standards Track [Page 6] + +RFC 3442 Classless Static Route Option for DHCPv4 December 2002 + + + attack by providing the IP address of a potential snooper. This is + not a new problem - the existing Router and Static Routes options + defined in RFC 2132 [4] exhibit the same vulnerability. + +IANA Considerations + + This DHCP option has been allocated the option code 121 in the list + of DHCP option codes that the IANA maintains. + +Normative References + + [1] Postel, J., "Internet Protocol", STD 5, RFC 791, September 1981. + + [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement + Levels", BCP 14, RFC 2119, March 1997. + + [3] Droms, R., "Dynamic Host Configuration Protocol", RFC 2131, + March 1997. + + [4] Alexander, S. and R. Droms, "DHCP Options and BOOTP Vendor + Extensions", RFC 2132, March 1997. + + [5] Lemon, T. and S. Cheshire, "Encoding Long Options in the Dynamic + Host Configuration Protocol (DHCPv4)", RFC 3396, November 2002. + +Informative References + + [6] Postel, J., "Internet Control Message Protocol", STD 5, RFC 792, + September 1981. + + [7] Mogul, J. and J. Postel, "Internet Standard Subnetting + Procedure", STD 5, RFC 950, August 1985. + + [8] Hedrick, C., "Routing Information Protocol", RFC 1058, June + 1988. + + [9] Deering, S., "ICMP Router Discovery Messages", RFC 1256, + September 1991. + + [10] Pummill, T. and B. Manning, "Variable Length Subnet Table For + IPv4", RFC 1878, December 1995. + + [11] Droms, R. and W. Arbaugh, "Authentication for DHCP Messages", + RFC 3118, June 2001. + + + + + + + +Lemon, et. al. Standards Track [Page 7] + +RFC 3442 Classless Static Route Option for DHCPv4 December 2002 + + +Intellectual Property Statement + + The IETF takes no position regarding the validity or scope of any + intellectual property or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; neither does it represent that it + has made any effort to identify any such rights. Information on the + IETF's procedures with respect to rights in standards-track and + standards-related documentation can be found in BCP-11. Copies of + claims of rights made available for publication and any assurances of + licenses to be made available, or the result of an attempt made to + obtain a general license or permission for the use of such + proprietary rights by implementors or users of this specification can + be obtained from the IETF Secretariat. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights which may cover technology that may be required to practice + this standard. Please address the information to the IETF Executive + Director. + +Authors' Addresses + + Ted Lemon + Nominum, Inc. + 2385 Bay Road + Redwood City, CA 94063 + + EMail: Ted.Lemon@nominum.com + + Stuart Cheshire + Apple Computer, Inc. + 1 Infinite Loop + Cupertino + California 95014 + USA + + Phone: +1 408 974 3207 + EMail: rfc@stuartcheshire.org + + Bernie Volz + Ericsson + 959 Concord Street + Framingham, MA, 01701 + + Phone: +1 508 875 3162 + EMail: bernie.volz@ericsson.com + + + +Lemon, et. al. Standards Track [Page 8] + +RFC 3442 Classless Static Route Option for DHCPv4 December 2002 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2002). All Rights Reserved. + + This document and translations of it may be copied and furnished to + others, and derivative works that comment on or otherwise explain it + or assist in its implementation may be prepared, copied, published + and distributed, in whole or in part, without restriction of any + kind, provided that the above copyright notice and this paragraph are + included on all such copies and derivative works. However, this + document itself may not be modified in any way, such as by removing + the copyright notice or references to the Internet Society or other + Internet organizations, except as needed for the purpose of + developing Internet standards in which case the procedures for + copyrights defined in the Internet Standards process must be + followed, or as required to translate it into languages other than + English. + + The limited permissions granted above are perpetual and will not be + revoked by the Internet Society or its successors or assigns. + + This document and the information contained herein is provided on an + "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING + TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING + BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION + HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF + MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + + + + + + + + + + + + + +Lemon, et. al. Standards Track [Page 9] + diff --git a/docs/rfc3942.txt b/docs/rfc3942.txt new file mode 100644 index 0000000..0676a49 --- /dev/null +++ b/docs/rfc3942.txt @@ -0,0 +1,395 @@ + + + + + + +Network Working Group B. Volz +Request for Comments: 3942 Cisco Systems, Inc. +Updates: 2132 November 2004 +Category: Standards Track + + + Reclassifying Dynamic Host Configuration Protocol + version 4 (DHCPv4) Options + +Status of this Memo + + 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. + +Copyright Notice + + Copyright (C) The Internet Society (2004). + +Abstract + + This document updates RFC 2132 to reclassify Dynamic Host + Configuration Protocol version 4 (DHCPv4) option codes 128 to 223 + (decimal) as publicly defined options to be managed by IANA in + accordance with RFC 2939. This document directs IANA to make these + option codes available for assignment as publicly defined DHCP + options for future options. + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 2 + 2. Requirements Notation . . . . . . . . . . . . . . . . . . . . 2 + 3. Background . . . . . . . . . . . . . . . . . . . . . . . . . . 2 + 3.1. Publicly Defined Options Range . . . . . . . . . . . . . 2 + 3.2. Site-Specific Options Range . . . . . . . . . . . . . . 3 + 4. Reclassifying Options . . . . . . . . . . . . . . . . . . . . 3 + 5. Security Considerations . . . . . . . . . . . . . . . . . . . 4 + 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 + 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 5 + 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 5 + 8.1. Normative References . . . . . . . . . . . . . . . . . . 5 + 8.2. Informative References . . . . . . . . . . . . . . . . . 6 + Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 6 + Full Copyright Statement . . . . . . . . . . . . . . . . . . . . . 7 + + + + + +Volz Standards Track [Page 1] + +RFC 3942 Reclassifying DHCPv4 Options November 2004 + + +1. Introduction + + The DHCPv4 [RFC2131] publicly defined options range, options 1 - 127, + is nearly used up. Efforts such as [RFC3679] help extend the life of + this space, but ultimately the space will be exhausted. + + This document reclassifies much of the site-specific option range, + which has not been widely used for its original intended purpose, to + extend the publicly defined options space. + +2. Requirements Notation + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + +3. Background + + The DHCP option space (0 - 255) is divided into two ranges [RFC2132]: + + 1. 1 - 127 are publicly defined options, now allocated in accordance + with [RFC2939]. + + 2. 128 - 254 are site-specific options. + + Options 0 (pad) and 255 (end) are special and defined in [RFC2131]. + +3.1. Publicly Defined Options Range + + The publicly defined options space (1 - 127) is nearly exhausted. + Recent work [RFC3679] will buy more time, as several allocated but + unused option codes have been reclaimed. A review could be made from + time to time to determine whether there are other option codes that + can be reclaimed. + + A longer-term solution to the eventual exhaustion of the publicly + defined options space is desired. The DHC WG evaluated several + solutions: + + 1. Using options 126 and 127 to carry 16-bit options as originally + proposed by Ralph Droms in late 1996. However, this significantly + penalizes the first option assigned to this new space, as it + requires implementing the 16-bit option support. Because of this, + options 126 and 127 have been reclaimed [RFC3679]. + + 2. Using a new magic cookie and 16-bit option code format. However, + this proposal + + + + +Volz Standards Track [Page 2] + +RFC 3942 Reclassifying DHCPv4 Options November 2004 + + + * penalizes the first option assigned to this new space, as it + requires significant changes to clients, servers, and relay + agents, + + * could adversely impact existing clients, servers, and relay + agents that fail to properly check the magic cookie value, + + * requires support of both message formats for the foreseeable + future, and + + * requires clients to send multiple DHCPDISCOVER messages -- one + for each magic cookie. + + 3. Reclassifying a portion of the site-specific option codes as + publicly defined. The impact is minimal, as only those sites + presently using options in the reclassified range need to renumber + their options. + +3.2. Site-Specific Options Range + + The site-specific option range is rather large (127 options in all) + and little used. The original intent of the site-specific option + range was to support local (to a site) configuration options, and it + is difficult to believe a site would need 127 options for this + purpose. Further, many DHCP client implementations do not provide a + well documented means to request site-specific options from a server + or to allow applications to extract the returned option values. + + Some vendors have made use of site-specific option codes that violate + the intent of the site-specific options, as the options are used to + configure features of their products and thus are specific to many + sites. This usage could potentially cause problems if a site that + has been using the same site-specific option codes for other purposes + deploys products from one of the vendors, or if two vendors pick the + same site-specific options. + +4. Reclassifying Options + + The site-specific option codes 128 to 223 are hereby reclassified as + publicly defined options. This leaves 31 site-specific options, 224 + to 254. + + To allow vendors that have made use of site-specific options within + the reclassified range to publish their option usage and to request + an official assignment of the option number to that usage, the + following procedure will be used to reclassify these options: + + + + + +Volz Standards Track [Page 3] + +RFC 3942 Reclassifying DHCPv4 Options November 2004 + + + 1. The reclassified options (128 to 223) will be placed in the + "Unavailable" state by IANA. These options are not yet available + for assignment to publicly defined options. + + 2. Vendors that currently use one or more of the reclassified options + have 6 months following this RFC's publication date to notify the + DHC WG and IANA that they are using particular options numbers and + agree to document that usage in an RFC. IANA will move these + options from the "Unavailable" to "Tentatively Assigned" state. + + Vendors have 18 months from this RFC's publication date to start + the documentation process by submitting an Internet-Draft. + + NOTE: If multiple vendors of an option number come forward and can + demonstrate that their usage is in reasonably wide use, none of + the vendors will be allowed to keep the current option number, and + they MUST go through the normal process of getting a publicly + assigned option [RFC2939]. + + 3. Any options still classified as "Unavailable" 6 months after the + RFC publication date will be moved to the "Unassigned" state by + IANA. These options may then be assigned to any new publicly + defined options in accordance with [RFC2939]. + + 4. For those options in the "Tentatively Assigned" state, vendors + have 18 months following this RFC's publication date to submit an + Internet-Draft documenting the option. The documented usage MUST + be consistent with the existing usage. When the option usage is + published as an RFC, IANA will move the option to the "Assigned" + state. + + If no Internet-Draft is published within the 18 months or should + one of these Internet-Drafts expire after the 18 months, IANA will + move the option to the "Unassigned" state, and the option may then + be assigned to any new publicly defined options in accordance with + [RFC2939]. + + Sites presently using site-specific option codes within the + reclassified range SHOULD take steps to renumber these options to + values within the remaining range. If a site needs more than 31 + site-specific options, the site must switch to using suboptions, as + has been done for other options, such as the Relay Agent Information + Option [RFC3046]. + +5. Security Considerations + + This document in and by itself provides no security, nor does it + impact existing DCHP security as described in [RFC2131]. + + + +Volz Standards Track [Page 4] + +RFC 3942 Reclassifying DHCPv4 Options November 2004 + + +6. IANA Considerations + + IANA is requested to + + 1. expand the publicly defined DHCPv4 options space from 1 - 127 to 1 + - 223. The new options (128 - 223) are to be listed as + "Unavailable" and MUST NOT be assigned to any publicly defined + options. + + 2. receive notices from vendors that have been using one or more of + the options in the 128-223 range that they are using the option + and are willing to document that usage. IANA will list these + options as "Tentatively Assigned". + + 3. change the listing of any options listed as "Unavailable" to + "Available" 6 months from this RFC's publication date. These + options may now be assigned in accordance with [RFC2939]. + + 4. change the listing of any options listed as "Tentatively-Assigned" + to "Unavailable" 18 months from this RFC's publication date and + periodically thereafter as long as there is an option listed as + "Tentatively-Assigned", if no un-expired Internet-Draft exists + documenting the usage. + +7. Acknowledgements + + Many thanks to Ralph Droms and Ted Lemon for their valuable input and + earlier work on the various alternatives. + +8. References + +8.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", RFC + 2131, March 1997. + + [RFC2132] Alexander, S. and R. Droms, "DHCP Options and BOOTP Vendor + Extensions", RFC 2132, March 1997. + + [RFC2939] Droms, R., "Procedures and IANA Guidelines for Definition + of New DHCP Options and Message Types", BCP 43, RFC 2939, + September 2000. + + + + + + +Volz Standards Track [Page 5] + +RFC 3942 Reclassifying DHCPv4 Options November 2004 + + +8.2. Informative References + + [RFC3046] Patrick, M., "DHCP Relay Agent Information Option", RFC + 3046, January 2001. + + [RFC3679] Droms, R., "Unused Dynamic Host Configuration Protocol + (DHCP) Option Codes", RFC 3679, January 2004. + +Author's Address + + Bernard Volz + Cisco Systems, Inc. + 1414 Massachusetts Ave. + Boxborough, MA 01719 + USA + + Phone: +1 978 936 0382 + EMail: volz@cisco.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Volz Standards Track [Page 6] + +RFC 3942 Reclassifying DHCPv4 Options November 2004 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2004). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the IETF's procedures with respect to rights in IETF Documents can + be found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at ietf- + ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is currently provided by the + Internet Society. + + + + + + + +Volz Standards Track [Page 7] + diff --git a/docs/rfc4388.txt b/docs/rfc4388.txt new file mode 100644 index 0000000..9dd005d --- /dev/null +++ b/docs/rfc4388.txt @@ -0,0 +1,1515 @@ + + + + + + +Network Working Group R. Woundy +Request for Comments: 4388 Comcast Cable +Category: Standards Track K. Kinnear + Cisco Systems + February 2006 + + + Dynamic Host Configuration Protocol (DHCP) Leasequery + +Status of This Memo + + 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. + +Copyright Notice + + Copyright (C) The Internet Society (2006). + +Abstract + + A Dynamic Host Configuration Protocol version 4 (DHCPv4) server is + the authoritative source of IP addresses that it has provided to + DHCPv4 clients. Other processes and devices that already make use of + DHCPv4 may need to access this information. The leasequery protocol + provides these processes and devices a lightweight way to access IP + address information. + + + + + + + + + + + + + + + + + + + + + + +Woundy & Kinnear Standards Track [Page 1] + +RFC 4388 DHCP Leasequery February 2006 + + +Table of Contents + + 1. Introduction ....................................................2 + 2. Terminology .....................................................5 + 3. Background ......................................................7 + 4. Design Goals ....................................................7 + 4.1. Broadcast ARP Is Undesirable ...............................7 + 4.2. SNMP and LDAP Are Not Appropriate ..........................8 + 4.3. DHCP Relay Agent Functionality Is Common ...................8 + 4.4. DHCP Servers Are a Reliable Source of Location + Information ................................................9 + 4.5. Minimal Additional Configuration Is Required ...............9 + 5. Protocol Overview ...............................................9 + 6. Protocol Details ...............................................12 + 6.1. Definitions Required for DHCPLEASEQUERY Processing ........12 + 6.2. Sending the DHCPLEASEQUERY Message ........................14 + 6.3. Receiving the DHCPLEASEQUERY Message ......................15 + 6.4. Responding to the DHCPLEASEQUERY Message ..................16 + 6.5. Receiving a DHCPLEASEUNASSIGNED, DHCPLEASEACTIVE, or + DHCPLEASEUNKNOWN Message ..................................20 + 6.6. Receiving No Response to the DHCPLEASEQUERY Message .......21 + 6.7. Lease Binding Data Storage Requirements ...................22 + 6.8. Using the DHCPLEASEQUERY Message with Multiple + DHCP Servers ..............................................23 + 7. Security Considerations ........................................23 + 8. IANA Considerations ............................................24 + 9. Acknowledgements ...............................................24 + 10. References ....................................................25 + 10.1. Normative References .....................................25 + 10.2. Informative References ...................................25 + +1. Introduction + + A DHCPv4 server contains considerable authoritative information + concerning the IP addresses it has leased to DHCP clients. Sometimes + devices or other processes may need access to this information. In + some cases, these devices or processes already have the capability to + send and receive DHCP packets, and so the leasequery protocol is + designed to give these processes and devices a low-overhead way to + access such information. + + For example, access concentrators that act as DHCP relay agents + sometimes derive information important to their operation by + extracting data out of the DHCP packets they forward, a process known + as "gleaning". Unfortunately, the typical access concentrator loses + its gleaned information when the access concentrator is rebooted or + is replaced. This memo proposes that when gleaned DHCP information + is not available, the access concentrator/relay agent can obtain the + + + +Woundy & Kinnear Standards Track [Page 2] + +RFC 4388 DHCP Leasequery February 2006 + + + location information directly from the DHCP server(s) using the + DHCPLEASEQUERY message. + + To continue this example in more depth, in many broadband access + networks, the access concentrator needs to associate an IP address + lease to the correct endpoint location, which includes knowledge of + the host hardware address, the port or virtual circuit that leads to + the host, and/or the hardware address of the intervening subscriber + modem. This is particularly important when one or more IP subnets + are shared among many ports, circuits, and modems. Representative + cable and DSL environments are depicted in Figures 1 and 2 below. + + +--------+ +---------------+ + | DHCP | | DOCSIS CMTS | + | Server |-...-| or DVB INA |------------------- + +--------+ | (Relay Agent) | | | + +---------------+ +------+ +------+ + |Modem1| |Modem2| + +------+ +------+ + | | | + +-----+ +-----+ +-----+ + |Host1| |Host2| |Host3| + +-----+ +-----+ +-----+ + + Figure 1: Cable Environment for DHCPLEASEQUERY + + +--------+ +---------------+ + | DHCP | | DSL Access | +-------+ + | Server |-...-| Concentrator |-...-| DSLAM | + +--------+ | (Relay Agent) | +-------+ + +---------------+ | | + +------+ +------+ + |Modem1| |Modem2| + +------+ +------+ + | | | + +-----+ +-----+ +-----+ + |Host1| |Host2| |Host3| + +-----+ +-----+ +-----+ + + Figure 2: DSL Environment for DHCPLEASEQUERY + + Knowledge of this location information can benefit the access + concentrator in several ways: + + 1. The access concentrator can forward traffic to the access + network using the correct access network port, down the + correct virtual circuit, through the correct modem, to the + correct hardware address. + + + +Woundy & Kinnear Standards Track [Page 3] + +RFC 4388 DHCP Leasequery February 2006 + + + 2. The access concentrator can perform IP source address + verification of datagrams received from the access network. + The verification may be based on the datagram source hardware + address, the incoming access network port, the incoming + virtual circuit, and/or the transmitting modem. + + 3. The access concentrator can encrypt datagrams that can only be + decrypted by the correct modem, using mechanisms such as [BPI] + or [BPI+]. + + The access concentrator in this example obtains the location + information primarily from "gleaning" information from DHCP server + responses sent through the relay agent. When location information is + not available from "gleaning", e.g., because the access concentrator + has rebooted, the access concentrator can query the DHCP server(s) + for location information using the DHCPLEASEQUERY message defined in + this document. + + The DHCPLEASEQUERY message is a new DHCP message type transmitted + from a DHCP relay agent to a DHCP server. A DHCPLEASEQUERY-aware + relay agent sends the DHCPLEASEQUERY message when it needs to know + the location of an IP endpoint. The DHCPLEASEQUERY-aware DHCP server + replies with a DHCPLEASEUNASSIGNED, DHCPLEASEACTIVE, or + DHCPLEASEUNKNOWN message. The DHCPLEASEACTIVE response to a + DHCPLEASEQUERY message allows the relay agent to determine the IP + endpoint location and the remaining duration of the IP address lease. + The DHCPLEASEUNASSIGNED is similar to a DHCPLEASEACTIVE message, but + indicates that there is no currently active lease on the resultant IP + address but that this DHCP server is authoritative for this IP + address. The DHCPLEASEUNKNOWN message indicates that the DHCP server + has no knowledge of the information specified in the query (e.g., IP + address, MAC address, or Client-identifier option). + + The DHCPLEASEQUERY message does not presuppose a particular use for + the information it returns -- it is simply designed to return + information for which the DHCP server is an authoritative source to a + client that requests that information. It is designed to make it + straightforward for processes and devices that already interpret DHCP + packets to access information from the DHCP server. + + This document specifies an extension specifically to the DHCPv4 + protocol [RFC2131]. Given the nature of the DHCPv6 protocol + [RFC3315], there is no effective way to make the DHCPLEASEQUERY + message interaction common between DHCPv4 and DHCPv6 even should the + desire to do so exist. + + + + + + +Woundy & Kinnear Standards Track [Page 4] + +RFC 4388 DHCP Leasequery February 2006 + + + The DHCPLEASEQUERY message was the result of a set of specific real- + world implementation needs that appeared many years after the DHCPv4 + protocol was in wide use. Furthermore, at the time of this writing, + the DHCPv6 protocol has yet to be widely deployed. The needs of + access concentrators in yet to be determined DHCPv6 deployment + scenarios are difficult to estimate. If a DHCPLEASEQUERY-like + function is necessary in DHCPv6, many of the ideas of this document + will probably be applicable, while others may not. We have been + cautioned against designing protocol capabilities for which there is + only an imagined consumer, and that is all that exists today in the + realm of DHCPLEASEQUERY for DHCPv6. + + Thus, this document applies only to DHCPv4, and for clarity we have + not appended DHCPv4 to every appearance of several common terms. In + this document, all references to IP addresses should be taken to mean + IPv4 addresses, and all references to DHCP servers and DHCP clients + should be taken to mean DHCPv4 servers and DHCPv4 clients. + +2. Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in RFC 2119 [RFC2119]. + + This document uses the following terms: + + o "access concentrator" + + An access concentrator is a router or switch at the broadband + access provider's edge of a public broadband access network. + This document assumes that the access concentrator includes + the DHCP relay agent functionality. + + o "DHCP client" + + A DHCP client is an Internet host using DHCP to obtain + configuration parameters such as a network address. + + o "DHCP relay agent" + + A DHCP relay agent is a third-party agent that transfers + Bootstrap Protocol (BOOTP) and DHCP messages between clients + and servers residing on different subnets, per [RFC951] and + [RFC1542]. + + + + + + + +Woundy & Kinnear Standards Track [Page 5] + +RFC 4388 DHCP Leasequery February 2006 + + + o "DHCP server" + + A DHCP server is an Internet host that returns configuration + parameters to DHCP clients. + + o "downstream" + + Downstream is the direction from the access concentrator + towards the broadband subscriber. + + o "gleaning" + + Gleaning is the extraction of location information from DHCP + messages, as the messages are forwarded by the DHCP relay + agent function. + + o "location information" + + Location information is information needed by the access + concentrator to forward traffic to a broadband-accessible + host. This information includes knowledge of the host + hardware address, the port or virtual circuit that leads to + the host, and/or the hardware address of the intervening + subscriber modem. + + o "MAC address" + + In the context of a DHCP packet, a MAC address consists of the + following fields: hardware type "htype", hardware length + "hlen", and client hardware address "chaddr". + + o "stable storage" + + Every DHCP server is assumed to have some form of what is + called "stable storage". Stable storage is used to hold + information concerning IP address bindings (among other + things) so that this information is not lost in the event of a + server failure that requires restart of the server. + + o "upstream" + + Upstream is the direction from the broadband subscriber + towards the access concentrator. + + + + + + + + +Woundy & Kinnear Standards Track [Page 6] + +RFC 4388 DHCP Leasequery February 2006 + + +3. Background + + The focus of this document is to enable processes and devices that + wish to access information from the DHCP server in a lightweight and + convenient manner. It is especially appropriate for processes and + devices that already interpret DHCP packets. + + One important motivating example is that the DHCPLEASEQUERY message + allows access concentrators to send DHCPLEASEQUERY messages to DHCP + servers to obtain location information of broadband access network + devices. + + This document assumes that many access concentrators have an embedded + DHCP relay agent functionality. Typical access concentrators include + DOCSIS Cable Modem Termination Systems (CMTSs) [DOCSIS], DVB + Interactive Network Adapters (INAs) [EUROMODEM], and DSL Access + Concentrators. + + The DHCPLEASEQUERY message is an extension to the DHCP protocol + [RFC2131]. + + The DHCPLEASEQUERY message is a query message only and does not + affect the state of the IP address or the binding information + associated with it. + +4. Design Goals + + The goal of this document is to provide a lightweight mechanism for + processes or devices to access information contained in the DHCP + server. It is designed to allow processes and devices that already + process and interpret DHCP messages to access this information in a + rapid and lightweight manner. + + Some of this information might be acquired in a different way, and + the following sections discuss some of these alternative approaches. + +4.1. Broadcast ARP Is Undesirable + + The access concentrator can transmit a broadcast Address Resolution + Protocol (ARP) Request [RFC826], and observe the origin and contents + of the ARP Reply, to reconstruct the location information. + + The ARP mechanism is undesirable for three reasons: + + 1. the burden on the access concentrator to transmit over + multiple access ports and virtual circuits (assuming that IP + subnets span multiple ports or virtual circuits), + + + + +Woundy & Kinnear Standards Track [Page 7] + +RFC 4388 DHCP Leasequery February 2006 + + + 2. the burden on the numerous subscriber hosts to receive and + process the broadcast, and + + 3. the ease by which a malicious host can misrepresent itself as + the IP endpoint. + +4.2. SNMP and LDAP Are Not Appropriate + + Access concentrator implementations typically do not have Simple + Network Management Protocol (SNMP) management client interfaces nor + Lightweight Directory Access Protocol (LDAP) client interfaces + (although they typically do include SNMP management agents). This is + one reason why this document does not leverage the proposed DHCP + Server MIB [DHCPMIB]. + + The DHCP Server MIB effort [DHCPMIB] grew out of traffic engineering + and troubleshooting activities at large DHCP installations, and is + primarily intended as a method of gathering performance statistics + about servers the load presented to them. + + Despite the presence in the proposed DHCPv4 server MIB of objects + that report configuration and status information, the MIB is intended + to provide more generic, server-wide aggregated or summarized data. + DHCPLEASEQUERY is intended to provide detailed, specific information + about individual leases at a level that would be difficult or + impossible to shoehorn into a MIB. + + From an implementation standpoint, the DHCPLEASEQUERY message is not + required to be supported by all DHCPv4 servers. Since it appears + that defining optional MIB objects and objects for optional features + in a MIB is discouraged, trying to support DHCPLEASEQUERY + functionality optionally through a MIB would be similarly discouraged + from an SNMP MIB standpoint. + +4.3. DHCP Relay Agent Functionality Is Common + + Access concentrators commonly act as DHCP relay agents. Furthermore, + many access concentrators already glean location information from + DHCP server responses, as part of the relay agent function. + + The gleaning mechanism as a technique to determine the IP addresses + valid for a particular downstream link is preferred over other + mechanisms (ARP, SNMP, LDAP) because of the lack of additional + network traffic, but sometimes gleaning information can be + incomplete. The access concentrator usually cannot glean information + from any DHCP unicast (i.e., non-relayed) messages due to performance + reasons. Furthermore, the DHCP-gleaned location information often + + + + +Woundy & Kinnear Standards Track [Page 8] + +RFC 4388 DHCP Leasequery February 2006 + + + does not persist across access concentrator reboots (due to lack of + stable storage), and almost never persists across concentrator + replacements. + +4.4. DHCP Servers Are a Reliable Source of Location Information + + DHCP servers are the most reliable source of location information for + access concentrators, particularly when the location information is + dynamic and not reproducible by algorithmic means (e.g., when a + single IP subnet extends behind many broadband modems). DHCP servers + participate in all IP lease transactions (and therefore in all + location information updates) with DHCP clients, whereas access + concentrators sometimes miss some important lease transactions. + + An access concentrator can be configured with the IP addresses of + multiple different DHCP servers, so that no one DHCP server is a + single point of failure. + +4.5. Minimal Additional Configuration Is Required + + Access concentrators can usually query the same set of DHCP servers + used for forwarding by the relay agent, thus minimizing configuration + requirements. + +5. Protocol Overview + + In the following discussion of the DHCPLEASEQUERY message, the client + of the message is assumed to be an access concentrator. Note that + access concentrators are not the only allowed (or required) consumers + of the information provided by the DHCPLEASEQUERY message, but they + do give readers a concrete feel for how the message might be used. + + The access concentrator initiates all DHCPLEASEQUERY message + conversations. This document assumes that the access concentrator + gleans location information in its DHCP relay agent function. + However, the location information is usually unavailable after the + reboot or replacement of the access concentrator. + + Suppose the access concentrator is a router, and further suppose that + the router receives an IP datagram to forward downstream to the + public broadband access network. If the location information for the + downstream next hop is missing, the access concentrator sends one or + more DHCPLEASEQUERY message(s), each containing the IP address of the + downstream next hop in the "ciaddr" field. + + This query will then be answered by returning the information current + when this client's lease was last granted or renewed, allowing the + access concentrator to forward the IP datagram. + + + +Woundy & Kinnear Standards Track [Page 9] + +RFC 4388 DHCP Leasequery February 2006 + + + An alternative approach is to send in a DHCPLEASEQUERY message with + the "ciaddr" field empty and the MAC address (i.e., "htype", "hlen", + and "chaddr" fields) with a valid MAC address or a Client-identifier + option (option 61) appearing in the options area. In this case, the + DHCP server must return an IP address in the ciaddr if it has any + record of the client described by the Client-identifier or MAC + address. In the absence of specific configuration information to the + contrary (see Section 6.4), it SHOULD be the IP address with the + latest client-last-transaction-time associated with the client + described by the MAC address or Client-identifier option. + + The DHCP servers that implement this protocol always send a response + to the DHCPLEASEQUERY message: either a DHCPLEASEUNASSIGNED, + DHCPLEASEACTIVE, or DHCPLEASEUNKNOWN. The reasons why a + DHCPLEASEUNASSIGNED, DHCPLEASEACTIVE, or DHCPLEASEUNKNOWN message + might be generated are explained in the specific query regimes, + below. + + Servers that do not implement the DHCPLEASEQUERY message SHOULD + simply not respond. + + The DHCPLEASEQUERY message can support three query regimes: A server + that implements the DHCPLEASEQUERY message must implement all three + query regimes. + + o Query by IP address: + + For this query, the requester supplies only an IP address in the + DHCPLEASEQUERY message. The DHCP server will return any + information that it has on the most recent client to have been + assigned that IP address. + + The DHCP server replies with a DHCPLEASEUNASSIGNED or + DHCPLEASEACTIVE message if the IP address in the DHCPLEASEQUERY + message corresponds to an IP address about which the server has + definitive information (i.e., it is authorized to lease this IP + address). The server replies with a DHCPLEASEUNKNOWN message if + the server does not have definitive information concerning the + address in the DHCPLEASEQUERY message. + + o Query by MAC address: + + For this query, the requester supplies only a MAC address in the + DHCPLEASEQUERY message. The DHCP server will return any + information that it has on the IP address most recently accessed + by a client with that MAC address. In addition, it may supply + additional IP addresses that have been associated with that MAC + address in different subnets. Information about these bindings + + + +Woundy & Kinnear Standards Track [Page 10] + +RFC 4388 DHCP Leasequery February 2006 + + + can then be found using the Query by IP Address, described + above. + + The DHCP server replies with a DHCPLEASEACTIVE message if the + MAC address in the DHCPLEASEQUERY message corresponds to a MAC + address with an active lease on an IP address in this server. + The server replies with a DHCPLEASEUNKNOWN message if the server + does not presently have an active lease by a client with this + MAC address in this DHCP server. + + o Query by Client-identifier option: + + For this query, the requester supplies only a Client-identifier + option in the DHCPLEASEQUERY message. The DHCP server will + return any information that it has on the IP address most + recently accessed by a client with that Client-identifier. In + addition, it may supply additional IP addresses that have been + associated with Client-identifier in different subnets. + Information about these bindings can then be found using the + Query by IP Address, described above. + + The DHCP server replies with a DHCPLEASEACTIVE message if the + Client-identifier in the DHCPLEASEQUERY message currently has an + active lease on an IP address in this DHCP server. The server + replies with a DHCPLEASEUNKNOWN message if the server does not + have an active lease by a client with this Client-identifier. + + For many DHCP servers, the query by IP address is likely to be the + most efficient form of leasequery. This is the form of + DHCPLEASEQUERY that SHOULD be used if possible. + + The DHCPLEASEUNASSIGNED or DHCPLEASEACTIVE message reply must always + contain the IP address in the "ciaddr" field. The DHCPLEASEACTIVE + message SHOULD contain the physical address of the IP address lease + owner in the "htype", "hlen", and "chaddr" fields. The Parameter + Request List (option 55) can be used to request specific options to + be returned about the IP address in the ciaddr. The reply often + contains the time until expiration of the lease, and the original + contents of the Relay Agent Information option [RFC3046]. The access + concentrator uses the "chaddr" field and Relay Agent Information + option to construct location information, which can be cached on the + access concentrator until lease expiration. + + Any DHCP server that supports the DHCPLEASEQUERY message SHOULD save + the information from the most recent Relay Agent Information option + (option 82) [RFC3046] associated with every IP address that it + serves. It is assumed that most clients that generate the + DHCPLEASEQUERY message will ask for the Relay Agent Information + + + +Woundy & Kinnear Standards Track [Page 11] + +RFC 4388 DHCP Leasequery February 2006 + + + option (option 82) in the Parameter Request List (option 55), and so + supporting the DHCPLEASEQUERY message without having the Relay Agent + Information option around to return to the client is likely to be + less than helpful. + + A server that implements DHCPLEASEQUERY SHOULD also save the + information on the most recent Vendor class identifier, option 60, + associated with each IP address, since this option is also likely to + be requested by clients sending the DHCPLEASEQUERY message. + +6. Protocol Details + +6.1. Definitions Required for DHCPLEASEQUERY Processing + + The operation of the DHCPLEASEQUERY message requires the definition + of the following new and extended values for the DHCP packet beyond + those defined by [RFC2131] and [RFC2132]. See also Section 8, IANA + Considerations. + + 1. The message type option (option 53) from [RFC2132] requires + four new values: one for the DHCPLEASEQUERY message itself and + one for each of its three possible responses + DHCPLEASEUNASSIGNED, DHCPLEASEACTIVE, DHCPLEASEUNKNOWN. The + values of these message types are shown below in an extension + of the table from section 9.6 of [RFC2132]: + + Value Message Type + ----- ------------ + 10 DHCPLEASEQUERY + 11 DHCPLEASEUNASSIGNED + 12 DHCPLEASEUNKNOWN + 13 DHCPLEASEACTIVE + + 2. There is a new option, the client-last-transaction-time: + + client-last-transaction-time + + This option allows the receiver to determine the time of the + most recent access of the client. It is particularly useful + when DHCPLEASEACTIVE messages from two different DHCP servers + need to be compared, although it can be useful in other + situations. The value is a duration in seconds from the + current time into the past when this IP address was most + recently the subject of communication between the client and + the DHCP server. + + + + + + +Woundy & Kinnear Standards Track [Page 12] + +RFC 4388 DHCP Leasequery February 2006 + + + This MUST NOT be an absolute time. This MUST NOT be an + absolute number of seconds since Jan. 1, 1970. Instead, this + MUST be an integer number of seconds in the past from the time + the DHCPLEASEACTIVE message is sent that the client last dealt + with this server about this IP address. In the same way that + the IP Address Lease Time option (option 51) encodes a lease + time that is a number of seconds into the future from the time + the message was sent, this option encodes a value that is a + number of seconds into the past from when the message was + sent. + + The code for the this option is 91. The length of the this + option is 4 octets. + + Code Len Seconds in the past + +-----+-----+-----+-----+-----+-----+ + | 91 | 4 | t1 | t2 | t3 | t4 | + +-----+-----+-----+-----+-----+-----+ + + 3. There in a second new option, the associated-ip option: + + associated-ip + + This option is used to return all of the IP addresses + associated with the DHCP client specified in a particular + DHCPLEASEQUERY message. + + The code for this option is 92. The minimum length for this + option is 4 octets, and the length MUST always be a multiple + of 4. + + Code Len Address 1 Address 2 + +-----+-----+-----+-----+-----+-----+-----+-----+-- + | 92 | n | a1 | a2 | a3 | a4 | a1 | a2 | ... + +-----+-----+-----+-----+-----+-----+-----+-----+-- + + + + + + + + + + + + + + + + +Woundy & Kinnear Standards Track [Page 13] + +RFC 4388 DHCP Leasequery February 2006 + + +6.2. Sending the DHCPLEASEQUERY Message + + The DHCPLEASEQUERY message is typically sent by an access + concentrator. The DHCPLEASEQUERY message uses the DHCP message + format as described in [RFC2131], and uses message number 10 in the + DHCP Message Type option (option 53). The DHCPLEASEQUERY message has + the following pertinent message contents: + + o The giaddr MUST be set to the IP address of the requester (i.e., + the access concentrator). The giaddr is independent of the + "ciaddr" field to be searched -- it is simply the return address + of the DHCPLEASEUNASSIGNED, DHCPLEASEACTIVE, or DHCPLEASEUNKNOWN + message from the DHCP server. + + Note that this use of the giaddr is consistent with the + definition of giaddr in [RFC2131], where the giaddr is always + used as the return address of the DHCP response message. In some + (but not all) contexts in RFC 2131, the giaddr is used as the + "key" to access the appropriate address pool. The DHCPLEASEQUERY + message is one of those cases where the giaddr MUST NOT be used + as such a "key". + + o The Parameter Request List option (option 55) SHOULD be set to + the options of interest to the requester. The interesting + options are likely to include the IP Address Lease Time option + (option 51), the Relay Agent Information option (option 82), and + possibly the Vendor class identifier option (option 60). In the + absence of a Parameter Request List option, the server SHOULD + return the same options it would return for a DHCPREQUEST message + that didn't contain a DHCPLEASEQUERY message, which includes + those mandated by Section 4.3.1 of [RFC2131] as well as any + options that the server was configured to always return to a + client. + + Additional details concerning different query types are: + + o Query by IP address: + + The values of htype, hlen, and chaddr MUST be set to zero. + + The "ciaddr" field MUST be set to the IP address of the lease to + be queried. + + The Client-identifier option (option 61) MUST NOT appear in the + packet. + + + + + + +Woundy & Kinnear Standards Track [Page 14] + +RFC 4388 DHCP Leasequery February 2006 + + + o Query by MAC address: + + The values of htype, hlen, and chaddr MUST be set to the value + of the MAC address to search for. + + The "ciaddr" field MUST be set to zero. + + The Client-identifier option (option 61) MUST NOT appear in the + packet. + + o Query by Client-identifier option: + + There MUST be a Client-identifier option (option 61) in the + DHCPLEASEQUERY message. + + The "ciaddr" field MUST be set to zero. + + The values of htype, hlen, and chaddr MUST be set to zero. + + The DHCPLEASEQUERY message SHOULD be sent to a DHCP server which is + known to possess authoritative information concerning the IP address. + The DHCPLEASEQUERY message MAY be sent to more than one DHCP server, + and in the absence of information concerning which DHCP server might + possess authoritative information concerning the IP address, it + SHOULD be sent to all DHCP servers configured for the associated + relay agent (if any are known). + + Any device expecting to use a DHCPLEASEQUERY message SHOULD ensure + that the Relay Agent Info option that it uses contains information + that unambiguously identifies the device. + +6.3. Receiving the DHCPLEASEQUERY Message + + A server that implements the DHCPLEASEQUERY message MUST implement + all three query regimes: query by IP address, query by MAC address, + and query by Client-identifier. + + A DHCPLEASEQUERY message MUST have a non-zero giaddr. The + DHCPLEASEQUERY message MUST have exactly one of the following: a + non-zero ciaddr, a non-zero htype/hlen/chaddr, or a Client-identifier + option. + + The DHCP server that receives a DHCPLEASEQUERY message MUST base its + response on the particular data item used in the query. + + + + + + + +Woundy & Kinnear Standards Track [Page 15] + +RFC 4388 DHCP Leasequery February 2006 + + + The giaddr is used only for the destination address of any generated + response and, while required, is not otherwise used in generating the + response to the DHCPLEASEQUERY message. It MUST NOT be used to + restrict the processing of the query in any way, and MUST NOT be used + locate a subnet to which the ciaddr (if any) must belong. + + Note that this use of the giaddr is consistent with the definition of + giaddr in [RFC2131], where the giaddr is always used as the return + address of the DHCP response message. In some (but not all) contexts + in RFC 2131, the giaddr is used as the "key" to access the + appropriate address pool. The DHCPLEASEQUERY message is one of those + cases where the giaddr MUST NOT be used as such a "key". + +6.4. Responding to the DHCPLEASEQUERY Message + + There are three possible responses to a DHCPLEASEQUERY message: + + o DHCPLEASEUNASSIGNED + + The server MUST respond with a DHCPLEASEUNASSIGNED message if + this server has information about the IP address, but there is + no active lease for the IP address. The DHCPLEASEUNASSIGNED + message is only returned for a query by IP address, and + indicates that the server manages this IP address, but there is + no currently active lease on this IP address. + + o DHCPLEASEUNKNOWN + + The DHCPLEASEUNKNOWN message indicates that the server does not + manage the IP address or the client specified in the + DHCPLEASEQUERY message does not currently have a lease on an IP + address. + + When responding with a DHCPLEASEUNKNOWN, the DHCP server MUST + NOT include other DHCP options in the response. + + o DHCPLEASEACTIVE + + The DHCPLEASEACTIVE message indicates that the server not only + knows about the IP address and client specified in the + DHCPLEASEACTIVE message, but also knows that there is an active + lease by that client for that IP address. + + The server MUST respond with a DHCPLEASEACTIVE message when the + IP address returned in the "ciaddr" field is currently leased. + + + + + + +Woundy & Kinnear Standards Track [Page 16] + +RFC 4388 DHCP Leasequery February 2006 + + +6.4.1. Determining the IP address about Which to Respond + + Since the response to a DHCPLEASEQUERY request can only contain full + information about one IP address -- the one that appears in the + "ciaddr" field -- determination of which IP address about which to + respond is a key issue. Of course, the values of additional IP + addresses for which a client has a lease must also be returned in the + associated-ip option (Section 6.1, #3). This is the only information + returned not directly associated with the IP address in the "ciaddr" + field. + + In the event that an IP address appears in the "ciaddr" field of a + DHCPLEASEQUERY message, if that IP address is one managed by the DHCP + server, then that IP address MUST be set in the "ciaddr" field of a + DHCPLEASEUNASSIGNED message. + + If the IP address is not managed by the DHCP server, then a + DHCPLEASEUNKNOWN message must be returned. + + If the "ciaddr" field of the DHCPLEASEQUERY is zero, then the + DHCPLEASEQUERY message is a query by Client-identifier or MAC + address. In this case, the client's identity is any client that has + proffered an identical Client-identifier option (if the Client- + identifier option appears in the DHCPLEASEQUERY message), or an + identical MAC address (if the MAC address fields in the + DHCPLEASEQUERY message are non-zero). This client matching approach + will, for the purposes of this section, be described as "Client- + identifier or MAC address". + + If the "ciaddr" field is zero in a DHCPLEASEQUERY message, then the + IP address placed in the "ciaddr" field of a DHCPLEASEACTIVE message + MUST be that of an IP address for which the client that most recently + used the IP address matches the Client-identifier or MAC address + specified in the DHCPLEASEQUERY message. + + If there is only a single IP address that fulfills this criteria, + then it MUST be placed in the "ciaddr" field of the DHCPLEASEACTIVE + message. + + In the case where more than one IP address has been accessed by the + client specified by the MAC address or Client-identifier option, then + the DHCP server MUST return the IP address returned to the client in + the most recent transaction with the client unless the DHCP server + has been configured by the server administrator to use some other + preference mechanism. + + + + + + +Woundy & Kinnear Standards Track [Page 17] + +RFC 4388 DHCP Leasequery February 2006 + + + If, after all of the above processing, no value is set in the + "ciaddr" field of the DHCPLEASEUNASSIGNED or DHCPLEASEACTIVE message, + then a DHCPLEASEUNKNOWN message MUST be returned instead. + +6.4.2. Building a DHCPLEASEUNASSIGNED or DHCPLEASEACTIVE Message Once + the "ciaddr" Field Is Set + + Once the "ciaddr" field of the DHCPLEASEUNASSIGNED is set, the + processing for a DHCPLEASEUNASSIGNED message is complete. No other + options are returned for the DHCPLEASEUNASSIGNED message. + + For the DHCPLEASEACTIVE message, the rest of the processing largely + involves returning information about the IP address specified in the + "ciaddr" field. + + The IP address in the "ciaddr" field of the DHCPLEASEUNASSIGNED or + DHCPLEASEACTIVE message MUST be one for which this server is + responsible (or a DHCPLEASEUNKNOWN message would be have already been + returned early in the processing described in the previous section). + + The MAC address of the DHCPLEASEACTIVE message MUST be set to the + values that identify the client associated with the IP address in the + "ciaddr" field of the DHCPLEASEUNASSIGNED message. + + If the Client-identifier option (option 61) is specified in the + Parameter Request List option (option 55), then the Client-identifier + (if any) of the client associated with the IP address in the "ciaddr" + field SHOULD be returned in the DHCPLEASEACTIVE message. + + In the case where more than one IP address has been involved in a + DHCP message exchange with the client specified by the MAC address + and/or Client-identifier option, then the list of all of the IP + addresses MUST be returned in the associated-ip option, whether or + not that option was requested as part of the Parameter Request List + option. + + If the IP Address Lease Time option (option 51) is specified in the + Parameter Request List and if there is a currently valid lease for + the IP address specified in the ciaddr, then the DHCP server MUST + return this option in the DHCPLEASEACTIVE message with its value + equal to the time remaining until lease expiration. If there is no + valid lease for the IP address, then the server MUST NOT return the + IP Address Lease Time option (option 51). + + A request for the Renewal (T1) Time Value option or the Rebinding + (T2) Time Value option in the Parameter Request List of the + DHCPLEASEQUERY message MUST be handled like the IP Address Lease Time + option is handled. If there is a valid lease and these times are not + + + +Woundy & Kinnear Standards Track [Page 18] + +RFC 4388 DHCP Leasequery February 2006 + + + yet in the past, then the DHCP server SHOULD return these options + (when requested) with the remaining time until renewal or rebinding, + respectively. If these times are already in the past, or if there is + not currently a valid lease for this IP address, the DHCP server MUST + NOT return these options. + + If the Relay Agent Information (option 82) is specified in the + Parameter Request List, then the information contained in the most + recent Relay Agent Information option received from the relay agent + associated with this IP address MUST be included in the + DHCPLEASEACTIVE message. + + The DHCPLEASEACTIVE message SHOULD include the values of all other + options not specifically discussed above that were requested in the + Parameter Request List of the DHCPLEASEQUERY message and that are + acceptable to return based on the list of "non-sensitive options", + discussed below. + + DHCP servers SHOULD be configurable with a list of "non-sensitive + options" that can be returned to the client when specified in the + Parameter Request List of the DHCPLEASEQUERY message. Any option not + on this list SHOULD NOT be returned to a client, even if requested by + that client. + + The DHCP server uses information from its lease binding database to + supply the DHCPLEASEACTIVE option values. The values of the options + that were returned to the DHCP client would generally be preferred, + but in the absence of those, options that were sent in DHCP client + requests would be acceptable. + + In some cases, the Relay Agent Information option in an incoming + DHCPREQUEST packet is used to help determine the options returned to + the DHCP client that sent the DHCPREQUEST. When responding to a + DHCPLEASEQUERY message, the DHCP server MUST use the saved Relay + Agent Information option just like it did when responding to the DHCP + client in order to determine the values of any options requested by + the DHCPLEASEQUERY message. The goal is to return the same option + values to the DHCPLEASEQUERY as those that were returned to the + DHCPDISCOVER or DHCPREQUEST from the DHCP client (unless otherwise + specified, above). + + In the event that two servers are cooperating to provide a high- + availability DHCP server, as supported by [RFC2131], they would have + to communicate some information about IP address bindings to each + other. In order to properly support the DHCPLEASEQUERY message, + these servers MUST ensure that they communicate the Relay Agent + Information option information to each other in addition to any other + IP address binding information. + + + +Woundy & Kinnear Standards Track [Page 19] + +RFC 4388 DHCP Leasequery February 2006 + + +6.4.3. Sending a DHCPLEASEUNASSIGNED, DHCPLEASEACTIVE, or + DHCPLEASEUNKNOWN Message + + The server expects a giaddr in the DHCPLEASEQUERY message, and + unicasts the DHCPLEASEUNASSIGNED, DHCPLEASEACTIVE, or + DHCPLEASEUNKNOWN message to the giaddr. If the "giaddr" field is + zero, then the DHCP server MUST NOT reply to the DHCPLEASEQUERY + message. + +6.5. Receiving a DHCPLEASEUNASSIGNED, DHCPLEASEACTIVE, or + DHCPLEASEUNKNOWN Message + + When a DHCPLEASEACTIVE message is received in response to the + DHCPLEASEQUERY message, it means that there is a currently active + lease for this IP address in this DHCP server. The access + concentrator SHOULD use the information in the "htype", "hlen", and + "chaddr" fields of the DHCPLEASEACTIVE as well as any Relay Agent + Information option information included in the packet to refresh its + location information for this IP address. + + When a DHCPLEASEUNASSIGNED message is received in response to the + DHCPLEASEQUERY message, that means that there is no currently active + lease for the IP address present in the DHCP server, but that this + server does in fact manage that IP address. In this case, the access + concentrator SHOULD cache this information in order to prevent + unacceptable loads on the access concentrator and the DHCP server in + the face of a malicious or seriously compromised device downstream of + the access concentrator. This caching could be as simple as simply + setting a bit saying that a response was received from a server that + knew about this IP address but that there was no current lease. This + would, of course, need to be cleared when the access concentrator + next "gleaned" that a lease for this IP address came into existence. + + In either case, when a DHCPLEASEUNASSIGNED or DHCPLEASEACTIVE message + is received in response to a DHCPLEASEQUERY message, it means that + the DHCP server that responded is a DHCP server that manages the IP + address present in the ciaddr, and the Relay Agent SHOULD cache this + information for later use. + + When a DHCPLEASEUNKNOWN message is received by an access concentrator + that has sent out a DHCPLEASEQUERY message, it means that the DHCP + server contacted supports the DHCPLEASEQUERY message but that the + DHCP server does not have definitive information concerning the IP + address contained in the "ciaddr" field of the DHCPLEASEQUERY + message. If there is no IP address in the "ciaddr" field of the + DHCPLEASEQUERY message, then a DHCPLEASEUNKNOWN message means that + + + + + +Woundy & Kinnear Standards Track [Page 20] + +RFC 4388 DHCP Leasequery February 2006 + + + the DHCP server does not have definitive information concerning the + DHCP client specified in the "hlen", "htype", and "chaddr" fields or + the Client-identifier option of the DHCPLEASEQUERY message. + + The access concentrator SHOULD cache this information, but only for a + relatively short lifetime, approximately 5 minutes. + + Having cached this information, the access concentrator SHOULD only + infrequently direct a DHCPLEASEQUERY message to a DHCP server that + responded to a DHCPLEASEQUERY message for a particular "ciaddr" field + with a DHCPLEASEUNKNOWN. + +6.6. Receiving No Response to the DHCPLEASEQUERY Message + + When an access concentrator receives no response to a DHCPLEASEQUERY + message, there are several possible reasons: + + o The DHCPLEASEQUERY or a corresponding DHCPLEASEUNASSIGNED, + DHCPLEASEACTIVE, or DHCPLEASEUNKNOWN was lost during transmission + or the DHCPLEASEQUERY arrived at the DHCP server but it was + dropped because the server was too busy. + + o The DHCP server doesn't support DHCPLEASEQUERY. + + In the first of the cases above, a retransmission of the + DHCPLEASEQUERY would be appropriate, but in the second of the two + cases, a retransmission would not be appropriate. There is no way to + tell these two cases apart (other than, perhaps, because of a DHCP + server's response to other DHCPLEASEQUERY messages indicating that it + does or does not support the DHCPLEASEQUERY message). + + An access concentrator that utilizes the DHCPLEASEQUERY message + SHOULD attempt to resend DHCPLEASEQUERY messages to servers that do + not respond to them using a backoff algorithm for the retry time that + approximates an exponential backoff. The access concentrator SHOULD + adjust the backoff approach such that DHCPLEASEQUERY messages do not + arrive at a server that is not otherwise known to support the + DHCPLEASEQUERY message at a rate of more than approximately one + packet every 10 seconds, and yet (if the access concentrator needs to + send DHCPLEASEQUERY messages) not less than one DHCPLEASEQUERY per 70 + seconds. + + In practice, this approach would probably best be handled by a per- + server timer that is restarted whenever a response to a + DHCPLEASEQUERY message is received, and expires after one minute. + The per-server timer would start off expired, and in the expired + state only one DHCPLEASEQUERY message would be queued for the + associated server. + + + +Woundy & Kinnear Standards Track [Page 21] + +RFC 4388 DHCP Leasequery February 2006 + + + All DHCPLEASEQUERY messages SHOULD use the exponential backoff + algorithm specified in Section 4.1 of [RFC2131]. + + Thus, in the initial state, the per-server timer is expired, and a + single DHCPLEASEQUERY message is queued for each server. After the + first response to a DHCPLEASEQUERY message, the per-server timer is + started. At that time, multiple DHCPLEASEQUERY messages can be sent + in parallel to the DHCP server, though the total number SHOULD be + limited to 100 or 200, to avoid swamping the DHCP server. Each of + these messages uses the [RFC2131] exponential backoff algorithm. + Every time a response to any of these messages is received, the per- + server timer is reset and starts counting again up to one minute. In + the event the per-server timer goes off, then all outstanding + messages SHOULD be dropped except for a single DHCPLEASEQUERY message + that is used to poll the server at approximately 64-second intervals + until such time as another (or the first) response to the + DHCPLEASEQUERY is received. + + In the event that there is no DHCPLEASEQUERY traffic for one minute, + then the per-server timer will expire. After that time, there will + only be one DHCPLEASEQUERY message allowed to be outstanding to that + server until a response to that message is received. + +6.7. Lease Binding Data Storage Requirements + + DHCP server implementations that implement the DHCPLEASEQUERY + capability MUST save the most recent Relay Agent Information option + from the most recent DHCPREQUEST packet for two reasons. First, it + is almost certain to be requested by in the dhcp-parameter-request- + list option in any DHCPLEASEQUERY request. Second, the saved Relay + Agent Information option may be necessary to determine the value of + other options given to the DHCP client, if these are requested by the + dhcp-parameter-request list in the DHCPLEASEQUERY request. + + This is a list of the information that is required to successfully + implement + + o relay-agent-info option from client packet: MUST store with + binding. + + o client-last-transaction-time of last client interaction: MUST + store with binding. + + o vendor-class-id: SHOULD store with binding. + + These data storage requirements are minimally larger than those + required for normal operation of the DHCP protocol, as required to + properly implement [RFC2131]. + + + +Woundy & Kinnear Standards Track [Page 22] + +RFC 4388 DHCP Leasequery February 2006 + + +6.8. Using the DHCPLEASEQUERY Message with Multiple DHCP Servers + + When using the DHCPLEASEQUERY message in an environment where + multiple DHCP servers may contain authoritative information about the + same IP address (such as when two DHCP servers are cooperating to + provide a high-availability DHCP service), multiple, possibly + conflicting, responses might be received. + + In this case, some information in the response packet SHOULD be used + to decide among the various responses. The client-last-transaction- + time (if it is available) can be used to decide which server has more + recent information concerning the IP address returned in the "ciaddr" + field. + +7. Security Considerations + + Access concentrators that use DHCP gleaning, refreshed with + DHCPLEASEQUERY messages, will maintain accurate location information. + Location information accuracy ensures that the access concentrator + can forward data traffic to the intended location in the broadband + access network, can perform IP source address verification of + datagrams from the access network, and can encrypt traffic that can + only be decrypted by the intended access modem (e.g., [BPI] and + [BPI+]). As a result, the access concentrator does not need to + depend on ARP broadcasts across the access network, which is + susceptible to malicious hosts that masquerade as the intended IP + endpoints. Thus, the DHCPLEASEQUERY message allows an access + concentrator to provide considerably enhanced security. + + DHCP servers SHOULD prevent exposure of location information + (particularly the mapping of hardware address to IP address lease, + which can be an invasion of broadband subscriber privacy) by + employing the techniques detailed in [RFC3118], "Authentication for + DHCP Messages". + + This RFC describes how a DHCP client interacts with a DHCP server. + Access concentrators that send the DHCPLEASEQUERY message are + essentially DHCP clients for the purposes of the DHCPLEASEQUERY + message, even though they perform the functions of a DHCP relay agent + as well. Thus, [RFC3118] is an appropriate mechanism for + DHCPLEASEQUERY messages. + + Since [RFC3118] discusses the normal DHCP client interaction, + consisting of a DHCPDISCOVER, DHCPOFFER, DHCPREQUEST, and DHCPACK, it + is necessary to transpose the operations described in [RFC3118] to + the DHCPLEASEQUERY domain. The operations described in [RFC3118] for + + + + + +Woundy & Kinnear Standards Track [Page 23] + +RFC 4388 DHCP Leasequery February 2006 + + + DHCPDISCOVER are performed for DHCPLEASEQUERY, and the operations + described for DHCPOFFER are performed for DHCPLEASEUNASSIGNED, + DHCPLEASEACTIVE, and DHCPLEASEUNKNOWN messages. + + Access concentrators SHOULD minimize potential denial of service + attacks on the DHCP servers by minimizing the generation of + DHCPLEASEQUERY messages. In particular, the access concentrator + SHOULD employ negative caching (i.e., cache DHCPLEASEUNASSIGNED, + DHCPLEASEACTIVE, and DHCPLEASEUNKNOWN responses to DHCPLEASEQUERY + messages) and ciaddr restriction (i.e., don't send a DHCPLEASEQUERY + message with a ciaddr outside of the range of the attached broadband + access networks). Together, these mechanisms limit the access + concentrator to transmitting one DHCPLEASEQUERY message (excluding + message retries) per legitimate broadband access network IP address + after a reboot event. + + DHCP servers supporting the DHCPLEASEQUERY message SHOULD ensure that + they cannot be successfully attacked by being flooded with large + quantities of DHCPLEASEQUERY messages in a short time. + + In some environments, it may be appropriate to configure a DHCP + server with the IP addresses of the relay agents for which it may + respond to DHCPLEASEQUERY messages, thereby allowing it to respond + only to requests from only a handful of relay agents. This does not + provide any true security, but may be useful to thwart + unsophisticated attacks of various sorts. + +8. IANA Considerations + + IANA has assigned six values for this document. See Section 6.1 for + details. There are four new messages types, which are the value of + the message type option (option 53) from [RFC2132]. The value for + DHCPLEASEQUERY is 10, the value for DHCPLEASEUNASSIGNED is 11, the + value for DHCPLEASEUNKNOWN is 12, and the value for DHCPLEASEACTIVE + is 13. Finally, there are two new DHCP option defined; the client- + last-transaction-time option -- option code 91, and the associated-ip + option -- option code 92. + +9. Acknowledgements + + Jim Forster, Joe Ng, Guenter Roeck, and Mark Stapp contributed + greatly to the initial creation of the DHCPLEASEQUERY message. + + Patrick Guelat suggested several improvements to support static IP + addressing. Thomas Narten made many suggestions for improvements. + Russ Housley pressed effectively for increased security capabilities, + and Ted Hardie suggested ways to minimize undesired information + leakage. Bert Wijnen suggested we clarify our focus to DHCPv4 and + + + +Woundy & Kinnear Standards Track [Page 24] + +RFC 4388 DHCP Leasequery February 2006 + + + distinguish our approach from that of the DHCP MIB. R. Barr Hibbs, + one of the authors of the DHCP MIB, supplied information to + effectively distinguish that effort from DHCPLEASEQUERY. + +10. References + +10.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", RFC + 2131, March 1997. + + [RFC3046] Patrick, M., "DHCP Relay Agent Information Option", RFC + 3046, January 2001. + + [RFC3118] Droms, R. and W. Arbaugh, "Authentication for DHCP + Messages", RFC 3118, June 2001. + +10.2. Informative References + + [RFC826] Plummer, D., "Ethernet Address Resolution Protocol: Or + converting network protocol addresses to 48.bit Ethernet + address for transmission on Ethernet hardware", STD 37, + RFC 826, November 1982. + + [RFC951] Croft, W. and J. Gilmore, "Bootstrap Protocol", RFC 951, + September 1985. + + [RFC1542] Wimer, W., "Clarifications and Extensions for the + Bootstrap Protocol", RFC 1542, October 1993. + + [RFC2132] Alexander, S. and R. Droms, "DHCP Options and BOOTP + Vendor Extensions", RFC 2132, March 1997. + + [RFC3315] Droms, R., Bound, J., Volz, B., Lemon, T., Perkins, C., + and M. Carney, "Dynamic Host Configuration Protocol for + IPv6 (DHCPv6)", RFC 3315, July 2003. + + [BPI] SCTE Data Standards Subcommittee, "Data-Over-Cable + Service Interface Specifications: DOCSIS 1.0 Baseline + Privacy Interface Specification SCTE 22-2 2002", 2002, + available at http://www.scte.org/standards/. + + + + + + + +Woundy & Kinnear Standards Track [Page 25] + +RFC 4388 DHCP Leasequery February 2006 + + + [BPI+] CableLabs, "Data-Over-Cable Service Interface + Specifications: Baseline Privacy Plus Interface + Specification CM-SP-BPI+_I12-050812", August 2005, + available at http://www.cablemodem.com/. + + [DHCPMIB] Hibbs, R., Waters, G., "Dynamic Host Configuration + Protocol (DHCP) Server MIB", Work in Progress, February + 2004. + + [DOCSIS] SCTE Data Standards Subcommittee, "Data-Over-Cable + Service Interface Specifications: DOCSIS 1.0 Radio + Frequency Interface Specification SCTE 22-1 2002", 2002, + available at http://www.scte.org/standards/. + + [EUROMODEM] ECCA, "Technical Specification of a European Cable Modem + for digital bi-directional communications via cable + networks", Version 1.0, May 1999. + +Authors' Addresses + + Rich Woundy + Comcast Cable + 27 Industrial Ave. + Chelmsford, MA 01824 + + Phone: (978) 244-4010 + EMail: richard_woundy@cable.comcast.com + + + Kim Kinnear + Cisco Systems + 1414 Massachusetts Ave + Boxborough, MA 01719 + + Phone: (978) 936-0000 + EMail: kkinnear@cisco.com + + + + + + + + + + + + + + + +Woundy & Kinnear Standards Track [Page 26] + +RFC 4388 DHCP Leasequery February 2006 + + +Full Copyright Statement + + Copyright (C) The Internet Society (2006). + + This document is subject to the rights, licenses and restrictions + contained in BCP 78, and except as set forth therein, the authors + retain all their rights. + + This document and the information contained herein are provided on an + "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS + OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET + ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, + INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE + INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED + WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. + +Intellectual Property + + The IETF takes no position regarding the validity or scope of any + Intellectual Property Rights or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; nor does it represent that it has + made any independent effort to identify any such rights. Information + on the procedures with respect to rights in RFC documents can be + found in BCP 78 and BCP 79. + + Copies of IPR disclosures made to the IETF Secretariat and any + assurances of licenses to be made available, or the result of an + attempt made to obtain a general license or permission for the use of + such proprietary rights by implementers or users of this + specification can be obtained from the IETF on-line IPR repository at + http://www.ietf.org/ipr. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights that may cover technology that may be required to implement + this standard. Please address the information to the IETF at + ietf-ipr@ietf.org. + +Acknowledgement + + Funding for the RFC Editor function is provided by the IETF + Administrative Support Activity (IASA). + + + + + + + +Woundy & Kinnear Standards Track [Page 27] + diff --git a/docs/rfc6926.txt b/docs/rfc6926.txt new file mode 100644 index 0000000..81cd0dc --- /dev/null +++ b/docs/rfc6926.txt @@ -0,0 +1,2299 @@ + + + + + + +Internet Engineering Task Force (IETF) K. Kinnear +Request for Comments: 6926 M. Stapp +Category: Standards Track Cisco Systems, Inc. +ISSN: 2070-1721 R. Desetti + B. Joshi + Infosys Ltd. + N. Russell + Sea Street Technologies Inc. + P. Kurapati + Juniper Networks + B. Volz + Cisco Systems, Inc. + April 2013 + + + DHCPv4 Bulk Leasequery + +Abstract + + The Dynamic Host Configuration Protocol for IPv4 (DHCPv4) Leasequery + protocol allows a requestor to request information about DHCPv4 + bindings. This protocol is limited to queries for individual + bindings. In some situations, individual binding queries may not be + efficient or even possible. This document extends the DHCPv4 + Leasequery protocol to allow for bulk transfer of DHCPv4 address + binding data via TCP. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc6926. + + + + + + + + + + + +Kinnear, et al. Standards Track [Page 1] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + +Copyright Notice + + Copyright (c) 2013 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Kinnear, et al. Standards Track [Page 2] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + +Table of Contents + + 1. Introduction ....................................................4 + 2. Terminology .....................................................5 + 3. Design Goals ....................................................8 + 3.1. Information Acquisition before Data Starts .................8 + 3.2. Lessen Need for Caching and Negative Caching ...............8 + 3.3. Antispoofing in 'Fast Path' ................................8 + 3.4. Minimize Data Transmission .................................9 + 4. Protocol Overview ...............................................9 + 5. Interaction between UDP Leasequery and Bulk Leasequery .........11 + 6. Message and Option Definitions .................................12 + 6.1. Message Framing for TCP ...................................12 + 6.2. New or Changed Options ....................................13 + 6.3. Connection and Transmission Parameters ....................20 + 7. Requestor Behavior .............................................21 + 7.1. Connecting and General Processing .........................21 + 7.2. Forming a Bulk Leasequery .................................21 + 7.3. Processing Bulk Replies ...................................23 + 7.4. Processing Time Values in Leasequery Messages .............25 + 7.5. Querying Multiple Servers .................................26 + 7.6. Making Sense out of Multiple Responses concerning + a Single IPv4 Address .....................................26 + 7.7. Multiple Queries to a Single Server over One Connection ...27 + 7.8. Closing Connections .......................................28 + 8. Server Behavior ................................................29 + 8.1. Accepting Connections .....................................29 + 8.2. Replying to a Bulk Leasequery .............................29 + 8.3. Building a Single Reply for Bulk Leasequery ...............33 + 8.4. Multiple or Parallel Queries ..............................34 + 8.5. Closing Connections .......................................35 + 9. Security Considerations ........................................35 + 10. IANA Considerations ...........................................37 + 11. Acknowledgements ..............................................38 + 12. References ....................................................38 + 12.1. Normative References .....................................38 + 12.2. Informative References ...................................39 + + + + + + + + + + + + + + +Kinnear, et al. Standards Track [Page 3] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + +1. Introduction + + DHCPv4 [RFC2131] [RFC2132] specifies a protocol for the assignment of + IPv4 address and configuration information to IPv4 nodes. DHCPv4 + servers maintain authoritative binding information. + + +--------+ + | DHCPv4 | +--------------+ + | Server |-...-| DHCP | + | | | Relay Agent | + +--------+ +--------------+ + | | + +------+ +------+ + |Modem1| |Modem2| + +------+ +------+ + | | | + +-----+ +-----+ +-----+ + |Node1| |Node2| |Node3| + +-----+ +-----+ +-----+ + + Figure 1: Example DHCPv4 Configuration + + DHCPv4 relay agents receive DHCPv4 messages and frequently append a + Relay Agent Information option [RFC3046] before relaying them to the + configured DHCPv4 servers (see Figure 1). In this process, some + relay agents also glean lease information sent by the server and + cache it locally. This information is used for a variety of + purposes. Two examples are prevention of spoofing attempts from the + DHCPv4 clients and installation of routes. When a relay agent + reboots, this information is frequently lost. + + The DHCPv4 Leasequery capability [RFC4388] extends the basic DHCPv4 + capability to allow an external entity, such as a relay agent, to + query a DHCPv4 server to rapidly recover lease state information + about a particular IP address or client. + + The existing query types in Leasequery are typically data driven; the + relay agent initiates the Leasequery when it receives data traffic + from or to the client. This approach may not scale well when there + are thousands of clients connected to the relay agent or when the + relay agent has a need to rebuild its internal data store prior to + processing traffic in one direction or another. + + Some applications require the ability to query the server without + waiting for traffic from or to clients. This query capability, in + turn, requires an underlying transport more suitable to the bulk + transmission of data. + + + + +Kinnear, et al. Standards Track [Page 4] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + This document extends the DHCPv4 Leasequery protocol [RFC4388] to add + support for queries that address these additional requirements. + There may be many thousands of DHCPv4 bindings returned as the result + of a single request, so TCP [RFC4614] is specified for efficiency of + data transfer. We define several additional query types, each of + which can return multiple responses, in order to meet a variety of + requirements. + +2. Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and + "OPTIONAL" in this document are to be interpreted as described in RFC + 2119 [RFC2119]. + + This document uses the following terms: + + o "absolute time" + + Absolute time is a 32-bit quantity containing the number of + seconds since January 1, 1970. + + o "access concentrator" + + An access concentrator is a router or switch at the broadband + access provider's edge of a public broadband access network. This + document assumes that the access concentrator includes the DHCPv4 + relay agent functionality, for example, a CMTS (Cable Modem + Termination System) in a cable environment or a DSLAM (Digital + Subscriber Line Access Multiplexer) in a DSL environment. + + o "active binding" + + An IP address with an active binding refers to an IP address that + is currently associated with a DHCPv4 client where that DHCPv4 + client has the right to use the IP address. + + o "Bulk Leasequery" + + Bulk Leasequery involves requesting and receiving the existing + DHCPv4 address binding information in an efficient manner. + + o "clock skew" + + The clock skew for a Bulk Leasequery connection is the difference + between the absolute time on a DHCPv4 server and the absolute time + on the system where a requestor of a Bulk Leasequery is executing. + It is not absolutely constant but is likely to vary only slowly. + + + +Kinnear, et al. Standards Track [Page 5] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + It is possible that, when both systems run NTP, the clock skew is + negligible; this is not only acceptable but desired. + + While it is easy to think that this can be calculated precisely + after one message is received by a requestor from a DHCPv4 server, + a more accurate value is derived from continuously examining the + instantaneous value developed from each message received from a + DHCPv4 server and using it to make small adjustments to the + existing value held in the requestor. + + o "Default VPN" + + A default VPN indicates that the address being described belongs + to the set of addresses not part of any VPN (in other words, the + normal address space operated on by DHCP). This includes Special + Use IPv4 Addresses as defined in [RFC5735]. + + o "DHCPv4 client" + + A DHCPv4 client is an Internet node using DHCPv4 to obtain + configuration parameters such as a network address. + + o "DHCPv4 relay agent" + + A DHCPv4 relay agent is an agent that is neither a DHCPv4 client + nor a DHCP server that transfers BOOTP and DHCPv4 messages between + clients and servers residing on different subnets, per [RFC951] + and [RFC1542]. + + o "DHCPv4 server" + + A DHCPv4 server is an Internet node that returns configuration + parameters to DHCPv4 clients. + + o "DSLAM" + + DSLAM stands for Digital Subscriber Line Access Multiplexer. + + o "downstream" + + Downstream refers to a direction away from the central part of a + network and toward the edge. In a DHCPv4 context, this typically + refers to a network direction that is away from the DHCPv4 server + and toward the DHCPv4 client. + + o "Global VPN" + + Global VPN is another name for the default VPN. + + + +Kinnear, et al. Standards Track [Page 6] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + o "IP address" + + In this document, the term "IP address" refers to an IPv4 IP + address. + + o "IP address binding" + + An IP address binding is the information that a DHCPv4 server + keeps regarding the relationship between a DHCPv4 client and an IP + address. This includes the identity of the DHCPv4 client and the + expiration time, if any, of any lease that client has on a + particular IP address. In some contexts, this may include + information on IP addresses that are currently associated with + DHCPv4 clients, and in others, it may also include IP addresses + with no current association to a DHCPv4 client. + + o "MAC address" + + In the context of a DHCPv4 message, a Media Access Control (MAC) + address consists of the fields: hardware type "htype", hardware + length "hlen", and client hardware address "chaddr". + + o "upstream" + + Upstream refers to a direction toward the central part of a + network and away from the edge. In a DHCPv4 context, this + typically refers to a network direction that is away from the + DHCPv4 client and toward the DHCPv4 server. + + o "stable storage" + + Stable storage is used to hold information concerning IP address + bindings (among other things) so that this information is not lost + in the event of a failure that requires restart of the network + element. DHCPv4 servers are typically expected to have high-speed + access to stable storage, while relay agents and access + concentrators usually do not have access to stable storage, + although they may have periodic access to such storage. + + o "xid" + + Transaction-id. The term "xid" refers to the DHCPv4 field + containing the transaction-id of the message. + + + + + + + + +Kinnear, et al. Standards Track [Page 7] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + +3. Design Goals + + The goal of this document is to provide a lightweight protocol for an + access concentrator or other network element (such as a DHCP relay + agent) to retrieve IP address binding information available in the + DHCPv4 server. The protocol should also allow an access concentrator + or DHCP relay agent to retrieve consolidated IP address binding + information for either the entire access concentrator or a single + connection/circuit. Throughout the discussion below, everything that + applies to an access concentrator also applies to a DHCP relay agent. + +3.1. Information Acquisition before Data Starts + + The existing data-driven approach required by [RFC4388] means that + the Leasequeries can only be performed after an access concentrator + receives data. To implement antispoofing, the concentrator must drop + messages for each client until it gets lease information from the + DHCPv4 server for that client. If an access concentrator finishes + the Leasequeries before it starts receiving data, then there is no + need to drop legitimate messages. In this way, outage time may be + reduced. + +3.2. Lessen Need for Caching and Negative Caching + + The result of a single Leasequery should be cached, whether that + results in a positive or negative cache, in order to remember that + the Leasequery was performed. This caching is required to limit the + traffic imposed upon a DHCPv4 server by Leasequeries for information + already received. + + These caches not only consume precious resources, they also need to + be managed. Hence, they should be avoided as much as possible. One + of the goals of the DHCPv4 Bulk Leasequery is to reduce the need for + this sort of caching. + +3.3. Antispoofing in 'Fast Path' + + If antispoofing is not done in the fast path, it will become a + bottleneck and may lead to denial of service of the access + concentrator. The Leasequeries should make it possible to do + antispoofing in the fast path. + + + + + + + + + + +Kinnear, et al. Standards Track [Page 8] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + +3.4. Minimize Data Transmission + + It may be that a network element is able to periodically save its + entire list of assigned IP addresses to some form of stable storage. + In this case, it will wish to recover all of the updates to this + information without duplicating the information it has recovered from + its own stable storage. + + Bulk Leasequery allows the specification of a query-start-time as + well as a query-end-time. Use of query times allows a network + element that periodically commits information to stable storage to + recover just what it lost since the last commit. + +4. Protocol Overview + + The DHCPv4 Bulk Leasequery protocol is modeled on the existing + individual DHCPv4 Leasequery protocol in [RFC4388] as well as related + work on DHCPv6 Bulk Leasequery [RFC5460]. A Bulk Leasequery + requestor opens a TCP connection to a DHCPv4 server using the DHCPv4 + port 67. Note that this implies that the Leasequery requestor has + server IP address(es) available via configuration or some other means + and that it has unicast IP reachability to the DHCPv4 server. No + relaying of Bulk Leasequery messages is specified. + + After establishing a connection, the requestor sends a + DHCPBULKLEASEQUERY message over the connection. + + The server uses the message type and additional data in the DHCPv4 + DHCPBULKLEASEQUERY message to identify any relevant bindings. + + In order to support some query types, servers may have to maintain + additional data structures or otherwise be able to locate bindings + that have been requested by the Leasequery requestor. + + Relevant bindings are returned in DHCPv4 messages with either the + DHCPLEASEACTIVE message type for an IP address with a currently + active lease or, in some situations, a DHCPLEASEUNASSIGNED message + type for an IP address that is controlled by the DHCPv4 server but is + not actively leased by a DHCPv4 client at the present time. + + The Bulk Leasequery protocol is designed to provide an external + entity with information concerning existing DHCPv4 IPv4 address + bindings managed by the DHCPv4 server. When complete, the DHCPv4 + server will send a DHCPLEASEQUERYDONE message. If a connection is + lost while processing a Bulk Leasequery, the Bulk Leasequery must be + retried as there is no provision for determining the extent of data + already received by the requestor for a Bulk Leasequery. + + + + +Kinnear, et al. Standards Track [Page 9] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + Bulk Leasequery supports queries by MAC address and by Client + Identifier in a way similar to [RFC4388]. The Bulk Leasequery + protocol also adds several new queries. + + o Query by Relay Identifier + + This query asks a server for the bindings associated with a + specific relay agent; the relay agent is identified by a Relay + Agent Identifier carried in a Relay-ID sub-option [RFC6925]. + Relay agents can include this sub-option while relaying messages + to DHCPv4 servers. Servers can retain the Relay-ID and associate + it with bindings made on behalf of the relay agent's clients. The + bindings returned are only those for DHCPv4 clients with a + currently active binding. + + o Query by Remote ID + + This query asks a server for the bindings associated with a relay + agent Remote ID sub-option [RFC3046] value. The bindings returned + are only those for DHCPv4 clients with a currently active binding. + + o Query for All Configured IP Addresses + + This query asks a server for information concerning all IP + addresses configured in that DHCPv4 server by specifying no other + type of query. In this case, the bindings returned are for all + configured IP addresses, whether or not they contain a currently + active binding to a DHCPv4 client, since one point of this type of + query is to update an existing database with changes after a + particular point in time. + + Any of the above queries can be qualified by the specification of a + query-start-time or a query-end-time (or both). When these timers + are used as qualifiers, they indicate that a binding should be + included if it changed on or after the query-start-time and on or + before the query-end-time. + + In addition, any of the above queries can be qualified by the + specification of a VPN-ID option [RFC6607] to select the VPN on which + the query should be processed. The VPN-ID option is also extended to + allow queries across all available VPNs. In the absence of any VPN- + ID option, only the default (global) VPN is used to satisfy the + query. + + + + + + + + +Kinnear, et al. Standards Track [Page 10] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + +5. Interaction between UDP Leasequery and Bulk Leasequery + + Bulk Leasequery can be seen as an extension of the existing UDP + Leasequery protocol [RFC4388]. This section clarifies the + relationship between the two protocols. + + The Bulk Leasequery TCP connection is only designed to handle the + DHCPBULKLEASEQUERY request. It is not intended as an alternative + DHCPv4 communication option for clients seeking other DHCPv4 + services. DHCPv4 address allocation could not be performed over a + TCP connection in any case, as a TCP connection requires an IP + address and no IPv4 address exists prior to a successful DHCPv4 + address allocation exchange. In addition, the existing DHCPv4 UDP + transmission regime is implemented in untold millions of devices + deployed worldwide, and complicating DHCPv4 services with alternative + transmission approaches (even if it were possible) would be worse + than any perceived benefit to doing so. + + Two of the query types introduced in the UDP Leasequery protocol can + be used in the Bulk Leasequery protocol -- Query by MAC address and + Query by Client-identifier. + + The contents of the reply messages are similar between the existing + UDP Leasequery protocol and the Bulk Leasequery protocol, though more + information is returned in the Bulk Leasequery messages. + + One change in behavior for these existing queries is required when + Bulk Leasequery is used. Sections 6.1, 6.4.1, and 6.4.2 of [RFC4388] + specify the use of an associated-ip option in DHCPLEASEACTIVE + messages in cases where multiple bindings were found. When Bulk + Leasequery is used, this mechanism is not necessary; a server + returning multiple bindings simply does so directly as specified in + this document. The associated-ip option MUST NOT appear in Bulk + Leasequery replies. + + Implementors should note that the TCP message framing defined in + Section 6.1 is not compatible with the UDP message format. If a TCP- + framed request is sent as a UDP message, it may not be valid, because + protocol fields will be offset by the message-size prefix. + + + + + + + + + + + + +Kinnear, et al. Standards Track [Page 11] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + +6. Message and Option Definitions + +6.1. Message Framing for TCP + + The use of TCP for the Bulk Leasequery protocol permits multiple + messages to be sent from one end of the connection to the other + without requiring a request/response paradigm as does UDP DHCPv4 + [RFC2131]. The receiver needs to be able to determine the size of + each message it receives. Two octets containing the message size in + network byte order are prepended to each DHCPv4 message sent on a + Bulk Leasequery TCP connection. The two message-size octets 'frame' + each DHCPv4 message. + + The maximum message size is 65535 octets. + + 0 1 2 3 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | message-size | op (1) | htype (1) | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | hlen (1) | hops (1) | .... | + +---------------+---------------+ + + | | + . remainder of DHCPv4 message, + . from Figure 1 of [RFC2131] . + . . + . (variable) . + | | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + message-size the number of octets in the message that + follows, as a 16-bit unsigned integer in + network byte order. + + All other fields are as specified in DHCPv4 [RFC2131]. + + Figure 2: Format of a DHCPv4 Message in TCP + + The intent in using this format is that code that currently knows how + to deal with sending or receiving a message in [RFC2131] format will + easily be able to deal with the message contained in the TCP framing. + + + + + + + + + + +Kinnear, et al. Standards Track [Page 12] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + +6.2. New or Changed Options + + The existing messages DHCPLEASEUNASSIGNED and DHCPLEASEACTIVE are + used as the value of the dhcp-message-type option to indicate an IP + address that is currently not leased or currently leased to a DHCPv4 + client, respectively [RFC4388]. + + Additional options have also been defined to enable the Bulk + Leasequery protocol to communicate useful information to the + requestor. + +6.2.1. dhcp-message-type + + The dhcp-message-type option (option 53) from Section 9.6 of + [RFC2132] requires new values. The values of these message types are + shown below in an extension of the table from Section 9.6 of + [RFC2132]: + + Value Message Type + ----- ------------ + 14 DHCPBULKLEASEQUERY + 15 DHCPLEASEQUERYDONE + +6.2.2. status-code + + The status-code option allows a machine-readable value to be returned + regarding the status of a DHCPBULKLEASEQUERY request. + + This option has two possible scopes when used with Bulk Leasequery, + depending on the context in which it appears. It refers to the + information in a single Leasequery reply if the value of the dhcp- + message-type is DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED. It refers to + the message stream related to an entire request if the value of the + dhcp-message-type is DHCPLEASEQUERYDONE. + + The code for this option is 151. The length of this option is a + minimum of 1 octet. + + Status Status + Code Len Code Message + +------+------+------+------+------+-- --+-----+ + | 151 | n+1 |status| s1 | s2 | ... | sn | + +------+------+------+------+------+-- --+-----+ + + + + + + + + +Kinnear, et al. Standards Track [Page 13] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + The status-code is indicated in one octet as defined in the table + below. The Status Message is an optional UTF-8-encoded text string + suitable for display to an end user. This text string MUST NOT + contain a termination character (e.g., a null). The Len field + describes the length of the Status Message without any terminator + character. Null characters MUST NOT appear in the Status Message + string, and it is a protocol violation for them to appear in any + position in the Status Message, including at the end. + + Name Status Code Description + ---- ----------- ----------- + Success 000 Success. Also signaled by absence of + a status-code option. + + UnspecFail 001 Failure, reason unspecified. + + QueryTerminated 002 Indicates that the server is unable to + perform a query or has prematurely terminated + the query for some reason (which should be + communicated in the text message). + + MalformedQuery 003 The query was not understood. + + NotAllowed 004 The query or request was understood but was + not allowed in this context. + + A status-code option MAY appear in the options field of a DHCPv4 + message. If the status-code option does not appear, it is assumed + that the operation was successful. The status-code option SHOULD NOT + appear in a message that is successful unless there is some text + string that needs to be communicated to the requestor. + +6.2.3. base-time + + The base-time option is the current time the message was created to + be sent by the DHCPv4 server to the requestor of the Bulk Leasequery. + This MUST be an absolute time. All of the other time-based options + in the reply message are relative to this time, including the dhcp- + lease-time [RFC2132] and client-last-transaction-time [RFC4388]. + This time is in the context of the DHCPv4 server that placed this + option in a message. + + This is an unsigned integer in network byte order. + + + + + + + + +Kinnear, et al. Standards Track [Page 14] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + The code for this option is 152. The length of this option is 4 + octets. + + DHCPv4 Server + Code Len base-time + +-----+-----+-----+-----+-----+-----+ + | 152 | 4 | t1 | t2 | t3 | t4 | + +-----+-----+-----+-----+-----+-----+ + +6.2.4. start-time-of-state + + The start-time-of-state option allows the receiver to determine the + time at which the IP address made the transition into its current + state. + + This MUST NOT be an absolute time, which is equivalent to saying that + this MUST NOT be an absolute number of seconds since January 1, 1970. + Instead, this MUST be the unsigned integer number of seconds from the + time the IP address transitioned its current state to the time + specified in the base-time option in the same message. + + This is an unsigned integer in network byte order. + + The code for this option is 153. The length of this option is 4 + octets. + + Seconds in the past + Code Len from base-time + +-----+-----+-----+-----+-----+-----+ + | 153 | 4 | t1 | t2 | t3 | t4 | + +-----+-----+-----+-----+-----+-----+ + +6.2.5. query-start-time + + The query-start-time option specifies a start query time to the + DHCPv4 server. If specified, only bindings that have changed on or + after the query-start-time should be included in the response to the + query. + + The requestor MUST determine the query-start-time using lease + information it has received from the DHCPv4 server. This MUST be an + absolute time in the DHCPv4 server's context (see Section 7.4). + + Typically (though this is not a requirement), the query-start-time + option will contain the value most recently received in a base-time + option by the requestor, as this will indicate the last successful + communication with the DHCP server. + + + + +Kinnear, et al. Standards Track [Page 15] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + This MUST be an absolute time. + + This is an unsigned integer in network byte order. + + The code for this option is 154. The length of this option is 4 + octets. + + DHCPv4 Server + Code Len query-start-time + +-----+-----+-----+-----+-----+-----+ + | 154 | 4 | t1 | t2 | t3 | t4 | + +-----+-----+-----+-----+-----+-----+ + +6.2.6. query-end-time + + The query-end-time option specifies an end query time to the DHCPv4 + server. If specified, only bindings that have changed on or before + the query-end-time should be included in the response to the query. + + The requestor MUST determine the query-end-time based on lease + information it has received from the DHCPv4 server. This MUST be an + absolute time in the context of the DHCPv4 server. + + In the absence of information to the contrary, the requestor SHOULD + assume that the time context of the DHCPv4 server is identical to the + time context of the requestor (see Section 7.4). + + This is an unsigned integer in network byte order. + + The code for this option is 155. The length of this option is 4 + octets. + + DHCPv4 Server + Code Len query-end-time + +-----+-----+-----+-----+-----+-----+ + | 155 | 4 | t1 | t2 | t3 | t4 | + +-----+-----+-----+-----+-----+-----+ + + + + + + + + + + + + + + +Kinnear, et al. Standards Track [Page 16] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + +6.2.7. dhcp-state + + The dhcp-state option allows greater detail to be returned than + allowed by the DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED message types. + + The code for this option is 156. The length of this option is 1 + octet. + + 0 1 2 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | 156 | Length | State | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + 156 The option code. + + Length The option length, 1 octet. + + State The state of the IP address. + + Value State + ----- ----- + 1 AVAILABLE Address is available to local DHCPv4 server + 2 ACTIVE Address is assigned to a DHCPv4 client + 3 EXPIRED Lease has expired + 4 RELEASED Lease has been released by DHCPv4 client + 5 ABANDONED Server or client flagged address as unusable + 6 RESET Lease was freed by some external agent + 7 REMOTE Address is available to a remote DHCPv4 server + 8 TRANSITIONING Address is moving between states + + Note that some of these states may be transient and may not appear in + normal use. A DHCPv4 server MUST implement at least the AVAILABLE + and ACTIVE states and SHOULD implement at least the ABANDONED and + RESET states. + + Note the states AVAILABLE and REMOTE are relative to the current + server. An address that is available to the current server should + show AVAILABLE on that server, and if another server is involved with + that address as well, it should show as REMOTE on that other server. + + The dhcp-state option SHOULD contain ACTIVE when it appears in a + DHCPLEASEACTIVE message. A DHCPv4 server MAY choose to not send a + dhcp-state option in a DHCPLEASEACTIVE message, and a requestor + SHOULD assume that the dhcp-state is ACTIVE if no dhcp-state option + appears in a DHCPLEASEACTIVE message. + + + + + +Kinnear, et al. Standards Track [Page 17] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + The reference to local and remote relate to possible use in an + environment that includes multiple servers cooperating to provide an + increased availability solution. In this case, an IP address with + the state of AVAILABLE is available to the local server, while one + with the state of REMOTE is available to a remote server. Usually, + an IP address that is AVAILABLE on one server would be REMOTE on any + remote server. The TRANSITIONING state is also likely to be useful + in multiple server deployments, where sometimes one server must + interlock a state change with one or more other servers. Should a + Bulk Leasequery need to send information concerning the state of the + IP address during this period, it SHOULD use the TRANSITIONING state, + since the IP address is likely to be neither ACTIVE or AVAILABLE. + + There is no requirement for the state of an IP address to transition + in a well-defined way from state to state. To put this another way, + you cannot draw a simple state transition graph for the states of an + IP address, and the requestor of a Leasequery MUST NOT depend on one + certain state always following a particular previous state. While a + state transition diagram can be drawn, it would be fully connected + and therefore conveys no useful information. Every state can (at + times) follow every other state. + +6.2.8. data-source + + The data-source option contains information about the source of the + data in a DHCPLEASEACTIVE or a DHCPLEASEUNASSIGNED message. It + SHOULD be used when there are two or more servers that might have + information about a particular IP address binding. Frequently, two + servers work together to provide an increased availability solution + for the DHCPv4 service, and in these cases, both servers will respond + to Bulk Leasequery requests for the same IP address. When one server + is working with another server and both may respond with information + about the same IP address, each server SHOULD return the data-source + option with the other information provided about the IP address. + + The data contained in this option will allow an external process to + better discriminate between the information provided by each of the + servers servicing this IPv4 address. + + + + + + + + + + + + + +Kinnear, et al. Standards Track [Page 18] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + The code for this option is 157. The length of this option is 1 + octet. + + 0 1 2 + 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | 157 | Length | Flags | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + + 157 The option code. + + Length The option length, 1 octet. + + Flags The source information for this message. + + 0 1 2 3 4 5 6 7 + +-+-+-+-+-+-+-+-+ + | UNA |R| + +-+-+-+-+-+-+-+-+ + + R: REMOTE flag + + remote = 1 + local = 0 + + UNA: UNASSIGNED + + The REMOTE flag is used to indicate where the most recent change of + state (or other interesting change) concerning this IPv4 address took + place. If the value is local, then the change took place on the + server from which this message was transmitted. If the value is + remote, then the change took place on some other server and was made + known to the server from which this message was transmitted. + + If this option was requested and it doesn't appear, the requestor + MUST consider that the data-source was local. + + Unassigned bits MUST be ignored. + + + + + + + + + + + + + +Kinnear, et al. Standards Track [Page 19] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + +6.2.9. Virtual Subnet Selection Type and Information + + All of the (sub-)options defined in [RFC6607] carry identical + payloads, consisting of a type and additional VSS (Virtual Subnet + Selection) information. The existing table is extended (see below) + with a new type 254 to allow specification of a type code that + indicates that all VPNs are to be used to process the Bulk + Leasequery. + + Type VSS Information Format + ---------------------------------------------------------- + 0 Network Virtual Terminal (NVT) ASCII VPN identifier + 1 RFC 2685 VPN-ID + CHANGED -> 2-253 Unassigned + NEW -> 254 All VPNs (wildcard) + 255 Global, default VPN + +6.3. Connection and Transmission Parameters + + DHCPv4 servers that support Bulk Leasequery SHOULD listen for + incoming TCP connections on the DHCPv4 server port 67. + Implementations MAY offer to make the incoming port configurable, but + port 67 MUST be the default. Requestors SHOULD make TCP connections + to port 67 and MAY offer to make the destination server port + configurable. + + This section presents a table of values used to control Bulk + Leasequery behavior, including recommended defaults. Implementations + MAY make these values configurable. However, configuring too-small + timeout values may lead to harmful behavior both to this application + as well as to other traffic in the network. As a result, timeout + values smaller than the default values are NOT RECOMMENDED. + + Parameter Default Description + -------------------------------------------------------------------- + BULK_LQ_DATA_TIMEOUT 300 secs Bulk Leasequery data timeout + for both client and server + (see Sections 7 and 8) + BULK_LQ_MAX_CONNS 10 Max Bulk Leasequery TCP connections + at the server side (see Section 8.1) + + + + + + + + + + + +Kinnear, et al. Standards Track [Page 20] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + +7. Requestor Behavior + +7.1. Connecting and General Processing + + A requestor attempts to establish a TCP connection to a DHCPv4 server + in order to initiate a Leasequery exchange. If the attempt fails, + the requestor MAY retry. + + If Bulk Leasequery is terminated prematurely by a DHCPLEASEQUERYDONE + with a status-code option with a status code of QueryTerminated or by + the failure of the connection over which it was being submitted, the + requestor MAY retry the request after the creation of a new + connection. + + Messages from the DHCPv4 server come as multiple responses to a + single DHCPBULKLEASEQUERY message. Thus, each DHCPBULKLEASEQUERY + request MUST have an xid (transaction-id) unique on the connection on + which it is sent. All of the messages that come as a response to + that message will contain the same xid as the request. The xid + allows the data-streams of two different DHCPBULKLEASEQUERY requests + to be demultiplexed by the requestor. + +7.2. Forming a Bulk Leasequery + + Bulk Leasequery is designed to create a connection that will transfer + the state of some subset (or possibly all) of the IP address bindings + from the DHCPv4 server to the requestor. The DHCPv4 server will send + all of the requested IPv4 address bindings across this connection + with minimal delay after it receives the request. In this context, + "all IP address binding information" means information about all IPv4 + addresses configured within the DHCPv4 server that meet the specified + query criteria. For some query criteria, this may include IP address + binding information for IP addresses that may not now have or ever + have had an association with a specific DHCPv4 client. + + To form the Bulk query, a DHCPv4 request is constructed with a dhcp- + message-type of DHCPBULKLEASEQUERY. The query SHOULD have a dhcp- + parameter-request-list to inform the DHCPv4 server which DHCPv4 + options are of interest to the requestor sending the + DHCPBULKLEASEQUERY message. The dhcp-parameter-request-list in a + DHCPBULKLEASEQUERY message SHOULD contain the codes for base-time, + dhcp-lease-time, start-time-of-state, and client-last-transaction- + time. + + A DHCPBULKLEASEQUERY request is constructed of one primary query and + optionally one or more qualifiers for it. + + + + + +Kinnear, et al. Standards Track [Page 21] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + The possible primary queries are listed below. Each + DHCPBULKLEASEQUERY request MUST contain only one of these primary + queries. + + o Query by MAC address + + In a Query by MAC address, the chaddr, htype, and hlen of the + DHCPv4 packet are filled in with the values requested. + + o Query by Client-identifier + + In a Query by Client-identifier, a Client-identifier option + containing the requested value is included in the + DHCPBULKLEASEQUERY request. + + o Query by Remote ID + + In a Query by Remote ID, a Remote ID sub-option containing the + requested value is included in the relay-agent-information option + of the DHCPBULKLEASEQUERY request. + + o Query by Relay-ID + + In a Query by Relay-ID, a Relay-ID sub-option [RFC6925] containing + the requested value is included in the relay-agent-information + option of the DHCPBULKLEASEQUERY request. + + o Query for All Configured IP Addresses + + A Query for All Configured IP addresses is signaled by the absence + of any other primary query. + + There are three qualifiers that can be applied to any of the above + primary queries. These qualifiers can appear individually or + together in any combination, but only one of each can appear. + + o Query Start Time + + Inclusion of a query-start-time option specifies that only IP + address bindings that have changed on or after the time specified + in the query-start-time option should be returned. + + o Query End Time + + Inclusion of a query-end-time option specifies that only IP + address bindings that have changed on or before the time specified + in the query-end-time option should be returned. + + + + +Kinnear, et al. Standards Track [Page 22] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + o VPN-ID + + If no VPN-ID option appears in the DHCPBULKLEASEQUERY, the default + (global) VPN is searched to satisfy the query specified by the + DHCPBULKLEASEQUERY. Using the VPN-ID option [RFC6607] allows the + requestor to specify a single VPN other than the default VPN. In + addition, the VPN-ID option has been extended as part of this + document to allow specification that all configured VPNs be + searched in order to satisfy the query specified in the + DHCPBULKLEASEQUERY. + + In all cases, any message returned from a DHCPBULKLEASEQUERY + request containing information about an IP address for other than + the default (global) VPN MUST contain a VPN-ID option in the + message. + + Use of the query-start-time or the query-end-time options or both can + serve to reduce the amount of data transferred over the TCP + connection by a considerable amount. Note that the times specified + in the query-start-time or query-end-time options are absolute times, + not durations offset from "now". + + The TCP connection may become blocked or stop being writable while + the requestor is sending its query. Should this happen, the + implementation's behavior is controlled by the current value of + BULK_LQ_DATA_TIMEOUT. The default value is given elsewhere in this + document, and this value may be overridden by local configuration of + the operator. + + If this situation is detected, the requestor SHOULD start a timer + using the current value of BULK_LQ_DATA_TIMEOUT. If that timer + expires, the requestor SHOULD terminate the connection. This timer + is completely independent of any TCP timeout established by the TCP + protocol connection. + +7.3. Processing Bulk Replies + + The requestor attempts to read a DHCPv4 Leasequery reply message from + the TCP connection. + + The TCP connection may stop delivering reply data (i.e., the + connection stops being readable). Should this happen, the + implementation's behavior is controlled by the current value of + BULK_LQ_DATA_TIMEOUT. The default value is given elsewhere in this + document, and this value may be overridden by local configuration of + the operator. + + + + + +Kinnear, et al. Standards Track [Page 23] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + If this situation is detected, the requestor SHOULD start a timer + using the current value of BULK_LQ_DATA_TIMEOUT. If that timer + expires, the requestor SHOULD terminate the connection. + + A single Bulk Leasequery can, and usually will, result in a large + number of replies. The requestor MUST be prepared to receive more + than one reply with an xid matching a single DHCPBULKLEASEQUERY + message from a single DHCPv4 server. If the xid in the received + message does not match an outstanding DHCPBULKLEASEQUERY message, the + requestor MUST close the TCP connection. + + If the requestor receives more data than it can process, it can + simply abort the connection and try again with a more specific + request. It can also simply read the TCP connection more slowly and + match the rate at which it can digest the information returned in the + Bulk Leasequery packets with the rate at which it reads those packets + from the TCP connection. + + The DHCPv4 server MUST send a server-identifier option (option 54) in + the first response to any DHCPBULKLEASEQUERY message. The DHCPv4 + server SHOULD NOT send server-identifier options in subsequent + responses to that DHCPBULKLEASEQUERY message. The requestor MUST + cache the server-identifier option from the first response and apply + it to any subsequent responses. + + The response messages generated by a DHCPBULKLEASEQUERY request are: + + o DHCPLEASEACTIVE + + A Bulk Leasequery will generate DHCPLEASEACTIVE messages + containing binding data for bound IP addresses that match the + specified query criteria. The IP address that is bound to a + DHCPv4 client will appear in the ciaddr field of the + DHCPLEASEACTIVE message. The message may contain a non-zero + chaddr, htype, hlen, and possibly additional options. + + o DHCPLEASEUNASSIGNED + + Some queries will also generate DHCPLEASEUNASSIGNED messages for + IP addresses that match the query criteria. These messages + indicate that the IP address is managed by the DHCPv4 server but + is not currently bound to any DHCPv4 client. The IP address to + which this message refers will appear in the ciaddr field of the + DHCPLEASEUNASSIGNED message. A DHCPLEASEUNASSGINED message MAY + also contain information about the last DHCPv4 client that was + bound to this IP address. The message may contain a non-zero + chaddr, htype, hlen, and possibly additional options in this case. + + + + +Kinnear, et al. Standards Track [Page 24] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + o DHCPLEASEQUERYDONE + + A response of DHCPLEASEQUERYDONE indicates that the server has + completed its response to the query and that no more messages will + be sent in response to the DHCPBULKLEASEQUERY. More details will + sometimes be available in the received status-code option in the + DHCPLEASEQUERYDONE message. If there is no status-code option in + the DHCPLEASEQUERYDONE message, then the query completed + successfully. + + Note that a query that returned no data, that is, a + DHCPBULKLEASEQUERY request followed by a DHCPLEASEQUERYDONE + response, is considered a successful query in that no errors + occurred during the processing. It is not considered an error to + have no information to return to a DHCPBULKLEASEQUERY request. + + The DHCPLEASEUNKNOWN message MUST NOT appear in a response to a Bulk + Leasequery. + + The requestor MUST NOT assume that there is any inherent order in the + IP address binding information that is sent in response to a + DHCPBULKLEASEQUERY. While the base-time will tend to increase + monotonically (as it is the current time on the DHCPv4 server), the + actual time that any IP address binding information changed is + unrelated to the base-time. + + The DHCPLEASEQUERYDONE message always ends a successful + DHCPBULKLEASEQUERY request and any unsuccessful DHCPBULKLEASEQUERY + requests not terminated by a dropped connection. After receiving a + DHCPLEASEQUERYDONE from a server, the requestor MAY close the TCP + connection to that server if no other DHCPBULKLEASEQUERY is + outstanding on that TCP connection. + + The DHCPv4 Leasequery protocol [RFC4388] uses the associated-ip + option as an indicator that multiple bindings were present in + response to a single DHCPv4 client-based query. For Bulk Leasequery, + a separate message is returned for each binding, so the associated-ip + option is not used. + +7.4. Processing Time Values in Leasequery Messages + + Bulk Leasequery requests may be made to a DHCPv4 server whose + absolute time may not be synchronized with the local time of the + requestor. Thus, there are at least two time contexts in even the + simplest Bulk Leasequery response, and in the situation where + multiple DHCPv4 servers are queried, the situation becomes even more + complex. + + + + +Kinnear, et al. Standards Track [Page 25] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + If the requestor of a Bulk Leasequery is saving the data returned in + some form, it has a requirement to store a variety of time values; + some of these will be time in the context of the requestor, and some + will be time in the context of the DHCPv4 server. + + When receiving a DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message from + the DHCPv4 server, the message will contain a base-time option. The + time contained in this base-time option is in the context of the + DHCPv4 server. As such, it is an ideal time to save and use as input + to a DHCPBULKLEASEQUERY in the query-start-time or query-end-time + options, should the requestor ever need to issue a DHCPBULKLEASEQUERY + message using those options as part of a later query, since those + options require a time in the context of the DHCPv4 server. + + In addition to saving the base-time for possible future use in a + query-start-time or query-end-time option, the base-time is used as + part of the conversion of the other times in the Leasequery message + to values that are meaningful in the context of the requestor. These + other time values are specified as a offset (duration) from the base- + time value and not as an absolute time. + + In systems whose clocks are synchronized, perhaps using NTP, the + clock skew will usually be zero. + +7.5. Querying Multiple Servers + + A Bulk Leasequery requestor MAY be configured to attempt to connect + to and query from multiple DHCPv4 servers in parallel. The DHCPv4 + Leasequery specification [RFC4388] includes a discussion about + reconciling binding data received from multiple DHCPv4 servers. + + In addition, the algorithm in Section 7.6 should be used. + +7.6. Making Sense out of Multiple Responses concerning a Single IPv4 + Address + + Any requestor of an Bulk Leasequery MUST be prepared for multiple + responses to arrive for a particular IPv4 address from multiple + different DHCPv4 servers. The following algorithm SHOULD be used to + decide if the information just received is more up to date (i.e., + better) than the best existing information. In the discussion below, + the information that is received from a DHCPv4 server about a + particular IPv4 address is termed a "record". The times used in the + algorithm below SHOULD have been converted into the requestor's + context, and the time comparisons SHOULD be performed in a manner + consistent with the information in Section 7.4. + + + + + +Kinnear, et al. Standards Track [Page 26] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + o If both the existing and the new record contain client-last- + transaction-time information, the record with the later client- + last-transaction-time is considered better. + + o If one of the records contains client-last-transaction-time + information and the other one doesn't, then compare the client- + last-transaction-time in the record that contains it against the + other record's start-time-of-state. The record with the later + time is considered better. + + o If neither record contains client-last-transaction-time + information, compare their start-time-of-state information. The + record with the later start-time-of-state is considered better. + + o If none of the comparisons above yield a clear answer as to which + record is later, then compare the value of the REMOTE flag from + the data-source option for each record. If the values of the + REMOTE flag are different between the two records, the record with + the REMOTE flag value of local is considered better. + + The above algorithm does not necessarily determine which record is + better. In the event that the algorithm is inconclusive with regard + to a record that was just received by the requestor, the requestor + SHOULD use additional information in the two records to make a + determination as to which record is better. + +7.7. Multiple Queries to a Single Server over One Connection + + Bulk Leasequery requestors may need to make multiple queries in order + to recover binding information. A requestor MAY use a single + connection to issue multiple queries to a server willing to support + them. Each query MUST have a unique xid. + + A server SHOULD allow configuration of the number of queries that can + be processed simultaneously over a single connection. A server + SHOULD read the number of queries it is configured to process + simultaneously and only read any subsequent queries as current + queries are processed. + + A server that is processing multiple queries simultaneously MUST NOT + block sending replies on new queries until all replies for the + existing query are complete. Requestors need to be aware that + replies for multiple queries may be interleaved within the stream of + reply messages. Requestors that are not able to process interleaved + replies (based on xid) MUST NOT send more than one query over a + single connection prior to the completion of the previous query. + + + + + +Kinnear, et al. Standards Track [Page 27] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + Requestors should be aware that servers are not required to process + more than one query over a connection at a time (the limiting case + for the configuration described above) and that servers are likely to + limit the rate at which they process queries from any one requestor. + +7.7.1. Example + + This example illustrates what a series of queries and responses might + look like. This is only an example -- there is no requirement that + this sequence must be followed or that requestors or servers must + support parallel queries. + + In the example session, the client sends four queries after + establishing a connection. Query 1 returns no results; query 2 + returns 3 messages, and the stream of replies concludes before the + client issues any new query. Query 3 and query 4 overlap, and the + server interleaves its replies to those two queries. + + Requestor Server + --------- ------ + DHCPBULKLEASEQUERY xid 1 -----> + <----- DHCPLEASEQUERYDONE xid 1 + DHCPBULKLEASEQUERY xid 2 -----> + <----- DHCPLEASEACTIVE xid 2 + <----- DHCPLEASEACTIVE xid 2 + <----- DHCPLEASEACTIVE xid 2 + <----- DHCPLEASEQUERYDONE xid 2 + DHCPBULKLEASEQUERY xid 3 -----> + DHCPBULKLEASEQUERY xid 4 -----> + <----- DHCPLEASEACTIVE xid 4 + <----- DHCPLEASEACTIVE xid 4 + <----- DHCPLEASEACTIVE xid 3 + <----- DHCPLEASEACTIVE xid 4 + <----- DHCPLEASEUNASSIGNED xid 3 + <----- DHCPLEASEACTIVE xid 4 + <----- DHCPLEASEACTIVE xid 3 + <----- DHCPLEASEQUERYDONE xid 3 + <----- DHCPLEASEACTIVE xid 4 + <----- DHCPLEASEQUERYDONE xid 4 + +7.8. Closing Connections + + If a requestor has no additional queries to send, or doesn't know if + it has additional queries to send or not, then it SHOULD close the + connection after receiving the DHCPLEASEQUERYDONE message for the + last outstanding query that it sent. + + + + + +Kinnear, et al. Standards Track [Page 28] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + The requestor SHOULD close connections in a graceful manner and not + an abort. The requestor SHOULD NOT assume that the manner in which + the DHCP server closed a connection carries any special meaning. + + Typically, the requestor is the entity that will close the + connection, as servers will often wait with an open connection in + case the requestor has additional queries. + + If a server closes a connection with an exception condition, the + requestor SHOULD consider as valid any completely received + intermediate results, and the requestor MAY retry the Bulk Leasequery + operation. + +8. Server Behavior + +8.1. Accepting Connections + + Servers that implement DHCPv4 Bulk Leasequery listen for incoming TCP + connections. Port numbers are discussed in Section 6.3. Servers + MUST be able to limit the number of concurrently accepted and active + connections. The value BULK_LQ_MAX_CONNS SHOULD be the default; + implementations MAY permit the value to be configurable. Connections + SHOULD be accepted and, if the number of connections is over + BULK_LQ_MAX_CONNS, they SHOULD be closed immediately. + + Servers MAY restrict Bulk Leasequery connections and + DHCPBULKLEASEQUERY messages to certain requestors. Connections not + from permitted requestors SHOULD be closed immediately to avoid + server connection resource exhaustion. Servers MAY restrict some + requestors to certain query types. Servers MAY reply to queries that + are not permitted with the DHCPLEASEQUERYDONE message with a status- + code option status of NotAllowed or MAY simply close the connection. + + If the TCP connection becomes blocked while the server is accepting a + connection or reading a query, it SHOULD be prepared to terminate the + connection after a BULK_LQ_DATA_TIMEOUT. We make this recommendation + to allow servers to control the period of time they are willing to + wait before abandoning an inactive connection, independent of the TCP + implementations they may be using. + +8.2. Replying to a Bulk Leasequery + + If the connection becomes blocked while the server is attempting to + send reply messages, the server SHOULD be prepared to terminate the + TCP connection after a BULK_LQ_DATA_TIMEOUT. + + + + + + +Kinnear, et al. Standards Track [Page 29] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + Every Bulk Leasequery request MUST be terminated by sending a final + DHCPLEASEQUERYDONE message if such a message can be sent. The + DHCPLEASEQUERYDONE message MUST have a status-code option status if + the termination was other than successful, and SHOULD NOT contain a + status-code option status if the termination was successful. + + If the DHCPv4 server encounters an error during processing of the + DHCPBULKLEASEQUERY message, either during initial processing or later + during the message processing, it SHOULD send a DHCPLEASEQUERYDONE + containing a status-code option. It MAY close the connection after + this error is signaled, but that is not required. + + If the server does not find any bindings satisfying a query, it MUST + send a DHCPLEASEQUERYDONE. It SHOULD NOT include a status-code + option with a Success status unless there is a useful string to + include in the status-code option. Otherwise, the server sends each + binding's data in a DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message. + + The response to a DHCPBULKLEASEQUERY may involve examination of + multiple DHCPv4 IP address bindings maintained by the DHCPv4 server. + The Bulk Leasequery protocol does not require any ordering of the IP + addresses returned in DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED + messages. + + When responding to a DHCPBULKLEASEQUERY message, the DHCPv4 server + MUST NOT send more than one message for each applicable IP address, + even if the state of some of those IP addresses changes during the + processing of the message. Updates to such IP address state are + already handled by normal protocol processing, so no special effort + is needed here. + + If the ciaddr, yiaddr, or siaddr is non-zero in a DHCPBULKLEASEQUERY + request, the request must be terminated immediately by a + DHCPLEASEQUERYDONE message with a status-code option status of + MalformedQuery. + + Any DHCPBULKLEASEQUERY that has more than one of the following + primary query types specified MUST be terminated immediately by a + DHCPLEASEQUERYDONE message with a status-code option status code of + NotAllowed. + + The allowable queries in a DHCPBULKLEASEQUERY message are processed + as follows. Note that the descriptions of the primary queries below + must be constrained by the actions of any of the three qualifiers + described subsequently as well. + + + + + + +Kinnear, et al. Standards Track [Page 30] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + The following table discusses how to process the various queries. + For information on how to identify the query, see the information in + Section 7.2. + + o Query by MAC address + + Every IP address that has a current binding to a DHCPv4 client + matching the chaddr, htype, and hlen in the DHCPBULKLEASEQUERY + request MUST be returned in a DHCPLEASEACTIVE message. + + o Query by Client-identifier + + Every IP address that has a current binding to a DHCPv4 client + matching the Client-identifier option in the DHCPBULKLEASEQUERY + request MUST be returned in a DHCPLEASEACTIVE message. + + o Query by Remote ID + + Every IP address that has a current binding to a DHCPv4 client + matching the Remote ID sub-option of the relay-agent-information + option in the DHCPBULKLEASEQUERY request MUST be returned in a + DHCPLEASEACTIVE message. + + o Query by Relay-ID + + Every IP address that has a current binding to a DHCPv4 client + matching the Relay-ID sub-option of the relay-agent-information + option in the DHCPBULKLEASEQUERY request MUST be returned in a + DHCPLEASEACTIVE message. + + o Query for All Configured IP Addresses + + A Query for All Configured IP addresses is signaled by the absence + of any other primary query. That is, if there is no value in the + chaddr, hlen, htype, no Client-identifier option, and no Remote ID + sub-option or Relay-ID sub-option of the relay-agent-information + option, then the request is a query for information concerning all + configured IP addresses. In this case, every configured IP + address that has a current binding to a DHCPv4 client MUST be + returned in a DHCPLEASEACTIVE message. In addition, every + configured IP address that does not have a current binding to a + DHCPv4 client MUST be returned in a DHCPLEASEUNASSIGNED message. + + In this form of query, each configured IP address MUST be returned + at most one time. In the absence of qualifiers restricting the + number of IP addresses returned, every configured IP address MUST + be returned exactly once. + + + + +Kinnear, et al. Standards Track [Page 31] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + There are three qualifiers that can be applied to any of the above + primary queries. These qualifiers can appear individually or + together in any combination, but only one of each can appear. + + o Query Start Time + + If a query-start-time option appears in the DHCPBULKLEASEQUERY + request, only IP address bindings that have changed on or after + the time specified in the query-start-time option should be + returned. + + o Query End Time + + If a query-end-time option appears in the DHCPBULKLEASEQUERY + request, only IP address bindings that have changed on or before + the time specified in the query-end-time option should be + returned. + + o VPN-ID + + If no VPN-ID option appears in the DHCPBULKLEASEQUERY, the default + (global) VPN is used to satisfy the query. A VPN-ID option + [RFC6607] value other than the wildcard value (254) allows the + requestor to specify a single VPN other than the default VPN. In + addition, the VPN-ID option has been extended as part of this + document to allow specification of a type 254, which indicates + that all configured VPNs be searched in order to satisfy the + primary query. + + In all cases, if the information returned in a DHCPLEASEACTIVE or + DHCPLEASEUNASSIGNED message is for a VPN other than the default + (global) VPN, a VPN-ID option MUST appear in the packet. + + The query-start-time and query-end-time qualifiers are used to + constrain the amount of data returned by a Bulk Leasequery request by + returning only IP addresses whose address bindings have changed in + some way during the time window specified by the query-start-time and + query-end-time. + + A DHCPv4 server SHOULD consider an address binding to have changed + during a specified time window if either the client-last- + transaction-time or the start-time-of-state of the address binding + changed during that time window. + + The DHCPv4 server MAY return address binding data in any order, as + long as binding information for any given IP address is not repeated. + When all binding data for a given DHCPBULKLEASEQUERY has been sent, + the DHCPv4 server MUST send a DHCPBULKLEASEQUERYDONE message. + + + +Kinnear, et al. Standards Track [Page 32] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + +8.3. Building a Single Reply for Bulk Leasequery + + The DHCPv4 Leasequery specification [RFC4388] describes the initial + construction of DHCPLEASEQUERY reply messages using the + DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED message types in Section + 6.4.2. All of the reply messages in Bulk Leasequery are similar to + the reply messages for an IP address query. Message transmission and + framing for TCP are described in this document in Section 6.1. + + [RFC2131] and [RFC4388] specify that every response message MUST + contain the server-identifier option. However, that option will be + the same for every response from a particular DHCPBULKLEASEQUERY + request. Thus, the DHCPv4 server MUST include the server-identifier + option in the first message sent in response to a DHCPBULKLEASEQUERY. + It SHOULD NOT include the server-identifier option in later messages. + + The message type of DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED is based + on the value of the dhcp-state option. If the dhcp-state option + value is ACTIVE, then the message type is DHCPLEASEACTIVE; otherwise, + the message type is DHCPLEASEUNASSIGNED. + + In addition to the basic message construction described in [RFC4388], + the following guidelines exist: + + 1. If the dhcp-state option code appears in the dhcp-parameter- + request-list, the DHCPv4 server SHOULD include a dhcp-state + option whose value corresponds most closely to the state held by + the DHCPv4 server for the IP address associated with this reply. + If the state is ACTIVE and the message being returned is + DHCPLEASEACTIVE, then the DHCPv4 server MAY choose to not send + the dhcp-state option. The requestor SHOULD assume that any + DHCPLEASEACTIVE message arriving without a requested dhcp-state + option has a dhcp-state of ACTIVE. + + 2. If the base-time option code appears in the dhcp-parameter- + request-list, the DHCPv4 server MUST include a base-time option, + which is the current time in the DHCPv4 server's context and the + time from which the start-time-of-state, dhcp-lease-time, client- + last-transaction-time, and other duration-style times are based + upon. + + 3. If the start-time-of-state option code appears in the dhcp- + parameter-request-list, the DHCPv4 server MUST include a start- + time-of-state option whose value represents the time at which the + dhcp-state option's state became valid. + + + + + + +Kinnear, et al. Standards Track [Page 33] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + 4. If the dhcp-lease-time option code appears in the dhcp- + parameter-request-list, the DHCPv4 server MUST include a dhcp- + lease-time option for any state that has a timeout value + associated with it. + + 5. If the data-source option code appears in the dhcp-parameter- + request-list, the DHCPv4 server MUST include the data-source + option in any situation where any of the bits would be non-zero. + Thus, in the absence of the data-source option, the assumption is + that all of the flags are zero. + + 6. If the client-last-transaction-time option code appears in the + dhcp-parameter-request-list, the DHCPv4 server MUST include the + client-last-transaction-time option in any situation where the + information is available. + + 7. If there is a dhcp-parameter-request-list in the initial + DHCPBULKLEASEQUERY request, then it should be used for all of the + replies generated by that request. Some options can be sent from + a DHCPv4 client to the server or from the DHCPv4 server to a + DHCPv4 client. Option 125 is such an option. If the option code + for one of these options appears in the dhcp-parameter-request- + list, it SHOULD result in returning the value of the option sent + by the DHCPv4 client to the server if one exists. + + Note that there may be other requirements for a reply to a + DHCPBULKLEASEQUERY request, as discussed in Section 8.2. + +8.4. Multiple or Parallel Queries + + As discussed in Section 7.3, requestors may want to use a connection + that has already been established when they need to make additional + queries. Servers SHOULD support reading and processing multiple + queries from a single connection and SHOULD allow configuration of + the number of simultaneous queries it may process. A server MUST NOT + read more query messages from a connection than it is prepared to + process simultaneously. + + This SHOULD be a feature that is administratively controlled. + Servers SHOULD offer configuration that limits the number of + simultaneous queries permitted from any one requestor, in order to + control resource use if there are multiple requestors seeking + service. + + + + + + + + +Kinnear, et al. Standards Track [Page 34] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + +8.5. Closing Connections + + The DHCPv4 server SHOULD close connections in a graceful manner and + not abort the connection. The DHCPv4 server SHOULD NOT assume that + the manner in which the requestor closed a connection carries any + special meaning. + + Typically, the DHCPv4 server will only close the connection after + some form of an exception or a timeout on the connection. + + Using a timer to detect when a connection is idle and then closing + that connection is designed to protect the DHCPv4 server from + consuming unnecessary resources. + + The DHCPv4 server should start a timer for BULK_LQ_DATA_TIMEOUT + seconds for a particular connection after it sends a + DHCPLEASEQUERYDONE message over that connection if there is no + current query outstanding for that connection. It should restart + this timer if a query arrives over that connection. If the timer + expires, the DHCPv4 server should close the connection. + + The server MUST close its end of the TCP connection if it encounters + an error sending data on the connection. The server MUST close its + end of the TCP connection if it finds that it has to abort an in- + process request. A server aborting an in-process request SHOULD + attempt to signal that to its requestors by using the QueryTerminated + status code in the status-code option in a DHCPLEASEQUERYDONE + message, including a message string indicating details of the reason + for the abort. If the connection is closed for any reason, all of + the data flows associated with any currently outstanding + DHCPBULKLEASEQUERY messages will be terminated. + + If the server detects that the requesting end of the connection has + been closed, the server MUST close its end of the connection. + +9. Security Considerations + + The Security Considerations section of [RFC2131] details the general + threats to DHCPv4. The DHCPv4 Leasequery specification [RFC4388] + describes recommendations for the Leasequery protocol, especially + with regard to authentication of LEASEQUERY messages, mitigation of + packet-flooding DoS attacks, and restriction to trusted requestors. + + The use of TCP introduces some additional concerns. Attacks that + attempt to exhaust the DHCPv4 server's available TCP connection + resources, such as SYN flooding attacks, can compromise the ability + of legitimate requestors to receive service. Malicious requestors + who succeed in establishing connections but who then send invalid + + + +Kinnear, et al. Standards Track [Page 35] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + queries, partial queries, or no queries at all can also exhaust a + server's pool of available connections. We recommend that servers + offer configuration to limit the sources of incoming connections, + that they limit the number of accepted connections and the number of + in-process queries from any one connection, and that they limit the + period of time during which an idle connection will be left open. + + There are two specific issues regarding Bulk Leasequery security that + deserve explicit mention. The first is preventing information that + Bulk Leasequery can provide from reaching clients who are not + authorized to receive such information. The second is ensuring that + authorized clients of the Bulk Leasequery capability receive accurate + information from the server (and that this information is not + disrupted in transit). + + To prevent information leakage to unauthorized clients, servers + SHOULD restrict Bulk Leasequery connections and DHCPBULKLEASEQUERY + messages to certain requestors, either through explicit configuration + of the server itself or by employing external network elements to + provide such restrictions. In particular, the typical DHCPv4 client + SHOULD NOT be allowed to receive a response to a Bulk Leasequery + request, and some technique MUST exist to allow prevention of such + access in any environment where Bulk Leasequery is deployed. + + Connections not from permitted requestors SHOULD be closed + immediately to avoid server connection resource exhaustion or + alternatively, simply not be allowed to reach the server at all. + Servers SHOULD have the capability to restrict certain requestors to + certain query types. Servers MAY reply to queries that are not + permitted with the DHCPLEASEQUERYDONE message with a status-code + option status of NotAllowed or MAY simply close the connection. + + To prevent disruption and malicious corruption of Bulk Leasequery + data flows between the server and authorized clients, these data + flows SHOULD transit only secured networks. These data flows are + typically infrastructure oriented, and there is usually no reason to + have them flowing over networks where such attacks are likely. In + the rare cases where these data flows might need to be sent through + unsecured networks, they MUST be sent over connections secured + through means external to the DHCPv4/DHCPv6 server and its client(s) + (e.g., through VPNs). + + Authentication for DHCP messages [RFC3118] MUST NOT be used to + attempt to secure transmission of the messages described in this + document. In particular, the message framing would not be protected + by using the mechanisms described in [RFC3118] (which was designed + only with UDP transport in mind). + + + + +Kinnear, et al. Standards Track [Page 36] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + +10. IANA Considerations + + IANA has assigned the following new DHCPv4 option codes from the + registry "BOOTP Vendor Extensions and DHCP Options" maintained at + http://www.iana.org/assignments/bootp-dhcp-parameters. + + 1. An option code of 151 for status-code. + + 2. An option code of 152 for base-time. + + 3. An option code of 153 for start-time-of-state. + + 4. An option code of 154 for query-start-time. + + 5. An option code of 155 for query-end-time. + + 6. An option code of 156 for dhcp-state. + + 7. An option code of 157 for data-source. + + IANA has assigned the following new DHCP message types from the + registry "DHCP Message Type 53 Values" maintained at + http://www.iana.org/assignments/bootp-dhcp-parameters. + + 1. A dhcp-message-type of 14 for DHCPBULKLEASEQUERY. + + 2. A dhcp-message-type of 15 for DHCPLEASEQUERYDONE. + + IANA has created a new registry on the same assignments page, titled + "DHCP State 156 Values" (where 156 corresponds to the assigned value + of the dhcp-state option above). This registry has the following + initial values: + + State + ----- + 1 AVAILABLE + 2 ACTIVE + 3 EXPIRED + 4 RELEASED + 5 ABANDONED + 6 RESET + 7 REMOTE + 8 TRANSITIONING + + New values for this namespace may only be defined by IETF Review, as + described in [RFC5226]. + + + + + +Kinnear, et al. Standards Track [Page 37] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + IANA has created a new registry on the same assignments page, titled + "DHCP Status Code 151 Values" (where 151 corresponds to the assigned + value of the status-code option above). This registry has the + following initial values: + + Name status-code + ---- ----------- + Success 000 + UnspecFail 001 + QueryTerminated 002 + MalformedQuery 003 + NotAllowed 004 + + New values for this namespace may only be defined by IETF Review, as + described in [RFC5226]. + + IANA has revised the registry "VSS Type Options" created by [RFC6607] + in the overall area "Dynamic Host Configuration Protocol (DHCP) and + Bootstrap Protocol (BOOTP) Parameters". It has been revised to + appear as follows. Note that the number range for "Unassigned" has + changed, and a new line for "All VPNs (wildcard)" was added. + + Type VSS Information Format + ------------------------------------------------------------ + 0 Network Virtual Terminal (NVT) ASCII VPN identifier + 1 RFC 2685 VPN-ID + 2-253 Unassigned + 254 All VPNs (wildcard) + 255 Global, default VPN + +11. Acknowledgements + + Significant text as well as important ideas were borrowed in whole or + in part from "DHCPv6 Bulk Leasequery" [RFC5460], written by Mark + Stapp. Further suggestions and improvements were made by + participants in the DHC Working Group, including Alfred Hoenes. + +12. References + +12.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, March 1997. + + [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", RFC + 2131, March 1997. + + + + + +Kinnear, et al. Standards Track [Page 38] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + [RFC2132] Alexander, S. and R. Droms, "DHCP Options and BOOTP Vendor + Extensions", RFC 2132, March 1997. + + [RFC3046] Patrick, M., "DHCP Relay Agent Information Option", RFC + 3046, January 2001. + + [RFC3118] Droms, R., Ed., and W. Arbaugh, Ed., "Authentication for + DHCP Messages", RFC 3118, June 2001. + + [RFC4388] Woundy, R. and K. Kinnear, "Dynamic Host Configuration + Protocol (DHCP) Leasequery", RFC 4388, February 2006. + + [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an + IANA Considerations Section in RFCs", BCP 26, RFC 5226, + May 2008. + + [RFC5735] Cotton, M. and L. Vegoda, "Special Use IPv4 Addresses", + BCP 153, RFC 5735, January 2010. + + [RFC6607] Kinnear, K., Johnson, R., and M. Stapp, "Virtual Subnet + Selection Options for DHCPv4 and DHCPv6", RFC 6607, April + 2012. + + [RFC6925] Joshi, B., Desetti, R., and M. Stapp, "The DHCPv4 Relay + Agent Identifier Sub-Option", RFC 6925, April 2013. + +12.2. Informative References + + [RFC951] Croft, W. and J. Gilmore, "Bootstrap Protocol", RFC 951, + September 1985. + + [RFC1542] Wimer, W., "Clarifications and Extensions for the + Bootstrap Protocol", RFC 1542, October 1993. + + [RFC4614] Duke, M., Braden, R., Eddy, W., and E. Blanton, "A Roadmap + for Transmission Control Protocol (TCP) Specification + Documents", RFC 4614, September 2006. + + [RFC5460] Stapp, M., "DHCPv6 Bulk Leasequery", RFC 5460, February + 2009. + + + + + + + + + + + +Kinnear, et al. Standards Track [Page 39] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + +Authors' Addresses + + Kim Kinnear + Cisco Systems, Inc. + 1414 Massachusetts Ave. + Boxborough, Massachusetts 01719 + USA + + Phone: (978) 936-0000 + EMail: kkinnear@cisco.com + + + Mark Stapp + Cisco Systems, Inc. + 1414 Massachusetts Ave. + Boxborough, Massachusetts 01719 + USA + + Phone: (978) 936-0000 + EMail: mjs@cisco.com + + + D.T.V Ramakrishna Rao + Infosys Ltd. + 44 Electronics City, Hosur Road + Bangalore 560 100 + India + + EMail: ramakrishnadtv@infosys.com + URI: http://www.infosys.com/ + + + Bharat Joshi + Infosys Ltd. + 44 Electronics City, Hosur Road + Bangalore 560 100 + India + + EMail: bharat_joshi@infosys.com + URI: http://www.infosys.com/ + + + Neil Russell + Sea Street Technologies Inc. + + EMail: neil.e.russell@gmail.com + + + + + +Kinnear, et al. Standards Track [Page 40] + +RFC 6926 DHCPv4 Bulk Leasequery April 2013 + + + Pavan Kurapati + Juniper Networks + 1194 N. Mathilda Ave. + Sunnyvale, CA 94089 + USA + + EMail: kurapati@juniper.net + URI: http://www.juniper.net/ + + + Bernie Volz + Cisco Systems, Inc. + 1414 Massachusetts Ave. + Boxborough, Massachusetts 01719 + USA + + Phone: (978) 936-0000 + EMail: volz@cisco.com + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Kinnear, et al. Standards Track [Page 41] + diff --git a/docs/rfc7724.txt b/docs/rfc7724.txt new file mode 100644 index 0000000..76bc4a1 --- /dev/null +++ b/docs/rfc7724.txt @@ -0,0 +1,1571 @@ + + + + + + +Internet Engineering Task Force (IETF) K. Kinnear +Request for Comments: 7724 M. Stapp +Updates: 6926 B. Volz +Category: Standards Track Cisco Systems +ISSN: 2070-1721 N. Russell + Staples + December 2015 + + + Active DHCPv4 Lease Query + +Abstract + + The Dynamic Host Configuration Protocol for IPv4 (DHCPv4) has been + extended with a Leasequery capability that allows a requestor to + request information about DHCPv4 bindings (RFC 4388). That mechanism + is limited to queries for individual bindings. In some situations, + individual binding queries may not be efficient, or even possible. + In addition, continuous update of an external requestor with + Leasequery data is sometimes desired. This document expands on the + DHCPv4 Leasequery protocol, and allows for active transfer of near + real-time DHCPv4 binding information data via TCP. This document + updates RFC 6926, "DHCPv4 Bulk Leasequery". + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 5741. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + http://www.rfc-editor.org/info/rfc7724. + + + + + + + + + + + + + + +Kinnear, et al. Standards Track [Page 1] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + +Copyright Notice + + Copyright (c) 2015 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (http://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Simplified BSD License text as described in Section 4.e of + the Trust Legal Provisions and are provided without warranty as + described in the Simplified BSD License. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Kinnear, et al. Standards Track [Page 2] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + +Table of Contents + + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 6 + 4. Interaction Between Active Leasequery and Bulk Leasequery . . 8 + 5. Message and Option Definitions . . . . . . . . . . . . . . . 9 + 5.1. Message Framing for TCP . . . . . . . . . . . . . . . . . 9 + 5.2. New or Changed Options . . . . . . . . . . . . . . . . . 9 + 5.2.1. dhcp-message-type . . . . . . . . . . . . . . . . . . 10 + 5.2.2. dhcp-status-code . . . . . . . . . . . . . . . . . . 10 + 5.3. Connection and Transmission Parameters . . . . . . . . . 11 + 6. Information Communicated by Active Leasequery . . . . . . . . 11 + 7. Requestor Behavior . . . . . . . . . . . . . . . . . . . . . 12 + 7.1. General Processing . . . . . . . . . . . . . . . . . . . 12 + 7.2. Initiating a Connection . . . . . . . . . . . . . . . . . 13 + 7.3. Forming an Active Leasequery . . . . . . . . . . . . . . 14 + 7.4. Processing Active Replies . . . . . . . . . . . . . . . . 15 + 7.4.1. Processing Replies from a Request Containing a + query-start-time . . . . . . . . . . . . . . . . . . 17 + 7.5. Closing Connections . . . . . . . . . . . . . . . . . . . 19 + 8. Server Behavior . . . . . . . . . . . . . . . . . . . . . . . 19 + 8.1. Accepting Connections . . . . . . . . . . . . . . . . . . 19 + 8.1.1. Update to RFC 6926 . . . . . . . . . . . . . . . . . 21 + 8.2. Replying to an Active Leasequery . . . . . . . . . . . . 21 + 8.3. Multiple or Parallel Queries . . . . . . . . . . . . . . 23 + 8.4. Closing Connections . . . . . . . . . . . . . . . . . . . 24 + 9. Security Considerations . . . . . . . . . . . . . . . . . . . 24 + 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 + 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 26 + 11.1. Normative References . . . . . . . . . . . . . . . . . . 26 + 11.2. Informative References . . . . . . . . . . . . . . . . . 27 + Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 27 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 28 + +1. Introduction + + The DHCPv4 Leasequery capability [RFC4388] extends the basic DHCPv4 + capability [RFC2131] [RFC2132] to allow an external entity to query a + DHCPv4 server to recover lease state information about a particular + IPv4 address or client in near real-time. + + Continuous update of an external requestor with Leasequery data is + sometimes desired. These requestors need to keep up with the current + binding activity of the DHCPv4 server. Keeping up with these binding + activities is termed "active" leasequery. + + + + + +Kinnear, et al. Standards Track [Page 3] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + The DHCPv4 Bulk Leasequery [RFC6926] capability can be used to + recover useful information from a DHCPv4 server when some external + entity starts up. This entity could be one that is directly involved + in the DHCPv4 client-server transactions (e.g., a relay agent), or it + could be an external process that needs information present in the + DHCPv4 server's lease state database. + + The Active Leasequery capability documented here is designed to allow + an entity not directly involved in DHCPv4 client-server transactions + to nevertheless keep current with the state of the DHCPv4 lease state + information in real-time. + + This document updates DHCPv4 Bulk Leasequery [RFC6926] in that it + specifies the DHCPv4 server must close the TCP connection if it + receives a DHCPv4 message that is not allowed over the TCP connection + (for example, DHCPDISCOVER, DHCPLEASEQUERY). See Section 8.1.1. + +2. Terminology + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this + document are to be interpreted as described in [RFC2119]. + + This document uses the following terms: + + o "Active Leasequery" + + Keeping up to date in real-time (or near real-time) with DHCPv4 + binding activity. + + o "binding" + + The information that a DHCPv4 server keeps regarding the + relationship between a DHCPv4 client and an IPv4 address. This + includes the identity of the DHCPv4 client and the expiration + time, if any, of any lease that client has on a particular IPv4 + address. + + o "Bulk Leasequery" + + Requesting and receiving the information about all or some of the + existing DHCPv4 binding information in an efficient manner, as + defined by [RFC6926]. + + + + + + + + +Kinnear, et al. Standards Track [Page 4] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + o "blocked TCP connection" + + A TCP connection is considered blocked if the underlying TCP + transport will not accept new messages to be sent without blocking + the thread that is attempting to send the message. + + o "catch-up information" + + If a DHCPv4 Active Leasequery requestor sends in a query-start- + time option in a DHCPACTIVELEASEQUERY message, the DHCPv4 server + will attempt to send the requestor the information that changed + since the time specified in the query-start-time option. The + binding information sent to satisfy this request is the catch-up + information. + + o "catch-up phase" + + The period while the catch-up information is being sent is the + catch-up phase. + + o "clock skew" + + The difference between the absolute time on a DHCPv4 server and + the absolute time on the system where a requestor of an Active or + Bulk Leasequery is executing is termed the "clock skew" for that + Active or Bulk Leasequery connection. It is not absolutely + constant but is likely to vary only slowly. While it is easy to + think that this can be calculated precisely after one packet is + received by a requestor from a DHCPv4 server, a more accurate + value is derived from continuously examining the instantaneous + value developed from each packet received from a DHCPv4 server and + using it to make small adjustments to the existing value held in + the requestor. + + o "DHCPv4 client" + + A DHCPv4 client is an IPv4 node using DHCP to obtain configuration + parameters such as a network address. + + o "DHCPv4 relay agent" + + A DHCPv4 relay agent is a third-party agent that transfers BOOTP + and DHCPv4 messages between clients and servers residing on + different subnets, per [RFC951] and [RFC1542]. + + + + + + + +Kinnear, et al. Standards Track [Page 5] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + o "DHCPv4 server" + + A DHCPv4 server is an IPv4 node that returns configuration + parameters to DHCPv4 clients. + + o "insecure mode" + + When operating in insecure mode, the TCP connection between the + requestor and DHCPv4 server is not protected in any way. In + addition, the identity of the requestor is not validated by the + server nor is the identity of the server validated by the + requestor. + + o "MAC address" + + In the context of a DHCP message, a Media Access Control (MAC) + address consists of the fields: hardware type "htype", hardware + length "hlen", and client hardware address "chaddr". + + o "requestor" + + The node that sends LEASEQUERY messages to one or more servers to + retrieve information on the bindings for a client. + + o "secure mode" + + When operating in secure mode, the TCP connection between the + requestor and the DHCPv4 server is protected by TLS [RFC5246]. In + addition, the requestor uses the certificates exchanged between it + and the DHCPv4 server while setting up the TLS connection to + validate the identity of the server. The DHCPv4 server also uses + these certificates to validate the identity of the requestor. + +3. Protocol Overview + + The Active Leasequery mechanism is modeled on the existing individual + Leasequery protocol in [RFC4388] as well as related work on DHCPv4 + Bulk Leasequery [RFC6926]; most differences arise from the long-term + nature of the TCP [RFC7414] connection required for Active + Leasequery. In addition, a DHCPv4 server that supports Active + Leasequery must support Bulk Leasequery [RFC6926] as well. See + Section 8. + + An Active Leasequery requestor opens a TCP connection to a DHCPv4 + Server, using the DHCPv4 port 67. Note that this implies that the + Leasequery requestor has the server IPv4 address(es) available via + configuration or some other means, and that it has unicast IP + + + + +Kinnear, et al. Standards Track [Page 6] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + reachability to the DHCPv4 server. The message framing for TCP is + discussed in Section 5.1. No relaying for Active Leasequery is + specified. + + After establishing a connection, the requestor sends an + DHCPACTIVELEASEQUERY message over the connection. In response, the + server sends updates to the requestor using DHCPLEASEACTIVE and + DHCPLEASEUNASSIGNED messages that are extensions of these messages as + defined in [RFC4388] and [RFC6926]. This response procedure is + similar to the procedure specified in [RFC6926], except that in the + case of Active Leasequery the server sends updates whenever some + activity occurs to change the binding state -- thus the need for the + long-lived connection. Additionally, the Active Leasequery server + should provide a mechanism to control which data is allowed to be + included in the messages sent to the requestor. See Section 8.2. + + Since [RFC6926] did not specify what to do with an unknown message + type received over the DHCP TCP connection, system administrators + SHOULD NOT allow a DHCPACTIVELEASEQUERY message to be sent over a + DHCP TCP connection to a DHCPv4 server that does not support Active + Leasequery. + + Active Leasequery is designed to provide continuous updates of DHCPv4 + binding activity to an external entity. + + Active Leasequery has features that allow this external entity to + lose its connection and then reconnect and receive the latest + information concerning any IPv4 bindings changed while it was not + connected. + + These capabilities are designed to allow the Active Leasequery + requestor to efficiently become current with respect to the lease + state database after it has been restarted or the machine on which it + is running has been reinitialized. It is easy to define a protocol + that works when the requestor is always connected to the DHCPv4 + server. Since that isn't sufficiently robust, much of the mechanism + in this document is designed to deal efficiently with situations that + occur when the Active Leasequery requestor becomes disconnected from + the DHCPv4 server from which it is receiving updates and then becomes + reconnected to that server. + + Central to this approach is the concept that, if the Active + Leasequery requestor loses service, it is allowed to specify the time + of its most recent update in a subsequent Active Leasequery request, + and the DHCPv4 server will determine whether or not data was missed + while the Active Leasequery requestor was not connected. + + + + + +Kinnear, et al. Standards Track [Page 7] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + The DHCP server processing the Active Leasequery request MAY limit + the amount of data saved, and methods exist for the DHCPv4 server to + inform the Active Leasequery requestor that more data was missed than + could be saved. In this situation, the Active Leasequery requestor + would issue a Bulk Leasequery [RFC6926] to recover information not + available through an Active Leasequery. + + DHCPv4 servers are not required to keep any data corresponding to + data missed on an Active Leasequery connection, but will typically + choose to keep data corresponding to some recent activity available + for subsequent queries by a DHCPv4 Active Leasequery requestor whose + connection was temporarily interrupted. + + An Active Leasequery requestor would typically use Bulk Leasequery to + initialize its database with all current data when that database + contains no binding information. In addition, it would use Bulk + Leasequery to recover missed information in the event that its + connection with the DHCPv4 server was lost for a longer time than the + DHCPv4 server would keep track of the specific changes to the IPv4 + binding information. + + The messages sent by the server in response to an Active Leasequery + request should be identical to the messages sent by the server to a + Bulk Leasequery request regarding the way the data is encoded into + the Active Leasequery responses. In addition, the actions taken by + the Active Leasequery requestor to interpret the responses to an + Active Leasequery request should be identical to the way that the + requestor interprets the responses to a Bulk Leasequery request. + Thus, the handling of time, clock skew, data source, and other items + discussed in the Bulk Leasequery specification [RFC6926] are to be + followed when implementing Active Leasequery, with the exception that + a server responding to an Active Leasequery request SHOULD be able to + be configured to prevent specific data items from being included in + the response to the requestor even if they were requested by + inclusion in the dhcp-parameter-request-list option. + +4. Interaction between Active Leasequery and Bulk Leasequery + + Active Leasequery is an extension of the Bulk Leasequery protocol + [RFC6926]. The contents of messages returned to an Active Leasequery + requestor are identical to those defined for the Bulk Leasequery + protocol. + + Applications that employ Active Leasequery to keep a database up to + date with respect to the DHCPv4 server's lease state database should + use an initial Bulk Leasequery to bring their database into + + + + + +Kinnear, et al. Standards Track [Page 8] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + equivalence with that of the DHCPv4 server, and then use Active + Leasequery to keep that database current with respect to the DHCPv4 + server's lease state database. + + There are several differences between the Active and Bulk Leasequery + protocols. Active Leasequery defines only one qualifier (the query- + start-time) and no query types, while Bulk Leasequery defines several + query types and qualifiers. An Active Leasequery connection sends + all available updates to the requestor. + + An Active Leasequery connection does not ever "complete", though the + DHCPv4 server can close the connection for a variety of reasons + associated with some sort of exception condition. + +5. Message and Option Definitions + +5.1. Message Framing for TCP + + The use of TCP for the Active Leasequery protocol permits one or more + DHCPv4 messages to be sent in response to a single Active Leasequery + request. The receiver needs to be able to determine how large each + message is. The same framing technique used for Bulk Leasequery + [RFC6926] is used for Active Leasequery. + + When using TLS to secure a connection [RFC5246], the message framing + for TLS uses the same format as that used for TCP. One DHCP message + is carried in one TLS record. + +5.2. New or Changed Options + + The existing messages DHCPLEASEUNASSIGNED and DHCPLEASEACTIVE are + used as the value of the dhcp-message-type option to indicate an IPv4 + address that is currently not leased or is currently leased to a + DHCPv4 client, respectively. + + All of the message types and options defined for Bulk Leasequery + [RFC6926] are also used by Active Leasequery. In addition, new + message types and option types are defined for Active Leasequery, as + described below. + + + + + + + + + + + + +Kinnear, et al. Standards Track [Page 9] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + +5.2.1. dhcp-message-type + + The message type option (option 53) from [RFC2132] requires + additional values. The values of these message types are shown below + in an extension of the table from Section 9.6 of [RFC2132]: + + +-------+----------------------+ + | Value | Message Type | + +-------+----------------------+ + | 16 | DHCPACTIVELEASEQUERY | + | 17 | DHCPLEASEQUERYSTATUS | + | 18 | DHCPTLS | + +-------+----------------------+ + +5.2.2. dhcp-status-code + + The dhcp-status-code option defined in [RFC6926] allows greater + detail to be returned regarding the status of a DHCP request. While + specified in the Bulk Leasequery document, this DHCPv4 option is also + used in Active Leasequery. + + This option has two possible scopes when used with Active Leasequery, + depending on the context in which it appears. It refers to the + information in a single leasequery reply if the value of the dhcp- + message-type is DHCPLEASEACTIVE, DHCPLEASEUNASSIGNED, or DHCPTLS. It + refers to the message stream related to an entire request if the + value of the dhcp-message-type is DHCPLEASEQUERYSTATUS. + + Additional status codes defined for support of Active Leasequery are: + + +----------------------+-------------+------------------------------+ + | Name | Status-Code | Description | + +----------------------+-------------+------------------------------+ + | DataMissing | 5 | Indicates that IPv4 binding | + | | | information requested is not | + | | | available. | + | ConnectionActive | 6 | Indicates that this | + | | | connection remains active. | + | CatchUpComplete | 7 | Indicates that this Active | + | | | Leasequery connection has | + | | | completed sending all of the | + | | | saved data requested. | + | TLSConnectionRefused | 8 | Indicates that a TLS | + | | | connection is not allowed. | + +----------------------+-------------+------------------------------+ + + + + + + +Kinnear, et al. Standards Track [Page 10] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + A dhcp-status-code option MAY appear in the options field of a DHCP + message. If the dhcp-status-code option does not appear, it is + assumed that the operation was successful. The dhcp-status-code + option SHOULD NOT appear in a message that is successful unless it is + needed to convey some text message along with the Success status + code. + +5.3. Connection and Transmission Parameters + + Active Leasequery uses the same port configuration as DHCPv4 Bulk + Leasequery [RFC6926]. It also uses other transmission parameters + (BULK_LQ_DATA_TIMEOUT and BULK_LQ_MAX_CONNS) as defined in [RFC6926]. + + This section presents a table of values used to control Active + Leasequery behavior, including recommended defaults. Implementations + MAY make these values configurable. However, configuring too-small + timeout values may lead to harmful behavior both to this application + as well as to other traffic in the network. As a result, timeout + values smaller than the default values SHOULD NOT be used. + + +------------------------+---------+-------------------------------+ + | Parameter | Default | Description | + +------------------------+---------+-------------------------------+ + | ACTIVE_LQ_RCV_TIMEOUT | 120 s | Active Leasequery receive | + | | | timeout | + | ACTIVE_LQ_SEND_TIMEOUT | 120 s | Active Leasequery send | + | | | timeout | + | ACTIVE_LQ_IDLE_TIMEOUT | 60 s | Active Leasequery idle | + | | | timeout | + +------------------------+---------+-------------------------------+ + +6. Information Communicated by Active Leasequery + + While the information communicated by a Bulk Leasequery [RFC6926] is + taken directly from the DHCPv4 server's lease state database, the + information communicated by an Active Leasequery is real-time + information. As such, it is the information that is currently + associated with a particular binding in the DHCPv4 server's lease + state database. + + This is of significance, because if the Active Leasequery requestor + runs slowly or the requestor disconnects from the DHCPv4 server and + then reconnects with a query-start-time (signaling a catch-up + operation), the information communicated to the Active Leasequery + requestor is only the most current information from the DHCPv4 + server's lease state database. + + + + + +Kinnear, et al. Standards Track [Page 11] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + The requestor of an Active Leasequery MUST NOT assume that every + lease state change is communicated across an Active Leasequery + connection. Even if the Active Leasequery requestor remains + connected, the DHCPv4 server is only required to transmit information + about a binding that is current when the packet is created and handed + off to the TCP stack to send to the requestor. + + If the TCP connection blocks and the DHCPv4 server is waiting to send + information down the connection, when the connection becomes + available to be written, the DHCPv4 server MAY create the packet to + send at this time. The current state of the binding will be sent, + and any transition in state or other information that occurred while + the TCP connection was blocked will be lost. + + Thus, the Active Leasequery protocol does not allow the requestor to + build a complete history of every activity on every lease. An + effective history of the important state changes for a lease can be + created if the parameters of the DHCPv4 server are tuned to take into + account the requirements of an Active Leasequery requestor. For + instance, the period after the expiration or release of a binding + could be configured long enough (say, several minutes, well more than + the receive timeout), so that an Active Leasequery requestor would + never miss any changes in the binding. + +7. Requestor Behavior + +7.1. General Processing + + A requestor attempts to establish a TCP connection to a DHCPv4 server + in order to initiate a Leasequery exchange. If the attempt fails, + the Requestor MAY retry. Retries should not be more frequent than + one every ACTIVE_LQ_IDLE_TIMEOUT. See Section 5.3. + + If an Active Leasequery is terminated prematurely by a + DHCPLEASEQUERYDONE with a dhcp-message status-code of QueryTerminated + or by the failure of the connection over which it was being + submitted, the requestor MAY retry the request after the creation of + a new connection. Retries should not be more frequent than one every + ACTIVE_LQ_IDLE_TIMEOUT. See Section 5.3. + + Messages from the DHCPv4 server come as multiple responses to a + single DHCPACTIVELEASEQUERY message. Thus, each DHCPACTIVELEASEQUERY + or DHCPBULKLEASEQUERY request must have an xid (transaction-id) + unique on the connection on which it is sent (see Section 7.3), and + all of the messages that come as a response to it contain the same + xid as the request. + + + + + +Kinnear, et al. Standards Track [Page 12] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + Only one DHCPACTIVELEASEQUERY is allowed on any one TCP connection at + a time. Parallel DHCPACTIVELEASEQUERY requests on the same TCP + connection are not allowed. + +7.2. Initiating a Connection + + A requestor SHOULD be able to operate in either insecure or secure + mode. See Section 9. This MAY be a feature that is administratively + controlled. + + When operating in insecure mode, the requestor sends a + DHCPACTIVELEASEQUERY request after the establishment of a TCP + connection. + + When operating in secure mode, the requestor MUST attempt to + negotiate a TLS [RFC5246] connection over the TCP connection. If + this negotiation fails, the requestor MUST close the TCP connection. + The recommendations in [RFC7525] apply when negotiating this + connection. + + A requestor requests the establishment of a TLS connection by sending + the DHCPTLS message to the DHCPv4 server as the first message over + the TCP connection. The DHCPTLS message SHOULD be sent without any + options. This message indicates to the DHCPv4 server that a TLS + connection over this TCP connection is desired. There are four + possibilities after the requestor sends the DHCPTLS message to the + DHCPV4 server: + + 1. No response from the DHCPv4 server. + + 2. The DHCPv4 server closes the TCP connection after it receives the + DHCPTLS message. + + 3. DHCPv4 server responds with a DHCPTLS message with a dhcp-status- + code of TLSConnectionRefused. + + 4. DHCPv4 server responds with DHCPTLS message with no dhcp-status- + code, indicating success. + + In any of the first three possibilities, the DHCPv4 server can be + assumed to not support TLS. In this case, the requestor MUST close + the connection. + + In the final possibility, where the DHCPv4 server has responded with + a DHCPTLS message with no dhcp-status-code in response to the + requestor's DHCPTLS message, the requestor SHOULD initiate the + exchange of the messages involved in a TLS handshake [RFC5246]. + + + + +Kinnear, et al. Standards Track [Page 13] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + During the TLS handshake, the requestor MUST validate the DHCPv4 + server's digital certificates. + + If the handshake exchange yields a functioning TLS connection, then + the requestor SHOULD transmit a DHCPACTIVELEASEQUERY message over + that TLS connection and use that TLS connection for all further + interactions in which it engages with the DHCPv4 server over this TCP + connection. + + If the handshake exchange does not yield a functioning TLS + connection, then the requestor MUST close the TCP connection. + +7.3. Forming an Active Leasequery + + The Active Leasequery is designed to create a long-lived connection + between the requestor and the DHCPv4 server processing the active + query. The DHCPv4 server SHOULD send binding information back across + this connection with minimal delay after it learns of the binding + information. It will learn about the bindings either because it + makes the bindings itself or because it has received information + about a binding from another server. + + An Active Leasequery is a DHCPv4 request with a dhcp-message-type of + DHCPACTIVELEASEQUERY. The DHCPv4 request MUST NOT have a ciaddr, a + chaddr, or a dhcp-client-identifier. The DHCPv4 request MUST have an + xid (transaction-id) unique on the connection on which it is sent. + The DHCPv4 request SHOULD have a dhcp-parameter-request-list to + inform the DHCPv4 server which DHCPv4 options are of interest to the + requestor sending the DHCPACTIVELEASEQUERY message. + + An important capability of the Active Leasequery is that the + requestor can specify that some recent data be sent immediately to + the requestor in parallel with the transmission of the ongoing + binding information in more or less real time. This capability is + used in order to allow an Active Leasequery requestor to recover + missed information in the event that it temporarily loses + connectivity with the DHCPv4 server processing a previous Active + Leasequery. + + This capability is enabled by the transmission of a 4-octet base-time + option with each Leasequery reply sent as the result of a previous + Active Leasequery. The requestor SHOULD keep track of the highest + base-time received from a particular DHCPv4 server over an Active + Leasequery connection, and in the event that the requestor finds it + necessary (for whatever reason) to reestablish an Active Leasequery + connection to that DHCPv4 server, the requestor should place this + + + + + +Kinnear, et al. Standards Track [Page 14] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + highest base-time value into a query-start-time option in the new + DHCPACTIVELEASEQUERY request. (See Sections 6.2.5 and 7.2 of + [RFC6926] for information on the query-start-time option.) + + Note that until all of the recent data (catch-up data) has been + received, the requestor MUST NOT keep track of the base-time received + in Leasequery reply messages to use later in a subsequent Bulk + Leasequery or Active Leasequery request. + + If the requestor doesn't wish to request an update of information + missed when it was not connected to the DHCPv4 server, then it does + not include the query-start-time option in the DHCPACTIVELEASEQUERY + request. + + If the TCP connection becomes blocked or stops being writable while + the requestor is sending its query, the requestor SHOULD terminate + the connection after BULK_LQ_DATA_TIMEOUT. We make this + recommendation to allow requestors to control the period of time they + are willing to wait before abandoning a connection, independent of + notifications from the TCP implementations they may be using. + +7.4. Processing Active Replies + + The Requestor attempts to read a DHCPv4 leasequery reply message from + the TCP connection. + + Note that the connection resulting from accepting a + DHCPACTIVELEASEQUERY request may be long-lived and may not have data + transferring continuously during its lifetime. Therefore, the DHCPv4 + server SHOULD send a DHCPLEASEQUERYSTATUS message with a dhcp-status- + code of ConnectionActive every ACTIVE_LQ_IDLE_TIMEOUT seconds + (default 60) in order for the requestor to know that the connection + remains alive. This approach is followed only when the connection is + idle (i.e., the server has no binding data to send). During normal + binding data exchange, receiving DHCPLEASEACTIVE or + DHCPLEASEUNASSIGNED messages by the requestor itself signifies that + the connection is active. Note that the default for + ACTIVE_LQ_RCV_TIMEOUT is 120 seconds, twice the value of the + ACTIVE_LQ_IDLE_TIMEOUT's default of 60 seconds, which drives the + DHCPv4 server to send messages. Thus, ACTIVE_LQ_RCV_TIMEOUT controls + how sensitive the requestor is to be to delays by the DHCPv4 server + in sending updates or DHCPLEASEQUERYSTATUS messages. + + If the stream of replies becomes blocked with no messages being + received, the Requestor SHOULD terminate the connection after + ACTIVE_LQ_RCV_TIMEOUT, and MAY begin retry processing if configured + to do so. + + + + +Kinnear, et al. Standards Track [Page 15] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + A successful query that is returning binding data MUST include a non- + zero ciaddr. It may also include a non-zero chaddr, htype, and hlen + as well as additional options. If there are additional bindings to + be returned, they will be carried in additional Active Leasequery + messages. + + Any requestor of an Active Leasequery operation MUST be prepared to + receive multiple copies of the binding information for a particular + IPv4 address. See the Bulk Leasequery document [RFC6926] for + information on how to deal with this situation. + + A single Active Leasequery can and usually will result in a large + number of replies. The Requestor MUST be prepared to receive more + than one reply with transaction-ids matching a single + DHCPACTIVELEASEQUERY message from a single DHCPv4 server. + + A DHCPACTIVELEASEQUERY has two regimes -- during the catch-up phase, + if any, and after any catch-up phase. If the DHCPACTIVELASEQUERY + request had a query-start-time, then the DHCPACTIVELEASEQUERY starts + out in the catch-up phase. See Section 7.4.1 for information on + processing during the catch-up phase, as well as how to determine + when the catch-up phase is complete. + + After the catch-up phase, or during the entire series of messages + received as the response to a DHCPACTIVELEASEQUERY request with no + query-start-time (and therefore no catch-up phase), the base-time + option of the most recent message SHOULD be saved as a record of the + most recent time that data was received. This base-time (in the + context of the DHCPv4 server) can be used in a subsequent + DHCPACTIVELEASEQUERY message's query-start-time or in a + DHCPBULKLEASEQUERY message's query-start-time, if one is required, + after a loss of the Active Leasequery connection. + + The DHCPLEASEQUERYSTATUS message MAY unilaterally terminate a + successful DHCPACTIVELEASEQUERY request that is currently in progress + in the event that the DHCPv4 server determines that it cannot + continue processing a DHCPACTIVELEASEQUERY request. For example, + when a server is requested to shut down, it SHOULD send a + DHCPLEASEQUERYSTATUS message with a dhcp-status-code of + QueryTerminated and include in the message a base-time. This MUST be + the last message on that connection, and once the message has been + transmitted, the server MUST close the connection. + + After receiving DHCPLEASEQUERYSTATUS with a QueryTerminated status + from a server, the Requestor MAY close the TCP connection to that + server. + + + + + +Kinnear, et al. Standards Track [Page 16] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + The DHCPv4 Leasequery protocol uses the associated-ip option as an + indicator that multiple bindings were present in response to a single + client-based query. For Active Leasequery, client-based queries are + not supported, and so the associated-ip option is not used and MUST + NOT be present in replies. + +7.4.1. Processing Replies from a Request Containing a query-start-time + + If the DHCPACTIVELEASEQUERY was requested with a query-start-time, + the DHCPv4 server will attempt to send information about all bindings + that changed since the time specified in the query-start-time. This + is the catch-up phase of the DHCPACTIVELEASEQUERY processing. The + DHCPv4 server MAY also begin immediate updates over the same + connection of real-time binding information changes. Thus, the + catch-up phase can run in parallel with the normal updates generated + by the DHCPACTIVELEASEQUERY request. + + A DHCPv4 server MAY keep only a limited amount of time-ordered + information available to respond to a DHCPACTIVELEASEQUERY request + containing a query-start-time. Thus, it is possible that the time + specified in the query-start-time represents a time not covered by + the time-ordered information kept by the DHCPv4 server. In such + case, when there is not enough data saved in the DHCPv4 server to + satisfy the request specified by the query-start-time option, the + DHCPv4 server will reply immediately with a DHCPLEASEQUERYSTATUS + message with a dhcp-status-code of DataMissing with a base-time + option equal to the server's current time. This will signal the end + of the catch-up phase, and the only updates that will subsequently be + received on this connection are the real-time updates from the + DHCPACTIVELEASEQUERY request. + + If there is enough data saved to satisfy the request, then + DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED messages will begin arrive + from the DHCPv4 server. Some of these messages will be related to + the query-start-time request and be part of the catch-up phase. Some + of these messages will be real-time updates of binding changes taking + place in the DHCPv4 server. In general, there is no way to determine + the source of each message. + + The updates sent by the DHCPv4 server during the catch-up phase are + not in the order that the binding data was updated. Therefore, until + the catch-up phase is complete, the latest base-time value received + from a DHCPv4 server processing an Active Leasequery request cannot + be reset from the incoming messages (and used in a subsequent Active + Leasequery's query-start-time option), because to do so would + compromise the ability to recover lost information if the + DHCPACTIVELEASEQUERY were to terminate prior to the completion of the + catch-up phase. + + + +Kinnear, et al. Standards Track [Page 17] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + The requestor will know that the catch-up phase is complete because + the DHCPv4 server will transmit a DHCPLEASEQUERYSTATUS message with + the dhcp-status-code of CatchUpComplete (or, as discussed above, + DataMissing). Once this message is transmitted, all additional + DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED messages will relate to real- + time ("new") binding changes in the DHCPv4 server. + + As discussed in Section 6.3, the requestor SHOULD keep track of the + latest base-time option value received over a particular connection, + to be used in a subsequent DHCPACTIVELEASEQUERY request -- but only + if the catch-up phase is complete. Prior to the completion of the + catch-up phase, if the connection should go away or if the requestor + receives a DHCPLEASEQUERYDONE message, then when it reconnects it + MUST use the base-time value from the previous connection and not any + base-time value received from the recently closed connection. + + In the event that there was enough data available to the DHCPv4 + server to begin to satisfy the request implied by the query-start- + time option, but during the processing of that data the server found + that it was unable to continue (perhaps there was barely enough, the + connection was very slow, and the aging algorithm caused the saved + data to become unavailable), the DHCPv4 server will terminate the + catch-up phase of processing immediately by sending a + DHCPLEASEQUERYSTATUS message with a dhcp-status-code of DataMissing + and with a base-time option of the current time. + + The requestor must not assume that every individual state change of + every binding during the period from the time specified in the query- + start-time and the present is replicated in an Active Leasequery + reply message. See Section 6. The requestor MAY assume that at + least one Active Leasequery reply message will exist for every + binding that had one or more changes of state during the period + specified by the query-start-time and the current time. The last + message for each binding will contain the state at the current time, + and there can be one or more messages concerning a single binding + during the catch-up phase of processing. + + Bindings can change multiple times while the requestor is not + connected. The requestor will only receive information about the + current state of the binding, not information about each state change + that occurred during the period from the query-start-time to the + present. + + If the DHCPLEASEQUERYSTATUS message containing a dhcp-status-code of + DataMissing is received and the requestor is interested in keeping + its database up to date with respect to the current state of the + bindings in the DHCPv4 server, then the requestor SHOULD issue a + DHCPBULKLEASEQUERY request to recover the information missing from + + + +Kinnear, et al. Standards Track [Page 18] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + its database. This DHCPBULKLEASEQUERY should include a query-start- + time option, set to the same value as the query-start-time option + previously included in the DHCPACTIVELEASEQUERY responses from the + DHCPv4 server, and a query-end-time option equal to the base-time + option returned by the DHCPv4 server in the DHCPLEASEQUERYSTATUS + message with the dhcp-status-code of DataMissing. + + Typically, the requestor would have one connection open to a DHCPv4 + server for a DHCPACTIVELEASEQUERY request and possibly one additional + connection open for a DHCPBULKLEASEQUERY request to the same DHCPv4 + server to fill in the data that might have been missed prior to the + initiation of the DHCPACTIVELEASEQUERY. The Bulk Leasequery + connection would typically run to completion and be closed, leaving + one Active Leasequery connection open to a single DHCPv4 server. + +7.5. Closing Connections + + The Requestor or DHCPv4 leasequery server MAY close its end of the + TCP connection at any time. The Requestor MAY choose to retain the + connection if it intends to issue additional queries. Note that this + requestor behavior does not guarantee that the connection will be + available for additional queries: the server might decide to close + the connection based on its own configuration. + +8. Server Behavior + + A DHCPv4 server that supports Active Leasequery MUST support Bulk + Leasequery [RFC6926] as well. + +8.1. Accepting Connections + + DHCPv4 servers that implement DHCPv4 Active Leasequery listen for + incoming TCP connections. The approach used in accepting the + requestor's connection is the same as specified in DHCPv4 Bulk + Leasequery [RFC6926], with the exception that support for Active + Leasequery MUST NOT be enabled by default, and MUST require an + explicit configuration step to be performed before it will operate. + + DHCPv4 servers SHOULD be able to operate in either insecure or secure + mode. See Section 9. This MAY be a mode that is administratively + controlled, where the server will require a TLS connection to operate + or will only operate without a TLS connection. In either case, + operation in insecure mode MUST NOT be the default, even if operation + in secure mode is not supported. Operation in insecure mode MUST + always require an explicit configuration step, separate from the + configuration step required to enable support for Active Leasequery. + + + + + +Kinnear, et al. Standards Track [Page 19] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + When operating in insecure mode, the DHCPv4 server simply waits for + the requestor to send the Active Leasequery after the establishment + of TCP connection. If it receives a DHCPTLS message, it will respond + with TLSConnectionRefused in a DHCPTLS message. + + When operating in secure mode, DHCPv4 servers MUST support TLS + [RFC5246] to protect the integrity and privacy of the data + transmitted over the TCP connection. When operating in secure mode, + DHCPv4 servers MUST be configurable with regard to which requestors + they will communicate. The certificate presented by a requestor when + initiating the TLS connection is used to distinguish between + acceptable and unacceptable requestors. + + When operating in secure mode, a DHCPv4 server MUST begin to + negotiate a TLS connection with a requestor who asks for one, and + MUST close TCP connections that are not secured with TLS or for which + the requestor's certificate is deemed unacceptable. The + recommendations in [RFC7525] apply when negotiating a TLS connection. + + A requestor will request a TLS connection by sending a DHCPTLS as the + first message over a newly created TCP connection. If the DHCPv4 + server supports TLS connections and has not been configured to not + allow them on this link, the DHCPv4 server MUST respond to this + DHCPTLS message by sending a DHCPTLS message with no dhcp-status-code + back to the requestor. This indicates to the requestor that the + DHCPv4 server will support the negotiation of a TLS connection over + this existing TCP connection. + + If a connection is to be rejected because of a limitation of the + number of open connections, the TCP connection itself should be + rejected, or the subsequent ACTIVELEASEQUERY message should be + rejected. Capacity-related rejections SHOULD NOT affect the response + to the DHCPTLS message. + + Any options appearing in a DHCPTLS message received by a DHCPv4 + server SHOULD be ignored. This is a "SHOULD" instead of a "MUST" in + order to allow use of the DHCPTLS message in later documents, + possibly with the use of options, without requiring those documents + to update this document. + + If for some reason the DHCPv4 server cannot support or has been + configured to not support a TLS connection, then it sends a DHCPTLS + message with a dhcp-status-code of TLSConnectionRefused back to the + requestor. + + In the event that the DHCPv4 server sends a DHCPTLS message with no + dhcp-status-code option included (which indicates success), the + requestor is supposed to initiate a TLS handshake [RFC5246] (see + + + +Kinnear, et al. Standards Track [Page 20] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + Section 7.2). During the TLS handshake, the DHCPv4 server MUST + validate the requestor's digital certificate. In addition, the + digital certificate presented by the requestor is used to decide if + this requestor is allowed to perform an Active Leasequery. If this + requestor's certificate is deemed unacceptable, the server MUST abort + the creation of the TLS connection. + + All TLS connections established between a requestor and a DHCPv4 + server for the purposes of supporting Active Leasequery MUST be + mutually authenticated. + + If the TLS handshake is not successful in creating a TLS connection, + the server MUST close the TCP connection. + + If the TCP connection becomes blocked while the server is accepting a + connection or reading a query, it SHOULD terminate the connection + after a BULK_LQ_DATA_TIMEOUT. We make this recommendation to allow + servers to control the period of time they are willing to wait before + abandoning an inactive connection, independent of the TCP + implementations they may be using. + +8.1.1. Update to RFC 6926 + + In an update to the DHCPv4 Bulk Leasequery protocol [RFC6926] (which + didn't discuss this situation explicitly), if the DHCPv4 server + receives a DHCPv4 message containing a dhcp-message-type option with + a value that is not supported over a TCP connection, it MUST close + the TCP connection. + +8.2. Replying to an Active Leasequery + + If the connection becomes blocked while the server is attempting to + send reply messages, the server SHOULD terminate the TCP connection + after ACTIVE_LQ_SEND_TIMEOUT. This timeout governs how long the + DHCPv4 server is prepared to wait for the requestor to read and + process enough information to unblock the TCP connection. The + default is two minutes, which means that if more than two minutes + goes by without the requestor reading enough information to unblock + the TCP connection, the DHCPv4 server SHOULD close the TCP + connection. + + If the DHCPv4 server encounters an error during processing of the + DHCPACTIVELEASEQUERY message, either during initial processing or + later during the message processing, it SHOULD send a + DHCPLEASEQUERYSTATUS containing an error code of some kind in a dhcp- + status-code option. It SHOULD close the connection after this error + is signaled. + + + + +Kinnear, et al. Standards Track [Page 21] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + Every reply to a DHCPACTIVELEASEQUERY request MUST contain the + information specified in replies to a DHCPBULKLEASEQUERY request + [RFC6926], with the exception that a server implementing Active + Leasequery SHOULD be able to be configured to prevent specific data + items from being sent to the requestor even if these data items were + requested in the dhcp-parameter-request-list option. + + Some servers can be configured to respond to a DHCPv4 Leasequery + [RFC4388] or a DHCPBULKLEASEQUERY [RFC6926] for an IPv4 binding that + is reserved in such a way that it appears that the IPv4 binding is + leased to the DHCP client for which it is reserved. These servers + SHOULD also respond to a DHCPACTIVELEASEQUERY request with the same + information as they would to a DHCPBULKLEASEQUERY request when they + first determine that the IPv4 binding is reserved to a DHCP client. + + If a DHCPACTIVELEASEQUERY request contains a query-start-time option, + it indicates that the requestor would like the DHCPv4 server to send + it not only messages that correspond to DHCPv4 binding activity that + occurs subsequent to the receipt of the DHCPLEASEACTIVE request, but + also messages that correspond to DHCPv4 binding activity that + occurred prior to the DHCPACTIVELEASEQUERY request. + + If a query-end-time option appears in a DHCPACTIVELEASEQUERY the + DHCPv4 server should send a DHCPLEASEQUERYSTATUS message with a dhcp- + status-code of MalformedQuery and terminate the connection. + + In order to implement a meaningful response to this query, the DHCPv4 + server MAY keep track of the binding activity and associate changes + with particular base-time values from the messages. Then, when + requested to do so by a DHCPACTIVELEASEQUERY request containing a + query-start-time option, the DHCPv4 server can respond with replies + for all binding activity occurring on that query-start-time or later + times. + + These replies based on the query-start-time MAY be interleaved with + the messages generated due to current binding activity. + + Once the transmission of the DHCPv4 Leasequery messages associated + with the query-start-time option are complete, a DHCPLEASEQUERYSTATUS + message MUST be sent with a dhcp-status-code value of + CatchUpComplete. + + The DHCPv4 server SHOULD keep track of previous binding activity. It + SHOULD limit the amount of previous binding activity it keeps track + of. The DHCPv4 server MAY choose to only do this in the event that + it has received at least one DHCPACTIVELEASEQUERY request in the + past, as to do so will almost certainly entail some utilization of + resources that would be wasted if there are no DHCPACTIVELEASEQUERY + + + +Kinnear, et al. Standards Track [Page 22] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + requestors for this DHCPv4 server. The DHCPv4 server SHOULD make the + amount of previous binding activity it retains configurable. There + is no requirement on the DHCPv4 server to retain this information + over a server restart (or even to retain such information at all). + + Unless there is an error or some requirement to cease processing a + DHCPACTIVELEASEQUERY request yielding a DHCPLEASEQUERYSTATUS message, + such as a server shutdown, there will be no DHCPLEASEQUERYSTATUS + message at the conclusion of the DHCPACTIVELEASEQUERY processing + because that processing will not conclude but will continue until + either the requestor or the server closes the connection. + + While the form of the data being sent by a DHCPACTIVELEASEQUERY is + essentially the same as that being sent by a DHCPBULKLEASEQUERY, the + reasons for sending information differs considerably between these + two capabilities. In the DHCPBULKLEASEQUERY context, the entire + contents of the lease state database (subject to the constraints of + the various query options) are returned to the requestor. In the + DHCPACTIVELEASEQUERY context, changes to the lease state database are + returned to the requestor essentially as they happen. For instance, + when an IPv4 binding transitions from the leased state to some other + state, the DHCPACTIVELEASEQUERY will send a DHCPLEASEUNASSIGNED + packet with information regarding that binding. The server may then + entirely forget about that IPv4 binding (or not), but it is important + to tell the DHCPACTIVELEASEQUERY requestor that a binding has + transitioned away from the leased state. + + The relationship between the time that the server replies to a DHCP + client request and the time that the DHCP server sends a reply to a + DHCPACTIVELEASEQUERY message is a matter of implementation (and thus + not defined by this document). However, the server SHOULD NOT delay + responding to the DHCP client in order to transmit a reply to a + DHCPACTIVELEASEQUERY message, and the server SHOULD send the reply to + the DHCPACTIVELASEQUERY message as soon as possible after responding + to the client. + +8.3. Multiple or Parallel Queries + + Every Active Leasequery request MUST be made on a single TCP + connection where there is no other request active at the time the + request is made. Note that this is different than what was allowed + in Section 7.7 of [RFC6926] for Bulk Leasequery requests. + + Typically, a requestor of an Active Leasequery would not need to send + a second Active Leasequery while the first is still active. However, + sending an Active Leasequery and a Bulk Leasequery in parallel would + be possible and reasonable. In case of parallel Active and Bulk + Leasequery requests, the requestor MUST use different connections. + + + +Kinnear, et al. Standards Track [Page 23] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + This MAY be a feature that is administratively controlled. Servers + that are able to process queries in parallel SHOULD offer + configuration that limits the number of simultaneous queries + permitted from any one requestor, in order to control resource use if + there are multiple requestors seeking service. + +8.4. Closing Connections + + The server MAY end communication by sending a DHCPLEASEQUERYSTATUS + message and then immediately closing the TCP connection. + Alternatively, the server MAY retain the connection and wait for + additional queries from the requestor. The server SHOULD limit the + number of connections it maintains and SHOULD close idle connections + to enforce the limit. + + The server MUST close its end of the TCP connection if it encounters + an error sending data on the connection. The server MUST close its + end of the TCP connection if it finds that it has to abort an in- + process request. A server aborting an in-process request SHOULD + attempt to signal that to its requestors by using the QueryTerminated + status code in the dhcp-status-code option in a DHCPLEASEQUERYSTATUS + message. If the server detects that the requestor end has been + closed, the server MUST close its end of the connection. + +9. Security Considerations + + The Security Considerations section of [RFC2131] details the general + threats to DHCPv4. The DHCPv4 Leasequery specification [RFC4388] + describes recommendations for the Leasequery protocol, especially + with regard to relayed LEASEQUERY messages, mitigation of packet- + flooding DoS attacks, restriction to trusted requestors, and use of + IPsec [RFC4301]. + + The use of TCP introduces some additional concerns. Attacks that + attempt to exhaust the DHCPv4 server's available TCP connection + resources can compromise the ability of legitimate clients to receive + service. Malicious requestors who succeed in establishing + connections, but who then send invalid queries, partial queries, or + no queries at all also can exhaust a server's pool of available + connections. + + Two modes of operation exist for this protocol, insecure mode and + secure mode. These two modes exist because there are essentially two + models of use for this protocol. In one model, the requestor of an + Active Leasequery is connected to the Internet in an arbitrary + location, and the information transmitted needs to be protected + + + + + +Kinnear, et al. Standards Track [Page 24] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + during transmission. In addition, the identities of both requestor + and server need to be verified. For this model of use, the secure + mode is appropriate. + + The other model of use is where the requestor of the Active + Leasequery resides in a network element that is essentially "next to" + the element containing the DHCP server, and both of these elements + are inside a protected environment. For this model, the insecure + mode is sufficient since there are other, more global, protections in + place to protect this information. + + When operating in secure mode, TLS [RFC5246] is used to secure the + connection. The recommendations in [RFC7525] apply when negotiating + a TLS connection. + + Operating in insecure mode (see Section 8.1) does not provide any way + to validate the authorization of requestors of a DHCPV4 Active + Leasequery request. + + Servers SHOULD offer configuration parameters to limit the sources of + incoming connections through validation and use of the digital + certificates presented to create a TLS connection. They SHOULD also + limit the number of accepted connections and limit the period of time + during which an idle connection will be left open. + + The data acquired by using an Active Leasequery is subject to the + same potential abuse as the data held by the DHCPv4 server from which + it was acquired and SHOULD be secured by mechanisms as strong as + those used for the data held by that DHCPv4 server. The data + acquired by using an Active Leasequery SHOULD be deleted as soon as + possible after the use for which it was acquired has passed. + + Servers that implement the Bulk Leasequery protocol [RFC6926] but do + not implement the Active Leasequery protocol SHOULD implement the + update to [RFC6926] discussed in Section 8.1.1. + +10. IANA Considerations + + IANA has assigned the following new DHCP message types from the + registry "DHCP Message Type 53 Values" maintained at + : + + 1. A dhcp-message-type of 16 for DHCPACTIVELEASEQUERY. + + 2. A dhcp-message-type of 17 for DHCPLEASEQUERYSTATUS. + + 3. A dhcp-message-type of 18 for DHCPTLS. + + + + +Kinnear, et al. Standards Track [Page 25] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + + IANA has assigned the following new DHCP status codes from the + registry "DHCP Status Code Type 151 Values" maintained at + : + + +----------------------+-------------+ + | Name | Status-Code | + +----------------------+-------------+ + | DataMissing | 5 | + | ConnectionActive | 6 | + | CatchUpComplete | 7 | + | TLSConnectionRefused | 8 | + +----------------------+-------------+ + +11. References + +11.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + . + + [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", + RFC 2131, DOI 10.17487/RFC2131, March 1997, + . + + [RFC4388] Woundy, R. and K. Kinnear, "Dynamic Host Configuration + Protocol (DHCP) Leasequery", RFC 4388, + DOI 10.17487/RFC4388, February 2006, + . + + [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", RFC 5246, + DOI 10.17487/RFC5246, August 2008, + . + + [RFC6926] Kinnear, K., Stapp, M., Desetti, R., Joshi, B., Russell, + N., Kurapati, P., and B. Volz, "DHCPv4 Bulk Leasequery", + RFC 6926, DOI 10.17487/RFC6926, April 2013, + . + + [RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, + "Recommendations for Secure Use of Transport Layer + Security (TLS) and Datagram Transport Layer Security + (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May + 2015, . + + + + + +Kinnear, et al. Standards Track [Page 26] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + +11.2. Informative References + + [RFC951] Croft, W. and J. Gilmore, "Bootstrap Protocol", RFC 951, + DOI 10.17487/RFC0951, September 1985, + . + + [RFC1542] Wimer, W., "Clarifications and Extensions for the + Bootstrap Protocol", RFC 1542, DOI 10.17487/RFC1542, + October 1993, . + + [RFC2132] Alexander, S. and R. Droms, "DHCP Options and BOOTP Vendor + Extensions", RFC 2132, DOI 10.17487/RFC2132, March 1997, + . + + [RFC4301] Kent, S. and K. Seo, "Security Architecture for the + Internet Protocol", RFC 4301, DOI 10.17487/RFC4301, + December 2005, . + + [RFC7414] Duke, M., Braden, R., Eddy, W., Blanton, E., and A. + Zimmermann, "A Roadmap for Transmission Control Protocol + (TCP) Specification Documents", RFC 7414, + DOI 10.17487/RFC7414, February 2015, + . + +Acknowledgments + + The ideas in this document came in part from work in DHCPv6 and + DHCPv4 Bulk Leasequery as well as from in depth discussions between + the authors. Useful review comments by Ted Lemon, Scott Bradner, + Francis Dupont, and Stephen Farrell on drafts for DHCPv6 Active + Leasequery were also included in this draft. Brian Haberman's review + brought this document into much closer alignment with DHCPv6 Active + Leasequery. Additional reviews by Alissa Cooper, Spencer Dawkins, + Christer Holmberg, and Ben Campbell added clarity to this document. + + + + + + + + + + + + + + + + + +Kinnear, et al. Standards Track [Page 27] + +RFC 7724 Active DHCPv4 Lease Query December 2015 + + +Authors' Addresses + + Kim Kinnear + Cisco Systems, Inc. + 1414 Massachusetts Ave + Boxborough, MA 01719 + United States + + Email: kkinnear@cisco.com + + + Mark Stapp + Cisco Systems, Inc. + 1414 Massachusetts Ave + Boxborough, MA 01719 + United States + + Email: mjs@cisco.com + + + Bernie Volz + Cisco Systems, Inc. + 1414 Massachusetts Ave + Boxborough, MA 01719 + United States + + Email: volz@cisco.com + + + Neil Russell + Staples + 500 Staples Drive + Framingham, MA 01702 + United States + + Email: neil.e.russell@gmail.com + + + + + + + + + + + + + + + +Kinnear, et al. Standards Track [Page 28] + diff --git a/kdhcpd.yaml b/kdhcpd.yaml index 3cd1f77..8a6c671 100644 --- a/kdhcpd.yaml +++ b/kdhcpd.yaml @@ -1,10 +1,10 @@ kdhcp: version: 1 lease_file: /tmp/kdhcp_lease.yaml - # interface: enp89s0 - interface: eth0 - address: 192.168.4.250:67 + interface: enp89s0 + port: 67 network: + address: 192.168.4.250 gateway: 192.168.4.254 mask: 255.255.255.0 broadcast: 192.168.4.255 diff --git a/server/BUILD.bazel b/server/BUILD.bazel index d21f781..cefe30d 100644 --- a/server/BUILD.bazel +++ b/server/BUILD.bazel @@ -10,6 +10,7 @@ go_library( visibility = ["//visibility:public"], deps = [ "//config", + "//dhcp", "//log", ], ) diff --git a/server/server.go b/server/server.go index 0fc40ff..94960cc 100644 --- a/server/server.go +++ b/server/server.go @@ -5,6 +5,7 @@ import ( "net" "git.wntrmute.dev/kyle/kdhcp/config" + "git.wntrmute.dev/kyle/kdhcp/dhcp" "git.wntrmute.dev/kyle/kdhcp/log" ) @@ -22,7 +23,9 @@ func (s *Server) Close() error { } func (s *Server) Bind() (err error) { - s.Conn, err = BindInterface(s.Config.IP, s.Config.Port, s.Config.Interface) + // In order to read DHCP packets, we'll need to listen on all addresses. + ip := net.IP([]byte{0, 0, 0, 0}) + s.Conn, err = BindInterface(ip, s.Config.Port, s.Config.Interface) return err } @@ -37,17 +40,27 @@ func (s *Server) ReadFrom() ([]byte, net.Addr, error) { return b, addr, nil } +func (s *Server) ReadDHCPRequest() (*dhcp.BootRequest, error) { + pkt, addr, err := s.ReadFrom() + if err != nil { + return nil, err + } + + log.Debugf("server: read %db packet from %s", len(pkt), addr) + return dhcp.ReadRequest(pkt) +} + func (s *Server) WriteTo(b []byte, addr net.Addr) error { return errors.New("server: not implemented") } func (s *Server) AcceptPacket() error { - packet, addr, err := s.ReadFrom() + request, err := s.ReadDHCPRequest() if err != nil { return err } - log.Debugf("accepted %d byte packet from %s", len(packet), addr) + log.Debugf("BOOTP request received from %x", request.HardwareAddress) return nil }