eKo Pro Cloud Based DB and UI Files

       eKo Pro Cloud Based DB and UI  Installation and Release Notes: 

                                   by Mark Holler - Camalie Networks  11/1/11

The eKo Pro Cloud Based DB and UI consists of several components. 
	A. drraw.cgi Web based user interface for graphing sensor data.  Written in PERL it 
           pulls data from an RRDtools database and produces HTML pages which are served by Apache.
	B. snetmonEKOxxx.pl  PERL script which connects to an eKo Pro Gateway over the internet  
           via a socket and receives, parses and stores data into an RRDtools database. It receives a copy
	   of the data packet stream that eKo Pro gateway is receiving from a set of wireless eKo Pro 
	   network nodes in the field. The eKo Pro nodes have sensors connected and send packets with data
           from those sensors. The sensors are typically, temp/humidity, soil moisture, wind, rain, etc.  
	C. snetmsEKOxxx.pl  PERL script to stop and start snetmonEKOxxx.pl when the server is rebooted. optional
	D. snetmonEKOxxxwatch.pl  PERL script which watches the updating of the database files for 
		interruptions in excess of 2 hours in which case it restarts snetmonEKOxxx.pl It will also start
                snetmonEKOxxx.pl within 2 hours of a reboot making snetmsEKOxxx.pl superfluous.

******************************* Installation and Configuration **********************************************

To install these components to run automatically at bootup on an Ubuntu 10.04 based computer: 

	0.   Create a user account on the Ubuntu 10.04 host computer and log in as user.

	1.   Use the synaptic package manager to install rrdtool 1.3.8-1 and apache2 2.2.14-5 and libRRDs.perl

	2.   Open a terminal window sudo su to become root then use mkdir to create the following directories.  
						/usr/cnets/mkscode/ for the snetmon perl script
                                                /usr/cnets/watches/ for watch programs 
						/usr/cnets/RRDs/    for the RRD databases. 
						/var/www/cgi-bin
						/var/www/html 
   	     Change the ownership of these directories from root to user by doing "chown -R user /usr/cnets/" and
              "chown -R user /var/www/cgi-bin/"   and "chown -R user /var/www/html/" 
						/var/lib/drraw
						/var/cache/drraw
	     Change ownership of these directories from user to www-data by becoming root and doing 
              "chown -R www-data /var/lib/drraw" and equivalent for /var/cache/drraw.  

	3.  Open Firefox and go to http://sourceforge.net  and find the project "eKo Pro Cloud Based DB and UI"
		Download the following files and copy them into the 
		corresponding directories: 
			snetmonEKOBOR.pl   --> /usr/cnets/mkscode/
			drraw.cgi           --> /var/www/cgi-bin/    
			drraw.conf          --> /var/www/cgi-bin/
 
			000-default        --> /etc/apache2/sites-enabled/  will need to do as root, use sudo su
			snetmsEKOBOR       --> /etc/init.d/   will need to do as root, use sudo su 

		Enable execution of all using  "sudo su"  and then like "chmod u+x /etc/init.d/snetmsEKOBOR"
		Verify using ls -l  look for x as the fourth character is the permissions string.      
		
	   In the file names above, "BOR" is a three letter acronym (TLA) associated with the eKo Pro system 
		being monitored.  In this case BOR stands for Blue Oak Ranch.  If multiple systems are being 
		monitored there will be unique versions of each of the snet* files above, each three with their
		own TLA corresponding to the system being monitored.   

	4. Edit the snetmonEKOBOR.pl file for the specific eKo Pro gateway you want to monitor/capture data from.
		a. Edit the IP address assigned to $host in snetmonEKOBOR.pl to be the address
			 of the eKo View server providing the data stream. You must do this much. 
                b.  If you are going to be monitoring more than one network or if you just want to use your own 
		       TLA in all of the files then Edit $networkTLA="BOR";  substituting your own TLA.   
			This TLA is used in the RRD filenames for the eKo Pro server being monitored.
			The TLA is used to differentiate the RRD database files for different eKo Pro systems
		a. Test the snetmonEKOBOR.pl script by running it from the command prompt in a terminal window
			use the command  ./snetmonEKOBOR.pl  It should connect to the desired server and 
			provide a stream of messages and data. 
			It also writes this stream to a log file /tmp/snetmonEKOxxx.log deleted each reboot.

	5. To get snetmonEKOBOR.pl to run automatically at boot create a symbolic link in /etc/rc2.d to the
	     snetmsEKOBOR script. This is the directory Linux looks for scripts to run on a level 2 startup 
             which is the default level.  Do the following as root from the command line. 
		a. Test the script; "sudo su" to become root, then  "cd /etc/init.d"  then "./snetmsEKOBOR start"
		b. You should get the response "snetmonEKOBOR started"
		a. Create a symbolic link in the level 2 startup dir to the script by going  "cd /etc/rc2.d"
		    ln -s /etc/init.d/snetmsEKOBOR S60snetmsEKOBOR     This creates the symlink
		c. Reboot your system to see if snetmonEKOBOR has started properly, use the system monitor to see.
	             The reboot will also start up apache2 which you will need to serve the drraw U.I. 
			
	6. The file 000-default installed above directs apache2 to the location of the "drraw" grapher. 
		a. With Firefox open the site http://localhost/cgi-bin/drraw.cgi.  All functionality of the 
                   grapher should be available although it will take some time for snetmonEKOBOR.pl to 
                   accumulate some data. 
		b. If you already have RRD databases you can just copy the xxx.rrd files to /usr/cnets/RRDs/ 
		   and they will show up on drraw's data selection page.  If you want to back up your data, backup
                   the xxx.rrd files in this directory to somewhere safe.  They can be restored by just copying
		   them back.  	

	7. Copy the watch program snetmonEKOBORwatch to /etc/cron.hourly
                a. sudo su
                b. cd /home/user/Downloads
  		c. cp snetmonEKOBORwatch /etc/cron.hourly		
   		d. change permissions to allow execution.  chmod u+x snetmonEKOBORwatch
 		e. test the watch program to be sure it runs.  ./snetmonEKOBORwatch
		f. snetmonEKOBORwatch will be run hourly at 17 minutes past the hour to check if 
                       snetmon is still running and if not restart it.  It checks to see if snetmon has changed
		       any database files in the last 20 minutes. 
	8. To secure this software from random modification of your graphs from the web you can use Apache's build in security.
		a. Add the following lines to /etc/apache2/sites-enabled/000-default below the line <Directory "/var/www/cgi-bin">
			Authname "protected"	
			Authtype Basic
			AuthUserFile /var/www/.htpasswd
			AuthGroupFile /dev/null
			require user user
		b. Use synaptic package manager to download libapache2-mod-auth-plain     
		c. create a password for user by running the command htpasswd -c .htpasswd user     
		     Enter the desired password for user twice as prompted. Do this while in /var/www/


	9. If you want to add additional html content to the site I suggest downloading bluefish with the synaptic
           package manager and inserting the files in the /var/www/html/ subdirectory.  This is where I typically 
           put satellite imagery with node placements on them for reference in interpreting the data.  
	

