README file for DHIS server rel5.3
==================================

DHIS Release 5.3 introduces:
============================
	Corrected bug that caused improper handling of comment character (;) 
      	in the database file.


DHIS Release 5.2 introduces:
============================

	Documentation Updates

DHIS Release 5.1 introduces:
============================

	AUTH_ACK packets return the client's external interface IP address
	for its possible use.


DHIS Release 5.0 introduces:
============================

	A new redefined protocol
	Configurable refresh rates
	No longer a DNS-only system
	A modular architecture for multiple types of updates
	based on dynamic IP address client assignments.
	Multi-client and Multi-server support.

	For a description and understanding of the new modular
	structure please see the MODULES file in this distribution.

	For the new DHIS R5 protocol specifications please see the
	DHIS Release 5 Specification [DHISR5SPEC.pdf] document.

	For a step-by-step QRC description in C using libgmp please
	see Implementing QRC Authentication using the GNU Multi-Precision 
	library [IQRCGMP.pdf]

DHIS Principle and Architecture:
================================

	DHIS is a client-server architecture meant to update databases
	for systems which are assigned a dynamic IP[v4] address.

	By the means of a DHIS client a host which is assigned a dynamic
	IP address (either from its ISP or from DHCP) is able to 
	communicate with a DHIS server in order to advertise its newly
	acquired IP address.

	DHIS comprises a UDP based protocol to achieve this purpose. 

	A DHIS client has a unique identification number and a set of
	authentication keys, runs in background, and attempts to reach
	its server. 
	
	The DHIS server (permanently online) listens to UDP messages
	from its clients and authenticates these against its knowledge
	of keys. When authentication is successful the DHIS server 
	updates one or more databases with the newly received IP
	address for the given client. 

	The server then keeps sending, every period of time, check
	requests to each of its connected clients. These need to
	be acknowledged. If not the server will consider, on an
	individual basis, that the client has disconnected and will
	again update the databases to an offline state.

	Alternativelly the server may receive an OFFLINE_REQ
	packet from the client, in which case the DNS record
	is updated at once and the online state droped.

	Unlike previous versions of the DHIS server, release 5 no
	longer attempts to provide Dynamic DNS only. Instead, 
	the current distribution provides a server capable of
	handling multiple services implemented externally by
	modules. Dynamic DNS is one possible server to provide 
	with a DHIS server but not the only one. Therefore all
	DNS related code has been removed from this release.
	For details on the new modular architecture please see
	MODULES.

	In essence the DHIS server:

		Listens to a UDP port for messages from clients
		Authenticates clients
		Submits online requests to sub-processes
		Checks that clients are still connected
		If not, submits offline requests to sub-processes

Compatibility:
==============

	The DHIS release 5 server dhisd is compatible with release 3 and
	4 clients.

	Release 3 and 4 servers are not, however, compatible with 
	release 5 clients.


	
Secure QRC Authentication:
==========================

	On a secure level DHIS 5 has built in public key authentication based
	on QRC (Quadratic Residue Cypher). The server(dhisd) supports
	two methods of authentication, password and qrc. Furthermore,
	dhisd 5 is compatible with R3 authentication scheme.

	In R5 authentication (and protocol) the client sends an
	ECHO_REQ packet to the server from which it expects an
	ECHO_REP. If received the connection is established and
	the client proceeds to authentication. If mode is password,
	a simple password is sent raw over the network upon which
	the server confirms or denies the online state. If scheme
	is QRC the server sends the client an AUTH_SY packet to
	which the client must reply with an AUTH_SX before authentication
	can be confirmed.

	The QRC algorithm, as implemented in DHIS 5, is as follows:

	The client has two 100 digit keys P and Q. The server
	has (for each client) the public key N obtained by
	P*Q. P and Q are both prime and congruent to 3 mod 4.
	When authentication is requested the server generates
	a random number (prime relative to N) called X and 
	squares it mod N. It then sends its square to the client (Y)
	which by its turn has to calculte its square root
	mod N (X') using the chinese remainder theorem. X' is sent 
	back and compared with X. X' may only be calculated 
	knowing the two private keys factors P and Q. 

	In order to make use of QRC dhisd uses the GNU Multi 
	Precision Library gmp. 


Possible DHIS services in modules:
==================================

	1) Dynamic DNS Update
	2) Mail relaying 
	3) IPinIP automatic tunneling
	4) IPv6inIP automatic tunneling
	5) IPSEC automatic tunneling
	6) Firewall access control
	7) Mail relay access database control
	8) A simple log server
	9) Monitoring online status service
	etc ...

Signals:
========

	dhisd accepts HUP and TERM signals. A kill -HUP will
	make it reload the hosts database and kill -TERM
	will terminate it. Its pid number is recorded a the
	text file (default: /etc/dhis/pid/dhisd.pid)

	Before terminating with SIGTERM dhisd will attempt to bring all 
	online clients offline.

