################################################################################
#                                                                              #
#                             "WEBALIZER Xtended"                              #
#                                                                              #
################################################################################

INSTALL

Version: RB-19
Date   : August 8, 2007
Author : Patrick Frei
Copyright (c) 2005-2007 Patrick Frei. All rights reserved.

================================================================================

INDEX
1.   IMPORTANT NOTE ON UPGRADING FROM PRIOR VERSIONS
2.   PREREQUISITES
3.   INSTALLATION INSTRUCTIONS FOR PATCH ONLY
4.   INSTALLATION INSTRUCTIONS FOR COMPLETE PATCHED SOURCE CODE
5.   INSTALLATION INSTRUCTIONS FOR DNS, LANGUAGE AND HTTP-404-ERROR SUPPORT
6.   INSTALLATION INSTRUCTIONS FOR GEOIP LIBRARY SUPPORT
7.   INSTALLATION INSTRUCTIONS FOR APACHE MOD_LOGIO SUPPORT
8.   KNOWN ISSUES

================================================================================

1. IMPORTANT NOTES ON UPGRADING FROM PRIOR VERSIONS

a. Whenever you install Webalizer Xtended for the first time or upgrade the 
   original Webalizer to Webalizer Xtended, make sure that your system no 
   longer has an old version of the webalizer.current data file installed! 
   This file saves the previously stored data for the current month if you are 
   using incremental mode. You can typically find the offending file in the 
   same directory as the generated reports are located, e.g. in 
   /usr/local/apache/htdocs/stat. To upgrade you can REMOVE or MODIFY that 
   file:
   1. If you REMOVE the webalizer.current data file, you will probably lose 
      some previously cached data. That depends on your system configuration, 
      e.g. if you are using logrotate, etc.
   2. If you MODIFY your webalizer.current data file you won't lose any data. 
      Proceed as described below:
      - Backup the original file by executing the following command:
        # cp webalizer.current webalizer.current.orig
      - Execute the following command:
        # sed "$ a\0\n\# -notfounderrors- \n\# End Of Table - notfounderrors" \
	   webalizer.current > webalizer.current.tmp
      - Execute the following command:
        # mv webalizer.current.tmp webalizer.current
   
   Now go to section 3 or 4 of this manual to install Webalizer Xtended. If you 
   don't get an error like "Error: Unable to restore run data (15)" after 
   running Webalizer Xtended the upgrade was successful.

b. No action has to be taken if you upgrade from an already patched Webalizer 
   Xtended version to a new one, e.g. from Webalizer Xtended RB18 to RB19.

c. If you'd like to profit from the browser / user agent grouping and already 
   have an old Webalizer version installed, you first need the remove the old 
   webalizer.conf for the changes to take effect. Don't forget to adjust the 
   file to your previous configuration options.
   
d. The 404 Not Found Errors will be unreliable of course if you start processing 
   them e.g. at the end or in the middle of the month (i.e. if you are using 
   incremental processing).
   
================================================================================

2. PREREQUISITES

Depending on your system you additionally need software packages to make 
Webalizer Xtended run successfully. Normally these necessary packages are 
called:
- libpng
- libpng-devel
- gd
- gd-devel
- zlib
- zlib-devel

If you need DNS support or want to change the default language please refer to 
chapter 5. INSTALLATION INSTRUCTIONS FOR DNS, LANGUAGE AND 404 SUPPORT.

DEBIAN users need the following packages instead of the above ones (successfully 
tested on Debian Sarge 3.1). Installation has to be done via "aptitude install"
(thanks to Marc Kiefer for this input):
- libpng3
- libpng3-dev
- libgd2
- libgd2-dev
- zlib1g
- zlib1g-dev

If you need DNS support or want to change the default language please refer to 
chapter 6. INSTALLATION INSTRUCTIONS FOR DNS, LANGUAGE AND 404 SUPPORT.

================================================================================

3. INSTALLATION INSTRUCTIONS FOR PATCH ONLY

a. Download the complete source distribution (tar/gzip-archive) of Webalizer 
   Version 2.01-10 (webalizer-2.01-10-src.tgz) from http://www.webalizer.com/ 
   into a directory on your server (e.g. /home/user/).

b. Download the patch for Webalizer (webalizer-2.01-10-RB19-patch.tar.gz) from 
   http://www.patrickfrei.ch/webalizer/ into the same directory where you have 
   already saved the Webalizer source code (e.g. /home/user/).

c. Extract the Webalizer source code (webalizer-2.01-10-src.tgz) and the
   Webalizer patch (webalizer-2.01-10-RB19-patch.tar.gz):
   # tar -xvzf webalizer-2.01-10-src.tgz
   # tar -xvzf webalizer-2.01-10-RB19-patch.tar.gz

