The configuration mechanism in RSB is based on the following principles:

  • The configuration mechanism works identically across implementation languages
  • We cannot (and do not want to) handle configuration of individual participants:
    • The configuration mechanism is intended to provide process-wide defaults.
    • Participants that require individual configurations have to be configured programmatically.
  • Configuration options are obtained from multiple configuration sources:

Name-value Pairs

See also

Specification of inprocess Transport
Options accepted by the inprocess transport.
Specification of Spread-based Transport
Options accepted by the Spread transport.
Specification of TCP-socket-based Transport
Options accepted by the TCP-socket-based transport.
Specification of TCP+YARP Transport
Options accepted by TCP+YARP transport.
Specification of YARP Transport
Options accepted by YARP transport.
Specification of TCP+ROS Transport
Options accepted by TCP+ROS transport.
Specification of ROS Transport
Options accepted by ROS transport.

Option names consist of multiple components which are specified in configuration-source-dependent syntax. For example, in configuration files section names like [transport.spread] are concatenated with names of contained options like port to obtain transport.spread.port. For environment variables, the name RSB_TRANSPORT_SPREAD_PORT is mapped to transport.spread.port.

Currently the following option tree is defined (uppercase option name components are placeholders, LANGUAGE refers to the implementation language, e.g. cpp, java, etc.)

Name                                Type                      Comment
----                                ----                      -------

+ qualityofservice
+-- reliability                     { UNRELIABLE, RELIABLE }
+-- ordering                        { UNORDERED, ORDERED }

+ errorhandling
+-- onhandlererror                  { LOG, PRINT, EXIT }

+ introspection
+-- enabled                         bool
+-- displayname                     string

+ plugins
+---- path                          list of strings
+---- load                          list of strings

+ transport

+-- NAME                                                     #
+---- enabled                       bool                      #
+---- TRANSPORT_SPECIFIC_OPTION ?                         # Subtree is valid
+---- converter                                               # for all transports
+------ LANGUAGE                                             #
+-------- WIRE-SCHEMA              string                    #

Effective Configuration

Configuration sources are processed in the following order such that options from sources which are processed later take precedence over options from sources which are processed earlier:

  1. Start with Global Defaults
  2. Merge with Config Files (“Merge 3”), being the result of:
    1. Start with System Config file PREFIX/etc/rsb.conf
    2. Merge with User Config file ~/.config/rsb.conf (“Merge 1”)
    3. Merge with Current Directory Config file $(pwd)/rsb.conf (“Merge 2”)
  3. Merge with options supplied via environment variables (“Merge 4”)
  4. Merge with programatically supplied options (“Merge 6”)

digraph configuration_processing {
node [fontsize=11,fontname=Arial]
edge [fontsize=11,fontname=Arial]

node [shape = box]

subgraph cluster_global_defaults {
  label = "Global Defaults"

  global_transports [label="options"]

subgraph cluster_config_files {
  label = "Config Files"

  system_config [label="System Config\ne.g. /etc/rsb.conf"]
  user_config [label="User Config\ne.g. $HOME/.config/rsb.conf"]
  pwd_config [label="Current Dir. Config\ne.g. $(pwd)/rsb.conf"]

  subgraph cluster_config_merge_1 {
    label = "Merge 1"
    style = "rounded,filled"

    config_1_options [label = "options", fillcolor = "white", style="filled"]

  system_config -> config_1_options [style="dashed"]
  user_config -> config_1_options

  subgraph cluster_config_merge_2 {
    label = "Merge 2"
    style = "rounded,filled"

    config_2_options [label = "options", fillcolor = "white", style="filled"]

  config_1_options -> config_2_options [style="dashed"]
  pwd_config -> config_2_options

  config_2_options [label="options"]
  /* config_transports [label="options"] */

  /* config_2_options -> config_transports */

subgraph cluster_step_3 {
  label = "Merge 3"
  style = "rounded,filled"

  step_3_options [label = "options", fillcolor = "white", style="filled"]

global_transports -> step_3_options [style="dashed"]
config_2_options -> step_3_options

subgraph cluster_environment_variables_options {
  label = "Environment Variables"

  environment_options [label="options"]

subgraph cluster_step_4 {
  label = "Merge 4"
  style = "rounded,filled"

  step_4_options [label = "options", fillcolor = "white", style="filled"]

step_3_options -> step_4_options [style="dashed"]
environment_options -> step_4_options

/* subgraph cluster_commandline_options {
  label = "Commandline"

  commandline_options [label="options"]

subgraph cluster_step_5 {
  label = "Merge 5"
  style = "rounded,filled"

  step_5_options [label = "options", fillcolor = "white", style="filled"]

step_4_options -> step_5_options [style="dashed"]
commandline_options -> step_5_options */

subgraph cluster_programmatic_options {
  label = "Programmatic Options"

  programmatic_options [label="options"]

subgraph cluster_step_6 {
  label = "Merge 6"
  style = "rounded,filled"

  step_6_options [label = "options", fillcolor = "white", style="filled"]

step_4_options -> step_6_options [style="dashed"]
programmatic_options -> step_6_options

/* subgraph cluster_uri {
  label = "URI"

  uri_schema [label="schema"]

  uri_transports [label=transports]

  uri_schema -> uri_transports

subgraph cluster_step_7 {
  label = "Merge 7"
  style = "rounded,filled"

  step_7_options [label = "options", fillcolor = "white", style="filled"]

step_6_options -> step_7_options [style="dashed"]
uri_transports -> step_7_options */

Computation of effective transport configuration. In merges, solid arrows indicate precedence over dashed arrows.


On Windows the configuration file is located at %userprofile%\.config\rsb.conf.


The following sections briefly explain the currently defined configuration sources.

Configuration Files

Configuration files use the following syntax, which is similar to INI-files or desktop-files

  • Comments are initiated by the # character and extend to the end of the current line
  • After removing comments, all lines have to be of one of the following forms:
    • empty
    • [NAME] where NAME consists of alphanumeric characters and colons
    • NAME = VALUE where NAME consists of alphanumeric characters
    • Double quotes (") can be used in NAME to avoid splitting at . characters. E.g [transport.""] would interpreted as the section name (transport,

Here is an example:

reliability = UNRELIABLE
ordering = UNORDERED

onhandlererror = LOG

host    = localhost
port    = 4803
enabled = 1                          # this is the default

image = IplImage                     # wire-schema = data-type

foo     = barbar
factor  = 1.5
enabled = 1

path = /vol/vampire/lib:/vol/cor/lib
load = rsbspread:rsbvampire     # no filetype suffix

Please note that only files with the platform’s respective line endings are supported (i.e. \n on Linux and \r\n on Windows).

Environment Variables

Environment variables are processed according to the following rules:

  1. Variables whose names start with RSB_ are processed
  2. The RSB_ prefix is stripped form the name
  3. To obtain the name of the corresponding option, the remainder of the name is converted to lower case and split at _ characters


Programmatic Options

Please have a look at the API documentation for ParticipantConfig (C++, Python) or Properties (Java). Links to the API documentation can be found in the left sidebar.

Example and Test Case

Consider the following situation:

  • Contents of ~/.config/rsb.conf

    host = azurit
    port = 5301
  • Contents of $(pwd)/rsb.conf

    host = localhost
  • Environment Variables


This should result in the following effective option values:

  • = localhost
  • transport.spread.port = 4444


Language File(s)
C++ “0.12” branch of at src/rsb/
Java “0.12” branch of at src/rsb/
Python /../rsb-python/rsb/
Common Lisp /../rsb-cl/src/configuration.lisp