1 2Install instructions for DHIS server rel5.4 3=========================================== 4 5dhisd is the DHIS server, meant to permit updating external 6databases with dynamically assiged IP addresses to clients. 7 8In order to build the dhisd server the following requirements must 9be met: 10 11 The machine must be permanently connected to the internet 12 with a static IP address. 13 14 The machine which will act as a server should be running 15 a distribution of UNIX or similar system. 16 17 A C compiler is needed. 18 19 The GNU Multi Precision library is required (see section 0 below). 20 21 You need a DNS server that is configured for the zone you wish to 22 update and that allows nsupdates from the server on which dhisd is 23 run. 24 25 260. GMP 27====== 28 29 Before starting to compile DHISD, the GNU MultiPrecision library gmp 30 must be installed. 31 32 It may be downloaded from: 33 34 ftp://ftp.dhis.org/pub/dhis/gmp-4.2.2.tar.gz 35 36 Decompressed. Building should require: 37 38 ./configure 39 make 40 make install 41 421. Compile Stage 43---------------- 44 45 If your system is System V based, edit the Makefile and add 46 -lsocket -lnsl to the LIBS section. These are required 47 for TCP/IP operation. 48 49 Being in the source directory type "make". 50 It should build the dhisd binary. 51 52 If you want to make use of the MySQL support in dhisd-5.4, 53 please edit the Makefile and uncomment 54 55 # -DWITH_MYSQL # From the CFLAGS section 56 # $(MYSQL_LIBDIR) # From the LFLAGS section 57 # -lmysqlclient # From the LIBS section 58 59 The DHIS server relies on the fact that your system has an 60 nsupdate command available under /usr/sbin/nsupdate. 61 If this is not the case you may need to edit nsupdate.h and 62 change its location before compiling the code. 63 64 Build with "make" 65 66 You will need to have a mysqlclient library in your system, 67 typically somewhere under /usr/local. 68 69 702. Install stage 71---------------- 72 73 Create a user called "dhis" and a group called "dhis" 74 75 Type "make install" which will: 76 77 Create /var/log/dhis and assign it to dhis:dhis 78 Create /var/run/dhis and assign it to dhis:dhis 79 80 Copy dhisd and dhisgenkyes to /usr/local/sbin 81 Copy dhis.db.sample and dhisd.conf.sample to /usr/local/etc 82 83 Copy dhisd.rc to /usr/local/etc/rc.d/dhisd 84 85 Otherwise, make sure you start /usr/local/sbin/dhisd on startup 86 87 Make all these files owned by dhis:dhis with appropriate 88 permissions. 89 90 If you plan on using a text based database file: 91 92 Create a text file named dhis.db with a text editor under 93 /usr/local/etc/dhis.db 94 95 Each dynamic host in the database file is represented by 96 a record in the following form: 97 98 ID { 99 hostname something.domain 100 authentication keys 101 } 102 103 104 Example: 3 hosts, 2 with password authentication and 1 with 105 QRC authentication. 106 107 dhis.db: 108 -------- 109 1000 { 110 HostName host1.somewhere.com 111 HostPass secret1 112 } 113 114 1001 { 115 HostName host2.somewhere.com 116 HostPass secret2 117 } 118 1002 { 119 HostName host3.somewhere.com 120 AuthN 62618356157083313953659443711837574706224086057551 121 AuthN 20427737733677817431836864820217527591008711003863 122 AuthN 70979542582114024334017868024554473396638523106022 123 AuthN 2702375049521348659606361903688258217224352016237 124 } 125 126 127 A dynamic record starts with a { and ends with a }. 128 129 The hostid is a unique number that identifies the client. 130 131 HostPass is the text password that the client uses to authenticate. 132 133 AuthN is the client's public key if QRC is being used. 134 Please note that either hostpass or authn must be present 135 for each host but they may not be used together. 136 137 QRC keys may be generated with the dhisgenkeys utility provided 138 in this distribution. Run dhisgenkeys and copy-paste the 139 AuthN lines. AuthP and AuthQ lines are the client's private 140 keys and should be sent to the client wishing to authenticate 141 using QRC. 142 143 authn is the client's public key. It may be represented 144 as a series of authn lines in which case the digits 145 are concatenated in appearance order originating a 146 bigger public key. 147 148 Any line inside a record that does not have a known keyword 149 is discarded and thus, may be used as a comment or additional 150 information. 151 152 Keywords are case insensitive thus AuthN is the same as authn. 153 154 Please note that R3 clients should use password (and hostpass) 155 and not QRC. The authentication sequence is different but 156 the same keywords serves both purposes i.e., password 157 in R3 and R4/R5. 158 159 1003 uses QRC and has the public key resulting 160 from concatenating the number sequence. 161 162 For each new dynamic host added, kill -HUP the dhisd process 163 for database reloading. 164 165 See the README file for more information on the server. 166 167 Start dhisd and add it to your OS's startup scripts: 168 169 /usr/local/sbin/dhisd 170 171 Or in xBSD with the startup script: 172 173 Add dhisd_enable="YES" to rc.conf 174 If you are using a user/group other than dhis add to rc.conf: 175 dhisd_user="auser" 176 dhisd_group="agroup" 177 178 Start the server: 179 180 /usr/local/etc/rc.d/dhisd start 181 182 1833. DNS 184------ 185 186 The purpose of DHIS is to update DNS hosts of a given domain. 187 These hosts need to exist in the nameserver which must be able 188 to accept updates. 189 190 Assuming that you are installing dhisd for a ficticious domain 191 named somewhere.org with BIND, 192 193 Configure your BIND name server 194 195 Add to /etc/named.conf something like: 196 197 zone "somewhere.org" in { 198 type master; 199 file "zonefile"; 200 allow-update { 127.0.0.1; }; 201 }; 202 203 And then create a zone file for the dynamic domain with 204 each dynamic host listed there i.e. 205 206 e.g. 207 208 $TTL 86400 ; 1 day 209 somewhere.org IN SOA is.somewhere.org hostmaster.somewhere.org. ( 210 2007216591 ; serial 211 28800 ; refresh (8 hours) 212 7200 ; retry (2 hours) 213 604800 ; expire (1 week) 214 86400 ; minimum (1 day) 215 ) 216 NS is.somewhere.org. 217 $ORIGIN somewhere.org. 218 $TTL 60 ; 1 minute 219 220 host1 A 192.168.255.0 221 host2 A 192.168.255.0 222 host3 A 192.168.255.0 223 224 And restart the nameserver in order for the changes to take 225 effect and for host1, host2 and host3 to be recognised. 226 227 Note: The nameserver(s) must be the authority servers for the 228 domain you wish to run. 229 230 Note: If you do not add the hosts themselves, dhisd will add them 231 the first time they come online. 232 233 2344. Adding Records 235----------------- 236 237 For each new host, as described above, a new record must be 238 added to dhis.db and a kill -HUP must be sent to the dhisd process. 239 240 For MySQL hosts, see below. 241 2425. MySQL Support 243---------------- 244 245 If you want to have the DHIS hosts in a MySQL table instead of in 246 the dhis.db file, you need to compile the server with MySQL 247 support enabled (see above). 248 249 You then need to edit the configuration file dhisd.conf and add 250 5 parameters that will make dhisd query the database: 251 252 253 DBFile mysql 254 MySQLServer 127.0.0.1 255 MySQLUser dhis 256 MySQLPassword secret 257 MySQLDBase DHIS 258 259 The user dhis must have read/write permissions on the database DHIS. 260 261 In addition you need to create the "DHISHost" table in the database 262 of choice with a schema similar to the following: 263 264 CREATE TABLE `DHISHost` ( 265 `DHISHostID` int(11) NOT NULL DEFAULT '0', 266 `DHISHostName` varchar(127) NOT NULL DEFAULT '', 267 `DHISHostPassword` varchar(127) DEFAULT NULL, 268 `DHISAuthN0` varchar(127) DEFAULT NULL, 269 `DHISAuthN1` varchar(127) DEFAULT NULL, 270 `DHISAuthN2` varchar(127) DEFAULT NULL, 271 `DHISAuthN3` varchar(127) DEFAULT NULL, 272 `DHISStatus` int(11) NOT NULL DEFAULT '0', 273 `DHISOnlineCmd` varchar(255) DEFAULT NULL, 274 `DHISOfflineCmd` varchar(255) DEFAULT NULL, 275 `DHISLastLogin` bigint(20) NOT NULL DEFAULT '0', 276 PRIMARY KEY (`DHISHostID`), 277 UNIQUE KEY `DHISHosts_UID` (`DHISHostID`), 278 UNIQUE KEY `DHISHosts_Hostname` (`DHISHostName`) 279 ) ENGINE=InnoDB; 280 281 And a DHIS Server Log table with: 282 283 CREATE TABLE `DHISServerLog` ( 284 `DHISLogString` varchar(255) NOT NULL DEFAULT '' 285 ) ENGINE=InnoDB; 286 287 All hosts that come online and offline will be logged under 288 DHISServerLog in addition to the default dhisd.log file 289 290 Then add hosts to DHISHost as wished with insert statements. 291 292 Each host must have a DHISHostID, a DHISHostName, 293 a DHISHostPassword OR the 4 QRC keys set DHISAuthN0, DHISAuthN1, 294 DHISAuthN2 and DHISAuthN3, and DHISStatus must be set to anything 295 other than 0 (0 means that the host is locked). 296 297 Everytime a host logs in, the database is updated and the host's 298 DHISLastLogin field is updated with the current date/time as given by 299 the unix time(3) command. 300 301 Once you have created your hosts in the MySQL you can start the dhisd 302 server. Any new hosts or changes need to be reflected in the server 303 with a kill -HUP to it. 304 3056. Running dhisd in debug mode 306------------------------------ 307 308 The DHIS server dhisd may be configured to log DEBUG messages 309 to syslog. 310 311 Currently most messages are logged under LOG_DEBUG so 312 a proper log file specified in syslog.conf is required. 313 314 By default dhisd does not log much. 315 Currently most information will be dumped on level 1 316 and only one function will log on level 2. 317 318 There are two ways of turning debugging on: 319 320 1) Use the -D option 321 322 To log on level 1 use dhisd -D 323 To log on level 2 use dhisd -D -D 324 325 2) Using SIGUSR1 and SIGUSR2 dhisd can be configured 326 at run time to increase or reset its log level. 327 Sengind a SIGURS1 to the dhisd process increases its log 328 level by one. Sending a SIGUSR2 to the process resets 329 the log level to 0. 330 331And that's it. The DHIS server is installed. 332 333