Commit 60b0e6e7 authored by Michal Nowikowski's avatar Michal Nowikowski
Browse files

initial conversion of kea guide from docbook to rst/sphinx

parent aa7ecb92
......@@ -4,3 +4,4 @@
\ No newline at end of file
# generated documentation
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
DOCBOOK = kea-guide.xml intro.xml quickstart.xml install.xml admin.xml config.xml
DOCBOOK += config-backend.xml keactrl.xml dhcp4-srv.xml dhcp6-srv.xml lease-expiration.xml
DOCBOOK += logging.xml ddns.xml hooks.xml hooks-class-cmds.xml hooks-cb-cmds.xml
DOCBOOK += hooks-ha.xml hooks-host-cache.xml hooks-lease-cmds.xml hooks-radius.xml
DOCBOOK += hooks-stat-cmds.xml lfc.xml stats.xml ctrl-channel.xml classify.xml shell.xml
DOCBOOK += agent.xml netconf.xml api.xml congestion-handling.xml hammer.xml
EXTRA_DIST = $(DOCBOOK) kea-docbook.xsl
DISTCLEANFILES = $(HTMLDOCS) $(DOCS) kea-messages.xml
$(top_builddir)/tools/system_messages -o $@ \
`find $(top_srcdir) -name "*.mes" -print`
# This is not a "man" manual, but reuse this for now for docbook.
kea-guide.html: $(DOCBOOK)
@XSLTPROC@ --novalid --xinclude @NONET@ \
--path $(top_builddir)/doc \
-o $@ \
--stringparam section.autolabel 1 \
--stringparam section.label.includes.component.label 1 \
--stringparam html.stylesheet kea-guide.css \
$(srcdir)/kea-docbook.xsl \
kea-guide.txt: kea-guide.html
@ELINKS@ -dump -no-numbering -no-references kea-guide.html > $@
kea-messages.html: kea-messages.xml
@XSLTPROC@ --novalid --xinclude @NONET@ \
--path $(top_builddir)/doc \
-o $@ \
--stringparam generate.toc "book toc" \
--stringparam html.stylesheet kea-guide.css \
$(srcdir)/kea-docbook.xsl \
@echo Doc generation disabled. Creating dummy $@. Configure with --enable-generate-docs to enable it.
@echo Doc generation disabled. Remove this file, configure with --enable-generate-docs, and rebuild Kea > $@
CLEANFILES = kea-guide.pdf kea-messages.pdf
DBLATEX_FLAGS = --xslt-opts=--path --xslt-opts=$(abs_top_builddir)/doc \
-P -P latex.output.revhistory=0 \
-P term.breakline=1 -P \
-P imagedata.default.scale="maxwidth=50px,maxheight=35px"
pdf: kea-guide.pdf kea-messages.pdf
kea-guide.pdf: $(DOCBOOK)
@DBLATEX@ $(DBLATEX_FLAGS) kea-guide.xml
kea-messages.pdf: kea-messages.xml
@DBLATEX@ $(DBLATEX_FLAGS) kea-messages.xml
pdf kea-guide.pdf kea-messages.pdf:
@echo Install dblatex tool and rerun ./configure to be able to generate documentation in PDF format.
sphinxbuild = sphinx-build
sphinxopts = -E
kea-guide.pdf: $(rst_sources)
@$(sphinxbuild) -M latexpdf $(srcdir) $(builddir)/_build $(sphinxopts)
kea-guide.html: $(rst_sources)
@$(sphinxbuild) -M singlehtml $(srcdir) $(builddir)/_build $(sphinxopts)
EXTRA_DIST = $(rst_sources)
# TODO: here should ba added some stuff for DIST, etc to be consumed by automake/autoconf
This diff is collapsed.
.. _kea-ctrl-agent:
The Kea Control Agent
.. _agent-overview:
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
`??? <#ctrl-channel>`__.
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 `Kea Developer's
Guide <>`__.
The CA processes received commands according to the following algorithm:
- Pass command into any installed hooks (regardless of service
value(s)). If the command is handled by a hook, return the response.
- If the service specifies one more or services, forward the command to
the specified services and return the accumulated responses.
- If the service is not specified or is an empty list, handle the
command if the CA supports it.
.. _agent-configuration:
The following example demonstrates the basic CA configuration.
"Control-agent": {
"http-host": "",
"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/",
"parameters": {
"param1": "foo"
} ],
"loggers": [ {
"name": "kea-ctrl-agent",
"severity": "INFO"
} ]
The ``http-host`` and ``http-port`` 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
````. If these parameters are not specified, the
default URL is
As mentioned in `Overview <#agent-overview>`__, the CA can forward
received commands to the Kea servers for processing. For example,
``config-get`` is sent to retrieve the configuration of one of the Kea
services. When the CA receives this command, including a ``service``
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 ``service`` parameter and the general structure of commands can be
found in `??? <#ctrl-channel>`__.
The CA uses UNIX domain sockets to forward control commands and receive
responses from other Kea services. The ``dhcp4``, ``dhcp6``, and ``d2``
maps specify the files to which UNIX domain sockets are bound. In the
configuration above, the CA will connect to the DHCPv4 server via
``/path/to/the/unix/socket-v4`` 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
`??? <#dhcp4-ctrl-channel>`__, `??? <#dhcp6-ctrl-channel>`__ and
`??? <#d2-ctrl-channel>`__ to learn how the socket configuration is
specified for the DHCPv4, DHCPv6 and D2 services.
"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.
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
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.
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 ``hooks-libraries`` list contains the list of hooks libraries that
should be loaded by the CA, along with their configuration information
specified with ``parameters``.
Please consult `??? <#logging>`__ for the details how to configure
logging. The CA's root logger's name is ``kea-ctrl-agent``, as given in
the example above.
.. _agent-secure-connection:
Secure Connections
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 ``doc/examples/https/`` directory.
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.
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.
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.
# 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" }' \
# nginx configuration starts here.
events {
http {
# HTTPS server
server {
# Use default HTTPS port.
listen 443 ssl;
# Set server name.
# 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, forward the
# requests to
location /kea {
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.
When you use an HTTP client without TLS support as ``kea-shell``, you
can use an HTTP/HTTPS translator such as stunnel in client mode. A
sample configuration is provided in the ``doc/examples/https/shell/``
.. _agent-launch:
Starting the Control Agent
The CA is started by running its binary and specifying the configuration
file it should use. For example:
$ ./kea-ctrl-agent -c /usr/local/etc/kea/kea-ctrl-agent.conf
It can be started by keactrl as well (see `??? <#keactrl>`__).
.. _agent-clients:
Connecting to the Control Agent
For an example of a tool that can take advantage of the RESTful API, see
`??? <#kea-shell>`__.
This diff is collapsed.
This diff is collapsed.
# -*- coding: utf-8 -*-
# Configuration file for the Sphinx documentation builder.
# This file does only contain a selection of the most common options. For a
# full list see the documentation:
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'Kea Administrator Reference Manual'
copyright = '2019, Internet Systems Consortium'
author = 'Internet Systems Consortium'
# The short X.Y version
version = '1.6'
# The full version, including alpha/beta/rc tags
release = '1.6.0'
# -- General configuration ---------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
# source_suffix = ['.rst', '.md']
source_suffix = '.rst'
# The master toctree document.
master_doc = 'kea-guide'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
language = None
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = None
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'alabaster'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
html_theme_options = {
"logo": "kea-logo-100x70.png",
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Custom sidebar templates, must be a dictionary that maps document names
# to template names.
# The default sidebars (for documents that don't match any pattern) are
# defined by theme itself. Builtin themes are using these templates by
# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
# 'searchbox.html']``.
# html_sidebars = {}
# -- Options for HTMLHelp output ---------------------------------------------
# Output file base name for HTML help builder.
htmlhelp_basename = 'KeaAdministratorReferenceManualdoc'
# -- Options for LaTeX output ------------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
# 'preamble': '',
# Latex figure (float) alignment
# 'figure_align': 'htbp',
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'KeaAdministratorReferenceManual.tex', 'Kea Administrator Reference Manual Documentation',
'Kea Team', 'manual'),
# -- Options for manual page output ------------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'keaadministratorreferencemanual', 'Kea Administrator Reference Manual Documentation',
[author], 1)
# -- Options for Texinfo output ----------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'KeaAdministratorReferenceManual', 'Kea Administrator Reference Manual Documentation',
author, 'KeaAdministratorReferenceManual', 'One line description of project.',
# -- Options for Epub output -------------------------------------------------
# Bibliographic Dublin Core info.
epub_title = project
# The unique identifier of the text. This can be a ISBN number
# or the project homepage.
# epub_identifier = ''
# A unique identification for the text.
# epub_uid = ''
# A list of files that should not be packed into the epub file.
epub_exclude_files = ['search.html']
# -- Extension configuration -------------------------------------------------
# -- Options for todo extension ----------------------------------------------
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True
.. _config-backend:
Kea Configuration Backend
.. _cb-applicability:
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.
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.
A good example is a pair of the Kea DHCP servers which can be configured
to support High Availability as described in
`??? <#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.
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.
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.