Skip to content
This repository has been archived by the owner on Apr 16, 2018. It is now read-only.

Latest commit

 

History

History
1330 lines (993 loc) · 48.3 KB

README.md

File metadata and controls

1330 lines (993 loc) · 48.3 KB
Raw

Icinga 2 Puppet module

Fair warning

This module is no longer maintained. Find the official Icinga 2 Puppet Module here: puppet-icinga2

The GIT branch develop of this module is in a bit of flux at the moment.

Please make sure to check:

TODO: remove for release!

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
  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.

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. OracleLinux and similar might also need addons and optional (EPEL-7) enabled too. Consider using a module to manage all yum repos on hosts to manage the repos locally.

####Note for RedHat

If you are using RedHat Satellite server, set

   $manage_repos = false

in icinga2 class and make sure, you have a channel set up with the contents of the icinga2 repository and the needed packages from EPEL. If you leave it at true, the EPEL repository will be used directly.

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.

####Note For CentOS 5 You must be running CentOS 5.11 and no later in order to satisfy dependencies.

If you are attempting to install Icinga2 server on CentOS 5 (discouraged) and would like to use PostgreSQL, you must provide a non-EOL'd version of it. If you are installing PostgreSQL for the first time, you can tell the module to manage the pgsql YUM repository like so:

  class { 'postgresql::globals':
    manage_package_repo => true,
    version             => '9.3',
  }->
  class { 'postgresql::server': }

CentOS 5 provides PostgreSQL 9.1 by default, which was end-of-life'd in 2010. Without having the module manage the repo, it will gladly install this crippled version for you which isn't what you want.

You will still need to declare a database for Icinga2 to access.

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 begin, Icinga 2 requires that a database is available for use. Either Mysql or PostgreSQL will work for this purpose. This database creation is not handled in this module.

Once the database is available, use the icinga2 class with the db_ database connection parameters to specify the database information for Icinga 2 to use.

####Install Icinga 2:

class { 'icinga2':
  db_type         => 'pgsql',
  db_host         => 'localhost',
  db_port         => '5432',
  db_name         => 'icinga2_data',
  db_user         => 'icinga2',
  db_pass         => $password_goes_here,
  manage_database => true,
}

When the db_type parameter is set and manage_database is enabled, the required IDO database connection packages are automatically installed and the database schema is loaded.

Note: You may wish to consider Hiera eYAML to encrypt the password value for YAML storage.

#####Manual Database Connection Object

In some circumstances, it may be desirable to set manage_database => false and handle the database connection yourself. In such a case, you can either apply the icinga2::object::idomysqlconnection or icinga2::object::idopgsqlconnection class to your Icinga 2 server, depending on the chosen database.

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',
}

#####Using the Debmon Repository on Debian Systems

If you would like to use the Debmon repository for Debian 7 systems, set use_debmon_repo to true when you call the icinga2 class:

class { 'icinga2':
  db_type => 'pgsql',
  # default to false
  use_debmon_repo => true,
  db_host => 'localhost'
  db_port => '5432'
  db_name => 'icinga2_data'
  db_user => 'icinga2'
  db_pass => 'password',
}

mail binaries

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

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

Enabling and disabling Icinga 2 features

To manage the features that are enabled or disabled on an Icinga 2 server, you can specify default_features to true or false to enable or disable the features checker, mainlog and notification.

class { 'icinga2':
  ...
  default_features  => true,
}

To enable features selectively you need to configure them seperately.

class { 'icinga2::feature::command':
  command_path => '/var/run/icinga2/cmd/icinga2.cmd',
}

class { 'icinga2::feature::notification': }

Switch from restart to reload Icinga2 service

The benefits to reload the service can be found in this chapter.

Because the Puppet Resource Service doesn't support a reload, you can override the restart command. Every time the service should be restart, we execute a reload.

class { 'icinga2':
  ...
  restart_cmd  => 'service icinga2 reload',
  ...
}

You can also use Hiera

icinga2::restart_cmd: 'service icinga2 reload'

You should validate the reload command for your operatingsystem.

PKI

To use the external CA of puppet add ::icinga2::pki::puppet to your setup.

