Skip to content
Commits on Source (4)
Expand all Show whitespace changes
Inline Side-by-side
.mailmap
View file @ 7bc6030f
......@@ -36,3 +36,4 @@ Michael Insel <mcktr55@gmail.com> <michael@insel.email>
Marianne Spiller <github@spiller.me>
Robin O'Brien <robin@labs.epiuse.com> <robinjohnobrien@gmail.com>
<noah.hilverling@icinga.com> <noah@hilverling.com>
<pe-git@hindenburgring.com> <pe-icinga2@hindenburgring.com>
AUTHORS
View file @ 7bc6030f
......@@ -50,6 +50,7 @@ Dolf Schimmel <dolf@transip.nl>
Edgar Fuß <ef@math.uni-bonn.de>
Eduard Güldner <eduard.gueldner@gmail.com>
Edvin Seferovic <edvin@seferovic.net>
Elias Ohm <eohm@novomind.com>
Eric Lippmann <eric.lippmann@icinga.com>
Evgeni Golov <evgeni@golov.de>
Ewoud Kohl van Wijngaarden <ewoud@kohlvanwijngaarden.nl>
......@@ -106,6 +107,7 @@ Leon Stringer <leon@priorsvle.com>
Louis Sautier <sautier.louis@gmail.com>
Luca Lesinigo <luca@lm-net.it>
Lucas Fairchild-Madar <lucas.madar@gmail.com>
Luiz Amaral <luiz.amaral@innogames.com>
Magnus Bäck <magnus@noun.se>
Malte Rabenseifner <mail@malte-rabenseifner.de>
Manuel Reiter <reiter@csc.uni-frankfurt.de>
......@@ -147,7 +149,6 @@ Paul Richards <paul@minimoo.org>
Pawel Szafer <pszafer@gmail.com>
Per von Zweigbergk <pvz@itassistans.se>
Peter Eckel <pe-git@hindenburgring.com>
Peter Eckel <pe-icinga2@hindenburgring.com>
Petr Ruzicka <petr.ruzicka@gmail.com>
Phil Hutchinson <phil@volumedia.co.uk>
Philipp Dallig <philipp.dallig@gmail.com>
......@@ -212,6 +213,7 @@ gitmopp <mopp@gmx.net>
jre3brg <jorge.rebelo@pt.bosch.com>
krishna <gskrishna44@gmail.com>
lihan <tclh123@gmail.com>
marxin <mliska@suse.cz>
mocruz <mocruz@theworkshop.com>
noobahoi <20069422+noobahoi@users.noreply.github.com>
pv2b <pvz@pvz.pp.se>
......
CHANGELOG.md
View file @ 7bc6030f
# Icinga 2.x CHANGELOG
## 2.10.5 (2019-05-23)
[Issues and PRs](https://github.com/Icinga/icinga2/milestone/81?closed=1)
### Bugfixes
* Core
* Fix crashes with logrotate signals #6737 (thanks Elias Ohm)
* API
* Fix crashes and problems with permission filters from recent Namespace introduction #6785 (thanks Elias Ohm) #6874 (backported from 2.11)
* Reduce log spam with locked connections (real fix is the network stack rewrite in 2.11) #6877
* Cluster
* Fix problems with replay log rotation and storage #6932 (thanks Peter Eckel)
* IDO DB
* Fix that reload shutdown deactivates hosts and hostgroups (introduced in 2.9) #7157
* Documentation
* Improve the [REST API](https://icinga.com/docs/icinga2/latest/doc/12-icinga2-api/) chapter: Unix timestamp handling, filters, unify POST requests with filters in the body
* Better layout for the [features](https://icinga.com/docs/icinga2/latest/doc/14-features/) chapter, specifically metrics and events
* Split [object types](https://icinga.com/docs/icinga2/latest/doc/09-object-types/) into monitoring, runtime, features
* Add technical concepts for [cluster messages](https://icinga.com/docs/icinga2/latest/doc/19-technical-concepts/#json-rpc-message-api)
## 2.10.4 (2019-03-19)
### Notes
......
VERSION
View file @ 7bc6030f
Version: 2.10.4
Version: 2.10.5
Revision: 1
debian/changelog
View file @ 7bc6030f
icinga2 (2.10.5-1~exp1) experimental; urgency=medium
* Team upload.
* New upstream release.
-- Bas Couwenberg <sebastic@debian.org> Fri, 24 May 2019 05:53:45 +0200
icinga2 (2.10.4-1~exp1) experimental; urgency=medium
* Team upload.
......
doc/02-getting-started.md
View file @ 7bc6030f
......@@ -37,6 +37,11 @@ Community repositories:
Packages for distributions other than the ones listed above may also be
available. Please contact your distribution packagers.
> **Note**
>
> Windows is only supported for agent installations. Please refer
> to the [distributed monitoring chapter](06-distributed-monitoring.md#distributed-monitoring-setup-client-windows).
### Package Repositories <a id="package-repositories"></a>
You need to add the Icinga repository to your package management configuration.
......@@ -47,7 +52,8 @@ The following commands must be executed with `root` permissions unless noted oth
Debian:
```
apt-get -y install apt-transport-https
apt-get update
apt-get -y install apt-transport-https wget gnupg
wget -O - https://packages.icinga.com/icinga.key | apt-key add -
......@@ -63,7 +69,8 @@ apt-get update
Ubuntu:
```
apt-get -y install apt-transport-https
apt-get update
apt-get -y install apt-transport-https wget gnupg
wget -O - https://packages.icinga.com/icinga.key | apt-key add -
......@@ -79,7 +86,8 @@ apt-get update
Raspbian:
```
apt-get -y install apt-transport-https
apt-get update
apt-get -y install apt-transport-https wget gnupg
wget -O - https://packages.icinga.com/icinga.key | apt-key add -
......@@ -92,6 +100,18 @@ DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
apt-get update
```
##### Debian Backports Repository <a id="package-repositories-debian-backports"></a>
Debian Stretch:
```
DIST=$(awk -F"[)(]+" '/VERSION=/ {print $2}' /etc/os-release); \
echo "deb https://deb.debian.org/debian ${DIST}-backports main" > \
/etc/apt/sources.list.d/${DIST}-backports.list
apt-get update
```
#### RHEL/CentOS/Fedora Repositories <a id="package-repositories-rhel-centos-fedora"></a>
RHEL/CentOS 7:
......@@ -100,7 +120,7 @@ RHEL/CentOS 7:
yum install https://packages.icinga.com/epel/icinga-rpm-release-7-latest.noarch.rpm
```
RHEL/CentOS 6:
RHEL/CentOS 6 x64:
```
yum install https://packages.icinga.com/epel/icinga-rpm-release-6-latest.noarch.rpm
......@@ -112,7 +132,7 @@ Fedora 29:
dnf install https://packages.icinga.com/fedora/icinga-rpm-release-29-latest.noarch.rpm
```
#### RHEL/CentOS EPEL Repository <a id="package-repositories-rhel-epel"></a>
##### RHEL/CentOS EPEL Repository <a id="package-repositories-rhel-epel"></a>
The packages for RHEL/CentOS depend on other packages which are distributed
as part of the [EPEL repository](https://fedoraproject.org/wiki/EPEL).
......@@ -143,15 +163,6 @@ zypper ar https://packages.icinga.com/SUSE/ICINGA-release.repo
zypper ref
```
SLES 11:
```
rpm --import https://packages.icinga.com/icinga.key
zypper ar https://packages.icinga.com/SUSE/ICINGA-release-11.repo
zypper ref
```
openSUSE:
```
......@@ -161,16 +172,6 @@ zypper ar https://packages.icinga.com/openSUSE/ICINGA-release.repo
zypper ref
```
#### SLES Security Repository <a id="package-repositories-sles-security"></a>
The packages for SLES 11 depend on the `openssl1` package which is distributed
as part of the [SLES 11 Security Module](https://www.suse.com/communities/conversations/introducing-the-suse-linux-enterprise-11-security-module/).
#### SLES 12 SDK <a id="package-sles-sdk"></a>
Icinga 2 requires the `libboost_chrono1_54_0` package from the `SLES 12 SDK` repository. Refer to the SUSE Enterprise
Linux documentation for further information.
#### Alpine Linux Repositories <a id="package-repositories-alpine"></a>
Alpine Linux:
......@@ -329,7 +330,7 @@ yum install nagios-plugins-all
```
The packages for RHEL/CentOS depend on other packages which are distributed
as part of the [EPEL repository](#package-repositories-rhel-epel).
as part of the [EPEL repository](02-getting-started.md#package-repositories-rhel-epel).
Fedora:
......@@ -928,7 +929,7 @@ SUSE:
```
zypper install apache2
chkconfig on
chkconfig apache2 on
service apache2 start
```
......
doc/03-monitoring-basics.md
View file @ 7bc6030f
......@@ -2424,14 +2424,19 @@ states = [ OK, Critical, Unknown ]
> If the parent service object changes into the `Warning` state, this
> dependency will fail and render all child objects (hosts or services) unreachable.
You can determine the child's reachability by querying the `is_reachable` attribute
in for example [DB IDO](24-appendix.md#schema-db-ido-extensions).
You can determine the child's reachability by querying the `last_reachable` attribute
via the [REST API](12-icinga2-api.md#icinga2-api).
> **Note**
>
> Reachability calculation depends on fresh and processed check results. If dependencies
> disable checks for child objects, this won't work reliably.
### Implicit Dependencies for Services on Host <a id="dependencies-implicit-host-service"></a>
Icinga 2 automatically adds an implicit dependency for services on their host. That way
service notifications are suppressed when a host is `DOWN` or `UNREACHABLE`. This dependency
does not overwrite other dependencies and implicitely sets `disable_notifications = true` and
does not overwrite other dependencies and implicitly sets `disable_notifications = true` and
`states = [ Up ]` for all service objects.
Service checks are still executed. If you want to prevent them from happening, you can
......
doc/04-configuring-icinga-2.md
View file @ 7bc6030f
......@@ -77,12 +77,14 @@ If you prefer to organize your own local object tree, you can also remove
Create a new configuration directory, e.g. `objects.d` and include it
in your icinga2.conf file.
```
[root@icinga2-master1.localdomain /]# mkdir -p /etc/icinga2/objects.d
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/icinga2.conf
/* Local object configuration on our master instance. */
include_recursive "objects.d"
```
This approach is used by the [Icinga 2 Puppet module](https://github.com/Icinga/puppet-icinga2).
......@@ -97,6 +99,7 @@ An example configuration file is installed for you in `/etc/icinga2/icinga2.conf
Here's a brief description of the example configuration:
```
/**
* Icinga 2 configuration file
* -- this is where you define settings for the Icinga application including
......@@ -105,6 +108,7 @@ Here's a brief description of the example configuration:
* For an overview of all available configuration options please refer
* to the documentation that is distributed as part of Icinga 2.
*/
```
Icinga 2 supports [C/C++-style comments](17-language-reference.md#comments).
......@@ -115,15 +119,18 @@ Icinga 2 supports [C/C++-style comments](17-language-reference.md#comments).
The `include` directive can be used to include other files.
```
/**
* The zones.conf defines zones for a cluster setup.
* Not required for single instance setups.
*/
include "zones.conf"
```
The [Icinga Template Library](10-icinga-template-library.md#icinga-template-library) provides a set of common templates
and [CheckCommand](03-monitoring-basics.md#check-commands) definitions.
```
/**
* The Icinga Template Library (ITL) provides a number of useful templates
* and command definitions.
......@@ -154,17 +161,20 @@ and [CheckCommand](03-monitoring-basics.md#check-commands) definitions.
* the features-enabled directory.
*/
include "features-enabled/*.conf"
```
This `include` directive takes care of including the configuration files for all
the features which have been enabled with `icinga2 feature enable`. See
[Enabling/Disabling Features](11-cli-commands.md#enable-features) for more details.
```
/**
* Although in theory you could define all your objects in this file
* the preferred way is to create separate directories and files in the conf.d
* directory. Each of these files must have the file extension ".conf".
*/
include_recursive "conf.d"
```
You can put your own configuration files in the [conf.d](04-configuring-icinga-2.md#conf-d) directory. This
directive makes sure that all of your own configuration files are included.
......@@ -184,6 +194,7 @@ cluster setup.
Example:
```
/* The directory which contains the plugins from the Monitoring Plugins project. */
const PluginDir = "/usr/lib64/nagios/plugins"
......@@ -202,6 +213,7 @@ Example:
/* Secret key for remote node tickets */
const TicketSalt = ""
```
The `ZoneName` and `TicketSalt` constants are required for remote client
and distributed setups only.
......@@ -286,6 +298,7 @@ rules in [services.conf](04-configuring-icinga-2.md#services-conf) will automati
generate a new service checking the `/icingaweb2` URI using the `http`
check.
```
/*
* Host definitions with object attributes
* used for apply rules for Service, Notification,
......@@ -337,6 +350,7 @@ check.
groups = [ "icingaadmins" ]
}
}
```
This is only the host object definition. Now we'll need to make sure that this
host and your additional hosts are getting [services](04-configuring-icinga-2.md#services-conf) applied.
......@@ -376,6 +390,7 @@ which we enabled earlier by including the `itl` and `plugins` configuration file
Example `load` service apply rule:
```
apply Service "load" {
import "generic-service"
......@@ -386,6 +401,7 @@ Example `load` service apply rule:
assign where host.name == NodeName
}
```
The `apply` keyword can be used to create new objects which are associated with
another group of objects. You can `import` existing templates, define (custom)
......@@ -403,6 +419,7 @@ may be used in `assign where` conditions.
Multiple `assign where` condition can be combined with `AND` using the `&&` operator
as shown in the `ssh` example:
```
apply Service "ssh" {
import "generic-service"
......@@ -410,6 +427,7 @@ as shown in the `ssh` example:
assign where host.address && host.vars.os == "Linux"
}
```
In this example, the service `ssh` is applied to all hosts having the `address`
attribute defined `AND` having the custom attribute `os` set to the string
......@@ -429,6 +447,7 @@ The idea is simple: Your host in [hosts.conf](04-configuring-icinga-2.md#hosts-c
Remember the example from [hosts.conf](04-configuring-icinga-2.md#hosts-conf):
```
...
/* Define disks and attributes for service apply rules in `services.conf`. */
vars.disks["disk"] = {
......@@ -438,7 +457,7 @@ Remember the example from [hosts.conf](04-configuring-icinga-2.md#hosts-conf):
disk_partition = "/"
}
...
```
This dictionary contains multiple service names we want to monitor. `disk`
should just check all available disks, while `disk /` will pass an additional
......@@ -466,6 +485,7 @@ generated service
Configuration example:
```
apply Service for (disk => config in host.vars.disks) {
import "generic-service"
......@@ -473,6 +493,7 @@ Configuration example:
vars += config
}
```
A similar example is used for the `http` services. That way you can make your
host the information provider for all apply rules. Define them once, and only
......@@ -494,6 +515,7 @@ Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is u
[hosts.conf](04-configuring-icinga-2.md#hosts-conf) for defining a custom host attribute later used in
[notifications.conf](04-configuring-icinga-2.md#notifications-conf) for notification apply rules.
```
object User "icingaadmin" {
import "generic-user"
......@@ -506,7 +528,7 @@ Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is u
object UserGroup "icingaadmins" {
display_name = "Icinga 2 Admin Group"
}
```
#### notifications.conf <a id="notifications-conf"></a>
......@@ -527,6 +549,7 @@ By setting the `user_groups` to the value provided by the
respective [host.vars.notification.mail](04-configuring-icinga-2.md#hosts-conf) attribute we'll
implicitely use the `icingaadmins` UserGroup defined in [users.conf](04-configuring-icinga-2.md#users-conf).
```
apply Notification "mail-icingaadmin" to Host {
import "mail-host-notification"
......@@ -544,6 +567,7 @@ implicitely use the `icingaadmins` UserGroup defined in [users.conf](04-configur
assign where host.vars.notification.mail
}
```
More details on defining notifications and their additional attributes such as
filters can be read in [this chapter](03-monitoring-basics.md#alert-notifications).
......@@ -565,6 +589,7 @@ a member of the host group `linux-servers`.
This is done by using the [group assign](17-language-reference.md#group-assign) expressions similar
to previously seen [apply rules](03-monitoring-basics.md#using-apply).
```
object HostGroup "linux-servers" {
display_name = "Linux Servers"
......@@ -576,11 +601,13 @@ to previously seen [apply rules](03-monitoring-basics.md#using-apply).
assign where host.vars.os == "Windows"
}
```
Service groups can be grouped together by similar pattern matches.
The [match function](18-library-reference.md#global-functions-match) expects a wildcard match string
and the attribute string to match with.
```
object ServiceGroup "ping" {
display_name = "Ping Checks"
......@@ -598,13 +625,14 @@ and the attribute string to match with.
assign where match("disk*", service.check_command)
}
```
#### templates.conf <a id="templates-conf"></a>
Most of the example configuration objects use generic global templates by
default:
```
template Host "generic-host" {
max_check_attempts = 5
check_interval = 1m
......@@ -618,11 +646,12 @@ default:
check_interval = 1m
retry_interval = 30s
}
```
The `hostalive` check command is part of the
[Plugin Check Commands](10-icinga-template-library.md#icinga-template-library).
```
template Notification "mail-host-notification" {
command = "mail-host-notification"
......@@ -644,6 +673,7 @@ The `hostalive` check command is part of the
period = "24x7"
}
```
More details on `Notification` object attributes can be found [here](09-object-types.md#objecttype-notification).
......@@ -658,6 +688,7 @@ for the time ranges required for recurring downtime slots.
Learn more about downtimes in [this chapter](08-advanced-topics.md#downtimes).
```
apply ScheduledDowntime "backup-downtime" to Service {
author = "icingaadmin"
comment = "Scheduled downtime for backup"
......@@ -674,7 +705,7 @@ Learn more about downtimes in [this chapter](08-advanced-topics.md#downtimes).
assign where service.vars.backup_downtime != ""
}
```
#### timeperiods.conf <a id="timeperiods-conf"></a>
......
doc/05-service-monitoring.md
View file @ 7bc6030f
......@@ -15,6 +15,7 @@ The recommended way of setting up these plugins is to copy them to a common dire
and create a new global constant, e.g. `CustomPluginDir` in your [constants.conf](04-configuring-icinga-2.md#constants-conf)
configuration file:
```
# cp check_snmp_int.pl /opt/monitoring/plugins
# chmod +x /opt/monitoring/plugins/check_snmp_int.pl
......@@ -27,12 +28,15 @@ configuration file:
const PluginDir = "/usr/lib/nagios/plugins"
const CustomPluginDir = "/opt/monitoring/plugins"
```
Prior to using the check plugin with Icinga 2 you should ensure that it is working properly
by trying to run it on the console using whichever user Icinga 2 is running as:
```
# su - icinga -s /bin/bash
$ /opt/monitoring/plugins/check_snmp_int.pl --help
```
Additional libraries may be required for some plugins. Please consult the plugin
documentation and/or the included README file for installation instructions.
......@@ -64,6 +68,7 @@ set them on host/service level and you'll always know which command they control
This is an example for a custom `my-snmp-int` check command:
```
object CheckCommand "my-snmp-int" {
command = [ CustomPluginDir + "/check_snmp_int.pl" ]
......@@ -87,7 +92,7 @@ This is an example for a custom `my-snmp-int` check command:
vars.snmp_warn = "300,400"
vars.snmp_crit = "0,600"
}
```
For further information on your monitoring configuration read the
[Monitoring Basics](03-monitoring-basics.md#monitoring-basics) chapter.
......@@ -127,6 +132,7 @@ Common best practices when creating a new plugin are for example:
Example skeleton:
```
# 1. include optional libraries
# 2. global variables
# 3. helper functions and/or classes
......@@ -149,6 +155,7 @@ Example skeleton:
else
print "OK - ... | 'time'=0.2 'myperfdatavalue'=1.0
endif
```
There are various plugin libraries available which will help
with plugin execution and output formatting too, for example
......
doc/06-distributed-monitoring.md
View file @ 7bc6030f
This diff is collapsed.
doc/07-agent-based-monitoring.md
View file @ 7bc6030f
......@@ -15,6 +15,7 @@ The following example uses the [SNMP ITL](10-icinga-template-library.md#plugin-c
overrides the `snmp_oid` custom attribute. A service is created for all hosts which
have the `snmp-community` custom attribute.
```
apply Service "uptime" {
import "generic-service"
......@@ -24,6 +25,7 @@ have the `snmp-community` custom attribute.
assign where host.vars.snmp_community != ""
}
```
Additional SNMP plugins are available using the [Manubulon SNMP Plugins](10-icinga-template-library.md#snmp-manubulon-plugin-check-commands).
......@@ -37,6 +39,7 @@ Calling a plugin using the SSH protocol to execute a plugin on the remote server
its return code and output. The `by_ssh` command object is part of the built-in templates and
requires the `check_by_ssh` check plugin which is available in the [Monitoring Plugins package](02-getting-started.md#setting-up-check-plugins).
```
object CheckCommand "by_ssh_swap" {
import "by_ssh"
......@@ -54,6 +57,7 @@ requires the `check_by_ssh` check plugin which is available in the [Monitoring P
vars.by_ssh_logname = "icinga"
}
```
## NSClient++ <a id="agent-based-checks-nsclient"></a>
......@@ -67,6 +71,7 @@ Icinga 2 provides the [nscp check command](10-icinga-template-library.md#plugin-
Example:
```
object Service "disk" {
import "generic-service"
......@@ -79,6 +84,7 @@ Example:
vars.nscp_warn = 70
vars.nscp_crit = 80
}
```
For details on the `NSClient++` configuration please refer to the [official documentation](https://docs.nsclient.org/).
......@@ -116,6 +122,7 @@ Icinga 2 provides the [nrpe check command](10-icinga-template-library.md#plugin-
Example:
```
object Service "users" {
import "generic-service"
......@@ -124,10 +131,13 @@ Example:
check_command = "nrpe"
vars.nrpe_command = "check_users"
}
```
nrpe.cfg:
```
command[check_users]=/usr/local/icinga/libexec/check_users -w 5 -c 10
```
If you are planning to pass arguments to NRPE using the `-a`
command line parameter, make sure that your NRPE daemon has them
......@@ -144,6 +154,7 @@ attribute which expects either a single value or an array of values.
Example:
```
object Service "nrpe-disk-/" {
import "generic-service"
......@@ -153,10 +164,13 @@ Example:
vars.nrpe_command = "check_disk"
vars.nrpe_arguments = [ "20%", "10%", "/" ]
}
```
Icinga 2 will execute the nrpe plugin like this:
```
/usr/lib/nagios/plugins/check_nrpe -H <remote-nrpe-host> -c 'check_disk' -a '20%' '10%' '/'
```
NRPE expects all additional arguments in an ordered fashion
and interprets the first value as `$ARG1$` macro, the second
......@@ -164,12 +178,16 @@ value as `$ARG2$`, and so on.
nrpe.cfg:
```
command[check_disk]=/usr/local/icinga/libexec/check_disk -w $ARG1$ -c $ARG2$ -p $ARG3$
```
Using the above example with `nrpe_arguments` the command
executed by the NRPE daemon looks similar to that:
```
/usr/local/icinga/libexec/check_disk -w 20% -c 10% -p /
```
You can pass arguments in a similar manner to [NSClient++](07-agent-based-monitoring.md#agent-based-checks-nsclient)
when using its NRPE supported check method.
......@@ -193,6 +211,7 @@ state or from a missed reset event.
Add a directive in `snmptt.conf`
```
EVENT coldStart .1.3.6.1.6.3.1.1.5.1 "Status Events" Normal
FORMAT Device reinitialized (coldStart)
EXEC echo "[$@] PROCESS_SERVICE_CHECK_RESULT;$A;Coldstart;2;The snmp agent has reinitialized." >> /var/run/icinga2/cmd/icinga2.cmd
......@@ -201,6 +220,7 @@ Add a directive in `snmptt.conf`
in an agent role, is reinitializing itself and that its
configuration may have been altered.
EDESC
```
1. Define the `EVENT` as per your need.
2. Construct the `EXEC` statement with the service name matching your template
......@@ -210,6 +230,7 @@ match your Icinga convention.
Add an `EventCommand` configuration object for the passive service auto reset event.
```
object EventCommand "coldstart-reset-event" {
command = [ ConfigDir + "/conf.d/custom/scripts/coldstart_reset_event.sh" ]
......@@ -219,11 +240,13 @@ Add an `EventCommand` configuration object for the passive service auto reset ev
"-s" = "$service.name$"
}
}
```
Create the `coldstart_reset_event.sh` shell script to pass the expanded variable
data in. The `$service.state_id$` is important in order to prevent an endless loop
of event firing after the service has been reset.
```
#!/bin/bash
SERVICE_STATE_ID=""
......@@ -286,9 +309,11 @@ of event firing after the service has been reset.
if [ "$SERVICE_STATE_ID" -gt 0 ]; then
echo "[`date +%s`] PROCESS_SERVICE_CHECK_RESULT;$HOST_NAME;$SERVICE_NAME;0;Auto-reset (`date +"%m-%d-%Y %T"`)." >> /var/run/icinga2/cmd/icinga2.cmd
fi
```
Finally create the `Service` and assign it:
```
apply Service "Coldstart" {
import "generic-service-custom"
......@@ -309,6 +334,7 @@ Finally create the `Service` and assign it:
assign where (host.vars.os == "Linux" || host.vars.os == "Windows")
}
```
### Complex SNMP Traps <a id="complex-traps"></a>
......@@ -321,6 +347,7 @@ As long as the most recent passive update has occurred, the active check is bypa
Add a directive in `snmptt.conf`
```
EVENT enterpriseSpecific <YOUR OID> "Status Events" Normal
FORMAT Enterprise specific trap
EXEC echo "[$@] PROCESS_SERVICE_CHECK_RESULT;$A;$1;$2;$3" >> /var/run/icinga2/cmd/icinga2.cmd
......@@ -328,6 +355,7 @@ Add a directive in `snmptt.conf`
An enterprise specific trap.
The varbinds in order denote the Icinga service name, state and text.
EDESC
```
1. Define the `EVENT` as per your need using your actual oid.
2. The service name, state and text are extracted from the first three varbinds.
......@@ -337,6 +365,7 @@ Create a `Service` for the specific use case associated to the host. If the host
matches and the first varbind value is `Backup`, SNMPTT will submit the corresponding
passive update with the state and text from the second and third varbind:
```
object Service "Backup" {
import "generic-service-custom"
......@@ -356,3 +385,4 @@ passive update with the state and text from the second and third varbind:
vars.dummy_state = 2
vars.dummy_text = "No passive check result received."
}
```
\ No newline at end of file
doc/08-advanced-topics.md
View file @ 7bc6030f
......@@ -387,12 +387,16 @@ In Icinga 2 active check freshness is enabled by default. It is determined by th
The threshold is calculated based on the last check execution time for actively executed checks:
```
(last check execution time + check interval) > current time
```
If this host/service receives check results from an [external source](08-advanced-topics.md#external-check-results),
the threshold is based on the last time a check result was received:
```
(last check result time + check interval) > current time
```
> **Tip**
>
......@@ -579,6 +583,7 @@ In addition to that you can optionally define the `ssl` attribute which enables
Host definition:
```
object Host "webserver01" {
import "generic-host"
address = "192.168.56.200"
......@@ -602,9 +607,11 @@ Host definition:
}
}
}
```
Service apply for definitions:
```
apply Service "webserver_ping" for (instance => config in host.vars.webserver.instance) {
display_name = "webserver_" + instance
check_command = "ping4"
......@@ -638,6 +645,7 @@ Service apply for definitions:
assign where config.url != ""
}
```
The variables defined in the host dictionary are not using the typical custom attribute
prefix recommended for CheckCommand parameters. Instead they are re-used for multiple
......@@ -756,6 +764,7 @@ slightly unexpected way. The following example shows how to assign values
depending on group membership. All hosts in the `slow-lan` host group use 300
as value for `ping_wrta`, all other hosts use 100.
```
globals.group_specific_value = function(group, group_value, non_group_value) {
return function() use (group, group_value, non_group_value) {
if (group in host.groups) {
......@@ -775,6 +784,7 @@ as value for `ping_wrta`, all other hosts use 100.
assign where true
}
```
#### Use Functions in Assign Where Expressions <a id="use-functions-assign-where"></a>
......@@ -790,6 +800,7 @@ The following example requires the host `myprinter` being added
to the host group `printers-lexmark` but only if the host uses
a template matching the name `lexmark*`.
```
template Host "lexmark-printer-host" {
vars.printer_type = "Lexmark"
}
......@@ -819,7 +830,7 @@ a template matching the name `lexmark*`.
/* call the global function and pass the arguments */
assign where check_host_templates(host, "lexmark*")
}
```
Take a different more complex example: All hosts with the
custom attribute `vars_app` as nested dictionary should be
......@@ -828,12 +839,15 @@ added to the host group `ABAP-app-server`. But only if the
It could read as wildcard match for nested dictionaries:
```
where host.vars.vars_app["*"].app_type == "ABAP"
```
The solution for this problem is to register a global
function which checks the `app_type` for all hosts
with the `vars_app` dictionary.
```
object Host "appserver01" {
check_command = "dummy"
vars.vars_app["ABC"] = { app_type = "ABAP" }
......@@ -864,7 +878,7 @@ with the `vars_app` dictionary.
object HostGroup "ABAP-app-server" {
assign where check_app_type(host, "ABAP")
}
```
#### Use Functions in Command Arguments set_if <a id="use-functions-command-arguments-setif"></a>
......@@ -879,6 +893,7 @@ multiple conditions and attributes.
The following example was found on the community support channels. The user had defined a host
dictionary named `compellent` with the key `disks`. This was then used inside service apply for rules.
```
object Host "dict-host" {
check_command = "check_compellent"
vars.compellent["disks"] = {
......@@ -886,6 +901,7 @@ dictionary named `compellent` with the key `disks`. This was then used inside se
checks = ["disks"]
}
}
```
The more significant problem was to only add the command parameter `--disk` to the plugin call
when the dictionary `compellent` contains the key `disks`, and omit it if not found.
......@@ -894,6 +910,7 @@ By defining `set_if` as [abbreviated lambda function](17-language-reference.md#n
and evaluating the host custom attribute `compellent` containing the `disks` this problem was
solved like this:
```
object CheckCommand "check_compellent" {
command = [ "/usr/bin/check_compellent" ]
arguments = {
......@@ -908,6 +925,7 @@ solved like this:
}
}
}
```
This implementation uses the dictionary type method [contains](18-library-reference.md#dictionary-contains)
and will fail if `host.vars.compellent` is not of the type `Dictionary`.
......@@ -915,6 +933,7 @@ Therefore you can extend the checks using the [typeof](17-language-reference.md#
You can test the types using the `icinga2 console`:
```
# icinga2 console
Icinga (version: v2.3.0-193-g3eb55ad)
<1> => srv_vars.compellent["check_a"] = { file="outfile_a.json", checks = [ "disks", "fans" ] }
......@@ -924,9 +943,11 @@ You can test the types using the `icinga2 console`:
<3> => typeof(srv_vars.compellent)
type 'Dictionary'
<4> =>
```
The more programmatic approach for `set_if` could look like this:
```
"--disks" = {
set_if = {{
var srv_vars = service.vars
......@@ -943,7 +964,7 @@ The more programmatic approach for `set_if` could look like this:
}
}}
}
```
#### Use Functions as Command Attribute <a id="use-functions-command-attribute"></a>
......@@ -955,6 +976,7 @@ The following example was taken from the community support channels. The require
specify a custom attribute inside the notification apply rule and decide which notification
script to call based on that.
```
object User "short-dummy" {
}
......@@ -969,6 +991,7 @@ script to call based on that.
vars.short = true
assign where host.vars.notification.mail
}
```
The solution is fairly simple: The `command` attribute is implemented as function returning
an array required by the caller Icinga 2.
......@@ -980,6 +1003,7 @@ returned.
You can omit the `log()` calls, they only help debugging.
```
object NotificationCommand "mail-host-notification-test" {
command = {{
log("command as function")
......@@ -998,7 +1022,7 @@ You can omit the `log()` calls, they only help debugging.
env = {
}
}
```
### Access Object Attributes at Runtime <a id="access-object-attributes-at-runtime"></a>
......
doc/09-object-types.md
View file @ 7bc6030f
This diff is collapsed.
doc/10-icinga-template-library.md
View file @ 7bc6030f
......@@ -25,7 +25,9 @@ You are advised to create your own CheckCommand definitions in
By default the generic templates are included in the [icinga2.conf](04-configuring-icinga-2.md#icinga2-conf) configuration file:
```
include <itl>
```
These templates are imported by the provided example configuration.
......
doc/11-cli-commands.md
View file @ 7bc6030f
......@@ -22,7 +22,7 @@ Supported commands:
* api setup (setup for API)
* ca list (lists all certificate signing requests)
* ca sign (signs an outstanding certificate request)
* console (Icinga console)
* console (Icinga debug console)
* daemon (starts Icinga 2)
* feature disable (disables specified feature)
* feature enable (enables specified feature)
......@@ -272,7 +272,7 @@ are required for executing config expressions and auto-completion.
> **Note**
>
> The debug console does not currently support SSL certificate verification.
> The debug console does not currently support TLS certificate verification.
>
> Runtime modifications are not validated and might cause the Icinga 2
> daemon to crash or behave in an unexpected way. Use these runtime changes
......
doc/12-icinga2-api.md
View file @ 7bc6030f
This diff is collapsed.
doc/13-addons.md
View file @ 7bc6030f
......@@ -19,7 +19,9 @@ You need to install Graphite first, then proceed with configuring it in Icinga 2
Use the [GraphiteWriter](14-features.md#graphite-carbon-cache-writer) feature
for sending real-time metrics from Icinga 2 to Graphite.
```
# icinga2 feature enable graphite
```
A popular alternative frontend for Graphite is for example [Grafana](https://grafana.org).
......@@ -36,7 +38,9 @@ It’s written in Go and has no external dependencies.
Use the [InfluxdbWriter](14-features.md#influxdb-writer) feature
for sending real-time metrics from Icinga 2 to InfluxDB.
```
# icinga2 feature enable influxdb
```
A popular frontend for InfluxDB is for example [Grafana](https://grafana.org).
......@@ -56,16 +60,20 @@ Use your distribution's package manager to install the `pnp4nagios` package.
If you're planning to use it, configure it to use the
[bulk mode with npcd and npcdmod](https://docs.pnp4nagios.org/pnp-0.6/modes#bulk_mode_with_npcd_and_npcdmod)
in combination with Icinga 2's [PerfdataWriter](14-features.md#performance-data). NPCD collects the performance
in combination with Icinga 2's [PerfdataWriter](14-features.md#writing-performance-data-files). NPCD collects the performance
data files which Icinga 2 generates.
Enable performance data writer in icinga 2
```
# icinga2 feature enable perfdata
```
Configure npcd to use the performance data created by Icinga 2:
```
vim /etc/pnp4nagios/npcd.cfg
```
Set `perfdata_spool_dir = /var/spool/icinga2/perfdata` and restart the `npcd` daemon.
......@@ -120,9 +128,11 @@ based on your monitoring configuration and status data using [NagVis](https://ww
The configuration in nagvis.ini.php should look like this for Livestatus for example:
```
[backend_live_1]
backendtype="mklivestatus"
socket="unix:/var/run/icinga2/cmd/livestatus"
```
If you are planning an integration into Icinga Web 2, look at [this module](https://github.com/Icinga/icingaweb2-module-nagvis).
......@@ -190,6 +200,7 @@ These tools are currently in development and require feedback and tests:
They work in a similar fashion for Icinga 2 and are used for 1.x web interfaces (Icinga Web 2 doesn't require
the action url attribute in its own module).
```
template Host "pnp-hst" {
action_url = "/pnp4nagios/graph?host=$HOSTNAME$"
}
......@@ -197,6 +208,7 @@ the action url attribute in its own module).
template Service "pnp-svc" {
action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$"
}
```
### PNP Custom Templates with Icinga 2 <a id="addons-graphing-pnp-custom-templates"></a>
......@@ -213,6 +225,7 @@ and use that inside the formatting templates as `SERVICECHECKCOMMAND` for instan
Example for services:
```
# vim /etc/icinga2/features-enabled/perfdata.conf
service_format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$icinga.timet$\tHOSTNAME::$host.name$\tSERVICEDESC::$service.name$\tSERVICEPERFDATA::$service.perfdata$\tSERVICECHECKCOMMAND::$service.check_command$$pnp_check_arg1$\tHOSTSTATE::$host.state$\tHOSTSTATETYPE::$host.state_type$\tSERVICESTATE::$service.state$\tSERVICESTATETYPE::$service.state_type$"
......@@ -231,6 +244,7 @@ Example for services:
vars.pnp_check_arg1 = "!$nrpe_command$"
}
```
If there are warnings about unresolved macros, make sure to specify a default value for `vars.pnp_check_arg1` inside the
......
doc/14-features.md
View file @ 7bc6030f
This diff is collapsed.
doc/15-troubleshooting.md
View file @ 7bc6030f
......@@ -547,15 +547,19 @@ settings of the Icinga 2 systemd service by creating
`/etc/systemd/system/icinga2.service.d/override.conf` with the following
content:
```
[Service]
Restart=always
RestartSec=1
StartLimitInterval=10
StartLimitBurst=3
```
Using the watchdog can also help with monitoring Icinga 2, to activate and use it add the following to the override:
```
WatchdogSec=30s
```
This way systemd will kill Icinga 2 if does not notify for over 30 seconds, a timout of less than 10 seconds is not
recommended. When the watchdog is activated, `Restart=` can be set to `watchdog` to restart Icinga 2 in the case of a
......@@ -857,8 +861,6 @@ Fetch the `ca.crt` file from the client node and compare it to your master's `ca
# diff -ur /var/lib/icinga2/certs/ca.crt test-client-ca.crt
```
On SLES11 you'll need to use the `openssl1` command instead of `openssl`.
<!--
### Certificate Signing <a id="troubleshooting-certificate-signing"></a>
-->
......
doc/16-upgrading-icinga-2.md
View file @ 7bc6030f
......@@ -9,6 +9,13 @@ follow the instructions for v2.7 too.
## Upgrading to v2.10 <a id="upgrading-to-2-10"></a>
### 2.10.5 Packages <a id="upgrading-to-2-10-5-packages"></a>
EOL distributions where no packages are available with 2.10.5:
* SLES 11
* Ubuntu 14 LTS
### Path Constant Changes <a id="upgrading-to-2-10-path-constant-changes"></a>
During package upgrades you may see a notice that the configuration
......