Docker-README.md

   1 # Intro
   2
   3 https://hub.docker.com/u/powerdns offers automatic builds of dnsdist, Auth and Recursor, from the pdns.git master branch.
   4
   5 The images are based on Debian Buster (slim).
   6
   7 The Dockerfiles:
   8
   9 * https://github.com/PowerDNS/pdns/blob/master/Dockerfile-auth
  10 * https://github.com/PowerDNS/pdns/blob/master/Dockerfile-dnsdist
  11 * https://github.com/PowerDNS/pdns/blob/master/Dockerfile-recursor
  12
  13 Other data involved in the Docker build process can be found at https://github.com/PowerDNS/pdns/tree/master/dockerdata
  14
  15 > **Note**
  16 > If you are building the Dockerfiles directly from the git repo, make sure you run `git submodule init` followed by `git submodule update` first.
  17
  18 # Usage
  19
  20 The images are ready to run with limited functionality.
  21 At container startup, the startup.py wrapper (from the dockerdata directory linked above) checks for `PDNS_RECURSOR_API_KEY` / `PDNS_AUTH_API_KEY` / `DNSDIST_API_KEY` environment variables for the product you are running.
  22 If such a variable is found, `/etc/powerdns-api.conf` or `/etc/dnsdist-api.conf` is written, enabling the webserver in all products, and the dnsdist console.
  23 For the dnsdist console, make sure that your API key is in a format suitable for the console (use `makeKey()`).
  24
  25 The default configs shipped in the image (see dockerdata above) parse all files in `/etc/powerdns/pdns.d` / `/etc/powerdns/recursor.d` / `/etc/dnsdist/conf.d`.
  26 The image also ships a symlink to the API config file inside those `.d` dirs.
  27 For Auth and Recursor, extra configuration can be passed on the command line, or via a volume mount into `/etc/powerdns` or the `.d` dir.
  28 For dnsdist, only the volume mount is applicable.
  29
  30 If you want to volume mount a config, but also take the keys from the environment, please take care to include the same `X-api.conf` symlink in your `.d` directory.
  31
  32 # Auth and databases
  33
  34 The default auth config uses SQLite3 in `/var/lib/powerdns/pdns.sqlite3`.
  35 We suggest providing that file via a volume.
  36 For other databases, either pass config overrides on the command line, or mount a config file.
  37
  38 ## LMDB
  39
  40 When using the LMDB backend with the auth image, please make sure that any containers that might access the database volume do not have overlapping PIDs - otherwise you will get locking problems and possibly resulting corruption.
  41 In a plain Docker or Compose setup, this can be done by using the host PID namespace.
  42
  43 # Compose example
  44
  45 We have a Docker Compose example at https://github.com/PowerDNS/pdns/blob/master/docker-compose.yml.
  46 It brings up all three services, and exposes them to each other by name (using Docker's internal DNS).
  47 In the dockerdata dir, you can find an example dnsdist Lua config (with Python helper to make DNS lookups non-blocking for dnsdist) for managing your auth/rec backends by name.
  48
  49 # Privileged ports
  50
  51 The default configurations included for dnsdist, Auth and Recursor attempt to bind to port 53, which may not be permitted by the platform on which you intend to use these images. Kubernetes clusters, for example, might have a restriction on binding to privileged ports unless the `NET_BIND_SERVICE` capability is explicitly added to the container's security context.
  52
  53 There are multiple ways of dealing with these restrictions if you encounter them:
  54
  55 * Grant the `NET_BIND_SERVICE` capability to the containers which utilize these images
  56 * Use custom configuration files to bind to alternate ports outside of the privileged range. This can be done via the following configuration settings:
  57     * dnsdist: `setLocal()`
  58     * Auth & Recursor: `local-address` and/or `local-port`
  59
  60 Note: Docker Engine 20.10.0 (released december 2020) removed the need to set the `NET_BIND_SERVICE` capability when attempting to bind to a privileged port.