Skip to content
Snippets Groups Projects
Commit b6165e6a authored by Ondřej Surý's avatar Ondřej Surý
Browse files

Convert the documentation to texinfo format, it will be much easier to support... 

Convert the documentation to texinfo format, it will be much easier to support that without xmlto and all docbook stylesheets
parent 56346056
No related branches found
No related tags found
No related merge requests found
Expand all Hide whitespace changes
Inline Side-by-side
Showing
with 872 additions and 758 deletions
configure.ac
+ 0
− 15
View file @ b6165e6a
......@@ -45,21 +45,6 @@ rm -f conftest.l lexyy.c lex.yy.c
AC_SUBST([LEX], [$ac_cv_path_LEX])
AM_PROG_LEX
# Check for tools needed to compile used documentation
AC_ARG_VAR([XMLTO], [path to xmlto processor to generate a HTML documentation])
AC_ARG_WITH([documentation],
[AS_HELP_STRING([--with-documentation @<:@default=no@:>@],
[enable building of the user documentation])],
[],
[with_documentation=no])
XMLTO=
AS_IF([test "x$with_documentation" != "xno"],
[AC_CHECK_PROG([XMLTO], [xmlto], [xmlto],
[AC_MSG_ERROR([xmlto needed for building the documentation])])
AM_CONDITIONAL([build_documentation], [test "x$XMLTO" != "x"])
])
AC_PROG_YACC
YACC_BISON=`bison --version | awk '{print $1;exit}'`
AS_IF([test "x$YACC_BISON" != "xbison"],
......
doc/Makefile.am
+ 1
− 21
View file @ b6165e6a
XMLTO=@XMLTO@
XMLTO_FLAGS=--skip-validation
XML_SOURCES=configuration.xml \
installation.xml \
introduction.xml \
migration.xml \
reference.xml \
resources.xml \
security.xml \
troubleshooting.xml
if build_documentation
htmldir = $(prefix)/share/doc/@PACKAGE@
dist_html_DATA = @PACKAGE@.html
@PACKAGE@.html: @PACKAGE@.xml $(XML_SOURCES)
$(XMLTO) $(XMLTO_FLAGS) html-nochunks @PACKAGE@.xml
fi
info_TEXINFOS = knot.texi
doc/configuration.xml deleted 100644 → 0
+ 0
− 79
View file @ 56346056
<chapter>
<title>Knot DNS Configuration</title>
<para>
In this chapter we provide suggested configuration and explain the meaning of individual configuration options.
</para>
<section>
<title>Sample Configurations</title>
<section>
<title>Minimal Configuration</title>
<para>
The following configuration presents a minimal configuration
file which can be used as a base for your Knot DNS setup.
<programlisting>
# 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.
#
system {
storage "/var/lib/knot";
}
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";
}
}
</programlisting>
</para>
<para>
Let's now go step by step through this minimal configuration file:
<orderedlist>
<listitem>
In <filename><link xml:id="system">system</link></filename>
statement we have
configured <link xml:id="storage">storage</link> directory
where Knot DNS will store compiled zone files, it's
pidfile and for slave zone also their journal files.
</listitem>
<listitem>
The <filename><link xml:id="interfaces">interfaces</link></filename>
statement defines interfaces where Knot DNS will listen
for incoming connections. We have defined two interfaces:
one IPv4 called <filename>my_interface</filename>
explicitly listening on port 53 and second IPv6
called <filename>second_int</filename> also listening on
port 53, which is the default port for the DNS.
</listitem>
<listitem>
The <filename><link xml:id="log">log</link></filename>
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 <filename>debug</filename>, <filename>warning</filename>
and <filename>notice</filename> into the syslog.
</listitem>
<listitem>
The <filename><link xml:id="zones">zones</link></filename>
statement is the one probably most important, because it
defines the zones 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.
</listitem>
</orderedlist>
</para>
</section>
</section>
</chapter>
doc/installation.xml deleted 100644 → 0
+ 0
− 192
View file @ 56346056
<chapter>
<title>Knot DNS Installation</title>
<section>
<title>Required build environment</title>
<para>
[TODO] Describe lowest needed GCC/Clang, etc.
</para>
</section>
<section>
<title>Required libraries</title>
<para>
Knot DNS requires few libraries to be compiled:
<itemizedlist>
<listitem>OpenSSL</listitem>
<listitem>zlib</listitem>
<listitem>Userspace RCU</listitem>
</itemizedlist>
</para>
<para>
You can probably find OpenSSL and zlib libraries already included
in your system or distribution. If not, zlib resides at
<link xl:href="http://zlib.net/">http://zlib.net</link>, and OpenSSL can be found at
<link xl:href="http://www.openssl.org/">OpenSSL</link>.
</para>
<section>
<title>Userspace RCU</title>
<para>
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 multiples 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. (<link xl:href="http://lttng.org/urcu">Userspace RCU</link>)
</para>
<para>
Binary packages for Debian can be found under liburcu1 for the
library and liburcu-dev for development files.
</para>
<para>
Minimum supported version of Userspace RCU library is 0.4.0,
but we recommend using latest available version. It is
especially on non-Linux systems as we got some compatibility
patches accepted in later releases of Userspace RCU.
</para>
</section>
</section>
<section>
<title>Installation from the sources</title>
<para>
After unpacking the sources, the compilation and installation is
a quite straightforward process using autotools.
</para>
<section>
<title>Configuring and generating Makefiles</title>
<para>
For all available options run:
<programlisting>
./configure --help
</programlisting>
</para>
<para>
In most simple case you can just run configure without any options.
<programlisting>
./configure
</programlisting>
</para>
</section>
<section>
<title>Compilation</title>
<para>
After running <filename>./configure</filename> you can compile
Knot DNS by running make command, which will produce binaries
and other related files.
<programlisting>
make
</programlisting>
</para>
<para>
Knot DNS build process is safe to paralelize
using <filename>make -j N</filename>, where N is number of
concurrent processes. Using this option can increase speed of
the compilation.
</para>
<para>
For example to use maximum 8 concurrent processes you would use:
<programlisting>
make -j 8
</programlisting>
</para>
</section>
<section>
<title>Installation</title>
<para>
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 <filename>make install</filename> command. When installing as a
non-root user you might have to gain elevated privileges by
switching to root user, e.g. <filename>sudo make install</filename>
or <filename>su -c 'make install'</filename>.
<programlisting>
make install
</programlisting>
</para>
</section>
</section>
<section>
<title>Installation from packages</title>
<para>
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.
</para>
<section>
<title>Installing Knot DNS packages on Debian</title>
<para>
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:
<programlisting>
deb http://deb.knot-dns.cz/debian/ &lt;codename&gt; main
deb-src http://deb.knot-dns.cz/debian/ &lt;codename&gt; main
</programlisting>
to your /etc/apt/sources.list or into separate file in
/etc/apt/sources.list.d/.
</para>
<para>
As an example, for Debian squeeze (current stable) the Knot
DNS packages can be added by executing following command as
the root user.
<programlisting>
cat &gt;/etc/apt/sources.list.d/knot.list &lt;&lt;EOF
deb http://deb.knot-dns.cz/debian/ &lt;codename&gt; main
deb-src http://deb.knot-dns.cz/debian/ &lt;codename&gt; main
EOF
apt-get update
apt-get install knot
</programlisting>
</para>
</section>
<section>
<title>Installing Knot DNS packages on Ubuntu</title>
<para>
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.
</para>
<para>
We typically provide packages for all supported versions of
Ubuntu Linux including 5 year support
for <link xl:href="https://wiki.ubuntu.com/LTS">LTS</link>
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.
</para>
<section>
<title>Adding official PPA repository for Knot DNS</title>
<para>
To start installing and using software from a Personal
Package Archive, you first need to tell Ubuntu where to find
the PPA.
<programlisting>
sudo add-apt-repository ppa:cz.nic-labs/knot-dns
sudo apt-get update
sudo apt-get install knot
</programlisting>
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.
</para>
</section>
</section>
<section>
<title>Installing Knot DNS RPMs on Fedora</title>
<para>
[TODO]
</para>
</section>
<section>
<title>Installing Knot DNS from ports on FreeBSD</title>
<para>
[TODO]
</para>
</section>
</section>
</chapter>
doc/introduction.xml deleted 100644 → 0
+ 0
− 41
View file @ 56346056
<chapter>
<title>Introduction</title>
<para>
The reader of this document is assumed to know the principles of
Domain Name System.
</para>
<section>
<title>What is Knot DNS</title>
<para>
Knot DNS implements a domain name server. It implements only
authoritative domain name service and can be used to serve DNS
zones in the Internet.
</para>
<para>
Knot DNS supports following features:
<simplelist>
<member>TCP/UDP</member>
<member>AXFR</member>
<member>IXFR</member>
<member>TSIG</member>
<member>...</member>
</simplelist>
</para>
</section>
<section>
<title>Scope of Document</title>
<para>
This document covers the basic information on installing,
configuring and troubleshooting the Knot DNS server. We have
also dedicated a chapter for users of other DNS server
implementations where describe how to migrate their
configuration to Knot DNS.
</para>
</section>
<section>
<title>Conventions Used in This Document</title>
<para>
[TODO]:
</para>
</section>
</chapter>
doc/knot.texi 0 → 100644
+ 871
− 0
View file @ b6165e6a
This diff is collapsed.
doc/knot.xml deleted 100644 → 0
+ 0
− 36
View file @ 56346056
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V5.0//EN"
"http://www.oasis-open.org/docbook/xml/5.0/docbook.dtd" [
<!ENTITY introduction SYSTEM "introduction.xml">
<!ENTITY resources SYSTEM "resources.xml">
<!ENTITY installation SYSTEM "installation.xml">
<!ENTITY configuration SYSTEM "configuration.xml">
<!ENTITY migration SYSTEM "migration.xml">
<!ENTITY reference SYSTEM "reference.xml">
<!ENTITY security SYSTEM "security.xml">
<!ENTITY troubleshooting SYSTEM "troubleshooting.xml">
]>
<book xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink"
version="5.0">
<info>
<title>Knot DNS Reference Manual</title>
<author>
<personname>
<firstname>Ondřej</firstname><surname>Surý</surname>
<email>ondrej.sury@nic.cz</email>
<affiliation>CZ.NIC, z.s.p.o.</affiliation>
</personname>
</author>
<copyright><year>2012</year><holder>CZ.NIC, z.s.p.o.</holder></copyright>
</info>
&introduction;
&resources;
&installation;
&configuration;
&migration;
&reference;
&security;
&troubleshooting;
</book>
doc/migration.xml deleted 100644 → 0
+ 0
− 32
View file @ 56346056
<chapter>
<title>Migration for other DNS servers</title>
<section>
<title>Knot DNS for BIND users</title>
<para>
[TODO]
</para>
</section>
<section>
<title>Knot DNS for NSD users</title>
<para>
[TODO]
</para>
</section>
<section>
<title>Knot DNS for PowerDNS users</title>
<para>
[TODO]
</para>
</section>
<section>
<title>Knot DNS for djbdns users</title>
<para>
[TODO]
</para>
</section>
</chapter>
doc/reference.xml deleted 100644 → 0
+ 0
− 279
View file @ 56346056
<chapter>
<title>Knot DNS Configuration Reference</title>
<para>
This reference describe every configuration option in Knot DNS.
</para>
<section xml:id="system">
<title>system</title>
<para>
The <filename>system</filename> statement contains general
options related to the operating system and other general
options which don't fit anywhere else.
</para>
<section>
<title>Syntax</title>
<para>
<programlisting>
system {
[ identity "<emphasis>string</emphasis>"; ]
[ version "<emphasis>string</emphasis>"; ]
[ nsid ( "<emphasis>string</emphasis>" | <filename>hex_string</filename> ); ]
[ storage "<emphasis>string</emphasis>"; ]
[ pidfile "<emphasis>string</emphasis>"; ]
[ workers <emphasis>integer</emphasis>; ]
[ user <emphasis>string</emphasis>[.<emphasis>string</emphasis>]; ]
}
</programlisting>
</para>
</section>
<section>
<title>Statement Definition and Usage</title>
<section xml:id="identity">
<title>identity</title>
<para>
Identity of the server (see RFC 4892). Not used yet.
</para>
<para>
<programlisting>
system {
identity "Knot DNS";
}
</programlisting>
</para>
</section>
<section xml:id="version">
<title>version</title>
<para>
Version of the server (see RFC 4892). Not used yet.
</para>
<para>
<programlisting>
system {
version "1.0.5";
}
</programlisting>
</para>
</section>
<section xml:id="nsid">
<title>nsid</title>
<para>
DNS Name Server Identifier (RFC 5001)
</para>
<para>
Use a string format "text" or a hexstring f.e. 0x01ab00
</para>
<para>
<programlisting>
system {
nsid 0x00cafe;
}
</programlisting>
</para>
</section>
<section xml:id="storage">
<title>storage</title>
<para>
The working directory of the Knot DNS, it is used to store compiled zone files and it's also a default location of the pidfile.
</para>
<para>
<programlisting>
system {
storage "/var/lib/knot";
}
</programlisting>
</para>
</section>
<section xml:id="pidfile">
<title>pidfile</title>
<para>
Custom pidfile location.
</para>
<para>
Default value: knot.pid in <link xml:id="storage">storage</link> directory)
</para>
<para>
<programlisting>
system {
pidfile "/var/run/knot.pid";
}
</programlisting>
</para>
</section>
<section xml:id="workers">
<title>workers</title>
<para>
Number of workers (threads) per interface. This option is used to force number of threads used per interface.
</para>
<para>
Default value: unset (auto-estimates optimal value from the number of online CPUs)
</para>
<para>
<programlisting>
system {
workers: 16;
}
</programlisting>
</para>
</section>
<section xml:id="user">
<title>user</title>
<para>
System user or user.group under which the Knot DNS is run after starting and binding to interfaces.
</para>
<para>
Default value: root.root
</para>
<para>
<programlisting>
system {
user knot.knot;
}
</programlisting>
</para>
</section>
</section>
<section>
<title>Example:</title>
<para>
<programlisting>
system {
version "1.0.7";
storage "/var/lib/knot";
}
</programlisting>
</para>
</section>
</section>
<section xml:id="keys">
<title>keys</title>
<para>
The <filename>keys</filename> statement sets up the TSIG keys used to authenticate zone transfers.
</para>
<section>
<title>Syntax</title>
<para>
<programlisting>
keys {
<emphasis>key_id</emphasis> <emphasis>algorithm</emphasis> "<emphasis>string</emphasis>"; ]
[ <emphasis>key_id</emphasis> <emphasis>algorithm</emphasis> "<emphasis>string</emphasis>"; ... ]
}
</programlisting>
</para>
</section>
<section>
<title>Statement Definition and Usage</title>
<section xml:id="key_id">
<title>key_id</title>
<para>
The <filename>key_id</filename> statement defines a secret
shared key for use with TSIG. It consists of its name,
algorithm and key contents.
</para>
<para>
Supported algoritms:
<simplelist>
<member>hmac-md5</member>
<member>hmac-sha1</member>
<member>hmac-sha224</member>
<member>hmac-sha256</member>
<member>hmac-sha384</member>
<member>hmac-sha512</member>
</simplelist>
</para>
<para>
You will need to use bind or ldns utils to generate TSIG keys. Knot DNS doesn't have it's own generation utilities yet.
<programlisting>
$ dnssec-keygen -a HMAC-SHA256 -b 256 -n HOST foobar.example.com
Kfoobar.example.com.+163+21239
$ cat Kfoobar.example.com.+163+21239.key
foobar.example.com. IN KEY 512 3 163 rqv2WRyDgIUaHcJi03Zssor9jtG1kOpb3dPywxZfTeo=
</programlisting>
</para>
<para>
Key generated in previous paragraph would be written as:
<programlisting>
keys {
foobar.example.com. hmac-sha256 "rqv2WRyDgIUaHcJi03Zssor9jtG1kOpb3dPywxZfTeo=";
}
</programlisting>
</para>
</section>
</section>
<section>
<title>Example</title>
<para>
<programlisting>
keys {
key0.server0 hmac-md5 "Wg==";
foobar.example.com. hmac-sha256 "RQ==";
}
</programlisting>
</para>
</section>
</section>
<section xml:id="interfaces">
<title>interfaces</title>
<para>
The <filename>interfaces</filename> statement contains IP interfaces where Knot DNS listens for incoming queries.
</para>
<section>
<title>Syntax</title>
<para>
<programlisting>
interface {
<emphasis>interface_id</emphasis>
( <emphasis>ip_address</emphasis>[@<emphasis>port_number</emphasis>] |
{ address <emphasis>ip_address</emphasis>; [ port <emphasis>port_number</emphasis>; ] } )
[ <emphasis>interface_id</emphasis> ...; ...; ]
}
</programlisting>
</para>
</section>
<section>
<title>Statement Definition and Usage</title>
<section xml:id="interface_id">
<title>interface_id</title>
<para>
The <filename>interface_id</filename> is a textual
identifier of an IP interface, which consists of IP address
and port.
</para>
<para>
The definition of interface can be written in long or a
short form and it has always contain and IP (IPv4 or IPv6)
address.
</para>
</section>
</section>
<section>
<title>Examples</title>
<para>
Long form:
<programlisting>
interfaces {
my_ip {
address 192.0.2.1;
port 53;
}
}
</programlisting>
</para>
<para>
Short form:
<programlisting>
interfaces {
my_second_ip 198.51.100.1@53;
}
</programlisting>
</para>
<para>
Short form without port (defaults to 53):
<programlisting>
interfaces {
my_third_ip 203.0.113.1;
}
</programlisting>
</para>
</section>
</section>
</chapter>
doc/resources.xml deleted 100644 → 0
+ 0
− 47
View file @ 56346056
<chapter>
<title>Knot DNS Resource Requirements</title>
<section>
<title>Hardware Requirements</title>
<para>
Knot DNS requirements are not very demanding for typical
installations, and a comodity server or virtualized solution
will be sufficient in most cases.
</para>
<para>
However please not that there are some scenarios that will
require the administrator attention and a testing of exact
requirements before deploying Knot DNS in a 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.
</para>
</section>
<section>
<title>CPU Requirements</title>
<para>
Knot DNS is not very CPU requiring, but it can consume some CPU
</para>
</section>
<section>
<title>Memory Requirements</title>
<para>
Knot DNS implementation focuses on the performance and thus can
be very demanding for the memory. The rough estimate for memory
requirements is 5-7 times of the size of the zone in text
format. Again this is only a estimate and you are advised to do
your own measurements before deploying Knot DNS into the
production.
</para>
</section>
<section>
<title>Supported Operating System</title>
<para>
Knot DNS itself is written in a portable way, but it depends on
userspace-rcu library, which is the main 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.
</para>
</section>
</chapter>
doc/security.xml deleted 100644 → 0
+ 0
− 10
View file @ 56346056
<chapter>
<title>Security Considerations</title>
<para>
[TODO]
- faces the internet
- Linux capabilities used
</para>
</chapter>
doc/troubleshooting.xml deleted 100644 → 0
+ 0
− 6
View file @ 56346056
<chapter>
<title>Troubleshooting</title>
<para>
Check the LOGS!
</para>
</chapter>
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