Example usage:

class { '::icinga2':
  ...
}

contain ::icinga2::pki::puppet

Check Plugins

Agents installed on nodes that Icinga is performing active checks against often require additional or custom check plugins. In order to deploy these check pluings on a node you can call the checkplugin defined resource.

The checkplugin defined resource can distribute files via both content (templates) and source (files). By default the checkpluin resource will assume your distribution method is content (template) and that your template resides in the icinga2 module

To reference a template that resides in another module you can update the $checkplugin_template_module parameter with the module your template resides

$checkplugin_template_module => 'SomeModule',

Example 1: Distribute check plugin that is a template

icinga2::checkplugin { 'check_diskstats':
  checkplugin_template => 'checkplugins/check_diskstats.erb',
}

Example 2: Distribute check plugin that is a static file

icinga2::checkplugin { 'check_diskstats':
  checkplugin_file_distribution_method => 'source',
  checkplugin_source_file              => 'puppet:///modules/checkplugins/check_diskstats',
}

Example 3: Distribute check plugin in a manifest

icinga2::checkplugin { 'check_diskstats':
  checkplugin_file_distribution_method => 'inline',
  checkplugin_source_inline            => 'command[check_disks]=/usr/lib64/nagios/plugins/check_disk -w 20 -c 10 -p /',
}

Example 4: Distribute check plugin stored in Hiera(-yaml)

---
icinga2::checkplugin:
  check_diskstats:
    checkplugin_file_distribution_method: 'inline'
    checkplugin_source_inline:            'command[check_disks]=/usr/lib64/nagios/plugins/check_disk -w 20 -c 10 -p /'

###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.

####Default object file locations, owner, group and mode

The default file location for each object type is controlled by the target_file_dir parameter. For each object type, it defaults to a subdirectory under /etc/icinga2/objects.

The default locations are under /etc/icinga2/objects and not /etc/icinga2/conf.d/ so that user-defined objects can be kept completely separate from the objects included with Icinga 2. However, you can change the target_file_dir parameter to /etc/icinga2/conf.d if needed.

The default file owner and group are controlled by the target_file_owner and target_file_group parameters. Both default to root.

The default file mode is controlled by the target_file_mode parameter. It defaults to 0644.

####Purging unmanaged object files

The purge_unmanaged_object_files parameter of the icinga2 class controls whether object files in /etc/icinga2/objects that are not managed by Puppet get purged. It defaults to false.

Note: This will purge unmanaged subdirectories as well as unmanaged files!

####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 ensure status, owner, group and mode of the automatically generated files can be controlled via the target_file_ensure 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_ensure => 'file',
  target_file_owner  => 'root',
  target_file_group  => 'root',
  target_file_mode   => '0644'
}

####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.

####Notifying the Icinga 2 service

By default, each object defined type will automatically notify and restart the Icinga 2 service. However, if you're using the module to just generate object files and not using it to manage the service, you'll likely get compilation errors about the icinga2 service not being in the catalog.

Each object defined type has a boolean parameter, refresh_icinga2_service, that controls whether the object file will notify the service. To not notify the service, set it to false:

icinga2::object::apply_dependency { 'usermail_dep_on_icinga2mail':
  parent_host_name => 'icinga2mail.local',
  target_file_owner => vagrant,
  assign_where => 'match("^usermail*", host.name)',
  refresh_icinga2_service => false,
}

####Features

TODO: describe init.pp params TODO: checker

Please see the Icinga 2 Documentation for details on the attributes.

#####icinga2::feature::mainlog

This feature is enabled by default and defines where to write the main log file of Icinga2.

You can change the location and severity.

class { 'icinga2::feature::mainlog':
  severity => 'debug',
  path     => '/data/icinga2/icinga2.log',
}

#####icinga2::feature::notification

This feature is enabled by default and enabled notification features in Icinga2.

You can change the enable_ha feature

class { 'icinga2::feature::mainlog':
  enable_ha => false,
}

####Objects

Object types:

####icinga2::object::apiuser

This defined type creates ApiUser objects that creates users for Icinga 2's API.

