module-icinga2/README.md

puppet-icinga2

Table of Contents

1. Overview - What is the Icinga 2 module?
2. Module Description - What does the module do?
3. Setup - The basics of getting started with the Icinga 2 module
4. Usage - How to use the module for various tasks
   • Object type usage
   • Objects
5. Reference - The classes and defined types available in this module
6. Limitations - OS compatibility, etc.
7. Development - Guide for contributing to the module
8. Contributors - List of module contributors

Overview

This module installs and configures the Icinga 2 monitoring system. It can also install and configure NRPE on client systems that are being monitored by an Icinga 2 server.

Module Description

Coming soon...

Setup

This module should be used with Puppet 3.6 or later. It may work with earlier versions of Puppet 3 but it has not been tested.

This module requires Facter 2.2 or later, specifically because it uses the operatingsystemmajrelease fact.

This module requires the Puppet Labs stdlib module.

For Ubuntu systems, this module requires the Puppet Labs apt module.

On EL-based systems (CentOS, Red Hat Enterprise Linux, Fedora, etc.), the EPEL package repository is required.

If you would like to use the icinga2::object defined types as exported resources, you'll need to have your Puppet master set up with PuppetDB. See the Puppet Labs documentation for more info: Docs: PuppetDB

###Server requirements

Icinga 2 requires either a MySQL or a Postgres database.

Currently, this module does not set up any databases. You'll have to create one before installing Icinga 2 via the module.

If you would like to set up your own database, either of the Puppet Labs MySQL or Postgres modules can be used.

The example below shows the Puppet Labs Postgres module being used to install Postgres and create a database and database user for Icinga 2:

  class { 'postgresql::server': }

  postgresql::server::db { 'icinga2_data':
    user     => 'icinga2',
    password => postgresql_password('icinga2', 'password'),
  }

For production use, you'll probably want to get the database password via a Hiera lookup so the password isn't sitting in your site manifests in plain text.

Usage

###General Usage

####icinga2::conf

This defined type creates custom files in the /etc/icinga2/conf.d directory.

The icinga2::conf type has target_dir, target_file_name, target_file_owner, target_file_group and target_file_mode parameters just like the icinga2::object types.

The content of the file can be managed with two parameters:

