diff --git a/README.md b/README.md index 424f0cd..44d8fe5 100644 --- a/README.md +++ b/README.md @@ -1,247 +1,247 @@ [![Build Status](https://travis-ci.org/Icinga/puppet-icingaweb2.png?branch=master)](https://travis-ci.org/Icinga/puppet-icingaweb2) # Icinga Web 2 Puppet Module #### Table of Contents 1. [Overview](#overview) 2. [Module Description - What the module does and why it is useful](#module-description) 3. [Setup - The basics of getting started with Icinga Web 2](#setup) * [What Icinga Web 2 affects](#what-icinga-web-2-affects) 4. [Usage - Configuration options and additional functionality](#usage) 5. [Reference](#reference) 6. [Development - Guide for contributing to the module](#development) ## 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](https://www.icinga.com/products/icinga-web-2-modules/) as well as modules developed by the community. ### What's new in version 3.0.0 * The current version now uses the `icinga::repos` class from the new module `icinga` for the configuration of repositories including EPEL on RedHat and Backports on Debian. (see https://github.com/icinga/puppet-icinga) ## 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 * [icinga/icinga] >= 1.0.0 * needed if `manage_repos` is set to `true` -* [puppetlabs/stdlib] >= 4.16.0 +* [puppetlabs/stdlib] >= 4.25.0 * [puppetlabs/vcsrepo] >= 1.3.0 * [puppetlabs/concat] >= 2.0.1 ### Limitations This module has been tested on: * Debian 9, 10 * CentOS/RHEL 6, 7, 8 * Requires [Software Collections Repository](https://wiki.centos.org/AdditionalResources/Repositories/SCL) * Ubuntu 16.04, 18.04, 20.04 * SLES 12, 15 Other operating systems or versions may work but have not been tested. ## Usage NOTE: If you plan to use additional modules from git, the CLI `git` command has to be installed. You can manage it yourself as package resource or declare the package name in `extra_packages`. By default, your distribution's packages are used to install Icinga Web 2. Use the `manage_repos` parameter to configure repositories by default the official and stable [packages.icinga.com]. To configure your own repositories, or use the official testing or nightly snapshot stage, see https://github.com/icinga/puppet-icinga. ``` puppet class { '::icingaweb2': manage_repos => true, } ``` The usage of this module isn't simple. That depends on how Icinga Web 2 is implemented. Monitoring is here just a module in a framework. All basic stuff like authentication, logging or authorization is done by this framework. To store user and usergroups in a MySQL database, the database has to exist: ``` mysql::db { 'icingaweb2': user => 'icingaweb2', password => 'supersecret', host => 'localhost', grant => [ 'ALL' ], } class {'icingaweb2': manage_repos => true, import_schema => true, db_type => 'mysql', db_host => 'localhost', db_port => 3306, db_username => 'icingaweb2', db_password => 'supersecret', config_backend => 'db', extra_packages => [ 'git' ], require => Mysql::Db['icingaweb2'], } ``` If you set `import_schema` to `true` an default admin user `icingaadmin` with password `icinga` will be created automatically and you're allowed to login. In case that `import_schema` is disabled or you'd like to use a different backend for authorization like LDAP, more work is required. At first we need a ressource with credentials to connect a LDAP server: ``` class {'icingaweb2': manage_repos => true, } icingaweb2::config::resource{ 'my-ldap': type => 'ldap', host => 'localhost', port => 389, ldap_root_dn => 'ou=users,dc=icinga,dc=com', ldap_bind_dn => 'cn=icingaweb2,ou=users,dc=icinga,dc=com', ldap_bind_pw => 'supersecret', } ``` With the help of this resource, we are now creating user and group backends. Users are permitted to login and users and groups will later be used for authorization. ``` icingaweb2::config::authmethod { 'ldap-auth': backend => 'ldap', resource => 'my-ldap', ldap_user_class => 'user', ldap_filter => '(memberof:1.2.840.113556.1.4.1941:=CN=monitoring,OU=groups,DC=icinga,DC=com)', ldap_user_name_attribute => 'cn', order => '05', } icingaweb2::config::groupbackend { 'ldap-groups': backend => 'ldap', resource => 'my-ldap', ldap_group_class => 'group', ldap_group_name_attribute => 'cn', ldap_group_member_attribute => 'member', ldap_base_dn => 'ou=groups,dc=icinga,dc=com', domain => 'icinga.com', } ``` So that a group gets admin rights a role has to manage: ``` icingaweb2::config::role { 'default admin user': groups => 'icingaadmins', permissions => '*', } ``` All available permissions for module monitoring are listed below: | 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` | Finally we configure the monitoring with the needed connection to the IDO to get information and an API user to send commands to Icinga 2: ``` class {'icingaweb2::module::monitoring': ido_host => 'localhost', ido_db_type => 'mysql', ido_db_name => 'icinga2', ido_db_username => 'icinga2', ido_db_password => 'supersecret', commandtransports => { icinga2 => { transport => 'api', username => 'icingaweb2', password => 'supersecret', } } } ``` ## Reference See [REFERENCE.md](https://github.com/Icinga/puppet-icingaweb2/blob/master/REFERENCE.md) ## 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. [Icinga 2]: https://www.icinga.com/products/icinga-2/ [Icinga Web 2]: https://www.icinga.com/products/icinga-web-2/ [icinga/icinga]: https://github.com/icinga/puppet-icinga/ [puppetlabs/stdlib]: https://github.com/puppetlabs/puppetlabs-stdlib [puppetlabs/concat]: https://github.com/puppetlabs/puppetlabs-concat [puppetlabs/vcsrepo]: https://forge.puppet.com/puppetlabs/vcsrepo [puppetlabs/mysql]: https://github.com/puppetlabs/puppetlabs-mysql [puppetlabs/puppetlabs-postgresql]: https://github.com/puppetlabs/puppetlabs-postgresql [packages.icinga.com]: https://packages.icinga.com [CHANGELOG.md]: CHANGELOG.md [AUTHORS]: AUTHORS [RELEASE.md]: RELEASE.md [TESTING.md]: TESTING.md [CONTRIBUTING.md]: CONTRIBUTING.md diff --git a/metadata.json b/metadata.json index 22a0499..ed04e5d 100644 --- a/metadata.json +++ b/metadata.json @@ -1,87 +1,87 @@ { "name": "icinga-icingaweb2", "version": "3.1.0", "author": "Icinga Team", "summary": "Icinga Web 2 Puppet Module", "license": "Apache-2.0", "source": "git://github.com/Icinga/puppet-icingaweb2", "project_page": "https://github.com/Icinga/puppet-icingaweb2", "issues_url": "https://github.com/Icinga/puppet-icingaweb2/issues", "dependencies": [ { "name": "puppetlabs/stdlib", - "version_requirement": ">= 4.16.0 < 8.0.0" + "version_requirement": ">= 4.25.0 < 8.0.0" }, { "name": "puppetlabs/concat", "version_requirement": ">= 2.0.1 < 8.0.0" }, { "name": "icinga/icinga", "version_requirement": ">= 1.0.0 < 3.0.0" }, { "name": "puppetlabs/vcsrepo", "version_requirement": ">= 1.3.0 < 6.0.0" }, { "name": "puppet/systemd", "version_requirement": ">= 1.1.1 < 4.0.0" } ], "operatingsystem_support": [ { "operatingsystem": "Debian", "operatingsystemrelease": [ "9", "10" ] }, { "operatingsystem": "RedHat", "operatingsystemrelease": [ "6", "7", "8" ] }, { "operatingsystem": "CentOS", "operatingsystemrelease": [ "6", "7", "8" ] }, { "operatingsystem": "Ubuntu", "operatingsystemrelease": [ "16.04", "18.04", "20.04" ] }, { "operatingsystem": "SLES", "operatingsystemrelease": [ "12", "15" ] } ], "requirements": [ { "name": "puppet", "version_requirement": ">= 4.7.0 < 8.0.0" } ], "tags": [ "icinga", "icinga2", "icingaweb2", "monitoring" ], "pdk-version": "1.18.1", "template-url": "pdk-default#1.18.1", "template-ref": "tags/1.18.1-0-g3d2e75c" }