path: root/README

Dependencies
============
Knot DNS has several dependencies:
* libtool
* autoconf > 2.65
* flex >= 2.5.31
* bison >= 2.3
* libssl >= 0.9.8
* liburcu >= 0.5.4 (available as packages or as a sources from http://lttng.org/urcu)

Optional packages:
* libcap-ng >= 0.6.4 for POSIX 1003.1e capabilites(7)

Installation
============

The following steps should work (verified in VirtualBox only)
on the distribution/architecture/release combinations as listed bellow.

----------------------------------------------
Debian         (AMD64, I386) 6.0.2.1 (squeeze)
Ubuntu Server  (AMD64, I386) 10.04 LTS
Ubuntu Desktop (AMD64, I386) 10.04 LTS
----------------------------------------------

# Make the system up-to-date
$ sudo apt-get update
$ sudo apt-get upgrade

# Ensure all prerequisites are installed
$ sudo apt-get install git-core autoconf libtool flex bison libssl-dev liburcu-dev

# Install optional packages (POSIX 1003.1e capabilities)
$ sudo apt-get install libcap-ng-dev

# If the liburcu-dev package is not present, install directly
$ wget http://bd.archive.ubuntu.com/ubuntu/pool/universe/libu/liburcu/liburcu0_0.5.4-1_amd64.deb
$ wget http://bd.archive.ubuntu.com/ubuntu/pool/universe/libu/liburcu/liburcu-dev_0.5.4-1_amd64.deb
$ sudo dpkg -i liburcu0_0.5.4-1_amd64.deb
$ sudo dpkg -i liburcu-dev_0.5.4-1_amd64.deb

# Go for the real thing
$ git clone git://git.nic.cz/knot-dns.git
$ cd knot
$ autoreconf -if
$ ./configure
$ make
$ sudo make install
$ sudo ldconfig

Alternative packages for I386:
$ # the required version of liburcu is not available in the default package 
$ # sources.
$
$ wget http://bd.archive.ubuntu.com/ubuntu/pool/universe/libu/liburcu/liburcu0_0.5.4-1_i386.deb
$ wget http://bd.archive.ubuntu.com/ubuntu/pool/universe/libu/liburcu/liburcu-dev_0.5.4-1_i386.deb
$ sudo dpkg -i liburcu0_0.5.4-1_i386.deb
$ sudo dpkg -i liburcu-dev_0.5.4-1_i386.deb

Installation on BSD
===================

Not all prerequisites are available as ports on BSD.

- liburcu must be compiled from sources
  - version 0.6.4 compiles on BSD without any source code modifications
  - in case of x86_64 build, CFLAGS nad build type has to be set appropriately.
    $ CFLAGS=-fPIC ./configure --build amd64
- flex must be newer version from ports that support reentrant parsers

Knot DNS requires more recent version of flex from ports, to prevent name clash
specify flex destination.
$ cd <knot sources>
$ autoreconf -if
$ ./configure
$ make && sudo make install

It is also present in port tree, so you can install it from there.
$ cd /usr/ports/dns/knot
$ sudo make install

Installation on OpenBSD/NetBSD
==============================
Also works for OS X, if you don't want to install gcc from ports.
Prerequisites:
- liburcu needs patch for absent compiler TLS capability
  - patch is located in "scripts/urcu-tls-compat.patch"
- patch compatible with liburcu-0.6.7
- liburcu >= 0.7.0 works out of the box

$ mkdir liburcu && cd liburcu
$ wget "http://lttng.org/files/urcu/userspace-rcu-0.6.7.tar.bz2"
$ patch -p1 < ../scripts/urcu-tls-compat.patch 
$ autoconf && ./configure && make && sudo make install
$ # or follow installation instructions in INSTALL

Knot DNS installation is the same as in previous section (Installation on BSD).

Installation on OS X
====================

Not all prerequisites are preinstalled for OS X.

- liburcu must be compiled from sources
  - liburcu requires gcc-4.6 from MacPorts, as it depends on __thread keyword
  $ CC=gcc-mp-4.6 ARCH=x86_64 ./configure
  $ make && sudo make install

Compiling Knot DNS with gcc-mp-4.6 is recommended, but not necessary. 

Running
=======

First, each server needs configuration file. 
Please see samples/knot.sample.conf for reference. 
Minimal configuration can be found in samples/knot.min.conf
Configuration zone has to specify:
* storage for PID files, compiled zones etc.
* network interfaces
* served zones

$ cp samples/knot.min.conf myserver.conf
$ vim myserver.conf # or your favourite text editor

Second, zone files have to be compiled to binary form in order for server to
load them. Binary 'knotc' (controller) offers functionality for everything from
zone file management to controlling server instance. Most important parameter 
is '-c' that specifies config file for our server. Compiled zones are saved to 
storage defined in 'storage' variable in configuration.

$ knotc -h # see what it can do

Copy zone to the specified directory and compile.

$ mkdir -p /tmp/knot-minimal/samples; cp samples/example.com.zone /tmp/knot-minimal/samples/
$ knotc -c myserver.conf compile # compile zone files to binary format

Third, lets load server. You can do this by running 'knotd' directly, or with
'knotc' as well. Server is able to run in daemonized or interactive mode.
Lets start our server in interactive mode (parameter '-i') to see if it runs.

$ knotc -c myserver.conf -i start # start server in interactive mode

Running as daemon
=================

Controller runs server in daemonized mode as default. Disadvantage is, that
it closes stdout/stderr so you need to set up either syslog or logging to
own files in the configuration. Controller parameter '-w' waits for the 
operation to finish. Let's test server functionality.

$ knotc -c myserver.conf -w start # start server
$ dig @$ADDR -p $PORT example.com # issue a query and see result
$ ...
$ knotc -c myserver.conf -w stop  # stop server

Also, keep in mind that zone files have to be compiled before they are loaded
to server. Workflow is as follows:

$ knotc -c myserver.conf -w start
$ <edit zonefile>
$ knotc -c myserver.conf compile  # compile zones to binary format
$ knotc -c myserver.conf reload   # reconfigures server on-the-fly
$ dig @$ADDR -p $PORT example.com # issue a query and see result
$ ...
$ knotc -c myserver.conf stop

Supported features
==================

DNS functions:
* AXFR/IXFR (master and slave)
* EDNS0
* DNSSEC
* NSEC3
* Unknown RR types

Server features:
* Adding/removing zones on-the-fly
* Reconfiguring server instance on-the-fly
* IPv6 support
* Semantic checks of loaded zone