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