| 1 | Installation instructions for The Webalizer |
| 2 | |
| 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. |
| 11 | |
| 12 | |
| 13 | For Binary distributions |
| 14 | ------------------------ |
| 15 | |
| 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) |
| 23 | |
| 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. |
| 30 | |
| 31 | |
| 32 | For Source distributions |
| 33 | ------------------------ |
| 34 | |
| 35 | The Webalizer requires, at a minimum, the GD graphics library |
| 36 | (http://www.libgd.org/), the PNG (portable network graphics) |
| 37 | graphics library ( http://www.libpng.org/pub/png/ ), the Zlib |
| 38 | compression library ( http://www.zlib.net/ ) 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. |
| 44 | |
| 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. |
| 48 | http://www.oracle.com/technology/products/berkeley-db/ |
| 49 | |
| 50 | For BZip2 support, the bzip2 compression library and header file is |
| 51 | required. http://www.bzip.org/ |
| 52 | |
| 53 | For GeoIP geolocation support, the GeoIP library (by MaxMind, Inc.) |
| 54 | and header file is required, along with a Country Edition database. |
| 55 | http://www.maxmind.com/app/ip-location |
| 56 | |
| 57 | |
| 58 | New style build: |
| 59 | |
| 60 | The Webalizer source distribution now comes packaged with a GNU |
| 61 | autoconf 'configure' script, which should allow you to simply type: |
| 62 | |
| 63 | ./configure |
| 64 | make |
| 65 | make install |
| 66 | |
| 67 | Normal configure options apply, type ./configure --help to get a |
| 68 | complete list. A few options in particular may be useful: |
| 69 | |
| 70 | --sysconfdir=/etc |
| 71 | |
| 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. |
| 75 | |
| 76 | --with-language=<language> |
| 77 | |
| 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 |
| 80 | |
| 81 | ./configure --with-language=french |
| 82 | |
| 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). |
| 86 | |
| 87 | --enable-dns |
| 88 | |
| 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 ftp://ftp.mrunix.net/pub/webalizer/geodb). |
| 94 | |
| 95 | --with-geodb=<path> |
| 96 | |
| 97 | The default location for the GeoDB database is /usr/share/GeoDB but |
| 98 | may be changed using this option. |
| 99 | |
| 100 | --enable-bz2 |
| 101 | |
| 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. |
| 105 | |
| 106 | --enable-geoip |
| 107 | |
| 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. |
| 113 | |
| 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: |
| 117 | |
| 118 | CC=c89 CFLAGS=-O LIBS=-lposix ./configure --with-language=german |
| 119 | |
| 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: |
| 128 | |
| 129 | ./configure --with-bz2=/src/bzip2 --with-bz2lib=/src/bzip2 --enable-bz2 |
| 130 | |
| 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: libbz2.so), 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 ld.so.conf file and ldconfig program to configure the dynamic |
| 143 | linker run-time bindings. Consult the documentation for your |
| 144 | system specific requirements. |
| 145 | |
| 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: |
| 153 | |
| 154 | make install DESTDIR=/usr/pkg/webalizer-2.20 |
| 155 | |
| 156 | Which would then create the following directory tree: |
| 157 | |
| 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 |
| 171 | |
| 172 | |
| 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. |
| 176 | |
| 177 | |
| 178 | Old style build: |
| 179 | |
| 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). |
| 190 | |
| 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 :) |
| 195 | |
| 196 | |
| 197 | Usage |
| 198 | ----- |
| 199 | |
| 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: |
| 205 | |
| 206 | webalizer [options] [log_file] |
| 207 | |
| 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: |
| 212 | |
| 213 | webalizer /var/lib/httpd/logs/access_log |
| 214 | |
| 215 | This will produce output in the current directory based on the |
| 216 | logfile /var/lib/httpd/logs/access_log. Another example: |
| 217 | |
| 218 | webalizer -c somehost.conf |
| 219 | |
| 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. |
| 233 | |
| 234 | |
| 235 | Configuration |
| 236 | ------------- |
| 237 | |
| 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. |
| 252 | |
| 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. |
| 260 | |
| 261 | |
| 262 | Language Support |
| 263 | ---------------- |
| 264 | |
| 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 ftp://ftp.webalizer.org/pub/webalizer/lang and |
| 272 | are always the most current versions. |
| 273 | |
| 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. |
| 279 | |
| 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. |
| 287 | |
| 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 | ftp://ftp.webalizer.org/pub/webalizer/lang where I will |
| 292 | put them as I receive them. |
| 293 | |
| 294 | |
| 295 | Common Questions |
| 296 | ---------------- |
| 297 | |
| 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. |
| 302 | |
| 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. |
| 311 | |
| 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 http://www.boutell.com/gd/ and grab a copy. |
| 316 | If you do have it, add a -L switch in the Makefile to point |
| 317 | to the proper location. |
| 318 | |
| 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. |
| 331 | |
| 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. |
| 340 | |