DHCPv4 Bulk Leasequery
updated by
- rfc-7724 — Active DHCPv4 Lease Query
Extracted elements (29)
Query start and end time qualifiers allow a relay agent that periodically saves state to stable storage to recover only the changes since its last commit, minimizing data transferred over the TCP connection.
TCP is used instead of UDP for Bulk Leasequery because a single request may return thousands of DHCPv4 bindings, making UDP's per-message overhead impractical. The existing UDP Leasequery is data-driven and cannot efficiently support proactive bulk recovery before traffic begins.
The base-time option is introduced because Bulk Leasequery requestors and servers may not be time-synchronized; all other time values are expressed as offsets from base-time so the requestor can convert server-context times to local context without requiring NTP alignment.
The 2-octet message-size TCP framing is not compatible with the UDP message format; a TCP-framed request sent as a UDP datagram will have all DHCPv4 protocol fields offset by two bytes and will likely be invalid.
A server processing parallel queries MUST NOT block sending replies for a new query until all replies for an existing query are complete; requestors that cannot handle interleaved replies (demultiplexed by xid) MUST NOT send more than one query at a time.
DHCPLEASEUNKNOWN MUST NOT appear in a response to a Bulk Leasequery; the requestor MUST NOT assume any inherent ordering of IP address binding information returned in bulk replies.
DHCPv4 servers MUST listen for TCP connections on port 67 by default (SHOULD listen, configurable MAY be offered). The BULK_LQ_DATA_TIMEOUT default is 300 seconds for both client and server; timeout values smaller than defaults are NOT RECOMMENDED.
Each DHCPBULKLEASEQUERY message MUST carry an xid (transaction-id) unique on the connection; if a received message's xid does not match any outstanding query, the requestor MUST close the TCP connection.
Each DHCPBULKLEASEQUERY request MUST contain exactly one primary query type; having more than one MUST cause the server to terminate the request immediately with DHCPLEASEQUERYDONE and a status-code of NotAllowed.
If ciaddr, yiaddr, or siaddr is non-zero in a DHCPBULKLEASEQUERY request, the server MUST terminate the request immediately with DHCPLEASEQUERYDONE carrying a MalformedQuery status code.
Servers MUST be able to limit concurrent accepted connections; BULK_LQ_MAX_CONNS (default 10) SHOULD be the enforced limit. Connections exceeding this limit SHOULD be closed immediately.
The associated-ip option MUST NOT appear in Bulk Leasequery replies; multiple bindings are returned as separate DHCPLEASEACTIVE messages rather than aggregated as in UDP Leasequery.
The server MUST include the server-identifier option (option 54) in the first response to any DHCPBULKLEASEQUERY; it SHOULD NOT include it in subsequent responses, and the requestor MUST cache and apply it to all subsequent messages in the stream.
Five primary query types are supported: Query by MAC address (chaddr/htype/hlen), Query by Client-identifier option, Query by Remote ID sub-option, Query by Relay-ID sub-option (RFC 6925), and Query for All Configured IP Addresses (signaled by absence of any other primary query).
The VSS Type Options registry (RFC 6607) is extended with type 254 as an 'All VPNs (wildcard)' value, allowing a DHCPBULKLEASEQUERY to search all configured VPNs. Absent a VPN-ID option, only the default (global) VPN is queried.
Two new dhcp-message-type (option 53) values are defined: DHCPBULKLEASEQUERY (14) for initiating a bulk query over TCP, and DHCPLEASEQUERYDONE (15) to signal that the server has finished responding to a query.
IANA assigned DHCP message type 14 (DHCPBULKLEASEQUERY) and type 15 (DHCPLEASEQUERYDONE) in the DHCP Message Type 53 Values registry.
IANA assigned DHCPv4 option codes 151 (status-code), 152 (base-time), 153 (start-time-of-state), 154 (query-start-time), 155 (query-end-time), 156 (dhcp-state), and 157 (data-source) in the BOOTP Vendor Extensions and DHCP Options registry.
IANA created the 'DHCP State 156 Values' registry with initial values 1–8 (AVAILABLE through TRANSITIONING) and the 'DHCP Status Code 151 Values' registry with codes 0–4 (Success through NotAllowed); both require IETF Review for new values.
Bulk Leasequery data flows SHOULD transit only secured networks; where unsecured paths are unavoidable, the flows MUST be protected by external mechanisms such as VPNs. RFC 3118 DHCP authentication MUST NOT be used, as it was designed for UDP only and does not cover TCP framing.
Bulk Leasequery exposes all binding data; servers SHOULD restrict access to authorized requestors and a technique MUST exist in any deployment to prevent ordinary DHCPv4 clients from receiving Bulk Leasequery responses. Unauthorized connections SHOULD be closed immediately.
TCP introduces SYN-flooding and connection-exhaustion risks; servers SHOULD restrict incoming connections by source, limit accepted connections and per-connection in-process queries, and impose idle-connection timeouts to defend against malicious or misbehaving requestors.
Each DHCPv4 message sent over a Bulk Leasequery TCP connection is prefixed with a 2-octet message-size field in network byte order, yielding a maximum message size of 65535 octets. All other fields follow the standard RFC 2131 DHCPv4 layout.
The base-time option (code 152) is a 4-octet unsigned integer in network byte order representing the absolute time (seconds since 1970-01-01) at which the server created the reply message; all other time-based options in the same message are relative to this value.
The data-source option (code 157) is a 1-octet flags field; the low-order R bit indicates whether the most recent state change for an IP address occurred on the local server (0) or a remote server (1). Unassigned bits MUST be ignored.
The dhcp-state option (code 156) is a 1-octet field encoding eight possible address states: AVAILABLE (1), ACTIVE (2), EXPIRED (3), RELEASED (4), ABANDONED (5), RESET (6), REMOTE (7), TRANSITIONING (8). A server MUST implement at least AVAILABLE and ACTIVE.
The query-start-time option (code 154) and query-end-time option (code 155) are each 4-octet unsigned integers representing absolute times in the DHCPv4 server's context; only bindings changed within the specified window are returned.
The start-time-of-state option (code 153) is a 4-octet unsigned integer expressing how many seconds before the base-time the IP address transitioned into its current state; it MUST NOT be an absolute time.
The status-code option (code 151) carries a 1-octet machine-readable status code followed by an optional UTF-8 text message; null characters MUST NOT appear anywhere in the text string, including at the end.