Icinga Web 2 Puppet Module

Overview
Module Description - What the module does and why it is useful
Setup - The basics of getting started with Icinga Web 2
- What Icinga Web 2 affects
Usage - Configuration options and additional functionality
Reference - An under-the-hood peek at what the module is doing and how
Development - Guide for contributing to the module

Overview

Icinga Web 2 is the associated web interface for the open source monitoring tool Icinga 2. This module helps with installing and managing configuration of Icinga Web 2 and its modules on multiple operating systems.

Description

This module installs and configures Icinga Web 2 on your Linux host by using the official packages from packages.icinga.com. Dependend packages are installed as they are defined in the Icinga Web 2 package.

This module can manage all configurations files of Icinga Web 2 and import an initial database schema. It can install and manage all official modules as well as modules developed by the community.

Setup

What the Icinga 2 Puppet module supports

Installation of Icinga Web 2 via packages
Configuration
MySQL / PostgreSQL database schema import
Install and manage official Icinga Web 2 modules
Install community modules

Dependencies

This module depends on

Depending on your setup following modules may also be required:

puppetlabs/apt >= 2.0.0
puppet/zypprepo >= 2.0.0

Limitations

This module has been tested on:

Debian 7, 8, 9
CentOS/RHEL 6, 7
- Requires Software Collections Repository
Ubuntu 14.04, 16.04
SLES 12
PHP >= 5.6

Other operating systems or versions may work but have not been tested.

Usage

Install Icinga Web 2

The default class icingaweb2 installs a basic installation of Icinga Web 2 by using the systems package manager. It is recommended to use the official Icinga repository for the installation.

Use the manage_repo parameter to configure the official packages.icinga.com repository.

class { '::icingaweb2':
  manage_repo => true,
}

Info: If you are using the Icinga 2 Puppet module on the same server, make sure to disable the repository management for one of the modules!

If you want to manage the version of Icinga Web 2, you have to disable the package management of this module and handle packages in your own Puppet code.

package { 'icingaweb2':
  ensure => latest,
}

class { '::icingaweb2':
  manage_package => false,
}

Be careful with this option: Setting manage_package to false also means that this module will not install any dependent packages of modules.

Use the monitoring class to connect the web interface to Icinga 2.

This module does not provide functionality to install and configure any web server, see the following examples how to install Icinga Web 2 with differen web servers:

Manage Resources

Icinga Web 2 resources are managed with the icingaweb2::config::resource defined type. Supported resource types are db and ldap. Resources are used for the internal authentication mechanism and by modules. Depending on the type of resource you are managing, different parameters may be required.

Create a db resource:

icingaweb2::config::resource{'my-sql':
  type        => 'db',
  db_type     => 'mysql',
  host        => 'localhost',
  port        => '3306',
  db_name     => 'icingaweb2',
  db_username => 'root',
  db_password => 'supersecret',
}

Create a ldap resource:

icingaweb2::config::resource{'my-ldap':
  type         => 'ldap',
  host         => 'localhost',
  port         => 389,
  ldap_root_dn => 'dc=users,dc=icinga,dc=com',
  ldap_bind_dn => 'cn=root,dc=users,dc=icinga,dc=com',
  ldap_bind_pw => 'supersecret',
}

Manage Authentication Methods

Authentication methods are created with the icingaweb2::config:authmethod defined type. Various authentication methods are supported: db, ldap, msldap and external. Auth methods can be chained with the order parameter.

Create a MySQL authmethod:

icingaweb2::config::authmethod{'my-sql':
  backend  => 'db',
  resource => 'my-sql',
  order    => '01',
}

Create a LDAP authmethod:

icingaweb2::config::authmethod {'ldap-auth':
  backend                  => 'ldap',
  resource                 => 'my-ldap',
  ldap_user_class          => 'myObjectClass',
  ldap_filter              => '(icingaaccess=true))',
  ldap_user_name_attribute => 'uid',
  order                    => '02',
}

DB Schema and Default User

You can choose to import the database schema for MySQL or PostgreSQL. If you set import_schema to true the module import the corresponding schema for your db_type. Additionally a resource, an authentication method and a role will be generated.

The module does not support the creation of databases, we encourage you to use either the puppetlabs/mysql or the puppetlabs/puppetlabs-postgresql module.

💡 Default credentials are: User: icingaadmin Password: icinga

MySQL

Use MySQL as backend for user authentication in Icinga Web 2:

include ::mysql::server

mysql::db { 'icingaweb2':
  user     => 'icingaweb2',
  password => 'icingaweb2',
  host     => 'localhost',
  grant    => ['SELECT', 'INSERT', 'UPDATE', 'DELETE', 'DROP', 'CREATE VIEW', 'CREATE', 'INDEX', 'EXECUTE', 'ALTER', 'REFERENCES'],
}

