From 2fc042e2315f283e26205a7a8df01fdfed1cc4af Mon Sep 17 00:00:00 2001 From: Jean Flach Date: Tue, 27 Oct 2015 14:15:07 +0100 Subject: [PATCH] Update API actions and documentation refs #9080 #9105 --- doc/9-icinga2-api.md | 166 ++++++++++++++++++-------------------- lib/icinga/apiactions.cpp | 13 +-- lib/icinga/apiactions.hpp | 4 +- 3 files changed, 86 insertions(+), 97 deletions(-) diff --git a/doc/9-icinga2-api.md b/doc/9-icinga2-api.md index 06a0a0e2c..0d4b82c8b 100644 --- a/doc/9-icinga2-api.md +++ b/doc/9-icinga2-api.md @@ -49,8 +49,8 @@ including error codes. When an error occurs, the response body will contain additional information about the problem and its source. -A status in the range between 200 and 299 generally means that the request was succesful -and no error was encountered. +A status code between 200 and 299 generally means that the request was +succesful. 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 @@ -166,7 +166,7 @@ the custom host attribute `os` matching the regular expression `^Linux`. Available permissions for specific URL endpoints: - Permissions | Url Endpoint + Permissions | URL Endpoint ------------------------------|--------------- actions/;<action;> | /v1/actions config/query | /v1/config @@ -203,14 +203,13 @@ Example for JSON body: #### Filters -Use the same syntax as for apply rule expressions -for filtering specific objects. +Uses the same syntax as apply rule expressions 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) @@ -227,7 +226,7 @@ Each url contains the version string as prefix (currently "/v1"). 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/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). 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 shown here (url/actions/action-name?list=of¶meters) 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 action performed. So there will be a return for each object matching the filter. - ### process-check-result /v1/actions/process-check-result -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. 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. 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.** + check\_source | string | **Optional.** Usually the name of the `command_endpoint` This is used to submit a passive check result for a service or host. Passive checks need to be enabled for the check result to be processed. 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\"]}" \ ;echo {"results": @@ -306,12 +294,12 @@ Example: /v1/actions/reschedule-check -Target: `Service` or `Host` - - Parameter | Type | Description - -------------|---------|-------------- - 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. + 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 | 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. 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 @@ -339,10 +327,10 @@ allowed for the service (`force_check=true`). /v1/actions/send-custom-notification -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. 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. @@ -352,11 +340,11 @@ Target: `Service` or `Host` /v1/actions/delay-notification -Target: `Service` or `Host` - - Parameter | Type | Description - ----------|---------|-------------- - timestamp | time\_t | **Required.** Delay notifications until this timestamp. + 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 | timestamp | **Required.** Delay notifications until this 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 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 -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. + 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. + comment | string | **Required.** Comment text, may be empty. + 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. + 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 acknowledging the current problem, future notifications (for the same state) @@ -401,22 +389,25 @@ a notification for them. /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 -have been removed, notifications will be sent out again. +Remove the acknowledgements for services or hosts. Once the acknowledgement has +been removed notifications will be sent out again. ### add-comment /v1/actions/add-comment -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. + 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. + comment | string | **Required.** Comment text, may be empty. 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. -### remove-comment +### 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. @@ -437,28 +431,29 @@ Removes ALL comments for services or hosts. /v1/actions/remove-comment-by-id -Target: `None` - parameter | type | description ------------|---------|-------------- 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. ### schedule-downtime /v1/actions/schedule-downtime -Target: `Host` or `Service` - - parameter | type | description - ------------|---------|-------------- - start\_time | time\_t | **Required.** Timestamp marking the begining of the downtime. - end\_time | time\_t | **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. - 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. + 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 | timestamp | **Required.** Timestamp marking the begining 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. + 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. Example: @@ -479,11 +474,12 @@ Example: ### remove-downtime - /v1/actions/remove-downtime + /v1/actions/remove-all-downtimes -Target: `Host` or `Service` - -Does not take any parameters. + 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 downtimes for services or hosts. @@ -492,22 +488,21 @@ Removes ALL downtimes for services or hosts. /v1/actions/remove-downtime-by-id -Target: `None` - parameter | type | description -------------|---------|-------------- 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. ### shutdown-process /v1/actions/shutdown-process -Target: `None` - -Does not take any parameters. +Does not have a target type. Shuts down Icinga2. May or may not return. @@ -516,12 +511,11 @@ Shuts down Icinga2. May or may not return. /v1/actions/restart-process -Target: `None` - -Does not take any parameters. +Does not have a target type. Restarts Icinga2. May or may not return. + ## Event Streams You can subscribe to event streams by sending a `POST` request. The following diff --git a/lib/icinga/apiactions.cpp b/lib/icinga/apiactions.cpp index 071fc15bb..1dc0c0bc0 100644 --- a/lib/icinga/apiactions.cpp +++ b/lib/icinga/apiactions.cpp @@ -40,10 +40,10 @@ REGISTER_APIACTION(delay_notification, "Service;Host", &ApiActions::DelayNotific REGISTER_APIACTION(acknowledge_problem, "Service;Host", &ApiActions::AcknowledgeProblem); REGISTER_APIACTION(remove_acknowledgement, "Service;Host", &ApiActions::RemoveAcknowledgement); 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(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(shutdown_process, "", &ApiActions::ShutdownProcess); 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->SetPerformanceData(params->Get("performance_data")); 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); /* 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); } -Dictionary::Ptr ApiActions::RemoveComment(const ConfigObject::Ptr& object, +Dictionary::Ptr ApiActions::RemoveAllComments(const ConfigObject::Ptr& object, const Dictionary::Ptr& params) { Checkable::Ptr checkable = static_pointer_cast(object); @@ -341,7 +336,7 @@ Dictionary::Ptr ApiActions::ScheduleDowntime(const ConfigObject::Ptr& object, 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) { Checkable::Ptr checkable = static_pointer_cast(object); diff --git a/lib/icinga/apiactions.hpp b/lib/icinga/apiactions.hpp index 246da8fb3..e5fa8fe9c 100644 --- a/lib/icinga/apiactions.hpp +++ b/lib/icinga/apiactions.hpp @@ -40,10 +40,10 @@ public: 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 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 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 ShutdownProcess(const ConfigObject::Ptr& object, const Dictionary::Ptr& params); static Dictionary::Ptr RestartProcess(const ConfigObject::Ptr& object, const Dictionary::Ptr& params);