DHC Working Group Kim Kinnear
Internet Draft Bernie Volz
Intended Status: Standards Track Neil Russell
Expires: January 7, 2009 Mark Stapp
Cisco Systems
July 7, 2008
Bulk DHCPv4 Lease Query
<draft-kinnear-dhc-dhcpv4-bulk-leasequery-00.txt>
Status of this Memo
By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on January 7, 2009
Copyright Notice
Copyright (C) The IETF Trust (2008).
Abstract
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. This
document expands on the DHCPv4 Leasequery protocol to allow for bulk
Kinnear Expires December 2008 [Page 1]
Internet Draft Bulk DHCPv4 Lease Query July 2008
transfer of DHCPv4 address binding data via TCP.
Table of Contents
1. Introduction................................................. 2
2. Terminology.................................................. 3
3. Protocol Overview............................................ 5
4. Interaction Between UDP Leasequery and Bulk Leasequery....... 5
5. Message and Option Definitions............................... 6
5.1. Message Framing for TCP.................................... 6
5.2. New or Changed Options..................................... 7
5.3. Connection and Transmission Parameters..................... 13
6. Requestor Behavior........................................... 14
6.1. Connecting and General Processing.......................... 14
6.2. Forming a Bulk Leasequery.................................. 15
6.3. Processing Bulk Replies.................................... 16
6.4. Processing Time Values in Leasequery messages.............. 16
6.5. Making Sense Out of Multiple Responses Concerning a Single. 18
6.6. Querying Multiple Servers.................................. 19
6.7. Closing Connections........................................ 19
7. Server Behavior.............................................. 19
7.1. Accepting Connections...................................... 20
7.2. Replying to a Bulk Leasequery.............................. 20
7.3. Building a Single Reply for Bulk Leasequery................ 21
7.4. Multiple or Parallel Queries............................... 22
7.5. Closing Connections........................................ 22
8. Security Considerations...................................... 23
9. IANA Considerations.......................................... 23
10. Acknowledgements............................................ 24
11. References.................................................. 24
11.1. Normative References...................................... 24
11.2. Informative References.................................... 25
12. Authors' Addresses.......................................... 25
13. Full Copyright Statement.................................... 26
14. Intellectual Property....................................... 27
15. Acknowledgment.............................................. 27
1. Introduction
The DHCPv4 Leasequery capability [RFC4388] extends the basic DHCPv4
capability [RFC2131] [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.
Sometimes relay agents need to learn all of the DHCPv4 address
binding information contained in a DHCPv4 server in an efficient
Kinnear Expires December 2008 [Page 2]
Internet Draft Bulk DHCPv4 Lease Query July 2008
manner. This can occur after a DHCPv4 relay agent has lost the
information it collected by watching DHCPv4 messages it has relayed.
In other cases, an external entity may need to update itself with
information from the DHCPv4 server's IP address binding database
without knowledge of the particular IP addresses managed by the
DHCPv4 server.
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 RFC 2119 [RFC2119].
This document uses the following terms:
o "address binding"
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.
o "access concentrator"
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
DHCP relay agent functionality.
o "Bulk Leasequery"
Requesting and receiving the existing DHCPv4 address binding
information in an efficient manner.
o "clock skew"
The difference between the absolute time on a DHCPv4 server and
the absolute time on the system where a requestor of a Bulk
Leasequery is executing is termed the "clock skew" for that 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 message is received by a
requestor from a DHCPv4 server, a more accurate value is derived
from continuously examining the instantaneous value developed
from each message received from a DHCPv4 server and using it to
Kinnear Expires December 2008 [Page 3]
Internet Draft Bulk DHCPv4 Lease Query July 2008
make small adjustments to the existing value held in the
requestor.
o "DHCPv4 client"
A DHCPv4 client is an Internet host using DHCP to obtain
configuration parameters such as a network address.
o "DHCPv4 relay agent"
A DHCPv4 relay agent is a third-party agent that transfers BOOTP
and DHCPv4 messages between clients and servers residing on
different subnets, per [RFC951] and [RFC1542].
o "DHCPv4 server"
A DHCPv4 server is an Internet host that returns configuration
parameters to DHCPv4 clients.
o "IP address binding"
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.
o "location information"
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.
o "MAC address"
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".
o "stable storage"
Every DHCP server is assumed to have some form of what is called
"stable storage". Stable storage is used to hold information
concerning IP address bindings (among other things) so that this
information is not lost in the event of a server failure which
requires restart of the server.
Kinnear Expires December 2008 [Page 4]
Internet Draft Bulk DHCPv4 Lease Query July 2008
3. Protocol Overview
The Bulk Leasequery mechanism is modeled on the existing individual
Leasequery protocol in [RFC4388] as well as related work on DHCPv6
Bulk Leasequery [DHCPv6Bulk]; most differences arise from the use of
TCP. A Bulk 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 of Bulk Leasequery
messages is specified.
After establishing a connection, the client sends a
DHCPBULKLEASEQUERY message over the connection.
The server uses the message and additional data in the DHCPv4 message
to decide how much data to send as a response to the query.
In order to support some query types, servers may have to maintain
additional data structures or be able to locate bindings that have
been requested by the Leasequery client.
The Bulk Leasequery mechanism is designed to provide an external
entity with information concerning existing DHCPv4 IPv4 address
bindings managed by the DHCPv4 server. When complete, the DHCPv4
server will send a DHCPLEASEQUERYDONE message. If a connection is
lost while processing a Bulk Leasequery, the Bulk Leasequery must be
retried as there is no provision for determining the extent of data
already received by the requestor for a Bulk Leasequery.
4. Interaction Between UDP Leasequery and Bulk Leasequery
Bulk Leasequery can be seen as an extension of the existing UDP
Leasequery protocol [RFC4388]. This section clarifies the
relationship between the two protocols.
The three query types available in the DHCPv4 Leasequery capability:
IP address, MAC address, and dhcp-client-identifier, are not
supported by Bulk Leasequery and MUST NOT be used by a requestor.
Bulk Leasequery allows specification of a query-start-time as well as
a a query-end-time. The query times are optional (and sent as
options), and in the absence of query times Bulk Leasequery will
return all current IP address bindings.
Use of query-times allows a relay agent that periodically commits
information to stable storage to recover just what it lost since the
Kinnear Expires December 2008 [Page 5]
Internet Draft Bulk DHCPv4 Lease Query July 2008
last commit.
The contents of message returns are similar between the existing UDP
Leasequery protocol and the Bulk Leasequery protocol, though more
information is returned in the Bulk Leasequery messages. See Section
7.3 for the details of the messages returned.
5. Message and Option Definitions
5.1. Message Framing for TCP
The use of TCP for the Bulk 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. Two octets containing the
message size in network byte-order are prepended to each DHCPv4
message sent on a Bulk Leasequery TCP connection. The two message-
size octets 'frame' each DHCPv4 message.
DHCPv4 message framed for TCP:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| message-size | op (1) | htype (1) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| hlen (1) | hops (1) | .... |
+---------------+---------------+ +
| |
. remainder of DHCPv4 message,
. from Figure 1 of [RFC2131] .
. .
. (variable) .
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
message-size the number of octets in the message that
follows, as a 16-bit integer in network
byte-order.
All other fields are as specified in DHCPv4 [RFC2131].
Figure 1: Format of a DHCPv4 message in TCP
The intent in using this format is that code which currently knows
Kinnear Expires December 2008 [Page 6]
Internet Draft Bulk DHCPv4 Lease Query July 2008
how to deal with a message returned from DHCPv4 Leasequery [RFC4388]
will be able to deal with the message held inside of the TCP framing.
5.2. New or Changed Options
The existing messages DHCPLEASEUNASSIGNED and DHCPLEASEACTIVE are
used as the value of the dhcp-message-type option to indicate an IP
address which is currently not leased or currently leased to a DHCPv4
client, respectively.
Additional options have also been defined to enable the Bulk
Leasequery protocol to communicate useful information to the
requestor.
5.2.1. dhcp-message-type
The message type option (option 53) from [RFC2132] requires new
values. The values of these message types are shown below in an
extension of the table from Section 9.6 of [RFC2132]:
Value Message Type
----- ------------
14 DHCPBULKLEASEQUERY
15 DHCPLEASEQUERYDONE
16 DHCPLEASEQUERYSTATUS
5.2.2. dhcp-status-code
The dhcp-status-code option allows greater detail to be returned
regarding the status of a DHCP request. While specified in the Bulk
Leasequery document, this DHCPv4 option may well be valuable in other
circumstances. In those circumstances its scope should be explicitly
defined.
This option has two possible scopes when used with Bulk 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 DHCPLEASEQUERYDONE or DHCPLEASEQUERYSTATUS.
The code for the this option is TBD. The length of the this option is
at least 1 octet. It SHOULD be present unless the status would be
Success, in which case it SHOULD NOT be present.
Kinnear Expires December 2008 [Page 7]
Internet Draft Bulk DHCPv4 Lease Query July 2008
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-code | option-len | status-code | |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |
. status-message (if any) .
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
option-code TBD.
option-len 1 + length of status-message (which may be 0).
status-code The numeric code for the status encoded
in this option. The status codes are
defined below.
status-message An optional UTF-8 encoded text string
suitable for display to an end user, which
MUST NOT be null-terminated.
Name status-code Description
---- ----------- -----------
Success 0 Success. Also signaled by absence of
dhcp-status-code option.
UnspecFail 1 Failure, reason unspecified.
QueryTerminated 2 Indicates that the server is unable to
perform a query or has prematurely terminated
the query for some reason (which should be
communicated in the text message).
MalformedQuery 3 The query was not understood.
NotAllowed 4 The query or request was understood but was
not allowed in this context.
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.
Kinnear Expires December 2008 [Page 8]
Internet Draft Bulk DHCPv4 Lease Query July 2008
5.2.3. base-time
The base-time option is the current time the message was created to
be sent by the DHCPv4 server to the requestor of the Bulk Leasequery.
This MUST be an absolute time. This MUST be an absolute number of
seconds since Jan 1, 1970. It is the time relative to which all of
the other relative times in the reply message are based. This time
is in the context of the DHCPv4 server.
This is an integer in network order.
The code for the this option is TBD. The length of the this option is
4 octets. It MUST appear in every DHCPLEASEACTIVE or
DHCPLEASEUNASSIGNED message returned as a response to a
DHCPBULKLEASEQUERY.
DHCPv4 Server
Code Len Base Time
+-----+-----+-----+-----+-----+-----+
| TBD | 4 | t1 | t2 | t3 | t4 |
+-----+-----+-----+-----+-----+-----+
5.2.4. start-time-of-state
The start-time-of-state option allows the receiver to determine the
time at which the IP address transitioned into its current state.
This MUST NOT be an absolute time. This MUST NOT be an absolute
number of seconds since Jan 1, 1970. Instead, this MUST be an
integer number of seconds in the past from the time specified in the
base-time option in the same message that the IP address transitioned
into its current state. In the same way that the IP Address Lease
Time option (option 51) encodes a lease time which is a number of
seconds into the future from the time the message was sent, this
option encodes a value which is a number of seconds into the past
from the base-time option included in the same message.
This is an integer in network order.
The code for the this option is TBD. The length of the this option is
4 octets. It MUST appear in every DHCPLEASEACTIVE or
DHCPLEASEUNASSIGNED message returned as a response to a
DHCPBULKLEASEQUERY.
Kinnear Expires December 2008 [Page 9]
Internet Draft Bulk DHCPv4 Lease Query July 2008
Seconds in the past
Code Len from base-time
+-----+-----+-----+-----+-----+-----+
| TBD | 4 | t1 | t2 | t3 | t4 |
+-----+-----+-----+-----+-----+-----+
5.2.5. query-start-time
The query-start-time option allows the requestor to specify a request
time to the DHCPv4 server.
This MUST be an absolute time. This MUST be an absolute number of
seconds since Jan 1, 1970.
This MUST be in a time in the context of the DHCPv4 server, and thus
SHOULD be equal to or derived from a base-time value received from
the DHCPv4 server itself.
It SHOULD NOT be a time in the context of the requestor.
This is an integer in network order.
The code for the this option is TBD. The length of the this option is
4 octets.
Code Len DHCPv4 Server Time
+-----+-----+-----+-----+-----+-----+
| TBD | 4 | t1 | t2 | t3 | t4 |
+-----+-----+-----+-----+-----+-----+
5.2.6. query-end-time
The query-end-time option allows the requestor to specify a request
time to the DHCPv4 server.
This MUST be an absolute time. This MUST be an absolute number of
seconds since Jan 1, 1970.
This MUST be in a time in the context of the DHCPv4 server, and thus
SHOULD be equal to or derived from a base-time value received from
the DHCPv4 server itself.
It SHOULD NOT be a time in the context of the requestor.
Kinnear Expires December 2008 [Page 10]
Internet Draft Bulk DHCPv4 Lease Query July 2008
This is an integer in network order.
The code for the this option is TBD. The length of the this option is
4 octets.
Code Len DHCPv4 Server Time
+-----+-----+-----+-----+-----+-----+
| TBD | 4 | t1 | t2 | t3 | t4 |
+-----+-----+-----+-----+-----+-----+
5.2.7. dhcp-state
The dhcp-state option allows greater detail to be returned than
allowed by the DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED message types.
The code for the this option is TBD. The length of the this option is
1 octet. It MUST appear in every message returned as a response to a
DHCPBULKLEASEQUERY.
0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Code | Length | State |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Code The suboption code (TBD).
Length The suboption length, 1 octet.
State The State of the IP address.
State
-----
1 AVAILABLE Address is available to local server
2 ACTIVE Address is assigned to a client
3 EXPIRED Lease has expired
4 RELEASED Lease has been released by client
5 ABANDONED Server or client flagged address as unusable
6 RESET Lease was freed by some external agent
7 REMOTE Address is available to a remote server
Note that some of these states may be transient and may not appear in
normal use. A DHCPv4 server MUST implement at least the AVAILABLE
and ACTIVE states, and SHOULD implement at least the ABANDONED and
RESET states.
Kinnear Expires December 2008 [Page 11]
Internet Draft Bulk DHCPv4 Lease Query July 2008
The reference to local and remote relate to possible use in an
environment that includes multiple servers cooperating to provide an
increased availability solution. In this case, an IP address with
the state of AVAILABLE is available to the local server, while one
with the state of REMOTE is available to a remote server. Usually,
an IP address which is AVAILABLE on one server would be REMOTE on any
remote server.
There is no requirement for the state of an IP address to transition
in a well defined way from state to state. To put this another way,
you cannot draw a simple state transition graph for the states of an
IP address and the requestor of a LEASEQUERY MUST NOT depend on one
certain state always following a particular previous state. In
general, every state can (at times) follow every other state.
5.2.8. data-source
The data-source option contains information about the source of the
data in a DHCPLEASEACTIVE or a DHCPLEASEUNASSIGNED message. It is
used when there are two or more servers who might have information
about a particular IP address binding. Frequently two servers work
together to provide an increased availability solution for the DHCPv4
service, and in these cases, both servers will respond to Bulk
Leasequery requests for the same IP address.
The data contained in this option will allow an external process to
better discriminate between the information provided by each of the
servers servicing this IPv4 address.
The code for the this option is TBD. The length of the this option is
1 octet.
This option MUST appear in every Bulk Leasequery message where the
REMOTE flag would be have the value remote. If this option does not
appear, then the REMOTE flag is considered to be have the value
local.
Kinnear Expires December 2008 [Page 12]
Internet Draft Bulk DHCPv4 Lease Query July 2008
0 1 2
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| Code | Length | Flags |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Code The suboption code (TBD).
Length The suboption length, 1 octet.
Flags The Source information for this message.
0 1 2 3 4 5 6 7
+-+-+-+-+-+-+-+-+
| MBZ |R|
+-+-+-+-+-+-+-+-+
R: REMOTE flag
remote = 1
local = 0
MBZ: MUST BE ZERO (reserved for future use)
The REMOTE flag is used to indicate where the change of state (or
other interesting change) concerning this IPv4 address took place.
If the value is local, then the change took place on the server from
which this message was transmitted. If the value is remote, then the
change took place on some other server, and was made known to the
server from which this message was transmitted.
5.3. Connection and Transmission Parameters
DHCPv4 Servers that Bulk Leasequery SHOULD listen for incoming TCP
connections on the DHCPv4 server port 67. Implementations MAY offer
to make the incoming port configurable, but port 67 MUST be the
default. Client implementations SHOULD make TCP connections to port
67, and MAY offer to make the destination server port configurable.
This section presents a table of values used to control Bulk
Leasequery behavior, including recommended defaults. Implementations
MAY make these values configurable.
Kinnear Expires December 2008 [Page 13]
Internet Draft Bulk DHCPv4 Lease Query July 2008
Parameter Default Description
------------------------------------------
BULK_LQ_CONN_TIMEOUT 30 secs Leasequery connection timeout
BULK_LQ_QUERY_TIMEOUT 30 secs Leasequery query timeout
BULK_LQ_MAX_CONNS 10 Max Leasequery TCP connections
BULK_LQ_MAX_CONN_RETRY 60 secs Max Leasequery retry timeout
BULK_LQ_DATA_TIMEOUT 30 secs Leasequery data timeout
6. Requestor Behavior
6.1. Connecting and General Processing
A requestor attempts to establish a TCP connection to a DHCPv4 Server
in order to initiate a Leasequery exchange. The requestor SHOULD be
prepared to abandon the connection attempt after
BULK_LQ_CONN_TIMEOUT. If the attempt fails, the requestor MAY retry.
Retries MUST use an exponential backoff timer, increasing the
interval between attempts up to BULK_LQ_MAX_CONN_RETRY.
If Bulk Leasequery is terminated prematurely by a
DHCPLEASEQUERYSTATUS with a dhcp-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. Retries MUST use an exponential backoff timer,
increasing the interval between attempts up to
BULK_LQ_MAX_CONN_RETRY.
Messages from the DHCPv4 server come as a response to a
DHCPBULKLEASEQUERY message. These requests MUST have a transaction-
id unique to the connection on which they are sent, and all of the
messages which come as a response to them all contain the same
transaction-id as the requests. In the event that a response is
received with a different transaction-id than the request which
generated it, the requestor MUST close the connection immediately.
6.2. Forming a Bulk Leasequery
The Bulk Leasequery is designed to create a connection which will
transfer the state of all IP address bindings between the requestor
and the DHCPv4 server processing the bulk query. The DHCPv4 server
will send all of the requested IPv4 address binding across this
connection with minimal delay after it receives the request. In this
context, "all IP address binding information" means information about
Kinnear Expires December 2008 [Page 14]
Internet Draft Bulk DHCPv4 Lease Query July 2008
all IPv4 addresses configured within the DHCPv4 server, whether or
not they have ever had or now have an association with a specific
DHCPv4 client.
To form the Bulk query, a DHCPv4 request is constructed with a dhcp-
message-type of DHCPBULKLEASEQUERY. This DHCPv4 request MUST NOT
have a ciaddr, a chaddr, or a dhcp-client-identifier. The query
SHOULD have a dhcp-parameter-request-list to inform the DHCPv4 server
which DHCPv4 options are of interest to the requestor sending the
DHCPBULKLEASEQUERY message.
The requestor MAY include a query-start-time option or a query-end-
time option or both in the DHCPBULKLEASEQUERY request indicating to
the DHCPv4 server that it should only send information which changed
on or after the time specified in any query-start-time option and on
or before any time specified in a query-end-time option.
If there is no query-start-time, then the DHCPv4 server will assume
the query-start-time is equivalent to a time prior to any time that
resides in any IP address binding. If there is no query-end-time,
the DHCPv4 server will assume that the query-end-time is equivalent
to the current time.
Both of these options (if they appear) MUST include times derived
directly from base-time options received from the server and MUST be
in the context of the DHCPv4 server's time, not the requestor's time
should they be different.
Use of the query-start-time or the query-end-time options or both can
serve to reduce the amount of data transferred over the TCP
connection by a considerable amount, though it may not change the
actual data processed on the DHCPv4 server.
If the TCP connection becomes blocked while the requestor is sending
its query, the requestor SHOULD be prepared to terminate the
connection after BULK_LQ_QUERY_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.
6.3. Processing Bulk Replies
The requestor attempts to read a DHCPv4 leasequery message from the
TCP connection. If the stream of replies becomes blocked, the
requestor SHOULD be prepared to terminate the connection after
BULK_LQ_DATA_TIMEOUT, and MAY begin retry processing if configured to
do so.
Kinnear Expires December 2008 [Page 15]
Internet Draft Bulk DHCPv4 Lease Query July 2008
A Bulk Leasequery will consist of a variety of DHCPLEASEACTIVE
messages containing binding data and DHCPLEASEUNASSIGNED messages
which MAY also contain information about the last client that was
bound to this IP address. In both cases, the ciaddr will contain the
IP address of the Leasequery reply, and may contain a non-zero
chaddr, htype, and hlen and possibly additional options. If there
are additional bindings to be returned, they will be carried in
additional DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED messages.
A single Bulk Leasequery can and usually will result in a large
number of replies. The requestor MUST be prepared to receive more
than one reply with a transaction-id matching a single
DHCPBULKLEASEQUERY message from a single DHCPv4 server. Indeed, a
requestor which receives a reply with a transaction-id which is not
the same as that in the DHCPBULKLEASEQUERY request MUST terminate the
connection.
The requestor MUST NOT assume that there is any inherent order in the
IPv4 address binding information that is sent in response to a
DHCPBULKLEASEQUERY. While the base-time will tend to increase
monotonically (as it is the current time on the DHCPv4 server), the
actual time that any IP address binding information changed is
unrelated to the base-time.
The DHCPLEASEQUERYDONE message always ends a successful
DHCPBULKLEASEQUERY request. After receiving DHCPLEASEQUERYDONE from
a server, the requestor MAY close the TCP connection to that server.
The DHCPv4 Leasequery protocol [RFC4388] uses the associated-ip
option as an indicator that multiple bindings were present in
response to a single client based query. For Bulk Leasequery, client
based queries are not supported, and so the associated-ip option is
not used, and MUST NOT be present in replies.
6.4. Processing Time Values in Leasequery messages
Bulk Leasequery requests may be made to a DHCPv4 server whose
absolute time may not be synchronized with the local time of the
requestor. Thus, there are at least two time contexts in even the
simplest Bulk Leasequery response, and in the situation where
multiple DHCPv4 servers are queried, the situation becomes even more
complex.
If the requestor of a Bulk Leasequery is saving the data returned in
some form, it has a requirement to store a variety of time values,
and some of these will be time in the context of the requestor and
some will be time in the context of the DHCPv4 server.
Kinnear Expires December 2008 [Page 16]
Internet Draft Bulk DHCPv4 Lease Query July 2008
When receiving a DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED message from
the DHCPv4 server, the message will contain a base-time option. The
time contained in this base-time option is in the context of the
DHCPv4 server. As such, it is an ideal time to save and use as input
to a DHCPBULKLEASEQUERY in the query-start-time or query-end-time
options.
In addition to saving the base-time for future use in a query-start-
time option, the base-time is used as part of the conversion of the
other times in the Leasequery message to values which are meaningful
in the context of the requestor.
The requestor SHOULD use the base-time values received in Leasequery
messages to develop a value which represents the clock skew between
the DHCPv4 server and the requestor. In theory this clock skew would
simply be the difference between the first base-time value and the
current time on the requestor when the message containing the base-
time value was received. However, there may be transmission delays
at the beginning or end or along the TCP connection, and so the
actual clock skew may not be the same as any individual difference
between a base-time value and the current time of the requestor.
The requestor SHOULD smooth the value which it uses as the clock skew
by continuously examining the instantaneous value developed from the
base-time of each message received from a DHCPv4 server and using
this instantaneous value of clock skew to make small adjustments to
the existing value of the clock skew. Thus, the clock skew will vary
only slowly and one slow message will not completely distort a large
number of future time calculations.
Given the value of the clock skew on the requestor, the requestor
SHOULD bring all of the times in the DHCPLEASEACTIVE and
DHCPLEASEUNASSIGNED messages into the context of the requestor.
Except for the base-time value, the times in the Leasequery message
are all relative to the base-time. These relative times SHOULD first
be converted into absolute times in the context of the DHCPv4 server
using the base-time value. Once this stage is complete, the absolute
times that result SHOULD be brought into the context of the requestor
by applying the calculated clock skew to each of the absolute times.
After all of this processing, the times are in the context of the
requestor.
An alternative might appear to be to leave all of the times in the
context of the DHCPv4 server, and if the requestor is dealing with
only one DHCPv4 server at a time, this is an accurate and effective
approach. However, if the requestor is dealing with DHCPLEASEACTIVE
and DHCPLEASEUNASSIGNED messages from two or more different DHCPv4
Kinnear Expires December 2008 [Page 17]
Internet Draft Bulk DHCPv4 Lease Query July 2008
servers, then in order to make any sense of them, the times from each
server SHOULD be converted into the time of the requestor.
Since various transmission and processing delays may occur, a time
converted into the requestor's context may be accurate to only a few
seconds, at best. This is rarely an issue in the larger context of
the use of the information derived from a Bulk Leasequery request.
However, time comparison is an important factor in determining which
update to the address binding information for a particular IPv4
address is the most recent and therefore worth remembering. The next
section discusses the issue of comparing two updates in some detail,
but a key aspect of that comparison is a comparison of the times in
the two messages.
The requestor SHOULD consider times converted into its context as
effectively equivalent if they are within a small number of seconds
of each other. The precise number depends on the particular
implementation involved, but 4 to 8 seconds is probably a good
starting point. Thus, if two times are 3 seconds apart after
conversion to the requestor's context they should be considered the
same for purposes of comparison with each other.
6.5. Making Sense Out of Multiple Responses Concerning a Single IPv4
Address
Any requestor of an Bulk Leasequery MUST be prepared for multiple
responses to arrive for a particular IPv4 address from a single
DHCPv4 server as well as from multiple different DHCPv4 servers. The
following algorithm SHOULD be used to decide if the information just
received is more up to date (i.e., better) than the best existing
information. In the discussion below, the information that is
received from a DHCPv4 server about a particular IPv4 address is
termed a "record".
o If both the existing and the new record contain client-last-
transaction-time information, the record with the later client-
last-transaction-time is considered better.
o If one of the records contains client-last-transaction-time
information and the other one doesn't, then compare the client-
last-transaction-time in the record that contains it against the
other record's start-time-of-state. The record with the later
time is considered better.
o If neither record contains client-last-transaction-time
information, compare their start-time-of-state information. The
record with the later start-time-of-state is considered better.
Kinnear Expires December 2008 [Page 18]
Internet Draft Bulk DHCPv4 Lease Query July 2008
o If none of the comparisons above yield a clear answer as to
which record is later, then compare the value of the REMOTE flag
from the data-source option for the each record.
If the values of the REMOTE flag are different between the two
records, the record with the REMOTE flag value of local is
considered better.
The above algorithm does not necessarily determine which record is
better. In the event that the algorithm is inconclusive with
regard to a record which was just received by the requestor, the
requestor SHOULD use additional information in the two records to
make a determination as to which record is better.
6.6. Querying Multiple Servers
A Bulk Leasequery client MAY be configured to attempt to connect to
and query from multiple DHCPv4 servers in parallel. The DHCPv4
Leasequery specification [RFC4388] includes a discussion about
reconciling binding data received from multiple DHCPv4 servers.
In addition, the algorithm in the Section 6.5 should be used.
6.7. Closing Connections
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.
7. Server Behavior
7.1. Accepting Connections
Servers that implement DHCPv4 Bulk 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.
Servers MAY restrict Bulk Leasequery connections and
DHCPBULKLEASEQUERY messages to certain clients. Connections not from
permitted clients SHOULD be closed immediately, to avoid server
Kinnear Expires December 2008 [Page 19]
Internet Draft Bulk DHCPv4 Lease Query July 2008
connection resource exhaustion.
If a DHCPv4 server receives more than one DHCPBULKLEASEQUERY message
on a connection without transmission of an intervening
DHCPLEASEQUERYDONE message by that DHCPv4 server, it SHOULD send a
DHCPLEASEQUERYSTATUS message containing a dhcp-status-code of
NotAllowed and then drop the connection.
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 an BULK_LQ_QUERY_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.
7.2. Replying to a Bulk Leasequery
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 BULK_LQ_DATA_TIMEOUT.
If the DHCPv4 server encounters an error during processing of the
DHCPBULKLEASEQUERY message, either during initial processing or later
during the message processing, it SHOULD send a DHCPLEASEQUERYDONE
containing an error code of some kind in a dhcp-status-code option.
It MAY close the connection after this error is signaled, but that is
not required.
If the server does not find any bindings satisfying a query, it MUST
send a DHCPLEASEQUERYDONE without a dhcp-status-code option.
Otherwise, the server sends each binding's data in a DHCPLEASEACTIVE
or DHCPLEASEUNASSIGNED message.
The response to a DHCPBULKLEASEQUERY almost certainly entails a scan
of many if not all all existing DHCPv4 IP address bindings maintained
by the DHCPv4 server. These bindings may be scanned in any order
convenient to the DHCPv4 server and the messages sent to the
requestor may be in any order as well. Information concerning every
configured IPv4 address (whether or not currently bound to a DHCPv4
client) MUST be sent in response to a Bulk Leasequery, subject to any
constraints on the information sent imposed in the request.
In the event that the DHCPBULKLEASEQUERY request contains a query-
start-time option or a query-end-time option or both, only those
address bindings which changed on or after the query-start-time time
specified or changed on or before the query-end-time time specified
(or both, if both option appear) SHOULD be sent to the requestor. If
there is no query-start-time or query-end-time option in the
Kinnear Expires December 2008 [Page 20]
Internet Draft Bulk DHCPv4 Lease Query July 2008
DHCPBULKLEASEQUERY request, then the query-start-time is assumed to
be prior to the earliest time of any IP address binding, and the
query-end-time is assumed to be the time of the query. This is to
prevent the Bulk Leasequery from getting caught by a busy server and
never terminating.
Even if the query-start-time or query-end-time option value is being
used to limit the amount of data flow from the DHCPv4 server to the
requestor, there is no requirement placed on the DHCPv4 server to
return address binding data in any order and certainly not in any
order based on time.
When the DHCPv4 server has no additional information to send to the
requestor, it will send a DHCPLEASEQUERYDONE message.
7.3. Building a Single Reply for Bulk Leasequery
The DHCPv4 Leasequery [RFC4388] specification describes the initial
construction of DHCPLEASEQUERY reply messages using the
DHCPLEASEACTIVE and DHCPLEASEUNASSIGNED message types in Section
6.4.2. All of the reply messages in Bulk Leasequery are similar to
the reply messages for an IP address query. Message transmission and
framing for TCP is described in this document in Section 5.1.
In addition to the basic message construction described in [RFC4388],
the following guidelines exist:
The message type of DHCPLEASEACTIVE or DHCPLEASEUNASSIGNED is based
on the value of the dhcp-state option. If the dhcp-state option
value is ACTIVE, then the message type is DHCPLEASEACTIVE, otherwise
the message type is DHCPLEASEUNASSIGNED.
1. The DHCPv4 server MUST include a dhcp-state option whose value
corresponds most closely to the state held by the DHCPv4 server
for the IP address associated with this reply.
2. The DHCPv4 server MUST include a base-time option, which is the
current time in the DHCPv4 server's context and the time from
which the start-time-of-state, dhcp-lease-time, client-last-
transaction-time, and other duration-style times are based
upon.
3. The DHCPv4 server MUST include a state-time-of-state option
whose value represents the time at which the dhcp-state
option's state became valid.
4. The DHCPv4 server MUST include a dhcp-lease-time option for any
state that has a time-out value associated with it, and not
Kinnear Expires December 2008 [Page 21]
Internet Draft Bulk DHCPv4 Lease Query July 2008
just appear in a DHCPLEASEACTIVE message. Thus, the EXPIRED
state which is sent in a DHCPLEASEUNASSIGNED message would have
a dhcp-lease-time option in the message if the EXPIRED state
represented a grace-period and would be changing state after
the grace-period expired.
5. The DHCPv4 server MUST include the data-source option in any
situation where any of the bits would be non-zero. Thus, in
the absence of the data-source option, the assumption is that
all of the flags were zero.
6. The DHCPv4 server MUST include the client-last-transaction-time
option in any situation where the information is available.
7. If there is a dhcp-parameter-request-list in the initial
DHCPBULKLEASEQUERY request, then it should be used for all of
the replies generated by that request.
Note that there may be other requirements for a reply to a
DHCPBULKLEASEQUERY request discussed in Section 7.2.
7.4. Multiple or Parallel Queries
A single connection MUST be used for a single Bulk Leasequery
request. Servers MUST NOT process two queries on the same
connection at the same time.
7.5. Closing Connections
The server MAY close its end of the TCP connection after sending its
last message, a DHCPLEASEQUERYDONE 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.
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 DHCPLEASEQUERYDONE
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.
The server MUST send a DHCPLEASEQUERYDONE message at the end of the
data returned from a Bulk Leasequery request.
Kinnear Expires December 2008 [Page 22]
Internet Draft Bulk DHCPv4 Lease Query July 2008
8. Security Considerations
The "Security Considerations" section of [RFC2131] details the
general threats to DHCPv4. The DHCPv4 Leasequery specification
[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 [RFC4301].
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.
9. IANA Considerations
IANA is requested to assign the following new values for this
document. See Section 5.2 for details.
1. A dhcp-message-type of 14 for DHCPBULKLEASEQUERY.
2. A dhcp-message-type of 15 for DHCPLEASEQUERYDONE.
3. A dhcp-message-type of 16 for DHCPLEASEQUERYSTATUS.
4. An option code of TBD for dhcp-status-code.
5. An option code of TBD for base-time.
6. An option code of TBD for start-time-of-state.
7. An option code of TBD for query-start-time.
8. An option code of TBD for query-end-time.
9. An option code of TBD for dhcp-state.
10.Values for dhcp-status-code:
Kinnear Expires December 2008 [Page 23]
Internet Draft Bulk DHCPv4 Lease Query July 2008
Name status-code
---- -----------
Success 0
UnspecFail 1
QueryTerminated 2
MalformedQuery 3
NotAllowed 4
12.Values for dhcp-state:
State
-----
1 AVAILABLE
2 ACTIVE
3 EXPIRED
4 RELEASED
5 ABANDONED
6 RESET
7 REMOTE
10. Acknowledgements
The ideas in this document came from in part from the DHCPv6 Bulk
Leasequery protocol documents as well as from in depth discussions
between the authors.
11. References
11.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", RFC 2119, March 1997.
[RFC2131] Droms, R., "Dynamic Host Configuration Protocol", RFC 2131,
March 1997.
[RFC4301] Kent, S., Seo, K., "Security Architecture for the Internet
Protocol", RFC4301, December 2005.
[RFC4388] Woundy, R., Kinnear, K., "Dynamic Host Configuration
Protocol (DHCP) Leasequery", RFC 4388, February 2006.
Kinnear Expires December 2008 [Page 24]
Internet Draft Bulk DHCPv4 Lease Query July 2008
11.2. Informative References
[RFC951] Croft, B., Gilmore, J., "Bootstrap Protocol (BOOTP)", RFC
951, September 1985.
[RFC1542] Wimer, W., "Clarifications and Extensions for the Bootstrap
Protocol", RFC 1542, October 1993.
[RFC2132] Alexander, S., Droms, R., "DHCP Options and BOOTP Vendor
Extensions", RFC 2132, March 1997.
[DHCPv6Bulk] Stapp, M., "DHCPv6 Bulk Leasequery", draft-ietf-dhc-
dhcpv6-bulk-leasequery-03.txt, June 2008.
12. Authors' Addresses
Kim Kinnear
Cisco Systems
1414 Massachusetts Ave.
Boxborough, Massachusetts 01719
Phone: (978) 936-0000
EMail: kkinnear@cisco.com
Bernie Volz
Cisco Systems
1414 Massachusetts Ave.
Boxborough, Massachusetts 01719
Phone: (978) 936-0000
EMail: volz@cisco.com
Neil Russell
Cisco Systems
1414 Massachusetts Ave.
Boxborough, Massachusetts 01719
Phone: (978) 936-0000
EMail: nrussell@cisco.com
Kinnear Expires December 2008 [Page 25]
Internet Draft Bulk DHCPv4 Lease Query July 2008
Mark Stapp
Cisco Systems
1414 Massachusetts Ave.
Boxborough, Massachusetts 01719
Phone: (978) 936-0000
EMail: mjs@cisco.com
13. Full Copyright Statement
Copyright (C) The IETF Trust (2008).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
14. Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
Kinnear Expires December 2008 [Page 26]
Internet Draft Bulk DHCPv4 Lease Query July 2008
ietf-ipr@ietf.org.
15. Acknowledgment
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
Kinnear Expires December 2008 [Page 27]