SUMMARY
=======

An Apache 2 only module serving link counting information via jpeg and png images. Configuration commands include font selection, font size, image type, image background and text color, digit width, reset, ignore, access list database, and random. Direct support for RedHat 8.0 distribution with the required gd-1.8.4, zlib1.1.4, libjpeg6b, Berkeley DB 4.0.14, libpng-1.2.3, and Freetype 2.0.9 installed, via RPM. An port of pre Apache 2 mod_ometer to Apache 2.

REQUIRES
========
gd-1.8.4 (gd-1.8.4.tar.gzgd-1.8.4-9.src.rpm)
zlib-1.1.4 (zlib-1.1.4-4.src.rpm, most versions included with dist seem to be adequate)
libjpeg6b (libjpeg-6b-21.src.rpm)
Berkeley DB >= 4.0.14 (db-4.0.14.tar.gz, db-4.1.25.tar.gz, db4-4.0.14-14.src.rpm)
Freetype 2.1.2 (FreeType-2.1.2-7.src.rpm, freetype-2.1.4.tar.gz)
libpng-1.2.3 (libpng-1.2.2-6.src.rpm)
libm (standard C math library)
gcc.
True Type fonts (use the web, grasshopper).
Reading skills. If you cannot read, do not continue.

USAGE
=====

font=font
Specify the font for the counter image text/digits. A font error is indicated by "Efont".

width=number
Specify the number of digits/chars displayed. If the count requires more digits/chars, then "Eovr" is returned. Use with caution as some errors will be displayed as "Eovr" if width is only a couple of digits. A width=0 will use exactly the number of digits/chars required (default). The max value is 10.

rand=true
Just displays a random number.

reset=access
The links' access list is removed from the database. Success is indicated by the returned image "Arst". If link is not currently in the database, "NoLink" is returned.

reset=delete
The links' counter value is removed from the database. If the link has an access list, it remains in the database. If the link is not currently in the database, "NoLink" is returned.

reset=number
If the link has a current counter value in the database, it is returned, and the links' database counter value is set to the specified new value. Otherwise, the new link is added to the database, the links' counter value is set to the specified new value, and "Cadd" is returned. Planned in a future release is a default value option. Any commands specified during the counter reset/ initialization phase will become the link defaults, and not be required on subsequent calls.

image=[jpeg, png]
Specify the return image to be jpeg or png. If the module has been compiled with USE_PNG_IF_ACCEPTABLE, and the requesting client accepts png images, then a png image will be returned.

point=number
Specifies the point size of the font.

link=linkname
The linkname to be associated with this counter.

ignore=[IPADDR, DOMAINNAME]
These cannot increment the counter.

text=000000
The font color using "web color" rgb notation.

bgcolor=000000
The image background color.

count=inc
Specifies that the count should be incremented as if the link is unique.


DATABASE
========
The counter database maintains, for each link, a current count value and an access list. The links' counter value is incremented when a new hostname is added to the links' access list. The links' counter value may be changed with the reset command. The links' counter value may be deleted from the database with the reset=delete command. The links' access list may be deleted from the database with the reset=access command.


CREDITS
=======

Ported to Apache 2 by <Byron Young> spamiccling@yahoo.com, bkyoung@users.sourceforge.net
Adapted from mod_ometer by J Craig. See modules.apache.org for more information.


COMMON ERRORS
=============
Attempting to increment a link that has not be inserted into the database:
	   <IMG src="www.counter.com/counter?link=linkname">
  The image displays NoLink.
Solution:
	<IMG src="www.counter.com/counter?link=linkname&reset=0">
  The image will display "Cadd".
	<IMG src="www.counter.com/counter?link=linkname">
  The image will display 0 if hostname is in the linknames' access list, and 1 if it is not.

In general, avoid duplicate <IMG src=""> tags in a html page. Browsers tend to optimize resource retrievals, and could receive the count image out of desired order.

If the error log continues to spew out Unlock failed messages, verify database lock file is not present.

URL FORMATION
=============

Counter Usage:

