From 05e3c267c4b45bd9e41c6cdc5af771f8e90f169b Mon Sep 17 00:00:00 2001 From: Michael Friedrich Date: Sun, 17 Aug 2014 16:14:42 +0200 Subject: [PATCH] Add AUTHORS, update install instructions --- .mailmap | 5 + AUTHORS | 2 + doc/configuration.md | 215 ++++++++++++++++++++++++++++++++++++++++ doc/installation.md | 230 +++++-------------------------------------- 4 files changed, 249 insertions(+), 203 deletions(-) create mode 100644 .mailmap create mode 100644 AUTHORS create mode 100644 doc/configuration.md diff --git a/.mailmap b/.mailmap new file mode 100644 index 0000000..140198f --- /dev/null +++ b/.mailmap @@ -0,0 +1,5 @@ + + +Gunnar Beutner + + diff --git a/AUTHORS b/AUTHORS new file mode 100644 index 0000000..564064e --- /dev/null +++ b/AUTHORS @@ -0,0 +1,2 @@ +Michael Friedrich +Nick Chappell diff --git a/doc/configuration.md b/doc/configuration.md new file mode 100644 index 0000000..bfd71a5 --- /dev/null +++ b/doc/configuration.md @@ -0,0 +1,215 @@ +# puppet-icinga2 Installation + +## Requirements + +For Ubuntu systems, this module requires the [Puppet Labs apt module](https://github.com/puppetlabs/puppetlabs-apt). + +On EL-based systems (CentOS, Red Hat Enterprise Linux, Fedora, etc.), the [EPEL package repository](https://fedoraproject.org/wiki/EPEL) is required. + +### Server requirements + +Icinga 2 requires either a [MySQL](http://www.mysql.com/) or a [Postgres](http://www.postgresql.org/) 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](https://github.com/puppetlabs/puppetlabs-mysql) or [Postgres](https://github.com/puppetlabs/puppetlabs-postgresql) modules can be used. + +Database connection parameters can be specified by the `db_host`, `db_port`, `db_name`, `db_user` and `db_password` parameters. + +The example below shows the [Puppet Labs Postgres module](https://github.com/puppetlabs/puppetlabs-postgresql) 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](http://docs.puppetlabs.com/hiera/1/puppet.html) so the password isn't sitting in your site manifests in plain text. + +To configure Icinga with the password you set up for the Postgres Icinga user, use the `server_db_password` parameter (shown here with a Hiera lookup): + +
+  class { 'icinga2::server':
+    server_db_password => hiera('icinga_db_password_key_here')
+  }
+
+ +##Usage + +###Server usage + +To install Icinga 2 with a Postgres database, first set up the database. + +Once the database is set up, use the `icinga2::server` class with the database connection parameters to specify + +
+#Install Icinga 2:
+class { 'icinga2::server': 
+  server_db_type => 'pgsql',
+  db_host => 'localhost'
+  db_port => '5432'
+  db_name => 'icinga2_data'
+  db_user => 'icinga2'
+  db_password => 'password',
+}
+
+ +When the `server_db_type` parameter is set, the right IDO database connection packages are automatically installed and the schema is loaded. + +**Note:** For production use, you'll probably want to get the database password via a [Hiera lookup](http://docs.puppetlabs.com/hiera/1/puppet.html) so the password isn't sitting in your site manifests in plain text: + +
+#Install Icinga 2:
+class { 'icinga2::server': 
+  server_db_type => 'pgsql',
+  db_host => 'localhost'
+  db_port => '5432'
+  db_name => 'icinga2_data'
+  db_user => 'icinga2'
+  db_password => hiera('icinga_db_password_key_here'),
+}
+
+ +**Note:** If you will be installing NRPE or the Nagios plugins packages with the `icinga2::nrpe` class on a node that also has the `icinga2::server` class applied, be sure to set the `$server_install_nagios_plugins` parameter in your call to `icinga2::server` to `false`: + +
+#Install Icinga 2:
+class { 'icinga2::server': 
+  ...
+  server_install_nagios_plugins => false,
+  ...
+ }
+
+ +This will stop the `icinga2::server` class from trying to install the plugins pacakges, since the `icinga2::nrpe` class will already be installing them and will prevent a resulting duplicate resource error. + +###Client usage + +To install NRPE and allow the local machine and Icinga 2 servers (or Icinga 1 or plain old Nagios servers) with various IP addresess to connect: + +
+class { 'icinga2::nrpe':
+  nrpe_allowed_hosts => ['10.0.1.79', '10.0.1.80', '10.0.1.85', '127.0.0.1'],
+}
+
+ +**Note:** If you would like to install NRPE on a node that also has the `icinga2::server` class applied, be sure to set the `$server_install_nagios_plugins` parameter in your call to `icinga2::server` to `false`: + +
+#Install Icinga 2:
+class { 'icinga2::server': 
+  server_db_type => 'pgsql',
+  server_install_nagios_plugins => false,
+ }
+
+ +This will stop the `icinga2::server` class from trying to install the plugins pacakges, since the `icinga2::nrpe` class will already be installing them and will prevent a resulting duplicate resource error. + +###Object type usage + +This module includes several defined types that can be used to automatically generate Icinga 2 format object definitions. They function in a similar way to [the built-in Nagios types that are included in Puppet](http://docs.puppetlabs.com/guides/exported_resources.html#exported-resources-with-nagios). + +####Exported resources + +Like the built-in Nagios types, they can be exported to PuppetDB as virtual resources and collected on your Icinga 2 server. + +Nodes that are being monitored can have the `@@` virtual resources applied to them: + +
+@@icinga2::object::host { $::fqdn:
+  display_name => $::fqdn,
+  ipv4_address => $::ipaddress_eth0,
+  groups => ['linux_servers', 'mysql_servers'],
+  vars => {
+    os              => 'linux',
+    virtual_machine => 'true',
+    distro          => $::operatingsystem,
+  },
+  target_dir => '/etc/icinga2/objects/hosts',
+  target_file_name => "${fqdn}.conf"
+}
+
+ +Then, on your Icinga 2 server, you can collect the exported virtual resources (notice the camel casing in the class name): + +
+#Collect all @@icinga2::object::host resources from PuppetDB that were exported by other machines:
+Icinga2::Object::Host <<| |>> { }
+
+ +Unlike the built-in Nagios types, the file owner, group and mode of the automatically generated files can be controlled via the `target_file_owner`, `target_file_group` and `target_file_mode` parameters: + +
+@@icinga2::object::host { $::fqdn:
+  display_name => $::fqdn,
+  ipv4_address => $::ipaddress_eth0,
+  groups => ['linux_servers', 'mysql_servers'],
+  vars => {
+    os              => 'linux',
+    virtual_machine => 'true',
+    distro          => $::operatingsystem,
+  },
+  target_dir        => '/etc/icinga2/objects/hosts',
+  target_file_name  => "${fqdn}.conf"
+  target_file_owner => 'root',
+  target_file_group => 'root',
+  target_file_mode  => '644'
+}
+
+ +####`undef` and default object values + +Most of the object parameters *in the Puppet module* are set to **undef**. + +This means that they will not be added to the rendered object definition files. + +**However**, this doesn't mean that the values are undefined in Icinga 2. Icinga 2 itself has built-in default values for many object parameters and falls back to them if one isn't present in an object definition. See the docs for individual object types in [Configuring Icinga 2](http://docs.icinga.org/icinga2/latest/doc/module/icinga2/toc#!/icinga2/latest/doc/module/icinga2/chapter/configuring-icinga2) for more info about which object parameters have what default values. + +####`icinga2::object::host` + +**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::apply_service_to_host` + +The `apply_service_to_host` defined type can create `apply` objects to apply services to hosts: + +
+#Create an apply that checks the number of zombie processes:
+icinga2::object::apply_service_to_host { 'check_zombie_procs':
+  display_name => 'Zombie procs',
+  check_command => 'nrpe',
+  vars => {
+    nrpe_command => 'check_zombie_procs',
+  },
+  assign_where => '"linux_servers" in host.groups',
+  ignore_where => 'host.name == "localhost"',
+  target_dir => '/etc/icinga2/objects/applys'
+}
+
+ +This defined type has the same available parameters that the `icinga2::object::service` defined type does. + +The `assign_where` and `ignore_where` parameter values are meant to be provided as strings. Since Icinga 2 requires that string literals be double-quoted, the whole string in your Puppet site manifests will have to be single-quoted (leaving the double quotes intact inside): + +
+assign_where => '"linux_servers" in host.groups',
+
+ +If you would like to use Puppet or Facter variables in an `assign_where` or `ignore_where` parameter's value, you'll first need to double-quote the whole value for [Puppet's variable interpolation](http://docs.puppetlabs.com/puppet/latest/reference/lang_datatypes.html#double-quoted-strings) 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}"",
+
diff --git a/doc/installation.md b/doc/installation.md index bfd71a5..a7db606 100644 --- a/doc/installation.md +++ b/doc/installation.md @@ -1,215 +1,39 @@ # puppet-icinga2 Installation -## Requirements +## Installing the Puppet Module -For Ubuntu systems, this module requires the [Puppet Labs apt module](https://github.com/puppetlabs/puppetlabs-apt). +Put it in your modules directly and configure your manifest. -On EL-based systems (CentOS, Red Hat Enterprise Linux, Fedora, etc.), the [EPEL package repository](https://fedoraproject.org/wiki/EPEL) is required. +## Building Release Tarballs -### Server requirements +In order to build a release tarball you should first check out the Git repository +in a new directory. If you're using an existing check-out you should make sure +that there are no local modifications: -Icinga 2 requires either a [MySQL](http://www.mysql.com/) or a [Postgres](http://www.postgresql.org/) database. +$ git status -Currently, this module does not set up any databases. You'll have to create one before installing Icinga 2 via the module. +Here's a short check-list for releases: -If you would like to set up your own database, either of the Puppet Labs [MySQL](https://github.com/puppetlabs/puppetlabs-mysql) or [Postgres](https://github.com/puppetlabs/puppetlabs-postgresql) modules can be used. +* Update the .mailmap and AUTHORS files + $ git log --use-mailmap | grep ^Author: | cut -f2- -d' ' | sort | uniq > AUTHORS +* Bump the version in metadata.json. +* Update the ChangeLog file. +* Commit these changes to the "master" branch and create a signed tag (tags/v). + $ git commit -v -a -m "Release version " + $ git tag -u EE8E0720 -m "Version " v + $ git push --tags +* Merge the "master" branch into the "support/2.0" branch (using --ff-only). + $ git checkout support/2.0 + $ git merge --ff-only master + $ git push origin support/2.0 +* Bump the version to "v-dev" and commit this change to the "master" branch. -Database connection parameters can be specified by the `db_host`, `db_port`, `db_name`, `db_user` and `db_password` parameters. +Use "git archive" to build the release tarball: -The example below shows the [Puppet Labs Postgres module](https://github.com/puppetlabs/puppetlabs-postgresql) being used to install Postgres and create a database and database user for Icinga 2: +$ VERSION=2.0.0 +$ git archive --format=tar --prefix=puppet-icinga2-$VERSION/ tags/v$VERSION | gzip >puppet-icinga2-$VERSION.tar.gz -
-  class { 'postgresql::server': }
+Finally you should verify that the tarball only contains the files it should contain:
 
-  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](http://docs.puppetlabs.com/hiera/1/puppet.html) so the password isn't sitting in your site manifests in plain text. - -To configure Icinga with the password you set up for the Postgres Icinga user, use the `server_db_password` parameter (shown here with a Hiera lookup): - -
-  class { 'icinga2::server':
-    server_db_password => hiera('icinga_db_password_key_here')
-  }
-
- -##Usage - -###Server usage - -To install Icinga 2 with a Postgres database, first set up the database. - -Once the database is set up, use the `icinga2::server` class with the database connection parameters to specify - -
-#Install Icinga 2:
-class { 'icinga2::server': 
-  server_db_type => 'pgsql',
-  db_host => 'localhost'
-  db_port => '5432'
-  db_name => 'icinga2_data'
-  db_user => 'icinga2'
-  db_password => 'password',
-}
-
- -When the `server_db_type` parameter is set, the right IDO database connection packages are automatically installed and the schema is loaded. - -**Note:** For production use, you'll probably want to get the database password via a [Hiera lookup](http://docs.puppetlabs.com/hiera/1/puppet.html) so the password isn't sitting in your site manifests in plain text: - -
-#Install Icinga 2:
-class { 'icinga2::server': 
-  server_db_type => 'pgsql',
-  db_host => 'localhost'
-  db_port => '5432'
-  db_name => 'icinga2_data'
-  db_user => 'icinga2'
-  db_password => hiera('icinga_db_password_key_here'),
-}
-
- -**Note:** If you will be installing NRPE or the Nagios plugins packages with the `icinga2::nrpe` class on a node that also has the `icinga2::server` class applied, be sure to set the `$server_install_nagios_plugins` parameter in your call to `icinga2::server` to `false`: - -
-#Install Icinga 2:
-class { 'icinga2::server': 
-  ...
-  server_install_nagios_plugins => false,
-  ...
- }
-
- -This will stop the `icinga2::server` class from trying to install the plugins pacakges, since the `icinga2::nrpe` class will already be installing them and will prevent a resulting duplicate resource error. - -###Client usage - -To install NRPE and allow the local machine and Icinga 2 servers (or Icinga 1 or plain old Nagios servers) with various IP addresess to connect: - -
-class { 'icinga2::nrpe':
-  nrpe_allowed_hosts => ['10.0.1.79', '10.0.1.80', '10.0.1.85', '127.0.0.1'],
-}
-
- -**Note:** If you would like to install NRPE on a node that also has the `icinga2::server` class applied, be sure to set the `$server_install_nagios_plugins` parameter in your call to `icinga2::server` to `false`: - -
-#Install Icinga 2:
-class { 'icinga2::server': 
-  server_db_type => 'pgsql',
-  server_install_nagios_plugins => false,
- }
-
- -This will stop the `icinga2::server` class from trying to install the plugins pacakges, since the `icinga2::nrpe` class will already be installing them and will prevent a resulting duplicate resource error. - -###Object type usage - -This module includes several defined types that can be used to automatically generate Icinga 2 format object definitions. They function in a similar way to [the built-in Nagios types that are included in Puppet](http://docs.puppetlabs.com/guides/exported_resources.html#exported-resources-with-nagios). - -####Exported resources - -Like the built-in Nagios types, they can be exported to PuppetDB as virtual resources and collected on your Icinga 2 server. - -Nodes that are being monitored can have the `@@` virtual resources applied to them: - -
-@@icinga2::object::host { $::fqdn:
-  display_name => $::fqdn,
-  ipv4_address => $::ipaddress_eth0,
-  groups => ['linux_servers', 'mysql_servers'],
-  vars => {
-    os              => 'linux',
-    virtual_machine => 'true',
-    distro          => $::operatingsystem,
-  },
-  target_dir => '/etc/icinga2/objects/hosts',
-  target_file_name => "${fqdn}.conf"
-}
-
- -Then, on your Icinga 2 server, you can collect the exported virtual resources (notice the camel casing in the class name): - -
-#Collect all @@icinga2::object::host resources from PuppetDB that were exported by other machines:
-Icinga2::Object::Host <<| |>> { }
-
- -Unlike the built-in Nagios types, the file owner, group and mode of the automatically generated files can be controlled via the `target_file_owner`, `target_file_group` and `target_file_mode` parameters: - -
-@@icinga2::object::host { $::fqdn:
-  display_name => $::fqdn,
-  ipv4_address => $::ipaddress_eth0,
-  groups => ['linux_servers', 'mysql_servers'],
-  vars => {
-    os              => 'linux',
-    virtual_machine => 'true',
-    distro          => $::operatingsystem,
-  },
-  target_dir        => '/etc/icinga2/objects/hosts',
-  target_file_name  => "${fqdn}.conf"
-  target_file_owner => 'root',
-  target_file_group => 'root',
-  target_file_mode  => '644'
-}
-
- -####`undef` and default object values - -Most of the object parameters *in the Puppet module* are set to **undef**. - -This means that they will not be added to the rendered object definition files. - -**However**, this doesn't mean that the values are undefined in Icinga 2. Icinga 2 itself has built-in default values for many object parameters and falls back to them if one isn't present in an object definition. See the docs for individual object types in [Configuring Icinga 2](http://docs.icinga.org/icinga2/latest/doc/module/icinga2/toc#!/icinga2/latest/doc/module/icinga2/chapter/configuring-icinga2) for more info about which object parameters have what default values. - -####`icinga2::object::host` - -**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::apply_service_to_host` - -The `apply_service_to_host` defined type can create `apply` objects to apply services to hosts: - -
-#Create an apply that checks the number of zombie processes:
-icinga2::object::apply_service_to_host { 'check_zombie_procs':
-  display_name => 'Zombie procs',
-  check_command => 'nrpe',
-  vars => {
-    nrpe_command => 'check_zombie_procs',
-  },
-  assign_where => '"linux_servers" in host.groups',
-  ignore_where => 'host.name == "localhost"',
-  target_dir => '/etc/icinga2/objects/applys'
-}
-
- -This defined type has the same available parameters that the `icinga2::object::service` defined type does. - -The `assign_where` and `ignore_where` parameter values are meant to be provided as strings. Since Icinga 2 requires that string literals be double-quoted, the whole string in your Puppet site manifests will have to be single-quoted (leaving the double quotes intact inside): - -
-assign_where => '"linux_servers" in host.groups',
-
- -If you would like to use Puppet or Facter variables in an `assign_where` or `ignore_where` parameter's value, you'll first need to double-quote the whole value for [Puppet's variable interpolation](http://docs.puppetlabs.com/puppet/latest/reference/lang_datatypes.html#double-quoted-strings) 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}"",
-
+$ VERSION=2.0.0 +$ tar ztf puppet-icinga2-$VERSION.tar.gz | less