W3Olista Installation

The program must be configured by editing its Makefile, where all major settings are defined. You must edit the Makefile in order to set the program up correctly.

First Step: Editing the Makefile

Section One: Required Settings

CC

Your C compiler. It must be Ansi-compliant (most important, it must accept function prototypes); this excludes some standard Sun compilers. The program won't compile with K&R compilers, so get GCC instead.

FLAGS

Any flags you want to pass to the compiler, like '-O' for optimization. If you are on a HP/UX machine and only have the standard C compiler that came with the system, you must also add '-Aa' to switch it to Ansi.

LOGDIR

The directory where your logfile(s) reside. Must be given without a trailing slash. You can also define multiple directories by separating them with a semicolon ';' (without any spaces in between). The program will then read all logfiles from all directories.

LOGFILE

A file pattern for your logfiles, using formatting directives similar to the C function strftime(). Read the appendix Logfile Pattern for a complete description of this matter. You can give multiple file patterns by separating them with a semicolon ';' (without any spaces in between). You only must make sure that these logs don't overlap (not in the sense of time, but in the sense of data).

GMT

This one is also a very sensible setting, especially if you use daily logfiles. It selects whether dates and times should be calculated in local time (exactly the way they are in the logfile) or if they should be corrected back to Greenwich Mean Time (GMT). If you have daily logfiles, then your choice is determined by the logs: If each logfile begins at midnight (00:00:00) and runs through to midnight (23:59:59), then you must choose local time. If the log has an offset to midnight (on our site, it runs from 02:00:00 to 01:59:00, since we are GMT+0200), you must choose GMT.
To choose GMT, leave this line as it is; to choose local time, uncomment the line (put a hash sign '#' in front of it).
Notes: The GMT setting assumes that you have correctly set the TZ environment variable in /etc/profile to reflect your geographical location and your daylight saving policy. See the manual page of environ. If your system doesn't know about timezones, read on.
If your logs have an offset, but not the correct offset to GMT (or if you can't get timezones to work), then you are in trouble, and must reorganize the logfiles with the splitlog utility.
Be aware that this setting doen't have anything to do with the CERN server's LogTime directive, and may be the reverse of that setting. Because if the server writes dates in local time, then W3Olista must correct this time back to GMT.

CAT, ZCAT, GZCAT

These variables must be set to programs that simply read a file and output its contents. CAT must work for plain text files, ZCAT for compressed files with the '.Z' file extension, and GZCAT for files that were compressed with GNU gzip ('.gz' extension). They are used solely for reading logfiles, so if you don't use compressed logs, you need not define the latter two and can comment them out. If any program does not reside in /bin or /usr/bin, you must give its full path name.

Section Two: Recommended Settings

WELCOME

If your server gets a HTTP request upon a directory, it usually returns a well-defined file from within that directory. The standard setting for the CERN server is "welcome.html", for the NCSA server, it's "index.html".
For CERN servers, this is defined with the Welcome directive.

INHOST, EXHOST, INFILE, EXFILE

Here you can define default settings for hosts to include, hosts to exclude, files to include and files to exclude, respectively. They automatically show up in the query form, but apart from that, they're utterly insignificant.

Section Three: Advanced Configuration

BAROFFSET, BARLENGTH

These are numerical values for the offset and the length of the bar graphics that are printed in some places. They should be chosen to show a good level of detail (a length of 2 won't) while still fitting on the screen. The default ones with an offset of 14 and a length of 30 can be used with Mosaic, and will also work with 80-column lynx, but if you use miniature fonts like in Netscape, you can increase the length.

SHMONITOR

There is a 'monitor' tool that comes with this package. It uses shared memory to monitor the progress of W3Olista as it prepares a report. If you want to use the monitor, uncomment this setting. The decimal number is the shared memory ID to use. If the default of 1995 is regularly on use on your system (check with ipcs), change it to any other value. The shared memory monitoring requires System V, and may not compile everywhere. If it doesn't compile, simply comment it out.

RESOLVEADDR

Uncommenting this line enables support for automatic resolution of numerical addresses found in the logs. This setting only compiles the support; you must still explicitely enable resolution with W3Olista's ResolveAddr command. If this setting causes compilation problems, comment it out.

EGREP

This was an attempt of mine to use grep for filtering of the logfiles. I hoped that grep would be significantly faster than my own simple code, but it wasnt. If you believe that your system's grep is faster, then uncomment this line and set the value to your system's extended regular expression grep. I have not verified too hard if this portion of code works, so handle with care.

DEBUG

was used in addition to the monitor during the debugging phase of the program. Uncommenting this line will cause in some status messages written to standard error. If you uncomment this line, the program cannot be run as CGI.

Compiling the Program

make

Installing the Program

Installation for Command Line usage

Installation for CGI usage

• If you want to run W3Olista as a CGI program, you must copy it to the directory where your CGI programs reside. If you don't have such a directory yet, create it. Carefully read the documentation of your Web server on how to set up a CGI directory. For the CERN server, this is done with the Exec redirection rule. If you don't want everyone to be able to access the program (because of the time reporting consumes), set up protection for the program. Again, read your server's documentation for protecting scripts (the Protect rule for the CERN server).
• You may also want to copy the program to some global directory, where it can be offline-accessed by all users.
• Give the program appropriate access permissions. As a CGI program, it is probably not called as root, so it will usually need a permission of r-x--x--x (511). It does not need to be setuid.
• Make sure the logfiles are readable by the user who executes the program (the user as which the Web server runs).
• Depending on the power of your server host, you may have to increase your Web Server's script timeout value. There is usually a timeout of 300 seconds; extensive online reports on dozens of megabytes of log data can easily need more time. See your server's documentation on how to increase the timeout (CERN server: the ScriptTimeOut directive). I use a timeout value of 20 minutes here.

Starting the CGI Program