:tocdepth: 3

base/frameworks/communication/main.bro
======================================
.. bro:namespace:: Communication

Facilitates connecting to remote Bro or Broccoli instances to share state
and/or transfer events.

:Namespace: Communication
:Imports: :doc:`base/frameworks/packet-filter </scripts/base/frameworks/packet-filter/index>`, :doc:`base/utils/addrs.bro </scripts/base/utils/addrs.bro>`
:Source File: :download:`/scripts/base/frameworks/communication/main.bro`

Summary
~~~~~~~
Options
#######
=================================================================================== =============================================================
:bro:id:`Communication::listen_interface`: :bro:type:`addr` :bro:attr:`&redef`      Which interface to listen on.
:bro:id:`Communication::listen_ipv6`: :bro:type:`bool` :bro:attr:`&redef`           Defines if a listening socket can bind to IPv6 addresses.
:bro:id:`Communication::listen_ipv6_zone_id`: :bro:type:`string` :bro:attr:`&redef` If :bro:id:`Communication::listen_interface` is a non-global
                                                                                    IPv6 address and requires a specific :rfc:`4007` ``zone_id``,
                                                                                    it can be specified here.
:bro:id:`Communication::listen_port`: :bro:type:`port` :bro:attr:`&redef`           Which port to listen on.
:bro:id:`Communication::listen_retry`: :bro:type:`interval` :bro:attr:`&redef`      Defines the interval at which to retry binding to
                                                                                    :bro:id:`Communication::listen_interface` on
                                                                                    :bro:id:`Communication::listen_port` if it's already in use.
:bro:id:`Communication::listen_ssl`: :bro:type:`bool` :bro:attr:`&redef`            This defines if a listening socket should use SSL.
=================================================================================== =============================================================

State Variables
###############
================================================================================ ========================================================================
:bro:id:`Communication::compression_level`: :bro:type:`count` :bro:attr:`&redef` Default compression level.
:bro:id:`Communication::connected_peers`: :bro:type:`table`                      A table of peer nodes for which this node has an established connection.
:bro:id:`Communication::nodes`: :bro:type:`table` :bro:attr:`&redef`             The table of Bro or Broccoli nodes that Bro will initiate connections
                                                                                 to or respond to connections from.
:bro:id:`Communication::pending_peers`: :bro:type:`table`                        A table of peer nodes for which this node issued a
                                                                                 :bro:id:`Communication::connect_peer` call but with which a connection
                                                                                 has not yet been established or with which a connection has been
                                                                                 closed and is currently in the process of retrying to establish.
================================================================================ ========================================================================

Types
#####
=================================================== ====================================================================
:bro:type:`Communication::Info`: :bro:type:`record` A record type containing the column fields of the communication log.
:bro:type:`Communication::Node`: :bro:type:`record` A remote peer to which we would like to talk.
=================================================== ====================================================================

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

Functions
#########
=========================================================== ===============================================================
:bro:id:`Communication::connect_peer`: :bro:type:`function` Connect to a node in :bro:id:`Communication::nodes` independent
                                                            of its "connect" flag.
=========================================================== ===============================================================


Detailed Interface
~~~~~~~~~~~~~~~~~~
Options
#######
.. bro:id:: Communication::listen_interface

   :Type: :bro:type:`addr`
   :Attributes: :bro:attr:`&redef`
   :Default: ``0.0.0.0``

   Which interface to listen on. The addresses ``0.0.0.0`` and ``[::]``
   are wildcards.

.. bro:id:: Communication::listen_ipv6

   :Type: :bro:type:`bool`
   :Attributes: :bro:attr:`&redef`
   :Default: ``F``

   Defines if a listening socket can bind to IPv6 addresses.
   
   Note that this is overridden by the BroControl IPv6Comm option.

.. bro:id:: Communication::listen_ipv6_zone_id

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

   If :bro:id:`Communication::listen_interface` is a non-global
   IPv6 address and requires a specific :rfc:`4007` ``zone_id``,
   it can be specified here.

.. bro:id:: Communication::listen_port

   :Type: :bro:type:`port`
   :Attributes: :bro:attr:`&redef`
   :Default: ``47757/tcp``

   Which port to listen on.  Note that BroControl sets this
   automatically.

.. bro:id:: Communication::listen_retry

   :Type: :bro:type:`interval`
   :Attributes: :bro:attr:`&redef`
   :Default: ``30.0 secs``

   Defines the interval at which to retry binding to
   :bro:id:`Communication::listen_interface` on
   :bro:id:`Communication::listen_port` if it's already in use.

.. bro:id:: Communication::listen_ssl

   :Type: :bro:type:`bool`
   :Attributes: :bro:attr:`&redef`
   :Default: ``F``

   This defines if a listening socket should use SSL.

State Variables
###############
.. bro:id:: Communication::compression_level

   :Type: :bro:type:`count`
   :Attributes: :bro:attr:`&redef`
   :Default: ``0``

   Default compression level.  Compression level is 0-9, with 0 = no
   compression.

