Configuration¶
The configuration file is a YAML dictionary containing:
- inputs: a list of input streams
- outputs: a list of output streams
- core: configuration of the internal sockets
- reactor: the reacting part of ReactOBus
- db: the database configuration
Note
All keys except core and inputs are optional. If the optional keys are not found in the configuration, the corresponding modules won’t be loaded.
For instance, if the outputs key is not found in the configuration, the messages won’t be forwarded outside of ReactOBus.
Inputs¶
The inputs key is a list of dictionaries describing the different sources of messages.
inputs: - class: ZMQPull name: PullIn options: url: tcp://*:5554 - class: ZMQSub name: SubIn options: url: tcp://127.0.0.1:5555 encryption: self: /etc/reactobus/certs/SubIn.key_secret server: /etc/reactobus/certs/SubIn-server.key
In each dictionary, some fields are required:
- class: the name of the input class (ZMQPull or ZMQSub)
- name: the name of this input in the logs and for the name of the subprocess
- options: dictionary of options, depending on the class
ZMQPull¶
This class allows to receive messages from ZMQ PUSH sockets. The options dictionary should include:
- url: the url where to bind the socket
If the PUSH sockets are sending encrypted content, you should add the following configuration:
options:
url: tcp://*:5554
encryption:
self: /etc/reactobus/certs/PullIn.key_secret
clients: /etc/reactobus/certs/PullIn.d/
The encryption keys are both mandatory:
- self: the path to the secret certificate of this socket
- clients: the path to a directory containing the public certificates of the PUSH sockets
ZMQSub¶
This class allows to subscribe to a ZMQ PUB socket. The options are:
- url: the url of the PUB socket
For an encrypted socket, you should add:
options:
url: tcp://127.0.0.1:5555
encryption:
self: /etc/reactobus/certs/SubIn.key_secret
server: /etc/reactobus/certs/SubIn-server.key
The encryption keys are both mandatory:
- self: the private certificate of this socket
- server: the server’s public key
Core¶
The core key is mandatory and should contains two keys:
- inbound: internal incoming socket
- outbound: internal outgoing socket
core: inbound: ipc:///tmp/ReactOBus.inbound outbound: ipc:///tmp/ReactOBus.outbound
These two sockets are used internally by ReactOBus to send messages between the different stages of the pipeline. It’s import to configure these sockets correctly because two instances of ReactOBus should not use the same sockets.
Reactor¶
The reactor is the module that will execute sub-commands when a given message is received.
reactor: workers: 10 rules: - name: org.reactobus match: field: topic pattern: ^org\.reactobus\. exec: path: share/examples/react.sh timeout: 2 args: - topic - $topic - stdin:topic - stdin:$topic
The reactor configuration is made of two keys:
- workers: the number of workers that will execute the sub-commands
- rules: a list of dictionaries describing the different rules to execute
A rule describes a command to execute when a message matches the rule conditions.
A rule description is made of:
- name: the name used in the logs
- math: the matching rule as a dictionary:
- field: the field to match
- pattern: the regular expression that should match the field content
- exec: the sub-command as a dictionary:
- path: path to the binary or script to execute
- timeout: timeout for the sub-command
- args: a list of arguments for the sub-command
The available fields are:
- topic
- uuid
- datetime
- username
- data
The available arguments are build using the following algorithm:
- “topic”: won’t be changed
- “$topic”: will be replaced by the content of the corresponding field
- “$data.url”: will be replace by the content of data[“url”]
If the argument is prefixed by stdin then the content will be send to the sub-command standard input:
- “stdin:something”
- “stdin:$uuid”
- “stdin:$data.is_finished”
Database¶
This module allows to store all the received messages into a database. This database can then be exported by tools like ReactOWeb.
db: url: sqlite:///db.sqlite3
The only option is the url to the database. This url should be a valid SQLAlchemy database url.
Outputs¶
The outputs key is a list of dictionaries describing the different destinations for the messages.
outputs: - class: ZMQPub name: PublicPub options: url: tcp://*:5556 - class: ZMQPush name: PrivatePush options: url: tcp://127.0.0.1:5557 encryption: self: /etc/reactobus/certs/PrivatePush.key_secret server: /etc/reactobus/certs/PrivatePush-server.key
In each dictionary, some fields are required:
- class: the name of the output class (ZMQPush or ZMQPub)
- name: the name of this output in the logs and for the name of the subprocess
- options: dictionary of options, depending on the class
ZMQPush¶
This class allows to forward the messages to a ZMQ PULL socket. The options dictionary should include:
- url: the url of the PULL socket
In order to encrypt the messages, you should add the following configuration:
options:
url: tcp://*:5554
encryption:
self: /etc/reactobus/certs/PrivatePush.key_secret
server: /etc/reactobus/certs/PrivatePush-server.key
The encryption keys are both mandatory:
- self: the path to the secret certificate of this socket
- clients: the server’s public certificate
ZMQPub¶
This class allows to publish messages to ZMQ PUB sockets. The options are:
- url: the url of the PUB socket
For an encrypted socket, you should add:
options:
url: tcp://127.0.0.1:5555
encryption:
self: /etc/reactobus/certs/Pub.key_secret
clients: /etc/reactobus/certs/Pub.d/
The encryption keys are both mandatory:
- self: the private certificate of this socket
- clients: the path to a directory containing the public certificates of the SUB sockets