So, You Want Your Own Counter CGI, Huh?

This is the counter   
    you will receive here.

Use these to jump around or read it all…

     Please note that this tutorial uses UNIX commands. That means it will not work on Windows NT server systems…sorry.

     Everybody wants a counter on his or her page. I can understand. I love the look of a counter proclaiming to all that my page is cool enough for a couple hundred thousand to roll through. The problem is that counters are not all that easy to come by if you don’t own the CGI. Well, I do own the CGI and now, I’m going to give it to you. If you follow this tutorial straightaway, you’ll get a counter just like the one above counting on your page.

     But be careful! There are many not-so-nice people out there who will attach to your counter without your knowing it, or without asking your permission. Later I’ll tell you how to lock those people out of this counter. I should say that this tutorial does get tricky. CGIs are tough sometimes. If you simply cannot get this to work or want another way of getting a counter, see So, You Want A Counter, Huh? for some other ideas.

How This Thing Works

     This is a very simple counter CGI. It returns a bitmap image count, like the one above. The process is this:

• The page is requested by a server.
  
• There is a codeword on the page that contacts the CGI.
  
• The CGI checks in a “counts” directory for a file named after that code word.
  
• If the file exists, the CGI adds one to the count in the file and returns the bitmap image of the count.
  
• If the file doesn’t exist, the CGI creates it starting the count at 1.
  

     So, we need to create two things: The cgi-bin (if you don’t already have one) and a directory where this CGI can keep record of all your counts.

You Must Be Able To…

     In order to do this, you must be able to do a few things with your Internet account. You must be able to:

• Gain access through telnet.
  
• Create directories.
  
• Change directory modification.
  

     If you don’t know if you have these permissions, then contact your system tech or just start following along. You’ll be told soon enough if something doesn’t jibe with the server.

     So, here we go…

Telnet (Click for a short tutorial regarding telnet)

     For those of you who don’t know, “Telnet” is another way to attach to your Internet server. Using Telnet you are attaching directly to the server “shell.” This is where you can enter commands that directly affect the UNIX settings.

     When you signed up with your Internet Service Provider (ISP) you should have gotten a telnet program. If not, you still may be in luck. Windows-based computers have telnet programs already installed. In versions 3.x, it’s named “Terminal.” In W95, it’s named “Telnet.” Both can be found in the Accessories section.

     Whatever telnet you are using, they all work the same way. Open the program, choose to connect, and type in your WWW address without the http://.

     You’re good to go. Keep following along…

Making A Directory For The CGI To Use

     First off, you will need to telnet into your server. Upon connecting, you will be asked for your user name and password. Put them in. Usually you will get a few welcome greeting messages and then a prompt of some sort will pop up. I have worked with seven different servers and the prompt has been different on all seven. It should look something like this:

telnet%

     Does that look familiar? If not, don’t worry, you will see the blinking curser where you will enter information.

Your Public HTML Directory

     When you send files over to your server, for them to be seen by the entire Internet community, you send the files to a directory. It has a name. You need to find that name. Most of the time the name is something like “public-html” or “www” or “default.”

     For the sake of demonstration, we’ll say the directory’s name is WWW. That’s the shortest name and thus easiest to write a couple hundred more times. Depending on how your system is set up, you will either be in that directory when you telnet in, or you will be one above it. The smart money is that you are one above it. Type this at the prompt:

telnet% ls

(Please note, I am using “telnet% to represent the prompt. Your prompt may look different)

     Hit return. You will get back a listing (that’s what “ls” means) of everything in that directory. If you see all the names of your HTML documents that Internet viewers can access, then you are already in the WWW directory. If you see the name of your Internet directory (I called it WWW above), then you are one above the directory. This is probably where most of you are. This is where I want you to be, one above your WWW directory.

     You need to get one level above your WWW directory if you’re not already. Do that by typing this at the prompt:

telnet% cd .. (two dots)

     “cd” stands for “change directory.” That’s what you just did. Now put in the “ls” command again and you should see your WWW directory.

Making the CGI Directory

     This may already have been done for you. You should check that first. If when you typed one of the “ls” commands above you saw a cgi-bin, you need not do this.

     Now you will need to create a special directory for your CGIs. No, they cannot sit where all the other files are located. Why will become clear in a moment. I suggest you name the directory you are about to create “cgi-bin” as that is what I am going to call it the rest of the way through this tutorial. Please notice that is a hyphen between the “cgi” and the “bin.” You will make the directory by typing this:

telnet% mkdir cgi-bin

     If you get another prompt and no error messages, you did it. This is the first point at which you may be told you do not have the ability to place a CGI.

     If you’d like to see your work, type this:

telnet% cd ls

You should see your cgi-bin. However, some servers are set up that as soon as you create a new directory, you are then put into it. I had a school server do this once. It’s actually helpful if you want to place files right away. If you do the list command above and see nothing, you’re probably in the directory you just created. Type this:

telnet% cd .. (those two dots again)

…and then this:

telnet% ls

     You should see the new directory “cgi-bin.” Log out of telnet by typing “logout” at the prompt.

Make a Directory For The Counter’s Files

     Follow the same steps as above, but this time, create a directory called “count.” This is where the CGI counts of pages will reside. Again, do an ls. You should see the two new directories, cgi-bin and count sitting before you.

Log out by typing logout at the prompt.

Grab The CGI

     The CGI I am giving you here is the exact CGI I use on my system. The file is in text format. You need to save it to your hard drive as count.pl or count.cgi, depending on what format your server wants. I can’t answer that question. You’ll need to find out from your server’s tech which one is preferred.

