From 0c674147011b6f83ec244279e100b33d2596ebca Mon Sep 17 00:00:00 2001 From: Gunnar Beutner Date: Mon, 30 Sep 2013 09:05:27 +0200 Subject: [PATCH] Remove unused files. --- docs/icinga2-compat.md | 131 -- docs/icinga2-config-syntax.md | 419 ----- docs/icinga2-config-types.md | 994 ------------ docs/icinga2-config.md | 76 - docs/icinga2-install.md | 72 - docs/icinga2-intro.md | 268 --- docs/icinga2-main.md | 56 - docs/icinga2-migration.md | 36 - docs/icinga2-tutorial.md | 811 ---------- docs/icinga2.md | 2865 --------------------------------- 10 files changed, 5728 deletions(-) delete mode 100644 docs/icinga2-compat.md delete mode 100644 docs/icinga2-config-syntax.md delete mode 100644 docs/icinga2-config-types.md delete mode 100644 docs/icinga2-config.md delete mode 100644 docs/icinga2-install.md delete mode 100644 docs/icinga2-intro.md delete mode 100644 docs/icinga2-main.md delete mode 100644 docs/icinga2-migration.md delete mode 100644 docs/icinga2-tutorial.md delete mode 100644 docs/icinga2.md diff --git a/docs/icinga2-compat.md b/docs/icinga2-compat.md deleted file mode 100644 index a39e151f1..000000000 --- a/docs/icinga2-compat.md +++ /dev/null @@ -1,131 +0,0 @@ -Purpose -======= - -Documentation on the compatibility and changes introduced with Icinga 2. - -Introduction -============ - -Unlike Icinga 1.x, all used components (not only those for -compatibility) run asynchronous and use queues, if required. That way -Icinga 2 does not get blocked by any event, action or execution. - -Configuration -============= - -> **Note** -> -> If you are upgrading from Icinga 1.x (or Nagios 3.x+) please note that -> Icinga 2 introduces a new configuration format. - -Details on the configuration can be found in chapter -[Configuration](:icinga2-config.html) - -Icinga 2 ships a config conversion script which will help you migrating -the existing configuration into the new format. Please look into the -*tools/configconvert* directory and follow the *README* instructions. - -> **Tip** -> -> If you kept planning to clean up your existing configuration, it may -> be a good shot to start fresh with a new configuration strategy based -> on the Icinga 2 configuration logic. - -Check Plugins -============= - -All native check plugins can be used with Icinga 2. The configuration of -check commands is changed due to the new configuration format. - -Classic status and log files -============================ - -Icinga 2 will write status.dat and objects.cache in a given interval -like known from Icinga 1.x - including the logs and their archives in -the old format and naming syntax. That way you can point any existing -Classic UI installation to the new locations (or any other addon/plugin -using them). - -External Commands -================= - -Like known from Icinga 1.x, Icinga 2 also provides an external command -pipe allowing your scripts and guis to send commands to the core -triggering various actions. - -Some commands are not supported though as their triggered functionality -is not available in Icinga 2 anymore. - -For a detailed list, please check: -[https://wiki.icinga.org/display/icinga2/External+Commands](https://wiki.icinga.org/display/icinga2/External+Commands) - -Performance Data -================ - -The Icinga 1.x Plugin API defines the performance data format. Icinga 2 -parses the check output accordingly and writes performance data files -based on template macros. File rotation interval can be defined as well. - -Unlike Icinga 1.x you can define multiple performance data writers for -all your graphing addons such as PNP, inGraph or graphite. - -IDO DB -====== - -Icinga 1.x uses an addon called *IDOUtils* to store core configuration, -status and historical information in a database schema. Icinga Web and -Reporting are using that database as their chosen backend. - -Icinga 2 is compatible to the IDO db schema but the the underlaying -design of inserting, updating and deleting data is different - -asynchronous queueing, database transactions and optimized queries for -performance. - -Furthermore there is no seperated daemon to receive the data through a -socket. Instead the IDO component queues the data and writes directly -into the database using the native database driver library (e.g. -libmysqlclient). Unlike Icinga 1.x libdbi as db abstraction layer is not -used anymore. - -Livestatus -========== - -Icinga 2 supports the livestatus api while using Icinga 1.x an addon -named *mk\_livestatus* was required. - -Next to the GET functionality for retrieving configuration, status and -historical data, Icinga 2 livestatus also supports the COMMANDS -functionality. - -> **Tip** -> -> Icinga 2 supports tcp sockets natively while the Icinga 1.x addon only -> provides unix socket support. - -Checkresult Reaper -================== - -Unlike Icinga 1.x Icinga 2 is a multithreaded application and processes -check results in memory. The old checkresult reaper reading files from -disk again is obviously not required anymore for native checks. - -Some popular addons have been injecting their checkresults into the -Icinga 1.x checkresult spool directory bypassing the external command -pipe and PROCESS\_SERVICE\_CHECK\_RESULT mainly for performance reasons. - -In order to support that functionality as well, Icinga 2 got its -optional checkresult reaper. - -Changes -======= - -This is a collection of known changes in behaviour, configuration and -outputs. - -> **Note** -> -> May be incomplete, and requires updates in the future. - -TODO - -/\* vim: set syntax=asciidoc filetype=asciidoc: \*/ diff --git a/docs/icinga2-config-syntax.md b/docs/icinga2-config-syntax.md deleted file mode 100644 index 193aaa495..000000000 --- a/docs/icinga2-config-syntax.md +++ /dev/null @@ -1,419 +0,0 @@ -Configuration Syntax -==================== - -Object Definition ------------------ - -Icinga 2 features an object-based configuration format. In order to -define objects the *object* keyword is used: - - object Host "host1.example.org" { - display_name = "host1", - - check_interval = 30, - retry_interval = 15, - - macros = { - address = "192.168.0.1" - } - } - -> **Note** -> -> The Icinga 2 configuration format is agnostic to whitespaces and -> new-lines. - -> **Note** -> -> Colons (:) are not permitted in object names. - -Each object is uniquely identified by its type (*Host*) and name -(*host1.example.org*). Objects can contain a comma-separated list of -property declarations. The following data types are available for -property values: - -### Numeric Literals - -A floating-point number. - -Example: - - -27.3 - -### Duration Literal - -Similar to floating-point numbers except for that fact that they support -suffixes to help with specifying time durations. - -Example: - - 2.5m - -Supported suffixes include ms (milliseconds), s (seconds), m (minutes) -and h (hours). - -### String Literals - -A string. - -Example: - - "Hello World!" - -Certain characters need to be escaped. The following escape sequences -are supported: - - ------------------------------------ ------------------------------------ - Character Escape sequence - " \\" - \ \\t - \ \\r - \ \\n - \ \\b - \ \\f - ------------------------------------ ------------------------------------ - -In addition to these pre-defined escape sequences you can specify -arbitrary ASCII characters using the backslash character (\\) followed -by an ASCII character in octal encoding. - -### Multiline String Literals - -Strings spanning multiple lines can be specified by enclosing them in -{{{ and }}}. - -Example. - - {{{This - is - a multi-line - string.}}} - -### Boolean Literals - -The keywords *true* and *false* are equivalent to 1 and 0 respectively. - -### Null Value - -The *null* keyword can be used to specify an empty value. - -### Dictionary - -An unordered list of key-value pairs. Keys must be unique and are -compared in a case-insensitive manner. - -Individual key-value pairs must be separated from each other with a -comma. The comma after the last key-value pair is optional. - -Example: - - { - address = "192.168.0.1", - 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. - -> **Note** -> -> Setting a dictionary key to null causes the key to be removed from the -> dictionary. - -### Array - -An ordered list of values. - -Individual array elements must be separated from each other with a -comma. The comma after the last element is optional. - -Example: - - [ - "hello", - "world", - 42, - [ "a", "nested", "array" ] - ] - -> **Note** -> -> An array may simultaneously contain values of different types, e.g. -> strings and numbers. - -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 *=* - -Sets a dictionary element to the specified value. - -Example: - - { - a = 5, - a = 7 - } - -In this example a has the value 7 after both instructions are executed. - -### Operator *+=* - -Modifies a dictionary or array by adding new elements to it. - -Example: - - { - a = [ "hello" ], - a += [ "world" ] - } - -In this example a contains both *"hello"* and *"world"*. This currently -only works for dictionaries and arrays. Support for numbers might be -added later on. - -### Operator *-=* - -Removes elements from a dictionary. - -Example: - - { - a = { "hello", "world" }, - a -= { "world" } - } - -In this example a contains *"hello"*. Trying to remove an item that does -not exist is not an error. Not implemented yet. - -### Operator *\*=* - -Multiplies an existing dictionary element with the specified number. If -the dictionary element does not already exist 0 is used as its value. - -Example: - - { - a = 60, - a *= 5 - } - -In this example a is 300. This only works for numbers. Not implemented -yet. - -### Operator */=* - -Divides an existing dictionary element by the specified number. If the -dictionary element does not already exist 0 is used as its value. - -Example: - - { - a = 300, - a /= 5 - } - -In this example a is 60. This only works for numbers. Not implemented -yet. - -Attribute Shortcuts -------------------- - -### Indexer Shortcut - -Example: - - { - hello["key"] = "world" - } - -This is equivalent to writing: - - { - hello += { - key = "world" - } - } - -Specifiers ----------- - -Objects can have specifiers that have special meaning. The following -specifiers can be used (prefacing the *object* keyword): - -### Specifier *abstract* - -This specifier identifies the object as a template which can be used by -other object definitions. The object will not be instantiated on its -own. - -Instead of using the *abstract* specifier you can use the *template* -keyword which is a shorthand for writing *abstract object*: - - template Service "http" { - ... - } - -### Specifier *local* - -This specifier disables replication for this object. The object will not -be sent to remote Icinga instances. - -Inheritance ------------ - -Objects can inherit attributes from one or more other objects. - -Example: - - template Host "default-host" { - check_interval = 30, - - macros = { - color = "red" - } - } - - template Host "test-host" inherits "default-host" { - macros += { - color = "blue" - } - } - - object Host "localhost" inherits "test-host" { - macros += { - address = "127.0.0.1", - address6 = "::1" - } - } - -> **Note** -> -> The *"default-host"* and *"test-host"* objects are marked as templates -> using the *abstract* keyword. Parent objects do not necessarily have -> to be *abstract* though in general they are. - -> **Note** -> -> The += operator is used to insert additional properties into the -> macros dictionary. The final dictionary contains all 3 macros and the -> property *color* has the value *"blue"*. - -Parent objects are resolved in the order they’re specified using the -*inherits* keyword. - -Comments --------- - -The Icinga 2 configuration format supports C/C++-style comments. - -Example: - - /* - This is a comment. - */ - object Host "localhost" { - check_interval = 30, // this is also a comment. - retry_interval = 15 - } - -Includes --------- - -Other configuration files can be included using the *include* directive. -Paths must be relative to the configuration file that contains the -*include* directive. - -Example: - - include "some/other/file.conf" - include "conf.d/*.conf" - -> **Note** -> -> Wildcard includes are not recursive. - -Icinga also supports include search paths similar to how they work in a -C/C++ compiler: - - include - -Note the use of angle brackets instead of double quotes. This causes the -config compiler to search the include search paths for the specified -file. By default \$PREFIX/icinga2 is included in the list of search -paths. - -Wildcards are not permitted when using angle brackets. - -Library directive ------------------ - -The *library* directive can be used to manually load additional -libraries. Upon loading these libraries may provide additional types or -methods. - -Example: - - library "snmphelper" - -> **Note** -> -> The *icinga* library is automatically loaded at startup. - -Type Definition ---------------- - -By default Icinga has no way of semantically verifying its configuration -objects. This is where type definitions come in. Using type definitions -you can specify which attributes are allowed in an object definition. - -Example: - - type Pizza { - %require "radius", - %attribute number "radius", - - %attribute dictionary "ingredients" { - %validator "ValidateIngredients", - - %attribute string "*", - - %attribute dictionary "*" { - %attribute number "quantity", - %attribute string "name" - } - }, - - %attribute any "custom::*" - } - -The Pizza definition provides the following validation rules: - -- Pizza objects must contain an attribute *radius* which has to be a - number. - -- Pizza objects may contain an attribute *ingredients* which has to be - a dictionary. - -- Elements in the ingredients dictionary can be either a string or a - dictionary. - -- If they’re a dictionary they may contain attributes *quantity* (of - type number) and *name* (of type string). - -- The script function *ValidateIngredients* is run to perform further - validation of the ingredients dictionary. - -- Pizza objects may contain attribute matching the pattern - *custom::\** of any type. - -Valid types for type rules include: \* any \* number \* string \* scalar -(an alias for string) \* dictionary diff --git a/docs/icinga2-config-types.md b/docs/icinga2-config-types.md deleted file mode 100644 index d687bb466..000000000 --- a/docs/icinga2-config-types.md +++ /dev/null @@ -1,994 +0,0 @@ -Configuration Format -==================== - -Object Definition ------------------ - -Icinga 2 features an object-based configuration format. In order to -define objects the "object" keyword is used: - - object Host "host1.example.org" { - alias = "host1", - - check_interval = 30, - retry_interval = 15, - - macros = { - address = "192.168.0.1" - } - } - -> **Note** -> -> The Icinga 2 configuration format is agnostic to whitespaces and -> new-lines. - -Each object is uniquely identified by its type ("Host") and name -("host1.example.org"). Objects can contain a comma-separated list of -property declarations. The following data types are available for -property values: - -### Numeric Literals - -A floating-point number. - -Example: - - -27.3 - -### Duration Literal - -Similar to floating-point numbers except for that fact that they support -suffixes to help with specifying time durations. - -Example: - - 2.5m - -Supported suffixes include ms (milliseconds), s (seconds), m (minutes) -and h (hours). - -### String Literals - -A string. No escape characters are supported at present though this will -likely change. - -Example: - - "Hello World!" - -### Expression List - -A list of expressions that when executed has a dictionary as a result. - -Example: - - { - address = "192.168.0.1", - 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. - -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 "=" - -Sets a dictionary element to the specified value. - -Example: - - { - a = 5, - a = 7 - } - -In this example a has the value 7 after both instructions are executed. - -### Operator "+=" - -Modifies a dictionary by adding new elements to it. - -Example: - - { - a = { "hello" }, - a += { "world" } - } - -In this example a contains both "hello" and "world". This currently only -works for expression lists. Support for numbers might be added later on. - -### Operator "-=" - -Removes elements from a dictionary. - -Example: - - { - a = { "hello", "world" }, - a -= { "world" } - } - -In this example a contains "hello". Trying to remove an item that does -not exist is not an error. Not implemented yet. - -### Operator "\*=" - -Multiplies an existing dictionary element with the specified number. If -the dictionary element does not already exist 0 is used as its value. - -Example: - - { - a = 60, - a *= 5 - } - -In this example a is 300. This only works for numbers. Not implemented -yet. - -### Operator "/=" - -Divides an existing dictionary element by the specified number. If the -dictionary element does not already exist 0 is used as its value. - -Example: - - { - a = 300, - a /= 5 - } - -In this example a is 60. This only works for numbers. Not implemented -yet. - -Attribute Shortcuts -------------------- - -### Value Shortcut - -Example: - - { - "hello", "world" - } - -This is equivalent to writing: - - { - _00000001 = "hello", _00000002 = "world" - } - -The item’s keys are monotonically increasing and the config compiler -takes care of ensuring that all keys are unique (even when adding items -to an existing attribute using +=). - -### Indexer Shortcut - -Example: - - { - hello["key"] = "world" - } - -This is equivalent to writing: - - { - hello += { - key = "world" - } - } - -Specifiers ----------- - -Objects can have specifiers that have special meaning. The following -specifiers can be used (before the "object" keyword): - -### Specifier "abstract" - -This specifier identifies the object as a template which can be used by -other object definitions. The object will not be instantiated on its -own. - -Instead of using the "abstract" specifier you can use the "template" -keyword which is a shorthand for writing "abstract object": - - template Service "http" { - ... - } - -### Specifier "local" - -This specifier disables replication for this object. The object will not -be sent to remote Icinga instances. - -Inheritance ------------ - -Objects can inherit attributes from one or more other objects. - -Example: - - abstract object Host "default-host" { - check_interval = 30, - - macros = { - color = "red" - } - } - - abstract object Host "test-host" inherits "default-host" { - macros += { - color = "blue" - } - } - - object Host "localhost" inherits "test-host" { - macros += { - address = "127.0.0.1", - address6 = "::1" - } - } - -> **Note** -> -> The "default-host" and "test-host" objects are marked as templates -> using the "abstract" keyword. Parent objects do not necessarily have -> to be "abstract" though in general they are. - -> **Note** -> -> The += operator is used to insert additional properties into the -> macros dictionary. The final dictionary contains all 3 macros and the -> property "color" has the value "blue". - -Parent objects are resolved in the order they’re specified using the -"inherits" keyword. Parent objects must already be defined by the time -they’re used in an object definition. - -Comments --------- - -The Icinga 2 configuration format supports C/C++-style comments. - -Example: - - /* - This is a comment. - */ - object Host "localhost" { - check_interval = 30, // this is also a comment. - retry_interval = 15 - } - -Includes --------- - -Other configuration files can be included using the "\#include" -directive. Paths must be relative to the configuration file that -contains the "\#include" keyword: - -Example: - - #include "some/other/file.conf" - #include "conf.d/*.conf" - -Icinga also supports include search paths similar to how they work in a -C/C++ compiler: - - #include - -Note the use of angle brackets instead of double quotes. This causes the -config compiler to search the include search paths for the specified -file. By default \$PREFIX/icinga2 is included in the list of search -paths. - -Wildcards are not permitted when using angle brackets. - -Library directive ------------------ - -The "\#library" directive can be used to manually load additional -libraries. Upon loading these libraries may provide additional classes -or methods. - -Example: - - #library "snmphelper" - -> **Note** -> -> The "icinga" library is automatically loaded by Icinga. - -Type Definition ---------------- - -By default Icinga has no way of semantically verifying its configuration -objects. This is where type definitions come in. Using type definitions -you can specify which attributes are allowed in an object definition. - -Example: - - type Pizza { - %require "radius", - %attribute number "radius", - - %attribute dictionary "ingredients" { - %validator "ValidateIngredients", - - %attribute string "*", - - %attribute dictionary "*" { - %attribute number "quantity", - %attribute string "name" - } - }, - - %attribute any "custom::*" - } - -The Pizza definition provides the following validation rules: - -- Pizza objects must contain an attribute "radius" which has to be a - number. - -- Pizza objects may contain an attribute "ingredients" which has to be - a dictionary. - -- Elements in the ingredients dictionary can be either a string or a - dictionary. - -- If they’re a dictionary they may contain attributes "quantity" (of - type number) and "name" (of type string). - -- The script function "ValidateIngredients" is run to perform further - validation of the ingredients dictionary. - -- Pizza objects may contain attribute matching the pattern - "custom::\*" of any type. - -Valid types for type rules include: \* any \* number \* string \* scalar -(an alias for string) \* dictionary - -Configuration Objects -===================== - -Type: IcingaApplication ------------------------ - -The "IcingaApplication" type is used to specify global configuration -parameters for Icinga. There must be exactly one application object in -each Icinga 2 configuration. The object must have the "local" specifier. - -Example: - - local object IcingaApplication "icinga" { - cert_path = "my-cert.pem", - ca_path = "ca.crt", - - node = "192.168.0.1", - service = 7777, - - pid_path = "/var/run/icinga2.pid", - state_path = "/var/lib/icinga2/icinga2.state", - - macros = { - plugindir = "/usr/local/icinga/libexec" - } - } - -### Attribute: cert\_path - -This is used to specify the SSL client certificate Icinga 2 will use -when connecting to other Icinga 2 instances. This property is optional -when you’re setting up a non-networked Icinga 2 instance. - -### Attribute: ca\_path - -This is the public CA certificate that is used to verify connections -from other Icinga 2 instances. This property is optional when you’re -setting up a non-networked Icinga 2 instance. - -### Attribute: node - -The externally visible IP address that is used by other Icinga 2 -instances to connect to this instance. This property is optional when -you’re setting up a non-networked Icinga 2 instance. - -> **Note** -> -> Icinga does not bind to this IP address. - -### Attribute: service - -The port this Icinga 2 instance should listen on. This property is -optional when you’re setting up a non-networked Icinga 2 instance. - -### Attribute: pid\_path - -Optional. The path to the PID file. Defaults to "icinga.pid" in the -current working directory. - -### Attribute: state\_path - -Optional. The path of the state file. This is the file Icinga 2 uses to -persist objects between program runs. Defaults to "icinga2.state" in the -current working directory. - -### Attribute: macros - -Optional. Global macros that are used for service checks and -notifications. - -Type: Component ---------------- - -Icinga 2 uses a number of components to implement its feature-set. The -"Component" configuration object is used to load these components and -specify additional parameters for them. "Component" objects must have -the "local" specifier. The typical components to be loaded in the -default configuration would be "checker", "delegation" and more. - -Example "compat": - - local object Component "compat" { - status_path = "/var/cache/icinga2/status.dat", - objects_path = "/var/cache/icinga2/objects.cache", - } - -### Attribute: status\_path - -Specifies where Icinga 2 Compat component will put the status.dat file, -which can be read by Icinga 1.x Classic UI and other addons. If not set, -it defaults to the localstatedir location. - -### Attribute: objects\_path - -Specifies where Icinga 2 Compat component will put the objects.cache -file, which can be read by Icinga 1.x Classic UI and other addons. If -not set, it defaults to the localstatedir location. - -Type: ConsoleLogger -------------------- - -Specifies Icinga 2 logging to the console. Objects of this type must -have the "local" specifier. - -Example: - - local object ConsoleLogger "my-debug-console" { - severity = "debug" - } - -### Attribute: severity - -The minimum severity for this log. Can be "debug", "information", -"warning" or "critical". Defaults to "information". - -Type: FileLogger ----------------- - -Specifies Icinga 2 logging to a file. Objects of this type must have the -"local" specifier. - -Example: - - local object FileLogger "my-debug-file" { - severity = "debug", - path = "/var/log/icinga2/icinga2-debug.log" - } - -### Attribute: path - -The log path. - -### Attribute: severity - -The minimum severity for this log. Can be "debug", "information", -"warning" or "critical". Defaults to "information". - -Type: SyslogLogger ------------------- - -Specifies Icinga 2 logging to syslog. Objects of this type must have the -"local" specifier. - -Example: - - local object SyslogLogger "my-crit-syslog" { - severity = "critical" - } - -### Attribute: severity - -The minimum severity for this log. Can be "debug", "information", -"warning" or "critical". Defaults to "information". - -Type: Endpoint --------------- - -Endpoint objects are used to specify connection information for remote -Icinga 2 instances. Objects of this type should not be local: - - object Endpoint "icinga-c2" { - node = "192.168.5.46", - service = 7777, - } - -### Attribute: node - -The hostname/IP address of the remote Icinga 2 instance. - -### Attribute: service - -The service name/port of the remote Icinga 2 instance. - -Type: 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 = {2yy - plugindir = "/usr/lib/nagios/plugins", - address = "127.0.0.1", - community = "public", - } - } - -Type: NotificationCommand -------------------------- - -A notification command definition. - -Example: - - object NotificationCommand "mail-service-notification" inherits "plugin-notification-command" { - command = "/usr/bin/printf \"%b\" \"***** Icinga *****\n\nNotification Type: $NOTIFICATIONTYPE$\n\nService: $SERVICEDESC$\nHost: $HOSTALIAS$\nAddress: $HOSTADDRESS$\nState: $SERVICESTATE$\n\nDate/Time: $LONGDATETIME$\n\nAdditional Info: $SERVICEOUTPUT$\n\nComment: [$NOTIFICATIONAUTHORNAME$] $NOTIFICATIONCOMMENT$\n\n\" | /usr/bin/mail -s \"$NOTIFICATIONTYPE$ - $HOSTNAME$ - $SERVICEDESC$ - $SERVICESTATE$\" $CONTACTEMAIL$", - } - -Type: EventCommand - - An event command definition. - - NOTE: Similar to Icinga 1.x event handlers. - - Example: - - ------------------------------------------------------------------------------- - object EventCommand "restart-httpd-event" inherits "plugin-event-command" { - command = "/usr/local/icinga/libexec/restart-httpd.sh", - } - ------------------------------------------------------------------------------- - - - Type: Service - -Service objects describe network services and how they should be checked -by Icinga 2. - -> **Note** -> -> Better create a service template and use that reference on the host -> definition as shown below. - -Example: - - object Service "localhost-uptime" { - host_name = "localhost", - - alias = "localhost Uptime", - - methods = { - check = "PluginCheck" - }, - - check_command = "check_snmp", - - macros = { - plugindir = "/usr/lib/nagios/plugins", - address = "127.0.0.1", - community = "public", - oid = "DISMAN-EVENT-MIB::sysUpTimeInstance" - } - - check_interval = 60s, - retry_interval = 15s, - - servicegroups = { "all-services", "snmp" }, - - checkers = { "*" }, - } - -### Attribute: host\_name - -The host this service belongs to. There must be a "Host" object with -that name. - -### Attribute: alias - -Optional. A short description of the service. - -### Attribute: methods - check - -The check type of the service. For now only external check plugins are -supported ("PluginCheck"). - -### Attribute: check\_command - -Optional when not using the "external plugin" check type. The check -command. May contain macros. - -### Attribute: check\_interval - -Optional. The check interval (in seconds). - -### Attribute: retry\_interval - -Optional. The retry interval (in seconds). This is used when the service -is in a soft state. - -### Attribute: servicegroups - -Optional. The service groups this service belongs to. - -### Attribute: checkers - -Optional. A list of remote endpoints that may check this service. -Wildcards can be used here. - -Type: ServiceGroup ------------------- - -A group of services. - -Example: - - object ServiceGroup "snmp" { - alias = "SNMP services", - - custom = { - notes_url = "http://www.example.org/", - action_url = "http://www.example.org/", - } - } - -### Attribute: alias - -Optional. A short description of the service group. - -### Attribute: notes\_url - -Optional. Notes URL. Used by the CGIs. - -### Attribute: action\_url - -Optional. Action URL. Used by the CGIs. - -Type: Host ----------- - -A host. Unlike in Icinga 1.x hosts are not checkable objects in Icinga -2. - -Example: - - object Host "localhost" { - alias = "The best host there is", - - hostgroups = [ "all-hosts" ], - - hostcheck = "ping", - dependencies = [ "router-ping" ] - - services["ping"] = { templates = "ping" } - services["http"] = { - templates = "my-http", - macros = { - vhost = "test1.example.org", - port = 81 - } - } - - check_interval = 60m, - retry_interval = 15m, - - servicegroups = [ "all-services" ], - - checkers = { "*" }, - } - -### Attribute: alias - -Optional. A short description of the host. - -### Attribute: hostgroups - -Optional. A list of host groups this host belongs to. - -### Attribute: hostcheck - -Optional. A service that is used to determine whether the host is up or -down. - -### Attribute: hostdependencies - -Optional. A list of hosts that are used to determine whether the host is -unreachable. - -### Attribute: servicedependencies - -Optional. A list of services that are used to determine whether the host -is unreachable. - -### Attribute: services - -Inline definition of services. Each service name is defined in square -brackets and got its own dictionary with attribute properties, such as -the template service being used. All other service-related properties -are additively copied into the new service object. - -The new service’s name is "hostname-service" - where "service" is the -array key in the services array. - -The priority for service properties is (from highest to lowest): - -1. Properties specified in the dictionary of the inline service - definition - -2. Host properties - -3. Properties inherited from the new service’s parent object - -### Attribute: check\_interval - -Optional. Copied into inline service definitions. The host itself does -not have any checks. - -### Attribute: retry\_interval - -Optional. Copied into inline service definitions. The host itself does -not have any checks. - -### Attribute: servicegroups - -Optional. Copied into inline service definitions. The host itself does -not have any checks. - -### Attribute: checkers - -Optional. Copied into inline service definitions. The host itself does -not have any checks. - -Type: HostGroup ---------------- - -A group of hosts. - -Example - - object HostGroup "my-hosts" { - alias = "My hosts", - - notes_url = "http://www.example.org/", - action_url = "http://www.example.org/", - } - -### Attribute: alias - -Optional. A short description of the host group. - -### Attribute: notes\_url - -Optional. Notes URL. Used by the CGIs. - -### Attribute: action\_url - -Optional. Action URL. Used by the CGIs. - -Type: PerfdataWriter --------------------- - -Write check result performance data to a defined path using macro -pattern. - -Example - - local object PerfdataWriter "pnp" { - perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata", - format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$TIMET$\tHOSTNAME::$HOSTNAME$\tSERVICEDESC::$SERVICEDESC$\tSERVICEPERFDATA::$SERVICEPERFDATA$\tSERVICECHECKCOMMAND::$SERVICECHECKCOMMAND$\tHOSTSTATE::$HOSTSTATE$\tHOSTSTATETYPE::$HOSTSTATETYPE$\tSERVICESTATE::$SERVICESTATE$\tSERVICESTATETYPE::$SERVICESTATETYPE$", - rotation_interval = 15s, - } - -### Attribute: perfdata\_path - -Path to the service perfdata file. - -> **Note** -> -> Will be automatically rotated with timestamp suffix. - -### Attribute: format\_template - -Formatting of performance data output for graphing addons or other post -processing. - -### Attribute: rotation\_interval - -Rotation interval for the file defined in *perfdata\_path*. - -Type: IdoMySqlConnection ------------------------- - -IDO DB schema compatible output into mysql database. - -Example - - library "ido_mysql" - local object IdoMysqlDbConnection "mysql-ido" { - host = "127.0.0.1", - port = "3306", - user = "icinga", - password = "icinga", - database = "icinga", - table_prefix = "icinga_", - instance_name = "icinga2", - instance_description = "icinga2 dev instance" - } - -### Attribute: host - -MySQL database host address. Default is *localhost*. - -### Attribute: port - -MySQL database port. Default is *3306*. - -### Attribute: user - -MySQL database user with read/write permission to the icinga database. -Default is *icinga*. - -### Attribute: password - -MySQL database user’s password. Default is *icinga*. - -### Attribute: database - -MySQL database name. Default is *icinga*. - -### Attribute: table\_prefix - -MySQL database table prefix. Default is *icinga\_*. - -### Attribute: instance\_name - -Unique identifier for the local Icinga 2 instance. - -### Attribute: instance\_description - -Optional. Description for the Icinga 2 instance. - -Type: LiveStatusComponent -------------------------- - -Livestatus api interface available as tcp or unix socket. - -Example - - library "livestatus" - - local object LivestatusComponent "livestatus-tcp" { - socket_type = "tcp", - host = "127.0.0.1", - port = "6558" - } - - local object LivestatusComponent "livestatus-unix" { - socket_type = "unix", - socket_path = "/var/run/icinga2/livestatus" - } - -### Attribute: socket\_type - -*tcp* or *unix* socket. Default is *unix*. - -> **Note** -> -> *unix* sockets are not supported on Windows. - -### Attribute: host - -Only valid when socket\_type="tcp". Host address to listen on for -connections. - -### Attribute: port - -Only valid when socket\_type="tcp". Port to listen on for connections. - -### Attribute: socket\_path - -Only valid when socket\_type="unix". Local unix socket file. Not -supported on Windows. - -Configuration Examples -====================== - -Non-networked minimal example ------------------------------ - -> **Note** -> -> Icinga 2 ITL provides itl/standalone.conf which loads all required -> components, as well as itl/itl.conf includes many object templates -> already for an easy start with Icinga 2. - - local object IcingaApplication "icinga" { - - } - - local object Component "checker" { - - } - - local object Component "delegation" { - - } - - object CheckCommand "ping" { - command = "$plugindir$/check_ping -H $address$ -w $wrta$,$wpl$% -c $crta$,$cpl$%", - } - - template Service "icinga-service" { - methods = { - check = "PluginCheck" - }, - - macros = { - plugindir = "/usr/lib/nagios/plugins" - } - } - - template Service "ping-tmpl" inherits "icinga-service" { - check_command = "ping", - macros += { - wrta = 50, - wpl = 5, - crta = 100, - cpl = 10 - } - } - - object Host "localhost" { - services["ping"] = { templates = "ping-tmpl" }, - - macros = { - address = "127.0.0.1" - }, - - check_interval = 10m - } - -> **Note** -> -> You may also want to load the "compat" component if you want Icinga 2 -> to write status.dat and objects.cache files. - -/\* vim: set syntax=asciidoc filetype=asciidoc: \*/ diff --git a/docs/icinga2-config.md b/docs/icinga2-config.md deleted file mode 100644 index b6d52b49b..000000000 --- a/docs/icinga2-config.md +++ /dev/null @@ -1,76 +0,0 @@ -Configuration Introduction -========================== - -In Icinga 2 configuration is based on objects. There’s no difference in -defining global settings for the core application or for a specific -runtime configuration object. - -There are different types for the main application, its components and -tools. The runtime configuration objects such as hosts, services, etc -are defined using the same syntax. - -Each configuration object must be unique by its name. Otherwise Icinga 2 -will bail early on verifying the parsed configuration. - -Main Configuration -================== - -Starting Icinga 2 requires the main configuration file called -"icinga2.conf". That’s the location where everything is defined or -included. Icinga 2 will only know the content of that file and included -configuration file snippets. - - # /usr/bin/icinga2 -c /etc/icinga2/icinga2.conf - -> **Note** -> -> You can use just the main configuration file and put everything in -> there. Though that is not advised because configuration may be -> expanded over time. Rather organize runtime configuration objects into -> their own files and/or directories and include that in the main -> configuration file. - -Configuration Syntax -==================== - -/\* TODO \*/ - -Details on the syntax can be found in the chapter -icinga2-config-syntax.html[Configuration Syntax] - -Configuration Types -=================== - -/\* TODO \*/ - -Details on the available types can be found in the chapter -icinga2-config-types.html[Configuration Types] - -Configuration Templates -======================= - -Icinga 2 ships with the **Icinga Template Library (ITL)**. This is a set -of predefined templates and definitions available in your actual -configuration. - -> **Note** -> -> Do not change the ITL’s files. They will be overridden on upgrade. -> Submit a patch upstream or include your very own configuration -> snippet. - -Include the basic ITL set in your main configuration like - - include - -> **Note** -> -> Icinga 2 recognizes the ITL’s installation path and looks for that -> specific file then. - -Having Icinga 2 installed in standalone mode make sure to include -itl/standalone.conf as well (see sample configuration). - - include - -/\* vim: set syntax=asciidoc filetype=asciidoc: \*/ diff --git a/docs/icinga2-install.md b/docs/icinga2-install.md deleted file mode 100644 index ef05fcd43..000000000 --- a/docs/icinga2-install.md +++ /dev/null @@ -1,72 +0,0 @@ -Requirements -============ - -Packages -======== - -> **Note** -> -> Use packages whenever possible. - - ------------------------------------ ------------------------------------ - Distribution Package URL - Debian TBD - RHEL/CentOS TBD - SLES TBD - ------------------------------------ ------------------------------------ - -In case you’re running a distribution for which Icinga 2 packages are -not yet available download the source tarball and jump to Source Builds. - -Windows Installer -================= - -TODO - -Source Builds -============= - -Download the source tarball and read the *INSTALL* file for details and -requirements. - -Linux Builds ------------- - -Building from source on specific linux distributions is described on the -wiki: -[https://wiki.icinga.org/display/icinga2/Linux+Builds](https://wiki.icinga.org/display/icinga2/Linux+Builds) - -Windows Builds --------------- - -Icinga 2 ships a MS Visual Studio solution file. Requirements and -compilation instructions can be found on the wiki: -[https://wiki.icinga.org/display/icinga2/Windows+Builds](https://wiki.icinga.org/display/icinga2/Windows+Builds) - -Installation Locations -====================== - - ------------------------------------ ------------------------------------ - Path Description - - /etc/icinga2 Contains Icinga 2 configuration - files. - - /etc/init.d/icinga2 The Icinga 2 init script. - - /usr/share/doc/icinga2 Documentation files that come with - Icinga 2. - - /usr/share/icinga2/itl The Icinga Template Library. - - /var/run/icinga2 Command pipe and PID file. - - /var/cache/icinga2 Performance data files and - status.dat/objects.cache. - - /var/lib/icinga2 The Icinga 2 state file. - ------------------------------------ ------------------------------------ - -/\* TODO \*/ - -/\* vim: set syntax=asciidoc filetype=asciidoc: \*/ diff --git a/docs/icinga2-intro.md b/docs/icinga2-intro.md deleted file mode 100644 index 62037ce37..000000000 --- a/docs/icinga2-intro.md +++ /dev/null @@ -1,268 +0,0 @@ -Icinga 2 is a network monitoring application that tries to improve upon -the success of Icinga 1.x while fixing some of its shortcomings. A few -frequently encountered issues are: - -- Scalability problems in large monitoring setups - -- Difficult configuration with dozens of "magic" tweaks and several - ways of defining services - -- Code quality and the resulting inability to implement changes - without breaking add-ons - -- Limited access to the runtime state of Icinga (e.g. for querying a - service’s state or for dynamically creating new services) - -Fixing these issues would involve major breaking changes to the Icinga -1.x core and configuration syntax. Icinga users would likely experience -plenty of problems with the Icinga versions introducing these changes. -Many of these changes would likely break add-ons which rely on the NEB -API and other core internals. - -From a developer standpoint this may be justifiable in order to get to a -better end-product. However, for (business) users spending time on -getting familiar with these changes for each new version may become -quite frustrating and may easily cause users to lose their confidence in -Icinga. - -Nagios™ 4 is currently following this approach and it remains to be seen -how this fares with its users. - -Instead the Icinga project will maintain two active development -branches. There will be one branch for Icinga 1.x which focuses on -improving the existing Icinga 1.x code base - just like it has been done -so far. - -Independently from Icinga 1.x development on Icinga 2 will happen in a -separate branch and some of the long-term design goals will be outlined -in this document. Status updates for Icinga 2 will be posted on the -project website (www.icinga.org) as they become available. - -Code Quality -============ - -Icinga 2 will not be using any code from the Icinga 1.x branch due to -the rampant code quality issues with the existing code base. However, an -important property of the Icinga development process has always been to -rely on proven technologies and Icinga 2 will be no exception. - -A lot of effort has gone into designing a maintainable architecture for -Icinga 2 and making sure that algorithmic choices are in alignment with -our scalability goals for Icinga 2. - -There are plans to implement unit tests for most Icinga 2 features in -order to make sure that changes to the code base do not break things -that were known to work before. - -Language Choice -=============== - -Icinga 1.x is written in C and while in general C has quite a number of -advantages (e.g. performance and relatively easy portability to other -\*NIX- based platforms) some of its disadvantages show in the context of -a project that is as large as Icinga. - -With a complex software project like Icinga an object-oriented design -helps tremendously with keeping things modular and making changes to the -existing code easier. - -While it is true that you can write object-oriented software in C (the -Linux kernel is one of the best examples of how to do that) a truly -object-oriented language makes the programmers' life just a little bit -easier. - -For Icinga 2 we have chosen C++ as the main language. This decision was -influenced by a number of criteria including performance, support on -different platforms and general user acceptability. - -In general there is nothing wrong with other languages like Java, C\# or -Python; however - even when ignoring technical problems for just a -moment - in a community as conservative as the monitoring community -these languages seem out of place. - -Knowing that users will likely want to run Icinga 2 on older systems -(which are still fully vendor-supported even for years to come) we will -make every effort to ensure that Icinga 2 can be built and run on -commonly used operating systems and refrain from using new and exotic -features like C++11. - -Unlike Icinga 1.x there will be Windows support for Icinga 2. Some of -the compatibility features (e.g. the command pipe) which rely on \*NIX -features may not be supported on Windows but all new features will be -designed in such a way as to support \*NIX as well as Windows. - -Configuration -============= - -Icinga 1.x has a configuration format that is fully backwards-compatible -to the Nagios™ configuration format. This has the advantage of allowing -users to easily upgrade their existing Nagios™ installations as well as -downgrading if they choose to do so (even though this is generally not -the case). - -The Nagios™ configuration format has evolved organically over time and -for the most part it does what it’s supposed to do. However this -evolutionary process has brought with it a number of problems that make -it difficult for new users to understand the full breadth of available -options and ways of setting up their monitoring environment. - -Experience with other configuration formats like the one used by Puppet -has shown that it is often better to have a single "right" way of doing -things rather than having multiple ways like Nagios™ does (e.g. defining -host/service dependencies and parent/child relationships for hosts). - -Icinga 2 tries to fix those issues by introducing a new object-based -configuration format that is heavily based on templates and supports -user-friendly features like freely definable macros. - -External Interfaces -=================== - -While Icinga 1.x has easily accessible interfaces to its internal state -(e.g. status.dat, objects.cache and the command pipe) there is no -standards-based way of getting that information. - -For example, using Icinga’s status information in a custom script -generally involves writing a parser for the status.dat format and there -are literally dozens of Icinga-specific status.dat parsers out there. - -While Icinga 2 will support these legacy interfaces in order to make -migration easier and allowing users to use the existing CGIs and -whatever other scripts they may have Icinga 2 will focus on providing a -unified interface to Icinga’s state and providing similar functionality -to that provided by the command pipe in Icinga 1.x. The exact details -for such an interface are yet to be determined but this will likely be -an RPC interface based on one of the commonly used web-based remoting -technologies. - -Icinga 1.x exports historical data using the IDO database interface -(Icinga Data Output). Icinga 2 will support IDO in a -backwards-compatible fashion in order to support icinga-web. -Additionally there will be a newly-designed backend for historical data -which can be queried using the built-in API when available. Effort will -be put into making this new data source more efficient for use with SLA -reporting. - -Icinga 2 will also feature dynamic reconfiguration using the API which -means users can create, delete and update any configuration object (e.g. -hosts and services) on-the-fly. Based on the API there are plans to -implement a command-line configuration tool similar to what Pacemaker -has with "crm". Later on this API may also be used to implement -auto-discovery for new services. - -The RPC interface may also be used to receive events in real-time, e.g. -when service checks are being executed or when a service’s state -changes. Some possible uses of this interface would be to export -performance data for services (RRD, graphite, etc.) or general log -information (logstash, graylog2, etc.). - -Checks -====== - -In Icinga 2 services are the only checkable objects. Hosts only have a -calculated state and no check are ever run for them. - -In order to maintain compatibility with the hundreds of existing check -plugins for Icinga 1.x there will be support for Nagios™-style checks. -The check interface however will be modular so that support for other -kinds of checks can be implemented later on (e.g. built-in checks for -commonly used services like PING, HTTP, etc. in order to avoid spawning -a process for each check). - -Based on the availability of remote Icinga 2 instances the core can -delegate execution of service checks to them in order to support -large-scale distributed setups with a minimal amount of maintenance. -Services can be assigned to specific check instances using configuration -settings. - -Notifications -============= - -Event handlers and notifications will be supported similar to Icinga -1.x. Thanks to the dynamic configuration it is possible to easily adjust -the notification settings at runtime (e.g. in order to implement on-call -rotation). - -Scalability -=========== - -Icinga 1.x has some serious scalability issues which explains why there -are several add-ons which try to improve the core’s check performance. -One of these add-ons is mod\_gearman which can be used to distribute -checks to multiple workers running on remote systems. - -A problem that remains is the performance of the core when processing -check results. Scaling Icinga 1.x beyond 25.000 services proves to be a -challenging problem and usually involves setting up a cascade of Icinga -1.x instances and dividing the service checks between those instances. -This significantly increases the maintenance overhead when updating the -configuration for such a setup. - -Icinga 2 natively supports setting up multiple Icinga 2 instances in a -cluster to distribute work between those instances. Independent tasks -(e.g. performing service checks, sending notifications, updating the -history database, etc.) are implemented as components which can be -loaded for each instance. Configuration as well as program state is -automatically replicated between instances. - -In order to support using Icinga 2 in a partially trusted environment -SSL is used for all network communication between individual instances. -Objects (like hosts and services) can be grouped into security domains -for which permissions can be specified on a per-instance basis (so e.g. -you can have a separate API or checker instance for a specific domain). - -Agent-based Checks -================== - -Traditionally most service checks have been performed actively, meaning -that check plugins are executed on the same server that is also running -Icinga. This works great for checking most network-based services, e.g. -PING and HTTP. However, there are a number of services which cannot be -checked remotely either because they are not network-based or because -firewall settings or network policies ("no unencrypted traffic") -disallow accessing these services from the network where Icinga is -running. - -To solve this problem two add-ons have emerged, namely NRPE and NSCA. -NRPE can be thought of as a light-weight remote shell which allows the -execution of a restricted set of commands while supporting some -Nagios™-specific concepts like command timeouts. However unlike with the -design of commonly used protocols like SSH security in NRPE is merely an -afterthought. - -In most monitoring setups all NRPE agents share the same secret key -which is embedded into the NRPE binary at compile time. This means that -users can extract this secret key from their NRPE agent binary and use -it to query sensitive monitoring information from other systems running -the same NRPE binary. NSCA has similar problems. - -Based on Icinga 2’s code for check execution there will be an agent -which can be used on \*NIX as well as on Windows platforms. The agent -will be using the same configuration format like Icinga 2 itself and -will support SSL and IPv4/IPv6 to communicate with Icinga 2. - -Business Processes -================== - -In most cases users don’t care about the availability of individual -services but rather the aggregated state of multiple related services. -For example one might have a database cluster that is used for a web -shop. For an end-user the shop is available as long as at least one of -the database servers is working. - -Icinga 1.x does not have any support for business processes out of the -box. There are several add-ons which implement business process support -for Icinga, however none of those are well-integrated into Icinga. - -Icinga 2 will have native support for business processes which are built -right into the core and can be configured in a similar manner to -Nagios™-style checks. Users can define their own services based on -business rules which can be used as dependencies for other hosts or -services. - -Logging -======= - -Icinga 2 supports file-based logged as well as syslog (on \*NIX) and -event log (on Windows). Additionally Icinga 2 supports remote logging to -a central Icinga 2 instance. diff --git a/docs/icinga2-main.md b/docs/icinga2-main.md deleted file mode 100644 index 03bc422c1..000000000 --- a/docs/icinga2-main.md +++ /dev/null @@ -1,56 +0,0 @@ -Introduction -============ - -A detailed introduction can be found in the chapter -[Introduction](icinga2-intro.html). /\* TODO insert url \*/ - -Installation -============ - -For more information see the chapter Installation. /\* TODO insert url -\*/ - -Quick Example -============= - -/\* TODO \*/ - -For a general tutorial see the chapter -[Tutorial](icinga2-tutorial.html). /\* TODO insert url \*/ - -Requirements -============ - -/\* TODO \*/ - -License -======= - -Icinga 2 is licensed under the GPLv2 license, a copy of this license can -be found in the LICENSE file on the main source tree. - -Community -========= - -- [\#icinga](http://webchat.freenode.net/?channels=icinga) on the - Freenode IRC Network - -- [Mailinglists](https://lists.sourceforge.net/lists/listinfo/icinga-users) - -- [Monitoring Portal](http://www.monitoring-portal.org) - -More details at -[http://www.icinga.org/support/](http://www.icinga.org/support/) - -Support -======= - -For more information on the support options refer to -[https://www.icinga.org/support](https://www.icinga.org/support) - -Chapters -======== - -/\* TODO \*/ - -/\* vim: set syntax=asciidoc filetype=asciidoc: \*/ diff --git a/docs/icinga2-migration.md b/docs/icinga2-migration.md deleted file mode 100644 index c9d403520..000000000 --- a/docs/icinga2-migration.md +++ /dev/null @@ -1,36 +0,0 @@ -Purpose -======= - -Documentation on the general migration from Icinga 1.x to Icinga 2. - -Requirements -============ - -Multi-core cpu, ram, fast disks. - -Installation -============ - -Icinga 1.x and Icinga 2 may run side by side, but it’s recommended to -backup your existing 1.x installation before installing Icinga 2 on the -same host. - -Compatibility -============= - -> **Note** -> -> The configuration format changed from 1.x to 2.x. Don’t panic though. -> A conversion script is shipped in *tools/configconvert* - please check -> the *README* file. - -For details check the chapter [Compatibility](icinga2-compat.html). - -Changes -======= - -For details check the chapter [Changes](icinga2-compat.html). - -TODO - -/\* vim: set syntax=asciidoc filetype=asciidoc: \*/ diff --git a/docs/icinga2-tutorial.md b/docs/icinga2-tutorial.md deleted file mode 100644 index 41557b56a..000000000 --- a/docs/icinga2-tutorial.md +++ /dev/null @@ -1,811 +0,0 @@ -Preface -======= - -This tutorial is a step-by-step introduction to installing Icinga 2 and -setting up your first couple of service checks. It assumes some -familiarity with Icinga 1.x. - -Installation -============ - -In order to get started with Icinga 2 we will have to install it. The -preferred way of doing this is to use the official Debian or RPM -packages depending on which Linux distribution you are running. - - ------------------------------------ ------------------------------------ - Distribution Package URL - - Debian [http://icingabuild.dus.dg-i.net:808 - 0/job/icinga2/](http://icingabuild.d - us.dg-i.net:8080/job/icinga2/) - - RHEL TBD - ------------------------------------ ------------------------------------ - -In case you’re running a distribution for which Icinga 2 packages are -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. - -By default Icinga 2 uses the following files and directories: - - ------------------------------------ ------------------------------------ - Path Description - - /etc/icinga2 Contains Icinga 2 configuration - files. - - /etc/init.d/icinga2 The Icinga 2 init script. - - /usr/share/doc/icinga2 Documentation files that come with - Icinga 2. - - /usr/share/icinga2/itl The Icinga Template Library. - - /var/run/icinga2 Command pipe and PID file. - - /var/cache/icinga2 Performance data files and - status.dat/objects.cache. - - /var/lib/icinga2 The Icinga 2 state file. - ------------------------------------ ------------------------------------ - -Our First Service Check -======================= - -The Icinga 2 package comes with a number of example configuration files. -However, in order to explain some of the basics we’re going write our -own configuration file from scratch. - -Start by creating the file /etc/icinga2/icinga2.conf with the following -content: - - include - include - - object IcingaApplication "my-icinga" { - macros["plugindir"] = "/usr/lib/nagios/plugins" - } - -The configuration snippet includes the *itl/itl.conf* and -*itl/standalone.conf* files which are distributed as part of Icinga 2. -We will discuss the Icinga Template Library (ITL) in more detail later -on. - -The *itl/standalone.conf* configuration file takes care of configuring -Icinga 2 for single-instance (i.e. non-clustered) mode. - -Our configuration file also creates an object of type -*IcingaApplication* with the name *my-icinga*. The *IcingaApplication* -type can be used to define global macros and some other global settings. - -For now we’re only defining the global macro *plugindir* which we’re -going to use later on when referring to the path which contains our -check plugins. Depending on where you’ve installed your check plugins -you may need to update this path in your configuration file. - -You can verify that your configuration file works by starting Icinga 2: - - $ /usr/bin/icinga2 -c /etc/icinga2/icinga2.conf - [2013/04/23 13:36:20 +0200]
information/icinga-app: Icinga application loader (version: 0.0.1, git branch master, commit 0fcbfdb2) - [2013/04/23 13:36:20 +0200]
information/base: Adding library search dir: /usr/lib/icinga2 - [2013/04/23 13:36:20 +0200]
information/base: Loading library 'libicinga.la' - [2013/04/23 13:36:20 +0200]
information/config: Adding include search dir: /usr/share/icinga2 - [2013/04/23 13:36:20 +0200]
information/config: Compiling config file: /etc/icinga2/icinga2.conf - [2013/04/23 13:36:20 +0200]
information/config: Linking config items... - [2013/04/23 13:36:20 +0200]
information/config: Validating config items... - [2013/04/23 13:36:20 +0200]
information/config: Activating config items in compilation unit 'b2d21c28-a2e8-4fcb-ba00-45646bc1afb9' - [2013/04/23 13:36:20 +0200]
information/base: Restoring program state from file '/var/lib/icinga2/icinga2.state' - [2013/04/23 13:36:20 +0200]
information/base: Restored 0 objects - -In case there are any configuration errors Icinga 2 should print error -messages containing details about what went wrong. - -You can stop Icinga 2 with Control-C: - - ^C - [2013/04/23 13:39:39 +0200] information/base: Shutting down Icinga... - [2013/04/23 13:39:39 +0200] information/base: Dumping program state to file '/var/lib/icinga2/icinga2.state' - [2013/04/23 13:39:39 +0200]
information/icinga: Icinga has shut down. - $ - -Icinga 2 automatically saves its current state every couple of minutes -and when it’s being shut down. - -So far our Icinga 2 setup doesn’t do much. Lets change that by setting -up a service check for localhost. Modify your *icinga2.conf* -configuration file by adding the following lines: - - object CheckCommand "my-ping" inherits "plugin-check-command" { - command = [ - "$plugindir$/check_ping", - "-H", "$address$", - "-w", "10,5%", - "-c", "25,10%" - ] - } - - template Service "my-ping" inherits "plugin-service" { - check_command = "my-ping" - } - - object Host "localhost" { - display_name = "Home, sweet home!", - - services["ping"] = { - templates = [ "my-ping" ] - }, - - macros = { - address = "127.0.0.1" - }, - - check_interval = 10s, - - hostcheck = "ping" - } - -We’re defining a command object called "my-ping" which inherits from the -*plugin-check-command* template. The *plugin-check-command* template is -provided as part of the Icinga Template Library and describes how checks -are performed. In the case of plugin-based services this means that the -command specified by the *command* property is executed. - -The *command* property is an array or command-line arguments for the -check plugin. Alternatively you can specify the check command as a -string. - -The check command can make use of macros. Unlike in Icinga 1.x we have -free-form macros which means that users can choose arbitrary names for -their macros. - -By convention the following macros are usually used: - - ------------------------------------ ------------------------------------ - Macro Description - plugindir The path of your check plugins. - address The IPv4 address of the host. - address6 The IPv6 address of the host. - ------------------------------------ ------------------------------------ - -Note that the *my-ping* command object does not define a value for the -*address* macro. This is perfectly fine as long as that macro is defined -somewhere else (e.g. in the host). - -We’re also defining a service template called *my-ping* which uses the -command object we just created. - -Next we’re defining a *Host* object called *localhost*. We’re setting an -optional display\_name which is used by the Icinga Classic UI when -showing that host in the host overview. - -The services dictionary defines which services belong to a host. Using -the [] indexing operator we can manipulate individual items in this -dictionary. In this case we’re creating a new service called *ping*. - -The templates array inside the service definition lists all the -templates we want to use for this particular service. For now we’re just -listing our *my-ping* template. - -Remember how we used the *address* macro in the *command* setting -earlier? Now we’re defining a value for this macro which is used for all -services and their commands which belong to the *localhost* Host object. - -We’re also setting the check\_interval for all services belonging to -this host to 10 seconds. - -> **Note** -> -> When you don’t specify an explicit time unit Icinga 2 automatically -> assumes that you meant seconds. - -And finally we’re specifying which of the services we’ve created before -is used to define the host’s state. Note that unlike in Icinga 1.x this -just "clones" the service’s state and does not cause any additional -checks to be performed. - -Setting up the Icinga 1.x 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 -"command pipe") are also supported. If you require the icinga.log for -history views and/or reporting in Classic UI, this can be added -seperately to the CompatComponent object definition by adding a -CompatLog object. - -In order to enable this feature you will need to load the library -*compat* by adding the following lines to your configuration file: - - library "compat" - - object CompatComponent "compat" { } - object CompatLog "my-log" { } - -After restarting Icinga 2 you should be able to find the status.dat and -objects.cache files in /var/cache/icinga2. The log files can be found in -/var/log/icinga2/compat. The command pipe can be found in -/var/run/icinga2. - -You can install the Icinga 1.x Classic UI in standalone mode using the -following commands: - - $ wget http://downloads.sourceforge.net/project/icinga/icinga/1.9.0/icinga-1.9.0.tar.gz - $ tar xzf icinga-1.9.0.tar.gz ; cd icinga-1.9.0 - $ ./configure --enable-classicui-standalone --prefix=/usr/local/icinga2-classicui - $ make classicui-standalone - $ sudo make install classicui-standalone install-webconf-auth - $ sudo service apache2 restart - -> **Note** -> -> A detailed guide on installing Icinga 1.x Classic UI Standalone can be -> 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) - -After installing the Classic UI you will need to update the following -settings in your cgi.cfg configuration file at the bottom (section -"STANDALONE (ICINGA 2) OPTIONS"): - - ------------------------------------ ------------------------------------ - Configuration Setting Value - object\_cache\_file /var/cache/icinga2/objects.cache - status\_file /var/cache/icinga2/status.dat - resource\_file - - command\_file /var/run/icinga2/icinga2.cmd - check\_external\_commands 1 - interval\_length 60 - status\_update\_interval 10 - log\_file /var/log/icinga2/compat/icinga.log - log\_rotation\_method h - log\_archive\_path /var/log/icinga2/compat/archives - date\_format us - ------------------------------------ ------------------------------------ - -Depending on how you installed Icinga 2 some of those paths and options -might be different. - -> **Note** -> -> You need to grant permissions for the apache user manually after -> starting Icinga 2 for now. - - # chmod o+rwx /var/run/icinga2/{icinga2.cmd,livestatus} - -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) - -Some More Templates -=================== - -Now that we’ve got our basic monitoring setup as well as the Icinga 1.x -Classic UI to work we can define a second host. Add the following lines -to your configuration file: - - object Host "icinga.org" { - display_name = "Icinga Website", - - services["ping"] = { - templates = [ "my-ping" ] - }, - - macros = { - address = "www.icinga.org" - }, - - check_interval = 10s, - - hostcheck = "ping" - } - -Restart your Icinga 2 instance and check the Classic UI for your new -service’s state. Unless you have a low-latency network connection you -will note that the service’s state is *CRITICAL*. This is because in the -*my-ping* command object we have hard-coded the timeout as 25 -milliseconds. - -Ideally we’d be able to specify different timeouts for our new service. -Using macros we can easily do this. - -> **Note** -> -> If you’ve used Icinga 1.x before you’re probably familiar with doing -> this by passing ARGx macros to your check commands. - -Start by replacing your *my-ping* command object with this: - - object CheckCommand "my-ping" inherits "plugin-check-command" { - command = [ - "$plugindir$/check_ping", - "-H", "$address$", - "-w", "$wrta$,$wpl$%", - "-c", "$crta$,$cpl$%" - ], - - macros = { - wrta = 10, - wpl = 5, - - crta = 25, - cpl = 10 - } - } - -We have replaced our hard-coded timeout values with macros and we’re -providing default values for these same macros right in the template -definition. The object inherits the basic check command attributes from -the ITL provided template *plugin-check-command*. - -In order to oderride some of these macros for a specific host we need to -update our *icinga.org* host definition like this: - - object Host "icinga.org" { - display_name = "Icinga Website", - - services["ping"] = { - templates = [ "my-ping" ], - - macros += { - wrta = 100, - crta = 250 - } - }, - - macros = { - address = "www.icinga.org" - }, - - check_interval = 10s, - - hostcheck = "ping" - } - -The *+=* operator allows us to selectively add new key-value pairs to an -existing dictionary. If we were to use the *=* operator instead we would -have to provide values for all the macros that are used in the *my-ping* -template overriding all values there. - -Icinga Template Library -======================= - -The Icinga Template Library is a collection of configuration templates -for commonly used services. By default it is installed in -*/usr/share/icinga2/itl* and you can include it in your configuration -files using the include directive: - - include - -> **Note** -> -> Ordinarily you’d use double-quotes for the include path. This way only -> paths relative to the current configuration file are considered. The -> angle brackets tell Icinga 2 to search its list of global include -> directories. - -One of the templates in the ITL is the *ping4* service template which is -quite similar to our example objects: - - object CheckCommand "ping4" inherits "plugin-check-command" { - command = [ - "$plugindir$/check_ping", - "-4", - "-H", "$address$", - "-w", "$wrta$,$wpl$%", - "-c", "$crta$,$cpl$%", - "-p", "$packets$", - "-t", "$timeout$" - ], - - macros = { - wrta = 100, - wpl = 5, - - crta = 200, - cpl = 15, - - packets = 5, - timeout = 0 - } - } - - template Service "ping4" { - check_command = "ping4" - } - -Lets simplify our configuration file by removing our custom *my-ping* -template and updating our service definitions to use the *ping4* -template instead. - -Include Files -============= - -So far we’ve been using just one configuration file. However, once -you’ve created a few more host objects and service templates this can -get rather confusing. - -Icinga 2 lets you include other files from your configuration file. We -can use this feature to make our configuration a bit more modular and -easier to understand. - -Lets start by moving our two *Host* objects to a separate configuration -file: hosts.conf - -We will also need to tell Icinga 2 that it should include our newly -created configuration file when parsing the main configuration file. -This can be done by adding the include directive to our *icinga2.conf* -file: - - include "hosts.conf" - -Depending on the number of hosts you have it might be useful to split -your configuration files based on other criteria (e.g. device type, -location, etc.). - -You can use wildcards in the include path in order to refer to multiple -files. Assuming you’re keeping your host configuration files in a -directory called *hosts* you could include them like this: - - include "hosts/*.conf" - -Notifications -============= - -Icinga 2 can send you notifications when your services change state. In -order to do this we’re going to write a shell script in -*/etc/icinga2/mail-notification.sh* that sends e-mail based -notifications: - - #!/bin/sh - - if [ -z "$1" ]; then - echo "Syntax: $0 " - echo - echo "Sends a mail notification to the specified e-mail address." - exit 1 - fi - - mail -s "** $NOTIFICATIONTYPE Service Alert: $HOSTALIAS/$SERVICEDESC is $SERVICESTATE **" $1 < **Note** -> -> Rather than adding these templates to your main configuration file you -> might want to create a separate file, e.g. *notifications.conf* and -> include it in *icinga2.conf*. - -The *export\_macros* property tells Icinga which macros to export into -the environment for the notification script. - -We also need to create a *User* object which Icinga can use to send -notifications to specific people: - - object User "tutorial-user" { - display_name = "Some User", - - macros = { - email = "tutorial@example.org" - } - } - -Each time a notification is sent for a service the user’s macros are -used when resolving the macros we used in the *Notification* template. - -In the next step we’re going to create a *Service* template which -specifies who notifications should be sent to: - - template Service "mail-notification-service" { - notifications["mail"] = { - templates = [ "mail-notification" ], - - users = [ "tutorial-user" ] - }, - - notification_interval = 1m - } - -And finally we can assign this new service template to our services: - - ... - services["ping"] = { - templates = [ "ping4", "mail-notification-service" ] - }, - ... - -In addition to defining notifications for individual services it is also -possible to assign notification templates to all services of a host. You -can find more information about how to do that in the documentation. - -> **Note** -> -> Escalations in Icinga 2 are just a notification, only added a defined -> begin and end time. Check the documentation for details. - -Time Periods -============ - -Time periods allow you to specify when certain services should be -checked and when notifications should be sent. - -Here is an example time period definition: - - object TimePeriod "work-hours" inherits "legacy-timeperiod" { - ranges = { - monday = "9:00-17:00", - tuesday = "9:00-17:00", - wednesday = "9:00-17:00", - thursday = "9:00-17:00", - friday = "9:00-17:00", - } - } - -The *legacy-timeperiod* template is defined in the Icinga Template -Library and supports Icinga 1.x time periods. A complete definition of -the time Icinga 1.x time period syntax can be found at -[http://docs.icinga.org/latest/en/objectdefinitions.html\#timeperiod](http://docs.icinga.org/latest/en/objectdefinitions.html#timeperiod). - -Using the *check\_period* attribute you can define when services should -be checked: - - ... - services["ping"] = { - templates = [ "ping4", "mail-notification-service" ], - check_period = "work-hours" - }, - ... - -Also, using the *notification\_period* attribute you can define when -notifications should be sent: - - template Service "mail-notification-service" { - notifications["mail"] = { - templates = [ "mail-notification" ], - - users = [ "tutorial-user" ] - }, - - notification_interval = 1m, - notification_period = "work-hours" - } - -The *notification\_period* attribute is also valid in *User* and -*Notification* objects. - -Dependencies -============ - -If you are familiar with Icinga 1.x host/service dependencies and -parent/child relations on hosts, you might want to look at the -conversion script in order to convert your existing configuration. There -are no separate dependency objects anymore, and no separate parent -attribute either. - -Using Icinga 2, we can directly define a dependency in the current host -or service object to any other host or service object. If we want other -objects to inherit those dependency attributes, we can also define them -in a template. - -In the following example we’ve added a cluster host with the service -*ping* which we are going to define a dependency for in another host. - - template Service "my-cluster-ping" { - check_command = "my-ping", - } - - object Host "my-cluster" { - ... - services["ping"] = { - templates = [ "my-cluster-ping" ], - } - ... - } - -We can now define a service dependency as new service template (or -directly on the service definition): - - template Service "my-cluster-dependency" { - servicedependencies = [ - { host = "my-cluster", service = "ping" }, - ], - } - -Now let’s use that template for the *ping* service we’ve defined -previously and assign the servicedependencies to that service. - - ... - services["ping"] = { - templates = [ "ping4", "mail-notification-service", "my-cluster-dependency" ], - }, - ... - -Performance Data -================ - -Because there are no host checks in Icinga 2, the PerfdataWriter object -will only write service performance data files. Creating the object will -allow you to set the perfdata\_path, format\_template and -rotation\_interval. The format template is similar to existing Icinga -1.x configuration for PNP or inGraph using macro formatted strings. - -Details on the common Icinga 1.x macros can be found at -[http://docs.icinga.org/latest/en/macrolist.html](http://docs.icinga.org/latest/en/macrolist.html) - -> **Note** -> -> You can define multiple PerfdataWriter objects with different -> configuration settings, i.e. one for PNP, one for inGraph or your -> preferred graphite collector. - -Let’s create a new PNP PerfdataWriter object: - - object PerfdataWriter "pnp" { - perfdata_path = "/var/lib/icinga2/service-perfdata", - format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$TIMET$\tHOSTNAME::$HOSTNAME$\tSERVICEDESC::$SERVICEDESC$\tSERVICEPERFDATA::$SERVICEPERFDATA$\tSERVICECHECKCOMMAND::$SERVICECHECKCOMMAND$\tHOSTSTATE::$HOSTSTATE$\tHOSTSTATETYPE::$HOSTSTATETYPE$\tSERVICESTATE::$SERVICESTATE$\tSERVICESTATETYPE::$SERVICESTATETYPE$", - rotation_interval = 15s, - } - -You may need to reconfigure your NPCD daemon with the correct path for -your performance data files. This can be done in the PNP configuration -file npcd.cfg: - - perfdata_spool_dir = /var/lib/icinga2/ - -Livestatus Component -==================== - -The Livestatus component will provide access to Icinga 2 using the -livestatus api. In addition to the unix socket Icinga 2 also service -livestatus directly via tcp socket. - -> **Note** -> -> Only config and status tables are available at this time. History -> tables such as log, statehist will follow. - -Once Icinga 2 is started, configure your gui (e.g. Thruk) using the -livestatus backend. - -TCP Socket - - library "livestatus" - object LivestatusComponent "livestatus-tcp" { - socket_type = "tcp", - host = "10.0.10.18", - port = "6558" - } - -Unix Socket - - library "livestatus" - object LivestatusComponent "livestatus-unix" { - socket_type = "unix", - socket_path = "/var/run/icinga2/livestatus" - } - -> **Note** -> -> You need to grant permissions for the apache user manually after -> starting Icinga 2 for now. - - # chmod o+rwx /var/run/icinga2/{icinga2.cmd,livestatus} - -IDO Database Component -====================== - -The IDO component will write to the same database backend as known from -Icinga 1.x IDOUtils. Therefore you’ll need to have your database schema -and users already installed, like described in -[http://docs.icinga.org/latest/en/quickstart-idoutils.html\#createidoutilsdatabase](http://docs.icinga.org/latest/en/quickstart-idoutils.html#createidoutilsdatabase) - -> **Note** -> -> Currently there’s only MySQL support in progress, Postgresql, Oracle -> tbd. - -Configure the IDO MySQL component with the defined credentials and start -Icinga 2. - -> **Note** -> -> Make sure to define a unique instance\_name. That way the Icinga 2 IDO -> component will not interfere with your Icinga 1.x setup, if existing. - - library "ido_mysql" - object IdoMysqlDbConnection "my-ido-mysql" { - host = "127.0.0.1", - port = "3306", - user = "icinga", - password = "icinga", - database = "icinga", - table_prefix = "icinga_", - instance_name = "icinga2", - instance_description = "icinga2 instance" - } - -Starting Icinga 2 in debug mode in foreground using -x will show all -database queries. - -Custom Attributes -================= - -In Icinga 1.x there were so-called "custom variables" available prefixed -with an underscore, as well as plenty of other attributes such as -action\_url, notes\_url, icon\_image, etc. To overcome the limitations -of hardcoded custom attributes, Icinga 2 ships with the *custom* -attribute as dictionary. - -For example, if you have PNP installed we could add a reference url to -Icinga Classic UI by using the classic method of defining an -action\_url. - - template Service "my-pnp-svc" { - custom = { - action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$' class='tips' rel='/pnp4nagios/popup?host=$HOSTNAME$&srv=$SERVICEDESC$", - } - } - -And add that template again to our service definition: - - ... - services["ping"] = { - templates = [ "ping4", "mail-notification-service", "my-cluster-dependency", "my-pnp-svc" ], - }, - ... - -While at it, our configuration tool will add its LDAP DN and a snmp -community to the service too, using += for additive attributes: - - ... - services["ping"] = { - templates = [ "ping4", "mail-notification-service", "my-cluster-dependency", "my-pnp-svc" ], - custom += { - DN = "cn=icinga2-dev-svc,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org", - SNMPCOMMUNITY = "public" - } - }, - ... - -/\* vim: set syntax=asciidoc filetype=asciidoc: \*/ diff --git a/docs/icinga2.md b/docs/icinga2.md deleted file mode 100644 index e1c1c3be8..000000000 --- a/docs/icinga2.md +++ /dev/null @@ -1,2865 +0,0 @@ -Icinga 2 Main -============= - -Introduction ------------- - -A detailed introduction can be found in the chapter -[Introduction](icinga2-intro.html). /\* TODO insert url \*/ - -Installation ------------- - -For more information see the chapter Installation. /\* TODO insert url -\*/ - -Quick Example -------------- - -/\* TODO \*/ - -For a general tutorial see the chapter -[Tutorial](icinga2-tutorial.html). /\* TODO insert url \*/ - -Requirements ------------- - -/\* TODO \*/ - -License -------- - -Icinga 2 is licensed under the GPLv2 license, a copy of this license can -be found in the LICENSE file on the main source tree. - -Community ---------- - -- [\#icinga](http://webchat.freenode.net/?channels=icinga) on the - Freenode IRC Network - -- [Mailinglists](https://lists.sourceforge.net/lists/listinfo/icinga-users) - -- [Monitoring Portal](http://www.monitoring-portal.org) - -More details at -[http://www.icinga.org/support/](http://www.icinga.org/support/) - -Support -------- - -For more information on the support options refer to -[https://www.icinga.org/support](https://www.icinga.org/support) - -Chapters --------- - -/\* TODO \*/ - -/\* vim: set syntax=asciidoc filetype=asciidoc: \*/ - -Icinga 2 Introduction -===================== - -Icinga 2 is a network monitoring application that tries to improve upon -the success of Icinga 1.x while fixing some of its shortcomings. A few -frequently encountered issues are: - -- Scalability problems in large monitoring setups - -- Difficult configuration with dozens of "magic" tweaks and several - ways of defining services - -- Code quality and the resulting inability to implement changes - without breaking add-ons - -- Limited access to the runtime state of Icinga (e.g. for querying a - service’s state or for dynamically creating new services) - -Fixing these issues would involve major breaking changes to the Icinga -1.x core and configuration syntax. Icinga users would likely experience -plenty of problems with the Icinga versions introducing these changes. -Many of these changes would likely break add-ons which rely on the NEB -API and other core internals. - -From a developer standpoint this may be justifiable in order to get to a -better end-product. However, for (business) users spending time on -getting familiar with these changes for each new version may become -quite frustrating and may easily cause users to lose their confidence in -Icinga. - -Nagios™ 4 is currently following this approach and it remains to be seen -how this fares with its users. - -Instead the Icinga project will maintain two active development -branches. There will be one branch for Icinga 1.x which focuses on -improving the existing Icinga 1.x code base - just like it has been done -so far. - -Independently from Icinga 1.x development on Icinga 2 will happen in a -separate branch and some of the long-term design goals will be outlined -in this document. Status updates for Icinga 2 will be posted on the -project website (www.icinga.org) as they become available. - -Code Quality ------------- - -Icinga 2 will not be using any code from the Icinga 1.x branch due to -the rampant code quality issues with the existing code base. However, an -important property of the Icinga development process has always been to -rely on proven technologies and Icinga 2 will be no exception. - -A lot of effort has gone into designing a maintainable architecture for -Icinga 2 and making sure that algorithmic choices are in alignment with -our scalability goals for Icinga 2. - -There are plans to implement unit tests for most Icinga 2 features in -order to make sure that changes to the code base do not break things -that were known to work before. - -Language Choice ---------------- - -Icinga 1.x is written in C and while in general C has quite a number of -advantages (e.g. performance and relatively easy portability to other -\*NIX- based platforms) some of its disadvantages show in the context of -a project that is as large as Icinga. - -With a complex software project like Icinga an object-oriented design -helps tremendously with keeping things modular and making changes to the -existing code easier. - -While it is true that you can write object-oriented software in C (the -Linux kernel is one of the best examples of how to do that) a truly -object-oriented language makes the programmers' life just a little bit -easier. - -For Icinga 2 we have chosen C++ as the main language. This decision was -influenced by a number of criteria including performance, support on -different platforms and general user acceptability. - -In general there is nothing wrong with other languages like Java, C\# or -Python; however - even when ignoring technical problems for just a -moment - in a community as conservative as the monitoring community -these languages seem out of place. - -Knowing that users will likely want to run Icinga 2 on older systems -(which are still fully vendor-supported even for years to come) we will -make every effort to ensure that Icinga 2 can be built and run on -commonly used operating systems and refrain from using new and exotic -features like C++11. - -Unlike Icinga 1.x there will be Windows support for Icinga 2. Some of -the compatibility features (e.g. the command pipe) which rely on \*NIX -features may not be supported on Windows but all new features will be -designed in such a way as to support \*NIX as well as Windows. - -Configuration -------------- - -Icinga 1.x has a configuration format that is fully backwards-compatible -to the Nagios™ configuration format. This has the advantage of allowing -users to easily upgrade their existing Nagios™ installations as well as -downgrading if they choose to do so (even though this is generally not -the case). - -The Nagios™ configuration format has evolved organically over time and -for the most part it does what it’s supposed to do. However this -evolutionary process has brought with it a number of problems that make -it difficult for new users to understand the full breadth of available -options and ways of setting up their monitoring environment. - -Experience with other configuration formats like the one used by Puppet -has shown that it is often better to have a single "right" way of doing -things rather than having multiple ways like Nagios™ does (e.g. defining -host/service dependencies and parent/child relationships for hosts). - -Icinga 2 tries to fix those issues by introducing a new object-based -configuration format that is heavily based on templates and supports -user-friendly features like freely definable macros. - -External Interfaces -------------------- - -While Icinga 1.x has easily accessible interfaces to its internal state -(e.g. status.dat, objects.cache and the command pipe) there is no -standards-based way of getting that information. - -For example, using Icinga’s status information in a custom script -generally involves writing a parser for the status.dat format and there -are literally dozens of Icinga-specific status.dat parsers out there. - -While Icinga 2 will support these legacy interfaces in order to make -migration easier and allowing users to use the existing CGIs and -whatever other scripts they may have Icinga 2 will focus on providing a -unified interface to Icinga’s state and providing similar functionality -to that provided by the command pipe in Icinga 1.x. The exact details -for such an interface are yet to be determined but this will likely be -an RPC interface based on one of the commonly used web-based remoting -technologies. - -Icinga 1.x exports historical data using the IDO database interface -(Icinga Data Output). Icinga 2 will support IDO in a -backwards-compatible fashion in order to support icinga-web. -Additionally there will be a newly-designed backend for historical data -which can be queried using the built-in API when available. Effort will -be put into making this new data source more efficient for use with SLA -reporting. - -Icinga 2 will also feature dynamic reconfiguration using the API which -means users can create, delete and update any configuration object (e.g. -hosts and services) on-the-fly. Based on the API there are plans to -implement a command-line configuration tool similar to what Pacemaker -has with "crm". Later on this API may also be used to implement -auto-discovery for new services. - -The RPC interface may also be used to receive events in real-time, e.g. -when service checks are being executed or when a service’s state -changes. Some possible uses of this interface would be to export -performance data for services (RRD, graphite, etc.) or general log -information (logstash, graylog2, etc.). - -Checks ------- - -In Icinga 2 services are the only checkable objects. Hosts only have a -calculated state and no check are ever run for them. - -In order to maintain compatibility with the hundreds of existing check -plugins for Icinga 1.x there will be support for Nagios™-style checks. -The check interface however will be modular so that support for other -kinds of checks can be implemented later on (e.g. built-in checks for -commonly used services like PING, HTTP, etc. in order to avoid spawning -a process for each check). - -Based on the availability of remote Icinga 2 instances the core can -delegate execution of service checks to them in order to support -large-scale distributed setups with a minimal amount of maintenance. -Services can be assigned to specific check instances using configuration -settings. - -Notifications -------------- - -Event handlers and notifications will be supported similar to Icinga -1.x. Thanks to the dynamic configuration it is possible to easily adjust -the notification settings at runtime (e.g. in order to implement on-call -rotation). - -Scalability ------------ - -Icinga 1.x has some serious scalability issues which explains why there -are several add-ons which try to improve the core’s check performance. -One of these add-ons is mod\_gearman which can be used to distribute -checks to multiple workers running on remote systems. - -A problem that remains is the performance of the core when processing -check results. Scaling Icinga 1.x beyond 25.000 services proves to be a -challenging problem and usually involves setting up a cascade of Icinga -1.x instances and dividing the service checks between those instances. -This significantly increases the maintenance overhead when updating the -configuration for such a setup. - -Icinga 2 natively supports setting up multiple Icinga 2 instances in a -cluster to distribute work between those instances. Independent tasks -(e.g. performing service checks, sending notifications, updating the -history database, etc.) are implemented as components which can be -loaded for each instance. Configuration as well as program state is -automatically replicated between instances. - -In order to support using Icinga 2 in a partially trusted environment -SSL is used for all network communication between individual instances. -Objects (like hosts and services) can be grouped into security domains -for which permissions can be specified on a per-instance basis (so e.g. -you can have a separate API or checker instance for a specific domain). - -Agent-based Checks ------------------- - -Traditionally most service checks have been performed actively, meaning -that check plugins are executed on the same server that is also running -Icinga. This works great for checking most network-based services, e.g. -PING and HTTP. However, there are a number of services which cannot be -checked remotely either because they are not network-based or because -firewall settings or network policies ("no unencrypted traffic") -disallow accessing these services from the network where Icinga is -running. - -To solve this problem two add-ons have emerged, namely NRPE and NSCA. -NRPE can be thought of as a light-weight remote shell which allows the -execution of a restricted set of commands while supporting some -Nagios™-specific concepts like command timeouts. However unlike with the -design of commonly used protocols like SSH security in NRPE is merely an -afterthought. - -In most monitoring setups all NRPE agents share the same secret key -which is embedded into the NRPE binary at compile time. This means that -users can extract this secret key from their NRPE agent binary and use -it to query sensitive monitoring information from other systems running -the same NRPE binary. NSCA has similar problems. - -Based on Icinga 2’s code for check execution there will be an agent -which can be used on \*NIX as well as on Windows platforms. The agent -will be using the same configuration format like Icinga 2 itself and -will support SSL and IPv4/IPv6 to communicate with Icinga 2. - -Business Processes ------------------- - -In most cases users don’t care about the availability of individual -services but rather the aggregated state of multiple related services. -For example one might have a database cluster that is used for a web -shop. For an end-user the shop is available as long as at least one of -the database servers is working. - -Icinga 1.x does not have any support for business processes out of the -box. There are several add-ons which implement business process support -for Icinga, however none of those are well-integrated into Icinga. - -Icinga 2 will have native support for business processes which are built -right into the core and can be configured in a similar manner to -Nagios™-style checks. Users can define their own services based on -business rules which can be used as dependencies for other hosts or -services. - -Logging -------- - -Icinga 2 supports file-based logged as well as syslog (on \*NIX) and -event log (on Windows). Additionally Icinga 2 supports remote logging to -a central Icinga 2 instance. - -Icinga 2 Installation -===================== - -Requirements ------------- - -Packages --------- - -> **Note** -> -> Use packages whenever possible. - - ------------------------------------ ------------------------------------ - Distribution Package URL - Debian TBD - RHEL/CentOS TBD - SLES TBD - ------------------------------------ ------------------------------------ - -In case you’re running a distribution for which Icinga 2 packages are -not yet available download the source tarball and jump to Source Builds. - -Windows Installer ------------------ - -TODO - -Source Builds -------------- - -Download the source tarball and read the *INSTALL* file for details and -requirements. - -### Linux Builds - -Building from source on specific linux distributions is described on the -wiki: -[https://wiki.icinga.org/display/icinga2/Linux+Builds](https://wiki.icinga.org/display/icinga2/Linux+Builds) - -### Windows Builds - -Icinga 2 ships a MS Visual Studio solution file. Requirements and -compilation instructions can be found on the wiki: -[https://wiki.icinga.org/display/icinga2/Windows+Builds](https://wiki.icinga.org/display/icinga2/Windows+Builds) - -Installation Locations ----------------------- - - ------------------------------------ ------------------------------------ - Path Description - - /etc/icinga2 Contains Icinga 2 configuration - files. - - /etc/init.d/icinga2 The Icinga 2 init script. - - /usr/share/doc/icinga2 Documentation files that come with - Icinga 2. - - /usr/share/icinga2/itl The Icinga Template Library. - - /var/run/icinga2 Command pipe and PID file. - - /var/cache/icinga2 Performance data files and - status.dat/objects.cache. - - /var/lib/icinga2 The Icinga 2 state file. - ------------------------------------ ------------------------------------ - -/\* TODO \*/ - -/\* vim: set syntax=asciidoc filetype=asciidoc: \*/ - -Icinga 2 Migration -================== - -Purpose -------- - -Documentation on the general migration from Icinga 1.x to Icinga 2. - -Requirements ------------- - -Multi-core cpu, ram, fast disks. - -Installation ------------- - -Icinga 1.x and Icinga 2 may run side by side, but it’s recommended to -backup your existing 1.x installation before installing Icinga 2 on the -same host. - -Compatibility -------------- - -> **Note** -> -> The configuration format changed from 1.x to 2.x. Don’t panic though. -> A conversion script is shipped in *tools/configconvert* - please check -> the *README* file. - -For details check the chapter [Compatibility](icinga2-compat.html). - -Changes -------- - -For details check the chapter [Changes](icinga2-compat.html). - -TODO - -/\* vim: set syntax=asciidoc filetype=asciidoc: \*/ - -Icinga 2 Compatibility -====================== - -Purpose -------- - -Documentation on the compatibility and changes introduced with Icinga 2. - -Introduction ------------- - -Unlike Icinga 1.x, all used components (not only those for -compatibility) run asynchronous and use queues, if required. That way -Icinga 2 does not get blocked by any event, action or execution. - -Configuration -------------- - -> **Note** -> -> If you are upgrading from Icinga 1.x (or Nagios 3.x+) please note that -> Icinga 2 introduces a new configuration format. - -Details on the configuration can be found in chapter -[Configuration](:icinga2-config.html) - -Icinga 2 ships a config conversion script which will help you migrating -the existing configuration into the new format. Please look into the -*tools/configconvert* directory and follow the *README* instructions. - -> **Tip** -> -> If you kept planning to clean up your existing configuration, it may -> be a good shot to start fresh with a new configuration strategy based -> on the Icinga 2 configuration logic. - -Check Plugins -------------- - -All native check plugins can be used with Icinga 2. The configuration of -check commands is changed due to the new configuration format. - -Classic status and log files ----------------------------- - -Icinga 2 will write status.dat and objects.cache in a given interval -like known from Icinga 1.x - including the logs and their archives in -the old format and naming syntax. That way you can point any existing -Classic UI installation to the new locations (or any other addon/plugin -using them). - -External Commands ------------------ - -Like known from Icinga 1.x, Icinga 2 also provides an external command -pipe allowing your scripts and guis to send commands to the core -triggering various actions. - -Some commands are not supported though as their triggered functionality -is not available in Icinga 2 anymore. - -For a detailed list, please check: -[https://wiki.icinga.org/display/icinga2/External+Commands](https://wiki.icinga.org/display/icinga2/External+Commands) - -Performance Data ----------------- - -The Icinga 1.x Plugin API defines the performance data format. Icinga 2 -parses the check output accordingly and writes performance data files -based on template macros. File rotation interval can be defined as well. - -Unlike Icinga 1.x you can define multiple performance data writers for -all your graphing addons such as PNP, inGraph or graphite. - -IDO DB ------- - -Icinga 1.x uses an addon called *IDOUtils* to store core configuration, -status and historical information in a database schema. Icinga Web and -Reporting are using that database as their chosen backend. - -Icinga 2 is compatible to the IDO db schema but the the underlaying -design of inserting, updating and deleting data is different - -asynchronous queueing, database transactions and optimized queries for -performance. - -Furthermore there is no seperated daemon to receive the data through a -socket. Instead the IDO component queues the data and writes directly -into the database using the native database driver library (e.g. -libmysqlclient). Unlike Icinga 1.x libdbi as db abstraction layer is not -used anymore. - -Livestatus ----------- - -Icinga 2 supports the livestatus api while using Icinga 1.x an addon -named *mk\_livestatus* was required. - -Next to the GET functionality for retrieving configuration, status and -historical data, Icinga 2 livestatus also supports the COMMANDS -functionality. - -> **Tip** -> -> Icinga 2 supports tcp sockets natively while the Icinga 1.x addon only -> provides unix socket support. - -Checkresult Reaper ------------------- - -Unlike Icinga 1.x Icinga 2 is a multithreaded application and processes -check results in memory. The old checkresult reaper reading files from -disk again is obviously not required anymore for native checks. - -Some popular addons have been injecting their checkresults into the -Icinga 1.x checkresult spool directory bypassing the external command -pipe and PROCESS\_SERVICE\_CHECK\_RESULT mainly for performance reasons. - -In order to support that functionality as well, Icinga 2 got its -optional checkresult reaper. - -Changes -------- - -This is a collection of known changes in behaviour, configuration and -outputs. - -> **Note** -> -> May be incomplete, and requires updates in the future. - -TODO - -/\* vim: set syntax=asciidoc filetype=asciidoc: \*/ - -Icinga 2 Tutorial -================= - -Preface -------- - -This tutorial is a step-by-step introduction to installing Icinga 2 and -setting up your first couple of service checks. It assumes some -familiarity with Icinga 1.x. - -Installation ------------- - -In order to get started with Icinga 2 we will have to install it. The -preferred way of doing this is to use the official Debian or RPM -packages depending on which Linux distribution you are running. - - ------------------------------------ ------------------------------------ - Distribution Package URL - - Debian [http://icingabuild.dus.dg-i.net:808 - 0/job/icinga2/](http://icingabuild.d - us.dg-i.net:8080/job/icinga2/) - - RHEL TBD - ------------------------------------ ------------------------------------ - -In case you’re running a distribution for which Icinga 2 packages are -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. - -By default Icinga 2 uses the following files and directories: - - ------------------------------------ ------------------------------------ - Path Description - - /etc/icinga2 Contains Icinga 2 configuration - files. - - /etc/init.d/icinga2 The Icinga 2 init script. - - /usr/share/doc/icinga2 Documentation files that come with - Icinga 2. - - /usr/share/icinga2/itl The Icinga Template Library. - - /var/run/icinga2 Command pipe and PID file. - - /var/cache/icinga2 Performance data files and - status.dat/objects.cache. - - /var/lib/icinga2 The Icinga 2 state file. - ------------------------------------ ------------------------------------ - -Our First Service Check ------------------------ - -The Icinga 2 package comes with a number of example configuration files. -However, in order to explain some of the basics we’re going write our -own configuration file from scratch. - -Start by creating the file /etc/icinga2/icinga2.conf with the following -content: - - include - include - - object IcingaApplication "my-icinga" { - macros["plugindir"] = "/usr/lib/nagios/plugins" - } - -The configuration snippet includes the *itl/itl.conf* and -*itl/standalone.conf* files which are distributed as part of Icinga 2. -We will discuss the Icinga Template Library (ITL) in more detail later -on. - -The *itl/standalone.conf* configuration file takes care of configuring -Icinga 2 for single-instance (i.e. non-clustered) mode. - -Our configuration file also creates an object of type -*IcingaApplication* with the name *my-icinga*. The *IcingaApplication* -type can be used to define global macros and some other global settings. - -For now we’re only defining the global macro *plugindir* which we’re -going to use later on when referring to the path which contains our -check plugins. Depending on where you’ve installed your check plugins -you may need to update this path in your configuration file. - -You can verify that your configuration file works by starting Icinga 2: - - $ /usr/bin/icinga2 -c /etc/icinga2/icinga2.conf - [2013/04/23 13:36:20 +0200]
information/icinga-app: Icinga application loader (version: 0.0.1, git branch master, commit 0fcbfdb2) - [2013/04/23 13:36:20 +0200]
information/base: Adding library search dir: /usr/lib/icinga2 - [2013/04/23 13:36:20 +0200]
information/base: Loading library 'libicinga.la' - [2013/04/23 13:36:20 +0200]
information/config: Adding include search dir: /usr/share/icinga2 - [2013/04/23 13:36:20 +0200]
information/config: Compiling config file: /etc/icinga2/icinga2.conf - [2013/04/23 13:36:20 +0200]
information/config: Linking config items... - [2013/04/23 13:36:20 +0200]
information/config: Validating config items... - [2013/04/23 13:36:20 +0200]
information/config: Activating config items in compilation unit 'b2d21c28-a2e8-4fcb-ba00-45646bc1afb9' - [2013/04/23 13:36:20 +0200]
information/base: Restoring program state from file '/var/lib/icinga2/icinga2.state' - [2013/04/23 13:36:20 +0200]
information/base: Restored 0 objects - -In case there are any configuration errors Icinga 2 should print error -messages containing details about what went wrong. - -You can stop Icinga 2 with Control-C: - - ^C - [2013/04/23 13:39:39 +0200] information/base: Shutting down Icinga... - [2013/04/23 13:39:39 +0200] information/base: Dumping program state to file '/var/lib/icinga2/icinga2.state' - [2013/04/23 13:39:39 +0200]
information/icinga: Icinga has shut down. - $ - -Icinga 2 automatically saves its current state every couple of minutes -and when it’s being shut down. - -So far our Icinga 2 setup doesn’t do much. Lets change that by setting -up a service check for localhost. Modify your *icinga2.conf* -configuration file by adding the following lines: - - object CheckCommand "my-ping" inherits "plugin-check-command" { - command = [ - "$plugindir$/check_ping", - "-H", "$address$", - "-w", "10,5%", - "-c", "25,10%" - ] - } - - template Service "my-ping" inherits "plugin-service" { - check_command = "my-ping" - } - - object Host "localhost" { - display_name = "Home, sweet home!", - - services["ping"] = { - templates = [ "my-ping" ] - }, - - macros = { - address = "127.0.0.1" - }, - - check_interval = 10s, - - hostcheck = "ping" - } - -We’re defining a command object called "my-ping" which inherits from the -*plugin-check-command* template. The *plugin-check-command* template is -provided as part of the Icinga Template Library and describes how checks -are performed. In the case of plugin-based services this means that the -command specified by the *command* property is executed. - -The *command* property is an array or command-line arguments for the -check plugin. Alternatively you can specify the check command as a -string. - -The check command can make use of macros. Unlike in Icinga 1.x we have -free-form macros which means that users can choose arbitrary names for -their macros. - -By convention the following macros are usually used: - - ------------------------------------ ------------------------------------ - Macro Description - plugindir The path of your check plugins. - address The IPv4 address of the host. - address6 The IPv6 address of the host. - ------------------------------------ ------------------------------------ - -Note that the *my-ping* command object does not define a value for the -*address* macro. This is perfectly fine as long as that macro is defined -somewhere else (e.g. in the host). - -We’re also defining a service template called *my-ping* which uses the -command object we just created. - -Next we’re defining a *Host* object called *localhost*. We’re setting an -optional display\_name which is used by the Icinga Classic UI when -showing that host in the host overview. - -The services dictionary defines which services belong to a host. Using -the [] indexing operator we can manipulate individual items in this -dictionary. In this case we’re creating a new service called *ping*. - -The templates array inside the service definition lists all the -templates we want to use for this particular service. For now we’re just -listing our *my-ping* template. - -Remember how we used the *address* macro in the *command* setting -earlier? Now we’re defining a value for this macro which is used for all -services and their commands which belong to the *localhost* Host object. - -We’re also setting the check\_interval for all services belonging to -this host to 10 seconds. - -> **Note** -> -> When you don’t specify an explicit time unit Icinga 2 automatically -> assumes that you meant seconds. - -And finally we’re specifying which of the services we’ve created before -is used to define the host’s state. Note that unlike in Icinga 1.x this -just "clones" the service’s state and does not cause any additional -checks to be performed. - -Setting up the Icinga 1.x 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 -"command pipe") are also supported. If you require the icinga.log for -history views and/or reporting in Classic UI, this can be added -seperately to the CompatComponent object definition by adding a -CompatLog object. - -In order to enable this feature you will need to load the library -*compat* by adding the following lines to your configuration file: - - library "compat" - - object CompatComponent "compat" { } - object CompatLog "my-log" { } - -After restarting Icinga 2 you should be able to find the status.dat and -objects.cache files in /var/cache/icinga2. The log files can be found in -/var/log/icinga2/compat. The command pipe can be found in -/var/run/icinga2. - -You can install the Icinga 1.x Classic UI in standalone mode using the -following commands: - - $ wget http://downloads.sourceforge.net/project/icinga/icinga/1.9.0/icinga-1.9.0.tar.gz - $ tar xzf icinga-1.9.0.tar.gz ; cd icinga-1.9.0 - $ ./configure --enable-classicui-standalone --prefix=/usr/local/icinga2-classicui - $ make classicui-standalone - $ sudo make install classicui-standalone install-webconf-auth - $ sudo service apache2 restart - -> **Note** -> -> A detailed guide on installing Icinga 1.x Classic UI Standalone can be -> 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) - -After installing the Classic UI you will need to update the following -settings in your cgi.cfg configuration file at the bottom (section -"STANDALONE (ICINGA 2) OPTIONS"): - - ------------------------------------ ------------------------------------ - Configuration Setting Value - object\_cache\_file /var/cache/icinga2/objects.cache - status\_file /var/cache/icinga2/status.dat - resource\_file - - command\_file /var/run/icinga2/icinga2.cmd - check\_external\_commands 1 - interval\_length 60 - status\_update\_interval 10 - log\_file /var/log/icinga2/compat/icinga.log - log\_rotation\_method h - log\_archive\_path /var/log/icinga2/compat/archives - date\_format us - ------------------------------------ ------------------------------------ - -Depending on how you installed Icinga 2 some of those paths and options -might be different. - -> **Note** -> -> You need to grant permissions for the apache user manually after -> starting Icinga 2 for now. - - # chmod o+rwx /var/run/icinga2/{icinga2.cmd,livestatus} - -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) - -Some More Templates -------------------- - -Now that we’ve got our basic monitoring setup as well as the Icinga 1.x -Classic UI to work we can define a second host. Add the following lines -to your configuration file: - - object Host "icinga.org" { - display_name = "Icinga Website", - - services["ping"] = { - templates = [ "my-ping" ] - }, - - macros = { - address = "www.icinga.org" - }, - - check_interval = 10s, - - hostcheck = "ping" - } - -Restart your Icinga 2 instance and check the Classic UI for your new -service’s state. Unless you have a low-latency network connection you -will note that the service’s state is *CRITICAL*. This is because in the -*my-ping* command object we have hard-coded the timeout as 25 -milliseconds. - -Ideally we’d be able to specify different timeouts for our new service. -Using macros we can easily do this. - -> **Note** -> -> If you’ve used Icinga 1.x before you’re probably familiar with doing -> this by passing ARGx macros to your check commands. - -Start by replacing your *my-ping* command object with this: - - object CheckCommand "my-ping" inherits "plugin-check-command" { - command = [ - "$plugindir$/check_ping", - "-H", "$address$", - "-w", "$wrta$,$wpl$%", - "-c", "$crta$,$cpl$%" - ], - - macros = { - wrta = 10, - wpl = 5, - - crta = 25, - cpl = 10 - } - } - -We have replaced our hard-coded timeout values with macros and we’re -providing default values for these same macros right in the template -definition. The object inherits the basic check command attributes from -the ITL provided template *plugin-check-command*. - -In order to oderride some of these macros for a specific host we need to -update our *icinga.org* host definition like this: - - object Host "icinga.org" { - display_name = "Icinga Website", - - services["ping"] = { - templates = [ "my-ping" ], - - macros += { - wrta = 100, - crta = 250 - } - }, - - macros = { - address = "www.icinga.org" - }, - - check_interval = 10s, - - hostcheck = "ping" - } - -The *+=* operator allows us to selectively add new key-value pairs to an -existing dictionary. If we were to use the *=* operator instead we would -have to provide values for all the macros that are used in the *my-ping* -template overriding all values there. - -Icinga Template Library ------------------------ - -The Icinga Template Library is a collection of configuration templates -for commonly used services. By default it is installed in -*/usr/share/icinga2/itl* and you can include it in your configuration -files using the include directive: - - include - -> **Note** -> -> Ordinarily you’d use double-quotes for the include path. This way only -> paths relative to the current configuration file are considered. The -> angle brackets tell Icinga 2 to search its list of global include -> directories. - -One of the templates in the ITL is the *ping4* service template which is -quite similar to our example objects: - - object CheckCommand "ping4" inherits "plugin-check-command" { - command = [ - "$plugindir$/check_ping", - "-4", - "-H", "$address$", - "-w", "$wrta$,$wpl$%", - "-c", "$crta$,$cpl$%", - "-p", "$packets$", - "-t", "$timeout$" - ], - - macros = { - wrta = 100, - wpl = 5, - - crta = 200, - cpl = 15, - - packets = 5, - timeout = 0 - } - } - - template Service "ping4" { - check_command = "ping4" - } - -Lets simplify our configuration file by removing our custom *my-ping* -template and updating our service definitions to use the *ping4* -template instead. - -Include Files -------------- - -So far we’ve been using just one configuration file. However, once -you’ve created a few more host objects and service templates this can -get rather confusing. - -Icinga 2 lets you include other files from your configuration file. We -can use this feature to make our configuration a bit more modular and -easier to understand. - -Lets start by moving our two *Host* objects to a separate configuration -file: hosts.conf - -We will also need to tell Icinga 2 that it should include our newly -created configuration file when parsing the main configuration file. -This can be done by adding the include directive to our *icinga2.conf* -file: - - include "hosts.conf" - -Depending on the number of hosts you have it might be useful to split -your configuration files based on other criteria (e.g. device type, -location, etc.). - -You can use wildcards in the include path in order to refer to multiple -files. Assuming you’re keeping your host configuration files in a -directory called *hosts* you could include them like this: - - include "hosts/*.conf" - -Notifications -------------- - -Icinga 2 can send you notifications when your services change state. In -order to do this we’re going to write a shell script in -*/etc/icinga2/mail-notification.sh* that sends e-mail based -notifications: - - #!/bin/sh - - if [ -z "$1" ]; then - echo "Syntax: $0 " - echo - echo "Sends a mail notification to the specified e-mail address." - exit 1 - fi - - mail -s "** $NOTIFICATIONTYPE Service Alert: $HOSTALIAS/$SERVICEDESC is $SERVICESTATE **" $1 < **Note** -> -> Rather than adding these templates to your main configuration file you -> might want to create a separate file, e.g. *notifications.conf* and -> include it in *icinga2.conf*. - -The *export\_macros* property tells Icinga which macros to export into -the environment for the notification script. - -We also need to create a *User* object which Icinga can use to send -notifications to specific people: - - object User "tutorial-user" { - display_name = "Some User", - - macros = { - email = "tutorial@example.org" - } - } - -Each time a notification is sent for a service the user’s macros are -used when resolving the macros we used in the *Notification* template. - -In the next step we’re going to create a *Service* template which -specifies who notifications should be sent to: - - template Service "mail-notification-service" { - notifications["mail"] = { - templates = [ "mail-notification" ], - - users = [ "tutorial-user" ] - }, - - notification_interval = 1m - } - -And finally we can assign this new service template to our services: - - ... - services["ping"] = { - templates = [ "ping4", "mail-notification-service" ] - }, - ... - -In addition to defining notifications for individual services it is also -possible to assign notification templates to all services of a host. You -can find more information about how to do that in the documentation. - -> **Note** -> -> Escalations in Icinga 2 are just a notification, only added a defined -> begin and end time. Check the documentation for details. - -Time Periods ------------- - -Time periods allow you to specify when certain services should be -checked and when notifications should be sent. - -Here is an example time period definition: - - object TimePeriod "work-hours" inherits "legacy-timeperiod" { - ranges = { - monday = "9:00-17:00", - tuesday = "9:00-17:00", - wednesday = "9:00-17:00", - thursday = "9:00-17:00", - friday = "9:00-17:00", - } - } - -The *legacy-timeperiod* template is defined in the Icinga Template -Library and supports Icinga 1.x time periods. A complete definition of -the time Icinga 1.x time period syntax can be found at -[http://docs.icinga.org/latest/en/objectdefinitions.html\#timeperiod](http://docs.icinga.org/latest/en/objectdefinitions.html#timeperiod). - -Using the *check\_period* attribute you can define when services should -be checked: - - ... - services["ping"] = { - templates = [ "ping4", "mail-notification-service" ], - check_period = "work-hours" - }, - ... - -Also, using the *notification\_period* attribute you can define when -notifications should be sent: - - template Service "mail-notification-service" { - notifications["mail"] = { - templates = [ "mail-notification" ], - - users = [ "tutorial-user" ] - }, - - notification_interval = 1m, - notification_period = "work-hours" - } - -The *notification\_period* attribute is also valid in *User* and -*Notification* objects. - -Dependencies ------------- - -If you are familiar with Icinga 1.x host/service dependencies and -parent/child relations on hosts, you might want to look at the -conversion script in order to convert your existing configuration. There -are no separate dependency objects anymore, and no separate parent -attribute either. - -Using Icinga 2, we can directly define a dependency in the current host -or service object to any other host or service object. If we want other -objects to inherit those dependency attributes, we can also define them -in a template. - -In the following example we’ve added a cluster host with the service -*ping* which we are going to define a dependency for in another host. - - template Service "my-cluster-ping" { - check_command = "my-ping", - } - - object Host "my-cluster" { - ... - services["ping"] = { - templates = [ "my-cluster-ping" ], - } - ... - } - -We can now define a service dependency as new service template (or -directly on the service definition): - - template Service "my-cluster-dependency" { - servicedependencies = [ - { host = "my-cluster", service = "ping" }, - ], - } - -Now let’s use that template for the *ping* service we’ve defined -previously and assign the servicedependencies to that service. - - ... - services["ping"] = { - templates = [ "ping4", "mail-notification-service", "my-cluster-dependency" ], - }, - ... - -Performance Data ----------------- - -Because there are no host checks in Icinga 2, the PerfdataWriter object -will only write service performance data files. Creating the object will -allow you to set the perfdata\_path, format\_template and -rotation\_interval. The format template is similar to existing Icinga -1.x configuration for PNP or inGraph using macro formatted strings. - -Details on the common Icinga 1.x macros can be found at -[http://docs.icinga.org/latest/en/macrolist.html](http://docs.icinga.org/latest/en/macrolist.html) - -> **Note** -> -> You can define multiple PerfdataWriter objects with different -> configuration settings, i.e. one for PNP, one for inGraph or your -> preferred graphite collector. - -Let’s create a new PNP PerfdataWriter object: - - object PerfdataWriter "pnp" { - perfdata_path = "/var/lib/icinga2/service-perfdata", - format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$TIMET$\tHOSTNAME::$HOSTNAME$\tSERVICEDESC::$SERVICEDESC$\tSERVICEPERFDATA::$SERVICEPERFDATA$\tSERVICECHECKCOMMAND::$SERVICECHECKCOMMAND$\tHOSTSTATE::$HOSTSTATE$\tHOSTSTATETYPE::$HOSTSTATETYPE$\tSERVICESTATE::$SERVICESTATE$\tSERVICESTATETYPE::$SERVICESTATETYPE$", - rotation_interval = 15s, - } - -You may need to reconfigure your NPCD daemon with the correct path for -your performance data files. This can be done in the PNP configuration -file npcd.cfg: - - perfdata_spool_dir = /var/lib/icinga2/ - -Livestatus Component --------------------- - -The Livestatus component will provide access to Icinga 2 using the -livestatus api. In addition to the unix socket Icinga 2 also service -livestatus directly via tcp socket. - -> **Note** -> -> Only config and status tables are available at this time. History -> tables such as log, statehist will follow. - -Once Icinga 2 is started, configure your gui (e.g. Thruk) using the -livestatus backend. - -TCP Socket - - library "livestatus" - object LivestatusComponent "livestatus-tcp" { - socket_type = "tcp", - host = "10.0.10.18", - port = "6558" - } - -Unix Socket - - library "livestatus" - object LivestatusComponent "livestatus-unix" { - socket_type = "unix", - socket_path = "/var/run/icinga2/livestatus" - } - -> **Note** -> -> You need to grant permissions for the apache user manually after -> starting Icinga 2 for now. - - # chmod o+rwx /var/run/icinga2/{icinga2.cmd,livestatus} - -IDO Database Component ----------------------- - -The IDO component will write to the same database backend as known from -Icinga 1.x IDOUtils. Therefore you’ll need to have your database schema -and users already installed, like described in -[http://docs.icinga.org/latest/en/quickstart-idoutils.html\#createidoutilsdatabase](http://docs.icinga.org/latest/en/quickstart-idoutils.html#createidoutilsdatabase) - -> **Note** -> -> Currently there’s only MySQL support in progress, Postgresql, Oracle -> tbd. - -Configure the IDO MySQL component with the defined credentials and start -Icinga 2. - -> **Note** -> -> Make sure to define a unique instance\_name. That way the Icinga 2 IDO -> component will not interfere with your Icinga 1.x setup, if existing. - - library "ido_mysql" - object IdoMysqlDbConnection "my-ido-mysql" { - host = "127.0.0.1", - port = "3306", - user = "icinga", - password = "icinga", - database = "icinga", - table_prefix = "icinga_", - instance_name = "icinga2", - instance_description = "icinga2 instance" - } - -Starting Icinga 2 in debug mode in foreground using -x will show all -database queries. - -Custom Attributes ------------------ - -In Icinga 1.x there were so-called "custom variables" available prefixed -with an underscore, as well as plenty of other attributes such as -action\_url, notes\_url, icon\_image, etc. To overcome the limitations -of hardcoded custom attributes, Icinga 2 ships with the *custom* -attribute as dictionary. - -For example, if you have PNP installed we could add a reference url to -Icinga Classic UI by using the classic method of defining an -action\_url. - - template Service "my-pnp-svc" { - custom = { - action_url = "/pnp4nagios/graph?host=$HOSTNAME$&srv=$SERVICEDESC$' class='tips' rel='/pnp4nagios/popup?host=$HOSTNAME$&srv=$SERVICEDESC$", - } - } - -And add that template again to our service definition: - - ... - services["ping"] = { - templates = [ "ping4", "mail-notification-service", "my-cluster-dependency", "my-pnp-svc" ], - }, - ... - -While at it, our configuration tool will add its LDAP DN and a snmp -community to the service too, using += for additive attributes: - - ... - services["ping"] = { - templates = [ "ping4", "mail-notification-service", "my-cluster-dependency", "my-pnp-svc" ], - custom += { - DN = "cn=icinga2-dev-svc,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org", - SNMPCOMMUNITY = "public" - } - }, - ... - -/\* vim: set syntax=asciidoc filetype=asciidoc: \*/ - -Icinga 2 Configuration -====================== - -Configuration Introduction --------------------------- - -In Icinga 2 configuration is based on objects. There’s no difference in -defining global settings for the core application or for a specific -runtime configuration object. - -There are different types for the main application, its components and -tools. The runtime configuration objects such as hosts, services, etc -are defined using the same syntax. - -Each configuration object must be unique by its name. Otherwise Icinga 2 -will bail early on verifying the parsed configuration. - -Main Configuration ------------------- - -Starting Icinga 2 requires the main configuration file called -"icinga2.conf". That’s the location where everything is defined or -included. Icinga 2 will only know the content of that file and included -configuration file snippets. - - # /usr/bin/icinga2 -c /etc/icinga2/icinga2.conf - -> **Note** -> -> You can use just the main configuration file and put everything in -> there. Though that is not advised because configuration may be -> expanded over time. Rather organize runtime configuration objects into -> their own files and/or directories and include that in the main -> configuration file. - -Configuration Syntax --------------------- - -/\* TODO \*/ - -Details on the syntax can be found in the chapter -icinga2-config-syntax.html[Configuration Syntax] - -Configuration Types -------------------- - -/\* TODO \*/ - -Details on the available types can be found in the chapter -icinga2-config-types.html[Configuration Types] - -Configuration Templates ------------------------ - -Icinga 2 ships with the **Icinga Template Library (ITL)**. This is a set -of predefined templates and definitions available in your actual -configuration. - -> **Note** -> -> Do not change the ITL’s files. They will be overridden on upgrade. -> Submit a patch upstream or include your very own configuration -> snippet. - -Include the basic ITL set in your main configuration like - - include - -> **Note** -> -> Icinga 2 recognizes the ITL’s installation path and looks for that -> specific file then. - -Having Icinga 2 installed in standalone mode make sure to include -itl/standalone.conf as well (see sample configuration). - - include - -/\* vim: set syntax=asciidoc filetype=asciidoc: \*/ - -Icinga 2 Configuration Syntax -============================= - -Configuration Syntax --------------------- - -### Object Definition - -Icinga 2 features an object-based configuration format. In order to -define objects the *object* keyword is used: - - object Host "host1.example.org" { - display_name = "host1", - - check_interval = 30, - retry_interval = 15, - - macros = { - address = "192.168.0.1" - } - } - -> **Note** -> -> The Icinga 2 configuration format is agnostic to whitespaces and -> new-lines. - -> **Note** -> -> Colons (:) are not permitted in object names. - -Each object is uniquely identified by its type (*Host*) and name -(*host1.example.org*). Objects can contain a comma-separated list of -property declarations. The following data types are available for -property values: - -#### Numeric Literals - -A floating-point number. - -Example: - - -27.3 - -#### Duration Literal - -Similar to floating-point numbers except for that fact that they support -suffixes to help with specifying time durations. - -Example: - - 2.5m - -Supported suffixes include ms (milliseconds), s (seconds), m (minutes) -and h (hours). - -#### String Literals - -A string. - -Example: - - "Hello World!" - -Certain characters need to be escaped. The following escape sequences -are supported: - - ------------------------------------ ------------------------------------ - Character Escape sequence - " \\" - \ \\t - \ \\r - \ \\n - \ \\b - \ \\f - ------------------------------------ ------------------------------------ - -In addition to these pre-defined escape sequences you can specify -arbitrary ASCII characters using the backslash character (\\) followed -by an ASCII character in octal encoding. - -#### Multiline String Literals - -Strings spanning multiple lines can be specified by enclosing them in -{{{ and }}}. - -Example. - - {{{This - is - a multi-line - string.}}} - -#### Boolean Literals - -The keywords *true* and *false* are equivalent to 1 and 0 respectively. - -#### Null Value - -The *null* keyword can be used to specify an empty value. - -#### Dictionary - -An unordered list of key-value pairs. Keys must be unique and are -compared in a case-insensitive manner. - -Individual key-value pairs must be separated from each other with a -comma. The comma after the last key-value pair is optional. - -Example: - - { - address = "192.168.0.1", - 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. - -> **Note** -> -> Setting a dictionary key to null causes the key to be removed from the -> dictionary. - -#### Array - -An ordered list of values. - -Individual array elements must be separated from each other with a -comma. The comma after the last element is optional. - -Example: - - [ - "hello", - "world", - 42, - [ "a", "nested", "array" ] - ] - -> **Note** -> -> An array may simultaneously contain values of different types, e.g. -> strings and numbers. - -### 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 *=* - -Sets a dictionary element to the specified value. - -Example: - - { - a = 5, - a = 7 - } - -In this example a has the value 7 after both instructions are executed. - -#### Operator *+=* - -Modifies a dictionary or array by adding new elements to it. - -Example: - - { - a = [ "hello" ], - a += [ "world" ] - } - -In this example a contains both *"hello"* and *"world"*. This currently -only works for dictionaries and arrays. Support for numbers might be -added later on. - -#### Operator *-=* - -Removes elements from a dictionary. - -Example: - - { - a = { "hello", "world" }, - a -= { "world" } - } - -In this example a contains *"hello"*. Trying to remove an item that does -not exist is not an error. Not implemented yet. - -#### Operator *\*=* - -Multiplies an existing dictionary element with the specified number. If -the dictionary element does not already exist 0 is used as its value. - -Example: - - { - a = 60, - a *= 5 - } - -In this example a is 300. This only works for numbers. Not implemented -yet. - -#### Operator */=* - -Divides an existing dictionary element by the specified number. If the -dictionary element does not already exist 0 is used as its value. - -Example: - - { - a = 300, - a /= 5 - } - -In this example a is 60. This only works for numbers. Not implemented -yet. - -### Attribute Shortcuts - -#### Indexer Shortcut - -Example: - - { - hello["key"] = "world" - } - -This is equivalent to writing: - - { - hello += { - key = "world" - } - } - -### Specifiers - -Objects can have specifiers that have special meaning. The following -specifiers can be used (prefacing the *object* keyword): - -#### Specifier *abstract* - -This specifier identifies the object as a template which can be used by -other object definitions. The object will not be instantiated on its -own. - -Instead of using the *abstract* specifier you can use the *template* -keyword which is a shorthand for writing *abstract object*: - - template Service "http" { - ... - } - -#### Specifier *local* - -This specifier disables replication for this object. The object will not -be sent to remote Icinga instances. - -### Inheritance - -Objects can inherit attributes from one or more other objects. - -Example: - - template Host "default-host" { - check_interval = 30, - - macros = { - color = "red" - } - } - - template Host "test-host" inherits "default-host" { - macros += { - color = "blue" - } - } - - object Host "localhost" inherits "test-host" { - macros += { - address = "127.0.0.1", - address6 = "::1" - } - } - -> **Note** -> -> The *"default-host"* and *"test-host"* objects are marked as templates -> using the *abstract* keyword. Parent objects do not necessarily have -> to be *abstract* though in general they are. - -> **Note** -> -> The += operator is used to insert additional properties into the -> macros dictionary. The final dictionary contains all 3 macros and the -> property *color* has the value *"blue"*. - -Parent objects are resolved in the order they’re specified using the -*inherits* keyword. - -### Comments - -The Icinga 2 configuration format supports C/C++-style comments. - -Example: - - /* - This is a comment. - */ - object Host "localhost" { - check_interval = 30, // this is also a comment. - retry_interval = 15 - } - -### Includes - -Other configuration files can be included using the *include* directive. -Paths must be relative to the configuration file that contains the -*include* directive. - -Example: - - include "some/other/file.conf" - include "conf.d/*.conf" - -> **Note** -> -> Wildcard includes are not recursive. - -Icinga also supports include search paths similar to how they work in a -C/C++ compiler: - - include - -Note the use of angle brackets instead of double quotes. This causes the -config compiler to search the include search paths for the specified -file. By default \$PREFIX/icinga2 is included in the list of search -paths. - -Wildcards are not permitted when using angle brackets. - -### Library directive - -The *library* directive can be used to manually load additional -libraries. Upon loading these libraries may provide additional types or -methods. - -Example: - - library "snmphelper" - -> **Note** -> -> The *icinga* library is automatically loaded at startup. - -### Type Definition - -By default Icinga has no way of semantically verifying its configuration -objects. This is where type definitions come in. Using type definitions -you can specify which attributes are allowed in an object definition. - -Example: - - type Pizza { - %require "radius", - %attribute number "radius", - - %attribute dictionary "ingredients" { - %validator "ValidateIngredients", - - %attribute string "*", - - %attribute dictionary "*" { - %attribute number "quantity", - %attribute string "name" - } - }, - - %attribute any "custom::*" - } - -The Pizza definition provides the following validation rules: - -- Pizza objects must contain an attribute *radius* which has to be a - number. - -- Pizza objects may contain an attribute *ingredients* which has to be - a dictionary. - -- Elements in the ingredients dictionary can be either a string or a - dictionary. - -- If they’re a dictionary they may contain attributes *quantity* (of - type number) and *name* (of type string). - -- The script function *ValidateIngredients* is run to perform further - validation of the ingredients dictionary. - -- Pizza objects may contain attribute matching the pattern - *custom::\** of any type. - -Valid types for type rules include: \* any \* number \* string \* scalar -(an alias for string) \* dictionary - -Icinga 2 Configuration Types -============================ - -Configuration Format --------------------- - -### Object Definition - -Icinga 2 features an object-based configuration format. In order to -define objects the "object" keyword is used: - - object Host "host1.example.org" { - alias = "host1", - - check_interval = 30, - retry_interval = 15, - - macros = { - address = "192.168.0.1" - } - } - -> **Note** -> -> The Icinga 2 configuration format is agnostic to whitespaces and -> new-lines. - -Each object is uniquely identified by its type ("Host") and name -("host1.example.org"). Objects can contain a comma-separated list of -property declarations. The following data types are available for -property values: - -#### Numeric Literals - -A floating-point number. - -Example: - - -27.3 - -#### Duration Literal - -Similar to floating-point numbers except for that fact that they support -suffixes to help with specifying time durations. - -Example: - - 2.5m - -Supported suffixes include ms (milliseconds), s (seconds), m (minutes) -and h (hours). - -#### String Literals - -A string. No escape characters are supported at present though this will -likely change. - -Example: - - "Hello World!" - -#### Expression List - -A list of expressions that when executed has a dictionary as a result. - -Example: - - { - address = "192.168.0.1", - 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. - -### 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 "=" - -Sets a dictionary element to the specified value. - -Example: - - { - a = 5, - a = 7 - } - -In this example a has the value 7 after both instructions are executed. - -#### Operator "+=" - -Modifies a dictionary by adding new elements to it. - -Example: - - { - a = { "hello" }, - a += { "world" } - } - -In this example a contains both "hello" and "world". This currently only -works for expression lists. Support for numbers might be added later on. - -#### Operator "-=" - -Removes elements from a dictionary. - -Example: - - { - a = { "hello", "world" }, - a -= { "world" } - } - -In this example a contains "hello". Trying to remove an item that does -not exist is not an error. Not implemented yet. - -#### Operator "\*=" - -Multiplies an existing dictionary element with the specified number. If -the dictionary element does not already exist 0 is used as its value. - -Example: - - { - a = 60, - a *= 5 - } - -In this example a is 300. This only works for numbers. Not implemented -yet. - -#### Operator "/=" - -Divides an existing dictionary element by the specified number. If the -dictionary element does not already exist 0 is used as its value. - -Example: - - { - a = 300, - a /= 5 - } - -In this example a is 60. This only works for numbers. Not implemented -yet. - -### Attribute Shortcuts - -#### Value Shortcut - -Example: - - { - "hello", "world" - } - -This is equivalent to writing: - - { - _00000001 = "hello", _00000002 = "world" - } - -The item’s keys are monotonically increasing and the config compiler -takes care of ensuring that all keys are unique (even when adding items -to an existing attribute using +=). - -#### Indexer Shortcut - -Example: - - { - hello["key"] = "world" - } - -This is equivalent to writing: - - { - hello += { - key = "world" - } - } - -### Specifiers - -Objects can have specifiers that have special meaning. The following -specifiers can be used (before the "object" keyword): - -#### Specifier "abstract" - -This specifier identifies the object as a template which can be used by -other object definitions. The object will not be instantiated on its -own. - -Instead of using the "abstract" specifier you can use the "template" -keyword which is a shorthand for writing "abstract object": - - template Service "http" { - ... - } - -#### Specifier "local" - -This specifier disables replication for this object. The object will not -be sent to remote Icinga instances. - -### Inheritance - -Objects can inherit attributes from one or more other objects. - -Example: - - abstract object Host "default-host" { - check_interval = 30, - - macros = { - color = "red" - } - } - - abstract object Host "test-host" inherits "default-host" { - macros += { - color = "blue" - } - } - - object Host "localhost" inherits "test-host" { - macros += { - address = "127.0.0.1", - address6 = "::1" - } - } - -> **Note** -> -> The "default-host" and "test-host" objects are marked as templates -> using the "abstract" keyword. Parent objects do not necessarily have -> to be "abstract" though in general they are. - -> **Note** -> -> The += operator is used to insert additional properties into the -> macros dictionary. The final dictionary contains all 3 macros and the -> property "color" has the value "blue". - -Parent objects are resolved in the order they’re specified using the -"inherits" keyword. Parent objects must already be defined by the time -they’re used in an object definition. - -### Comments - -The Icinga 2 configuration format supports C/C++-style comments. - -Example: - - /* - This is a comment. - */ - object Host "localhost" { - check_interval = 30, // this is also a comment. - retry_interval = 15 - } - -### Includes - -Other configuration files can be included using the "\#include" -directive. Paths must be relative to the configuration file that -contains the "\#include" keyword: - -Example: - - #include "some/other/file.conf" - #include "conf.d/*.conf" - -Icinga also supports include search paths similar to how they work in a -C/C++ compiler: - - #include - -Note the use of angle brackets instead of double quotes. This causes the -config compiler to search the include search paths for the specified -file. By default \$PREFIX/icinga2 is included in the list of search -paths. - -Wildcards are not permitted when using angle brackets. - -### Library directive - -The "\#library" directive can be used to manually load additional -libraries. Upon loading these libraries may provide additional classes -or methods. - -Example: - - #library "snmphelper" - -> **Note** -> -> The "icinga" library is automatically loaded by Icinga. - -### Type Definition - -By default Icinga has no way of semantically verifying its configuration -objects. This is where type definitions come in. Using type definitions -you can specify which attributes are allowed in an object definition. - -Example: - - type Pizza { - %require "radius", - %attribute number "radius", - - %attribute dictionary "ingredients" { - %validator "ValidateIngredients", - - %attribute string "*", - - %attribute dictionary "*" { - %attribute number "quantity", - %attribute string "name" - } - }, - - %attribute any "custom::*" - } - -The Pizza definition provides the following validation rules: - -- Pizza objects must contain an attribute "radius" which has to be a - number. - -- Pizza objects may contain an attribute "ingredients" which has to be - a dictionary. - -- Elements in the ingredients dictionary can be either a string or a - dictionary. - -- If they’re a dictionary they may contain attributes "quantity" (of - type number) and "name" (of type string). - -- The script function "ValidateIngredients" is run to perform further - validation of the ingredients dictionary. - -- Pizza objects may contain attribute matching the pattern - "custom::\*" of any type. - -Valid types for type rules include: \* any \* number \* string \* scalar -(an alias for string) \* dictionary - -Configuration Objects ---------------------- - -### Type: IcingaApplication - -The "IcingaApplication" type is used to specify global configuration -parameters for Icinga. There must be exactly one application object in -each Icinga 2 configuration. The object must have the "local" specifier. - -Example: - - local object IcingaApplication "icinga" { - cert_path = "my-cert.pem", - ca_path = "ca.crt", - - node = "192.168.0.1", - service = 7777, - - pid_path = "/var/run/icinga2.pid", - state_path = "/var/lib/icinga2/icinga2.state", - - macros = { - plugindir = "/usr/local/icinga/libexec" - } - } - -#### Attribute: cert\_path - -This is used to specify the SSL client certificate Icinga 2 will use -when connecting to other Icinga 2 instances. This property is optional -when you’re setting up a non-networked Icinga 2 instance. - -#### Attribute: ca\_path - -This is the public CA certificate that is used to verify connections -from other Icinga 2 instances. This property is optional when you’re -setting up a non-networked Icinga 2 instance. - -#### Attribute: node - -The externally visible IP address that is used by other Icinga 2 -instances to connect to this instance. This property is optional when -you’re setting up a non-networked Icinga 2 instance. - -> **Note** -> -> Icinga does not bind to this IP address. - -#### Attribute: service - -The port this Icinga 2 instance should listen on. This property is -optional when you’re setting up a non-networked Icinga 2 instance. - -#### Attribute: pid\_path - -Optional. The path to the PID file. Defaults to "icinga.pid" in the -current working directory. - -#### Attribute: state\_path - -Optional. The path of the state file. This is the file Icinga 2 uses to -persist objects between program runs. Defaults to "icinga2.state" in the -current working directory. - -#### Attribute: macros - -Optional. Global macros that are used for service checks and -notifications. - -### Type: Component - -Icinga 2 uses a number of components to implement its feature-set. The -"Component" configuration object is used to load these components and -specify additional parameters for them. "Component" objects must have -the "local" specifier. The typical components to be loaded in the -default configuration would be "checker", "delegation" and more. - -Example "compat": - - local object Component "compat" { - status_path = "/var/cache/icinga2/status.dat", - objects_path = "/var/cache/icinga2/objects.cache", - } - -#### Attribute: status\_path - -Specifies where Icinga 2 Compat component will put the status.dat file, -which can be read by Icinga 1.x Classic UI and other addons. If not set, -it defaults to the localstatedir location. - -#### Attribute: objects\_path - -Specifies where Icinga 2 Compat component will put the objects.cache -file, which can be read by Icinga 1.x Classic UI and other addons. If -not set, it defaults to the localstatedir location. - -### Type: ConsoleLogger - -Specifies Icinga 2 logging to the console. Objects of this type must -have the "local" specifier. - -Example: - - local object ConsoleLogger "my-debug-console" { - severity = "debug" - } - -#### Attribute: severity - -The minimum severity for this log. Can be "debug", "information", -"warning" or "critical". Defaults to "information". - -### Type: FileLogger - -Specifies Icinga 2 logging to a file. Objects of this type must have the -"local" specifier. - -Example: - - local object FileLogger "my-debug-file" { - severity = "debug", - path = "/var/log/icinga2/icinga2-debug.log" - } - -#### Attribute: path - -The log path. - -#### Attribute: severity - -The minimum severity for this log. Can be "debug", "information", -"warning" or "critical". Defaults to "information". - -### Type: SyslogLogger - -Specifies Icinga 2 logging to syslog. Objects of this type must have the -"local" specifier. - -Example: - - local object SyslogLogger "my-crit-syslog" { - severity = "critical" - } - -#### Attribute: severity - -The minimum severity for this log. Can be "debug", "information", -"warning" or "critical". Defaults to "information". - -### Type: Endpoint - -Endpoint objects are used to specify connection information for remote -Icinga 2 instances. Objects of this type should not be local: - - object Endpoint "icinga-c2" { - node = "192.168.5.46", - service = 7777, - } - -#### Attribute: node - -The hostname/IP address of the remote Icinga 2 instance. - -#### Attribute: service - -The service name/port of the remote Icinga 2 instance. - -### Type: 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 = {2yy - plugindir = "/usr/lib/nagios/plugins", - address = "127.0.0.1", - community = "public", - } - } - -### Type: NotificationCommand - -A notification command definition. - -Example: - - object NotificationCommand "mail-service-notification" inherits "plugin-notification-command" { - command = "/usr/bin/printf \"%b\" \"***** Icinga *****\n\nNotification Type: $NOTIFICATIONTYPE$\n\nService: $SERVICEDESC$\nHost: $HOSTALIAS$\nAddress: $HOSTADDRESS$\nState: $SERVICESTATE$\n\nDate/Time: $LONGDATETIME$\n\nAdditional Info: $SERVICEOUTPUT$\n\nComment: [$NOTIFICATIONAUTHORNAME$] $NOTIFICATIONCOMMENT$\n\n\" | /usr/bin/mail -s \"$NOTIFICATIONTYPE$ - $HOSTNAME$ - $SERVICEDESC$ - $SERVICESTATE$\" $CONTACTEMAIL$", - } - -Type: EventCommand - - An event command definition. - - NOTE: Similar to Icinga 1.x event handlers. - - Example: - - ------------------------------------------------------------------------------- - object EventCommand "restart-httpd-event" inherits "plugin-event-command" { - command = "/usr/local/icinga/libexec/restart-httpd.sh", - } - ------------------------------------------------------------------------------- - - - Type: Service - -Service objects describe network services and how they should be checked -by Icinga 2. - -> **Note** -> -> Better create a service template and use that reference on the host -> definition as shown below. - -Example: - - object Service "localhost-uptime" { - host_name = "localhost", - - alias = "localhost Uptime", - - methods = { - check = "PluginCheck" - }, - - check_command = "check_snmp", - - macros = { - plugindir = "/usr/lib/nagios/plugins", - address = "127.0.0.1", - community = "public", - oid = "DISMAN-EVENT-MIB::sysUpTimeInstance" - } - - check_interval = 60s, - retry_interval = 15s, - - servicegroups = { "all-services", "snmp" }, - - checkers = { "*" }, - } - -#### Attribute: host\_name - -The host this service belongs to. There must be a "Host" object with -that name. - -#### Attribute: alias - -Optional. A short description of the service. - -#### Attribute: methods - check - -The check type of the service. For now only external check plugins are -supported ("PluginCheck"). - -#### Attribute: check\_command - -Optional when not using the "external plugin" check type. The check -command. May contain macros. - -#### Attribute: check\_interval - -Optional. The check interval (in seconds). - -#### Attribute: retry\_interval - -Optional. The retry interval (in seconds). This is used when the service -is in a soft state. - -#### Attribute: servicegroups - -Optional. The service groups this service belongs to. - -#### Attribute: checkers - -Optional. A list of remote endpoints that may check this service. -Wildcards can be used here. - -### Type: ServiceGroup - -A group of services. - -Example: - - object ServiceGroup "snmp" { - alias = "SNMP services", - - custom = { - notes_url = "http://www.example.org/", - action_url = "http://www.example.org/", - } - } - -#### Attribute: alias - -Optional. A short description of the service group. - -#### Attribute: notes\_url - -Optional. Notes URL. Used by the CGIs. - -#### Attribute: action\_url - -Optional. Action URL. Used by the CGIs. - -### Type: Host - -A host. Unlike in Icinga 1.x hosts are not checkable objects in Icinga -2. - -Example: - - object Host "localhost" { - alias = "The best host there is", - - hostgroups = [ "all-hosts" ], - - hostcheck = "ping", - dependencies = [ "router-ping" ] - - services["ping"] = { templates = "ping" } - services["http"] = { - templates = "my-http", - macros = { - vhost = "test1.example.org", - port = 81 - } - } - - check_interval = 60m, - retry_interval = 15m, - - servicegroups = [ "all-services" ], - - checkers = { "*" }, - } - -#### Attribute: alias - -Optional. A short description of the host. - -#### Attribute: hostgroups - -Optional. A list of host groups this host belongs to. - -#### Attribute: hostcheck - -Optional. A service that is used to determine whether the host is up or -down. - -#### Attribute: hostdependencies - -Optional. A list of hosts that are used to determine whether the host is -unreachable. - -#### Attribute: servicedependencies - -Optional. A list of services that are used to determine whether the host -is unreachable. - -#### Attribute: services - -Inline definition of services. Each service name is defined in square -brackets and got its own dictionary with attribute properties, such as -the template service being used. All other service-related properties -are additively copied into the new service object. - -The new service’s name is "hostname-service" - where "service" is the -array key in the services array. - -The priority for service properties is (from highest to lowest): - -1. Properties specified in the dictionary of the inline service - definition - -2. Host properties - -3. Properties inherited from the new service’s parent object - -#### Attribute: check\_interval - -Optional. Copied into inline service definitions. The host itself does -not have any checks. - -#### Attribute: retry\_interval - -Optional. Copied into inline service definitions. The host itself does -not have any checks. - -#### Attribute: servicegroups - -Optional. Copied into inline service definitions. The host itself does -not have any checks. - -#### Attribute: checkers - -Optional. Copied into inline service definitions. The host itself does -not have any checks. - -### Type: HostGroup - -A group of hosts. - -Example - - object HostGroup "my-hosts" { - alias = "My hosts", - - notes_url = "http://www.example.org/", - action_url = "http://www.example.org/", - } - -#### Attribute: alias - -Optional. A short description of the host group. - -#### Attribute: notes\_url - -Optional. Notes URL. Used by the CGIs. - -#### Attribute: action\_url - -Optional. Action URL. Used by the CGIs. - -### Type: PerfdataWriter - -Write check result performance data to a defined path using macro -pattern. - -Example - - local object PerfdataWriter "pnp" { - perfdata_path = "/var/spool/icinga2/perfdata/service-perfdata", - format_template = "DATATYPE::SERVICEPERFDATA\tTIMET::$TIMET$\tHOSTNAME::$HOSTNAME$\tSERVICEDESC::$SERVICEDESC$\tSERVICEPERFDATA::$SERVICEPERFDATA$\tSERVICECHECKCOMMAND::$SERVICECHECKCOMMAND$\tHOSTSTATE::$HOSTSTATE$\tHOSTSTATETYPE::$HOSTSTATETYPE$\tSERVICESTATE::$SERVICESTATE$\tSERVICESTATETYPE::$SERVICESTATETYPE$", - rotation_interval = 15s, - } - -#### Attribute: perfdata\_path - -Path to the service perfdata file. - -> **Note** -> -> Will be automatically rotated with timestamp suffix. - -#### Attribute: format\_template - -Formatting of performance data output for graphing addons or other post -processing. - -#### Attribute: rotation\_interval - -Rotation interval for the file defined in *perfdata\_path*. - -### Type: IdoMySqlConnection - -IDO DB schema compatible output into mysql database. - -Example - - library "ido_mysql" - local object IdoMysqlDbConnection "mysql-ido" { - host = "127.0.0.1", - port = "3306", - user = "icinga", - password = "icinga", - database = "icinga", - table_prefix = "icinga_", - instance_name = "icinga2", - instance_description = "icinga2 dev instance" - } - -#### Attribute: host - -MySQL database host address. Default is *localhost*. - -#### Attribute: port - -MySQL database port. Default is *3306*. - -#### Attribute: user - -MySQL database user with read/write permission to the icinga database. -Default is *icinga*. - -#### Attribute: password - -MySQL database user’s password. Default is *icinga*. - -#### Attribute: database - -MySQL database name. Default is *icinga*. - -#### Attribute: table\_prefix - -MySQL database table prefix. Default is *icinga\_*. - -#### Attribute: instance\_name - -Unique identifier for the local Icinga 2 instance. - -#### Attribute: instance\_description - -Optional. Description for the Icinga 2 instance. - -### Type: LiveStatusComponent - -Livestatus api interface available as tcp or unix socket. - -Example - - library "livestatus" - - local object LivestatusComponent "livestatus-tcp" { - socket_type = "tcp", - host = "127.0.0.1", - port = "6558" - } - - local object LivestatusComponent "livestatus-unix" { - socket_type = "unix", - socket_path = "/var/run/icinga2/livestatus" - } - -#### Attribute: socket\_type - -*tcp* or *unix* socket. Default is *unix*. - -> **Note** -> -> *unix* sockets are not supported on Windows. - -#### Attribute: host - -Only valid when socket\_type="tcp". Host address to listen on for -connections. - -#### Attribute: port - -Only valid when socket\_type="tcp". Port to listen on for connections. - -#### Attribute: socket\_path - -Only valid when socket\_type="unix". Local unix socket file. Not -supported on Windows. - -Configuration Examples ----------------------- - -### Non-networked minimal example - -> **Note** -> -> Icinga 2 ITL provides itl/standalone.conf which loads all required -> components, as well as itl/itl.conf includes many object templates -> already for an easy start with Icinga 2. - - local object IcingaApplication "icinga" { - - } - - local object Component "checker" { - - } - - local object Component "delegation" { - - } - - object CheckCommand "ping" { - command = "$plugindir$/check_ping -H $address$ -w $wrta$,$wpl$% -c $crta$,$cpl$%", - } - - template Service "icinga-service" { - methods = { - check = "PluginCheck" - }, - - macros = { - plugindir = "/usr/lib/nagios/plugins" - } - } - - template Service "ping-tmpl" inherits "icinga-service" { - check_command = "ping", - macros += { - wrta = 50, - wpl = 5, - crta = 100, - cpl = 10 - } - } - - object Host "localhost" { - services["ping"] = { templates = "ping-tmpl" }, - - macros = { - address = "127.0.0.1" - }, - - check_interval = 10m - } - -> **Note** -> -> You may also want to load the "compat" component if you want Icinga 2 -> to write status.dat and objects.cache files. - -/\* vim: set syntax=asciidoc filetype=asciidoc: \*/ - -/\* vim: set syntax=asciidoc filetype=asciidoc: \*/ -- 2.40.0