base/frameworks/cluster/main.bro

Cluster

A framework for establishing and controlling a cluster of Bro instances. In order to use the cluster framework, a script named cluster-layout.bro must exist somewhere in Bro’s script search path which has a cluster definition of the Cluster::nodes variable. The CLUSTER_NODE environment variable or Cluster::node must also be sent and the cluster framework loaded as a package like @load base/frameworks/cluster.

Namespace:Cluster Imports:base/frameworks/control Source File:/scripts/base/frameworks/cluster/main.bro

Summary

Options

Cluster::control_events: pattern &redef	Events sent by the control host (i.e., BroControl) when dynamically connecting to a running instance to update settings or request data.
Cluster::manager2logger_events: pattern &redef	Events raised by a manager and handled by loggers.
Cluster::manager2proxy_events: pattern &redef	Events raised by a manager and handled by proxies.
Cluster::manager2worker_events: pattern &redef	Events raised by a manager and handled by the workers.
Cluster::manager_is_logger: bool &redef	Indicates whether or not the manager will act as the logger and receive logs.
Cluster::node: string &redef	This is usually supplied on the command line for each instance of the cluster that is started up.
Cluster::nodes: table &redef	The cluster layout definition.
Cluster::proxy2logger_events: pattern &redef	Events raised by proxies and handled by loggers.
Cluster::proxy2manager_events: pattern &redef	Events raised by proxies and handled by a manager.
Cluster::proxy2worker_events: pattern &redef	Events raised by proxies and handled by workers.
Cluster::retry_interval: interval &redef	Interval for retrying failed connections between cluster nodes.
Cluster::tm2manager_events: pattern &redef	Events raised by TimeMachine instances and handled by a manager.
Cluster::tm2worker_events: pattern &redef	Events raised by TimeMachine instances and handled by workers.
Cluster::worker2logger_events: pattern &redef	Events raised by workers and handled by loggers.
Cluster::worker2manager_events: pattern &redef	Events raised by workers and handled by a manager.
Cluster::worker2proxy_events: pattern &redef	Events raised by workers and handled by proxies.

State Variables

Cluster::worker_count: count

This gives the value for the number of workers currently connected to, and it’s maintained internally by the cluster framework.

Types

Cluster::Info: record &log	The record type which contains the column fields of the cluster log.
Cluster::Node: record	Record type to indicate a node in a cluster.
Cluster::NodeType: enum	Types of nodes that are allowed to participate in the cluster configuration.

Redefinitions

Log::ID: enum

The cluster logging stream identifier.

Functions

Cluster::is_enabled: function	This function can be called at any time to determine if the cluster framework is being enabled for this run.
Cluster::local_node_type: function	This function can be called at any time to determine what type of cluster node the current Bro instance is going to be acting as.

Detailed Interface

Options

Cluster::control_events

Type:pattern Attributes:&redef Default:

/^?(Control::.*_request)$?/

Events sent by the control host (i.e., BroControl) when dynamically connecting to a running instance to update settings or request data.

Cluster::manager2logger_events

Type:pattern Attributes:&redef Default:

/^?(EMPTY)$?/

Events raised by a manager and handled by loggers.

Cluster::manager2proxy_events

Type:pattern Attributes:&redef Default:

/^?(EMPTY)$?/

Events raised by a manager and handled by proxies.

Cluster::manager2worker_events

Type:pattern Attributes:&redef Default:

/^?(Drop::.*)$?/

Events raised by a manager and handled by the workers.

Cluster::manager_is_logger

Type:bool Attributes:&redef Default:T

Indicates whether or not the manager will act as the logger and receive logs. This value should be set in the cluster-layout.bro script (the value should be true only if no logger is specified in Cluster::nodes). Note that BroControl handles this automatically.

Cluster::node

Type:string Attributes:&redef Default:""

This is usually supplied on the command line for each instance of the cluster that is started up.

Cluster::nodes

Type:table [string] of Cluster::Node Attributes:&redef Default:{}

The cluster layout definition. This should be placed into a filter named cluster-layout.bro somewhere in the BROPATH. It will be automatically loaded if the CLUSTER_NODE environment variable is set. Note that BroControl handles all of this automatically.

