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: -------- ADSL Router --------- Internet --- DHIS Server <10.0.0.1/24> <10.0.0.254/24> <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.