mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-08-22 01:49:48 +00:00
Code Issues Releases Wiki Activity

rearranges docs and build script

Browse Source 
Two reasons:
- sphinx requires to have all sources in its source directory
  so man pages have to be moved
- layout of subfolders in doc folder was not consistent
This commit is contained in:
Michal Nowikowski 2019-07-17 15:42:19 +02:00
parent 556016fc34
commit 01fb9fd370
226 changed files with 3301 additions and 36362 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
configure.ac
View File

@ -1566,9 +1566,8 @@ fi
AC_CONFIG_FILES([Makefile
doc/Makefile
doc/guide/Makefile
doc/version.ent
doc/docgen/Makefile
doc/sphinx/Makefile
doc/devel/Makefile
ext/Makefile
ext/gtest/Makefile
ext/coroutine/Makefile

162
doc/Makefile.am
View File

@ -1,14 +1,4 @@
SUBDIRS = guide docgen
EXTRA_DIST = version.ent.in Doxyfile Doxyfile-xml
EXTRA_DIST += devel/bison.dox
EXTRA_DIST += devel/config-backend.dox
EXTRA_DIST += devel/contribute.dox
EXTRA_DIST += devel/mainpage.dox
EXTRA_DIST += devel/terminology.dox
EXTRA_DIST += devel/unit-tests.dox
EXTRA_DIST += devel/doc.dox
EXTRA_DIST += devel/congestion-handling.dox
SUBDIRS = devel sphinx
nobase_dist_doc_DATA = examples/agent/comments.json
nobase_dist_doc_DATA += examples/agent/simple.json
@ -77,153 +67,3 @@ nobase_dist_doc_DATA += examples/netconf/kea-dhcp6-operations/twosubnets.xml
nobase_dist_doc_DATA += examples/netconf/comments.json
nobase_dist_doc_DATA += examples/netconf/simple-dhcp4.json
nobase_dist_doc_DATA += examples/netconf/simple-dhcp6.json
# These are files that document our APIs. They're not really needed as the
# content is included in the api.xml, but may be useful for people who
# want to document the API.
EXTRA_DIST += api/build-report.json
EXTRA_DIST += api/cache-clear.json api/cache-get.json
EXTRA_DIST += api/cache-get-by-id.json api/cache-insert.json
EXTRA_DIST += api/cache-load.json api/cache-remove.json
EXTRA_DIST += api/cache-size.json api/cache-write.json
EXTRA_DIST += api/class-add.json api/class-del.json
EXTRA_DIST += api/class-get.json api/class-list.json
EXTRA_DIST += api/class-update.json
EXTRA_DIST += api/config-get.json api/config-reload.json
EXTRA_DIST += api/config-set.json api/config-test.json
EXTRA_DIST += api/config-write.json api/dhcp-disable.json
EXTRA_DIST += api/dhcp-enable.json api/ha-continue.json
EXTRA_DIST += api/ha-heartbeat.json api/ha-scopes.json
EXTRA_DIST += api/ha-sync.json api/lease4-add.json
EXTRA_DIST += api/lease4-del.json api/lease4-get-all.json
EXTRA_DIST += api/lease4-get.json api/lease4-update.json
EXTRA_DIST += api/lease4-wipe.json api/lease6-add.json
EXTRA_DIST += api/lease6-bulk-apply.json
EXTRA_DIST += api/lease6-del.json api/lease6-get-all.json
EXTRA_DIST += api/lease6-get.json api/lease6-update.json
EXTRA_DIST += api/lease6-wipe.json api/leases-reclaim.json
EXTRA_DIST += api/libreload.json api/list-commands.json
EXTRA_DIST += api/network4-add.json api/network4-del.json
EXTRA_DIST += api/network4-get.json api/network4-list.json
EXTRA_DIST += api/network4-subnet-add.json api/network4-subnet-del.json
EXTRA_DIST += api/network6-add.json api/network6-del.json
EXTRA_DIST += api/network6-get.json api/network6-list.json
EXTRA_DIST += api/network6-subnet-add.json api/network6-subnet-del.json
EXTRA_DIST += api/remote-global-parameter4-del.json
EXTRA_DIST += api/remote-global-parameter4-get-all.json
EXTRA_DIST += api/remote-global-parameter4-get.json
EXTRA_DIST += api/remote-global-parameter4-set.json
EXTRA_DIST += api/remote-global-parameter6-del.json
EXTRA_DIST += api/remote-global-parameter6-get-all.json
EXTRA_DIST += api/remote-global-parameter6-get.json
EXTRA_DIST += api/remote-global-parameter6-set.json
EXTRA_DIST += api/remote-network4-del.json
EXTRA_DIST += api/remote-network4-get.json
EXTRA_DIST += api/remote-network4-list.json
EXTRA_DIST += api/remote-network4-set.json
EXTRA_DIST += api/remote-network6-del.json
EXTRA_DIST += api/remote-network6-get.json
EXTRA_DIST += api/remote-network6-list.json
EXTRA_DIST += api/remote-network6-set.json
EXTRA_DIST += api/remote-option-def4-del.json
EXTRA_DIST += api/remote-option-def4-get-all.json
EXTRA_DIST += api/remote-option-def4-get.json
EXTRA_DIST += api/remote-option-def4-set.json
EXTRA_DIST += api/remote-option-def6-del.json
EXTRA_DIST += api/remote-option-def6-get-all.json
EXTRA_DIST += api/remote-option-def6-get.json
EXTRA_DIST += api/remote-option-def6-set.json
EXTRA_DIST += api/remote-option4-global-del.json
EXTRA_DIST += api/remote-option4-global-get-all.json
EXTRA_DIST += api/remote-option4-global-get.json
EXTRA_DIST += api/remote-option4-global-set.json
EXTRA_DIST += api/remote-option6-global-del.json
EXTRA_DIST += api/remote-option6-global-get-all.json
EXTRA_DIST += api/remote-option6-global-get.json
EXTRA_DIST += api/remote-option6-global-set.json
EXTRA_DIST += api/remote-subnet4-del-by-id.json
EXTRA_DIST += api/remote-subnet4-del-by-prefix.json
EXTRA_DIST += api/remote-subnet4-get-by-id.json
EXTRA_DIST += api/remote-subnet4-get-by-prefix.json
EXTRA_DIST += api/remote-subnet4-list.json
EXTRA_DIST += api/remote-subnet4-set.json
EXTRA_DIST += api/remote-subnet6-del-by-id.json
EXTRA_DIST += api/remote-subnet6-del-by-prefix.json
EXTRA_DIST += api/remote-subnet6-get-by-id.json
EXTRA_DIST += api/remote-subnet6-get-by-prefix.json
EXTRA_DIST += api/remote-subnet6-list.json
EXTRA_DIST += api/remote-subnet6-set.json
EXTRA_DIST += api/reservation-add.json api/reservation-del.json
EXTRA_DIST += api/reservation-get.json api/reservation-get-all.json
EXTRA_DIST += api/reservation-get-page.json
EXTRA_DIST += api/server-tag-get.json api/shutdown.json
EXTRA_DIST += api/remote-server4-del.json
EXTRA_DIST += api/remote-server4-get.json
EXTRA_DIST += api/remote-server4-get-all.json
EXTRA_DIST += api/remote-server4-set.json
EXTRA_DIST += api/remote-server6-del.json
EXTRA_DIST += api/remote-server6-get.json
EXTRA_DIST += api/remote-server6-get-all.json
EXTRA_DIST += api/remote-server6-set.json
EXTRA_DIST += api/statistic-get-all.json api/statistic-get.json
EXTRA_DIST += api/statistic-remove-all.json api/statistic-remove.json
EXTRA_DIST += api/statistic-reset-all.json api/statistic-reset.json
EXTRA_DIST += api/stat-lease4-get.json api/stat-lease6-get.json
EXTRA_DIST += api/subnet4-add.json api/subnet4-del.json
EXTRA_DIST += api/subnet4-get.json api/subnet4-list.json
EXTRA_DIST += api/subnet4-update.json
EXTRA_DIST += api/subnet6-add.json api/subnet6-del.json
EXTRA_DIST += api/subnet6-get.json api/subnet6-list.json
EXTRA_DIST += api/subnet6-update.json
EXTRA_DIST += api/_template.json api/version-get.json
devel:
mkdir -p html
(cat Doxyfile; echo PROJECT_NUMBER=$(PACKAGE_VERSION)) | doxygen - > html/doxygen.log 2> html/doxygen-error.log
echo `grep -i ": warning:" html/doxygen-error.log | wc -l` warnings/errors detected.
clean:
rm -rf html
# There are several steps needed to document new API command:
#
# 1. edit docgen/cmds-list and add the new command
# 2. ./configure --enable-generate-docs
# 3. make - you need to build the sources first, am afraid. The reason why you
# need to do this is that the tool kea-docgen depends on libkea-cc as it
# loads JSON files. This means that the libs need to be built first.
# 4. (optional) run: make templates
# This will go through the list of commands listed in cmds-list
# and will check if there are corresponding JSON files in api/name.json
# If the file is missing, a new JSON will be created using template.
# If you dislike this generator, you can always use api/_template.json
# and copy it over under the name of a new command.
# 5. Edit api/command-name.json. If the command is provided by the daemon
# out of its own (and not via hook), simply delete the hook entry.
# If you don't want to provide command syntax (cmd-syntax key),
# any comments about the syntax (cmd-comment key) or response syntax
# (resp-syntax) or any comment about response (resp-comment), simply
# remove those unused keys. The generator will attempt to generate
# boilerplates for it.
# 6. Generate api.xml: make api
# 7. Rebuild User's Guide as usual: make guide
# This target will generate templates. There's no need to run it, unless
# new commands have been added or there are existing commands that are
# still not documented.
templates: docgen
docgen/generate-templates docgen/cmds-list
# This will generate the api.xml file using docgen generator. It will
# read the JSON files from api/ directory. Make sure they're up to date.
api: docgen
docgen/kea-docgen api/*.json
# This convenience target makes sure the docgen tool is built properly
docgen:
$(MAKE) -C docgen
# That's a bit of a hack, but we are making sure that devel target
# is always valid. The alternative is to make devel depend on all
# *.cc *.h files in the whole tree.
.PHONY: devel guide docgen

3
doc/design/datasrc/.gitignore vendored
View File

@ -1,3 +0,0 @@
/*.html
/*.png
/*.xml

366
doc/design/datasrc/data-source-classes.txt
View File

@ -1,366 +0,0 @@
Data Source Library Classes
===========================
About this document
-------------------
This memo describes major classes used in the data source library,
mainly focusing on handling in-memory cache with consideration of the
shared memory support. It will give an overview of the entire design
architecture and some specific details of how these classes are expected
to be used.
Before reading, the higher level inter-module protocol should be understood:
http://bind10.isc.org/wiki/SharedMemoryIPC
Overall relationships between classes
-------------------------------------
The following diagram shows major classes in the data source library
related to in-memory caches and their relationship.
image::overview.png[Class diagram showing overview of relationships]
Major design decisions of this architecture are:
* Keep each class as concise as possible, each focusing on one or
small set of responsibilities. Smaller classes are generally easier
to understand (at the cost of understanding how they work in the
"big picture" of course) and easier to test.
* On a related point, minimize dependency to any single class. A
monolithic class on which many others are dependent is generally
difficult to maintain because you'll need to ensure a change to the
monolithic class doesn't break anything on any other classes.
* Use polymorphism for any "fluid" behavior, and hide specific details
under abstract interfaces so implementation details won't be
directly referenced from any other part of the library.
Specifically, the underlying memory segment type (local, mapped, and
possibly others) and the source of in-memory data (master file or
other data source) are hidden via a kind of polymorphism.
* Separate classes directly used by applications from classes that
implement details. Make the former classes as generic as possible,
agnostic about implementation specific details such as the memory
segment type (or, ideally and where possible, whether it's for
in-memory cache or the underlying data source).
The following give a summarized description of these classes.
* `ConfigurableClientList`: The front end to application classes. An
application that uses the data source library generally maintains
one or more `ConfigurableClientList` object (usually one per RR
class, or when we support views, probably one per view). This class
is a container of sets of data source related classes, providing
accessor to these classes and also acting as a factory of other
related class objects. Note: Due to internal implementation
reasons, there is a base class for `ConfigurableClientList` named
`ClientList` in the C++ version, and applications are expected to
use the latter. But conceptually `ConfigurableClientList` is an
independent value class; the inheritance is not for polymorphism.
Note also that the Python version doesn't have the base class.
* `DataSourceInfo`: this is a straightforward tuple of set of class
objects corresponding to a single data source, including
`DataSourceClient`, `CacheConfig`, and `ZoneTableSegment`.
`ConfigurableClientList` maintains a list of `DataSourceInfo`, one
for each data source specified in its configuration.
* `DataSourceClient`: The front end class to applications for a single
data source. Applications will get a specific `DataSourceClient`
object by `ConfigurableClientList::find()`.
`DataSourceClient` itself is a set of factories for various
operations on the data source such as lookup or update.
* `CacheConfig`: library internal representation of in-memory cache
configuration for a data source. It knows which zones are to be
cached and where the zone data (RRs) should come from, either from a
master file or other data source. With this knowledge it will
create an appropriate `LoadAction` object. Note that `CacheConfig`
isn't aware of the underlying memory segment type for the in-memory
data. It's intentionally separated from this class (see the
conciseness and minimal-dependency design decisions above).
* `ZoneTableSegment`: when in-memory cache is enabled, it provides
memory-segment-type independent interface to the in-memory data.
This is an abstract base class (see polymorphism in the design
decisions) and inherited by segment-type specific subclasses:
`ZoneTableSegmentLocal` and `ZoneTableSegmentMapped` (and possibly
others). Any subclass of `ZoneTableSegment` is expected to maintain
the specific type of `MemorySegment` object.
* `ZoneWriter`: a frontend utility class for applications to update
in-memory zone data (currently it can only load a whole zone and
replace any existing zone content with a new one, but this should be
extended so it can handle partial updates).
Applications will get a specific `ZoneWriter`
object by `ConfigurableClientList::getCachedZoneWriter()`.
`ZoneWriter` is constructed with `ZoneableSegment` and `LoadAction`.
Since these are abstract classes, `ZoneWriter` doesn't have to be
aware of "fluid" details. It's only responsible for "somehow" preparing
`ZoneData` for a new version of a specified zone using `LoadAction`,
and installing it in the `ZoneTable` (which can be accessed via
`ZoneTableSegment`).
* `DataSourceStatus`: created by `ConfigurableClientList::getStatus()`,
a straightforward tuple that represents some status information of a
specific data source managed in the `ConfigurableClientList`.
`getStatus()` generates `DataSourceStatus` for all data sources
managed in it, and returns them as a vector.
* `ZoneTableAccessor`, `ZoneTableIterator`: frontend classes to get
access to the conceptual "zone table" (a set of zones) stored in a
specific data source. In particular, `ZoneTableIterator` allows
applications to iterate over all zones (by name) stored in the
specific data source.
Applications will get a specific `ZoneTableAccessor`
object by `ConfigurableClientList::getZoneTableAccessor()`,
and get an iterator object by calling `getIterator` on the accessor.
These are abstract classes and provide unified interfaces
independent from whether it's for in-memory cached zones or "real"
underlying data source. But the initial implementation only
provides the in-memory cache version of subclass (see the next
item).
* `ZoneTableAccessorCache`, `ZoneTableIteratorCache`: implementation
classes of `ZoneTableAccessor` and `ZoneTableIterator` for in-memory
cache. They refer to `CacheConfig` to get a list of zones to be
cached.
* `ZoneTableHeader`, `ZoneTable`: top-level interface to actual
in-memory data. These were separated based on a prior version of
the design (http://bind10.isc.org/wiki/ScalableZoneLoadDesign) where
`ZoneTableHeader` may contain multiple `ZoneTable`s. It's
one-to-one relationship in the latest version (of implementation),
so we could probably unify them as a cleanup.
* `ZoneData`: representing the in-memory content of a single zone.
`ZoneTable` contains (zero, one or) multiple `ZoneData` objects.
* `RdataSet`: representing the in-memory content of (data of) a single
RRset.
`ZoneData` contains `RdataSet`s corresponding to the RRsets stored
in the zone.
* `LoadAction`: a "polymorphic" functor that implements loading zone
data into memory. It hides from its user (i.e., `ZoneWriter`)
details about the source of the data: master file or other data
source (and perhaps some others). The "polymorphism" is actually
realized as different implementations of the functor interface, not
class inheritance (but conceptually the effect and goal is the
same). Note: there's a proposal to replace `LoadAction` with
a revised `ZoneDataLoader`, although the overall concept doesn't
change. See Trac ticket #2912.
* `ZoneDataLoader` and `ZoneDataUpdater`: helper classes for the
`LoadAction` functor(s). These work independently from the source
of data, taking a sequence of RRsets objects, converting them
into the in-memory data structures (`RdataSet`), and installing them
into a newly created `ZoneData` object.
Sequence for auth module using local memory segment
---------------------------------------------------
In the remaining sections, we explain how the classes shown in the
previous section work together through their methods for commonly
intended operations.
The following sequence diagram shows the case for the authoritative
DNS server module to maintain "local" in-memory data. Note that
"auth" is a conceptual "class" (not actually implemented as a C++
class) to represent the server application behavior. For the purpose
of this document that should be sufficient. The same note applies to
all examples below.
image::auth-local.png[Sequence diagram for auth server using local memory segment]
1. On startup, the auth module creates a `ConfigurableClientList`
for each RR class specified in the configuration for "data_sources"
module. It then calls `ConfigurableClientList::configure()`
for the given configuration of that RR class.
2. For each data source, `ConfigurableClientList` creates a
`CacheConfig` object with the corresponding cache related
configuration.
3. If in-memory cache is enabled for the data source,
`ZoneTableSegment` is also created. In this scenario the cache
type is specified as "local" in the configuration, so a functor
creates `ZoneTableSegmentLocal` as the actual instance.
In this case its `ZoneTable` is immediately created, too.
4. `ConfigurableClientList` checks if the created `ZoneTableSegment` is
writable. It is always so for "local" type of segments. So
`ConfigurableClientList` immediately loads zones to be cached into
memory. For each such zone, it first gets the appropriate
`LoadAction` through `CacheConfig`, then creates `ZoneWriter` with
the `LoadAction`, and loads the data using the writer.
5. If the auth module receives a "reload" command for a cached zone
from other module (xfrin, an end user, etc), it calls
`ConfigurableClientList::getCachedZoneWriter` to load and install
the new version of the zone. The same loading sequence takes place
except that the user of the writer is the auth module.
Also, the old version of the zone data is destroyed at the end of
the process.
Sequence for auth module using mapped memory segment
----------------------------------------------------
This is an example for the authoritative server module that uses
mapped type memory segment for in-memory data.
image::auth-mapped.png[Sequence diagram for auth server using mapped memory segment]
1. The sequence is the same to the point of creating `CacheConfig`.
2. But in this case a `ZoneTableSegmentMapped` object is created based
on the configuration of the cache type. This type of
`ZoneTableSegment` is initially empty and isn't even associated
with a `MemorySegment` (and therefore considered non-writable).
3. `ConfigurableClientList` checks if the zone table segment is
writable to know whether to load zones into memory by itself,
but as `ZoneTableSegment::isWritable()` returns false, it skips
the loading.
4. The auth module gets the status of each data source, and notices
there's a `WAITING` state of segment. So it subscribes to the
"Memmgr" group on a command session and waits for an update
from the memory manager (memmgr) module. (See also the note at the
end of the section)
5. When the auth module receives an update command from memmgr, it
calls `ConfigurableClientList::resetMemorySegment()` with the command
argument and the segment mode of `READ_ONLY`.
Note that the auth module handles the command argument as mostly
opaque data; it's not expected to deal with details of segment
type-specific behavior. If the reset fails, auth aborts (as there's
no clear way to handle the failure).
6. `ConfigurableClientList::resetMemorySegment()` subsequently calls
`reset()` method on the corresponding `ZoneTableSegment` with the
given parameters.
In the case of `ZoneTableSegmentMapped`, it creates a new
`MemorySegment` object for the mapped type, which internally maps
the specific file into memory.
memmgr is expected to have prepared all necessary data in the file,
so all the data are immediately ready for use (i.e., there
shouldn't be any explicit load operation).
7. When a change is made in the mapped data, memmgr will send another
update command with parameters for new mapping. The auth module
calls `ConfigurableClientList::resetMemorySegment()`, and the
underlying memory segment is swapped with a new one. The old
memory segment object is destroyed. Note that
this "destroy" just means unmapping the memory region; the data
stored in the file are intact. Again, if mapping fails, auth
aborts.
8. If the auth module happens to receive a reload command from other
module, it could call
`ConfigurableClientList::getCachedZoneWriter()`
to reload the data by itself, just like in the previous section.
In this case, however, the writability check of
`getCachedZoneWriter()` fails (the segment was created as
`READ_ONLY` and is non-writable), so loading won't happen.
NOTE: While less likely in practice, it's possible that the same auth
module uses both "local" and "mapped" (and even others) type of
segments for different data sources. In such cases the sequence is
either the one in this or previous section depending on the specified
segment type in the configuration. The auth module itself isn't aware
of per segment-type details, but changes the behavior depending on the
segment state of each data source at step 4 above: if it's `WAITING`,
it means the auth module needs help from memmgr (that's all the auth
module should know; it shouldn't be bothered with further details such
as mapped file names); if it's something else, the auth module doesn't
have to do anything further.
Sequence for memmgr module initialization using mapped memory segment
---------------------------------------------------------------------
This sequence shows the common initialization sequence for the
memory manager (memmgr) module using a mapped type memory segment.
This is a mixture of the sequences shown in Sections 2 and 3.
image::memmgr-mapped-init.png[]
1. Initial sequence is the same until the application module (memmgr)
calls `ConfigurableClientList::getStatus()` as that for the
previous section.
2. The memmgr module identifies the data sources whose in-memory cache
type is "mapped". (Unlike other application modules, the memmgr
should know what such types means due to its exact responsibility).
For each such data source, it calls
`ConfigurableClientList::resetMemorySegment` with the READ_WRITE
mode and other mapped-type specific parameters. memmgr should be
able to generate the parameters from its own configuration and
other data source specific information (such as the RR class and
data source name).
3. The `ConfigurableClientList` class calls
`ZoneTableSegment::reset()` on the corresponding zone table
segment with the given parameters. In this case, since the mode is
READ_WRITE, a new `ZoneTable` will be created (assuming this is a
very first time initialization; if there's already a zone table
in the segment, it will be used).
4. The memmgr module then calls
`ConfigurableClientList::getZoneTableAccessor()`, and calls the
`getIterator()` method on it to get a list of zones for which
zone data are to be loaded into the memory segment.
5. The memmgr module loads the zone data for each such zone. This
sequence is the same as shown in Section 2.
6. On loading all zone data, the memmgr module sends an update command
to all interested modules (such as auth) in the segment, and waits
for acknowledgment from all of them.
7. Then it calls `ConfigurableClientList::resetMemorySegment()` for
this data source with almost the same parameter as step 2 above,
but with a different mapped file name. This will make a swap of
the underlying memory segment with a new mapping. The old
`MemorySegment` object will be destroyed, but as explained in the
previous section, it simply means unmapping the file.
8. The memmgr loads the zone data into the newly mapped memory region
by repeating the sequence shown in step 5.
9. The memmgr repeats all this sequence for data sources that use
"mapped" segment for in-memory cache. Note: it could handle
multiple data sources in parallel, e.g., while waiting for
acknowledgment from other modules.
Sequence for memmgr module to reload a zone using mapped memory segment
-----------------------------------------------------------------------
This example is a continuation of the previous section, describing how
the memory manager reloads a zone in mapped memory segment.
image::memmgr-mapped-reload.png[]
1. When the memmgr module receives a reload command from other module,
it calls `ConfigurableClientList::getCachedZoneWriter()` for the
specified zone name. This method checks the writability of
the segment, and since it's writable (as memmgr created it in the
READ_WRITE mode), `getCachedZoneWriter()` succeeds and returns
a `ZoneWriter`.
2. The memmgr module uses the writer to load the new version of zone
data. There is nothing specific to mapped-type segment here.
3. The memmgr module then sends an update command to other modules
that would share this version, and waits for acknowledgment from
all of them.
4. On getting acknowledgments, the memmgr module calls
`ConfigurableClientList::resetMemorySegment()` with the parameter
specifying the other mapped file. This will swap the underlying
`MemorySegment` with a newly created one, mapping the other file.
5. The memmgr updates this segment, too, so the two files will contain
the same version of data.

137
doc/design/datasrc/memmgr-mapped-init.txt
View File

@ -1,137 +0,0 @@
@startuml
participant memmgr as ":b10-memmgr"
[-> memmgr: new/initial config\n(datasrc cfg)
activate memmgr
participant list as ":Configurable\nClientList"
create list
memmgr -> list: <<construct>>
memmgr -> list: configure(cfg)
activate list
participant CacheConfig as ":CacheConfig"
create CacheConfig
list -> CacheConfig: <<construct>> (cfg)
participant zt_segment as ":ZoneTable\nSegment\n(Mapped)"
create zt_segment
list -> zt_segment: <<construct>>
list -> zt_segment: isWritable()
activate zt_segment
note over zt_segment: Segment not writable\nwhen not reset
zt_segment --> list: false
deactivate zt_segment
deactivate list
memmgr -> list: getStatus()
activate list
list --> memmgr: DataSourceStatus[]
deactivate list
loop for each datasrc with mapped segment
memmgr -> list: resetMemorySegment\n(datasrc_name,\nREAD_WRITE,\nsegmentparam)
activate list
list -> zt_segment: reset\n(READ_WRITE,\nsegmentparam)
activate zt_segment
participant segment as "seg1:Memory\nSegment\n(Mapped)"
create segment
zt_segment -> segment: <<construct>>
participant segment.2 as "seg2:Memory\nSegment\n(Mapped)"
participant ZoneTable as ":ZoneTable"
create ZoneTable
zt_segment -> ZoneTable: <<construct>>
deactivate zt_segment
deactivate list
memmgr -> list: getZoneTableAccessor\n(datasrc_name,\ncache=true)
activate list
list -> memmgr: ZoneTableAccessor
deactivate list
loop for each zone given by ZoneTableIterator
memmgr -> list: getCachedZoneWriter\n(zone_name)
activate list
list -> CacheConfig: getLoadAction()
activate CacheConfig
participant LoadAction as "la:LoadAction"
create LoadAction
CacheConfig -> LoadAction: <<construct>>
CacheConfig --> list : la
deactivate CacheConfig
participant ZoneWriter as "zw:ZoneWriter"
create ZoneWriter
list -> ZoneWriter: <<construct>> (la)
list --> memmgr: zw
deactivate list
memmgr -> ZoneWriter: load()
activate ZoneWriter
ZoneWriter -> LoadAction: (funcall)
activate LoadAction
participant ZoneData as "zd:ZoneData"
create ZoneData
LoadAction -> ZoneData: <<construct>> via helpers
LoadAction --> ZoneWriter: zd
deactivate LoadAction
deactivate ZoneWriter
memmgr -> ZoneWriter: install()
activate ZoneWriter
ZoneWriter -> ZoneTable: addZone(zd)
activate ZoneTable
ZoneTable --> ZoneWriter: NULL (no old data)
deactivate ZoneTable
deactivate ZoneWriter
end
[<- memmgr: command to\nmodules\n(datasrc_name,\nsegmentparam)
[--> memmgr: ack from all\nmodules
memmgr -> list: resetMemorySegment\n(datasrc_name,\nREAD_WRITE,\nsegmentparam)
activate list
list -> zt_segment: reset\n(READ_WRITE,\nsegmentparam)
activate zt_segment
zt_segment -> segment: <<destroy>>
destroy segment
create segment.2
zt_segment -> segment.2: <<construct>>
deactivate zt_segment
deactivate list
note left of memmgr: load zone\nfor each zone\ngiven by\nZoneTableIterator
end
[<-- memmgr
deactivate memmgr
@enduml

94
doc/design/datasrc/memmgr-mapped-reload.txt
View File

@ -1,94 +0,0 @@
@startuml
participant memmgr as ":b10-memmgr"
[-> memmgr: reload\n(zonename)
activate memmgr
participant list as ":Configurable\nClientList"
memmgr -> list: getCachedZoneWriter\n(zone_name)
activate list
participant CacheConfig as ":CacheConfig"
participant zt_segment as ":ZoneTable\nSegment\n(Mapped)"
participant segment as "existing:Memory\nSegment\n(Mapped)"
participant segment2 as "new:Memory\nSegment\n(Mapped)"
list -> zt_segment: isWritable()
activate zt_segment
zt_segment --> list: true
deactivate zt_segment
list -> CacheConfig: getLoadAction()
activate CacheConfig
participant ZoneTable as ":ZoneTable"
participant ZoneWriter as "zw:ZoneWriter"
participant LoadAction as "la:LoadAction"
create LoadAction
CacheConfig -> LoadAction: <<construct>>
CacheConfig --> list: la
deactivate CacheConfig
create ZoneWriter
list -> ZoneWriter: <<construct>> (la)
list --> memmgr: zw
deactivate list
memmgr -> ZoneWriter: load()
activate ZoneWriter
ZoneWriter -> LoadAction: (funcall)
activate LoadAction
participant ZoneData as "zd_existing\n:ZoneData"
participant ZoneData2 as "zd_new\n:ZoneData"
create ZoneData2
LoadAction -> ZoneData2: <<construct>> via helpers
LoadAction --> ZoneWriter: zd_new
deactivate LoadAction
deactivate ZoneWriter
memmgr -> ZoneWriter: install()
activate ZoneWriter
ZoneWriter -> ZoneTable: addZone(zd_new)
activate ZoneTable
ZoneTable --> ZoneWriter: zd_existing (old data)
deactivate ZoneTable
deactivate ZoneWriter
memmgr -> ZoneWriter: cleanup()
activate ZoneWriter
ZoneWriter -> ZoneData: <<destroy>>
destroy ZoneData
deactivate ZoneWriter
[<- memmgr: command to\nmodules\n(datasrc_name,\nsegmentparam)
[--> memmgr: ack from all\nmodules
memmgr -> list: resetMemorySegment\n(datasrc_name,\nREAD_WRITE,\nsegmentparam)
activate list
list -> zt_segment: reset\n(READ_WRITE,\nsegmentparam)
activate zt_segment
zt_segment -> segment: <<destroy>>
destroy segment
create segment2
zt_segment -> segment2: <<construct>>
deactivate zt_segment
deactivate list
note left of memmgr: (repeat the\nsame sequence\nfor loading to the\nother segment)
memmgr -> list: getCachedZoneWriter\n(zone_name)
...
@enduml

112
doc/Doxyfile → doc/devel/Doxyfile
View File

@ -51,7 +51,7 @@ PROJECT_BRIEF =
# pixels and the maximum width should not exceed 200 pixels. Doxygen will copy
# the logo to the output directory.
PROJECT_LOGO = guide/kea-logo-100x70.png
PROJECT_LOGO = ../images/kea-logo-100x70.png
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
# into which the generated documentation will be written. If a relative path is
@ -771,53 +771,53 @@ WARN_LOGFILE =
# spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
# Note: If this tag is empty the current directory is searched.
INPUT = ../src/bin/agent \
../src/bin/d2 \
../src/bin/dhcp4 \
../src/bin/dhcp6 \
../src/bin/lfc \
../src/bin/netconf \
../src/bin/perfdhcp \
../src/bin/sockcreator \
../src/hooks/dhcp/high_availability \
../src/hooks/dhcp/lease_cmds \
../src/hooks/dhcp/stat_cmds \
../src/hooks/dhcp/user_chk \
../src/lib/asiodns \
../src/lib/asiolink \
../src/lib/cc \
../src/lib/cfgrpt \
../src/lib/config \
../src/lib/config_backend \
../src/lib/cql \
../src/lib/cryptolink \
../src/lib/database \
../src/lib/dhcp \
../src/lib/dhcp_ddns \
../src/lib/dhcpsrv \
../src/lib/dhcpsrv/parsers \
../src/lib/dhcpsrv/benchmarks \
../src/lib/dns \
../src/lib/eval \
../src/lib/exceptions \
../src/lib/hooks \
../src/lib/http \
../src/lib/log \
../src/lib/log/compiler \
../src/lib/log/interprocess \
../src/lib/mysql \
../src/lib/pgsql \
../src/lib/process \
../src/lib/stats \
../src/lib/testutils \
../src/lib/util \
../src/lib/util/encode \
../src/lib/util/io \
../src/lib/util/random \
../src/lib/util/threads \
../src/lib/util/unittests \
../src/lib/yang \
devel
INPUT = ../../src/bin/agent \
../../src/bin/d2 \
../../src/bin/dhcp4 \
../../src/bin/dhcp6 \
../../src/bin/lfc \
../../src/bin/netconf \
../../src/bin/perfdhcp \
../../src/bin/sockcreator \
../../src/hooks/dhcp/high_availability \
../../src/hooks/dhcp/lease_cmds \
../../src/hooks/dhcp/stat_cmds \
../../src/hooks/dhcp/user_chk \
../../src/lib/asiodns \
../../src/lib/asiolink \
../../src/lib/cc \
../../src/lib/cfgrpt \
../../src/lib/config \
../../src/lib/config_backend \
../../src/lib/cql \
../../src/lib/cryptolink \
../../src/lib/database \
../../src/lib/dhcp \
../../src/lib/dhcp_ddns \
../../src/lib/dhcpsrv \
../../src/lib/dhcpsrv/parsers \
../../src/lib/dhcpsrv/benchmarks \
../../src/lib/dns \
../../src/lib/eval \
../../src/lib/exceptions \
../../src/lib/hooks \
../../src/lib/http \
../../src/lib/log \
../../src/lib/log/compiler \
../../src/lib/log/interprocess \
../../src/lib/mysql \
../../src/lib/pgsql \
../../src/lib/process \
../../src/lib/stats \
../../src/lib/testutils \
../../src/lib/util \
../../src/lib/util/encode \
../../src/lib/util/io \
../../src/lib/util/random \
../../src/lib/util/threads \
../../src/lib/util/unittests \
../../src/lib/yang
# This tag can be used to specify the character encoding of the source files
# that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@ -861,9 +861,9 @@ RECURSIVE = NO
# Note that relative paths are relative to the directory from which doxygen is
# run.
EXCLUDE = ../src/lib/dns/master_lexer.cc \
../src/lib/dns/rdataclass.cc \
../src/lib/eval/lexer.cc
EXCLUDE = ../../src/lib/dns/master_lexer.cc \
../../src/lib/dns/rdataclass.cc \
../../src/lib/eval/lexer.cc
# The EXCLUDE_SYMLINKS tag can be used to select whether or not files or
# directories that are symbolic links (a Unix file system feature) are excluded
@ -917,10 +917,10 @@ EXAMPLE_RECURSIVE = NO
# that contain images that are to be included in the documentation (see the
# \image command).
IMAGE_PATH = ../doc/images \
../src/lib/hooks/images \
../src/bin/d2/images \
../src/lib/dhcpsrv/images
IMAGE_PATH = ../images \
../../src/lib/hooks/images \
../../src/bin/d2/images \
../../src/lib/dhcpsrv/images
# The INPUT_FILTER tag can be used to specify a program that doxygen should
# invoke to filter for each input file. Doxygen will invoke the filter program
@ -2215,7 +2215,7 @@ HIDE_UNDOC_RELATIONS = YES
# set to NO
# The default value is: YES.
HAVE_DOT = YES
HAVE_DOT = YES
# The DOT_NUM_THREADS specifies the number of dot invocations doxygen is allowed
# to run in parallel. When set to 0 doxygen will base this on the number of

0
doc/Doxyfile-xml → doc/devel/Doxyfile-xml
View File

20
doc/devel/Makefile.am Normal file
View File

@ -0,0 +1,20 @@
EXTRA_DIST =
EXTRA_DIST += Doxyfile Doxyfile-xml
EXTRA_DIST += bison.dox
EXTRA_DIST += config-backend.dox
EXTRA_DIST += contribute.dox
EXTRA_DIST += mainpage.dox
EXTRA_DIST += terminology.dox
EXTRA_DIST += unit-tests.dox
EXTRA_DIST += doc.dox
EXTRA_DIST += congestion-handling.dox
all: devel
devel:
mkdir -p $(builddir)/html
(cat Doxyfile; echo PROJECT_NUMBER=$(PACKAGE_VERSION)) | doxygen - > $(builddir)/html/doxygen.log 2> $(builddir)/html/doxygen-error.log
echo `grep -i ": warning:" $(builddir)/html/doxygen-error.log | wc -l` warnings/errors detected.
clean:
rm -rf html

125
doc/guide/Makefile.am
View File

@ -1,125 +0,0 @@
if GENERATE_DOCS
# TODO
#HTMLDOCS = kea-guide.html kea-messages.html
#DOCS = kea-guide.txt
#dist_doc_DATA = $(DOCS)
#dist_html_DATA = $(HTMLDOCS) kea-guide.css kea-logo-100x70.png
#dist_html_DATA = $(HTMLDOCS) _static/kea-logo-100x70.png
#doc_DATA = _build/singlehtml/kea-guide.html _build/singlehtml/_static/kea-logo-100x70.png
rst_sources=
rst_sources+=kea-messages.rst
rst_sources+=admin.rst
rst_sources+=agent.rst
rst_sources+=api.rst
rst_sources+=classify.rst
rst_sources+=config-backend.rst
rst_sources+=config.rst
rst_sources+=congestion-handling.rst
rst_sources+=ctrl-channel.rst
rst_sources+=ddns.rst
rst_sources+=dhcp4-srv.rst
rst_sources+=dhcp6-srv.rst
rst_sources+=hammer.rst
rst_sources+=hooks-cb-cmds.rst
rst_sources+=hooks-class-cmds.rst
rst_sources+=hooks-ha.rst
rst_sources+=hooks-host-cache.rst
rst_sources+=hooks-lease-cmds.rst
rst_sources+=hooks-radius.rst
rst_sources+=hooks.rst
rst_sources+=hooks-stat-cmds.rst
rst_sources+=install.rst
rst_sources+=index.rst
rst_sources+=intro.rst
rst_sources+=keactrl.rst
rst_sources+=lease-expiration.rst
rst_sources+=lfc.rst
rst_sources+=logging.rst
rst_sources+=netconf.rst
rst_sources+=quickstart.rst
rst_sources+=shell.rst
rst_sources+=stats.rst
static_sources=
static_sources+=_static/kea-imageonly-100bw.png
static_sources+=_static/kea-logo-200.png
static_sources+=_static/kea.css
all_sources=$(rst_sources) conf.py $(static_sources)
EXTRA_DIST = $(all_sources) $(top_srcdir)/tools/system_messages.py
DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml
CLEANFILES = kea-guide.pdf kea-messages.pdf
mes_files=
mes_files+=$(top_srcdir)/src/hooks/dhcp/mysql_cb/mysql_cb_messages.mes
mes_files+=$(top_srcdir)/src/hooks/dhcp/lease_cmds/lease_cmds_messages.mes
mes_files+=$(top_srcdir)/src/hooks/dhcp/high_availability/ha_messages.mes
mes_files+=$(top_srcdir)/src/hooks/dhcp/stat_cmds/stat_cmds_messages.mes
mes_files+=$(top_srcdir)/src/hooks/dhcp/user_chk/user_chk_messages.mes
mes_files+=$(top_srcdir)/src/lib/config/config_messages.mes
mes_files+=$(top_srcdir)/src/lib/hooks/hooks_messages.mes
mes_files+=$(top_srcdir)/src/lib/dhcpsrv/dhcpsrv_messages.mes
mes_files+=$(top_srcdir)/src/lib/dhcpsrv/alloc_engine_messages.mes
mes_files+=$(top_srcdir)/src/lib/dhcpsrv/hosts_messages.mes
mes_files+=$(top_srcdir)/src/lib/http/http_messages.mes
mes_files+=$(top_srcdir)/src/lib/dhcp_ddns/dhcp_ddns_messages.mes
mes_files+=$(top_srcdir)/src/lib/database/db_messages.mes
mes_files+=$(top_srcdir)/src/lib/log/log_messages.mes
mes_files+=$(top_srcdir)/src/lib/log/logimpl_messages.mes
mes_files+=$(top_srcdir)/src/lib/log/tests/log_test_messages.mes
mes_files+=$(top_srcdir)/src/lib/process/process_messages.mes
mes_files+=$(top_srcdir)/src/lib/asiodns/asiodns_messages.mes
mes_files+=$(top_srcdir)/src/lib/eval/eval_messages.mes
mes_files+=$(top_srcdir)/src/bin/dhcp4/dhcp4_messages.mes
mes_files+=$(top_srcdir)/src/bin/agent/ca_messages.mes
mes_files+=$(top_srcdir)/src/bin/d2/d2_messages.mes
mes_files+=$(top_srcdir)/src/bin/dhcp6/dhcp6_messages.mes
mes_files+=$(top_srcdir)/src/bin/lfc/lfc_messages.mes
mes_files+=$(top_srcdir)/src/bin/netconf/netconf_messages.mes
kea-messages.rst: $(mes_files) $(top_srcdir)/tools/system_messages.py
$(top_srcdir)/tools/system_messages.py -o $@ $(mes_files)
sphinxopts=
sphinxopts+=-v
sphinxopts+=-E
sphinxopts+=-a
sphinxopts+=-c "${abs_srcdir}"
sphinxopts+=-D release="@PACKAGE_VERSION@"
sphinxopts+=-D version="@PACKAGE_VERSION@"
sphinxbuilddir=$(builddir)/_build
all: pdf html
pdf: $(all_sources)
$(SPHINXBUILD) -M latexpdf $(srcdir) $(sphinxbuilddir) $(sphinxopts)
html: $(all_sources)
$(SPHINXBUILD) -M $@ $(srcdir) $(sphinxbuilddir) $(sphinxopts)
install-data-local:
mkdir -p $(DESTDIR)$(docdir)
cp -r $(sphinxbuilddir)/html $(DESTDIR)$(docdir)
cp -r $(sphinxbuilddir)/latex/KeaAdministratorReferenceManual.pdf $(DESTDIR)$(docdir)
uninstall-local:
rm -rf $(DESTDIR)$(docdir)
clean::
-rm -rf $(sphinxbuilddir)
.PHONY: all pdf html
endif

762
doc/guide/admin.xml
View File

@ -1,762 +0,0 @@
<!--
- Copyright (C) 2015-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="admin">
<title>Kea Database Administration</title>
<section xml:id="kea-database-version">
<title>Databases and Database Version Numbers</title>
<para>
Kea may be configured to use a database as a storage for leases,
a source of servers' configurations and host reservations (i.e. static
assignments of addresses, prefixes, options etc.). Subsequent Kea
releases introduce changes to the database schemas to faciliate new
features and correct discovered issues with the existing schemas.
</para>
<para>
A given version of Kea expects a particular structure in
the backend and checks for this by examining the version of
database it is using. Separate version numbers are maintained for
backends, independent of the version of Kea itself. It
is possible that the backend version will stay the same
through several Kea revisions; similarly, it is possible that the
version of the backend may go up several revisions during a
Kea upgrade. Versions for each backend are independent, so an
increment in the MySQL backend version does not imply an increment
in that of PostgreSQL.
</para>
<para>
Backend versions are specified in
a <replaceable>major.minor</replaceable> format. The minor
number is increased when there are backward-compatible changes
introduced; for example, the addition of a new index. It is
desirable but not mandatory to apply such a change; you
can run an older backend version if you want to. (Although, in
the example given, running without the new index may be at the
expense of a performance penalty.) On the other hand, the major
number is increased when an incompatible change is introduced:
for example, an extra column is added to a table. If you try to
run Kea on a backend that is too old (as signified by
a mismatched backend major version number), Kea will refuse to run;
administrative action will be required to upgrade the backend.
</para>
</section>
<section xml:id="kea-admin">
<title>The kea-admin Tool</title>
<para>
To manage the databases, Kea provides the
<command>kea-admin</command> tool. It is able to initialize
a new backend, check its version number, perform a
backend upgrade, and dump lease data to a text file.
</para>
<para>
<command>kea-admin</command> takes two mandatory
parameters: <command>command</command> and
<command>backend</command>. Additional, non-mandatory options
may be specified. The currently supported commands are:
<itemizedlist>
<listitem>
<simpara>
<command>db-init</command> —
Initializes a new database schema. This is useful during a new
Kea installation. The database is initialized to the
latest version supported by the version of the software being
installed.
</simpara>
</listitem>
<listitem>
<simpara>
<command>db-version</command> —
Reports the database backend version number. This is
not necessarily equal to the Kea version number as
each backend has its own versioning scheme.
</simpara>
</listitem>
<listitem>
<simpara>
<command>db-upgrade</command> —
Conducts a database schema upgrade. This is useful when
upgrading Kea.
</simpara>
</listitem>
<listitem>
<simpara>
<command>lease-dump</command> —
Dumps the contents of the lease database (for MySQL, PostgreSQL, or
CQL backends) to a CSV (comma-separated values) text file. The first
line of the file contains the column names. This is meant to be
used as a diagnostic tool, so it provides a portable, human-readable
form of the lease data.
</simpara>
</listitem>
</itemizedlist>
<note>In previous versions of Kea ending with 1.6.0
<command>db-init</command>, <command>db-version</command> and
<command>db-upgrade</command> commands were named
<command>lease-init</command>, <command>lease-version</command> and
<command>lease-upgrade</command>.
</note>
<command>backend</command> specifies the type of backend database. The currently
supported types are:
<itemizedlist>
<listitem>
<simpara>
<command>memfile</command> — Lease information is
stored on disk in a text file.
</simpara>
</listitem>
<listitem>
<simpara>
<command>mysql</command> —
Information is stored in a MySQL relational database.
</simpara>
</listitem>
<listitem>
<simpara>
<command>pgsql</command> —
Information is stored in a PostgreSQL relational database.
</simpara>
</listitem>
<listitem>
<simpara>
<command>cql</command> —
Information is stored in an Apache Cassandra database.
</simpara>
</listitem>
</itemizedlist>
Additional parameters may be needed, depending on your setup
and specific operation: username, password, and database name or
the directory where specific files are located. See the appropriate
manual page for details (<command>man 8 kea-admin</command>).
</para>
</section>
<section xml:id="supported-databases">
<title>Supported Backends</title>
<para>The following table presents the capabilities of available
backends. Please refer to the specific sections dedicated to each backend to
better understand their capabilities and limitations. Choosing the right
backend may be essential for the success of your deployment.</para>
<para>
<table frame="all" xml:id="backends">
<title>List of available backends</title>
<tgroup cols='5'>
<colspec colname='feature'/>
<colspec colname='memfile'/>
<colspec colname='mysql'/>
<colspec colname='pgsql'/>
<colspec colname='cql' colwidth='1.5*'/>
<thead>
<row>
<entry>Feature</entry>
<entry>Memfile</entry>
<entry>MySQL</entry>
<entry>PostgreSQL</entry>
<entry>CQL (Cassandra)</entry>
</row>
</thead>
<tbody>
<row>
<entry>Status</entry>
<entry>Stable</entry>
<entry>Stable</entry>
<entry>Stable</entry>
<entry>Experimental</entry>
</row>
<row>
<entry>Data format</entry>
<entry>CSV file</entry>
<entry>SQL RMDB</entry>
<entry>SQL RMDB</entry>
<entry>NoSQL database (Cassandra)</entry>
</row>
<row>
<entry>Leases</entry>
<entry>yes</entry>
<entry>yes</entry>
<entry>yes</entry>
<entry>yes</entry>
</row>
<row>
<entry>Host Reservations</entry>
<entry>no</entry>
<entry>yes</entry>
<entry>yes</entry>
<entry>yes</entry>
</row>
<row>
<entry>Options defined on per host basis</entry>
<entry>no</entry>
<entry>yes</entry>
<entry>yes</entry>
<entry>yes</entry>
</row>
<row>
<entry>Configuration Backend</entry>
<entry>no</entry>
<entry>yes</entry>
<entry>no</entry>
<entry>no</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<section>
<title>memfile</title>
<para>
The memfile backend is able to store lease information, but is not able to
store host reservation details; these must be stored in the configuration
file. (There are no plans to add a host reservations storage capability to
this backend.)
</para>
<para>
No special initialization steps are necessary
for the memfile backend. During the first run, both
<command>kea-dhcp4</command> and <command>kea-dhcp6</command>
will create an empty lease file if one is not
present. Necessary disk-write permission is required.
</para>
<section xml:id="memfile-upgrade">
<title>Upgrading Memfile Lease Files from an Earlier Version of Kea</title>
<para>
There are no special steps required to upgrade memfile lease files
from an earlier version of Kea to a new version of Kea.
During startup the servers will check the schema version of the lease
files against their own. If there is a mismatch, the servers will
automatically launch the LFC process to convert the files to the
server's schema version. While this mechanism is primarily meant to
ease the process of upgrading to newer versions of Kea, it can also
be used for downgrading should the need arise. When upgrading, any
values not present in the original lease files will be assigned
appropriate default values. When downgrading, any data present in
the files but not in the server's schema will be dropped.
If you wish to convert the files manually prior to starting the
servers, you may do so by running the LFC process yourself.
See <xref linkend="kea-lfc"/> for more information.
</para>
</section>
<!-- @todo: document lease file upgrades once they are implemented in kea-admin -->
</section>
<section id="mysql-database">
<title>MySQL</title>
<para>
MySQL is able to store leases, host reservations, options defined on
a per-host basis and a subset of the server configuration parameters
(serving as a configuration backend). This section can be safely ignored
if you choose to store the data in other backends.
</para>
<section xml:id="mysql-database-create">
<title>First-Time Creation of the MySQL Database</title>
<para>
If you are setting the MySQL database for the first time,
you need to create the database area within MySQL and set up
the MySQL user ID under which Kea will access the database.
This needs to be done manually; <command>kea-admin</command>
is not able to do this for you.
</para>
<para>
To create the database:
<orderedlist>
<listitem>
<para>
Log into MySQL as "root":
<screen>
$ <userinput>mysql -u root -p</userinput>
Enter password:
mysql&gt;
</screen>
</para>
</listitem>
<listitem>
<para>
Create the MySQL database:
<screen>
mysql&gt; <userinput>CREATE DATABASE <replaceable>database-name</replaceable>;</userinput>
</screen>
(<replaceable>database-name</replaceable> is the name
you have chosen for the database.)
</para>
</listitem>
<listitem>
<para>
Create the user under which Kea will access the database
(and give it a password), then grant it access to the
database tables:
<screen>
mysql&gt; <userinput>CREATE USER '<replaceable>user-name</replaceable>'@'localhost' IDENTIFIED BY '<replaceable>password</replaceable>';</userinput>
mysql&gt; <userinput>GRANT ALL ON <replaceable>database-name</replaceable>.* TO '<replaceable>user-name</replaceable>'@'localhost';</userinput>
</screen>
(<replaceable>user-name</replaceable> and
<replaceable>password</replaceable> are the user ID
and password you are using to allow Kea's access to the
MySQL instance. All apostrophes in the command lines
above are required.)
</para>
</listitem>
<listitem>
<para>
At this point, you may elect to create the database
tables. (Alternatively, you can exit MySQL and create
the tables using the <command>kea-admin</command> tool,
as explained below.) To do this:
<screen>
mysql&gt; <userinput>CONNECT <replaceable>database-name</replaceable>;</userinput>
mysql&gt; <userinput>SOURCE <replaceable>path-to-kea</replaceable>/share/kea/scripts/mysql/dhcpdb_create.mysql</userinput>
</screen>
(<replaceable>path-to-kea</replaceable> is the
location where you installed Kea.)
</para>
</listitem>
<listitem>
<para>
Exit MySQL:
<screen>
mysql&gt; <userinput>quit</userinput>
Bye
$
</screen>
</para>
</listitem>
</orderedlist>
</para>
<para>
If you elected not to create the tables in Step 4, you can do
so now by running the <command>kea-admin</command> tool:
<screen>
$ <userinput>kea-admin db-init mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
</screen>
(Do not do this if you did create the tables in Step 4.)
<command>kea-admin</command> implements rudimentary checks;
it will refuse to initialize a database that contains any
existing tables. If you want to start from scratch, you
must remove all data manually. (This process is a manual
operation on purpose, to avoid possibly irretrievable mistakes
by <command>kea-admin</command>.)
</para>
</section>
<section xml:id="mysql-upgrade">
<title>Upgrading a MySQL Database from an Earlier Version of Kea</title>
<para>
Sometimes a new Kea version may use a newer database schema, so
the existing database will need to be upgraded. This can
be done using the <command>kea-admin db-upgrade</command>
command.
</para>
<para>
To check the current version of the database, use the following command:
<screen>
$ <userinput>kea-admin db-version mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
</screen>
(See <xref linkend="kea-database-version"/> for a discussion
about versioning.) If the version does not match the minimum
required for the new version of Kea (as described in the
release notes), the database needs to be upgraded.
</para>
<para>
Before upgrading, please make sure that the database is
backed up. The upgrade process does not discard any data, but
depending on the nature of the changes, it may be impossible
to subsequently downgrade to an earlier version. To perform
an upgrade, issue the following command:
<screen>
$ <userinput>kea-admin db-upgrade mysql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
</screen>
</para>
</section>
</section> <!-- end of MySQL sections -->
<section id="pgsql-database">
<title>PostgreSQL</title>
<para>
PostgreSQL is able to store leases, host reservations, and options
defined on a per-host basis.
This step can be
safely ignored if you are using other database backends.
</para>
<section xml:id="pgsql-database-create">
<title>First-Time Creation of the PostgreSQL Database</title>
<para>
The first task is to create both the database and the
user under which the servers will access it. A number of steps
are required:
<orderedlist>
<listitem>
<para>
Log into PostgreSQL as "root":
<screen>
$ <userinput>sudo -u postgres psql postgres</userinput>
Enter password:
postgres=#
</screen>
</para>
</listitem>
<listitem>
<para>
Create the database:
<screen>
postgres=#<userinput> CREATE DATABASE <replaceable>database-name</replaceable>;</userinput>
CREATE DATABASE
postgres=#
</screen>
(<replaceable>database-name</replaceable> is the name
you have chosen for the database.)
</para>
</listitem>
<listitem>
<para>
Create the user under which Kea will access the database
(and give it a password), then grant it access to the
database:
<screen>
postgres=#<userinput> CREATE USER <replaceable>user-name</replaceable> WITH PASSWORD '<replaceable>password</replaceable>';</userinput>
CREATE ROLE
postgres=#<userinput> GRANT ALL PRIVILEGES ON DATABASE <replaceable>database-name</replaceable> TO <replaceable>user-name</replaceable>;</userinput>
GRANT
postgres=#
</screen>
</para>
</listitem>
<listitem>
<para>
Exit PostgreSQL:
<screen>
postgres=# <userinput>\q</userinput>
Bye
$
</screen>
</para>
</listitem>
<listitem>
<para>
At this point you are ready to create the database tables.
This can be done using the <command>kea-admin</command> tool
as explained in the next section (recommended), or manually.
To create the tables manually, enter the following command.
Note that PostgreSQL will prompt you to enter the new user's
password you specified in Step 3. When the command completes,
you will be returned to the shell prompt. You should see output
similar to the following:
<screen>
$ <userinput>psql -d <replaceable>database-name</replaceable> -U <replaceable>user-name</replaceable> -f <replaceable>path-to-kea</replaceable>/share/kea/scripts/pgsql/dhcpdb_create.pgsql</userinput>
Password for user <replaceable>user-name</replaceable>:
CREATE TABLE
CREATE INDEX
CREATE INDEX
CREATE TABLE
CREATE INDEX
CREATE TABLE
START TRANSACTION
INSERT 0 1
INSERT 0 1
INSERT 0 1
COMMIT
CREATE TABLE
START TRANSACTION
INSERT 0 1
COMMIT
$
</screen>
(<replaceable>path-to-kea</replaceable> is the location
where you installed Kea.)
</para>
<para>
If instead you encounter an error like:
<screen>
psql: FATAL: no pg_hba.conf entry for host "[local]", user "<replaceable>user-name</replaceable>", database "<replaceable>database-name</replaceable>", SSL off
</screen>
... you will need to alter the PostgreSQL configuration.
Kea uses password authentication when connecting to
the database and must have the appropriate entries
added to PostgreSQL's pg_hba.conf file. This file is
normally located in the primary data directory for your
PostgreSQL server. The precise path may vary depending on your operating system and version, but the
default location for PostgreSQL 9.3 on Centos 6.5 is:
<filename>/var/lib/pgsql/9.3/data/pg_hba.conf</filename>.
</para>
<para>
Assuming Kea is running on the same host as PostgreSQL,
adding lines similar to the following should be sufficient to
provide password-authenticated access to Kea's database:
<screen>
local <replaceable>database-name</replaceable> <replaceable>user-name</replaceable> password
host <replaceable>database-name</replaceable> <replaceable>user-name</replaceable> 127.0.0.1/32 password
host <replaceable>database-name</replaceable> <replaceable>user-name</replaceable> ::1/128 password
</screen>
</para>
<para>
These edits are primarily intended as a starting point, and are
not a definitive reference on PostgreSQL administration or
database security. Please consult your PostgreSQL user
manual before making these changes, as they may expose
other databases that you run. It may be necessary to
restart PostgreSQL in order for the changes to take effect.
</para>
</listitem>
</orderedlist>
</para>
</section>
<section>
<title>Initialize the PostgreSQL Database Using kea-admin</title>
<para>
If you elected not to create the tables manually, you can do
so now by running the <command>kea-admin</command> tool:
<screen>
$ <userinput>kea-admin db-init pgsql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
</screen>
Do not do this if you already created the tables manually.
<command>kea-admin</command> implements rudimentary checks;
it will refuse to initialize a database that contains any
existing tables. If you want to start from scratch, you
must remove all data manually. (This process is a manual
operation on purpose, to avoid possibly irretrievable mistakes
by <command>kea-admin</command>.)
</para>
</section>
<section xml:id="pgsql-upgrade">
<title>Upgrading a PostgreSQL Database from an Earlier Version of Kea</title>
<para>
The PostgreSQL database schema can be upgraded using the same tool and
commands as described in <xref linkend="mysql-upgrade"/>, with the
exception that the "pgsql" database backend type must be used in
the commands.
</para>
<para>
Use the following command to check the current schema version:
<screen>
$ <userinput>kea-admin db-version pgsql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
</screen>
Use the following command to perform an upgrade:
<screen>
$ <userinput>kea-admin db-upgrade pgsql -u <replaceable>database-user</replaceable> -p <replaceable>database-password</replaceable> -n <replaceable>database-name</replaceable></userinput>
</screen>
</para>
</section>
</section> <!-- end of PostgreSQL sections -->
<section id="cql-database">
<title>Cassandra</title>
<para>
Cassandra (sometimes for historical reasons referred to in documentation and commands as CQL) is the newest backend
added to Kea; initial development was contributed by Deutsche Telekom.
The Cassandra backend is able to store leases,
host reservations, and options defined on a per-host basis.
</para>
<para>
Cassandra must be properly set up if you want Kea to store
information in it. This section can be safely ignored if you choose to
store the data in other backends.
</para>
<section xml:id="cql-database-create">
<title>First-Time Creation of the Cassandra Database</title>
<para>
If you are setting up the Cassandra database for the first time, you need to create the keyspace area within it. This needs to be done manually;
<command>kea-admin</command> cannot do this for you.
</para>
<para>
To create the database:
<orderedlist>
<listitem>
<para>
Export CQLSH_HOST environment variable:
<screen>
$ <userinput>export CQLSH_HOST=localhost</userinput>
</screen>
</para>
</listitem>
<listitem>
<para>
Log into CQL:
<screen>
$ <userinput>cqlsh</userinput>
cql&gt;
</screen>
</para>
</listitem>
<listitem>
<para>
Create the CQL keyspace:
<screen>
cql&gt; <userinput>CREATE KEYSPACE keyspace-name WITH replication = {'class' : 'SimpleStrategy','replication_factor' : 1};</userinput>
</screen>
(<replaceable>keyspace-name</replaceable> is the name you have
chosen for the keyspace)
</para>
</listitem>
<listitem>
<para>
At this point, you may elect to create the database tables.
(Alternatively, you can exit Cassandra and create the tables using the
<command>kea-admin</command> tool, as explained below.) To do this:
<screen>
<userinput>cqslh -k <replaceable>keyspace-name</replaceable> -f <replaceable>path-to-kea</replaceable>/share/kea/scripts/cql/dhcpdb_create.cql</userinput>
</screen>
(<replaceable>path-to-kea</replaceable> is the location where you
installed Kea)
</para>
</listitem>
</orderedlist>
</para>
<para>
If you elected not to create the tables in Step 4, you can do
so now by running the <command>kea-admin</command> tool:
<screen>
$ <userinput>kea-admin db-init cql -n <replaceable>database-name</replaceable></userinput>
</screen>
(Do not do this if you did create the tables in Step 4.)
<command>kea-admin</command> implements rudimentary checks;
it will refuse to initialize a database that contains any
existing tables. If you want to start from scratch, you
must remove all data manually. (This process is a manual
operation on purpose, to avoid possibly irretrievable mistakes
by <command>kea-admin</command>.)
</para>
</section>
<section xml:id="cql-upgrade">
<title>Upgrading a Cassandra Database from an Earlier Version of Kea</title>
<para>
Sometimes a new Kea version may use a newer database schema, so
the existing database will need to be upgraded. This can
be done using the <command>kea-admin db-upgrade</command>
command.
</para>
<para>
To check the current version of the database, use the following command:
<screen>
$ <userinput>kea-admin db-version cql -n <replaceable>database-name</replaceable></userinput>
</screen>
(See <xref linkend="kea-database-version"/> for a discussion
about versioning.) If the version does not match the minimum
required for the new version of Kea (as described in the
release notes), the database needs to be upgraded.
</para>
<para>
Before upgrading, please make sure that the database is
backed up. The upgrade process does not discard any data, but
depending on the nature of the changes, it may be impossible
to subsequently downgrade to an earlier version. To perform
an upgrade, issue the following command:
<screen>
$ <userinput>kea-admin db-upgrade cql -n <replaceable>database-name</replaceable></userinput>
</screen>
</para>
</section>
</section> <!-- end of CQL sections -->
<section>
<title>Using Read-Only Databases with Host Reservations</title>
<para>If a read-only database is used for storing host reservations,
Kea must be explicitly configured to operate on the database in
read-only mode.
Sections <xref linkend="read-only-database-configuration4"/> and
<xref linkend="read-only-database-configuration6"/> describe when
such configuration may be required and how to configure Kea to
operate in this way.
</para>
</section>
<section>
<title>Limitations Related to the Use of SQL Databases</title>
<section>
<title>Year 2038 Issue</title>
<para>
The lease expiration time is stored in the SQL database for each lease
as a timestamp value. Kea developers observed that the MySQL database doesn't
accept timestamps beyond 2147483647 seconds (maximum signed 32-bit number)
from the beginning of the Unix epoch (00:00:00 on 1 January 1970). Some versions of PostgreSQL
do accept greater values, but the value is altered when it is read back.
For this reason, the lease database backends put a restriction on the
maximum timestamp to be stored in the database, which is equal to the
maximum signed 32-bit number. This effectively means that the current
Kea version cannot store leases whose expiration time is later than
2147483647 seconds since the beginning of the epoch (around year 2038).
This will be fixed when the database support for longer timestamps
is available.
</para>
</section>
</section>
</section> <!-- End of Database sections -->
</chapter>

312
doc/guide/agent.xml
View File

@ -1,312 +0,0 @@
<!--
- Copyright (C) 2017-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="kea-ctrl-agent">
<title>The Kea Control Agent</title>
<section xml:id="agent-overview">
<title>Overview</title>
<para>The Kea Control Agent (CA) is a daemon which
exposes a RESTful control interface for managing Kea servers. The daemon
can receive control commands over HTTP and either forward these commands
to the respective Kea servers or handle these commands on its own. The
determination whether the command should be handled by the CA or forwarded
is made by checking the value of the "service" parameter, which may be
included in the command from the controlling client. The details of the
supported commands, as well as their structures, are provided in
<xref linkend="ctrl-channel"/>.</para>
<para>The CA can use hook libraries to provide support for
additional commands or custom behavior of existing commands. Such hook
libraries must implement callouts for the "control_command_receive" hook point.
Details about creating new hook libraries and supported hook points can be
found in the
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Kea_doc/doxygen/">Kea Developer's Guide</link>.
</para>
<para>
The CA processes received commands according to the following algorithm:
<itemizedlist>
<listitem>
<simpara>
Pass command into any installed hooks (regardless of service value(s)).
If the command is handled by a hook, return the response.
</simpara>
</listitem>
<listitem>
<simpara>
If the service specifies one more or services, forward the
command to the specified services and return the accumulated responses.
</simpara>
</listitem>
<listitem>
<simpara>
If the service is not specified or is an empty list, handle
the command if the CA supports it.
</simpara>
</listitem>
</itemizedlist>
</para>
</section>
<section xml:id="agent-configuration">
<title>Configuration</title>
<para>The following example demonstrates the basic CA configuration.</para>
<para>
<screen>
{
"Control-agent": {
"http-host": "10.20.30.40",
"http-port": 8080,
"control-sockets": {
"dhcp4": {
"comment": "main server",
"socket-type": "unix",
"socket-name": "/path/to/the/unix/socket-v4"
},
"dhcp6": {
"socket-type": "unix",
"socket-name": "/path/to/the/unix/socket-v6",
"user-context": { "version": 3 }
},
"d2": {
"socket-type": "unix",
"socket-name": "/path/to/the/unix/socket-d2"
},
},
"hooks-libraries": [
{
"library": "/opt/local/control-agent-commands.so",
"parameters": {
"param1": "foo"
}
} ],
"loggers": [ {
"name": "kea-ctrl-agent",
"severity": "INFO"
} ]
}
}</screen>
</para>
<para>
The <command>http-host</command> and <command>http-port</command> parameters
specify an IP address and port to which HTTP service will be bound.
In the example configuration provided above, the RESTful
service will be available under the URL of
<command>http://10.20.30.40:8080/</command>. If these parameters
are not specified, the default URL is http://127.0.0.1:8000/
</para>
<para>
As mentioned in <xref linkend="agent-overview"/>, the
CA can forward received commands to the Kea servers for
processing. For example, <command>config-get</command> is sent to
retrieve the configuration of one of the Kea services. When the CA receives
this command, including a <command>service</command> parameter
indicating that the client desires to retrieve the configuration of
the DHCPv4 server, the CA forwards this command to that server
and passes the received response back to the client. More about
the <command>service</command> parameter and the general structure of
commands can be found in <xref linkend="ctrl-channel"/>.
</para>
<para>
The CA uses UNIX domain sockets to forward control commands and receive
responses from other Kea services. The <command>dhcp4</command>,
<command>dhcp6</command>, and <command>d2</command> maps
specify the files to which UNIX domain sockets are bound. In
the configuration above, the CA will connect to the DHCPv4 server
via <filename>/path/to/the/unix/socket-v4</filename> to forward the
commands to it. Obviously, the DHCPv4 server must be configured to
listen to connections via this same socket. In other words, the command
socket configuration for the DHCPv4 server and the CA (for this server)
must match. Consult <xref linkend="dhcp4-ctrl-channel"/>,
<xref linkend="dhcp6-ctrl-channel"/> and
<xref linkend="d2-ctrl-channel"/> to learn how the socket
configuration is specified for the DHCPv4, DHCPv6 and D2 services.
</para>
<warning>
<simpara>
"dhcp4-server", "dhcp6-server" and "d2-server" were renamed
to "dhcp4", "dhcp6" and "d2" respectively in Kea 1.2.
If you are migrating from Kea 1.2, you must modify your CA configuration
to use this new naming convention.
</simpara>
</warning>
<para>
User contexts can store arbitrary data as long as they are in valid JSON
syntax and their top-level element is a map (i.e. the data must be
enclosed in curly brackets). Some hook libraries may expect specific
formatting; please consult the relevant hook library
documentation for details.
</para>
<para>
User contexts can be specified on either global scope, control
socket, or loggers. One other useful feature is the ability to
store comments or descriptions; the parser translates a
"comment" entry into a user context with the entry, which allows
a comment to be attached within the configuration itself.
</para>
<para>
Hooks libraries can be loaded by the Control Agent in the same way as they are loaded by the
DHCPv4 and DHCPv6 servers. The CA currently supports one hook point -
'control_command_receive' - which makes it possible to delegate
processing of some commands to the hooks library. The
<command>hooks-libraries</command> list contains the list of hooks
libraries that should be loaded by the CA, along with their configuration
information specified with <command>parameters</command>.
</para>
<para>
Please consult <xref linkend="logging"/> for the details how to
configure logging. The CA's root logger's name is
<command>kea-ctrl-agent</command>, as given in the example above.
</para>
</section>
<section xml:id="agent-secure-connection">
<title>Secure Connections</title>
<para>
The Control Agent does not natively support secure HTTP connections like
SSL or TLS. In order to setup a secure connection, please use one
of the available third-party HTTP servers and configure it to run
as a reverse proxy to the Control Agent. Kea has been tested with
two major HTTP server implentations working as a reverse proxy:
Apache2 and nginx. Example configurations, including extensive
comments, are provided in the <filename>doc/examples/https/</filename>
directory.
</para>
<para>
The reverse proxy forwards HTTP requests received over a secure
connection to the Control Agent using unsecured HTTP. Typically,
the reverse proxy and the Control Agent are running on the same machine,
but it is possible to configure them to run on separate machines as
well. In this case, security depends on the protection of the
communications between the reverse proxy and the Control Agent.
</para>
<para>Apart from providing the encryption layer for the control channel,
a reverse proxy server is also often used for authentication of the
controlling clients. In this case, the client must present a valid
certificate when it connects via reverse proxy. The proxy server
authenticates the client by checking whether the presented certificate is
signed by the certificate authority used by the server.</para>
<para>To illustrate this, the following is a sample configuration for the
nginx server running as a reverse proxy to the Kea Control Agent.
The server enables authentication of the clients using
certificates.</para>
<screen>
# The server certificate and key can be generated as follows:
#
# openssl genrsa -des3 -out kea-proxy.key 4096
# openssl req -new -x509 -days 365 -key kea-proxy.key -out kea-proxy.crt
#
# The CA certificate and key can be generated as follows:
#
# openssl genrsa -des3 -out ca.key 4096
# openssl req -new -x509 -days 365 -key ca.key -out ca.crt
#
#
# The client certificate needs to be generated and signed:
#
# openssl genrsa -des3 -out kea-client.key 4096
# openssl req -new -key kea-client.key -out kea-client.csr
# openssl x509 -req -days 365 -in kea-client.csr -CA ca.crt \
# -CAkey ca.key -set_serial 01 -out kea-client.crt
#
# Note that the 'common name' value used when generating the client
# and the server certificates must differ from the value used
# for the CA certificate.
#
# The client certificate must be deployed on the client system.
# In order to test the proxy configuration with 'curl' run
# command similar to the following:
#
# curl -k --key kea-client.key --cert kea-client.crt -X POST \
# -H Content-Type:application/json -d '{ "command": "list-commands" }' \
# https://kea.example.org/kea
#
#
#
# nginx configuration starts here.
events {
}
http {
# HTTPS server
server {
# Use default HTTPS port.
listen 443 ssl;
# Set server name.
server_name kea.example.org;
# Server certificate and key.
ssl_certificate /path/to/kea-proxy.crt;
ssl_certificate_key /path/to/kea-proxy.key;
# Certificate Authority. Client certificate must be signed by the CA.
ssl_client_certificate /path/to/ca.crt;
# Enable verification of the client certificate.
ssl_verify_client on;
# For URLs such as https://kea.example.org/kea, forward the
# requests to http://127.0.0.1:8080.
location /kea {
proxy_pass http://127.0.0.1:8080;
}
}
}
</screen>
<note>
<simpara>Note that the configuration snippet provided above is for testing
purposes only. It should be modified according to the security policies and best practices of your organization.</simpara>
</note>
<para>When you use an HTTP client without TLS support as <command>
kea-shell</command>, you can use an HTTP/HTTPS translator such as stunnel
in client mode. A sample configuration is provided in the
<filename>doc/examples/https/shell/</filename> directory.</para>
</section>
<section xml:id="agent-launch">
<title>Starting the Control Agent</title>
<para>
The CA is started by running its binary and specifying the configuration file
it should use. For example:
<screen>
$ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf
</screen>
It can be started by keactrl as well (see <xref linkend="keactrl"/>).
</para>
</section>
<section xml:id="agent-clients">
<title>Connecting to the Control Agent</title>
<para>For an example of a tool that can take advantage of the
RESTful API, see <xref linkend="kea-shell"/>.</para>
</section>
</chapter>

6318
doc/guide/api.xml
View File

File diff suppressed because it is too large Load Diff

1199
doc/guide/classify.xml
View File

File diff suppressed because it is too large Load Diff

345
doc/guide/config-backend.xml
View File

@ -1,345 +0,0 @@
<!--
- Copyright (C) 2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<section xml:id="config-backend">
<title>Kea Configuration Backend</title>
<section xml:id="cb-applicability">
<title>Applicability</title>
<para>
Kea Configuration Backend (abbreviated as CB) is a feature first
introduced in 1.6.0 release, which provides Kea servers with the
ability to manage and fetch their configuration from one or more
databases. In the documentation, the term "Configuration Backend"
may also refer to the particular Kea module providing support
to manage and fetch the configuration information from the particular
database type. For example: MySQL Configuration Backend is the logic
implemented within the "mysql_cb" hooks library which provides a
complete set of functions to manage and fetch the configuration
information from the MySQL database.
</para>
<para>
In small deployments, e.g. those comprising a single DHCP server instance
with limited and infrequently changing number of subnets, it may
be impractical to use the CB as a configuration repository because
it requires additional third party software to be installed and
configured - in particular the MySQL server and MySQL client.
Once the number of DHCP servers and/or the number of managed
subnets in the network grows, the usefulness of the CB becomes
obvious.
</para>
<para>
A good example is a pair of the Kea DHCP servers which can be
configured to support High Availability as described in
<xref linkend="high-availability-library"/>.
The configurations of both servers are almost exactly the same.
They may differ by the server identifier and designation of the
server as a primary or standby (or secondary). They may also
differ by the interfaces configuration. Typically, the subnets,
shared networks, option definitions, global parameters are
the same for both servers and can be sourced from a single
database instance to both Kea servers.
</para>
<para>
Using the database as a single source of configuration for subnets
and/or other configuration information supported by the CB has
the advantage that any modifications to the configuration in
the database is automatically applied to both servers.
</para>
<para>
Another case when the centralized configuration repository is desired
is in deployments including large number of the DHCP servers, possibly
using a common lease database to provide redundancy. The new servers
can be added to the pool frequently to fulfil growing scalability
requirements. Adding the new server does not require replicating
the entire configuration to the new server when common database is
used.
</para>
<para>
Using the database as a configuration repository for Kea servers also
brings other benefits, such as:
<itemizedlist>
<listitem><simpara>an ability to use database specific tools to access
the configuration information,</simpara></listitem>
<listitem><simpara>an ability to create customized statistics based
on the information stored in the database,</simpara></listitem>
<listitem><simpara>an ability to backup the configuration information
using the database builtin replication mechanisms.</simpara></listitem>
</itemizedlist>
</para>
</section>
<section xml:id="cb-limitations">
<title>CB Capabilities and Limitations</title>
<para>
Kea CB has been introduced in the 1.6.0 release, but this
implementation comes with a number of limitations being the
result of the overall complexity of this feature and the development
time constraints. This feature will evolve over time and the new
capabilities will be added in subsequent releases. In this
section we present the limitations of the CB, present in the
current Kea 1.6.0 release:
</para>
<itemizedlist>
<listitem><simpara>
Kea CB is currently supported for the MySQL database only.
</simpara></listitem>
<listitem><simpara>
Kea CB is only supported for DHCPv4 and DHCPv6 servers.
Neither Control Agent nor D2 deamon can be configured via the database.
</simpara></listitem>
<listitem><simpara>
Configuration to be stored for the DHCP servers includes: global parameters,
option definitions, global options, shared networks and subnets. Other
configuration parameters are not stored in the database at the moment.
They have to be configured via the JSON configuration file.
</simpara></listitem>
</itemizedlist>
<note>
<para>
We strongly recommend to not duplicate the configuration information
in the file and the database. For example, when specifying subnets
for the DHCP server, please store them in the configuration backend
or in the configuration file, not in both places. Storing some subnets
in the database and other in the file may put you at risk of potential
configuration conflicts. Note that the configuration from the database
takes precedence over the configuration from the file, thus it is possible
that parts of the configuration specified in the file may be overriden.
</para>
</note>
<note>
<para>
It is recommended that <command>subnet_cmds</command> hooks library is
not used to manage the subnets when the configuration backend is used
as a source of information about the subnets. The
<command>subnet_cmds</command> hooks library modifies the local subnets
configuration (in the server's memory), not in the database. Use
the <command>cb_cmds</command> hooks library to manage the subnets
information in the database instead.
</para>
</note>
</section>
<section xml:id="cb-components">
<title>CB Components</title>
<para>
In order to use the Kea CB feature, the Kea 1.6.0 version or later is
required. The <command>mysql_cb</command> open source hooks library
implementing the Configuration Backend for MySQL must be compiled and
loaded by the DHCP servers. This hooks library is compiled when the
<filename>--with-mysql</filename> configuration switch is used during
Kea build. The MySQL C client libraries must be installed
as explained in the <xref linkend="dhcp-install-configure"/>.
</para>
<note>
<simpara>Any existing MySQL schema must be upgraded to the latest schema
required by the particular Kea version using <command>kea-admin</command>
tool described in <xref linkend="kea-admin"/>.</simpara>
</note>
<para>
The <command>cb_cmds</command> premium hooks library is available to
ISC paid supported customers, which provides a complete set of commands
to manage the servers' configuration information within the database.
This library can be attached to both DHCPv4 and DHCPv6 server instances.
It is still possible to manage the configuration information without the
<command>cb_cmds</command> hooks library with commonly available tools
such as MySQL Workbench or command line MySQL client, by directly working
with the database.
</para>
<para>
Refer to the <xref linkend="cb-cmds-library"/> for the details regarding
the <command>cb_cmds</command> hooks library.
</para>
<para>
The DHCPv4 and DHCPv6 server specific configuration of the CB as well as
the list of supported configuration parameters can be found in the
<xref linkend="dhcp4-cb"/> and <xref linkend="dhcp6-cb"/>
respectively.
</para>
</section>
<section xml:id="cb-sharing">
<title>Configuration Sharing and Server Tags</title>
<para>
The configuration database is designed to store the configuration information
for multiple Kea servers. Depending on the use case, the entire configuration
may be shared by all servers, parts of the configuration may be shared by
multiple servers and the rest of the configuration may be different for these
servers or, finally, each server may have its own non-shared configuration.
</para>
<para>
The configuration elements in the database are associated with the servers
by "server tags". The server tag is an arbitrary string holding the name
of the Kea server instance. The tags of the DHCPv4 and DHCPv6 servers are
independent in the database, i.e. the same server tag can be created for
the DHCPv4 and the DHCPv6 server respectively.
</para>
<para>
The server definition, which consists of the server tag and the server
description, must be stored in the configuration database prior to creating
the dedicated configuration for that server. In cases when all servers use
the same configuration, e.g. a pair of servers running as the High Availability
peers, there is no need to configure the server tags for these
servers in the database. The database by default includes the logical
server <command>all</command>, which is used as a keyword to indicate that
the particular piece of configuration must be shared between all servers
connecting to the database. The <command>all</command> server can't be
deleted or modified. It is not even returned among other servers
as a result of the <command>remote-server[46]-get-all</command>
commands. Also, slightly different rules may apply to "all" keyword
than to any user defined server when running the commands provided by
the <command>cb_cmds</command> hooks library
(see <xref linkend="cb-cmds-library"/> for details).
</para>
<note>
<simpara>
In the simplest case there are no server tags defined in the configuration
database and all connecting servers will get the same configuration
regardless of the server tag they are using. The server tag that the
particular Kea instance presents to the database to fetch its configuration
is specified in the Kea configuration file, using the
<command>config-control</command> map (please refer to the
<xref linkend="dhcp4-cb-json"/> and <xref linkend="dhcp6-cb-json"/>
for details).
</simpara>
</note>
<para>
All Kea instances presenting the same server tag to the configuration database
are given the same configuration. It is the administrator's choice whether
multiple Kea instances use the same server tag or each Kea instance is using
a different sever tag. Also, there is no requirement that the instances
running on the same physical or virtual machine use the same server tag. It is
even possible to configure the Kea server without assigning it a server tag.
In such case the server will be given the configuration specified for "all"
servers.
</para>
<para>
In order to differentiate the configurations between the Kea servers, a
collection of the server tags used by the servers must be stored in the
database. For the DHCPv4 and DHCPv6 servers, it can be done using the
commands described in <xref linkend="command-remote-server4-set"/> and
<xref linkend="command-remote-server6-set"/>. Next, the
server tags can be used to associate the configuration information with
the servers. However, it is important to note that some DHCP
configuration elements may be associated with multiple server tags and
other configuration elements may be associated with exactly one
server tag. The former configuration elements are referred to as
shareable configuration elements and the latter are referred to as
non-shareable configuration elements. The <xref linkend="dhcp4-cb"/>
and <xref linkend="dhcp6-cb"/> list the DHCP specific shareable and
non-shareable configuration elements. However, in this section we
want to briefly explain the difference between them.
</para>
<para>
The shareable configuration element is the one having some unique
property identifying it and which instance may appear only once in
the database. An example of the shareable DHCP element is a subnet
instance. The subnet is a part of the network topology and we assume
that the particular subnet may have only one definition within this
network. The subnet has two unique identifiers: subnet id and the
subnet prefix. The subnet identifier is used in Kea to uniquely
identify the subnet and to connect it with other configuration elements,
e.g. in host reservations. The subnet identifier uniquely identifies
the subnet within the network. Some commands provided by the
<command>cb_cmds</command> hooks library allow for accessing the subnet
information by subnet identifier (or prefix) and explicitly prohibit
using the server tag to access the subnet. This is because, in a
general case, the subnet definition is associated with multiple servers
rather than single server. In fact, it may even be associated
with no servers (unassigned). Still, the unassigned subnet has an
identifier and prefix which can be used to access the subnet.
</para>
<para>
A shareable configuration element may be associated with multiple
servers, one server or no servers. Deletion of the server which is
associated with the shareable element does not cause the deletion of
the shareable element. It merely deletes the association of the
deleted server with the element.
</para>
<para>
Unlike the shareable element, the non-shareable element must not be
explicitly associated with more than one server and must not exist
after the server is deleted (must not remain unassigned). The
non-shareable element only exists within the context of the server.
An example of the non-shareable element in DHCP is a global
parameter, e.g. <command>renew-timer</command>. The renew timer
is the value to be used by the particular server and only this
server. Other servers may have their respective renew timers
set to the same or different value. The renew timer is the
parameter which has no unique identifier by which it could be
accessed, modified or otherwise used. The global parameters like
the renew timer can be accessed by the parameter name and the
tag of the server for which they are configured. For example:
the commands described in
<xref linkend="command-remote-global-parameter4-get"/> allow for
fetching the value of the global parameter by the parameter name and
the server name. Getting the global parameter only by its name (without
specifying the server tag) is not possible because there may be many
global parameters with the given name in the database.
</para>
<para>
When the server associated with a non-shareable configuration element
is deleted, the configuration element is automatically deleted from
the database along with the server because the non-shareable element
must be always assigned to some server (or the logical server "all").
</para>
<para>
The terms "shareable" and "non-shareable" only apply to the associations
with user defined servers. All configuration elements associated with
the logical server "all" are by definition shareable. For example: the
<command>renew-timer</command> associated with "all" servers is used
by all servers connecting to the database which don't have their specific
renew timers defined. In the special case, when none of the configuration
elements are associated with user defined servers, the entire
configuration in the database is shareable because all its pieces
belong to "all" servers.
</para>
<note>
<simpara>
Be very careful when associating the configuration elements with
different server tags. The configuration backend doesn't protect you
against some possible misconfigurations that may arise from the
wrong server tags' assignments. For example: if you assign a shared
network to one server and the subnets belonging to this shared network
to another server, the servers will fail upon trying to fetch and
use this configuration. The server fetching the subnets will be
aware that the subnets are associated with the shared network but
the shared network will not be found by this server as it doesn't
belong to it. In such case, both the shared network and the subnets
should be assigned to the same set of servers.
</simpara>
</note>
</section>
</section>

157
doc/guide/config.xml
View File

@ -1,157 +0,0 @@
<!--
- Copyright (C) 2014-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="kea-config">
<title>Kea Configuration</title>
<para>Kea uses JSON structures to represent server configurations.
The following sections describe how the configuration structures are
organized.
</para>
<section xml:id="json">
<title>JSON Configuration</title>
<para>JSON is the notation used throughout the Kea project. The most obvious
usage is for the configuration file, but JSON is also used for sending commands
over the Management API (see <xref linkend="ctrl-channel"/>) and for
communicating between DHCP servers and the DDNS update daemon.</para>
<para>Typical usage assumes that the servers are started from the command line,
either directly or using a script, e.g. <filename>keactrl</filename>.
The configuration file is specified upon startup using the -c parameter.</para>
<section xml:id="json-format">
<title>JSON Syntax</title>
<para>Configuration files for the DHCPv4, DHCPv6, DDNS, Control
Agent, and Netconf modules are defined in an extended JSON
format. Basic JSON is defined
in <link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="http://tools.ietf.org/html/rfc7159">RFC 7159</link> and
<link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="http://www.ecma-international.org/publications/standards/Ecma-404.htm">ECMA 404</link>.
In particular, the only boolean values allowed
are true or false (all lowercase). The capitalized
versions (True or False) are not accepted.
</para>
<para>Kea components use an extended JSON with additional features
allowed:
<itemizedlist>
<listitem>
<simpara>shell comments: any text after the hash (#)
character is ignored.</simpara>
</listitem>
<listitem>
<simpara>C comments: any text after the double slashes (//)
character is ignored.</simpara>
</listitem>
<listitem>
<simpara>Multiline comments: any text between /* and */ is
ignored. This commenting can span multiple lines.</simpara>
</listitem>
<listitem>
<simpara>File inclusion: JSON files can include other JSON files by using a statement of the form &lt;?include
"file.json"?&gt;.</simpara>
</listitem>
</itemizedlist>
</para>
<para>The configuration file consists of a single object (often
colloquially called a map) started with a curly bracket. It
comprises one or more of the "Dhcp4", "Dhcp6", "DhcpDdns",
"Control-agent" and "Netconf" objects. It is possible to define
additional elements but they will be ignored.</para>
<para>A very simple configuration for DHCPv4 could look like this:
<screen>
# The whole configuration starts here.
{
# DHCPv4 specific configuration starts here.
"Dhcp4": {
"interfaces-config": {
"interfaces": [ "eth0" ],
"dhcp-socket-type": "raw"
},
"valid-lifetime": 4000,
"renew-timer": 1000,
"rebind-timer": 2000,
"subnet4": [{
"pools": [ { "pool": "192.0.2.1-192.0.2.200" } ],
"subnet": "192.0.2.0/24"
}],
# Now loggers are inside the DHCPv4 object.
"loggers": [{
"name": "*",
"severity": "DEBUG"
}]
}
# The whole configuration structure ends here.
}
</screen>
</para>
<para>More examples are available in the installed
<filename>share/doc/kea/examples</filename> directory.</para>
<note>
<para>
The "Logging" element is removed in Kea 1.6.0 and its contents
(the "loggers" object) moved inside the configuration objects (maps) for
respective Kea modules. For example: the "Dhcp4" map contains the
"loggers" object specifying logging configuration for the DHCPv4
server. Backward compatibility is maintained until at least Kea
1.7.0 release: it will be possible to specify "Logging" object
at the top configuration level and "loggers"
objects at the module configuration level. Ultimately, support for the
top-level "Logging" object will be removed.
</para>
<para>
The specification of several supported elements (e.g. "Dhcp4",
"Dhcp6") in a single configuration file can be confusing and works
badly with the commands that fetch and write new configurations.
Support for it will be removed in a future release of Kea, after which
each component will require its own configuration file.
</para>
</note>
<para>To avoid repetition of mostly similar structures,
examples in the rest of this guide will showcase only the
subset of parameters appropriate for a given context. For
example, when discussing the IPv6 subnets configuration in
DHCPv6, only subnet6 parameters will be mentioned. It is
implied that the remaining elements (the global map that holds
Dhcp6 and Logging) are present, but they are omitted for
clarity. Usually, locations where extra parameters may appear
are denoted by an ellipsis (...).</para>
</section>
<section>
<title>Simplified Notation</title>
<para>It is sometimes convenient to refer to a specific
element in the configuration hierarchy. Each hierarchy level
is separated by a slash. If there is an array, a specific
instance within that array is referenced by a number in square
brackets (with numbering starting at zero). For example, in
the above configuration the valid-lifetime in the Dhcp4
component can be referred to as Dhcp4/valid-lifetime and the
pool in the first subnet defined in the DHCPv4 configuration
as Dhcp4/subnet4[0]/pool.</para>
</section>
</section>
<!-- Include large section about Kea Config Backend -->
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config-backend.xml"/>
</chapter>

149
doc/guide/congestion-handling.xml
View File

@ -1,149 +0,0 @@
<!--
- Copyright (C) 2018-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="congestion-handling">
<title>Congestion Handling in DHCPv4 and DHCPv6</title>
<section xml:id="congeston-handling-background">
<title>What is Congestion?</title>
<para>Congestion occurs when servers are subjected to client queries
faster than they can be processed. As a result, the servers begin
accumulating a backlog of pending queries. The longer the high rate of
traffic continues the farther behind the servers fall. Depending on the
client implementations, those that fail to get leases either give up or simply
continue to retry forever. In the former case, the server may eventually
recover, but the latter case is a vicious cycle from which the server is unable
to escape.
</para>
<para>
In a well-planned deployment, the number and capacity of servers is matched
to the maximum client loads expected. As long as capacity is matched to
load, congestion does not occur. If the load is routinely too heavy, then
the deployment needs to be re-evaluated. Congestion typically occurs when
there is a network event that causes overly large numbers of clients to
simultaneously need leases, such as recovery after a network outage.
</para>
<para>
The goal of congestion handling is to help servers mitigate the peak
in traffic by fulfilling as many of the most relevant requests as possible
until the congestion subsides.
</para>
<para>Prior to Kea 1.5, kea-dhcp4 and kea-dhcp4 read inbound packets directly
from the interface sockets in the main application thread, which meant that
packets waiting to be processed were held in socket buffers themselves. Once
these buffers filled, any new packets were discarded. Under swamped conditions,
the servers ended up processing client packets that were no longer
relevant, or worse were redundant. In other words, the packets waiting in
the FIFO socket buffers became increasingly stale.
</para>
</section>
<section xml:id="congeston-handling-solution">
<title>Configuring Congestion Handling</title>
<para>Kea 1.5 introduced the Congestion Handling feature.
Congestion handling offers the ability to configure the server to use a
separate thread to read packets from the interface socket buffers. As the
thread reads packets from the buffers, they are added to an internal packet
queue, and the server's main application thread processes packets from this queue
rather than from the socket buffers. By structuring it this way, a configurable layer
has been introduced which can make decisions on which packets to process,
how to store them, and the order in which they are processed by the server.
</para>
<para>The default packet queue implemenation for both kea-dhcp4 and kea-dhcp6
is a simple ring buffer. Once it reaches capacity, new packets get added to
the back of the queue by discarding packets from the front of the queue. Rather than
always discarding the newest packets, Kea now always discards the oldest
packets. The capacity of the buffer, i.e the maximum number of packets the
buffer can contain, is configurable. A reasonable starting point would be to
match the capacity to the number of leases per second your installation of
Kea can handle. Please note that this figure varies widely depending on the
specifics of your deployment.
</para>
<para>As there is no one algorithm that will best handle the dynamics of
all sites, and because over time new approaches will evolve, the packet
queue is implemented as a plug-in, which can replaced by a custom queue
implementation via a hook library. This should make it straightforward
for interested parties to experiment with their own solutions. (Developers
can refer to isc::dhcp::PacketQueue and isc::dhcp::PacketQueueMgr, described in the Kea
Developer's Guide).
</para>
<para>Packet queue behavior is configured in both kea-dhcp4 and kea-dhcp6
servers through an optional, top-level, configuration element,
'dhcp-queue-control'. Omitting this element disables packet queueing:
<screen>
"dhcp-queue-control": {
"enable-queue": true|false,
"queue-type": "queue type",
"capacity" : n
}
</screen>
where:
<itemizedlist>
<listitem>
<simpara><command>enable-queue</command> true|false. Enables or
disables packet queueing. When true, the server processes packets
from the packet queue, which is filled by a separate thread. When
false, the server processes packets directly from the socket buffers
in the main thread. It is
disabled by default.
</simpara>
</listitem>
<listitem>
<simpara><command>queue-type</command> name of the queue implementation
to use. This value exists so that custom implementations can be
registered (via hook library) and then selected. There is a default
packet queue implementation that is pre-registered during server
start up: "kea-ring4" for kea-dhcp4 and "kea-ring6" for kea-dhcp6.
</simpara>
</listitem>
<listitem>
<simpara><command>capacity</command> = n [packets]. This is the
maximum number of packets the queue can hold before packets
are discarded. The optimal value for this is extremely site-dependent.
The default value is 500 for both kea-ring4 and kea-ring6.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>The following example enables the default packet queue for kea-dhcp4,
with a queue capacity of 250 packets:
<screen>
"Dhcp4":
{
...
"dhcp-queue-control": {
"enable-queue": true,
"queue-type": "kea-ring4",
"capacity" : 250
},
...
}
</screen>
</para>
<para> The following example enables the default packet queue for kea-dhcp6,
with a queue capacity of 300 packets:
<screen>
"Dhcp6":
{
...
"dhcp-queue-control": {
"enable-queue": true,
"queue-type": "kea-ring6",
"capacity" : 300
},
...
}
</screen>
</para>
</section>
</chapter>

682
doc/guide/ctrl-channel.xml
View File

@ -1,682 +0,0 @@
<!--
- Copyright (C) 2015-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="ctrl-channel">
<title>Management API</title>
<para>A classic approach to daemon configuration assumes that
the server's configuration is stored in configuration files
and, when the configuration is changed, the daemon is restarted.
This approach has the significant disadvantage of introducing periods
of downtime when client traffic is not handled. Another risk
is that if the new configuration is invalid for any reason,
the server may refuse to start, which will further extend the
downtime period until the issue is resolved.</para>
<para>To avoid such problems, the DHCPv4, DHCPv6 and D2 servers in Kea
include support for a mechanism that allows
online reconfiguration without requiring server shutdown.
Both servers can be instructed to open control sockets, which
is a communications channel. The server is able to receive
commands on that channel, act on them, and report back status.</para>
<para>The DHCPv4, DHCPv6 and D2 servers receive commands over the
UNIX domain sockets. The details how to configure these sockets,
see <xref linkend="dhcp4-ctrl-channel"/> and <xref
linkend="dhcp6-ctrl-channel"/>. While it is possible to control
the servers directly using unix domain sockets it requires that
the controlling client be running on the same machine as
the server. SSH is usually used to
connect remotely to the controlled machine.</para>
<para>Network administrators usually prefer using some form
of a RESTful API to control the servers, rather than using UNIX
domain sockets directly. Therefore,
Kea includes a component called Control Agent (or CA), which
exposes a RESTful API to the controlling clients and can forward
commands to the respective Kea services over the UNIX domain
sockets. The CA configuration has been described in
<xref linkend="agent-configuration"/>.</para>
<para>The HTTP requests received by the CA contain the control
commands encapsulated within HTTP requests. Simply speaking,
the CA is responsible for stripping the HTTP layer from the
received commands and forwarding the commands in a JSON format
over the UNIX domain sockets to the respective services. Because the
CA receives commands for all services, it requires additional
"forwarding" information to be included in the client's messages.
This forwarding information is carried within the
<command>service</command> parameter of the received command.
If the <command>service</command> parameter is not included, or if
the parameter is a blank list, the CA will assume that the control
command is targeted at the CA itself and will try to handle
it on its own.
</para>
<para>Control connections over both HTTP and UNIX domain sockets are
guarded with timeouts. The default timeout value is set to 10s
and is not configurable.
</para>
<section xml:id="ctrl-channel-syntax">
<title>Data Syntax</title>
<para>Communication over the control channel is conducted using JSON
structures. If configured, Kea will open a socket and listen
for incoming connections. A process connecting to this socket
is expected to send JSON commands structured as follows:
<screen>
{
"command": "foo",
"service": [ "dhcp4" ]
"arguments": {
"param1": "value1",
"param2": "value2",
...
}
}
</screen>
The same command sent over the RESTful interface to the CA will have
the following structure:
<screen>
POST / HTTP/1.1\r\n
Content-Type: application/json\r\n
Content-Length: 147\r\n\r\n
{
"command": "foo",
"service": [ "dhcp4" ]
"arguments": {
"param1": "value1",
"param2": "value2",
...
}
}
</screen>
<command>command</command> is the name of the command to execute and
is mandatory. <command>arguments</command> is a map of parameters
required to carry out the given command. The exact content and
format of the map is command-specific.</para>
<para>
<command>service</command> is a list of the servers at which the control
command is targeted. In the example above, the control command is
targeted at the DHCPv4 server. In most cases, the CA will simply forward this
command to the DHCPv4 server for processing via a UNIX domain socket.
Sometimes, the command including a service value may also be processed by the
CA, if the CA is running a hooks library which handles such a command for the
given server. As an example, the hooks library loaded by the CA
may perform some operations on the database, such as adding host reservations,
modifying leases, etc. An advantage of performing DHCPv4-specific
administrative operations in the CA, rather than forwarding it to
the DHCPv4 server, is the ability to perform these operations without
disrupting the DHCPv4 service, since the DHCPv4 server doesn't have to stop
processing DHCP messages to apply changes to the database. Nevertheless,
these situations are rather rare and, in most cases, when the
<command>service</command> parameter contains a name of the service
the commands are simply forwarded by the CA. The forwarded command
includes the <command>service</command> parameter but this parameter
is ignored by the receiving server. This parameter is only meaningful
to the CA.
</para>
<para>
If the command received by the CA does not include a <command>service</command>
parameter or this list is empty, the CA simply processes this message
on its own. For example, a <command>config-get</command> command which
includes no service parameter returns the Control Agent's own
configuration. The <command>config-get</command> with a service
value "dhcp4" is forwarded to the DHCPv4 server and returns the
DHCPv4 server's configuration.
</para>
<para>
The following list shows the mapping of the values carried within the
<command>service</command> parameter to the servers to which the commands
are forwarded:
<itemizedlist>
<listitem>
<simpara><command>dhcp4</command> - the command is forwarded to the
<command>kea-dhcp4</command> server.</simpara>
</listitem>
<listitem>
<simpara><command>dhcp6</command> - the command is forwarded to the
<command>kea-dhcp6</command> server.</simpara>
</listitem>
<listitem>
<simpara><command>d2</command> - the command is forwarded to the
<command>kea-d2</command> server.</simpara>
</listitem>
</itemizedlist>
</para>
<para>The server processing the incoming command will send a response of
the form:
<screen>
{
"result": 0|1|2|3,
"text": "textual description",
"arguments": {
"argument1": "value1",
"argument2": "value2",
...
}
}
</screen>
<command>result</command> indicates the outcome of the command. A value of 0
means success, while any non-zero value designates an error or a
failure to complete the requested action. Currently 1 indicates a generic
error, 2 means that a command is not supported, and 3 means that the
requested operation was completed, but the requested object was not
found. For example, a well-formed
command that requests a subnet that exists in a server's configuration
returns the result 0. If the server encounters an error condition, it
returns 1. If the command asks for the IPv6 subnet, but was sent to a DHCPv4
server, it returns 2. If the query asks for a subnet-id and there
is no subnet with such an id, the result is 3.</para>
<para>
The <command>text</command> field typically appears when the result is non-zero
and contains a description of the error encountered, but it often also appears
for successful outcomes. The exact text is command-specific, but in general
uses plain English to describe the outcome of the command.
<command>arguments</command> is a map of additional data values
returned by the server which are specific to the command issued. The map
may be present, but that depends on the specific command.
</para>
<note>
<simpara>
When sending commands via Control Agent, it is possible to specify
multiple services at which the command is targeted. CA forwards this
command to each service individually. Thus, the CA response to the
controlling client contains an array of individual responses.
</simpara>
</note>
</section>
<section xml:id="ctrl-channel-client">
<title>Using the Control Channel</title>
<para>The easiest way to start interacting with the control API is to use common UNIX/Linux tools
such as <command>socat</command> and <command>curl</command>.</para>
<para>In order to control the given Kea service via UNIX domain socket, use
<command>socat</command> in interactive mode as follows:
<screen>
$ socat UNIX:/path/to/the/kea/socket -
</screen>
or in batch mode, include the "ignoreeof" option as shown below to ensure
socat waits long enough for the server to respond:
<screen>
$ echo "{ some command...}" | socat UNIX:/path/to/the/kea/socket -,ignoreeof
</screen>
where <command>/path/to/the/kea/socket</command> is the path specified in the
<command>Dhcp4/control-socket/socket-name</command> parameter in the Kea
configuration file. Text passed to <command>socat</command>
is sent to Kea and the responses received from Kea are printed to standard
output. This approach communicates with the specific server directly and
bypasses the Control Agent.</para>
<para>It is also easy to open a UNIX socket programmatically. An example of
a simple client written in C is available in the Kea Developer's
Guide, in the Control Channel Overview chapter, in the Using Control Channel section.</para>
<para>To use Kea's RESTful API with <command>curl</command>, you may
use the following:
<screen>
$ curl -X POST -H "Content-Type: application/json" -d '{ "command": "config-get", "service": [ "dhcp4" ] }' http://ca.example.org:8000/
</screen>
This assumes that the Control Agent is running on host
<filename>ca.example.org</filename> and is running the RESTful service on port 8000.
</para>
</section>
<section xml:id="commands-common">
<title>Commands Supported by Both the DHCPv4 and DHCPv6 Servers</title>
<section xml:id="command-build-report">
<title>build-report</title>
<para>
The <emphasis>build-report</emphasis> command returns
on the control channel what the command line
<command>-W</command> argument displays, i.e. the embedded
content of the <filename>config.report</filename> file.
This command does not take any parameters.
</para>
<screen>
{
"command": "build-report"
}
</screen>
</section> <!-- end of command-build-report -->
<section xml:id="command-config-get">
<title>config-get</title>
<para>The <emphasis>config-get</emphasis> command retrieves the current
configuration used by the server. This command does not take any
parameters. The configuration returned is roughly equal to the
configuration that was loaded using the -c command line option during server
start-up or later set using config-set command. However, there may be
certain differences, as comments are not retained. If the original
configuration used file inclusion, the returned configuration will
include all parameters from all the included files.</para>
<para> Note that the returned configuration is not redacted, i.e. it will
contain database passwords in plain text if those were specified in the
original configuration. Care should be taken not to expose the command
channel to unprivileged users.</para>
<para>
An example command invocation looks like this:
<screen>
{
"command": "config-get"
}
</screen>
</para>
</section> <!-- end of command-config-get -->
<section xml:id="command-config-reload">
<title>config-reload</title>
<para>The <emphasis>config-reload</emphasis> command instructs
Kea to load again the configuration file that was used
previously. This operation is useful if the configuration file
has been changed by some external source; for example, a
sysadmin can tweak the configuration file and use this command
to force Kea pick up the changes.</para>
<para>Caution should be taken when mixing this with config-set
commands. Kea remembers the location of the configuration file
it was started with, and this configuration can be significantly
changed using config-set command. When config-reload is issued
after config-set, Kea will attempt to reload its original
configuration from the file, possibly losing all changes
introduced using config-set or other commands.</para>
<para><emphasis>config-reload</emphasis> does not take any parameters.
An example command invocation looks like this:
<screen>
{
"command": "config-reload"
}
</screen>
</para>
</section> <!-- end of command-config-reload -->
<section xml:id="command-config-test">
<title>config-test</title>
<para>
The <emphasis>config-test</emphasis> command instructs the server to check
whether the new configuration supplied in the command's arguments can
be loaded. The supplied configuration is expected to be the full
configuration for the target server, along with an optional Logger
configuration. As for the <command>-t</command> command, some sanity checks
are not performed so it is possible a configuration which successfully
passes this command will still fail in the <command>config-set</command>
command or at launch time.
The structure of the command is as follows:
</para>
<screen>
{
"command": "config-test",
"arguments": {
"&lt;server&gt;": {
}
}
}
</screen>
<para>
where &lt;server&gt; is the configuration element name for a given server
such as "Dhcp4" or "Dhcp6". For example:
</para>
<screen>
{
"command": "config-test",
"arguments": {
"Dhcp6": {
:
}
}
}
</screen>
<para>
The server's response will contain a numeric code, "result" (0 for success,
non-zero on failure), and a string, "text", describing the outcome:
<screen>
{"result": 0, "text": "Configuration seems sane..." }
or
{"result": 1, "text": "unsupported parameter: BOGUS (&lt;string&gt;:16:26)" }
</screen>
</para>
</section> <!-- end of command-config-test -->
<section xml:id="command-config-write">
<title>config-write</title>
<para>The <emphasis>config-write</emphasis> command instructs the Kea server
to write its current configuration to a file on disk. It takes one
optional argument called <emphasis>filename</emphasis> that specifies
the name of the file to write the configuration to. If not specified, the
name used when starting Kea (passed as a -c argument) will be
used. If a relative path is specified, Kea will write its files
only in the directory it is running.</para>
<para>
An example command invocation looks like this:
<screen>
{
"command": "config-write",
"arguments": {
"filename": "config-modified-2017-03-15.json"
}
}
</screen>
</para>
</section> <!-- end of command-config-write -->
<section xml:id="command-leases-reclaim">
<title>leases-reclaim</title>
<para>
The <emphasis>leases-reclaim</emphasis> command instructs the server to
reclaim all expired leases immediately. The command has the following
JSON syntax:
<screen>
{
"command": "leases-reclaim",
"arguments": {
"remove": true
}
}
</screen>
</para>
<para>The <emphasis>remove</emphasis> boolean parameter is mandatory
and indicates whether the reclaimed leases should be removed from
the lease database (if true), or left in the
<emphasis>expired-reclaimed</emphasis> state (if false). The latter
facilitates lease affinity, i.e. the ability to re-assign an expired lease to
the same client which used this lease before. See
<xref linkend="lease-affinity"/> for the details. Also, see
<xref linkend="lease-reclamation"/> for general information
about the processing of expired leases (leases reclamation).</para>
</section>
<section xml:id="command-libreload">
<title>libreload</title>
<para>
The <emphasis>libreload</emphasis> command first unloads and then
loads all currently loaded hook libraries. This is primarily intended
to allow one or more hook libraries to be replaced with newer versions
without requiring Kea servers to be reconfigured or restarted. Note that
the hook libraries are passed the same parameter values (if any)
that were passed when they originally loaded.
<screen>
{
"command": "libreload",
"arguments": { }
}
</screen>
</para>
<para>
The server will respond with a result of either 0, indicating success, or 1,
indicating failure.
</para>
</section> <!-- end of command-libreload -->
<section xml:id="command-list-commands">
<title>list-commands</title>
<para>
The <emphasis>list-commands</emphasis> command retrieves a list of all
commands supported by the server. It does not take any arguments.
An example command may look like this:
<screen>
{
"command": "list-commands",
"arguments": { }
}
</screen>
</para>
<para>
The server responds with a list of all supported commands. The
arguments element is a list of strings, each of which conveys
one supported command.
</para>
</section> <!-- end of command-list-commands -->
<section xml:id="command-config-set">
<title>config-set</title>
<para>
The <emphasis>config-set</emphasis> command instructs the server to replace
its current configuration with the new configuration supplied in the
command's arguments. The supplied configuration is expected to be the full
configuration for the target server, along with an optional Logger
configuration. While optional, the Logger configuration is highly
recommended, as without it the server will revert to its default logging
configuration. The structure of the command is as follows:
</para>
<screen>
{
"command": "config-set",
"arguments": {
"&lt;server&gt;": {
}
}
}
</screen>
<para>
where &lt;server&gt; is the configuration element name for a given server
such as "Dhcp4" or "Dhcp6". For example:
</para>
<screen>
{
"command": "config-set",
"arguments": {
"Dhcp6": {
:
}
}
}
</screen>
<para>
If the new configuration proves to be invalid, the server retains
its current configuration. Please note that the new configuration is
retained in memory only; if the server is restarted or a configuration
reload is triggered via a signal, the server uses the configuration
stored in its configuration file.
The server's response contains a numeric code, "result" (0 for success,
non-zero on failure), and a string, "text", describing the outcome:
<screen>
{"result": 0, "text": "Configuration successful." }
or
{"result": 1, "text": "unsupported parameter: BOGUS (&lt;string&gt;:16:26)" }
</screen>
</para>
</section> <!-- end of command-config-set -->
<section xml:id="command-shutdown">
<title>shutdown</title>
<para>
The <emphasis>shutdown</emphasis> command instructs the server to initiate
its shutdown procedure. It is the equivalent of sending a SIGTERM signal
to the process. This command does not take any arguments. An example
command may look like this:
<screen>
{
"command": "shutdown"
}
</screen>
</para>
<para>
The server responds with a confirmation that the shutdown procedure
has been initiated.
</para>
</section> <!-- end of command-shutdown -->
<section id="command-dhcp-disable">
<title>dhcp-disable</title>
<para>
The <emphasis>dhcp-disable</emphasis> command globally disables the DHCP
service. The server continues to operate, but it drops all received DHCP
messages. This command is useful when the server's maintenance requires that
the server temporarily stop allocating new leases and renew existing leases.
It is also useful in failover-like configurations during a synchronization of
the lease databases at startup, or recovery after a failure. The optional parameter
<emphasis>max-period</emphasis> specifies the time in seconds after which the
DHCP service should be automatically re-enabled, if the
<emphasis>dhcp-enable</emphasis> command is not sent before this time elapses.
</para>
<screen>
{
"command": "dhcp-disable",
"arguments": {
"max-period": 20
}
}
</screen>
</section> <!-- end of command-dhcp-disable -->
<section id="command-dhcp-enable">
<title>dhcp-enable</title>
<para>
The <emphasis>dhcp-enable</emphasis> command globally enables the DHCP
service.
</para>
<screen>
{
"command": "dhcp-enable"
}
</screen>
</section> <!-- end of command-dhcp-disable -->
<section xml:id="command-version-get">
<title>version-get</title>
<para>
The <emphasis>version-get</emphasis> command returns
extended information about the Kea version. It is the same
information available via the <command>-V</command> command-line
argument. This command does not take any parameters.
</para>
<screen>
{
"command": "version-get"
}
</screen>
</section> <!-- end of command-version-get -->
<section xml:id="command-server-tag-get">
<title>server-tag-get</title>
<para>
The <emphasis>server-tag-get</emphasis> command returns
the server tag. This command does not take any parameters.
</para>
<screen>
{
"command": "server-tag-get"
}
</screen>
</section> <!-- end of command-server-tag-get -->
</section> <!-- end of commands supported by both servers -->
<section>
<title>Commands Supported by D2 Server</title>
<para>The D2 server supports only a subset of DHCPv4 / DHCPv6 server
commands:
<itemizedlist>
<listitem>
<simpara>build-report</simpara>
</listitem>
<listitem>
<simpara>config-get</simpara>
</listitem>
<listitem>
<simpara>config-reload</simpara>
</listitem>
<listitem>
<simpara>config-set</simpara>
</listitem>
<listitem>
<simpara>config-test</simpara>
</listitem>
<listitem>
<simpara>config-write</simpara>
</listitem>
<listitem>
<simpara>list-commands</simpara>
</listitem>
<listitem>
<simpara>shutdown</simpara>
</listitem>
<listitem>
<simpara>version-get</simpara>
</listitem>
</itemizedlist>
</para>
</section>
<section xml:id="agent-commands">
<title>Commands Supported by Control Agent</title>
<para>The following commands listed in <xref linkend="commands-common"/>
are also supported by the Control Agent, i.e. when the
<command>service</command> parameter is blank, the commands are handled
by the CA and they relate to the CA process itself:
<itemizedlist>
<listitem>
<simpara>build-report</simpara>
</listitem>
<listitem>
<simpara>config-get</simpara>
</listitem>
<listitem>
<simpara>config-reload</simpara>
</listitem>
<listitem>
<simpara>config-set</simpara>
</listitem>
<listitem>
<simpara>config-test</simpara>
</listitem>
<listitem>
<simpara>config-write</simpara>
</listitem>
<listitem>
<simpara>list-commands</simpara>
</listitem>
<listitem>
<simpara>shutdown</simpara>
</listitem>
<listitem>
<simpara>version-get</simpara>
</listitem>
</itemizedlist>
</para>
</section>
</chapter>

1063
doc/guide/ddns.xml
View File

File diff suppressed because it is too large Load Diff

5838
doc/guide/dhcp4-srv.xml
View File

File diff suppressed because it is too large Load Diff

5858
doc/guide/dhcp6-srv.xml
View File

File diff suppressed because it is too large Load Diff

137
doc/guide/hammer.xml
View File

@ -1,137 +0,0 @@
<!--
- Copyright (C) 2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, You can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- need this include to make the &keaversion; macro work -->
<!DOCTYPE book [
<!ENTITY % keaversion SYSTEM "version.ent">
%keaversion;
]>
<section xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="hammer">
<title>Hammer Building Tool</title>
<para>
An optionl building tool called Hammer was introduced with Kea 1.6.0. It
is a Python 3 script that lets users automate tasks related to building
Kea, such as setting up virtual machines, installing Kea dependencies,
compiling Kea with various options, running unit-tests and more. This tool
was created primarily for internal QA purposes at ISC and it is
not included in the Kea distribution. However, it is available in
the Kea git repository. This tool was developed primarily for
internal purpose and ISC cannot guarantee its proper operation. If
you decide to use it, please do so with care.
</para>
<note>
<simpara>Use of this tool is completely optional. Everything it does can
be done manually.</simpara>
</note>
<para>
The first time user is strongly encouraged to look at Hammer's built in
help: <screen><userinput>./hammer.py --help</userinput></screen> It will
list available parameters.
</para>
<para>
Hammer is able to set up various operating systems running eiter in LXC
or in VirtualBox. To list of supported systems, use
<command>supported-systems</command> command:
<screen>
$<userinput>./hammer.py supported-systems</userinput>
fedora:
- 27: lxc, virtualbox
- 28: lxc, virtualbox
- 29: lxc, virtualbox
centos:
- 7: lxc, virtualbox
rhel:
- 8: virtualbox
ubuntu:
- 16.04: lxc, virtualbox
- 18.04: lxc, virtualbox
- 18.10: lxc, virtualbox
debian:
- 8: lxc, virtualbox
- 9: lxc, virtualbox
freebsd:
- 11.2: virtualbox
- 12.0: virtualbox
</screen>
It is also possible to run build locally, in current system (if
the OS is supported).
</para>
<!-- @todo: explain how to install deps (hammer ensure-hammer-deps), explain
what is installed -->
<para>
At first it is required to install Hammer dependencies which is Vagrant and either
VirtualBox or LXC. To make life easier Hammer can install Vagrant and required
Vagrant plugins using the command:
<screen><userinput>./hammer.py ensure-hammer-deps</userinput></screen>
VirtualBox and LXC need to be installed manually.
</para>
<para>
Basic functionality provided by Hammer is preparing building environment and
performing actual build and running unit tests locally, in current system.
This can be achieved by running the command:
<screen><userinput>./hammer.py build -p local</userinput></screen>
</para>
<para>
The scope of the process can be defined using --with (-w) and --without (-x) options.
By default the build command will build Kea with documentation, install it locally
and run unit tests.
</para>
<para>
To exclude installation and generating docs do:
<screen><userinput>./hammer.py build -p local -x install docs</userinput></screen>
</para>
<para>
The basic scope can be extended by: mysql, pgsql, cql, native-pkg, radius, shell, forge.
</para>
<note>
<simpara>For build Kea locally installing Hammer dependencies like Vagrant is not needed.</simpara>
</note>
<para>
Hammer can be told to set up a new virtual machine with specified operating system
and not running the build:
<screen><userinput>./hammer.py prepare-system -p virtualbox -s freebsd -r 12.0</userinput></screen>
This way we can prepare a system for our own use. To get to such system using SSH invoke:
<screen><userinput>./hammer.py ssh -p virtualbox -s freebsd -r 12.0</userinput></screen>
</para>
<para>
It is possible to speed up subsequent Hammer builds. To achieve this Hammer
employs <ulink url="https://ccache.samba.org/">ccache</ulink>. During compilation
ccache stores object to shared folder. In subsequent runs instead doing actuall
compilation ccache just returns stored earlier objects. Cache with objects for
reuse needs to be stored outside of VM or LXC. To indicate such folder Hammer
requires providing --ccache-dir parameter. In indicated folder there are stored
objects for each target operating system separatelly.
<screen><userinput>
./hammer.py build -p lxc -s ubuntu -r 18.04 --ccache-dir ~/kea-ccache
</userinput></screen>
</para>
<note>
<simpara>For now ccache is only supported for LXC provider in Hammer. Support
for VirtualBox will be added later.</simpara>
</note>
<para>
For more information check: <screen><userinput>./hammer.py --help</userinput></screen>
</para>
</section>

1512
doc/guide/hooks-cb-cmds.xml
View File

File diff suppressed because it is too large Load Diff

243
doc/guide/hooks-class-cmds.xml
View File

@ -1,243 +0,0 @@
<!--
- Copyright (C) 2018-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<section xml:id="class-cmds-library">
<title>class_cmds: Class Commands</title>
<para>
This section describes the Class Commands hooks library, which exposes
several control commands for manipulating client classes (part of
the Kea DHCP servers' configurations) without the need to restart those
servers. Using these commands it is possible to add, update, delete, and
list client classes configured for a given server.
<note>
<para>This library may only be loaded by the <command>kea-dhcp4</command>
or the <command>kea-dhcp6</command> process.
</para>
</note>
<para>The Class Commands hooks library is available to premium Kea
customers only.</para>
</para>
<section xml:id="command-class-add">
<title>class-add Command</title>
<para>The <command>class-add</command> command adds a new client
class to the DHCP server configuration. This class is appended at the
end of the list of classes used by the server and may depend
on any of the already configured client classes.</para>
<para>The following example demonstrates how to add a new client class
to the DHCPv4 server configuration:
<screen>
{
"command": "class-add",
"arguments": {
"client-classes": [
{
"name": "ipxe_efi_x64",
"test": "option[93].hex == 0x0009",
"next-server": "192.0.2.254",
"server-hostname": "hal9000",
"boot-file-name": "/dev/null"
}
]
}
}
</screen>
</para>
<para>
Note that the <command>client-classes</command> parameter is a JSON list,
but it allows only a single client class to be present.
</para>
<para>
Here is the response to the <command>class-add</command>
command in our example:
<screen>
{
"result": 0,
"text": "Class 'ipxe_efi_x64' added."
}
</screen>
</para>
</section>
<section xml:id="command-class-update">
<title>class-update Command</title>
<para>
The <command>class-update</command> command updates an existing
client class in the DHCP server configuration. If the client class with the
given name doesn't exist, the server returns the result code of 3, which means that
the server configuration is not modified and the client class does not exist. The
<command>class-add</command> command must be used instead to create the new
client class.
</para>
<para>
The <command>class-update</command> command has the same argument structure
as the <command>class-add</command> command:
<screen>
{
"command": "class-update",
"arguments": {
"client-classes": [
{
"name": "ipxe_efi_x64",
"test": "option[93].hex == 0x0017",
"next-server": "0.0.0.0",
"server-hostname": "xfce",
"boot-file-name": "/dev/null"
}
]
}
}
</screen>
</para>
<para>
Here is the response for our example:
<screen>
{
"result": 0,
"text": "Class 'ipxe_efi_x64' updated."
}
</screen>
</para>
<para>
Any parameter of the client class can be modified with this command, except
<command>name</command>. There is currently no way to rename the class,
because the class name is used as a key for searching the class to be updated.
To achieve a similar effect to renaming the class, an existing class
can be removed with the <command>class-del</command> command and then added
again with a different name using <command>class-add</command>. Note, however,
that the class with the new name will be added at the end of the list of
configured classes.
</para>
</section>
<section xml:id="command-class-del">
<title>class-del Command</title>
<para>The <command>class-del</command> is used to remove a particular class
from the server configuration. The class to be removed is identified by name.
The class is not removed if there are other classes depending on it;
to remove such a class, the dependent classes must be removed first.</para>
<para>The following is a sample command removing the
<command>ipxe_efi_x64</command> class:
<screen>
{
"command": "class-del",
"arguments": {
{
"name": "ipxe_efi_x64"
}
}
}
</screen>
</para>
<para>Here is the response to the <command>class-del</command>
command in our example, when the specified client class has been found:
<screen>
{
"result": 0,
"text": "Class 'ipxe_efi_x64' deleted."
}
</screen>
</para>
<para>If the class doesn't exist, the result of 3 is returned.</para>
</section>
<section xml:id="command-class-list">
<title>class-list Command</title>
<para><command>class-list</command> is used to retrieve a list of all
client classes. This command includes no arguments:
<screen>
{
"command": "class-list"
}
</screen>
</para>
<para>
Here is the response of the server in our example, including the list
of client classes:
<screen>
{
"result": 0,
"text": "2 classes found",
"arguments": {
"client-classes": [
{
"name": "ipxe_efi_x64"
},
{
"name": "pxeclient"
}
]
}
}
</screen>
</para>
<para>
Note that the returned list does not contain full class definitions, but
merely class names. To retrieve full class information, the
<command>class-get</command> command should be used.
</para>
</section>
<section xml:id="command-class-get">
<title>class-get Command</title>
<para><command>class-get</command> is used to retrieve detailed information
about a specified class. The command structure is very simple:
<screen>
{
"command": "class-get",
"arguments": {
"name": "pxeclient"
}
}
</screen>
</para>
<para>
If the class with the specified name does not exist, the status code of 3
is returned. If the specified client class exists, the class details are
returned in the following format:
<screen>
{
"result": 0,
"text": "Class 'pxeclient' definition returned",
"arguments": {
"client-classes": [
{
"name": "pxeclient",
"only-if-required": true,
"test": "option[vendor-class-identifier].text == 'PXEClient'",
"option-def": [
{
"name": "configfile",
"code": 209,
"type": "string"
}
],
"option-data": [ ],
"next-server": "0.0.0.0",
"server-hostname": "xfce",
"boot-file-name": "/dev/null"
}
]
}
}
</screen>
</para>
<para>
Note that the example above is DHCPv4-specific; the last three parameters
are only returned by the DHCPv4 server and are never returned by the DHCPv6
server. Also, some of the parameters provided in this example may not be
returned if they are not specified for the class. Specifically,
<command>only-if-required</command>, <command>test</command>, and
<command>option-def</command> are not returned if they are not specified
for the class.
</para>
</section>
</section>

1423
doc/guide/hooks-ha.xml
View File

File diff suppressed because it is too large Load Diff

300
doc/guide/hooks-host-cache.xml
View File

@ -1,300 +0,0 @@
<section xml:id="hooks-host-cache">
<title>host_cache: Caching Host Reservations</title>
<para>Some database backends, such as RADIUS, are considered
slow and may take a long time to respond. Since Kea in general is
synchronous, the backend performance directly affects the DHCP
performance. To minimize the impact and improve performance, the
Host Cache library provides a way to cache information from the database locally.
This includes negative caching, i.e. the ability to remember
that there is no client information in the database.</para>
<para>
</para>
<para>
<note>
<para>This library may only be loaded by the <command>kea-dhcp4</command>
or the <command>kea-dhcp6</command> process.
</para>
</note>
In principle, this hook library can be used with any backend that may introduce
performance degradation (MySQL, PostgreSQL, Cassandra, RADIUS).
Host Cache must be loaded for the RADIUS accounting
mechanism to work.
</para>
<para>
The Host Cache hook library is currently very simple. It takes only
one optional parameter ("maximum") that defines the maximum number
of hosts to be cached. If not specified, the default value of 0 is
used, which means there is no limit. The hook library can be
loaded the same way as any other hook library; for example, this
configuration could be used:
<screen>
"Dhcp4": {
// Your regular DHCPv4 configuration parameters here.
"hooks-libraries": [
{
"library": "/usr/local/lib/kea/hooks/libdhc_host_cache.so",
"parameters": {
// Tells Kea to never cache more than 1000 hosts.
"maximum": 1000
}
} ]</screen>
</para>
<para>
Once loaded, the Host Cache hook library provides a number
of new commands which can be used either over the control
channel (see <xref linkend="ctrl-channel-client"/>) or the REST API
(see <xref linkend="agent-overview"/>). An example REST API client
is described in <xref linkend="shell-overview"/>. The following
sections describe the commands available.
</para>
<section id="command-cache-flush">
<title>cache-flush Command</title>
<para>This command allows removal of a specified number of cached
host entries. It takes one parameter, which defines the number of
hosts to be removed. An example usage looks as follows:
<screen>
{
"command": "cache-flush",
"arguments": 1000
}</screen>
This command will remove 1000 hosts. If you want to delete all
cached hosts, please use cache-clear instead. The hosts are stored
in FIFO order, so the oldest entries are always removed.
</para>
</section>
<section id="command-cache-clear">
<title>cache-clear Command</title>
<para>This command allows removal of all cached
host entries. An example usage looks as follows:
<screen>
{
"command": "cache-clear"
}</screen>
This command will remove all hosts. If you want to delete only a
certain number of cached hosts, please use cache-flush instead.
</para>
</section>
<section id="command-cache-size">
<title>cache-size Command</title>
<para>This command returns the number of host entries.
An example usage looks as follows:
<screen>
{
"command": "cache-size"
}</screen>
</para>
</section>
<section id="command-cache-write">
<title>cache-write Command</title>
<para>In general, the cache content is considered a runtime
state and the server can be shut down or restarted as usual; the
cache will then be repopulated after restart. However, there are
some cases when it is useful to store the contents of the cache. One
such case is RADIUS, where the cached hosts also retain
additional cached RADIUS attributes; there is no easy way to
obtain this information again, because renewing clients send their
packet to the DHCP server directly. Another use
case is when you want to restart the server and for performance
reasons you want it to start with a hot (populated) cache.
</para>
<para>This command allows writing the contents of the in-memory cache
to a file on disk. It takes one parameter, which defines the
filename. An example usage looks as follows:
<screen>
{
"command": "cache-write",
"arguments": "/tmp/kea-host-cache.json"
}</screen>
This causes the contents to be stored in the /tmp/kea-host-cache.json file.
That file can then be loaded with the cache-load command or processed by
any other tool that is able to understand JSON format.
</para>
</section>
<section id="command-cache-load">
<title>cache-load Command</title>
<para>See the previous section for a discussion of use cases
where it may be useful to write and load contents of the host
cache to disk.</para>
<para>This command allows the contents of a file on disk to be loaded into
an in-memory cache. It takes one parameter, which defines the
filename. An example usage looks as follows:
<screen>
{
"command": "cache-load",
"arguments": "/tmp/kea-host-cache.json"
}</screen>
This command will store the contents to the /tmp/kea-host-cache.json file.
That file can then be loaded with the cache-load command or processed by
any other tool that is able to understand JSON format.
</para>
</section>
<section id="command-cache-get">
<title>cache-get Command</title>
<para>This command is similar to cache-write, but instead of
writing the cache contents to disk, it returns the contents to
whoever sent the command.</para>
<para>This command allows the contents of a file on disk to be loaded into
an in-memory cache. It takes one parameter, which defines the
filename. An example usage looks as follows:
<screen>
{
"command": "cache-get"
}</screen>
This command will return all the cached hosts. Note that the response
may be large.
</para>
</section>
<section id="command-cache-get-by-id">
<title>cache-get-by-id Command</title>
<para>This command is similar to cache-get, but instead of
returning the whole content it returns only the entries matching
the given identifier.</para>
<para>It takes one parameter, which defines the identifier of
wanted cached host reservations. An example usage looks as follows:
<screen>
{
"command": "cache-get-by-id",
"arguments": {
"hw-address": "01:02:03:04:05:06"
}
}</screen>
This command will return all the cached hosts with the given hardware address.
</para>
</section>
<section id="command-cache-insert">
<title>cache-insert Command</title>
<para>This command may be used to manually insert a host into the
cache; there are very few use cases when this command could be
useful. This command expects its arguments to follow the usual
syntax for specifying host reservations (see <xref
linkend="host-reservation-v4"/> or <xref
linkend="host-reservation-v6"/>), with one difference: the
subnet-id value must be specified explicitly.</para>
<para>
An example command that will insert an IPv4 host into the host
cache looks as follows:
<screen>
{
"command": "cache-insert",
"arguments": {
"hw-address": "01:02:03:04:05:06",
"subnet-id4": 4,
"subnet-id6": 0,
"ip-address": "192.0.2.100",
"hostname": "somehost.example.org",
"client-classes4": [ ],
"client-classes6": [ ],
"option-data4": [ ],
"option-data6": [ ],
"next-server": "192.0.0.2",
"server-hostname": "server-hostname.example.org",
"boot-file-name": "bootfile.efi",
"host-id": 0
}
}</screen>
</para>
<para>
An example command that will insert an IPv6 host into the host
cache looks as follows:
<screen>
{
"command": "cache-insert",
"arguments": {
"hw-address": "01:02:03:04:05:06",
"subnet-id4": 0,
"subnet-id6": 6,
"ip-addresses": [ "2001:db8::cafe:babe" ],
"prefixes": [ "2001:db8:dead:beef::/64" ],
"hostname": "",
"client-classes4": [ ],
"client-classes6": [ ],
"option-data4": [ ],
"option-data6": [ ],
"next-server": "0.0.0.0",
"server-hostname": "",
"boot-file-name": "",
"host-id": 0
}
}</screen>
</para>
</section>
<section id="command-cache-remove">
<title>cache-remove Command</title>
<para>Sometimes it is useful to remove a single entry from the
host cache. A good use case is a situation where the device is up,
Kea has already provided configuration, and the host entry is in
cache. As a result of administrative action (e.g. customer hasn't
paid their bills or has perhaps been upgraded to better service), the
information in the backend (e.g. MySQL or RADIUS) is being
updated. However, since cache is in use, Kea does not notice the
change as the cached values are used. The cache-remove command can
solve this problem by removing a cached entry after administrative
changes.</para>
<para>
The cache-remove command works similarly to the reservation-get
command. It allows querying by two parameters:
either subnet-id4 or subnet-id6; or
ip-address (may be an IPv4 or IPv6 address), hw-address (specifies
hardware/MAC address), duid, circuit-id, client-id, or flex-id.
</para>
<para>
An example command to remove an IPv4 host with reserved address
192.0.2.1 from a subnet with a subnet-id 123 looks as follows:
<screen>
{
"command": "cache-remove",
"arguments": {
"ip-address": "192.0.2.1",
"subnet-id": 123
}
}</screen>
</para>
<para>
Another example that removes an IPv6 host identifier by DUID and
specific subnet-id is:
<screen>
{
"command": "cache-remove",
"arguments": {
"duid": "00:01:ab:cd:f0:a1:c2:d3:e4",
"subnet-id": 123
}
}</screen>
</para>
</section>
</section>

870
doc/guide/hooks-lease-cmds.xml
View File

@ -1,870 +0,0 @@
<!--
- Copyright (C) 2018-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<section xml:id="lease-cmds">
<title>lease_cmds: Lease Commands</title>
<para>
This section describes the hook library with
commands used to manage leases. Kea provides a way to store lease
information in several backends (memfile, MySQL, PostgreSQL and
Cassandra), and this library provides a interface that can
manipulate leases in a unified, safe way. In particular, it allows
things previously impossible: lease manipulation in memfile while Kea
is running, sanity check changes, lease existence checks, and removal of all
leases belonging to a specific subnet. It can also catch more obscure
errors, like an attempt to add a lease with a subnet-id that does not exist in the
configuration, or configuring a lease to use an address that is outside
of the subnet to which it is supposed to belong.
The library also provides a non-programmatic way to manage user contexts
associated with leases.
<note>
<para>This library may only be loaded by the <command>kea-dhcp4</command>
or the <command>kea-dhcp6</command> process.
</para>
</note>
</para>
<para>There are many use cases where an administrative command may be
useful; for example, during migration between servers or
different vendors, when a certain network is being retired, or when a
device has been disconnected and the sysadmin knows for sure that it
will not be coming back. The "get" queries may be useful for automating
certain management and monitoring tasks. They can also act as
preparatory steps for lease updates and removals.</para>
<para>
This library provides the following commands:
<itemizedlist>
<listitem>
<para><command>lease4-add</command> - adds a new IPv4 lease;</para>
</listitem>
<listitem>
<para><command>lease6-add</command> - adds a new IPv6 lease;</para>
</listitem>
<listitem>
<para><command>lease6-bulk-apply</command> - creates, updates and/or
deletes multiple IPv6 leases in a single transaction;</para>
</listitem>
<listitem>
<para><command>lease4-get</command> - checks whether an IPv4 lease with
the specified parameters exists and returns it if it does;</para>
</listitem>
<listitem>
<para><command>lease6-get</command> - checks whether an IPv6 lease with
the specified parameters exists and returns it if it does;</para>
</listitem>
<listitem>
<para><command>lease4-get-all</command> - returns all IPv4 leases
or all IPv4 leases for the specified subnets;</para>
</listitem>
<listitem>
<para><command>lease6-get-all</command> - returns all IPv6 leases
or all IPv6 leases for the specified subnets;</para>
</listitem>
<listitem>
<para><command>lease4-get-page</command> - returns a set ("page")
of leases from the list of all IPv4 leases in the database.
By iterating through the pages it is possible to retrieve all the leases;</para>
</listitem>
<listitem>
<para><command>lease6-get-page</command> - returns a set ("page")
of leases from the list of all IPv6 leases in the database.
By iterating through the pages it is possible to retrieve all the leases;</para>
</listitem>
<listitem>
<para><command>lease4-del</command> - deletes an IPv4
lease with the specified parameters;</para>
</listitem>
<listitem>
<para><command>lease6-del</command> - deletes an IPv6
lease with the specified parameters;</para>
</listitem>
<listitem>
<para><command>lease4-update</command> - updates an IPv4 lease;</para>
</listitem>
<listitem>
<para><command>lease6-update</command> - updates an IPv6 lease;</para>
</listitem>
<listitem>
<para><command>lease4-wipe</command> - removes all leases from a
specific IPv4 subnet or from all subnets;</para>
</listitem>
<listitem>
<para><command>lease6-wipe</command> - removes all leases from a
specific IPv6 subnet or from all subnets;</para>
</listitem>
</itemizedlist>
</para>
<para>The lease commands library is part of the open source code and is
available to every Kea user.</para>
<para>
All commands use JSON syntax and can be issued either using
control channel (see <xref linkend="ctrl-channel"/>) or Control
Agent (see <xref linkend="kea-ctrl-agent"/>).
</para>
<para>
The library can be loaded in the same way as other hook libraries, and it
does not take any parameters. It supports both DHCPv4 and DHCPv6
servers.
<screen>
"Dhcp6": { <userinput>
"hooks-libraries": [
{
"library": "/path/libdhcp_lease_cmds.so"
}
...
] </userinput>
}
</screen>
</para>
<section id="command-lease4-add">
<title>lease4-add, lease6-add Commands</title>
<para id="command-lease6-add">
The <command>lease4-add</command> and <command>lease6-add</command>
commands allow for the creation of a new lease. Typically Kea creates
a lease when it first sees a new device; however,
sometimes it may be convenient to create the lease
manually. The <command>lease4-add</command> command requires
at least two parameters: an IPv4 address and an identifier, i.e. hardware
(MAC) address. A third parameter, subnet-id, is optional. If the subnet-id is not
specified or the specified value is 0, Kea will try to determine the
value by running a subnet-selection procedure. If specified, however,
its value must match the existing subnet. The simplest successful
call might look as follows:
<screen>
{
"command": "lease4-add",
"arguments": {
"ip-address": "192.0.2.202",
"hw-address": "1a:1b:1c:1d:1e:1f"
}
}
</screen>
</para>
<para>The <command>lease6-add</command> command requires three parameters: an
IPv6 address, an IAID value (identity association identifier, a value
sent by clients), and a DUID. As with lease4-add, the subnet-id parameter is optional. If the subnet-id is not
specified or the provided value is 0, Kea will try to determine the
value by running a subnet-selection procedure. If specified, however,
its value must match the existing subnet. For
example:
<screen>
{
"command": "lease6-add",
"arguments": {
"subnet-id": 66,
"ip-address": "2001:db8::3",
"duid": "1a:1b:1c:1d:1e:1f:20:21:22:23:24",
"iaid": 1234
}
}</screen>
<command>lease6-add</command> can also be used to add leases for IPv6
prefixes. In this case there are three additional parameters that must be
specified: subnet-id, type (set to value of "IA_PD"), and prefix
length. The actual prefix is set using ip-address field. Note that Kea cannot
guess subnet-id values for prefixes; they must be specified explicitly.
For example, to configure a lease for prefix 2001:db8:abcd::/48, the following
command can be used:
<screen>
{
"command": "lease6-add",
"arguments": {
"subnet-id": 66,
"type": "IA_PD",
"ip-address": "2001:db8:abcd::",
"prefix-len": 48,
"duid": "1a:1b:1c:1d:1e:1f:20:21:22:23:24",
"iaid": 1234
}
}</screen>
The commands can take a number of additional optional parameters:
<itemizedlist>
<listitem>
<para><command>valid-lft</command> - specifies the lifetime of the
lease, expressed in seconds. If not specified, the value
configured in the subnet related to the specified subnet-id is
used.</para>
</listitem>
<listitem>
<para><command>expire</command> - creates a timestamp of the lease
expiration time, expressed in unix format (seconds since 1 Jan
1970). If not specified, the default value is now + the lease lifetime (the value of valid-lft).</para>
</listitem>
<listitem>
<para><command>fqdn-fwd</command> - specifies whether the lease
should be marked as if a forward DNS update were conducted. Note this
only affects the the data stored in the lease database, and no DNS update
will be performed. If configured, a DNS
update to remove the A or AAAA records will be conducted when the
lease is removed due to expiration or being released by a
client. If not specified, the default value is false. The hostname
parameter must be specified if fqdn-fwd is set to true.</para>
</listitem>
<listitem>
<para><command>fqdn-rev</command> - specifies whether the lease
should be marked as if reverse DNS update were conducted. Note this
only affects the the data stored in the lease database, and no DNS update
will be performed.. If configured, a DNS
update to remove the PTR record will be conducted when the lease
is removed due to expiration or being released by a client. If not
specified, the default value is false. The hostname parameter must be
specified if fqdn-fwd is set to true.</para>
</listitem>
<listitem>
<para><command>hostname</command> - specifies the hostname to be
associated with this lease. Its value must be non-empty if either
fqdn-fwd or fwdn-rev are set to true. If not specified, the
default value is an empty string.</para>
</listitem>
<listitem>
<para><command>hw-address</command> - optionally specifies a hardware (MAC) address
for an IPv6 lease. It is a mandatory parameter
for an IPv4 lease.</para>
</listitem>
<listitem>
<para><command>client-id</command> - optionally specifies a client identifier
for an IPv4 lease.</para>
</listitem>
<listitem>
<para><command>preferred-lft</command> - optionally specifies a preferred lifetime
for IPv6 leases. If not specified, the value
configured for the subnet corresponding to the specified subnet-id
is used. This parameter is not used when adding an IPv4 lease.</para>
</listitem>
<listitem>
<para><command>user-context</command> - specifies the user
context to be associated with this lease. It must be a
JSON map.</para>
</listitem>
</itemizedlist>
</para>
<para>Here is an example of a more complex lease addition:
<screen>
{
"command": "lease6-add",
"arguments": {
"subnet-id": 66,
"ip-address": "2001:db8::3",
"duid": "01:02:03:04:05:06:07:08",
"iaid": 1234,
"hw-address": "1a:1b:1c:1d:1e:1f",
"preferred-lft": 500,
"valid-lft": 1000,
"expire": 12345678,
"fqdn-fwd": true,
"fqdn-rev": true,
"hostname": "urania.example.org",
"user-context": { "version": 1 }
}
}
</screen>
</para>
<para>
The command returns a status that indicates either a success (result
0) or a failure (result 1). A failed command always includes a text
parameter that explains the cause of failure. For example:
<screen>{ "result": 0, "text": "Lease added." }</screen> Example failure:
<screen>{ "result": 1, "text": "missing parameter 'ip-address' (&lt;string&gt;:3:19)" }</screen>
</para>
<section id="command-lease6-bulk-apply">
<title>lease6-bulk-apply</title>
<para>The <command>lease6-bulk-apply</command> was implemented to address
the performance penalty in the High Availability when a single DHCPv6
transaction resulted in multiple lease updates sent to the partner if
multiple address and/or prefix leases were allocated. Consider the case
when a DHCPv6 client requests the assignment of two IPv6 addresses and two IPv6
prefixes. That may result in allocation of 4 leases. In addition, the
DHCPv6 may assign different address than requested by the client during
the renew or rebind and delete the leases previously used by this client.
The are 6 of lease changes sent between the HA partners is in this case.
Sending these updates in individual commands, e.g. <command>lease6-update</command>
is highly inefficient and produces unnecessary delays in communication
between the HA partners and in sending the response to the DHCPv6 client.
</para>
<para>The <command>lease6-bulk-apply</command> command deals with this
problem by aggregating all lease changes in a single command. Both
deleted leases and new/updated leases are conveyed in a single command.
The receiving server iterates over the deleted leases and deletes them
from its lease database. Next, it iterates over the new/updated leases
and adds them to the database or updates them if they already exist.
</para>
<para>Even though the High Avialability is the major application for
this command, it can be freely used in all cases when it is desired to
send multiple lease changes in a single command.</para>
<para>In the following example, we ask to delete two leases and to add
or update two other leases in the database:
<screen>
{
"command": "lease6-bulk-apply",
"arguments": {
"deleted-leases": [
{
"ip-address": "2001:db8:abcd::",
"type": "IA_PD",
},
{
"ip-address": "2001:db8:abcd::234",
"type": "IA_NA",
}
],
"leases": [
{
"subnet-id": 66,
"ip-address": "2001:db8:cafe::",
"type": "IA_PD",
...
},
{
"subnet-id": 66,
"ip-address": "2001:db8:abcd::333",
"type": "IA_NA",
...
}
]
}
}
</screen>
</para>
<para>If any of the leases is malformed, no leases changes are applied
to the lease database. If the leases are well formed but there is a
failure to apply any of the lease changes to the database, the command
will continue to be processed for other leases. All the leases for which
the command was unable to apply the changes in the database will be
listed in the response.
</para>
<para>For example:
<screen>
{
"result": 0,
"text": "Bulk apply of 2 IPv6 leases completed".
"arguments": {
"failed-deleted-leases": [
{
"ip-address": "2001:db8:abcd::",
"type": "IA_PD",
"result": 3,
"error-message": "no lease found"
}
],
"failed-leases": [
{
"ip-address": "2001:db8:cafe::",
"type": "IA_PD",
"result": 1,
"error-message": "unable to communicate with the lease database"
}
]
}
}
</screen>
</para>
<para>The response above indicates that the hooks library was unable to
delete the lease for prefix "2001:db8:abcd::" and add or update the lease
for prefix "2001:db8:cafe::". However, there are two other lease changes
which have been applied as indicated by the text message. The
<command>result</command> is the status constant that indicates the type
of the error experienced for the particular lease. The meaning of the
returned codes are the same as the results returned for the commands.
In particular, the result of 1 indicates an error while processing the
lease, e.g. a communication error with the database. The result of 3
indicates that an attempt to delete the lease was unsuccessful because
such lease doesn't exist (empty result).
</para>
</section>
<section id="command-lease4-get">
<title>lease4-get, lease6-get Commands</title>
<para id="command-lease6-get">
<command>lease4-get</command> or <command>lease6-get</command>
can be used to query the lease database and retrieve existing
leases. There are two types of parameters the
<command>lease4-get</command> command supports: (address) or (subnet-id,
identifier-type, identifier). There are also two types for
<command>lease6-get</command>: (address,type) or (subnet-id,
identifier-type, identifier, IAID, type). The first type of query is
used when the address (either IPv4 or IPv6) is known, but the details
of the lease are not; one common use case of this type of query is to
find out whether a given address is being used. The second
query uses identifiers; currently supported identifiers for leases are:
"hw-address" (IPv4 only), "client-id" (IPv4 only), and "duid" (IPv6 only).
</para>
<para>
An example <command>lease4-get</command> command for getting a lease
using an IPv4 address is:
<screen>
{
"command": "lease4-get",
"arguments": {
"ip-address": "192.0.2.1"
}
}
</screen>
</para>
<para>An example of the <command>lease6-get</command> query
is:
<screen>
{
"command": "lease6-get",
"arguments": {
"ip-address": "2001:db8:1234:ab::",
"type": "IA_PD"
}
}</screen>
</para>
<para>An example query by "hw-address" for an IPv4 lease looks
as follows:
<screen>
{
"command": "lease4-get",
"arguments": {
"identifier-type": "hw-address",
"identifier": "08:08:08:08:08:08",
"subnet-id": 44
}
}</screen>
</para>
<para>An example query by "client-id" for an IPv4 lease looks
as follows:
<screen>
{
"command": "lease4-get",
"arguments": {
"identifier-type": "client-id",
"identifier": "01:01:02:03:04:05:06",
"subnet-id": 44
}
}</screen>
</para>
<para>An example query by (subnet-id, identifier-type,
identifier, iaid, type) for an IPv6 lease is:
<screen>
{
"command": "lease4-get",
"arguments": {
"identifier-type": "duid",
"identifier": "08:08:08:08:08:08",
"iaid": 1234567,
"type": "IA_NA",
"subnet-id": 44
}
}</screen>
The type is an optional parameter. Supported values are: IA_NA
(non-temporary address) and IA_PD (IPv6 prefix).
If not specified, IA_NA is assumed.
</para>
<para><command>leaseX-get</command> returns a result that indicates a
result of the operation and lease details, if found. It has one of the
following values: 0 (success), 1 (error), or 2 (empty). An empty
result means that a query has been completed properly, but the object
(a lease in this case) has not been found. The lease parameters, if
found, are returned as arguments.
</para>
<para>
An example result returned when the host was found:
<screen>{
"arguments": {
"client-id": "42:42:42:42:42:42:42:42",
"cltt": 12345678,
"fqdn-fwd": false,
"fqdn-rev": true,
"hostname": "myhost.example.com.",
"hw-address": "08:08:08:08:08:08",
"ip-address": "192.0.2.1",
"state": 0,
"subnet-id": 44,
"valid-lft": 3600
},
"result": 0,
"text": "IPv4 lease found."
}</screen>
</para>
</section>
<section id="command-lease4-get-all">
<title>lease4-get-all, lease6-get-all Commands</title>
<para id="command-lease6-get-all"><command>lease4-get-all</command> and
<command>lease6-get-all</command> are used to retrieve all
IPv4 or IPv6 leases, or all leases for the specified set of
subnets. All leases are returned when there are no arguments
specified with the command, as in the following example:
<screen>
{
"command": "lease4-get-all"
}
</screen>
</para>
<para>If the arguments are provided, it is expected that they contain the
"subnets" parameter, which is a list of subnet identifiers for which the
leases should be returned. For example, in order to retrieve all IPv6
leases belonging to the subnets with identifiers 1, 2, 3, and 4:
<screen>
{
"command": "lease6-get-all",
"arguments": {
"subnets": [ 1, 2, 3, 4 ]
}
}
</screen>
</para>
<para>
The returned response contains a detailed list of leases in the
following format:
<screen>{
"arguments": {
"leases": [
{
"cltt": 12345678,
"duid": "42:42:42:42:42:42:42:42",
"fqdn-fwd": false,
"fqdn-rev": true,
"hostname": "myhost.example.com.",
"hw-address": "08:08:08:08:08:08",
"iaid": 1,
"ip-address": "2001:db8:2::1",
"preferred-lft": 500,
"state": 0,
"subnet-id": 44,
"type": "IA_NA",
"valid-lft": 3600
},
{
"cltt": 12345678,
"duid": "21:21:21:21:21:21:21:21",
"fqdn-fwd": false,
"fqdn-rev": true,
"hostname": "",
"iaid": 1,
"ip-address": "2001:db8:0:0:2::",
"preferred-lft": 500,
"prefix-len": 80,
"state": 0,
"subnet-id": 44,
"type": "IA_PD",
"valid-lft": 3600
}
]
},
"result": 0,
"text": "2 IPv6 lease(s) found."
}</screen>
</para>
<warning>
<para>The <command>lease4-get-all</command> and
<command>lease6-get-all</command> commands may result in very
large responses. This may have a negative impact on the DHCP server's
responsiveness while the response is generated and transmitted
over the control channel, as the server imposes no restriction
on the number of leases returned as a result of this command.
</para>
</warning>
</section>
<section xml:id="lease-get-page-cmds">
<title>lease4-get-page, lease6-get-page Commands</title>
<para>The <command>lease4-get-all</command> and
<command>lease6-get-all</command> commands may result in very
large responses; generating such a response may consume CPU bandwidth
as well as memory. It may even cause the server to become
unresponsive. In case of large lease databases it is usually better
to retrieve leases in chunks, using the paging mechanism.
<command>lease4-get-page</command> and <command>lease6-get-page</command>
implement a paging mechanism for DHCPv4 and DHCPv6 servers respectively.
The following command retrieves the first 1024 IPv4 leases:
<screen>
{
"command": "lease4-get-page",
"arguments": {
"from": "start",
"limit": 1024
}
}
</screen>
</para>
<para>The keyword <command>start</command> denotes that the first page
of leases should be retrieved. Alternatively, an IPv4 zero address
can be specified to retrieve the first page:
<screen>
{
"command": "lease4-get-page",
"arguments": {
"from": "0.0.0.0",
"limit": 1024
}
}
</screen>
</para>
<para>Similarly, the IPv6 zero address can be specified in the
<command>lease6-get-page</command> command:
<screen>
{
"command": "lease6-get-page",
"arguments": {
"from": "::",
"limit": 6
}
}
</screen>
</para>
<para>The response has the following structure:
<screen>
{
"arguments": {
"leases": [
{
"ip-address": "2001:db8:2::1",
...
},
{
"ip-address": "2001:db8:2::9",
...
},
{
"ip-address": "2001:db8:3::1",
...
},
{
"ip-address": "2001:db8:5::3",
...
}
{
"ip-address": "2001:db8:4::1",
...
},
{
"ip-address": "2001:db8:2::7",
...
}
],
"count": 6
},
"result": 0,
"text": "6 IPv6 lease(s) found."
}
</screen>
</para>
<para>Note that the leases' details were excluded from the response above
for brevity.</para>
<para>Generally, the returned list is not sorted in any particular order.
Some lease database backends may sort leases in ascending order of addresses,
but the controlling client must not rely on this behavior. In cases of
highly distributed databases, such as Cassandra, ordering may be inefficient
or even impossible.</para>
<para>The <command>count</command> parameter contains the number of returned
leases on the page.
</para>
<para>To fetch the next page, the client must use the last address
of the current page as an input to the next
<command>lease4-get-page</command> or <command>lease6-get-page</command>
command call. In this example it is:
<screen>
{
"command": "lease6-get-page",
"arguments": {
"from": "2001:db8:2::7",
"count": 6
}
}
</screen>
because 2001:db8:2::7 is the last address on the current page.
</para>
<para>The client may assume that it has reached the last page when the
<command>count</command> value is lower than that specified in the command;
this includes the case when the <command>count</command> is equal to 0,
meaning that no leases were found.
</para>
</section>
<section id="command-lease4-del">
<title>lease4-del, lease6-del Commands</title>
<para id="command-lease6-del">
<command>leaseX-del</command> can be used to delete a lease from
the lease database. There are two types of parameters this command
supports, similar to leaseX-get commands: (address) for both v4 and
v6, (subnet-id, identifier-type, identifier) for v4, and (subnet-id,
identifier-type, identifier, type, IAID) for v6. The first type of
query is used when the address (either IPv4 or IPv6) is known, but the
details of the lease are not. One common use case is where an administrator
wants a specified address to no longer be used. The second form of the command uses
identifiers. For maximum flexibility, this interface uses identifiers
as a pair of values: type and the actual identifier. The currently
supported identifiers are "hw-address" (IPv4 only), "client-id"
(IPv4 only), and "duid" (IPv6 only). </para>
<para>
An example command for deleting a lease by address is:
<screen>
{
"command": "lease4-del",
"arguments": {
"ip-address": "192.0.2.202"
}
}</screen>
An example IPv4 lease deletion by "hw-address" is:
<screen>{
"command": "lease4-del",
"arguments": {
"identifier": "08:08:08:08:08:08",
"identifier-type": "hw-address",
"subnet-id": 44
}
}</screen>
</para>
<para><command>leaseX-del</command> returns a result that
indicates the outcome of the operation. It has one of the
following values: 0 (success), 1 (error), or 3 (empty). The
empty result means that a query has been completed properly,
but the object (a lease in this case) has not been found.
</para>
</section>
<section id="command-lease4-update">
<title>lease4-update, lease6-update Commands</title>
<para id="command-lease6-update">The <command>lease4-update</command> and
<command>lease6-update</command> commands can be used to update
existing leases. Since all lease database backends are indexed by IP
addresses, it is not possible to update an address, but all other fields
may be altered. If an address needs to be changed, please use
<command>leaseX-del</command> followed by
<command>leaseX-add</command>.</para>
<para>The subnet-id parameter
is optional. If not specified, or if the specified value is 0, Kea
will try to determine its value by running a subnet-selection
procedure. If specified, however, its value must match the existing
subnet.</para>
<para>The optional boolean parameter "force-create" specifies
whether the lease should be created if it doesn't exist in the database.
It defaults to false, which indicates that the lease is not created
if it doesn't exist. In such a case, an error is returned as a result
of trying to update a non-existing lease. If the "force-create" parameter
is set to true and the updated lease does not exist, the new lease is
created as a result of receiving the <command>leaseX-update</command>.
</para>
<para>
An example of a command to update an IPv4 lease is:
<screen>{
"command": "lease4-update",
"arguments": {
"ip-address": "192.0.2.1",
"hostname": "newhostname.example.org",
"hw-address": "1a:1b:1c:1d:1e:1f",
"subnet-id": 44,
"force-create": true
}
}</screen>
</para>
<para>
An example of a command to update an IPv6 lease is:
<screen>{
"command": "lease6-update",
"arguments": {
"ip-address": "2001:db8::1",
"duid": "88:88:88:88:88:88:88:88",
"iaid": 7654321,
"hostname": "newhostname.example.org",
"subnet-id": 66,
"force-create": false
}
}</screen>
</para>
</section>
<section id="command-lease4-wipe">
<title>lease4-wipe, lease6-wipe Commands</title>
<para id="command-lease6-wipe"><command>lease4-wipe</command> and
<command>lease6-wipe</command> are designed to remove all
leases associated with a given subnet. This administrative
task is expected to be used when an existing subnet is being
retired. Note that the leases are not properly expired:
no DNS updates are carried out, no log messages are created, and
hooks are not called for the leases being removed.</para>
<para>An example of <command>lease4-wipe</command> is:
<screen>{
"command": "lease4-wipe",
"arguments": {
"subnet-id": 44
}
}</screen>
</para>
<para>An example of <command>lease6-wipe</command> is:
<screen>{
"command": "lease6-wipe",
"arguments": {
"subnet-id": 66
}
}</screen>
</para>
<para>The commands return a text description of the
number of leases removed, plus the status code 0 (success) if any
leases were removed or 2 (empty) if there were no
leases. Status code 1 (error) may be returned if the
parameters are incorrect or some other exception is
encountered.</para>
<para>Subnet-id 0 has a special meaning; it tells Kea to
delete leases from all configured subnets. Also, the
subnet-id parameter may be omitted. If not specified, leases
from all subnets are wiped.</para>
<para>Note: not all backends support this command.</para>
</section>
</section>
</section>

620
doc/guide/hooks-radius.xml
View File

@ -1,620 +0,0 @@
<!--
- Copyright (C) 2018-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-
- This license applies to the documentation itself, not the software.
-->
<!-- need this include to make the &keaversion; macro work -->
<!DOCTYPE book [
<!ENTITY % keaversion SYSTEM "version.ent">
%keaversion;
]>
<section xml:id="hooks-radius">
<title>radius: RADIUS Server Support</title>
<para>
The RADIUS hook library allows Kea to interact with two types of
RADIUS servers: access and accounting. Although the most common
DHCP and RADIUS integration is done on the DHCP relay-agent level
(DHCP clients send DHCP packets to DHCP relays; those relays contact
the RADIUS server and depending on the response either send the packet
to the DHCP server or drop it), it does require DHCP relay
hardware to support RADIUS communication. Also, even if the relay
has the necessary support, it is often not flexible enough to send and
receive additional RADIUS attributes. As such, the alternative
looks more appealing: to extend the DHCP server to talk to RADIUS
directly. That is the goal this library intends to fulfill.
<note>
<para>This library may only be loaded by the <command>kea-dhcp4</command>
or the <command>kea-dhcp6</command> process.
</para>
</note>
</para>
<para>
The major feature of the hook library is the ability to use RADIUS
authorization. When a DHCP packet is received, the Kea server
sends an Access-Request to the RADIUS server and waits for
a response. The server then sends back either an Access-Accept
with specific client attributes, or an Access-Reject. There are two
cases supported here: first, the Access-Accept includes a
Framed-IP-Address (for DHCPv4) or Framed-IPv6-Address (for
DHCPv6), which will be interpreted by Kea as an instruction to
assign that specified IPv4 or IPv6 address. This effectively
means RADIUS can act as an address-reservation database.
</para>
<para>
The second case supported is the ability to assign clients to
specific pools based on a RADIUS response. In this case, the RADIUS
server sends back an Access-Accept with Framed-Pool (IPv4) or
Framed-IPv6-Pool (IPv6). In both cases, Kea interprets those
attributes as client classes. With the addition of the
ability to limit access to pools to specific classes (see <xref
linkend="classification-pools"/>), RADIUS can be used to force the client
to be assigned a dynamic address from a specific pool. Furthermore,
the same mechanism can be used to control what kind of options the
client will get if there are DHCP options specified for a
particular class.
</para>
<section id="hooks-radius-install">
<title>Compilation and Installation of the RADIUS Hook</title>
<para>
The following section describes how to compile and install the
software on CentOS 7.0. Other systems may differ slightly.
</para>
<para>
STEP 1: Install dependencies
</para>
<para>
Several tools are needed to build dependencies and Kea
itself. The following commands should install them:
<screen>
$ sudo rpm -Uvh https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
$ sudo yum install gcc-g++ openssl-devel log4cplus-devel wget git
</screen>
</para>
<para>
STEP 2: FreeRADIUS installation
</para>
<para>
The Kea RADIUS hook library uses the FreeRADIUS client library to
conduct RADIUS communication. Unfortunately, the standard
1.1.7 release available from the project website
<uri xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="http://freeradius.org/sub_projects/">http://freeradius.org/sub_projects/</uri>
has several serious deficiencies; ISC engineers observed a segmentation
fault during testing. Also, the base version of the library does
not offer asynchronous transmissions, which are essential for
effective accounting implementation. Both of these issues
were addressed by ISC engineers, and the changes have been
reported to the FreeRADIUS client project. Acceptance of those
changes is outside of ISC's control, so until those
are processed, it is strongly recommended to use the FreeRADIUS
client with ISC's patches. To download and compile this version, please use
the following steps:
<screen>
$ git clone https://github.com/fxdupont/freeradius-client.git
$ cd freeradius-client/
$ git checkout iscdev
$ ./configure
$ make
$ sudo make install
</screen>
You may pass additional parameters to the configure script, if you need
to. Once installed, the FreeRADIUS client will be installed in
/usr/local. This is the default path where Kea will be looking for
it. You may install it in a different directory; if you choose to do
so, make sure you add that path to the configure script when compiling Kea.
</para>
<para>
STEP 3: Install recent BOOST version
</para>
<para>
Kea requires a reasonably recent Boost version. Unfortunately,
the version available in CentOS 7 is too old, so a
newer Boost version is necessary. Furthermore, CentOS 7 has an
old version of the g++ compiler that does not handle the latest Boost
versions. Fortunately, Boost 1.65 meets both requirements; it is both
recent enough for Kea and able to be compiled using
the g++ 4.8 version in CentOS.
</para>
<para>
To download and compile Boost 1.65, please use the following
commands:
<screen>
$ wget -nd https://dl.bintray.com/boostorg/release/1.65.1/source/boost_1_65_1.tar.gz
$ tar zxvf boost_1_65_1.tar.gz
$ cd boost_1_65_1/
$ ./bootstrap.sh
$ ./b2 --without-python
$ sudo ./b2 install
</screen>
Note that the b2 script may optionally take extra parameters; one
of them specifies the destination path where the sources are to
be compiled.
</para>
<para>
STEP 4: Compile and install Kea
</para>
<para>
Obtain the Kea sources either by downloading them from the git repository or extracting the tarball:
<screen>
# Use one of those commands to obtain the Kea sources:
# Choice 1: get from github
$ git clone https://github.com/isc-projects/kea
# Get a tarball and extract it
$ tar zxvf kea-&keaversion;.tar.gz
</screen>
The next step is to extract the premium Kea package that contains the RADIUS repository
into the Kea sources. After the tarball is extracted, the Kea sources should have
a premium/ subdirectory.
<screen>
$ cd kea
$ tar zxvf ../kea-premium-radius-&keaversion;.tar.gz
</screen>
Once this is done, verify that the Kea sources look similar to this:
<screen>
$ ls -l
total 952
-rw-r--r-- 1 thomson staff 6192 Apr 25 17:38 AUTHORS
-rw-r--r-- 1 thomson staff 29227 Apr 25 17:38 COPYING
-rw-r--r-- 1 thomson staff 360298 Apr 25 20:00 ChangeLog
-rw-r--r-- 1 thomson staff 645 Apr 25 17:38 INSTALL
-rw-r--r-- 1 thomson staff 5015 Apr 25 17:38 Makefile.am
-rw-r--r-- 1 thomson staff 587 Apr 25 17:38 README
-rw-r--r-- 1 thomson staff 62323 Apr 25 17:38 configure.ac
drwxr-xr-x 12 thomson staff 408 Apr 26 19:04 doc
drwxr-xr-x 7 thomson staff 238 Apr 25 17:38 examples
drwxr-xr-x 5 thomson staff 170 Apr 26 19:04 ext
drwxr-xr-x 8 thomson staff 272 Apr 26 19:04 m4macros
drwxr-xr-x 20 thomson staff 680 Apr 26 11:22 <userinput>premium</userinput>
drwxr-xr-x 10 thomson staff 340 Apr 26 19:04 src
drwxr-xr-x 14 thomson staff 476 Apr 26 19:04 tools
</screen>
The makefiles must be regenerated using autoreconf.</para>
<para>The next step is to configure Kea, and there are several essential steps necessary here.
Running autoreconf -if is necessary to compile the premium package that contains
RADIUS. Also, the --with-freeradius option is necessary to tell Kea where the FreeRADIUS
client sources can be found. Also, since the non-standard Boost is used, the path
to it must be specified.</para>
<screen>
$ autoreconf -i
$ ./configure --with-freeradius=/path/to/freeradius --with-boost-include=/path/to/boost --with-boost-lib-dir=/path/to/boost/state/lib
</screen>
<para>
For example, assuming the FreeRADIUS client was installed in the default directory (/usr/local)
and the Boost 1.65 sources were compiled in /home/thomson/devel/boost1_65_1, the configure path
should look as follows:</para>
<screen>
./configure --with-freeradius=/usr/local \
--with-boost-include=/home/thomson/devel/boost_1_65_1 \
--with-boost-lib-dir=/home/thomson/devel/boost_1_65_1/stage/lib
</screen>
<para>
After some checks, the configure script should print a report similar to the
following:
<screen>
Kea source configure results:
-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Package:
Name: kea
Version: &keaversion;
Extended version: &keaversion; (tarball)
OS Family: Linux
Hooks directory: /usr/local/lib/kea/hooks
Premium hooks: yes
Included Hooks: forensic_log flex_id host_cmds subnet_cmds radius host_cache
C++ Compiler:
CXX: g++ --std=c++11
CXX_VERSION: g++ (GCC) 4.8.5 20150623 (Red Hat 4.8.5-16)
CXX_STANDARD: 201103
DEFS: -DHAVE_CONFIG_H
CPPFLAGS: -DOS_LINUX -DBOOST_ASIO_HEADER_ONLY
CXXFLAGS: -g -O2
LDFLAGS: -lpthread
KEA_CXXFLAGS: -Wall -Wextra -Wnon-virtual-dtor -Wwrite-strings -Woverloaded-virtual -Wno-sign-compare -pthread -Wno-missing-field-initializers -fPIC
Python:
PYTHON_VERSION: not needed (because kea-shell is disabled)
Boost:
BOOST_VERSION: 1.65.1
BOOST_INCLUDES: -I/home/thomson/devel/boost_1_65_1
BOOST_LIBS: -L/home/thomson/devel/boost_1_65_1/stage/lib -lboost_system
OpenSSL:
CRYPTO_VERSION: OpenSSL 1.0.2k 26 Jan 2017
CRYPTO_CFLAGS:
CRYPTO_INCLUDES:
CRYPTO_LDFLAGS:
CRYPTO_LIBS: -lcrypto
Botan: no
Log4cplus:
LOG4CPLUS_VERSION: 1.1.3
LOG4CPLUS_INCLUDES: -I/usr/include
LOG4CPLUS_LIBS: -L/usr/lib -L/usr/lib64 -llog4cplus
Flex/bison:
FLEX: flex
BISON: bison -y
MySQL:
no
PostgreSQL:
no
Cassandra CQL:
no
Google Test:
no
Google Benchmark:
no
FreeRADIUS client:
FREERADIUS_INCLUDE: -I/usr/local/include
FREERADIUS_LIB: -L/usr/local/lib -lfreeradius-client
FREERADIUS_DICTIONARY: /usr/local/etc/radiusclient/dictionary
Developer:
Enable Debugging: no
Google Tests: no
Valgrind: not found
C++ Code Coverage: no
Logger checks: no
Generate Documentation: no
Parser Generation: no
Kea-shell: no
Perfdhcp: no
</screen>
</para>
<para>
Please make sure that your compilation has the following:
<itemizedlist>
<listitem>RADIUS listed in Included Hooks;</listitem>
<listitem>FreeRADIUS client directories printed and pointing to the right
directories;</listitem>
<listitem>Boost version at least 1.65.1. The versions available
in CentOS 7 (1.48 and and 1.53) are too old.</listitem>
</itemizedlist>
</para>
<para>
Once your configuration is complete, compile Kea using make. If your system has
more than one core, it is recommended that you use the "-j N" option to speed up the build.
<screen>
$ make -j5
$ sudo make install</screen>
</para>
</section>
<section id="hooks-radius-config">
<title>RADIUS Hook Configuration</title>
<para>
The RADIUS hook is a library that has to be loaded by either DHCPv4 or
DHCPv6 Kea servers. Unlike some other available hook libraries, this one
takes many parameters. For example, this configuration
could be used:
<screen>
"Dhcp4": {
// Your regular DHCPv4 configuration parameters here.
"hooks-libraries": [
{
// Note that RADIUS requires host-cache for proper operation,
// so that library is loaded as well.
"library": "/usr/local/lib/kea/hooks/libdhcp_host_cache.so"
},
{
"library": "/usr/local/lib/kea/hooks/libdhc_radius.so",
"parameters": {
// Specify where FreeRADIUS dictionary could be located
"dictionary": "/usr/local/etc/freeradius/dictionary",
// Specify which address to use to communicate with RADIUS servers
"bindaddr": "*",
// more RADIUS parameters here
}
} ]</screen>
</para>
<para>
RADIUS is a complicated environment. As such, it's not really possible
to provide a default configuration that would work out of the box.
However, we do have one example that showcases some of the more
common features. Please see doc/examples/kea4/hooks-radius.json in your
Kea sources.
</para>
<para>
The RADIUS hook library supports the following global configuration
flags, which correspond to FreeRADIUS client library options:
<itemizedlist>
<listitem><simpara><command>bindaddr</command> (default "*") specifies
the address to be used by the hook library in communication with RADIUS
servers. The "*" special value tells the kernel to choose
the address.</simpara></listitem>
<listitem><simpara><command>canonical-mac-address</command> (default
false) specifies whether MAC addresses in attributes follow the canonical
RADIUS format (lowercase pairs of hexadecimal digits separated by
'-').</simpara></listitem>
<listitem><simpara><command>client-id-pop0</command> (default false), used
with flex-id, removes the leading zero (or pair of zeroes in DHCPv6) type in
client-id (aka duid in DHCPv6). Implied by
client-id-printable.</simpara></listitem>
<listitem><simpara><command>client-id-printable</command> (default false)
checks whether the client-id/duid content is printable and uses it as is
instead of in hexadecimal. Implies client-id-pop0 and extract-duid as 0
and 255 are not printable.</simpara></listitem>
<listitem><simpara><command>deadtime</command> (default 0) is a mechanism
to try unresponsive servers after responsive servers. Its value
specifies the number of seconds after which a server is considered not to have answered,
so 0 disables the mechanism. As the asynchronous communication does not
use locks or atomics, it is recommended that you do not use this feature when running in this mode.</simpara></listitem>
<listitem><simpara><command>dictionary</command> (default set by configure
at build time) is the attribute and value dictionary. Note that it is a
critical parameter.</simpara></listitem>
<listitem><simpara><command>extract-duid</command> (default true) extracts
the embedded duid from an RFC 4361-compliant DHCPv4 client-id. Implied by
client-id-printable.</simpara></listitem>
<listitem><simpara><command>identifier-type4</command> (default client-id)
specifies the identifier type to build the User-Name attribute. It should
be the same as the host identifier, and when the flex-id hook library is
used the replace-client-id must be set to true; client-id will be used
with client-id-pop0. </simpara></listitem>
<listitem><simpara><command>identifier-type6</command> (default duid)
specifies the identifier type to build the User-Name attribute. It should
be the same as the host identifier, and when the flex-id hook library is
used the replace-client-id must be set to true; duid will be used with
client-id-pop0.</simpara></listitem>
<listitem><simpara><command>realm</command> (default "") is the default
realm.</simpara></listitem>
<listitem><simpara><command>reselect-subnet-address</command> (default
false) uses the Kea reserved address/RADIUS Framed-IP-Address or
Framed-IPv6-Address to reselect subnets where the address is not in
the subnet range.</simpara></listitem>
<listitem><simpara><command>reselect-subnet-pool</command> (default
false) uses the Kea client-class/RADIUS Frame-Pool to reselect
subnets where no available pool can be found.</simpara></listitem>
<listitem><simpara><command>retries</command> (default 3) is the number of
retries before trying the next server. Note that it is not supported for
asynchronous communication.</simpara></listitem>
<listitem><simpara><command>session-history</command> (default "") is the
name of the file providing persistent storage for accounting session
history.</simpara></listitem>
<listitem><simpara><command>timeout</command> (default 10) is the number
of seconds during which a response is awaited.</simpara></listitem>
</itemizedlist>
</para>
<para> When <command>reselect-subnet-pool</command> or
<command>reselect-subnet-address</command> is set to true at the
reception of RADIUS Access-Accept, the selected subnet is checked
against the client-class name or the reserved address; if it does
not match, another subnet is selected among matching subnets.
</para>
<para>
Two services are supported:
<itemizedlist>
<listitem><simpara><command>access</command> - the authentication service </simpara></listitem>
<listitem><simpara><command>accounting</command> - the accounting service</simpara></listitem>
</itemizedlist>
</para>
<para>
Configuration of services is divided into two parts:
<itemizedlist>
<listitem>
<simpara>servers that define RADIUS servers the library is expected to
contact. Each server may have the following items specified:</simpara>
<itemizedlist>
<listitem><simpara><command>name</command>, which specifies the IP
address of the server (it is possible to use a name which will be
resolved, but it is not recommended).</simpara></listitem>
<listitem><simpara><command>port</command> (default RADIUS
authentication or accounting service), which specifies the UDP port
of the server. Note that the FreeRADIUS client library by default
uses ports 1812 (authorization) and 1813 (accounting). Some server implementations
use 1645 (authorization) and 1646 (accounting). You may use the "port" parameter to
adjust as needed.</simpara></listitem>
<listitem><simpara><command>secret</command>, which authenticates
messages.</simpara></listitem>
</itemizedlist>
<simpara>There may be up to eight servers. Note that when no server is
specified, the service is disabled.</simpara>
</listitem>
<listitem>
<simpara>attributes which define additional information that
the Kea server will send to a RADIUS server. The parameter
must be identified either by a name or type. Its value can
be specified in one of three possible ways: data (which
defines a plain text value), raw (which defines the value in
hex), or expr (which defines an expression, which will be
evaluated for each incoming packet independently).
</simpara>
<itemizedlist>
<listitem><simpara><command>name</command> of the
attribute.</simpara></listitem>
<listitem><simpara><command>type</command> of the attribute. Either the type
or the name must be provided, and the attribute must be defined in the dictionary.</simpara></listitem>
<listitem><simpara><command>data</command> is the first of three
ways to specify the attribute content. The data entry is parsed by
the FreeRADIUS library, so values defined in the dictionary of the
attribute may be used.</simpara></listitem>
<listitem><simpara><command>raw</command> is the second of three
ways to specify the attribute content; it specifies the content in
hexadecimal. Note that it does not work with integer-content attributes
(date, integer, and IPv4 address); a string-content attribute
(string, IPv6 address, and IPv6 prefix) is
required.</simpara></listitem>
<listitem><simpara><command>expr</command> is the last way to
specify the attribute content. It specifies an evaluation expression
which must return a not-empty string when evaluated with the DHCP
query packet. Currently this is restricted to the access
service. </simpara></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
</para>
<para>
For example, to specify a single access server available on localhost that
uses "xyz123" as a secret, and tell Kea to send three additional attributes
(Password, Connect-Info, and Configuration-Token), the following snippet could
be used:
<screen>
"parameters": {
// Other RADIUS parameters here
"access": {
// This starts the list of access servers
"servers": [
{
// These are parameters for the first (and only) access server
"name": "127.0.0.1",
"port": 1812,
"secret": "xyz123"
}
// Additional access servers could be specified here
],
// This defines a list of additional attributes Kea will send to each
// access server in Access-Request.
"attributes": [
{
// This attribute is identified by name (must be present in the
// dictionary) and has static value (i.e. the same value will be
// sent to every server for every packet)
"name": "Password",
"data": "mysecretpassword"
},
{
// It's also possible to specify an attribute using its type,
// rather than a name. 77 is Connect-Info. The value is specified
// using hex. Again, this is a static value. It will be sent the
// same for every packet and to every server.
"type": 77,
"raw": "65666a6a71"
},
{
// This example shows how an expression can be used to send dynamic
// value. The expression (see Section 13) may take any value from
// the incoming packet or even its metadata (e.g. the interface
// it was received over from)
"name": "Configuration-Token",
"expr": "hexstring(pkt4.mac,':')"
}
] // End of attributes
} // End of access
// Accounting parameters.
"accounting": {
// This starts the list of accounting servers
"servers": [
{
// These are parameters for the first (and only) accounting server
"name": "127.0.0.1",
"port": 1813,
"secret": "sekret"
}
// Additional accounting servers could be specified here
]
}
}
</screen>
</para>
<para>For the RADIUS hook library to operate properly in DHCPv4, it is necessary
to also load the Host Cache hook library. The reason for this is somewhat
complex. In a typical deployment, the DHCP clients send their packets via
DHCP relay which inserts certain Relay Agent Information options, such as
circuit-id or remote-id. The values of those options are then used by the
Kea DHCP server to formulate the necessary attributes in the Access-Request message
sent to the RADIUS server. However, once the DHCP client gets its address, it
then renews by sending packets directly to the DHCP server. As a result, the
relays are not able to insert their RAI options and the DHCP server can't send the
Access-Request queries to the RADIUS server by using just the information from
incoming packets. Kea needs to keep the information received during the initial
Discover/Offer exchanges and use it again later when sending accounting
messages.</para>
<para>This mechanism is implemented based on user context in host reservations.
(See <xref linkend="user-context"/> for details about user context). The host
cache mechanism allows the information retrieved by RADIUS to be
stored and later used for sending accounting and access queries to the RADIUS
server. In other words, the host-cache mechanism is mandatory, unless you
do not want RADIUS communication for messages other than
Discover and the first Request from each client.</para>
</section>
</section>

258
doc/guide/hooks-stat-cmds.xml
View File

@ -1,258 +0,0 @@
<section xml:id="hooks-stat-cmds">
<title>stat_cmds: Supplemental Statistics Commands</title>
<para>
This library provides additional commands for
retrieving lease statistics from Kea DHCP servers. These commands
were added to address an issue with obtaining accurate lease
statistics in deployments running multiple Kea servers that use a
shared lease backend. The in-memory statistics kept by individual
servers only track lease changes made by that server; thus, in a
deployment with multiple servers (e.g. two kea-dhcp6 servers using the
same PostgreSQL database for lease storage), these statistics are incomplete.
The MySQL and PostgreSQL backends in Kea track
lease allocation changes as they occur via database triggers. Additionally,
all four lease backends were extended to support retrieving lease
statistics for all subnets, a single subnet, or a range of subnets.
Finally, this library was constructed to provide commands for retrieving
these statistics.
<note>
<para>This library may only be loaded by the <command>kea-dhcp4</command>
or the <command>kea-dhcp6</command> process.
</para>
</note>
</para>
<para>
The commands currently provided by this library are:
<itemizedlist>
<listitem>
<para><command>stat-lease4-get</command> - fetches DHCPv4 lease statistics</para>
</listitem>
<listitem>
<para><command>stat-lease6-get</command> - fetches DHCPv6 lease statistics</para>
</listitem>
</itemizedlist>
</para>
<para>
The Stat commands library is part of the open source code and is
available to every Kea user.
</para>
<para>
All commands use JSON syntax and can be issued directly to
the servers via either the control channel (see <xref linkend="ctrl-channel"/>)
or the Control Agent (see <xref linkend="kea-ctrl-agent"/>).
</para>
<para>
This library may be loaded by both kea-dhcp4 and kea-dhcp6 servers.
It is loaded in the same way as other libraries and currently has
no parameters:
</para>
<para>
<screen>
"Dhcp6": { <userinput>
"hooks-libraries": [
{
"library": "/path/libdhcp_stat_cmds.so"
}
...
] </userinput>
}
</screen>
</para>
<para>
In a deployment with multiple Kea DHCP servers sharing a common lease
storage, it may be loaded by any or all of the servers. However, one
thing to keep in mind is that a server's response to a stat-lease{4/6}-get
command will only contain data for subnets known to that server. In
other words, if a subnet does not appear in a server's configuration, Kea
will not retrieve statistics for it.
</para>
<section id="command-stat-lease4-get">
<title>stat-lease4-get, stat-lease6-get Commands</title>
<para id="command-stat-lease6-get">
The <command>stat-lease4-get</command> and <command>stat-lease6-get</command>
commands fetch lease statistics for a range of known subnets. The
range of subnets is determined through the use of optional command
input parameters:
<itemizedlist>
<listitem>
<para><command>subnet-id</command> - The ID of the subnet for which
lease statistics should be fetched. Use this to get statistics for
a single subnet. If the subnet does not exist, the command result
code is 3 (i.e. CONTROL_RESULT_EMPTY).
</para>
</listitem>
<listitem>
<para><command>subnet-range</command> - A pair of subnet IDs which
describe an inclusive range of subnets for which statistics should
be retrieved. The range may include one or more IDs that correspond
to no subnet: in this case, the command will only output lease
statistics for those that exist. However, if the range does not
include any known subnets, the command result code is 3
(i.e. CONTROL_RESULT_EMPTY).
<itemizedlist>
<listitem>
<para><command>first-subnet-id</command> - The ID of the first
subnet in the range.</para>
</listitem>
<listitem>
<para><command>last-subnet-id</command> - The ID of the last
subnet in the range.</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
The use of subnet-id and subnet-range are mutually exclusive.
If no parameters are given, the result will contain data for all
known subnets. Note that in configurations with large numbers of
subnets, this can result in a large response.
</para>
<para>
The following command fetches lease statistics for all known subnets from a kea-dhcp4 server:
<screen>
{
"command": "stat-lease4-get"
}
</screen>
</para>
<para>
The following command fetches lease statistics for subnet ID 10 from a kea-dhcp6 server:
<screen>
{
"command": "stat-lease6-get",
"arguments": {
"subnet-id" : 10
}
}
</screen>
</para>
<para>
The following command fetches lease statistics for all subnets with IDs in the range 10 through 50 from a kea-dhcp4 server:
<screen>
{
"command": "stat-lease4-get",
"arguments": {
"subnet-range" {
"first-subnet-id": 10,
"last-subnet-id": 50,
}
}
}
</screen>
</para>
<para>
The response to either command will contain three elements:
<itemizedlist>
<listitem>
<para><command>result</command> - a numeric value indicating the outcome of the
command where:
<itemizedlist>
<listitem><simpara><command>0</command> - the command was successful;</simpara></listitem>
<listitem><simpara><command>1</command> - an error occurred, an explanation will
be the "text" element;</simpara></listitem>
<listitem><simpara><command>2</command> - the fetch found no matching data</simpara></listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para><command>text</command> - an explanation of the command outcome. When the command
succeeds it will contain the command name along with the number of rows returned.</para>
</listitem>
<listitem>
<para><command>arguments</command> - a map containing the data returned by the
command as the element "result-set", which is patterned after SQL statement responses:
<itemizedlist>
<listitem><para><command>columns</command> - a list of text column labels
The columns returned for DHCPv4 are:
<itemizedlist>
<listitem><simpara><command>subnet-id</command> - ID of the subnet.</simpara></listitem>
<listitem><simpara><command>total-addresses</command> - total number of addresses
available for DHCPv4 management in the subnet. In other words, this is the sum of all
addresses in all the configured pools in the subnet.</simpara></listitem>
<listitem><simpara><command>assigned-addresses</command> - number of addresses
in the subnet that are currently assigned to a client.</simpara></listitem>
<listitem><simpara><command>declined-addresses</command> - number of addresses
in the subnet that are currently declined and are thus unavailable for assignment.
</simpara></listitem>
</itemizedlist></para>
</listitem>
<listitem><para>The columns returned for DHCPv6 are:
<itemizedlist>
<listitem><simpara><command>subnet-id</command> - ID of the subnet.</simpara></listitem>
<listitem><simpara><command>total-nas</command> - number of NA addresses available
for DHCPv6 management in the subnet. In other words, this is the sum of all
the NA addresses in the all configured NA pools in the subnet.</simpara></listitem>
<listitem><simpara><command>assigned-nas</command> - number of NA addresses in a
the subnet that are currently assigned to a client.</simpara></listitem>
<listitem><simpara><command>declined-nas</command> - number of NA addresses that
are currently declined and are thus unavailable for assignment.</simpara></listitem>
<listitem><simpara><command>total-pds</command> - total number of prefixes available
of DHCPv6 management in the subnet. In other words, this is the sum of all prefixes
in all the configured prefix pools in the subnet.</simpara></listitem>
<listitem><simpara><command>assigned-pds</command> - number of prefixes in the subnet
that are currently assigned to a client.</simpara></listitem>
</itemizedlist></para>
</listitem>
<listitem><para><command>rows</command> - a list of rows, one per subnet ID. Each row
contains a data value corresponding to and in the same order as each column
listed in "columns" for a given subnet.
</para></listitem>
<listitem><para><command>timestamp</command> - textual date and time the data was fetched,
expressed as GMT.</para></listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>
<para>
The response to a DHCPv4 command might look as follows:
<screen>
{
"result": 0,
"text": "stat-lease4-get: 2 rows found",
"arguments": {
"result-set": {
"columns": [ "subnet-id", "total-addresses", "assigned-addresses", "declined-addresses" ]
"rows": [
[ 10, 256, 111, 0 ],
[ 20, 4098, 2034, 4 ]
],
"timestamp": "2018-05-04 15:03:37.000000"
}
}
}
</screen>
</para>
<para>
The response to a DHCPv6 command might look as follows (subnet 10 has no
prefix pools, subnet 20 has no NA pools, and subnet 30 has both NA and PD
pools):
<screen>
{
"result": 0,
"text": "stat-lease6-get: 2 rows found",
"arguments": {
"result-set": {
"columns": [ "subnet-id", "total-nas", "assigned-nas", "declined-nas", "total-pds", "assigned-pds" ]
"rows": [
[ 10, 4096, 2400, 3, 0, 0],
[ 20, 0, 0, 0, 1048, 233 ]
[ 30, 256, 60, 0, 1048, 15 ]
],
"timestamp": "2018-05-04 15:03:37.000000"
}
}
}
</screen>
</para>
</section>
</section>

2965
doc/guide/hooks.xml
View File

File diff suppressed because it is too large Load Diff

753
doc/guide/install.xml
View File

@ -1,753 +0,0 @@
<!--
- Copyright (C) 2014-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="installation">
<title>Installation</title>
<section xml:id="packages">
<title>Packages</title>
<para>
Some operating systems or software package vendors may provide
ready-to-use, pre-built software packages for Kea. Installing a
pre-built package means you do not need to install the software
required only to build Kea and do not need to <emphasis>make</emphasis>
the software.
</para>
</section>
<section xml:id="install-hierarchy">
<title>Installation Hierarchy</title>
<para>
The following is the directory layout of the complete Kea installation.
(All directory paths are relative to the installation directory):
<itemizedlist>
<listitem>
<simpara>
<filename>etc/kea/</filename> —
configuration files.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>include/</filename> —
C++ development header files.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>lib/</filename> —
libraries.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>lib/kea/hooks</filename> —
additional hooks libraries.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>sbin/</filename> —
server software and commands used by the system administrator.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>share/kea/</filename> —
configuration specifications and examples.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>share/doc/kea/</filename> —
this guide, other supplementary documentation, and examples.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>share/man/</filename> —
manual pages (online documentation).
</simpara>
</listitem>
<listitem>
<simpara>
<filename>var/lib/kea/</filename> —
server identification, and lease databases files.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>var/log/</filename> —
log files.
</simpara>
</listitem>
<listitem>
<simpara>
<filename>var/run/kea/</filename> —
pid and logger lock files.
</simpara>
</listitem>
</itemizedlist>
</para>
</section>
<section xml:id="build-requirements">
<title>Building Requirements</title>
<para>
In addition to the run-time requirements (listed in <xref linkend="required-software"/>), building Kea from source code requires
various development include headers and program development tools.
</para>
<note>
<simpara>
Some operating systems have split their distribution packages into
a run-time and a development package. You will need to install
the development package versions, which include header files and
libraries, to build Kea from the source code.
</simpara>
</note>
<para>
Building from source code requires the following software installed
on the system:</para>
<itemizedlist>
<listitem>
<para>Boost C++ Libraries
(<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/">http://www.boost.org/</uri>).
The oldest Boost version used for testing is 1.57 (although it may also work with
older versions). The Boost system library must also be installed. Installing
a header-only version of Boost is no longer recommended.
</para>
</listitem>
<listitem>
<para>
OpenSSL (at least version 1.0.1) or Botan (at least version 1.9).
Note that OpenSSL version 1.0.2 or 1.1.0 or later and Botan version 2
or later are strongly recommended.
</para>
</listitem>
<listitem>
<para>
log4cplus (at least version 1.0.3)
development include headers.
</para>
</listitem>
<!--
TODO
Debian and Ubuntu:
libgmp3-dev and libbz2-dev required for botan too
-->
<listitem>
<para>
A C++ compiler (with C++11 support) and standard development
headers. Kea building was checked with GCC g++ 4.8.5 and some later
versions and Clang 800.0.38 and some later versions.
</para>
</listitem>
<listitem>
<para>
The development tools automake, libtool, pkg-config.
</para>
</listitem>
<listitem>
<para>
The MySQL client and the client development libraries, when using
the --with-mysql configuration flag to build the Kea MySQL
database backend. In this case, an instance of the MySQL server
running locally or on a machine reachable over a network
is required. Note that
running the unit tests requires a local MySQL server.
</para>
</listitem>
<listitem>
<para>
The PostgreSQL client and the client development libraries, when
using the --with-pgsql configuration flag to build the Kea
PostgreSQL database backend. In this case an instance of the
PostgreSQL server running locally or on some other machine,
reachable over the network from the machine running Kea, is
required. Note that running the unit tests requires a local
PostgreSQL server.
</para>
</listitem>
<listitem>
<para>
The cpp-driver from DataStax is needed when using the --with-cql
configuration flag to build Kea with the Cassandra database backend.
In this case, an instance of the Cassandra server running locally
or on some other machine, reachable over the network from the
machine running Kea, is required. Note that running the unit
tests requires a local Cassandra server.
</para>
</listitem>
<listitem>
<para>
The FreeRADIUS client library is required to connect to a RADIUS server.
(This is specified using the --with-freeradius configuration switch.)
</para>
</listitem>
<listitem>
<para>
Sysrepo (version 0.7.6 or later) and libyang (version 0.16-r2 or later)
are needed to connect to a Sysrepo database. (This is specified using
the --with-sysrepo switch when running "configure".)
</para>
</listitem>
<listitem>
<para>
googletest (version 1.8 or later), when using the --with-gtest configuration
option to build the unit tests.
</para>
</listitem>
<listitem>
<para>
The documentation generation tools elinks, docbook-xsl, libxslt, and Doxygen,
if using the --enable-generate-docs configuration option
to create the documentation.
</para>
</listitem>
</itemizedlist>
<para>
Visit ISC's Knowledgebase at
<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://kb.isc.org/docs/installing-kea">https://kb.isc.org/docs/installing-kea</uri>
for system-specific installation tips.
</para>
</section>
<section xml:id="install">
<title>Installation from Source</title>
<para>
Although Kea may be available in pre-compiled, ready-to-use packages from operating system vendors, it is open source software written in C++. As such, it is freely available in
source code form from ISC as a downloadable tar file. The source code can also be obtained from the
Kea Gitlab repository at (<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gitlab.isc.org/isc-projects/kea">https://gitlab.isc.org/isc-projects/kea</uri>).
This section describes how to build Kea from the source code.
</para>
<section>
<title>Download Tar File</title>
<para>
The Kea release tarballs may be downloaded from:
<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://ftp.isc.org/isc/kea/">http://ftp.isc.org/isc/kea/</uri> (using FTP or HTTP).
</para>
</section>
<section>
<title>Retrieve from Git</title>
<para>
Downloading this "bleeding edge" code is recommended only for
developers or advanced users. Using development code in a production
environment is not recommended.
</para>
<note>
<para>
When building from source code retrieved via Git, additional
software will be required: automake (v1.11 or later),
libtoolize, and autoconf (v2.69 or later).
These may need to be installed.
</para>
</note>
<para>
The latest development code is available on Gitlab (see
<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gitlab.isc.org/isc-projects/kea">https://gitlab.isc.org/isc-projects/kea</uri>). The Kea source
is public and development is done in the <quote>master</quote>
branch.
</para>
<para>
The code can be checked out from
<filename>https://gitlab.isc.org/isc-projects/kea.git</filename>:
<screen>$ <userinput>git clone https://gitlab.isc.org/isc-projects/kea.git</userinput></screen>
</para>
<para>
The code checked out from the git repository does not include the
generated configure script, Makefile.in files, nor their
related build files.
They can be created by running <command>autoreconf</command>
with the <option>--install</option> switch.
This will run <command>autoconf</command>,
<command>aclocal</command>,
<command>libtoolize</command>,
<command>autoheader</command>,
<command>automake</command>,
and related commands.
</para>
<para>
Write access to the Kea repository is only granted to ISC staff. If you
are a developer planning to contribute to Kea, please check our
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gitlab.isc.org/isc-projects/kea/wikis/contributor's-guide">Contributor's Guide</link>. The
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Kea_doc/doxygen/">Kea Developer's Guide</link> contains more information about the process, as
well as describes the requirements for contributed code to be accepted by ISC.
</para>
</section>
<section xml:id="configure">
<title>Configure Before the Build</title>
<para>
Kea uses the GNU Build System to discover build environment
details.
To generate the makefiles using the defaults, simply run:
<screen>$ <userinput>./configure</userinput></screen>
</para>
<para>
Run <command>./configure</command> with the <option>--help</option>
switch to view the different options. Some commonly-used options are:
<variablelist>
<varlistentry>
<term>--prefix</term>
<listitem>
<simpara>Define the installation location (the
default is <filename>/usr/local</filename>).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-mysql</term>
<listitem>
<simpara>
Build Kea with code to allow it to store leases and
host reservations in a MySQL database.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-pgsql</term>
<listitem>
<simpara>
Build Kea with code to allow it to store leases and
host reservations in a PostgreSQL database.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-cql</term>
<listitem>
<simpara>
Build Kea with code to allow it to store leases and
host reservations in a Cassandra (CQL) database.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-log4cplus</term>
<listitem>
<simpara>Define the path to find the Log4cplus headers
and libraries. Normally this is not necessary.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-boost-include</term>
<listitem>
<simpara>Define the path to find the Boost headers. Normally this is not necessary.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-botan-config</term>
<listitem>
<simpara>Specify the path to the botan-config
script to build with Botan for cryptographic functions. It is prefered to use OpenSSL (see below).
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-openssl</term>
<listitem>
<simpara>Replace Botan by the OpenSSL the cryptographic library.
By default <command>configure</command> searches for a valid
Botan installation. If one is not found, it searches for OpenSSL.
Normally this is not necessary.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-shell</term>
<listitem>
<simpara>Build the optional <command>kea-shell</command> tool
(more in <xref linkend="kea-shell"/>). The default is to not
build it.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-perfdhcp</term>
<listitem>
<simpara>Build the optional <command>perfdhcp</command> DHCP
benchmarking tool. The default is to not build it.
</simpara>
</listitem>
</varlistentry>
</variablelist>
<note>
<para>
The <option>--runstatedir</option> in the installation
directories is particular: there are three cases:
<orderedlist>
<listitem>
<simpara>You use autoconf 2.70 or greater which supports
this but this autoconf version has not been currently
released.
</simpara>
</listitem>
<listitem>
<simpara>You use autoconf 2.69 patched to add support of
this. In this case and the previous simply use when needed
the <option>--runstatedir</option> configure parameter.
</simpara>
</listitem>
<listitem>
<simpara>There is no support (the configure parameter is
not recognized and configure directly raises an error).
For autoconf 2.69 the <option>runstatedir</option>
environment variable is supported so simply remove the
<command>--</command> before <option>runstatedir</option>
in the configure script call.
</simpara>
</listitem>
</orderedlist>
</para>
</note>
<note>
<para>
For instructions concerning the installation and configuration
of database backends for Kea, see <xref linkend="dhcp-install-configure"/>.
</para>
</note>
</para>
<!-- TODO: lcov -->
<para>
There are also many additional options that are typically not used by
regular users. However, they may be useful for package maintainers,
developers or people who want to extend Kea code or send patches:
<variablelist>
<varlistentry>
<term>--with-gtest, --with-gtest-source</term>
<listitem>
<simpara>Enable the building of the C++ Unit Tests using the
Google Test framework. This option specifies the path to the
gtest source. (If the framework
is not installed on your system, it can be downloaded
from <ulink url="https://github.com/google/googletest"/>.)
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-generate-docs</term>
<listitem>
<simpara>Enable the rebuilding Kea documentation. ISC publishes
Kea documentation for each release. However, in some cases you
may want to rebuild it. For example, if you want to change
something in the docs, or want to generate new one from git
sources that are not released yet.
The build procedure uses the xsltproc tool with the
nonet argument which disables fetching missing sources, e.g
docbook.xsl, from the Internet. If you want anyway to use
the Internet please set the XSLTPROC_NET environment variable
in configure to any non-empty value, e.g.
<screen>$ <replaceable>./configure XSLTPROC_NET=yes --enable-generate-docs</replaceable></screen>
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-generate-parser</term>
<listitem>
<simpara>Many Kea components have parsers implemented using flex
(.ll files) and bison (.yy files). Kea sources have C++/h files
generated out from them. By default Kea does not use flex or
bison to avoid requiring installation of unnecessary
dependencies for users. However, if you change anything in the
parses (such as add new parameter), you will need to use flex
and bison to regenerate parsers. This option lets you do that.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--enable-generate-messages</term>
<listitem>
<simpara>Enable the regeneration of messages files from
their messages source files, e.g. regenerate xxx_messages.h
and xxx_messages.cc from xxx_messages.mes using the Kea
message compiler. By default Kea is built using these .h
and .cc files from the distribution. However, if you change
anything in a .mes file (such as add new message), you will
need to build and use the Kea message compiler. This option
lets you do that.
</simpara>
</listitem>
</varlistentry>
<varlistentry>
<term>--with-benchmark, --with-benchmark-source</term>
<listitem>
<simpara>Enable the building of the database backend
benchmarks using the Google Benchmark framework. This
option specifies the path to the gtest source. (If the
framework is not installed on your system, it can be downloaded
from <ulink url="https://github.com/google/benchmark"/>.)
This support is experimental.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
For example, the following command configures Kea to find the
Boost headers in /usr/pkg/include, specifies that PostgreSQL
support should be enabled, and sets the installation location
to /opt/kea:
<screen>$ <userinput>./configure \
--with-boost-include=/usr/pkg/include \
--with-pgsql=/usr/local/bin/pg_config \
--prefix=/opt/kea</userinput></screen>
</para>
<para>
If you have any problems with building Kea using the header-only
Boost code, or you'd like to use the Boost system library
(assumed for the sake of this example to be located in /usr/pkg/lib):
<screen>$ <userinput>./configure \
--with-boost-libs=-lboost_system \
--with-boost-lib-dir=/usr/pkg/lib</userinput></screen>
</para>
<para>
If <command>configure</command> fails, it may be due to missing or old
dependencies.
</para>
<para>
If <command>configure</command> succeeds, it displays a report
with the parameters used to build the code. This report is saved into
the file <filename>config.report</filename> and is also embedded into
the executable binaries, e.g., <userinput>kea-dhcp4</userinput>.
</para>
</section>
<section>
<title>Build</title>
<para>
After the configure step is complete, build the executables
from the C++ code and prepare the Python scripts by running the command:
<screen>$ <userinput>make</userinput></screen>
</para>
</section>
<section>
<title>Install</title>
<para>
To install the Kea executables, support files,
and documentation, issue the command:
<screen>$ <userinput>make install</userinput></screen>
</para>
<para>
Do not use any form of parallel or job server options
(such as GNU make's <command>-j</command> option) when
performing this step; doing so may cause errors.
</para>
<note>
<para>The install step may require superuser privileges.</para>
</note>
<para>
If required, run <command>ldconfig</command> as root with
<filename>/usr/local/lib</filename> (or with <replaceable>prefix</replaceable>/lib if
configured with --prefix) in
<filename>/etc/ld.so.conf</filename> (or the relevant linker
cache configuration file for your OS):
<screen>$ <userinput>ldconfig</userinput></screen>
</para>
<note>
<para>
If you do not run <command>ldconfig</command> where it is
required, you may see errors like the following:
<screen>
program: error while loading shared libraries: libkea-something.so.1:
cannot open shared object file: No such file or directory
</screen>
</para>
</note>
</section>
<!-- @todo: tests -->
</section>
<section xml:id="dhcp-install-configure">
<title>DHCP Database Installation and Configuration</title>
<para>
Kea stores its leases in a lease database. The software has been
written in a way that makes it possible to choose which database product
should be used to store the lease information. At present, Kea supports
four database backends: MySQL, PostgreSQL, Cassandra, and Memfile. To
limit external dependencies, MySQL, PostgreSQL, and Cassandra support are
disabled by default and only Memfile is available. Support for the
optional external database backend must be explicitly included when Kea
is built. This section covers the building of Kea with one of the
optional backends and the creation of the lease database.
</para>
<note>
<simpara>
When unit tests are built with Kea (the --with-gtest configuration option is specified),
the databases must be manually pre-configured for the unit tests to run.
The details of this configuration can be found in the
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Kea_doc/doxygen/">Kea Developer's Guide</link>.
</simpara>
</note>
<section>
<title>Building with MySQL Support</title>
<para>
Install MySQL according to the instructions for your system. The client development
libraries must be installed.
</para>
<para>
Build and install Kea as described in <xref linkend="installation"/>, with
the following modification. To enable the MySQL database code, at the
"configure" step (see <xref linkend="configure"/>), the --with-mysql switch
should be specified:
<screen><userinput>./configure [other-options] --with-mysql</userinput></screen>
If MySQL was not installed in the default location, the location of the MySQL
configuration program "mysql_config" should be included with the switch, i.e.
<screen><userinput>./configure [other-options] --with-mysql=<replaceable>path-to-mysql_config</replaceable></userinput></screen>
</para>
<para>
See <xref linkend="mysql-database-create"/> for details regarding
MySQL database configuration.
</para>
</section>
<section>
<title>Building with PostgreSQL support</title>
<para>
Install PostgreSQL according to the instructions for your system. The client development
libraries must be installed. Client development libraries are often packaged as "libpq".
</para>
<para>
Build and install Kea as described in <xref linkend="installation"/>, with
the following modification. To enable the PostgreSQL database code, at the
"configure" step (see <xref linkend="configure"/>), the --with-pgsql switch
should be specified:
<screen><userinput>./configure [other-options] --with-pgsql</userinput></screen>
If PostgreSQL was not installed in the default location, the location of the PostgreSQL
configuration program "pg_config" should be included with the switch, i.e.
<screen><userinput>./configure [other-options] --with-pgsql=<replaceable>path-to-pg_config</replaceable></userinput></screen>
</para>
<para>
See <xref linkend="pgsql-database-create"/> for details regarding
PostgreSQL database configuration.
</para>
</section>
<section>
<title>Building with CQL (Cassandra) Support</title>
<para>
Install Cassandra according to the instructions for your system. The
Cassandra project website contains useful pointers: <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://cassandra.apache.org">http://cassandra.apache.org</uri>.
</para>
<para>
If you have a cpp-driver package available as binary or as source,
simply install or build and install the package. Then build
and install Kea as described in <xref linkend="installation"/>.
To enable the Cassandra (CQL) database code, at the "configure"
step (see <xref linkend="configure"/>), do:
<screen><userinput>./configure [other-options] --with-cql=<replaceable>path-to-pkg-config</replaceable></userinput></screen>
Note if <command>pkg-config</command> is at its standard location
(and thus in the shell path) you do not need to supply its path.
If it does not work (e.g. no pkg-config, package not available in
pkg-config with the cassandra name), you can still use
the <command>cql_config</command> script in tools/ as described below.
</para>
<para>
Download and compile cpp-driver from DataStax. For details regarding
dependencies for building cpp-driver, see the project homepage
<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://github.com/datastax/cpp-driver">https://github.com/datastax/cpp-driver</uri>. In June
2016, the following commands were used:
<screen>
$ <userinput>git clone https://github.com/datastax/cpp-driver</userinput>
$ <userinput>cd cpp-driver</userinput>
$ <userinput>mkdir build</userinput>
$ <userinput>cd build</userinput>
$ <userinput>cmake ..</userinput>
$ <userinput>make</userinput>
</screen>
</para>
<para>
As of January 2019, cpp-driver does not include cql_config script.
Work is in progress to contribute such a script to the cpp-driver
project but, until that is complete, intermediate steps need to
be conducted. A cql_config script is present in the tools/ directory
of the Kea sources. Before using it, please create a
cql_config_defines.sh in the same directory (there is an example in
cql_config_define.sh.sample available; you may copy it over to
cql_config_defines.sh and edit the path specified in it) and change the
environment variable CPP_DRIVER_PATH to point to the directory where the
cpp-driver sources are located. Make sure that appropriate access
rights are set on this file. It should be executable by the system
user building Kea.
</para>
<para>
Build and install Kea as described in <xref linkend="installation"/>, with
the following modification. To enable the Cassandra (CQL) database code, at the
"configure" step (see <xref linkend="configure"/>), do:
<screen><userinput>./configure [other-options] --with-cql=<replaceable>path-to-cql_config</replaceable></userinput></screen>
</para>
</section>
</section>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hammer.xml"/>
</chapter>

242
doc/guide/intro.xml
View File

@ -1,242 +0,0 @@
<!--
- Copyright (C) 2014-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- need this include to make the &keaversion; macro work -->
<!DOCTYPE book [
<!ENTITY % keaversion SYSTEM "version.ent">
%keaversion;
]>
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="intro">
<title>Introduction</title>
<para>
Kea is the next generation of DHCP software developed by ISC.
It supports both DHCPv4 and DHCPv6 protocols along with their
extensions, e.g. prefix delegation and dynamic updates to DNS.
</para>
<para>
This guide covers Kea version &keaversion;.
</para>
<section>
<title>Supported Platforms</title>
<para>
Kea is officially supported on CentOS, Fedora, Ubuntu, Debian, and FreeBSD systems.
It is also likely to work on many other platforms. Kea-&keaversion; builds have been tested on:
<itemizedlist>
<listitem>CentOS Linux — 7.1804 (aka 7.5)</listitem>
<listitem>Fedora — 28, 29</listitem>
<listitem>Ubuntu — 16.04, 18.04</listitem>
<listitem>Debian GNU/Linux — 8, 9</listitem>
<listitem>FreeBSD — 11.0</listitem>
<listitem>macOS — 10.13, 10.14</listitem>
</itemizedlist>
</para>
<para>There are currently no plans to port Kea to Windows platforms.</para>
</section>
<section xml:id="required-software">
<title>Required Software at Run-time</title>
<para>
Running Kea uses various extra software packages which may
not be provided in the default installation of some operating systems,
nor in the standard package collections. You may
need to install this required software separately.
(For the build requirements, also see
<xref linkend="build-requirements"/>.)
</para>
<itemizedlist>
<listitem>
<simpara>
Kea supports two cryptographic libraries: Botan and OpenSSL. Only one of them
is required to be installed during compilation. Kea uses the Botan
library for C++ (<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://botan.randombit.net/">http://botan.randombit.net/</uri>),
version 1.9 or later. Note that support for Botan versions earlier than 2.0 will be removed in Kea 1.6.0 and later. As an alternative to Botan, Kea can use the
OpenSSL cryptographic library (<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.openssl.org/">http://www.openssl.org/</uri>),
version 1.0.2 or later.
</simpara>
</listitem>
<listitem>
<simpara>
Kea uses the log4cplus C++ logging library
(<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://log4cplus.sourceforge.net/">http://log4cplus.sourceforge.net/</uri>).
It requires log4cplus version 1.0.3 or later.
</simpara>
</listitem>
<listitem>
<simpara>
Kea requires the Boost system library (<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/">http://www.boost.org/</uri>). Building with the header-only version of Boost is no longer recommended.
</simpara>
</listitem>
<listitem>
<simpara>
In order to store lease information in a MySQL database, Kea requires MySQL
headers and libraries. This is an optional dependency in that Kea can be
built without MySQL support.
</simpara>
</listitem>
<listitem>
<simpara>
In order to store lease information in a PostgreSQL database, Kea requires PostgreSQL
headers and libraries. This is an optional dependency in that Kea can be
built without PostgreSQL support.
</simpara>
</listitem>
<listitem>
<simpara>
In order to store lease information in a Cassandra database (CQL), Kea
requires Cassandra headers and libraries. This is an optional dependency
in that Kea can be built without Cassandra support.
</simpara>
</listitem>
<listitem>
<simpara>
Integration with RADIUS is provided in Kea via the hooks
library available to our paid support customers. Use of this library requires
the FreeRadius-client library to be present on the system where Kea is running.
This is an optional dependency in that Kea can be built without RADIUS support.
</simpara>
</listitem>
<listitem>
<simpara>
As of the 1.5.0 release, Kea provides a NETCONF interface with the kea-netconf agent.
This Kea module is built optionally and requires Sysrepo software when used.
Building Kea with NETCONF support requires many dependencies to be installed,
which are described in more detail in <xref linkend="netconf-install"/>.
</simpara>
</listitem>
</itemizedlist>
</section>
<section xml:id="kea_software">
<title>Kea Software</title>
<para>
Kea is modular. Part of this modularity is
accomplished using multiple cooperating processes which, together,
provide the server functionality.
The following software is included with Kea:
</para>
<para>
<itemizedlist>
<listitem>
<simpara>
<command>keactrl</command> —
Tool to start, stop, reconfigure, and report status
for the Kea servers.
</simpara>
</listitem>
<listitem>
<simpara>
<command>kea-dhcp4</command> —
The DHCPv4 server process.
This process responds to DHCPv4 queries from clients.
</simpara>
</listitem>
<listitem>
<simpara>
<command>kea-dhcp6</command> —
The DHCPv6 server process.
This process responds to DHCPv6 queries from clients.
</simpara>
</listitem>
<listitem>
<simpara>
<command>kea-dhcp-ddns</command> —
The DHCP Dynamic DNS process.
This process acts as an intermediary between the DHCP servers
and DNS servers. It receives name update requests from the DHCP
servers and sends DNS update messages to the DNS servers.
</simpara>
</listitem>
<listitem>
<simpara>
<command>kea-admin</command> —
A useful tool for database backend maintenance (creating a new
database, checking versions, upgrading, etc.)
</simpara>
</listitem>
<listitem>
<simpara>
<command>kea-lfc</command> —
This process removes redundant information from the files used
to provide persistent storage for the memfile database backend.
While it can be run standalone, it is normally run as and when
required by the Kea DHCP servers.
</simpara>
</listitem>
<listitem>
<simpara>
<command>kea-ctrl-agent</command> —
Kea Control Agent (CA) is a daemon that exposes a RESTful control
interface for managing Kea servers.
</simpara>
</listitem>
<listitem>
<simpara>
<command>kea-netconf</command> -
Kea netconf is an agent that provides a YANG/NETCONF interface
for the Kea environment.
</simpara>
</listitem>
<listitem>
<simpara>
<command>kea-shell</command> —
This simple text client uses the REST interface to connect to the Kea
Control Agent.
</simpara>
</listitem>
<listitem>
<simpara>
<command>perfdhcp</command> —
A DHCP benchmarking tool which simulates multiple clients to
test both DHCPv4 and DHCPv6 server performance.
</simpara>
</listitem>
</itemizedlist>
</para>
</section>
<para>
The tools and modules are covered in full detail in this guide.
<!-- TODO point to these -->
In addition, manual pages are also provided in the default installation.
</para>
<para>
Kea also provides C++ libraries and programmer interfaces for
DHCP. These include detailed developer documentation and
code examples.
<!-- TODO point to this -->
</para>
</chapter>

49
doc/guide/kea-guide.css
View File

@ -1,49 +0,0 @@
body {
background-color: #ffffff;
color: #333333;
font-family: "ArialMT", "Verdana", "Arial", "Helvetica", sans-serif;
font-size: 14px;
line-height: 18px;
margin: 2em;
}
.command {
font-family: "Courier New", "Courier", monospace;
font-weight: normal;
}
.note {
background-color: #ddeedd;
border: 1px solid #aaccaa;
margin: 1em 0 1em 0;
padding: 0.5em 1em 0.5em 1em;
-moz-border-radius: 10px;
-webkit-border-radius: 10px;
}
.screen {
background-color: #ffffee;
border: 1px solid #ddddaa;
padding: 0.25em 1em 0.25em 1em;
margin: 1em 0 1em 0;
-moz-border-radius: 10px;
-webkit-border-radius: 10px;
}
.warning {
background-color: #eedddd;
border: 1px solid #ccaaaa;
margin: 1em 0 1em 0;
padding: 0.5em 1em 0.5em 1em;
-moz-border-radius: 10px;
-webkit-border-radius: 10px;
}
h3 {
text-decoration: underline;
}
h4 {
text-decoration: underline;
font-weight: normal;
}

145
doc/guide/kea-guide.xml
View File

@ -1,145 +0,0 @@
<?xml version="1.0"?>
<!--
- Copyright (C) 2014-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- need this include to make the &keaversion; macro work -->
<!DOCTYPE book [
<!ENTITY % keaversion SYSTEM "version.ent">
%keaversion;
]>
<!-- Converted by db4-upgrade version 1.1 -->
<book xmlns="http://docbook.org/ns/docbook" version="5.0">
<?xml-stylesheet href="kea-guide.css" type="text/css"?>
<info>
<title>
<inlinemediaobject>
<imageobject>
<imagedata fileref="kea-logo-100x70.png" align="left"/>
</imageobject>
</inlinemediaobject>
Kea Administrator Reference Manual
</title>
<releaseinfo>This is the reference guide for Kea version &keaversion;.</releaseinfo>
<copyright>
<year>2010-2019</year>
<holder>Internet Systems Consortium, Inc. ("ISC")</holder>
</copyright>
<abstract>
<para>
Kea is an open source implementation of the Dynamic Host Configuration
Protocol (DHCP) servers, developed and maintained by Internet Systems
Consortium (ISC).
</para>
<para>
This is the reference guide for Kea version &keaversion;.
Links to the most up-to-date version of this document (in PDF, HTML,
and plain text formats), along with other documents for
Kea, can be found in ISC's <uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://kb.isc.org/docs/kea-administrator-reference-manual">Knowledgebase</uri>.
</para> </abstract>
</info>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="intro.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="quickstart.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="install.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="admin.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="config.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="keactrl.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="agent.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp4-srv.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="dhcp6-srv.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lease-expiration.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="congestion-handling.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ddns.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lfc.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="classify.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="hooks.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stats.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="ctrl-channel.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="logging.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="shell.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="netconf.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="api.xml"/>
<appendix xml:id="acknowledgments">
<title>Acknowledgments</title>
<para>Kea is an open source project designed, developed, and maintained by Internet Systems
Consortium, Inc, a 501(c)3 non-profit organization. ISC is primarily funded by revenues from
support subscriptions for our open source, and we encourage all professional users to consider
this option. To learn more, see ​<ulink
url="https://www.isc.org/support/">https://www.isc.org/support/</ulink>.</para>
<para>If you would like to contribute to ISC to assist us in continuing to make quality open
source software, please visit our donations page at ​<ulink
url="https://www.isc.org/donate/">https://www.isc.org/donate/</ulink>.</para>
<para>We thank all the organizations and individuals who have helped to make Kea
possible. <link xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="http://www.comcast.com/">Comcast</link>
and the Comcast Innovation Fund provided major support for the development
of Kea's DHCPv4, DHCPv6, and DDNS modules. Mozilla funded initial work on the REST API via a
MOSS award.</para>
<para>Kea was initially implemented as a collection of applications
within the BIND 10 framework. We thank the founding sponsors of the BIND 10 project:
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.afilias.info/">Afilias</link>,
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.iis.se/">IIS.SE</link>,
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.nominet.org.uk/">Nominet</link>,
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.sidn.nl/">SIDN</link>,
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://jprs.co.jp/">JPRS</link>,
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://cira.ca/">CIRA</link>; and additional sponsors
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.afnic.fr/">AFNIC</link>,
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.cnnic.net.cn/">CNNIC</link>,
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.nic.cz/">CZ.NIC</link>,
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.denic.de/">DENIC eG</link>,
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.google.com/">Google</link>,
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.ripe.net/">RIPE NCC</link>,
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://registro.br/">Registro.br</link>,
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://nzrs.net.nz/">.nz Registry Services</link>, and
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.tcinet.ru/">Technical Center of Internet</link>
.</para>
</appendix>
<!-- TODO: Add bibliography section (mostly RFCs, probably) -->
<!-- TODO: how to help: run unit tests, join lists, review trac tickets -->
<!-- <index> <title>Index</title> </index> -->
</book>

381
doc/guide/keactrl.xml
View File

@ -1,381 +0,0 @@
<!--
- Copyright (C) 2014-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="keactrl">
<title>Managing Kea with keactrl</title>
<section xml:id="keactrl-overview">
<title>Overview</title>
<para>keactrl is a shell script which controls the startup, shutdown,
and reconfiguration of the Kea servers (<command>kea-dhcp4</command>,
<command>kea-dhcp6</command>, <command>kea-dhcp-ddns</command>,
<command>kea-ctrl-agent</command>, and
<command>kea-netconf</command>). It also provides the means for
checking the current status of the servers and determining the
configuration files in use.
</para>
</section>
<section xml:id="keactrl-usage">
<title>Command Line Options</title>
<para><command>keactrl</command> is run as follows:
<screen>
keactrl &lt;command&gt; [-c keactrl-config-file] [-s server[,server,...]]
</screen>
</para>
<para>
<command>&lt;command&gt;</command> is the one of the commands
described in <xref linkend="keactrl-commands"/>.
</para>
<para>
The optional <command>-c keactrl-config-file</command> switch
allows specification of an alternate <command>keactrl</command>
configuration file. (<command>--ctrl-config</command> is a synonym for
<command>-c</command>.) In the absence of <command>-c</command>,
<command>keactrl</command> will use the default configuration
file <filename>[kea-install-dir]/etc/kea/keactrl.conf</filename>.
</para>
<para>
The optional <command>-s server[,server,...]</command> switch selects
the servers to which the command is issued.
(<command>--server</command> is a synonym for <command>-s</command>.)
If absent, the command is sent to all servers enabled in the keactrl
configuration file.
If multiple servers are specified, they
should be separated by commas with no intervening spaces.
</para>
</section>
<section xml:id="keactrl-config-file">
<title>The keactrl Configuration File</title>
<para>
Depending on requirements, not all of the available servers need
to be run. The keactrl configuration file sets which servers are
enabled and which are disabled. The default configuration
file is <filename>[kea-install-dir]/etc/kea/keactrl.conf</filename>,
but this can be overridden on a per-command basis using the
<command>-c</command> switch.
</para>
<para>
The contents of <filename>keactrl.conf</filename> are:
<screen>
# This is a configuration file for keactrl script which controls
# the startup, shutdown, reconfiguration and gathering the status
# of the Kea's processes.
# prefix holds the location where the Kea is installed.
prefix=@prefix@
# Location of Kea configuration file.
kea_dhcp4_config_file=@sysconfdir@/@PACKAGE@/kea-dhcp4.conf
kea_dhcp6_config_file=@sysconfdir@/@PACKAGE@/kea-dhcp6.conf
kea_dhcp_ddns_config_file=@sysconfdir@/@PACKAGE@/kea-dhcp-ddns.conf
kea_ctrl_agent_config_file=@sysconfdir@/@PACKAGE@/kea-ctrl-agent.conf
kea_netconf_config_file=@sysconfdir@/@PACKAGE@/kea-netconf.conf
# Location of Kea binaries.
exec_prefix=@exec_prefix@
dhcp4_srv=@sbindir@/kea-dhcp4
dhcp6_srv=@sbindir@/kea-dhcp6
dhcp_ddns_srv=@sbindir@/kea-dhcp-ddns
ctrl_agent_srv=@sbindir@/kea-ctrl-agent
netconf_srv=@sbindir@/kea-netconf
# Start DHCPv4 server?
dhcp4=yes
# Start DHCPv6 server?
dhcp6=yes
# Start DHCP DDNS server?
dhcp_ddns=no
# Start Control Agent?
ctrl_agent=yes
# Start Netconf?
netconf=no
# Be verbose?
kea_verbose=no
</screen>
</para>
<note>
<para>
In the example above, strings of the form @something@ are replaced by the
appropriate values when Kea is installed.
</para>
</note>
<para>
The <parameter>dhcp4</parameter>, <parameter>dhcp6</parameter>,
<parameter>dhcp_ddns</parameter>, <parameter>ctrl_agent</parameter>,
and <parameter>netconf</parameter>
parameters set to "yes" will configure <command>keactrl</command> to manage
(start, reconfigure) all servers, i.e. <command>kea-dhcp4</command>,
<command>kea-dhcp6</command>, <command>kea-dhcp-ddns</command>,
<command>kea-ctrl-agent</command>, and <command>kea-netconf</command>.
When any of these parameters is set
to "no," the <command>keactrl</command> will ignore
the corresponding server when starting or reconfiguring Kea. Some
daemons (ddns and netconf) are disabled by default.
</para>
<para>
By default, Kea servers managed by <command>keactrl</command> are
located in <filename>[kea-install-dir]/sbin</filename>. This
should work for most installations. If the default
location needs to be altered for any reason, the paths
specified with the <parameter>dhcp4_srv</parameter>,
<parameter>dhcp6_srv</parameter>, <parameter>dhcp_ddns_srv</parameter>
<parameter>ctrl_agent_srv</parameter>, and <parameter>netconf_srv</parameter>
parameters should be modified.
</para>
<para>
The <parameter>kea_verbose</parameter> parameter specifies the verbosity
of the servers being started. When <parameter>kea_verbose</parameter>
is set to "yes" the logging level of the server is set to DEBUG.
Modification of the logging severity in a configuration file, as
described in <xref linkend="logging"/>, will have no effect as long
as the <parameter>kea_verbose</parameter> is set to "yes." Setting
it to "no" will cause the server to use the logging levels specified
in the Kea configuration file. If no
logging configuration is specified, the default settings will be
used.
</para>
<note>
<para>
The verbosity for the server is set when it is started. Once
started, the verbosity can be only changed by stopping the server and
starting it again with the new value of the
<parameter>kea_verbose</parameter> parameter.
</para>
</note>
</section>
<section xml:id="keactrl-commands">
<title>Commands</title>
<para>The following commands are supported by <command>keactrl</command>:
<itemizedlist>
<listitem><simpara>
<command>start</command> - starts selected servers.
</simpara></listitem>
<listitem><simpara>
<command>stop</command> - stops all running servers.
</simpara></listitem>
<listitem><simpara>
<command>reload</command> - triggers reconfiguration of the
selected servers by sending the SIGHUP signal to them.
</simpara></listitem>
<listitem><simpara>
<command>status</command> - returns the status of the servers (active
or inactive) and the names of the configuration files in use.
</simpara></listitem>
<listitem><simpara>
<command>version</command> - prints out the version of the
keactrl tool itself, together with the versions of the Kea daemons.
</simpara></listitem>
</itemizedlist>
</para>
<para>Typical output from <command>keactrl</command> when starting
the servers looks similar to the following:
<screen>
<userinput>$ keactrl start</userinput>
INFO/keactrl: Starting kea-dhcp4 -c /usr/local/etc/kea/kea-dhcp4.conf -d
INFO/keactrl: Starting kea-dhcp6 -c /usr/local/etc/kea/kea-dhcp6.conf -d
INFO/keactrl: Starting kea-dhcp-ddns -c /usr/local/etc/kea/kea-dhcp-ddns.conf -d
INFO/keactrl: Starting kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf -d
INFO/keactrl: Starting kea-netconf -c /usr/local/etc/kea/kea-netconf.conf -d
</screen>
</para>
<para>Kea's servers create PID files upon startup. These files are used
by keactrl to determine whether a given server is running. If
one or more servers are running when the start command is issued, the
output will look similar to the following:
<screen>
<userinput>$ keactrl start</userinput>
INFO/keactrl: kea-dhcp4 appears to be running, see: PID 10918, PID file: /usr/local/var/run/kea/kea.kea-dhcp4.pid.
INFO/keactrl: kea-dhcp6 appears to be running, see: PID 10924, PID file: /usr/local/var/run/kea/kea.kea-dhcp6.pid.
INFO/keactrl: kea-dhcp-ddns appears to be running, see: PID 10930, PID file: /usr/local/var/run/kea/kea.kea-dhcp-ddns.pid.
INFO/keactrl: kea-ctrl-agent appears to be running, see: PID 10931, PID file: /usr/local/var/run/kea/kea.kea-ctrl-agent.pid.
INFO/keactrl: kea-netconf appears to be running, see: PID 10123, PID file: /usr/local/var/run/kea/kea.kea-netconf.pid.
</screen>
During normal shutdowns these PID files are deleted. They may, however,
be left over as remnants following a system crash. It is possible,
though highly unlikely, that upon system restart the PIDs they contain may
actually refer to processes unrelated to Kea. This condition will cause
keactrl to decide that the servers are running, when in fact they are
not. In such a case the PID files as listed in the keactrl output
must be manually deleted.
</para>
<para>The following command stops all servers:
<screen>
<userinput>$ keactrl stop</userinput>
INFO/keactrl: Stopping kea-dhcp4...
INFO/keactrl: Stopping kea-dhcp6...
INFO/keactrl: Stopping kea-dhcp-ddns...
INFO/keactrl: Stopping kea-ctrl-agent...
INFO/keactrl: Stopping kea-netconf...
</screen>
Note that the <command>stop</command> command will attempt to stop all servers
regardless of whether they are "enabled" in the <filename>keactrl.conf</filename>.
If any of the servers are not running, an informational message
is displayed as in the <command>stop</command> command output below.
<screen>
<userinput>$ keactrl stop</userinput>
INFO/keactrl: kea-dhcp4 isn't running.
INFO/keactrl: kea-dhcp6 isn't running.
INFO/keactrl: kea-dhcp-ddns isn't running.
INFO/keactrl: kea-ctrl-agent isn't running.
INFO/keactrl: kea-netconf isn't running.
</screen>
</para>
<para>
As already mentioned, the reconfiguration of each Kea server is
triggered by the SIGHUP signal. The <command>reload</command>
command sends the SIGHUP signal to the servers that are enabled in
the <command>keactrl</command> configuration file and are
currently running. When a server receives the SIGHUP signal it
re-reads its configuration file and, if the new configuration is
valid, uses the new configuration. A reload is executed as follows:
<screen>
<userinput>$ keactrl reload</userinput>
INFO/keactrl: Reloading kea-dhcp4...
INFO/keactrl: Reloading kea-dhcp6...
INFO/keactrl: Reloading kea-dhcp-ddns...
INFO/keactrl: Reloading kea-ctrl-agent...
</screen>
If any of the servers are not running, an informational message
is displayed as in the <command>reload</command> command output below.
Note that as of version 1.5.0, kea-netconf does not support the SIGHUP
signal. If its configuration has changed, please stop and restart it for
the change to take effect. This limitation will be removed in a future release.
<screen>
<userinput>$ keactrl stop</userinput>
INFO/keactrl: kea-dhcp4 isn't running.
INFO/keactrl: kea-dhcp6 isn't running.
INFO/keactrl: kea-dhcp-ddns isn't running.
INFO/keactrl: kea-ctrl-agent isn't running.
INFO/keactrl: kea-netconf isn't running.
</screen>
</para>
<note>
NETCONF is an optional feature that is disabled by default and can be
enabled during compilation. If Kea was compiled without NETCONF support,
keactrl will do its best to not bother the user with information about
it. The netconf entries will still be present in the keactrl.conf file,
but netconf status will not be shown and other commands will ignore it.
</note>
<note>
<para>
Currently <command>keactrl</command> does not report configuration
failures when the server is started or reconfigured. To check if
the server's configuration succeeded, the Kea log must be examined
for errors. By default, this is written to the syslog file.
</para>
</note>
<para>
Sometimes it is useful to check which servers are running. The
<command>status</command> reports this, with typical output that looks like:
<screen>
<userinput>$ keactrl status</userinput>
DHCPv4 server: active
DHCPv6 server: inactive
DHCP DDNS: active
Control Agent: active
Netconf agent: inactive
Kea configuration file: /usr/local/etc/kea/kea.conf
Kea DHCPv4 configuration file: /usr/local/etc/kea/kea-dhcp4.conf
Kea DHCPv6 configuration file: /usr/local/etc/kea/kea-dhcp6.conf
Kea DHCP DDNS configuration file: /usr/local/etc/kea/kea-dhcp-ddns.conf
Kea Control Agent configuration file: /usr/local/etc/kea/kea-ctrl-agent.conf
Kea Netconf configuration file: /usr/local/etc/kea/kea-netconf.conf
keactrl configuration file: /usr/local/etc/kea/keactrl.conf
</screen>
</para>
</section>
<section xml:id="keactrl-overriding-servers">
<title>Overriding the Server Selection</title>
<para>
The optional <command>-s</command> switch allows
the selection of the servers to which the <command>keactrl</command>
command is issued. For example, the following
instructs <command>keactrl</command> to stop the
<command>kea-dhcp4</command> and <command>kea-dhcp6</command> servers
and leave the <command>kea-dhcp-ddns</command> and
<command>kea-ctrl-agent</command> running:
<screen>
<userinput>$ keactrl stop -s dhcp4,dhcp6</userinput>
</screen>
</para>
<para>
Similarly, the following
will start only the <command>kea-dhcp4</command> and
<command>kea-dhcp-ddns</command> servers, but not
<command>kea-dhcp6</command> or <command>kea-ctrl-agent</command>.
<screen>
<userinput>$ keactrl start -s dhcp4,dhcp_ddns</userinput>
</screen>
</para>
<para>
Note that the behavior of the <command>-s</command> switch
with the <command>start</command> and <command>reload</command> commands
is different to its behavior with the <command>stop</command> command.
On <command>start</command> and <command>reload</command>,
<command>keactrl</command> will check if the servers given as
parameters to the <command>-s</command> switch are
enabled in the <command>keactrl</command> configuration file;
if not, the server will be ignored. For <command>stop</command>, however,
this check is not made; the command is applied to all listed servers,
regardless of whether they have been enabled in the file.
</para>
<para>
The following keywords can be used with the <command>-s</command>
command line option:
<itemizedlist>
<listitem><simpara>
<command>dhcp4</command> for <command>kea-dhcp4</command>.
</simpara></listitem>
<listitem><simpara>
<command>dhcp6</command> for <command>kea-dhcp6</command>.
</simpara></listitem>
<listitem><simpara>
<command>dhcp_ddns</command> for <command>kea-dhcp-ddns</command>.
</simpara></listitem>
<listitem><simpara>
<command>ctrl_agent</command> for <command>kea-ctrl-agent</command>.
</simpara></listitem>
<listitem><simpara>
<command>netconf</command> for <command>kea-netconf</command>.
</simpara></listitem>
<listitem><simpara>
<command>all</command> for all servers (default).
</simpara></listitem>
</itemizedlist>
</para>
</section>
</chapter>

377
doc/guide/lease-expiration.xml
View File

@ -1,377 +0,0 @@
<!--
- Copyright (C) 2015-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="lease-expiration">
<title>Lease Expiration in DHCPv4 and DHCPv6</title>
<para>The primary role of the DHCP server is to assign addresses and/or
delegate prefixes to DHCP clients. These addresses and prefixes are
often referred to as "leases." Leases are typically assigned to clients
for a finite amount of time, known as the "valid lifetime." DHCP clients who
wish to continue using their assigned leases will periodically renew them
by sending the appropriate message to the DHCP server. The DHCP server records
the time when these leases are renewed and calculates new expiration times
for them.
</para>
<para>If the client does not renew a lease before its valid lifetime
elapses, the lease is considered expired. There are many situations
when the client may cease lease renewals; a common scenario is when
the machine running the client shuts down for an extended period of
time.</para>
<para> The process through which the DHCP server makes expired leases
available for reassignment is referred to as "lease reclamation" and expired
leases returned to availability through this process are referred to as
"reclaimed."
The DHCP server attempts to reclaim an expired lease as soon as it detects
that it has expired. The server has several possible ways to detect expiration:
it may attempt to allocate a lease to a client but find this
lease already present in the database and expired; or it can
periodically query the lease
database for expired leases. Regardless of how an expired lease is detected, it must be
reclaimed before it can be assigned to a client.
</para>
<para>
This chapter explains how to configure the server to periodically query
for the expired leases, and how to minimize the impact of the periodic lease
reclamation process on the server's responsiveness. Finally, it explains
"lease affinity," which provides the means to assign the same lease to a
returning client after its lease has expired.
</para>
<para>Although all configuration examples in this section are provided
for the DHCPv4 server, the same parameters may be used for
DHCPv6 server configuration.
</para>
<section xml:id="lease-reclamation">
<title>Lease Reclamation</title>
<para>Lease reclamation is the process through which an expired lease
becomes available for assignment to the same or a different client.
This process involves the following steps for each reclaimed lease:
</para>
<itemizedlist>
<listitem>
<simpara>Invoke callouts for the <command>lease4_expire</command> or
<command>lease6_expire</command> hook points, if hook libraries
supporting those callouts are currently loaded.</simpara>
</listitem>
<listitem>
<simpara>Update the DNS, i.e. remove any DNS entries associated with
the expired lease.</simpara>
</listitem>
<listitem>
<simpara>Update lease information in the lease database to
indicate that the lease is now available for re-assignment.</simpara>
</listitem>
<listitem>
<simpara>Update counters on the server, a process that includes
increasing the number of reclaimed leases and decreasing the
number of assigned addresses or delegated prefixes.</simpara>
</listitem>
</itemizedlist>
<para>Please refer to <xref linkend="dhcp-ddns-server"/> to see
how to configure DNS updates in Kea, and to
<xref linkend="hooks-libraries"/> for information about using
hooks libraries.</para>
</section>
<section xml:id="lease-reclamation-defaults">
<title>Lease Reclamation Configuration Parameters</title>
<para>The following list presents all configuration parameters
pertaining to processing expired leases with their default values:</para>
<itemizedlist>
<listitem>
<simpara><command>reclaim-timer-wait-time</command> - This parameter
governs intervals between completion of previous reclaimation cycle
and a start of the next one. Specified in seconds. The default value
is 10 [seconds].</simpara>
</listitem>
<listitem>
<simpara><command>flush-reclaimed-timer-wait-time</command> - This
parameter controls how often the server initiates lease reclaimation
procedure. Expressed in seconds. The default value is 25 [seconds].</simpara>
</listitem>
<listitem>
<simpara><command>hold-reclaimed-time</command> - This parameter governs
how long the lease should be kept after it was reclaimed. This enables
lease affinity when set to a non-zero value. Expressed in seconds. The
default value is 3600 [seconds].</simpara>
</listitem>
<listitem>
<simpara><command>max-reclaim-leases</command> - This parameter
specifies the maximum number of reclaimed leases that can be processed
in one go. Zero means unlimited (i.e. process all reclaimed leases). The
default value is 100.</simpara>
</listitem>
<listitem>
<simpara><command>max-reclaim-time</command> - This parameter specifies
an upper bound of how long a lease reclaimation procedure can
take. Zero means no time limit. Expressed in milliseconds. The default
value is 250 [milliseconds].</simpara>
</listitem>
<listitem>
<simpara><command>unwarned-reclaim-cycles</command> - If lease
reclaimation limits are specifed (<command>max-reclaim-leases</command>
and/oor <command>max-reclaim-time</command>), then under certain
circumstances the server may not be able to deal with leases to be
reclaimed fast enough. This parameter specifies how many consecutive
clean up cycles must end with remaining leases to be processed before a
warning is printed. The default is 5 [cycles].
</simpara>
</listitem>
</itemizedlist>
<para>
The parameters are explained in more detail in the rest of this chapter.
</para>
<para>The default value for any parameter is used when this parameter is not
explicitly specified in the configuration. Also, the
<command>expired-leases-processing</command> map may be omitted entirely
in the configuration, in which case the default values are used for all
parameters listed above.</para>
</section>
<section xml:id="lease-reclaim-config">
<title>Configuring Lease Reclamation</title>
<para>Kea can be configured to periodically detect and reclaim expired
leases. During this process the lease entries in the database are
modified or removed. While this is happening, the server will not process incoming DHCP
messages to avoid issues with concurrent access to database information.
As a result, the server will be unresponsive while lease reclamation
is performed and DHCP queries will accumulate; responses will be
sent once the lease-reclamation cycle is complete.</para>
<para>In deployments where response time is critical, administrators may
wish to minimize the interruptions in service caused by lease reclamation.
Toward this end, Kea provides configuration parameters to control the
frequency of lease reclamation cycles, the maximum number of leases
processed in a single reclamation cycle, and the maximum amount of time a
single reclamation cycle is allowed to run before being interrupted. The
following examples demonstrate how these parameters can be used:
<screen>
"Dhcp4": {
...
"expired-leases-processing": {
"reclaim-timer-wait-time": 5,
"max-reclaim-leases": 0,
"max-reclaim-time": 0,
},
...
}
</screen>
</para>
<para>The first parameter is expressed in seconds and specifies an
interval between the two consecutive lease reclamation cycles. This
is explained by the following diagram:
<screen>
| c1 | | c2 | |c3| | c4 |
|&lt;----&gt;|&lt;----------&gt;|&lt;--&gt;|&lt;----------&gt;|&lt;&gt;|&lt;----------&gt;|&lt;--&gt;|
----------------------------------------------------------------&gt;
| | 5s | | 5s | | 5s | | time
</screen>
</para>
<para>This diagram shows four lease-reclamation cycles (c1 through c4) of variable duration.
Note that the duration of the reclamation cycle depends on the number
of expired leases detected and processed in the particular cycle. This
duration is usually significantly shorter than the interval between
the cycles.
</para>
<para>According to the <command>reclaim-timer-wait-time</command>, the
server keeps fixed intervals of five seconds between the end of one cycle
and the start of the next cycle. This guarantees the presence of
5s-long periods during which the server remains responsive to DHCP
queries and does not perform lease reclamation. The
<command>max-reclaim-leases</command> and
<command>max-reclaim-time</command> are set to 0, which sets
no restriction on the maximum number of leases reclaimed
in the particular cycle, or on the maximum duration of each cycle.
</para>
<para>In deployments with high lease-pool utilization, relatively
short valid lifetimes, and frequently disconnecting clients which
allow leases to expire, the number of expired leases requiring reclamation
at any given time may rise significantly. In this case, it is often
desirable to apply restrictions to the maximum duration of a reclamation
cycle or the maximum number of leases reclaimed in a cycle. The following
configuration demonstrates how this can be done:
<screen>
"Dhcp4": {
...
"expired-leases-processing": {
"reclaim-timer-wait-time": 3,
"max-reclaim-leases": 100,
"max-reclaim-time": 50,
"unwarned-reclaim-cycles": 10,
},
...
}</screen>
</para>
<para>The <command>max-reclaim-leases</command> parameter limits the number
of leases reclaimed in a single cycle to 100. The
<command>max-reclaim-time</command> limits the maximum duration of each
cycle to 50ms. The lease-reclamation cycle will be interrupted if either
of these limitations is reached. The reclamation of any unreclaimed
leases will be attempted in subsequent cycles.</para>
<para>The following diagram illustrates the behavior of the system in the
presence of many expired leases, when the limits are applied for the
reclamation cycles:
<screen>
| c1 | | c2 | | c3 | | c4 |
|&lt;--&gt;|&lt;--------------&gt;|&lt;--&gt;|&lt;--------------&gt;|&lt;--&gt;|&lt;--------------&gt;|&lt;--&gt;|&lt;--
------------------------------------------------------------------------------&gt;
|50ms| 3s |50ms| 3s |50ms| 3s |50ms| time
</screen>
</para>
<para>This diagram demonstrates the case when each reclamation cycle takes
more than 50ms, and thus is interrupted according to the value of the
<command>max-reclaim-time</command>. This results in equal durations of
all reclamation cycles over time. Note that in this example the limitation
of the maximum 100 leases is not reached. This may be the case when database
transactions are slow or callouts in the hook libraries attached to
the server are slow. Regardless, the chosen values for either the
maximum number of leases or a maximum cycle time strongly depend on the
particular deployment, the lease database backend being used, and any hooks
libraries, etc. Administrators may need to experiment to tune the system
to suit the dynamics of their deployment.</para>
<para>It is important to realize that with the use of these limits, there
is a risk that expired leases will accumulate faster than the server can
reclaim them. This should not be a problem if the server is dealing
with a temporary burst of expirations, because it should be able to
eventually deal with them over time. However, if leases expire at a high
rate for a longer period of time, the unreclaimed leases will pile up in
the database. To notify the administrator that the current
configuration does not satisfy the needs for reclamation of expired
leases, the server issues a warning message in the log if it is unable
to reclaim all leases within several reclamation cycles. The
number of cycles after which such a warning is issued is specified with the
<command>unwarned-reclaim-cycles</command> configuration parameter.
</para>
<para>Setting the <command>reclaim-timer-wait-time</command> to 0 disables
periodic reclamation of the expired leases.</para>
</section>
<section xml:id="lease-affinity">
<title>Configuring Lease Affinity</title>
<para>Suppose that a laptop goes into sleep mode after a period of user
inactivity. While the laptop is in sleep mode, its DHCP client will not
renew leases obtained from the server and these leases will eventually
expire. When the laptop wakes up, it is often desirable for it to continue
using its previous assigned IP addresses. To facilitate this,
the server needs to correlate returning clients with their expired leases.
When the client returns, the server will first check for those leases and
re-assign them if they have not been assigned to another client. The ability
of the server to re-assign the same lease to a returning client is
referred to as "lease affinity."
</para>
<para>When lease affinity is enabled (i.e. when
<command>hold-reclaimed-time</command> is configured to a value
greater than zero), the server will still
reclaim leases according to the parameters described in
<xref linkend="lease-reclaim-config"/>, but the reclaimed leases
will be held in the database (rather than removed) for a specified
amount of time. When the client returns, the server will first verify
whether there are any reclaimed leases associated with this client and will
re-assign them if possible. However, it is important to note that
any reclaimed lease may be assigned to another client if that client
specifically asks for it. Therefore, lease affinity does not
guarantee that the reclaimed lease will be available for the client
who used it before; it merely increases the chances for the client to
be assigned the same lease. If the lease pool is small (this mostly applies
to DHCPv4 for which address space is small), there is an increased
likelihood that the expired lease will be assigned to another client.
</para>
<para>Consider the following configuration:
<screen>
"Dhcp4": {
...
"expired-leases-processing": {
"reclaim-timer-wait-time": 3,
"hold-reclaimed-time": 1800,
"flush-reclaimed-timer-wait-time": 5
},
...
}
</screen>
</para>
<para>The <command>hold-reclaim-time</command> specifies how many seconds
after an expiration a reclaimed lease should be held in the database
for re-assignment to the same client. In the example given above,
reclaimed leases will be held for 30 minutes (1800s) after their
expiration. During this time, the server will likely be able to
re-assign the same lease to the returning client, unless another client
requests this lease and the server assigns it.</para>
<para>The server must periodically remove reclaimed leases for which the
time indicated by <command>hold-reclaim-time</command> has elapsed. The
<command>flush-reclaimed-timer-wait-time</command> parameter controls how
often the server removes such leases. In the example provided
above, the server will initiate removal of such leases 5 seconds after
the previous removal attempt was completed. Setting this value to 0
disables lease affinity, in which case leases will be removed from the
lease database when they are reclaimed. If lease affinity is enabled, it
is recommended that <command>hold-reclaim-time</command> be set to a value significantly
higher than the <command>reclaim-timer-wait-time</command>, as timely
removal of expired-reclaimed leases is less critical than the removal
process, which may impact server responsiveness.</para>
<para>There is no guarantee that lease affinity will work every
time. If a server is running out of addresses, it will reassign
expired addresses to new clients. Also, clients can request
specific addresses and the server will try to honor such a request
if possible. If you want to ensure a client keeps its address,
even after periods of inactivity, consider using host reservations
or leases with very long lifetimes.</para>
</section>
<section xml:id="leases-reclamation-using-command">
<title>Reclaiming Expired Leases with Command</title>
<para>The <emphasis>leases-reclaim</emphasis> command can be used to trigger
lease reclamation at any time. Please consult the
<xref linkend="command-leases-reclaim"/> section for details about using this
command.</para>
</section>
</chapter>

101
doc/guide/lfc.xml
View File

@ -1,101 +0,0 @@
<!--
- Copyright (C) 2015-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="kea-lfc">
<title>The LFC Process</title>
<section xml:id="kea-lfc-overview">
<title>Overview</title>
<para><command>kea-lfc</command> is a service process that removes
redundant information from the files used to provide persistent storage
for the memfile database backend. This service is written to run as a
standalone process.
</para>
<para>While <command>kea-lfc</command> can be started externally, there is
usually no need to do this. <command>kea-lfc</command> is run on a periodic
basis by the Kea DHCP servers.
</para>
<para>The process operates on a set of files, using them to receive input and output
of the lease entries and to indicate what stage the process is in, in the event of an
interruption. Currently the caller must supply names for all of the files.
</para>
</section>
<section xml:id="kea-lfc-usage">
<title>Command-Line Options</title>
<para><command>kea-lfc</command> is run as follows:
<screen>
kea-lfc [-4 | -6] -c config-file -p pid-file -x previous-file -i copy-file -o output-file -f finish-file
</screen>
</para>
<para>The argument <command>-4</command> or <command>-6</command> selects the protocol
version of the lease files.
</para>
<para>The <command>-c</command> argument specifies the configuration file. This is
required, but is not currently used by the process.
</para>
<para>The <command>-p</command> argument specifies the PID file. When the
<command>kea-lfc</command> process starts, it attempts to determine whether another
instance of the process is already running by examining the pid file. If one
is already running, the new process is terminated; if one is not running, Kea writes
its pid into the pid file.
</para>
<para>The other filenames specify where the <command>kea-lfc</command> process
should look for input, write its output, and perform its bookkeeping:
<itemizedlist>
<listitem><simpara>
<command>previous</command> —
When <command>kea-lfc</command> starts, this
is the result of any previous run of <command>kea-lfc</command>.
When <command>kea-lfc</command> finishes, it is the result of this run.
If <command>kea-lfc</command> is interrupted before completing,
this file may not exist.
</simpara></listitem>
<listitem><simpara>
<command>input</command> —
Before the DHCP server invokes <command>kea-lfc</command>, it will
move the current lease file here and then call <command>kea-lfc</command>
with this file.
</simpara></listitem>
<listitem><simpara>
<command>output</command> —
This is the temporary file where <command>kea-lfc</command> writes the leases.
Upon completion of writing this file, it will be moved to the finish file
(see below).
</simpara></listitem>
<listitem><simpara>
<command>finish</command> —
This is another temporary file <command>kea-lfc</command> uses for bookkeeping. When
<command>kea-lfc</command> completes writing the outputfile, it moves it to this
file name. After <command>kea-lfc</command> finishes deleting the other files
(previous and input), it moves this file to the previous lease file. By moving the
files in this fashion, the <command>kea-lfc</command> and the DHCP server
processes can determine the correct file to use even if one of the
processes was interrupted before completing its task.
</simpara></listitem>
</itemizedlist>
</para>
<para>There are several additional arguments, mostly for debugging purposes.
<command>-d</command> sets the logging level to debug. <command>-v</command> and
<command>-V</command> print out version stamps, with <command>-V</command> providing
a longer form. <command>-h</command> prints out the usage string.
</para>
</section>
</chapter>

612
doc/guide/logging.xml
View File

@ -1,612 +0,0 @@
<!--
- Copyright (C) 2014-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="logging">
<title>Logging</title>
<section>
<title>Logging Configuration</title>
<para>
During its operation Kea may produce many messages. They differ in
severity (some are more important than others) and source (different components
(e.g. hooks) produce different messages). It is useful to understand
which log messages are critical and which are not, and configure your
logging appropriately. For example, debug-level messages can be safely
ignored in a typical deployment. They are, however, very useful when
debugging a problem.
</para>
<para>
The logging system in Kea is configured through the loggers entry
in the server section of your configuration file. In previous
Kea releases this entry was in an independent Logging section,
this is still supported for backward compatibility.
</para>
<section>
<title>Loggers</title>
<para>
Within Kea, a message is logged through an entity called a
"logger." Different components log messages through different
loggers, and each logger can be configured independently of
the others. Some components, in particular the DHCP server
processes, may use multiple loggers to log messages pertaining
to different logical functions of the component. For example,
the DHCPv4 server uses one logger for messages
about packet reception and transmission, another
logger for messages related to lease allocation, and so on.
Some of the libraries used by the Kea server, e.g. libdhcpsrv,
use their own loggers.
</para>
<para>
Users implementing hooks libraries (code attached to the server at
runtime) are responsible for creating the loggers used by those
libraries. Such loggers should have unique names, different
from the logger names used by Kea. In this way the
messages produced by the hooks library can be distinguished from
messages issued by the core Kea code. Unique names also allow
the loggers to be configured independently of loggers used
by Kea. Whenever it makes sense, a hooks library can use multiple
loggers to log messages pertaining to different logical parts
of the library.
</para>
<para>
In the server section of a configuration file you can specify the
configuration for zero or more loggers (including loggers used by the
proprietary hooks libraries). If there are no loggers specified, the
code will use default values; these cause Kea to log messages of INFO
severity or greater to standard output. There is a small
time window after Kea has been started but before it has read its
configuration; logging in this short period can be controlled
using environment variables. For details, see <xref linkend="logging-during-startup"/>.
</para>
<para>
The three main elements of a logger configuration are:
<command>name</command> (the component that is generating the messages),
<command>severity</command> (what to log), and
<command>output_commands</command> (where to log). There is also a
<command>debuglevel</command> element, which is only relevant if
debug-level logging has been selected.
</para>
<section>
<title>name (string)</title>
<para>
Each logger in the system has a name: that of the
component binary file using it to log messages. For instance, if you
want to configure logging for the DHCPv4 server, you add an entry
for a logger named <quote>kea-dhcp4</quote>. This configuration will
then be used by the loggers in the DHCPv4 server, and all the
libraries used by it (unless a library defines its own logger and
there is a specific logger configuration that applies to that logger).
</para>
<para>
When tracking down an issue with the server's operation, use of
DEBUG logging is required to obtain the verbose output needed for
problem diagnosis. However, the high verbosity is likely to
overwhelm the logging system in cases where the server
is processing high-volume traffic. To mitigate this problem,
Kea can use multiple loggers, for different
functional parts of the server, that can each be configured independently.
If the user is reasonably confident that a problem originates
in a specific function of the server, or that the problem is related
to a specific type of operation, they may enable high verbosity
only for the relevant logger, thereby limiting the debug messages
to the required minimum.
</para>
<para>
The loggers are associated with a particular library or binary
of Kea. However, each library or binary may (and usually does)
include multiple loggers. For example, the DHCPv4 server binary
contains separate loggers for packet parsing, for dropped packets,
for callouts, etc.
</para>
<para>
The loggers form a hierarchy. For each program in Kea, there is
a "root" logger, named after the program (e.g. the root logger for
kea-dhcp (the DHCPv4 server) is named kea-dhcp4. All other loggers
are children of this logger and are named accordingly, e.g. the
allocation engine in the DHCPv4 server logs messages using
a logger called kea-dhcp4.alloc-engine.
</para>
<para>
This relationship is important, as each child logger derives its
default configuration from its parent root logger.
In the typical case, the root logger configuration
is the only logging configuration specified in the configuration
file and so applies to all loggers. If an entry is made for
a given logger, any attributes specified override those of
the root logger, whereas any not specified are inherited from it.
</para>
<para>
To illustrate this, suppose you are using the DHCPv4 server
with the root logger <quote>kea-dhcp4</quote> logging at the
INFO level. In order to enable DEBUG verbosity for DHCPv4
packet drops, you must create a configuration entry for the
logger called <quote>kea-dhcp4.bad-packets</quote> and specify
severity DEBUG for this logger. All other configuration
parameters may be omitted for this logger if the logger should
use the default values specified in the root logger's
configuration.
</para>
<para>
If there are multiple logger specifications in the configuration
that might match a particular logger, the specification with the
more specific logger name takes precedence. For example, if there
are entries for both <quote>kea-dhcp4</quote> and
<quote>kea-dhcp4.dhcpsrv</quote>, the main DHCPv4 server program — and all
libraries it uses other than the dhcpsrv library (libdhcpsrv) — will log messages
according to the configuration in the first entry
(<quote>kea-dhcp4</quote>). Messages generated by the dhcpsrv library
will be logged according to the configuration set by the second entry.
</para>
<para>
Currently defined loggers are defined in the following table. The
"Software Package" column of this table specifies whether the particular
loggers belong to the core Kea code (open source Kea binaries and
libraries), or hook libraries (open source or premium).
</para>
<para>
<table frame="all" xml:id="supported-loggers-list">
<title>List of loggers supported by Kea servers and hooks libraries
shipped with Kea and premium packages</title>
<tgroup cols='3'>
<colspec colname="logger-name" align="left"/>
<colspec colname="software-package" align="center"/>
<colspec colname="description" align="left"/>
<thead>
<row>
<entry>Logger Name</entry>
<entry>Software Package</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row><entry><command>kea-ctrl-agent</command></entry><entry>core</entry><entry>The root logger for the Control Agent exposing the RESTful control API. All components used by the Control Agent inherit the settings from this logger.</entry></row>
<row><entry><command>kea-ctrl-agent.http</command></entry><entry>core</entry><entry>A logger which outputs log messages related to receiving, parsing, and sending HTTP messages.</entry></row>
<row><entry><command>kea-dhcp4</command></entry><entry>core</entry><entry>The root logger for the DHCPv4 server. All components used by the DHCPv4 server inherit the settings from this logger.</entry></row>
<row><entry><command>kea-dhcp6</command></entry><entry>core</entry><entry>The root logger for the DHCPv6 server. All components used by the DHCPv6 server inherit the settings from this logger.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.alloc-engine</command></member><member><command>kea-dhcp6.alloc-engine</command></member></simplelist></entry><entry>core</entry><entry>Used by the lease allocation engine, which is responsible for managing leases in the lease database, i.e. creating, modifying, and removing DHCP leases as a result of processing messages from the clients.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.bad-packets</command></member><member><command>kea-dhcp6.bad-packets</command></member></simplelist></entry><entry>core</entry><entry>Used by the DHCP servers for logging inbound client packets that were dropped or to which the server responded with a DHCPNAK. It allows administrators to configure a separate log output that contains only packet drop and reject entries.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.callouts</command></member><member><command>kea-dhcp6.callouts</command></member></simplelist></entry><entry>core</entry><entry>Used to log messages pertaining to the callouts registration and execution for the particular hook point.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.commands</command></member><member><command>kea-dhcp6.commands</command></member></simplelist></entry><entry>core</entry><entry>Used to log messages relating to the handling of commands received by the DHCP server over the command channel.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.database</command></member><member><command>kea-dhcp6.database</command></member></simplelist></entry><entry>core</entry><entry>Used to log messages relating to general operations on the relational databases and Cassandra.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.ddns</command></member><member><command>kea-dhcp6.ddns</command></member></simplelist></entry><entry>core</entry><entry>Used by the DHCP server to log messages related to the Client FQDN and Hostname option processing. It also includes log messages related to the relevant DNS updates.</entry></row>
<row><entry><command>kea-dhcp4.dhcp4</command></entry><entry>core</entry><entry>Used by the DHCPv4 server daemon to log basic operations.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.dhcpsrv</command></member><member><command>kea-dhcp6.dhcpsrv</command></member></simplelist></entry><entry>core</entry><entry>The base loggers for the libkea-dhcpsrv library.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.eval</command></member><member><command>kea-dhcp6.eval</command></member></simplelist></entry><entry>core</entry><entry>Used to log messages relating to the client classification expression evaluation code.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.host-cache-hooks</command></member><member><command>kea-dhcp6.host-cache-hooks</command></member></simplelist></entry><entry>libdhcp_host_cache premium hook library</entry><entry>This logger is used to log messages related to the operation of the Host Cache Hook Library.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.flex-id-hooks</command></member><member><command>kea-dhcp6.flex-id-hooks</command></member></simplelist></entry><entry>libdhcp_flex_id premium hook library</entry><entry>This logger is used to log messages related to the operation of the Flexible Identifiers Hook Library.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.ha-hooks</command></member><member><command>kea-dhcp6.ha-hooks</command></member></simplelist></entry><entry>libdhcp_ha hook library</entry><entry>This logger is used to log messages related to the operation of the High Availability Hook Library.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.hooks</command></member><member><command>kea-dhcp6.hooks</command></member></simplelist></entry><entry>core</entry><entry>Used to log messages related to the management of hooks libraries, e.g. registration and deregistration of the libraries, and to the initialization of the callouts execution for various hook points within the DHCP server.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.host-cmds-hooks</command></member><member><command>kea-dhcp6.host-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_host_cmds premium hook library</entry><entry>This logger is used to log messages related to the operation of the Host Cmds hooks library. In general, these will pertain to the loading and unloading of the library and the execution of commands by the library.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.hosts</command></member><member><command>kea-dhcp6.hosts</command></member></simplelist></entry><entry>core</entry><entry>Used within the libdhcpsrv, it logs messages related to the management of the DHCP host reservations, i.e. retrieval of the reservations and adding new reservations.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.lease-cmds-hooks</command></member><member><command>kea-dhcp6.lease-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_lease_cmds hook library</entry><entry>This logger is used to log messages related to the operation of the Lease Cmds hooks library. In general, these will pertain to the loading and unloading of the library and the execution of commands by the library.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.leases</command></member><member><command>kea-dhcp6.leases</command></member></simplelist></entry><entry>core</entry><entry>Used by the DHCP server to log messages related to lease allocation. The messages include detailed information about the allocated or offered leases, errors during the lease allocation, etc.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.legal-log-hooks</command></member><member><command>kea-dhcp6.legal-log-hooks</command></member></simplelist></entry><entry>libdhcp_legal_log premium hook library</entry><entry>This logger is used to log messages related to the operation of the Forensic Logging Hooks Library.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.options</command></member><member><command>kea-dhcp4.options</command></member></simplelist></entry><entry>core</entry><entry>Used by the DHCP server to log messages related to the processing of options in the DHCP messages, i.e. parsing options, encoding options into on-wire format, and packet classification using options contained in the received packets.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.packets</command></member><member><command>kea-dhcp6.packets</command></member></simplelist></entry><entry>core</entry><entry>This logger is mostly used to log messages related to transmission of the DHCP packets, i.e. packet reception and the sending of a response. Such messages include information about the source and destination IP addresses and interfaces used to transmit packets. The logger is also used to log messages related to subnet selection, as this selection is usually based on the IP addresses, relay addresses, and/or interface names, which can be retrieved from the received packet even before the DHCP message carried in the packet is parsed.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.radius-hooks</command></member><member><command>kea-dhcp6.radius-hooks</command></member></simplelist></entry><entry>libdhcp_radius premium hook library</entry><entry>This logger is used to log messages related to the operation of the Radius Hook Library.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.stat-cmds-hooks</command></member><member><command>kea-dhcp6.stat-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_stat_cmds hook library</entry><entry>This logger is used to log messages related to the operation of the Statistics Commands hooks library. In general, these will pertain to loading and unloading the library and the execution of commands by the library.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.subnet-cmds-hooks</command></member><member><command>kea-dhcp6.subnet-cmds-hooks</command></member></simplelist></entry><entry>libdhcp_subnet_cmds hook library</entry><entry>This logger is used to log messages related to the operation of the Subnet Commands hooks library. In general, these will pertain to loading and unloading the library and the execution of commands by the library.</entry></row>
<row><entry><simplelist type="horiz"><member><command>kea-dhcp4.mysql-cb-hooks</command></member><member><command>kea-dhcp6.mysql-cb-hooks</command></member></simplelist></entry><entry>libdhcp_mysql_cb_hooks hook library</entry><entry>This logger is used to log messages related to the operation of the MySQL Configuration Backend hooks library.</entry></row>
<row><entry><command>kea-dhcp-ddns</command></entry><entry>core</entry><entry>The root logger for the kea-dhcp-ddns daemon. All components used by this daemon inherit the settings from this logger unless there are configurations for more specialized loggers..</entry></row>
<row><entry><command>kea-dhcp-ddns.dctl</command></entry><entry>core</entry><entry>The logger used by the kea-dhcp-ddns daemon for logging basic information about the process, received signals, and triggered reconfigurations.</entry></row>
<row><entry><command>kea-dhcp-ddns.dhcpddns</command></entry><entry>core</entry><entry>The logger used by the kea-dhcp-ddns daemon for logging events related to DDNS operations.</entry></row>
<row><entry><command>kea-dhcp-ddns.dhcp-to-d2</command></entry><entry>core</entry><entry>Used by the kea-dhcp-ddns daemon for logging information about events dealing with receiving messages from the DHCP servers and adding them to the queue for processing.</entry></row>
<row><entry><command>kea-dhcp-ddns.d2-to-dns</command></entry><entry>core</entry><entry>Used by the kea-dhcp-ddns daemon for logging information about events dealing with sending and receiving messages with the DNS servers.</entry></row>
<row><entry><command>kea-netconf</command></entry><entry>core</entry><entry>The root logger for the Netconf agent. All components used by Netconf inherit the settings from this logger if there is no specialized logger provided.</entry></row>
</tbody>
</tgroup>
</table>
</para>
<para>
Note that user-defined hook libraries should not use any of the loggers
mentioned above, but should instead define new loggers with names that correspond to
the libraries using them. Suppose that the user created the library
called <quote>libdhcp-packet-capture</quote> to dump packets received and
transmitted by the server to the file. An appropriate name for the
logger could be <command>kea-dhcp4.packet-capture-hooks</command>. (Note
that the hook library implementer only specifies the second part of
this name, i.e. <quote>packet-capture</quote>. The first part is a
root-logger name and is prepended by the Kea logging system.) It is
also important to note that since this new logger is a child of a root
logger, it inherits the configuration from the root logger, something
that can be overridden by an entry in the configuration file.
</para>
<para>
The easiest way to find a logger name is to configure all logging to
go to a single destination and look for specific logger names. See
<xref linkend="logging-message-format"/> for details.
</para>
</section>
<section>
<title>severity (string)</title>
<para>
This specifies the category of messages logged. Each message is
logged with an associated severity, which may be one of the following
(in descending order of severity):
</para>
<itemizedlist>
<listitem>
<simpara>
FATAL - associated with messages generated by a condition that is
so serious that the server cannot continue executing.
</simpara>
</listitem>
<listitem>
<simpara>
ERROR - associated with messages generated by an error condition.
The server will continue executing, but the results may not be as
expected.
</simpara>
</listitem>
<listitem>
<simpara>
WARN - indicates an out-of-the-ordinary condition. However, the
server will continue executing normally.
</simpara>
</listitem>
<listitem>
<simpara>
INFO - an informational message marking some event.
</simpara>
</listitem>
<listitem>
<simpara>
DEBUG - messages produced for debugging purposes.
</simpara>
</listitem>
</itemizedlist>
<para>
When the severity of a logger is set to one of these values, it will
only log messages of that severity and above (e.g. setting the logging
severity to INFO will log INFO, WARN, ERROR, and FATAL messages). The
severity may also be set to NONE, in which case all messages from that
logger are inhibited.
</para>
<note>
<para>
The keactrl tool, described in <xref linkend="keactrl"/>, can be
configured to start the servers in verbose mode. If this is the
case, the settings of the logging severity in the configuration file
will have no effect, i.e. the servers will use a logging severity of
DEBUG regardless of the logging settings specified in the
configuration file. If you need to control severity via the
configuration file, please make sure that the
<parameter>kea_verbose</parameter> value is set to "no" within the
keactrl configuration.
</para>
</note>
</section>
<section>
<title>debuglevel (integer)</title>
<para>
When a logger's severity is set to DEBUG, this value specifies what
level of debug messages should be printed. It ranges from 0 (least
verbose) to 99 (most verbose). If severity for the logger is not
DEBUG, this value is ignored.
</para>
</section>
<section>
<title>output_options (list)</title>
<para>
Each logger can have zero or more <option>output_options</option>.
These specify where log messages are sent and are explained in
detail below.
</para>
<section>
<title>output (string)</title>
<para>
This value determines the type of output. There are several special
values allowed here: <command>stdout</command> (messages are printed
on standard output), <command>stderr</command> (messages are printed
on stderr), <command>syslog</command> (messages are logged to syslog
using default name), <command>syslog:name</command> (messages are
logged to syslog using specified name). Any other value is
interpreted as a filename to which messages should be written.
</para>
</section>
<section>
<title>flush (true of false)</title>
<para>
Flush buffers after each log message. Doing this will reduce
performance but will ensure that if the program terminates
abnormally, all messages up to the point of termination are output.
The default is "true".
</para>
</section>
<section>
<title>maxsize (integer)</title>
<para>
Only relevant when the destination is a file. This is the maximum size
in bytes that a log file may reach. When the maximum size is
reached, the file is renamed and a new file opened. For example,
a ".1" is appended to the name — if a ".1" file exists, it
is renamed ".2", etc. This is referred to as rotation.
</para>
<para>
The default value is 10240000 (10MB). The smallest value that may
be specified without disabling rotation is 204800. Any value less than
this, including 0, disables rotation.
</para>
<note>
<simpara>
Due to a limitation of the underlying logging library (log4cplus),
rolling over the log files (from ".1" to ".2", etc) may show odd
results; there can be multiple small files at the timing of roll
over. This can happen when multiple processes try to roll over
the files simultaneously. Version 1.1.0 of log4cplus solved this
problem, so if this version or later of log4cplus is used to
build Kea, the issue should not occur. Even for older versions, it is
normally expected to happen rarely unless the log messages are
produced very frequently by multiple different processes.
</simpara>
</note>
</section>
<section>
<title>maxver (integer)</title>
<para>
Only relevant when the destination is a file and rotation is enabled
(i.e. maxsize is large enough). This is the maximum number of rotated
versions that will be kept. Once that number of files has been
reached, the oldest file, "log-name.maxver", will be discarded
each time the log rotates. In other words, at most there will be
the active log file plus maxver rotated files. The minimum and
default value is 1.
</para>
</section>
</section>
<section>
<title>Example Logger Configurations</title>
<para>
In this example we want to set the Server logging to write to the
console using standard output.
</para>
<screen><userinput>"Server": {
"loggers": [
{
"name": "kea-dhcp4",
"output_options": [
{
"output": "stdout"
}
],
"severity": "WARN"
}
]
}</userinput> </screen>
<para>
In this second example, we want to store debug log messages in a file
that is at most 2MB and keep up to 8 copies of old logfiles. Once the
logfile grows to 2MB, it will be renamed and a new file will be
created.
</para>
<screen><userinput>"Server": {
"loggers": [
{
"name": "kea-dhcp6",
"output_options": [
{
"output": "/var/log/kea-debug.log",
"maxver": 8,
"maxsize": 204800,
"flush": true
}
],
"severity": "DEBUG",
"debuglevel": 99
}
]
}</userinput></screen>
</section>
</section>
<section xml:id="logging-message-format">
<title>Logging Message Format</title>
<para>
Each message written to the configured logging destinations comprises a
number of components that identify the origin of the message and, if the
message indicates a problem, information about the problem that may be
useful in fixing it.
</para>
<para>
Consider the message below logged to a file:
<screen>2014-04-11 12:58:01.005 INFO [kea-dhcp4.dhcpsrv/27456]
DHCPSRV_MEMFILE_DB opening memory file lease database: type=memfile universe=4</screen>
</para>
<para>
Note: the layout of messages written to the system logging file (syslog)
may be slightly different. This message has been split across two lines
here for display reasons; in the logging file, it will appear on one
line.
</para>
<para>
The log message comprises a number of components:
<variablelist>
<varlistentry>
<term>2014-04-11 12:58:01.005</term>
<!-- TODO: timestamp repeated even if using syslog? -->
<listitem>
<para>
The date and time at which the message was generated.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>INFO</term>
<listitem>
<para>
The severity of the message.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>[kea-dhcp4.dhcpsrv/27456]</term>
<listitem>
<para>
The source of the message. This includes two elements: the Kea
process generating the message (in this case,
<command>kea-dhcp4</command>) and the component within the
program from which the message originated
(<command>dhcpsrv</command>, which is the name of the common
library used by DHCP server implementations). The number after
the slash is a process id (pid).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>DHCPSRV_MEMFILE_DB</term>
<listitem>
<para>
The message identification. Every message in Kea has a unique
identification, which can be used as an index into the
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="kea-messages.html"><citetitle>Kea Messages
Manual</citetitle></link>
(<uri xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://jenkins.isc.org/job/Kea_doc/messages/kea-messages.html">https://jenkins.isc.org/job/Kea_doc/messages/kea-messages.html</uri>)
from which more information can be obtained.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>opening memory file lease database: type=memfile universe=4</term>
<listitem>
<para>
A brief description. Within this text, information relating to
the condition that caused the message to be logged will be
included. In this example, the information is logged that the
in-memory lease database backend will be used to store DHCP
leases.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</section>
<section xml:id="logging-during-startup">
<title>Logging During Kea Startup</title>
<para>
The logging configuration is specified in the configuration file.
However, when Kea starts, the file is not read until partway into the
initialization process. Prior to that, the logging settings are set to
default values, although it is possible to modify some aspects of the
settings by means of environment variables. Note that in the absence of
any logging configuration in the configuration file, the settings of the
(possibly modified) default configuration will persist while the program
is running.
</para>
<para>
The following environment variables can be used to control the behavior
of logging during startup:
</para>
<variablelist>
<varlistentry>
<term>KEA_LOCKFILE_DIR</term>
<listitem>
<para>
Specifies a directory where the logging system should create its
lock file. If not specified, it is
<replaceable>prefix</replaceable>/var/run/kea, where
<replaceable>prefix</replaceable> defaults to /usr/local. This
variable must not end with a slash. There is one special value:
"none", which instructs Kea to not create a lock file at all. This
may cause issues if several processes log to the same file.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>KEA_LOGGER_DESTINATION</term>
<listitem>
<para>
Specifies logging output. There are several special values.
<variablelist>
<varlistentry>
<term>stdout</term>
<listitem>
<para>
Log to standard output.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>stderr</term>
<listitem>
<para>
Log to standard error.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>syslog<optional>:<replaceable>fac</replaceable></optional></term>
<listitem>
<para>
Log via syslog. The optional
<replaceable>fac</replaceable> (which is separated from
the word "syslog" by a colon) specifies the facility to be
used for the log messages. Unless specified, messages will
be logged using the facility "local0".
</para>
</listitem>
</varlistentry>
</variablelist>
Any other value is treated as a name of the output file. If not
specified otherwise, Kea will log to standard output.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>
</section>
</chapter>

1162
doc/guide/netconf.xml
View File

File diff suppressed because it is too large Load Diff

144
doc/guide/quickstart.xml
View File

@ -1,144 +0,0 @@
<!--
- Copyright (C) 2014-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- need this include to make the &keaversion; macro work -->
<!DOCTYPE book [
<!ENTITY % keaversion SYSTEM "version.ent">
%keaversion;
]>
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
xml:id="quickstart">
<title>Quick Start</title>
<para>
This section describes the basic steps needed to get Kea up and running.
For further details, full customizations, and troubleshooting, see the
respective chapters in the Kea Administrator Reference Manual (ARM).
</para>
<section xml:id="quick-start">
<title>Quick Start Guide for DHCPv4 and DHCPv6 Services</title>
<orderedlist>
<listitem>
<simpara>
Install required run-time and build dependencies. See <xref linkend="build-requirements"/> for details.
</simpara>
</listitem>
<listitem>
<para>
Download the Kea source tarball from the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://www.isc.org/downloads/">ISC.org downloads page</link> or the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://ftp.isc.org/isc/kea/">ISC FTP server</link>.
</para>
</listitem>
<listitem>
<para>
Extract the tarball. For example:
<screen>$ <userinput>tar xvzf kea-&keaversion;.tar.gz</userinput></screen>
</para>
</listitem>
<listitem>
<para>Go into the source directory and run the configure script:
<screen>$ <userinput>cd kea-&keaversion;</userinput>
$ <userinput>./configure [your extra parameters]</userinput></screen>
</para>
</listitem>
<listitem>
<para>Build it:
<screen>$ <userinput>make</userinput></screen>
</para>
</listitem>
<listitem>
<para>Install it (by default it will be placed in
<filename>/usr/local/</filename>,
so it is likely that you will need root privileges for this step):
<screen># <userinput>make install</userinput></screen>
</para>
</listitem>
<listitem>
<para>Edit the Kea configuration files which by default are installed in
the <filename>[kea-install-dir]/etc/kea/</filename> directory. These are:
<filename>kea-dhcp4.conf</filename>, <filename>kea-dhcp6.conf</filename>,
<filename>kea-dhcp-ddns.conf</filename> and
<filename>kea-ctrl-agent.conf</filename>, for DHCPv4 server, DHCPv6 server,
D2, and Control Agent, respectively.
</para>
</listitem>
<listitem>
<para>In order to start the DHCPv4 server in the background, run the
following command (as root):
<screen># <userinput>keactrl start -s dhcp4</userinput></screen>
Or run the following command to start the DHCPv6 server instead:
<screen># <userinput>keactrl start -s dhcp6</userinput></screen>
Note that it is also possible to start all servers simultaneously:
<screen>$ <userinput>keactrl start</userinput></screen>
</para>
</listitem>
<listitem>
<para>Verify that the Kea server(s) is/are running:
<screen># <userinput>keactrl status</userinput></screen>
A server status of "inactive" may indicate a configuration
error. Please check the log file (by default named
<filename>[kea-install-dir]/var/log/kea-dhcp4.log</filename>,
<filename>[kea-install-dir]/var/log/kea-dhcp6.log</filename>,
<filename>[kea-install-dir]/var/log/kea-ddns.log</filename> or
<filename>[kea-install-dir]/var/log/kea-ctrl-agent.log</filename>)
for the details of the error.
</para>
</listitem>
<listitem>
<para>
If the server has been started successfully, test that it is
responding to DHCP queries and that the client
receives a configuration from the server; for example, use
the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.isc.org/downloads/DHCP/">ISC DHCP client</link>.
</para>
</listitem>
<listitem>
<para>
Stop running the server(s):
<screen># <userinput>keactrl stop</userinput></screen>
</para>
</listitem>
</orderedlist>
<para>
For instructions specific to your system, please read the
<link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://kb.isc.org/docs/installing-kea">system-specific notes</link>,
available in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://kb.isc.org/docs">Kea section of ISC's Knowledgebase</link>.
</para>
<para>The details of <command>keactrl</command> script usage can be found
in <xref linkend="keactrl"/>.</para>
</section>
<section xml:id="quick-start-direct-run">
<title>Running the Kea Servers Directly</title>
<para>The Kea servers can be started directly, without the need to use the
<command>keactrl</command>. To start the DHCPv4 server run the following
command:
<screen># <userinput>kea-dhcp4 -c /path/to/your/kea4/config/file.json</userinput></screen>
Similarly, to start the DHCPv6 server run the following command:
<screen># <userinput>kea-dhcp6 -c /path/to/your/kea6/config/file.json</userinput></screen>
</para>
</section>
</chapter>

154
doc/guide/shell.xml
View File

@ -1,154 +0,0 @@
<!--
- Copyright (C) 2017-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="kea-shell">
<title>The Kea Shell</title>
<section xml:id="shell-overview">
<title>Overview</title>
<para>Kea 1.2.0 introduced the Control Agent (CA, see <xref linkend="kea-ctrl-agent"/>), which
provides a RESTful control interface over HTTP. That API is typically expected to be used by
various IPAMs and similar management systems. Nevertheless, there may be cases when an administrator wants
to send a command to the CA directly. The Kea shell provides a way to do this. It is a simple
command-line, scripting-friendly, text client that is able to connect to the CA, send it commands
with parameters, retrieve the responses, and display them.</para>
<para>As the primary purpose of the Kea shell is as a tool in a scripting environment,
it is not interactive. However, with simple tricks it can be run manually.
</para>
</section>
<section xml:id="shell-usage">
<title>Shell Usage</title>
<para><command>kea-shell</command> is run as follows:
<screen>
kea-shell [--host hostname] [--port number] [--path path] [--timeout seconds] [--service service-name] [command]
</screen>
where:
</para>
<itemizedlist>
<listitem>
<simpara>
<command>--host <replaceable>hostname</replaceable></command> specifies the hostname
of the CA. If not specified, "localhost" is used.
</simpara>
</listitem>
<listitem>
<simpara>
<command>--port <replaceable>number</replaceable></command> specifies the TCP port
on which the CA listens. If not specified, 8000 is used.
</simpara>
</listitem>
<listitem>
<simpara>
<command>--path <replaceable>path</replaceable></command> specifies
the path in the URL to connect to. If not specified, an
empty path is used. As the CA listens at the empty path,
this parameter is useful only with a reverse proxy.
</simpara>
</listitem>
<listitem>
<simpara>
<command>--timeout <replaceable>seconds</replaceable></command> specifies the
timeout (in seconds) for the connection. If not given, 10 seconds is used.
</simpara>
</listitem>
<listitem>
<simpara>
<command>--service <replaceable>service-name</replaceable></command> specifies the
target of a command. If not given, the CA will be used as the target. May be used more
than once to specify multiple targets.
</simpara>
</listitem>
<listitem>
<simpara>
<command>command</command> specifies the command to be sent. If not specified,
the <command>list-commands</command> command is used.
</simpara>
</listitem>
</itemizedlist>
<para>Other switches are:</para>
<itemizedlist>
<listitem>
<simpara>
<command>-h</command> prints a help message.
</simpara>
</listitem>
<listitem>
<simpara>
<command>-v</command> prints the software version.
</simpara>
</listitem>
</itemizedlist>
<para>
Once started, the shell reads parameters for the command from standard input, which are
expected to be in JSON format. When all have been read, the shell establishes a connection
with the CA using HTTP, sends the command, and awaits a response. Once that is received,
it is displayed on standard output.
</para>
<para>
For a list of available commands, see <xref linkend="ctrl-channel"/>; additional commands
may be provided by hook libraries. If you are unsure which commands are supported, use the
<command>list-commands</command> command. It will instruct the CA to return a list of
all supported commands.
</para>
<para>The following shows a simple example of usage:
<screen>
$ <userinput>kea-shell --host 192.0.2.1 --port 8001 --service dhcp4 list-commands</userinput>
^D
</screen>
After the command line is entered, the program waits for command parameters to be entered.
Since <command>list-commands</command> does not take any
arguments, CTRL-D (represented in the above example by "^D") is pressed to indicate
end-of-file and terminate the parameter input. The shell then contacts
the CA and prints out the list of available commands returned for the service named <command>dhcp4</command>.
</para>
<para>It is envisaged that the Kea shell will be most frequently used in scripts; the next example
shows a simple scripted execution. It sends the command "config-write" to the CA
(the <command> --service </command> parameter hasn't been used), along
with the parameters specified in param.json. The result will be stored in result.json.
<screen>
$ cat param.json
"filename": "my-config-file.json"
$ <userinput>cat param.json | kea-shell --host 192.0.2.1 config-write &gt; result.json</userinput>
</screen>
</para>
<para>When a reverse proxy is used to de-multiplex requests to different
servers, the default empty path in the URL is not enough, so the
<command> --path </command> parameter should be used. For instance,
if requests to the "/kea" path are forwarded to the CA this can be used:
<screen>
$ <userinput>kea-shell --host 192.0.2.1 --port 8001 --path kea ...</userinput>
</screen>
</para>
<para>Kea shell requires Python to to be installed on the system. It has been tested with
Python 2.7 and various versions
of Python 3, up to 3.5. Since not every Kea deployment uses this feature and there are
deployments that do not have Python, the Kea shell is not enabled by default. To use it,
specify <command>--enable-shell</command> when running "configure" during the
installation of Kea.</para>
<para>The Kea shell is intended to serve more as a demonstration of the RESTful interface's
capabilities (and, perhaps, an illustration for people interested in integrating their
management environments with Kea) than as a serious management client. Do not expect it
to be significantly expanded in the future. It is, and will remain, a simple tool.</para>
</section>
</chapter>

268
doc/guide/stats.xml
View File

@ -1,268 +0,0 @@
<!--
- Copyright (C) 2015-2019 Internet Systems Consortium, Inc. ("ISC")
-
- This Source Code Form is subject to the terms of the Mozilla Public
- License, v. 2.0. If a copy of the MPL was not distributed with this
- file, you can obtain one at http://mozilla.org/MPL/2.0/.
-->
<!-- Converted by db4-upgrade version 1.1 -->
<chapter xmlns="http://docbook.org/ns/docbook" version="5.0" xml:id="stats">
<title>Statistics</title>
<section>
<title>Statistics Overview</title>
<para>Both Kea DHCP servers support statistics gathering.
A working DHCP server encounters various events
that can cause certain statistics to be collected. For
example, a DHCPv4 server may receive a packet (pkt4-received
statistic increases by one) that after parsing is identified as a
DHCPDISCOVER (pkt4-discover-received). The server processes it and
decides to send a DHCPOFFER representing its answer (pkt4-offer-sent
and pkt4-sent statistics increase by one). Such events happen
frequently, so it is not uncommon for the statistics to have
values in the high thousands. They can serve as an easy and powerful
tool for observing a server's and a network's health. For example,
if the pkt4-received statistic stops growing, it means that the
clients' packets are not reaching the server.</para>
<para>There are four types of statistics:
<itemizedlist>
<listitem>
<simpara><emphasis>integer</emphasis> - this is the most common type. It
is implemented as a 64-bit integer (int64_t in C++), so it can hold any
value between -2^63 to 2^63 -1.</simpara>
</listitem>
<listitem>
<simpara><emphasis>floating point</emphasis> - this type is intended to
store floating-point precision. It is implemented as a C++ double type.
</simpara>
</listitem>
<listitem>
<simpara><emphasis>duration</emphasis> - this type is intended for
recording time periods. It uses the `boost::posix_time::time_duration type,
which stores hours, minutes, seconds, and microseconds.</simpara>
</listitem>
<listitem>
<simpara><emphasis>string</emphasis> - this type is intended for
recording statistics in textual form. It uses the C++ std::string type.
</simpara>
</listitem>
</itemizedlist>
</para>
<para>
During normal operation, the DHCPv4 and DHCPv6 servers gather statistics.
For a list of DHCPv4 and DHCPv6 statistics, see <xref linkend="dhcp4-stats"/> and <xref linkend="dhcp6-stats"/>, respectively.
</para>
<para>
To extract data from the statistics module, the control channel can be
used. See <xref linkend="ctrl-channel"/> for details. It is possible to
retrieve a single statistic or all statistics, reset statistics (i.e. set to neutral
value, typically zero), or even remove completely a single statistic or all
statistics. See section <xref linkend="command-stats"/> for a list of
statistics-oriented commands.
</para>
</section>
<section xml:id="stats-lifecycle">
<title>Statistics Lifecycle</title>
<para>
It is useful to understand how the Statistics Manager module works. When
the server starts operation, the manager is empty and contains no
statistics. When <command>statistic-get-all</command> is executed, an
empty list is returned. Once the server performs an operation that causes
a statistic to change, the related statistic will be created. In general,
once a statistic is recorded even once, it is kept in the manager until
explicitly removed, by <command>statistic-remove</command> or
<command>statistic-remove-all</command> being called, or when the server is shut
down. Per-subnet statistics are explicitly removed when reconfiguration
takes place.
</para>
<para>
Statistics are considered runtime properties, so they are not retained
after server restart.
</para>
<para>
Removing a statistic that is updated frequently makes little sense, as it
will be re-added when the server code next records that statistic.
The <command>statistic-remove</command> and
<command>statistic-remove-all</command> commands are intended to remove
statistics that are not expected to be observed in the near future. For
example, a misconfigured device in a network may cause clients to report
duplicate addresses, so the server will report increasing values of
pkt4-decline-received. Once the problem is found and the device is
removed, the system administrator may want to remove the
pkt4-decline-received statistic, so it won't be reported anymore. If a
duplicate address is detected ever again, the server will add this
statistic back.
</para>
</section>
<section xml:id="command-stats">
<title>Commands for Manipulating Statistics</title>
<para>
There are several commands defined that can be used for accessing (-get),
resetting to zero or neutral value (-reset), or even removing a statistic
completely (-remove). The difference between reset and remove is somewhat
subtle. The reset command sets the value of the statistic to zero or a neutral
value, so after this operation, the statistic will have a value of 0 (integer),
0.0 (float), 0h0m0s0us (duration), or "" (string). When requested, a statistic
with the values mentioned will be returned. <command>Remove</command> removes
a statistic completely, so the statistic will not be reported anymore. Please
note that the server code may add it back if there is a reason to record
it.
</para>
<note><para>
The following sections describe commands that can be sent to the server; the
examples are not fragments of a configuration file. For more information on
sending commands to Kea, see <xref linkend="ctrl-channel"/>.
</para></note>
<section xml:id="command-statistic-get">
<title>statistic-get Command</title>
<para>
The <emphasis>statistic-get</emphasis> command retrieves a single
statistic. It takes a single-string parameter called
<command>name</command>, which specifies the statistic name. An example
command may look like this:
<screen>
{
"command": "statistic-get",
"arguments": {
"name": "<userinput>pkt4-received</userinput>"
}
}
</screen>
</para>
<para>
The server returns details of the requested statistic, with a result
of 0 indicating success and the specified statistic as the value of the
"arguments" parameter. If the requested statistic is not found, the response
will contain an empty map, i.e. only { } as an argument, but the status
code will still indicate success (0).
</para>
</section> <!-- end of command-statistic-get -->
<section xml:id="command-statistic-reset">
<title>statistic-reset Command</title>
<para>
The <emphasis>statistic-reset</emphasis> command sets the specified statistic
to its neutral value: 0 for integer, 0.0 for float, 0h0m0s0us for time
duration, and "" for string type. It takes a single-string parameter
called <command>name</command>, which specifies the statistic name. An
example command may look like this:
<screen>
{
"command": "statistic-reset",
"arguments": {
"name": "<userinput>pkt4-received</userinput>"
}
}
</screen>
</para>
<para>
If the specific statistic is found and the reset is successful, the
server responds with a status of 0, indicating success, and an empty
parameters field. If an error is encountered (e.g. the requested statistic
was not found), the server returns a status code of 1 (error)
and the text field contains the error description.
</para>
</section> <!-- end of command-statistic-reset -->
<section xml:id="command-statistic-remove">
<title>statistic-remove Command</title>
<para>
The <emphasis>statistic-remove</emphasis> command attempts to delete a single
statistic. It takes a single-string parameter called
<command>name</command>, which specifies the statistic name. An example
command may look like this:
<screen>
{
"command": "statistic-remove",
"arguments": {
"name": "<userinput>pkt4-received</userinput>"
}
}
</screen>
</para>
<para>
If the specific statistic is found and its removal is successful, the
server responds with a status of 0, indicating success, and an empty
parameters field. If an error is encountered (e.g. the requested statistic
was not found), the server returns a status code of 1 (error)
and the text field contains the error description.
</para>
</section> <!-- end of command-statistic-reset -->
<section xml:id="command-statistic-get-all">
<title>statistic-get-all Command</title>
<para>
The <emphasis>statistic-get-all</emphasis> command retrieves all statistics
recorded. An example command may look like this:
<screen>
{
"command": "statistic-get-all",
"arguments": { }
}
</screen>
</para>
<para>
The server responds with details of all recorded statistics, with a result
set to 0 to indicate that it iterated over all statistics (even when
the total number of statistics is zero).
</para>
</section> <!-- end of command-statistic-get-all -->
<section xml:id="command-statistic-reset-all">
<title>statistic-reset-all Command</title>
<para>
The <emphasis>statistic-reset</emphasis> command sets all statistics to
their neutral values: 0 for integer, 0.0 for float, 0h0m0s0us for time
duration, and "" for string type. An example command may look like this:
<screen>
{
"command": "statistic-reset-all",
"arguments": { }
}
</screen>
</para>
<para>
If the operation is successful, the server responds with a status of
0, indicating success, and an empty parameters field. If an error is
encountered, the server returns a status code of 1 (error) and the text
field contains the error description.
</para>
</section> <!-- end of command-statistic-reset-all -->
<section xml:id="command-statistic-remove-all">
<title>statistic-remove-all Command</title>
<para>
The <emphasis>statistic-remove-all</emphasis> command attempts to delete all
statistics. An example command may look like this:
<screen>
{
"command": "statistic-remove-all",
"arguments": { }
}
</screen>
</para>
<para>
If the removal of all statistics is successful, the server responds
with a status of 0, indicating success, and an empty parameters field. If
an error is encountered, the server returns a status code of 1 (error)
and the text field will contain the error description.
</para>
</section> <!-- end of command-statistic-remove-all -->
</section>
</chapter>

0
doc/images/.gitignore vendored
View File

0
doc/guide/_static/kea-logo-100x70.png → doc/images/kea-logo-100x70.png
View File

Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 9.7 KiB

After

Width:  |  Height:  |  Size: 9.7 KiB

280
doc/sphinx/Makefile.am Normal file
View File

@ -0,0 +1,280 @@
EXTRA_DIST=
if GENERATE_DOCS
sphinxbuilddir=$(builddir)/_build
sphinxopts=
sphinxopts+=-v
sphinxopts+=-E
sphinxopts+=-a
sphinxopts+=-j auto
sphinxopts+=-c "${abs_srcdir}"
sphinxopts+=-D release="@PACKAGE_VERSION@"
sphinxopts+=-D version="@PACKAGE_VERSION@"
# TODO
#HTMLDOCS = kea-guide.html kea-messages.html
#DOCS = kea-guide.txt
#dist_doc_DATA = $(DOCS)
#dist_html_DATA = $(HTMLDOCS) kea-guide.css kea-logo-100x70.png
#dist_html_DATA = $(HTMLDOCS) _static/kea-logo-100x70.png
#doc_DATA = _build/singlehtml/kea-guide.html _build/singlehtml/_static/kea-logo-100x70.png
static_sources=
static_sources+=static/kea-imageonly-100bw.png
static_sources+=static/kea-logo-200.png
static_sources+=static/kea.css
# ARM
rst_arm_sources=
rst_arm_sources+=arm/admin.rst
rst_arm_sources+=arm/agent.rst
rst_arm_sources+=arm/api.rst
rst_arm_sources+=arm/classify.rst
rst_arm_sources+=arm/config-backend.rst
rst_arm_sources+=arm/config.rst
rst_arm_sources+=arm/congestion-handling.rst
rst_arm_sources+=arm/ctrl-channel.rst
rst_arm_sources+=arm/ddns.rst
rst_arm_sources+=arm/dhcp4-srv.rst
rst_arm_sources+=arm/dhcp6-srv.rst
rst_arm_sources+=arm/hammer.rst
rst_arm_sources+=arm/hooks-cb-cmds.rst
rst_arm_sources+=arm/hooks-class-cmds.rst
rst_arm_sources+=arm/hooks-ha.rst
rst_arm_sources+=arm/hooks-host-cache.rst
rst_arm_sources+=arm/hooks-lease-cmds.rst
rst_arm_sources+=arm/hooks-radius.rst
rst_arm_sources+=arm/hooks.rst
rst_arm_sources+=arm/hooks-stat-cmds.rst
rst_arm_sources+=arm/install.rst
rst_arm_sources+=arm/index.rst
rst_arm_sources+=arm/intro.rst
rst_arm_sources+=arm/keactrl.rst
rst_arm_sources+=arm/lease-expiration.rst
rst_arm_sources+=arm/lfc.rst
rst_arm_sources+=arm/logging.rst
rst_arm_sources+=arm/netconf.rst
rst_arm_sources+=arm/quickstart.rst
rst_arm_sources+=arm/shell.rst
rst_arm_sources+=arm/stats.rst
main_sources=$(rst_arm_sources) kea-messages.rst conf.py $(static_sources)
# mans # TODO perfdhcp and netconf should be conditional
rst_man_sources=
rst_man_sources+=man/kea-admin.8.rst
rst_man_sources+=man/kea-ctrl-agent.8.rst
rst_man_sources+=man/kea-dhcp4.8.rst
rst_man_sources+=man/kea-dhcp6.8.rst
rst_man_sources+=man/kea-dhcp-ddns.8.rst
rst_man_sources+=man/kea-lfc.8.rst
rst_man_sources+=man/kea-netconf.8.rst
rst_man_sources+=man/kea-shell.8.rst
rst_man_sources+=man/keactrl.8.rst
rst_man_sources+=man/perfdhcp.8.rst
man_sources=$(rst_man_sources) conf.py
man8s=$(foreach rst,$(rst_man_sources), $(sphinxbuilddir)/$(basename $(rst)))
EXTRA_DIST += $(main_sources) $(man_sources) system_messages.py
#DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml
#CLEANFILES = kea-guide.pdf kea-messages.pdf
mes_files=
mes_files+=$(top_srcdir)/src/hooks/dhcp/mysql_cb/mysql_cb_messages.mes
mes_files+=$(top_srcdir)/src/hooks/dhcp/lease_cmds/lease_cmds_messages.mes
mes_files+=$(top_srcdir)/src/hooks/dhcp/high_availability/ha_messages.mes
mes_files+=$(top_srcdir)/src/hooks/dhcp/stat_cmds/stat_cmds_messages.mes
mes_files+=$(top_srcdir)/src/hooks/dhcp/user_chk/user_chk_messages.mes
mes_files+=$(top_srcdir)/src/lib/config/config_messages.mes
mes_files+=$(top_srcdir)/src/lib/hooks/hooks_messages.mes
mes_files+=$(top_srcdir)/src/lib/dhcpsrv/dhcpsrv_messages.mes
mes_files+=$(top_srcdir)/src/lib/dhcpsrv/alloc_engine_messages.mes
mes_files+=$(top_srcdir)/src/lib/dhcpsrv/hosts_messages.mes
mes_files+=$(top_srcdir)/src/lib/http/http_messages.mes
mes_files+=$(top_srcdir)/src/lib/dhcp_ddns/dhcp_ddns_messages.mes
mes_files+=$(top_srcdir)/src/lib/database/db_messages.mes
mes_files+=$(top_srcdir)/src/lib/log/log_messages.mes
mes_files+=$(top_srcdir)/src/lib/log/logimpl_messages.mes
mes_files+=$(top_srcdir)/src/lib/log/tests/log_test_messages.mes
mes_files+=$(top_srcdir)/src/lib/process/process_messages.mes
mes_files+=$(top_srcdir)/src/lib/asiodns/asiodns_messages.mes
mes_files+=$(top_srcdir)/src/lib/eval/eval_messages.mes
mes_files+=$(top_srcdir)/src/bin/dhcp4/dhcp4_messages.mes
mes_files+=$(top_srcdir)/src/bin/agent/ca_messages.mes
mes_files+=$(top_srcdir)/src/bin/d2/d2_messages.mes
mes_files+=$(top_srcdir)/src/bin/dhcp6/dhcp6_messages.mes
mes_files+=$(top_srcdir)/src/bin/lfc/lfc_messages.mes
mes_files+=$(top_srcdir)/src/bin/netconf/netconf_messages.mes
all: pdf html mans
kea-messages.rst: $(mes_files) system_messages.py
./system_messages.py -o $@ $(mes_files)
pdf: $(main_sources)
$(SPHINXBUILD) -M latexpdf $(srcdir) $(sphinxbuilddir) $(sphinxopts)
html: $(main_sources)
$(SPHINXBUILD) -M html $(srcdir) $(sphinxbuilddir) $(sphinxopts)
$(man8s): mans
mans: $(man_sources)
$(SPHINXBUILD) -M man $(srcdir) $(sphinxbuilddir) $(sphinxopts)
install-data-local:
mkdir -p $(DESTDIR)$(docdir)
cp -r $(sphinxbuilddir)/html $(DESTDIR)$(docdir)
${INSTALL_DATA} $(sphinxbuilddir)/latex/kea-arm.pdf $(DESTDIR)$(docdir)
${INSTALL_DATA} $(sphinxbuilddir)/latex/kea-messages.pdf $(DESTDIR)$(docdir)
${MKDIR_P} ${DESTDIR}${mandir}/man8
${INSTALL_DATA} $(man8s) ${DESTDIR}${mandir}/man8/
uninstall-local:
rm -rf $(DESTDIR)$(docdir)
clean::
-rm -rf $(sphinxbuilddir)
.PHONY: all pdf html mans
endif
# There are several steps needed to document new API command:
#
# 1. edit docgen/cmds-list and add the new command
# 2. ./configure --enable-generate-docs
# 3. make - you need to build the sources first, am afraid. The reason why you
# need to do this is that the tool kea-docgen depends on libkea-cc as it
# loads JSON files. This means that the libs need to be built first.
# 4. (optional) run: make templates
# This will go through the list of commands listed in cmds-list
# and will check if there are corresponding JSON files in api/name.json
# If the file is missing, a new JSON will be created using template.
# If you dislike this generator, you can always use api/_template.json
# and copy it over under the name of a new command.
# 5. Edit api/command-name.json. If the command is provided by the daemon
# out of its own (and not via hook), simply delete the hook entry.
# If you don't want to provide command syntax (cmd-syntax key),
# any comments about the syntax (cmd-comment key) or response syntax
# (resp-syntax) or any comment about response (resp-comment), simply
# remove those unused keys. The generator will attempt to generate
# boilerplates for it.
# 6. Generate api.xml: make api
# 7. Rebuild User's Guide as usual: make guide
# This target will generate templates. There's no need to run it, unless
# new commands have been added or there are existing commands that are
# still not documented.
templates: docgen
docgen/generate-templates docgen/cmds-list
# This will generate the api.xml file using docgen generator. It will
# read the JSON files from api/ directory. Make sure they're up to date.
api: docgen
docgen/kea-docgen api/*.json
# This convenience target makes sure the docgen tool is built properly
docgen:
$(MAKE) -C docgen
# These are files that document our APIs. They're not really needed as the
# content is included in the api.xml, but may be useful for people who
# want to document the API.
EXTRA_DIST += api/build-report.json
EXTRA_DIST += api/cache-clear.json api/cache-get.json
EXTRA_DIST += api/cache-get-by-id.json api/cache-insert.json
EXTRA_DIST += api/cache-load.json api/cache-remove.json
EXTRA_DIST += api/cache-size.json api/cache-write.json
EXTRA_DIST += api/class-add.json api/class-del.json
EXTRA_DIST += api/class-get.json api/class-list.json
EXTRA_DIST += api/class-update.json
EXTRA_DIST += api/config-get.json api/config-reload.json
EXTRA_DIST += api/config-set.json api/config-test.json
EXTRA_DIST += api/config-write.json api/dhcp-disable.json
EXTRA_DIST += api/dhcp-enable.json api/ha-continue.json
EXTRA_DIST += api/ha-heartbeat.json api/ha-scopes.json
EXTRA_DIST += api/ha-sync.json api/lease4-add.json
EXTRA_DIST += api/lease4-del.json api/lease4-get-all.json
EXTRA_DIST += api/lease4-get.json api/lease4-update.json
EXTRA_DIST += api/lease4-wipe.json api/lease6-add.json
EXTRA_DIST += api/lease6-del.json api/lease6-get-all.json
EXTRA_DIST += api/lease6-get.json api/lease6-update.json
EXTRA_DIST += api/lease6-wipe.json api/leases-reclaim.json
EXTRA_DIST += api/libreload.json api/list-commands.json
EXTRA_DIST += api/network4-add.json api/network4-del.json
EXTRA_DIST += api/network4-get.json api/network4-list.json
EXTRA_DIST += api/network4-subnet-add.json api/network4-subnet-del.json
EXTRA_DIST += api/network6-add.json api/network6-del.json
EXTRA_DIST += api/network6-get.json api/network6-list.json
EXTRA_DIST += api/network6-subnet-add.json api/network6-subnet-del.json
EXTRA_DIST += api/remote-global-parameter4-del.json
EXTRA_DIST += api/remote-global-parameter4-get-all.json
EXTRA_DIST += api/remote-global-parameter4-get.json
EXTRA_DIST += api/remote-global-parameter4-set.json
EXTRA_DIST += api/remote-global-parameter6-del.json
EXTRA_DIST += api/remote-global-parameter6-get-all.json
EXTRA_DIST += api/remote-global-parameter6-get.json
EXTRA_DIST += api/remote-global-parameter6-set.json
EXTRA_DIST += api/remote-network4-del.json
EXTRA_DIST += api/remote-network4-get.json
EXTRA_DIST += api/remote-network4-list.json
EXTRA_DIST += api/remote-network4-set.json
EXTRA_DIST += api/remote-network6-del.json
EXTRA_DIST += api/remote-network6-get.json
EXTRA_DIST += api/remote-network6-list.json
EXTRA_DIST += api/remote-network6-set.json
EXTRA_DIST += api/remote-option-def4-del.json
EXTRA_DIST += api/remote-option-def4-get-all.json
EXTRA_DIST += api/remote-option-def4-get.json
EXTRA_DIST += api/remote-option-def4-set.json
EXTRA_DIST += api/remote-option-def6-del.json
EXTRA_DIST += api/remote-option-def6-get-all.json
EXTRA_DIST += api/remote-option-def6-get.json
EXTRA_DIST += api/remote-option-def6-set.json
EXTRA_DIST += api/remote-option4-global-del.json
EXTRA_DIST += api/remote-option4-global-get-all.json
EXTRA_DIST += api/remote-option4-global-get.json
EXTRA_DIST += api/remote-option4-global-set.json
EXTRA_DIST += api/remote-option6-global-del.json
EXTRA_DIST += api/remote-option6-global-get-all.json
EXTRA_DIST += api/remote-option6-global-get.json
EXTRA_DIST += api/remote-option6-global-set.json
EXTRA_DIST += api/remote-subnet4-del-by-id.json
EXTRA_DIST += api/remote-subnet4-del-by-prefix.json
EXTRA_DIST += api/remote-subnet4-get-by-id.json
EXTRA_DIST += api/remote-subnet4-get-by-prefix.json
EXTRA_DIST += api/remote-subnet4-list.json
EXTRA_DIST += api/remote-subnet4-set.json
EXTRA_DIST += api/remote-subnet6-del-by-id.json
EXTRA_DIST += api/remote-subnet6-del-by-prefix.json
EXTRA_DIST += api/remote-subnet6-get-by-id.json
EXTRA_DIST += api/remote-subnet6-get-by-prefix.json
EXTRA_DIST += api/remote-subnet6-list.json
EXTRA_DIST += api/remote-subnet6-set.json
EXTRA_DIST += api/reservation-add.json api/reservation-del.json
EXTRA_DIST += api/reservation-get.json api/reservation-get-all.json
EXTRA_DIST += api/reservation-get-page.json api/shutdown.json
EXTRA_DIST += api/statistic-get-all.json api/statistic-get.json
EXTRA_DIST += api/statistic-remove-all.json api/statistic-remove.json
EXTRA_DIST += api/statistic-reset-all.json api/statistic-reset.json
EXTRA_DIST += api/stat-lease4-get.json api/stat-lease6-get.json
EXTRA_DIST += api/subnet4-add.json api/subnet4-del.json
EXTRA_DIST += api/subnet4-get.json api/subnet4-list.json
EXTRA_DIST += api/subnet4-update.json
EXTRA_DIST += api/subnet6-add.json api/subnet6-del.json
EXTRA_DIST += api/subnet6-get.json api/subnet6-list.json
EXTRA_DIST += api/subnet6-update.json
EXTRA_DIST += api/_template.json api/version-get.json

0
doc/api/_template.json → doc/sphinx/api/_template.json
View File

0
doc/api/build-report.json → doc/sphinx/api/build-report.json
View File

0
doc/api/cache-clear.json → doc/sphinx/api/cache-clear.json
View File

0
doc/api/cache-get-by-id.json → doc/sphinx/api/cache-get-by-id.json
View File

0
doc/api/cache-get.json → doc/sphinx/api/cache-get.json
View File

0
doc/api/cache-insert.json → doc/sphinx/api/cache-insert.json
View File

0
doc/api/cache-load.json → doc/sphinx/api/cache-load.json
View File

0
doc/api/cache-remove.json → doc/sphinx/api/cache-remove.json
View File

0
doc/api/cache-size.json → doc/sphinx/api/cache-size.json
View File

0
doc/api/cache-write.json → doc/sphinx/api/cache-write.json
View File

0
doc/api/class-add.json → doc/sphinx/api/class-add.json
View File

0
doc/api/class-del.json → doc/sphinx/api/class-del.json
View File

0
doc/api/class-get.json → doc/sphinx/api/class-get.json
View File

0
doc/api/class-list.json → doc/sphinx/api/class-list.json
View File

0
doc/api/class-update.json → doc/sphinx/api/class-update.json
View File

0
doc/api/config-get.json → doc/sphinx/api/config-get.json
View File

0
doc/api/config-reload.json → doc/sphinx/api/config-reload.json
View File

0
doc/api/config-set.json → doc/sphinx/api/config-set.json
View File

0
doc/api/config-test.json → doc/sphinx/api/config-test.json
View File

0
doc/api/config-write.json → doc/sphinx/api/config-write.json
View File

0
doc/api/dhcp-disable.json → doc/sphinx/api/dhcp-disable.json
View File

0
doc/api/dhcp-enable.json → doc/sphinx/api/dhcp-enable.json
View File

0
doc/api/ha-continue.json → doc/sphinx/api/ha-continue.json
View File

0
doc/api/ha-heartbeat.json → doc/sphinx/api/ha-heartbeat.json
View File

0
doc/api/ha-scopes.json → doc/sphinx/api/ha-scopes.json
View File

0
doc/api/ha-sync.json → doc/sphinx/api/ha-sync.json
View File

0
doc/api/lease4-add.json → doc/sphinx/api/lease4-add.json
View File

0
doc/api/lease4-del.json → doc/sphinx/api/lease4-del.json
View File

0
doc/api/lease4-get-all.json → doc/sphinx/api/lease4-get-all.json
View File

0
doc/api/lease4-get.json → doc/sphinx/api/lease4-get.json
View File

0
doc/api/lease4-update.json → doc/sphinx/api/lease4-update.json
View File

0
doc/api/lease4-wipe.json → doc/sphinx/api/lease4-wipe.json
View File

0
doc/api/lease6-add.json → doc/sphinx/api/lease6-add.json
View File

0
doc/api/lease6-del.json → doc/sphinx/api/lease6-del.json
View File

0
doc/api/lease6-get-all.json → doc/sphinx/api/lease6-get-all.json
View File

0
doc/api/lease6-get.json → doc/sphinx/api/lease6-get.json
View File

0
doc/api/lease6-update.json → doc/sphinx/api/lease6-update.json
View File

0
doc/api/lease6-wipe.json → doc/sphinx/api/lease6-wipe.json
View File

0
doc/api/leases-reclaim.json → doc/sphinx/api/leases-reclaim.json
View File

0
doc/api/libreload.json → doc/sphinx/api/libreload.json
View File

0
doc/api/list-commands.json → doc/sphinx/api/list-commands.json
View File

0
doc/api/network4-add.json → doc/sphinx/api/network4-add.json
View File

0
doc/api/network4-del.json → doc/sphinx/api/network4-del.json
View File

0
doc/api/network4-get.json → doc/sphinx/api/network4-get.json
View File

0
doc/api/network4-list.json → doc/sphinx/api/network4-list.json
View File

0
doc/api/network4-subnet-add.json → doc/sphinx/api/network4-subnet-add.json
View File

0
doc/api/network4-subnet-del.json → doc/sphinx/api/network4-subnet-del.json
View File

0
doc/api/network6-add.json → doc/sphinx/api/network6-add.json
View File

0
doc/api/network6-del.json → doc/sphinx/api/network6-del.json
View File

0
doc/api/network6-get.json → doc/sphinx/api/network6-get.json
View File

0
doc/api/network6-list.json → doc/sphinx/api/network6-list.json
View File

0
doc/api/network6-subnet-add.json → doc/sphinx/api/network6-subnet-add.json
View File

0
doc/api/network6-subnet-del.json → doc/sphinx/api/network6-subnet-del.json
View File

0
doc/api/remote-global-parameter4-del.json → doc/sphinx/api/remote-global-parameter4-del.json
View File

0
doc/api/remote-global-parameter4-get-all.json → doc/sphinx/api/remote-global-parameter4-get-all.json
View File

Some files were not shown because too many files have changed in this diff Show More