]
}
-Tip: If you are working on the CLI with curl you can also use [jq](https://stedolan.github.io/jq/)
-to format the returned JSON output in a readable manner. The documentation
-prefers `python -m json.tool` as Python is available nearly everywhere.
+> **Tip**
+>
+> You can use the `pretty` parameter to beautify the JSON response with Icinga v2.9+.
+
+You can also use [jq](https://stedolan.github.io/jq/) or `python -m json.tool`
+in combination with curl on the CLI.
+
+```
+curl ... | python -m json.tool
+```
> **Note**
>
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
+ -d '{ "type": "Service", "filter": "service.name==\"ping6\"", "pretty": true }'
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
to worry about escaping values:
$ curl -k -s -u 'root:icinga' -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5665/v1/objects/hosts' \
- -d '{ "filter": "host.vars.os == os", "filter_vars": { "os": "Linux" } }'
+ -d '{ "filter": "host.vars.os == os", "filter_vars": { "os": "Linux" }, "pretty": true }'
We're using [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override) here because
the HTTP specification does not allow message bodies for GET requests.
Parameters | Type | Description
-----------|--------------|----------------------------
- attrs | string array | **Optional.** Limits attributes in the output.
- joins | string array | **Optional.** Join related object types and their attributes (`?joins=host` for the entire set, or selectively by `?joins=host.name`).
- meta | string array | **Optional.** Enable meta information using `?meta=used_by` (references from other objects) and/or `?meta=location` (location information). Defaults to disabled.
+ attrs | Array | **Optional.** Limited attribute list in the output.
+ joins | Array | **Optional.** Join related object types and their attributes specified as list (`?joins=host` for the entire set, or selectively by `?joins=host.name`).
+ meta | Array | **Optional.** Enable meta information using `?meta=used_by` (references from other objects) and/or `?meta=location` (location information) specified as list. Defaults to disabled.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) may be provided.
You can limit the output to specific attributes using the `attrs` URL parameter:
- $ curl -k -s -u root:icinga 'https://localhost:5665/v1/objects/hosts/example.localdomain?attrs=name&attrs=address' | python -m json.tool
+ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/objects/hosts/example.localdomain?attrs=name&attrs=address&pretty=1'
{
"results": [
{
Attribute | Type | Description
-----------|------------|--------------
- name | string | Full object name.
- type | string | Object type.
- attrs | dictionary | Object attributes (can be filtered using the URL parameter `attrs`).
- joins | dictionary | [Joined object types](12-icinga2-api.md#icinga2-api-config-objects-query-joins) as key, attributes as nested dictionary. Disabled by default.
- meta | dictionary | Contains `used_by` object references. Disabled by default, enable it using `?meta=used_by` as URL parameter.
+ name | String | Full object name.
+ type | String | Object type.
+ attrs | Dictionary | Object attributes (can be filtered using the URL parameter `attrs`).
+ joins | Dictionary | [Joined object types](12-icinga2-api.md#icinga2-api-config-objects-query-joins) as key, attributes as nested dictionary. Disabled by default.
+ meta | Dictionary | Contains `used_by` object references. Disabled by default, enable it using `?meta=used_by` as URL parameter.
#### Object Query Joins <a id="icinga2-api-config-objects-query-joins"></a>
attributes for the service. The query also returns the host's `name` and `address` attribute
via a join:
- $ 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&pretty=1'
{
"results": [
for hosts and services, you can use the following query URL (similar example
for downtimes):
- https://localhost:5665/v1/objects/comments?joins=host&joins=service
+ https://localhost:5665/v1/objects/comments?joins=host&joins=service
This is another example for listing all service objects which are unhandled problems (state is not OK
and no downtime or acknowledgement set). We're using [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
here because we want to pass all query attributes in the request body.
- $ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://127.0.0.1:5665/v1/objects/services' \
- -d '{ "joins": [ "host.name", "host.address" ], "attrs": [ "name", "state", "downtime_depth", "acknowledgement" ], "filter": "service.state != ServiceOK && service.downtime_depth == 0.0 && service.acknowledgement == 0.0" }' | python -m json.tool
+ $ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://127.0.0.1:5665/v1/objects/services' \
+ -d '{ "joins": [ "host.name", "host.address" ], "attrs": [ "name", "state", "downtime_depth", "acknowledgement" ], "filter": "service.state != ServiceOK && service.downtime_depth == 0.0 && service.acknowledgement == 0.0", "pretty": true }'
{
"results": [
method:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5665/v1/objects/comments' \
- -d '{ "joins": [ "service.name", "service.acknowledgement", "service.acknowledgement_expiry" ], "attrs": [ "author", "text" ], "filter": "service.acknowledgement!=0 && service.acknowledgement_expiry==0" }' | python -m json.tool
+ -d '{ "joins": [ "service.name", "service.acknowledgement", "service.acknowledgement_expiry" ], "attrs": [ "author", "text" ], "filter": "service.acknowledgement!=0 && service.acknowledgement_expiry==0", "pretty": true }'
{
"results": [
Parameters | Type | Description
-----------|--------------|--------------------------
- templates | string array | **Optional.** Import existing configuration templates for this object type. Note: These templates must either be statically configured or provided in [config packages](12-icinga2-api.md#icinga2-api-config-management)-
- attrs | dictionary | **Required.** Set specific object attributes for this [object type](09-object-types.md#object-types).
+ templates | Array | **Optional.** Import existing configuration templates for this object type. Note: These templates must either be statically configured or provided in [config packages](12-icinga2-api.md#icinga2-api-config-management)-
+ attrs | Dictionary | **Required.** Set specific object attributes for this [object type](09-object-types.md#object-types).
The object name must be specified as part of the URL path. For objects with composite names (e.g. services)
the full name (e.g. `example.localdomain!http`) must be specified.
Example for creating the new host object `example.localdomain`:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \
- -d '{ "templates": [ "generic-host" ], "attrs": { "address": "192.168.1.1", "check_command": "hostalive", "vars.os" : "Linux" } }' \
- | python -m json.tool
+ -d '{ "templates": [ "generic-host" ], "attrs": { "address": "192.168.1.1", "check_command": "hostalive", "vars.os" : "Linux" }, "pretty": true }'
{
"results": [
{
which is required for host objects:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \
- -d '{ "attrs": { "address": "192.168.1.1", "vars.os" : "Linux" } }' \
- | python -m json.tool
+ -d '{ "attrs": { "address": "192.168.1.1", "vars.os" : "Linux" }, "pretty": true }'
{
"results": [
{
Parameters | Type | Description
-----------|------------|---------------------------
- attrs | dictionary | **Required.** Set specific object attributes for this [object type](09-object-types.md#object-types).
+ attrs | Dictionary | **Required.** Set specific object attributes for this [object type](09-object-types.md#object-types).
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) should be provided.
The following example updates the `address` attribute and the custom attribute `os` for the `example.localdomain` host:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/objects/hosts/example.localdomain' \
- -d '{ "attrs": { "address": "192.168.1.2", "vars.os" : "Windows" } }' \
- | python -m json.tool
+ -d '{ "attrs": { "address": "192.168.1.2", "vars.os" : "Windows" }, "pretty": true }'
{
"results": [
{
Parameters | Type | Description
-----------|---------|---------------
- cascade | boolean | **Optional.** Delete objects depending on the deleted objects (e.g. services on a host).
+ cascade | Boolean | **Optional.** Delete objects depending on the deleted objects (e.g. services on a host).
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) should be provided.
Example for deleting the host object `example.localdomain`:
- $ curl -k -s -u root:icinga -H 'Accept: application/json' -X DELETE 'https://localhost:5665/v1/objects/hosts/example.localdomain?cascade=1' | python -m json.tool
+ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X DELETE 'https://localhost:5665/v1/objects/hosts/example.localdomain?cascade=1&pretty=1'
{
"results": [
{
Parameter | Type | Description
------------------|--------------|--------------
- 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. Does **not** contain the performance data.
- 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\_source | string | **Optional.** Usually the name of the `command_endpoint`
+ exit\_status | Number | **Required.** For services: 0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN, for hosts: 0=OK, 1=CRITICAL.
+ plugin\_output | String | **Required.** One or more lines of the plugin main output. Does **not** contain the performance data.
+ performance\_data | Array | **Optional.** The performance data.
+ check\_command | 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`
+ execution\_start | Timestamp | **Optional.** The timestamp where a script/process started its execution.
+ execution\_end | Timestamp | **Optional.** The timestamp where a script/process ended its execution. This timestamp is used in features to determine e.g. the metric timestamp.
+ ttl | Number | **Optional.** Time-to-live duration in seconds for this check result. The next expected check result is `now + ttl` where freshness checks are executed.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
Example for the service `passive-ping6`:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/process-check-result?service=example.localdomain!passive-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": "example.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": "example.localdomain", "pretty": true }'
{
"results": [
You can avoid URL encoding of white spaces in object names by using the `filter` attribute in the request body.
+> **Note**
+>
+> Multi-line plugin output requires the following format: The first line is treated as `short` plugin output corresponding
+> to the first line of the plugin output. Subsequent lines are treated as `long` plugin output. Please note that the
+> performance data is separated from the plugin output and has to be passed as `performance_data` attribute.
+
### reschedule-check <a id="icinga2-api-actions-reschedule-check"></a>
Reschedule a check for hosts and services. The check can be forced if required.
Parameter | Type | Description
-------------|-----------|--------------
- 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.
+ 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.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
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' \
- -d '{ "type": "Service", "filter": "service.name==\"ping6\"", "force_check": true }' | python -m json.tool
+ -d '{ "type": "Service", "filter": "service.name==\"ping6\"", "force_check": true, "pretty": true }'
{
"results": [
Parameter | Type | Description
----------|---------|--------------
- author | string | **Required.** Name of the author, 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.
+ author | String | **Required.** Name of the author, 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.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
host owners:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/send-custom-notification' \
- -d '{ "type": "Host", "author": "icingaadmin", "comment": "System is going down for maintenance", "force": true }' | python -m json.tool
+ -d '{ "type": "Host", "author": "icingaadmin", "comment": "System is going down for maintenance", "force": true, "pretty": true }'
{
"results": [
Parameter | Type | Description
----------|-----------|--------------
- timestamp | timestamp | **Required.** Delay notifications until this timestamp.
+ timestamp | Timestamp | **Required.** Delay notifications until this timestamp.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
Example:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/delay-notification' \
- -d '{ "type": "Service", "timestamp": 1446389894 }' | python -m json.tool
+ -d '{ "type": "Service", "timestamp": 1446389894, "pretty": true }'
{
"results": [
Parameter | Type | Description
---------------------|-----------|--------------
- author | string | **Required.** Name of the author, may be empty.
- comment | string | **Required.** Comment text, may be empty.
- expiry | timestamp | **Optional.** Whether the acknowledgement will be removed at the timestamp.
- sticky | boolean | **Optional.** Whether the acknowledgement will be set until the service or host fully recovers. Defaults to `false`.
- notify | boolean | **Optional.** Whether a notification of the `Acknowledgement` type will be sent. Defaults to `false`.
- persistent | boolean | **Optional.** When the comment is of type `Acknowledgement` and this is set to `true`, the comment will remain after the acknowledgement recovers or expires. Defaults to `false`.
+ author | String | **Required.** Name of the author, may be empty.
+ comment | String | **Required.** Comment text, may be empty.
+ expiry | Timestamp | **Optional.** Whether the acknowledgement will be removed at the timestamp.
+ sticky | Boolean | **Optional.** Whether the acknowledgement will be set until the service or host fully recovers. Defaults to `false`.
+ notify | Boolean | **Optional.** Whether a notification of the `Acknowledgement` type will be sent. Defaults to `false`.
+ persistent | Boolean | **Optional.** When the comment is of type `Acknowledgement` and this is set to `true`, the comment will remain after the acknowledgement recovers or expires. Defaults to `false`.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
a notification for them:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/acknowledge-problem?type=Service&filter=service.state==2&service.state_type=1' \
- -d '{ "author": "icingaadmin", "comment": "Global outage. Working on it.", "notify": true }' | python -m json.tool
+ -d '{ "author": "icingaadmin", "comment": "Global outage. Working on it.", "notify": true, "pretty": true }'
{
"results": [
The example removes all service acknowledgements:
- $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-acknowledgement?type=Service' | python -m json.tool
+ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-acknowledgement?type=Service&pretty=1'
{
"results": [
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.", "pretty": true }'
{
"results": [
{
Example for a simple filter using the `comment` URL parameter:
- $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-comment?comment=example2.localdomain!ping4!mbmif.local-1446986367-0' | python -m json.tool
+ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-comment?comment=example2.localdomain!ping4!mbmif.local-1446986367-0&pretty=1'
{
"results": [
{
Example for removing all service comments using a service name filter for `ping4`:
- $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-comment?filter=service.name==%22ping4%22&type=Service' | python -m json.tool
+ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-comment?filter=service.name==%22ping4%22&type=Service&pretty=1'
{
"results": [
{
Parameter | Type | Description
--------------|-----------|--------------
- author | string | **Required.** Name of the author.
- comment | string | **Required.** Comment text.
- start\_time | timestamp | **Required.** Timestamp marking the beginning of the downtime.
- end\_time | timestamp | **Required.** Timestamp marking the end of the downtime.
- fixed | boolean | **Optional.** Defaults to `true`. If true, the downtime is `fixed` otherwise `flexible`. See [downtimes](08-advanced-topics.md#downtimes) for more information.
- duration | integer | **Required for flexible downtimes.** Duration of the downtime in seconds if `fixed` is set to false.
- trigger\_name | string | **Optional.** Sets the trigger for a triggered downtime. See [downtimes](08-advanced-topics.md#downtimes) for more information on triggered downtimes.
- child\_options | integer | **Optional.** Schedule child downtimes. `0` does not do anything, `1` schedules child downtimes triggered by this downtime, `2` schedules non-triggered downtimes. Defaults to `0`.
+ author | String | **Required.** Name of the author.
+ comment | String | **Required.** Comment text.
+ start\_time | Timestamp | **Required.** Timestamp marking the beginning of the downtime.
+ end\_time | Timestamp | **Required.** Timestamp marking the end of the downtime.
+ fixed | Boolean | **Optional.** Defaults to `true`. If true, the downtime is `fixed` otherwise `flexible`. See [downtimes](08-advanced-topics.md#downtimes) for more information.
+ duration | Number | **Required for flexible downtimes.** Duration of the downtime in seconds if `fixed` is set to false.
+ trigger\_name | String | **Optional.** Sets the trigger for a triggered downtime. See [downtimes](08-advanced-topics.md#downtimes) for more information on triggered downtimes.
+ child\_options | Number | **Optional.** Schedule child downtimes. `0` does not do anything, `1` schedules child downtimes triggered by this downtime, `2` schedules non-triggered downtimes. Defaults to `0`.
In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
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", "pretty": true }'
{
"results": [
{
Example for a simple filter using the `downtime` URL parameter:
- $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-downtime?downtime=example.localdomain!ping4!mbmif.local-1446979168-6' | python -m json.tool
+ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-downtime?downtime=example.localdomain!ping4!mbmif.local-1446979168-6&pretty=1'
{
"results": [
{
Example for removing all host downtimes using a host name filter for `example.localdomain`:
- $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-downtime?filter=host.name==%22example.localdomain%22&type=Host' | python -m json.tool
+ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-downtime?filter=host.name==%22example.localdomain%22&type=Host&pretty=1'
{
"results": [
{
"filter_vars": {
"filterHost": "example.localdomain",
"filterAuthor": "icingaadmin"
- }
- }' | python -m json.tool
+ },
+ "pretty": true
+ }'
{
"results": [
Example:
- $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/shutdown-process' | python -m json.tool
+ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/shutdown-process?pretty=1'
{
"results": [
Example:
- $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/restart-process' | python -m json.tool
+ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/restart-process?pretty=1'
{
"results": [
Parameter | Type | Description
--------------|-----------|--------------
- cn | string | **Required.** The host's common name for which the ticket should be geenerated.
+ cn | String | **Required.** The host's common name for which the ticket should be geenerated.
Example:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/generate-ticket' \
- -d '{ "cn": "icinga2-client1.localdomain" }' | python -m json.tool
+ -d '{ "cn": "icinga2-client1.localdomain", "pretty": true }'
{
"results": [
{
Parameter | Type | Description
-----------|--------------|-------------
- types | string array | **Required.** Event type(s). Multiple types as URL parameters are supported.
- 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 | string | **Optional.** Filter for specific event attributes using [filter expressions](12-icinga2-api.md#icinga2-api-filters).
+ types | Array | **Required.** Event type(s). Multiple types as URL parameters are supported.
+ 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 | String | **Optional.** Filter for specific event attributes using [filter expressions](12-icinga2-api.md#icinga2-api-filters).
### Event Stream Types <a id="icinga2-api-event-streams-types"></a>
&types=DowntimeAdded&types=DowntimeRemoved&types=DowntimeTriggered
+#### <a id="icinga2-api-event-streams-type-checkresult"></a> Event Stream Type: CheckResult
+
+ Name | Type | Description
+ --------------|---------------|--------------------------
+ type | String | Event type `CheckResult`.
+ timestamp | Timestamp | Unix timestamp when the event happened.
+ host | String | [Host](09-object-types.md#objecttype-host) name.
+ service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host check result.
+ check\_result | CheckResult | Serialized [CheckResult](08-advanced-topics.md#advanced-value-types-checkresult) value type.
+
+#### <a id="icinga2-api-event-streams-type-statechange"></a> Event Stream Type: StateChange
+
+ Name | Type | Description
+ --------------|---------------|--------------------------
+ type | String | Event type `StateChange`.
+ timestamp | Timestamp | Unix timestamp when the event happened.
+ host | String | [Host](09-object-types.md#objecttype-host) name.
+ service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host state change.
+ state | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state.
+ state\_type | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state type.
+ check\_result | CheckResult | Serialized [CheckResult](08-advanced-topics.md#advanced-value-types-checkresult) value type.
+
+#### <a id="icinga2-api-event-streams-type-notification"></a> Event Stream Type: Notification
+
+ Name | Type | Description
+ --------------|---------------|--------------------------
+ type | String | Event type `Notification`.
+ timestamp | Timestamp | Unix timestamp when the event happened.
+ host | String | [Host](09-object-types.md#objecttype-host) name.
+ service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host notification.
+ users | Array | List of notified [user](09-object-types.md#objecttype-user) names.
+ notification\_type | String | [$notification.type$](03-monitoring-basics.md#notification-runtime-macros) runtime macro value.
+ author | String | [$notification.author$](03-monitoring-basics.md#notification-runtime-macros) runtime macro value.
+ text | String | [$notification.comment$](03-monitoring-basics.md#notification-runtime-macros) runtime macro value.
+ check\_result | CheckResult | Serialized [CheckResult](08-advanced-topics.md#advanced-value-types-checkresult) value type.
+
+#### <a id="icinga2-api-event-streams-type-flapping"></a> Event Stream Type: Flapping
+
+ Name | Type | Description
+ ------------------|---------------|--------------------------
+ type | String | Event type `Flapping`.
+ timestamp | Timestamp | Unix timestamp when the event happened.
+ host | String | [Host](09-object-types.md#objecttype-host) name.
+ service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host flapping event.
+ state | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state.
+ state\_type | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state type.
+ is\_flapping | Boolean | Whether this object is flapping.
+ current\_flapping | Number | Current flapping value in percent (added in 2.8).
+ threshold\_low | Number | Low threshold in percent (added in 2.8).
+ threshold\_high | Number | High threshold in percent (added in 2.8).
+
+#### <a id="icinga2-api-event-streams-type-acknowledgementset"></a> Event Stream Type: AcknowledgementSet
+
+ Name | Type | Description
+ --------------|---------------|--------------------------
+ type | String | Event type `AcknowledgementSet`.
+ timestamp | Timestamp | Unix timestamp when the event happened.
+ host | String | [Host](09-object-types.md#objecttype-host) name.
+ service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host acknowledgement.
+ state | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state.
+ state\_type | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state type.
+ author | String | Acknowledgement author set via [acknowledge-problem](12-icinga2-api.md#icinga2-api-actions-acknowledge-problem) action.
+ comment | String | Acknowledgement comment set via [acknowledge-problem](12-icinga2-api.md#icinga2-api-actions-acknowledge-problem) action.
+ acknowledgement\_type | Number | 0 = None, 1 = Normal, 2 = Sticky. `sticky` can be set via [acknowledge-problem](12-icinga2-api.md#icinga2-api-actions-acknowledge-problem) action.
+ notify | Boolean | Notifications were enabled via [acknowledge-problem](12-icinga2-api.md#icinga2-api-actions-acknowledge-problem) action.
+ expiry | Timestamp | Acknowledgement expire time set via [acknowledge-problem](12-icinga2-api.md#icinga2-api-actions-acknowledge-problem) action.
+
+#### <a id="icinga2-api-event-streams-type-acknowledgementcleared"></a> Event Stream Type: AcknowledgementCleared
+
+ Name | Type | Description
+ --------------|---------------|--------------------------
+ type | String | Event type `AcknowledgementCleared`.
+ timestamp | Timestamp | Unix timestamp when the event happened.
+ host | String | [Host](09-object-types.md#objecttype-host) name.
+ service | String | [Service](09-object-types.md#objecttype-service) name. Optional if this is a host acknowledgement.
+ state | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state.
+ state\_type | Number | [Host](09-object-types.md#objecttype-host) or [service](09-object-types.md#objecttype-service) state type.
+
+#### <a id="icinga2-api-event-streams-type-commentadded"></a> Event Stream Type: CommentAdded
+
+ Name | Type | Description
+ --------------|---------------|--------------------------
+ type | String | Event type `CommentAdded`.
+ timestamp | Timestamp | Unix timestamp when the event happened.
+ comment | Dictionary | Serialized [Comment](09-object-types.md#objecttype-comment) object.
+
+#### <a id="icinga2-api-event-streams-type-commentremoved"></a> Event Stream Type: CommentRemoved
+
+ Name | Type | Description
+ --------------|---------------|--------------------------
+ type | String | Event type `CommentRemoved`.
+ timestamp | Timestamp | Unix timestamp when the event happened.
+ comment | Dictionary | Serialized [Comment](09-object-types.md#objecttype-comment) object.
+
+#### <a id="icinga2-api-event-streams-type-downtimeadded"></a> Event Stream Type: DowntimeAdded
+
+ Name | Type | Description
+ --------------|---------------|--------------------------
+ type | String | Event type `DowntimeAdded`.
+ timestamp | Timestamp | Unix timestamp when the event happened.
+ downtime | Dictionary | Serialized [Comment](09-object-types.md#objecttype-downtime) object.
+
+#### <a id="icinga2-api-event-streams-type-downtimeremoved"></a> Event Stream Type: DowntimeRemoved
+
+ Name | Type | Description
+ --------------|---------------|--------------------------
+ type | String | Event type `DowntimeRemoved`.
+ timestamp | Timestamp | Unix timestamp when the event happened.
+ downtime | Dictionary | Serialized [Comment](09-object-types.md#objecttype-downtime) object.
+
+
+#### <a id="icinga2-api-event-streams-type-downtimestarted"></a> Event Stream Type: DowntimeStarted
+
+ Name | Type | Description
+ --------------|---------------|--------------------------
+ type | String | Event type `DowntimeStarted`.
+ timestamp | Timestamp | Unix timestamp when the event happened.
+ downtime | Dictionary | Serialized [Comment](09-object-types.md#objecttype-downtime) object.
+
+
+#### <a id="icinga2-api-event-streams-type-downtimetriggered"></a> Event Stream Type: DowntimeTriggered
+
+ Name | Type | Description
+ --------------|---------------|--------------------------
+ type | String | Event type `DowntimeTriggered`.
+ timestamp | Timestamp | Unix timestamp when the event happened.
+ downtime | Dictionary | Serialized [Comment](09-object-types.md#objecttype-downtime) object.
+
### Event Stream Filter <a id="icinga2-api-event-streams-filter"></a>
Example:
- $ curl -k -s -u root:icinga 'https://localhost:5665/v1/status' | python -m json.tool
+ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/status?pretty=1'
{
"results": [
{
You can limit the output by specifying a status type in the URL, e.g. `IcingaApplication`:
- $ curl -k -s -u root:icinga 'https://localhost:5665/v1/status/IcingaApplication' | python -m json.tool
+ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/status/IcingaApplication?pretty=1'
{
"results": [
{
will create a new empty configuration package.
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \
- 'https://localhost:5665/v1/config/packages/example-cmdb' | python -m json.tool
+ 'https://localhost:5665/v1/config/packages/example-cmdb?pretty=1'
{
"results": [
{
Send a `POST` request to the URL endpoint `/v1/config/stages` and add the name of an existing
configuration package to the URL path (e.g. `example-cmdb`).
The request body must contain the `files` attribute with the value being
-a dictionary of file targets and their content.
+a dictionary of file targets and their content. You can also specify an optional `reload` attribute
+that will tell icinga2 to reload after stage config validation. By default this is set to `true`.
The file path requires one of these two directories inside its path:
intentional.
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \
- -d '{ "files": { "conf.d/test.conf": "object Host \"cmdb-host\" { chec_command = \"dummy\" }" } }' \
- 'https://localhost:5665/v1/config/stages/example-cmdb' | python -m json.tool
+ -d '{ "files": { "conf.d/test.conf": "object Host \"cmdb-host\" { chec_command = \"dummy\" }" }, "pretty": true }' \
+ 'https://localhost:5665/v1/config/stages/example-cmdb'
{
"results": [
{
"code": 200.0,
"package": "example-cmdb",
"stage": "example.localdomain-1441625839-0",
- "status": "Created stage."
+ "status": "Created stage. Icinga2 will reload."
}
]
}
The Icinga 2 API returns the `package` name this stage was created for, and also
generates a unique name for the `stage` attribute you'll need for later requests.
-Icinga 2 automatically restarts the daemon in order to activate the new config stage.
-If the validation for the new config stage failed, the old stage and its configuration objects
-will remain active.
+Icinga 2 automatically restarts the daemon in order to activate the new config stage. This
+can be disabled by setting `reload` to `false` in the request.
+If the validation for the new config stage failed, the old stage
+and its configuration objects will remain active.
> **Note**
>
The following example contains one configuration package `example-cmdb`. The package does not currently
have an active stage.
- $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/packages' | python -m json.tool
+ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/packages?pretty=1'
{
"results": [
{
the URL endpoint `/v1/config/stages`. You need to include
the package name (`example-cmdb`) and stage name (`example.localdomain-1441625839-0`) in the URL:
- $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/stages/example-cmdb/example.localdomain-1441625839-0' | python -m json.tool
+ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/stages/example-cmdb/example.localdomain-1441625839-0?pretty=1'
{
"results": [
...
in the `example-cmdb` configuration package:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X DELETE \
- 'https://localhost:5665/v1/config/stages/example-cmdb/example.localdomain-1441133065-1' | python -m json.tool
+ 'https://localhost:5665/v1/config/stages/example-cmdb/example.localdomain-1441133065-1?pretty=1'
{
"results": [
{
This example entirely deletes the configuration package `example-cmdb`:
$ curl -k -s -u root:icinga -H 'Accept: application/json' -X DELETE \
- 'https://localhost:5665/v1/config/packages/example-cmdb' | python -m json.tool
+ 'https://localhost:5665/v1/config/packages/example-cmdb?pretty=1'
{
"results": [
{
Each response entry in the results array contains the following attributes:
- Attribute | Type | Description
- ---------------|--------------|---------------------
- name | string | The type name.
- plural_name | string | The plural type name.
- fields | dictionary | Available fields including details on e.g. the type and attribute accessibility.
- abstract | boolean | Whether objects can be instantiated for this type.
- base | boolean | The base type (e.g. `Service` inherits fields and prototype methods from `Checkable`).
- prototype_keys | string array | Available prototype methods.
+ Attribute | Type | Description
+ ----------------|--------------|---------------------
+ name | String | The type name.
+ plural\_name | String | The plural type name.
+ fields | Dictionary | Available fields including details on e.g. the type and attribute accessibility.
+ abstract | Boolean | Whether objects can be instantiated for this type.
+ base | Boolean | The base type (e.g. `Service` inherits fields and prototype methods from `Checkable`).
+ prototype\_keys | Array | Available prototype methods.
In order to view a specific configuration object type specify its name inside the URL path:
- $ curl -k -s -u root:icinga 'https://localhost:5665/v1/types/Object' | python -m json.tool
+ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/types/Object?pretty=1'
{
"results": [
{
Parameter | Type | Description
-----------|--------------|-------------
- session | string | **Optional.** The session ID. Ideally this should be a GUID or some other unique identifier.
- command | string | **Required.** Command expression for execution or auto-completion.
- sandboxed | number | **Optional.** Whether runtime changes are allowed or forbidden. Defaults to disabled.
+ session | String | **Optional.** The session ID. Ideally this should be a GUID or some other unique identifier.
+ command | String | **Required.** Command expression for execution or auto-completion.
+ sandboxed | Number | **Optional.** Whether runtime changes are allowed or forbidden. Defaults to disabled.
The [API permission](12-icinga2-api.md#icinga2-api-permissions) `console` is required for executing
expressions.
Example for fetching the command line from the local host's last check result:
- $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/console/execute-script?command=get_host(NodeName).last_check_result.command&sandboxed=0&session=bb75fd7c-c686-407d-9688-582c04227756' | python -m json.tool
+ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/console/execute-script?command=get_host(NodeName).last_check_result.command&sandboxed=0&session=bb75fd7c-c686-407d-9688-582c04227756&pretty=1'
{
"results": [
{
Example for fetching auto-completion suggestions for the `Host.` type. This works in a
similar fashion when pressing TAB inside the [console CLI command](11-cli-commands.md#cli-command-console):
- $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/console/auto-complete-script?command=Host.&sandboxed=0&session=bb75fd7c-c686-407d-9688-582c04227756' | python -m json.tool
+ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/console/auto-complete-script?command=Host.&sandboxed=0&session=bb75fd7c-c686-407d-9688-582c04227756&pretty=1'
{
"results": [
{
projects / icinga2 / blobdiff