binder/README.markdown

6.2 KiB

Binder

Build Status Code Health

A Django web application for viewing and editing BIND DNS zone records.

Download

git clone https://github.com/jforman/binder.git

Requirements

The requirements.txt file has the necessary dependencies.

pip install -r requirements.txt

Running Binder

Over the course of developing Binder, it has come to the fore that using a container makes development and runnin Binder much easier.

Local Sqlite database

docker run jforman/binder:latest

Admin user

Default admin user for Binder is 'admin', and password is 'admin' as well.

MySQL database

If you wish to use a MySQL database, the following structure works:

docker run -e 'DJANGO_DB_HOST=XXXX' -e 'DJANGO_DB_PASSWORD=YYYY' -e 'DJANGO_DB_NAME=ZZZZ' -e 'DJANGO_DB_USER=binder' jforman/binder:latest

The Django settings.py is configured to accept the following environment variables when configuring a MySQL-based backend database.

  • DJANGO_DB_HOST: IP address or Hostname of the MySQL database host. (Required)
  • DJANGO_DB_NAME: Name of the MySQL database. (Required)
  • DJANGO_DB_USER: Username to access the above database. (Optional. Default: binder)
  • DJANGO_DB_PASSWORD: Binder Database password (Required)

If you wish to use MySQL as the backing database, you must specify all required parameters.

Manually

Or you can run Binder directly on your host using the Django devserver.

python manage.py migrate
python manage.py createsuperuser
python manage.py runserver

Develop Binder

If you want to develop on Binder, I've tried to write down the steps I use.

develop.sh is a shell script that will start a Docker container based off the same image as the one on Docker hub. Only this script will mount your Binder code directory into /code in the container.

Before any development can commence, you will need to install the requirements.

From inside the container:

pip install -r requirements.txt

Generating a new initial_data.json

Certain versions of Django cause changes in the schema of the admin table. In this case, I've found a (perhaps less than proper) workflow for creating a new initial_data.json file. This uses a local Sqlite database file for bootstrapping.

python manage.py migrate
python manage.py createsuperuser
...
python manage.py dumpdata -o binder/fixtures/initial_data.json

Encrypted TSIG Keys

Starting with version 1.5, TSIG keys inside the database are encrypted using the Crytography library and Fernet facilities.

Normally on startup, a new Fernet encryption key is created. This will change upon reboot as the process dies and restarts.

If you wish to use a statically configured encryption/decryption key, one must pass the DJANGO_FERNET_KEY environment variable, containing this key string. This should be used in production. This key MUST be kept secret or your TSIG keys will be able to be decrypted.

External configuration

Aside from the Binder application itself, other infrastructure is required to make Binder useful.

BIND DNS Server

When Binder accesses your BIND DNS server, it first queries the statistics port to gather zone information. This includes zone name, view, and serial number.

named.conf

We must provide server statistics from the BIND process itself. This allows Binder to query BIND itself and get a list of zones, views, and other statistics.

options {
  zone-statistics yes;
}

statistics-channels {
    inet * port 8053 allow { 10.10.0.0/24; };
};

This tells bind to start an HTTP server on port 8053 on all interfaces, allowing 10.10.0.0/24 to make requests on this interface, http://${bind_server}:8053/. You will most likely want to narrow down list of source hosts/IPs who can query BIND for this data.

It is smart to include your TSIG key in a separate file. This way if you choose to have specific ACLs for your named.conf that are different from your TSIG key, this can be done.

include "/etc/bind/dynzone.key";

This tells Bind to load a TSIG key from dynzone.key that can be referenced later in named.conf.

Moving on to zone declaration, determine how locked down you want zone updates and transfers to be. The following zone is defined to allow all zone transfers, but restrict updates to those provided with the dynzone-key TSIG key.

zone "dynzone.yourdomain.org" IN {
    type master;
    file "/var/cache/bind/master/db.dynzone.yourdomain.org";
    allow-update { key dynzone-key; };
};

/etc/bind/dynzone.key

Below are the entire contents of the dynzone.key file. This specifies the name, algorith and TSIG secret.

key dynzone-key {
    algorithm hmac-md5;
    secret "foobar...BhBrq+Ra3fBzhA4IWjXY85AVUdxkSSObbw3D30xgsf.....";
};

referenced as 'dynzone-key' in named.conf

For information on TSIG see http://www.cyberciti.biz/faq/unix-linux-bind-named-configuring-tsig/ .

Apache HTTPD

If you are using Apache to front-end your Binder Django app, the following two configuration files can be used as starting points.

binder-apache.conf.dist: Apache virtual host configuration file to be inclued in your apache.conf. Values provide for Binder to run on its own virtual host, separate logs, etc

django.wsgi: WSGI configuration file used by Apache to run the actual Django app.

Nginx

binder-nginx.conf.dist: Nginx virtual host configuraiton. This configuration expects Django to be running in fcgi mode on port 4001 on 127.0.0.1.

MySQL

If you choose to use MySQL as your backing datastore, the following commands will help you get up and running quickly.

create database binder;

create user 'binder'@'%' identified by 'INSERTYOURPASSWORDHERE';

grant all privileges on binder.* to 'binder'@'%';

flush privileges;