Autonomous System Number ASN Extension for The Webalizer - README.ASN


This is release 2.0 of webalizer-asn
Copyright (C) 2003-2008, Marco Steinacher <msteinacher@init7.net>
                         Init Seven AG http://www.init7.net

ABOUT
   
   This version is based on version 2.20-01 of The Webalizer extended by the
   AS number (ASN) lookup feature. The Webalizer is a cool web server analysis
   program written by Bradford L. Barrett. See http://www.webalizer.org for
   more information.
   
   With this extension The Webalizer has the ability to perform AS number lookups
   to generate additional statistics. The AS number identifies the AS (Autonomous
   System) a host is belonging to. An Autonomous System is a group of IP networks
   operated by one or more network operator/s which has a single and clearly
   defined external routing policy.
   (See RFC1930 for more information about AS numbers.)
   
   It can be useful for high-traffic sites and ISPs when they know from which
   networks their visitors come from. For example they can plan future peerings
   or other things based on this information.
   
   This document attempts to explain how it works and some things that you should
   be aware of when using the AS number lookup features.
   
   
STATUS
   
   Please note that this is BETA-software that has NOT been tested on many
   systems with different configurations.
   See CHANGES.ASN for information about bugfixes etc.

   IPv6 is supported in principle but AS number lookups for IPv6 addresses are
   disabled at the moment because the ASN DB file is currently not IPv6 compatible.
   The AS numbers of IPv6 addresses are currently listed as 'n/a (IPv6)'.


UPGRADING

   Upgrading from the previous version 1.3b to 2.0 should be straightforward. The
   only incompatible changes are that the command line options '-b' (ASN without
   DNS support), '-O' (# top ASNs), and '-Z' (Suppress ASN graph) have been dis-
   abled as they conflict with new options in webalizer 2.20-01. Please use the
   corresponding directives in the configuration file instead.

   When upgrading from a previous version or when ASN support is enabled for the
   first time, you probably have to delete one or more of the following files:
   - ASN cache/database file (when the DB format has changed, no data will be lost)
   - webalizer.current (incremental processing information will be lost)
   - webalizer.hist (only necessary in rare cases, history will be lost)


INSTALLATION

   1. Download the Source at http://www.init7.net/webalizer_asn/.

   2. Minimal installation steps:

       ./configure
       make
       make install

     If you get errors you maybe have to add other options for configure.
     For example:
       --with-dblib=/usr/lib  or  --with-dblib=/usr/local/lib
       --with-db=/usr/include/db1
       --with-gdlib=/usr/local/lib
     See also the FAQ at http://www.webalizer.org/faq.html
   
     The option --disable-asn disables the ASN feature at compile time.
     If the ASN feature is enabled the DNS feature must also be enabled
     (which is the default). See DNS.README for additional information on
     the DNS feature.
   
   3. Add a line to your crontab to update the ASN DB file regularly.
      See DOWNLOADING AND UPDATING THE ASN DB FILE below.

   
HOW IT WORKS
   
   ASN lookups are made against an ASN DB file containing routes and AS
   numbers. Because ASN lookups require IP addresses DNS lookups will be
   done if the logfile contains hostnames instead of IP adresses. These
   DNS lookups are done like the reverse lookups using the same cache file
   but without multiple child processes. Thus it is recommended to use 
   logfiles containing IP adresses rather than hostnames for performance
   reasons.
   
   To enable the ASN feature you must either use the '-B' command line switch,
   or the 'ASNDB' configuration keyword. If no DB file is specified, no
   attempts to perform ASN lookups will be done.
   Note, that you also have to enable the DNS feature if you enable ASN
   lookups ('-D' or 'DNSCache, see DNS.README) unless you specify use the
   ASNWithoutDNS option (see hint 2 below).
   
   Hint 1:
   If you want reliable results or you see too much 'n/a (no IP)' entries
   in the report, it is recommended that you disable hostname lookups
   (HostnameLookups Off in your Apache configuration) and let The
   Webalizer do the hostname lookups. That is because the hostnames
   in the logfile may be outdated or unresolvable (e.g. dialup network
   of ISPs that only have reverse DNS records) and therefore the ASN lookups
   result in wrong or missing AS numbers. This will also improve the
   DNS lookup performance (see above).
   
   Hint 2:
   If you are only interested in IP addresses and AS numbers then
   you can speedup The Webalizer by disabling DNS lookups and using the
   ASNWithoutDNS option. But remember: In this case the logfile
   *must* only contain IP addresses but no hostnames!
   
   Other options/configuration keywords related to the ASN feature are:
    TopASNs       :  Number of top AS numbers to be listed
    ASNGraph      :  Supress AS number graph
    AllASNs       :  Generate HTML page with all AS numbers
    DumpASNs      :  Dump all AS numbers to a tab separated file (asn_YYYYMM.tab)
   
EXAMPLE
   
   webalizer -c test.conf -N 10 -D dns_cache.db -B /var/local/asn_db /var/log/my_www_log
   
      This will use the configuration file 'test.conf' to obtain normal
      configuration options such as hostname and output directory... it
      will use the DNS cache file 'dns_cache.db' (using 10 child processes)
      in the default output directory and the ASN DB file '/var/local/asn_db'.
      (Of course you can use the keywords DNSCache, DNSChildren and ASNDB in
       the configuration file instead of using the options -D, -N and -B.)
   
   
DOWNLOADING AND UPDATING THE ASN DB FILE
   
   The ASN DB file is in the Alligator database format (ADB), generated by
   the Piranha/Alligator BGP route collector. Visit http://www.netlantis.org
   for more information.
   
   You can download a current ASN DB file from:
   http://www.init7.net/webalizer_asn/alligator/webalizer_asn.adb.gz
   It is recommended to update this ASN DB file weekly (e.g. with a cronjob).
   You can use the script webalizer-update-asndb to do so.
   
   
CONSIDERATIONS
   
   Processing of live log files is discouraged, as the chances of log records
   being written between the time of ASN/DNS resolution and normal processing
   will cause problems.
   
   
ASNDB-READER
   
   When compiling The Webalizer the tool 'asndb-reader' will be created
   in the source directory. You can use it to dump the content of the
   ASN DB file or to lookup the AS number for an IP address or even process
   a file with IP addresses. With this feature you can query the AS numbers
   for list of IP addresses very fast.


CONTACT
   
   Send bug reports, suggestions, comments to msteinacher@init7.net.
   URL: http://www.init7.net/webalizer_asn/


COPYRIGHT
   
   Copyright (C) 2003-2008 Marco Steinacher, Init Seven AG
   
   webalizer-asn is free software.
   See the file COPYING for copying conditions.
   
   
EOF
[Back] [text/plain]