Imported Upstream version 2.23.05

[hcoop/zz_old/debian/webalizer.git] / INSTALL

Installation instructions for The Webalizer

The Webalizer is distributed in either source or binary distributions,
and installation is different for each type.  Regardless of the type
of installation, you need to obtain and un-tar/un-zip the distribution.
For binary distributions, you should create a directory somewhere and
chdir to it before unpacking the file.  Source distributions will
automagically create a directory for you (webalizer-x.xx-xx).  If you
are upgrading from a previous version, check the CHANGES file, and the
README.FIRST file for important upgrade information.


For Binary distributions
------------------------

You should have all the files you need in the directory you created
when you un-tarred/un-zipped the distribution file.  The file
'webalizer' in this directory is the binary executable.  Copy this
someplace useful, like /usr/local/bin or /usr/bin.  A man page for
The Webalizer is also supplied... If desired, copy the file
'webalizer.1' to your local man directory (ie: /usr/local/man/man1).
(You may also need to run 'makeinfo' or similar)

Note: There may also be platform specific installation instructions
      and/or usage notes supplied with the binary distribution.  You
      should read them, as that will be your starting point if problems
      are encountered.  Most of the binary distributions are submitted
      by users, and I cannot support them the same way I can the
      Linux binary distribution and the source code itself.


For Source distributions
------------------------

