awstats-update for Debian -------------------------------------------------------------------------------- OVERVIEW -------------------------------------------------------------------------------- This package is a supplement to the official Debian awstats package. You should read /usr/share/doc/awstats/README.Debian. That package includes some useful scripts in /usr/share/doc/awstats/examples, however, it requires a little work to get them running. This package, awstats-update, does most of the work for you, especially when you have several virtual hosts with each having a separate configuration file in /etc/awstats. Note that the awstats package installs a cron script for updating its database every 10 minutes, but by default it does not do anything because it does not have read access to /var/log/apache/access.log. Also note that the default awstats configuration is for apache not apache2. -------------------------------------------------------------------------------- CONTENTS -------------------------------------------------------------------------------- This package installs/updates the following components: 1. /etc/cron.daily/awstats-update 2. /usr/sbin/awstats-update 3. /usr/lib/cgi-bin/awstats The two awstats-update files are to automatically update the awstats database. The first file is a cron script that runs /usr/sbin/awstats-update every day to update your awstats database. The second file is a script that runs the following command: /usr/lib/cgi-bin/awstats.pl -config=CONFIGNAME -update for every configuration file found in /etc/awstats. See the man page awstats-update(8) for more detailed information. The last component, /usr/lib/cgi-bin/awstats, is a CGI script that lists all of the available reports (with HREF links to awstat.pl to show the report). The list of available reports is based on the names of the configuration files found in /etc/awstats. -------------------------------------------------------------------------------- SETUP -------------------------------------------------------------------------------- 1. The first requirement is proper naming of configuration files in /etc/awstats. For each of your virtual hosts (or, more generally, for each separate report you want from awstats), create a configuration file in /etc/awstats with the following name: /etc/awstats/awstat.CONFIGNAME.conf The CONFIGNAME can be anything you want. The awstats-update script and the awstats CGI script will search /etc/awstats for files named like this and process them. 2. The second requirement is that you must use __LOGROTATE__ in your configuration files for the LogFile directive. For example, instead of the following: LogFile=/var/log/apache2/access.log You should use: LogFile=/var/log/apache2/access.log__LOGROTATE__ When called, awstats will substitute __LOGROTATE__ for the environment variable LOGROTATE. This environment variable is first set to ".1" in the cron script so that entries from a rotated log file ("access.log.1") are processed before entries from the regular log file ("access.log") are processed. There is no problem with rerunning awstats on the rotated log file every day even though it is rotated weekly. AWStats will ignore old records. If you get an error message mailed from cron about a missing "access.log.1" file, it just means your log files have not yet been rotated. You can ignore the message and wait until your log file gets rotated within the next week, or you can create an empty access.log.1 file. For example: cd /var/log/apache2 touch access.log.1 chmod --reference=access.log access.log.1 chown --reference=access.log access.log.1 3. You may wish to increase the number of weeks of log files to save by editing /etc/logrotate.d/apache2 or /etc/logrotate.d/apache and change the "rotate" line as described in the man page for logrotate. Although AWStats does not need access to old log files after it has processed them, you may decide later to change your AWStats configuration file in which case you may need to delete the AWStats database files and rerun awstats on the older log files to get the newly configured statistics. 4. To configure Apache 2.0 to access the CGI scripts: cp -p /usr/share/doc/awstats-update/examples/awstats.conf \ /etc/apache2/sites-available/awstats a2ensite awstats invoke-rc.d apache2 restart or, for Apache 1.3: cp -p /usr/share/doc/awstats-update/examples/awstats.conf \ /etc/apache/conf.d/awstats invoke-rc.d apache restart You will now be able to access reports from the following URL: http://hostname/cgi-bin/awstats NOTE: when you remove this package with the --purge option, the awstats apache configuration file(s) will be deleted: /etc/apache2/sites-available/awstats* /etc/apache/conf.d/awstats* -------------------------------------------------------------------------------- NOTE ABOUT FILE OWNERSHIP -------------------------------------------------------------------------------- The log files under /var/log/apache2 are owned by root and placed in the adm group. Only root or members of the adm group are able to read these log files. For this reason, a new system user called "awstats" is created by this package and placed in the adm group. The cron script runs awstats-update as the user "awstats" so that it can read the log files. The database files under /var/lib/awstats will be placed under the group www-data and owned by the "awstats" user. This package sets the owner of that directory to "awstats", sets the group to "www-data", and sets the group sticky bit. This allows the awstats-update script running as the "awstats" user to write the database files, and allows the awstats CGI script running as the "www-data" user to read the awstats database files. -------------------------------------------------------------------------------- -- Ken Neighbors , Sun Jun 10 14:52:50 2007