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.
Copyright 2016, The Bro Project. Last updated on December 19, 2018. Created using Sphinx 1.8.2.