Skip to content
Snippets Groups Projects
Commit 4078f150 authored by Daniel Salzman's avatar Daniel Salzman
Browse files

doc: unify installation, update introduction, and extend migration

parent db1195a8
Branches
Tags v4.1.0
No related merge requests found
Hide whitespace changes
Inline Side-by-side
README
+ 6
− 38
View file @ 4078f150
Dependencies
Requirements
============
Knot DNS has several dependencies:
* libtool
* autoconf > 2.65
* pkg-config
* liburcu >= 0.5.4
* gnutls >= 3.0
* libedit
Embedded libraries:
* lmdb (system library is preferred)
Optional packages:
* libcap-ng >= 0.6.4 (for POSIX 1003.1e capabilities(7))
* libidn (for IDNA2003 support in Knot utilities)
* libsystemd (for systemd init system support)
Dependencies for building documentation:
* python-sphinx
./doc/requirements.rst
Installation
============
Knot DNS may already be included in your operating system distribution and
therefore can be installed from packages (Linux), ports (BSD) or via
Homebrew (Mac). This is always preferred unless you want to test the latest
features, contribute to Knot development, or you just know what you are doing.
Following sections describe how to build Knot DNS from the source code.
./doc/installation.rst
1) Install prerequisites
......@@ -72,10 +50,6 @@ with newer GnuTLS is required instead of gnutls-devel.
2) Install Knot DNS
Knot DNS requires compiler to support atomic intrinsics.
GCC version at least 4.1 supports legacy atomic builtins, however 4.7
or newer is preferred. Clang supports atomics since version 2.9.
Get the source code:
$ git clone git://git.nic.cz/knot-dns.git
Or extract source package to knot-dns directory
......@@ -90,15 +64,15 @@ Install Knot DNS into system:
$ sudo make install
$ sudo ldconfig
NOTE: If you want to reduce zscanner compile time, use configure option --disable-fastparser.
Running
=======
./doc/operation.rst
1) Each server needs configuration file. Please see samples/knot.sample.conf,
project documentation, or man 5 knot.conf for more details.
Configuration file has to specify:
- storage for PID files, journal files etc.
- storage for PID files, journal and timer databases etc.
- network interfaces
- served zones
......@@ -117,9 +91,3 @@ installed Knot using a binary package.
Start Knot in the foreground to see if it runs:
$ knotd -c myserver.conf
For more information, refer to the user manual or:
$ knotc -h
$ knotd -h
Join the chat at https://gitter.im/CZ-NIC/knot
doc/installation.rst
+ 30
− 133
View file @ 4078f150
......@@ -5,61 +5,42 @@
Installation
************
.. _Required build environment:
.. _Installation from a package_:
Required build environment
==========================
GCC at least 4.1 is strictly required for atomic built-ins, but the latest
available version is recommended. Another requirement is ``_GNU_SOURCE``
support, otherwise it adapts to the compiler available features.
LLVM clang compiler can be used as well. However, the compilation with
enabled optimizations will take a long time, unless the ``--disable-fastparser``
configure option is given.
Knot DNS build system relies on these standard tools:
* make
* libtool
* autoconf >= 2.65
Installation from a package
===========================
.. _Required libraries:
Knot DNS may already be included in your operating system distribution and
therefore can be installed from packages (Linux), ports (BSD), or via
Homebrew (macOS). This is always preferred unless you want to test the latest
features, contribute to Knot development, or you just know what you are doing.
Required libraries
==================
See the project `download <https://www.knot-dns.cz/download>`_ page for
the latest information.
Knot DNS requires few libraries to be compiled:
.. _Installation from the source code:
* GnuTLS, at least 3.3
* Userspace RCU, at least 0.5.4
* libedit
* lmdb (included)
* libcap-ng, at least 0.6.4 (optional)
* libidn (optional)
* libsystemd (optional)
* protobuf-c and fstrm (optional)
Installation from the source code
=================================
The LMDB library is required. It is included with the Knot DNS source code,
however linking with the system library is preferred.
If the libcap-ng library is available, Knot DNS will take advantage of the
POSIX 1003.1e :manpage:`capabilites(7)` by sandboxing the exposed threads.
Most rights are stripped from the exposed threads for security reasons.
The libidn library is a prerequisite for IDNA2003 (International Domain Names)
support in Knot DNS utilities.
Required build environment
--------------------------
If the libsystemd library is available, the server will use systemd's startup
notifications mechanism and journald for logging.
The build process relies on these standard tools:
If the protobuf-c and fstrm libraries are available, the support for logging
in Dnstap format will be included.
* make
* libtool
* pkg-config
* autoconf >= 2.65
* python-sphinx (optional, for documentation building)
.. _Installation from source code:
GCC at least 4.1 is strictly required for atomic built-ins, but the latest
available version is recommended. Another requirements ``_GNU_SOURCE``
and C99 support, otherwise it adapts to the compiler available features.
LLVM clang compiler since version 2.9 can be used as well.
Installation from source code
=============================
Getting the source code
-----------------------
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
......@@ -94,6 +75,10 @@ files::
$ make
.. NOTE::
The compilation with enabled optimizations may take a long time. In such
a case the ``--disable-fastparser`` configure option can help.
Installation
------------
......@@ -105,91 +90,3 @@ 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'``.
.. _OS specific installation:
OS specific installation
========================
Knot DNS might already be available in the destination operating system
repository.
Debian Linux
------------
Knot DNS is already available from Debian 7 (Wheezy) upwards. In addition
to the official packages we also provide custom repository, which can
be used by adding::
deb http://deb.knot-dns.cz/debian/ <codename> main
deb-src http://deb.knot-dns.cz/debian/ <codename> main
to your ``/etc/apt/sources.list`` or into separate file in
``/etc/apt/sources.list.d/``.
As an example, for Debian 8 (Jessie) the Knot DNS packages can be added by
executing following command as the root user::
# cat >/etc/apt/sources.list.d/knot.list <<EOF
deb http://deb.knot-dns.cz/debian/ jessie main
deb-src http://deb.knot-dns.cz/debian/ jessie main
EOF
# apt-get update
# apt-get install knot
Ubuntu Linux
------------
Prepackaged version of 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 in order to upgrade to the last stable version of Knot DNS or to install
it on older versions of Ubuntu Linux.
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::
$ sudo add-apt-repository ppa:cz.nic-labs/knot-dns
$ sudo apt-get update
$ sudo apt-get install knot
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.
Fedora Linux
------------
The RPM packages for Knot DNS are available in official Fedora
repositories since Fedora 18 (Spherical Cow). Search for the ``knot``
package in your package manager. To install the package using Yum, run
the following command as the root user::
# yum install knot
Arch Linux
----------
Knot DNS is available in the official package repository (AUR). To install the
package, run::
# pacman -S knot
Gentoo Linux
------------
Knot DNS is also available in the Gentoo package repository. However, you will
probably need to unmask the package prior to starting the installation::
# emerge -a knot
FreeBSD
-------
Knot DNS is in ports tree under ``dns/knot``. To install the port, run::
# cd /usr/ports/dns/knot
# make install
doc/introduction.rst
+ 30
− 31
View file @ 4078f150
......@@ -10,53 +10,52 @@ What is Knot DNS
Knot DNS is a high-performance open-source DNS server. It
implements only the authoritative domain name service. Knot DNS
is best suited for use on TLD domains but it can reliably serve
any other zones as well.
can reliably serve TLD domains as well as any other zones.
Knot DNS benefits from its multi-threaded and mostly lock-free
implementation which allows it to scale well on SMP systems and
operate non-stop even when adding or removing zones.
For more info and downloads see `www.knot-dns.cz <https://www.knot-dns.cz>`_.
Knot DNS features
=================
DNS features:
* IN class and partially CH class
* TCP/UDP protocols
* AXFR, IXFR – master, slave
* TSIG
* EDNS0
* DNSSEC, including NSEC3
* NSID
* Dynamic updates
* Response Rate Limiting
* RR types A, NS, CNAME, SOA, PTR, HINFO, MINFO, MX, TXT, RP, AFSDB, RT, KEY,
AAAA, LOC, SRV, NAPTR, KX, CERT, DNAME, APL, DS, SSHFP, IPSECKEY, RRSIG, NSEC,
DNSKEY, DHCID, NSEC3, NSEC3PARAM, TLSA, CDS, CDNSKEY, SPF, NID, L32, L64, LP,
EUI48, EUI64, URI, CAA and Unknown
* Master and slave operation
* Internet class (IN)
* DNS extension (EDNS0)
* TCP and UDP protocols
* Dynamic zone updates
* DNSSEC with NSEC and NSEC3
* Transaction signature using TSIG
* Full and incremental zone transfers (AXFR, IXFR)
* Name server identification using NSID or Chaos TXT records
* Resource record types A, NS, CNAME, SOA, PTR, HINFO, MINFO, MX,
TXT, RP, AFSDB, RT, KEY, AAAA, LOC, SRV, NAPTR, KX, CERT, DNAME, APL, DS,
SSHFP, IPSECKEY, RRSIG, NSEC, DNSKEY, DHCID, NSEC3, NSEC3PARAM, TLSA, CDS,
CDNSKEY, SPF, NID, L32, L64, LP, EUI48, EUI64, URI, CAA, and Unknown
Server features:
* Adding/removing/editing zones on-the-fly
* Reconfiguring server instance on-the-fly
* Dynamic configuration
* IPv4 and IPv6 support
* Semantic checks of zones
* DDNS support
* Persistent zone timers
* Automatic DNSSEC signing
* PKCS #11 interface
* Forward and reverse records synthesis
* DNS request traffic statistics
* Semantic zone checks
* Server control interface
* Zone journal storage
* Persistent zone event timers
* YAML-based or database-based configuration
* Query processing modules with dynamic loading
* On-the-fly zone management and server reconfiguration
* Automatic DNSSEC signing with automatic key maganement and PKCS #11 interface
For more info and downloads see `www.knot-dns.cz <https://www.knot-dns.cz>`_.
Remarkable module extensions:
Git repository: `git://git.nic.cz/knot-dns.git <https://gitlab.labs.nic.cz/labs/knot/tree/master>`_
Knot DNS issue tracker: `gitlab.labs.nic.cz/labs/knot/issues <https://gitlab.labs.nic.cz/labs/knot/issues>`_
Knot DNS users mailing list: `knot-dns-users@lists.nic.cz <mailto:knot-dns-users@lists.nic.cz>`_
* Response rate limiting
* Forward and reverse records synthesis
* DNS request traffic statistics
* Dnstap traffic logging
* Online DNSSEC signing
License
=======
......
doc/migration.rst
+ 22
− 3
View file @ 4078f150
......@@ -5,14 +5,33 @@
Migration
*********
.. _Upgrade comments 2.4 to 2.5:
.. _Upgrade 2.4.x to 2.5.x:
Upgrade comments 2.4 to 2.5
===========================
Upgrade 2.4.x to 2.5.x
======================
This chapter describes some steps necessary after upgrading Knot DNS from
version 2.4.x to 2.5.x.
.. _Building changes:
Building changes
----------------
The ``--enable-dnstap`` configure option now enables the dnstap support in
kdig only! To build the dnstap query module, ``--with-module-dnstap`` have
to be used.
Since Knot DNS version 2.5.0 each query module can be configured to be:
- disabled: ``--with-module-``\ MODULE_NAME\ ``=no``
- embedded: ``--with-module-``\ MODULE_NAME\ ``=yes``
- external: ``--with-module-``\ MODULE_NAME\ ``=shared`` (excluding
``dnsproxy`` and ``onlinesign``)
The ``--with-timer-mapsize`` configure option was replaced with the runtime
:ref:`template_max-timer-db-size` configuration option.
.. _KASP DB migration:
KASP DB migration
......
doc/requirements.rst
+ 51
− 12
View file @ 4078f150
......@@ -13,26 +13,33 @@ 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
administrator's attention and a testing of exact requirements before
deploying Knot DNS to a production environment. These cases include deployment for a
large number of zones (DNS hosting), large number of records in one
or more zones (TLD) or large number of requests.
administrator's attention and some testing of exact requirements before
deploying Knot DNS to a production environment. These cases include
deployment for a large number of zones (DNS hosting), large number
of records in one or more zones (TLD), or large number of requests.
CPU requirements
----------------
Knot DNS scales with processing power and also with the number of
available cores/CPUs.
The server scales with processing power and also with the number of
available cores/CPUs. Enabling Hyper-threading is convenient if supported.
There is no lower bound on the CPU requirements, but it should support
memory barriers and CAS (i586 and newer).
Network card
------------
The best results have been achieved with multi-queue network cards. The
number of multi-queues should equal the total number of CPU cores (with
Hyper-threading enabled).
Memory requirements
-------------------
Knot DNS implementation focuses on performance and thus can be quite
The server implementation focuses on performance and thus can be quite
memory demanding. The rough estimate for memory requirements is
3 times the size of the zone in text format. Again this is only
3 times the size of the zone in the text format. Again this is only
an estimate and you are advised to do your own measurements before
deploying Knot DNS to production.
......@@ -45,7 +52,39 @@ deploying Knot DNS to production.
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
when it comes to the operating system support. Knot DNS can be compiled
and run on most UNIX-like systems, such as Linux, \*BSD, and OS X.
Knot DNS itself is written in a portable way and can be compiled
and run on most UNIX-like systems, such as Linux, \*BSD, and macOS.
Required libraries
==================
Knot DNS requires a few libraries to be available:
* libedit
* GnuTLS >= 3.3
* Userspace RCU >= 0.5.4
* lmdb >= 0.9.15
.. NOTE::
The LMDB library is included with the Knot DNS source code, however linking
with the system library is preferred.
Optional libraries
==================
International Domain Names support (IDNA2003 or IDNA2008) in kdig:
* libidn or libidn2
Systemd's startup notifications mechanism and journald logging:
* libsystemd
Dnstap support in kdig and module dnstap:
* fstrm (and protobuf-c if building from the source code)
POSIX 1003.1e :manpage:`capabilites(7)` by sandboxing the exposed threads.
Most rights are stripped from the exposed threads for security reasons.
* libcap-ng >= 0.6.4
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