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

Update documentation 

refs #9105
This commit is contained in:
Gunnar Beutner 2015-11-07 13:28:09 +01:00
parent 9830ea6ea7
commit 1a29fa6539
1 changed files with 133 additions and 139 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

272
doc/9-icinga2-api.md
View File

@ -223,59 +223,56 @@ The required actions or types can be replaced by using a wildcard match ("*").
Depending on the request method there are two ways of Depending on the request method there are two ways of
passing parameters to the request: passing parameters to the request:
* JSON object as request body (`POST`, `PUT`) * JSON object as request body (all request methods other than `GET`)
* Query string as URL parameter (`GET`, `DELETE`) * Query string as URL parameter (all request methods)
Reserved characters by the HTTP protocol must be [URL-encoded](https://en.wikipedia.org/wiki/Percent-encoding) Reserved characters by the HTTP protocol must be [URL-encoded](https://en.wikipedia.org/wiki/Percent-encoding)
as query string, e.g. a space becomes `%20`. as query string, e.g. a space character becomes `%20`.
Example for a URL-encoded query string: Example for a URL-encoded query string:
/v1/objects/hosts?filter=match(%22icinga2-node1.localdomain*%22,host.name)&attrs=host.name&attrs=host.state /v1/objects/hosts?filter=match(%22icinga2-node1.localdomain*%22,host.name)&attrs=host.name&attrs=host.state
Example for a JSON body: Here are the exact same query parameters as a JSON object:
{ "templates": [ "generic-host" ], "attrs": { "address": "8.8.8.8", "check_command": "hostalive", "vars.os" : "Linux" } } { "filter": "match(\"icinga2-node1.localdomain*\",host.name)", "attrs": [ "host.name", "host.state" ] }
### <a id="icinga2-api-filters"></a> Filters
Selecting a single object as URL parameter: #### <a id="icinga2-api-simple-filters"></a> Simple Filters
?host=icinga.org By default actions and queries operate on all objects unless further restricted by the user. For
example, the following query returns all `Host` objects:
Selecting multiple objects as URL parameter: https://localhost:5665/v1/objects/hosts
?hosts=host1&hosts=host2&hosts=host3 If you're only interested in a single object you can limit the output to that object by specifying its name:
The array-append-notation is also supported: https://localhost:5665/v1/objects/hosts?host=localhost
?hosts[]=host1&hosts[]=host2&hosts[]=host3 The name of the URL parameter is the lower-case version of the type the query applies to. For
example, for `Host` objects the URL parameter therefore is `host`, for `Service` objects it is
`service` and so on.
In case you want to add an object with a reference to other objects (e.g. the service You can also specify multiple objects:
`ping4` belonging to the host `icinga2-node1.localdomain`) you'll need to use the
full name from the returned result set, e.g. `icinga2-node1.localdomain`. An object's
full name can also be retrieved from the `__name` object attribute in object queries.
A similar output is shown in [object list](8-cli-commands.md#cli-command-object) cli output.
#### <a id="icinga2-api-filters"></a> Filters https://localhost:5665/v1/objects/hosts?hosts=first-host&hosts=second-host
The information provided in this chapter applies to both permission filters (as used when Again - like in the previous example - the name of the URL parameter is the lower-case version of the type. However, because we're specifying multiple objects here the **plural form** of the type is used.
When specifying names for objects which have composite names like for example services the
full name has to be used:
https://localhost:5665/v1/objects/services?service=localhost!ping6
The full name of an object can be obtained by looking at the `__name` attribute.
#### <a id="icinga2-api-advanced-filters"></a> Advanced Filters
Most of the information provided in this chapter applies to both permission filters (as used when
configuring `ApiUser` objects) and filters specified in queries. configuring `ApiUser` objects) and filters specified in queries.
The syntax for filters is the same like for [apply rule expressions](3-monitoring-basics.md#using-apply-expressions). Advanced filters allow users to filter objects using lambda expressions. The syntax for these filters is the same like for [apply rule expressions](3-monitoring-basics.md#using-apply-expressions).
User-specified filters are run in a sandbox environment which ensures that filters cannot
modify Icinga's state, for example object attributes or global variables.
When querying objects of a specific type the filter expression is evaluated for each object
of that type. The object is made available to the filter expression as a variable whose name
is the lower-case version of the object's type name.
For example when querying objects of type `Host` the variable in the filter expression is named
`host`. Additionally related objects such as the host's check command are also made available
(e.g., via the `check_command` variable).
The object is also made available via the `obj` variable. This makes it easier to build
filters which can be used for more than one object type (e.g., for permissions).
> **Note** > **Note**
> >
@ -294,6 +291,27 @@ Example for all hosts which are in the host group `linux-servers`:
https://localhost:5665/v1/objects/hosts?filter="linux-servers" in host.groups https://localhost:5665/v1/objects/hosts?filter="linux-servers" in host.groups
User-specified filters are run in a sandbox environment which ensures that filters cannot
modify Icinga's state, for example object attributes or global variables.
When querying objects of a specific type the filter expression is evaluated for each object
of that type. The object is made available to the filter expression as a variable whose name
is the lower-case version of the object's type name.
For example when querying objects of type `Host` the variable in the filter expression is named
`host`. Additionally related objects such as the host's check command are also made available
(e.g., via the `check_command` variable).
The object is also made available via the `obj` variable. This makes it easier to build
filters which can be used for more than one object type (e.g., for permissions).
Some queries can be performed for more than just one object type. One example is the 'reschedule-check'
action which can be used for both hosts and services. When using advanced filters you will also have to specify the
type using the `type` parameter:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST "https://localhost:5665/v1/actions/reschedule-check \
-d '{ "type": "Service", "filter": "service.name==\"ping6\"" }' | python -m json.tool
When building filters you have to ensure that values such as When building filters you have to ensure that values such as
`"linux-servers"` are escaped properly according to the rules of the Icinga 2 configuration `"linux-servers"` are escaped properly according to the rules of the Icinga 2 configuration
language. language.
@ -332,21 +350,14 @@ Please check the respective sections for detailed URL information and parameters
## <a id="icinga2-api-actions"></a> Actions ## <a id="icinga2-api-actions"></a> Actions
There are several actions available for Icinga 2 provided by the `actions` There are several actions available for Icinga 2 provided by the `/v1/actions`
URL endpoint `/v1/actions`. You can run actions by sending a `POST` request. URL endpoint. You can run actions by sending a `POST` request.
In case you have been using the [external commands](15-features.md#external-commands) In case you have been using the [external commands](15-features.md#external-commands)
in the past, the API actions provide a similar interface with filter in the past, the API actions provide a similar interface with filter
capabilities for some of the more common targets which do not directly change capabilities for some of the more common targets which do not directly change
the configuration. the configuration.
Some actions require specific target types (e.g. `type=Host`) and a
[filter expression](9-icinga2-api.md#icinga2-api-filters).
For each object matching the filter the action in question is performed once.
These parameters may either be passed as a URL query string (e.g. url/actions/action-name?list=of&parameters)
or as key-value pairs in a JSON-formatted payload or a mix of both.
All actions return a 200 `OK` or an appropriate error code for each All actions return a 200 `OK` or an appropriate error code for each
action performed on each object matching the supplied filter. action performed on each object matching the supplied filter.
@ -365,20 +376,17 @@ Send a `POST` request to the URL endpoint `/v1/actions/process-check-result`.
Parameter | Type | Description Parameter | Type | Description
------------------|--------------|-------------- ------------------|--------------|--------------
type | string | **Required.** `Host` or `Service`.
filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api.md#icinga2-api-filters).
exit\_status | integer | **Required.** For services: 0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN, for hosts: 0=OK, 1=CRITICAL. exit\_status | integer | **Required.** For services: 0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN, for hosts: 0=OK, 1=CRITICAL.
plugin\_output | string | **Required.** The plugins main output, i.e. the text before the `|`. Does **not** contain the performance data. plugin\_output | string | **Required.** The plugins main output. Does **not** contain the performance data.
performance\_data | string array | **Optional.** One array entry per `;` separated block. performance\_data | string array | **Optional.** The performance data.
check\_command | string array | **Optional.** The first entry should be the check commands path, then one entry for each command line option followed by an entry for each of its argument. check\_command | string array | **Optional.** The first entry should be the check commands path, then one entry for each command line option followed by an entry for each of its argument.
check\_source | string | **Optional.** Usually the name of the `command_endpoint` check\_source | string | **Optional.** Usually the name of the `command_endpoint`
This is used to submit a passive check result for a service or host. Passive In addition to these parameters a [filter](9-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
checks need to be enabled for the check result to be processed.
Example: Example:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/process-check-result?type=Service&filter=service.name==%22ping6%22' \ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/process-check-result?service=localhost!ping6' \
-d '{ "exit_status": 2, "plugin_output": "PING CRITICAL - Packet loss = 100%", "performance_data": [ "rta=5000.000000ms;3000.000000;5000.000000;0.000000", "pl=100%;80;100;0" ], "check_source": "icinga2-node1.localdomain" }' | python -m json.tool -d '{ "exit_status": 2, "plugin_output": "PING CRITICAL - Packet loss = 100%", "performance_data": [ "rta=5000.000000ms;3000.000000;5000.000000;0.000000", "pl=100%;80;100;0" ], "check_source": "icinga2-node1.localdomain" }' | python -m json.tool
{ {
@ -398,17 +406,17 @@ Send a `POST` request to the URL endpoint `/v1/actions/reschedule-check`.
Parameter | Type | Description Parameter | Type | Description
-------------|-----------|-------------- -------------|-----------|--------------
type | string | **Required.** `Host` or `Service`.
filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api.md#icinga2-api-filters).
next\_check | timestamp | **Optional.** The next check will be run at this time. If omitted the current time is used. next\_check | timestamp | **Optional.** The next check will be run at this time. If omitted the current time is used.
force\_check | boolean | **Optional.** Defaults to `false`. If enabled the checks are executed regardless of time period restrictions and checks being disabled per object or on a global basis. force\_check | boolean | **Optional.** Defaults to `false`. If enabled the checks are executed regardless of time period restrictions and checks being disabled per object or on a global basis.
In addition to these parameters a [filter](9-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
The example reschedules all services with the name "ping6" to immediately perform a check The example reschedules all services with the name "ping6" to immediately perform a check
(`next_check` default), ignoring any time periods or whether active checks are (`next_check` default), ignoring any time periods or whether active checks are
allowed for the service (`force_check=true`). allowed for the service (`force_check=true`).
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST "https://localhost:5665/v1/actions/reschedule-check?type=Service&filter=service.name==%22ping6%22" \ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST "https://localhost:5665/v1/actions/reschedule-check \
-d '{ "force_check": true }' | python -m json.tool -d '{ "type": "Service", "filter": "service.name==\"ping6\"", "force_check": true }' | python -m json.tool
{ {
"results": [ "results": [
@ -429,12 +437,12 @@ Send a `POST` request to the URL endpoint `/v1/actions/send-custom-notification`
Parameter | Type | Description Parameter | Type | Description
----------|---------|-------------- ----------|---------|--------------
type | string | **Required.** `Host` or `Service`.
filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api.md#icinga2-api-filters).
author | string | **Required.** Name of the author, may be empty. author | string | **Required.** Name of the author, may be empty.
comment | string | **Required.** Comment text, may be empty. comment | string | **Required.** Comment text, may be empty.
force | boolean | **Optional.** Default: false. If true, the notification is sent regardless of downtimes or whether notifications are enabled or not. force | boolean | **Optional.** Default: false. If true, the notification is sent regardless of downtimes or whether notifications are enabled or not.
In addition to these parameters a [filter](9-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
Example for a custom host notification announcing a global maintenance to Example for a custom host notification announcing a global maintenance to
host owners: host owners:
@ -464,10 +472,9 @@ Send a `POST` request to the URL endpoint `/v1/actions/delay-notification`.
Parameter | Type | Description Parameter | Type | Description
----------|-----------|-------------- ----------|-----------|--------------
type | string | **Required.** `Host` or `Service`.
filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api.md#icinga2-api-filters).
timestamp | timestamp | **Required.** Delay notifications until this timestamp. timestamp | timestamp | **Required.** Delay notifications until this timestamp.
In addition to these parameters a [filter](9-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
Example: Example:
@ -496,14 +503,14 @@ Send a `POST` request to the URL endpoint `/v1/actions/acknowledge-problem`.
Parameter | Type | Description Parameter | Type | Description
----------|-----------|-------------- ----------|-----------|--------------
type | string | **Required.** `Host` or `Service`.
filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api.md#icinga2-api-filters).
author | string | **Required.** Name of the author, may be empty. author | string | **Required.** Name of the author, may be empty.
comment | string | **Required.** Comment text, may be empty. comment | string | **Required.** Comment text, may be empty.
expiry | timestamp | **Optional.** If set the acknowledgement will vanish after this timestamp. expiry | timestamp | **Optional.** If set the acknowledgement will vanish after this timestamp.
sticky | boolean | **Optional.** If `true`, the default, the acknowledgement will remain until the service or host fully recovers. sticky | boolean | **Optional.** If `true`, the default, the acknowledgement will remain until the service or host fully recovers.
notify | boolean | **Optional.** If `true` a notification will be sent out to contacts to indicate this problem has been acknowledged. The default is false. notify | boolean | **Optional.** If `true` a notification will be sent out to contacts to indicate this problem has been acknowledged. The default is false.
In addition to these parameters a [filter](9-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
The following example acknowledges all services which are in a hard critical state and sends out The following example acknowledges all services which are in a hard critical state and sends out
a notification for them: a notification for them:
@ -530,10 +537,7 @@ been removed notifications will be sent out again.
Send a `POST` request to the URL endpoint `/v1/actions/remove-acknowledgement`. Send a `POST` request to the URL endpoint `/v1/actions/remove-acknowledgement`.
parameter | type | description A [filter](9-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
----------|--------|--------------
type | string | **Required.** `Host` or `Service`.
filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api.md#icinga2-api-filters).
The example removes all service acknowledgements: The example removes all service acknowledgements:
@ -557,14 +561,14 @@ Adds a `comment` from an `author` to services or hosts.
Send a `POST` request to the URL endpoint `/v1/actions/add-comment`. Send a `POST` request to the URL endpoint `/v1/actions/add-comment`.
parameter | type | description Parameter | Type | Description
----------|--------|-------------- ----------|--------|--------------
type | string | **Required.** `Host` or `Service`.
filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api.md#icinga2-api-filters).
author | string | **Required.** name of the author, may be empty. author | string | **Required.** name of the author, may be empty.
comment | string | **Required.** Comment text, may be empty. comment | string | **Required.** Comment text, may be empty.
Example: In addition to these parameters a [filter](9-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
The following example adds a comment for all `ping4` services:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/add-comment?type=Service&filter=service.name==%22ping4%22' -d '{ "author": "icingaadmin", "comment": "Troubleticket #123456789 opened." }' | python -m json.tool $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/add-comment?type=Service&filter=service.name==%22ping4%22' -d '{ "author": "icingaadmin", "comment": "Troubleticket #123456789 opened." }' | python -m json.tool
{ {
@ -590,12 +594,9 @@ Removes all comments for services or hosts.
Send a `POST` request to the URL endpoint `/v1/actions/remove-all-comments`. Send a `POST` request to the URL endpoint `/v1/actions/remove-all-comments`.
parameter | type | description A [filter](9-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
------------|---------|--------------
type | string | **Required.** `Host` or `Service`.
filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api.md#icinga2-api-filters).
Example: The following example removes all comments from all services:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-all-comments?type=Service' | python -m json.tool $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-all-comments?type=Service' | python -m json.tool
@ -616,11 +617,11 @@ Example:
Remove the comment using its `name` attribute , returns `OK` if the Remove the comment using its `name` attribute , returns `OK` if the
comment did not exist. comment did not exist.
**Note**: This is **not** the legacy ID but the comment name returned by **Note**: This is **not** the legacy ID but the comment name returned by
Icinga 2 when [add a comment](9-icinga2-api.md#icinga2-api-actions-add-comment). Icinga 2 when [adding a comment](9-icinga2-api.md#icinga2-api-actions-add-comment).
Send a `POST` request to the URL endpoint `/v1/actions/remove-comment`. Send a `POST` request to the URL endpoint `/v1/actions/remove-comment`.
parameter | type | description Parameter | Type | Description
------------|---------|-------------- ------------|---------|--------------
name | string | **Required.** Name of the comment to remove. name | string | **Required.** Name of the comment to remove.
@ -644,16 +645,16 @@ Schedule a downtime for hosts and services.
Send a `POST` request to the URL endpoint `/v1/actions/schedule-downtime`. Send a `POST` request to the URL endpoint `/v1/actions/schedule-downtime`.
parameter | type | description Parameter | Type | Description
------------|-----------|-------------- ------------|-----------|--------------
type | string | **Required.** `Host` or `Service`.
filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api.md#icinga2-api-filters).
start\_time | timestamp | **Required.** Timestamp marking the beginning of the downtime. start\_time | timestamp | **Required.** Timestamp marking the beginning of the downtime.
end\_time | timestamp | **Required.** Timestamp marking the end of the downtime. end\_time | timestamp | **Required.** Timestamp marking the end of the downtime.
duration | integer | **Required.** Duration of the downtime in seconds if `fixed` is set to false. duration | integer | **Required.** Duration of the downtime in seconds if `fixed` is set to false.
fixed | boolean | **Optional.** Defaults to `false`. If true the downtime is `fixed` otherwise `flexible`. See [downtimes](5-advanced-topics.md#downtimes) for more information. fixed | boolean | **Optional.** Defaults to `false`. If true the downtime is `fixed` otherwise `flexible`. See [downtimes](5-advanced-topics.md#downtimes) for more information.
trigger\_name | string | **Optional.** Sets the trigger for a triggered downtime. See [downtimes](5-advanced-topics.md#downtimes) for more information on triggered downtimes. trigger\_name | string | **Optional.** Sets the trigger for a triggered downtime. See [downtimes](5-advanced-topics.md#downtimes) for more information on triggered downtimes.
In addition to these parameters a [filter](9-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
Example: Example:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/schedule-downtime?type=Service&filter=service.name==%22ping4%22' -d '{ "start_time": 1446388806, "end_time": 1446389806, "duration": 1000, "author": "icingaadmin", "comment": "IPv4 network maintenance" }' | python -m json.tool $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/schedule-downtime?type=Service&filter=service.name==%22ping4%22' -d '{ "start_time": 1446388806, "end_time": 1446389806, "duration": 1000, "author": "icingaadmin", "comment": "IPv4 network maintenance" }' | python -m json.tool
@ -681,12 +682,9 @@ Removes all downtimes for services or hosts.
Send a `POST` request to the URL endpoint `/v1/actions/remove-all-downtimes`. Send a `POST` request to the URL endpoint `/v1/actions/remove-all-downtimes`.
parameter | type | description A [filter](9-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
----------|--------|--------------
type | string | **Required.** `Host` or `Service`.
filter | string | **Optional.** Apply the action only to objects matching the [filter](9-icinga2-api.md#icinga2-api-filters).
Example: The following example removes all downtimes for all `ping4` services:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-all-downtimes?type=Service&filter=service.name==%22ping4%22' | python -m json.tool $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-all-downtimes?type=Service&filter=service.name==%22ping4%22' | python -m json.tool
@ -712,7 +710,7 @@ Icinga 2 when [scheduling a downtime](9-icinga2-api.md#icinga2-api-actions-sched
Send a `POST` request to the URL endpoint `/v1/actions/remove-downtime`. Send a `POST` request to the URL endpoint `/v1/actions/remove-downtime`.
parameter | type | description Parameter | Type | Description
-------------|---------|-------------- -------------|---------|--------------
name | string | **Required.** Name of the downtime to remove. name | string | **Required.** Name of the downtime to remove.
@ -773,17 +771,16 @@ Example:
} }
## <a id="icinga2-api-event-streams"></a> Event Streams ## <a id="icinga2-api-event-streams"></a> Event Streams
You can subscribe to event streams by sending a `POST` request to the URL endpoint `/v1/events`. You can subscribe to event streams by sending a `POST` request to the URL endpoint `/v1/events`.
The following parameters need to be passed as URL parameters: The following parameters need to be specified (either as URL parameters or in a JSON-encoded message body):
Parameters | Description Parameter | Type | Description
-----------|-------------- -----------|--------------|-------------
types | **Required.** Event type(s). Multiple types as URL parameters are supported. types | string array | **Required.** Event type(s). Multiple types as URL parameters are supported.
queue | **Required.** Unique queue name. Multiple HTTP clients can use the same queue with existing filters. queue | string | **Required.** Unique queue name. Multiple HTTP clients can use the same queue as long as they use the same event types and filter.
filter | **Optional.** Filter for specific event attributes using [filter expressions](9-icinga2-api.md#icinga2-api-filters). filter | string | **Optional.** Filter for specific event attributes using [filter expressions](9-icinga2-api.md#icinga2-api-filters).
### <a id="icinga2-api-event-streams-types"></a> Event Stream Types ### <a id="icinga2-api-event-streams-types"></a> Event Stream Types
@ -927,16 +924,13 @@ available as [config object types](6-object-types.md#object-types):
/v1/objects/comments | Endpoint for [Comment](6-object-types.md#objecttype-comment) objects. /v1/objects/comments | Endpoint for [Comment](6-object-types.md#objecttype-comment) objects.
/v1/objects/downtimes | Endpoint for [Downtime](6-object-types.md#objecttype-downtime) objects. /v1/objects/downtimes | Endpoint for [Downtime](6-object-types.md#objecttype-downtime) objects.
Make sure that your API user has the appropriate [permissions](9-icinga2-api.md#icinga2-api-permissions)
to manipulate config objects.
### <a id="icinga2-api-config-objects-cluster-sync"></a> API Objects and Cluster Config Sync ### <a id="icinga2-api-config-objects-cluster-sync"></a> API Objects and Cluster Config Sync
Newly created or updated objects can be synced throughout your Newly created or updated objects can be synced throughout your
Icinga 2 cluster. Set the `zone` attribute to the zone this object Icinga 2 cluster. Set the `zone` attribute to the zone this object
belongs to and let the API and cluster handle the rest. belongs to and let the API and cluster handle the rest.
Objects without zone attribute are only synced in the same (HA) zone.
Objects without a zone attribute are only synced in the same zone the Icinga instance belongs to.
> **Note** > **Note**
> >
@ -945,15 +939,11 @@ Objects without zone attribute are only synced in the same (HA) zone.
> in the [ApiListener](6-object-types.md#objecttype-apilistener) object > in the [ApiListener](6-object-types.md#objecttype-apilistener) object
> on each node. > on each node.
If you add a new cluster instance, or boot an instance which has been offline If you add a new cluster instance, or reconnect an instance which has been offline
for a while, Icinga 2 takes care of the initial object sync for all objects for a while, Icinga 2 takes care of the initial object sync for all objects
created by the API. created by the API.
More information about distributed monitoring, cluster and its ### <a id="icinga2-api-config-objects-query"></a> Querying Objects
configuration can be found [here](13-distributed-monitoring-ha.md#distributed-monitoring-high-availability).
### <a id="icinga2-api-config-objects-query"></a> Query Objects
Send a `GET` request to `/v1/objects/hosts` to list all host objects and Send a `GET` request to `/v1/objects/hosts` to list all host objects and
their attributes. their attributes.
@ -966,11 +956,9 @@ The following URL parameters can be added:
Parameters | Description Parameters | Description
-----------|-------------- -----------|--------------
name | **Optional.** If not specified inside the url, all objects of this type are queried.
attrs | **Optional.** Query specific object attributes for this [object type](6-object-types.md#object-types). attrs | **Optional.** Query specific object attributes for this [object type](6-object-types.md#object-types).
joins | **Optional.** Join related object types and their attributes (`?joins=host` for the entire set, or selectively by `?joins=host.name`). joins | **Optional.** Join related object types and their attributes (`?joins=host` for the entire set, or selectively by `?joins=host.name`).
meta | **Optional.** Enable meta information using `?meta=used_by`. Defaults to disabled. meta | **Optional.** Enable meta information using `?meta=used_by`. Defaults to disabled.
filter | **Optional.** Query objects matching the [filter](9-icinga2-api.md#icinga2-api-filters).
Example for the host `google.com` inside the URL: Example for the host `google.com` inside the URL:
@ -1041,10 +1029,9 @@ attribute. There is an exception for multiple objects used in dependencies and z
User | period User | period
Zones | parent Zones | parent
Example for querying all service objects and fetching their `display_name` and `check_command` In addition to these parameters a [filter](9-icinga2-api.md#icinga2-api-filters) may be provided.
attribute. The host object joined attributes are `host.name` and `host.address`.
The [filter](9-icinga2-api.md#icinga2-api-filters) ensures that only hosts with the custom attribute `os` set to `Linux` are Here's an example that retrieves all service objects for hosts which have had their `os` custom attribute set to `Linux`. The result set contains the `display_name` and `check_command` attributes for the service. The query also returns the host's `name` and `address` attribute via a join:
listed.
$ curl -k -s -u root:icinga 'https://localhost:5665/v1/objects/services?attrs=display_name&attrs=check_command&joins=host.name&joins=host.address&filter=host.vars.os==%22Linux%22' | python -m json.tool $ curl -k -s -u root:icinga 'https://localhost:5665/v1/objects/services?attrs=display_name&attrs=check_command&joins=host.name&joins=host.address&filter=host.vars.os==%22Linux%22' | python -m json.tool
@ -1084,7 +1071,7 @@ listed.
} }
### <a id="icinga2-api-config-objects-create"></a> Create Config Object ### <a id="icinga2-api-config-objects-create"></a> Creating Config Objects
New objects must be created by sending a PUT request. The following New objects must be created by sending a PUT request. The following
parameters need to be passed inside the JSON body: parameters need to be passed inside the JSON body:
@ -1096,7 +1083,7 @@ parameters need to be passed inside the JSON body:
attrs | **Required.** Set specific object attributes for this [object type](6-object-types.md#object-types). attrs | **Required.** Set specific object attributes for this [object type](6-object-types.md#object-types).
If attributes are of the Dictionary type, you can also use the indexer format: If attributes are of the Dictionary type, you can also use the indexer format. This might be necessary to only override specific custom variables and keep all other existing custom variables (e.g. from templates):
"attrs": { "vars.os": "Linux" } "attrs": { "vars.os": "Linux" }
@ -1114,11 +1101,9 @@ Example for creating the new host object `google.com`:
] ]
} }
**Note**: Host objects require the `check_command` attribute.
If the configuration validation fails, the new object will not be created and the response body 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 `check_command` attribute required contains a detailed error message. The following example is missing the `check_command` attribute
by the host object. which is required for host objects:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/hosts/google.com' \ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/hosts/google.com' \
-d '{ "attrs": { "address": "8.8.8.8", "vars.os" : "Linux" } }' \ -d '{ "attrs": { "address": "8.8.8.8", "vars.os" : "Linux" } }' \
@ -1137,7 +1122,7 @@ by the host object.
### <a id="icinga2-api-config-objects-modify"></a> Modify Object ### <a id="icinga2-api-config-objects-modify"></a> Modifying Objects
Existing objects must be modified by sending a `POST` request. The following Existing objects must be modified by sending a `POST` request. The following
parameters need to be passed inside the JSON body: parameters need to be passed inside the JSON body:
@ -1152,8 +1137,7 @@ If attributes are of the Dictionary type, you can also use the indexer format:
"attrs": { "vars.os": "Linux" } "attrs": { "vars.os": "Linux" }
The following example updates the `address` attribute and the custom attribute `os` for the `google.com` host:
Example for existing object `google.com`:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/objects/hosts/google.com' \ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/objects/hosts/google.com' \
-d '{ "attrs": { "address": "8.8.4.4", "vars.os" : "Windows" } }' \ -d '{ "attrs": { "address": "8.8.4.4", "vars.os" : "Windows" } }' \
@ -1170,17 +1154,16 @@ Example for existing object `google.com`:
} }
### <a id="icinga2-api-config-objects-delete"></a> Delete Object ### <a id="icinga2-api-config-objects-delete"></a> Deleting Objects
You can delete objects created using the API by sending a `DELETE` You can delete objects created using the API by sending a `DELETE`
request. Specify the object name inside the url. request.
Parameters | Description Parameters | Description
-----------|-------------- -----------|--------------
cascade | **Optional.** Delete objects depending on the deleted objects (e.g. services on a host). cascade | **Optional.** Delete objects depending on the deleted objects (e.g. services on a host).
**Note**: Objects created by apply rules (services, notifications, etc.) will implicitly require In addition to these parameters a [filter](9-icinga2-api.md#icinga2-api-filters) should be provided.
to pass the `cascade` parameter on host object deletion.
Example for deleting the host object `google.com`: Example for deleting the host object `google.com`:
@ -1366,11 +1349,10 @@ The output is similar to the manual [configuration validation](8-cli-commands.md
## <a id="icinga2-api-clients"></a> API Clients ## <a id="icinga2-api-clients"></a> API Clients
There's a couple of existing clients using the Icinga 2 API There are a couple of existing clients which can be used with the Icinga 2 API:
for various use cases:
* [curl](http://curl.haxx.se) * [curl](http://curl.haxx.se)
* [console cli command](9-icinga2-api.md#icinga2-api-clients-cli-console) * [console CLI command](9-icinga2-api.md#icinga2-api-clients-cli-console)
* [Icinga Studio](9-icinga2-api.md#icinga2-api-clients-icinga-studio) * [Icinga Studio](9-icinga2-api.md#icinga2-api-clients-icinga-studio)
* [Icinga Web 2 Director](https://dev.icinga.org/projects/icingaweb2-modules) * [Icinga Web 2 Director](https://dev.icinga.org/projects/icingaweb2-modules)
@ -1393,23 +1375,35 @@ Icinga Studio is a graphical application to query configuration objects provided
Please check the package repository of your distribution for available Please check the package repository of your distribution for available
packages. packages.
> **Note**
> Icinga Studio does not currently support SSL certificate verification.
The Windows installer includes Icinga Studio already. You must additionally The Windows installer includes Icinga Studio already. You must additionally
install the [WxWidgets library](https://www.wxwidgets.org/downloads/). install the [wxWidgets library](https://github.com/wxWidgets/wxWidgets/releases/download/v3.0.2/wxMSW-3.0.2-Setup.exe).
### <a id="icinga2-api-clients-cli-console"></a> Console Command using the API ### <a id="icinga2-api-clients-cli-console"></a> Console Command using the API
The [console cli command](8-cli-commands.md#cli-command-console) accepts the API URL as `--connect` parameter. Note: You can omit the By default the [console CLI command](8-cli-commands.md#cli-command-console) evaluates expressions in a local interpreter, i.e. independently from your Icinga 2 daemon. Using the `--connect` parameter you can use the Icinga 2 console to evaluate expressions via the API.
username and/or password string and use the environment variables `ICINGA2_API_USERNAME`
and `ICINGA2_API_PASSWORD` instead.
$ icinga2 console --connect 'https://root:icinga@localhost:5665/' > **Note**
> The console does not currently support SSL certificate verification.
Although the password can be specified in the URL process arguments on UNIX platforms are usually visible to other users (e.g. through `ps`). In order to securely specify the user credentials the console supports two environment variables:
Environment variable | Description
---------------------|-------------
ICINGA2_API_USERNAME | The API username.
ICINGA2_API_PASSWORD | The API password.
Here's an example:
$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/'
Icinga 2 (version: v2.3.11-762-g1d327ac) Icinga 2 (version: v2.3.11-762-g1d327ac)
<1> => <1> =>
Once connected fetch the host object and print its attribute `last_check_result`. Once connected you can inspect variables and execute other expressions by entering them at the prompt:
Tip: On systems with enabled auto-completion press <TAB>.
<1> => h = get_host("mbmif.int.netways.de") <1> => var h = get_host("mbmif.int.netways.de")
null null
<2> => h.last_check_result <2> => h.last_check_result
{ {
@ -1441,10 +1435,11 @@ Tip: On systems with enabled auto-completion press <TAB>.
<3> => <3> =>
Use the `--eval` parameter to evaluate a single expression in batch mode. The You can use the `--eval` parameter to evaluate a single expression in batch mode. The output format for batch mode is JSON.
following example fetches the local node object and its check result:
$ icinga2 console --connect 'https://root:icinga@localhost:5665/' --eval "get_host(NodeName).last_check_result.command" | python -m json.tool Here's an example that retrieves the command that was used by Icinga to check the `example-host` host:
$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/' --eval 'get_host("example-host").last_check_result.command' | python -m json.tool
[ [
"/usr/local/sbin/check_ping", "/usr/local/sbin/check_ping",
"-H", "-H",
@ -1455,6 +1450,7 @@ following example fetches the local node object and its check result:
"3000,80%" "3000,80%"
] ]
### <a id="icinga2-api-clients-programmatic-examples"></a> API Clients Programmatic Examples ### <a id="icinga2-api-clients-programmatic-examples"></a> API Clients Programmatic Examples
#### <a id="icinga2-api-clients-programmatic-examples-Python"></a> Example API Client using Python #### <a id="icinga2-api-clients-programmatic-examples-Python"></a> Example API Client using Python
@ -1471,7 +1467,7 @@ Example for **Python** using the `requests` and `json` module:
import requests, json import requests, json
request_url = "https://localhost:5665/v1/status" request_url = "https://localhost:5665/v1/status"
headers = {"Content-Type": "application/json", "Accept": "application/json"} headers = {"Accept": "application/json"}
r = requests.get(request_url, headers=headers, auth=('root', 'icinga'), verify=False) r = requests.get(request_url, headers=headers, auth=('root', 'icinga'), verify=False)
print "Status code: " + str(r.status_code) print "Status code: " + str(r.status_code)
@ -1494,7 +1490,7 @@ Example for **Ruby** using the `rest_client` gem:
request_url = "https://localhost:5665/v1/status" request_url = "https://localhost:5665/v1/status"
options = { :user => "root", :password => "icinga", :verify_ssl => OpenSSL::SSL::VERIFY_NONE } options = { :user => "root", :password => "icinga", :verify_ssl => OpenSSL::SSL::VERIFY_NONE }
headers = {"Content-Type" => "application/json", "Accept" => "application/json"} headers = {"Accept" => "application/json"}
r = RestClient::Resource.new(URI.encode(request_url), options) r = RestClient::Resource.new(URI.encode(request_url), options)
response = r.get(headers) response = r.get(headers)
@ -1517,8 +1513,7 @@ Example for **PHP** using `curl`:
$username = "root"; $username = "root";
$password = "icinga"; $password = "icinga";
$headers = array( $headers = array(
'Accept: application/json', 'Accept: application/json'
'Content-Type: application/json',
); );
$curl = curl_init(); $curl = curl_init();
@ -1564,7 +1559,6 @@ Example for **Perl** using the `Rest::Client` module:
$userpass = "root:icinga"; $userpass = "root:icinga";
my $client = REST::Client->new(); my $client = REST::Client->new();
$client->setHost("https://127.0.0.1:5665"); $client->setHost("https://127.0.0.1:5665");
$client->addHeader("Content-Type", "application/json");
$client->addHeader("Accept", "application/json"); $client->addHeader("Accept", "application/json");
$client->addHeader("Authorization", "Basic ".encode_base64($userpass)); $client->addHeader("Authorization", "Basic ".encode_base64($userpass));
$client->GET("/v1/status"); $client->GET("/v1/status");