Imported Debian patch 2.23.05-1
[hcoop/zz_old/debian/webalizer.git] / INSTALL
1Installation instructions for The Webalizer
3The Webalizer is distributed in either source or binary distributions,
4and installation is different for each type. Regardless of the type
5of installation, you need to obtain and un-tar/un-zip the distribution.
6For binary distributions, you should create a directory somewhere and
7chdir to it before unpacking the file. Source distributions will
8automagically create a directory for you (webalizer-x.xx-xx). If you
9are upgrading from a previous version, check the CHANGES file, and the
10README.FIRST file for important upgrade information.
13For Binary distributions
16You should have all the files you need in the directory you created
17when you un-tarred/un-zipped the distribution file. The file
18'webalizer' in this directory is the binary executable. Copy this
19someplace useful, like /usr/local/bin or /usr/bin. A man page for
20The Webalizer is also supplied... If desired, copy the file
21'webalizer.1' to your local man directory (ie: /usr/local/man/man1).
22(You may also need to run 'makeinfo' or similar)
24Note: There may also be platform specific installation instructions
25 and/or usage notes supplied with the binary distribution. You
26 should read them, as that will be your starting point if problems
27 are encountered. Most of the binary distributions are submitted
28 by users, and I cannot support them the same way I can the
29 Linux binary distribution and the source code itself.
32For Source distributions
35The Webalizer requires, at a minimum, the GD graphics library
36(, the PNG (portable network graphics)
37graphics library ( ), the Zlib
38compression library ( ) and associated
39header files for these libraries. Most modern systems will have
40these libraries, but may or may not have the required header files
41for them unless you installed the 'dev' (development) versions
42(which include the required header files along with the libraries).
43Consult your systems documentation for specifics.
45For native DNS and Geolocation (GeoDB) support, the Berkeley DB
46library (by sleepycat, now owned by Oracle) v4.1 or higher and
47associated header file is required.
50For BZip2 support, the bzip2 compression library and header file is
53For GeoIP geolocation support, the GeoIP library (by MaxMind, Inc.)
54and header file is required, along with a Country Edition database.
58New style build:
60The Webalizer source distribution now comes packaged with a GNU
61autoconf 'configure' script, which should allow you to simply type:
65make install
67Normal configure options apply, type ./configure --help to get a
68complete list. A few options in particular may be useful:
72The sysconfdir switch specifies where the default configuration
73file (webalizer.conf) should be looked for. If not specified, the
74default of ${prefix}/etc is used.
78Allows you to specify the language to use. Check the /lang directory
79to see the available language choices. As an example, you could use
81./configure --with-language=french
83to compile the program using french (webalizer_lang.french) for output.
84You can also use the --without-language switch, which will use the
85default language (english).
89DNS lookup and native geolocation features are added if the required
90library (libdb) and header file (db.h) are found. DNS/GeoDB code is
91enabled at compile time by using the -DUSE_DNS compiler switch. For
92GeoDB lookups, a current geodb database is also required (available
97The default location for the GeoDB database is /usr/share/GeoDB but
98may be changed using this option.
102BZip2 compression support will be added if the required library
103(libbz2) and header file (bzlib.h) are found. BZip2 code is
104enabled at compile time using the -DUSE_BZIP compiler switch.
108GeoIP geolocation support will be added if the required library
109(libGeoIP) and header file (GeoIP.h) are found. No attempt is
110made to locate a valid Country Edition database, which is also
111required for GeoIP lookups to be performed. GeoIP code is
112enabled at compile time using the -DUSE_GEOIP compiler switch.
114Some systems may require unusual settings that the configure script
115cannot determine. You can pass values to the script by setting
116environment variables. For example:
118CC=c89 CFLAGS=-O LIBS=-lposix ./configure --with-language=german
120Would allow you to set the compiler (c89) and various flags and
121libraries to use, which would then be passed to the configure script
122and eventually to the Makefile generated. It also will cause the
123program to be compiled using German instead of the English default.
124Additionally, the various --with-<package> and --with-<packagelib>
125options allow specification of non-standard locations for the
126various libraries and headers. For example, if you built the bzip2
127library in /src/bzip2, you could use:
129./configure --with-bz2=/src/bzip2 --with-bz2lib=/src/bzip2 --enable-bz2
131to specify where the bz2 header files (--with-bz2) and library
132(--with-bz2lib) are located. They should then be detected by
133the configure script and enabled. Please note that if you are
134linking against a shared library (ie:, then even though
135configure script finds the library, and The Webalizer compiles
136successfully, the program may FAIL when run because the systems
137run-time linking loader cannot find the library. If this happens,
138then you need to tell the loader where the library is, and is
139dependent upon what type system is being used. Some platforms
140require the path to the library to be placed in the LD_LIBRARY_PATH
141environment variable.. some (such as linux based platforms) use
142the file and ldconfig program to configure the dynamic
143linker run-time bindings. Consult the documentation for your
144system specific requirements.
146For package maintainers, the environment variable DESTDIR can be
147used to specify a root directory for installation. This is the
148top level directory under which all other directories will be
149placed when 'make install' is invoked, and allows binary packages
150to be easily built outside the normal root directory tree. For
151example, if you wish to build a binary package of The Webalizer
152under the /usr/pkg/webalizer-2.20 directory, you could type:
154make install DESTDIR=/usr/pkg/webalizer-2.20
156Which would then create the following directory tree:
164/usr/pkg/webalizer-2.20/usr/bin/webazolver -> webalizer
169/usr/pkg/webalizer-2.20/usr/man/man1/webazolver.1 -> webalizer.1
173If the configure script doesn't work for you.. please let me know
174(along with relevant info like system type, compiler, etc..) If you
175are able and can tweak something to make it work, let me know as well.
178Old style build:
180If you have a platform that the configure script won't work on, or
181some other situation where you have to configure and build the
182source yourself, the file 'Makefile.std' is a "stock" Makefile
183that you can use to build the Webalizer. Copy or rename the file
184to 'Makefile', edit to match your system, and do the usual 'make'.
185This is a very generic Makefile, so expect to have to tweak it for
186your particular platform and configuration. If everything seems
187to have gone well, next type 'make install' to do a stock install.
188Again, you may want to tweak the Makefile for the install, or
189skip the 'make install' step completely (see below).
191This will install the Webalizer on your system, and put a sample
192configuration file in /etc (named 'webalizer.conf.sample'). If
193you don't want to use the 'make install' method... just copy the
194file 'webalizer' to someplace useful, and you are ready to go :)
200When run, The Webalizer will read the specified log file and
201produce HTML output in the directory specified (or current
202directory if none). You may specify various configuration
203options either on the command line or in a configuration file.
204The format of the command line is:
206webalizer [options] [log_file]
208Where 'options' may be any of the valid command line options
209described in the README file. If a log filename is not given,
210input is taken from stdin. A typical command line might look
211something similar to:
213webalizer /var/lib/httpd/logs/access_log
215This will produce output in the current directory based on the
216logfile /var/lib/httpd/logs/access_log. Another example:
218webalizer -c somehost.conf
220This will read the configuration file somehost.conf, which
221should specify, among other things, the log filename and
222output directory to use. You can use 'webalizer -h' to get
223a list of available command line options, or view the file
224README for complete instructions on all available configuration
225options. You should note that The Webalizer will _always_
226look for a configuration file named 'webalizer.conf' in either
227the current directory or in /etc/, and will process that file
228_before_ any other configuration or command line options. If
229you run a single server, you may want to create a default
230configuration file and place it in the /etc/ directory. This
231will allow you to simply type 'webalizer' without the need to
232specify additional command line options.
238The Webalizer can be customized in many ways using either the
239command line or configuration files. To test The Webalizer,
240type: 'webalizer /var/lib/httpd/logs/access_log', changing the
241directory to wherever your log files are. After processing,
242you should have the output and a file named index.html which
243can be viewed with any browser. The Webalizer can accept many
244command line options as well, type 'webalizer -h' to view them.
245In addition to the command line options, The Webalizer can
246be customized using configuration files. There is a sample.conf
247file that is part of both the source and binary distributions
248that can be used as a 'template' for creating your own site
249configuration file. Just make a copy of the file and name it
250something like 'mysite.conf'. Edit the new file to match your
251particular setup and taste.
253To test the new configuration file, type 'webalizer -c mysite.conf'
254(or whatever your configuration file is named). Fire up the
255browser and look at the results. If you rename your new
256configuration file to 'webalizer.conf', you will only need
257to type 'webalizer', and The Webalizer will use it as the
258default. See the README file for more on configuration and
259use of configuration files.
262Language Support
265Language support is provided as language specific header
266files that must be compiled into the program. If you don't
267have the source code, get it. If you can't compile the
268program yourself, ask a friend. The /lang/ directory of
269the distribution contains all supported languages at the
270time of release. Additional/updated language files will
271be found at and
272are always the most current versions.
274To build with language support, use the --with-language
275option of the configure script. This will automagically
276do for you the steps described below. If you can't use
277the configure script, you can manually select the language
278file to use.
280In the webalizer source directory, you will find a symbolic
281link for the file webalizer_lang.h, and it will be pointing
282to the file webalizer_lang.english which is the default.
283Delete the link (ie: rm webalizer_lang.h) and create a new
284one to the language file you want The Webalizer to use
285(ie: ln -s lang/webalizer_lang.spanish webalizer_lang.h)
286and re-compile the program.
288Note: The source distribution of The Webalizer contains all
289 language support files that were available at the time.
290 Additional/updated language files can be found at:
291 where I will
292 put them as I receive them.
295Common Questions
298Q: Will it run on [some platform]
299A: If it is a *nix platform, it should without a problem. If it's
300 something different, probably not and your on your own if you
301 want to try to make it work.
303Q: When I compile, I get "file not found" errors?
304A: Most likely, the compiler cant find the header files for one
305 the required libraries. If they are someplace other than the
306 standard locations (ie: /usr/include), then you probably need
307 to specify an alternate location to look using one of the
308 --with-<package> command line switches when you run configure,
309 or edit the Makefile and specify the location with an '-I<path>'
310 compiler flag.
312Q: I get "libgd not found' errors?
313A: You don't have the GD graphics located in a standard library
314 path, or you don't have the GD graphics library at all. If
315 the later, go to and grab a copy.
316 If you do have it, add a -L switch in the Makefile to point
317 to the proper location.
319Q: I get unresolved symbol errors when compiling, why?
320A: This most often occurs when the GD library was built with
321 additional support for such things as TrueType fonts or
322 X11 graphics. The configure script for The Webalizer only
323 checks that the gd library is available, and does not check
324 any other dependencies it may have. Typically, to fix this
325 problem, you need to edit the Makefile and add the dependent
326 libraries to a compiler switch (or pass them on the command
327 line when running the configure script). For example, if
328 you are getting errors about not finding truetype routines,
329 you may need to add '-lttf' (for 'libttf', the truetype library)
330 to the "LIBS" variable.
332 Hint: I usually find it easier to just grab the GD library
333 source, and compile it myself locally as a static
334 library, in a directory just above where I compile The
335 Webalizer. Then, at configure time, just add the
336 '-with-gd=../gd' and '--with-gdlib=../gd' switches,
337 and the GD graphic stuff will be statically linked into
338 The Webalizer, eliminating any other library dependencies
339 that the normal, shared library on my system may have.