This page is a part of WWWstats.

WWWstats documentation

Version: 1.55
Author: Lars Marius Garshol - larsga@ifi.uio.no.
Last release: 13.May.98
[Main page] [Installation] [Non-obvious features] [Log file format] [FAQs] [config.pl docs]

Some Frequently Asked Questions

Do I need SSI?

No, you don't need SSI at all. WWWstats does not use SSI to generate the log file, instead, it reads the log file generated by the server itself. (If you can't read the server log you can just use the included make_log.pl CGI script instead. This does not require SSI either.)

Where is the log file?

That depends on the server configuration. (WWWstats can generate its own, but it's not recommended to do so.) Most installations will have the log files in a subdirectory somewhere below the directory where the server itself is installed. The only person who really knows is the server administrator.

wwwbrowser.pl shows no browsers at all, what's wrong?

If all the other reports work OK, this probably means that your server uses NCSA Common Log Format, which does not include the browser information. (Check the log file. If the last field has a lot of stuff like "Mozilla/x.x (blablabla)" in it then you have the right format, if not, you don't.)

The solution is to either reconfigure your server to add this information, or wait for version 1.60, which will probably read the browser log. (Some servers have a separate browser log.)

wwwrefer.pl shows no referrals at all, why?

If you're using the make_log.pl script the problem is that this script does not include the information in its log, simply because the information is not available.

If you don't use make_log.pl the answer is the same as for the wwwbrowser.pl report. The NCSA CLF format does not include referrer information either. See above for suggestions on what to do.

Why do the "Accesses by domain" and "Accesses by host" only show IP-adresses?

Your server has probably been configured not to look up DNS host names. The solution is to either make it do so, or to configure the scripts to do DNS lookup for you. (There's a setting in the config.pl file.)

Why do I get "Can't locate Socket.pm ..."-errors?

The DNS lookup feature uses the Perl Socket module, and this error means that the Perl interpreter can't find the Socket module. This may be because it's not installed, the Perl interpreter isn't properly set up or because you're using a Perl interpreter that does not support that module. Try looking into this, and if you can't figure it out, send me an email about it.

What are these wwwstats.dbm.*-files?

If you use DNS lookup and set the DNSFile option to 1 the script will store the DNS lookup information in these two files, so that it doesn't have to do DNS lookups for those addresses next time. This speeds up the script after the first runs.

If the files annoy you, you can just set DNSFile to 0 and delete them and they won't reappear. You can delete these files whenever you want, without causing problems for the scripts. (Well, it's probably best to not delete them while the scripts are running. :)

Why does Perl say "you need build xxx, BEGIN failed"?

If you get an error message that looks like this from running wwwstats.pl:

This is build 307 of Perl and the extension requires build 312
BEGIN failed--compilation aborted at wwwstats.pl line 22.

the problem is caused by the DNSLookup feature. You can either turn this off or download a newer version of Perl.

How to install WWWstats

The first step is to download the scripts and unzip the WWWstats.zip file. Then, edit the Config.pl file to suit your needs. (Instructions are in the source code.) After that, things get system-specific, but I'll try to cover the most important points anyway.

These are CGI scripts, so you'll need to tell the server somehow that they're supposed to be executed and not just downloaded. Most servers require you to either put the scripts in a /cgi-bin/ directory or to give them file names ending in cgi. (This is usually configurable.) Ask your server administrator, or look at other scripts on the same server.

If your server is a UNIX server there is some extra points to be aware of. The first line of all the scripts with names like www*.pl looks like this "#!/usr/bin/perl". This has to be changed to point to the Perl interpreter on your server. The command "which perl" will tell you where it is. There is a real gotcha at this point. Some systems won't find the Perl interpreter if there is a ^M (carriage return) at the end of the #! line. So check for this and remove it if it's there.

Also, you'll need to make your scripts executable by setting the permissions to "-rwxr-xr-x", which can be done with the command "chmod 755 www*.pl".

One problem that's been reported to me is that many UNIX sites have two Perl installations, one for Perl 4 and another for Perl5. So if you can't make the scripts work, try checking the Perl version you're using. ("perl -v" does that.) If it's Perl 4 you can try to find Perl 5 with "locate perl5". If that doesn't work you'll have to talk to the administrator about it.

If you still have problems, contact your server administrator. If you are the server administrator, contact me. :)

Generating the log

If you don't have access to the server logs you can use the make_log.pl script to generate the log for you. To do that you must edit it and insert the correct log file location near the top of the file as well as the correct URL to the log image. (The log image is a tiny transparent GIF.) You must then insert an IMG element in all your pages that refers to the log image.

The script is not able to generate a complete log, so some fields will simply be set to nothing:

This script was donated to the package by Ian Johnston.

Non-obvious features

The package has a couple of features that may not be immediately intuitive, so I'm listing them here. Any comments on this documentation would be most welcome. I'd also like to know if you think these features are hard to understand or use.

Customizing the looks of reports

You can do this without changing the Perl source at all, by linking all reports to a CSS style sheet. Use the $StyleURL in Config.pl to do this. The value will be used for the link to the style sheet with no changes at all. In other words: $StyleURL should be set to the URL you would have written if you wrote the report page by hand.

Taking care of changed URLs and aliases

If you've moved a page it will be reported by WWWstats as two different pages, as WWWstats has no way of knowing that the pages are really one and the same. You can handle this by setting up the %Aliases hash to map from old URLs to new URLs. %Aliases=("oldurl","newurl"); means that all hits to "oldurl" will be reported as if they had really hit "newurl".

Finding out what the "Unknown browsers" are in wwwbrowser.pl

I've added the script uaunknown.pl to the package in order to make it possible to find out which browsers the scripts don't recognize. If you get many hits from "Unknown browser" you can run this script to see who they are, and then add them to the lists in shared.pl manually.

QUERY_STRING: Options not in Config.pl

When you run one of these scripts as CGI scripts, everything you type after "?" is going to be sent to the script as a so-called QUERY_STRING. The script reads this string and uses it to set some options that can't be set from Config.pl.

The string has the format "variable=value&variable=value&variable=value...etc" and the following variables are recognized:

restrictto
This is the exact same thing as the $RestrictTo value of Config.pl. If this is set, only URLs that match this regexp will counted in the stats. If it's not set, it mathces all URLs (ie: has no effect).
config
This can be used if you want the script to use a config file other than Config.pl. If it is not set the default value is "Config.pl".
month (wwwmonth.pl only)
The month wwwmonth.pl is to generate a report for. (Defaults to the current month.)
year (wwwmonth.pl only)
The month wwwmonth.pl is to generate a report for. (Defaults to the current month.)

If the scripts are redirected to file, these options are still available in the same way. See the section on batch mode below.

Batch mode

You no longer have to run WWWstats as CGI scripts, which can be fairly slow. Instead, you can run the scripts from the command line, redirecting the output to file. If you do this you can use the first command line parameter to set the QUERY_STRING you would have used if it were a CGI script. (Ie: write what you would have put after the ? in the script URL as the first command line parameter.) All options available to the CGI scripts are available to the scripts in redirect mode as well.

An example command line with no options set would be: "perl wwwstats.pl > wwwstats.html". This generates the main report and saves it in the wwwstats.html file.

The best way to use this is to make a batch file (DOS .bat or UNIX shell script) that runs all the scripts with the options you want, redirecting them to the files you want. If your log file is compressed you can still read it by having the script first unzip it and then zip it up again after the scripts are done.

Here's a sample script:

gunzip /hom/larsga/wwwlog.gz
rm www*.html
perl wwwstats.pl > wwwstats.html
perl wwwmonth.pl > wwwmonth.html
perl wwwweek.pl > wwwweek.html
perl wwwyear.pl > wwwyear.html
perl wwwbrowser.pl > wwwbrowser.html
chmod 644 www*.html
gzip /hom/larsga/wwwlog

This means that if you are under UNIX, you can set up a cron job to run the scripts as often as you'd like. For users with large log files, this is definitely recommended.

Log file format

The programs expect the log files to be in NCSA extended/combined log format. However, only the browser report requires this and the rest of the scripts only expect Common Log Format, which is what most servers use. (Most servers can be set up to use the NCSA e/c log format. The Apache site has info on how to do it with Apache.)


13.May.98 22:12, Lars Marius Garshol, larsga@ifi.uio.no. A part of WWWstats.