From 3d0386f27ca66379acf50199e1d1298386eeeeb8 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 6 May 2024 02:55:53 +0200 Subject: Adding upstream version 3.2.1. Signed-off-by: Daniel Baumann --- doc/Doxyfile | 19 +++ doc/NEWS.rst | 6 + doc/README.md | 27 +++++ doc/_static/.gitignore | 0 doc/build.rst | 321 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/conf.py | 71 +++++++++++ doc/daemon.rst | 1 + doc/doc.mk | 14 +++ doc/index.rst | 26 ++++ doc/kresd.8.in | 172 ++++++++++++++++++++++++++ doc/lib.rst | 58 +++++++++ doc/modules.rst | 37 ++++++ doc/modules_api.rst | 1 + doc/requirements.txt | 2 + doc/resolution.png | Bin 0 -> 95991 bytes 15 files changed, 755 insertions(+) create mode 100644 doc/Doxyfile create mode 100644 doc/NEWS.rst create mode 100644 doc/README.md create mode 100644 doc/_static/.gitignore create mode 100644 doc/build.rst create mode 100644 doc/conf.py create mode 100644 doc/daemon.rst create mode 100644 doc/doc.mk create mode 100644 doc/index.rst create mode 100644 doc/kresd.8.in create mode 100644 doc/lib.rst create mode 100644 doc/modules.rst create mode 100644 doc/modules_api.rst create mode 100644 doc/requirements.txt create mode 100644 doc/resolution.png (limited to 'doc') 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 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 `_ 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 `_ +-- Linux on x86_64 is unaffected but `Linux on aarch64 is +`_. + +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 ``_CFLAGS`` and ``_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 ` 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 `_. +* **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 `_. + +.. 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 `_ 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 `_ + +Building for packages +~~~~~~~~~~~~~~~~~~~~~ + +The build system supports DESTDIR_ + +.. Our amalgamation has fallen into an unmaintained state and probably doesn't work. +.. and `amalgamated builds `_. + +.. 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 `_. + +.. 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 `_ 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 +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 +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 +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 +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 +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 +(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 +(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 +Override the directory that is searched for modules. Default: @MODULEDIR@ +.TP +.B \-f\fI N\fR, \fB\-\-forks=\fI +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 Binary files /dev/null and b/doc/resolution.png differ -- cgit v1.2.3