From 75e7019c54924ebc28280145dcb43b0b02f0d020 Mon Sep 17 00:00:00 2001 From: Peter Schiffer Date: Sat, 3 Sep 2016 11:28:24 +0200 Subject: [PATCH] Document pdns-admin --- README.md | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 71 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 72ed014..272b2c8 100644 --- a/README.md +++ b/README.md @@ -6,17 +6,17 @@ This repository contains two Docker images - pdns-mysql and pdns-admin. Image ** Docker image with [PowerDNS 4.x server](https://www.powerdns.com/) and mysql backend (without mysql server). For running, it needs external mysql server. Env vars for mysql configuration: ``` -(name = default value) +(name=default value) -PDNS_gmysql_host = mysql -PDNS_gmysql_port = 3306 -PDNS_gmysql_user = root -PDNS_gmysql_password = powerdns -PDNS_gmysql_dbname = powerdns +PDNS_gmysql_host=mysql +PDNS_gmysql_port=3306 +PDNS_gmysql_user=root +PDNS_gmysql_password=powerdns +PDNS_gmysql_dbname=powerdns ``` If linked with official [mariadb](https://hub.docker.com/_/mariadb/) image with alias `mysql`, the connection can be automatically configured, so you don't need to specify any of the above. Also, DB is automatically initialized if tables are missing. -PowerDNS server is configurable via env vars. Every variable starting with `PDNS_` will be inserted into `/etc/pdns/pdns.conf` conf file in the following way: prefix `PDNS_` will be stripped and every `_` will be replaced with `-`. For example, from above mysql config, `PDNS_gmysql_host = mysql` will became `gmysql-host=mysql` in `/etc/pdns/pdns.conf` file. This way, you can configure PowerDNS server any way you need within a `docker run` command. +PowerDNS server is configurable via env vars. Every variable starting with `PDNS_` will be inserted into `/etc/pdns/pdns.conf` conf file in the following way: prefix `PDNS_` will be stripped and every `_` will be replaced with `-`. For example, from above mysql config, `PDNS_gmysql_host=mysql` will became `gmysql-host=mysql` in `/etc/pdns/pdns.conf` file. This way, you can configure PowerDNS server any way you need within a `docker run` command. There is also a `SUPERMASTER_IPS` env var supported, which can be used to configure supermasters for slave dns server. [Docs](https://doc.powerdns.com/md/authoritative/modes-of-operation/#supermaster-automatic-provisioning-of-slaves). Multiple ip addresses separated by space should work. @@ -54,3 +54,67 @@ docker run -d -p 53:53 -p 53:53/udp --name pdns-slave \ -e SUPERMASTER_IPS=172.5.0.20 \ pschiffe/pdns-mysql ``` + +## pdns-admin + +Docker image with [PowerDNS Admin](https://github.com/ngoduykhanh/PowerDNS-Admin) web app, written in Flask, for managing PowerDNS servers. The app is running under uWSGI with nginx. Processes in the container are managed by systemd. For running, it needs external mysql server. Env vars for mysql configuration: +``` +(name=default value) + +PDNS_ADMIN_SQLA_DB_HOST="'mysql'" +PDNS_ADMIN_SQLA_DB_PORT="'3306'" +PDNS_ADMIN_SQLA_DB_USER="'root'" +PDNS_ADMIN_SQLA_DB_PASSWORD="'powerdnsadmin'" +PDNS_ADMIN_SQLA_DB_NAME="'powerdnsadmin'" +``` +If linked with official [mariadb](https://hub.docker.com/_/mariadb/) image with alias `mysql`, the connection can be automatically configured, so you don't need to specify any of the above. Also, DB is automatically initialized if tables are missing. + +Similar to the pdns-mysql, pdns-admin is also completely configurable via env vars. Prefix in this case is `PDNS_ADMIN_`, but there is one caveat: as the config file is a python source file, every string value must be quoted, as shown above. Double quotes are consumed by Bash, so the single quotes stay for Python. (Port number in this case is treated as string, because later on it's concatenated with hostname, user, etc in the db uri). Configuration from these env vars will be written to the `/opt/powerdns-admin/config.py` file. + +### Connecting to the PowerDNS server + +For the pdns-admin to make sense, it needs a PowerDNS server to manage. The PowerDNS server needs to have exposed API (example configuration for PowerDNS 4.x): +``` +api=yes +api-key=secret +webserver=yes +``` + +And again, PowerDNS connection is configured via env vars (it needs url of the PowerDNS server, api key and a version of PowerDNS server, for example 4.0.1): +``` +(name=default value) + +PDNS_ADMIN_PDNS_STATS_URL="'http://pdns:8081/'" +PDNS_ADMIN_PDNS_API_KEY="''" +PDNS_ADMIN_PDNS_VERSION="''" +``` + +If this container is linked with pdns-mysql from this repo with alias `pdns`, it will be configured automatically and none of the env vars from above are needed to be specified. + +### Persistent data + +There is a directory with user uploads which should be persistent: `/opt/powerdns-admin/upload` + +### Systemd + +Because of the systemd is managing processes inside of this container, there are some special requirements when running this container: `/run` and `/tmp` must be mounted on tmpfs, and cgroup filesystem must be bind-mounted from the host. Example Docker run bit when running on Red Hat based distro: `--tmpfs /run --tmpfs /tmp -v /sys/fs/cgroup:/sys/fs/cgroup:ro` (If you are on a recent Fedora, you can install `oci-systemd-hook` rpm package, and you don't need to specify any of this, it will be done automatically for you.) + +And if you want to see logs with `docker logs` command, allocate tty for the container with `-t, --tty` option. + +### Example + +When linked with pdns-mysql from this repo and with LDAP auth: +``` +docker run -dt -p 8080:80 --name pdns-admin \ + --link mariadb:mysql --link pdns-master:pdns \ + -v pdns-admin-upload:/opt/powerdns-admin/upload \ + --tmpfs /run --tmpfs /tmp -v /sys/fs/cgroup:/sys/fs/cgroup:ro \ + -e PDNS_ADMIN_LDAP_TYPE="'ldap'" \ + -e PDNS_ADMIN_LDAP_URI="'ldaps://your-ldap-server:636'" \ + -e PDNS_ADMIN_LDAP_USERNAME="'cn=dnsuser,ou=users,ou=services,dc=example,dc=com'" \ + -e PDNS_ADMIN_LDAP_PASSWORD="'dnsuser'" \ + -e PDNS_ADMIN_LDAP_SEARCH_BASE="'ou=System Admins,ou=People,dc=example,dc=com'" \ + -e PDNS_ADMIN_LDAP_USERNAMEFIELD="'uid'" \ + -e PDNS_ADMIN_LDAP_FILTER="'(objectClass=inetorgperson)'" \ + pschiffe/pdns-admin +```