mirror of
https://github.com/zeek/zeek.git
synced 2025-10-03 07:08:19 +00:00
ded98cd373
This is based on commit 2731def9159247e6da8a3191783c89683363689c from the zeek-docs repo.
377 lines
14 KiB
ReStructuredText
377 lines
14 KiB
ReStructuredText
:tocdepth: 3
|
|
|
|
base/frameworks/supervisor/api.zeek
|
|
===================================
|
|
.. zeek:namespace:: Supervisor
|
|
|
|
The Zeek process supervision API.
|
|
This API was introduced in Zeek 3.1.0 and considered unstable until 4.0.0.
|
|
That is, it may change in various incompatible ways without warning or
|
|
deprecation until the stable 4.0.0 release.
|
|
|
|
:Namespace: Supervisor
|
|
|
|
Summary
|
|
~~~~~~~
|
|
Types
|
|
#####
|
|
============================================================= ========================================================================
|
|
:zeek:type:`Supervisor::ClusterEndpoint`: :zeek:type:`record` Describes configuration of a supervised-node within Zeek's Cluster
|
|
Framework.
|
|
:zeek:type:`Supervisor::ClusterRole`: :zeek:type:`enum` The role a supervised-node will play in Zeek's Cluster Framework.
|
|
:zeek:type:`Supervisor::NodeConfig`: :zeek:type:`record` Configuration options that influence behavior of a supervised Zeek node.
|
|
:zeek:type:`Supervisor::NodeStatus`: :zeek:type:`record` The current status of a supervised node.
|
|
:zeek:type:`Supervisor::Status`: :zeek:type:`record` The current status of a set of supervised nodes.
|
|
============================================================= ========================================================================
|
|
|
|
Events
|
|
######
|
|
====================================================== ================================================================
|
|
:zeek:id:`Supervisor::node_status`: :zeek:type:`event` A notification event the Supervisor generates when it receives a
|
|
status message update from the stem, indicating node has
|
|
(re-)started.
|
|
====================================================== ================================================================
|
|
|
|
Hooks
|
|
#####
|
|
===================================================== ==================================================================
|
|
:zeek:id:`Supervisor::stderr_hook`: :zeek:type:`hook` Hooks into the stderr stream for all supervisor's child processes.
|
|
:zeek:id:`Supervisor::stdout_hook`: :zeek:type:`hook` Hooks into the stdout stream for all supervisor's child processes.
|
|
===================================================== ==================================================================
|
|
|
|
Functions
|
|
#########
|
|
=========================================================== =============================================================
|
|
:zeek:id:`Supervisor::create`: :zeek:type:`function` Create a new supervised node process.
|
|
:zeek:id:`Supervisor::destroy`: :zeek:type:`function` Destroy and remove a supervised node process.
|
|
:zeek:id:`Supervisor::is_supervised`: :zeek:type:`function` Returns: true if this is a supervised node process.
|
|
:zeek:id:`Supervisor::is_supervisor`: :zeek:type:`function` Returns: true if this is the Supervisor process.
|
|
:zeek:id:`Supervisor::node`: :zeek:type:`function` Returns: the node configuration if this is a supervised node.
|
|
:zeek:id:`Supervisor::restart`: :zeek:type:`function` Restart a supervised node process by destroying (killing) and
|
|
re-recreating it.
|
|
:zeek:id:`Supervisor::status`: :zeek:type:`function` Retrieve current status of a supervised node process.
|
|
=========================================================== =============================================================
|
|
|
|
|
|
Detailed Interface
|
|
~~~~~~~~~~~~~~~~~~
|
|
Types
|
|
#####
|
|
.. zeek:type:: Supervisor::ClusterEndpoint
|
|
:source-code: base/frameworks/supervisor/api.zeek 20 35
|
|
|
|
:Type: :zeek:type:`record`
|
|
|
|
|
|
.. zeek:field:: role :zeek:type:`Supervisor::ClusterRole`
|
|
|
|
The role a supervised-node will play in Zeek's Cluster Framework.
|
|
|
|
|
|
.. zeek:field:: host :zeek:type:`addr`
|
|
|
|
The host/IP at which the cluster node runs.
|
|
|
|
|
|
.. zeek:field:: p :zeek:type:`port`
|
|
|
|
The TCP port at which the cluster node listens for connections.
|
|
|
|
|
|
.. zeek:field:: interface :zeek:type:`string` :zeek:attr:`&optional`
|
|
|
|
The interface name from which the node will read/analyze packets.
|
|
Typically used by worker nodes.
|
|
|
|
|
|
.. zeek:field:: pcap_file :zeek:type:`string` :zeek:attr:`&optional`
|
|
|
|
The PCAP file name from which the node will read/analyze packets.
|
|
Typically used by worker nodes.
|
|
|
|
|
|
.. zeek:field:: metrics_port :zeek:type:`port` :zeek:attr:`&optional`
|
|
|
|
The TCP port at which the cluster node exposes metrics for Prometheus.
|
|
|
|
|
|
Describes configuration of a supervised-node within Zeek's Cluster
|
|
Framework.
|
|
|
|
.. zeek:type:: Supervisor::ClusterRole
|
|
:source-code: base/frameworks/supervisor/api.zeek 10 10
|
|
|
|
:Type: :zeek:type:`enum`
|
|
|
|
.. zeek:enum:: Supervisor::NONE Supervisor::ClusterRole
|
|
|
|
.. zeek:enum:: Supervisor::LOGGER Supervisor::ClusterRole
|
|
|
|
.. zeek:enum:: Supervisor::MANAGER Supervisor::ClusterRole
|
|
|
|
.. zeek:enum:: Supervisor::PROXY Supervisor::ClusterRole
|
|
|
|
.. zeek:enum:: Supervisor::WORKER Supervisor::ClusterRole
|
|
|
|
The role a supervised-node will play in Zeek's Cluster Framework.
|
|
|
|
.. zeek:type:: Supervisor::NodeConfig
|
|
:source-code: base/frameworks/supervisor/api.zeek 38 73
|
|
|
|
:Type: :zeek:type:`record`
|
|
|
|
|
|
.. zeek:field:: name :zeek:type:`string`
|
|
|
|
The name of the supervised node. These are unique within a given
|
|
supervised process tree and typically human-readable.
|
|
|
|
|
|
.. zeek:field:: interface :zeek:type:`string` :zeek:attr:`&optional`
|
|
|
|
The interface name from which the node will read/analyze packets.
|
|
|
|
|
|
.. zeek:field:: pcap_file :zeek:type:`string` :zeek:attr:`&optional`
|
|
|
|
The PCAP file name from which the node will read/analyze packets.
|
|
|
|
|
|
.. zeek:field:: directory :zeek:type:`string` :zeek:attr:`&optional`
|
|
|
|
The working directory that the node should use.
|
|
|
|
|
|
.. zeek:field:: stdout_file :zeek:type:`string` :zeek:attr:`&optional`
|
|
|
|
The filename/path to which the node's stdout will be redirected.
|
|
|
|
|
|
.. zeek:field:: stderr_file :zeek:type:`string` :zeek:attr:`&optional`
|
|
|
|
The filename/path to which the node's stderr will be redirected.
|
|
|
|
|
|
.. zeek:field:: bare_mode :zeek:type:`bool` :zeek:attr:`&optional`
|
|
|
|
Whether to start the node in bare mode. When left out, the node
|
|
inherits the bare-mode status the supervisor itself runs with.
|
|
|
|
|
|
.. zeek:field:: addl_base_scripts :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional`
|
|
|
|
Additional script filenames/paths that the node should load
|
|
after the base scripts, and prior to any user-specified ones.
|
|
|
|
|
|
.. zeek:field:: addl_user_scripts :zeek:type:`vector` of :zeek:type:`string` :zeek:attr:`&default` = ``[]`` :zeek:attr:`&optional`
|
|
|
|
Additional script filenames/paths that the node should load
|
|
after any user-specified scripts.
|
|
|
|
|
|
.. zeek:field:: env :zeek:type:`table` [:zeek:type:`string`] of :zeek:type:`string` :zeek:attr:`&default` = ``{ }`` :zeek:attr:`&optional`
|
|
|
|
Environment variables to define in the supervised node.
|
|
|
|
|
|
.. zeek:field:: cpu_affinity :zeek:type:`int` :zeek:attr:`&optional`
|
|
|
|
A cpu/core number to which the node will try to pin itself.
|
|
|
|
|
|
.. zeek:field:: cluster :zeek:type:`table` [:zeek:type:`string`] of :zeek:type:`Supervisor::ClusterEndpoint` :zeek:attr:`&default` = ``{ }`` :zeek:attr:`&optional`
|
|
|
|
The Cluster Layout definition. Each node in the Cluster Framework
|
|
knows about the full, static cluster topology to which it belongs.
|
|
Entries use node names for keys. The Supervisor framework will
|
|
automatically translate this table into the right Cluster Framework
|
|
configuration when spawning supervised-nodes. E.g. it will
|
|
populate the both the CLUSTER_NODE environment variable and
|
|
:zeek:see:`Cluster::nodes` table.
|
|
|
|
|
|
Configuration options that influence behavior of a supervised Zeek node.
|
|
|
|
.. zeek:type:: Supervisor::NodeStatus
|
|
:source-code: base/frameworks/supervisor/api.zeek 76 82
|
|
|
|
:Type: :zeek:type:`record`
|
|
|
|
|
|
.. zeek:field:: node :zeek:type:`Supervisor::NodeConfig`
|
|
|
|
The desired node configuration.
|
|
|
|
|
|
.. zeek:field:: pid :zeek:type:`int` :zeek:attr:`&optional`
|
|
|
|
The current or last known process ID of the node. This may not
|
|
be initialized if the process has not yet started.
|
|
|
|
|
|
The current status of a supervised node.
|
|
|
|
.. zeek:type:: Supervisor::Status
|
|
:source-code: base/frameworks/supervisor/api.zeek 85 88
|
|
|
|
:Type: :zeek:type:`record`
|
|
|
|
|
|
.. zeek:field:: nodes :zeek:type:`table` [:zeek:type:`string`] of :zeek:type:`Supervisor::NodeStatus`
|
|
|
|
The status of supervised nodes, keyed by node names.
|
|
|
|
|
|
The current status of a set of supervised nodes.
|
|
|
|
Events
|
|
######
|
|
.. zeek:id:: Supervisor::node_status
|
|
:source-code: base/frameworks/supervisor/api.zeek 174 174
|
|
|
|
:Type: :zeek:type:`event` (node: :zeek:type:`string`, pid: :zeek:type:`count`)
|
|
|
|
A notification event the Supervisor generates when it receives a
|
|
status message update from the stem, indicating node has
|
|
(re-)started.
|
|
|
|
|
|
:param node: the name of a previously created node via
|
|
:zeek:see:`Supervisor::create` indicating to which
|
|
child process the stdout line is associated.
|
|
|
|
|
|
:param pid: the process ID the stem reported for this node.
|
|
|
|
Hooks
|
|
#####
|
|
.. zeek:id:: Supervisor::stderr_hook
|
|
:source-code: policy/frameworks/management/supervisor/main.zeek 77 92
|
|
|
|
:Type: :zeek:type:`hook` (node: :zeek:type:`string`, msg: :zeek:type:`string`) : :zeek:type:`bool`
|
|
|
|
Hooks into the stderr stream for all supervisor's child processes.
|
|
If a hook terminates with ``break``, that will suppress output to the
|
|
associated stream.
|
|
|
|
|
|
:param node: the name of a previously created node via
|
|
:zeek:see:`Supervisor::create` indicating to which
|
|
child process the stdout line is associated.
|
|
A empty value is used to indicate the message
|
|
came from the internal supervisor stem process.
|
|
(this should typically never happen).
|
|
|
|
|
|
:param msg: line-buffered contents from the stderr of a child process.
|
|
|
|
.. zeek:id:: Supervisor::stdout_hook
|
|
:source-code: policy/frameworks/management/supervisor/main.zeek 55 75
|
|
|
|
:Type: :zeek:type:`hook` (node: :zeek:type:`string`, msg: :zeek:type:`string`) : :zeek:type:`bool`
|
|
|
|
Hooks into the stdout stream for all supervisor's child processes.
|
|
If a hook terminates with ``break``, that will suppress output to the
|
|
associated stream.
|
|
|
|
|
|
:param node: the name of a previously created node via
|
|
:zeek:see:`Supervisor::create` indicating to which
|
|
child process the stdout line is associated.
|
|
An empty value is used to indicate the message
|
|
came from the internal supervisor stem process
|
|
(this should typically never happen).
|
|
|
|
|
|
:param msg: line-buffered contents from the stdout of a child process.
|
|
|
|
Functions
|
|
#########
|
|
.. zeek:id:: Supervisor::create
|
|
:source-code: base/frameworks/supervisor/main.zeek 12 15
|
|
|
|
:Type: :zeek:type:`function` (node: :zeek:type:`Supervisor::NodeConfig`) : :zeek:type:`string`
|
|
|
|
Create a new supervised node process.
|
|
It's an error to call this from a process other than a Supervisor.
|
|
|
|
|
|
:param node: the desired configuration for the new supervised node process.
|
|
|
|
|
|
:returns: an empty string on success or description of the error/failure.
|
|
|
|
.. zeek:id:: Supervisor::destroy
|
|
:source-code: base/frameworks/supervisor/main.zeek 17 20
|
|
|
|
:Type: :zeek:type:`function` (node: :zeek:type:`string` :zeek:attr:`&default` = ``""`` :zeek:attr:`&optional`) : :zeek:type:`bool`
|
|
|
|
Destroy and remove a supervised node process.
|
|
It's an error to call this from a process other than a Supervisor.
|
|
|
|
|
|
:param node: the name of the node to destroy or an empty string to mean
|
|
"all nodes".
|
|
|
|
|
|
:returns: true on success.
|
|
|
|
.. zeek:id:: Supervisor::is_supervised
|
|
:source-code: base/frameworks/supervisor/main.zeek 32 35
|
|
|
|
:Type: :zeek:type:`function` () : :zeek:type:`bool`
|
|
|
|
|
|
:returns: true if this is a supervised node process.
|
|
|
|
.. zeek:id:: Supervisor::is_supervisor
|
|
:source-code: base/frameworks/supervisor/main.zeek 27 30
|
|
|
|
:Type: :zeek:type:`function` () : :zeek:type:`bool`
|
|
|
|
|
|
:returns: true if this is the Supervisor process.
|
|
|
|
.. zeek:id:: Supervisor::node
|
|
:source-code: base/frameworks/supervisor/main.zeek 37 40
|
|
|
|
:Type: :zeek:type:`function` () : :zeek:type:`Supervisor::NodeConfig`
|
|
|
|
|
|
:returns: the node configuration if this is a supervised node.
|
|
It's an error to call this function from a process other than
|
|
a supervised one.
|
|
|
|
.. zeek:id:: Supervisor::restart
|
|
:source-code: base/frameworks/supervisor/main.zeek 22 25
|
|
|
|
:Type: :zeek:type:`function` (node: :zeek:type:`string` :zeek:attr:`&default` = ``""`` :zeek:attr:`&optional`) : :zeek:type:`bool`
|
|
|
|
Restart a supervised node process by destroying (killing) and
|
|
re-recreating it.
|
|
It's an error to call this from a process other than a Supervisor.
|
|
|
|
|
|
:param node: the name of the node to restart or an empty string to mean
|
|
"all nodes".
|
|
|
|
|
|
:returns: true on success.
|
|
|
|
.. zeek:id:: Supervisor::status
|
|
:source-code: base/frameworks/supervisor/main.zeek 7 10
|
|
|
|
:Type: :zeek:type:`function` (node: :zeek:type:`string` :zeek:attr:`&default` = ``""`` :zeek:attr:`&optional`) : :zeek:type:`Supervisor::Status`
|
|
|
|
Retrieve current status of a supervised node process.
|
|
It's an error to call this from a process other than a Supervisor.
|
|
|
|
|
|
:param node: the name of the node to get the status of or an empty string
|
|
to mean "all nodes".
|
|
|
|
|
|
:returns: the current status of a set of nodes.
|
|
|
|
|