tyler.durden
/
icinga2
mirror of https://github.com/Icinga/icinga2.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

API: First documentation draft 

refs #9105
This commit is contained in:
Michael Friedrich 2015-08-28 17:17:07 +02:00
parent 9d9a7ca73d
commit d4b3bb57cb
22 changed files with 649 additions and 195 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/1-about.md
View File

@ -50,7 +50,7 @@ More details in the [Icinga FAQ](https://www.icinga.org/icinga/faq/).
* [Register](https://accounts.icinga.org/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](16-troubleshooting.md#troubleshooting-information-required) chapter (version, configs, logs, etc).
* When reporting a bug, please include the details described in the [Troubleshooting](17-troubleshooting.md#troubleshooting-information-required) chapter (version, configs, logs, etc).
## <a id="whats-new"></a> What's New
@ -431,7 +431,7 @@ Please note that this version fixes the default thresholds for the disk check wh
* Solved a number of issues where cluster instances would not reconnect after intermittent connection problems
* A lot of other, minor changes
* [DB IDO schema upgrade](17-upgrading-icinga-2.md#upgrading-icinga-2) to `1.13.0` required!
* [DB IDO schema upgrade](18-upgrading-icinga-2.md#upgrading-icinga-2) to `1.13.0` required!
#### Features

2
doc/9-monitoring-remote-systems.md → doc/10-monitoring-remote-systems.md
View File

@ -5,7 +5,7 @@
There's a variety of possibilities to monitor remote servers and services. First off you should
decide how your primary monitoring master is able to reach these hosts and services.
* direct connection querying the service interface (for example `http`), so-called [agent-less checks](9-monitoring-remote-systems.md#agent-less-checks)
* direct connection querying the service interface (for example `http`), so-called [agent-less checks](10-monitoring-remote-systems.md#agent-less-checks)
* local checks requiring an additional daemon as communication device for your monitoring server
## <a id="agent-less-checks"></a> Agent-less Checks

52
doc/10-icinga2-client.md → doc/11-icinga2-client.md
View File

@ -4,7 +4,7 @@
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](10-icinga2-client.md#icinga2-client).
agent [monitoring a remote client](11-icinga2-client.md#icinga2-client).
All communication is secured by TLS with certificates, and fully supports IPv4 and IPv6.
@ -21,9 +21,9 @@ monitoring and high-availability, please continue reading in
## <a id="icinga2-client-scenarios"></a> Client Scenarios
* Clients with [local configuration](10-icinga2-client.md#icinga2-client-configuration-local), sending their inventory to the master
* Clients as [command execution bridge](10-icinga2-client.md#icinga2-client-configuration-command-bridge) without local configuration
* Clients receive their configuration from the master ([Cluster config sync](10-icinga2-client.md#icinga2-client-configuration-master-config-sync))
* Clients with [local configuration](11-icinga2-client.md#icinga2-client-configuration-local), sending their inventory to the master
* Clients as [command execution bridge](11-icinga2-client.md#icinga2-client-configuration-command-bridge) without local configuration
* Clients receive their configuration from the master ([Cluster config sync](11-icinga2-client.md#icinga2-client-configuration-master-config-sync))
### <a id="icinga2-client-configuration-combined-scenarios"></a> Combined Client Scenarios
@ -43,7 +43,7 @@ and simply use the cluster configuration sync.
* `accept_config` and `accept_commands` are disabled by default in the `api` feature
If you are planning to use the Icinga 2 client inside a distributed setup, refer to
[this chapter](12-distributed-monitoring-ha.md#cluster-scenarios-master-satellite-clients) with detailed instructions.
[this chapter](13-distributed-monitoring-ha.md#cluster-scenarios-master-satellite-clients) with detailed instructions.
## <a id="icinga2-client-installation"></a> Installation
@ -60,7 +60,7 @@ you can close the port and use a different communication direction (master-to-cl
### <a id="icinga2-client-installation-master-setup"></a> Setup the Master for Remote Clients
If you are planning to use the [remote Icinga 2 clients](10-icinga2-client.md#icinga2-client)
If you are planning to use the [remote Icinga 2 clients](11-icinga2-client.md#icinga2-client)
you'll first need to update your master setup.
Your master setup requires the following
@ -156,14 +156,14 @@ Validate the configuration and restart Icinga 2.
## <a id="icinga2-client-setup"></a> Client Setup for Remote Monitoring
Icinga 2 can be installed on Linux/Unix and Windows. While
[Linux/Unix](10-icinga2-client.md#icinga2-client-installation-client-setup-linux) will be using the [CLI command](8-cli-commands.md#cli-command-node)
[Linux/Unix](11-icinga2-client.md#icinga2-client-installation-client-setup-linux) will be using the [CLI command](8-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](10-icinga2-client.md#icinga2-client-installation-master-setup)
* SSL signed certificate for communication with the master (Use [CSR auto-signing](10-icinga2-client.md#csr-autosigning-requirements)).
* A ready configured and installed [master node](11-icinga2-client.md#icinga2-client-installation-master-setup)
* SSL signed certificate for communication with the master (Use [CSR auto-signing](11-icinga2-client.md#csr-autosigning-requirements)).
* Enabled API feature, and a local Endpoint and Zone object configuration
* Firewall ACLs for the communication port (default 5665)
@ -175,7 +175,7 @@ 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](4-configuring-icinga-2.md#constants-conf).
The [setup wizard for the master setup](10-icinga2-client.md#icinga2-client-installation-master-setup) will create
The [setup wizard for the master setup](11-icinga2-client.md#icinga2-client-installation-master-setup) will create
one for you already.
# grep TicketSalt /etc/icinga2/constants.conf
@ -200,11 +200,11 @@ Example for a client:
### <a id="certificates-manual-creation"></a> Manual SSL Certificate Generation
This is described separately in the [cluster setup chapter](12-distributed-monitoring-ha.md#manual-certificate-generation).
This is described separately in the [cluster setup chapter](13-distributed-monitoring-ha.md#manual-certificate-generation).
> **Note**
>
> If you're using [CSR Auto-Signing](10-icinga2-client.md#csr-autosigning-requirements), skip this step.
> If you're using [CSR Auto-Signing](11-icinga2-client.md#csr-autosigning-requirements), skip this step.
### <a id="icinga2-client-installation-client-setup-linux"></a> Setup the Client on Linux
@ -212,8 +212,8 @@ This is described separately in the [cluster setup chapter](12-distributed-monit
There is no extra client binary or package required. Install Icinga 2 from your distribution's package
repository as described in the general [installation instructions](2-getting-started.md#setting-up-icinga2).
Please make sure that either [CSR Auto-Signing](10-icinga2-client.md#csr-autosigning-requirements) requirements
are fulfilled, or that you're using [manual SSL certificate generation](12-distributed-monitoring-ha.md#manual-certificate-generation).
Please make sure that either [CSR Auto-Signing](11-icinga2-client.md#csr-autosigning-requirements) requirements
are fulfilled, or that you're using [manual SSL certificate generation](13-distributed-monitoring-ha.md#manual-certificate-generation).
> **Note**
>
@ -229,7 +229,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 (port defaults to 5665)
* The [request ticket number](10-icinga2-client.md#csr-autosigning-requirements) generated on your master
* The [request ticket number](11-icinga2-client.md#csr-autosigning-requirements) generated on your master
for CSR Auto-Signing
* Bind host/port for the Api feature (optional)
@ -417,7 +417,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](10-icinga2-client.md#csr-autosigning-requirements) generated on your master
* The [request ticket number](11-icinga2-client.md#csr-autosigning-requirements) generated on your master
for CSR Auto-Signing
* Bind host/port for the Api feature (optional)
@ -435,9 +435,9 @@ Configuration validation is done similar to the linux pendant on the Windows she
## <a id="icinga2-client-configuration-modes"></a> Client Configuration Modes
* Clients with [local configuration](10-icinga2-client.md#icinga2-client-configuration-local), sending their inventory to the master
* Clients as [command execution bridge](10-icinga2-client.md#icinga2-client-configuration-command-bridge) without local configuration
* Clients receive their configuration from the master ([Cluster config sync](10-icinga2-client.md#icinga2-client-configuration-master-config-sync))
* Clients with [local configuration](11-icinga2-client.md#icinga2-client-configuration-local), sending their inventory to the master
* Clients as [command execution bridge](11-icinga2-client.md#icinga2-client-configuration-command-bridge) without local configuration
* Clients receive their configuration from the master ([Cluster config sync](11-icinga2-client.md#icinga2-client-configuration-master-config-sync))
### <a id="icinga2-client-configuration-local"></a> Clients with Local Configuration
@ -531,7 +531,7 @@ objects configured, only the check command definitions must be configured.
> **Note**
>
> Remote clients must explicitely accept commands in a similar
> fashion as cluster nodes [accept configuration](12-distributed-monitoring-ha.md#cluster-zone-config-sync).
> fashion as cluster nodes [accept configuration](13-distributed-monitoring-ha.md#cluster-zone-config-sync).
> This is due to security reasons.
Edit the `api` feature configuration in `/etc/icinga2/features-enabled/api.conf` on your client
@ -581,8 +581,8 @@ in `/etc/icinga2/zones.conf` and define a trusted master zone as `parent`.
}
More details here:
* [configure endpoints](12-distributed-monitoring-ha.md#configure-cluster-endpoints)
* [configure zones](12-distributed-monitoring-ha.md#configure-cluster-zones)
* [configure endpoints](13-distributed-monitoring-ha.md#configure-cluster-endpoints)
* [configure zones](13-distributed-monitoring-ha.md#configure-cluster-zones)
Once you have configured the required `Endpoint` and `Zone` object definition, you can start
@ -666,9 +666,9 @@ This is an advanced configuration mode which requires knowledge about the Icinga
cluster configuration and its object relation (Zones, Endpoints, etc) and the way you
will be able to sync the configuration from the master to the remote satellite or client.
Please continue reading in the [distributed monitoring chapter](12-distributed-monitoring-ha.md#distributed-monitoring-high-availability),
especially the [configuration synchronisation](12-distributed-monitoring-ha.md#cluster-zone-config-sync)
and [best practices](12-distributed-monitoring-ha.md#zone-config-sync-best-practice).
Please continue reading in the [distributed monitoring chapter](13-distributed-monitoring-ha.md#distributed-monitoring-high-availability),
especially the [configuration synchronisation](13-distributed-monitoring-ha.md#cluster-zone-config-sync)
and [best practices](13-distributed-monitoring-ha.md#zone-config-sync-best-practice).
@ -735,5 +735,5 @@ using the following CLI command:
> **Note**
>
> Better use [blacklists and/or whitelists](10-icinga2-client.md#icinga2-remote-monitoring-master-discovery-blacklist-whitelist)
> Better use [blacklists and/or whitelists](11-icinga2-client.md#icinga2-remote-monitoring-master-discovery-blacklist-whitelist)
> to control which clients and hosts/services are integrated into your master configuration repository.

8
doc/11-agent-based-checks.md → doc/12-agent-based-checks.md
View File

@ -8,7 +8,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](13-addons-plugins.md#plugins)
the `check_snmp` plugin binary, but there are plenty of [existing plugins](14-addons-plugins.md#plugins)
for specific use cases already around, for example monitoring Cisco routers.
The following example uses the [SNMP ITL](7-icinga-template-library.md#plugin-check-command-snmp) `CheckCommand` and just
@ -67,7 +67,7 @@ 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](10-icinga2-client.md#icinga2-client)
> In order to stay safe, please use the native [Icinga 2 client](11-icinga2-client.md#icinga2-client)
> instead.
The NRPE daemon uses its own configuration format in nrpe.cfg while `check_nrpe`
@ -133,7 +133,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++](11-agent-based-checks.md#agent-based-checks-nsclient)
You can pass arguments in a similar manner to [NSClient++](12-agent-based-checks.md#agent-based-checks-nsclient)
when using its NRPE supported check method.
## <a id="agent-based-checks-nsclient"></a> NSClient++
@ -181,7 +181,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](22-appendix.md#external-commands-list-detail)
documentation and the Icinga external command syntax found [here](23-appendix.md#external-commands-list-detail)
we can create generic services that can accommodate any number of hosts for a given scenario.
### <a id="simple-traps"></a> Simple SNMP Traps

108
doc/12-distributed-monitoring-ha.md → doc/13-distributed-monitoring-ha.md
View File

@ -3,9 +3,9 @@
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](12-distributed-monitoring-ha.md#cluster-scenarios-high-availability). All instances in the `Zone` run as Active/Active cluster.
* [Distributed Zones](12-distributed-monitoring-ha.md#cluster-scenarios-distributed-zones). A master zone and one or more satellites in their zones.
* [Load Distribution](12-distributed-monitoring-ha.md#cluster-scenarios-load-distribution). A configuration master and multiple checker satellites.
* [High Availability](13-distributed-monitoring-ha.md#cluster-scenarios-high-availability). All instances in the `Zone` run as Active/Active cluster.
* [Distributed Zones](13-distributed-monitoring-ha.md#cluster-scenarios-distributed-zones). A master zone and one or more satellites in their zones.
* [Load Distribution](13-distributed-monitoring-ha.md#cluster-scenarios-load-distribution). A configuration master and multiple checker satellites.
You can combine these scenarios into a global setup fitting your requirements.
@ -19,19 +19,19 @@ is in effect - all alive instances continue to do their job, and history will be
Before you start deploying, keep the following things in mind:
* Your [SSL CA and certificates](12-distributed-monitoring-ha.md#manual-certificate-generation) are mandatory for secure communication
* Your [SSL CA and certificates](13-distributed-monitoring-ha.md#manual-certificate-generation) are mandatory for secure communication
* Get pen and paper or a drawing board and design your nodes and zones!
* all nodes in a cluster zone are providing high availability functionality and trust each other
* 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](12-distributed-monitoring-ha.md#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](13-distributed-monitoring-ha.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](16-troubleshooting.md#troubleshooting-cluster) section.
> [troubleshooting](17-troubleshooting.md#troubleshooting-cluster) section.
## <a id="manual-certificate-generation"></a> Manual SSL Certificate Generation
@ -114,7 +114,7 @@ The [Endpoint](6-object-types.md#objecttype-endpoint) name is further referenced
endpoints = [ "icinga2a", "icinga2b" ]
}
Specifying the local node name using the [NodeName](12-distributed-monitoring-ha.md#configure-nodename) variable requires
Specifying the local node name using the [NodeName](13-distributed-monitoring-ha.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"
@ -125,19 +125,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](12-distributed-monitoring-ha.md#configure-nodename)
* [configure the ApiListener object](12-distributed-monitoring-ha.md#configure-apilistener-object)
* [configure cluster endpoints](12-distributed-monitoring-ha.md#configure-cluster-endpoints)
* [configure cluster zones](12-distributed-monitoring-ha.md#configure-cluster-zones)
* [configure the node name](13-distributed-monitoring-ha.md#configure-nodename)
* [configure the ApiListener object](13-distributed-monitoring-ha.md#configure-apilistener-object)
* [configure cluster endpoints](13-distributed-monitoring-ha.md#configure-cluster-endpoints)
* [configure cluster zones](13-distributed-monitoring-ha.md#configure-cluster-zones)
Once you're finished with the basic setup the following section will
describe how to use [zone configuration synchronisation](12-distributed-monitoring-ha.md#cluster-zone-config-sync)
and configure [cluster scenarios](12-distributed-monitoring-ha.md#cluster-scenarios).
describe how to use [zone configuration synchronisation](13-distributed-monitoring-ha.md#cluster-zone-config-sync)
and configure [cluster scenarios](13-distributed-monitoring-ha.md#cluster-scenarios).
### <a id="configure-nodename"></a> Configure the Icinga Node Name
Instead of using the default FQDN as node name you can optionally set
that value using the [NodeName](19-language-reference.md#constants) constant.
that value using the [NodeName](20-language-reference.md#constants) constant.
> ** Note **
>
@ -147,7 +147,7 @@ that value using the [NodeName](19-language-reference.md#constants) constant.
This setting must be unique for each node, and must also match
the name of the local [Endpoint](6-object-types.md#objecttype-endpoint) object and the
SSL certificate common name as described in the
[cluster naming convention](12-distributed-monitoring-ha.md#cluster-naming-convention).
[cluster naming convention](13-distributed-monitoring-ha.md#cluster-naming-convention).
vim /etc/icinga2/constants.conf
@ -157,7 +157,7 @@ SSL certificate common name as described in the
const NodeName = "icinga2a"
Read further about additional [naming conventions](12-distributed-monitoring-ha.md#cluster-naming-convention).
Read further about additional [naming conventions](13-distributed-monitoring-ha.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.
@ -184,7 +184,7 @@ You can simply enable the `api` feature using
Edit `/etc/icinga2/features-enabled/api.conf` if you require the configuration
synchronisation enabled for this node. Set the `accept_config` attribute to `true`.
If you want to use this node as [remote client for command execution](10-icinga2-client.md#icinga2-client-configuration-command-bridge)
If you want to use this node as [remote client for command execution](11-icinga2-client.md#icinga2-client-configuration-command-bridge)
set the `accept_commands` attribute to `true`.
> **Note**
@ -221,10 +221,10 @@ all instances and point-of-view dependant.
`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](12-distributed-monitoring-ha.md#cluster-scenarios-high-availability),
[distributed setups](12-distributed-monitoring-ha.md#cluster-scenarios-distributed-zones) and
[load distribution](12-distributed-monitoring-ha.md#cluster-scenarios-load-distribution).
Furthermore zones are used for the [Icinga 2 remote client](10-icinga2-client.md#icinga2-client).
Zones can be used for [high availability](13-distributed-monitoring-ha.md#cluster-scenarios-high-availability),
[distributed setups](13-distributed-monitoring-ha.md#cluster-scenarios-distributed-zones) and
[load distribution](13-distributed-monitoring-ha.md#cluster-scenarios-load-distribution).
Furthermore zones are used for the [Icinga 2 remote client](11-icinga2-client.md#icinga2-client).
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
@ -259,7 +259,7 @@ 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](12-distributed-monitoring-ha.md#configure-apilistener-object) object by configuring the `accept_config`
[ApiListener](13-distributed-monitoring-ha.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`
@ -272,11 +272,11 @@ if not used).
Better use a dedicated directory name for local configuration like `local` 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](12-distributed-monitoring-ha.md#cluster-health-check) for example.
useful for local [health checks](13-distributed-monitoring-ha.md#cluster-health-check) for example.
> **Note**
>
> In a [high availability](12-distributed-monitoring-ha.md#cluster-scenarios-high-availability)
> In a [high availability](13-distributed-monitoring-ha.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.
@ -286,7 +286,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](12-distributed-monitoring-ha.md#configure-apilistener-object) object.
attribute of the [ApiListener](13-distributed-monitoring-ha.md#configure-apilistener-object) object.
Config on node `icinga2a`:
@ -327,7 +327,7 @@ process.
>
> `zones.d` must not be included in [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf). Icinga 2 automatically
> determines the required include directory. This can be overridden using the
> [global constant](19-language-reference.md#constants) `ZonesDir`.
> [global constant](20-language-reference.md#constants) `ZonesDir`.
### <a id="zone-global-config-templates"></a> Global Configuration Zone for Templates
@ -387,7 +387,7 @@ master instances anymore.
> ** Tip **
>
> Look into the [troubleshooting guides](16-troubleshooting.md#troubleshooting-cluster-config-sync) for debugging
> Look into the [troubleshooting guides](17-troubleshooting.md#troubleshooting-cluster-config-sync) for debugging
> problems with the configuration synchronisation.
@ -396,9 +396,9 @@ master instances anymore.
The configuration synchronisation works with multiple hierarchies. The following example
illustrate a quite common setup where the master is reponsible for configuration deployment:
* [High-Availability master zone](12-distributed-monitoring-ha.md#distributed-monitoring-high-availability)
* [High-Availability master zone](13-distributed-monitoring-ha.md#distributed-monitoring-high-availability)
* [Distributed satellites](12-distributed-monitoring-ha.md#)
* [Remote clients](10-icinga2-client.md#icinga2-client-scenarios) connected to the satellite
* [Remote clients](11-icinga2-client.md#icinga2-client-scenarios) connected to the satellite
While you could use the clients with local configuration and service discovery on the satellite/master
**bottom up**, the configuration sync could be more reasonable working **top-down** in a cascaded scenario.
@ -408,7 +408,7 @@ Once you've added them to your zones.conf as connection and permission configura
the actual configuration organization:
* Ensure that `command` object definitions are globally available. That way you can use the
`command_endpoint` configuration more easily on clients as [command execution bridge](10-icinga2-client.md#icinga2-client-configuration-command-bridge)
`command_endpoint` configuration more easily on clients as [command execution bridge](11-icinga2-client.md#icinga2-client-configuration-command-bridge)
* Generic `Templates`, `timeperiods`, `downtimes` should be synchronized in a global zone as well.
* [Apply rules](3-monitoring-basics.md#using-apply) can be synchronized globally. Keep in mind that they are evaluated on each instance,
and might require additional filters (e.g. `match("icinga2*", NodeName) or similar based on the zone information.
@ -455,7 +455,7 @@ are unsure about the best method, join the [support channels](1-about.md#support
with the community.
If you are planning to synchronize local service health checks inside a zone, look into the
[command endpoint](12-distributed-monitoring-ha.md#cluster-health-check-command-endpoint)
[command endpoint](13-distributed-monitoring-ha.md#cluster-health-check-command-endpoint)
explainations.
@ -507,14 +507,14 @@ If you are planning to sync the zone configuration inside a [High-Availability](
cluster zone, you can also use the `command_endpoint` object attribute to
pin host/service checks to a specific endpoint inside the same zone.
This requires the `accept_commands` setting inside the [ApiListener](12-distributed-monitoring-ha.md#configure-apilistener-object)
object set to `true` similar to the [remote client command execution bridge](10-icinga2-client.md#icinga2-client-configuration-command-bridge)
This requires the `accept_commands` setting inside the [ApiListener](13-distributed-monitoring-ha.md#configure-apilistener-object)
object set to `true` similar to the [remote client command execution bridge](11-icinga2-client.md#icinga2-client-configuration-command-bridge)
setup.
Make sure to set `command_endpoint` to the correct endpoint instance.
The example below assumes that the endpoint name is the same as the
host name configured for health checks. If it differs, define a host
custom attribute providing [this information](10-icinga2-client.md#icinga2-client-configuration-command-bridge-master-config).
custom attribute providing [this information](11-icinga2-client.md#icinga2-client-configuration-command-bridge-master-config).
apply Service "cluster-ha" {
check_command = "cluster"
@ -566,11 +566,11 @@ While there are certain capabilities to ensure the safe communication between al
nodes (firewalls, policies, software hardening, etc) the Icinga 2 cluster also provides
additional security itself:
* [SSL certificates](12-distributed-monitoring-ha.md#manual-certificate-generation) are mandatory for cluster communication.
* [SSL certificates](13-distributed-monitoring-ha.md#manual-certificate-generation) are mandatory for cluster communication.
* 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](12-distributed-monitoring-ha.md#zone-config-sync-permissions) is disabled by default.
* [Configuration sync](13-distributed-monitoring-ha.md#zone-config-sync-permissions) is disabled by default.
### <a id="cluster-scenarios-features"></a> Features in Cluster Zones
@ -582,8 +582,8 @@ actual slave checker node.
> **Note**
>
> All features must be same on all endpoints inside an [HA zone](12-distributed-monitoring-ha.md#cluster-scenarios-high-availability).
> There are additional [High-Availability-enabled features](12-distributed-monitoring-ha.md#high-availability-features) available.
> All features must be same on all endpoints inside an [HA zone](13-distributed-monitoring-ha.md#cluster-scenarios-high-availability).
> There are additional [High-Availability-enabled features](13-distributed-monitoring-ha.md#high-availability-features) available.
### <a id="cluster-scenarios-distributed-zones"></a> Distributed Zones
@ -598,7 +598,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](12-distributed-monitoring-ha.md#zone-global-config-templates) available in all zones.
[global templates](13-distributed-monitoring-ha.md#zone-global-config-templates) available in all zones.
The configuration tree on the master instance `nuremberg` could look like this:
@ -662,7 +662,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](12-distributed-monitoring-ha.md#zone-config-sync-permissions).
> [accepts synced configuration](13-distributed-monitoring-ha.md#zone-config-sync-permissions).
### <a id="cluster-scenarios-load-distribution"></a> Load Distribution
@ -721,15 +721,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](12-distributed-monitoring-ha.md#zone-config-sync-permissions).
> [accepts synced configuration](13-distributed-monitoring-ha.md#zone-config-sync-permissions).
### <a id="cluster-scenarios-high-availability"></a> Cluster High Availability
High availability with Icinga 2 is possible by putting multiple nodes into
a dedicated [zone](12-distributed-monitoring-ha.md#configure-cluster-zones). All nodes will elect one
a dedicated [zone](13-distributed-monitoring-ha.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](12-distributed-monitoring-ha.md#high-availability-features).
Selected features provide advanced [HA functionality](13-distributed-monitoring-ha.md#high-availability-features).
Checks and notifications are load-balanced between nodes in the high availability
zone.
@ -741,15 +741,15 @@ commands, etc.
endpoints = [ "icinga2a", "icinga2b", "icinga2c" ]
}
Two or more nodes in a high availability setup require an [initial cluster sync](12-distributed-monitoring-ha.md#initial-cluster-sync).
Two or more nodes in a high availability setup require an [initial cluster sync](13-distributed-monitoring-ha.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](12-distributed-monitoring-ha.md#zone-config-sync-permissions).
> Details in the [Configuration Sync Chapter](12-distributed-monitoring-ha.md#cluster-zone-config-sync).
> [accept synced configuration](13-distributed-monitoring-ha.md#zone-config-sync-permissions).
> Details in the [Configuration Sync Chapter](13-distributed-monitoring-ha.md#cluster-zone-config-sync).
### <a id="cluster-scenarios-multiple-hierarchies"></a> Multiple Hierarchies
@ -783,9 +783,9 @@ amongst them.
By default the following features provide advanced HA functionality:
* [Checks](12-distributed-monitoring-ha.md#high-availability-checks) (load balanced, automated failover)
* [Notifications](12-distributed-monitoring-ha.md#high-availability-notifications) (load balanced, automated failover)
* [DB IDO](12-distributed-monitoring-ha.md#high-availability-db-ido) (Run-Once, automated failover)
* [Checks](13-distributed-monitoring-ha.md#high-availability-checks) (load balanced, automated failover)
* [Notifications](13-distributed-monitoring-ha.md#high-availability-notifications) (load balanced, automated failover)
* [DB IDO](13-distributed-monitoring-ha.md#high-availability-db-ido) (Run-Once, automated failover)
### <a id="high-availability-checks"></a> High Availability with Checks
@ -859,13 +859,13 @@ data duplication in split-brain-scenarios. The failover timeout can be set for t
These steps are required for integrating a new cluster endpoint:
* generate a new [SSL client certificate](12-distributed-monitoring-ha.md#manual-certificate-generation)
* generate a new [SSL client certificate](13-distributed-monitoring-ha.md#manual-certificate-generation)
* identify its location in the zones
* update the `zones.conf` file on each involved node ([endpoint](12-distributed-monitoring-ha.md#configure-cluster-endpoints), [zones](12-distributed-monitoring-ha.md#configure-cluster-zones))
* update the `zones.conf` file on each involved node ([endpoint](13-distributed-monitoring-ha.md#configure-cluster-endpoints), [zones](13-distributed-monitoring-ha.md#configure-cluster-zones))
* a new slave zone node requires updates for the master and slave zones
* verify if this endpoints requires [configuration synchronisation](12-distributed-monitoring-ha.md#cluster-zone-config-sync) enabled
* if the node requires the existing zone history: [initial cluster sync](12-distributed-monitoring-ha.md#initial-cluster-sync)
* add a [cluster health check](12-distributed-monitoring-ha.md#cluster-health-check)
* verify if this endpoints requires [configuration synchronisation](13-distributed-monitoring-ha.md#cluster-zone-config-sync) enabled
* if the node requires the existing zone history: [initial cluster sync](13-distributed-monitoring-ha.md#initial-cluster-sync)
* add a [cluster health check](13-distributed-monitoring-ha.md#cluster-health-check)
### <a id="initial-cluster-sync"></a> Initial Cluster Sync

4
doc/13-addons-plugins.md → doc/14-addons-plugins.md
View File

@ -29,8 +29,8 @@ Set `perfdata_spool_dir = /var/spool/icinga2/perfdata` and restart the `npcd` da
There's also an Icinga Web 2 module for direct PNP graph integration
available at https://exchange.icinga.org/icinga/PNP4Nagios
More information on [action_url as attribute](13-addons-plugins.md#addons-graphing-pnp-action-url)
and [graph template names](13-addons-plugins.md#addons-graphing-pnp-custom-templates).
More information on [action_url as attribute](14-addons-plugins.md#addons-graphing-pnp-action-url)
and [graph template names](14-addons-plugins.md#addons-graphing-pnp-custom-templates).
### <a id="addons-graphing-graphite"></a> Graphite

2
doc/14-alternative-frontends.md → doc/15-alternative-frontends.md
View File

@ -157,7 +157,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](14-alternative-frontends.md#icinga-web-rpm-notes):
> the configuration manually as shown in [the RPM notes](15-alternative-frontends.md#icinga-web-rpm-notes):
>
> `apt-get install --no-install-recommends icinga-web`

8
doc/15-livestatus.md → doc/16-livestatus.md
View File

@ -8,7 +8,7 @@ status information. It can also be used to send commands.
>
> 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](14-alternative-frontends.md#setting-up-icinga-classic-ui) and [Icinga Web](14-alternative-frontends.md#setting-up-icinga-web)
> [Icinga Classic UI](15-alternative-frontends.md#setting-up-icinga-classic-ui) and [Icinga Web](15-alternative-frontends.md#setting-up-icinga-web)
> do not use Livestatus as backend.
The Livestatus component that is distributed as part of Icinga 2 is a
@ -16,7 +16,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 Schema](22-appendix.md#schema-livestatus) section.
in the [Livestatus Schema](23-appendix.md#schema-livestatus) section.
You can enable Livestatus using icinga2 feature enable:
@ -92,7 +92,7 @@ Example using the tcp socket listening on port `6558`:
### <a id="livestatus-command-queries"></a> Livestatus COMMAND Queries
A list of available external commands and their parameters can be found [here](22-appendix.md#external-commands-list-detail)
A list of available external commands and their parameters can be found [here](23-appendix.md#external-commands-list-detail)
$ echo -e 'COMMAND <externalcommandstring>' | netcat 127.0.0.1 6558
@ -193,5 +193,5 @@ Default separators.
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](22-appendix.md#schema-livestatus).
A detailed list on the available table attributes can be found in the [Livestatus Schema documentation](23-appendix.md#schema-livestatus).

36
doc/16-troubleshooting.md → doc/17-troubleshooting.md
View File

@ -13,7 +13,7 @@
* How was Icinga 2 installed (and which repository in case) and which distribution are you using
* Provide complete configuration snippets explaining your problem in detail
* If the check command failed - what's the output of your manual plugin tests?
* In case of [debugging](21-debug.md#debug) Icinga 2, the full back traces and outputs
* In case of [debugging](22-debug.md#debug) Icinga 2, the full back traces and outputs
## <a id="troubleshooting-enable-debug-output"></a> Enable Debug Output
@ -37,7 +37,7 @@ and `debug`.
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](19-language-reference.md#apply).
That way you can also identify which objects have been created from your [apply rules](20-language-reference.md#apply).
# icinga2 object list
@ -157,13 +157,13 @@ to `features-enabled` and that the latter is included in [icinga2.conf](4-config
## <a id="configuration-ignored"></a> Configuration is ignored
* Make sure that the line(s) are not [commented out](19-language-reference.md#comments) (starting with `//` or `#`, or
* Make sure that the line(s) are not [commented out](20-language-reference.md#comments) (starting with `//` or `#`, or
encapsulated by `/* ... */`).
* Is the configuration file included in [icinga2.conf](4-configuring-icinga-2.md#icinga2-conf)?
## <a id="configuration-attribute-inheritance"></a> Configuration attributes are inherited from
Icinga 2 allows you to import templates using the [import](19-language-reference.md#template-imports) keyword. If these templates
Icinga 2 allows you to import templates using the [import](20-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.
@ -171,10 +171,10 @@ or modify these attributes in the current object.
This applies to anything using the cluster protocol:
* [Distributed and High-Availability](12-distributed-monitoring-ha.md#distributed-monitoring-high-availability) scenarios
* [Remote client](10-icinga2-client.md#icinga2-client-scenarios) scenarios
* [Distributed and High-Availability](13-distributed-monitoring-ha.md#distributed-monitoring-high-availability) scenarios
* [Remote client](11-icinga2-client.md#icinga2-client-scenarios) scenarios
You should configure the [cluster health checks](12-distributed-monitoring-ha.md#cluster-health-check) if you haven't
You should configure the [cluster health checks](13-distributed-monitoring-ha.md#cluster-health-check) if you haven't
done so already.
> **Note**
@ -240,12 +240,12 @@ Try to manually connect from `icinga2-node2.localdomain` to the master node `ici
---
...
If the connection attempt fails or your CA does not match, [verify the master and client certificates](16-troubleshooting.md#troubleshooting-cluster-ssl-certificate-verification).
If the connection attempt fails or your CA does not match, [verify the master and client certificates](17-troubleshooting.md#troubleshooting-cluster-ssl-certificate-verification).
#### <a id="troubleshooting-cluster-unauthenticated-clients"></a> Cluster Troubleshooting Unauthenticated Clients
Unauthenticated nodes are able to connect required by the
[CSR auto-signing](10-icinga2-client.md#csr-autosigning-requirements) functionality.
[CSR auto-signing](11-icinga2-client.md#csr-autosigning-requirements) functionality.
Master:
@ -255,7 +255,7 @@ Client as command execution bridge:
[2015-07-13 18:29:26 +1000] notice/ApiEvents: Discarding 'execute command' message from 'icinga-master': Invalid endpoint origin (client not allowed).
If these messages do not go away, make sure to [verify the master and client certificates](16-troubleshooting.md#troubleshooting-cluster-ssl-certificate-verification).
If these messages do not go away, make sure to [verify the master and client certificates](17-troubleshooting.md#troubleshooting-cluster-ssl-certificate-verification).
#### <a id="troubleshooting-cluster-ssl-certificate-verification"></a> Cluster Troubleshooting SSL Certificate Verification
@ -281,24 +281,24 @@ At some point, when the network connection is broken or gone, the Icinga 2 insta
will be disconnected. If the connection can't be re-established between zones and endpoints,
they remain in a Split-Brain-mode and history may differ.
Although the Icinga 2 cluster protocol stores historical events in a [replay log](16-troubleshooting.md#troubleshooting-cluster-replay-log)
Although the Icinga 2 cluster protocol stores historical events in a [replay log](17-troubleshooting.md#troubleshooting-cluster-replay-log)
for later synchronisation, you should make sure to check why the network connection failed.
### <a id="troubleshooting-cluster-command-endpoint-errors"></a> Cluster Troubleshooting Command Endpoint Errors
Command endpoints can be used for clients acting as [remote command execution bridge](10-icinga2-client.md#icinga2-client-configuration-command-bridge)
as well as inside an [High-Availability cluster](12-distributed-monitoring-ha.md#distributed-monitoring-high-availability).
Command endpoints can be used for clients acting as [remote command execution bridge](11-icinga2-client.md#icinga2-client-configuration-command-bridge)
as well as inside an [High-Availability cluster](13-distributed-monitoring-ha.md#distributed-monitoring-high-availability).
There is no cli command for manually executing the check, but you can verify
the following (e.g. by invoking a forced check from the web interface):
* `/var/log/icinga2/icinga2.log` contains connection and execution errors.
* The ApiListener is not enabled to [accept commands](10-icinga2-client.md#clients-as-command-execution-bridge).
* The ApiListener is not enabled to [accept commands](#clients-as-command-execution-bridge).
* `CheckCommand` definition not found on the remote client.
* Referenced check plugin not found on the remote client.
* Runtime warnings and errors, e.g. unresolved runtime macros or configuration problems.
* Specific error messages are also populated into `UNKNOWN` check results including a detailed error message in their output.
* More verbose logs are found inside the [debug log](16-troubleshooting.md#troubleshooting-enable-debug-output).
* More verbose logs are found inside the [debug log](17-troubleshooting.md#troubleshooting-enable-debug-output).
### <a id="troubleshooting-cluster-config-sync"></a> Cluster Troubleshooting Config Sync
@ -308,7 +308,7 @@ If the cluster zones do not sync their configuration, make sure to check the fol
** 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 in `/var/log/icinga2` will indicate whether this ApiListener
[accepts config](12-distributed-monitoring-ha.md#zone-config-sync-permissions), or not.
[accepts config](13-distributed-monitoring-ha.md#zone-config-sync-permissions), or not.
### <a id="troubleshooting-cluster-replay-log"></a> Cluster Troubleshooting Replay Log
@ -317,7 +317,7 @@ cannot replay the log on connection loss and re-establishment.
Check the following:
* All clients are connected? (e.g. [cluster health check](12-distributed-monitoring-ha.md#cluster-health-check)).
* Check your [connection](16-troubleshooting.md#troubleshooting-cluster-connection-errors) in general.
* All clients are connected? (e.g. [cluster health check](13-distributed-monitoring-ha.md#cluster-health-check)).
* Check your [connection](17-troubleshooting.md#troubleshooting-cluster-connection-errors) in general.
* Does the log replay work, e.g. are all events processed and the directory gets cleared up over time?
* Decrease the `log_duration` attribute value for that specific [endpoint](6-object-types.md#objecttype-endpoint).

0
doc/17-upgrading-icinga-2.md → doc/18-upgrading-icinga-2.md
View File

32
doc/18-migrating-from-icinga-1x.md → doc/19-migrating-from-icinga-1x.md
View File

@ -29,7 +29,7 @@ object specific policies.
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](18-migrating-from-icinga-1x.md#differences-1x-2) to find out more about the differences
Please read the [next chapter](19-migrating-from-icinga-1x.md#differences-1x-2) to find out more about the differences
between 1.x and 2.
### <a id="manual-config-migration-hints"></a> Manual Config Migration Hints
@ -42,7 +42,7 @@ The examples are taken from Icinga 1.x test and production environments and conv
straight into a possible Icinga 2 format. If you found a different strategy, please
let us know!
If you require in-depth explanations, please check the [next chapter](18-migrating-from-icinga-1x.md#differences-1x-2).
If you require in-depth explanations, please check the [next chapter](19-migrating-from-icinga-1x.md#differences-1x-2).
#### <a id="manual-config-migration-hints-Intervals"></a> Manual Config Migration Hints for Intervals
@ -129,7 +129,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](19-language-reference.md#group-assign). The additional nested hostgroup
This can be migrated to Icinga 2 and [using group assign](20-language-reference.md#group-assign). The additional nested hostgroup
`hg1` is included into `hg2` with the `groups` attribute.
@ -205,7 +205,7 @@ While you could manually migrate this like (please note the new generic command
#### <a id="manual-config-migration-hints-runtime-macros"></a> Manual Config Migration Hints for Runtime Macros
Runtime macros have been renamed. A detailed comparison table can be found [here](18-migrating-from-icinga-1x.md#differences-1x-2-runtime-macros).
Runtime macros have been renamed. A detailed comparison table can be found [here](19-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:
@ -278,7 +278,7 @@ while the service check command resolves its value to the service attribute attr
#### <a id="manual-config-migration-hints-contacts-users"></a> 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](18-migrating-from-icinga-1x.md#manual-config-migration-hints-notifications).
This migration part is explained in the [next chapter](19-migrating-from-icinga-1x.md#manual-config-migration-hints-notifications).
define contact{
contact_name testconfig-user
@ -288,7 +288,7 @@ This migration part is explained in the [next chapter](18-migrating-from-icinga-
email icinga@localhost
}
The `service_notification_options` can be [mapped](18-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters)
The `service_notification_options` can be [mapped](19-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`.
@ -340,7 +340,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](18-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters). Add the notification period.
[here](19-migrating-from-icinga-1x.md#manual-config-migration-hints-notification-filters). Add the notification period.
states = [ OK, Warning, Critical ]
types = [ Recovery, Problem, Custom ]
@ -577,7 +577,7 @@ enabled.
assign where "hg_svcdep2" in host.groups
}
Host dependencies are explained in the [next chapter](18-migrating-from-icinga-1x.md#manual-config-migration-hints-host-parents).
Host dependencies are explained in the [next chapter](19-migrating-from-icinga-1x.md#manual-config-migration-hints-host-parents).
@ -681,9 +681,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](12-distributed-monitoring-ha.md#cluster-scenarios-load-distribution) setup with Icinga 2.
building a [load distribution](13-distributed-monitoring-ha.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](12-distributed-monitoring-ha.md#cluster-scenarios-high-availability) setup.
consider the [High Availability](13-distributed-monitoring-ha.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.
@ -744,7 +744,7 @@ included in `icinga2.conf` by default.
### <a id="differences-1x-2-main-config"></a> 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](19-language-reference.md#constants) allowing
Icinga 2 only uses a small set of [global constants](20-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](4-configuring-icinga-2.md#icinga2-conf) should take care of including
@ -797,7 +797,7 @@ set in the `constants.conf` configuration file:
const PluginDir = "/usr/lib/nagios/plugins"
[Global macros](19-language-reference.md#constants) can only be defined once. Trying to modify a
[Global macros](20-language-reference.md#constants) can only be defined once. Trying to modify a
global constant will result in an error.
### <a id="differences-1x-2-configuration-comments"></a> Configuration Comments
@ -948,7 +948,7 @@ In Icinga 1.x arguments are specified in the `check_command` attribute and
are separated from the command name using an exclamation mark (`!`).
Please check the migration hints for a detailed
[migration example](18-migrating-from-icinga-1x.md#manual-config-migration-hints-check-command-arguments).
[migration example](19-migrating-from-icinga-1x.md#manual-config-migration-hints-check-command-arguments).
> **Note**
>
@ -1340,7 +1340,7 @@ child attributes may be omitted.
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](19-language-reference.md#apply).
Dependencies can be applied to hosts or services using the [apply rules](20-language-reference.md#apply).
The `StatusDataWriter`, `IdoMysqlConnection` and `LivestatusListener` types
support the Icinga 1.x schema with dependencies and parent attributes for
@ -1391,7 +1391,7 @@ execution during config validation:
* 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](12-distributed-monitoring-ha.md#cluster-zone-config-sync))
(this is **essential** for the [cluster config synchronisation](13-distributed-monitoring-ha.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
@ -1448,7 +1448,7 @@ not synced between the master and slave nodes. There are addons available solvin
and configuration distribution problems Icinga 1.x distributed monitoring currently suffers from.
Icinga 2 implements a new built-in
[distributed monitoring architecture](12-distributed-monitoring-ha.md#distributed-monitoring-high-availability),
[distributed monitoring architecture](13-distributed-monitoring-ha.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 feature, next to local replay
logs on connection loss ensuring that the event history is kept in sync.

6
doc/2-getting-started.md
View File

@ -161,7 +161,7 @@ update the global `PluginDir` constant in your [Icinga 2 configuration](4-config
This constant is used by the check command definitions contained in the Icinga Template Library
to determine where to find the plugin binaries.
Please refer to the [plugins](13-addons-plugins.md#plugins) chapter for details about how to integrate
Please refer to the [plugins](14-addons-plugins.md#plugins) chapter for details about how to integrate
additional check plugins into your Icinga 2 setup.
## <a id="running-icinga2"></a> Running Icinga 2
@ -284,7 +284,7 @@ Test it:
Icinga 2 can be used with Icinga Web 2 and a number of other web interfaces.
This chapter explains how to set up Icinga Web 2. The
[Alternative Frontends](14-alternative-frontends.md#alternative-frontends)
[Alternative Frontends](15-alternative-frontends.md#alternative-frontends)
chapter can be used as a starting point for installing some of the other web
interfaces which are also available.
@ -595,4 +595,4 @@ for further instructions on how to install Icinga Web 2.
A number of additional features are available in the form of addons. A list of
popular addons is available in the
[Addons and Plugins](13-addons-plugins.md#addons-plugins) chapter.
[Addons and Plugins](14-addons-plugins.md#addons-plugins) chapter.

8
doc/19-language-reference.md → doc/20-language-reference.md
View File

@ -199,7 +199,7 @@ Functions can be called using the `()` operator:
check_interval = len(MyGroups) * 1m
}
A list of available functions is available in the [Library Reference](20-library-reference.md#library-reference) chapter.
A list of available functions is available in the [Library Reference](21-library-reference.md#library-reference) chapter.
## <a id="dictionary-operators"></a> Assignments
@ -394,7 +394,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](19-language-reference.md#expression-operators)
is created for each matching host. [Expression operators](20-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
@ -431,7 +431,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](19-language-reference.md#expression-operators) may be used in `assign where` and
condition. [Expression operators](20-language-reference.md#expression-operators) may be used in `assign where` and
`ignore where` conditions.
Source Type | Variables
@ -460,7 +460,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](19-language-reference.md#expression-operators).
statements, see [expression operators](20-language-reference.md#expression-operators).
## <a id="comments"></a> Comments

2
doc/20-library-reference.md → doc/21-library-reference.md
View File

@ -411,7 +411,7 @@ Signature:
function contains(str);
Returns `true` if the string `str` was found in the string. If the string
was not found `false` is returned. Use [find](20-library-reference.md#string-find)
was not found `false` is returned. Use [find](21-library-reference.md#string-find)
for getting the index instead.
Example:

0
doc/21-debug.md → doc/22-debug.md
View File

0
doc/22-appendix.md → doc/23-appendix.md
View File

34
doc/3-monitoring-basics.md
View File

@ -46,7 +46,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](16-troubleshooting.md#troubleshooting).
Details on troubleshooting check problems can be found [here](17-troubleshooting.md#troubleshooting).
### <a id="host-states"></a> Host States
@ -152,13 +152,13 @@ In addition to built-in attributes you can define your own attributes:
Valid values for custom attributes include:
* [Strings](19-language-reference.md#string-literals), [numbers](19-language-reference.md#numeric-literals) and [booleans](19-language-reference.md#boolean-literals)
* [Arrays](19-language-reference.md#array) and [dictionaries](19-language-reference.md#dictionary)
* [Strings](20-language-reference.md#string-literals), [numbers](20-language-reference.md#numeric-literals) and [booleans](20-language-reference.md#boolean-literals)
* [Arrays](20-language-reference.md#array) and [dictionaries](20-language-reference.md#dictionary)
* [Functions](3-monitoring-basics.md#custom-attributes-functions)
### <a id="custom-attributes-functions"></a> Functions as Custom Attributes
Icinga 2 lets you specify [functions](19-language-reference.md#functions) for custom attributes.
Icinga 2 lets you specify [functions](20-language-reference.md#functions) for custom attributes.
The special case here is that whenever Icinga 2 needs the value for such a custom attribute it runs
the function and uses whatever value the function returns:
@ -170,7 +170,7 @@ the function and uses whatever value the function returns:
vars.text = {{ Math.random() * 100 }}
}
This example uses the [abbreviated lambda syntax](19-language-reference.md#nullary-lambdas).
This example uses the [abbreviated lambda syntax](20-language-reference.md#nullary-lambdas).
These functions have access to a number of variables:
@ -425,15 +425,15 @@ The following macros provide global statistics:
Instead of assigning each object ([Service](6-object-types.md#objecttype-service),
[Notification](6-object-types.md#objecttype-notification), [Dependency](6-object-types.md#objecttype-dependency),
[ScheduledDowntime](6-object-types.md#objecttype-scheduleddowntime))
based on attribute identifiers for example `host_name` objects can be [applied](19-language-reference.md#apply).
based on attribute identifiers for example `host_name` objects can be [applied](20-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](3-monitoring-basics.md#custom-attributes) 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](19-language-reference.md#function-calls) on the host/service name?
* [Multiple expressions combined](3-monitoring-basics.md#using-apply-expressions) with `&&` or `||` [operators](19-language-reference.md#expression-operators)
* A generic pattern [match](20-language-reference.md#function-calls) on the host/service name?
* [Multiple expressions combined](3-monitoring-basics.md#using-apply-expressions) with `&&` or `||` [operators](20-language-reference.md#expression-operators)
* All expressions must return a boolean value (an empty string is equal to `false` e.g.)
> **Note**
@ -497,7 +497,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](19-language-reference.md#expression-operators) `2`.
`OR` the `priority` custom attribute is [less than](20-language-reference.md#expression-operators) `2`.
template Notification "cust-xy-notification" {
users = [ "noc-xy", "mgmt-xy" ]
@ -553,7 +553,7 @@ In this example the `mail-noc` notification will be created as object for all se
and all members of the user group `noc` will get notified.
It is also possible to generally apply a notification template and dynamically overwrite values from
the template by checking for custom attributes. This can be achieved by using [conditional statements](19-language-reference.md#conditional-statements):
the template by checking for custom attributes. This can be achieved by using [conditional statements](20-language-reference.md#conditional-statements):
apply Notification "host-mail-noc" to Host {
import "mail-host-notification"
@ -758,10 +758,10 @@ After `vars` is fully populated, all object attributes can be set calculated fro
provided host attributes. For strings, you can use string concatention with the `+` operator.
You can also specifiy the display_name, check command, interval, notes, notes_url, action_url, etc.
attributes that way. Attribute strings can be [concatenated](19-language-reference.md#expression-operators),
attributes that way. Attribute strings can be [concatenated](20-language-reference.md#expression-operators),
for example for adding a more detailed service `display_name`.
This example also uses [if conditions](19-language-reference.md#conditional-statements)
This example also uses [if conditions](20-language-reference.md#conditional-statements)
if specific values are not set, adding a local default value.
The other way around you can override specific custom attributes inherited from a service template,
if set.
@ -1000,7 +1000,7 @@ hosts or with the `test_server` attribute set to `true` are not added to this
group.
Details on the `assign where` syntax can be found in the
[Language Reference](19-language-reference.md#apply)
[Language Reference](20-language-reference.md#apply)
## <a id="notifications"></a> Notifications
@ -1015,7 +1015,7 @@ refining the notifications being actually sent.
There are many ways of sending notifications, e.g. by e-mail, XMPP,
IRC, Twitter, etc. On its own Icinga 2 does not know how to send notifications.
Instead it relies on external mechanisms such as shell scripts to notify users.
More notification methods are listed in the [addons and plugins](13-addons-plugins.md#notification-scripts-interfaces)
More notification methods are listed in the [addons and plugins](14-addons-plugins.md#notification-scripts-interfaces)
chapter.
A notification specification requires one or more users (and/or user groups)
@ -1036,7 +1036,7 @@ 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](16-troubleshooting.md#troubleshooting).
Details on troubleshooting notification problems can be found [here](17-troubleshooting.md#troubleshooting).
> **Note**
>
@ -1291,7 +1291,7 @@ Next step is to understand how [command parameters](3-monitoring-basics.md#comma
are being passed from a host or service object, and add a [CheckCommand](6-object-types.md#objecttype-checkcommand)
definition based on these required parameters and/or default values.
Please continue reading in the [plugins section](13-addons-plugins.md#plugins) for additional integration examples.
Please continue reading in the [plugins section](14-addons-plugins.md#plugins) for additional integration examples.
#### <a id="command-passing-parameters"></a> Passing Check Command Parameters from Host or Service
@ -1800,7 +1800,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](22-appendix.md#schema-db-ido-extensions).
in for example [DB IDO](23-appendix.md#schema-db-ido-extensions).
### <a id="dependencies-implicit-host-service"></a> Implicit Dependencies for Services on Host

24
doc/4-configuring-icinga-2.md
View File

@ -5,7 +5,7 @@ The configuration files which are automatically created when installing the Icin
are a good way to start with Icinga 2.
If you're interested in a detailed explanation of each language feature used in those
configuration files you can find more information in the [Language Reference](19-language-reference.md#language-reference)
configuration files you can find more information in the [Language Reference](20-language-reference.md#language-reference)
chapter.
## <a id="configuration-best-practice"></a> Configuration Best Practice
@ -17,7 +17,7 @@ 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 tool](13-addons-plugins.md#configuration-tools) such as Puppet, Chef, Ansible, etc.
* Generated by a [configuration management tool](14-addons-plugins.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.
@ -79,7 +79,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](19-language-reference.md#comments).
Icinga 2 supports [C/C++-style comments](20-language-reference.md#comments).
/**
* The constants.conf defines global constants.
@ -123,7 +123,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](10-icinga2-client.md#icinga2-remote-monitoring-master-discovery).
[this chapter](11-icinga2-client.md#icinga2-remote-monitoring-master-discovery).
/**
@ -293,13 +293,13 @@ host and your additional hosts are getting [services](4-configuring-icinga-2.md#
> **Tip**
>
> If you don't understand all the attributes and how to use [apply rules](19-language-reference.md#apply)
> If you don't understand all the attributes and how to use [apply rules](20-language-reference.md#apply)
> don't worry - the [monitoring basics](3-monitoring-basics.md#monitoring-basics) chapter will explain
> that in detail.
#### <a id="services-conf"></a> services.conf
These service [apply rules](19-language-reference.md#apply) will show you how to monitor
These service [apply rules](20-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.
@ -347,7 +347,7 @@ these services in [downtimes.conf](4-configuring-icinga-2.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](19-language-reference.md#expression-operators)
is created for each matching host. [Expression operators](20-language-reference.md#expression-operators)
may be used in `assign where` conditions.
Multiple `assign where` condition can be combined with `AND` using the `&&` operator
@ -365,7 +365,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](19-language-reference.md#expression-operators), for example
and `OR` using `&&` and `||` [operators](20-language-reference.md#expression-operators), for example
`assign where host.address && (vars.os == "Linux" || vars.os == "Windows")`.
@ -513,7 +513,7 @@ 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](19-language-reference.md#group-assign) expressions similar
This is done by using the [group assign](20-language-reference.md#group-assign) expressions similar
to previously seen [apply rules](3-monitoring-basics.md#using-apply).
object HostGroup "linux-servers" {
@ -529,7 +529,7 @@ to previously seen [apply rules](3-monitoring-basics.md#using-apply).
}
Service groups can be grouped together by similar pattern matches.
The [match() function](19-language-reference.md#function-calls) expects a wildcard match string
The [match() function](20-language-reference.md#function-calls) expects a wildcard match string
and the attribute string to match with.
object ServiceGroup "ping" {
@ -635,9 +635,9 @@ objects such as hosts, services or notifications.
#### <a id="satellite-conf"></a> satellite.conf
Includes default templates and dependencies for
[monitoring remote clients](10-icinga2-client.md#icinga2-client)
[monitoring remote clients](11-icinga2-client.md#icinga2-client)
using service discovery and
[config generation](10-icinga2-client.md#icinga2-remote-monitoring-master-discovery)
[config generation](11-icinga2-client.md#icinga2-remote-monitoring-master-discovery)
on the master. Can be ignored/removed on setups not using this features.

22
doc/5-advanced-topics.md
View File

@ -226,7 +226,7 @@ The other way around you can create objects dynamically using your own global fu
Tips when implementing functions:
* Use [log()](20-library-reference.md#global-functions) to dump variables. You can see the output
* Use [log()](21-library-reference.md#global-functions) to dump variables. You can see the output
inside the `icinga2.log` file depending in your log severity
* Use the `icinga2 console` to test basic functionality (e.g. iterating over a dictionary)
* Build them step-by-step. You can always refactor your code later on.
@ -255,7 +255,7 @@ dictionary named `compellent` with the key `disks`. This was then used inside se
The more significant problem was to only add the command parameter `--disk` to the plugin call
when the dictionary `compellent` contains the key `disks`, and omit it if not found.
By defining `set_if` as [abbreviated lambda function](19-language-reference.md#nullary-lambdas)
By defining `set_if` as [abbreviated lambda function](20-language-reference.md#nullary-lambdas)
and evaluating the host custom attribute `compellent` containing the `disks` this problem was
solved like this:
@ -275,9 +275,9 @@ solved like this:
}
}
This implementation uses the dictionary type method [contains](20-library-reference.md#dictionary-contains)
This implementation uses the dictionary type method [contains](21-library-reference.md#dictionary-contains)
and will fail if `host.vars.compellent` is not of the type `Dictionary`.
Therefore you can extend the checks using the [typeof](19-language-reference.md#types) function.
Therefore you can extend the checks using the [typeof](20-language-reference.md#types) function.
You can test the types using the `icinga2 console`:
@ -370,7 +370,7 @@ You can omit the `log()` calls, they only help debugging.
## <a id="access-object-attributes-at-runtime"></a> Access Object Attributes at Runtime
The [Object Accessor Functions](20-library-reference.md#object-accessor-functions)
The [Object Accessor Functions](21-library-reference.md#object-accessor-functions)
can be used to retrieve references to other objects by name.
This allows you to access configuration and runtime object attributes. A detailed
@ -535,7 +535,7 @@ a forced service check:
Oct 17 15:01:25 icinga-server icinga2: Executing external command: [1382014885] SCHEDULE_FORCED_SVC_CHECK;localhost;ping4;1382014885
Oct 17 15:01:25 icinga-server icinga2: Rescheduling next check for service 'ping4'
A list of currently supported external commands can be found [here](22-appendix.md#external-commands-list-detail).
A list of currently supported external commands can be found [here](23-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).
@ -621,7 +621,7 @@ 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](3-monitoring-basics.md#runtime-macros) and a
[global constant](19-language-reference.md#constants) named `GraphiteEnv`. The constant name
[global constant](20-language-reference.md#constants) named `GraphiteEnv`. The constant name
is freely definable and should be put in the [constants.conf](4-configuring-icinga-2.md#constants-conf) file.
const GraphiteEnv = "icinga.env1"
@ -778,7 +778,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](15-livestatus.md#setting-up-livestatus) feature uses these logs for answering queries to
[Livestatus](16-livestatus.md#setting-up-livestatus) feature uses these logs for answering queries to
historical tables.
The `CompatLogger` object can be enabled with
@ -830,7 +830,7 @@ chapter. Details on the configuration can be found in the
[IdoMysqlConnection](6-object-types.md#objecttype-idomysqlconnection) and
[IdoPgsqlConnection](6-object-types.md#objecttype-idopgsqlconnection)
object configuration documentation.
The DB IDO feature supports [High Availability](12-distributed-monitoring-ha.md#high-availability-db-ido) in
The DB IDO feature supports [High Availability](13-distributed-monitoring-ha.md#high-availability-db-ido) in
the Icinga 2 cluster.
The following example query checks the health of the current Icinga 2 instance
@ -841,7 +841,7 @@ the query returns an empty result.
> **Tip**
>
> Use [check plugins](13-addons-plugins.md#plugins) to monitor the backend.
> Use [check plugins](14-addons-plugins.md#plugins) to monitor the backend.
Replace the `default` string with your instance name, if different.
@ -872,7 +872,7 @@ Example for PostgreSQL:
(1 Zeile)
A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](22-appendix.md#schema-db-ido).
A detailed list on the available table attributes can be found in the [DB IDO Schema documentation](23-appendix.md#schema-db-ido).
## <a id="check-result-files"></a> Check Result Files

18
doc/6-object-types.md
View File

@ -451,7 +451,7 @@ Configuration Attributes:
Metric prefix names can be modified using [runtime macros](3-monitoring-basics.md#runtime-macros).
Example with your custom [global constant](19-language-reference.md#constants) `GraphiteEnv`:
Example with your custom [global constant](20-language-reference.md#constants) `GraphiteEnv`:
const GraphiteEnv = "icinga.env1"
@ -541,7 +541,7 @@ A group of hosts.
> **Best Practice**
>
> Assign host group members using the [group assign](19-language-reference.md#group-assign) rules.
> Assign host group members using the [group assign](20-language-reference.md#group-assign) rules.
Example:
@ -617,8 +617,8 @@ Configuration 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](12-distributed-monitoring-ha.md#high-availability-db-ido). Defaults to "true".
failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](12-distributed-monitoring-ha.md#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](13-distributed-monitoring-ha.md#high-availability-db-ido). Defaults to "true".
failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](13-distributed-monitoring-ha.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.
@ -706,8 +706,8 @@ Configuration 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](12-distributed-monitoring-ha.md#high-availability-db-ido). Defaults to "true".
failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](12-distributed-monitoring-ha.md#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](13-distributed-monitoring-ha.md#high-availability-db-ido). Defaults to "true".
failover_timeout | **Optional.** Set the failover timeout in a [HA cluster](13-distributed-monitoring-ha.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.
@ -927,7 +927,7 @@ Configuration Attributes:
Name |Description
----------------|----------------
enable\_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](12-distributed-monitoring-ha.md#high-availability-notifications). Defaults to "true".
enable\_ha |**Optional.** Enable the high availability functionality. Only valid in a [cluster setup](13-distributed-monitoring-ha.md#high-availability-notifications). Defaults to "true".
## <a id="objecttype-opentsdbwriter"></a> OpenTsdbWriter
@ -1126,7 +1126,7 @@ A group of services.
> **Best Practice**
>
> Assign service group members using the [group assign](19-language-reference.md#group-assign) rules.
> Assign service group members using the [group assign](20-language-reference.md#group-assign) rules.
Example:
@ -1290,7 +1290,7 @@ A user group.
> **Best Practice**
>
> Assign user group members using the [group assign](19-language-reference.md#group-assign) rules.
> Assign user group members using the [group assign](20-language-reference.md#group-assign) rules.
Example:

20
doc/8-cli-commands.md
View File

@ -112,12 +112,12 @@ can be specified with the `--app` command-line option.
### Libraries
Instead of loading libraries using the [`library` config directive](19-language-reference.md#library)
Instead of loading libraries using the [`library` config directive](20-language-reference.md#library)
you can also use the `--library` command-line option.
### Constants
[Global constants](19-language-reference.md#constants) can be set using the `--define` command-line option.
[Global constants](20-language-reference.md#constants) can be set using the `--define` command-line option.
### <a id="config-include-path"></a> Config Include Path
@ -227,8 +227,8 @@ The `feature list` command shows which features are currently enabled:
## <a id="cli-command-node"></a> CLI command: Node
Provides the functionality to install and manage master and client
nodes in a [remote monitoring ](10-icinga2-client.md#icinga2-client) or
[distributed cluster](12-distributed-monitoring-ha.md#distributed-monitoring-high-availability) scenario.
nodes in a [remote monitoring ](11-icinga2-client.md#icinga2-client) or
[distributed cluster](13-distributed-monitoring-ha.md#distributed-monitoring-high-availability) scenario.
# icinga2 node --help
@ -273,9 +273,9 @@ nodes in a [remote monitoring ](10-icinga2-client.md#icinga2-client) or
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](19-language-reference.md#apply).
That way you can also identify which objects have been created from your [apply rules](20-language-reference.md#apply).
More information can be found in the [troubleshooting](16-troubleshooting.md#list-configuration-objects) section.
More information can be found in the [troubleshooting](17-troubleshooting.md#list-configuration-objects) section.
# icinga2 object --help
icinga2 - The Icinga 2 network monitoring daemon (version: v2.1.1-299-gf695275)
@ -406,7 +406,7 @@ cleared after review.
## <a id="cli-command-troubleshoot"></a> CLI command: Troubleshoot
Collects basic information like version, paths, log files and crash reports for troubleshooting purposes and prints them to a file or the console. See [troubleshooting](16-troubleshooting.md#troubleshooting-information-required).
Collects basic information like version, paths, log files and crash reports for troubleshooting purposes and prints them to a file or the console. See [troubleshooting](17-troubleshooting.md#troubleshooting-information-required).
Its output defaults to a file named `troubleshooting-[TIMESTAMP].log` so it won't overwrite older troubleshooting files.
@ -555,12 +555,12 @@ Or manually passing the `-C` argument:
> `# icinga2 daemon -C`
If you encouter errors during configuration validation, please make sure
to read the [troubleshooting](16-troubleshooting.md#troubleshooting) chapter.
to read the [troubleshooting](17-troubleshooting.md#troubleshooting) chapter.
You can also use the [CLI command](8-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](16-troubleshooting.md#list-configuration-objects).
Find more on troubleshooting with `object list` in [this chapter](17-troubleshooting.md#list-configuration-objects).
Example filtered by `Service` objects with the name `ping*`:
@ -604,5 +604,5 @@ safely reload 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](18-migrating-from-icinga-1x.md#differences-1x-2-real-reload).
> Details can be found [here](19-migrating-from-icinga-1x.md#differences-1x-2-real-reload).

454
doc/9-icinga2-api.md Normal file
View File

@ -0,0 +1,454 @@
# <a id="icinga2-api"></a> Icinga 2 API
## <a id="icinga2-api-introduction"></a> Introduction
The Icinga 2 API allows you to manage configuration objects
and resources in a simple, programmatic way using HTTP requests.
The endpoints are logically separated allowing you to easily
make calls to
* retrieve information (status, config)
* run actions (reschedule checks, etc.)
* create/update/delete configuration objects
* manage configuration modules
* subscribe to event streams
This chapter will start with a general overview followed by
detailed information about specific endpoints.
### <a id="icinga2-api-requests></a> Requests
Any tool capable of making HTTP requests can communicate with
the API, for example [curl](http://curl.haxx.se).
Requests are only allowed to use the HTTPS protocol so that
traffic remains encrypted.
By default the Icinga 2 API listens on port `5665` sharing this
port with the cluster communication protocol. This can be changed
by setting the `bind_port` attribute in the [ApiListener](6-object-types.md#objecttype-apilistener)
configuration object in the `/etc/icinga2/features-available/api.conf`
file.
Supported request methods:
Method | Usage
--------------|------------------------------------------------------
GET | Retrieve information about configuration objects. Any request using the GET method is read-only and does not affect any objects.
POST | Update attributes of a specified configuration object.
PUT | Create a new object. The PUT request must include all attributes required to create a new object.
DELETE | Remove an object created by the API. The DELETE method is idempotent and does not require any check if the object actually exists.
### <a id="icinga2-api-http-statuses></a> HTTP Statuses
The API will return standard [HTTP statuses](https://www.ietf.org/rfc/rfc2616.txt)
including error codes.
When an error occurs, the response body will contain additional information
about the problem and its source.
A status in the range of 200 generally means that the request was succesful
and no error was encountered.
Return codes within the 400 range indicate that there was a problem with the
request. Either you did not authenticate correctly, you are missing the authorization
for your requested action, the requested object does not exist or the request
was malformed.
A status in the range of 500 generally means that there was a server-side problem
and Icinga 2 is unable to process your request currently.
Ask your Icinga 2 system administrator to check the `icinga2.log` file for further
troubleshooting.
### <a id="icinga2-api-responses></a> Responses
Succesful requests will send back a response body containing a `results`
list. Depending on the number of affected objects in your request, the
results may contain one or more entries.
The [output](9-icinga2-api.md#icinga2-api-output) will be sent back as JSON object:
{
"results": [
{
"code": 200.0,
"status": "Object was created."
}
]
}
### <a id="icinga2-api-authentication></a> Authentication
There are two different ways for authenticating against the Icinga 2 API:
* username and password using HTTP basic auth
* X.509 certificate with client CN
In order to configure a new API user you'll need to add a new [ApiUser](6-object-types.md#objecttype-apiuser)
configuration object. In this example `root` will be the basic auth username
and the `password` attribute contains the basic auth password.
vim /etc/icinga2/conf.d/api-users.conf
object ApiUser "root" {
password = icinga"
}
Alternatively you can use X.509 client certificates by specifying the `client_cn`
the API should trust.
vim /etc/icinga2/conf.d/api-users.conf
object ApiUser "api-clientcn" {
password = "CertificateCommonName"
}
An `ApiUser` object can have both methods configured. Sensitive information
such as the password will not be exposed through the API itself.
New installations of Icinga 2 will automatically generate a new `ApiUser`
named `root` with a generated password in the `/etc/icinga2/conf.d/api-users.conf`
file.
You can manually invoke the cli command `icinga2 api setup` which will generate
a new local CA, self-signed certificate and a new API user configuration.
Once the API user is configured make sure to restart Icinga 2:
# service icinga2 restart
Now pass the basic auth information to curl and send a GET request to the API:
$ curl -u root:icinga -k -s 'https://nbmif.int.netways.de:5665/v1' -X GET
In case you will get `Unauthorized` make sure to check the API user credentials.
### <a id="icinga2-api-permissions></a> Permissions
**TODO** https://dev.icinga.org/issues/9088
### <a id="icinga2-api-parameters></a> Parameters
Depending on the request method there are two ways of
passing parameters to the request:
* JSON body (`POST`, `PUT`)
* Query string (`GET`, `DELETE`)
Reserved characters by the HTTP protocol must be passed url-encoded as query string, e.g. a
whitespace becomes `%20`.
Example for query string:
/v1/hosts?filter=match(%22nbmif*%22,host.name)&attrs=host.name&attrs=host.state
Example for JSON body:
{ "attrs": { "address": "8.8.4.4", "vars.os" : "Windows" } }
**TODO**
#### <a id="icinga2-api-filters></a> Filters
Use the same syntax as for apply rule expressions
for filtering specific objects.
Example for all services in NOT-OK state:
https://localhost:5665/v1/services?filter=service.state!=0
Example for matching all hosts by name (**Note**: `"` are url-encoded as `%22`):
https://localhost:5665/v1/hosts?filter=match(%22nbmif*%22,host.name)
**TODO**
### <a id="icinga2-api-output-format></a>Output Format
The request and reponse body contain a JSON encoded string.
### <a id="icinga2-api-version></a>Version
Each url contains the version string as prefix (currently "/v1").
### <a id="icinga2-api-url-overview></a>Url Overview
The Icinga 2 API provides multiple url endpoints
Url Endpoints | Description
--------------|----------------------------------------------------
/v1/actions | Endpoint for running specific [API actions](9-icinga2-api.md#icinga2-api-actions).
/v1/config | Endpoint for [managing configuration modules](9-icinga2-api.md#icinga2-api-config-management).
/v1/events | Endpoint for subscribing to [API events](9-icinga2-api.md#icinga2-api-actions).
/v1/types | Endpoint for listing Icinga 2 configuration object types and their attributes.
Additionally there are endpoints for each [config object type](6-object-types.md#object-types):
**TODO** Update
Url Endpoints | Description
----------------------|----------------------------------------------------
/v1/hosts | Endpoint for retreiving and updating [Host](6-object-types.md#objecttype-host) objects.
/v1/services | Endpoint for retreiving and updating [Service](6-object-types.md#objecttype-service) objects.
/v1/notifications | Endpoint for retreiving and updating [Notification](6-object-types.md#objecttype-notification) objects.
/v1/dependencies | Endpoint for retreiving and updating [Dependency](6-object-types.md#objecttype-dependency) objects.
/v1/users | Endpoint for retreiving and updating [User](6-object-types.md#objecttype-user) objects.
/v1/checkcommands | Endpoint for retreiving and updating [CheckCommand](6-object-types.md#objecttype-checkcommand) objects.
/v1/eventcommands | Endpoint for retreiving and updating [EventCommand](6-object-types.md#objecttype-eventcommand) objects.
/v1/notificationcommands | Endpoint for retreiving and updating [NotificationCommand](6-object-types.md#objecttype-notificationcommand) objects.
/v1/hostgroups | Endpoint for retreiving and updating [HostGroup](6-object-types.md#objecttype-hostgroup) objects.
/v1/servicegroups | Endpoint for retreiving and updating [ServiceGroup](6-object-types.md#objecttype-servicegroup) objects.
/v1/usergroups | Endpoint for retreiving and updating [UserGroup](6-object-types.md#objecttype-usergroup) objects.
/v1/zones | Endpoint for retreiving and updating [Zone](6-object-types.md#objecttype-zone) objects.
/v1/endpoints | Endpoint for retreiving and updating [Endpoint](6-object-types.md#objecttype-endpoint) objects.
/v1/timeperiods | Endpoint for retreiving and updating [TimePeriod](6-object-types.md#objecttype-timeperiod) objects.
## <a id="icinga2-api-actions></a> Actions
There are several actions available for Icinga 2 provided by the `actions` url endpoint.
In case you have been using the [external commands](5-advanced-topics.md#external-commands)
in the past, the API actions provide a yet more powerful interface with
filters and even more functionality.
Actions require specific target types (e.g. `type=Host`) and a [filter](9-icinga2-api.md#)
**TODO**
Action name | Parameters | Target types | Notes
---------------------------------------|-----------------------------------|--------------------------|-----------------------
process-check-result | exit_status; plugin_output; check_source; performance_data[]; check_command[]; execution_end; execution_start; schedule_end; schedule_start | Service; Host | -
reschedule-check | {next_check}; {(force_check)} | Service; Host | -
acknowledge-problem | author; comment; {timestamp}; {(sticky)}; {(notify)} | Service; Host | -
remove-acknowledgement | - | Service; Host | -
add-comment | author; comment | Service; Host | -
remove-comment | - | Service;Host | -
remove-comment-by-id | comment_id | - | -
delay-notifications | timestamp | Service;Host | -
add-downtime | start_time; end_time; duration; author; comment; {trigger_id}; {(fixed)} | Service; Host; ServiceGroup; HostGroup | Downtime for all services on host x?
remove-downtime | - | Service; Host | -
remove-downtime-by-id | downtime_id | - | -
send-custom-notification | options[]; author; comment | Service; Host | -
enable-passive-checks | - | Service; Host; ServiceGroup; HostGroup | "System" as target?
disable-passive-checks | - | Service; Host; ServiceGroup; HostGroup | diable all passive checks for services of hosts y in hostgroup x?
enable-active-checks | - | Host; HostGroup | -
disable-active-checks | - | Host; HostGroup | -
enable-notifications | - | Service; Host; ServiceGroup; HostGroup | Enable all notifications for services of host x?
disable-notifications | - | Service; Host; ServiceGroup; HostGroup | -
enable-flap-detection | - | Service; Host; ServiceGroup; HostGroup | -
disable-flap-detection | - | Service; Host; ServiceGroup; HostGroup | -
enable-event-handler | - | Service; Host | -
disable-event-handler | - | Service; Host | -
enable-global-notifications | - | - | -
disable-global-notifications | - | - | -
enable-global-flap-detection | - | - | -
disable-global-flap-detection | - | - | -
enable-global-event-handlers | - | - | -
disable-global-event-handlers | - | - | -
enable-global-performance-data | - | - | -
disable-global-performance-data | - | - | -
start-global-executing-svc-checks | - | - | -
stop-global-executing-svc-checks | - | - | -
start-global-executing-host-checks | - | - | -
stop-global-executing-host-checks | - | - | -
shutdown-process | - | - | -
restart-process | - | - | -
Examples:
Reschedule a service check for all services in NOT-OK state:
$ curl -u root:icinga -k -s 'https://localhost:5665/v1/actions/reschedule-check?filter=service.state!=0&type=Service' -X POST | python -m json.tool
{
"results": [
{
"code": 200.0,
"status": "Successfully rescheduled check for nbmif.int.netways.de!http."
},
{
"code": 200.0,
"status": "Successfully rescheduled check for nbmif.int.netways.de!disk."
},
{
"code": 200.0,
"status": "Successfully rescheduled check for nbmif.int.netways.de!disk /."
}
]
}
## <a id="icinga2-api-config-management></a> Configuration Management
`/v1/config`
**TODO** Depends on https://dev.icinga.org/issues/9953
## <a id="icinga2-api-events></a> Events
**TODO**
## <a id="icinga2-api-hosts></a> Hosts
All object attributes are prefixed with their respective object type.
Example:
host.address
Output listing and url parameters use the same syntax.
### <a id="icinga2-api-hosts-list></a> List All Hosts
Send a `GET` request to `/v1/hosts` to list all host objects and
their attributes.
$ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts' -X GET
### <a id="icinga2-api-hosts-create></a> Create New Host Object
New objects must be created by sending a PUT request. The following
parameters need to be passed inside the JSON body:
Parameters | Description
--------------|------------------------------------
name | **Optional.** If not specified inside the url, this is **required**.
templates | **Optional.** Import existing configuration templates, e.g. `generic-host`.
attrs | **Required.** Set specific [Host](6-object-types.md#objecttype-host) object attributes.
If attributes are of the Dictionary type, you can also use the indexer format:
"attrs": { "vars.os": "Linux" }
Example:
$ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com' \
-X PUT \
-d '{ "templates": [ "generic-host" ], "attrs": { "address": "8.8.8.8", "vars.os" : "Linux" } }' \
| python -m json.tool
{
"results": [
{
"code": 200.0,
"status": "Object was created."
}
]
}
**Note**: Host objects require the `check_command` attribute. In the example above the `generic-host`
template already provides such.
If the configuration validation fails, the new object will not be created and the response body
contains a detailed error message. The following example omits the required `check_command` attribute.
$ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com' \
-X PUT \
-d '{ "attrs": { "address": "8.8.8.8", "vars.os" : "Linux" } }' \
| python -m json.tool
{
"results": [
{
"code": 500.0,
"errors": [
"Error: Validation failed for object 'google.com' of type 'Host'; Attribute 'check_command': Attribute must not be empty."
],
"status": "Object could not be created."
}
]
}
### <a id="icinga2-api-hosts-show></a> Show Host
Send a `GET` request including the host name inside the url:
$ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com' -X GET
You can select specific attributes by adding them as url parameters using `?attrs=...`. Multiple
attributes must be added one by one, e.g. `?attrs=host.address&attrs=host.name`.
$ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com?attrs=host.name&attrs=host.address' -X GET | python -m json.tool
{
"results": [
{
"attrs": {
"host.address": "8.8.8.8",
"host.name": "google.com"
}
}
]
}
### <a id="icinga2-api-hosts-modify></a> Modify Host
Existing objects must be modifed by sending a `POST` request. The following
parameters need to be passed inside the JSON body:
Parameters | Description
--------------|------------------------------------
name | **Optional.** If not specified inside the url, this is **required**.
templates | **Optional.** Import existing configuration templates, e.g. `generic-host`.
attrs | **Required.** Set specific [Host](6-object-types.md#objecttype-host) object attributes.
If attributes are of the Dictionary type, you can also use the indexer format:
"attrs": { "vars.os": "Linux" }
Example for existing object `google.com`:
$ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com' \
-X POST \
-d '{ "attrs": { "address": "8.8.4.4", "vars.os" : "Windows" } }' \
| python -m json.tool
{
"results": [
{
"code": 200.0,
"name": "google.com",
"status": "Attributes updated.",
"type": "Host"
}
]
}
### <a id="icinga2-api-hosts-delete></a> Delete Host
You can delete objects created using the API by sending a `DELETE`
request. Specify the object name inside the url.
Parameters | Description
--------------|------------------------------------
cascade | **Optional.** Delete objects depending on the deleted objects (e.g. services on a host).
Example:
$ curl -u root:icinga -k -s 'https://localhost:5665/v1/hosts/google.com?cascade=1' -X DELETE | python -m json.tool
{
"results": [
{
"code": 200.0,
"name": "google.com",
"status": "Object was deleted.",
"type": "Host"
}
]
}
**TODO** Add more config objects