Configuration¶

• Configuration
  • Syntax and Semantics
  • Processing Order
    • Example and test case
  • Sources
    • Configuration Files
    • Environment Variables
    • Commandline Options

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
+---- maxfragmentsize               uint
+---- tcpnodelay                    boolean
+-- 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

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

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