RFC 6926
DHCPv4 Bulk Leasequery
RFC 6926: DHCPv4 Bulk Leasequery 🎀
okay bestie, let's get into it! 💖 This is the standards-track spec that lets DHCPv4 Leasequery do bulk transfers over TCP 🦋
The title block has everything you need up top:
- Who wrote it: K. Kinnear and M. Stapp from Cisco Systems, Inc., R. Desetti and B. Joshi from Infosys Ltd., N. Russell from Sea Street Technologies Inc., P. Kurapati from Juniper Networks, and B. Volz from Cisco Systems, Inc. again 👑
- Category: Standards Track
- Date: April 2013
- ISSN: 2070-1721
- Obsoletes and updates: the title block doesn't list anything it obsoletes or updates 🧚
Abstract 🌸
so the DHCPv4 Leasequery protocol lets a requestor ask about DHCPv4 bindings ✨ the catch is that it only handles queries for individual bindings. 🙈 Sometimes asking one binding at a time is slow or just not possible, which is giving "not it" energy 💀 This document extends DHCPv4 Leasequery so you can bulk transfer DHCPv4 address binding data over TCP 💅
Status of This Memo 💜
this is an Internet Standards Track document 🔥
it's a product of the Internet Engineering Task Force (IETF), so it represents the consensus of the IETF community. it went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). 👑 If you want more on Internet Standards, check out Section 2 of RFC 5741 🌈
for the current status, any errata, and how to send feedback, go to http://www.rfc-editor.org/info/rfc6926 🦋
Copyright Notice 🫶
Copyright (c) 2013 IETF Trust and the persons identified as the document authors. All rights reserved. 💖
this document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they stand on the publication date. please actually read these, bestie, because they spell out your rights and restrictions for this document 🙈 Code Components pulled out of this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as the Simplified BSD License describes ✨
Table of Contents 📜
1. Introduction ....................................................4
2. Terminology .....................................................5
3. Design Goals ....................................................8
3.1. Information Acquisition before Data Starts .................8
3.2. Lessen Need for Caching and Negative Caching ...............8
3.3. Antispoofing in 'Fast Path' ................................8
3.4. Minimize Data Transmission .................................9
4. Protocol Overview ...............................................9
5. Interaction between UDP Leasequery and Bulk Leasequery .........11
6. Message and Option Definitions .................................12
6.1. Message Framing for TCP ...................................12
6.2. New or Changed Options ....................................13
6.3. Connection and Transmission Parameters ....................20
7. Requestor Behavior .............................................21
7.1. Connecting and General Processing .........................21
7.2. Forming a Bulk Leasequery .................................21
7.3. Processing Bulk Replies ...................................23
7.4. Processing Time Values in Leasequery Messages .............25
7.5. Querying Multiple Servers .................................26
7.6. Making Sense out of Multiple Responses concerning
a Single IPv4 Address .....................................26
7.7. Multiple Queries to a Single Server over One Connection ...27
7.8. Closing Connections .......................................28
8. Server Behavior ................................................29
8.1. Accepting Connections .....................................29
8.2. Replying to a Bulk Leasequery .............................29
8.3. Building a Single Reply for Bulk Leasequery ...............33
8.4. Multiple or Parallel Queries ..............................34
8.5. Closing Connections .......................................35
9. Security Considerations ........................................35
10. IANA Considerations ...........................................37
11. Acknowledgements ..............................................38
12. References ....................................................38
12.1. Normative References .....................................38
12.2. Informative References ...................................391. Introduction ✨
okay so DHCPv4 [RFC2131] [RFC2132] is the protocol that hands out IPv4 addresses and configuration info to IPv4 nodes 🌸 DHCPv4 servers are the ones keeping the authoritative binding info 👑
check out this layout (Figure 1) 🦋
+--------+
| DHCPv4 | +--------------+
| Server |-...-| DHCP |
| | | Relay Agent |
+--------+ +--------------+
| |
+------+ +------+
|Modem1| |Modem2|
+------+ +------+
| | |
+-----+ +-----+ +-----+
|Node1| |Node2| |Node3|
+-----+ +-----+ +-----+
Figure 1: Example DHCPv4 Configurationso DHCPv4 relay agents receive DHCPv4 messages and usually tack on a Relay Agent Information option [RFC3046] before forwarding them to the configured DHCPv4 servers (see Figure 1) 💅 Some relay agents also glean lease info from what the server sends and cache it locally 🧚 That info gets used for a bunch of stuff, like stopping spoofing attempts from DHCPv4 clients and installing routes ✨ The problem is, when a relay agent reboots, that info is often lost 💀
the DHCPv4 Leasequery capability [RFC4388] extends basic DHCPv4 so an outside entity, like a relay agent, can ask a DHCPv4 server to quickly recover lease state about a particular IP address or client 🫶
here's the thing though: existing Leasequery query types are usually data driven, meaning the relay agent starts a Leasequery when it sees data traffic to or from the client 🙈 That can scale badly when there are thousands of clients on one relay agent, or when the relay agent needs to rebuild its internal data store before it handles traffic in one direction or the other 😭
some applications need to query the server without waiting for traffic from or to clients 💜 That kind of query needs an underlying transport that's better suited to bulk data transmission 🔥
so this document extends the DHCPv4 Leasequery protocol [RFC4388] to support queries that cover these extra requirements 🌈 A single request can return many thousands of DHCPv4 bindings, so TCP [RFC4614] is specified for efficient data transfer 🦋 We define several more query types, and each one can return multiple responses, so we can meet a whole variety of requirements 👑 iconic, honestly 💖
- Terminology ✨
okay so bestie, this section is the glossary 🎀 and you NEED it before anything else, because the rest of the doc uses these words like everyone already knows them 💅 the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC2119]. that's the official rulebook for how strong each of those words is 📖✨
here's the vocab list 🦋
- "absolute time" 🕰️ is a 32-bit quantity containing the number of seconds since January 1, 1970. just a plain old timestamp, nothing fancy 💖
- "access concentrator" 🌐 is a router or switch at the broadband access provider's edge of a public broadband access network. this document assumes that the access concentrator includes the DHCPv4 relay agent functionality, for example, a CMTS (Cable Modem Termination System) in a cable environment or a DSLAM (Digital Subscriber Line Access Multiplexer) in a DSL environment. basically the gatekeeper at the edge, and it's doing relay work too 🫶
- "active binding" 🔗 is an IP address with an active binding, which means an IP address that is currently associated with a DHCPv4 client where that DHCPv4 client has the right to use the IP address. so it's taken AND the client is allowed to have it 🌸
- "Bulk Leasequery" 📦 involves requesting and receiving the existing DHCPv4 address binding information in an efficient manner. the whole point is getting a big pile of bindings fast ✨
- "clock skew" ⏱️ for a Bulk Leasequery connection is the difference between the absolute time on a DHCPv4 server and the absolute time on the system where a requestor of a Bulk Leasequery is executing. it is not absolutely constant but is likely to vary only slowly. 🐢
it is possible that, when both systems run NTP, the clock skew is negligible; this is not only acceptable but desired. 😌
while it is easy to think that this can be calculated precisely after one message is received by a requestor from a DHCPv4 server, a more accurate value is derived from continuously examining the instantaneous value developed from each message received from a DHCPv4 server and using it to make small adjustments to the existing value held in the requestor. so one message isn't enough, you keep nudging the number as more messages come in 📈💜
- "Default VPN" 🏠 indicates that the address being described belongs to the set of addresses not part of any VPN (in other words, the normal address space operated on by DHCP). this includes Special Use IPv4 Addresses as defined in [RFC5735]. the regular, no-VPN neighborhood 🏡
- "DHCPv4 client" 💻 is an Internet node using DHCPv4 to obtain configuration parameters such as a network address.
- "DHCPv4 relay agent" 📬 is an agent that is neither a DHCPv4 client nor a DHCP server that transfers BOOTP and DHCPv4 messages between clients and servers residing on different subnets, per [RFC951] and [RFC1542]. it's the middle person between subnets 💌
- "DHCPv4 server" 🖥️ is an Internet node that returns configuration parameters to DHCPv4 clients. the one handing out the goodies 🎁
- "DSLAM" 📡 stands for Digital Subscriber Line Access Multiplexer.
- "downstream" ⬇️ refers to a direction away from the central part of a network and toward the edge. in a DHCPv4 context, this typically refers to a network direction that is away from the DHCPv4 server and toward the DHCPv4 client.
- "Global VPN" 🌍 is another name for the default VPN. same vibe, different name 🙈
- "IP address" 🔢 in this document, the term "IP address" refers to an IPv4 IP address. just IPv4, no IPv6 drama here 💅
- "IP address binding" 🧾 is the information that a DHCPv4 server keeps regarding the relationship between a DHCPv4 client and an IP address. this includes the identity of the DHCPv4 client and the expiration time, if any, of any lease that client has on a particular IP address. in some contexts, this may include information on IP addresses that are currently associated with DHCPv4 clients, and in others, it may also include IP addresses with no current association to a DHCPv4 client. the server's little record card 🗂️
- "MAC address" 🪪 in the context of a DHCPv4 message, a Media Access Control (MAC) address consists of the fields: hardware type "htype", hardware length "hlen", and client hardware address "chaddr".
- "upstream" ⬆️ refers to a direction toward the central part of a network and away from the edge. in a DHCPv4 context, this typically refers to a network direction that is away from the DHCPv4 client and toward the DHCPv4 server. opposite of downstream, obviously 🙃
- "stable storage" 💾 is used to hold information concerning IP address bindings (among other things) so that this information is not lost in the event of a failure that requires restart of the network element. DHCPv4 servers are typically expected to have high-speed access to stable storage, while relay agents and access concentrators usually do not have access to stable storage, although they may have periodic access to such storage. the safe deposit box that survives a crash 🔐
- "xid" 🎫 is "Transaction-id." the term "xid" refers to the DHCPv4 field containing the transaction-id of the message.
3. Design Goals 🎯
okay the goal here is giving us a lightweight protocol 🪶 so an access concentrator or other network element (such as a DHCP relay agent) can retrieve IP address binding information available in the DHCPv4 server. the protocol should also allow an access concentrator or DHCP relay agent to retrieve consolidated IP address binding information for either the entire access concentrator or a single connection/circuit. throughout the discussion below, everything that applies to an access concentrator also applies to a DHCP relay agent. ✨
3.1. Information Acquisition before Data Starts 🚦
the existing data-driven approach required by [RFC4388] means that the Leasequeries can only be performed after an access concentrator receives data. to implement antispoofing, the concentrator must drop messages for each client until it gets lease information from the DHCPv4 server for that client. if an access concentrator finishes the Leasequeries before it starts receiving data, then there is no need to drop legitimate messages. in this way, outage time may be reduced. 📉💖
3.2. Lessen Need for Caching and Negative Caching 🗃️
the result of a single Leasequery should be cached, whether that results in a positive or negative cache, in order to remember that the Leasequery was performed. this caching is required to limit the traffic imposed upon a DHCPv4 server by Leasequeries for information already received.
these caches not only consume precious resources, they also need to be managed. hence, they should be avoided as much as possible. one of the goals of the DHCPv4 Bulk Leasequery is to reduce the need for this sort of caching. 🧹
3.3. Antispoofing in 'Fast Path' ⚡
if antispoofing is not done in the fast path, it will become a bottleneck and may lead to denial of service of the access concentrator. the Leasequeries should make it possible to do antispoofing in the fast path. no slowdowns allowed 🏎️
3.4. Minimize Data Transmission 📦
it may be that a network element is able to periodically save its entire list of assigned IP addresses to some form of stable storage. in this case, it will wish to recover all of the updates to this information without duplicating the information it has recovered from its own stable storage.
bulk leasequery allows the specification of a query-start-time as well as a query-end-time. use of query times allows a network element that periodically commits information to stable storage to recover just what it lost since the last commit. only the missing bits, no re-downloading the whole thing 🙌
4. Protocol Overview 🧚
the DHCPv4 Bulk Leasequery protocol is modeled on the existing individual DHCPv4 Leasequery protocol in [RFC4388] as well as related work on DHCPv6 Bulk Leasequery [RFC5460]. a Bulk Leasequery requestor opens a TCP connection to a DHCPv4 server using the DHCPv4 port 67. note that this implies that the Leasequery requestor has server IP address(es) available via configuration or some other means and that it has unicast IP reachability to the DHCPv4 server. no relaying of Bulk Leasequery messages is specified. 🛣️
after establishing a connection, the requestor sends a DHCPBULKLEASEQUERY message over the connection. 📨
the server uses the message type and additional data in the DHCPv4 DHCPBULKLEASEQUERY message to identify any relevant bindings. 🔍
in order to support some query types, servers may have to maintain additional data structures or otherwise be able to locate bindings that have been requested by the Leasequery requestor. 🗝️
relevant bindings are returned in DHCPv4 messages with either the DHCPLEASEACTIVE message type for an IP address with a currently active lease or, in some situations, a DHCPLEASEUNASSIGNED message type for an IP address that is controlled by the DHCPv4 server but is not actively leased by a DHCPv4 client at the present time. 🎁
the Bulk Leasequery protocol is designed to provide an external entity with information concerning existing DHCPv4 IPv4 address bindings managed by the DHCPv4 server. when complete, the DHCPv4 server will send a DHCPLEASEQUERYDONE message. if a connection is lost while processing a Bulk Leasequery, the Bulk Leasequery must be retried as there is no provision for determining the extent of data already received by the requestor for a Bulk Leasequery. 🔁
heads up bestie: if the connection drops mid-query, you MUST retry the whole thing, because there's no way to tell how much already arrived 😭
Bulk Leasequery supports queries by MAC address and by Client Identifier in a way similar to [RFC4388]. the Bulk Leasequery protocol also adds several new queries. 🆕
- Query by Relay Identifier 🆔
this query asks a server for the bindings associated with a specific relay agent; the relay agent is identified by a Relay Agent Identifier carried in a Relay-ID sub-option [RFC6925]. relay agents can include this sub-option while relaying messages to DHCPv4 servers. servers can retain the Relay-ID and associate it with bindings made on behalf of the relay agent's clients. the bindings returned are only those for DHCPv4 clients with a currently active binding.
- Query by Remote ID 🛰️
this query asks a server for the bindings associated with a relay agent Remote ID sub-option [RFC3046] value. the bindings returned are only those for DHCPv4 clients with a currently active binding.
- Query for All Configured IP Addresses 🌈
this query asks a server for information concerning all IP addresses configured in that DHCPv4 server by specifying no other type of query. in this case, the bindings returned are for all configured IP addresses, whether or not they contain a currently active binding to a DHCPv4 client, since one point of this type of query is to update an existing database with changes after a particular point in time.
any of the above queries can be qualified by the specification of a query-start-time or a query-end-time (or both). when these timers are used as qualifiers, they indicate that a binding should be included if it changed on or after the query-start-time and on or before the query-end-time. ⏳
in addition, any of the above queries can be qualified by the specification of a VPN-ID option [RFC6607] to select the VPN on which the query should be processed. the VPN-ID option is also extended to allow queries across all available VPNs. in the absence of any VPN-ID option, only the default (global) VPN is used to satisfy the query. 🌐💜
- Interaction between UDP Leasequery and Bulk Leasequery ✨
Okay so Bulk Leasequery is basically a glow-up of the existing UDP Leasequery protocol [RFC4388] 🦋. This section spells out how the two are related, and bestie, it's giving clarity 💅.
The Bulk Leasequery TCP connection is only built for the DHCPBULKLEASEQUERY request 🎀. It is NOT meant to be a replacement DHCPv4 communication option for clients who want other DHCPv4 services 🙅♀️. Honestly, DHCPv4 address allocation couldn't happen over TCP anyway, because a TCP connection needs an IP address and no IPv4 address exists before a successful DHCPv4 address allocation exchange 💀. Plus, the existing DHCPv4 UDP transmission regime is running on untold millions of devices all over the world 🌍, and messing with DHCPv4 services using other transport approaches (even if it were possible) would be way worse than any perceived benefit 😭.
Two of the query types from the UDP Leasequery protocol can be used in Bulk Leasequery too 🍓: Query by MAC address and Query by Client-identifier ✨.
The reply messages look pretty similar between UDP Leasequery and Bulk Leasequery 💜, though Bulk Leasequery messages give you more info 🌸.
One behavior change is REQUIRED when Bulk Leasequery is in use 🔥. Sections 6.1, 6.4.1, and 6.4.2 of [RFC4388] describe using an associated-ip option in DHCPLEASEACTIVE messages when multiple bindings are found 🧚. With Bulk Leasequery, this mechanism is not necessary, because a server returning multiple bindings just does it directly, as this document specifies 💖. The associated-ip option MUST NOT appear in Bulk Leasequery replies 🙈.
Implementors, pay attention 👑: the TCP message framing defined in Section 6.1 is NOT compatible with the UDP message format 🚫. If a TCP-framed request gets sent as a UDP message, it may not be valid, because the protocol fields will be offset by the message-size prefix 😩.
6. Message and Option Definitions 🎀
6.1. Message Framing for TCP 🦋
Using TCP for Bulk Leasequery lets multiple messages go from one end of the connection to the other without needing a request/response paradigm like UDP DHCPv4 [RFC2131] does 🌈. The receiver has to be able to figure out the size of each message it gets 🧠. So, two octets holding the message size in network byte order get prepended to each DHCPv4 message sent on a Bulk Leasequery TCP connection 💅. Those two message-size octets 'frame' each DHCPv4 message 🖼️.
The maximum message size is 65535 octets ✨.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| message-size | op (1) | htype (1) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| hlen (1) | hops (1) | .... |
+---------------+---------------+ +
| |
. remainder of DHCPv4 message,
. from Figure 1 of [RFC2131] .
. .
. (variable) .
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
message-size the number of octets in the message that
follows, as a 16-bit unsigned integer in
network byte order.
All other fields are as specified in DHCPv4 [RFC2131].
Figure 2: Format of a DHCPv4 Message in TCPThe whole point of this format is that code which already knows how to send or receive a message in [RFC2131] format will easily be able to handle the message inside the TCP framing 🫶.
6.2. New or Changed Options 🌸
The existing messages DHCPLEASEUNASSIGNED and DHCPLEASEACTIVE are used as the value of the dhcp-message-type option to indicate an IP address that is currently not leased or currently leased to a DHCPv4 client, respectively [RFC4388] 💜.
Extra options were also defined so Bulk Leasequery can pass along useful info to the requestor 🎁.
6.2.1. dhcp-message-type 🍓
The dhcp-message-type option (option 53) from Section 9.6 of [RFC2132] NEEDS new values 😤. The values for these message types are shown below, as an extension of the table from Section 9.6 of [RFC2132] 📋:
Value Message Type
----- ------------
14 DHCPBULKLEASEQUERY
15 DHCPLEASEQUERYDONE6.2.2. status-code ✨
The status-code option lets a machine-readable value come back about the status of a DHCPBULKLEASEQUERY request 🤖.
This option has two possible scopes with Bulk Leasequery, depending on where it shows up 👀. It refers to the info in a single Leasequery reply when the dhcp-message-type is DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED 🦄. It refers to the whole message stream for a request when the dhcp-message-type is DHCPLEASEQUERYDONE 🌊.
The code for this option is 151 🔢. The length of this option is a minimum of 1 octet 📏.
Status Status
Code Len Code Message
+------+------+------+------+------+-- --+-----+
| 151 | n+1 |status| s1 | s2 | ... | sn |
+------+------+------+------+------+-- --+-----+The status-code is indicated in one octet, as defined in the table below 🔢. The Status Message is an OPTIONAL UTF-8-encoded text string that's suitable for display to an end user 💬. This text string MUST NOT contain a termination character (e.g., a null) 🚫. The Len field describes the length of the Status Message without any terminator character 📐. Null characters MUST NOT appear in the Status Message string, and it's a protocol violation for them to appear in ANY position in the Status Message, including at the end 💀🚨.
Name Status Code Description
---- ----------- -----------
Success 000 Success. Also signaled by absence of
a status-code option.
UnspecFail 001 Failure, reason unspecified.
QueryTerminated 002 Indicates that the server is unable to
perform a query or has prematurely terminated
the query for some reason (which should be
communicated in the text message).
MalformedQuery 003 The query was not understood.
NotAllowed 004 The query or request was understood but was
not allowed in this context.A status-code option MAY appear in the options field of a DHCPv4 message 🤷♀️. If the status-code option doesn't appear, it's assumed the operation was successful 🥳. The status-code option SHOULD NOT appear in a message that's successful, UNLESS there's some text string that needs to be communicated to the requestor 🙃.
6.2.3. base-time 🕰️
The base-time option is the current time the message was created to be sent by the DHCPv4 server to the requestor of the Bulk Leasequery ⏰. This MUST be an absolute time ⚠️. All of the other time-based options in the reply message are relative to this time, including the dhcp-lease-time [RFC2132] and client-last-transaction-time [RFC4388] 🧵. This time is in the context of the DHCPv4 server that placed this option in a message 🖥️.
This is an unsigned integer in network byte order 🔢.
The code for this option is 152 🔢. The length of this option is 4 octets 📏.
DHCPv4 Server
Code Len base-time
+-----+-----+-----+-----+-----+-----+
| 152 | 4 | t1 | t2 | t3 | t4 |
+-----+-----+-----+-----+-----+-----+6.2.4. start-time-of-state 🌟
The start-time-of-state option lets the receiver figure out when the IP address made the transition into its current state 🔍.
This MUST NOT be an absolute time, which is the same as saying this MUST NOT be an absolute number of seconds since January 1, 1970 🙅♀️. Instead, this MUST be the unsigned integer number of seconds from the time the IP address transitioned its current state to the time specified in the base-time option in the same message 🧮.
This is an unsigned integer in network byte order 🔢.
The code for this option is 153 🔢. The length of this option is 4 octets 📏.
Seconds in the past
Code Len from base-time
+-----+-----+-----+-----+-----+-----+
| 153 | 4 | t1 | t2 | t3 | t4 |
+-----+-----+-----+-----+-----+-----+6.2.5. query-start-time 🎬
The query-start-time option gives the DHCPv4 server a start query time 🏁. If it's specified, only bindings that have changed ON or AFTER the query-start-time SHOULD be included in the response to the query 📆.
The requestor MUST determine the query-start-time using lease information it has received from the DHCPv4 server 📨. This MUST be an absolute time in the DHCPv4 server's context (see Section 7.4) 🕰️.
Typically (though this is NOT a requirement), the query-start-time option will contain the value most recently received in a base-time option by the requestor, since that indicates the last successful communication with the DHCP server 🤝.
This MUST be an absolute time ⏱️.
This is an unsigned integer in network byte order 🔢.
The code for this option is 154 🔢. The length of this option is 4 octets 📏.
DHCPv4 Server
Code Len query-start-time
+-----+-----+-----+-----+-----+-----+
| 154 | 4 | t1 | t2 | t3 | t4 |
+-----+-----+-----+-----+-----+-----+6.2.6. query-end-time 🏁
The query-end-time option gives the DHCPv4 server an end query time 🔚. If it's specified, only bindings that have changed ON or BEFORE the query-end-time SHOULD be included in the response to the query 📆.
The requestor MUST determine the query-end-time based on lease information it has received from the DHCPv4 server 📨. This MUST be an absolute time in the context of the DHCPv4 server 🕰️.
Without information to the contrary, the requestor SHOULD assume that the time context of the DHCPv4 server is identical to the time context of the requestor (see Section 7.4) 🤔.
This is an unsigned integer in network byte order 🔢.
The code for this option is 155 🔢. The length of this option is 4 octets 📏.
DHCPv4 Server
Code Len query-end-time
+-----+-----+-----+-----+-----+-----+
| 155 | 4 | t1 | t2 | t3 | t4 |
+-----+-----+-----+-----+-----+-----+6.2.7. dhcp-state ✨
okay so the dhcp-state option lets you see way more detail than the DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED message types can show 💅 it's giving precision
the code for this option is 156 and the length is 1 octet 🎀
0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 156 | Length | State |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+156is the option code.Lengthis the option length, 1 octet.Stateis the state of the IP address.
Value State
----- -----
1 AVAILABLE Address is available to local DHCPv4 server
2 ACTIVE Address is assigned to a DHCPv4 client
3 EXPIRED Lease has expired
4 RELEASED Lease has been released by DHCPv4 client
5 ABANDONED Server or client flagged address as unusable
6 RESET Lease was freed by some external agent
7 REMOTE Address is available to a remote DHCPv4 server
8 TRANSITIONING Address is moving between statesngl some of these states can be transient, so they might not show up in normal use 🙈 A DHCPv4 server MUST implement at least the AVAILABLE and ACTIVE states and SHOULD implement at least the ABANDONED and RESET states 🔥
the states AVAILABLE and REMOTE are relative to the current server 🌸 An address that is available to the current server should show AVAILABLE on that server, and if another server is involved with that address as well, it should show as REMOTE on that other server.
the dhcp-state option SHOULD contain ACTIVE when it appears in a DHCPLEASEACTIVE message. A DHCPv4 server MAY choose to not send a dhcp-state option in a DHCPLEASEACTIVE message, and a requestor SHOULD assume that the dhcp-state is ACTIVE if no dhcp-state option appears in a DHCPLEASEACTIVE message ✨
the local and remote stuff is all about setups with multiple servers working together for better availability 🦋 An IP address that is AVAILABLE on the local server is available to that server, while one that is REMOTE is available to a remote server. Usually, an IP address that is AVAILABLE on one server would be REMOTE on any remote server. TRANSITIONING is also super useful in multi-server deployments, where one server sometimes has to interlock a state change with one or more other servers. Should a Bulk Leasequery need to send information about the state of the IP address during this period, it SHOULD use the TRANSITIONING state, since the IP address is likely to be neither ACTIVE or AVAILABLE 💜
there is no requirement for an IP address's state to change in a well-defined way from one state to the next. you literally cannot draw a simple state transition graph for these, because it would be fully connected and tell you nothing useful. every state can (at times) follow every other state 💀 so the requestor of a Leasequery MUST NOT depend on one certain state always following a particular previous state 🙅♀️
6.2.8. data-source 🧚
the data-source option tells you where the data in a DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message came from 🌈 It SHOULD be used when there are two or more servers that might have info about a particular IP address binding. Often two servers team up for an increased availability solution, and in that case both of them will respond to Bulk Leasequery requests for the same IP address 👑 When one server is working with another and both might reply about the same IP address, each server SHOULD return the data-source option along with the other info it gives about that address.
this option lets an external process tell apart the info coming from each of the servers handling that IPv4 address 🫶
the code for this option is 157 and the length is 1 octet 🍓
0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| 157 | Length | Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+157is the option code.Lengthis the option length, 1 octet.Flagsis the source information for this message.
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
| UNA |R|
+-+-+-+-+-+-+-+-+
R: REMOTE flag
remote = 1
local = 0
UNA: UNASSIGNEDthe REMOTE flag shows where the most recent change of state (or other interesting change) for this IPv4 address happened 🎯 If it's local, the change happened on the server that sent this message. If it's remote, the change happened on some other server and then got passed along to the server that sent this message.
if this option was requested and it doesn't show up, the requestor MUST consider that the data-source was local 🌸
Unassigned bits MUST be ignored 🙈
6.2.9. Virtual Subnet Selection Type and Information 🌷
all of the (sub-)options defined in [RFC6607] have the same payload: a type plus extra VSS (Virtual Subnet Selection) info 🧁 The existing table gets extended (see below) with a brand-new type 254, which lets you say that all VPNs should be used to process the Bulk Leasequery 💖
Type VSS Information Format
----------------------------------------------------------
0 Network Virtual Terminal (NVT) ASCII VPN identifier
1 RFC 2685 VPN-ID
CHANGED -> 2-253 Unassigned
NEW -> 254 All VPNs (wildcard)
255 Global, default VPN6.3. Connection and Transmission Parameters ⭐
DHCPv4 servers that support Bulk Leasequery SHOULD listen for incoming TCP connections on the DHCPv4 server port 67. Implementations MAY offer to make the incoming port configurable, but port 67 MUST be the default. Requestors SHOULD make TCP connections to port 67 and MAY offer to make the destination server port configurable 🎀
this section has a table of values that control Bulk Leasequery behavior, with the recommended defaults 🧚 Implementations MAY make these values configurable. BUT, configuring timeouts that are too small can cause harmful behavior, both for this application and for other traffic on the network 😭 So timeout values smaller than the default values are NOT RECOMMENDED 🚫
Parameter Default Description
--------------------------------------------------------------------
BULK_LQ_DATA_TIMEOUT 300 secs Bulk Leasequery data timeout
for both client and server
(see Sections 7 and 8)
BULK_LQ_MAX_CONNS 10 Max Bulk Leasequery TCP connections
at the server side (see Section 8.1)7. Requestor Behavior 🦋
7.1. Connecting and General Processing 💅
a requestor tries to set up a TCP connection to a DHCPv4 server to start a Leasequery exchange 🫶 If the attempt fails, the requestor MAY retry.
if Bulk Leasequery gets cut off early, either by a DHCPLEASEQUERYDONE with a status-code option carrying the status code QueryTerminated, or because the connection it was sent over failed, the requestor MAY retry the request after making a new connection 🔁
messages from the DHCPv4 server come back as multiple responses to a single DHCPBULKLEASEQUERY message 🌈 So each DHCPBULKLEASEQUERY request MUST have an xid (transaction-id) that is unique on the connection it's sent on. All the messages that respond to that request will contain the same xid as the request. The xid is what lets the requestor tell apart the data-streams of two different DHCPBULKLEASEQUERY requests, iykyk 🧚✨
7.2. Forming a Bulk Leasequery 🎀
Okay so Bulk Leasequery is basically a connection that moves the state of some subset (or possibly ALL of them, no cap) of the IP address bindings from the DHCPv4 server over to the requestor 🦋. The server sends every requested IPv4 address binding down that connection with minimal delay once it gets the request ✨. When we say "all IP address binding information," we mean info about every IPv4 address configured on the server that matches the query criteria. For some criteria, that can even include addresses that may not have a connection to a specific DHCPv4 client right now, or ever had one 🙈.
To build the Bulk query, you make a DHCPv4 request with a dhcp-message-type of DHCPBULKLEASEQUERY 💅. The query SHOULD have a dhcp-parameter-request-list so the server knows which DHCPv4 options the requestor is into 👑. In that list, a DHCPBULKLEASEQUERY message SHOULD contain the codes for base-time, dhcp-lease-time, start-time-of-state, and client-last-transaction-time 🧚.
A DHCPBULKLEASEQUERY request is made of one primary query plus optionally one or more qualifiers for it 🍓.
The possible primary queries are listed below. Each DHCPBULKLEASEQUERY request MUST contain only one of these primary queries, so no double-dipping 💀.
- Query by MAC address 🔍
In a Query by MAC address, the chaddr, htype, and hlen of the DHCPv4 packet are filled in with the values requested.
- Query by Client-identifier 🪪
In a Query by Client-identifier, a Client-identifier option containing the requested value is included in the DHCPBULKLEASEQUERY request.
- Query by Remote ID 🛰️
In a Query by Remote ID, a Remote ID sub-option containing the requested value is included in the relay-agent-information option of the DHCPBULKLEASEQUERY request.
- Query by Relay-ID 🌸
In a Query by Relay-ID, a Relay-ID sub-option [RFC6925] containing the requested value is included in the relay-agent-information option of the DHCPBULKLEASEQUERY request.
- Query for All Configured IP Addresses 🌈
A Query for All Configured IP addresses is signaled by the absence of any other primary query. Main character energy, literally ✨.
There are three qualifiers that can go on top of any of the above primary queries. They can show up solo or together in any combo, but only one of each is allowed 💖.
- Query Start Time ⏰
Including a query-start-time option specifies that only IP address bindings that have changed on or after the time in the query-start-time option should be returned.
- Query End Time ⌛
Including a query-end-time option specifies that only IP address bindings that have changed on or before the time in the query-end-time option should be returned.
- VPN-ID 🦄
If no VPN-ID option shows up in the DHCPBULKLEASEQUERY, the default (global) VPN gets searched to satisfy the query. The VPN-ID option [RFC6607] lets the requestor name a single VPN other than the default one. This document also extended the VPN-ID option so you can say that all configured VPNs should be searched to satisfy the query 🫶.
In all cases, any message returned from a DHCPBULKLEASEQUERY request containing information about an IP address for other than the default (global) VPN MUST contain a VPN-ID option in the message. 🚨
Using query-start-time, query-end-time, or both can cut down the amount of data sent over the TCP connection by a lot 📉. Also, the times in those options are absolute times, not durations counted from "now," so don't mix those up 🙅♀️.
If the TCP connection gets blocked or stops being writable while the requestor is sending its query, the implementation's behavior is controlled by the current value of BULK_LQ_DATA_TIMEOUT ⏳. The default value is given elsewhere in this document, and the operator can override it with local configuration 🎛️.
When that situation is detected, the requestor SHOULD start a timer using the current value of BULK_LQ_DATA_TIMEOUT. If that timer expires, the requestor SHOULD terminate the connection 🔚. This timer is completely independent of any TCP timeout set by the TCP protocol connection, so they don't cancel each other out 🙌.
7.3. Processing Bulk Replies 💌
The requestor tries to read a DHCPv4 Leasequery reply message from the TCP connection 👀.
The TCP connection may stop delivering reply data (aka the connection stops being readable) 😬. If that happens, the implementation's behavior is controlled by the current value of BULK_LQ_DATA_TIMEOUT. Again, the default value is given elsewhere in this document, and the operator can override it with local configuration 🧸.
When that situation is detected, the requestor SHOULD start a timer using the current value of BULK_LQ_DATA_TIMEOUT. If that timer expires, the requestor SHOULD terminate the connection 🥀.
A single Bulk Leasequery can, and usually will, result in a LOT of replies 📚. The requestor MUST be prepared to receive more than one reply with an xid matching a single DHCPBULKLEASEQUERY message from a single DHCPv4 server 🫠. If the xid in the received message does not match an outstanding DHCPBULKLEASEQUERY message, the requestor MUST close the TCP connection 🚪.
If the requestor gets more data than it can process, it can just abort the connection and try again with a more specific request 🏃♀️. It can also read the TCP connection more slowly, matching the rate it reads packets to the rate it can actually digest the info in the Bulk Leasequery packets 🐢.
The DHCPv4 server MUST send a server-identifier option (option 54) in the first response to any DHCPBULKLEASEQUERY message 🔑. The DHCPv4 server SHOULD NOT send server-identifier options in subsequent responses to that DHCPBULKLEASEQUERY message. The requestor MUST cache the server-identifier option from the first response and apply it to any subsequent responses 🧠.
The response messages a DHCPBULKLEASEQUERY request can generate are:
- DHCPLEASEACTIVE ✅
A Bulk Leasequery will generate DHCPLEASEACTIVE messages containing binding data for bound IP addresses that match the query criteria. The IP address bound to a DHCPv4 client shows up in the ciaddr field of the DHCPLEASEACTIVE message. The message may contain a non-zero chaddr, htype, hlen, and possibly additional options 🎁.
- DHCPLEASEUNASSIGNED 🫥
Some queries also generate DHCPLEASEUNASSIGNED messages for IP addresses that match the query criteria. These messages mean the IP address is managed by the DHCPv4 server but isn't currently bound to any DHCPv4 client 💤. The IP address this message refers to shows up in the ciaddr field of the DHCPLEASEUNASSIGNED message. A DHCPLEASEUNASSGINED message MAY also contain info about the last DHCPv4 client that was bound to this IP address. In that case, the message may contain a non-zero chaddr, htype, hlen, and possibly additional options 🕰️.
- DHCPLEASEQUERYDONE 🏁
A DHCPLEASEQUERYDONE response means the server finished its response to the query, and no more messages will be sent in response to the DHCPBULKLEASEQUERY 🎉. Sometimes more details show up in the status-code option in the DHCPLEASEQUERYDONE message. If there's no status-code option in the DHCPLEASEQUERYDONE message, then the query completed successfully ✨.
Note that a query that returned no data (a DHCPBULKLEASEQUERY request followed by a DHCPLEASEQUERYDONE response) still counts as a successful query, since no errors happened during processing 🥳. Having nothing to return to a DHCPBULKLEASEQUERY request is not considered an error 🙆♀️.
The DHCPLEASEUNKNOWN message MUST NOT appear in a response to a Bulk Leasequery 🙅.
The requestor MUST NOT assume there's any inherent order in the IP address binding information sent in response to a DHCPBULKLEASEQUERY 🌀. The base-time will tend to increase monotonically (since it's the current time on the DHCPv4 server), but the actual time any IP address binding changed is unrelated to the base-time 🕊️.
The DHCPLEASEQUERYDONE message always ends a successful DHCPBULKLEASEQUERY request, plus any unsuccessful ones not ended by a dropped connection 🔚. After receiving a DHCPLEASEQUERYDONE from a server, the requestor MAY close the TCP connection to that server, as long as no other DHCPBULKLEASEQUERY is outstanding on that TCP connection 👋.
The DHCPv4 Leasequery protocol [RFC4388] uses the associated-ip option as an indicator that multiple bindings were present in response to a single DHCPv4 client-based query. For Bulk Leasequery, a separate message is returned for each binding, so the associated-ip option isn't used 🙃.
7.4. Processing Time Values in Leasequery Messages ⏱️
Bulk Leasequery requests may be made to a DHCPv4 server whose absolute time isn't synced with the requestor's local time 🕰️. So there are at least two time contexts even in the simplest Bulk Leasequery response, and when multiple DHCPv4 servers are queried, it gets even messier 🌪️.
If the requestor of a Bulk Leasequery is saving the returned data in some form, it has to store a variety of time values. Some are in the requestor's context, and some are in the DHCPv4 server's context 📝.
When the requestor receives a DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message from the DHCPv4 server, the message will contain a base-time option. The time in that option is in the context of the DHCPv4 server. That makes it a great time to save and reuse as input to a DHCPBULKLEASEQUERY in the query-start-time or query-end-time options, if the requestor ever needs to issue one later, since those options need a time in the DHCPv4 server's context 🧚♀️.
Besides saving the base-time for later query-start-time or query-end-time use, the base-time is also used to convert the other times in the Leasequery message into values that make sense for the requestor 🔄. Those other time values are given as an offset (duration) from the base-time value, not as an absolute time ⏳.
In systems whose clocks are synchronized (maybe using NTP), the clock skew will usually be zero 🫶.
7.5. Querying Multiple Servers 🌐
A Bulk Leasequery requestor MAY be configured to connect to and query multiple DHCPv4 servers in parallel 🧑🤝🧑. The DHCPv4 Leasequery specification [RFC4388] has a discussion about reconciling binding data received from multiple DHCPv4 servers 📖.
In addition, the algorithm in Section 7.6 should be used 💜.
7.6. Making Sense out of Multiple Responses concerning a Single IPv4 Address ✨
bestie, every Bulk Leasequery requestor MUST be ready for multiple responses about the same IPv4 address 🫠 coming from different DHCPv4 servers. so the algorithm below SHOULD be used to figure out if the new info is more up to date (aka better) than what you already have 💅. in this part, the info a DHCPv4 server sends about one IPv4 address is called a "record" 📝. the times used in the algorithm SHOULD have been converted into the requestor's context 🌍, and the time comparisons SHOULD be done in a way that matches what's in Section 7.4 ⏰.
- If both the existing and the new record have
client-last-transaction-timeinfo, the record with the laterclient-last-transaction-timeis considered better 🏆. - If only one record has
client-last-transaction-timeinfo, compare that record'sclient-last-transaction-timeagainst the other record'sstart-time-of-state. the one with the later time is considered better ⏳. - If neither record has
client-last-transaction-timeinfo, compare theirstart-time-of-stateinfo. the record with the laterstart-time-of-stateis considered better 🌷. - If none of the comparisons above give a clear winner about which record is later, then compare the value of the
REMOTEflag from thedata-sourceoption for each record 🧐. if theREMOTEflag values are different between the two records, the record whoseREMOTEflag value islocalis considered better 🏠.
ngl, the algorithm above doesn't always pick a winner 😭. if it's inconclusive about a record the requestor just got, the requestor SHOULD use additional info in the two records to decide which one is better 🕵️♀️✨.
7.7. Multiple Queries to a Single Server over One Connection 🔁
okay so Bulk Leasequery requestors might need to make a bunch of queries to recover binding info 📚. a requestor MAY use a single connection to send multiple queries to a server that's willing to support them 🔌. each query MUST have a unique xid 🆔, no duplicates allowed bestie 🙅♀️.
a server SHOULD let you configure how many queries it can process at the same time over one connection ⚙️. it SHOULD read as many queries as it's configured to process simultaneously, and only read any later queries as the current ones get processed 📖.
a server that's processing multiple queries at once MUST NOT block sending replies on new queries until all replies for the existing query are complete 🚫. requestors need to know that replies for multiple queries may be interleaved in the stream of reply messages 🧵💕. requestors that can't process interleaved replies (based on xid) MUST NOT send more than one query over a single connection before the previous query is complete 🙅.
requestors should be aware that servers are not required to process more than one query over a connection at a time (that's the limiting case for the configuration above) 😌, and that servers are likely to limit how fast they process queries from any one requestor 🐢.
7.7.1. Example 🎀
this example shows what a series of queries and responses might look like 👀. it's just an example, though, so there is no requirement that this sequence must be followed, or that requestors or servers must support parallel queries 💅.
in the example session, the client sends four queries after establishing a connection 🤝. query 1 returns no results 🫥; query 2 returns 3 messages, and the stream of replies wraps up before the client issues any new query 🎁. query 3 and query 4 overlap, and the server interleaves its replies to those two queries 🌀😭.
Requestor Server
--------- ------
DHCPBULKLEASEQUERY xid 1 ----->
<----- DHCPLEASEQUERYDONE xid 1
DHCPBULKLEASEQUERY xid 2 ----->
<----- DHCPLEASEACTIVE xid 2
<----- DHCPLEASEACTIVE xid 2
<----- DHCPLEASEACTIVE xid 2
<----- DHCPLEASEQUERYDONE xid 2
DHCPBULKLEASEQUERY xid 3 ----->
DHCPBULKLEASEQUERY xid 4 ----->
<----- DHCPLEASEACTIVE xid 4
<----- DHCPLEASEACTIVE xid 4
<----- DHCPLEASEACTIVE xid 3
<----- DHCPLEASEACTIVE xid 4
<----- DHCPLEASEUNASSIGNED xid 3
<----- DHCPLEASEACTIVE xid 4
<----- DHCPLEASEACTIVE xid 3
<----- DHCPLEASEQUERYDONE xid 3
<----- DHCPLEASEACTIVE xid 4
<----- DHCPLEASEQUERYDONE xid 47.8. Closing Connections 🚪
if a requestor has no more queries to send, or isn't sure whether it has more, then it SHOULD close the connection after getting the DHCPLEASEQUERYDONE message for the last outstanding query it sent 💌.
the requestor SHOULD close connections gracefully, not by aborting 🕊️. the requestor SHOULD NOT assume that the way the DHCP server closed a connection carries any special meaning 🤷♀️.
typically the requestor is the one that closes the connection 🙌, since servers will often keep a connection open in case the requestor has more queries 🥰.
⚠️ if a server closes a connection with an exception condition, the requestor SHOULD consider as valid any completely received intermediate results, and the requestor MAY retry the Bulk Leasequery operation 🔄💀.
8. Server Behavior 🖥️✨
8.1. Accepting Connections 🤍
servers that implement DHCPv4 Bulk Leasequery listen for incoming TCP connections 👂. port numbers are discussed in Section 6.3 🔢. servers MUST be able to limit the number of connections that are accepted and active at the same time 🛑. the value BULK_LQ_MAX_CONNS SHOULD be the default, but implementations MAY let it be configurable 🎛️. connections SHOULD be accepted, and if the number of connections is over BULK_LQ_MAX_CONNS, they SHOULD be closed immediately ⚡.
servers MAY restrict Bulk Leasequery connections and DHCPBULKLEASEQUERY messages to certain requestors 🔐. connections that aren't from permitted requestors SHOULD be closed immediately, to avoid exhausting the server's connection resources 🫧. servers MAY restrict some requestors to certain query types 🎟️. servers MAY reply to queries that aren't permitted with the DHCPLEASEQUERYDONE message, with a status-code option status of NotAllowed, or MAY simply close the connection 🙈.
if the TCP connection gets blocked while the server is accepting a connection or reading a query, it SHOULD be ready to terminate the connection after BULK_LQ_DATA_TIMEOUT ⏱️. we're making this recommendation so servers can control how long they're willing to wait before giving up on an inactive connection, no matter which TCP implementation they're using 💖🫶.
8.2. Replying to a Bulk Leasequery
okay bestie, if the connection gets blocked while the server is trying to send replies, the server SHOULD be prepared to terminate the TCP connection after a BULK_LQ_DATA_TIMEOUT 🙈⏰
Every Bulk Leasequery request MUST be wrapped up by sending a final DHCPLEASEQUERYDONE message, if such a message can be sent 💌 The DHCPLEASEQUERYDONE message MUST have a status-code option status if the termination was anything other than successful, and SHOULD NOT contain a status-code option status if the termination was successful ✨
If the DHCPv4 server runs into an error while processing a DHCPBULKLEASEQUERY message, whether during the initial processing or later on during the message processing, it SHOULD send a DHCPLEASEQUERYDONE containing a status-code option 🚨 It MAY close the connection after this error is signaled, but that is not required 🫶
If the server doesn't find any bindings that satisfy a query, it MUST send a DHCPLEASEQUERYDONE 🌸 It SHOULD NOT include a status-code option with a Success status unless there is a useful string to include in the status-code option. Otherwise, the server sends each binding's data in a DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message 💖
A response to a DHCPBULKLEASEQUERY may involve checking multiple DHCPv4 IP address bindings that the DHCPv4 server maintains 👀 The Bulk Leasequery protocol does not require any ordering of the IP addresses returned in DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED messages, so no stress about the order 🦋
When responding to a DHCPBULKLEASEQUERY message, the DHCPv4 server MUST NOT send more than one message for each applicable IP address, even if the state of some of those IP addresses changes while the message is being processed 🙅♀️ Updates to that IP address state are already handled by normal protocol processing, so no special effort is needed here 💅
If the ciaddr, yiaddr, or siaddr is non-zero in a DHCPBULKLEASEQUERY request, the request must be terminated immediately by a DHCPLEASEQUERYDONE message with a status-code option status of MalformedQuery 😭
Any DHCPBULKLEASEQUERY that has more than one of the following primary query types specified MUST be terminated immediately by a DHCPLEASEQUERYDONE message with a status-code option status code of NotAllowed 🚫
Here's how the allowable queries in a DHCPBULKLEASEQUERY message get processed 🧚 Heads up that the primary query descriptions below must be constrained by the actions of any of the three qualifiers described afterwards too 👑 The table below talks through how to process the various queries, and for info on how to identify the query, check out Section 7.2.
- Query by MAC address
Every IP address that has a current binding to a DHCPv4 client matching the chaddr, htype, and hlen in the DHCPBULKLEASEQUERY request MUST be returned in a DHCPLEASEACTIVE message 💜
- Query by Client-identifier
Every IP address that has a current binding to a DHCPv4 client matching the Client-identifier option in the DHCPBULKLEASEQUERY request MUST be returned in a DHCPLEASEACTIVE message 💜
- Query by Remote ID
Every IP address that has a current binding to a DHCPv4 client matching the Remote ID sub-option of the relay-agent-information option in the DHCPBULKLEASEQUERY request MUST be returned in a DHCPLEASEACTIVE message 💜
- Query by Relay-ID
Every IP address that has a current binding to a DHCPv4 client matching the Relay-ID sub-option of the relay-agent-information option in the DHCPBULKLEASEQUERY request MUST be returned in a DHCPLEASEACTIVE message 💜
- Query for All Configured IP Addresses
A Query for All Configured IP addresses is signaled by the absence of any other primary query 🌈 In other words, if there's no value in the chaddr, hlen, or htype, no Client-identifier option, and no Remote ID sub-option or Relay-ID sub-option of the relay-agent-information option, then the request is a query for information about all configured IP addresses. In this case, every configured IP address that has a current binding to a DHCPv4 client MUST be returned in a DHCPLEASEACTIVE message. On top of that, every configured IP address that does not have a current binding to a DHCPv4 client MUST be returned in a DHCPLEASEUNASSIGNED message 🍓
In this form of query, each configured IP address MUST be returned at most one time. Without any qualifiers restricting the number of IP addresses returned, every configured IP address MUST be returned exactly once 🔁
There are three qualifiers that can be applied to any of the above primary queries 🎀 They can show up individually or together in any combination, but only one of each can appear.
- Query Start Time
If a query-start-time option appears in the DHCPBULKLEASEQUERY request, only IP address bindings that have changed on or after the time specified in the query-start-time option should be returned ⏳
- Query End Time
If a query-end-time option appears in the DHCPBULKLEASEQUERY request, only IP address bindings that have changed on or before the time specified in the query-end-time option should be returned ⌛
- VPN-ID
If no VPN-ID option appears in the DHCPBULKLEASEQUERY, the default (global) VPN is used to satisfy the query 🌍 A VPN-ID option [RFC6607] value other than the wildcard value (254) lets the requestor specify a single VPN other than the default VPN. On top of that, the VPN-ID option has been extended as part of this document to allow specification of a type 254, which indicates that all configured VPNs should be searched in order to satisfy the primary query 🕵️♀️
In all cases, if the information returned in a DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message is for a VPN other than the default (global) VPN, a VPN-ID option MUST appear in the packet 📦
The query-start-time and query-end-time qualifiers are used to limit the amount of data a Bulk Leasequery request returns, by only returning IP addresses whose address bindings have changed in some way during the time window set by the query-start-time and query-end-time 🪟
A DHCPv4 server SHOULD consider an address binding to have changed during a specified time window if either the client-last-transaction-time or the start-time-of-state of the address binding changed during that window 🧠
The DHCPv4 server MAY return address binding data in any order, as long as the binding information for any given IP address isn't repeated 🔀 Once all binding data for a given DHCPBULKLEASEQUERY has been sent, the DHCPv4 server MUST send a DHCPBULKLEASEQUERYDONE message 🎉
8.3. Building a Single Reply for Bulk Leasequery
The DHCPv4 Leasequery specification [RFC4388] describes how to initially build DHCPLEASEQUERY reply messages using the DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED message types, in Section 6.4.2 📝 All of the reply messages in Bulk Leasequery are pretty similar to the reply messages for an IP address query 💕 Message transmission and framing for TCP are described in this document in Section 6.1 🧵
[RFC2131] and [RFC4388] specify that every response message MUST contain the server-identifier option. However, that option will be the same for every response from a particular DHCPBULKLEASEQUERY request 🤔 So the DHCPv4 server MUST include the server-identifier option in the first message sent in response to a DHCPBULKLEASEQUERY. It SHOULD NOT include the server-identifier option in later messages 🙌
The message type of DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED is based on the value of the dhcp-state option. If the dhcp-state option value is ACTIVE, then the message type is DHCPLEASEACTIVE; otherwise, the message type is DHCPLEASEUNASSIGNED 🎯
In addition to the basic message construction described in [RFC4388], the following guidelines apply 📋
- If the dhcp-state option code appears in the dhcp-parameter-request-list, the DHCPv4 server SHOULD include a dhcp-state option whose value corresponds most closely to the state the DHCPv4 server holds for the IP address associated with this reply. If the state is
ACTIVEand the message being returned isDHCPLEASEACTIVE, then the DHCPv4 server MAY choose not to send the dhcp-state option. The requestor SHOULD assume that anyDHCPLEASEACTIVEmessage arriving without a requested dhcp-state option has a dhcp-state ofACTIVE🫧 - If the base-time option code appears in the dhcp-parameter-request-list, the DHCPv4 server MUST include a base-time option. This is the current time in the DHCPv4 server's context, and it's the time that the start-time-of-state, dhcp-lease-time, client-last-transaction-time, and other duration-style times are based upon ⏱️
- If the start-time-of-state option code appears in the dhcp-parameter-request-list, the DHCPv4 server MUST include a start-time-of-state option whose value represents the time at which the dhcp-state option's state became valid 🕰️
- If the dhcp-lease-time option code appears in the dhcp-parameter-request-list, the DHCPv4 server MUST include a dhcp-lease-time option for any state that has a timeout value associated with it ⏲️
- If the data-source option code appears in the dhcp-parameter-request-list, the DHCPv4 server MUST include the data-source option in any situation where any of the bits would be non-zero. So, in the absence of the data-source option, the assumption is that all of the flags are zero 🚩
- If the client-last-transaction-time option code appears in the dhcp-parameter-request-list, the DHCPv4 server MUST include the client-last-transaction-time option in any situation where the information is available 🗓️
- If there is a dhcp-parameter-request-list in the initial
DHCPBULKLEASEQUERYrequest, then it should be used for all of the replies generated by that request. Some options can be sent from a DHCPv4 client to the server, or from the DHCPv4 server to a DHCPv4 client. Option 125 is one such option. If the option code for one of these options appears in the dhcp-parameter-request-list, it SHOULD result in returning the value of the option sent by the DHCPv4 client to the server, if one exists 🎁
Note that there may be other requirements for a reply to a DHCPBULKLEASEQUERY request, as discussed in Section 8.2 👀
8.4. Multiple or Parallel Queries
As discussed in Section 7.3, requestors may want to use a connection that's already been established when they need to make additional queries 🔗 Servers SHOULD support reading and processing multiple queries from a single connection, and SHOULD allow configuration of the number of simultaneous queries the server may process 🛠️ A server MUST NOT read more query messages from a connection than it is prepared to process simultaneously 🛑
This SHOULD be a feature that is administratively controlled 🧑💼 Servers SHOULD offer configuration that limits the number of simultaneous queries permitted from any one requestor, so resource use stays under control when there are multiple requestors asking for service 🌟
8.5. Closing Connections 🔌✨
okay bestie, so the DHCPv4 server SHOULD close connections in a graceful manner and NOT just abort the connection 💅 The server SHOULD NOT assume that the way the requestor closed a connection carries any special meaning 🙈
Usually the DHCPv4 server only closes a connection after some kind of exception or a timeout on that connection ⏰
Using a timer to spot when a connection is idle and then closing it is designed to keep the DHCPv4 server from burning through resources it doesn't need 🫶
The DHCPv4 server should start a timer for BULK_LQ_DATA_TIMEOUT seconds for a particular connection after it sends a DHCPLEASEQUERYDONE message over that connection, if there is no current query outstanding for that connection 🌸 It should restart this timer if a query arrives over that connection. If the timer expires, the DHCPv4 server should close the connection 💜
The server MUST close its end of the TCP connection if it encounters an error sending data on the connection 😭 The server MUST close its end of the TCP connection if it finds that it has to abort an in-process request 💀 A server aborting an in-process request SHOULD attempt to signal that to its requestors by using the QueryTerminated status code in the status-code option in a DHCPLEASEQUERYDONE message, including a message string that explains the reason for the abort 🔥 If the connection is closed for any reason, all of the data flows associated with any currently outstanding DHCPBULKLEASEQUERY messages will be terminated 🥀
If the server detects that the requesting end of the connection has been closed, the server MUST close its end of the connection 🦋
9. Security Considerations 🔐
Okay, this part is seriously important, so pay attention 👑 The Security Considerations section of [RFC2131] details the general threats to DHCPv4. The DHCPv4 Leasequery specification [RFC4388] describes recommendations for the Leasequery protocol, especially when it comes to authentication of LEASEQUERY messages, mitigation of packet-flooding DoS attacks, and restriction to trusted requestors.
Using TCP brings some extra concerns 😬 Attacks that try to exhaust the DHCPv4 server's available TCP connection resources, such as SYN flooding attacks, can stop legitimate requestors from receiving service 🚨 Malicious requestors who manage to establish connections and then send invalid queries, partial queries, or no queries at all can also drain a server's pool of available connections 🫠 We recommend that servers offer configuration to limit the sources of incoming connections, that they limit the number of accepted connections and the number of in-process queries from any one connection, and that they limit the period of time during which an idle connection will be left open 🛡️
There are two specific Bulk Leasequery security issues that deserve explicit mention, so let's go 🎀 The first is preventing the information that Bulk Leasequery can provide from reaching clients who are not authorized to receive it 🙅♀️ The second is making sure that authorized clients of the Bulk Leasequery capability receive accurate information from the server, and that this information is not disrupted in transit 🧚
To prevent information leakage to unauthorized clients, servers SHOULD restrict Bulk Leasequery connections and DHCPBULKLEASEQUERY messages to certain requestors. They can do this either through explicit configuration of the server itself or by using external network elements to provide such restrictions 💅 In particular, the typical DHCPv4 client SHOULD NOT be allowed to receive a response to a Bulk Leasequery request, and some technique MUST exist to prevent that access in any environment where Bulk Leasequery is deployed 🙈
Connections that aren't from permitted requestors SHOULD be closed immediately to avoid server connection resource exhaustion. Or, alternatively, they simply aren't allowed to reach the server at all 🚫 Servers SHOULD have the capability to restrict certain requestors to certain query types. Servers MAY reply to queries that are not permitted with the DHCPLEASEQUERYDONE message and a status-code option status of NotAllowed, or they MAY simply close the connection 🌈
To prevent disruption and malicious corruption of Bulk Leasequery data flows between the server and authorized clients, these data flows SHOULD transit only secured networks 🔒 These data flows are typically infrastructure oriented, and there's usually no reason for them to flow over networks where these attacks are likely 🫶 In the rare cases where these data flows might need to go through unsecured networks, they MUST be sent over connections secured by means external to the DHCPv4/DHCPv6 server and its client(s), for example through VPNs ✨
Authentication for DHCP messages [RFC3118] MUST NOT be used to try to secure transmission of the messages described in this document. This is a big one, so remember it 🙅♀️ In particular, the message framing would not be protected by using the mechanisms described in [RFC3118], which was designed only with UDP transport in mind 💔
10. IANA Considerations 📋
IANA has assigned the following new DHCPv4 option codes from the registry "BOOTP Vendor Extensions and DHCP Options" maintained at http://www.iana.org/assignments/bootp-dhcp-parameters.
- An option code of 151 for
status-code. - An option code of 152 for
base-time. - An option code of 153 for
start-time-of-state. - An option code of 154 for
query-start-time. - An option code of 155 for
query-end-time. - An option code of 156 for
dhcp-state. - An option code of 157 for
data-source.
IANA has assigned the following new DHCP message types from the registry "DHCP Message Type 53 Values" maintained at http://www.iana.org/assignments/bootp-dhcp-parameters.
- A dhcp-message-type of 14 for
DHCPBULKLEASEQUERY. - A dhcp-message-type of 15 for
DHCPLEASEQUERYDONE.
IANA has created a new registry on the same assignments page, titled "DHCP State 156 Values" (where 156 corresponds to the assigned value of the dhcp-state option above). This registry has the following initial values:
State
-----
1 AVAILABLE
2 ACTIVE
3 EXPIRED
4 RELEASED
5 ABANDONED
6 RESET
7 REMOTE
8 TRANSITIONINGNew values for this namespace may only be defined by IETF Review, as described in [RFC5226].
IANA has created a new registry on the same assignments page, titled "DHCP Status Code 151 Values" (where 151 corresponds to the assigned value of the status-code option above). This registry has the following initial values:
Name status-code
---- -----------
Success 000
UnspecFail 001
QueryTerminated 002
MalformedQuery 003
NotAllowed 004New values for this namespace may only be defined by IETF Review, as described in [RFC5226].
IANA has revised the registry "VSS Type Options" created by [RFC6607] in the overall area "Dynamic Host Configuration Protocol (DHCP) and Bootstrap Protocol (BOOTP) Parameters". It has been revised to appear as follows. Note that the number range for "Unassigned" has changed, and a new line for "All VPNs (wildcard)" was added 🍓
Type VSS Information Format
------------------------------------------------------------
0 Network Virtual Terminal (NVT) ASCII VPN identifier
1 RFC 2685 VPN-ID
2-253 Unassigned
254 All VPNs (wildcard)
255 Global, default VPN11. Acknowledgements 🌷
Big thank-you moment 🫶 Significant text as well as important ideas were borrowed in whole or in part from "DHCPv6 Bulk Leasequery" [RFC5460], written by Mark Stapp. Further suggestions and improvements came from participants in the DHC Working Group, including Alfred Hoenes 👑
12. References 📚
12.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2131] Droms, R., "Dynamic Host Configuration Protocol", RFC
2131, March 1997.
[RFC2132] Alexander, S. and R. Droms, "DHCP Options and BOOTP Vendor
Extensions", RFC 2132, March 1997.
[RFC3046] Patrick, M., "DHCP Relay Agent Information Option", RFC
3046, January 2001.
[RFC3118] Droms, R., Ed., and W. Arbaugh, Ed., "Authentication for
DHCP Messages", RFC 3118, June 2001.
[RFC4388] Woundy, R. and K. Kinnear, "Dynamic Host Configuration
Protocol (DHCP) Leasequery", RFC 4388, February 2006.
[RFC5226] Narten, T. and H. Alvestrand, "Guidelines for Writing an
IANA Considerations Section in RFCs", BCP 26, RFC 5226,
May 2008.
[RFC5735] Cotton, M. and L. Vegoda, "Special Use IPv4 Addresses",
BCP 153, RFC 5735, January 2010.
[RFC6607] Kinnear, K., Johnson, R., and M. Stapp, "Virtual Subnet
Selection Options for DHCPv4 and DHCPv6", RFC 6607, April
2012.
[RFC6925] Joshi, B., Desetti, R., and M. Stapp, "The DHCPv4 Relay
Agent Identifier Sub-Option", RFC 6925, April 2013.12.2. Informative References
[RFC951] Croft, W. and J. Gilmore, "Bootstrap Protocol", RFC 951,
September 1985.
[RFC1542] Wimer, W., "Clarifications and Extensions for the
Bootstrap Protocol", RFC 1542, October 1993.
[RFC4614] Duke, M., Braden, R., Eddy, W., and E. Blanton, "A Roadmap
for Transmission Control Protocol (TCP) Specification
Documents", RFC 4614, September 2006.
[RFC5460] Stapp, M., "DHCPv6 Bulk Leasequery", RFC 5460, February
2009.Authors' Addresses 🦋
Kim Kinnear
Cisco Systems, Inc.
1414 Massachusetts Ave.
Boxborough, Massachusetts 01719
USA
Phone: (978) 936-0000
EMail: kkinnear@cisco.com
Mark Stapp
Cisco Systems, Inc.
1414 Massachusetts Ave.
Boxborough, Massachusetts 01719
USA
Phone: (978) 936-0000
EMail: mjs@cisco.com
D.T.V Ramakrishna Rao
Infosys Ltd.
44 Electronics City, Hosur Road
Bangalore 560 100
India
EMail: ramakrishnadtv@infosys.com
URI: http://www.infosys.com/
Bharat Joshi
Infosys Ltd.
44 Electronics City, Hosur Road
Bangalore 560 100
India
EMail: bharat_joshi@infosys.com
URI: http://www.infosys.com/
Neil Russell
Sea Street Technologies Inc.
EMail: neil.e.russell@gmail.com
Pavan Kurapati
Juniper Networks
1194 N. Mathilda Ave.
Sunnyvale, CA 94089
USA
EMail: kurapati@juniper.net
URI: http://www.juniper.net/
Bernie Volz
Cisco Systems, Inc.
1414 Massachusetts Ave.
Boxborough, Massachusetts 01719
USA
Phone: (978) 936-0000
EMail: volz@cisco.com📦 where this page comes from
- ietf: rfc6926 2013-04
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms