base/frameworks/communication/main.bro

Communication

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

Namespace:Communication
Imports:base/frameworks/packet-filter, base/utils/addrs.bro
Source File:/scripts/base/frameworks/communication/main.bro

Summary

Options

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

State Variables

Communication::compression_level: count &redef Default compression level.
Communication::connected_peers: table A table of peer nodes for which this node has an established connection.
Communication::nodes: table &redef The table of Bro or Broccoli nodes that Bro will initiate connections to or respond to connections from.
Communication::pending_peers: table A table of peer nodes for which this node issued a 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

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

Redefinitions

Log::ID: enum The communication logging stream identifier.

Functions

Communication::connect_peer: function Connect to a node in Communication::nodes independent of its “connect” flag.

Detailed Interface

Options

Communication::listen_interface
Type:addr
Attributes:&redef
Default:0.0.0.0

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

Communication::listen_ipv6
Type:bool
Attributes:&redef
Default:F

Defines if a listening socket can bind to IPv6 addresses.

Note that this is overridden by the BroControl IPv6Comm option.

Communication::listen_ipv6_zone_id
Type:string
Attributes:&redef
Default:""

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

Communication::listen_port
Type:port
Attributes:&redef
Default:47757/tcp

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

Communication::listen_retry
Type:interval
Attributes:&redef
Default:30.0 secs

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

Communication::listen_ssl
Type:bool
Attributes:&redef
Default:F

This defines if a listening socket should use SSL.

State Variables

Communication::compression_level
Type:count
Attributes:&redef
Default:0

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

Communication::connected_peers
Type:table [peer_id] of 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.

Communication::nodes
Type:table [string] of Communication::Node
Attributes:&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.

Communication::pending_peers
Type:table [peer_id] of Communication::Node
Default:{}

A table of peer nodes for which this node issued a 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

Communication::Info
Type:

record

ts: time &log

The network time at which a communication event occurred.

peer: string &log &optional

The peer name (if any) with which a communication event is concerned.

src_name: string &log &optional

Where the communication event message originated from, that is, either from the scripting layer or inside the Bro process.

connected_peer_desc: string &log &optional

Todo

currently unused.

connected_peer_addr: addr &log &optional

Todo

currently unused.

connected_peer_port: port &log &optional

Todo

currently unused.

level: string &log &optional

The severity of the communication event message.

message: string &log

A message describing the communication event between Bro or Broccoli instances.

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

Communication::Node
Type:

record

host: addr

Remote address.

zone_id: string &optional

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

p: port &optional

Port of the remote Bro communication endpoint if we are initiating the connection (based on the connect field).

class: string &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: pattern &optional

Events requested from remote side.

connect: bool &default = F &optional

Whether we are going to connect (rather than waiting for the other side to connect to us).

retry: interval &default = 0 secs &optional

If disconnected, reconnect after this many seconds.

accept_input: bool &default = T &optional

Whether to accept remote events.

sync: bool &default = F &optional

Whether to perform state synchronization with peer.

request_logs: bool &default = F &optional

Whether to request logs from the peer.

auth: bool &default = F &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: string &optional

If not set, no capture filter is sent. If set to an empty string, then the default capture filter is sent.

ssl: bool &default = F &optional

Whether to use SSL-based communication.

compression: count &default = Communication::compression_level &optional

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

peer: event_peer &optional

The remote peer.

connected: bool &default = F &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

Communication::connect_peer
Type:function (peer: string) : void

Connect to a node in Communication::nodes independent of its “connect” flag.

Peer:the string used to index a particular node within the Communication::nodes table.
Copyright 2016, The Bro Project. Last updated on December 12, 2017. Created using Sphinx 1.5.2.