From d4d214d2e7b8341a728f551b4279ffb1e950d2e0 Mon Sep 17 00:00:00 2001 From: Gunnar Beutner Date: Thu, 22 Jan 2015 09:40:25 +0100 Subject: [PATCH] Update documentation --- doc/1-about.md | 349 +------- ...y-reference.md => 10-library-reference.md} | 0 ...{10-object-types.md => 11-object-types.md} | 38 +- ...brary.md => 12-icinga-template-library.md} | 4 +- doc/{12-appendix.md => 13-appendix.md} | 0 doc/2-getting-started.md | 784 +++--------------- doc/3-monitoring-basics.md | 208 ++--- doc/4-monitoring-remote-systems.md | 224 ++--- doc/5-cli-commands.md | 537 ++++++++++++ ...-addons-plugins.md => 6-addons-plugins.md} | 22 +- ...roubleshooting.md => 7-troubleshooting.md} | 22 +- ...ga-1x.md => 8-migrating-from-icinga-1x.md} | 60 +- ...e-reference.md => 9-language-reference.md} | 12 +- doc/update-links.py | 55 ++ 14 files changed, 1035 insertions(+), 1280 deletions(-) rename doc/{9-library-reference.md => 10-library-reference.md} (100%) rename doc/{10-object-types.md => 11-object-types.md} (96%) rename doc/{11-icinga-template-library.md => 12-icinga-template-library.md} (99%) rename doc/{12-appendix.md => 13-appendix.md} (100%) create mode 100644 doc/5-cli-commands.md rename doc/{5-addons-plugins.md => 6-addons-plugins.md} (83%) rename doc/{6-troubleshooting.md => 7-troubleshooting.md} (93%) rename doc/{7-migrating-from-icinga-1x.md => 8-migrating-from-icinga-1x.md} (95%) rename doc/{8-language-reference.md => 9-language-reference.md} (98%) create mode 100755 doc/update-links.py diff --git a/doc/1-about.md b/doc/1-about.md index ea828008a..8452642f1 100644 --- a/doc/1-about.md +++ b/doc/1-about.md @@ -17,7 +17,7 @@ LICENSE file included in the source package. ## Support Support for Icinga 2 is available in a number of ways. Please have a look at -the support overview page at https://support.icinga.org. +the [support overview page](https://support.icinga.org). ## Contribute @@ -46,285 +46,30 @@ More details in the [Icinga FAQ](https://www.icinga.org/icinga/faq/). * [Register](https://exchange.icinga.org/authentication/register) an Icinga account. * Create a new issue at the [Icinga 2 Development Tracker](https://dev.icinga.org/projects/i2). -* When reporting a bug, please include the details described in the [Troubleshooting](#troubleshooting-information-required) chapter (version, configs, logs, etc). - -## Demo VM - -Icinga 2 is available as [Vagrant Demo VM](#vagrant). +* When reporting a bug, please include the details described in the [Troubleshooting](7-troubleshooting.md#troubleshooting-information-required) chapter (version, configs, logs, etc). ## What's new -### What's New in Version 2.2.3 - -#### Changes - -* Bugfixes - -#### Issues - -* Bug #8063: Volatile checks trigger invalid notifications on OK->OK state changes -* Bug #8125: Incorrect ticket shouldn't cause "node wizard" to terminate -* Bug #8126: Icinga 2.2.2 doesn't build on i586 SUSE distributions -* Bug #8143: Windows plugin check_service.exe can't find service NTDS -* Bug #8144: Arguments without values are not used on plugin exec -* Bug #8147: check_interval must be greater than 0 error on update-config -* Bug #8152: DB IDO query queue limit reached on reload -* Bug #8171: Typo in example of StatusDataWriter -* Bug #8178: Icinga 2.2.2 segfaults on FreeBSD -* Bug #8181: icinga2 node update config shows hex instead of human readable names -* Bug #8182: Segfault on update-config old empty config - -### What's New in Version 2.2.2 - -#### Changes - -* Bugfixes - -#### Issues - -* Bug #7045: icinga2 init-script doesn't validate configuration on reload action -* Bug #7064: Missing host downtimes/comments in Livestatus -* Bug #7301: Docs: Better explaination of dependency state filters -* Bug #7314: double macros in command arguments seems to lead to exception -* Bug #7511: Feature `compatlog' should flush output buffer on every new line -* Bug #7518: update-config fails to create hosts -* Bug #7591: CPU usage at 100% when check_interval = 0 in host object definition -* Bug #7618: Repository does not support services which have a slash in their name -* Bug #7683: If a parent host goes down, the child host isn't marked as unrechable in the db ido -* Bug #7707: "node wizard" shouldn't crash when SaveCert fails -* Bug #7745: Cluster heartbeats need to be more aggressive -* Bug #7769: The unit tests still crash sometimes -* Bug #7863: execute checks locally if command_endpoint == local endpoint -* Bug #7878: Segfault on issuing node update-config -* Bug #7882: Improve error reporting when libmysqlclient or libpq are missing -* Bug #7891: CLI `icinga2 node update-config` doesn't sync configs from remote clients as expected -* Bug #7913: /usr/lib/icinga2 is not owned by a package -* Bug #7914: SUSE packages %set_permissions post statement wasn't moved to common -* Bug #7917: update_config not updating configuration -* Bug #7920: Test Classic UI config file with Apache 2.4 -* Bug #7929: Apache 2.2 fails with new apache conf -* Bug #8002: typeof() seems to return null for arrays and dictionaries -* Bug #8003: SIGABRT while evaluating apply rules -* Bug #8028: typeof does not work for numbers -* Bug #8039: Livestatus: Replace unixcat with nc -U -* Bug #8048: Wrong command in documentation for installing Icinga 2 pretty printers. -* Bug #8050: exception during config check -* Bug #8051: Update host examples in Dependencies for Network Reachability documentation -* Bug #8058: DB IDO: Missing last_hard_state column update in {host,service}status tables -* Bug #8059: Unit tests fail on FreeBSD -* Bug #8066: Setting a dictionary key to null does not cause the key/value to be removed -* Bug #8070: Documentation: Add note on default notification interval in getting started notifications.conf -* Bug #8075: No option to specify timeout to check_snmp and snmp manubulon commands - -### What's New in Version 2.2.1 +### What's New in Version 2.3 #### Changes -* Support arrays in [command argument macros](#command-passing-parameters) #6709 - * Allows to define multiple parameters for [nrpe -a](#plugin-check-command-nrpe), [nscp -l](#plugin-check-command-nscp), [disk -p](#plugin-check-command-disk), [dns -a](#plugin-check-command-dns). -* Bugfixes +TODO #### Issues -* Feature #6709: Support for arrays in macros -* Feature #7463: Update spec file to use yajl-devel -* Feature #7739: The classicui Apache conf doesn't support Apache 2.4 -* Feature #7747: Increase default timeout for NRPE checks -* Feature #7867: Document how arrays in macros work - -* Bug #7173: service icinga2 status gives wrong information when run as unprivileged user -* Bug #7602: livestatus large amount of submitting unix socket command results in broken pipes -* Bug #7613: icinga2 checkconfig should fail if group given for command files does not exist -* Bug #7671: object and template with the same name generate duplicate object error -* Bug #7708: Built-in commands shouldn't be run on the master instance in remote command execution mode -* Bug #7725: Windows wizard uses incorrect CLI command -* Bug #7726: Windows wizard is missing --zone argument -* Bug #7730: Restart Icinga - Error Restoring program state from file '/var/lib/icinga2/icinga2.state' -* Bug #7735: 2.2.0 has out-of-date icinga2 man page -* Bug #7738: systemd rpm scripts are run in wrong package -* Bug #7740: /usr/sbin/icinga-prepare-dirs conflicts in the bin and common package -* Bug #7741: Icinga 2.2 misses the build requirement libyajl-devel for SUSE distributions -* Bug #7743: Icinga2 node add failed with unhandled exception -* Bug #7754: Incorrect error message for localhost -* Bug #7770: Objects created with node update-config can't be seen in Classic UI -* Bug #7786: Move the icinga2-prepare-dirs script elsewhere -* Bug #7806: !in operator returns incorrect result -* Bug #7828: Verify if master radio box is disabled in the Windows wizard -* Bug #7847: Wrong information in section "Linux Client Setup Wizard for Remote Monitoring" -* Bug #7862: Segfault in CA handling -* Bug #7868: Documentation: Explain how unresolved macros are handled -* Bug #7890: Wrong permission in run directory after restart -* Bug #7896: Fix Apache config in the Debian package - -### What's New in Version 2.2.0 - -#### Changes - -* DB IDO schema update to version `1.12.0` - * schema files in `lib/db_ido_{mysql,pgsql}/schema` (source) - * Table `programstatus`: New column `program_version` - * Table `customvariables` and `customvariablestatus`: New column `is_json` (required for custom attribute array/dictionary support) -* New features - * [GelfWriter](#gelfwriter): Logging check results, state changes, notifications to GELF (graylog2, logstash) #7619 - * Agent/Client/Node framework #7249 - * Windows plugins for the client/agent parts #7242 #7243 -* New CLI commands #7245 - * `icinga2 feature {enable,disable}` replaces `icinga2-{enable,disable}-feature` script #7250 - * `icinga2 object list` replaces `icinga2-list-objects` script #7251 - * `icinga2 pki` replaces` icinga2-build-{ca,key}` scripts #7247 - * `icinga2 repository` manages `/etc/icinga2/repository.d` which must be included in `icinga2.conf` #7255 - * `icinga2 node` CLI command provides node (master, satellite, agent) setup (wizard) and management functionality #7248 - * `icinga2 daemon` for existing daemon arguments (`-c`, `-C`). Removed `-u` and `-g` parameters in favor of [init.conf](#init-conf). - * bash auto-completion & terminal colors #7396 -* Configuration - * Former `localhost` example host is now defined in [hosts.conf](#hosts-conf) #7594 - * All example services moved into advanced apply rules in [services.conf](#services-conf) - * Updated downtimes configuration example in [downtimes.conf](#downtimes-conf) #7472 - * Updated notification apply example in [notifications.conf](#notifications-conf) #7594 - * Support for object attribute 'zone' #7400 - * Support setting [object variables in apply rules](#dependencies-apply-custom-attributes) #7479 - * Support arrays and dictionaries in [custom attributes](#custom-attributes-apply) #6544 #7560 - * Add [apply for rules](#using-apply-for) for advanced dynamic object generation #7561 - * New attribute `accept_commands` for [ApiListener](#objecttype-apilistener) #7559 - * New [init.conf](#init-conf) file included first containing new constants `RunAsUser` and `RunAsGroup`. -* Cluster - * Add [CSR Auto-Signing support](#csr-autosigning-requirements) using generated ticket #7244 - * Allow to [execute remote commands](#icinga2-remote-monitoring-client-command-execution) on endpoint clients #7559 -* Perfdata - * [PerfdataWriter](#writing-performance-data-files): Don't change perfdata, pass through from plugins #7268 - * [GraphiteWriter](#graphite-carbon-cache-writer): Add warn/crit/min/max perfdata and downtime_depth stats values #7366 #6946 -* Packages - * `python-icinga2` package dropped in favor of integrated CLI commands #7245 - * Windows Installer for the agent parts #7243 - -> **Note** -> -> Please remove `conf.d/hosts/localhost*` after verifying your updated configuration! - -#### Issues - -* Feature #6544: Support for array in custom variable. -* Feature #6946: Add downtime depth as statistic metric for GraphiteWriter -* Feature #7187: Document how to use multiple assign/ignore statements with logical "and" & "or" -* Feature #7199: Cli commands: add filter capability to 'object list' -* Feature #7241: Windows Wizard -* Feature #7242: Windows plugins -* Feature #7243: Windows installer -* Feature #7244: CSR auto-signing -* Feature #7245: Cli commands -* Feature #7246: Cli command framework -* Feature #7247: Cli command: pki -* Feature #7248: Cli command: Node -* Feature #7249: Node Repository -* Feature #7250: Cli command: Feature -* Feature #7251: Cli command: Object -* Feature #7252: Cli command: SCM -* Feature #7253: Cli Commands: Node Repository Blacklist & Whitelist -* Feature #7254: Documentation: Agent/Satellite Setup -* Feature #7255: Cli command: Repository -* Feature #7262: macro processor needs an array printer -* Feature #7319: Documentation: Add support for locally-scoped variables for host/service in applied Dependency -* Feature #7334: GraphiteWriter: Add support for customized metric prefix names -* Feature #7356: Documentation: Cli Commands -* Feature #7366: GraphiteWriter: Add warn/crit/min/max perfdata values if existing -* Feature #7370: CLI command: variable -* Feature #7391: Add program_version column to programstatus table -* Feature #7396: Implement generic color support for terminals -* Feature #7400: Remove zone keyword and allow to use object attribute 'zone' -* Feature #7415: CLI: List disabled features in feature list too -* Feature #7421: Add -h next to --help -* Feature #7423: Cli command: Node Setup -* Feature #7452: Replace cJSON with a better JSON parser -* Feature #7465: Cli command: Node Setup Wizard (for Satellites and Agents) -* Feature #7467: Remove virtual agent name feature for localhost -* Feature #7472: Update downtimes.conf example config -* Feature #7478: Documentation: Mention 'icinga2 object list' in config validation -* Feature #7479: Set host/service variable in apply rules -* Feature #7480: Documentation: Add host/services variables in apply rules -* Feature #7504: Documentation: Revamp getting started with 1 host and multiple (service) applies -* Feature #7514: Documentation: Move troubleshooting after the getting started chapter -* Feature #7524: Documentation: Explain how to manage agent config in central repository -* Feature #7543: Documentation for arrays & dictionaries in custom attributes and their usage in apply rules for -* Feature #7559: Execute remote commands on the agent w/o local objects by passing custom attributes -* Feature #7560: Support dictionaries in custom attributes -* Feature #7561: Generate objects using apply with foreach in arrays or dictionaries (key => value) -* Feature #7566: Implement support for arbitrarily complex indexers -* Feature #7594: Revamp sample configuration: add NodeName host, move services into apply rules schema -* Feature #7596: Plugin Check Commands: disk is missing '-p', 'x' parameter -* Feature #7619: Add GelfWriter for writing log events to graylog2/logstash -* Feature #7620: Documentation: Update Icinga Web 2 installation -* Feature #7622: Icinga 2 should use less RAM -* Feature #7680: Conditionally enable MySQL and PostgresSQL, add support for FreeBSD and DragonFlyBSD - -* Bug #6547: delaying notifications with times.begin should postpone first notification into that window -* Bug #7257: default value for "disable_notifications" in service dependencies is set to "false" -* Bug #7268: Icinga2 changes perfdata order and removes maximum -* Bug #7272: icinga2 returns exponential perfdata format with check_nt -* Bug #7275: snmp-load checkcommand has wrong threshold syntax -* Bug #7276: SLES (Suse Linux Enterprise Server) 11 SP3 package dependency failure -* Bug #7302: ITL: check_procs and check_http are missing arguments -* Bug #7324: config parser crashes on unknown attribute in assign -* Bug #7327: Icinga2 docs: link supported operators from sections about apply rules -* Bug #7331: Error messages for invalid imports missing -* Bug #7338: Docs: Default command timeout is 60s not 5m -* Bug #7339: Importing a CheckCommand in a NotificationCommand results in an exception without stacktrace. -* Bug #7349: Documentation: Wrong check command for snmp-int(erface) -* Bug #7351: snmp-load checkcommand has a wrong "-T" param value -* Bug #7359: Setting snmp_v2 can cause snmp-manubulon-command derived checks to fail -* Bug #7365: Typo for "HTTP Checks" match in groups.conf -* Bug #7369: Fix reading perfdata in compat/checkresultreader -* Bug #7372: custom attribute name 'type' causes empty vars dictionary -* Bug #7373: Wrong usermod command for external command pipe setup -* Bug #7378: Commands are auto-completed when they shouldn't be -* Bug #7379: failed en/disable feature should return error -* Bug #7380: Debian package root permissions interfere with icinga2 CLI commands as icinga user -* Bug #7392: Schema upgrade files are missing in /usr/share/icinga2-ido-{mysql,pgsql} -* Bug #7417: CMake warnings on OS X -* Bug #7428: Documentation: 1-about contribute links to non-existing report a bug howto -* Bug #7433: Unity build fails on RHEL 5 -* Bug #7446: When replaying logs the secobj attribute is ignored -* Bug #7473: Performance data via API is broken -* Bug #7475: can't assign Service to Host in nested HostGroup -* Bug #7477: Fix typos and other small corrections in documentation -* Bug #7482: OnStateLoaded isn't called for objects which don't have any state -* Bug #7483: Hosts/services should not have themselves as parents -* Bug #7495: Utility::GetFQDN doesn't work on OS X -* Bug #7503: Icinga2 fails to start due to configuration errors -* Bug #7520: Use ScriptVariable::Get for RunAsUser/RunAsGroup -* Bug #7536: Object list dump erraneously evaluates template definitions -* Bug #7537: Nesting an object in a template causes the template to become non-abstract -* Bug #7538: There is no __name available to nested objects -* Bug #7573: link missing in documentation about livestatus -* Bug #7577: Invalid checkresult object causes Icinga 2 to crash -* Bug #7579: only notify users on recovery which have been notified before (not-ok state) -* Bug #7585: Nested templates do not work (anymore) -* Bug #7586: Exception when executing check -* Bug #7597: Compilation Error with boost 1.56 under Windows -* Bug #7599: Plugin execution on Windows does not work -* Bug #7617: mkclass crashes when called without arguments -* Bug #7623: Missing state filter 'OK' must not prevent recovery notifications being sent -* Bug #7624: Installation on Windows fails -* Bug #7625: IDO module crashes on Windows -* Bug #7646: Get rid of static boost::mutex variables -* Bug #7648: Unit tests fail to run -* Bug #7650: Wrong set of dependency state when a host depends on a service -* Bug #7681: CreateProcess fails on Windows 7 -* Bug #7688: DebugInfo is missing for nested dictionaries - -### Archive - -Please check the `ChangeLog` file. +TODO ## Icinga 2 in a Nutshell -* Use [Packages](#getting-started) +* Use [Packages](2-getting-started.md#getting-started) Look for available packages on http://packages.icinga.org or ask your distribution's maintainer. Compiling from source is not recommended. * Real Distributed Architecture -[Cluster](#distributed-monitoring-high-availability) model for distributed setups, load balancing +[Cluster](4-monitoring-remote-systems.md#distributed-monitoring-high-availability) model for distributed setups, load balancing and High-Availability installations (or a combination of them). On-demand configuration synchronisation between zones is available, but not mandatory (for example when config management tools such as Puppet are used). Secured by TLS with certificates, supporting IPv4 and IPv6. @@ -332,9 +77,9 @@ High Availability for DB IDO: Only active on the current zone master, failover h * Monitoring Remote Clients -Built on proven [cluster](#distributed-monitoring-high-availability) stack, -[Icinga 2 clients](#icinga2-remote-client-monitoring) can be installed acting as remote satellite or -agent. Secured communication by TLS with certificates, install them with [CLI commands](#cli-commands), +Built on proven [cluster](4-monitoring-remote-systems.md#distributed-monitoring-high-availability) stack, +[Icinga 2 clients](4-monitoring-remote-systems.md#icinga2-remote-client-monitoring) can be installed acting as remote satellite or +agent. Secured communication by TLS with certificates, install them with [CLI commands](5-cli-commands.md#cli-commands), and configure them either locally with discovery on the master, or use them for executing checks and event handlers remotely. @@ -343,37 +88,37 @@ event handlers remotely. Multithreaded and scalable for small embedded systems as well as large scale environments. Running checks every second is no longer a problem and enables real-time monitoring capabilities. -Checks, notifications and event handlers [do not block Icinga 2](#differences-1x-2-async-event-execution) +Checks, notifications and event handlers [do not block Icinga 2](8-migrating-from-icinga-1x.md#differences-1x-2-async-event-execution) in its operation. Same goes for performance data writers and the external command pipe, or any file writers on disk (`statusdata`). -Unlike Icinga 1.x the [daemon reload](#differences-1x-2-real-reload) happens asynchronously. +Unlike Icinga 1.x the [daemon reload](8-migrating-from-icinga-1x.md#differences-1x-2-real-reload) happens asynchronously. A child daemon validates the new configuration, the parent process is still doing checks, replicating cluster events, triggering alert notifications, etc. If the configuration validation is ok, all remaining events are synchronized and the child process continues as normal. The DB IDO configuration dump and status/historical event updates also runs asynchronously in a queue not blocking the core anymore. The configuration validation itself runs in parallel allowing fast verification checks. That way you are not blind (anymore) during a configuration reload and benefit from a real scalable architecture. * Integrated CLI with Bash Auto-Completion -Enable only the [features](#cli-command-feature) which are currently disabled, -[list objects](#cli-command-object) generated from [apply rules](#using-apply) or -[generate X.509 certificates](#cli-command-pki) for remote clients or cluster setup. -Start/stop the Icinga 2 [daemon](#cli-command-daemon) or validate your configuration, -[manage and install](#cli-command-node) remote clients and service discovery helped +Enable only the [features](5-cli-commands.md#cli-command-feature) which are currently disabled, +[list objects](5-cli-commands.md#cli-command-object) generated from [apply rules](3-monitoring-basics.md#using-apply) or +[generate X.509 certificates](5-cli-commands.md#cli-command-pki) for remote clients or cluster setup. +Start/stop the Icinga 2 [daemon](5-cli-commands.md#cli-command-daemon) or validate your configuration, +[manage and install](5-cli-commands.md#cli-command-node) remote clients and service discovery helped with black- and whitelists. -* Modular & flexible [features](#features) +* Modular & flexible [features](5-cli-commands.md#features) Enable only the features you require. Want to use Icinga Web 2 with DB IDO but no status data? No problem! Just enable ido-mysql and disable statusdata. Another example: Graphite should be enabled on a dedicated cluster node. Enable it over there and point it to the carbon cache socket. -Combine Icinga 2 Core with web user interfaces: Use [Icinga Web 2](#setting-up-icingaweb2), but also +Combine Icinga 2 Core with web user interfaces: Use [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2), but also Web 1.x or Classic UI or your own preferred addon. -* Native support for the [Livestatus protocol](#setting-up-livestatus) +* Native support for the [Livestatus protocol](2-getting-started.md#setting-up-livestatus) In Icinga2, the 'Livestatus' protocol is available for use as either a UNIX, or TCP socket. -* Native support for [Graphite](#graphite-carbon-cache-writer) +* Native support for [Graphite](3-monitoring-basics.md#graphite-carbon-cache-writer) Icinga 2 still supports writing performance data files for graphing addons, but also adds the capability of writing performance data directly into a Graphite TCP socket simplifying realtime @@ -382,24 +127,24 @@ monitoring graphs. * Native support for writing log events to [GELF](#gelf-writer) receivers (graylog2, Logstash) Icinga 2 will write all check result, state change and notification event logs into a defined -[GELF](#gelfwriter) input receiver. Natively provided by [graylog2](http://www.graylog2.org), +[GELF](3-monitoring-basics.md#gelfwriter) input receiver. Natively provided by [graylog2](http://www.graylog2.org), and as additional input type provided by [Logstash](http://logstash.net). * Dynamic configuration language -Simple [apply](#using-apply) and [assign](#group-assign) rules for creating configuration object +Simple [apply](3-monitoring-basics.md#using-apply) and [assign](9-language-reference.md#group-assign) rules for creating configuration object relationships based on patterns. More advanced features for dynamic object generation using -[apply for rules](#using-apply-for) helped with arrays and dictionaries for -[custom attributes](#custom-attributes-apply). -Supported with [duration literals](#duration-literals) for interval -attributes, [expression operators](#expression-operators), [function calls](#function-calls) for -pattern and regex matching and (global) [constants](#constants). +[apply for rules](3-monitoring-basics.md#using-apply-for) helped with arrays and dictionaries for +[custom attributes](3-monitoring-basics.md#custom-attributes-apply). +Supported with [duration literals](9-language-reference.md#duration-literals) for interval +attributes, [expression operators](9-language-reference.md#expression-operators), [function calls](9-language-reference.md#function-calls) for +pattern and regex matching and (global) [constants](9-language-reference.md#constants). [Check command configuration](#plugin-check-commands) for common plugins is shipped with Icinga 2 as part of the [Icinga Template Library](#itl). * Revamped Commands -One command to rule them all - supporting optional and conditional [command arguments](#command-arguments). -[Environment variables](#command-environment-variables) exported on-demand populated with +One command to rule them all - supporting optional and conditional [command arguments](3-monitoring-basics.md#command-arguments). +[Environment variables](3-monitoring-basics.md#command-environment-variables) exported on-demand populated with runtime evaluated macros. Three types of commands used for different actions: checks, notifications and events. Check timeout for commands instead of a global option. Commands also have custom attributes allowing @@ -408,14 +153,14 @@ There is no plugin output or performance data length restriction anymore compare * Custom Runtime Macros -Access [custom attributes](#custom-attributes) with their short name, for example $mysql_user$, +Access [custom attributes](3-monitoring-basics.md#custom-attributes) with their short name, for example $mysql_user$, or any object attribute, for example $host.notes$. Additional macros with runtime and statistic -information are available as well. Use these [runtime macros](#runtime-custom-attributes) in +information are available as well. Use these [runtime macros](3-monitoring-basics.md#runtime-custom-attributes) in the command line, environment variables and custom attribute assignments. * Notifications simplified -Multiple [notifications](#notifications) for one host or service with existing users +Multiple [notifications](3-monitoring-basics.md#notifications) for one host or service with existing users and notification commands. No more duplicated contacts for different notification types. Telling notification filters by state and type, even more fine-grained than Icinga 1.x. [Escalation notifications](#notification-escalations) and [delayed notifications](#first-notification-delay) @@ -423,15 +168,15 @@ are just notifications with an additional begin and/or end time attribute. * Dependencies between Hosts and Services -Classic [dependencies](#dependencies) between host and parent hosts, and services and parent services work the +Classic [dependencies](3-monitoring-basics.md#dependencies) between host and parent hosts, and services and parent services work the same way as "mixed" dependencies from a service to a parent host and vice versa. Host checks depending on an upstream link port (as service) are not a problem anymore. No more additional parents settings - host dependencies already define the host parent relationship required for network reachability calculations. -Set parent host/services based on [host/service custom attributes](#dependencies-apply-custom-attributes) +Set parent host/services based on [host/service custom attributes](3-monitoring-basics.md#dependencies-apply-custom-attributes) generated from your cloud inventory or CMDB and make your dependency rules simple and short. -* [Recurring Downtimes](#recurring-downtimes) +* [Recurring Downtimes](3-monitoring-basics.md#recurring-downtimes) Forget using cronjobs to set up recurring downtime - you can configure them as Icinga 2 configuration objects and specify their active time window. @@ -443,21 +188,21 @@ check providing direct statistics as performance data for your graphing addon, f * Compatibility with Icinga 1.x -All known interfaces are optionally available: [status files](#status-data), [logs](#compat-logging), -[DB IDO](#configuring-ido) MySQL/PostgreSQL, [performance data](#performance-data), -[external command pipe](#external-commands) and for migration reasons a -[checkresult file reader](#check-result-files) too. -All [Monitoring Plugins](#setting-up-check-plugins) can be integrated into Icinga 2 with +All known interfaces are optionally available: [status files](3-monitoring-basics.md#status-data), [logs](3-monitoring-basics.md#compat-logging), +[DB IDO](#configuring-ido) MySQL/PostgreSQL, [performance data](3-monitoring-basics.md#performance-data), +[external command pipe](3-monitoring-basics.md#external-commands) and for migration reasons a +[checkresult file reader](3-monitoring-basics.md#check-result-files) too. +All [Monitoring Plugins](2-getting-started.md#setting-up-check-plugins) can be integrated into Icinga 2 with newly created check command configuration if not already provided. -[Configuration migration](#configuration-migration) is possible through an external migration tool. +[Configuration migration](8-migrating-from-icinga-1x.md#configuration-migration) is possible through an external migration tool. -Detailed [migration hints](#manual-config-migration-hints) explain migration of the Icinga 1.x +Detailed [migration hints](8-migrating-from-icinga-1x.md#manual-config-migration-hints) explain migration of the Icinga 1.x configuration objects into the native Icinga 2 configuration schema. -Additional information on the differences is documented in the [migration](#differences-1x-2) chapter. +Additional information on the differences is documented in the [migration](8-migrating-from-icinga-1x.md#differences-1x-2) chapter. * Configuration Syntax Highlighting -Icinga 2 ships [syntax highlighting](#configuration-syntax-highlighting) for `vim` and `nano` to help +Icinga 2 ships [syntax highlighting](2-getting-started.md#configuration-syntax-highlighting) for `vim` and `nano` to help edit your configuration. * Puppet modules, Chef Cookbooks, Ansible Playbooks, Salt Formulas, etc @@ -465,7 +210,3 @@ edit your configuration. This is a constant work-in-progress. For details checkout https://dev.icinga.org/projects/icinga-tools If you want to contribute to these projects, do not hesitate to contact us at https://support.icinga.org -* [Vagrant Demo VM](#vagrant) - -Used for demo cases and development tests. Get Icinga 2 running within minutes and spread the #monitoringlove -to your friends and colleagues. diff --git a/doc/9-library-reference.md b/doc/10-library-reference.md similarity index 100% rename from doc/9-library-reference.md rename to doc/10-library-reference.md diff --git a/doc/10-object-types.md b/doc/11-object-types.md similarity index 96% rename from doc/10-object-types.md rename to doc/11-object-types.md index 6925e615f..bba8e5a5c 100644 --- a/doc/10-object-types.md +++ b/doc/11-object-types.md @@ -59,7 +59,7 @@ A group of hosts. > **Best Practice** > -> Assign host group members using the [group assign](#group-assign) rules. +> Assign host group members using the [group assign](9-language-reference.md#group-assign) rules. Example: @@ -84,7 +84,7 @@ by Icinga 2. > Rather than creating a `Service` object for a specific host it is usually easier > to just create a `Service` template and use the `apply` keyword to assign the > service to a number of hosts. -> Check the [apply](#using-apply) chapter for details. +> Check the [apply](3-monitoring-basics.md#using-apply) chapter for details. Example: @@ -145,7 +145,7 @@ A group of services. > **Best Practice** > -> Assign service group members using the [group assign](#group-assign) rules. +> Assign service group members using the [group assign](9-language-reference.md#group-assign) rules. Example: @@ -224,7 +224,7 @@ A user group. > **Best Practice** > -> Assign user group members using the [group assign](#group-assign) rules. +> Assign user group members using the [group assign](9-language-reference.md#group-assign) rules. Example: @@ -398,7 +398,7 @@ Attributes: zone |**Optional.** The zone this object is a member of. arguments |**Optional.** A dictionary of command arguments. -Command arguments can be used the same way as for [CheckCommand objects](#objecttype-checkcommand-arguments). +Command arguments can be used the same way as for [CheckCommand objects](11-object-types.md#objecttype-checkcommand-arguments). ## EventCommand @@ -425,7 +425,7 @@ Attributes: timeout |**Optional.** The command timeout in seconds. Defaults to 60 seconds. arguments |**Optional.** A dictionary of command arguments. -Command arguments can be used the same way as for [CheckCommand objects](#objecttype-checkcommand-arguments). +Command arguments can be used the same way as for [CheckCommand objects](11-object-types.md#objecttype-checkcommand-arguments). ## Notification @@ -439,7 +439,7 @@ of host and service state changes and other events. > usually easier to just create a `Notification` template and use the `apply` keyword > to assign the notification to a number of hosts or services. Use the `to` keyword > to set the specific target type for `Host` or `Service`. -> Check the [notifications](#notifications) chapter for detailed examples. +> Check the [notifications](3-monitoring-basics.md#notifications) chapter for detailed examples. Example: @@ -465,7 +465,7 @@ Attributes: user_groups | **Optional.** A list of user group names who should be notified. times | **Optional.** A dictionary containing `begin` and `end` attributes for the notification. command | **Required.** The name of the notification command which should be executed when the notification is triggered. - interval | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, [re-notifications](#disable-renotification) are disabled. + interval | **Optional.** The notification interval (in seconds). This interval is used for active notifications. Defaults to 30 minutes. If set to 0, [re-notifications](3-monitoring-basics.md#disable-renotification) are disabled. period | **Optional.** The name of a time period which determines when this notification should be triggered. Not set by default. zone |**Optional.** The zone this object is a member of. types | **Optional.** A list of type filters when this notification should be triggered. By default everything is matched. @@ -540,7 +540,7 @@ ScheduledDowntime objects can be used to set up recurring downtimes for hosts/se > to just create a `ScheduledDowntime` template and use the `apply` keyword to assign the > scheduled downtime to a number of hosts or services. Use the `to` keyword to set the specific target > type for `Host` or `Service`. -> Check the [recurring downtimes](#recurring-downtimes) example for details. +> Check the [recurring downtimes](3-monitoring-basics.md#recurring-downtimes) example for details. Example: @@ -591,7 +591,7 @@ relations. > to just create a `Dependency` template and use the `apply` keyword to assign the > dependency to a number of hosts or services. Use the `to` keyword to set the specific target > type for `Host` or `Service`. -> Check the [dependencies](#dependencies) chapter for detailed examples. +> Check the [dependencies](3-monitoring-basics.md#dependencies) chapter for detailed examples. Service-to-Service Example: @@ -642,7 +642,7 @@ Available state filters: Up Down -When using [apply rules](#using-apply) for dependencies, you can leave out certain attributes which will be +When using [apply rules](3-monitoring-basics.md#using-apply) for dependencies, you can leave out certain attributes which will be automatically determined by Icinga 2. Service-to-Host Dependency Example: @@ -735,9 +735,9 @@ Attributes: host_name_template |**Optional.** Metric prefix for host name. Defaults to "icinga.$host.name$". service_name_template |**Optional.** Metric prefix for service name. Defaults to "icinga.$host.name$.$service.name$". -Metric prefix names can be modified using [runtime macros](#runtime-macros). +Metric prefix names can be modified using [runtime macros](3-monitoring-basics.md#runtime-macros). -Example with your custom [global constant](#constants) `GraphiteEnv`: +Example with your custom [global constant](9-language-reference.md#constants) `GraphiteEnv`: const GraphiteEnv = "icinga.env1" @@ -805,8 +805,8 @@ Attributes: table\_prefix |**Optional.** MySQL database table prefix. Defaults to "icinga\_". instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default". instance\_description|**Optional.** Description for the Icinga 2 instance. - enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](#high-availability-db-ido). Defaults to "true". - failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s". + enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](4-monitoring-remote-systems.md#high-availability-db-ido). Defaults to "true". + failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](4-monitoring-remote-systems.md#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s". cleanup |**Optional.** Dictionary with items for historical table cleanup. categories |**Optional.** The types of information that should be written to the database. @@ -856,7 +856,7 @@ a shortcut for listing all flags. External interfaces like Icinga Web require everything except `DbCatCheck` which is the default value if `categories` is not set. -## IdoPgSqlConnection +## IdoPgSqlConnection IDO database adapter for PostgreSQL. @@ -894,8 +894,8 @@ Attributes: table\_prefix |**Optional.** PostgreSQL database table prefix. Defaults to "icinga\_". instance\_name |**Optional.** Unique identifier for the local Icinga 2 instance. Defaults to "default". instance\_description|**Optional.** Description for the Icinga 2 instance. - enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](#high-availability-db-ido). Defaults to "true". - failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s". + enable_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](4-monitoring-remote-systems.md#high-availability-db-ido). Defaults to "true". + failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](4-monitoring-remote-systems.md#high-availability-db-ido). Must not be lower than 60s. Defaults to "60s". cleanup |**Optional.** Dictionary with items for historical table cleanup. categories |**Optional.** The types of information that should be written to the database. @@ -1154,7 +1154,7 @@ Attributes: ApiListener objects are used for distributed monitoring setups specifying the certificate files used for ssl authorization. -The `NodeName` constant must be defined in [constants.conf](#constants-conf). +The `NodeName` constant must be defined in [constants.conf](2-getting-started.md#constants-conf). Example: diff --git a/doc/11-icinga-template-library.md b/doc/12-icinga-template-library.md similarity index 99% rename from doc/11-icinga-template-library.md rename to doc/12-icinga-template-library.md index 60cbc06dd..df79dfef6 100644 --- a/doc/11-icinga-template-library.md +++ b/doc/12-icinga-template-library.md @@ -462,7 +462,7 @@ snmp_invert_search | **Optional.** Invert search result and return CRITICAL sta snmp_units | **Optional.** Units label(s) for output value (e.g., 'sec.'). snmp_timeout | **Optional.** The command timeout in seconds. Defaults to 10 seconds. -### snmpv3 +### snmpv3 Check command object for the `check_snmp` plugin, using SNMPv3 authentication and encryption options. @@ -622,7 +622,7 @@ The SNMP manubulon plugin check commands assume that the global constant named ` is set to the path where the Manubublon SNMP plugins are installed. You can enable these plugin check commands by adding the following the include directive in your -configuration [icinga2.conf](#icinga2-conf) file: +configuration [icinga2.conf](2-getting-started.md#icinga2-conf) file: include diff --git a/doc/12-appendix.md b/doc/13-appendix.md similarity index 100% rename from doc/12-appendix.md rename to doc/13-appendix.md diff --git a/doc/2-getting-started.md b/doc/2-getting-started.md index e2100f080..9ffb68c3f 100644 --- a/doc/2-getting-started.md +++ b/doc/2-getting-started.md @@ -4,7 +4,7 @@ This tutorial is a step-by-step introduction to installing Icinga 2 and available Icinga web interfaces. It assumes that you are familiar with the system you're installing Icinga 2 on. -Details on troubleshooting problems can be found [here](#troubleshooting). +Details on troubleshooting problems can be found [here](7-troubleshooting.md#troubleshooting). ## Setting up Icinga 2 @@ -68,7 +68,7 @@ openSUSE: The packages for RHEL/CentOS depend on other packages which are distributed as part of the [EPEL repository](http://fedoraproject.org/wiki/EPEL). Please make sure to enable this repository by following -[these instructions](#http://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F). +[these instructions](http://fedoraproject.org/wiki/EPEL#How_can_I_use_these_extra_packages.3F). ### Installing Icinga 2 @@ -93,7 +93,7 @@ the `icinga2` service: # chkconfig icinga2 on # service icinga2 start -RHEL/CentOS 7 and Fedora use [systemd](#systemd-service): +RHEL/CentOS 7 and Fedora use [systemd](2-getting-started.md#systemd-service): # systemctl enable icinga2 # systemctl start icinga2 @@ -102,8 +102,8 @@ Some parts of Icinga 2's functionality are available as separate packages: Name | Description ------------------------|-------------------------------- - icinga2-ido-mysql | [DB IDO](#configuring-db-ido) provider module for MySQL - icinga2-ido-pgsql | [DB IDO](#configuring-db-ido) provider module for PostgreSQL + icinga2-ido-mysql | [DB IDO](2-getting-started.md#configuring-db-ido) provider module for MySQL + icinga2-ido-pgsql | [DB IDO](2-getting-started.md#configuring-db-ido) provider module for PostgreSQL ### Enabled Features during Installation @@ -114,7 +114,7 @@ Icinga 2 installation: * `notification` for sending notifications * `mainlog` for writing the `icinga2.log` file -You can verify that by calling `icinga2 feature list` [CLI command](#cli-command-feature) +You can verify that by calling `icinga2 feature list` [CLI command](5-cli-commands.md#cli-command-feature) to see which features are enabled and disabled. # icinga2 feature list @@ -172,7 +172,7 @@ update the global `PluginDir` constant in your Icinga 2 configuration. This macr by the check command definitions contained in the Icinga Template Library to determine where to find the plugin binaries. -Please refer to the [plugins](#plugins) chapter for details about how to integrate +Please refer to the [plugins](6-addons-plugins.md#plugins) chapter for details about how to integrate additional check plugins into your Icinga 2 setup. ## Configuring Icinga 2: First Steps @@ -192,7 +192,7 @@ Here's a brief description of the example configuration: * to the documentation that is distributed as part of Icinga 2. */ -Icinga 2 supports [C/C++-style comments](#comments). +Icinga 2 supports [C/C++-style comments](9-language-reference.md#comments). /** * The constants.conf defines global constants. @@ -226,7 +226,7 @@ The `include` directive can be used to include other files. This `include` directive takes care of including the configuration files for all the features which have been enabled with `icinga2 feature enable`. See -[Enabling/Disabling Features](#features) for more details. +[Enabling/Disabling Features](5-cli-commands.md#features) for more details. /** * The repository.d directory contains all configuration objects @@ -236,7 +236,7 @@ the features which have been enabled with `icinga2 feature enable`. See This `include_recursive` directive is used for discovery of services on remote clients and their generated configuration described in -[this chapter](#icinga2-remote-monitoring-master-discovery-generate-config). +[this chapter](4-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-generate-config). /** @@ -246,7 +246,7 @@ and their generated configuration described in */ include_recursive "conf.d" -You can put your own configuration files in the [conf.d](#conf-d) directory. This +You can put your own configuration files in the [conf.d](2-getting-started.md#conf-d) directory. This directive makes sure that all of your own configuration files are included. > **Tip** @@ -261,9 +261,9 @@ The `constants.conf` configuration file can be used to define global constants. By default, you need to make sure to set these constants: -* The `PluginDir` constant must be pointed to your [check plugins](#setting-up-check-plugins) path. +* The `PluginDir` constant must be pointed to your [check plugins](2-getting-started.md#setting-up-check-plugins) path. This constant is required by the shipped -[plugin check command configuration](#plugin-check-commands). +[plugin check command configuration](12-icinga-template-library.md#plugin-check-commands). * The `NodeName` constant defines your local node name. Should be set to FQDN which is the default if not set. This constant is required for local host configuration, monitoring remote clients and cluster setup. @@ -297,35 +297,35 @@ and distributed setups only. This directory contains example configuration which should help you get started with monitoring the local host and its services. It is included in the -[icinga2.conf](#icinga2-conf) configuration file by default. +[icinga2.conf](2-getting-started.md#icinga2-conf) configuration file by default. It can be used as reference example for your own configuration strategy. Just keep in mind to include the main directories in the -[icinga2.conf](#icinga2-conf) file. +[icinga2.conf](2-getting-started.md#icinga2-conf) file. You are certainly not bound to it. Remove it, if you prefer your own way of deploying Icinga 2 configuration. Further details on configuration best practice and how to build your -own strategy is described in [this chapter](#configuration-best-practice). +own strategy is described in [this chapter](3-monitoring-basics.md#configuration-best-practice). Available configuration files shipped by default: -* [hosts.conf](#hosts-conf) -* [services.conf](#services-conf) -* [users.conf](#users-conf) -* [notifications.conf](#notifications-conf) -* [commands.conf](#commands-conf) -* [groups.conf](#groups-conf) -* [templates.conf](#templates-conf) -* [downtimes.conf](#downtimes-conf) -* [timeperiods.conf](#timeperiods-conf) -* [satellite.conf](#satellite-conf) +* [hosts.conf](2-getting-started.md#hosts-conf) +* [services.conf](2-getting-started.md#services-conf) +* [users.conf](2-getting-started.md#users-conf) +* [notifications.conf](2-getting-started.md#notifications-conf) +* [commands.conf](2-getting-started.md#commands-conf) +* [groups.conf](2-getting-started.md#groups-conf) +* [templates.conf](2-getting-started.md#templates-conf) +* [downtimes.conf](2-getting-started.md#downtimes-conf) +* [timeperiods.conf](2-getting-started.md#timeperiods-conf) +* [satellite.conf](2-getting-started.md#satellite-conf) #### hosts.conf The `hosts.conf` file contains an example host based on your -`NodeName` setting in [constants.conf](#constants-conf). You +`NodeName` setting in [constants.conf](2-getting-started.md#constants-conf). You can use global constants for your object names instead of string values. @@ -334,11 +334,11 @@ takes care of setting up the host check command to `hostalive`. If you require a different check command, you can override it in the object definition. The `vars` attribute can be used to define custom attributes which are available -for check and notification commands. Most of the [Plugin Check Commands](#plugin-check-commands) +for check and notification commands. Most of the [Plugin Check Commands](12-icinga-template-library.md#plugin-check-commands) in the Icinga Template Library require an `address` attribute. The custom attribute `os` is evaluated by the `linux-servers` group in -[groups.conf](#groups-conf) making the local host a member. +[groups.conf](2-getting-started.md#groups-conf) making the local host a member. The example host will show you how to @@ -349,7 +349,7 @@ service apply rule defined in [services.conf](#services.conf). * define notification types (`mail`) and set the groups attribute. This will be used by notification apply rules in [notifications.conf](notifications-conf). -If you've installed [Icinga Web 2](#setting-up-icingaweb2) you can +If you've installed [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2) you can uncomment the http vhost attributes and relaod Icinga 2. The apply rules in [services.conf](#services.conf) will automatically generate a new service checking the `/icingaweb2` URI using the `http` @@ -408,17 +408,17 @@ check. } This is only the host object definition. Now we'll need to make sure that this -host and your additional hosts are getting [services](#services-conf) applied. +host and your additional hosts are getting [services](2-getting-started.md#services-conf) applied. > **Tip** > -> If you don't understand all the attributes and how to use [apply rules](#apply) -> don't worry - the [monitoring basics](#monitoring-basics) chapter will explain +> If you don't understand all the attributes and how to use [apply rules](9-language-reference.md#apply) +> don't worry - the [monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter will explain > that in detail. #### services.conf -These service [apply rules](#apply) will show you how to monitor +These service [apply rules](9-language-reference.md#apply) will show you how to monitor the local host, but also allow you to re-use or modify them for your own requirements. @@ -439,7 +439,7 @@ The Debian packages also ship an additional `apt` service check applied to the l The command object `icinga` for the embedded health check is provided by the [Icinga Template Library (ITL)](#itl) while `http_ip`, `ssh`, `load`, `processes`, -`users` and `disk` are all provided by the [Plugin Check Commands](#plugin-check-commands) +`users` and `disk` are all provided by the [Plugin Check Commands](12-icinga-template-library.md#plugin-check-commands) which we enabled earlier by including the `itl` and `plugins` configuration file. @@ -462,11 +462,11 @@ attributes. The custom attribe `backup_downtime` is defined to a specific timerange string. This variable value will be used for applying a `ScheduledDowntime` object to -these services in [downtimes.conf](#downtimes-conf). +these services in [downtimes.conf](2-getting-started.md#downtimes-conf). In this example the `assign where` condition is a boolean expression which is evaluated for all objects of type `Host` and a new service with name "load" -is created for each matching host. [Expression operators](#expression-operators) +is created for each matching host. [Expression operators](9-language-reference.md#expression-operators) may be used in `assign where` conditions. Multiple `assign where` condition can be combined with `AND` using the `&&` operator @@ -484,7 +484,7 @@ In this example, the service `ssh` is applied to all hosts having the `address` attribute defined `AND` having the custom attribute `os` set to the string `Linux`. You can modify this condition to match multiple expressions by combinding `AND` -and `OR` using `&&` and `||` [operators](#expression-operators), for example +and `OR` using `&&` and `||` [operators](9-language-reference.md#expression-operators), for example `assign where host.address && (vars.os == "Linux" || vars.os == "Windows")`. @@ -493,10 +493,10 @@ rules. While one `apply` rule for `ssh` will only create a service for matching hosts, you can go one step further: Generate apply rules based on array items or dictionary key-value pairs. -The idea is simple: Your host in [hosts.conf](#hosts-conf) defines the +The idea is simple: Your host in [hosts.conf](2-getting-started.md#hosts-conf) defines the `disks` dictionary as custom attribute in `vars`. -Remember the example from [hosts.conf](#hosts-conf): +Remember the example from [hosts.conf](2-getting-started.md#hosts-conf): ... @@ -516,7 +516,7 @@ parameter `disk_partition` to the check command. You'll recognize that the naming is important - that's the very same name as it is passed from a service to a check command argument. Read about services -and passing check commands in [this chapter](#command-passing-parameters). +and passing check commands in [this chapter](3-monitoring-basics.md#command-passing-parameters). Using `apply Service for` omits the service name, it will take the key stored in the `disk` variable in `key => config` as new service object name. @@ -530,7 +530,7 @@ Once defined like this, the `apply` rule defined below will do the following: * loop through all entries in the `host.vars.disks` dictionary. That's `disk` and `disk /` as keys. * call `apply` on each, and set the service object name from the provided key * inside apply, the `generic-service` template is imported -* defining the [disk](#plugin-check-command-disk) check command requiring command arguments like `disk_partition` +* defining the [disk](12-icinga-template-library.md#plugin-check-command-disk) check command requiring command arguments like `disk_partition` * adding the `config` dictionary items to `vars`. Simply said, there's now `vars.disk_partition` defined for the generated service @@ -550,21 +550,21 @@ A similar example is used for the `http` services. That way you can make your host the information provider for all apply rules. Define them once, and only manage your hosts. -Look into [notifications.conf](#notifications-conf) how this technique is used +Look into [notifications.conf](2-getting-started.md#notifications-conf) how this technique is used for applying notifications to hosts and services using their type and user attributes. -Don't forget to install the [check plugins](#setting-up-check-plugins) required by +Don't forget to install the [check plugins](2-getting-started.md#setting-up-check-plugins) required by the hosts and services and their check commands. Further details on the monitoring configuration can be found in the -[monitoring basics](#monitoring-basics) chapter. +[monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter. #### users.conf Defines the `icingaadmin` User and the `icingaadmins` UserGroup. The latter is used in -[hosts.conf](#hostss-conf) for defining a custom host attribute later used in -[notifications.conf](#notifications-conf) for notification apply rules. +[hosts.conf](2-getting-started.md#hosts-conf) for defining a custom host attribute later used in +[notifications.conf](2-getting-started.md#notifications-conf) for notification apply rules. object User "icingaadmin" { import "generic-user" @@ -589,14 +589,14 @@ The shipped example defines two notification apply rules for hosts and services. Both `apply` rules match on the same condition: They are only applied if the nested dictionary attribute `notification.mail` is set. -Please note that the `to` keyword is important in [notification apply rules](#using-apply-notifications) +Please note that the `to` keyword is important in [notification apply rules](3-monitoring-basics.md#using-apply-notifications) defining whether these notifications are applies to hosts or services. -The `import` keyword imports the specific mail templates defined in [templates.conf](#templates-conf). +The `import` keyword imports the specific mail templates defined in [templates.conf](2-getting-started.md#templates-conf). -The `interval` attribute is not explicitly set - it [defaults to 30 minutes](#objecttype-notification). +The `interval` attribute is not explicitly set - it [defaults to 30 minutes](11-object-types.md#objecttype-notification). By setting the `user_groups` to the value provided by the -respective [host.vars.notification.mail](#hosts-conf) attribute we'll +respective [host.vars.notification.mail](2-getting-started.md#hosts-conf) attribute we'll implicitely use the`icingaadmins` UserGroup defined in [users.conf](#users.conf). apply Notification "mail-icingaadmin" to Host { @@ -616,21 +616,21 @@ implicitely use the`icingaadmins` UserGroup defined in [users.conf](#users.conf) } More details on defining notifications and their additional attributes such as -filters can be read in [this chapter](#notifications). +filters can be read in [this chapter](3-monitoring-basics.md#notifications). #### commands.conf This is the place where your own command configuration can be defined. By default -only the notification commands used by the notification templates defined in [templates.conf](#templates-conf). +only the notification commands used by the notification templates defined in [templates.conf](2-getting-started.md#templates-conf). > **Tip** > > Icinga 2 ships the most common command definitions already in the -> [Plugin Check Commands](#plugin-check-commands) definitions. More details on -> that topic in the [troubleshooting section](#check-command-definitions). +> [Plugin Check Commands](12-icinga-template-library.md#plugin-check-commands) definitions. More details on +> that topic in the [troubleshooting section](7-troubleshooting.md#check-command-definitions). You can freely customize these notification commands, and adapt them for your needs. -Read more on that topic [here](#notification-commands). +Read more on that topic [here](3-monitoring-basics.md#notification-commands). #### groups.conf @@ -638,8 +638,8 @@ The example host defined in [hosts.conf](hosts-conf) already has the custom attribute `os` set to `Linux` and is therefore automatically a member of the host group `linux-servers`. -This is done by using the [group assign](#group-assign) expressions similar -to previously seen [apply rules](#using-apply). +This is done by using the [group assign](9-language-reference.md#group-assign) expressions similar +to previously seen [apply rules](3-monitoring-basics.md#using-apply). object HostGroup "linux-servers" { display_name = "Linux Servers" @@ -654,7 +654,7 @@ to previously seen [apply rules](#using-apply). } Service groups can be grouped together by similar pattern matches. -The [match() function](#function-calls) expects a wildcard match string +The [match() function](9-language-reference.md#function-calls) expects a wildcard match string and the attribute string to match with. object ServiceGroup "ping" { @@ -680,9 +680,9 @@ and the attribute string to match with. All shipped example configuration objects use generic global templates by default. Be it setting a default `check_command` attribute in the `generic-host` -templates for your hosts defined in [hosts.conf](#hosts-conf), or defining +templates for your hosts defined in [hosts.conf](2-getting-started.md#hosts-conf), or defining the default `states` and `types` filters for notification apply rules defined in -[notifications.conf](#notifications-conf). +[notifications.conf](2-getting-started.md#notifications-conf). template Host "generic-host" { @@ -700,7 +700,7 @@ the default `states` and `types` filters for notification apply rules defined in } The `hostalive` check command is shipped with Icinga 2 in the -[Plugin Check Commands](#plugin-check-commands). +[Plugin Check Commands](12-icinga-template-library.md#plugin-check-commands). template Notification "mail-host-notification" { @@ -725,15 +725,15 @@ The `hostalive` check command is shipped with Icinga 2 in the period = "24x7" } -More details on `Notification` object attributes can be found [here](#objecttype-notification). +More details on `Notification` object attributes can be found [here](11-object-types.md#objecttype-notification). #### downtimes.conf -The `load` service apply rule defined in [services.conf](#services-conf) defines +The `load` service apply rule defined in [services.conf](2-getting-started.md#services-conf) defines the `backup_downtime` custom attribute. -The [ScheduledDowntime](#objecttype-scheduleddowntime) apply rule uses this attribute +The [ScheduledDowntime](11-object-types.md#objecttype-scheduleddowntime) apply rule uses this attribute to define the default value for the time ranges required for recurring downtime slots. apply ScheduledDowntime "backup-downtime" to Service { @@ -763,19 +763,19 @@ objects such as hosts, services or notifications. #### satellite.conf -Ships default templates and dependencies for [monitoring remote clients](#icinga2-remote-client-monitoring) -using service discovery and [config generation](#icinga2-remote-monitoring-master-discovery-generate-config) +Ships default templates and dependencies for [monitoring remote clients](4-monitoring-remote-systems.md#icinga2-remote-client-monitoring) +using service discovery and [config generation](4-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-generate-config) on the master. Can be ignored/removed on setups not using this features. Further details on the monitoring configuration can be found in the -[monitoring basics](#monitoring-basics) chapter. +[monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter. ## Configuring DB IDO The DB IDO (Database Icinga Data Output) modules for Icinga 2 take care of exporting all configuration and status information into a database. The IDO database is used -by a number of projects including [Icinga Web 2](#setting-up-icingaweb2), +by a number of projects including [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2), Icinga Reporting or Icinga Web 1.x. You only need to set up the IDO modules if you're using an external project which uses @@ -789,12 +789,12 @@ features not yet released with older Icinga 1.x versions. > **Note** > -> Please check the [what's new](#whats-new) section for the required schema version. +> Please check the [what's new](1-about.md#whats-new) section for the required schema version. ### Installing the Database Server -In order to use DB IDO you need to setup either [MySQL](#installing-database-mysql-server) -or [PostgreSQL](#installing-database-postgresql-server) as supported database server. +In order to use DB IDO you need to setup either [MySQL](2-getting-started.md#installing-database-mysql-server) +or [PostgreSQL](2-getting-started.md#installing-database-postgresql-server) as supported database server. #### Installing MySQL database server @@ -836,7 +836,7 @@ RHEL/CentOS 5/6: # chkconfig postgresql on # service postgresql start -RHEL/CentOS 7 and Fedora 20 use [systemd](#systemd-service): +RHEL/CentOS 7 and Fedora 20 use [systemd](2-getting-started.md#systemd-service): # yum install postgresql-server postgresql # systemctl enable postgresql.service @@ -922,7 +922,7 @@ The package provides a new configuration file that is installed in `/etc/icinga2/features-available/ido-mysql.conf`. You will need to update the database credentials in this file. All available attributes are listed in the -[IdoMysqlConnection object](#objecttype-idomysqlconnection) configuration details. +[IdoMysqlConnection object](11-object-types.md#objecttype-idomysqlconnection) configuration details. You can enable the `ido-mysql` feature configuration file using `icinga2 feature enable`: @@ -1036,7 +1036,7 @@ The package provides a new configuration file that is installed in `/etc/icinga2/features-available/ido-pgsql.conf`. You will need to update the database credentials in this file. All available attributes are listed in the -[IdoPgsqlConnection object](#objecttype-idopgsqlconnection) configuration details. +[IdoPgsqlConnection object](11-object-types.md#objecttype-idopgsqlconnection) configuration details. You can enable the `ido-pgsql` feature configuration file using `icinga2 feature enable`: @@ -1101,8 +1101,8 @@ status information. It can also be used to send commands. > **Tip** > > Only install the Livestatus feature if your web interface or addon requires -> you to do so (for example, [Icinga Web 2](#setting-up-icingaweb2)). -> [Icinga Classic UI](#setting-up-icinga-classic-ui) and [Icinga Web](#setting-up-icinga-web) +> you to do so (for example, [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2)). +> [Icinga Classic UI](2-getting-started.md#setting-up-icinga-classic-ui) and [Icinga Web](2-getting-started.md#setting-up-icinga-web) > do not use Livestatus as backend. The Livestatus component that is distributed as part of Icinga 2 is a @@ -1110,7 +1110,7 @@ re-implementation of the Livestatus protocol which is compatible with MK Livestatus. Details on the available tables and attributes with Icinga 2 can be found -in the [Livestatus](#livestatus) section. +in the [Livestatus](3-monitoring-basics.md#livestatus) section. You can enable Livestatus using icinga2 feature enable: @@ -1147,15 +1147,15 @@ are expected to be in `/var/log/icinga2/compat`. A different path can be set usi ## Setting up Icinga 2 User Interfaces -Icinga 2 can be used with [Icinga Web 2](#setting-up-icingaweb2), using +Icinga 2 can be used with [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2), using DB IDO or Livestatus as preferred backend provider, next to the command pipe. Icinga 2 also is compatible with Icinga 1.x user interfaces -[Classic UI 1.x](#installing-icinga-classic-ui) and [Icinga Web 1.x](#setting-up-icinga-web) +[Classic UI 1.x](2-getting-started.md#installing-icinga-classic-ui) and [Icinga Web 1.x](2-getting-started.md#setting-up-icinga-web) by providing additional features required as backends. Some Icinga 1.x interface features will only work in a limited manner due to -[compatibility reasons](#differences-1x-2), other features like the +[compatibility reasons](8-migrating-from-icinga-1x.md#differences-1x-2), other features like the statusmap parents are available by dumping the host dependencies as parents. Special restrictions are noted specifically in the sections below. @@ -1164,8 +1164,8 @@ that Icinga 2 core features might not be fully supported in these addons. > **Tip** > -> Choose your preferred interface. There's no need to install [Classic UI 1.x](#setting-up-icinga-classic-ui) -> if you prefer [Icinga Web 1.x](#setting-up-icinga-web) or [Icinga Web 2](#setting-up-icingaweb2) for example. +> Choose your preferred interface. There's no need to install [Classic UI 1.x](2-getting-started.md#setting-up-icinga-classic-ui) +> if you prefer [Icinga Web 1.x](2-getting-started.md#setting-up-icinga-web) or [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2) for example. ### Requirements @@ -1173,8 +1173,8 @@ that Icinga 2 core features might not be fully supported in these addons. * User credentials * Firewall ports (tcp/80) -The Debian, RHEL and SUSE packages for Icinga [Classic UI](#setting-up-icinga-classic-ui), -[Web](#setting-up-icinga-web) and [Icingaweb 2](#setting-up-icingaweb2) depend on Apache2 +The Debian, RHEL and SUSE packages for Icinga [Classic UI](2-getting-started.md#setting-up-icinga-classic-ui), +[Web](2-getting-started.md#setting-up-icinga-web) and [Icingaweb 2](2-getting-started.md#setting-up-icingaweb2) depend on Apache2 as web server. #### Webserver @@ -1210,17 +1210,17 @@ RHEL/CentOS 7 specific: Icinga Web 2 supports `DB IDO` or `Livestatus` as backends. Using DB IDO as backend, you need to install and configure the -[DB IDO backend](#configuring-db-ido). +[DB IDO backend](2-getting-started.md#configuring-db-ido). Once finished, you can enable the feature for DB IDO MySQL: # icinga2 feature enable ido-mysql -Furthermore [external commands](#external-commands) are supported through the external +Furthermore [external commands](3-monitoring-basics.md#external-commands) are supported through the external command pipe. # icinga2 feature enable command -In order for commands to work you will need to [setup the external command pipe](#setting-up-external-command-pipe). +In order for commands to work you will need to [setup the external command pipe](2-getting-started.md#setting-up-external-command-pipe). [Icinga Web 2](https://github.com/Icinga/icingaweb2) ships its own web-based setup wizard which will guide you through the entire setup process. @@ -1240,7 +1240,7 @@ and packages. ### Setting up Icinga Classic UI 1.x 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](#external-commands) +is supported by the Icinga 1.x Classic UI. [External commands](3-monitoring-basics.md#external-commands) (a.k.a. the "command pipe") are also supported. It also supports writing Icinga 1.x log files which are required for the reporting functionality in the Classic UI. @@ -1269,13 +1269,13 @@ to satisfy this dependency: On all distributions other than Debian you may have to restart both your web server as well as Icinga 2 after installing the Classic UI package. -Icinga Classic UI requires the [StatusDataWriter](#status-data), [CompatLogger](#compat-logging) -and [ExternalCommandListener](#external-commands) features. +Icinga Classic UI requires the [StatusDataWriter](3-monitoring-basics.md#status-data), [CompatLogger](3-monitoring-basics.md#compat-logging) +and [ExternalCommandListener](3-monitoring-basics.md#external-commands) features. Enable these features and restart Icinga 2. # icinga2 feature enable statusdata compatlog command -In order for commands to work you will need to [setup the external command pipe](#setting-up-external-command-pipe). +In order for commands to work you will need to [setup the external command pipe](2-getting-started.md#setting-up-external-command-pipe). #### Setting Up Icinga Classic UI 1.x Summary @@ -1342,11 +1342,11 @@ found in the [Icinga Web documentation](http://docs.icinga.org/latest/en/icinga- # icinga-web-clearcache -Additionally you need to enable the `command` feature for sending [external commands](#external-commands): +Additionally you need to enable the `command` feature for sending [external commands](3-monitoring-basics.md#external-commands): # icinga2 feature enable command -In order for commands to work you will need to [setup the external command pipe](#setting-up-external-command-pipe). +In order for commands to work you will need to [setup the external command pipe](2-getting-started.md#setting-up-external-command-pipe). Then edit the Icinga Web configuration for sending commands in `/etc/icinga-web/conf.d/access.xml` (RHEL) or `/etc/icinga-web/access.xml` (SUSE) setting the command pipe path @@ -1378,7 +1378,7 @@ use one of the config packages: - `icinga-web-config-icinga2-ido-mysql` - `icinga-web-config-icinga2-ido-pgsql` -These packages take care of setting up the [DB IDO](#configuring-db-ido) configuration, +These packages take care of setting up the [DB IDO](2-getting-started.md#configuring-db-ido) configuration, enabling the external command pipe for Icinga Web and depend on the corresponding packages of Icinga 2. @@ -1395,7 +1395,7 @@ When changing Icinga Web configuration files make sure to clear the config cache > **Note** > > If you are using an older version of Icinga Web, install it like this and adapt -> the configuration manually as shown in [the RPM notes](#icinga-web-rpm-notes): +> the configuration manually as shown in [the RPM notes](2-getting-started.md#icinga-web-rpm-notes): > > `apt-get install --no-install-recommends icinga-web` @@ -1416,9 +1416,9 @@ please check the official [Icinga 1.x user interface documentation](http://docs. There are many visualization addons which can be used with Icinga 2. -Some of the more popular ones are [PNP](#addons-graphing-pnp), [inGraph](#addons-graphing-pnp) -(graphing performance data), [Graphite](#addons-graphing-pnp), and -[NagVis](#addons-visualization-nagvis) (network maps). +Some of the more popular ones are [PNP](6-addons-plugins.md#addons-graphing-pnp), [inGraph](6-addons-plugins.md#addons-graphing-pnp) +(graphing performance data), [Graphite](6-addons-plugins.md#addons-graphing-pnp), and +[NagVis](6-addons-plugins.md#addons-visualization-nagvis) (network maps). ## Configuration Tools @@ -1429,8 +1429,8 @@ or similar. > **Tip** > -> Get to know the new configuration format and the advanced [apply](#using-apply) rules and -> use [syntax highlighting](#configuration-syntax-highlighting) in vim/nano. +> Get to know the new configuration format and the advanced [apply](3-monitoring-basics.md#using-apply) rules and +> use [syntax highlighting](2-getting-started.md#configuration-syntax-highlighting) in vim/nano. If you're looking for puppet manifests, chef cookbooks, ansible recipes, etc - we're happy to integrate them upstream, so please get in touch at [https://support.icinga.org](https://support.icinga.org). @@ -1507,11 +1507,10 @@ for historical reasons. ### systemd Service -Some distributions (e.g. Fedora and openSUSE) already use `systemd`. Other -distributions such as RHEL7 changed to `systemd` recently. Icinga 2 Packages will install the -service automatically. +Some distributions (e.g. Fedora, openSUSE and RHEL/CentOS 7) use systemd. The Icinga 2 +packages automatically install the necessary systemd unit files. -The Icinga 2 `systemd` service can be (re)started, reloaded, stopped and also queried for its current status. +The Icinga 2 systemd service can be (re)started, reloaded, stopped and also queried for its current status. # systemctl status icinga2 icinga2.service - Icinga host/service/network monitoring system @@ -1532,7 +1531,7 @@ The Icinga 2 `systemd` service can be (re)started, reloaded, stopped and also qu Jul 23 13:39:38 nbmif icinga2[21692]: [2014-07-23 13:39:38 +0200] information/ConfigItem: Checked 8 Dependency(s). Jul 23 13:39:38 nbmif systemd[1]: Started Icinga host/service/network monitoring system. -`systemd` supports the following command actions: +The `systemctl` command supports the following actions: Command | Description --------------------|------------------------ @@ -1543,581 +1542,10 @@ The Icinga 2 `systemd` service can be (re)started, reloaded, stopped and also qu status | The `status` action checks if Icinga 2 is running. enable | The `enable` action enables the service being started at system boot time (similar to `chkconfig`) -If you're stuck with configuration errors, you can manually invoke the [configuration validation](#config-validation). +If you're stuck with configuration errors, you can manually invoke the [configuration validation](5-cli-commands.md#config-validation). # systemctl enable icinga2 # systemctl restart icinga2 Job for icinga2.service failed. See 'systemctl status icinga2.service' and 'journalctl -xn' for details. - - -### Icinga 2 CLI Commands - -Icinga 2 ships its own integrated CLI commands supporting bash-autocompletion. - -These CLI commands will allow you to use certain functionality -provided by and around the Icinga 2 daemon. - -> **Note** -> -> The CLI commands are available in Icinga 2 starting with *2.2*. - -Each CLI command provides its own help and usage information, so please -make sure to always run them withthe `--help` parameter. - -Run `icinga2` without any arguments (or using `--help`) to get a list of -all available global options. - - # icinga2 - - icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) - - Usage: - icinga2 [] - - Supported commands: - * daemon (starts Icinga 2) - * feature disable (disables specified feature) - * feature enable (enables specified feature) - * feature list (lists all enabled features) - * node add (add node) - * node blacklist add (adds a new blacklist filter) - * node blacklist list (lists all blacklist filters) - * node blacklist remove (removes a blacklist filter) - * node list (lists all nodes) - * node remove (removes node) - * node set (set node attributes) - * node setup (set up node) - * node update-config (update node config) - * node whitelist add (adds a new whitelist filter) - * node whitelist list (lists all whitelist filters) - * node whitelist remove (removes a whitelist filter) - * node wizard (wizard for node setup) - * object list (lists all objects) - * pki new-ca (sets up a new CA) - * pki new-cert (creates a new CSR) - * pki request (requests a certificate) - * pki save-cert (saves another Icinga 2 instance's certificate) - * pki sign-csr (signs a CSR) - * pki ticket (generates a ticket) - * repository clear-changes (clear uncommitted repository changes) - * repository commit (commit repository changes) - * repository endpoint add (adds a new Endpoint object) - * repository endpoint list (lists all Endpoint objects) - * repository endpoint remove (removes a Endpoint object) - * repository host add (adds a new Host object) - * repository host list (lists all Host objects) - * repository host remove (removes a Host object) - * repository service add (adds a new Service object) - * repository service list (lists all Service objects) - * repository service remove (removes a Service object) - * repository zone add (adds a new Zone object) - * repository zone list (lists all Zone objects) - * repository zone remove (removes a Zone object) - * variable get (gets a variable) - * variable list (lists all variables) - - Global options: - -h [ --help ] show this help message - -V [ --version ] show version information - --color use VT100 color codes even when stdout is not a - terminal - -D [ --define ] arg define a constant - -l [ --library ] arg load a library - -I [ --include ] arg add include search directory - -x [ --log-level ] arg specify the log level for the console log - - Command options: - - Report bugs at - Icinga home page: - - -#### Icinga 2 CLI Bash Autocompletion - -Bash Auto-Completion (pressing ``) is provided only for the corresponding context. - -While `--config` will suggest and auto-complete files and directories on disk, -`feature enable` will only suggest disabled features. `repository` will know -about object specific attributes, and so on. Try it yourself. - -RPM and Debian packages install the bash completion files into -`/etc/bash_completion.d/icinga2`. - -You will need to install the `bash-completion` package if not already installed. - -RHEL/CentOS/Fedora: - # yum install bash-completion - -SUSE: - # zypper install bash-completion - -Debian/Ubuntu: - # apt-get install bash-completion - -#### Icinga 2 CLI Global Options - -##### Libraries - -Instead of loading libraries using the [`library` config directive](#library) -you can also use the `--library` command-line option. - -##### Constants - -[Global constants](#constants) can be set using the `--define` command-line option. - -##### Config Include Path - -When including files you can specify that the include search path should be -checked. You can do this by putting your configuration file name in angle -brackets like this: - - include - -This would cause Icinga 2 to search its include path for the configuration file -`test.conf`. By default the installation path for the Icinga Template Library -is the only search directory. - -Using the `--include` command-line option additional search directories can be -added. - - - -#### Cli command: Daemon - -The CLI command `daemon` provides the functionality to start/stop Icinga 2. -Furthermore it provides the [configuration validation](#config-validation). - - # icinga2 daemon --help - icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) - - Usage: - icinga2 daemon [] - - Starts Icinga 2. - - Global options: - -h [ --help ] show this help message - -V [ --version ] show version information - --color use VT100 color codes even when stdout is not a - terminal - -D [ --define ] arg define a constant - -l [ --library ] arg load a library - -I [ --include ] arg add include search directory - -x [ --log-level ] arg specify the log level for the console log - - Command options: - -c [ --config ] arg parse a configuration file - -z [ --no-config ] start without a configuration file - -C [ --validate ] exit after validating the configuration - -e [ --errorlog ] arg log fatal errors to the specified log file (only works - in combination with --daemonize) - -d [ --daemonize ] detach from the controlling terminal - - Report bugs at - Icinga home page: - -##### Config Files - -Using the `--config` option you can specify one or more configuration files. -Config files are processed in the order they're specified on the command-line. - -When no configuration file is specified and the `--no-config` is not used -Icinga 2 automatically falls back to using the configuration file -`SysconfDir + "/icinga2/icinga2.conf"` (where SysconfDir is usually `/etc`). - -##### Config Validation - -The `--validate` option can be used to check if your configuration files -contain errors. If any errors are found the exit status is 1, otherwise 0 -is returned. More details in the [configuration validation](#config-validation) chapter. - - -#### Cli command: Feature - -The CLI commands for `enable` and `disable` feature support bash auto-completion -and will only suggest features for the corresponding context. Like disabling a -feature will only bring up all enabled features. - - # icinga2 feature disable - checker --color --define --help --include --library --log-level mainlog notification --version - - # icinga2 feature enable - api command debuglog graphite icingastatus ido-pgsql --library --log-level statusdata --version - --color compatlog --define --help ido-mysql --include livestatus perfdata syslog - -#### Cli command: Node - -Provides the functionality to install and manage master and client -nodes in a [remote monitoring ](#icinga2-remote-client-monitoring) or -[distributed cluster](#distributed-monitoring-high-availability) scenario. - - - # icinga2 node --help - icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) - - Usage: - icinga2 [] - - Supported commands: - * node add (add node) - * node blacklist add (adds a new blacklist filter) - * node blacklist list (lists all blacklist filters) - * node blacklist remove (removes a blacklist filter) - * node list (lists all nodes) - * node remove (removes node) - * node set (set node attributes) - * node setup (set up node) - * node update-config (update node config) - * node whitelist add (adds a new whitelist filter) - * node whitelist list (lists all whitelist filters) - * node whitelist remove (removes a whitelist filter) - * node wizard (wizard for node setup) - - Global options: - -h [ --help ] show this help message - -V [ --version ] show version information - --color use VT100 color codes even when stdout is not a - terminal - -D [ --define ] arg define a constant - -l [ --library ] arg load a library - -I [ --include ] arg add include search directory - -x [ --log-level ] arg specify the log level for the console log - - Command options: - - Report bugs at - Icinga home page: - - -#### Cli command: Object - -The `object` CLI command can be used to list all configuration objects and their -attributes. The command also shows where each of the attributes was modified. -That way you can also identify which objects have been created from your [apply rules](#apply). - -More information can be found in the [troubleshooting](#list-configuration-objects) section. - - # icinga2 object --help - icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) - - Usage: - icinga2 [] - - Supported commands: - * object list (lists all objects) - - Global options: - -h [ --help ] show this help message - -V [ --version ] show version information - --color use VT100 color codes even when stdout is not a - terminal - -D [ --define ] arg define a constant - -l [ --library ] arg load a library - -I [ --include ] arg add include search directory - -x [ --log-level ] arg specify the log level for the console log - - Command options: - - Report bugs at - Icinga home page: - - - -#### Cli command: Pki - -Provides the CLI commands to - -* generate a new local CA -* generate a new CSR or self-signed certificate -* sign a CSR and return a certificate -* save a master certificate manually -* request a signed certificate from the master -* generate a new ticket for the client setup - -This functionality is used by the [node setup/wizard](#cli-command-pki) CLI commands too. - - # icinga2 pki --help - icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) - - Usage: - icinga2 [] - - Supported commands: - * pki new-ca (sets up a new CA) - * pki new-cert (creates a new CSR) - * pki request (requests a certificate) - * pki save-cert (saves another Icinga 2 instance's certificate) - * pki sign-csr (signs a CSR) - * pki ticket (generates a ticket) - - Global options: - -h [ --help ] show this help message - -V [ --version ] show version information - --color use VT100 color codes even when stdout is not a - terminal - -D [ --define ] arg define a constant - -l [ --library ] arg load a library - -I [ --include ] arg add include search directory - -x [ --log-level ] arg specify the log level for the console log - - Command options: - - Report bugs at - Icinga home page: - - -#### Cli command: Repository - -Provides the functionality to manage the Icinga 2 configuration repository in -`/etc/icinga2/repository.d`. All changes are logged and must be committed or -cleared after review. - - -> **Note** -> -> The CLI command `repository` only supports basic configuration manipulation (add, remove) -> and a limited set of objects required for the [remote client] integration. Future -> versions will support more options (set, etc.). -> -> Please check the Icinga 2 development roadmap for updates. - - - # icinga2 repository --help - icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) - - Usage: - icinga2 [] - - Supported commands: - * repository clear-changes (clear uncommitted repository changes) - * repository commit (commit repository changes) - * repository endpoint add (adds a new Endpoint object) - * repository endpoint list (lists all Endpoint objects) - * repository endpoint remove (removes a Endpoint object) - * repository host add (adds a new Host object) - * repository host list (lists all Host objects) - * repository host remove (removes a Host object) - * repository service add (adds a new Service object) - * repository service list (lists all Service objects) - * repository service remove (removes a Service object) - * repository zone add (adds a new Zone object) - * repository zone list (lists all Zone objects) - * repository zone remove (removes a Zone object) - - Global options: - -h [ --help ] show this help message - -V [ --version ] show version information - --color use VT100 color codes even when stdout is not a - terminal - -D [ --define ] arg define a constant - -l [ --library ] arg load a library - -I [ --include ] arg add include search directory - -x [ --log-level ] arg specify the log level for the console log - - Command options: - - Report bugs at - Icinga home page: - - - -#### Cli command: Variable - -Lists all configured variables (constants) in a similar fasion like [object list](#cli-command-object). - - # icinga2 variable --help - icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) - - Usage: - icinga2 [] - - Supported commands: - * variable get (gets a variable) - * variable list (lists all variables) - - Global options: - -h [ --help ] show this help message - -V [ --version ] show version information - --color use VT100 color codes even when stdout is not a - terminal - -D [ --define ] arg define a constant - -l [ --library ] arg load a library - -I [ --include ] arg add include search directory - -x [ --log-level ] arg specify the log level for the console log - - Command options: - - Report bugs at - Icinga home page: - - - - - -### Enabling/Disabling Features - -Icinga 2 provides configuration files for some commonly used features. These -are installed in the `/etc/icinga2/features-available` directory and can be -enabled and disabled using the `icinga2 feature enable` and `icinga2 feature disable` -[CLI commands](#cli-command-feature), respectively. - -The `icinga2 feature enable` CLI command creates symlinks in the -`/etc/icinga2/features-enabled` directory which is included by default -in the example configuration file. - -You can view a list of enabled and disabled features: - - # icinga2 feature list - Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog - Enabled features: checker mainlog notification - -Using the `icinga2 feature enable` command you can enable features: - - # icinga2 feature enable graphite - Enabling feature graphite. Make sure to restart Icinga 2 for these changes to take effect. - - -You can disable features using the `icinga2 feature disable` command: - - # icinga2 feature disable ido-mysql livestatus - Disabling feature ido-mysql. Make sure to restart Icinga 2 for these changes to take effect. - Disabling feature livestatus. Make sure to restart Icinga 2 for these changes to take effect. - - -The `icinga2 feature enable` and `icinga2 feature disable` commands do not -restart Icinga 2. You will need to restart Icinga 2 using the init script -after enabling or disabling features. - - - -### Configuration Validation - -Once you've edited the configuration files make sure to tell Icinga 2 to validate -the configuration changes. Icinga 2 will log any configuration error including -a hint on the file, the line number and the affected configuration line itself. - -The following example creates an apply rule without any `assign` condition. - - apply Service "5872-ping4" { - import "generic-service" - check_command = "ping4" - //assign where match("5872-*", host.name) - } - -Validate the configuration with the init script option `checkconfig`: - - # /etc/init.d/icinga2 checkconfig - -> **Note** -> -> Using [systemd](#systemd-service) you need to manually validate the configuration using -> the CLI command below. - -Or manually passing the `-C` argument: - - # /usr/sbin/icinga2 daemon -c /etc/icinga2/icinga2.conf -C - - [2014-05-22 17:07:25 +0200] critical/ConfigItem: Location: - /etc/icinga2/conf.d/tests/5872.conf(5): } - /etc/icinga2/conf.d/tests/5872.conf(6): - /etc/icinga2/conf.d/tests/5872.conf(7): apply Service "5872-ping4" { - ^^^^^^^^^^^^^ - /etc/icinga2/conf.d/tests/5872.conf(8): import "test-generic-service" - /etc/icinga2/conf.d/tests/5872.conf(9): check_command = "ping4" - - Config error: 'apply' is missing 'assign' - [2014-05-22 17:07:25 +0200] critical/ConfigItem: 1 errors, 0 warnings. - Icinga 2 detected configuration errors. - -> **Tip** -> -> Icinga 2 will automatically detect the default path for `icinga2.conf` -> in `SysconfDir + /icinga2/icinga2.conf` and you can safely omit this parameter. -> -> `# icinga2 daemon -C` - -If you encouter errors during configuration validation, please make sure -to read the [troubleshooting](#troubleshooting) chapter. - -You can also use the [CLI command](#cli-command-object) `icinga2 object list` -after validation passes to analyze object attributes, inheritance or created -objects by apply rules. -Find more on troubleshooting with `object list` in [this chapter](#list-configuration-objects). - -Example filtered by `Service` objects with the name `ping*`: - - # icinga2 object list --type Service --name *ping* - Object 'nbmif.int.netways.de!ping4' of type 'Service': - * __name = 'nbmif.int.netways.de!ping4' - * check_command = 'ping4' - % = modified in '/etc/icinga2/conf.d/services.conf', lines 17:3-17:25 - * check_interval = 60 - % = modified in '/etc/icinga2/conf.d/templates.conf', lines 28:3-28:21 - * host_name = 'nbmif.int.netways.de' - % = modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21 - * max_check_attempts = 3 - % = modified in '/etc/icinga2/conf.d/templates.conf', lines 27:3-27:24 - * name = 'ping4' - % = modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21 - * retry_interval = 30 - % = modified in '/etc/icinga2/conf.d/templates.conf', lines 29:3-29:22 - * templates = [ 'ping4', 'generic-service' ] - % += modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21 - % += modified in '/etc/icinga2/conf.d/templates.conf', lines 26:1-30:1 - * type = 'Service' - * vars - % += modified in '/etc/icinga2/conf.d/services.conf', lines 18:3-18:19 - * sla = '24x7' - % = modified in '/etc/icinga2/conf.d/services.conf', lines 18:3-18:19 - - - -### Reload on Configuration Changes - -Everytime you have changed your configuration you should first tell Icinga 2 -to [validate](#config-validation). If there are no validation errors you can -safely reload the Icinga 2 daemon. - - # /etc/init.d/icinga2 reload - -> **Note** -> -> The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon -> which will validate the configuration in a separate process and not stop -> the other events like check execution, notifications, etc. -> -> Details can be found [here](#differences-1x-2-real-reload). - - -## Vagrant Demo VM - -The Icinga Vagrant Git repository contains support for [Vagrant](http://docs.vagrantup.com/v2/) -with VirtualBox. Please note that Vagrant version `1.0.x` is not supported. At least -version `1.2.x` is required. - -In order to build the Vagrant VM first you will have to check out -the Git repository: - - $ git clone git://git.icinga.org/icinga-vagrant.git - -For Icinga 2 there are currently two scenarios available: - -* `icinga2x` bringing up a standalone box with Icinga 2 -* `icinga2x-cluster` setting up two virtual machines in a master/slave cluster - -> **Note** -> -> Please consult the `README.md` file for each project for further installation -> details at [https://github.com/Icinga/icinga-vagrant] - -Once you have checked out the Git repository navigate to your required -vagrant box and build the VM using the following command: - - $ vagrant up - -The Vagrant VMs are based on CentOS 6.x and are using the official -Icinga 2 RPM snapshot packages from `packages.icinga.org`. The check -plugins are installed from EPEL providing RPMs with sources from the -Monitoring Plugins project. diff --git a/doc/3-monitoring-basics.md b/doc/3-monitoring-basics.md index dbec2ef95..4aaafb0e6 100644 --- a/doc/3-monitoring-basics.md +++ b/doc/3-monitoring-basics.md @@ -43,7 +43,7 @@ check command. The `address` attribute is used by check commands to determine which network address is associated with the host object. -Details on troubleshooting check problems can be found [here](#troubleshooting). +Details on troubleshooting check problems can be found [here](7-troubleshooting.md#troubleshooting). ### Host States @@ -95,13 +95,13 @@ there is no check available, the `dummy` check command. } Service checks could also use a `dummy` check, but the common strategy is to -[integrate an existing plugin](#command-plugin-integration) as -[check command](#check-commands) and [reference](#command-passing-parameters) -that in your [Service](#objecttype-service) object definition. +[integrate an existing plugin](3-monitoring-basics.md#command-plugin-integration) as +[check command](3-monitoring-basics.md#check-commands) and [reference](3-monitoring-basics.md#command-passing-parameters) +that in your [Service](11-object-types.md#objecttype-service) object definition. ## Configuration Best Practice -The [Getting Started](#getting-started) chapter already introduced various aspects +The [Getting Started](2-getting-started.md#getting-started) chapter already introduced various aspects of the Icinga 2 configuration language. If you are ready to configure additional hosts, services, notifications, dependencies, etc, you should think about the requirements first and then decide for a possible strategy. @@ -109,7 +109,7 @@ requirements first and then decide for a possible strategy. There are many ways of creating Icinga 2 configuration objects: * Manually with your preferred editor, for example vi(m), nano, notepad, etc. -* Generated by a [configuration management too](#configuration-tools) such as Puppet, Chef, Ansible, etc. +* Generated by a [configuration management too](2-getting-started.md#configuration-tools) such as Puppet, Chef, Ansible, etc. * A configuration addon for Icinga 2 * A custom exporter script from your CMDB or inventory tool * your own. @@ -119,7 +119,7 @@ In order to find the best strategy for your own configuration, ask yourself the * Do your hosts share a common group of services (for example linux hosts with disk, load, etc checks)? * Only a small set of users receives notifications and escalations for all hosts/services? -If you can at least answer one of these questions with yes, look for the [apply rules](#using-apply) logic +If you can at least answer one of these questions with yes, look for the [apply rules](3-monitoring-basics.md#using-apply) logic instead of defining objects on a per host and service basis. * You are required to define specific configuration for each host/service? @@ -128,7 +128,7 @@ instead of defining objects on a per host and service basis. Then you should look for the object specific configuration setting `host_name` etc accordingly. Finding the best files and directory tree for your configuration is up to you. Make sure that -the [icinga2.conf](#icinga2-conf) configuration file includes them, and then think about: +the [icinga2.conf](2-getting-started.md#icinga2-conf) configuration file includes them, and then think about: * tree-based on locations, hostgroups, specific host attributes with sub levels of directories. * flat `hosts.conf`, `services.conf`, etc files for rule based configuration. @@ -143,10 +143,10 @@ You can later use them for applying assign/ignore rules, or export them into ext * Put hosts into hostgroups, services into servicegroups and use these attributes for your apply rules. * Use templates to store generic attributes for your objects and apply rules making your configuration more readable. Details can be found in the [using templates](#using-templates) chapter. -* Apply rules may overlap. Keep a central place (for example, [services.conf](#services-conf) or [notifications.conf](#notifications-conf)) storing +* Apply rules may overlap. Keep a central place (for example, [services.conf](2-getting-started.md#services-conf) or [notifications.conf](2-getting-started.md#notifications-conf)) storing the configuration instead of defining apply rules deep in your configuration tree. * Every plugin used as check, notification or event command requires a `Command` definition. -Further details can be looked up in the [check commands](#check-commands) chapter. +Further details can be looked up in the [check commands](3-monitoring-basics.md#check-commands) chapter. If you happen to have further questions, do not hesitate to join the [community support channels](https://support.icinga.org) and ask community members for their experience and best practices. @@ -213,18 +213,18 @@ Example for importing objects: ### Apply objects based on rules -Instead of assigning each object ([Service](#objecttype-service), -[Notification](#objecttype-notification), [Dependency](#objecttype-dependency), -[ScheduledDowntime](#objecttype-scheduleddowntime)) -based on attribute identifiers for example `host_name` objects can be [applied](#apply). +Instead of assigning each object ([Service](11-object-types.md#objecttype-service), +[Notification](11-object-types.md#objecttype-notification), [Dependency](11-object-types.md#objecttype-dependency), +[ScheduledDowntime](11-object-types.md#objecttype-scheduleddowntime)) +based on attribute identifiers for example `host_name` objects can be [applied](9-language-reference.md#apply). Before you start using the apply rules keep the following in mind: * Define the best match. - * A set of unique [custom attributes](#custom-attributes-apply) for these hosts/services? - * Or [group](#groups) memberships, e.g. a host being a member of a hostgroup, applying services to it? - * A generic pattern [match](#function-calls) on the host/service name? - * [Multiple expressions combined](#using-apply-expressions) with `&&` or `||` [operators](#expression-operators) + * A set of unique [custom attributes](3-monitoring-basics.md#custom-attributes-apply) for these hosts/services? + * Or [group](3-monitoring-basics.md#groups) memberships, e.g. a host being a member of a hostgroup, applying services to it? + * A generic pattern [match](9-language-reference.md#function-calls) on the host/service name? + * [Multiple expressions combined](3-monitoring-basics.md#using-apply-expressions) with `&&` or `||` [operators](9-language-reference.md#expression-operators) * All expressions must return a boolean value (an empty string is equal to `false` e.g.) > **Note** @@ -232,24 +232,24 @@ Before you start using the apply rules keep the following in mind: > You can set/override object attributes in apply rules using the respectively available > objects in that scope (host and/or service objects). -[Custom attributes](#custom-attributes) can also store nested dictionaries and arrays. That way you can use them +[Custom attributes](3-monitoring-basics.md#custom-attributes) can also store nested dictionaries and arrays. That way you can use them for not only matching for their existance or values in apply expressions, but also assign ("inherit") their values into the generated objected from apply rules. -* [Apply services to hosts](#using-apply-services) -* [Apply notifications to hosts and services](#using-apply-notifications) -* [Apply dependencies to hosts and services](#using-apply-scheduledowntimes) -* [Apply scheduled downtimes to hosts and services](#using-apply-scheduledowntimes) +* [Apply services to hosts](3-monitoring-basics.md#using-apply-services) +* [Apply notifications to hosts and services](3-monitoring-basics.md#using-apply-notifications) +* [Apply dependencies to hosts and services](3-monitoring-basics.md#using-apply-scheduledowntimes) +* [Apply scheduled downtimes to hosts and services](3-monitoring-basics.md#using-apply-scheduledowntimes) A more advanced example is using [apply with for loops on arrays or dictionaries](#using-apply-for) for example provided by -[custom atttributes](#custom-attributes-apply) or groups. +[custom atttributes](3-monitoring-basics.md#custom-attributes-apply) or groups. > **Tip** > > Building configuration in that dynamic way requires detailed information -> of the generated objects. Use the `object list` [CLI command](#cli-command-object) -> after successful [configuration validation](#config-validation). +> of the generated objects. Use the `object list` [CLI command](5-cli-commands.md#cli-command-object) +> after successful [configuration validation](5-cli-commands.md#config-validation). #### Apply Rules Expressions @@ -288,7 +288,7 @@ two condition passes: Either the `customer` host custom attribute is set to `cus `OR` the host custom attribute `always_notify` is set to `true`. The notification is ignored for services whose host name ends with `*internal` -`OR` the `priority` custom attribute is [less than](#expression-operators) `2`. +`OR` the `priority` custom attribute is [less than](9-language-reference.md#expression-operators) `2`. template Notification "cust-xy-notification" { users = [ "noc-xy", "mgmt-xy" ] @@ -307,8 +307,8 @@ The notification is ignored for services whose host name ends with `*internal` #### Apply Services to Hosts -The sample configuration already ships a detailed example in [hosts.conf](#hosts-conf) -and [services.conf](#services-conf) for this use case. +The sample configuration already ships a detailed example in [hosts.conf](2-getting-started.md#hosts-conf) +and [services.conf](2-getting-started.md#services-conf) for this use case. The example for `ssh` applies a service object to all hosts with the `address` attribute being defined and the custom attribute `os` set to the string `Linux` in `vars`. @@ -323,7 +323,7 @@ attribute being defined and the custom attribute `os` set to the string `Linux` Other detailed scenario examples are used in their respective chapters, for example -[apply services with custom command arguments](#using-apply-services-command-arguments). +[apply services with custom command arguments](3-monitoring-basics.md#using-apply-services-command-arguments). #### Apply Notifications to Hosts and Services @@ -346,13 +346,13 @@ and all members of the user group `noc` will get notified. #### Apply Dependencies to Hosts and Services -Detailed examples can be found in the [dependencies](#dependencies) chapter. +Detailed examples can be found in the [dependencies](3-monitoring-basics.md#dependencies) chapter. #### Apply Recurring Downtimes to Hosts and Services -The sample confituration ships an example in [downtimes.conf](#downtimes-conf). +The sample confituration ships an example in [downtimes.conf](2-getting-started.md#downtimes-conf). -Detailed examples can be found in the [recurring downtimes](#recurring-downtimes) chapter. +Detailed examples can be found in the [recurring downtimes](3-monitoring-basics.md#recurring-downtimes) chapter. #### Using Apply For Rules @@ -362,8 +362,8 @@ apply rules objects based on set (array or dictionary). That way you'll save qui of a lot of duplicated apply rules by combining them into one generic generating the object name with or without a prefix. -The sample configuration already ships a detailed example in [hosts.conf](#hosts-conf) -and [services.conf](#services-conf) for this use case. +The sample configuration already ships a detailed example in [hosts.conf](2-getting-started.md#hosts-conf) +and [services.conf](2-getting-started.md#services-conf) for this use case. Imagine a different example: You are monitoring your switch (hosts) with many interfaces (services). The following requirements/problems apply: @@ -432,13 +432,13 @@ You can also specifiy the check command that way. } Note that numbers must be explicitely casted to string when adding to strings. -This can be achieved by wrapping them into the [string()](#function-calls) function. +This can be achieved by wrapping them into the [string()](9-language-reference.md#function-calls) function. > **Tip** > > Building configuration in that dynamic way requires detailed information -> of the generated objects. Use the `object list` [CLI command](#cli-command-object) -> after successful [configuration validation](#config-validation). +> of the generated objects. Use the `object list` [CLI command](5-cli-commands.md#cli-command-object) +> after successful [configuration validation](5-cli-commands.md#config-validation). #### Use Object Attributes in Apply Rules @@ -541,11 +541,11 @@ the user groups are associated as attributes in `Notification` objects. email = "ops@example.com" } -#### Group Membership Assign +#### Group Membership Assign If there is a certain number of hosts, services, or users matching a pattern it's reasonable to assign the group object to these members. -Details on the `assign where` syntax can be found [here](#apply) +Details on the `assign where` syntax can be found [here](9-language-reference.md#apply) object HostGroup "prod-mssql" { display_name = "Production MSSQL Servers" @@ -590,18 +590,18 @@ The user `icingaadmin` in the example below will get notified only on `WARNING` If you don't set the `states` and `types` configuration attributes for the `User` object, notifications for all states and types will be sent. -Details on troubleshooting notification problems can be found [here](#troubleshooting). +Details on troubleshooting notification problems can be found [here](7-troubleshooting.md#troubleshooting). > **Note** > -> Make sure that the [notification](#features) feature is enabled on your master instance +> Make sure that the [notification](5-cli-commands.md#features) feature is enabled on your master instance > in order to execute notification commands. You should choose which information you (and your notified users) are interested in case of emergency, and also which information does not provide any value to you and your environment. -An example notification command is explained [here](#notification-commands). +An example notification command is explained [here](3-monitoring-basics.md#notification-commands). You can add all shared attributes to a `Notification` template which is inherited to the defined notifications. That way you'll save duplicated attributes in each @@ -881,30 +881,30 @@ events should be handled. ### Environment Variables for Commands -Please check [Runtime Custom Attributes as Environment Variables](#runtime-custom-attribute-env-vars). +Please check [Runtime Custom Attributes as Environment Variables](3-monitoring-basics.md#runtime-custom-attribute-env-vars). ### Check Commands -[CheckCommand](#objecttype-checkcommand) objects define the command line how +[CheckCommand](11-object-types.md#objecttype-checkcommand) objects define the command line how a check is called. -[CheckCommand](#objecttype-checkcommand) objects are referenced by -[Host](#objecttype-host) and [Service](#objecttype-service) objects +[CheckCommand](11-object-types.md#objecttype-checkcommand) objects are referenced by +[Host](11-object-types.md#objecttype-host) and [Service](11-object-types.md#objecttype-service) objects using the `check_command` attribute. > **Note** > -> Make sure that the [checker](#features) feature is enabled in order to +> Make sure that the [checker](5-cli-commands.md#features) feature is enabled in order to > execute checks. #### Integrate the Plugin with a CheckCommand Definition -[CheckCommand](#objecttype-checkcommand) objects require the [ITL template](#itl-plugin-check-command) +[CheckCommand](11-object-types.md#objecttype-checkcommand) objects require the [ITL template](12-icinga-template-library.md#itl-plugin-check-command) `plugin-check-command` to support native plugin based check methods. Unless you have done so already, download your check plugin and put it -into the [PluginDir](#constants-conf) directory. The following example uses the +into the [PluginDir](2-getting-started.md#constants-conf) directory. The following example uses the `check_disk` plugin shipped with the Monitoring Plugins package. The plugin path and all command arguments are made a list of @@ -932,7 +932,7 @@ partition defined (`-p`) it will check all local partitions. > Don't execute plugins as `root` and always use the absolute path to the plugin! Trust us. Next step is to understand how command parameters are being passed from -a host or service object, and add a [CheckCommand](#objecttype-checkcommand) +a host or service object, and add a [CheckCommand](11-object-types.md#objecttype-checkcommand) definition based on these required parameters and/or default values. #### Passing Check Command Parameters from Host or Service @@ -942,7 +942,7 @@ by the executed check command. Define the default check command custom attribute `disk_wfree` and `disk_cfree` (freely definable naming schema) and their default threshold values. You can -then use these custom attributes as runtime macros for [command arguments](#command-arguments) +then use these custom attributes as runtime macros for [command arguments](3-monitoring-basics.md#command-arguments) on the command line. > **Tip** @@ -976,7 +976,7 @@ can also be inherited from a parent template using additive inheritance (`+=`). > **Note** > > A proper example for the `check_disk` plugin is already shipped with Icinga 2 -> ready to use with the [plugin check commands](#plugin-check-command-disk). +> ready to use with the [plugin check commands](12-icinga-template-library.md#plugin-check-command-disk). The host `localhost` with the applied service `basic-partitions` checks a basic set of disk partitions with modified custom attributes (warning thresholds at `10%`, critical thresholds at `5%` @@ -1009,7 +1009,7 @@ string values for passing multiple partitions to the `check_disk` check plugin. More details on using arrays in custom attributes can be found in -[this chapter](#runtime-custom-attributes). +[this chapter](3-monitoring-basics.md#runtime-custom-attributes). #### Command Arguments @@ -1072,7 +1072,7 @@ That way you can use the `check_http` command definition for both, with and without SSL enabled checks saving you duplicated command definitions. Details on all available options can be found in the -[CheckCommand object definition](#objecttype-checkcommand). +[CheckCommand object definition](11-object-types.md#objecttype-checkcommand). ### Apply Services with Custom Command Arguments @@ -1100,7 +1100,7 @@ the `my-host2` host requires a different port on 2222. Both hosts are in the hos } All hosts in the `my-linux-servers` hostgroup should get the `my-ssh` service applied based on an -[apply rule](#apply). The optional `ssh_port` command argument should be inherited from the host +[apply rule](9-language-reference.md#apply). The optional `ssh_port` command argument should be inherited from the host the service is applied to. If not set, the check command `my-ssh` will omit the argument. The `host` argument is special: `skip_key` tells Icinga 2 to ignore the key, and directly put the value onto the command line. The `order` attribute specifies that this argument is the first one @@ -1145,18 +1145,18 @@ The `my-host2` will inherit the `custom_ssh_port` variable to the service and ex ### Notification Commands -[NotificationCommand](#objecttype-notificationcommand) objects define how notifications are delivered to external +[NotificationCommand](11-object-types.md#objecttype-notificationcommand) objects define how notifications are delivered to external interfaces (E-Mail, XMPP, IRC, Twitter, etc). -[NotificationCommand](#objecttype-notificationcommand) objects are referenced by -[Notification](#objecttype-notification) objects using the `command` attribute. +[NotificationCommand](11-object-types.md#objecttype-notificationcommand) objects are referenced by +[Notification](11-object-types.md#objecttype-notification) objects using the `command` attribute. -`NotificationCommand` objects require the [ITL template](#itl-plugin-notification-command) +`NotificationCommand` objects require the [ITL template](12-icinga-template-library.md#itl-plugin-notification-command) `plugin-notification-command` to support native plugin-based notifications. > **Note** > -> Make sure that the [notification](#features) feature is enabled on your master instance +> Make sure that the [notification](5-cli-commands.md#features) feature is enabled on your master instance > in order to execute notification commands. Below is an example using runtime macros from Icinga 2 (such as `$service.output$` for @@ -1227,12 +1227,12 @@ NotificationCommand object refer to that. Unlike notifications event commands for hosts/services are called on every check execution if one of these conditions match: -* The host/service is in a [soft state](#hard-soft-states) -* The host/service state changes into a [hard state](#hard-soft-states) -* The host/service state recovers from a [soft or hard state](#hard-soft-states) to [OK](#service-states)/[Up](#host-states) +* The host/service is in a [soft state](3-monitoring-basics.md#hard-soft-states) +* The host/service state changes into a [hard state](3-monitoring-basics.md#hard-soft-states) +* The host/service state recovers from a [soft or hard state](#hard-soft-states) to [OK](3-monitoring-basics.md#service-states)/[Up](3-monitoring-basics.md#host-states) -[EventCommand](#objecttype-eventcommand) objects are referenced by -[Host](#objecttype-host) and [Service](#objecttype-service) objects +[EventCommand](11-object-types.md#objecttype-eventcommand) objects are referenced by +[Host](11-object-types.md#objecttype-host) and [Service](11-object-types.md#objecttype-service) objects using the `event_command` attribute. Therefore the `EventCommand` object should define a command line @@ -1269,7 +1269,7 @@ Example on Debian: icinga ALL=(ALL) NOPASSWD: /etc/init.d/apache2 restart -Define a generic [EventCommand](#objecttype-eventcommand) object `event_by_ssh` +Define a generic [EventCommand](11-object-types.md#objecttype-eventcommand) object `event_by_ssh` which can be used for all event commands triggered using ssh: /* pass event commands through ssh */ @@ -1370,7 +1370,7 @@ Remote Host Terminal: ## Dependencies -Icinga 2 uses host and service [Dependency](#objecttype-dependency) objects +Icinga 2 uses host and service [Dependency](11-object-types.md#objecttype-dependency) objects for determing their network reachability. A service can depend on a host, and vice versa. A service has an implicit @@ -1381,8 +1381,8 @@ account but all parents are inherited. The `parent_host_name` and `parent_service_name` attributes are mandatory for service dependencies, `parent_host_name` is required for host dependencies. -[Apply rules](#using-apply) will allow you to -[determine these attributes](#dependencies-apply-custom-attributes) in a more +[Apply rules](3-monitoring-basics.md#using-apply) will allow you to +[determine these attributes](3-monitoring-basics.md#dependencies-apply-custom-attributes) in a more dynamic fashion if required. parent_host_name = "core-router" @@ -1405,7 +1405,7 @@ Rephrased: If the parent service object changes into the `Warning` state, this dependency will fail and render all child objects (hosts or services) unreachable. You can determine the child's reachability by querying the `is_reachable` attribute -in for example [DB IDO](#schema-db-ido-extensions). +in for example [DB IDO](13-appendix.md#schema-db-ido-extensions). ### Implicit Dependencies for Services on Host @@ -1471,7 +1471,7 @@ be suppressed. This is achieved by setting the `disable_checks` attribute to `tr ### Apply Dependencies based on Custom Attributes -You can use [apply rules](#using-apply) to set parent or +You can use [apply rules](3-monitoring-basics.md#using-apply) to set parent or child attributes e.g. `parent_host_name`to other object's attributes. @@ -1640,7 +1640,7 @@ is removed (may happen before or after the actual end time!). ### Scheduling a downtime -This can either happen through a web interface or by sending an [external command](#external-commands) +This can either happen through a web interface or by sending an [external command](3-monitoring-basics.md#external-commands) to the external command pipe provided by the `ExternalCommandListener` configuration. Fixed downtimes require a start and end time (a duration will be ignored). @@ -1657,7 +1657,7 @@ downtime on NOT-OK state change. ### Recurring Downtimes -[ScheduledDowntime objects](#objecttype-scheduleddowntime) can be used to set up +[ScheduledDowntime objects](11-object-types.md#objecttype-scheduleddowntime) can be used to set up recurring downtimes for services. Example: @@ -1680,7 +1680,7 @@ Example: } -## Comments +## Comments Comments can be added at runtime and are persistent over restarts. You can add useful information for others on repeating incidents (for example @@ -1726,14 +1726,14 @@ Custom attributes are not only used at runtime in command definitions to pass command arguments, but are also a smart way to define patterns and groups for applying objects for dynamic config generation. -There are several ways of using custom attributes with [apply rules](#using-apply): +There are several ways of using custom attributes with [apply rules](3-monitoring-basics.md#using-apply): * As simple attribute literal ([number](#numeric-literal), [string](#string-literal), [boolean](#boolean-literal)) for expression conditions (`assign where`, `ignore where`) -* As [array](#array) or [dictionary](#dictionary) attribute with nested values -(e.g. dictionaries in dictionaries) in [apply for](#using-apply-for) rules. +* As [array](9-language-reference.md#array) or [dictionary](9-language-reference.md#dictionary) attribute with nested values +(e.g. dictionaries in dictionaries) in [apply for](3-monitoring-basics.md#using-apply-for) rules. -Features like [DB IDO](#db-ido), Livestatus(#livestatus) or StatusData(#status-data) +Features like [DB IDO](3-monitoring-basics.md#db-ido), Livestatus(#livestatus) or StatusData(#status-data) dump this column as encoded JSON string, and set `is_json` resp. `cv_is_json` to `1`. If arrays are used in runtime macros (for example `$host.groups$`) all entries @@ -1745,13 +1745,13 @@ it is escaped like this: `entry1;ent\;ry2;entry3`. Custom attributes may be used in command definitions to dynamically change how the command is executed. -Additionally there are Icinga 2 features such as the [PerfDataWriter](#performance-data) feature +Additionally there are Icinga 2 features such as the [PerfDataWriter](3-monitoring-basics.md#performance-data) feature which use custom runtime attributes to format their output. > **Tip** > > Custom attributes are identified by the `vars` dictionary attribute as short name. -> Accessing the different attribute keys is possible using the [index accessor](#indexer) `.`. +> Accessing the different attribute keys is possible using the [index accessor](9-language-reference.md#indexer) `.`. Custom attributes in command definitions or performance data templates are evaluated at runtime when executing a command. These custom attributes cannot be used somewhere else @@ -1764,13 +1764,13 @@ Arrays can be used to pass multiple arguments with or without repeating the key This helps passing multiple parameters to check plugins requiring them. Prominent plugin examples are: -* [check_disk -p](#plugin-check-command-disk) -* [check_nrpe -a](#plugin-check-command-nrpe) -* [check_nscp -l](#plugin-check-command-nscp) -* [check_dns -a](#plugin-check-command-dns) +* [check_disk -p](12-icinga-template-library.md#plugin-check-command-disk) +* [check_nrpe -a](12-icinga-template-library.md#plugin-check-command-nrpe) +* [check_nscp -l](12-icinga-template-library.md#plugin-check-command-nscp) +* [check_dns -a](12-icinga-template-library.md#plugin-check-command-dns) More details on how to use `repeat_key` and other command argument options can be -found in [this section](#objecttype-checkcommand-arguments). +found in [this section](11-object-types.md#objecttype-checkcommand-arguments). > **Note** > @@ -1816,11 +1816,11 @@ for example `$address$`. > When using the `$` sign as single character, you need to escape it with an > additional dollar sign (`$$`). -This example also makes use of the [command arguments](#command-arguments) passed +This example also makes use of the [command arguments](3-monitoring-basics.md#command-arguments) passed to the command line. You can integrate the above example `CheckCommand` definition -[passing command argument parameters](#command-passing-parameters) like this: +[passing command argument parameters](3-monitoring-basics.md#command-passing-parameters) like this: object Host "my-icmp-host" { import "generic-host" @@ -1963,7 +1963,7 @@ external commands). ### Runtime Macro Evaluation Order -Custom attributes can be accessed at [runtime](#runtime-custom-attributes) using their +Custom attributes can be accessed at [runtime](3-monitoring-basics.md#runtime-custom-attributes) using their identifier omitting the `vars.` prefix. There are special cases when those custom attributes are not set and Icinga 2 provides a fallback to existing object attributes for example `host.address`. @@ -2204,7 +2204,7 @@ a forced service check: ### External Command List -A list of currently supported external commands can be found [here](#external-commands-list-detail). +A list of currently supported external commands can be found [here](13-appendix.md#external-commands-list-detail). Detailed information on the commands and their required parameters can be found on the [Icinga 1.x documentation](http://docs.icinga.org/latest/en/extcommands2.html). @@ -2290,9 +2290,9 @@ The current naming schema is You can customize the metric prefix name by using the `host_name_template` and `service_name_template` configuration attributes. -The example below uses [runtime macros](#runtime-macros) and a -[global constant](#constants) named `GraphiteEnv`. The constant name -is freely definable and should be put in the [constants.conf](#constants-conf) file. +The example below uses [runtime macros](3-monitoring-basics.md#runtime-macros) and a +[global constant](9-language-reference.md#constants) named `GraphiteEnv`. The constant name +is freely definable and should be put in the [constants.conf](2-getting-started.md#constants-conf) file. const GraphiteEnv = "icinga.env1" @@ -2385,7 +2385,7 @@ in Icinga 2 provided with the `CompatLogger` object. These logs are not only used for informational representation in external web interfaces parsing the logs, but also to generate SLA reports and trends in Icinga 1.x Classic UI. Furthermore the -[Livestatus](#livestatus) feature uses these logs for answering queries to +[Livestatus](3-monitoring-basics.md#livestatus) feature uses these logs for answering queries to historical tables. The `CompatLogger` object can be enabled with @@ -2434,10 +2434,10 @@ by a number of projects including Icinga Web 1.x and 2. Details on the installation can be found in the [Getting Started](#configuring-ido) chapter. Details on the configuration can be found in the -[IdoMysqlConnection](#objecttype-idomysqlconnection) and +[IdoMysqlConnection](11-object-types.md#objecttype-idomysqlconnection) and [IdoPgsqlConnection](#objecttype-idoPgsqlconnection) object configuration documentation. -The DB IDO feature supports [High Availability](#high-availability-db-ido) in +The DB IDO feature supports [High Availability](4-monitoring-remote-systems.md#high-availability-db-ido) in the Icinga 2 cluster. The following example query checks the health of the current Icinga 2 instance @@ -2448,7 +2448,7 @@ the query returns an empty result. > **Tip** > -> Use [check plugins](#plugins) to monitor the backend. +> Use [check plugins](6-addons-plugins.md#plugins) to monitor the backend. Replace the `default` string with your instance name, if different. @@ -2479,7 +2479,7 @@ Example for PostgreSQL: (1 Zeile) -A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](#schema-db-ido). +A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](13-appendix.md#schema-db-ido). ## Livestatus @@ -2488,7 +2488,7 @@ The [MK Livestatus](http://mathias-kettner.de/checkmk_livestatus.html) project implements a query protocol that lets users query their Icinga instance for status information. It can also be used to send commands. -Details on the installation can be found in the [Getting Started](#setting-up-livestatus) +Details on the installation can be found in the [Getting Started](2-getting-started.md#setting-up-livestatus) chapter. ### Livestatus Sockets @@ -2498,7 +2498,7 @@ Other to the Icinga 1.x Addon, Icinga 2 supports two socket types * Unix socket (default) * TCP socket -Details on the configuration can be found in the [LivestatusListener](#objecttype-livestatuslistener) +Details on the configuration can be found in the [LivestatusListener](11-object-types.md#objecttype-livestatuslistener) object configuration. ### Livestatus GET Queries @@ -2531,7 +2531,7 @@ Example using the tcp socket listening on port `6558`: ### Livestatus COMMAND Queries -A list of available external commands and their parameters can be found [here](#external-commands-list-detail) +A list of available external commands and their parameters can be found [here](13-appendix.md#external-commands-list-detail) $ echo -e 'COMMAND ' | netcat 127.0.0.1 6558 @@ -2624,12 +2624,12 @@ Default separators. downtimes | services | status attributes timeperiods |   | name and is inside flag endpoints |   | config and status attributes - log | services, hosts, contacts, commands | parses [compatlog](#objecttype-compatlogger) and shows log attributes - statehist | hosts, services | parses [compatlog](#objecttype-compatlogger) and aggregates state change attributes + log | services, hosts, contacts, commands | parses [compatlog](11-object-types.md#objecttype-compatlogger) and shows log attributes + statehist | hosts, services | parses [compatlog](11-object-types.md#objecttype-compatlogger) and aggregates state change attributes The `commands` table is populated with `CheckCommand`, `EventCommand` and `NotificationCommand` objects. -A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](#schema-livestatus). +A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](13-appendix.md#schema-livestatus). ## Check Result Files diff --git a/doc/4-monitoring-remote-systems.md b/doc/4-monitoring-remote-systems.md index eccab124c..efee207de 100644 --- a/doc/4-monitoring-remote-systems.md +++ b/doc/4-monitoring-remote-systems.md @@ -1,17 +1,17 @@ # Monitoring Remote Systems -There are multiple ways you can monitor remote clients. Be it using [agent-less](#agent-less-checks) +There are multiple ways you can monitor remote clients. Be it using [agent-less](4-monitoring-remote-systems.md#agent-less-checks) or [agent-based](agent-based-checks-addons) using additional addons & tools. Icinga 2 uses its own unique and secure communitication protol amongst instances. Be it an High-Availability cluster setup, distributed load-balanced setup or just a single -agent [monitoring a remote client](#icinga2-remote-client-monitoring). +agent [monitoring a remote client](4-monitoring-remote-systems.md#icinga2-remote-client-monitoring). All communication is secured by TLS with certificates, and fully supports IPv4 and IPv6. If you are planning to use the native Icinga 2 cluster feature for distributed monitoring and high-availability, please continue reading in -[this chapter](#distributed-monitoring-high-availability). +[this chapter](4-monitoring-remote-systems.md#distributed-monitoring-high-availability). > **Tip** > @@ -22,24 +22,24 @@ monitoring and high-availability, please continue reading in ## Agent-less Checks If the remote service is available using a network protocol and port, -and a [check plugin](#setting-up-check-plugins) is available, you don't +and a [check plugin](2-getting-started.md#setting-up-check-plugins) is available, you don't necessarily need a local client installed. Rather choose a plugin and configure all parameters and thresholds. The [Icinga 2 Template Library](#itl) already ships various examples like -* [ping4](#plugin-check-command-ping4), [ping6](#plugin-check-command-ping6), -[fping4](#plugin-check-command-fping4), [fping6](#plugin-check-command-fping6), [hostalive](#plugin-check-command-hostalive) -* [tcp](#plugin-check-command-tcp), [udp](#plugin-check-command-udp), [ssl](#plugin-check-command-ssl) -* [http](#plugin-check-command-http), [ftp](#plugin-check-command-ftp) -* [smtp](#plugin-check-command-smtp), [ssmtp](#plugin-check-command-ssmtp), -[imap](#plugin-check-command-imap), [simap](#plugin-check-command-simap), -[pop](#plugin-check-command-pop), [spop](#plugin-check-command-spop) +* [ping4](12-icinga-template-library.md#plugin-check-command-ping4), [ping6](12-icinga-template-library.md#plugin-check-command-ping6), +[fping4](#plugin-check-command-fping4), [fping6](12-icinga-template-library.md#plugin-check-command-fping6), [hostalive](12-icinga-template-library.md#plugin-check-command-hostalive) +* [tcp](#plugin-check-command-tcp), [udp](12-icinga-template-library.md#plugin-check-command-udp), [ssl](12-icinga-template-library.md#plugin-check-command-ssl) +* [http](12-icinga-template-library.md#plugin-check-command-http), [ftp](12-icinga-template-library.md#plugin-check-command-ftp) +* [smtp](12-icinga-template-library.md#plugin-check-command-smtp), [ssmtp](12-icinga-template-library.md#plugin-check-command-ssmtp), +[imap](12-icinga-template-library.md#plugin-check-command-imap), [simap](12-icinga-template-library.md#plugin-check-command-simap), +[pop](12-icinga-template-library.md#plugin-check-command-pop), [spop](12-icinga-template-library.md#plugin-check-command-spop) * [ntp_time](#plugin-check-command-ntp_time) -* [ssh](#plugin-check-command-ssh) -* [dns](#plugin-check-command-dns), [dig](#plugin-check-command-dig), [dhcp](#plugin-check-command-dhcp) +* [ssh](12-icinga-template-library.md#plugin-check-command-ssh) +* [dns](#plugin-check-command-dns), [dig](12-icinga-template-library.md#plugin-check-command-dig), [dhcp](12-icinga-template-library.md#plugin-check-command-dhcp) There are numerous check plugins contributed by community members available -on the internet. If you found one for your requirements, [integrate them into Icinga 2](#command-plugin-integration). +on the internet. If you found one for your requirements, [integrate them into Icinga 2](3-monitoring-basics.md#command-plugin-integration). Start your search at @@ -47,7 +47,7 @@ Start your search at * [Icinga Wiki](https://wiki.icinga.org) An example is provided in the sample configuration in the getting started -section shipped with Icinga 2 ([hosts.conf](#hosts-conf), [services.conf](#services-conf)). +section shipped with Icinga 2 ([hosts.conf](2-getting-started.md#hosts-conf), [services.conf](2-getting-started.md#services-conf)). ## Monitoring Icinga 2 Remote Clients @@ -58,13 +58,13 @@ First, you should decide which role the remote client has: * a remote command execution client (similar to NRPE, NSClient++, etc) Later on, you will be asked again and told how to proceed with these -different [roles](#icinga2-remote-monitoring-client-roles). +different [roles](4-monitoring-remote-systems.md#icinga2-remote-monitoring-client-roles). > **Note** > > If you are planning to build an Icinga 2 distributed setup using the cluster feature, please skip > the following instructions and jump directly to the -> [cluster setup instructions](#distributed-monitoring-high-availability). +> [cluster setup instructions](4-monitoring-remote-systems.md#distributed-monitoring-high-availability). > **Note** > @@ -73,7 +73,7 @@ different [roles](#icinga2-remote-monitoring-client-roles). ## Master Setup for Remote Monitoring -If you are planning to use the [remote Icinga 2 clients](#icinga2-remote-monitoring-client) +If you are planning to use the [remote Icinga 2 clients](4-monitoring-remote-systems.md#icinga2-remote-monitoring-client) you'll first need to update your master setup. Your master setup requires the following @@ -82,7 +82,7 @@ Your master setup requires the following * Enabled API feature, and a local Endpoint and Zone object configuration * Firewall ACLs for the communication port (default 5665) -You can use the [CLI command](#cli-command-node) `node wizard` for setting up a new node +You can use the [CLI command](5-cli-commands.md#cli-command-node) `node wizard` for setting up a new node on the master. The command must be run as root, all Icinga 2 specific files will be updated to the icinga user the daemon is running as (certificate files for example). @@ -148,13 +148,13 @@ The setup wizard does not automatically restart Icinga 2. ## Client Setup for Remote Monitoring Icinga 2 can be installed on Linux/Unix and Windows. While -[Linux/Unix](#icinga2-remote-monitoring-client-linux) will be using the [CLI command](#cli-command-node) +[Linux/Unix](4-monitoring-remote-systems.md#icinga2-remote-monitoring-client-linux) will be using the [CLI command](5-cli-commands.md#cli-command-node) `node wizard` for a guided setup, you will need to use the graphical installer for Windows based client setup. Your client setup requires the following -* A ready configured and installed [master node](#icinga2-remote-monitoring-master) +* A ready configured and installed [master node](4-monitoring-remote-systems.md#icinga2-remote-monitoring-master) * SSL signed certificate for communication with the master (Use [CSR auto-signing](certifiates-csr-autosigning)). * Enabled API feature, and a local Endpoint and Zone object configuration * Firewall ACLs for the communication port (default 5665) @@ -168,8 +168,8 @@ Your client setup requires the following If your remote clients are capable of connecting to the central master, Icinga 2 supports CSR auto-signing. -First you'll need to define a secure ticket salt in the [constants.conf](#constants-conf). -The [setup wizard for the master setup](#icinga2-remote-monitoring-master) will create +First you'll need to define a secure ticket salt in the [constants.conf](2-getting-started.md#constants-conf). +The [setup wizard for the master setup](4-monitoring-remote-systems.md#icinga2-remote-monitoring-master) will create one for you already. # grep TicketSalt /etc/icinga2/constants.conf @@ -188,25 +188,25 @@ Example for a client notebook: > **Note** > > You can omit the `--salt` parameter using the `TicketSalt` constant from -> [constants.conf](#constants-conf) if already defined and Icinga 2 was +> [constants.conf](2-getting-started.md#constants-conf) if already defined and Icinga 2 was > reloaded after the master setup. #### Manual SSL Certificate Generation -This is described separately in the [cluster setup chapter](#manual-certificate-generation). +This is described separately in the [cluster setup chapter](4-monitoring-remote-systems.md#manual-certificate-generation). > **Note** > -> If you're using [CSR Auto-Signing](#csr-autosigning-requirements), skip this step. +> If you're using [CSR Auto-Signing](4-monitoring-remote-systems.md#csr-autosigning-requirements), skip this step. #### Linux Client Setup Wizard for Remote Monitoring Install Icinga 2 from your distribution's package repository as described in the -general [installation instructions](#setting-up-icinga2). +general [installation instructions](2-getting-started.md#setting-up-icinga2). -Please make sure that either [CSR Auto-Signing](#csr-autosigning-requirements) requirements -are fulfilled, or that you're using [manual SSL certificate generation](#manual-certificate-generation). +Please make sure that either [CSR Auto-Signing](4-monitoring-remote-systems.md#csr-autosigning-requirements) requirements +are fulfilled, or that you're using [manual SSL certificate generation](4-monitoring-remote-systems.md#manual-certificate-generation). > **Note** > @@ -222,7 +222,7 @@ You'll need the following configuration details: * The client's local zone name. Defaults to FQDN. * The master endpoint name. Look into your master setup `zones.conf` file for the proper name. * The master endpoint connection information. Your master's IP address and port (defaults to 5665) -* The [request ticket number](#csr-autosigning-requirements) generated on your master +* The [request ticket number](4-monitoring-remote-systems.md#csr-autosigning-requirements) generated on your master for CSR Auto-Signing * Bind host/port for the Api feature (optional) @@ -325,7 +325,7 @@ You'll need the following configuration details: * The client's local zone name. Defaults to FQDN. * The master endpoint name. Look into your master setup `zones.conf` file for the proper name. * The master endpoint connection information. Your master's IP address and port (defaults to 5665) -* The [request ticket number](#csr-autosigning-requirements) generated on your master +* The [request ticket number](4-monitoring-remote-systems.md#csr-autosigning-requirements) generated on your master for CSR Auto-Signing * Bind host/port for the Api feature (optional) @@ -348,8 +348,8 @@ This scenario allows you to configure the checkable objects (hosts, services) on your Icinga 2 master or satellite, and only send commands remotely. Requirements: -* Exact same [CheckCommand](#objecttype-checkcommand) (and -[EventCommand](#objecttype-eventcommand)) configuration objects +* Exact same [CheckCommand](11-object-types.md#objecttype-checkcommand) (and +[EventCommand](11-object-types.md#objecttype-eventcommand)) configuration objects on the master and the remote client(s). * Installed plugin scripts on the remote client (`PluginDir` constant can be locally modified) * `Zone` and `Endpoint` configuration for the client on the master @@ -357,9 +357,9 @@ on the master and the remote client(s). endpoint `CheckCommand` objects are already shipped with the Icinga 2 ITL -as [plugin check commands](#plugin-check-commands). If you are +as [plugin check commands](12-icinga-template-library.md#plugin-check-commands). If you are using your own configuration definitions for example in -[commands.conf](#commands-conf) make sure to copy/sync it +[commands.conf](2-getting-started.md#commands-conf) make sure to copy/sync it on your remote client. #### Client Configuration Remote Client for Command Execution @@ -395,8 +395,8 @@ in [zones.conf](#zones-conf) and define a trusted master zone as `parent`. } More details here: -* [configure endpoints](#configure-cluster-endpoints) -* [configure zones](#configure-cluster-zones) +* [configure endpoints](4-monitoring-remote-systems.md#configure-cluster-endpoints) +* [configure zones](4-monitoring-remote-systems.md#configure-cluster-zones) Configuration example for host and service objects running commands on the remote endpoint `remote-client1`: @@ -438,7 +438,7 @@ schedule client updates in your management tool (e.g. Puppet). > **Tip** > -> [Event commands](#event-commands) are executed on the +> [Event commands](3-monitoring-basics.md#event-commands) are executed on the > remote command endpoint as well. You do not need > an additional transport layer such as SSH or similar. @@ -447,7 +447,7 @@ schedule client updates in your management tool (e.g. Puppet). > clients. There are no local configured objects available. > > If you require this, please install a full-featured -> [local client](#icinga2-remote-monitoring-client-local-config). +> [local client](4-monitoring-remote-systems.md#icinga2-remote-monitoring-client-local-config). ### Remote Client with Local Configuration @@ -519,7 +519,7 @@ using the following CLI command: > **Note** > -> Better use [blacklists and/or whitelists](#icinga2-remote-monitoring-master-discovery-blacklist-whitelist) +> Better use [blacklists and/or whitelists](4-monitoring-remote-systems.md#icinga2-remote-monitoring-master-discovery-blacklist-whitelist) > to control which clients and hosts/services are integrated into your master configuration repository. ### Generate Icinga 2 Configuration for Client Services on the Master @@ -601,15 +601,15 @@ You can `list` and `remove` existing blacklists: ### Manually add Client Endpoint and Zone Objects on the Master -Define a [Zone](#objecttype-zone) with a new [Endpoint](#objecttype-endpoint) similar to the cluster setup. +Define a [Zone](11-object-types.md#objecttype-zone) with a new [Endpoint](11-object-types.md#objecttype-endpoint) similar to the cluster setup. -* [configure the node name](#configure-nodename) -* [configure the ApiListener object](#configure-apilistener-object) -* [configure cluster endpoints](#configure-cluster-endpoints) -* [configure cluster zones](#configure-cluster-zones) +* [configure the node name](4-monitoring-remote-systems.md#configure-nodename) +* [configure the ApiListener object](4-monitoring-remote-systems.md#configure-apilistener-object) +* [configure cluster endpoints](4-monitoring-remote-systems.md#configure-cluster-endpoints) +* [configure cluster zones](4-monitoring-remote-systems.md#configure-cluster-zones) on a per remote client basis. If you prefer to synchronize the configuration to remote -clients, you can also use the cluster provided [configuration sync](#cluster-zone-config-sync) +clients, you can also use the cluster provided [configuration sync](4-monitoring-remote-systems.md#cluster-zone-config-sync) in `zones.d`. @@ -622,11 +622,11 @@ become handy. ### SNMP The SNMP daemon runs on the remote system and answers SNMP queries by plugin -binaries. The [Monitoring Plugins package](#setting-up-check-plugins) ships +binaries. The [Monitoring Plugins package](2-getting-started.md#setting-up-check-plugins) ships the `check_snmp` plugin binary, but there are plenty of [existing plugins](#integrate-additional-plugins) for specific use cases already around, for example monitoring Cisco routers. -The following example uses the [SNMP ITL](#plugin-check-command-snmp) `CheckCommand` and just +The following example uses the [SNMP ITL](12-icinga-template-library.md#plugin-check-command-snmp) `CheckCommand` and just overrides the `snmp_oid` custom attribute. A service is created for all hosts which have the `snmp-community` custom attribute. @@ -639,13 +639,13 @@ have the `snmp-community` custom attribute. assign where host.vars.snmp_community != "" } -Additional SNMP plugins are available using the [Manubulon SNMP Plugins](#snmp-manubulon-plugin-check-commands). +Additional SNMP plugins are available using the [Manubulon SNMP Plugins](12-icinga-template-library.md#snmp-manubulon-plugin-check-commands). ### SSH Calling a plugin using the SSH protocol to execute a plugin on the remote server fetching its return code and output. The `by_ssh` command object is part of the built-in templates and -requires the `check_by_ssh` check plugin which is available in the [Monitoring Plugins package](#setting-up-check-plugins). +requires the `check_by_ssh` check plugin which is available in the [Monitoring Plugins package](2-getting-started.md#setting-up-check-plugins). object CheckCommand "by_ssh_swap" { import "by_ssh" @@ -677,14 +677,14 @@ remote client. > The NRPE protocol is considered insecure and has multiple flaws in its > design. Upstream is not willing to fix these issues. > -> In order to stay safe, please use the native [Icinga 2 client](#icinga2-remote-monitoring-master) +> In order to stay safe, please use the native [Icinga 2 client](4-monitoring-remote-systems.md#icinga2-remote-monitoring-master) > instead. The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe` can be embedded into the Icinga 2 `CheckCommand` configuration syntax. You can use the `check_nrpe` plugin from the NRPE project to query the NRPE daemon. -Icinga 2 provides the [nrpe check command](#plugin-check-command-nrpe) for this: +Icinga 2 provides the [nrpe check command](12-icinga-template-library.md#plugin-check-command-nrpe) for this: Example: @@ -743,7 +743,7 @@ executed by the NRPE daemon looks similar to that: /usr/local/icinga/libexec/check_disk -w 20% -c 10% -p / -You can pass arguments in a similar manner to [NSClient++](#agent-based-checks-nsclient) +You can pass arguments in a similar manner to [NSClient++](4-monitoring-remote-systems.md#agent-based-checks-nsclient) when using its NRPE supported check method. ### NSClient++ @@ -754,7 +754,7 @@ but using `NSClient++` will allow you to run local scripts similar to check plug the required output and performance counters. You can use the `check_nt` plugin from the Monitoring Plugins project to query NSClient++. -Icinga 2 provides the [nscp check command](#plugin-check-command-nscp) for this: +Icinga 2 provides the [nscp check command](12-icinga-template-library.md#plugin-check-command-nscp) for this: Example: @@ -790,7 +790,7 @@ SNMP Traps can be received and filtered by using [SNMPTT](http://snmptt.sourcefo and specific trap handlers passing the check results to Icinga 2. Following the SNMPTT [Format](http://snmptt.sourceforge.net/docs/snmptt.shtml#SNMPTT.CONF-FORMAT) -documentation and the Icinga external command syntax found [here](#external-commands-list-detail) +documentation and the Icinga external command syntax found [here](13-appendix.md#external-commands-list-detail) we can create generic services that can accommodate any number of hosts for a given scenario. #### Simple SNMP Traps @@ -974,9 +974,9 @@ passive update with the state and text from the second and third varbind: Building distributed environments with high availability included is fairly easy with Icinga 2. The cluster feature is built-in and allows you to build many scenarios based on your requirements: -* [High Availability](#cluster-scenarios-high-availability). All instances in the `Zone` elect one active master and run as Active/Active cluster. -* [Distributed Zones](#cluster-scenarios-distributed-zones). A master zone and one or more satellites in their zones. -* [Load Distribution](#cluster-scenarios-load-distribution). A configuration master and multiple checker satellites. +* [High Availability](4-monitoring-remote-systems.md#cluster-scenarios-high-availability). All instances in the `Zone` elect one active master and run as Active/Active cluster. +* [Distributed Zones](4-monitoring-remote-systems.md#cluster-scenarios-distributed-zones). A master zone and one or more satellites in their zones. +* [Load Distribution](4-monitoring-remote-systems.md#cluster-scenarios-load-distribution). A configuration master and multiple checker satellites. You can combine these scenarios into a global setup fitting your requirements. @@ -1000,18 +1000,18 @@ Before you start deploying, keep the following things in mind: * cluster zones can be built in a Top-Down-design where the child trusts the parent * communication between zones happens bi-directional which means that a DMZ-located node can still reach the master node, or vice versa * Update firewall rules and ACLs -* Decide whether to use the built-in [configuration syncronization](#cluster-zone-config-sync) or use an external tool (Puppet, Ansible, Chef, Salt, etc) to manage the configuration deployment +* Decide whether to use the built-in [configuration syncronization](4-monitoring-remote-systems.md#cluster-zone-config-sync) or use an external tool (Puppet, Ansible, Chef, Salt, etc) to manage the configuration deployment > **Tip** > > If you're looking for troubleshooting cluster problems, check the general -> [troubleshooting](#troubleshooting-cluster) section. +> [troubleshooting](7-troubleshooting.md#troubleshooting-cluster) section. ### Manual SSL Certificate Generation -Icinga 2 ships [CLI commands](#cli-command-pki) assisting with CA and node certificate creation +Icinga 2 ships [CLI commands](5-cli-commands.md#cli-command-pki) assisting with CA and node certificate creation for your Icinga 2 distributed setup. > **Note** @@ -1054,8 +1054,8 @@ the host's FQDN): #### Cluster Naming Convention -The SSL certificate common name (CN) will be used by the [ApiListener](#objecttype-apilistener) -object to determine the local authority. This name must match the local [Endpoint](#objecttype-endpoint) +The SSL certificate common name (CN) will be used by the [ApiListener](11-object-types.md#objecttype-apilistener) +object to determine the local authority. This name must match the local [Endpoint](11-object-types.md#objecttype-endpoint) object name. Example: @@ -1069,8 +1069,8 @@ Example: host = "icinga2a.icinga.org" } -The [Endpoint](#objecttype-endpoint) name is further referenced as `endpoints` attribute on the -[Zone](#objecttype-zone) object. +The [Endpoint](11-object-types.md#objecttype-endpoint) name is further referenced as `endpoints` attribute on the +[Zone](11-object-types.md#objecttype-zone) object. object Endpoint "icinga2b" { host = "icinga2b.icinga.org" @@ -1080,7 +1080,7 @@ The [Endpoint](#objecttype-endpoint) name is further referenced as `endpoints` a endpoints = [ "icinga2a", "icinga2b" ] } -Specifying the local node name using the [NodeName](#configure-nodename) variable requires +Specifying the local node name using the [NodeName](4-monitoring-remote-systems.md#configure-nodename) variable requires the same name as used for the endpoint name and common name above. If not set, the FQDN is used. const NodeName = "icinga2a" @@ -1091,19 +1091,19 @@ the same name as used for the endpoint name and common name above. If not set, t The following section describe which configuration must be updated/created in order to get your cluster running with basic functionality. -* [configure the node name](#configure-nodename) -* [configure the ApiListener object](#configure-apilistener-object) -* [configure cluster endpoints](#configure-cluster-endpoints) -* [configure cluster zones](#configure-cluster-zones) +* [configure the node name](4-monitoring-remote-systems.md#configure-nodename) +* [configure the ApiListener object](4-monitoring-remote-systems.md#configure-apilistener-object) +* [configure cluster endpoints](4-monitoring-remote-systems.md#configure-cluster-endpoints) +* [configure cluster zones](4-monitoring-remote-systems.md#configure-cluster-zones) Once you're finished with the basic setup the following section will -describe how to use [zone configuration synchronisation](#cluster-zone-config-sync) -and configure [cluster scenarios](#cluster-scenarios). +describe how to use [zone configuration synchronisation](4-monitoring-remote-systems.md#cluster-zone-config-sync) +and configure [cluster scenarios](4-monitoring-remote-systems.md#cluster-scenarios). #### Configure the Icinga Node Name Instead of using the default FQDN as node name you can optionally set -that value using the [NodeName](#constants) constant. +that value using the [NodeName](9-language-reference.md#constants) constant. > ** Note ** > @@ -1111,9 +1111,9 @@ that value using the [NodeName](#constants) constant. > in `/etc/icinga2/constants.conf`. This setting must be unique for each node, and must also match -the name of the local [Endpoint](#objecttype-endpoint) object and the +the name of the local [Endpoint](11-object-types.md#objecttype-endpoint) object and the SSL certificate common name as described in the -[cluster naming convention](#cluster-naming-convention). +[cluster naming convention](4-monitoring-remote-systems.md#cluster-naming-convention). vim /etc/icinga2/constants.conf @@ -1123,14 +1123,14 @@ SSL certificate common name as described in the const NodeName = "icinga2a" -Read further about additional [naming conventions](#cluster-naming-convention). +Read further about additional [naming conventions](4-monitoring-remote-systems.md#cluster-naming-convention). Not specifying the node name will make Icinga 2 using the FQDN. Make sure that all configured endpoint names and common names are in sync. #### Configure the ApiListener Object -The [ApiListener](#objecttype-apilistener) object needs to be configured on +The [ApiListener](11-object-types.md#objecttype-apilistener) object needs to be configured on every node in the cluster with the following settings: A sample config looks like: @@ -1178,9 +1178,9 @@ If this endpoint object is reachable on a different port, you must configure the `Zone` objects specify the endpoints located in a zone. That way your distributed setup can be seen as zones connected together instead of multiple instances in that specific zone. -Zones can be used for [high availability](#cluster-scenarios-high-availability), -[distributed setups](#cluster-scenarios-distributed-zones) and -[load distribution](#cluster-scenarios-load-distribution). +Zones can be used for [high availability](4-monitoring-remote-systems.md#cluster-scenarios-high-availability), +[distributed setups](4-monitoring-remote-systems.md#cluster-scenarios-distributed-zones) and +[load distribution](4-monitoring-remote-systems.md#cluster-scenarios-load-distribution). Each Icinga 2 `Endpoint` must be put into its respective `Zone`. In this example, you will define the zone `config-ha-master` where the `icinga2a` and `icinga2b` endpoints @@ -1215,21 +1215,21 @@ on the configuration master. Your child zones and endpoint members **must not** have their config copied to `zones.d`. The built-in configuration synchronisation takes care of that if your nodes accept configuration from the parent zone. You can define that in the -[ApiListener](#configure-apilistener-object) object by configuring the `accept_config` +[ApiListener](4-monitoring-remote-systems.md#configure-apilistener-object) object by configuring the `accept_config` attribute accordingly. You should remove the sample config included in `conf.d` by commenting the `recursive_include` -statement in [icinga2.conf](#icinga2-conf): +statement in [icinga2.conf](2-getting-started.md#icinga2-conf): //include_recursive "conf.d" Better use a dedicated directory name like `cluster` or similar, and include that one if your nodes require local configuration not being synced to other nodes. That's -useful for local [health checks](#cluster-health-check) for example. +useful for local [health checks](4-monitoring-remote-systems.md#cluster-health-check) for example. > **Note** > -> In a [high availability](#cluster-scenarios-high-availability) +> In a [high availability](4-monitoring-remote-systems.md#cluster-scenarios-high-availability) > setup only one assigned node can act as configuration master. All other zone > member nodes **must not** have the `/etc/icinga2/zones.d` directory populated. @@ -1238,7 +1238,7 @@ to their respective target zone instances. Each configured zone must exist with the same directory name. The parent zone syncs the configuration to the child zones, if allowed using the `accept_config` -attribute of the [ApiListener](#configure-apilistener-object) object. +attribute of the [ApiListener](4-monitoring-remote-systems.md#configure-apilistener-object) object. Config on node `icinga2a`: @@ -1277,9 +1277,9 @@ process. > **Note** > -> `zones.d` must not be included in [icinga2.conf](#icinga2-conf). Icinga 2 automatically +> `zones.d` must not be included in [icinga2.conf](2-getting-started.md#icinga2-conf). Icinga 2 automatically > determines the required include directory. This can be overridden using the -> [global constant](#constants) `ZonesDir`. +> [global constant](9-language-reference.md#constants) `ZonesDir`. #### Global Configuration Zone for Templates @@ -1326,7 +1326,7 @@ If you don't require any global configuration, skip this setting. #### Zone Configuration Synchronisation Permissions -Each [ApiListener](#objecttype-apilistener) object must have the `accept_config` attribute +Each [ApiListener](11-object-types.md#objecttype-apilistener) object must have the `accept_config` attribute set to `true` to receive configuration from the parent `Zone` members. Default value is `false`. object ApiListener "api" { @@ -1341,7 +1341,7 @@ master instances anymore. > ** Tip ** > -> Look into the [troubleshooting guides](#troubleshooting-cluster-config-sync) for debugging +> Look into the [troubleshooting guides](7-troubleshooting.md#troubleshooting-cluster-config-sync) for debugging > problems with the configuration synchronisation. @@ -1396,7 +1396,7 @@ additional security itself: * Child zones only receive event updates (check results, commands, etc) for their configured updates. * Zones cannot influence/interfere other zones. Each checked object is assigned to only one zone. * All nodes in a zone trust each other. -* [Configuration sync](#zone-config-sync-permissions) is disabled by default. +* [Configuration sync](4-monitoring-remote-systems.md#zone-config-sync-permissions) is disabled by default. #### Features in Cluster Zones @@ -1407,11 +1407,11 @@ re-schedule a check or acknowledge a problem on the master, and it gets replicat actual slave checker node. DB IDO on the left, graphite on the right side - works (if you disable -[DB IDO HA](#high-availability-db-ido)). +[DB IDO HA](4-monitoring-remote-systems.md#high-availability-db-ido)). Icinga Web 2 on the left, checker and notifications on the right side - works too. Everything on the left and on the right side - make sure to deal with -[load-balanced notifications and checks](#high-availability-features) in a -[HA zone](#cluster-scenarios-high-availability). +[load-balanced notifications and checks](4-monitoring-remote-systems.md#high-availability-features) in a +[HA zone](4-monitoring-remote-systems.md#cluster-scenarios-high-availability). configure-cluster-zones #### Distributed Zones @@ -1426,7 +1426,7 @@ graphing, etc. in their own specified zone. Imagine the following example with a master node in Nuremberg, and two remote DMZ based instances in Berlin and Vienna. Additonally you'll specify -[global templates](#zone-global-config-templates) available in all zones. +[global templates](4-monitoring-remote-systems.md#zone-global-config-templates) available in all zones. The configuration tree on the master instance `nuremberg` could look like this: @@ -1490,7 +1490,7 @@ check results from the satellite nodes in the zones `berlin` and `vienna`. > The child zones `berlin` and `vienna` will get their configuration synchronised > from the configuration master 'nuremberg'. The endpoints in the child > zones **must not** have their `zones.d` directory populated if this endpoint -> [accepts synced configuration](#zone-config-sync-permissions). +> [accepts synced configuration](4-monitoring-remote-systems.md#zone-config-sync-permissions). #### Load Distribution @@ -1549,15 +1549,15 @@ Zones: > The child zones `checker` will get its configuration synchronised > from the configuration master 'master'. The endpoints in the child > zone **must not** have their `zones.d` directory populated if this endpoint -> [accepts synced configuration](#zone-config-sync-permissions). +> [accepts synced configuration](4-monitoring-remote-systems.md#zone-config-sync-permissions). #### Cluster High Availability High availability with Icinga 2 is possible by putting multiple nodes into -a dedicated [zone](#configure-cluster-zones). All nodes will elect one +a dedicated [zone](4-monitoring-remote-systems.md#configure-cluster-zones). All nodes will elect one active master, and retry an election once the current active master is down. -Selected features provide advanced [HA functionality](#high-availability-features). +Selected features provide advanced [HA functionality](4-monitoring-remote-systems.md#high-availability-features). Checks and notifications are load-balanced between nodes in the high availability zone. @@ -1569,15 +1569,15 @@ commands, etc. endpoints = [ "icinga2a", "icinga2b", "icinga2c" ] } -Two or more nodes in a high availability setup require an [initial cluster sync](#initial-cluster-sync). +Two or more nodes in a high availability setup require an [initial cluster sync](4-monitoring-remote-systems.md#initial-cluster-sync). > **Note** > > Keep in mind that **only one node acts as configuration master** having the > configuration files in the `zones.d` directory. All other nodes **must not** > have that directory populated. Instead they are required to -> [accept synced configuration](#zone-config-sync-permissions). -> Details in the [Configuration Sync Chapter](#cluster-zone-config-sync). +> [accept synced configuration](4-monitoring-remote-systems.md#zone-config-sync-permissions). +> Details in the [Configuration Sync Chapter](4-monitoring-remote-systems.md#cluster-zone-config-sync). #### Multiple Hierachies @@ -1611,9 +1611,9 @@ amongst them. By default the following features provide advanced HA functionality: -* [Checks](#high-availability-checks) (load balanced, automated failover) -* [Notifications](#high-availability-notifications) (load balanced, automated failover) -* [DB IDO](#high-availability-db-ido) (Run-Once, automated failover) +* [Checks](4-monitoring-remote-systems.md#high-availability-checks) (load balanced, automated failover) +* [Notifications](4-monitoring-remote-systems.md#high-availability-notifications) (load balanced, automated failover) +* [DB IDO](4-monitoring-remote-systems.md#high-availability-db-ido) (Run-Once, automated failover) #### High Availability with Checks @@ -1634,7 +1634,7 @@ Notifications are load balanced amongst all nodes in a zone. By default this fun is enabled. If your nodes should notify independent from any other nodes (this will cause duplicated notifications if not properly handled!), you can set `enable_ha = false` -in the [NotificationComponent](#objecttype-notificationcomponent) feature. +in the [NotificationComponent](11-object-types.md#objecttype-notificationcomponent) feature. #### High Availability with DB IDO @@ -1652,8 +1652,8 @@ nodes disable the active IDO database connection at runtime. > **Note** > > The DB IDO HA feature can be disabled by setting the `enable_ha` attribute to `false` -> for the [IdoMysqlConnection](#objecttype-idomysqlconnection) or -> [IdoPgsqlConnection](#objecttype-idopgsqlconnection) object on all nodes in the +> for the [IdoMysqlConnection](11-object-types.md#objecttype-idomysqlconnection) or +> [IdoPgsqlConnection](11-object-types.md#objecttype-idopgsqlconnection) object on all nodes in the > same zone. > > All endpoints will enable the DB IDO feature then, connect to the configured @@ -1683,11 +1683,11 @@ These steps are required for integrating a new cluster endpoint: * generate a new [SSL client certificate](#certificate-authority-certificates) * identify its location in the zones -* update the `zones.conf` file on each involved node ([endpoint](#configure-cluster-endpoints), [zones](#configure-cluster-zones)) +* update the `zones.conf` file on each involved node ([endpoint](4-monitoring-remote-systems.md#configure-cluster-endpoints), [zones](4-monitoring-remote-systems.md#configure-cluster-zones)) * a new slave zone node requires updates for the master and slave zones - * verify if this endpoints requires [configuration synchronisation](#cluster-zone-config-sync) enabled -* if the node requires the existing zone history: [initial cluster sync](#initial-cluster-sync) -* add a [cluster health check](#cluster-health-check) + * verify if this endpoints requires [configuration synchronisation](4-monitoring-remote-systems.md#cluster-zone-config-sync) enabled +* if the node requires the existing zone history: [initial cluster sync](4-monitoring-remote-systems.md#initial-cluster-sync) +* add a [cluster health check](4-monitoring-remote-systems.md#cluster-health-check) #### Initial Cluster Sync @@ -1706,7 +1706,7 @@ Special scenarios might require multiple cluster nodes running on a single host. By default Icinga 2 and its features will place their runtime data below the prefix `LocalStateDir`. By default packages will set that path to `/var`. You can either set that variable as constant configuration -definition in [icinga2.conf](#icinga2-conf) or pass it as runtime variable to +definition in [icinga2.conf](2-getting-started.md#icinga2-conf) or pass it as runtime variable to the Icinga 2 daemon. # icinga2 -c /etc/icinga2/node1/icinga2.conf -DLocalStateDir=/opt/node1/var diff --git a/doc/5-cli-commands.md b/doc/5-cli-commands.md new file mode 100644 index 000000000..2aa03ebae --- /dev/null +++ b/doc/5-cli-commands.md @@ -0,0 +1,537 @@ +## Icinga 2 CLI Commands + +Icinga 2 ships its own integrated CLI commands supporting bash-autocompletion. + +These CLI commands will allow you to use certain functionality +provided by and around the Icinga 2 daemon. + +Each CLI command provides its own help and usage information, so please +make sure to always run them with the `--help` parameter. + +Run `icinga2` without any arguments to get a list of all available global +options. + + # icinga2 + + icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) + + Usage: + icinga2 [] + + Supported commands: + * daemon (starts Icinga 2) + * feature disable (disables specified feature) + * feature enable (enables specified feature) + * feature list (lists all enabled features) + * node add (add node) + * node blacklist add (adds a new blacklist filter) + * node blacklist list (lists all blacklist filters) + * node blacklist remove (removes a blacklist filter) + * node list (lists all nodes) + * node remove (removes node) + * node set (set node attributes) + * node setup (set up node) + * node update-config (update node config) + * node whitelist add (adds a new whitelist filter) + * node whitelist list (lists all whitelist filters) + * node whitelist remove (removes a whitelist filter) + * node wizard (wizard for node setup) + * object list (lists all objects) + * pki new-ca (sets up a new CA) + * pki new-cert (creates a new CSR) + * pki request (requests a certificate) + * pki save-cert (saves another Icinga 2 instance's certificate) + * pki sign-csr (signs a CSR) + * pki ticket (generates a ticket) + * repository clear-changes (clear uncommitted repository changes) + * repository commit (commit repository changes) + * repository endpoint add (adds a new Endpoint object) + * repository endpoint list (lists all Endpoint objects) + * repository endpoint remove (removes a Endpoint object) + * repository host add (adds a new Host object) + * repository host list (lists all Host objects) + * repository host remove (removes a Host object) + * repository service add (adds a new Service object) + * repository service list (lists all Service objects) + * repository service remove (removes a Service object) + * repository zone add (adds a new Zone object) + * repository zone list (lists all Zone objects) + * repository zone remove (removes a Zone object) + * variable get (gets a variable) + * variable list (lists all variables) + + Global options: + -h [ --help ] show this help message + -V [ --version ] show version information + --color use VT100 color codes even when stdout is not a + terminal + -D [ --define ] arg define a constant + -l [ --library ] arg load a library + -I [ --include ] arg add include search directory + -x [ --log-level ] arg specify the log level for the console log + + Command options: + + Report bugs at + Icinga home page: + + +### Icinga 2 CLI Bash Autocompletion + +Bash Auto-Completion (pressing ``) is provided only for the corresponding context. + +While `--config` will suggest and auto-complete files and directories on disk, +`feature enable` will only suggest disabled features. `repository` will know +about object specific attributes, and so on. Try it yourself. + +RPM and Debian packages install the bash completion files into +`/etc/bash_completion.d/icinga2`. + +You will need to install the `bash-completion` package if not already installed. + +RHEL/CentOS/Fedora: + + # yum install bash-completion + +SUSE: + + # zypper install bash-completion + +Debian/Ubuntu: + + # apt-get install bash-completion + +### Icinga 2 CLI Global Options + +#### Libraries + +Instead of loading libraries using the [`library` config directive](9-language-reference.md#library) +you can also use the `--library` command-line option. + +#### Constants + +[Global constants](9-language-reference.md#constants) can be set using the `--define` command-line option. + +#### Config Include Path + +When including files you can specify that the include search path should be +checked. You can do this by putting your configuration file name in angle +brackets like this: + + include + +This would cause Icinga 2 to search its include path for the configuration file +`test.conf`. By default the installation path for the Icinga Template Library +is the only search directory. + +Using the `--include` command-line option additional search directories can be +added. + + + +### Cli command: Daemon + +The CLI command `daemon` provides the functionality to start/stop Icinga 2. +Furthermore it provides the [configuration validation](5-cli-commands.md#config-validation). + + # icinga2 daemon --help + icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) + + Usage: + icinga2 daemon [] + + Starts Icinga 2. + + Global options: + -h [ --help ] show this help message + -V [ --version ] show version information + --color use VT100 color codes even when stdout is not a + terminal + -D [ --define ] arg define a constant + -l [ --library ] arg load a library + -I [ --include ] arg add include search directory + -x [ --log-level ] arg specify the log level for the console log + + Command options: + -c [ --config ] arg parse a configuration file + -z [ --no-config ] start without a configuration file + -C [ --validate ] exit after validating the configuration + -e [ --errorlog ] arg log fatal errors to the specified log file (only works + in combination with --daemonize) + -d [ --daemonize ] detach from the controlling terminal + + Report bugs at + Icinga home page: + +#### Config Files + +Using the `--config` option you can specify one or more configuration files. +Config files are processed in the order they're specified on the command-line. + +When no configuration file is specified and the `--no-config` is not used +Icinga 2 automatically falls back to using the configuration file +`SysconfDir + "/icinga2/icinga2.conf"` (where SysconfDir is usually `/etc`). + +#### Config Validation + +The `--validate` option can be used to check if your configuration files +contain errors. If any errors are found the exit status is 1, otherwise 0 +is returned. More details in the [configuration validation](5-cli-commands.md#config-validation) chapter. + + +### Cli command: Feature + +The CLI commands for `enable` and `disable` feature support bash auto-completion +and will only suggest features for the corresponding context. Like disabling a +feature will only bring up all enabled features. + + # icinga2 feature disable + checker --color --define --help --include --library --log-level mainlog notification --version + + # icinga2 feature enable + api command debuglog graphite icingastatus ido-pgsql --library --log-level statusdata --version + --color compatlog --define --help ido-mysql --include livestatus perfdata syslog + +### Cli command: Node + +Provides the functionality to install and manage master and client +nodes in a [remote monitoring ](4-monitoring-remote-systems.md#icinga2-remote-client-monitoring) or +[distributed cluster](4-monitoring-remote-systems.md#distributed-monitoring-high-availability) scenario. + + + # icinga2 node --help + icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) + + Usage: + icinga2 [] + + Supported commands: + * node add (add node) + * node blacklist add (adds a new blacklist filter) + * node blacklist list (lists all blacklist filters) + * node blacklist remove (removes a blacklist filter) + * node list (lists all nodes) + * node remove (removes node) + * node set (set node attributes) + * node setup (set up node) + * node update-config (update node config) + * node whitelist add (adds a new whitelist filter) + * node whitelist list (lists all whitelist filters) + * node whitelist remove (removes a whitelist filter) + * node wizard (wizard for node setup) + + Global options: + -h [ --help ] show this help message + -V [ --version ] show version information + --color use VT100 color codes even when stdout is not a + terminal + -D [ --define ] arg define a constant + -l [ --library ] arg load a library + -I [ --include ] arg add include search directory + -x [ --log-level ] arg specify the log level for the console log + + Command options: + + Report bugs at + Icinga home page: + + +### Cli command: Object + +The `object` CLI command can be used to list all configuration objects and their +attributes. The command also shows where each of the attributes was modified. +That way you can also identify which objects have been created from your [apply rules](9-language-reference.md#apply). + +More information can be found in the [troubleshooting](7-troubleshooting.md#list-configuration-objects) section. + + # icinga2 object --help + icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) + + Usage: + icinga2 [] + + Supported commands: + * object list (lists all objects) + + Global options: + -h [ --help ] show this help message + -V [ --version ] show version information + --color use VT100 color codes even when stdout is not a + terminal + -D [ --define ] arg define a constant + -l [ --library ] arg load a library + -I [ --include ] arg add include search directory + -x [ --log-level ] arg specify the log level for the console log + + Command options: + + Report bugs at + Icinga home page: + + + +### Cli command: Pki + +Provides the CLI commands to + +* generate a new local CA +* generate a new CSR or self-signed certificate +* sign a CSR and return a certificate +* save a master certificate manually +* request a signed certificate from the master +* generate a new ticket for the client setup + +This functionality is used by the [node setup/wizard](5-cli-commands.md#cli-command-pki) CLI commands too. + + # icinga2 pki --help + icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) + + Usage: + icinga2 [] + + Supported commands: + * pki new-ca (sets up a new CA) + * pki new-cert (creates a new CSR) + * pki request (requests a certificate) + * pki save-cert (saves another Icinga 2 instance's certificate) + * pki sign-csr (signs a CSR) + * pki ticket (generates a ticket) + + Global options: + -h [ --help ] show this help message + -V [ --version ] show version information + --color use VT100 color codes even when stdout is not a + terminal + -D [ --define ] arg define a constant + -l [ --library ] arg load a library + -I [ --include ] arg add include search directory + -x [ --log-level ] arg specify the log level for the console log + + Command options: + + Report bugs at + Icinga home page: + + +### Cli command: Repository + +Provides the functionality to manage the Icinga 2 configuration repository in +`/etc/icinga2/repository.d`. All changes are logged and must be committed or +cleared after review. + + +> **Note** +> +> The CLI command `repository` only supports basic configuration manipulation (add, remove) +> and a limited set of objects required for the [remote client] integration. Future +> versions will support more options (set, etc.). +> +> Please check the Icinga 2 development roadmap for updates. + + + # icinga2 repository --help + icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) + + Usage: + icinga2 [] + + Supported commands: + * repository clear-changes (clear uncommitted repository changes) + * repository commit (commit repository changes) + * repository endpoint add (adds a new Endpoint object) + * repository endpoint list (lists all Endpoint objects) + * repository endpoint remove (removes a Endpoint object) + * repository host add (adds a new Host object) + * repository host list (lists all Host objects) + * repository host remove (removes a Host object) + * repository service add (adds a new Service object) + * repository service list (lists all Service objects) + * repository service remove (removes a Service object) + * repository zone add (adds a new Zone object) + * repository zone list (lists all Zone objects) + * repository zone remove (removes a Zone object) + + Global options: + -h [ --help ] show this help message + -V [ --version ] show version information + --color use VT100 color codes even when stdout is not a + terminal + -D [ --define ] arg define a constant + -l [ --library ] arg load a library + -I [ --include ] arg add include search directory + -x [ --log-level ] arg specify the log level for the console log + + Command options: + + Report bugs at + Icinga home page: + + + +### Cli command: Variable + +Lists all configured variables (constants) in a similar fasion like [object list](5-cli-commands.md#cli-command-object). + + # icinga2 variable --help + icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275) + + Usage: + icinga2 [] + + Supported commands: + * variable get (gets a variable) + * variable list (lists all variables) + + Global options: + -h [ --help ] show this help message + -V [ --version ] show version information + --color use VT100 color codes even when stdout is not a + terminal + -D [ --define ] arg define a constant + -l [ --library ] arg load a library + -I [ --include ] arg add include search directory + -x [ --log-level ] arg specify the log level for the console log + + Command options: + + Report bugs at + Icinga home page: + + + + + +## Enabling/Disabling Features + +Icinga 2 provides configuration files for some commonly used features. These +are installed in the `/etc/icinga2/features-available` directory and can be +enabled and disabled using the `icinga2 feature enable` and `icinga2 feature disable` +[CLI commands](5-cli-commands.md#cli-command-feature), respectively. + +The `icinga2 feature enable` CLI command creates symlinks in the +`/etc/icinga2/features-enabled` directory which is included by default +in the example configuration file. + +You can view a list of enabled and disabled features: + + # icinga2 feature list + Disabled features: api command compatlog debuglog graphite icingastatus ido-mysql ido-pgsql livestatus notification perfdata statusdata syslog + Enabled features: checker mainlog notification + +Using the `icinga2 feature enable` command you can enable features: + + # icinga2 feature enable graphite + Enabling feature graphite. Make sure to restart Icinga 2 for these changes to take effect. + + +You can disable features using the `icinga2 feature disable` command: + + # icinga2 feature disable ido-mysql livestatus + Disabling feature ido-mysql. Make sure to restart Icinga 2 for these changes to take effect. + Disabling feature livestatus. Make sure to restart Icinga 2 for these changes to take effect. + + +The `icinga2 feature enable` and `icinga2 feature disable` commands do not +restart Icinga 2. You will need to restart Icinga 2 using the init script +after enabling or disabling features. + + + +## Configuration Validation + +Once you've edited the configuration files make sure to tell Icinga 2 to validate +the configuration changes. Icinga 2 will log any configuration error including +a hint on the file, the line number and the affected configuration line itself. + +The following example creates an apply rule without any `assign` condition. + + apply Service "5872-ping4" { + import "generic-service" + check_command = "ping4" + //assign where match("5872-*", host.name) + } + +Validate the configuration with the init script option `checkconfig`: + + # /etc/init.d/icinga2 checkconfig + +> **Note** +> +> Using [systemd](2-getting-started.md#systemd-service) you need to manually validate the configuration using +> the CLI command below. + +Or manually passing the `-C` argument: + + # /usr/sbin/icinga2 daemon -c /etc/icinga2/icinga2.conf -C + + [2014-05-22 17:07:25 +0200] critical/ConfigItem: Location: + /etc/icinga2/conf.d/tests/5872.conf(5): } + /etc/icinga2/conf.d/tests/5872.conf(6): + /etc/icinga2/conf.d/tests/5872.conf(7): apply Service "5872-ping4" { + ^^^^^^^^^^^^^ + /etc/icinga2/conf.d/tests/5872.conf(8): import "test-generic-service" + /etc/icinga2/conf.d/tests/5872.conf(9): check_command = "ping4" + + Config error: 'apply' is missing 'assign' + [2014-05-22 17:07:25 +0200] critical/ConfigItem: 1 errors, 0 warnings. + Icinga 2 detected configuration errors. + +> **Tip** +> +> Icinga 2 will automatically detect the default path for `icinga2.conf` +> in `SysconfDir + /icinga2/icinga2.conf` and you can safely omit this parameter. +> +> `# icinga2 daemon -C` + +If you encouter errors during configuration validation, please make sure +to read the [troubleshooting](7-troubleshooting.md#troubleshooting) chapter. + +You can also use the [CLI command](5-cli-commands.md#cli-command-object) `icinga2 object list` +after validation passes to analyze object attributes, inheritance or created +objects by apply rules. +Find more on troubleshooting with `object list` in [this chapter](7-troubleshooting.md#list-configuration-objects). + +Example filtered by `Service` objects with the name `ping*`: + + # icinga2 object list --type Service --name *ping* + Object 'nbmif.int.netways.de!ping4' of type 'Service': + * __name = 'nbmif.int.netways.de!ping4' + * check_command = 'ping4' + % = modified in '/etc/icinga2/conf.d/services.conf', lines 17:3-17:25 + * check_interval = 60 + % = modified in '/etc/icinga2/conf.d/templates.conf', lines 28:3-28:21 + * host_name = 'nbmif.int.netways.de' + % = modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21 + * max_check_attempts = 3 + % = modified in '/etc/icinga2/conf.d/templates.conf', lines 27:3-27:24 + * name = 'ping4' + % = modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21 + * retry_interval = 30 + % = modified in '/etc/icinga2/conf.d/templates.conf', lines 29:3-29:22 + * templates = [ 'ping4', 'generic-service' ] + % += modified in '/etc/icinga2/conf.d/services.conf', lines 14:1-14:21 + % += modified in '/etc/icinga2/conf.d/templates.conf', lines 26:1-30:1 + * type = 'Service' + * vars + % += modified in '/etc/icinga2/conf.d/services.conf', lines 18:3-18:19 + * sla = '24x7' + % = modified in '/etc/icinga2/conf.d/services.conf', lines 18:3-18:19 + + + +## Reload on Configuration Changes + +Everytime you have changed your configuration you should first tell Icinga 2 +to [validate](5-cli-commands.md#config-validation). If there are no validation errors you can +safely reload the Icinga 2 daemon. + + # /etc/init.d/icinga2 reload + +> **Note** +> +> The `reload` action will send the `SIGHUP` signal to the Icinga 2 daemon +> which will validate the configuration in a separate process and not stop +> the other events like check execution, notifications, etc. +> +> Details can be found [here](8-migrating-from-icinga-1x.md#differences-1x-2-real-reload). + diff --git a/doc/5-addons-plugins.md b/doc/6-addons-plugins.md similarity index 83% rename from doc/5-addons-plugins.md rename to doc/6-addons-plugins.md index c704d0e94..4952189f1 100644 --- a/doc/5-addons-plugins.md +++ b/doc/6-addons-plugins.md @@ -8,19 +8,19 @@ [PNP](http://www.pnp4nagios.org) must be configured using the [bulk mode with npcd and npcdmod](http://docs.pnp4nagios.org/pnp-0.6/modes#bulk_mode_with_npcd_and_npcdmod) -hence Icinga 2's [PerfdataWriter](#performance-data) acts as npcdmod. NPCD will collect +hence Icinga 2's [PerfdataWriter](3-monitoring-basics.md#performance-data) acts as npcdmod. NPCD will collect the rotated performance data files. #### inGraph [inGraph](https://www.netways.org/projects/ingraph/wiki) requires the ingraph-collector addon -to be configured to point at the perfdata files. Icinga 2's [PerfdataWriter](#performance-data) will +to be configured to point at the perfdata files. Icinga 2's [PerfdataWriter](3-monitoring-basics.md#performance-data) will write to the performance data spool directory. #### Graphite There are Graphite addons available for collecting the performance data files as well. But -natively you can use the [GraphiteWriter](#graphite-carbon-cache-writer) feature. +natively you can use the [GraphiteWriter](3-monitoring-basics.md#graphite-carbon-cache-writer) feature. #### Icinga Reporting @@ -39,7 +39,7 @@ based on your monitoring configuration and status data using [NagVis](http://www As well as the Icinga supported web interfaces (Classic UI 1.x, Web 1.x, Web 2) there are a number of community provided web interfaces too: -* [Thruk](http://www.thruk.org) based on the [Livestatus](#livestatus) feature +* [Thruk](http://www.thruk.org) based on the [Livestatus](3-monitoring-basics.md#livestatus) feature ## Plugins @@ -54,7 +54,7 @@ list of popular community sites which host check plugins: * [Icinga Wiki](https://wiki.icinga.org) The recommended way of setting up these plugins is to copy them to a common directory -and create a new global constant, e.g. `CustomPluginDir` in your [constants.conf](#constants-conf) +and create a new global constant, e.g. `CustomPluginDir` in your [constants.conf](2-getting-started.md#constants-conf) configuration file: # cp check_snmp_int.pl /opt/plugins @@ -81,9 +81,9 @@ documentation and/or plugin provided README for installation instructions. Sometimes plugins contain hard-coded paths to other components. Instead of changing the plugin it might be easier to create logical links which is (more) update-safe. -Each plugin requires a [CheckCommand](#objecttype-checkcommand) object in your -configuration which can be used in the [Service](#objecttype-service) or -[Host](#objecttype-host) object definition. +Each plugin requires a [CheckCommand](11-object-types.md#objecttype-checkcommand) object in your +configuration which can be used in the [Service](11-object-types.md#objecttype-service) or +[Host](11-object-types.md#objecttype-host) object definition. There are the following conventions to follow when adding a new command object definition: @@ -93,7 +93,7 @@ in `[ ... ]` then for shell escaping. * Define a unique `prefix` for the command's specific command arguments. That way you can safely set them on host/service level and you'll always know which command they control. * Use command argument default values, e.g. for thresholds -* Use [advanced conditions](#objecttype-checkcommand) like `set_if` definitions. +* Use [advanced conditions](11-object-types.md#objecttype-checkcommand) like `set_if` definitions. Example for a custom `my-snmp-int` check command: @@ -124,12 +124,12 @@ Example for a custom `my-snmp-int` check command: } You can find an existing `CheckCommand` definition for the `check_snmp_int.pl` plugin -shipped with the optional [Manubulon Plugin Check Command](#snmp-manubulon-plugin-check-commands) +shipped with the optional [Manubulon Plugin Check Command](12-icinga-template-library.md#snmp-manubulon-plugin-check-commands) definitions already. For further information on your monitoring configuration read the -[monitoring basics](#monitoring-basics). +[monitoring basics](3-monitoring-basics.md#monitoring-basics). You can find plugins (additional to the ones at [Monitoring Plugins](https://www.monitoring-plugins.org)) over at [Icinga Exchange](https://exchange.icinga.org) diff --git a/doc/6-troubleshooting.md b/doc/7-troubleshooting.md similarity index 93% rename from doc/6-troubleshooting.md rename to doc/7-troubleshooting.md index 27a8729bb..3cab123cd 100644 --- a/doc/6-troubleshooting.md +++ b/doc/7-troubleshooting.md @@ -8,7 +8,7 @@ * Provide complete configuration snippets explaining your problem in detail * Provide complete logs targetting your problem * If the check command failed - what's the output of your manual plugin tests? -* In case of [debugging](#debug) Icinga 2, the full back traces and outputs +* In case of [debugging](7-troubleshooting.md#debug) Icinga 2, the full back traces and outputs ## Enable Debug Output @@ -31,7 +31,7 @@ Alternatively you can enable the debug log: The `icinga2 object list` CLI command can be used to list all configuration objects and their attributes. The tool also shows where each of the attributes was modified. -That way you can also identify which objects have been created from your [apply rules](#apply). +That way you can also identify which objects have been created from your [apply rules](9-language-reference.md#apply). # icinga2 object list @@ -90,13 +90,13 @@ You can also filter by name and type: ## Where are the check command definitions -Icinga 2 ships additional [plugin check command definitions](#plugin-check-commands) which are +Icinga 2 ships additional [plugin check command definitions](12-icinga-template-library.md#plugin-check-commands) which are included using include include -in the [icinga2.conf](#icinga2-conf) configuration file. These configurations will be overridden +in the [icinga2.conf](2-getting-started.md#icinga2-conf) configuration file. These configurations will be overridden on upgrade, so please send modifications as proposed patches upstream. The default include path is set to `LocalStateDir + "/share/icinga2/includes"`. @@ -108,7 +108,7 @@ or similar. * Check the debug log to see if the check command gets executed * Verify that failed depedencies do not prevent command execution * Make sure that the plugin is executable by the Icinga 2 user (run a manual test) -* Make sure the [checker](#features) feature is enabled. +* Make sure the [checker](5-cli-commands.md#features) feature is enabled. Examples: @@ -130,7 +130,7 @@ Verify the following configuration * Do the notification attributes `states`, `types`, `period` match the notification conditions? * Do the user attributes `states`, `types`, `period` match the notification conditions? * Are there any notification `begin` and `end` times configured? -* Make sure the [notification](#features) feature is enabled. +* Make sure the [notification](5-cli-commands.md#features) feature is enabled. * Does the referenced NotificationCommand work when executed as Icinga user on the shell? If notifications are to be sent via mail make sure that the mail program specified exists. @@ -145,15 +145,15 @@ Examples: ## Feature is not working * Make sure that the feature configuration is enabled by symlinking from `features-available/` -to `features-enabled` and that the latter is included in [icinga2.conf](#icinga2-conf). +to `features-enabled` and that the latter is included in [icinga2.conf](2-getting-started.md#icinga2-conf). * Are the feature attributes set correctly according to the documentation? * Any errors on the logs? ## Configuration is ignored -* Make sure that the line(s) are not [commented](#comments) (starting with `//` or `#`, or +* Make sure that the line(s) are not [commented](9-language-reference.md#comments) (starting with `//` or `#`, or encapsulated by `/* ... */`). -* Is the configuration file included in [icinga2.conf](#icinga2-conf)? +* Is the configuration file included in [icinga2.conf](2-getting-started.md#icinga2-conf)? ## Configuration attributes are inherited from @@ -163,7 +163,7 @@ or modify these attributes in the current object. ## Cluster Troubleshooting -You should configure the [cluster health checks](#cluster-health-check) if you haven't +You should configure the [cluster health checks](4-monitoring-remote-systems.md#cluster-health-check) if you haven't done so already. > **Note** @@ -217,7 +217,7 @@ If the cluster zones do not sync their configuration, make sure to check the fol * Within a config master zone, only one configuration master is allowed to have its config in `/etc/icinga2/zones.d`. ** The master syncs the configuration to `/var/lib/icinga2/api/zones/` during startup and only syncs valid configuration to the other nodes ** The other nodes receive the configuration into `/var/lib/icinga2/api/zones/` -* The `icinga2.log` log file will indicate whether this ApiListener [accepts config](#zone-config-sync-permissions), or not +* The `icinga2.log` log file will indicate whether this ApiListener [accepts config](4-monitoring-remote-systems.md#zone-config-sync-permissions), or not ## Debug Icinga 2 diff --git a/doc/7-migrating-from-icinga-1x.md b/doc/8-migrating-from-icinga-1x.md similarity index 95% rename from doc/7-migrating-from-icinga-1x.md rename to doc/8-migrating-from-icinga-1x.md index 168073c4f..e41d37201 100644 --- a/doc/7-migrating-from-icinga-1x.md +++ b/doc/8-migrating-from-icinga-1x.md @@ -27,7 +27,7 @@ If you encounter a bug, please open an issue at https://dev.icinga.org. For a long-term migration of your configuration you should consider re-creating your configuration based on the proposed Icinga 2 configuration paradigm. -Please read the [next chapter](#differences-1x-2) to find out more about the differences +Please read the [next chapter](8-migrating-from-icinga-1x.md#differences-1x-2) to find out more about the differences between 1.x and 2. ### Manual Config Migration Hints @@ -39,7 +39,7 @@ Icinga 1.x configuration. The examples are taken from Icinga 1.x test and production environments and converted straight into a possible Icinga 2 format. If you found a different strategy, send a patch! -If you require in-depth explanations, please check the [next chapter](#differences-1x-2). +If you require in-depth explanations, please check the [next chapter](8-migrating-from-icinga-1x.md#differences-1x-2). #### Manual Config Migration Hints for Intervals @@ -70,7 +70,7 @@ Icinga 2: #### Manual Config Migration Hints for Services If you have used the `host_name` attribute in Icinga 1.x with one or more host names this service -belongs to, you can migrate this to the [apply rules](#using-apply) syntax. +belongs to, you can migrate this to the [apply rules](3-monitoring-basics.md#using-apply) syntax. Icinga 1.x: @@ -100,7 +100,7 @@ like the following example: use generic-service } -Using Icinga 2 you can migrate this to the [apply rules](#using-apply) syntax: +Using Icinga 2 you can migrate this to the [apply rules](3-monitoring-basics.md#using-apply) syntax: apply Service "servicewithhostgroups" { import "generic-service" @@ -127,7 +127,7 @@ a member and includes all members of the `hg1` hostgroup. hostgroup_members hg1 } -This can be migrated to Icinga 2 and [using group assign](#group-assign). The additional nested hostgroup +This can be migrated to Icinga 2 and [using group assign](9-language-reference.md#group-assign). The additional nested hostgroup `hg1` is included into `hg2` with the `groups` attribute. @@ -217,8 +217,8 @@ directory - one major problem solved. For the check command it is required to * Escape all double quotes with an additional `\`. -* Replace all [runtime macros](#manual-config-migration-hints-runtime-macros), e.g. `$HOSTADDRESS$` with `$address$`. -* Replace [custom variable macros](#manual-config-migration-hints-runtime-custom-attributes) if any. +* Replace all [runtime macros](8-migrating-from-icinga-1x.md#manual-config-migration-hints-runtime-macros), e.g. `$HOSTADDRESS$` with `$address$`. +* Replace [custom variable macros](8-migrating-from-icinga-1x.md#manual-config-migration-hints-runtime-custom-attributes) if any. * Keep `$ARGn$` macros. The final check command looks like this in Icinga2: @@ -257,7 +257,7 @@ That way the old command arguments fashion can be applied for Icinga 2, although #### Manual Config Migration Hints for Runtime Macros -Runtime macros have been renamed. A detailed comparison table can be found [here](#differences-1x-2-runtime-macros). +Runtime macros have been renamed. A detailed comparison table can be found [here](8-migrating-from-icinga-1x.md#differences-1x-2-runtime-macros). For example, accessing the service check output looks like the following in Icinga 1.x: @@ -318,7 +318,7 @@ while the service check command resolves its value to the service attribute attr #### Manual Config Migration Hints for Contacts (Users) Contacts in Icinga 1.x act as users in Icinga 2, but do not have any notification commands specified. -This migration part is explained in the [next chapter](#manual-config-migration-hints-notifications). +This migration part is explained in the [next chapter](8-migrating-from-icinga-1x.md#manual-config-migration-hints-notifications). define contact{ contact_name testconfig-user @@ -328,7 +328,7 @@ This migration part is explained in the [next chapter](#manual-config-migration- email icinga@localhost } -The `service_notification_options` can be [mapped](#manual-config-migration-hints-notification-filters) +The `service_notification_options` can be [mapped](8-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters) into generic `state` and `type` filters, if additional notification filtering is required. `alias` gets renamed to `display_name`. @@ -358,7 +358,7 @@ generic strategy * which contacts (users) are notified by mail? * do the notification filters, periods, intervals still apply for them? (do a cleanup during migration) * assign users and groups to these notifications -* Redesign the notifications into generic [apply rules](#using-apply-notifications) +* Redesign the notifications into generic [apply rules](3-monitoring-basics.md#using-apply-notifications) The ugly workaround solution could look like this: @@ -380,7 +380,7 @@ Assign it to the host or service and set the newly generated notification comman Convert the `notification_options` attribute from Icinga 1.x to Icinga 2 `states` and `types`. Details -[here](#manual-config-migration-hints-notification-filters). Add the notification period. +[here](8-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters). Add the notification period. states = [ OK, Warning, Critical ] types = [ Recovery, Problem, Custom ] @@ -518,7 +518,7 @@ just this service belonging to hosts in the matched hostgroup. #### Manual Config Migration Hints for Dependencies -There are some dependency examples already in the [basics chapter](#dependencies). Dependencies in +There are some dependency examples already in the [basics chapter](3-monitoring-basics.md#dependencies). Dependencies in Icinga 1.x can be confusing in terms of which host/service is the parent and which host/service acts as the child. @@ -617,7 +617,7 @@ enabled. assign where "hg_svcdep2" in host.groups } -Host dependencies are explained in the [next chapter](#manual-config-migration-hints-host-parents). +Host dependencies are explained in the [next chapter](8-migrating-from-icinga-1x.md#manual-config-migration-hints-host-parents). @@ -721,9 +721,9 @@ daemon for passing check results between instances. * Icinga 2 does not support any 1.x NEB addons for check load distribution * If your current setup consists of instances distributing the check load, you should consider -building a [load distribution](#cluster-scenarios-load-distribution) setup with Icinga 2. +building a [load distribution](4-monitoring-remote-systems.md#cluster-scenarios-load-distribution) setup with Icinga 2. * If your current setup includes active/passive clustering with external tools like Pacemaker/DRBD -consider the [High Availability](#cluster-scenarios-high-availability) setup. +consider the [High Availability](4-monitoring-remote-systems.md#cluster-scenarios-high-availability) setup. * If you have build your own custom configuration deployment and check result collecting mechanism you should re-design your setup and re-evaluate your requirements, and how they may be fulfilled using the Icinga 2 cluster capabilities. @@ -773,11 +773,11 @@ included in `icinga2.conf` by default. ### Main Config File In Icinga 1.x there are many global configuration settings available in `icinga.cfg`. -Icinga 2 only uses a small set of [global constants](#constants) allowing +Icinga 2 only uses a small set of [global constants](9-language-reference.md#constants) allowing you to specify certain different setting such as the `NodeName` in a cluster scenario. -Aside from that, the [icinga2.conf](#icinga2-conf) should take care of including -global constants, enabled [features](#features) and the object configuration. +Aside from that, the [icinga2.conf](2-getting-started.md#icinga2-conf) should take care of including +global constants, enabled [features](5-cli-commands.md#features) and the object configuration. ### Include Files and Directories @@ -826,7 +826,7 @@ set in the `constants.conf` configuration file: const PluginDir = "/usr/lib/nagios/plugins" -[Global macros](#constants) can only be defined once. Trying to modify a +[Global macros](9-language-reference.md#constants) can only be defined once. Trying to modify a global constant will result in an error. ### Configuration Comments @@ -924,7 +924,7 @@ In Icinga 2 these attributes must be added to the `vars` dictionary as custom at vars.dn = "cn=icinga2-dev-host,ou=icinga,ou=main,ou=IcingaConfig,ou=LConf,dc=icinga,dc=org" vars.cv = "my custom cmdb description" -These custom attributes are also used as [command parameters](#command-passing-parameters). +These custom attributes are also used as [command parameters](3-monitoring-basics.md#command-passing-parameters). ### Host Service Relation @@ -933,7 +933,7 @@ In Icinga 1.x a service object is associated with a host by defining the to `hostgroup_name` or behaviour changing regular expression. The preferred way of associating hosts with services in Icinga 2 is by -using the [apply](#using-apply) keyword. +using the [apply](3-monitoring-basics.md#using-apply) keyword. ### Users @@ -952,7 +952,7 @@ and their users. ### Macros Various object attributes and runtime variables can be accessed as macros in -commands in Icinga 1.x - Icinga 2 supports all required [custom attributes](#custom-attributes). +commands in Icinga 1.x - Icinga 2 supports all required [custom attributes](3-monitoring-basics.md#custom-attributes). #### Command Arguments @@ -992,7 +992,7 @@ With the freely definable custom attributes in Icinga 2 it looks like this: > **Note** > -> For better maintainability you should consider using [command arguments](#command-arguments) +> For better maintainability you should consider using [command arguments](3-monitoring-basics.md#command-arguments) > for your check commands. > **Note** @@ -1004,7 +1004,7 @@ With the freely definable custom attributes in Icinga 2 it looks like this: The global configuration setting `enable_environment_macros` does not exist in Icinga 2. -Macros exported into the [environment](#runtime-custom-attribute-env-vars) +Macros exported into the [environment](3-monitoring-basics.md#runtime-custom-attribute-env-vars) must be set using the `env` attribute in command objects. #### Runtime Macros @@ -1251,7 +1251,7 @@ timeout. This was essentially bad when there only was a couple of check plugins requiring some command timeouts to be extended. Icinga 2 allows you to specify the command timeout directly on the command. So -if your VMVware check plugin takes 15 minutes, [increase the timeout](#objecttype-checkcommand) +if your VMVware check plugin takes 15 minutes, [increase the timeout](11-object-types.md#objecttype-checkcommand) accordingly. @@ -1383,10 +1383,10 @@ The former `host_name` and `dependent_host_name` have been renamed to `parent_ho and `child_host_name` (same for the service attribute). When using apply rules the child attributes may be omitted. -For detailed examples on how to use the dependencies please check the [dependencies](#dependencies) +For detailed examples on how to use the dependencies please check the [dependencies](3-monitoring-basics.md#dependencies) chapter. -Dependencies can be applied to hosts or services using the [apply rules](#apply). +Dependencies can be applied to hosts or services using the [apply rules](9-language-reference.md#apply). The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types support the Icinga 1.x schema with dependencies and parent attributes for @@ -1436,7 +1436,7 @@ Unlike Icinga 1.x the Icinga 2 daemon reload happens asynchronously. * parent process continues with old configuration objects and the event scheduling (doing checks, replicating cluster events, triggering alert notifications, etc.) * validation NOT ok: child process terminates, parent process continues with old configuration state -(this is ESSENTIAL for the [cluster config synchronisation](#cluster-zone-config-sync)) +(this is ESSENTIAL for the [cluster config synchronisation](4-monitoring-remote-systems.md#cluster-zone-config-sync)) * validation ok: child process signals parent process to terminate and save its current state (all events until now) into the icinga2 state file * parent process shuts down writing icinga2.state file @@ -1491,6 +1491,6 @@ distribution out-of-the-box. Furthermore comments, downtimes, and other stateful not synced between the master and slave nodes. There are addons available solving the check and configuration distribution problems Icinga 1.x distributed monitoring currently suffers from. -Icinga 2 implements a new built-in [distributed monitoring architecture](#distributed-monitoring-high-availability), +Icinga 2 implements a new built-in [distributed monitoring architecture](4-monitoring-remote-systems.md#distributed-monitoring-high-availability), including config and check distribution, IPv4/IPv6 support, SSL certificates and zone support for DMZ. High Availability and load balancing are also part of the Icinga 2 Cluster setup. diff --git a/doc/8-language-reference.md b/doc/9-language-reference.md similarity index 98% rename from doc/8-language-reference.md rename to doc/9-language-reference.md index 831d329d0..90876a826 100644 --- a/doc/8-language-reference.md +++ b/doc/9-language-reference.md @@ -188,12 +188,6 @@ Functions can be called using the `()` operator: check_interval = len(MyGroups) * 1m } -> **Tip** -> -> Use these functions in [apply](#using-apply) rule expressions. - - assign where match("192.168.*", host.address) - A list of available functions is available in the [Built-in functions and methods](#builtin-functions) chapter. ## Assignments @@ -389,7 +383,7 @@ another group of objects. In this example the `assign where` condition is a boolean expression which is evaluated for all objects of type `Host` and a new service with name "ping" -is created for each matching host. [Expression operators](#expression-operators) +is created for each matching host. [Expression operators](9-language-reference.md#expression-operators) may be used in `assign where` conditions. The `to` keyword and the target type may be omitted if there is only one target @@ -426,7 +420,7 @@ and `ignore where` conditions. In this example the `assign where` condition is a boolean expression which is evaluated for all objects of the type `Host`. Each matching host is added as member to the host group with the name "linux-servers". Membership exclusion can be controlled using the `ignore where` -condition. [Expression operators](#expression-operators) may be used in `assign where` and +condition. [Expression operators](9-language-reference.md#expression-operators) may be used in `assign where` and `ignore where` conditions. Source Type | Variables @@ -455,7 +449,7 @@ Empty dictionary | {} | false Non-empty dictionary | { key = "value" } | true For a list of supported expression operators for `assign where` and `ignore where` -statements, see [expression operators](#expression-operators). +statements, see [expression operators](9-language-reference.md#expression-operators). ## Comments diff --git a/doc/update-links.py b/doc/update-links.py new file mode 100755 index 000000000..f1d0b0b9d --- /dev/null +++ b/doc/update-links.py @@ -0,0 +1,55 @@ +#!/usr/bin/env python +# Icinga 2 +# Copyright (C) 2012-2014 Icinga Development Team (http://www.icinga.org) +# +# This program is free software; you can redistribute it and/or +# modify it under the terms of the GNU General Public License +# as published by the Free Software Foundation; either version 2 +# of the License, or (at your option) any later version. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License +# along with this program; if not, write to the Free Software Foundation +# Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. + +import os +import sys +import re + +if len(sys.argv) < 2: + print "Syntax: %s " + print "" + print "Updates intra-chapter links in the specified Markdown files." + sys.exit(1) + +anchors = {} + +for file in sys.argv[1:]: + text = open(file).read() + for match in re.finditer(r".*?)\">", text): + id = match.group("id") + + if id in anchors: + print "Anchor '%s' is used multiple times: in %s and %s" % (id, file, anchors[id]) + + anchors[match.group("id")] = file + +def update_anchor(match): + id = match.group("id") + + try: + file = os.path.basename(anchors[id]) + except KeyError: + print "Unmatched anchor: %s" % (id) + file = "" + + return "[%s](%s#%s)" % (match.group("text"), file, id) + +for file in sys.argv[1:]: + text = open(file).read() + new_text = re.sub(r"\[(?P.*)\]\((?P[0-9-[a-z]\.]+)?#(?P[^#\)]+)\)", update_anchor, text) + open(file, "w").write(new_text) -- 2.40.0