pdns/dnsdistdist/docs/install.rst

   1 Installing dnsdist
   2 ==================
   3
   4 dnsdist only runs on UNIX-like systems and there are several ways to install dnsdist.
   5 The fastest way is using packages, either from your own operating system vendor or supplied by the PowerDNS project.
   6 Building from source is also supported.
   7
   8
   9 Installing from Packages
  10 ------------------------
  11
  12 If dnsdist is available in your operating system's software repositories, install it from there.
  13 However, the version of dnsdist in the repositories might be an older version that might not have a feature that was added in a later version.
  14 Or you might want to be brave and try a development snapshot from the master branch.
  15 PowerDNS provides software repositories for the most popular distributions.
  16 Visit https://repo.powerdns.com for more information and installation instructions.
  17
  18 Debian
  19 ~~~~~~
  20
  21 For Debian and its derivatives (like Ubuntu) installing the ``dnsdist`` package should do it:
  22
  23 .. code-block:: sh
  24
  25   apt-get install -y dnsdist
  26
  27 Red Hat
  28 ~~~~~~~
  29
  30 For Red Hat, CentOS and its derivatives, dnsdist is available in `EPEL <https://fedoraproject.org/wiki/EPEL>`_:
  31
  32 .. code-block:: sh
  33
  34   yum install -y epel-release
  35   yum install -y dnsdist
  36
  37 FreeBSD
  38 ~~~~~~~
  39
  40 dnsdist is also available in `FreeBSD ports <http://www.freshports.org/dns/dnsdist/>`_.
  41
  42 Installing from Source
  43 ----------------------
  44
  45 In order to compile dnsdist, a modern compiler with C++ 2017 support and GNU make are required.
  46 dnsdist depends on the following libraries:
  47
  48 * `Boost <http://boost.org/>`_
  49 * `Lua <http://www.lua.org/>`_ 5.1+ or `LuaJit <http://luajit.org/>`_
  50 * `Editline (libedit) <http://thrysoee.dk/editline/>`_
  51 * `libfstrm <https://github.com/farsightsec/fstrm>`_ (optional, dnstap support)
  52 * `GnuTLS <https://www.gnutls.org/>`_ (optional, DoT and outgoing DoH support)
  53 * `libh2o <https://github.com/h2o/h2o>`_ (optional, incoming DoH support)
  54 * `libcap <https://sites.google.com/site/fullycapable/>`_ (optional, capabilities support)
  55 * `libsodium <https://download.libsodium.org/doc/>`_ (optional, DNSCrypt and console encryption support)
  56 * `LMDB <http://www.lmdb.tech/doc/>`_ (optional, LMDB support)
  57 * `net-snmp <http://www.net-snmp.org/>`_ (optional, SNMP support)
  58 * `nghttp2 <https://nghttp2.org/>`_ (optional, outgoing DoH support)
  59 * `OpenSSL <https://www.openssl.org/>`_ (optional, DoT and DoH support)
  60 * `protobuf <https://developers.google.com/protocol-buffers/>`_ (optional, not needed as of 1.6.0)
  61 * `re2 <https://github.com/google/re2>`_ (optional)
  62 * `TinyCDB <https://www.corpit.ru/mjt/tinycdb.html>` (optional, CDB support)
  63
  64 Should :program:`dnsdist` be run on a system with systemd, it is highly recommended to have
  65 the systemd header files (``libsystemd-dev`` on Debian and ``systemd-devel`` on CentOS)
  66 installed to have :program:`dnsdist` support ``systemd-notify``.
  67
  68 From tarball
  69 ~~~~~~~~~~~~
  70
  71 Release tarballs are available `from the downloads site <https://downloads.powerdns.com/releases>`_, snapshot and pre-release tarballs `can be found as well <https://downloads.powerdns.com/autobuilt_browser/#/dnsdist>`__.
  72
  73 The release tarballs have detached PGP signatures, signed by one of these PGP keys:
  74
  75 * `D630 0CAB CBF4 69BB E392 E503 A208 ED4F 8AF5 8446 <https://pgp.mit.edu/pks/lookup?op=get&search=0xA208ED4F8AF58446>`__
  76 * `FBAE 0323 821C 7706 A5CA 151B DCF5 13FA 7EED 19F3 <https://pgp.mit.edu/pks/lookup?op=get&search=0xDCF513FA7EED19F3>`__
  77 * `1628 90D0 689D D12D D33E 4696 1C5E E990 D2E7 1575 <https://pgp.mit.edu/pks/lookup?op=get&search=0x1C5EE990D2E71575>`__
  78 * `B76C D467 1C09 68BA A87D E61C 5E50 715B F2FF E1A7 <https://pgp.mit.edu/pks/lookup?op=get&search=0x5E50715BF2FFE1A7>`__
  79 * `16E1 2866 B773 8C73 976A 5743 6FFC 3343 9B0D 04DF <https://pgp.mit.edu/pks/lookup?op=get&search=0x6FFC33439B0D04DF>`__
  80
  81 There is a PGP keyblock with these keys available on `https://dnsdist.org/_static/dnsdist-keyblock.asc <https://dnsdist.org/_static/dnsdist-keyblock.asc>`__.
  82
  83 * Untar the tarball and ``cd`` into the source directory
  84 * Run ``./configure``
  85 * Run ``make`` or ``gmake`` (on BSD)
  86
  87 From git
  88 ~~~~~~~~
  89
  90 To compile from git, these additional dependencies are required:
  91
  92 * GNU `Autoconf <http://www.gnu.org/software/autoconf/autoconf.html>`_
  93 * GNU `Automake <https://www.gnu.org/software/automake/>`_
  94 * `Ragel <http://www.colm.net/open-source/ragel/>`_
  95
  96 dnsdist source code lives in the `PowerDNS git repository <https://github.com/PowerDNS/pdns>`_ but is independent of PowerDNS.
  97
  98 ::
  99
 100   git clone https://github.com/PowerDNS/pdns.git
 101   cd pdns/pdns/dnsdistdist
 102   autoreconf -i
 103   ./configure
 104   make
 105
 106 OS Specific Instructions
 107 ~~~~~~~~~~~~~~~~~~~~~~~~
 108
 109 None, really.
 110
 111 Build options
 112 ~~~~~~~~~~~~~
 113
 114 Our ``configure`` script provides a fair number of options with regard to which features should be enabled, as well as which libraries should be used. In addition to these options, more features can be disabled at compile-time by defining the following symbols:
 115
 116 * ``DISABLE_BUILTIN_HTML`` removes the built-in web pages
 117 * ``DISABLE_CARBON`` for carbon support
 118 * ``DISABLE_COMPLETION`` for completion support in the console
 119 * ``DISABLE_DEPRECATED_DYNBLOCK`` for legacy dynamic blocks not using the new ``DynBlockRulesGroup`` interface
 120 * ``DISABLE_ECS_ACTIONS`` to disable actions altering EDNS Client Subnet
 121 * ``DISABLE_LUA_WEB_HANDLERS`` for custom Lua web handlers support
 122 * ``DISABLE_PROMETHEUS`` for prometheus
 123 * ``DISABLE_PROTOBUF`` for protocol-buffer support, including dnstap
 124 * ``DISABLE_RECVMMSG`` for ``recvmmsg`` support
 125 * ``DISABLE_RULES_ALTERING_QUERIES`` to remove rules altering the content of queries
 126 * ``DISABLE_SECPOLL`` for security polling
 127 * ``DISABLE_WEB_CONFIG`` to disable accessing the configuration via the web interface
 128
 129 Additionally several Lua bindings can be removed when they are not needed, as they increase the memory required during compilation and the size of the final binary:
 130
 131 * ``DISABLE_CLIENT_STATE_BINDINGS``
 132 * ``DISABLE_COMBO_ADDR_BINDINGS``
 133 * ``DISABLE_DNSHEADER_BINDINGS``
 134 * ``DISABLE_DNSNAME_BINDINGS``
 135 * ``DISABLE_DOWNSTREAM_BINDINGS``
 136 * ``DISABLE_NETMASK_BINDINGS``
 137 * ``DISABLE_NON_FFI_DQ_BINDINGS``
 138 * ``DISABLE_PACKETCACHE_BINDINGS``
 139 * ``DISABLE_POLICIES_BINDINGS``
 140 * ``DISABLE_QPS_LIMITER_BINDINGS``
 141 * ``DISABLE_SUFFIX_MATCH_BINDINGS``
 142 * ``DISABLE_TOP_N_BINDINGS``