.. bro:id:: Communication::connected_peers

   :Type: :bro:type:`table` [:bro:type:`peer_id`] of :bro:type:`Communication::Node`
   :Default: ``{}``

   A table of peer nodes for which this node has an established connection.
   Peers are automatically removed if their connection is closed and
   automatically added back if a connection is re-established later.

.. bro:id:: Communication::nodes

   :Type: :bro:type:`table` [:bro:type:`string`] of :bro:type:`Communication::Node`
   :Attributes: :bro:attr:`&redef`
   :Default: ``{}``

   The table of Bro or Broccoli nodes that Bro will initiate connections
   to or respond to connections from.  Note that BroControl sets this
   automatically.

.. bro:id:: Communication::pending_peers

   :Type: :bro:type:`table` [:bro:type:`peer_id`] of :bro:type:`Communication::Node`
   :Default: ``{}``

   A table of peer nodes for which this node issued a
   :bro:id:`Communication::connect_peer` call but with which a connection
   has not yet been established or with which a connection has been
   closed and is currently in the process of retrying to establish.
   When a connection is successfully established, the peer is removed
   from the table.

Types
#####
.. bro:type:: Communication::Info

   :Type: :bro:type:`record`

      ts: :bro:type:`time` :bro:attr:`&log`
         The network time at which a communication event occurred.

      peer: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
         The peer name (if any) with which a communication event is
         concerned.

      src_name: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
         Where the communication event message originated from, that
         is, either from the scripting layer or inside the Bro process.

      connected_peer_desc: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
         .. todo:: currently unused.

      connected_peer_addr: :bro:type:`addr` :bro:attr:`&log` :bro:attr:`&optional`
         .. todo:: currently unused.

      connected_peer_port: :bro:type:`port` :bro:attr:`&log` :bro:attr:`&optional`
         .. todo:: currently unused.

      level: :bro:type:`string` :bro:attr:`&log` :bro:attr:`&optional`
         The severity of the communication event message.

      message: :bro:type:`string` :bro:attr:`&log`
         A message describing the communication event between Bro or
         Broccoli instances.

   A record type containing the column fields of the communication log.

.. bro:type:: Communication::Node

   :Type: :bro:type:`record`

      host: :bro:type:`addr`
         Remote address.

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

      p: :bro:type:`port` :bro:attr:`&optional`
         Port of the remote Bro communication endpoint if we are
         initiating the connection (based on the *connect* field).

      class: :bro:type:`string` :bro:attr:`&optional`
         When accepting a connection, the configuration only
         applies if the class matches the one transmitted by
         the peer.
         
         When initiating a connection, the class is sent to
         the other side.

      events: :bro:type:`pattern` :bro:attr:`&optional`
         Events requested from remote side.

      connect: :bro:type:`bool` :bro:attr:`&default` = ``F`` :bro:attr:`&optional`
         Whether we are going to connect (rather than waiting
         for the other side to connect to us).

      retry: :bro:type:`interval` :bro:attr:`&default` = ``0 secs`` :bro:attr:`&optional`
         If disconnected, reconnect after this many seconds.

      accept_input: :bro:type:`bool` :bro:attr:`&default` = ``T`` :bro:attr:`&optional`
         Whether to accept remote events.

      sync: :bro:type:`bool` :bro:attr:`&default` = ``F`` :bro:attr:`&optional`
         Whether to perform state synchronization with peer.

      request_logs: :bro:type:`bool` :bro:attr:`&default` = ``F`` :bro:attr:`&optional`
         Whether to request logs from the peer.

      auth: :bro:type:`bool` :bro:attr:`&default` = ``F`` :bro:attr:`&optional`
         When performing state synchronization, whether we consider
         our state to be authoritative (only one side can be
         authoritative).  If so, we will send the peer our current
         set when the connection is set up.

      capture_filter: :bro:type:`string` :bro:attr:`&optional`
         If not set, no capture filter is sent.
         If set to an empty string, then the default capture filter
         is sent.

      ssl: :bro:type:`bool` :bro:attr:`&default` = ``F`` :bro:attr:`&optional`
         Whether to use SSL-based communication.

      compression: :bro:type:`count` :bro:attr:`&default` = :bro:see:`Communication::compression_level` :bro:attr:`&optional`
         Compression level is 0-9, with 0 = no compression.

      peer: :bro:type:`event_peer` :bro:attr:`&optional`
         The remote peer.

      connected: :bro:type:`bool` :bro:attr:`&default` = ``F`` :bro:attr:`&optional`
         Indicates the status of the node.

   A remote peer to which we would like to talk.
   If there's no entry for a peer, it may still connect
   and request state, but not send us any.

Functions
#########
.. bro:id:: Communication::connect_peer

   :Type: :bro:type:`function` (peer: :bro:type:`string`) : :bro:type:`void`

   Connect to a node in :bro:id:`Communication::nodes` independent
   of its "connect" flag.
   

   :peer: the string used to index a particular node within the
        :bro:id:`Communication::nodes` table.


