Commit f81a2220 authored by Stephen Morris's avatar Stephen Morris
Browse files

[3484] Miscellanous editing changes during review

Correction of typos/grammatical errors etc.  Also included text in the
contributors' section explaining why test-driven development is used.
parent ef70dd89
......@@ -76,12 +76,31 @@ almost every line of code. Even if you are fixing something small,
like a single line fix, you are encouraged to write unit-tests for that
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 the test for the specific change is valid, it
should be written before the change is applied. The test should initially
fail. When the change is applied the test should start passing. The
test validating a new function should be written against empty
(unimplemented) function. When the function is implemented, the test
should pass.
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.
......
......@@ -31,7 +31,7 @@
* If you are a user or system administrator, rather than software engineer,
* you should read the
* <a href="http://kea.isc.org/docs/kea-guide.html">Kea
* Administrator Reference Manual</a> instead. If you are using Beta or
* 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.
......
......@@ -57,7 +57,7 @@ applies to all subnets. However, some subnets may have it overwritten with subne
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 storages of different kind, e.g. text parameters,
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
......@@ -120,32 +120,31 @@ 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 the any level of
encapsulation but these functions are unaware of the option formats defined
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::unpackOptions4 are only useful to parse standard
options which definitions are provided in the libdhcp++. In order to overcome
@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 the instance of the @c Pkt4 the
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::unpackOptions4 functions. With this approach, the callback is
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.
......@@ -170,7 +169,7 @@ 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
The server may generate one NameChangeRequest in the case when client acquires a new
lease or it releases an existing lease. 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
......@@ -183,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
......@@ -200,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,
......@@ -208,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.
......@@ -293,11 +292,11 @@ a handler function defined in the kea_controller.cc. The handler function
calls a static function @c configure defined in the kea_controller.cc.
The signal handler reconfigures the server using the configuration file
specified at the server startup. The location of this file is held in the
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.
*/
......@@ -157,7 +157,7 @@ packet processing. Hook points that are not specific to packet processing
- <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 continue using old values instead.
database and will continue using the old values instead.
@subsection dhcpv4HooksLeaseRelease lease4_release
......
......@@ -142,10 +142,10 @@ send them to the kea-dhcp-ddns module when server is idle waiting for DHCP messa
In the simplest case, when client gets one address from the server, a DHCPv6 server
may generate 0, 1 or 2 NameChangeRequests during single message processing.
Server generates no NameChangeRequests if it is not configured to update DNS
The 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 situation when a client acquires a
The server may generate one NameChangeRequest in a situation when a client acquires a
new lease or it releases an existing lease. 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
......@@ -158,7 +158,7 @@ both reverse and forward update) have been performed when the lease was acquired
Server checks this information to make a decision which mapping it is supposed to
remove when a lease is released.
Server may generate 2 NameChangeRequests in case the client is renewing a lease and
The server may generate two NameChangeRequests in case the client is renewing a lease and
it already has a DNS binding for that lease. Note, that renewal may be triggered
as a result of sending a RENEW message as well as the REQUEST message. In both cases
DHCPv6 server will check if there is an existing lease for the client which has sent
......@@ -202,7 +202,7 @@ 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 which definitions are provided in the libdhcp++. In order to overcome
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 Pkt6
classes. By installing a callback function on the instance of the @c Pkt6 the
server may provide a custom implementation of the options parsing algorithm.
......@@ -214,7 +214,7 @@ definitions).
@section dhcpv6Classifier DHCPv6 Client Classification
Kea DHCPv6 server currently supports simplified client classification. It is called
The Kea DHCPv6 server currently supports simplified client classification. It is called
"simplified", because the incoming packets are classified based on the content
of the vendor class (16) option. More flexible classification is planned, but there
are no specific development dates agreed.
......@@ -247,13 +247,14 @@ limited.
@section dhcpv6ConfigBackend Configuration backend for DHCPv6
There are many theoretical ways in which server configuration can be stored.
There are many theoretical ways in which the server configuration can be stored.
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 has introduced configuration backends that are switchable during compilation phase. Currently the only choice is JSON.
Kea 0.9 has introduced configuration backends that are switchable during the
compilation phase. Currently the only choice is JSON.
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
......@@ -296,11 +297,11 @@ a handler function defined in the kea_controller.cc. The handler function
calls a static function @c configure defined in the kea_controller.cc.
The signal handler reconfigures the server using the configuration file
specified at the server startup. The location of this file is held in the
specified at server startup. The location of this file is held in the
@c Daemon class.
@section dhcpv6Other Other DHCPv6 topics
@section dhcpv6Other Other DHCPv6 topics
For hooks API support in DHCPv6, see @ref dhcpv6Hooks.
For hooks API support in DHCPv6, see @ref dhcpv6Hooks.
*/
......@@ -36,10 +36,10 @@ smart pointers using the \c boost::shared_ptr type. There are no const
versions of packet types defined, as we assume that hooks can modify any
aspect of the packet at almost any stage of processing.
Both packet types use collection of \ref isc::dhcp::Option objects to
Both packet types use a collection of \ref isc::dhcp::Option objects to
represent DHCPv4 and DHCPv6 options. The base class @c Option can be used to
represent generic option that contains collection of
bytes. Depending on whether the option is instantiated as DHCPv4 or DHCPv6
bytes. Depending on whether the option is instantiated as a DHCPv4 or DHCPv6
option, it will adjust its header (DHCPv4 options use 1 octet for
type and 1 octet for length, while DHCPv6 options use 2 bytes for
each).
......@@ -50,13 +50,13 @@ specific formats:
- isc::dhcp::Option6AddrLst -- DHCPv6 option, contains one or more IPv6 addresses;
- isc::dhcp::Option4ClientFqdn -- DHCPv4 Client FQDN option;
- isc::dhcp::Option6ClientFqdn -- DHCPv6 Client FQDN option;
- isc::dhcp::Option6IAAddr -- DHCPv6 option, represents IAADDR option (an option that
- isc::dhcp::Option6IAAddr -- DHCPv6 option, represents the IAADDR option (an option that
contains IPv6 address with extra parameters);
- isc::dhcp::Option6IAPrefix -- DHCPv6 option, represents IAPREFIX option (an option
- isc::dhcp::Option6IAPrefix -- DHCPv6 option, represents the IAPREFIX option (an option
that contains IPv6 prefix in prefix delegation);
- isc::dhcp::Option6IA -- DHCPv6 option used to store IA_NA and its suboptions.
- isc::dhcp::Option6StatusCode -- DHCPv6 option, carries a status code to the client;
- isc::dhcp::OptionCustom -- Represents option having many different formats, where
- isc::dhcp::OptionCustom -- Represents an option having many different formats, where
data fields can be accessed in a convenient way;
- isc::dhcp::OptionInt -- DHCPv4 or DHCPv6 option, carries a single numeric value;
- isc::dhcp::OptionString -- DHCPv4 or DHCPv6 option, carries a text value;
......@@ -93,7 +93,7 @@ that interface-id in its copy, when sending data back to the client.
This will be used by the relay to choose proper interface when forwarding
response towards the client.
Pkt6 class has a public \c Pkt6::relay_info_ field, which is of type \c Pkt6::RelayInfo.
The Pkt6 class has a public \c Pkt6::relay_info_ field, which is of type \c Pkt6::RelayInfo.
This is a simple structure that represents the information in each RELAY_FORW
or RELAY_REPL message. It is important to understand the order in which
the data appear here. Consider the following network:
......@@ -125,10 +125,10 @@ network operations. In particlar, it provides information about existing
network interfaces See @ref isc::dhcp::Iface class and
@ref isc::dhcp::IfaceMgr::detectIfaces() and @ref isc::dhcp::IfaceMgr::getIface().
Generic parts of the code are @ref isc::dhcp::IfaceMgr class in
Generic parts of the code are contained in the @ref isc::dhcp::IfaceMgr class in
src/lib/dhcp/iface_mgr.cc file. OS-specific code is located in separate
files, e.g. iface_mgr_linux.cc, iface_mgr_bsd. Such separation should be
maintained when additional code will be developed.
files, e.g. iface_mgr_linux.cc, iface_mgr_bsd. The separation should be
maintained when developing additional code.
Other useful methods are dedicated to transmission
(\ref isc::dhcp::IfaceMgr::send(), 2 overloads) and reception
......
......@@ -205,7 +205,7 @@ host all all ::1/128 password
Please consult your PostgreSQL user manual before applying those changes as
those changes may expose your other databases that you run on the same system.
In general case, it is a poor idea to run anything of value on a system
that runs tests. Use caution!§
that runs tests. Use caution!
The unit tests are run automatically when "make check" is executed (providing
that Kea has been build with the \--with-dhcp-pgsql switch (see the installation
......
......@@ -15,36 +15,35 @@
/**
@page libdhcpsrv libdhcpsrv - Server DHCP library
This library contains code used for DHCPv4 and DHCPv6 servers' operations,
including "Lease Manager" that manages information about leases,
"Configuration Manager" that stores servers' configuration etc.
The code here is server specific. For generic (useful by server,
This library contains code used for the DHCPv4 and DHCPv6 servers' operations,
including the "Lease Manager" that manages information about leases and the
"Configuration Manager" that stores the servers' configuration etc.
The code here is server specific. For generic (useful to the server,
client, relay and other tools like perfdhcp) code, please see
\ref libdhcp.
This library contains several crucial elements for the DHCP server operation:
This library contains several crucial elements for the operation of the DHCP server:
- isc::dhcp::LeaseMgr - lease manager is a name for database backend that stores
- isc::dhcp::LeaseMgr - lease manager is the name for the database backend that stores
leases.
- isc::dhcp::CfgMgr - configuration manager that holds DHCP specific
configuration information (subnets, pools, options, timer values etc.) in
easy to use format.
- isc::dhcp::AllocEngine - allocation engine that handles new requestes and allocates new
- isc::dhcp::AllocEngine - allocation engine that handles new requests and allocates new
leases.
- isc::dhcp::HostMgr - manager for static reservations, a.k.a. as host
reservations.
- isc::dhcp::D2ClientMgr - D2 client manager which is responsible for
- isc::dhcp::HostMgr - manager for static reservations (a.k.a. host reservations).
- isc::dhcp::D2ClientMgr - DHCP-DDNS (D2) client manager which is responsible for
the communication between the DHCP server and the D2 component.
@section leasemgr Lease Manager
LeaseMgr provides a common, unified abstract API for all database backends. All
backends are derived from the base class isc::dhcp::LeaseMgr. Currently Kea
supports three backends implemented in the following classes:
supports three backends, implemented in the following classes:
- isc::dhcp::Memfile_LeaseMgr - stores leases in the CSV file,
- isc::dhcp::MySqlLeaseMgr - stores leases in the MySQL database
- isc::dhcp::PgSqlLeaseMgr - stores leases in the PostgreSQL database
- isc::dhcp::Memfile_LeaseMgr - stores leases in a CSV file,
- isc::dhcp::MySqlLeaseMgr - stores leases in a MySQL database
- isc::dhcp::PgSqlLeaseMgr - stores leases in a PostgreSQL database
@section cfgmgr Configuration Manager
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment