Building from sources

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.labs.nic.cz/knot/knot-resolver.git

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:

Requirement

Notes

ninja

build only

meson >= 0.46

build only 1

C and C++ compiler

build only 2

pkg-config

build only 3

libknot 2.8+

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

lua-http

modules/http

HTTP/2 client/server for Lua.

lua-cqueues

modules/graphite

Send statistics over the Graphite protocol.

cmocka

unit tests

Unit testing framework.

Doxygen

documentation

Generating API documentation.

Sphinx and sphinx_rtd_theme

documentation

Building this HTML/PDF documentation.

breathe

documentation

Exposing Doxygen API doc to Sphinx.

libsystemd

daemon

Systemd watchdog support.

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.46 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).

Packaged dependencies

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

Note

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

Following example script will:

  • create new build directory named build_dir

  • configure installation path /tmp/kr

  • enable static build (to allow installation to non-standard path)

  • build Knot Resolver

  • install it into the previously configured path

$ meson build_dir --prefix=/tmp/kr --default-library=static
$ ninja -C build_dir
$ 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 build_dir
$ meson configure build_dir

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

$ meson 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 command runs all enabled tests. By default, only unit tests are enabled.

$ ninja -C build_dir
$ meson test -C build_dir

More comprehensive tests require you to install kresd into the configured prefix before running the test suite. They also have to be explicitly enabled by using either -Dconfig_tests=enabled for postinstall config tests, or -Dextra_tests=enabled for all tests, including deckard tests.

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

It’s also 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

HTML 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 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 follwing command. The

$ ninja -C build_dir dist

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

$ ./scripts/make-dev-archive.sh

Packaging

Recommended build options for packagers:

  • --buildtype=release for default flags (optimalization, 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 html documentation (see HTML Documentation)

  • -Dinstall_kresd_conf=enabled to install default config file

  • -Dclient=enabled to force build of kresc

  • -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 .