Databases and Database Version Numbers
======================================
-Kea may be configured to use a database as a storage for leases, a
+Kea may be configured to use a database as a storage for leases or as 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
+assignments of addresses, prefixes, options, etc.). Kea
+updates introduce changes to the database schemas to faciliate new
features and correct discovered issues with the existing schemas.
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.
+checks for this by examining the version of the 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
PostgreSQL.
Backend versions are specified in a major.minor format. The minor number
-is increased when there are backward-compatible changes introduced; for
+is increased when there are backwards-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
+introduce 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
.. table:: List of available backends
- +-------------+-------------+-------------+-------------+-------------+
- | Feature | Memfile | MySQL | PostgreSQL | CQL |
- | | | | | (Cassandra) |
- +=============+=============+=============+=============+=============+
- | Status | Stable | Stable | Stable | Experimenta |
- | | | | | l |
- +-------------+-------------+-------------+-------------+-------------+
- | Data format | CSV file | SQL RMDB | SQL RMDB | NoSQL |
- | | | | | database |
- | | | | | (Cassandra) |
- +-------------+-------------+-------------+-------------+-------------+
- | Leases | yes | yes | yes | yes |
- +-------------+-------------+-------------+-------------+-------------+
- | Host | no | yes | yes | yes |
- | Reservation | | | | |
- | s | | | | |
- +-------------+-------------+-------------+-------------+-------------+
- | Options | no | yes | yes | yes |
- | defined on | | | | |
- | per host | | | | |
- | basis | | | | |
- +-------------+-------------+-------------+-------------+-------------+
- | Configurati | no | yes | no | no |
- | on | | | | |
- | Backend | | | | |
- +-------------+-------------+-------------+-------------+-------------+
+ +---------------+----------------+----------------+---------------+--------------+
+ | Feature | Memfile | MySQL | PostgreSQL | CQL |
+ | | | | | (Cassandra) |
+ +===============+================+================+===============+==============+
+ | Status | Stable | Stable | Stable | Experimental |
+ | | | | | |
+ +---------------+----------------+----------------+---------------+--------------+
+ | Data format | CSV file | SQL RMDB | SQL RMDB | NoSQL |
+ | | | | | database |
+ | | | | | (Cassandra) |
+ +---------------+----------------+----------------+---------------+--------------+
+ | Leases | yes | yes | yes | yes |
+ +---------------+----------------+----------------+---------------+--------------+
+ | Host | no | yes | yes | yes |
+ | Reservations | | | | |
+ | | | | | |
+ +---------------+----------------+----------------+---------------+--------------+
+ | Options | no | yes | yes | yes |
+ | defined on | | | | |
+ | per host | | | | |
+ | basis | | | | |
+ +---------------+----------------+----------------+---------------+--------------+
+ | Configuration | no | yes | no | no |
+ | Backend | | | | |
+ | | | | | |
+ +---------------+----------------+----------------+---------------+--------------+
memfile
-------
-The memfile backend is able to store lease information, but is not able
-to store host reservation details; these must be stored in the
+The memfile backend is able to store lease information, but cannot
+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.)
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
-`??? <#kea-lfc>`__ for more information.
+:ref:`The LFC Process <kea-lfc>` for more information.
.. _mysql-database:
-----
MySQL is able to store leases, host reservations, options defined on a
-per-host basis and a subset of the server configuration parameters
+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.
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;
-``kea-admin`` is not able to do this for you.
+``kea-admin`` cannot do this for you.
To create the database:
mysql> GRANT ALL ON database-name.* TO 'user-name'@'localhost';
(user-name and password are the user ID and password you are using to
- allow Kea's access to the MySQL instance. All apostrophes in the
+ allow Kea access to the MySQL instance. All apostrophes in the
command lines above are required.)
4. At this point, you may elect to create the database tables.
$ kea-admin lease-init mysql -u database-user -p database-password -n database-name
-(Do not do this if you did create the tables in Step 4.) ``kea-admin``
+Do not do this if you did create the tables in Step 4. ``kea-admin``
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
$ kea-admin lease-version mysql -u database-user -p database-password -n database-name
-(See `Databases and Database Version Numbers <#kea-database-version>`__
+(See :ref:`Databases and Database Version Numbers <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.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The PostgreSQL database schema can be upgraded using the same tool and
-commands as described in `Upgrading a MySQL Database from an Earlier
-Version of Kea <#mysql-upgrade>`__, with the exception that the "pgsql"
+commands as described in :ref:`Upgrading a MySQL Database from an Earlier
+Version of Kea <mysql-upgrade>`, with the exception that the "pgsql"
database backend type must be used in the commands.
Use the following command to check the current schema version:
$ kea-admin lease-init cql -n database-name
-(Do not do this if you did create the tables in Step 4.) ``kea-admin``
+Do not do this if you did create the tables in Step 4. ``kea-admin``
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
$ kea-admin lease-version cql -n database-name
-(See `Databases and Database Version Numbers <#kea-database-version>`__
+(See :ref:`Databases and Database Version Numbers <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.
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 `??? <#read-only-database-configuration4>`__ and
-`??? <#read-only-database-configuration6>`__ describe when such
-configuration may be required and how to configure Kea to operate in
+Sections :ref:`Using Read-Only Databases for Host Reservations (DHCPv4) <read-only-database-configuration4>` and
+:ref:`Using Read-Only Databases for Host Reservations (DHCPv6) <read-only-database-configuration6>` describe when such
+a configuration may be required, and how to configure Kea to operate in
this way.
Limitations Related to the Use of SQL Databases
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
+doesn't accept timestamps beyond 2147483647 seconds (the 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
-------------
Kea Configuration Backend (abbreviated as CB) is a feature first
-introduced in 1.6.0 release, which provides Kea servers with the ability
+introduced in the 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
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
+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
+A good example of a use case for the CB is a pair of Kea DHCP servers which can be configured
to support High Availability as described in
-`??? <#high-availability-library>`__. The configurations of both servers
+:ref:`ha: High Availability <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
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
+advantage that any modifications to the configuration in the database are
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.
+in deployments including a large number of DHCP servers, possibly
+using a common lease database to provide redundancy. New servers can
+be added to the pool frequently to fulfill growing scalability
+requirements. Adding a new server does not require replicating the
+entire configuration to the new server when a common database is used.
Using the database as a configuration repository for Kea servers also
brings other benefits, such as:
-- an ability to use database specific tools to access the configuration
+- the ability to use database specific tools to access the configuration
information,
-- an ability to create customized statistics based on the information
- stored in the database,
+- the ability to create customized statistics based on the information
+ stored in the database, and
-- an ability to backup the configuration information using the database
- builtin replication mechanisms.
+- the ability to backup the configuration information using the database's
+ built-in replication mechanisms.
.. _cb-limitations:
CB Capabilities and Limitations
-------------------------------
-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
+Kea CB, introduced in the 1.6.0 release,
+comes with a number of limitations as a 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:
+subsequent releases. In this section we present the capabilities and limitations of the
+CB in the current Kea 1.6.0 release:
-- Kea CB is currently supported for the MySQL database only.
+- Kea CB is supported for the MySQL database only.
-- Kea CB is only supported for DHCPv4 and DHCPv6 servers. Neither
- Control Agent nor D2 deamon can be configured via the database.
+- Kea CB is only supported for DHCPv4 and DHCPv6 servers. Neither the
+ Control Agent nor the D2 daemon can be configured via the database.
-- Configuration to be stored for the DHCP servers includes: global
- parameters, option definitions, global options, shared networks and
+- Potential configurations to be stored for the DHCP servers include: 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
+ database and must be configured via the JSON
configuration file.
-- It is not supported to differentiate configurations of multiple DHCP
- servers within the same database. All servers conected to the
+- Different configurations of multiple DHCP
+ servers cannot be stored within the same database; all servers connected to the
particular database instance share the configuration stored in this
- database. This limitation will be removed in Kea 1.6.0 final release.
+ database. This limitation is expected to be removed in the Kea 1.6.0 final release.
..
**Note**
- We strongly recommend to not duplicate the configuration information
+ We strongly recommend against duplication of 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.
+ for the DHCP server, please store them in either the configuration backend
+ or in the configuration file, not both. Storing some
+ subnets in the database and others in the file may put you at risk of
+ potential configuration conflicts. Note that the configuration instructions from
+ the database take precedence over instructions from the file,
+ so it is possible that parts of the configuration specified in the
+ file may be overridden if contradicted by information in the database.
**Note**
- It is recommended that ``subnet_cmds`` hooks library is not used to
+ It is recommended that the ``subnet_cmds`` hooks library not be used to
manage the subnets when the configuration backend is used as a source
of information about the subnets. The ``subnet_cmds`` hooks library
- modifies the local subnets configuration (in the server's memory),
+ modifies the local subnets configuration in the server's memory,
not in the database. Use the ``cb_cmds`` hooks library to manage the
subnets information in the database instead.
required. The ``mysql_cb`` 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 ``--with-mysql``
-configuration switch is used during Kea build. The MySQL C client
-libraries must be installed as explained in the
-`??? <#dhcp-install-configure>`__.
+configuration switch is used during the Kea build. The MySQL C client
+libraries must be installed, as explained in
+:ref:`DHCP Database Installation and Configuration <dhcp-install-configure>`.
**Note**
Any existing MySQL schema must be upgraded to the latest schema
- required by the particular Kea version using ``kea-admin`` tool
- described in `??? <#kea-admin>`__.
+ required by the particular Kea version using the ``kea-admin`` tool,
+ as described in `The kea-admin Tool <kea-admin>`.
-The ``cb_cmds`` premium hooks library is available to ISC paid supported
-customers, which provides a complete set of commands to manage the
+The ``cb_cmds`` premium hooks library, which is available to ISC's paid support
+customers, 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 instance. It is still
+be attached to both DHCPv4 and DHCPv6 server instances. It is still
possible to manage the configuration information without the ``cb_cmds``
-hooks library with commonly available tools such as MySQL Workbench or
-command line MySQL client, by directly working with the database.
+hooks library with commonly available tools, such as MySQL Workbench or
+the command-line MySQL client, by directly working with the database.
-Refer to the `??? <#cb-cmds-library>`__ for the details regarding the
+Refer to :ref:`cb_cmds: Configuration Backend Commands <cb-cmds-library>` for the details regarding the
``cb_cmds`` hooks library.
-The DHCPv4 and DHCPv6 server specific configuration of the CB as well as
-the list of supported configuration parameters can be found in the
-`??? <#dhcp4-cb>`__ and `??? <#dhcp6-cb>`__ respectively.
+The DHCPv4 and DHCPv6 server-specific configurations of the CB, as well as
+the list of supported configuration parameters, can be found in
+:ref:`Configuration Backend in DHCPv4 <dhcp4-cb>` and :ref:`Configuration Backend in DHCPv6 <dhcp6-cb>` respectively.
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 `??? <#ctrl-channel>`__) and for
+commands over the Management API (see :ref:`Management API <ctrl-channel>`) and for
communicating between DHCP servers and the DDNS update daemon.
Typical usage assumes that the servers are started from the command
Configuration files for the DHCPv4, DHCPv6, DDNS, Control Agent, and
Netconf modules are defined in an extended JSON format. Basic JSON is
-defined in `RFC 7159 <http://tools.ietf.org/html/rfc7159>`__ and `ECMA
-404 <http://www.ecma-international.org/publications/standards/Ecma-404.htm>`__.
+defined in :ref:`RFC 7159 <http://tools.ietf.org/html/rfc7159>` and :ref:`ECMA
+404 <http://www.ecma-international.org/publications/standards/Ecma-404.htm>`.
In particular, the only boolean values allowed are true or false (all
lowercase). The capitalized versions (True or False) are not accepted.
commenting can span multiple lines.
- File inclusion: JSON files can include other JSON files by using a
- statement of the form <?include "file.json"?>.
+ statement of the form \<?include "file.json"?\>.
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.
+the "Dhcp4", "Dhcp6", "DhcpDdns", "Control-agent", and "Netconf" objects.
It is possible to define additional elements but they will be ignored.
A very simple configuration for DHCPv4 could look like this:
**Note**
The "Logging" element is removed in Kea 1.6.0 and its contents (the
- "loggers" object) moved inside the configuration objects (maps) for
+ "loggers" object) moved inside the configuration objects (maps) for the
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
+ release; it will be possible to specify the "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.
Hammer Building Tool
====================
-An optionl building tool called Hammer was introduced with Kea 1.6.0. It
+An optional 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
+git repository. This tool was developed primarily for internal purposes
and ISC cannot guarantee its proper operation. If you decide to use it,
please do so with care.
Use of this tool is completely optional. Everything it does can be
done manually.
-The first time user is strongly encouraged to look at Hammer's built in
+The first-time user is strongly encouraged to look at Hammer's built-in
help:
::
It will list available parameters.
-Hammer is able to set up various operating systems running eiter in LXC
-or in VirtualBox. To list of supported systems, use
+Hammer is able to set up various operating systems running either in LXC
+or in VirtualBox. To list of supported systems, use the
``supported-systems`` command:
::
- 12.0: virtualbox
-It is also possible to run build locally, in current system (if the OS
+It is also possible to run the build locally, in the current system (if the OS
is supported).
-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:
+First, you must install the Hammer dependencies: Vagrant
+and either VirtualBox or LXC. To make life easier, Hammer can install
+Vagrant and the required Vagrant plugins using the command:
::
VirtualBox and LXC need to be installed manually.
-Basic functionality provided by Hammer is preparing building environment
-and performing actual build and running unit tests locally, in current
+The basic functions provided by Hammer are to prepare the build environment
+and perform the actual build, and to run the unit tests locally in the current
system. This can be achieved by running the command:
::
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.
+documentation, install it locally, and run unit tests.
-To exclude installation and generating docs do:
+To exclude the installation and generation of docs, type:
::
./hammer.py build -p local -x install docs
The basic scope can be extended by: mysql, pgsql, cql, native-pkg,
-radius, shell, forge.
+radius, shell, and forge.
**Note**
- For build Kea locally installing Hammer dependencies like Vagrant is
+ To build Kea locally, Hammer dependencies like Vagrant are
not needed.
-Hammer can be told to set up a new virtual machine with specified
-operating system and not running the build:
+Hammer can be told to set up a new virtual machine with a specified
+operating system, without the build:
::
./hammer.py prepare-system -p virtualbox -s freebsd -r 12.0
-This way we can prepare a system for our own use. To get to such system
-using SSH invoke:
+This way we can prepare a system for our own use. To get to such a system
+using SSH, invoke:
::
./hammer.py ssh -p virtualbox -s freebsd -r 12.0
It is possible to speed up subsequent Hammer builds. To achieve this
-Hammer employs `ccache <https://ccache.samba.org/>`__. 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.
+Hammer employs :ref:`ccache <https://ccache.samba.org/>`. During
+compilation, ccache stores objects in a shared folder. In subsequent runs,
+instead of doing an actual compilation, ccache returns the stored earlier
+objects. The cache with these objects for reuse needs to be stored outside of VM
+or LXC. To indicate the folder, you must indicate the --ccache-dir
+parameter for Hammer. In the indicated folder, there are separate stored objects for each target
+operating system.
::
**Note**
- For now ccache is only supported for LXC provider in Hammer. Support
- for VirtualBox will be added later.
+ ccache is currently only supported for LXC in Hammer; support
+ for VirtualBox may be added later.
For more information check:
.. _build-requirements:
-Building Requirements
+Build Requirements
=====================
In addition to the run-time requirements (listed in
-`??? <#required-software>`__), building Kea from source code requires
+:ref:`Required Software at Run-Time <required-software>`), building Kea from source code requires
various development include headers and program development tools.
**Note**
Building from source code requires the following software installed on
the system:
-- Boost C++ Libraries (http://www.boost.org/). The oldest Boost version
+- Boost C++ libraries (https://www.boost.org/). 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.
- log4cplus (at least version 1.0.3) development include headers.
- 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
+ The Kea build has been checked with GCC g++ 4.8.5 and some later versions,
and Clang 800.0.38 and some later versions.
-- The development tools automake, libtool, pkg-config.
+- The development tools automake, libtool, and pkg-config.
- The MySQL client and the client development libraries, when using the
--with-mysql configuration flag to build the Kea MySQL database
later) are needed to connect to a Sysrepo database. (This is
specified using the --with-sysrepo switch when running "configure".)
-- googletest (version 1.8 or later), when using the --with-gtest
+- googletest (version 1.8 or later) is required when using the --with-gtest
configuration option to build the unit tests.
- The documentation generation tools elinks, docbook-xsl, libxslt, and
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 (https://gitlab.isc.org/isc-projects/kea). This
+Gitlab repository at https://gitlab.isc.org/isc-projects/kea. This
section describes how to build Kea from the source code.
Download Tar File
**Note**
- When building from source code retrieved via Git, additional software
+ 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.
-The latest development code is available on Gitlab (see
+The latest development code is available on GitLab (see
https://gitlab.isc.org/isc-projects/kea). The Kea source is public and
development is done in the “master” branch.
$ git clone https://gitlab.isc.org/isc-projects/kea.git
The code checked out from the git repository does not include the
-generated configure script, Makefile.in files, nor their related build
+generated configure script, the Makefile.in files, nor their related build
files. They can be created by running ``autoreconf`` with the
``--install`` switch. This will run ``autoconf``, ``aclocal``,
``libtoolize``, ``autoheader``, ``automake``, and related commands.
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
-`Contributor's
-Guide <https://gitlab.isc.org/isc-projects/kea/wikis/contributor's-guide>`__.
-The `Kea Developer's
-Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/>`__ contains more
+:ref:`Contributor's
+Guide <https://gitlab.isc.org/isc-projects/kea/blob/master/contributors-guide.md>`.
+The :ref:`Kea Developer's
+Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/>` contains more
information about the process, as well as describes the requirements for
contributed code to be accepted by ISC.
$ ./configure
Run ``./configure`` with the ``--help`` switch to view the different
-options. Some commonly-used options are:
+options. Some commonly used options are:
--prefix
Define the installation location (the default is ``/usr/local``).
--with-botan-config
Specify the path to the botan-config script to build with Botan for
- cryptographic functions. It is prefered to use OpenSSL (see below).
+ cryptographic functions. It is preferable to use OpenSSL (see below).
--with-openssl
Replace Botan by the OpenSSL the cryptographic library. By default
found, it searches for OpenSSL. Normally this is not necessary.
--enable-shell
- Build the optional ``kea-shell`` tool (more in `??? <#kea-shell>`__).
+ Build the optional ``kea-shell`` tool (more in :ref:`The Kea Shell" <kea-shell>`).
The default is to not build it.
--enable-perfdhcp
**Note**
For instructions concerning the installation and configuration of
- database backends for Kea, see `DHCP Database Installation and
- Configuration <#dhcp-install-configure>`__.
+ database backends for Kea, see :ref:`DHCP Database Installation and
+ Configuration <dhcp-install-configure>`.
-There are also many additional options that are typically not used by
+There are also many additional options that are typically not necessary for
regular users. However, they may be useful for package maintainers,
-developers or people who want to extend Kea code or send patches:
+developers, or people who want to extend Kea code or send patches:
--with-gtest, --with-gtest-source
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 ` <https://github.com/google/googletest>`__.)
+ from https://github.com/google/googletest.)
--enable-generate-docs
Enable the rebuilding Kea documentation. ISC publishes Kea
- documentation for each release. However, in some cases you may want
+ 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
+ docs, or want to generate new ones 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
+ docbook.xsl, from the Internet. If you want to use the
+ Internet anyway, please set the XSLTPROC_NET environment variable in
configure to any non-empty value, e.g.
::
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
+ However, if you change anything in the parses (such as adding a new
parameter), you will need to use flex and bison to regenerate
parsers. This option lets you do that.
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
+ you change anything in a .mes file (such as adding a new message), you
will need to build and use the Kea message compiler. This option lets
you do that.
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 ` <https://github.com/google/benchmark>`__.)
+ can be downloaded from https://github.com/google/benchmark.)
This support is experimental.
For example, the following command configures Kea to find the Boost
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
+be used to store the lease information. 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
**Note**
- When unit tests are built with Kea (the --with-gtest configuration
+ When unit tests are built with Kea (i.e. 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 `Kea Developer's
- Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/>`__.
+ found in the :ref:`Kea Developer's
+ Guide <https://jenkins.isc.org/job/Kea_doc/doxygen/>`.
Building with MySQL Support
---------------------------
Install MySQL according to the instructions for your system. The client
development libraries must be installed.
-Build and install Kea as described in `Installation <#installation>`__,
+Build and install Kea as described in :ref:`Installation <installation>`,
with the following modification. To enable the MySQL database code, at
-the "configure" step (see `Configure Before the Build <#configure>`__),
+the "configure" step (see :ref:`Configure Before the Build <configure>`),
the --with-mysql switch should be specified:
::
./configure [other-options] --with-mysql=path-to-mysql_config
-See `??? <#mysql-database-create>`__ for details regarding MySQL
+See :ref:`First-Time Creation of the MySQL Database <mysql-database-create>` for details regarding MySQL
database configuration.
Building with PostgreSQL support
client development libraries must be installed. Client development
libraries are often packaged as "libpq".
-Build and install Kea as described in `Installation <#installation>`__,
+Build and install Kea as described in :ref:`Installation <installation>`,
with the following modification. To enable the PostgreSQL database code,
-at the "configure" step (see `Configure Before the
-Build <#configure>`__), the --with-pgsql switch should be specified:
+at the "configure" step (see :ref:`Configure Before the
+Build <configure>`), the --with-pgsql switch should be specified:
::
./configure [other-options] --with-pgsql=path-to-pg_config
-See `??? <#pgsql-database-create>`__ for details regarding PostgreSQL
+See :ref:`First-Time Creation of the PostgreSQL Database <pgsql-database-create>` for details regarding PostgreSQL
database configuration.
Building with CQL (Cassandra) Support
Install Cassandra according to the instructions for your system. The
Cassandra project website contains useful pointers:
-http://cassandra.apache.org.
+https://cassandra.apache.org.
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 `Installation <#installation>`__. To enable the
-Cassandra (CQL) database code, at the "configure" step (see `Configure
-Before the Build <#configure>`__), do:
+Kea as described in :ref:`Installation <installation>`. To enable the
+Cassandra (CQL) database code, at the "configure" step (see :ref:`Configure
+Before the Build <configure>`), enter:
::
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;
+Before using it, please create a cql_config_defines.sh file in the same
+directory (there is an example available in cql_config_define.sh.sample;
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.
-Build and install Kea as described in `Installation <#installation>`__,
+Build and install Kea as described in :ref:`Installation <installation>`,
with the following modification. To enable the Cassandra (CQL) database
-code, at the "configure" step (see `Configure Before the
-Build <#configure>`__), do:
+code, at the "configure" step (see :ref:`Configure Before the
+Build <configure>`), enter:
::
.. _intro:
-***********************
-Chapter 1. Introduction
-***********************
+************
+Introduction
+************
Kea is the next generation of DHCP software developed by ISC. It
supports both DHCPv4 and DHCPv6 protocols along with their extensions,
This guide covers Kea version KEAVERSION.
-1.1 Supported Platforms
-=======================
+Supported Platforms
+===================
Kea is officially supported on CentOS, Fedora, Ubuntu, Debian, and
FreeBSD systems. It is also likely to work on many other platforms.
.. _required-software:
-1.2 Required Software at Run-time
-=================================
+Required Software at Run-Time
+=============================
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
-`Section 3.3, "Building Requirements" <#build-requirements>`__.)
+software separately. (For the build requirements, also see :ref:`Build Requirements <build-requirements>`.)
- Kea supports two cryptographic libraries: Botan and OpenSSL. Only one
of them is required to be installed during compilation. Kea uses 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 `Section 20.2, “Installing NETCONF” <#netconf-install>`__.
+ more detail in :ref: `Installing NETCONF <netconf-install>`.
.. _kea_software:
-1.3 Kea Software
-================
+Kea Software
+============
Kea is modular. Part of this modularity is accomplished using multiple
cooperating processes which, together, provide the server functionality.
.. toctree::
- :maxdepth: 2
+ :numbered:
+ :maxdepth: 3
intro
quickstart
netconf
api
-TODO: this is appendinx
+TODO: this is appendix
Acknowledgments
===============
\ https://www.isc.org/donate/.
We thank all the organizations and individuals who have helped to make
-Kea possible. `Comcast <http://www.comcast.com/>`__ and the Comcast
+Kea possible. `Comcast <https://www.comcast.com/>`__ 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.
BIND 10 framework. We thank the founding sponsors of the BIND 10
project: `Afilias <https://www.afilias.info/>`__,
`IIS.SE <https://www.iis.se/>`__,
-`Nominet <http://www.nominet.org.uk/>`__,
-`SIDN <https://www.sidn.nl/>`__, `JPRS <http://jprs.co.jp/>`__,
-`CIRA <http://cira.ca/>`__; and additional sponsors
+`Nominet <https://www.nominet.uk/>`__,
+`SIDN <https://www.sidn.nl/>`__, `JPRS <https://jprs.co.jp/>`__,
+`CIRA <https://cira.ca/>`__; and additional sponsors
`AFNIC <https://www.afnic.fr/>`__,
`CNNIC <https://www.cnnic.net.cn/>`__, `CZ.NIC <https://www.nic.cz/>`__,
-`DENIC eG <http://www.denic.de/>`__,
+`DENIC eG <https://www.denic.de/>`__,
`Google <https://www.google.com/>`__, `RIPE
NCC <https://www.ripe.net/>`__, `Registro.br <https://registro.br/>`__,
`.nz Registry Services <https://nzrs.net.nz/>`__, and `Technical Center
.. _quickstart:
-**********************
-Chapter 2. Quick Start
-**********************
+***********
+Quick Start
+***********
This section describes the basic steps needed to get Kea up and running.
For further details, full customizations, and troubleshooting, see the
.. _quick-start:
-2.1 Quick Start Guide for DHCPv4 and DHCPv6 Services
-====================================================
+Quick Start Guide for DHCPv4 and DHCPv6 Services
+================================================
1. Install required run-time and build dependencies. See
- `Section 3.3, “Building Requirements” <#build-requirements>`__ for details.
+ :ref:`Build Requirements <build-requirements>` for details.
-2. Download the Kea source tarball from the `ISC.org downloads
- page <https://www.isc.org/download/>`__ or the `ISC FTP
- server <ftp://ftp.isc.org/isc/kea/>`__.
+2. Download the Kea source tarball from the :ref:`ISC.org downloads
+ page <https://www.isc.org/download/>` or the :ref:`ISC FTP
+ server <ftp://ftp.isc.org/isc/kea/>`.
3. Extract the tarball. For example:
10. 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 `ISC DHCP
- client <https://www.isc.org/download/>`__.
+ configuration from the server; for example, use the :ref:`ISC DHCP
+ client <https://www.isc.org/download/>`.
11. Stop running the server(s):
# keactrl stop
For instructions specific to your system, please read the
-`system-specific notes <https://kb.isc.org/docs/installing-kea>`__,
-available in the `Kea section of ISC's
-Knowledgebase <https://kb.isc.org/docs>`__.
+:ref:`system-specific notes <https://kb.isc.org/docs/installing-kea>`,
+available in the :ref:`Kea section of ISC's
+Knowledgebase <https://kb.isc.org/docs>`.
The details of ``keactrl`` script usage can be found in
-`Chapter 6, "Managing Kea with keactrl" <#keactrl>`__.
+:ref:`Managing Kea with keactrl <#keactrl>`.
.. _quick-start-direct-run:
-2.2 Running the Kea Servers Directly
-====================================
+Running the Kea Servers Directly
+================================
The Kea servers can be started directly, without the need to use
``keactrl``. To start the DHCPv4 server run the following command:
projects / thirdparty / kea.git / commitdiff
