squidanalyzer/README

NAME
    SquidAnalyzer v4.2 - Squid access log report generation tool

DESCRIPTION
    SquidAnalyzer parse native access log format of the Squid proxy and
    generate general statistics about hits, bytes, users, networks, top url
    and top second level domain.

    Statistic reports are oriented to user and bandwidth control, this is
    not a pure cache statistics generator. SquidAnalyzer use flat files to
    store data and don't need any SQL, SQL Lite or Berkeley databases.

    This analyzer is incremental so it should be run in a daily cron. Take
    care if you have rotate log enable to run it before rotation is done.

    The HTML output need a huge size for large number of user. Here on my
    pentium III 500 MHz with 15Mb of free memory, for 600 users and an
    access.log of 72 Mb it takes 20 minutes to run and generate 70 Mb of
    HTML output by month. If you have an older system than this and want to
    save space and time, you can disable url details feature that logs and
    reports statistics for every URL and domain.

REQUIREMENT
    perl 5.005_03 or higher and the following Perl modules:

            GD
            GD::Graph
            GD::TextUtil
            GD::Graph::bars3d;

    See GD and GD::Graph requirements for other needed libraries.

    If they are not yet include in your OS distribution you can always find
    them at http://search.cpan.org/

    If you have Internet access from your server, you can execute the
    following command to install GD::Graph::bars3d and all its dependencies.

            perl -MCPAN -e 'install GD::Graph::bars3d'

    Images output format is PNG so libgd must be compiled with libpng.

INSTALLATION
  Generic install
    If you want the package to be intalled into the Perl distribution just
    do the following:

        perl Makefile.PL
        make
        make install

    Follow the instruction given at the end of install. With this default
    install everything configurable will be installed under
    /etc/squidanalyzer. The Perl library SquidAnalyzer.pm will be installed
    under your site_perl directory and the squid-analyzer Perl script will
    be copied under /usr/local/bin.

    The default output directory for html reports will be
    /var/www/squidanalyzer/.

  Custom install
    You can create your fully customized SquidAnalyzer installation by using
    the Makefile.PL Perl script. Here is a sample:

            perl Makefile.PL \
                    LOGFILE=/var/log/squid3/access.log \
                    BINDIR=/usr/bin \
                    CONFDIR=/etc \
                    HTMLDIR=/var/www/squidreport \
                    BASEURL=/squidreport \
                    MANDIR=/usr/man/man3 \
                    DOCDIR=/usr/share/doc/squidanalyzer

    If you want to build a distro package, there are two other options that
    you may use. The QUIET option is to tell to Makefile.PL to not show the
    default post install README. The DESTDIR is to create and install all
    files in a package build base directory. For example for Fedora RPM,
    thing may look like that:

            # Make Perl and SendmailAnalyzer distrib files
            %{__perl} Makefile.PL \
                INSTALLDIRS=vendor \
                QUIET=1 \
                LOGFILE=/var/log/squid/access.log \
                BINDIR=%{_bindir} \
                CONFDIR=%{_sysconfdir} \
                BASEDIR=%{_localstatedir}/lib/%{uname} \
                HTMLDIR=%{webdir} \
                MANDIR=%{_mandir}/man3 \
                DOCDIR=%{_docdir}/%{uname}-%{version} \
                DESTDIR=%{buildroot} < /dev/null

    See spec file in packaging/RPM for full RPM build script.

  Local install
    You can also have a custom installation. Just copy the SquidAnalyzer.pm
    and the squid-analyzer perl script into a directory, copy and modify the
    configuration file and run the script from here with the -c option.

    Then copy files sorttable.js, squidanalyzer.css and
    logo-squidanalyzer.png into the output directory.

  Post installation
    1. Modify your httpd.conf to allow access to HTML output like follow:

            Alias /squidreport /var/www/squidanalyzer
            <Directory /var/www/squidanalyzer>
                Options -Indexes FollowSymLinks MultiViews
                AllowOverride None
                Order deny,allow
                Deny from all
                Allow from 127.0.0.1
            </Directory>

    2. If necessary, give additional host access to SquidAnalyzer in
    httpd.conf. Restart and ensure that httpd is running.

    3. Browse to http://my.host.dom/squidreport/ to ensure that things are
    working properly.

    4. Setup a cronjob to run squid-analyzer daily or more often:

         # SquidAnalyzer log reporting daily
         0 2 * * * /usr/local/bin/squid-analyzer > /dev/null 2>&1

    or run it manually. For more information, see README file.

    You can use network name instead of network ip addresses by using the
    network-aliases file. Also if you don't have authentication enable and
    want to replace client ip addresses by some know user or computer you
    can use the user-aliases file to do so.

    See the file squidanalyzer.conf to customized your output statistics and
    match your network and file system configuration.

