From e09b8885bd267812a578dc1c21fea87c1f8d3baa Mon Sep 17 00:00:00 2001 From: Gunnar Beutner Date: Thu, 22 Jan 2015 16:09:28 +0100 Subject: [PATCH] Update documentation --- doc/1-about.md | 8 +- ...-reference.md => 10-language-reference.md} | 4 +- ...y-reference.md => 11-library-reference.md} | 0 ...{11-object-types.md => 12-object-types.md} | 0 ...brary.md => 13-icinga-template-library.md} | 0 doc/{13-appendix.md => 14-appendix.md} | 0 doc/2-getting-started.md | 79 ++----- doc/3-monitoring-basics.md | 178 ++-------------- doc/4-monitoring-remote-systems.md | 21 +- doc/5-cli-commands.md | 16 +- doc/7-livestatus.md | 194 ++++++++++++++++++ ...roubleshooting.md => 8-troubleshooting.md} | 9 +- ...ga-1x.md => 9-migrating-from-icinga-1x.md} | 0 doc/scroll.js | 16 ++ doc/update-links.py | 2 +- mkdocs.yml | 21 ++ 16 files changed, 288 insertions(+), 260 deletions(-) rename doc/{9-language-reference.md => 10-language-reference.md} (99%) rename doc/{10-library-reference.md => 11-library-reference.md} (100%) rename doc/{11-object-types.md => 12-object-types.md} (100%) rename doc/{12-icinga-template-library.md => 13-icinga-template-library.md} (100%) rename doc/{13-appendix.md => 14-appendix.md} (100%) create mode 100644 doc/7-livestatus.md rename doc/{7-troubleshooting.md => 8-troubleshooting.md} (97%) rename doc/{8-migrating-from-icinga-1x.md => 9-migrating-from-icinga-1x.md} (100%) create mode 100644 doc/scroll.js create mode 100644 mkdocs.yml diff --git a/doc/1-about.md b/doc/1-about.md index 8452642f13c..721efd202b2 100644 --- a/doc/1-about.md +++ b/doc/1-about.md @@ -124,7 +124,7 @@ Icinga 2 still supports writing performance data files for graphing addons, but capability of writing performance data directly into a Graphite TCP socket simplifying realtime monitoring graphs. -* Native support for writing log events to [GELF](#gelf-writer) receivers (graylog2, Logstash) +* Native support for writing log events to [GELF](11-object-types.md#objecttype-gelfwriter) receivers (graylog2, Logstash) Icinga 2 will write all check result, state change and notification event logs into a defined [GELF](3-monitoring-basics.md#gelfwriter) input receiver. Natively provided by [graylog2](http://www.graylog2.org), @@ -139,7 +139,7 @@ relationships based on patterns. More advanced features for dynamic object gener 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). +[Check command configuration](12-icinga-template-library.md#plugin-check-commands) for common plugins is shipped with Icinga 2 as part of the [Icinga Template Library](12-icinga-template-library.md#icinga-template-library). * Revamped Commands @@ -183,13 +183,13 @@ objects and specify their active time window. * Embedded Health Checks -No more external statistic tool but an [instance](#itl-icinga) and [cluster](#itl-cluster) health +No more external statistic tool but an [instance](12-icinga-template-library.md#itl-icinga) and [cluster](12-icinga-template-library.md#itl-icinga-cluster) health check providing direct statistics as performance data for your graphing addon, for example Graphite. * Compatibility with Icinga 1.x 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), +[DB IDO](2-getting-started.md#configuring-db-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 diff --git a/doc/9-language-reference.md b/doc/10-language-reference.md similarity index 99% rename from doc/9-language-reference.md rename to doc/10-language-reference.md index 90876a826de..26a1fa24c30 100644 --- a/doc/9-language-reference.md +++ b/doc/10-language-reference.md @@ -188,7 +188,7 @@ Functions can be called using the `()` operator: check_interval = len(MyGroups) * 1m } -A list of available functions is available in the [Built-in functions and methods](#builtin-functions) chapter. +A list of available functions is available in the [Library Reference](10-library-reference.md#library-reference) chapter. ## Assignments @@ -487,7 +487,7 @@ Note the use of angle brackets instead of double quotes. This causes the config compiler to search the include search paths for the specified file. By default $PREFIX/share/icinga2/include is included in the list of search paths. Additional include search paths can be added using -[command-line options](#cmdline). +[command-line options](5-cli-commands.md#config-include-path). Wildcards are not permitted when using angle brackets. diff --git a/doc/10-library-reference.md b/doc/11-library-reference.md similarity index 100% rename from doc/10-library-reference.md rename to doc/11-library-reference.md diff --git a/doc/11-object-types.md b/doc/12-object-types.md similarity index 100% rename from doc/11-object-types.md rename to doc/12-object-types.md diff --git a/doc/12-icinga-template-library.md b/doc/13-icinga-template-library.md similarity index 100% rename from doc/12-icinga-template-library.md rename to doc/13-icinga-template-library.md diff --git a/doc/13-appendix.md b/doc/14-appendix.md similarity index 100% rename from doc/13-appendix.md rename to doc/14-appendix.md diff --git a/doc/2-getting-started.md b/doc/2-getting-started.md index 9ffb68c3f42..fe06c5ffd47 100644 --- a/doc/2-getting-started.md +++ b/doc/2-getting-started.md @@ -343,15 +343,15 @@ The custom attribute `os` is evaluated by the `linux-servers` group in The example host will show you how to * define http vhost attributes for the `http` service apply rule defined -in [services.conf](#services.conf). +in [services.conf](2-getting-started.md#services-conf). * define disks (all, specific `/`) and their attributes for the `disk` -service apply rule defined in [services.conf](#services.conf). +service apply rule defined in [services.conf](2-getting-started.md#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](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 +rules in [services.conf](2-getting-started.md#services-conf) will automatically generate a new service checking the `/icingaweb2` URI using the `http` check. @@ -438,7 +438,7 @@ Service(s) | Applied on host(s) The Debian packages also ship an additional `apt` service check applied to the local host. The command object `icinga` for the embedded health check is provided by the -[Icinga Template Library (ITL)](#itl) while `http_ip`, `ssh`, `load`, `processes`, +[Icinga Template Library (ITL)](12-icinga-template-library.md#icinga-template-library) while `http_ip`, `ssh`, `load`, `processes`, `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. @@ -597,7 +597,7 @@ The `interval` attribute is not explicitly set - it [defaults to 30 minutes](11- By setting the `user_groups` to the value provided by the 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). +implicitely use the`icingaadmins` UserGroup defined in [users.conf](2-getting-started.md#users-conf). apply Notification "mail-icingaadmin" to Host { import "mail-host-notification" @@ -811,8 +811,8 @@ RHEL/CentOS 5/6: RHEL/CentOS 7 and Fedora 20 prefer MariaDB over MySQL: # yum install mariadb-server mariadb - # systemctl enable mariadb.service - # systemctl start mariadb.service + # systemctl enable mariadb + # systemctl start mariadb SUSE: @@ -839,8 +839,8 @@ RHEL/CentOS 5/6: RHEL/CentOS 7 and Fedora 20 use [systemd](2-getting-started.md#systemd-service): # yum install postgresql-server postgresql - # systemctl enable postgresql.service - # systemctl start postgresql.service + # systemctl enable postgresql + # systemctl start postgresql SUSE: @@ -938,7 +938,7 @@ Debian/Ubuntu, RHEL/CentOS 6 and SUSE: RHEL/CentOS 7 and Fedora 20: - # systemctl restart icinga2.service + # systemctl restart icinga2 ### Configuring DB IDO PostgreSQL @@ -1052,7 +1052,7 @@ Debian/Ubuntu, RHEL/CentOS 6 and SUSE: RHEL/CentOS 7 and Fedora 20: - # systemctl restart icinga2.service + # systemctl restart icinga2 ### Setting Up External Command Pipe @@ -1072,7 +1072,7 @@ Debian/Ubuntu, RHEL/CentOS 6 and SUSE: RHEL/CentOS 7 and Fedora 20: - # systemctl restart icinga2.service + # systemctl restart icinga2 By default the command pipe file is owned by the group `icingacmd` with read/write permissions. Add your webserver's user to the group `icingacmd` to @@ -1092,59 +1092,6 @@ Change "www-data" to the user you're using to run queries. > Packages will do that automatically. Verify that by running `id ` and skip this > step. -## Setting up Livestatus - -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. - -> **Tip** -> -> Only install the Livestatus feature if your web interface or addon requires -> 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 -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](3-monitoring-basics.md#livestatus) section. - -You can enable Livestatus using icinga2 feature enable: - - # icinga2 feature enable livestatus - -After that you will have to restart Icinga 2: - -Debian/Ubuntu, RHEL/CentOS 6 and SUSE: - - # service icinga2 restart - -RHEL/CentOS 7 and Fedora 20: - - # systemctl restart icinga2.service - -By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`. - -In order for queries and commands to work you will need to add your query user -(e.g. your web server) to the `icingacmd` group: - - # usermod -a -G icingacmd www-data - -The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to -`nagios` if you're using Debian. - -Change "www-data" to the user you're using to run queries. - -In order to use the historical tables provided by the livestatus feature (for example, the -`log` table) you need to have the `CompatLogger` feature enabled. By default these logs -are expected to be in `/var/log/icinga2/compat`. A different path can be set using the -`compat_log_path` configuration attribute. - - # icinga2 feature enable compatlog - ## Setting up Icinga 2 User Interfaces Icinga 2 can be used with [Icinga Web 2](2-getting-started.md#setting-up-icingaweb2), using @@ -1294,7 +1241,7 @@ please check the official [Icinga 1.x user interface documentation](http://docs. Icinga 2 can write to the same schema supplied by `Icinga IDOUtils 1.x` which is an explicit requirement to run `Icinga Web` next to the external command pipe. -Therefore you need to setup the [DB IDO feature](#configuring-ido) remarked in the previous sections. +Therefore you need to setup the [DB IDO feature](2-getting-started.md#configuring-db-ido) remarked in the previous sections. #### Installing Icinga Web 1.x diff --git a/doc/3-monitoring-basics.md b/doc/3-monitoring-basics.md index 4aaafb0e666..08da0d070be 100644 --- a/doc/3-monitoring-basics.md +++ b/doc/3-monitoring-basics.md @@ -142,7 +142,7 @@ In either way of choosing the right strategy you should additionally check the f You can later use them for applying assign/ignore rules, or export them into external interfaces. * 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. +Details can be found in the [using templates](3-monitoring-basics.md#object-inheritance-using-templates) chapter. * 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. @@ -299,7 +299,7 @@ The notification is ignored for services whose host name ends with `*internal` import "cust-xy-notification" assign where match("*has gold support 24x7*", service.notes) && (host.vars.customer == "customer-xy" || host.vars.always_notify == true - ignore where match("*internal", host.name) || (service.vars.priority < 2 && host.is_clustered == true) + ignore where match("*internal", host.name) || (service.vars.priority < 2 && host.vars.is_clustered == true) } @@ -453,15 +453,15 @@ values for any object attribute specified in that apply rule. vars.hosting["xyz"] = { http_uri = "/shop" - customer_name = "Customer xyz" - customer_id = "7568" - support_contract = "gold" + customer_name = "Customer xyz" + customer_id = "7568" + support_contract = "gold" } vars.hosting["abc"] = { http_uri = "/shop" - customer_name = "Customer xyz" - customer_id = "7568" - support_contract = "silver" + customer_name = "Customer xyz" + customer_id = "7568" + support_contract = "silver" } } @@ -629,7 +629,7 @@ Use the `apply` keyword to create `Notification` objects for your services: users = [ "noc-xy", "mgmt-xy" ] assign where match("*has gold support 24x7*", service.notes) && (host.vars.customer == "customer-xy" || host.vars.always_notify == true - ignore where match("*internal", host.name) || (service.vars.priority < 2 && host.is_clustered == true) + ignore where match("*internal", host.name) || (service.vars.priority < 2 && host.vars.is_clustered == true) } @@ -1229,7 +1229,7 @@ check execution if one of these conditions match: * 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) +* The host/service state recovers from a [soft or hard state](3-monitoring-basics.md#hard-soft-states) to [OK](3-monitoring-basics.md#service-states)/[Up](3-monitoring-basics.md#host-states) [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 @@ -1728,8 +1728,8 @@ for applying objects for dynamic config generation. 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 simple attribute literal ([number](9-language-reference.md#numeric-literals), [string](9-language-reference.md#string-literals), +[boolean](9-language-reference.md#boolean-literals)) for expression conditions (`assign where`, `ignore where`) * 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. @@ -2432,10 +2432,10 @@ The IDO (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 1.x and 2. -Details on the installation can be found in the [Getting Started](#configuring-ido) +Details on the installation can be found in the [Configuring DB IDO](2-getting-started.md#configuring-db-ido) chapter. Details on the configuration can be found in the [IdoMysqlConnection](11-object-types.md#objecttype-idomysqlconnection) and -[IdoPgsqlConnection](#objecttype-idoPgsqlconnection) +[IdoPgsqlConnection](11-object-types.md#objecttype-idopgsqlconnection) object configuration documentation. The DB IDO feature supports [High Availability](4-monitoring-remote-systems.md#high-availability-db-ido) in the Icinga 2 cluster. @@ -2482,156 +2482,6 @@ Example for PostgreSQL: A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](13-appendix.md#schema-db-ido). -## Livestatus - -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](2-getting-started.md#setting-up-livestatus) -chapter. - -### Livestatus Sockets - -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](11-object-types.md#objecttype-livestatuslistener) -object configuration. - -### Livestatus GET Queries - -> **Note** -> -> All Livestatus queries require an additional empty line as query end identifier. -> The `nc` tool (`netcat`) provides the `-U` parameter to communicate using -> a unix socket. - -There also is a Perl module available in CPAN for accessing the Livestatus socket -programmatically: [Monitoring::Livestatus](http://search.cpan.org/~nierlein/Monitoring-Livestatus-0.74/) - - -Example using the unix socket: - - # echo -e "GET services\n" | /usr/bin/nc -U /var/run/icinga2/cmd/livestatus - -Example using the tcp socket listening on port `6558`: - - # echo -e 'GET services\n' | netcat 127.0.0.1 6558 - - # cat servicegroups < Livestatus COMMAND Queries - -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 - - -### Livestatus Filters - -and, or, negate - - Operator | Negate | Description - ----------|------------------------ - = | != | Equality - ~ | !~ | Regex match - =~ | !=~ | Equality ignoring case - ~~ | !~~ | Regex ignoring case - < | | Less than - > | | Greater than - <= | | Less than or equal - >= | | Greater than or equal - - -### Livestatus Stats - -Schema: "Stats: aggregatefunction aggregateattribute" - - Aggregate Function | Description - -------------------|-------------- - sum |   - min |   - max |   - avg | sum / count - std | standard deviation - suminv | sum (1 / value) - avginv | suminv / count - count | ordinary default for any stats query if not aggregate function defined - -Example: - - GET hosts - Filter: has_been_checked = 1 - Filter: check_type = 0 - Stats: sum execution_time - Stats: sum latency - Stats: sum percent_state_change - Stats: min execution_time - Stats: min latency - Stats: min percent_state_change - Stats: max execution_time - Stats: max latency - Stats: max percent_state_change - OutputFormat: json - ResponseHeader: fixed16 - -### Livestatus Output - -* CSV - -CSV Output uses two levels of array separators: The members array separator -is a comma (1st level) while extra info and host|service relation separator -is a pipe (2nd level). - -Separators can be set using ASCII codes like: - - Separators: 10 59 44 124 - -* JSON - -Default separators. - -### Livestatus Error Codes - - Code | Description - ----------|-------------- - 200 | OK - 404 | Table does not exist - 452 | Exception on query - -### Livestatus Tables - - Table | Join |Description - --------------|-----------|---------------------------- - hosts |   | host config and status attributes, services counter - hostgroups |   | hostgroup config, status attributes and host/service counters - services | hosts | service config and status attributes - servicegroups |   | servicegroup config, status attributes and service counters - contacts |   | contact config and status attributes - contactgroups |   | contact config, members - commands |   | command name and line - status |   | programstatus, config and stats - comments | services | status attributes - downtimes | services | status attributes - timeperiods |   | name and is inside flag - endpoints |   | config and status 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](13-appendix.md#schema-livestatus). - - ## Check Result Files Icinga 1.x writes its check result files to a temporary spool directory diff --git a/doc/4-monitoring-remote-systems.md b/doc/4-monitoring-remote-systems.md index efee207de8f..bc16910fdf8 100644 --- a/doc/4-monitoring-remote-systems.md +++ b/doc/4-monitoring-remote-systems.md @@ -24,19 +24,19 @@ monitoring and high-availability, please continue reading in If the remote service is available using a network protocol and port, 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) +configure all parameters and thresholds. The [Icinga 2 Template Library](12-icinga-template-library.md#icinga-template-library) already ships various examples like * [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) +[fping4](12-icinga-template-library.md#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](12-icinga-template-library.md#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) +* [ntp_time](12-icinga-template-library.md#plugin-check-command-ntp-time) * [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) +* [dns](12-icinga-template-library.md#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](3-monitoring-basics.md#command-plugin-integration). @@ -133,7 +133,7 @@ The setup wizard will do the following: * Generate a new CSR, sign it with the local CA and copying it into `/etc/icinga2/pki` * Generate a local zone and endpoint configuration for this master based on FQDN * Enabling the API feature, and setting optional `bind_host` and `bind_port` -* Setting the `NodeName` and `TicketSalt` constants in [constants.conf](#constants.conf) +* Setting the `NodeName` and `TicketSalt` constants in [constants.conf](2-getting-started.md#constants-conf) The setup wizard does not automatically restart Icinga 2. @@ -299,7 +299,7 @@ The setup wizard will do the following: (based on FQDN) * Disabling the notification feature for this client * Enabling the API feature, and setting optional `bind_host` and `bind_port` -* Setting the `NodeName` constant in [constants.conf](#constants.conf) +* Setting the `NodeName` constant in [constants.conf](2-getting-started.md#constants-conf) The setup wizard does not automatically restart Icinga 2. @@ -562,8 +562,7 @@ After updating the configuration repository, make sure to reload Icinga 2. # service icinga2 reload Using systemd: - # systemctl reload icinga2.service - + # systemctl reload icinga2 #### Blacklist/Whitelist for Clients on the Master @@ -623,7 +622,7 @@ become handy. The SNMP daemon runs on the remote system and answers SNMP queries by plugin 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) +the `check_snmp` plugin binary, but there are plenty of [existing plugins](6-addons-plugins.md#plugins) for specific use cases already around, for example monitoring Cisco routers. The following example uses the [SNMP ITL](12-icinga-template-library.md#plugin-check-command-snmp) `CheckCommand` and just @@ -1347,7 +1346,7 @@ master instances anymore. ### Cluster Health Check -The Icinga 2 [ITL](#itl) ships an internal check command checking all configured +The Icinga 2 [ITL](12-icinga-template-library.md#icinga-template-library) ships an internal check command checking all configured `EndPoints` in the cluster setup. The check result will become critical if one or more configured nodes are not connected. diff --git a/doc/5-cli-commands.md b/doc/5-cli-commands.md index 2aa03ebaefb..59d5739d5b1 100644 --- a/doc/5-cli-commands.md +++ b/doc/5-cli-commands.md @@ -112,7 +112,7 @@ you can also use the `--library` command-line option. [Global constants](9-language-reference.md#constants) can be set using the `--define` command-line option. -#### Config Include Path +#### 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 @@ -129,7 +129,7 @@ added. -### Cli command: Daemon +### 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). @@ -179,7 +179,7 @@ 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 +### 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 @@ -192,7 +192,7 @@ feature will only bring up all enabled features. 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 +### 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 @@ -236,7 +236,7 @@ nodes in a [remote monitoring ](4-monitoring-remote-systems.md#icinga2-remote-cl Icinga home page: -### Cli command: Object +### 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. @@ -270,7 +270,7 @@ More information can be found in the [troubleshooting](7-troubleshooting.md#list -### Cli command: Pki +### CLI command: Pki Provides the CLI commands to @@ -313,7 +313,7 @@ This functionality is used by the [node setup/wizard](5-cli-commands.md#cli-comm Icinga home page: -### Cli command: Repository +### 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 @@ -368,7 +368,7 @@ cleared after review. -### Cli command: Variable +### CLI command: Variable Lists all configured variables (constants) in a similar fasion like [object list](5-cli-commands.md#cli-command-object). diff --git a/doc/7-livestatus.md b/doc/7-livestatus.md new file mode 100644 index 00000000000..faabf518dba --- /dev/null +++ b/doc/7-livestatus.md @@ -0,0 +1,194 @@ +## Setting up Livestatus + +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. + +> **Tip** +> +> Only install the Livestatus feature if your web interface or addon requires +> 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 +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](3-monitoring-basics.md#livestatus) section. + +You can enable Livestatus using icinga2 feature enable: + + # icinga2 feature enable livestatus + +After that you will have to restart Icinga 2: + +Debian/Ubuntu, RHEL/CentOS 6 and SUSE: + + # service icinga2 restart + +RHEL/CentOS 7 and Fedora 20: + + # systemctl restart icinga2 + +By default the Livestatus socket is available in `/var/run/icinga2/cmd/livestatus`. + +In order for queries and commands to work you will need to add your query user +(e.g. your web server) to the `icingacmd` group: + + # usermod -a -G icingacmd www-data + +The Debian packages use `nagios` as the user and group name. Make sure to change `icingacmd` to +`nagios` if you're using Debian. + +Change "www-data" to the user you're using to run queries. + +In order to use the historical tables provided by the livestatus feature (for example, the +`log` table) you need to have the `CompatLogger` feature enabled. By default these logs +are expected to be in `/var/log/icinga2/compat`. A different path can be set using the +`compat_log_path` configuration attribute. + + # icinga2 feature enable compatlog + + +### Livestatus Sockets + +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](11-object-types.md#objecttype-livestatuslistener) +object configuration. + +### Livestatus GET Queries + +> **Note** +> +> All Livestatus queries require an additional empty line as query end identifier. +> The `nc` tool (`netcat`) provides the `-U` parameter to communicate using +> a unix socket. + +There also is a Perl module available in CPAN for accessing the Livestatus socket +programmatically: [Monitoring::Livestatus](http://search.cpan.org/~nierlein/Monitoring-Livestatus-0.74/) + + +Example using the unix socket: + + # echo -e "GET services\n" | /usr/bin/nc -U /var/run/icinga2/cmd/livestatus + +Example using the tcp socket listening on port `6558`: + + # echo -e 'GET services\n' | netcat 127.0.0.1 6558 + + # cat servicegroups < Livestatus COMMAND Queries + +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 + + +### Livestatus Filters + +and, or, negate + + Operator | Negate | Description + ----------|------------------------ + = | != | Equality + ~ | !~ | Regex match + =~ | !=~ | Equality ignoring case + ~~ | !~~ | Regex ignoring case + < | | Less than + > | | Greater than + <= | | Less than or equal + >= | | Greater than or equal + + +### Livestatus Stats + +Schema: "Stats: aggregatefunction aggregateattribute" + + Aggregate Function | Description + -------------------|-------------- + sum |   + min |   + max |   + avg | sum / count + std | standard deviation + suminv | sum (1 / value) + avginv | suminv / count + count | ordinary default for any stats query if not aggregate function defined + +Example: + + GET hosts + Filter: has_been_checked = 1 + Filter: check_type = 0 + Stats: sum execution_time + Stats: sum latency + Stats: sum percent_state_change + Stats: min execution_time + Stats: min latency + Stats: min percent_state_change + Stats: max execution_time + Stats: max latency + Stats: max percent_state_change + OutputFormat: json + ResponseHeader: fixed16 + +### Livestatus Output + +* CSV + +CSV output uses two levels of array separators: The members array separator +is a comma (1st level) while extra info and host|service relation separator +is a pipe (2nd level). + +Separators can be set using ASCII codes like: + + Separators: 10 59 44 124 + +* JSON + +Default separators. + +### Livestatus Error Codes + + Code | Description + ----------|-------------- + 200 | OK + 404 | Table does not exist + 452 | Exception on query + +### Livestatus Tables + + Table | Join |Description + --------------|-----------|---------------------------- + hosts |   | host config and status attributes, services counter + hostgroups |   | hostgroup config, status attributes and host/service counters + services | hosts | service config and status attributes + servicegroups |   | servicegroup config, status attributes and service counters + contacts |   | contact config and status attributes + contactgroups |   | contact config, members + commands |   | command name and line + status |   | programstatus, config and stats + comments | services | status attributes + downtimes | services | status attributes + timeperiods |   | name and is inside flag + endpoints |   | config and status 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](13-appendix.md#schema-livestatus). + diff --git a/doc/7-troubleshooting.md b/doc/8-troubleshooting.md similarity index 97% rename from doc/7-troubleshooting.md rename to doc/8-troubleshooting.md index 3cab123cd97..3f4723aefc8 100644 --- a/doc/7-troubleshooting.md +++ b/doc/8-troubleshooting.md @@ -24,7 +24,8 @@ Alternatively you can enable the debug log: # icinga2 feature enable debuglog # service icinga2 restart - # tail -f /var/log/icinga2/debug.log + +You can find the debug log file in `/var/log/icinga2/debug.log`. ## List Configuration Objects @@ -88,7 +89,7 @@ You can also filter by name and type: [2014-10-15 14:27:19 +0200] information/cli: Parsed 175 objects. -## Where are the check command definitions +## Where are the check command definitions? Icinga 2 ships additional [plugin check command definitions](12-icinga-template-library.md#plugin-check-commands) which are included using @@ -151,13 +152,13 @@ to `features-enabled` and that the latter is included in [icinga2.conf](2-gettin ## Configuration is ignored -* Make sure that the line(s) are not [commented](9-language-reference.md#comments) (starting with `//` or `#`, or +* Make sure that the line(s) are not [commented out](9-language-reference.md#comments) (starting with `//` or `#`, or encapsulated by `/* ... */`). * Is the configuration file included in [icinga2.conf](2-getting-started.md#icinga2-conf)? ## Configuration attributes are inherited from -Icinga 2 allows you to import templates using the [import](#import) keyword. If these templates +Icinga 2 allows you to import templates using the [import](9-language-reference.md#template-imports) keyword. If these templates contain additional attributes, your objects will automatically inherit them. You can override or modify these attributes in the current object. diff --git a/doc/8-migrating-from-icinga-1x.md b/doc/9-migrating-from-icinga-1x.md similarity index 100% rename from doc/8-migrating-from-icinga-1x.md rename to doc/9-migrating-from-icinga-1x.md diff --git a/doc/scroll.js b/doc/scroll.js new file mode 100644 index 00000000000..bad2ef60e18 --- /dev/null +++ b/doc/scroll.js @@ -0,0 +1,16 @@ +$(document).ready(function() { + + $('a[href^="#"]').on('click',function (e) { + e.preventDefault(); + + var target = this.hash; + var $target = $(target); + + $('html, body').stop().animate({ + 'scrollTop': $target.offset().top + }, 900, 'swing', function () { + window.location.hash = target; + }); + }); + +}); diff --git a/doc/update-links.py b/doc/update-links.py index dd03ad19ba6..9c20ea2bead 100755 --- a/doc/update-links.py +++ b/doc/update-links.py @@ -23,7 +23,7 @@ if len(sys.argv) < 2: print "Syntax: %s " print "" - print "Updates intra-chapter links in the specified Markdown files." + print "Updates inter-chapter links in the specified Markdown files." sys.exit(1) anchors = {} diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000000..72e0bcb57f9 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,21 @@ +site_name: Icinga 2 +docs_dir: doc +dev_addr: 0.0.0.0:8000 +pages: +- [1-about.md, About Icinga 2] +- [2-getting-started.md, Getting Started] +- [3-monitoring-basics.md, Monitoring Basics] +- [4-monitoring-remote-systems.md, Monitoring Remote Systems] +- [5-cli-commands.md, CLI Commands] +- [6-addons-plugins.md, Addons and Plugins] +- [7-livestatus.md, Livestatus] +- [8-troubleshooting.md, Troubleshooting] +- [9-migrating-from-icinga-1x.md, Migrating from Icinga 1.x] +- [10-language-reference.md, Language Reference] +- [11-library-reference.md, Library Reference] +- [12-object-types.md, Object Types] +- [13-icinga-template-library.md, Icinga Template Library] +- [14-appendix.md, Appendix] +theme: readthedocs +markdown_extensions: [smarty] +extra_javascript: [scroll.js]