Forge Home

awstats

Manages the AWStats HTTP/FTP/SMTP log analyzer

10,993 downloads

363 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 1.0.0 (latest)
  • 0.1.0
released Aug 19th 2022
This version is compatible with:
  • Puppet Enterprise 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x
  • Puppet >= 6.0.0 < 8.0.0
  • , , , , , ,

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'jhoblitt-awstats', '1.0.0'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add jhoblitt-awstats
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install jhoblitt-awstats --version 1.0.0

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

jhoblitt/awstats — version 1.0.0 Aug 19th 2022

Puppet awstats Module

CI

Table of Contents

  1. Overview
  2. Description
  3. Usage
  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