api.zeek

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

`Supervisor::ClusterEndpoint`: `record`	Describes configuration of a supervised-node within Zeek’s Cluster Framework.
`Supervisor::ClusterRole`: `enum`	The role a supervised-node will play in Zeek’s Cluster Framework.
`Supervisor::NodeConfig`: `record`	Configuration options that influence behavior of a supervised Zeek node.
`Supervisor::NodeStatus`: `record`	The current status of a supervised node.
`Supervisor::Status`: `record`	The current status of a set of supervised nodes.

Events

Supervisor::node_status: event

A notification event the Supervisor generates when it receives a status message update from the stem, indicating node has (re-)started.

Hooks

`Supervisor::stderr_hook`: `hook`	Hooks into the stderr stream for all supervisor’s child processes.
`Supervisor::stdout_hook`: `hook`	Hooks into the stdout stream for all supervisor’s child processes.

Functions

`Supervisor::create`: `function`	Create a new supervised node process.
`Supervisor::destroy`: `function`	Destroy and remove a supervised node process.
`Supervisor::is_supervised`: `function`	Returns: true if this is a supervised node process.
`Supervisor::is_supervisor`: `function`	Returns: true if this is the Supervisor process.
`Supervisor::node`: `function`	Returns: the node configuration if this is a supervised node.
`Supervisor::restart`: `function`	Restart a supervised node process by destroying (killing) and re-recreating it.
`Supervisor::status`: `function`	Retrieve current status of a supervised node process.

Detailed Interface

Types

Supervisor::ClusterEndpoint 

Type

record

role: Supervisor::ClusterRole: The role a supervised-node will play in Zeek’s Cluster Framework.
host: addr: The host/IP at which the cluster node runs.
p: port: The TCP port at which the cluster node listens for connections.
interface: string &optional: The interface name from which the node will read/analyze packets. Typically used by worker nodes.
pcap_file: string &optional: The PCAP file name from which the node will read/analyze packets. Typically used by worker nodes.
metrics_port: port &optional: The TCP port at which the cluster node exposes metrics for Prometheus.

Describes configuration of a supervised-node within Zeek’s Cluster Framework.

Supervisor::ClusterRole 

Type

enum

Supervisor::NONE

Supervisor::LOGGER

Supervisor::MANAGER

Supervisor::PROXY

Supervisor::WORKER

The role a supervised-node will play in Zeek’s Cluster Framework.

Supervisor::NodeConfig 

Type

record

name: string: The name of the supervised node. These are unique within a given supervised process tree and typically human-readable.
interface: string &optional: The interface name from which the node will read/analyze packets.
pcap_file: string &optional: The PCAP file name from which the node will read/analyze packets.
directory: string &optional: The working directory that the node should use.
stdout_file: string &optional: The filename/path to which the node’s stdout will be redirected.
stderr_file: string &optional: The filename/path to which the node’s stderr will be redirected.
bare_mode: bool &optional: Whether to start the node in bare mode. When left out, the node inherits the bare-mode status the supervisor itself runs with.
addl_base_scripts: vector of string &default = [] &optional: Additional script filenames/paths that the node should load after the base scripts, and prior to any user-specified ones.
addl_user_scripts: vector of string &default = [] &optional: Additional script filenames/paths that the node should load after any user-specified scripts.
env: table [string] of string &default = { } &optional: Environment variables to define in the supervised node.
cpu_affinity: int &optional: A cpu/core number to which the node will try to pin itself.
cluster: table [string] of Supervisor::ClusterEndpoint &default = { } &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 Cluster::nodes table.

Configuration options that influence behavior of a supervised Zeek node.

Supervisor::NodeStatus 

Type

record

node: Supervisor::NodeConfig: The desired node configuration.
pid: int &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.

Supervisor::Status 

Type

record

nodes: table [string] of Supervisor::NodeStatus: The status of supervised nodes, keyed by node names.

The current status of a set of supervised nodes.

Events

Supervisor::node_status 

Type: event (node: string, pid: count)

A notification event the Supervisor generates when it receives a status message update from the stem, indicating node has (re-)started.

Parameters

node – the name of a previously created node via Supervisor::create indicating to which child process the stdout line is associated.
pid – the process ID the stem reported for this node.

Hooks

Supervisor::stderr_hook 

Type: hook (node: string, msg: string) : 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.

Parameters

node – the name of a previously created node via 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).
msg – line-buffered contents from the stderr of a child process.

Supervisor::stdout_hook 

Type: hook (node: string, msg: string) : 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.

Parameters

node – the name of a previously created node via 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).
msg – line-buffered contents from the stdout of a child process.

Functions

Supervisor::create 

Type: function (node: Supervisor::NodeConfig) : string

Create a new supervised node process. It’s an error to call this from a process other than a Supervisor.

Parameters: node – the desired configuration for the new supervised node process.
Returns: an empty string on success or description of the error/failure.

Supervisor::destroy 

Type: function (node: string &default = "" &optional) : bool

Destroy and remove a supervised node process. It’s an error to call this from a process other than a Supervisor.

Parameters: node – the name of the node to destroy or an empty string to mean “all nodes”.
Returns: true on success.

Supervisor::is_supervised 

Type: function () : bool
Returns: true if this is a supervised node process.

Supervisor::is_supervisor 

Type: function () : bool
Returns: true if this is the Supervisor process.

Supervisor::node 

Type: function () : 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.

Supervisor::restart 

Type: function (node: string &default = "" &optional) : 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.

Parameters: node – the name of the node to restart or an empty string to mean “all nodes”.
Returns: true on success.

Supervisor::status 

Type: function (node: string &default = "" &optional) : Supervisor::Status

Retrieve current status of a supervised node process. It’s an error to call this from a process other than a Supervisor.

Parameters: 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.