d. Change to the directory of Webalizer:
   # cd webalizer-2.01-10/

e. Apply the Webalizer patch (webalizer-2.01-10-RB19-patch):
   # patch -Np1 -i ../webalizer-2.01-10-RB19-patch

f. Configure, compile and install the Webalizer (see chapter 5. INSTALLATION 
   INSTRUCTIONS FOR DNS, LANGUAGE AND 404 SUPPORT and chapter 6.  INSTALLATION 
   INSTRUCTIONS FOR GEOIP LIBRARY, too):
   # ./configure
   # make
   # make install

g. Adjust the configuration in /etc/webalizer.conf and run the Webalizer:
   # /usr/local/bin/webalizer

================================================================================

4. INSTALLATION INSTRUCTIONS FOR COMPLETE PATCHED SOURCE CODE

a. Download the patched Webalizer version (webalizer-2.01-10-RB19-src.tar.gz) 
   from http://www.patrickfrei.ch/webalizer/ into a directory on your server 
   (e.g. /home/user/).

b. Extract the patched source code (webalizer-2.01-10-RB19-src.tar.gz):
   # tar -xvzf webalizer-2.01-10-RB19-src.tar.gz

c. Change to the directory of the patched Webalizer version:
   # cd webalizer-2.01-10-RB19/

d. Configure, compile and install the Webalizer (see chapter 5. INSTALLATION 
   INSTRUCTIONS FOR DNS, LANGUAGE AND 404 SUPPORT and chapter 6. INSTALLATION 
   INSTRUCTIONS FOR GEOIP LIBRARY, too):
   # ./configure
   # make
   # make install

e. Adjust the configuration in /etc/webalizer.conf and run the Webalizer:
   # /usr/local/bin/webalizer

================================================================================

5. INSTALLATION INSTRUCTIONS FOR DNS, LANGUAGE AND HTTP-404-ERROR SUPPORT

a. DNS: If you'd like to enable DNS support for the Webalizer you additionally 
   need the following packages on your system:
   - db
   - db-devel
   - db40 (alternatively you can use 'db41' or 'db42')
   - db40-devel (alternatively you can use 'db41-devel' or 'db42-devel')
   
   DEBIAN users need the following packages instead of the above ones 
   (installation via aptitude install):
   - libdb4.2
   - libdb4.2-dev
   
   Furthermore you have to configure Webalizer for DNS support:
   # ./configure --enable-dns
   
   If you get a Webalizer configuration warning as...
   --> configure: warning: You must have a V1.85 compatable DB library!
   --> configure: warning: DNS lookup code will be disabled...
   ...you need to adjust the paths for db and dblib corresponding to your 
   system:
   E.g. if you installed db version 4.0.x:
   # ./configure --enable-dns --with-db=/usr/include/db40/ \
      --with-dblib=/usr/lib/
   E.g. if you installed db version 4.2.x:
   # ./configure --enable-dns --with-db=/usr/include/db42/ \
      --with-dblib=/usr/lib/
   
   Don't forget to adjust the configuration in /etc/webalizer.conf to enable the 
   DNS feature (Directives: DNSCache and DNSChildren).

b. LANGUAGE: If you'd like to change the default language you need the following 
   configuration directive (default 'language' is english):
   --with-language=language

c. 404 ERROR's: If you'd like to change the default value of 404 error entries 
   in the 404 error monthly table you can change that value with the 
   "CodeNotFound" keyword in /etc/webalizer.conf. Additionally all 404 errors 
   can be display on a separate HTML page with the keyword "AllErrors" (please 
   refer to the README of Webalizer Xtended for further information about the 
   new configuration keywords).
   
================================================================================

6. INSTALLATION INSTRUCTIONS FOR GEOIP LIBRARY SUPPORT

a. Download the latest "GeoLite Country Library"...
   http://www.maxmind.com/download/geoip/api/c/
   ...and install it (replace X with the correct version numbers):
   # tar -xvzf GeoIP-X.X.X.tar.gz
   # cd GeoIP-X.X.X/
   # ./configure
   # make
   # make check
   # make install
   
b. Download the latest "GeoLite Country Binary"...
   http://www.maxmind.com/download/geoip/database/
   ...and install it:
   # gunzip GeoIP.dat.gz
   # mkdir -p /usr/local/share/GeoIP/
   # cp GeoIP.dat /usr/local/share/GeoIP/
   # cd /usr/local/share/GeoIP/
   # chown 0:0 GeoIP.dat
   # chmod 0644 GeoIP.dat

