Compiling :program:`PowerDNS Recursor`
======================================

.. versionchanged:: 5.5.0
   Support for autotools and make have been removed, use the ``meson`` instructions.

As :program:`PowerDNS Recursor` is distributed with a configure script, compiling it is a matter of::

  tar xf pdns-recursor-$VERSION.tar.bz2
  cd pdns-recursor-$VERSION
  ./configure
  make
  make install

Or when building using meson::

  tar xf pdns-recursor-$VERSION.tar.bz2
  cd pdns-recursor-$VERSION
  meson setup build
  meson compile -C build
  meson install -C build

Getting the sources
-------------------

.. warning::
   Do not use the tarballs auto-generated by GitHub from the tags, as these are not proper release tarballs.

There are 3 ways of getting the source.

If you want the bleeding edge, you can clone the `repository at GitHub <https://github.com/PowerDNS/pdns>`__ and run ``autoreconf -vi`` in the ``pdns/recursordist`` directory of the clone.

You can also download `snapshot tarballs <https://downloads.powerdns.com/autobuilt_browser/#/recursor>`__.

You can also download releases on the `website <https://downloads.powerdns.com/releases/>`__.
These releases are PGP-signed with one of these key-ids:

.. include:: ../common/tarball-pgp-keys.rst

Dependencies
------------

To build :program:`PowerDNS Recursor`, a C++ compiler with support for C++ 2017 is required.
This means ``gcc 5`` and newer and ``clang 5`` and newer.
Furthermore, the Makefiles require GNU ``make``, not BSD ``make``.
Building using ``meson`` is also supported.
Starting with version 5, a Rust compiler is needed.

By default, the :program:`Recursor` requires the following libraries and headers:

* `Boost <https://boost.org/>`_ 1.54 or newer
* `Lua <https://www.lua.org/>`_ 5.1+ or `LuaJit <https://luajit.org/>`_
* `OpenSSL <https://openssl.org>`_
* For :program:`Recursor` version 5 and higher, `cargo <https://www.rust-lang.org/tools/install>`_. Minimum version depends on the version of Recursor being build.

.. note::
   On Debian and Ubuntu, the following will get you the dependencies::

      apt-get install libboost-dev libboost-filesystem-dev libboost-serialization-dev \
         libboost-thread-dev libboost-context-dev \
         libboost-test-dev libssl-dev libboost-test-dev g++ make pkg-config \
         libluajit-5.1-dev cargo

Compiling from a git checkout
-----------------------------
Source code is available on GitHub::

   git clone https://github.com/PowerDNS/pdns.git

This repository contains the sources for the PowerDNS Recursor, the PowerDNS
Authoritative Server, and dnsdist (a powerful DNS loadbalancer). The sources for
the recursor are located in the `pdns/recursordist` subdirectory of the repository.

To compile from a git checkout using autotools install the dependencies above plus::

  apt-get install ragel automake autoconf libtool virtualenv curl

Then run::

    cd pdns/pdns/recursordist/
    autoreconf -vi
    ./configure
    make

To compile from a git checkout using meson install the dependencies above plus::

  apt-get install ragel meson virtualenv curl rustc

Then run::

    cd pdns/pdns/recursordist/
    meson setup builddir
    meson compile -C builddir

macOS Notes
-----------

If you want to compile yourself, the dependencies can be installed using
Homebrew. You need to tell configure where to find OpenSSL, too::

    brew install boost lua pkg-config ragel openssl
    ./configure PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig
    make -j4

meson is capable of finding openssl itself::

    brew install boost lua meson pkg-config ragel rust openssl
    meson setup build
    meson compile -C build

Optional dependencies
---------------------

Several options that can be passed to ``./configure`` or ``meson setup`` can enable and disable different features.
These will require additional dependencies.
To list the options run ``./configure --help`` or ``meson configure``.

ed25519 support with libsodium
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The :program:`Recursor` can link with `libsodium <https://download.libsodium.org/doc/>`_ to support ed25519 (DNSSEC algorithm 15).
To detect libsodium, use the ``--with-libsodium`` configure option or ``-Dlibsodium=auto`` for meson, which is the default.

Protobuf to emit DNS logs
^^^^^^^^^^^^^^^^^^^^^^^^^

The :program:`Recursor` can log DNS query information over :doc:`Protocol Buffers <../lua-config/protobuf>`.

This functionality is available from 4.5.0 and upwards without needing any external library.

``systemd`` notify support
^^^^^^^^^^^^^^^^^^^^^^^^^^

During configure, ``configure`` will attempt to detect the availability of `systemd or systemd-daemon <https://freedesktop.org/wiki/Software/systemd/>`_ headers.
To force the use of ``systemd`` (and failing configure if the headers do not exist), use ``--enable-systemd``.
To set the directory where the unit files should be installed, use ``--with-systemd=/path/to/unit/dir``.

.. note::
   If you want systemd support, you will need to install the corresponding development package. On Debian and Ubuntu, this means `apt install libsystemd-dev`.

Documentation
-------------
After compiling, run `pdns\_recursor --config` to view the configuration options
and a short description. The full documentation is online at
https://doc.powerdns.com/recursor/