doc/dev/systemd-multiinst.rst

+../../systemd/multiinst.rst
\ No newline at end of file

doc/dev/worker_api.rst

+.. SPDX-License-Identifier: GPL-3.0-or-later
+
+Worker API reference
+====================
+
+.. doxygenfile:: daemon/worker.h
+

doc/doc.mk

-doc-doxygen:
-	@cd doc && $(doxygen_BIN) 
-doc-html: doc-doxygen
-	@cd doc && $(sphinx-build_BIN) -b html . html
-doc-clean:
-	rm -rf doc/doxyxml doc/*.db doc/html
-
-.PHONY: doc-doxygen doc-html doc-clean
-

doc/index.rst

-#################
-Knot DNS Resolver
-#################
-
-The Knot DNS Resolver is a minimalistic caching resolver implementation.
-The project provides both a resolver library and a small daemon.
-Modular architecture of the library keeps the core tiny and efficient, and provides a state-machine like API for extensions.
-
-.. toctree::
-   :maxdepth: 2
-
-   build
-   lib
-   daemon
-   modules
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

doc/kresctl.8.in

+.TH "kresctl" "8" "@date@" "CZ.NIC" "Knot Resolver @version@"
+.\"
+.\" kresctl.8 -- Knot Resolver control tool manpage
+.\"
+.\" Copyright (c) CZ.NIC. All rights reserved.
+.\"
+.\" SPDX-License-Identifier: GPL-3.0-or-later
+.\"
+.\"
+.SH "NAME"
+.B kresctl
+\- Control Knot Resolver @version@, the full caching DNSSEC-enabled resolver
+.SH "SYNOPSIS"
+.B kresctl
+.RB [ \-s | \-\-socket
+.IR API_SOCKET ]
+.IR <command>
+.IR <args>
+.SH "DESCRIPTION"
+.B \fIkresctl\fR is a control tool for Knot Resolver, a DNSSEC-enabled full caching resolver.
+.P
+
+\fBkresctl\fR may be used to control and inspect the configuration of running
+Knot Resolver via its HTTP API.
+
+Full documentation is available at
+\fIhttps://www.knot-resolver.cz/documentation/latest/\fR or in package
+documentation (available as knot-resolver-doc package in most distributions.
+.SH OPTIONS
+The available options are:
+.TP
+.B \-s\fI <api_socket>\fR, \fB\-\-socket \fI<api_socket>
+
+Specify how to connect to a running Knot Resolver. Accepts path to Unix-domain
+socket  or \fIhost:port\fR. Defaults to \fI/var/run/knot-resolver/kres-api.sock\fR
+
+Some commands do not require communication with the running resolver. In such
+cases, the value of this option is ignored and the command may succeed even
+if the socket is invalid.
+.B \-h, --help
+Print help message and exit.
+.SH COMMANDS
+.TP
+.B config [-d|--delete] [--stdin] \fIjson_ptr\fR \fI[new_value]\fR
+Get or modify resolver's runtime configuration.
+
+\fIjson_ptr\fR follows \fBRFC 6901\fR and specifies, which part of the configuration
+will the tool operate on. This argument is required. When not given any additional
+options or arguments, prints the current configured value. Equivalent to GET method
+in the underlying HTTP API.
+
+When \fB-d\fR or \fB--delete\fR is provided, \fBkresctl\fB tries to remove
+the runtime configuration subtree. The operation fails if it renders the
+configuration invalid. Equivalent to the DELETE method in the HTTP API.
+
+When \fB--stdin\fR or \fInew_value\fR are provided, the new value (from the
+argument or from reading stdin) is put into the configuration at the given
+\fIjson_ptr\fR. The operation fails if it renders the configuration invalid.
+Equivalent to PUT method in the underlying HTTP API.
+.TP
+.B stop
+Gracefully stops the running resolver.
+.SH "SEE ALSO"
+\fBkresd(8)\fR, @man_seealso_systemd@\fIhttps://www.knot-resolver.cz/documentation/latest/\fR
+.SH "AUTHORS"
+.B kresd
+developers are mentioned in the AUTHORS file in the distribution.

doc/kresd.8.in

+.TH "kresd" "8" "@date@" "CZ.NIC" "Knot Resolver @version@"
+.\"
+.\" kresd.8 -- kresd daemon manpage
+.\"
+.\" Copyright (c) CZ.NIC. All rights reserved.
+.\"
+.\" SPDX-License-Identifier: GPL-3.0-or-later
+.\"
+.\"
+.SH "NAME"
+.B kresd
+\- full caching DNSSEC-enabled Knot Resolver @version@.
+.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 [ \-n | \-\-noninteractive ]
+.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.
+
+.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
+
+.P
+The daemon may be configured also as a plain forwarder using query policies.
+This requires using a config file. Please refer to documentation for
+configuration file options. It is available at
+\fIhttps://www.knot-resolver.cz/documentation/latest/\fR or in package
+documentation (available as knot-resolver-doc package in most distributions).
+
+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).
+.TP
+.B \-n\fR, \fB\-\-noninteractive
+Daemon will refrain from entering into read-eval-print loop for stdin+stdout.
+.TP
+.B \-q\fR, \fB\-\-quiet
+Daemon will refrain from printing the command prompt.
+.TP
+.B \-v\fR, \fB\-\-verbose
+Increase logging to debug level.
+.TP
+.B \-h
+Show short command-line option help.
+.TP
+.B \-V
+Show the version.
+.SH "SEE ALSO"
+@man_seealso_systemd@\fIhttps://www.knot-resolver.cz/documentation/latest/\fR
+.SH "AUTHORS"
+.B kresd
+developers are mentioned in the AUTHORS file in the distribution.

doc/meson.build

+# documentation
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+# man page
+man_config = configuration_data()
+man_config.set('version', meson.project_version())
+man_config.set('date', run_command('../scripts/lib/get-date.sh', check: true).stdout())
+
+man_config.set('man_seealso_systemd', '')
+if systemd_legacy_units == 'enabled'
+  man_config.set('man_seealso_systemd', '\\fIkresd.systemd(7)\\fR, ')
+endif
+
+man_kresd = configure_file(
+  input: 'kresd.8.in',
+  output: 'kresd.8',
+  configuration: man_config,
+)
+install_man(man_kresd)
+
+man_kresctl = configure_file(
+  input: 'kresctl.8.in',
+  output: 'kresctl.8',
+  configuration: man_config,
+)
+install_man(man_kresctl)
+
+# html and info documentation
+if get_option('doc') == 'enabled'
+  message('--- doc dependencies ---')
+  doxygen = find_program('doxygen')
+  sphinx_build = find_program('sphinx-build-3', required: false)
+  if not sphinx_build.found()
+    sphinx_build = find_program('sphinx-build')
+  endif
+
+  # python dependencies: breathe, sphinx_rtd_theme
+  python_breathe = run_command('python3', '-c', 'import breathe', check: false)
+  if python_breathe.returncode() != 0
+    python_breathe = run_command('python2', '-c', 'import breathe', check: false)
+    if python_breathe.returncode() != 0
+      error('missing doc dependency: python breathe')
+    endif
+    python = 'python2'
+  else
+    python = 'python3'
+  endif
+
+  python_sphinx_rtd_theme = run_command(python, '-c', 'import sphinx_rtd_theme', check: false)
+  if python_sphinx_rtd_theme.returncode() != 0
+    error('missing doc dependency: python sphinx_rtd_theme')
+  endif
+
+  python_sphinx_tabs = run_command(python, '-c', 'import sphinx_tabs', check: false)
+  if python_sphinx_tabs.returncode() != 0
+    error('missing doc dependency: python python-sphinx-tabs')
+  endif
+
+  jsonschemaforhumans = run_command(python, '-c', 'import json_schema_for_humans', check: false)
+  if jsonschemaforhumans.returncode() != 0
+    error('missing doc dependency: python json-schema-for-humans')
+  endif
+
+  message('------------------------')
+
+  # install html docs
+  install_subdir(
+    meson.current_source_dir() / 'html',
+    install_dir: doc_dir,
+  )
+
+endif
+
+
+make_doc = find_program('../scripts/meson/make-doc.sh')
+run_target(
+  'doc',
+  command: make_doc
+)
+
+
+run_target(
+  'doc-strict',
+  command: [make_doc, '-W']
+)

doc/modules.rst

-.. include:: ../modules/README.rst
-
-.. _modules-implemented:
-
-Implemented modules
-===================
-
-.. contents::
-   :depth: 1
-   :local:
-
-.. include:: ../modules/hints/README.rst
-.. include:: ../modules/block/README.rst
-.. include:: ../modules/stats/README.rst
-.. include:: ../modules/prefetch/README.rst
-.. include:: ../modules/cachectl/README.rst
-.. include:: ../modules/graphite/README.rst
-.. include:: ../modules/ketcd/README.rst
-.. include:: ../modules/kmemcached/README.rst
-.. include:: ../modules/redis/README.rst

doc/requirements.txt

-Sphinx
-breathe<=3.2.0
+Sphinx>=3.0.0
+sphinx-tabs
+breathe
+json-schema-for-humans
+sphinx_rtd_theme