atop

master branch:

Table of Contents

1. Description
2. Setup - The basics of getting started with atop
   • What atop affects
   • Setup requirements
   • Beginning with atop
3. Usage - Configuration options and additional functionality
4. Reference
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module
7. Acknowledgements

Description

This module manages the installation, configuration and state of the system and process monitor services provided by the atop package.

The best description of what atop does comes directly from the atop web site:

Atop is an ASCII full-screen performance monitor for Linux that is capable of reporting the activity of all processes (even if processes have finished during the interval), daily logging of system and process activity for long-term analysis, highlighting overloaded system resources by using colors, etc. At regular intervals, it shows system-level activity related to the CPU, memory, swap, disks (including LVM) and network layers, and for every process (and thread) it shows e.g. the CPU utilization, memory growth, disk utilization, priority, username, state, and exit code.

For more detailed information and documentation concerning atop, please see:

• https://www.atoptool.nl
• https://github.com/Atoptool/atop

Setup

What atop affects

The module installs and configures the atop service. Additionally, atop can also use process accounting provided by the kernel. Depending on the operating system, defaults have been put in place to allow for both atop and atopacctd services to run at startup. This includes the installation and configuration of the operating system appropriate package and service for processing accounting. Please see the data directory for how each operating system will be configured.

The atop module optionally allows for inclusion of the epel class for the installation of the atop package. By default, inclusion of epel on RedHat family systems is disabled assuming that it is managed elsewhere in puppet or content management system like Spacewalk.

Setup Requirements

This module was written for Puppet 5/6 and depends on the following modules:

• puppetlabs/stdlib
• stahnma/epel (if manage_epel => true)

Beginning with atop

include atop should be enough to get the atop service up and running with process accounting enabled.

Usage

All parameters for the atop module are contained in the main atop class. In order to see how to provide the parameters via hiera, see the hiera.yaml file and the data directory.

Some examples of using the module:

Install and configure atop, process accounting and epel on 'osfamily == RedHat'

class { 'atop':
  manage_epel => true,
}

Install and configure atop but no process accounting pieces

class { 'atop':
  manage_package                 => true,
  manage_service_atop            => true,
  mamage_service_atopacctd       => false,
  process_accting_package_manage => false,
  process_accting_service_manage => false,
}

Reference

Puppet strings generated documentation is available in the docs directory and at https://millerjl1701.github.io/millerjl1701-atop. Also, the puppet strings generated REFERENCE.md file is provided.

Limitations

For Debian based operating systems, testing via travis of atopacctd is currently disabled as atopacctd does not run in containers correctly. This was discussed in: https://github.com/Atoptool/atop/issues/11

The atop program supports a large number of configurable options in /etc/atoprc and ~/.atoprc files. This module currently does not support these files.

This module does not currently handle the installation and configuration of the pieces needed for per-process network statistics. Also on the todo list are development of tasks for remotely querying atop performance metrics as well as the use of atopsar.

Development

This module uses the Puppet Development Kit for developing, validating, and testing the module. In addition to running acceptance tests locally using vagrant/virtualbox, GitHub Travis CI tests are performed according to the .travis.yml file.

Acknowledgements

The atop system and process monitor is authored and maintained by Gerlof Langeveld gerlof.langeveld@atoptool.nl. Thank you for providing us with this tool!

Reference

Table of Contents

Classes

Public Classes

• atop: Main class that includes private classes (repo, install, config, service).

Private Classes

• atop::config: This class is called from the main class to configure the atop service.
• atop::install: This class is called from the main class to install atop.
• atop::repo: This class is called from the main class to add epel if desired.
• atop::service: This class is called from the main class to manage the atop service.

Classes

atop

Main class that includes private classes (repo, install, config, service).

Examples

include atop

Parameters

The following parameters are available in the atop class.

defaults_file

Data type: Stdlib::Unixpath

Path to the atop defaults configuration file. Default value on RedHat: '/etc/sysconfig/atop'. Default value on Debian: '/etc/default/atop'.

defaults_file_template

Data type: String

Specifies the ERB template to use for the defaults file. Default value: 'atop/atop_defaults.erb'. There are other operating system version specific defaults template depending on the version of atop installed.

loggenerations

Data type: Integer

Specifies the number of days of logfiles to keep. Default value: 28.

loginterval

Data type: Integer

Specifies the interval in seconds. Default value: 600.

logopts

Data type: String

Speficies the default options for the atop service. Default value: '-R'.

manage_epel

Data type: Boolean

Whether or not to manage epel on the system. Default value: false.

manage_package

Data type: Boolean

Whether or not to manage the installation of the atop package. Default value: true.

manage_service_atop

Data type: Boolean

Whether or not to manage the atop service. Default value: true.

manage_service_atopacctd

Data type: Boolean

Whether or not to manage the atopacctd service. Default value: true.

package_ensure

Data type: String

Whether to install the atop package, and what version to install. Default value: 'present'. Values: 'present', 'latest', 'absent', or a specific version number.

package_name

Data type: String

Specifies the name of the atop package to manage. Default value: 'atop'.

process_accting_package_ensure

Data type: String

Whether to install the psacct (acct on Debian) package for process accounting and what version. Default value: 'present'.

process_accting_package_manage

Data type: Boolean

Whether or not to manage the process acounting package. Default value: true.

process_accting_package_name

Data type: String

Specifies the name of the process accounting package to manage. Default value on RedHat: 'psacct'. Default value on Debian: 'acct'.

process_accting_service_ensure

Data type: String

Whether the process accounting service should be running. Varies depending on whether or not atopacct need this running as well.

process_accting_service_enable

Data type: Boolean

Whether to enable the process accounting service at boot. Varies depending on whether or not atopacct need this running as well.

process_accting_service_manage

Data type: Boolean

Whether or not to manage the process accounting service. Default value: true.

process_accting_service_name

Data type: String

Specifies the name of the process accounting service. Varies depending on the operating system, but defaults to 'psacct'.

service_atop_enable

Data type: Boolean

Whether to enable the atop service at boot. Default value: true.

service_atop_ensure

Data type: Enum['running', 'stopped']

Whether the atop service should be running. Default value: 'running'.

service_atop_name

Data type: String

Specifies the name of the atop service. Default value: 'atop'.

service_atopacctd_enable

Data type: Boolean

Whether to enable the atopacctd daemon. Varies depending on the operating system.

service_atopacctd_ensure

Data type: Enum['running', 'stopped']

Whether the atopacctd service should be running. Varies depending on the operating system.

service_atopacctd_name

Data type: String

Specifies the name of the atopacctd service. Default value: 'atopacct'.

Changelog

All notable changes to this project will be documented in this file.

Release 1.0.1

• Fixed puppet linting error on atop::service class
• Modifications to metadata.json from pdk build process
• README.md section renamed
• Modified .travis.yml file to match closer what is being done by pdk, Puppetlabs, and Voxpupuli

Release 1.0.0

• Initial release