Puppet module ssm-munin

Table of Contents

• Puppet module ssm-munin
• Overview
• Module Description
• Setup
  • Setup requirements
• Usage
  • munin::node
  • munin::master
  • munin::master::node_definition
  • munin::plugin
• Examples
  • munin::master::node_definition
    • Static node definitions
    • node definitions as class parameter
    • node definitions with hiera
  • munin::node
    • Allow remote masters to connect
  • munin::plugin
    • Activate a plugin
    • Install and activate a plugin
    • Activate wildcard plugin
    • Plugin with configuration
    • A plugin configuration file

Overview

Configure munin master, node and plugins.

Module Description

This module installs the munin master using the munin::master class, munin node using the munin::node class, and can install, configure and manage munin plugins using the munin::plugin defined type.

Munin nodes are automatically exported by the munin nodes, and collected on the munin master. (Requires puppetdb)

Setup

Classify all nodes with munin::node, and classify at least one node with munin::master. Use the munin::plugin defined type to control plugin installation and configuration.

Setup requirements

Munin should be available in most distributions. For RedHat OS Family, you need to install the EPEL source.

The munin::master class does not manage any web server configuration. The munin package installed might add some.

Usage

For detailed usage, see the reference.

munin::node

Typical usage

include munin::node

Installs a munin node.

By default, munin::node exports a munin node definition so a node classified with the munin::master class can collect it.

Export extra nodes

If munin::node::export_node is enabled, you may export additional nodes with the munin::node::export::node_definitions hash. These are exported as munin::master::node_definition resources. They will be associated with the same mastername as the node itself.

munin::master

Typical usage:

include munin::master

Installs a munin master.

By default, munin::master collects all munin node definitions exported by nodes classified with munin::node.

munin::master::node_definition

This will add configuration for the munin master to connect to a munin node, and ask for data from its munin plugins.

Note: By default, the node classified with munin::master will collect all all exported instances of this type from hosts classified with munin::node.

The resource title is used as the munin FQN, or "fully qualified name". This defines the node name and group. It is common to use the host's fully qualified domain name, where the domain name will be implicitly used as the node group.

For more information about configuring a munin node definition, see https://munin.readthedocs.io/en/latest/reference/munin.conf.html#node-definitions

If you have multiple munin master servers in your infrastructure and want to assign different nodes to different masters, you can specify the master's fully qualified domain name on the node's definition:

munin::master::node_definition { 'fqn':
    address    => $address,
    mastername => 'munin.example.com',
}

Examples

munin::master::node_definition

Static node definitions

The munin master class will collect all "munin::master::node_definition" exported by "munin::node".

For extra nodes, you can define them in hiera data for the master server, and munin::master will create them. Example:

munin::master::node_definition { 'foo.example.com':
  address => '192.0.2.1'
}
munin::master::node_definition { 'bar.example.com':
  address => '192.0.2.1',
  config  => [ 'load.graph_future 30',
               'load.load.trend yes',
               'load.load.predict 86400,12' ],
}

See also munin::node::export::node_definitions for extra nodes declared on the clients.

node definitions as class parameter

If you define your nodes as a data structure in a puppet manifest, or from the puppet External Node Classifier, you can use a class parameter:

$nodes = { ... }

class { 'puppet::master':
  node_definitions => $nodes,
}

node definitions with hiera

A JSON definition.

{
  "munin::master::node_definitions" : {
    "foo.example.com" : {
      "address" : "192.0.2.1"
    },
    "bar.example.com" : {
      "address" : "192.0.2.2",
      "config" : [
        "load.graph_future 30",
        "load.load.trend yes",
        "load.load.predict 86400,12"
      ]
    }
  }
}

A YAML definition

---
munin::master::node_definitions:
  foo.example.com:
    address: 192.0.2.1
  bar.example.com:
    address: 192.0.2.2
    config:
    - load.graph_future 30
    - load.load.trend yes
    - load.load.predict 86400,12

munin::node

Allow remote masters to connect

The allow parameter enables the munin master to connect. By default, the munin node only permits connections from localhost.

class { 'munin::node':
    allow => [ '192.0.2.0/24', '2001:db8::/64' ]
}

or in hiera:

---
munin::node::allow:
  - 192.0.2.0/24
  - 2001:db8::/64

Installs munin-node, and exports a munin::master::node_definition which munin::master will collect, and allows munin masters on specified networks to connect.

