GnuGK Current Calls Monitor v 1.0
===========================================

	1.0  Overview
	2.0  Prerequisites
	3.0  Description of Files
	4.0  Installation
	5.0  Database Connectivity
	6.0  Acknowledgements & Apologies


1.0  Overview
--------------------------------

This is a basic current call monitoring system for those who use GnuGK as a switching platform for wholesale traffic movement released under the same licensing terms as GnuGK.

The scripts will provide a webpage with two tables:
A. Calls being originated sorted as Destination Routes on x-axis and Originators on y-axis
B. Calls being terminated by each of the endpoints

All call data are shown in "Run.Try" format, where Run implies calls that are connected (has more than 0 second duration value) and Try means calls that are not yet connected (has 0 second duration value).

The scripts are configured to refresh every 15 seconds, meaning all data is refreshed every 15 seconds.  The script shows the time when the data was pulled from the GnuGK along with the delay from that time to the time when the webpage was generated.


2.0  Prerequisites
--------------------------------

The scripts were created and tested using Apache 2.0.54 and PHP 5.1.1.


3.0  Description of Files
--------------------------------

The total system comes with 6 files (without this Readme.txt):

* gk_status.php => This is the file that is to be called by the web browser.  This file basically reads data from text files and parses the data to create the view.  The files being read are (in order of read):
	gk_status.inc.php (comes along with the archive)
	gk_custsupp.csv (comes along with the archive)
	gk_routes.csv (comes along with the archive)
	gk_ep.txt (has to be generated using get_gkep.php)
	gk_now.txt (has to be generated using get_gknow.txt)
    Description of each files are given below separately.  However, please keep in mind that each of these files are required by the gk_status.php file to output the correct data.

* gk_status.inc.php => This is the configuration file, and is the only file that needs to be edited.  Please put the appropriate values in the three lines.  Please note that the $path variable should refer to the current absolute path with respect to your operating system, as some webservers might not give proper file paths when processing a webpage.

* gk_custsupp.csv => This is the file that contains customer / suppliers' names along with the IP addresses that they use.  Since the same IP can both originate and terminate traffic, the file is called "custsupp".  This data can also be used to modify the existing "Terminated To" table to look like the "Originated From" table, with some minor adjustments to the gk_status.php file, but since that was not desired by the creators, it has been skipped.

* gk_routes.csv => This is another text file that contains all the routes that are being handled by the GnuGK.  No route names are given to avoide cluttering the display.  Just entering any number of routes in the sample format is sufficient.

* get_gkep.php => This file creates the gk_ep.txt file which is read by the gk_status.php script.  Since new endpoints are added at much lesser frequency, this is to be run manually.  A link to this file is also given at the bottom row of the "Terminated To" table.  Usually, endpoints that are not on file but has been added in GnuGK will come up as "0.0.0.0" entries in the "Terminated To" table.

* get_gknow.php => This is the data retreiver for all the call information being displayed.  Please put this file on cron / task_scheduler to run automatically every 1 minute if it becomes inactive.  Once the script starts running it does not stop unless it encounters an error in its operation. Typical erros are read errors, or socket being hung, etc.  One extra feature of this script is it usually exits by closing the socket safely using the fclose() function.  To use this safe exit manually (as opposed to killing the process / application via the operating system), just create an empty file named "stop_gknow" (note the absence of any extensions), and the script should exit gracefully.


4.0  Installation
--------------------------------

If you've read the above section, the system should be clear by now, but if want to start right away, or if you are encountering problems, please follow these steps:

	i. Create a folder in your web document root and copy all files from the archive.
	ii. Edit the gk_status.inc.php file to put the values of the path (the absolute file system path of the folder that you just created above), ip of the gnugk to be monitored and username / password combination for this gnugk to logon to the status port.
	iii. Run the get_gkep.php script to create the base gk_ep.txt file.
	iv. Put the get_gknow.php script in the cron job / task scheduler so that this file keeps running to get the most data.  Typical settings would include running the file continuously and check if it is running every minute so that it can be restarted if it exits for some reason.
	v. Open the gk_status.php file using your web browser by using the http path of your server.

    At this point your browser should show you the current status of calls.  The get_gknow.php script usually takes upto 5 seconds (depending upon latency, and several other limiting factors) to be able to create the first instance of gk_now.txt.  Check if your gk_now.txt is being created / updated at regular intervals, and if yes, then your system is working fine.  Enjoy!


5.0  Database Connectivity
--------------------------------

The original program was created to query the database for customer / suppliers' names & ipaddresses and routes.  However, it was ported to a text file read system for ease of use by other users.  The database connectivity portion can be provided upon request.


6.0  Acknowledgements & Apologies
--------------------------------

We would like to thank the developers of GnugK for their time and energy that they have dedicated towards this project.  We shall forever remain indebted to their work.

Lastly, we apologize for any inconvenience faced by the users.  The scripts are also not very organized and might need some time to get used to.  Please send any questions / suggestions to mnhassan at the rate of usa dot net.