• template is an ERB tmplate to use for the content (ie. site/icinga2/baseservices.conf.erb)
• source is the file server source URL for a static file (ie. puppet:///modules/site/icinga2/baseservices.conf)

To dynamically manage the variables of your template, use the options_hash parameter. It can be given a hash of data that is accessible in the template.

Example usage:

icinga2::conf { 'baseservices':
  template     => 'site/icinga2/baseservices.conf.erb',
  options_hash => {
    enable_notifications => true,
    check_interval       => '5',
    groups               => [ 'all-servers' , 'linux-servers' ],
  }
}

###Server usage

To install Icinga 2, first set up a MySQL or Postgres database.

Once the database is set up, use the icinga2::server class with the database connection parameters to specify

#Install Icinga 2:
class { 'icinga2::server': 
  server_db_type => 'pgsql',
  db_host => 'localhost'
  db_port => '5432'
  db_name => 'icinga2_data'
  db_user => 'icinga2'
  db_password => 'password',
}

When the server_db_type parameter is set, the right IDO database connection packages are automatically installed and the schema is loaded.

If you want to use Debmon repository for Debian 7, you have to set use_debmon_repo to true when you call icinga2::server class.

Note: For production use, you'll probably want to get the database password via a Hiera lookup so the password isn't sitting in your site manifests in plain text:

#Install Icinga 2:
class { 'icinga2::server':
  server_db_type => 'pgsql',
  db_host => 'localhost'
  db_port => '5432'
  db_name => 'icinga2_data'
  db_user => 'icinga2'
  db_password => hiera('icinga_db_password_key_here'),
}

You'll also need to add an IDO connection object that has the same database settings and credentials as what you entered for your icinga2::server class.

You can do this by applying either the icinga2::object::idomysqlconnection or icinga2::object::idopgsqlconnection class to your Icinga 2 server, depending on which database you're using.

An example icinga2::object::idopgsqlconnection class is below:

icinga2::object::idopgsqlconnection { 'postgres_connection':
   target_dir => '/etc/icinga2/features-enabled',
   target_file_name => 'ido-pgsql.conf',
   host             => '127.0.0.1',
   port             => 5432,
   user             => 'icinga2',
   password         => 'password',
   database         => 'icinga2_data',
   categories => ['DbCatConfig', 'DbCatState', 'DbCatAcknowledgement', 'DbCatComment', 'DbCatDowntime', 'DbCatEventHandler' ],
}

In a future version, the module will automatically create the IDO connection objects.

Note: If you will be installing NRPE or the Nagios plugins packages with the icinga2::nrpe class on a node that also has the icinga2::server class applied, be sure to set the $server_install_nagios_plugins parameter in your call to icinga2::server to false:

#Install Icinga 2:
class { 'icinga2::server':
  ...
  server_install_nagios_plugins => false,
  ...
 }

This will stop the icinga2::server class from trying to install the plugins pacakges, since the icinga2::nrpe class will already be installing them and will prevent a resulting duplicate resource error.

If you would like to install packages to make a mail command binary available so that Icinga 2 can send out notifications, set the install_mail_utils_package parameter to true:

  class { 'icinga2::server': 
    ...
    install_mail_utils_package => true,
    ...
  }

###NRPE usage

To install NRPE and allow the local machine and Icinga 2 servers (or Icinga 1 or plain old Nagios servers) with various IP addresess to connect:

class { 'icinga2::nrpe':
  nrpe_allowed_hosts => ['10.0.1.79', '10.0.1.80', '10.0.1.85', '127.0.0.1'],
}

By default the NRPE daemon will not allow clients to specify arguments to the commands that are executed. To enable NRPE to allow client argument processing you can call the icinga2::nrpe class with the allow_command_argument_processing parameter.

Valid parameter values are: 0=do not allow arguments, 1=allow command arguments

WARNING! - ENABLING THIS OPTION IS A SECURITY RISK!

class { 'icinga2::nrpe':
  allow_command_argument_processing => 1,
}

Note: If you would like to install NRPE on a node that also has the icinga2::server class applied, be sure to set the $server_install_nagios_plugins parameter in your call to icinga2::server to false:

#Install Icinga 2:
class { 'icinga2::server': 
  server_db_type => 'pgsql',
  server_install_nagios_plugins => false,
 }

This will stop the icinga2::server class from trying to install the plugins pacakges, since the icinga2::nrpe class will already be installing them and will prevent a resulting duplicate resource error.

###Object type usage

This module includes several defined types that can be used to automatically generate Icinga 2 format object definitions. They function in a similar way to the built-in Nagios types that are included in Puppet.

####Exported resources

Like the built-in Nagios types, the Icinga 2 objects in this module can be exported to PuppetDB as virtual resources and collected on your Icinga 2 server.

Nodes that are being monitored can have the @@ virtual resources applied to them:

@@icinga2::object::host { $::fqdn:
  display_name => $::fqdn,
  ipv4_address => $::ipaddress_eth0,
  groups => ['linux_servers', 'mysql_servers'],
  vars => {
    os              => 'linux',
    virtual_machine => 'true',
    distro          => $::operatingsystem,
  },
  target_dir => '/etc/icinga2/objects/hosts',
  target_file_name => "${fqdn}.conf"
}

Then, on your Icinga 2 server, you can collect the exported virtual resources (notice the camel casing in the class name):

#Collect all @@icinga2::object::host resources from PuppetDB that were exported by other machines:
Icinga2::Object::Host <<| |>> { }

Unlike the built-in Nagios types, the file owner, group and mode of the automatically generated files can be controlled via the target_file_owner, target_file_group and target_file_mode parameters:

@@icinga2::object::host { $::fqdn:
  display_name => $::fqdn,
  ipv4_address => $::ipaddress_eth0,
  groups => ['linux_servers', 'mysql_servers'],
  vars => {
    os              => 'linux',
    virtual_machine => 'true',
    distro          => $::operatingsystem,
  },
  target_dir        => '/etc/icinga2/objects/hosts',
  target_file_name  => "${fqdn}.conf"
  target_file_owner => 'root',
  target_file_group => 'root',
  target_file_mode  => '644'
}

####undef and default object values

Most of the object parameters in the Puppet module are set to undef.

This means that they will not be added to the rendered object definition files.

However, this doesn't mean that the values are undefined in Icinga 2. Icinga 2 itself has built-in default values for many object parameters and falls back to them if one isn't present in an object definition. See the docs for individual object types in Configuring Icinga 2 for more info about which object parameters have what default values.

####Objects

Object types:

• icinga2::object::apply_service_to_host
• icinga2::object::host
• icinga2::object::hostgroup
• icinga2::object::idomysqlconnection
• icinga2::object::idopgsqlconnection
• icinga2::object::service
• icinga2::object::servicegroup
• icinga2::object::syslogger
• icinga2::object::user
• icinga2::object::usergroup

####icinga2::object::apply_service_to_host

The apply_service_to_host defined type can create apply objects to apply services to hosts:

#Create an apply that checks the number of zombie processes:
icinga2::object::apply_service_to_host { 'check_zombie_procs':
  display_name => 'Zombie procs',
  check_command => 'nrpe',
  vars => {
    nrpe_command => 'check_zombie_procs',
  },
  assign_where => '"linux_servers" in host.groups',
  ignore_where => 'host.name == "localhost"',
  target_dir => '/etc/icinga2/objects/applys'
}

This defined type has the same available parameters that the icinga2::object::service defined type does.

The assign_where and ignore_where parameter values are meant to be provided as strings. Since Icinga 2 requires that string literals be double-quoted, the whole string in your Puppet site manifests will have to be single-quoted (leaving the double quotes intact inside):

assign_where => '"linux_servers" in host.groups',

If you would like to use Puppet or Facter variables in an assign_where or ignore_where parameter's value, you'll first need to double-quote the whole value for Puppet's variable interpolation to work. Then, you'll need to escape the double quotes that surround the Icinga 2 string literals inside:

assign_where => "\"linux_servers\" in host.${facter_variable}"",

####icinga2::object::host

This defined type creates host objects.

Example:

@@icinga2::object::host { $::fqdn:
  display_name => $::fqdn,
  ipv4_address => $::ipaddress_eth1,
  groups => ["linux_servers", 'mysql_servers', 'postgres_servers', 'clients', 'smtp_servers', 'ssh_servers', 'http_servers', 'imap_servers'],
  vars => {
    os              => 'linux',
    virtual_machine => 'true',
    distro          => $::operatingsystem,
  },
  target_dir => '/etc/icinga2/objects/hosts',
  target_file_name => "${fqdn}.conf"
}

Notes on specific parameters:

• groups: must be specified as a Puppet array, even if there's only one element
• vars: must be specified as a Puppet hash, with the Icinga 2 variable as the key and the variable's value as the value

Note: The ipv6_address parameter is set to undef by default. This is because facter can return either IPv4 or IPv6 addresses for the ipaddress_ethX facts. The default value for the ipv6_address parameter is set to undef and not ipaddress_eth0 so that an IPv4 address isn't unintentionally set as the value for address6 in the rendered host object definition.

If you would like to use an IPv6 address, make sure to set the ipv6_address parameter to the ipaddress_ethX fact that will give you the right IPv6 address for the machine:

@@icinga2::object::host { $::fqdn:
  display_name => $::fqdn,
  ipv6_address => $::ipaddress_eth1,
....
}

####icinga2::object::hostgroup

Coming soon...

####icinga2::object::idomysqlconnection

This defined type creates an IdoMySqlConnection objects.

Though you can create the file anywhere and with any name via the target_dir and target_file_name parameters, you should set the target_dir parameter to /etc/icinga2/features-enabled, as that's where Icinga 2 will look for DB connection objects by default.

Example usage:

icinga2::object::idomysqlconnection { 'mysql_connection':
   target_dir       => '/etc/icinga2/features-enabled',
   target_file_name => 'ido-mysql.conf',
   host             => '127.0.0.1',
   port             => 3306,
   user             => 'icinga2',
   password         => 'password',
   database         => 'icinga2_data',
   categories       => ['DbCatConfig', 'DbCatState', 'DbCatAcknowledgement', 'DbCatComment', 'DbCatDowntime', 'DbCatEventHandler' ],
}

Some parameters require specific data types to be given:

• port: needs to be a number, not a quoted string
• cleanup: If changed from the default value, needs to be given as a hash with the keys being the cleanup item names and the maximum age as a number (not a quoted string); default values are set to the default values shown in the Cleanup Items section of the IdomysqlConnection object documentation
• categories: needs to be given as an array with single-quoted strings as the elements; default values are set to the default values shown in the Data Categories section of the IdomysqlConnection object documentation

All other parameters are given as single-quoted strings.

This defined type supports all of the parameters that IdoMySqlConnection objects have available.

See IdoMySqlConnection on docs.icinga.org for a full list of parameters.

####icinga2::object::idopgsqlconnection

This defined type creates an IdoPgSqlConnection objects.

Though you can create the file anywhere and with any name via the target_dir and target_file_name parameters, you should set the target_dir parameter to /etc/icinga2/features-enabled, as that's where Icinga 2 will look for DB connection objects by default.

Example usage:

icinga2::object::idopgsqlconnection { 'postgres_connection':
   target_dir => '/etc/icinga2/features-enabled',
   target_file_name => 'ido-pgsql.conf',
   host             => '127.0.0.1',
   port             => 5432,
   user             => 'icinga2',
   password         => 'password',
   database         => 'icinga2_data',

   categories => ['DbCatConfig', 'DbCatState', 'DbCatAcknowledgement', 'DbCatComment', 'DbCatDowntime', 'DbCatEventHandler' ],
}

Some parameters require specific data types to be given:

• port: needs to be a number, not a quoted string
• cleanup: If changed from the default value, needs to be given as a hash with the keys being the cleanup item names and the maximum age as a number (not a quoted string); default values are set to the default values shown in the Cleanup Items section of the IdopgsqlConnection object documentation
• categories: needs to be given as an array with single-quoted strings as the elements; default values are set to the default values shown in the Data Categories section of the IdopgsqlConnection object documentation

All other parameters are given as single-quoted strings.

This defined type supports all of the parameters that IdoMySqlConnection objects have available.

See IdoPgSqlConnection on docs.icinga.org for a full list of parameters.

####icinga2::object::service

Coming soon...

####icinga2::object::servicegroup

This defined type creates an ServiceGroup objects.

Example usage:

icinga2::object::servicegroup { 'web_services':
  display_name => 'web services',
  target_dir => '/etc/icinga2/objects/servicegroups',
}

See ServiceGroup on docs.icinga.org for a full list of parameters.

####icinga2::object::sysloglogger

This defined type creates SyslogLogger objects.

severity can be set to debug, notice, information, warning or critical.

Example usage:

icinga2::object::sysloglogger { 'syslog-warning':
  severity => 'warning',
  target_dir => '/etc/icinga2/features-enabled',
}

See SyslogLogger on docs.icinga.org for more info.

####icinga2::object::user

Coming soon...

####icinga2::object::usergroup

You can use this defined type to create user groups. Example:

#Create an admins user group:
icinga2::object::hostgroup { 'admins':
  display_name => 'admins',
  target_dir => '/etc/icinga2/objects/usergroups',
}

####icinga2::object::graphitewriter

This defined type creates an GraphiteWriter object

Though you can create the file anywhere and with any name via the target_dir and target_file_name parameters, you should set the target_dir parameter to /etc/icinga2/features-enabled, as that's where Icinga 2 will look for graphitewriter connection objects by default.

Example Usage:

icinga2::object::graphitewriter { 'graphite_relay':
  target_dir       => '/etc/icinga2/features-enabled',
  target_file_name => 'graphite.conf',
  graphite_host    => '127.0.0.1',
  graphite_port    => 2003,
}

Reference

Classes:

Coming soon...

Defined types:

Coming soon...

Limitations

Coming soon...

Development

###Contributing

To submit a pull request via Github, fork Icinga/puppet-icinga2 and make your changes in a feature branch off of the master branch.

If your changes require any discussion, create an account on https://www.icinga.org/register/. Once you have an account, log onto dev.icinga.org. Create an issue under the Icinga Tools project and add it to the Puppet category.

If applicable for the changes you're making, add documentation to the README.md file.

###Support

Check the project website at http://www.icinga.org for status updates and https://support.icinga.org if you want to contact us.

Contributors

Coming soon...