class {'icingaweb2':
  manage_repo   => true,
  import_schema => true,
  db_type       => 'mysql',
  db_host       => 'localhost',
  db_port       => 3306,
  db_username   => 'icingaweb2',
  db_password   => 'icingaweb2',
  require       => Mysql::Db['icingaweb2'],
}

PostgreSQL

Use PostgreSQL as backend for user authentication in Icinga Web 2:

include ::postgresql::server

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

class {'icingaweb2':
  manage_repo   => true,
  import_schema => true,
  db_type       => 'pgsql',
  db_host       => 'localhost',
  db_port       => '5432',
  db_username   => 'icingaweb2',
  db_password   => 'icingaweb2',
  require       => Postgresql::Server::Db['icingaweb2'],
}

Manage Roles

Roles are a set of permissions applied to users and groups. With filters you can limit the access to certain objects only. Each module can add its own permissions, so it's hard to create a list of all available permissions. The following permissions are included when the monitoring module is enabled:

Description	Value
Allow everything	`*`
Allow to share navigation items	`application/share/navigation`
Allow to adjust in the preferences whether to show stacktraces	`application/stacktraces`
Allow to view the application log	`application/log`
Grant admin permissions, e.g. manage announcements	`admin`
Allow config access	`config/*`
Allow access to module doc	`module/doc`
Allow access to module monitoring	`module/monitoring`
Allow all commands	`monitoring/command/*`
Allow scheduling host and service checks	`monitoring/command/schedule-check`
Allow acknowledging host and service problems	`monitoring/command/acknowledge-problem`
Allow removing problem acknowledgements	`monitoring/command/remove-acknowledgement`
Allow adding and deleting host and service comments	`monitoring/command/comment/*`
Allow commenting on hosts and services	`monitoring/command/comment/add`
Allow deleting host and service comments	`monitoring/command/comment/delete`
Allow scheduling and deleting host and service downtimes	`monitoring/command/downtime/*`
Allow scheduling host and service downtimes	`monitoring/command/downtime/schedule`
Allow deleting host and service downtimes	`monitoring/command/downtime/delete`
Allow processing host and service check results	`monitoring/command/process-check-result`
Allow processing commands for toggling features on an instance-wide basis	`monitoring/command/feature/instance`
Allow processing commands for toggling features on host and service objects	`monitoring/command/feature/object/*`)
Allow processing commands for toggling active checks on host and service objects	`monitoring/command/feature/object/active-checks`
Allow processing commands for toggling passive checks on host and service objects	`monitoring/command/feature/object/passive-checks`
Allow processing commands for toggling notifications on host and service objects	`monitoring/command/feature/object/notifications`
Allow processing commands for toggling event handlers on host and service objects	`monitoring/command/feature/object/event-handler`
Allow processing commands for toggling flap detection on host and service objects	`monitoring/command/feature/object/flap-detection`
Allow sending custom notifications for hosts and services	`monitoring/command/send-custom-notification`
Allow access to module setup	`module/setup`
Allow access to module test	`module/test`
Allow access to module translation	`module/translation`

With the monitoring module, possible filters are:

application/share/users
application/share/groups
monitoring/filter/objects
monitoring/blacklist/properties

Create role that allows a user to see only hosts beginning with linux-*:

icingaweb2::config::role{'linux-user':
  users       => 'bob, pete',
  permissions => '*',
  filters     => {
    'monitoring/filter/objects' => 'host_name=linux-*',
  }
}

Manage Group Backends

Group backends store information about available groups and their members. Valid backends are db, ldap or msldap. Groups backends can be combined with authentication methods. For example, users can be stored in a database, but group definitions in LDAP. If a user is member of multiple groups, he inherits permissions of all his groups.

Create an LDAP group backend:

icingaweb2::config::groupbackend {'ldap-backend':
  backend                     => 'ldap',
  resource                    => 'my-ldap',
  ldap_group_class            => 'groupofnames',
  ldap_group_name_attribute   => 'cn',
  ldap_group_member_attribute => 'member',
  ldap_base_dn                => 'ou=groups,dc=icinga,dc=com'
}

If you have imported the database schema (parameter import_schema), you can use this database as group backend:

icingaweb2::config::groupbackend {'mysql-backend':
  backend  => 'db',
  resource => 'mysql-icingaweb2',
}

Install and Manage Modules

Monitoring

This module is mandatory for almost every setup. It connects your Icinga Web interface to the Icinga 2 core. Current and history information are queried through the IDO database. Actions such as Check Now, Set Downtime or Acknowledge are send to the Icinga 2 API.

