base/frameworks/supervisor/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.

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.

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.

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.

scripts: vector of string &default = [] &optional

Additional script filenames/paths that the node should load.

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.

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.

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.

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.

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.

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.

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.

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.