diff --git a/.gitignore b/.gitignore
index d25da824049eae781a16036dc05379c3bf9b2c74..f51c67877eb769cd3df13e11896c25540030d426 100644
--- a/.gitignore
+++ b/.gitignore
@@ -77,3 +77,7 @@
# alternative allocators
/src/allocator.h
/src/allocators/
+
+# sphinx documentation
+/doc/_build/
+/doc/conf.py
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 34911796556be0021020df98744be5099c8d29d9..5656ab4c352415515b3bc52d448120f034e35f71 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,35 +1,30 @@
-PAPER =
-BUILDDIR = _build
-
-# Internal variables.
-PAPEROPT_a4 = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+SPHINXBUILDDIR = _build
+ALLSPHINXOPTS = -d $(SPHINXBUILDDIR)/doctrees -D latex_paper_size=a4 $(SPHINXOPTS) .
.PHONY: help html dirhtml singlehtml pdf info doctest
if HAVE_SPHINXBUILD
html:
- $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/html
@echo
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+ @echo "Build finished. The HTML pages are in $(SPHINXBUILDDIR)/html."
dirhtml:
- $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/dirhtml
@echo
- @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+ @echo "Build finished. The HTML pages are in $(SPHINXBUILDDIR)/dirhtml."
singlehtml:
- $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/singlehtml
@echo
- @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+ @echo "Build finished. The HTML page is in $(SPHINXBUILDDIR)/singlehtml."
if HAVE_PDFLATEX
pdf:
- $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
- $(MAKE) -C $(BUILDDIR)/latex all-pdf
- @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+ $(MAKE) -C $(SPHINXBUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(SPHINXBUILDDIR)/latex."
else
pdf:
@echo "You need to install pdflatex and re-run configure to be"
@@ -38,37 +33,21 @@ endif
if HAVE_MAKEINFO
info:
- $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+ $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
- make -C $(BUILDDIR)/texinfo info
- @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+ make -C $(SPHINXBUILDDIR)/texinfo info
+ @echo "makeinfo finished; the Info files are in $(SPHINXBUILDDIR)/texinfo."
else
@echo "You need to install GNU Texinfo and re-run configure to be"
@echo "able to generate info pages."
endif
doctest:
- $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
- "results in $(BUILDDIR)/doctest/output.txt."
+ "results in $(SPHINXBUILDDIR)/doctest/output.txt."
else
html pdf info doctest:
@echo "Please install sphinx (python-sphinx) to generate Knot DNS documentation."
endif
-
-#info_TEXINFOS = knot.texi
-#knot_TEXINFOS = \
-# configuration.texi \
-# indices.texi \
-# installation.texi \
-# introduction.texi \
-# knot.texi \
-# migration.texi \
-# reference.texi \
-# requirements.texi \
-# running.texi \
-# security.texi \
-# synth_record.texi \
-# troubleshooting.texi \
-# version.texi
diff --git a/doc/configuration.rst b/doc/configuration.rst
index 185d75e6438352293713af7e43c53ebedfe29fb2..d8bb1f2264553e449306f28601b547d72c94a19d 100644
--- a/doc/configuration.rst
+++ b/doc/configuration.rst
@@ -4,3 +4,442 @@ Knot DNS Configuration
In this chapter we provide suggested configurations and explain the
meaning of individual configuration options.
+
+Minimal configuration
+=====================
+
+The following configuration presents a minimal configuration file
+which can be used as a base for your Knot DNS setup::
+
+ # This is a sample of a minimal configuration file for Knot DNS.
+ #
+ # For exhaustive list of all options see samples/knot.full.conf
+ # in the source directory.
+ #
+
+ interfaces {
+ my_interface { address 127.0.0.1@53; }
+ second_int { address ::1; }
+ }
+
+ log {
+ syslog { any notice, warning, error; }
+ }
+
+ zones {
+ example.com {
+ file "/etc/knot/example.com";
+ }
+ }
+
+Now let's go step by step through this minimal configuration file:
+
+* The ``interfaces`` statement defines interfaces where Knot
+ DNS will listen for incoming connections. We have defined two
+ interfaces: one IPv4 called ``my_interface`` explicitly listening
+ on port 53 and second IPv6 called ``second_int`` also listening on
+ port 53, which is the default port for the DNS. See @ref{interfaces}.
+* The ``log`` statement defines the log facilities for Knot DNS.
+ In this example we told Knot DNS to send its log messages with the severities
+ ``debug``, ``warning`` and ``notice`` into the syslog.
+ If you omit this sections, all severities will printed to
+ either ``stdout`` or ``stderr``, and the severities
+ from the ``warning`` and more serious to syslog. You can find all
+ possible combinations in the @ref{log}.
+* The ``zones`` statement is probably the most important one,
+ because it defines the zones that Knot DNS will serve. In its most simple
+ form you can define a zone by its name and zone file.
+
+Slave configuration
+===================
+
+Knot DNS doesn't strictly differ between master and slave zones. The
+only requirement is to have ``xfr-in`` ``zones`` statement set for
+given zone, thus allowing both incoming XFR from that remote and using
+it as the zone master. If ``update-in`` is set and zone has a master,
+any accepted DNS UPDATE will be forwarded to master. Also note that
+you need to explicitly allow incoming NOTIFY, otherwise the daemon
+would reject them. Also, you can specify paths, relative to the
+storage directory. See @ref{zones} and @ref{storage}. If the zone
+file doesn't exist and ``xfr-in`` is set, it will be bootstrapped over
+AXFR.
+
+::
+
+ remotes {
+ master { address 127.0.0.1@@53; }
+ subnet1 { address 192.168.1.0/24; }
+ }
+
+ zones {
+ example.com {
+ file "example.com"; # relative to 'storage'
+ xfr-in master; # define 'master' for this zone
+ notify-in master; # also allow NOTIFY from 'master'
+ update-in subnet1; # accept UPDATE msgs from subnet1 and forward
+ # to master
+ }
+ }
+
+You can also use TSIG for access control. For this, you need to configure a TSIG key
+and assign it to a remote. Supported algorithms for TSIG key are:
+| ``hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, hmac-sha512``
+Key secret is written in a base64 encoded format. See @ref{keys}.
+
+::
+
+ keys {
+ key0 hmac-md5 "Wg=="; # keyname algorithm secret
+ }
+ remotes {
+ master { address 127.0.0.1@@53; key key0; }
+ }
+ zones {
+ example.com {
+ file "example.com"; # relative to 'storage'
+ xfr-in master; # define 'master' for this zone
+ notify-in master; # also allow NOTIFY from 'master'
+ }
+ }
+
+As of now it is not possible to associate multiple keys with a remote.
+
+Master configuration
+====================
+
+You can specify which remotes to allow for outgoing XFR and NOTIFY ``zones``.
+
+::
+
+ remotes {
+ slave { address 127.0.0.1@@53; }
+ any { address 0.0.0.0/0; }
+ subnet1 { address 192.168.1.0/8; }
+ subnet2 { address 192.168.2.0/8; }
+ }
+ zones {
+ example.com {
+ file "/var/zones/example.com";
+ xfr-out subnet1, subnet2; # allow outgoing transfers
+ notify-out slave;
+ update-in subnet1; # only allow DNS UPDATE from subnet1
+ }
+ }
+ @end example
+
+ You can also secure outgoing XFRs with TSIG.
+
+ @example
+ keys {
+ key0 hmac-md5 "Wg=="; # keyname algorithm secret
+ }
+ remotes {
+ any { address 0.0.0.0/0; key key0; }
+ }
+ zones {
+ example.com {
+ file "/var/zones/example.com";
+ xfr-out any; # uses 'any' remote secured with TSIG key 'key0'
+ }
+ }
+
+Configuring multiple interfaces
+===============================
+
+Knot DNS support binding to multiple available interfaces in the
+``interfaces`` section. You can also use the special addresses for
+"any address" like ``0.0.0.0`` or ``[::]``.
+
+::
+
+ interfaces {
+ if1 { address 192.168.1.2@@53; }
+ anyv6 { address [::]@@53; }
+ }
+
+Using DNS UPDATE
+================
+
+As noted in examples for master and slave, it is possible to accept
+DNS UPDATE messages. When the zone is configured as a slave and DNS
+UPDATE messages is accepted, server forwards the message to its
+primary master specified by ``xfr-in`` directive. When it receives the
+response from primary master, it forwards it back to the
+originator. This finishes the transaction.
+
+However, if the zone is configured as master (i.e. not having any
+``xfr-in`` directive), it accepts such an UPDATE and processes it.
+
+Remote control interface
+========================
+
+As of v1.3.0, it is possible to control running daemon using UNIX
+sockets, which is also preferred over internet sockets. You don't need
+any specific configuration, since it is enabled by default and the
+UNIX socket is placed in the rundir. To disable remote control
+completely, add an empty ``control`` section to the configuration
+like::
+
+ control { }
+
+However you can still use IPv4/IPv6 address, although with several
+shortcomings. You then can use ``allow`` for an ACL list similar to
+``xfr-in`` or ``xfr-out``, see that for syntax reference. The
+``listen-on`` has syntax equal to an interface specification, but the
+default port for remote control protocol is ``5533``. However keep in
+mind, that the transferred data isn't encrypted and could be
+susceptible to replay attack in a short timeframe.
+
+Example configuration::
+
+ control {
+ listen-on { address 127.0.0.1@@5533; }
+ }
+
+Enabling zone semantic checks
+=============================
+
+You can turn on more detailed semantic checks of zone file in this
+``zones`` statement (@pxref{zones}). Refer to @ref{zones List of zone
+semantic checks} to see which checks are enabled by default and which
+are optional.
+
+Creating IXFR differences from zone file changes
+================================================
+
+If Knot is being run as a master server, feature
+``ixfr-from-differences`` can be enabled to create IXFR differences
+from changes made to the master zone file. See @ref{Controlling
+running daemon} for more information. For more about ``zones``
+statement see @ref{zones}.
+
+Using Response Rate Limiting
+============================
+
+Response rate limiting (RRL) is a method to combat recent DNS
+reflection amplification attacks. These attacked rely on the fact
+that source address of a UDP query could be forged, and without a
+worldwide deployment of BCP38, such a forgery could not be detected.
+Attacker could then exploit DNS server responding to every query,
+potentially flooding the victim with a large unsolicited DNS
+responses.
+
+As of Knot DNS version 1.2.0, RRL is compiled in, but disabled by
+default. You can enable it with the @ref{rate-limit} option in the
+@ref{system} section. Setting to a value greater than ``0`` means
+that every flow is allowed N responses per second, (i.e. ``rate-limit
+50;`` means ``50`` responses per second). It is also possible to
+configure SLIP interval, which causes every Nth blocked response to be
+slipped as a truncated response. Not that some error responses cannot
+be truncated and are slipped as-is. For more information, refer to
+@ref{rate-limit-slip}. It is advisable to not set slip interval to a
+value larger than 1.
+
+Example configuration::
+
+ system {
+ rate-limit 200; # Each flow is allowed to 200 resp. per second
+ rate-limit-slip 1; # Every response is slipped (default)
+ }
+
+Automatic DNSSEC signing
+========================
+
+Knot DNS 1.4.0 is the first release to include automatic DNSSEC
+signing feature. Automatic DNSSEC signing is currently a technical
+preview and there are some limitations we will try to eliminate. The
+concept of key management and configuration is likely to change in the
+future without maintaining backward compatibility.
+
+Example configuration
+---------------------
+
+The example configuration enables automatic signing for all zones
+using @ref{dnssec-enable} option in the ``zones`` section, but the
+signing is explicitly disabled for zone ``example.dev`` using the same
+option directly in zone configuration. The location of directory with
+signing keys is set globally by option @ref{dnssec-keydir}.
+
+::
+
+ zones {
+ dnssec-enable on;
+ dnssec-keydir "/var/lib/knot/keys";
+
+ example.com {
+ file "example.com.zone";
+ }
+
+ example.dev {
+ file "example.dev.zone";
+ dnssec-enable off;
+ }
+ }
+
+Signing keys
+------------
+
+The signing keys can be generated using ISC ``dnssec-keygen`` tool
+only and there are some limitations:
+
+* Keys for all zones must be placed in one directory.
+* Algorithms based on RSA, DSA, and ECDSA are supported, support for
+ GOST algorithm is not finished yet.
+* Only key publication, activation, inactivation, and removal time
+ stamps are utilized. Other time stamps are ignored.
+* It is required, that both ``.private`` and ``.key`` files for each
+ key are available in the key directory in order to use the keys
+ (even for verification only).
+* There cannot be more than eight keys per zone. Keys which are not
+ published are not included in this number.
+
+Example how to generate NSEC3 capable zone signing key (ZSK) and key
+signing key (KSK) for zone ``example.com``::
+
+ $ cd /var/lib/knot/keys
+ $ dnssec-keygen -3 example.com
+ $ dnssec-keygen -3 -f KSK example.com
+
+Signing policy
+--------------
+
+Currently the signing policy is not configurable, except for signature
+lifetime.
+
+* Signature lifetime can be set in configuration globally for all
+ zones and for each zone in particular. @xref{signature-lifetime}. If
+ not set, the default value is 30 days.
+* Signature is refreshed 2 hours before expiration. The signature
+ lifetime must thus be set to more than 2 hours.
+
+Zone signing
+------------
+
+The signing process consists of the following steps:
+
+* Fixing ``NSEC`` or ``NSEC3`` records. This is determined by
+ ``NSEC3PARAM`` record presence in unsigned zone.
+* Updating ``DNSKEY`` records. This also means adding DNSKEY records
+ for any keys that are present in keydir, but missing in zone file.
+* Removing expired signatures, invalid signatures, signatures expiring
+ in a short time, and signatures with unknown key.
+* Creating any missing signatures. ``DNSKEY`` records are signed by
+ both ZSK and KSK keys, other records are signed only by ZSK keys.
+* SOA record is updated and resigned if any changes were performed.
+
+The zone signing is performed when the zone is loaded into server, on
+zone reload, before any signature is expiring, and after DDNS
+update. The signing can be also forced using ``signzone`` command
+issued by ``knotc``, in this case all signatures are recreated. After
+each zone signing, a new signing event is planned. User can view the
+time of this event by using the ``knotc zonestatus`` command.
+
+Query modules
+=============
+
+Knot DNS supports configurable query modules that can alter the way
+queries are processed. The concept is quite simple - each query
+requires a finite number of steps to be resolved. We call this set of
+steps a query plan, an abstraction that groups these steps into
+several stages.
+
+* Before query processing
+* Answer, Authority, Additional records packet sections processing
+* After query processing
+
+For example, processing an Internet zone query needs to find an
+answer. Then based on the previous state, it may also append an
+authority SOA or provide additional records. Each of these actions
+represents a 'processing step'. Now if a query module is loaded for a
+zone, it is provided with an implicit query plan, and it is allowed to
+extend it or even change it altogether.
+
+*Note:* Programmable interface is described in the ``query_module.h``,
+it will not be discussed here.
+
+The general syntax for importing a query module is described in the
+@ref{query_module} configuration reference. Basically, each module is
+described by a name and a configuration string. Below is a list of
+modules and configuration string reference.
+
+``synth_record`` - Automatic forward/reverse records
+----------------------------------------------------
+
+This module is able to synthetise either forward or reverse records for given prefix and subnet.
+The module configuration string looks like this: @code{(forward|reverse) <prefix> <ttl> <address>/<netblock>}.
+
+Records are synthetised only if the query can't be satisfied from the zone. Both IPv4 and IPv6 are supported.
+@emph{Note: 'prefix' doesn't allow dots, address parts in the synthetic names are separated with a dash.}
+
+Here are a few examples:
+@emph{Note: long names are snipped for readability.}
+
+@subsubsection Automatic forward records
+
+@code{synth_record "forward dynamic- 400 2620:0:b61::/52"} on @code{example.} zone will result in following
+answer::
+
+ $ kdig AAAA dynamic-2620-0000-0b61-0100-0000-0000-0000-0000.example.
+ ...
+ ;; QUESTION SECTION:
+ ;; dynamic-2620-0000-0b61-0100-0000-0000-0000-0000.example. 0 IN AAAA
+
+ ;; ANSWER SECTION:
+ dynamic-2620-0000-0b61-0100... 400 IN AAAA 2620:0:b61:100::
+ @end example
+
+ You can also have CNAME aliases to the dynamic records, which are going to be further resoluted.
+ @example
+ $ kdig AAAA hostalias.example.
+ ...
+ ;; QUESTION SECTION:
+ ;hostalias.example. 0 IN AAAA
+
+ ;; ANSWER SECTION:
+ hostalias.example. 3600 IN CNAME dynamic-2620-0000-0b61-0100...
+ dynamic-2620-0000-0b61-0100... 400 IN AAAA 2620:0:b61:100::
+
+Automatic reverse records
+-------------------------
+
+Module can be configured to synthetise reverse records as well. With
+the ``synth_record "reverse dynamic- example. 400 2620:0:b61::/52"``
+string in the ``1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa.`` zone
+configuration::
+
+ $ kdig PTR 1.0.0...1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa.
+ ...
+ ;; QUESTION SECTION:
+ ;; 1.0.0...1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa. 0 IN PTR
+
+ ;; ANSWER SECTION:
+ ... 400 IN PTR dynamic-2620-0000-0b61-0000-0000-0000-0000-0001.example.
+
+Here's a full configuration of the aforementioned zones. Note that the zone files have to exist.
+
+::
+
+ example. {
+ query_module {
+ synth_record "forward dynamic- 400 2620:0:b61::/52";
+ synth_record "forward dynamic- 400 192.168.1.0/25";
+ }
+ }
+ 1.168.192.in-addr.arpa {
+ query_module {
+ synth_record "reverse dynamic- example. 400 192.168.1.0/25";
+ }
+ }
+ 1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa {
+ query_module {
+ synth_record "reverse dynamic- example. 400 2620:0:b61::/52";
+ }
+ }
+
+Limitations
+^^^^^^^^^^^
+
+* As of now, there is no authenticated denial of nonexistence (neither
+ NSEC or NSEC3 is supported) nor DNSSEC signed records. However,
+ since the module is hooked in the query processing plan, it will be
+ possible to do online signing in the future.
diff --git a/doc/configuration.texi b/doc/configuration.texi
deleted file mode 100644
index daf73493fd6a178d300e725f0d672465f1a2c02b..0000000000000000000000000000000000000000
--- a/doc/configuration.texi
+++ /dev/null
@@ -1,405 +0,0 @@
-@node Knot DNS Configuration, Running Knot DNS, Knot DNS Installation, Top
-@chapter Knot DNS Configuration
-
-In this chapter we provide suggested configurations and explain the meaning of individual configuration options.
-
-@menu
-* Minimal configuration::
-* Slave configuration::
-* Master configuration::
-* Configuring multiple interfaces::
-* Using DNS UPDATE::
-* Remote control interface::
-* Enabling zone semantic checks::
-* Creating IXFR differences from zone file changes::
-* Using Response Rate Limiting::
-* Automatic DNSSEC signing::
-* Query modules::
-@end menu
-
-@node Minimal configuration
-@section Minimal configuration
-
-The following configuration presents a minimal configuration
-file which can be used as a base for your Knot DNS setup.
-
-@example
-
-# This is a sample of a minimal configuration file for Knot DNS.
-#
-# For exhaustive list of all options see samples/knot.full.conf
-# in the source directory.
-#
-
-interfaces @{
- my_interface @{ address 127.0.0.1@@53; @}
- second_int @{ address ::1; @}
-@}
-
-log @{
- syslog @{ any notice, warning, error; @}
-@}
-
-zones @{
- example.com @{
- file "/etc/knot/example.com";
- @}
-@}
-
-@end example
-
-@page
-Now let's go step by step through this minimal configuration file:
-
-@enumerate
-
-@item
-The @code{interfaces} statement defines interfaces where Knot
-DNS will listen for incoming connections. We have defined two
-interfaces: one IPv4 called @kbd{my_interface} explicitly listening
-on port 53 and second IPv6 called @kbd{second_int} also listening on
-port 53, which is the default port for the DNS. See @ref{interfaces}.
-
-@item
-The @code{log} statement defines the log facilities for Knot DNS.
-In this example we told Knot DNS to send its log messages with the severities
-@code{debug}, @code{warning} and @code{notice} into the syslog.
-If you omit this sections, all severities will printed to
-either @code{stdout} or @code{stderr}, and the severities
-from the @code{warning} and more serious to syslog. You can find all
-possible combinations in the @ref{log}.
-
-@item
-The @code{zones} statement is probably the most important one,
-because it defines the zones that Knot DNS will serve. In its most simple
-form you can define a zone by its name and zone file.
-@end enumerate
-
-@page
-@node Slave configuration
-@section Slave configuration
-
-Knot DNS doesn't strictly differ between master and slave zones.
-The only requirement is to have @code{xfr-in} @code{zones} statement set for given zone,
-thus allowing both incoming XFR from that remote and using it as the
-zone master. If @code{update-in} is set and zone has a master,
-any accepted DNS UPDATE will be forwarded to master.
-Also note that you need to explicitly allow incoming NOTIFY, otherwise
-the daemon would reject them.
-Also, you can specify paths, relative to the storage directory.
-See @ref{zones} and @ref{storage}.
-If the zone file doesn't exist and @code{xfr-in} is set, it will be bootstrapped over AXFR.
-
-@example
-remotes @{
- master @{ address 127.0.0.1@@53; @}
- subnet1 @{ address 192.168.1.0/24; @}
-@}
-zones @{
- example.com @{
- file "example.com"; # relative to 'storage'
- xfr-in master; # define 'master' for this zone
- notify-in master; # also allow NOTIFY from 'master'
- update-in subnet1; # accept UPDATE msgs from subnet1 and forward
- # to master
- @}
-@}
-@end example
-
-You can also use TSIG for access control. For this, you need to configure a TSIG key
-and assign it to a remote.
-Supported algorithms for TSIG key are:@*
-@code{hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, hmac-sha512}
-@*
-Key secret is written in a base64 encoded format. See @ref{keys}.
-
-@example
-keys @{
- key0 hmac-md5 "Wg=="; # keyname algorithm secret
-@}
-remotes @{
- master @{ address 127.0.0.1@@53; key key0; @}
-@}
-zones @{
- example.com @{
- file "example.com"; # relative to 'storage'
- xfr-in master; # define 'master' for this zone
- notify-in master; # also allow NOTIFY from 'master'
- @}
-@}
-@end example
-
-As of now it is not possible to associate multiple keys with a remote.
-
-@page
-@node Master configuration
-@section Master configuration
-
-You can specify which remotes to allow for outgoing XFR and NOTIFY @code{zones}.
-
-@example
-remotes @{
- slave @{ address 127.0.0.1@@53; @}
- any @{ address 0.0.0.0/0; @}
- subnet1 @{ address 192.168.1.0/8; @}
- subnet2 @{ address 192.168.2.0/8; @}
-@}
-zones @{
- example.com @{
- file "/var/zones/example.com";
- xfr-out subnet1, subnet2; # allow outgoing transfers
- notify-out slave;
- update-in subnet1; # only allow DNS UPDATE from subnet1
- @}
-@}
-@end example
-
-You can also secure outgoing XFRs with TSIG.
-
-@example
-keys @{
- key0 hmac-md5 "Wg=="; # keyname algorithm secret
-@}
-remotes @{
- any @{ address 0.0.0.0/0; key key0; @}
-@}
-zones @{
- example.com @{
- file "/var/zones/example.com";
- xfr-out any; # uses 'any' remote secured with TSIG key 'key0'
- @}
-@}
-@end example
-
-@node Configuring multiple interfaces
-@section Configuring multiple interfaces
-
-Knot DNS support binding to multiple available interfaces in the @code{interfaces} section.
-@*You can also use the special addresses for "any address" like @code{0.0.0.0} or @code{[::]}.
-
-@example
-interfaces @{
- if1 @{ address 192.168.1.2@@53; @}
- anyv6 @{ address [::]@@53; @}
-@}
-@end example
-
-@node Using DNS UPDATE
-@section Using DNS UPDATE
-
-As noted in examples for master and slave, it is possible to accept DNS UPDATE messages.
-When the zone is configured as a slave and DNS UPDATE messages is accepted, server forwards the
-message to its primary master specified by @code{xfr-in} directive. When it receives
-the response from primary master, it forwards it back to the originator. This finishes the transaction.
-
-However, if the zone is configured as master (i.e. not having any @code{xfr-in} directive), it accepts
-such an UPDATE and processes it.
-
-@node Remote control interface
-@section Remote control interface
-
-As of v1.3.0, it is possible to control running daemon using UNIX sockets,
-which is also preferred over internet sockets. You don't need any specific configuration,
-since it is enabled by default and the UNIX socket is placed in the rundir.
-To disable remote control completely, add an empty @code{control} section to the
-configuration like:
-
-@example
-control @{ @}
-@end example
-
-However you can still use IPv4/IPv6 address, although with several shortcomings.
-You then can use @code{allow} for an ACL list similar to @code{xfr-in} or @code{xfr-out},
-see that for syntax reference. The @code{listen-on} has syntax equal to an interface specification,
-but the default port for remote control protocol is @code{5533}.
-However keep in mind, that the transferred data isn't encrypted and could be
-susceptible to replay attack in a short timeframe.
-
-Example configuration:
-@example
-control @{
- listen-on @{ address 127.0.0.1@@5533; @}
-@}
-@end example
-
-@node Enabling zone semantic checks
-@section Enabling zone semantic checks
-You can turn on more detailed semantic
-checks of zone file in this @code{zones} statement (@pxref{zones}). Refer to @ref{zones List of zone semantic checks} to see
-which checks are enabled by default and which are optional.
-
-@node Creating IXFR differences from zone file changes
-@section Creating IXFR differences from zone file changes
-If Knot is being run as a master server, feature @code{ixfr-from-differences}
-can be enabled to create IXFR differences from changes made to the master zone file.
-See @ref{Controlling running daemon} for more information. For more about @code{zones} statement see @ref{zones}.
-
-@node Using Response Rate Limiting
-@section Using Response Rate Limiting
-
-Response rate limiting (RRL) is a method to combat recent DNS reflection amplification attacks.
-These attacked rely on the fact that source address of a UDP query could be forged,
-and without a worldwide deployment of BCP38, such a forgery could not be detected.
-Attacker could then exploit DNS server responding to every query, potentially flooding the
-victim with a large unsolicited DNS responses.
-
-As of Knot DNS version 1.2.0, RRL is compiled in, but disabled by default.
-You can enable it with the @ref{rate-limit} option in the @ref{system} section.
-Setting to a value greater than @code{0} means that every flow is allowed N responses per second,
-(i.e. @code{rate-limit 50;} means @code{50} responses per second).
-It is also possible to configure SLIP interval, which causes every Nth blocked response to be slipped
-as a truncated response. Not that some error responses cannot be truncated and are slipped as-is.
-For more information, refer to @ref{rate-limit-slip}.
-It is advisable to not set slip interval to a value larger than 1.
-
-Example configuration:
-@example
-system @{
- rate-limit 200; # Each flow is allowed to 200 resp. per second
- rate-limit-slip 1; # Every response is slipped (default)
-@}
-@end example
-
-@node Automatic DNSSEC signing
-@section Automatic DNSSEC signing
-
-Knot DNS 1.4 is the first release to include automatic DNSSEC signing feature.
-Automatic DNSSEC signing is currently a technical preview and there are some
-limitations we will try to eliminate. The concept of key management and
-configuration is likely to change in the future without maintaining backward
-compatibility.
-
-@subsection Example configuration
-
-The example configuration enables automatic signing for all zones using
-@ref{dnssec-enable} option in the @code{zones} section, but the signing is
-explicitly disabled for zone @code{example.dev} using the same option directly
-in zone configuration. The location of directory with signing keys is set
-globally by option @ref{dnssec-keydir}.
-
-@sp 1
-
-@example
-zones @{
- dnssec-enable on;
- dnssec-keydir "/var/lib/knot/keys";
-
- example.com @{
- file "example.com.zone";
- @}
-
- example.dev @{
- file "example.dev.zone";
- dnssec-enable off;
- @}
-@}
-@end example
-
-@subsection Signing keys
-
-The signing keys can be generated using ISC @code{dnssec-keygen} tool only
-and there are some limitations:
-
-@itemize @bullet
-@item
-Keys for all zones must be placed in one directory.
-
-@item
-Algorithms based on RSA, DSA, and ECDSA are supported, support for GOST
-algorithm is not finished yet.
-
-@item
-Only key publication, activation, inactivation, and removal time stamps
-are utilized. Other time stamps are ignored.
-
-@item
-It is required, that both @code{.private} and @code{.key} files for each key
-are available in the key directory in order to use the keys (even for
-verification only).
-
-@item
-There cannot be more than eight keys per zone. Keys which are not published
-are not included in this number.
-
-@end itemize
-
-@sp 1
-
-Example how to generate NSEC3 capable zone signing key (ZSK) and key signing
-key (KSK) for zone @code{example.com}:
-
-@sp 1
-@example
-$ cd /var/lib/knot/keys
-$ dnssec-keygen -3 example.com
-$ dnssec-keygen -3 -f KSK example.com
-@end example
-
-@subsection Signing policy
-
-Currently the signing policy is not configurable, except for signature lifetime.
-
-@itemize @bullet
-@item Signature lifetime can be set in configuration globally for all zones and for each zone in particular. @xref{signature-lifetime}. If not set, the default value is 30 days.
-@item Signature is refreshed 2 hours before expiration. The signature lifetime must thus be set to more than 2 hours.
-@end itemize
-
-@subsection Zone signing
-
-The signing process consists of the following steps:
-
-@itemize @bullet
-@item
-Fixing @code{NSEC} or @code{NSEC3} records. This is determined by
-@code{NSEC3PARAM} record presence in unsigned zone.
-
-@item
-Updating @code{DNSKEY} records. This also means adding DNSKEY records for any keys that are present in keydir, but missing in zone file.
-
-@item
-Removing expired signatures, invalid signatures, signatures expiring in a short
-time, and signatures with unknown key.
-
-@item
-Creating any missing signatures. @code{DNSKEY} records are signed by both ZSK
-and KSK keys, other records are signed only by ZSK keys.
-
-@item
-SOA record is updated and resigned if any changes were performed.
-
-@end itemize
-
-@sp 1
-
-The zone signing is performed when the zone is loaded into server, on zone
-reload, before any signature is expiring, and after DDNS update. The signing
-can be also forced using @code{signzone} command issued by @code{knotc}, in
-this case all signatures are recreated. After each zone signing, a new signing
-event is planned. User can view the time of this event by using the
-@code{knotc zonestatus} command.
-
-@node Query modules
-@section Query modules
-
-Knot DNS supports configurable query modules that can alter the way queries are processed.
-The concept is quite simple - each query requires a finite number of steps to be resolved.
-We call this set of steps a query plan, an abstraction that groups these steps into several stages.
-
-@itemize @bullet
-@item Before query processing
-@item Answer, Authority, Additional records packet sections processing
-@item After query processing
-@end itemize
-
-For example, processing an Internet zone query needs to find an answer. Then
-based on the previous state, it may also append an authority SOA or provide additional records.
-Each of these actions represents a 'processing step'.
-Now if a query module is loaded for a zone, it is provided with an implicit query plan, and
-it is allowed to extend it or even change it altogether.
-@emph{Note: Programmable interface is described in the @code{query_module.h}, it will not be discussed here.}
-
-The general syntax for importing a query module is described in the @ref{query_module} configuration reference.
-Basically, each module is described by a name and a configuration string.
-Below is a list of modules and configuration string reference.
-
-@include synth_record.texi
diff --git a/doc/installation.rst b/doc/installation.rst
index e86d0f1f5a7012da085c9592c1a28765b99700a8..db9b3ab9cc9813adff64896f7d7ccd9c0f840382 100644
--- a/doc/installation.rst
+++ b/doc/installation.rst
@@ -1,10 +1,13 @@
+.. _Knot DNS Installation:
+
*********************
Knot DNS Installation
*********************
-Required build environment
-====================
+.. _Required build environment:
+Required build environment
+==========================
GCC at least 4.1 is strictly required for atomic built-ins, but 4.2 or
newer is recommended. Another requirement is ``_GNU_SOURCE`` support,
@@ -19,6 +22,8 @@ Knot DNS build system relies on these standard tools:
* flex >= 2.5.31
* bison >= 2.3
+.. _Required libraries:
+
Required libraries
==================
@@ -37,6 +42,8 @@ You can probably find OpenSSL and zlib libraries already included in
your system or distribution. If not, zlib resides at http://zlib.net,
and OpenSSL can be found at http://www.openssl.org.
+.. _Userspace RCU:
+
Userspace RCU
-------------
@@ -56,6 +63,8 @@ It is crucial especially on non-Linux systems, as we got some compatibility
patches accepted to later releases of Userspace RCU.
OpenBSD, NetBSD and OS X platforms are supported from version 0.7.0.
+.. _Installation from the source:
+
Installation from the sources
=============================
@@ -65,6 +74,8 @@ Alternatively, you can fetch the sources from git repository `<git://git.nic.cz/
After unpacking the sources, the compilation and installation is a
quite straightforward process using autotools.
+.. _Configuring and generating Makefiles:
+
Configuring and generating Makefiles
------------------------------------
@@ -98,7 +109,7 @@ For example::
$ ./configure --enable-debug=server,packet --enable-debuglevel=brief
$ ./configure --enable-debug=server,packet --enable-debuglevel=verbose
-For more detailed information, see @ref{Debug messages}.
+For more detailed information, see @ref{Debug messages}. ##TODO
In most simple case you can just run configure without any options::
@@ -146,8 +157,8 @@ Knot DNS is already available from Debian wheezy upwards. In addition
to the official packages we also provide custom repository, which can
be used by adding::
- deb @url{http://deb.knot-dns.cz/debian/} <codename> main
- deb-src @url{http://deb.knot-dns.cz/debian/} <codename> main
+ deb http://deb.knot-dns.cz/debian/ <codename> main
+ deb-src http://deb.knot-dns.cz/debian/ <codename> main
to your ``/etc/apt/sources.list`` or into separate file in
``/etc/apt/sources.list.d/``.
@@ -194,9 +205,9 @@ Installing Knot DNS packages on Fedora
--------------------------------------
The RPM packages for ``Knot DNS`` are available in official Fedora
-repositories since Fedora@tie{}18 (Spherical Cow). Look for
-``knot`` package in your package manager. To install the package
-using Yum, run a following command as the root user::
+repositories since Fedora 18 (Spherical Cow). Look for ``knot``
+package in your package manager. To install the package using Yum, run
+a following command as the root user::
# yum install knot
@@ -234,9 +245,13 @@ Knot DNS is in ports tree under ``dns/knot``::
Installing Knot DNS on Arch Linux
---------------------------------
-TODO
+Knot DNS is available official package repository (AUR)::
+
+ https://aur.archlinux.org/packages/knot/
Installing Knot DNS on Gentoo Linux
-----------------------------------
-TODO
+Knot DNS is available from Gentoo package repository::
+
+ https://packages.gentoo.org/package/net-dns/knot
diff --git a/doc/installation.texi b/doc/installation.texi
deleted file mode 100644
index e89db1daa54145559a3f58be0b08c9a97863361e..0000000000000000000000000000000000000000
--- a/doc/installation.texi
+++ /dev/null
@@ -1,318 +0,0 @@
-@node Knot DNS Installation, Knot DNS Configuration, Knot DNS Resource Requirements, Top
-@chapter Knot DNS Installation
-
-@menu
-* Required build environment::
-* Required libraries::
-* Installation from the sources::
-* Installation from packages::
-@end menu
-
-@node Required build environment
-@section Required build environment
-
-GCC at least 4.1 is strictly required for atomic built-ins, but 4.2 or newer is recommended.
-Another requirement is @code{_GNU_SOURCE} support, otherwise it adapts to the compiler available features.
-Clang should work, but it is not officially supported.
-
-Knot DNS build system relies on these standard tools:
-@itemize
-@item
-make
-@item
-libtool
-@item
-autoconf >= 2.65
-@item
-flex >= 2.5.31
-@item
-bison >= 2.3
-@end itemize
-
-@node Required libraries
-@section Required libraries
-
-Knot DNS requires few libraries to be compiled:
-
-@itemize
-
-@item
-OpenSSL, at least 0.9.8
-@item
-zlib
-@item
-Userspace RCU, at least 0.5.4
-@item
-libcap-ng, at least 0.6.4 (optional library)
-@end itemize
-
-If libcap-ng library is available, Knot DNS will take advantage of
-the POSIX 1003.1e capabilites(7) by sandboxing the exposed threads.
-Most rights are stripped from the exposed threads for security reasons.
-
-You can probably find OpenSSL and zlib libraries already included in
-your system or distribution. If not, zlib resides at
-@url{http://zlib.net}, and OpenSSL can be found at
-@url{http://www.openssl.org}.
-
-@menu
-* Userspace RCU::
-@end menu
-
-@node Userspace RCU
-@subsection Userspace RCU
-
-liburcu is a LGPLv2.1 userspace RCU (read-copy-update)
-library. This data synchronization library provides read-side
-access which scales linearly with the number of cores. It does
-so by allowing multiple copies of a given data structure to
-live at the same time, and by monitoring the data structure
-accesses to detect grace periods after which memory reclamation
-is possible. (@url{http://lttng.org/urcu,Userspace RCU})
-
-Binary packages for Debian can be found under @code{liburcu1} for the
-library and @code{liburcu-dev} for development files.
-
-Minimum supported version of Userspace RCU library is 0.5.4,
-but we recommend using latest available version.
-It is crucial especially on non-Linux systems, as we got some compatibility
-patches accepted to later releases of Userspace RCU.
-OpenBSD, NetBSD and OS X platforms are supported from version 0.7.0.
-
-@node Installation from the sources
-@section Installation from the sources
-
-You can find the source files for the latest release on @url{www.knot-dns.cz}.
-Alternatively, you can fetch the sources from git repository @url{git://git.nic.cz/knot-dns.git}
-
-After unpacking the sources, the compilation and installation is
-a quite straightforward process using autotools.
-
-@menu
-* Configuring and generating Makefiles::
-* Compilation::
-* Installation::
-@end menu
-
-@node Configuring and generating Makefiles
-@subsection Configuring and generating Makefiles
-
-If you want to compile from Git sources, you need to bootstrap the
-@command{./configure} file first.
-
-@example
-$ autoreconf -i -f
-@end example
-
-For all available configure options run:
-
-@example
-$ ./configure --help
-@end example
-
-If you have trouble with unknown syscalls under valgrind, disable recvmmsg by
-adding a parameter @command{--enable-recvmmsg=no} to configure.
-
-Knot DNS has also support for link time optimizations.
-You can enable it by the configure parameter @command{./configure --enable-lto=yes}.
-It is however disabled by default as it is known to be broken in some compiler
-versions and may result in an unexpected behaviour.
-
-If you want to add debug messages, there are two steps to do that.
-First you have to enable modules you are interested in.
-Available are: @code{server, zones, xfr, packet, dname, rr, ns, hash, compiler}.
-You can combine multiple modules as a comma-separated list.
-Then you can narrow the verbosity of the debugging message by specifying the
-verbosity as @code{brief, verbose, details}.
-
-For example:
-@example
-$ ./configure --enable-debug=server,packet --enable-debuglevel=brief
-$ ./configure --enable-debug=server,packet --enable-debuglevel=verbose
-@end example
-
-For more detailed information, see @ref{Debug messages}.
-
-In most simple case you can just run configure without any options.
-
-@example
-$ ./configure
-@end example
-
-@node Compilation
-@subsection Compilation
-
-After running @command{./configure} you can compile
-Knot DNS by running @command{make} command, which will produce binaries
-and other related files.
-
-@example
-$ make
-@end example
-
-Knot DNS build process is safe to parallelize
-using @command{make -j N}, where N is number of
-concurrent processes. Using this option can increase speed of
-the compilation.
-
-For example to use maximum 8 concurrent processes you would use:
-
-@example
-$ make -j 8
-@end example
-
-@node Installation
-@subsection Installation
-
-When you have finished building the Knot DNS, it's time to
-install the binaries and configuration files into the
-operation system hierarchy. You can do so by
-executing @command{make install} command. When installing as a
-non-root user you might have to gain elevated privileges by
-switching to root user, e.g. @command{sudo make install}
-or @command{su -c 'make install'}.
-
-@example
-$ make install
-@end example
-
-@node Installation from packages
-@section Installation from packages
-
-In addition to providing the packages in .DEB and .RPM format,
-the Knot DNS might already be available in your favourite
-distribution, or in a ports tree.
-
-@menu
-* Installing Knot DNS packages on Debian::
-* Installing Knot DNS packages on Ubuntu::
-* Installing Knot DNS packages on Fedora::
-* Installing Knot DNS from ports on FreeBSD::
-@end menu
-
-@node Installing Knot DNS packages on Debian
-@subsection Installing Knot DNS packages on Debian
-
-Knot DNS is already available from Debian wheezy upwards. In
-addition to the official packages we also provide custom
-repository, which can be used by adding:
-
-@example
-deb @url{http://deb.knot-dns.cz/debian/} <codename> main
-deb-src @url{http://deb.knot-dns.cz/debian/} <codename> main
-@end example
-
-@noindent
-to your @file{/etc/apt/sources.list} or into separate file in
-@file{/etc/apt/sources.list.d/}.
-
-As an example, for Debian squeeze (current stable) the Knot
-DNS packages can be added by executing following command as
-the root user.
-
-@example
-
-$ cat >/etc/apt/sources.list.d/knot.list <<EOF
-deb http://deb.knot-dns.cz/debian/ <codename> main
-deb-src http://deb.knot-dns.cz/debian/ <codename> main
-EOF
-$ apt-get update
-$ apt-get install knot
-
-@end example
-
-@node Installing Knot DNS packages on Ubuntu
-@subsection Installing Knot DNS packages on Ubuntu
-
-Prepackaged version of the Knot DNS can be found in Ubuntu
-from version 12.10 (Quantal Quetzal). In addition to the
-package included in the main archive, we provide Personal
-Package Archive (PPA) as an option to upgrade to last stable
-version of the Knot DNS or to install it on older versions of
-Ubuntu Linux.
-
-We typically provide packages for all supported versions of Ubuntu
-Linux including 5 year support for
-@url{https://wiki.ubuntu.com/LTS,LTS} versions of Ubuntu Linux. At
-the time of writing this manual this includes Ubuntu 10.04 LTS, 11.04,
-11.10 and 12.04 LTS.
-
-@menu
-* Adding official PPA repository for Knot DNS::
-@end menu
-
-@node Adding official PPA repository for Knot DNS
-@subsubsection Adding official PPA repository for Knot DNS
-
-To start installing and using software from a Personal
-Package Archive, you first need to tell Ubuntu where to find
-the PPA.
-
-@example
-
-$ sudo add-apt-repository ppa:cz.nic-labs/knot-dns
-$ sudo apt-get update
-$ sudo apt-get install knot
-
-@end example
-
-@noindent
-Running this sequence of commands will ensure that you will
-install Knot DNS on your system and keep it up-to-date
-in the future, when new versions are released.
-
-@page
-@node Installing Knot DNS packages on Fedora
-@subsection Installing Knot DNS packages on Fedora
-
-The RPM packages for @code{Knot DNS} are available in official Fedora
-repositories since Fedora@tie{}18 (Spherical Cow). Look for @code{knot}
-package in your package manager. To install the package using Yum, run
-a following command as the root user:
-
-@example
-
-# yum install knot
-
-@end example
-
-Using official distribution repository is highly recommended, however you may
-want to run @code{Knot DNS} on older releases of Fedora. In this case you can
-set up an unofficial repository by creating @file{/etc/yum.repos.d/knot.conf}
-file with the following content:
-
-@example
-
-[knot]
-name=Network.CZ Repository
-baseurl=ftp://repo.network.cz/pub/redhat/
-enabled=1
-gpgcheck=0
-gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-network.cz
-
-@end example
-
-After performing this action, you can install @code{knot} package the same way
-as described above. Please note that the unofficial repository contains only
-builds for i686 and x86_64 architecture.
-
-When upgrading to Fedora@tie{}18 or higher, backup the configuration and
-switch to the latest package provided in the official repository by running the
-following command as the root user:
-
-@example
-
-# yum distro-sync knot
-
-@end example
-
-
-@node Installing Knot DNS from ports on FreeBSD
-@subsection Installing Knot DNS from ports on FreeBSD
-
-Knot DNS is in ports tree under @code{dns/knot}.
-
-@example
-$ cd /usr/ports/dns/knot
-$ sudo make install
-@end example
diff --git a/doc/introduction.texi b/doc/introduction.texi
deleted file mode 100644
index 96e53cb73d20caed1c1fa6f4c34a6a79bec5010c..0000000000000000000000000000000000000000
--- a/doc/introduction.texi
+++ /dev/null
@@ -1,68 +0,0 @@
-@node Introduction, Knot DNS Resource Requirements, Top, Top
-@chapter Introduction
-
-The reader of this document is assumed to know the principles of
-Domain Name System.
-
-@menu
-* What is Knot DNS::
-* Knot DNS features::
-* Scope of this document::
-@end menu
-
-@node What is Knot DNS
-@section What is Knot DNS
-
-Knot DNS is a high-performance open source DNS server. It
-implements only authoritative domain name service. Knot DNS
-is best suited for use on TLD domains but can reliably serve
-any other zones as well.
-
-Knot DNS benefits from its multi-threaded and mostly lock-free
-implementation which allows it to scale well on SMP systems and
-operate non-stop even when adding or removing zones.
-
-@node Knot DNS features
-@section Knot DNS features
-
-Knot DNS supports the following DNS features:
-
-@itemize
-@item TCP/UDP protocols
-@item AXFR, IXFR - master, slave
-@item TSIG
-@item EDNS0
-@item DNSSEC, including NSEC3
-@item NSID
-@item Unknown RR types
-@end itemize
-
-Server features:
-
-@itemize
-@item Adding/removing zones on-the-fly
-@item Reconfiguring server instance on-the-fly
-@item IPv4 / IPv6 support
-@item Semantic checks of zones
-@end itemize
-
-For more info and downloads see
-@url{http://www.knot-dns.cz, www.knot-dns.cz}.
-
-Git repository:
-@url{git://git.nic.cz/knot-dns.git, git://git.nic.cz/knot-dns.git}
-
-Git repository browser:
-@url{https://gitlab.labs.nic.cz/knot/tree/master, gitlab.labs.nic.cz/knot/tree/master}
-
-Knot DNS issue tracker:
-@url{https://gitlab.labs.nic.cz/knot/issues, gitlab.labs.nic.cz/knot/issues}
-
-Knot DNS users mailing list:
-@url{mailto:knot-dns-users@@lists.nic.cz, knot-dns-users@@lists.nic.cz}
-
-@node Scope of this document
-@section Scope of this document
-
-This document covers the basic information on installing,
-configuring and troubleshooting the Knot DNS server.
diff --git a/doc/migration.rst b/doc/migration.rst
index d794ed5de091a7edeff0f298ed50381f6796d3b8..4a665532c28295fca5fc83dc82ae8de205a6fe02 100644
--- a/doc/migration.rst
+++ b/doc/migration.rst
@@ -1,5 +1,54 @@
+.. _Migration from other DNS servers:
+
********************************
Migration from other DNS servers
********************************
-TODO
+.. _Knot DNS for BIND users:
+
+Knot DNS for BIND users
+=======================
+
+.. _Automatic DNSSEC signing:
+
+Automatic DNSSEC signing
+------------------------
+
+Migrating automatically signed zones from Bind to Knot DNS is very
+easy due to the fact that Knot DNS is able to use DNSSEC keys
+generated by Bind.
+
+1. To obtain current content of the zone which is being migrated,
+ request Bind to flush the zone into the zone file: ``rndc flush
+ example.com``.
+
+ Note: If dynamic updates (DDNS) are enabled for the given zone, you
+ might need to freeze the zone before flushing it. That can be done
+ similarly: ``rndc freeze example.com``
+
+2. Copy the fresh zone file into the zones storage directory of Knot
+ DNS. It's default location is ``/var/lib/knot``.
+
+3. We recommend to store DNSSEC keys for each zone in a separate
+ directory. For this purpose, create a directory
+ ``example.com.keys`` in zones storage directory. Then copy all
+ DNSSEC keys (``*.key`` and ``*.private``) from Bind key directory
+ (configured as ``key-directory``) into the newly created one.
+
+4. Add the zone into the Knot DNS configuration file. Zone
+ configuration should contain at least specification of the zone
+ file (option ``file``), key directory (option ``dnssec-keydir``),
+ and enable automatic DNSSEC signing (option ``dnssec-enable``).
+
+ You can follow this example::
+
+ zones {
+ storage "/var/lib/knot";
+ example.com {
+ dnssec-enable on;
+ dnssec-keydir "example.com.keys";
+ file "example.com.db";
+ }
+ }
+
+5. Start Knot DNS and check the log files to make sure that everything went right.
diff --git a/doc/migration.texi b/doc/migration.texi
deleted file mode 100644
index a0b0534a2daaca6ee6dff8eb0019007bb9cd906c..0000000000000000000000000000000000000000
--- a/doc/migration.texi
+++ /dev/null
@@ -1,81 +0,0 @@
-@node Migration from other DNS servers, , Knot DNS Configuration Reference, Top
-@appendix Migration from other DNS servers
-
-@menu
-* Knot DNS for BIND users::
-@c * Knot DNS for NSD users::
-@c * Knot DNS for PowerDNS users::
-@c * Knot DNS for djbdns users::
-@end menu
-
-@node Knot DNS for BIND users
-@appendixsec Knot DNS for BIND users
-
-@subsection Automatic DNSSEC signing
-
-Migrating automatically signed zones from Bind to Knot DNS is very easy due to
-the fact that Knot DNS is able to use DNSSEC keys generated by Bind.
-
-@enumerate
-
-@item
-To obtain current content of the zone which is being migrated, request Bind
-to flush the zone into the zone file: @code{rndc flush example.com}
-
-Note: If dynamic updates (DDNS) are enabled for the given zone, you might need to
-freeze the zone before flushing it. That can be done similarly:
-@code{rndc freeze example.com}
-
-@item
-Copy the fresh zone file into the zones storage directory of Knot DNS. It's
-default location is @code{/var/lib/knot}.
-
-@item
-We recommend to store DNSSEC keys for each zone in a separate directory. For
-this purpose, create a directory @code{example.com.keys} in zones storage
-directory. Then copy all DNSSEC keys (@code{*.key} and @code{*.private}) from
-Bind key directory (configured as @code{key-directory}) into the newly
-created one.
-
-@item
-Add the zone into the Knot DNS configuration file. Zone configuration should
-contain at least specification of the zone file (option @code{file}), key
-directory (option @code{dnssec-keydir}), and enable automatic DNSSEC signing
-(option @code{dnssec-enable}).
-
-You can follow this example:
-
-@example
-zones @{
- storage "/var/lib/knot";
- example.com @{
- dnssec-enable on;
- dnssec-keydir "example.com.keys";
- file "example.com.db";
- @}
-@}
-@end example
-
-@item
-Start Knot DNS and check the log files to make sure that everything went right.
-
-@end enumerate
-
-@ignore
-
-@node Knot DNS for NSD users
-@appendixsec Knot DNS for NSD users
-
-[TODO]
-
-@node Knot DNS for PowerDNS users
-@appendixsec Knot DNS for PowerDNS users
-
-[TODO]
-
-@node Knot DNS for djbdns users
-@appendixsec Knot DNS for djbdns users
-
-[TODO]
-
-@end ignore
diff --git a/doc/reference.rst b/doc/reference.rst
index b5337b386630260d69588264db3a152c774922ca..e5c60e4133ecbf6abb83e1dab855b2bb8ac3e3c3 100644
--- a/doc/reference.rst
+++ b/doc/reference.rst
@@ -1,7 +1,1164 @@
+.. _Knot DNS Configuration Reference:
+
********************************
Knot DNS Configuration Reference
********************************
This reference describes every configuration option in Knot DNS server.
-TODO
+.. _system:
+
+``system`` Statement
+====================
+
+The ``system`` statement contains general options related to the
+operating system and other general options which do not fit anywhere
+else.
+
+.. _system Syntax:
+
+``system`` Syntax
+-----------------
+
+::
+
+ system {
+ [ identity ( on | "string" ); ]
+ [ version ( on | "string" ); ]
+ [ nsid ( on | "string" | hex_string ); ]
+ [ rundir "string"; ]
+ [ pidfile "string"; ]
+ [ workers integer; ]
+ [ user string[.string]; ]
+ [ max-conn-idle ( integer | integer(s | m | h | d); ) ]
+ [ max-conn-handshake ( integer | integer(s | m | h | d); ) ]
+ [ max-conn-reply ( integer | integer(s | m | h | d); ) ]
+ [ transfers integer; ]
+ [ rate-limit integer; ]
+ [ rate-limit-size integer; ]
+ [ rate-limit-slip integer; ]
+ [ max-udp-payload integer; ]
+ }
+
+.. _system Statement Definition and Usage:
+
+``system`` Statement Definition and Usage
+-----------------------------------------
+
+.. _identity:
+
+identity
+^^^^^^^^
+
+Identity of the server returned in a response for the query for TXT
+record ``id.server.`` or ``hostname.bind.`` in the CHAOS class (see
+`RFC\ 4892 <http://tools.ietf.org/html/rfc4892>`).
+
+If not specified or empty, the server returns REFUSED status code. If
+a boolean value of ``on`` is used, FQDN hostname is used as a default.
+
+::
+
+ system {
+ identity "ns01.example.com";
+ identity on;
+ }
+
+.. _version:
+
+version
+^^^^^^^
+
+Version of the server software returned in a response for the query
+for TXT record ``version.server.`` or ``version.bind.`` in the CHAOS
+class (see `RFC\ 4892 <http://tools.ietf.org/html/rfc4892>`).
+
+Option allows a boolean value ``on|off``, if ``on``, automatic version
+string is set as a default. If not specified or empty, the server
+returns REFUSED status code.
+
+::
+
+ system {
+ version "Knot DNS 1.3.0";
+ version on; # Reports current version
+ }
+
+.. _nsid:
+
+nsid
+^^^^
+
+DNS Name Server Identifier (see `RFC\ 5001 <http://tools.ietf.org/html/rfc5001>`).
+
+Use a string format "text" or a hexstring (e.g. 0x01ab00) If a
+boolean value of ``on`` is used, FQDN hostname is used as a default.
+
+::
+
+ system {
+ nsid 0x00cafe;
+ nsid "cafe";
+ nsid on;
+ }
+
+.. _rundir:
+
+rundir
+^^^^^^
+
+Path for storing run-time data, for example PID file and unix sockets.
+Default: ``${localstatedir}/run/knot``, configured with
+``--with-rundir=path``
+
+::
+
+ system {
+ rundir "/var/run/knot";
+ }
+
+.. _pidfile:
+
+pidfile
+^^^^^^^
+
+Specifies a custom PID file location.
+
+Default value: ``knot.pid`` in ``rundir`` directory.
+
+::
+
+ system {
+ pidfile "/var/run/knot/knot_dmz.pid";
+ }
+
+.. _workers:
+
+workers
+^^^^^^^
+
+Number of workers (threads) per server interface. This option is used
+to force number of threads used per interface.
+
+Default value: unset (auto-estimates optimal value from the number of
+online CPUs)
+
+::
+
+ system {
+ workers 16;
+ }
+
+.. _user:
+
+user
+^^^^
+
+System ``user`` or ``user``.``group`` under which the Knot DNS is run
+after starting and binding to interfaces. Linux capabilities
+(:ref:`Required libraries`) are employed if supported and this
+configuration option is set.
+
+Default value: ``root.root``
+
+::
+
+ system {
+ user knot.knot;
+ }
+
+.. _max-conn-idle:
+
+max-conn-idle
+^^^^^^^^^^^^^
+
+Maximum idle time between requests on a TCP connection. This also
+limits receiving of a single query, each query must be received in
+this time limit.
+
+.. _max-conn-handshake:
+
+max-conn-handshake
+^^^^^^^^^^^^^^^^^^
+
+Maximum time between newly accepted TCP connection and first query.
+This is useful to disconnect inactive connections faster, than
+connection that already made at least 1 meaningful query.
+
+.. _max-conn-reply:
+
+max-conn-reply
+^^^^^^^^^^^^^^
+
+Maximum time to wait for a reply to an issued SOA query.
+
+.. _transfers:
+
+transfers
+^^^^^^^^^
+
+Maximum parallel transfers, including pending SOA queries. Lowest
+possible number is the number of CPUs. Default is 10.
+
+.. _rate-limit:
+
+rate-limit
+^^^^^^^^^^
+
+Rate limiting is based on a token bucket scheme, rate basically
+represents number of tokens available each second. Each response is
+processed and classified (based on a several discriminators, f.e.
+source netblock, qtype, name, rcode, etc.). Classified responses are
+then hashed and assigned to a bucket containing number of available
+tokens, timestamp and metadata. When available tokens are exhausted,
+response is rejected or enters SLIP (server responds with a truncated
+response). Number of available tokens is recalculated each second.
+
+Default value: ``0 (disabled)``
+
+.. _rate-limit-size:
+
+rate-limit-size
+^^^^^^^^^^^^^^^
+
+Option controls the size of a hashtable of buckets. The larger the
+hashtable, the lesser probability of a hash collision, but at the
+expense of additional memory costs. Each bucket is estimated roughly
+to 32B. Size should be selected as a reasonably large prime due to
+the better hash function distribution properties. Hash table is
+internally chained and works well up to a fill rate of 90%, general
+rule of thumb is to select a prime near ``1.2 * maximum_qps``.
+
+Default value: ``393241``
+
+.. _rate-limit-slip:
+
+rate-limit-slip
+^^^^^^^^^^^^^^^
+
+As attacks using DNS/UDP are usually based on a forged source address,
+an attacker could deny services to the victim netblock if all
+responses would be completely blocked. The idea behind SLIP mechanism
+is to send each Nth response as truncated, thus allowing client to
+reconnect via TCP for at least some degree of service. It is worth
+noting, that some responses can't be truncated (f.e. SERVFAIL).
+
+Default value: ``1``
+
+.. _max-udp-payload:
+
+max-udp-payload
+^^^^^^^^^^^^^^^
+
+Maximum EDNS0 UDP payload size.
+
+Default value: ``4096``
+
+.. _system Example:
+
+system Example
+--------------
+
+::
+
+ system {
+ identity "Knot DNS @VERSION@";
+ version "@VERSION@";
+ nsid "amaterasu";
+ rundir "/var/run/knot";
+ workers 16;
+ user knot.knot;
+ max-udp-payload 4096;
+ }
+
+.. _keys:
+
+``keys`` Statement
+==================
+
+The ``keys`` statement sets up the TSIG keys used to authenticate
+zone transfers.
+
+.. _keys Syntax:
+
+keys Syntax
+-----------
+
+::
+
+ keys {
+ key_id algorithm "string"; ]
+ [ key_id algorithm "string"; ... ]
+ }
+
+.. _keys Statement Definition and Usage:
+
+Statement Definition and Usage
+------------------------------
+
+.. _key_id:
+
+``key_id`` Statement
+^^^^^^^^^^^^^^^^^^^^
+
+The ``key_id`` statement defines a secret shared key for use with
+TSIG. It consists of its ``name``, ``algorithm`` and ``key``
+contents.
+
+Supported algoritms:
+
+* hmac-md5
+* hmac-sha1
+* hmac-sha224
+* hmac-sha256
+* hmac-sha384
+* hmac-sha512
+
+You need to use bind or ldns utils to generate TSIG keys.
+Unfortunately, Knot DNS does not have any own generation utilities
+yet.
+
+::
+
+ $ dnssec-keygen -a HMAC-SHA256 -b 256 -n HOST foobar.example.com
+ Kfoobar.example.com.+163+21239
+ $ cat Kfoobar.example.com.+163+21239.key
+ foobar.example.com. ( IN KEY 512 3 163
+ rqv2WRyDgIUaHcJi03Zssor9jtG1kOpb3dPywxZfTeo= )
+
+Key generated in previous paragraph would be written as::
+
+ keys {
+ foobar.example.com. hmac-sha256
+ "rqv2WRyDgIUaHcJi03Zssor9jtG1kOpb3dPywxZfTeo=";
+ }
+
+.. _keys Example:
+
+keys Example
+------------
+
+::
+
+ keys {
+ key0.server0 hmac-md5 "Wg==";
+ foobar.example.com. hmac-sha256 "RQ==";
+ }
+
+.. _interfaces:
+
+interfaces Statement
+====================
+
+The ``interfaces`` statement contains IP interfaces where Knot DNS
+listens for incoming queries.
+
+.. _interfaces Syntax:
+
+``interfaces`` Syntax
+---------------------
+
+::
+
+ interfaces {
+ interface_id
+ ( ip_address[@port_number] |
+ { address ip_address; [ port port_number; ] @} )
+ [ interface_id ...; ...; ]
+ }
+
+.. _interfaces Statement Definition and Usage:
+
+``interfaces`` Statement Definition and Usage
+---------------------------------------------
+
+.. _interface_id:
+
+``interface_id``
+^^^^^^^^^^^^^^^^
+
+The ``interface_id`` is a textual identifier of an IP interface, which
+consists of an IP address and a port.
+
+The definition of an interface can be written in long or a short form
+and it always contains IP (IPv4 or IPv6) address.
+
+.. _interfaces Example:
+
+``interfaces`` Example
+----------------------
+
+Long form::
+
+ interfaces {
+ my_ip {
+ address 192.0.2.1;
+ port 53;
+ }
+ }
+
+Short form::
+
+ interfaces {
+ my_second_ip { address 198.51.100.1@@53; }
+ }
+
+Short form without port (defaults to 53)::
+
+ interfaces {
+ my_third_ip { address 203.0.113.1; }
+ }
+
+.. _remotes:
+
+``remotes`` Statement
+=====================
+
+The ``remotes`` statement sets up all remote servers for zone
+transfers. Knot DNS does not distinguish between client or server in
+this section. Role of the server is determined at the time of its
+usage in the ``zones`` section. One server may act as a client for
+one zone (e.g. downloading the updates) and as a master server for a
+different zone.
+
+.. _remotes Syntax:
+
+``remotes`` Syntax
+------------------
+
+::
+
+ remotes {
+ remote_id
+ ( ip_address[@port_number] |
+ { address ip_address;
+ [ port port_number; ]
+ [ key key_id; ]
+ [ via [ interface_id | ip_address ]; ]
+ }
+ )
+ [ remote_id @dots{}; @dots{}; ]
+ }
+
+.. _remotes Statement Definition and Grammar:
+
+``remotes`` Statement Definition and Grammar
+--------------------------------------------
+
+.. _remote_id:
+
+``remote_id``
+^^^^^^^^^^^^^
+
+``remote_id`` contains a symbolic name for a remote server.
+
+.. _address:
+
+``address``
+^^^^^^^^^^^
+
+``address`` sets an IPv4 or an IPv6 address for this particular
+``remote``.
+
+.. _port:
+
+``port``
+^^^^^^^^
+
+``port`` section contains a port number for the current ``remote``.
+This section is optional with default port set to 53.
+
+.. _key:
+
+``key``
+^^^^^^^
+
+``key`` section contains a key associated with this ``remote``. This
+section is optional.
+
+.. _via:
+
+via
+^^^
+
+``via`` section specifies which interface will be used to communicate
+with this ``remote``. This section is optional.
+
+.. _remotes Example:
+
+``remotes`` Example
+-------------------
+
+::
+
+ remotes {
+ # Long form:
+ server0 {
+ address 127.0.0.1;
+ port 53531;
+ key key0.server0;
+ via ipv4; # reference to 'remotes'
+ # via 82.35.64.59; # direct IPv4
+ # via [::cafe]; # direct IPv6
+ }
+
+ # Short form:
+ server1 {
+ address 127.0.0.1@@53001;
+ }
+ }
+
+.. _groups:
+
+``groups`` Statement
+====================
+
+The ``groups`` statement is used to create groups of remote machines
+defined in :ref:`remotes` statement. The group can substitute multiple
+machines specification anywhere in the configuration where the list of
+remotes is allowed to be used (namely ``allow`` in :ref:`control`
+section and ACLs in :ref:`zones` section).
+
+The remotes definitions must exist prior to using them in group
+definitions. One remote can be a member of multiple groups.
+
+.. _groups Syntax:
+
+``groups`` Syntax
+-----------------
+
+::
+
+ groups {
+ group_id { remote_id [ , ... ] }
+ [ ... ]
+ }
+
+.. _groups Statement Definition and Grammar:
+
+``groups`` Statement Definition and Grammar
+-------------------------------------------
+
+.. _group_id:
+
+``group_id``
+^^^^^^^^^^^^
+
+``group_id`` contains a symbolic name for a group of remotes.
+
+.. _groups-remote_id:
+
+``remote_id``
+^^^^^^^^^^^^^
+
+``remote_id`` contains a symbolic name for a remote server as
+specified in :ref:`remotes` section.
+
+.. _groups Example:
+
+``groups`` Example
+------------------
+
+::
+
+ remotes {
+ ctl {
+ # ...
+ }
+ alice {
+ # ...
+ }
+ bob {
+ # ...
+ }
+ }
+
+ groups {
+ admins { alice, bob }
+ }
+
+ # example usage:
+ control {
+ # ...
+ allow ctl, admins;
+ }
+
+.. _control:
+
+``control`` Statement
+=====================
+
+The ``control`` statement specifies on which interface to listen for
+remote control commands. Caution: The control protocol is not
+encrypted, and susceptible to replay attack in a short timeframe until
+message digest expires, for that reason, it is recommended to use
+default UNIX sockets.
+
+.. _control Syntax:
+
+``control`` Syntax
+------------------
+
+::
+
+ control {
+ [ listen-on {
+ ( address ip_address[@@port_number] |
+ { address ip_address; [ port port_number; ] } )
+ } ]
+ [ allow remote_id [, remote_id, @dots{} ]; ]
+ }
+
+.. _control Statement Definition and Grammar:
+
+``control`` Statement Definition and Grammar
+--------------------------------------------
+
+Control interface ``listen-on`` either defines a UNIX socket or an
+IPv4/IPv6 ``interface`` definition as in :ref:`interfaces`. Default
+port for IPv4/v6 control interface is ``5533``, however UNIX socket is
+preferred. UNIX socket address is relative to ``rundir`` if not
+specified as an absolute path. Without any configuration, the socket
+will be created in ``rundir/knot.sock``.
+
+.. _control Examples:
+
+``control`` Examples
+--------------------
+
+
+UNIX socket example::
+
+ control {
+ listen-on "/var/run/knot/knot.sock";
+ }
+
+IPv4 socket example::
+
+ keys {
+ knotc-key hmac-md5 "Wg==";
+ }
+ remotes {
+ ctl { address 127.0.0.1; key knotc-key; }
+ }
+ control {
+ listen-on { address 127.0.0.1; }
+ allow ctl;
+ }
+
+.. _zones:
+
+``zones`` Statement
+===================
+
+The ``zones`` statement contains definition of zones served by Knot DNS.
+
+.. _zones Syntax:
+
+``zones`` Syntax
+----------------
+
+::
+
+ zones {
+ [ zone_options ]
+ zone_id {
+ file "string";
+ [ xfr-in remote_id [, remote_id, @dots{} ]; ]
+ [ xfr-out remote_id [, remote_id, @dots{} ]; ]
+ [ notify-in remote_id [, remote_id, @dots{} ]; ]
+ [ notify-out remote_id [, remote_id, @dots{} ]; ]
+ [ update-in remote_id [, remote_id, @dots{} ]; ]
+ [ query_module { module_name "string"; [ module_name "string"; @dots{} ] } ]
+ [ zone_options ]
+ }
+ }
+
+ zone_options :=
+ [ storage "string"; ]
+ [ semantic-checks boolean; ]
+ [ ixfr-from-differences boolean; ]
+ [ disable-any boolean; ]
+ [ notify-timeout integer; ]
+ [ notify-retries integer; ]
+ [ zonefile-sync ( integer | integer(s | m | h | d); ) ]
+ [ ixfr-fslimit ( integer | integer(k | M | G) ); ]
+ [ ixfr-from-differences boolean; ]
+ [ dnssec-keydir "string"; ]
+ [ dnssec-enable ( on | off ); ]
+ [ signature-lifetime ( integer | integer(s | m | h | d); ) ]
+ [ serial-policy ( increment | unixtime ); ]
+
+.. _zones Statement Definition and Grammar:
+
+``zones`` Statement Definition and Grammar
+------------------------------------------
+
+.. _zone_id:
+
+``zone_id``
+^^^^^^^^^^^
+
+``zone_id`` is a zone origin, and as such is a domain name that may or
+may not end with a ".". If no $ORIGIN directive is found inside
+actual zone file, this domain name will be used in place of "@@". SOA
+record in the zone must have this name as its owner.
+
+.. _file:
+
+``file``
+^^^^^^^^
+
+The ``file`` statement defines a path to the zone file. You can
+either use an absolute path or a relative path. In that case, the
+zone file path will be relative to the ``storage`` directory
+(:ref:`storage`).
+
+.. _xfr-in:
+
+``xfr-in``
+^^^^^^^^^^
+
+In ``xfr-in`` statement user specifies which remotes will be permitted
+to perform a zone transfer to update the zone. Remotes are defined in
+``remotes`` section of configuration file (:ref:`remotes`).
+
+.. _xfr-out:
+
+``xfr-out``
+^^^^^^^^^^^
+
+In ``xfr-out`` statement user specifies which remotes will be
+permitted to obtain zone's contents via zone transfer. Remotes are
+defined in ``remotes`` section of configuration file
+(:ref:`remotes`).
+
+.. _notify-in:
+
+``notify-in``
+^^^^^^^^^^^^^
+
+``notify-in`` defines which remotes will be permitted to send NOTIFY
+for this particular zone. Remotes are defined in ``remotes`` section
+of configuration file (:ref:`remotes`).
+
+.. _notify-out:
+
+``notify-out``
+^^^^^^^^^^^^^^
+
+``notify-out`` defines to which remotes will your server send NOTIFYs
+about this particular zone. Remotes are defined in ``remotes``
+section of configuration file (:ref:`remotes`).
+
+.. _update-in:
+
+``update-in``
+^^^^^^^^^^^^^
+
+In ``update-in`` statement user specifies which remotes will be
+permitted to perform a DNS UPDATE. Remotes are defined in ``remotes``
+section of configuration file (:ref:`remotes`).
+
+.. _query_module :
+
+``query_module``
+^^^^^^^^^^^^^^^^
+
+Statement ``query_module`` takes a list of ``module_name
+"config_string"`` query modules separated by semicolon.
+
+.. _storage:
+
+``storage``
+^^^^^^^^^^^
+
+Data directory for zones. It is used to store zone files and journal
+files.
+
+Value of ``storage`` set in ``zone`` section is relative to
+``storage`` in ``zones`` section.
+
+Default value (in ``zones`` section): ``${localstatedir}/lib/knot``,
+configured with ``--with-storage=path``
+
+Default value (in ``zone`` config): inherited from ``zones`` section
+
+::
+
+ zones {
+ storage "/var/lib/knot";
+ example.com {
+ storage "com";
+ file "example.com"; # /var/lib/knot/com/example.com
+ }
+ }
+
+.. _semantic-checks:
+
+``semantic-checks``
+^^^^^^^^^^^^^^^^^^^
+
+``semantic-checks`` statement turns on optional semantic checks for
+this particular zone. See :ref:`zones List of zone semantic checks` for
+more information.
+
+Possible values are ``on`` and ``off``. Most checks are disabled by
+default.
+
+.. _ixfr-from-differences:
+
+``ixfr-from-differences``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Option ``ixfr-from-differences`` is only relevant if you are running
+Knot DNS as a master for this zone. By turning the feature on you
+tell Knot to create differences from changes you made to a zone file
+upon server reload. See :ref:`Controlling running daemon` for more
+information.
+
+Possible values are ``on`` and ``off``. Disabled by default.
+
+.. _disable-any:
+
+``disable-any``
+^^^^^^^^^^^^^^^
+
+If you enable ``disable-any``, all authoritative ANY queries sent over
+UDP will be answered with an empty response and with the TC bit set.
+Use to minimize the risk of DNS reflection attack. Disabled by default.
+
+.. _notify-timeout:
+
+``notify-timeout``
+^^^^^^^^^^^^^^^^^^
+
+``notify-timeout`` in seconds specifies how long will server wait for
+NOTIFY response. Possible values are 1 to INT_MAX. By default, this
+value is set to 60 seconds.
+
+.. _notify-retries:
+
+``notify-retries``
+^^^^^^^^^^^^^^^^^^
+
+``notify-retries`` tells the server how many times it can retry to
+send a NOTIFY. Possible values are 1 to INT_MAX and default value
+is 5.
+
+.. _zonefile-sync:
+
+``zonefile-sync``
+^^^^^^^^^^^^^^^^^
+
+``zonefile-sync`` specifies a time in seconds after which current zone
+in memory will be synced to zone file on the disk (as set in
+:ref:`file`). Knot DNS will serve the latest zone even after restart,
+but zone file on a disk will only be synced after ``zonefile-sync``
+time has expired (or synced manually via ``knotc flush`` - see
+:ref:`Running Knot DNS`). This is applicable when the zone is updated
+via IXFR, DDNS or automatic DNSSEC signing. Possible values are 0 to
+INT_MAX, optionally suffixed by unit size (s/m/h/d) - @emph{1s} is one
+second, @emph{1m} one minute, @emph{1h} one hour and @emph{1d} one day
+with default value set to @emph{0s}.
+
+*Important note:* If you are serving large zones with frequent
+updates where the immediate sync to zone file is not desirable, set
+this value in the configuration file to other value.
+
+.. _ixfr-fslimit:
+
+``ixfr-fslimit``
+^^^^^^^^^^^^^^^^
+
+``ixfr-fslimit`` sets a maximum file size for zone's journal in bytes.
+Possible values are 1 to INT_MAX, with optional suffixes k, m and G.
+I.e. *1k*, *1m* and *1G* with default value not being set, meaning
+that journal file can grow without limitations.
+
+.. _dnssec-keydir:
+
+``dnssec-keydir``
+^^^^^^^^^^^^^^^^^
+
+Location of DNSSEC signing keys, relative to ``storage``.
+
+Default value: not set
+
+.. _dnssec-enable:
+
+``dnssec-enable``
+^^^^^^^^^^^^^^^^^
+
+PREVIEW: Enable automatic DNSSEC signing for the zone.
+
+Default value (in ``zones`` section): ``off``
+
+Default value (in ``zone`` config): inherited from ``zones`` section
+
+.. _signature-lifetime:
+
+``signature-lifetime``
+^^^^^^^^^^^^^^^^^^^^^^
+
+Specifies how long should the automatically generated DNSSEC signatures be valid.
+Expiration will thus be set as current time (in the moment of signing)
++ ``signature-lifetime``. Possible values are from 10801 to INT_MAX.
+The signatures are refreshed one tenth of the signature lifetime
+before the signature expiration (i.e., 3 days before the expiration
+with the default value). For information about zone expiration date,
+invoke the ``knotc zonestatus`` command.
+
+Default value: ``30d`` (``2592000``)
+
+.. _serial-policy:
+
+``serial-policy``
+^^^^^^^^^^^^^^^^^
+
+Specifies how the zone serial is updated after DDNS (dynamic update)
+and automatic DNSSEC signing. If the serial is changed by the dynamic
+update, no change is made.
+
+* ``increment`` - After update or signing, the serial is automatically
+ incremented (according to serial number arithmetic).
+* ``unixtime`` - After update or signing, serial is set to the current
+ unix time.
+
+*Warning:* If your serial was in other than unix time format, be
+careful with transition to unix time. It may happen that the new
+serial will be 'lower' than the old one. If this is the case, the
+transition should be done by hand (see `RFC\ 1982
+<https://tools.ietf.org/html/rfc1982>`).
+
+Default value: ``increment``
+
+.. _zones Example:
+
+``zones`` Example
+-----------------
+
+::
+
+ zones {
+
+ # Shared options for all listed zones
+ storage "/var/lib/knot";
+ ixfr-from-differences off;
+ semantic-checks off;
+ disable-any off;
+ notify-timeout 60;
+ notify-retries 5;
+ zonefile-sync 0;
+ ixfr-fslimit 1G;
+ dnssec-enable on;
+ dnssec-keydir "keys";
+ signature-lifetime 60d;
+ serial-policy increment;
+ example.com {
+ storage "samples";
+ file "example.com.zone";
+ ixfr-from-differences off;
+ disable-any off;
+ semantic-checks on;
+ notify-timeout 60;
+ notify-retries 5;
+ zonefile-sync 0;
+ dnssec-keydir "keys";
+ dnssec-enable off;
+ signature-lifetime 30d;
+ serial-policy increment;
+ xfr-in server0;
+ xfr-out server0, server1;
+ notify-in server0;
+ notify-out server0, server1;
+ }
+ }
+
+.. _zones List of zone semantic checks:
+
+``zones`` List of zone semantic checks
+--------------------------------------
+
+The ``semantic-checks`` statement turns on extra zone file semantic
+checks. Several checks are enabled by default and cannot be turned
+off. If an error is found using these mandatory checks, the zone file
+will not be loaded. Upon loading a zone file, occurred errors and
+counts of their occurrence will be logged to @emph{stderr}. These
+checks are the following:
+
+* An extra record together with CNAME record (except for RRSIG and DS)
+* CNAME link chain length greater than 10 (including infinite cycles)
+* DNAME and CNAME records under the same owner (RFC 2672)
+* CNAME and DNAME wildcards pointing to themselves
+* SOA record missing in the zone (RFC 1034)
+* DNAME records having records under it (DNAME children) (RFC 2672)
+
+Following checks have to be turned on using ``semantic-checks`` and a
+zone containing following errors will be loaded even upon discovering
+an error:
+
+- Missing NS record at the zone apex
+- Missing glue A or AAAA records
+- Broken or non-cyclic NSEC(3) chain
+- Wrong NSEC(3) type bitmap
+- Multiple NSEC records at the same node
+- Missing NSEC records at authoritative nodes
+- Extra record types under same name as NSEC3 record (this is
+ RFC-valid, but Knot will not serve such a zone correctly)
+- NSEC3-unsecured delegation that is not part of Opt-out span
+- Wrong original TTL value in NSEC3 records
+- Wrong RDATA TTL value in RRSIG record
+- Signer name in RRSIG RR not the same as in DNSKEY
+- Signed RRSIG
+- Not all RRs in node are signed
+- Wrong key flags or wrong key in RRSIG record (not the same as ZSK)
+
+.. _log:
+
+``log`` Statement
+=================
+
+.. _log Syntax:
+
+``log`` Syntax
+--------------
+
+::
+
+ log {
+ [ log_name {
+ [ category severity [, severity @dots{} ]; ]
+ } ]
+ [ log_file filename {
+ [ category severity [, severity @dots{} ]; ]
+ } ]
+ }
+
+.. _log Statement Definition and Grammar:
+
+``log`` Statement Definition and Grammar
+----------------------------------------
+
+The ``log`` statement configures logging output of Knot DNS. You can
+configure Knot DNS to log into file or system log. There are several
+logging categories to choose from. Each log message has its severity
+and user can configure severities for each log destination.
+
+In case of missing log section, severities from ``warning`` and more
+serious will be logged to both ``stderr`` and ``syslog``. The
+``info`` and ``notice`` severities will be logged to the ``stdout``.
+
+.. _log_name:
+
+``log_name``
+^^^^^^^^^^^^
+
+``log_name`` should be replaced with one of 3 symbolic log names:
+
+* ``stdout`` - logging to standard output
+* ``stderr`` - logging to standard error output
+* ``syslog`` - logging to syslog
+
+.. _category:
+
+``category``
+^^^^^^^^^^^^
+
+Knot DNS allows user to choose from these logging categories:
+
+* ``server`` - Messages related to general operation of the server.
+* ``zone`` - Messages related to zones, zone parsing and loading.
+* ``answering`` - Messages regarding query processing and response creation.
+* ``any`` - All categories.
+
+.. _severity:
+
+``severity``
+^^^^^^^^^^^^
+
+Knot DNS has the following logging severities:
+
+* ``debug`` - Debug messages, must be turned on at compile time (:ref:`Enabling debug messages in server`).
+* ``info`` - Informational message.
+* ``notice`` - Server notices and hints.
+* ``warning`` - Warnings that might require user action.
+* ``error`` - Recoverable error. Action should be taken.
+* ``all`` - All severities.
+
+More severities may be listed for each category, but all severities
+have to be listed explicitly, i.e. using ``warning`` severity does
+not mean that ``error`` severity messages will be logged as well.
+
+.. _log_file:
+
+``log_file``
+^^^^^^^^^^^^
+
+``log_file`` is either absolute or relative path to file user wants to
+log to. See following example for clarification.
+
+.. _log Example:
+
+log Example
+-----------
+
+::
+
+ log {
+
+ syslog {
+ any error;
+ zone warning, notice;
+ server info;
+ }
+
+ stderr {
+ any error, warning;
+ }
+
+ file "/tmp/knot-sample/knotd.debug" {
+ server debug;
+ }
+ }
+
+.. _include:
+
+``include`` Statement
+=====================
+
+The ``include`` statement is a special statement which can be used
+almost anywhere on any level in the configuration file. It allows
+inclusion of another file or all files in the given directory.
+
+The path of the included file can be either absolute or relative to a
+configuration file currently being processed.
+
+.. _include Syntax:
+
+``include`` Syntax
+------------------
+
+::
+
+ include "filename";
+ include "dirname";
+
+.. _include Examples:
+
+``include`` Examples
+--------------------
+
+::
+
+ include "keys.conf";
+
+ remotes {
+ ctl {
+ address 127.0.0.1;
+ key knotc-key;
+ }
+ include "remotes.conf";
+ }
+
+ include "zones";
diff --git a/doc/reference.texi b/doc/reference.texi
deleted file mode 100644
index 30001542ec3ccd69b609be242425b85c8421bdbf..0000000000000000000000000000000000000000
--- a/doc/reference.texi
+++ /dev/null
@@ -1,1178 +0,0 @@
-@node Knot DNS Configuration Reference, Migration from other DNS servers, Statement Index, Top
-@appendix Knot DNS Configuration Reference
-
-This reference describes every configuration option in Knot DNS server.
-
-@menu
-* system::
-* keys::
-* interfaces::
-* remotes::
-* groups::
-* control::
-* zones::
-* log::
-* include::
-@end menu
-
-@node system
-@section @code{system} Statement
-@stindex system
-
-The @code{system} statement contains general options related to the
-operating system and other general options which do not fit anywhere
-else.
-
-@menu
-* system Syntax::
-* system Statement Definition and Usage::
-* system Example::
-@end menu
-
-@node system Syntax
-@subsection @code{system} Syntax
-
-@example
-@code{system} @code{@{}
- [ @code{identity} ( @code{on} | @code{"}@kbd{string}@code{"} )@code{;} ]
- [ @code{version} ( @code{on} | @code{"}@kbd{string}@code{"} )@code{;} ]
- [ @code{nsid} ( @code{on} | @code{"}@kbd{string}@code{"} | @kbd{hex_string} )@code{;} ]
- [ @code{rundir} @code{"}@kbd{string}@code{";} ]
- [ @code{pidfile} @code{"}@kbd{string}@code{";} ]
- [ @code{workers} @kbd{integer}@code{;} ]
- [ @code{user} @kbd{string}[@code{.}@kbd{string}]@code{;} ]
- [ @code{max-conn-idle} ( @kbd{integer} | @kbd{integer}(@code{s} | @code{m} | @code{h} | @code{d})@code{;} ) ]
- [ @code{max-conn-handshake} ( @kbd{integer} | @kbd{integer}(@code{s} | @code{m} | @code{h} | @code{d})@code{;} ) ]
- [ @code{max-conn-reply} ( @kbd{integer} | @kbd{integer}(@code{s} | @code{m} | @code{h} | @code{d})@code{;} ) ]
- [ @code{transfers} @kbd{integer}@code{;} ]
- [ @code{rate-limit} @kbd{integer}@code{;} ]
- [ @code{rate-limit-size} @kbd{integer}@code{;} ]
- [ @code{rate-limit-slip} @kbd{integer}@code{;} ]
- [ @code{max-udp-payload} @kbd{integer}@code{;} ]
-@code{@}}
-@end example
-
-@node system Statement Definition and Usage
-@subsection Statement Definition and Usage
-
-@menu
-* identity::
-* version::
-* nsid::
-* rundir::
-* pidfile::
-* workers::
-* user::
-* max-conn-idle::
-* max-conn-handshake::
-* max-conn-reply::
-* transfers::
-* rate-limit::
-* rate-limit-size::
-* rate-limit-slip::
-* max-udp-payload::
-@end menu
-
-@node identity
-@subsubsection identity
-@vindex identity
-
-Identity of the server returned in a response for the query for TXT record
-@code{id.server.} or @code{hostname.bind.} in the CHAOS class
-(see @url{http://tools.ietf.org/html/rfc4892,RFC 4892}).
-
-If not specified or empty, the server returns REFUSED status code.
-If a boolean value of @code{on} is used, FQDN hostname is used as a default.
-
-@example
-system @{
- identity "ns01.example.com";
- identity on;
-@}
-@end example
-
-@node version
-@subsubsection version
-@vindex version
-
-Version of the server software returned in a response for the query for TXT
-record @code{version.server.} or @code{version.bind.} in the CHAOS class
-(see @url{http://tools.ietf.org/html/rfc4892,RFC 4892}).
-
-Option allows a boolean value @code{on|off}, if @code{on}, automatic version
-string is set as a default. If not specified or empty, the server returns REFUSED status code.
-
-@example
-system @{
- version "Knot DNS 1.3.0";
- version on; # Reports current version
-@}
-@end example
-
-@node nsid
-@subsubsection nsid
-@vindex nsid
-
-DNS Name Server Identifier (see @url{http://tools.ietf.org/html/rfc5001,RFC 5001}).
-
-Use a string format "text" or a hexstring (e.g. 0x01ab00)
-If a boolean value of @code{on} is used, FQDN hostname is used as a default.
-
-@example
-system @{
- nsid 0x00cafe;
- nsid "cafe";
- nsid on;
-@}
-@end example
-
-@node rundir
-@subsubsection rundir
-@vindex rundir
-
-Path for storing run-time data, for example PID file and unix sockets.
-Default: @file{$@{localstatedir@}/run/knot}, configured with @code{--with-rundir=path}
-
-@example
-system @{
- rundir "/var/run/knot";
-@}
-@end example
-
-@node pidfile
-@subsubsection pidfile
-@vindex pidfile
-
-Specifies a custom PID file location.
-
-Default value: @file{knot.pid} in @code{rundir} directory.
-
-@example
-system @{
- pidfile "/var/run/knot/knot_dmz.pid";
-@}
-@end example
-
-@node workers
-@subsubsection workers
-@vindex workers
-
-Number of workers (threads) per server interface. This option is used to
-force number of threads used per interface.
-
-Default value: unset (auto-estimates optimal value from the number of online CPUs)
-
-@example
-system @{
- workers 16;
-@}
-@end example
-
-@node user
-@subsubsection user
-@vindex user
-
-System @kbd{user} or @kbd{user}.@kbd{group} under which the Knot DNS
-is run after starting and binding to interfaces.
-Linux capabilities (@pxref{Required libraries}) are employed if supported
-and this configuration option is set.
-
-Default value: @kbd{root.root}
-
-@example
-system @{
- user knot.knot;
-@}
-@end example
-
-@node max-conn-idle
-@subsubsection max-conn-idle
-@vindex max-conn-idle
-
-Maximum idle time between requests on a TCP connection.
-This also limits receiving of a single query, each query must be received in this time limit.
-
-@node max-conn-handshake
-@subsubsection max-conn-handshake
-@vindex max-conn-handshake
-
-Maximum time between newly accepted TCP connection and first query.
-This is useful to disconnect inactive connections faster, than connection
-that already made at least 1 meaningful query.
-
-@node max-conn-reply
-@subsubsection max-conn-reply
-@vindex max-conn-reply
-
-Maximum time to wait for a reply to an issued SOA query.
-
-@node transfers
-@subsubsection transfers
-@vindex transfers
-
-Maximum parallel transfers, including pending SOA queries.
-Lowest possible number is the number of CPUs.
-Default is 10.
-
-@node rate-limit
-@subsubsection rate-limit
-@vindex rate-limit
-
-Rate limiting is based on a token bucket scheme, rate basically represents number of tokens available each second.
-Each response is processed and classified (based on a several discriminators, f.e. source netblock, qtype, name, rcode, etc.).
-Classified responses are then hashed and assigned to a bucket containing number of available tokens, timestamp and metadata.
-When available tokens are exhausted, response is rejected or enters SLIP (server responds with a truncated response).
-Number of available tokens is recalculated each second.
-
-Default value: @kbd{0 (disabled)}
-
-@node rate-limit-size
-@subsubsection rate-limit-size
-@vindex rate-limit-size
-
-Option controls the size of a hashtable of buckets. The larger the hashtable, the lesser probability of a hash collision, but
-at the expense of additional memory costs. Each bucket is estimated roughly to 32B.
-Size should be selected as a reasonably large prime due to the better hash function distribution properties.
-Hash table is internally chained and works well up to a fill rate of 90%, general rule of thumb is to select a prime near
-@kbd{1.2 * maximum_qps}.
-
-Default value: @kbd{393241}
-
-@node rate-limit-slip
-@subsubsection rate-limit-slip
-@vindex rate-limit-slip
-
-As attacks using DNS/UDP are usually based on a forged source address, an attacker could deny services to the victim netblock
-if all responses would be completely blocked. The idea behind SLIP mechanism is to send each Nth response as truncated, thus allowing
-client to reconnect via TCP for at least some degree of service. It is worth noting, that some responses can't be truncated (f.e. SERVFAIL).
-
-Default value: @kbd{1}
-
-@node max-udp-payload
-@subsubsection max-udp-payload
-@vindex max-udp-payload
-
-Maximum EDNS0 UDP payload size.
-
-Default value: @kbd{4096}
-
-@node system Example
-@subsection system Example
-
-@example
-system @{
- identity "Knot DNS @value{VERSION}";
- version "@value{VERSION}";
- nsid "amaterasu";
- rundir "/var/run/knot";
- workers 16;
- user knot.knot;
- max-udp-payload 4096;
-@}
-@end example
-
-@node keys
-@section @code{keys} Statement
-@stindex keys
-
-The @code{keys} statement sets up the TSIG keys used to authenticate
-zone transfers.
-
-@menu
-* keys Syntax::
-* keys Statement Definition and Usage::
-* Example::
-@end menu
-
-@node keys Syntax
-@subsection keys Syntax
-
-@example
-keys @{
- key_id algorithm "string"; ]
- [ key_id algorithm "string"; ... ]
-@}
-@end example
-
-@node keys Statement Definition and Usage
-@subsection Statement Definition and Usage
-
-@menu
-* key_id::
-@end menu
-
-@node key_id
-@subsubsection @code{key_id} Statement
-@vindex key_id
-
-The @kbd{key_id} statement defines a secret shared key for use with
-TSIG. It consists of its @kbd{name}, @kbd{algorithm} and @kbd{key} contents.
-
-Supported algoritms:
-
-@itemize
-@item
-hmac-md5
-@item
-hmac-sha1
-@item
-hmac-sha224
-@item
-hmac-sha256
-@item
-hmac-sha384
-@item
-hmac-sha512
-@end itemize
-
-You need to use bind or ldns utils to generate TSIG keys. Unfortunately, Knot DNS does not have any own generation utilities yet.
-
-@example
-
-$ dnssec-keygen -a HMAC-SHA256 -b 256 -n HOST foobar.example.com
-Kfoobar.example.com.+163+21239
-$ cat Kfoobar.example.com.+163+21239.key
-foobar.example.com. ( IN KEY 512 3 163
- rqv2WRyDgIUaHcJi03Zssor9jtG1kOpb3dPywxZfTeo= )
-
-@end example
-
-Key generated in previous paragraph would be written as:
-
-@example
-
-keys @{
- foobar.example.com. hmac-sha256
- "rqv2WRyDgIUaHcJi03Zssor9jtG1kOpb3dPywxZfTeo=";
-@}
-
-@end example
-
-@node Example
-@subsection keys Example
-
-
-@example
-
-keys @{
- key0.server0 hmac-md5 "Wg==";
- foobar.example.com. hmac-sha256 "RQ==";
-@}
-
-@end example
-
-@node interfaces
-@section interfaces
-@stindex interfaces
-
-The @code{interfaces} statement contains IP interfaces where Knot DNS listens for incoming queries.
-
-@menu
-* interfaces Syntax::
-* interfaces Statement Definition and Usage::
-* interfaces Examples::
-@end menu
-
-@node interfaces Syntax
-@subsection Syntax
-
-@example
-@code{interfaces} @code{@{}
- @kbd{interface_id}
- ( @kbd{ip_address}[@@@kbd{port_number}] |
- @code{@{} @code{address} @kbd{ip_address}@code{;} [ @code{port} @kbd{port_number}@code{;} ] @code{@}} )
- [ @kbd{interface_id ...}@code{;} @kbd{...}@code{;} ]
-@code{@}}
-@end example
-
-@node interfaces Statement Definition and Usage
-@subsection Statement Definition and Usage
-
-@menu
-* interface_id::
-@end menu
-
-@node interface_id
-@subsubsection @kbd{interface_id}
-@vindex interface_id
-
-The @kbd{interface_id} is a textual identifier of an IP interface,
-which consists of an IP address and a port.
-
-The definition of an interface can be written in long or a short form and
-it always contains IP (IPv4 or IPv6) address.
-
-@node interfaces Examples
-@subsection interfaces Examples
-
-Long form:
-
-@example
-
-interfaces @{
- my_ip @{
- address 192.0.2.1;
- port 53;
- @}
-@}
-
-@end example
-
-Short form:
-
-@example
-
-interfaces @{
- my_second_ip @{ address 198.51.100.1@@53; @}
-@}
-
-@end example
-
-Short form without port (defaults to 53):
-
-@example
-
-interfaces @{
- my_third_ip @{ address 203.0.113.1; @}
-@}
-
-@end example
-
-@node remotes
-@section @code{remotes} Statement
-@stindex remotes
-
-The @code{remotes} statement sets up all remote servers for zone
-transfers. Knot DNS does not distinguish between client or server in
-this section. Role of the server is determined at the time of its
-usage in the @code{zones} section. One server may act as a
-client for one zone (e.g. downloading the updates) and as a master
-server for a different zone.
-
-@menu
-* remotes Syntax::
-* remotes Statement Definition and Grammar::
-* remotes Examples::
-@end menu
-
-@node remotes Syntax
-@subsection Syntax
-
-@example
-@code{remotes} @code{@{}
- @kbd{remote_id}
- ( @kbd{ip_address}[@code{@@}@kbd{port_number}] |
- @code{@{} @code{address} @kbd{ip_address};
- [ @code{port} @kbd{port_number}; ]
- [ @code{key} @kbd{key_id}; ]
- [ @code{via} [ @kbd{interface_id} | @kbd{ip_address} ]; ]
- @code{@}}
- )
- [ @kbd{remote_id} @dots{}; @dots{}; ]
-@code{@}}
-@end example
-
-@node remotes Statement Definition and Grammar
-@subsection Statement Definition and Grammar
-
-@menu
-* remote_id::
-* address::
-* port::
-* key::
-* via::
-@end menu
-
-@node remote_id
-@subsubsection @kbd{remote_id}
-@vindex remote_id
-
-@kbd{remote_id} contains a symbolic name for a remote server.
-
-@node address
-@subsubsection address
-@vindex address
-
-@kbd{address} sets an IPv4 or an IPv6 address for this particular @code{remote}.
-
-@node port
-@subsubsection port
-@vindex port
-
-@code{port} section contains a port number for the current @code{remote}. This section is optional with default port set to 53.
-
-@node key
-@subsubsection key
-@vindex key
-
-@code{key} section contains a key associated with this @code{remote}. This section is optional.
-
-
-@node via
-@subsubsection via
-@vindex via
-
-@code{via} section specifies which interface will be used to communicate with this @code{remote}. This section is optional.
-
-@node remotes Examples
-@subsection remotes Examples
-
-@example
-
-remotes @{
-
- # Format 1:
- server0 @{
- address 127.0.0.1;
- port 53531;
- key key0.server0;
- via ipv4; # reference to 'remotes'
- # via 82.35.64.59; # direct IPv4
- # via [::cafe]; # direct IPv6
- @}
-
- # Format 2:
- server1 @{
- address 127.0.0.1@@53001;
- @}
-@}
-
-@end example
-
-@node groups
-@section @code{groups} Statement
-@stindex groups
-
-The @code{groups} statement is used to create groups of remote machines defined
-in @ref{remotes} statement. The group can substitute multiple machines
-specification anywhere in the configuration where the list of remotes is
-allowed to be used (namely @code{allow} in @ref{control} section and ACLs in
-@ref{zones} section).
-
-The remotes definitions must exist prior to using them in group definitions.
-One remote can be a member of multiple groups.
-
-@menu
-* groups Syntax::
-* groups Statement Definition and Grammar::
-* groups Examples::
-@end menu
-
-@node groups Syntax
-@subsection Syntax
-
-@example
-@code{groups} @code{@{}
- @kbd{group_id} @code{@{} @kbd{remote_id} [ @code{,} @kbd{...} ] @code{@}}
- [ @kbd{...} ]
-@code{@}}
-@end example
-
-@node groups Statement Definition and Grammar
-@subsection Statement Definition and Grammar
-
-@menu
-* group_id::
-* remote_id:groups_remote_id.
-@end menu
-
-@node group_id
-@subsubsection @kbd{group_id}
-@vindex group_id
-
-@kbd{group_id} contains a symbolic name for a group of remotes.
-
-@node groups_remote_id
-@subsubsection @kbd{remote_id}
-@vindex groups_remote_id
-
-@kbd{remote_id} contains a symbolic name for a remote server as specified in
-@ref{remotes} section.
-
-@node groups Examples
-@subsection Examples
-
-@example
-remotes @{
- ctl @{
- # ...
- @}
- alice @{
- # ...
- @}
- bob @{
- # ...
- @}
-@}
-
-groups @{
- admins @{ alice, bob @}
-@}
-
-# example usage:
-control @{
- # ...
- allow ctl, admins;
-@}
-@end example
-
-@node control
-@section @code{control} Statement
-
-The @code{control} statement specifies on which interface to listen for remote control commands.
-Caution: The control protocol is not encrypted,
-and susceptible to replay attack in a short timeframe until message digest expires,
-for that reason, it is recommended to use default UNIX sockets.
-
-@menu
-* control Syntax::
-* control Statement Definition and Grammar::
-* control Examples::
-@end menu
-
-@node control Syntax
-@subsection Syntax
-
-@example
-@code{control} @code{@{}
- [ @kbd{listen-on} @code{@{}
- ( @code{address} @kbd{ip_address}[@@@kbd{port_number}] |
- @code{@{} @code{address} @kbd{ip_address}@code{;} [ @code{port} @kbd{port_number}@code{;} ] @code{@}} )
- @code{@}} ]
- [ @code{allow} @kbd{remote_id} [, @kbd{remote_id}, @dots{} ]@code{;} ]
-@code{@}}
-@end example
-
-@node control Statement Definition and Grammar
-@subsection Statement Definition and Grammar
-
-Control interface @code{listen-on} either defines a UNIX socket or an
-IPv4/IPv6 @code{interface} definition as in @ref{interfaces}.
-Default port for IPv4/v6 control interface is @code{5533},
-however UNIX socket is preferred.
-UNIX socket address is relative to @code{rundir} if not specified as an absolute
-path. Without any configuration, the socket will be created in @code{rundir/knot.sock}.
-
-@node control Examples
-@subsection Examples
-
-UNIX socket example:
-@example
-control @{
- listen-on "/var/run/knot/knot.sock";
-@}
-@end example
-
-IPv4 socket example:
-@example
-keys @{
- knotc-key hmac-md5 "Wg==";
-@}
-remotes @{
- ctl @{ address 127.0.0.1; key knotc-key; @}
-@}
-control @{
- listen-on @{ address 127.0.0.1; @}
- allow ctl;
-@}
-@end example
-
-
-@node zones
-@section @code{zones} Statement
-
-The @code{zones} statement contains definition of zones served by Knot DNS.
-
-@menu
-* zones Syntax::
-* zones Statement Definition and Grammar::
-* zones Example::
-* zones List of zone semantic checks::
-@end menu
-
-@node zones Syntax
-@subsection Syntax
-
-@example
-@code{zones} @code{@{}
- [ @kbd{zone_options} ]
- @kbd{zone_id} @code{@{}
- @code{file} @code{"}@kbd{string}@code{";}
- [ @code{xfr-in} @kbd{remote_id} [, @kbd{remote_id}, @dots{} ]@code{;} ]
- [ @code{xfr-out} @kbd{remote_id} [, @kbd{remote_id}, @dots{} ]@code{;} ]
- [ @code{notify-in} @kbd{remote_id} [, @kbd{remote_id}, @dots{} ]@code{;} ]
- [ @code{notify-out} @kbd{remote_id} [, @kbd{remote_id}, @dots{} ]@code{;} ]
- [ @code{update-in} @kbd{remote_id} [, @kbd{remote_id}, @dots{} ]@code{;} ]
- [ @code{query_module} @code{@{} @kbd{module_name} @code{"}@kbd{string}@code{"}@code{;} [ @kbd{module_name} @code{"}@kbd{string}@code{"}; @dots{} ] @code{@}} ]
- [ @kbd{zone_options} ]
- @code{@}}
-@code{@}}
-
-@kbd{zone_options} :=
- [ @code{storage} @code{"}@kbd{string}@code{";} ]
- [ @code{semantic-checks} @kbd{boolean}@code{;} ]
- [ @code{ixfr-from-differences} @kbd{boolean}@code{;} ]
- [ @code{disable-any} @kbd{boolean}@code{;} ]
- [ @code{notify-timeout} @kbd{integer}@code{;} ]
- [ @code{notify-retries} @kbd{integer}@code{;} ]
- [ @code{zonefile-sync} ( @kbd{integer} | @kbd{integer}(@code{s} | @code{m} | @code{h} | @code{d})@code{;} ) ]
- [ @code{ixfr-fslimit} ( @kbd{integer} | @kbd{integer}(@code{k} | @code{M} | @code{G}) )@code{;} ]
- [ @code{ixfr-from-differences} @kbd{boolean}@code{;} ]
- [ @code{dnssec-keydir} @code{"}@kbd{string}@code{"}@code{;} ]
- [ @code{dnssec-enable} ( @code{on} | @code{off} )@code{;} ]
- [ @code{signature-lifetime} ( @kbd{integer} | @kbd{integer}(@code{s} | @code{m} | @code{h} | @code{d})@code{;} ) ]
- [ @code{serial-policy} ( increment | unixtime ); ]
-@end example
-
-@node zones Statement Definition and Grammar
-@subsection Statement Definition and Grammar
-
-@menu
-* zone_id::
-* file::
-* xfr-in::
-* xfr-out::
-* notify-in::
-* notify-out::
-* update-in::
-* query_module::
-* storage::
-* semantic-checks::
-* ixfr-from-differences::
-* disable-any::
-* notify-timeout::
-* notify-retries::
-* zonefile-sync::
-* ixfr-fslimit::
-* dnssec-keydir::
-* dnssec-enable::
-* signature-lifetime::
-* serial-policy::
-@end menu
-
-@node zone_id
-@subsubsection @kbd{zone_id}
-@vindex zone_id
-
-@code{zone_id} is a zone origin, and as such is a domain name that may or may not end with a ".".
-If no $ORIGIN directive is found inside actual zone file, this domain name will be used in place of "@@".
-SOA record in the zone must have this name as its owner.
-
-@node file
-@subsubsection file
-@vindex file
-
-The @code{file} statement defines a path to the zone file.
-You can either use an absolute path or a relative path.
-In that case, the zone file path will be relative to the @code{storage} directory (@pxref{storage}).
-
-@node xfr-in
-@subsubsection xfr-in
-@vindex xfr-in
-
-In @code{xfr-in} statement user specifies which remotes will be permitted to perform a zone transfer to update the zone.
-Remotes are defined in @code{remotes} section of configuration file (@pxref{remotes}).
-
-@node xfr-out
-@subsubsection xfr-out
-@vindex xfr-out
-
-In @code{xfr-out} statement user specifies which remotes will be permitted to obtain zone's contents via zone transfer.
-Remotes are defined in @code{remotes} section of configuration file (@pxref{remotes}).
-
-@node notify-in
-@subsubsection notify-in
-@vindex notify-in
-
-@code{notify-in} defines which remotes will be permitted to send NOTIFY for this particular zone.
-
-@node notify-out
-@subsubsection notify-out
-@vindex notify-out
-
-@code{notify-out} defines to which remotes will your server send NOTIFYs about this particular zone.
-
-@node update-in
-@subsubsection update-in
-@vindex update-in
-
-In @code{update-in} statement user specifies which remotes will be permitted to perform a DNS UPDATE.
-Remotes are defined in @code{remotes} section of configuration file (@pxref{remotes}).
-
-@node query_module
-@subsubsection query_module
-@vindex query_module
-
-Statement @code{query_module} takes a list of @code{module_name "config_string"} query modules separated
-by semicolon.
-
-@node storage
-@subsubsection storage
-@vindex storage
-
-Data directory for zones. It is used to store zone files and journal files.
-
-Value of @code{storage} set in @code{zone} section is relative to @code{storage} in @code{zones} section.
-
-Default value (in @code{zones} section): @file{$@{localstatedir@}/lib/knot}, configured with @code{--with-storage=path}
-
-Default value (in @code{zone} config): inherited from @code{zones} section
-
-@example
-zones @{
- storage "/var/lib/knot";
- example.com @{
- storage "com";
- file "example.com"; # /var/lib/knot/com/example.com
- @}
-@}
-@end example
-
-@node semantic-checks
-@subsubsection semantic-checks
-@vindex semantic-checks
-
-@code{semantic-checks} statement turns on optional semantic checks for this particular zone.
-See @ref{zones List of zone semantic checks} for more information.
-
-Possible values are @code{on} and @code{off}.
-Most checks are disabled by default.
-
-@node ixfr-from-differences
-@subsubsection ixfr-from-differences
-@vindex ixfr-from-differences
-
-Option @code{ixfr-from-differences} is only relevant if you are running Knot DNS as a master for this zone.
-By turning the feature on you tell Knot to create differences from changes you made to a zone file upon server reload.
-See @ref{Controlling running daemon} for more information.
-
-Possible values are @code{on} and @code{off}. Disabled by default.
-
-@node disable-any
-@subsubsection disable-any
-@vindex disable-any
-
-If you enable @code{disable-any}, all authoritative ANY queries sent over UDP will be answered with an empty response and with the TC bit set.
-Use to minimize the risk of DNS replay attack. Disabled by default.
-
-@node notify-timeout
-@subsubsection notify-timeout
-@vindex notify-timeout
-
-@code{notify-timeout} in seconds specifies how long will server wait for NOTIFY response. Possible values are 1 to INT_MAX.
-By default, this value is set to 60 seconds.
-
-@node notify-retries
-@subsubsection notify-retries
-@vindex notify-retries
-
-@code{notify-retries} tells the server how many times it can retry to send a NOTIFY. Possible values
-are 1 to INT_MAX and default value is 5.
-
-@node zonefile-sync
-@subsubsection zonefile-sync
-@vindex zonefile-sync
-
-@code{zonefile-sync} specifies a time in seconds after which current zone in memory will be synced to zone file on the disk (as set in @ref{file}). Knot DNS will serve the latest zone even after restart, but zone file on a disk will only be synced after @code{zonefile-sync} time has expired (or synced manually via @code{knotc flush} - see @ref{Running Knot DNS}). This is applicable when the zone is updated via IXFR, DDNS or automatic DNSSEC signing. Possible values are 0 to INT_MAX, optionally suffixed by unit size (s/m/h/d) - @emph{1s} is one second, @emph{1m} one minute, @emph{1h} one hour and @emph{1d} one day with default value set to @emph{0s}.
-
-@b{Important note:} If you are serving large zones with frequent updates where the immediate sync to zone file is not desirable, set this value in the configuration file to other value.
-
-@node ixfr-fslimit
-@subsubsection ixfr-fslimit
-@vindex ixfr-fslimit
-
-@code{ixfr-fslimit} sets a maximum file size for zone's journal in bytes. Possible values are 1 to INT_MAX, with optional suffixes k, m and G. I.e. @emph{1k}, @emph{1m} and @emph{1G} with default value not being set, meaning that journal file can grow without limitations.
-
-@node dnssec-keydir
-@subsubsection dnssec-keydir
-@vindex dnssec-keydir
-
-Location of DNSSEC signing keys, relative to @code{storage}.
-
-Default value: not set
-
-@node dnssec-enable
-@subsubsection dnssec-enable
-@vindex dnssec-enable
-
-PREVIEW: Enable automatic DNSSEC signing for the zone.
-
-Default value (in @code{zones} section): off
-
-Default value (in @code{zone} config): inherited from @code{zones} section
-
-@node signature-lifetime
-@subsubsection signature-lifetime
-@vindex signature-lifetime
-
-Specifies how long should the automatically generated DNSSEC signatures be valid.
-Expiration will thus be set as current time (in the moment of signing)
-+ @code{signature-lifetime}.
-Possible values are from 10801 to INT_MAX. The signatures are refreshed one
-tenth of the signature lifetime before the signature expiration (i.e., 3 days
-before the expiration with the default value). For information about zone
-expiration date, invoke the
-@code{knotc zonestatus} command.
-
-Default value: @kbd{30d} (@kbd{2592000})
-
-@node serial-policy
-@subsubsection serial-policy
-@vindex serial-policy
-
-Specifies how the zone serial is updated after DDNS (dynamic update) and
-automatic DNSSEC signing. If the serial is changed by the dynamic update, no
-change is made.
-
-increment - After update or signing, the serial is automatically incremented
-(according to serial number arithmetic).
-
-unixtime - After update or signing, serial is set to the current unix time.
-
-@strong{Warning:} If your serial was in other than unix time format, be careful with
-transition to unix time. It may happen that the new serial will be 'lower' than
-the old one. If this is the case, the transition should be done by hand (consult:
- http://www.zytrax.com/books/dns/ch9/serial.html).
-
-Default value: increment
-
-@node zones Example
-@subsection zones Example
-
-@example
-@group
-zones @{
-
- # Shared options for all listed zones
- storage "/var/lib/knot";
- ixfr-from-differences off;
- semantic-checks off;
- disable-any off;
- notify-timeout 60;
- notify-retries 5;
- zonefile-sync 0;
- ixfr-fslimit 1G;
- dnssec-enable on;
- dnssec-keydir "keys";
- signature-lifetime 60d;
- serial-policy increment;
- example.com @{
- storage "samples";
- file "example.com.zone";
- ixfr-from-differences off;
- disable-any off;
- semantic-checks on;
- notify-timeout 60;
- notify-retries 5;
- zonefile-sync 0;
- dnssec-keydir "keys";
- dnssec-enable off;
- signature-lifetime 30d;
- serial-policy increment;
- xfr-in server0;
- xfr-out server0, server1;
- notify-in server0;
- notify-out server0, server1;
- @}
-@}
-
-@end group
-@end example
-
-@node zones List of zone semantic checks
-@subsection List of zone semantic checks
-
-The @code{semantic-checks} statement turns on extra zone file semantic
-checks. Several checks are enabled by default and cannot be turned
-off. If an error is found using these mandatory checks, the zone file
-will not be loaded. Upon loading a zone file, occurred
-errors and counts of their occurrence will be logged to @emph{stderr}.
-These checks are the following:
-
-@example
-- An extra record together with CNAME record (except for RRSIG and DS)
-- CNAME link chain length greater than 10 (including infinite cycles)
-- DNAME and CNAME records under the same owner (RFC 2672)
-- CNAME and DNAME wildcards pointing to themselves
-- SOA record missing in the zone (RFC 1034)
-- DNAME records having records under it (DNAME children) (RFC 2672)
-@end example
-
-Following checks have to be turned on using @code{semantic-checks} and
-a zone containing following errors will be
-loaded even upon discovering an error:
-
-@example
-- Missing NS record at the zone apex
-- Missing glue A or AAAA records
-- Broken or non-cyclic NSEC(3) chain
-- Wrong NSEC(3) type bitmap
-- Multiple NSEC records at the same node
-- Missing NSEC records at authoritative nodes
-- Extra record types under same name as NSEC3 record
-(this is RFC-valid, but Knot will not serve such a zone correctly)
-- NSEC3-unsecured delegation that is not part of Opt-out span
-- Wrong original TTL value in NSEC3 records
-- Wrong RDATA TTL value in RRSIG record
-- Signer name in RRSIG RR not the same as in DNSKEY
-- Signed RRSIG
-- Not all RRs in node are signed
-- Wrong key flags or wrong key in RRSIG record (not the same as ZSK)
-@end example
-
-@node log
-@section @code{log} Statement
-@stindex log
-
-@menu
-* log Syntax::
-* log Statement Definition and Grammar::
-* log Example::
-@end menu
-
-@node log Syntax
-@subsection Syntax
-
-@example
-@code{log} @code{@{}
- [ @kbd{log_name} @code{@{}
- [ @kbd{category} @kbd{severity} [, @kbd{severity} @dots{} ]@code{;} ]
- @code{@}} ]
- [ @code{log_file} @kbd{filename} @{
- [ @kbd{category} @kbd{severity} [, @kbd{severity} @dots{} ]@code{;} ]
- @} ]
-@code{@}}
-
-@end example
-
-@node log Statement Definition and Grammar
-@subsection Statement Definition and Grammar
-
-@menu
-* log_name::
-* category::
-* severity::
-* log_file::
-@end menu
-
-The @code{log} statement configures logging output of Knot DNS. You
-can configure Knot DNS to log into file or system log. There are several
-logging categories to choose from. Each log
-message has its severity and user can configure severities for each
-log destination.
-
-In case of missing log section, severities from @kbd{warning} and more serious
-will be logged to both @kbd{stderr} and @kbd{syslog}. The @kbd{info} and @kbd{notice}
-severities will be logged to the @kbd{stdout}.
-
-@node log_name
-@subsubsection @kbd{log_name}
-@vindex @kbd{log_name}
-
-@kbd{log_name} should be replaced with one of 3 symbolic log names :
-@itemize
-@item @emph{stdout} - logging to standard output
-@item @emph{stderr} - logging to standard error output
-@item @emph{syslog} - logging to syslog
-@end itemize
-
-@node category
-@subsubsection @kbd{category}
-@vindex category
-
-Knot DNS allows user to choose from these logging categories:
-
-@itemize
-@item @emph{server} - Messages related to general operation of the server.
-@item @emph{zone} - Messages related to zones, zone parsing and loading.
-@item @emph{answering} - Messages regarding query processing and response creation.
-@item @emph{any} - All categories.
-@end itemize
-
-@node severity
-@subsubsection @kbd{severity}
-@vindex severity
-
-Knot DNS has the following logging severities:
-@itemize
-@item @emph{debug} - Debug messages, must be turned on at compile time (@pxref{Enabling debug messages in server}).
-@item @emph{info} - Informational message.
-@item @emph{notice} - Server notices and hints.
-@item @emph{warning} - Warnings that might require user action.
-@item @emph{error} - Recoverable error. Action should be taken.
-@item @emph{all} - All severities.
-@end itemize
-
-More severities may be listed for each category, but all severities have to be listed explicitly, i.e. using @emph{warning} severity does not mean that @emph{error} severity messages will be logged as well.
-
-@node log_file
-@subsubsection @kbd{log_file}
-@vindex @kbd{log_file}
-
-@kbd{log_file} is either absolute or relative path to file user wants to log to.
-See following example for clarification.
-
-@node log Example
-@subsection log Example
-
-@example
-
-log @{
-
- syslog @{
- any error;
- zone warning, notice;
- server info;
- @}
-
- stderr @{
- any error, warning;
- @}
-
- file "/tmp/knot-sample/knotd.debug" @{
- server debug;
- @}
-@}
-
-@end example
-
-@node include
-@section @code{include} Statement
-@stindex include
-
-The @code{include} statement is a special statement which can be used almost
-anywhere on any level in the configuration file. It allows inclusion of another
-file or all files in the given directory.
-
-The path of the included file can be either absolute or relative to a
-configuration file currently being processed.
-
-@menu
-* include Syntax::
-* include Examples::
-@end menu
-
-@node include Syntax
-@subsection Syntax
-
-@example
-@code{include} "filename"@code{;}
-@code{include} "dirname"@code{;}
-@end example
-
-@node include Examples
-@subsection Examples
-
-@example
-include "keys.conf";
-
-remotes @{
- ctl @{
- address 127.0.0.1;
- key knotc-key;
- @}
- include "remotes.conf";
-@}
-
-include "zones";
-@end example
diff --git a/doc/requirements.texi b/doc/requirements.texi
deleted file mode 100644
index 6bebf04c35a4fb617956e326f6579ee19089360f..0000000000000000000000000000000000000000
--- a/doc/requirements.texi
+++ /dev/null
@@ -1,52 +0,0 @@
-@node Knot DNS Resource Requirements, Knot DNS Installation, Introduction, Top
-@chapter Knot DNS Resource Requirements
-
-@menu
-* Hardware requirements::
-* CPU requirements::
-* Memory requirements::
-* Supported operating system::
-@end menu
-
-@node Hardware requirements
-@section Hardware requirements
-
-Knot DNS requirements are not very demanding for typical
-installations, and a commodity server or a virtual solution
-will be sufficient in most cases.
-
-However please note that there are some scenarios that will
-require administrator attention and testing of exact
-requirements before deploying Knot DNS in production. These
-cases include deployment for a large number of zones (DNS
-hosting), a large number of records in one or more zones (TLD)
-or large number of requests.
-
-@node CPU requirements
-@section CPU requirements
-
-Knot DNS scales with processing power and also with the number of available cores/CPUs.
-
-There is no lower bound on the CPU requirements, but it should support memory barriers
-and CAS (i586 and newer).
-
-@node Memory requirements
-@section Memory requirements
-
-Knot DNS implementation focuses on performance and thus can
-be quite demanding for memory. The rough estimate for memory
-requirements is 5-7 times of the size of the zone in text
-format. Again this is only an estimate and you are advised to do
-your own measurements before deploying Knot DNS into production.
-
-Also note that to ensure uninterrupted serving of the zone, Knot DNS employs
-a Read-Copy-Update mechanism instead of locking and thus requires
-twice the amount of memory for the duration of incoming transfers.
-
-@node Supported operating system
-@section Supported operating system
-
-Knot DNS itself is written in a portable way, but it depends on
-several libraries. Namely userspace-rcu, which could be a constraint when it
-comes to the operating system support. As far as we know the
-Knot DNS can be compiled and run on Linux, FreeBSD, OpenBSD, NetBSD and Mac OS X.
diff --git a/doc/running.rst b/doc/running.rst
index baaa3c972c8544ef55af640b4e75f0ee6c05b766..69097a06b56f28d23ebdf8a038e5aef6bb33f705 100644
--- a/doc/running.rst
+++ b/doc/running.rst
@@ -1,8 +1,10 @@
+.. _Running Knot DNS:
+
****************
Running Knot DNS
****************
-Knot DNS can run either in the foreground or in a background, with the @code{-d}
+Knot DNS can run either in the foreground or in a background, with the ``-d``
option. When run in foreground, it doesn't create a PID file. Other than that,
there are no differences and you can control it just the same way.
@@ -26,4 +28,137 @@ with the server much more user friendly.
$ knotc -c knot.conf reload
-TODO
+The tool ``knotc`` is designed as a front-end for user, making it easier to control running server daemon.
+If you want to control the daemon directly, use ``SIGINT`` to quit the process or ``SIGHUP`` to reload configuration.
+
+::
+
+ Usage: knotc [parameters] <action> [action_args]
+
+ Parameters:
+ -c, --config <file> Select configuration file.
+ -s <server> Remote UNIX socket/IP address (default
+ ${rundir}/knot.sock).
+ -p <port> Remote server port (only for IP).
+ -y <[hmac:]name:key> Use key specified on the command line
+ (default algorithm is hmac-md5).
+ -k <file> Use key file (as in config section 'keys').
+ -f, --force Force operation - override some checks.
+ -v, --verbose Verbose mode - additional runtime information.
+ -V, --version Print knot server version.
+ -i, --interactive Interactive mode (do not daemonize).
+ -h, --help Print help and usage.
+
+ Actions:
+ stop Stop server.
+ reload Reload configuration and changed zones.
+ refresh [zone] Refresh slave zone (all if not specified).
+ flush Flush journal and update zone files.
+ status Check if server is running.
+ zonestatus Show status of configured zones.
+ checkconf Check current server configuration.
+ checkzone [zone] Check zone (all if not specified).
+ memstats [zone] Estimate memory consumption for zone (all if not
+ specified).
+
+Also, the server needs to create several files in order to run properly. These
+files are stored in the folowing directories.
+
+``storage`` (:ref:`storage`):
+
+* *Zone files* - default directory for storing zone files. This can be
+ overriden using absolute zone file location.
+
+* *Journal files* - each zone has a journal file to store differences
+ for IXFR and dynamic updates. Journal for zone ``example.com`` will
+ be placed in ``example.com.diff.db``.
+
+``rundir`` (:ref:`rundir`):
+
+* *PID file* - is created automatically when the server is run in background.
+
+* *Control sockets* - as a default, UNIX sockets are created here, but
+ this can be overriden.
+
+.. _Running a slave server:
+
+Running a slave server
+======================
+
+Running the server as a slave is very straightforward as you usually
+bootstrap zones over AXFR and thus avoid any manual zone compilation.
+In contrast to AXFR, when the incremental transfer finishes, it stores
+the differences in a journal file and doesn't update the zone file
+immediately. There is a timer that checks periodically for new
+differences and updates the zone file. You can configure this timer
+with the ``zonefile-sync`` statement in ``zones`` (:ref:`zones`).
+
+There are two ways to start the server - in foreground or background.
+First, let's start in foreground. If you do not pass any configuration, it will try to
+search configuration in default path that is ``SYSCONFDIR/knot.conf``. The ``SYSCONFDIR``
+depends on what you passed to the ``./configure``, usually ``/etc``.
+
+::
+
+ $ knotd -c slave.conf
+
+To start it as a daemon, just add a ``-d`` parameter. Unlike the foreground mode,
+PID file will be created in ``rundir`` directory.
+
+ $ knotd -d -c slave.conf # start the daemon
+ $ knotc -c slave.conf stop # stop the daemon
+
+When the server is running, you can control the daemon, see :ref:`Controlling running daemon`.
+
+.. _Running a master server:
+
+Running a master server
+=======================
+
+If you want to just check the zone files first before starting, you
+can use ``knotc checkzone`` action::
+
+ $ knotc -c master.conf checkzone example.com
+
+For an approximate estimate of server's memory consumption, you can
+use the ``knotc memstats`` action. This action prints count of
+resource records, percentage of signed records and finally estimation
+of memory consumption for each zone, unless specified
+otherwise. Please note that estimated values might differ from the
+actual consumption. Also, for slave servers with incoming transfers
+enabled, be aware that the actual memory consumption might be double
+or more during transfers.
+
+::
+
+ $ knotc -c master.conf memstats example.com
+
+Starting and stopping the daemon is the same as with the slave server in the previous section.
+
+.. _Controlling running daemon:
+
+Controlling running daemon
+==========================
+
+Knot DNS was designed to allow server reconfiguration on-the-fly
+without interrupting its operation. Thus it is possible to change
+both configuration and zone files and also add or remove zones without
+restarting the server. This can be done with the ``knotc reload``
+action.
+
+::
+
+ $ knotc -c master.conf reload # reconfigure and load updated zones
+
+If you want *IXFR-out* differences created from changes you make to a
+zone file, enable :ref:`ixfr-from-differences` in ``zones`` statement,
+then reload your server as seen above. If *SOA*'s *serial* is not
+changed no differences will be created.
+
+If you want to force refresh the slave zones, you can do this with the
+``knotc refresh`` action::
+
+ $ knotc -c slave.conf refresh
+
+For a complete list of actions refer to ``knotc --help`` command
+output.
diff --git a/doc/running.texi b/doc/running.texi
deleted file mode 100644
index 92ac46221741bd203e9f0fb5c34f72727f6a7f10..0000000000000000000000000000000000000000
--- a/doc/running.texi
+++ /dev/null
@@ -1,163 +0,0 @@
-@node Running Knot DNS, Troubleshooting, Knot DNS Configuration, Top
-@chapter Running Knot DNS
-
-@menu
-* Running a slave server::
-* Running a master server::
-* Controlling running daemon::
-@end menu
-
-Knot DNS can run either in the foreground or in a background, with the @code{-d}
-option. When run in foreground, it doesn't create a PID file. Other than that,
-there are no differences and you can control it just the same way.
-@example
-Usage: knotd [parameters]
-
-Parameters:
- -c, --config <file> Select configuration file.
- -d, --daemonize=[dir] Run server as a daemon. Working directory may
- be set.
- -v, --verbose Verbose mode - additional runtime information.
- -V, --version Print version of the server.
- -h, --help Print help and usage.
-@end example
-
-Use knotc tool for convenience when working with the server daemon.
-As of Knot DNS 1.3.0, the zones are not compiled anymore. That makes working
-with the server much more user friendly.
-@example
-$ knotc -c knot.conf reload
-@end example
-
-The tool @code{knotc} is designed as a front-end for user, making it easier to control running server daemon.
-If you want to control the daemon directly, use @code{SIGINT} to quit the process or @code{SIGHUP} to reload configuration.
-
-@example
-Usage: knotc [parameters] <action> [action_args]
-
-Parameters:
- -c, --config <file> Select configuration file.
- -s <server> Remote UNIX socket/IP address (default
- $@{rundir@}/knot.sock).
- -p <port> Remote server port (only for IP).
- -y <[hmac:]name:key> Use key specified on the command line
- (default algorithm is hmac-md5).
- -k <file> Use key file (as in config section 'keys').
- -f, --force Force operation - override some checks.
- -v, --verbose Verbose mode - additional runtime information.
- -V, --version Print knot server version.
- -i, --interactive Interactive mode (do not daemonize).
- -h, --help Print help and usage.
-
-Actions:
- stop Stop server.
- reload Reload configuration and changed zones.
- refresh [zone] Refresh slave zone (all if not specified).
- flush Flush journal and update zone files.
- status Check if server is running.
- zonestatus Show status of configured zones.
- checkconf Check current server configuration.
- checkzone [zone] Check zone (all if not specified).
- memstats [zone] Estimate memory consumption for zone (all if not
- specified).
-@end example
-
-Also, the server needs to create several files in order to run properly. These
-files are stored in the folowing directories.
-
-@code{storage} (@pxref{storage}):
-
-@itemize @bullet
-@item
-@emph{Zone files} - default directory for storing zone files. This can be overriden
-using absolute zone file location.
-
-@item
-@emph{Journal files} - each zone has a journal file to store differences for IXFR and
-dynamic updates. Journal for zone @code{example.com} will be placed in @file{example.com.diff.db}.
-@end itemize
-
-@code{rundir} (@pxref{rundir}):
-
-@itemize @bullet
-@item
-@emph{PID file} - is created automatically when the server is run in background.
-
-@item
-@emph{Control sockets} - as a default, UNIX sockets are created here,
-but this can be overriden.
-@end itemize
-
-@node Running a slave server
-@section Running a slave server
-
-Running the server as a slave is very straightforward as you usually bootstrap
-zones over AXFR and thus avoid any manual zone compilation.
-In contrast to AXFR, when the incremental transfer finishes, it stores the differences in a journal file
-and doesn't update the zone file immediately.
-There is a timer that checks periodically for new differences and
-updates the zone file. You can configure this timer
-with the @code{zonefile-sync} statement in @code{zones} (@pxref{zones}).
-
-There are two ways to start the server - in foreground or background.
-First, let's start in foreground. If you do not pass any configuration, it will try to
-search configuration in default path that is @code{SYSCONFDIR/knot.conf}. The @code{SYSCONFDIR}
-depends on what you passed to the @code{./configure}, usually @code{/etc}.
-
-@example
-$ knotd -c slave.conf
-@end example
-
-To start it as a daemon, just add a @code{-d} parameter. Unlike the foreground mode,
-PID file will be created in @code{rundir} directory.
-
-@example
-$ knotd -d -c slave.conf # start the daemon
-$ knotc -c slave.conf stop # stop the daemon
-@end example
-
-When the server is running, you can control the daemon, see @ref{Controlling running daemon}.
-
-@node Running a master server
-@section Running a master server
-
-If you want to just check the zone files first before starting,
-you can use @code{knotc checkzone} action.
-@example
-$ knotc -c master.conf checkzone example.com
-@end example
-
-For an approximate estimate of server's memory consumption, you can use the @code{knotc memstats} action.
-This action prints count of resource records, percentage of signed records and finally estimation
-of memory consumption for each zone, unless specified otherwise. Please note that estimated values might
-differ from the actual consumption. Also, for slave servers with incoming transfers enabled,
-be aware that the actual memory consumption might be double or more during transfers.
-
-@example
-$ knotc -c master.conf memstats example.com
-@end example
-
-Starting and stopping the daemon is the same as with the slave server in the previous section.
-
-@node Controlling running daemon
-@section Controlling running daemon
-
-Knot DNS was designed to allow server reconfiguration on-the-fly without interrupting
-its operation. Thus it is possible to change both configuration and zone files and
-also add or remove zones without restarting the server. This can be done with the
-@code{knotc reload} action.
-
-@example
-$ knotc -c master.conf reload # reconfigure and load updated zones
-@end example
-
-If you want @emph{IXFR-out} differences created from changes you make to a zone file, enable @ref{ixfr-from-differences}
-in @code{zones} statement, then reload your server as seen above.
-If @emph{SOA}'s @emph{serial} is not changed no differences will be created.
-
-If you want to force refresh the slave zones, you can do this with the @code{knotc refresh} action.
-@example
-$ knotc -c slave.conf refresh
-@end example
-
-For a complete list of actions refer to @code{knotc --help} command output.
diff --git a/doc/security.texi b/doc/security.texi
deleted file mode 100644
index 37165215ccd96c0581b343a13308d3325fcf2805..0000000000000000000000000000000000000000
--- a/doc/security.texi
+++ /dev/null
@@ -1,15 +0,0 @@
-@node Security Considerations, Troubleshooting, Running Knot DNS, Top
-@chapter Security Considerations
-
-[TODO]
-- faces the internet
-
-If libcap-ng is available, Knot DNS on Linux takes advantage of
-the POSIX 1003.1e capabilities. This mechanism breaks the a set of privileges
-traditionally associated with the root into groups that can be set per-thread
-and independently enabled or disabled. For more information, look up manual page
-for capabilities(7).
-
-Knot DNS uses strips exposed threads of most capabilities like file access,
-privileged socket operations and such.
-This mitigates potential remote exploits or at least the impact.
diff --git a/doc/synth_record.texi b/doc/synth_record.texi
deleted file mode 100644
index 5251ae2d979b6400ef695e9e82974f964d9f620f..0000000000000000000000000000000000000000
--- a/doc/synth_record.texi
+++ /dev/null
@@ -1,84 +0,0 @@
-@subsection @code{synth_record} - Automatic forward/reverse records
-
-This module is able to synthetise either forward or reverse records for given prefix and subnet.
-The module configuration string looks like this: @code{(forward|reverse) <prefix> <ttl> <address>/<netblock>}.
-
-Records are synthetised only if the query can't be satisfied from the zone. Both IPv4 and IPv6 are supported.
-@emph{Note: 'prefix' doesn't allow dots, address parts in the synthetic names are separated with a dash.}
-
-Here are a few examples:
-@emph{Note: long names are snipped for readability.}
-
-@subsubsection Automatic forward records
-
-@code{synth_record "forward dynamic- 400 2620:0:b61::/52"} on @code{example.} zone will result in following
-answer.
-@example
-$ kdig AAAA dynamic-2620-0000-0b61-0100-0000-0000-0000-0000.example.
-...
-;; QUESTION SECTION:
-;; dynamic-2620-0000-0b61-0100-0000-0000-0000-0000.example. 0 IN AAAA
-
-;; ANSWER SECTION:
-dynamic-2620-0000-0b61-0100... 400 IN AAAA 2620:0:b61:100::
-@end example
-
-You can also have CNAME aliases to the dynamic records, which are going to be further resoluted.
-@example
-$ kdig AAAA hostalias.example.
-...
-;; QUESTION SECTION:
-;hostalias.example. 0 IN AAAA
-
-;; ANSWER SECTION:
-hostalias.example. 3600 IN CNAME dynamic-2620-0000-0b61-0100...
-dynamic-2620-0000-0b61-0100... 400 IN AAAA 2620:0:b61:100::
-@end example
-
-@subsubsection Automatic reverse records
-
-Module can be configured to synthetise reverse records as well.
-With the @code{synth_record "reverse dynamic- example. 400 2620:0:b61::/52"} string in the
-@code{1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa.} zone configuration:
-@example
-$ kdig PTR 1.0.0...1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa.
-...
-;; QUESTION SECTION:
-;; 1.0.0...1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa. 0 IN PTR
-
-;; ANSWER SECTION:
-... 400 IN PTR dynamic-2620-0000-0b61-0000-0000-0000-0000-0001.example.
-@end example
-
-
-
-Here's a full configuration of the aforementioned zones. Note that the zone files have to exist.
-@example
-example. @{
- query_module @{
- synth_record "forward dynamic- 400 2620:0:b61::/52";
- synth_record "forward dynamic- 400 192.168.1.0/25";
- @}
-@}
-1.168.192.in-addr.arpa @{
- query_module @{
- synth_record "reverse dynamic- example. 400 192.168.1.0/25";
- @}
-@}
-1.6.b.0.0.0.0.0.0.2.6.2.ip6.arpa @{
- query_module @{
- synth_record "reverse dynamic- example. 400 2620:0:b61::/52";
- @}
-@}
-@end example
-
-@subsubsection Limitations
-
-@itemize @bullet
-
-@item
-As of now, there is no authenticated denial of nonexistence (neither NSEC or NSEC3 is supported) nor DNSSEC signed records.
-However, since the module is hooked in the query processing plan,
-it will be possible to do online signing in the future.
-
-@end itemize
diff --git a/doc/troubleshooting.rst b/doc/troubleshooting.rst
index dc8162a58d97b031f0dfee75a7b02c2441f71bc1..05f36baab90d312fa4014c41c3b53f0f52020ec6 100644
--- a/doc/troubleshooting.rst
+++ b/doc/troubleshooting.rst
@@ -2,4 +2,118 @@
Troubleshooting
***************
-TODO
+First of all, check the logs (:ref:`log`). By default, Knot DNS logs
+all error messages to syslog. Enabling at least the ``warning``
+message severity may help you identify some problems.
+
+.. _Submitting a bugreport:
+
+Submitting a bugreport
+======================
+
+If you are unable to solve the problem by yourselves, you can submit a
+bugreport to the Knot DNS team. For security issues (e.g. crash) do
+not use the public mailinglist. Instead, write to
+`knot-dns@labs.nic.cz <mailto:knot-dns@@labs.nic.cz>`. All other bugs
+and questions may be directed to the Knot DNS users mailinglist
+(`knot-dns-users@lists.nic.cz <mailto:knot-dns-users@lists.nic.cz>`).
+
+The bugreport should contain at least:
+
+* Knot DNS version and type of installation (source, package, etc.),
+* type and version of your operating system,
+* basic hardware information,
+* description of the bug,
+* log output of all messages (category ``any``) with severity Info and
+ higher (severities ``info, notice, warning, error``, or ``any`` if
+ debug messages are not turned on (see below)),
+* steps to reproduce the bug (if known),
+* backtrace (if the bug caused a crash; see next section).
+
+If it is possible, the actual configuration file and/or zone file(s)
+will be very useful as well.
+
+.. _Generating backtrace:
+
+Generating backtrace
+====================
+
+There are several ways to achieve that, the most common way is to
+leave core dumps and then extract a backtrace from it. This doesn't
+affect any server operation, you just need to make sure the OS is
+configured to generate them.
+
+::
+ $ ulimit -c unlimited # enable unlimited core dump size
+ ...
+ $ gdb $(which knotd) core.<KNOT_PID> # start gdb on a core dump
+ (gdb) thread apply all bt # extract backtrace from all threads
+ (gdb) q
+
+If the error is repeatable, you can run the binary in a ``gdb``
+debugger or attach the debugger to the running process. The backtrace
+from a running process is generally useful when debugging problems
+like stuck process and similar.
+
+::
+ $ knotc -c knot.conf start
+ $ sudo gdb --pid <KNOT_PID>
+ (gdb) continue
+ ...
+ (gdb) thread apply all bt
+ (gdb) q
+
+.. _Debug messages:
+
+Debug messages
+==============
+
+In some cases the aforementioned information may not be enough to find
+and fix the bug. In these cases it may be useful to turn on debug
+messages.
+
+Two steps are required in order to log debug messages. First you need
+to allow the debug messages in the server. Then the logging must be
+configured to log debug messages (:ref:`log`). It is recommended to
+log these messages to a file. Firstly, the debug output may be rather
+large and secondly, it is easier to use the data for debugging.
+
+.. _Enabling debug messages in server:
+
+Enabling debug messages in server
+---------------------------------
+
+Allowing debug messages in the server is possible only when
+configuring the sources. Two ``configure`` options are required
+to do this:
+
+* The ``--enable-debug`` option specifies the server modules for which
+ you want to enable debug messages. One or more of the following
+ modules may be listed, separated by commas:
+
+ * ``server`` - Messages related to networking, threads and low-level
+ journal handling.
+ * ``zones`` - All operations with zones - loading, updating, saving,
+ timers, high-level journal management.
+ * ``xfr`` - AXFR, IXFR and NOTIFY handling.
+ * ``packet`` - Packet parsing and response creation.
+ * ``rr`` - Details of processed resource records.
+ * ``ns`` - Query processing, high-level handling of all requests
+ (transfers, NOTIFY, normal queries).
+ * ``loader`` - Zone loading and semantic checks.
+ * ``dnssec`` - DNSSEC operations.
+
+* The ``--enable-debuglevel`` option is used to specify the verbosity
+ of the debug output. Be careful with this, as the ``details``
+ verbosity may produce really large logs (in order of GBs). There are
+ three levels of verbosity: ``brief``, ``verbose`` and ``details``.
+
+.. _Debug messages Example:
+
+Debug messages Example
+----------------------
+
+::
+
+ $ ./configure --enable-debug=server,zones --enable-debuglevel=verbose
+
diff --git a/doc/troubleshooting.texi b/doc/troubleshooting.texi
deleted file mode 100644
index ddd65a35f18db0909f3190f1d850179da3812a31..0000000000000000000000000000000000000000
--- a/doc/troubleshooting.texi
+++ /dev/null
@@ -1,128 +0,0 @@
-@node Troubleshooting, Statement Index, Running Knot DNS, Top
-@chapter Troubleshooting
-
-@menu
-* Submitting a bugreport::
-* Generating backtrace::
-* Debug messages::
-@end menu
-
-First of all, check the logs (@pxref{log}).
-By default, Knot DNS logs all error messages to syslog. Enabling at least
-the @code{warning} message severity may help you identify some problems.
-
-@node Submitting a bugreport
-@section Submitting a bugreport
-
-If you are unable to solve the problem by yourselves, you can submit a
-bugreport to the Knot DNS team. For security issues (e.g. crash) do not
-use the public mailinglist. Instead, write to
-@url{mailto:knot-dns@@labs.nic.cz, knot-dns@@labs.nic.cz}. All other bugs
-and questions may be directed to the Knot DNS users mailinglist
-(@url{mailto:knot-dns-users@@lists.nic.cz, knot-dns-users@@lists.nic.cz}).
-
-The bugreport should contain at least:
-@itemize
-@item Knot DNS version and type of installation (source, package, etc.),
-@item type and version of your operating system,
-@item basic hardware information,
-@item description of the bug,
-@item log output of all messages (category @code{any}) with severity Info
-and higher (severities @code{info, notice, warning, error}, or @code{any} if debug messages are not turned on (see below)),
-@item steps to reproduce the bug (if known),
-@item backtrace (if the bug caused a crash; see next section).
-@end itemize
-
-If it is possible, the actual configuration file and/or zone file(s) will
-be very useful as well.
-
-@node Generating backtrace
-@section Generating backtrace
-
-There are several ways to achieve that, the most common way is to leave core
-dumps and then extract a backtrace from it.
-This doesn't affect any server operation, you just need to make sure
-the OS is configured to generate them.
-
-@example
-$ ulimit -c unlimited # enable unlimited core dump size
-...
-$ gdb $(which knotd) core.<KNOT_PID> # start gdb on a core dump
-(gdb) thread apply all bt # extract backtrace from all threads
-(gdb) q
-@end example
-
-If the error is repeatable, you can run the binary in a @code{gdb} debugger
-or attach the debugger to the running process. The backtrace from a running
-process is generally useful when debugging problems like stuck process and similar.
-@example
-$ knotc -c knot.conf start
-$ sudo gdb --pid <KNOT_PID>
-(gdb) continue
-...
-(gdb) thread apply all bt
-(gdb) q
-@end example
-
-
-
-@node Debug messages
-@section Debug messages
-
-@menu
-* Enabling debug messages in server::
-@end menu
-
-In some cases the aforementioned information may not be enough to find
-and fix the bug. In these cases it may be useful to turn on debug messages.
-
-Two steps are required in order to log debug messages. First you need to
-allow the debug messages in the server. Then the logging must be configured
-to log debug messages (@pxref{log}). It is recommended to log these
-messages to a file. Firstly, the debug output may be rather large and
-secondly, it is easier to use the data for debugging.
-
-@node Enabling debug messages in server
-@subsection Enabling debug messages in server
-
-@menu
-* Debug messages Example::
-@end menu
-
-Allowing debug messages in the server is possible only when configuring the
-sources. Two @command{configure} options are required to do this:
-
-@itemize
-@item
-The @code{--enable-debug} option specifies the server modules for which you
-want to enable debug messages. One or more of the following modules may be
-listed, separated by commas:
-
-@itemize
-@item @code{server} - Messages related to networking, threads and low-level
- journal handling.
-@item @code{zones} - All operations with zones - loading, updating, saving,
- timers, high-level journal management.
-@item @code{xfr} - AXFR, IXFR and NOTIFY handling.
-@item @code{packet} - Packet parsing and response creation.
-@item @code{rr} - Details of processed resource records.
-@item @code{ns} - Query processing, high-level handling of all requests
- (transfers, NOTIFY, normal queries).
-@item @code{loader} - Zone loading and semantic checks.
-@item @code{dnssec} - DNSSEC operations.
-@end itemize
-
-@item
-The @code{--enable-debuglevel} option is used to specify the verbosity of the
-debug output. Be careful with this, as the @code{details} verbosity may produce
-really large logs (in order of GBs). There are three levels of verbosity:
-@code{brief}, @code{verbose} and @code{details}.
-
-@end itemize
-
-@node Debug messages Example
-@subsubsection Example
-
-@example
-$ ./configure --enable-debug=server,zones --enable-debuglevel=verbose
-@end example