munin::plugin

Activate a plugin

Here, we activate an already installed plugin.

The use of "ensure => link" creates an implicit "target => /usr/share/munin/plugins/$title".

The "target" parameter can be set to an absolute path (starting with a "/"), or a relative path (anything else). If relative, $munin::params::node::plugin_share_dir is prepended to the path.

munin::plugin {
  'apt':
    ensure => link;
  'something':
    ensure => link,
    target => '/usr/local/share/munin/plugins/something';
  'ip_eth0':
    ensure => link,
    target => 'ip_'; # becomes $munin::params::node::plugin_share_dir/ip_
}

Install and activate a plugin

The use of "ensure => present" creates a file in /etc/munin/plugins

munin::plugin { 'somedaemon':
    ensure => present,
    source => 'puppet:///modules/munin/plugins/somedaemon',
}

Activate wildcard plugin

A pair of plugins we provide, with a _name symlink (This is also known as "wildcard" plugins)

munin::plugin {
  'foo_bar':
    ensure => present,
    target => 'foo_',
    source => 'puppet:///modules/munin/plugins/foo_';
  'foo_baz':
    ensure => present,
    target => 'foo_',
    source => 'puppet:///modules/munin/plugins/foo_';
}

Plugin with configuration

This creates an additional "/etc/munin/plugin-conf.d/${title}.conf"

munin::plugin {
  'bletch':
    ensure => link,
    config => 'env.database flumpelump';
  'thud':
    ensure => present,
    source => 'puppet:///modules/munin/plugins/thud',
    config => ['env.database zotto', 'user root'];
}

A plugin configuration file

This only adds a plugin configuration file.

munin::plugin { 'slapd':
  config       => ['env.rootdn cn=admin,dc=example,dc=org'],
  config_label => 'slapd_*',
}

Reference

Table of Contents

Classes

Public Classes

• munin::master: configure a munin master
• munin::node: configure a munin node

Private Classes

• munin::master::collect: Helper class to collect the exported munin nodes.
• munin::node::export: Helper class to export the munin node.

Defined types

• munin::master::node_definition: Configure information about a munin node on the munin master
• munin::plugin: Install and configure munin plugins

Classes

munin::master

The munin master will install munin, and collect all exported munin node definitions as files into /etc/munin/munin-conf.d/.

Parameters:

'unclaimed' makes the munin master collect nodes not tagged with a host name.

This is used for collecting munin::master::node_definition resources exported by nodes using the munin::node class.

• See also http://guide.munin-monitoring.org/en/latest/

Examples

Basic usage

include munin::master

With TLS

class { 'munin::master':
  tls             => 'enabled',
  tls_certificate => '/path/to/tls/certificate',
  tls_private_key => '/path/to/tls/key',
}

Parameters

The following parameters are available in the munin::master class.

node_definitions

Data type: Hash

A hash of node definitions used by create_resources to make static node definitions.

host_name

Data type: Stdlib::Host

A host name for this munin master, matched with munin::node::mastername for collecting nodes. Defaults to $::fqdn

This is used for collecting munin::master::node_definition resources exported by nodes using the munin::node class.

graph_strategy

Data type: Enum['cgi', 'cron']

Controls if munin-graph graphs all services ('cron') or if graphing is done by munin-cgi-graph (which must configured seperatly)

html_strategy

Data type: Enum['cgi', 'cron']

Controls if munin-html will recreate all html pages every run interval ('cron') or if html pages are generated by munin-cgi-graph (which must configured seperatly). Defaults to "cgi".

config_root

Data type: Stdlib::Absolutepath

The root directory of the munin master configuration. Default: /etc/munin on most platforms.

file_group

Data type: String

The group name for configuration file permissions.

collect_nodes

Data type: Enum['enabled', 'disabled', 'mine', 'unclaimed']

Controls which nodes to collect.

'enabled' (default) makes the munin master collect all exported node_definitions.

'disabled' disables collection.

'mine' makes the munin master collect nodes matching the $host_name parameter.

dbdir

Data type: Optional[Stdlib::Absolutepath]

Path to the munin dbdir, where munin stores everything.

htmldir

Data type: Optional[Stdlib::Absolutepath]

Path to where munin will generate HTML documents and graphs, used if graph_strategy is cron.

rundir

Data type: Optional[Stdlib::Absolutepath]

Path to directory munin uses for pid and lock files.

logdir