****************************  Release Notes  11/1/11  ************************************************************

The current version is based on Christophe Kalt's last posted version of drraw 2b-2.  I have designated the current release 2.2c1.  This version supports the RRDtools features associated with version 1.2.1x and beyond.  Key features added in the current release are 
	1. Comma separated value file exports of the data associated with any graph. 
	2. Guidance on how to secure the interface using Apache access security. Thanks to Christophe Kalt for clueing us in on this.   

All of the graph, dashboard and template definitions are stored in /var/lib/drraw/.  It is a good idea to back up all the files in this directory periodically if you have spent a lot of time specifying a set of graphs and dashboards. Copying back the whole set of graphs restores all the graphs etc. that you saved. However, to save new graphs you will need to change ownership of the copied back files to www-data by going to /var/lib/ and doing a "chown -R www-data drraw" at the command line.   To see the files in this subdirectory you will need to add user to the www-data group. 

*****************************  Acknowledgements:  ***************************************************************
   Funding for this Open Source release was provided by the University of California - Berkeley researcher  
   Michael Hamilton stationed at the Blue Oak Ranch Reserve where a 38 node eKo Pro network provides a steady
    stream of data. Please don't abuse this data stream or we will have to block its use.     
   The drraw program was written and maintained by Christophe Kalt from 2003-2008, modified here by M. Holler
    M.Holler added the .csv file export capability.  
   The security fix was elaborated by Luke Gordon. 10/24/11