idnits 2.17.1 draft-ietf-dhc-dhcpv4-active-leasequery-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (June 3, 2014) is 3615 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group K. Kinnear 3 Internet-Draft M. Stapp 4 Intended status: Standards Track B. Volz 5 Expires: December 5, 2014 Cisco Systems 6 N. Russell 7 Staples 8 June 3, 2014 10 Active DHCPv4 Lease Query 11 draft-ietf-dhc-dhcpv4-active-leasequery-01.txt 13 Abstract 15 The Dynamic Host Configuration Protocol for IPv4 (DHCPv4) has been 16 extended with a Leasequery capability that allows a client to request 17 information about DHCPv4 bindings. That mechanism is limited to 18 queries for individual bindings. In some situations individual 19 binding queries may not be efficient, or even possible. In addition, 20 continuous update of an external client with Leasequery data is 21 sometimes desired. This document expands on the DHCPv4 Leasequery 22 protocol, and allows for active transfer of near real-time DHCPv4 23 address binding information data via TCP. 25 Status of This Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on December 5, 2014. 42 Copyright Notice 44 Copyright (c) 2014 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 60 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 5 62 4. Interaction Between Active Leasequery and Bulk Leasequery . . 6 63 5. Message and Option Definitions . . . . . . . . . . . . . . . 7 64 5.1. Message Framing for TCP . . . . . . . . . . . . . . . . . 7 65 5.2. New or Changed Options . . . . . . . . . . . . . . . . . 7 66 5.2.1. dhcp-message-type . . . . . . . . . . . . . . . . . . 7 67 5.2.2. dhcp-status-code . . . . . . . . . . . . . . . . . . 8 68 5.3. Connection and Transmission Parameters . . . . . . . . . 9 69 6. Information Communicated by Active Leasequery . . . . . . . . 9 70 7. Requestor Behavior . . . . . . . . . . . . . . . . . . . . . 10 71 7.1. Connecting and General Processing . . . . . . . . . . . . 10 72 7.2. Forming an Active Leasequery . . . . . . . . . . . . . . 11 73 7.3. Processing Active Replies . . . . . . . . . . . . . . . . 12 74 7.3.1. Processing Replies from a Request Containing a query- 75 start-time . . . . . . . . . . . . . . . . . . . . . 14 76 7.4. Closing Connections . . . . . . . . . . . . . . . . . . . 16 77 8. Server Behavior . . . . . . . . . . . . . . . . . . . . . . . 16 78 8.1. Accepting Connections . . . . . . . . . . . . . . . . . . 16 79 8.2. Replying to an Active Leasequery . . . . . . . . . . . . 17 80 8.3. Multiple or Parallel Queries . . . . . . . . . . . . . . 19 81 8.4. Closing Connections . . . . . . . . . . . . . . . . . . . 19 82 9. Security Considerations . . . . . . . . . . . . . . . . . . . 20 83 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20 84 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 21 85 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 21 86 12.1. Normative References . . . . . . . . . . . . . . . . . . 21 87 12.2. Informative References . . . . . . . . . . . . . . . . . 21 88 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 90 1. Introduction 92 The DHCPv4 Leasequery capability [RFC4388] extends the basic DHCPv4 93 capability [RFC2131] [RFC2132] to allow an external entity to query a 94 DHCPv4 server to recover lease state information about a particular 95 IPv4 address or client in near real-time. 97 Requirements exist for external entities to keep up to date on the 98 correspondence between DHCPv4 clients and the IPv4 addresses for 99 which they have leases. These requirements often stem from 100 regulatory requirements placed on service providers by governmental 101 agencies. 103 These entities need to keep up with the current IPv4 address binding 104 activity of the DHCPv4 server. Keeping up with address binding 105 activity is termed "active" leasequery. 107 The DHCPv4 Bulk Leasequery [RFC6926] capability can be used to 108 recover useful information from a DHCPv4 server when some external 109 entity starts up. This entity could be one which is directly 110 involved in the DHCPv4 client - server transactions (e.g., a relay 111 agent), or it could be an external process which needs information 112 present in the DHCPv4 server's lease state database. 114 The Active Leasequery capability documented here is designed to allow 115 an entity not directly involved in DHCPv4 client - server 116 transactions to nevertheless keep current with the state of the 117 DHCPv4 lease state information in real-time. 119 2. Terminology 121 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 122 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 123 document are to be interpreted as described in [RFC2119]. 125 This document uses the following terms: 127 o "address binding" 129 The information that a DHCPv4 server keeps regarding the 130 relationship between a DHCPv4 client and an IPv4 address. This 131 includes the identity of the DHCPv4 client and the expiration 132 time, if any, of any lease that client has on a particular IPv4 133 address. 135 o "Active Leasequery" 137 Keeping up to date in real-time (or near real-time) with DHCPv4 138 address binding activity. 140 o "Bulk Leasequery" 142 Requesting and receiving the information about all or some of the 143 existing DHCPv4 address binding information in an efficient 144 manner, as defined by [RFC6926]. 146 o "catch-up information, catch-up phase" 148 If a DHCPv4 Active Leasequery requestor sends in a query-start- 149 time option in a DHCPACTIVELEASEQUERY message, the DHCPv4 server 150 will attempt to send the requestor the information that changed 151 since the time specified in the query-start-time option. The 152 address binding information sent to satisfy this request is the 153 catch-up information, and the period while it is being sent is the 154 catch-up phase. 156 o "clock skew" 158 The difference between the absolute time on a DHCPv4 server and 159 the absolute time on the system where a requestor of an Active or 160 Bulk Leasequery is executing is termed the "clock skew" for that 161 Active or Bulk Leasequery connection. It is not absolutely 162 constant but is likely to vary only slowly. While it is easy to 163 think that this can be calculated precisely after one packet is 164 received by a requestor from a DHCPv4 server, a more accurate 165 value is derived from continuously examining the instantaneous 166 value developed from each packet received from a DHCPv4 server and 167 using it to make small adjustments to the existing value held in 168 the requestor. 170 o "DHCPv4 client" 172 A DHCPv4 client is an IPv4 node using DHCP to obtain configuration 173 parameters such as a network address. 175 o "DHCPv4 relay agent" 177 A DHCPv4 relay agent is a third-party agent that transfers BOOTP 178 and DHCPv4 messages between clients and servers residing on 179 different subnets, per [RFC0951] and [RFC1542]. 181 o "DHCPv4 server" 183 A DHCPv4 server is an IPv4 node that returns configuration 184 parameters to DHCPv4 clients. 186 o "IP address binding" 188 The information that a DHCPv4 server keeps regarding the 189 relationship between a DHCPv4 client and an IPv4 address. This 190 includes the identity of the DHCPv4 client and the expiration 191 time, if any, of any lease that client has on a particular IPv4 192 address. 194 o "MAC address" 196 In the context of a DHCP message, a MAC address consists of the 197 fields: hardware type "htype", hardware length "hlen", and client 198 hardware address "chaddr". 200 o "requestor" 202 The node that sends LEASEQUERY messages to one or more servers to 203 retrieve information on the bindings for a client. 205 3. Protocol Overview 207 The Active Leasequery mechanism is modeled on the existing individual 208 Leasequery protocol in [RFC4388] as well as related work on DHCPv4 209 Bulk Leasequery [RFC6926]; most differences arise from the long term 210 nature of the TCP connection required for Active Leasequery. In 211 addition, a DHCPv4 server which supports Active Leasequery MUST 212 support Bulk Leasequery [RFC6926] as well. 214 An Active Leasequery client opens a TCP connection to a DHCPv4 215 Server, using the DHCPv4 port 67. Note that this implies that the 216 Leasequery client has the server IPv4 address(es) available via 217 configuration or some other means, and that it has unicast IP 218 reachability to the DHCPv4 server. The message framing for TCP is 219 discusssed in Section 5.1. No relaying for Active Leasequery is 220 specified. 222 After establishing a connection, the client sends an 223 DHCPACTIVELEASEQUERY message over the connection. In response, the 224 server sends updates to the requestor using DHCPLEASEACTIVE and 225 DHCPLEASEUNASSIGNED messages which are extensions of these messages 226 as defined in [RFC4388] and [RFC6926]. 228 Active Leasequery is designed to provide continuous updates of DHCPv4 229 IPv4 address binding activity to an external entity. 231 Active Leasequery has features which allow this external entity to 232 lose its connection and then reconnect and receive the latest 233 information concerning any IPv4 addresses changed while it was not 234 connected. 236 These capabilities are designed to allow the Active Leasequery 237 requestor to efficiently become current with respect to the lease 238 state database after it has been restarted or the machine on which it 239 is running has been reinitialized. It is easy to define a protocol 240 which works when the requestor is always connected to the DHCPv4 241 server. Since that isn't sufficiently robust, much of the mechanism 242 in this document is designed to deal efficiently with situations that 243 occur when the Active Leasequery requestor becomes disconnected from 244 the DHCPv4 server from which it is receiving updates and then becomes 245 reconnected to that server. 247 Central to this approach, if the Active Leasequery requestor loses 248 service, it is allowed to specify the time of its most recent update 249 in a subsequent Active Leasequery request and the DHCPv4 server will 250 determine whether or not data was missed while the Active Leasequery 251 requestor was not connected. 253 The DHCP server processing the Active Leasequery request may limit 254 the amount of data saved, and methods exist for the DHCPv4 server to 255 inform the Active Leasequery requestor that more data was missed than 256 could be saved. In this situation, the Active Leasequery requestor 257 would issue a Bulk Leasequery [RFC6926] to recover information not 258 available through an Active Leasequery. 260 DHCPv4 servers are not required to keep any data corresponding to 261 data missed on a Active Leasequery connection, but will typically 262 choose to keep data corresponding to some recent activity available 263 for subsequent queries by a DHCPv4 Active Leasequery client whose 264 connection was temporarily interrupted. 266 An Active Leasequery requestor would typically use Bulk Leasequery to 267 initialize its database with all current data when that database 268 contains no address binding information. In addition, it would use 269 Bulk Leasequery to recover missed information in the event that its 270 connection with the DHCPv4 server was lost for a longer time than the 271 DHCPv4 server would keep track of the specific changes to the IPv4 272 address binding information. 274 The messages sent by the server in response to an Active Leasequery 275 request SHOULD be identical to the messages sent by the server to a 276 Bulk Leasequery request regarding the way the data is encoded into 277 the Active Leasequery responses. In addition, the actions taken by 278 the Active Leasequery requestor to interpret the responses to an 279 Active Leasequery request SHOULD be identical to the way that the 280 requestor interprets the responses to a Bulk Leasequery request. 281 Thus, the handling of time, clock skew, data source, and other items 282 discussed in the Bulk Leasequery specification [RFC6926] are to be 283 followed when implementing Active Leasequery. 285 4. Interaction Between Active Leasequery and Bulk Leasequery 287 Active Leasequery can be seen as an extension of the Bulk Leasequery 288 protocol [RFC6926]. The contents of packets returned to an Active 289 Leasequery requestor are identical to that defined for the Bulk 290 Leasequery protocol. 292 Applications which employ Active Leasequery to keep a database up to 293 date with respect to the DHCPv4 server's lease state database will 294 usually use an initial Bulk Leasequery to bring their database into 295 equivalence with that of the DHCPv4 server, and then use Active 296 Leasequery to keep that database current with respect to the DHCPv4 297 server's lease state database. 299 There are several differences between the Active and Bulk Leasequery 300 protocols. Active Leasequery defines only one qualifier (the query- 301 start-time) and no query types, while Bulk Leasequery defines several 302 query types and qualifiers. An Active Leasequery connection sends 303 all available updates to the requestor. 305 An Active Leasequery connection does not ever "complete", though the 306 DHCPv4 server may drop the connection for a variety of reasons 307 associated with some sort of exception condition. 309 5. Message and Option Definitions 311 5.1. Message Framing for TCP 313 The use of TCP for the Active Leasequery protocol permits one or more 314 DHCPv4 messages to be sent at a time. The receiver needs to be able 315 to determine how large each message is. The same framing technique 316 used for Bulk Leasequery [RFC6926] is used for Active Leasequery. 318 5.2. New or Changed Options 320 The existing messages DHCPLEASEUNASSIGNED and DHCPLEASEACTIVE are 321 used as the value of the dhcp-message-type option to indicate an IPv4 322 address which is currently not leased or currently leased to a DHCPv4 323 client, respectively. 325 All of the message types and options defined for Bulk Leasequery 326 [RFC6926] are also used by Active Leasequery. In addition, new 327 message types and option types are defined for Active Leasequery, as 328 described below. 330 5.2.1. dhcp-message-type 332 The message type option (option 53) from [RFC2132] requires 333 additional values. The values of these message types are shown below 334 in an extension of the table from Section 9.6 of [RFC2132]: 336 +-------+----------------------+ 337 | Value | Message Type | 338 +-------+----------------------+ 339 | TBD1 | DHCPACTIVELEASEQUERY | 340 | TBD2 | DHCPLEASEQUERYSTATUS | 341 +-------+----------------------+ 343 5.2.2. dhcp-status-code 345 The dhcp-status-code option defined in [RFC6926] allows greater 346 detail to be returned regarding the status of a DHCP request. While 347 specified in the Bulk Leasequery document, this DHCPv4 option is also 348 used in Active Leasequery. 350 This option has two possible scopes when used with Active Leasequery, 351 depending on the context in which it appears. It refers to the 352 information in a single leasequery reply if the value of the dhcp- 353 message-type is DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED. It refers to 354 the message stream related to an entire request if the value of the 355 dhcp-message-type is DHCPLEASEQUERYSTATUS. 357 Additional status codes defined for support of Active Leasequery are: 359 +------------------+-------------+----------------------------------+ 360 | Name | status-code | Description | 361 +------------------+-------------+----------------------------------+ 362 | DataMissing | TBD3 | Indicates that IPv4 address | 363 | | | binding information requested is | 364 | | | not available. | 365 | ConnectionActive | TBD4 | Indicates that this connection | 366 | | | remains active. | 367 | CatchUpComplete | TBD5 | Indicates that this Active | 368 | | | Leasequery connection has | 369 | | | completed sending all of the | 370 | | | saved data requested. | 371 +------------------+-------------+----------------------------------+ 373 A dhcp-status-code option MAY appear in the options field of a DHCP 374 message. If the dhcp-status-code option does not appear, it is 375 assumed that the operation was successful. The dhcp-status-code 376 option SHOULD NOT appear in a message which is successful unless it 377 is needed to convey some text message along with the Success status 378 code. 380 5.3. Connection and Transmission Parameters 382 DHCPv4 servers that support Active Leasequery SHOULD listen for 383 incoming TCP connections on port 67. Implementations MAY offer to 384 make the incoming port configurable, but port 67 MUST be the default. 385 Requestors SHOULD make TCP connections to port 67, and MAY offer to 386 make the destination server port configurable. 388 This section presents a table of values used to control Active 389 Leasequery behavior, including recommended defaults. Implementations 390 MAY make these values configurable. However, configuring too-small 391 timeout values may lead to harmful behavior both to this application 392 as well as to other traffic in the network. As a result, timeout 393 values smaller than the default values SHOULD NOT be used. 395 +------------------------+---------+--------------------------------+ 396 | Parameter | Default | Description | 397 +------------------------+---------+--------------------------------+ 398 | BULK_LQ_DATA_TIMEOUT | * | Bulk Leasequery data timeout | 399 | BULK_LQ_MAX_CONNS | * | Max Bulk Leasequery TCP | 400 | | | connections | 401 | ACTIVE_LQ_RCV_TIMEOUT | 120 | Active Leasequery receive | 402 | | secs | timeout | 403 | ACTIVE_LQ_SEND_TIMEOUT | 120 | Active Leasequery send timeout | 404 | | secs | | 405 | ACTIVE_LQ_IDLE_TIMEOUT | 60 secs | Active Leasequery idle timeout | 406 +------------------------+---------+--------------------------------+ 408 * See Section 6.3 of [RFC6926] for specific default values. 410 6. Information Communicated by Active Leasequery 412 While the information communicated by a Bulk Leasequery [RFC6926] is 413 taken directly from the DHCPv4 server's lease state database, the 414 information communicated by an Active Leasequery is real-time 415 information. As such, it is the information which is currently 416 associated with a particular IPv4 address in the DHCPv4 server's 417 lease state database. 419 This is of significance, because if the Active Leasequery requestor 420 runs slowly or the requestor disconnects from the DHCPv4 server and 421 then reconnects with a query-start-time (signaling a catch-up 422 operation), the information communicated to the Active Leasequery 423 requestor is only the most current information from the DHCPv4 424 server's lease state database. 426 The requestor of an Active Leasequery MUST NOT assume that every 427 lease state change is communicated across an Active Leasequery 428 connection. Even if the Active Leasequery requestor remains 429 connected, the DHCPv4 server is only required to transmit information 430 about an IPv4 address that is current when the packet is created and 431 handed off to the TCP stack to send to the requestor. 433 If the TCP connection blocks and the DHCPv4 server is waiting to send 434 information down the connection, when the connection becomes 435 available to be written the DHCPv4 server MAY create the packet to 436 send at this time. The current state of the IPv4 address will be 437 sent, and any transition in state or other information that occurred 438 while the TCP connection was blocked will be lost. 440 Thus, the Active Leasequery protocol does not allow the requestor to 441 build a complete history of every activity on every lease. An 442 effective history of the important state changes for a lease can be 443 created if the parameters of the DHCPv4 server are tuned to take into 444 account the requirements of an Active Leasequery requestor. For 445 instance, the period after the expiration or release of an IPv4 446 address could be configured long enough (say several minutes, well 447 more than the receive timeout), so that an Active Leasequery 448 requestor would never miss any changes in the client to IPv4 address 449 binding. 451 7. Requestor Behavior 453 7.1. Connecting and General Processing 455 A Requestor attempts to establish a TCP connection to a DHCPv4 Server 456 in order to initiate a Leasequery exchange. If the attempt fails, 457 the Requestor MAY retry. 459 If an Active Leasequery is terminated prematurely by a 460 DHCPLEASEQUERYDONE with a dhcp-message status-code of QueryTerminated 461 or by the failure of the connection over which it was being 462 submitted, the requestor MAY retry the request after the creation of 463 a new connection. 465 Messages from the DHCPv4 server come as multiple responses to a 466 single DHCPACTIVELEASEQUERY message. Thus, each DHCPACTIVELEASEQUERY 467 or DHCPBULKLEASEQUERY request MUST have an xid (transaction-id) 468 unique on the connection on which it is sent, and all of the messages 469 which come as a response to it all contain the same xid as the 470 request. It is the xid which allows the data-streams of two or more 471 different DHCPACTIVELEASEQUERY or DHCPBULKLEASEQUERY requests to be 472 demultiplexed by the requestor. 474 A requestor MAY send a DHCPACTIVELEASEQUERY request to a DHCPv4 475 server and immediately close the transmission side of its TCP 476 connection, and then read the resulting response messages from the 477 DHCPv4 server. This is not required, and the usual approach is to 478 leave both sides of the TCP connection up until at least the 479 conclusion of the Active Leasequery. 481 7.2. Forming an Active Leasequery 483 The Active Leasequery is designed to create a long lived connection 484 between the requestor and the DHCPv4 server processing the active 485 query. The DHCPv4 server will send IPv4 address binding information 486 back across this connection with minimal delay after it learns of the 487 binding information. It will learn about IPv4 address bindings 488 either because it makes the bindings itself or because it has 489 received information about a binding from another server. 491 To form the Active query, a DHCPv4 request is constructed with a 492 dhcp-message-type of DHCPACTIVELEASEQUERY. This DHCPv4 request MUST 493 NOT have a ciaddr, a chaddr, or a dhcp-client-identifier. The DHCPv4 494 request MUST contain a transaction-id, and that transaction-id MUST 495 be locally unique to the TCP connection to the DHCPv4 server. The 496 DHCPv4 request SHOULD have a dhcp-parameter-request-list to inform 497 the DHCPv4 server which DHCPv4 options are of interest to the 498 requestor sending the DHCPACTIVELEASEQUERY message. 500 An important capability of the Active Leasequery is the ability of 501 the requestor to specify that some recent data be sent immediately to 502 the requestor in parallel with the transmission of the ongoing IPv4 503 address binding information in more or less real time. This 504 capability is used in order to allow an Active Leasequery requestor 505 to recover missed information in the event that it temporarily loses 506 connectivity with the DHCPv4 server processing a previous Active 507 Leasequery. 509 Note that until all of the recent data (catch-up data) has been 510 received, the requestor MUST NOT keep track of the base time received 511 in Leasequery reply messages to use later in a subsequent Bulk 512 Leasequery or Active Leasequery request. 514 This capability is enabled by the transmission of a 4 octet base-time 515 option with each Leasequery reply sent as the result of a previous 516 Active Leasequery. The requestor will typically keep track of the 517 highest base-time received from a particular DHCPv4 server over an 518 Active Leasequery connection, and in the event that the requestor 519 finds it necessary (for whatever reason) to reestablish an Active 520 Leasequery connection to that DHCPv4 server, the requestor will place 521 this highest base-time value into a query-start-time option in the 522 new DHCPACTIVELEASEQUERY request. (See Sections 6.2.5 and 7.2 of 523 [RFC6926] for information on the query-start-time option.) 524 If the requestor doesn't wish to request an update of information 525 missed when it was not connected to the DHCPv4 server, then it does 526 not include the query-start-time option in the DHCPACTIVELEASEQUERY 527 request. 529 If the TCP connection becomes blocked or stops being writable while 530 the requestor is sending its query, the requestor SHOULD be prepared 531 to terminate the connection after BULK_LQ_DATA_TIMEOUT. We make this 532 recommendation to allow requestors to control the period of time they 533 are willing to wait before abandoning a connection, independent of 534 notifications from the TCP implementations they may be using. 536 7.3. Processing Active Replies 538 The Requestor attempts to read a DHCPv4 leasequery reply message from 539 the TCP connection. If the stream of replies becomes blocked, the 540 Requestor SHOULD be prepared to terminate the connection after 541 ACTIVE_LQ_RCV_TIMEOUT, and MAY begin retry processing if configured 542 to do so. 544 Note that a DHCPACTIVELEASEQUERY request specifically requests the 545 DHCPv4 server to create a long-lived connection which may not have 546 data transferring continuously during its lifetime. Therefore the 547 DHCPv4 server will send a DHCPLEASEQUERYSTATUS message with a dhcp- 548 status-code of ConnectionActive every ACTIVE_LQ_IDLE_TIMEOUT seconds 549 (default 60) in order for the requestor to know that the connection 550 remains alive. Note that the default for ACTIVE_LQ_RCV_TIMEOUT is 551 120 seconds, twice the value of the ACTIVE_LQ_IDLE_TIMEOUT's default 552 of 60 seconds which drives the DHCPv4 server to send messages. Thus 553 ACTIVE_LQ_RCV_TIMEOUT controls how sensitive the requestor is to be 554 to delays by the DHCPv4 server in sending updates or 555 DHCPLEASEQUERYSTATUS messages. 557 A successful query that is returning binding data MUST include a non- 558 zero ciaddr. It may also include a non-zero chaddr, htype, and hlen 559 as well as additional options. If there are additional bindings to 560 be returned, they will be carried in additional Active Leasequery 561 messages. 563 Any requestor of an Active Leasequery operation MUST be prepared to 564 receive multiple copies of the IPv4 address binding information for a 565 particular IPv4 address. See the Bulk Leasequery document [RFC6926] 566 for information on how to deal with this situation. 568 A single Active Leasequery can and usually will result in a large 569 number of replies. The Requestor MUST be prepared to receive more 570 than one reply with transaction-ids matching a single 571 DHCPACTIVELEASEQUERY message from a single DHCPv4 server. 573 A DHCPACTIVELEASEQUERY has two regimes -- during the catch-up phase, 574 if any, and after any catch-up phase. During the catch-up phase (if 575 one exists), the data returned in the base-time option in a 576 DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message may appear to be 577 ordered, but the most recent change in the lease state data being 578 returned is not related to the base-time option value in the 579 messages. Another way to say this is that the ordering of the 580 updates sent by the DHCPv4 server during the catch-up phase is 581 independent of the ordering in the changes in the lease state data. 582 The base-time option from messages during this phase MUST NOT be 583 saved and used in a subsequent DHCPACTIVELEASEQUERY message's query- 584 start-time option as it does not represent the extent of progress of 585 the catch-up activity. 587 After the catch-up phase, or during the entire series of messages 588 received as the response to a DHCPACTIVELEASEQUERY request with no 589 query-start-time (and therefore no catch-up phase), the base-time 590 option of the most recent message SHOULD be saved as a record of the 591 most recent time that data was received. This base-time (in the 592 context of the DHCPv4 server) can be used in a subsequent 593 DHCPACTIVELEASEQUERY message's query-start-time, or in a 594 DHCPBULKLEASEQUERY message's query-start-time if one is required, 595 after a loss of the Active Leasequery connection. 597 The DHCPLEASEQUERYSTATUS message MAY unilaterally terminate a 598 successful DHCPACTIVELEASEQUERY request which is currently in 599 progress in the event that the DHCPv4 server determines that it 600 cannot continue processing a DHCPACTIVELEASEQUERY request. For 601 example, when a server is requested to shut down it SHOULD send a 602 DHCPLEASEQUERYSTATUS message with a dhcp-status-code of 603 QueryTerminated and include in the message a base time. This SHOULD 604 be the last message on that connection, and once the message has been 605 transmistted, the server should close the connection. 607 After receiving DHCPLEASEQUERYSTATUS with a QueryTerminated status 608 from a server, the Requestor MAY close the TCP connection to that 609 server. 611 The DHCPv4 Leasequery protocol uses the associated-ip option as an 612 indicator that multiple bindings were present in response to a single 613 client based query. For Active Leasequery, client-based queries are 614 not supported and so the associated-ip option is not used, and MUST 615 NOT be present in replies. 617 7.3.1. Processing Replies from a Request Containing a query-start-time 619 If the DHCPACTIVELEASEQUERY was requested with a query-start-time, 620 the DHCPv4 server will attempt to send information about all IPv4 621 address bindings that changed since the time specified in the query- 622 start-time. This is the catch-up phase of the DHCPACTIVELEASEQUERY 623 processing. The DHCPv4 server MAY also begin immediate updates over 624 the same connection of real-time IPv4 address binding information 625 changes. Thus, the catch-up phase may run in parallel with the 626 normal updates generated by the DHCPACTIVELEASEQUERY request. 628 A DHCPv4 server MAY keep only a limited amount of time ordered 629 information available to respond to a DHCPACTIVELEASEQUERY request 630 containing a query-start-time. Thus, it is possible that the time 631 specified in the query-start-time represents a time not covered by 632 the time ordered information kept by the DHCPv4 server. If this 633 should occur, and there is not enough data saved in the DHCPv4 server 634 to satisfy the request specified by the query-start-time option, the 635 DHCPv4 server will reply immediately with a DHCPLEASEQUERYSTATUS 636 message with a dhcp-status-code of DataMissing with a base-time 637 option equal to the server's current time. This will signal the end 638 of the catch-up phase, and the only updates that will subsequently be 639 received on this connection are the real-time updates from the 640 DHCPACTIVELEASEQUERY request. 642 If there is enough data saved to satisfy the request, then 643 DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED messages will begin arrive 644 from the DHCPv4 server. Some of these messages will be related to 645 the query-start-time request and be part of the catch-up phase. Some 646 of these messages will be real-time updates of IPv4 address binding 647 changes taking place in the DHCPv4 server. In general, there is no 648 way to determine the source each message. 650 Until the catch-up phase is complete, the latest base-time value 651 received from a DHCPv4 server processing an Active Leasequery request 652 cannot be reset from the incoming messages because to do so would 653 compromise the ability to recover lost information if the 654 DHCPACTIVELEASEQUERY were to terminate prior to the completion of the 655 catch-up phase. 657 The requestor will know that the catch-up phase is complete because 658 the DHCPv4 server will transmit a DHCPLEASEQUERYSTATUS message with 659 the dhcp-status-code of CatchUpComplete. Once this message is 660 transmitted, all additional DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED 661 messages will relate to real-time ("new") IPv4 address binding 662 changes in the DHCPv4 server. 664 As discussed in Section 6.3, the requestor SHOULD keep track of the 665 latest base-time option value received over a particular connection, 666 to be used in a subsequent DHCPACTIVELEASEQUERY request -- but only 667 if the catch-up phase is complete. Prior to the completion of the 668 catch-up phase, if the connection should go away or if the requestor 669 receives a DHCPLEASEQUERYDONE message, then when it reconnects it 670 MUST use the base-time value from the previous connection and not any 671 base-time value received from the recently closed connection. 673 In the event that there was enough data available to the DHCPv4 674 server to begin to satisfy the request implied by the query-start- 675 time option, but during the processing of that data the server found 676 that it was unable to continue (perhaps there was barely enough, the 677 connection is very slow, and the aging algorithm causes the saved 678 data to become unavailable) the DHCPv4 server will terminate the 679 catch-up phase of processing immediately by sending a 680 DHCPLEASEQUERYSTATUS message with a dhcp-status-code of DataMissing 681 and with a base-time option of the current time. 683 The requestor MUST NOT assume that every individual state change of 684 every IPv4 address during the period from the time specified in the 685 query-start-time and the present is replicated in an Active 686 Leasequery reply message. The requestor MAY assume that at least one 687 Active Leasequery reply message will exist for every IPv4 address 688 which had one or more changes of state during the period specified by 689 the query-start-time and the current time. The last message for each 690 IPv4 address will contain the state at the current time, and there 691 may be one or more messages concerning a single IPv4 address during 692 the catch-up phase of processing. 694 If an IPv4 address changed state multiple times during the time that 695 the requestor was not connected (that is, during the time from the 696 query-start-time and the present), then only the current IPv4 address 697 binding information will be sent during the catch-up phase. Thus, 698 the requestor MUST NOT assume that every intermediate state change 699 that occurred during the period from the query-start-time to the 700 present will be represented by an individual Leasequery message. 702 If the DHCPLEASEQUERYSTATUS message containing a dhcp-status-code of 703 DataMissing is received and the requestor is interested in keeping 704 its database up to date with respect to the current state of IPv4 705 address bindings in the DHCPv4 server, then the requestor SHOULD 706 issue a DHCPBULKLEASEQUERY request to recover the information missing 707 from its database. This DHCPBULKLEASEQUERY should include a query- 708 start-time, set to be the same as its query-start-time previously 709 included in the DHCPACTIVELEASEQUERY responses from the DHCPv4 710 server, and a query-end-time equal to the base-time returned by the 711 DHCPv4 server in the DHCPLEASEQUERYSTATUS message with the dhcp- 712 status-code of DataMissing. 714 In the event that the requestor receives a DHCPLEASEQUERYSTATUS 715 message with a dhcp-status-code of DataMissing, it is a reasonable 716 assumption that it is interested in keeping its database up to date 717 with respect to the DHCPv4 server's internal IPv4 address binding 718 database or it would not have included the query-start-time in the 719 DHCPACTIVELEASEQUERY message. 721 Typically, the requestor would have one connection open to a DHCPv4 722 server for a DHCPACTIVELEASEQUERY request and possibly one additional 723 connection open for a DHCPBULKLEASEQUERY request to the same DHCPv4 724 server to fill in the data that might have been missed prior to the 725 initiation of the DHCPACTIVELEASEQUERY. The Bulk Leasequery 726 connection would typically run to completion and be closed, leaving 727 one Active Leasequery connection open to a single DHCPv4 server. 728 Alternatively, both requests could be issued over a single 729 connection. 731 7.4. Closing Connections 733 The Requestor or DHCPv4 leasequery server MAY close its end of the 734 TCP connection at any time. The Requestor MAY choose to retain the 735 connection if it intends to issue additional queries. Note that this 736 client behavior does not guarantee that the connection will be 737 available for additional queries: the server might decide to close 738 the connection based on its own configuration. 740 8. Server Behavior 742 A DHCPv4 server which supports Active Leasequery MUST support Bulk 743 Leasequery [RFC6926] as well. 745 8.1. Accepting Connections 747 Servers that implement DHCPv4 Active Leasequery listen for incoming 748 TCP connections. Port numbers are discussed in Section 5.3. Servers 749 MUST be able to limit the number of currently accepted and active 750 connections. The value BULK_LQ_MAX_CONNS MUST be the default; 751 implementations MAY permit the value to be configurable. Connections 752 SHOULD be accepted and, if the number of connections is over 753 BULK_LQ_MAX_CONNS, they SHOULD be closed immediately. 755 Servers MAY restrict Active Leasequery connections and 756 DHCPACTIVELEASEQUERY messages to certain clients. Connections not 757 from permitted clients SHOULD be closed immediately, to avoid server 758 connection resource exhaustion. 760 If the TCP connection becomes blocked while the server is accepting a 761 connection or reading a query, it SHOULD be prepared to terminate the 762 connection after a BULK_LQ_DATA_TIMEOUT. We make this recommendation 763 to allow servers to control the period of time they are willing to 764 wait before abandoning an inactive connection, independent of the TCP 765 implementations they may be using. 767 8.2. Replying to an Active Leasequery 769 If the connection becomes blocked while the server is attempting to 770 send reply messages, the server SHOULD be prepared to terminate the 771 TCP connection after ACTIVE_LQ_SEND_TIMEOUT. This timeout governs 772 how much congestion the DHCPv4 server is prepared to tolerate over 773 any Active Leasequery connection. The default is two minutes, which 774 means that if more than two minutes goes by without the requestor 775 reading enough information to unblock the TCP connection, the DHCPv4 776 server will drop the TCP connection. 778 If the DHCPv4 server encounters an error during processing of the 779 DHCPACTIVELEASEQUERY message, either during initial processing or 780 later during the message processing, it SHOULD send a 781 DHCPLEASEQUERYSTATUS containing an error code of some kind in a dhcp- 782 status-code option. It SHOULD close the connection after this error 783 is signaled. 785 Every reply to a DHCPACTIVELEASEQUERY request MUST contain the 786 information specified in replies to a DHCPBULKLEASEQUERY request 787 [RFC6926]. 789 Some servers can be configured to respond to a DHCPv4 Leasequery 790 [RFC4388] or a DHCPBULKLEASEQUERY [RFC6926] for an IPv4 address which 791 is reserved in such a way that it appears that the IPv4 address is 792 leased to the DHCP client for which it is reserved. These servers 793 SHOULD also respond to a DHCPACTIVELEASEQUERY request with the same 794 information as they would to a DHCPBULKLEASEQUERY request when they 795 first determine that the IPv4 address is reserved to a DHCP client. 797 If a DHCPACTIVELEASEQUERY request contains a query-start-time option, 798 it indicates that the requestor would like the DHCPv4 server to send 799 it not only messages that correspond to DHCPv4 address binding 800 activity that occurs subsequent to the receipt of the DHCPLEASEACTIVE 801 request, but also messages that correspond to DHCPv4 address binding 802 activity that occurred prior to the DHCPACTIVELEASEQUERY request. 804 If a query-end-time option appears in a DHCPACTIVELEASEQUERY the 805 DHCPv4 server should send a DHCPLEASEQUERYSTATUS message with a dhcp- 806 status-code of MalformedQuery and terminate the connection. 808 In order to implement a meaningful response to this query, the DHCPv4 809 server MAY keep track of the address binding activity and associate 810 changes with particular base-time values from the messages. Then, 811 when requested to do so by a DHCPACTIVELEASEQUERY request containing 812 a query-start-time option, the DHCPv4 server can respond with replies 813 for all address binding activity occurring on that query-start-time 814 or later times. 816 These replies based on the query-start-time MAY be interleaved with 817 the messages generated due to current IPv4 address binding activity. 819 Once the transmission of the DHCPv4 Leasequery messages associated 820 with the query-start-time option are complete, a DHCPLEASEQUERYSTATUS 821 message MUST be sent with a dhcp-status-code value of 822 CatchUpComplete. 824 The DHCPv4 server SHOULD, but is not required to, keep track of a 825 limited amount of previous address binding activity and associate it 826 with base-time values. The DHCPv4 server MAY choose to only do this 827 in the event that it has received at least one DHCPACTIVELEASEQUERY 828 request in the past, as to do so will almost certainly entail some 829 utilization of resources which would be wasted if there are no 830 DHCPACTIVELEASEQUERY clients for this DHCPv4 server. The DHCPv4 831 server SHOULD make the amount of previous address binding activity it 832 retains configurable. There is no requirement on the DHCPv4 server 833 to retain this information over a server restart (or even to retain 834 such information at all). 836 Unless there is an error or some requirement to cease processing a 837 DHCPACTIVELEASEQUERY request yielding a DHCPLEASEQUERYSTATUS message, 838 such as a server shutdown, there will be no DHCPLEASEQUERYSTATUS 839 message at the conclusion of the DHCPACTIVELEASEQUERY processing 840 because that processing will not conclude but will continue until 841 either the client or the server drops the connection. 843 While the form of the data being sent by a DHCPACTIVELEASEQUERY is 844 essentially the same as that being sent by a DHCPBULKLEASEQUERY, the 845 reasons for sending information differs considerably between these 846 two capabilities. In the DHCPBULKLEASEQUERY context, the entire 847 contents of the lease state database (subject to the constraints of 848 the various query options) are returned to the requestor. In the 849 DHCPACTIVELEASEQUERY context, changes to the lease state database are 850 returned to the requestor essentially as they happen. For instance, 851 when an IPv4 address transitions from the leased state to some other 852 state, the DHCPACTIVELEASEQUERY will send a DHCPLEASEUNASSIGNED 853 packet with information regarding that IPv4 address. The server may 854 then entirely forget about that IPv4 address (or not), but it is 855 important to tell the DHCPACTIVELEASEQUERY client that an IPv4 856 address has transitioned away from the leased state. 858 The relationship between the time that the server replies to a DHCP 859 client request and the time that the DHCP server sends a reply to a 860 DHCPACTIVELEASEQUERY message is a matter of implementation (and thus 861 not something defined by this document). However, the server SHOULD 862 NOT delay responding to the DHCP client in order to transmit a reply 863 to a DHCPACTIVELEASEQUERY message, and the server SHOULD send the 864 reply to the DHCPACTIVELASEQUERY message as soon as possible after 865 responding to the client. 867 8.3. Multiple or Parallel Queries 869 Requestors may want to use an existing connection if they need to 870 make multiple queries. Servers MAY support reading and processing 871 multiple queries from a single connection. A server MUST NOT read 872 more query messages from a connection than it is prepared to process 873 simultaneously. 875 Typically, a requestor of a Active Leasequery would not need to send 876 a second Active Leasequery while the first is still active. However, 877 sending an Active Leasequery and a Bulk Leasequery over the same 878 connection would be possible and reasonable. 880 This MAY be a feature that is administratively controlled. Servers 881 that are able to process queries in parallel SHOULD offer 882 configuration that limits the number of simultaneous queries 883 permitted from any one requestor, in order to control resource use if 884 there are multiple requestors seeking service. 886 8.4. Closing Connections 888 The server MAY close its end of the TCP connection after sending its 889 last message, a DHCPLEASEQUERYSTATUS message in response to a query. 890 Alternatively, the server MAY retain the connection and wait for 891 additional queries from the client. The server SHOULD be prepared to 892 limit the number of connections it maintains, and SHOULD be prepared 893 to close idle connections to enforce the limit. 895 The server MUST close its end of the TCP connection if it encounters 896 an error sending data on the connection. The server MUST close its 897 end of the TCP connection if it finds that it has to abort an in- 898 process request. A server aborting an in-process request SHOULD 899 attempt to signal that to its clients by using the QueryTerminated 900 status code in the dhcp-status-code option in a DHCPLEASEQUERYSTATUS 901 message. If the server detects that the client end has been closed, 902 the server MUST close its end of the connection after it has finished 903 processing any outstanding requests. 905 9. Security Considerations 907 The "Security Considerations" section of [RFC2131] details the 908 general threats to DHCPv4. The DHCPv4 Leasequery specification 909 [RFC4388] describes recommendations for the Leasequery protocol, 910 especially with regard to relayed LEASEQUERY messages, mitigation of 911 packet-flooding DOS attacks, restriction to trusted clients, and use 912 of IPsec [RFC4301]. 914 This capability SHOULD be disabled by default. 916 The use of TCP introduces some additional concerns. Attacks that 917 attempt to exhaust the DHCPv4 server's available TCP connection 918 resources, such as SYN flooding attacks, can compromise the ability 919 of legitimate clients to receive service. Malicious clients who 920 succeed in establishing connections, but who then send invalid 921 queries, partial queries, or no queries at all also can exhaust a 922 server's pool of available connections. We recommend that servers 923 offer configuration to limit the sources of incoming connections, 924 that they limit the number of accepted connections and the number of 925 in-process queries from any one connection, and that they limit the 926 period of time during which an idle connection will be left open. 928 10. IANA Considerations 930 IANA is requested to assign the following new DHCP message types from 931 the registry "DHCP Message Type 53 Values" maintained at 932 http://www.iana.org/assignments/bootp-dhcp-parameters: 934 1. A dhcp-message-type of TBD1 for DHCPACTIVELEASEQUERY. 936 2. A dhcp-message-type of TBD2 for DHCPLEASEQUERYSTATUS. 938 IANA is requested to assign the following new DHCP status codes from 939 the registry "DHCP Status Code Type 151 Values" maintained at 940 http://www.iana.org/assignments/bootp-dhcp-parameters: 942 +------------------+-------------+ 943 | Name | status-code | 944 +------------------+-------------+ 945 | DataMissing | TBD3 | 946 | ConnectionActive | TBD4 | 947 | CatchUpComplete | TBD5 | 948 +------------------+-------------+ 950 11. Acknowledgements 952 The ideas in this document came in part from work in DHCPv6 and 953 DHCPv4 Bulk Leasequery as well as from in depth discussions between 954 the authors. 956 12. References 958 12.1. Normative References 960 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 961 Requirement Levels", BCP 14, RFC 2119, March 1997. 963 [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", RFC 964 2131, March 1997. 966 [RFC4301] Kent, S. and K. Seo, "Security Architecture for the 967 Internet Protocol", RFC 4301, December 2005. 969 [RFC4388] Woundy, R. and K. Kinnear, "Dynamic Host Configuration 970 Protocol (DHCP) Leasequery", RFC 4388, February 2006. 972 [RFC6926] Kinnear, K., Stapp, M., Desetti, R., Joshi, B., Russell, 973 N., Kurapati, P., and B. Volz, "DHCPv4 Bulk Leasequery", 974 RFC 6926, April 2013. 976 12.2. Informative References 978 [RFC0951] Croft, B. and J. Gilmore, "Bootstrap Protocol", RFC 951, 979 September 1985. 981 [RFC1542] Wimer, W., "Clarifications and Extensions for the 982 Bootstrap Protocol", RFC 1542, October 1993. 984 [RFC2132] Alexander, S. and R. Droms, "DHCP Options and BOOTP Vendor 985 Extensions", RFC 2132, March 1997. 987 Authors' Addresses 989 Kim Kinnear 990 Cisco Systems, Inc. 991 1414 Massachusetts Ave 992 Boxborough, MA 01719 993 USA 995 Email: kkinnear@cisco.com 996 Mark Stapp 997 Cisco Systems, Inc. 998 1414 Massachusetts Ave 999 Boxborough, MA 01719 1000 USA 1002 Email: mjs@cisco.com 1004 Bernie Volz 1005 Cisco Systems, Inc. 1006 1414 Massachusetts Ave 1007 Boxborough, MA 01719 1008 USA 1010 Email: volz@cisco.com 1012 Neil Russell 1013 Staples 1014 500 Staples Drive 1015 Framingham, MA 01702 1016 USA 1018 Email: neil.e.russell@gmail.com