<?xml version="1.0" encoding="US-ASCII"?>

<?rfc toc="yes" ?>
<?rfc rfcedstyle="yes" ?>
<?rfc subcompact="no" ?>
<?rfc symrefs="no" ?>

<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
    <!ENTITY rfc2119 PUBLIC '' 
      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
    <!ENTITY rfc2131 PUBLIC ''
      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2131.xml'>
    <!ENTITY rfc3315 PUBLIC '' 
      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3315.xml'>
    <!ENTITY rfc3633 PUBLIC '' 
      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3633.xml'>
    <!ENTITY rfc4388 PUBLIC '' 
      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4388.xml'>
    <!ENTITY rfc4301 PUBLIC '' 
      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4301.xml'>
    <!ENTITY rfc2434 PUBLIC '' 
      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2434.xml'>
    <!ENTITY rfc2461 PUBLIC '' 
      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2461.xml'>
    <!ENTITY rfc0826 PUBLIC '' 
      'http://xml.resource.org/public/rfc/bibxml/reference.RFC.0826.xml'>
]>

<rfc number="5007" category="std" >
<front>

<title>DHCPv6 Leasequery</title>

<author initials="J." surname="Brzozowski" fullname="John Jason Brzozowski">
<organization>Comcast Cable</organization>
<address>
<postal>
<street>1800 Bishops Gate Boulevard</street>
<city>Mt. Laurel</city> <region>NJ</region> <code>08054</code>
<country>USA</country>
</postal>
<phone>+1 856 324 2671</phone>
<email>john_brzozowski@cable.comcast.com</email>
</address>
</author>

<author initials="K." surname="Kinnear" fullname="Kim Kinnear">
<organization>Cisco Systems, Inc.</organization>
<address>
<postal>
<street>1414 Massachusetts Ave.</street>
<city>Boxborough</city> <region>MA</region> <code>01719</code>
<country>USA</country>
</postal>
<phone>+1 978 936 0000</phone>
<email>kkinnear@cisco.com</email>
</address>
</author>

<author initials="B." surname="Volz" fullname="Bernard Volz">
<organization>Cisco Systems, Inc.</organization>
<address>
<postal>
<street>1414 Massachusetts Ave.</street>
<city>Boxborough</city> <region>MA</region> <code>01719</code>
<country>USA</country>
</postal>
<phone>+1 978 936 0000</phone>
<email>volz@cisco.com</email>
</address>
</author>

<author initials="S." surname="Zeng" fullname="Shengyou Zeng">
<organization>Cisco Systems, Inc.</organization>
<address>
<postal>
<street>1414 Massachusetts Ave.</street>
<city>Boxborough</city> <region>MA</region> <code>01719</code>
<country>USA</country>
</postal>
<phone>+1 978 936 0000</phone>
<email>szeng@cisco.com</email>
</address>
</author>

<date month="August" year="2007"></date>

<!-- [rfced] Please insert any additional keywords (beyond those that appear in
the title) for use on http://www.rfc-editor.org/rfcsearch.html. -->

<workgroup>DHC</workgroup>
<keyword>DHCP</keyword>
<keyword>IPv6</keyword>
<keyword>LEASEQUERY</keyword>
<keyword>DHCPv6</keyword>

<abstract>
<t>
This document specifies a leasequery exchange for the Dynamic Host Configuration Protocol
for IPv6 (DHCPv6) that can be used to obtain lease information about
DHCPv6 clients from a DHCPv6 server.  This document specifies the scope of data
that can be retrieved as well as both DHCPv6 leasequery requestor and server behavior.
This document extends DHCPv6.
</t>
</abstract>

</front>
<middle>

<!--
============================INTRODUCTION-BEGIN==========================
======= -->
<section title="Introduction">

<t>
The DHCPv6 <xref target="RFC3315"/> protocol specifies a
mechanism for the assignment of both IPv6 address and
configuration information to IPv6 nodes.  IPv6 Prefix Options for
DHCPv6 <xref target="RFC3633"/>
specifies a mechanism for the automated delegation of IPv6 prefixes and related
options.  Similar to DHCPv4 <xref target="RFC2131"/>, DHCPv6 servers maintain
authoritative information related to their operations including, but not
limited to, lease information for IPv6 addresses and delegated prefixes.
</t>

<t>
The requirement exists in various types of IPv6 deployments, particularly
those of a broadband variety, to leverage DHCPv6 <xref target="RFC3315"/>
for retrieving data related to the operation of DHCPv6 servers
programmatically.  In particular, it is desirable to be able to extract 
lease information about IPv6 addresses and delegated prefixes assigned
using DHCPv6 <xref target="RFC3315"/> <xref target="RFC3633"/>. 
Specific examples where this information has illustrated value are in
broadband networks to facilitate access control by edge devices.  
This capability to programmatically extract lease data from the DHCPv6
server is called leasequery.
</t>