Requirements:

IDO feature in Icinga 2 (MySQL or PostgreSQL)
ApiUser object in Icinga 2 with proper permissions

Example:

class {'icingaweb2::module::monitoring':
  ido_host        => 'localhost',
  ido_db_name     => 'icinga2',
  ido_db_username => 'icinga2',
  ido_db_password => 'supersecret',
  commandtransports => {
    icinga2 => {
      transport => 'api',
      username  => 'root',
      password  => 'icinga',
    }
  }
}

Monitoring module documentation

Director

The Director is used to manage Icinga 2 configuration through the web interface Icinga Web 2. The module requires its database. The module is installed by cloning the git repository, therefore you need to set git_revision to either a git branch or tag, eg. master or v1.3.2.

The Director has some dependencies that you have to fulfill manually currently:

Icinga 2 (>= 2.6.0)
Icinga Web 2 (>= 2.4.1)
A MySQL or PostgreSQL database
PHP (>= 5.4)
php-curl

Example:

class {'icingaweb2::module::director':
  git_revision  => 'v1.3.2',
  db_host       => 'localhost',
  db_name       => 'director',
  db_username   => 'director',
  db_password   => 'director',
  import_schema => true,
  kickstart     => true,
  endpoint      => 'puppet-icingaweb2.localdomain',
  api_username  => 'root',
  api_password  => 'icinga',
  require       => Mysql::Db['director']
}

Director module documentation

To run the kickstart mechanism, it's required to set import_schema to true.

Doc

The doc module provides an interface to the Icinga 2 and Icinga Web 2 documentation.

Example:

include ::icingaweb2::module::doc

To disable:

class {'::icingaweb2::module::doc':
  ensure => absent
}

Doc module documentation

PuppetDB

You can configure Director to query one or more PuppetDB servers.

Example: Set up the PuppetDB module and configure two custom SSL keys

$certificates = {'pupdb1' => {
                   :ssl_key => '-----BEGIN RSA PRIVATE KEY----- abc...',
                   :ssl_cacert => '-----BEGIN RSA PRIVATE KEY----- def...', },
                 'pupdb2' => {
                   :ssl_key => '-----BEGIN RSA PRIVATE KEY----- zyx...',
                   :ssl_cacert => '-----BEGIN RSA PRIVATE KEY----- wvur...', },
                }

class {'::icingaweb2::module::puppetdb':
  git_revision => 'master',
  ssl          => 'none',
  certificates => $certificates,
}

Example: Set up the PuppetDB module and configure the hosts SSL key to connect to the PuppetDB host

class {'::icingaweb2::module::puppetdb':
  git_revision => 'master',
  ssl          => 'puppet',
  host         => 'puppetdb.example.com',
}

PuppetDB module documentation

Business Process

The Business Process module allows you to visualize and monitor business processes based on hosts and services monitored by Icinga 2. The module is installed by cloning the git repository, therefore you need to set git_revision to either a git branch or tag, eg. master or v2.1.0.

This module has the following dependecies:

Icinga Web 2 (>= 2.4.1)
PHP (>= 5.3 or 7.x)

Example:

class { 'icingaweb2::module::businessprocess':
  git_revision => 'v2.1.0'
}

Business Process mdoule documentation

Cube

The Cube module is like a extended filtering tool. It visualizes host statistics (count and health state) grouped by various custom variables in multiple dimensions. The module is installed by cloning the git repository, therefore you need to set git_revision to either a git branch or tag, eg. master or v1.0.0.

Example:

class { 'icingaweb2::module::cube':
  git_revision => 'v1.0.0'
}

GenericTTS

The GenericTTS module matches ticket pattern and replaces them with a link to your ticketsystem. The module is installed by cloning the git repository, therefore you need to set git_revision to either a git branch or tag, eg. master or v2.0.0.

Example:

class { 'icingaweb2::module::generictts':
  git_revision  => 'v2.0.0',
  ticketsystems => {
    'my-ticket-system' => {
      pattern => '/#([0-9]{4,6})/',
      url     => 'https://my.ticket.system/tickets/id=$1',
    },
  },
}

Fileshipper

The main purpose of this module is to extend Icinga Director using some of it's exported hooks. Based on them it offers an Import Source able to deal with CSV, JSON, YAML and XML files. It also offers the possibility to deploy hand-crafted Icinga 2 config files through the Icinga Director.

The fileshipper module has some optional requirements:

php-xml for optional XML file support
php-yaml for optional YAML file support

Example:

