[Pkg-awstats-commits] [SCM] awstats Debian packaging branch, master, updated. debian/6.9.5.dfsg-3-7-g54bcf11

Sat Jun 12 15:17:09 UTC 2010

The following commit has been merged in the master branch:
commit 54bcf1123da1ee225a94b6c80bcd6862c39bfe1b
Author: Sergey B Kirpichev <skirpichev at gmail.com>
Date:   Sat Jun 12 19:15:30 2010 +0400

    Improve documentation.  Logfile permissions, EnableLockForUpdate option, setup for multiple sites.  Closes: bug#580702.

diff --git a/debian/README.Debian b/debian/README.Debian
index d5a9a1e..006ec2f 100644
--- a/debian/README.Debian
+++ b/debian/README.Debian
@@ -4,35 +4,43 @@ awstats for Debian
 Quick'n'dirty setup
 -------------------
 
-Do the following for a simple setup of a single website with Apache 2.x:
+Do the following for a simple setup of a single website with Apache:
 
-  * Edit /etc/logrotate.d/apache2 to permit www-data access to logfiles
-  * copy /usr/share/doc/awstats/examples/apache.conf to /etc/apache2/conf.d/
+  * Edit /etc/logrotate.d/apache2 to permit www-data access to
+    logfiles
+  * Copy /usr/share/doc/awstats/examples/apache.conf to
+    /etc/apache2/conf.d/
 
-The above is _NOT_ supported or recommended! Please read the rest of this
-document instead...
+Optionaly edit /etc/default/awstats to disable nightly build of static
+html reports (placed in /var/cache/awstats/).
 
+The above is _NOT_ supported or recommended!  Please read the rest of
+this document instead...
 
-No stats are generated
-----------------------
 
-As AWStats is used both as a CGI-script and offline, it is by default run as
-uid=www-data in cron jobs so that generated files are accessible from CGI as
-well.
-By default Apache stores (since version 1.3.22-1) logfiles with uid=root and
-gid=adm, so you need to either...
+No stats are generated due to logfile permissions
+-------------------------------------------------
+
+As AWStats is used both as a CGI-script and offline, it is by default
+run as uid=www-data in cron jobs so that generated files are
+accessible from CGI as well.  By default Apache stores (since version
+1.3.22-1) logfiles with uid=root and gid=adm, so you need to either...
 
- 1) Change the rights of the logfiles in /etc/logrotate.d/apache2 so that
-    www-data has at least read access.
+ 1) Change the rights of the logfiles so that www-data has at least read
+    access.  For example:
 
- 2) As 1) but change to a specific user, and use the suEXEC feature of Apache
-    to run as same user (and either change the right of /var/lib/awstats as
-    well or use another directory). This is more complicated, but then the logs
-    are not generally accessible to the server (which was probably the point of
-    the Apache default).
+    * change line in /etc/logrotate.d/apache2 to: "create 644 root adm"
+    * change permissions of existing files: chmod 644 /var/log/apache2/*.log
 
- 3) Change awstats.pl to group adm (but beware that you are then taking the
-    risk of allowing a CGI-script access to admin stuff on the machine!).
+ 2) As 1) but change to a specific user, and use the suEXEC feature of
+    Apache to run as same user (and either change the right of
+    /var/lib/awstats as well or use another directory).  This is more
+    complicated, but then the logs are not generally accessible to the
+    server (which was probably the point of the Apache default).
+
+ 3) Change awstats.pl to group adm (but beware that you are then
+    taking the risk of allowing a CGI-script access to admin stuff on
+    the machine!).
 
 With other webservers than Apache several things should probably be
 changed, like location and format of logfiles.
@@ -45,8 +53,21 @@ By default AWStats scans logfiles each 10 minutes. When Apache (and
 other webservers) rotate their logfiles, the last entries in the old
 logfile may not have been read by AWStats.
 
-Make sure to run AWStats right _before_ web logs are rotated (add a
-"prerotate" in /etc/logrotate.d/apache2 for Apache).
+Make sure to run AWStats right _before_ web logs are rotated.  For
+example, insert the following lines in /etc/logrotate.d/apache2:
+
+    prerotate
+      if [ -x /usr/share/awstats/tools/update.sh ]; then
+        su - -c /usr/share/awstats/tools/update.sh www-data
+      fi
+    endscript
+
+Also consider enabling lock files in /etc/awstats/awstats.conf with
+EnableLockForUpdate=1 so that only one AWStats update process is
+running at a time.  This will reduce system resources especially if
+the AWStats update process takes longer than 10 minutes to complete.
+This solution has some security drawbacks: lockfile with well-known
+name and writable by www-data user.
 
 
 The icons are missing
@@ -70,18 +91,18 @@ Multiple stats
 To handle multiple stats (eg. using VirtualHosts in Apache) you
 should...
 
- 1) Place all configs in /etc/awstats.
+ 1) Place all additional configs in /etc/awstats/.
 
- 2) Name the configs "awstats." + whatever you want - ".conf" (eg.
-    awstats.example.com.conf"). But avoid "awstats.awstats.conf.
+ 2) Name the new configs "awstats." + whatever you want + ".conf" (eg.
+    "awstats.example.com.conf"). But avoid "awstats.awstats.conf".
 
     To retain use of a common config file containing defaults for all
     of your sites, consider a scheme such as the following:
  
-    Make a bunch of awstats.[site_name_here].conf files, and have
-    the first line include the parent awstats.conf file (which by
-    default also includes awstats.conf.local). The remainder of the
-    file should have your site-specific configuration settings, which
+    Make a bunch of awstats.[site_name_here].conf files, and have the
+    first line include the parent awstats.conf file (which by default
+    also includes awstats.conf.local).  The remainder of the file
+    should have your site-specific configuration settings, which
     override the defaults specified in awstats.conf and
     awstats.conf.local.
  
@@ -104,12 +125,10 @@ should...
     main file is updated (with warnings if edited locally) but extra
     config files are silently ignored and possibly broken.
 
- 3) Run awstats.pl with each config one by one (have a look at the
-    scripts awstats-update and awstats_updateall.pl in
-    /usr/share/doc/awstats/examples/).
-
- 4) Edit /etc/cron.d/awstats for each site. Possibly a line like this
-    for each site:
+ 3) Default awstats crontabs in /etc/cron.d/awstats can handle
+    generation of the raw statistics data and html reports for above
+    config layout.  But you can comment out defaults and edit
+    /etc/cron.d/awstats for each site. Possibly add lines like this:
 
         20 2 * * * www-data [ -x /usr/lib/cgi-bin/awstats.pl ] && \
             /usr/lib/cgi-bin/awstats.pl -config=example.com -update >/dev/null
@@ -129,5 +148,3 @@ Where is configure.pl?
 AWStats configure.pl script is not available as a CGI script on
 Debian.  Instead, it is located as awstats_configure.pl in
 /usr/share/doc/awstats/examples/.
-
- -- Jonas Smedegaard <dr at jones.dk>  Fri,  8 Oct 2004 12:28:31 +0200

-- 
awstats Debian packaging