<t>
The leasequery capability described in this document parallels the DHCPv4
leasequery capability documented in <xref target="RFC4388"/>. As such, it
shares the basic motivations, background, design goals and constraints
as described in <xref target="RFC4388"/>.  Differences are due to
the differences between IPv4 and IPv6 and by extension, DHCPv4 and DHCPv6.
For example, Neighbor Discovery <xref target="RFC2461"/> is used in IPv6
instead of the Address Resolution Protocol (ARP) <xref target="RFC0826"/> (Section 4.1 of <xref target="RFC4388"/>)
and DOCSIS 3.0 <xref target="DOCSIS3"/> defines IPv6 support for cable modem
environments.
</t>

</section>
<!--
============================INTRODUCTION-END============================
===== -->

<section title="Terminology">
<t>
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 <xref target="RFC2119"/>.
</t>

<t>DHCPv6 terminology is defined in <xref target="RFC3315"/>.
Terminology specific to DHCPv6 leasequery can be found below:
</t>


<t>
<list style="hanging" hangIndent="16">

<t hangText="access concentrator">
<vspace blankLines="0"/>
                    An 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 DHCPv6 relay agent functionality.</t>

<t hangText="client(s)">       The nodes that have one or more bindings
                    with a DHCPv6 server. This does not refer to
                    the node issuing the LEASEQUERY unless it
                    itself has one or more bindings with a DHCPv6
                    server.</t>
                    
<t hangText="gleaning">        Gleaning is the extraction of location
                    information from DHCPv6 messages, as the
                    messages are forwarded by the DHCP relay agent
                    function.</t>

<t hangText="location information">
<vspace blankLines="0"/>
                    Location information is information needed by
                    the access concentrator to forward traffic to
                    a broadband-accessible host. This information
                    includes knowledge of the host hardware
                    address, the port or virtual circuit that
                    leads to the host, and/or the hardware address
                    of the intervening subscriber modem.</t>
                    
<t hangText="requestor">       The node that sends LEASEQUERY messages to one 
                    or more servers to retrieve information on the
                    bindings for a client.</t>

</list>
</t>

</section>

<!-- ===============================================================-->
<section title="Protocol Overview">

<t>The focus of this document is to extend the DHCPv6 protocol to allow
processes and devices that wish to access information from a DHCPv6
server to do so in a lightweight and
convenient manner.  It is especially appropriate for processes and
devices that already interpret DHCPv6 messages.</t>

<t>The LEASEQUERY message is a query message only and does not
affect the state of the IPv6 address or prefix, or the binding information
associated with it.</t>

<t>
One important motivating example is that the LEASEQUERY message
allows access concentrators to query DHCP servers to obtain location
information of broadband access network devices. This is described
in Section 1 of <xref target="RFC4388"/> for IPv4.
</t>

<section title="On-Demand Query">

<t>The on-demand leasequery capability allows requesting just
the information necessary to satisfy an immediate need.  If the
requestor is an access concentrator, then the immediate need will
typically be that it has received an IPv6 packet and it needs to
refresh its information concerning the DHCPv6 client to which 
that IPv6 address is currently leased.  In this case, the request
will be by address. This fits clearly into the single request/response
cycle common to other DHCPv6 message exchanges.
</t>

<t>
However, this approach has limitations when used with prefix
delegation <xref target="RFC3633"/> as no traffic may arrive because
the access concentrator is unable to inject the appropriate
routing information into the routing infrastructure, such as after a reboot.
This approach does work if the access concentrator is configured to inject routing
information for a prefix that aggregates potentially delegated
prefixes. Or, it also works if the access concentrator and requesting router
use a routing protocol; as then the requesting router can
trigger the access concentrator to request information from a DHCPv6
server and inject appropriate routing information into the routing
infrastructure.
</t>

</section>

<section title="Anticipatory Query">

<t>
A second approach for requesting information from a DHCPv6 server would
be to use a leasequery-like capability to rebuild an internal data store
containing information available from a DHCPv6 server. The rebuilding
of the data store in this approach can take place as soon as possible
after the need to rebuild it is discovered (such as on booting), and
doesn't wait on the receipt of specific packets to trigger a piecemeal
database update (as is the case for on-demand leasequery). This approach
would also remove the limitation discussed above for prefix delegation.
</t>

<t>
This anticipatory query is not specified in this document and is an
area of future work.
</t>

</section>

<section title="Query Types">

<t>Leasequery provides for the following queries:</t>

<list style="hanging">
<t hangText="Query by IPv6 address -">
This query allows a requestor to request from a server the
bindings for a client that either is bound to the address
or has been delegated the prefix that contains the address.
</t>

<t hangText="Query by Client Identifier (DUID) -">
This query allows a requestor to request from a server the
bindings for a specific client on a specific link or a list
of the links on which the client has one or more bindings.
</t>
</list>

