webalizer.1

   1 .TH webalizer 1 "12-Jul-2008" "Version 2.20" "The Webalizer"
   2 .SH NAME
   3 webalizer - A web server log file analysis tool.
   4 .SH SYNOPSIS
   5 .B webalizer
   6 [\fI option ... \fP] [\fI log-file \fP]
   7 .PP
   8 .B webazolver
   9 [\fI option ... \fP] [\fI log-file \fP]
  10 .PP
  11 .SH DESCRIPTION
  12 The \fIWebalizer\fP is a web server log file analysis program which produces
  13 usage statistics in HTML format for viewing with a browser.  The results
  14 are presented in both columnar and graphical format, which facilitates
  15 interpretation.  Yearly, monthly, daily and hourly usage statistics are
  16 presented, along with the ability to display usage by site, URL, referrer,
  17 user agent (browser), username, search strings, entry/exit pages,  and
  18 country (some information may not be available if not present in the log
  19 file being processed).
  20 .PP
  21 The \fIWebalizer\fP supports \fBCLF\fP (common log format) log files,
  22 as well as \fBCombined\fP log formats as defined by NCSA and others,
  23 and variations of these which it attempts to handle intelligently.  In
  24 addition, the \fIWebalizer\fP supports \fBxferlog\fP formatted (\fIFTP\fP)
  25 log files, \fBsquid\fP proxy logs and \fBW3C\fP extended format logs.
  26 Logs may also be compressed, via \fIgzip\fP (.gz) or, if enabled at compile
  27 time, \fIbzip2\fP (.bz2).  If a compressed log file is detected, it will be
  28 automatically uncompressed while it is read.  Compressed logs must have the
  29 standard \fIgzip\fP extension of \fB.gz\fP or \fIbzip2\fP extension of
  30 \fB.bz2\fP.
  31 .PP
  32 \fIwebazolver\fP is normally just a symbolic link to the \fIWebalizer\fP.
  33 When run as \fIwebazolver\fP, only DNS file creation/updates are performed,
  34 and the program will exit once complete.  All normal options and
  35 configuration directives are available, however many will not be used.
  36 In addition, a DNS cache file must be specified.  If the number of DNS
  37 children processes to use are not specified, the \fIwebazolver\fP will
  38 default to \fB5\fP.
  39 .PP
  40 This documentation applies to The Webalizer Version 2.20
  41 .SH RUNNING THE WEBALIZER
  42 The \fIWebalizer\fP was designed to be run from a Unix command line prompt or
  43 as a \fBcrond(8)\fP job. Once executed, the general flow of the program is:
  44 .TP 8
  45 .B o
  46 A default configuration file is scanned for.  A file named
  47 \fIwebalizer.conf\fP is searched for in the current directory, and if
  48 found, it's configuration data is parsed.  If the file is not
  49 present in the current directory,  the file \fI/etc/webalizer.conf\fP
  50 is searched for and, if found, is used instead.
  51 .TP 8
  52 .B o
  53 Any command line arguments given to the program are parsed.  This
  54 may include the specification of a configuration file, which is
  55 processed at the time it is encountered.
  56 .TP 8
  57 .B o
  58 If a log file was specified, it is opened and made ready for
  59 processing.  If no log file was given, \fISTDIN\fP is used for input.
  60 If the log filename '\fB-\fP' is specified, \fISTDIN\fP will be forced.
  61 .TP 8
  62 .B o
  63 If an output directory was specified, the program does a \fBchdir(2)\fP to
  64 that directory in preparation for generating output.  If no output
  65 directory was given, the current directory is used.
  66 .TP 8
  67 .B o
  68 If a non-zero number of DNS Children processes were specified, they will
  69 be started, and the specified log file will be processed, creating or
  70 updating the specified DNS cache file.
  71 .TP 8
  72 .B o
  73 If no hostname was given, the program attempts to get the hostname
  74 using a \fBuname(2)\fP system call.  If that fails, \fIlocalhost\fP
  75 is used.
  76 .TP 8
  77 .B o
  78 A history file is searched for in the current directory (output
  79 directory) and read if found.  This file keeps totals for previous
  80 months, which is used in the main \fIindex.html\fP HTML document.
  81 .B Note:
  82 The file location can now be specified with the \fIHistoryName\fP
  83 configuration option.
  84 .TP 8
  85 .B o
  86 If incremental processing was specified, a data file is searched for
  87 and loaded if found, containing the 'internal state' data of the
  88 program at the end of a previous run.
  89 .B Note:
  90 The file location can now be specified with the \fIIncrementalName\fP
  91 configuration option.
  92 .TP 8
  93 .B o
  94 Main processing begins on the log file.  If the log spans multiple
  95 months, a separate HTML document is created for each month.
  96 .TP 8
  97 .B o
  98 After main processing, the main \fIindex.html\fP page is created, which
  99 has totals by month and links to each months HTML document.
 100 .TP 8
 101 .B o
 102 A new history file is saved to disk, which includes totals generated
 103 by The \fIWebalizer\fP during the current run.
 104 .TP 8
 105 .B o
 106 If incremental processing was specified, a data file is written that
 107 contains the 'internal state' data at the end of this run.
 108 .SH INCREMENTAL PROCESSING
 109 The \fIWebalizer\fP supports incremental run capability.  Simply
 110 put, this allows processing large log files by breaking them up into
 111 smaller pieces, and processing these pieces instead.  What this means
 112 in real terms is that you can now rotate your log files as often as you
 113 want, and still be able to produce monthly usage statistics without the
 114 loss of any detail.  Basically, The \fIWebalizer\fP saves and restores all
 115 internal data in a file named \fIwebalizer.current\fP.  This allows the
 116 program to 'start where it left off' so to speak, and allows the
 117 preservation of detail from one run to the next.  The data file is
 118 placed in the current output directory, and is a plain ASCII text
 119 file that can be viewed with any standard text editor.  It's location
 120 and name may be changed using the \fIIncrementalName\fP configuration
 121 keyword.
 122 .PP
 123 Some special precautions need to be taken when using the incremental
 124 run capability of The \fIWebalizer\fP.  Configuration options should not be
 125 changed between runs, as that could cause corruption of the internal
 126 data stored.  For example, changing the \fIMangleAgents\fP level will cause
 127 different representations of user agents to be stored, producing invalid
 128 results in the user agents section of the report.  If you need to change
 129 configuration options, do it at the end of the month after normal
 130 processing of the previous month and before processing the current month.
 131 You may also want to delete the \fIwebalizer.current\fP file as well.
 132 .PP
 133 The \fIWebalizer\fP also attempts to prevent data duplication by keeping
 134 track of the timestamp of the last record processed.  This timestamp
 135 is then compared to current records being processed, and any records
 136 that were logged previous to that timestamp are ignored.  This, in
 137 theory, should allow you to re-process logs that have already been
 138 processed, or process logs that contain a mix of processed/not yet
 139 processed records, and not produce duplication of statistics.  The
 140 only time this may break is if you have duplicate timestamps in two
 141 separate log files... any records in the second log file that do have
 142 the same timestamp as the last record in the previous log file processed,
 143 will be discarded as if they had already been processed.  There are
 144 lots of ways to prevent this however, for example, stopping the web
 145 server before rotating logs will prevent this situation.  This setup
 146 also necessitates that you always process logs in chronological order,
 147 otherwise data loss will occur as a result of the timestamp compare.
 148 .SH REVERSE DNS LOOKUPS
 149 The \fIWebalizer\fP fully supports IPv4 and IPv6 DNS lookups, and
 150 maintains a cache of those lookups to reduce processing the same
 151 addresses in subsequent runs.  The cache file can be created at
 152 run-time, or may be created before running the webalizer using either
 153 the stand alone '\fIwebazolver\fP' program, or The Webalizer (DNS)
 154 Cache file manager program '\fIwcmgr\fP'.  In order to perform reverse
 155 lookups, a \fBDNSCache\fP file must be specified, either on the command
 156 line or in a configuration file.  In order to create/update the cache
 157 file at run-time, the number of \fBDNSChildren\fP must also be specified,
 158 and can be anything between 1 and 100.  This specifies the number of
 159 child processes to be forked, each of which will perform network DNS
 160 queries in order to lookup up the addresses and update the cache.
 161 Cached entries that are older than a specified TTL (time to live)
 162 will be expired, and if encountered again in a log, will be looked
 163 up at that time in order to 'freshen' them (verify the name is still
 164 the same and update its timestamp).  The default TTL is 7 days, however
 165 may be set to anything between 1 and 100 days.  Using the '\fIwcmgr\fP'
 166 program, entries may also be marked as 'permanent', in which case
 167 they will persist (with an infinite TTL) in the cache until manually
 168 removed.  See the file \fBDNS.README\fP for additional information
 169 and examples.
 170 .SH GEOLOCATION LOOKUPS
 171 The \fIWebalizer\fP has the ability to perform geolocation lookups on
 172 IP addresses using either it's own internal \fIGeoDB\fP database,  or
 173 optionally the \fIGeoIP\fP database from MaxMind, Inc. (www.maxmind.com).
 174 If used, unresolved addresses will be searched for in the database and
 175 its country of origin will be returned if found.  This actually produces
 176 more accurate \fICountry\fP information than DNS lookups, since the DNS
 177 address space has additional \fIgcTLDs\fP that do not necessarily map
 178 to a specific country (such as \fI.net\fP and \fI.com\fP).  It is possible
 179 to use both DNS lookups and geolocation lookups at the same time, which
 180 will cause any addresses that could not be resolved using DNS lookups to
 181 then be looked up in the database, greatly reducing the number of
 182 \fIUnknown/Unresolved\fP entries in the generated reports.  The native
 183 \fIGeoDB\fP geolocation database provided by The \fIWebalizer\fP fully
 184 supports both \fIIPv4\fP and \fIIPv6\fP lookups, is updated regularly and
 185 is the preferred geolocation method for use with The \fIWebalizer\fP.  The
 186 most current version of the database can be obtained from our ftp site
 187 (\fIftp://ftp.mrunix.net/\fP).
 188 .SH COMMAND LINE OPTIONS
 189 The \fIWebalizer\fP supports many different configuration options that will
 190 alter the way the program behaves and generates output.  Most of these
 191 can be specified on the command line, while some can only be specified
 192 in a configuration file. The command line options are listed below,
 193 with references to the corresponding configuration file keywords.
 194 .PP
 195 .I General Options
 196 .TP 8
 197 .B \-h
 198 Display all available command line options and exit program.
 199 .TP 8
 200 .B \-v
 201 Be verbose.  Will cause the program to output informational
 202 and \fIDebug\fP messages at run-time.
 203 .TP 8
 204 .B \-V
 205 Display the program version and exit.  Additional program specific
 206 information will be displayed if \fIverbose\fP mode is also used
 207 (e.g. '\fI-vV\fP'), which can be useful when submitting bug reports.
 208 .TP 8
 209 .B \-d
 210 \fBDebug\fP.  Display debugging information for errors and warnings.
 211 .TP 8
 212 .B \-i
 213 \fBIgnoreHist\fP.  Ignore history.  \fBUSE WITH CAUTION\fP. This
 214 will cause The \fIWebalizer\fP to ignore any previous monthly history
 215 file only.  Incremental data (if present) is still processed.
 216 .TP 8
 217 .B \-b
 218 \fBIgnoreState\fP.  Ignore incremental data file.  \fBUSE WITH CAUTION\fP.
 219 This will cause The \fIWebalizer\fP to ignore any existing incremental
 220 data file.  By ignoring the incremental data file, all previous processing
 221 for the current month will be lost and those logs must be re-processed.
 222 .TP 8
 223 .B \-p
 224 \fBIncremental\fP.  Preserve internal data between runs.
 225 .TP 8
 226 .B \-q
 227 \fBQuiet\fP.  Suppress informational messages.  Does not suppress
 228 warnings or errors.
 229 .TP 8
 230 .B \-Q
 231 \fBReallyQuiet\fP.  Suppress all messages including warnings and errors.
 232 .TP 8
 233 .B \-T
 234 \fBTimeMe\fP.  Force display of timing information at end of processing.
 235 .TP 8
 236 .B \-c \fIfile\fP
 237 Use configuration file \fIfile\fP.
 238 .TP 8
 239 .B \-n \fIname\fP
 240 \fBHostName\fP.  Use the hostname \fIname\fP.
 241 .TP 8
 242 .B \-o \fIdir\fP
 243 \fBOutputDir\fP.  Use output directory \fIdir\fP.
 244 .TP 8
 245 .B \-t \fIname\fP
 246 \fBReportTitle\fP.  Use \fIname\fP for report title.
 247 .TP 8
 248 .B \-F \fP( \fBc\fPlf | \fBf\fPtp | \fBs\fPquid | \fBw\fP3c )
 249 \fBLogType\fP.  Specify log type to be processed.  Value can be either
 250 \fIc\fPlf, \fIf\fPtp, \fIs\fPquid or \fIw\fP3c format.  If not specified,
 251 will default to \fBCLF\fP format.  \fIFTP\fP logs must be in standard
 252 wu-ftpd \fIxferlog\fP format.
 253 .TP 8
 254 .B \-f
 255 \fBFoldSeqErr\fP.  Fold out of sequence log records back into analysis,
 256 by treating as if they were the same date/time as the last good record.
 257 Normally, out of sequence log records are simply ignored.
 258 .TP 8
 259 .B \-Y
 260 \fBCountryGraph\fP. Suppress country graph.
 261 .TP 8
 262 .B \-G
 263 \fBHourlyGraph\fP.  Suppress hourly graph.
 264 .TP 8
 265 .B \-x \fIname\fP
 266 \fBHTMLExtension\fP.  Defines HTML file extension to use.  If not
 267 specified, defaults to \fIhtml\fP.  Do not include the leading
 268 period.
 269 .TP 8
 270 .B \-H
 271 \fBHourlyStats\fP.  Suppress hourly statistics.
 272 .TP 8
 273 .B \-K \fInum\fP
 274 \fBIndexMonths\fP.  Specify how many months should be displayed in the
 275 main index (yearly summary) table.  Default is 12 months.  Can be set
 276 to anything between 12 and 120 months (1 to 10 years).
 277 .TP 8
 278 .B \-k \fInum\fP
 279 \fBGraphMonths\fP.  Specify how many months should be displayed in the
 280 main index (yearly summary) graph.  Default is 12 months.  Can be set
 281 to anything between 12 and 72 months (1 to 6 years).
 282 .TP 8
 283 .B \-L
 284 \fBGraphLegend\fP.  Suppress color coded graph legends.
 285 .TP 8
 286 .B \-l \fInum\fP
 287 \fBGraphLines\fP.  Specify number of background lines. Default
 288 is 2.  Use zero ('0') to disable the lines.
 289 .TP 8
 290 .B \-P \fIname\fP
 291 \fBPageType\fP.  Specify file extensions that are considered \fIpages\fP.
 292 Sometimes referred to as \fIpageviews\fP.
 293 .TP 8
 294 .B \-O \fIname\fP
 295 \fBOmitPage\fP.  Specify URLs to exclude from being counted as \fIpages\fP.
 296 .TP 8
 297 .B \-m \fInum\fP
 298 \fBVisitTimeout\fP.  Specify the Visit timeout period.  Specified in
 299 number of seconds.  Default is 1800 seconds (30 minutes).
 300 .TP 8
 301 .B \-I \fIname\fP
 302 \fBIndexAlias\fP.  Use the filename \fIname\fP as an additional alias
 303 for \fIindex.\fP.
 304 .TP 8
 305 .B \-M \fInum\fP
 306 \fBMangleAgents\fP.  Mangle user agent names according to the mangle
 307 level specified by \fInum\fP.  Mangle levels are:
 308 .RS
 309 .TP 12
 310 .B 5
 311 Browser name and major version.
 312 .TP 12
 313 .B 4
 314 Browser name, major and minor version.
 315 .TP 12
 316 .B 3
 317 Browser name, major version, minor version to two decimal places.
 318 .TP 12
 319 .B 2
 320 Browser name, major and minor versions and sub-version.
 321 .TP 12
 322 .B 1
 323 Browser name, version and machine type if possible.
 324 .TP 12
 325 .B 0
 326 All information (left unchanged).
 327 .RE
 328 .TP 8
 329 .B \-g \fInum\fP
 330 \fBGroupDomains\fP. Automatically group sites by domain.  The
 331 grouping level specified by \fInum\fP can be thought of as 'the
 332 number of dots' to display in the grouping.  The default value
 333 of \fB0\fP disables any domain grouping.
 334 .TP 8
 335 .B \-D \fIname\fP
 336 \fBDNSCache\fP.  Use the DNS cache file \fIname\fP.
 337 .TP 8
 338 .B \-N \fInum\fP
 339 \fBDNSChildren\fP.  Use \fInum\fP DNS children processes to perform DNS
 340 lookups, either creating or updating the DNS cache file.  Specify zero
 341 (\fB0\fP) to disable cache file creation/updates.  If given, a DNS cache
 342 filename must be specified.
 343 .TP 8
 344 .B \-j
 345 Enable \fIGeoDB\fP.  This enables the internal GeoDB geolocation services
 346 provided by The \fIWebalizer\fP.
 347 .TP 8
 348 .B \-J \fIname\fP
 349 \fBGeoDBDatabase\fP.  Use the alternate GeoDB database \fIname\fP.
 350 .TP 8
 351 .B \-w
 352 Enable \fIGeoIP\fP.  Enables GeoIP (by MaxMind Inc.) geolocation services.
 353 If native \fIGeoDB\fP services are also enabled, then this option
 354 will have no effect.
 355 .TP 8
 356 .B \-W \fIname\fP
 357 \fBGeoIPDatabase\fP.  Use the alternate GeoIP database \fIname\fP.
 358 .TP 8
 359 .B \-z \fIname\fP
 360 \fBFlagDir\fP.  Specify location of the country flag graphics and
 361 enable their display in the top country table.  The directory \fIname\fP
 362 is relative to the output directory being used unless an absolute path
 363 is given (ie: starts with a leading '/').
 364 .PP
 365 .I Hide Options
 366 .TP 8
 367 .B \-a \fIname\fP
 368 \fBHideAgent\fP.  Hide user agents matching \fIname\fP.
 369 .TP 8
 370 .B \-r \fIname\fP
 371 \fBHideReferrer\fP.  Hide referrer matching \fIname\fP.
 372 .TP 8
 373 .B \-s \fIname\fP
 374 \fBHideSite\fP.  Hide site matching \fIname\fP.
 375 .TP 8
 376 .B \-X
 377 \fBHideAllSites\fP.  Hide all individual sites (only display groups).
 378 .TP 8
 379 .B \-u \fIname\fP
 380 \fBHideURL\fP.  Hide URL matching \fIname\fP.
 381 .PP
 382 .I Table size options
 383 .TP 8
 384 .B \-A \fInum\fP
 385 \fBTopAgents\fP.  Display the top \fInum\fP user agents table.
 386 .TP 8
 387 .B \-R \fInum\fP
 388 \fBTopReferrers\fP.  Display the top \fInum\fP referrers table.
 389 .TP 8
 390 .B \-S \fInum\fP
 391 \fBTopSites\fP.  Display the top \fInum\fP sites table.
 392 .TP 8
 393 .B \-U \fInum\fP
 394 \fBTopURLs\fP.  Display the top \fInum\fP URLs table.
 395 .TP 8
 396 .B \-C \fInum\fP
 397 \fBTopCountries\fP.  Display the top \fInum\fP countries table.
 398 .TP 8
 399 .B \-e \fInum\fP
 400 \fBTopEntry\fP.  Display the top \fInum\fP entry pages table.
 401 .TP 8
 402 .B \-E \fInum\fP
 403 \fBTopExit\fP.  Display the top \fInum\fP exit pages table.
 404 .SH CONFIGURATION FILES
 405 Configuration files are standard \fBASCII(7)\fP text files that may be created
 406 or edited using any standard editor.  Blank lines and lines that begin
 407 with a pound sign ('#') are ignored.  Any other lines are considered to
 408 be configuration lines, and have the form "Keyword Value", where the
 409 \'Keyword\' is one of the currently available configuration keywords defined
 410 below, and 'Value' is the value to assign to that particular option.  Any
 411 text found after the keyword up to the end of the line is considered the
 412 keyword's value, so you should not include anything after the actual value
 413 on the line that is not actually part of the value being assigned.  The
 414 file \fIsample.conf\fP provided with the distribution contains lots of useful
 415 documentation and examples as well.
 416
 417 .I General Configuration Keywords
 418 .TP 8
 419 .B LogFile \fIname\fP
 420 Use log file named \fIname\fP.  If none specified, \fISTDIN\fP will be used.
 421 .TP 8
 422 .B LogType \fIname\fP
 423 Specify log file type as \fIname\fP. Values can be either \fIclf\fP,
 424 \fIsquid\fP, \fIftp\fP or \fIw3c\fP, with the default being \fBclf\fP.
 425 .TP 8
 426 .B OutputDir \fIdir\fP
 427 Create output in the directory \fIdir\fP.  If none specified, the current
 428 directory will be used.
 429 .TP 8
 430 .B HistoryName \fIname\fP
 431 Filename to use for history file.  Relative to output directory unless
 432 absolute name is given (ie: starts with '/'). Defaults to
 433 \'\fBwebalizer.hist\fP' in the standard output directory.
 434 .TP 8
 435 .B ReportTitle \fIname\fP
 436 Use the title string \fIname\fP for the report title.  If none
 437 specified, use the default of (in english) "\fIUsage Statistics for \fP".
 438 .TP 8
 439 .B HostName \fIname\fP
 440 Set the hostname for the report as \fIname\fP.  If none specified, an
 441 attempt will be made to gather the hostname via a \fBuname(2)\fP system
 442 call.  If that fails, \fIlocalhost\fP will be used.
 443 .TP 8
 444 .B UseHTTPS \fP( yes | \fBno\fP )
 445 Use \fIhttps://\fP on links to URLS, instead of the default \fIhttp://\fP,
 446 in the '\fBTop URLs\fP' table.
 447 .TP 8
 448 .B HTAccess \fP( yes | \fBno\fP )
 449 Enables the creation of a default .htaccess file in the output directory.
 450 .TP 8
 451 .B Quiet \fP( yes | \fBno\fP )
 452 Suppress informational messages.  Warning and Error messages will not be
 453 suppressed.
 454 .TP 8
 455 .B ReallyQuiet \fP( yes | \fBno\fP )
 456 Suppress all messages, including Warning and Error messages.
 457 .TP 8
 458 .B Debug \fP( yes | \fBno\fP )
 459 Print extra debugging information on Warnings and Errors.
 460 .TP 8
 461 .B TimeMe \fP( yes | \fBno\fP )
 462 Force timing information at end of processing.
 463 .TP 8
 464 .B GMTTime \fP( yes | \fBno\fP )
 465 Use \fIGMT \fP(\fIUTC\fP) time instead of local timezone for reports.
 466 .TP 8
 467 .B IgnoreHist \fP( yes | \fBno\fP )
 468 Ignore previous monthly history file.  \fBUSE WITH CAUTION\fP.  Does
 469 not prevent \fIIncremental\fP file processing.
 470 .TP 8
 471 .B IgnoreState \fP( yes | \fBno\fP )
 472 Ignore incremental data file.  \fBUSE WITH CAUTION\fP.  By ignoring
 473 the incremental data file, all previous processing for the current
 474 month will be lost and those logs must be re-processed.
 475 .TP 8
 476 .B FoldSeqErr \fP( yes | \fBno\fP )
 477 Fold out of sequence log records back into analysis by treating them
 478 as if they had the same date/time as the last good record.  Normally,
 479 out of sequence log records are ignored.
 480 .TP 8
 481 .B CountryGraph \fP( \fByes\fP | no )
 482 Display Country Usage Graph in output report.
 483 .TP 8
 484 .B CountryFlags \fP( yes | \fBno\fP )
 485 Enable or disable the display of flags in the top country table.
 486 .TP 8
 487 .B FlagDir \fIname\fP
 488 Specifies the directory \fIname\fP where the flag graphics are located.
 489 If not specified, the default is in the \fIflags\fP directory directly
 490 under the output directory being used.  If specified, the display of
 491 country flags will be enabled by default.  Using '\fIFlagDir flags\fP'
 492 is identical to using '\fICountryFlags yes\fP'.
 493 .TP 8
 494 .B DailyGraph \fP( \fByes\fP | no )
 495 Display Daily Graph in output report.
 496 .TP 8
 497 .B DailyStats \fP( \fByes\fP | no )
 498 Display Daily Statistics in output report.
 499 .TP 8
 500 .B HourlyGraph \fP( \fByes\fP | no )
 501 Display Hourly Graph in output report.
 502 .TP 8
 503 .B HourlyStats \fP( \fByes\fP | no )
 504 Display Hourly Statistics in output report.
 505 .TP 8
 506 .B PageType \fIname\fP
 507 Define the file extensions to consider as a \fIpage\fP.  If a file
 508 is found to have the same extension as \fIname\fP, it will be counted
 509 as a \fIpage\fP (sometimes called a \fIpageview\fP).
 510 .TP 8
 511 .B PagePrefix \fIname\fP
 512 Allows URLs with the prefix \fIname\fP to be counted as a \fIpage\fP
 513 type regardless of actual file type.  This allows you to treat contents
 514 under specified directories as pages no matter what their extension is.
 515 .TP 8
 516 .B OmitPage \fIname\fP
 517 Specifies URLs which should not be counted as pages, regardless of their
 518 extension (or lack thereof).
 519 .TP 8
 520 .B GraphLegend \fP( \fByes\fP | no )
 521 Allows the color coded graph legends to be enabled/disabled.
 522 .TP 8
 523 .B GraphLines \fInum\fP
 524 Specify the number of background reference lines displayed on the
 525 graphs produced.  Disable by using zero ('\fB0\fP'), default is \fB2\fP.
 526 .TP 8
 527 .B IndexMonths \fInum\fP
 528 Specify the number of months to display in the main index (yearly summary)
 529 table.  Default is 12 months.  Can be set to anything between 12 and 120
 530 months (1 to 10 years).
 531 .TP 8
 532 .B YearHeaders \fP( \fByes\fP | no )
 533 Enable/disable the display of year headers in the main index (yearly
 534 summary) table.  If enabled, year headers will be shown when the table
 535 is displaying more than 16 months worth of data.  Values can be 'yes'
 536 or 'no'.  Default is 'yes'.
 537 .TP 8
 538 .B YearTotals \fP( \fByes\fP | no )
 539 Enable/disable the display of year totals in the main index (yearly
 540 summary) table.  If enabled, year totals will be shown when the table
 541 is displaying more than 16 months worth of data.  Values can be 'yes'
 542 or 'no'.  Default is 'yes'.
 543 .TP 8
 544 .B GraphMonths \fInum\fP
 545 Specify the number of months to display in the main index (yearly
 546 summary) graph.  Default is 12 months.  Can be set to anything between
 547 12 and 72 months (1 to 6 years).
 548 .TP 8
 549 .B VisitTimeout \fInum\fP
 550 Specifies the visit timeout value.  Default is \fI1800 seconds\fP (30
 551 minutes).  A visit is determined by looking at the difference in time
 552 between the current and last request from a specific site.  If the
 553 difference is greater or equal to the timeout value, the request is
 554 counted as a new visit.  Specified in seconds.
 555 .TP 8
 556 .B IndexAlias \fIname\fP
 557 Use \fIname\fP as an additional alias for \fIindex.*\fP.
 558 .TP 8
 559 .B DefaultIndex \fP( \fByes\fP | no )
 560 Enables or disables the use of '\fBindex.\fP' as a default index name
 561 to be stripped from the end of URLs.  This does not effect any index
 562 names that may be defined with the \fIIndexAlias\fP option.
 563 .TP 8
 564 .B MangleAgents \fInum\fP
 565 Mangle user agent names based on mangle level \fInum\fP.  See the
 566 \fI-M\fP command line switch for mangle levels and their meaning.
 567 The default is \fB0\fP, which doesn't mangle user agents at all.
 568 .TP 8
 569 .B StripCGI \fP( \fByes\fP | no )
 570 Determines if URL CGI variables should be stripped from the end of
 571 URLs.  Values may be 'yes' or 'no', with the default being 'yes'.
 572 .TP 8
 573 .B TrimSquidURL \fInum\fP
 574 Allows squid log URLs to be reduced in granularity by truncating
 575 them after \fInum\fP slashes ('/') after the http:// prefix.  A
 576 setting of one (1) will cause all URLs to be summarized by domain
 577 only.  The default value is zero (0), which will disable any URL
 578 modifications and leave them exactly as found in the log file.
 579 .TP 8
 580 .B SearchEngine\fP \fIname\fP \fIvariable\fP
 581 Allows the specification of search engines and their query strings.
 582 The \fIname\fP is the name to match against the referrer string for
 583 a given search engine.  The \fIvariable\fP is the cgi variable that
 584 the search engine uses for queries.  See the \fBsample.conf\fP file
 585 for example usage with common search engines.
 586 .TP 8
 587 .B SearchCaseI\fP ( \fByes\fP | no )
 588 Determines if search strings should be treated case insensitive or
 589 not.  The default is 'yes', which lowercases all search strings
 590 (treat as case insensitive).
 591 .TP 8
 592 .B Incremental \fP( yes | \fBno\fP )
 593 Enable Incremental mode processing.
 594 .TP 8
 595 .B IncrementalName \fIname\fP
 596 Filename to use for incremental data.  Relative to output directory unless
 597 an absolute name is given (ie: starts with '/').  Defaults to
 598 \'\fBwebalizer.current\fP' in the standard output directory.
 599 .TP 8
 600 .B DNSCache \fIname\fP
 601 Filename to use for the DNS cache.  Relative to output directory unless
 602 an absolute name is given (ie: starts with '/').
 603 .TP 8
 604 .B DNSChildren \fInum\fP
 605 Number of children DNS processes to run in order to create/update the
 606 DNS cache file.  Specify zero (\fB0\fP) to disable.
 607 .TP 8
 608 .B CacheIPs \fP( yes | \fBno\fP )
 609 Cache unresolved IP addresses in the DNS database.  Default is '\fBno\fP'.
 610 .TP 8
 611 .B CacheTTL \fInum\fP
 612 DNS cache entry time to live (TTL) in days.  Default is 7 days.  May
 613 be any value between 1 and 100.
 614 .TP 8
 615 .B GeoDB \fP( yes | \fBno\fP )
 616 Allows native GeoDB geolocation services to be enabled or disabled.
 617 Default value is '\fBno\fP'.
 618 .TP 8
 619 .B GeoDBDatabase \fIname\fP
 620 Allows the use of an alternate GeoDB database \fIname\fP.  If not
 621 specified, the default database will be used.
 622 .TP 8
 623 .B GeoIP \fP( yes | \fBno\fP )
 624 Allows GeoIP (by MaxMind Inc.) geolocation services to be enabled or
 625 disabled.  Default is '\fBno\fP'.  If native \fIGeoDB\fP geolocation
 626 services are also enabled, then this option will have no effect (and
 627 the native \fIGeoDB\fP services will be used).
 628 .TP 8
 629 .B GeoIPDatabase \fIname\fP
 630 Allows the use of an alternate GeoIP database \fIname\fP.  If not
 631 specified, the default database will be used.
 632 .PP
 633 .I Top Table Keywords
 634 .TP 8
 635 .B TopAgents \fInum\fP
 636 Display the top \fInum\fP User Agents table. Use zero to disable.
 637 .TP 8
 638 .B AllAgents \fP( yes | \fBno\fP )
 639 Create separate HTML page with \fBAll\fP User Agents.
 640 .TP 8
 641 .B TopReferrers \fInum\fP
 642 Display the top \fInum\fP Referrers table. Use zero to disable.
 643 .TP 8
 644 .B AllReferrers \fP( yes | \fBno\fP )
 645 Create separate HTML page with \fBAll\fP Referrers.
 646 .TP 8
 647 .B TopSites \fInum\fP
 648 Display the top \fInum\fP Sites table. Use zero to disable.
 649 .TP 8
 650 .B TopKSites \fInum\fP
 651 Display the top \fInum\fP Sites (by KByte) table.  Use zero to disable.
 652 .TP 8
 653 .B AllSites \fP( yes | \fBno\fP )
 654 Create separate HTML page with \fBAll\fP Sites.
 655 .TP 8
 656 .B TopURLs \fInum\fP
 657 Display the top \fInum\fP URLs table. Use zero to disable.
 658 .TP 8
 659 .B TopKURLs \fInum\fP
 660 Display the top \fInum\fP URLs (by KByte) table.  Use zero to disable.
 661 .TP 8
 662 .B AllURLs \fP( yes | \fBno\fP )
 663 Create separate HTML page with \fBAll\fP URLs.
 664 .TP 8
 665 .B TopCountries \fInum\fP
 666 Display the top \fInum\fP Countries in the table. Use zero to disable.
 667 .TP 8
 668 .B TopEntry \fInum\fP
 669 Display the top \fInum\fP Entry Pages in the table.  Use zero to disable.
 670 .TP 8
 671 .B TopExit \fInum\fP
 672 Display the top \fInum\fP Exit Pages in the table.  Use zero to disable.
 673 .TP 8
 674 .B TopSearch \fInum\fP
 675 Display the top \fInum\fP Search Strings in the table.  Use zero to disable.
 676 .TP 8
 677 .B AllSearchStr \fP( yes | \fBno\fP )
 678 Create separate HTML page with \fBAll\fP Search Strings.
 679 .TP 8
 680 .B TopUsers \fInum\fP
 681 Display the top \fInum\fP Usernames in the table.  Use zero to disable.
 682 Usernames are only available if using http based authentication.
 683 .TP 8
 684 .B AllUsers \fP( yes | \fBno\fP )
 685 Create separate HTML page with \fBAll\fP Usernames.
 686 .PP
 687 .I Hide/Ignore/Group/Include Keywords
 688 .TP 8
 689 .B HideAgent \fIname\fP
 690 Hide User Agents that match \fIname\fP.
 691 .TP 8
 692 .B HideReferrer \fIname\fP
 693 Hide Referrers that match \fIname\fP.
 694 .TP 8
 695 .B HideSite \fIname\fP
 696 Hide Sites that match \fIname\fP.
 697 .TP 8
 698 .B HideAllSites \fP( yes | \fBno\fP )
 699 Hide all individual sites.  This causes only grouped sites to be displayed.
 700 .TP 8
 701 .B HideURL \fIname\fP
 702 Hide URLs that match \fIname\fP.
 703 .TP 8
 704 .B HideUser \fIname\fP
 705 Hide Usernames that match \fIname\fP.
 706 .TP 8
 707 .B IgnoreAgent \fIname\fP
 708 Ignore User Agents that match \fIname\fP.
 709 .TP 8
 710 .B IgnoreReferrer \fIname\fP
 711 Ignore Referrers that match \fIname\fP.
 712 .TP 8
 713 .B IgnoreSite \fIname\fP
 714 Ignore Sites that match \fIname\fP.
 715 .TP 8
 716 .B IgnoreURL \fIname\fP
 717 Ignore URLs that match \fIname\fP.
 718 .TP 8
 719 .B IgnoreUser \fIname\fP
 720 Ignore Usernames that match \fIname\fP.
 721 .TP 8
 722 .B GroupAgent \fIname\fP [\fILabel\fP]
 723 Group User Agents that match \fIname\fP.  Display \fILabel\fP in 'Top Agent'
 724 table if given (instead of \fIname\fP).  \fIname\fP may be enclosed in quotes.
 725 .TP 8
 726 .B GroupReferrer \fIname\fP [\fILabel\fP]
 727 Group Referrers that match \fIname\fP.  Display \fILabel\fP in 'Top Referrer'
 728 table if given (instead of \fIname\fP).  \fIname\fP may be enclosed in quotes.
 729 .TP 8
 730 .B GroupSite \fIname\fP [\fILabel\fP]
 731 Group Sites that match \fIname\fP.  Display \fILabel\fP in 'Top Site'
 732 table if given (instead of \fIname\fP).  \fIname\fP may be enclosed in quotes.
 733 .TP 8
 734 .B GroupDomains \fInum\fP
 735 Automatically group sites by domain.  The value \fInum\fP specifies the
 736 level of grouping, and can be thought of as the 'number of dots' to
 737 be displayed.  The default value of \fB0\fP disables domain grouping.
 738 .TP 8
 739 .B GroupURL \fIname\fP [\fILabel\fP]
 740 Group URLs that match \fIname\fP.  Display \fILabel\fP in 'Top URL'
 741 table if given (instead of \fIname\fP).  \fIname\fP may be enclosed in quotes.
 742 .TP 8
 743 .B GroupUser \fIname\fP [\fILabel\fP]
 744 Group Usernames that match \fIname\fP.  Display \fILabel\fP in 'Top
 745 Usernames' table if given (instead of \fIname\fP).  \fIname\fP may be
 746 enclosed in quotes.
 747 .TP 8
 748 .B IncludeSite \fIname\fP
 749 Force inclusion of sites that match \fIname\fP.  Takes precedence
 750 over \fBIgnore*\fP keywords.
 751 .TP 8
 752 .B IncludeURL \fIname\fP
 753 Force inclusion of URLs that match \fIname\fP.  Takes precedence
 754 over \fBIgnore*\fP keywords.
 755 .TP 8
 756 .B IncludeReferrer \fIname\fP
 757 Force inclusion of Referrers that match \fIname\fP.  Takes precedence
 758 over \fBIgnore*\fP keywords.
 759 .TP 8
 760 .B IncludeAgent \fIname\fP
 761 Force inclusion of User Agents that match \fIname\fP.  Takes precedence
 762 over \fBIgnore*\fP keywords.
 763 .TP 8
 764 .B IncludeUser \fIname\fP
 765 Force inclusion of Usernames that match \fIname\fP.  Takes precedence
 766 over \fBIgnore*\fP keywords.
 767 .PP
 768 .I HTML Generation Keywords
 769 .TP 8
 770 .B HTMLExtension \fItext\fP
 771 Defines the HTML file extension to use.  Default is \fIhtml\fP.  Do not
 772 include the leading period!
 773 .TP 8
 774 .B HTMLPre \fItext\fP
 775 Insert \fItext\fP at the very beginning of the generated HTML file.
 776 Defaults to a standard html 3.2 \fIDOCTYPE\fP record.
 777 .TP 8
 778 .B HTMLHead \fItext\fP
 779 Insert \fItext\fP within the <HEAD></HEAD> block of the HTML file.
 780 .TP 8
 781 .B HTMLBody \fItext\fP
 782 Insert \fItext\fP in HTML page, starting with the <BODY> tag.  If used, the
 783 first line must be a \fI<BODY ...>\fP tag.  Multiple lines may be specified.
 784 .TP 8
 785 .B HTMLPost \fItext\fP
 786 Insert \fItext\fP at top (before horiz. rule) of HTML pages.  Multiple lines
 787 may be specified.
 788 .TP 8
 789 .B HTMLTail \fItext\fP
 790 Insert \fItext\fP at bottom of the HTML page.  The \fItext\fP is top and
 791 right aligned within a table column at the end of the report.
 792 .TP 8
 793 .B HTMLEnd \fItext\fP
 794 Insert \fItext\fP at the very end of the HTML page.  If not specified,
 795 the default is to insert the ending </BODY> and </HTML> tags.  If used,
 796 you \fImust\fP supply these tags yourself.
 797 .TP 8
 798 .B LinkReferrer \fP( yes | \fBno\fP )
 799 Determines if the referrers listed in the top referrers table should be
 800 displayed as plain text, or as a link to the referrer URL.
 801 .TP 8
 802 .B ColorHit \fP( rrggbb | \fB00805c\fP )
 803 Sets the graph's hit-color to the specified html color (no '#').
 804 .TP 8
 805 .B ColorFile \fP( rrggbb | \fB0040ff\fP )
 806 Sets the graph's file-color to the specified html color (no '#').
 807 .TP 8
 808 .B ColorSite \fP( rrggbb | \fBff8000\fP )
 809 Sets the graph's site-color to the specified html color (no '#').
 810 .TP 8
 811 .B ColorKbyte \fP( rrggbb | \fBff0000\fP )
 812 Sets the graph's kilobyte-color to the specified html color (no '#').
 813 .TP 8
 814 .B ColorPage \fP( rrggbb | \fB00e0ff\fP )
 815 Sets the graph's page-color to the specified html color (no '#').
 816 .TP 8
 817 .B ColorVisit \fP( rrggbb | \fBffff00\fP )
 818 Sets the graph's visit-color to the specified html color (no '#').
 819 .TP 8
 820 .B ColorMisc \fP( rrggbb | \fB00e0ff\fP )
 821 Sets the 'miscellaneous' color for table headers (not graphs) to
 822 the specified html color (no '#').
 823 .TP 8
 824 .B PieColor1 \fP( rrggbb | \fB800080\fP )
 825 Sets the pie's first optional color to the specified html color (no '#').
 826 .TP 8
 827 .B PieColor2 \fP( rrggbb | \fB80ffc0\fP )
 828 Sets the pie's second optional color to the specified html color (no '#').
 829 .TP 8
 830 .B PieColor3 \fP( rrggbb | \fBff00ff\fP )
 831 Sets the pie's third optional color to the specified html color (no '#').
 832 .TP 8
 833 .B PieColor4 \fP( rrggbb | \fBffc480\fP )
 834 Sets the pie's fourth optional color to the specified html color (no '#').
 835 .PP
 836 .I Dump Object Keywords
 837 .PP
 838 The \fIWebalizer\fP allows you to export processed data to other programs by
 839 using \fItab delimited\fP text files.  The \fIDump*\fP commands specify
 840 which files are to be written, and where.
 841 .TP 8
 842 .B DumpPath \fIname\fP
 843 Save dump files in directory \fIname\fP.  If not specified, the default
 844 output directory will be used.  Do not specify a trailing slash ('/').
 845 .TP 8
 846 .B DumpExtension \fIname\fP
 847 Use \fIname\fP as the filename extension for dump files.  If not given,
 848 the default of \fBtab\fP will be used.
 849 .TP 8
 850 .B DumpHeader \fP( yes | \fBno\fP )
 851 Print a column header as the first record of the file.
 852 .TP 8
 853 .B DumpSites \fP( yes | \fBno\fP )
 854 Dump the sites data to a tab delimited file.
 855 .TP 8
 856 .B DumpURLs \fP( yes | \fBno\fP )
 857 Dump the url data to a tab delimited file.
 858 .TP 8
 859 .B DumpReferrers \fP( yes | \fBno\fP )
 860 Dump the referrer data to a tab delimited file.  This data is only
 861 available if using a log that contains referrer information
 862 (ie: a combined format web log).
 863 .TP 8
 864 .B DumpAgents \fP( yes | \fBno\fP )
 865 Dump the user agent data to a tab delimited file.  This data is only
 866 available if using a log that contains user agent information
 867 (ie: a combined format web log).
 868 .TP 8
 869 .B DumpUsers \fP( yes | \fBno\fP )
 870 Dump the username data to a tab delimited file.  This data is only available
 871 if processing a wu-ftpd xferlog or a web log that contains http authentication
 872 information.
 873 .TP 8
 874 .B DumpSearchStr \fP( yes | \fBno\fP )
 875 Dump the search string data to a tab delimited file.  This data is only
 876 available if processing a web log that contains referrer information and
 877 had search string information present.
 878 .SH FILES
 879 .TP 20
 880 .I webalizer.conf
 881 Default configuration file.  Is searched for in the current directory
 882 and if not found, in the \fI/etc/\fP directory.
 883 .TP 20
 884 .I webalizer.hist
 885 Monthly history file for previous months.  (can be changed)
 886 .TP 20
 887 .I webalizer.current
 888 Current state data file (Incremental processing).  (can be changed)
 889 .TP 20
 890 .I xxxxx_YYYYMM.html
 891 Various monthly \fIHTML\fP output files produced. (extension can be changed)
 892 .TP 20
 893 .I xxxxx_YYYYMM.png
 894 Various monthly image files used in the reports.
 895 .TP 20
 896 .I xxxxx_YYYYMM.tab
 897 Monthly tab delimited text files.  (extension can be changed)
 898 .SH BUGS
 899 Please report bugs to the author.
 900 .SH COPYRIGHT
 901 Copyright (C) 1997-2011 by Bradford L. Barrett.  Distributed under
 902 the GNU GPL.  See the files "\fICOPYING\fP" and "\fICopyright\fP",
 903 supplied with all distributions for additional information.
 904 .SH AUTHOR
 905 Bradford L. Barrett <\fIbrad at mrunix dot net\fP>