http-analyze 2.2 Installation Instructions
------------------------------------------

Last update: 11/Sep/1998

Please see the file CHANGES for the most recent changes and enhancements
including the latest bug fixes. Information about installation, configu-
ration, usage and interpretation of the results are available in the
online manual included also in the distribution in pre-formatted ASCII,
PostScript and PDF format.

Follow the installation instructions below to compile the source distri-
bution and set up the analyzer on your system.  As always, please test
the software before installing it on a production system. See the manual
for instructions how to test the analyzer after you have compiled it.

The software is also available in binary form for easy installation.
Please see the file INSTALL in the binary distribution for information
about the installation procedure.


INSTALLATION INSTRUCTIONS
-------------------------

To compile http-analyze, you need the GD graphics library for fast GIF
creation written by Thomas Boutell. If you have not done so already, you
can download this software from http://www.boutell.com/gd/. The current
version http-analyze has been tested with is version 1.3. The Makefile
looks for the GD library (libgd.a) in /usr/local/lib and for the header
files in /usr/local/include by default. You have to change this according
to your installation (look for the macros GDLIB and GDINC).

The http-analyze source distribution comes as a TAR archive with the
following files, which are placed in a subdirectory `http-analyze2.2':

  README, INSTALL, CHANGES, LICENSE, ORDER.PS, ORDER.PDF, ORDER.TXT
	- Installation instructions, list of changes, license agreement,
	  ordering and pricing information in PostScript, PDF and ASCII format.

  ha-setup
	- Shell script to set up an analyzer configuration for a virtual web
	  server, to install buttons and to brand http-analyze.

  rotate-httpd
	- Shell script to rotate the logfiles of all virtual servers at the
	  beginning of a new month as required by http-analyze.

  cvt_files
	- Shell script to convert the directory structure of an older
	  statistics directory into the new 2.X format. Caution: Don't
	  erase your actual stats directory, but rather make a copy
	  somewehere, then run this script, then run the new analyzer
	  with output directory set to this new stats directory. So
	  you can test whether everything is running fine without
	  breaking a working scheme.

  config.h
	- Configuration settings: add definitions for your OS/C
	  environment if it is not there already.

  Makefile
	- Change the DEFINES to select appropriate platform-specific
	  settings from config.h

  cntrycode.h, cntrycode.c, defs.h, http-analyze.c, images.c, utils.c, vrml.c 
	- Source files you should not need to touch

  http-analyze.man, http-analyze.1, http-analyze.ps, http-analyze.pdf
	- Manpage in source and pre-formatted ASCII/PostScript/PDF version.
	  Do not remove those files unless you have the nroff/troff text
	  formatter installed on your system, which are needed to produce
	  the formatted files.

  sample.conf
	- Sample configuration file (usually installed somewhere
	  outside the server's document root)

  verify
	- Script to verify logfile entries. Try this if you don't
	  trust the numbers in the summary reports.

  files/...
	- Demo files for logfile formats
	    logfmt.clf		- Common Logfile Format CLF
	    logfmt.dlf		- Combined Logfile Format DLF
	    logfmt.elf		- Extended Logfile Format ELF

	- Files to be installed in HA_LIBDIR (/usr/local/lib/http-analyze)
	  and in the statistics directory as defined with the option -o or
	  with the OutputDir configuration setting:
	    TLD			- List of current top-level-domains
	    3Dlogo.html		- Required for VRML
	    3Dlogo.wrl.gz	- Required for VRML
	    3Dprolog.wrl	- Optional for VRML
	    3DshelfMotion.wav	- Optional for VRML
	    btn/*		- Various buttons and images
	    bugreport.html	- Bug report form (for registered customers)

	This required files can be installed into a statistics directory for
	a new web server by using the ha-setup utility once they have been
	placed in the central directory /usr/local/lib/http-analyze by
	issuing the "make install" command (see below).


QUICK INSTALLATION AND TEST
---------------------------

- After unpacking, change into the directory http-analyze2.2.

- Define the appropriate configuration options in the file config.h and
  in the Makefile. At least, you have to define the platform.  You also
  will have to change the Makefile definitions for the path to the GD
  library and it's header files, which have to be installed separately.
  See the description of the options in the files for examples.

- Decide which directory to use as a central directory (HA_LIBDIR) for the
  buttons and logos. HA_LIBDIR is usually /usr/local/lib/http-analyze. The
  installation of the files there will require root permission later. To
  change the default path, modify the macro LOCALLIB in the Makefile.

- Compile the software and generate the executable by typing "make".
  If your compiler is in pedantic mode, ignore the following warnings:
  http-analyze.c:
    (806) Warning 822: control may fall through case-labeled statement
    (810) Warning 822: control may fall through case-labeled statement
  vrml.c:
    (1214) Warning 819: parameter 'ofp' is not used in function 'prBackground'

- If your compiler complains about missing functions, see the header
  file config for customization macros. They allow to include replacements
  for "problematic" functions. However, this actuall "can't happen" in
  a true ANSI-C environment.

- Create a temporary output directory (say, testd) for a first test and
  install the required files and buttons from the files/ subdirectory.
  Use the ha-setup script to create those files in the temporary output
  directory.

- Then run http-analyze with the actual logfile of your server or with
  one of the logfiles included in this distribution (logfmt.*):

	$ ./http-analyze -vm3f -o testd access

  You will find the resulting main page in testd/index.html.

  Note: If you compare the numbers with the 1.9e version, bear in mind
  that some numbers differ slightly because of higher precision (KB sent)
  or because of changed semantics (unique sites, hits per day).


PERMANENT INSTALLATION
----------------------

- To permanently install the analyzer, issue as root the command

	# make install

  The installation process will copy the executable and scripts into the
  local bin directory and will create a directory HA_LIBDIR for commonly
  used files such as buttons and logos.  The advantage of having all
  required files in this directory is the ability to set up an analyzer
  configuration for virtual servers using the ha-setup script.

- HA_LIBDIR is by default /usr/local/lib/http-analyze (see the LOCALLIB
  macro in the Makefile). Installation of the buttons and logos in this
  directory requires root permissions. If you can't become root, change
  the Makefile macro LOCALLIB to the pathname of a directory you have
  write permission to (for example: $HOME/lib) and re-install the files
  by issuing a "make install". To have ha-setup and http-analyze use this
  library directory, define the environment variable HA_LIBDIR. If, for
  example, LOCALLIB was set to $HOME/lib, HA_LIBDIR would have to be set
  to $HOME/lib/http-analyze.

- Installation for regular invocation of the analyzer and setup as a
  cron job is described in the manpage.

- To view the optional frames summary you need a frames capable browser
  with JavaScript enabled. This functionality has been tested with
  Netscape 3.x/Communicator 4.x on IRIX 6.2 and MSIE 4.0 on WinNT.

- To view the optional VRML model you need a VRML2.0-compliant browser
  such as the CosmoPlayer plug-in from SGI (http://cosmo.sgi.com/)
  currently available for IRIX and Windows. The models created by
  http-analyze have been tested on IRIX 6.2 and WindowsNT.


UPGRADE FROM 1.9e
-----------------

http-analyze 2.X uses a completely new directory structure for the output
files of a statistics report.  If you upgrade from version 1.9e and want
to keep all older statistics without having to analyze all logfiles again,
you have to convert the files into the new directory structure. Please
note, that certain parts of the 2.X report were not available in the 1.9e
version and therefore the link structure of converted reports differs
slightly from the new structure actually generated by http-analyze 2.X.

Version 1.9e did create the following output files per statistics report:

	Name		Content			Period
	-----------------------------------------------------
	index.html	Summary			last 12 month
	stats.hist	History file		last 12 month
	statsYYYY.html	Summary			YYYY
	statsMMYY.html	Full (monthly) stats	MM YY
	stats.html	Short (daily) stats	current month
	filesMMYY.html	List of all URLs	MM YY
	sitesMMYY.html	List of all sites	MM YY
	graphYYYY.gif	Graph			YYYY
	statsMMYY.gif	Full statistics chart	MM YY
	stats.gif	Short statistics chart	current month
	avloadMMYY.gif	Hits by hour		MM YY
	cntryMMYY.gif	Country pie chart	MM YY
	sq_*.gif	Images for bars
	gr-icon.gif	Icon
	-----------------------------------------------------

To convert old statistic files into the new directory structure used by
http-analyze 2.X, use the cvt_files utility:

	$ ./cvt_files
	Name of output directory for HTML files: /usr/foo/stats
	Name of private output directory for lists if any: 

	Creating files and buttons in '/usr/foo/stats'

	Creating subdirectories for 1996 1997
		Creating 'www1996'
		Creating 'www1997'

	Moving HTML and GIF files into appropriate subdirectories:
		stats1996.html -> www1996/index.html
		stats??96.html -> www1996/
		[a-z]*[0-9][0-9]?96.gif -> www1996
		./files??96.html -> www1996/.
		./sites??96.html -> www1996/.
		stats1997.html -> www1997/index.html
		stats??97.html -> www1997/
		[a-z]*[0-9][0-9]?97.gif -> www1997
		./files??97.html -> www1997/.
		./sites??97.html -> www1997/.
		index.html,stats.html -> www1997
		stats.hist -> www-stats.hist

	Done.
	You should now run http-analyze to create an up-to-date summary.
	   -> Note that you will not see an index file in your stats directory
	   -> unless you have run http-analyze for the current month.
	   -> The files for 1997 will be created in '/usr/foo/stats/www1997'.
	$


Then run http-analyze with this new statistics directory at least for the
current the month:

	$ ./http-analyze -vm3f -c sample.conf /usr4/tmp/log/access.12
	Generating statistics in directory `testd'
	Reading data from `/usr4/tmp/log/access.12'
	Hmm, looks like Extended Logfile Format (ELF)
	Start new period at 01/Dec/1997
	Creating VRML model for December 1997
	Creating full statistics for December 1997
	... processing URLs
	... processing hostnames
	... processing user agents
	... processing referrer URLs
	... updating `www1997/index.html': last report is for December 1997
	Statistics complete until 31/Dec/1997
	$

