phpSNMP v0.7b
05/02/00

Copyright (C) 1999-2000 Serge Egelman <serge@guanotronic.com>
----------------------------------------------------------------------------
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
----------------------------------------------------------------------------

ABOUT
------

phpSNMP is designed to automate the process of billing a customer based on monthly router stats.  The month and year for the billing period are entered along with a customer's name, and then the script prints out the 95th, 90th, 99th, 50th, and 10th percentiles, and also the maximum, minimum, and average usage for both the incoming and outgoing bandwidth for that month.

phpSNMP also allows you to use htpasswd so that you can have admin and user level accounts, whereby user accounts will only display stats for a specific user, and the admin account will display stats for all users on the system.

phpSNMP works by taking in the month, year, and customer name from a pull-down menu, and then spits out a table of values.  It will first check to see if the data values have already been created and saved in a local file, if it cannot find a file, it queries the MySQL database and parses all of the information.  This works so that if stats for a particular customer for one billing period have already been created, there is no need to waste time parsing thousands of records again.  This saves a lot of time and is safer since backups of all stats will be kept in HTML form.

phpSNMP also includes a script to be entered in cron so that deprecated database entries can be deleted, thus saving valuable space and time (fewer records to sort through).  Since everytime stats are compiled they get saved in HTML form in a directory, old information that is deleted but later needed can be taken from these HTML files.

REQUIREMENTS
-------------

phpSNMP requires the following to be installed:
PHP3
MySQL
Apache
snmpmon (found in the SNMP::Monitor Perl module)

INSTALLATION
-------------

Once you have installed all of the prerequisites, untar phpSNMP into a directory on the webserver.  Edit "mysql.inc.php3" to specify the username and password for MySQL, the name and date of creation of the snmpmon database, the name of the main script, and the hostname of the MySQL server.

Next, edit "ports.inc.php3" to specify the name of each client, the name of the router (this _must_ match the "HOST" field in the snmpmon database), and the port number on that router for this client (this will match the "INTERFACE" field in the snmpmon database).  More editing information can be found in the comments in the file itself.

Then edit "customers.inc.php3" to add the names of each customer and also make sure to have them match the corresponding unique letter specified in "ports.inc.php3".  You will also need to specify the login name for each customer in this file.  These login names correspond to the login names given when setting up htpasswd.  If you do not want to password protect each customer (therefore one customer can view everyone else's stats, in addition to their own) you can ignore this part and delete the specified lines in "customers.inc.php3". 

Next, you must edit the "update.php3" file and add a cron job if you would like to clear out old entries from the snmpmon MySQL database in order to save space (do not worry, if stats are viewed atleast once a month for each customer, the data will still reside in HTML form in the directory).  First you must enter your specific values in this file for the username, password, and location of the MySQL database.  The default is to delete all stats that are over two months old, so if it is January, all stats up until November of the previous year will be deleted.  This time interval can be changed by doing some simple math and changing the switch statement in that file.  After this file is configured properly, you must make a crontab entry for the update script.  I have it clear the database at 3:00AM on the first of every month, this can be done with a cron entry like the following:

0 3 1 * * /var/www/phpSNMP/update


The final thing to be configured is the "data" directory.  You must make a directory titled "data" in the location of all the other scripts ("mkdir data").  This directory must be writable by the user that Apache is run as (for instance, "nobody" on a generic RedHat system, "nobody" or "root" are good guesses on most other systems, use "ps" to make sure).  This directory is where all the compiled data files will reside, so it might be a good idea to not let any other uses read or write here.

Lastly, open up the script in your web browser and everything should work.


TODO
----

In future revisions of this script, I would like to make it so that snmpmon is no longer required.  Instead, I'd like to implement the snmp data collection with a cron job (using a script either written in Perl, PHP, or a shell script).

I'd also like to automate the administration of the customers.  I'd like to build a PHP web interface for adding and removing customers from the script, rather than having to edit all of the config files.

If you would like to help out with maintaining and editing this script, please feel free to do so and email me with changes or suggestions (serge@guanotronic.com)


QUESTIONS / BUGS
-----------------

Feel free to email the author at serge@guanotronic.com with any questions and concerns.
