guoyu07 / awstats-multisite-summary Goto Github PK

                          AWStats MultiSite Summary

                                 Version 1.8

                          Copyright (C) 2005 - 2012
                   25th-floor - de Pretis & Helmberger KG.
                             All rights reserved.

This program is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with
this program; if not, write to the Free Software Foundation, Inc., 59 Temple 
Place, Suite 330, Boston, MA  02111-1307  USA



INDEX
=====

1. Overview
2. Quick Start
  2.1 Configuring AWStats MultiSite Summary
  2.1 Configuring AWStats
  2.2 Configuring Apache
3. How it works
4. Requirements
5. Support



1. OVERVIEW
===========

What is and does AWStats MultiSite Summary exactly? Unlike other AWStats addons
this little tool summarizes multiple sites in a clear and compact way on a per
month and a per user basis.

It depends on the following AWStats settings for each site:

    AllowAccessFromWebToAuthenticatedUsersOnly=1
    AllowAccessFromWebToFollowingAuthenticatedUsers="user1 user2 user3"

and a seperate Apache VirtualHost (might work as subdirectory installation too)
to act as centralized AWStats "portal" (see "Apache Configuration" below).

To see a working online demo please go to:

    https://stats.25th-floor.com

and login as "awstats-mss-demo" with password "demo".



2. QUICK START
==============

The latest version of AWStats MultiSite Summary can be retrieved from:

    http://www.25th-floor.com/oss/projects/AWStats-MultiSite-Summary

To install AWStats MultiSite Summary:

    cd /path/to/DocumentRoot
    tar xvf AWStats-MultiSite-Summary-1.8.tar.gz
    mv AWStats-MultiSite-Summary-1.8/* .

Additionally AWStats' "awstats.pl" has to be copied to
/path/to/DocumentRoot so AWStats MultiSite Summary can link to it from its
summary page. Creating a symlink might works too - depending on your
Apache/VirtualHost configuration.


2.1 Configure AWStats MultiSite Summary
---------------------------------------

Edit 'index.pl' and change the following values to suit your needs. Default
values are:

    my $awstats_config_dir = '/etc/awstats';
    my $awstats_uri        = '/awstats.pl';
    my $template_root      = '_system/templates';

NOTE: AWStats MSS (= the user your Apache is running as) needs read access to
      both the directory containinig AWStats configuration files and the
      corresponding "CacheDir".


2.2 Configuring AWStats
-----------------------

Besides a seperate AWStats configuration file for each site to be analyzed it
is strongly adviced to use

    awstats.model.conf

to configure default values and e.g.

    awstats.sitename.conf

to override these default values on a per site basis. Just add the following
line at the beginning of each site configuration file:

    Include "/path/to/awstats.model.conf"

As mentioned above for each site these parameters have to be set:

    AllowAccessFromWebToAuthenticatedUsersOnly=1
    AllowAccessFromWebToFollowingAuthenticatedUsers="user1 user2 user3"

User(s) defined here must be able to login on your AWStats "portal" (see
Configuring Apache below) via HTTP Authentication and will then get an overview
of all sites analysis he is allowed to access.

This way you can e.g. define a user who's allowed to access all available site
analysis.

If there's not more than one site configured for an authenticated users he will
be instantaneous redirected directly to the corresponding AWStats report.


2.3 Configuring Apache
----------------------

It is strongly advised that you create a seperate Apache VirtualHost as
centralized AWStats "portal" like e.g.

    http://stats.yoursite.com

Most important is however that you enable HTTP Authentication (Basic or Digest)
for the VirtualHost (or the Location/Directory if you prefer so). The users you
add to your UserFile (.htaccess, mod_auth_ldap, ...) have to be identical with
the ones you define in the respective sites' AWStats configuration file.

AWStats MultiSite Summary as well as AWStats itself are written in Perl so you
will have to enable CGI support for the DocumentRoot (see example VirtualHost).

An example Apache VirtualHost would look like:

    <VirtualHost 127.0.0.1:80>
      ServerName stats.yoursite.com
      ServerAdmin [email protected]

      DocumentRoot /path/to/DocumentRoot

      ErrorLog /var/log/httpd/stats_yoursite.error_log
      CustomLog /var/log/httpd/stats_yoursite.access_log combined

      <Directory /path/to/DocumentRoot>
        AuthName "HTTP Statistics"
        AuthType Basic
        AuthUserFile /etc/httpd/auth/.stats.yoursite.com
        require valid-user

        Options +ExecCGI
        AddHandler cgi-script .pl
      </Directory
    </VirtualHost>

For information about how to create and maintain the AuthUserFile please see
the Apache documentation at

    http://httpd.apache.org/docs/mod/mod_auth.html#authuserfile



3. HOW IT WORKS
===============

AWStats MultiSite Summary matches the authenticated user (HTTP Authentication)
with available site configuration files in e.g. /etc/awstats. If a match
occures it opens the file, reads some configuration values and tries to open
the latest corresponding AWStats cache file in "CacheDir" to get some values
for summarization.

If no cache file can be found (e.g. AWStats hasn't analyzed a site yet) the
site will not be visibile in the summary.



4. REQUIREMENTS
===============

AWStats MultiSite Summary has been tested with Perl 5.8.x and will most likely
work with all Perl5 versions.

Besides AWStats 6.x itself (earlier versions will work too eventually) the
following Perl modules are required and have to be installed. You can find them
all on CPAN (http://search.cpan.org):

    CGI
    File::Find::Rule
    File::Slurp
    Math::Round::Var
    Template Toolkit (see also http://www.tt2.org)



5. SUPPORT
==========

Our mailing list provides a forum for discussing issues relating to the use and
of AWStats MultiSite Summary.

To subscribe to the mailing list send an email to:

    [email protected]

with an empty message body. You can also use the web· interface to subscribe or
browse the archives:

    http://lists.25th-floor.com/wwsympa.fcgi/info/awstats-mss

Please don't hesitate to report bugs at:

    http://bugtraq.25th-floor.com