policy/frameworks/management/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

metrics_port: port &optional

Metrics exposure port, for Prometheus

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.

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

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.