:tocdepth: 3

base/frameworks/cluster/main.bro
================================
.. bro:namespace:: 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 :bro:id:`Cluster::nodes` variable.
The ``CLUSTER_NODE`` environment variable or :bro:id:`Cluster::node`
must also be sent and the cluster framework loaded as a package like
``@load base/frameworks/cluster``.

:Namespace: Cluster
:Imports: :doc:`base/frameworks/control </scripts/base/frameworks/control/index>`
:Source File: :download:`/scripts/base/frameworks/cluster/main.bro`

Summary
~~~~~~~
Options
#######
================================================================================ ================================================================
:bro:id:`Cluster::control_events`: :bro:type:`pattern` :bro:attr:`&redef`        Events sent by the control host (i.e.
:bro:id:`Cluster::manager2proxy_events`: :bro:type:`pattern` :bro:attr:`&redef`  Events raised by a manager and handled by proxies.
:bro:id:`Cluster::manager2worker_events`: :bro:type:`pattern` :bro:attr:`&redef` Events raised by a manager and handled by the workers.
:bro:id:`Cluster::node`: :bro:type:`string` :bro:attr:`&redef`                   This is usually supplied on the command line for each instance
                                                                                 of the cluster that is started up.
:bro:id:`Cluster::nodes`: :bro:type:`table` :bro:attr:`&redef`                   The cluster layout definition.
:bro:id:`Cluster::proxy2manager_events`: :bro:type:`pattern` :bro:attr:`&redef`  Events raised by proxies and handled by a manager.
:bro:id:`Cluster::proxy2worker_events`: :bro:type:`pattern` :bro:attr:`&redef`   Events raised by proxies and handled by workers.
:bro:id:`Cluster::tm2manager_events`: :bro:type:`pattern` :bro:attr:`&redef`     Events raised by TimeMachine instances and handled by a manager.
:bro:id:`Cluster::tm2worker_events`: :bro:type:`pattern` :bro:attr:`&redef`      Events raised by TimeMachine instances and handled by workers.
:bro:id:`Cluster::worker2manager_events`: :bro:type:`pattern` :bro:attr:`&redef` Events raised by workers and handled by a manager.
:bro:id:`Cluster::worker2proxy_events`: :bro:type:`pattern` :bro:attr:`&redef`   Events raised by workers and handled by proxies.
================================================================================ ================================================================

State Variables
###############
================================================== ======================================================================
:bro:id:`Cluster::worker_count`: :bro:type:`count` This gives the value for the number of workers currently connected to,
                                                   and it's maintained internally by the cluster framework.
================================================== ======================================================================

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

Redefinitions
#############
===================================== ======================================
:bro:type:`Log::ID`: :bro:type:`enum` The cluster logging stream identifier.
===================================== ======================================

Functions
#########
======================================================== ===================================================================
:bro:id:`Cluster::is_enabled`: :bro:type:`function`      This function can be called at any time to determine if the cluster
                                                         framework is being enabled for this run.
:bro:id:`Cluster::local_node_type`: :bro: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
#######
.. bro:id:: Cluster::control_events

   :Type: :bro:type:`pattern`
   :Attributes: :bro:attr:`&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.

.. bro:id:: Cluster::manager2proxy_events

   :Type: :bro:type:`pattern`
   :Attributes: :bro:attr:`&redef`
   :Default:

   ::

      /^?(EMPTY)$?/

   Events raised by a manager and handled by proxies.

.. bro:id:: Cluster::manager2worker_events

   :Type: :bro:type:`pattern`
   :Attributes: :bro:attr:`&redef`
   :Default:

   ::

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

   Events raised by a manager and handled by the workers.

.. bro:id:: Cluster::node

   :Type: :bro:type:`string`
   :Attributes: :bro:attr:`&redef`
   :Default: ``""``

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

.. bro:id:: Cluster::nodes

   :Type: :bro:type:`table` [:bro:type:`string`] of :bro:type:`Cluster::Node`
   :Attributes: :bro:attr:`&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.

.. bro:id:: Cluster::proxy2manager_events

   :Type: :bro:type:`pattern`
   :Attributes: :bro:attr:`&redef`
   :Default:

   ::

      /^?(EMPTY)$?/

   Events raised by proxies and handled by a manager.

.. bro:id:: Cluster::proxy2worker_events

   :Type: :bro:type:`pattern`
   :Attributes: :bro:attr:`&redef`
   :Default:

   ::

      /^?(EMPTY)$?/

   Events raised by proxies and handled by workers.

.. bro:id:: Cluster::tm2manager_events

   :Type: :bro:type:`pattern`
   :Attributes: :bro:attr:`&redef`
   :Default:

   ::

      /^?(EMPTY)$?/

   Events raised by TimeMachine instances and handled by a manager.

.. bro:id:: Cluster::tm2worker_events

   :Type: :bro:type:`pattern`
   :Attributes: :bro:attr:`&redef`
   :Default:

   ::

      /^?(EMPTY)$?/

   Events raised by TimeMachine instances and handled by workers.

.. bro:id:: Cluster::worker2manager_events

   :Type: :bro:type:`pattern`
   :Attributes: :bro:attr:`&redef`
   :Default:

   ::

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

   Events raised by workers and handled by a manager.

.. bro:id:: Cluster::worker2proxy_events

   :Type: :bro:type:`pattern`
   :Attributes: :bro:attr:`&redef`
   :Default:

   ::

      /^?(EMPTY)$?/

   Events raised by workers and handled by proxies.

State Variables
###############
.. bro:id:: Cluster::worker_count

   :Type: :bro: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
#####
.. bro:type:: Cluster::Info

   :Type: :bro:type:`record`

      ts: :bro:type:`time` :bro:attr:`&log`
         The time at which a cluster message was generated.

      message: :bro:type:`string` :bro:attr:`&log`
         A message indicating information about the cluster's operation.
   :Attributes: :bro:attr:`&log`

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

.. bro:type:: Cluster::Node

   :Type: :bro:type:`record`

      node_type: :bro:type:`Cluster::NodeType`
         Identifies the type of cluster node in this node's configuration.

      ip: :bro:type:`addr`
         The IP address of the cluster node.

      zone_id: :bro:type:`string` :bro:attr:`&default` = ``""`` :bro:attr:`&optional`
         If the *ip* field is a non-global IPv6 address, this field
         can specify a particular :rfc:`4007` ``zone_id``.

      p: :bro:type:`port`
         The port to which this local node can connect when
         establishing communication.

      interface: :bro:type:`string` :bro:attr:`&optional`
         Identifier for the interface a worker is sniffing.

      manager: :bro:type:`string` :bro:attr:`&optional`
         Name of the manager node this node uses.  For workers and proxies.

      proxy: :bro:type:`string` :bro:attr:`&optional`
         Name of the proxy node this node uses.  For workers and managers.

      workers: :bro:type:`set` [:bro:type:`string`] :bro:attr:`&optional`
         Names of worker nodes that this node connects with.
         For managers and proxies.

      time_machine: :bro:type:`string` :bro:attr:`&optional`
         Name of a time machine node with which this node connects.

      lb_filter: :bro:type:`string` :bro:attr:`&optional`
         (present if :doc:`/scripts/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.

.. bro:type:: Cluster::NodeType

   :Type: :bro:type:`enum`

      .. bro:enum:: Cluster::NONE Cluster::NodeType

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

      .. bro:enum:: Cluster::CONTROL Cluster::NodeType

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

      .. bro:enum:: Cluster::MANAGER Cluster::NodeType

         A node type responsible for log and policy management.

      .. bro:enum:: Cluster::PROXY Cluster::NodeType

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

      .. bro:enum:: Cluster::WORKER Cluster::NodeType

         The node type doing all the actual traffic analysis.

      .. bro:enum:: Cluster::TIME_MACHINE Cluster::NodeType

         A node acting as a traffic recorder using the
         `Time Machine <http://bro.org/community/time-machine.html>`_
         software.

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

Functions
#########
.. bro:id:: Cluster::is_enabled

   :Type: :bro:type:`function` () : :bro:type:`bool`

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

   :returns: True if :bro:id:`Cluster::node` has been set.

.. bro:id:: Cluster::local_node_type

   :Type: :bro:type:`function` () : :bro:type:`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 :bro:id:`Cluster::is_enabled` returns false, then
   :bro:enum:`Cluster::NONE` is returned.
   

   :returns: The :bro:type:`Cluster::NodeType` the calling node acts as.


