1DHIS Principle and Architecture: 2================================ 3 4 DHIS is a client-server architecture meant to update databases 5 for systems which are assigned a dynamic IP[v4] address. 6 7 By the means of a DHIS client a host which is assigned a dynamic 8 IP address (either from its ISP or from DHCP) is able to 9 communicate with a DHIS server in order to advertise its newly 10 acquired IP address. 11 12 DHIS comprises a UDP based protocol to achieve this purpose. 13 14 A DHIS client has a unique identification number and a set of 15 authentication keys, runs in background, and attempts to reach 16 its server. 17 18 The DHIS server (permanently online) listens to UDP messages 19 from its clients and authenticates these against its knowledge 20 of keys. When authentication is successful the DHIS server 21 updates one or more databases with the newly received IP 22 address for the given client. 23 24 The client then keeps sending, every period of time, refresh 25 messages to the server. If the server doesn't hear from a client 26 for an amount of time (3x refresh period) it considers that the 27 client has gone offline and marks it accordingly with 192.168.255.0 28 (a private unrechable IP address). 29 30 Alternativelly the server may receive an OFFLINE_REQ 31 packet from the client, in which case the DNS record 32 is updated at once and the online state droped. 33 34 In essence the DHIS server: 35 36 Listens to a UDP port for messages from clients 37 Authenticates clients 38 Checks that clients are still connected 39 If not, marks them offline 40 41Compatibility: 42============== 43 44 The DHIS release 5 server dhisd is compatible with release 3 and 45 4 clients. 46 47 Release 3 and 4 servers are not, however, compatible with 48 release 5 clients. 49 50Secure QRC Authentication: 51========================== 52 53 On a secure level DHIS 5 has built in public key authentication based 54 on QRC (Quadratic Residue Cypher). The server(dhisd) supports 55 two methods of authentication, password and qrc. Furthermore, 56 dhisd 5 is compatible with R3 authentication scheme. 57 58 In R5 authentication (and protocol) the client sends an 59 ECHO_REQ packet to the server from which it expects an 60 ECHO_REP. If received the connection is established and 61 the client proceeds to authentication. If mode is password, 62 a simple password is sent raw over the network upon which 63 the server confirms or denies the online state. If scheme 64 is QRC the server sends the client an AUTH_SY packet to 65 which the client must reply with an AUTH_SX before authentication 66 can be confirmed. 67 68 The QRC algorithm, as implemented in DHIS 5, is as follows: 69 70 The client has two 100 digit keys P and Q. The server 71 has (for each client) the public key N obtained by 72 P*Q. P and Q are both prime and congruent to 3 mod 4. 73 When authentication is requested the server generates 74 a random number (prime relative to N) called X and 75 squares it mod N. It then sends its square to the client (Y) 76 which by its turn has to calculte its square root 77 mod N (X') using the chinese remainder theorem. X' is sent 78 back and compared with X. X' may only be calculated 79 knowing the two private keys factors P and Q. 80 81 In order to make use of QRC dhisd uses the GNU Multi 82 Precision Library gmp. 83 84Signals: 85======== 86 87 dhisd accepts HUP and TERM signals. A kill -HUP will 88 make it reload the hosts database and kill -TERM 89 will terminate it. Its pid number is recorded a the 90 text file (default: /var/run/dhis/dhisd.pid) 91 92 Before terminating with SIGTERM dhisd will attempt to bring all 93 online clients offline. 94 95 The pid file location can be changed with either the -P option 96 of the PidFile statement under dhisd.conf 97 98 In addition, a kill -USR1 signal will increate the debug level of 99 dhisd by 1 and a -USR2 will reset its debug level to 0. 100 101Logging: 102======== 103 104 dhisd logs online and offline transitions on a text file 105 (default: /var/log/dhis/dhisd.log) 106 107 The log file location can be changed with either the -l option 108 of the LogFile statement under dhisd.conf 109 110Command Line Options: 111===================== 112 113 dhisd supports the following command line options: 114 115 -b <ipv4addr> binds the server to the interface with the specified 116 IPv4 address instead of the default 0.0.0.0 ANY 117 118 -p <udp port> allows the server to listen to an 119 alternative port. Default is 58800. 120 121 -P <pid_file> allows the specification of an alternative port 122 123 e.g. dhisd -P /var/run/dhisd.pid 124 125 -l <log_file> allows specifying a path for the log file 126 127 e.g. dhisd -l /var/log/dhisd.log 128 129 -d <dbase_file> allows specifying a path for the database file 130 131 e.g. dhisd -d /usr/local/etc/dhis.db 132 133 If the special keyword "mysql" is given as a file, 134 and dhisd has been compiled with MySQL support, 135 dhisd uses the authentication information present 136 in dhisd.conf to connect to a MySQL database and 137 use it as a database instead. 138 139 -D Increases the verbosity log level by 1 140 141 All options may be used in conjunction with each other. 142 143Confirguration File 144=================== 145 146 If specified and if it exists, parameters can be put on a 147 configuration file (default is /usr/local/etc/dhisd.conf) 148 149 The following parameters are supported: 150 151 LogFile a-log-file-location 152 PidFile a-pid-file-location 153 BindAddress The address to bind the server to, default is ANY 154 BindPort The UDP port to use, default is 58000 155 DBFile The location of the database file 156 157 See dhisd.conf.sample for an example. 158 159MySQL Support 160============= 161 162 dhisd 5.4 adds MySQL support in that, instead of using a dhis.db file 163 for keeping the hosts, these can be kept on a MySQL database table. 164 165 In order to add MySQL suport the source code must be compiled with 166 WITH_MYSQL enabled (in the Makefile) and must be linked against 167 the mysqlclient library. 168 169 If enabled, dhisd will try to use an SQL database instead of the 170 traditional text file if and only if the DBFile is set to the special 171 keyword "mysql". 172 173 If so, dhisd needs to know how to reach the database so the following 174 dhisd.conf configuration parameters become mandatory: 175 176 MySQLServer 127.0.0.0 ; Or the IP address of the server 177 MySQLUser auser 178 MySQLPassword userpassword 179 MySQLDBase mysql-database-to-use 180 181 auser with userpassword must exist as a user in the SQL server and 182 must have read/write access to the DHISHost table of the database in 183 use. 184 185 And the parameters must be correct in order to dhisd to connect 186 to the database and load it. If any of them are missed or incorrect 187 dhisd won't run. 188 189 The server queries/updates a table named DHISHost under the specified 190 database. The table should have the following schema at least, although 191 more parameters can be added for other purposes without impact on the 192 server. 193 194 +-------------------+--------------+------+-----+---------+-------+ 195 | Field | Type | Null | Key | Default | Extra | 196 +-------------------+--------------+------+-----+---------+-------+ 197 | DHISHostID | int(11) | NO | PRI | 0 | | 198 | DHISHostName | varchar(127) | NO | UNI | | | 199 | DHISHostPassword | varchar(127) | YES | | NULL | | 200 | DHISAuthN0 | varchar(127) | YES | | NULL | | 201 | DHISAuthN1 | varchar(127) | YES | | NULL | | 202 | DHISAuthN2 | varchar(127) | YES | | NULL | | 203 | DHISAuthN3 | varchar(127) | YES | | NULL | | 204 | DHISStatus | int(11) | NO | | 0 | | 205 | DHISOnlineCmd | varchar(255) | YES | | NULL | | 206 | DHISOfflineCmd | varchar(255) | YES | | NULL | | 207 | DHISLastLogin | bigint(20) | NO | | 0 | | 208 +-------------------+--------------+------+-----+---------+-------+ 209 210Text Database 211============= 212 213 For details on using a text file as a database instead of MySQL 214 (the traditional method) please see dhis.db.sample 215 216Running dhisd as dhis user 217========================== 218 219 The server can and should be run by a user created for that purpose, 220 namely dhis. Running it as root is no longer required. 221 222Multi-server mode: 223================== 224 225 Since release 5 (due to the R5 client) DHIS may be used 226 in more than one server at the same time for redundancy or 227 load sharing purposes. 228 229 DHIS R5 clients has the possibility of specifying multiple 230 redundant servers. When connected the clients try to reach 231 one of the available servers and use the one that provides 232 a faster reply (or a reply at all if others are down). 233 234 The only restriction to running DHIS in redundant multi-servers 235 is to keep exactly the same database files on all redundant systems 236 at all times. 237 238 An example for a redundant or load-balanced dynamic DNS service: 239 240 241 Primary DNS server A Secondary DNS server B 242 | +-----------------+ | 243 | | 244 -------------------------------------------------- 245 | | 246 DHIS Server C DHIS Server D 247 \ / 248 ----- client ----- 249 250 Client attempts to communicate with C and D. Client uses whichever 251 replies (first) and authenticates with it. Say, if C picks up the 252 request, C issues an nsupdate to A or B. An Update is then sent to B 253 or A if DNS NOTIFY is configured. 254 255 If C is down D will keep the system running. 256 257 If is also possible to run multiple DHIS servers on the 258 same machine (using different UDP port and file locations) 259 in either independent or redundant mode. 260 261 262Firewalls: 263========== 264 265 In order to configure a firewall for a DHIS server ensure that: 266 267 The server can receive UDP packets on its listening port 268 (default: 58800) 269 270 The server can send UDP packets to anywhere/anyport 271 (Since the client has the possibility of changing its UDP port) 272 273 274Refreshing and keeping the connection alive: 275============================================ 276 277 The new R5 method of keep-alive for DHIS is as follows: 278 279 The client authenticates with the server. Optionally the 280 client (in the authentication request) sends a refresh 281 rate proposal. 282 283 The server updates the client with its subscribed services 284 and initialises the refresh period to a default of 60 seconds. 285 286 If the refresh period was proposed by the client in the 287 AUTH request the server compares this value against minimum 288 and maximum limits and, if valid, uses this refresh delay 289 instead. 290 291 When N seconds have elapsed the client should send an ECHO_REQ 292 to the server. If the server doesn't receive ECHO_REQs for three 293 periods of time it considers the host offline and marks it 294 accordingly. 295 296 297Online and Offline Commands: 298============================ 299 300 The server may run individual commands for a given client at online 301 and offline transitions. 302 303 For each client in dhis.db: 304 305 If the client record has a line in the form: 306 307 OnCmd /path/to/on/cmd 308 309 /path/to/on/cmd is executed when that client becomes online. 310 311 If the client record has a line in the form: 312 313 OffCmd /path/to/off/cmd 314 315 /path/to/off/cmd is executed when that client becomes offline. 316 317 Both OffCmd and OnCmd executions occur with 2 parameters, 318 the HostID of the client and the IP address acquired via DHIS. 319 320 In addition both oncmd and offcmd commands may be invoqued 321 with additional parameters (3, 4, 5, ...) as they appear 322 in the dhis.db file. The first "word" after the command 323 is passed to the external program as argument 3 (1 and 2 324 are id and address from above), the second as argument 4 325 and so on... 326 327 Example of a simple logging test: 328 329 1000 { 330 hostpass something 331 oncmd /etc/oncmd 332 } 333 334 335 # /etc/oncmd 336 #!/bin/sh 337 # 338 echo I am $1 online now at $2 339 340 OnCmd = oncmd and OffCmd = offcmd as keywords are not case 341 sensitive. 342 343 344Support: 345======== 346 347 Please address any questions or bugs regarding dhisd to 348 support (at) dhis.org 349 350 351