CONFIGURATION
    Unless previous version customization of SquidAnalyzer is now done by a
    single configuration file squidanalyzer.conf.

    Here follow the configuration directives used by Squid Analyzer.

    Output output_directory
        Where SquidAnalyzer should dump all HTML, data and images files. You
        should give a path that can be read by a Web browser.

    LogFile squid_access_log_file
        Set the path to the Squid log file.

    NetworkAlias network-aliases_file
        Set path to the file containing network alias name. Network are show
        as Ip addresses so if you want to display name instead create a file
        with this format:

            LOCATION_NAME IP_NETWORK_ADDRESS

        Separator must be a tabulation.

        You can use regex to match and group some network addresses. See
        network-aliases file for examples.

    UserAlias user-aliases_file
        Set path to the file containing user alias name. If you don't have
        auth_proxy enable users are seen as ip addresses. So if you want to
        show username or computer name instead, create a file with this
        format:

            FULL_USERNAME IP_ADDRESS

        If you have auth_proxy enable but want to replace login name by full
        user name, create a file with this format:

            FULL_USERNAME LOGIN_NAME

        Separator for both must be a tabulation.

        You can use regex to match and group some user login or ip
        addresses. See user-aliases file for examples.

    AnonymizeLogin 0
        Set this to 1 if you want to anonymize all user login. The username
        will be replaced by an unique id that change at each squid-analyzer
        run. Default disable.

    OrderNetwork bytes|hits|duration
    OrderUser bytes|hits|duration
    OrderUrl bytes|hits|duration
        Used to set how SquidAnalyzer sort Network, User and Url report
        screen. Value can be: bytes, hits or duration. Default is bytes.

    OrderMime bytes|hits
        Used to set how SquidAnalyzer sort Mime types report screen Value
        can be: bytes or hits. Default is bytes.

    UrlReport 0|1
        Should SquidAnalyzer display user details. This will show all URL
        read by user. Take care to have enougth space disk for large user.
        Default is 0, no url detail report.

    QuietMode 0|1
        Run in quiet mode for batch processing or print debug information.
        Default is 0, verbose mode.

    CostPrice price/Mb
        Used to set a cost of the bandwith per Mb. If you want to generate
        invoice per Mb for bandwith traffic this can help you. Value 0 mean
        no cost, this is the default value, the "Cost" column is not
        displayed

    Currency currency_abreviation
        Used to set the currency of the bandwith cost. Preferably the html
        special character. Default is &euro;

    TopNumber number
        Used to set the number of top url and second level domain to show.
        Default is top 10.

    Exclude exclusion_file
        Used to set client ip addresses, network addresses and/or auth login
        name to exclude from report. Format of the file is a login or an ip
        address by line.

    Lang language_file
        Used to set the translation file to be used. Value must be set to a
        file containing all string translated. See the lang directory for
        translation files. Default is defined internally in English.

    HeaderFile custom_header_file
        Custom header. Must be a path to a text file containing HTML code
        that will be placed just after the body tag and just before the
        program name and version. Default is defined internally if this
        directive is not set to a valid file.

    FooterFile custom_footer_file
        Custom Footer. Must be a path to a text file containing HTML code
        that will be placed at the bottom of each page just before the end
        if the body tag. Default is defined internally if this directive is
        not set to a valid file.

    SiblingHit
        Adds peer cache hit (CD_SIBLING_HIT) to be taken has local cache
        hit. Enabled by default, you must disabled it if you don't want to
        report peer cache hit onto your stats.

AUTHOR
    Gilles DAROLD <gilles@darold.net>

COPYRIGHT
    Copyright (c) 2001-2012 Gilles DAROLD

    This package is free software and published under the GPL v3 or above
    license.