Cluster::proxy2logger_events

Type:pattern Attributes:&redef Default:

/^?(EMPTY)$?/

Events raised by proxies and handled by loggers.

Cluster::proxy2manager_events

Type:pattern Attributes:&redef Default:

/^?(EMPTY)$?/

Events raised by proxies and handled by a manager.

Cluster::proxy2worker_events

Type:pattern Attributes:&redef Default:

/^?(EMPTY)$?/

Events raised by proxies and handled by workers.

Cluster::retry_interval

Type:interval Attributes:&redef Default:1.0 min

Interval for retrying failed connections between cluster nodes.

Cluster::tm2manager_events

Type:pattern Attributes:&redef Default:

/^?(EMPTY)$?/

Events raised by TimeMachine instances and handled by a manager.

Cluster::tm2worker_events

Type:pattern Attributes:&redef Default:

/^?(EMPTY)$?/

Events raised by TimeMachine instances and handled by workers.

Cluster::worker2logger_events

Type:pattern Attributes:&redef Default:

/^?(EMPTY)$?/

Events raised by workers and handled by loggers.

Cluster::worker2manager_events

Type:pattern Attributes:&redef Default:

/^?((TimeMachine::command|Drop::.*))$?/

Events raised by workers and handled by a manager.

Cluster::worker2proxy_events

Type:pattern Attributes:&redef Default:

/^?(EMPTY)$?/

Events raised by workers and handled by proxies.

State Variables

Cluster::worker_count

Type:count Default:0

This gives the value for the number of workers currently connected to, and it’s maintained internally by the cluster framework. It’s primarily intended for use by managers to find out how many workers should be responding to requests.

Types

Cluster::Info

Type:

record

ts: time &log

The time at which a cluster message was generated.

message: string &log

A message indicating information about the cluster’s operation.

Attributes:

&log

The record type which contains the column fields of the cluster log.

Cluster::Node

Type:

record

node_type: Cluster::NodeType

Identifies the type of cluster node in this node’s configuration.

ip: addr

The IP address of the cluster node.

zone_id: string &default = "" &optional

If the ip field is a non-global IPv6 address, this field can specify a particular RFC 4007 zone_id.

p: port

The port to which this local node can connect when establishing communication.

interface: string &optional

Identifier for the interface a worker is sniffing.

logger: string &optional

Name of the logger node this node uses. For manager, proxies and workers.

manager: string &optional

Name of the manager node this node uses. For workers and proxies.

proxy: string &optional

Name of the proxy node this node uses. For workers and managers.

workers: set [string] &optional

Names of worker nodes that this node connects with. For managers and proxies.

time_machine: string &optional

Name of a time machine node with which this node connects.

lb_filter: string &optional

(present if policy/misc/load-balancing.bro is loaded)

A BPF filter for load balancing traffic sniffed on a single interface across a number of processes. In normal uses, this will be assigned dynamically by the manager and installed by the workers.

Record type to indicate a node in a cluster.

Cluster::NodeType

Type:

enum

Cluster::NONE

A dummy node type indicating the local node is not operating within a cluster.

Cluster::CONTROL

A node type which is allowed to view/manipulate the configuration of other nodes in the cluster.

Cluster::LOGGER

A node type responsible for log management.

Cluster::MANAGER

A node type responsible for policy management.

Cluster::PROXY

A node type for relaying worker node communication and synchronizing worker node state.

Cluster::WORKER

The node type doing all the actual traffic analysis.

Cluster::TIME_MACHINE

A node acting as a traffic recorder using the Time Machine software.

Types of nodes that are allowed to participate in the cluster configuration.

Functions

Cluster::is_enabled

Type:function () : bool

This function can be called at any time to determine if the cluster framework is being enabled for this run.

Returns:True if Cluster::node has been set.

Cluster::local_node_type

Type:function () : Cluster::NodeType

This function can be called at any time to determine what type of cluster node the current Bro instance is going to be acting as. If Cluster::is_enabled returns false, then Cluster::NONE is returned.

Returns:The Cluster::NodeType the calling node acts as.