Data type: Optional[Stdlib::Absolutepath]

Path to directory munin uses for log files.

package_name

Data type: Variant[String,Array[String]]

The package name used for installing the munin master.

tls

Data type: Enum['enabled', 'disabled']

Controls the use of TLS globally for master to node communications. Default 'disabled'.

tls_certificate

Data type: Stdlib::Absolutepath

Path to a file containing a TLS certificate. No default. Required if tls is enabled.

tls_private_key

Data type: Stdlib::Absolutepath

Path to a file containing a TLS key. No default. Required if tls is enabled.

tls_verify_certificate

Data type: Enum['yes','no']

If TLS is used, verify the certificate. Defaults to 'yes'.

extra_config

Data type: Array[String]

Extra lines of config to put in munin.conf.

munin::node

Configure a munin node, and export configuration a munin master can collect.

• See also http://guide.munin-monitoring.org/en/latest/

Examples

Basic usage

include munin::node

Parameters

The following parameters are available in the munin::node class.

allow

Data type: Array

List of IPv4 and IPv6 addresses and networks to allow to connect.

config_root

Data type: Stdlib::Absolutepath

Root directory for munin configuration.

nodeconfig

Data type: Array

List of lines to append to the munin node configuration.

host_name

Data type: Stdlib::Host

The host name munin node identifies as. Defaults to the $::fqdn fact.

log_dir

Data type: Stdlib::Absolutepath

The log directory for the munin node process. Defaults change according to osfamily, see munin::params::node for details.

log_file

Data type: String

File name for the log file, this is appended to "log_dir". Defaults to "munin-node.log".

log_destination

Data type: Enum['file','syslog']

Configures the log destination. Defaults to "file". If set to "syslog", the "logfile" and "log_dir" parameters are ignored, and the "syslog*" parameters are used if set.

purge_configs

Data type: Boolean

Removes all munin plugins and munin plugin configuration files not managed by Puppet. Defaults to false.

syslog_facility

Data type: Optional[ Variant[ Integer[0,23], Enum[ 'kern','user','mail','daemon','auth','syslog','lpr','news','uucp', 'authpriv','ftp','cron','local0','local1','local2','local3','local4', 'local5','local6','local7' ]]]

Defaults to undef, which makes munin-node use the perl Net::Server module default of "daemon". Possible values are any syslog facility by number, or lowercase name.

export_node

Data type: Enum['enabled','disabled']

Causes the node config to be exported to puppetmaster. Defaults to "enabled".

This is used for exporting a munin::master::node_definition, to be collected by a node with munin::master.

masterconfig

Data type: Array

List of configuration lines to append to the munin master node definition.

This is used for exporting a munin::master::node_definition, to be collected by a node with munin::master.

mastername

Data type: Optional[Stdlib::Host]

The name of the munin master server which will collect the node definition.

This is used for exporting a munin::master::node_definition, to be collected by a node with munin::master.

mastergroup

Data type: Optional[String]

The group used on the master to construct a FQN for this node. Defaults to "", which in turn makes munin master use the domain. Note: changing this for a node also means you need to move rrd files on the master, or graph history will be lost.

This is used for exporting a munin::master::node_definition, to be collected by a node with munin::master.

plugins

Data type: Hash

A hash used by create_resources to create munin::plugin instances.

address

Data type: String

The address used in the munin master node definition.

bind_address

Data type: Variant[Enum['*'],Stdlib::Host]

The IP address the munin-node process listens on. Defaults: *.

bind_port

Data type: Stdlib::Port

The port number the munin-node process listens on.

package_name

Data type: String

The name of the munin node package to install.

service_name

Data type: String

The name of the munin node service.

service_ensure

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

Used as parameter "ensure" for the munin node service.

file_group

Data type: String

The UNIX group name owning the configuration files, log files, etc.

timeout

Data type: Optional[Integer[0]]

Set the global plugin runtime timeout for this node. Defaults to undef, which lets munin-node use its default of 10 seconds.

Default value: $munin::params::node::timeout

Defined types

munin::master::node_definition

This will add configuration for the munin master to connect to a munin node, and ask for data from its munin plugins.

The resource title is used as the munin FQN, or "fully qualified name". This defines the node name and group. It is common to use the host's fully qualified domain name, where the domain name will be implicitly used as the node group.

Note: By default, using munin::node on a node will create a export a munin::master::node_definition to PuppetDB. The node classified with munin::master will collect all these exported instances.