Insert the link into the database and set the counter to the initial value:
       <IMG src="www.counter.com/counter?link=linkname&reset=#">
  The image will indicate success with "Cadd".

Display the counter, incrementing it first if necessary.
	<IMG src="www.counter.com/counter?link=linkname">
  The image will display the count.

Reset the counter to a arbitrary value:
       <IMG src="www.counter.com/counter?link=linkname&reset=#">
  If the link is currently present in the database, the old value is displayed.
  If the link was added to the database, "Cadd" is displayed.

Reset the access list to empty:
      <IMG src="www.counter.com/counter?link=linkname&reset=access">
  The image will display Arst (Access Reset).

Remove the link from the counter database.
       <IMG src="www.counter.com/counter?link=linkname&reset=delete">
  The image will display Del. (Deleted)


INSTALLATION
============
Review the included module configuration file for example configuration.

Verify the required rpms are installed.
rpm -i --test /usr/src/redhat/RPMS/i386/mod_countm-2.0Beta.i386.rpm

Install any missing requirements.

Verify the server is not running.
/etc/rc.d/init.d/httpd status

If it is, then stop the server.
/etc/rc.d/init.d/httpd stop

Install the rpm.
rpm -i mod_countm-2.0-2Beta.i386.rpm

Adjusting /etc/httpd/conf.d/mod_countm.conf should not be necessary.

Restart the server.
/etc/rc.d/init.d/httpd start

Move the test index.html page into /var/www/html/test

Launch Netscape, and enter www.yourdomain/test/index.html

Automate httpd startup with:
chkconfig httpd on

CHECK THE ERROR LOGS
====================
/var/log/httpd/error_log
/var/countm/dbase/db.log

QUICK DATABASE CHECK
====================
Assuming that db4-utils is installed.
To quickly view the database:
db_dump -p /var/countm/dbase/countm.db.

REMOVAL
=======
rpm -e mod_countm

DEVELOPMENT STATUS
==================
The project is currently in Alpha phase. Project will advance to Beta phase up successful Test completion in other environments.

OPERATING SYSTEM
================
RedHat 8.0 Linux/ Apache 2.0.44
RedHat 9.0 Linux/ Apache 2.0.44

INTENDED AUDIENCE
=================
As a simple page counter, the project is intended for small office/ home office system administrators interested in adding page counter capabilities to their Apache server.


SOURCEFORGE.NET INFORMATION
===========================
Development Status: 1-Stable
Operating System: POSIX: Linux
Topic: Internet: WWW/HTTP: Dynamic Content: Page Counters
Intended Audience: Other Audience
License: OSI Approved: BSD License
Programming Language: C
Environment: Web Environment
Natural Language: English
Project Unix Name: countm

DISTRIBUTION FILES
==================

Stable Release 2.0
mod_countm-2.0
apache2-mod_countm-2.0-3rh.src.rpm
apache2-mod_countm-2.0-3rh.i386.rpm

Alpha Relese 2.0
mod_countm-2.0.tar.bz2
mod_countm-2.0-3Beta.src.rpm
mod_countm-2.0-3Beta.i386.rpm


RELEASE DATE
============
11-09-03 advanced to stable 2.0 version RH9,RH8

4-14-03 released RH8.0 Alpha version.


BUILDING THE MODULE
===================

The following are commands for a recent BASH shell.

Download the sources from CVS.
CVSROOT=:pserver:anonymous@cvs.sourceforge.net:/cvsroot/countm
export CVSROOT
cvs login
password: <just hit enter>
cvs co countm
cvs logout
cd countm


Determine the version of autoconf installed on your system.
If autoconf --version == 2.13, then use configure.in.
If autoconf --version == 2.53, then use configure.ac.

The major difference between configure scripts produced is the variable passing method. The configure produced using 2.13 requires all variables be passed via global environmental variables. The configure produced using 2.53 will accept the variables defined on the configure script command line.

Create the configure script.
(2.13) autoconf configure.in
(2.53) autoconf configure.ac

Configure the build. This step will create mod_countm.conf and Makefile.
./configure

The following commands are recognized by configure:

