diff --git a/docs/Makefile.am b/docs/Makefile.am index b6f3665b2..716768ed5 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,8 +1,10 @@ .PHONY: clean EXTRA_DIST = \ - icinga2-config.txt \ + icinga2-config-syntax.txt \ + icinga2-config-types.txt \ icinga2-intro.txt \ + icinga2-tutorial.txt \ icinga2.8 icinga2docdir = ${docdir} @@ -15,8 +17,10 @@ man8_MANS = \ if AD_COND_doc icinga2doc_DATA += \ - icinga2-config.html \ - icinga2-intro.html + icinga2-config-syntax.html \ + icinga2-config-types.html \ + icinga2-intro.html \ + icinga2-tutorial.html .txt.html: $(AD_ENV) $(AD_ASCIIDOC) -a toc -a numbered -o $@ $< diff --git a/docs/icinga2-config-syntax.txt b/docs/icinga2-config-syntax.txt new file mode 100644 index 000000000..b5a53ef56 --- /dev/null +++ b/docs/icinga2-config-syntax.txt @@ -0,0 +1,449 @@ +Icinga 2 Configuration +====================== + +: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. + +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.txt b/docs/icinga2-config-types.txt similarity index 100% rename from docs/icinga2-config.txt rename to docs/icinga2-config-types.txt diff --git a/docs/icinga2-tutorial.txt b/docs/icinga2-tutorial.txt new file mode 100644 index 000000000..b4722d37e --- /dev/null +++ b/docs/icinga2-tutorial.txt @@ -0,0 +1,310 @@ +Icinga 2 Configuration +====================== + +: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 setting up Icinga 2 in order to +monitor network services. 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 Debian or RPM packages depending on which Linux distribution +you are running. + + + +In case you're running a distribution for which Icinga 2 packages are not available +you will have to check out the Icinga 2 git repository from git://git.icinga.org/icinga2 +and run the "autogen.sh" script and follow its instructions to get Icinga 2 installed. + +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 (a collection of configuration fragments). +|/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 + +local 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. The Icinga Template Library (ITL) is a +collection of templates for commonly used templates. + +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 setting one global macro named 'plugindir' which you may need to update +with your plugin directory's path. + +You can verify that your configuration file works by starting Icinga 2: + +------------------------------------------------------------------------------- +$ /usr/sbin/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 by hitting 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. Edit your +'icinga2.conf' configuration file by adding the following lines: + +------------------------------------------------------------------------------- +template Service "my-ping" inherits "plugin-service" { + check_command = [ + "$plugindir$/check_ping", + "-H", "$address$", + "-w", "10,5%", + "-c", "25,10%" + ] +} + +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 service template called "my-ping" which inherits from the +'plugin-service' template. The 'plugin-service' template is provided as part of +the ITL and describes how services are checked. In the case of plugin-based services +this means that the command specified by the 'check_command' property is executed. + +The 'check_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 how the 'my-ping' template 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). + +Next we're defining a 'Host' object with name 'localhost'. We're setting an optional +display_name which is used by the CGIs when showing that host in the host list. + +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 'check_command' setting earlier? Now we're +defining a value for this macro which is used for all services 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 defining which of the services we've defined 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 CGIs +------------------------------ + +Icinga 2 can write status.dat and objects.cache files in the format that is supported +by the Icinga 1.x CGIs. + +In order to do this you will need to load the library 'compat' by adding the following lines +to your configuration file: + +------------------------------------------------------------------------------- +library "compat" + +local object CompatComponent "compat" { } +------------------------------------------------------------------------------- + +After restarting Icinga 2 you should be able to find the status.dat and objects.cache files in +/var/cache/icinga2. + +You can create symlinks in your Icinga 1.x installation directory to make the CGIs use +Icinga 2's status files and its command pipe: + +------------------------------------------------------------------------------- +cd /usr/local/icinga # Change this to your Icinga 1.x installation directory +ln -sf /var/cache/icinga2/status.dat var/status.dat +ln -sf /var/cache/icinga2/objects.cache var/objects.cache +ln -sf /var/run/icinga2/icinga2.cmd var/rw/icinga.cmd +------------------------------------------------------------------------------- + +Verify that your Icinga 1.x CGIs work by browsing to your CGI's installation URL. + +Some More Templates +------------------- + +Now that we've got a work basic monitoring setup as well as the CGIs 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 CGIs for your new service's state. Unless +you have a low-latency network connection you will note that the service's state is 'CRITICAL'. + +Ideally we'd be able to specify different timeouts for our new service. Using macros we +can easily do this. + +Start by replacing your 'my-ping' service template with this: + +------------------------------------------------------------------------------- +template Service "my-ping" inherits "plugin-service" { + check_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. + +In order to oderride some of these macros for a specific host we need to update our +host 'icinga.org' 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 modify an existing dictionary. If we were +to use the '=' operator instead we would have to provide values for all the macros from +the 'my-ping' template. + +ITL +--- + +TODO + +Notifications +------------- + +TODO + +Time Periods +------------ + +TODO + +Host/Service Groups +------------------- + +TODO