#Create an API user object:
icinga2::object::apiuser { 'myapiuser':
  password => 'mysecretpassword',
}

The permissions for a ApiUser are default unlimited, but it can limited with permissions parameter.

See the Icinga 2 documention for more info: http://docs.icinga.org/icinga2/latest/doc/module/icinga2/chapter/object-types#objecttype-apiuser

####icinga2::object::apilistener

This defined type creates ApiLister objects that set the bind address and port for Icinga 2's API listener, as well as the locations of the machine's Icinga 2 cert, key and Icinga 2 CA key:

#Create an API listener object:
icinga2::object::apilistener { 'master-api':
  bind_host => $ipaddress_eth1,
  accept_commands => true,
}

The accept_config and accept_commands parameters default to false.

See the Icinga 2 documention for more info: http://docs.icinga.org/icinga2/latest/doc/module/icinga2/chapter/object-types#objecttype-apilistener

####icinga2::object::apply_service

This defined type creates Apply objects to apply services to hosts:

#Create an apply that checks the number of zombie processes:
icinga2::object::apply_service { '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 except the apply parameter.

The apply allows multiple services with one definition based on host variables. See http://docs.icinga.org/icinga2/latest/doc/module/icinga2/chapter/monitoring-basics#using-apply-for-custom-attribute-override for more information.

apply => 'for (interface_name => interface_config in host.vars.interfaces)';

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::apply_notification_to_host

This defined type creates Apply objects to apply notifications to hosts:

This defined type has the same available attributes that the icinga2::object::notification defined type does. With the addition of assign_where and ignore_where

#Create an apply that will send notifications to PagerDuty
icinga2::object::apply_notification_to_host { 'pagerduty-host':
  assign_where => 'host.vars.enable_pagerduty == "true"',
  command      => 'notify-host-by-pagerduty',
  users        => [ 'pagerduty' ],
  states       => [ 'Up', 'Down' ],
  types        => [ 'Problem', 'Acknowledgement', 'Recovery', 'Custom' ],
  period       => '24x7',
}

####icinga2::object::apply_notification_to_service

This defined type creates Apply objects to apply notifications to services:

This defined type has the same available attributes that the icinga2::object::notification defined type does. With the addition of assign_where and ignore_where

icinga2::object::apply_notification_to_service { 'pagerduty-service':
  assign_where => 'service.vars.enable_pagerduty == "true"',
  command      => 'notify-service-by-pagerduty',
  users        => [ 'pagerduty' ],
  states       => [ 'OK', 'Warning', 'Critical', 'Unknown' ],
  types        => [ 'Problem', 'Acknowledgement', 'Recovery', 'Custom' ],
  period       => '24x7',
}

####icinga2::object::apply_scheduleddowntime

The apply_scheduleddowntime defined type can create apply objects to apply downtimes to hosts or services:

icinga2::object::apply_scheduleddowntime { 'apply-downtime-name':
  apply        => 'Service',
  templates    => [
    'generic-downtime-template'
  ],
  assign_where => 'service.vars.anoying_check == true',
  ignore_where => 'host.vars.critical_machine == true',
  author       => 'icingaadmin',
  comment      => 'Some comment',
  fixed        => false,
  duration     => '30m',
  ranges       => { 'sunday' => '02:00-03:00' }
}

####icinga2::object::checkcommand

This defined type creates CheckCommand objects.

Example usage:

#Create an HTTP check command:
icinga2::object::checkcommand { 'check_http':
  command => ['"/check_http"'],
  arguments     => {
    '"-H"'          => '"$http_vhost$"',
    '"-I"'          => '"$http_address$"',
    '"-u"'          => '"$http_uri$"',
    '"-p"'          => '"$http_port$"',
    '"-S"'          => {
      'set_if' => '"$http_ssl$"'
    },
    '"--sni"'       => {
      'set_if' => '"$http_sni$"'
    },
    '"-a"'          => {
      'value'       => '"$http_auth_pair$"',
      'description' => '"Username:password on sites with basic authentication"'
    },
    '"--no-body"'   => {
      'set_if' => '"$http_ignore_body$"'
    },
    '"-r"' => '"$http_expect_body_regex$"',
    '"-w"' => '"$http_warn_time$"',
    '"-c"' => '"$http_critical_time$"',
    '"-e"' => '"$http_expect$"'
  },
  vars => {
    http_address => '"$address$"',
    http_ssl     => false,
    http_sni     => false
  }
}

Available parameters are:

  • command
  • cmd_path
  • arguments
  • env
  • sudo
  • sudo_cmd
  • vars
  • timeout
  • target_dir
  • target_file_name
  • target_file_owner
  • target_file_group
  • target_file_mode

####icinga2::object::compatlogger

This defined type creates CompatLogger objects.

icinga2::object::compatlogger { 'daily-log':
  log_dir         => '/var/log/icinga2/compat',
  rotation_method => 'DAILY'
}

Both patameters as optionals. The parameter rotation_method can one of HOURLY, DAILY, WEEKLY or MONTHY. See CompatLogger on docs.icinga.org for a full list of parameters.

####icinga2::object::checkresultreader

This defined type creates CheckResultReader objects.

Example usage:

icinga2::object::checkresultreader {'reader':
  spool_dir => '/data/check-results'
}

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

####icinga2::object::endpoint

This defined type creates Endpoint objects.

icinga2::object::endpoint { 'icinga2b':
  host => '192.168.5.46',
  port => 5665
}

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

####icinga2::object::eventcommand

This defined type creates EventCommand objects.

#Create the http restart command:
icinga2::object::eventcommand { 'restart-httpd-event':
  command => [ '"/opt/bin/restart-httpd.sh"' ]
}

This object use the same parameter defined to checkcommand.

####icinga2::object::externalcommandlistener

This defined type creates ExternalCommandListener objects.

icinga2::object::externalcommandlistener { 'external':
  command_path => '/var/run/icinga2/cmd/icinga2.cmd'
}

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

####icinga2::object::gelfwriter

This defined type creates an GelfWriter objects.

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

Example usage:

icinga2::object::gelfwriter { 'gelf_server':
  target_dir => '/etc/icinga2/features-enabled',
  file_name  => 'gelf.conf',
  host       => '127.0.0.1',
  port       => 12201,
}

####icinga2::object::graphitewriter

This defined type creates GraphiteWriter 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 graphitewriter connection objects by default.

Example usage:

icinga2::object::graphitewriter { 'graphite_relay':
  target_dir => '/etc/icinga2/features-enabled',
  file_name  => 'graphite.conf',
  host       => '127.0.0.1',
  port       => 2003,
}

####icinga2::object::host

This defined type creates Host objects.

Example usage:

@@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
  • custom_prepend and custom_append: must be specified as Puppet arrays, even if there's only one element. This allows to define free form text which will be inserted either in the beginning, or end of the hosts definition, i.e.
    custom_append => [
      'vars += { disks["disk"] = {} }',
    ]

will add the literal line 'vars += { disks["disk"] = {} }' to the host definition. This helps overcoming limitations about quoting especially in the vars hash. This also allows to add comments to the hosts file.

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

This defined type creates Hostgroup objects.

Example usage:

@@icinga2::object::hostgroup { 'mysql-server':
  display_name      => 'mysql servers',
  groups            => ['linux-servers', 'database-severs'],
  target_dir        => '/etc/icinga2/objects/hostgroups',
  target_file_name  => "${name}.conf",
  target_file_owner => 'root',
  target_file_group => 'root',
  target_file_mode  => '0644',
}

Notes on specific parameters:

  • groups: must be specified as a Puppet array, even if there's only one element

Note: Make sure to avoid duplicate hostgroup definitions.

####icinga2::object::icingastatuswriter

This defined type creates IcingaStatusWriter objects.

Example usage:

icinga2::object::icingastatuswriter { 'status':
   status_path       => '/cache/icinga2/status.json',
   update_interval   => '15s',
}

See IcingaStatusWriter on docs.icinga.org for more details about the object.

####icinga2::object::idomysqlconnection

This defined type creates 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',
}

