diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ef320d1aab..11b181a2ba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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) diff --git a/INSTALL b/INSTALL index e16c113a35..bb53880ae9 100644 --- a/INSTALL +++ b/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 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. diff --git a/doc/devel/bison.dox b/doc/devel/bison.dox index 4c9630204a..13f8a0adbe 100644 --- a/doc/devel/bison.dox +++ b/doc/devel/bison.dox @@ -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, diff --git a/doc/devel/config-backend.dox b/doc/devel/config-backend.dox index 7991307e53..293470f381 100644 --- a/doc/devel/config-backend.dox +++ b/doc/devel/config-backend.dox @@ -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. diff --git a/doc/devel/cross-compile.dox b/doc/devel/cross-compile.dox index cc7685ebab..b4e5eb2fd1 100644 --- a/doc/devel/cross-compile.dox +++ b/doc/devel/cross-compile.dox @@ -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" diff --git a/doc/devel/doc.dox b/doc/devel/doc.dox index cde7f9071c..a28d2ee789 100644 --- a/doc/devel/doc.dox +++ b/doc/devel/doc.dox @@ -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 */ diff --git a/doc/devel/fuzz.dox b/doc/devel/fuzz.dox index aa7bf8148d..8c2f80ec60 100644 --- a/doc/devel/fuzz.dox +++ b/doc/devel/fuzz.dox @@ -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 diff --git a/doc/devel/unit-tests.dox b/doc/devel/unit-tests.dox index 63a410dbed..823b88ec64 100644 --- a/doc/devel/unit-tests.dox +++ b/doc/devel/unit-tests.dox @@ -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 gtest framework 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. -fsanitize=thread. + 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 Kea Administrator Reference Manual). @@ -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 Kea Administrator Reference Manual). diff --git a/doc/examples/kea4/backends.json b/doc/examples/kea4/backends.json index e5abb16544..5d37ca1c56 100644 --- a/doc/examples/kea4/backends.json +++ b/doc/examples/kea4/backends.json @@ -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", diff --git a/doc/examples/kea6/backends.json b/doc/examples/kea6/backends.json index 097d37c394..c30200f86e 100644 --- a/doc/examples/kea6/backends.json +++ b/doc/examples/kea6/backends.json @@ -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", diff --git a/doc/sphinx/arm/admin.rst b/doc/sphinx/arm/admin.rst index 8c1676ca6c..1cda552206 100644 --- a/doc/sphinx/arm/admin.rst +++ b/doc/sphinx/arm/admin.rst @@ -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 diff --git a/doc/sphinx/arm/agent.rst b/doc/sphinx/arm/agent.rst index 3ec3484f77..0ace3cad7c 100644 --- a/doc/sphinx/arm/agent.rst +++ b/doc/sphinx/arm/agent.rst @@ -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 diff --git a/doc/sphinx/arm/config-backend.rst b/doc/sphinx/arm/config-backend.rst index 8b5d0db144..122ec31e0b 100644 --- a/doc/sphinx/arm/config-backend.rst +++ b/doc/sphinx/arm/config-backend.rst @@ -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`. diff --git a/doc/sphinx/arm/ddns.rst b/doc/sphinx/arm/ddns.rst index 77dbcecfce..4406143d02 100644 --- a/doc/sphinx/arm/ddns.rst +++ b/doc/sphinx/arm/ddns.rst @@ -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. diff --git a/doc/sphinx/arm/dhcp4-srv.rst b/doc/sphinx/arm/dhcp4-srv.rst index 75e6529b3c..c02d7c337a 100644 --- a/doc/sphinx/arm/dhcp4-srv.rst +++ b/doc/sphinx/arm/dhcp4-srv.rst @@ -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 diff --git a/doc/sphinx/arm/dhcp6-srv.rst b/doc/sphinx/arm/dhcp6-srv.rst index 2064ada15a..6dc5902388 100644 --- a/doc/sphinx/arm/dhcp6-srv.rst +++ b/doc/sphinx/arm/dhcp6-srv.rst @@ -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 diff --git a/doc/sphinx/arm/ext-gss-tsig.rst b/doc/sphinx/arm/ext-gss-tsig.rst index 831f75e418..6cf41cc456 100644 --- a/doc/sphinx/arm/ext-gss-tsig.rst +++ b/doc/sphinx/arm/ext-gss-tsig.rst @@ -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: diff --git a/doc/sphinx/arm/ext-netconf.rst b/doc/sphinx/arm/ext-netconf.rst index b32f4efe7d..4b967aac2a 100644 --- a/doc/sphinx/arm/ext-netconf.rst +++ b/doc/sphinx/arm/ext-netconf.rst @@ -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 diff --git a/doc/sphinx/arm/hooks.rst b/doc/sphinx/arm/hooks.rst index d46eb9099b..ea324ff489 100644 --- a/doc/sphinx/arm/hooks.rst +++ b/doc/sphinx/arm/hooks.rst @@ -59,8 +59,8 @@ Installing Hook Packages .. note:: - For more details about installing the Kea Subscriber Hooks, please read - `this Knowledgebase article `__. + For more details about installing the Kea Subscriber Hooks, please read + `this Knowledgebase article `__. 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 diff --git a/doc/sphinx/arm/install.rst b/doc/sphinx/arm/install.rst index 15a8abe5d3..230c0abe15 100644 --- a/doc/sphinx/arm/install.rst +++ b/doc/sphinx/arm/install.rst @@ -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 `_, - 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 `__ 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: diff --git a/doc/sphinx/arm/quickstart.rst b/doc/sphinx/arm/quickstart.rst index 9c6e6c83a7..2214dc970e 100644 --- a/doc/sphinx/arm/quickstart.rst +++ b/doc/sphinx/arm/quickstart.rst @@ -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: diff --git a/src/bin/dhcp4/tests/config_parser_unittest.cc b/src/bin/dhcp4/tests/config_parser_unittest.cc index 58cdecdd65..28e2e896bc 100644 --- a/src/bin/dhcp4/tests/config_parser_unittest.cc +++ b/src/bin/dhcp4/tests/config_parser_unittest.cc @@ -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. diff --git a/src/bin/dhcp4/tests/dora_unittest.cc b/src/bin/dhcp4/tests/dora_unittest.cc index 6666f722c3..b2a6fdc6b3 100644 --- a/src/bin/dhcp4/tests/dora_unittest.cc +++ b/src/bin/dhcp4/tests/dora_unittest.cc @@ -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. diff --git a/src/bin/dhcp4/tests/kea_controller_unittest.cc b/src/bin/dhcp4/tests/kea_controller_unittest.cc index 0df8502f4c..0625ad23b0 100644 --- a/src/bin/dhcp4/tests/kea_controller_unittest.cc +++ b/src/bin/dhcp4/tests/kea_controller_unittest.cc @@ -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 diff --git a/src/bin/dhcp6/tests/config_parser_unittest.cc b/src/bin/dhcp6/tests/config_parser_unittest.cc index 06c94acbfb..4d823074bc 100644 --- a/src/bin/dhcp6/tests/config_parser_unittest.cc +++ b/src/bin/dhcp6/tests/config_parser_unittest.cc @@ -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": [{ diff --git a/src/bin/dhcp6/tests/fqdn_unittest.cc b/src/bin/dhcp6/tests/fqdn_unittest.cc index 2a10e1021c..ca51856e67 100644 --- a/src/bin/dhcp6/tests/fqdn_unittest.cc +++ b/src/bin/dhcp6/tests/fqdn_unittest.cc @@ -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 diff --git a/src/bin/dhcp6/tests/kea_controller_unittest.cc b/src/bin/dhcp6/tests/kea_controller_unittest.cc index 80fb89b37a..4bec04af23 100644 --- a/src/bin/dhcp6/tests/kea_controller_unittest.cc +++ b/src/bin/dhcp6/tests/kea_controller_unittest.cc @@ -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 diff --git a/src/hooks/dhcp/class_cmds/class_cmds.dox b/src/hooks/dhcp/class_cmds/class_cmds.dox index d2bf67aa58..565c521c78 100644 --- a/src/hooks/dhcp/class_cmds/class_cmds.dox +++ b/src/hooks/dhcp/class_cmds/class_cmds.dox @@ -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 diff --git a/src/hooks/dhcp/host_cmds/host_cmds.dox b/src/hooks/dhcp/host_cmds/host_cmds.dox index 64156e9823..fb5d9e3a53 100644 --- a/src/hooks/dhcp/host_cmds/host_cmds.dox +++ b/src/hooks/dhcp/host_cmds/host_cmds.dox @@ -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 diff --git a/src/lib/config_backend/base_config_backend_mgr.h b/src/lib/config_backend/base_config_backend_mgr.h index 3edcdb6ba8..2b29b2b227 100644 --- a/src/lib/config_backend/base_config_backend_mgr.h +++ b/src/lib/config_backend/base_config_backend_mgr.h @@ -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?"); } diff --git a/src/lib/dhcpsrv/database_backends.dox b/src/lib/dhcpsrv/database_backends.dox index c2d41312b3..9a7d4b47a5 100644 --- a/src/lib/dhcpsrv/database_backends.dox +++ b/src/lib/dhcpsrv/database_backends.dox @@ -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. diff --git a/src/lib/dhcpsrv/host_data_source_factory.cc b/src/lib/dhcpsrv/host_data_source_factory.cc index 506502967c..f2d90b356f 100644 --- a/src/lib/dhcpsrv/host_data_source_factory.cc +++ b/src/lib/dhcpsrv/host_data_source_factory.cc @@ -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?"); } diff --git a/src/lib/dhcpsrv/lease_mgr_factory.cc b/src/lib/dhcpsrv/lease_mgr_factory.cc index ea86d4ed5b..64f1c8fe9f 100644 --- a/src/lib/dhcpsrv/lease_mgr_factory.cc +++ b/src/lib/dhcpsrv/lease_mgr_factory.cc @@ -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?"); } diff --git a/src/lib/dhcpsrv/legal_log_mgr_factory.cc b/src/lib/dhcpsrv/legal_log_mgr_factory.cc index 881d717a7b..3af6a59e57 100644 --- a/src/lib/dhcpsrv/legal_log_mgr_factory.cc +++ b/src/lib/dhcpsrv/legal_log_mgr_factory.cc @@ -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?"); } diff --git a/src/lib/eval/eval.dox b/src/lib/eval/eval.dox index eed27ec66b..af6e91ec0c 100644 --- a/src/lib/eval/eval.dox +++ b/src/lib/eval/eval.dox @@ -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 diff --git a/src/lib/hooks/hooks_user.dox b/src/lib/hooks/hooks_user.dox index e6e96e392d..a5a78f9234 100644 --- a/src/lib/hooks/hooks_user.dox +++ b/src/lib/hooks/hooks_user.dox @@ -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 /include/kea -L /lib -fpic -shared -o example.s Notes: - Replace "" 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, diff --git a/src/lib/log/logging.dox b/src/lib/log/logging.dox index 8dbc02f6cb..9ecdb5857d 100644 --- a/src/lib/log/logging.dox +++ b/src/lib/log/logging.dox @@ -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. -@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. Including Message files in C++ Component Builds
-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 diff --git a/src/lib/yang/yang.dox b/src/lib/yang/yang.dox index e0fcab0493..039b00c411 100644 --- a/src/lib/yang/yang.dox +++ b/src/lib/yang/yang.dox @@ -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: