Cloning the repository

Note

Latest up-to-date packages for various distribution can be obtained from web https://knot-resolver.cz/download/.

Knot Resolver is written for UNIX-like systems using modern C standards. Beware that some 64-bit systems with LuaJIT 2.1 may be affected by a problem – Linux on x86_64 is unaffected but Linux on aarch64 is.

$ git clone --recursive https://gitlab.nic.cz/knot/knot-resolver.git

Building with apkg

Knot Resolver uses apkg tool for upstream packaging. It allows build packages localy for supported distributions, which it then installs. apkg also takes care of dependencies itself.

First, you need to install and setup apkg.

Tip

Install apkg with pipx to avoid version conflicts.

$ pip3 install apkg
$ apkg system-setup

Clone and change dir to knot-resolver git repository.

$ git clone --recursive https://gitlab.nic.cz/knot/knot-resolver.git
$ cd knot-resolver

Tip

The apkg status command can be used to find out some useful information, such as whether the current distribution is supported.

When apkg is ready, a package can be built and installed.

# takes care of dependencies
apkg build-dep

# build package
apkg build

# (build and) install package, builds package when it is not already built
apkg install

After that Knot Resolver should be installed.

Building with Meson

Knot Resolver uses Meson Build system. Shell snippets below should be sufficient for basic usage but users unfamiliar with Meson might want to read introductory article Using Meson.

Dependencies

Note

This section lists basic requirements. Individual modules might have additional build or runtime dependencies.

The following dependencies are needed to build and run Knot Resolver with core functions:

Requirement	Notes
ninja	build only
meson >= 0.49	build only [1]
C and C++ compiler	build only [2]
pkg-config	build only [3]
libknot 3.0.2+	Knot DNS libraries
LuaJIT 2.0+	Embedded scripting language
libuv 1.7+	Multiplatform I/O and services
lmdb	Memory-mapped database for cache
GnuTLS	TLS

Additional dependencies are needed to build and run Knot Resolver with manager: All dependencies are also listed in pyproject.toml which is our authoritative source.

Requirement	Notes
python3 >=3.7	Python language interpreter
Jinja2	Template engine for Python
PyYAML	YAML framework for Python
aiohttp	HTTP Client/Server for Python.
prometheus-client	Prometheus client for Python
typing-extensions	Compatibility module for Python

There are also optional packages that enable specific functionality in Knot Resolver:

Optional	Needed for	Notes
jemalloc	daemon	Improve long-term memory consumption.
nghttp2	daemon	DNS over HTTPS support.
libsystemd	daemon	Systemd watchdog support.
libcap-ng	daemon	Linux capabilities: support dropping them.
lua-basexx	config tests	Number base encoding/decoding for Lua.
lua-http	modules/http	HTTP/2 client/server for Lua.
lua-cqueues	some lua modules
cmocka	unit tests	Unit testing framework.
dnsdist	proxyv2 test	DNS proxy server
Doxygen	documentation	Generating API documentation.
Sphinx, sphinx-tabs and sphinx_rtd_theme	documentation	Building this documentation.
breathe	documentation	Exposing Doxygen API doc to Sphinx.
libprotobuf 3.0+	modules/dnstap	Protocol Buffers support for dnstap.
libprotobuf-c 1.0+	modules/dnstap	C bindings for Protobuf.
libfstrm 0.2+	modules/dnstap	Frame Streams data transport protocol.
luacheck	lint-lua	Syntax and static analysis checker for Lua.
clang-tidy	lint-c	Syntax and static analysis checker for C.
luacov	check-config	Code coverage analysis for Lua modules.

[1]

If meson >= 0.49 isn’t available for your distro, check backports repository or use python pip to install it.

[2]

Requires __attribute__((cleanup)) and -MMD -MP for dependency file generation. We test GCC and Clang, and ICC is likely to work as well.

[3]

You can use variables <dependency>_CFLAGS and <dependency>_LIBS to configure dependencies manually (i.e. libknot_CFLAGS and libknot_LIBS).

Note

Some build dependencies can be found in home:CZ-NIC:knot-resolver-build.

On reasonably new systems most of the dependencies can be resolved from packages, here’s an overview for several platforms.

• Debian/Ubuntu - Current stable doesn’t have new enough Meson and libknot. Use repository above or build them yourself. Fresh list of dependencies can be found in Debian control file in our repo, search for “Build-Depends”.

• CentOS/Fedora/RHEL/openSUSE - Fresh list of dependencies can be found in RPM spec file in our repo, search for “BuildRequires”.

• FreeBSD - when installing from ports, all dependencies will install automatically, corresponding to the selected options.

• Mac OS X - the dependencies can be obtained from Homebrew formula.

Compilation

Folowing meson command creates new build directory named build_dir, configures installation path to /tmp/kr and enables static build (to allow installation to non-standard path). You can also configure some Build options, in this case enable manager, which is disabled by default.

$ meson build_dir --prefix=/tmp/kr --default-library=static -Dmanager=enabled

After that it is possible to build and install Knot Resolver.

$ meson setup build_dir --prefix=/tmp/kr --default-library=static
$ ninja -C build_dir

