http-analyze 2.4 - A log analyzer for web servers
=================================================

INSTALLATION INSTRUCTIONS FOR UNIX SYSTEMS
------------------------------------------

Last update: 01/November/1999

http-analyze is available in binary (pre-compiled) and in source form.
Installation of the software requires the following steps:

	1.  Unpack the files from the software distribution.
	2.  Get the GD, PNG and ZLIB software and generate the binary
	    by compiling the http-analyze sources and linking the object
	    with the libraries mentioned above (SOURCE DISTRIBUTION only).
	3.  Run the analyzer for a first test.
	4.  Install the program and the required support files.
	5.  Optionally install the multi-national message catalogs.
	6.  Create an analyzer configuration for your web server.
	7.  Register and brand your copy of http-analyze.


These steps are described in greater detail below. More information about
configuration, usage and interpretation of the results is available in the
online manual included in the distribution in pre-formatted ASCII, PostScript
and PDF format.

As always, please test the software carefully before installing it on a
production system. Follow the instructions below for a quick test of the
analyzer software after you have unpacked or installed the program.


-----------------------------------------
STEP 1: UNPACK THE FILES FROM THE ARCHIVE
-----------------------------------------

BINARY DISTRIBUTION:
--------------------
The binary distribution comes as a gzip'ed (compressed) TAR archive.
To unpack the archive, change into the directory where you want to
install the files and issue a command similar to the following:

    gzip -dc http-analyze2.4-solaris.tar.gz | tar xvof -

This will create a directory "http-analyze2.4" with all required files
and the executable for the selected platform. See the file "FILELIST"
for a detailed listing of all files.

Proceed with step 4 (BINARY DISTRIBUTION).


SOURCE DISTRIBUTION:
--------------------
The source distribution comes as a gzip'ed (compressed) TAR archive.
To unpack the archive, change into the directory where you want to
install the files and issue the following command:

    gzip -dc http-analyze2.4-src.tar.gz | tar xvof -

This will create a directory "http-analyze2.4" with all required files.
See the file "FILELIST" for a detailed listing of all files.

To compile http-analyze on your system, you will also need the "GD library
for image creation" by Thomas Boutell, version 1.6 or 1.7 (PNG format) and
probably the PNG and ZLIB libraries as well. You can get them from:

	http://www.boutell.com/gd/		GD library
	http://www.cdrom.com/pub/png/		PNG library
	http://www.cdrom.com/pub/infozip/zlib/	ZLIB library

Proceed with next step (2).


----------------------------------------------------------
STEP 2: GENERATE THE EXECUTABLE (SOURCE DISTRIBUTION ONLY)
----------------------------------------------------------

To compile http-analyze, change into the directory "http-analyze2.4"
(or in the subdirectory "src"), define the following macros and run the
command "make". Specify the values for the macros below either by editing
the Makefile or by passing them as arguments to "make":

    Make macro	Default

    REQLIBS	-L /usr/local/lib -lgd -lpng -lz
		linker options for the GD, the PNG and the ZLIB libraries

    REQINCS	/usr/local/include
		pathname of the directory containing necessary header files

    DEFINES	the platform-specific compiler options such as the selection
		of the OS. Pre-defined configurations exist for various
		platforms, such as IRIX, SUN, AIX, DEC, HPUX, Linux, SCO,
		BSD, SVR4, SVR3.  See the definitions in the Makefile.

    PLATFORM	more platform-specific compiler options such as the compiler
		mode (-ansi or -xansi) which should not be passed to "lint",
		but to the linking loader. See also the descriptions for
		this macro in the Makefile.

    HA_LIBDIR	/usr/local/lib/http-analyze
		the directory where required support files such as buttons
		and logos are to be installed.

    HA_BINDIR	/usr/local/bin
		the directory to install the http-analyze binary in.

    HA_MANDIR	/usr/local/man/cat1
		the directory for the manpage of http-analyze.


If you want to include multi-national language support (MNLS), please look
at the file "config.h" and read the instructions in step 5 before starting
to compile the sources. http-analyze supports X/Open MNLS, System V MNLS
and an own implementation for systems without MNLS support. Look for the
macros USE_XPGCAT (default), USE_SVR4CAT and USE_MYCAT in this file.