Some parameters require specific data types to be given:

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 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',
}

Some parameters require specific data types to be given:

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::livestatuslistener

This defined type creates a LivestatusListener objects.

Example usage:

icinga2::object::livestatuslistener { 'livestatus-unix':
  socket_type => 'unix',
  socket_path => '/var/run/icinga2/cmd/livestatus'
}

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

####icinga2::object::notification

This defined type creates Notification objects.

#Defining Create the mail notification command:
icinga2::object::notification { 'localhost-ping-notification':
  host_name    => 'localhost',
  service_name => 'ping4',
  command      => 'mail-service-notification',
  types        => [ 'Problem', 'Recovery' ]
}

Available parameters are:

  • host_name: Required.
  • service_name: Optional.
  • vars: Optional.
  • users: Optional.
  • user_groups: Optional.
  • times: Optional.
  • command: Required.
  • interval: Optional.
  • period: Optional.
  • types: Optional.
  • states: Optional.
  • target_file_name: Optional.
  • target_file_owner: Optional.
  • target_file_group: Optional.
  • target_file_mode: Optional.

Notes on specific parameters:

  • vars: needs to be a hash
  • users,user_groups,types,states: should be an array, see Notification for list of valid state and type filters
  • times: needs to be a hash with begin and end attributes
  • interval: needs to be a number, not a quoted string