Examples

Typical usage

munin::master::node_definition { 'host.example.com':
    address => $address,
    config  => ['additional', 'configuration' 'lines'],
}

Using a group in the FQN

munin::master::node_definition { 'webservers;web01.example.com':
    address => $address,
    config  => ['additional', 'configuration' 'lines'],
}

Parameters

The following parameters are available in the munin::master::node_definition defined type.

address

Data type: String

The address of the munin node. A hostname, an IP address, or a ssh:// uri for munin-async node.

mastername

Data type: Optional[String]

The name of the munin master server which will collect the node definition. This is used when exporting and collecting munin::master::node_definition resources between hosts.

Default value: ''

config

Data type: Array[String]

An array of configuration lines to be added to the node definition.

Default value: []

fqn

Data type: String

The Munin FQN (Fully Qualified Name) of the node. This should be 'hostname', 'group;hostname', 'group;subgroup;hostname').

If a group is not set, munin will by default use the domain of the node as a group, if the node name is a fully qualified host name.

The title of the defined resource should be a munin FQN. See the "fqn" parameter

Default value: $title

munin::plugin

Install and configure munin plugins

Examples

Activate a packaged plugin

munin::plugin { 'cpu':
  ensure => link,
}

Activate a packaged wildcard plugin

munin::plugin { 'foo_bar':
  ensure => link,
  target => 'foo_',
}

Install and activate a plugin

munin::plugin { 'gazonk':
  ensure => present,
  source => 'puppet:///modules/profile/foo/monitoring/gazonk',
}

A plugin with configuration

munin::plugin { 'bletch':
  ensure => link,
  config => ['env.database thing', 'user bletch'],
}

A plugin configuration file, but no plugin

munin::plugin { 'slapd':
  config       => ['env.rootdn cn=admin,dc=example,dc=org'],
  config_label => 'slapd_*',
}

Parameters

The following parameters are available in the munin::plugin defined type.

ensure

Data type: Enum['','present','absent','link']

The ensure parameter is mandatory for installing a plugin.

With "ensure => link", a symlink is created in the munin plugin directory to where the plugin file is installed.

With "ensure => present", the plugin is installed in the munin plugin directory, and the "source" parameter is required to provide a source for the plugin.

With "ensure => absent", remove the munin plugin.

When ensure is not set, a plugin will not be installed, but extra plugin configuration can be managed with the config and config_label parameters.

Default value: ''

source

Data type: Optional[String]

When ensure => present, path to a source file

Default value: undef

target

Data type: String

When "ensure => link", Add a link in the plugin directory to the link target.

If target is an absolute path (starts with "/") it is used directly.

If target is a relative path, $munin::node::plugin_share_dir is prepended.

If target is unset, a link is created to a plugin with the same name in the packaged $munin::node:: plugin_share_dir directory. (In other words, activate a plugin that is already installed)

Default value: ''

config

Data type: Optional[Array[String]]

Lines for the munin plugin config.

Default value: []

config_label

Data type: String

Label for munin plugin config

Default value: $title

Changelog

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

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

0.3.0 - 2020-06-29

Changed

• Replaced params classes with module hieradata.
• Replaced function based parameter validation with Puppet Types.
• Require puppetlabs/stdlib version 4.25.0 to support the types used.
• Allow puppetlabs/stdlib < 7.0.0.
• Allow Puppet version < 7.0.0.
• Changed parameter munin::plugin::config default value from undef to [].
• Converted some templates from erb to epp.

Added

• New parameter munin::master::node_definition::fqn. This is the namevar for the defined type, and will default to the value of the title.
• Added support for osfamily RedHat version 8
• Added Puppet Strings documentation

Deprecated

• Module is no longer supported on Puppet versions before 4.10.0
• Module is no longer supported on osfamily RedHat version 5
• Module is no longer supported on osfamily RedHat version 6
• Module is no longer supported on Ubuntu 14.04

0.2.0 - 2019-03-03

Added

