mirror of https://github.com/Icinga/icinga2.git
Add technical concept docs for our internal JSON-RPC message API
This commit is contained in:
Michael Friedrich
parent
58ae29acac
commit
3c591a03b0
|
|
@ -735,14 +735,6 @@ Icinga 2 v2.9+ adds more performance metrics for these values:
|
||||||
* `sum_bytes_sent_per_second` and `sum_bytes_received_per_second`
|
* `sum_bytes_sent_per_second` and `sum_bytes_received_per_second`
|
||||||
|
|
||||||
|
|
||||||
<!--
|
|
||||||
## REST API <a id="technical-concepts-rest-api"></a>
|
|
||||||
|
|
||||||
Icinga 2 provides its own HTTP server which shares the port 5665 with
|
|
||||||
the JSON-RPC cluster protocol.
|
|
||||||
-->
|
|
||||||
|
|
||||||
|
|
||||||
## TLS Network IO <a id="technical-concepts-tls-network-io"></a>
|
## TLS Network IO <a id="technical-concepts-tls-network-io"></a>
|
||||||
|
|
||||||
### TLS Connection Handling <a id="technical-concepts-tls-network-io-connection-handling"></a>
|
### TLS Connection Handling <a id="technical-concepts-tls-network-io-connection-handling"></a>
|
||||||
|
|
@ -936,3 +928,789 @@ into the Icinga 2 binary.
|
||||||
* cpp-netlib: https://github.com/cpp-netlib/cpp-netlib
|
* cpp-netlib: https://github.com/cpp-netlib/cpp-netlib
|
||||||
* evpp: https://github.com/Qihoo360/evpp
|
* evpp: https://github.com/Qihoo360/evpp
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
<!--
|
||||||
|
## REST API <a id="technical-concepts-rest-api"></a>
|
||||||
|
|
||||||
|
Icinga 2 provides its own HTTP server which shares the port 5665 with
|
||||||
|
the JSON-RPC cluster protocol.
|
||||||
|
-->
|
||||||
|
|
||||||
|
## JSON-RPC Message API <a id="technical-concepts-json-rpc-messages"></a>
|
||||||
|
|
||||||
|
**The JSON-RPC message API is not a public API for end users.** In case you want
|
||||||
|
to interact with Icinga, use the [REST API](12-icinga2-api.md#icinga2-api).
|
||||||
|
|
||||||
|
This section describes the internal cluster messages exchanged between endpoints.
|
||||||
|
|
||||||
|
> **Tip**
|
||||||
|
>
|
||||||
|
> Debug builds with `icinga2 daemon -DDebugJsonRpc=1` unveils the JSON-RPC messages.
|
||||||
|
|
||||||
|
### Registered Handler Functions
|
||||||
|
|
||||||
|
Functions by example:
|
||||||
|
|
||||||
|
Event Sender: `Checkable::OnNewCheckResult`
|
||||||
|
|
||||||
|
```
|
||||||
|
On<xyz>.connect(&xyzHandler)
|
||||||
|
```
|
||||||
|
|
||||||
|
Event Receiver (Client): `CheckResultAPIHandler` in `REGISTER_APIFUNCTION`
|
||||||
|
|
||||||
|
```
|
||||||
|
<xyz>APIHandler()
|
||||||
|
```
|
||||||
|
|
||||||
|
### Messages
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-icinga-hello"></a> icinga::Hello
|
||||||
|
|
||||||
|
> Location: `apilistener.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | icinga::Hello
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Currently empty.
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
Event Sender: When a new client connects in `NewClientHandlerInternal()`.
|
||||||
|
Event Receiver: `HelloAPIHandler`
|
||||||
|
|
||||||
|
##### Permissions
|
||||||
|
|
||||||
|
None, this is a required message.
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-event-heartbeat"></a> event::Heartbeat
|
||||||
|
|
||||||
|
> Location: `jsonrpcconnection-heartbeat.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | event::Heartbeat
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
----------|---------------|------------------
|
||||||
|
timeout | Number | Heartbeat timeout, sender sets 120s.
|
||||||
|
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
Event Sender: `JsonRpcConnection::HeartbeatTimerHandler`
|
||||||
|
Event Receiver: `HeartbeatAPIHandler`
|
||||||
|
|
||||||
|
Both sender and receiver exchange this heartbeat message. If the sender detects
|
||||||
|
that a client endpoint hasn't sent anything in the updated timeout span, it disconnects
|
||||||
|
the client. This is to avoid stale connections with no message processing.
|
||||||
|
|
||||||
|
##### Permissions
|
||||||
|
|
||||||
|
None, this is a required message.
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-event-checkresult"></a> event::CheckResult
|
||||||
|
|
||||||
|
> Location: `clusterevents.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | event::CheckResult
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
----------|---------------|------------------
|
||||||
|
host | String | Host name
|
||||||
|
service | String | Service name
|
||||||
|
cr | Serialized CR | Check result
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
Event Sender: `Checkable::OnNewCheckResult`
|
||||||
|
Event Receiver: `CheckResultAPIHandler`
|
||||||
|
|
||||||
|
##### Permissions
|
||||||
|
|
||||||
|
The receiver will not process messages from not configured endpoints.
|
||||||
|
|
||||||
|
Message updates will be dropped when:
|
||||||
|
|
||||||
|
* Hosts/services do not exist
|
||||||
|
* Origin is a remote command endpoint different to the configured, and whose zone is not allowed to access this checkable.
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-event-setnextcheck"></a> event::SetNextCheck
|
||||||
|
|
||||||
|
> Location: `clusterevents.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | event::SetNextCheck
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
------------|---------------|------------------
|
||||||
|
host | String | Host name
|
||||||
|
service | String | Service name
|
||||||
|
next\_check | Timestamp | Next scheduled time as UNIX timestamp.
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
Event Sender: `Checkable::OnNextCheckChanged`
|
||||||
|
Event Receiver: `NextCheckChangedAPIHandler`
|
||||||
|
|
||||||
|
##### 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.
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-event-setnextnotification"></a> event::SetNextNotification
|
||||||
|
|
||||||
|
> Location: `clusterevents.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | event::SetNextNotification
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
-------------------|---------------|------------------
|
||||||
|
host | String | Host name
|
||||||
|
service | String | Service name
|
||||||
|
notification | String | Notification name
|
||||||
|
next\_notification | Timestamp | Next scheduled notification time as UNIX timestamp.
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
Event Sender: `Notification::OnNextNotificationChanged`
|
||||||
|
Event Receiver: `NextNotificationChangedAPIHandler`
|
||||||
|
|
||||||
|
##### Permissions
|
||||||
|
|
||||||
|
The receiver will not process messages from not configured endpoints.
|
||||||
|
|
||||||
|
Message updates will be dropped when:
|
||||||
|
|
||||||
|
* Notification does not exist.
|
||||||
|
* Origin endpoint's zone is not allowed to access this checkable.
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-event-setforcenextcheck"></a> event::SetForceNextCheck
|
||||||
|
|
||||||
|
> Location: `clusterevents.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | event::SetForceNextCheck
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
----------|---------------|------------------
|
||||||
|
host | String | Host name
|
||||||
|
service | String | Service name
|
||||||
|
forced | Boolean | Forced next check (execute now)
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
Event Sender: `Checkable::OnForceNextCheckChanged`
|
||||||
|
Event Receiver: `ForceNextCheckChangedAPIHandler`
|
||||||
|
|
||||||
|
##### 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.
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-event-setforcenextnotification"></a> event::SetForceNextNotification
|
||||||
|
|
||||||
|
> Location: `clusterevents.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | event::SetForceNextNotification
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
----------|---------------|------------------
|
||||||
|
host | String | Host name
|
||||||
|
service | String | Service name
|
||||||
|
forced | Boolean | Forced next check (execute now)
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
Event Sender: `Checkable::SetForceNextNotification`
|
||||||
|
Event Receiver: `ForceNextNotificationChangedAPIHandler`
|
||||||
|
|
||||||
|
##### 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.
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-event-setacknowledgement"></a> event::SetAcknowledgement
|
||||||
|
|
||||||
|
> Location: `clusterevents.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | event::SetAcknowledgement
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
-----------|---------------|------------------
|
||||||
|
host | String | Host name
|
||||||
|
service | String | Service name
|
||||||
|
author | String | Acknowledgement author name.
|
||||||
|
comment | String | Acknowledgement comment content.
|
||||||
|
acktype | Number | Acknowledgement type (0=None, 1=Normal, 2=Sticky)
|
||||||
|
notify | Boolean | Notification should be sent.
|
||||||
|
persistent | Boolean | Whether the comment is persistent.
|
||||||
|
expiry | Timestamp | Optional expire time as UNIX timestamp.
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
Event Sender: `Checkable::OnForceNextCheckChanged`
|
||||||
|
Event Receiver: `ForceNextCheckChangedAPIHandler`
|
||||||
|
|
||||||
|
##### 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.
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-event-clearacknowledgement"></a> event::ClearAcknowledgement
|
||||||
|
|
||||||
|
> Location: `clusterevents.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | event::ClearAcknowledgement
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
----------|---------------|------------------
|
||||||
|
host | String | Host name
|
||||||
|
service | String | Service name
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
Event Sender: `Checkable::OnAcknowledgementCleared`
|
||||||
|
Event Receiver: `AcknowledgementClearedAPIHandler`
|
||||||
|
|
||||||
|
##### 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.
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-event-sendnotifications"></a> event::SendNotifications
|
||||||
|
|
||||||
|
> Location: `clusterevents.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | event::SendNotifications
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
----------|---------------|------------------
|
||||||
|
host | String | Host name
|
||||||
|
service | String | Service name
|
||||||
|
cr | Serialized CR | Check result
|
||||||
|
type | Number | enum NotificationType, same as `types` for notification objects.
|
||||||
|
author | String | Author name
|
||||||
|
text | String | Notification text
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
Event Sender: `Checkable::OnNotificationsRequested`
|
||||||
|
Event Receiver: `SendNotificationsAPIHandler`
|
||||||
|
|
||||||
|
##### 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 the same as the receiver. This binds notification messages to the HA zone.
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-event-notificationsentuser"></a> event::NotificationSentUser
|
||||||
|
|
||||||
|
> Location: `clusterevents.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | event::NotificationSentUser
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
--------------|-----------------|------------------
|
||||||
|
host | String | Host name
|
||||||
|
service | String | Service name
|
||||||
|
notification | String | Notification name.
|
||||||
|
user | String | Notified user name.
|
||||||
|
type | Number | enum NotificationType, same as `types` in Notification objects.
|
||||||
|
cr | Serialized CR | Check result.
|
||||||
|
author | String | Notification author (for specific types)
|
||||||
|
text | String | Notification text (for specific types)
|
||||||
|
command | String | Notification command name.
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
Event Sender: `Checkable::OnNotificationSentToUser`
|
||||||
|
Event Receiver: `NotificationSentUserAPIHandler`
|
||||||
|
|
||||||
|
##### 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 the same as the receiver. This binds notification messages to the HA zone.
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-event-notificationsenttoallusers"></a> event::NotificationSentToAllUsers
|
||||||
|
|
||||||
|
> Location: `clusterevents.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | event::NotificationSentToAllUsers
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
----------------------------|-----------------|------------------
|
||||||
|
host | String | Host name
|
||||||
|
service | String | Service name
|
||||||
|
notification | String | Notification name.
|
||||||
|
users | Array of String | Notified user names.
|
||||||
|
type | Number | enum NotificationType, same as `types` in Notification objects.
|
||||||
|
cr | Serialized CR | Check result.
|
||||||
|
author | String | Notification author (for specific types)
|
||||||
|
text | String | Notification text (for specific types)
|
||||||
|
last\_notification | Timestamp | Last notification time as UNIX timestamp.
|
||||||
|
next\_notification | Timestamp | Next scheduled notification time as UNIX timestamp.
|
||||||
|
notification\_number | Number | Current notification number in problem state.
|
||||||
|
last\_problem\_notification | Timestamp | Last problem notification time as UNIX timestamp.
|
||||||
|
no\_more\_notifications | Boolean | Whether to send future notifications when this notification becomes active on this HA node.
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
Event Sender: `Checkable::OnNotificationSentToAllUsers`
|
||||||
|
Event Receiver: `NotificationSentToAllUsersAPIHandler`
|
||||||
|
|
||||||
|
##### 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 the same as the receiver. This binds notification messages to the HA zone.
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-event-executecommand"></a> event::ExecuteCommand
|
||||||
|
|
||||||
|
> Location: `clusterevents-check.cpp` and `checkable-check.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.
|
||||||
|
command\_type | String | `check_command` or `event_command`.
|
||||||
|
command | String | CheckCommand or EventCommand name.
|
||||||
|
macros | Dictionary | Command arguments as key/value pairs for remote execution.
|
||||||
|
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
**Event Sender:** This gets constructed directly in `Checkable::ExecuteCheck()` or `Checkable::ExecuteEventHandler()` 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.
|
||||||
|
* When the endpoint is not connected and not syncing replay logs and 5m after application start, generate an UNKNOWN check result for the user ("not connected").
|
||||||
|
|
||||||
|
**Event Receiver:** `ExecuteCommandAPIHandler`
|
||||||
|
|
||||||
|
Special handling, calls `ClusterEvents::EnqueueCheck()` for command endpoint checks.
|
||||||
|
This function enqueues check tasks into a queue which is controlled in `RemoteCheckThreadProc()`.
|
||||||
|
|
||||||
|
##### Permissions
|
||||||
|
|
||||||
|
The receiver will not process messages from not configured endpoints.
|
||||||
|
|
||||||
|
Message updates will be dropped when:
|
||||||
|
|
||||||
|
* Origin endpoint's zone is not a parent zone of the receiver endpoint.
|
||||||
|
* `accept_commands = false` in the `api` feature configuration sends back an UNKNOWN check result to the sender.
|
||||||
|
|
||||||
|
The receiver constructs a virtual host object and looks for the local CheckCommand object.
|
||||||
|
|
||||||
|
Returns UNKNWON as check result to the sender
|
||||||
|
|
||||||
|
* when the CheckCommand object does not exist.
|
||||||
|
* when there was an exception triggered from check execution, e.g. the plugin binary could not be executed or similar.
|
||||||
|
|
||||||
|
The returned messages are synced directly to the sender's endpoint, no cluster broadcast.
|
||||||
|
|
||||||
|
> **Note**: EventCommand errors are just logged on the remote endpoint.
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-config-update"></a> config::Update
|
||||||
|
|
||||||
|
> Location: `apilistener-filesync.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | config::Update
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
-----------|---------------|------------------
|
||||||
|
update | Dictionary | Config file paths and their content.
|
||||||
|
update\_v2 | Dictionary | Additional meta config files introduced in 2.4+ for compatibility reasons.
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
**Event Sender:** `SendConfigUpdate()` called in `ApiListener::SyncClient()` when a new client endpoint connects.
|
||||||
|
**Event Receiver:** `ConfigUpdateHandler` reads the config update content and stores them in `/var/lib/icinga2/api`.
|
||||||
|
When it detects a configuration change, the function requests and application restart.
|
||||||
|
|
||||||
|
##### Permissions
|
||||||
|
|
||||||
|
The receiver will not process messages from not configured endpoints.
|
||||||
|
|
||||||
|
Message updates will be dropped when:
|
||||||
|
|
||||||
|
* The origin sender is not in a parent zone of the receiver.
|
||||||
|
* `api` feature does not accept config.
|
||||||
|
|
||||||
|
Config updates will be ignored when:
|
||||||
|
|
||||||
|
* The zone is not configured on the receiver endpoint.
|
||||||
|
* The zone is authoritative on this instance (this only happens on a master which has `/etc/icinga2/zones.d` populated, and prevents sync loops)
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-config-updateobject"></a> config::UpdateObject
|
||||||
|
|
||||||
|
> Location: `apilistener-configsync.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | config::UpdateObject
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
---------------------|-------------|------------------
|
||||||
|
name | String | Object name.
|
||||||
|
type | String | Object type name.
|
||||||
|
version | Number | Object version.
|
||||||
|
config | String | Config file content for `_api` packages.
|
||||||
|
modified\_attributes | Dictionary | Modified attributes at runtime as key value pairs.
|
||||||
|
original\_attributes | Array | Original attributes as array of keys.
|
||||||
|
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
**Event Sender:** Either on client connect (full sync), or runtime created/updated object
|
||||||
|
|
||||||
|
`ApiListener::SendRuntimeConfigObjects()` gets called when a new endpoint is connected
|
||||||
|
and runtime created config objects need to be synced. This invokes a call to `UpdateConfigObject()`
|
||||||
|
to only sync this JsonRpcConnection client.
|
||||||
|
|
||||||
|
`ConfigObject::OnActiveChanged` (created or deleted) or `ConfigObject::OnVersionChanged` (updated)
|
||||||
|
also call `UpdateConfigObject()`.
|
||||||
|
|
||||||
|
**Event Receiver:** `ConfigUpdateObjectAPIHandler` calls `ConfigObjectUtility::CreateObject()` in order
|
||||||
|
to create the object if it is not already existing. Afterwards, all modified attributes are applied
|
||||||
|
and in case, original attributes are restored. The object version is set as well, keeping it in sync
|
||||||
|
with the sender.
|
||||||
|
|
||||||
|
##### Permissions
|
||||||
|
|
||||||
|
###### Sender
|
||||||
|
|
||||||
|
Client receiver connects:
|
||||||
|
|
||||||
|
The sender only syncs config object updates to a client which can access
|
||||||
|
the config object, in `ApiListener::SendRuntimeConfigObjects()`.
|
||||||
|
|
||||||
|
In addition to that, the client endpoint's zone is checked whether this zone may access
|
||||||
|
the config object.
|
||||||
|
|
||||||
|
Runtime updated object:
|
||||||
|
|
||||||
|
Only if the config object belongs to the `_api` package.
|
||||||
|
|
||||||
|
|
||||||
|
###### Receiver
|
||||||
|
|
||||||
|
The receiver will not process messages from not configured endpoints.
|
||||||
|
|
||||||
|
Message updates will be dropped when:
|
||||||
|
|
||||||
|
* Origin sender endpoint's zone is in a child zone.
|
||||||
|
* `api` feature does not accept config
|
||||||
|
* The received config object type does not exist (this is to prevent failures with older nodes and new object types).
|
||||||
|
|
||||||
|
Error handling:
|
||||||
|
|
||||||
|
* Log an error if `CreateObject` fails (only if the object does not already exist)
|
||||||
|
* Local object version is newer than the received version, object will not be updated.
|
||||||
|
* Compare modified and original attributes and restore any type of change here.
|
||||||
|
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-config-deleteobject"></a> config::DeleteObject
|
||||||
|
|
||||||
|
> Location: `apilistener-configsync.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | config::DeleteObject
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
--------------------|-------------|------------------
|
||||||
|
name | String | Object name.
|
||||||
|
type | String | Object type name.
|
||||||
|
version | Number | Object version.
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
**Event Sender:**
|
||||||
|
|
||||||
|
`ConfigObject::OnActiveChanged` (created or deleted) or `ConfigObject::OnVersionChanged` (updated)
|
||||||
|
call `DeleteConfigObject()`.
|
||||||
|
|
||||||
|
**Event Receiver:** `ConfigDeleteObjectAPIHandler`
|
||||||
|
|
||||||
|
##### Permissions
|
||||||
|
|
||||||
|
###### Sender
|
||||||
|
|
||||||
|
Runtime deleted object:
|
||||||
|
|
||||||
|
Only if the config object belongs to the `_api` package.
|
||||||
|
|
||||||
|
###### Receiver
|
||||||
|
|
||||||
|
The receiver will not process messages from not configured endpoints.
|
||||||
|
|
||||||
|
Message updates will be dropped when:
|
||||||
|
|
||||||
|
* Origin sender endpoint's zone is in a child zone.
|
||||||
|
* `api` feature does not accept config
|
||||||
|
* The received config object type does not exist (this is to prevent failures with older nodes and new object types).
|
||||||
|
* The object in question was not created at runtime, it does not belong to the `_api` package.
|
||||||
|
|
||||||
|
Error handling:
|
||||||
|
|
||||||
|
* Log an error if `DeleteObject` fails (only if the object does not already exist)
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-pki-requestcertificate"></a> pki::RequestCertificate
|
||||||
|
|
||||||
|
> Location: `jsonrpcconnection-pki.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | pki::RequestCertificate
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
--------------|---------------|------------------
|
||||||
|
ticket | String | Own ticket, or as satellite in CA proxy from local store.
|
||||||
|
cert\_request | String | Certificate request content from local store, optional.
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
Event Sender: `RequestCertificateHandler`
|
||||||
|
Event Receiver: `RequestCertificateHandler`
|
||||||
|
|
||||||
|
##### Permissions
|
||||||
|
|
||||||
|
This is an anonymous request, and the number of anonymous clients can be configured
|
||||||
|
in the `api` feature.
|
||||||
|
|
||||||
|
Only valid certificate request messages are processed, and valid signed certificates
|
||||||
|
won't be signed again.
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-pki-updatecertificate"></a> pki::UpdateCertificate
|
||||||
|
|
||||||
|
> Location: `jsonrpcconnection-pki.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | pki::UpdateCertificate
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
---------------------|---------------|------------------
|
||||||
|
status\_code | Number | Status code, 0=ok.
|
||||||
|
cert | String | Signed certificate content.
|
||||||
|
ca | String | Public CA certificate content.
|
||||||
|
fingerprint\_request | String | Certificate fingerprint from the CSR.
|
||||||
|
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
**Event Sender:**
|
||||||
|
|
||||||
|
* When a client requests a certificate in `RequestCertificateHandler` and the satellite
|
||||||
|
already has a signed certificate, the `pki::UpdateCertificate` message is constructed and sent back.
|
||||||
|
* When the endpoint holding the master's CA private key (and TicketSalt private key) is able to sign
|
||||||
|
the request, the `pki::UpdateCertificate` message is constructed and sent back.
|
||||||
|
|
||||||
|
**Event Receiver:** `UpdateCertificateHandler`
|
||||||
|
|
||||||
|
##### Permissions
|
||||||
|
|
||||||
|
Message updates are dropped when
|
||||||
|
|
||||||
|
* The origin sender is not in a parent zone of the receiver.
|
||||||
|
* The certificate fingerprint is in an invalid format.
|
||||||
|
|
||||||
|
#### <a id="technical-concepts-json-rpc-messages-pki-updatecertificate"></a> log::SetLogPosition
|
||||||
|
|
||||||
|
> Location: `apilistener.cpp` and `jsonrpcconnection.cpp`
|
||||||
|
|
||||||
|
##### Message Body
|
||||||
|
|
||||||
|
Key | Value
|
||||||
|
----------|---------
|
||||||
|
jsonrpc | 2.0
|
||||||
|
method | log::SetLogPosition
|
||||||
|
params | Dictionary
|
||||||
|
|
||||||
|
##### Params
|
||||||
|
|
||||||
|
Key | Type | Description
|
||||||
|
--------------------|---------------|------------------
|
||||||
|
log\_position | Timestamp | The endpoint's log position as UNIX timestamp.
|
||||||
|
|
||||||
|
|
||||||
|
##### Functions
|
||||||
|
|
||||||
|
**Event Sender:**
|
||||||
|
|
||||||
|
During log replay to a client endpoint in `ApiListener::ReplayLog()`, each processed
|
||||||
|
file generates a message which updates the log position timestamp.
|
||||||
|
|
||||||
|
`ApiListener::ApiTimerHandler()` invokes a check to keep all connected endpoints and
|
||||||
|
their log position in sync during replay log.
|
||||||
|
|
||||||
|
**Event Receiver:** `SetLogPositionHandler`
|
||||||
|
|
||||||
|
##### Permissions
|
||||||
|
|
||||||
|
The receiver will not process messages from not configured endpoints.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue