W3Olista Installation

These are the installation instructions for W3Olista. Since it is a program that is usually installed by site administrators, a certain level of knowledge about your system and your WWW server is required to install the software. For your convenience, this document has some links to the CERN server's documentation (that's what I run here) for further reference.

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

You have to adjust certain settings in the Makefile before compiling it. These settings are divided into three parts: The first part contains required settings that must be set to match your site. Settings in the second part are not vital, yet you should at least take a look at them. The third part contains advanced settings you hopefully don't have to worry about. If the program refuses to compile or run, some of the settings in this last category may help.

Section One: Required Settings

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.
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.
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.
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).
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.
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

The settings in this section aren't vital, so if you don't know what to do with them, forget 'em.
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.
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

You may choose to not even read about the settings here, but if the program then fails to compile, you might want to try some changes here; especially the SHMONITOR and RESOLVEADDR settings might not compile on some systems.
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.
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.
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.
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.
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

After editing the Makefile, simply entering
should compile the program and create two executables, olista and monitor (if you didn't compile with shared memory monitoring support, the latter will be pretty empty). If it didn't compile, make sure that your system meets the necessary requirements, and that your settings in the Makefile are correct. If you are sure it's not your fault, send the compiler output to me.

Installing the Program

Installation for Command Line usage

If you only want to use W3Olista from the command line, then you're finished with the installation. You can simply copy the compiled binary to a directory of your choice and go ahead. You will probably want to copy it into some globally accessible directory and give it 'r-x--x--x' (511) permissions, so that everybody can run the program.

Installation for CGI usage

Starting the CGI Program

After you have copied the binary to its proper CGI directory, you can test if the program correctly shows up its query form. To do so, enter the URL as given by the redirection rules of your server, adding "/cgi/form" at the end of the URL as extra path information. This should bring up the form, and W3Olista is awaiting your input.

Frank Pilhofer <fp -AT- fpx.de> Back to the Homepage
Last modified: Tue Apr 11 11:44:01 1995