README.md

   1 PowerDNS is copyright © 2001-2019 by PowerDNS.COM BV and lots of
   2 contributors, using the GNU GPLv2 license (see NOTICE for the
   3 exact license and exception used).
   4
   5 All documentation can be found on http://doc.powerdns.com/
   6
   7 This file may lag behind at times. For most recent updates, always check
   8 https://doc.powerdns.com/md/changelog/.
   9
  10 Another good place to look for information is:
  11 https://doc.powerdns.com/md/appendix/compiling-powerdns/
  12
  13 To file bugs, head towards:
  14 https://github.com/PowerDNS/pdns/issues
  15
  16 But please check if the issue is already reported there first.
  17
  18 SOURCE CODE / GIT
  19 -----------------
  20 Source code is available on GitHub:
  21
  22 ```sh
  23 git clone https://github.com/PowerDNS/pdns.git
  24 ```
  25
  26 This repository contains the sources for the PowerDNS Recursor, the PowerDNS
  27 Authoritative Server, and dnsdist (a powerful DNS loadbalancer). All three can
  28 be built from this repository. However, all three released separately as .tar.bz2,
  29 .deb and .rpm.
  30
  31 COMPILING Authoritative Server
  32 ------------------------------
  33 The PowerDNS Authoritative Server depends on Boost, OpenSSL and requires a
  34 compiler with C++-2011 support.
  35
  36 On Debian 9, the following is useful:
  37
  38 ```sh
  39 apt install g++ libboost-all-dev libtool make pkg-config default-libmysqlclient-dev libssl-dev virtualenv
  40 ```
  41
  42 When building from git, the following packages are also required:
  43
  44 ```sh
  45 apt install autoconf automake ragel bison flex
  46 ```
  47
  48 For Ubuntu 18.04 (Bionic Beaver), the following packages should be installed:
  49
  50 ```sh
  51 apt install libcurl4-openssl-dev luajit lua-yaml-dev libyaml-cpp-dev libtolua-dev lua5.3 autoconf automake ragel bison flex g++ libboost-all-dev libtool make pkg-config libssl-dev virtualenv lua-yaml-dev libyaml-cpp-dev libluajit-5.1-dev libcurl4 gawk
  52 # For DNSSEC ed25519 (algorithm 15) support with --with-libsodium
  53 apt install libsodium-dev
  54 # If using the gmysql (Generic MySQL) backend
  55 apt install default-libmysqlclient-dev
  56 # If using the gpgsql (Generic PostgreSQL) backend
  57 apt install postgresql-server-dev-10
  58 # If using --enable-systemd (will create the service scripts so it can be managed with systemctl/service)
  59 apt install libsystemd0 libsystemd-dev
  60 # If using the geoip backend
  61 apt install libmaxminddb-dev libmaxminddb0 libgeoip1 libgeoip-dev
  62 ```
  63
  64 Then generate the configure file:
  65
  66 ```sh
  67 autoreconf -vi
  68 ```
  69
  70 To compile a very clean version, use:
  71
  72 ```sh
  73 ./configure --with-modules="" --without-lua --disable-lua-records
  74 make
  75 # make install
  76 ```
  77
  78 This generates a PowerDNS Authoritative Server binary with no modules built in.
  79
  80 See https://doc.powerdns.com/authoritative/backends/index.html for a list of available modules.
  81
  82 When `./configure` is run without `--with-modules`, the bind and gmysql module are
  83 built-in by default and the pipe-backend is compiled for runtime loading.
  84
  85 To add multiple modules, try:
  86
  87 ```sh
  88 ./configure --with-modules="bind gmysql gpgsql"
  89 ```
  90
  91 Note that you will need the development headers for PostgreSQL as well in this case.
  92
  93 See https://doc.powerdns.com/authoritative/appendices/compiling.html for more details.
  94
  95 If you run into C++11-related symbol trouble, please try passing `CPPFLAGS=-D_GLIBCXX_USE_CXX11_ABI=0` (or 1) to `./configure` to make sure you are compatible with the installed dependencies.
  96
  97 Compiling the Recursor
  98 ----------------------
  99 See [README.md](pdns/recursordist/README.md) in `pdns/recursordist/`.
 100
 101 Compiling dnsdist
 102 -----------------
 103 See [README-dnsdist.md](pdns/README-dnsdist.md) in `pdns/`.
 104
 105 Building the HTML documentation
 106 -------------------------------
 107
 108 The HTML documentation (as seen [on the PowerDNS docs site](https://doc.powerdns.com/authoritative/)) is built from ReStructured Text (rst) files located in `docs`. They are compiled into HTML files using [Sphinx](http://www.sphinx-doc.org/en/master/index.html), a documentation generator tool which is built in Python.
 109
 110 **Using a normal Python installation**
 111
 112 For those simply contributing to the documentation, this avoids needing to install the various build
 113 tools and other dependencies.
 114
 115 Install Python 2.7 or Python 3 (preferable) if you don't yet have it installed. On some operating
 116 systems you may also have to install `python3-pip` or similarly named.
 117
 118 Ubuntu 16.04 / 18.04
 119
 120 ```sh
 121 apt update
 122 apt install python3 python3-pip python3-venv
 123 ```
 124
 125 macOS (using homebrew)
 126
 127 ```sh
 128 brew install python3
 129 ```
 130
 131 Update your `pip` and install/update `virtualenv` to avoid problems:
 132
 133 ```sh
 134 # for python2, use "pip" instead of "pip3"
 135 pip3 install -U pip
 136 pip3 install -U virtualenv
 137 ```
 138
 139 Enter the repository's `docs` folder, set up the virtualenv, and install the requirements
 140
 141 ```sh
 142 cd docs
 143 # for python2, use "virtualenv .venv" instead
 144 python3 -m venv .venv
 145 source .venv/bin/activate
 146 # The virtualenv may use an older pip, so upgrade it again
 147 pip3 install -U pip setuptools setuptools-git
 148 # Now you can install the requirements
 149 pip3 install -r requirements.txt
 150 ```
 151
 152 Finally, you can build the documentation:
 153
 154 ```sh
 155 sphinx-build . html-docs
 156 ```
 157
 158 Note: If your shell has problems finding sphinx-build, try using `.venv/bin/sphinx-build` instead.
 159
 160 The HTML documentation is now available in `html-docs`.
 161
 162 **Using the build tools**
 163
 164 This method is preferable for those who already have a working build environment for PowerDNS.
 165
 166 Install the dependencies under "COMPILING", and run autoreconf if you haven't already:
 167
 168 ```sh
 169 autoreconf -vi
 170 ```
 171
 172 Enter the `docs` folder, and use make to build the HTML docs.
 173
 174 ```
 175 cd docs
 176 make html-docs
 177 ```
 178
 179 The HTML documentation will now be available in `html-docs`.
 180
 181 Solaris Notes
 182 -------------
 183 Use a recent gcc. OpenCSW is a good source, as is Solaris 11 IPS.
 184
 185 If you encounter problems with the Solaris make, gmake is advised.
 186
 187 FreeBSD Notes
 188 -------------
 189 You need to compile using gmake - regular make only appears to work, but doesn't in fact. Use gmake, not make.
 190
 191 The clang compiler installed through FreeBSD's package manager does not expose all of the C++11 features needed under `std=gnuc++11`. Force the compiler to use `std=c++11` mode instead.
 192
 193 ```sh
 194 export CXXFLAGS=-std=c++11
 195 ```
 196
 197 macOS Notes
 198 -----------
 199 PowerDNS Authoritative Server is available through Homebrew:
 200
 201 ```
 202 brew install pdns
 203 ```
 204
 205 If you want to compile yourself, the dependencies can be installed using
 206 Homebrew. You need to tell configure where to find OpenSSL, too.
 207
 208 ```sh
 209 brew install boost lua pkg-config ragel openssl
 210 ./configure --with-modules="" --with-lua PKG_CONFIG_PATH=/usr/local/opt/openssl/lib/pkgconfig
 211 make -j4
 212 ```
 213
 214 Additionally, for PostgreSQL support, run `brew install postgresql` and add `--with-modules="gpgsql"` to `./configure`.
 215 For MySQL support, run `brew install mariadb` and add `--with-modules="gmysql"` to `./configure`.
 216
 217 Linux notes
 218 -----------
 219 None really.