Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

icingaweb2

Icinga Web 2 Puppet Module
Project URLRSS FeedReport issues

626,547 downloads

1,071 latest version

5.0 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Version information

  • 4.0.0 (latest)
  • 3.10.1
  • 3.10.0
  • 3.9.1
  • 3.9.0
  • 3.8.0
  • 3.7.3
  • 3.7.2
  • 3.7.1
  • 3.7.0
  • 3.6.1
  • 3.6.0
  • 3.5.0
  • 3.4.1
  • 3.4.0
  • 3.3.0
  • 3.2.4
  • 3.2.3
  • 3.2.2
  • 3.2.1
  • 3.2.0 (deleted)
  • 3.1.0
  • 3.0.1
  • 3.0.0
  • 2.4.1
  • 2.4.0
  • 2.3.1
  • 2.3.0
  • 2.2.0
  • 2.1.0
  • 2.0.1
  • 2.0.0
  • 1.0.6
  • 1.0.5
  • 1.0.4
  • 1.0.3
  • 1.0.2 (deleted)
released Jun 25th 2019
This version is compatible with:
  • Puppet Enterprise 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x, 2018.1.x, 2017.3.x, 2017.2.x, 2017.1.x, 2016.5.x, 2016.4.x
  • Puppet >= 4.7.0 < 7.0.0
  • , , , ,
This module has been deprecated by its author since Jun 3rd 2024.

The author has suggested puppet-icingaweb2 as its replacement.

Start using this module

Tags: monitoring, icinga, icinga2, icingaweb2

Documentation

icinga/icingaweb2 — version 2.3.1 Jun 25th 2019

Build Status

Icinga Web 2 Puppet Module

Table of Contents

  1. Overview
  2. Module Description - What the module does and why it is useful
  3. Setup - The basics of getting started with Icinga Web 2
  4. Usage - Configuration options and additional functionality
  5. Reference - An under-the-hood peek at what the module is doing and how
  6. 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 the following modules may also be required:

Limitations

This module has been tested on:

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.

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

Reference

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

logging_facility

Logging facilty for syslog. Allowed values are user and local0 through local7. Defaults to user

logging_application

Logging application name for syslog. Defaults to icingaweb2

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.

cookie_path

Set the Cookie validity path for the Icinga Web 2 sessions.

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 and Puppet version puppetlabs/apt, puppetlabs/yumrepo_core, or puppet/zypprepo is 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

See also CHANGELOG.md

Authors

AUTHORS is generated on each release.