[Pkg-awstats-devel] Bug#572353: A Suggestion

[Ken Neighbors]

I have some comments and a suggestion for handling AWStats
configuration files in Debian.

OBSERVATION:

When you invoke "/usr/lib/cgi-bin/awstats.pl -config=mysite", it
searches the following directories in order:

   /usr/lib/cgi-bin
   /etc/awstats
   /usr/local/etc
   /etc
   /etc/opt/awstat

For each directory, it looks for two files "awstats.mysite.conf" or
"awstats.conf".  So here is the complete search order:

   /usr/lib/cgi-bin/awstats.mysite.conf
   /usr/lib/cgi-bin/awstats.conf
   /etc/awstats/awstats.mysite.conf
   /etc/awstats/awstats.conf
   /usr/local/etc/awstats/awstats.mysite.conf
   /usr/local/etc/awstats/awstats.conf
   /etc/awstats.mysite.conf
   /etc/awstats.conf
   /etc/opt/awstat/awstats.mysite.conf
   /etc/opt/awstat/awstats.conf

It stops as soon as it finds one.  It only emits an error message if
none of the above files are found.  I do not believe it is a good idea
to change the awstats.pl file to do something different, as it may
break existing installations.  However, note that AWStats has two
command line options related to finding the configuration file:

   -configdir=DirConfig (single directory to search for config file)
   -config=SiteConfig   ("virtualhostname" in the config file name)

SUGGESTION:

Do not use a file named "awstats.conf" at all, nor allow AWStats to
search so many different directories.  This way, if the config file
does not exist or is not readable, awstats.pl will emit an error
message.  For example:

   root# ls -l /etc/awstats
   -rw------- 1 root root    49 2010-04-25 11:20 awstats.custom.conf
   -rw-r--r-- 1 root root 61033 2010-04-25 11:10 default.conf
   -rw-r--r-- 1 root root   240 2010-03-26 16:39 local.conf

   root# su www-data -c "/usr/lib/cgi-bin/awstats.pl 
-configdir=/etc/awstats -config=custom"
   Error: Couldn't open config file "awstats.custom.conf" nor
   "awstats.conf" after searching in path "/etc/awstats": No such file
   or directory

   - Did you use correct config parameter ?
   Example: If your config file is awstats.mysite.conf, use -config=mysite
   - Did you create your config file 'awstats.custom.conf' ?
   If not, you can run "awstats_configure.pl"
   from command line, or create it manually.

   Check config file, permissions and AWStats documentation (in 'docs'
   directory).

Here are the specifics of my suggestion:

1. Use the "-configdir" option in Debian-packaged scripts
(/usr/share/awstats/tools/buildstatic.sh and update.sh) to instruct
awstats.pl to only search one directory, "/etc/awstats".

2. Do not create a default /etc/awstats/awstats.conf file.  Instead,
create a default /etc/awstats/default.conf file which can be included
into one or more local, site-specific configuration files.  Do not
have the Debian-packaged scripts use this default configuration file,
but only sysadmin-installed custom configuration files.  Here are more
details:

2a. /etc/awstats/default.conf
This file contains the default configuration shipped with the awstats
Debian package (currently it is called awstats.conf).

2b. Either get rid of /etc/awstats/awstats.conf.local or rename it
local.conf and change the last line of default.conf to: Include
"local.conf"

2c. Create /etc/awstats/README file that explains how the
configuration files are read.  For example:

AWStats will search this directory for any configuration file(s) of
the form awstats.*.conf, for example "awstats.mysite.conf".  See
/usr/share/doc/awstats/examples/awstats.mysite.conf for a sample
configuration file.

2d. Provide a sample configuration file in
/usr/share/doc/awstats/examples/awstats.mysite.conf which can be
copied by the sysadmin into /etc/awstats and modified for their local
requirements:

# This is a sample site-specific configuration file for AWStats.  You
# can copy it into /etc/awstats and rename it according to your site
# name.  Also change the SiteDomain parameter below to your site name
# and add any additional configuration parameters that you wish to
# override (see /etc/awstats/default.conf for a list of parameters).
# You may create several copies of this file with different names for
# multiple virtual hosts.

# Note that when a variable is defined both in a config file and in an
# included file, AWStats will use the last value read for parameters that
# contains one value and AWStats will concat all values from both files for
# parameters that are lists of values.
#
Include="default.conf"

# "SiteDomain" must contain the main domain name, or the main intranet web
# server name, used to reach the web site.
# If you share the same log file for several virtual web servers, this
# parameter is used to tell AWStats to filter record that contains 
records for
# this virtual host name only (So check that this virtual hostname can be
# found in your log file and use a personalized log format that include the
# %virtualname tag).
# But for multi hosting a better solution is to have one log file for each
# virtual web server. In this case, this parameter is only used to generate
# full URL's links when ShowLinksOnUrl option is set to 1.
# If analyzing mail log, enter here the domain name of mail server.
# Example: "myintranetserver"
# Example: "www.domain.com"
# Example: "ftp.domain.com"
# Example: "domain.com"
#
SiteDomain="mysite"

2e. Edit /usr/share/awstats/tools/buildstatic.sh and update.sh and
change

> for c in awstats \
>          `/bin/ls -1 awstats.*.conf 2>/dev/null | \
>           /bin/sed 's/^awstats\.\(.*\)\.conf/\1/'`
> do

to:

> for c in `/bin/ls -1 awstats.*.conf 2>/dev/null | \
>           /bin/sed 's/^awstats\.\(.*\)\.conf/\1/'`
> do

and add right before "-config=$c":

     -configdir=/etc/awstats

I hope this is helpful.  I am planning to implement something like the
above for the sites I manage.  I look forward to further discussion on
the handling of AWStats configuration file(s) in Debian.  It is very
tricky to get right, and what works for one might not work for
another.

Ken