From 49efe009bd99cf49cdbc91509cbfd73ffea3d94f Mon Sep 17 00:00:00 2001 From: Mattia Codato Date: Mon, 24 Aug 2020 14:37:06 +0200 Subject: [PATCH 1/6] Update doc --- doc/12-icinga2-api.md | 35 +++++++++++++++++ doc/19-technical-concepts.md | 76 +++++++++++++++++++++++++++++++++++- 2 files changed, 110 insertions(+), 1 deletion(-) diff --git a/doc/12-icinga2-api.md b/doc/12-icinga2-api.md index 6f8f296c6..0a9ac41a5 100644 --- a/doc/12-icinga2-api.md +++ b/doc/12-icinga2-api.md @@ -1535,6 +1535,41 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' \ } ``` +### execute-command + +This API can e used to execute a particular check/notification/event-command on a particular +endpoint in the context of a particular checkable. + +Send a `POST` request to the URL endpoint `/v1/actions/execute-command`. + + Parameter | Type | Description + --------------|------------|-------------- + ttl | Number | **Required.** The time to live of the execution expressed in seconds. + command_type | String | **Optional.** The command type: `CheckCommand` or `EventCommand` or `NotificationCommand`. Default: `EventCommand` + command | String | **Optional.** The command to execute. Its type must the same as `command_type`. It can be a macro string. Default: depending on the `command_type` it can be `$check_command$`, `$event_command$` or `$notification_command$` + endpoint | String | **Optional.** The endpoint execute the command on. It can be a macro string. Default: `$command_endpoint`. + macros | Dictionary | **Optional**. A serialized object used to resolve the macro strings. Default: `{}` + user | String | **Optional.** The user used for the notification command. + notification | String | **Optional.** The notification used for the notification command. + + Example: + + ``` + $ curl -k -s -u root:icinga -H 'Accept: application/json' \ + -X POST 'https://localhost:5665/v1/actions/execute-command' \ + -d '{"type":"Service", "service": "agent!custom_service", "ttl":"15", "macros": { "command_endpoint":"master", "ls_dir":"/tmp/foo" }, "command": "custom_command", "command_type": "CheckCommand" }' + { + "results": [ + { + "checkable": "agent!custom_service", + "code": 202.0, + "execution": "3541d906-9afe-4c0e-ae6d-f549ee9bb3e7", + "status": "Accepted" + } + ] + } + ``` + ## Event Streams Event streams can be used to receive check results, downtimes, comments, diff --git a/doc/19-technical-concepts.md b/doc/19-technical-concepts.md index 4586410f6..9a3229ca4 100644 --- a/doc/19-technical-concepts.md +++ b/doc/19-technical-concepts.md @@ -1750,11 +1750,12 @@ command\_type | String | `check_command` or `event_command`. command | String | CheckCommand or EventCommand name. check\_timeout | Number | Check timeout of the checkable object, if specified as `check_timeout` attribute. macros | Dictionary | Command arguments as key/value pairs for remote execution. +endpoint | String | The endpoint execute the command on. ##### Functions -**Event Sender:** This gets constructed directly in `Checkable::ExecuteCheck()` or `Checkable::ExecuteEventHandler()` when a remote command endpoint is configured. +**Event Sender:** This gets constructed directly in `Checkable::ExecuteCheck()`, `Checkable::ExecuteEventHandler()` or `ApiActions::ExecuteCommand()` when a remote command endpoint is configured. * `Get{CheckCommand,EventCommand}()->Execute()` simulates an execution and extracts all command arguments into the `macro` dictionary (inside lib/methods tasks). * When the endpoint is connected, the message is constructed and sent directly. @@ -1764,6 +1765,7 @@ macros | Dictionary | Command arguments as key/value pairs for remote Special handling, calls `ClusterEvents::EnqueueCheck()` for command endpoint checks. This function enqueues check tasks into a queue which is controlled in `RemoteCheckThreadProc()`. +If the `endpoint` parameter is specified and is not equal to the local endpoint then the message is forwarded to the correct endpoint zone. ##### Permissions @@ -1785,6 +1787,78 @@ The returned messages are synced directly to the sender's endpoint, no cluster b > **Note**: EventCommand errors are just logged on the remote endpoint. +### event::UpdateExecutions + +> Location: `clusterevents.cpp` + +##### Message Body + +Key | Value +----------|--------- +jsonrpc | 2.0 +method | event::ExecuteCommand +params | Dictionary + +##### Params + +Key | Type | Description +---------------|---------------|------------------ +host | String | Host name. +service | String | Service name. +execution | Dictionary | Executions to be updated + +##### Functions + +**Event Sender:** `ClusterEvents::ExecutedCommandAPIHandler`, `ClusterEvents::UpdateExecutionsAPIHandler`, `ApiActions::ExecuteCommand` +**Event Receiver:** `ClusterEvents::UpdateExecutionsAPIHandler` + +##### Permissions + +The receiver will not process messages from not configured endpoints. + +Message updates will be dropped when: + +* Checkable does not exist. +* Origin endpoint's zone is not allowed to access this checkable. + +### event::ExecutedCommand + +> Location: `clusterevents.cpp` + +##### Message Body + +Key | Value +----------|--------- +jsonrpc | 2.0 +method | event::ExecuteCommand +params | Dictionary + +##### Params + +Key | Type | Description +---------------|---------------|------------------ +host | String | Host name. +service | String | Service name. +execution | String | The execution ID executed. +exitStatus | Number | The command exit status. +output | String | The command output. +start | Number | The unix timestamp at the start of the command execution +end | Number | The unix timestamp at the end of the command execution + +##### Functions + +**Event Sender:** `ClusterEvents::ExecuteCheckFromQueue`, `ClusterEvents::ExecuteCommandAPIHandler` +**Event Receiver:** `ClusterEvents::ExecutedCommandAPIHandler` + +##### Permissions + +The receiver will not process messages from not configured endpoints. + +Message updates will be dropped when: + +* Checkable does not exist. +* Origin endpoint's zone is not allowed to access this checkable. + #### config::Update > Location: `apilistener-filesync.cpp` From 078ae38661514962370908a346b78645b394e8a5 Mon Sep 17 00:00:00 2001 From: Mattia Codato Date: Mon, 24 Aug 2020 14:45:01 +0200 Subject: [PATCH 2/6] Fix typo --- doc/12-icinga2-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/12-icinga2-api.md b/doc/12-icinga2-api.md index 0a9ac41a5..da38b31ca 100644 --- a/doc/12-icinga2-api.md +++ b/doc/12-icinga2-api.md @@ -1537,7 +1537,7 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' \ ### execute-command -This API can e used to execute a particular check/notification/event-command on a particular +This API can be used to execute a particular check/notification/event-command on a particular endpoint in the context of a particular checkable. Send a `POST` request to the URL endpoint `/v1/actions/execute-command`. From 9c2cc1169bbf9fa5dfe9f57444b834422c94672b Mon Sep 17 00:00:00 2001 From: Mattia Codato Date: Tue, 25 Aug 2020 09:24:28 +0200 Subject: [PATCH 3/6] Fix typos --- doc/12-icinga2-api.md | 2 +- doc/19-technical-concepts.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/12-icinga2-api.md b/doc/12-icinga2-api.md index da38b31ca..e5720e0c8 100644 --- a/doc/12-icinga2-api.md +++ b/doc/12-icinga2-api.md @@ -1547,7 +1547,7 @@ Send a `POST` request to the URL endpoint `/v1/actions/execute-command`. ttl | Number | **Required.** The time to live of the execution expressed in seconds. command_type | String | **Optional.** The command type: `CheckCommand` or `EventCommand` or `NotificationCommand`. Default: `EventCommand` command | String | **Optional.** The command to execute. Its type must the same as `command_type`. It can be a macro string. Default: depending on the `command_type` it can be `$check_command$`, `$event_command$` or `$notification_command$` - endpoint | String | **Optional.** The endpoint execute the command on. It can be a macro string. Default: `$command_endpoint`. + endpoint | String | **Optional.** The endpoint to execute the command on. It can be a macro string. Default: `$command_endpoint`. macros | Dictionary | **Optional**. A serialized object used to resolve the macro strings. Default: `{}` user | String | **Optional.** The user used for the notification command. notification | String | **Optional.** The notification used for the notification command. diff --git a/doc/19-technical-concepts.md b/doc/19-technical-concepts.md index 9a3229ca4..272381181 100644 --- a/doc/19-technical-concepts.md +++ b/doc/19-technical-concepts.md @@ -1750,7 +1750,7 @@ command\_type | String | `check_command` or `event_command`. command | String | CheckCommand or EventCommand name. check\_timeout | Number | Check timeout of the checkable object, if specified as `check_timeout` attribute. macros | Dictionary | Command arguments as key/value pairs for remote execution. -endpoint | String | The endpoint execute the command on. +endpoint | String | The endpoint to execute the command on. ##### Functions From 3b4c008c8109976944655a2f232d1151ab38858d Mon Sep 17 00:00:00 2001 From: Mattia Codato Date: Tue, 25 Aug 2020 17:35:34 +0200 Subject: [PATCH 4/6] Fix doc --- doc/12-icinga2-api.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/doc/12-icinga2-api.md b/doc/12-icinga2-api.md index e5720e0c8..379153bd0 100644 --- a/doc/12-icinga2-api.md +++ b/doc/12-icinga2-api.md @@ -1535,9 +1535,9 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' \ } ``` -### execute-command +### execute-command -This API can be used to execute a particular check/notification/event-command on a particular +Executes a particular check/notification/event-command on a particular endpoint in the context of a particular checkable. Send a `POST` request to the URL endpoint `/v1/actions/execute-command`. @@ -1546,18 +1546,18 @@ Send a `POST` request to the URL endpoint `/v1/actions/execute-command`. --------------|------------|-------------- ttl | Number | **Required.** The time to live of the execution expressed in seconds. command_type | String | **Optional.** The command type: `CheckCommand` or `EventCommand` or `NotificationCommand`. Default: `EventCommand` - command | String | **Optional.** The command to execute. Its type must the same as `command_type`. It can be a macro string. Default: depending on the `command_type` it can be `$check_command$`, `$event_command$` or `$notification_command$` - endpoint | String | **Optional.** The endpoint to execute the command on. It can be a macro string. Default: `$command_endpoint`. - macros | Dictionary | **Optional**. A serialized object used to resolve the macro strings. Default: `{}` + command | String | **Optional.** The command to execute. Its type must the same as `command_type`. It can be a macro string. Default: depending on the `command_type` it's either `$check_command$`, `$event_command$` or `$notification_command$` + endpoint | String | **Optional.** The endpoint to execute the command on. It can be a macro string. Default: `$command_endpoint$`. + macros | Dictionary | **Optional**. A serialized object used to resolve the macro strings. It overrides also macros of other parameter. e.g. {"http_ssl": false}. Default: `{}` user | String | **Optional.** The user used for the notification command. notification | String | **Optional.** The notification used for the notification command. Example: ``` - $ curl -k -s -u root:icinga -H 'Accept: application/json' \ + $ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ -X POST 'https://localhost:5665/v1/actions/execute-command' \ - -d '{"type":"Service", "service": "agent!custom_service", "ttl":"15", "macros": { "command_endpoint":"master", "ls_dir":"/tmp/foo" }, "command": "custom_command", "command_type": "CheckCommand" }' + -d '{"type": "Service", "service": "agent!custom_service", "ttl": 15, "macros": { "command_endpoint": "master", "ls_dir": "/tmp/foo" }, "command": "custom_command", "command_type": "CheckCommand" }' { "results": [ { From dd2bc681fea09f4b66effa92272d9cda610635ea Mon Sep 17 00:00:00 2001 From: Mattia Codato Date: Wed, 26 Aug 2020 09:20:06 +0200 Subject: [PATCH 5/6] Fix doc execute-command --- doc/12-icinga2-api.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/doc/12-icinga2-api.md b/doc/12-icinga2-api.md index 379153bd0..7ee51e69b 100644 --- a/doc/12-icinga2-api.md +++ b/doc/12-icinga2-api.md @@ -1548,7 +1548,7 @@ Send a `POST` request to the URL endpoint `/v1/actions/execute-command`. command_type | String | **Optional.** The command type: `CheckCommand` or `EventCommand` or `NotificationCommand`. Default: `EventCommand` command | String | **Optional.** The command to execute. Its type must the same as `command_type`. It can be a macro string. Default: depending on the `command_type` it's either `$check_command$`, `$event_command$` or `$notification_command$` endpoint | String | **Optional.** The endpoint to execute the command on. It can be a macro string. Default: `$command_endpoint$`. - macros | Dictionary | **Optional**. A serialized object used to resolve the macro strings. It overrides also macros of other parameter. e.g. {"http_ssl": false}. Default: `{}` + macros | Dictionary | **Optional**. Macro overrides. Default: `{}` user | String | **Optional.** The user used for the notification command. notification | String | **Optional.** The notification used for the notification command. @@ -1558,6 +1558,9 @@ Send a `POST` request to the URL endpoint `/v1/actions/execute-command`. $ curl -k -s -S -i -u root:icinga -H 'Accept: application/json' \ -X POST 'https://localhost:5665/v1/actions/execute-command' \ -d '{"type": "Service", "service": "agent!custom_service", "ttl": 15, "macros": { "command_endpoint": "master", "ls_dir": "/tmp/foo" }, "command": "custom_command", "command_type": "CheckCommand" }' +``` + +``` { "results": [ { From 46b4e72c8ce4ebd0b084954d386542462641e628 Mon Sep 17 00:00:00 2001 From: Mattia Codato Date: Wed, 26 Aug 2020 11:43:18 +0200 Subject: [PATCH 6/6] Fix doc for cluster events --- doc/19-technical-concepts.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/19-technical-concepts.md b/doc/19-technical-concepts.md index 272381181..9ab347454 100644 --- a/doc/19-technical-concepts.md +++ b/doc/19-technical-concepts.md @@ -1751,6 +1751,8 @@ command | String | CheckCommand or EventCommand name. check\_timeout | Number | Check timeout of the checkable object, if specified as `check_timeout` attribute. macros | Dictionary | Command arguments as key/value pairs for remote execution. endpoint | String | The endpoint to execute the command on. +deadline | Number | A Unix timestamp indicating the execution deadline +source | String | The execution UUID ##### Functions @@ -1796,7 +1798,7 @@ The returned messages are synced directly to the sender's endpoint, no cluster b Key | Value ----------|--------- jsonrpc | 2.0 -method | event::ExecuteCommand +method | event::UpdateExecutions params | Dictionary ##### Params @@ -1805,7 +1807,7 @@ Key | Type | Description ---------------|---------------|------------------ host | String | Host name. service | String | Service name. -execution | Dictionary | Executions to be updated +executions | Dictionary | Executions to be updated ##### Functions @@ -1830,7 +1832,7 @@ Message updates will be dropped when: Key | Value ----------|--------- jsonrpc | 2.0 -method | event::ExecuteCommand +method | event::ExecutedCommand params | Dictionary ##### Params