Merge pull request #8188 from WuerthPhoenix/feature/v1-actions-execute-command-8034-doc

Feature/v1 actions execute command 8034 doc

doc/12-icinga2-api.md

@@ -1535,6 +1535,44 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' \
 }
 ```
 
+### execute-command <a id="icinga2-api-actions-execute-command"></a>
+
+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`.
+
+  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'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**. Macro overrides. 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 -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": [
+          {
+              "checkable": "agent!custom_service",
+              "code": 202.0,
+              "execution": "3541d906-9afe-4c0e-ae6d-f549ee9bb3e7",
+              "status": "Accepted"
+          }
+      ]
+  }
+  ```
+
 ## Event Streams <a id="icinga2-api-event-streams"></a>
 
 Event streams can be used to receive check results, downtimes, comments,

doc/19-technical-concepts.md

@@ -1750,11 +1750,14 @@ 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 to execute the command on.
+deadline       | Number        | A Unix timestamp indicating the execution deadline
+source         | String        | The execution UUID
 
 
 ##### 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 +1767,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 +1789,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 <a id="technical-concepts-json-rpc-messages-event-updateexecutions"></a>
+
+> Location: `clusterevents.cpp`
+
+##### Message Body
+
+Key       | Value
+----------|---------
+jsonrpc   | 2.0
+method    | event::UpdateExecutions
+params    | Dictionary
+
+##### Params
+
+Key            | Type          | Description
+---------------|---------------|------------------
+host           | String        | Host name.
+service        | String        | Service name.
+executions     | 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 <a id="technical-concepts-json-rpc-messages-event-executedcommand"></a>
+
+> Location: `clusterevents.cpp`
+
+##### Message Body
+
+Key       | Value
+----------|---------
+jsonrpc   | 2.0
+method    | event::ExecutedCommand
+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 <a id="technical-concepts-json-rpc-messages-config-update"></a>
 
 > Location: `apilistener-filesync.cpp`