DHIS Daemon Client release 5.1
==============================

This distribution includes the source code for the DHIS daemon client
dhid release 5.1. 

What is dhid ?
--------------

  dhid is the DHIS client daemon. After setting up with a DHIS provider,
  each machine may run a dhid daemon (in background) in order to
  update its dynamic IP address within the server.

  /etc/dhid.conf should be configured according to the provider's 
  assigned parameters.

  Until release 4.0 DHIS was a system intended to provide dynamic DNS
  updates (on the server). In other words, this client daemon dhid 
  would update its DNS entry within the server.

  As of R5 DHIS is no longer a Dynamic DNS protocol only. While 
  service providers may in fact provide such a service with DHIS, 
  other servers may also be offered based on the dynamic IP acquisiton.
   
  Once running, dhid sends echo request packets to the server and
  expects a reply. Once received, dhid tries to authenticate at the
  server either in secure on insecure mode. From then on, and 
  providing authentication was successful, the client waits and
  replies to queries originated at the server. If the server doesn't
  receive acknowledgments of these packets the host is marked offline.
  Likewise, if the client doesn't receive queries for a period of time
  the offline stage is restored.

  Therefore, the only thing a DHIS host needs is to run the dhid client.
  The server is able to determine when the host is online and the server 
  tables are updated automatically.

  From R5 the DHIS client dhid no longer implements mail relaying functions
  or interactive mode.

  This release of the client however supports the following additional
  features:

    Multi-server support
    Multi-client update support 
    Configurable refresh rates
    Possibility of running external commands when online/offline transitions
    occur.

   For an example of the possible options please see dhid.conf.sample

Running dhid on a different incoming port
-----------------------------------------

The incoming UDP port (for UDP messages from servers) is by default
58800. It may be otherwise specified with the -p option.

	Example:

		dhid -p 59000

		Will make dhid listen for UDP packets on port 59000

Running dhid under a user other than root
-----------------------------------------

The DHIS daemon dhid may be executed by any user, providing that
that user has 1) access to the configuration file 2) the port used
is above 1023. In fact there's no reason it for it to be run under
root other than simplicity. if you wish to run dhid under a different
user (say dhis), simply perform the following steps:

	Edit main.c and remove 

		if(getuid()) {
			syslog(LOG_ERR,"%s must be executed by root",argv[0]);
			exit(1);
		}

	Make sure the user running dhid has access to dhid.conf
	(in the dhis user example)

		chown dhis /etc/dhid.conf

	Execute it under that user

	In startup script

		su -c dhis /somewhere/dhid


Having dhid.conf on a different location
----------------------------------------

You may move dhid.conf anywhere and use the -f option to specify 
its location. Alternativelly you may update the DHID_CONF directive 
in dhid.h and recompile the client.

e.g.
	dhid -f /usr/local/etc/dhid.conf



Moving the PID file
-------------------

The PID file location may also be specified on the command line
using the -P option.

Example:

	dhid -P /var/run/dhid.pid

Logging
-------

The DHIS client dhid does not send any output to stdout. Instead
it uses syslog() to report messages.

Error messages are logged under LOG_ERR and informational
messages under LOG_INFO. 


Asynchronous Offline Packets
----------------------------

  It is possible to instruct the IS to mark the host Offline
  at once. The procedure is performed automatically when the timeout 
  is reached and no acknowledgements  are received by the server. However, 
  the user may wish to speed up the offline process by including the offline
  request in his system's disconnection script. 

  The command: kill -USR2 `cat /etc/dhid.pid` issues an Offline packet
  request.

  Please note that this kill must be included in the script that
  is called prior to disconnection, not in the one that is
  executed once the PPP session is terminated. Also, you may
  wish to add a sleep of 1 second to allow the offline packet
  to get through.