</section>

</section>

<!-- =============================================================== -->
<?rfc needLines="10"?>

<section title="Protocol Details">

<section title="Message and Option Definitions">

<!-- =============================================================== -->
<section title="Messages">

<t>
The LEASEQUERY and LEASEQUERY-REPLY messages use the Client/Server
message formats described in <xref target="RFC3315"/>, Section 6.
Two new message codes are defined:
</t>

<list style="hanging">

<t hangText="LEASEQUERY (14) -">
A requestor sends a LEASEQUERY message to any
available server to obtain information on a client's leases.
The options in an OPTION_LQ_QUERY determine the query.
</t>

<t hangText="LEASEQUERY-REPLY (15) -">
A server sends a LEASEQUERY-REPLY message
containing client data in response to a LEASEQUERY message.
</t>
</list>

</section>

<!-- =============================================================== -->

<section title="Options">

<!-- =============================================================== -->

<section title="Query Option" anchor="section.queryoption">

<t>
The Query option is used only in a LEASEQUERY message and identifies
the query being performed. The option includes the query type, link-address (or
0::0), and option(s) to provide data needed for the query.
</t>

<figure>
<preamble>The format of the Query option is shown below:</preamble>
<artwork>
     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_LQ_QUERY        |         option-len            |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |   query-type  |                                               |
    +-+-+-+-+-+-+-+-+                                               |
    |                                                               |
    |                         link-address                          |
    |                                                               |
    |               +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |               |                                               .
    +-+-+-+-+-+-+-+-+                                               .
    .                         query-options                         .
    .                                                               .
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

      option-code      OPTION_LQ_QUERY (44)

      option-len       17 + length of query-options field.
      
      link-address     A global address that will be used by the
                       server to identify the link to which the
                       query applies, or 0::0 if unspecified.

      query-type       The query requested (see below).

      query-options    The options related to the query.
</artwork>
</figure>

<t>The query-type and required query-options are:</t>

<list style="hanging">

<t hangText="QUERY_BY_ADDRESS (1) -">
The query-options MUST contain an OPTION_IAADDR option
<xref target="RFC3315"/>. The link-address field, if not 0::0,
specifies an address for the link on which the client is located
if the address in the OPTION_IAADDR option is of insufficient
scope. Only the information for the client that has a lease for
the specified address or was delegated a prefix that contains the
specified address is returned (if available).
</t>

<t hangText="QUERY_BY_CLIENTID (2) - ">
The query-options MUST contain an OPTION_CLIENTID option
<xref target="RFC3315"/>. The link-address field, if not 0::0,
specifies an address for the link on which the client is located.
If the link-address field is 0::0, the server SHOULD search all
of its links for the client.
<!-- [rfced] Can "its links of the client" be replaced with "client links"?-->
</t>
</list>

<t>The query-options MAY also include an OPTION_ORO option
<xref target="RFC3315"/> to indicate the options for each client that the
requestor would like the server to return. Note that this OPTION_ORO is
distinct and separate from an OPTION_ORO that may be in the requestor's
LEASEQUERY message.
</t>

<t>If a server receives an OPTION_LQ_QUERY with a query-type it does not
support, the server SHOULD return an UnknownQueryType status-code. If a server
receives a supported query-type but the query-options is missing a
required option, the server SHOULD return a MalformedQuery status-code.
</t>

</section>

<!-- =============================================================== -->

<section title="Client Data Option">

<t>
The Client Data option is used to encapsulate the data for a single client on
a single link in a LEASEQUERY-REPLY message.
</t>

<figure>
<preamble>The format of the Client Data option is shown below:</preamble>
<artwork>
     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_CLIENT_DATA      |         option-len            |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    .                                                               .
    .                        client-options                         .
    .                                                               .
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

      option-code      OPTION_CLIENT_DATA (45)

      option-len       Length, in octets, of the encapsulated client-
                       options field.

      client-options   The options associated with this client.
</artwork>
</figure>

<t>
The encapsulated client-options include the OPTION_CLIENTID, OPTION_IAADDR,
OPTION_IAPREFIX, and OPTION_CLT_TIME options and other options specific to
the client and requested by the requestor in the OPTION_ORO in the
OPTION_LQ_QUERY's query-options.  The server MUST return all of the client's
statefully assigned addresses and delegated prefixes, with a
non-zero valid lifetime, on the link.
</t>

</section>

<section title="Client Last Transaction Time Option">

<t>
The Client Last Transaction Time option is encapsulated in
an OPTION_CLIENT_DATA and identifies how long ago the server
last communicated with the client, in seconds.
</t>

