Cloning the repository¶
Note
Maybe you do not need to build from source? See ../gettingstarted-install.html.
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, but distros supporting LuaJIT on aarch64 have typically resolved this already.
$ 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] |
build only |
|
libknot 3.3.0+ |
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 |
There are also optional packages that enable specific functionality in Knot Resolver:
Optional |
Needed for |
Notes |
---|---|---|
|
Improve long-term memory consumption. |
|
|
DNS over HTTPS support. |
|
|
Systemd watchdog support. |
|
|
Linux capabilities: support dropping them. |
|
|
Number base encoding/decoding for Lua. |
|
|
HTTP/2 client/server for Lua. |
|
some modules and tests |
||
|
Unit testing framework. |
|
|
DNS proxy server |
|
|
Generating API documentation. |
|
|
Building this documentation. |
|
|
Exposing Doxygen API doc to Sphinx. |
|
libprotobuf 3.0+ |
|
Protocol Buffers support for dnstap. |
libprotobuf-c 1.0+ |
|
C bindings for Protobuf. |
libfstrm 0.2+ |
|
Frame Streams data transport protocol. |
|
Syntax and static analysis checker for Lua. |
|
|
Syntax and static analysis checker for C. |
|
|
Code coverage analysis for Lua modules. |
On reasonably new systems most of the dependencies can be resolved from packages.
apkg build-dep
is one option of obtaining them (see above).
We tend to require not too old libknot, so you might need to install a newer one. Their team also provides binaries for major Linux distros: https://www.knot-dns.cz/download/
FreeBSD - when installing from ports, all dependencies will install automatically, corresponding to the selected options. FIXME: resolver 6.x stuff (manager) doesn’t even work yet.
Mac OS X - the dependencies can be obtained from Homebrew formula. FIXME: resolver 6.x stuff (manager) doesn’t even work yet.
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
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.
Testing infrastructure¶
The following is a non-exhaustive list of various tests that can be found in this repo. Some can be enabled by meson build system and some can be performed by Poetry tool.
The manager unit tests¶
The unit tests use pytest
and can be run with the command poe test
.
They can be run from a freshly cloned repository and should be successful.
They are located in the manager
subdirectory.
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, useplain
and see Customizing compiler flags.--prefix=/usr
to customize prefix, other directories can be set in a similar fashion, seemeson 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-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!).
Installing the manager from source¶
Additional dependencies are needed to run Knot Resolver with the manager
.
All dependencies are also listed in pyproject.toml which is our authoritative source.
Requirement |
Notes |
---|---|
python3 >=3.8 |
Python language interpreter |
Template engine for Python |
|
YAML framework for Python |
|
HTTP Client/Server for Python. |
|
Compatibility module for Python |
|
Prometheus client for Python (optional) |
You can install the Manager using the generated setup.py
.
cd manager
python3 setup.py install
Tip
For development, it is recommended to run the manager using the procedure described in Manager development environment.
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 .