Readme for analog3.3

Form interface and CGI program

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 have to be running a web server. You need to know what CGI programs are, where they live on your server, and how to set up their permissions properly. And you need to know how to 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. Read and understand the World Wide Web Security FAQ first.) I have tried to make this form interface safe, but I cannot guarantee it, and I take no responsibility if anything goes wrong. You use it at your own risk. (See the licence.) Furthermore, you should be aware that unless you take special measures like password protection, setting up the form interface implies making analog executable, and your logfiles analysable, by anyone on the internet.

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 must first 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, the cgi program is compiled already, and called anlgform.exe. It assumes that analog is at \analog\analog.exe (on the same drive as anlgform.exe), so you must put a copy of analog there.

There is a form called anlgform.html distributed with the program. You can also find forms in languages other than English in the lang directory. 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. There are other instructions at the top of the form which you must read and do before the form will work.

The form 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. But as an example, if you have a form element with name="lo", then its argument will be passed to a LOGFILE command, so you can allow your users to select a logfile in this way.

(It is theoretically possible, though I think very unlikely, that another file on your system could conform sufficiently closely to one of the predefined log formats that analog could be persuaded to analyse it and so reveal some of its contents. If you're worried about this, or even if you want to force only one particular logfile to be analysed from the form, you can put a LOGFILE command in your mandatory configuration file. This will override earlier LOGFILE commands, and thus make analog ignore any logfiles specified on the form. This trick is only possible on Windows if you compile your own version of analog.)

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. You may therefore want two copies of analog, one for form use and one for non-form use, with different configuration files compiled in. Note that the commands in the default and mandatory configuration files will contribute to the configuration: some of them may even override options specified on the form.

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

1. Do other CGI programs work on your server?
2. Look in the server's error log for clues.
3. Are all relevant files (analog itself, logfiles, configuration files etc.) readable by your web server?
4. Include qv=1 in the arguments as explained above. If this works, then at least the CGI program is working.
5. Try running the cgi program from the shell. Set the environment variable QUERY_STRING to equal "xq=1", and run anlgform.cgi directly.
6. If some form options don't seem to take effect, then check whether they are being overridden by a command in a configuration file.
7. 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.
8. There is one DNS issue which confuses people. The form always sets either DNS READ (if a DNS file is set on the form) or DNS NONE (otherwise). This may override what you have set somewhere else. You can override this behaviour in the mandatory configuration file, but you are likely to run into timeout problems if you do.

Time reports

        lc   uc    value
ON/OFF   q    p    1 for on, 0 for off
GRAPH    g    h
ROWS     r    s
COLS     c    d

Other reports

                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

Browser       b
Referrer      f
File          r
Host          s
User          u
Virtual host  v

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 set to 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

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