Commit 3eec93cb authored by Ondřej Surý's avatar Ondřej Surý

Rewritten all basic documentation into sphinx and have a working build

parent 51733eda
......@@ -77,3 +77,7 @@
# alternative allocators
/src/allocator.h
/src/allocators/
# sphinx documentation
/doc/_build/
/doc/conf.py
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
This diff is collapsed.
This diff is collapsed.
.. _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
@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
@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.
.. _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.
@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
This diff is collapsed.
This diff is collapsed.
@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