# install Knot Resolver into the previously configured '/tmp/kr' path
$ ninja install -C build_dir

At this point you can execute the newly installed binary using path /tmp/kr/sbin/kresd.

Note

When compiling on OS X, creating a shared library is currently not possible when using luajit package from Homebrew due to #37169.

Build options

It’s possible to change the compilation with build options. These are useful to packagers or developers who wish to customize the daemon behaviour, run extended test suites etc. By default, these are all set to sensible values.

For complete list of build options create a build directory and run:

$ meson setup build_dir
$ meson configure build_dir

To customize project build options, use -Doption=value when creating a build directory:

$ meson setup build_dir -Ddoc=enabled

… or change options in an already existing build directory:

$ meson configure build_dir -Ddoc=enabled

Customizing compiler flags

If you’d like to use customize the build, see meson’s built-in options. For hardening, see b_pie.

For complete control over the build flags, use --buildtype=plain and set CFLAGS, LDFLAGS when creating the build directory with meson command.

Tests

The following is a non-comprehensitve lists of various tests that can be found in this repo. These can be enabled by the build system.

Unit tests

The unit tests depend on cmocka and can easily be executed after compilation. They are enabled by default (if cmocka is found).

$ ninja -C build_dir
$ meson test -C build_dir --suite unit

Postinstall tests

There following tests require a working installation of kresd. The binary kresd found in $PATH will be tested. When testing through meson, $PATH is modified automatically and you just need to make sure to install kresd first.

$ ninja install -C build_dir

Config tests

Config tests utilize the kresd’s lua config file to execute arbitrary tests, typically testing various modules, their API etc.

To enable these tests, specify -Dconfig_tests=enabled option for meson. Multiple dependencies are required (refer to meson’s output when configuring the build dir).

$ meson configure build_dir -Dconfig_tests=enabled
$ ninja install -C build_dir
$ meson test -C build_dir --suite config

Extra tests

The extra tests require a large set of additional dependencies and executing them outside of upstream development is probably redundant.

To enable these tests, specify -Dextra_tests=enabled option for meson. Multiple dependencies are required (refer to meson’s output when configuring the build dir). Enabling extra_tests automatically enables config tests as well.

Integration tests

The integration tests are using Deckard, the DNS test harness. The tests simulate specific DNS scenarios, including authoritative server and their responses. These tests rely on linux namespaces, refer to Deckard documentation for more info.

$ meson configure build_dir -Dextra_tests=enabled
$ ninja install -C build_dir
$ meson test -C build_dir --suite integration

Pytests

The pytest suite is designed to spin up a kresd instance, acquire a connected socket, and then performs any tests on it. These tests are used to test for example TCP, TLS and its connection management.

$ meson configure build_dir -Dextra_tests=enabled
$ ninja install -C build_dir
$ meson test -C build_dir --suite pytests

Useful meson commands

It’s possible to run only specific test suite or a test.

$ meson test -C build_dir --help
$ meson test -C build_dir --list
$ meson test -C build_dir --no-suite postinstall
$ meson test -C build_dir integration.serve_stale

Documentation

To check for documentation dependencies and allow its installation, use -Ddoc=enabled. The documentation doesn’t build automatically. Instead, target doc must be called explicitly.

$ meson configure build_dir -Ddoc=enabled
$ ninja -C build_dir doc

Tarball

Released tarballs are available from https://knot-resolver.cz/download/

To make a release tarball from git, use the following command. The

$ ninja -C build_dir dist

It’s also possible to make a development snapshot tarball:

$ ./scripts/make-archive.sh

Packaging

Recommended build options for packagers:

• --buildtype=release for default flags (optimization, asserts, …). For complete control over flags, use plain and see Customizing compiler flags.

• --prefix=/usr to customize prefix, other directories can be set in a similar fashion, see meson setup --help

• -Dsystemd_files=enabled for systemd unit files

• -Ddoc=enabled for offline documentation (see Documentation)

• -Dinstall_kresd_conf=enabled to install default config file

• -Dmanager=enabled to force build of the manager and its features

• -Dunit_tests=enabled to force build of unit tests

Systemd

It’s recommended to use the upstream system unit files. If any customizations are required, drop-in files should be used, instead of patching/changing the unit files themselves.

To install systemd unit files, use the -Dsystemd_files=enabled build option.

To support enabling services after boot, you must also link kresd.target to multi-user.target.wants:

ln -s ../kresd.target /usr/lib/systemd/system/multi-user.target.wants/kresd.target

Trust anchors

If the target distro has externally managed (read-only) DNSSEC trust anchors or root hints use this:

• -Dkeyfile_default=/usr/share/dns/root.key

• -Droot_hints=/usr/share/dns/root.hints

• -Dmanaged_ta=disabled

In case you want to have automatically managed DNSSEC trust anchors instead, set -Dmanaged_ta=enabled and make sure both keyfile_default file and its parent directories are writable by kresd process (after package installation!).

Docker image

Visit hub.docker.com/r/cznic/knot-resolver for instructions how to run the container.

For development, it’s possible to build the container directly from your git tree:

$ docker build -t knot-resolver .