Commit 97f58c29 authored by Daniel Salzman's avatar Daniel Salzman

Update manual pages and documentation

File knot.conf.5.in is generated from the documentation.
parent 6cf1437f
......@@ -15,7 +15,7 @@ EXTRA_DIST = \
SPHINXBUILDDIR = _build
ALLSPHINXOPTS = -n -d $(SPHINXBUILDDIR)/doctrees -D latex_paper_size=a4 $(SPHINXOPTS) .
.PHONY: html-local singlehtml pdf-local info-local
.PHONY: html-local singlehtml pdf-local info-local man
if HAVE_DOCS
......@@ -37,7 +37,6 @@ pdf-local:
$(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
......@@ -53,8 +52,13 @@ else
@echo "able to generate info pages."
endif
man:
$(SPHINXBUILD) -b man -D version="__VERSION__" -D today="__DATE__" $(ALLSPHINXOPTS) $(SPHINXBUILDDIR)/man
@echo
@echo "Build finished. The man pages are in $(SPHINXBUILDDIR)/man."
else
html-local singlehtml pdf-local info-local:
html-local singlehtml pdf-local info-local man:
@echo "Please install sphinx (python-sphinx) to generate Knot DNS documentation."
endif
......
......@@ -40,8 +40,9 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'Knot DNS'
copyright = "%d, CZ.NIC, z.s.p.o." % time.localtime().tm_year
project = 'Knot DNS'
copyright = 'Copyright 2010-%d, CZ.NIC, z.s.p.o.' % time.localtime().tm_year
author = 'CZ.NIC Labs <http://www.knot-dns.cz>'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
......@@ -189,8 +190,7 @@ latex_elements = {
# 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'),
('index', 'KnotDNS.tex', 'Knot DNS Documentation', copyright, 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
......@@ -218,10 +218,9 @@ latex_domain_indices = False
# 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)
#]
man_pages = [
('reference', 'knot.conf', 'Knot DNS configuration file', author, 5)
]
# If true, show URL addresses after external links.
#man_show_urls = False
......@@ -233,10 +232,7 @@ latex_domain_indices = False
# (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'),
('index', 'KnotDNS', 'Knot DNS Documentation', author)
]
# Documents to append as an appendix to all manuals.
......
This diff is collapsed.
.. meta::
:description: reStructuredText plaintext markup language
.. _Knot DNS Installation:
.. _Installation:
*********************
Knot DNS Installation
*********************
************
Installation
************
.. _Required build environment:
......@@ -59,12 +59,12 @@ http://www.openssl.org.
Userspace RCU
-------------
liburcu is a LGPLv2.1 userspace RCU (read-copy-update) library. This
data synchronization library provides read-side access which scales
`Liburcu <http://urcu.so>`_ is a 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>`_
which memory reclamation is possible.
Binary packages for Debian can be found under ``liburcu1`` for the
library and ``liburcu-dev`` for development files.
......@@ -75,16 +75,16 @@ 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 source code:
Installation from the sources
Installation from source code
=============================
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
You can find the source code for the latest release on `www.knot-dns.cz <https://www.knot-dns.cz>`_.
Alternatively, you can fetch the whole project from the git repository
`git://git.nic.cz/knot-dns.git <https://gitlab.labs.nic.cz/labs/knot/tree/master>`_.
After unpacking the sources, the compilation and installation is a
After obtaining the source code the compilation and installation is a
quite straightforward process using autotools.
.. _Configuring and generating Makefiles:
......@@ -92,7 +92,7 @@ quite straightforward process using autotools.
Configuring and generating Makefiles
------------------------------------
If you want to compile from Git sources, you need to bootstrap the ``./configure`` file first::
If compiling from the git source, you need to bootstrap the ``./configure`` file first::
$ autoreconf -i -f
......@@ -114,19 +114,6 @@ 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, ns, loader, dnssec``.
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=verbose
For more detailed information, see :ref:`Debug messages`.
Compilation
-----------
......@@ -152,17 +139,18 @@ You can do so by executing::
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'``.
Installation from packages
==========================
.. _OS specific installation:
In addition to providing the packages in .DEB and .RPM format,
Knot DNS might already be available in your favourite distribution, or
in a ports tree.
OS specific installation
========================
Installing Knot DNS packages on Debian
--------------------------------------
Knot DNS might already be available in the destination operating system
repository.
Knot DNS is already available from Debian wheezy upwards. In addition
Debian Linux
------------
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::
......@@ -182,11 +170,11 @@ executing following command as the root user::
$ apt-get update
$ apt-get install knot
Installing Knot DNS packages on Ubuntu
--------------------------------------
Ubuntu Linux
------------
Prepackaged version of Knot DNS can be found in Ubuntu from
version 12.10 (Quantal Quetzal). In addition to the package included
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 the last stable version of Knot DNS or to install
it on older versions of Ubuntu Linux.
......@@ -205,33 +193,33 @@ 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
--------------------------------------
Fedora Linux
------------
The RPM packages for ``Knot DNS`` are available in official 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::
the following command as the root user::
$ yum install knot
Installing Knot DNS from ports on FreeBSD
-----------------------------------------
FreeBSD
-------
Knot DNS is in ports tree under ``dns/knot``::
$ cd /usr/ports/dns/knot
$ sudo make install
Installing Knot DNS on Arch Linux
---------------------------------
Arch Linux
----------
Knot DNS is available official package repository (AUR)::
https://aur.archlinux.org/packages/knot/
Installing Knot DNS on Gentoo Linux
-----------------------------------
Gentoo Linux
------------
Knot DNS is available from Gentoo package repository::
......
.. meta::
:description: reStructuredText plaintext markup language
Introduction
============
.. _Introduction:
The reader of this document is assumed to know the principles of
Domain Name System.
************
Introduction
************
What is Knot DNS
----------------
================
Knot DNS is a high-performance open source DNS server. It
implements only authoritative domain name service. Knot DNS
......@@ -20,9 +20,9 @@ implementation which allows it to scale well on SMP systems and
operate non-stop even when adding or removing zones.
Knot DNS features
-----------------
=================
Knot DNS supports the following DNS features:
DNS features:
* IN class and partially CH class
* TCP/UDP protocols
......@@ -54,15 +54,9 @@ Knot DNS issue tracker: `gitlab.labs.nic.cz/labs/knot/issues <https://gitlab.lab
Knot DNS users mailing list: `knot-dns-users@lists.nic.cz <mailto:knot-dns-users@lists.nic.cz>`_
Scope of this document
----------------------
This document covers the basic information on installing, configuring
and troubleshooting the Knot DNS server.
License
-------
=======
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.
is available in the ``COPYING`` file distributed with the source code.
......@@ -45,13 +45,11 @@ generated by Bind.
You can follow this example::
zones {
storage "/var/lib/knot";
example.com {
dnssec-enable on;
dnssec-keydir "example.com.keys";
file "example.com.db";
}
}
zone:
- domain: "example.com."
file: "example.com.db"
storage: "/var/lib/knot"
dnssec-enable: on
dnssec-keydir: "example.com.keys"
5. Start Knot DNS and check the log files to make sure that everything went right.
This diff is collapsed.
.. meta::
:description: reStructuredText plaintext markup language
Knot DNS Resource Requirements
==============================
.. _Requirements:
Hardware requirements
---------------------
************
Requirements
************
Hardware
========
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
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
......@@ -30,7 +33,7 @@ Memory requirements
-------------------
Knot DNS implementation focuses on performance and thus can be quite
demanding for memory. The rough estimate for memory requirements is
demanding for memory. The rough estimate for memory requirements is
3 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.
......@@ -40,8 +43,8 @@ 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
--------------------------
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
......
.. meta::
:description: reStructuredText plaintext markup language
.. _Running Knot DNS:
.. _Running:
****************
Running Knot DNS
****************
*******
Running
*******
The Knot DNS server part ``knotd`` can run either in the foreground or in the background,
with the ``-d`` option. When run in the foreground, it doesn't create a PID file.
......@@ -15,9 +15,10 @@ The tool ``knotc`` is designed as a front-end for user, making it easier to cont
server daemon. If you want to control the daemon directly, use ``SIGINT`` to quit
the process or ``SIGHUP`` to reload configuration.
If you do not pass any configuration via ``-c`` option, it will try to
search configuration in default path that is ``SYSCONFDIR/knot.conf``. The ``SYSCONFDIR``
depends on what you passed to the ``./configure``, usually ``/etc``.
If you pass neither configuration file (``-c`` parameter) nor configuration
database (``-C`` parameter), server will try to use the default configuration
file stored in ``SYSCONFDIR/knot/knot.conf`` (configured with
``--with-configdir=path``)
Example of server start as a daemon::
......@@ -30,24 +31,24 @@ Example of server stop::
For a complete list of actions refer to ``knotd -h`` and ``knotc -h``
or corresponding man pages.
Also, the server needs to create several files in order to run properly. These
files are stored in the folowing directories.
Also, the server needs to create :ref:`server_rundir` and :ref:`template_storage`
directories in order to run properly.
``storage`` (:ref:`storage`):
.. _Configuration database:
* *Zone files* - default directory for storing zone files. This can be
overriden using absolute zone file location.
Configuration database
======================
In the case of a huge configuration file, the configuration can be preloaded
into the server`s configuration database::
* *Journal files* - each zone has a journal file to store differences
for IXFR and dynamic updates. Journal for zone ``example.com`` will
be placed in ``example.com.diff.db``.
$ knotc import input.conf
``rundir`` (:ref:`rundir`):
Also the configuration database can be exported into the configuration file::
* *PID file* - is created automatically when the server is run in background.
$ knotc export output.conf
* *Control sockets* - as a default, UNIX sockets are created here, but
this can be overriden.
It is recommended to process these operations without server running.
.. _Running a slave server:
......@@ -55,12 +56,10 @@ Running a slave server
======================
Running the server as a slave is very straightforward as you usually
bootstrap zones over AXFR and thus avoid any manual zone compilation.
bootstrap zones over AXFR and thus avoid any manual zone operations.
In contrast to AXFR, when the incremental transfer finishes, it stores
the differences in a journal file and doesn't update the zone file
immediately. There is a timer that checks periodically for new
differences and updates the zone file. You can configure this timer
with the ``zonefile-sync`` statement in ``zones`` (:ref:`zones`).
the differences in the journal file and doesn't update the zone file
immediately but after :ref:`template_zonefile-sync` period elapses.
.. _Running a master server:
......@@ -96,14 +95,14 @@ action::
$ knotc -c master.conf reload
If you want *IXFR-out* differences created from changes you make to a
zone file, enable :ref:`ixfr-from-differences` in ``zones`` statement,
then reload your server as seen above. If *SOA*'s *serial* is not
changed no differences will be created.
If you want to enable ixfr differences creation from changes you make to a
zone file, enable :ref:`template_ixfr-from-differences` in the zone configuration
and reload your server as seen above. If *SOA*'s *serial* is not changed,
no differences will be created.
If you want to refresh the slave zones, you can do this with the
``knotc refresh`` action::
$ knotc -c slave.conf refresh
For the zone retransfer, there is also additional command ``-f``.
For the zone retransfer, there is also an additional command ``-f``.
.. meta::
:description: reStructuredText plaintext markup language
.. _Troubleshooting:
***************
Troubleshooting
***************
First of all, check the logs (:ref:`log`). By default, Knot DNS logs
all error messages to syslog. Enabling at least the ``warning``
message severity may help you identify some problems.
First of all, check the logs (:ref:`Logging section`). Enabling at least
the ``warning`` message severity may help you identify some problems.
.. _Submitting a bugreport:
Submitting a bugreport
======================
If you are unable to solve the problem by yourselves, you can submit a
bugreport to the Knot DNS team. For security issues (e.g. crash) do
not use the public mailinglist. Instead, write to
`knot-dns@labs.nic.cz <mailto:knot-dns@labs.nic.cz>`_. All other bugs
and questions may be directed to the Knot DNS users mailinglist
If you are unable to solve the problem by yourself, you can submit a
bugreport to the Knot DNS team. For security issues (e.g. crash) do
not use the public mailing list. Instead, write to
`knot-dns@labs.nic.cz <mailto:knot-dns@labs.nic.cz>`_. All other bugs
and questions may be directed to the Knot DNS users mailing list
(`knot-dns-users@lists.nic.cz <mailto:knot-dns-users@lists.nic.cz>`_).
The bugreport should contain at least:
* Knot DNS version and type of installation (source, package, etc.),
* type and version of your operating system,
* basic hardware information,
* description of the bug,
* log output of all messages (category ``any``) with severity Info and
higher (severities ``info, notice, warning, error``, or ``any`` if
debug messages are not turned on (see below)),
* steps to reproduce the bug (if known),
* backtrace (if the bug caused a crash; see next section).
* Knot DNS version and type of installation (source, package, etc.)
* Type and version of your operating system
* Basic hardware information
* Description of the bug
* Log output of all messages (category ``any``, severity ``info``)
* Steps to reproduce the bug (if known)
* Backtrace (if the bug caused a crash; see next section)
If it is possible, the actual configuration file and/or zone file(s)
will be very useful as well.
......@@ -42,22 +41,22 @@ Generating backtrace
====================
There are several ways to achieve that, the most common way is to
leave core dumps and then extract a backtrace from it. This doesn't
leave core dumps and then extract a backtrace from it. This doesn't
affect any server operation, you just need to make sure the OS is
configured to generate them::
$ ulimit -c unlimited # enable unlimited core dump size
$ ulimit -c unlimited # Enable unlimited core dump size
...
$ gdb $(which knotd) core.<KNOT_PID> # start gdb on a core dump
(gdb) thread apply all bt # extract backtrace from all threads
$ gdb $(which knotd) core.<KNOT_PID> # Start gdb on the core dump
(gdb) thread apply all bt # Extract backtrace from all threads
(gdb) q
If the error is repeatable, you can run the binary in a ``gdb``
debugger or attach the debugger to the running process. The backtrace
debugger or attach the debugger to the running process. The backtrace
from a running process is generally useful when debugging problems
like stuck process and similar::
$ knotc -c knot.conf start
$ knotd -c knot.conf
$ sudo gdb --pid <KNOT_PID>
(gdb) continue
...
......@@ -70,49 +69,44 @@ Debug messages
==============
In some cases the aforementioned information may not be enough to find
and fix the bug. In these cases it may be useful to turn on debug
and fix the bug. In these cases it may be useful to turn on debug
messages.
Two steps are required in order to log debug messages. First you need
to allow the debug messages in the server. Then the logging must be
configured to log debug messages (:ref:`log`). It is recommended to
log these messages to a file. Firstly, the debug output may be rather
Two steps are required in order to log debug messages. First you need
to allow the debug messages in the server. Then the logging must be
configured to log debug messages (:ref:`Logging section`). It is recommended to
log these messages to a file. Firstly, the debug output may be rather
large and secondly, it is easier to use the data for debugging.
.. _Enabling debug messages in server:
.. _Enabling debug messages:
Enabling debug messages in server
---------------------------------
Enabling debug messages
-----------------------
Allowing debug messages in the server is possible only when
configuring the sources. Two ``configure`` options are required
configuring the sources. Two ``configure`` options are required
to do this:
* The ``--enable-debug`` option specifies the server modules for which
you want to enable debug messages. One or more of the following
you want to enable debug messages. One or more of the following
modules may be listed, separated by commas:
* ``server`` - Messages related to networking, threads and low-level
journal handling.
* ``zones`` - All operations with zones - loading, updating, saving,
timers, high-level journal management.
* ``xfr`` - AXFR, IXFR and NOTIFY handling.
* ``packet`` - Packet parsing and response creation.
* ``rr`` - Details of processed resource records.
* ``zones`` - All operations with zones (loading, updating, saving,
timers, high-level journal management).
* ``ns`` - Query processing, high-level handling of all requests
(transfers, NOTIFY, normal queries).
(transfers, notifies, normal queries).
* ``loader`` - Zone loading and semantic checks.
* ``dnssec`` - DNSSEC operations.
* The ``--enable-debuglevel`` option is used to specify the verbosity
of the debug output. Be careful with this, as the ``details``
of the debug output. Be careful with this, as the ``details``
verbosity may produce really large logs (in order of GBs). There are
three levels of verbosity: ``brief``, ``verbose`` and ``details``.
.. _Debug messages Example:
Example:
Debug messages Example
----------------------
::
$ ./configure --enable-debug=server,zones --enable-debuglevel=verbose
This diff is collapsed.
......@@ -9,10 +9,13 @@
.SS "Parameters:"
.TP
\fB\-c\fR, \fB\-\-config\fR \fIfile\fR
Select configuration file.
Use textual configuration file (default is @config_dir@/knot.conf).
.TP
\fB\-C\fR, \fB\-\-confdb\fR \fIdirectory\fR
Use configuration database.
.TP
\fB\-s\fR, \fB\-\-server\fR \fIserver\fR
Remote UNIX socket/IP address (default @run_dir@/knot.sock).
Remote UNIX socket/IP address (default is @run_dir@/knot.sock).
.TP
\fB\-p\fR, \fB\-\-port\fR \fIport\fR
Remote server port (only for IP).
......@@ -21,7 +24,7 @@ Remote server port (only for IP).
Use key specified on the command line (default algorithm is hmac\-md5).
.TP
\fB\-k\fR, \fB\-\-keyfile\fR \fIfile\fR
Use key file (as in config section 'keys').
Use key file.
.TP
\fB\-f\fR, \fB\-\-force\fR
Force operation \- override some checks.
......@@ -54,7 +57,7 @@ Check if server is running.
Show status of configured zones.
.TP
\fBrefresh\fR [\fIzone\fR] ...
Refresh slave zones. Flag '-f' forces retransfer (zone(s) must be specified).
Refresh slave zones. Flag \fB-f\fR forces retransfer (zone(s) must be specified).
.TP
\fBcheckconf\fR
Check current server configuration.
......@@ -67,6 +70,12 @@ Estimate memory consumption for zones.
.TP
\fBsignzone\fR \fIzone\fR ...
Sign zones with available DNSSEC keys.
.TP
\fBimport\fR \fIfile\fR
Import configuration database from file.
.TP
\fBexport\fR \fIfile\fR
Export configuration database to file. Flag \fB-f\fR is required.
.SH EXAMPLES
.TP
.B Setup a keyfile for remote control
......
......@@ -9,10 +9,14 @@
.SS "Parameters:"
.TP
\fB\-c\fR, \fB\-\-config\fR \fIfile\fR
Select configuration file.
Use textual configuration file (default is @config_dir@/knot.conf).
.TP
\fB\-d\fR, \fB\-\-daemonize\fR=[\fIdir\fR]
Run server as a daemon. Working directory may be set.
\fB\-C\fR, \fB\-\-confdb\fR \fIdirectory\fR
Use configuration database.
.TP
\fB\-d\fR, \fB\-\-daemonize\fR=[\fIdirectory\fR]
Run server as a daemon. Working directory may be set
(default directory is /).
.TP
\fB\-V\fR, \fB\-\-version\fR
Print version of the server.
......@@ -24,4 +28,4 @@ Print help and usage.
.BR knot.conf (5).
.SH NOTE
If the \fBinfo\fR program is properly installed at your site,
the \fBinfo\ Knot\fR command should give you an access to the complete manual.
\ No newline at end of file
the \fBinfo\ Knot\fR command should give you an access to the complete manual.
#!/bin/bash
pushd ../doc
make man
for f in ./_build/man/*; do
file=`basename $f`
echo "Processing '${file}' file..."
sed -e "s/__VERSION__/@VERSION@/g; s/__DATE__/@RELEASE_DATE@/g" ${f} > ../man/${file}.in
done
popd
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment