Adding upstream version 3.2.1.upstream/3.2.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

15 files changed, 755 insertions, 0 deletions

diff --git a/doc/Doxyfile b/doc/Doxyfile
new file mode 100644
index 0000000..6e57cb3
--- /dev/null
+++ b/doc/Doxyfile
@@ -0,0 +1,19 @@
+PROJECT_NAME      = Knot Resolver library
+GENERATE_HTML     = NO
+GENERATE_XML      = YES
+GENERATE_LATEX    = NO
+GENERATE_MAN      = NO
+GENERATE_RTF      = NO
+CASE_SENSE_NAMES  = NO
+INPUT             = ../lib
+FILE_PATTERNS     = *.h
+QUIET             = YES
+RECURSIVE         = YES
+JAVADOC_AUTOBRIEF = YES
+AUTOLINK_SUPPORT  = YES
+XML_OUTPUT        = doxyxml
+HIDE_UNDOC_MEMBERS = YES
+HIDE_UNDOC_CLASSES = YES
+OPTIMIZE_OUTPUT_FOR_C = YES
+ENABLE_PREPROCESSING  = YES
+PREDEFINED        = NDEBUG
diff --git a/doc/NEWS.rst b/doc/NEWS.rst
new file mode 100644
index 0000000..4eb8194
--- /dev/null
+++ b/doc/NEWS.rst
@@ -0,0 +1,6 @@
+*************
+Release notes
+*************
+
+.. include:: ../NEWS
+
diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 0000000..6860672
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,27 @@
+## Documentation
+
+Each directory contains a README.md with the basic information, examples and usage.
+It does not however contain API documentation, which is built separately in this directory.
+
+### Requirements
+
+The code is documented with [Doxygen][doxygen] JavaDoc style, a prettified documentation
+also requires [breathe][breathe] and [Sphinx][sphinx] for building sane documentation pages.
+It is not however required.
+
+[doxygen]:https://www.stack.nl/~dimitri/doxygen/manual/index.html
+[breathe]: https://github.com/michaeljones/breathe
+[sphinx]: http://sphinx-doc.org/
+
+You can get the extra dependencies with pip:
+
+```sh
+pip install -U Sphinx breathe
+# Alternatively
+pip -r doc/requirements.txt
+```
+
+### Building documentation
+
+If you satisfy the requirements, it's as easy as `make doc`, which builds the documentation in this folder.
+
diff --git a/doc/_static/.gitignore b/doc/_static/.gitignore
new file mode 100644
index 0000000..e69de29
--- /dev/null
+++ b/doc/_static/.gitignore
diff --git a/doc/build.rst b/doc/build.rst
new file mode 100644
index 0000000..55667a4
--- /dev/null
+++ b/doc/build.rst
@@ -0,0 +1,321 @@
+Building project
+================
+
+Installing from packages
+------------------------
+
+The resolver is packaged for Debian, Fedora+EPEL, Ubuntu, Docker, NixOS/NixPkgs, FreeBSD, HomeBrew, and Turris Omnia.
+Some of these are maintained directly by the knot-resolver team.
+
+Refer to `project page <https://www.knot-resolver.cz/download>`_ for information about
+installing from packages. If packages are not available for your OS, see following sections
+to see how you can build it from sources (or package it), or use official `Docker images`_.
+
+Platform considerations
+-----------------------
+
+Knot-resolver is written for UNIX-like systems, mainly in C99.
+Portable I/O is provided by libuv_.
+Some 64-bit systems with LuaJIT 2.1 may be affected by
+`a problem <https://github.com/LuaJIT/LuaJIT/blob/v2.1/doc/status.html#L100>`_
+-- Linux on x86_64 is unaffected but `Linux on aarch64 is
+<https://gitlab.labs.nic.cz/knot/knot-resolver/issues/216>`_.
+
+Windows systems might theoretically work without large changes,
+but it's most likely broken and currently not planned to be supported.
+
+Requirements
+------------
+
+The following is a list of software required to build Knot Resolver from sources.
+
+.. csv-table::
+   :header: "Requirement", "Required by", "Notes"
+
+   "`GNU Make`_ 3.80+", "*all*", "*(build only)*"
+   "C and C++ compiler", "*all*", "*(build only)* [#]_"
+   "`pkg-config`_", "*all*", "*(build only)* [#]_"
+   "hexdump or xxd", "``daemon``", "*(build only)*"
+   "libknot_ 2.7.2+", "*all*", "Knot DNS libraries - requires autotools, GnuTLS, ..."
+   "LuaJIT_ 2.0+", "``daemon``", "Embedded scripting language."
+   "libuv_ 1.7+", "``daemon``", "Multiplatform I/O and services (libuv_ 1.0 with limitations [#]_)."
+   "lmdb", "``daemon``", "If missing, a static version is embedded."
+
+There are also *optional* packages that enable specific functionality in Knot Resolver, they are useful mainly for developers to build documentation and tests.
+
+.. csv-table::
+   :header: "Optional", "Needed for", "Notes"
+
+   "`lua-http`_", "``modules/http``", "HTTP/2 client/server for Lua."
+   "luasocket_", "``trust anchors, modules/stats``", "Sockets for Lua."
+   "luasec_", "``trust anchors``", "TLS for Lua."
+   "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 socket activation 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."
+
+.. [#] Requires C99, ``__attribute__((cleanup))`` and ``-MMD -MP`` for dependency file generation. GCC, Clang and ICC are supported.
+.. [#] You can use variables ``<dependency>_CFLAGS`` and ``<dependency>_LIBS`` to configure dependencies manually (i.e. ``libknot_CFLAGS`` and ``libknot_LIBS``).
+.. [#] libuv 1.7 brings SO_REUSEPORT support that is needed for multiple forks. libuv < 1.7 can be still used, but only in single-process mode. Use :ref:`different method <daemon-reuseport>` for load balancing.
+
+Packaged dependencies
+~~~~~~~~~~~~~~~~~~~~~
+
+Most of the dependencies can be resolved from packages, here's an overview for several platforms.
+
+* **Debian** (since *sid*) - current stable doesn't have libknot and libuv, which must be installed from sources.
+
+.. code-block:: bash
+
+   sudo apt-get install pkg-config libknot-dev libuv1-dev libcmocka-dev libluajit-5.1-dev
+
+* **Ubuntu** - unknown.
+* **Fedora**
+
+.. code-block:: bash
+
+   # minimal build
+   sudo dnf install @buildsys-build knot-devel libuv-devel luajit-devel
+   # unit tests
+   sudo dnf install libcmocka-devel
+   # integration tests
+   sudo dnf install cmake git python-dns python-jinja2
+   # optional features
+   sudo dnf install lua-sec-compat lua-socket-compat systemd-devel
+   # docs
+   sudo dnf install doxygen python-breathe python-sphinx
+
+* **RHEL/CentOS** - unknown.
+* **openSUSE** - there is an `experimental package <https://build.opensuse.org/package/show/server:dns/knot-resolver>`_.
+* **FreeBSD** - when installing from ports, all dependencies will install automatically, corresponding to the selected options.
+* **NetBSD** - unknown.
+* **OpenBSD** - unknown.
+* **Mac OS X** - the dependencies can be found through `Homebrew <http://brew.sh/>`_.
+
+.. code-block:: bash
+
+   brew install pkg-config libuv luajit cmocka
+
+Building from sources
+---------------------
+
+Initialize git submodules first.
+
+.. code-block:: bash
+
+    $ git submodule update --init --recursive
+
+The Knot Resolver depends on the the Knot DNS library, recent version of libuv_, and LuaJIT_.
+
+.. code-block:: bash
+
+   $ make info # See what's missing
+
+When you have all the dependencies ready, you can build and install.
+
+.. code-block:: bash
+
+   $ make PREFIX="/usr/local"
+   $ make install PREFIX="/usr/local"
+
+.. note:: Always build with ``PREFIX`` if you want to install, as it is hardcoded in the executable for module search path.
+    Production code should be compiled with ``-DNDEBUG``.
+    If you build the binary with ``-DNOVERBOSELOG``, it won't be possible to turn on verbose logging; we advise packagers against using that flag.
+
+.. note:: If you build with ``PREFIX``, you may need to also set the ``LDFLAGS`` for the libraries:
+
+.. code-block:: bash
+
+   make LDFLAGS="-Wl,-rpath=/usr/local/lib" PREFIX="/usr/local"
+
+Alternatively you can build only specific parts of the project, i.e. ``library``.
+
+.. code-block:: bash
+
+   $ make lib
+   $ make lib-install
+
+.. note:: Documentation is not built by default, run ``make doc`` to build it.
+
+Building with security compiler flags
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Knot Resolver enables certain `security compile-time flags <https://wiki.debian.org/Hardening#Notes_on_Memory_Corruption_Mitigation_Methods>`_ that do not affect performance.
+You can add more flags to the build by appending them to `CFLAGS` variable, e.g. ``make CFLAGS="-fstack-protector"``.
+
+  .. csv-table::
+   :header: "Method", "Status", "Notes"
+
+   "-fstack-protector", "*disabled*", "(must be specifically enabled in CFLAGS)"
+   "-D_FORTIFY_SOURCE=2", "**enabled**", ""
+   "-pie", "**enabled**", "enables ASLR for kresd (disable with ``make HARDENING=no``)"
+   "RELRO", "**enabled**", "full [#]_"
+
+You can also disable linker hardening when it's unsupported with ``make HARDENING=no``.
+
+.. [#] See `checksec.sh <http://www.trapkit.de/tools/checksec.html>`_
+
+Building for packages
+~~~~~~~~~~~~~~~~~~~~~
+
+The build system supports DESTDIR_
+
+.. Our amalgamation has fallen into an unmaintained state and probably doesn't work.
+.. and `amalgamated builds <https://www.sqlite.org/amalgamation.html>`_.
+
+.. code-block:: bash
+
+   $ make install DESTDIR=/tmp/stage
+..   $ make all install AMALG=yes # Amalgamated build
+
+.. Amalgamated build assembles everything in one source file and compiles it. It is useful for packages, as the compiler sees the whole program and is able to produce a smaller and faster binary. On the other hand, it complicates debugging.
+
+.. tip:: There is a template for service file and AppArmor profile to help you kickstart the package.
+
+Default paths
+~~~~~~~~~~~~~
+
+The default installation follows FHS with several custom paths for configuration and modules.
+All paths are prefixed with ``PREFIX`` variable by default if not specified otherwise.
+
+  .. csv-table::
+   :header: "Component", "Variable", "Default", "Notes"
+
+   "library", "``LIBDIR``", "``$(PREFIX)/lib``", "pkg-config is auto-generated [#]_"
+   "daemon",  "``SBINDIR``", "``$(PREFIX)/sbin``", ""
+   "configuration", "``ETCDIR``", "``$(PREFIX)/etc/knot-resolver``", "Configuration file, templates."
+   "modules", "``MODULEDIR``", "``$(LIBDIR)/kdns_modules``", "Runtime directory for loading dynamic modules [#]_."
+   "trust anchor file", "``KEYFILE_DEFAULT``", "*(none)*", "Path to read-only trust anchor file, which is used as fallback when no other file is specified. [#]_"
+   "work directory", "", "the current directory", "Run directory for daemon. (Only relevant during run time, not e.g. during installation.)"
+
+.. [#] The ``libkres.pc`` is installed in ``$(LIBDIR)/pkgconfig``.
+.. [#] The default moduledir can be changed with `-m` option to `kresd` daemon or by calling `moduledir()` function from lua.
+.. [#] If no other trust anchor is specified by user, the compiled-in path ``KEYFILE_DEFAULT`` must contain a valid trust anchor. This is typically used by distributions which provide DNSSEC root trust anchors as part of distribution package. Users can disable the built-in trust anchor by adding ``trust_anchors.keyfile_default = nil`` to their configuration.
+
+.. note:: Each module is self-contained and may install additional bundled files within ``$(MODULEDIR)/$(modulename)``. These files should be read-only, non-executable.
+
+Static or dynamic?
+~~~~~~~~~~~~~~~~~~
+
+By default the resolver library is built as a dynamic library with versioned ABI. You can revert to static build with ``BUILDMODE`` variable.
+
+.. code-block:: bash
+
+   $ make BUILDMODE=dynamic # Default, create dynamic library
+   $ make BUILDMODE=static  # Create static library
+
+When the library is linked statically, it usually produces a smaller binary. However linking it to various C modules might violate ODR and increase the size.
+
+Resolving dependencies
+~~~~~~~~~~~~~~~~~~~~~~
+
+The build system relies on `pkg-config`_ to find dependencies.
+You can override it to force custom versions of the software by environment variables.
+
+.. code-block:: bash
+
+   $ make libknot_CFLAGS="-I/opt/include" libknot_LIBS="-L/opt/lib -lknot -ldnssec"
+
+Optional dependencies may be disabled as well using ``HAS_x=yes|no`` variable.
+
+.. code-block:: bash
+
+   $ make HAS_go=no HAS_cmocka=no
+
+.. warning:: If the dependencies lie outside of library search path, you need to add them somehow.
+   Try ``LD_LIBRARY_PATH`` on Linux/BSD, and ``DYLD_FALLBACK_LIBRARY_PATH`` on OS X.
+   Otherwise you need to add the locations to linker search path.
+
+Building extras
+~~~~~~~~~~~~~~~
+
+The project can be built with code coverage tracking using the ``COVERAGE=1`` variable.
+
+The `make coverage` target gathers both gcov code coverage for C files, and luacov_ code coverage for Lua files and merges it for analysis. It requires lcov_ to be installed.
+
+.. code-block:: bash
+
+   $ make coverage
+
+Running unit and integration tests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The linter requires luacheck_ and `clang-tidy`_ and is executed by ``make lint``.
+The unit tests require cmocka_ and are executed by ``make check``.
+Tests for the dnstap module need go and are executed by ``make ckeck-dnstap``.
+
+The integration tests use Deckard, the `DNS test harness <deckard>`_.
+
+.. code-block:: bash
+
+	$  make check-integration
+
+Note that the daemon and modules must be installed first before running integration tests, the reason is that the daemon
+is otherwise unable to find and load modules.
+
+Read the `documentation <deckard_doc>`_ for more information about requirements, how to run it and extend it.
+
+Getting Docker image
+--------------------
+
+Docker images require only either Linux or a Linux VM (see boot2docker_ on OS X).
+
+.. code-block:: bash
+
+   $ docker run cznic/knot-resolver
+
+See the `Docker images`_ page for more information and options.
+You can hack on the container by changing the container entrypoint to shell like:
+
+.. code-block:: bash
+
+   $ docker run -it --entrypoint=/bin/bash cznic/knot-resolver
+
+.. tip:: You can build the Docker image yourself with ``docker build -t knot-resolver scripts``.
+
+.. _Docker images: https://hub.docker.com/r/cznic/knot-resolver
+.. _libuv: https://github.com/libuv/libuv
+.. _MSVC: https://msdn.microsoft.com/en-us/vstudio/hh386302.aspx
+.. _MinGW: http://www.mingw.org/
+.. _Dockerfile: https://registry.hub.docker.com/u/cznic/knot-resolver/dockerfile/
+
+.. _Lua: https://www.lua.org/about.html
+.. _LuaJIT: http://luajit.org/luajit.html
+.. _Go: https://golang.org
+.. _geoip: https://github.com/abh/geoip
+.. _Doxygen: https://www.stack.nl/~dimitri/doxygen/manual/index.html
+.. _breathe: https://github.com/michaeljones/breathe
+.. _Sphinx: http://sphinx-doc.org/
+.. _sphinx_rtd_theme: https://pypi.python.org/pypi/sphinx_rtd_theme
+.. _GNU Make: https://www.gnu.org/software/make/
+.. _pkg-config: https://www.freedesktop.org/wiki/Software/pkg-config/
+.. _libknot: https://gitlab.labs.nic.cz/knot/knot-dns
+.. _cmocka: https://cmocka.org/
+.. _Python: https://www.python.org/
+.. _luasec: https://luarocks.org/modules/brunoos/luasec
+.. _luasocket: https://luarocks.org/modules/luarocks/luasocket
+.. _lua-http: https://luarocks.org/modules/daurnimator/http
+
+.. _boot2docker: http://boot2docker.io/
+
+.. _deckard: https://gitlab.labs.nic.cz/knot/deckard
+.. _deckard_doc: https://gitlab.labs.nic.cz/knot/knot-resolver/blob/master/tests/README.rst
+
+.. _libsystemd: https://www.freedesktop.org/wiki/Software/systemd/
+.. _dnstap: http://dnstap.info/
+.. _libprotobuf: https://developers.google.com/protocol-buffers/
+.. _libprotobuf-c: https://github.com/protobuf-c/protobuf-c/wiki
+.. _libfstrm: https://github.com/farsightsec/fstrm
+.. _luacheck: http://luacheck.readthedocs.io
+.. _clang-tidy: http://clang.llvm.org/extra/clang-tidy/index.html
+.. _luacov: https://keplerproject.github.io/luacov/
+.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php
+
+.. _DESTDIR: https://www.gnu.org/prep/standards/html_node/DESTDIR.html
diff --git a/doc/conf.py b/doc/conf.py
new file mode 100644
index 0000000..dc7411d
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,71 @@
+# -*- coding: utf-8 -*-
+
+import sys, os, re, subprocess
+
+import sphinx_rtd_theme
+
+# -- General configuration -----------------------------------------------------
+
+if os.environ.get('READTHEDOCS', None) == 'True':
+  subprocess.call('doxygen')
+
+# Add any Sphinx extension module names here, as strings.
+extensions = ['sphinx.ext.todo', 'sphinx.ext.viewcode', 'breathe']
+
+# Breathe configuration
+breathe_projects = { "libkres": "doxyxml" }
+breathe_default_project = "libkres"
+breathe_domain_by_extension = {"h" : "c"}
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+master_doc = 'index'
+
+# General information about the project.
+project = u'Knot Resolver'
+copyright = u'2014-2018 CZ.NIC labs'
+version = { k[0][0]: k[0][1] for k in filter(None, [re.findall(r'(MAJOR|MINOR|PATCH) := ([0-9]+)',line) for line in open('../config.mk')])}
+version = '%s.%s.%s' % (version['MAJOR'], version['MINOR'], version['PATCH'])
+release = version
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+highlight_language = 'c'
+primary_domain = 'c'
+
+# -- Options for HTML output ---------------------------------------------------
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'apidoc'
+
+# Theme
+html_theme = 'sphinx_rtd_theme'
+html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'format.tex', u'Knot Resolver',
+   u'CZ.NIC Labs', 'manual'),
+]
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    ('index', 'libkres', u'libkres documentation',
+     [u'CZ.NIC Labs'], 1)
+]
+
diff --git a/doc/daemon.rst b/doc/daemon.rst
new file mode 100644
index 0000000..dbeecab
--- /dev/null
+++ b/doc/daemon.rst
@@ -0,0 +1 @@
+.. include:: ../daemon/README.rst
\ No newline at end of file
diff --git a/doc/doc.mk b/doc/doc.mk
new file mode 100644
index 0000000..58c299e
--- /dev/null
+++ b/doc/doc.mk
@@ -0,0 +1,14 @@
+ifeq ($(HAS_doxygen)|$(HAS_sphinx-build), yes|yes)
+doc-doxygen:
+	@cd doc && $(doxygen_BIN)
+doc-html: doc-doxygen
+	@cd doc && $(sphinx-build_BIN) $(SPHINXFLAGS) -b html . html
+else
+doc-html:
+	$(error doxygen and sphinx must be installed)
+endif
+doc-clean:
+	rm -rf doc/doxyxml doc/*.db doc/html
+
+.PHONY: doc-doxygen doc-html doc-clean
+
diff --git a/doc/index.rst b/doc/index.rst
new file mode 100644
index 0000000..683c77c
--- /dev/null
+++ b/doc/index.rst
@@ -0,0 +1,26 @@
+#############
+Knot Resolver
+#############
+
+Knot Resolver is a minimalistic implementation of a caching validating DNS resolver.
+Modular architecture keeps the core tiny and efficient,
+and it provides a state-machine like API for extensions.
+
+.. toctree::
+   :maxdepth: 2
+
+   daemon
+   modules
+   build
+   lib
+   modules_api
+   NEWS
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+
diff --git a/doc/kresd.8.in b/doc/kresd.8.in
new file mode 100644
index 0000000..0fa8cc9
--- /dev/null
+++ b/doc/kresd.8.in
@@ -0,0 +1,172 @@
+.TH "kresd" "8" "@DATE@" "CZ.NIC" "Knot Resolver @VERSION@"
+.\"
+.\" kresd.8 -- kresd daemon manpage
+.\"
+.\" Copyright (c) 2016, CZ.NIC. All rights reserved.
+.\"
+.\" See COPYING for the license.
+.\"
+.\"
+.SH "NAME"
+.B kresd
+\- Knot @VERSION@ full caching resolver.
+.SH "SYNOPSIS"
+.B kresd
+.RB [ \-a | \-\-addr
+.IR addr[@port] ]
+.RB [ \-t | \-\-tls
+.IR addr[@port] ]
+.RB [ \-S | \-\-fd
+.IR fd ]
+.RB [ \-T | \-\-tlsfd
+.IR fd ]
+.RB [ \-c | \-\-config
+.IR config ]
+.RB [ \-k | \-\-keyfile
+.IR keyfile ]
+.RB [ \-K | \-\-keyfile\-ro
+.IR keyfile ]
+.RB [ \-m | \-\-moduledir
+.IR path ]
+.RB [ \-f | \-\-forks
+.IR N ]
+.RB [ \-q | \-\-quiet ]
+.RB [ \-v | \-\-verbose ]
+.RB [ \-V | \-\-version ]
+.RB [ \-h | \-\-help ]
+.IR [rundir]
+.SH "DESCRIPTION"
+.B Knot Resolver is a DNSSEC-enabled full caching resolver.
+.P
+Default mode of operation: when it receives a DNS query it iteratively
+asks authoritative nameservers starting from root zone (.) and ending
+with a nameservers authoritative for queried name. Automatic DNSSEC means
+verification of integrity of authoritative responses by following
+keys and signatures starting from root. Root trust anchor is automatically
+bootstrapped from IANA, or you can provide a file with root trust anchors
+(same format as Unbound or BIND9 root keys file).
+
+The daemon also caches intermediate answers into cache, which by default
+uses LMDB memory-mapped database. This has a significant advantage over
+in-memory caches as the process may be stopped and restarted without
+loss of cache entries. In multi-user scenario a shared cache
+is potential privacy/security issue, with kresd each user can have resolver cache
+in their private directory and use it in similar fashion to keychain.
+
+By default, no configuration is needed, only a directory where the daemon can store
+runtime data (cache, control sockets, ...)
+.P
+To use a locally running
+.B kresd
+for resolving put
+.sp
+.RS 6n
+nameserver 127.0.0.1
+.RE
+.sp
+into
+.IR resolv.conf (5)
+and start
+.B kresd
+.PP
+.nf
+.RS 6n
+$ kresd -a 127.0.0.1 -k root.keys
+[system] interactive mode
+>
+.RE
+.fi
+.PP
+.P
+The daemon may be configured also as a plain forwarder using query policies, that requires
+creating a file
+.B config
+in daemon runtime directory. See \fIdaemon/README.md\fR for more information about interacting
+with CLI and configuration file options, or visit
+.B https://knot-resolver.readthedocs.io
+online documentation.
+.PP
+.nf
+.RS 6n
+# Create a basic forwarder configuration
+$ cat << EOF > config
+modules = { 'policy' }
+policy.add(policy.all(policy.FORWARD('192.168.1.1')))
+$ kresd -a 127.0.0.1 -k root.keys
+EOF
+.RE
+.fi
+.PP
+.P
+The available CLI options are:
+.TP
+.B \-a\fI addr[@port]\fR, \fB\-\-addr=\fI<addr[@port]>
+Listen on given address (and port) pair. If no port is given, \fI53\fR is used as a default.
+Option may be passed multiple times to listen on more addresses.
+.TP
+.B \-t\fI addr[@port]\fR, \fB\-\-tls=\fI<addr[@port]>
+Listen using TLS on given address (and port) pair. If no port is
+given, \fI853\fR is used as a default.  Option may be passed multiple
+times to listen on more addresses.
+.TP
+.B \-S\fI fd\fR, \fB\-\-fd=\fI<fd>
+Listen on given file descriptor(s), passed by supervisor.
+Option may be passed multiple times to listen on more file descriptors.
+.TP
+.B \-T\fI fd\fR, \-\-tlsfd=\fI<fd>
+Listen using TLS on given file descriptor(s), passed by supervisor.
+Option may be passed multiple times to listen on more file descriptors.
+.TP
+.B \-c\fI config\fR, \fB\-\-config=\fI<config>
+Set the config file with settings for kresd to read instead of reading the
+file at the default location (\fIconfig\fR). The syntax is
+described in \fIdaemon/README.md\fR.
+.TP
+.B \-k\fI keyfile\fR, \fB\-\-keyfile=\fI<keyfile>
+(Recommended!) Automatically managed root trust anchors file.
+Root trust anchors in this file are managed using standard RFC 5011 (Automated Updates of DNS Security Trust Anchors).
+Kresd needs write access to the directory containing the keyfile.
+
+If the file does not exist, it will be automatically boostrapped from IANA using HTTPS protocol
+and warning that you need to to check the key before trusting it will be issued.
+
+The file contains DNSKEY/DS records in presentation format,
+and is compatible with Unbound and BIND 9 root key files.
+.TP
+.B \-K\fI keyfile\fR, \fB\-\-keyfile\-ro=\fI<keyfile>
+(Discouraged) Static root trust anchors file. The file is not updated by kresd. Use of this option is discouraged because it will break your installation when the trust anchor key changes!
+
+Default: "@KEYFILE_DEFAULT@" (can be empty if your distribution did not provide one)
+.TP
+.B \-m\fI path\fR, \fB\-\-moduledir=\fI<path>
+Override the directory that is searched for modules.  Default: @MODULEDIR@
+.TP
+.B \-f\fI N\fR, \fB\-\-forks=\fI<N>
+With this option, the daemon is started in non-interactive mode and instead creates a
+UNIX socket in \fIrundir\fR that the operator can connect to for interactive session.
+A number greater than 1 forks the daemon N times, all forks will bind to same addresses
+and the kernel will load-balance between them on Linux with \fISO_REUSEPORT\fR support.
+
+When socket-activated and supervised by systemd or the equivalent, kresd defaults to
+--forks=1, and must not be set to any other value.  If you want multiple concurrent
+processes supervised in this way, they should be supervised independently (see
+\fBkresd.systemd(7)\fR).
+.TP
+.B \-q\fR, \fB\-\-quiet
+Daemon will refrain from printing the command prompt.
+.TP
+.B \-v\fR, \fB\-\-verbose
+Increase verbosity. If given multiple times, more information is logged.
+This is in addition to the verbosity (if any) from the config file.
+.TP
+.B \-h
+Show short commandline option help.
+.TP
+.B \-V
+Show the version.
+.SH "SEE ALSO"
+\fIkresd.systemd(7)\fR,
+\fIhttps://knot-resolver.readthedocs.io\fR
+.SH "AUTHORS"
+.B kresd
+developers are mentioned in the AUTHORS file in the distribution.
diff --git a/doc/lib.rst b/doc/lib.rst
new file mode 100644
index 0000000..6eeaa13
--- /dev/null
+++ b/doc/lib.rst
@@ -0,0 +1,58 @@
+.. _lib_index:
+
+.. include:: ../lib/README.rst
+
+API reference
+=============
+
+.. contents::
+   :depth: 1
+   :local:
+
+.. _lib_api_rplan:
+
+Name resolution
+---------------
+
+.. doxygenfile:: resolve.h
+   :project: libkres
+.. doxygenfile:: rplan.h
+   :project: libkres
+
+.. _lib_api_cache:
+
+Cache
+-----
+
+.. doxygenfile:: cache/api.h
+   :project: libkres
+
+.. _lib_api_nameservers:
+
+Nameservers
+-----------
+
+.. doxygenfile:: nsrep.h
+   :project: libkres
+.. doxygenfile:: zonecut.h
+   :project: libkres
+
+.. _lib_api_modules:
+
+Modules
+-------
+
+.. doxygenfile:: module.h
+   :project: libkres
+
+Utilities
+---------
+
+.. doxygenfile:: utils.h
+   :project: libkres
+.. doxygenfile:: defines.h
+   :project: libkres
+
+.. _lib_generics:
+
+.. include:: ../lib/generic/README.rst
diff --git a/doc/modules.rst b/doc/modules.rst
new file mode 100644
index 0000000..ce65940
--- /dev/null
+++ b/doc/modules.rst
@@ -0,0 +1,37 @@
+.. _modules-implemented:
+
+*********************
+Knot Resolver modules
+*********************
+
+.. contents::
+   :depth: 1
+   :local:
+
+.. include:: ../modules/hints/README.rst
+.. include:: ../modules/stats/README.rst
+.. include:: ../modules/policy/README.rst
+.. include:: ../modules/view/README.rst
+.. include:: ../modules/predict/README.rst
+.. include:: ../modules/http/README.rst
+.. include:: ../modules/daf/README.rst
+.. include:: ../modules/rebinding/README.rst
+.. include:: ../modules/graphite/README.rst
+.. include:: ../modules/etcd/README.rst
+.. include:: ../modules/dns64/README.rst
+.. include:: ../modules/renumber/README.rst
+.. .. include:: ../modules/cookies/README.rst
+.. include:: ../modules/bogus_log/README.rst
+.. include:: ../modules/nsid/README.rst
+.. include:: ../modules/workarounds/README.rst
+.. include:: ../modules/dnstap/README.rst
+.. include:: ../modules/ta_signal_query/README.rst
+.. include:: ../modules/ta_sentinel/README.rst
+.. include:: ../modules/priming/README.rst
+.. include:: ../modules/detect_time_skew/README.rst
+.. include:: ../modules/detect_time_jump/README.rst
+.. include:: ../modules/rfc7706.rst
+.. include:: ../modules/prefill/README.rst
+.. include:: ../modules/serve_stale/README.rst
+.. include:: ../modules/edns_keepalive/README.rst
+.. include:: ../modules/experimental_dot_auth/README.rst
diff --git a/doc/modules_api.rst b/doc/modules_api.rst
new file mode 100644
index 0000000..2f0f147
--- /dev/null
+++ b/doc/modules_api.rst
@@ -0,0 +1 @@
+.. include:: ../modules/README.rst
\ No newline at end of file
diff --git a/doc/requirements.txt b/doc/requirements.txt
new file mode 100644
index 0000000..7f36028
--- /dev/null
+++ b/doc/requirements.txt
@@ -0,0 +1,2 @@
+Sphinx
+breathe
diff --git a/doc/resolution.png b/doc/resolution.png
new file mode 100644
index 0000000..65d5027
--- /dev/null
+++ b/doc/resolution.png