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.