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.

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.

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.

scripts: vector of string &default = [] &optional &deprecated = “Remove in 6.1. Use the addl_user_scripts field instead.”

The former name of addl_user_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.