[ Top | Up | Prev | Next | Map | Index ]

Readme for analog3.1

Form interface

The form interface provides an HTML front end to analog. That means that users can select options from a web page, instead of having to create a configuration file.

The form interface is suitable for ordinary users to use, but it needs to be set up by a system administrator or other expert. In order to set it up, you need to know what CGI programs are, where they live on your server, and how to set up their permissions properly. It would also be hepful if you can write HTML forms. I shall assume this level of background knowledge for the rest of this section. Also, I shall assume that analog has already been set up and is running properly on its own.

Warning: CGI programs can contain security loopholes which allow an unscrupulous user to harm your system. (If you don't know about this, you shouldn't be running CGI programs at all.) I have tried to make this form interface safe, but I cannot guarantee it, and take no responsibility if anything goes wrong. You use it at your own risk. (See the licence.)

The form interface consists of two parts: a form to choose the options, and a cgi program to interpret them and pass them to the analog program. You don't in fact need the form at all: if you want to create a link to the cgi program, with the arguments passed in the URL in the usual way, then that's fine.

On Unix, to compile the cgi program, you first need to edit the top of anlgform.c to indicate where analog lives on your system. Then type make form, which should compile this source into a program called anlgform.cgi.

On Windows 95 & NT, the cgi program is compiled already, and called anlgform.exe. It assumes that analog is at \analog\analog.exe, so you must move analog there if necessary.

Next put the cgi program wherever your server can find it. Make sure that analog is executable by the server, and that the logfile and domains file are readable. You will probably want to use the full path name for these files; if you don't, it will look locally to anlgform.cgi for them.

The form anlgform.html which is distributed with the program should only be regarded as an example form. Almost every configuration command has a counterpart in the CGI program, and so you can add to the form options to do almost anything you want. (The main exceptions are aliases, which are too complicated, and HEADERFILE, FOOTERFILE and LOGFORMAT, which would allow people to view any file on your system.) I shall give the full list in a minute.

Before you use the form, you must uncomment and edit the action at the top to indicate where anlgform.cgi (or anlgform.exe on Windows) lives on your server. I have also included two other important options at the top, commented out. First, it is often useful to set the logfile to be analysed (or allow the user to choose it), with a field with name="lo". Secondly, some servers need a timezone to be set in a field with name="TZ", or all the times will be wrong. If you are on Unix, you can put any of the standard timezones in this field: the correct one may well be in your own TZ environment variable.

You can specify other configuration files to be included. When analog is called by the CGI program, it first processes the default configuration file as usual. Then it processes any configuration file specified by an argument with name cg. Then it processes all the other arguments which the CGI program specifies. After that, it processes any configuration file specified by an argument with name cm. Finally, it processes the mandatory configuration file as usual.

If the option qv=1 is sent to the CGI program, then analog is not run, but a list of the configuration commands which would have been sent to analog is printed instead. This is useful for checking that the CGI program is working properly. It can also be used for using the form to produce a configuration file.

Troubleshooting

There are lots of reasons why the form interface may not work, and I can't diagnose them very easily. If it doesn't work, first check the following points:
  1. Look in the server's error log for clues.
  2. Are all the file permissions set correctly? Do other CGI programs work on your server?
  3. Include qv=1 in the arguments as explained above. If this works, then at least the CGI program is working.
  4. If you get a long wait, then no data returned, the server is probably timing out the request before analog has finished. The remedy is to increase the timeout interval.
  5. Try running the cgi program from the shell. Set the environment variable QUERY_STRING to equal "xq=1", or "xq=1&qv=1", and run anlgform.cgi directly.
  6. If everything works but the images don't appear in the output, be careful about the IMAGEDIR. It probably shouldn't be inside your /cgi-bin/ directory, or your server will try and execute the images, not send them out.
Here is the complete list of options which can be added to the form and will be interpreted by the CGI program. Each has a two letter name. Values are the same as for the corresponding configuration command except where stated.

Time reports

The first letter is the standard code letter for the report, except that the Quarter-Hour Report is q and the Five-Minute Report is p. The second letter is as follows. If the first letter is lower case, read the column marked lc; if it is upper case, read uc. So, for example, FIVECOLS is pc, but WEEKCOLS is Wd. 
        lc   uc    value
ON/OFF   q    p    1 for on, 0 for off
GRAPH    g    h
ROWS     r    s
COLS     c    d

Other reports

Again, the first letter is the code letter for the report. The second letter is 
                lc   uc    value
ON/OFF           q    p    1 for on, 0 for off
FLOOR            f    g    Excluding floor method
Floor method     h    i    r, p, b or d
SORTBY           s    t    0 for requests, 1 for pages, 2 for bytes,
                           3 for date, 4 for alphabetical, 5 for random
SUB              j         (Where applicable)
SUBFLOOR         w    x    As above
Subfloor method  y    z    As above
SUBSORTBY        u    v    As above
COLS             c    d
Report INCLUDE   l    m
Report EXCLUDE   n    o

Items

First letter as follows: 
Browser       b
Referrer      f
File          r
Host          s
User          u
Virtual host  v
Second letter: 
LOWMEM    k
INCLUDE   x
EXCLUDE   z

Miscellaneous

Command        Code    Value/Notes

ALLBACK        ab      1 for on, 0 for off
BASEURL        ba
CASE           ca      1 for sensitive, 0 for insensitive
CONFIGFILE     cg/cm   See above
COMPSEP        cp
               cr      Charset of language file
DNSGOODHOURS   da
DNSBADHOURS    db
DECPOINT       de
DOMFILE        df
DIRSUFFIX      di
DNSFILE        dn      Also sets DNS READ; o/wise DNS is NONE
FROM           fr
MINGRAPHWIDTH  gw
HOSTNAME       hn
HOSTURL        hu
IMAGEDIR       ie
LANGUAGE       la      Name of language: LANGFILE overrides
CACHEFILE      lc
LANGFILE       lf      Overrides LANGUAGE
LOGO           lg
LOGFILE        lo
LASTSEVEN      ls
LOGTIMEOFFSET  lt      For all logfiles
REFLINKINCLUDE lw
LINKINCLUDE    lx
REFLINKEXCLUDE ly
LINKEXCLUDE    lz
MARKCHAR       ma
OUTPUT         ot      0 for HTML, 1 for ASCII, 2 for COMPUTER
PAGEWIDTH      pw
PAGEINCLUDE    px
PAGEEXCLUDE    pz
               qv      Output configuration file, rather than run analog
RAWBYTES       rb
REPORTORDER    re
SEPCHAR        sa
REPSEPCHAR     sb
TIMEOFFSET     tm
TO             to
WARNINGS       wa      1 for on, 0 for off. If unspecified, get WARNINGS FL.
WEEKBEGINSON   wb      0 for Sunday, 1 for Monday, ..., 6 for Saturday
GOTOS          xp
GENERAL        xq
REFARGSINCLUDE yw
ARGSINCLUDE    yx
REFARGSEXCLUDE yy
ARGSEXCLUDE    yz
Stephen Turner
E-mail: sret1@cam.ac.uk

[ Top | Up | Prev | Next | Map | Index ]