One document matched: draft-ietf-dhc-dhcpv4-active-leasequery-00.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!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 rfc4301 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4301.xml">
<!ENTITY rfc4388 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4388.xml">
<!ENTITY rfc6926 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6926.xml">
<!ENTITY rfc0951 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.0951.xml">
<!ENTITY rfc1542 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1542.xml">
<!ENTITY rfc2132 PUBLIC "" "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2132.xml">
]>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<rfc category="std" docName="draft-ietf-dhc-dhcpv4-active-leasequery-00.txt"
ipr="trust200902">
<front>
<title abbrev="Active DHCPv4 Lease Query">
Active DHCPv4 Lease Query</title>
<author fullname="Kim Kinnear" initials="K" surname="Kinnear">
<organization abbrev="Cisco Systems">Cisco Systems, Inc.</organization>
<address>
<postal>
<street>1414 Massachusetts Ave</street>
<city>Boxborough, MA 01719</city>
<region></region>
<code></code>
<country>USA</country>
</postal>
<email>kkinnear@cisco.com</email>
</address>
</author>
<author fullname="Mark Stapp" initials="M" surname="Stapp">
<organization abbrev="Cisco Systems">Cisco Systems, Inc.</organization>
<address>
<postal>
<street>1414 Massachusetts Ave</street>
<city>Boxborough, MA 01719</city>
<region></region>
<code></code>
<country>USA</country>
</postal>
<email>mjs@cisco.com</email>
</address>
</author>
<author fullname="Bernie Volz" initials="B" surname="Volz">
<organization abbrev="Cisco Systems">Cisco Systems, Inc.</organization>
<address>
<postal>
<street>1414 Massachusetts Ave</street>
<city>Boxborough, MA 01719</city>
<region></region>
<code></code>
<country>USA</country>
</postal>
<email>volz@cisco.com</email>
</address>
</author>
<author fullname="Neil Russell" initials="N" surname="Russell">
<organization abbrev="">Staples</organization>
<address>
<postal>
<street>500 Staples Drive</street>
<city>Framingham, MA 01702</city>
<region></region>
<code></code>
<country>USA</country>
</postal>
<email>neil.e.russell@gmail.com</email>
</address>
</author>
<date year="2013" />
<area>Internet</area>
<workgroup>Network Working Group</workgroup>
<!-- SECTION 0: Abstract -->
<abstract>
<t>
The Dynamic Host Configuration Protocol for IPv4 (DHCPv4) has been
extended with a Leasequery capability that allows a client to request
information about DHCPv4 bindings. That mechanism is limited to
queries for individual bindings. In some situations individual
binding queries may not be efficient, or even possible. In addition,
continuous update of an external client with Leasequery data is
sometimes desired. This document expands on the DHCPv4 Leasequery
protocol, and allows for active transfer of near real-time DHCPv4
address binding information data via TCP.
</t>
</abstract>
</front>
<middle>
<!-- SECTION 1: Introduction -->
<section title="Introduction">
<t>
The DHCPv4 Leasequery capability <xref target="RFC4388"/> extends the basic DHCPv4
capability <xref target="RFC2131"/> <xref target="RFC2132"/> to allow an external entity to query a
DHCPv4 server to recover lease state information about a particular
IP address or client in near real-time.
</t>
<t>
Requirements exist for external entities to keep up to date on the
correspondence between DHCPv4 clients and the IPv4 addresses for
which they have leases. These requirements often stem from
regulatory requirements placed on service providers by governmental
agencies.
</t>
<t>
These entities need to keep up with the current IPv4 address binding
activity of the DHCPv4 server. Keeping up with address binding
activity is termed "active" leasequery.
</t>
<t>
The DHCPv4 Bulk Leasequery <xref target="RFC6926"/> capability can be used to
recover useful information from a DHCPv4 server when some external
entity starts up. This entity could be one which is directly
involved in the DHCPv4 client - server transactions (e.g., a relay
agent), or it could be an external process which needs information
present in the DHCPv4 server's lease state database.
</t>
<t>
The Active Leasequery capability documented here is designed to allow
an entity not directly involved in DHCPv4 client - server
transactions to nevertheless keep current with the state of the
DHCPv4 lease state information in real-time.
</t>
</section>
<!-- SECTION 2: Terminology -->
<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>
This document uses the following terms:
<list style="symbols">
<t>"address binding"<vspace blankLines="1" />
The information that a DHCPv4 server keeps regarding the
relationship between a DHCPv4 client and an IPv4 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 IPv4 address.
</t>
<t>"Active Leasequery"<vspace blankLines="1" />
Keeping up to date in real-time (or near real-time) with DHCPv4
address binding activity.
</t>
<t>"Bulk Leasequery"<vspace blankLines="1" />
Requesting and receiving the existing DHCPv4 address binding
information in an efficient manner.
</t>
<t>"catch-up information, catch-up phase"<vspace blankLines="1" />
If a DHCPv4 Active Leasequery requestor sends in a query-start-
time option in a DHCPACTIVELEASEQUERY message, the DHCPv4 server
will attempt to send the requestor the information that changed
since the time specified in the query-start-time option. The
address binding information sent to satisfy this request is the
catch-up information, and the period while it is being sent is
the catch-up phase.
</t>
<t>"clock skew"<vspace blankLines="1" />
The difference between the absolute time on a DHCPv4 server and
the absolute time on the system where a requestor of an Active
or Bulk Leasequery is executing is termed the "clock skew" for
that Active or Bulk Leasequery connection. It is not absolutely
constant but is likely to vary only slowly. While it is easy to
think that this can be calculated precisely after one packet is
received by a requestor from a DHCPv4 server, a more accurate
value is derived from continuously examining the instantaneous
value developed from each packet received from a DHCPv4 server
and using it to make small adjustments to the existing value
held in the requestor.
</t>
<t>"DHCPv4 client"<vspace blankLines="1" />
A DHCPv4 client is an Internet host using DHCP to obtain
configuration parameters such as a network address.
</t>
<t>"DHCPv4 relay agent"<vspace blankLines="1" />
A DHCPv4 relay agent is a third-party agent that transfers BOOTP
and DHCPv4 messages between clients and servers residing on
different subnets, per <xref target="RFC0951"/> and <xref target="RFC1542"/>.
</t>
<t>"DHCPv4 server"<vspace blankLines="1" />
A DHCPv4 server is an Internet host that returns configuration
parameters to DHCPv4 clients.
</t>
<t>"IP address binding"<vspace blankLines="1" />
The information that a DHCPv4 server keeps regarding the
relationship between a DHCPv4 client and an IPv4 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 IPv4 address.
</t>
<t>"MAC address"<vspace blankLines="1" />
In the context of a DHCP message, a MAC address consists of the
fields: hardware type "htype", hardware length "hlen", and
client hardware address "chaddr".
</t>
</list>
</t>
</section>
<!-- Terminology -->
<!-- SECTION 3: Protocol Overview -->
<section title="Protocol Overview">
<t>
The Active Leasequery mechanism is modeled on the existing individual
Leasequery protocol in <xref target="RFC4388"/> as well as related work on DHCPv4
Bulk Leasequery <xref target="RFC6926"/>; most differences arise from the long term
nature of the TCP connection required for Active Leasequery. In
addition, a DHCPv4 server which supports Active Leasequery MUST
support Bulk Leasequery <xref target="RFC6926"/> as well.
</t>
<t>
An Active Leasequery client opens a TCP connection to a DHCPv4
Server, using the DHCPv4 port 67. Note that this implies that the
Leasequery client 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 for Active Leasequery
is specified.
</t>
<t>
After establishing a connection, the client sends an
DHCPACTIVELEASEQUERY message over the connection. In response, the
server sends updates to the requestor using DHCPLEASEACTIVE and
DHCPLEASEUNASSIGNED messages which are extensions of these messages
as defined in <xref target="RFC4388"/> and <xref target="RFC6926"/>.
</t>
<t>
Active Leasequery is designed to provide continuous updates of DHCPv4
IPv4 address binding activity to an external entity.
</t>
<t>
Active Leasequery has features which allow this external entity to
lose its connection and then reconnect and receive the latest
information concerning any IP addresses changed while it was not
connected.
</t>
<t>
These capabilities are designed to allow the Active Leasequery
requestor to efficiently become current with respect to the lease
state database after it has been restarted or the machine on which it
is running has been reinitialized. It is easy to define a protocol
which works when the requestor is always connected to the DHCPv4
server. Since that isn't sufficiently robust, much of the mechanism
in this document is designed to deal efficiently with situations that
occur when the Active Leasequery requestor becomes disconnected from
the DHCPv4 server from which it is receiving updates and then becomes
reconnected to that server.
</t>
<t>
Central to this approach, if the Active Leasequery requestor loses
service, it is allowed to specify the time of its most recent update
in a subsequent Active Leasequery request and the DHCPv4 server will
determine whether or not data was missed while the Active Leasequery
requestor was not connected.
</t>
<t>
The DHCP server processing the Active Leasequery request may limit
the amount of data saved, and methods exist for the DHCPv4 server to
inform the Active Leasequery requestor that more data was missed than
could be saved. In this situation, the Active Leasequery requestor
would issue a Bulk Leasequery <xref target="RFC6926"/> to recover information not
available through an Active Leasequery.
</t>
<t>
DHCPv4 servers are not required to keep any data corresponding to
data missed on a Active Leasequery connection, but will typically
choose to keep data corresponding to some recent activity available
for subsequent queries by a DHCPv4 Active Leasequery client whose
connection was temporarily interrupted.
</t>
<t>
An Active Leasequery requestor would typically use Bulk Leasequery to
initialize its database with all current data when that database
contains no address binding information. In addition, it would use
Bulk Leasequery to recover missed information in the event that its
connection with the DHCPv4 server was lost for a longer time than the
DHCPv4 server would keep track of the specific changes to the IP
address binding information.
</t>
<t>
The messages sent by the server in response to an Active Leasequery
request SHOULD be identical to the messages sent by the server to a
Bulk Leasequery request regarding the way the data is encoded into
the Active Leasequery responses. In addition, the actions taken by
the Active Leasequery requestor to interpret the responses to an
Active Leasequery request SHOULD be identical to the way that the
requestor interprets the responses to a Bulk Leasequery request.
Thus, the handling of time, clock skew, data source, and other items
discussed in the Bulk Leasequery specification <xref target="RFC6926"/> are to be
followed when implementing Active Leasequery.
</t>
</section>
<!-- SECTION 4: Interaction Between Active Leasequery and Bulk Leasequery -->
<section title="Interaction Between Active Leasequery and Bulk Leasequery">
<t>
Active Leasequery can be seen as an extension of the Bulk Leasequery
protocol <xref target="RFC6926"/>. The contents of packets returned to an Active
Leasequery requestor are identical to that defined for the Bulk
Leasequery protocol.
</t>
<t>
Applications which employ Active Leasequery to keep a database up to
date with respect to the DHCPv4 server's lease state database will
usually use an initial Bulk Leasequery to bring their database into
equivalence with that of the DHCPv4 server, and then use Active
Leasequery to keep that database current with respect to the DHCPv4
server's lease state database.
</t>
<t>
There are several differences between the Active and Bulk Leasequery
protocols. Active Leasequery defines only one qualifier (the query-
start-time) and no query types, while Bulk Leasequery defines several
query types and qualifiers. An Active Leasequery connection sends
all available updates to the requestor.
</t>
<t>
An Active Leasequery connection does not ever "complete", though the
DHCPv4 server may drop the connection for a variety of reasons
associated with some sort of exception condition.
</t>
</section>
<!-- SECTION 5: Message and Option Definitions -->
<section title="Message and Option Definitions">
<section title="Message Framing for TCP">
<t>
The use of TCP for the Active Leasequery protocol permits one or more
DHCPv4 messages to be sent at a time. The receiver needs to be able
to determine how large each message is. The same framing technique
used for Bulk Leasequery <xref target="RFC6926"/> is used for Active Leasequery.
</t>
<t>
Two octets containing the message size in network byte-order are
prepended to each DHCPv4 message sent on an Active Leasequery TCP
connection. The two message-size octets 'frame' each DHCPv4 message.
</t>
<t>
DHCPv4 message framed for TCP:
</t>
<figure title="Format of a DHCPv4 message in TCP">
<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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| message-size | op (1) | htype (1) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| hlen (1) | hops (1) | .... |
+---------------+---------------+ +
| |
. remainder of DHCPv4 message, .
. from Figure 1 of [RFC2131] .
. .
. (variable) .
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
</artwork>
</figure>
<t>
<list hangIndent="20" style="hanging">
<t hangText=" message-size">
the number of octets in the message that
follows, as a 16-bit integer in network
byte-order.
</t>
<t hangText=" All other fields are as specified in DHCPv4">
<xref target="RFC2131"/>.
</t>
</list>
</t>
<t>
The intent in using this format is that code which currently knows
how to deal with a message returned from DHCPv4 Leasequery <xref target="RFC4388"/>
will be able to deal with the message held inside of the TCP framing.
</t>
</section>
<section title="New or Changed Options">
<t>
The existing messages DHCPLEASEUNASSIGNED and DHCPLEASEACTIVE are
used as the value of the dhcp-message-type option to indicate an IP
address which is currently not leased or currently leased to a DHCPv4
client, respectively.
</t>
<t>
All of the message types and options defined for Bulk Leasequery
<xref target="RFC6926"/> are also used by Active Leasequery. In addition, new
message types and option types are defined for Active Leasequery, as
described below.
</t>
<section title="dhcp-message-type">
<t>
The message type option (option 53) from <xref target="RFC2132"/> requires
additional values. The values of these message types are shown below
in an extension of the table from Section 9.6 of <xref target="RFC2132"/>:
</t>
<texttable>
<ttcol>Value</ttcol>
<ttcol>Message Type</ttcol>
<c>TBD1</c>
<c>DHCPACTIVELEASEQUERY</c>
<c>TBD2</c>
<c>DHCPLEASEQUERYSTATUS</c>
</texttable>
</section>
<section title="dhcp-status-code">
<t>
The dhcp-status-code option defined in <xref target="RFC6926"/> allows greater
detail to be returned regarding the status of a DHCP request. While
specified in the Bulk Leasequery document, this DHCPv4 option is also
used in Active Leasequery.
</t>
<t>
This option has two possible scopes when used with Active Leasequery,
depending on the context in which it appears. It refers to the
information in a single leasequery reply if the value of the dhcp-
message-type is DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED. It refers to
the message stream related to an entire request if the value of the
dhcp-message-type is DHCPLEASEQUERYSTATUS.
</t>
<t>
Additional status codes defined for support of Active Leasequery are:
</t>
<texttable>
<ttcol>Name</ttcol>
<ttcol>status-code</ttcol>
<ttcol>Description</ttcol>
<c>DataMissing</c>
<c>TBD3</c>
<c>Indicates that IP address binding information requested is
not available.</c>
<c>ConnectionActive</c>
<c>TBD4</c>
<c>Indicates that this connection remains active.</c>
<c>CatchUpComplete</c>
<c>TBD5</c>
<c>Indicates that this Active Leasequery connection has
completed sending all of the saved data requested.</c>
</texttable>
<t>
A dhcp-status-code option MAY appear in the options field of a DHCP
message. If the dhcp-status-code option does not appear, it is
assumed that the operation was successful. The dhcp-status-code
option SHOULD NOT appear in a message which is successful unless it
is needed to convey some text message along with the Success status
code.
</t>
</section>
</section>
<section title="Connection and Transmission Parameters">
<t>
DHCPv4 servers that support Active 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.
</t>
<t>
This section presents a table of values used to control Active
Leasequery behavior, including recommended defaults. Implementations
MAY make these values configurable. However, configuring too-small
timeout values may lead to harmful behavior both to this application
as well as to other traffic in the network. As a result, timeout
values smaller than the default values SHOULD NOT be used.
</t>
<texttable>
<ttcol>Parameter</ttcol>
<ttcol>Default</ttcol>
<ttcol>Description</ttcol>
<c>BULK_LQ_DATA_TIMEOUT</c>
<c>300 secs</c>
<c>Bulk Leasequery data timeout</c>
<c>BULK_LQ_MAX_CONNS</c>
<c>10</c>
<c>Max Bulk Leasequery TCP connections</c>
<c>ACTIVE_LQ_RCV_TIMEOUT</c>
<c>120 secs</c>
<c>Active Leasequery receive timeout</c>
<c>ACTIVE_LQ_SEND_TIMEOUT</c>
<c>120 secs</c>
<c>Active Leasequery send timeout</c>
<c>ACTIVE_LQ_IDLE_TIMEOUT</c>
<c>60 secs</c>
<c>Active Leasequery idle timeout</c>
</texttable>
</section>
</section>
<section title="Information Communicated by Active Leasequery">
<t>
While the information communicated by a Bulk Leasequery <xref target="RFC6926"/> is
taken directly from the DHCPv4 server's lease state database, the
information communicated by an Active Leasequery is real-time
information. As such, it is the information which is currently
associated with a particular IP address in the DHCPv4 server's lease
state database.
</t>
<t>
This is of significance, because if the Active Leasequery requestor
runs slowly or the requestor disconnects from the DHCPv4 server and
then reconnects with a query-start-time (signaling a catch-up
operation), the information communicated to the Active Leasequery
requestor is only the most current information from the DHCPv4
server's lease state database.
</t>
<t>
The requestor of an Active Leasequery MUST NOT assume that every
lease state change is communicated across an Active Leasequery
connection. Even if the Active Leasequery requestor remains
connected, the DHCPv4 server is only required to transmit information
about an IP address that is current when the packet is created and
handed off to the TCP stack to send to the requestor.
</t>
<t>
If the TCP connection blocks and the DHCPv4 server is waiting to send
information down the connection, when the connection becomes
available to be written the DHCPv4 server MAY create the packet to
send at this time. The current state of the IP address will be sent,
and any transition in state or other information that occurred while
the TCP connection was blocked will be lost.
</t>
<t>
Thus, the Active Leasequery protocol does not allow the requestor to
build a complete history of every activity on every lease. An
effective history of the important state changes for a lease can be
created if the parameters of the DHCPv4 server are tuned to take into
account the requirements of an Active Leasequery requestor. For
instance, the period after the expiration or release of an IP address
could be configured long enough (say several minutes, well more than
the receive timeout), so that an Active Leasequery requestor would
never miss any changes in the client to IP address binding.
</t>
</section>
<section title="Requestor Behavior">
<section title="Connecting and General Processing">
<t>
A Requestor attempts to establish a TCP connection to a DHCPv4 Server
in order to initiate a Leasequery exchange. If the attempt fails,
the Requestor MAY retry.
</t>
<t>
If an Active Leasequery is terminated prematurely by a
DHCPLEASEQUERYDONE with a dhcp-message status-code of QueryTerminated
or by the failure of the connection over which it was being
submitted, the requestor MAY retry the request after the creation of
a new connection.
</t>
<t>
Messages from the DHCPv4 server come as multiple responses to a
single DHCPACTIVELEASEQUERY message. Thus, each DHCPACTIVELEASEQUERY
or DHCPBULKLEASEQUERY request MUST have an xid (transaction-id)
unique on the connection on which it is sent, and all of the messages
which come as a response to it all contain the same xid as the
request. It is the xid which allows the data-streams of two or more
different DHCPACTIVELEASEQUERY or DHCPBULKLEASEQUERY requests to be
demultiplexed by the requestor.
</t>
<t>
A requestor MAY send a DHCPACTIVELEASEQUERY request to a DHCPv4
server and immediately close the transmission side of its TCP
connection, and then read the resulting response messages from the
DHCPv4 server. This is not required, and the usual approach is to
leave both sides of the TCP connection up until at least the
conclusion of the Active Leasequery.
</t>
</section>
<section title="Forming an Active Leasequery">
<t>
The Active Leasequery is designed to create a long lived connection
between the requestor and the DHCPv4 server processing the active
query. The DHCPv4 server will send IPv4 address binding information
back across this connection with minimal delay after it learns of the
binding information. It will learn about IPv4 address bindings
either because it makes the bindings itself or because it has
received information about a binding from another server.
</t>
<t>
To form the Active query, a DHCPv4 request is constructed with a
dhcp-message-type of DHCPACTIVELEASEQUERY. This DHCPv4 request MUST
NOT have a ciaddr, a chaddr, or a dhcp-client-identifier. The DHCPv4
request MUST contain a transaction-id, and that transaction-id MUST
be locally unique to the TCP connection to the DHCPv4 server. The
DHCPv4 request SHOULD have a dhcp-parameter-request-list to inform
the DHCPv4 server which DHCPv4 options are of interest to the
requestor sending the DHCPACTIVELEASEQUERY message.
</t>
<t>
An important capability of the Active Leasequery is the ability of
the requestor to specify that some recent data be sent immediately to
the requestor in parallel with the transmission of the ongoing IPv4
address binding information in more or less real time. This
capability is used in order to allow an Active Leasequery requestor
to recover missed information in the event that it temporarily loses
connectivity with the DHCPv4 server processing a previous Active
Leasequery.
</t>
<t>
Note that until all of the recent data (catch-up data) has been
received, the requestor MUST NOT keep track of the base time received
in Leasequery reply messages to use later in a subsequent Bulk
Leasequery or Active Leasequery request.
</t>
<t>
This capability is enabled by the transmission of a 4 octet base-time
option with each Leasequery reply sent as the result of a previous
Active Leasequery. The requestor will typically keep track of the
highest base-time received from a particular DHCPv4 server over an
Active Leasequery connection, and in the event that the requestor
finds it necessary (for whatever reason) to reestablish an Active
Leasequery connection to that DHCPv4 server, the requestor will place
this highest base-time value into a query-start-time option in the
new DHCPACTIVELEASEQUERY request.
</t>
<t>
If the requestor doesn't wish to request an update of information
missed when it was not connected to the DHCPv4 server, then it does
not include the query-start-time option in the DHCPACTIVELEASEQUERY
request.
</t>
<t>
If the TCP connection becomes blocked or stops being writable 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 to allow requestors to control the period of time they
are willing to wait before abandoning a connection, independent of
notifications from the TCP implementations they may be using.
</t>
</section>
<section title="Processing Active Replies">
<t>
The Requestor attempts to read a DHCPv4 leasequery reply message from
the TCP connection. If the stream of replies becomes blocked, the
Requestor SHOULD be prepared to terminate the connection after
ACTIVE_LQ_RCV_TIMEOUT, and MAY begin retry processing if configured
to do so.
</t>
<t>
Note that a DHCPACTIVELEASEQUERY request specifically requests the
DHCPv4 server to create a long-lived connection which may not have
data transferring continuously during its lifetime. Therefore the
DHCPv4 server will send a DHCPLEASEQUERYSTATUS message with a dhcp-
status-code of ConnectionActive every ACTIVE_LQ_IDLE_TIMEOUT seconds
(default 60) in order for the requestor to know that the connection
remains alive. Note that the default for ACTIVE_LQ_RCV_TIMEOUT is
120 seconds, twice the value of the ACTIVE_LQ_IDLE_TIMEOUT's default
of 60 seconds which drives the DHCPv4 server to send messages. Thus
ACTIVE_LQ_RCV_TIMEOUT controls how sensitive the requestor is to be
to delays by the DHCPv4 server in sending updates or
DHCPLEASEQUERYSTATUS messages.
</t>
<t>
A successful query that is returning binding data MUST include a
non-zero ciaddr. It may also include a non-zero chaddr, htype, and
hlen as well as additional options. If there are additional bindings
to be returned, they will be carried in additional Active Leasequery
messages.
</t>
<t>
Any requestor of an Active Leasequery operation MUST be prepared to
receive multiple copies of the IPv4 address binding information for a
particular IPv4 address. See the Bulk Leasequery document <xref target="RFC6926"/>
for information on how to deal with this situation.
</t>
<t>
A single Active Leasequery can and usually will result in a large
number of replies. The Requestor MUST be prepared to receive more
than one reply with transaction-ids matching a single
DHCPACTIVELEASEQUERY message from a single DHCPv4 server.
</t>
<t>
A DHCPACTIVELEASEQUERY has two regimes -- during the catch-up phase,
if any, and after any catch-up phase. During the catch-up phase (if
one exists), the data returned in the base-time option in a
DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message may appear to be
ordered, but the most recent change in the lease state data being
returned is not related to the base-time option value in the
messages. Another way to say this is that the ordering of the
updates sent by the DHCPv4 server during the catch-up phase is
independent of the ordering in the changes in the lease state data.
The base-time option from messages during this phase MUST NOT be
saved and used in a subsequent DHCPACTIVELEASEQUERY message's query-
start-time option as it does not represent the extent of progress of
the catch-up activity.
</t>
<t>
After the catch-up phase, or during the entire series of messages
received as the response to a DHCPACTIVELEASEQUERY request with no
query-start-time (and therefore no catch-up phase), the base-time
option of the most recent message SHOULD be saved as a record of the
most recent time that data was received. This base-time (in the
context of the DHCPv4 server) can be used in a subsequent
DHCPACTIVELEASEQUERY message's query-start-time, or in a
DHCPBULKLEASEQUERY message's query-start-time if one is required,
after a loss of the Active Leasequery connection.
</t>
<t>
The DHCPLEASEQUERYSTATUS message MAY unilaterally terminate a
successful DHCPACTIVELEASEQUERY request which is currently in
progress in the event that the DHCPv4 server determines that it
cannot continue processing a DHCPACTIVELEASEQUERY request. For
example, when a server is requested to shut down it SHOULD send a
DHCPLEASEQUERYSTATUS message with a dhcp-status-code of
QueryTerminated and include in the message a base time. This SHOULD
be the last message on that connection, and once the message has been
transmistted, the server should close the connection.
</t>
<t>
After receiving DHCPLEASEQUERYSTATUS with a QueryTerminated status
from a server, the Requestor MAY close the TCP connection to that
server.
</t>
<t>
The DHCPv4 Leasequery protocol uses the associated-ip option as an
indicator that multiple bindings were present in response to a single
client based query. For Active Leasequery, client-based queries are
not supported and so the associated-ip option is not used, and MUST
NOT be present in replies.
</t>
<section title="Processing Replies from a Request Containing a query-start-time">
<t>
If the DHCPACTIVELEASEQUERY was requested with a query-start-time,
the DHCPv4 server will attempt to send information about all IP
address bindings that changed since the time specified in the query-
start-time. This is the catch-up phase of the DHCPACTIVELEASEQUERY
processing. The DHCPv4 server MAY also begin immediate updates over
the same connection of real-time IP address binding information
changes. Thus, the catch-up phase may run in parallel with the
normal updates generated by the DHCPACTIVELEASEQUERY request.
</t>
<t>
A DHCPv4 server MAY keep only a limited amount of time ordered
information available to respond to a DHCPACTIVELEASEQUERY request
containing a query-start-time. Thus, it is possible that the time
specified in the query-start-time represents a time not covered by
the time ordered information kept by the DHCPv4 server. If this
should occur, and there is not enough data saved in the DHCPv4 server
to satisfy the request specified by the query-start-time option, the
DHCPv4 server will reply immediately with a DHCPLEASEQUERYSTATUS
message with a dhcp-status-code of DataMissing with a base-time
option equal to the server's current time. This will signal the end
of the catch-up phase, and the only updates that will subsequently be
received on this connection are the real-time updates from the
DHCPACTIVELEASEQUERY request.
</t>
<t>
If there is enough data saved to satisfy the request, then
DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED messages will begin arrive
from the DHCPv4 server. Some of these messages will be related to
the query-start-time request and be part of the catch-up phase. Some
of these messages will be real-time updates of IP address binding
changes taking place in the DHCPv4 server. In general, there is no
way to determine the source each message.
</t>
<t>
Until the catch-up phase is complete, the latest base-time value
received from a DHCPv4 server processing an Active Leasequery request
cannot be reset from the incoming messages because to do so would
compromise the ability to recover lost information if the
DHCPACTIVELEASEQUERY were to terminate prior to the completion of the
catch-up phase.
</t>
<t>
The requestor will know that the catch-up phase is complete because
the DHCPv4 server will transmit a DHCPLEASEQUERYSTATUS message with
the dhcp-status-code of CatchUpComplete. Once this message is
transmitted, all additional DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED
messages will relate to real-time ("new") IP address binding changes
in the DHCPv4 server.
</t>
<t>
As discussed in Section 6.3, the requestor SHOULD keep track of the
latest base-time option value received over a particular connection,
to be used in a subsequent DHCPACTIVELEASEQUERY request -- but only
if the catch-up phase is complete. Prior to the completion of the
catch-up phase, if the connection should go away or if the requestor
receives a DHCPLEASEQUERYDONE message, then when it reconnects it
MUST use the base-time value from the previous connection and not any
base-time value received from the recently closed connection.
</t>
<t>
In the event that there was enough data available to the DHCPv4
server to begin to satisfy the request implied by the query-start-
time option, but during the processing of that data the server found
that it was unable to continue (perhaps there was barely enough, the
connection is very slow, and the aging algorithm causes the saved
data to become unavailable) the DHCPv4 server will terminate the
catch-up phase of processing immediately by sending a
DHCPLEASEQUERYSTATUS message with a dhcp-status-code of DataMissing
and with a base-time option of the current time.
</t>
<t>
The requestor MUST NOT assume that every individual state change of
every IP address during the period from the time specified in the
query-start-time and the present is replicated in an Active
Leasequery reply message. The requestor MAY assume that at least one
Active Leasequery reply message will exist for every IP address which
had one or more changes of state during the period specified by the
query-start-time and the current time. The last message for each IP
address will contain the state at the current time, and there may be
one or more messages concerning a single IP address during the
catch-up phase of processing.
</t>
<t>
If an IP address changed state multiple times during the time that
the requestor was not connected (that is, during the time from the
query-start-time and the present), then only the current IP address
binding information will be sent during the catch-up phase. Thus,
the requestor MUST NOT assume that every intermediate state change
that occurred during the period from the query-start-time to the
present will be represented by an individual Leasequery message.
</t>
<t>
If the DHCPLEASEQUERYSTATUS message containing a dhcp-status-code of
DataMissing is received and the requestor is interested in keeping
its database up to date with respect to the current state of IP
address bindings in the DHCPv4 server, then the requestor SHOULD
issue a DHCPBULKLEASEQUERY request to recover the information missing
from its database. This DHCPBULKLEASEQUERY should include a query-
start-time, set to be the same as its query-start-time previously
included in the DHCPACTIVELEASEQUERY responses from the DHCPv4
server, and a query-end-time equal to the base-time returned by the
DHCPv4 server in the DHCPLEASEQUERYSTATUS message with the dhcp-
status-code of DataMissing.
</t>
<t>
In the event that the requestor receives a DHCPLEASEQUERYSTATUS
message with a dhcp-status-code of DataMissing, it is a reasonable
assumption that it is interested in keeping its database up to date
with respect to the DHCPv4 server's internal IP address binding
database or it would not have included the query-start-time in the
DHCPACTIVELEASEQUERY message.
</t>
<t>
Typically, the requestor would have one connection open to a DHCPv4
server for a DHCPACTIVELEASEQUERY request and possibly one additional
connection open for a DHCPBULKLEASEQUERY request to the same DHCPv4
server to fill in the data that might have been missed prior to the
initiation of the DHCPACTIVELEASEQUERY. The Bulk Leasequery
connection would typically run to completion and be closed, leaving
one Active Leasequery connection open to a single DHCPv4 server.
Alternatively, both requests could be issued over a single
connection.
</t>
</section>
</section>
<section title="Closing Connections">
<t>
The Requestor or DHCPv4 leasequery server MAY close its end of the
TCP connection at any time. The Requestor MAY choose to retain the
connection if it intends to issue additional queries. Note that this
client behavior does not guarantee that the connection will be
available for additional queries: the server might decide to close
the connection based on its own configuration.
</t>
</section>
</section>
<section title="Server Behavior">
<t>
A DHCPv4 server which supports Active Leasequery MUST support Bulk
Leasequery <xref target="RFC6926"/> as well.
</t>
<section title="Accepting Connections">
<t>
Servers that implement DHCPv4 Active Leasequery listen for incoming
TCP connections. Port numbers are discussed in Section 5.3. Servers
MUST be able to limit the number of currently accepted and active
connections. The value BULK_LQ_MAX_CONNS MUST be the default;
implementations MAY permit the value to be configurable. Connections
SHOULD be accepted and, if the number of connections is over
BULK_LQ_MAX_CONNS, they SHOULD be closed immediately.
</t>
<t>
Servers MAY restrict Active Leasequery connections and
DHCPACTIVELEASEQUERY messages to certain clients. Connections not
from permitted clients SHOULD be closed immediately, to avoid server
connection resource exhaustion.
</t>
<t>
If the TCP connection becomes blocked while the server is accepting a
connection or reading a query, it SHOULD be prepared to terminate the
connection after a BULK_LQ_DATA_TIMEOUT. We make this recommendation
to allow servers to control the period of time they are willing to
wait before abandoning an inactive connection, independent of the TCP
implementations they may be using.
</t>
</section>
<section title="Replying to an Active Leasequery">
<t>
If the connection becomes blocked while the server is attempting to
send reply messages, the server SHOULD be prepared to terminate the
TCP connection after ACTIVE_LQ_SEND_TIMEOUT. This timeout governs how
much congestion the DHCPv4 server is prepared to tolerate over any
Active Leasequery connection. The default is two minutes, which means
that if more than two minutes goes by without the requestor reading
enough information to unblock the TCP connection, the DHCPv4 server
will drop the TCP connection.
</t>
<t>
If the DHCPv4 server encounters an error during processing of the
DHCPACTIVELEASEQUERY message, either during initial processing or
later during the message processing, it SHOULD send a
DHCPLEASEQUERYSTATUS containing an error code of some kind in a
dhcp-status-code option. It SHOULD close the connection after this
error is signaled.
</t>
<t>
Every reply to a DHCPACTIVELEASEQUERY request MUST contain the
information specified in replies to a DHCPBULKLEASEQUERY request
<xref target="RFC6926"/>.
</t>
<t>
If a DHCPACTIVELEASEQUERY request contains a query-start-time option,
it indicates that the requestor would like the DHCPv4 server to send
it not only messages that correspond to DHCPv4 address binding
activity that occurs subsequent to the receipt of the DHCPLEASEACTIVE
request, but also messages that correspond to DHCPv4 address binding
activity that occurred prior to the DHCPACTIVELEASEQUERY request.
</t>
<t>
If a query-end-time option appears in a DHCPACTIVELEASEQUERY the
DHCPv4 server should send a DHCPLEASEQUERYSTATUS message with a
dhcp-status-code of MalformedQuery and terminate the connection.
</t>
<t>
In order to implement a meaningful response to this query, the DHCPv4
server MAY keep track of the address binding activity and associate
changes with particular base-time values from the messages. Then,
when requested to do so by a DHCPACTIVELEASEQUERY request containing
a query-start-time option, the DHCPv4 server can respond with replies
for all address binding activity occurring on that query-start-time
or later times.
</t>
<t>
These replies based on the query-start-time MAY be interleaved with
the messages generated due to current IP address binding activity.
</t>
<t>
Once the transmission of the DHCPv4 Leasequery messages associated
with the query-start-time option are complete, a DHCPLEASEQUERYSTATUS
message MUST be sent with a dhcp-status-code value of
CatchUpComplete.
</t>
<t>
The DHCPv4 server SHOULD keep track of a limited amount of previous
address binding activity and associate it with base-time values. The
DHCPv4 server MAY choose to only do this in the event that it has
received at least one DHCPACTIVELEASEQUERY request in the past, as to
do so will almost certainly entail some utilization of resources
which would be wasted if there are no DHCPACTIVELEASEQUERY clients
for this DHCPv4 server. The DHCPv4 server SHOULD make the amount of
previous address binding activity it retains configurable. There is
no requirement on the DHCPv4 server to retain this information over a
server restart (or even to retain such information at all).
</t>
<t>
Unless there is an error or some requirement to cease processing a
DHCPACTIVELEASEQUERY request yielding a DHCPLEASEQUERYSTATUS message,
such as a server shutdown, there will be no DHCPLEASEQUERYSTATUS
message at the conclusion of the DHCPACTIVELEASEQUERY processing
because that processing will not conclude but will continue until
either the client or the server drops the connection.
</t>
</section>
<section title="Multiple or Parallel Queries">
<t>
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. A server MUST NOT read
more query messages from a connection than it is prepared to process
simultaneously.
</t>
<t>
Typically, a requestor of a Active Leasequery would not need to send
a second Active Leasequery while the first is still active. However,
sending an Active Leasequery and a Bulk Leasequery over the same
connection would be possible and reasonable.
</t>
<t>
This MAY be a feature that is administratively controlled. Servers
that are able to process queries in parallel SHOULD offer
configuration that limits the number of simultaneous queries
permitted from any one requestor, in order to control resource use if
there are multiple requestors seeking service.
</t>
</section>
<section title="Closing Connections">
<t>
The server MAY close its end of the TCP connection after sending its
last message, a DHCPLEASEQUERYSTATUS message in response to a query.
Alternatively, the server MAY retain the connection and wait for
additional queries from the client. The server SHOULD be prepared to
limit the number of connections it maintains, and SHOULD be prepared
to close idle connections to enforce the limit.
</t>
<t>
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 clients by using the QueryTerminated
status code in the dhcp-status-code option in a DHCPLEASEQUERYSTATUS
message. 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.
</t>
</section>
</section>
<section title="Security Considerations">
<t>
The "Security Considerations" section of <xref target="RFC2131"/> details the
general threats to DHCPv4. The DHCPv4 Leasequery specification
<xref target="RFC4388"/> describes recommendations for the Leasequery protocol,
especially with regard to relayed LEASEQUERY messages, mitigation of
packet-flooding DOS attacks, restriction to trusted clients, and use
of IPsec <xref target="RFC4301"/>.
</t>
<t>
The use of TCP introduces some additional concerns. Attacks that
attempt to exhaust the DHCPv4 server's available TCP connection
resources, such as SYN flooding attacks, can compromise the ability
of legitimate clients to receive service. Malicious clients who
succeed in establishing connections, but who then send invalid
queries, partial queries, or no queries at all also can 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.
</t>
</section>
<section title="IANA Considerations">
<t>
IANA is requested to assign the following new DHCP message types from
the registry "DHCP Message Type 53 Values" maintained at
http://www.iana.org/assignments/bootp-dhcp-parameters:
<list style="numbers">
<t>A dhcp-message-type of TBD1 for DHCPACTIVELEASEQUERY.</t>
<t>A dhcp-message-type of TBD2 for DHCPLEASEQUERYSTATUS.</t>
</list>
</t>
<t>
IANA is requested to assign the following new DHCP status codes from
the registry "DHCP Status Code Type 151 Values" maintained at
http://www.iana.org/assignments/bootp-dhcp-parameters:
</t>
<texttable>
<ttcol>Name</ttcol>
<ttcol>status-code</ttcol>
<c>DataMissing</c>
<c>TBD3</c>
<c>ConnectionActive</c>
<c>TBD4</c>
<c>CatchUpComplete</c>
<c>TBD5</c>
</texttable>
</section>
<!-- SECTION 11: Acknowledgements -->
<section title="Acknowledgements">
<t>
The ideas in this document came in part from work in DHCPv6 and
DHCPv4 Bulk Leasequery as well as from in depth discussions between
the authors.
</t>
</section>
</middle>
<back>
<!-- SECTION 12.1: Normative References -->
<references title="Normative References">
&rfc2119;
&rfc2131;
&rfc4301;
&rfc4388;
&rfc6926;
</references>
<!-- SECTION 12.2: Informative References -->
<references title="Informative References">
&rfc0951;
&rfc1542;
&rfc2132;
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 21:50:51 |