idnits 2.17.1 draft-ietf-dhc-dhcpv4-bulk-leasequery-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Sep 2009 rather than the newer Notice from 28 Dec 2009. (See https://trustee.ietf.org/license-info/) 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 471 has weird spacing: '...ge-size the...' == Line 555 has weird spacing: '...-number base...' == Line 556 has weird spacing: '...-number fro...' == Line 563 has weird spacing: '... Name sta...' == Line 1561 has weird spacing: '... Name sta...' == The document seems to use 'NOT RECOMMENDED' as an RFC 2119 keyword, but does not include the phrase in its RFC 2119 key words list. -- The document date (October 26, 2009) is 5295 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) == 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-11 -- Obsolete informational reference (is this intentional?): RFC 4614 (Obsoleted by RFC 7414) Summary: 1 error (**), 0 flaws (~~), 9 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 Neil Russell 5 Expires: April 26, 2010 Mark Stapp 6 Cisco Systems, Inc. 7 D. Rao 8 B. Joshi 9 P. Kurapati 10 Infosys Technologies Ltd. 11 October 26, 2009 13 Bulk DHCPv4 Lease Query 14 16 Status of this Memo 18 This Internet-Draft is submitted to IETF in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF), its areas, and its working groups. Note that 23 other groups may also distribute working documents as Internet- 24 Drafts. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 The list of current Internet-Drafts can be accessed at 32 http://www.ietf.org/ietf/1id-abstracts.txt. 34 The list of Internet-Draft Shadow Directories can be accessed at 35 http://www.ietf.org/shadow.html. 37 This Internet-Draft will expire on April 26, 2010 39 Copyright Notice 41 Copyright (c) 2009 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 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 65 1. Introduction................................................. 3 66 2. Terminology.................................................. 4 67 3. Design Goals................................................. 6 68 3.1. Information Acquisition before Data Starts................. 7 69 3.2. Lessen need for Caching and Negative Caching............... 7 70 3.3. Antispoofing in 'Fast Path'................................ 7 71 3.4. Minimize data transmission................................. 7 72 4. Protocol Overview............................................ 8 73 5. Interaction Between UDP Leasequery and Bulk Leasequery....... 9 74 6. Message and Option Definitions............................... 10 75 6.1. Message Framing for TCP.................................... 10 76 6.2. New or Changed Options..................................... 11 77 6.3. Connection and Transmission Parameters..................... 19 78 7. Requestor Behavior........................................... 19 79 7.1. Connecting and General Processing.......................... 19 80 7.2. Forming a Bulk Leasequery.................................. 20 81 7.3. Processing Bulk Replies.................................... 22 82 7.4. Processing Time Values in Leasequery messages.............. 24 83 7.5. Querying Multiple Servers.................................. 24 84 7.6. Making Sense Out of Multiple Responses Concerning a Single. 25 85 7.7. Multiple Queries to a Single Server over One Connection.... 25 86 7.8. Closing Connections........................................ 27 87 8. Server Behavior.............................................. 27 88 8.1. Accepting Connections...................................... 27 89 8.2. Replying to a Bulk Leasequery.............................. 28 90 8.3. Building a Single Reply for Bulk Leasequery................ 31 91 8.4. Multiple or Parallel Queries............................... 33 92 8.5. Closing Connections........................................ 33 93 9. Security Considerations...................................... 33 94 10. IANA Considerations......................................... 34 95 11. Acknowledgements............................................ 35 97 12. References.................................................. 35 98 12.1. Normative References...................................... 35 99 12.2. Informative References.................................... 36 100 Authors' Addresses............................................... 37 102 1. Introduction 104 The DHCPv4 protocol [RFC2131] [RFC2132] specifies a mechanism for the 105 assignment of IPv4 address and configuration information to IPv4 106 nodes. DHCPv4 servers maintain authoritative binding information. 108 +--------+ 109 | DHCPv4 | +--------------+ 110 | Server |-...-| DSLAM | 111 | | | Relay Agent | 112 +--------+ +--------------+ 113 | | 114 +------+ +------+ 115 |Modem1| |Modem2| 116 +------+ +------+ 117 | | | 118 +-----+ +-----+ +-----+ 119 |Host1| |Host2| |Host3| 120 +-----+ +-----+ +-----+ 122 Figure 1: Example DHCPv4 configuration 124 DHCPv4 relay agents receive DHCPv4 messages and frequently append a 125 relay agent information option [RFC3046] before relaying them to the 126 configured DHCPv4 servers (see Figure 1). In this process, some relay 127 agents also glean lease information sent by the server and cache it 128 locally. This information is used for a variety of purposes. Two 129 examples are prevention of spoofing attempts from the DHCPv4 clients, 130 and installation of routes. When a relay agent reboots, this 131 information is frequently lost. 133 The DHCPv4 Leasequery capability [RFC4388] extends the basic DHCPv4 134 capability to allow an external entity, such as a relay agent, to 135 query a DHCPv4 server to recover lease state information about a 136 particular IP address or client in near real-time. 138 The existing query types in Leasequery are typically data driven; the 139 relay agent initiates the Leasequery when it receives data traffic 140 from or to the client. This approach may not scale well when there 141 are thousands of clients connected to the relay agent or when the 142 relay agent has a need to rebuild its internal data store prior to 143 processing traffic in one direction or another. 145 Some applications require the ability to query the server without 146 waiting for traffic from or to clients. This query capability in turn 147 requires an underlying transport more suitable to the bulk 148 transmission of data. 150 This document extends the DHCPv4 Leasequery protocol to add support 151 for queries that address these additional requirements. There may be 152 many thousands of DHCPv4 bindings returned as the result of a single 153 request, so TCP [RFC4614] is specified for efficiency of data 154 transfer. We define several additional query types, each of which 155 could return multiple responses, in order to meet a variety of 156 requirements. 158 2. Terminology 160 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 161 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 162 document are to be interpreted as described in RFC 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 Multiplexer) in a DSL environment. 180 o "active binding" 182 An IP address with an active binding refers to an IP address 183 which is currently associated with a DHCPv4 client where that 184 DHCPv4 client has the right to use the IP address. 186 o "Bulk Leasequery" 188 Requesting and receiving the existing DHCPv4 address binding 189 information in an efficient manner. 191 o "clock skew" 193 The difference between the absolute time on a DHCPv4 server and 194 the absolute time on the system where a requestor of a Bulk 195 Leasequery is executing is termed the "clock skew" for that Bulk 196 Leasequery connection. It is not absolutely constant but is 197 likely to vary only slowly. It is possible that, when both 198 systems run NTP, the clock skew is negligible, and this is not 199 only acceptable, but desired. 201 While it is easy to think that this can be calculated precisely 202 after one message is received by a requestor from a DHCPv4 203 server, a more accurate value is derived from continuously 204 examining the instantaneous value developed from each message 205 received from a DHCPv4 server and using it to make small 206 adjustments to the existing value held in the requestor. 208 o "DHCPv4 client" 210 A DHCPv4 client is an Internet host using DHCPv4 to obtain 211 configuration parameters such as a network address. 213 o "DHCPv4 relay agent" 215 A DHCPv4 relay agent is a third-party agent that transfers BOOTP 216 and DHCPv4 messages between clients and servers residing on 217 different subnets, per [RFC951] and [RFC1542]. 219 o "DHCPv4 server" 221 A DHCPv4 server is an Internet host that returns configuration 222 parameters to DHCPv4 clients. 224 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 IPv4 IP address. 243 This includes the identity of the DHCPv4 client and the 244 expiration time, if any, of any lease that client has on a 245 particular IPv4 address. In some contexts, this may include 246 information on IP addresses that are currently associated with 247 DHCPv4 clients, and in others it may also include IP addresses 248 with no current 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" 274 Transaction-id. The term "xid" refers to the DHCPv4 field 275 containing the transaction-id of the message. 277 3. Design Goals 279 The goal of this document is to provide a lightweight mechanism for 280 an Access Concentrator or other network element to retrieve IP 281 address binding information available in the DHCPv4 server. The 282 mechanism should also allow an Access Concentrator to retrieve 283 consolidated IP address binding information for either the entire 284 access concentrator or a single connection/circuit. 286 3.1. Information Acquisition before Data Starts 288 The existing data driven approach required by [RFC4388] means that 289 the Leasequeries can only be performed after an Access Concentrator 290 receives data. To implement antispoofing, the concentrator must drop 291 packets for each client until it gets lease information from DHCPv4 292 server for that client. If an Access Concentrator finishes the 293 Leasequeries before it starts receiving data, then there is no need 294 to drop legitimate packets. In this way, outage time may be reduced. 296 3.2. Lessen need for Caching and Negative Caching 298 The result of a single Leasequery should be cached, whether that 299 results in a positive or negative cache, in order to remember that 300 the Leasequery was performed. This caching is required to limit the 301 traffic imposed upon a DHCPv4 server by Leasequeries for information 302 already received. 304 These caches not only consume precious resources, they also need to 305 be managed. Hence they should be avoided as much as possible. 307 3.3. Antispoofing in 'Fast Path' 309 If Antispoofing is not done in the fast path, it will become a 310 bottleneck and may lead to denial of service of the access 311 concentrator. The Leasequeries should make it possible to do 312 antispoofing in the fast path. 314 3.4. Minimize data transmission 316 It may be that a network element is able to periodically save its 317 entire list of assigned IP addresses to some form of stable storage. 318 In this case, it will wish to recover all of the updates to this 319 information without duplicating the information it has recovered from 320 its own stable storage. 322 Bulk Leasequery allows the specification of a query-start-time as 323 well as a query-end-time. Use of query-times allows a network 324 element that periodically commits information to stable storage to 325 recover just what it lost since the last commit. 327 4. Protocol Overview 329 The Bulk Leasequery mechanism is modeled on the existing individual 330 Leasequery protocol in [RFC4388] as well as related work on DHCPv6 331 Bulk Leasequery [RFC5460]. A Bulk Leasequery requestor opens a TCP 332 connection to a DHCPv4 Server, using the DHCPv4 port 67. Note that 333 this implies that the Leasequery requestor has server IP address(es) 334 available via configuration or some other means, and that it has 335 unicast IP reachability to the DHCPv4 server. No relaying of Bulk 336 Leasequery messages is specified. 338 After establishing a connection, the requestor sends a 339 DHCPBULKLEASEQUERY message over the connection. 341 The server uses the message type and additional data in the DHCPv4 342 DHCPBULKLEASEQUERY message to identify any relevant bindings. 344 In order to support some query types, servers may have to maintain 345 additional data structures or otherwise be able to locate bindings 346 that have been requested by the Leasequery requestor. 348 Relevant bindings are returned in DHCPv4 packets with either the 349 DHCPLEASEACTIVE message type for an IP address with a currently 350 active lease or, in some situations, a DHCPLEASEUNASSIGNED message 351 type for an IP address which is controlled by the DHCPv4 server but 352 which is not actively leased by a DHCPv4 client at the present time. 354 The Bulk Leasequery mechanism is designed to provide an external 355 entity with information concerning existing DHCPv4 IPv4 address 356 bindings managed by the DHCPv4 server. When complete, the DHCPv4 357 server will send a DHCPLEASEQUERYDONE message. If a connection is 358 lost while processing a Bulk Leasequery, the Bulk Leasequery must be 359 retried as there is no provision for determining the extent of data 360 already received by the requestor for a Bulk Leasequery. 362 Bulk Leasequery supports queries by MAC address and by Client 363 Identifier in a way similar to [RFC4388]. The Bulk Leasequery 364 protocol also adds several new queries. 366 o Query by Relay Identifier 368 This query asks a server for the bindings associated with a 369 specific relay agent; the relay agent is identified by a DUID 370 carried in a Relay-ID sub-option [RelayId]. Relay agents can 371 include this sub-option while relaying messages to DHCPv4 372 servers. Servers can retain the Relay-ID and associate it with 373 bindings made on behalf of the relay agent's clients. The 374 bindings returned are only those for DHCPv4 clients with a 375 currently active binding. 377 o Query by Remote ID 379 This query asks a server for the bindings associated with a 380 Relay Agent Remote-ID sub-option [RFC3046] value. The bindings 381 returned are only those for DHCPv4 clients with a currently 382 active binding. 384 o Query for All Configured IP Addresses 386 This query asks a server for information concerning all IP 387 addresses configured in that DHCPv4 server, by specifying no 388 other type of query. In this case, the bindings returned are for 389 all configured IP addresses, whether or not they contain a 390 currently active binding to a DHCPv4 client, since one point of 391 this type of query is to update an existing database with 392 changes after a particular point in time. 394 Any of the above queries can be qualified by the specification of a 395 query-start-time or a query-end-time (or both). When these timers are 396 used as qualifiers, they indicate that a binding should be included 397 if it changed on or after the query-start-time and on or before the 398 query-end-time. 400 In addition, any of the above queries can be qualified by the 401 specification of a vpn-id option [VpnId] to select the VPN on which 402 the query should be processed. The vpn-id option is also extended to 403 allow queries across all available VPNs. By default, only the default 404 VPN is used to satisfy the query. 406 5. Interaction Between UDP Leasequery and Bulk Leasequery 408 Bulk Leasequery can be seen as an extension of the existing UDP 409 Leasequery protocol [RFC4388]. This section clarifies the 410 relationship between the two protocols. 412 Only the DHCPBULKLEASEQUERY request is supported over the Bulk 413 Leasequery connection. No other DHCPv4 requests are supported. The 414 Bulk Leasequery connection is not an alternative DHCPv4 communication 415 option for clients seeking other DHCPv4 services. 417 Two of the query-types introduced in the UDP Leasequery protocol can 418 be used in the Bulk Leasequery protocol -- query by MAC address and 419 query by client-id. 421 The contents of the reply messages are similar between the existing 422 UDP Leasequery protocol and the Bulk Leasequery protocol, though more 423 information is returned in the Bulk Leasequery messages. 425 One change in behavior for these existing queries is required when 426 Bulk Leasequery is used. [RFC4388], in sections 6.1, 6.4.1, and 427 6.4.2 specifies the use of an associated-ip option in DHCPLEASEACTIVE 428 messages in cases where multiple bindings were found. When Bulk 429 Leasequery is used, this mechanism is not necessary; a server 430 returning multiple bindings simply does so directly as specified in 431 this document. The associated-ip option MUST NOT appear in Bulk 432 Leasequery replies. 434 Implementors should note that the TCP message framing defined in 435 Section 4.1 is not compatible with the UDP message format. If a TCP- 436 framed request is sent as a UDP message, it may not be valid, because 437 protocol fields will be offset by the message-size prefix. 439 6. Message and Option Definitions 441 6.1. Message Framing for TCP 443 The use of TCP for the Bulk Leasequery protocol permits multiple 444 messages to be sent from one end of the connection to the other 445 without requiring a request/response paradigm as does UDP DHCPv4 446 [RFC2131]. The receiver needs to be able to determine the size of 447 each message it receives. Two octets containing the message size in 448 network byte-order are prepended to each DHCPv4 message sent on a 449 Bulk Leasequery TCP connection. The two message-size octets 'frame' 450 each DHCPv4 message. 452 The maximum message size is 65535 octets. 454 DHCPv4 message framed for TCP: 456 0 1 2 3 457 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 458 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 459 | message-size | op (1) | htype (1) | 460 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 461 | hlen (1) | hops (1) | .... | 462 +---------------+---------------+ + 463 | | 464 . remainder of DHCPv4 message, 465 . from Figure 1 of [RFC2131] . 466 . . 467 . (variable) . 468 | | 469 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 471 message-size the number of octets in the message that 472 follows, as a 16-bit integer in network 473 byte-order. 475 All other fields are as specified in DHCPv4 [RFC2131]. 477 Figure 2: Format of a DHCPv4 message in TCP 479 The intent in using this format is that code which currently knows 480 how to deal with sending or receiving a message in [RFC2131] format 481 will easily be able to deal with the message contained in the TCP 482 framing. 484 6.2. New or Changed Options 486 The existing messages DHCPLEASEUNASSIGNED and DHCPLEASEACTIVE are 487 used as the value of the dhcp-message-type option to indicate an IP 488 address which is currently not leased or currently leased to a DHCPv4 489 client, respectively [RFC4388]. 491 Additional options have also been defined to enable the Bulk 492 Leasequery protocol to communicate useful information to the 493 requestor. 495 6.2.1. dhcp-message-type 497 The dhcp-message-type option (option 53) from Section 9.6 of 498 [RFC2132] requires new values. The values of these message types are 499 shown below in an extension of the table from Section 9.6 of 500 [RFC2132]: 502 Value Message Type 503 ----- ------------ 504 14 DHCPBULKLEASEQUERY 505 15 DHCPLEASEQUERYDONE 507 6.2.2. dhcp-message 509 The dhcp-message option (option 56) from Section 9.9 of [RFC2132] 510 requires additional definition for use in the context of a 511 DHCPBULKLEASEQUERY. 513 The format of the NVT ASCII message in the dhcp-message option is 514 specified to have the first three characters appear in a constrained 515 format. The first three characters MUST be numeric (base 10) 516 characters. 518 Encoded in these first three characters is the decimal number 519 corresponding to a variety of status codes defined below. 521 The motivation for this constraint of the existing dhcp-message 522 option is to reduce the number of top-level options used by this 523 document. 525 The status code returned in the dhcp-message option allows greater 526 detail to be returned regarding the status of a DHCPBULKLEASEQUERY 527 request. While specified in the Bulk Leasequery document, this 528 additional specification of the DHCPv4 dhcp-message option may well 529 be valuable in other circumstances. In those circumstances its scope 530 should be explicitly defined. 532 This option has two possible scopes when used with Bulk Leasequery, 533 depending on the context in which it appears. It refers to the 534 information in a single Leasequery reply if the value of the dhcp- 535 message-type is DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED. It refers to 536 the message stream related to an entire request if the value of the 537 dhcp-message-type is DHCPLEASEQUERYDONE. 539 The code for this option is 56. The length of this option is at least 540 3 octets. 542 0 1 2 3 543 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 544 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 545 | option-code | option-len | left-number | middle-number | 546 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 547 | right-number | status-message (if any) ... . 548 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 550 option-code 56. 552 option-len 3 + length of status-message (which may be 0). 554 left-number NVT ASCII encoded characters representing the 555 middle-number base-10 value of the status code, taken 556 right-number from the table below. 558 status-message An optional NVT ASCII encoded text string 559 suitable for display to an end user, which 560 MUST NOT be null-terminated. It SHOULD 561 start with an NVT ASCII space. 563 Name status-code Description 564 ---- ----------- ----------- 565 Success 000 Success. Also signaled by absence of 566 a dhcp-message option. 568 UnspecFail 001 Failure, reason unspecified. 570 QueryTerminated 002 Indicates that the server is unable to 571 perform a query or has prematurely terminated 572 the query for some reason (which should be 573 communicated in the text message). 575 MalformedQuery 003 The query was not understood. 577 NotAllowed 004 The query or request was understood but was 578 not allowed in this context. 580 A dhcp-message option MAY appear in the options field of a DHCPv4 581 message. If the dhcp-message option does not appear, it is assumed 582 that the operation was successful. The dhcp-message option SHOULD 583 NOT appear in a message which is successful unless there is some text 584 string that needs to be communicated to the requestor. 586 6.2.3. base-time 588 The base-time option is the current time the message was created to 589 be sent by the DHCPv4 server to the requestor of the Bulk Leasequery. 590 This MUST be an absolute time. All of the other time based options in 591 the reply message are relative to this time, including the dhcp- 592 lease-time [RFC2132] and client-last-transaction-time [RFC4388]. 593 This time is in the context of the DHCPv4 server. 595 This is an integer in network byte order. 597 The code for this option is TBD1. The length of this option is 4 598 octets. 600 DHCPv4 Server 601 Code Len Base Time 602 +-----+-----+-----+-----+-----+-----+ 603 | TBD1| 4 | t1 | t2 | t3 | t4 | 604 +-----+-----+-----+-----+-----+-----+ 606 6.2.4. start-time-of-state 608 The start-time-of-state option allows the receiver to determine the 609 time at which the IP address made the transition into its current 610 state. 612 This MUST NOT be an absolute time. This MUST NOT be an absolute 613 number of seconds since Jan 1, 1970. Instead, this MUST be an 614 integer number of seconds in the past from the time specified in the 615 base-time option in the same message that the IP address transitioned 616 into its current state. In the same way that the IP Address Lease 617 Time option (option 51) encodes a lease time which is a number of 618 seconds into the future from the time the message was sent, this 619 option encodes a value which is a number of seconds into the past 620 from the base-time option included in the same message. 622 This is an integer in network byte order. 624 The code for this option is TBD2. The length of this option is 4 625 octets. 627 Seconds in the past 628 Code Len from base-time 629 +-----+-----+-----+-----+-----+-----+ 630 | TBD2| 4 | t1 | t2 | t3 | t4 | 631 +-----+-----+-----+-----+-----+-----+ 633 6.2.5. query-start-time 635 The query-start-time option specifies a start query time to the 636 DHCPv4 server. If specified, only bindings that have changed on or 637 after the query-start-time should be included in the response to the 638 query. 640 The requester MUST compute the query-start-time relative to a lease 641 it has received from the DHCPv4 server, and MUST specify that time in 642 terms of the DHCPv4 server's clock. 644 Typically (though this is not a requirement) the query-start-time 645 option will contain the value most recently received in a base-time 646 option by the requestor, as this will indicate the last successful 647 communication with the DHCP server. 649 This MUST be an absolute time. 651 This is an integer in network byte order. 653 The code for this option is TBD3. The length of this option is 4 654 octets. 656 DHCPv4 Server 657 Code Len query-start-time 658 +-----+-----+-----+-----+-----+-----+ 659 | TBD3| 4 | t1 | t2 | t3 | t4 | 660 +-----+-----+-----+-----+-----+-----+ 662 6.2.6. query-end-time 664 The query-end-time option specifies an end query time to the DHCPv4 665 server. If specified, only bindings that have changed on or before 666 the query-end-time should be included in the response to the query. 668 The requester MUST compute the query-end-time relative to a lease it 669 has received from the DHCPv4 server, and MUST specify that time in 670 terms of the DHCPv4 server's clock. 672 This MUST be an absolute time. 674 This MUST be a time in the context of the DHCPv4 server. In the 675 absence of information to the contrary, the requestor SHOULD assume 676 that the time context of the DHCPv4 server is identical to the time 677 context of the requestor. 679 It SHOULD NOT be a time in the context of the requestor. 681 This is an integer in network byte order. 683 The code for this option is TBD4. The length of this option is 4 684 octets. 686 DHCPv4 Server 687 Code Len query-end-time 688 +-----+-----+-----+-----+-----+-----+ 689 | TBD4| 4 | t1 | t2 | t3 | t4 | 690 +-----+-----+-----+-----+-----+-----+ 692 6.2.7. dhcp-state 694 The dhcp-state option allows greater detail to be returned than 695 allowed by the DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED message types. 697 The code for this option is TBD6. The length of this option is 1 698 octet. 700 0 1 2 701 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 702 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 703 | TBD6 | Length | State | 704 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 706 TBD6 The option code. 708 Length The option length, 1 octet. 710 State The State of the IP address. 712 Value State 713 ----- ----- 714 1 AVAILABLE Address is available to local DHCPv4 server 715 2 ACTIVE Address is assigned to a DHCPv4 client 716 3 EXPIRED Lease has expired 717 4 RELEASED Lease has been released by DHCPv4 client 718 5 ABANDONED Server or client flagged address as unusable 719 6 RESET Lease was freed by some external agent 720 7 REMOTE Address is available to a remote DHCPv4 server 721 8 TRANSITIONING Address is moving between states 723 Note that some of these states may be transient and may not appear in 724 normal use. A DHCPv4 server MUST implement at least the AVAILABLE 725 and ACTIVE states, and SHOULD implement at least the ABANDONED and 726 RESET states. 728 The dhcp-state option SHOULD contain ACTIVE when it appears in a 729 DHCPLEASEACTIVE message. A DHCPv4 server MAY choose to not send a 730 dhcp-state option in a DHCPLEASEACTIVE message, and a requestor 731 SHOULD assume that the dhcp-state is ACTIVE if no dhcp-state option 732 appears in a DHCPLEASEACTIVE message. 734 The reference to local and remote relate to possible use in an 735 environment that includes multiple servers cooperating to provide an 736 increased availability solution. In this case, an IP address with 737 the state of AVAILABLE is available to the local server, while one 738 with the state of REMOTE is available to a remote server. Usually, 739 an IP address which is AVAILABLE on one server would be REMOTE on any 740 remote server. The TRANSITIONING state is also likely to be useful 741 in multiple server deployments, where sometimes one server must 742 interlock a state change with one or more other servers. Should a 743 Bulk Leasequery need to send information concerning the state of the 744 IP address during this period, it SHOULD use the TRANSITIONING state, 745 since the IP address is likely to be neither ACTIVE or AVAILABLE. 747 There is no requirement for the state of an IP address to transition 748 in a well defined way from state to state. To put this another way, 749 you cannot draw a simple state transition graph for the states of an 750 IP address and the requestor of a Leasequery MUST NOT depend on one 751 certain state always following a particular previous state. In 752 general, every state can (at times) follow every other state. 754 6.2.8. data-source 756 The data-source option contains information about the source of the 757 data in a DHCPLEASEACTIVE or a DHCPLEASEUNASSIGNED message. It is 758 used when there are two or more servers who might have information 759 about a particular IP address binding. Frequently two servers work 760 together to provide an increased availability solution for the DHCPv4 761 service, and in these cases, both servers will respond to Bulk 762 Leasequery requests for the same IP address. 764 The data contained in this option will allow an external process to 765 better discriminate between the information provided by each of the 766 servers servicing this IPv4 address. 768 The code for this option is TBD5. The length of this option is 1 769 octet. 771 0 1 2 772 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 773 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 774 | TBD5 | Length | Flags | 775 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 777 TBD5 The option code. 779 Length The option length, 1 octet. 781 Flags The Source information for this message. 783 0 1 2 3 4 5 6 7 784 +-+-+-+-+-+-+-+-+ 785 | MBZ |R| 786 +-+-+-+-+-+-+-+-+ 788 R: REMOTE flag 790 remote = 1 791 local = 0 793 MBZ: MUST BE ZERO (reserved for future use) 795 The REMOTE flag is used to indicate where the most recent change of 796 state (or other interesting change) concerning this IPv4 address took 797 place. If the value is local, then the change took place on the 798 server from which this message was transmitted. If the value is 799 remote, then the change took place on some other server, and was made 800 known to the server from which this message was transmitted. 802 If this option was requested and it doesn't appear, the the requestor 803 SHOULD consider that the data-source was local. 805 6.2.9. Virtual Subnet Selection Type and Information 807 All of the (sub)options defined in [VpnId] carry identical payloads, 808 consisting of a type and additional VSS (Virtual Subnet Selection) 809 information. The existing table is extended (see below) with a new 810 type 254 to allow specification of a type code which indicates that 811 all VPN's are to be used to process the Bulk Leasequery. 813 Type VSS Information format: 814 ---- ----------------------- 815 0 NVT ASCII VPN identifier 816 1 RFC2685 VPN-ID 817 2-253 Not Allowed 818 NEW -> 254 All VPN's (wildcard). 819 255 Global, default VPN. 821 6.3. Connection and Transmission Parameters 823 DHCPv4 servers that support Bulk Leasequery SHOULD listen for 824 incoming TCP connections on the DHCPv4 server port 67. 825 Implementations MAY offer to make the incoming port configurable, but 826 port 67 MUST be the default. Requestors SHOULD make TCP connections 827 to port 67, and MAY offer to make the destination server port 828 configurable. 830 This section presents a table of values used to control Bulk 831 Leasequery behavior, including recommended defaults. Implementations 832 MAY make these values configurable. However, configuring too-small 833 timeout values may lead to harmful behavior both to this application 834 as well as to other traffic in the network. As a result, timeout 835 values smaller than the default values are NOT RECOMMENDED. 837 Parameter Default Description 838 ------------------------------------------- 839 BULK_LQ_DATA_TIMEOUT 300 secs Bulk Leasequery data timeout 840 BULK_LQ_MAX_CONNS 10 Max Bulk Leasequery TCP connections 842 7. Requestor Behavior 844 7.1. Connecting and General Processing 846 A Requestor attempts to establish a TCP connection to a DHCPv4 Server 847 in order to initiate a Leasequery exchange. If the attempt fails, 848 the Requestor MAY retry. 850 If Bulk Leasequery is terminated prematurely by a DHCPLEASEQUERYDONE 851 with a dhcp-message status-code of QueryTerminated or by the failure 852 of the connection over which it was being submitted, the requestor 853 MAY retry the request after the creation of a new connection. 855 Messages from the DHCPv4 server come as multiple responses to a 856 single DHCPBULKLEASEQUERY message. Thus, each DHCPBULKLEASEQUERY 857 request MUST have a xid (transaction-id) unique on the connection on 858 which it is sent. All of the messages which come as a response to 859 that message will contain the same xid as the request. It is the xid 860 which allows the data-streams of two different DHCPBULKLEASEQUERY 861 requests to be demultiplexed by the requestor. 863 7.2. Forming a Bulk Leasequery 865 Bulk Leasequery is designed to create a connection which will 866 transfer the state of some subset (or possibly all) of the IP address 867 bindings from the DHCPv4 server to the requestor. The DHCPv4 server 868 will send all of the requested IPv4 address bindings across this 869 connection with minimal delay after it receives the request. In this 870 context, "all IP address binding information" means information about 871 all IPv4 addresses configured within the DHCPv4 server which meet the 872 specified query criteria. For some query criteria, this may include 873 IP address binding information for IP addresses which may not now 874 have or ever had have an association with a specific DHCPv4 client. 876 To form the Bulk query, a DHCPv4 request is constructed with a dhcp- 877 message-type of DHCPBULKLEASEQUERY. The query SHOULD have a dhcp- 878 parameter-request-list to inform the DHCPv4 server which DHCPv4 879 options are of interest to the requestor sending the 880 DHCPBULKLEASEQUERY message. The dhcp-parameter-request-list in a 881 DHCPBULKLEASEQUERY message SHOULD contain the codes for base-time, 882 dhcp-lease-time, start-time-of-state, and client-last-transaction- 883 time. 885 A DHCPBULKLEASEQUERY request is constructed of one primary query and 886 optionally one or more qualifiers for it. 888 The possible primary queries are listed below. Each 889 DHCPBULKLEASEQUERY request MUST contain only one of these primary 890 queries. 892 o Query by MAC address 894 In a Query by MAC address, the chaddr, htype, and hlen of the 895 DHCPv4 packet are filled in with the values requested. 897 o Query by Client-Id 899 In a Query by Client-Id, the dhcp-client-id option containing 900 the requested value is included in the DHCPBULKLEASEQUERY 901 request. 903 o Query by Remote-Id 905 In a Query by Remote-Id, the remote-id sub-option of the relay- 906 agent-information option containing the requested value is 907 included in the DHCPBULKLEASEQUERY request. 909 o Query by Relay-Id 911 In a Query by Relay-Id, the relay-id sub-option [RelayId] of the 912 relay-agent-information option containing the requested value is 913 included in the DHCPBULKLEASEQUERY request. 915 o Query for All Configured IP Addresses 917 A Query for All Configured IP addresses is signaled by the 918 absence of any other primary query. 920 There are three qualifiers which can be applied to any of the above 921 primary queries. These qualifiers can appear individually or 922 together in any combination, but only one of each can appear. 924 o Query Start Time 926 Inclusion of the query-start-time option specifies that only IP 927 address bindings which have changed on or after the time specified 928 in the query-start-time option should be returned. 930 o Query End Time 932 Inclusion of the query-end-time option specifies that only IP 933 address bindings which have changed on or before the time specified 934 in the query-end-time option should be returned. 936 o VPN Id 938 If no vpn-id option appears in the DHCPBULKLEASEQUERY, the default 939 VPN is used to search to satisfy the query specified by the 940 DHCPBULKLEASEQUERY. Using the vpn-id option [VpnId] allows the 941 requestor to specify a single VPN other than the default VPN. In 942 addition, the vpn-id option has been extended as part of this 943 document to allow specification that all configured VPN's be 944 searched in order to satisfy the query specified in the 945 DHCPBULKLEASEQUERY. 947 In all cases, any message returned from a DHCPBULKLEASEQUERY 948 request containing information about an IP address for other than 949 the default VPN MUST contain a vpn-id option in the message. 951 Use of the query-start-time or the query-end-time options or both can 952 serve to reduce the amount of data transferred over the TCP 953 connection by a considerable amount. 955 The TCP connection may become blocked or stop being writable while 956 the requestor is sending its query. Should this happen, the 957 implementation's behavior is controlled the current value of 958 BULK_LQ_DATA_TIMEOUT. The default value is given elsewhere in this 959 document, and this value may be overridden by local configuration of 960 the operator. 962 If this situation is detected, the requester SHOULD start a timer 963 using the current value of BULK_LQ_DATA_TIMEOUT. If that timer 964 expires, the requester SHOULD terminate the connection. 966 7.3. Processing Bulk Replies 968 The requestor attempts to read a DHCPv4 Leasequery message from the 969 TCP connection. 971 The TCP connection may stop delivering reply data (i.e., the 972 connection stops being readable). Should this happen, the 973 implementation's behavior is controlled the current value of 974 BULK_LQ_DATA_TIMEOUT. The default value is given elsewhere in this 975 document, and this value may be overridden by local configuration of 976 the operator. 978 If this situation is detected, the requester SHOULD start a timer 979 using the current value of BULK_LQ_DATA_TIMEOUT. If that timer 980 expires, the requester SHOULD terminate the connection. 982 A single Bulk Leasequery can and usually will result in a large 983 number of replies. The requestor MUST be prepared to receive more 984 than one reply with an xid matching a single DHCPBULKLEASEQUERY 985 message from a single DHCPv4 server. If the xid in the received 986 message does not match an outstanding DHCPBULKLEASEQUERY message, the 987 requestor MUST close the TCP connection. 989 The DHCPv4 server MUST send a server-identifier option (option 54) in 990 the first response to any DHCPBULKLEASEQUERY message. The DHCPv4 991 server SHOULD NOT send server identifier options in subsequent 992 responses to that DHCPBULKLEASEQUERY message. The requester MUST 993 cache the server-identifier option from the first response and apply 994 it to any subsequent responses. 996 The response messages generated by a DHCPBULKLEASEQUERY request are: 998 o DHCPLEASEACTIVE 1000 A Bulk Leasequery will generate DHCPLEASEACTIVE messages 1001 containing binding data for bound IP addresses which match the 1002 specified query criteria. The IP address which is bound to a 1003 DHCPv4 client will appear in the ciaddr field of the 1004 DHCPLEASEACTIVE message. The message may contain a non-zero 1005 chaddr, htype, and hlen and possibly additional options. 1007 o DHCPLEASEUNASSIGNED 1009 Some queries will also generate DHCPLEASEUNASSIGNED messages for 1010 IP addresses which match the query criteria. These messages 1011 indicate that the IP address is managed by the DHCPv4 server but 1012 is not currently bound to any DHCPv4 client. The IP address to 1013 which this message refers will appear in the ciaddr field of the 1014 DHCPLEASEUNASSIGNED message. A DHCPLEASEUNASSGINED message MAY 1015 also contain information about the last DHCPv4 client that was 1016 bound to this IP address. The message may contain a non-zero 1017 chaddr, htype, and hlen and possibly additional options. 1019 o DHCPLEASEQUERYDONE 1021 A response of DHCPLEASEQUERYDONE indicates that the server has 1022 completed its response to the query, and that no more messages 1023 will be sent in response to the DHCPBULKLEASEQUERY. More details 1024 will sometimes be available in the received dhcp-message option 1025 in the DHCPLEASEQUERYDONE message. If there is no dhcp-message 1026 option in the DHCPLEASEQUERYDONE message, then the query 1027 completed successfully. 1029 Note that a query which returned no data, that is a 1030 DHCPBULKLEASEQUERY request followed by a DHCPLEASEQUERYDONE 1031 response, is considered a successful query in that no errors 1032 occurred during the processing. It is not considered an error 1033 to have no information to return to a DHCPBULKLEASEQUERY 1034 request. 1036 The DHCPLEASEUNKNOWN message MUST NOT appear in a response to a Bulk 1037 Leasequery. 1039 The requestor MUST NOT assume that there is any inherent order in the 1040 IP address binding information that is sent in response to a 1041 DHCPBULKLEASEQUERY. While the base-time will tend to increase 1042 monotonically (as it is the current time on the DHCPv4 server), the 1043 actual time that any IP address binding information changed is 1044 unrelated to the base-time. 1046 The DHCPLEASEQUERYDONE message always ends a successful 1047 DHCPBULKLEASEQUERY request and any unsuccessful DHCPBULKLEASEQUERY 1048 requests not terminated by a dropped connection. After receiving 1049 DHCPLEASEQUERYDONE from a server, the requestor MAY close the TCP 1050 connection to that server if no other DHCPBULKLEASEQUERY is 1051 outstanding on that TCP connection. 1053 The DHCPv4 Leasequery protocol [RFC4388] uses the associated-ip 1054 option as an indicator that multiple bindings were present in 1055 response to a single DHCPv4 client based query. For Bulk Leasequery, 1056 a separate message is returned for each binding, and so the 1057 associated-ip option is not used. 1059 7.4. Processing Time Values in Leasequery messages 1061 Bulk Leasequery requests may be made to a DHCPv4 server whose 1062 absolute time may not be synchronized with the local time of the 1063 requestor. Thus, there are at least two time contexts in even the 1064 simplest Bulk Leasequery response, and in the situation where 1065 multiple DHCPv4 servers are queried, the situation becomes even more 1066 complex. 1068 If the requestor of a Bulk Leasequery is saving the data returned in 1069 some form, it has a requirement to store a variety of time values, 1070 and some of these will be time in the context of the requestor and 1071 some will be time in the context of the DHCPv4 server. 1073 When receiving a DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message from 1074 the DHCPv4 server, the message will contain a base-time option. The 1075 time contained in this base-time option is in the context of the 1076 DHCPv4 server. As such, it is an ideal time to save and use as input 1077 to a DHCPBULKLEASEQUERY in the query-start-time or query-end-time 1078 options, should the requestor need to ever issue a DHCPBULKLEASEQUERY 1079 message using those options as part of a later query. 1081 In addition to saving the base-time for possible future use in a 1082 query-start-time option, the base-time is used as part of the 1083 conversion of the other times in the Leasequery message to values 1084 which are meaningful in the context of the requestor. 1086 In systems whose clocks are synchronized, perhaps using NTP, the 1087 clock skew will usually be zero, which is not only acceptable, but 1088 desired. 1090 7.5. Querying Multiple Servers 1092 A Bulk Leasequery requestor MAY be configured to attempt to connect 1093 to and query from multiple DHCPv4 servers in parallel. The DHCPv4 1094 Leasequery specification [RFC4388] includes a discussion about 1095 reconciling binding data received from multiple DHCPv4 servers. 1097 In addition, the algorithm in the Section 7.6 should be used. 1099 7.6. Making Sense Out of Multiple Responses Concerning a Single IPv4 1100 Address 1102 Any requestor of an Bulk Leasequery MUST be prepared for multiple 1103 responses to arrive for a particular IPv4 address from multiple 1104 different DHCPv4 servers. The following algorithm SHOULD be used to 1105 decide if the information just received is more up to date (i.e., 1106 better) than the best existing information. In the discussion below, 1107 the information that is received from a DHCPv4 server about a 1108 particular IPv4 address is termed a "record". The times used in the 1109 algorithm below SHOULD have been converted into the requestor's 1110 context and the time comparisons SHOULD be performed in a manner 1111 consistent with the information in Section 7.4. 1113 o If both the existing and the new record contain client-last- 1114 transaction-time information, the record with the later client- 1115 last-transaction-time is considered better. 1117 o If one of the records contains client-last-transaction-time 1118 information and the other one doesn't, then compare the client- 1119 last-transaction-time in the record that contains it against the 1120 other record's start-time-of-state. The record with the later 1121 time is considered better. 1123 o If neither record contains client-last-transaction-time 1124 information, compare their start-time-of-state information. The 1125 record with the later start-time-of-state is considered better. 1127 o If none of the comparisons above yield a clear answer as to 1128 which record is later, then compare the value of the REMOTE flag 1129 from the data-source option for each record. 1131 If the values of the REMOTE flag are different between the two 1132 records, the record with the REMOTE flag value of local is 1133 considered better. 1135 The above algorithm does not necessarily determine which record is 1136 better. In the event that the algorithm is inconclusive with regard 1137 to a record which was just received by the requestor, the requestor 1138 SHOULD use additional information in the two records to make a 1139 determination as to which record is better. 1141 7.7. Multiple Queries to a Single Server over One Connection 1143 Bulk Leasequery requestors may need to make multiple queries in order 1144 to recover binding information. A requestor MAY use a single 1145 connection to issue multiple queries to a server willing to support 1146 them. Each query MUST have a unique xid. 1148 A server SHOULD allow configuration of the number of queries that can 1149 be processed simultaneously over a single connection. A server 1150 SHOULD read the number of queries it is configured to process 1151 simultaneously and only read any subsequent queries as current 1152 queries are processed. 1154 A server that is processing multiple queries simultaneously MUST 1155 interleave replies to the multiple queries within the stream of reply 1156 messages it sends. Requestors need to be aware that replies for 1157 multiple queries may be interleaved within the stream of reply 1158 messages. Requestors that are not able to process interleaved 1159 replies (based on xid) MUST NOT send more than one query over a 1160 single connection prior to the completion of the previous query. 1162 Requestors should be aware that servers are not required to process 1163 more than one query over a connection at a time (the limiting case 1164 for the configuration described above), and that servers are likely 1165 to limit the rate at which they process queries from any one 1166 requestor. 1168 7.7.1. Example 1170 This example illustrates what a series of queries and responses might 1171 look like. This is only an example - there is no requirement that 1172 this sequence must be followed, or that requestors or servers must 1173 support parallel queries. 1175 In the example session, the client sends four queries after 1176 establishing a connection. Query 1 returns no results; query 2 1177 returns 3 messages and the stream of replies concludes before the 1178 client issues any new query. Query 3 and query 4 overlap, and the 1179 server interleaves its replies to those two queries. 1181 Requestor Server 1182 --------- ------ 1183 DHCPBULKLEASEQUERY xid 1 -----> 1184 <----- DHCPLEASEQUERYDONE xid 1 1185 DHCPBULKLEASEQUERY xid 2 -----> 1186 <----- DHCPLEASEACTIVE xid 2 1187 <----- DHCPLEASEACTIVE xid 2 1188 <----- DHCPLEASEACTIVE xid 2 1189 <----- DHCPLEASEQUERYDONE xid 2 1190 DHCPBULKLEASEQUERY xid 3 -----> 1191 DHCPBULKLEASEQUERY xid 4 -----> 1192 <----- DHCPLEASEACTIVE xid 4 1193 <----- DHCPLEASEACTIVE xid 4 1194 <----- DHCPLEASEACTIVE xid 3 1195 <----- DHCPLEASEACTIVE xid 4 1196 <----- DHCPLEASEUNASSIGNED xid 3 1197 <----- DHCPLEASEACTIVE xid 4 1198 <----- DHCPLEASEACTIVE xid 3 1199 <----- DHCPLEASEQUERYDONE xid 3 1200 <----- DHCPLEASEACTIVE xid 4 1201 <----- DHCPLEASEQUERYDONE xid 4 1203 7.8. Closing Connections 1205 The requestor SHOULD close the connection after the 1206 DHCPLEASEQUERYDONE message is received for the last outstanding query 1207 that it has sent. 1209 8. Server Behavior 1210 8.1. Accepting Connections 1212 Servers that implement DHCPv4 Bulk Leasequery listen for incoming TCP 1213 connections. Port numbers are discussed in Section 6.3. Servers 1214 MUST be able to limit the number of currently accepted and active 1215 connections. The value BULK_LQ_MAX_CONNS SHOULD be the default; 1216 implementations MAY permit the value to be configurable. Connections 1217 SHOULD be accepted and, if the number of connections is over 1218 BULK_LQ_MAX_CONNS, they SHOULD be closed immediately. 1220 Servers MAY restrict Bulk Leasequery connections and 1221 DHCPBULKLEASEQUERY messages to certain requestors. Connections not 1222 from permitted requestors SHOULD be closed immediately, to avoid 1223 server connection resource exhaustion. Servers MAY restrict some 1224 requestors to certain query types. Servers MAY reply to queries that 1225 are not permitted with the DHCPLEASEQUERYDONE message with a dhcp- 1226 message status of NotAllowed, or MAY simply close the connection. 1228 If the TCP connection becomes blocked while the server is accepting a 1229 connection or reading a query, it SHOULD be prepared to terminate the 1230 connection after an BULK_LQ_DATA_TIMEOUT. We make this 1231 recommendation to allow servers to control the period of time they 1232 are willing to wait before abandoning an inactive connection, 1233 independent of the TCP implementations they may be using. 1235 8.2. Replying to a Bulk Leasequery 1237 If the connection becomes blocked while the server is attempting to 1238 send reply messages, the server SHOULD be prepared to terminate the 1239 TCP connection after BULK_LQ_DATA_TIMEOUT. 1241 Every Bulk Leasequery request MUST be terminated by sending a final 1242 DHCPLEASEQUERYDONE message if such a message can be sent. The 1243 DHCPLEASEQUERYDONE message MUST have a dhcp-message status if the 1244 termination was other than successful, and SHOULD NOT contain a 1245 dhcp-message status if the termination was successful. 1247 If the DHCPv4 server encounters an error during processing of the 1248 DHCPBULKLEASEQUERY message, either during initial processing or later 1249 during the message processing, it SHOULD send a DHCPLEASEQUERYDONE 1250 containing a status dhcp-message option. It MAY close the connection 1251 after this error is signaled, but that is not required. 1253 If the server does not find any bindings satisfying a query, it MUST 1254 send a DHCPLEASEQUERYDONE. It SHOULD NOT include a dhcp-message 1255 option with a Success status unless there is a useful string to 1256 include in the dhcp-message option. Otherwise, the server sends each 1257 binding's data in a DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message. 1259 The response to a DHCPBULKLEASEQUERY may involve examination of 1260 multiple DHCPv4 IP address bindings maintained by the DHCPv4 server. 1261 The Bulk Leasequery protocol does not require any ordering of the IP 1262 addresses returned in DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED 1263 messages. 1265 When responding to a DHCPBULKLEASEQUERY message, the DHCPv4 server 1266 MUST NOT send more than one message for each applicable IP address, 1267 even if the state of some of those IP addresses changes during the 1268 processing of the message. Updates to such IP address state are 1269 already handled by normal protocol processing, so no special effort 1270 is needed here. (I hope!) 1272 If the ciaddr, yiaddr, or siaddr is non-zero in a DHCPBULKLEASEQUERY 1273 request, the request must be terminated immediately by a 1274 DHCPLEASEQUERYDONE message with a dhcp-message status of 1275 MalformedQuery. 1277 Any DHCPBULKLEASEQUERY which has more than one of the following 1278 primary query types specified MUST be terminated immediately by a 1279 DHCPLEASEQUERYDONE message with a dhcp-message status code of 1280 NotAllowed. 1282 The allowable queries in a DHCPBULKLEASEQUERY message are processed 1283 as follows. Note that the descriptions of the primary queries below 1284 must be constrained by the actions of any of the three qualifiers 1285 described subsequently as well. 1287 The following table discusses how to process the various queries. 1288 For information on how to identify the query, see the information in 1289 Section 7.2. 1291 o Query by MAC address 1293 Every IP address that has a current binding to a DHCPv4 client 1294 matching the chaddr, htype, and hlen in the DHCPBULKLEASEQUERY 1295 request MUST be returned in a DHCPLEASEACTIVE message. 1297 o Query by Client-Id 1299 Every IP address that has a current binding to a DHCPv4 client 1300 matching the client-id option in the DHCPBULKLEASEQUERY request 1301 MUST be returned in a DHCPLEASEACTIVE message. 1303 o Query by Remote-Id 1305 Every IP address that has a current binding to a DHCPv4 client 1306 matching the remote-id sub-option of the relay-agent-information 1307 option in the DHCPBULKLEASEQUERY request MUST be returned in a 1308 DHCPLEASEACTIVE message. 1310 o Query by Relay-Id 1312 Every IP address that has a current binding to a DHCPv4 client 1313 matching the relay-id sub-option of the relay-agent-information 1314 option in the DHCPBULKLEASEQUERY request MUST be returned in a 1315 DHCPLEASEACTIVE message. 1317 o Query for All Configured IP Addresses 1319 A Query for All Configured IP addresses is signaled by the 1320 absence of any other primary query. That is, if there is no 1321 value in the chaddr, hlen, htype, no client-id option, no 1322 remote-id sub-option or relay-id sub-option of the relay-agent- 1323 information option, then the request is a query for information 1324 concerning all configured IP addresses. In this case, every 1325 configured IP address that has a current binding to a DHCPv4 1326 client MUST be returned in a DHCPLEASEACTIVE message. In 1327 addition, every configured IP address that does not have a 1328 current binding to a DHCPv4 client MUST be returned in a 1329 DHCPLEASEUNASSIGNED message. 1331 In this form of query, each configured IP address MUST be 1332 returned at most one time. If the absence of qualifiers 1333 restricting the number of IP addresses returned, every 1334 configured IP address MUST be returned exactly once. 1336 There are three qualifiers that can be applied to any of the above 1337 primary queries. These qualifiers can appear individually or 1338 together in any combination, but only one of each can appear. 1340 o Query Start Time 1342 If a query-start-time option appears in the DHCPBULKLEASEQUERY 1343 request, only IP address bindings that have changed on or after the 1344 time specified in the query-start-time option should be returned. 1346 o Query End Time 1348 If a query-end-time option appears in the DHCPBULKLEASEQUERY 1349 request, only IP address bindings that have changed on or before 1350 the time specified in the query-end-time option should be returned. 1352 o VPN Id 1353 If no vpn-id option appears in the DHCPBULKLEASEQUERY, the default 1354 VPN is used to satisfy the query. A vpn-id option [VpnId] value 1355 other than the wildcard value (254) allows the requestor to specify 1356 a single VPN other than the default VPN. In addition, the vpn-id 1357 option has been extended as part of this document to allow 1358 specification of a type 254 which indicates that all configured 1359 VPN's be searched in order to satisfy the primary query. 1361 In all cases, if the information returned in a DHCPLEASEACTIVE or 1362 DHCPLEASEUNASSIGNED message is for a VPN other than the default, a 1363 vpn-id option MUST appear in the packet. 1365 The query-start-time and query-end-time qualifiers are used to 1366 constrain the amount of data returned by a Bulk Leasequery request by 1367 returning only IP addresses whose address bindings have changed in 1368 some way during the time window specified by the query-start-time and 1369 query-end-time. 1371 A DHCPv4 server SHOULD consider an address binding to have changed 1372 during a specified time window if either the client-last- 1373 transaction-time or the start-time-of-state of the address binding 1374 changed during that time window. 1376 The DHCPv4 server MAY return address binding data in any order, as 1377 long as binding information for any given IP address is not repeated. 1378 When all binding data for a given DHCPBULKLEASEQUERY has been sent, 1379 the DHCPv4 server MUST send a DHCPBULKLEASEQUERYDONE message. 1381 8.3. Building a Single Reply for Bulk Leasequery 1383 The DHCPv4 Leasequery [RFC4388] specification describes the initial 1384 construction of DHCPLEASEQUERY reply messages using the 1385 DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED message types in Section 1386 5.4.2. All of the reply messages in Bulk Leasequery are similar to 1387 the reply messages for an IP address query. Message transmission and 1388 framing for TCP is described in this document in Section 6.1. 1390 [RFC2131] and [RFC4388] specify that every response message MUST 1391 contain the server-identifier option. However, that option will be 1392 the same for every response from a particular DHCPBULKLEASEQUERY 1393 request. Thus, the DHCPv4 server MUST include the server-identifier 1394 option in the first message sent in response to a DHCPBULKLEASEQUERY. 1395 It SHOULD NOT include the server-identifier in later messages. 1397 The message type of DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED is based 1398 on the value of the dhcp-state option. If the dhcp-state option 1399 value is ACTIVE, then the message type is DHCPLEASEACTIVE, otherwise 1400 the message type is DHCPLEASEUNASSIGNED. 1402 In addition to the basic message construction described in [RFC4388], 1403 the following guidelines exist: 1405 1. If the dhcp-state option code appears in the dhcp-parameter- 1406 request-list, the DHCPv4 server SHOULD include a dhcp-state 1407 option whose value corresponds most closely to the state held 1408 by the DHCPv4 server for the IP address associated with this 1409 reply. If the state is ACTIVE and the message being returned 1410 is DHCPLEASEACTIVE, then the DHCPv4 server MAY choose to not 1411 send the dhcp-state option. The requestor SHOULD assume that 1412 any DHCPLEASEACTIVE message arriving without a requested dhcp- 1413 state option has a dhcp-state of ACTIVE. 1415 2. If the base-time option code appears in the dhcp-parameter- 1416 request-list, the DHCPv4 server MUST include a base-time 1417 option, which is the current time in the DHCPv4 server's 1418 context and the time from which the start-time-of-state, dhcp- 1419 lease-time, client-last-transaction-time, and other duration- 1420 style times are based upon. 1422 3. If the start-time-of-state option code appears in the dhcp- 1423 parameter-request-list, the DHCPv4 server MUST include a 1424 start-time-of-state option whose value represents the time at 1425 which the dhcp-state option's state became valid. 1427 4. If the dhcp-lease-time option code appears in the dhcp- 1428 parameter-request-list, the DHCPv4 server MUST include a dhcp- 1429 lease-time option for any state that has a time-out value 1430 associated with it. In the [RFC4388] Leasequery, the dhcp- 1431 lease-time option appears only in a DHCPLEASEACTIVE message. 1432 Thus, the EXPIRED state, which is sent in a DHCPLEASEUNASSIGNED 1433 message, would have a dhcp-lease-time option in the message if 1434 the EXPIRED state represented a grace-period and would be 1435 changed into the FREE state after the expiration of the grace- 1436 period. 1438 5. If the data-source option code appears in the dhcp-parameter- 1439 request-list, the DHCPv4 server MUST include the data-source 1440 option in any situation where any of the bits would be non- 1441 zero. Thus, in the absence of the data-source option, the 1442 assumption is that all of the flags were zero. 1444 6. If the client-last-transaction-time option code appears in the 1445 dhcp-parameter-request-list, The DHCPv4 server MUST include the 1446 client-last-transaction-time option in any situation where the 1447 information is available. 1449 7. If there is a dhcp-parameter-request-list in the initial 1450 DHCPBULKLEASEQUERY request, then it should be used for all of 1451 the replies generated by that request. Some options can be 1452 sent from a DHCPv4 client to the server or from the DHCPv4 1453 server to a DHCPv4 client. Option 125 is such an option. If 1454 the option code for one of these options appears in the dhcp- 1455 parameter-request-list, it SHOULD result in returning the value 1456 of the option sent by the DHCPv4 client to the server if one 1457 exists. 1459 Note that there may be other requirements for a reply to a 1460 DHCPBULKLEASEQUERY request discussed in Section 8.2. 1462 8.4. Multiple or Parallel Queries 1464 As discussed in Section 7.3, requestors may want to use a connection 1465 that has already been established when they need to make additional 1466 queries. Servers SHOULD support reading and processing multiple 1467 queries from a single connection and SHOULD allow configuration of 1468 the number of simultaneous queries it may process. A server MUST NOT 1469 read more query messages from a connection than it is prepared to 1470 process simultaneously. 1472 This SHOULD be a feature that is administratively controlled. 1473 Servers SHOULD offer configuration that limits the number of 1474 simultaneous queries permitted from any one requestor, in order to 1475 control resource use if there are multiple requestors seeking 1476 service. 1478 8.5. Closing Connections 1480 The DHCPv4 server SHOULD start a timer for BULK_LQ_DATA_TIMEOUT 1481 seconds for a particular connection after it sends a 1482 DHCPLEASEQUERYDONE message over that connection and if there is no 1483 current outstanding query outstanding for that connection. It should 1484 clear this timer if a query arrives over that connection. If the 1485 timer expires, the DHCPv4 server should close the connection. 1487 The server MUST close its end of the TCP connection if it encounters 1488 an error sending data on the connection. The server MUST close its 1489 end of the TCP connection if it finds that it has to abort an in- 1490 process request. A server aborting an in-process request SHOULD 1491 attempt to signal that to its requestors by using the QueryTerminated 1492 status code in the dhcp-message option in a DHCPLEASEQUERYDONE 1493 message, including a message string indicating details of the reason 1494 for the abort. If the server detects that the requesting end of the 1495 connection has been closed, the server MUST close its end of the 1496 connection. 1498 9. Security Considerations 1500 The "Security Considerations" section of [RFC2131] details the 1501 general threats to DHCPv4. The DHCPv4 Leasequery specification 1502 [RFC4388] describes recommendations for the Leasequery protocol, 1503 especially with regard to authentication of LEASEQUERY messages, 1504 mitigation of packet-flooding DOS attacks, and restriction to trusted 1505 requestors. 1507 The use of TCP introduces some additional concerns. Attacks that 1508 attempt to exhaust the DHCPv4 server's available TCP connection 1509 resources, such as SYN flooding attacks, can compromise the ability 1510 of legitimate requestors to receive service. Malicious requestors 1511 who succeed in establishing connections, but who then send invalid 1512 queries, partial queries, or no queries at all also can exhaust a 1513 server's pool of available connections. We recommend that servers 1514 offer configuration to limit the sources of incoming connections, 1515 that they limit the number of accepted connections and the number of 1516 in-process queries from any one connection, and that they limit the 1517 period of time during which an idle connection will be left open. 1519 [RFC4388] discusses security concerns and potential solutions for 1520 DHCPLEASEQUERY message exchanges in its Section 7, and all of the 1521 solutions discussed there are applicable to the DHCPLEASEQUERY 1522 message exchanges described in this document. 1524 10. IANA Considerations 1526 IANA is requested to assign the following new values for this 1527 document. See Section 6.2 for details. 1529 1. A dhcp-message-type of 14 for DHCPBULKLEASEQUERY. 1531 2. A dhcp-message-type of 15 for DHCPLEASEQUERYDONE. 1533 3. An option code of TBD1 for base-time. 1535 4. An option code of TBD2 for start-time-of-state. 1537 5. An option code of TBD3 for query-start-time. 1539 6. An option code of TBD4 for query-end-time. 1541 7. An option code of TBD5 for data-source. 1543 8. An option code of TBD6 for dhcp-state. 1545 9. Values for dhcp-state: 1547 State 1548 ----- 1549 1 AVAILABLE 1550 2 ACTIVE 1551 3 EXPIRED 1552 4 RELEASED 1553 5 ABANDONED 1554 6 RESET 1555 7 REMOTE 1556 8 TRANSITIONING 1558 10.Values for status code in a constrained dhcp-message option 1559 (option 53): 1561 Name status-code 1562 ---- ----------- 1563 Success 000 1564 UnspecFail 001 1565 QueryTerminated 002 1566 MalformedQuery 003 1567 NotAllowed 004 1569 11.Additional type field values for the Virtual Subnet Selection 1570 Type and Information [VpnId]: 1572 Type VSS Information format: 1574 0 NVT ASCII VPN identifier 1575 1 RFC2685 VPN-ID 1576 2-253 Not Allowed 1577 NEW -> 254 All VPN's. (wildcard) 1578 255 Global, default VPN. 1580 11. Acknowledgements 1582 This draft is a collaboration between the authors of draft-dtv-dhc- 1583 dhcpv4-bulk-leasequery-00.txt and draft-kkinnear-dhc-dhcpv4-bulk- 1584 leasequery-00.txt. Both documents acknowledged that significant text 1585 as well as important ideas were borrowed in whole or in part from the 1586 DHCPv6 Bulk Leasequery RFC, [RFC5460] written by Mark Stapp. Further 1587 suggestions and improvements were made by participants in the DHC 1588 working group, including Alfred Hoenes. 1590 12. References 1592 12.1. Normative References 1594 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1595 Requirement Levels", RFC 2119, March 1997. 1597 [RFC2131] Droms, R., "Dynamic Host Configuration Protocol", RFC 2131, 1598 March 1997. 1600 [RFC2132] Alexander, S., Droms, R., "DHCP Options and BOOTP Vendor 1601 Extensions", RFC 2132, March 1997. 1603 [RFC3046] Patrick, M., "DHCP Relay Agent Information Option", RFC 1604 3046, January 2001. 1606 [RFC4388] Woundy, R., K. Kinnear, "Dynamic Host Configuration 1607 Protocol (DHCP) Leasequery", RFC 4388, February 2006. 1609 [RelayId] Stapp, M., "The DHCPv4 Relay Agent Identifier Suboption", 1610 draft-ietf-dhc-relay-id-suboption-07.txt, (work in progress) July 1611 2009. 1613 [VpnId] Kinnear, K., R. Johnson, M. Stapp and J. Kumarasamy, "Virtual 1614 Subnet Selection Options for DHCPv4 and DHCPv6" draft-ietf-dhc- 1615 vpn-option-11.txt, (work in progress) March 2009. 1617 12.2. Informative References 1619 [RFC951] Croft, B., Gilmore, J., "Bootstrap Protocol (BOOTP)", RFC 1620 951, September 1985. 1622 [RFC1542] Wimer, W., "Clarifications and Extensions for the Bootstrap 1623 Protocol", RFC 1542, October 1993. 1625 [RFC4614] Duke, M., R. Braden, W. Eddy, and E. Blanton, "A Roadmap 1626 for Transmission Control Protocol (TCP) Specification Documents", 1627 RFC 4614, September 2006. 1629 [RFC5460] Stapp, M., "DHCPv6 Bulk Leasequery", RFC 5460, February 1630 2009. 1632 Authors' Addresses 1634 Kim Kinnear 1635 Cisco Systems 1636 1414 Massachusetts Ave. 1637 Boxborough, Massachusetts 01719 1639 Phone: (978) 936-0000 1641 EMail: kkinnear@cisco.com 1643 Bernie Volz 1644 Cisco Systems 1645 1414 Massachusetts Ave. 1646 Boxborough, Massachusetts 01719 1648 Phone: (978) 936-0000 1650 EMail: volz@cisco.com 1652 Neil Russell 1653 10 Jordan Terrace 1654 Wakefield, MA 01880 1656 EMail: provng@gmail.com 1658 Mark Stapp 1659 Cisco Systems 1660 1414 Massachusetts Ave. 1661 Boxborough, Massachusetts 01719 1663 Phone: (978) 936-0000 1665 EMail: mjs@cisco.com 1667 Ramakrishna Rao DTV 1668 Infosys Technologies Ltd. 1669 44 Electronics City, Hosur Road 1670 Bangalore 560 100 1671 India 1673 EMail: ramakrishnadtv@infosys.com 1674 URI: http://www.infosys.com/ 1676 Bharat Joshi 1677 Infosys Technologies Ltd. 1678 44 Electronics City, Hosur Road 1679 Bangalore 560 100 1680 India 1682 EMail: bharat_joshi@infosys.com 1683 URI: http://www.infosys.com/ 1685 Pavan Kurapati 1686 Infosys Technologies Ltd. 1687 44 Electronics City, Hosur Road 1688 Bangalore 560 100 1689 India 1691 EMail: pavan_kurapati@infosys.com 1692 URI: http://www.infosys.com/