the standalone version of the Icinga 1.x classic web interface. It assumes
that you are familiar with the system you're installing Icinga 2 on.
-### Installing Icinga 2
+### Setting up Icinga 2
In order to get started with Icinga 2 you will have to install it. The
preferred way of doing this is to use the official Debian or RPM
not yet available you will have to check out the Icinga 2 Git repository
from git://git.icinga.org/icinga2 and read the *INSTALL* file.
+#### Installation Paths
+
By default Icinga 2 uses the following files and directories:
Path |Description
/var/cache/icinga2 |Performance data files and status.dat/objects.cache.
/var/lib/icinga2 |The Icinga 2 state file.
+#### Configuration
+
An example configuration file is installed for you in /etc/icinga2/icinga2.conf.
Here's a brief description of the concepts the example configuration file
services which belong to this host. Most of the templates in the Icinga Template
Library require an *address* macro.
-### Installing the Icinga Classic UI
+### Setting up the Icinga Classic UI
Icinga 2 can write status.dat and objects.cache files in the format that
is supported by the Icinga 1.x Classic UI. External commands (a.k.a. the
/var/cache/icinga2. The log files can be found in /var/log/icinga2/compat.
The command pipe can be found in /var/run/icinga2.
+#### Installing the Icinga Classic UI
+
You can install the Icinga 1.x Classic UI in standalone mode using the
following commands:
> found on the Icinga Wiki here:
> [https://wiki.icinga.org/display/howtos/Setting+up+Icinga+Classic+UI+Standalone](https://wiki.icinga.org/display/howtos/Setting+up+Icinga+Classic+UI+Standalone)
+#### Configuring the Classic UI
+
After installing the Classic UI you will need to update the following
-settings in your cgi.cfg configuration file in the "STANDALONE (ICINGA 2)
-OPTIONS" section:
+settings in your *cgi.cfg* configuration file in the *STANDALONE (ICINGA 2)
+OPTIONS* section:
Configuration Setting |Value
------------------------------------|------------------------------------
Verify that your Icinga 1.x Classic UI works by browsing to your Classic
UI installation URL, e.g.
-[http://localhost/icinga](http://localhost/icinga)
\ No newline at end of file
+[http://localhost/icinga](http://localhost/icinga)
+
+### Configuring IDO Support
+
+TODO
+
+## Running Icinga
+
+TODO
+
+## Monitoring Basics
+
+### Hosts
+
+TODO
+
+### Services
+
+TODO
+
+### Check Commands
+
+TODO
+
+### Macros
+
+TODO
+
+## Using Templates
+
+TODO
+
+## Groups
+
+TODO
+
+## Host/Service Dependencies
+
+TODO
+
+## Time Periods
+
+TODO
+
+## Notifications
+
+TODO
-Configuration Syntax
-====================
+## Configuration Syntax
-Object Definition
------------------
+### Object Definition
Icinga 2 features an object-based configuration format. In order to
define objects the *object* keyword is used:
property declarations. The following data types are available for
property values:
-### Numeric Literals
+#### Numeric Literals
A floating-point number.
-27.3
-### Duration Literal
+#### Duration Literals
Similar to floating-point numbers except for the fact that they support
suffixes to help with specifying time durations.
Supported suffixes include ms (milliseconds), s (seconds), m (minutes)
and h (hours).
-### String Literals
+#### String Literals
A string.
arbitrary ASCII characters using the backslash character (\\) followed
by an ASCII character in octal encoding.
-### Multiline String Literals
+#### Multiline String Literals
Strings spanning multiple lines can be specified by enclosing them in
{{{ and }}}.
a multi-line
string.}}}
-### Boolean Literals
+#### Boolean Literals
The keywords *true* and *false* are equivalent to 1 and 0 respectively.
-### Null Value
+#### Null Value
The *null* keyword can be used to specify an empty value.
-### Dictionary
+#### Dictionary
An unordered list of key-value pairs. Keys must be unique and are
compared in a case-insensitive manner.
> Setting a dictionary key to null causes the key and its value to be
> removed from the dictionary.
-### Array
+#### Array
An ordered list of values.
Example:
- [
- "hello",
- "world",
- 42,
- [ "a", "nested", "array" ]
- ]
+ [ "hello", 42 ]
> **Note**
>
-> An array may simultaneously contain values of different types, e.g.
+> An array may simultaneously contain values of different types, such as
> strings and numbers.
-Operators
----------
+### Operators
In addition to the *=* operator shown above a number of other operators
to manipulate configuration objects are supported. Here's a list of all
available operators:
-### Operator =
+#### Operator =
Sets a dictionary element to the specified value.
In this example a has the value 7 after both instructions are executed.
-### Operator +=
+#### Operator +=
Modifies a dictionary or array by adding new elements to it.
<!--
-### Operator *-=*
+#### Operator -=
Removes elements from a dictionary.
In this example a contains *"hello"*. Trying to remove an item that does
not exist is not an error. Not implemented yet.
-### Operator *\*=*
+#### Operator \*=
Multiplies an existing dictionary element with the specified number. If
the dictionary element does not already exist 0 is used as its value.
In this example a is 300. This only works for numbers. Not implemented
yet.
-### Operator */=*
+#### Operator /=
Divides an existing dictionary element by the specified number. If the
dictionary element does not already exist 0 is used as its value.
-->
-Attribute Shortcuts
--------------------
+### Indexer
-### Indexer Shortcut
+The indexer syntax provides a convenient way to set dictionary elements.
Example:
}
}
-Inheritance
------------
+### Inheritance
Objects can inherit attributes from other objects.
Parent objects are resolved in the order they're specified using the
*inherits* keyword.
-Variables
----------
+### Variables
Global variables can be set using the *set* keyword:
The value can be a string, number, array or a dictionary.
-Constant Expressions
---------------------
+### Constant Expressions
Simple calculations can be performed using the constant expression syntax:
> Constant expressions are evaluated as soon as they're encountered in
> the configuration file.
-Comments
---------
+### Comments
The Icinga 2 configuration format supports C/C++-style comments.
retry_interval = 15
}
-Includes
---------
+### Includes
Other configuration files can be included using the *include* directive.
Paths must be relative to the configuration file that contains the
Wildcards are not permitted when using angle brackets.
-Library directive
------------------
+### Library directive
The *library* directive can be used to manually load additional
libraries. Libraries can be used to provide additional object types and
<!--
-Type Definition
----------------
+### Type Definition
By default Icinga has no way of semantically verifying its configuration
objects. This is where type definitions come in. Using type definitions
-Object Types
-============
+## Object Types
-ConsoleLogger
--------------
+### Host
-Specifies Icinga 2 logging to the console.
+A host.
+
+> **Note**
+>
+> Unlike in Icinga 1.x hosts are not checkable objects in Icinga 2.
Example:
- object ConsoleLogger "my-debug-console" {
- severity = "debug"
- }
+ object Host "localhost" {
+ display_name = "The best host there is",
-Attributes:
+ groups = [ "all-hosts" ],
- Name |Description
- ----------------|----------------
- severity |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".
+ check = "ping",
-FileLogger
-----------
+ host_dependencies = [ "router" ],
-Specifies Icinga 2 logging to a file.
+ service_dependencies = [
+ { host = "db-server", service = "mysql" }
+ ],
-Example:
+ services["ping"] = {
+ templates = [ "ping" ]
+ },
- object FileLogger "my-debug-file" {
- severity = "debug",
- path = "/var/log/icinga2/icinga2-debug.log"
+ services["http"] = {
+ templates = [ "my-http" ],
+
+ macros = {
+ vhost = "test1.example.org",
+ port = 81
+ }
+ }
}
Attributes:
Name |Description
----------------|----------------
- path |**Required.** The log path.
- severity |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".
+ display_name |**Optional.** A short description of the host.
+ check |**Optional.** A service that is used to determine whether the host is up or down. This must be a service short name of a service that belongs to the host.
+ groups |**Optional.** A list of host groups this host belongs to.
+ host_dependencies|**Optional.** A list of host names which this host depends on. These dependencies are used to determine whether the host is unreachable.
+ service_dependencies|**Optional.** A list of services which this host depends on. Each array element must be a dictionary containing the keys "host" and "service". These dependencies are used to determine whether the host is unreachable.
+ services |**Optional.** Inline definition of services. Each dictionary item specifies a service.<br /><br />The *templates* attribute can be used to specify an array of templates that should be inherited by the service.<br /><br />The new service's name is "hostname:service" - where "service" is the dictionary key in the services dictionary.<br /><br />The dictionary key is used as the service's short name.
+ macros |TODO
-SyslogLogger
-------------
+### HostGroup
-Specifies Icinga 2 logging to syslog.
+A group of hosts.
Example:
- object SyslogLogger "my-crit-syslog" {
- severity = "critical"
+ object HostGroup "my-hosts" {
+ display_name = "My hosts",
}
Attributes:
Name |Description
----------------|----------------
- severity |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".
-
-CheckCommand
-------------
-
-A check command definition. Additional default command macros can be
-defined here.
-
-Example:
-
- object CheckCommand "check_snmp" inherits "plugin-check-command" {
- command = "$plugindir$/check_snmp -H $address$ -C $community$ -o $oid$",
-
- macros = {
- address = "127.0.0.1",
- community = "public",
- }
- }
-
-NotificationCommand
--------------------
-
-A notification command definition.
-
-Example:
-
- object NotificationCommand "mail-service-notification" inherits "plugin-notification-command" {
- command = [
- "/opt/bin/send-mail-notification",
- "$CONTACTEMAIL$",
- "$NOTIFICATIONTYPE$ - $HOSTNAME$ - $SERVICEDESC$ - $SERVICESTATE$",
- {{{***** Icinga *****
-
- Notification Type: $NOTIFICATIONTYPE$
-
- Service: $SERVICEDESC$
- Host: $HOSTALIAS$
- Address: $HOSTADDRESS$
- State: $SERVICESTATE$
-
- Date/Time: $LONGDATETIME$
-
- Additional Info: $SERVICEOUTPUT$
-
- Comment: [$NOTIFICATIONAUTHORNAME$] $NOTIFICATIONCOMMENT$}}}
- ]
- }
-
-EventCommand
-------------
-
-An event command definition.
-
-> **Note**
->
-> Similar to Icinga 1.x event handlers.
-
-Example:
-
- object EventCommand "restart-httpd-event" inherits "plugin-event-command" {
- command = "/opt/bin/restart-httpd.sh",
- }
-
+ display_name |**Optional.** A short description of the host group.
-Service
--------
+### Service
Service objects describe network services and how they should be checked
by Icinga 2.
host |**Required.** The host this service belongs to. There must be a *Host* object with that name.
short_name |**Required.** The service name. Must be unique on a per-host basis (Similar to the service_description attribute in Icinga 1.x).
display_name |**Optional.** A short description of the service.
- macros |TODO
+ macros |**Optional.**
check\_command |**Required.** The name of the check command.
max\_check\_attempts|TODO
- check\_period |TODO
+ check\_period |**Optional.** The name of a time period which determines when this service should be checked. Not set by default.
check\_interval |**Optional.** The check interval (in seconds).
retry\_interval |**Optional.** The retry interval (in seconds). This is used when the service is in a soft state. Defaults to 1/5th of the check interval if not specified.
- event\_command |TODO
+ event\_command |**Optional.** The name of an event command that should be executed every time the service's state changes.
flapping\_threshold|TODO
volatile |TODO
host\_dependencies|TODO
groups |**Optional.** The service groups this service belongs to.
notifications |TODO
-ServiceGroup
-------------
+### ServiceGroup
A group of services.
----------------|----------------
display_name |**Optional.** A short description of the service group.
-Notification
-------------
+### Notification
TODO
Name |Description
----------------|----------------
- host |TODO
- service |TODO
+ host |**Required.** The name of the host this notification belongs to.
+ service |**Required.** The short name of the service this notification belongs to.
macros |TODO
- users |TODO
- user_groups |TODO
+ 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 |TODO
notification_command|TODO
notification_interval|TODO
notification_type_filter|TODO
notification_state_filter|TODO
-User
-----
+### User
-TODO
+A user.
Example:
Name |Description
----------------|----------------
- display_name |TODO
+ display_name |**Optional.** A short description of the user.
macros |TODO
groups |TODO
enable_notifications|TODO
notification_type_filter|TODO
notification_state_filter|TODO
-UserGroup
----------
+### UserGroup
-TODO
+A user group.
Example:
- TODO
+ object UserGroup "noc-staff" {
+ display_name = "NOC Staff"
+ }
Attributes:
Name |Description
----------------|----------------
- display_name |TODO
+ display_name |**Optional.** A short description of the user group.
-TimePeriod
-----------
+### TimePeriod
-TODO
+Time periods can be used to specify when services should be checked or to limit
+when notifications should be sent out.
Example:
Name |Description
----------------|----------------
- display_name |TODO
+ display_name |**Optional.** A short description of the time period.
methods |TODO
ranges |TODO
-TimePeriod
-----------
+### ConsoleLogger
-TODO
+Specifies Icinga 2 logging to the console.
Example:
- TODO
+ object ConsoleLogger "my-debug-console" {
+ severity = "debug"
+ }
Attributes:
Name |Description
----------------|----------------
- display_name |TODO
+ severity |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".
-Domain
-------
+### FileLogger
-TODO
+Specifies Icinga 2 logging to a file.
Example:
- TODO
+ object FileLogger "my-debug-file" {
+ severity = "debug",
+ path = "/var/log/icinga2/icinga2-debug.log"
+ }
Attributes:
Name |Description
----------------|----------------
- acl |TODO
-
-Host
-----
+ path |**Required.** The log path.
+ severity |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".
-A host.
+### SyslogLogger
-> **Note**
->
-> Unlike in Icinga 1.x hosts are not checkable objects in Icinga 2.
+Specifies Icinga 2 logging to syslog.
Example:
- object Host "localhost" {
- display_name = "The best host there is",
+ object SyslogLogger "my-crit-syslog" {
+ severity = "critical"
+ }
- groups = [ "all-hosts" ],
+Attributes:
- check = "ping",
-
- host_dependencies = [ "router" ],
+ Name |Description
+ ----------------|----------------
+ severity |**Optional.** The minimum severity for this log. Can be "debug", "information", "warning" or "critical". Defaults to "information".
- service_dependencies = [
- { host = "db-server", service = "mysql" }
- ],
+### CheckCommand
- services["ping"] = {
- templates = [ "ping" ]
- },
+A check command definition. Additional default command macros can be
+defined here.
- services["http"] = {
- templates = [ "my-http" ],
+Example:
- macros = {
- vhost = "test1.example.org",
- port = 81
- }
+ object CheckCommand "check_snmp" inherits "plugin-check-command" {
+ command = "$plugindir$/check_snmp -H $address$ -C $community$ -o $oid$",
+
+ macros = {
+ address = "127.0.0.1",
+ community = "public",
}
}
Name |Description
----------------|----------------
- display_name |**Optional.** A short description of the host.
- check |**Optional.** A service that is used to determine whether the host is up or down. This must be a service short name of a service that belongs to the host.
- groups |**Optional.** A list of host groups this host belongs to.
- host_dependencies|**Optional.** An array of host names which this host depends on. These dependencies are used to determine whether the host is unreachable.
- service_dependencies|**Optional.** An array of service names which this host depends on. Each array element must be a dictionary containing the keys "host" and "service". These dependencies are used to determine whether the host is unreachable.
- services |**Optional.** Inline definition of services. Each dictionary item specifies a service.<br /><br />The *templates* attribute can be used to specify an array of templates that should be inherited by the service.<br /><br />The new service's name is "hostname:service" - where "service" is the dictionary key in the services dictionary.<br /><br />The dictionary key is used as the service's short name.
+ methods |TODO
+ command |TODO
+ export_macros |TODO
+ escape_macros |TODO
macros |TODO
+ timeout |TODO
-HostGroup
----------
+### NotificationCommand
-A group of hosts.
+A notification command definition.
Example:
- object HostGroup "my-hosts" {
- display_name = "My hosts",
+ object NotificationCommand "mail-service-notification" inherits "plugin-notification-command" {
+ command = [
+ "/opt/bin/send-mail-notification",
+ "$CONTACTEMAIL$",
+ "$NOTIFICATIONTYPE$ - $HOSTNAME$ - $SERVICEDESC$ - $SERVICESTATE$",
+ {{{***** Icinga *****
+
+ Notification Type: $NOTIFICATIONTYPE$
+
+ Service: $SERVICEDESC$
+ Host: $HOSTALIAS$
+ Address: $HOSTADDRESS$
+ State: $SERVICESTATE$
+
+ Date/Time: $LONGDATETIME$
+
+ Additional Info: $SERVICEOUTPUT$
+
+ Comment: [$NOTIFICATIONAUTHORNAME$] $NOTIFICATIONCOMMENT$}}}
+ ]
}
Attributes:
Name |Description
----------------|----------------
- display_name |**Optional.** A short description of the host group.
+ methods |TODO
+ command |TODO
+ export_macros |TODO
+ escape_macros |TODO
+ macros |TODO
+ timeout |TODO
-PerfdataWriter
---------------
+### EventCommand
+
+An event command definition.
+
+> **Note**
+>
+> Similar to Icinga 1.x event handlers.
+
+Example:
+
+ object EventCommand "restart-httpd-event" inherits "plugin-event-command" {
+ command = "/opt/bin/restart-httpd.sh",
+ }
+
+
+Attributes:
+
+ Name |Description
+ ----------------|----------------
+ methods |TODO
+ command |TODO
+ export_macros |TODO
+ escape_macros |TODO
+ macros |TODO
+ timeout |TODO
+
+### PerfdataWriter
Writes check result performance data to a defined path using macro
pattern.
> When rotating the perfdata file the current UNIX timestamp is appended to the path specified
> in *perfdata\_path* to generate a unique filename.
-IdoMySqlConnection
-------------------
+### IdoMySqlConnection
IDO DB schema compatible output into MySQL database.
servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time)
systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time)
-LiveStatusListener
-------------------
+### LiveStatusListener
Livestatus API interface available as TCP or UNIX socket.
>
> UNIX sockets are not supported on Windows.
-StatusDataWriter
-----------------
+### StatusDataWriter
-TODO
+Periodically writes status data files which are used by the Classic UI and other third-party tools.
Example:
- TODO
+ library "compat"
+
+ object StatusDataWriter "status" {
+ status\_path = "/data/status.dat",
+ objects\_path = "/data/objects.path"
+ }
Attributes:
Name |Description
----------------|----------------
- status\_path |TODO
- objects\_path |TODO
+ status\_path |**Optional.** Path to the status.dat file. Defaults to IcingaLocalStateDir + "/cache/icinga2/status.dat".
+ objects\_path |**Optional.** Path to the objects.cache file. Defaults to IcingaLocalStateDir + "/cache/icinga2/objects.cache".
-ExternalCommandListener
------------------------
+### ExternalCommandListener
-TODO
+Implements the Icinga 1.x command pipe which can be used to send commands to Icinga.
Example:
- TODO
+ library "compat"
+
+ object ExternalCommandListener "external" {
+ command\_path = "/data/icinga2.cmd"
+ }
Attributes:
Name |Description
----------------|----------------
- command\_path |TODO
+ command\_path |**Optional.** Path to the command pipe. Defaults to IcingaLocalStateDir + "/run/icinga2/icinga2.cmd".
-CompatLogger
-------------
+### CompatLogger
-TODO
+Writes log files in a format that's compatible with Icinga 1.x.
Example:
- TODO
+ library "compat"
+
+ object CompatLogger "my-log" {
+ log\_dir = "/data/compat-log",
+ rotation\_method = "HOURLY"
+ }
Attributes:
Name |Description
----------------|----------------
- log\_dir |TODO
- rotation\_method|TODO
+ log\_dir |**Optional.** Path to the compat log directory. Defaults to IcingaLocalStateDir + "/log/icinga2/compat".
+ rotation\_method|**Optional.** Specifies when to rotate log files. Can be one of "HOURLY", "DAILY", "WEEKLY" or "MONTHLY". Defaults to "HOURLY".
-CheckResultReader
------------------
+### CheckResultReader
TODO
----------------|----------------
spool\_dir |TODO
-CheckerComponent
-----------------
+### CheckerComponent
TODO
object CheckerComponent "checker" { }
-NotificationComponent
----------------------
+### NotificationComponent
TODO
object NotificationComponent "notification" { }
-ClusterListener
----------------
+### ClusterListener
TODO
bind\_port |TODO
peers |TODO
-Endpoint
---------
+### Endpoint
Endpoint objects are used to specify connection information for remote
Icinga 2 instances.
node |**Required.** The hostname/IP address of the remote Icinga 2 instance.
service |**Required.** The service name/port of the remote Icinga 2 instance.
config\_files |TODO
- accept\_config |TODO
+ accept\_config |**Optional.** A list of endpoint names from which this endpoint accepts configuration files.
+
+### Domain
+
+TODO
+
+Example:
+
+ TODO
+
+Attributes:
+
+ Name |Description
+ ----------------|----------------
+ acl |TODO
projects / icinga2 / commitdiff