Puppet awstats Module

Table of Contents

1. Overview
2. Description
3. Usage

• Examples
• Classes
• Defines

1. Reference - An under-the-hood peek at what the module is doing and how
2. Limitations
3. Versioning
4. Support
5. Contributing
6. See Also

Overview

Manages the AWStats HTTP/FTP/SMTP log analyzer

Description

"AWStats is a free powerful and featureful tool that generates advanced web, streaming, ftp or mail server statistics, graphically." -- www.awstats.org

This is a puppet module for the installation and configuration of the AWStats package. It offers comprehensive configuration file generation and limited support for the enabling AWStats plugins.

Currently, this module relies on the package to enable periodic log processing. The EPEL6package installs an hourly crontab that runs as root. This is sub-optimal for security purposes as AWStats is a complex script but understandable as historically logs have had root ownership. A future release of this module may provide for AWStats to be invoked as a non-root user.

Usage

Examples

Install awstats and configure apache

Example of configuring Apache for the AWStats CGI interface using the puppetlabs/apache module.

$loadplugin     = ['decodeutfkeys', 'geoip GEOIP_STANDARD /usr/share/GeoIP/GeoIP.dat']
$internal_hosts = 'REGEX[^192\.168\.] REGEX[^172\.16\.] REGEX[^10\.]'

include ::apache

apache::vhost { 'awstats.example.org':
  port          => '80',
  docroot       => '/usr/share/awstats/wwwroot',
  serveraliases => ['awstats'],
  aliases => [
    { alias => '/awstatsclasses', path => '/usr/share/awstats/wwwroot/classes/' },
    { alias => '/awstatscss', path => '/usr/share/awstats/wwwroot/css/' },
    { alias => '/awstatsicons', path => '/usr/share/awstats/wwwroot/icon/' },
  ],
  scriptaliases => [
    { alias => '/awstats/', path => '/usr/share/awstats/wwwroot/cgi-bin/' },
  ],
  directories   => [{
    path     => '/usr/share/awstats/wwwroot',
    provider => 'directory',
    options  => 'None',
    order    => 'Allow,Deny',
    allow    => 'from all',
    #deny    => 'from all',
  }],
  setenv        => ['PERL5LIB /usr/share/awstats/lib:/usr/share/awstats/plugins'],
}

class { '::awstats':
  config_dir_purge => true,
  enable_plugins   => [ 'DecodeUTFKeys', 'GeoIP' ],
}

# this ordering is needed for both the docroot path and so that the
# awstats package provided apache configuration snippet is purged on the
# first run
Class['::awstats'] -> Class['::apache']

Local apache log -- example 1

# apache log
awstats::conf { 'www.example.org':
  options => {
    'SiteDomain'        => 'www.example.org',
    'HostAliases'       => 'localhost 127.0.0.1 example.org',
    'LogFile'           => 'sudo -iu loguser ssh loguser@example.org sudo cat /var/log/httpd/access_log |',
    'AllowFullYearView' => 3,
    'DNSLookup'         => 1,
    'SkipHosts'         => $internal_hosts,
    'LoadPlugin'        => $loadplugin,
  },
}

Local apache log -- example 2

Defaults to processing /var/log/httpd/access_log.

# apache log
awstats::conf { 'www.example.org': }

Which is equivalent to:

# apache log
awstats::conf { 'www.example.org':
  options => { # defaults
    'LogFile'      => '/var/log/httpd/access_log',
    'LogFormat'    => '1',
    'DirData'      => '/var/lib/awstats',
    'SiteDomain'   => $::fqdn,
    'HostAliases'  => "localhost 127.0.0.1 ${::hostname}",
  },
}

Remote apache log via ssh

# apache log
awstats::conf { 'www.example.org':
  options => {
    'SiteDomain'        => 'www.example.org',
    'HostAliases'       => 'localhost 127.0.0.1 example.org',
    'LogFile'           => 'sudo -iu loguser ssh loguser@example.org sudo cat /var/log/httpd/access_log |',
    'AllowFullYearView' => 3,
    'DNSLookup'         => 1,
    'SkipHosts'         => $internal_hosts,
    'LoadPlugin'        => $loadplugin,
  },
}

Remote vsftp log via ssh

# vsftp log
awstats::conf { 'ftp.example.org':
  options => {
    'SiteDomain'        => 'ftp.example.org',
    'HostAliases'       => 'localhost 127.0.0.1 example.org',
    'LogFile'           => 'sudo -iu loguser ssh loguser@example.org sudo cat /var/log/vsftpd.log |',
    'LogFormat'         => '%time3 %other %host %bytesd %url %other %other %method %other %logname %other %code %other %other',
    'LogSeparator'      => '\s',
    'LogType'           => 'F',
    'AllowFullYearView' => 3,
    'DNSLookup'         => 1,
    'SkipHosts'         => $internal_hosts,
    'LoadPlugin'        => $loadplugin,
  },
}

Remote pureftpd log via ssh

# pureftp log
awstats::conf { 'ftp.example.org':
  options => {
    'SiteDomain'        => 'ftp.example.org',
    'HostAliases'       => 'localhost 127.0.0.1 example.org',
    'LogFile'           => 'sudo -iu loguser ssh loguser@example.org sudo cat /var/log/pureftpdstats.log |',
    'LogFormat'         => '%host %other %logname %time1 %methodurlnoprot %code %bytesd',
    'LogSeparator'      => '\s',
    'LogType'           => 'F',
    'AllowFullYearView' => 3,
    'DNSLookup'         => 1,
    'SkipHosts'         => $internal_hosts,
    'LoadPlugin'        => $loadplugin,
  },
}