• Support for DragonFly BSD (#46)
• Support for FreeBSD as master (#46)
• Export additional nodes with munin::node::export::node_definitions if munin::node::export_node is enabled. (#44)
• New parameter munin::master::package_name
• New parameter munin::master::file_group
• New parameter munin::master::config_root

Changed

• Support puppet 4 and newer. (#49)
• Scaffolding updated with PDK 1.9.0

Fixed

• Support for Arch Linux (#53)
• Fixed bug with parameter munin::master::node_definitions

Deprecated

• Module is no longer tested with Puppet 3.x and 2.x
• Module is no longer tested on Ruby < 2.1.9

0.1.0 - 2015-12-12

• Added support for Archlinux (#40)
• Added acceptance tests
• Added CONTRIBUTING.md for how to contribute to the module (#41)
• Document all parameters in README.md

munin::node

• Two new parameters: bind_address and bind_port (#37)
• Bugfix: Rescue InvalidAddressError only if ruby is capable (#38)

contributors

Contributors to this release: David Hayes, Julien Pivotto, Stig Sandbeck Mathisen, Victor Engmark

0.0.10 - 2015-08-01

• Bugfix: Add missing dependency for the "munin-node" package when $munin::node::purge_configs is true. (#34)

Contributors to this release: Martin Meinhold

0.0.9 - 2015-07-29

• Bugfix: The mastergroup, if used in the node's FQN (Fully Qualified Name), should no longer be empty on Puppet 4.0. (#27)

• Bugfix: Using munin::master and munin::node with export and collect disabled should no longer trigger warnings about missing storeconfigs. (#30, #33)

munin::master

• Add FreeBSD support.

munin::node

• New feature: Log to syslog with the "log_destination" and "syslog_facility" parameters. (#23, #24, #25)

• New feature: Set the plugin runtime timeout with the "timeout" parameter. (#29, #32)

• New feature: Purge unmanaged plugins and plugin configuration with the "purge_configs" parameter. (#28, #31)

0.0.8 - 2015-02-06

Support the future parser.

Contributors to this release: Rike-Benjamin Schuppner, Stig Sandbeck Mathisen

0.0.7 - 2014-12-05

This release adds support for DragonFly BSD, FreeBSD, OpenBSD.

Other changes listed below, per component.

Contributors to this release: Alex Hornung, Chris Roddy, Frank Groeneveld, Fredrik Thulin, Julien Pivotto, Martin Jackson, Sebastian Wiesinger, Stig Sandbeck Mathisen

munin::node

• Add "host_name" parameter to override the host name of the munin node.

• Add "file_group" parameter, used for configuration and log files.

• Add "log_dir" parameter.

• Improved handling of "allow" ACL parameter.

munin::master

• Improved collection logic. Set "collect_nodes" to "mine" to collect nodes which are targeted for this master, or "unclaimed" to pick up nodes not aimed a specific master.

• Add global tls_* parameters for connecting to nodes.

• Add "dbdir", "htmldir", "rundir" parameters.

• Add "extra_config" parameter, which takes an array of extra configuration lines for munin.conf.

munin::plugin

• Support absolute paths as target for a plugin.

0.0.6 - 2014-12-05

• Retracted, had a breaking bug on older (3.4.x) puppet versions.

0.0.5 - 2014-03-19

• Support multiple masters with different nodes (Thanks: Cristian Gae)

• Support older (1.4.6) munin versions (Thanks: Sergio Oliveira)

• Update for compatibility with puppet 3.4 (Thanks: Harald Skoglund)

• Easier configuration with more parameters. All parameters have trivial validation.

munin::master

• new parameter "config_root". Defaults should match supported operating systems.

munin::plugin

• new parameter "config_root". Defaults should match supported operating systems.

munin::node

• new parameter "address". Default is $::fqdn. This will be used as the "address" when registering with the munin master.

• new parameter "config_root". Defaults should match supported operating systems.

• new parameter "package_name". Default should match supported operating systems.

• new parameter "service_name". Default should match supported operating systems.

• new parameter "service_ensure". Default is "". Possible values: "", "running" or "stopped".

munin::params

• new class

0.0.4 - 2013-08-13

Bugfix for the munin::plugin define.

• Bugfix: Ensure that we can run tests on ruby 1.8.

• Bugfix: No longer requires the class Munin::Plugins, which does not exist in this module. (#3)

• The ensure attribute no longer defaults to "link". If not set, a potentially existing plugin with the same name is not touched.

• Plugin and configuration directories are now configurable.

• Improved rspec tests, which now actually match the documentation.

0.0.2 - 2013-06-31

A few pull requests

• Bugfix: Install munin package before creating munin-conf.d directory (#1)

• Make graph strategy configurable (#2)

• Improve documentation

0.0.1 - 2013-06-02

Initial release