Configuration¶

The configuration mechanism is based on the following principles:

• 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.
• The configuration mechanism works identically across implementation languages
• Configuration options are obtained from multiple configuration sources:
  • Configuration files
  • Environment variables
  • Commandline options (planned)
• Configuration options are organized in a tree of name-value pairs

Syntax and Semantics¶

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 maps to transport.spread.port.

Currently the following option tree is defined (uppercase option name components are placeholders, LANGUAGE refers to the implementation language):

+ qualityofservice
+-- reliability                     { UNRELIABLE, RELIABLE }
+-- ordering                        { UNORDERED, ORDERED }
+ errorhandling
+-- onhandlererror                  { LOG, PRINT, EXIT }
+ plugins
+-- LANGUAGE
+---- path                          list of strings
+---- load                          list of strings
+ transport
+-- NAME
+---- enabled                       bool
+---- TRANSPORT_SPECIFIC_OPTION     ?
+---- converter
+------ LANGUAGE
+-------- WIRE-SCHEMA               string
+-- spread
+---- host                          string
+---- port                          uint
+-- inprocess

Processing Order¶

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. Config file ${HOME}/.config/rsb.conf
2. Config file $(pwd)/rsb.conf
3. Environment variables

Example and test case¶

Consider the following situation:

• Contents of ${HOME}/.config/rsb.conf:
  

  [transport.spread]
  host = azurit
  port = 5301
  

• Contents of (pwd)/rsb.conf
  

  [transport.spread]
  host = localhost
  

• Environment Variables
  RSB_TRANSPORT_SPREAD_PORT='4444'

This would result in the following effective option values:

• transport.spread.host = localhost
• transport.spread.port = 4444

Sources¶

The following sections briefly explains 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

Here is an example:

[qualityofservice]
reliability = UNRELIABLE
ordering = UNORDERED

[errorhandling]
onhandlererror = LOG

[transport.spread]
host    = localhost
port    = 4803
enabled = 1                          # this is the default

[spread.converter.cpp]
image = IplImage                     # wire-schema = data-type

[transport.inprocess]
foo     = barbar
factor  = 1.5
enabled = 1

[plugins.cpp]
path = /vol/vampire/lib:/vol/cor/lib
load = rsbspread:rsbvampire     # no filetype suffix

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

Examples:

• RSB_PLUGINS_CPP_LOAD <-> plugins.cpp.load
• RSB_TRANSPORT_SPREAD_PORT <-> transport.spread.port

Commandline Options¶

This section is a proposal.

Commandline options are processed according to the following rules:

1. Language-specific name components (such as plugins.cpp.load) are dropped
2. Components are joined with/strings are split at - characters

Examples:

• --plugins-load <-> plugins.cpp.load
• --transport-spread-port <-> transport.spread.port