Written by Brian Kolaci (bk@galaxy.net) Feb 15, 1996.

Thanks to the DigitMania page at: http://cervantes.comptons.com/digits/digits.htm.

The latest copy of this file may be found at: http://www.galaxy.net/webcounter.html. Questions may be sent to bk@galaxy.net. The latest version of this software may be found at: ftp://ftp.galaxy.net/pub/bk/webcounter.tar.gz.

This package contains the module code to link in with the web server, the executable to manipulate and display the counter as a GIF, and a perl script to display/manipulate the counter log files.

This code uses the gd1.2 library by Tom Boutell, boutell@boutell.com
The whole gd distribution is enclosed in the subdirectory gd1.2, please see the README file there.

Contents:

• Overview
• Changes
• Apache Module
• Page Counter code
• Counter Logfile display/manipulation script
• Building & Installation
• Still TODO

The counter software counts web pages, not URL's. This means that whether a page was accessed via a direct URL, a redirected URL, or a directory index (index.html), the same counter is used. Because of this, the counter GIF program must have the same DirectoryIndex parameter compiled into it. When a directory is referenced, then it scans the possibilities of files within the directory to find the page counter.

Since the web server itself keeps track of the counts and not the CGI script, there can be no spoofing on the counter. The page itself must be delivered to the client by the web server to be counted. The GIF counter script (to deliver an image as the counter) uses the web server environment variable HTTP_REFERER to figure out which page counter is to be referenced. Some browsers (like AOL and Prodigy) do not set this field yet, therefore the command "url" to be passed to the count program may be set to specify the page URL to report. Note that calling the CGI program "count" does NOT increase the hit count on the page, only accessing the page itself will do that.

For those that use server side includes, the environment variables URL_COUNT and URL_COUNT_RESET are set to the counter value for the current page, and the last time it was reset. Another variable, URL_COUNT_DB, is set to the counter log database file, for use by CGI scripts.

There is a feature to automatically add pages to the counter log when it has never been referenced before. Also, pages may be individually reset on demand.

Two modes of counter logs are available, per server and per directory. This allows indexing files by file system and by server domain or virtual domain. This allows control of a counter file to be maintained for a virtual domain, and in addition, the webmaster for the whole server may have their own copy indexed on the whole filesystem. This means counter logs may be used server wide, within a virtual host, and also within a Directory directive.

Changes

Version 1.1:

• 3-5-96
  Updated the countctl script to be able to set the current count of a page (in case a page or set of pages have moved between servers).
• 3-10-96
  Updated counter to *not* rely on correct SERVER_NAME and SERVER_PORT being set. This is for the case of either an IP address being sent or some other alias instead.

This code allows easy transparent use of web page counters.

Apache Module

The apache source code module mod_cntr.c contains code to be linked in with the apache web server. This file should be installed in the source directory with the web server source.

The only changes you should expect to make would be:

Default counter file type

The default is to use DBM logging rather than File logging. This is because its faster and more efficient.

Default counter files

You may decide to automatically have default counter log files. As is, there are no default files, hence, no counting would be attempted unless specified in the configuration files. The files are relative to the Server Root Directory.

Page Counter code

The program count is an ansi C program that uses the gd library to concatenate GIF files and output a new GIF image that appears to be a counter. It uses a collection of GIF files, each comprising exactly one digit, 0-9. The program accepts an unlimited number of digit types or styles, each style being in a subdirectory named the same name as the type itself. This subdirectory should contain 10 files, named 0.gif, 1.gif, ... 9.gif.

Count is a standalone executable that may be called directly as a CGI program, or called by other CGI programs. It reads values from environment variables to determine where to get the count from, then obtains style modifiers from CGI variables which are parsed from QUERY_STRING (we assume a GET method), then last overridden by any command-line options.

CGI variables may be sent as:

<img src="/cgi-bin/count?type=odb&length=10">

CGI String	Command-line Option	Default	Description
type	-t	default	Name of digit type to use
length	-l	5	Length of digits to use, left side padded with 0's
counter	-c	(from database)	Counter value to use
url	-u	(CGI environment variable HTTP_REFERER)	URL page to count

Counter Logfile display/manipulation script

The script "countctl" is used to control/manipulate/display the contents of a counter log file. This uses the same locking mechanism as the web server module and counter program.

Do NOT edit the file(s) by hand as the file may become corrupt if is being updated by the server at the same time you write it out.

This script allows you to add a URL, delete a URL, reset count/date on a URL, and view a URL or the contents of a file.

Building & Installation

There are essentially 3 items that need to be installed. First, start with the web server.

Compiling the module into the Apache Web server

• In the Apache distribution, edit the file Configuration and add the following line:

   Module cntr_module mod_cntr.o 

• Run Configure
• Run make
• Edit the config file httpd.conf and/or access.conf

Building & Installing the counter CGI program

• Edit the program count.c and customize the following:
  1. Set TYPE_DIR to be the directory where the digit type sub-directories are stored.
  2. Set DEFAULT_TYPE to the default digit type.
  3. Update DigitWidth to a new default digit width, if desired.
  4. Update the array IndexNames with your list of DirectoryIndex values from the httpd.conf file.
• Edit the Makefile to your taste (see comments in the Makefile)
• run make
• copy the executable count to your cgi-bin directory. Suggestion: create a new directory in your server root directory called counter and install it there.

Digits

The digits should be installed where you set TYPE_DIR to point to in the counter CGI program, default is /export/www/digits. Create this directory. Within this directory, create the sub-directories default and one for each digit type. Each sub-directory should contain 10 GIF files, each labeled 0.gif, ... 9.gif.

Counter Control Script

The script countctl may be used to manipulate, reset, add, delete or view the counter logs. Make sure you have perl around. The countctl script is written assuming perl is located in /usr/local/bin/perl. If its in a different place, edit the first line to point to where your perl executable lies. Copy the script to either /usr/local/bin or where you plan to keep your counter log files. The script requires at least one argument, the hash or log filename. Certain options require the URL being processed.

The synopsis is as follows:

countctl [ -cdrv URL ] filename 

    -c     create URL
    -d     delete URL
    -r     reset counter
    -v     view counter (and reset date)

If no option is supplied, it essentially dumps the contents of the file. The output is in no particular order. The format of the output is:

URL     count     reset_date

Still TODO

As this code has been pretty much tested, there are still things that should be added and still more testing... I've only tested the code under Solaris 2.4 and Solaris 2.5. It needs to be tested on other platforms. At any rate, here are a few things I'd like to see in the future:

• Change the storage of the date so it can be dynamically formatted
• Ability to change the time format of the reset date