This is the resulting directory structure after conversion and after updating
the statistics by running the new version of the analyzer:

    Name		Content				Period
    -----------------------------------------------------------------
    index.html		Main page for all reports	-
    www-stats.hist	WWW history file		last 12 month
    3Dlogo.html		3D logo (created automatically)	-
    3Dlogo.wrl.gz	3D logo (must exist already)	-
    3Dprolog.wrl	3D prolog (must exist already)	-
    3DshelfMotion.wav Sound (must exist already)	-
    -----------------------------------------------------------------
    btn/		Subdirectory for buttons	-
	*.gif		Several buttons and logos	-
    -----------------------------------------------------------------
    wwwYYYY/		Subdirectory for all output files  YYYY
	index.html	WWW Summary main page		last 12 months
	jsnav.html	Navigation panel		last 12 months
	navMMYY.html	Navigation panel		current month
	stats.html	Short statistics		current month
	statsMMYY.html	Full statistics			MM YY
	daysMMYY.html	Hits by day			MM YY
	avloadMMYY.html Average load by hour		MM YY
	topdom1197.html Top N domains			MM YY
	topuag1197.html Top N browser types		MM YY
	topurl1197.html Top N URLs			MM YY
	filesMMYY.html	Overview about URLs		MM YY
	rfilesMMYY.html Overview about Not Found resp.	MM YY
	lfilesMMYY.html Detailed list of all URLs	MM YY
	sitesMMYY.html	Overview about domains		MM YY
	rsitesMMYY.html	Overview about reverse domains	MM YY
	lsitesMMYY.html	List of all hostnames		MM YY
	agentsMMYY.html Overview about browser types	MM YY
	lagentsMMYY.html List of all browser types	MM YY
	referMMYY.html	Overview about referrer URLs	MM YY
	lreferMMYY.html	List of all referrer URLs 	MM YY
	3DstatsMMYY.html 3D statistics (HTML)		MM YY
	3DstatsMMYY.wrl.gz 3D world (VRML)		MM YY
	frames.html	Frames definition		last 12 months
	header.html	Frames navigation		last 12 months
	fstatsYYYY.html Frames Summary			YYYY
	totalsMMYY.html Frames Summary			MM YY
	graphYYYY.gif	Graph for last 12 months	YYYY
	statsMMYY.gif	Full statistics chart		MM YY
	stats.gif	Short statistics chart		current month
	avloadMMYY.gif	Hits by hour			MM YY
	countryMMYY.gif	Country pie chart		MM YY
	domainsMMYY.gif	Domain pie chart		MM YY
	filesMMYY.gif	Files pie chart			MM YY
	agentsMMYY.gif	Browser pie chart		MM YY
	refersMMYY.gif	Referrer URLs pie chart		MM YY
	gr-icon.gif	Icon				YYYY
    -----------------------------------------------------------------


