Install instructions for DHIS server rel5.2
===========================================

dhisd is the DHIS server, meant to permit updating external 
databases with dynamically assiged IP addresses to clients.

In order to build the dhisd server the following requirements must
be met:

	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 C compiler is needed.

	The GNU Multi Precision library is required (see section 0 below).


0. GMP
======

	Before starting to compile DHISD, the GNU MultiPrecision library gmp
	must be installed. 

	It may be downloaded from:

	ftp://ftp.dhis.org/pub/dhis/gmp-4.1.tar.gz

	Decompressed. Building should require:

	./configure
	make
	make install

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

	In this installation we will use /etc/dhis as the default
	base directory for the server. Another directory may be
	used in which case file location command line options must
	be given to dhisd when executing.

	Create the directories:

	/etc/dhis
	/etc/dhis/bin
	/etc/dhis/pid
	/etc/dhis/db
	/etc/dhis/log
	
	You may wish to create /etc/dhis/src and put dhisd-5.2 under
	this directory.

	Copy dhisd to /etc/dhis/bin . This is the server binary.

	Create the database file which will hold information for
	current dynamic hosts:

	Change directory to /etc/dhis/db
	
	Create a text file named dhis.db with a text editor.

	Each dynamic host in the database file is represented by
	a record in the following form:

	ID {
		authentication keys
	}

	
	Example: 3 hosts, 2 with password authentication and 1 with 
	QRC authentication.

	dhis.db:
	--------
	1000 {
		HostPass	secret1
		Service		serviceA
	}

	1001 {
		HostPass	secret2
		Service		serviceA
	}
	1002 {
        	AuthN   62618356157083313953659443711837574706224086057551
        	AuthN   20427737733677817431836864820217527591008711003863
        	AuthN   70979542582114024334017868024554473396638523106022
        	AuthN   2702375049521348659606361903688258217224352016237
		Service serviceA
		Service serviceB
	}

	
	A dynamic record starts with a { and ends with a }. 

	The hostid is a unique number that identifies the client.

	HostPass is the text password that the client uses to authenticate.
	
	AuthN is the client's public key if QRC is being used.
	Please note that either hostpass or authn must be present
	for each host but they may not be used together. 

	QRC keys may be generated with the genkeys utility provided
	in this distribution. Run genkeys and copy-paste the 
	AuthN lines. AuthP and AuthQ lines are the client's private
	keys and should be sent to the client wishing to authenticate
	using QRC.

	authn is the client's public key. It may be represented 
	as a series of authn lines in which case the digits
	are concatenated in appearance order originating a 
	bigger public key.

	Service represents the services/modules that the client subscribes
	to. See MODULES for more information.

	Any line inside a record that does not have a known keyword
	is discarded and thus, may be used as a comment or additional 
	information.

	Keywords are case insensitive thus AuthN is the same as authn.

	Please note that R3 clients should use password (and hostpass)
	and not QRC. The authentication sequence is different but
	the same keywords serves both purposes i.e., password
	in R3 and R4/R5.

	As of R5 the file dhisd no longer requires a hostname keyword.
	This is because the DHIS server is no longer DNS service
	specific. For a DNS service the dns engine should implement
	a matrix for translation between hostid and hostname.

	Since dhisd ignores anything that does not match an implemented
	command the dhis.db file may be used by engines to contain
	additional information. 

	1003 uses QRC and has the public key resulting
	from concatenating the number sequence.

	For each new dynamic host added, kill -HUP the dhisd process 
	for database reloading.

	Change the permissions as you wish. In particular dhis.db
	should not be readable by anyone. Suggested example:

	chmod 700 /etc/dhis /etc/dhis/*
	chmod 600 /etc/dhis/db/dhis.db

	Add dhisd to your system's startup script 
	(rc.local for BSD systems, SXXdhis under /etc/rc2.d
	for System V). A simple line such as 

		/etc/dhis/bin/dhisd

	will do. 


	Now create /etc/dhis/db/services.db 
	
	Insert one line per module implemented. See MODULES
	for a detailed description of the modular architecture 
	and services.db format.


	And the DHIS server is installed.

	See the README file for more information on the server
	and MODULES for information on the new modular structure 
	of the server.

	You may also run /etc/dhis/bin/dhisd now if you wish to 
	run DHIS at once.


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

4. Running dhisd in debug mode
------------------------------

	The DHIS server dhisd may be configured to log DEBUG messages
	to syslog.

	Currently most messages are logged under LOG_DEBUG so
	a proper log file specified in syslog.conf is required.

	By default dhisd does not log much. 
	Currently most information will be dumped on level 1 
	and only one function will log on level 2.

	There are two ways of turning debugging on:

	1) Use the -D option 

	To log on level 1 use dhisd -D
	To log on level 2 use dhisd -D -D

	2) Using SIGUSR1 and SIGUSR2 dhisd can be configured
	at run time to increase or reset its log level.
	Sengind a SIGURS1 to the dhisd process increases its log
	level by one. Sending a SIGUSR2 to the process resets
	the log level to 0.

And that's it. The DHIS server is installed.