<figure>
<preamble>The format of the Client Last Transaction Time option is
shown below:</preamble>
<artwork>
     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_CLT_TIME        |         option-len            |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                 client-last-transaction-time                  |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

      option-code      OPTION_CLT_TIME (46)

      option-len       4

      client-last-transaction-time
                       The number of seconds since the server last
                       communicated with the client (on that link).
</artwork>
</figure>

<t>
The client-last-transaction-time is a positive value and reflects the
number of seconds since the server last communicated with the client
(on that link).
</t>

</section>

<section title="Relay Data" anchor="section.relayoption">

<t>
The Relay Data option is used only in a LEASEQUERY-REPLY message
and provides the relay agent information used when the client
last communicated with the server.
</t>

<figure>
<preamble>The format of the Relay Data option is shown below:</preamble>
<artwork>
     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_LQ_RELAY_DATA      |         option-len            |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                                                               |
    |                  peer-address (IPv6 address)                  |
    |                                                               |
    |                                                               |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                                                               |
    |                       DHCP-relay-message                      |
    .                                                               .
    .                                                               .
    .                                                               .
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

      option-code      OPTION_LQ_RELAY_DATA (47)

      option-len       16 + length of DHCP-relay-message.

      peer-address     The address of the relay agent from which
                       the relayed message was received by the
                       server.

      DHCP-relay-message
                       The last complete relayed message, excluding
                       the client's message OPTION_RELAY_MSG,
                       received by the server.
</artwork>
</figure>

<t>This option is used by the server to return full relay agent
information for a client. It MUST NOT be returned if the server does
not have such information, either because the client communicated
directly (without relay agent) with the server or if the server did
not retain such information.</t>

<t>If returned, the DHCP-relay-message MUST contain a valid (perhaps
multi-hop) RELAY-FORW message as the most recently received by the server
for the client. However, the (innermost) OPTION_RELAY_MSG option
containing the client's message MUST have been removed.
</t>

<t>This option SHOULD only be returned if requested by the OPTION_ORO
of the OPTION_LQ_QUERY.</t>

</section>

<section title="Client Link Option" anchor="section.linkoption">

<t>
The Client Link option is used only in a LEASEQUERY-REPLY message
and identifies the links on which the client has one or more bindings.
It is used in reply to a query when no link-address was specified
and the client is found to be on more than one link.
</t>

<figure>
<preamble>The format of the Client Link option is shown below:</preamble>
<artwork>
     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_LQ_CLIENT_LINK     |         option-len            |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                                                               |
    |                  link-address (IPv6 address)                  |
    |                                                               |
    |                                                               |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                                                               |
    |                  link-address (IPv6 address)                  |
    |                                                               |
    |                                                               |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                              ...                              |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

      option-code      OPTION_LQ_CLIENT_LINK (48)

      option-len       Length of the list of links in octets;
                       must be a multiple of 16.
      
      link-address     A global address used by the server to
                       identify the link on which the client is
                       located.
</artwork>
</figure>

<t>A server may respond to a query by client-id, where the 0::0 link-address
was specified, with this option if the client is found to be on multiple links.
The requestor may then repeat the query once for each link-address returned
in the list, specifying the returned link-address.
If the client is on a single link, the server SHOULD return the
client's data in an OPTION_CLIENT_DATA option.</t>

</section>

</section>

<!-- =============================================================== -->
<?rfc needLines="10"?>

<section title="Status Codes" anchor="section.statuscodes">

<t>The following new status codes are defined:</t>

<list style="hanging">

<t hangText="UnknownQueryType (7) -">
The query-type is unknown to or not supported by the server.
</t>

<t hangText="MalformedQuery (8) -">
The query is not valid; for example, a required query-option is missing
from the OPTION_LQ_QUERY.
</t>

<t hangText="NotConfigured (9) -">
The server does not have the target address or link in its
configuration.</t>

<t hangText="NotAllowed (10) -">
The server does not allow the requestor to issue this LEASEQUERY.
</t>
</list>

</section>

<section title="Transmission and Retransmission Parameters">

<t>
This section presents a table of values used to describe the message
transmission behavior for leasequery.
</t>

<figure>
<artwork>
Parameter     Default  Description
----------------------------------
LQ_TIMEOUT     1 sec   Initial LEASEQUERY timeout
LQ_MAX_RT     10 secs  Max LEASEQUERY timeout value
LQ_MAX_RC      5       Max LEASEQUERY retry attempts
</artwork>
</figure>

</section>

</section>

<!--
============================MESSAGE-VALIDATION-BEGIN====================
============= -->
<section title="Message Validation">
<section title="LEASEQUERY">
<t>
Requestors and clients MUST discard any received LEASEQUERY messages.
</t>
<t>
Servers MUST discard any received LEASEQUERY messages that meet any of
the following conditions:
</t>
<list style="symbols">
<t>the message does not include an OPTION_CLIENTID option.</t>
<t>the message includes an OPTION_SERVERID option but the contents of
the OPTION_SERVERID option does not match the server's identifier.</t>
<t>the message does not include an OPTION_LQ_QUERY option.</t>
</list>