Then issue the command "make". It should compile http-analyze without errors.
Note that http-analyze has been successfully linted and ported to many
platforms with no changes on the source files. See the file "lint.out"
for possible warnings which can be ignored safely.

To pass arguments to the "make" command for customization as discussed
above, use command line arguments as in:

    cd http-analyze2.4
    make DEFINES="-DIRIX" PLATFORM="-xansi -n32" OPTIM="-O2" \
         REQINCS=/usr/local/include REQLIBS="-L/usr/local/lib -lgd"


It is usually sufficient to define the REQINCS/REQLIBS macros and to select
the appropriate target platform in the DEFINES macro. If your C environment
lacks one or the other function used by http-analyze or if you want to
generate a special tailored version of the program, you may want to take a
closer look into the file "config.h", which actually contains all required
definitions for the selected platform. A description of all configuration
parameters and of the replacement functions included in the distribution
can be found in the file "config.h" itself. However, using replacement
functions actually shouldn't become necessary in a true ANSI-C environment.

Proceed with step 3 or step 4.


-----------------------------
STEP 3: TEST-RUN THE ANALYZER
-----------------------------

To test run the analyzer, create an output directory for the statistics
report (say "testd") and run the analyzer on your server's logfile or on
some of the sample logfiles contained in the subdirectory "files". Note
that there is no need to install the required support files in the output
directory as it used to be in previous versions of http-analyze.

