RFC 5460

DHCPv6 Bulk Leasequery

📅 published February 2009, from ietf

DHCPv6 Bulk Leasequery 🎀

  • RFC: 5460 ✨
  • Title: DHCPv6 Bulk Leasequery 💖
  • Stream: Network Working Group 🌸
  • Author: M. Stapp, Cisco Systems, Inc. 💅
  • Category: Standards Track 🦋
  • Date: February 2009 🌈
  • Obsoletes / Updates: Nothing is listed in the title block 🙈

Status of This Memo 📜

Okay so this doc is an Internet standards track protocol for the whole Internet community, and it's literally asking for discussion and suggestions for improvements 🫶 If you want to know where this protocol stands in standardization, check the current edition of the "Internet Official Protocol Standards" (STD 1) 💜 And distribution of this memo is unlimited, so share away 🦋

Copyright (c) 2009 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, as they stand on the date this document was published (http://trustee.ietf.org/license-info). Please read these carefully, bestie 🙏 They spell out your rights and restrictions for this doc 📜

Abstract ✨

So DHCPv6 got a Leasequery feature that lets a client ask about DHCPv6 bindings, but it only works one binding at a time 😭 That gets clunky, and sometimes it's inefficient or even impossible. This document levels up Leasequery by adding new query types and letting you bulk transfer DHCPv6 binding data over TCP 🚀💖

Table of Contents 🗂️

1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  3
3.  Protocol Overview  . . . . . . . . . . . . . . . . . . . . . .  4
4.  Interaction between UDP Leasequery and Bulk Leasequery . . . .  5
5.  Message and Option Definitions . . . . . . . . . . . . . . . .  6
  5.1.  Message Framing for TCP  . . . . . . . . . . . . . . . . .  6
  5.2.  Messages . . . . . . . . . . . . . . . . . . . . . . . . .  6
    5.2.1.  LEASEQUERY-DATA  . . . . . . . . . . . . . . . . . . .  7
    5.2.2.  LEASEQUERY-DONE  . . . . . . . . . . . . . . . . . . .  7
  5.3.  Query Types  . . . . . . . . . . . . . . . . . . . . . . .  7
    5.3.1.  QUERY_BY_RELAY_ID  . . . . . . . . . . . . . . . . . .  7
    5.3.2.  QUERY_BY_LINK_ADDRESS  . . . . . . . . . . . . . . . .  8
    5.3.3.  QUERY_BY_REMOTE_ID . . . . . . . . . . . . . . . . . .  8
  5.4.  Options  . . . . . . . . . . . . . . . . . . . . . . . . .  8
    5.4.1.  Relay-ID Option  . . . . . . . . . . . . . . . . . . .  8
  5.5.  Status Codes . . . . . . . . . . . . . . . . . . . . . . .  9
  5.6.  Connection and Transmission Parameters . . . . . . . . . .  9
6.  Requestor Behavior . . . . . . . . . . . . . . . . . . . . . . 10
  6.1.  Connecting . . . . . . . . . . . . . . . . . . . . . . . . 10
  6.2.  Forming Queries  . . . . . . . . . . . . . . . . . . . . . 10
  6.3.  Processing Replies . . . . . . . . . . . . . . . . . . . . 10
    6.3.1.  Reply Completion . . . . . . . . . . . . . . . . . . . 11
  6.4.  Querying Multiple Servers  . . . . . . . . . . . . . . . . 11
  6.5.  Multiple Queries to a Single Server  . . . . . . . . . . . 12
    6.5.1.  Example  . . . . . . . . . . . . . . . . . . . . . . . 12
  6.6.  Closing Connections  . . . . . . . . . . . . . . . . . . . 13
7.  Server Behavior  . . . . . . . . . . . . . . . . . . . . . . . 13
  7.1.  Accepting Connections  . . . . . . . . . . . . . . . . . . 13
  7.2.  Forming Replies  . . . . . . . . . . . . . . . . . . . . . 14
  7.3.  Multiple or Parallel Queries . . . . . . . . . . . . . . . 15
  7.4.  Closing Connections  . . . . . . . . . . . . . . . . . . . 15
8.  Security Considerations  . . . . . . . . . . . . . . . . . . . 16
9.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 16
10. Acknowledgments  . . . . . . . . . . . . . . . . . . . . . . . 17
11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17
  11.1. Normative References . . . . . . . . . . . . . . . . . . . 17
  11.2. Informative References . . . . . . . . . . . . . . . . . . 17

1. Introduction 💅

The DHCPv6 [RFC3315] protocol is the mechanism for handing out IPv6 address and configuration info to IPv6 nodes 🌐 Then there's IPv6 Prefix Delegation (PD) for DHCPv6 [RFC3633], which covers handing out whole IPv6 prefixes and related data to downstream devices 🎀 DHCPv6 servers are the source of truth here, keeping the authoritative binding info for those delegated prefixes 👑

Now the PD client is usually a router, and it takes the delegated prefix and advertises it to hosts on its local network 🏠 That prefix has to be routeable to be useful, but the actual DHCPv6 PD client might not be allowed to inject routes into the delegating network 😬 In service-provider (SP) networks, for example, an edge router normally works as a DHCPv6 relay agent, and that edge router is often the one responsible for keeping routes inside the SP network for clients' PD bindings 🛰️

Here's the tricky part. If a relay with that job gets replaced or rebooted, it needs a way to pull binding info back from the authoritative DHCPv6 server(s) so it can restore routeability to delegated prefixes 🔄 The relay might be a network device with no real local storage for its binding-to-route data 📦 The DHCPv6 Leasequery protocol [RFC5007] already exists for this, and it lets you query individual bindings from the authoritative server(s) 🔍 The catch is that individual queries only work when the requestor already knows the target binding, like after traffic shows up 🚦 With DHCPv6 Prefix Delegation, though, the PD binding data might need to be known before any traffic arrives from the client router 😭 In those cases, the relay may not be able to form individual queries at all 💔

This document extends the DHCPv6 Leasequery protocol so it can handle these needs 💖 At the SP edge there could be many thousands of delegated prefixes per relay, so the spec calls for TCP [RFC4614] to move data efficiently ✨ It also adds a new DHCPv6 option, the Relay Identifier option, to make it efficient to recover all the data tied to one specific relay agent, along with a query type for that purpose 🧚 And it adds query types by network segment and by Remote-ID option value, which helps a relay that only needs to recover some of its clients' bindings 🎯

2. Terminology 📚

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 💜

DHCPv6 terminology is defined in [RFC3315]. DHCPv6 Leasequery terminology is defined in [RFC5007]. 📖

3. Protocol Overview 🦋

Bulk Leasequery is modeled on the existing individual Leasequery protocol in [RFC5007], and most of the differences come from using TCP 🧠 A Bulk Leasequery client opens a TCP connection to a DHCPv6 server on DHCPv6 port 547 🔌 That means the Leasequery client needs the server's IP address(es) from configuration or some other method, and it needs unicast IP reachability to the server 📡 No relaying for bulk leasequery is specified, so no detours 🙅‍♀️

Once the connection is up, the client sends a LEASEQUERY message with a query-type and data about the bindings it's after 🎯 The server uses that query-type and data to find any relevant bindings 🔎 Some query types might require servers to keep extra data structures or be able to find bindings based on specific option data, so servers may have to do that work 🛠️ The server replies with a LEASEQUERY-REPLY message that says whether the query worked or failed 🚦 If it worked, the server puts the first client's binding data right into that LEASEQUERY-REPLY message too 🎁 If bindings for more than one client are coming back, the server then sends the rest in a series of LEASEQUERY-DATA messages 📦 If the server has sent at least one client's bindings, it finishes up with a LEASEQUERY-DONE message once all its replies are out 🏁 The client can reuse the same connection to send more queries 🔁 And either end of the TCP connection can close once all the data has been sent 👋

This spec adds a new DHCPv6 option, the Relay-ID option 🆔 The option carries a DUID (DHCP Unique Identifier) that identifies a DHCPv6 relay agent 🪪 Relay agents can include this option in the Relay-Forward messages they send 📨 Servers can keep the Relay-ID and tie it to bindings made for the relay's clients 🗂️ Then a relay can recover binding info about its downstream clients by putting the Relay-ID in a LEASEQUERY message 🔑 The Relay-ID option is defined in Section 5.4.1 📍

Bulk Leasequery supports queries by IPv6 address and by Client DUID, just like [RFC5007] does 🙌 It also adds several brand-new queries 🆕 The new ones can't really be used effectively with the UDP Leasequery protocol 🚫 Requestors MUST NOT send these new query-types in [RFC5007] query messages. 🛑

  • Query by Relay Identifier: asks a server for the bindings tied to one specific relay. The relay is identified by a DUID carried in a Relay-ID option. 🆔
  • Query by Link Address: asks a server for the bindings on one particular network segment. The link is specified in the query's link-address field. 🛤️
  • Query by Remote ID: asks a server for the bindings associated with a Relay Agent Remote-ID option [RFC4649] value. 🏷️

4. Interaction between UDP Leasequery and Bulk Leasequery 🤝

Bulk Leasequery is basically an extension of the existing UDP Leasequery protocol [RFC5007] 💕 This section clears up how the two protocols relate to each other ✨

The query-types introduced in the UDP Leasequery protocol can be used in Bulk Leasequery too 🙌 There's one behavior change when you use Bulk Leasequery 👀 [RFC5007], in sections 4.1.2.5 and 4.3.3, says to use a Client Link option in LEASEQUERY-REPLY messages when multiple bindings were found 📋 With Bulk Leasequery, that mechanism isn't needed, because a server returning multiple bindings just sends them directly, as this document describes 🎉 The Client Link option MUST NOT appear in Bulk Leasequery replies. 🚫

Only LEASEQUERY, LEASEQUERY-REPLY, LEASEQUERY-DATA, and LEASEQUERY-DONE messages are allowed over a Bulk Leasequery connection 🔒 No other DHCPv6 messages are supported 🙅‍♀️ And the Bulk Leasequery connection is not a backup DHCPv6 communication option for clients looking for DHCPv6 service, so don't try it 💀

The new queries introduced in this specification can't be used with the UDP Leasequery protocol 🙈 Servers that implement this specification and also allow UDP queries MUST NOT accept Bulk Leasequery query-types in UDP Leasequery messages. Such servers MUST respond with an error status code of NotAllowed [RFC5007]. ⛔

Implementors should note that the TCP message framing defined in Section 5.1 is not compatible with the UDP message format. If a TCP-framed request is sent as a UDP message, it may not be valid, because protocol fields will be offset by the message-size prefix. 🚨

5. Message and Option Definitions 🧁

Section 5 is next, bestie, and it's where all the exact message layouts live 🔥

5.1. Message Framing for TCP ✨

okay so bulk leasequery over TCP can send one or more DHCPv6 messages at a time, which means the receiver needs to know how big each one is 🧠 that's where the framing comes in. Two octets holding the message size in network byte order get prepended to every DHCPv6 message sent on a Bulk Leasequery TCP connection. those two size octets "frame" each message, periodt 🎀

    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          |    msg-type   |               :
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   :   transaction-id              |                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+                               |
   |                                                               .
   .                            options                            .
   .                           (variable)                          .
   |                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  • message-size: the number of octets in the message that follows, as a 16-bit integer in network byte order.

all the other fields are exactly as they're defined in DHCPv6 [RFC3315] 💅

5.2. Messages 🫶

the LEASEQUERY and LEASEQUERY-REPLY messages are defined in [RFC5007]. in a Bulk Leasequery exchange, one LEASEQUERY-REPLY tells you whether the query worked or flopped, and it also carries the stuff that doesn't change during one query and answer, like the Server-ID and Client-ID options. if a query is successful, only a single LEASEQUERY-REPLY MUST appear. if the server is returning binding data, the LEASEQUERY-REPLY also carries the first client's binding data in an OPTION_CLIENT_DATA option ✨

5.2.1. LEASEQUERY-DATA 🦋

the LEASEQUERY-DATA message carries data about a single DHCPv6 client's leases and/or PD bindings on a single link. the whole point is to cut down on redundant data when there are a bunch of bindings to send. the LEASEQUERY-DATA message MUST be preceded by a LEASEQUERY-REPLY message. the LEASEQUERY-REPLY carries the query's status, the Leasequery's Client-ID and Server-ID options, and the first client's binding data if the query was successful.

LEASEQUERY-DATA MUST ONLY be sent in response to a successful LEASEQUERY, and only if more than one client's data is to be sent. the LEASEQUERY-DATA message's transaction-id field MUST match the transaction-id of the LEASEQUERY request message. the Server-ID, Client-ID, and OPTION_STATUS_CODE options SHOULD NOT be included, because that data should be constant for any one Bulk Leasequery reply and should already have been conveyed in the LEASEQUERY-REPLY message 🙈

5.2.2. LEASEQUERY-DONE 🏁

the LEASEQUERY-DONE message marks the end of a group of related Leasequery replies. its transaction-id field MUST match the transaction-id of the LEASEQUERY request message. the message itself is the signal that a stream of reply messages is over. a single LEASEQUERY-DONE MUST BE sent after all replies (a successful LEASEQUERY-REPLY and zero or more LEASEQUERY-DATA messages) to a successful Bulk Leasequery request that returned at least one binding.

a server might hit an error after it has already sent the initial LEASEQUERY-REPLY. in that case, it SHOULD attempt to send a LEASEQUERY-DONE with an OPTION_STATUS_CODE option indicating the error condition to the requestor. other DHCPv6 options SHOULD NOT be included in the LEASEQUERY-DONE message 😭

5.3. Query Types 🍓

the OPTION_LQ_QUERY option is defined in [RFC5007]. we're introducing three new query-types: QUERY_BY_RELAY_ID, QUERY_BY_LINK_ADDRESS, and QUERY_BY_REMOTE_ID. these are built to help relay agents recover binding data when some or all of the relay's binding data has been lost. main character energy for relays, honestly 👑

5.3.1. QUERY_BY_RELAY_ID 🧚

this query asks the server to return bindings associated with the specified relay DUID.

  • QUERY_BY_RELAY_ID: the query-options MUST contain an OPTION_RELAY_ID option. if the link-address field is 0::0, the query asks for all bindings associated with the specified relay DUID. if the link-address is specified, the query asks for bindings on that link.

the QUERY_BY_LINK_ADDRESS query asks the server to return bindings on a network segment identified by a link-address value from a relay's Relay-Forward message.

  • QUERY_BY_LINK_ADDRESS: the query's link-address contains an address a relay may have used in the link-address of a Relay-Forward message. the server attempts to locate bindings on the same network segment as the link-address.

5.3.3. QUERY_BY_REMOTE_ID 💜

the QUERY_BY_REMOTE_ID query asks the server to return bindings associated with a Remote-ID option value from a relay's Relay-Forward message. the query-options MUST include a Relay Agent Remote-ID option [RFC4649].

in order to support this query, a server needs to record the most-recent Remote-ID option value it sees in a Relay-Forward message along with its other binding data.

  • QUERY_BY_REMOTE_ID: the query-options MUST include a Relay Agent Remote-ID option [RFC4649]. if the server has recorded Remote-ID values with its bindings, it uses the option's value to identify the bindings to return.

5.4. Options 🎀

5.4.1. Relay-ID Option 🔥

the Relay-ID option carries a DUID [RFC3315]. a relay agent MAY include the option in the Relay-Forward messages it sends. obviously, a server can't respond to QUERY_BY_RELAY_ID queries unless the relay agent has included this option 🙄 a relay SHOULD be able to generate a DUID for this purpose and capture the result in stable storage. a relay SHOULD also let the DUID value be configurable, because that lets an administrator replace a relay agent while keeping the association between the relay and existing DHCPv6 bindings ✨

a DHCPv6 server MAY associate Relay-ID options from the Relay-Forward messages it processes with the prefix delegations and/or lease bindings that result. doing that lets it respond to QUERY_BY_RELAY_ID Leasequeries 🦋

the format of the Relay-ID option looks like this:

    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
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |       OPTION_RELAY_ID         |          option-len           |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   .                                                               .
   .                              DUID                             .
   .                        (variable length)                      .
   .                                                               .
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  • option-code: OPTION_RELAY_ID.
  • option-len: length of the DUID in octets.
  • DUID: the DUID for the relay agent.

5.5. Status Codes 🌸

QueryTerminated means the server is unable to perform a query or has stopped it early for some reason (which should be communicated in the text of the message). this could be because the server is short on resources or is being shut down. the requestor may retry the query at a later time, and it should wait at least a short interval before retrying. note that while a server may simply close its end of the connection early, it's preferable for the server to send a LEASEQUERY-REPLY or LEASEQUERY-DONE with this status-code so the requestor knows what happened 🥺

5.6. Connection and Transmission Parameters 🍭

DHCPv6 servers that support Bulk Leasequery SHOULD listen for incoming TCP connections on the DHCPv6 server port 547. implementations MAY offer to make the incoming port configurable, but port 547 MUST be the default. client implementations SHOULD make TCP connections to port 547, and MAY offer to make the destination server port configurable 💖

this section has a table of values that control Bulk Leasequery behavior, including the recommended defaults. implementations MAY make these values configurable. however, configuring timeout values that are too small may lead to harmful behavior, both for this application and for other traffic on the network. so timeout values smaller than the default values are NOT RECOMMENDED. be careful, bestie 🚫

Parameter             Default   Description
-------------------------------------------
BULK_LQ_DATA_TIMEOUT  300 s     Bulk Leasequery data timeout
BULK_LQ_MAX_CONNS     10        Max Bulk Leasequery TCP connections

6. Requestor Behavior 💅

6.1. Connecting 🌈

a requestor tries to establish a TCP connection to a DHCPv6 server so it can start a Leasequery exchange. if the attempt fails, the requestor MAY retry.

6.2. Forming Queries ✨

once the connection is established, the requestor builds a Leasequery message as specified in [RFC5007]. the query can use any of the defined query-types, and it includes the options and data that the chosen query-type needs. the requestor sends the message size first, then the actual DHCPv6 message, as described in Section 5.1 🎀

if the TCP connection becomes blocked or stops being writeable while the requestor is sending its query, the requestor SHOULD be prepared to terminate the connection after BULK_LQ_DATA_TIMEOUT. we make this recommendation so requestors can control how long they're willing to wait before abandoning a connection, independent of any notifications from the TCP implementations they may be using 🫶

6.3. Processing Replies ✨

okay so the requestor tries to read a LEASEQUERY-REPLY message off the TCP connection 📖. If the connection stops delivering reply data (aka it stops being readable), the requestor SHOULD be ready to kill the connection once BULK_LQ_DATA_TIMEOUT passes, and it MAY start retry-processing if it's set up to do that 🫶.

Then the requestor looks at the LEASEQUERY-REPLY and decides what to do next 💅. The validation rules live in DHCPv6 Leasequery [RFC5007], so go read those too. If the reply has an error status code (carried in an OPTION_STATUS_CODE option), the requestor follows the recommendations in [RFC5007] 🚨. A successful reply that doesn't include an OPTION_CLIENT_DATA option just means the target server had no bindings matching the query 🤷‍♀️.

Note: The Leasequery protocol uses the OPTION_CLIENT_LINK option as an indicator that multiple bindings were present in response to a single query. For Bulk Leasequery, the OPTION_CLIENT_LINK option is not used, and MUST NOT be present in replies.

A successful LEASEQUERY-REPLY that's actually returning binding data has an OPTION_CLIENT_DATA option, plus maybe some other options too 💜. If there are more bindings to send back, they show up in LEASEQUERY-DATA messages. Each LEASEQUERY-DATA message has an OPTION_CLIENT_DATA option, and maybe other options as well. Any LEASEQUERY-DATA message that doesn't have an OPTION_CLIENT_DATA MUST be discarded 🗑️.

A single bulk query can produce a LOT of replies. Like, a single relay agent might be in charge of routes for thousands of clients' delegated prefixes 😭. So the requestor MUST be prepared to receive more than one LEASEQUERY-DATA with transaction-ids matching a single LEASEQUERY message 🌈.

The LEASEQUERY-DONE message wraps up a successful Bulk Leasequery request that returned at least one binding 🎀. A LEASEQUERY-REPLY without any bindings MUST NOT be followed by a LEASEQUERY-DONE message for the same transaction-id. After the requestor gets LEASEQUERY-DONE from a server, it MAY close the TCP connection to that server 🦋. And if the transaction-id in the LEASEQUERY-DONE doesn't match any outstanding LEASEQUERY message, the client MUST close the TCP connection. No exceptions, bestie 🙅‍♀️.

6.3.1. Reply Completion

so when is the reply to a Bulk Leasequery request actually done? (aka no more messages for that request transaction-id are coming) 🧐 It's done when one of these is true:

  1. if the LEASEQUERY-REPLY message had no OPTION_CLIENT_DATA option, when the LEASEQUERY-REPLY is received,
  2. else if the LEASEQUERY-REPLY did have an OPTION_CLIENT_DATA, when the corresponding LEASEQUERY-DONE message is received,
  3. else when the connection is closed.

6.4. Querying Multiple Servers

a Bulk Leasequery client MAY be set up to connect to and query multiple DHCPv6 servers in parallel 🍓. The DHCPv6 Leasequery specification [RFC5007] has a whole discussion about reconciling binding data received from multiple DHCPv6 servers, so go check that out if you're doing this 📚.

6.5. Multiple Queries to a Single Server

Bulk Leasequery clients might need to make multiple queries to recover binding information 🔍. A requestor MAY use a single connection to issue multiple queries. Each query MUST have a unique transaction-id 🔑. A server MAY process more than one query at a time. And a server that's willing to do that MAY interleave replies to the multiple queries inside the stream of reply messages it sends 🧚. Clients need to be aware that replies for multiple queries can be interleaved in that stream, obvi 👀. Clients that can't process interleaved replies (based on transaction-id) MUST NOT send more than one query at a time 🙈. Requestors should be aware that servers aren't required to process queries in parallel, and that servers are likely to limit the rate at which they process queries from any one requestor 🐢.

6.5.1. Example

this example shows what a series of queries and responses might look like 💖. It's only an example, though. There's no requirement that this exact sequence be followed, or that clients or servers have to support parallel queries 🫠.

In the example session, the client sends four queries after establishing a connection. "xid" is the transaction-id in the diagram 🎀. Query 1 fails. Query 2 succeeds, and the stream of replies wraps up before the client sends any new query ✅. Query 3 and query 4 overlap, and the server interleaves its replies to those two queries 🌀.

     Client                        Server
     ------                        ------
     LEASEQUERY xid 1 ----->
                      <-----       LEASEQUERY-REPLY xid 1 (w/error)
     LEASEQUERY xid 2 ----->
                      <-----       LEASEQUERY-REPLY xid 2
                      <-----       LEASEQUERY-DATA xid 2
                      <-----       LEASEQUERY-DATA xid 2
                      <-----       LEASEQUERY-DONE xid 2
     LEASEQUERY xid 3 ----->
     LEASEQUERY xid 4 ----->
                      <-----       LEASEQUERY-REPLY xid 4
                      <-----       LEASEQUERY-DATA xid 4
                      <-----       LEASEQUERY-REPLY xid 3
                      <-----       LEASEQUERY-DATA xid 4
                      <-----       LEASEQUERY-DATA xid 3
                      <-----       LEASEQUERY-DONE xid 3
                      <-----       LEASEQUERY-DATA xid 4
                      <-----       LEASEQUERY-DONE xid 4

6.6. Closing Connections

the requestor MAY close its end of the TCP connection after sending a LEASEQUERY message to the server 🔒. It MAY also choose to keep the connection open if it plans to issue more queries 💭. Just know that this doesn't guarantee the connection will still be around for more queries, since the server might decide to close it based on its own configuration 😬.

7. Server Behavior 🏰

7.1. Accepting Connections

servers that implement DHCPv6 Bulk Leasequery listen for incoming TCP connections 👂. Port numbers are covered in Section 5.6. Servers MUST be able to limit the number of currently accepted and active connections 🚦. The value BULK_LQ_MAX_CONNS MUST be the default, but implementations MAY let you configure it 🛠️.

Servers MAY restrict Bulk Leasequery connections and LEASEQUERY messages to certain clients 🕵️‍♀️. Connections that aren't from permitted clients SHOULD BE closed immediately, so the server doesn't run out of connection resources 💀. Servers MAY restrict some clients to certain query types. And servers MAY reply to queries that aren't permitted with the NotAllowed status code [RFC5007], and/or 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 make this recommendation so servers can control how long they're willing to wait before abandoning an inactive connection, no matter which TCP implementation they're using 🧘‍♀️.

7.2. Forming Replies

the DHCPv6 Leasequery [RFC5007] specification describes how to build the initial LEASEQUERY-REPLY messages and how to process QUERY_BY_ADDRESS and QUERY_BY_CLIENTID 📜. Using LEASEQUERY-REPLY and LEASEQUERY-DATA messages to carry multiple bindings is described in Section 5.2. Message transmission and framing for TCP is in Section 5.1. And if the connection gets blocked while the server is trying to send replies, the server SHOULD be ready to terminate the TCP connection after BULK_LQ_DATA_TIMEOUT ⏰.

If the server runs into an error during initial query processing, before any reply has been sent, it SHOULD send a LEASEQUERY-REPLY containing an error code in an OPTION_STATUS_CODE option 🚫. That tells the requestor no data is coming. If the server hits an error while processing a query that has already produced one or more replies, the server SHOULD send a LEASEQUERY-DONE message with an error status 💔. The server SHOULD also close its end of the connection, which says "hey, I couldn't finish query processing" 👋.

If the server doesn't find any bindings that satisfy a query, it SHOULD send a LEASEQUERY-REPLY without an OPTION_STATUS_CODE option and without any OPTION_CLIENT_DATA option 🫥. Otherwise, the server sends each binding's data in a reply message. The first reply message is a LEASEQUERY-REPLY. The binding data goes in an OPTION_CLIENT_DATA option, as specified in [RFC5007] and extended below ✨. The server returns the rest of the bindings in LEASEQUERY-DATA messages, which avoids sending redundant data (like the requestor's Client-ID) over and over 🧠.

For QUERY_BY_RELAY_ID, the server finds each binding associated with the query's Relay-ID option value 🔎. To give a meaningful reply, the server has to be able to keep this association in its DHCPv6 binding data 🗂️. If the query's link-address isn't set to 0::0, the server only returns bindings on links that could contain that address 📍. And if the link-address isn't 0::0 and the server can't find any matching links, the server SHOULD return the NotConfigured status in a LEASEQUERY-REPLY 🙃.

For QUERY_BY_LINK_ADDRESS, the server finds each binding associated with the link identified by the query's link-address value 🔗.

For QUERY_BY_REMOTE_ID, the server finds each binding associated with the query's Relay Remote-ID option value 🛰️. To give meaningful replies to this query, the server has to be able to keep this association in its binding database 💅. If the query message's link-address isn't set to 0::0, the server only returns bindings on links that could contain that address. And if the link-address isn't 0::0 and the server can't find any matching links, the server SHOULD return the NotConfigured status in a LEASEQUERY-REPLY 🌸.

The server sends the LEASEQUERY-DONE message as specified in Section 5.2 🎬.

7.3. Multiple or Parallel Queries

as we covered in Section 6.5, requestors may want to use an existing connection if they need to make multiple queries 🔁. Servers MAY support reading and processing multiple queries from a single connection. But a server MUST NOT read more query messages from a connection than it's prepared to process at the same time 🛑.

This MAY be a feature that's controlled administratively 🎛️. Servers that can process queries in parallel SHOULD offer configuration that limits how many simultaneous queries are allowed from any one requestor 💜. That keeps resource use under control when there are multiple requestors asking for service 🫶.

7.4. Closing Connections 🔌✨

okay so the server MAY close its end of the TCP connection after sending its last message (a LEASEQUERY-REPLY or a LEASEQUERY-DONE) in response to a query. 💅 Or, alternatively, the server MAY retain the connection and wait for more queries from the client. 🦋 The server SHOULD be prepared to limit the number of connections it maintains, and it SHOULD be prepared to close idle connections to enforce that limit. bestie, that's just good housekeeping 🧹💖

The server MUST close its end of the TCP connection if it runs into 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 MAY attempt to notify its clients by using the QueryTerminated (Section 5.5) status code. 📣 And if the server detects that the client end has been closed, the server MUST close its end of the connection after it has finished processing any outstanding requests from the client. 🫶 Finish your work first, then leave the party 🎀

8. Security Considerations 🔐💀

The "Security Considerations" section of [RFC3315] details the general threats to DHCPv6. 👀 The DHCPv6 Leasequery specification [RFC5007] describes recommendations for the Leasequery protocol, especially with regard to relayed LEASEQUERY messages, mitigation of packet-flooding denial-of-service (DoS) attacks, restriction to trusted clients, and use of IPsec [RFC4301]. 🛡️

The use of TCP introduces some additional concerns, and this part is seriously important 😤 Attacks that try to exhaust the DHCPv6 server's available TCP connection resources, such as SYN flooding attacks, can compromise the ability of legitimate clients to receive service. 🚨 Malicious clients who manage to establish connections, but then send invalid queries, partial queries, or no queries at all, can also exhaust 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. 🔒✨ Lock the doors, bestie!

9. IANA Considerations 📋🌈

IANA has assigned a new value in the registry of DHCPv6 Option Codes:

   53 OPTION_RELAY_ID

IANA has assigned a new value in the registry of DHCPv6 Status Codes:

   11 QueryTerminated

IANA has assigned the following values in the registry of DHCPv6 Message types:

   16 LEASEQUERY-DONE
   17 LEASEQUERY-DATA

IANA has assigned the following values in the registry of query-types for the DHCPv6 OPTION_LQ_QUERY option:

   3 QUERY_BY_RELAY_ID
   4 QUERY_BY_LINK_ADDRESS
   5 QUERY_BY_REMOTE_ID

The above-mentioned registries are available from http://www.iana.org. 🌸

10. Acknowledgments 🫶🎀

Many of the ideas in this document were originally proposed by Kim Kinnear, Richard Johnson, Hemant Singh, Ole Troan, and Bernie Volz. 👑 Further suggestions and improvements were made by participants in the DHC working group, including John Brzozowski, Marcus Goller, Alfred Hoenes, Ted Lemon, Bud Millwood, and Thomas Narten. 💜 The real MVPs, no cap 😭✨

11. References 📚

11.1. Normative References 💅

[RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
           Requirement Levels", BCP 14, RFC 2119, March 1997.

[RFC3315]  Droms, R., Bound, J., Volz, B., Lemon, T., Perkins, C.,
           and M. Carney, "Dynamic Host Configuration Protocol for
           IPv6 (DHCPv6)", RFC 3315, July 2003.

[RFC3633]  Troan, O. and R. Droms, "IPv6 Prefix Options for Dynamic
           Host Configuration Protocol (DHCP) version 6", RFC 3633,
           December 2003.

[RFC4649]  Volz, B., "Dynamic Host Configuration Protocol for IPv6
           (DHCPv6) Relay Agent Remote-ID Option", RFC 4649,
           August 2006.

[RFC5007]  Brzozowski, J., Kinnear, K., Volz, B., and S. Zeng,
           "DHCPv6 Leasequery", RFC 5007, September 2007.

11.2. Informative References 🧚

[RFC4301]  Kent, S. and K. Seo, "Security Architecture for the
           Internet Protocol", RFC 4301, December 2005.

[RFC4614]  Duke, M., Braden, R., Eddy, W., and E. Blanton, "A Roadmap
           for Transmission Control Protocol (TCP) Specification
           Documents", RFC 4614, September 2006.

Author's Address 🦋

Mark Stapp
Cisco Systems, Inc.
1414 Massachusetts Ave.
Boxborough, MA  01719
USA

Phone: +1 978 936 0000
EMail: mjs@cisco.com
📦 where this page comes from