</section>
<section title="LEASEQUERY-REPLY">
<t>
Requestors MUST discard any received LEASEQUERY-REPLY messages that meet
any of the following conditions:
</t>

<list style="symbols">
<t>the message does not include an OPTION_SERVERID option.</t>
<t>the message does not include an OPTION_CLIENTID option, or the 
contents of the OPTION_CLIENTID option do not match the DUID of the requestor.</t>
<t>the "transaction-id" field in the message does not match the value
used in the original message.</t>
</list>

<t>
Servers and Relay Agents (on the server port, 547 <xref target="RFC3315"/>)
MUST discard any received LEASEQUERY-REPLY messages.
</t>

</section>
</section>
<!--
============================MESSAGE-VALIDATION-END======================
=========== -->



<!-- ======================CLIENT SECTION BEGIN========================= -->


<section title="DHCPv6 Leasequery Requestor Behavior" anchor="section.clients">

<t>
This section describes how a requestor initiates lease data retrieval from
DHCPv6 servers.
</t>

<section title="Creation of LEASEQUERY">

<t>
The requestor sets the "msg-type" field to LEASEQUERY. The requestor
generates a transaction ID and inserts this value in the "transaction-id" field.  
</t>

<t>
The requestor MUST include an OPTION_CLIENTID option to identify itself
to the server.
</t>

<t>
The requestor MUST include an OPTION_LQ_QUERY option and set the
query-type, link-address, and query-options as appropriate to the
query-type (<xref target="section.queryoption"/>).  
</t>

<t>
The requestor SHOULD include an OPTION_SERVERID if it is not unicasting
the LEASEQUERY yet only wants a response from a specific server.
</t>

</section>


<section title="Transmission of LEASEQUERY">

<t>
The requestor MAY be configured to use a list of destination
addresses, which MAY include unicast addresses, the All_DHCP_Servers
multicast address, or other addresses selected by the network
administrator. If the requestor has not been explicitly configured, 
it MAY use the All_DHCP_Servers multicast address as the
default.
</t>

<t>
The requestor SHOULD send LEASEQUERY to one or more DHCPv6 servers that are
known to possess authoritative information concerning the query target. 
</t>

<t>
In the absence of information concerning which DHCPv6 servers might possess
authoritative information on the query target, the requestor SHOULD send
LEASEQUERY to all DHCPv6 servers that the requestor knows about or is
configured with.  For example, the requestor MAY send LEASEQUERY to the
All_DHCP_Servers multicast address.
</t>

<t>
The requestor transmits LEASEQUERY messages according to Section 14 of
<xref target="RFC3315"/>, using the following parameters:</t>

<figure>
<artwork>
    IRT    LQ_TIMEOUT
    MRT    LQ_MAX_RT
    MRC    LQ_MAX_RC
    MRD    0
</artwork>
</figure>

<t>
If the message exchange fails, the requestor takes an action based on
the requestor's local policy.  Examples of actions the requestor might take
include:
</t>
<t>

<list style="symbols">
<t>
Select another server from a list of servers known to the requestor.
</t>
<t>
Send to multiple servers by multicasting to the All_DHCP_Servers address.
</t>
<t>
Terminate the request.
</t>
</list>
</t>

</section>

<section title="Receipt of LEASEQUERY-REPLY">

<t>
A successful LEASEQUERY-REPLY is one without an OPTION_STATUS_CODE
option (or an OPTION_STATUS_CODE option with a success code). There
are three variants:</t>

<list style="numbers">
<t>If the server had bindings for the requested client,
the message includes an OPTION_CLIENT_DATA option and the
requestor extracts the client data from the LEASEQUERY-REPLY and
updates its binding information database. If the OPTION_CLIENT_DATA
contains no OPTION_CLT_TIME, the requestor SHOULD silently discard
the OPTION_CLIENT_DATA option.
</t>

<t>If the server found bindings for the client on multiple links,
the message includes an OPTION_CLIENT_LINK option. The requestor
will need to reissue LEASEQUERY messages using each of the
returned link-addresses to obtain the client's bindings.</t>

<t>If the server had no bindings for the client, neither the
OPTION_CLIENT_DATA nor OPTION_CLIENT_LINK option will be present.
</t>
</list>

<t>
An unsuccessful LEASEQUERY-REPLY is one that has an OPTION_STATUS_CODE
with an error code. Depending on the status code, the requestor may
try a different server (such as for NotAllowed, NotConfigured, and
UnknownQueryType), try a different or corrected query (such as for
UnknownQueryType and MalformedQuery), or terminate the query.
</t>

</section>

<section title="Handling DHCPv6 Client Data from Multiple Sources" anchor="section.sources">

