==========================================================================

		INSTALLATION NOTES FOR mod_benchmark

		VERSION: 1.6.0

==========================================================================

1.REQUIREMENTS
--------------

a) Linux 2.4.x
b) Apache 2.x.y
c) PHP 4+
d) MySQL 3/4 (optional) or Sybase 10+ (optional)
e) a Browser that supports SVG 

Notes:
* This Apache module has been only developped for Linux platforms.
It has been tested on 2.4.x kernel. It should (could ?) work on 2.2.x if
sysstat2.c file is checked towards the /proc/... files used.

* for users who want to interface mod_benchmark GUI with Sybase, we
recommend the use of the FreeTDS interface (see www.freetds.org) 
(tested version: 0.61)



2.INSTALLATION
--------------

2.1.Compilation
---------------

a) get the mod_benchmark-1.6.tar.gz archive and expand it under
   a directory

b) run ./configure with at least on the option to enable a DB manager:
	--enable-mysql
     or --enable-pgsql
     or --enable-sybase

     and one of the two following options depending on your Apache server version:
        --with-apxs=[path to apxs]	if you're using Apache 1.x
     or --with -apxs2=[path to apxs]	if you're using Apache 2.x

     Example:
     
     ./configure --enable-mysql --with-mysqldir=/usr/include/mysql --with-apxs=/usr/sbin/apxs

     Note: if the include files for the DB interface are not found at compile time,
  	   add one of the following directive:
	   	--with-mysqldir=[dir] or 
		--with-sybasedir=[dir] or
		--with-pgsqldir=[dir]

     you also must include (if needed) the corresponding parameter to indicate the database
     client library location with:

		--with-mysqllib=[dir] or
		--with-sybaselib=[dir] or
		--with-pgsqllib=[dir]

     Note that we *strongly* recommend the use of the FreeTDS package to connect mod_benchmark
     to a Sybase directory (tested with version 0.61 available at www.freetds.org).

c) run "make"

d) run "make install"
   Since the Makefile has been created by apxs, it will try to copy
   the module and its related file under the Apache module directory.

e) check that the following new files have been copied under the Apache module
   directory:
   	mod_benchmark.so
	benchmark-mysql.so (optional)
	benchmark-pgsql.so (optional)
	benchmark-sybase.so (optional)

   mod_benchmark.so is the Apache module
   benchmark-mysql.so is the interface between the module and the MySQL database. 
   benchmark-pgsql.so is the interface between the module and the PostgreSQL database. 
   benchmark-sybase.so is the interface between the module and a SYBASE database.
   
   If you want to use another DB, create your own benchmark-db.c
   driver (it's very easy !) or send a mail to support@trickytools.com.



2.2.Database table creation
---------------------------

mod_benchmark will log the measured requests and the alerts in a database.
You can use an existing DB or create a new one.

a) choose or create a database 

b) run the "sql/mod_benchmark-mysql.sql" or "sql/mod_benchmark-sybase.sql" or 
   "sql/mod_benchmark-pgsql.sql" script to create the tables in the DB

c) create a user/passwd that can access these tables, if necessary



3.APACHE CONFIGURATION
----------------------

a) edit the "httpd.conf" file and add at least the directives for "mod_benchmark":
   (see the benchmark/directives.html file)
   Add a LoadModule directive to make apache load the module:

   	LoadModule benchmark_module modules_location/mod_benchmark.so

   Under Apache 1.x, you may also have to add the directive:

	AddModule mod_benchmark.c

   Now add the directives that activates the module, for example:

   BenchmarkStore /path_to_db_module.so:dbserver:dbname:user:password
   <Location /mydir>
	BenchmarkEngine on
	BenchmarkAccept .*
   </Location>

b) restart Apache

   If an error occurrs, the message should be self-explanatory. Otherwise read the
   FAQs. The most common errors are:
	- a problem at module load time: a needed external library could not be
 	  found or there is an external symbol not resolved. Check with "ldd" that
	  the module refers to the good DB interface (aka: mod_benchmark-mysql.so
	  is dynamically linked to libmysqlclient.so). If not, check the "configure"
	  script has well determined libmysqlclient location. If not, modify the
	  LDFLAGS environment variable such as: 
		$ export LDFLAGS=-L/usr/lib/mysql (read the FAQ)
	- wrong right access to the DB



4.TEST APACHE
-------------

a) using your favorite browser, navigate through any location handled by
   "mod_benchmark" (one is enough !)

b) connect to the DB and check one row has been inserted for each request.
   If not, check the error logs (Apache, MySQL, system...) and fix the bug.



5.STATISTICS VIEWER CONFIGURATION
---------------------------------

a) under the installation directory, there is a subdirectory named "benchmark",
   make a symbolic link for this subdir under your web server tree.

b) change the owner & group of "benchmark" subdir to reflect the owner & group
   normally used for your Apache server

c) cd to "benchmark" subdir

d) edit "yourglobals.inc.php" file and put the good DB parameters here...



6.TEST VIEWER
-------------

a) switch to your browser and navigate to the newly created "benchmark" subdir.
   
b) if your Apache server is configured to automatically return the "index.html"
   file, you will see the control panel, otherwise, click on "index.html" file

c) Select the "1 Hour" Duration and leave the other parameters unchanged.
   Then press the "Get Report" button.

d) a chart should appear !!! Congratulations.
   otherwise, there is a DB or PHP misconfiguration. The error message should
   be explicit enough. To help you, each SQL error is alos logged using the
   syslog facility.


THANKS FOR YOUR PATIENCE !

================================ EOF =====================================