c. Install Webalizer Xtended as described in chapter 3. or 4. but make sure
   you add at least the configuration parameter "--enable-geoip". Examples:
   1) GeoIP support only:
      # ./configure --enable-geoip
   2) GeoIP and DNS support:
      # ./configure --enable-geoip --enable-dns
   3) GeoIP, DNS and german language support:
      # ./configure --enable-geoip --enable-dns --with-language=german
   If you get a configuration warning concerning DNS support go to chapter 7a.

d. If you get an error check where you have installed the dependencies and use
   the configure parameters "--with-geoip-inc=" and "--with-geoip-lib=" 
   additionally.

e. Adjust the configuration in /etc/webalizer.conf if necessary by changing
   the keywords "GeoIP" and "GeoIPDatabase".
   
f. Make sure that the installation path of libGeoIP (usually /usr/local/lib) is 
   present in /etc/ld.so.conf. If it's not there add such a line. Then run:
   # ldconfig -v
   
   If you have no superuser access you may be unable to run "ldconfig -v". In 
   that case if you installed libGeoIP at "$HOME/lib" you can put the following
   line in your initialization scripts:
   
   * For bash:
     export LD_LIBRARY_PATH=$HOME/lib
   * For csh:
     setenv LD_LIBRARY_PATH $HOME/lib
   
g. NOTE: GeoLite Country is similar to the GeoIP Country database, but is not 
   as accurate. Should you require greater accuracy, GeoIP Country is a drop-in 
   replacement for GeoLite Country. You can download it (not for free) at
   http://www.maxmind.com/

================================================================================

7. INSTALLATION INSTRUCTIONS FOR APACHE MOD_LOGIO SUPPORT

   Webalizer Xtended can show detailed statistics about the number of bytes 
   received/sent per request on your website. The numbers reflect the actual 
   bytes as received on the network. This feature is provided by the Apache 
   module "mod_logio". See http://httpd.apache.org/docs/2.2/mod/mod_logio.html 
   for more details (Note: You can use this feature for all Apache versions).
   
   To enable the mod_logio feature you need...
   1) ...to enable the Apache module "mod_logio". This can be done while 
      building Apache (NOT Webalizer!) with:
         ./configure --enable-logio
      ...or with:
         ./configure --enable-modules=all
   2) ...to enable the logio-module in your Apache webserver configuration file 
      (generally called "httpd.conf"):
         LoadModule logio_module modules/mod_logio.so
   3) ...access to your Apache webserver configuration file (generally called
      "httpd.conf") in order to add / adjust the "LogFormat" and "CustomLog" 
      configuration directives as follows:
         LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" 
            %I %O" combinedio
	 CustomLog logs/access_log combinedio
   
   Note:
   If mod_logio is not enabled on your webserver, Webalizer Xtended will simply
   show "0 bytes" for incoming (Vol. In) and outgoing (Vol. Out) website 
   traffic. In that case you can hide the according two table columns by using 
   the configuration file keyword "HideInOutVolume".

================================================================================

8. KNOWN ISSUES

a. Note that Internet Explorer may rename Unix files to *.tar.tar while 
   downloading. If so, rename them to *.tar.gz before extracting.

b. DEBIAN SYSTEMS INSTALLATION: Some users reported a problem with 
   "make install". You may have this problem if you see the following error 
   after executing "make install":
   
   # /usr/bin/install -c webalizer /usr/local/bin/webalizer
   # /usr/bin/install -c -m 644 webalizer.1 /usr/local/man/man1/webalizer.1
   # /usr/bin/install: cannot create regular file 
     `/usr/local/man/man1/webalizer.1': No such file or directory
   # make: *** [install] Error 1

   To work around this create the following directories before executing 
   the command "make install":
   # mkdir /usr/local/man/man1/
   # mkdir /usr/local/man/man1/webalizer.1
   # mkdir /usr/local/bin

c. If compiling fails due to a missing package or another problem, you should
   delete the whole folder "webalizer-2.01-10" and extract the tar.gz again. 
   Otherwise even after installing a missing package you might get the same 
   compiling problems again because the configure script keeps some old 
   information stored in the "webalizer-2.01-10" folder (you can check that if 
   you execute the configure command and each line will additionally show the 
   comment "(cache)" at its end).

d. If you receive "Error: Unable to restore run data (15)" go to section 
   1. IMPORTANT NOTES ON UPGRADING FROM PRIOR VERSIONS in this manual.

e. Using gcc version 4 will show you a bunch of compiler warnings when compiling 
   Webalizer with 'make'. You can either safely ignore or suppress them by
   configuring Webalizer Xtended with:
   # CFLAGS="-Wno-pointer-sign" ./configure

================================================================================