<t>
A requestor may receive lease data on the same client from the same
DHCPv6 server in response to different types of LEASEQUERY.  If a
LEASEQUERY is sent to multiple servers, the requestor may receive
from several servers lease data on the same DHCPv6 client.
This section describes how the requestor handles multiple lease data
sources on the same DHCPv6 client from the same server or different
servers.  
</t>

<t>
The client data from the different sources may be disjoint or overlapping.
The disjoint and overlapping relationship can happen between data from the
same server or different servers.  
</t>

<t>
If client data from two sources on the same client are of different types
or values, then the data are disjoint.  An example of data of different
types is when a requestor receives an IPv6 address lease from one server
and a prefix lease from another server, both assigned to the same client.
An example of different values (but the same type) is when a requestor
receives two IPv6 address leases from two different servers, both assigned
to the same client, but the leases are on two different IPv6 addresses.
If the requestor receives disjoint client data from different sources,
it SHOULD merge them.     
</t>

<t>
If client data from two sources on the same client are of the same type
and value, then the data are overlapping.  An example of overlapping data
is when a requestor receives a lease on the same IPv6 address from two
different servers.  Overlapping client data are also called conflicting data.  
</t>

<t>
The requestor SHOULD use the OPTION_CLT_TIME to resolve data conflicts
originated from different servers, and SHOULD accept data with most
recent OPTION_CLT_TIME.
</t> 

</section>

</section>

<!--
============================SERVER-BEGIN================================
= -->

<section title="DHCPv6 Leasequery Server Behavior" anchor="section.servers">

<t>
A DHCPv6 server sends LEASEQUERY-REPLY messages in response
to valid LEASEQUERY messages it receives to return the statefully
assigned addresses, delegated prefixes, and other information 
that match the query.
</t>

<section title="Receipt of LEASEQUERY Messages"  anchor="section.server.receipt">
<t>
Upon receipt of a valid LEASEQUERY message, the DHCPv6 server locates
the requested client, collects data on the client, and constructs
and returns a LEASEQUERY-REPLY.  A LEASEQUERY message cannot be used
to assign, release, or otherwise modify bindings or other configuration
information.
</t>

<t>
The server constructs a LEASEQUERY-REPLY message by setting the "msg-type" field
to LEASEQUERY-REPLY, and copying the transaction ID from the LEASEQUERY message
into the transaction-id field.
</t>

<t>
If the query-type in the OPTION_LQ_QUERY option is not a known or supported
value, the server adds an OPTION_STATUS_CODE option with the UnknownQueryType
status code and sends the LEASEQUERY-REPLY to the requestor. 
If the query-options do not contain the required options for the
query-type, the server adds an OPTION_STATUS_CODE option with the
MalformedQuery status code and sends the LEASEQUERY-REPLY to the client. 
</t>

<t>
A server may also restrict LEASEQUERY messages, or query-types, to certain
requestors. In this case, the server MAY discard the LEASEQUERY message or
MAY add an OPTION_STATUS_CODE option with the NotAllowed status code and
send the LEASEQUERY-REPLY to the requestor. 
</t>

<t>
If the OPTION_LQ_QUERY specified a non-zero link-address, the server MUST
use the link-address to find the appropriate link for the client.
For a QUERY_BY_ADDRESS, if the 0::0 link-address was specified, the
server uses the address from the OPTION_IAADDR option to find the
appropriate link for the client. In either of these cases, if the
server is unable to find the link, it SHOULD return an
OPTION_STATUS_CODE option with the NotConfigured status and send the
LEASEQUERY-REPLY to the requestor.
</t>

<t>
For a QUERY_BY_CLIENTID, if a 0::0 link-address was specified, the
server MUST search all of its links for the client. If the client
is only found on a single link, the server SHOULD return that
client's data in an OPTION_CLIENT_DATA option. If the client is
found on more than a single link, the server MUST return the list
of links in the OPTION_CLIENT_LINK option; the server MUST NOT
return any client data.
</t>

<t>
Otherwise, the server uses the data in the OPTION_LQ_QUERY to initiate
the query. The result of the query will be zero or one client. This will
result in zero or one OPTION_CLIENT_DATA option being added to the
LEASEQUERY-REPLY.
</t>

</section>

<section title="Constructing the Client's OPTION_CLIENT_DATA" anchor="section.clientdata">
<t>
An OPTION_CLIENT_DATA option in a LEASEQUERY-REPLY message MUST
minimally contain the following options:
</t>

<?rfc subcompact="yes"?>

<list style="numbers">
<t>OPTION_CLIENTID</t>
<t>OPTION_IAADDR and/or OPTION_IAPREFIX</t>
<t>OPTION_CLT_TIME</t>
</list>	

<?rfc subcompact="no"?>

