NOTE: This page was converted to HTML rather badly by Notetab lite, so if something doesn't look right, check the text version of this file.
HTMLfixIT.com Statistical Counter Installation file.
----------------------------------------------------
- Summary.
- Benefits/Features.
- Possible downsides.
- Requirements
- File and directory structure.
- Installation instructions.
- Upgrading from older stats counters.
- Notes for windows servers.
- Notes for mod_perl servers
- The script doesn't work, what do I do.
- To Do.
Summary
-------
The HTMLfixIT.com stats counter is a different sort of counter.
If you want one of those ugly numeric counters that display
your sites popularity (or lack thereof) on the site somewhere,
you need to be looking elsewhere.
(try http://nms-cgi.sourceforge.net/ for a good secure one.)
I will add php/shtml includes at some stage for those that really
want to display the page count, but that was not the main purpose
of this script.
The purpose of this counter is to be totally hidden and collect
data about your users that might be of assistance with site development.
The information collected about your visitors can be viewed by you in an administative web page that is password protected.
The data collected is as follows:
1. Unique hits (per 24 hour or other pre-defined period)
2. Total hits, minus any from address's you have set to be ignored.
3. All hits, including ignored hits and repeat hits.
The latest versions store the data in two ways:
1. Since the moment you started the counter.
2. Since the last rollover (monthly rollover recommended.)
Statistical data collected:
4. Browser types, and popularity.
5. Visitor Screen resolution and popularity.
6. Operating System type and popularity.
7. Referer information, how visitors found your sites.
(eg. Search engines and search terms, links from other sites etc.)
------------------------------------------------------------------
Benefits/Features of this script over "other counters".
-------------------------------------------------------
- No SSI (Server Side Includes) required, this script runs as an invisible
preloaded image using very basic Javascript.
- Password protected admin screen detailing the statistics collected.
- Counts unique hits, all hits and minus ignored hits. not just hits from you
marvelling over your own page. :-)
- Collects data from the visitor to your site that other SSI and image scripts
Are unable to access. (Screen Resolution is a good example.)
- Is sometimes able to collect referer information even though a firewall like zonealarm might
by blocking enviroment variables leaving the clients PC.
- Script was written with Taint mode, strictures, warnings and diagnostics turned
on. with no errors. A good bit of insurance for security in CGI scripts.
- The JavaScript used to call the script is so old and tested, that every single
JS capable browser I tested worked just fine with it.
Browsers tested so far as working.
- IE 4.x, 5.x, 6.x on Win and Mac.
- Netscape 4.x 6.x, 7.x on Win, Linux, Mac etc.
- Mozilla (all mozilla versions on Win, Linux and Mac)
- Opera 6.x, 7.x all platforms(and I am confident Opera 5 will work also.)
- Safari, (new Apple browser, OSX).
- Galeon and Konqueror on linux.
- WebTV
The Possible downsides.
-----------------------
- Will not register hits from text based browsers or any other browsers
with JavaScript disabled or turned off.
(generally less then half a percent of browsers or less.)
- One counter installed per site. This counter is designed to work
for only one site at a time. The reasons for this are many, but the main one
is that nowdays browsers block images from sites with different address's
to the main website, so there is really no point having one counter for alot
of sites.
Requirements
------------
- Perl support, (5.05 and above should be fine.)
- A cgi-bin or similiar on your web host.
- The CGI module, (which is part of all modern Perl Installations.)
- Some patience.
- A decent text editor like TextPad or NoteTab.
- FTP client (smartftp.com is a good freebie).
- Coffee (at least enough for one cup, possibly two).
--------------------------------------------------------------------
File and directory structure.
-----------------------------
The zip or tar file contains files and directories in this layout:
|---- archive (empty directory)
|---- counter---|
| (directory) |---- ips (empty directory)
| |
| |---- stats.txt (text file)
| |
| |---- counter.txt (text file)
stats-counter | |
| |---- ip_ignore.txt (text file)
| |
| |---- spacer.gif (tiny image file)
| |
| |---- .htaccess (file that stops this directory
| | from being browsed directly.)
| |
| |---- overall.txt (text file)
|
| |---- fixit-counter.pl (main script file)
|---- fixit-counter---|
(directory) |---- stats.pl (script initialisation file.)
|
|---- spacer.gif (another copy of the image file
| in case you missed the first one.)
|
|---- htmlfixit-lib.pl (script library file.)
|
|---- counter_config.pl (script configuration file.)
If your extracted files and directories don't look like this, you need to
change/move/add whatever is missing.
At worst you might have to create the archive and ips directories which winzip sometimes
loses because winzip doesn't like extracting empty directories. (This shouldn't be necessary
anymore because we include temp files in the empty directories so winzip extracts them. but you
will need to delete the temp files (called "delete_me") from the 'ips' and 'archive' directories
before uploading your new counter.)
--------------------------------------------------------------------
Installation Instructions.
--------------------------
Step 1.
Open your site's main page, be it index.html, default.html or whatever.
You can put the code in all of your site's pages if you like.
Insert the JavaScript at the very bottom of your html (generally
just before the </body> tag is best).
Be sure that the two config settings in the JavaScript match your
particular setup.
The two config settings required are pretty simple.
1. Is the path (url) to your copy of the stats counter.
2. Is the path (url) to your copy of the spacer.gif file provided in the script download.
NOTE: With htmlfixit.com and other sites like it, we use php include files to have the same
header and footer in every page. In cases like this, its a good idea to just put the below
Javascript into the footer include to have it automatically appear in all the pages of your site.
##### GRAB EVERYTHING BELOW THIS LINE #####
<!--
////////////////////////////////////////
// HTMLfixIT.com STATS Counter. //
// All rights reserved. //
//////////////////////////////////////// //-->
<script type='text/javascript'>
<!--
///////////////////////////////////////
// Start of config settings:
// URL to counter script (change following config variable).
var path_to_counter = '/cgi-bin/fixit-counter/stats.pl';
// URL to spacer.gif
var url_to_spacer_image = 'http://htmlfixit.com/counter/spacer.gif';
// end of config setting, do not change anything below.
///////////////////////////////////////
var res_height = window.screen.height;
// Change following http: part
var str1 = '<a href=\'http://htmlfixit.com\'><img src="' + url_to_spacer_image;
var res_width = window.screen.width;
var res = res_width + 'x' + res_height;
var refer = document.referrer;
var str2 = '" border=\'0\' width=\'1px\' height=\'2px\' name=\'fixitlink\'';
var ref = refer.replace(/&/g,'%26');
ref = ref.replace(/ /g,'%20');
var url = path_to_counter + '?count=yes&res=' + res + '&ref=' + ref;
var str3 = 'alt=\'htmlfixit counter\' title=\'Counter provided by htmlfixit.com\' /></a>';
preloadOn = new Image(1, 1);
preloadOn.src = url;
document.write(str1+str2+str3);
// End of HTMLfixIT.com STATs Counter //
/////////////////////////////////////////
//-->
</script>
##### GRAB EVERYTHING ABOVE THIS LINE #####
Step 2.
Unzip the tar or zip file using winzip (www.winzip.com) or whatever you normally use,
and put the files in it into an empty directory somewhere where you can edit them.
They contain two directories ('counter' and 'fixit-counter') containing all the needed
files and directories.
Step 3.
Fire up your trusty FTP client.
(http://smartftp.com is a very good freebie if you don't already have one.)
Connect to your web host using the settings provided by them and upload the file
called install-tool.pl to your cgi-bin (or where ever you plan to install the counter
script file) be sure to upload in ASCII and not Binary. Once its on your server
right click on the remote file in your FTP client and use whatever method is provide by your
FTP client to make this file executable, (chmod 755).
Then point your browser at that script like so:
http://htmlfixit.com/cgi-bin/install-tool.pl
(edit the address to suit of course :-)
Make a note of all the settings suggestions it gives you, you will need them later.
Once you have all the settings the script provided, delete the script, we don't want to be handing
that info out to just anybody.
Inside the "counter" directory that was in the zip/tar file are two other directories and several
files, right now we are interested in the directores, 'ips' and 'archives' inside both are some temp
files I added so that winzip would recreate the directores for you.
(Winzip doesn't extract empty directories.) since we don't need those files anymore, its important that
you delete these temporary files (both are called "delete_me" for your convenience. :-)
Now upload both the the html page/pages you added the Javascript to in Step 1, and the whole 'counter'
directory with all the files and directores in it.
Be sure you upload everything except the space.gif in ASCII, NOT binary, (check the settings of your FTP client for
this.) Upload both of the directorys -- archive and ips -- and the html file/files into your web root. (where all your other
web pages are). There is an image file called spacer.gif in there as well. Keep that in mind for
when you edit the config file later on (the script will need to know where to find at least one of
these little image files).
Right click on the counter directory in your FTP client and select "properties" or "permissions"
give it full permissions to owner, group and others. (777) (ditto for the all directories
inside that one) and full write permissions to all the files contained within the directories (666),
accept for the .htaccess file).
NOTE, It's always a good idea to use the lowest permissions you can and still have the script work.
the reason I have chosen fairly open permissions here is because there are many different ways to
configure a web server and the best permissions you can set are determined by how your web server
was configured, so rather then risk "permission denied" errors and the testing that goes along with it,
I have suggested the permissions that will work in the vast majority of cases. If your server runs
as your own user name, then you can tighten your permissions down considerably more then this.
Speak to your host if you want to look into that. Since we are not keeping critical secrets in these
files and directories, and the script really only uses them in safe ways, there is no real danger here.
Step 4.
Using a text editor like Textpad, (textpad.com) or Notetab Lite (both have free or trial versions
you can use) (Windows Notepad will introduce Windows return characters to the file
which Unix/Linux servers will not like, so use an editor that will preserve the
files standard Unix format which both windows and unix based machines will handle):
Open the file 'counter_config.pl' (its in the 'fixit-counter' directory) and fill out the various parameters
mentioned therein. All the configuration options are commented well and don't require explanation from me here.
I will make a point or two however:
- If the server you are installing this on is a windows machine
The paths should be in this format:
my $something = 'C:/Inetpub/webroot/scripts/something';
(Notice that the slashes are reverse what they would be in normal windows usage.)
- This is where the results printed by the install-tool.pl script you uploaded in Step 3 will come in handy,
as it details what it think the settings should be in this config file.
Step 5.
In your FTP client, browse to your cgi-bin directory, (If you don't seem to have one, call your
hosting provider and ask them why not.) and upload the 'fixit-counter' directory containing all the
files with the .pl extension, into your cgi-bin. Right click on the files in your FTP client and select
"properties" or "permissions" and set it to (755)(read/write/execute for owner, and read/execute for
both group and others.)
Step 6.
You're done! Now to test it.
Open your web browser and enter this url (edited to suit your situation.):
http://mydomain.com/cgi-bin/fixit-counter/stats.pl?login=yes
If all went well, you should be looking at a login screen, entering your password and username
(you would have set the username and password when you filled in the config file.)
will take you to the main statistics screen. A cookie is set at this point so you can refresh the screen
and not have to login again. (if you get a "server 500" or other error, see the section "The script
doesn't work" below.)
Open another browser window and go to your web sites homepage, and then go back to the first browser window
and click refresh count. you should see the hit has been counted and the statistics for your hit showing up.
(you should bookmark that address so you don't have to type it in again).
If all that proceeded as stated, congratulations, you have installed the counter. well done.
If it doesn't work as stated here, see the section below entitled: "The script doesn't work, what do I do."
Upgrading from older stats counters.
------------------------------------
If you have one of the earlier versions of the stats counter, like 0.7x or 0.9x, then you don't really have
an upgrade path, the new version was written with easy upgrading as one of the goals, so its not particularly
compatible with the old ones.
Having said that, the files that store the data are much the same, counter.txt, stats.txt the ips and archive
directory are all the same as before, but there is a new text file, overall.txt that stores your counts since
you installed the counter and doesn't roll over like the other count/stat files.
You could conceivably use your current stats.txt and counter.txt files with the new counter, the format is the same
however you'd have to edit overall.txt otherwise it would be reporting an overall count thats actually less then the
monthly count.
I personally suggest you just start from scratch so everything syncs up.
Even the Javascript that goes in the web pages is different from the old version.
It does some more escaping of bad chars and now actually uses the image it preloads.
In future, upgrading should be as simple as overwriting the old fixit-counter.pl file with the new one, no reconfiguration
etc necessary, which is why this change was made.
The script doesn't work, what do I do.
--------------------------------------
- Check your file and directory permissions. probably the most common cause of errors.
- Be sure you uploaded the files in ASCII there is no way to get files uploaded as binary to work, you have to
start again.
- Be sure you didn't edit the files in windows notepad thereby putting windows control characters
all through the perl scripts. This will ALWAYS give an error on unix systems.
- Make sure that the parameters you entered in the config section are exactly correct, often just one
character out of place can ruin the whole experiance. Also, the configuration variables in the config
file are all in this format: my $variable = 'some value'; do not change that format in any way, including
the '' and the ; at the end.
- Check the web servers error log. If you can't find it in your host home directory, ask your service provider
how you can access it.
- Ask a question on the htmlfixit.com forum, being as detailed as possible.
- Pop into the htmlfixit.com chatroom and ask whomever is in there about your problem.
- Check this page: http://www.perl.org/troubleshooting_CGI.html out, its from the guys that brought
you perl in the first place.
- Search google.com for "my CGI script won't run" or "server 500 error", you'll get alot of info.
Notes for Windows servers.
------------------------
- All file paths for configuration should be in windows format with forward slashes instead
of back slashes.
For example: my $counterfiledir= 'c:/Inetpub/www/counter/downloadcounter/';
- Near the top of fixit-counter.pl, you will find the following two lines:
my $path_to_lib = '.';
my $path_to_config = '.';
These will need to be edited to match the path to the actual directory containing the .pl files
eg:
my $path_to_lib = 'c:/Inetpub/Scripts/fixit-counter';
my $path_to_config = 'c:/Inetpub/Scripts/fixit-counter';
Windows does not handle relative directories very well, so they must be absolute.
- Taint mode most be turned off. In the file stats.pl first line, change the following:
change:
#!/usr/bin/perl -Tw
to:
#!/usr/bin/perl -w
- Temp directory must be set. in the counter_config.pl file, near the bottom is the following
line:
my $tmp_dir = '/tmp';
Windows will not understand that path, it must be changed to: my $tmp_dir = 'c:/temp'; or whatever
directory you can store temp session files in. if you don't know of one, just create a directory
somewhere that your script can have write access to. (but don't put it in the www directory.)
Try c:/temp first before you try anything else.
For example:
my $tmp_dir = 'c:/somedir/temp';
Be sure the user the web server runs as has read/write access to the directory.
Give the directory full write/write/execute permissions to ensure the web server can write to it.
again, do NOT put this directory in your web root or cgi-bin, as it would not be very safe.
- If you are silly enough to want to run a webserver on win95/98/98SE/ME, you will have to modify the
script somewhat, open all the .pl files and put a hash # in front of any line starting with the word:
flock
Win9x has no file locking method in place and you will get errors when perl tries to lock a file.
Notes for mod_perl servers.
---------------------------
- Cookies, I have not been able to test the cookie code of the counter in mod_perl due to some server
issues at my end, but it should work fine under apache::registry.
- As with windows servers, its a good idea to edit the $path_to_lib and $path_to_config variables
in fixit-counter.pl to absolute paths, and the htmlfixit-lib.pl and counter_config.pl files need not
actually be in the same directory as stats.pl.
- Taint mode must be turned off. In the file stats.pl first line, change the following:
change:
#!/usr/bin/perl -Tw
to:
#!/usr/bin/perl -w
To Do
-----
- Others in the browser category is not functional, but not really important anyway.
- Regex that determines statistics to be externalised so it can be updated seperately from
the rest of the script when new browsers are released.
- File operations need to be memory optimised, currently all stats pulled into memory and passed out
of the subs.. this is very wasteful and needs to be changed at some stage.
- Admin console displays to the left on some Mac browsers, instead of centered, not serious but should
be consistant as possible across platforms.
Bugs, Problem or anything else I should be concerned about can be emailed to:
frank at gshop.com.au
(replace the 'at' for @.)