/*******************************************************************************

    Author ......... Larry Adams
    Contact ........ larryjadams@comcast.net
    Home Site ...... http://www.cacti.net
    Program ........ Cacti Performance Booster
    Version ........ 1.7
    Purpose ........ Large Site Performane Booster for Cacti

*******************************************************************************/


----[ Purpose

    This plugin boost's Cacti performance especially for Large Sites.  It does 
    this by introducing three new features to Cacti.

    First, it caches recently viewed images to a public Cache folder for all 
    users to share.  

    Second, it introduces an "on demand" RRD update feaure to Cacti.  This 
    feature will only update the RRD files when there is demand on the system 
    to view a graph.  The RRD's will be updated just before the Graph is rendered 
    by the web server.  Then, on a predetermined schedule, it conducts a batch 
    update's of all remaining RRD's.  

    Lastly, it introduces an RRD update service to Cacti.  This service allows 
    you to add multiple Cacti servers to your web farm allowing all the servers 
    to participate in the "on demand" RRD update and viewing process.

----[ Features

    On Demand RRD Updates
    Timed and Mass RRD Updates by Number of Records
    RRD Update Service
    PNG Caching

----[ Prerequisites

    Before you install Boost, you need to have met the following pre-requisites:

    1) Cacti 0.8.6i or Above.  Versions of Cacti prior to 0.8.6 are not supported.
    2) Cacti Plugin Architecture v1.x
    3) MySQL 4.1 or above.  Versions of MySQL less than 4.1 are not supported.
    4) Have quite a bit of system memory available to hold your memory resident
       database and/or your sql results during major rrd update cycles.

    Before enabling boost, please consider very carefully how you plan to use it
    long term.  Carefull thought should be given to how often you update RRD's
    at what point you need to either increase your MySQL max heap table size,
    or increase your update frequency.  You should also consider carefully how
    much memory to allocate to PHP when retrieving records during major updates.

    If you are unsure of what I am talking about, you should not use Boost!!!


----[ Installation

    Install is similar to other plugins with the following notes:

    1) You must choose your RRD update cache database format.  There are 
       two options:

       - Memory Resident (MySQL 5.x and Above)
       - MyISAM (All Supported MySQL Versions)

       The benefit of the Memory Resident impmenentation is that database
       exchanges will be very fast and will not delay the system.  However,
       if your system is rebooted between major update cycles, you can loose
       some graph data.  It does also require a new version of MySQL.

       The MyISAM version will increase MySQL load during polling, but does
       store the information in a lossless (well almost anyway) format.

       IMPORTANT: If you plan on using a memory resident database format, 
       make sure you set the mysql environment variable "max_heap_table_size"
       large enough to accomodate all of your records, else, you will loose 
       data.  This environment must go into either your my.cnf or my.ini file.

       To install either format, you must follow the instructions below:

       mysql -u <user> -p cacti < "my_chosen_format.sql"

       Options here are as follows:

       boost_sql_memory.sql, boost_sql_myisam.sql

    2) Once you have the SQL in place, you must enable you plugin by adding
       the boost plugin into cacti's <path_cacti>/include/config.php file not
       unlike other plugins.

    3) The files in the modified directory of this plugin must be moved to
       Cacti's base directory.  Please insure that you copy the files in
       the lib directory as well.

       Important Note: If using Boost 1.3 and Cacti 0.8.6j or below, you must
       replace the poller.php in the base directory with the revised one 
       in the modified directory.

    4) Then, you must decide on directories to hold both your PNG and RRD
       directories.  Once you have decided, create these directories and
       verify your poller user has "RW" and your Web user has "R" access to the
       RRD directory and "RW" to the PNG directory. 

    5) Next you have to enable any of the three features mentioned.  You can
       do this by going to your Cacti website, logging in as an adminnistrator
       and going to the Settings->Performance Booster tab.

    6) If your Web server is not going to have access to create/update RRD
       files, you must start the "boost_server.php" file as a service.  You
       should do this once at boot time.  In the UNIX/LINUX environment, you
       can perform this using a script that was provided by Jimmy Connor 
       (cigamit) to do this.  Please see the file cacti_rrdsvc.  Place this
       file in the /etc/init.d folder.  Once it is there, you need to edit it
       and modify the variable PROGPATH to poing to the location of
       boost_server.php.  Once those steps are complete, run the following 
       commands.

       On Most Linux Variants:
       dos2unix cacti_rrdsvc (sorry, I'm still writing in Windows)
       chkconfig --add cacti_rrdsvc
       chkconfig cacti_rrdsvc on

       Then either:

       service cacti_rrdsvc start

       or:

       /etc/init.d/cacti_rrdsvc start

       make sure it's running by issuing the following command:

       ps -ef | grep cacti_rrdsvc

    7) Finally, you can poll the server using telnet.  To do so, start a telnet
       session on the port you choose to use (default 9050) and type the 
       "status" command followd by a carriage return.  You should receive a 
       favorable response.
    
----[ Additional Help?

    If you need additional help, please goto forums.cacti.net.

----[ Possible Bugs?
   
    If you figure out this problem, let me know!!!

----[ Special Thanks

    Ernest Wilson (N3NCY) - For allowing me to break and then fix his
    system repeatedly perfecting this Plugin.

    Jimmy Connor (cigamit) - For bringing the plugin architecture to
    the world of Cacti and provding continual support of my development
    efforts.

----[ Future Changes
    
    Got any ideas or complaints, please e-mail me!

----[ Changelog
    --- SVN ---

    --- 1.0 ---
    Initial release

    --- 1.1 ---
    bug: Fix issues with Multiprocess RRDupdating of RRD Files

    --- 1.2 ---
    bug: Added boost_server.php and poller_boost.php to the no session array

    bug: Made slight change to rrd-update functions to accomodate for abarant
    output in the poller_output_boost table.  This would cause the boost
    plugin to loose data if improperly formatted data made it into the table.

    --- 1.3 ---
    bug: Fixed an issue where multi part responses with a "0" would return "U"

    feature: Added better logging functions to help in debugging

    feature: Allow you to increase the MySQL Insert string length to improve performance

    feature: Allow you to increase the RRDtool update string length to improve performance

    --- 1.4 ---
    bug: Fixed an issue with data queries where the rrdupdate template was not formated correctly

    --- 1.5 ---
    bug: Under some circumstanced the poller_boost.php could not be fored to run

    bug: Scripts that do not return the correct number of DS' did not update properly

    bug: New forcerun option introduced in version 1.3 was causing boost not disable properly
    when you unselected it from the user interface.

    --- 1.6 ---
    feature: make the delete process a high performance one by batching the deletes

    bug: set a good memory limit and runtime in poller_boost.php

		--- 1.7 ---
		feature: Add Cacti 0.8.7 compatibility