#######################################################################
#  $Id: INSTALL 294 2006-10-11 11:54:54Z steve $
#  Copyright (C) 2005, 2006 by Stephen McInerney (spm@stedee.id.au)
#######################################################################

Installation instructions for AWFFull

Requirements:
-------------
AWFFull is dependant on several external libraries, most should be on a
standard *nix system anyway, some are more specific.

The main additional libraries being:
* PNG for creating the various images
	http://www.libpng.org/pub/png/
* GD for creating the graphs as png images
	http://www.boutell.com/gd/
* ZLIB for reading compressed log files
	http://www.gzip.org/zlib/
* PCRE for simplifying the matching of log entries
	http://www.pcre.org/

If you require more accurate Country tracking, you can make use of GeoIP.
        http://www.maxmind.com/app/geoip_country


Basic Installation:
-------------------
* Untar the source file
* cd into the newly created source directory
* ./configure
* make
* make install

Eg:
$ tar zxf awffull-3.7.1.tar.gz
$ cd awffull-3.7.1
$ ./configure
$ make
$ make install

The "make install" may need to be performed as a privileged user (root).


Basic Usage and Running of AWFFull:
-----------------------------------
AWFFull comes with a sample config file in the main directory of the
source collection: sample.conf.
You will probably want to copy and edit this file and configure various
settings to meet your needs, the defaults should work but will be
inadequate.

A normal run would be similar to:
awffull -c awffull.mywebsite.conf logfile.lastmonth.log.gz


AWFFull generates several HTML files and png images in a designated output
directory. Either open directly with a local web browser, or access via
a web server configured to allow access to that directory.


Advanced Installation:
----------------------
Assumes that you are already familiar with GNU autobuilding.
Additional configure options are:

  --with-gd=DIR           Where to additionally look for gd header files
  --with-gdlib=DIR        Alternate location for libgd library
  --with-z=DIR            Alternate location for libz header files
  --with-zlib=DIR         Alternate location for libz library
  --with-png=DIR          Alternate location of png header files
  --with-pnglib=DIR       Alternate location for libpng library
  --with-geoip=DIR        Alternate location of geoip header files
  --with-geoiplib=DIR     Alternate location for libGeoIP library

  --disable-geoip         Disable GeoIP (default=no)


These all assist with locating libraries and headers in non standard
locations. "--disable-geoip" will stop automatic inclusion of GeoIP
capabilities if otherwise found.


  --enable-debug          Turn on compiler debugging information (default=no)
  --enable-developer      Turn on developer warnings and debugging
                          (default=no)

These two enable additional levels of error checking in the compiled code.
Developer mode additionally adds a lot more compile time warnings and
enables profiling mode for use with gprof. This *really* slows down
normal run speeds, and is recommended only for those keen to help
with coding/debugging/performance issues.


Country Flags:
--------------
With version 3.7.1 of AWFFull, a set of country flags from
http://flags.blogpotato.de/ can be included and displayed in the country
table.
These are all stored in the "flags" subdirectory, and need to be manually
copied to a web server or similar for access.
The location can be specified within the config file, and can be a complete
URL, vs relative position from a web root. Thus multiple awffull reports
could access a single set of flag picture files.
See 'FlagsLocation' for more details. By default the flags will not display.


GeoIP:
------
With version 3.7.1 of AWFFull, the GeoIP API can be called.
By default, if they exist on the system where AWFFull is being
built, then the resulting binary will enable access to GeoIP.
Do be aware that the default state of AWFFull is to *NOT* actually use
GeoIP. Mainly to maintain existing backwards compatibility.
This can be controlled at both build time (configure --disable-geoip) and
at run time (awffull --use_geoip).

