idnits 2.17.1 draft-ietf-dhc-dhcpv4-bulk-leasequery-04.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 469 has weird spacing: '...ge-size the...' == Line 1526 has weird spacing: '... Name sta...' -- The document date (April 28, 2011) is 4739 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) ** Obsolete normative reference: RFC 5226 (Obsoleted by RFC 8126) == Outdated reference: A later version (-13) exists of draft-ietf-dhc-relay-id-suboption-07 == Outdated reference: A later version (-15) exists of draft-ietf-dhc-vpn-option-13 -- Obsolete informational reference (is this intentional?): RFC 4614 (Obsoleted by RFC 7414) Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DHC Working Group Kim Kinnear 3 Internet Draft Bernie Volz 4 Intended Status: Standards Track Mark Stapp 5 Expires: October 28, 2011 Cisco Systems, Inc. 6 D. Rao 7 B. Joshi 8 Infosys Technologies Ltd. 9 Neil Russell 10 Nokia 11 P. Kurapati 12 Juniper Networks Ltd. 13 April 28, 2011 15 Bulk DHCPv4 Lease Query 16 18 Status of this Memo 20 This Internet-Draft is submitted to IETF in full conformance with the 21 provisions of BCP 78 and BCP 79. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF), its areas, and its working groups. Note that 25 other groups may also distribute working documents as Internet- 26 Drafts. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 The list of current Internet-Drafts can be accessed at 34 http://www.ietf.org/ietf/1id-abstracts.txt. 36 The list of Internet-Draft Shadow Directories can be accessed at 37 http://www.ietf.org/shadow.html. 39 Copyright Notice 41 Copyright (c) 2011 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Abstract 56 The Dynamic Host Configuration Protocol for IPv4 (DHCPv4) Leasequery 57 extension allows a requestor to request information about DHCPv4 58 bindings. This mechanism is limited to queries for individual 59 bindings. In some situations individual binding queries may not be 60 efficient, or even possible. This document extends the DHCPv4 61 Leasequery protocol to allow for bulk transfer of DHCPv4 address 62 binding data via TCP. 64 Table of Contents 66 1. Introduction................................................. 3 67 2. Terminology.................................................. 4 68 3. Design Goals................................................. 7 69 3.1. Information Acquisition before Data Starts................. 7 70 3.2. Lessen need for Caching and Negative Caching............... 7 71 3.3. Antispoofing in 'Fast Path'................................ 7 72 3.4. Minimize data transmission................................. 7 73 4. Protocol Overview............................................ 8 74 5. Interaction Between UDP Leasequery and Bulk Leasequery....... 9 75 6. Message and Option Definitions............................... 10 76 6.1. Message Framing for TCP.................................... 10 77 6.2. New or Changed Options..................................... 11 78 6.3. Connection and Transmission Parameters..................... 19 79 7. Requestor Behavior........................................... 19 80 7.1. Connecting and General Processing.......................... 19 81 7.2. Forming a Bulk Leasequery.................................. 20 82 7.3. Processing Bulk Replies.................................... 22 83 7.4. Processing Time Values in Leasequery messages.............. 24 84 7.5. Querying Multiple Servers.................................. 25 85 7.6. Making Sense Out of Multiple Responses Concerning a Single. 25 86 7.7. Multiple Queries to a Single Server over One Connection.... 26 87 7.8. Closing Connections........................................ 27 88 8. Server Behavior.............................................. 27 89 8.1. Accepting Connections...................................... 27 90 8.2. Replying to a Bulk Leasequery.............................. 28 91 8.3. Building a Single Reply for Bulk Leasequery................ 31 92 8.4. Multiple or Parallel Queries............................... 32 93 8.5. Closing Connections........................................ 33 94 9. Security Considerations...................................... 33 95 10. IANA Considerations......................................... 34 96 11. Acknowledgements............................................ 35 97 12. References.................................................. 36 98 12.1. Normative References...................................... 36 99 12.2. Informative References.................................... 36 101 1. Introduction 103 The DHCPv4 protocol [RFC2131] [RFC2132] specifies a mechanism for the 104 assignment of IPv4 address and configuration information to IPv4 105 nodes. DHCPv4 servers maintain authoritative binding information. 107 +--------+ 108 | DHCPv4 | +--------------+ 109 | Server |-...-| DSLAM | 110 | | | Relay Agent | 111 +--------+ +--------------+ 112 | | 113 +------+ +------+ 114 |Modem1| |Modem2| 115 +------+ +------+ 116 | | | 117 +-----+ +-----+ +-----+ 118 |Node1| |Node2| |Node3| 119 +-----+ +-----+ +-----+ 121 Figure 1: Example DHCPv4 configuration 123 DHCPv4 relay agents receive DHCPv4 messages and frequently append a 124 relay agent information option [RFC3046] before relaying them to the 125 configured DHCPv4 servers (see Figure 1). In this process, some relay 126 agents also glean lease information sent by the server and cache it 127 locally. This information is used for a variety of purposes. Two 128 examples are prevention of spoofing attempts from the DHCPv4 clients, 129 and installation of routes. When a relay agent reboots, this 130 information is frequently lost. 132 The DHCPv4 Leasequery capability [RFC4388] extends the basic DHCPv4 133 capability to allow an external entity, such as a relay agent, to 134 query a DHCPv4 server to recover lease state information about a 135 particular IP address or client in near real-time. 137 The existing query types in Leasequery are typically data driven; the 138 relay agent initiates the Leasequery when it receives data traffic 139 from or to the client. This approach may not scale well when there 140 are thousands of clients connected to the relay agent or when the 141 relay agent has a need to rebuild its internal data store prior to 142 processing traffic in one direction or another. 144 Some applications require the ability to query the server without 145 waiting for traffic from or to clients. This query capability in turn 146 requires an underlying transport more suitable to the bulk 147 transmission of data. 149 This document extends the DHCPv4 Leasequery protocol to add support 150 for queries that address these additional requirements. There may be 151 many thousands of DHCPv4 bindings returned as the result of a single 152 request, so TCP [RFC4614] is specified for efficiency of data 153 transfer. We define several additional query types, each of which 154 can return multiple responses, in order to meet a variety of 155 requirements. 157 2. Terminology 159 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 160 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 161 "OPTIONAL" in this document are to be interpreted as described in RFC 162 2119 [RFC2119]. 164 This document uses the following terms: 166 o "absolute time" 168 A 32-bit quantity containing the number of seconds since Jan 1, 169 1970. 171 o "access concentrator" 173 An access concentrator is a router or switch at the broadband 174 access provider's edge of a public broadband access network. 175 This document assumes that the access concentrator includes the 176 DHCPv4 relay agent functionality. For example, a CMTS (Cable 177 Modem Termination System) in Cable environment or a DSLAM 178 (Digital Subscriber Line Access Multiplexer) in a DSL 179 environment. 181 o "active binding" 183 An IP address with an active binding refers to an IP address 184 which is currently associated with a DHCPv4 client where that 185 DHCPv4 client has the right to use the IP address. 187 o "Bulk Leasequery" 189 Requesting and receiving the existing DHCPv4 address binding 190 information in an efficient manner. 192 o "clock skew" 194 The difference between the absolute time on a DHCPv4 server and 195 the absolute time on the system where a requestor of a Bulk 196 Leasequery is executing is termed the "clock skew" for that Bulk 197 Leasequery connection. It is not absolutely constant but is 198 likely to vary only slowly. It is possible that, when both 199 systems run NTP, the clock skew is negligible, and this is not 200 only acceptable, but desired. 202 While it is easy to think that this can be calculated precisely 203 after one message is received by a requestor from a DHCPv4 204 server, a more accurate value is derived from continuously 205 examining the instantaneous value developed from each message 206 received from a DHCPv4 server and using it to make small 207 adjustments to the existing value held in the requestor. 209 o "DHCPv4 client" 211 A DHCPv4 client is an Internet node using DHCPv4 to obtain 212 configuration parameters such as a network address. 214 o "DHCPv4 relay agent" 216 A DHCPv4 relay agent is a third-party agent that transfers BOOTP 217 and DHCPv4 messages between clients and servers residing on 218 different subnets, per [RFC951] and [RFC1542]. 220 o "DHCPv4 server" 222 A DHCPv4 server is an Internet node that returns configuration 223 parameters to DHCPv4 clients. 225 o "DSLAM" 226 Digital Subscriber Line Multiplexer. 228 o "downstream" 230 Refers to a direction away from the central part of a network 231 and toward the edge. In a DHCPv4 context, typically refers to a 232 network direction which is away from the DHCPv4 server. 234 o "IP address" 236 In this document, the term "IP address" refers to an IPv4 IP 237 address. 239 o "IP address binding" 241 The information that a DHCPv4 server keeps regarding the 242 relationship between a DHCPv4 client and an IP address. This 243 includes the identity of the DHCPv4 client and the expiration 244 time, if any, of any lease that client has on a particular IP 245 address. In some contexts, this may include information on IP 246 addresses that are currently associated with DHCPv4 clients, and 247 in others it may also include IP addresses with no current 248 association to a DHCPv4 client. 250 o "MAC address" 252 In the context of a DHCPv4 message, a MAC address consists of 253 the fields: hardware type "htype", hardware length "hlen", and 254 client hardware address "chaddr". 256 o "upstream" 258 Refers to a direction toward the central part of a network and 259 away from the edge. In a DHCPv4 context, typically refers to a 260 network direction which is toward the DHCPv4 server. 262 o "stable storage" 264 Stable storage is used to hold information concerning IP address 265 bindings (among other things) so that this information is not 266 lost in the event of a failure which requires restart of the 267 network element. DHCPv4 servers are typically expected to have 268 high speed access to stable storage, while relay agents and 269 access concentrators usually do not have access to stable 270 storage, although they may have periodic access to such storage. 272 o "xid" 273 Transaction-id. The term "xid" refers to the DHCPv4 field 274 containing the transaction-id of the message. 276 3. Design Goals 278 The goal of this document is to provide a lightweight mechanism for 279 an Access Concentrator or other network element to retrieve IP 280 address binding information available in the DHCPv4 server. The 281 mechanism should also allow an Access Concentrator to retrieve 282 consolidated IP address binding information for either the entire 283 access concentrator or a single connection/circuit. 285 3.1. Information Acquisition before Data Starts 287 The existing data driven approach required by [RFC4388] means that 288 the Leasequeries can only be performed after an Access Concentrator 289 receives data. To implement antispoofing, the concentrator must drop 290 packets for each client until it gets lease information from the 291 DHCPv4 server for that client. If an Access Concentrator finishes the 292 Leasequeries before it starts receiving data, then there is no need 293 to drop legitimate packets. In this way, outage time may be reduced. 295 3.2. Lessen need for Caching and Negative Caching 297 The result of a single Leasequery should be cached, whether that 298 results in a positive or negative cache, in order to remember that 299 the Leasequery was performed. This caching is required to limit the 300 traffic imposed upon a DHCPv4 server by Leasequeries for information 301 already received. 303 These caches not only consume precious resources, they also need to 304 be managed. Hence they should be avoided as much as possible. 306 3.3. Antispoofing in 'Fast Path' 308 If Antispoofing is not done in the fast path, it will become a 309 bottleneck and may lead to denial of service of the access 310 concentrator. The Leasequeries should make it possible to do 311 antispoofing in the fast path. 313 3.4. Minimize data transmission 314 It may be that a network element is able to periodically save its 315 entire list of assigned IP addresses to some form of stable storage. 316 In this case, it will wish to recover all of the updates to this 317 information without duplicating the information it has recovered from 318 its own stable storage. 320 Bulk Leasequery allows the specification of a query-start-time as 321 well as a query-end-time. Use of query-times allows a network 322 element that periodically commits information to stable storage to 323 recover just what it lost since the last commit. 325 4. Protocol Overview 327 The DHCPv4 Bulk Leasequery mechanism is modeled on the existing 328 individual DHCPv4 Leasequery protocol in [RFC4388] as well as related 329 work on DHCPv6 Bulk Leasequery [RFC5460]. A Bulk Leasequery requestor 330 opens a TCP connection to a DHCPv4 Server, using the DHCPv4 port 67. 331 Note that this implies that the Leasequery requestor has server IP 332 address(es) available via configuration or some other means, and that 333 it has unicast IP reachability to the DHCPv4 server. No relaying of 334 Bulk Leasequery messages is specified. 336 After establishing a connection, the requestor sends a 337 DHCPBULKLEASEQUERY message over the connection. 339 The server uses the message type and additional data in the DHCPv4 340 DHCPBULKLEASEQUERY message to identify any relevant bindings. 342 In order to support some query types, servers may have to maintain 343 additional data structures or otherwise be able to locate bindings 344 that have been requested by the Leasequery requestor. 346 Relevant bindings are returned in DHCPv4 packets with either the 347 DHCPLEASEACTIVE message type for an IP address with a currently 348 active lease or, in some situations, a DHCPLEASEUNASSIGNED message 349 type for an IP address which is controlled by the DHCPv4 server but 350 which is not actively leased by a DHCPv4 client at the present time. 352 The Bulk Leasequery mechanism is designed to provide an external 353 entity with information concerning existing DHCPv4 IPv4 address 354 bindings managed by the DHCPv4 server. When complete, the DHCPv4 355 server will send a DHCPLEASEQUERYDONE message. If a connection is 356 lost while processing a Bulk Leasequery, the Bulk Leasequery must be 357 retried as there is no provision for determining the extent of data 358 already received by the requestor for a Bulk Leasequery. 360 Bulk Leasequery supports queries by MAC address and by Client 361 Identifier in a way similar to [RFC4388]. The Bulk Leasequery 362 protocol also adds several new queries. 364 o Query by Relay Identifier 366 This query asks a server for the bindings associated with a 367 specific relay agent; the relay agent is identified by a DUID 368 carried in a Relay-ID sub-option [RelayId]. Relay agents can 369 include this sub-option while relaying messages to DHCPv4 370 servers. Servers can retain the Relay-ID and associate it with 371 bindings made on behalf of the relay agent's clients. The 372 bindings returned are only those for DHCPv4 clients with a 373 currently active binding. 375 o Query by Remote ID 377 This query asks a server for the bindings associated with a 378 Relay Agent Remote-ID sub-option [RFC3046] value. The bindings 379 returned are only those for DHCPv4 clients with a currently 380 active binding. 382 o Query for All Configured IP Addresses 384 This query asks a server for information concerning all IP 385 addresses configured in that DHCPv4 server, by specifying no 386 other type of query. In this case, the bindings returned are for 387 all configured IP addresses, whether or not they contain a 388 currently active binding to a DHCPv4 client, since one point of 389 this type of query is to update an existing database with 390 changes after a particular point in time. 392 Any of the above queries can be qualified by the specification of a 393 query-start-time or a query-end-time (or both). When these timers are 394 used as qualifiers, they indicate that a binding should be included 395 if it changed on or after the query-start-time and on or before the 396 query-end-time. 398 In addition, any of the above queries can be qualified by the 399 specification of a vpn-id option [VpnId] to select the VPN on which 400 the query should be processed. The vpn-id option is also extended to 401 allow queries across all available VPNs. By default, only the default 402 VPN is used to satisfy the query. 404 5. Interaction Between UDP Leasequery and Bulk Leasequery 406 Bulk Leasequery can be seen as an extension of the existing UDP 407 Leasequery protocol [RFC4388]. This section clarifies the 408 relationship between the two protocols. 410 Only the DHCPBULKLEASEQUERY request is supported over the Bulk 411 Leasequery connection. No other DHCPv4 requests are supported. The 412 Bulk Leasequery connection is not an alternative DHCPv4 communication 413 option for clients seeking other DHCPv4 services. 415 Two of the query-types introduced in the UDP Leasequery protocol can 416 be used in the Bulk Leasequery protocol -- query by MAC address and 417 query by client-id. 419 The contents of the reply messages are similar between the existing 420 UDP Leasequery protocol and the Bulk Leasequery protocol, though more 421 information is returned in the Bulk Leasequery messages. 423 One change in behavior for these existing queries is required when 424 Bulk Leasequery is used. [RFC4388], in sections 6.1, 6.4.1, and 425 6.4.2 specifies the use of an associated-ip option in DHCPLEASEACTIVE 426 messages in cases where multiple bindings were found. When Bulk 427 Leasequery is used, this mechanism is not necessary; a server 428 returning multiple bindings simply does so directly as specified in 429 this document. The associated-ip option MUST NOT appear in Bulk 430 Leasequery replies. 432 Implementors should note that the TCP message framing defined in 433 Section 4.1 is not compatible with the UDP message format. If a TCP- 434 framed request is sent as a UDP message, it may not be valid, because 435 protocol fields will be offset by the message-size prefix. 437 6. Message and Option Definitions 439 6.1. Message Framing for TCP 441 The use of TCP for the Bulk Leasequery protocol permits multiple 442 messages to be sent from one end of the connection to the other 443 without requiring a request/response paradigm as does UDP DHCPv4 444 [RFC2131]. The receiver needs to be able to determine the size of 445 each message it receives. Two octets containing the message size in 446 network byte-order are prepended to each DHCPv4 message sent on a 447 Bulk Leasequery TCP connection. The two message-size octets 'frame' 448 each DHCPv4 message. 450 The maximum message size is 65535 octets. 452 DHCPv4 message framed for TCP: 454 0 1 2 3 455 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 456 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 457 | message-size | op (1) | htype (1) | 458 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 459 | hlen (1) | hops (1) | .... | 460 +---------------+---------------+ + 461 | | 462 . remainder of DHCPv4 message, 463 . from Figure 1 of [RFC2131] . 464 . . 465 . (variable) . 466 | | 467 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 469 message-size the number of octets in the message that 470 follows, as a 16-bit integer in network 471 byte-order. 473 All other fields are as specified in DHCPv4 [RFC2131]. 475 Figure 2: Format of a DHCPv4 message in TCP 477 The intent in using this format is that code which currently knows 478 how to deal with sending or receiving a message in [RFC2131] format 479 will easily be able to deal with the message contained in the TCP 480 framing. 482 6.2. New or Changed Options 484 The existing messages DHCPLEASEUNASSIGNED and DHCPLEASEACTIVE are 485 used as the value of the dhcp-message-type option to indicate an IP 486 address which is currently not leased or currently leased to a DHCPv4 487 client, respectively [RFC4388]. 489 Additional options have also been defined to enable the Bulk 490 Leasequery protocol to communicate useful information to the 491 requestor. 493 6.2.1. dhcp-message-type 495 The dhcp-message-type option (option 53) from Section 9.6 of 496 [RFC2132] requires new values. The values of these message types are 497 shown below in an extension of the table from Section 9.6 of 498 [RFC2132]: 500 Value Message Type 501 ----- ------------ 502 TBD8 DHCPBULKLEASEQUERY 503 TBD9 DHCPLEASEQUERYDONE 505 6.2.2. status-code 507 The status code option allows a machine readable value to be returned 508 regarding the status of a DHCPBULKLEASEQUERY request. 510 This option has two possible scopes when used with Bulk Leasequery, 511 depending on the context in which it appears. It refers to the 512 information in a single Leasequery reply if the value of the dhcp- 513 message-type is DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED. It refers to 514 the message stream related to an entire request if the value of the 515 dhcp-message-type is DHCPLEASEQUERYDONE. 517 The code for this option is TBD1. The length of this option is a 518 minimum of 1 octet. 520 Status Status 521 Code Len Code Message 522 +------+------+------+------+------+-- --+-----+ 523 | TBD1 | n+1 |status| s1 | s2 | ... | sn | 524 +------+------+------+------+------+-- --+-----+ 526 The status-code is an octet defined in the table below. The Status 527 Message is an optional NVT ASCII encoded text string suitable for 528 display to an end user, which MUST NOT be null-terminated. 530 Name Status Code Description 531 ---- ----------- ----------- 532 Success 000 Success. Also signaled by absence of 533 a status-code option. 535 UnspecFail 001 Failure, reason unspecified. 537 QueryTerminated 002 Indicates that the server is unable to 538 perform a query or has prematurely terminated 539 the query for some reason (which should be 540 communicated in the text message). 542 MalformedQuery 003 The query was not understood. 544 NotAllowed 004 The query or request was understood but was 545 not allowed in this context. 547 A status-code option MAY appear in the options field of a DHCPv4 548 message. If the status-code option does not appear, it is assumed 549 that the operation was successful. The status-code option SHOULD NOT 550 appear in a message which is successful unless there is some text 551 string that needs to be communicated to the requestor. 553 6.2.3. base-time 555 The base-time option is the current time the message was created to 556 be sent by the DHCPv4 server to the requestor of the Bulk Leasequery. 557 This MUST be an absolute time. All of the other time based options in 558 the reply message are relative to this time, including the dhcp- 559 lease-time [RFC2132] and client-last-transaction-time [RFC4388]. 560 This time is in the context of the DHCPv4 server who placed this 561 option in a message. 563 This is an integer in network byte order. 565 The code for this option is TBD2. The length of this option is 4 566 octets. 568 DHCPv4 Server 569 Code Len base-time 570 +-----+-----+-----+-----+-----+-----+ 571 | TBD2| 4 | t1 | t2 | t3 | t4 | 572 +-----+-----+-----+-----+-----+-----+ 574 6.2.4. start-time-of-state 576 The start-time-of-state option allows the receiver to determine the 577 time at which the IP address made the transition into its current 578 state. 580 This MUST NOT be an absolute time, which is equivalent to saying that 581 this MUST NOT be an absolute number of seconds since Jan 1, 1970. 582 Instead, this MUST be the integer number of seconds from the time the 583 IP address transitioned its current state to the time specified in 584 the base-time option in the same message. 586 This is an integer in network byte order. 588 The code for this option is TBD3. The length of this option is 4 589 octets. 591 Seconds in the past 592 Code Len from base-time 593 +-----+-----+-----+-----+-----+-----+ 594 | TBD3| 4 | t1 | t2 | t3 | t4 | 595 +-----+-----+-----+-----+-----+-----+ 597 6.2.5. query-start-time 599 The query-start-time option specifies a start query time to the 600 DHCPv4 server. If specified, only bindings that have changed on or 601 after the query-start-time should be included in the response to the 602 query. 604 The requestor MUST determine the query-start-time using lease 605 information it has received from the DHCPv4 server. This MUST be an 606 absolute time in the DHCPv4 server's context (see Section 7.4). 608 Typically (though this is not a requirement) the query-start-time 609 option will contain the value most recently received in a base-time 610 option by the requestor, as this will indicate the last successful 611 communication with the DHCP server. 613 This MUST be an absolute time. 615 This is an integer in network byte order. 617 The code for this option is TBD4. The length of this option is 4 618 octets. 620 DHCPv4 Server 621 Code Len query-start-time 622 +-----+-----+-----+-----+-----+-----+ 623 | TBD4| 4 | t1 | t2 | t3 | t4 | 624 +-----+-----+-----+-----+-----+-----+ 626 6.2.6. query-end-time 628 The query-end-time option specifies an end query time to the DHCPv4 629 server. If specified, only bindings that have changed on or before 630 the query-end-time should be included in the response to the query. 632 The requestor MUST determine the query-end-time based on lease 633 information it has received from the DHCPv4 server. This MUST be an 634 absolute time in the context of the DHCPv4 server. 636 In the absence of information to the contrary, the requestor SHOULD 637 assume that the time context of the DHCPv4 server is identical to the 638 time context of the requestor (see Section 7.4). 640 This is an integer in network byte order. 642 The code for this option is TBD5. The length of this option is 4 643 octets. 645 DHCPv4 Server 646 Code Len query-end-time 647 +-----+-----+-----+-----+-----+-----+ 648 | TBD5| 4 | t1 | t2 | t3 | t4 | 649 +-----+-----+-----+-----+-----+-----+ 651 6.2.7. dhcp-state 653 The dhcp-state option allows greater detail to be returned than 654 allowed by the DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED message types. 656 The code for this option is TBD6. The length of this option is 1 657 octet. 659 0 1 2 660 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 661 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 662 | TBD6 | Length | State | 663 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 665 TBD6 The option code. 667 Length The option length, 1 octet. 669 State The State of the IP address. 671 Value State 672 ----- ----- 673 1 AVAILABLE Address is available to local DHCPv4 server 674 2 ACTIVE Address is assigned to a DHCPv4 client 675 3 EXPIRED Lease has expired 676 4 RELEASED Lease has been released by DHCPv4 client 677 5 ABANDONED Server or client flagged address as unusable 678 6 RESET Lease was freed by some external agent 679 7 REMOTE Address is available to a remote DHCPv4 server 680 8 TRANSITIONING Address is moving between states 682 Note that some of these states may be transient and may not appear in 683 normal use. A DHCPv4 server MUST implement at least the AVAILABLE 684 and ACTIVE states, and SHOULD implement at least the ABANDONED and 685 RESET states. 687 Note the states AVAILABLE and REMOTE are relative to the current 688 server. An address that is available to the current server should 689 show AVAILABLE on that server, and if another server is involved with 690 that address as well, on that other server it should show as REMOTE. 692 The dhcp-state option SHOULD contain ACTIVE when it appears in a 693 DHCPLEASEACTIVE message. A DHCPv4 server MAY choose to not send a 694 dhcp-state option in a DHCPLEASEACTIVE message, and a requestor 695 SHOULD assume that the dhcp-state is ACTIVE if no dhcp-state option 696 appears in a DHCPLEASEACTIVE message. 698 The reference to local and remote relate to possible use in an 699 environment that includes multiple servers cooperating to provide an 700 increased availability solution. In this case, an IP address with 701 the state of AVAILABLE is available to the local server, while one 702 with the state of REMOTE is available to a remote server. Usually, 703 an IP address which is AVAILABLE on one server would be REMOTE on any 704 remote server. The TRANSITIONING state is also likely to be useful 705 in multiple server deployments, where sometimes one server must 706 interlock a state change with one or more other servers. Should a 707 Bulk Leasequery need to send information concerning the state of the 708 IP address during this period, it SHOULD use the TRANSITIONING state, 709 since the IP address is likely to be neither ACTIVE or AVAILABLE. 711 There is no requirement for the state of an IP address to transition 712 in a well defined way from state to state. To put this another way, 713 you cannot draw a simple state transition graph for the states of an 714 IP address and the requestor of a Leasequery MUST NOT depend on one 715 certain state always following a particular previous state. In 716 general, every state can (at times) follow every other state. 718 6.2.8. data-source 720 The data-source option contains information about the source of the 721 data in a DHCPLEASEACTIVE or a DHCPLEASEUNASSIGNED message. It is 722 used when there are two or more servers who might have information 723 about a particular IP address binding. Frequently two servers work 724 together to provide an increased availability solution for the DHCPv4 725 service, and in these cases, both servers will respond to Bulk 726 Leasequery requests for the same IP address. 728 The data contained in this option will allow an external process to 729 better discriminate between the information provided by each of the 730 servers servicing this IPv4 address. 732 The code for this option is TBD7. The length of this option is 1 733 octet. 735 0 1 2 736 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 737 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 738 | TBD7 | Length | Flags | 739 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 741 TBD7 The option code. 743 Length The option length, 1 octet. 745 Flags The Source information for this message. 747 0 1 2 3 4 5 6 7 748 +-+-+-+-+-+-+-+-+ 749 | MBZ |R| 750 +-+-+-+-+-+-+-+-+ 752 R: REMOTE flag 754 remote = 1 755 local = 0 757 MBZ: MUST BE ZERO (reserved for future use) 759 The REMOTE flag is used to indicate where the most recent change of 760 state (or other interesting change) concerning this IPv4 address took 761 place. If the value is local, then the change took place on the 762 server from which this message was transmitted. If the value is 763 remote, then the change took place on some other server, and was made 764 known to the server from which this message was transmitted. 766 If this option was requested and it doesn't appear, the requestor 767 SHOULD consider that the data-source was local. 769 6.2.9. Virtual Subnet Selection Type and Information 771 All of the (sub)options defined in [VpnId] carry identical payloads, 772 consisting of a type and additional VSS (Virtual Subnet Selection) 773 information. The existing table is extended (see below) with a new 774 type 254 to allow specification of a type code which indicates that 775 all VPN's are to be used to process the Bulk Leasequery. 777 Type VSS Information format: 778 ---- ----------------------- 779 0 NVT ASCII VPN identifier 780 1 RFC 2685 VPN-ID 781 CHANGED -> 2-253 Not Allowed 782 NEW -> 254 All VPN's (wildcard) 783 255 Global, default VPN 785 6.3. Connection and Transmission Parameters 787 DHCPv4 servers that support Bulk Leasequery SHOULD listen for 788 incoming TCP connections on the DHCPv4 server port 67. 789 Implementations MAY offer to make the incoming port configurable, but 790 port 67 MUST be the default. Requestors SHOULD make TCP connections 791 to port 67, and MAY offer to make the destination server port 792 configurable. 794 This section presents a table of values used to control Bulk 795 Leasequery behavior, including recommended defaults. Implementations 796 MAY make these values configurable. However, configuring too-small 797 timeout values may lead to harmful behavior both to this application 798 as well as to other traffic in the network. As a result, timeout 799 values smaller than the default values are NOT RECOMMENDED. 801 Parameter Default Description 802 ------------------------------------------- 803 BULK_LQ_DATA_TIMEOUT 300 secs Bulk Leasequery data timeout 804 for both client and server 805 (see Sections 7 and 8) 806 BULK_LQ_MAX_CONNS 10 Max Bulk Leasequery TCP connections 807 at the server side (see Section 8.1) 809 7. Requestor Behavior 811 7.1. Connecting and General Processing 813 A Requestor attempts to establish a TCP connection to a DHCPv4 Server 814 in order to initiate a Leasequery exchange. If the attempt fails, 815 the Requestor MAY retry. 817 If Bulk Leasequery is terminated prematurely by a DHCPLEASEQUERYDONE 818 with a status-code option with a status-code of QueryTerminated or by 819 the failure of the connection over which it was being submitted, the 820 requestor MAY retry the request after the creation of a new 821 connection. 823 Messages from the DHCPv4 server come as multiple responses to a 824 single DHCPBULKLEASEQUERY message. Thus, each DHCPBULKLEASEQUERY 825 request MUST have an xid (transaction-id) unique on the connection on 826 which it is sent. All of the messages which come as a response to 827 that message will contain the same xid as the request. It is the xid 828 which allows the data-streams of two different DHCPBULKLEASEQUERY 829 requests to be demultiplexed by the requestor. 831 7.2. Forming a Bulk Leasequery 833 Bulk Leasequery is designed to create a connection which will 834 transfer the state of some subset (or possibly all) of the IP address 835 bindings from the DHCPv4 server to the requestor. The DHCPv4 server 836 will send all of the requested IPv4 address bindings across this 837 connection with minimal delay after it receives the request. In this 838 context, "all IP address binding information" means information about 839 all IPv4 addresses configured within the DHCPv4 server which meet the 840 specified query criteria. For some query criteria, this may include 841 IP address binding information for IP addresses which may not now 842 have or ever had have an association with a specific DHCPv4 client. 844 To form the Bulk query, a DHCPv4 request is constructed with a dhcp- 845 message-type of DHCPBULKLEASEQUERY. The query SHOULD have a dhcp- 846 parameter-request-list to inform the DHCPv4 server which DHCPv4 847 options are of interest to the requestor sending the 848 DHCPBULKLEASEQUERY message. The dhcp-parameter-request-list in a 849 DHCPBULKLEASEQUERY message SHOULD contain the codes for base-time, 850 dhcp-lease-time, start-time-of-state, and client-last-transaction- 851 time. 853 A DHCPBULKLEASEQUERY request is constructed of one primary query and 854 optionally one or more qualifiers for it. 856 The possible primary queries are listed below. Each 857 DHCPBULKLEASEQUERY request MUST contain only one of these primary 858 queries. 860 o Query by MAC address 862 In a Query by MAC address, the chaddr, htype, and hlen of the 863 DHCPv4 packet are filled in with the values requested. 865 o Query by Client-Id 866 In a Query by Client-Id, a dhcp-client-id option containing the 867 requested value is included in the DHCPBULKLEASEQUERY request. 869 o Query by Remote-Id 871 In a Query by Remote-Id, a remote-id sub-option containing the 872 requested value is included in the relay-agent-information 873 option of the DHCPBULKLEASEQUERY request. 875 o Query by Relay-Id 877 In a Query by Relay-Id, a relay-id sub-option [RelayId] 878 containing the requested value is included in the relay-agent- 879 information option of the DHCPBULKLEASEQUERY request. 881 o Query for All Configured IP Addresses 883 A Query for All Configured IP addresses is signaled by the 884 absence of any other primary query. 886 There are three qualifiers which can be applied to any of the above 887 primary queries. These qualifiers can appear individually or 888 together in any combination, but only one of each can appear. 890 o Query Start Time 892 Inclusion of a query-start-time option specifies that only IP 893 address bindings which have changed on or after the time specified 894 in the query-start-time option should be returned. 896 o Query End Time 898 Inclusion of a query-end-time option specifies that only IP address 899 bindings which have changed on or before the time specified in the 900 query-end-time option should be returned. 902 o VPN Id 904 If no vpn-id option appears in the DHCPBULKLEASEQUERY, the default 905 VPN is used to search to satisfy the query specified by the 906 DHCPBULKLEASEQUERY. Using the vpn-id option [VpnId] allows the 907 requestor to specify a single VPN other than the default VPN. In 908 addition, the vpn-id option has been extended as part of this 909 document to allow specification that all configured VPN's be 910 searched in order to satisfy the query specified in the 911 DHCPBULKLEASEQUERY. 913 In all cases, any message returned from a DHCPBULKLEASEQUERY 914 request containing information about an IP address for other than 915 the default VPN MUST contain a vpn-id option in the message. 917 Use of the query-start-time or the query-end-time options or both can 918 serve to reduce the amount of data transferred over the TCP 919 connection by a considerable amount. 921 The TCP connection may become blocked or stop being writable while 922 the requestor is sending its query. Should this happen, the 923 implementation's behavior is controlled by the current value of 924 BULK_LQ_DATA_TIMEOUT. The default value is given elsewhere in this 925 document, and this value may be overridden by local configuration of 926 the operator. 928 If this situation is detected, the requestor SHOULD start a timer 929 using the current value of BULK_LQ_DATA_TIMEOUT. If that timer 930 expires, the requestor SHOULD terminate the connection. 932 7.3. Processing Bulk Replies 934 The requestor attempts to read a DHCPv4 Leasequery reply message from 935 the TCP connection. 937 The TCP connection may stop delivering reply data (i.e., the 938 connection stops being readable). Should this happen, the 939 implementation's behavior is controlled by the current value of 940 BULK_LQ_DATA_TIMEOUT. The default value is given elsewhere in this 941 document, and this value may be overridden by local configuration of 942 the operator. 944 If this situation is detected, the requestor SHOULD start a timer 945 using the current value of BULK_LQ_DATA_TIMEOUT. If that timer 946 expires, the requestor SHOULD terminate the connection. 948 A single Bulk Leasequery can and usually will result in a large 949 number of replies. The requestor MUST be prepared to receive more 950 than one reply with an xid matching a single DHCPBULKLEASEQUERY 951 message from a single DHCPv4 server. If the xid in the received 952 message does not match an outstanding DHCPBULKLEASEQUERY message, the 953 requestor MUST close the TCP connection. 955 The DHCPv4 server MUST send a server-identifier option (option 54) in 956 the first response to any DHCPBULKLEASEQUERY message. The DHCPv4 957 server SHOULD NOT send server identifier options in subsequent 958 responses to that DHCPBULKLEASEQUERY message. The requestor MUST 959 cache the server-identifier option from the first response and apply 960 it to any subsequent responses. 962 The response messages generated by a DHCPBULKLEASEQUERY request are: 964 o DHCPLEASEACTIVE 966 A Bulk Leasequery will generate DHCPLEASEACTIVE messages 967 containing binding data for bound IP addresses which match the 968 specified query criteria. The IP address which is bound to a 969 DHCPv4 client will appear in the ciaddr field of the 970 DHCPLEASEACTIVE message. The message may contain a non-zero 971 chaddr, htype, and hlen and possibly additional options. 973 o DHCPLEASEUNASSIGNED 975 Some queries will also generate DHCPLEASEUNASSIGNED messages for 976 IP addresses which match the query criteria. These messages 977 indicate that the IP address is managed by the DHCPv4 server but 978 is not currently bound to any DHCPv4 client. The IP address to 979 which this message refers will appear in the ciaddr field of the 980 DHCPLEASEUNASSIGNED message. A DHCPLEASEUNASSGINED message MAY 981 also contain information about the last DHCPv4 client that was 982 bound to this IP address. The message may contain a non-zero 983 chaddr, htype, and hlen and possibly additional options in this 984 case. 986 o DHCPLEASEQUERYDONE 988 A response of DHCPLEASEQUERYDONE indicates that the server has 989 completed its response to the query, and that no more messages 990 will be sent in response to the DHCPBULKLEASEQUERY. More details 991 will sometimes be available in the received status-code option 992 in the DHCPLEASEQUERYDONE message. If there is no status-code 993 option in the DHCPLEASEQUERYDONE message, then the query 994 completed successfully. 996 Note that a query which returned no data, that is a 997 DHCPBULKLEASEQUERY request followed by a DHCPLEASEQUERYDONE 998 response, is considered a successful query in that no errors 999 occurred during the processing. It is not considered an error 1000 to have no information to return to a DHCPBULKLEASEQUERY 1001 request. 1003 The DHCPLEASEUNKNOWN message MUST NOT appear in a response to a Bulk 1004 Leasequery. 1006 The requestor MUST NOT assume that there is any inherent order in the 1007 IP address binding information that is sent in response to a 1008 DHCPBULKLEASEQUERY. While the base-time will tend to increase 1009 monotonically (as it is the current time on the DHCPv4 server), the 1010 actual time that any IP address binding information changed is 1011 unrelated to the base-time. 1013 The DHCPLEASEQUERYDONE message always ends a successful 1014 DHCPBULKLEASEQUERY request and any unsuccessful DHCPBULKLEASEQUERY 1015 requests not terminated by a dropped connection. After receiving 1016 DHCPLEASEQUERYDONE from a server, the requestor MAY close the TCP 1017 connection to that server if no other DHCPBULKLEASEQUERY is 1018 outstanding on that TCP connection. 1020 The DHCPv4 Leasequery protocol [RFC4388] uses the associated-ip 1021 option as an indicator that multiple bindings were present in 1022 response to a single DHCPv4 client based query. For Bulk Leasequery, 1023 a separate message is returned for each binding, and so the 1024 associated-ip option is not used. 1026 7.4. Processing Time Values in Leasequery messages 1028 Bulk Leasequery requests may be made to a DHCPv4 server whose 1029 absolute time may not be synchronized with the local time of the 1030 requestor. Thus, there are at least two time contexts in even the 1031 simplest Bulk Leasequery response, and in the situation where 1032 multiple DHCPv4 servers are queried, the situation becomes even more 1033 complex. 1035 If the requestor of a Bulk Leasequery is saving the data returned in 1036 some form, it has a requirement to store a variety of time values, 1037 and some of these will be time in the context of the requestor and 1038 some will be time in the context of the DHCPv4 server. 1040 When receiving a DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message from 1041 the DHCPv4 server, the message will contain a base-time option. The 1042 time contained in this base-time option is in the context of the 1043 DHCPv4 server. As such, it is an ideal time to save and use as input 1044 to a DHCPBULKLEASEQUERY in the query-start-time or query-end-time 1045 options, should the requestor need to ever issue a DHCPBULKLEASEQUERY 1046 message using those options as part of a later query, since those 1047 options require a time in the context of the DHCPv4 server. 1049 In addition to saving the base-time for possible future use in a 1050 query-start-time or query-end-time option, the base-time is used as 1051 part of the conversion of the other times in the Leasequery message 1052 to values which are meaningful in the context of the requestor. 1054 In systems whose clocks are synchronized, perhaps using NTP, the 1055 clock skew will usually be zero, which is not only acceptable, but 1056 desired. 1058 7.5. Querying Multiple Servers 1060 A Bulk Leasequery requestor MAY be configured to attempt to connect 1061 to and query from multiple DHCPv4 servers in parallel. The DHCPv4 1062 Leasequery specification [RFC4388] includes a discussion about 1063 reconciling binding data received from multiple DHCPv4 servers. 1065 In addition, the algorithm in Section 7.6 should be used. 1067 7.6. Making Sense Out of Multiple Responses Concerning a Single IPv4 1068 Address 1070 Any requestor of an Bulk Leasequery MUST be prepared for multiple 1071 responses to arrive for a particular IPv4 address from multiple 1072 different DHCPv4 servers. The following algorithm SHOULD be used to 1073 decide if the information just received is more up to date (i.e., 1074 better) than the best existing information. In the discussion below, 1075 the information that is received from a DHCPv4 server about a 1076 particular IPv4 address is termed a "record". The times used in the 1077 algorithm below SHOULD have been converted into the requestor's 1078 context and the time comparisons SHOULD be performed in a manner 1079 consistent with the information in Section 7.4. 1081 o If both the existing and the new record contain client-last- 1082 transaction-time information, the record with the later client- 1083 last-transaction-time is considered better. 1085 o If one of the records contains client-last-transaction-time 1086 information and the other one doesn't, then compare the client- 1087 last-transaction-time in the record that contains it against the 1088 other record's start-time-of-state. The record with the later 1089 time is considered better. 1091 o If neither record contains client-last-transaction-time 1092 information, compare their start-time-of-state information. The 1093 record with the later start-time-of-state is considered better. 1095 o If none of the comparisons above yield a clear answer as to 1096 which record is later, then compare the value of the REMOTE flag 1097 from the data-source option for each record. 1099 If the values of the REMOTE flag are different between the two 1100 records, the record with the REMOTE flag value of local is 1101 considered better. 1103 The above algorithm does not necessarily determine which record is 1104 better. In the event that the algorithm is inconclusive with regard 1105 to a record which was just received by the requestor, the requestor 1106 SHOULD use additional information in the two records to make a 1107 determination as to which record is better. 1109 7.7. Multiple Queries to a Single Server over One Connection 1111 Bulk Leasequery requestors may need to make multiple queries in order 1112 to recover binding information. A requestor MAY use a single 1113 connection to issue multiple queries to a server willing to support 1114 them. Each query MUST have a unique xid. 1116 A server SHOULD allow configuration of the number of queries that can 1117 be processed simultaneously over a single connection. A server 1118 SHOULD read the number of queries it is configured to process 1119 simultaneously and only read any subsequent queries as current 1120 queries are processed. 1122 A server that is processing multiple queries simultaneously MUST 1123 interleave replies to the multiple queries within the stream of reply 1124 messages it sends. Requestors need to be aware that replies for 1125 multiple queries may be interleaved within the stream of reply 1126 messages. Requestors that are not able to process interleaved 1127 replies (based on xid) MUST NOT send more than one query over a 1128 single connection prior to the completion of the previous query. 1130 Requestors should be aware that servers are not required to process 1131 more than one query over a connection at a time (the limiting case 1132 for the configuration described above), and that servers are likely 1133 to limit the rate at which they process queries from any one 1134 requestor. 1136 7.7.1. Example 1138 This example illustrates what a series of queries and responses might 1139 look like. This is only an example - there is no requirement that 1140 this sequence must be followed, or that requestors or servers must 1141 support parallel queries. 1143 In the example session, the client sends four queries after 1144 establishing a connection. Query 1 returns no results; query 2 1145 returns 3 messages and the stream of replies concludes before the 1146 client issues any new query. Query 3 and query 4 overlap, and the 1147 server interleaves its replies to those two queries. 1149 Requestor Server 1150 --------- ------ 1151 DHCPBULKLEASEQUERY xid 1 -----> 1152 <----- DHCPLEASEQUERYDONE xid 1 1153 DHCPBULKLEASEQUERY xid 2 -----> 1154 <----- DHCPLEASEACTIVE xid 2 1155 <----- DHCPLEASEACTIVE xid 2 1156 <----- DHCPLEASEACTIVE xid 2 1157 <----- DHCPLEASEQUERYDONE xid 2 1158 DHCPBULKLEASEQUERY xid 3 -----> 1159 DHCPBULKLEASEQUERY xid 4 -----> 1160 <----- DHCPLEASEACTIVE xid 4 1161 <----- DHCPLEASEACTIVE xid 4 1162 <----- DHCPLEASEACTIVE xid 3 1163 <----- DHCPLEASEACTIVE xid 4 1164 <----- DHCPLEASEUNASSIGNED xid 3 1165 <----- DHCPLEASEACTIVE xid 4 1166 <----- DHCPLEASEACTIVE xid 3 1167 <----- DHCPLEASEQUERYDONE xid 3 1168 <----- DHCPLEASEACTIVE xid 4 1169 <----- DHCPLEASEQUERYDONE xid 4 1171 7.8. Closing Connections 1173 The requestor SHOULD close the connection after the 1174 DHCPLEASEQUERYDONE message is received for the last outstanding query 1175 that it has sent, if it has no more queries to send. 1177 8. Server Behavior 1179 8.1. Accepting Connections 1181 Servers that implement DHCPv4 Bulk Leasequery listen for incoming TCP 1182 connections. Port numbers are discussed in Section 6.3. Servers 1183 MUST be able to limit the number of concurrently accepted and active 1184 connections. The value BULK_LQ_MAX_CONNS SHOULD be the default; 1185 implementations MAY permit the value to be configurable. Connections 1186 SHOULD be accepted and, if the number of connections is over 1187 BULK_LQ_MAX_CONNS, they SHOULD be closed immediately. 1189 Servers MAY restrict Bulk Leasequery connections and 1190 DHCPBULKLEASEQUERY messages to certain requestors. Connections not 1191 from permitted requestors SHOULD be closed immediately, to avoid 1192 server connection resource exhaustion. Servers MAY restrict some 1193 requestors to certain query types. Servers MAY reply to queries that 1194 are not permitted with the DHCPLEASEQUERYDONE message with a status- 1195 code option status of NotAllowed, or MAY simply close the connection. 1197 If the TCP connection becomes blocked while the server is accepting a 1198 connection or reading a query, it SHOULD be prepared to terminate the 1199 connection after an BULK_LQ_DATA_TIMEOUT. We make this 1200 recommendation to allow servers to control the period of time they 1201 are willing to wait before abandoning an inactive connection, 1202 independent of the TCP implementations they may be using. 1204 8.2. Replying to a Bulk Leasequery 1206 If the connection becomes blocked while the server is attempting to 1207 send reply messages, the server SHOULD be prepared to terminate the 1208 TCP connection after BULK_LQ_DATA_TIMEOUT. 1210 Every Bulk Leasequery request MUST be terminated by sending a final 1211 DHCPLEASEQUERYDONE message if such a message can be sent. The 1212 DHCPLEASEQUERYDONE message MUST have a status-code option status if 1213 the termination was other than successful, and SHOULD NOT contain a 1214 status-code option status if the termination was successful. 1216 If the DHCPv4 server encounters an error during processing of the 1217 DHCPBULKLEASEQUERY message, either during initial processing or later 1218 during the message processing, it SHOULD send a DHCPLEASEQUERYDONE 1219 containing a status-code option. It MAY close the connection after 1220 this error is signaled, but that is not required. 1222 If the server does not find any bindings satisfying a query, it MUST 1223 send a DHCPLEASEQUERYDONE. It SHOULD NOT include a status-code 1224 option with a Success status unless there is a useful string to 1225 include in the status-code option. Otherwise, the server sends each 1226 binding's data in a DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message. 1228 The response to a DHCPBULKLEASEQUERY may involve examination of 1229 multiple DHCPv4 IP address bindings maintained by the DHCPv4 server. 1230 The Bulk Leasequery protocol does not require any ordering of the IP 1231 addresses returned in DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED 1232 messages. 1234 When responding to a DHCPBULKLEASEQUERY message, the DHCPv4 server 1235 MUST NOT send more than one message for each applicable IP address, 1236 even if the state of some of those IP addresses changes during the 1237 processing of the message. Updates to such IP address state are 1238 already handled by normal protocol processing, so no special effort 1239 is needed here. 1241 If the ciaddr, yiaddr, or siaddr is non-zero in a DHCPBULKLEASEQUERY 1242 request, the request must be terminated immediately by a 1243 DHCPLEASEQUERYDONE message with a status-code status of 1244 MalformedQuery. 1246 Any DHCPBULKLEASEQUERY which has more than one of the following 1247 primary query types specified MUST be terminated immediately by a 1248 DHCPLEASEQUERYDONE message with a status-code option status code of 1249 NotAllowed. 1251 The allowable queries in a DHCPBULKLEASEQUERY message are processed 1252 as follows. Note that the descriptions of the primary queries below 1253 must be constrained by the actions of any of the three qualifiers 1254 described subsequently as well. 1256 The following table discusses how to process the various queries. 1257 For information on how to identify the query, see the information in 1258 Section 7.2. 1260 o Query by MAC address 1262 Every IP address that has a current binding to a DHCPv4 client 1263 matching the chaddr, htype, and hlen in the DHCPBULKLEASEQUERY 1264 request MUST be returned in a DHCPLEASEACTIVE message. 1266 o Query by Client-Id 1268 Every IP address that has a current binding to a DHCPv4 client 1269 matching the client-id option in the DHCPBULKLEASEQUERY request 1270 MUST be returned in a DHCPLEASEACTIVE message. 1272 o Query by Remote-Id 1274 Every IP address that has a current binding to a DHCPv4 client 1275 matching the remote-id sub-option of the relay-agent-information 1276 option in the DHCPBULKLEASEQUERY request MUST be returned in a 1277 DHCPLEASEACTIVE message. 1279 o Query by Relay-Id 1281 Every IP address that has a current binding to a DHCPv4 client 1282 matching the relay-id sub-option of the relay-agent-information 1283 option in the DHCPBULKLEASEQUERY request MUST be returned in a 1284 DHCPLEASEACTIVE message. 1286 o Query for All Configured IP Addresses 1288 A Query for All Configured IP addresses is signaled by the 1289 absence of any other primary query. That is, if there is no 1290 value in the chaddr, hlen, htype, no client-id option, no 1291 remote-id sub-option or relay-id sub-option of the relay-agent- 1292 information option, then the request is a query for information 1293 concerning all configured IP addresses. In this case, every 1294 configured IP address that has a current binding to a DHCPv4 1295 client MUST be returned in a DHCPLEASEACTIVE message. In 1296 addition, every configured IP address that does not have a 1297 current binding to a DHCPv4 client MUST be returned in a 1298 DHCPLEASEUNASSIGNED message. 1300 In this form of query, each configured IP address MUST be 1301 returned at most one time. If the absence of qualifiers 1302 restricting the number of IP addresses returned, every 1303 configured IP address MUST be returned exactly once. 1305 There are three qualifiers that can be applied to any of the above 1306 primary queries. These qualifiers can appear individually or 1307 together in any combination, but only one of each can appear. 1309 o Query Start Time 1311 If a query-start-time option appears in the DHCPBULKLEASEQUERY 1312 request, only IP address bindings that have changed on or after the 1313 time specified in the query-start-time option should be returned. 1315 o Query End Time 1317 If a query-end-time option appears in the DHCPBULKLEASEQUERY 1318 request, only IP address bindings that have changed on or before 1319 the time specified in the query-end-time option should be returned. 1321 o VPN Id 1323 If no vpn-id option appears in the DHCPBULKLEASEQUERY, the default 1324 VPN is used to satisfy the query. A vpn-id option [VpnId] value 1325 other than the wildcard value (254) allows the requestor to specify 1326 a single VPN other than the default VPN. In addition, the vpn-id 1327 option has been extended as part of this document to allow 1328 specification of a type 254 which indicates that all configured 1329 VPN's be searched in order to satisfy the primary query. 1331 In all cases, if the information returned in a DHCPLEASEACTIVE or 1332 DHCPLEASEUNASSIGNED message is for a VPN other than the default, a 1333 vpn-id option MUST appear in the packet. 1335 The query-start-time and query-end-time qualifiers are used to 1336 constrain the amount of data returned by a Bulk Leasequery request by 1337 returning only IP addresses whose address bindings have changed in 1338 some way during the time window specified by the query-start-time and 1339 query-end-time. 1341 A DHCPv4 server SHOULD consider an address binding to have changed 1342 during a specified time window if either the client-last- 1343 transaction-time or the start-time-of-state of the address binding 1344 changed during that time window. 1346 The DHCPv4 server MAY return address binding data in any order, as 1347 long as binding information for any given IP address is not repeated. 1348 When all binding data for a given DHCPBULKLEASEQUERY has been sent, 1349 the DHCPv4 server MUST send a DHCPBULKLEASEQUERYDONE message. 1351 8.3. Building a Single Reply for Bulk Leasequery 1353 The DHCPv4 Leasequery [RFC4388] specification describes the initial 1354 construction of DHCPLEASEQUERY reply messages using the 1355 DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED message types in Section 1356 6.4.2. All of the reply messages in Bulk Leasequery are similar to 1357 the reply messages for an IP address query. Message transmission and 1358 framing for TCP is described in this document in Section 6.1. 1360 [RFC2131] and [RFC4388] specify that every response message MUST 1361 contain the server-identifier option. However, that option will be 1362 the same for every response from a particular DHCPBULKLEASEQUERY 1363 request. Thus, the DHCPv4 server MUST include the server-identifier 1364 option in the first message sent in response to a DHCPBULKLEASEQUERY. 1365 It SHOULD NOT include the server-identifier in later messages. 1367 The message type of DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED is based 1368 on the value of the dhcp-state option. If the dhcp-state option 1369 value is ACTIVE, then the message type is DHCPLEASEACTIVE, otherwise 1370 the message type is DHCPLEASEUNASSIGNED. 1372 In addition to the basic message construction described in [RFC4388], 1373 the following guidelines exist: 1375 1. If the dhcp-state option code appears in the dhcp-parameter- 1376 request-list, the DHCPv4 server SHOULD include a dhcp-state 1377 option whose value corresponds most closely to the state held 1378 by the DHCPv4 server for the IP address associated with this 1379 reply. If the state is ACTIVE and the message being returned 1380 is DHCPLEASEACTIVE, then the DHCPv4 server MAY choose to not 1381 send the dhcp-state option. The requestor SHOULD assume that 1382 any DHCPLEASEACTIVE message arriving without a requested dhcp- 1383 state option has a dhcp-state of ACTIVE. 1385 2. If the base-time option code appears in the dhcp-parameter- 1386 request-list, the DHCPv4 server MUST include a base-time 1387 option, which is the current time in the DHCPv4 server's 1388 context and the time from which the start-time-of-state, dhcp- 1389 lease-time, client-last-transaction-time, and other duration- 1390 style times are based upon. 1392 3. If the start-time-of-state option code appears in the dhcp- 1393 parameter-request-list, the DHCPv4 server MUST include a 1394 start-time-of-state option whose value represents the time at 1395 which the dhcp-state option's state became valid. 1397 4. If the dhcp-lease-time option code appears in the dhcp- 1398 parameter-request-list, the DHCPv4 server MUST include a dhcp- 1399 lease-time option for any state that has a time-out value 1400 associated with it. 1402 5. If the data-source option code appears in the dhcp-parameter- 1403 request-list, the DHCPv4 server MUST include the data-source 1404 option in any situation where any of the bits would be non- 1405 zero. Thus, in the absence of the data-source option, the 1406 assumption is that all of the flags were zero. 1408 6. If the client-last-transaction-time option code appears in the 1409 dhcp-parameter-request-list, The DHCPv4 server MUST include the 1410 client-last-transaction-time option in any situation where the 1411 information is available. 1413 7. If there is a dhcp-parameter-request-list in the initial 1414 DHCPBULKLEASEQUERY request, then it should be used for all of 1415 the replies generated by that request. Some options can be 1416 sent from a DHCPv4 client to the server or from the DHCPv4 1417 server to a DHCPv4 client. Option 125 is such an option. If 1418 the option code for one of these options appears in the dhcp- 1419 parameter-request-list, it SHOULD result in returning the value 1420 of the option sent by the DHCPv4 client to the server if one 1421 exists. 1423 Note that there may be other requirements for a reply to a 1424 DHCPBULKLEASEQUERY request discussed in Section 8.2. 1426 8.4. Multiple or Parallel Queries 1428 As discussed in Section 7.3, requestors may want to use a connection 1429 that has already been established when they need to make additional 1430 queries. Servers SHOULD support reading and processing multiple 1431 queries from a single connection and SHOULD allow configuration of 1432 the number of simultaneous queries it may process. A server MUST NOT 1433 read more query messages from a connection than it is prepared to 1434 process simultaneously. 1436 This SHOULD be a feature that is administratively controlled. 1437 Servers SHOULD offer configuration that limits the number of 1438 simultaneous queries permitted from any one requestor, in order to 1439 control resource use if there are multiple requestors seeking 1440 service. 1442 8.5. Closing Connections 1444 The DHCPv4 server SHOULD start a timer for BULK_LQ_DATA_TIMEOUT 1445 seconds for a particular connection after it sends a 1446 DHCPLEASEQUERYDONE message over that connection and if there is no 1447 current query outstanding for that connection. It should clear this 1448 timer if a query arrives over that connection. If the timer expires, 1449 the DHCPv4 server should close the connection. 1451 The server MUST close its end of the TCP connection if it encounters 1452 an error sending data on the connection. The server MUST close its 1453 end of the TCP connection if it finds that it has to abort an in- 1454 process request. A server aborting an in-process request SHOULD 1455 attempt to signal that to its requestors by using the QueryTerminated 1456 status code in the status-code option in a DHCPLEASEQUERYDONE 1457 message, including a message string indicating details of the reason 1458 for the abort. If the server detects that the requesting end of the 1459 connection has been closed, the server MUST close its end of the 1460 connection. 1462 9. Security Considerations 1464 The "Security Considerations" section of [RFC2131] details the 1465 general threats to DHCPv4. The DHCPv4 Leasequery specification 1466 [RFC4388] describes recommendations for the Leasequery protocol, 1467 especially with regard to authentication of LEASEQUERY messages, 1468 mitigation of packet-flooding DOS attacks, and restriction to trusted 1469 requestors. 1471 The use of TCP introduces some additional concerns. Attacks that 1472 attempt to exhaust the DHCPv4 server's available TCP connection 1473 resources, such as SYN flooding attacks, can compromise the ability 1474 of legitimate requestors to receive service. Malicious requestors 1475 who succeed in establishing connections, but who then send invalid 1476 queries, partial queries, or no queries at all also can exhaust a 1477 server's pool of available connections. We recommend that servers 1478 offer configuration to limit the sources of incoming connections, 1479 that they limit the number of accepted connections and the number of 1480 in-process queries from any one connection, and that they limit the 1481 period of time during which an idle connection will be left open. 1483 [RFC4388] discusses security concerns and potential solutions for 1484 DHCPLEASEQUERY message exchanges in its Section 7, and all of the 1485 solutions discussed there are applicable to the DHCPLEASEQUERY 1486 message exchanges described in this document. 1488 10. IANA Considerations 1490 This document defines two new name spaces associated with DHCPv4 1491 options: 1493 1. Status code values for the status-code option, TBD1. 1495 2. DHCP state values for the dhcp-state option, TBD6. 1497 IANA has established a registry of values for these two name spaces. 1498 These name spaces will be managed by IANA. New values for these name 1499 spaces may only be defined by IETF Consensus, as described in 1500 [RFC5226]. Basically, this means that they are defined by RFCs 1501 approved by the IESG. 1503 IANA is requested to assign the following new values for this 1504 document. See Section 6.2 for details. 1506 1. A dhcp-message-type of TBD8 for DHCPBULKLEASEQUERY. 1508 2. A dhcp-message-type of TBD9 for DHCPLEASEQUERYDONE. 1510 3. An option code of TBD1 for status-code. 1512 4. An option code of TBD2 for base-time. 1514 5. An option code of TBD3 for start-time-of-state. 1516 6. An option code of TBD4 for query-start-time. 1518 7. An option code of TBD5 for query-end-time. 1520 8. An option code of TBD6 for dhcp-state. 1522 9. An option code of TBD7 for data-source. 1524 10.Values for status code in a status-code option (option TBD1): 1526 Name status-code 1527 ---- ----------- 1528 Success 000 1529 UnspecFail 001 1530 QueryTerminated 002 1531 MalformedQuery 003 1532 NotAllowed 004 1534 11.Values for dhcp-state (option TBD6): 1536 State 1537 ----- 1538 1 AVAILABLE 1539 2 ACTIVE 1540 3 EXPIRED 1541 4 RELEASED 1542 5 ABANDONED 1543 6 RESET 1544 7 REMOTE 1545 8 TRANSITIONING 1547 12.Additional type field values for the Virtual Subnet Selection Type 1548 and Information [VpnId]: 1550 Type VSS Information format: 1552 0 NVT ASCII VPN identifier 1553 1 RFC2685 VPN-ID 1554 2-253 Not Allowed 1555 254 All VPN's. (wildcard; only allowed in 1556 DHCPBULKLEASEQUERY messages) 1557 255 Global, default VPN. 1559 11. Acknowledgements 1561 This draft is a collaboration between the authors of draft-dtv-dhc- 1562 dhcpv4-bulk-leasequery-00.txt and draft-kkinnear-dhc-dhcpv4-bulk- 1563 leasequery-00.txt. Both documents acknowledged that significant text 1564 as well as important ideas were borrowed in whole or in part from the 1565 DHCPv6 Bulk Leasequery RFC, [RFC5460] written by Mark Stapp. Further 1566 suggestions and improvements were made by participants in the DHC 1567 working group, including Alfred Hoenes. 1569 12. References 1571 12.1. Normative References 1573 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1574 Requirement Levels", RFC 2119, March 1997. 1576 [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", RFC 2131, 1577 March 1997. 1579 [RFC2132] Alexander, S., Droms, R., "DHCP Options and BOOTP Vendor 1580 Extensions", RFC 2132, March 1997. 1582 [RFC3046] Patrick, M., "DHCP Relay Agent Information Option", RFC 1583 3046, January 2001. 1585 [RFC4388] Woundy, R., K. Kinnear, "Dynamic Host Configuration 1586 Protocol (DHCP) Leasequery", RFC 4388, February 2006. 1588 [RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an 1589 IANA Considerations Section in RFCs", BCP 26, RFC 5226, May 2008. 1591 [RelayId] Stapp, M., "The DHCPv4 Relay Agent Identifier Suboption", 1592 draft-ietf-dhc-relay-id-suboption-07.txt, (work in progress) July 1593 2009. 1595 [VpnId] Kinnear, K., R. Johnson, M. Stapp and J. Kumarasamy, "Virtual 1596 Subnet Selection Options for DHCPv4 and DHCPv6" draft-ietf-dhc- 1597 vpn-option-13.txt, (work in progress) April 2011. 1599 12.2. Informative References 1601 [RFC951] Croft, B., Gilmore, J., "Bootstrap Protocol (BOOTP)", RFC 1602 951, September 1985. 1604 [RFC1542] Wimer, W., "Clarifications and Extensions for the Bootstrap 1605 Protocol", RFC 1542, October 1993. 1607 [RFC4614] Duke, M., R. Braden, W. Eddy, and E. Blanton, "A Roadmap 1608 for Transmission Control Protocol (TCP) Specification Documents", 1609 RFC 4614, September 2006. 1611 [RFC5460] Stapp, M., "DHCPv6 Bulk Leasequery", RFC 5460, February 1612 2009. 1614 Authors' Addresses 1616 Kim Kinnear 1617 Cisco Systems 1618 1414 Massachusetts Ave. 1619 Boxborough, Massachusetts 01719 1621 Phone: (978) 936-0000 1623 EMail: kkinnear@cisco.com 1625 Bernie Volz 1626 Cisco Systems 1627 1414 Massachusetts Ave. 1628 Boxborough, Massachusetts 01719 1630 Phone: (978) 936-0000 1632 EMail: volz@cisco.com 1634 Neil Russell 1635 Nokia 1636 5 Wayside Drive 1637 Burlington, MA 01803 1639 EMail: neil.russell@nokia.com 1641 Mark Stapp 1642 Cisco Systems 1643 1414 Massachusetts Ave. 1644 Boxborough, Massachusetts 01719 1646 Phone: (978) 936-0000 1648 EMail: mjs@cisco.com 1650 Ramakrishna Rao DTV 1651 Infosys Technologies Ltd. 1652 44 Electronics City, Hosur Road 1653 Bangalore 560 100 1654 India 1656 EMail: ramakrishnadtv@infosys.com 1657 URI: http://www.infosys.com/ 1659 Bharat Joshi 1660 Infosys Technologies Ltd. 1661 44 Electronics City, Hosur Road 1662 Bangalore 560 100 1663 India 1665 EMail: bharat_joshi@infosys.com 1666 URI: http://www.infosys.com/ 1668 Pavan Kurapati 1669 Juniper Networks Ltd. 1670 Embassy Prime Buildings, C.V.Raman Nagar 1671 Bangalore 560 093 1672 India 1674 Email: kurapati@juniper.net 1675 URI: http://www.juniper.net/