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

Fields:

id: string &default = Fm22x30CduPMuXAq1 &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

Fields:

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

Fields:

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

metrics_port: port &optional: Metrics exposure port, for Prometheus

Configuration describing a Cluster Node process.

Management::NodeOutputs 

Type:

record

Fields:

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

Fields:

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.

metrics_port: port &optional: The node’s metrics port for Prometheus, 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

Fields:

name: string: Name of option

value: string: Value of option

A Zeek-side option with value.

Management::Result 

Type:

record

Fields:

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.