tyler.durden/icinga2
1
0
Fork 0
mirror of https://github.com/Icinga/icinga2.git synced 2025-07-26 23:24:09 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update API documentation

Browse Source 
refs #9080
This commit is contained in:
Jean Flach 2015-10-26 15:53:25 +01:00
parent 1ec20a1e8d
commit 0efab37e72
1 changed files with 299 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,4 +1,4 @@
# <a id="icinga2-api"></a> Icinga 2 API # <a id="icinga2-api"></a> Icinga 2 API
## <a id="icinga2-api-introduction"></a> Introduction ## <a id="icinga2-api-introduction"></a> Introduction
@ -16,6 +16,7 @@ make calls to
This chapter will start with a general overview followed by This chapter will start with a general overview followed by
detailed information about specific URL endpoints. detailed information about specific URL endpoints.
### <a id="icinga2-api-requests"></a> Requests ### <a id="icinga2-api-requests"></a> Requests
Any tool capable of making HTTP requests can communicate with Any tool capable of making HTTP requests can communicate with
@ -32,12 +33,13 @@ file.
Supported request methods: Supported request methods:
Method | Usage Method | Usage
--------------|------------------------------------------------------ -------|--------
GET | Retrieve information about configuration objects. Any request using the GET method is read-only and does not affect any objects. 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. 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. 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. 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 ### <a id="icinga2-api-http-statuses"></a> HTTP Statuses
@ -58,6 +60,7 @@ was malformed.
A status in the range of 500 generally means that there was a server-side problem 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. and Icinga 2 is unable to process your request currently.
### <a id="icinga2-api-responses"></a> Responses ### <a id="icinga2-api-responses"></a> Responses
Succesful requests will send back a response body containing a `results` Succesful requests will send back a response body containing a `results`
@ -124,6 +127,7 @@ You can test authentication by sending a GET request to the API:
In case you get an error message make sure to check the API user credentials. In case you get an error message make sure to check the API user credentials.
### <a id="icinga2-api-permissions"></a> Permissions ### <a id="icinga2-api-permissions"></a> Permissions
By default an API user does not have any permissions to perform By default an API user does not have any permissions to perform
@ -162,20 +166,21 @@ the custom host attribute `os` matching the regular expression `^Linux`.
Available permissions for specific URL endpoints: Available permissions for specific URL endpoints:
Permissions | URL Endpoint Permissions | Url Endpoint
--------------------------------------|------------------------ ------------------------------|---------------
actions/&lt;action&gt; | /v1/actions actions/;&lt;action;&gt; | /v1/actions
config/query | /v1/config config/query | /v1/config
config/modify | /v1/config config/modify | /v1/config
objects/query/&lt;type&gt; | /v1/objects objects/query/;&lt;type;&gt; | /v1/objects
objects/create/&lt;type&gt; | /v1/objects objects/create/;&lt;type;&gt; | /v1/objects
objects/modify/&lt;type&gt; | /v1/objects objects/modify/;&lt;type;&gt; | /v1/objects
objects/delete/&lt;type&gt; | /v1/objects objects/delete/;&lt;type;&gt; | /v1/objects
status/query | /v1/status status/query | /v1/status
events/&lt;type&gt; | /v1/events events/&lt;type&gt; | /v1/events
The required actions or types can be replaced by using a wildcard match ("*"). The required actions or types can be replaced by using a wildcard match ("*").
### <a id="icinga2-api-parameters"></a> Parameters ### <a id="icinga2-api-parameters"></a> Parameters
Depending on the request method there are two ways of Depending on the request method there are two ways of
@ -210,28 +215,30 @@ Example for matching all hosts by name (**Note**: `"` are url-encoded as `%22`):
https://localhost:5665/v1/objects/hosts?filter=match(%22nbmif*%22,host.name) https://localhost:5665/v1/objects/hosts?filter=match(%22nbmif*%22,host.name)
### <a id="icinga2-api-output-format"></a>Output Format ### <a id="icinga2-api-output-format"></a> Output Format
The request and reponse body contain a JSON encoded string. The request and response body contain a JSON encoded string.
### <a id="icinga2-api-version"></a>Version
### <a id="icinga2-api-version"></a> Version
Each url contains the version string as prefix (currently "/v1"). Each url contains the version string as prefix (currently "/v1").
### <a id="icinga2-api-url-endpoints"></a>URL Endpoints
### <a id="icinga2-api-url-endpoints"></a> URL Endpoints
The Icinga 2 API provides multiple URL endpoints: The Icinga 2 API provides multiple URL endpoints:
URL Endpoints | Description Url Endpoints | Description
--------------|---------------------------------------------------- --------------|--------------
/v1/actions | Endpoint for running specific [API actions](9-icinga2-api.md#icinga2-api-actions). /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/config | Endpoint for [managing configuration modules](9-icinga2-api.md#icinga2-api-config-management).
/v1/objects | Endpoint for querying, creating, modifying and deleting [config objects](9-icinga2-api.md#icinga2-api-config-objects). /v1/events | Endpoint for subscribing to [API events](9-icinga2-api.md#icinga2-api-actions).
/v1/status | Endpoint for receiving icinga2 [status and statistics](9-icinga2-api.md#icinga2-api-status). /v1/objects | Endpoint for querying, creating, modifying and deleting [config objects](9-icinga2-api.md#icinga2-api-config-objects).
/v1/events | Endpoint for subscribing to [API event streams](9-icinga2-api.md#icinga2-api-event-streams). /v1/status | Endpoint for receiving icinga2 [status and statistics](9-icinga2-api.md#icinga2-api-status).
/v1/types | Endpoint for listing Icinga 2 configuration object types and their attributes. /v1/types | Endpoint for listing Icinga 2 configuration object types and their attributes.
Please check the respective sections for detailed urls and parameters. 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
@ -254,97 +261,172 @@ parameters. If an optional parameter has no default value explicitly stated it
is either 0, NULL, Empty depending on the type. Timestamps are always `time_t`, is either 0, NULL, Empty depending on the type. Timestamps are always `time_t`,
the seconds since the UNIX epoch. the seconds since the UNIX epoch.
### <a id="icinga2-api-actions-process-check-result"></a> Process Check Result Action These parameters may either be delivered as a query string in the form they are
shown here (url/actions/action-name?list=of&parameters) or as key-value pairs in
a json formatted payload. In any case the request needs to be POST.
/v1/actions/process-check-result?exit_status=int&(plugin_output=string)&(performance_data[]=string)&\ All actions return a 200 `OK` or an appropriate error code for each
(check_command[]=string)&(check_source=string)&(execution_end=time_t)&(execution_start=time_t)&\ action performed. So there will be a return for each object matching the filter.
(schedule_end=time_t)&(schedule_start=time_t)
### <a id="icinga2-api-actions-process-check-result"></a> process-check-result
/v1/actions/process-check-result
Target: `Service` or `Host` Target: `Service` or `Host`
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.** Some text output.
performance\_data | string array | **Optional.** One array entry per `;` separated block.
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.** Some text
execution\_end | time\_t | **Optional.**
execution\_start | time\_t | **Optional.**
schedule\_end | time\_t | **Optional.**
schedule\_start | time\_t | **Optional.**
This is used to submit a passive check result for a service or host. Passive This is used to submit a passive check result for a service or host. Passive
checks need to be enabled for the check result to be processed. checks need to be enabled for the check result to be processed.
The `exit_status` field should be one of the following for services:
0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN or for hosts: 0=OK, 1=CRITICAL.
The `plugin_output` field contains text output from the service check, the
performance data is submitted via `performance_data` as one array entry per ';'
separated block.
Example: Example:
$ curl -u root:icinga -k -s 'https://localhost:5665/v1/actions/process-check-result?filter=service.name=="ping6"' curl --user root:icinga -k -X POST "https://127.0.0.1:5665/v1/actions/process-check-result?type=Service&filter=service.name==%22ping6%22" -d \
"{\"exit_status\":2,\"plugin_output\":\"IMAGINARY CHECK\",\"performance_data\":[\"This is just\", \"a drill\"],\"check_command\":[\"some/path\", \"--argument\", \"words\"]}" \
;echo
{"results":
[
{
"code":200.0,"status":"Successfully processed check result for object icinga!ping6."
}
]
}
### reschedule-check
/v1/actions/reschedule-check?next_check=time_t&force_check=boolean ### <a id="icinga2-api-actions-reschedule-check"></a> reschedule-check
/v1/actions/reschedule-check
Target: `Service` or `Host` Target: `Service` or `Host`
Schedules an active check of a collection of hosts or services at `next_check`. Parameter | Type | Description
If the `forced_check" flag is set the checks are performed regardless of what -------------|---------|--------------
time it is (e.g. timeperiod restrictions are ignored) and whether or not active next\_check | time\_t | **Optional.** The next check will be run at this timestamp. Defaults to `now`.
force\_check | boolean | **Optional.** Defaults to `false`. See blow for further information.
If the `forced_check` flag is set the checks are performed regardless of what
time it is (i.e. time period restrictions are ignored) and whether or not active
checks are enabled on a host/service-specific or program-wide basis. checks are enabled on a host/service-specific or program-wide basis.
### send-custom-notification Example:
/v1/actions/send-custom-notification?author=string&comment=string&(force=bool) $ curl --user root:icinga -k -X POST "https://127.0.0.1:5665/v1/actions/reschedule-check?type=Service&filter=service.name==%22ping6%22" -d \
"{\"force_check\":true}" \
;echo
{"results":
[
{
"code":200.0,"status":"Successfully rescheduled check for icinga!ping6."
}
]
}
This will reschedule all services with the name "ping6" to perform a check now
(`next_check` default), ignoring any time periods or whether active checks are
allowed for the service (`force_check=true`).
### <a id="icinga2-api-actions-send-custom-notification"></a> send-custom-notification
/v1/actions/send-custom-notification
Target: `Service` or `Host` Target: `Service` or `Host`
Allows you to send a custom host/service notification. Very useful in dire Parameter | Type | Description
situations, emergencies or to communicate with all admins that are responsible ----------|---------|--------------
for a host or service. The notification requires an `author` and a `comment`, author | string | **Required.** Name of the author, may be empty.
though those may be empty. If `force` (default: false) is set to true the comment | string | **Required.** Comment text, may be empty.
notification will be send regardless of downtimes or whether notifications are force | boolean | **Optional.** Default: false. If true, the notification is sent regardless of downtimes or whether notifications are enabled or not.
enabled or not.
### delay-notification
/v1/actions/delay-notification?timestamp=time_t ### <a id="icinga2-api-actions-delay-notification"></a> delay-notification
/v1/actions/delay-notification
Target: `Service` or `Host` Target: `Service` or `Host`
Delays the next notifications for a collection of services or hosts until Parameter | Type | Description
`timestamp`. Note that this will only have an effect if the service stays in ----------|---------|--------------
the same problem state that it is currently in. If the service changes to timestamp | time\_t | **Required.** Delay notifications until this timestamp.
another state, a new notification may go out before the time you specify in the
`timestamp` argument.
### acknowledge-problem Note that this will only have an effect if the service stays in the same problem
state that it is currently in. If the service changes to another state, a new
notification may go out before the time you specify in the `timestamp` argument.
/v1/actions/acknowledge-problem?author=string&comment=string&(expiry=time_t)&(sticky=bool)&(sticky=bool)
### <a id="icinga2-api-actions-acknowledge-problem"></a> acknowledge-problem
/v1/actions/acknowledge-problem
Target: `Service` or `Host` Target: `Service` or `Host`
Parameter | Type | Description
----------|---------|--------------
author | string | **Required.** Name of the author, may be empty.
comment | string | **Required.** Comment text, may be empty.
expiry | time\_t | **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.
notify | boolean | **Optional.** If `true` a notification will be sent out to contacts to indicate this problem has been acknowledged. The default is false.
Allows you to acknowledge the current problem for hosts or services. By Allows you to acknowledge the current problem for hosts or services. By
acknowledging the current problem, future notifications (for the same state) acknowledging the current problem, future notifications (for the same state)
are disabled. Acknowledgements require an `author` and a `comment` for are disabled.
documentation purposes, though both may be empty. If you set an `expiry` time
the acknowledgement will vanish after that timestamp. If the `sticky` option is
set (the default), the acknowledgement will remain until the host recovers.
Otherwise the acknowledgement will automatically be removed when the host
changes state. If the `notify` option is set, a notification will be sent out
to contacts indicating that the current host problem has been acknowledged, if
set to false (the default) there will be no notification.
### remove-acknowledgement Example:
$ curl --user root:icinga -k -X POST "https://127.0.0.1:5665/v1/actions/acknowledge-problem?type=Service&filter=service.state==2&service.state_type=1" -d \
"{\"author\":\"J. D. Salinger\",\"comment\":\"I thought what I'd do was I'd pretend I was one of those deaf-mutes\",\"notify\":true }" \
;echo
{"results":
[
{"code":200.0,"name":"icinga!down","status":"Attributes updated.","type":"Service"},
{"code":200.0,"name":"icinga!ssh","status":"Attributes updated.","type":"Service"}
]
}
This acknowledges all services which are in a hard critical state and sends out
a notification for them.
### <a id="icinga2-api-actions-remove-acknowledgement"></a> remove-acknowledgement
/v1/actions/remove-acknowledgement /v1/actions/remove-acknowledgement
Target: `Service` or `Host` Target: `Service` or `Host`
Removes acknowledgements for services or hosts. Once the acknowledgement has Removes ALL acknowledgements for services or hosts. Once the acknowledgements
been removed, notifications can once again be sent out. have been removed, notifications will be sent out again.
### add-comment
/v1/actions/add-comment?author=string&comment=string ### <a id="icinga2-api-actions-add-comment"></a> add-comment
/v1/actions/add-comment
Target: `service` or `host` Target: `service` or `host`
parameter | type | description
----------|---------|--------------
author | string | **Required.** name of the author, may be empty.
comment | string | **Required.** Comment text, may be empty.
Adds a `comment` by `author` to services or hosts. Adds a `comment` by `author` to services or hosts.
### remove-comment This action works akin to `acknowledge-problem`, using only the `comment` and
`author` parameters.
### <a id="icinga2-api-actions-remove-comment"></a> remove-comment
/v1/actions/remove-comment /v1/actions/remove-comment
@ -352,61 +434,94 @@ Target: `Service` or `Host`
Removes ALL comments for services or hosts. Removes ALL comments for services or hosts.
### remove-comment-by-id
/v1/actions/remove-comment-by-id?comment_id=int ### <a id="icinga2-api-actions-remove-comment-by-id"></a> remove-comment-by-id
/v1/actions/remove-comment-by-id
Target: `None` Target: `None`
Removes the comment with the legacy ID `comment_id` parameter | type | description
------------|---------|--------------
comment\_id | integer | **Required.** ID of the comment to remove.
### schedule-downtime Removes the comment with the legacy ID `comment_id`.
/v1/actions/schedule-downtime?start_time=time_t&end_time=time_t&duration=int&author=string&comment=string&\
(fixed=bool)&(trigger_id=int) ### <a id="icinga2-api-actions-schedule-downtime"></a> schedule-downtime
/v1/actions/schedule-downtime
Target: `Host` or `Service` Target: `Host` or `Service`
Schedules downtime for services or hosts. If the `fixed` argument is set to parameter | type | description
true (default: false) the downtime will start and end at the times specified by ------------|---------|--------------
the `start_time` and `end_time` arguments. Otherwise, downtime will begin start\_time | time\_t | **Required.** Timestamp marking the begining of the downtime.
between `start_time` and `start_end` and last for `duration` seconds. The end\_time | time\_t | **Required.** Timestamp marking the end of the downtime.
downtime can be triggered by another downtime entry if the `trigger_id` is set duration | integer | **Required.** May be zero. Duration of the downtime in seconds if `fixed` is set to false.
to the ID of another scheduled downtime entry. Set the `trigger_id` argument to fixed | boolean | **Optional.** Default: false. If true the downtime is `fixed`, if false it is `flexible`. See [downtimes](5-advanced-topics.md#Downtimes) for more information.
zero (the default) if the downtime for the specified host should not be trigger\_id | integer | **Optional.** Sets the trigger for a triggered downtime. See [downtimes](5-advanced-topics.md#Downtimes) for more information on triggered downtimes.
triggered by another downtime entry. All downtimes also need a `comment` and
with it an `author`, even though both can be empty.
### remove-downtime Example:
$ curl --user root:icinga -k -X POST "https://127.0.0.1:5665/v1/actions/schedule-downtime?type=Host&filter=host.name=%22icinga2b%22" -d \
"{\"start_time\":`date "+%s"`, \"end_time\":`date --date="next monday" "+%s"`,\"duration\":0,\"author\":\"Lazy admin\",\"comment\":\"Don't care until next monday\"}" \
;echo
{ "results":
[
{
"code":200.0,
"downtime_id":"icinga2b-1445861488-1",
"legacy_id":39.0,
"status":"Successfully scheduled downtime with id 39 for object icinga2b."
}
]
}
### <a id="icinga2-api-actions-remove-downtime"></a> remove-downtime
/v1/actions/remove-downtime /v1/actions/remove-downtime
Target: `Host` or `Service` Target: `Host` or `Service`
Does not take any parameters.
Removes ALL downtimes for services or hosts. Removes ALL downtimes for services or hosts.
### remove-downtime-by-id
/v1/actions/remove-downtime-by-id?downtime_id=int ### <a id="icinga2-api-actions-remove-downtime-by-id"></a> remove-downtime-by-id
/v1/actions/remove-downtime-by-id
Target: `None` Target: `None`
parameter | type | description
-------------|---------|--------------
downtime\_id | integer | **Required.** ID of the downtime to remove.
Removes the comment with the legacy ID `downtime_id` Removes the comment with the legacy ID `downtime_id`
### shutdown-process
### <a id="icinga2-api-actions-shutdown-process"></a> shutdown-process
/v1/actions/shutdown-process /v1/actions/shutdown-process
Target: `None` Target: `None`
Does not take any parameters.
Shuts down Icinga2. May or may not return. Shuts down Icinga2. May or may not return.
### restart-process
### <a id="icinga2-api-actions-restart-process"></a> restart-process
/v1/actions/restart-process /v1/actions/restart-process
Target: `None` Target: `None`
Does not take any parameters.
Restarts Icinga2. May or may not return. Restarts Icinga2. May or may not return.
## <a id="icinga2-api-event-streams"></a> Event Streams ## <a id="icinga2-api-event-streams"></a> Event Streams
@ -414,28 +529,29 @@ Restarts Icinga2. May or may not return.
You can subscribe to event streams by sending a `POST` request. The following You can subscribe to event streams by sending a `POST` request. The following
parameters need to be passed as url parameters: parameters need to be passed as url parameters:
Parameters | Description Parameters | Description
--------------|------------------------------------ -----------|--------------
types | **Required.** Event type(s). Multiple types as url parameters are supported. types | **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 | **Required.** Unique queue name. Multiple HTTP clients can use the same queue with existing filters.
filter | **Optional.** Filter for specific event attributes using [filter expressions](9-icinga2-api.md#icinga2-api-filters). filter | **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
The following event stream types are available: The following event stream types are available:
Type | Description Type | Description
------------------------------|------------------------------ -----------------------|--------------
CheckResult | Check results for hosts and services. CheckResult | Check results for hosts and services.
StateChange | Host/service state changes. StateChange | Host/service state changes.
Notification | Notification events including notified users for hosts and services. Notification | Notification events including notified users for hosts and services.
AcknowledgementSet | Acknowledgement set on hosts and services. AcknowledgementSet | Acknowledgement set on hosts and services.
AcknowledgementCleared | Acknowledgement cleared on hosts and services. AcknowledgementCleared | Acknowledgement cleared on hosts and services.
CommentAdded | Comment added for hosts and services. CommentAdded | Comment added for hosts and services.
CommentRemoved | Comment removed for hosts and services. CommentRemoved | Comment removed for hosts and services.
DowntimeAdded | Downtime added for hosts and services. DowntimeAdded | Downtime added for hosts and services.
DowntimeRemoved | Downtime removed for hosts and services. DowntimeRemoved | Downtime removed for hosts and services.
DowntimeTriggered | Downtime triggered for hosts and services. DowntimeTriggered | Downtime triggered for hosts and services.
Note: Each type requires [api permissions](9-icinga2-api.md#icinga2-api-permissions) Note: Each type requires [api permissions](9-icinga2-api.md#icinga2-api-permissions)
being set. being set.
@ -444,6 +560,7 @@ Example for all downtime events:
&types=DowntimeAdded&types=DowntimeRemoved&types=DowntimeTriggered &types=DowntimeAdded&types=DowntimeRemoved&types=DowntimeTriggered
### <a id="icinga2-api-event-streams-filter"></a> Event Stream Filter ### <a id="icinga2-api-event-streams-filter"></a> Event Stream Filter
Event streams can be filtered by attributes using the prefix `event.`. Event streams can be filtered by attributes using the prefix `event.`.
@ -456,6 +573,7 @@ Example for the `CheckResult` type with the service matching the string "random"
&types=CheckResult&filter=match%28%22random*%22,event.service%29 &types=CheckResult&filter=match%28%22random*%22,event.service%29
### <a id="icinga2-api-event-streams-response"></a> Event Stream Response ### <a id="icinga2-api-event-streams-response"></a> Event Stream Response
The event stream response is separated with new lines. The HTTP client The event stream response is separated with new lines. The HTTP client
@ -469,7 +587,6 @@ Example:
{"check_result":{ ... },"host":"www.icinga.org","service":"ping4","timestamp":1445421324.7226390839,"type":"CheckResult"} {"check_result":{ ... },"host":"www.icinga.org","service":"ping4","timestamp":1445421324.7226390839,"type":"CheckResult"}
{"check_result":{ ... },"host":"www.icinga.org","service":"ping4","timestamp":1445421329.7226390839,"type":"CheckResult"} {"check_result":{ ... },"host":"www.icinga.org","service":"ping4","timestamp":1445421329.7226390839,"type":"CheckResult"}
## <a id="icinga2-api-status"></a> Status and Statistics ## <a id="icinga2-api-status"></a> Status and Statistics
Contains a list of sub URL endpoints which provide the status and statistics Contains a list of sub URL endpoints which provide the status and statistics
@ -482,14 +599,14 @@ Example for the main URL endpoint `/v1/status`:
"results": [ "results": [
{ {
"name": "ApiListener", "name": "ApiListener",
"perfdata": [ ... ], "perfdata": [ ... ],
"status": [ ... ] "status": [ ... ]
}, },
... ...
{ {
"name": "IcingaAplication", "name": "IcingaAplication",
"perfdata": [ ... ], "perfdata": [ ... ],
"status": [ ... ] "status": [ ... ]
}, },
... ...
] ]
@ -531,22 +648,22 @@ Example for the icinga application URL endpoint `/v1/status/IcingaApplication`:
Provides functionality for all configuration object URL endpoints Provides functionality for all configuration object URL endpoints
provided by [config object types](6-object-types.md#object-types): provided by [config object types](6-object-types.md#object-types):
URL Endpoints | Description URL Endpoints | Description
--------------------------------------|---------------------------------------------------- ---------------------------------|--------------
/v1/objects/hosts | Endpoint for retreiving and updating [Host](6-object-types.md#objecttype-host) objects. /v1/objects/hosts | Endpoint for retrieving and updating [Host](6-object-types.md#objecttype-host) objects.
/v1/objects/services | Endpoint for retreiving and updating [Service](6-object-types.md#objecttype-service) objects. /v1/objects/services | Endpoint for retrieving and updating [Service](6-object-types.md#objecttype-service) objects.
/v1/objects/notifications | Endpoint for retreiving and updating [Notification](6-object-types.md#objecttype-notification) objects. /v1/objects/notifications | Endpoint for retrieving and updating [Notification](6-object-types.md#objecttype-notification) objects.
/v1/objects/dependencies | Endpoint for retreiving and updating [Dependency](6-object-types.md#objecttype-dependency) objects. /v1/objects/dependencies | Endpoint for retrieving and updating [Dependency](6-object-types.md#objecttype-dependency) objects.
/v1/objects/users | Endpoint for retreiving and updating [User](6-object-types.md#objecttype-user) objects. /v1/objects/users | Endpoint for retrieving and updating [User](6-object-types.md#objecttype-user) objects.
/v1/objects/checkcommands | Endpoint for retreiving and updating [CheckCommand](6-object-types.md#objecttype-checkcommand) objects. /v1/objects/checkcommands | Endpoint for retrieving and updating [CheckCommand](6-object-types.md#objecttype-checkcommand) objects.
/v1/objects/eventcommands | Endpoint for retreiving and updating [EventCommand](6-object-types.md#objecttype-eventcommand) objects. /v1/objects/eventcommands | Endpoint for retrieving and updating [EventCommand](6-object-types.md#objecttype-eventcommand) objects.
/v1/objects/notificationcommands | Endpoint for retreiving and updating [NotificationCommand](6-object-types.md#objecttype-notificationcommand) objects. /v1/objects/notificationcommands | Endpoint for retrieving and updating [NotificationCommand](6-object-types.md#objecttype-notificationcommand) objects.
/v1/objects/hostgroups | Endpoint for retreiving and updating [HostGroup](6-object-types.md#objecttype-hostgroup) objects. /v1/objects/hostgroups | Endpoint for retrieving and updating [HostGroup](6-object-types.md#objecttype-hostgroup) objects.
/v1/objects/servicegroups | Endpoint for retreiving and updating [ServiceGroup](6-object-types.md#objecttype-servicegroup) objects. /v1/objects/servicegroups | Endpoint for retrieving and updating [ServiceGroup](6-object-types.md#objecttype-servicegroup) objects.
/v1/objects/usergroups | Endpoint for retreiving and updating [UserGroup](6-object-types.md#objecttype-usergroup) objects. /v1/objects/usergroups | Endpoint for retrieving and updating [UserGroup](6-object-types.md#objecttype-usergroup) objects.
/v1/objects/zones | Endpoint for retreiving and updating [Zone](6-object-types.md#objecttype-zone) objects. /v1/objects/zones | Endpoint for retrieving and updating [Zone](6-object-types.md#objecttype-zone) objects.
/v1/objects/endpoints | Endpoint for retreiving and updating [Endpoint](6-object-types.md#objecttype-endpoint) objects. /v1/objects/endpoints | Endpoint for retrieving and updating [Endpoint](6-object-types.md#objecttype-endpoint) objects.
/v1/objects/timeperiods | Endpoint for retreiving and updating [TimePeriod](6-object-types.md#objecttype-timeperiod) objects. /v1/objects/timeperiods | Endpoint for retrieving and updating [TimePeriod](6-object-types.md#objecttype-timeperiod) objects.
All object attributes are prefixed with their respective object type. All object attributes are prefixed with their respective object type.
@ -556,12 +673,13 @@ Example:
Output listing and url parameters use the same syntax. Output listing and url parameters use the same syntax.
### <a id="icinga2-api-config-objects-joins"></a> API Objects and Joins ### <a id="icinga2-api-config-objects-joins"></a> API Objects and Joins
Icinga 2 knows about object relations, e.g. when querying a service object Icinga 2 knows about object relations, i.e. when querying a service object
the query handler will automatically add the referenced host object and its the query handler will automatically add the referenced host object and its
attributes to the result set. If the object reference is null (e.g. no event_command attributes to the result set. If the object reference is null (e.g. when no
defined), the joined results not added to the result set. event\_command is defined), the joined results not added to the result set.
**Note**: Select your required attributes beforehand by passing them to your **Note**: Select your required attributes beforehand by passing them to your
request. The default result set might get huge. request. The default result set might get huge.
@ -569,17 +687,17 @@ request. The default result set might get huge.
Each joined object will use its own attribute name as prefix for the attribute. Each joined object will use its own attribute name as prefix for the attribute.
There is an exception for multiple objects used in dependencies and zones. There is an exception for multiple objects used in dependencies and zones.
Objects with optional relations (e.g. a host notification does not have services) Objects with optional relations (e.g. host notifications without a service)
will not be joined. will not be joined.
Object Type | Object Relations (prefix name) Object Type | Object Relations (prefix name)
--------------|--------------------------------- -------------|---------------------------------
Service | host, notification, check_command, event_command Service | host, notification, check\_command, event\_command
Host | notification, check_command, event_command Host | notification, check\_command, event\_command
Notification | host, service, command, period Notification | host, service, command, period
Dependency | child_host, child_service, parent_host, parent_service, period Dependency | child\_host, child\_service, parent\_host, parent\_service, period
User | period User | period
Zones | parent Zones | parent
### <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
@ -596,9 +714,9 @@ 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 was offline If you add a new cluster instance, or boot an instance which has been offline
for a while, Icinga 2 takes care of the initial object sync for all for a while, Icinga 2 takes care of the initial object sync for all objects
objects created by the API. created by the API.
More information about distributed monitoring, cluster and its More information about distributed monitoring, cluster and its
configuration can be found [here](13-distributed-monitoring-ha.md#distributed-monitoring-high-availability). configuration can be found [here](13-distributed-monitoring-ha.md#distributed-monitoring-high-availability).
@ -619,11 +737,11 @@ This works in a similar fashion for other [config objects](9-icinga2-api.md#icin
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:
Parameters | Description Parameters | Description
--------------|------------------------------------ -----------|--------------
name | **Required.** Name of the newly created config object. name | **Required.** Name of the newly created config object.
templates | **Optional.** Import existing configuration templates for this object type. templates | **Optional.** Import existing configuration templates for this object type.
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:
@ -667,9 +785,10 @@ by the host object.
] ]
} }
#### <a id="icinga2-api-object-query"></a> Query Object #### <a id="icinga2-api-object-query"></a> Query Object
Send a `GET` request including the object name inside the url. Send a `GET` request including the object name inside the URL.
Example for the host `google.com`: Example for the host `google.com`:
@ -690,16 +809,17 @@ attributes must be added one by one, e.g. `?attrs=host.address&attrs=host.name`.
] ]
} }
#### <a id="icinga2-api-objects-modify"></a> Modify Object #### <a id="icinga2-api-objects-modify"></a> Modify Object
Existing objects must be modifed 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:
Parameters | Description Parameters | Description
--------------|------------------------------------ -----------|--------------
name | **Optional.** If not specified inside the url, this is **required**. name | **Optional.** If not specified inside the url, this is **Required.**.
templates | **Optional.** Import existing object configuration templates. templates | **Optional.** Import existing object configuration templates.
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:
@ -724,14 +844,15 @@ Example for existing object `google.com`:
] ]
} }
#### <a id="icinga2-api-hosts-delete"></a> Delete Host #### <a id="icinga2-api-hosts-delete"></a> Delete Host
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. Specify the object name inside the url.
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 implicitely require **Note**: Objects created by apply rules (services, notifications, etc) will implicitely require
to pass the `cascade` parameter on host object deletion. to pass the `cascade` parameter on host object deletion.
@ -761,6 +882,7 @@ In case you are pushing a new configuration stage to a package, Icinga 2 will
validate the configuration asynchronously and populate a status log which validate the configuration asynchronously and populate a status log which
can be fetched in a separated request. can be fetched in a separated request.
### <a id="icinga2-api-config-management-create-package"></a> Create Config Package ### <a id="icinga2-api-config-management-create-package"></a> Create Config Package
Send a `POST` request to a new config package called `puppet` in this example. This Send a `POST` request to a new config package called `puppet` in this example. This
@ -777,6 +899,7 @@ will create a new empty configuration package.
] ]
} }
### <a id="icinga2-api-config-management-create-config-stage"></a> Create Configuration to Package Stage ### <a id="icinga2-api-config-management-create-config-stage"></a> Create Configuration to Package Stage
Send a `POST` request to the URL endpoint `/v1/config/stages` including an existing Send a `POST` request to the URL endpoint `/v1/config/stages` including an existing
@ -811,14 +934,15 @@ system in place.
Icinga 2 automatically creates the following files in the main configuration package Icinga 2 automatically creates the following files in the main configuration package
stage: stage:
File | Description File | Description
--------------|--------------------------- ------------|--------------
status | Contains the [configuration validation](8-cli-commands.md#config-validation) exit code (everything else than 0 indicates an error). status | Contains the [configuration validation](8-cli-commands.md#config-validation) exit code (everything else than 0 indicates an error).
startup.log | Contains the [configuration validation](8-cli-commands.md#config-validation) output. startup.log | Contains the [configuration validation](8-cli-commands.md#config-validation) output.
You can [fetch these files](9-icinga2-api.md#icinga2-api-config-management-fetch-config-package-stage-files) via API call You can [fetch these files](9-icinga2-api.md#icinga2-api-config-management-fetch-config-package-stage-files) via API call
after creating a new stage. after creating a new stage.
### <a id="icinga2-api-config-management-list-config-packages"></a> List Configuration Packages and their Stages ### <a id="icinga2-api-config-management-list-config-packages"></a> List Configuration Packages and their Stages
List all config packages, their active stage and other stages. List all config packages, their active stage and other stages.
@ -841,6 +965,7 @@ The latter already has a stage created, but it is not active.
] ]
} }
### <a id="icinga2-api-config-management-list-config-package-stage-files"></a> List Configuration Packages and their Stages ### <a id="icinga2-api-config-management-list-config-package-stage-files"></a> List Configuration Packages and their Stages
Sent a `GET` request to the URL endpoint `/v1/config/stages` including the package Sent a `GET` request to the URL endpoint `/v1/config/stages` including the package
@ -891,6 +1016,7 @@ for further analysis.
Note: The returned files are plain-text instead of JSON-encoded. Note: The returned files are plain-text instead of JSON-encoded.
### <a id="icinga2-api-config-management-config-package-stage-errors"></a> Configuration Package Stage Errors ### <a id="icinga2-api-config-management-config-package-stage-errors"></a> Configuration Package Stage Errors
Now that we don’t have an active stage for `puppet` yet seen [here](9-icinga2-api.md#icinga2-api-config-management-list-config-packages), Now that we don’t have an active stage for `puppet` yet seen [here](9-icinga2-api.md#icinga2-api-config-management-list-config-packages),