From 3f8006b8fa9591652319c1c32b284c0115eb9c05 Mon Sep 17 00:00:00 2001 From: Gunnar Beutner Date: Mon, 30 Sep 2013 12:57:08 +0200 Subject: [PATCH] Remove asciidoc files. --- Makefile.am | 2 +- configure.ac | 7 +- doc/.gitignore | 6 +- {docs => doc}/Doxyfile.in | 0 doc/Makefile.am | 23 + {docs => doc}/icinga2.8 | 0 docs/.gitignore | 5 - docs/Makefile.am | 45 -- docs/icinga2-compat.adoc | 126 ---- docs/icinga2-config-syntax.adoc | 451 ------------- docs/icinga2-config-types.adoc | 1106 ------------------------------- docs/icinga2-config.adoc | 80 --- docs/icinga2-install.adoc | 67 -- docs/icinga2-intro.adoc | 252 ------- docs/icinga2-main.adoc | 55 -- docs/icinga2-migration.adoc | 39 -- docs/icinga2-tutorial.adoc | 788 ---------------------- docs/icinga2.adoc | 38 -- m4/ax_prog_asciidoc.m4 | 140 ---- 19 files changed, 32 insertions(+), 3198 deletions(-) rename {docs => doc}/Doxyfile.in (100%) create mode 100644 doc/Makefile.am rename {docs => doc}/icinga2.8 (100%) delete mode 100644 docs/.gitignore delete mode 100644 docs/Makefile.am delete mode 100644 docs/icinga2-compat.adoc delete mode 100644 docs/icinga2-config-syntax.adoc delete mode 100644 docs/icinga2-config-types.adoc delete mode 100644 docs/icinga2-config.adoc delete mode 100644 docs/icinga2-install.adoc delete mode 100644 docs/icinga2-intro.adoc delete mode 100644 docs/icinga2-main.adoc delete mode 100644 docs/icinga2-migration.adoc delete mode 100644 docs/icinga2-tutorial.adoc delete mode 100644 docs/icinga2.adoc delete mode 100644 m4/ax_prog_asciidoc.m4 diff --git a/Makefile.am b/Makefile.am index 9fb31406d..28b45474c 100644 --- a/Makefile.am +++ b/Makefile.am @@ -14,7 +14,7 @@ SUBDIRS = \ test \ itl \ etc \ - docs + doc #doc icinga2docdir = ${docdir} diff --git a/configure.ac b/configure.ac index c5c22b1c4..4b9dded9c 100644 --- a/configure.ac +++ b/configure.ac @@ -91,8 +91,7 @@ DX_RTF_FEATURE(OFF) DX_XML_FEATURE(OFF) DX_PDF_FEATURE(OFF) DX_PS_FEATURE(OFF) -DX_INIT_DOXYGEN([icinga], [docs/Doxyfile], [docs/dev]) -AD_INIT_ASCIIDOC([icinga], [docs]) +DX_INIT_DOXYGEN([icinga], [doc/Doxyfile], [doc/dev]) AC_PROG_INSTALL AC_PROG_LEX @@ -171,8 +170,8 @@ components/demo/Makefile components/db_ido_mysql/Makefile components/livestatus/Makefile components/notification/Makefile -docs/Doxyfile -docs/Makefile +doc/Doxyfile +doc/Makefile etc/Makefile etc/icinga2/Makefile etc/icinga2/conf.d/Makefile diff --git a/doc/.gitignore b/doc/.gitignore index dcaf71693..1dce93ba6 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1 +1,5 @@ -index.html +Doxyfile +icinga2.html +icinga2-*.html +icinga2.8 +.directory diff --git a/docs/Doxyfile.in b/doc/Doxyfile.in similarity index 100% rename from docs/Doxyfile.in rename to doc/Doxyfile.in diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 000000000..921c87597 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,23 @@ +.PHONY: clean + +EXTRA_DIST = \ + 1-about.md \ + 2.0-getting-started.md \ + 2.1.1-setting-up-icinga-2.md \ + 2.1.2-setting-up-icinga-classic-ui.md \ + 2.1.3-setting-up-check-plugins.md \ + 2.1.4-setting-up-ido.md \ + 2.2-running-icinga.md \ + 2.3-monitoring-basics.md \ + 3.1-configuration-syntax.md \ + 3.2-global-variables.md \ + 3.3-object-types.md \ + 3-configuring-icinga.md \ + 4-advanced-topics.md + +icinga2docdir = ${docdir} +icinga2doc_DATA = + +man8_MANS = \ + icinga2.8 + diff --git a/docs/icinga2.8 b/doc/icinga2.8 similarity index 100% rename from docs/icinga2.8 rename to doc/icinga2.8 diff --git a/docs/.gitignore b/docs/.gitignore deleted file mode 100644 index 1dce93ba6..000000000 --- a/docs/.gitignore +++ /dev/null @@ -1,5 +0,0 @@ -Doxyfile -icinga2.html -icinga2-*.html -icinga2.8 -.directory diff --git a/docs/Makefile.am b/docs/Makefile.am deleted file mode 100644 index 85d8520a9..000000000 --- a/docs/Makefile.am +++ /dev/null @@ -1,45 +0,0 @@ -.PHONY: clean - -EXTRA_DIST = \ - icinga2.adoc \ - icinga2-compat.adoc \ - icinga2-config.adoc \ - icinga2-config-syntax.adoc \ - icinga2-config-types.adoc \ - icinga2-install.adoc \ - icinga2-intro.adoc \ - icinga2-tutorial.adoc \ - icinga2-main.adoc \ - icinga2-migration.adoc \ - icinga2.8 - -icinga2docdir = ${docdir} -icinga2doc_DATA = - -man8_MANS = \ - icinga2.8 - -.SUFFIXES = .html .adoc - -if AD_COND_doc -icinga2doc_DATA += \ - icinga2.html \ - icinga2-compat.html \ - icinga2-config.html \ - icinga2-config-syntax.html \ - icinga2-config-types.html \ - icinga2-install.html \ - icinga2-intro.html \ - icinga2-tutorial.html \ - icinga2-main.html \ - icinga2-migration.html - -.adoc.html: - $(AD_ENV) $(AD_ASCIIDOC) -d book -a toc -a numbered -o $@ $< -endif AD_COND_doc - -clean: - rm -f $(icinga2doc_DATA) - -distclean: - rm -f $(icinga2doc_DATA) diff --git a/docs/icinga2-compat.adoc b/docs/icinga2-compat.adoc deleted file mode 100644 index 64e345b55..000000000 --- a/docs/icinga2-compat.adoc +++ /dev/null @@ -1,126 +0,0 @@ -Icinga 2 Compatibility -====================== - -:keywords: Icinga, documentation, migration -:description: Icinga 2 Migration - -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 link::icinga2-config.html[Configuration] - -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 - - -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.adoc b/docs/icinga2-config-syntax.adoc deleted file mode 100644 index 08e27e6ba..000000000 --- a/docs/icinga2-config-syntax.adoc +++ /dev/null @@ -1,451 +0,0 @@ -Icinga 2 Configuration Syntax -============================= - -:keywords: Icinga, documentation, configuration -:description: Description of the Icinga 2 config - -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.adoc b/docs/icinga2-config-types.adoc deleted file mode 100644 index 5e606d1b7..000000000 --- a/docs/icinga2-config-types.adoc +++ /dev/null @@ -1,1106 +0,0 @@ -Icinga 2 Configuration Types -============================ - -:keywords: Icinga, documentation, configuration -:description: Description of the Icinga 2 config - -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.adoc b/docs/icinga2-config.adoc deleted file mode 100644 index 3467ce5dc..000000000 --- a/docs/icinga2-config.adoc +++ /dev/null @@ -1,80 +0,0 @@ -Icinga 2 Configuration -====================== - -:keywords: Icinga, documentation, index -:description: Main index of Icinga 2 documentation - -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.adoc b/docs/icinga2-install.adoc deleted file mode 100644 index 7c4bd3b0c..000000000 --- a/docs/icinga2-install.adoc +++ /dev/null @@ -1,67 +0,0 @@ -Icinga 2 Installation -===================== - -:keywords: Icinga, documentation, installation -:description: 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 - -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 - -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.adoc b/docs/icinga2-intro.adoc deleted file mode 100644 index 086d53150..000000000 --- a/docs/icinga2-intro.adoc +++ /dev/null @@ -1,252 +0,0 @@ -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(TM) 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(TM) configuration format. This has the advantage of allowing users to -easily upgrade their existing Nagios(TM) installations as well as downgrading -if they choose to do so (even though this is generally not the case). - -The Nagios(TM) 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(TM) 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(TM)-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(TM)-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(TM)-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.adoc b/docs/icinga2-main.adoc deleted file mode 100644 index 065d975dd..000000000 --- a/docs/icinga2-main.adoc +++ /dev/null @@ -1,55 +0,0 @@ -Icinga 2 Main -============= - -:keywords: Icinga, documentation, index -:description: Main index of Icinga 2 documentation - -Introduction ------------- - -A detailed introduction can be found in the chapter link:icinga2-intro.html[Introduction]. /* TODO insert url */ - -Installation ------------- - -For more information see the chapter Installation. /* TODO insert url */ - -Quick Example -------------- - -/* TODO */ - -For a general tutorial see the chapter link:icinga2-tutorial.html[Tutorial]. /* 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 ---------- - -* http://webchat.freenode.net/?channels=icinga[#icinga] on the Freenode IRC Network -* https://lists.sourceforge.net/lists/listinfo/icinga-users[Mailinglists] -* http://www.monitoring-portal.org[Monitoring Portal] - -More details at http://www.icinga.org/support/ - -Support -------- - -For more information on the support options refer to https://www.icinga.org/support - - -Chapters --------- - -/* TODO */ - -/* vim: set syntax=asciidoc filetype=asciidoc: */ diff --git a/docs/icinga2-migration.adoc b/docs/icinga2-migration.adoc deleted file mode 100644 index 99bd03d6a..000000000 --- a/docs/icinga2-migration.adoc +++ /dev/null @@ -1,39 +0,0 @@ -Icinga 2 Migration -================== - -:keywords: Icinga, documentation, migration -:description: 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 link:icinga2-compat.html[Compatibility]. - -Changes -------- - -For details check the chapter link:icinga2-compat.html[Changes]. - -TODO - -/* vim: set syntax=asciidoc filetype=asciidoc: */ diff --git a/docs/icinga2-tutorial.adoc b/docs/icinga2-tutorial.adoc deleted file mode 100644 index a33ee5d0a..000000000 --- a/docs/icinga2-tutorial.adoc +++ /dev/null @@ -1,788 +0,0 @@ -Icinga 2 Tutorial -================= - -:keywords: Icinga, documentation, installation, configuration, tutorial -:description: Quick introduction to monitoring network services with Icinga 2 - -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: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 - -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 - -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 < -# -# Copying and distribution of this file, with or without modification, are -# permitted in any medium without royalty provided the copyright notice -# and this notice are preserved. This file is offered as-is, without any -# warranty. - -#serial 12 - -## ----------## -## Defaults. ## -## ----------## - -AD_ENV="" -AC_DEFUN([AD_FEATURE_doc], ON) - -## --------------- ## -## Private macros. ## -## --------------- ## - -# AD_ENV_APPEND(VARIABLE, VALUE) -# ------------------------------ -# Append VARIABLE="VALUE" to AD_ENV for invoking asciidoc. -AC_DEFUN([AD_ENV_APPEND], [AC_SUBST([AD_ENV], ["$AD_ENV $1='$2'"])]) - -# AD_DIRNAME_EXPR -# --------------- -# Expand into a shell expression prints the directory part of a path. -AC_DEFUN([AD_DIRNAME_EXPR], - [[expr ".$1" : '\(\.\)[^/]*$' \| "x$1" : 'x\(.*\)/[^/]*$']]) - -# AD_IF_FEATURE(FEATURE, IF-ON, IF-OFF) -# ------------------------------------- -# Expands according to the M4 (static) status of the feature. -AC_DEFUN([AD_IF_FEATURE], [ifelse(AD_FEATURE_$1, ON, [$2], [$3])]) - -# AD_REQUIRE_PROG(VARIABLE, PROGRAM) -# ---------------------------------- -# Require the specified program to be found for the AD_CURRENT_FEATURE to work. -AC_DEFUN([AD_REQUIRE_PROG], [ -AC_PATH_TOOL([$1], [$2]) -if test "$AD_FLAG_[]AD_CURRENT_FEATURE$$1" = 1; then - AC_MSG_WARN([$2 not found - will not AD_CURRENT_DESCRIPTION]) - AC_SUBST(AD_FLAG_[]AD_CURRENT_FEATURE, 0) -fi -]) - -# AD_TEST_FEATURE(FEATURE) -# ------------------------ -# Expand to a shell expression testing whether the feature is active. -AC_DEFUN([AD_TEST_FEATURE], [test "$AD_FLAG_$1" = 1]) -# AD_FEATURE_ARG(FEATURE, DESCRIPTION, -# CHECK_DEPEND, CLEAR_DEPEND, -# REQUIRE, DO-IF-ON, DO-IF-OFF) -# -------------------------------------------- -# Parse the command-line option controlling a feature. CHECK_DEPEND is called -# if the user explicitly turns the feature on (and invokes AD_CHECK_DEPEND), -# otherwise CLEAR_DEPEND is called to turn off the default state if a required -# feature is disabled (using AD_CLEAR_DEPEND). REQUIRE performs additional -# requirement tests (AD_REQUIRE_PROG). Finally, an automake flag is set and -# DO-IF-ON or DO-IF-OFF are called according to the final state of the feature. -AC_DEFUN([AD_ARG_ABLE], [ - AC_DEFUN([AD_CURRENT_FEATURE], [$1]) - AC_DEFUN([AD_CURRENT_DESCRIPTION], [$2]) - AC_ARG_ENABLE(asciidoc-$1, - [AS_HELP_STRING(AD_IF_FEATURE([$1], [--disable-asciidoc-$1], - [--enable-asciidoc-$1]), - AD_IF_FEATURE([$1], [don't $2], [$2]))], - [ -case "$enableval" in -#( -y|Y|yes|Yes|YES) - AC_SUBST([AD_FLAG_$1], 1) - $3 -;; #( -n|N|no|No|NO) - AC_SUBST([AD_FLAG_$1], 0) -;; #( -*) - AC_MSG_ERROR([invalid value '$enableval' given to asciidoc-$1]) -;; -esac -], [ -AC_SUBST([AD_FLAG_$1], [AD_IF_FEATURE([$1], 1, 0)]) -$4 -]) -if AD_TEST_FEATURE([$1]); then - $5 - : -fi -AM_CONDITIONAL(AD_COND_$1, AD_TEST_FEATURE([$1])) -if AD_TEST_FEATURE([$1]); then - $6 - : -else - $7 - : -fi -]) - -## -------------- ## -## Public macros. ## -## -------------- ## - -# AD_XXX_FEATURE(DEFAULT_STATE) -# ----------------------------- -AC_DEFUN([AD_ASCIIDOC_FEATURE], [AC_DEFUN([AD_FEATURE_asciidoc], [$1])]) - -# AD_INIT_ASCIIDOC(PROJECT, [OUTPUT-DOC-DIR]) -# --------------------------------------------------------- -# PROJECT also serves as the base name for the documentation files. -AC_DEFUN([AD_INIT_ASCIIDOC], [ - -# Files: -AC_SUBST([AD_PROJECT], [$1]) -AC_SUBST([AD_DOCDIR], [ifelse([$2], [], docs, [$2])]) - -# Asciidoc itself: -AD_ARG_ABLE(doc, [generate any asciidoc documentation], - [], - [], - [AD_REQUIRE_PROG([AD_ASCIIDOC], asciidoc)] - ) -]) -- 2.40.0