How to make a "simple" web counter

using Apache on a Macintosh running OS X

1. Motivation

My university stopped hosting web counters for its users, so I wanted to make a very simple web counter for my personal web pages. My web pages are hosted on my desktop computer, a Macintosh G4 running operating system 10.4 (OS X Tiger). Apache is the program that handles web server functions in OS X as well as many other UNIX-based systems. I didn't want to use a freebie counter from a commercial website that adds an advertisement and/or link to a commercial site (there are LOTS of such sites, just do a web search on "free hit counter.") So I set out to make my own web counters. I know almost nothing about UNIX, Apache, Perl scripts, etc. but I figured this function is so simple and so common it should be easy, right? Just do a web search and you'll quickly find everything you need to know in one page, right? WRONG. This turned out to be a remarkably frustrating project, but one somewhat "simple" to duplicate if you have all the required information in one place. Hence this document intended to help others spend less time than I did to do the equivalent task. I am sure there are even easier ways to do some of these functions, but this is what I found that works. If you find this helpful and want to sing my praises, or have constructive suggestions, please feel free to email me at ronney@usc.edu. In particular, if there are easier ways to accomplish the same thing, please let me know. I'm a lot less interested in hearing about ways to add new features. If you want to criticize what I've done and complain about how it messed up your computer, use this address: BillGates@microsoft.com.

While these instructions are written for Mac OS X, most or all if it will apply to any Apache server. The only thing that might be different for other systems is the directory pathways to get to the files of interest.

2. Disclaimer

FIRST AND FOREMOST, YOU USE THESE INSTRUCTIONS AT YOUR OWN RISK. IT WORKED FOR ME BUT THERE IS NO GUARANTEE THAT EVEN IF YOU FOLLOW THESE DIRECTIONS EXACTLY YOU WON'T MESS UP YOUR COMPUTER IN SOME IRREVERSIBLE WAY, OR OPEN YOU UP TO ATTACKS FROM HACKERS. YOU ARE WARNED!

3. Creating and saving the counter script

3.1 The Perl script

First you need a Perl script that actually computes the count, updates the counter file, and spits the output to your web page. If you don't know what a Perl script is, then we have something in common. But one that worked well for me is MultiCount, which you can download for free at http://www.teacherjohn.com/cabrillo/dm160c/exercises/downloads/spring07/mcount.zip. I’ve also posted it on here at http://ronney.usc.edu/mcount.zip. All due credit is hereby acknowledged. What's really nice about this one is that

1. The instructions are few and easy to follow
2. You don't have to set up separate counter files for each page. In fact, you don't have to set up even one counter file. In fact you don't even have to give each page counter a name. MultiCount automatically sets up a new counter file the first time a new page asks for a count. All you have to do is create a folder to hold these counter files and MultiCount does the rest.
3. It spits back the counter information in plain text with no format, which means you can control the format from Word or whatever program you use to make your web pages.

Once you've downloaded the Perl script, mcount.cgi, you need to edit it to configure it for your computer. Open the mcount.cgi file (using Word, TextEdit, whatever) then follow the directions in the comment lines in the file. In particular, you need tell mcount.cgi where to put the counter files. As the instructions clearly state, this is controlled by the "my $DATA_DIR" variable. I set it as follows:

my $DATA_DIR = '/library/webserver/cgi-executables/counters';

You can also set the number format (plain, with commas, hex, Roman numerals (!)), whether to display just the total count or statistics by day, week, month and/or year, and whether or not successive hits from the same visitor should count as multiple hits or not. But this is all so easy to follow from the instructions inside the mcount.cgi file, I need not elaborate upon it here.

By the way, the very first line of the mcount.cgi file is

#!/usr/bin/perl

This tells Apache where to find the Perl script executer. This is in fact the correct location for the Unix system underlying Mac OS X, so you don't need to change this line, but on other systems you might need to change it.

Now save mcount.cgi as a plain text file.  Make sure that there are no hidden additional extensions, which many text editors like to add.  Word and TextEdit keep trying to name the file mcount.cgi.txt then hide the .txt part, which then means it won't work because you need to call the Perl script file by name from your web page.  Save this file in the (visible to the Finder, searchable with Spotlight) folder Library/Webserver/CGI-Executables.  Note that there are many folders on your computer called Library, this is the one from your root directory on your startup disk, i.e. the one that you see when you double click on your hard disk icon.

3.2 Creating a folder to hold the counter files

You need a folder to hold the counter files that mcount.cgi creates. I put it in a sub-folder of the Library/Webserver/CGI-Executables folder, and named it simply counters. This is consistent with the value of the "my $DATA_DIR" variable created above.

3.3 Setting file permissions

Now you're done creating the files, right? No, you have to set the proper access permissions. There must be some way to do this from the Finder, but I couldn't figure it out. So here's what worked:

• Open Terminal in the Applications/Utilities folder
• Type "cd /////Library/Webserver/CGI-executables"(without the quotes) to get to the folder where you put mcount.cgi and created the sub-folder /counters.
• Type "chmod 755 mcount.cgi" (without the quotes) to set the proper permissions for the Perl script.
• Type "chmod 777 counters" (without the quotes) to set the proper permissions for the folder holding the counter files.
• Quit the Terminal application.

4. Modifying your Apache configuration file to allow scripts to be executed, and to incorporate the results into your web pages

