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

Update API actions and documentation

Browse Source 
refs #9080 #9105
This commit is contained in:
Jean Flach 2015-10-27 14:15:07 +01:00
parent 2f2269b477
commit 2fc042e231
3 changed files with 86 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -49,8 +49,8 @@ including error codes.
When an error occurs, the response body will contain additional information When an error occurs, the response body will contain additional information
about the problem and its source. about the problem and its source.
A status in the range between 200 and 299 generally means that the request was succesful A status code between 200 and 299 generally means that the request was
and no error was encountered. succesful.
Return codes within the 400 range indicate that there was a problem with the Return codes within the 400 range indicate that there was a problem with the
request. Either you did not authenticate correctly, you are missing the authorization request. Either you did not authenticate correctly, you are missing the authorization
@ -166,7 +166,7 @@ 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/;<action;> | /v1/actions actions/;<action;> | /v1/actions
config/query | /v1/config config/query | /v1/config
@ -203,14 +203,13 @@ Example for JSON body:
#### <a id="icinga2-api-filters"></a> Filters #### <a id="icinga2-api-filters"></a> Filters
Use the same syntax as for apply rule expressions Uses the same syntax as apply rule expressions for filtering specific objects.
for filtering specific objects.
Example for all services in NOT-OK state: Example for a filter matching all services in NOT-OK state:
https://localhost:5665/v1/objects/services?filter=service.state!=0 https://localhost:5665/v1/objects/services?filter=service.state!=ServiceOK
Example for matching all hosts by name (**Note**: `"` are url-encoded as `%22`): Example for a filter 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)
@ -227,7 +226,7 @@ Each url contains the version string as prefix (currently "/v1").
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).
@ -252,45 +251,34 @@ Some actions require specific target types (e.g. `type=Host`) and a
[filter expression](9-icinga2-api.md#icinga2-api-filters). [filter expression](9-icinga2-api.md#icinga2-api-filters).
For each object matching the filter the action in question is performed once. For each object matching the filter the action in question is performed once.
In the following each the actions are listed with their parameters, targets and
examples. The calls are first shown with all their possible query parameters and
their type. Optional parameters are encapsulated by `()` and `[]` mark array
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`,
the seconds since the UNIX epoch.
These parameters may either be delivered as a query string in the form they are 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 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. a json formatted payload, you can also mix them. In any case the request needs
to be POST.
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. So there will be a return for each object matching the filter. action performed. So there will be a return for each object matching the filter.
### <a id="icinga2-api-actions-process-check-result"></a> process-check-result ### <a id="icinga2-api-actions-process-check-result"></a> process-check-result
/v1/actions/process-check-result /v1/actions/process-check-result
Target: `Service` or `Host`
Parameter | Type | Description Parameter | Type | Description
------------------|--------------|-------------- ------------------|--------------|--------------
type | string | **Required.** Can either be "Host" or "Service"
filter | string | **Optional.** See [filters](9-icinga2-api#icinga2-api-filters). To apply the action only to yout target services or hosts.
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.** Some text output. plugin\_output | string | **Required.** The plugins main output, i.e. the text before the `|`. Does **not** contain the perfomance data.
performance\_data | string array | **Optional.** One array entry per `;` separated block. 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\_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 check\_source | string | **Optional.** Usually the name of the `command_endpoint`
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.
Example: Example:
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 \ $ 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\"]}" \ "{\"exit_status\":2,\"plugin_output\":\"IMAGINARY CHECK\",\"performance_data\":[\"This is just\", \"a drill\"],\"check_command\":[\"some/path\", \"--argument\", \"words\"]}" \
;echo ;echo
{"results": {"results":
@ -306,12 +294,12 @@ Example:
/v1/actions/reschedule-check /v1/actions/reschedule-check
Target: `Service` or `Host` Parameter | Type | Description
-------------|-----------|--------------
Parameter | Type | Description type | string | **Required.** Can either be "Host" or "Service"
-------------|---------|-------------- filter | string | **Optional.** See [filters](9-icinga2-api#icinga2-api-filters). To apply the action only to yout target services or hosts.
next\_check | time\_t | **Optional.** The next check will be run at this timestamp. Defaults to `now`. next\_check | timestamp | **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. 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 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 time it is (i.e. time period restrictions are ignored) and whether or not active
@ -339,10 +327,10 @@ allowed for the service (`force_check=true`).
/v1/actions/send-custom-notification /v1/actions/send-custom-notification
Target: `Service` or `Host`
Parameter | Type | Description Parameter | Type | Description
----------|---------|-------------- ----------|---------|--------------
type | string | **Required.** Can either be "Host" or "Service"
filter | string | **Optional.** See [filters](9-icinga2-api#icinga2-api-filters). To apply the action only to yout target services or hosts.
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.
@ -352,11 +340,11 @@ Target: `Service` or `Host`
/v1/actions/delay-notification /v1/actions/delay-notification
Target: `Service` or `Host` Parameter | Type | Description
----------|-----------|--------------
Parameter | Type | Description type | string | **Required.** Can either be "Host" or "Service"
----------|---------|-------------- filter | string | **Optional.** See [filters](9-icinga2-api#icinga2-api-filters). To apply the action only to yout target services or hosts.
timestamp | time\_t | **Required.** Delay notifications until this timestamp. timestamp | timestamp | **Required.** Delay notifications until this timestamp.
Note that this will only have an effect if the service stays in the same 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 state that it is currently in. If the service changes to another state, a new
@ -367,15 +355,15 @@ notification may go out before the time you specify in the `timestamp` argument.
/v1/actions/acknowledge-problem /v1/actions/acknowledge-problem
Target: `Service` or `Host` Parameter | Type | Description
----------|-----------|--------------
Parameter | Type | Description type | string | **Required.** Can either be "Host" or "Service"
----------|---------|-------------- filter | string | **Optional.** See [filters](9-icinga2-api#icinga2-api-filters). To apply the action only to yout target services or hosts.
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 | time\_t | **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.
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)
@ -401,22 +389,25 @@ a notification for them.
/v1/actions/remove-acknowledgement /v1/actions/remove-acknowledgement
Target: `Service` or `Host` parameter | type | description
----------|--------|--------------
type | string | **Required.** Can either be "Host" or "Service"
filter | string | **Optional.** See [filters](9-icinga2-api#icinga2-api-filters). To apply the action only to yout target services or hosts.
Removes ALL acknowledgements for services or hosts. Once the acknowledgements Remove the acknowledgements for services or hosts. Once the acknowledgement has
have been removed, notifications will be sent out again. been removed notifications will be sent out again.
### <a id="icinga2-api-actions-add-comment"></a> add-comment ### <a id="icinga2-api-actions-add-comment"></a> add-comment
/v1/actions/add-comment /v1/actions/add-comment
Target: `service` or `host` parameter | type | description
----------|--------|--------------
parameter | type | description type | string | **Required.** Can either be "Host" or "Service"
----------|---------|-------------- filter | string | **Optional.** See [filters](9-icinga2-api#icinga2-api-filters). To apply the action only to yout target services or hosts.
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.
Adds a `comment` by `author` to services or hosts. Adds a `comment` by `author` to services or hosts.
@ -424,11 +415,14 @@ This action works akin to `acknowledge-problem`, using only the `comment` and
`author` parameters. `author` parameters.
### <a id="icinga2-api-actions-remove-comment"></a> remove-comment ### <a id="icinga2-api-actions-remove-all-comments"></a> remove-all-comments
/v1/actions/remove-comment /v1/actions/remove-all-comments
Target: `Service` or `Host` parameter | type | description
------------|---------|--------------
type | string | **Required.** Can either be "Host" or "Service"
filter | string | **Optional.** See [filters](9-icinga2-api#icinga2-api-filters). To apply the action only to yout target services or hosts.
Removes ALL comments for services or hosts. Removes ALL comments for services or hosts.
@ -437,28 +431,29 @@ Removes ALL comments for services or hosts.
/v1/actions/remove-comment-by-id /v1/actions/remove-comment-by-id
Target: `None`
parameter | type | description parameter | type | description
------------|---------|-------------- ------------|---------|--------------
comment\_id | integer | **Required.** ID of the comment to remove. comment\_id | integer | **Required.** ID of the comment to remove.
Removes the comment with the legacy ID `comment_id`. Does not have a target type.
Tries to remove the comment with the ID `comment_id`, returns `OK` if the
comment did not exist.
### <a id="icinga2-api-actions-schedule-downtime"></a> schedule-downtime ### <a id="icinga2-api-actions-schedule-downtime"></a> schedule-downtime
/v1/actions/schedule-downtime /v1/actions/schedule-downtime
Target: `Host` or `Service` parameter | type | description
------------|-----------|--------------
parameter | type | description type | string | **Required.** Can either be "Host" or "Service"
------------|---------|-------------- filter | string | **Optional.** See [filters](9-icinga2-api#icinga2-api-filters). To apply the action only to yout target services or hosts.
start\_time | time\_t | **Required.** Timestamp marking the begining of the downtime. start\_time | timestamp | **Required.** Timestamp marking the begining of the downtime.
end\_time | time\_t | **Required.** Timestamp marking the end of the downtime. end\_time | timestamp | **Required.** Timestamp marking the end of the downtime.
duration | integer | **Required.** May be zero. Duration of the downtime in seconds if `fixed` is set to false. duration | integer | **Required.** May be zero. Duration of the downtime in seconds if `fixed` is set to false.
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. 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.
trigger\_id | integer | **Optional.** Sets the trigger for a triggered downtime. See [downtimes](5-advanced-topics.md#Downtimes) for more information on triggered downtimes. trigger\_id | integer | **Optional.** Sets the trigger for a triggered downtime. See [downtimes](5-advanced-topics.md#Downtimes) for more information on triggered downtimes.
Example: Example:
@ -479,11 +474,12 @@ Example:
### <a id="icinga2-api-actions-remove-downtime"></a> remove-downtime ### <a id="icinga2-api-actions-remove-downtime"></a> remove-downtime
/v1/actions/remove-downtime /v1/actions/remove-all-downtimes
Target: `Host` or `Service` parameter | type | description
----------|--------|--------------
Does not take any parameters. type | string | **Required.** Can either be "Host" or "Service"
filter | string | **Optional.** See [filters](9-icinga2-api#icinga2-api-filters). To apply the action only to yout target services or hosts.
Removes ALL downtimes for services or hosts. Removes ALL downtimes for services or hosts.
@ -492,22 +488,21 @@ Removes ALL downtimes for services or hosts.
/v1/actions/remove-downtime-by-id /v1/actions/remove-downtime-by-id
Target: `None`
parameter | type | description parameter | type | description
-------------|---------|-------------- -------------|---------|--------------
downtime\_id | integer | **Required.** ID of the downtime to remove. downtime\_id | integer | **Required.** ID of the downtime to remove.
Removes the comment with the legacy ID `downtime_id` Does not have a target type.
Tries to remove the downtime with the ID `downtime_id`, returns `OK` if the
downtime did not exist.
### <a id="icinga2-api-actions-shutdown-process"></a> shutdown-process ### <a id="icinga2-api-actions-shutdown-process"></a> shutdown-process
/v1/actions/shutdown-process /v1/actions/shutdown-process
Target: `None` Does not have a target type.
Does not take any parameters.
Shuts down Icinga2. May or may not return. Shuts down Icinga2. May or may not return.
@ -516,12 +511,11 @@ Shuts down Icinga2. May or may not return.
/v1/actions/restart-process /v1/actions/restart-process
Target: `None` Does not have a target type.
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
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

13
lib/icinga/apiactions.cpp
View File

@ -40,10 +40,10 @@ REGISTER_APIACTION(delay_notification, "Service;Host", &ApiActions::DelayNotific
REGISTER_APIACTION(acknowledge_problem, "Service;Host", &ApiActions::AcknowledgeProblem); REGISTER_APIACTION(acknowledge_problem, "Service;Host", &ApiActions::AcknowledgeProblem);
REGISTER_APIACTION(remove_acknowledgement, "Service;Host", &ApiActions::RemoveAcknowledgement); REGISTER_APIACTION(remove_acknowledgement, "Service;Host", &ApiActions::RemoveAcknowledgement);
REGISTER_APIACTION(add_comment, "Service;Host", &ApiActions::AddComment); REGISTER_APIACTION(add_comment, "Service;Host", &ApiActions::AddComment);
REGISTER_APIACTION(remove_comment, "Service;Host", &ApiActions::RemoveComment); REGISTER_APIACTION(remove_all_comments, "Service;Host", &ApiActions::RemoveAllComments);
REGISTER_APIACTION(remove_comment_by_id, "", &ApiActions::RemoveCommentByID); REGISTER_APIACTION(remove_comment_by_id, "", &ApiActions::RemoveCommentByID);
REGISTER_APIACTION(schedule_downtime, "Service;Host", &ApiActions::ScheduleDowntime); REGISTER_APIACTION(schedule_downtime, "Service;Host", &ApiActions::ScheduleDowntime);
REGISTER_APIACTION(remove_downtime, "Service;Host", &ApiActions::RemoveDowntime); REGISTER_APIACTION(remove_all_downtimes, "Service;Host", &ApiActions::RemoveAllDowntimes);
REGISTER_APIACTION(remove_downtime_by_id, "", &ApiActions::RemoveDowntimeByID); REGISTER_APIACTION(remove_downtime_by_id, "", &ApiActions::RemoveDowntimeByID);
REGISTER_APIACTION(shutdown_process, "", &ApiActions::ShutdownProcess); REGISTER_APIACTION(shutdown_process, "", &ApiActions::ShutdownProcess);
REGISTER_APIACTION(restart_process, "", &ApiActions::RestartProcess); REGISTER_APIACTION(restart_process, "", &ApiActions::RestartProcess);
@ -106,11 +106,6 @@ Dictionary::Ptr ApiActions::ProcessCheckResult(const ConfigObject::Ptr& object,
cr->SetCheckSource(HttpUtility::GetLastParameter(params, "check_source")); cr->SetCheckSource(HttpUtility::GetLastParameter(params, "check_source"));
cr->SetPerformanceData(params->Get("performance_data")); cr->SetPerformanceData(params->Get("performance_data"));
cr->SetCommand(params->Get("check_command")); cr->SetCommand(params->Get("check_command"));
cr->SetExecutionEnd(HttpUtility::GetLastParameter(params, "execution_end"));
cr->SetExecutionStart(HttpUtility::GetLastParameter(params, "execution_start"));
cr->SetScheduleEnd(HttpUtility::GetLastParameter(params, "schedule_end"));
cr->SetScheduleStart(HttpUtility::GetLastParameter(params, "schedule_start"));
checkable->ProcessCheckResult(cr); checkable->ProcessCheckResult(cr);
/* Reschedule the next check. The side effect of this is that for as long /* Reschedule the next check. The side effect of this is that for as long
@ -271,7 +266,7 @@ Dictionary::Ptr ApiActions::AddComment(const ConfigObject::Ptr& object,
+ "'.", additional); + "'.", additional);
} }
Dictionary::Ptr ApiActions::RemoveComment(const ConfigObject::Ptr& object, Dictionary::Ptr ApiActions::RemoveAllComments(const ConfigObject::Ptr& object,
const Dictionary::Ptr& params) const Dictionary::Ptr& params)
{ {
Checkable::Ptr checkable = static_pointer_cast<Checkable>(object); Checkable::Ptr checkable = static_pointer_cast<Checkable>(object);
@ -341,7 +336,7 @@ Dictionary::Ptr ApiActions::ScheduleDowntime(const ConfigObject::Ptr& object,
downtime_id + "' for object '" + checkable->GetName() + "'.", additional); downtime_id + "' for object '" + checkable->GetName() + "'.", additional);
} }
Dictionary::Ptr ApiActions::RemoveDowntime(const ConfigObject::Ptr& object, Dictionary::Ptr ApiActions::RemoveAllDowntimes(const ConfigObject::Ptr& object,
const Dictionary::Ptr& params) const Dictionary::Ptr& params)
{ {
Checkable::Ptr checkable = static_pointer_cast<Checkable>(object); Checkable::Ptr checkable = static_pointer_cast<Checkable>(object);

4
lib/icinga/apiactions.hpp
View File

@ -40,10 +40,10 @@ public:
static Dictionary::Ptr AcknowledgeProblem(const ConfigObject::Ptr& object, const Dictionary::Ptr& params); static Dictionary::Ptr AcknowledgeProblem(const ConfigObject::Ptr& object, const Dictionary::Ptr& params);
static Dictionary::Ptr RemoveAcknowledgement(const ConfigObject::Ptr& object, const Dictionary::Ptr& params); static Dictionary::Ptr RemoveAcknowledgement(const ConfigObject::Ptr& object, const Dictionary::Ptr& params);
static Dictionary::Ptr AddComment(const ConfigObject::Ptr& object, const Dictionary::Ptr& params); static Dictionary::Ptr AddComment(const ConfigObject::Ptr& object, const Dictionary::Ptr& params);
static Dictionary::Ptr RemoveComment(const ConfigObject::Ptr& object, const Dictionary::Ptr& params); static Dictionary::Ptr RemoveAllComments(const ConfigObject::Ptr& object, const Dictionary::Ptr& params);
static Dictionary::Ptr RemoveCommentByID(const ConfigObject::Ptr& object, const Dictionary::Ptr& params); static Dictionary::Ptr RemoveCommentByID(const ConfigObject::Ptr& object, const Dictionary::Ptr& params);
static Dictionary::Ptr ScheduleDowntime(const ConfigObject::Ptr& object, const Dictionary::Ptr& params); static Dictionary::Ptr ScheduleDowntime(const ConfigObject::Ptr& object, const Dictionary::Ptr& params);
static Dictionary::Ptr RemoveDowntime(const ConfigObject::Ptr& object, const Dictionary::Ptr& params); static Dictionary::Ptr RemoveAllDowntimes(const ConfigObject::Ptr& object, const Dictionary::Ptr& params);
static Dictionary::Ptr RemoveDowntimeByID(const ConfigObject::Ptr& object, const Dictionary::Ptr& params); static Dictionary::Ptr RemoveDowntimeByID(const ConfigObject::Ptr& object, const Dictionary::Ptr& params);
static Dictionary::Ptr ShutdownProcess(const ConfigObject::Ptr& object, const Dictionary::Ptr& params); static Dictionary::Ptr ShutdownProcess(const ConfigObject::Ptr& object, const Dictionary::Ptr& params);
static Dictionary::Ptr RestartProcess(const ConfigObject::Ptr& object, const Dictionary::Ptr& params); static Dictionary::Ptr RestartProcess(const ConfigObject::Ptr& object, const Dictionary::Ptr& params);