DHC Working Group Kim Kinnear Internet Draft Bernie Volz Intended Status: Standards Track Neil Russell Expires: January 7, 2009 Mark Stapp Cisco Systems July 7, 2008 Bulk DHCPv4 Lease Query Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on January 7, 2009 Copyright Notice Copyright (C) The IETF Trust (2008). Abstract The Dynamic Host Configuration Protocol for IPv4 (DHCPv4) has been extended with a Leasequery capability that allows a client to request information about DHCPv4 bindings. That mechanism is limited to queries for individual bindings. In some situations individual binding queries may not be efficient, or even possible. This document expands on the DHCPv4 Leasequery protocol to allow for bulk Kinnear Expires December 2008 [Page 1] Internet Draft Bulk DHCPv4 Lease Query July 2008 transfer of DHCPv4 address binding data via TCP. Table of Contents 1. Introduction................................................. 2 2. Terminology.................................................. 3 3. Protocol Overview............................................ 5 4. Interaction Between UDP Leasequery and Bulk Leasequery....... 5 5. Message and Option Definitions............................... 6 5.1. Message Framing for TCP.................................... 6 5.2. New or Changed Options..................................... 7 5.3. Connection and Transmission Parameters..................... 13 6. Requestor Behavior........................................... 14 6.1. Connecting and General Processing.......................... 14 6.2. Forming a Bulk Leasequery.................................. 15 6.3. Processing Bulk Replies.................................... 16 6.4. Processing Time Values in Leasequery messages.............. 16 6.5. Making Sense Out of Multiple Responses Concerning a Single. 18 6.6. Querying Multiple Servers.................................. 19 6.7. Closing Connections........................................ 19 7. Server Behavior.............................................. 19 7.1. Accepting Connections...................................... 20 7.2. Replying to a Bulk Leasequery.............................. 20 7.3. Building a Single Reply for Bulk Leasequery................ 21 7.4. Multiple or Parallel Queries............................... 22 7.5. Closing Connections........................................ 22 8. Security Considerations...................................... 23 9. IANA Considerations.......................................... 23 10. Acknowledgements............................................ 24 11. References.................................................. 24 11.1. Normative References...................................... 24 11.2. Informative References.................................... 25 12. Authors' Addresses.......................................... 25 13. Full Copyright Statement.................................... 26 14. Intellectual Property....................................... 27 15. Acknowledgment.............................................. 27 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 IP address or client in near real-time. Sometimes relay agents need to learn all of the DHCPv4 address binding information contained in a DHCPv4 server in an efficient Kinnear Expires December 2008 [Page 2] Internet Draft Bulk DHCPv4 Lease Query July 2008 manner. This can occur after a DHCPv4 relay agent has lost the information it collected by watching DHCPv4 messages it has relayed. In other cases, an external entity may need to update itself with information from the DHCPv4 server's IP address binding database without knowledge of the particular IP addresses managed by the DHCPv4 server. 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 "address binding" The information that a DHCPv4 server keeps regarding the relationship between a DHCPv4 client and an IPv4 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 IPv4 address. 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 "Bulk Leasequery" Requesting and receiving the existing DHCPv4 address binding information in an efficient manner. o "clock skew" 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 is termed the "clock skew" for that 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 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 Kinnear Expires December 2008 [Page 3] Internet Draft Bulk DHCPv4 Lease Query July 2008 make small adjustments to the existing value held in the requestor. o "DHCPv4 client" A DHCPv4 client is an Internet host 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]. o "DHCPv4 server" A DHCPv4 server is an Internet host that returns configuration parameters to DHCPv4 clients. o "IP address binding" The information that a DHCPv4 server keeps regarding the relationship between a DHCPv4 client and an IPv4 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 IPv4 address. 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 message, a MAC address consists of the 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 which requires restart of the server. Kinnear Expires December 2008 [Page 4] Internet Draft Bulk DHCPv4 Lease Query July 2008 3. Protocol Overview The Bulk Leasequery mechanism is modeled on the existing individual Leasequery protocol in [RFC4388] as well as related work on DHCPv6 Bulk Leasequery [DHCPv6Bulk]; most differences arise from the use of TCP. A Bulk Leasequery client opens a TCP connection to a DHCPv4 Server, using the DHCPv4 port 67. Note that this implies that the Leasequery client 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 client sends a DHCPBULKLEASEQUERY message over the connection. The server uses the message and additional data in the DHCPv4 message to decide how much data to send as a response to the query. In order to support some query types, servers may have to maintain additional data structures or be able to locate bindings that have been requested by the Leasequery client. The Bulk Leasequery mechanism 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. 4. 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 three query types available in the DHCPv4 Leasequery capability: IP address, MAC address, and dhcp-client-identifier, are not supported by Bulk Leasequery and MUST NOT be used by a requestor. Bulk Leasequery allows specification of a query-start-time as well as a a query-end-time. The query times are optional (and sent as options), and in the absence of query times Bulk Leasequery will return all current IP address bindings. Use of query-times allows a relay agent that periodically commits information to stable storage to recover just what it lost since the Kinnear Expires December 2008 [Page 5] Internet Draft Bulk DHCPv4 Lease Query July 2008 last commit. The contents of message returns are similar between the existing UDP Leasequery protocol and the Bulk Leasequery protocol, though more information is returned in the Bulk Leasequery messages. See Section 7.3 for the details of the messages returned. 5. Message and Option Definitions 5.1. Message Framing for TCP The use of TCP for the Bulk Leasequery protocol permits one or more DHCPv4 messages to be sent at a time. The receiver needs to be able to determine how large each message is. 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. DHCPv4 message framed for TCP: 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 integer in network byte-order. All other fields are as specified in DHCPv4 [RFC2131]. Figure 1: Format of a DHCPv4 message in TCP The intent in using this format is that code which currently knows Kinnear Expires December 2008 [Page 6] Internet Draft Bulk DHCPv4 Lease Query July 2008 how to deal with a message returned from DHCPv4 Leasequery [RFC4388] will be able to deal with the message held inside of the TCP framing. 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 IP address which is currently not leased or currently leased to a DHCPv4 client, respectively. Additional options have also been defined to enable the Bulk Leasequery protocol to communicate useful information to the requestor. 5.2.1. dhcp-message-type The message type option (option 53) from [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 16 DHCPLEASEQUERYSTATUS 5.2.2. dhcp-status-code The dhcp-status-code option allows greater detail to be returned regarding the status of a DHCP request. While specified in the Bulk Leasequery document, this DHCPv4 option may well be valuable in other circumstances. In those circumstances its scope should be explicitly defined. 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 or DHCPLEASEQUERYSTATUS. The code for the this option is TBD. The length of the this option is at least 1 octet. It SHOULD be present unless the status would be Success, in which case it SHOULD NOT be present. Kinnear Expires December 2008 [Page 7] Internet Draft Bulk DHCPv4 Lease Query July 2008 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | option-code | option-len | status-code | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | . status-message (if any) . +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ option-code TBD. option-len 1 + length of status-message (which may be 0). status-code The numeric code for the status encoded in this option. The status codes are defined below. status-message An optional UTF-8 encoded text string suitable for display to an end user, which MUST NOT be null-terminated. Name status-code Description ---- ----------- ----------- Success 0 Success. Also signaled by absence of dhcp-status-code option. UnspecFail 1 Failure, reason unspecified. QueryTerminated 2 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 3 The query was not understood. NotAllowed 4 The query or request was understood but was not allowed in this context. 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 which is successful. Kinnear Expires December 2008 [Page 8] Internet Draft Bulk DHCPv4 Lease Query July 2008 5.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. This MUST be an absolute number of seconds since Jan 1, 1970. It is the time relative to which all of the other relative times in the reply message are based. This time is in the context of the DHCPv4 server. This is an integer in network order. The code for the this option is TBD. The length of the this option is 4 octets. It MUST appear in every DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message returned as a response to a DHCPBULKLEASEQUERY. DHCPv4 Server Code Len Base Time +-----+-----+-----+-----+-----+-----+ | TBD | 4 | t1 | t2 | t3 | t4 | +-----+-----+-----+-----+-----+-----+ 5.2.4. start-time-of-state The start-time-of-state option allows the receiver to determine the time at which the IP address transitioned into its current state. 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 specified in the base-time option in the same message that the IP address transitioned into its current state. In the same way that the IP Address Lease Time option (option 51) encodes a lease time which is a number of seconds into the future from the time the message was sent, this option encodes a value which is a number of seconds into the past from the base-time option included in the same message. This is an integer in network order. The code for the this option is TBD. The length of the this option is 4 octets. It MUST appear in every DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message returned as a response to a DHCPBULKLEASEQUERY. Kinnear Expires December 2008 [Page 9] Internet Draft Bulk DHCPv4 Lease Query July 2008 Seconds in the past Code Len from base-time +-----+-----+-----+-----+-----+-----+ | TBD | 4 | t1 | t2 | t3 | t4 | +-----+-----+-----+-----+-----+-----+ 5.2.5. query-start-time The query-start-time option allows the requestor to specify a request time to the DHCPv4 server. This MUST be an absolute time. This MUST be an absolute number of seconds since Jan 1, 1970. This MUST be in a time in the context of the DHCPv4 server, and thus SHOULD be equal to or derived from a base-time value received from the DHCPv4 server itself. It SHOULD NOT be a time in the context of the requestor. This is an integer in network order. The code for the this option is TBD. The length of the this option is 4 octets. Code Len DHCPv4 Server Time +-----+-----+-----+-----+-----+-----+ | TBD | 4 | t1 | t2 | t3 | t4 | +-----+-----+-----+-----+-----+-----+ 5.2.6. query-end-time The query-end-time option allows the requestor to specify a request time to the DHCPv4 server. This MUST be an absolute time. This MUST be an absolute number of seconds since Jan 1, 1970. This MUST be in a time in the context of the DHCPv4 server, and thus SHOULD be equal to or derived from a base-time value received from the DHCPv4 server itself. It SHOULD NOT be a time in the context of the requestor. Kinnear Expires December 2008 [Page 10] Internet Draft Bulk DHCPv4 Lease Query July 2008 This is an integer in network order. The code for the this option is TBD. The length of the this option is 4 octets. Code Len DHCPv4 Server Time +-----+-----+-----+-----+-----+-----+ | TBD | 4 | t1 | t2 | t3 | t4 | +-----+-----+-----+-----+-----+-----+ 5.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 the this option is TBD. The length of the this option is 1 octet. It MUST appear in every message returned as a response to a DHCPBULKLEASEQUERY. 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Code | Length | State | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Code The suboption code (TBD). Length The suboption length, 1 octet. State The State of the IP address. State ----- 1 AVAILABLE Address is available to local server 2 ACTIVE Address is assigned to a client 3 EXPIRED Lease has expired 4 RELEASED Lease has been released by 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 server 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. Kinnear Expires December 2008 [Page 11] Internet Draft Bulk DHCPv4 Lease Query July 2008 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 which is AVAILABLE on one server would be REMOTE on any remote server. 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. In general, every state can (at times) follow every other state. 5.2.8. data-source The data-source option contains information about the source of the data in a DHCPLEASEACTIVE or a DHCPLEASEUNASSIGNED message. It is used when there are two or more servers who 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. 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. The code for the this option is TBD. The length of the this option is 1 octet. This option MUST appear in every Bulk Leasequery message where the REMOTE flag would be have the value remote. If this option does not appear, then the REMOTE flag is considered to be have the value local. Kinnear Expires December 2008 [Page 12] Internet Draft Bulk DHCPv4 Lease Query July 2008 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Code | Length | Flags | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Code The suboption code (TBD). Length The suboption length, 1 octet. Flags The Source information for this message. 0 1 2 3 4 5 6 7 +-+-+-+-+-+-+-+-+ | MBZ |R| +-+-+-+-+-+-+-+-+ R: REMOTE flag remote = 1 local = 0 MBZ: MUST BE ZERO (reserved for future use) The REMOTE flag is used to indicate where the 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. 5.3. Connection and Transmission Parameters DHCPv4 Servers that 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. Client implementations 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. Kinnear Expires December 2008 [Page 13] Internet Draft Bulk DHCPv4 Lease Query July 2008 Parameter Default Description ------------------------------------------ BULK_LQ_CONN_TIMEOUT 30 secs Leasequery connection timeout BULK_LQ_QUERY_TIMEOUT 30 secs Leasequery query timeout BULK_LQ_MAX_CONNS 10 Max Leasequery TCP connections BULK_LQ_MAX_CONN_RETRY 60 secs Max Leasequery retry timeout BULK_LQ_DATA_TIMEOUT 30 secs Leasequery data timeout 6. Requestor Behavior 6.1. Connecting and General Processing A requestor attempts to establish a TCP connection to a DHCPv4 Server in order to initiate a Leasequery exchange. The requestor SHOULD be prepared to abandon the connection attempt after BULK_LQ_CONN_TIMEOUT. If the attempt fails, the requestor MAY retry. Retries MUST use an exponential backoff timer, increasing the interval between attempts up to BULK_LQ_MAX_CONN_RETRY. If Bulk Leasequery is terminated prematurely by a DHCPLEASEQUERYSTATUS with a dhcp-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 MUST use an exponential backoff timer, increasing the interval between attempts up to BULK_LQ_MAX_CONN_RETRY. Messages from the DHCPv4 server come as a response to a DHCPBULKLEASEQUERY message. These requests MUST have a transaction- id unique to the connection on which they are sent, and all of the messages which come as a response to them all contain the same transaction-id as the requests. In the event that a response is received with a different transaction-id than the request which generated it, the requestor MUST close the connection immediately. 6.2. Forming a Bulk Leasequery The Bulk Leasequery is designed to create a connection which will transfer the state of all IP address bindings between the requestor and the DHCPv4 server processing the bulk query. The DHCPv4 server will send all of the requested IPv4 address binding across this connection with minimal delay after it receives the request. In this context, "all IP address binding information" means information about Kinnear Expires December 2008 [Page 14] Internet Draft Bulk DHCPv4 Lease Query July 2008 all IPv4 addresses configured within the DHCPv4 server, whether or not they have ever had or now have an association with a specific DHCPv4 client. To form the Bulk query, a DHCPv4 request is constructed with a dhcp- message-type of DHCPBULKLEASEQUERY. This DHCPv4 request MUST NOT have a ciaddr, a chaddr, or a dhcp-client-identifier. 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 requestor MAY include a query-start-time option or a query-end- time option or both in the DHCPBULKLEASEQUERY request indicating to the DHCPv4 server that it should only send information which changed on or after the time specified in any query-start-time option and on or before any time specified in a query-end-time option. If there is no query-start-time, then the DHCPv4 server will assume the query-start-time is equivalent to a time prior to any time that resides in any IP address binding. If there is no query-end-time, the DHCPv4 server will assume that the query-end-time is equivalent to the current time. Both of these options (if they appear) MUST include times derived directly from base-time options received from the server and MUST be in the context of the DHCPv4 server's time, not the requestor's time should they be different. 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, though it may not change the actual data processed on the DHCPv4 server. If the TCP connection becomes blocked while the requestor is sending its query, the requestor SHOULD be prepared to terminate the connection after BULK_LQ_QUERY_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. 6.3. Processing Bulk Replies The requestor attempts to read a DHCPv4 leasequery message from the TCP connection. If the stream of replies becomes blocked, the requestor SHOULD be prepared to terminate the connection after BULK_LQ_DATA_TIMEOUT, and MAY begin retry processing if configured to do so. Kinnear Expires December 2008 [Page 15] Internet Draft Bulk DHCPv4 Lease Query July 2008 A Bulk Leasequery will consist of a variety of DHCPLEASEACTIVE messages containing binding data and DHCPLEASEUNASSIGNED messages which MAY also contain information about the last client that was bound to this IP address. In both cases, the ciaddr will contain the IP address of the Leasequery reply, and may contain a non-zero chaddr, htype, and hlen and possibly additional options. If there are additional bindings to be returned, they will be carried in additional DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED messages. 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 a transaction-id matching a single DHCPBULKLEASEQUERY message from a single DHCPv4 server. Indeed, a requestor which receives a reply with a transaction-id which is not the same as that in the DHCPBULKLEASEQUERY request MUST terminate the connection. The requestor MUST NOT assume that there is any inherent order in the IPv4 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. After receiving DHCPLEASEQUERYDONE from a server, the requestor MAY close the TCP connection to that server. The DHCPv4 Leasequery protocol [RFC4388] uses the associated-ip option as an indicator that multiple bindings were present in response to a single client based query. For Bulk Leasequery, client based queries are not supported, and so the associated-ip option is not used, and MUST NOT be present in replies. 6.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. 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, and some of these will be time in the context of the requestor and some will be time in the context of the DHCPv4 server. Kinnear Expires December 2008 [Page 16] Internet Draft Bulk DHCPv4 Lease Query July 2008 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. In addition to saving the base-time for future use in a query-start- time option, the base-time is used as part of the conversion of the other times in the Leasequery message to values which are meaningful in the context of the requestor. The requestor SHOULD use the base-time values received in Leasequery messages to develop a value which represents the clock skew between the DHCPv4 server and the requestor. In theory this clock skew would simply be the difference between the first base-time value and the current time on the requestor when the message containing the base- time value was received. However, there may be transmission delays at the beginning or end or along the TCP connection, and so the actual clock skew may not be the same as any individual difference between a base-time value and the current time of the requestor. The requestor SHOULD smooth the value which it uses as the clock skew by continuously examining the instantaneous value developed from the base-time of each message received from a DHCPv4 server and using this instantaneous value of clock skew to make small adjustments to the existing value of the clock skew. Thus, the clock skew will vary only slowly and one slow message will not completely distort a large number of future time calculations. Given the value of the clock skew on the requestor, the requestor SHOULD bring all of the times in the DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED messages into the context of the requestor. Except for the base-time value, the times in the Leasequery message are all relative to the base-time. These relative times SHOULD first be converted into absolute times in the context of the DHCPv4 server using the base-time value. Once this stage is complete, the absolute times that result SHOULD be brought into the context of the requestor by applying the calculated clock skew to each of the absolute times. After all of this processing, the times are in the context of the requestor. An alternative might appear to be to leave all of the times in the context of the DHCPv4 server, and if the requestor is dealing with only one DHCPv4 server at a time, this is an accurate and effective approach. However, if the requestor is dealing with DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED messages from two or more different DHCPv4 Kinnear Expires December 2008 [Page 17] Internet Draft Bulk DHCPv4 Lease Query July 2008 servers, then in order to make any sense of them, the times from each server SHOULD be converted into the time of the requestor. Since various transmission and processing delays may occur, a time converted into the requestor's context may be accurate to only a few seconds, at best. This is rarely an issue in the larger context of the use of the information derived from a Bulk Leasequery request. However, time comparison is an important factor in determining which update to the address binding information for a particular IPv4 address is the most recent and therefore worth remembering. The next section discusses the issue of comparing two updates in some detail, but a key aspect of that comparison is a comparison of the times in the two messages. The requestor SHOULD consider times converted into its context as effectively equivalent if they are within a small number of seconds of each other. The precise number depends on the particular implementation involved, but 4 to 8 seconds is probably a good starting point. Thus, if two times are 3 seconds apart after conversion to the requestor's context they should be considered the same for purposes of comparison with each other. 6.5. 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 a single DHCPv4 server as well as 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". 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. Kinnear Expires December 2008 [Page 18] Internet Draft Bulk DHCPv4 Lease Query July 2008 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 the 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 which 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. 6.6. Querying Multiple Servers A Bulk Leasequery client 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 the Section 6.5 should be used. 6.7. 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 client 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. 7. Server Behavior 7.1. Accepting Connections Servers that implement DHCPv4 Bulk Leasequery listen for incoming TCP connections. Port numbers are discussed in Section 5.3. Servers MUST be able to limit the number of currently accepted and active connections. The value BULK_LQ_MAX_CONNS MUST 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 clients. Connections not from permitted clients SHOULD be closed immediately, to avoid server Kinnear Expires December 2008 [Page 19] Internet Draft Bulk DHCPv4 Lease Query July 2008 connection resource exhaustion. If a DHCPv4 server receives more than one DHCPBULKLEASEQUERY message on a connection without transmission of an intervening DHCPLEASEQUERYDONE message by that DHCPv4 server, it SHOULD send a DHCPLEASEQUERYSTATUS message containing a dhcp-status-code of NotAllowed and then drop 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 an BULK_LQ_QUERY_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. 7.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 BULK_LQ_DATA_TIMEOUT. 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 an error code of some kind in a dhcp-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 without a dhcp-status-code option. Otherwise, the server sends each binding's data in a DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message. The response to a DHCPBULKLEASEQUERY almost certainly entails a scan of many if not all all existing DHCPv4 IP address bindings maintained by the DHCPv4 server. These bindings may be scanned in any order convenient to the DHCPv4 server and the messages sent to the requestor may be in any order as well. Information concerning every configured IPv4 address (whether or not currently bound to a DHCPv4 client) MUST be sent in response to a Bulk Leasequery, subject to any constraints on the information sent imposed in the request. In the event that the DHCPBULKLEASEQUERY request contains a query- start-time option or a query-end-time option or both, only those address bindings which changed on or after the query-start-time time specified or changed on or before the query-end-time time specified (or both, if both option appear) SHOULD be sent to the requestor. If there is no query-start-time or query-end-time option in the Kinnear Expires December 2008 [Page 20] Internet Draft Bulk DHCPv4 Lease Query July 2008 DHCPBULKLEASEQUERY request, then the query-start-time is assumed to be prior to the earliest time of any IP address binding, and the query-end-time is assumed to be the time of the query. This is to prevent the Bulk Leasequery from getting caught by a busy server and never terminating. Even if the query-start-time or query-end-time option value is being used to limit the amount of data flow from the DHCPv4 server to the requestor, there is no requirement placed on the DHCPv4 server to return address binding data in any order and certainly not in any order based on time. When the DHCPv4 server has no additional information to send to the requestor, it will send a DHCPLEASEQUERYDONE message. 7.3. Building a Single Reply for Bulk Leasequery The DHCPv4 Leasequery [RFC4388] specification 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 is described in this document in Section 5.1. In addition to the basic message construction described in [RFC4388], the following guidelines exist: 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. 1. The DHCPv4 server MUST 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. 2. 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. The DHCPv4 server MUST include a state-time-of-state option whose value represents the time at which the dhcp-state option's state became valid. 4. The DHCPv4 server MUST include a dhcp-lease-time option for any state that has a time-out value associated with it, and not Kinnear Expires December 2008 [Page 21] Internet Draft Bulk DHCPv4 Lease Query July 2008 just appear in a DHCPLEASEACTIVE message. Thus, the EXPIRED state which is sent in a DHCPLEASEUNASSIGNED message would have a dhcp-lease-time option in the message if the EXPIRED state represented a grace-period and would be changing state after the grace-period expired. 5. 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 were zero. 6. 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. Note that there may be other requirements for a reply to a DHCPBULKLEASEQUERY request discussed in Section 7.2. 7.4. Multiple or Parallel Queries A single connection MUST be used for a single Bulk Leasequery request. Servers MUST NOT process two queries on the same connection at the same time. 7.5. Closing Connections The server MAY close its end of the TCP connection after sending its last message, a DHCPLEASEQUERYDONE message in response to a query. Alternatively, the server MAY retain the connection and wait for additional queries from the client. The server SHOULD be prepared to limit the number of connections it maintains, and SHOULD be prepared to 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 clients by using the QueryTerminated status code in the dhcp-status-code option in a DHCPLEASEQUERYDONE message. If the server detects that the client end has been closed, the server MUST close its end of the connection after it has finished processing any outstanding requests. The server MUST send a DHCPLEASEQUERYDONE message at the end of the data returned from a Bulk Leasequery request. Kinnear Expires December 2008 [Page 22] Internet Draft Bulk DHCPv4 Lease Query July 2008 8. 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 clients, 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, such as SYN flooding attacks, can compromise the ability of legitimate clients to receive service. Malicious clients 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. 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. 9. IANA Considerations IANA is requested to assign the following new values for this document. See Section 5.2 for details. 1. A dhcp-message-type of 14 for DHCPBULKLEASEQUERY. 2. A dhcp-message-type of 15 for DHCPLEASEQUERYDONE. 3. A dhcp-message-type of 16 for DHCPLEASEQUERYSTATUS. 4. An option code of TBD for dhcp-status-code. 5. An option code of TBD for base-time. 6. An option code of TBD for start-time-of-state. 7. An option code of TBD for query-start-time. 8. An option code of TBD for query-end-time. 9. An option code of TBD for dhcp-state. 10.Values for dhcp-status-code: Kinnear Expires December 2008 [Page 23] Internet Draft Bulk DHCPv4 Lease Query July 2008 Name status-code ---- ----------- Success 0 UnspecFail 1 QueryTerminated 2 MalformedQuery 3 NotAllowed 4 12.Values for dhcp-state: State ----- 1 AVAILABLE 2 ACTIVE 3 EXPIRED 4 RELEASED 5 ABANDONED 6 RESET 7 REMOTE 10. Acknowledgements The ideas in this document came from in part from the DHCPv6 Bulk Leasequery protocol documents as well as from in depth discussions between the authors. 11. References 11.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March 1997. [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", RFC 2131, March 1997. [RFC4301] Kent, S., Seo, K., "Security Architecture for the Internet Protocol", RFC4301, December 2005. [RFC4388] Woundy, R., Kinnear, K., "Dynamic Host Configuration Protocol (DHCP) Leasequery", RFC 4388, February 2006. Kinnear Expires December 2008 [Page 24] Internet Draft Bulk DHCPv4 Lease Query July 2008 11.2. Informative References [RFC951] Croft, B., Gilmore, J., "Bootstrap Protocol (BOOTP)", RFC 951, September 1985. [RFC1542] Wimer, W., "Clarifications and Extensions for the Bootstrap Protocol", RFC 1542, October 1993. [RFC2132] Alexander, S., Droms, R., "DHCP Options and BOOTP Vendor Extensions", RFC 2132, March 1997. [DHCPv6Bulk] Stapp, M., "DHCPv6 Bulk Leasequery", draft-ietf-dhc- dhcpv6-bulk-leasequery-03.txt, June 2008. 12. Authors' Addresses Kim Kinnear Cisco Systems 1414 Massachusetts Ave. Boxborough, Massachusetts 01719 Phone: (978) 936-0000 EMail: kkinnear@cisco.com Bernie Volz Cisco Systems 1414 Massachusetts Ave. Boxborough, Massachusetts 01719 Phone: (978) 936-0000 EMail: volz@cisco.com Neil Russell Cisco Systems 1414 Massachusetts Ave. Boxborough, Massachusetts 01719 Phone: (978) 936-0000 EMail: nrussell@cisco.com Kinnear Expires December 2008 [Page 25] Internet Draft Bulk DHCPv4 Lease Query July 2008 Mark Stapp Cisco Systems 1414 Massachusetts Ave. Boxborough, Massachusetts 01719 Phone: (978) 936-0000 EMail: mjs@cisco.com 13. Full Copyright Statement Copyright (C) The IETF Trust (2008). 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, THE IETF TRUST 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. 14. 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 Kinnear Expires December 2008 [Page 26] Internet Draft Bulk DHCPv4 Lease Query July 2008 ietf-ipr@ietf.org. 15. Acknowledgment Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Kinnear Expires December 2008 [Page 27]