Install instructions for DHIS R5 server module dhis-mx-sendmail-engine
======================================================================

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

While the DHIS server dhisd retrieves dynamic IP addresses
from clients, this module allows the server to deliver messages
that were previously queued for the newly online host.

In order to install dhis-mx-sendmail-engine-5.0:

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

	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".

	You may need to edit dhis-mx-sendmail-engine.c and update the 
	sendmail path of sendmail.

	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-mx-sendmail-engine to
	/etc/dhis/bin

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

	mx	5	/etc/dhis/bin/dhis-mx-sendmail-engine

	In here dns identifies the service type, 5 is the number
	of processes to serve mail relay (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 mail relay support
	add a line such as:
		
		Service		mx

	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
	mail relaying.

	Assuming BIND is already running from the dynamic DNS module
	and configured:

	For each host in dhis.db with the mx service perform a one
	time nsupdate as follows:

	execute nsupdate

	Type in:

        >update add dyn.example.com. 86400 in mx 0 dyn4.example.com.
        >update add dyn.example.com. 86400 in mx 10 relay.example.com.

        And press return twice.


        This adds a DNS MX record for host dyn.example.com with a lower
	preference to the dynamic address and a backup relay server.

	relay.example.com must be a valid static hostname of this
	server providing mail relaying.


4. Adding mail relay to clients
===============================

	To add mail relay to clients simply:

	1) Edit dhis.db and add "service mx" to the client
	2) Add that client MX records to DNS as above
	3) Reload dhisd with -HUP


5. Setting up the mail relay agent (MTA)
========================================

	This module is based on sendmail residing on /usr/sbin/sendmail
	
	To change the location of sendmail edit dhis-mx-sendmail-engine.c
	and change the appropriate path before compiling.

	
	You will need to configure the MTA to relay messages for
	your domain (example.com). 

	All this engine does is basically receiving requests and
	issuing sendmail to deliver mail for the appropriate host.

	In sendmail:

	Add a DNS A record for relay.example.com with the server's IP
	address.

	Edit sendmail.cw and add relay.example.com

	Edit relay-domains and add example.com

	Restart sendmail

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

