base/frameworks/broker/main.bro

Broker

The Broker-based communication API and its various options.

Namespace:Broker Imports:base/bif/comm.bif.bro, base/bif/messaging.bif.bro Source File:/scripts/base/frameworks/broker/main.bro

Summary

Redefinable Options

Broker::aggressive_interval: count &redef	Frequency of work-stealing polling attempts for Broker/CAF threads in “aggressive” mode.
Broker::aggressive_polls: count &redef	Number of work-stealing polling attempts for Broker/CAF threads in “aggressive” mode.
Broker::congestion_queue_size: count &redef	The number of buffered messages at the Broker/CAF layer after which a subscriber considers themselves congested (i.e.
Broker::default_connect_retry: interval &redef	Default interval to retry connecting to a peer if it cannot be made to work initially, or if it ever becomes disconnected.
Broker::default_listen_address: string &redef	Default address on which to listen.
Broker::default_listen_retry: interval &redef	Default interval to retry listening on a port if it’s currently in use already.
Broker::default_log_topic_prefix: string &redef	The default topic prefix where logs will be published.
Broker::default_port: port &redef	Default port for Broker communication.
Broker::disable_ssl: bool &redef	If true, do not use SSL for network connections.
Broker::forward_messages: bool &redef	Forward all received messages to subscribing peers.
Broker::max_threads: count &redef	Max number of threads to use for Broker/CAF functionality.
Broker::moderate_interval: count &redef	Frequency of work-stealing polling attempts for Broker/CAF threads in “moderate” mode.
Broker::moderate_polls: count &redef	Number of work-stealing polling attempts for Broker/CAF threads in “moderate” mode.
Broker::moderate_sleep: interval &redef	Interval of time for under-utilized Broker/CAF threads to sleep when in “moderate” mode.
Broker::relaxed_interval: count &redef	Frequency of work-stealing polling attempts for Broker/CAF threads in “relaxed” mode.
Broker::relaxed_sleep: interval &redef	Interval of time for under-utilized Broker/CAF threads to sleep when in “relaxed” mode.
Broker::ssl_cafile: string &redef	Path to a file containing concatenated trusted certificates in PEM format.
Broker::ssl_capath: string &redef	Path to an OpenSSL-style directory of trusted certificates.
Broker::ssl_certificate: string &redef	Path to a file containing a X.509 certificate for this node in PEM format.
Broker::ssl_keyfile: string &redef	Path to the file containing the private key for this node’s certificate.
Broker::ssl_passphrase: string &redef	Passphrase to decrypt the private key specified by Broker::ssl_keyfile.

Types

Broker::Data: record	Opaque communication data.
Broker::DataVector: vector	Opaque communication data sequence.
Broker::EndpointInfo: record
Broker::ErrorCode: enum	Enumerates the possible error types.
Broker::Event: record	Opaque event communication data.
Broker::NetworkInfo: record
Broker::PeerInfo: record
Broker::PeerInfos: vector
Broker::PeerStatus: enum	The possible states of a peer endpoint.
Broker::TableItem: record	Opaque communication data used as a convenient way to wrap key-value pairs that comprise table entries.

Functions

Broker::auto_publish: function	Automatically send an event to any interested peers whenever it is locally dispatched.
Broker::auto_unpublish: function	Stop automatically sending an event to peers upon local dispatch.
Broker::default_log_topic: function	The default implementation for Broker::log_topic.
Broker::flush_logs: function	Sends all pending log messages to remote peers.
Broker::forward: function	Register a topic prefix subscription for events that should only be forwarded to any subscribing peers and not raise any event handlers on the receiving/forwarding node.
Broker::listen: function	Listen for remote connections.
Broker::log_topic: function &redef	A function that will be called for each log entry to determine what broker topic string will be used for sending it to peers.
Broker::node_id: function	Get a unique identifier for the local broker endpoint.
Broker::peer: function	Initiate a remote connection.
Broker::peers: function	Get a list of all peer connections.
Broker::publish_id: function	Publishes the value of an identifier to a given topic.
Broker::subscribe: function	Register interest in all peer event messages that use a certain topic prefix.
Broker::unpeer: function	Remove a remote connection.
Broker::unsubscribe: function	Unregister interest in all peer event messages that use a topic prefix.

Detailed Interface

Redefinable Options

Broker::aggressive_interval

Type:count Attributes:&redef Default:4

Frequency of work-stealing polling attempts for Broker/CAF threads in “aggressive” mode.

Broker::aggressive_polls

Type:count Attributes:&redef Default:5

Number of work-stealing polling attempts for Broker/CAF threads in “aggressive” mode.

Broker::congestion_queue_size

Type:count Attributes:&redef Default:200

The number of buffered messages at the Broker/CAF layer after which a subscriber considers themselves congested (i.e. tune the congestion control mechanisms).

Broker::default_connect_retry

Type:interval Attributes:&redef Default:30.0 secs

Default interval to retry connecting to a peer if it cannot be made to work initially, or if it ever becomes disconnected. Use of the BRO_DEFAULT_CONNECT_RETRY environment variable (set as number of seconds) will override this option and also any values given to Broker::peer.

Broker::default_listen_address

Type:string Attributes:&redef Default:""

Default address on which to listen.

See also: Broker::listen

Broker::default_listen_retry

Type:interval Attributes:&redef Default:30.0 secs

Default interval to retry listening on a port if it’s currently in use already. Use of the BRO_DEFAULT_LISTEN_RETRY environment variable (set as a number of seconds) will override this option and also any values given to Broker::listen.

Broker::default_log_topic_prefix

Type:string Attributes:&redef Default:"bro/logs/"

The default topic prefix where logs will be published. The log’s stream id is appended when writing to a particular stream.

Broker::default_port

Type:port Attributes:&redef Default:9999/tcp

Default port for Broker communication. Where not specified otherwise, this is the port to connect to and listen on.

Broker::disable_ssl

Type:bool Attributes:&redef Default:F

If true, do not use SSL for network connections. By default, SSL will even be used if no certificates / CAs have been configured. In that case (which is the default) the communication will be encrypted, but not authenticated.

Broker::forward_messages

Type:bool Attributes:&redef Default:F

Forward all received messages to subscribing peers.

Broker::max_threads

Type:count Attributes:&redef Default:1

Max number of threads to use for Broker/CAF functionality. The BRO_BROKER_MAX_THREADS environment variable overrides this setting.

Broker::moderate_interval

Type:count Attributes:&redef Default:2

Frequency of work-stealing polling attempts for Broker/CAF threads in “moderate” mode.

Broker::moderate_polls

Type:count Attributes:&redef Default:5

Number of work-stealing polling attempts for Broker/CAF threads in “moderate” mode.

Broker::moderate_sleep

Type:interval Attributes:&redef Default:16.0 msecs

Interval of time for under-utilized Broker/CAF threads to sleep when in “moderate” mode.

Broker::relaxed_interval

Type:count Attributes:&redef Default:1

Frequency of work-stealing polling attempts for Broker/CAF threads in “relaxed” mode.

Broker::relaxed_sleep

Type:interval Attributes:&redef Default:64.0 msecs

Interval of time for under-utilized Broker/CAF threads to sleep when in “relaxed” mode.

Broker::ssl_cafile

Type:string Attributes:&redef Default:""

Path to a file containing concatenated trusted certificates in PEM format. If set, Bro will require valid certificates for all peers.

Broker::ssl_capath

Type:string Attributes:&redef Default:""

Path to an OpenSSL-style directory of trusted certificates. If set, Bro will require valid certificates for all peers.

Broker::ssl_certificate

Type:string Attributes:&redef Default:""

Path to a file containing a X.509 certificate for this node in PEM format. If set, Bro will require valid certificates for all peers.

Broker::ssl_keyfile

Type:string Attributes:&redef Default:""

Path to the file containing the private key for this node’s certificate. If set, Bro will require valid certificates for all peers.

Broker::ssl_passphrase

Type:string Attributes:&redef Default:""

Passphrase to decrypt the private key specified by Broker::ssl_keyfile. If set, Bro will require valid certificates for all peers.

Types

Broker::Data

Type:

record

data: opaque of Broker::Data &optional

Opaque communication data.

Broker::DataVector

Type:vector of Broker::Data

Opaque communication data sequence.

Broker::EndpointInfo

Type:

record

id: string

A unique identifier of the node.

network: Broker::NetworkInfo &optional

Network-level information.

Broker::ErrorCode

Type:

enum

Broker::UNSPECIFIED

The unspecified default error code.

Broker::PEER_INCOMPATIBLE

Version incompatibility.

Broker::PEER_INVALID

Referenced peer does not exist.

Broker::PEER_UNAVAILABLE

Remote peer not listening.

Broker::PEER_TIMEOUT

A peering request timed out.

Broker::MASTER_EXISTS

Master with given name already exists.

Broker::NO_SUCH_MASTER

Master with given name does not exist.

Broker::NO_SUCH_KEY

The given data store key does not exist.

Broker::REQUEST_TIMEOUT

The store operation timed out.

Broker::TYPE_CLASH

The operation expected a different type than provided.

Broker::INVALID_DATA

The data value cannot be used to carry out the desired operation.

Broker::BACKEND_FAILURE

The storage backend failed to execute the operation.

Broker::STALE_DATA

The storage backend failed to execute the operation.

Broker::CAF_ERROR

Catch-all for a CAF-level problem.

Enumerates the possible error types.

Broker::Event

Type:

record

name: string &optional

The name of the event. Not set if invalid event or arguments.

args: Broker::DataVector

The arguments to the event.

Opaque event communication data.

Broker::NetworkInfo

Type:

record

address: string &log

The IP address or hostname where the endpoint listens.

bound_port: port &log

The port where the endpoint is bound to.

Broker::PeerInfo

Type:

record

peer: Broker::EndpointInfo

status: Broker::PeerStatus

Broker::PeerInfos

Type:vector of Broker::PeerInfo

Broker::PeerStatus

Type:

enum

Broker::INITIALIZING

The peering process is initiated.

Broker::CONNECTING

Connection establishment in process.

Broker::CONNECTED

Connection established, peering pending.

Broker::PEERED

Successfully peered.

Broker::DISCONNECTED

Connection to remote peer lost.

Broker::RECONNECTING

Reconnecting to peer after a lost connection.

The possible states of a peer endpoint.

Broker::TableItem

Type:

record

key: Broker::Data

val: Broker::Data

Opaque communication data used as a convenient way to wrap key-value pairs that comprise table entries.

Functions

Broker::auto_publish

Type:function (topic: string, ev: any) : bool

Automatically send an event to any interested peers whenever it is locally dispatched. (For example, using “event my_event(…);” in a script.)

Topic:a topic string associated with the event message. Peers advertise interest by registering a subscription to some prefix of this topic name. Ev:a Bro event value. Returns:true if automatic event sending is now enabled.

Broker::auto_unpublish

Type:function (topic: string, ev: any) : bool

Stop automatically sending an event to peers upon local dispatch.

Topic:a topic originally given to Broker::auto_publish. Ev:an event originally given to Broker::auto_publish. Returns:true if automatic events will not occur for the topic/event pair.

Broker::default_log_topic

Type:function (id: Log::ID, path: string) : string

The default implementation for Broker::log_topic.

Broker::flush_logs

Type:function () : count

Sends all pending log messages to remote peers. This normally doesn’t need to be used except for test cases that are time-sensitive.

Broker::forward

Type:function (topic_prefix: string) : bool

Register a topic prefix subscription for events that should only be forwarded to any subscribing peers and not raise any event handlers on the receiving/forwarding node. i.e. it’s the same as Broker::subscribe except matching events are not raised on the receiver, just forwarded. Use Broker::unsubscribe with the same argument to undo this operation.

Topic_prefix:a prefix to match against remote message topics. e.g. an empty prefix matches everything and “a” matches “alice” and “amy” but not “bob”. Returns:true if a new event forwarding/subscription is now registered.

Broker::listen

Type:function (a: string &default = Broker::default_listen_address &optional, p: port &default = Broker::default_port &optional, retry: interval &default = Broker::default_listen_retry &optional) : port

Listen for remote connections.

A:an address string on which to accept connections, e.g. “127.0.0.1”. An empty string refers to INADDR_ANY. P:the TCP port to listen on. The value 0 means that the OS should choose the next available free port. Retry:If non-zero, retries listening in regular intervals if the port cannot be acquired immediately. 0 disables retries. If the BRO_DEFAULT_LISTEN_RETRY environment variable is set (as number of seconds), it overrides any value given here. Returns:the bound port or 0/? on failure.

See also: Broker::status

Broker::log_topic

Type:function (id: Log::ID, path: string) : string Attributes:&redef

A function that will be called for each log entry to determine what broker topic string will be used for sending it to peers. The default implementation will return a value based on Broker::default_log_topic_prefix.

Id:the ID associated with the log stream entry that will be sent. Path:the path to which the log stream entry will be output. Returns:a string representing the broker topic to which the log will be sent.

Broker::node_id

Type:function () : string

Get a unique identifier for the local broker endpoint.

Returns:a unique identifier for the local broker endpoint.

Broker::peer

Type:function (a: string, p: port &default = Broker::default_port &optional, retry: interval &default = Broker::default_connect_retry &optional) : bool

Initiate a remote connection.

A:an address to connect to, e.g. “localhost” or “127.0.0.1”. P:the TCP port on which the remote side is listening. Retry:an interval at which to retry establishing the connection with the remote peer if it cannot be made initially, or if it ever becomes disconnected. If the BRO_DEFAULT_CONNECT_RETRY environment variable is set (as number of seconds), it overrides any value given here. Returns:true if it’s possible to try connecting with the peer and it’s a new peer. The actual connection may not be established until a later point in time.

See also: Broker::status

Broker::peers

Type:function () : vector of Broker::PeerInfo

Get a list of all peer connections.

Returns:a list of all peer connections.

Broker::publish_id

Type:function (topic: string, id: string) : bool

Publishes the value of an identifier to a given topic. The subscribers will update their local value for that identifier on receipt.

Topic:a topic associated with the message. Id:the identifier to publish. Returns:true if the message is sent.

Broker::subscribe

Type:function (topic_prefix: string) : bool

Register interest in all peer event messages that use a certain topic prefix. Note that subscriptions may not be altered immediately after calling (except during bro_init).

Topic_prefix:a prefix to match against remote message topics. e.g. an empty prefix matches everything and “a” matches “alice” and “amy” but not “bob”. Returns:true if it’s a new event subscription and it is now registered.

Broker::unpeer

Type:function (a: string, p: port) : bool

Remove a remote connection.

Note that this does not terminate the connection to the peer, it just means that we won’t exchange any further information with it unless peering resumes later.

A:the address used in previous successful call to Broker::peer. P:the port used in previous successful call to Broker::peer. Returns:true if the arguments match a previously successful call to Broker::peer. TODO:We do not have a function yet to terminate a connection.

Broker::unsubscribe

Type:function (topic_prefix: string) : bool

Unregister interest in all peer event messages that use a topic prefix. Note that subscriptions may not be altered immediately after calling (except during bro_init).

Topic_prefix:a prefix previously supplied to a successful call to Broker::subscribe or Broker::forward. Returns:true if interest in the topic prefix is no longer advertised.