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