class { 'icingaweb2::module::fileshipper':
  git_revision => 'v1.0.1',
  base_directories => {
    temp => '/tmp'
  },
  directories      => {
    'test' => {
      'source'     => '/tmp/source',
      'target'     => '/tmp/target',
    }
  }
}

Fileshipper module documentation

vSphere

This module extends the Director module. It allows you to have an automated import of virtual maschines and physical hosts from vSphere.

The module needs some extra PHP extensions that you need to install:

php-posix
php-soap

Example:

class { 'icingaweb2::module::vsphere':
  git_revision => 'v1.1.0',
}

vSphere module documentation

Graphite

This module integrates an existing Graphite installation in your Icinga Web 2 frontend.

Example:

class { 'icingaweb2::module::graphite':
  git_revision => 'v0.9.0',
  url          => 'https://localhost:8080'
}

Graphite module documentation

Elasticsearch

The Elasticsearch module displays events from data stored in Elasticsearch.

Example:

class { 'icingaweb2::module::elasticsearch':
  git_revision => 'v0.9.0',
  instances    => {
    'elastic'  => {
      uri      => 'http://localhost:9200',
      user     => 'foo',
      password => 'bar',
    }
  },
  eventtypes   => {
    'filebeat' => {
      instance => 'elastic',
      index    => 'filebeat-*',
      filter   => 'beat.hostname={host.name}',
      fields   => 'input_type, source, message',
    }
  }
}

Elasticsearch module documentation

Public Classes

Class: `icingaweb2`

The default class of this module. It handles the basic installation and configuration of Icinga Web 2.

Parameters of icingaweb2:

`logging`

Whether Icinga Web 2 should log to file or to syslog. Setting none disables logging. Defaults to file

`logging_file`

If 'logging' is set to file, this is the target log file. Defaults to /var/log/icingaweb2/icingaweb2.log.

`logging_level`

Logging verbosity. Possible values are ERROR, WARNING, INFO and DEBUG. Defaults to INFO

`show_stacktraces`

Whether to display stacktraces in the web interface or not. Defaults to false

`module_path`

Path to module sources. Multiple paths must be separated by colon. Defaults to /usr/share/icingaweb2/modules

`theme`

The default theme setting. Users may override this settings. Defaults to icinga.

`theme_disabled`

Whether users can change themes or not. Defaults to false.

`manage_repo`

When set to true this module will install the packages.icinga.com repository. With this official repo you can get the latest version of Icinga Web. When set to false the operating systems default will be used. Defaults to false

NOTE: will be ignored if manage_package is set to false

`manage_package`

If set to false packages aren't managed. Defaults to true

`extra_pacakges`

An array of packages to install additionally.

`import_schema`

Import database scheme. Make sure you have an existing database if you use this option. Defaults to false

`db_type`

Database type, can be either mysql or pgsql. This parameter is only used if import_schema is true or config_backend is db. Defaults to mysql

`db_host`

Database hostname. This parameter is only used if import_schema is true or config_backend is db. Defaults to localhost

`db_port`

Port of database host. This parameter is only used if import_schema is true or config_backend is db. Defaults to 3306

`db_name`

Database name. This parameter is only used if import_schema is true or config_backend is db. Defaults to icingaweb2

`db_username`

Username for database access. This parameter is only used if import_schema is true or config_backend is db.

`db_password`

Password for database access. This parameter is only used if import_schema is true or config_backend is db.

`config_backend`

The global Icinga Web 2 preferences can either be stored in a database or in ini files. This parameter can either be set to db or ini. Defaults to ini

`conf_user`

By default this module expects Apache2 on the server. You can change the owner of the config files with this parameter. Default is dependent on the platform

`default_domain`

When using domain-aware authentication, you can set a default domain here.

Class: `icingaweb2::module::monitoring`

Manage the monitoring module. This module is mandatory for probably every setup.

Parameters of icingaweb2::module::monitoring:

`ensure`

Enable or disable module. Defaults to present

`protected_customvars`

Custom variables in Icinga 2 may contain sensible information. Set patterns for custom variables that should be hidden in the web interface. Defaults to *pw*,*pass*,community

`ido_type`

Type of your IDO database. Either mysql or pgsql. Defaults to mysql

`ido_host`

Hostname of the IDO database.

`ido_port`

Port of the IDO database. Defaults to 3306

`ido_db_name`

Name of the IDO database.

`ido_db_username`

Username for IDO DB connection.

`ido_db_password`

Password for IDO DB connection.

`ido_db_charset`

The character set to use for the database connection.

`commandtransports`

A hash of command transports.

Example:

  commandtransports => {
    icinga2 => {
      transport => 'api',
      username  => 'root',
      password  => 'icinga',
    }
  }