The Webalizer requires, at a minimum, the GD graphics library
(http://www.libgd.org/), the PNG (portable network graphics)
graphics library ( http://www.libpng.org/pub/png/ ), the Zlib
compression library ( http://www.zlib.net/ ) and associated
header files for these libraries.  Most modern systems will have
these libraries, but may or may not have the required header files
for them unless you installed the 'dev' (development) versions
(which include the required header files along with the libraries).
Consult your systems documentation for specifics.

For native DNS and Geolocation (GeoDB) support, the Berkeley DB
library (by sleepycat, now owned by Oracle) v4.1 or higher and
associated header file is required.
http://www.oracle.com/technology/products/berkeley-db/

For BZip2 support, the bzip2 compression library and header file is
required. http://www.bzip.org/ 

For GeoIP geolocation support, the GeoIP library (by MaxMind, Inc.)
and header file is required, along with a Country Edition database.
http://www.maxmind.com/app/ip-location


New style build:

The Webalizer source distribution now comes packaged with a GNU
autoconf 'configure' script, which should allow you to simply type:

./configure
make
make install

Normal configure options apply, type ./configure --help to get a
complete list.  A few options in particular may be useful:

--sysconfdir=/etc

The sysconfdir switch specifies where the default configuration
file (webalizer.conf) should be looked for.  If not specified, the
default of ${prefix}/etc is used.

--with-language=<language>

Allows you to specify the language to use.  Check the /lang directory
to see the available language choices.  As an example, you could use

./configure --with-language=french

to compile the program using french (webalizer_lang.french) for output.
You can also use the --without-language switch, which will use the
default language (english).

--enable-dns

DNS lookup and native geolocation features are added if the required
library (libdb) and header file (db.h) are found.  DNS/GeoDB code is
enabled at compile time by using the -DUSE_DNS compiler switch.  For
GeoDB lookups, a current geodb database is also required (available
at ftp://ftp.mrunix.net/pub/webalizer/geodb).

--with-geodb=<path>

The default location for the GeoDB database is /usr/share/GeoDB but
may be changed using this option.

--enable-bz2

BZip2 compression support will be added if the required library
(libbz2) and header file (bzlib.h) are found.  BZip2 code is
enabled at compile time using the -DUSE_BZIP compiler switch.

--enable-geoip

GeoIP geolocation support will be added if the required library
(libGeoIP) and header file (GeoIP.h) are found.  No attempt is
made to locate a valid Country Edition database, which is also
required for GeoIP lookups to be performed.  GeoIP code is
enabled at compile time using the -DUSE_GEOIP compiler switch.

Some systems may require unusual settings that the configure script
cannot determine.  You can pass values to the script by setting
environment variables.  For example:

CC=c89 CFLAGS=-O LIBS=-lposix ./configure --with-language=german

Would allow you to set the compiler (c89) and various flags and
libraries to use, which would then be passed to the configure script
and eventually to the Makefile generated.  It also will cause the
program to be compiled using German instead of the English default.
Additionally, the various --with-<package> and --with-<packagelib>
options allow specification of non-standard locations for the
various libraries and headers.  For example, if you built the bzip2
library in /src/bzip2, you could use:

./configure --with-bz2=/src/bzip2 --with-bz2lib=/src/bzip2 --enable-bz2

to specify where the bz2 header files (--with-bz2) and library
(--with-bz2lib) are located.  They should then be detected by
the configure script and enabled.  Please note that if you are
linking against a shared library (ie: libbz2.so), then even though
configure script finds the library, and The Webalizer compiles
successfully, the program may FAIL when run because the systems
run-time linking loader cannot find the library.  If this happens,
then you need to tell the loader where the library is, and is
dependent upon what type system is being used.  Some platforms
require the path to the library to be placed in the LD_LIBRARY_PATH
environment variable.. some (such as linux based platforms) use
the ld.so.conf file and ldconfig program to configure the dynamic
linker run-time bindings.  Consult the documentation for your
system specific requirements.

For package maintainers, the environment variable DESTDIR can be
used to specify a root directory for installation.  This is the
top level directory under which all other directories will be
placed when 'make install' is invoked, and allows binary packages
to be easily built outside the normal root directory tree.  For
example, if you wish to build a binary package of The Webalizer
under the /usr/pkg/webalizer-2.20 directory, you could type:

make install DESTDIR=/usr/pkg/webalizer-2.20

Which would then create the following directory tree:

/usr/pkg/webalizer-2.20/
/usr/pkg/webalizer-2.20/etc/
/usr/pkg/webalizer-2.20/etc/webalizer.conf.sample
/usr/pkg/webalizer-2.20/usr/
/usr/pkg/webalizer-2.20/usr/bin/
/usr/pkg/webalizer-2.20/usr/bin/webalizer
/usr/pkg/webalizer-2.20/usr/bin/webazolver -> webalizer
/usr/pkg/webalizer-2.20/usr/bin/wcmgr
/usr/pkg/webalizer-2.20/usr/man/
/usr/pkg/webalizer-2.20/usr/man/man1/
/usr/pkg/webalizer-2.20/usr/man/man1/webalizer.1
/usr/pkg/webalizer-2.20/usr/man/man1/webazolver.1 -> webalizer.1
/usr/pkg/webalizer-2.20/usr/man/man1/wcmgr.1


If the configure script doesn't work for you.. please let me know
(along with relevant info like system type, compiler, etc..)  If you
are able and can tweak something to make it work, let me know as well.


Old style build:

If you have a platform that the configure script won't work on, or
some other situation where you have to configure and build the
source yourself,  the file 'Makefile.std' is a "stock" Makefile
that you can use to build the Webalizer.  Copy or rename the file
to 'Makefile', edit to match your system, and do the usual 'make'.
This is a very generic Makefile, so expect to have to tweak it for
your particular platform and configuration.  If everything seems
to have gone well, next type 'make install' to do a stock install.
Again, you may want to tweak the Makefile for the install, or
skip the 'make install' step completely (see below).

This will install the Webalizer on your system, and put a sample
configuration file in /etc (named 'webalizer.conf.sample').  If
you don't want to use the 'make install' method... just copy the
file 'webalizer' to someplace useful, and you are ready to go :)


Usage
-----

When run, The Webalizer will read the specified log file and
produce HTML output in the directory specified (or current
directory if none).  You may specify various configuration
options either on the command line or in a configuration file.
The format of the command line is:

webalizer [options] [log_file]

Where 'options' may be any of the valid command line options
described in the README file.  If a log filename is not given,
input is taken from stdin.  A typical command line might look
something similar to:

webalizer /var/lib/httpd/logs/access_log

This will produce output in the current directory based on the
logfile /var/lib/httpd/logs/access_log.  Another example:

webalizer -c somehost.conf

This will read the configuration file somehost.conf, which
should specify, among other things, the log filename and
output directory to use.  You can use 'webalizer -h' to get
a list of available command line options, or view the file
README for complete instructions on all available configuration
options.  You should note that The Webalizer will _always_
look for a configuration file named 'webalizer.conf' in either
the current directory or in /etc/, and will process that file
_before_ any other configuration or command line options.  If
you run a single server, you may want to create a default
configuration file and place it in the /etc/ directory.  This
will allow you to simply type 'webalizer' without the need to
specify additional command line options.


Configuration
-------------

The Webalizer can be customized in many ways using either the
command line or configuration files.  To test The Webalizer,
type: 'webalizer /var/lib/httpd/logs/access_log', changing the
directory to wherever your log files are.  After processing,
you should have the output and a file named index.html which
can be viewed with any browser.  The Webalizer can accept many
command line options as well, type 'webalizer -h' to view them.
In addition to the command line options, The Webalizer can
be customized using configuration files. There is a sample.conf
file that is part of both the source and binary distributions
that can be used as a 'template' for creating your own site
configuration file.  Just make a copy of the file and name it
something like 'mysite.conf'.  Edit the new file to match your
particular setup and taste.

To test the new configuration file, type 'webalizer -c mysite.conf'
(or whatever your configuration file is named).  Fire up the
browser and look at the results.  If you rename your new
configuration file to 'webalizer.conf', you will only need
to type 'webalizer', and The Webalizer will use it as the
default.  See the README file for more on configuration and
use of configuration files.


Language Support
----------------

Language support is provided as language specific header
files that must be compiled into the program.  If you don't
have the source code, get it.  If you can't compile the
program yourself, ask a friend.  The /lang/ directory of
the distribution contains all supported languages at the
time of release.  Additional/updated language files will
be found at ftp://ftp.webalizer.org/pub/webalizer/lang and
are always the most current versions.

To build with language support, use the --with-language
option of the configure script.  This will automagically
do for you the steps described below.  If you can't use
the configure script, you can manually select the language
file to use.

In the webalizer source directory, you will find a symbolic
link for the file webalizer_lang.h, and it will be pointing
to the file webalizer_lang.english which is the default.
Delete the link (ie: rm webalizer_lang.h) and create a new
one to the language file you want The Webalizer to use
(ie: ln -s lang/webalizer_lang.spanish webalizer_lang.h)
and re-compile the program.

Note: The source distribution of The Webalizer contains all
      language support files that were available at the time.
      Additional/updated language files can be found at:
      ftp://ftp.webalizer.org/pub/webalizer/lang where I will
      put them as I receive them.


Common Questions
----------------

Q: Will it run on [some platform]
A: If it is a *nix platform, it should without a problem.  If it's
   something different, probably not and your on your own if you
   want to try to make it work.

Q: When I compile, I get "file not found" errors?
A: Most likely, the compiler cant find the header files for one
   the required libraries.  If they are someplace other than the
   standard locations (ie: /usr/include), then you  probably need
   to specify an alternate location to look using one of the
   --with-<package> command line switches when you run configure,
   or edit the Makefile and specify the location with an '-I<path>'
   compiler flag.

Q: I get "libgd not found' errors?
A: You don't have the GD graphics located in a standard library
   path, or you don't have the GD graphics library at all.  If
   the later, go to http://www.boutell.com/gd/ and grab a copy.
   If you do have it, add a -L switch in the Makefile to point
   to the proper location.

Q: I get unresolved symbol errors when compiling, why?
A: This most often occurs when the GD library was built with
   additional support for such things as TrueType fonts or
   X11 graphics.  The configure script for The Webalizer only
   checks that the gd library is available, and does not check
   any other dependencies it may have.  Typically, to fix this
   problem, you need to edit the Makefile and add the dependent
   libraries to a compiler switch (or pass them on the command
   line when running the configure script).  For example, if
   you are getting errors about not finding truetype routines,
   you may need to add '-lttf' (for 'libttf', the truetype library)
   to the "LIBS" variable.

   Hint: I usually find it easier to just grab the GD library
         source, and compile it myself locally as a static
         library, in a directory just above where I compile The
         Webalizer.  Then, at configure time, just add the
         '-with-gd=../gd' and '--with-gdlib=../gd' switches,
         and the GD graphic stuff will be statically linked into
         The Webalizer, eliminating any other library dependencies
         that the normal, shared library on my system may have.