Logging:
========

	dhisd logs online and offline transitions on a text file
	(default: /etc/dhis/log/dhisd.log)

Command Line Options:
=====================

	dhisd supports the following command line options:

	-p <udp port> allows the server to listen to an 
	              alternative port. Default is 58800.
	
	-P <pid_file> allows the specification of an alternative port

                      e.g. dhisd -P /var/run/dhisd.pid

	-l <log_file> allows specifying a path for the log file

		      e.g. dhisd -l /var/log/dhisd.log
	
	-d <dbase_file> allows specifying a path for the database file

		      e.g. dhisd -d /usr/local/etc/dhis.db

	-s <service_file> allows specifying a path for the services 
                          file.

                      e.g. dhisd -s /usr/local/etc/services.db

	All options may be used in conjunction.

Multi-server mode:
==================

	Since release 5 (due to the R5 client) DHIS may be used
	in more than one server at the same time for redundancy or
	load sharing purposes.

	DHIS R5 clients has the possibility of specifying multiple
	redundant servers. When connected the clients try to reach
	one of the available servers and use the one that provides
	a faster reply (or a reply at all if others are down).

	The only restriction to running DHIS in redundant multi-servers
	is to keep exactly the same database files on all redundant systems
	at all times.

	An example for a redundant or load-balanced dynamic DNS service:

	
		Primary DNS server A               Secondary DNS server B
                        |         +-----------------+          |
                        |                                      |
              --------------------------------------------------
              |                   |
        DHIS Server C        DHIS Server D
               \                  /
                ----- client -----

	Client attempts to communicate with C and D. Client uses whichever
	replies (first) and authenticates with it. Say, if C picks up the
	request, C issues an nsupdate to A or B. An Update is then sent to B
	or A if DNS NOTIFY is configured.

	If C is down D will keep the system running.

	If is also possible to run multiple DHIS servers on the
	same machine (using different UDP port and file locations)
	in either independent or redundant mode.


Modules required:
=================

This distribution of dhisd by itself does not provide any particular
service apart from learning dynamic IP addresses from clients.

In order to implement a service a module engine needs to be installed
and configured in services.db

Some modules are available for download at the DHIS site. One may
wish to write new modules using the interface described in MODULES.

A module represents the action to take when one client becomes online
or offline.

Firewalls:
==========

	In order to configure a firewall for a DHIS server ensure that:

	The server can receive UDP packets on its listening port
	(default: 58800)

	The server can send UDP packets to anywhere/anyport
	(Since the client has the possibility of changing its UDP port)


Refreshing and keeping the connection alive:
============================================

	The new R5 method of keep-alive for DHIS is as follows:

	The client authenticates with the server. Optionally the
	client (in the authentication request) sends a refresh 
	rate proposal. 

	The server updates the client with its subscribed services
	and initialises the refresh period to a default of 60 seconds.
	
	If the refresh period was proposed by the client in the 
	AUTH request the server compares this value against minimum
	and maximum limits and, if valid, uses this refresh delay
	instead.

	When N seconds have elapsed (N is the refresh delay) the
	server sends a CHECK_REQ packet to the client and expects
	a CHECK_ACK. If more than 3 CHECK_ACK packets are not received
	the client is marked offline.


Service Memberships:
====================

	Each client in dhis.db may be subscribed to one or more
	services (in services.db) with the service keyword.
	
	If a client does not have a service keyword line the 
	server will attempt to match it against a service called
	default. If such service exists the client will automatically
	be subscribed to it. If not the client will not update 
	any services (may still be useful for OnCmd and OffCmd).

	If however the client has at least one service keyword line
	on its section in dhis.db the default service will not be 
	used. In order to "also" subscribe to the default service
	add a second service line with "service default".

Online and Offline Commands:
============================

	In addition to the modular membership described in MODULES 
	for DHIS server clients, the server may run individual 
	commands for a given client at online and offline transitions.

	For each client in dhis.db:

	If the client record has a line in the form:

		OnCmd /path/to/on/cmd

	/path/to/on/cmd is executed when that client becomes online.

	If the client record has a line in the form:

		OffCmd /path/to/off/cmd

	/path/to/off/cmd is executed when that client becomes offline.

	Both OffCmd and OnCmd executions occur with 2 parameters,
	the HostID of the client and the IP address acquired via DHIS.

	In addition both oncmd and offcmd commands may be invoqued
	with additional parameters (3, 4, 5, ...) as they appear
	in the dhis.db file. The first "word" after the command
	is passed to the external program as argument 3 (1 and 2
	are id and address from above), the second as argument 4
	and so on...

	Example of a simple logging test:

	1000 {
		hostpass something
		oncmd /etc/oncmd
	}


	# /etc/oncmd
	#!/bin/sh	
	#
	echo I am $1 online now at $2

	 and OffCmd = offcmd as keywords are not case
	sensitive.


Support:
========

	Please address any questions or bugs regarding dhisd to 
        support (at) dhis.org