types.zeek

Management

This module holds the basic types needed for the Management framework. These are used by both cluster agent and controller, and several have corresponding implementations in zeek-client.

Namespace: Management

Summary

Types

`Management::Configuration`: `record`	Data structure capturing a cluster’s complete configuration.
`Management::Instance`: `record`	Configuration describing a Zeek instance running a Cluster Agent.
`Management::InstanceVec`: `vector`
`Management::Node`: `record`	Configuration describing a Cluster Node process.
`Management::NodeOutputs`: `record`	In `Management::Controller::API::deploy_response` events, each `Management::Result` indicates the outcome of a launched cluster node.
`Management::NodeStatus`: `record`	The status of a Supervisor-managed node, as reported to the client in a get_nodes_request/get_nodes_response transaction.
`Management::NodeStatusVec`: `vector`
`Management::Option`: `record`	A Zeek-side option with value.
`Management::Result`: `record`	Return value for request-response API event pairs.
`Management::ResultVec`: `vector`
`Management::Role`: `enum`	Management infrastructure node type.
`Management::State`: `enum`	State that a Cluster Node can be in.

Functions

`Management::result_to_string`: `function`	Given a `Management::Result` record, this function returns a string summarizing it.
`Management::result_vec_to_string`: `function`	Given a vector of `Management::Result` records, this function returns a string summarizing them.

Detailed Interface

Types

Management::Configuration 

Type

record

id: string &default = Chd8EgFWk2j &optional: Unique identifier for a particular configuration
instances: set [Management::Instance] &default = { } &optional: The instances in the cluster.
nodes: set [Management::Node] &default = { } &optional: The set of nodes in the cluster, as distributed over the instances.

Data structure capturing a cluster’s complete configuration.

Management::Instance 

Type

record

name: string: Unique, human-readable instance name
host: addr: IP address of system
listen_port: port &optional: Agent listening port. Not needed if agents connect to controller.

Configuration describing a Zeek instance running a Cluster Agent. Normally, there’ll be one instance per cluster system: a single physical system.

Management::InstanceVec 

Type: vector of Management::Instance

Management::Node 

Type

record

name: string: Cluster-unique, human-readable node name
instance: string: Name of instance where node is to run
role: Supervisor::ClusterRole: Role of the node.
state: Management::State: Desired, or current, run state.
p: port &optional: Port on which this node will listen
scripts: vector of string &optional: Additional Zeek scripts for node
options: set [Management::Option] &optional: Zeek options for node
interface: string &optional: Interface to sniff
cpu_affinity: int &optional: CPU/core number to pin to
env: table [string] of string &default = { } &optional: Custom environment vars

Configuration describing a Cluster Node process.

Management::NodeOutputs 

Type

record

stdout: string: The stdout stream of a Zeek process
stderr: string: The stderr stream of a Zeek process

In Management::Controller::API::deploy_response events, each Management::Result indicates the outcome of a launched cluster node. If a node does not launch properly (meaning it doesn’t check in with the agent on the machine it’s running on), the result will indicate failure, and its data field will be an instance of this record, capturing the stdout and stderr output of the failing node.

Management::NodeStatus 

Type

record

node: string: Cluster-unique, human-readable node name
state: Management::State: Current run state of the node.
mgmt_role: Management::Role &default = Management::NONE &optional: Role the node plays in cluster management.
cluster_role: Supervisor::ClusterRole &default = Supervisor::NONE &optional: Role the node plays in the Zeek cluster.
pid: int &optional: Process ID of the node. This is optional because the Supervisor may not have a PID when a node is still bootstrapping.
p: port &optional: The node’s Broker peering listening port, if any.

The status of a Supervisor-managed node, as reported to the client in a get_nodes_request/get_nodes_response transaction.

Management::NodeStatusVec 

Type: vector of Management::NodeStatus

Management::Option 

Type

record

name: string: Name of option
value: string: Value of option

A Zeek-side option with value.

Management::Result 

Type

record

reqid: string: Request ID of operation this result refers to
success: bool &default = T &optional: True if successful
instance: string &optional: Name of associated instance (for context)
data: any &optional: Addl data returned for successful operation
error: string &optional: Descriptive error on failure
node: string &optional: Name of associated node (for context)

Return value for request-response API event pairs. Some responses contain one, others multiple of these. The request ID allows clients to string requests and responses together. Agents and the controller fill in the instance and node fields whenever there’s sufficient context to define them. Any result produced by an agent will carry an instance value, for example.

Management::ResultVec 

Type: vector of Management::Result

Management::Role 

Type

enum

Management::NONE: No active role in cluster management

Management::AGENT: A cluster management agent.

Management::CONTROLLER: The cluster’s controller.

Management::NODE: A managed cluster node (worker, manager, etc).

Management infrastructure node type. This intentionally does not include the managed cluster node types (worker, logger, etc) – those continue to be managed by the cluster framework.

Management::State 

Type

enum

Management::PENDING: Not yet running

Management::RUNNING: Running and operating normally

Management::STOPPED: Explicitly stopped

Management::FAILED: Failed to start; and permanently halted

Management::CRASHED: Crashed, will be restarted,

Management::UNKNOWN: State not known currently (e.g., because of lost connectivity)

State that a Cluster Node can be in. State changes trigger an API notification (see notify_change()). The Pending state corresponds to the Supervisor not yet reporting a PID for a node when it has not yet fully launched.

Functions

Management::result_to_string 

Type: function (res: Management::Result) : string

Given a Management::Result record, this function returns a string summarizing it.

Management::result_vec_to_string 

Type: function (res: Management::ResultVec) : string

Given a vector of Management::Result records, this function returns a string summarizing them.