The following example uses the sample logfile "files/logfmt.elf" included
in the distribution, so that you can type exactly those commands on your
system to do a quick test (the "./" in front of the command name ensures
that you are indeed executing the new binary rather than an old version
of http-analyze, which might still be installed on your system):

    $ cd http-analyze2.4/src
    $ mkdir testd
    $ ./http-analyze -v3f -o testd ../files/logfmt.elf
    http-analyze 2.4pl1 (IP22; IRIX 6.2; XPG4 MNLS; PNG)
    Copyright 1999 by RENT-A-GURU(TM)
    Generating full statistics in output directory `testd'
    Reading data from `../files/logfmt.elf'
    Best blocksize for I/O is set to 64 KB
    Hmm, looks like Extended Logfile Format (ELF)
    Start new period at 01/Jan/1999
    NOTE: output files will be created in subdirectory `www1999'
    Creating VRML model for January 1999
    Creating full statistics for January 1999
    [...]
    $


Now start your favourite web browser and point it to the main page of
the statistics report contained in the file "testd/index.html" as in:

    $ netscape file:`pwd`/testd/index.html


---------------------------
STEP 4: INSTALL THE PROGRAM
---------------------------

All required support files should be installed in the central directory
HA_LIBDIR, which is /usr/local/lib/http-analyze by default. The binary is
installed in HA_BINDIR, while the manpage goes to HA_MANDIR.

If you want to change any of the defaults - for example, because you have no
write permission for those locations -, change the following macros in the
Makefile before compiling the software (SOURCE DISTRIBUTION) or define the
environment variables with the same name for the makeinstall shell script
(BINARY DISTRIBUTION):

    HA_LIBDIR	/usr/local/lib/http-analyze
		the directory where required support files such as buttons
		and logos are to be installed.

    HA_BINDIR	/usr/local/bin
		the directory for installation of the http-analyze binary.

    HA_MANDIR	/usr/local/man/cat1
		the directory for the manpage of http-analyze.

    EXTENSION	1
		the extension of the manpage: either `1' for pre-formatted
		ASCII text or `man' for the nroff source format.

    COMPRESS	(no default)
		the utility to use for compression of the manpage.


SOURCE DISTRIBUTION:
--------------------
Change into the directory "http-analyze2.4", define the macros shown above
either by editing the Makefile or by passing them via the command line and
install the binary and the required support files by issuing the command
"make install". This will change into the directories "src" and "man" and
execute a "make install" there. If an older version of http-analyze is found
in the installation directories, it will be saved by tacking a Suffix ".O"
on the names of the binary and the HA_LIBDIR:

    # cd http-analyze2.4
    # make install HA_BINDIR=/usr/local/bin \
    >              HA_LIBDIR=/usr/local/lib/http-analyze \
    >              HA_MANDIR=/usr/local/man/cat1 COMPRESS="compress -f"
    Installing http-analyze in /usr/local/bin
    Installing buttons and files in /usr/local/lib/http-analyze
    Installing http-analyze.1 in /usr/local/man/cat1
    [...]
    Installation completed.

    Please see following new options in the documentation:

    http-analyze -B [-v] [-o outdir]                to create buttons in outdir
    http-analyze -i new_cfg [-v] [-c cfgfile]       to create a new config file
    http-analyze -r company regID [free|comm]       to register your copy
    #


BINARY DISTRIBUTION:
--------------------
Change into the directory "http-analyze2.4" and install the binary, the
required support files and the manpage by running the shell script
"makeinstall". The script will list all binaries available for installation.
This is most often only one binary, but a multi-platform distribution with
binaries for all available platforms is available also to simplify the
installation in mixed environments.

Just answer the questions you will be asked by "makeinstall". In most cases,
the suggested default settings should be o.k. unless you have no write
permission into the recommended directories. In this case, choose any
directory you have write permission to and use the HA_LIBDIR environment
variable to specify the name of this directory when running http-analyze:

    # ./makeinstall
    HTTP-ANALYZE BINARY INSTALLATION
    --------------------------------

    This script will install http-analyze from a binary distribution.
    Please answer the few question for customization of the places
    where the files will be installed. Where appropriate, use the
    default values.

    Binaries are available for the following platforms:

            Suffix          Platform
            -------------------------------------
            irix            SGI IRIX 5.X/6.X
            irixN32         SGI IRIX 6.X (n32)
            solaris         Sun Solaris 5.5.1
	    [...]
            -------------------------------------

    Your system appears to be an IP22 running IRIX 6.2.
    The recommended binary for this platform is 'irix'.
    You can also choose the 'irixN32' version if the
    N32 libraries have been installed on your system.

    Please specify the binary to install: [irix] irixN32

    Now specify the various places to install the files in.

    Name of installation base directory: [/usr/local] <RET>
    Name of HA_BINDIR (for the executable): [/usr/local/bin] <RET>
    Name of HA_LIBDIR (for the buttons): [/usr/local/lib/http-analyze] <RET>
    Name of HA_MANDIR (for the manpage): [/usr/local/man/cat1] <RET>
    Type of manpage (p)re-formatted or (s)ource: [pre-formatted] <RET>

    This are the current configuration settings:

    Selected platform:      SGI IRIX 6.X (n32) (http-analyze.irixN32)
    Name of the executable: /usr/local/bin/http-analyze
    Name of the libdir:     /usr/local/lib/http-analyze
    Name of the manpage:    /usr/local/man/cat1/http-analyze.1
    XPG4 MNLS support:      the system's locale (/usr/lib/locale)

    (C)hange settings, (i)nstall the software or (q)uit? [install] <RET>
    
    Creating directories, saving old version
    Installing the http-analyze binary in /usr/local/bin
    Installing buttons and files in /usr/local/lib/http-analyze
    Installing the manpage in /usr/local/man/cat1
    Installing XPG4 MNLS support in the system's locale (/usr/lib/locale)

    Installation completed.

    Please see following new options in the documentation:

    http-analyze -B [-v] [-o outdir]             to create buttons in outdir
    http-analyze -i new_cfg [-v] [-c cfgfile]    to create a new config file
    http-analyze -r company regID [free|comm]    to register your copy
    # 


Note: Once the analyzer is installed, the files and buttons will be copied
to the web server's statistics output directory automatically if they don't
exist or if they are out-of-date. The helper script "ha-setup" used in
previous versions of http-analyze is not needed anymore, since all its
functionality has been integrated into http-analyze.


---------------------------------------
STEP 5: MULTI-NATIONAL LANGUAGE SUPPORT
---------------------------------------

If you do not want to use Multi-National Language Support, skip to step 6.

http-analyze supports Multi-National Language Support (MNLS) according to
X/Open Portability Guide 4 (XPG4) and according to the Unix System V
Interface Definition (SVR4). For systems without XPG4/SVR4 MNLS support,
a simple implementation (native MNLS) is included in http-analyze. All
three methods use message catalogs, which contain all messages and strings
in a certain language and which will be loaded by http-analyze at run-time.

While the method of MNLS support has to be specified through one of the
make macros USE_XPGCAT, USE_SVR4CAT or USE_MYCAT before compilation of
http-analyze, the message catalogs itself are completely independent from
the source files. This means that if more languages become available, you
must not recompile the analyzer in order to have it recognize a new language.
The only action required to add a new language is to install an appropriate
message catalog as described below.

The subdirectory "msgcat" contains all message source files in XPG4 and SVR4
format. The recommended method for MNLS support is the XPG4 MNLS. Therefore,
new languages are always implemented using a source file in X/Open format.
The SVR4 files will be generated from the XPG4 files using the perl script
"gen-msgcat" if SVR4 or native MNLS has been selected as the method.

To install the message catalogs, issue one of the following commands
depending on the method you did select. Note that you need root privileges
for the XPG4 and SVR4 MNLS and write permission to HA_LIBDIR for the native
MNLS. The following examples will install the message catalogs for English
(en), German (de) and Russian (ru):

    o X/Open MNLS (if USE_XPGCAT has been defined in step 2):

	# make xpgcat
	for idx in en de ru; do \
	gencat /usr/lib/locale/$idx/LC_MESSAGES/http-analyze ha-$idx.str; done
	#

	To request a certain language when running http-analyze, use the
	"LANG" or the "LC_MESSAGES" environment variables or the option
	"-L lang". See setlocale(3C) for information about localization
	and catopen(3C), catgets(3C), catclose(3C) and nl_types(5) for
	more information about X/Open MNLS.


    o SVR4 MNLS (if USE_SVR4CAT has been defined in step 2):

	# make svr4cat
	perl gen-msgcat ha-en.str >ha-en.cat
	perl gen-msgcat ha-de.str >ha-de.cat
	perl gen-msgcat ha-ru.str >ha-ru.cat
	for idx in en de ru; do \
	mkmsgs -o -i $idx ha-$idx.cat http-analyze; done
	#

	To request a certain language when running http-analyze, use the
	"LANG" or the "LC_MESSAGES" environment variables or the option
	"-L lang". See setlocale(3C) for information about localization
	and gettxt(3C) for more information about SVR4 MNLS.


    o Built-in MNLS (if USE_MYCAT has been defined in step 2):

	# make mycat HA_LIBDIR=/usr/local/lib/http-analyze
	perl gen-msgcat ha-en.str >ha-en.cat
	perl gen-msgcat ha-de.str >ha-de.cat
	perl gen-msgcat ha-ru.str >ha-ru.cat
	test -d /usr/local/lib/http-analyze/msgcat || \
	    mkdir /usr/local/lib/http-analyze/msgcat
	cp ha-en.cat ha-de.cat ha-ru.cat /usr/local/lib/http-analyze/msgcat
	#

	With built-in (or "native") MNLS the message catalogs are installed
	in the directory HA_LIBDIR/msgcat, so make sure to specify the
	correct value for the HA_LIBDIR macro here too if you have changed
	it during compilation of http-analyze in step 2.  HA_LIBDIR is by
	default "/usr/local/lib/http-analyze" and can be changed during
	run-time with the HA_LIBDIR environment variable. The format used
	for the native message catalogs is the same as in SVR4 MNLS. You
	can use the environment variable HA_LANG or the option "-L lang"
	to request the desired language at invocation of http-analyze.
	

------------------------------------------------------------
STEP 6: CREATE AN ANALYZER CONFIGURATION FOR YOUR WEB SERVER
------------------------------------------------------------

After installing the analyzer you can set up an analyzer configuration for
your web server.  http-analyze 2.4 provides some new options to create an
analyzer configuration file and to initialize the output directory for the
statistics report. This was accomplished in previous versions of http-analyze
by running the shell script "ha-setup" which now has become obsolete.

The following description explains the usage of the new functions:

  CREATE A NEW CONFIGURATION FILE
  -------------------------------
  To create a new configuration file for a virtual or physical web server,
  use the option "-i newcfg", where "newcfg" is the name of the config file
  (usually "analyze.conf", but you can choose any other name you like):

    $ http-analyze -i analyze.conf

  This creates the file "analyze.conf", which contains the default settings
  for all directives, except for the (probably virtual) server's name, which
  has to be specified by changing the value of the "ServerName" directive
  using a text editor.


  UPDATE AN OLD CONFIGURATION FILE
  --------------------------------
  If you already have a configuration file and if you want convert it into
  the new format, just add the name of the old config file to the command.
  Note that although the new config file may be the same file as the old one,
  it is recommended to use different files to be able to quickly locate the
  new configuration directives by comparing both files against each other.
  The command to update an older config file therfore is:

    $ http-analyze -c analyze.conf -i analyze.conf.N

  Then review the config settings in "analyze.conf.N", optionally add your
  settings for the new configuration directives and activate the new file by
  saving the old and renaming the new, just prepared configuration file:

    $ mv analyze.conf analyze.conf.O
    $ mv analyze.conf.N analyze.conf


  INSTALL THE BUTTONS WITHOUT RUNNING STATISTICS
  ----------------------------------------------
  You do not need to install any files or buttons into a new or old
  statistics output directory unlike required in previous versions of
  http-analyze. If http-analyze has been installed correctly (i.e. the
  buttons and logos are in HA_LIBDIR), it will create those files in the
  output directory automatically when running it the first time. If for
  some reason you want to install those files without creating a statistics
  report, use the option "-B", which causes http-analyze to only create the
  required files and buttons in the given output directory. The output
  directory must exist already:

    $ mkdir testd
    $ http-analyze -vB -o testd
    http-analyze 2.4pl1 (IP22; IRIX 6.2; XPG4 MNLS; PNG)
    Copyright 1999 by RENT-A-GURU(TM)
    All buttons and files have been installed
    $


  FILING A BUGREPORT
  ------------------
  To file a bug report, use the "-X" option, which causes http-analyze to
  print an URL pointing to our bug reporting form. Although you can locate
  the bug reporting form through links on our web site, using the analyzer
  to create the URL will fill in all required data such as the registration
  ID, the customer name, the version and the platform. To pass this URL to
  your browser, use the command substitution on Unix systems:

    $ netscape `http-analyze -X`

  This will pass the URL to the Netscape Communicator. Be sure to use the
  back quotes, which have quite a different meaning than the single quotes.
  For other systems without command substitution, use cut & paste to pass the
  URL of the bug reporting form to your browser.


----------------------------------------------------
STEP 7: REGISTER AND BRAND YOUR COPY OF HTTP-ANALYZE
----------------------------------------------------

http-analyze is available for personal and commercial use. For personal
use, the software is free, but does not include any support or any other
assistance. Only commercial users will receive support, technical assistance
and automatic updates. Both license types require registration through
a form on our web site.

After registration of either a free Personal License or a Commercial Service
License you will receive a registration ID and two registration images by
email. Detach the registration images from the email. They should be named
"free-netstore_sb.png" and "free-netstore_sw.png" for the Personal License
and "comm-netstore_sb.png" and "comm-netstore_sw.png" for the Commercial
Service License.

The registration ID should be saved in the file "REGID" under HA_LIBDIR
and the buttons should be placed into the subdirectory "HA_LIBDIR/btn".
http-analyze can do this for, so just run it as follows:

    $ http-analyze -r "CustomerName" RegID free

where "CustomerName" is the name of your organization as specified on the
registration form or any abbreviation of your organization's name, and
"RegID" is the registration number, which has been sent to you by email.
The (optional) third parameter "free" specifies to copy the registration
images for the Personal License into "HA_LIBDIR/btn". To install the
registration images for a Commercial Service License, use "comm" instead
of "free".

http-analyze will print an error message if the registration images can't
be found in the current directory. If this is the case, check whether you
detached the images from the email at the correct place and whether they
have the correct names as mentioned above.

Have fun with http-analyze!