W3Olista: Introduction

This software is a quite powerful tool that will give you complete insight into the access to your Web server. This text will introduce the different methods how to start up the program.

Basics

Like with any other software, you must give W3Olista commands, telling the program what it has to do. W3Olista knows a variety of commands that control its behaviour. But, there are many ways to issue the commands. If you run the program from the command line, you give the commands as individual parameters. If you call any specific report, you give the commands in the form of a specially constructed URL. And if you browse reports from the Query Form, W3Olista constucts its commands itself, you merely chose which command to execute by clicking with your mouse.

So keep in mind that I will always refer to a command as a single instruction to the program. Many commands are needed to run the program, and a full working set of commands is either a command line, or a URL.

With CGI programs, there is the interesting feature of the Extra Pathname Information. This is the part of the URL that exceeds the basic pathname of the script. If a script has a basic URL of /cgi/trashcan, and you call the URL /cgi/trashcan/delete/file, then delete/file is the Extra Pathname Information. You need to understand this concept, because it is extensively used here. W3Olista interpretes this extra information as a list of commands to the program. So, to call the program via an URL and simultaneously give it a set of commands, you add the commands, separated by slashes, to the basic URL.

Basic Startup Procedure

There are three different methods to produce a report. First, you can use the Query Form, where you can enter the necessary data online into a form, submit it, and browse the result. Second, you can specially construct commands into an URL, thus eliminating the form input. Third, you can offline-create reports from the command line. Each of this methods has its pros and cons, and its unique method of startup.

Getting to the Query Form

Getting the form is the first example of how to give the program commands via Extra Pathname Information. In order to bring up the Form, you give W3Olista two commands, cgi (tells W3Olista that it is called as a CGI program) and form (the command to bring up the Form). You can always add some more commands to modify its behaviour, but you usually only need these two. So, if you installed the program to have an URL of /cgi/olista, calling /cgi/olista/cgi/form brings up the form.

See below for other general commands.

Startup with a Custom URL

You can generate predefined reports by using a special URL, containing the set of commands that produce the wanted report. But there is a single command you must not forget: html, which instruct W3Olista that it shall not print out self-referencing browseable reports but HTML text. So, the prefix of any such URL is always (assuming the same location as above) /cgi/olista/html.

Startup from the Command Line

If you want to use the program offline, either by running it from the command line, or by executing it remotely from cron, you cannot use the Extra Pathname, simply because shells do not know this concept. Instead, you give each command as a separate parameter to the program (separated by spaces instead of slashes). As with the custom URL, you will also always use the html command to make the program output HTML text. If W3Olista resides, for example, in /usr/local/bin/WWW, then your command line will always begin with /usr/local/bin/WWW/olista html.

Command Details

There are some special characters that you must not use in commands, or at least, use with care. These special cases are the space ' ', the slash '/' and the semicolon ';'. A space causes troubles in all cases, but you can replace it with %20 (the hexadecimal representation). The semicolon can be used without problem in URLs, but is special to the shell and thus it must be escaped if you want to use a semicolon on the command line. The slash cannot be used in URLs, because there it is needed as command separator. And due to a bug in some servers, you also cannot replace it with its hexadecimal representation. Therefore, the dollar sign '$' must be used instead of a slash. This makes the dollar sign unavailable, but it isn't needed anyway.

General Commands

These are general commands that can be used in all cases:

sendcomment: With this command, W3Olista prints out a form to interactively send a comment about this program to the author. This overrides all other commands (save cgi or html, one of these must be given, too).
logdir=<directory>: Sets a different directry where to read logfiles from. It must be given as an absolute path without trailing slash. Multiple directories can be set by separating them with a semicolon. This value overrides the default value set in the Makefile. Remember that you must substitute all the slashes with dollar signs, and escape the semicolons on the command line.
logfile=<file pattern>: The file pattern for logfiles as described here. Again, this command overrides the default value from the Makefile. And don't forget to substitute percent signs with their escape sequence "%25".
CustomHeader=<filename>: filename is read and printed as header before the actual report, containing a custom title, headings and any kind of text. The filename must be given as absolute path, again with the slashes substituted by dollar signs. See here for a description of the required elements in a custom header. If you don't supply a custom header, a default one is used.
CustomFooter=<filename>: filename is read and printed at the bottom of the report. The filename must be given as absolute path, again with the slashes substituted by dollar signs. See here for a description of the required elements in a custom footer. If you don't supply a custom footer, a default one is used.
CutPrefix=<switch>: Our server sometimes gets malformed requests, with the http:// prefix still present, which is quite annoying. This also results in invalid File Links. This switch defaults to Yes, meaning that such prefixes are discarded. But in some other cases, for example when analyzing cache or proxy logs, it makes sense to leave them in; in this case, use CutPrefix=No.
CountUnique=<switch>: To save time and memory, W3Olista only records host and file information to the needed depth. Unfortunately, this makes a detailed count of Unique Hosts (the individual hosts that have accessed your pages, this is the best possible count of individual users) impossible. Use this command as CountUnique=Yes to re-enable this count. Be aware that this needs plenty extra memory and more time.

Frank Pilhofer <fp -AT- fpx.de> Back to the Homepage

Last modified: Tue Nov 7 16:45:25 1995