<t>
Depending on the bindings the client has on a link, either OPTION_IAADDR options,
OPTION_IAPREFIX options, or both may be present.</t>

<t>
The OPTION_CLIENT_DATA SHOULD include options requested in the
OPTION_ORO of the OPTION_LQ_QUERY option in the LEASEQUERY message
and that are acceptable to return based on the list of "sensitive options",
discussed below.
</t>

<t>
DHCPv6 servers SHOULD be configurable with a list of "sensitive
options" that must not be returned to the requestor when specified in the
OPTION_ORO of the OPTION_LQ_QUERY option in the LEASEQUERY message.
Any option on this list MUST NOT be returned to a requestor, even
if requested by that requestor.
</t>

</section>

<section title="Transmission of LEASEQUERY-REPLY Messages">
<t>
The server sends the LEASEQUERY-REPLY message as described in
the "Transmission of Reply Messages" section of <xref target="RFC3315"/>.
</t>

</section>

</section>

<!--
============================SERVER-END=================================
-->

</section>

<!-- ================================================================= -->

<section title="Security Considerations">

<t>
Access concentrators are expected to be common leasequery
requestors.  Access concentrators that use DHCPv6 gleaning
(i.e., <xref target="I-D.ietf-dhc-dhcpv6-agentopt-delegate"/>),
refreshed with LEASEQUERY messages, will maintain
accurate client/binding information.  This ensures that the
access concentrator can forward data traffic to the intended
destination in the broadband access network, can perform IPv6
source address verification of datagrams from the access
network, and can encrypt traffic that can only be decrypted by
the intended access modem (e.g., <xref target="refs.bpi"/> and
<xref target="refs.bpi+"/>).  Thus, the
leasequery capability allows an access concentrator to provide
considerably enhanced security.
</t>

<t>
The "Security Considerations" section of <xref target="RFC3315"/> details the
general threats to DHCPv6, and thus to LEASEQUERY messages.
The "Authentication of DHCP Messages" section of <xref target="RFC3315"/> describes
securing communication between relay agents and servers, as
well as clients and servers.  If the requestor is an access
concentrator, the IPsec-based <xref target="RFC4301"/>
security as described in <xref target="RFC3315"/>
Section 21.1 SHOULD be used.  Other types of requestors are
essentially DHCPv6 clients.  Thus, DHCPv6 authentication,
Section 21 of <xref target="RFC3315"/>, is an appropriate mechanism for securing
LEASEQUERY and LEASEQUERY-REPLY messages.  As the number of
leasequery requestors and servers in an administrative domain
is relatively small, any shared key distribution issues are
minimized.
</t>

<t>
After implementing the above approaches, the DHCPv6 server
should only be communicating with trusted LEASEQUERY
requestors, and so security needs should be met.
</t>

<t>
However, not all traffic originates directly from these
trusted requestors. For example, trusted relay agents can
relay LEASEQUERY messages from untrusted requestors or
elsewhere in the network.  This SHOULD be prevented at least at
the perimeter relay agents (or on all relay agents unless
relayed LEASEQUERY messages are required for some requestors).
DHCPv6 servers MAY be configured to discard relayed LEASEQUERY
messages or restrict relay chaining.
</t>

<t>
DHCPv6 servers SHOULD also provide for the ability to restrict
the information returned for a client in a LEASEQUERY-REPLY
even to a trusted LEASEQUERY requestor, as described in
<xref target="section.clientdata"/>.
</t>

<t>
Since even trusted access concentrators may generate LEASEQUERY
requests as a result of activity external to the access
concentrator, access concentrators SHOULD minimize potential
denial-of-service attacks on the DHCPv6 servers by minimizing
the generation of LEASEQUERY messages.  In particular, the
access concentrator SHOULD employ negative caching (i.e., cache
the fact that a particular recent query failed to return client
data) and address restrictions where possible (i.e., don't send
a LEASEQUERY message for addresses outside the range of the
attached broadband access networks).  Together, these
mechanisms limit the access concentrator to transmitting one
LEASEQUERY message (excluding message retries) per legitimate
broadband access network address after a reboot event.
</t>

<t>
Packet-flooding denial-of-service attacks can result in the
exhaustion of processing resources, thus preventing the server
from serving legitimate and regular DHCPv6 clients as well as
legitimate DHCPv6 LEASEQUERY requestors, denying configurations
to legitimate DHCPv6 clients as well lease information to
legitimate DHCPv6 LEASEQUERY requestors.  While these attacks
are unlikely when only communicating with trusted LEASEQUERY
requestors, the possibility always exists that the trust is
misplaced, security techniques are compromised, or even trusted
requestors can have bugs in them.  Therefore, techniques for
defending against packet-flooding denial of service are always
a good idea, and they include good perimeter security, as
mentioned earlier, and rate limiting DHCPv6 traffic by relay
agents, other network elements, or the server itself.
</t>

