path: root/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
@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