kea/src/bin/dhcp4/dhcp4.dox

// Copyright (C) 2012-2014 Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

/**
 @page dhcp4 DHCPv4 Server Component

BIND10 offers DHCPv4 server implementation. It is implemented as
b10-dhcp4 component.  Its primary code is located in
isc::dhcp::Dhcpv4Srv class. It uses \ref libdhcp extensively,
especially isc::dhcp::Pkt4, isc::dhcp::Option and
isc::dhcp::IfaceMgr classes. Currently this code offers skeleton
functionality, i.e. it is able to receive and process incoming
requests and trasmit responses. However, it does not have database
management, so it returns only one, hardcoded lease to whoever asks
for it.

DHCPv4 server component does not support direct traffic (relayed
only), as support for transmission to hosts without IPv4 address
assigned is not implemented in IfaceMgr yet.

@section dhcpv4Session BIND10 message queue integration

DHCPv4 server component is now integrated with BIND10 message queue.
The integration is performed by establishSession() and disconnectSession()
functions in isc::dhcp::ControlledDhcpv4Srv class. main() method defined
in the src/bin/dhcp4/main.cc file instantiates isc::dhcp::ControlledDhcpv4Srv
class that establishes connection with msgq and install necessary handlers
for receiving commands and configuration updates. It is derived from
a base isc::dhcp::Dhcpv4Srv class that implements DHCPv4 server functionality,
without any controlling mechanisms.

ControlledDhcpv4Srv instantiates several components to make management
session possible. In particular, isc::cc::Session cc_session
object uses ASIO for establishing connection. It registers its socket
in isc::asiolink::IOService io_service object. Typically, other components
(e.g. auth or resolver) that use ASIO for their communication, register their
other sockets in the
same io_service and then just call io_service.run() method that does
not return, until one of the callback decides that it is time to shut down
the whole component cal calls io_service.stop(). DHCPv4 works in a
different way. It does receive messages using select()
(see isc::dhcp::IfaceMgr::receive4()), which is incompatible with ASIO.
To solve this problem, socket descriptor is extracted from cc_session
object and is passed to IfaceMgr by using isc::dhcp::IfaceMgr::set_session_socket().
IfaceMgr then uses this socket in its select() call. If there is some
data to be read, it calls registered callback that is supposed to
read and process incoming data.

This somewhat complicated approach is needed for a simple reason. In
embedded deployments there will be no message queue. Not referring directly
to anything related to message queue in isc::dhcp::Dhcpv4Srv and
isc::dhcp::IfaceMgr classes brings in two benefits. First, the can
be used with and without message queue. Second benefit is related to the
first one: \ref libdhcp is supposed to be simple and robust and not require
many dependencies. One notable example of a use case that benefits from
this approach is a perfdhcp tool. Finally, the idea is that it should be
possible to instantiate Dhcpv4Srv object directly, thus getting a server
that does not support msgq. That is useful for embedded environments.
It may also be useful in validation.

@section dhcpv4ConfigParser Configuration Parser in DHCPv4

This parser follows exactly the same logic as its DHCPv6 counterpart.
See \ref dhcpv6ConfigParser.

@section dhcpv4ConfigInherit DHCPv4 configuration inheritance

Configuration inheritance in DHCPv4 follows exactly the same logic as its DHCPv6
counterpart. See \ref dhcpv6ConfigInherit.

@section dhcpv4OptionsParse Custom functions to parse message options

The DHCPv4 server uses the same logic to supply custom callback function to
parse message option as DHCPv6 server implementation. See \ref dhcpv6OptionsParse.

@section dhcpv4DDNSIntegration DHCPv4 Server Support for the Dynamic DNS Updates
T
he DHCPv4 server supports processing of the DHCPv4 Client FQDN option (RFC4702)
and the DHCPv4 Host Name option (RFC2132). Client may send one of these options
to convey its fully qualified or partial name to the server. The server may use
this name to perform DNS updates for the client. If server receives both options
in the same message, the DHCPv4 Client FQDN %Option is processed and the Host
Name option is ignored. If only Host Name Option is present in the client's
message, it is used to update DNS.

Server may be configured to use a different name to perform DNS update for the
client. In this case the server will return one of the DHCPv4 Client FQDN or
Host Name %Option in its response with the name which was selected for the
client to indicate that this name will be used to perform DNS update.

The b10-dhcp-ddns process is responsible for the actual communication with the
DNS, i.e. to send DNS update messages. The b10-dhcp4 module is responsible for
generating @ref isc::dhcp_ddns::NameChangeRequest and sending it to
the b10-dhcp-ddns module. The @ref isc::dhcp_ddns::NameChangeRequest object
represents changes to the DNS bindings, related to acquisition, renewal or
release of the DHCP lease. The b10-dhcp4 module implements the simple FIFO queue
of the NameChangeRequest objects. The module logic, which processes the incoming
DHCPv4 Client FQDN and Host Name Options puts these requests into the FIFO queue.

@todo Currently the FIFO queue is not processed after the NameChangeRequests are
generated and added to it. In the future implementation steps it is planned to
create a code which will check if there are any outstanding requests in the queue
and send them to the b10-dhcp-ddns module when server is idle waiting for DHCP
messages.

When client gets an address from the server, a DHCPv4 server may generate 0, 1
or 2 NameChangeRequests during single message processing. Server generates no
NameChangeRequests if it is not configured to update DNS or it rejects the DNS
update for any other reason.

Server may generate 1 NameChangeRequest in a case when client acquired a new
lease or it releases an existing lease. In the former case, the NameChangeRequest
type is CHG_ADD, which indicates that the b10-dhcp-ddns module should add a new
DNS binding for the client, and it is assumed that there is no DNS binding for
this client already. In the latter case, the NameChangeRequest type is CHG_REMOVE
to indicate to the b10-dhcp-ddns module that an existing DNS binding should be
removed from the DNS. The binding consists of the forward and reverse mapping.
The server may only remove the mapping which it had added. Therefore, the lease
database holds the information which updates (no update, reverse only update,
forward only update or both reverse and forward update) have been performed when
the lease was acquired or renewed. Server checks this information to make a
decision which mapping it is supposed to remove when lease is released.

Server may generate 2 NameChangeRequests in case a client is renewing a lease and
it already has a DNS binding for that lease. The DHCPv4 server will check if
there is an existing lease for the client which has sent a message and if DNS
Updates had been performed for this lease. If the notion of client's FQDN changes,
comparing to the information stored in the lease database, the DHCPv4 has to
remove an existing binding from the DNS and then add a new binding according to
the new FQDN information received from the client. If the client's FQDN
information (including the client's name and type of update performed) doesn't
change comparing to the NameChangeRequest is not generated.

The DHCPv4 Client FQDN %Option comprises flags which communicate to the server
what updates (if any) client expects the server to perform. Server may be
configured to obey client's preference or to do FQDN processing in a different way.
If the server overrides client's preference it will communicate it by sending
the DHCPv4 Client FQDN %Option in its responses to a client, with the appropriate
flags set.

@todo Note, that current implementation doesn't allow configuration of the
server's behaviour with respect to DNS Updates. This is planned for the future.
The default behaviour is constituted by the set of constants defined in the
(upper part of) dhcp4_srv.cc file. Once the configuration is implemented,
these constants will be removed.

@section dhcpv4Classifier DHCPv4 Client Classification

Kea DHCPv4 server currently supports simplified client classification. It is called
"simplified", because the incoming packets are classified based on the content
of the vendor class (60) option. More flexible classification is planned, but there
are no specific development dates agreed.

For each incoming packet, @ref isc::dhcp::Dhcpv4Srv::classifyPacket() method is called.
It attempts to extract content of the vendor class option and interpret as a name
of the class. For now, the code has been tested with two classes used in cable modem
networks: eRouter1.0 and docsis3.0, but any other content of the vendor class option will
be interpreted as a class name.

In principle any given packet can belong to zero or more classes. As the current
classifier is very modest, there's only one way to assign a class (based on vendor class
option), the ability to assign more than one class to a packet is not yet exercised.
Neverthless, there is such a possibility and it will be used in a near future. To
check whether a packet belongs to given class, isc::dhcp::Pkt4::inClass method should
be used.

Currently there is a short code section that alternates packet processing depending on
which class it belongs to. It is planned to move that capability to an external hook
library. See ticket #3275. The class specific behavior is:

- docsis3.0 packets have siaddr (next server) field set
- docsis3.0 packets have file field set to the content of the boot-file-name option
- eRouter1.0 packets have siaddr (next server) field cleared

Aforementioned modifications are conducted in @ref isc::dhcp::Dhcpv4Srv::classSpecificProcessing.

It is possible to define class restrictions in subnet, so a given subnet is only
accessible to clients that belong to a given class. That is implemented as isc::dhcp::Pkt4::classes_
being passed in isc::dhcp::Dhcpv4Srv::selectSubnet() to isc::dhcp::CfgMgr::getSubnet4().
Currently this capability is usable, but the number of scenarios it supports is
limited.

 @section dhcpv4ConfigBackend Configuration backend for DHCPv4

There are many theoretical ways in which server configuration can be stored. Kea 0.8 and
earlier versions used BIND10 framework and its internal storage for DHCPv6 server configuration.
The legacy ISC-DHCP implementation uses flat files. Configuration stored in JSON files is
becoming more and more popular among various projects. There are unofficial patches for
ISC-DHCP that keep parts of the configuration in LDAP. It was also suggested that in some
cases it would be convenient to keep configuration in XML files.

Kea 0.9 introduces configuration backends that are switchable during compilation phase.
There is a new parameter for configure script: --with-kea-config. It currently supports
two values: BUNDY and JSON.

BUNDY (which is the default value as of May 2014) means that Kea4 is linked with the
Bundy (former BIND10) configuration backend that connects to the BIND10 framework and in general works
exactly the same as Kea 0.8 and earlier versions. The benefits of that backend are uniform
integration with Bundy/BIND10 framework, easy on-line reconfiguration using bindctl, available
RESTful API. On the other hand, it requires the whole heavy Bundy framework that requires
Python3 to be present. That framework is going away with the release of Kea 0.9.

JSON is a new configuration backend that causes Kea to read JSON configuration file from
disk. It does not require any framework and thus is considered more lightweight. It will
allow dynamic on-line reconfiguration, but will lack remote capabilities (i.e. no RESTful
API). This configuration backend is expected to be the default for upcoming Kea 0.9. It
requires <tt> -c config-file </tt> command-line option.

Internally, configuration backends are implemented as different implementations of the
isc::dhcp::ControlledDhcpv4Srv class, stored in {kea,bundy}_controller.cc files. Depending on
the choice made by ./configure script, only one of those files is compiled and linked.
There are backend specific tests in src/bin/dhcp4/tests/{kea,bundy}_controller_unittest.cc.
Only tests specific to selected backend are linked and executed during make distcheck.

While it is unlikely that ISC will support more than one backend at any given time, there
are several aspects that make that approach appealing in the long term. First, having
two backends is essential during transition time, where both old and new backend is used.
Second, there are external organizations that develop and presumably maintain LDAP backend
for ISC-DHCP. Is at least possible that similar will happen for Kea. Finally, if we ever
extend the isc::dhcp::CfgMgr with configuration export, this approach could be used as
a migration tool.

@section dhcpv4Other Other DHCPv4 topics

 For hooks API support in DHCPv4, see @ref dhcpv4Hooks.

*/