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.
Copyright 2016, The Bro Project. Last updated on October 17, 2017. Created using Sphinx 1.5.2.