[Pkg-awstats-devel] Bug#580702: awstats: Improvement to documentation of logfile permissions and suggest locking

[Ken Neighbors]

Package: awstats
Version: 6.9.5~dfsg-2
Severity: wishlist
Tags: patch


Attached are some additions to the README.Debian file explaining in
more detail how to change the permissions of Apache log files and
recommendations for /etc/logrotate.d/apache2 and EnableLockForUpdate.

-- System Information:
Debian Release: 5.0.4
  APT prefers stable
  APT policy: (500, 'stable'), (50, 'unstable')
Architecture: i386 (i686)

Kernel: Linux 2.6.26-2-686 (SMP w/1 CPU core)
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8)
Shell: /bin/sh linked to /bin/bash

Versions of packages awstats depends on:
ii  perl                     5.10.0-19lenny2 Larry Wall's Practical Extraction 

Versions of packages awstats recommends:
ii  libnet-xwhois-perl            0.90-3     Whois Client Interface for Perl5

Versions of packages awstats suggests:
pn  apache2 | httpd            <none>        (no description available)
pn  libgeo-ipfree-perl         <none>        (no description available)
pn  libnet-dns-perl            <none>        (no description available)
pn  libnet-ip-perl             <none>        (no description available)
ii  liburi-perl                1.35.dfsg.1-1 Manipulates and accesses URI strin

-- no debconf information
-------------- next part --------------
>From 9ec6cd3775c74ec57ab2474b6a347b05fbe88f98 Mon Sep 17 00:00:00 2001
From: Ken Neighbors <ken at nsds.com>
Date: Tue, 27 Apr 2010 15:05:12 -0700
Subject: Improve documentation of logfile permissions and suggest
 EnableLockForUpdate=1.

---
 debian/README.Debian |   31 ++++++++++++++++++++++---------
 1 files changed, 22 insertions(+), 9 deletions(-)

diff --git a/debian/README.Debian b/debian/README.Debian
index b3ea45b..94fff06 100644
--- a/debian/README.Debian
+++ b/debian/README.Debian
@@ -7,16 +7,16 @@ Quick'n'dirty setup
 Do the following for a simple setup of a single website with Apache 2.x:
 
   * 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/
-  * copy /usr/share/doc/awstats/examples/awstats.default.conf to /etc/awstats/
-  * edit /etc/default/awstats to enable nightly build of static html reports
+  * Copy /usr/share/doc/awstats/examples/apache.conf to /etc/apache2/conf.d/
+  * Copy /usr/share/doc/awstats/examples/awstats.default.conf to /etc/awstats/
+  * Edit /etc/default/awstats to enable nightly build of static html reports
 
 The above is _NOT_ supported or recommended! Please read the rest of this
 document instead...
 
 
-No stats are generated
-----------------------
+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
@@ -24,8 +24,10 @@ 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:
+    change line in /etc/logrotate.d/apache2 to: "create 644 root adm"
+    change permissions of existing files: chmod 644 /var/log/apache2/*.log
 
  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
@@ -47,8 +49,19 @@ 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.local
+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.
 
 
 The icons are missing
-- 
1.5.6.5