4.1 Finding the Apache configuration file

Here’s the scary part of the project, where you modify a system file. The file that sets Apache's configuration (you might call this a “Preferences” file, although there is no direct access to it from the Mac OS) is named "httpd.conf" located at /private/etc/httpd/httpd.conf. It's a system file, and won't show up in a normal finder window no matter how you navigate through it. As far as I can tell, there are 3 modifications that need to be made to httpd.conf for the counter to work (2 essential, 1 very helpful). To find the httpd.conf file:

• From the Finder, type cmd-shift-g and in the dialog window that opens, type (without the quotes) "/private/etc/httpd/". Double-click on the file "httpd.conf".

• Finder will ask you what application to use to open this file, navigate to your preferred text editor.

4.2 Modification #1 (essential)

About 1/3 of the way down the file (you can use the search function to find this spot more easily), you'll find a directive for the folder /Library/Webserver/Documents that looks like

Options Indexes FollowSymLinks MultiViews

Add the word "Includes" to this list of options, i.e.

Options Includes Indexes FollowSymLinks MultiViews

This enables "Server Side Includes" or SSI, whatever that means.

4.3 Modification #2 (helpful)

About 1/2 of the way down the file, you'll find a directive like

<IfModule mod_dir.c>

DirectoryIndex index.html

</IfModule>

This sets the name(s) of the default web page(s) Apache will look for in a folder if a particular file is not specified, e.g. if you just type in http://ronney.usc.edu in your browser URL window. Usually the default page is index.html, but in this case we need to look first to see if there is a page with dynamic content, which apparently must have the extension .shtml, not just plain .html. Not to worry, just change the middle line to

DirectoryIndex index.shtml index.html

and Apache will look first for index.shtml, then if this file is not present, it will look for index.html as before.

4.4 Modification #3 (essential)

About 4/5 of the way down the file, you'll find a directive that effectively tells Apache to include the output of the Perl script in the page that it sends to the computer visiting your website. It's normally commented out:

#AddType text/html .shtml

#AddHandler server-parsed .shtml

All you have to do is remove the "#" characters to make these directives active:

AddType text/html .shtml

AddHandler server-parsed .shtml

(Note; this part drove me nuts. Without the AddType and AddHandler directives, I could access the counter directly and it worked fine, i.e. I go to http://ronney.usc.edu/cgi-bin/mcount.cgi and I get a proper count displayed on my browser, but when I tried to incorporate the counter into a web page, say index.shtml, and load the web page http://ronney.usc.edu/index.shtml, nothing happens where the counter was inserted.)

Note that this means you'll have to name all of the files that use the counter with the extension .shtml, not just plain .html.

4.5 Saving the file

You can't save this system file httpd.conf in a way that overwrites the existing one. So save it to the desktop, again as a text only file, and again watch out for text editors trying to add a hidden .txt extension. Then drag the file from the desktop to the /private/etc/httpd/ folder. Finder will ask you for your administrator password, and will ask you to confirm you want to overwrite the existing file. Note that there is a httpd.conf.default file you can use to reinstate the default configuration if you mess up the httpd.conf file.

You need to restart your computer before these changes take effect. (There is a way to restart Apache without restarting the whole operating system, see http://httpd.apache.org/docs/stopping.html, but it seems easier just to restart everything.)

5. Adding the counter to your web pages

Now that the heavy lifting is done, how do you tell your web pages to display the counter? Wherever you want the counter to appear, add the html directive

<!--#exec cgi="/cgi-bin/mcount.cgi" -->

How you incorporate such directives into a page depends on what program you're using to generate the page. If you're using Word, first note that you can't just put the above directive into your web page at the desired location, even when you're in the Online Layout view. If you do, when you load the web page from a web browser, you'll just see <!--#exec cgi="/cgi-bin/mcount.cgi" -->, not the output of a counter. You need to put the counter directive into the html source code itself. Word doesn't seem to have a means to add html code directly into a document, but you can do it in a somewhat indirect way. Here's how:

• Create your web page in the usual way. You might want to put something like "ABC XYZ" where you want the counter to go, e.g. "You are visitor number ABC XYZ since this page was created." Save the file using the "save as web page" option. Remember to use the .shtml extension.
• From the pull-down menus, select View/HTML Source
• Weed through the pages of weirdness that html source code is to find the place where you want the counter to go. This is a lot easier if you put "ABC XYZ" as a placeholder so you can search for it.
• Add the above exec cgi directive. Special note: When you type the "-->", Word likes to convert this into a single right-pointing arrow character which won't work! If you type "->" then backspace and add an extra "-", Word won't do the conversion and you'll have your desired "-->".
• Click on the "Exit HTML Source" button (if you don't see it, you can find the command in the View menu.) You won't see the counter information in the document, but it's there and will display when someone loads your web page from their web browser.
• If desired, change the color, font, size, etc. of the line containing the counter. This can be a bit tricky since you can't see the counter. But if you put the counter directive between ABC and XYZ, set the formatting of ABC XYZ the way you want the counter to appear, then delete the ABC and XYZ characters, you'll have your desired formatting.
• Save the file again, making sure you still are using the .shtml extension.
• Put the file in your Library/WebServer/Documents folder or the appropriate sub-folder.

AND THAT'S ALL THERE IS TO IT!!!

You are patient visitor number 50905 to this page.

(Yes this counter was created using the method just described!)