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

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>`_ version 1.64 or newer.

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

      apt-get install libboost-dev libboost-filesystem-dev libboost-serialization-dev \
         libboost-system-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 rust

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 from 4.5.0 and upwards, without needing any external library. Before 4.5.0, installing the  `protobuf <https://developers.google.com/protocol-buffers/>`_ library and compiler is required to enable this functionality. The configure script will automatically detect this and bump the Boost version dependency to 1.42. To disable building this functionality before 4.5.0, use ``--without-protobuf``.

``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/