Classes

awstats

# defaults
class { '::awstats':
  config_dir_purge => false,
  enable_plugins   => [],
}

config_dir_purge

Boolean Default to: false

If set to true, unmanaged files in the configuration directory path, typically /etc/awstats/ are purged.

enable_plugins

Array Defaults to: []

A case insensitive list of awstats plugins to enable "support" for by installing required dependencies. The supported plugins are:

• decodeutfkeys
• geoip

Defines

awstats::conf

# defaults
awstats::conf { '<title>':
  template => undef,
  options  => {},
}

template

String Defaults to undef

The path to the puppet ERB template to use to generate the configuration file. A value of undef is equivalent to ${module_name}/awstats.conf.erb.

options

Hash Defaults to {}

A hash of awstats configuration file options. The case of keys is preserved and no validation of what is or isn't a valid awstats directive is performed. The options hash is merged with these default values, which were determined to be the minimum set of required parameters via trial and error with EPEL6 awstats-7.0-3.el6.noarch package. Please see the comments in conf.pp for further details.

  $default_options = {
    'LogFile'      => '/var/log/httpd/access_log',
    'LogFormat'    => '1',
    'DirData'      => '/var/lib/awstats',
    'SiteDomain'   => $::fqdn,
    'HostAliases'  => "localhost 127.0.0.1 ${::hostname}",
  }

If a hash value is an array, multiple configuration file options with the same key name will be created. Eg.

  options => {
    'LoadPlugin' => ['foo', 'bar'],
  }

Would result in the following options in the configuration file. Note that the order is sorted.

LoadPlugin="bar"
LoadPlugin="foo"

Reference

See REFERENCE

Limitations

This module has been developed around the awstats version 7 package from EPEL6. A bit unfortunately, that package runs awstats.pl from cron as root. Rather than fighting the package, that decision has been left in place but may be revised in a future version of this module.

Versioning

This module is versioned according to the Semantic Versioning 2.0.0 specification.

Support

Please log tickets and issues at github

Contributing

1. Fork it on github
2. Make a local clone of your fork
3. Create a topic branch. Eg, feature/mousetrap
4. Make/commit changes

• Commit messages should be in imperative tense
• Check that linter warnings or errors are not introduced - bundle exec rake lint
• Check that Rspec-puppet unit tests are not broken and coverage is added for new features - bundle exec rake spec
• Documentation of API/features is updated as appropriate in the README
• If present, beaker acceptance tests should be run and potentially updated - bundle exec rake beaker

1. When the feature is complete, rebase / squash the branch history as necessary to remove "fix typo", "oops", "whitespace" and other trivial commits
2. Push the topic branch to github
3. Open a Pull Request (PR) from the topic branch onto parent repo's master branch

See Also

• www.awstats.org
• puppetlabs/apache

Reference

Table of Contents

Classes

Public Classes

• awstats: Install and configure awstats

Private Classes

• awstats::plugin::decodeutfkeys
• awstats::plugin::geoip

Defined types

• awstats::conf: manage awstats config file

Classes

awstats

Install and configure awstats

Parameters

The following parameters are available in the awstats class:

• owner
• group
• config_dir_path
• packages
• config_dir_purge
• enable_plugins

owner

Data type: String

awstats role user.

group

Data type: String

awstats role group.

config_dir_path

Data type: Stdlib::Absolutepath

Path of the awstats configuration directory.

packages

Data type: Optional[Array[String[1]]]

List of packages to install.

Default value: undef

config_dir_purge

Data type: Boolean

Default to: false

If set to true, unmanaged files in the configuration directory path, typically /etc/awstats/ are purged.

Default value: false

enable_plugins

Data type: Array[String]

Defaults to: []

A case insensitive list of awstats plugins to enable "support" for by installing required dependencies. The supported plugins are:

• decodeutfkeys
• geoip

Default value: []

Defined types

awstats::conf

# defaults
awstats::conf { '<title>':
  template        => undef,
  options         => {},
}

  $default_options = {
    'LogFile'     => '/var/log/httpd/access_log',
    'LogFormat'   => '1',
    'DirData'     => '/var/lib/awstats',
    'SiteDomain'  => $::fqdn,
    'HostAliases' => "localhost 127.0.0.1 ${::hostname}"
  }

If a hash value is an array, multiple configuration file options with the same key name will be created. Eg.

  options         => {
    'LoadPlugin'  => ['foo', 'bar'],
  }

Would result in the following options in the configuration file. Note that the order is sorted.

LoadPlugin="bar"
LoadPlugin="foo"

Parameters

The following parameters are available in the awstats::conf defined type:

• template
• options

template

Data type: Optional[String]

Defaults to undef

The path to the puppet ERB template to use to generate the configuration file.

A value of undef is equivalent to ${module_name}/awstats.conf.erb.

Default value: undef

options

Data type: Hash

Defaults to {}

A hash of awstats configuration file options. The case of keys is preserved and no validation of what is or isn't a valid awstats directive is performed. The options hash is merged with these default values, which were determined to be the minimum set of required parameters via trial and error with EPEL6 awstats-7.0-3.el6.noarch package.

Default value: {}