diff --git a/doc/2.1.1-setting-up-icinga-2.md b/doc/2.1.1-setting-up-icinga-2.md index 3350a2e9b..c46acb49d 100644 --- a/doc/2.1.1-setting-up-icinga-2.md +++ b/doc/2.1.1-setting-up-icinga-2.md @@ -15,6 +15,10 @@ Packages for distributions other than the ones listed above may also be available. Please check http://packages.icinga.org/ to see if packages are available for your favorite distribution. +You can install Icinga 2 by using your distribution's package manager +to install the *icinga2* package. Some parts of Icinga 2's functionality +are available as separate packages. + In case you're running a distribution for which Icinga 2 packages are not yet available you will have to use the release tarball which you can download from the [Icinga website](https://www.icinga.org/). The diff --git a/doc/2.1.2-setting-up-icinga-classic-ui.md b/doc/2.1.2-setting-up-icinga-classic-ui.md index 7f1920bfc..492e92b3b 100644 --- a/doc/2.1.2-setting-up-icinga-classic-ui.md +++ b/doc/2.1.2-setting-up-icinga-classic-ui.md @@ -30,6 +30,20 @@ following commands: > found on the Icinga Wiki here: > [https://wiki.icinga.org/display/howtos/Setting+up+Icinga+Classic+UI+Standalone](https://wiki.icinga.org/display/howtos/Setting+up+Icinga+Classic+UI+Standalone) +#### Configuring Icinga 2 + +By default Icinga 2 does not write *status.dat* and *objects.cache* files which are used +by the Classic UI. The command pipe is also not enabled by default. + +You can use i2enfeature to enable these features: + + # i2enfeature statusdat + # i2enfeature command + +After enabling these features you will need to restart Icinga 2: + + # /etc/init.d/icinga2 restart + #### Configuring the Classic UI After installing the Classic UI you will need to update the following diff --git a/doc/2.1.4-setting-up-ido.md b/doc/2.1.4-setting-up-ido.md index af661a6d1..3ecbf00ed 100644 --- a/doc/2.1.4-setting-up-ido.md +++ b/doc/2.1.4-setting-up-ido.md @@ -1,14 +1,15 @@ ### Configuring IDO The IDO (Icinga Data Output) modules for Icinga 2 takes care of exporting all -configuration and status information into a database. +configuration and status information into a database. The IDO database is used +by a number of projects including Icinga Web. There is a separate module for each database backend. At present only support for MySQL is implemented. #### Setting up the database -First of all you will need to create a database for Icinga 2: +First of all you have to create a database for Icinga 2: # mysql -u root -p @@ -29,14 +30,13 @@ First of all you will need to create a database for Icinga 2: mysql> quit After creating the database you can import the Icinga 2 IDO schema using the -following commands: +following command: - # cd /path/to/icinga-src/components/db_ido_mysql/schema - # mysql -u root -p icinga < mysql.sql + # mysql -u root -p icinga < /path/to/icinga-src/components/db_ido_mysql/schema/mysql.sql #### Installing the IDO module -Once you've set up your database you will need to install the *icinga2-ido-mysql* +Once you've set up your database you have to install the *icinga2-ido-mysql* package using your distribution's package manager. The package provides a new configuration file that is installed in @@ -49,6 +49,6 @@ You can enable the ido-mysql feature configuration file using *i2enfeature*: Module 'ido-mysql' was enabled. Make sure to restart Icinga 2 for these changes to take effect. -After enabling the ido-mysql feature you will need to restart Icinga 2: +After enabling the ido-mysql feature you have to restart Icinga 2: - # /etc/init.d/icinga2 restart \ No newline at end of file + # /etc/init.d/icinga2 restart diff --git a/doc/2.3-monitoring-basics.md b/doc/2.3-monitoring-basics.md index be56ae06f..2ca08f988 100644 --- a/doc/2.3-monitoring-basics.md +++ b/doc/2.3-monitoring-basics.md @@ -1,12 +1,85 @@ ## Monitoring Basics -### Hosts +This part of the Icinga 2 documentation provides an overview of all the basic +monitoring concepts you need to know to run Icinga 2. -TODO +### Hosts and Services -### Services +Icinga 2 can be used to monitor the availability of hosts and services. Services +can be virtually anything which can be checked in some way: -TODO +* Network services (HTTP, SMTP, SNMP, SSH, etc.) +* Printers +* Switches / Routers +* Temperature Sensors +* Other local or network-accessible services + +Host objects provide a mechanism to group together services that are running +on the same physical device. + +Here is an example of a host object which defines two child services: + + object Host "my-server1" { + services["ping4"] = { + check_command = "ping4" + }, + + services["http"] = { + check_command = "http_ip" + }, + + check = "ping4", + + macros["address"] = "10.0.0.1" + } + +The example host *my-server1* creates two services which belong to this host: +*ping4* and *http*. + +It also specifies that the host should inherit its availability state from the +*ping4* service. + +> **Note** +> +> In Icinga 1.x hosts had their own check command, check interval and +> notification settings. Instead, in Icinga 2 hosts inherit their state +> from one of its child services. No checks are performed for the host +> itself. + +The *address* macro is used by check commands to determine which network +address is associated with the host object. + +#### Host States + + Name | Description + ------------|-------------- + UP | The host is available. + DOWN | The host is unavailable. + UNREACHABLE | At least one of the host's dependencies (e.g. its upstream router) is unavailable causing the host to be unreachable. + +#### Service States + + Name | Description + ------------|-------------- + OK | The service is fully available. + WARNING | The service is experiencing some problems but is still considered available. + CRITICAL | The service is in a critical state. + UNKNOWN | The check could not determine the service's state. + +#### Hard and Soft States + +When detecting a problem with a service Icinga re-checks the service a number of +times (based on the *max_check_attempts* and *retry_interval* settings) before sending +notifications. This ensures that no unnecessary notifications are sent for +transient failures. During this time the service is in a *SOFT* state. + +After all re-checks have been executed and the service is still in a non-OK +state the service switches to a *HARD* state and notifications are sent. + + Name | Description + ------------|-------------- + HARD | The host/service's state hasn't recently changed. + SOFT | The host/service has recently changed state and is being re-checked. ### Check Commands @@ -14,25 +87,187 @@ TODO ### Macros -TODO +Macros may be used in command definitions to dynamically change how the command +is executed. -## Using Templates +Here is an example of a command definition which uses user-defined macros: + + object CheckCommand "my-ping" 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 + } + } + +> **Note** +> +> If you have previously used Icinga 1.x you may already be familiar with +> user and argument macros (e.g., USER1 or ARG1). Unlike in Icinga 1.x macros +> may have arbitrary names and arguments are no longer specified in the +> check_command setting. + +Macro names must be enclosed in two *$* signs, e.g. *$plugindir$*. When +executing the command Icinga 2 checks the following objects in this +order to look up macros: + +1. User object (only for notifications) +2. Service object +3. Host object +4. Command object +5. Global macros in the IcingaMacros variable + +This execution order allows you to define default values for macros in your +command objects. The *my-ping* command shown above uses this to set default +values for some of the latency thresholds and timeouts. + +When using the *my-ping* command you can overwrite all or some of the macros +in the service definition like this: + + object Host "my-server1" { + services["ping"] = { + check_command = "my-ping", + + macros["packets"] = 10 // Overwrites the default value of 5 given in the command + }, + + macros["address"] = "10.0.0.1" + } + +If a macro isn't defined anywhere an empty value is used and a warning is +emitted to the Icinga 2 log. + +> **Note** +> +> Macros in capital letters (e.g. HOSTNAME) are reserved for use by Icinga 2 +> and should not be overwritten by users. + +By convention every host should have an *address* macro. Hosts +which have an IPv6 address should also have an *address6* macro. + +The *plugindir* macro should be set to the path of your check plugins. The +*/etc/icinga2/conf.d/macros.conf* file is usually used to define global macros +including this one. + +#### Host Macros + +The following host macros are available in all commands that are executed for +hosts or services: + + Name | Description + -----------------------|-------------- + HOSTNAME |The name of the host object. + HOSTDISPLAYNAME |The value of the display_name attribute. + HOSTALIAS |This is an alias for the *HOSTDISPLAYNAME* macro. + HOSTSTATE |The host's current state. Can be one of UNREACHABLE, UP and DOWN. + HOSTSTATEID |The host's current state. Can be one of 0 (up), 1 (down) and 2 (unreachable). + HOSTSTATETYPE |The host's current state type. Can be one of SOFT and HARD. + HOSTATTEMPT |The current check attempt number. + MAXHOSTATTEMPT |The maximum number of checks which are executed before changing to a hard state. + LASTHOSTSTATE |The host's previous state. Can be one of UNREACHABLE, UP and DOWN. + LASTHOSTSTATEID |The host's previous state. Can be one of 0 (up), 1 (down) and 2 (unreachable). + LASTHOSTSTATETYPE |The host's previous state type. Can be one of SOFT and HARD. + HOSTLATENCY |The host's check latency. + HOSTEXECUTIONTIME |The host's check execution time. + HOSTOUTPUT |The last check's output. + HOSTPERFDATA |The last check's performance data. + LASTHOSTCHECK |The timestamp when the last check was executed. + HOSTADDRESS |This is an alias for the *address* macro. If the *address* macro is not defined the host object's name is used instead. + HOSTADDRESS6 |This is an alias for the *address6* macro. If the *address* macro is not defined the host object's name is used instead. + +#### Service Macros + +The following service macros are available in all commands that are executed for +services: + + Name | Description + -----------------------|-------------- + SERVICEDESC |The short name of the service object. + SERVICEDISPLAYNAME |The value of the display_name attribute. + SERVICECHECKCOMMAND |This is an alias for the *SERVICEDISPLAYNAME* macro. + SERVICESTATE |The service's current state. Can be one of OK, WARNING, CRITICAL, UNCHECKABLE and UNKNOWN. + SERVICESTATEID |The service's current state. Can be one of 0 (ok), 1 (warning), 2 (critical), 3 (unknown) and 4 (uncheckable). + SERVICESTATETYPE |The service's current state type. Can be one of SOFT and HARD. + SERVICEATTEMPT |The current check attempt number. + MAXSERVICEATTEMPT |The maximum number of checks which are executed before changing to a hard state. + LASTSERVICESTATE |The service's previous state. Can be one of OK, WARNING, CRITICAL, UNCHECKABLE and UNKNOWN. + LASTSERVICESTATEID |The service's previous state. Can be one of 0 (ok), 1 (warning), 2 (critical), 3 (unknown) and 4 (uncheckable). + LASTSERVICESTATETYPE |The service's previous state type. Can be one of SOFT and HARD. + LASTSERVICESTATECHANGE |The last state change's timestamp. + SERVICELATENCY |The service's check latency. + SERVICEEXECUTIONTIME |The service's check execution time. + SERVICEOUTPUT |The last check's output. + SERVICEPERFDATA |The last check's performance data. + LASTSERVICECHECK |The timestamp when the last check was executed. + +#### User Macros + +The following service macros are available in all commands that are executed for +users: + + Name | Description + -----------------------|--------------- + CONTACTNAME | The name of the user object. + CONTACTALIAS | The value of the display_name attribute. + CONTACTEMAIL | This is an alias for the *email* macro. + CONTACTPAGER | This is an alias for the *pager* macro. + +### Using Templates + +Templates may be used to apply a set of similar settings to more than one +object. + +For example, rather than manually creating a *ping* service object for each of +your hosts you can use templates to avoid having to copy & paste parts of your +config: + + template Host "linux-server" { + services["ping"] = { + check_command = "ping4" + }, + + check = "ping4" + } + + object Host "my-server1" inherits "linux-server" { + macros["address"] = "10.0.0.1" + } + + object Host "my-server2" inherits "linux-server" { + macros["address"] = "10.0.0.2" + } + +In this example both *my-server1* and *my-server2* each get their own ping +service check. + +Objects as well as templates themselves can inherit from an arbitrary number of +templates. Attributes inherited from a template can be overwritten in the +object if necessary. + +### Groups TODO -## Groups +### Host/Service Dependencies TODO -## Host/Service Dependencies - -TODO - -## Time Periods - -TODO - -## Notifications +### Notifications TODO diff --git a/doc/3.3-object-types.md b/doc/3.3-object-types.md index 5eeb7cae1..b0abe999f 100644 --- a/doc/3.3-object-types.md +++ b/doc/3.3-object-types.md @@ -106,15 +106,15 @@ Attributes: display_name |**Optional.** A short description of the service. macros |**Optional.** check\_command |**Required.** The name of the check command. - max\_check\_attempts|TODO + max\_check\_attempts|**Optional.** The number of times a service is re-checked before changing into a hard state. Defaults to 3. check\_period |**Optional.** The name of a time period which determines when this service should be checked. Not set by default. - check\_interval |**Optional.** The check interval (in seconds). - retry\_interval |**Optional.** The retry interval (in seconds). This is used when the service is in a soft state. Defaults to 1/5th of the check interval if not specified. + check\_interval |**Optional.** The check interval (in seconds). This interval is used for checks when the service is in a *HARD* state. Defaults to 5 minutes. + retry\_interval |**Optional.** The retry interval (in seconds). This interval is used for checks when the service is in a *SOFT* state. Defaults to 1/5th of the check interval if not specified. event\_command |**Optional.** The name of an event command that should be executed every time the service's state changes. flapping\_threshold|TODO volatile |TODO - host\_dependencies|TODO - service\_dependencies|TODO + host_dependencies|**Optional.** A list of host names which this host depends on. These dependencies are used to determine whether the host is unreachable. + service_dependencies|**Optional.** A list of services which this host depends on. Each array element must be a dictionary containing the keys "host" and "service". These dependencies are used to determine whether the host is unreachable. groups |**Optional.** The service groups this service belongs to. notifications |TODO @@ -397,10 +397,11 @@ Example: database = "icinga", table_prefix = "icinga_", instance_name = "icinga2", - instance_description = "icinga2 dev instance" + instance_description = "icinga2 dev instance", + cleanup = { downtimehistory_age = 48h, - logentries_age = 31d, + logentries_age = 31d, } } @@ -420,22 +421,23 @@ Attributes: Cleanup Items: + Name | Description ----------------|---------------- - acknowledgement_age |**Optional.** Max age for acknowledgement table rows (entry_time) - commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time) - contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time) - contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time) - downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time) - eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time) - externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time) - flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time) - hostchecks_age |**Optional.** Max age for hostchecks table rows (start_time) - logentries_age |**Optional.** Max age for logentries table rows (logentry_time) - notifications_age |**Optional.** Max age for notifications table rows (start_time) - processevents_age |**Optional.** Max age for processevents table rows (event_time) - statehistory_age |**Optional.** Max age for statehistory table rows (state_time) - servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time) - systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time) + acknowledgement_age |**Optional.** Max age for acknowledgement table rows (entry_time). Defaults to 0 (never). + commenthistory_age |**Optional.** Max age for commenthistory table rows (entry_time). Defaults to 0 (never). + contactnotifications_age |**Optional.** Max age for contactnotifications table rows (start_time). Defaults to 0 (never). + contactnotificationmethods_age |**Optional.** Max age for contactnotificationmethods table rows (start_time). Defaults to 0 (never). + downtimehistory_age |**Optional.** Max age for downtimehistory table rows (entry_time). Defaults to 0 (never). + eventhandlers_age |**Optional.** Max age for eventhandlers table rows (start_time). Defaults to 0 (never). + externalcommands_age |**Optional.** Max age for externalcommands table rows (entry_time). Defaults to 0 (never). + flappinghistory_age |**Optional.** Max age for flappinghistory table rows (event_time). Defaults to 0 (never). + hostchecks_age |**Optional.** Max age for hostchecks table rows (start_time). Defaults to 0 (never). + logentries_age |**Optional.** Max age for logentries table rows (logentry_time). Defaults to 0 (never). + notifications_age |**Optional.** Max age for notifications table rows (start_time). Defaults to 0 (never). + processevents_age |**Optional.** Max age for processevents table rows (event_time). Defaults to 0 (never). + statehistory_age |**Optional.** Max age for statehistory table rows (state_time). Defaults to 0 (never). + servicechecks_age |**Optional.** Max age for servicechecks table rows (start_time). Defaults to 0 (never). + systemcommands_age |**Optional.** Max age for systemcommands table rows (start_time). Defaults to 0 (never). ### LiveStatusListener @@ -529,21 +531,27 @@ Attributes: ### CheckResultReader -TODO +Reads Icinga 1.x check results from a directory. This functionality is provided +to help existing Icinga 1.x users and might be useful for certain cluster +scenarios. Example: - TODO + library "compat" + + object CheckResultReader "reader" { + spool_dir = "/data/check-results" + } Attributes: Name |Description ----------------|---------------- - spool\_dir |TODO + spool\_dir |**Optional.** The directory which contains the check result files. Defaults to IcingaLocalStateDir + "/lib/icinga2/spool/checkresults/". ### CheckerComponent -TODO +The checker component is responsible for scheduling active checks. There are no configurable options. Example: @@ -553,7 +561,7 @@ Example: ### NotificationComponent -TODO +The notification component is responsible for sending notifications. There are no configurable options. Example: diff --git a/doc/4-icinga-template-library.md b/doc/4-icinga-template-library.md new file mode 100644 index 000000000..6fff5b877 --- /dev/null +++ b/doc/4-icinga-template-library.md @@ -0,0 +1,46 @@ +## Icinga Template Library + +TODO + +### Overview + +### Check Commands + +#### ping4 + +#### ping6 + +#### dummy + +#### tcp + +#### udp + +#### http_vhost + +#### http_ip + +#### https_vhost + +#### https_ip + +#### smtp + +#### ssmtp + +#### ntp_time + +#### ssh + +#### disk + +#### users + +#### processes + +#### load + +#### snmp + +#### snmp-uptime + diff --git a/doc/4-advanced-topics.md b/doc/5-advanced-topics.md similarity index 83% rename from doc/4-advanced-topics.md rename to doc/5-advanced-topics.md index e8ad2bf27..291c7cdb1 100644 --- a/doc/4-advanced-topics.md +++ b/doc/5-advanced-topics.md @@ -1,5 +1,7 @@ # Advanced Topics +## Time Periods + ## External Commands TODO