Configuration » History » Version 12
J. Wienke, 01/13/2012 01:51 PM
1 | 1 | J. Moringen | h1. Configuration |
---|---|---|---|
2 | 1 | J. Moringen | |
3 | 11 | J. Moringen | {{>toc}} |
4 | 11 | J. Moringen | |
5 | 1 | J. Moringen | The configuration mechanism is based on the following principles: |
6 | 2 | J. Moringen | * 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. |
7 | 1 | J. Moringen | * The configuration mechanism works identically across implementation languages |
8 | 1 | J. Moringen | * Configuration options are obtained from multiple configuration sources: |
9 | 1 | J. Moringen | ** Configuration files |
10 | 1 | J. Moringen | ** Environment variables |
11 | 1 | J. Moringen | ** _Commandline options (planned)_ |
12 | 1 | J. Moringen | * Configuration options are organized in a tree of name-value pairs |
13 | 1 | J. Moringen | |
14 | 1 | J. Moringen | h2. Syntax and Semantics |
15 | 1 | J. Moringen | |
16 | 1 | J. Moringen | 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@. |
17 | 1 | J. Moringen | |
18 | 8 | J. Moringen | Currently the following option tree is defined (uppercase option name components are placeholders, LANGUAGE refers to the implementation language): |
19 | 1 | J. Moringen | <pre> |
20 | 1 | J. Moringen | + qualityofservice |
21 | 1 | J. Moringen | +-- reliability { UNRELIABLE, RELIABLE } |
22 | 1 | J. Moringen | +-- ordering { UNORDERED, ORDERED } |
23 | 1 | J. Moringen | + errorhandling |
24 | 1 | J. Moringen | +-- onhandlererror { LOG, PRINT, EXIT } |
25 | 7 | J. Moringen | + plugins |
26 | 7 | J. Moringen | +-- LANGUAGE |
27 | 7 | J. Moringen | +---- path list of strings |
28 | 7 | J. Moringen | +---- load list of strings |
29 | 1 | J. Moringen | + transport |
30 | 1 | J. Moringen | +-- NAME |
31 | 1 | J. Moringen | +---- enabled bool |
32 | 1 | J. Moringen | +---- TRANSPORT_SPECIFIC_OPTION ? |
33 | 1 | J. Moringen | +---- converter |
34 | 7 | J. Moringen | +------ LANGUAGE |
35 | 7 | J. Moringen | +-------- WIRE-SCHEMA string |
36 | 1 | J. Moringen | +-- spread |
37 | 1 | J. Moringen | +---- host string |
38 | 1 | J. Moringen | +---- port uint |
39 | 10 | J. Moringen | +---- maxfragmentsize uint |
40 | 10 | J. Moringen | +---- tcpnodelay boolean |
41 | 1 | J. Moringen | +-- inprocess |
42 | 1 | J. Moringen | </pre> |
43 | 1 | J. Moringen | |
44 | 1 | J. Moringen | h2. Processing Order |
45 | 1 | J. Moringen | |
46 | 1 | J. Moringen | 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: |
47 | 1 | J. Moringen | # Config file @${HOME}/.config/rsb.conf@ |
48 | 1 | J. Moringen | # Config file @$(pwd)/rsb.conf@ |
49 | 1 | J. Moringen | # Environment variables |
50 | 1 | J. Moringen | |
51 | 1 | J. Moringen | h3. Example and test case |
52 | 1 | J. Moringen | |
53 | 1 | J. Moringen | Consider the following situation: |
54 | 1 | J. Moringen | * Contents of @${HOME}/.config/rsb.conf@: |
55 | 1 | J. Moringen | <pre> |
56 | 1 | J. Moringen | [transport.spread] |
57 | 1 | J. Moringen | host = azurit |
58 | 5 | J. Moringen | port = 5301 |
59 | 1 | J. Moringen | </pre> |
60 | 1 | J. Moringen | * Contents of @(pwd)/rsb.conf@ |
61 | 1 | J. Moringen | <pre> |
62 | 1 | J. Moringen | [transport.spread] |
63 | 1 | J. Moringen | host = localhost |
64 | 1 | J. Moringen | </pre> |
65 | 1 | J. Moringen | * Environment Variables |
66 | 5 | J. Moringen | @RSB_TRANSPORT_SPREAD_PORT='4444'@ |
67 | 1 | J. Moringen | |
68 | 1 | J. Moringen | This would result in the following effective option values: |
69 | 1 | J. Moringen | * @transport.spread.host = localhost@ |
70 | 1 | J. Moringen | * @transport.spread.port = 4444@ |
71 | 1 | J. Moringen | |
72 | 1 | J. Moringen | h2. Sources |
73 | 1 | J. Moringen | |
74 | 1 | J. Moringen | The following sections briefly explains the currently defined configuration sources. |
75 | 1 | J. Moringen | |
76 | 1 | J. Moringen | h3. Configuration Files |
77 | 1 | J. Moringen | |
78 | 8 | J. Moringen | Configuration files use the following syntax, which is similar to "INI-files":http://en.wikipedia.org/wiki/INI_file or "desktop-files":http://standards.freedesktop.org/desktop-entry-spec/latest/: |
79 | 1 | J. Moringen | * Comments are initiated by the @#@ character and extend to the end of the current line |
80 | 1 | J. Moringen | * After removing comments, all lines have to be of one of the following forms: |
81 | 1 | J. Moringen | ** empty |
82 | 1 | J. Moringen | ** @[NAME]@ where @NAME@ consists of alphanumeric characters and colons |
83 | 1 | J. Moringen | ** @NAME = VALUE@ where @NAME@ consists of alphanumeric characters |
84 | 1 | J. Moringen | |
85 | 1 | J. Moringen | Here is an example: |
86 | 1 | J. Moringen | <pre> |
87 | 1 | J. Moringen | [qualityofservice] |
88 | 1 | J. Moringen | reliability = UNRELIABLE |
89 | 1 | J. Moringen | ordering = UNORDERED |
90 | 1 | J. Moringen | |
91 | 1 | J. Moringen | [errorhandling] |
92 | 1 | J. Moringen | onhandlererror = LOG |
93 | 1 | J. Moringen | |
94 | 1 | J. Moringen | [transport.spread] |
95 | 1 | J. Moringen | host = localhost |
96 | 4 | S. Wrede | port = 4803 |
97 | 4 | S. Wrede | enabled = 1 # this is the default |
98 | 1 | J. Moringen | |
99 | 6 | J. Moringen | [spread.converter.cpp] |
100 | 9 | J. Moringen | image = IplImage # wire-schema = data-type |
101 | 1 | J. Moringen | |
102 | 1 | J. Moringen | [transport.inprocess] |
103 | 4 | S. Wrede | foo = barbar |
104 | 4 | S. Wrede | factor = 1.5 |
105 | 3 | S. Wrede | enabled = 1 |
106 | 1 | J. Moringen | |
107 | 6 | J. Moringen | [plugins.cpp] |
108 | 3 | S. Wrede | path = /vol/vampire/lib:/vol/cor/lib |
109 | 7 | J. Moringen | load = rsbspread:rsbvampire # no filetype suffix |
110 | 1 | J. Moringen | </pre> |
111 | 1 | J. Moringen | |
112 | 12 | J. Wienke | Please note that only files with the platform's respective line endings are supported (i.e. \n on linux and \r\n on windows). |
113 | 12 | J. Wienke | |
114 | 1 | J. Moringen | h3. Environment Variables |
115 | 1 | J. Moringen | |
116 | 9 | J. Moringen | Environment variables are processed according to the following rules: |
117 | 1 | J. Moringen | # Variables whose names start with @RSB_@ are processed |
118 | 1 | J. Moringen | # The @RSB_@ prefix is stripped form the name |
119 | 1 | J. Moringen | # To obtain the name of the corresponding option, the remainder of the name is converted to lower case and split at @_@ characters |
120 | 1 | J. Moringen | |
121 | 9 | J. Moringen | Examples: |
122 | 9 | J. Moringen | * @RSB_PLUGINS_CPP_LOAD <-> plugins.cpp.load@ |
123 | 9 | J. Moringen | * @RSB_TRANSPORT_SPREAD_PORT <-> transport.spread.port@ |
124 | 9 | J. Moringen | |
125 | 9 | J. Moringen | h3. Commandline Options |
126 | 9 | J. Moringen | |
127 | 9 | J. Moringen | _This section is a proposal._ |
128 | 9 | J. Moringen | |
129 | 9 | J. Moringen | Commandline options are processed according to the following rules: |
130 | 9 | J. Moringen | # Language-specific name components (such as @plugins.cpp.load@) are dropped |
131 | 9 | J. Moringen | # Components are joined with/strings are split at @-@ characters |
132 | 9 | J. Moringen | |
133 | 9 | J. Moringen | Examples: |
134 | 9 | J. Moringen | * @--plugins-load <-> plugins.cpp.load@ |
135 | 9 | J. Moringen | * @--transport-spread-port <-> transport.spread.port@ |