BRANDING A REGISTERED VERSION
-----------------------------

Registered users will be sent a registration ID and two registration images.
The registration ID can be defined system-wide in a file named

	/usr/local/lib/http-analyze/REGID

if this directory exists ("make install" will create it). Use the command

	./http-analyze -r Customer 37B8JPJZ43009235F00168413866

to save the registration ID in this file.

If you can't become root, you may change the default pathname for the
library directory using the environment variable HA_LIBDIR.  If another
pathname is specified, http-analyze looks there for the required buttons
and logos. To have make install the buttons at the correct place, define
the macro LOCALLIB and run a "make install".

Alternatively, the registration ID can be placed into the configuration
file of an analyzer configuration (make sure to use tabulators to separate
the fields from each other):

	# Registration information
	RegInfo	Customer	37B8JPJZ43009235F00168413866

The dis-advantage of this latter method is that the configuration file
has to be specified each time the analyzer is invoked.


Next, replace the "Unregistered version" buttons with the registration
images you received with your registration. After detaching them from
the email, replace the 'netstore_sw.gif' and 'netstore_sb.gif' images
in the 'files/btn' subdirectory of the source distribution. On Unix,
this is done using the ha-setup utility included in this distribution:

	$ ha-setup
	http-analyze setup
	------------------

	1) Set up an analyzer configuration for a virtual web server
	2) Install the required files in a statistics output directory
	3) Brand your copy of http-analyze with the registration ID
	4) Exit
	
	Please select a function (1-4) [1]: 