--with-httpd
directory(absolute) containing httpd.h (and other httpd header files)
if not specified, or --with-httpd=yes, then is assumed to be in standard include path.
For RedHat 8.0 --with-httpd=/usr/lib/httpd

--with-apxs
The directory(absolute) containing apxs.
If not specified, or --with-apxs=yes, then assumed to be in PATH.
For RedHat 8.0 --with-apxs=/usr/sbin

--with-doxygen
The directory(absolute) containing doxygen.
For RedHat 8.0 --with-doxygen=/usr/bin
doxygen is optional. If doxygen configures properly, typing make dox will build some html files.

libexecdir=
Set libexecdir to the location to install the built module.
Directory must exist, or build will fail (configuration may succeed).
Set this variable. Almost no installations will work with the default value.
For RedHat 8.0 libexecdir=/usr/lib/httpd/modules

sysconfdir=
Directory to place module httpd configuration file.
RedHat 8.0 sysconfdir=/etc/httpd/conf.d

localstatedir=
Directory to place runtime database, lock, and log files.
RedHat 8.0 localstatedir=/var/countm

The following variables are recognized by configure. For 2.53, they may be passed via the command line.
APXS_CFLAGS=
Use -Wc and -Wl to pass flags to the APXS compiler.
For RedHat 8.0 APXS_FLAGS="-Wc,-O2 -Wc,-Wall"

DEBUG=-DDEBUG
To activate debugging
Specifying DEBUG will not include the -g in CFLAGS.

APXS_LIBDIRS=
The directories of the required libraries, if the libraries are not in standard location.
Requires a -L prior to each library directory.
example: APXS_LIBDIRS="-L/usr/lib/gd -L/usr/lib/db"
Not required for RedHat 8.0

The following variables are recognized by configure, but are used by the maintainer.
TEST_HTML=
The location of the html test pages.
RedHat 8.0, /var/www/html/test

APACHECTL=
The apache control program.
RedHat 8.0, /etc/rc.d/init.d/httpd

APACHEOWNER=
The user id of the httpd daemon.
RedHat 8.0, apache

APACHEGROUP=
The group id of the httpd daemon.
RedHat 8.0, apache

ERROR_LOG=
The httpd error log.
RedHat 8.0, /var/log/httpd/error_log

The following may or may not be required, depending on the type of tools used, and generally must be passed to the tool via a global environmental variable.
LDFLAGS=
if any of the required libraries are NOT in the standard library include paths, then pass their location to configure with LDFLAGS=-L/directory of library. Because of the way APXS builds the module, the  library directory may need to be passed with APXS_CFLAGS using -Wl,-Ldir.
For RedaHat 8.0 LDFLAGS is not required.

CFLAGS=
Define to any extra flags you wish to send to the compilier.
For RedHat 8.0, using CFLAGS=-O2 avoids placing debugging information in the library.

The complete command line for RedHat 8.0 (autoconf 2.53) is:
./configure --with-httpd=/usr/include/httpd --with-apxs=/usr/sbin libexecdir=/usr/lib/httpd/modules CFLAGS= --with-doxygen=yes sysconfdir=/etc/httpd/conf.d localstatedir=/var/countm APXS_CFLAGS="-Wc,-O2 -Wc,-Wall" DEBUG=

Because of APXS, the make part installs the module.
The make install part installs the config file and the resources directory/files.
make uninstall removes the module, the config file, and the resources directory/files.
Use uninstall with caution!!

FILES CREATED/INSTALLED
=======================
Assuming a default RedHat 8.0/9.0 installation:
/usr/lib/httpd/modules/mod_countm.so
/etc/httpd/conf.d/mod_countm.conf
/var/countm/fonts/FreeMono.ttf
/var/countm/dbase

RUNTIME FILES
=============
Assuming a default RedHat 8.0 installation:
/var/countm/countm.lock ( a temporary lock file, which should always be removed prior to module initialization)
/var/countm/dbase/* (various db4 database files)
/var/countm/dbase/db.log (the db4 database log file)
/var/countm/countm.dlog (a DEBUG log of parsed configure options)
/var/countm/dbg.dlog (a DEBUG log for the database)