Altering the Script for Your Server

     The script is not ready to go as-is. You will need to check a few things first.

• Look at the first line: #!/usr/bin/perl

  
  That is the path to the PERL program in your server. It must be correct for this to work. You see, the CGI will not do most of the work. The PERL program on your server will. This little CGI just sort of “brings” the information to PERL for manipulation. So, find out if this path is correct by asking your server’s tech. If it isn’t, change it. Just be sure to open the CGI in Notepad, Simple Text, or another text editor that does not have margins. Altering the shape of this CGI in any way will stop it form working.

  
  

• Look at the third line down: $counterdir=”/directory/sub/sub/counts

  
  That’s the absolute path to the directory that will contain the counts for the CGI. Remember you made it up above? You called it “count.”
  

The Absolute Path

     This is a tough concept to grasp at first. Let’s say your home page URL has an address of:

     That little squiggly line before “joe” is called a “tilde.” It’s a neat little trick to save space. It says to the computer, “There is one directory on this entire server called ‘joe.’ Find it!” There might be five directories between the server name and “joe” but you’d never know because of the use of the tilde. The actual path to “joe” might be this:

     What is listed above would be the absolute path to “joe.” Get it?

Find the Absolute Path

     You’ll have to log back into telnet.

     Follow the commands outlined above to once again get into the directory that contains your WWW files for all the world to see. Do an ls command. You should see the cgi-bin and count directory sitting there. Now…

1. Open the count directory by typing cd count
   
2. When the prompt comes back up, type pwd and hit Enter.
   
3. What is sitting before you is the Absolute Path of that directory.
   
4. Copy it down and enter it in the CGI.
   

     Log out of telnet.

FTP The CGI

     Whatever method you use for placing files on your server, use it now to transfer the count CGI to the cgi-bin directory. (Do not put the CGI in the count directory. It will not work there.)

     Transfer the file as ASCII. (Yes! I said ascii.)

Turn On The cgi-bin and Count Directory

     We’re getting close. Stay with me here. Log back in with Telnet and get to the directory where you keep your WWW files. You should see the cgi-bin and count directories using an ls command. Now we “turn on” both directories. Basically, what we are doing is setting the file’s modification instructions so the server knows that this directory can be written to, and read from, by other servers. Type this at the prompt:

telnet% chmod a+rx cgi-bin

     If you get no error codes, success. You did it. If you did get an error code, try this instead:

telnet% chmod 775 cgi-bin

     Sometimes that’s allowed but the other isn’t. If neither work, you don’t have the correct permissions. Talk to your server people to see if you can get them.

     Now go ahead and “turn on” the count directory by following the same steps as above, but using “count” instead of “cgi-bin.”

     That done, we need to “turn on” the counter CGI itself. At the prompt type:

telnet% cd cgi-bin (you just opened the directory)

then

telnet% chmod a+rx [cgi name]

     Just put in the name you gave to the CGI. Again, if the a+rx doesn’t work, try 775.

     Log out. We’re ready to count.

Getting A Count On A Page

     Here’s the command you need to place on your page to receive a count:

Here’s What’s Happening

• IMG denotes it’s an image that will be returned.
  
• SRC is the source path. Notice it’s pointing toward the cgi-bin you created, then the CGI inside of the directory. Make sure to put in the exact name you named the CGI. It may differ from what’s above.
  
• ?codeword is the way you denote each different page that receives a count. The code word can be up to 40 characters. Make up a different one for each page.
  

     That’s the general idea. If you have all the paths correct and the permissions turned on correctly, you should receive a count straightaway.

You Shouldn’t Do This, But I’ll Tell You Anyway.

     If you want your count to start at a certain level, like 10,000, you can do that by adding this to the end of the above command:

     Just replace the #### with the number you want to start with. Keep in mind though, that will only work the first time you access the page. If the counter already has a count of 1, then no dice…

     …but you shouldn’t do that anyway. It’s cheating.

Locking Out Others

     You put this counter on your site to count your pages. If someone is nice enough to ask to use the counter CGI, it’s up to you to let him or her or not. But there are some swarthy individuals out there who just muscle right on it. It’s not tough to steal into this one. You just copy the command above and poof! You’re counting. This CGI is not overly advanced, and doesn’t have a lock-out function. You need to do it by hand.

     First, log into the telnet again. Then get to your count directory (where all the counter’s counts are kept) and do an ls to see all the files inside. The files will all be named after the codewords you used. If you see one you didn’t put there, someone is stealing from you. Lock them out. Here’s how:

     For the sake of demonstration, we’ll say there’s a file there named “fred.” It’s not your file so some person is getting free counts from you without asking. Type these commands at the telnet prompt:

• telnet% touch fred.LOCK [hit enter]
  
• telnet% rm fred [hit enter]
  

     The TOUCH command creates the file you write after it. In this case, you created a file named after the bad file with the .LOCK suffix. Then you removed (that’s what rm means) the file “fred.” What you did was switch “fred” for “fred.LOCK.” Now the file fred is locked at zero. It cannot be written to. The person who is stealing from you is locked at zero and cannot come back in. They may change their password. Lock them out again. Soon they’ll get the message.

     I do this once a week for the fun on of it. I kind of feel like Matlock.

Good Luck

     There’s no doubt about it. This is a tough one. But if you get it to work, you’ll be very pleased with your own counter. It works very quickly and it runs right off of your own server. It’s a great upgrade to your site.

Enjoy!