Install instructions for DHIS R5 server module dhis-dns-engine
==============================================================

This package contains a dynamic DNS service module to be used
with dhisd release 5 or above.

While the DHIS server dhisd retrieves dynamic IP addresses
from clients, this module allows the server to update a
dynamic DNS zone based on those retrieved IP addresses.

In order to install dhis-dns-engine-5.3:

	A domain under which dynamic hosts will be updated must be
	available. 

	The server system must have BIND 8 or higher installed,
	with an available nsupdate binary. By default this module
	uses /usr/sbin/nsupdate. If your nsupdate is somewhere else on
	the system please edit nsupdate.c and replace NSUPDATE_CMD. 

	The machine must be permanently connected to the internet
	with a static IP address.

	The machine which will act as a server should be running
	a distribution of UNIX or similar system.

	A DHIS R5 server dhisd must be running on the same machine.
	
	This module must be included in the server's service database.


1. Compile Stage
================

	If your system is System V based, edit the Makefile and add
	-lsocket -lnsl to the LIBS section. These are required 
	for TCP/IP operation.

	Being in the source directory type "make".
	It should build the dhisd binary.


2. Install stage
================

	You will need to have dhisd installed in your system.

	Move the newly compiled module dhis-dns-engine to
	/etc/dhis/bin

	Edit /etc/dhis/db/services.db and add a line in the form:

	dns	5	/etc/dhis/bin/dhis-dns-engine

	In here dns identifies the service type, 5 is the number
	of processes to serve DNS (may differ depending on 
	resources and load requirements) and the command
	is the child process for dhisd to fork into.


	Edit /etc/dhis/db/dhis.db

	For each client that is to have dynamic DNS support
	add a line such as:
		
		Service		dns

	Plus a line with the hostname to update for that record:

	example:

		HostName	dyn1.exmaple.com

	Terminate your current DHIS server if running with SIGTERM

	Execute your DHIS server with something like /etc/dhis/bin/dhisd 
	
	The module in installed

3. DNS stage
============

	The final stage is to configure DNS, i.e. BIND, to allow
	DHIS operation. Let us assume that the nameserver is 
	known by ns.example.com and that, if relaying is 
	present, the relay machine is identified by relay.example.com.
	Again, these may point to the same machine.

	Edit /etc/named.conf and add a section such as:

	zone "example.com" in {

		type master;
		file "db.example.com";
		allow-update { 127.0.0.1; x.x.x.x; };
	};

	Where x.x.x.x is the server's IP address as seen from
	the outside world.

	The allow-updates keyword tells BIND to accept updates
	only from the given addresses.

	Now cd to the current DNS database directory and create
	db.example.com as a text file.

	Example: 
	---------------------------------------------------------------

	@	IN SOA ns.example.com. root.ns.example.com. (
		1000000		; Serial Number
		28800		; Refresh
		7200		; Retry
		604800		; Expire
		86400		; Default TTL
		);

			IN NS	ns

	ns		IN A	x.x.x.x

	; If relay is present

	relay		IN A	y.y.y.y

	localhost 	IN A	127.0.0.1

	; Now for each dynamic host add

	dyn1		60 IN A	192.168.255.0
	dyn2		60 IN A	192.168.255.0
	dyn3		60 IN A	192.168.255.0
	
	; Note that dynamic address A records have a TTL of 60 seconds

	---------------------------------------------------------------
	
	And run named (/usr/sbin/named or /usr/sbin/in.named) to load
	these fields.

	DNS is now running and accepting dynamic updates.

4. Adding Records
=================

	For each new host, as described above, a new record must be 
	added to dhis.db and a kill -HUP must be sent to the dhisd process.

	Furthermore, DNS entries must be created. Assuming you wish
	to add dyn4 at a later stage,

	Add

	1004 {
		hostname	dyn4.example.com
		hostpass	xpto4
	}

	to dhis.db, 

	run 

	kill -HUP `cat /etc/dhis/pid/dhisd.pid`

	to reload the DHIS server.

	run nsupdate command and issue:

	>update add dyn4.example.com. 60 in a 192.168.255.0

	And press return twice.

	When you finish type CTRL-D to exit nsupdate.

	This adds the DNS records. You can of course create a shell
	script to perform all these steps automatically.


And that's it. The DHIS DNS module is installed.