Class: `icingaweb2::module::director`

Install and configure the director module.

Parameters of icingaweb2::module::director:

`ensure`

Enable or disable module. Defaults to present

`git_repository`

Set a git repository URL. Defaults to github.

`git_revision`

Set either a branch or a tag name, eg. master or v1.3.2.

`db_type`

Type of your database. Either mysql or pgsql. Defaults to mysql

`db_host`

Hostname of the database.

`db_port`

Port of the database. Defaults to 3306

`db_name`

Name of the database.

`db_username`

Username for DB connection.

`db_password`

Password for DB connection.

`ido_db_charset`

The character set to use for the database connection.

`import_schema`

Import database schema. Defaults to false

`kickstart`

Run kickstart command after database migration. This requires import_schema to be true. Defaults to false

`endpoint`

Endpoint object name of Icinga 2 API. This setting is only valid if kickstart is true.

`api_host`

Icinga 2 API hostname. This setting is only valid if kickstart is true. Defaults to localhost

`api_port`

Icinga 2 API port. This setting is only valid if kickstart is true. Defaults to 5665

`api_username`

Icinga 2 API username. This setting is only valid if kickstart is true.

`api_password`

Icinga 2 API password. This setting is only valid if kickstart is true.

Class: `icingaweb2::module::doc`

Install and configure the doc module.

Parameters of icingaweb2::module::doc:

`ensure`

Enable or disable module. Defaults to present

Class: `icingaweb2::module::businessprocess`

Install and enable the businessprocess module.

Parameters of icingaweb2::module::businessprocess:

`ensure`

Enable or disable module. Defaults to present

`git_repository`

Set a git repository URL. Defaults to github.

`git_revision`

Set either a branch or a tag name, eg. master or v2.1.0.

Class: `icingaweb2::module::cube`

Install and configure the cube module.

Parameters of icingaweb2::module::cube: The cube module is installed by cloning the git repository. Set either a branch or a tag name, eg. master or v1.0.0.

`ensure`

Enable or disable module. Defaults to present

`git_repository`

Set a git repository URL. Defaults to github.

`git_revision`

Set either a branch or a tag name, eg. master or v1.0.0.

Class: `icingaweb2::module::generictts`

Install and enable the generictts module.

Parameters of icingaweb2::module::generictts:

`ensure`

Enable or disable module. Defaults to present

`git_repository`

Set a git repository URL. Defaults to github.

`git_revision`

Set either a branch or a tag name, eg. master or v2.0.0.

`ticketsystems`

A hash of ticketsystems. The hash expects a patten and a url for each ticketsystem. The regex pattern is to match the ticket ID, eg. /#([0-9]{4,6})/. Place the ticket ID in the URL, eg. https://my.ticket.system/tickets/id=$1

Example:

ticketsystems => {
  system1 => {
    pattern => '/#([0-9]{4,6})/',
    url     => 'https://my.ticket.system/tickets/id=$1'
  }
}

`ensure`

Enable or disable module. Defaults to present

Class: `icingaweb2::module::puppetdb`

Install and configure the puppetdb module.

Parameters of icingaweb2::module::puppetdb:

`ensure`

Enable or disable module. Defaults to present

`git_repository`

Set a git repository URL. Defaults to github.

`git_revision`

Set either a branch or a tag name, eg. master or v1.3.2.

`ssl`

How to set up ssl certificates. To copy certificates from the local puppet installation, use puppet. Defaults to none

`host`

Hostname of the server where PuppetDB is running. The ssl parameter needs to be set to puppet.

`certificates`

Hash with SSL certificates to configure. See icingaweb2::module::puppetdb::certificate.

Class: `icingaweb2::module::fileshipper`

The fileshipper module extends the Director. It offers import sources to deal with CSV, JSON, YAML and XML files.

Parameters of icingaweb2::module::fileshipper:

`ensure`

Enable or disable module. Defaults to present

`base_directories`

Hash of base directories. These directories can later be selected in the import source (Director).

`directories`

Deploy plain Icinga 2 configuration files through the Director to your Icinga 2 master.

Class: `icingaweb2::module::vsphere`

The vSphere module extends the Director. It provides import sources for virtual machines and physical hosts from vSphere.

Parameters of icingaweb2::module::vsphere:

`ensure`

Enable or disable module. Defaults to present

Class: `icingaweb2::module::graphite`

The Graphite module draws graphs out of time series data stored in Graphite.

Parameters of icingaweb2::module::graphite:

`ensure`

Enable or disable module. Defaults to present

`url`

URL to your Graphite Web

`user`

A user with access to your Graphite Web via HTTP basic authentication

`password`

The users password

