mirror of https://github.com/Icinga/icinga2.git
Merge pull request #8188 from WuerthPhoenix/feature/v1-actions-execute-command-8034-doc
Feature/v1 actions execute command 8034 doc
This commit is contained in:
Alexander Aleksandrovič Klimov
GitHub
commit
53fa09d144
|
|
@ -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,
|
||||
|
|
|
|||
|
|
@ -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`
|
||||
|
|
|
|||
Loading…
Reference in New Issue