Various data structure definitions for use with Bro’s communication system.
Namespaces: | Broker, Log |
---|---|
Imports: | base/bif/comm.bif.bro, base/bif/messaging.bif.bro |
Source File: | /scripts/base/frameworks/broker/main.bro |
Broker::endpoint_name: string &redef | A name used to identify this endpoint to peers. |
Broker::Data: record | Opaque communication data. |
Broker::DataVector: vector | Opaque communication data. |
Broker::EndpointFlags: record | Change communication behavior. |
Broker::EventArgs: record | Opaque event communication data. |
Broker::SendFlags: record | Fine-grained tuning of communication behavior for a particular message. |
Broker::TableItem: record | Opaque communication data used as a convenient way to wrap key-value pairs that comprise table entries. |
Log::ID: enum | Type that defines an ID unique to each log stream. |
Broker::auto_event: function | Automatically send an event to any interested peers whenever it is locally dispatched (e.g. |
Broker::auto_event_stop: function | Stop automatically sending an event to peers upon local dispatch. |
Broker::connect: function | Initiate a remote connection. |
Broker::disable_remote_logs: function | Disable remote logs for a given log stream. |
Broker::disconnect: function | Remove a remote connection. |
Broker::enable: function | Enable use of communication. |
Broker::enable_remote_logs: function | Enable remote logs for a given log stream. |
Broker::listen: function | Listen for remote connections. |
Broker::publish_topic: function | Allow sending messages to peers if associated with the given topic. |
Broker::remote_logs_enabled: function | Check if remote logs are enabled for a given log stream. |
Broker::send_event: function | Send an event to any interested peers. |
Broker::send_print: function | Print a simple message to any interested peers. |
Broker::set_endpoint_flags: function | Changes endpoint flags originally supplied to Broker::enable. |
Broker::subscribe_to_events: function | Register interest in all peer event messages that use a certain topic prefix. |
Broker::subscribe_to_logs: function | Register interest in all peer log messages that use a certain topic prefix. |
Broker::subscribe_to_prints: function | Register interest in all peer print messages that use a certain topic prefix. |
Broker::unpublish_topic: function | Disallow sending messages to peers if associated with the given topic. |
Broker::unsubscribe_to_events: function | Unregister interest in all peer event messages that use a topic prefix. |
Broker::unsubscribe_to_logs: function | Unregister interest in all peer log messages that use a topic prefix. |
Broker::unsubscribe_to_prints: function | Unregister interest in all peer print messages that use a topic prefix. |
Type : | string |
---|---|
Attributes : | &redef |
Default : | "" |
A name used to identify this endpoint to peers.
See also: Broker::connect, Broker::listen
Type : | vector of Broker::Data |
---|
Opaque communication data.
Type : |
|
---|
Change communication behavior.
Type : |
|
---|
Opaque event communication data.
Type : |
|
---|
Fine-grained tuning of communication behavior for a particular message.
Type : |
key: Broker::Data val: Broker::Data |
---|
Opaque communication data used as a convenient way to wrap key-value pairs that comprise table entries.
Type : |
|
---|
Type that defines an ID unique to each log stream. Scripts creating new log streams need to redef this enum to add their own specific log ID. The log ID implicitly determines the default name of the generated log file.
Type : | function (topic: string, ev: any, flags: Broker::SendFlags &default = [self=F, peers=T, unsolicited=F] &optional) : bool |
---|
Automatically send an event to any interested peers whenever it is locally dispatched (e.g. 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. |
Flags : | tune the behavior of how the message is sent. |
Returns : | true if automatic event sending is now enabled. |
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_event. |
---|---|
Ev : | an event originally given to Broker::auto_event. |
Returns : | true if automatic events will not occur for the topic/event pair. |
Type : | function (a: string, p: port, retry: interval) : 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. |
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::outgoing_connection_established
Type : | function (id: Log::ID) : bool |
---|
Disable remote logs for a given log stream.
Id : | the log stream to disable remote logs for. |
---|---|
Returns : | true if remote logs are disabled for the stream. |
Type : | function (a: string, p: port) : bool |
---|
Remove a remote connection.
A : | the address used in previous successful call to Broker::connect. |
---|---|
P : | the port used in previous successful call to Broker::connect. |
Returns : | true if the arguments match a previously successful call to Broker::connect. |
Type : | function (flags: Broker::EndpointFlags &default = [auto_publish=T, auto_advertise=T] &optional) : bool |
---|
Enable use of communication.
Flags : | used to tune the local Broker endpoint behavior. |
---|---|
Returns : | true if communication is successfully initialized. |
Type : | function (id: Log::ID, flags: Broker::SendFlags &default = [self=F, peers=T, unsolicited=F] &optional) : bool |
---|
Enable remote logs for a given log stream.
Id : | the log stream to enable remote logs for. |
---|---|
Flags : | tune the behavior of how log entry messages are sent. |
Returns : | true if remote logs are enabled for the stream. |
Type : | function (p: port, a: string &default = "" &optional, reuse: bool &default = T &optional) : bool |
---|
Listen for remote connections.
P : | the TCP port to listen on. |
---|---|
A : | an address string on which to accept connections, e.g. “127.0.0.1”. An empty string refers to @p INADDR_ANY. |
Reuse : | equivalent to behavior of SO_REUSEADDR. |
Returns : | true if the local endpoint is now listening for connections. |
See also: Broker::incoming_connection_established
Type : | function (topic: string) : bool |
---|
Allow sending messages to peers if associated with the given topic. This has no effect if auto publication behavior is enabled via the flags supplied to Broker::enable or Broker::set_endpoint_flags.
Topic : | a topic to allow messages to be published under. |
---|---|
Returns : | true if successful. |
Type : | function (id: Log::ID) : bool |
---|
Check if remote logs are enabled for a given log stream.
Id : | the log stream to check. |
---|---|
Returns : | true if remote logs are enabled for the given stream. |
Type : | function (topic: string, args: Broker::EventArgs, flags: Broker::SendFlags &default = [self=F, peers=T, unsolicited=F] &optional) : bool |
---|
Send an event to any interested peers.
Topic : | a topic associated with the event message. |
---|---|
Args : | event arguments as made by Broker::event_args. |
Flags : | tune the behavior of how the message is sent. |
Returns : | true if the message is sent. |
Type : | function (topic: string, msg: string, flags: Broker::SendFlags &default = [self=F, peers=T, unsolicited=F] &optional) : bool |
---|
Print a simple message to any interested peers. The receiver can use Broker::print_handler to handle messages.
Topic : | a topic associated with the printed message. |
---|---|
Msg : | the print message to send to peers. |
Flags : | tune the behavior of how the message is sent. |
Returns : | true if the message is sent. |
Type : | function (flags: Broker::EndpointFlags &default = [auto_publish=T, auto_advertise=T] &optional) : bool |
---|
Changes endpoint flags originally supplied to Broker::enable.
Flags : | the new endpoint behavior flags to use. |
---|---|
Returns : | true if flags were changed. |
Type : | function (topic_prefix: string) : bool |
---|
Register interest in all peer event messages that use a certain topic prefix.
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. |
Type : | function (topic_prefix: string) : bool |
---|
Register interest in all peer log messages that use a certain topic prefix. Logs are implicitly sent with topic “bro/log/<stream-name>” and the receiving side processes them through the logging framework as usual.
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 log subscription and it is now registered. |
Type : | function (topic_prefix: string) : bool |
---|
Register interest in all peer print messages that use a certain topic prefix. Use Broker::print_handler to handle received messages.
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 print subscription and it is now registered. |
Type : | function (topic: string) : bool |
---|
Disallow sending messages to peers if associated with the given topic. This has no effect if auto publication behavior is enabled via the flags supplied to Broker::enable or Broker::set_endpoint_flags.
Topic : | a topic to disallow messages to be published under. |
---|---|
Returns : | true if successful. |
Type : | function (topic_prefix: string) : bool |
---|
Unregister interest in all peer event messages that use a topic prefix.
Topic_prefix : | a prefix previously supplied to a successful call to Broker::subscribe_to_events. |
---|---|
Returns : | true if interest in the topic prefix is no longer advertised. |
Type : | function (topic_prefix: string) : bool |
---|
Unregister interest in all peer log messages that use a topic prefix. Logs are implicitly sent with topic “bro/log/<stream-name>” and the receiving side processes them through the logging framework as usual.
Topic_prefix : | a prefix previously supplied to a successful call to Broker::subscribe_to_logs. |
---|---|
Returns : | true if interest in the topic prefix is no longer advertised. |
Type : | function (topic_prefix: string) : bool |
---|
Unregister interest in all peer print messages that use a topic prefix.
Topic_prefix : | a prefix previously supplied to a successful call to Broker::subscribe_to_prints. |
---|---|
Returns : | true if interest in the topic prefix is no longer advertised. |