------------------------------------------------
 FOR UPDATE AND VERSION HISTORY SEE "UPDATING"
------------------------------------------------

DESCRIPTION
===========
This software (DirectSlave) is designed for fast & easy slave DNS management,
interacting with DirectAdmin powered servers using DirectAdmin multiserver API.
Configuration of master DirectAdmin server is not necessary, software provides
DirectAdmin multiserver API emulation via HTTP protocol. You only need to enable
Multi Server feature on master DirectAdmin server and set it up to work with
DirectSlave. Basic understanding of DNS credentials also might be helpful.
How to configure DirectSlave see CONFIGURATION section.

STRUCTURE
=========
Package contains one directory (directslave) with following structure:
bin = main binary location,
  -> directslave
etc = config file location
  -> directslave.conf 
     rc.d = startup scripts for various platforms
      -> freebsd.directslave - startup script for FreeBSD
      -> linux.directslave - startup script for Linux
  -> passwd - main authentication file
log = log files location, as defined in etc/directslave.conf
  -> access.log
  -> action.log
  -> error.log
run = directory for pid file, as defined in etc/directslave.conf
  ~> directslave.pid
scripts = script for /CMD_API_POP handling and management
  -> pop_create.sh - run when POP account created on master server
  -> pop_delete.sh - run when POP account deleted on master server
  -> pop_modify.sh - run when POP account modified on master server
ssl = put your SSL certificates here, like described in config options 
      'ssl_cert' and 'ssl_key' when you want to use HTTPS to connect 
      to DirectSlave. To use SSL you need to set 'ssl' to 'on' and 'ssport' 
      to port number where you want to connect to. HTTP is enabled by default.
www = files available through internal webserver & interface templates

PREREQISITES
============
There is no prerequisites any more.

INSTALLATION
============
Just copy directslave directory structure into /usr/local/directslave on your
slave DNS server and decide under which uid and gid you want to run the
directslave process, then run chown (usually you should run as bind user)

# chown -R bind:bind /usr/local/directslave

Configure directslave to suite your needs. Set up bind (named) DNS to include
named.conf which DirectSlave should produce (see CONFIGURATION).

CONFIGURATION
=============
Main configuration file is located in /usr/local/directslave/etc/ and named
directslave.conf - it's an apache-style plaintext config file. Before modifying
it please make a backup

$ cp directslave.conf ~directslave.conf

Details for fields:

background 1 - start process in background (daemonize it). When set to 1,
               process detaches itself from terminal (console) and writes all
               STDERR output to error_log (see below), and when set to 0 does
               not detach from terminal and logs all errors to console (for
               debug)

host 212.109.44.44 - bind to specified IP on your host, if asterisk (*) - binds
                     to all

port 2222 - bind to specified plaintext HTTP port

sslport 2224 - bind SSL-socket to serve HTTPS requests to specified port. If 
	       'ssl' is off this is no matter.
	       
ssl on - use SSL to serve HTTPS requests. Set this to on to secure your domains
         data transferred from your DirectAdmin servers to DirectSlave.

ssl_cert - path to your SSL server.crt file
 
ssl_key - path to your SSL server.key file

cookie_sess_id DS_SESSID - DirectSlave web interface not using any kind of stored sessions,
			   but encrypted cookies. This is a cookie name.
cookie_auth_key Change_this_line_to_something_long_&_secure - really, you NEED to change this!
                                                              Use strong key, like 64 or 128 
                                                              random characters, including all letters,
                                                              numbers and symbols.

debug 0 or 1 - for debugging purposes (extra console output and verbose logging)

uid 53 - user and group, under which rights daemon should work, usually bind id 
gid 53   or named id to have access to namedb/secondary directory (53:53 for Freebsd, any for Linux)

            various log entries and pid files
pid         /usr/local/directslave/run/directslave.pid
access_log  /usr/local/directslave/log/access.log - W3C formatted access log 
error_log   /usr/local/directslave/log/error.log - debug from daemon server
action_log  /usr/local/directslave/log/action.log - shows which action is taken
                                                    at a definite moment of time
                                                    (shows which domain was
                                                    created, reloaded or removed
                                                    and by which master server)

named_workdir /etc/namedb/secondary - where zone.db files must be stored for 
				      each transferred zone.

named_conf /etc/namedb/secondary/named.conf - file to add/remove entries for
                                transferred zones. This is not main named.conf,
                                just include from main named.conf
                                
retry_time  1200 - DNS retry time for zone updates

rndc_path /usr/sbin/rndc - where is your rndc tool located, or 'none', if you
                           don't use rndc

named_format text - accept text or binary, see 
		    http://geekdom.wesmo.com/2014/06/05/bind9-dns-slave-file-format/

authfile /usr/local/directslave/etc/passwd - where is your authentication credentials
		    stored. This is not UNIX or Linux /etc/passwd, this is local
		    DirectSlave authentication base. In most cases, you should not 
		    touch this line.

Okay, I hope, you understand all of this. For one of final steps, you need to include
DirectSlave named.conf to you main named.conf, add entry

include "/etc/named/secondary/named.conf"

Add auth entry to config, run

# /usr/local/directslave/bin/directslave --password admin:yourhardtoreadpassword

Test files and paths

# /usr/local/directslave/bin/directslave --check

If you see some errors, then you probably need to check permissions, 
create dirs ('named_workdir' & 'named_conf' file), then do check again.

If no errors, you are ready to run directslave (run it as root, like other system
services).

Set `background 0` in config for tests and go

# /usr/local/directslave/bin/directslave --debug
You must see output like this

=============================================================
*** Starting DirectSlave GO/3.x.x server ***
*** (c) Roman Mazur <roman.mazur@gmail.com> 2012-2017 ***

Staying foreground.
=============================================================

Turn on and set up your DirectAdmin MultiServer feature to check and transfer zones 
to your DirectSlave enabled server and test connection.

If you see `212.109.44.44 DirectSlave GO/3.x connection OK` then everything works
fine. Now create a test domain on your DirectAdmin server, check
named_workdir and named_conf file as you defined in config. You must see
named.conf conf entry for your new domain (and zone.db file), also check log files. 
If everything's OK, stop directslave process: press Ctrl+C or do

# kill `cat /usr/local/directslave/run/directslave.pid`

Set `background 1` and start directslave daemonized. Check error.log. Ready for
hard slave work :)

If you have any questions, feel free to contact me. See CONTACTS.

WARNING
=======
This software is provided as is. You can use it in your production or
test environment, but author is not responsible for any data loss or damage to
your system including servers and their components (workstations, phones,
cables and coffee machine).

Tested with DirectAdmin v1.41 (and less)

CONTACTS
========
E-Mail: roman.mazur@gmail.com
Skype:  roman_iris

Feel free to contact me.

(c) Roman Mazur, 2012-2018 (http://mazur.net.ua/)
