mirror of
https://github.com/zeek/zeek.git
synced 2025-10-07 00:58:19 +00:00
ded98cd373
This is based on commit 2731def9159247e6da8a3191783c89683363689c from the zeek-docs repo.
402 lines
19 KiB
ReStructuredText
402 lines
19 KiB
ReStructuredText
:tocdepth: 3
|
|
|
|
policy/frameworks/management/controller/api.zeek
|
|
================================================
|
|
.. zeek:namespace:: Management::Controller::API
|
|
|
|
The event API of cluster controllers. Most endpoints consist of event pairs,
|
|
where the controller answers the client's request event with a corresponding
|
|
response event. Such event pairs share the same name prefix and end in
|
|
"_request" and "_response", respectively.
|
|
|
|
:Namespace: Management::Controller::API
|
|
:Imports: :doc:`policy/frameworks/management/types.zeek </scripts/policy/frameworks/management/types.zeek>`
|
|
|
|
Summary
|
|
~~~~~~~
|
|
Constants
|
|
#########
|
|
=================================================================== ================================================================
|
|
:zeek:id:`Management::Controller::API::version`: :zeek:type:`count` A simple versioning scheme, used to track basic compatibility of
|
|
controller, agents, and the client.
|
|
=================================================================== ================================================================
|
|
|
|
Events
|
|
######
|
|
======================================================================================== ======================================================================
|
|
:zeek:id:`Management::Controller::API::deploy_request`: :zeek:type:`event` Trigger deployment of a previously staged configuration.
|
|
:zeek:id:`Management::Controller::API::deploy_response`: :zeek:type:`event` Response to a :zeek:see:`Management::Controller::API::deploy_request`
|
|
event.
|
|
:zeek:id:`Management::Controller::API::get_configuration_request`: :zeek:type:`event` The client sends this event to retrieve the controller's current
|
|
cluster configuration(s).
|
|
:zeek:id:`Management::Controller::API::get_configuration_response`: :zeek:type:`event` Response to a
|
|
:zeek:see:`Management::Controller::API::get_configuration_request`
|
|
event.
|
|
:zeek:id:`Management::Controller::API::get_id_value_request`: :zeek:type:`event` The client sends this event to retrieve the current value of a
|
|
variable in Zeek's global namespace, referenced by the given
|
|
identifier (i.e., variable name).
|
|
:zeek:id:`Management::Controller::API::get_id_value_response`: :zeek:type:`event` Response to a
|
|
:zeek:see:`Management::Controller::API::get_id_value_request`
|
|
event.
|
|
:zeek:id:`Management::Controller::API::get_instances_request`: :zeek:type:`event` The client sends this event to request a list of the currently
|
|
peered agents/instances.
|
|
:zeek:id:`Management::Controller::API::get_instances_response`: :zeek:type:`event` Response to a
|
|
:zeek:see:`Management::Controller::API::get_instances_request`
|
|
event.
|
|
:zeek:id:`Management::Controller::API::get_nodes_request`: :zeek:type:`event` The client sends this event to request a list of
|
|
:zeek:see:`Management::NodeStatus` records that capture
|
|
the status of Supervisor-managed nodes running on the cluster's
|
|
instances.
|
|
:zeek:id:`Management::Controller::API::get_nodes_response`: :zeek:type:`event` Response to a
|
|
:zeek:see:`Management::Controller::API::get_nodes_request` event.
|
|
:zeek:id:`Management::Controller::API::notify_agents_ready`: :zeek:type:`event` The controller triggers this event when the operational cluster
|
|
instances align with the ones desired by the cluster
|
|
configuration.
|
|
:zeek:id:`Management::Controller::API::restart_request`: :zeek:type:`event` The client sends this event to restart currently running Zeek cluster
|
|
nodes.
|
|
:zeek:id:`Management::Controller::API::restart_response`: :zeek:type:`event` Response to a :zeek:see:`Management::Controller::API::restart_request`
|
|
event.
|
|
:zeek:id:`Management::Controller::API::stage_configuration_request`: :zeek:type:`event` Upload a configuration to the controller for later deployment.
|
|
:zeek:id:`Management::Controller::API::stage_configuration_response`: :zeek:type:`event` Response to a
|
|
:zeek:see:`Management::Controller::API::stage_configuration_request`
|
|
event.
|
|
:zeek:id:`Management::Controller::API::test_timeout_request`: :zeek:type:`event` This event causes no further action (other than getting logged) if
|
|
with_state is F.
|
|
:zeek:id:`Management::Controller::API::test_timeout_response`: :zeek:type:`event` Response to a
|
|
:zeek:see:`Management::Controller::API::test_timeout_request`
|
|
event.
|
|
======================================================================================== ======================================================================
|
|
|
|
|
|
Detailed Interface
|
|
~~~~~~~~~~~~~~~~~~
|
|
Constants
|
|
#########
|
|
.. zeek:id:: Management::Controller::API::version
|
|
:source-code: policy/frameworks/management/controller/api.zeek 13 13
|
|
|
|
:Type: :zeek:type:`count`
|
|
:Default: ``1``
|
|
|
|
A simple versioning scheme, used to track basic compatibility of
|
|
controller, agents, and the client.
|
|
|
|
Events
|
|
######
|
|
.. zeek:id:: Management::Controller::API::deploy_request
|
|
:source-code: policy/frameworks/management/controller/main.zeek 1088 1128
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`)
|
|
|
|
Trigger deployment of a previously staged configuration. The client
|
|
sends this event to the controller, which deploys the configuration
|
|
to the agents. Agents then terminate any previously running cluster
|
|
nodes and (re-)launch those defined in the new configuration. Once
|
|
each agent has responded (or a timeout occurs), the controller sends
|
|
a response event back to the client, aggregating the results from the
|
|
agents. The controller keeps the staged configuration available for
|
|
download, or re-deployment. In addition, the deployed configuration
|
|
becomes available for download as well, with any augmentations
|
|
(e.g. node ports filled in by auto-assignment) reflected.
|
|
|
|
|
|
:param reqid: a request identifier string, echoed in the response event.
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::deploy_response
|
|
:source-code: policy/frameworks/management/controller/api.zeek 119 119
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`, results: :zeek:type:`Management::ResultVec`)
|
|
|
|
Response to a :zeek:see:`Management::Controller::API::deploy_request`
|
|
event. The controller sends this back to the client, conveying the
|
|
outcome of the deployment.
|
|
|
|
|
|
:param reqid: the request identifier used in the request event.
|
|
|
|
|
|
:param results: a vector of :zeek:see:`Management::Result` records.
|
|
Each member captures the result of launching one cluster
|
|
node captured in the configuration, or an agent-wide error
|
|
when the result does not indicate a particular node.
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::get_configuration_request
|
|
:source-code: policy/frameworks/management/controller/main.zeek 1063 1086
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`, deployed: :zeek:type:`bool`)
|
|
|
|
The client sends this event to retrieve the controller's current
|
|
cluster configuration(s).
|
|
|
|
|
|
:param reqid: a request identifier string, echoed in the response event.
|
|
|
|
|
|
:param deployed: when true, returns the deployed configuration (if any),
|
|
otherwise the staged one (if any).
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::get_configuration_response
|
|
:source-code: policy/frameworks/management/controller/api.zeek 89 89
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`, result: :zeek:type:`Management::Result`)
|
|
|
|
Response to a
|
|
:zeek:see:`Management::Controller::API::get_configuration_request`
|
|
event. The controller sends this back to the client, with the
|
|
requested configuration.
|
|
|
|
|
|
:param reqid: the request identifier used in the request event.
|
|
|
|
|
|
:param result: a :zeek:see:`Management::Result` record with a successful
|
|
:zeek:see:`Management::Configuration` in the data member, if
|
|
a configuration is currently deployed. Otherwise, a Result
|
|
record in error state, with no data value assigned.
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::get_id_value_request
|
|
:source-code: policy/frameworks/management/controller/main.zeek 1297 1374
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`, id: :zeek:type:`string`, nodes: :zeek:type:`set` [:zeek:type:`string`] :zeek:attr:`&default` = ``{ }`` :zeek:attr:`&optional`)
|
|
|
|
The client sends this event to retrieve the current value of a
|
|
variable in Zeek's global namespace, referenced by the given
|
|
identifier (i.e., variable name). The controller asks all agents
|
|
to retrieve this value from each cluster node, accumulates the
|
|
returned responses, and responds with a get_id_value_response
|
|
event back to the client.
|
|
|
|
|
|
:param reqid: a request identifier string, echoed in the response event.
|
|
|
|
|
|
:param id: the name of the variable whose value to retrieve.
|
|
|
|
|
|
:param nodes: a set of cluster node names (e.g. "worker-01") to retrieve
|
|
the values from. An empty set, supplied by default, means
|
|
retrieval from all current cluster nodes.
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::get_id_value_response
|
|
:source-code: policy/frameworks/management/controller/api.zeek 182 182
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`, results: :zeek:type:`Management::ResultVec`)
|
|
|
|
Response to a
|
|
:zeek:see:`Management::Controller::API::get_id_value_request`
|
|
event. The controller sends this back to the client, with a JSON
|
|
representation of the requested global ID on all relevant instances.
|
|
|
|
|
|
:param reqid: the request identifier used in the request event.
|
|
|
|
|
|
:param results: a :zeek:type:`vector` of :zeek:see:`Management::Result`
|
|
records. Each record covers one Zeek cluster node. Each record's
|
|
data field contains a string with the JSON rendering (as produced
|
|
by :zeek:id:`to_json`, including the error strings it potentially
|
|
returns).
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::get_instances_request
|
|
:source-code: policy/frameworks/management/controller/main.zeek 1130 1151
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`)
|
|
|
|
The client sends this event to request a list of the currently
|
|
peered agents/instances.
|
|
|
|
|
|
:param reqid: a request identifier string, echoed in the response event.
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::get_instances_response
|
|
:source-code: policy/frameworks/management/controller/api.zeek 32 32
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`, result: :zeek:type:`Management::Result`)
|
|
|
|
Response to a
|
|
:zeek:see:`Management::Controller::API::get_instances_request`
|
|
event. The controller sends this back to the client.
|
|
|
|
|
|
:param reqid: the request identifier used in the request event.
|
|
|
|
|
|
:param result: a :zeek:see:`Management::Result`. Its data member is a vector
|
|
of :zeek:see:`Management::Instance` records.
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::get_nodes_request
|
|
:source-code: policy/frameworks/management/controller/main.zeek 1199 1228
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`)
|
|
|
|
The client sends this event to request a list of
|
|
:zeek:see:`Management::NodeStatus` records that capture
|
|
the status of Supervisor-managed nodes running on the cluster's
|
|
instances.
|
|
|
|
|
|
:param reqid: a request identifier string, echoed in the response event.
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::get_nodes_response
|
|
:source-code: policy/frameworks/management/controller/api.zeek 147 147
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`, results: :zeek:type:`Management::ResultVec`)
|
|
|
|
Response to a
|
|
:zeek:see:`Management::Controller::API::get_nodes_request` event. The
|
|
controller sends this back to the client, with a description of the
|
|
nodes currently managed by the Supervisors on all connected
|
|
instances. This includes agents and possibly the controller, if it
|
|
runs jointly with an agent.
|
|
|
|
|
|
:param reqid: the request identifier used in the request event.
|
|
|
|
|
|
:param results: a :zeek:type:`vector` of :zeek:see:`Management::Result`
|
|
records. Each record covers one cluster instance. Each record's
|
|
data member is a vector of :zeek:see:`Management::NodeStatus`
|
|
records, covering the nodes at that instance. Results may also
|
|
indicate failure, with error messages indicating what went wrong.
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::notify_agents_ready
|
|
:source-code: policy/frameworks/management/controller/main.zeek 801 833
|
|
|
|
:Type: :zeek:type:`event` (instances: :zeek:type:`set` [:zeek:type:`string`])
|
|
|
|
The controller triggers this event when the operational cluster
|
|
instances align with the ones desired by the cluster
|
|
configuration. It's essentially a cluster management readiness
|
|
event. This event is currently only used internally by the controller,
|
|
and not published to topics.
|
|
|
|
|
|
:param instances: the set of instance names now ready.
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::restart_request
|
|
:source-code: policy/frameworks/management/controller/main.zeek 1416 1509
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`, nodes: :zeek:type:`set` [:zeek:type:`string`] :zeek:attr:`&default` = ``{ }`` :zeek:attr:`&optional`)
|
|
|
|
The client sends this event to restart currently running Zeek cluster
|
|
nodes. The controller relays the request to its agents, which respond
|
|
with a list of :zeek:see:`Management::Result` records summarizing
|
|
each node restart. The controller combines these lists, and sends a
|
|
:zeek:see:`Management::Controller::API::restart_response` event with
|
|
the result.
|
|
|
|
|
|
:param reqid: a request identifier string, echoed in the response event.
|
|
|
|
|
|
:param nodes: a set of cluster node names (e.g. "worker-01") to restart. An
|
|
empty set, supplied by default, means restart of all current
|
|
cluster nodes.
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::restart_response
|
|
:source-code: policy/frameworks/management/controller/api.zeek 213 213
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`, results: :zeek:type:`Management::ResultVec`)
|
|
|
|
Response to a :zeek:see:`Management::Controller::API::restart_request`
|
|
event. The controller sends this back to the client when it has received
|
|
responses from all agents involved, or a timeout occurs.
|
|
|
|
|
|
:param reqid: the request identifier used in the request event.
|
|
|
|
|
|
:param results: a :zeek:type:`vector` of :zeek:see:`Management::Result`,
|
|
combining the restart results from all agents. Each such result
|
|
identifies both the instance and node in question. Results that
|
|
do not identify an instance are generated by the controller,
|
|
flagging corner cases, including absence of a deployed cluster
|
|
or unknown nodes.
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::stage_configuration_request
|
|
:source-code: policy/frameworks/management/controller/main.zeek 1002 1061
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`, config: :zeek:type:`Management::Configuration`)
|
|
|
|
Upload a configuration to the controller for later deployment.
|
|
The client sends this event to the controller, which validates the
|
|
configuration and indicates the outcome in its response event. No
|
|
deployment takes place yet, and existing deployed configurations and
|
|
the running Zeek cluster remain intact. To trigger deployment of an uploaded
|
|
configuration, use :zeek:see:`Management::Controller::API::deploy_request`.
|
|
|
|
|
|
:param reqid: a request identifier string, echoed in the response event.
|
|
|
|
|
|
:param config: a :zeek:see:`Management::Configuration` record
|
|
specifying the cluster configuration.
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::stage_configuration_response
|
|
:source-code: policy/frameworks/management/controller/api.zeek 63 63
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`, results: :zeek:type:`Management::ResultVec`)
|
|
|
|
Response to a
|
|
:zeek:see:`Management::Controller::API::stage_configuration_request`
|
|
event. The controller sends this back to the client, conveying
|
|
validation results.
|
|
|
|
|
|
:param reqid: the request identifier used in the request event.
|
|
|
|
|
|
:param results: a :zeek:see:`Management::Result` vector, indicating whether
|
|
the controller accepts the configuration. In case of a success,
|
|
a single result record indicates so. Otherwise, the sequence is
|
|
all errors, each indicating a configuration validation error.
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::test_timeout_request
|
|
:source-code: policy/frameworks/management/controller/main.zeek 1588 1599
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`, with_state: :zeek:type:`bool`)
|
|
|
|
This event causes no further action (other than getting logged) if
|
|
with_state is F. When T, the controller establishes request state, and
|
|
the controller only ever sends the response event when this state times
|
|
out.
|
|
|
|
|
|
:param reqid: a request identifier string, echoed in the response event when
|
|
with_state is T.
|
|
|
|
|
|
:param with_state: flag indicating whether the controller should keep (and
|
|
time out) request state for this request.
|
|
|
|
|
|
.. zeek:id:: Management::Controller::API::test_timeout_response
|
|
:source-code: policy/frameworks/management/controller/api.zeek 238 238
|
|
|
|
:Type: :zeek:type:`event` (reqid: :zeek:type:`string`, result: :zeek:type:`Management::Result`)
|
|
|
|
Response to a
|
|
:zeek:see:`Management::Controller::API::test_timeout_request`
|
|
event. The controller sends this back to the client if the original
|
|
request had the with_state flag.
|
|
|
|
|
|
:param reqid: the request identifier used in the request event.
|
|
|
|
|
|
|