####icinga2::object::notificationcommand

This defined type creates NotificationCommand objects.

#Create the mail notification command:
icinga2::object::notificationcommand { 'mail-service-notification':
  command   => ['/icinga2/scripts/mail-notification.sh'],
  cmd_path  => 'SysconfDir',
  env       => {
    'NOTIFICATIONTYPE'  => '"$notification.type$"',
    'SERVICEDESC' => '"$service.name$"',
    'HOSTALIAS' => '"$host.display_name$"',
    'HOSTADDRESS' => '"$address$"',
    'SERVICESTATE' => '"$service.state$"',
    'LONGDATETIME' => '"$icinga.long_date_time$"',
    'SERVICEOUTPUT' => '"$service.output$"',
    'NOTIFICATIONAUTHORNAME' => '"$notification.author$"',
    'NOTIFICATIONCOMMENT' => '"$notification.comment$"',
    'HOSTDISPLAYNAME' => '"$host.display_name$"',
    'SERVICEDISPLAYNAME' => '"$service.display_name$"',
    'USEREMAIL' => '"$user.email$"'
  }
}

This object use the same parameter defined to checkcommand.

####icinga2::object::opentsdbwriter

This defined type creates OpenTsdbWriter objects.

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

Example usage:

icinga2::object::opentsdbwriter { 'opentsdb_server':
  target_dir => '/etc/icinga2/features-enabled',
  file_name  => 'opentsdb.conf',
  host       => '127.0.0.1',
  port       => 4242,
}

####icinga2::object::perfdatawriter

This defined type creates PerfdataWriter objects.

Example usage:

icinga2::object::perfdatawriter { 'pnp':
  host_perfdata_path      => '/var/spool/icinga2/perfdata/host-perfdata',
  service_perfdata_path   => '/var/spool/icinga2/perfdata/service-perfdata',
  host_format_template    => 'DATATYPE::HOSTPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tHOSTPERFDATA::$host.perfdata$\tHOSTCHECKCOMMAND::$host.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$',
  service_format_template => 'DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.check_command$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.state_type$',
  rotation_interval       => '15s'
}

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

####icinga2::object::scheduleddowntime

This defined type creates ScheduledDowntime objects.

Example usage:

icinga2::object::scheduleddowntime {'some-downtime':
  host_name    => 'localhost',
  service_name => 'ping4',
  author       => 'icingaadmin',
  comment      => 'Some comment',
  fixed        => false,
  duration     => '30m',
  ranges       => { 'sunday' => '02:00-03:00' }
}

####icinga2::object::service

This defined type creates Service objects.

Example usage:

