DHIS Daemon Client release 5.3
==============================

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

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

  dhid is the DHIS client daemon. After setting up with the 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) only. In other words, the 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 password or qrc 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. If you wish to run it on a different UDP port you may use 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 can be executed by any user provided it has
permissions to use (bind) the UDP port default 58800).

AFAWK there is no real risk in running dhid as root, but if
you're worried about security you may create a dhis user and run dhid 
as such. In this case make sure that the user under which dhid is being
executed has permissions to read the /etc/dhid.conf file.


	Create a dedicated username (e.g. dhis)

	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

	If you want a pid file with the process ID number to 
	be written, also make sure that either the user has 
	permissions to write under /var/run or that you use 
	the -P option described below to write somewhere where
	it has.
 

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. This procedure is performed automatically when the timeout 
  is reached and no acknowledgements  are received by the server. However, 
  you may wish to speed up the offline process by including the offline
  request in his system's disconnection script. 

  The command: kill -USR2 `cat /var/run/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 disconnection has happened. 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.


  With this option it is possible to use the dhid client in a redundant /
  load sharing DHIS service provided that 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. In the present
  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.


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).
  
   The port is 58800 by default or other if specified in dhid.conf and/or 
   with the -p option. Remember that this only changes the incoming 
   port. The server port (to which the client sends packets) is defined
   at the service provider and cannot be changed by the client.

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

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

  If your host is residing behind a NAT/PAT device (Network Address 
  Translation / Port Translation) such as a Wireless LAN / ADSL router, 
  a bit of additional configuration is needed. 

  Outbound packets are automatically translated and thus require
  no action. I.E. the dhid client sends packets to the server's port 
  58800 and the NAT router translates the inside address to the 
  outside address (possibly dynamically assigned by your ADSL or 
  Cable ISP). 

  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.

  The following diagram illustrates an example scenario of this:

  <host running dhid> -------- ADSL Router  --------- Internet --- DHIS Server
    <10.0.0.1/24>        <10.0.0.254/24>  <dynamic IP>          <212.1.1.1>

  1) Client sends UDP packet from 10.0.0.1 to 212.1.1.1:58000
  2) The router translates the source of the packet to the dynamic IP (NAT)
  3) The server replies to the dynamic IP on port 58800
  4) >>> The router must redirect (DMZ, etc ...) UDP packets to port 58800
         to the inside address 10.0.0.1
  
  Please note: 

  In this case, the IP address considered and marked online by the DHIS
  server is the dynamic IP address, not the internal IP address. 

  Hence if you wish to run a web server for example, on the same or
  a different machine inside your network, you need to redirect TCP port 
  80 as well to the web server.

Services
--------

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

  For further information concerning the dhid daemon, the DHIS server,
  for bug reporting or making suggestions please see our web site at
  www.dhis.org for contact information. 

  We have removed references to email addresses from this distribution 
  due to the excessive amounts of SPAM we were receiving on the 
  support mailboxes.