Commit 220c337c authored by Marcin Siodelski's avatar Marcin Siodelski
Browse files

[master] Merge branch 'trac3484'

parents c0d2c32d c9f25025
......@@ -45,7 +45,7 @@ PROJECT_BRIEF =
# exceed 55 pixels and the maximum width should not exceed 200 pixels.
# Doxygen will copy the logo to the output directory.
PROJECT_LOGO =
PROJECT_LOGO = images/isc-logo.png
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
# base path where the generated documentation will be put.
......@@ -659,6 +659,7 @@ INPUT = ../src/bin/d2 \
../src/lib/dhcp \
../src/lib/dhcp_ddns \
../src/lib/dhcpsrv \
../src/lib/dhcpsrv/parsers \
../src/lib/dns \
../src/lib/exceptions \
../src/lib/hooks \
......
......@@ -58,7 +58,7 @@ a regular x86 architecture machine to write your patch, but the software
is expected to run on many other architectures. You may take a look at
system specific build notes (http://kea.isc.org/wiki/SystemSpecificNotes).
For a complete list of systems we build on, you may take a look at the
following build farm report: http://git.kea.isc.org/~tester/builder/KEA-builder-new.html .
following build farm report: https://jenkins.isc.org/view/Kea_BuildFarm/ .
Does your patch conform to Kea coding guidelines
(http://kea.isc.org/wiki/CodingGuidelines)? You can submit a
......@@ -78,6 +78,30 @@ change. That is even more true for new code: if you write a new
function, method or a class, you definitely should write unit-tests
for it.
To ensure that everything is tested, ISC uses a development method
called Test Driven Development (TDD). In TDD, a feature is developed
alongside the tests, with the tests being written first. In detail,
a test is written for a small piece of functionality and run against
the existing code. (In the case where the test is a unit test for
a function, it would be run against an empty (unimplemented)
function.) The test should fail. A minimal amount of code is then
written, just enough to get the test to pass. Then the process is
repeated for the next small piece of functionality. This continues
until all the functionality has been implemented.
This approach has two advantages:
- By writing a test first and then only enough code to pass the
test, that code is fully tested. By repeating this process until
the feature is fully implemented, all the code gets test coverage.
You avoid the situation where not enough tests have been written
to check all the code.
- By running the test before the code implementing the function is
written and observing the test fail, you can detect the situation
where a bug in the test code will cause it to pass regardless of
the code being tested.
See @ref qaUnitTests for instructions on how to run unit-tests.
If you happen to add new files or have modified any \c Makefile.am
......@@ -94,10 +118,10 @@ checks on logger parameters. Use \c --enable-debug to enable various
additional consistency checks that reduce performance but help during
development. If you happen to modify anything in the
documentation, use \c --enable-generate-docs. If you are modifying DHCP
code, you are likely to be interested in enabling a database backend for
DHCP. Note that if the backend is not enabled, the database-specific unit-tests
are skipped. To enable the MySQL backend, use the switch
\c --with-dhcp-mysql; for PostgreSQL, use \c --with-dhcp-pgsql.
code, you are likely to be interested in enabling a non-default database
backends for DHCP. Note that if the backend is not enabled,
the database-specific unit-tests are skipped. To enable the MySQL backend,
use the switch \c --with-dhcp-mysql; for PostgreSQL, use \c --with-dhcp-pgsql.
A complete list of all switches can be obtained with the command:
@code
......
......@@ -15,12 +15,12 @@
/**
* @mainpage Kea Developer's Guide
*
* Welcome to Kea Developer's Guide. This documentation is addressed
* at existing and prospecting developers and programmers and provides
* information needed to both extend and maintain Kea.
*
* Welcome to Kea Developer's Guide. This documentation is addressed at
* either existing or prospective Kea developers and contributors, and
* provides information needed to extend and maintain Kea.
* If you wish to write "hook" code - code that is loaded by Kea at
* run-time and modifies its behavior you should read the section
* run-time and modifies its behavior, you should read the section
* @ref hooksdgDevelopersGuide.
*
* Kea maintenance information is divided into a number of sections
......@@ -30,8 +30,11 @@
*
* If you are a user or system administrator, rather than software engineer,
* you should read the
* <a href="http://kea.isc.org/docs/bind10-guide.html">Kea
* Administrator Reference Manual</a> instead.
* <a href="http://kea.isc.org/docs/kea-guide.html">Kea
* Administrator Reference Manual</a> instead. If you are using a beta or
* development version of Kea, the
* <a href="http://git.kea.isc.org/~tester/kea/guide/kea-guide.html">
* development version of the manual</a> is recommended.
*
* Regardless of your field of expertise, you are encouraged to visit the
* <a href="http://kea.isc.org/">Kea webpage (http://kea.isc.org)</a>
......@@ -117,10 +120,5 @@
* - @subpage SocketSessionUtility
* - <a href="./doxygen-error.log">Documentation warnings and errors</a>
*
* @image html isc-logo.png
*/
/*
* @todo: Move the logo to the right (and possibly up). Not sure what
* is the best way to do it in Doxygen, without using CSS hacks.
*/
doc/images/isc-logo.png

12.3 KB | W: | H:

doc/images/isc-logo.png

5.76 KB | W: | H:

doc/images/isc-logo.png
doc/images/isc-logo.png
doc/images/isc-logo.png
doc/images/isc-logo.png
  • 2-up
  • Swipe
  • Onion skin
......@@ -15,46 +15,136 @@
/**
@page dhcp4 DHCPv4 Server Component
Kea offers DHCPv4 server implementation. It is implemented as
kea-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 transmit 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.
Kea includes the "kea-dhcp4" component, which is the DHCPv4 server
implementation. This component is built around the
@ref isc::dhcp::Dhcpv4Srv class which controls all major operations
performed by the server such as: DHCP messages processing, callouts
execution for many hook points, FQDN processing and interactions with the
"kea-dhcp-ddns" component, lease allocation, system signals handling etc.
The "kea-dhcp4" component requires linking with many different libraries
to obtain access to common functions like: interfaces and sockets
management, configuration parsing, leases management and allocation,
hooks infrastructure, statistics management etc.
The following sections walk through some of the details of the "kea-dhcp4"
component implementation.
@section dhcpv4ConfigParser Configuration Parser in DHCPv4
This parser follows exactly the same logic as its DHCPv6 counterpart.
See \ref dhcpv6ConfigParser.
The common configuration parsers for the DHCP servers are located in the
src/lib/dhcpsrv/parsers/ directory. Parsers specific to the DHCPv4 component
are located in the src/bin/dhcp4/json_config_parser.cc. These parsers derive
from the common configuration parsers and customize their behavior. For
example: the @c Subnet4ConfigParser is used to parse parameters
describing a single subnet. It derives from the @c
isc::dhcp::SubnetConfigParser, which implements the common base for both
DHCPv4 and DHCPv6 subnets. The @ref isc::dhcp::Subnet4ConfigParser
implements the @c initSubnet abstract method, which creates an instance of
the DHCPv4 subnet. This method is invoked by the parent class.
Some parsers for the DHCPv4 server derive from the isc::dhcp::DhcpConfigParser
class directly. This is an abstract class, defining a basic interface for
all configuration parsers. All DHCPv4 parsers deriving from this class
directly have their entire implementation in the
src/bin/dhcp4/json_config_parser.cc.
@section dhcpv4ConfigInherit DHCPv4 configuration inheritance
Configuration inheritance in DHCPv4 follows exactly the same logic as its DHCPv6
counterpart. See \ref dhcpv6ConfigInherit.
One notable useful feature of DHCP configuration is its parameter inheritance.
For example, "renew-timer" value may be specified at a global scope and it then
applies to all subnets. However, some subnets may have it overwritten with subnet
specific values that takes precedence over global values that are considered
defaults. The parameters inheritance is implemented by means of the "global
context". The global context is represented by the @ref isc::dhcp::ParserContext
class and it holds pointers to storage of different kinds, e.g. text parameters,
numeric parameters etc. When the server is parsing the top level configuration
parameters it passes pointers to the storages of the appropriate kind, to the
parsers being invoked to parse the global values. Parsers will store the
parsed values into these storages. Once the global parameters are stored in the
global context, the parsers for the nested configuration parameters are invoked.
These parsers check the presence of the parameters overriding the values of
the global parameters. If a value is not present, the values from the global
context is used.
A good example of inheritance is the implementation of the @ref
isc::dhcp::SubnetConfigParser. The @c getParam method is used throughout the
class to obtain values of the parameters defining a subnet. It first checks
if the specific value is present in the local values storage. If it is not
present, it uses the value from the global context.
@code
isc::dhcp::Triplet<uint32_t>
SubnetConfigParser::getParam(const std::string& name) {
uint32_t value = 0;
try {
// look for local value
value = uint32_values_->getParam(name);
} catch (const DhcpConfigError &) {
try {
// no local, use global value
value = global_context_->uint32_values_->getParam(name);
} catch (const DhcpConfigError &) {
isc_throw(DhcpConfigError, "Mandatory parameter " << name
<< " missing (no global default and no subnet-"
<< "specific value)");
}
}
return (Triplet<uint32_t>(value));
}
@endcode
Note that if the value is neither present in the local storage nor in the global
context an error is signalled.
Parameter inheritance is done once, during the reconfiguration phase.
Reconfigurations are rare, so extra logic here is not a problem. On the other
hand, values of those parameters may be used thousands times per second, so
access to these parameters must be as efficient as possible. In fact,
currently the code has to only call @c Subnet4::getT1(), regardless if the
"renew-timer" has been specified as a global or subnet specific value.
Debugging a configuration parser may be confusing. Therefore there is a special
class called DebugParser. It does not configure anything, but just
accepts any parameter of any type. If requested to commit configuration, it will
print out received parameter name and its value. This class is not currently used,
but it is convenient to have it every time a new parameter is added to the DHCP
configuration. For that purpose it should be left in the code.
@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.
The DHCPv4 server implementation provides a generic support to define option
formats and set option values. A number of options formats have been defined
for standard options in libdhcp++. However, the formats for vendor specific
options are dynamically configured by the server's administrator and thus can't
be stored in libdhcp++. Such option formats are stored in the
@ref isc::dhcp::CfgMgr. The libdhcp++ provides functions for recursive parsing
of options which may be encapsulated by other options up to any level of
encapsulation, but these functions are unaware of the option formats defined
in the @ref isc::dhcp::CfgMgr because they belong to a different library.
Therefore, the generic functions @ref isc::dhcp::LibDHCP::unpackOptions4 and
@ref isc::dhcp::LibDHCP::unpackOptions6 are only useful to parse standard
options whose definitions are provided in the libdhcp++. In order to overcome
this problem a callback mechanism has been implemented in @c Option and @c Pkt4
classes. By installing a callback function on an instance of @c Pkt4, the
server may provide a custom implementation of the options parsing algorithm.
This callback function will take precedence over the @c LibDHCP::unpackOptions4
and @c LibDHCP::unpackOptions6 functions. With this approach, the callback is
implemented within the context of the server and it has access to all objects
which define its configuration (including dynamically created option
definitions).
@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
The DHCPv4 server supports processing of the DHCPv4 Client FQDN option (RFC4702)
and the DHCPv4 Host Name option (RFC2132). A 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
The 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.
......@@ -79,8 +169,8 @@ 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
The server may generate one NameChangeRequest in the case where a client acquires a new
lease or it releases an existing one. In the former case, the NameChangeRequest
type is CHG_ADD, which indicates that the kea-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
......@@ -92,15 +182,15 @@ 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 server may generate two NameChangeRequests in the case where 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
......@@ -109,7 +199,7 @@ 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
@todo Note: the 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,
......@@ -117,7 +207,7 @@ these constants will be removed.
@section dhcpv4Classifier DHCPv4 Client Classification
Kea DHCPv4 server currently supports simplified client classification. It is called
The 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.
......@@ -201,16 +291,12 @@ through the main loop. This method fetches the last received signal and calls
a handler function defined in the kea_controller.cc. The handler function
calls a static function @c configure defined in the kea_controller.cc.
In order for the signal handler to know the location of the configuration file
(specified at process startup), the location of this file needs to be stored
in a static variable so as it may be directly accessed by the signal handler.
This static variable is stored in the @c dhcp::Daemon class and all Kea processes
can use it (all processes derive from this class). The configuration file
location is initialized when the @c Daemon::init method is called. Therefore,
derived classes should call it in their implementations of the @c init method.
The signal handler reconfigures the server using the configuration file
specified at server startup. The location of this file is held in the
@c Daemon class.
@section dhcpv4Other Other DHCPv4 topics
For hooks API support in DHCPv4, see @ref dhcpv4Hooks.
For hooks API support in DHCPv4, see @ref dhcpv4Hooks.
*/
// Copyright (C) 2013 Internet Systems Consortium, Inc. ("ISC")
// Copyright (C) 2013-2015 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
......@@ -22,7 +22,7 @@
the @ref hooksdgDevelopersGuide. Information for Kea maintainers can be
found in the @ref hooksComponentDeveloperGuide.
This manual is more specialised and is aimed at developers of hook
This manual is more specialized and is aimed at developers of hook
code for the DHCPv4 server. It describes each hook point, what the callouts
attached to the hook are able to do, and the arguments passed to the
callouts. Each entry in this manual has the following information:
......@@ -54,23 +54,25 @@ packet processing. Hook points that are not specific to packet processing
- @b Arguments:
- name: @b query4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
- @b Description: this callout is executed when an incoming DHCPv4
buffer is received, before its content is parsed. The sole argument
- query4 - contains a pointer to an isc::dhcp::Pkt4 object that
contains raw information regarding incoming packet, including its
source and destination addresses, interface over which it was
received, and a raw buffer stored in data_ field. None of the
packet fields (op_, hlen_, chaddr_, etc.) are set yet. Callouts
installed on this hook point can modify the incoming buffer. The
server will parse the buffer afterwards.
- @b Description: this callout is executed when the server has received a
buffer containing a DHCPv4 message, but the message hasn't yet been parsed.
The sole argument "query4" contains a pointer to the isc::dhcp::Pkt4
object, which contains the source and destination address of the
received packet, the interface over which the packet has been received, and
a raw buffer, stored in the data_ field, containing the DHCPv4 message
in the wire format. None of the packet fields (op_, hlen_, chaddr_, etc.)
are set yet. Callouts installed on this hook point can modify the data
in the received buffer. The server will parse the buffer afterwards.
- <b>Skip flag action</b>: If any callout sets the skip flag, the server will
skip the buffer parsing. In such case there is an expectation that
the callout will parse the buffer and create option objects (see
isc::dhcp::Pkt4::addOption()). Otherwise the server will find out
that some mandatory options are missing (e.g. DHCP Message Type) and
will drop the packet. If you want to have the capability to drop
a message, it is better to use skip flag in pkt4_receive callout.
skip the buffer parsing. In this case there is an expectation that
the callout will parse the options carried in the buffer, create
@c isc::dhcp::Option objects (or derived) and add them to the "query4"
object using the @c isc::dhcp::Pkt4::addOption.
Otherwise the server will find out that some mandatory options are
missing (e.g. DHCP Message Type) and will drop the message. If you
want to have the capability to drop a message, it is better to use
the skip flag in the "pkt4_receive" callout.
@subsection dhcpv4HooksPkt4Receive pkt4_receive
......@@ -79,15 +81,14 @@ packet processing. Hook points that are not specific to packet processing
- @b Description: this callout is executed when an incoming DHCPv4
packet is received and its content has been parsed. The sole
argument - query4 - contains a pointer to an isc::dhcp::Pkt4 object
argument "query4" contains a pointer to an isc::dhcp::Pkt4 object
that contains all information regarding incoming packet, including
its source and destination addresses, interface over which it was
received, a list of all options present within and relay
received, a list of all options present within and the relay
information. All fields of the Pkt4 object can be modified at this
time, except data_. (By the time this hook is reached, the contents
of the data_ field has been already parsed and stored in other
fields. Therefore, the modification in the data_ field has no
effect.)
time. By the time this hook is reached, the contents of the data_
field has been already parsed and stored in other fields. Therefore,
the modification in the data_ field has no effect.
- <b>Skip flag action</b>: If any callout sets the skip flag, the server will
drop the packet and start processing the next one. The reason for the drop
......@@ -98,19 +99,19 @@ packet processing. Hook points that are not specific to packet processing
- @b Arguments:
- name: @b query4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
- name: @b subnet4, type: isc::dhcp::Subnet4Ptr, direction: <b>in/out</b>
- name: @b subnet4collection, type: const isc::dhcp::Subnet4Collection *, direction: <b>in</b>
- name: @b subnet4collection, type: const isc::dhcp::Subnet4Collection *,
direction: <b>in</b>
- @b Description: this callout is executed when a subnet is being
selected for the incoming packet. All parameters and addresses
will be assigned from that subnet. A callout can select a
different subnet if it wishes so, the list of all subnets currently
configured being provided as 'subnet4collection'. The list itself must
different subnet if it wishes so. The list of all subnets currently
configured are provided as "subnet4collection". The list itself must
not be modified.
- <b>Skip flag action</b>: If any callout installed on 'subnet4_select'
- <b>Skip flag action</b>: If any callout, installed on "subnet4_select",
sets the skip flag, the server will not select any subnet. Packet processing
will continue, but will be severely limited (i.e. only global options
will be assigned).
will continue, but will be severely limited.
@subsection dhcpv4HooksLeaseSelect lease4_select
......@@ -120,22 +121,24 @@ packet processing. Hook points that are not specific to packet processing
- name: @b lease4, type: isc::dhcp::Lease4Ptr, direction: <b>in/out</b>
- @b Description: this callout is executed after the server engine
has selected a lease for client's request but before the lease has
has selected a lease for the client's request, but before the lease has
been inserted into the database. Any modifications made to the
isc::dhcp::Lease4 object will be stored in the lease's record in
the database. The callout should sanity check all modifications as
the server will use that data as is with no further checking.\n\n
The server processes lease requests for DISCOVER and REQUEST in a
very similar way. The only major difference is that for DISCOVER
the lease is just selected, but not inserted into the database. It
is possible to distinguish between DISCOVER and REQUEST by checking
value of the fake_allocation flag: a value of true indicates that the
lease won't be inserted into the database (DISCOVER), a value of
false indicates that it will (REQUEST).
- <b>Skip flag action</b>: If any callout installed on 'lease4_select'
sets the skip flag, the server will not assign any lease. Packet
processing will continue, but client will not get an address.
"lease4" object will affect the lease's record in the database.
The callout should sanity check all modifications as the server will
use that data as is, with no further checking.\n\n
The server processes lease requests for DHCPDISCOVER and DHCPREQUEST in a
very similar way. The only major difference is that for DHCPDISCOVER
the lease is only selected, but not inserted into the database. The callouts
may distinguish between DHCPDISCOVER and DHCPREQUEST by checking the
value of the "fake_allocation" flag: a value of true indicates that the
lease won't be inserted into the database (DHCPDISCOVER case), a value of
false indicates that it will (DHCPREQUEST case).
- <b>Skip flag action</b>: If any callout installed on "lease4_select"
sets the skip flag, the server will not assign any lease and the callouts
become responsible for the lease assignment. If the callouts fail to provide
a lease, the packet processing will continue, but client will not get
an address.
@subsection dhcpv4HooksLeaseRenew lease4_renew
......@@ -146,15 +149,15 @@ packet processing. Hook points that are not specific to packet processing
- name: @b lease4, type: isc::dhcp::Lease4Ptr, direction: <b>in/out</b>
- @b Description: this callout is executed when the server engine
is about to renew a lease, as a result of receiving REQUEST/Renewing
packet. The lease4 argument points to Lease4 object that contains
the updated values. Callout can modify those values. Care should be taken
as the server will attempt to update the lease in the database without
any additional checks.
is about to renew a lease, as a result of receiving DHCPREQUEST/Renewing
packet. The "lease4" argument points to @c isc::dhcp::Lease4 object that
contains the updated values. Callout can modify those values. Care should
be taken as the server will attempt to update the lease in the database
without any additional checks.
- <b>Skip flag action</b>: If any callout installed on 'lease4_renew'
sets the skip flag, the server will not update the lease and will
use old values instead.
- <b>Skip flag action</b>: If any callout installed on "lease4_renew"
sets the skip flag, the server will not update the lease in the
database and will continue using the old values instead.
@subsection dhcpv4HooksLeaseRelease lease4_release
......@@ -163,11 +166,11 @@ packet processing. Hook points that are not specific to packet processing
- name: @b lease4, type: isc::dhcp::Lease4Ptr, direction: <b>in</b>
- @b Description: this callout is executed when the server engine
is about to release a lease, as a result of receiving RELEASE packet.
The lease4 argument points to Lease4 object that contains the lease to
is about to release a lease, as a result of receiving DHCPRELEASE packet.
The "lease4" argument points to @c Lease4 object that contains the lease to
be released. It doesn't make sense to modify it at this time.
- <b>Skip flag action</b>: If any callout installed on 'lease4_release'
- <b>Skip flag action</b>: If any callout installed on "lease4_release"
sets the skip flag, the server will not delete the lease. It will be
kept in the database and will go through the regular expiration/reuse
process.
......@@ -178,17 +181,17 @@ packet processing. Hook points that are not specific to packet processing
- name: @b response4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
- @b Description: this callout is executed when server's response
is about to be sent back to the client. The sole argument - response4 -
contains a pointer to an isc::dhcp::Pkt4 object that contains the
is about to be sent back to the client. The sole argument "response4"
contains a pointer to an isc::dhcp::Pkt4 object carrying the
packet, with source and destination addresses set, interface over which
it will be sent, and a list of all options and relay information. All fields
of the Pkt4 object can be modified at this time, except buffer_out_.
of the @c Pkt4 object can be modified at this time, except @c buffer_out_.
(This is scratch space used for constructing the packet after all
pkt4_send callouts are complete, so any changes to that field will
be overwritten.)
- <b>Skip flag action</b>: if any callout sets the skip flag, the server
will not construct raw buffer. The expectation is that if the callout
will not construct the raw buffer. The expectation is that if the callout
set skip flag, it is responsible for constructing raw form on its own.
Otherwise the output packet will be sent with zero length.
......@@ -198,17 +201,19 @@ packet processing. Hook points that are not specific to packet processing
- name: @b response4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
- @b Description: this callout is executed when server's response
is about to be sent back to the client. The sole argument - response4 -
contains a pointer to an isc::dhcp::Pkt4 object that contains the
is about to be sent back to the client. The sole argument "response4"
contains a pointer to an @c isc::dhcp::Pkt4 object that contains the
packet, with source and destination addresses set, interface over which
it will be sent, and a list of all options and relay information. The raw
on-wire form is already prepared in buffer_out_ (see isc::dhcp::Pkt4::getBuffer())
It doesn't make any sense to modify packet fields or options content
at this time, because they were already used to construct on-wire buffer.
on-wire form is already prepared in @c buffer_out_ (see
@c isc::dhcp::Pkt4::getBuffer())
Callouts should not modify the packet fields or options contents at this
time, because they were already used to construct on-wire buffer. Their
modification would have no effect.
- <b>Skip flag action</b>: if any callout sets the skip flag, the server
will drop this response packet. However, the original request packet
from a client was processed, so server's state was most likely changed
from a client was processed, so server's state most likely has changed
(e.g. lease was allocated). Setting this flag merely stops the change
being communicated to the client.
......
......@@ -156,9 +156,6 @@ typedef boost::shared_ptr<Dhcpv4Exchange> Dhcpv4ExchangePtr;
/// This class does not support any controlling mechanisms directly.
/// See the derived \ref ControlledDhcpv4Srv class for support for
/// command and configuration updates over msgq.
///
/// For detailed explanation or relations between main(), ControlledDhcpv4Srv,
/// Dhcpv4Srv and other classes, see \ref dhcpv4Session.
class Dhcpv4Srv : public Daemon {
public:
......
......@@ -33,9 +33,6 @@ using namespace std;
/// instantiates ControlledDhcpv4Srv class that is responsible for establishing
/// connection with msgq (receiving commands and configuration) and also
/// creating Dhcpv4 server object as well.
///
/// For detailed explanation or relations between main(), ControlledDhcpv4Srv,
/// Dhcpv4Srv and other classes, see \ref dhcpv4Session.
namespace {
......
......@@ -15,62 +15,102 @@
/**
@page dhcp6 DHCPv6 Server Component
Kea offers DHCPv6 server implementation. It is implemented as
kea-dhcp6 component. Its primary code is located in
isc::dhcp::Dhcpv6Srv class. It uses \ref libdhcp extensively,
especially lib::dhcp::Pkt6, 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 transmit responses. However, it does not have database
management, so it returns only one, hardcoded lease to whoever asks
for it.
DHCPv6 server component does not support relayed traffic yet, as
support for relay decapsulation is not implemented yet.
@section dhcpv6ConfigParser Configuration Parser in DHCPv6
\note With the implementation of the Kea ticket #3534 we're moving away from
the concept of commit being called for individual parsers. When this ticket
and a couple of followup tickets are implemented, the commit will be a
single operation executed for the whole configuration received from many
parsers.
All parsers are defined in src/bin/dhcp6/config_parser.cc file. Some of them
are generic (e.g. Uint32Parser that is able to handle any
unsigned 32 bit integer), but some are very specialized (e.g.
Subnets6ListConfigParser parses definitions of Subnet6 lists). In some cases,
e.g. subnet6 definitions, the configuration entry is not a simple value, but
a map or a list itself. In such case, the parser iterates over all elements
and creates parsers for a given scope. This process may be repeated (sort of)
recursively.
@section dhcpv6ConfigInherit DHCPv6 Configuration Inheritance
One notable useful feature of DHCP configuration is its parameter inheritance.
For example, renew-timer value may be specified at a global scope and it then
applies to all subnets. However, some subnets may have it overwritten with more
specific values that takes precedence over global values that are considered
defaults. Some parsers (e.g. Uint32Parser and StringParser) implement that
inheritance. By default, they store values in global uint32_defaults and
string_defaults storages. However, it is possible to instruct them to store
parsed values in more specific storages. That capability is used, e.g. in