Multi-Server and Multi-Client support:
--------------------------------------
  
  The present client supports:

     1)	Multi-client updates on a single independent server
     2)	Multi-client updates on multiple independent servers
     3)	Single client updates on one of multi redundant servers
     4) Or any combination of the above
  

  With option 1) it is possible to update multiple records 
  (with multiple ids and keys) on a same server address/port.

  With option 2) it is possible to update multiple clients 
  (with multiple ids and keys) on multiple server addresses/ports.

  With option 3) a same client (id and keys) is sent to a list
  of redundant servers. The client will pick up (for the session) 
  the first replying server and will use it for futher communication.
  It is this way possible to use the dhid client in a redundant /
  load sharing DHIS service providing the DHIS service provider 
  itself has servers in redundant mode.

  For more information on the usage of these options please see
  the example configuration file dhid.conf.sample

  
Note for Multiserver/client:
----------------------------

  Since R5 this client supports multiple server/clients. At the time
  of this release issuing an offline request with USR2 brings all
  records in dhid.conf to offline mode.

  Likewise when a connection is present all records in dhid.conf
  are automatically brought online.

  A way to individually control records is not yet available and
  will probably be developed in the next version of this client. 

On-Demand Dialup Connections
----------------------------

  Some users on the Internet have an on-demand dialup procedure. The
  connection is established automatically when a packet needs
  to be sent. In this scenario dhid may be undesirable. Sending a 
  packet every minute would result in a permanent connection.

  In order to resolve this problem the following should be performed:

  Configure the PPP daemon to consider DHIS packets "uninteresting"
  and not suitable for timeout purposes. How to will depend on the
  particular PPP implementation. 

  DHIS packets are UDP packets. These are sent from client to server
  (outbound) and from server to client (inbound).
  The default port for both is 58800. The server port may be another
  if specified in dhid.conf using a :<portnum> after the ISAddr line. 
  The client port may likewise be configured with the -p option.


Firewalls:
----------

   If you intend to run dhid behind a firewall make sure to allow 
   both incoming and outgoing UDP packets to the configured server(s).
  
   Port is 58800 by default or other if specified in dhid.conf and/or 
   with the -p option.

   Naturally don't be alarmed if you see incoming UDP packets arriving
   at your machine when running the dhid client. 

NAT Systems
-----------

  There may be systems which lie behind a NAT (Network Address Translation)
  with private IP addresses and connect through a common gateway/NAT 
  router to the Internet. In order to run dhid behind one of this systems, 
  please proceed as follows:

  If you have control over the NAT rules:

     Outbound packets are automatically translated and thus require
     no action.

     Inbound packets however will arrive at the router and not at the
     machine running dhid. Therefore you need to configure a redirect
     rule at the NAT device mapping UDP packets targeted at the DHIS
     port to the private IP address of the machine running dhid.

  If you don't have control over the NAT rules:

     Bad luck. The only solution is to run a DHIS R3 client which does
     not require a response from the server. DHIS R3 is much less secure
     in terms of authentication.

  Please note: 

     When running dhid behind a NAT device the address that will be marked
     or considered by the server is the address of the NAT device (public
     address) and not the private address of the host running it.

  An application for dhid with NAT:

     It has become more common to observe hardware devices for DSL, Cable
     of ISDN being deployed as NAT routers to provide internet connectivity.

     Since these devices are in the form of hardware and are not likely to
     support DHIS, running DHIS behind a private host may allow the router's
     public IP address to be advertised. 

     In a dynamic DNS service type one can, for example, then configure
     a redirect rule for port 80 (WWW) and run DHID to advertise the hostname
     of the inside web server.


Services
--------

  For a list of services implemented with DHIS see the DHIS web site
  at http://www.dhis.org/

  Please note that this list only refers to services of which existence 
  we are aware of. There might be more which we don't know about.

  Examples of services that DHIS may provide:

  Dynamic IP DNS
  Dynamic IP mail relaying and delivery
  Dynamic IP Tunnel establishment
  Dynamic IP ACL control

Further Information
-------------------

  Further information on the dhid daemon program may be obtained by
  email at info@dhis.org. 

  Mailing lists are also available to support the DHIS system:

  announce -- Announcements on the DHIS System and Service 
  misc     -- Miscelaneous discussions between DHIS users
  server   -- A list for DHIS Service Provider Administrators

  To subscribe one of these lists send a message to: majordomo@dhis.org

  having a single line in the body with:

  subscribe listname