diff --git a/doc/configuration.texi b/doc/configuration.texi
index 7c28ef66b77ebd93c59f1b2901212b8a1c34a0c4..70f3fb0455ab1f524b400002f1006c6d7a0d2c9d 100644
--- a/doc/configuration.texi
+++ b/doc/configuration.texi
@@ -1,7 +1,7 @@
@node Knot DNS Configuration, Running Knot DNS, Knot DNS Installation, Top
@chapter Knot DNS Configuration
-In this chapter we provide suggested configuration and explain the meaning of individual configuration options.
+In this chapter we provide suggested configurations and explain the meaning of individual configuration options.
@menu
* Minimal configuration::
@@ -47,14 +47,15 @@ zones @{
@end example
-Let's now go step by step through this minimal configuration file:
+@page
+Now let's go step by step through this minimal configuration file:
@enumerate
@item
In @code{@ref{system}} statement we have configured @code{@ref{storage}}
-directory where Knot DNS will store compiled zone files, it's
-@ref{pidfile} and for slave zone also their journal files.
+directory where Knot DNS will store compiled zone files,
+PID file and for slave zone also their journal files.
@item
The @code{@ref{interfaces}} statement defines interfaces where Knot
@@ -64,32 +65,33 @@ on port 53 and second IPv6 called @code{second_int} also listening on
port 53, which is the default port for the DNS.
@item
-The @code{@ref{log}} statement defines the destination where Knot DNS
-will send it's log messages. In this example we told Knot DNS to send
-its log messages with priority @code{debug}, @code{warning} and
-@code{notice} into the syslog. If you omit this sections, all levels
-will printed to either @code{stdout} or @code{stderr}, and the levels
+The @code{@ref{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{@ref{zones}} statement is the one probably most important,
-because it defines the zones Knot DNS will serve. In its most simple
+because it defines the zones that Knot DNS will serve. In its most simple
form you define zone by it's name and defined the filename where Knot
DNS can find the zone contents. You can turn on more detailed semantic
checks of zone file in this statement. Refer to @code{@ref{zones List of zone semantic checks}} to see
which checks are enabled by default and which are optional. If Knot is
being run as a master server, experimental feature @code{ixfr-from-differences}
-can be enabled to create IXFR changesets from changest made to master zone file.
+can be enabled to create IXFR changesets from changes made to the master zone file.
See @ref{Controlling running daemon} for more information.
@end enumerate
+@page
@node Slave configuration
@section Slave configuration
-Knot DNS doesn't strictly differ master and slave zones.
+Knot DNS doesn't strictly differ between master and slave zones.
The only requirement is to have @code{xfr-in} @code{@ref{zones}} statement set for given zone,
-thus both allowing incoming XFR from that remote and also using it as the
+thus allowing both incoming XFR from that remote and using it as the
zone master. Also, you can specify relative paths for zone file and in that case,
zone files will be bootstrapped over AXFR and placed in the storage directory,
specified in @code{@ref{storage}}.
@@ -107,10 +109,12 @@ zones @{
@}
@end example
-You can also use TSIG for access control. For this, you need to specify the key
-and assign it to the remote. Supported algorithms for TSIG key are:
-hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384, hmac-sha512.
-Secret is written in base64 encoded format. @code{@ref{keys}}
+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. @code{@ref{keys}}
@example
keys @{
@@ -130,11 +134,12 @@ zones @{
As of now it is not possible to associate multiple keys with a remote.
+@page
@node Master configuration
@section Master configuration
By default, zones are treated as master as long as they don't have the @code{xfr-in} set.
-You can specify which remotes to allow outgoing XFR and NOTIFY @code{@ref{zones}}.
+You can specify which remotes to allow for outgoing XFR and NOTIFY @code{@ref{zones}}.
@example
remotes @{
@@ -173,7 +178,7 @@ zones @{
@section Configuring multiple interfaces
Knot DNS support binding to multiple available interfaces in the @code{@ref{interfaces}}.
-You can also use the special addresses for "any address" like @code{0.0.0.0} or @code{[::]}.
+@*You can also use the special addresses for "any address" like @code{0.0.0.0} or @code{[::]}.
@example
interfaces @{
diff --git a/doc/installation.texi b/doc/installation.texi
index a4ae16b1df75244c839a44bfca8881c60b1e1156..36bed5cd2d1f379e00971f7a3fc660f3b73e4a81 100644
--- a/doc/installation.texi
+++ b/doc/installation.texi
@@ -12,7 +12,7 @@
@section Required build environment
GCC at least 4.1 is strictly required for atomic builtins, but 4.2 or newer is recommended.
-Another requirement is _GNU_SOURCE support, otherwise it adapts to the compiler available features.
+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:
@@ -47,13 +47,13 @@ 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 communication threads.
-Most rights are stripped from the communication threads for security reasons.
+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/}.
+@url{http://zlib.net}, and OpenSSL can be found at
+@url{http://www.openssl.org}.
@menu
* Userspace RCU::
@@ -70,12 +70,13 @@ 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 liburcu1 for the
-library and liburcu-dev for development files.
+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 in later releases of Userspace RCU.
+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
@@ -102,10 +103,13 @@ For all available options run:
@command{./configure --help}
@end example
-If you have trouble with unknown syscalls under valgrind, disable recvmmsg with
-@command{./configure --enable-recvmmsg=no}.
-Also, it has been reported that some platforms have broken LTO (Link time optimizations)
-support, you can disable that by @command{./configure --enable-lto=no}.
+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=no}.
+It is however disabled by default as it is known to be broken in some compiler
+versions and may result in an unexpected behavior.
If you want to add debug messages, there are two steps to do that.
First you have to enable modules you are interested in.
@@ -113,6 +117,7 @@ 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
@@ -247,6 +252,7 @@ Running this sequence of command will ensure that you will
install the Knot DNS on your system and keep it up-to-date
in the future, when new version are released.
+@page
@node Installing Knot DNS RPMs on Fedora
@subsection Installing Knot DNS RPMs on Fedora
@@ -263,6 +269,13 @@ gpgcheck=0
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-network.cz
@end example
+When you have added a new repository, you can install Knot DNS as a
+regular package.
+
+@example
+$ yum install knot
+@end example
+
@node Installing Knot DNS from ports on FreeBSD
@subsection Installing Knot DNS from ports on FreeBSD
diff --git a/doc/reference.texi b/doc/reference.texi
index fb3c99e8ae9134fbf562ffcbfc73a2964bdabe3a..1dde0c05feda135f75d49dc9de184d0f7f460a37 100644
--- a/doc/reference.texi
+++ b/doc/reference.texi
@@ -108,7 +108,7 @@ system @{
@subsubsection pidfile
@vindex pidfile
-Specifies custom pidfile location.
+Specifies a custom PID file location.
Default value: @file{knot.pid} in @code{@ref{storage}} directory.
@@ -139,9 +139,10 @@ system @{
System @kbd{user} or @kbd{user}.@kbd{group} under which the Knot DNS
is run after starting and binding to interfaces.
-Only aplicable if your system knows how to handle Linux capabilities (@pxref{Required libraries}).
+Linux capabilities (@pxref{Required libraries}) are employed if supported
+and this configuration option is set.
-Default value: root.root
+Default value: @kbd{root.root}
@example
system @{
@@ -199,7 +200,7 @@ TSIG. It consists of its @kbd{name}, @kbd{algorithm} and @kbd{key} contents.
Supported algoritms:
-@multitable @columnfractions 1
+@itemize
@item
hmac-md5
@item
@@ -212,7 +213,7 @@ hmac-sha256
hmac-sha384
@item
hmac-sha512
-@end multitable
+@end itemize
You need to use bind or ldns utils to generate TSIG keys. Unfortunately, Knot DNS does not have any own generation utilities yet.
@@ -310,7 +311,7 @@ Short form:
@example
interfaces @{
- my_second_ip 198.51.100.1@@53;
+ my_second_ip @{ address 198.51.100.1@@53; @}
@}
@end example
@@ -320,7 +321,7 @@ Short form without port (defaults to 53):
@example
interfaces @{
- my_third_ip 203.0.113.1;
+ my_third_ip @{ address 203.0.113.1; @}
@}
@end example
@@ -413,9 +414,9 @@ remotes @{
address 127.0.0.1;
port 53531;
key key0.server0;
- via ipv4;
- via 82.35.64.59; # IPv4
- via [::cafe]; # IPv6
+ via ipv4; # reference to 'remotes'
+ # via 82.35.64.59; # direct IPv4
+ # via [::cafe]; # direct IPv6
@}
# Format 2:
@@ -690,7 +691,9 @@ logging categories to choose from. Each log
message has its severity and user can configure severities for each
log destination.
-In case of missing log section, @emph{errors} from all categories will be logged to @emph{stderr} and to @emph{syslog}. No other severities shall be logged!
+In case of missing log section, severities from @kbd{warning} and more serious
+will be logged to both @kbd{stderr} and @kbd{syslog}. The @kbd{info} and @kbd{notice}
+severities will be logged to the @kbd{stdout}.
@node log_name
@subsubsection @kbd{log_name}
diff --git a/doc/requirements.texi b/doc/requirements.texi
index 0c83d2555ef488e7a6ec25d7a3c666420c83edf0..5e351fbdaa735dab49ce05f73363521aae8fb53c 100644
--- a/doc/requirements.texi
+++ b/doc/requirements.texi
@@ -34,7 +34,7 @@ and CAS (i586 and newer).
@section Memory requirements
Knot DNS implementation focuses on performance and thus can
-be very demanding for memory. The rough estimate for memory
+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.
@@ -47,7 +47,6 @@ twice the amount of memory for the duration of incoming transfers.
@section Supported operating system
Knot DNS itself is written in a portable way, but it depends on
-userspace-rcu library, which is the main constraint when it
+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 and userspace-rcu library can be compiled and run on
-Linux, FreeBSD, OpenBSD, NetBSD and Mac OS X.
+Knot DNS can be compiled and run on Linux, FreeBSD, OpenBSD, NetBSD and Mac OS X.
diff --git a/doc/running.texi b/doc/running.texi
index fb5c69bb834f0950669ea1c026d32b3446d2acca..1fe4cfed33984a464b2e2b1146c4c0ea701c0c86 100644
--- a/doc/running.texi
+++ b/doc/running.texi
@@ -20,7 +20,7 @@ $ knotc -a -c knot.conf start|reload|restart
The tool @code{knotc} is designed as a front-end for user, making it easier
to do everything from zone compilation to controlling the server daemon.
-To communicate with the binary, it reads the process PID from the @emph{pidfile} specified in the configuration and sends POSIX signals to it.
+To communicate with the binary, it reads the PID from the @emph{PID file} specified in the configuration @ref{pidfile} and sends POSIX signals to it.
If you want to control the daemon directly, use @code{SIGINT} to quit the process or @code{SIGHUP} to reload configuration. Signal @code{SIGUSR2} is currently used to refresh slave zones.
@example
@@ -58,7 +58,7 @@ Actions:
compile Compile zones (accepts specific zones, see above).
@end example
-But if you want to run Knot DNS daemon directly, you can use @code{knotd} binary
+If you want to run Knot DNS daemon directly, you can use @code{knotd} binary
to do that. It accepts just configuration file and option to run in background.
@example
Usage: knotd [parameters]
diff --git a/doc/troubleshooting.texi b/doc/troubleshooting.texi
index 7a9b79bcdf3449eaa0fe38180ba318c491a62f66..e00c28a2081d36679a7a5d5612e71631521e8c3c 100644
--- a/doc/troubleshooting.texi
+++ b/doc/troubleshooting.texi
@@ -39,28 +39,33 @@ be very useful as well.
@node Generating backtrace
@section Generating backtrace
-There are several ways to achieve that, the most common is to run
-the binary in a @code{gdb} debugger or attach to it.
+There are several ways to achieve that, the most common way is to leave core
+dumps and then extract a backtrace from it.
+This doesn't affect any server operation, you just need to make sure
+the OS is configured to generate them.
+
@example
-$ gdb --args knotd -c knot.conf
-(gdb) run
+$ ulimit -c unlimited # enable unlimited core dump size
...
-Program received signal SIGSEGV.
-(gdb) bt
+$ gdb $(which knotd) core.<KNOT_PID> # start gdb on a core dump
+(gdb) thread apply all bt # extract backtrace from all threads
(gdb) q
@end example
-Or attach to the running program.
+If the error is repeatable, you can run the binary in a @code{gdb} debugger
+or attach the debugger to the running process. The backtrace from a running
+process is generally useful when debugging problems like stuck process and similar.
@example
$ knotc -c knot.conf start
$ sudo gdb --pid <KNOT_PID>
(gdb) continue
...
-Program received signal SIGSEGV.
-(gdb) bt
+(gdb) thread apply all bt
(gdb) q
@end example
+
+
@node Debug messages
@section Debug messages