From 49b7559e869daec84bd59f0dc139aec192e98322 Mon Sep 17 00:00:00 2001 From: Karl Goetz Date: Sat, 2 Jan 2016 09:46:04 +1100 Subject: [PATCH] Attempted to clarify install documentation I've just worked my way through the install process and tried to clarify/explain anything that wasn't obvious or that I thought might not be obvious to someone new trying to use this software. Having encountered all the same problems as @vchoi in issue #5 I've attempted to update the documentation to clarify the requirements. Other than that its 'misc' really: some confusion with things like local_settings.py being missing, changed the headings and shuffled things around for clarity, expanded on the required django commands etc. --- README.markdown | 54 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 41 insertions(+), 13 deletions(-) diff --git a/README.markdown b/README.markdown index eb435e7..17073d0 100644 --- a/README.markdown +++ b/README.markdown @@ -7,9 +7,25 @@ A Django web application for viewing and editing BIND DNS zone records. Binder supports adding and deleting DNS records (and eventually editing in place). TSIG-authenticated transfers and updates are supported. -## Requirements ## +The Binder repository is housed in a [Github](http://github.com/jforman/binder) repository. The repo containts all the Django code and example configuration data for running Binder both in development and production. -Packages: +## Installation ## + +There are some build dependencies for the Python mondules, on apt based systems these can be installed with + + apt-get install python-dev libxml2-dev libxslt-dev git + +Initial checkout has to be performed with git + + git clone https://github.com/jforman/binder.git + +### Requirements ### + +Once the git repository has been cloned these can be installed with one command + + pip install -r requirements.txt + +Packages installed: * [Django](http://www.djangoproject.com) * Python Modules @@ -17,32 +33,42 @@ Packages: * Beautifulsoup4: This library is included as a dependency of pybindmlx when you when you install pybindxml. * [python-dnspython](http://www.dnspython.org/) * [python-sqlite](http://docs.python.org/2/library/sqlite3.html) (If you will be using Sqlite for server and key storage) -* [Bind DNS Server](http://www.isc.org/software/bind). At least version 9.5.x, which provides instrumentation for gathering process and zone statistics remotely. -## Installation & Configuration ## - -The Binder repository is housed in a [Github](http://github.com/jforman/binder) repository. The repo containts all the Django code and example configuration data for running Binder both in development and production. +Elsewhere you will need a [Bind DNS Server](http://www.isc.org/software/bind) running (at least version 9.5.x, which provides instrumentation for gathering process and zone statistics remotely). To verify that required and optional dependencies are installed, execute [check-dependencies.py](https://github.com/jforman/binder/blob/master/check-dependencies.py). This script checks that various Python modules will import correctly. Binder is intended to be installed into the /opt directory in /opt/binder. Forthcoming deb packages will provide for this easy installation and upgrades. -Provided under the config directory are various example configurations for runing Binder: +## Configuration ## -config/ +### binder/ ### + +If you wish to override anything from settings.py it should be done in a new file + +* local_settings.py: Local settings called by Binder templates for TTL choices, record types handled, etc. + +### config/ ### + +Provided under the config directory are various example configurations for runing Binder: * binder-apache.conf.dist: Name-based virtual host configuration for running Binder under Apache. * django.wsgi: WSGI configuration file called by Apache to run Binder. * binder-nginx.conf.dist: Name-based virtual host configuration for running Binder under Nginx using fcgi. * binder-upstart.conf.dist: Ubuntu Upstart configuration file for starting Binder upon machine startup. -binder/ +These are not necesary for development but are useful once moving to production. -* local_settings.py: Local settings called by Binder templates for TTL choices, record types handled, etc. +### Admin user ### +It is necesary to create an administrative user + + python manage.py createsuperuser + +## Running Binder ## The development server is run as most Django dev servers are run. - /opt/binder/manage.py syncdb + /opt/binder/manage.py migrate /opt/binder/manage.py runserver Once you have the Django server up and running, you will want to configure at least one BIND server in the Django Admin app. This includes a hostname, TCP statistics port and a default TSIG transfer key to be used when doing AXFR actions (if necessary). @@ -51,9 +77,9 @@ Keys should also be created, if needed. The name of the key should match the con Once these two pieces of configuration are done, open up [http://yourserver:port/](http://yourserver:port) to access Binder and begin DNS zone management. -### BIND DNS Server ### +## BIND DNS Server ## -When Binder accesses your BIND DNS server, it first queries the statistics port to gather various zone information. This data includes zone name, view, and serial number. This is all configured by some of the following configuration examples. +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. This is all configured by some of the following configuration examples. #### named.conf #### @@ -92,6 +118,8 @@ Below are the entire contents of the dynzone.key file. This specifies the name, referenced as 'dynzone-key' in named.conf +For information on TSIG see http://www.cyberciti.biz/faq/unix-linux-bind-named-configuring-tsig/ . + ### Related Configuration ### #### Apache HTTPD ####