`graphite_writer_host_name_template`

The value of your Icinga 2 GraphiteWriter's attribute host_name_template (if specified)

`graphite_writer_service_name_template`

The value of your icinga 2 GraphiteWriter's attribute service_name_template (if specified)

Class: `icingaweb2::module::elasticsearch`

The Elasticsearch module displays events from data stored in Elasticsearch.

Parameters of icingaweb2::module::elasticsearch:

`ensure`

Enable or disable module. Defaults to present

`instances`

A hash that configures one or more Elasticsearch instances that this module connects to. The defined type icingaweb2::module::elasticsearch::instance is used to create the instance configuration.

`eventtypes`

A hash oft ypes of events that should be displayed. Event types are always connected to instances. The defined type icingaweb2::module::elasticsearch::eventtype is used to create the event types.

Private Classes

Class: `icingaweb2::config`

Installs basic configuration files required to run Icinga Web 2.

Class: `icingaweb2::install`

Handles the installation of the Icinga Web 2 package.

Class: `icingaweb2::params`

Stores all default parameters for the Icinga Web 2 installation.

Class: `icingaweb2::repo`

Installs the packages.icinga.com repository. Depending on your operating system puppetlabs/apt or puppet/zypprepo are required.

Public Defined Types

Defined type: `icingaweb2::inisection`

Manage settings in INI configuration files.

Parameters of icingaweb2::inisection:

`target`

Absolute path to the configuration file.

`section_name`

Name of the target section. Settings are set under [$section_name]

`settings`

A hash of settings and their settings. Single settings may be set to absent.

`order`

Ordering of the INI section within a file. Defaults to 01

Defined type: `icingaweb2::config::resource`

Manage settings in INI configuration files.

Parameters of icingaweb2::config::resource:

`resource_name`

Name of the resources. Resources are referenced by their name in other configuration sections.

`type`

Supported resource types are db and ldap.

`host`

Connect to the database or ldap server on the given host. For using unix domain sockets, specify localhost for MySQL and the path to the unix domain socket directory for PostgreSQL. When using the 'ldap' type you can also provide multiple hosts separated by a space.

`port`

Port number to use.

`db_type`

Supported DB types are mysql and pgsql. Only valid when type is db.

`db_name`

The database to use. Only valid if type is db.

`db_username`

The username to use when connecting to the server. Only valid if type is db.

`db_password`

The password to use when connecting to the server. Only valid if type is db.

`db_charset`

The character set to use for the database connection. Only valid if type is db.

`ldap_root_dn`

Root object of the tree, e.g. ou=people,dc=icinga,dc=com. Only valid if type is ldap.

`ldap_bind_dn`

The user to use when connecting to the server. Only valid if type is ldap.

`ldap_bind_pw`

The password to use when connecting to the server. Only valid if type is ldap.

`ldap_encryption`

Type of encryption to use: none (default), starttls, ldaps. Only valid if type is ldap.

Defined type: `icingaweb2::config::authmethod`

Manage Icinga Web 2 authentication methods. Auth methods may be chained by setting proper ordering. Some backends require additional resources.

Parameters of icingaweb2::config::authmethod:

`backend`

Select between 'external', 'ldap', 'msldap' or 'db'. Each backend may require other settings.

`resource`

The name of the resource defined in resources.ini.

`ldap_user_class`

LDAP user class. Only valid if backend is ldap.

`ldap_user_name_attribute`

LDAP attribute which contains the username. Only valid if backend is ldap.

`ldap_filter`

LDAP search filter. Only valid if backend is ldap.

`ldap_base_dn`

LDAP base DN. Only valid if backend is ldap.

`domain`

Domain for domain-aware authentication.

`order`

Multiple authentication methods can be chained. The order of entries in the authentication configuration determines the order of the authentication methods. Defaults to 01

Defined type: `icingaweb2::config::role`

Roles define a set of permissions that may be applied to users or groups.

Parameters of icingaweb2::config::role:

`role_name`

Name of the role.

`users`

Comma separated list of users this role applies to.

`groups`

Comma separated list of groups this role applies to.

`permissions`

Comma separated lsit of permissions. Each module may add it's own permissions. Examples are

