mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-22 01:49:48 +00:00
[#3732] Switch docs from Autotools to Meson
This commit is contained in:
Andrei Pavel
parent
39ec5d22a6
commit
435d56b645
@ -191,29 +191,20 @@ such long periods, code tends to be refactored several times. The change you mad
|
||||
some other change or by the code that hasn't been written yet.
|
||||
|
||||
See Building Kea with Unit Tests for instructions on how to run unit-tests. If you happen to touch
|
||||
any database related code, make sure you compile your code with –with-mysql and/or –with-pgsql as
|
||||
any database related code, make sure you compile your code with `–Dmysql` and/or `–Dpostgresql` as
|
||||
needed. For example, if you change something substantial, make sure the other compilation options
|
||||
still work.
|
||||
|
||||
If you happen to add new files or have modified any Makefile.am files, it is also a good idea to
|
||||
check if you haven't broken the distribution process:
|
||||
Enabling tests automatically enables logger checks (sanity checks on logger parameters), enable debug symbols and
|
||||
various additional consistency checks that reduce performance but help during development.
|
||||
|
||||
```bash
|
||||
make distcheck
|
||||
```
|
||||
|
||||
There are other useful switches which can be passed to configure. It is always a good idea to use
|
||||
`–enable-logger-checks`, which does sanity checks on logger parameters. Use `–-enable-debug` to
|
||||
enable debug symbols and various additional consistency checks that reduce performance but help
|
||||
during development.
|
||||
If you happen to modify anything in the documentation, use `–-enable-generate-docs`. If you are
|
||||
modifying DHCP code, you are likely to be interested in enabling a non-default database backends for
|
||||
DHCP. Note that if the backend is not enabled, the database-specific unit-tests are skipped. To
|
||||
enable the MySQL backend, use the switch `–with-mysql`; for PostgreSQL, use `–with-pgsql`.
|
||||
If you are modifying DHCP code, you are likely to be interested in enabling a non-default database backends for DHCP.
|
||||
Note that if the backend is not enabled, the database-specific unit-tests are skipped. To
|
||||
enable the MySQL backend, use the switch `-Dmysql`; for PostgreSQL, use `–Dpostgresql`.
|
||||
A complete list of all switches can be obtained with the command:
|
||||
|
||||
```bash
|
||||
./configure --help
|
||||
meson configure
|
||||
```
|
||||
|
||||
## Submitting Merge Request (also known as sending your patch the right way)
|
||||
|
||||
53
INSTALL
53
INSTALL
@ -1,43 +1,38 @@
|
||||
INSTALLATION INSTRUCTIONS
|
||||
|
||||
1. Generate the configure script. If you downloaded the source from git or
|
||||
are compiling with premium hook packages, you will need to run autoreconf to
|
||||
generate the configure script as shown below. If you are building from a
|
||||
tarball you may skip this step.
|
||||
1. Set up the build. If you want to alter Kea's installation path, or want to
|
||||
make sure that certain capabilities are included (e.g. enabling MySQL or
|
||||
PostgreSQL), you will need to specify these as options to the command (run
|
||||
"meson configure" for a list of options).
|
||||
|
||||
$ autoreconf --install
|
||||
|
||||
2. Run the configure script. If you want to alter Kea's installation path, or
|
||||
need to include capabilities (e.g. enabling MySQL or PostgreSQL) you will need
|
||||
to specify these as options to the configure script (run ./configure -h for
|
||||
list of options).
|
||||
|
||||
$ ./configure
|
||||
$ meson setup build
|
||||
|
||||
If your environment is missing dependencies, the configure script will exit
|
||||
with error and should emit sufficient information to guide you on how to
|
||||
proceed. A detailed account of the configure process is captured in
|
||||
./config.log.
|
||||
proceed. A detailed account of the configure process is captured in
|
||||
build/meson-logs/meson-log.txt.
|
||||
|
||||
3. Build it. Once you've successfully configured the source tree, run "make" to
|
||||
build it. You may wish to include the -j<n> command line option to specify
|
||||
parallel execution to speed things along:
|
||||
2. Build it. Once you've successfully set up the build, run "meson compile" to
|
||||
build it.
|
||||
|
||||
$ make
|
||||
$ meson compile -C build
|
||||
|
||||
4. Install it. Depending on your target directory, this step will likely require
|
||||
a root privileges. You can install the software by running:
|
||||
4. Install it. Depending on your target directory, this step will likely
|
||||
require a root privileges. You can install the software by running:
|
||||
|
||||
$ sudo make install
|
||||
$ meson install -C build
|
||||
|
||||
Kea depends on C++ compiler, make, libtool, boost (at least includes, but many
|
||||
Kea depends on C++ compiler, meson, ninja, boost (at least includes, but many
|
||||
OSes require boost-system library), log4cplus and one crypto library (either
|
||||
OpenSSL or Botan) for compilation. Optional backends (MySQL and PostgreSQL)
|
||||
have additional dependencies. For detailed installation directions, see the
|
||||
documentation in doc/sphinx/arm/install.rst text file or on the Kea online
|
||||
docs: https://kea.readthedocs.io/.
|
||||
Another optional dependency is Sysrepo, a system for providing YANG/NETCONF
|
||||
interface.
|
||||
OpenSSL or Botan) for compilation.
|
||||
|
||||
Optional backends (MySQL and PostgreSQL) have additional dependencies. For
|
||||
detailed installation directions, see the documentation in the
|
||||
doc/sphinx/arm/install.rst text file or on the Kea online docs:
|
||||
https://kea.readthedocs.io/en/stable/arm/install.html.
|
||||
|
||||
Other optional dependencies are Kerberos with GSSAPI support for the GSS-TSIG
|
||||
hook library and libyang and sysrepo for providing a YANG/NETCONF interface.
|
||||
|
||||
You can find current OS-specific build/installation
|
||||
instructions in our knowledge base at https://kb.isc.org/docs/installing-kea
|
||||
instructions in our knowledge base at https://kb.isc.org/docs/installing-kea.
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2017-2021 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2017-2025 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
|
||||
@ -103,9 +103,8 @@ when the .ll or .yy files are altered and are stored in the Kea repository. To g
|
||||
issue the following sequence of commands from the top-level Kea directory:
|
||||
|
||||
@code
|
||||
./configure --enable-generate-parser
|
||||
cd src/bin/dhcp6
|
||||
make parser
|
||||
meson setup build
|
||||
meson compile -C build parser
|
||||
@endcode
|
||||
|
||||
Strictly speaking, the comment "make parser" is not necessary. If you updated the .ll or .yy file,
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2014-2023 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2014-2025 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
|
||||
@ -32,23 +32,6 @@ one day to develop a minimalistic, stripped down Kea version that does
|
||||
not have any command interface at all. This could prove useful for running
|
||||
Kea in embedded regime.
|
||||
|
||||
The following steps are needed for the DHCPv4 server to be able to
|
||||
process a new method of configuration. (It is assumed that the
|
||||
modified component is DHCPv4. Similar approach applies to the other
|
||||
components: DHCPv6 or DHCP-DDNS):
|
||||
|
||||
-# Write your own implementation of isc::dhcp::ControlledDhcpv4Srv::init(),
|
||||
isc::dhcp::ControlledDhcpv4Srv::init() and isc::dhcp::ControlledDhcpv4Srv::cleanup(),
|
||||
and put it in the src/bin/dhcp4 directory (e.g. as foo_controller.cc).
|
||||
-# Modify src/bin/dhcp4/Makefile.am to include your file (e.g. foo_controller.cc) in
|
||||
the build.
|
||||
-# Modify the AC_ARG_WITH(kea-config,...) macro in configure.ac to include an
|
||||
entry for your configuration backend.
|
||||
-# Add your own AM_CONDITIONAL(CONFIG_BACKEND_FOO, ...) and
|
||||
AC_DEFINE(CONFIG_BACKEND_FOO, ...) macros to configure.ac (following the
|
||||
above-mentioned AC_ARG_WITH macro) to set the C++ macro for your backend.
|
||||
-# Modify the sanity check in configure.ac to allow your configuration backend name.
|
||||
|
||||
Optionally you can also:
|
||||
|
||||
-# Implement unit tests for your backend in the src/bin/dhcp4/tests directory.
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2020-2022 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2020-2025 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
|
||||
@ -6,6 +6,8 @@
|
||||
|
||||
/**
|
||||
|
||||
* @note Outdated.
|
||||
|
||||
@page crossCompile Kea Cross-Compiling Example
|
||||
|
||||
The idea is to install Kea on a Raspberry Pi 4 Model B running Raspbian
|
||||
@ -195,7 +197,7 @@ Some explanations:
|
||||
cross-compiling and produce correct paths.
|
||||
- CONF_CMD contains the ./configure common arguments.
|
||||
|
||||
The script can be used by:
|
||||
The script can be used to:
|
||||
- eventually run "autoreconf -i" (if sources are from git)
|
||||
- put its content in a file, e.g. ccenv
|
||||
- load the file by ". ccenv"
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2018-2021 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2018-2025 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
|
||||
@ -11,15 +11,16 @@
|
||||
There are several types of documentation for Kea. The primary one, intended to
|
||||
be read by users, is User's Guide. It comes in HTML, PDF and txt format. All
|
||||
of them generated from the same sources. To generate this doc, you need to
|
||||
run configure script with --enable-generate-docs option. sphinx has to be
|
||||
enabled in the system.
|
||||
run configure script with --enable-generate-docs option. sphinx and
|
||||
sphinx_rtd_theme have to be available on the system. texlive is also required
|
||||
if you want to create documentation in HTML format.
|
||||
You can generate this by doing:
|
||||
@code
|
||||
$ ./configure --enable-generate-docs
|
||||
$ make -C ./doc
|
||||
$ meson setup build
|
||||
$ meson compile -C build doc
|
||||
@endcode
|
||||
|
||||
The output files will be generated in the ./doc/sphinx/_build directory.
|
||||
The output files will be generated in the ./build/doc/sphinx/_build directory.
|
||||
|
||||
The ARM has an appendix that lists all Kea commands. The commands are integrated
|
||||
into RST using the tool located at doc/sphinx/api2doc.py. The basic principle
|
||||
@ -30,19 +31,16 @@ Those JSON files are loaded by the api2doc.py tool that will generate api.txt
|
||||
that will be used by sphinx. There is no need to call this tool explicitly.
|
||||
It is called automatically when building the ARM.
|
||||
|
||||
Since Kea 1.9.9, the ARM has an appendix with the grammar. If there were new
|
||||
parameters added, you can regenerate the grammars and the appendix with the
|
||||
following procedure:
|
||||
The ARM has an appendix with the grammar. If there were new parameters added,
|
||||
you can regenerate the grammars and the appendix with the following procedure:
|
||||
|
||||
@code
|
||||
$ autoreconf -i
|
||||
$ ./configure --enable-generate-docs --enable-generate-parser
|
||||
$ cd doc
|
||||
$ make grammar
|
||||
$ make -C sphinx html
|
||||
$ meson setup build
|
||||
$ meson compile -C build grammar
|
||||
$ meson compile -C build doc
|
||||
@endcode
|
||||
|
||||
After that, inspect the html output and make sure it's ok, review changes in
|
||||
After that, inspect the HTML output and make sure it's ok, review changes in
|
||||
\c doc/sphinx/grammar/ and then check in those that are something more than a date
|
||||
update. The date is there, so we (and users) can determine if the grammar
|
||||
is or isn't out of date.
|
||||
@ -51,12 +49,12 @@ is or isn't out of date.
|
||||
|
||||
There are several steps needed to document a new API command:
|
||||
|
||||
1. Configure sources with ./configure --enable-generate-docs
|
||||
1. Copy src/share/api/_template.json to appropriate name.
|
||||
2. Remove comments from it and fill in the actual content.
|
||||
3. Update api_files.mk file in src/share/api/Makefile.am
|
||||
4. make html will generate multi-page html.
|
||||
5. make singlehtml will generate a single page html.
|
||||
1. Set up the build with "meson setup build".
|
||||
2. Copy src/share/api/_template.json to appropriate name.
|
||||
3. Remove comments from it and fill in the actual content.
|
||||
4. Update api_files.mk file in src/share/api.
|
||||
5. "meson compile -C build doc" will generate both multi-page and single-page
|
||||
HTML sites.
|
||||
|
||||
A word of caution regaring editing JSON files. The files themselves need to be
|
||||
valid JSON files. They also often contain fields, such as command syntax or
|
||||
@ -78,9 +76,8 @@ doxygen installed in your system. If you also have graphviz installed, it will
|
||||
generate nice diagrams. To generate developer's guide, do the following commands:
|
||||
|
||||
@code
|
||||
$ ./configure
|
||||
$ cd doc/devel
|
||||
$ make devel
|
||||
$ meson setup build
|
||||
$ meson compile -C build devel
|
||||
@endcode
|
||||
|
||||
*/
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2017-2024 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2017-2025 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
|
||||
@ -49,8 +49,8 @@ Combining the binaries and the fuzzer types results in eight fuzzing binaries:
|
||||
Use the "--enable-fuzzing" during the configure step. Then just compile as usual.
|
||||
|
||||
@code
|
||||
./configure --enable-fuzzing
|
||||
make
|
||||
meson setup build -D fuzz=enabled
|
||||
meson compile -C build
|
||||
@endcode
|
||||
|
||||
You can check that `config.report` shows these lines:
|
||||
@ -171,11 +171,11 @@ for this are:
|
||||
compiler.
|
||||
- Specify a value of "--prefix" on the command line to set the directory
|
||||
into which Kea is installed.
|
||||
- Add the "--enable-fuzzing" switch to the "configure" command line.
|
||||
- Add the "-Dfuzz=enabled" switch to the "meson setup" command line.
|
||||
.
|
||||
For example:
|
||||
@code
|
||||
CXX=afl-clang-fast ./configure --enable-fuzzing --prefix=$HOME/installed
|
||||
CXX=afl-clang-fast meson setup build -D fuzz=enabled --prefix=$HOME/installed
|
||||
make
|
||||
@endcode
|
||||
|
||||
@ -327,7 +327,7 @@ while (not shutting down) {
|
||||
Read and process one packet
|
||||
}
|
||||
@endcode
|
||||
When --enable-fuzzing is specified, this is conceptually modified to:
|
||||
When -Dfuzz=enabled is specified, this is conceptually modified to:
|
||||
@code{.unparsed}
|
||||
while (not shutting down) {
|
||||
Read stdin and copy data to address/port on which Kea is listening
|
||||
@ -374,7 +374,7 @@ leaks).
|
||||
No changes were required to Kea source code to fuzz configuration files. In
|
||||
fact, other than compiling with afl-clang++ and installing the resultant
|
||||
executable, no other steps are required. In particular, there is no need to
|
||||
use the "--enable-fuzzing" switch in the configuration command line (although
|
||||
use the "-Dfuzz=enabled" switch in the configuration command line (although
|
||||
doing so will not cause any problems).
|
||||
|
||||
@subsection fuzzThreads Changes Required for Multi-Threaded Kea
|
||||
@ -390,7 +390,7 @@ the AFL input in the background.
|
||||
|
||||
@subsection fuzzNotesUnitTests Unit Test Failures
|
||||
|
||||
If unit tests are built when --enable-fuzzing is specified and with the AFL
|
||||
If unit tests are built when -Dfuzz=enabled is specified and with the AFL
|
||||
compiler, note that tests which check or use the DHCP servers (i.e. the unit
|
||||
tests in src/bin/dhcp4, src/bin/dhcp6 and src/bin/kea-admin) will fail.
|
||||
With no AFL-related environment variables defined, a C++ exception will be
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2015-2024 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2015-2025 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
|
||||
@ -8,40 +8,31 @@
|
||||
|
||||
@page unitTests Building Kea with Unit Tests
|
||||
|
||||
By default, Kea is built without unit-tests as they're used mostly by
|
||||
developers and prospective contributors. Kea's unit-tests are using
|
||||
By default, Kea is built without unit tests as they're used mostly by
|
||||
developers and prospective contributors. Kea's unit tests are using
|
||||
<a href="https://github.com/google/googletest">gtest framework</a> from
|
||||
Google. Google's approach has changed over the years. For some time,
|
||||
they were very keen on not installing gtest as a normal software would
|
||||
be, but rather provide gtest as sources. This was further complicated
|
||||
with the fact that some Linux distributions packaged gtest and tried
|
||||
to mimic its installation. Kea tries its best to accommodate all typical
|
||||
situations and provides two switches to point to gtest. You can use
|
||||
`--with-gtest` or `--with-gtest-source`. Both attempt to locate gtest
|
||||
on their own. However, if neither of them can find it, you can specify
|
||||
the path explicitly. For example, on ubuntu with googletest package installed,
|
||||
you can do the following for Kea to find it:
|
||||
to mimic its installation. Meson tries its best to accommodate all typical
|
||||
situations and to locate gtest on its own. If it cannot be found, linking
|
||||
/usr/src/googletest to the custom location should do the trick. The `-D tests`
|
||||
flag has to be provided.
|
||||
|
||||
@code
|
||||
sudo apt install googletest
|
||||
./configure --with-gtest-source=/usr/src/googletest
|
||||
meson setup build -D tests=enabled
|
||||
@endcode
|
||||
|
||||
Depending on how you compiled or installed \c gtest (e.g. from sources
|
||||
or using some package management system) one of those two switches will
|
||||
find \c gtest. After that you make and run the unit-tests with:
|
||||
After that you run the unit tests with:
|
||||
|
||||
@code
|
||||
make
|
||||
make check
|
||||
meson compile -C build
|
||||
meson test -C build
|
||||
@endcode
|
||||
|
||||
As usual, using \c -jX option will speed up compilation. This parameter is
|
||||
even more useful for unit-tests as there are over 6000 unit-tests and their
|
||||
compilation is significantly slower than just the production Kea sources.
|
||||
|
||||
Kea should work with reasonably recent gtest versions. We recently tried
|
||||
with 1.7.0, 1.8.0, 1.8.1 and 1.10.0.
|
||||
Kea should work with gtest versions 1.8.0 and later.
|
||||
|
||||
@section unitTestsEnvironmentVariables Environment Variables
|
||||
|
||||
@ -119,8 +110,8 @@ anything e.g. `DEBUG=true`. `unset DEBUG` to remove this behavior.
|
||||
some tests always fail when it is used, experiments are run with
|
||||
different versions of Tsan).
|
||||
|
||||
The simplest way to enable a sanitizer is to add it to the CXXFLAGS
|
||||
environment variable in .configure by e.g. <i>-fsanitize=thread</i>.
|
||||
The simplest way to enable a sanitizer is to specify the flag on the setup
|
||||
step with `meson setup build -Db_sanitize=thread`.
|
||||
|
||||
When enabling lcov (code coverage), some gtest functions are detected as
|
||||
not being thread safe. It is recommended to disable lcov when enabling
|
||||
@ -208,7 +199,7 @@ anything e.g. `DEBUG=true`. `unset DEBUG` to remove this behavior.
|
||||
%@endverbatim
|
||||
|
||||
The unit tests are run automatically when "make check" is executed (providing
|
||||
that Kea has been built with the \c --with-mysql switch (see the installation
|
||||
that Kea has been built with the "-D mysql" switch (see the installation
|
||||
section in the <a href="https://kea.readthedocs.io/">Kea Administrator
|
||||
Reference Manual</a>).
|
||||
|
||||
@ -405,7 +396,7 @@ local all postgres trust
|
||||
that runs tests. Use caution!
|
||||
|
||||
The unit tests are run automatically when "make check" is executed (providing
|
||||
that Kea has been build with the \c --with-pgsql switch (see the installation
|
||||
that Kea has been build with the "-D postgresql" switch (see the installation
|
||||
section in the <a href="https://kea.readthedocs.io">Kea Administrator
|
||||
Reference Manual</a>).
|
||||
|
||||
|
||||
@ -31,7 +31,7 @@
|
||||
// parameters are type and name. If other parameters are not specified,
|
||||
// Kea will assume the database is available on localhost, that user and
|
||||
// password is not necessary to connect and that timeout is 5 seconds.
|
||||
// Kea must be compiled with --with-mysql option to use this backend.
|
||||
// Kea must be compiled with the "-D mysql" option to use this backend.
|
||||
// "lease-database": {
|
||||
// "type": "mysql",
|
||||
// "name": "keatest",
|
||||
@ -59,7 +59,7 @@
|
||||
// parameters are type and name. If other parameters are not specified,
|
||||
// Kea will assume the database is available on localhost, that user and
|
||||
// password is not necessary to connect and that timeout is 5 seconds.
|
||||
// Kea must be compiled with --with-pgsql option to use this backend.
|
||||
// Kea must be compiled with the "-D postgresql" option to use this backend.
|
||||
// "lease-database": {
|
||||
// "type": "postgresql",
|
||||
// "name": "keatest",
|
||||
|
||||
@ -31,7 +31,7 @@
|
||||
// parameters are type and name. If other parameters are not specified,
|
||||
// Kea will assume the database is available on localhost, that user and
|
||||
// password is not necessary to connect and that timeout is 5 seconds.
|
||||
// Kea must be compiled with --with-mysql option to use this backend.
|
||||
// Kea must be compiled with the "-D mysql" option to use this backend.
|
||||
// "lease-database": {
|
||||
// "type": "mysql",
|
||||
// "name": "keatest",
|
||||
@ -59,7 +59,7 @@
|
||||
// parameters are type and name. If other parameters are not specified,
|
||||
// Kea will assume the database is available on localhost, that user and
|
||||
// password is not necessary to connect and that timeout is 5 seconds.
|
||||
// Kea must be compiled with --with-pgsql option to use this backend.
|
||||
// Kea must be compiled with the "-D postgresql" option to use this backend.
|
||||
// "lease-database": {
|
||||
// "type": "postgresql",
|
||||
// "name": "keatest",
|
||||
|
||||
@ -633,19 +633,6 @@ Use the following command to perform an upgrade:
|
||||
|
||||
$ kea-admin db-upgrade pgsql -u database-user -p database-password -n database-name
|
||||
|
||||
.. _pgsl-ssl:
|
||||
|
||||
PostgreSQL without OpenSSL support
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Usually the PostgreSQL database client library is built with the OpenSSL
|
||||
support but Kea can be configured to handle the case where it is not
|
||||
supported:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ ./configure [other-options] --disable-pgsql-ssl
|
||||
|
||||
.. _pgsql-performance:
|
||||
|
||||
Improved Performance With PostgreSQL
|
||||
|
||||
@ -299,7 +299,7 @@ Starting and Stopping the Control Agent
|
||||
dynamically linked to Kea.
|
||||
|
||||
- ``-W`` - displays the Kea configuration report and exits. The report
|
||||
is a copy of the ``config.report`` file produced by ``./configure``;
|
||||
is a copy of the ``config.report`` file produced by ``meson setup``;
|
||||
it is embedded in the executable binary.
|
||||
|
||||
The contents of the ``config.report`` file may also be accessed by examining
|
||||
|
||||
@ -165,13 +165,13 @@ CB Components
|
||||
|
||||
To use a MySQL configuration backend, :ischooklib:`libdhcp_mysql.so` must
|
||||
be compiled and the DHCP servers must be configured to load it. It is compiled
|
||||
when the ``--with-mysql`` configuration switch is used during the Kea build.
|
||||
when the ``-D mysql`` configuration switch is used during the Kea build.
|
||||
The MySQL C client libraries must be installed, as explained in
|
||||
:ref:`dhcp-install-configure`.
|
||||
|
||||
To use a PostgreSQL configuration backend, :ischooklib:`libdhcp_pgsql.so` must
|
||||
be compiled and the DHCP servers must be configured to load it. It is compiled
|
||||
when the ``--with-pgsql`` configuration switch is used during the Kea build.
|
||||
when the ``-D pgsql`` configuration switch is used during the Kea build.
|
||||
The PostgreSQL C client libraries must be installed, as explained in
|
||||
:ref:`dhcp-install-configure`.
|
||||
|
||||
|
||||
@ -135,7 +135,7 @@ directly. It accepts the following command-line switches:
|
||||
- ``-V`` - displays the extended Kea version and exits.
|
||||
|
||||
- ``-W`` - displays the Kea configuration report and exits. The report
|
||||
is a copy of the ``config.report`` file produced by ``./configure``;
|
||||
is a copy of the ``config.report`` file produced by ``meson setup``;
|
||||
it is embedded in the executable binary.
|
||||
|
||||
- ``-t file`` - specifies the configuration file to be tested.
|
||||
|
||||
@ -58,7 +58,7 @@ the following command-line switches:
|
||||
dynamically linked to Kea.
|
||||
|
||||
- ``-W`` - displays the Kea configuration report and exits. The report
|
||||
is a copy of the ``config.report`` file produced by ``./configure``;
|
||||
is a copy of the ``config.report`` file produced by ``meson setup``;
|
||||
it is embedded in the executable binary.
|
||||
|
||||
The contents of the ``config.report`` file may also be accessed by examining
|
||||
|
||||
@ -58,7 +58,7 @@ the following command-line switches:
|
||||
dynamically linked to Kea.
|
||||
|
||||
- ``-W`` - displays the Kea configuration report and exits. The report
|
||||
is a copy of the ``config.report`` file produced by ``./configure``;
|
||||
is a copy of the ``config.report`` file produced by ``meson setup``;
|
||||
it is embedded in the executable binary.
|
||||
|
||||
The contents of the ``config.report`` file may also be accessed by examining
|
||||
|
||||
@ -64,66 +64,51 @@ the SPNEGO library. Two implementations meet this criteria: MIT Kerberos
|
||||
GSS-TSIG Compilation
|
||||
--------------------
|
||||
|
||||
The following procedure was tested on Ubuntu 20.10 and 21.04. A similar
|
||||
approach can be applied to other systems.
|
||||
The following procedure was tested on Debian 12. A similar approach can be
|
||||
applied to other systems.
|
||||
|
||||
1. Obtain the Kea sources, extract the Kea sources.
|
||||
|
||||
2. Run autoreconf:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
autoreconf -i
|
||||
|
||||
3. Make sure ``./configure --help`` shows the ``--with-gssapi`` option.
|
||||
|
||||
4. Install either the MIT (``libkrb5-dev``) or the Heimdal (``heimdal-dev``) library,
|
||||
1. Install either the MIT (``libkrb5-dev``) or the Heimdal (``heimdal-dev``) library,
|
||||
for instance:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
sudo apt install libkrb5-dev
|
||||
|
||||
5. Run ``configure`` with the ``--with-gssapi`` option:
|
||||
2. Obtain the Kea sources, extract the Kea sources.
|
||||
|
||||
3. Set up the build:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
./configure --with-gssapi
|
||||
meson setup build -D krb5=enabled
|
||||
|
||||
.. note:
|
||||
|
||||
It is ``--with-gssapi`` (with no dash between "gss" and "api"), to maintain
|
||||
consistency with the BIND 9 option.
|
||||
|
||||
The ``--with-gssapi`` parameter requires the ``krb5-config`` tool to be present. This
|
||||
tool is provided by both MIT Kerberos 5 and Heimdal; however, on some systems
|
||||
where both Kerberos 5 and Heimdal are installed, it is a symbolic link
|
||||
to one of them. If the tool is not in the standard location, it can be specified
|
||||
with ``--with-gssapi=/path/to/krb5-config``. It is strongly recommended
|
||||
to use the default installation locations provided by the packages.
|
||||
|
||||
The ``./configure`` script should complete with a successful GSS-API
|
||||
detection, similar to this:
|
||||
4. Make sure ``build/config.report`` shows the ``Kerberos5 GSS-API`` entry.
|
||||
|
||||
::
|
||||
|
||||
GSS-API support:
|
||||
GSSAPI_CFLAGS: -isystem /usr/include/mit-krb5
|
||||
GSSAPI_LIBS: -L/usr/lib/x86_64-linux-gnu/mit-krb5 -Wl,-Bsymbolic-functions -Wl,-z,relro -lgssapi_krb5 -lkrb5 -lk5crypto -lcom_err
|
||||
Kerberos5 GSS-API:
|
||||
VERSION: 1.20.1
|
||||
VENDOR: MIT
|
||||
|
||||
6. Compile ``make -jX``, where X is the number of CPU cores
|
||||
available.
|
||||
Either the ``krb5.pc`` file or the ``krb5-config`` tool are required to be
|
||||
present. They are provided by both MIT Kerberos 5 and Heimdal; however, on some
|
||||
systems where both Kerberos 5 and Heimdal are installed, it is a symbolic link
|
||||
to one of them. If the tool is not in the standard location, it can be selected
|
||||
by setting ``PKG_CONFIG_PATH=/path/to/krb5.pc:${PKG_CONFIG_PATH}`` or
|
||||
``PATH=/path/to/krb5-config:${PATH}`` prior to ``meson setup``.
|
||||
|
||||
7. After compilation, :ischooklib:`libddns_gss_tsig.so` is available in the
|
||||
``src/hooks/d2/gss_tsig`` directory. It can be loaded by :iscman:`kea-dhcp-ddns`.
|
||||
6. Compile with ``meson compile -C build``.
|
||||
|
||||
:ischooklib:`libddns_gss_tsig.so` was developed using the MIT Kerberos 5 implementation, but
|
||||
Heimdal is also supported. Note that Heimdal is picky about
|
||||
security-sensitive file permissions and is known to emit an unclear error message.
|
||||
It is a good idea to keep these files plain, with one link and no
|
||||
access for the group or other users.
|
||||
7. After compilation, :ischooklib:`libddns_gss_tsig.so` is available in the
|
||||
``build/src/hooks/d2/gss_tsig`` directory. It can be loaded by
|
||||
:iscman:`kea-dhcp-ddns`.
|
||||
|
||||
The ``krb5-config`` script should provide an ``--all`` option which
|
||||
:ischooklib:`libddns_gss_tsig.so` supports both MIT Kerberos 5 and Heimdal
|
||||
implementations. Heimdal is picky about security-sensitive file permissions and
|
||||
is known to emit an unclear error message. It is a good idea to keep these
|
||||
files plain, with one link and no access for the group or other users.
|
||||
|
||||
The ``krb5-config`` script should provide an ``--vendor`` option which
|
||||
identifies the implementation.
|
||||
|
||||
.. _gss-tsig-deployment:
|
||||
|
||||
@ -124,60 +124,38 @@ Compiling With NETCONF
|
||||
$ git clone gitlab.isc.org/isc-projects/kea.git
|
||||
$ cd kea
|
||||
|
||||
2. Configure the build.
|
||||
2. Set up the build.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ autoreconf -i
|
||||
$ ./configure --with-libyang --with-libyang-cpp --with-sysrepo --with-sysrepo-cpp
|
||||
$ meson setup build -D netconf=enabled -D cpp_std=c++20
|
||||
|
||||
.. note::
|
||||
|
||||
If any of the libraries are installed in a custom location, the
|
||||
``--with`` flags accept the installations paths as values.
|
||||
PKG_CONFIG_PATH can point to the .pc files.
|
||||
|
||||
3. Check ``config.report`` to verify NETCONF support.
|
||||
.. code-block:: console
|
||||
|
||||
PKG_CONFIG_PATH=:/opt/libyang/lib/pkgconfig:/opt/libyang-cpp/lib/pkgconfig:/opt/sysrepo/lib/pkgconfig:/opt/sysrepo-cpp/lib/pkgconfig
|
||||
|
||||
3. Check ``build/config.report`` to verify NETCONF support.
|
||||
|
||||
::
|
||||
|
||||
NETCONF:
|
||||
yes
|
||||
NETCONF:
|
||||
YANG: 2.1.4
|
||||
YANG_PREFIX: /opt/libyang
|
||||
YANGCPP: 1.1.0
|
||||
YANGCPP_PREFIX: /opt/libyang-cpp
|
||||
SYSREPO: 2.2.12
|
||||
SYSREPO_PREFIX: /opt/sysrepo
|
||||
SYSREPOCPP: 1.1.0
|
||||
SYSREPOCPP_PREFIX: /opt/sysrepo-cpp
|
||||
|
||||
libyang:
|
||||
LIBYANG_CPPFLAGS:
|
||||
LIBYANG_INCLUDEDIR: -I/usr/local/include
|
||||
LIBYANG_LIBS: -L/usr/local/lib -lyang -Wl,-R/usr/local/lib -lyang
|
||||
LIBYANG_PREFIX: /usr/local
|
||||
LIBYANG_VERSION: 2.1.4
|
||||
4. Compile as usual.
|
||||
|
||||
libyang-cpp:
|
||||
LIBYANGCPP_CPPFLAGS:
|
||||
LIBYANGCPP_INCLUDEDIR: -I/usr/local/include
|
||||
LIBYANGCPP_LIBS: -L/usr/local/lib -lyang-cpp -Wl,-R/usr/local/lib -lyang-cpp
|
||||
LIBYANGCPP_PREFIX: /usr/local
|
||||
LIBYANGCPP_VERSION: 1.1.0
|
||||
|
||||
sysrepo:
|
||||
SYSREPO_CPPFLAGS:
|
||||
SYSREPO_INCLUDEDIR: -I/usr/local/include
|
||||
SYSREPO_LIBS: -L/usr/local/lib -lsysrepo -Wl,-R/usr/local/lib -lsysrepo
|
||||
SYSREPO_PREFIX: /usr/local
|
||||
SYSREPO_VERSION: 2.2.12
|
||||
|
||||
SR_REPO_PATH: /etc/sysrepo
|
||||
SR_PLUGINS_PATH: /usr/local/lib/sysrepo/plugins
|
||||
SRPD_PLUGINS_PATH: /usr/local/lib/sysrepo-plugind/plugins
|
||||
|
||||
sysrepo-cpp:
|
||||
SYSREPOCPP_CPPFLAGS:
|
||||
SYSREPOCPP_INCLUDEDIR: -I/usr/local/include
|
||||
SYSREPOCPP_LIBS: -L/usr/local/lib -lsysrepo-cpp -Wl,-R/usr/local/lib -lsysrepo-cpp
|
||||
SYSREPOCPP_PREFIX : /usr/local
|
||||
SYSREPOCPP_VERSION: 1.1.0
|
||||
|
||||
4. Build as usual.
|
||||
|
||||
$ make
|
||||
$ meson compile -C build
|
||||
|
||||
.. _sysrepo-overview:
|
||||
|
||||
@ -684,7 +662,7 @@ Starting and Stopping the NETCONF Agent
|
||||
dynamically linked to Kea.
|
||||
|
||||
- ``-W`` - displays the Kea configuration report and exits. The report
|
||||
is a copy of the ``config.report`` file produced by ``./configure``;
|
||||
is a copy of the ``config.report`` file produced by ``meson setup``;
|
||||
it is embedded in the executable binary.
|
||||
|
||||
The contents of the ``config.report`` file may also be accessed by examining
|
||||
|
||||
@ -59,8 +59,8 @@ Installing Hook Packages
|
||||
|
||||
.. note::
|
||||
|
||||
For more details about installing the Kea Subscriber Hooks, please read
|
||||
`this Knowledgebase article <https://kb.isc.org/docs/aa-01587>`__.
|
||||
For more details about installing the Kea Subscriber Hooks, please read
|
||||
`this Knowledgebase article <https://kb.isc.org/docs/aa-01587>`__.
|
||||
|
||||
Most hook packages are now included in the base Kea sources. There is no
|
||||
need to do anything special to compile or install them, as they are covered
|
||||
@ -84,7 +84,7 @@ Unpack this tarball:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
$ tar -zxvf kea-|release|.tar.gz
|
||||
$ tar -zxvf kea-|release|.tar.gz
|
||||
|
||||
This will unpack the tarball into the ``kea-|release|`` subdirectory of
|
||||
the current working directory.
|
||||
@ -96,50 +96,38 @@ steps will unpack the subscriber tarball into the correct location:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
$ cd kea-|release|
|
||||
$ tar -xvf ../kea-subscriber-|release|.tar.gz
|
||||
$ cd kea-|release|
|
||||
$ tar -xvf ../kea-subscriber-|release|.tar.gz
|
||||
|
||||
Note that unpacking the Kea subscriber package puts the files into a
|
||||
directory named ``premium``. Regardless of the name of the package, the
|
||||
directory is always called ``premium``.
|
||||
|
||||
4. Run the ``autoreconf`` tools. This step is necessary to update Kea's build
|
||||
script to include the additional directory. If this tool is not already
|
||||
available on the system, install the ``automake`` and ``autoconf``
|
||||
tools. To generate the configure script, please use:
|
||||
4. Set up the build. Make sure ``meson`` and ``ninja`` are installed on your
|
||||
system. The first section of the output should look something like this:
|
||||
|
||||
::
|
||||
.. code-block:: console
|
||||
|
||||
$ autoreconf -i
|
||||
|
||||
5. Rerun ``configure``, using the same configuration options that were used when
|
||||
originally building Kea. It is possible to verify that ``configure`` has detected the
|
||||
subscriber package by inspecting the summary printed when it exits. The
|
||||
first section of the output should look something like this:
|
||||
$ meson setup build
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
Package:
|
||||
Name: kea
|
||||
Version: |release|
|
||||
Extended version: |release| (tarball)
|
||||
OS Family: Linux
|
||||
Using GNU sed: yes
|
||||
Premium package: yes
|
||||
Included Hooks: cb_cmds rbac
|
||||
Package:
|
||||
Name: kea
|
||||
Version: |release|
|
||||
Extended version: |release| (tarball)
|
||||
Version type: development
|
||||
OS Family: Linux
|
||||
|
||||
The last line indicates which specific hooks were detected. Note that
|
||||
some hooks may require their own dedicated switches.
|
||||
Please consult later sections of this chapter for details.
|
||||
Prefix: /opt/kea
|
||||
Hooks directory: /opt/kea/lib/kea/hooks
|
||||
Premium hooks: yes
|
||||
|
||||
6. Rebuild Kea.
|
||||
6. Compile Kea.
|
||||
|
||||
::
|
||||
.. code-block:: console
|
||||
|
||||
$ make
|
||||
|
||||
If the machine has multiple CPU cores, an interesting option to consider
|
||||
here is using the argument ``-j X``, where ``X`` is the number of available cores.
|
||||
$ meson compile -C build
|
||||
|
||||
7. Install Kea sources along with the hooks:
|
||||
|
||||
@ -148,11 +136,11 @@ here is using the argument ``-j X``, where ``X`` is the number of available core
|
||||
$ sudo make install
|
||||
|
||||
The installation location of the hook libraries depends on whether the
|
||||
``--prefix`` parameter was specified in the ``configure`` script. If not,
|
||||
``--prefix`` parameter was specified at the ``meson setup`` step. If not,
|
||||
the default location is ``/usr/local/lib/kea/hooks``. The proper installation
|
||||
of the libraries can be verified with this command:
|
||||
|
||||
::
|
||||
.. code-block:: console
|
||||
|
||||
$ ls -l /usr/local/lib/kea/hooks/*.so
|
||||
/usr/local/lib/kea/hooks/libddns_gss_tsig.so
|
||||
@ -179,17 +167,18 @@ of the libraries can be verified with this command:
|
||||
|
||||
with the following subscriber libraries:
|
||||
|
||||
::
|
||||
.. code-block:: console
|
||||
|
||||
/usr/local/lib/kea/hooks/libdhcp_rbac.so
|
||||
/usr/local/lib/kea/hooks/libca_rbac.so -> libdhcp_rbac.so
|
||||
/usr/local/lib/kea/hooks/libdhcp_cb_cmds.so
|
||||
/usr/local/lib/kea/hooks/libdhcp_rbac.so
|
||||
|
||||
The exact list returned depends on the packages installed. If the
|
||||
directory was specified via ``--prefix``, the hook libraries will be located in
|
||||
``{prefix directory}/lib/kea/hooks``.
|
||||
|
||||
Configuring Hook Libraries
|
||||
===========================
|
||||
==========================
|
||||
|
||||
The hook libraries for a given process are configured using the
|
||||
``hooks-libraries`` keyword in the configuration for that process. (Note
|
||||
@ -198,65 +187,77 @@ of map structures, with each structure corresponding to a hook library. For
|
||||
example, to set up two hook libraries for the DHCPv4 server, the
|
||||
configuration would be:
|
||||
|
||||
::
|
||||
.. code-block:: json
|
||||
|
||||
"Dhcp4": {
|
||||
:
|
||||
"hooks-libraries": [
|
||||
{
|
||||
"library": "/opt/first_custom_hooks_example.so"
|
||||
},
|
||||
{
|
||||
"library": "/opt/local/second_custom_hooks_example.so",
|
||||
"parameters": {
|
||||
"mail": "spam@example.com",
|
||||
"floor": 13,
|
||||
"debug": false,
|
||||
"users": [ "alice", "bob", "charlie" ],
|
||||
"languages": {
|
||||
"french": "bonjour",
|
||||
"klingon": "yl'el"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
:
|
||||
}
|
||||
{
|
||||
"Dhcp6": {
|
||||
"hooks-libraries": [
|
||||
{
|
||||
"library": "/opt/first_custom_hooks_example.so"
|
||||
},
|
||||
{
|
||||
"library": "/opt/local/second_custom_hooks_example.so",
|
||||
"parameters": {
|
||||
"mail": "spam@example.com",
|
||||
"floor": 13,
|
||||
"debug": false,
|
||||
"users": [
|
||||
"alice",
|
||||
"bob",
|
||||
"charlie"
|
||||
],
|
||||
"languages": {
|
||||
"french": "bonjour",
|
||||
"klingon": "yl'el"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
.. note::
|
||||
|
||||
Libraries are reloaded even if their lists have not changed,
|
||||
because the parameters specified for the library (or the files those
|
||||
parameters point to) may have changed.
|
||||
Libraries are reloaded even if their lists have not changed,
|
||||
because the parameters specified for the library (or the files those
|
||||
parameters point to) may have changed.
|
||||
|
||||
Since Kea-2.7.6, the server is able to load hook libraries specifying only the binary name,
|
||||
if they reside in the default installation directory (the path is OS specific).
|
||||
The default hook libraries installation path is provided in the config report as
|
||||
"Hooks directory".
|
||||
|
||||
::
|
||||
.. code-block:: json
|
||||
|
||||
"hooks-libraries": [
|
||||
{
|
||||
"library": "first_custom_hooks_example.so"
|
||||
},
|
||||
{
|
||||
"library": "second_custom_hooks_example.so"
|
||||
}
|
||||
]
|
||||
{
|
||||
"Dhcp6": {
|
||||
"hooks-libraries": [
|
||||
{
|
||||
"library": "first_custom_hooks_example.so"
|
||||
},
|
||||
{
|
||||
"library": "second_custom_hooks_example.so"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
This snippet (on Ubuntu 24.04) is equivalent to:
|
||||
This snippet (on Debian 12) is equivalent to:
|
||||
|
||||
::
|
||||
.. code-block:: json
|
||||
|
||||
"hooks-libraries": [
|
||||
{
|
||||
"library": "/usr/lib/x86_64-linux-gnu/kea/hooks/first_custom_hooks_example.so"
|
||||
},
|
||||
{
|
||||
"library": "/usr/lib/x86_64-linux-gnu/kea/hooks/second_custom_hooks_example.so"
|
||||
}
|
||||
]
|
||||
{
|
||||
"Dhcp6": {
|
||||
"hooks-libraries": [
|
||||
{
|
||||
"library": "/usr/lib/x86_64-linux-gnu/kea/hooks/first_custom_hooks_example.so"
|
||||
},
|
||||
{
|
||||
"library": "/usr/lib/x86_64-linux-gnu/kea/hooks/second_custom_hooks_example.so"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
Libraries may have additional parameters that are not mandatory, in the
|
||||
sense that there may be libraries that do not require them. However, for any
|
||||
|
||||
@ -172,34 +172,34 @@ the system:
|
||||
- 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
|
||||
``-D 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.
|
||||
|
||||
- The PostgreSQL client and the client development libraries, when using the
|
||||
``--with-pgsql`` configuration flag to build the Kea PostgreSQL database
|
||||
``-D postgresql`` configuration flag to build the Kea PostgreSQL database
|
||||
backend. In this case an instance of the PostgreSQL server running locally
|
||||
or on a machine reachable over a network is required. Note that running
|
||||
the unit tests requires a local PostgreSQL server.
|
||||
|
||||
- Sysrepo v1.4.140 and libyang v1.0.240, needed to connect to a Sysrepo
|
||||
datastore. Earlier versions are no longer supported. When compiling from
|
||||
sources, the configure switches that can be used are ``--with-libyang`` and
|
||||
``--with-sysrepo`` without any parameters. If these dependencies were
|
||||
installed in custom paths, point the switches to them.
|
||||
sources, the configure switch that can be used is ``-D netconf``.
|
||||
If these dependencies were installed in custom paths, point PKG_CONFIG_PATH
|
||||
to them.
|
||||
|
||||
- The MIT Kerberos 5 or Heimdal libraries are needed by Kea DDNS server to sign
|
||||
and verify DNS updates using GSS-TSIG. The configuration switch which enables
|
||||
this functionality is ``--with-gssapi``, without any parameters. If these
|
||||
dependencies were installed in custom paths, point the switch to them.
|
||||
- The MIT Kerberos 5 or Heimdal libraries are needed by Kea DDNS server to
|
||||
sign and verify DNS updates using GSS-TSIG. The configuration switch which
|
||||
enables this functionality is ``-D krb5``. If this dependency is installed
|
||||
in a custom path, point PKG_CONFIG_PATH to the .pc file or PATH to the
|
||||
krb5-config tool.
|
||||
|
||||
- googletest (version 1.8 or later) is required when using the ``--with-gtest``
|
||||
- googletest (version 1.8 or later) is required when using the ``-D tests``
|
||||
configuration option to build the unit tests.
|
||||
|
||||
- The documentation generation tools `Sphinx <https://www.sphinx-doc.org/>`_,
|
||||
texlive with its extensions, and Doxygen, if using the
|
||||
``--enable-generate-docs`` configuration option to create the documentation.
|
||||
texlive with its extensions, and Doxygen, to create the documentation.
|
||||
Specifically, with Fedora, ``python3-sphinx``, ``python3-sphinx_rtd_theme``,
|
||||
``texlive``, and ``texlive-collection-latexextra`` are necessary.
|
||||
With Ubuntu, ``python3-sphinx``, ``python3-sphinx-rtd-theme``,
|
||||
@ -277,11 +277,8 @@ The code can be checked out from
|
||||
|
||||
$ 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 or the Makefile.in files, nor their related build
|
||||
files. Those can be created by running ``autoreconf`` with the
|
||||
``--install`` switch, which will run ``autoconf``, ``aclocal``,
|
||||
``libtoolize``, ``autoheader``, ``automake``, and related commands.
|
||||
The code checked out from the git repository does not include the build files.
|
||||
They can be created by running ``meson setup build``.
|
||||
|
||||
Write access to the Kea repository is only granted to ISC staff.
|
||||
Developers planning to contribute to Kea should check our
|
||||
@ -292,144 +289,71 @@ Guide <https://reports.kea.isc.org/dev_guide/>`__ contains more
|
||||
information about the process, and describes the requirements for
|
||||
contributed code to be accepted by ISC.
|
||||
|
||||
.. _configure:
|
||||
.. _setup:
|
||||
|
||||
Configure Before the Build
|
||||
--------------------------
|
||||
Set up the Build
|
||||
----------------
|
||||
|
||||
Kea uses the GNU Build System to discover build environment details. To
|
||||
generate the makefiles using the defaults, simply run:
|
||||
Kea uses Meson to discover build environment details. To generate the ninja
|
||||
file using the defaults, simply run:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ ./configure
|
||||
$ meson setup build
|
||||
|
||||
Run ``./configure`` with the ``--help`` switch to view the different
|
||||
options. Some commonly used options are:
|
||||
Run ``meson configure`` to view the different build options.
|
||||
Some commonly used options are:
|
||||
|
||||
- ``--prefix``
|
||||
Define the installation location (the default is ``/usr/local``).
|
||||
|
||||
- ``--with-mysql``
|
||||
- ``-D mysql``
|
||||
Build Kea with code to allow it to store leases and host reservations
|
||||
in a MySQL database.
|
||||
|
||||
- ``--with-pgsql``
|
||||
- ``-D pgsql``
|
||||
Build Kea with code to allow it to store leases and host reservations
|
||||
in a PostgreSQL database.
|
||||
|
||||
- ``--with-log4cplus``
|
||||
Define the path to find the Log4cplus headers and libraries. Normally
|
||||
this is not necessary.
|
||||
- ``-D krb5``
|
||||
Build Kea with Kerberos5 with GSS-API support required by
|
||||
:ischooklib:`libddns_gss_tsig.so`.
|
||||
|
||||
- ``--with-boost-include``
|
||||
Define the path to find the Boost headers. Normally this is not
|
||||
necessary.
|
||||
- ``-D netconf``
|
||||
Build Kea with libyang and sysrepo support required by
|
||||
:iscman:`kea-netconf`.
|
||||
|
||||
- ``--with-botan``
|
||||
- ``-D crypto=botan``
|
||||
Specify the name of the Botan pkg-config library e.g. ``botan-2``
|
||||
to build with Botan for cryptographic functions. It is preferable
|
||||
to use OpenSSL (see below).
|
||||
|
||||
- ``--with-openssl``
|
||||
- ``--D crypto=openssl``
|
||||
Use the OpenSSL cryptographic library instead of Botan. By default
|
||||
``configure`` searches for a valid Botan installation; if one is not
|
||||
Meson searches for a valid Botan installation; if one is not
|
||||
found, Kea searches for OpenSSL. Normally this is not necessary.
|
||||
|
||||
- ``--enable-shell``
|
||||
Build the optional :iscman:`kea-shell` tool (see :ref:`kea-shell`).
|
||||
The default is to not build it.
|
||||
|
||||
- ``--with-site-packages``
|
||||
Install the kea-shell Python packages in the specified directory; this
|
||||
is only useful when :iscman:`kea-shell` is enabled, and is
|
||||
mostly helpful for Debian-related distributions. While most systems store
|
||||
Python packages in ``${prefix}/usr/lib/pythonX/site-packages``, Debian
|
||||
introduced a separate directory for packages installed from DEB. Such
|
||||
Python packages are expected to be installed in
|
||||
``/usr/lib/python3/dist-packages``.
|
||||
|
||||
- ``--enable-perfdhcp``
|
||||
Build the optional :iscman:`perfdhcp` DHCP benchmarking tool. The default
|
||||
is to not build it.
|
||||
|
||||
.. note::
|
||||
|
||||
For instructions concerning the installation and configuration of
|
||||
database backends for Kea, see :ref:`dhcp-install-configure`.
|
||||
|
||||
There are many 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:
|
||||
If ``meson setup build`` fails, it may be due to missing or old dependencies.
|
||||
|
||||
- ``--with-gtest``, ``--with-gtest-source``
|
||||
Enable the building of C++ unit tests using the Google Test
|
||||
framework. This option specifies the path to the gtest source. (If
|
||||
the framework is not installed on the system, it can be downloaded
|
||||
from https://github.com/google/googletest.)
|
||||
|
||||
- ``--enable-generate-docs``
|
||||
Enable the rebuilding of Kea documentation. ISC publishes Kea
|
||||
documentation for each release; however, in some cases it may be
|
||||
desirable to rebuild it: for example, to change something in the
|
||||
docs, or to generate new ones from git sources that are not yet
|
||||
released.
|
||||
|
||||
- ``--enable-generate-parser``
|
||||
Enable the generation of parsers using flex or bison. Kea sources include
|
||||
.cc and .h parser files, pre-generated for users' convenience. By
|
||||
default Kea does not use flex or bison, to avoid
|
||||
requiring installation of unnecessary dependencies for users.
|
||||
However, if anything in the parsers is changed (such as adding a new
|
||||
parameter), flex and bison are required to regenerate
|
||||
parsers. This option permits that.
|
||||
|
||||
- ``--enable-generate-messages``
|
||||
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
|
||||
anything in a .mes file is changed (such as adding a new message),
|
||||
the Kea message compiler needs to be built and used. This option
|
||||
permits that.
|
||||
|
||||
As an 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:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ ./configure \
|
||||
--with-boost-include=/usr/pkg/include \
|
||||
--with-pgsql=/usr/local/bin/pg_config \
|
||||
--prefix=/opt/kea
|
||||
|
||||
Users who have any problems with building Kea using the header-only Boost
|
||||
code, or who would like to use the Boost system library (assumed for the
|
||||
sake of this example to be located in /usr/pkg/lib), should issue these
|
||||
commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ ./configure \
|
||||
--with-boost-libs=-lboost_system \
|
||||
--with-boost-lib-dir=/usr/pkg/lib
|
||||
|
||||
If ``configure`` fails, it may be due to missing or old dependencies.
|
||||
|
||||
When ``configure`` succeeds, it displays a report with the parameters used
|
||||
to build the code. This report is saved into the file ``config.report``
|
||||
and is also embedded into the executable binaries, e.g. :iscman:`kea-dhcp4`.
|
||||
When ``meson setup build`` succeeds, it displays a report with the parameters
|
||||
used to build the code. This report is saved into the file
|
||||
``build/config.report`` and is also embedded into the executable binaries, e.g.
|
||||
:iscman:`kea-dhcp6`.
|
||||
|
||||
Build
|
||||
-----
|
||||
|
||||
After the configure step is complete, build the executables from the C++
|
||||
After the setup step is complete, build the executables from the C++
|
||||
code and prepare the Python scripts by running the command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make
|
||||
$ meson compile -C build
|
||||
|
||||
Install
|
||||
-------
|
||||
@ -439,33 +363,28 @@ the command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make install
|
||||
|
||||
Do not use any form of parallel or job server options (such as GNU
|
||||
make's ``-j`` option) when performing this step; doing so may cause
|
||||
errors.
|
||||
$ meson install -C build
|
||||
|
||||
.. note::
|
||||
|
||||
The install step may require superuser privileges.
|
||||
|
||||
If required, run ``ldconfig`` as root with ``/usr/local/lib`` (or with
|
||||
prefix/lib if configured with ``--prefix``) in ``/etc/ld.so.conf`` (or the
|
||||
relevant linker cache configuration file for the OS):
|
||||
It should not be required, but if shared libraries are not found at runtime,
|
||||
you can run ``ldconfig`` as root with ``/usr/local/lib`` (or with
|
||||
``${prefix}/lib`` if set up with ``--prefix``) in ``/etc/ld.so.conf`` (or
|
||||
the relevant linker cache configuration file for the OS):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ ldconfig
|
||||
|
||||
.. note::
|
||||
If ``ldconfig`` is not run where required, users may see
|
||||
errors like the following:
|
||||
|
||||
If ``ldconfig`` is not run where required, users may see
|
||||
errors like the following:
|
||||
::
|
||||
|
||||
::
|
||||
|
||||
program: error while loading shared libraries: libkea-something.so.1:
|
||||
cannot open shared object file: No such file or directory
|
||||
program: error while loading shared libraries: libkea-something.so.1:
|
||||
cannot open shared object file: No such file or directory
|
||||
|
||||
|
||||
Cross-Building
|
||||
@ -498,7 +417,7 @@ the creation of the lease database.
|
||||
|
||||
.. note::
|
||||
|
||||
When unit tests are built with Kea (i.e. the ``--with-gtest`` configuration
|
||||
When unit tests are built with Kea (i.e. the ``-D tests`` 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
|
||||
@ -512,53 +431,45 @@ development libraries must be installed.
|
||||
|
||||
Build and install Kea as described in :ref:`installation`,
|
||||
with the following modification. To enable the MySQL database code, at the
|
||||
"configure" step (see :ref:`configure`), the ``--with-mysql`` switch should be
|
||||
specified:
|
||||
setup step (see :ref:`setup`), the ``-D mysql`` switch should be specified:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ ./configure [other-options] --with-mysql
|
||||
$ meson setup build -D mysql=enabled
|
||||
|
||||
If MySQL was not installed in the default location, the location of the
|
||||
MySQL configuration program "mysql_config" should be included with the
|
||||
switch:
|
||||
If MySQL was not installed in the default location, the location can be
|
||||
selected by setting ``PKG_CONFIG_PATH=/path/to/mariadb.pc:${PKG_CONFIG_PATH}``
|
||||
or ``PATH=/path/to/mariadb-config:${PATH}`` prior to ``meson setup``.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ ./configure [other-options] --with-mysql=path-to-mysql_config
|
||||
$ PKG_CONFIG_PATH=/opt/mariadb/lib/pkgconfig PATH=/opt/mariadb/bin meson setup build -D mysql=enabled
|
||||
|
||||
See :ref:`mysql-database-create` for details regarding MySQL
|
||||
database configuration.
|
||||
|
||||
Building with PostgreSQL support
|
||||
Building with PostgreSQL Support
|
||||
--------------------------------
|
||||
|
||||
Install PostgreSQL according to the instructions for the system. The
|
||||
client development libraries must be installed. Client development
|
||||
libraries are often packaged as "libpq".
|
||||
libraries are often packaged as ``libpq``.
|
||||
|
||||
Build and install Kea as described in :ref:`installation`,
|
||||
with the following modification. To enable the PostgreSQL database code, at the
|
||||
"configure" step (see :ref:`configure`), the ``--with-pgsql`` switch should be
|
||||
specified:
|
||||
setup step (see :ref:`setup`), the ``-D postgresql`` switch should be specified:
|
||||
|
||||
If PostgreSQL was not installed in the default location, the location can be
|
||||
selected by setting ``PKG_CONFIG_PATH=/path/to/libpq.pc:${PKG_CONFIG_PATH}``
|
||||
or ``PATH=/path/to/pg_config:${PATH}`` prior to ``meson setup``.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ ./configure [other-options] --with-pgsql
|
||||
|
||||
If PostgreSQL was not installed in the default location, the location of
|
||||
the PostgreSQL configuration program "pg_config" should be included with
|
||||
the switch:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ ./configure [other-options] --with-pgsql=path-to-pg_config
|
||||
$ PKG_CONFIG_PATH=/opt/postgresql/lib/pkgconfig PATH=/opt/postgresql/bin meson setup build -D postgresql=enabled
|
||||
|
||||
See :ref:`pgsql-database-create` for details regarding PostgreSQL
|
||||
database configuration.
|
||||
|
||||
|
||||
|
||||
.. include:: hammer.rst
|
||||
|
||||
.. _non-root:
|
||||
|
||||
@ -32,20 +32,20 @@ Quick Start Guide Using tarball
|
||||
.. parsed-literal::
|
||||
|
||||
$ cd kea-|release|
|
||||
$ ./configure [your extra parameters]
|
||||
$ meson setup build [your extra parameters]
|
||||
|
||||
5. Build it:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make
|
||||
$ meson compile -C build
|
||||
|
||||
6. Install it (by default it will be placed in ``/usr/local/``, so
|
||||
root privileges are likely required for this step):
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ make install
|
||||
$ meson install -C build
|
||||
|
||||
.. _quick-start-repo:
|
||||
|
||||
|
||||
@ -7319,8 +7319,8 @@ TEST_F(Dhcp4ParserTest, configControlInfoNoFactory) {
|
||||
configure(config, CONTROL_RESULT_ERROR,
|
||||
"during update from config backend database: "
|
||||
"The Kea server has not been compiled with support for configuration "
|
||||
"database type: mysql. Did you forget to use --with-mysql during "
|
||||
"compilation or to load libdhcp_mysql hook library?");
|
||||
"database type: mysql. Did you forget to use -Dmysql during "
|
||||
"setup or to load libdhcp_mysql hook library?");
|
||||
}
|
||||
|
||||
// This test verifies that configuration control info gets populated.
|
||||
|
||||
@ -3370,8 +3370,7 @@ void DORATest::checkStat(string const& name,
|
||||
}
|
||||
|
||||
// Starting tests which require MySQL backend availability. Those tests
|
||||
// will not be executed if Kea has been compiled without the
|
||||
// --with-mysql.
|
||||
// will not be executed if Kea has been compiled without MySQL support.
|
||||
#ifdef HAVE_MYSQL
|
||||
|
||||
/// @brief Test fixture class for the test utilizing MySQL database backend.
|
||||
@ -3416,8 +3415,7 @@ TEST_F(DORAMySQLTest, multiStageBootMultiThreading) {
|
||||
#endif
|
||||
|
||||
// Starting tests which require MySQL backend availability. Those tests
|
||||
// will not be executed if Kea has been compiled without the
|
||||
// --with-pgsql.
|
||||
// will not be executed if Kea has been compiled without PostgreSQL support.
|
||||
#ifdef HAVE_PGSQL
|
||||
|
||||
/// @brief Test fixture class for the test utilizing PostgreSQL database backend.
|
||||
|
||||
@ -970,8 +970,7 @@ TEST_F(JSONFileBackendTest, configBackendPullCommandWithTimer) {
|
||||
}
|
||||
|
||||
// Starting tests which require MySQL backend availability. Those tests
|
||||
// will not be executed if Kea has been compiled without the
|
||||
// --with-mysql.
|
||||
// will not be executed if Kea has been compiled without MySQL support.
|
||||
#ifdef HAVE_MYSQL
|
||||
|
||||
/// @brief Test fixture class for the tests utilizing MySQL database
|
||||
|
||||
@ -8169,8 +8169,8 @@ TEST_F(Dhcp6ParserTest, configControlInfoNoFactory) {
|
||||
configure(config, CONTROL_RESULT_ERROR,
|
||||
"during update from config backend database: "
|
||||
"The Kea server has not been compiled with support for configuration "
|
||||
"database type: mysql. Did you forget to use --with-mysql during "
|
||||
"compilation or to load libdhcp_mysql hook library?");
|
||||
"database type: mysql. Did you forget to use -Dmysql during "
|
||||
"setup or to load libdhcp_mysql hook library?");
|
||||
}
|
||||
|
||||
// This test verifies that configuration control info gets populated.
|
||||
@ -9303,7 +9303,7 @@ TEST_F(Dhcp6ParserTest, ddnsTtlPercent) {
|
||||
{
|
||||
"ddns-ttl-percent": 0.75,
|
||||
"valid-lifetime": 4000,
|
||||
"shared-networks": [{
|
||||
"shared-networks": [{
|
||||
"name": "net",
|
||||
"ddns-ttl-percent": 0.50,
|
||||
"subnet6": [{
|
||||
@ -9348,7 +9348,7 @@ TEST_F(Dhcp6ParserTest, ddnsTtl) {
|
||||
{
|
||||
"ddns-ttl": 750,
|
||||
"valid-lifetime": 4000,
|
||||
"shared-networks": [{
|
||||
"shared-networks": [{
|
||||
"name": "net",
|
||||
"ddns-ttl": 500,
|
||||
"subnet6": [{
|
||||
@ -9394,7 +9394,7 @@ TEST_F(Dhcp6ParserTest, ddnsTtlMin) {
|
||||
{
|
||||
"ddns-ttl-min": 750,
|
||||
"valid-lifetime": 4000,
|
||||
"shared-networks": [{
|
||||
"shared-networks": [{
|
||||
"name": "net",
|
||||
"ddns-ttl-min": 500,
|
||||
"subnet6": [{
|
||||
@ -9440,7 +9440,7 @@ TEST_F(Dhcp6ParserTest, ddnsTtlMax) {
|
||||
{
|
||||
"ddns-ttl-max": 750,
|
||||
"valid-lifetime": 4000,
|
||||
"shared-networks": [{
|
||||
"shared-networks": [{
|
||||
"name": "net",
|
||||
"ddns-ttl-max": 500,
|
||||
"subnet6": [{
|
||||
|
||||
@ -669,7 +669,7 @@ public:
|
||||
/// @brief Updates inherited subnet and pool members
|
||||
///
|
||||
/// Hack added to set subnet_ and pool_ members that are buried into lower
|
||||
/// level tests such as checkLease(), so one can use "configure" functionality
|
||||
/// level tests such as checkLease(), so one can use "meson setup" functionality
|
||||
/// rather than hand-building configured objects
|
||||
/// @param subnet_idx Element index of the desired subnet
|
||||
/// @param pool_idx Element index of the desired pool within the desired subnet
|
||||
|
||||
@ -955,8 +955,7 @@ TEST_F(JSONFileBackendTest, configBackendPullCommandWithTimer) {
|
||||
}
|
||||
|
||||
// Starting tests which require MySQL backend availability. Those tests
|
||||
// will not be executed if Kea has been compiled without the
|
||||
// --with-mysql.
|
||||
// will not be executed if Kea has been compiled without MySQL support.
|
||||
#ifdef HAVE_MYSQL
|
||||
|
||||
/// @brief Test fixture class for the tests utilizing MySQL database
|
||||
|
||||
@ -105,12 +105,10 @@ in html/ directory.
|
||||
|
||||
Similar to all other code in Kea, also this library comes with unit-tests that
|
||||
use googletest framework. Those tests are stored in tests/ directory. To build
|
||||
and run them, you need to pass --with-gtest or --with-gtest-source to the
|
||||
configure script. Once the code builds, you can run tests with make check. This
|
||||
command can be run in top-level Kea directory (all tests will be run) or in more
|
||||
specific directory (only a subset of tests will be run). For example, make check
|
||||
issued in src/hooks/dhcp/class_cmds will run only tests for class_cmds
|
||||
library.
|
||||
and run them, you need to pass -Dtests=enabled to the "meson setup" command
|
||||
line. Once the code builds, you can run tests with "meson compile". This
|
||||
command can be run in top-level build directory (all tests will be run) or by
|
||||
running tests on this library only "meson test -C build dhcp-class-cmds-tests".
|
||||
|
||||
@section class_cmdsMTCompatibility Multi-Threading Compatibility
|
||||
|
||||
|
||||
@ -180,12 +180,10 @@ in html/ directory.
|
||||
|
||||
Similar to all other code in Kea, also this library comes with unit-tests that
|
||||
use googletest framework. Those tests are stored in tests/ directory. To build
|
||||
and run them, you need to pass --with-gtest or --with-gtest-source to the
|
||||
configure script. Once the code builds, you can run tests with make check. This
|
||||
command can be run in top-level Kea directory (all tests will be run) or in more
|
||||
specific directory (only a subset of tests will be run). For example, make check
|
||||
issued in src/hooks/dhcp/host_cmds will run only tests for host_cmds
|
||||
library.
|
||||
and run them, you need to pass -Dtests=enabled to the "meson setup" command
|
||||
line. Once the code builds, you can run tests with "meson compile". This
|
||||
command can be run in top-level build directory (all tests will be run) or by
|
||||
running tests on this library only "meson test -C build dhcp-host-cmds-tests".
|
||||
|
||||
@section host_cmdsMTCompatibility Multi-Threading Compatibility
|
||||
|
||||
|
||||
@ -168,7 +168,7 @@ public:
|
||||
std::string with = (db_type == "postgresql" ? "pgsql" : db_type);
|
||||
isc_throw(db::InvalidType, "The Kea server has not been compiled with "
|
||||
"support for configuration database type: " << db_type
|
||||
<< ". Did you forget to use --with-"
|
||||
<< ". Did you forget to use -D"
|
||||
<< with << " during compilation or to load libdhcp_"
|
||||
<< with << " hook library?");
|
||||
}
|
||||
|
||||
@ -23,14 +23,14 @@
|
||||
|
||||
- The MySQL lease manager uses the freely available MySQL as its backend
|
||||
database. This is not included in Kea DHCP by default:
|
||||
the \--with-mysql switch must be supplied to "configure" for support to be
|
||||
the \-Dmysql switch must be supplied to "meson setup" for support to be
|
||||
compiled into the software. This will also compile the "libdhcp_mysql.so" hook
|
||||
library which must be loaded by adding it to the "hooks-libraries"
|
||||
configuration parameter.
|
||||
|
||||
- The PostgreSQL lease manager uses the freely available PostgreSQL as its
|
||||
backend database. This is not included in Kea DHCP by default:
|
||||
the \--with-pgsql switch must be supplied to "configure" for support to be
|
||||
the \-Dpostgresql switch must be supplied to "meson setup" for support to be
|
||||
compiled into the software. This will also compile the "libdhcp_pgsql.so" hook
|
||||
library which must be loaded by adding it to the "hooks-libraries"
|
||||
configuration parameter.
|
||||
|
||||
@ -51,7 +51,7 @@ HostDataSourceFactory::add(HostDataSourceList& sources,
|
||||
string with = (db_type == "postgresql" ? "pgsql" : db_type);
|
||||
isc_throw(InvalidType, "The Kea server has not been compiled with "
|
||||
"support for host database type: " << db_type
|
||||
<< ". Did you forget to use --with-"
|
||||
<< ". Did you forget to use -D"
|
||||
<< with << " during compilation or to load libdhcp_"
|
||||
<< with << " hook library?");
|
||||
}
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2012-2024 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2012-2025 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
|
||||
@ -65,7 +65,7 @@ LeaseMgrFactory::create(const std::string& dbaccess) {
|
||||
string with = (db_type == "postgresql" ? "pgsql" : db_type);
|
||||
isc_throw(InvalidType, "The Kea server has not been compiled with "
|
||||
"support for lease database type: " << db_type
|
||||
<< ". Did you forget to use --with-"
|
||||
<< ". Did you forget to use -D"
|
||||
<< with << " during compilation or to load libdhcp_"
|
||||
<< with << " hook library?");
|
||||
}
|
||||
|
||||
@ -86,7 +86,7 @@ LegalLogMgrFactory::addBackend(DatabaseConnection::ParameterMap& parameters, Man
|
||||
string with = (db_type == "postgresql" ? "pgsql" : db_type);
|
||||
isc_throw(InvalidType, "The Kea server has not been compiled with "
|
||||
"support for configuration database type: " << db_type
|
||||
<< ". Did you forget to use --with-"
|
||||
<< ". Did you forget to use -D"
|
||||
<< with << " during compilation or to load libdhcp_"
|
||||
<< with << " hook library?");
|
||||
}
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2015-2024 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2015-2025 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
|
||||
@ -103,7 +103,7 @@ When the actual case is determined, the respective C++ action
|
||||
is executed. For example, if the token is a string, the TokenString class is
|
||||
instantiated with the appropriate value and put onto the expression vector.
|
||||
|
||||
@section dhcpEvalMakefile Generating parser files
|
||||
@section dhcpEval Generating parser files
|
||||
|
||||
In the general case, we want to avoid generating parser files, so an
|
||||
average user interested in just compiling Kea would not need flex or
|
||||
@ -114,14 +114,9 @@ instantiated with the appropriate value and put onto the expression vector.
|
||||
to tweak the lexer.ll and parser.yy files and then regenerate
|
||||
the code. For this purpose, two makefile targets are defined:
|
||||
@code
|
||||
make parser
|
||||
meson compile -C parser
|
||||
@endcode
|
||||
will generate the parsers and
|
||||
@code
|
||||
make parser-clean
|
||||
@endcode
|
||||
will remove the files. Generated files removal was also hooked
|
||||
into the maintainer-clean target.
|
||||
will generate the parsers.
|
||||
|
||||
@section dhcpEvalConfigure Configure options
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2013-2024 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2013-2025 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
|
||||
@ -892,7 +892,7 @@ g++ -I <install-dir>/include/kea -L <install-dir>/lib -fpic -shared -o example.s
|
||||
|
||||
Notes:
|
||||
- Replace "<install-dir>" with the location in which you installed Kea. Unless
|
||||
you specified the "--prefix" switch on the "configure" command line when
|
||||
you specified the "--prefix" switch on the "meson setup" command line when
|
||||
building Kea, it will be installed in the default location, usually /usr/local.
|
||||
- The compilation command and switches required may vary depending on
|
||||
your operating system and compiler - consult the relevant documentation
|
||||
@ -1358,8 +1358,8 @@ a name will conflict with any existing or future Kea argument names.
|
||||
|
||||
@subsection hooksdgStaticallyLinkedKea Running Against a Statically-Linked Kea
|
||||
|
||||
If Kea is built with the --enable-static-link switch (set when
|
||||
running the "configure" script), no shared Kea libraries are built;
|
||||
If Kea is built with the "-Ddefault_library=static" switch (set when
|
||||
running the "meson setup" script), no shared Kea libraries are built;
|
||||
instead, archive libraries are created and Kea is linked to them.
|
||||
If you create a hooks library also linked against these archive libraries,
|
||||
when the library is loaded you end up with two copies of the library code,
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2013-2021 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2013-2025 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
|
||||
@ -403,70 +403,53 @@ The appearance of such a message indicates a programming error.
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
@subsubsection logMakefile Include Message Compilation in Makefile
|
||||
@subsubsection logMeson Include Message Compilation in meson.build
|
||||
The source file for the messages is the ".mes" file, but the files
|
||||
used by the code which must be compiled and linked are the output of
|
||||
the message compiler. (The compiler is produced very early on in the
|
||||
Kea build sequence, so is available for use in the building of
|
||||
subsequent components.) To allow this, certain dependencies must be
|
||||
included in the Makefile.am for each component that uses logging.
|
||||
included in the meson.build file for each component that uses logging.
|
||||
|
||||
<b>Including Message files in C++ Component Builds</b><br/>
|
||||
The following segment from the "hooks" Makefile.am illustrates
|
||||
The following segment from src/lib/log/meson.build illustrates
|
||||
the entries needed.
|
||||
@code
|
||||
# Ensure that the message file is included in the distribution
|
||||
EXTRA_DIST = hooks_messages.mes
|
||||
|
||||
# If we want to get rid of all generated messages files, we need to use
|
||||
# make maintainer-clean. The proper way to introduce custom commands for
|
||||
# that operation is to define maintainer-clean-local target. However,
|
||||
# make maintainer-clean also removes Makefile, so running configure script
|
||||
# is required. To make it easy to rebuild messages without going through
|
||||
# reconfigure, a new target messages-clean has been added.
|
||||
maintainer-clean-local:
|
||||
rm -f hooks_messages.h hooks_messages.cc
|
||||
|
||||
# To regenerate messages files, one can do:
|
||||
#
|
||||
# make messages-clean
|
||||
# make messages
|
||||
#
|
||||
# This is needed only when a .mes file is modified.
|
||||
messages-clean: maintainer-clean-local
|
||||
|
||||
if GENERATE_MESSAGES
|
||||
|
||||
# Define rule to build logging source files from message file
|
||||
messages: hooks_messages.h hooks_messages.cc
|
||||
@echo Message files regenerated
|
||||
|
||||
hooks_messages.h hooks_messages.cc: hooks_messages.mes
|
||||
$(top_builddir)/src/lib/log/compiler/kea-msg-compiler $(top_srcdir)/src/lib/hooks/hooks_messages.mes
|
||||
|
||||
else
|
||||
|
||||
messages hooks_messages.h hooks_messages.cc:
|
||||
@echo Messages generation disabled. Configure with --enable-generate-messages to enable it.
|
||||
|
||||
if KEA_MSG_COMPILER.found()
|
||||
current_source_dir = meson.current_source_dir()
|
||||
target_gen_messages = run_target(
|
||||
'src-lib-log-log_messages',
|
||||
command: [
|
||||
CD_AND_RUN,
|
||||
TOP_SOURCE_DIR,
|
||||
KEA_MSG_COMPILER,
|
||||
'src/lib/log/log_messages.mes',
|
||||
],
|
||||
)
|
||||
TARGETS_GEN_MESSAGES += [target_gen_messages]
|
||||
target_gen_messages = run_target(
|
||||
'src-lib-log-logimpl_messages',
|
||||
command: [
|
||||
CD_AND_RUN,
|
||||
TOP_SOURCE_DIR,
|
||||
KEA_MSG_COMPILER,
|
||||
'src/lib/log/logimpl_messages.mes',
|
||||
],
|
||||
)
|
||||
TARGETS_GEN_MESSAGES += [target_gen_messages]
|
||||
endif
|
||||
@endcode
|
||||
|
||||
To regenerate messages files, one can do:
|
||||
@code@
|
||||
meson compile -C build messages
|
||||
@endcode@
|
||||
|
||||
The first rule adds a hook to make maintainer-clean which is the standard
|
||||
way to regenerate all messages files. The second rule adds the new
|
||||
messages-clean target to regenerate local messages files.
|
||||
|
||||
The GENERATE_MESSAGES conditional part is the (re)generation of
|
||||
the messages files. When configured with --enable-generate-messages
|
||||
and the source (.mes file) is newer these files are generated using
|
||||
the Kea message compiler. When configured without --enable-generate-messages
|
||||
(the default) and the source (.mes file) is newer a message is emitted.
|
||||
|
||||
Not shown are the Makefile.am lines where the .h and .cc file are used. These
|
||||
are the same as other lines specifying .h and .cc source files.
|
||||
|
||||
And finally please note the message header (e.g. hooks_messages.h)
|
||||
should be installed, i.e. in the include_HEADERS list.
|
||||
|
||||
@subsection logUsage Using Logging Files in Program Development
|
||||
|
||||
@subsubsection logCppUsage Use in a C++ Program or Module
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2018-2022 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2018-2025 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
|
||||
@ -174,7 +174,7 @@ category of adaptors are divided into:
|
||||
To run YANG/NETCONF/Sysrepo tests you need to compile Kea with Sysrepo support:
|
||||
|
||||
@verbatim
|
||||
./configure --with-libyang --with-sysrepo --with-libyang-cpp --with-sysrepo-cpp
|
||||
meson setup build -D netconf=enabled
|
||||
@endverbatim
|
||||
|
||||
For details, see Section "YANG/NETCONF support" in the Kea Administrator
|
||||
@ -192,7 +192,7 @@ non-root.
|
||||
To install all the modules, run the following script:
|
||||
|
||||
@verbatim
|
||||
./src/share/yang/modules/utils/reinstall.sh
|
||||
./build/src/share/yang/modules/utils/reinstall.sh
|
||||
@endverbatim
|
||||
|
||||
If the YANG modules are already installed, they will be upgraded.
|
||||
@ -200,7 +200,7 @@ To avoid any upgrade hastle, the -u flag may be passed to uninstall the modules
|
||||
before installing again.
|
||||
|
||||
@verbatim
|
||||
./src/share/yang/modules/utils/reinstall.sh -u
|
||||
./build/src/share/yang/modules/utils/reinstall.sh -u
|
||||
@endverbatim
|
||||
|
||||
Alternatively to install each module, issue the following command:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user