<t>
One way to attack an access concentrator (as opposed to a
DHCPv6 server) as a LEASEQUERY requestor is the establishment
of a malicious server with the intent of providing incorrect
lease or route information to the access concentrator,
thwarting source IPv6 address verification, and preventing
correct routing.  This type of attack can be minimized by using
IPsec as described in Section 21.1 of <xref target="RFC3315"/>.
</t>

</section>

<!-- ================================================================= -->

<section title="IANA Considerations" anchor="section.IANA">
<t>
IANA has assigned the following new DHCPv6 Message types in the
registry maintained in http://www.iana.org/assignments/dhcpv6-parameters:
</t>

<?rfc subcompact="yes"?>
<t>
<list>
<t>LEASEQUERY</t>
<t>LEASEQUERY-REPLY</t>
</list>
</t>

<t>
IANA has assigned the following new DHCPv6 Option Codes in the
registry maintained in http://www.iana.org/assignments/dhcpv6-parameters:
</t>

<t>
<list>
<t>OPTION_LQ_QUERY</t>
<t>OPTION_CLIENT_DATA</t>
<t>OPTION_CLT_TIME</t>
<t>OPTION_LQ_RELAY_DATA</t>
<t>OPTION_LQ_CLIENT_LINK</t>
</list>
</t>

<t>
IANA has assigned the following new DHCPv6 Status Codes in the
registry maintained in http://www.iana.org/assignments/dhcpv6-parameters:
</t>

<t>
<list>
<t>UnknownQueryType</t>
<t>MalformedQuery</t>
<t>NotConfigured</t>
<t>NotAllowed</t>
</list>
</t>
<?rfc subcompact="no"?>

<t>
IANA has created a new registry for the OPTION_LQ_QUERY option
query-type codes in the registry maintained in
http://www.iana.org/assignments/dhcpv6-parameters
with the following initial assignments:
</t>
<figure>
<artwork>
   QUERY_BY_ADDRESS       1
   QUERY_BY_CLIENTID      2
</artwork>
</figure>

<t>
New OPTION_LQ_QUERY option query-type codes are assigned through
Standards Action, as defined in <xref target="RFC2434"/>. 
</t>

</section>

<!-- ============================================================= -->

<section title="Acknowledgements">
<t>Thanks to Ralph Droms, Richard Johnson, Josh Littlefield, Hemant Singh,
Pak Siripunkaw, Markus Stenberg, and Ole Troan for their input, ideas, and
review during the production of this document.
</t>
</section>

<!-- ============================================================= -->

</middle>

<!-- ============================================================= -->

<back>

<?rfc needLines="10"?>

<references title="Normative References">

&rfc2119;
&rfc3315;
&rfc4388;
&rfc3633;

</references>
<references title="Informative References">

&rfc2131;
&rfc2434;
&rfc2461;
&rfc0826;
&rfc4301;

<reference anchor='I-D.ietf-dhc-dhcpv6-agentopt-delegate'>
<front>
<title>DHCPv6 Relay Agent Assignment Notification (RAAN) Option</title>

<author initials='R' surname='Droms' fullname='Ralph Droms'>
    <organization />
</author>

<date month='November' day='30' year='2006' />

<abstract><t>The DHCP Relay Agent Assignment Notification (RAAN) option is sent from a DHCP server to a DHCP relay agent to inform the relay agent of IPv6 addresses that have been assigned or IPv6 prefixes that have been delegated to DHCP clients.</t></abstract>

</front>

<seriesInfo name='Work' value='in Progress' />

</reference>


<reference anchor="DOCSIS3">
    <front>
    <title>Data-Over-Cable Service Interface Specifications: DOCSIS 3.0,
    MAC and Upper Layer Protocols Interface Specification,
    CM-SP-MULPIv3.0-I04-070518</title>
    <author initials="" surname="CableLabs"></author>
    <date month="May" year="2007, available at http://www.cablemodem.com/"></date>
    </front>
</reference>


<reference anchor="refs.bpi">
    <front>
    <title>Data-Over-Cable Service Interface Specifications: DOCSIS
    1.0 Baseline Privacy Interface Specification SCTE 22-2 2002
    </title>
    <author initials="" surname="SCTE Data Standards Subcommittee"></author>
    <date year="2002, available at http://www.scte.org/standards/"></date>
    </front>
</reference>

<reference anchor="refs.bpi+">
    <front>
    <title>Data-Over-Cable Service Interface Specifications: Baseline
    Privacy Plus Interface Specification CM-SP-BPI+_I12-050812</title>
    <author initials="" surname="CableLabs"></author>
    <date month="August" year="2005, available at http://www.cablemodem.com/"></date>
    </front>
</reference>

</references>
</back>

<vspace blankLines="100"/> <!-- page break to put addresses onto one page-->

</rfc>
