available. Please check http://packages.icinga.org/ to see if packages
are available for your favourite distribution.
-> **Note**
->
-> The packages for RHEL/CentOS 5 depend on other packages which are distributed
-> as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please
-> make sure to enable this repository.
+The packages for RHEL/CentOS 5 depend on other packages which are distributed
+as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please
+make sure to enable this repository.
You can install Icinga 2 by using your distribution's package manager
to install the `icinga2` package.
-> **Note**
->
-> On RHEL/CentOS and SLES you will need to use `chkconfig` to enable the
-> `icinga2` service. You can manually start Icinga 2 using `/etc/init.d/icinga2 start`.
+On RHEL/CentOS and SLES you will need to use `chkconfig` to enable the
+`icinga2` service. You can manually start Icinga 2 using `/etc/init.d/icinga2 start`.
Some parts of Icinga 2's functionality are available as separate packages:
# su - icinga -s /bin/bash
$ /opt/plugins/check_snmp_int.pl --help
-> **Note**
->
-> Additional libraries may be required for some plugins. Please consult the plugin
-> documentation and/or README for installation instructions.
+Additional libraries may be required for some plugins. Please consult the plugin
+documentation and/or README for installation instructions.
There is a separate module for each database back-end. At present support for
both MySQL and PostgreSQL is implemented.
-> **Note**
->
-> Icinga 2 uses the Icinga 1.x IDOUtils database schema starting with version
-> `1.11.0`. Icinga 2 may require additional features not yet released with
-> Icinga 1.x and therefore require manual upgrade steps during pre-final
-> milestone releases.
+Icinga 2 uses the Icinga 1.x IDOUtils database schema starting with version
+`1.11.0`. Icinga 2 may require additional features not yet released with
+Icinga 1.x and therefore require manual upgrade steps during pre-final
+milestone releases.
> **Tip**
>
# mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/mysql.sql
-> **Note**
->
-> The Icinga 2 RPM packages install the schema files into
-> `/usr/share/doc/icinga2-ido-mysql-*/schema` (`*` means package version).
-> The Icinga 2 dist tarball ships the schema files in `components/db_ido_mysql/schema/`.
->
-> On SuSE-based distributions the schema files are installed in
-> `/usr/share/doc/packages/icinga2-ido-mysql/schema`.
->
-> The Debian/Ubuntu packages put the schema files into
-> `/usr/share/icinga2-ido-mysql/schema`.
+The Icinga 2 RPM packages install the schema files into
+`/usr/share/doc/icinga2-ido-mysql-*/schema` (`*` means package version).
+
+On SuSE-based distributions the schema files are installed in
+`/usr/share/doc/packages/icinga2-ido-mysql/schema`.
+
+The Debian/Ubuntu packages put the schema files into
+`/usr/share/icinga2-ido-mysql/schema`.
#### <a id="upgrading-mysql-db"></a> Upgrading the MySQL database
# mysql -u root -p icinga < /usr/share/doc/icinga2-ido-mysql-*/schema/upgrade/mysql-upgrade-1.12.0.sql
-> **Note**
->
-> The Icinga 2 IDO module will check for the required database schema version
-> on startup and generate an error message if not satisfied.
+The Icinga 2 IDO module will check for the required database schema version on startup
+and generate an error message if not satisfied.
#### <a id="installing-ido-mysql"></a> Installing the IDO MySQL module
# export PGPASSWORD=icinga
# psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/pgsql.sql
-> **Note**
->
-> The Icinga 2 RPM packages install the schema files into
-> `/usr/share/doc/icinga2-ido-pgsql-*/schema` (`*` means package version).
-> The Icinga 2 dist tarball ships the schema files in `components/db_ido_pgsql/schema/`.
->
-> On SuSE-based distributions the schema files are installed in
-> `/usr/share/doc/packages/icinga2-ido-pgsql/schema`.
->
-> The Debian/Ubuntu packages put the schema files into
-> `/usr/share/icinga2-ido-pgsql/schema`.
+The Icinga 2 RPM packages install the schema files into
+`/usr/share/doc/icinga2-ido-pgsql-*/schema` (`*` means package version).
+On SuSE-based distributions the schema files are installed in
+`/usr/share/doc/packages/icinga2-ido-pgsql/schema`.
+
+The Debian/Ubuntu packages put the schema files into
+`/usr/share/icinga2-ido-pgsql/schema`.
#### <a id="upgrading-postgresql-db"></a> Upgrading the PostgreSQL database
# export PGPASSWORD=icinga
# psql -U icinga -d icinga < /usr/share/doc/icinga2-ido-pgsql-*/schema/upgrade/pgsql-upgrade-1.12.0.sql
-> **Note**
->
-> The Icinga 2 IDO module will check for the required database schema version
-> on startup and generate an error message if not satisfied.
-
+The Icinga 2 IDO module will check for the required database schema version on startup
+and generate an error message if not satisfied.
#### <a id="installing-ido-postgresql"></a> Installing the IDO PostgreSQL module
# usermod -a -G icingacmd www-data
-> **Note**
->
-> Debian packages use `nagios` as default user/group. Therefore change `icingacmd` to
-> `nagios`.
+The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to
+`nagios` if you're using Debian.
-> **Note**
->
-> Change "www-data" to the user you're using to run queries.
+Change "www-data" to the user you're using to run queries.
In order to use the historical tables provided by the livestatus feature (for example, the
`log` table) you need to have the `CompatLogger` feature enabled. By default these logs
Debian | icinga2-classicui
all others | icinga2-classicui-config icinga-gui
-> **Note**
->
-> Debian packages require additional dependencies satisfied by the [debmon](http://www.debmong.org)
-> repository.
+The Debian packages require additional packages which are provided by the
+[Debian Monitoring Project](http://www.debmon.org) repository.
-> **Note**
->
-> On all distributions other than Debian you may have to restart both your web
-> server as well as Icinga 2 after installing the Classic UI package.
+On all distributions other than Debian you may have to restart both your web
+server as well as Icinga 2 after installing the Classic UI package.
Verify that your Icinga 1.x Classic UI works by browsing to your Classic
UI installation URL:
Debian | [http://localhost/icinga2-classicui](http://localhost/icinga2-classicui) | asked during installation
all others | [http://localhost/icinga](http://localhost/icinga) | icingaadmin/icingaadmin
-> **Note**
->
-> Due to compatibility restrictions, not all features available in Icinga 1.x
-> Classic UI will be available with Icinga 2. The different handling of
-> [commands](#differences-1x-2-commands) and [custom attributes](#differences-1x-2-macros)
-> renders the command expander invalid for example.
-
### <a id="setting-up-icinga-web"></a> Setting up Icinga Web
Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which
Additionally you need to setup the `icinga_web` database.
-> **Note**
->
-> The Icinga Web RPM packages install the schema files into
-> `/usr/share/doc/icinga-web-*/schema` (`*` means package version).
-> The Icinga Web dist tarball ships the schema files in `etc/schema`.
->
-> On SuSE-based distributions the schema files are installed in
-> `/usr/share/doc/packages/icinga-web/schema`.
+The Icinga Web RPM packages install the schema files into
+`/usr/share/doc/icinga-web-*/schema` (`*` means package version).
+The Icinga Web dist tarball ships the schema files in `etc/schema`.
+On SuSE-based distributions the schema files are installed in
+`/usr/share/doc/packages/icinga-web/schema`.
Additionally you need to enable the `ExternalCommandListener` feature.
Please consult the INSTALL documentation shipped with `Icinga Web 2` for
further instructions.
-> **Note**
->
-> Icinga Web 2 is still under heavy development. Rather than installing it
-> yourself you should consider testing it using the available Vagrant
-> demo boxes.
+Icinga Web 2 is still under development. Rather than installing it
+yourself you should consider testing it using the available Vagrant
+demo VM.
### <a id="additional-visualization"></a> Additional visualization
checkconfig | The `checkconfig` action checks if the `/etc/icinga2/icinga2.conf` configuration file contains any errors.
status | The `status` action checks if Icinga 2 is running.
-> **Note**
->
-> By default the Icinga 2 daemon is running as `icinga` user and group
-> using the init script. Using Debian packages the user and group are set to `nagios`
-> for historical reasons.
+By default the Icinga 2 daemon is running as `icinga` user and group
+using the init script. Using Debian packages the user and group are set to `nagios`
+for historical reasons.
### <a id="cmdline"></a> Command-line Options
Module 'statusdata' was disabled.
Make sure to restart Icinga 2 for these changes to take effect.
-> **Note**
->
-> The `icinga2-enable-feature` and `icinga2-disable-feature` commands do not restart Icinga 2.
+The `icinga2-enable-feature` and `icinga2-disable-feature` commands do not
+restart Icinga 2. You will need to restart Icinga 2 using the init script
+after enabling or disabling features.
+
checks should be performed, notifications should be sent and
events should be handled.
-> **Note**
->
-> Define the global `PluginDir` constant (located in
-> `/etc/icinga2/constants.conf` by default) and use
-> it in all your command object definitions.
-> Put your plugins and scripts into the directory defined by the `PluginDir` constant
-> and make sure they are executable by the Icinga 2 user.
-
### <a id="command-environment-variables"></a> Environment Varialbes for Commands
Please check [Runtime Custom Attributes as Environment Variables](#runtime-custom-attribute-env-vars).
`CheckCommand` objects define the command line how a check is called.
-> **Note**
->
-> `CheckCommand` objects require the ITL template `plugin-check-command`
-> to support native plugin based check methods.
+`CheckCommand` objects require the ITL template `plugin-check-command`
+to support native plugin based check methods.
Unless you have done so already, download your check plugin and put it
into the `PluginDir` directory. The following example uses the
definable naming schema) and their default threshold values. You can
then use these custom attributes as runtime macros on the command line.
-> **Note**
->
-> The default custom attributes can be overridden by the custom attributes
-> defined in the service using the check command `disk`. The custom attributes
-> can also be inherited from a parent template using additive inheritance (`+=`).
+The default custom attributes can be overridden by the custom attributes
+defined in the service using the check command `disk`. The custom attributes
+can also be inherited from a parent template using additive inheritance (`+=`).
object CheckCommand "disk" {
import "plugin-check-command"
`NotificationCommand` objects define how notifications are delivered to external
interfaces (E-Mail, XMPP, IRC, Twitter, etc).
-> **Note**
->
-> `NotificationCommand` objects require the ITL template `plugin-notification-command`
-> to support native plugin-based notifications.
+`NotificationCommand` objects require the ITL template `plugin-notification-command`
+to support native plugin-based notifications.
Below is an example using runtime macros from Icinga 2 (such as `$SERVICEOUTPUT$` for
the current check output) sending an email to the user(s) associated with the
/usr/bin/printf "%b" $template | mail -s "$NOTIFICATIONTYPE - $HOSTDISPLAYNAME - $SERVICEDISPLAYNAME is $SERVICESTATE" $USEREMAIL
-> **Best Practice**
->
-> While it's possible to specify the entire notification command right
-> in the NotificationCommand object it is generally advisable to create a
-> shell script in the `/etc/icinga2/scripts` directory and have the
-> NotificationCommand object refer to that.
+While it's possible to specify the entire notification command right
+in the NotificationCommand object it is generally advisable to create a
+shell script in the `/etc/icinga2/scripts` directory and have the
+NotificationCommand object refer to that.
### <a id="event-commands"></a> Event Commands
restart via event command, or if an application is locked and requires
a restart upon detection.
-> **Note**
->
-> `EventCommand` objects require the ITL template `plugin-event-command`
-> to support native plugin based checks.
+`EventCommand` objects require the ITL template `plugin-event-command`
+to support native plugin based checks.
The example below is fictive and not necessarily meant for production use.
When the event command is triggered on a service state change, it will
> Custom attributes are identified by the 'vars' dictionary attribute as short name.
> Accessing the different attribute keys is possible using the '.' accessor.
-> **Note**
->
-> Custom attributes in command definitions or performance data templates are evaluated at
-> runtime when executing a command. These custom attributes cannot be used elsewhere
-> (e.g. in other configuration attributes).
+Custom attributes in command definitions or performance data templates are evaluated at
+runtime when executing a command. These custom attributes cannot be used elsewhere
+(e.g. in other configuration attributes).
Here is an example of a command definition which uses user-defined custom attributes:
vars.timeout = 0
}
-> **Note**
->
-> If you have previously used Icinga 1.x you may already be familiar with
-> user and argument macros (e.g., `USER1` or `ARG1`) and custom variables
-> (e.g., `_COMMUNITY public`). Unlike in Icinga 1.x macros may have arbitrary
-> names and arguments are no longer specified in the `check_command` setting.
-> Custom variables are available as custom attributes in the `vars` dictionary
-> without the `_` prefix.
-
Custom attribute names used at runtime must be enclosed in two `$` signs, e.g.
`$address$`. When using the `$` sign as single character, you need to escape
it with an additional dollar sign (`$$`).
The following macros are available in all executed commands:
-> **Note**
->
-> Global application runtime macros require the `icinga.` prefix.
-
Name | Description
-----------------------|--------------
icinga.timet | Current UNIX timestamp.
}
}
-> **Note**
->
-> If you don't set the `notification_state_filter` and `notification_type_filter`
-> configuration attributes for the `User` object, all states and types will be
-> notified.
-> Recovery notifications require the state filter `StateFilterOK`.
+If you don't set the `notification_state_filter` and `notification_type_filter`
+configuration attributes for the `User` object, all states and types will be
+notified.
You should choose which information you (and your notified users) are interested in
case of emergency, and also which information does not provide any value to you and
your environment.
-> **Note**
->
-> The chain of attribute inheritance including the (additive) vars dictionary for
-> notifications will allow granular custom attributes for every specific use case.
-
-
There are various custom attributes available at runtime execution of the
`NotificationCommand`. The example below may or may not fit your needs.
notification_period = "24x7"
}
-> **Note**
->
-> The `TimePeriod` `24x7` is shipped as example configuration with Icinga 2.
+The time period `24x7` is shipped as example configuration with Icinga 2.
Use the `apply` keyword to create `Notification` objects for your services:
assign where service.name == "mysql"
}
-> **Note**
->
-> Instead of assigning users to notifications, you can also add the `user_groups`
-> attribute with a list of user groups to the `Notification` object. Icinga 2 will
-> resolve all group members and send notifications to all of them.
+Instead of assigning users to notifications, you can also add the `user_groups`
+attribute with a list of user groups to the `Notification` object. Icinga 2 will
+resolve all group members and send notifications to all of them.
### <a id="notification-escalations"></a> Notification Escalations
Using the example from above, you can define additional users being escalated for sms
notifications between start and end time.
-> **Note**
->
-> `notification_state_filter` and `notification_type_filter` configuration attributes
-> are not set in this example.
-
object User "icinga-oncall-2nd-level" {
display_name = "Icinga 2nd Level"
enable_notifications = true
}
}
-Define an additional `NotificationCommand` for sms notifications.
+Define an additional `NotificationCommand` for SMS notifications.
> **Note**
>
-> The example is not complete as there are many different sms providers.
-> Please note that sending sms notifications will require an sms provider
+> The example is not complete as there are many different SMS providers.
+> Please note that sending SMS notifications will require an SMS provider
> or local hardware with a sim card active.
object NotificationCommand "sms-notification" {
The two new notification escalations are added onto the host `localhost`
and its service `ping4` using the `generic-notification` template.
-The user `icinga-oncall-2nd-level` will get notified by sms (`sms-notification`
+The user `icinga-oncall-2nd-level` will get notified by SMS (`sms-notification`
command) after `30m` until `1h`.
> **Note**
assign where service.name == "ping4"
}
-> **Note**
->
-> Instead of assigning users to notifications, you can also add the `user_groups`
-> attribute with a list of user groups to the `Notification` object. Icinga 2 will
-> resolve all group members and send notifications and notification escalations to
-> all of them.
+Instead of assigning users to notifications, you can also add the `user_groups`
+attribute with a list of user groups to the `Notification` object. Icinga 2 will
+resolve all group members and send notifications and notification escalations to
+all of them.
### <a id="first-notification-delay"></a> First Notification Delay
assign where service.name == "ping4"
}
-> **Note**
->
-> In Icinga 1.x the attribute is called `first_notification_delay`.
-
### <a id="notification-filters-state-type"></a> Notification Filters by State and Type
If there are no notification state and type filter attributes defined at the `Notification`
or `User` object Icinga 2 assumes that all states and types are being notified.
-> **Note**
->
-> In order to notify on problem states, you still need the type filter `NotificationFilterProblem`.
-
Available state and type filters for notifications are:
template Notification "generic-notification" {
NotificationFilterDowntimeRemoved)
}
-> **Note**
->
-> If you are familiar with Icinga 1.x `notification_options` please note that they have been split
-> into type and state, and allow more fine granular filtering for example on downtimes and flapping.
-> You can filter for acknowledgements and custom notifications too.
+If you are familiar with Icinga 1.x `notification_options` please note that they have been split
+into type and state, and allow more fine granular filtering for example on downtimes and flapping.
+You can filter for acknowledgements and custom notifications too.
Then add your hosts to this hostgroup
+ template Host "windows-server" {
+ groups += [ "windows" ]
+ }
+
object Host "mssql-srv1" {
- groups = [ "windows" ]
+ import "windows-server"
+
vars.mssql_port = 1433
}
object Host "mssql-srv2" {
- groups = [ "windows" ]
- vars.mssql_port = 1433
- }
-
-> **Best Practice**
->
-> Add the hostgroup membership into generic templates combined with
-> other attributes and let all windows hosts inherit from that template.
-> You can also define multiple group memberships.
+ import "windows-server"
- template Host "windows-mssql-template" {
- groups = [ "windows" ]
vars.mssql_port = 1433
}
-
- object Host "mssql-srv1" {
- import "windows-mssql-template"
- }
-
- object Host "mssql-srv2" {
- import "windows-mssql-template"
- }
This can be done for service and user groups the same way. Additionally
the user groups are associated as attributes in `Notification` objects.
Oct 17 15:01:25 icinga-server icinga2: Executing external command: [1382014885] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;1382014885
Oct 17 15:01:25 icinga-server icinga2: Rescheduling next check for service 'ping4'
-> **Note**
->
-> The command pipe file is owned by the group `icingacmd` with read/write
-> permissions. Add your webserver's user to the group `icingacmd` to
-> enable sending commands to Icinga 2 through your web interface.
+By default the command pipe file is owned by the group `icingacmd` with read/write
+permissions. Add your webserver's user to the group `icingacmd` to
+enable sending commands to Icinga 2 through your web interface:
# usermod -G -a icingacmd www-data
-> **Note**
->
-> Debian packages use `nagios` as default user/group. Therefore change `icingacmd` to
-> `nagios`.
+Debian packages use `nagios` as the default user and group name. Therefore change `icingacmd` to
+`nagios`.
### <a id="external-command-list"></a> External Command List
External collectors need to parse the rotated performance data files and then
remove the processed files.
-> **Note**
->
-> If you enable this feature by accident and no collector daemon is processing
-> these files, the filesystem's inodes may run out. Make sure to watch the
-> `localhost` service check `disks` and define your own inode warning
-> and critical thresholds.
-
-
### <a id="graphite-carbon-cache-writer"></a> Graphite Carbon Cache Writer
While there are some Graphite collector scripts and daemons like Graphios available for
>
> If you are not using any web interface or addon which uses these files
> you can safely disable this feature.
-
-> **Note**
->
-> Semicolons in the check result output are replaced with colons because
-> they are used as attribute separators.
[1382115731] EXTERNAL COMMAND: PROCESS_SERVICE_CHECK_RESULT;localhost;ping6;2;critical test|
[1382115731] SERVICE ALERT: localhost;ping6;CRITICAL;SOFT;2;critical test
-> **Note**
->
-> Semicolons in the check result output are replaced with colons because
-> they are used as attribute separators.
Icinga 2 calls the `check_nrpe` plugin binary in order to query the configured command on the
remote client.
-> **Note**
->
-> The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe`
-> can be embedded into the Icinga 2 `CheckCommand` configuration syntax.
+The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe`
+can be embedded into the Icinga 2 `CheckCommand` configuration syntax.
Example:
but using `NSClient++` will allow you to run local scripts similar to check plugins fetching
the required output and performance counters.
-> **Note**
->
-> The NSClient++ agent uses its own proprietary configuration format while `check_nt`
-> can be embedded into the Icinga 2 `CheckCommand` configuration syntax.
+The NSClient++ agent uses its own configuration format while `check_nt`
+can be embedded into the Icinga 2 `CheckCommand` configuration syntax.
Example:
For details on the `NSClient++` configuration please refer to the [official documentation](http://www.nsclient.org/nscp/wiki/doc/configuration/0.4.x).
-> ** Note **
+> **Note**
>
> The format of the `NSClient++` configuration file has changed from 0.3.x to 0.4!
The semi-colon after the last element (i.e. `address6`) may be omitted.
-> **Note**
->
-> Exclamation marks (!) are not permitted in object names.
-
Each object is uniquely identified by its type (`Host`) and name
(`host1.example.org`). Some types have composite names, e.g. the
`Service` type which uses the `host_name` attribute and the name
you specified to generate its object name.
+Exclamation marks (!) are not permitted in object names.
+
Objects can contain a comma-separated list of property
declarations. Instead of commas semi-colons may also be used.
The following data types are available for property values:
a multi-line
string.}}}
-> **Note**
->
-> Unlike in ordinary strings special characters do not have to be escaped
-> in multi-line string literals.
+Unlike in ordinary strings special characters do not have to be escaped
+in multi-line string literals.
#### <a id="boolean-literals"></a> Boolean Literals
port = 443
}
-> **Note**
->
-> Identifiers may not contain certain characters (e.g. space) or start
-> with certain characters (e.g. digits). If you want to use a dictionary
-> key that is not a valid identifier you can put the key in double
-> quotes.
+Identifiers may not contain certain characters (e.g. space) or start
+with certain characters (e.g. digits). If you want to use a dictionary
+key that is not a valid identifier you can put the key in double
+quotes.
-> **Note**
->
-> Setting a dictionary key to null causes the key and its value to be
-> removed from the dictionary.
+Setting a dictionary key to null causes the key and its value to be
+removed from the dictionary.
#### <a id="array"></a> Array
[ "hello", 42 ]
-> **Note**
->
-> An array may simultaneously contain values of different types, such as
-> strings and numbers.
+An array may simultaneously contain values of different types, such as
+strings and numbers.
#### <a id="expression-operators"></a> Operators
instantiated at run-time. Parent objects do not necessarily have to be
templates, however in general they are.
-> **Note**
->
-> The `vars` dictionary for the `localhost` object contains all three
-> custom attributes and the custom attribute `color` has the value `"blue"`.
+The `vars` dictionary for the `localhost` object contains all three
+custom attributes and the custom attribute `color` has the value `"blue"`.
Parent objects are resolved in the order they're specified using the
`import` keyword.
ScheduledDowntime | Host | host
ScheduledDowntime | Service | host, service
-> **Note**
->
-> Any valid config attribute can be accessed using the `host` and `service`
-> variables. For example, `host.vars.address` would return the host's
-> "address" custom attribute - or null if it doesn't have that custom attribute.
+Any valid config attribute can be accessed using the `host` and `service`
+variables. For example, `host.vars.address` would return the host's
+"address" custom attribute - or null if it doesn't have that custom attribute.
### <a id="boolean-values"></a> Boolean Values
include "some/other/file.conf"
include "conf.d/*.conf"
-> **Note**
->
-> Wildcard includes are not recursive.
+Wildcard includes are not recursive.
Icinga also supports include search paths similar to how they work in a
C/C++ compiler:
library "snmphelper"
-> **Note**
->
-> The `icinga` and `methods` libraries is automatically loaded at startup.
-> You don't need to load them manually.
-
<!--
### <a id="type-definition"></a> Type Definition
In addition to these attributes you can also use any of the attributes which are also valid for `Host` objects.
-> **Note**
->
-> Service objects have composite names, i.e. their names are based
-> on the host_name attribute and the name you specified. This means
-> you can define more than one object with the same (short) name
-> as long as the `host_name` attribute has a different value.
+Service objects have composite names, i.e. their names are based on the host_name attribute and the name you specified. This means
+you can define more than one object with the same (short) name as long as the `host_name` attribute has a different value.
### <a id="objecttype-servicegroup"></a> ServiceGroup
Attributes:
- Name |Description
- ----------------|----------------
- host_name |**Required.** The name of the host this notification belongs to.
- service_name |**Required.** The short name of the service this notification belongs to.
- vars |**Optional.** A dictionary containing custom attributes that are specific to this notification object.
- users |**Optional.** A list of user names who should be notified.
- user_groups |**Optional.** A list of user group names who should be notified.
- times |**Optional.** A dictionary containing `begin` and `end` attributes for the notification.
- notification_command|**Required.** The name of the notification command which should be executed when the notification is triggered.
- notification_interval|**Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 5 minutes.
- notification_period|**Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
- notification_type_filter|**Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
- notification_state_filter|**Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
-
+ Name | Description
+ --------------------------|----------------
+ host_name | **Required.** The name of the host this notification belongs to.
+ service_name | **Required.** The short name of the service this notification belongs to.
+ vars | **Optional.** A dictionary containing custom attributes that are specific to this notification object.
+ users | **Optional.** A list of user names who should be notified.
+ user_groups | **Optional.** A list of user group names who should be notified.
+ times | **Optional.** A dictionary containing `begin` and `end` attributes for the notification.
+ notification_command | **Required.** The name of the notification command which should be executed when the notification is triggered.
+ notification_interval | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 5 minutes.
+ notification_period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default.
+ notification_type_filter | **Optional.** A set of state filters when this notification should be triggered. By default everything is matched.
+ notification_state_filter | **Optional.** A set of type filters when this notification should be triggered. By default everything is matched.
+
Available notification type and state filters:
StateFilterOK
NotificationFilterRecovery
NotificationFilterFlappingStart
NotificationFilterFlappingEnd
-
-> **Note**
->
-> In order to notify on problem states, you will need the type filter `NotificationFilterProblem`.
### <a id="objecttype-dependency"></a> Dependency
StateFilterCritical
StateFilterUnknown
-> **Note**
->
-> Dependency objects have composite names, i.e. their names are based
-> on the `child_host_name` and `child_service_name` attributes and the
-> name you specified. This means you can define more than one object
-> with the same (short) name as long as one of the `child_host_name` and
-> `child_service_name` attributes has a different value.
+Dependency objects have composite names, i.e. their names are based on the `child_host_name` and `child_service_name` attributes and the
+name you specified. This means you can define more than one object with the same (short) name as long as one of the `child_host_name` and
+`child_service_name` attributes has a different value.
### <a id="objecttype-user"></a> User
NotificationFilterFlappingStart
NotificationFilterFlappingEnd
-> **Note**
->
-> In order to notify on problem states, you will need the type filter `NotificationFilterProblem`.
-> Recovery notifications require the state filter `StateFilterOK`.
-
Attributes:
Name |Description
duration |**Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
ranges |**Required.** A dictionary containing information which days and durations apply to this timeperiod.
-> **Note**
->
-> ScheduledDowntime objects have composite names, i.e. their names are based
-> on the `host_name` and `service_name` attributes and the
-> name you specified. This means you can define more than one object
-> with the same (short) name as long as one of the `host_name` and
-> `service_name` attributes has a different value.
+ScheduledDowntime objects have composite names, i.e. their names are based
+on the `host_name` and `service_name` attributes and the
+name you specified. This means you can define more than one object
+with the same (short) name as long as one of the `host_name` and
+`service_name` attributes has a different value.
### <a id="objecttype-filelogger"></a> FileLogger
An event command definition.
-> **Note**
->
-> Similar to Icinga 1.x event handlers.
-
Example:
object EventCommand "restart-httpd-event" {
service_format\_template|**Optional.** Service Format template for the performance data file. Defaults to a template that's suitable for use with PNP4Nagios.
rotation\_interval |**Optional.** Rotation interval for the files specified in `{host,service}\_perfdata\_path`. Defaults to 30 seconds.
-> **Note**
->
-> When rotating the performance data file the current UNIX timestamp is appended to the path specified
-> in `host_perfdata\_path` and `service_perfdata\_path` to generate a unique filename.
+When rotating the performance data file the current UNIX timestamp is appended to the path specified
+in `host_perfdata\_path` and `service_perfdata\_path` to generate a unique filename.
### <a id="objecttype-graphitewriter"></a> GraphiteWriter
Planned downtimes will also be taken into account for SLA reporting
tools calculating the SLAs based on the state and downtime history.
-> **Note**
->
-> Downtimes may overlap with their start and end times. If there
-> are multiple downtimes triggered for one object, the overall downtime depth
-> will be more than `1`. This is useful when you want to extend
-> your maintenance window taking longer than expected.
+Downtimes may overlap with their start and end times. If there
+are multiple downtimes triggered for one object, the overall downtime depth
+will be more than `1`. This is useful when you want to extend
+your maintenance window taking longer than expected.
### <a id="fixed-flexible-downtimes"></a> Fixed and Flexible Downtimes
Flexible downtimes need a start and end time for the time span, and a duration
independent from that time span.
-> **Note**
->
-> Modern web interfaces treat services in a downtime as `handled`.
-
### <a id="triggered-downtimes"></a> Triggered Downtimes
This is optional when scheduling a downtime. If there is already a downtime
a notification with the type `NotificationFilterAcknowledgement` is sent
to all notified users.
-> **Note**
->
-> Modern web interfaces treat acknowledged problems as `handled`.
-
### <a id="expiring-acknowledgements"></a> Expiring Acknowledgements
Once a problem is acknowledged it may disappear from your `handled problems`
you can define an expiration time when acknowledging the problem.
Icinga 2 will clear the acknowledgement when expired and start to
-re-notify if the problem persists.
\ No newline at end of file
+re-notify if the problem persists.
Read further about additional [naming conventions](#cluster-naming-convention).
-> **Note**
->
-> Not specifying the node name will default to FQDN. Make sure that all
-> configured endpoint names and set common names are in sync.
+Not specifying the node name will default to FQDN. Make sure that all
+configured endpoint names and set common names are in sync.
### <a id="configure-clusterlistener-object"></a> Configure the ClusterListener Object
peers = [ "icinga-node-2" ]
}
-> **Note**
->
-> The certificate files must be readable by the user Icinga 2 is running as. Also,
-> the private key file should not be world-readable.
+The certificate files must be readable by the user Icinga 2 is running as. Also,
+the private key file should not be world-readable.
Peers configures the direction used to connect multiple nodes together. If have
a three node cluster consisting of
assign where "oracle" in host.groups
}
-> **Tip**
->
-> Most common usecase is building a classic Master-Slave-Setup. The master node
-> does not have the `Checker` feature enabled, and the slave nodes are checking
-> services based on their location, inheriting from a global service template
-> defining the authorities.
+The most common use case is building a master-slave cluster. The master node
+does not have the `checker` feature enabled, and the slave nodes are checking
+services based on their location, inheriting from a global service template
+defining the authorities.
### <a id="cluster-health-check"></a> Cluster Health Check
assign where host.name = "icinga2a"
}
-> **Note**
->
-> Each cluster node should execute its own local cluster health check to
-> get an idea about network related connection problems from different
-> point of views. Use the `authorities` attribute to assign the service
-> check to the configured node.
+Each cluster node should execute its own local cluster health check to
+get an idea about network related connection problems from different
+point of views. Use the `authorities` attribute to assign the service
+check to the configured node.
### <a id="host-multiple-cluster-nodes"></a> Host With Multiple Cluster Nodes
half-life values. Icinga 2 compares the value with a single flapping threshold
configuration attribute named `flapping_threshold`.
-> **Note**
->
-> Flapping must be explicitely enabled setting the `Service` object attribute
-> `enable_flapping = 1`.
\ No newline at end of file
+Flapping detection can be enabled or disabled using the `enable_flapping` attribute.
logentries | object_id | bigint | NULL | FK: objects table (service associated with column)
hosts | check_service_object_id | bigint | NULL | FK: objects table (service associated with column)
-> **Note**
->
-> Additional command custom variables populated from 'vars' dictionary.
-> Additional global custom variables populated from 'IcingaVars' constant (object_id is NULL).
+Additional command custom variables populated from 'vars' dictionary.
+Additional global custom variables populated from 'IcingaVars' constant (object_id is NULL).
### <a id="schema-livestatus"></a> Livestatus
log | services, hosts, contacts, commands | parses [compatlog](#objecttype-compatlogger) and shows log attributes
statehist | hosts, services | parses [compatlog](#objecttype-compatlogger) and aggregates state change attributes
-> **Note**
->
-> The `commands` table is populated with `CheckCommand`, `EventCommand` and `NotificationCommand` objects.
+The `commands` table is populated with `CheckCommand`, `EventCommand` and `NotificationCommand` objects.
#### <a id="schema-livestatus-table-attributes"></a> Livestatus Table Attributes
status | custom_variable_values
status | custom_variables
-> **Note**
->
-> Command custom variables reflect the local 'vars' dictionary.
-> Status custom variables reflect the global 'IcingaVars' constant.
+Command custom variables reflect the local 'vars' dictionary.
+Status custom variables reflect the global 'IcingaVars' constant.
The migration script uses templates from the Icinga Template Library where
possible.
-> **Note**
->
-> Please check the provided README file for additional notes and possible
-> caveats.
-
# mkdir /etc/icinga2/conf.d/migrate
# /usr/bin/icinga2-migrate-config -c /etc/icinga/icinga.cfg -o /etc/icinga2/conf.d/migrate
not be re-used in your configuration. For instance, `generic-service` includes
all required attributes except `check_command` for an inline service.
-> **Note**
->
-> Sample configuration files are located in the `conf.d/` directory which is
-> included in `icinga2.conf` by default.
+Sample configuration files are located in the `conf.d/` directory which is
+included in `icinga2.conf` by default.
### <a id="differences-1x-2-include-files-dirs"></a> Include Files and Directories
include <itl/itl.conf>
-> **Best Practice**
->
-> By convention the `.conf` suffix is used for Icinga 2 configuration files.
+By convention the `.conf` suffix is used for Icinga 2 configuration files.
## <a id="differences-1x-2-resource-file-global-macros"></a> Resource File and Global Macros
const PluginDir = "/usr/lib/nagios/plugins"
-> **Note**
->
-> [Global macros](#global-constants) can only be defined once.
-
+[Global macros](#global-constants) can only be defined once. Trying to modify a
+global constant will result in an error.
## <a id="differences-1x-2-comments"></a> Comments
check_interval = 5m
}
-> **Note**
->
-> Please note that the default time value is seconds, if no duration literal
-> is given. `check_interval = 5` behaves the same as `check_interval = 5s`.
+Please note that the default time value is seconds, if no duration literal
+is given. `check_interval = 5` behaves the same as `check_interval = 5s`.
All strings require double quotes in Icinga 2. Therefore a double-quote
must be escaped with a backslash (e.g. in command line).
TODO
-> **Note**
->
-> If you are planning to access custom variables as runtime macros you may access
-> them with `_HOST`name as known from Icinga 1.x
-
## <a id="differences-1x-2-host-service-relation"></a> Host Service Relation
In Icinga 1.x a service object is associated with a host by defining the
vars.cpl = 60
}
-> **Note**
->
-> Tip: The above example uses the global `PluginDir` constant instead of the Icinga 1.x
-> $USER1$ macro. It also replaces the Icinga 1.x notation with $ARGn$ with freely
-> definable custom attributes.
-
### <a id="differences-1x-2-environment-macros"></a> Environment Macros
TODO
* Create notification C-Mail, set notification_command for mail, add user Y,
assign notification C-Mail to service C
-> **Note**
->
-> Notification objects are not required to be service-agnostic. They may use
-> global notification templates and can be added to a service wherever needed.
-
Previously in Icinga 1.x it looked like this:
service -> (contact, contactgroup) -> notification command
notification_state_filter = StateFilterWarning | StateFilterUnknown | StateFilterCritical,
notification_type_filter = NotificationProblem | NotificationRecovery | NotificationFlappingStart | NotificationFlappingEnd | NotificationDowntimeStart | NotificationDowntimeEnd | NotificationDowntimeRemoved
-> **Note**
->
-> Please note that `NotificationProblem` as type is required for all problem
-> notifications.
-
Icinga 2 adds more fine-grained type filters for acknowledgements, downtime
and flapping type (start, end, ...).
-> **Note**
->
-> Notification state and type filters are only valid configuration attributes for
-> `Notification` and `User` objects.
-
## <a id="differences-1x-2-dependencies-parents"></a> Dependencies and Parents
In Icinga 1.x it's possible to define host parents to determine network reachability
Icinga 2 implements a new built-in distributed monitoring architecture, including config and check
distribution, IPv4/IPv6 support, SSL certificates and domain support for DMZ. High Availability
and load balancing are also part of the Icinga 2 [Cluster](#cluster) setup.
+
# <a id="vagrant"></a> Vagrant Demo VM
The Icinga 2 Git repository contains support for [Vagrant](http://docs.vagrantup.com/v2/)
-with VirtualBox. In order to build the Vagrant VM first you will have to check out
+with VirtualBox. Please note that Vagrant version `1.0.x` is not supported. At least
+version `1.2.x` is required.
+
+In order to build the Vagrant VM first you will have to check out
the Git repository:
$ git clone git://git.icinga.org/icinga2.git
$ vagrant up
-> **Note**
->
-> [Vagrant](http://www.vagrantup.com/) and [VirtualBox](https://www.virtualbox.org/wiki/Downloads)
-> are available for various distributions. Please note that Vagrant version `1.0.x` is not
-> supported. At least version `1.2.x` is required.
-
The Vagrant VM is based on CentOS 6.4 and uses the official Icinga 2 RPM
packages from `packages.icinga.org`. The check plugins are installed from
EPEL providing RPMs with sources from the Monitoring Plugins project.
Host | 127.0.0.1
Port | 2222
Username | vagrant
- Password | vagrant
\ No newline at end of file
+ Password | vagrant
+
projects / icinga2 / commitdiff