mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-22 01:49:48 +00:00
[#3732] Address review
This commit is contained in:
Andrei Pavel
parent
80fc384e21
commit
60222843a6
@ -191,7 +191,7 @@ 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 `–Dmysql` and/or `–Dpostgresql` as
|
||||
any database related code, make sure you compile your code with `–D mysql=enabled` and/or `–D postgresql=enabled` as
|
||||
needed. For example, if you change something substantial, make sure the other compilation options
|
||||
still work.
|
||||
|
||||
@ -200,7 +200,7 @@ various additional consistency checks that reduce performance but help during de
|
||||
|
||||
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`.
|
||||
enable the MySQL backend, use the switch `-D mysql=enabled`; for PostgreSQL, use `–D postgresql=enabled`.
|
||||
A complete list of all switches can be obtained with the command:
|
||||
|
||||
```bash
|
||||
|
||||
4
INSTALL
4
INSTALL
@ -7,9 +7,9 @@ PostgreSQL), you will need to specify these as options to the command (run
|
||||
|
||||
$ meson setup build
|
||||
|
||||
If your environment is missing dependencies, the configure script will exit
|
||||
If your environment is missing dependencies, the command 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
|
||||
proceed. A detailed account of the setup process is captured in
|
||||
build/meson-logs/meson-log.txt.
|
||||
|
||||
2. Build it. Once you've successfully set up the build, run "meson compile" to
|
||||
|
||||
@ -5,7 +5,6 @@ EXTRA_DIST += changelog.dox
|
||||
EXTRA_DIST += config-backend.dox
|
||||
EXTRA_DIST += congestion-handling.dox
|
||||
EXTRA_DIST += contribute.dox
|
||||
EXTRA_DIST += cross-compile.dox
|
||||
EXTRA_DIST += debug.dox
|
||||
EXTRA_DIST += doc.dox
|
||||
EXTRA_DIST += fuzz.dox
|
||||
|
||||
@ -1,228 +0,0 @@
|
||||
// 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
|
||||
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
||||
|
||||
/**
|
||||
|
||||
* @note Outdated.
|
||||
|
||||
@page crossCompile Kea Cross-Compiling Example
|
||||
|
||||
The idea is to install Kea on a Raspberry Pi 4 Model B running Raspbian
|
||||
operation system (e.g. the
|
||||
<a href="https://www.raspberrypi.org/software/operating-systems/">
|
||||
Raspbian Buster with desktop and recommended software</a> distribution)
|
||||
without having to compile Kea on the Raspberry Pi box itself as it
|
||||
takes some hours so using a standard Linux box with a x86_64 processor.
|
||||
|
||||
To cross-compile anything for Raspbian you need:
|
||||
- a cross-compiler running on x86_64 producing arm binaries
|
||||
- either an image of system copied from a Raspberry disk or extracted
|
||||
from a Raspbian repository.
|
||||
|
||||
@section toolChain Cross-Compile Tool Chain
|
||||
|
||||
A priori it is possible to compile your own tool chain or to use
|
||||
a package as the arm-linux-gnueabihf one on Ubuntu. But there is
|
||||
reported compatibility issue with old Raspberry Pi versions) so
|
||||
we recommend a pre-built dedicated tool chain for this purpose:
|
||||
<a href="https://github.com/Pro/raspi-toolchain">RaspberryPi toolchain on github</a>.
|
||||
|
||||
The documentation of this tool chain gives a rsync command which
|
||||
copies selected parts of the Raspberry Pi root filesystem ("rootfs").
|
||||
If you have no access to a running Raspberry Pi it is still possible
|
||||
to get them following next section instructions. If you have, simply
|
||||
skip this part.
|
||||
|
||||
@section noRaspberry How to get system and packages without a running Raspberry Pi
|
||||
|
||||
It is not required to have access to a running Raspberry Pi.
|
||||
The system disk image is available at the Raspbian URL.
|
||||
Packages are in the Raspian repository which is given in
|
||||
sources list files in this disk image or below.
|
||||
|
||||
The /etc/apt/sources.list file content is:
|
||||
@verbatim
|
||||
deb http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi
|
||||
# Uncomment line below then 'apt-get update' to enable 'apt-get source'
|
||||
# deb-src http://raspbian.raspberrypi.org/raspbian/ buster main contrib non-free rpi
|
||||
@endverbatim
|
||||
|
||||
and the /etc/apt/sources.list.d/raspi.list file content is:
|
||||
@verbatim
|
||||
deb http://archive.raspberrypi.org/debian/ buster main
|
||||
# Uncomment line below then 'apt-get update' to enable 'apt-get source'
|
||||
# deb-src http://archive.raspberrypi.org/debian/ buster main
|
||||
@endverbatim
|
||||
|
||||
The disk image is a zipped image of a 4GB disk with a standard MSDOS
|
||||
boot block with two volumes:
|
||||
- boot (useless for this purpose)
|
||||
- rootfs (the Raspberry Pi root filesystem)
|
||||
|
||||
The idea is to mount the rootfs on the Linux box (it can work on another
|
||||
system as soon as it supports the ext4 file system type):
|
||||
- first use fdisk or similar tool to get the offset of the first block
|
||||
of the rootfs (second) volume
|
||||
- if the offset is in block unit multiply by 512 (block size)
|
||||
- mount as root (sudo mount ...) with the loop option, the offset option,
|
||||
the unzipped image file name and a mount point (absolute path of
|
||||
a directory)
|
||||
If you have a SD card with Raspbian installed on it and a SD reader
|
||||
you can directly mount the rootfs from it.
|
||||
|
||||
If a dependency (i.e. the Raspbian version of a library) is not in the
|
||||
rootfs image you need to simulate its installation:
|
||||
- get the .deb file from a Raspbian repository
|
||||
- extract files using the dpkg-deb -R tool on the .deb file
|
||||
- install the files (usually in the "rootfs"/usr directory)
|
||||
The idea is the files (includes and libraries) can be found by
|
||||
the cross-compiling tool chain.
|
||||
|
||||
It is possible to emulate a Raspberry Pi using qemu even I do not think
|
||||
it can run Kea. But at least it can run some tests as the hello world sample
|
||||
of the tool chain. Required qemu kernels can be found in
|
||||
<a href="https://github.com/dhruvvyas90/qemu-rpi-kernel">this github repo</a> with
|
||||
a documentation, which is well worth reading.
|
||||
|
||||
@section crossCompilePitfalls Usual problems
|
||||
|
||||
There are two usual problems when cross-compiling:
|
||||
- have a binary for the wrong processor, e.g. either trying to run
|
||||
an arm binary on the x86_64 box or building a x86_64 binary when
|
||||
it will be run by the Raspberry Pi
|
||||
- use the x86_64 system include or library instead of the Raspberry Pi
|
||||
one from the rootfs image. Usually it gives a direct error for a library
|
||||
but a wrong include is more subtle.
|
||||
Note that Kea has a build tool (kea-msg-compiler) but its use is optional
|
||||
so it should not be a problem. If anyway you need it simply copy it from
|
||||
a native (i.e. not cross-compiled) Kea build.
|
||||
|
||||
@section raspbianDependencies Usual Kea Dependencies
|
||||
|
||||
Required and optional Kea dependencies, usually available as packages:
|
||||
- Python (built-in)
|
||||
- libssl-dev (built-in in the full image)
|
||||
- liblog4cplus-dev (in liblog4cplus package, load both the library and
|
||||
the development part)
|
||||
- libboost-system-dev (in boost-xxx, load both the boost-system and
|
||||
the boost-libraries packages, the second includes header files)
|
||||
- googletest (download the last release from github)
|
||||
- doc (sphinx, texlive, etc: just generate docs on the build system)
|
||||
- MySQL (in mysql-defaults and mariadb-* packages?)
|
||||
- PostgreSQL (in postgresql-12?)
|
||||
|
||||
@section prepareCrossCompile Prepare Cross Compiling
|
||||
|
||||
This script was used with success: it sets the environment variables
|
||||
before calling ./configure.
|
||||
@code
|
||||
# change when at another location
|
||||
export ROOTFS="$HOME/rpi/rootfs"
|
||||
|
||||
# build commands
|
||||
export BUILD=x86_64-pc-linux-gnu
|
||||
export HOST=arm-linux-gnueabihf
|
||||
export CC="${HOST}-gcc"
|
||||
export CXX="${HOST}-g++"
|
||||
export LD="${HOST}-ld"
|
||||
export AR="${HOST}-ar"
|
||||
export RANLIB="${HOST}-ranlib"
|
||||
export STRIP="${HOST}-strip"
|
||||
export NM="${HOST}-nm"
|
||||
|
||||
# g++ flags
|
||||
CXXFLAGS="-O2 -g -isysroot ${ROOTFS} -I${ROOTFS}/usr/include"
|
||||
CXXFLAGS+=" -I${ROOTFS}/usr/include/${HOST}"
|
||||
|
||||
# ld flags
|
||||
LDFLAGS="--sysroot=${ROOTFS}"
|
||||
LDFLAGS+=" -L/opt/cross-pi-gcc/arm-linux-gnueabihf/lib -Wl,-rpath-link,/opt/cross-pi-gcc/arm-linux-gnueabihf/lib"
|
||||
LDFLAGS+=" -L/opt/cross-pi-gcc/lib -Wl,-rpath-link,/opt/cross-pi-gcc/lib"
|
||||
LDFLAGS+=" -L${ROOTFS}/opt/vc/lib -Wl,-rpath-link,${ROOTFS}/opt/vc/lib"
|
||||
LDFLAGS+=" -L${ROOTFS}/lib/${HOST} -Wl,-rpath-link,${ROOTFS}/lib/${HOST}"
|
||||
LDFLAGS+=" -L${ROOTFS}/usr/local/lib -Wl,-rpath-link,${ROOTFS}/usr/local/lib"
|
||||
LDFLAGS+=" -L${ROOTFS}/usr/lib/${HOST} -Wl,-rpath-link,${ROOTFS}/usr/lib/${HOST}"
|
||||
LDFLAGS+=" -L${ROOTFS}/usr/lib -Wl,-rpath-link,${ROOTFS}/usr/lib"
|
||||
LDFLAGS+=" -L${ROOTFS}/usr/lib/${HOST}/blas -Wl,-rpath-link,${ROOTFS}/usr/lib/${HOST}/blas"
|
||||
LDFLAGS+=" -L${ROOTFS}/usr/lib/${HOST}/lapack -Wl,-rpath-link,${ROOTFS}/usr/lib/${HOST}/lapack"
|
||||
|
||||
# CPU tuning (use the most generic one)
|
||||
# PI 4 (not sure for the FPU)
|
||||
# CXXFLAGS+=" -mcpu=cortex-a72 -mfpu=neon-vfpv4 -mfloat-abi=hard"
|
||||
# PI 3
|
||||
# CXXFLAGS+=" -mcpu=cortex-a53 -mfpu=neon-vfpv4 -mfloat-abi=hard"
|
||||
# PI 2
|
||||
# CXXFLAGS+=" -mcpu=cortex-a7 -mfpu=neon-vfpv4 -mfloat-abi=hard"
|
||||
# PI 1, zero, ...
|
||||
CXXFLAGS+=" -mcpu=arm1176jzf-s -mfpu=vfp -mfloat-abi=hard"
|
||||
|
||||
export CXXFLAGS
|
||||
export LDFLAGS
|
||||
|
||||
export PKG_CONFIG_PATH="${ROOTFS}/usr/lib/pkgconfig"
|
||||
|
||||
export PATH=/opt/cross-pi-gcc/bin:/opt/cross-pi-gcc/libexec/gcc/arm-linux-gnueabihf/8.3.0:$PATH
|
||||
|
||||
# libraries are in fact in ${ROOTFS}/usr/lib/${HOST} but
|
||||
# the library path can be set only for boost.
|
||||
CONF_CMD="./configure --build=${BUILD} --host=${HOST}"
|
||||
CONF_CMD+=" --with-sysroot=${ROOTFS}"
|
||||
CONF_CMD+=" --with-openssl=${ROOTFS}/usr"
|
||||
CONF_CMD+=" --with-log4cplus=${ROOTFS}/usr"
|
||||
CONF_CMD+=" --with-boost-include=${ROOTFS}/usr/include"
|
||||
CONF_CMD+=" --with-boost-lib-dir=${ROOTFS}/usr/lib/${HOST}"
|
||||
@endcode
|
||||
|
||||
Some explanations:
|
||||
- the rootfs was copied or mounted in rpi/rootfs in the home directory.
|
||||
- the build system triplet is x86_64-pc-linux-gnu (processor,
|
||||
system, application binary interface). It is returned by the config.guess
|
||||
script so please verify.
|
||||
- the host system triplet is arm-linux-gnueabihf. It is used as the prefix
|
||||
for cross-compiling tools so this value is critical.
|
||||
- all tool variables are set to the cross-compiling tool name
|
||||
- CXXFLAGS is defined to use the rootfs image for includes. It is critical
|
||||
it does not use any build system include.
|
||||
- LDFLAGS is defined to use the rootfs, all cross-compiler support libraries
|
||||
and libraries from the rootfs image. It is critical it does not use
|
||||
any build system library.
|
||||
- CXXFLAGS can be tuned for a specific Raspberry Pi version. Proposed
|
||||
tuning supports all versions.
|
||||
- even if Kea ./configure does not depends on pkgconfig its path is set.
|
||||
- PATH is updated to find first cross-compiling tools.
|
||||
- I did not try yet database config scripts: perhaps they detect
|
||||
cross-compiling and produce correct paths.
|
||||
- CONF_CMD contains the ./configure common arguments.
|
||||
|
||||
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"
|
||||
- configure Kea build by "$CONF_CMD <your arguments>"
|
||||
|
||||
Known problems:
|
||||
- AC_TRY_RUN and AC_CHECK_FILE[S] autoconf macros do not support
|
||||
cross-compiling. They were removed from ./configure.ac in Kea 1.7.10.
|
||||
- libtool is a disaster for cross-compiling, in particular it produces
|
||||
silly libtool archive (.la) files. Fortunately they are useless.
|
||||
- bad paths for mkdir or sed on Raspbian.
|
||||
- recent Debian systems including recent Ubuntu modified libtool to
|
||||
not accept indirect dependencies. Makefiles were updated to have no
|
||||
such indirect dependencies in common cases as it is in Kea Makefile
|
||||
writing guidelines.
|
||||
- the libtool variable managing this is link_all_deplibs. You can
|
||||
edit the libtool script to set it to unknown or yes. Or simply
|
||||
use another Linux distrib.
|
||||
- there is no ldd in cross-compiling tools. The table of used
|
||||
shared libraries in available by readelf -d which is in the
|
||||
cross-compiling tools.
|
||||
|
||||
Final words: this is still highly experimental and does not cover
|
||||
everything. New ways to offload almost everything outside the Raspberry
|
||||
Pi are still to be found. Currently to provide Raspbian Kea packages
|
||||
is not possible for ISC.
|
||||
|
||||
*/
|
||||
@ -10,8 +10,7 @@
|
||||
|
||||
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 and
|
||||
of them generated from the same sources. To generate the documentation, 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:
|
||||
|
||||
@ -46,7 +46,7 @@ Combining the binaries and the fuzzer types results in eight fuzzing binaries:
|
||||
|
||||
@subsection HowToBuild How to Build the LLVM Fuzzer
|
||||
|
||||
Use the "--enable-fuzzing" during the configure step. Then just compile as usual.
|
||||
Use the "-D fuzz=enabled" during the meson setup step. Then just compile as usual.
|
||||
|
||||
@code
|
||||
meson setup build -D fuzz=enabled
|
||||
@ -171,7 +171,7 @@ for this are:
|
||||
compiler.
|
||||
- Specify a value of "--prefix" on the command line to set the directory
|
||||
into which Kea is installed.
|
||||
- Add the "-Dfuzz=enabled" switch to the "meson setup" command line.
|
||||
- Add the "-D fuzz=enabled" switch to the "meson setup" command line.
|
||||
.
|
||||
For example:
|
||||
@code
|
||||
@ -327,7 +327,7 @@ while (not shutting down) {
|
||||
Read and process one packet
|
||||
}
|
||||
@endcode
|
||||
When -Dfuzz=enabled is specified, this is conceptually modified to:
|
||||
When -D fuzz=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 "-Dfuzz=enabled" switch in the configuration command line (although
|
||||
use the "-D fuzz=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 -Dfuzz=enabled is specified and with the AFL
|
||||
If unit tests are built when -D fuzz=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
|
||||
|
||||
@ -116,7 +116,7 @@ anything e.g. `DEBUG=true`. `unset DEBUG` to remove this behavior.
|
||||
different versions of Tsan).
|
||||
|
||||
The simplest way to enable a sanitizer is to specify the flag on the setup
|
||||
step with `meson setup build -Db_sanitize=thread`.
|
||||
step with `meson setup build -D b_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
|
||||
|
||||
@ -166,18 +166,21 @@ directly. It accepts the following command-line switches:
|
||||
Upon startup, the module loads its configuration and begins listening
|
||||
for NCRs based on that configuration.
|
||||
|
||||
During startup, the server attempts to create a PID file of the form:
|
||||
``[runstatedir]/[conf name].kea-dhcp-ddns.pid`` where:
|
||||
During startup, the server attempts to create a PID file of the
|
||||
form: ``[pidfile_dir]/[conf name].kea-dhcp-ddns.pid`` where:
|
||||
|
||||
- ``runstatedir`` - is the value as passed into the build configure
|
||||
script; it defaults to "/usr/local/var/run". Note that this value may be
|
||||
overridden at runtime by setting the environment variable
|
||||
``KEA_PIDFILE_DIR``. This is intended primarily for testing purposes.
|
||||
- ``pidfile_dir`` - is ``[prefix]/[localstatedir]/run/kea`` where
|
||||
``prefix`` and ``localstatedir`` are the values passed into meson setup using
|
||||
``--prefix`` and ``--localstatedir`` which default to ``/usr/local`` and
|
||||
``var`` respectively. So the whole ``pidfile_dir`` defaults to
|
||||
``/usr/local/var``. Note that this value may be overridden at runtime by
|
||||
setting the environment variable ``KEA_PIDFILE_DIR`` intended primarily for
|
||||
testing purposes.
|
||||
|
||||
- ``conf name`` - is the configuration file name used to start the server,
|
||||
minus all preceding paths and the file extension. For example, given
|
||||
a pathname of "/usr/local/etc/kea/myconf.txt", the portion used would
|
||||
be "myconf".
|
||||
a pathname of ``/usr/local/etc/kea/myconf.txt``, the portion used would
|
||||
be ``myconf``.
|
||||
|
||||
If the file already exists and contains the PID of a live process, the
|
||||
server issues a ``DHCP_DDNS_ALREADY_RUNNING`` log message and exits. It
|
||||
|
||||
@ -84,13 +84,15 @@ configuration file. Since the DHCPv4 server opens privileged ports, it
|
||||
requires root access; this daemon must be run as root.
|
||||
|
||||
During startup, the server attempts to create a PID file of the
|
||||
form: ``[runstatedir]/kea/[conf name].kea-dhcp4.pid``, where:
|
||||
form: ``[pidfile_dir]/[conf name].kea-dhcp4.pid`` where:
|
||||
|
||||
- ``runstatedir``: The value as passed into the build configure
|
||||
script; it defaults to ``/usr/local/var/run``. Note that this value may be
|
||||
overridden at runtime by setting the environment variable
|
||||
``KEA_PIDFILE_DIR``, although this is intended primarily for testing
|
||||
purposes.
|
||||
- ``pidfile_dir`` - is ``[prefix]/[localstatedir]/run/kea`` where
|
||||
``prefix`` and ``localstatedir`` are the values passed into meson setup using
|
||||
``--prefix`` and ``--localstatedir`` which default to ``/usr/local`` and
|
||||
``var`` respectively. So the whole ``pidfile_dir`` defaults to
|
||||
``/usr/local/var``. Note that this value may be overridden at runtime by
|
||||
setting the environment variable ``KEA_PIDFILE_DIR`` intended primarily for
|
||||
testing purposes.
|
||||
|
||||
- ``conf name``: The configuration file name used to start the server,
|
||||
minus all preceding paths and the file extension. For example, given
|
||||
|
||||
@ -84,13 +84,15 @@ configuration file. Since the DHCPv6 server opens privileged ports, it
|
||||
requires root access; this daemon must be run as root.
|
||||
|
||||
During startup, the server attempts to create a PID file of the
|
||||
form: ``[runstatedir]/kea/[conf name].kea-dhcp6.pid``, where:
|
||||
form: ``[pidfile_dir]/[conf name].kea-dhcp6.pid``, where:
|
||||
|
||||
- ``runstatedir``: The value as passed into the build configure
|
||||
script; it defaults to ``/usr/local/var/run``. Note that this value may be
|
||||
overridden at runtime by setting the environment variable
|
||||
``KEA_PIDFILE_DIR``, although this is intended primarily for testing
|
||||
purposes.
|
||||
- ``pidfile_dir`` - is ``[prefix]/[localstatedir]/run/kea`` where
|
||||
``prefix`` and ``localstatedir`` are the values passed into meson setup using
|
||||
``--prefix`` and ``--localstatedir`` which default to ``/usr/local`` and
|
||||
``var`` respectively. So the whole ``pidfile_dir`` defaults to
|
||||
``/usr/local/var``. Note that this value may be overridden at runtime by
|
||||
setting the environment variable ``KEA_PIDFILE_DIR`` intended primarily for
|
||||
testing purposes.
|
||||
|
||||
- ``conf name``: The configuration file name used to start the server,
|
||||
minus all preceding paths and the file extension. For example, given
|
||||
|
||||
@ -86,7 +86,7 @@ can save logs to a text file or to a database (created using
|
||||
:iscman:`kea-admin`; see :ref:`mysql-database-create` and :ref:`pgsql-database-create`).
|
||||
The library is installed alongside the Kea libraries in
|
||||
``[kea-install-dir]/var/lib/kea``, where ``kea-install-dir`` is determined
|
||||
by the ``--prefix`` option of the configure script; it defaults to
|
||||
by the ``--prefix`` meson setup option which defaults to
|
||||
``/usr/local``. Assuming the default value, :iscman:`kea-dhcp4` can be configured to load
|
||||
:ischooklib:`libdhcp_legal_log.so` like this:
|
||||
|
||||
|
||||
@ -73,18 +73,18 @@ For our users' convenience, the subscriber hooks' installation procedure is desc
|
||||
|
||||
1. Download the package; detailed instructions are provided in the KB article
|
||||
above. The package will be a file with a name similar to
|
||||
``kea-subscriber-|release|.tar.gz``.
|
||||
``kea-subscriber-|release|.tar.xz``.
|
||||
|
||||
2. Administrators who have the sources for the corresponding version of the
|
||||
open-source Kea package on their system from the initial Kea installation
|
||||
should skip this step. Otherwise, extract the Kea source from the original
|
||||
tarball that was downloaded. For example, with a download of Kea |release|,
|
||||
there should be a tarball called ``kea-|release|.tar.gz`` on the system.
|
||||
there should be a tarball called ``kea-|release|.tar.xz`` on the system.
|
||||
Unpack this tarball:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
$ tar -zxvf kea-|release|.tar.gz
|
||||
$ tar -Jxvf kea-|release|.tar.xz
|
||||
|
||||
This will unpack the tarball into the ``kea-|release|`` subdirectory of
|
||||
the current working directory.
|
||||
@ -97,7 +97,7 @@ steps will unpack the subscriber tarball into the correct location:
|
||||
.. parsed-literal::
|
||||
|
||||
$ cd kea-|release|
|
||||
$ tar -xvf ../kea-subscriber-|release|.tar.gz
|
||||
$ tar -Jxvf ../kea-subscriber-|release|.tar.xz
|
||||
|
||||
Note that unpacking the Kea subscriber package puts the files into a
|
||||
directory named ``premium``. Regardless of the name of the package, the
|
||||
|
||||
@ -248,7 +248,7 @@ following commands import the code-signing keys
|
||||
.. code-block:: console
|
||||
|
||||
$ gpg --import isc-keyblock.asc
|
||||
$ gpg --verify kea-X.Y.Z.tar.gz.asc kea-X.Y.Z.tar.gz
|
||||
$ gpg --verify kea-X.Y.Z.tar.xz.asc kea-X.Y.Z.tar.xz
|
||||
|
||||
The verification allows users to confirm that the tar file has not
|
||||
been tampered with and that it was created by ISC.
|
||||
@ -490,7 +490,7 @@ First, a regular user account must be created:
|
||||
|
||||
Then, change the binaries' ownership and group to the new user. Note that
|
||||
the specific path may be different. Please refer to the ``--prefix``
|
||||
parameter passed to the configure script:
|
||||
parameter passed to ``meson setup``:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
|
||||
@ -25,9 +25,9 @@ Quick Start Guide Using tarball
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
$ tar -xvzf kea-|release|.tar.gz
|
||||
$ tar -Jxvf kea-|release|.tar.xz
|
||||
|
||||
4. Go into the source directory and run the configure script:
|
||||
4. Go into the source directory and set up the build:
|
||||
|
||||
.. parsed-literal::
|
||||
|
||||
|
||||
@ -127,12 +127,7 @@ servers, the default empty path in the URL is not enough, so the
|
||||
$ kea-shell --host 192.0.2.1 --port 8001 --path kea ...
|
||||
|
||||
The Kea shell requires Python to be installed on the system. It has been
|
||||
tested with various versions of Python 3, up to 3.5.
|
||||
Since not every Kea deployment uses this feature and there are
|
||||
deployments that do not have Python, the Kea shell is not enabled by
|
||||
default. To use it, specify ``--enable-shell`` when running ``configure``
|
||||
during the installation of Kea. When building on Debian systems,
|
||||
``--with-site-packages=...`` may also be useful.
|
||||
tested with various versions of Python 3.
|
||||
|
||||
.. note::
|
||||
|
||||
|
||||
@ -3448,9 +3448,9 @@ This is an error message that occurs when the server is unable to create
|
||||
its PID file. The log message should contain details sufficient to
|
||||
determine the underlying cause. The most likely culprits are that
|
||||
some portion of the pathname does not exist or a permissions issue. The
|
||||
default path is determined by --localstatedir or --runstatedir configure
|
||||
parameters but may be overridden by setting environment variable,
|
||||
KEA_PIDFILE_DIR. The first argument is the process name.
|
||||
default path is determined by ``--localstatedir`` and ``--prefix`` meson setup
|
||||
options but may be overridden by setting environment variable
|
||||
``KEA_PIDFILE_DIR``. The first argument is the process name.
|
||||
|
||||
DCTL_PROCESS_FAILED
|
||||
===================
|
||||
|
||||
@ -7319,7 +7319,7 @@ 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 -Dmysql during "
|
||||
"database type: mysql. Did you forget to use -D mysql=enabled during "
|
||||
"setup or to load libdhcp_mysql hook library?");
|
||||
}
|
||||
|
||||
|
||||
@ -8169,7 +8169,7 @@ 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 -Dmysql during "
|
||||
"database type: mysql. Did you forget to use -D mysql=enabled during "
|
||||
"setup or to load libdhcp_mysql hook library?");
|
||||
}
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2019-2021 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2019-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
|
||||
@ -30,7 +30,7 @@ without vendor extensions are not supported.
|
||||
It must be configured as a hook library for the desired DHCP server
|
||||
modules. Note that the bootp library is installed alongside the
|
||||
Kea libraries in "<install-dir>/lib" where <install-dir> is determined
|
||||
by the --prefix option of the configure script. It defaults to
|
||||
by the --prefix meson setup option. It defaults to
|
||||
"/usr/local". Assuming the default value then, configuring kea-dhcp4
|
||||
to load the bootp library could be done with the following Kea4
|
||||
configuration:
|
||||
|
||||
@ -105,7 +105,7 @@ 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 -Dtests=enabled to the "meson setup" command
|
||||
and run them, you need to pass -D tests=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".
|
||||
|
||||
@ -32,7 +32,7 @@ incoming packet to be used as identifier.
|
||||
It must be configured as a hook library for the desired DHCP server
|
||||
modules. Note that the flex_id library is installed alongside the
|
||||
Kea libraries in "<install-dir>/lib" where <install-dir> is determined
|
||||
by the --prefix option of the configure script. It defaults to
|
||||
by the --prefix meson setup option. It defaults to
|
||||
"/usr/local". Assuming the default value then, configuring kea-dhcp4
|
||||
to load the flex_id library could be done with the following Kea4
|
||||
configuration:
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2019-2022 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2019-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,7 +32,7 @@ added to response packets.
|
||||
It must be configured as a hook library for the desired DHCP server
|
||||
modules. Note that the flex_option library is installed alongside the
|
||||
Kea libraries in "<install-dir>/lib" where <install-dir> is determined
|
||||
by the --prefix option of the configure script. It defaults to
|
||||
by the --prefix meson setup option. It defaults to
|
||||
"/usr/local". Assuming the default value then, configuring kea-dhcp4
|
||||
to load the flex_option library could be done with the following Kea4
|
||||
configuration:
|
||||
|
||||
@ -347,7 +347,7 @@ or
|
||||
It must be configured as a hook library for the desired DHCP server
|
||||
modules. Note that the legal_log library is installed alongside the
|
||||
Kea libraries in "<install-dir>/lib" where <install-dir> is determined
|
||||
by the --prefix option of the configure script. It defaults to
|
||||
by the --prefix meson setup option. It defaults to
|
||||
"/usr/local". Assuming the default value then, configuring kea-dhcp4
|
||||
to load the legal_log library could be done with the following Kea4
|
||||
configuration:
|
||||
|
||||
@ -180,7 +180,7 @@ 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 -Dtests=enabled to the "meson setup" command
|
||||
and run them, you need to pass -D tests=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".
|
||||
|
||||
@ -52,8 +52,9 @@ The global configuration flags are:
|
||||
deadtime value specifies the number of seconds after which a server is
|
||||
considered unresponsive. 0 disables the mechanism.
|
||||
|
||||
- dictionary (default set by configure at build time) is the attribute
|
||||
and value dictionary. Note it is a critical parameter.
|
||||
- dictionary (set to "[prefix][sysconfdir}/kea/radius/dictionary" during meson
|
||||
setup which defaults to "/usr/local/etc/kea/radius/dictionary") is the
|
||||
attribute and value dictionary. Note it is a critical parameter.
|
||||
|
||||
- extract-duid (default true) extracts the embedded duid from an
|
||||
RFC-4361-compliant DHCPv4 client-id. Implied by client-id-printable.
|
||||
|
||||
@ -29,7 +29,7 @@ be run on specific hook points.
|
||||
It must be configured as a hook library for the desired DHCP server
|
||||
modules. Note that the Run Script library is installed alongside the
|
||||
Kea libraries in "<install-dir>/lib" where <install-dir> is determined
|
||||
by the --prefix option of the configure script. It defaults to
|
||||
by the --prefix meson setup option. It defaults to
|
||||
"/usr/local".
|
||||
|
||||
Configuring kea-dhcp4 to load the Run Script library could be done with
|
||||
|
||||
@ -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
|
||||
@ -133,8 +133,8 @@ the library will unload.
|
||||
|
||||
It must be configured as a hook library for the desired DHCP server modules.
|
||||
Note that the user_chk library is installed alongside the Kea libraries in
|
||||
"<install-dir>/lib" where <install-dir> is determined by the --prefix option of
|
||||
the configure script. It defaults to "/usr/local". Assuming the default value
|
||||
"<install-dir>/lib" where <install-dir> is determined by the --prefix meson
|
||||
setup option which defaults to "/usr/local". Assuming the default value
|
||||
then, configuring kea-dhcp4 to load the user_chk library could be done with the
|
||||
following Kea4 configuration:
|
||||
|
||||
|
||||
@ -165,12 +165,12 @@ public:
|
||||
// No match?
|
||||
if (index == factories_.end()) {
|
||||
if ((db_type == "mysql") || (db_type == "postgresql")) {
|
||||
std::string with = (db_type == "postgresql" ? "pgsql" : db_type);
|
||||
std::string libdhcp(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 -D"
|
||||
<< with << " during compilation or to load libdhcp_"
|
||||
<< with << " hook library?");
|
||||
<< ". Did you forget to use -D "
|
||||
<< db_type << "=enabled during setup or to load libdhcp_"
|
||||
<< libdhcp << " hook library?");
|
||||
}
|
||||
isc_throw(db::InvalidType, "The type of the configuration backend: '" <<
|
||||
db_type << "' is not supported");
|
||||
|
||||
@ -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 \-Dmysql switch must be supplied to "meson setup" for support to be
|
||||
the "-D mysql=enabled" 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 \-Dpostgresql switch must be supplied to "meson setup" for support to be
|
||||
the "-D postgresql=enabled" 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.
|
||||
|
||||
@ -48,12 +48,12 @@ HostDataSourceFactory::add(HostDataSourceList& sources,
|
||||
// No match?
|
||||
if (index == map_.end()) {
|
||||
if ((db_type == "mysql") || (db_type == "postgresql")) {
|
||||
string with = (db_type == "postgresql" ? "pgsql" : db_type);
|
||||
string libdhcp(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 -D"
|
||||
<< with << " during compilation or to load libdhcp_"
|
||||
<< with << " hook library?");
|
||||
<< ". Did you forget to use -D "
|
||||
<< db_type << "=enabled during setup or to load libdhcp_"
|
||||
<< libdhcp << " hook library?");
|
||||
}
|
||||
isc_throw(InvalidType, "The type of host backend: '" <<
|
||||
db_type << "' is not supported");
|
||||
|
||||
@ -62,12 +62,12 @@ LeaseMgrFactory::create(const std::string& dbaccess) {
|
||||
if (index == map_.end()) {
|
||||
if ((db_type == "mysql") || (db_type == "postgresql")) {
|
||||
LOG_ERROR(dhcpsrv_logger, DHCPSRV_UNKNOWN_DB).arg(db_type);
|
||||
string with = (db_type == "postgresql" ? "pgsql" : db_type);
|
||||
string libdhcp(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 -D"
|
||||
<< with << " during compilation or to load libdhcp_"
|
||||
<< with << " hook library?");
|
||||
<< ". Did you forget to use -D "
|
||||
<< db_type << "=enabled during setup or to load libdhcp_"
|
||||
<< libdhcp << " hook library?");
|
||||
}
|
||||
// Get here on no match
|
||||
LOG_ERROR(dhcpsrv_logger, DHCPSRV_UNKNOWN_DB).arg(parameters[type]);
|
||||
|
||||
@ -83,12 +83,12 @@ LegalLogMgrFactory::addBackend(DatabaseConnection::ParameterMap& parameters, Man
|
||||
// No match?
|
||||
if (index == map_.end()) {
|
||||
if ((db_type == "mysql") || (db_type == "postgresql")) {
|
||||
string with = (db_type == "postgresql" ? "pgsql" : db_type);
|
||||
string libdhcp(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 -D"
|
||||
<< with << " during compilation or to load libdhcp_"
|
||||
<< with << " hook library?");
|
||||
<< ". Did you forget to use -D "
|
||||
<< db_type << "=enabled during setup or to load libdhcp_"
|
||||
<< libdhcp << " hook library?");
|
||||
}
|
||||
isc_throw(InvalidType, "The type of the forensic log backend: '" <<
|
||||
db_type << "' is not supported");
|
||||
|
||||
@ -121,12 +121,11 @@ instantiated with the appropriate value and put onto the expression vector.
|
||||
@section dhcpEvalConfigure Configure options
|
||||
|
||||
Since the flex/bison tools are not necessary for a regular compilation,
|
||||
checks are conducted during the configure script, but the lack of flex or
|
||||
bison tools does not stop the process. There is a flag
|
||||
(--enable-generate-parser) that tells configure script that the
|
||||
parser will be generated. With this flag, the checks for flex/bison
|
||||
are mandatory. If either tool is missing or at too early a version, the
|
||||
configure process will terminate with an error.
|
||||
checks are conducted during meson setup, but the lack of flex or
|
||||
bison tools does not stop the process. If either tool is missing or at too
|
||||
early a version, it will be mentioned in the config report that can be found
|
||||
at build/config.report that flex or bison are not available and the setup
|
||||
process will continue.
|
||||
|
||||
@section dhcpEvalToken Supported tokens
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2013-2020 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
|
||||
@ -366,9 +366,7 @@
|
||||
This should be executed by any hooks library linking against a statically
|
||||
initialized Kea. (In fact, running it against a dynamically-linked
|
||||
Kea should have no effect, as the load operation discards any duplicate
|
||||
message entries.) The hooks library tests do this, the code being
|
||||
conditionally compiled within a test of the @c USE_STATIC_LINK macro, set
|
||||
by the configure script.
|
||||
message entries.)
|
||||
|
||||
@note Not everything is completely rosy with logging and static linking.
|
||||
In particular, there appears to be an issue with the scenario where a
|
||||
|
||||
@ -1358,7 +1358,7 @@ 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 "-Ddefault_library=static" switch (set when
|
||||
If Kea is built with the "-D default_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,
|
||||
|
||||
@ -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
|
||||
@ -243,8 +243,8 @@ public:
|
||||
|
||||
/// @brief handler for 'build-report' command
|
||||
///
|
||||
/// This method handles build-report command. It returns the output printed
|
||||
/// by configure script which contains most compilation parameters.
|
||||
/// This method handles build-report command. It returns the config report
|
||||
/// created by meson setup which contains the compilation parameters.
|
||||
///
|
||||
/// @param command (ignored)
|
||||
/// @param args (ignored)
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
# Copyright (C) 2016-2024 Internet Systems Consortium, Inc. ("ISC")
|
||||
# Copyright (C) 2016-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
|
||||
@ -98,9 +98,9 @@ This is an error message that occurs when the server is unable to create
|
||||
its PID file. The log message should contain details sufficient to
|
||||
determine the underlying cause. The most likely culprits are that
|
||||
some portion of the pathname does not exist or a permissions issue. The
|
||||
default path is determined by --localstatedir or --runstatedir configure
|
||||
parameters but may be overridden by setting environment variable,
|
||||
KEA_PIDFILE_DIR. The first argument is the process name.
|
||||
default path is determined by --localstatedir and --prefix meson setup options
|
||||
but may be overridden by setting environment variable KEA_PIDFILE_DIR.
|
||||
The first argument is the process name.
|
||||
|
||||
% DCTL_PROCESS_FAILED %1 application execution failed: %2
|
||||
The controller has encountered a fatal error while running the
|
||||
|
||||
@ -1,10 +1,9 @@
|
||||
#!/bin/sh
|
||||
|
||||
################################################################################
|
||||
# This script runs all tests in valgrind. Configure and compile kea the way
|
||||
# you want it to be tested (you should use --with-gtest or --with-gtest-source,
|
||||
# however, or you get no tests). Then run this script from the top build
|
||||
# directory.
|
||||
# This script runs all tests in valgrind. Set up and compile Kea the way
|
||||
# you want it to be tested (you should use "-D tests=enabled" however, or you
|
||||
# get no tests). Then run this script.
|
||||
#
|
||||
# Note that the test isn't what you would call "production quality" (it is
|
||||
# expected to be used by the kea developers, not end user) and might break,
|
||||
@ -23,10 +22,10 @@ script_path=$(cd "$(dirname "${0}")" && pwd)
|
||||
cd "${script_path}/.."
|
||||
|
||||
# First, make sure the tests are up to date
|
||||
make
|
||||
meson compile -C build
|
||||
|
||||
if test $? = 2; then
|
||||
printf 'Did you run configure?\n'
|
||||
printf 'Did you run meson setup?\n'
|
||||
exit 1
|
||||
fi
|
||||
|
||||
@ -76,6 +75,6 @@ if test -n "$FAILED"; then
|
||||
fi
|
||||
|
||||
if ! $FOUND_ANY; then
|
||||
echo "No test was found. It is possible you configured without --with-gtest or you run it from wrong directory" >&2
|
||||
echo "No test was found. Is it possible you configured without '-D tests=enabled'?" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user