Allow everything: *
Allow config access: config/*
Allow access do module monitoring: module/monitoring
Allow scheduling checks: monitoring/command/schedule-checks
Grant admin permissions: admin

`filters`

Hash of filters. Modules may add new filter keys, some sample keys are:

application/share/users
application/share/groups
monitoring/filter/objects
monitoring/blacklist/properties

A string value is expected for each used key. For example:

monitoring/filter/objects = host_name!=*win*

Defined type: `icingaweb2::config::groupbackend`

Groups of users can be stored either in a database, LDAP or ActiveDirectory. This defined type configures backends that store groups.

Parameters of icingaweb2::config::groupbackend:

`group_name`

Name of the resources. Resources are referenced by their name in other configuration sections.

`backend`

Type of backend. Valide values are: db, ldap and msldap. Each backend supports different settings, see the parameters for detailed information.

`resource`

The resource used to connect to the backend. The resource contains connection information.

`ldap_user_backend`

A group backend can be connected with an authentication method. This parameter references the auth method. Only valid with backend ldap or msldap.

`ldap_group_class`

Class used to identify group objects. Only valid with backend ldap.

`ldap_group_filter`

Use a LDAP filter to receive only certain groups. Only valid with backend ldap or msldap.

`ldap_group_name_attribute`

The group name attribute. Only valid with backend ldap.

`ldap_group_member_attribute`

The group member attribute. Only valid with backend ldap.

`ldap_base_dn`

Base DN that is searched for groups. Only valid with backend ldap with msldap.

`ldap_nested_group_search`

Search for groups in groups. Only valid with backend msldap.

`domain`

Domain for domain-aware authentication.

Defined type: `icingaweb2::module`

Download, enable and configure Icinga Web 2 modules. This is a public defined type and is meant to be used to install modules developed by the community as well.

Parameters of icingaweb2::module:

`ensure`

Enable or disable module. Defaults to present

`module`

Name of the module.

`module_dir`

Target directory of the module.

`install_method`

Install methods are git, package and none is supported as installation method. Defaults to git

`git_repository`

Git repository of the module. This setting is only valid in combination with the installation method git.

`git_revision`

Tag or branch of the git repository. This setting is only valid in combination with the installation method git.

`package_name`

Package name of the module. This setting is only valid in combination with the installation method package.

`settings`

A hash with the module settings. Multiple configuration files with ini sections can be configured with this hash. The module_name should be used as target directory for the configuration files.

Example:

 $conf_dir        = $::icingaweb2::params::conf_dir
 $module_conf_dir = "${conf_dir}/modules/mymodule"

 $settings = {
   'section1' => {
     'target'   => "${module_conf_dir}/config1.ini",
     'settings' => {
       'setting1' => 'value1',
       'setting2' => 'value2',
     }
   },
   'section2' => {
     'target'   => "${module_conf_dir}/config2.ini",
     'settings' => {
       'setting3' => 'value3',
       'setting4' => 'value4',
     }
   }
 }

Private Defined Types

Defined type: `icingaweb2::module::generictts::ticketsystem`

Manage ticketsystem configuration for the generictts module.

Parameters of icingaweb2::module::generictts::ticketsystem:

`ticketsystem`

The name of the ticketsystem.

`pattern`

A regex pattern to match ticket numbers, eg. /#([0-9]{4,6})/

`url`

The URL to your ticketsystem. Place the ticket ID in the URL, eg. https://my.ticket.system/tickets/id=$1

Defined type: `icingaweb2::module::monitoring::commandtransport`

Manage commandtransports for the monitoring module.

Parameters of icingaweb2::module::monitoring::commandtransport:

`commandtransport`

The name of the commandtransport.

`transport`

The transport type you wish to use. Either api or local. Defaults to api

`host`

Hostname/ip for the transport. Only needed for api transport. Defaults to localhost

`port`

Port for the transport. Only needed for api transport. Defaults to 5665

`username`

Username for the transport. Only needed for api transport.

`password`

Password for the transport. Only needed for api transport.

`path`

Path for the transport. Only needed for local transport. Defaults to /var/run/icinga2/cmd/icinga2.cmd

Defined type: `icingaweb2::module::puppetdb::certificate`

Add extra certificates to the puppetdb module

Parameters of icingaweb2::module::puppetdb::certificate:

`ensure`

Enable or disable certificate. Defaults to present

`ssl_key`

Contents of the combined SSL key.

`ssl_cacert`

CA certificate

Defined type: `icingaweb2::module::fileshipper::basedir`

Manage base directories for the fileshipper module

Parameters of icingaweb2::module::fileshipper::basedir:

`identifier`

Identifier of the base directory

`basedir`

Absolute path of a direcory

Defined type: `icingaweb2::module::fileshipper::directory`

Manage directories with plain Icinga 2 configuration files

Parameters of icingaweb2::module::fileshipper::directory:

`identifier`

Identifier of the base directory

`source`

Absolute path of the source direcory

`target`

Absolute path of the target direcory

`extensions`

Only files with these extensions will be synced. Defaults to .conf

Defined type: `icingaweb2::module::elasticsearch::instance`

Manage an Elasticsearch instance

Parameters of icingaweb2::module::elasticsearch::instance:

`name`

Name of the Elasticsearch instance

`uri`

URI to the Elasticsearch instance

`user`

The user to use for authentication

`password`

The password to use for authentication

`ca`

The path of the file containing one or more certificates to verify the peer with or the path to the directory that holds multiple CA certificates.

`client_certificate`

The path of the client certificates

`client_private_key`

The path of the client private key

Defined type: `icingaweb2::module::elasticsearch::eventtype`

Manage an Elasticsearch event type

Parameters of icingaweb2::module::elasticsearch::eventtype:

`name*]

Name of the event type.

`instance*]

Elasticsearch instance to connect to.

`index*]

Elasticsearch index pattern, e.g. filebeat-*.

`filter*]

Elasticsearch filter in the Icinga Web 2 URL filter format. Host macros are evaluated if you encapsulate them in curly braces, e.g. host={host.name}&location={_host_location}.

`fields*]

Comma-separated list of field names to display. One or more wildcard asterisk (*) patterns are also accepted. Note that the @timestamp field is always respected.

Development

A roadmap of this project is located at https://github.com/Icinga/puppet-icingaweb2/milestones. Please consider this roadmap when you start contributing to the project.

Contributing

When contributing several steps such as pull requests and proper testing implementations are required. Find a detailed step by step guide in CONTRIBUTING.md.

Testing

Testing is essential in our workflow to ensure a good quality. We use RSpec as well as Serverspec to test all components of this module. For a detailed description see TESTING.md.

Release Notes

When releasing new versions we refer to [SemVer 1.0.0] for version numbers. All steps required when creating a new release are described in RELEASE.md

Authors

AUTHORS is generated on each release.

Icinga Web 2 Puppet Module

Table of Contents

Overview

Description

Setup

What the Icinga 2 Puppet module supports

Dependencies

Limitations

Usage

Install Icinga Web 2

Manage Resources

Manage Authentication Methods

DB Schema and Default User

MySQL

PostgreSQL

Manage Roles

Manage Group Backends

Install and Manage Modules

Monitoring

Director

Doc

PuppetDB

Business Process

Cube

GenericTTS

Fileshipper

vSphere

Graphite

Elasticsearch

Reference

Public Classes

Class: icingaweb2

logging

logging_file

logging_level

show_stacktraces

module_path

theme

theme_disabled

manage_repo

manage_package

extra_pacakges

import_schema

db_type

db_host

db_port

db_name

db_username

db_password

config_backend

conf_user

default_domain

Class: icingaweb2::module::monitoring

ensure

protected_customvars

ido_type

ido_host

ido_port

ido_db_name

ido_db_username

ido_db_password

ido_db_charset

commandtransports

Class: icingaweb2::module::director

ensure

git_repository

git_revision

db_type

db_host

db_port

db_name

db_username

db_password

ido_db_charset

import_schema

kickstart

endpoint

api_host

api_port

api_username

Class: `icingaweb2`

`logging`

`logging_file`

`logging_level`

`show_stacktraces`

`module_path`

`theme`

`theme_disabled`

`manage_repo`

`manage_package`

`extra_pacakges`

`import_schema`

`db_type`

`db_host`

`db_port`

`db_name`

`db_username`

`db_password`

`config_backend`

`conf_user`

`default_domain`

Class: `icingaweb2::module::monitoring`

`ensure`

`protected_customvars`

`ido_type`

`ido_host`

`ido_port`

`ido_db_name`

`ido_db_username`

`ido_db_password`

`ido_db_charset`

`commandtransports`

Class: `icingaweb2::module::director`

`ensure`

`git_repository`

`git_revision`

`db_type`

`db_host`

`db_port`

`db_name`

`db_username`

`db_password`

`ido_db_charset`

`import_schema`

`kickstart`

`endpoint`

`api_host`

`api_port`

`api_username`

`api_password`

Class: `icingaweb2::module::doc`

`ensure`

Class: `icingaweb2::module::businessprocess`

`ensure`

`git_repository`

`git_revision`

Class: `icingaweb2::module::cube`

`ensure`

`git_repository`

`git_revision`

Class: `icingaweb2::module::generictts`

`ensure`

`git_repository`

`git_revision`

`ticketsystems`

`ensure`

Class: `icingaweb2::module::puppetdb`

`ensure`

`git_repository`

`git_revision`

`ssl`

`host`

`certificates`

Class: `icingaweb2::module::fileshipper`

`ensure`

`base_directories`

`directories`

Class: `icingaweb2::module::vsphere`

`ensure`

Class: `icingaweb2::module::graphite`