Select function 3 and answer the questions to install the registration
images. Then, issue a "make install" to copy all required files (3D*,
btn/*) into a central directory (/usr/local/lib/http-analyze by default).

Use the ha-setup utility also to install the required files into the actual
output directory for your statistics (test directory or some statistics
directory on your web server).

The registration images installed this way will allow registered users to
add their logos to the reports. For users of the freeware version, a link
to the Netstore server will appear instead.  Except for this functionality
controlled with the CustLogoW and CustLogoB directives in the configuration
file, both (free and commercial) versions are absolutely identical. However,
registered users will be supported, freeware users get just the public
standard documentation available on our web site.

To create your own logos, design a logo not bigger than 80x80 pixels in size.
Save one version with a white background for display on white pages (for
example, logo_sw.gif) and one with a black background for display on black
pages (logo_sb.gif).  Then, place them into the central `btn' directory so
that they will be installed automatically by ha-setup. Finally, specify the
names of this logos in the configuration file:

	CustLogoW	btn/customer_sw.gif	http://your.URL/
	CustLogoB	btn/customer_sb.gif	http://your.URL/

For each statistics made now, your logos will appear in the corresponding
reports.  If you have problem creating appropriate logos, contact us.


----------------------------------------------------------------------
If you discover any bugs, please send an email to <office@rent-a-guru.de>.
Always include the version (-V), the Registration ID (visible on the main
page of the summary) and the Company name you have registered under in
your communication. If you want to fill in a bug report online, use the
ha-setup script to start a browser with a formular generated from the
file bugreport.html in the directory /usr/local/lib/http-analyze/.
The ha-setup script will automatically fill in the registration
information if it has been saved in the REGID file under the same
directory.  Thank you very much.
----------------------------------------------------------------------

