Torque Network Monitor and Browser source code
Author:    Nathan Martin
Released:  2012-10-29
License:   General Public License 2.0

This contains the torque network monitor and browser PHP scripts that makes
http://master.dottools.net operational. Note that this project is considered unstable
and alpha quality at best. Also, NO WARRANTY OF ANY KIND PROVIDED.


=======================
 Requirements
=======================
  PHP 5.3 (5.2 might work) or better,
    with UDP sockets enabled, PHP safe mode not supported.
    And needs the command line variant in addition to the web server module, mod_php5 in Apache's case.

  MySQL 5.1 or compatible database server.
  ADOdb 5 or better, of which is provided.

  Linux or other UNIX like operating system is recommended and Linux was only tested.
   primarily for the use of cron daemon.
  
 Optional and provided:
  jQuery 1.6.1 min
  Highcharts JS v2.1.4


=======================
 Provided Files
=======================

  tnm\adobd5\                             ADOdb 5 library's PHP files.
  tnm\js\                                 Java Script files for jQuery and Highcarts.
  tnm\imgs\*.png                          Icons for the server browser.
  tnm\page.main.php                       Torque Network Browser home page.
  tnm\page.server.php                     Torque Network Browser server details page.
  torque_browse.php                       Torque Network Browser core. Web facing script and should be renamed to index.php once deployed onto a web server.
  torque_masterd.php                      Torque Network Monitor script. This is the script that is to be ran via cron job every five minutes.
  torque_query.php                        Torque Server Query script. This was the original script for this project, but now just serves as a quick way for experimenting with various protocol methods, or just to see if the master server is currently alive with listing dumps (default configuration).
  queryMasterd.sh                         Cron job script.
  tgeMasterBrowser.sql                    MySQL database SQL file. Use this file to create the database tables for this project's use.


=======================
 TODO and Bugs
=======================

page.server.php:
(3) Does not currently do interpolation of data points for the highcarts JSON data arrays making the resulting data have large jumps between server no response and server seen alive again record updates. When interpolation is finally implemented then the highcarts data points should appear in exact 5 minute intervals just like on the home page for master server statistics carts.

torque_masterd.php:
(1) Incomplete master server listing response handling, currently only cares about the first list packet recieved and doesn't make sure to recieve all listing packets for cases when not all of the listed game servers' addresses + port will fit in a single packet.
(2) Incorrectly resets operation timeout timestamp whenever a game server erratically keeps sending reply packets keeping the script alive infinitely as long as a game server keeps sending packets. This needs to be fixed within the query and response processing state machine and have it ignore already processed game servers.

torque_query.php:
(1) Same as torque_masterd.php's #1


=======================
 Quick Setup
=======================
NOTE: These directions were rushed and I'm not really sorry... so I don't care... kthxbye!


1) Create a MySQL database named "tgeMasterBrowser", or name it anything you like but you'll have to update the $setup['db_base'] variables in both torque_browse.php and torque_masterd.php files.

2) Create two MySQL logins, one as "tgeMasterBrowser" with full rights (or again, anything you want, just update the files), and the second "tgeMasterBrowsRO" account with read only (data SELECT only) access.
   If you're using phpMyAdmin simply generate a random password for each account and make sure to update the $setup['db_pass'] variable in both torque_browse.php and torque_masterd.php files, for 'ReadOnlyPassGoesHere' and 'FullPassGoesHere' passwords respectively.

3) Copy all the files over to a publically web accessible directory, normally where the web server looks for HTML files.

4) Move queryMasterd.sh into your home directory for easy access. Next edit queryMasterd.sh to change
MS_DIR="/home/user/path/to/torqueBrowser" line to the exact directory where you put torque_masterd.php and the other files.
Save the file.

5) In a shell/terminal use crontab -e to edit your user's cron tab and enter a cron job line like so:
*/5 * * * * /home/user/queryMasterd.sh >/dev/null 2>&1

Replace user of /home/user/queryMasterd.sh with your login name used to gain shell access. whoami command comes in handy if you don't know who you are.
Save the file.

6) Go back into the directory where you put all the other torque network browser PHP files and such. Now rename torque_browse.php to index.php if you've placed everything into its own directory.

7) One last thing, if you intent on wanting to monitor your own torque master server instead of GarageGames' then edit torque_masterd.php and search for `$host = "' (without the `' single quotes)
   and replace master.garagegames.com:28002 with your master server's address and port.

8) Now it should be working if everything was configuration and prepared properly. You will have to wait until the cron job runs the torque_masterd.php script to see any updates.

