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.0:

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

	The server system must have BIND 8 or higher installed,
	with the corresponding libraries and header files.
	DHIS has been successfully tested with BIND 8.1.2 and BIND 8.2.1,
	BIND 8.2.2P5 and BIND 8.2.3.

	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 you are compiling this module to be used with BIND 8.1.2 or
	8.2.1 please edit the Makefile and uncomment -DBIND821.

	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.

	Under Solaris 7 and above, BIND 8 is already part of the
	system. Thus, -lbind is in the Makefile should be 
	replaced by -lresolv.

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

	Common Problems:

	1) The following message appears when compiling nsupdate.c:

	nsupdate.c: In function `dns_update':
	nsupdate.c:38: `ns_updrec' undeclared (first use in this function)
	nsupdate.c:38: (Each undeclared identifier is reported only once
	nsupdate.c:38: for each function it appears in.)
	nsupdate.c:38: `rrecp' undeclared (first use in this function)
	nsupdate.c:40: `S_UPDATE' undeclared (first use in this function)
	nsupdate.c: In function `mark_online':
	nsupdate.c:70: `DELETE' undeclared (first use in this function)
	nsupdate.c:71: `ADD' undeclared (first use in this function)
	nsupdate.c: In function `mark_offline':
	nsupdate.c:82: `DELETE' undeclared (first use in this function)
	nsupdate.c:83: `ADD' undeclared (first use in this function)

	This means nsupdate.c is not using the correct BIND 8 DNS
	header files. S_UPDATE, ADD and DELETE are declared in the
	BIND 8 header distribution. Under a normal installation BIND 8
	puts its files under /usr/local/bind (this may differ from 
	system to system). cd to /usr/local/bind/include and copy
	the files under it to /usr/include. You may wish to backup
	the original files first. Type make and it should compile.

	2) At the linking stage make isn't able to find -lbind

	Again, the system is not configured to find the library.
	Assuming BIND under /usr/local/bind copy 
	/usr/local/bind/lib/libbind.a to /usr/lib so that make 
	finds libbind.a

	3) Module keeps crashing when updates are issued

	This has been observed quite often on systems which 
	already have a BIND 8 distribution (either by default
	or with a system package) and another BIND distribution
	is installed.

	In this case make sure the include header files related to
	BIND are being correctly referenced. A most common problem
	is to refer to one set of include files while linking 
	against the other library. 
	
	For more on this problem see the server mailing list 
	archives for past articles.

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 8, 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.