icinga2::object::service { 'example_service':
  $template_to_import      => 'generic-service',
  $display_name            => 'Example Service',
  $host_name               => $::fqdn,
  $groups                  => ['example-servers', 'linux-servers'],
  $vars                    => {
    var1                   => 'somevalue',
    var2                   => 'someothervalue',
  },
  $check_command           => example-check,
  $max_check_attempts      => 5,
  $check_interval          => '10m',
  $retry_interval          => '1m',
  $enable_notifications    => true,
  $enable_active_checks    => true,
  $enable_flapping         => true,
  $enable_perfdata         => true,
  $flapping_threshold      => '50%',
  $target_dir              => '/etc/icinga2/objects/services',
  $target_file_name        => "${name}.conf",
  $target_file_ensure      => file,
  $target_file_owner       => 'root',
  $target_file_group       => 'root',
  $target_file_mode        => '0644',
  $refresh_icinga2_service => true,
}

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

####icinga2::object::servicegroup

This defined type creates 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::statusdatawriter

This defined type creates StatusDataWriter objects.

Example usage:

icinga2::object::statusdatawriter { 'status':
    status_path     => '/var/cache/icinga2/status.dat',
    objects_path    => '/var/cache/icinga2/objects.path',
    update_interval => 30s
}

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

####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

This defined type creates User objects.

icinga2::object::user { 'some_user':
  display_name => 'Some User',
  email        => '[email protected]',
  groups       => ['icingaadmins'],
  target_dir   => '/etc/icinga2/zones.d/global_zone',
}

####icinga2::object::usergroup

This defined type creates UserGroup objects.

Example usage:

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

####icinga2::object::timeperiod

This defined type creates TimePeriod objects.

Example usage:

icinga2::object::timeperiod { 'bra-office-hrs':
  timeperiod_display_name => 'Brazilian WorkTime Hours',
  ranges       => {
    'monday'    => '12:00-21:00',
    'tuesday'   => '12:00-21:00',
    'wednesday' => '12:00-21:00',
    'thursday'  => '12:00-21:00',
    'friday'    => '12:00-21:00'
  }
}

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

####icinga2::object::zone

This defined type creates Zone objects.

Example usage to create an HA master zone:

icinga2::object::zone { 'master':
    endpoints => { 'icinga-master1' => {}, 'icinga-master2' => {} },
}

Example usage to create a satellite zone and specify a parent:

icinga2::object::zone { 'satellite':
    endpoints => { 'icinga-satellite1' => {}, 'icinga-satellite2' => {} },
    parent    => 'master'
}

Example Usage to create a global zone:

icinga2::object::zone { 'global_zone':
  global => true,
}

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

Hiera

You can use hiera to create icinga 2 objects in your server. To use this feature one has to include or contain the class ::icinga2::objects. This class will autoload every hash found in Hiera.

Example usage: json file

{
  ...
  "icinga2::object::timeperiod": {
    "bra-office-hrs": {
      "timeperiod_display_name": "Brazilian WorkTime Hours",
      "ranges": {
        "monday": "12:00-21:00",
        "monday": "12:00-21:00",
        "monday": "12:00-21:00",
        "monday": "12:00-21:00",
        "monday": "12:00-21:00"
      }
    },
    "utc-office-hrs": {
      "timeperiod_display_name": "UTC WorkTime Hours",
      "ranges": {
        "monday": "08:00-17:00",
        "monday": "08:00-17:00",
        "monday": "08:00-17:00",
        "monday": "08:00-17:00",
        "monday": "08:00-17:00"
    }
  }
  ...
}

yaml file

icinga2::object::hostgroup:
  office-a:
    display_name: 'Office A'
    assign_where: 'host.vars.location == "office-a"'
  datacenter-b:
    display_name: 'Datacenter B'
    assign_where: 'host.vars.location == "datacenter-b"'

Objects available:

  • apiuser
  • apply_dependency
  • apply_notification_to_host
  • apply_notification_to_service
  • apply_service
  • apply_scheduleddowntime
  • checkcommand
  • dependency
  • eventcommand
  • graphitewriter
  • gelfwriter
  • hostgroup
  • host
  • idomysqlconnection
  • idopgsqlconnection
  • notificationcommand
  • notification
  • opentsdbwriter
  • perfdatawriter
  • scheduleddowntime
  • servicegroup
  • service
  • sysloglogger
  • timeperiod
  • usergroup
  • user

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 develop 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...