Merge branch 'sphinx'

Conflicts:
	doc/installation.texi
	doc/running.texi

.gitignore

@@ -77,3 +77,7 @@
 # alternative allocators
 /src/allocator.h
 /src/allocators/
+
+# sphinx documentation
+/doc/_build/
+/doc/conf.py

configure.ac

@@ -339,6 +339,21 @@ AC_LINK_IFELSE([AC_LANG_PROGRAM([[#include <sched.h>]], [[cpuset_t* set = cpuset
 # Add code coverage macro
 AX_CODE_COVERAGE
 
+AC_PATH_PROG([SPHINXBUILD], [sphinx-build], [false])
+AS_IF([test "$SPHINXBUILD" = "false"],
+  [AC_MSG_WARN([Could not find the 'sphinx-build' executable, you will be unable to regenerate documentation.])],
+  [AC_PATH_PROG([PDFLATEX], [pdflatex], [false])
+   AS_IF([test "$PDFLATEX" = ""],
+     [AC_MSG_WARN([Could not find the 'pdflatex' executable, you will be unable to generate PDF documentation.])])
+   AC_PATH_PROG([MAKEINFO], [makeinfo], [false])
+   AS_IF([test "$MAKEINFO" = "false"],
+     [AC_MSG_WARN([Could not find the 'makeinfo' executable, you will be unable to generate info documentation.])])
+  ])
+
+AM_CONDITIONAL([HAVE_SPHINXBUILD], test "$SPHINXBUILD" != "false")
+AM_CONDITIONAL([HAVE_PDFLATEX], test "$PDFLATEX" != "false")
+AM_CONDITIONAL([HAVE_MAKEINFO], test "$MAKEINFO" != "false")
+
 AC_CONFIG_FILES([Makefile
 		 doc/Makefile
 		 man/Makefile
@@ -348,6 +363,7 @@ AC_CONFIG_FILES([Makefile
 		 src/Makefile
 		 tests/Makefile
 		 src/zscanner/Makefile
+		 doc/conf.py
 		 man/khost.1
 		 man/knotc.8
 		 man/knotd.8

doc/.gitignore

@@ -15,3 +15,4 @@ texinfo.tex
 version.texi
 mdate-sh
 stamp-vti
+!/logo.pdf
\ No newline at end of file

doc/Makefile.am

-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
+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) $(SPHINXBUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(SPHINXBUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(SPHINXBUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(SPHINXBUILDDIR)/singlehtml."
+
+if HAVE_PDFLATEX
+pdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(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"
+	@echo "able to generate PDF documentation."
+endif
+
+if HAVE_MAKEINFO
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	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) $(SPHINXBUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(SPHINXBUILDDIR)/doctest/output.txt."
+
+else
+html pdf info doctest:
+	@echo "Please install sphinx (python-sphinx) to generate Knot DNS documentation."
+endif
+
+clean-local:
+	-rm -rf _build

doc/conf.py.in

+# -*- coding: utf-8 -*-
+#
+# Knot DNS documentation build configuration file, created by
+# sphinx-quickstart on Tue Apr 15 13:48:28 2014.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os, time
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = []
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'Knot DNS'
+copyright = "%d, CZ.NIC, z.s.p.o." % time.localtime().tm_year
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '@VERSION@'
+# The full version, including alpha/beta/rc tags.
+release = '@VERSION@'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+today = '@RELEASE_DATE@'
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+html_theme = 'nature'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = 'logo.png'
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+#html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+html_domain_indices = False
+
+# If false, no index is generated.
+html_use_index = False
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'KnotDNSdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+latex_elements = {
+# The paper size ('letterpaper' or 'a4paper').
+#'papersize': 'letterpaper',
+
+# The font size ('10pt', '11pt' or '12pt').
+#'pointsize': '10pt',
+
+# Additional stuff for the LaTeX preamble.
+#'preamble': '',
+
+# No empty pages between chapters
+'classoptions': ',openany,oneside',
+
+# Language preferences
+'babel': '\\usepackage[english]{babel}',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+  ('index', 'KnotDNS.tex', u'Knot DNS Documentation',
+   u'CZ.NIC, z.s.p.o.', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+latex_logo = 'logo.pdf'
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+latex_domain_indices = False
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+#man_pages = [
+#    ('index', 'knotdns', u'Knot DNS Documentation',
+#     [u'CZ.NIC, z.s.p.o.'], 1)
+#]
+
+# If true, show URL addresses after external links.
+#man_show_urls = False
+
+
+# -- Options for Texinfo output ------------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+  ('index', 'KnotDNS', u'Knot DNS Documentation',
+   u'CZ.NIC, z.s.p.o.', 'KnotDNS',
+   'High-performance authoritative DNS server implementation',
+   'Miscellaneous'),
+]
+
+# Documents to append as an appendix to all manuals.
+#texinfo_appendices = []
+
+# If false, no module index is generated.
+#texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#texinfo_show_urls = 'footnote'

doc/configuration.rst

+**********************
+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.

doc/configuration.texi

-@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

doc/index.rst

+Welcome to Knot DNS's documentation!
+====================================
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   requirements
+   installation
+   configuration
+   running
+   troubleshooting
+   reference
+   migration

doc/indices.texi

-@node Statement Index, Knot DNS Configuration Reference, Troubleshooting, Top
-@unnumbered Statement Index
-
-@printindex st

doc/installation.rst

+.. _Knot DNS Installation:
+
+*********************
+Knot DNS Installation
+*********************
+
+.. _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,
+otherwise it adapts to the compiler available features.  LLVM clang
+works, but it is not officially supported.
+
+Knot DNS build system relies on these standard tools:
+
+* make
+* libtool
+* autoconf >= 2.65
+* flex >= 2.5.31
+* bison >= 2.3
+
+.. _Required libraries:
+
+Required libraries
+==================
+
+Knot DNS requires few libraries to be compiled:
+
+* OpenSSL, at least 1.0.0 (1.0.1 is required for ECDSA)
+* zlib
+* Userspace RCU, at least 0.5.4
+* libcap-ng, at least 0.6.4 (optional library)
+
+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 http://zlib.net,
+and OpenSSL can be found at http://www.openssl.org.
+
+.. _Userspace RCU:
+
+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.  `Userspace RSU <http://lttng.org/urcu>`_
+
+Binary packages for Debian can be found under ``liburcu1`` for the
+library and ``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.
+
+.. _Installation from the source:
+
+Installation from the sources
+=============================
+
+You can find the source files for the latest release on `www.knot-dns.cz <https://www.knot-dns.cz>`_.
+Alternatively, you can fetch the sources from git repository `<git://git.nic.cz/knot-dns.git>`_.
+
+After unpacking the sources, the compilation and installation is a
+quite straightforward process using autotools.
+
+.. _Configuring and generating Makefiles:
+
+Configuring and generating Makefiles
+------------------------------------
+
+If you want to compile from Git sources, you need to bootstrap the ``./configure`` file first.::
+
+    $ autoreconf -i -f
+
+For all available configure options run::
+
+    $ ./configure --help
+
+If you have trouble with unknown syscalls under valgrind, disable recvmmsg by
+adding a parameter ``--enable-recvmmsg=no`` to configure.
+
+Knot DNS has also support for link time optimizations.  You can enable
+it by the configure parameter ``./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.  Link
+time optimizations also disables the possibility to debug the
+resulting binaries.
+
+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: ``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 ``brief, verbose, details``.
+
+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}. ##TODO
+
+In most simple case you can just run configure without any options::
+
+    $ ./configure
+
+Compilation
+-----------
+
+(After running ``./configure`` you can compile Knot DNS by running
+``make`` command, which will produce binaries and other related
+files::
+
+    $ make
+
+Knot DNS build process is safe to parallelize using ``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::
+
+    $ make -j 8
+
+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 ``make install`` command.  When installing
+as a non-root user you might have to gain elevated privileges by
+switching to root user, e.g. ``sudo make install`` or ``su -c 'make install'``::
+
+    $ make install
+
+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.
+
+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::
+
+    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/``.
+
+As an example, for Debian squeeze (current stable) the Knot DNS
+packages can be added by executing following command as the root user::
+
+    $ 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
+
+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 `LTS <https://wiki.ubuntu.com/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.
+
+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::
+
+    $ sudo add-apt-repository ppa:cz.nic-labs/knot-dns
+    $ sudo apt-get update
+    $ sudo apt-get install knot
+
+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.
+
+Installing Knot DNS packages on Fedora
+--------------------------------------
+
+The RPM packages for ``Knot DNS`` are available in official Fedora
+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
+
+Using official distribution repository is highly recommended, however you may
+want to run ``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::
+
+    [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
+
+After performing this action, you can install ``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 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:
+
+    # yum distro-sync knot
+
+
+Installing Knot DNS from ports on FreeBSD
+-----------------------------------------
+
+Knot DNS is in ports tree under ``dns/knot``::
+
+    $ cd /usr/ports/dns/knot
+    $ sudo make install
+
+Installing Knot DNS on Arch Linux
+---------------------------------
+
+Knot DNS is available official package repository (AUR)::
+
+    https://aur.archlinux.org/packages/knot/
+
+Installing Knot DNS on Gentoo Linux
+-----------------------------------
+
+Knot DNS is available from Gentoo package repository::
+
+    https://packages.gentoo.org/package/net-dns/knot

doc/installation.texi

-@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 1.0.0 (1.0.1 is required for ECDSA)
-@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

doc/introduction.texi → doc/introduction.rst

-@node Introduction, Knot DNS Resource Requirements, Top, Top
-@chapter Introduction
+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
+What is Knot DNS
+----------------
 
 Knot DNS is a high-performance open source DNS server. It
 implements only authoritative domain name service. Knot DNS
@@ -22,47 +16,45 @@ 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 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
+* TCP/UDP protocols
+* AXFR, IXFR - master, slave
+* TSIG
+* EDNS0
+* DNSSEC, including NSEC3
+* NSID
+* Unknown RR types
 
 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
+* Adding/removing zones on-the-fly
+* Reconfiguring server instance on-the-fly
+* IPv4 / IPv6 support
+* Semantic checks of zones
+
+For more info and downloads see `www.knot-dns.cz <https://www.knot-dns.cz>`_.
+
+Git repository: `git://git.nic.cz/knot-dns.git <git://git.nic.cz/knot-dns.git>`_
 
-For more info and downloads see
-@url{http://www.knot-dns.cz, www.knot-dns.cz}.
+Git repository browser: `gitlab.labs.nic.cz/knot/tree/master <https://gitlab.labs.nic.cz/knot/tree/master>`_
 
-Git repository:
-@url{git://git.nic.cz/knot-dns.git, git://git.nic.cz/knot-dns.git}
+Knot DNS issue tracker: `gitlab.labs.nic.cz/knot/issues <https://gitlab.labs.nic.cz/knot/issues>`_
 
-Git repository browser:
-@url{https://gitlab.labs.nic.cz/knot/tree/master, gitlab.labs.nic.cz/knot/tree/master}
+Knot DNS users mailing list: `knot-dns-users@lists.nic.cz <mailto:knot-dns-users@@lists.nic.cz>`_
 
-Knot DNS issue tracker:
-@url{https://gitlab.labs.nic.cz/knot/issues, gitlab.labs.nic.cz/knot/issues}
+Scope of this document
+----------------------
 
-Knot DNS users mailing list:
-@url{mailto:knot-dns-users@@lists.nic.cz, knot-dns-users@@lists.nic.cz}
+This document covers the basic information on installing, configuring
+and troubleshooting the Knot DNS server.
 
-@node Scope of this document
-@section Scope of this document
+License
+-------
 
-This document covers the basic information on installing,
-configuring and troubleshooting the Knot DNS server.
+Knot DNS is licensed under `GNU General Public License <https://www.gnu.org/copyleft/gpl.html>`_
+version 3 or (at your option) any later version. The full text of the license
+is available in the ``COPYING`` file distributed with the source codes.

doc/migration.rst

+.. _Migration from other DNS servers:
+
+********************************
+Migration from other DNS servers
+********************************
+
+.. _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.

doc/migration.texi

-@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

doc/requirements.rst

+Knot DNS Resource Requirements
+==============================
+
+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.
+
+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).
+
+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.
+
+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.

doc/requirements.texi

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