| 1 |
I-Scream System Configuration - initial draft |
| 2 |
============================= |
| 3 |
|
| 4 |
ajm4, 26/11/2000 |
| 5 |
|
| 6 |
This document will address all three areas of concern |
| 7 |
regarding the configuration operational parameters of the |
| 8 |
i-scream system to date. These areas being: |
| 9 |
|
| 10 |
1) Configuration Mechanisms |
| 11 |
- maintenance documentation |
| 12 |
|
| 13 |
2) Using the Configuration System |
| 14 |
- developer documentation |
| 15 |
|
| 16 |
3) Configuring the I-Scream System |
| 17 |
- user documentation |
| 18 |
|
| 19 |
Configuration Mechanisms |
| 20 |
------------------------ |
| 21 |
|
| 22 |
Configuration of the I-Scream system is predominantly |
| 23 |
carried out through the ConfigurationManager component. |
| 24 |
However there is another configuration option which should |
| 25 |
be used to an absolute minimum, yet it is necessary to |
| 26 |
explain it here as it is used! |
| 27 |
|
| 28 |
Any configuration that should be carried out before any |
| 29 |
component can initialise the ORB and obtain a reference to |
| 30 |
the ConfigurationManager should be placed in a "properties" |
| 31 |
file that is local to that component. At the time of |
| 32 |
writing the only component to require this is the CORE. This |
| 33 |
is because is requires some initialisation to get the system |
| 34 |
up and running. However, it is NOT the norm to use this |
| 35 |
method, and all elements of the system should make an effort |
| 36 |
to attach to the orb and obtain the ConfigurationManager |
| 37 |
before requiring any specific configuration. For information |
| 38 |
on what is currently contained within the |
| 39 |
"default.properties" file please refer to the user |
| 40 |
documentation. |
| 41 |
|
| 42 |
The main form of configuration mechanism is the afore |
| 43 |
mentioned ConfigurationManager. This component acts as a |
| 44 |
centralised holder for configuration for every part of the |
| 45 |
system. Components get a referance to this well known |
| 46 |
service either directly through the CORBA Naming Service |
| 47 |
(see to-be-published conventions on Naming for the I-Scream |
| 48 |
project). Or via a local proxy, in the case of a Host this |
| 49 |
is through the FilterManager, a hosts first connection to |
| 50 |
the system. This allows both CORBA aware and |
| 51 |
non-aware components to be configured through this system. |
| 52 |
The ConfigurationManager also provides support for |
| 53 |
determining if a configuration has changed and thus (if the |
| 54 |
component is programmed in such a way), support for dynamic |
| 55 |
re-loading of configuration. For information on how to use |
| 56 |
the ConfigurationManager, please see the next section on |
| 57 |
"Using the Configuration System". For information on the |
| 58 |
file format and structure, together with what is currently |
| 59 |
contained with the standard configuraton file, please refer |
| 60 |
to "Configuring the I-Scream System". |
| 61 |
|
| 62 |
|
| 63 |
Using the Configuration System |
| 64 |
------------------------------ |
| 65 |
|
| 66 |
The configuration system itself has two main components. |
| 67 |
The ConfigurationManager and the Configuration objects. |
| 68 |
It is currently envisaged that there will only ever be one |
| 69 |
instance of the ConfigurationManager registered with the ORB |
| 70 |
in use at any given time. It has the well known service |
| 71 |
name of "iscream.ConfigurationManager" which a component |
| 72 |
can used to get a reference to it. |
| 73 |
|
| 74 |
Once a component has reference to the ConfigurationManager |
| 75 |
it should then request its configuration using the |
| 76 |
getConfiguration(<name>) method. eg, |
| 77 |
|
| 78 |
Configuration myConfig = |
| 79 |
configManager.getConfiguration("FilterManager"); |
| 80 |
|
| 81 |
The above request causes the ConfigurationManager to look |
| 82 |
in the system configuration file for the property: |
| 83 |
|
| 84 |
"config.FilterManager=<config file>" |
| 85 |
|
| 86 |
It then creates a Configuration object based on the contents |
| 87 |
of <config file> using the system configuration for the |
| 88 |
defaults of any values. The ConfigurationManager also has |
| 89 |
support for including other configurations within a file. |
| 90 |
For more information on this feature please refer to the |
| 91 |
next section on "Configuring the I-Scream System". |
| 92 |
|
| 93 |
A refernce to this Configuration object is then passed back |
| 94 |
to the calling component. At which point that component can |
| 95 |
interrogate the Configuration object to obtain its |
| 96 |
configuration. It should be noted that the Configuration |
| 97 |
object uses a java.util.Properties object to store the |
| 98 |
configuration internally, so essentially Configuration acts |
| 99 |
as a CORBA wrapper for a java.util.Properties object. |
| 100 |
|
| 101 |
If the entry cannot be found, the component is returned a |
| 102 |
reference to the system configuration. This allows |
| 103 |
components to be configured without the need to a |
| 104 |
configuration file is only a small amount is needed. |
| 105 |
|
| 106 |
If there is an error at any stage of obtaining the |
| 107 |
configuration, an appropriate entry will be made in the log, |
| 108 |
but the component will be returned a NULL reference. |
| 109 |
|
| 110 |
To obtain entries from a Configuration, a component calls |
| 111 |
the getProperty(<name>) method. eg, |
| 112 |
|
| 113 |
myConfig.getProperty("FilterManager.listenPort") |
| 114 |
|
| 115 |
This will return the String value for that property. The |
| 116 |
entry in the configuration file would appear as: |
| 117 |
|
| 118 |
FilterManager.listenPort = <value> |
| 119 |
|
| 120 |
The configuration system also has support for detecting that |
| 121 |
a currently loaded configuration has been changed. It |
| 122 |
achieves this by monitoring the date stamps of the |
| 123 |
configuration files. The interface to this functionality is |
| 124 |
provided in two areas. The Configuration object has two |
| 125 |
further methods, getFileList() and getLastModified(). The |
| 126 |
first returns a ";" separated list of filenames used to |
| 127 |
obtain the configuration that was built for that instance. |
| 128 |
The second returns a long (in the programming sense) number |
| 129 |
of representing the date stamp of the most recently modified |
| 130 |
file in the list. Using these two attributes a component |
| 131 |
can ask the ConfigurationManager to see if its configuration |
| 132 |
has changed. This is done by calling the isModified(<list>, |
| 133 |
<last modified>) method. eg, |
| 134 |
|
| 135 |
configManager("conf1.conf;conf2.conf", 2897938472) |
| 136 |
|
| 137 |
The ConfigurationManager would then check the file list |
| 138 |
given together with the system configuration file (as that |
| 139 |
file is the root of all configurations) to see if the date |
| 140 |
stamp on any of them is more recent than the given date. If |
| 141 |
a change is detected this method returns "true" otherwise |
| 142 |
it returns false. It is then up to the calling component to |
| 143 |
act, the system does not enforce configuration changes it |
| 144 |
mearly supports the facility to detect it. |
| 145 |
|
| 146 |
(note: this next section deals with the naming conventions |
| 147 |
used withing the configuration files ONLY. ie, from a |
| 148 |
sys admins point of view (ie, our users).) |
| 149 |
|
| 150 |
|
| 151 |
Configuring the I-Scream System |
| 152 |
------------------------------- |
| 153 |
|
| 154 |
Although there are three main configuration sections to be |
| 155 |
delt with, all configuration files use the same formatting |
| 156 |
conventions. These follow. |
| 157 |
|
| 158 |
Formatting |
| 159 |
---------- |
| 160 |
|
| 161 |
Each line should be terminated by a line terminator (\n or |
| 162 |
\r or \r\n). A line that contains only whitespace or whose |
| 163 |
first non-whitespace character is an ASCII # or ! is ignored |
| 164 |
(thus, # or ! indicate comment lines). Every line other than |
| 165 |
a blank line or a comment line describes one property to be |
| 166 |
added to the table (except that if a line ends with \, then |
| 167 |
the following line, if it exists, is treated as a |
| 168 |
continuation line, as described below). The key consists of |
| 169 |
all the characters in the line starting with the first |
| 170 |
non-whitespace character and up to, but not including, the |
| 171 |
first ASCII =, :, or whitespace character. All of the key |
| 172 |
termination characters may be included in the key by |
| 173 |
preceding them with a \. Any whitespace after the key is |
| 174 |
skipped; if the first non-whitespace character after the key |
| 175 |
is = or :, then it is ignored and any whitespace characters |
| 176 |
after it are also skipped. All remaining characters on the |
| 177 |
line become part of the associated element string. Within |
| 178 |
the element string, the ASCII escape sequences \t, \n, \r, |
| 179 |
\\, \", \', \ (a backslash and a space), and \uxxxx are |
| 180 |
recognized and converted to single characters. Moreover, if |
| 181 |
the last character on the line is \, then the next line is |
| 182 |
treated as a continuation of the current line; the \ and |
| 183 |
line terminator are simply discarded, and any leading |
| 184 |
whitespace characters on the continuation line are also |
| 185 |
discarded and are not part of the element string. |
| 186 |
|
| 187 |
As an example, each of the following four lines specifies |
| 188 |
the key "Truth" and the associated element value "Beauty": |
| 189 |
|
| 190 |
|
| 191 |
Truth = Beauty |
| 192 |
Truth:Beauty |
| 193 |
Truth :Beauty |
| 194 |
|
| 195 |
As another example, the following three lines specify a |
| 196 |
single property: |
| 197 |
|
| 198 |
fruits apple, banana, pear, \ |
| 199 |
cantaloupe, watermelon, \ |
| 200 |
kiwi, mango |
| 201 |
|
| 202 |
The key is "fruits" and the associated element is: |
| 203 |
|
| 204 |
"apple, banana, pear, cantaloupe, watermelon,kiwi, mango" |
| 205 |
|
| 206 |
Note that a space appears before each \ so that a space will |
| 207 |
appear after each comma in the final result; the \, line |
| 208 |
terminator, and leading whitespace on the continuation line |
| 209 |
are merely discarded and are not replaced by one or more |
| 210 |
other characters. As a third example, the line: |
| 211 |
|
| 212 |
cheeses |
| 213 |
|
| 214 |
specifies that the key is "cheeses" and the associated |
| 215 |
element is the empty string. |
| 216 |
|
| 217 |
default.properties |
| 218 |
------------------ |
| 219 |
|
| 220 |
This file is loaded by the CORE. The CORE either loads this |
| 221 |
file from the working directory, or from a specific location |
| 222 |
using the "-l" command line option. This file provides |
| 223 |
intial bootstrapping configuration to the system to get the |
| 224 |
whole thing on its feet. The requirement for entries here |
| 225 |
is kept to a bare minimum, however all entries listed below |
| 226 |
MUST have an option set for the system to start. Current |
| 227 |
configurable options in this file are: |
| 228 |
|
| 229 |
---- |
| 230 |
org.omg.CORBA.ORBClass= jacorb.orb.ORB |
| 231 |
org.omg.CORBA.ORBSingletonClass= jacorb.orb.ORBSingleton |
| 232 |
|
| 233 |
These two options specifiy which ORB the sytem is to use. |
| 234 |
By default these are set to the above values, as the JacORB |
| 235 |
ORB is the one that is distributed with the system, however |
| 236 |
should you wish to change ORB's to fit with your |
| 237 |
organisation, it is supported. |
| 238 |
|
| 239 |
---- |
| 240 |
uk.ac.ukc.iscream.Verbosity= 5 |
| 241 |
|
| 242 |
This sets the logging verbosity to be used by the system, |
| 243 |
ie, how much information will be printed to the log file, |
| 244 |
where the number is: |
| 245 |
|
| 246 |
FATAL - (0) Fatal or Critical Errors |
| 247 |
ERROR - (1) All Errors |
| 248 |
WARNING - (2) Warnings |
| 249 |
SYSMSG - (3) System Component messages |
| 250 |
SYSINIT - (4) System Component initialisation |
| 251 |
DEBUG - (5) All debugging messages |
| 252 |
|
| 253 |
---- |
| 254 |
uk.ac.ukc.iscream.ConfigurationLocation=../etc |
| 255 |
uk.ac.ukc.iscream.SystemConfigurationFile=system.conf |
| 256 |
|
| 257 |
These set up the configuration component. The first entry |
| 258 |
tells where the root directory of all configurations for the |
| 259 |
system are to be found. The second entry specifies the name |
| 260 |
of the system configuration file to be used. |
| 261 |
|
| 262 |
---- |
| 263 |
uk.ac.ukc.iscream.LoggerClass=ScreenLogger |
| 264 |
uk.ac.ukc.iscream.LoggerClassParam= |
| 265 |
|
| 266 |
These set up the logging facility. The first entry is a |
| 267 |
class name of the Logger class to be used by the system. |
| 268 |
The second line may or may not appear depending on the |
| 269 |
logging class in use. Logging classes require different |
| 270 |
configuration options to operate, please refer to their |
| 271 |
documentation for details. A variety of logging classes |
| 272 |
will be included with the i-scream system, again, please |
| 273 |
refer to their documentation for what functionality they |
| 274 |
provide. |
| 275 |
|
| 276 |
System Configuration File |
| 277 |
------------------------- |
| 278 |
|
| 279 |
This file is used as the defaults for all configurations |
| 280 |
used by the system. When a property is requested from a |
| 281 |
configuration, if it can't be found in any of the other |
| 282 |
files in its configuration tree, this file is checked before |
| 283 |
returning null. This allows for global defaults to be |
| 284 |
placed here. Another function of this file is that if no |
| 285 |
individual configuration file exists for a component it is |
| 286 |
returned a reference to this file alone. This means that |
| 287 |
a configuration file does not HAVE to be created for every |
| 288 |
component. |
| 289 |
|
| 290 |
There are several key things to be noted for this file. |
| 291 |
Individual entries for various components are not detailed |
| 292 |
in this document, but are instead listed in the |
| 293 |
documentation for the component in question. |
| 294 |
|
| 295 |
config.<elementname> = <config file> |
| 296 |
|
| 297 |
where <elementname> can be: |
| 298 |
|
| 299 |
Host.<hostname> |
| 300 |
Client.<clientname> |
| 301 |
<componentname> |
| 302 |
|
| 303 |
The <hostname> must FQDN, it should all be in lower case. |
| 304 |
The <clientname> is the configured name for the particular |
| 305 |
client. |
| 306 |
The <componentname> the name as given in the component for |
| 307 |
any particular component. |
| 308 |
|
| 309 |
The <config file> is file name of a configuration under the |
| 310 |
configurtion root directory. |
| 311 |
|
| 312 |
An example of how this can be used: |
| 313 |
|
| 314 |
FilterManager.listenPort=4567 |
| 315 |
|
| 316 |
This line for the <componentname> of FilterManager can |
| 317 |
appear in the system configuration. Or if the following |
| 318 |
line exists in the system configuration: |
| 319 |
|
| 320 |
config.FilterManager = filterManager.conf |
| 321 |
|
| 322 |
The file "filterManager.conf" and any included files will |
| 323 |
be checked for the entry, before looking for it in the |
| 324 |
system configuration. |
| 325 |
|
| 326 |
Other Configuration Files |
| 327 |
------------------------- |
| 328 |
|
| 329 |
The main entry of other configuration files to be aware of |
| 330 |
is the: |
| 331 |
|
| 332 |
include = file1.conf;file2.conf;file3.conf |
| 333 |
|
| 334 |
This line can be in the configuration file. Each include |
| 335 |
would will be processed in turn, checking to see if they |
| 336 |
have any includes. All of these would then be brought |
| 337 |
together into one list. |
| 338 |
|
| 339 |
Assuming a configuration above, and that each of the |
| 340 |
includes has two includes, we would get the following list |
| 341 |
of configuration files, which are checked for configuration |
| 342 |
properties in the following order: |
| 343 |
|
| 344 |
conf.conf;file1.conf;file1a.conf;file1b.conf; |
| 345 |
file2.conf;file2a.conf;file2b.conf;file3.conf; |
| 346 |
file3a.conf;file3b.conf;system.conf |
| 347 |
|
| 348 |
Note the order of precedence of the includes of the included |
| 349 |
files, namely that their includes take higher priority over |
| 350 |
the includes of the lower down includes. Also note that |
| 351 |
they system configuration appears last, allowing global |
| 352 |
values to be placed there. |
| 353 |
|
| 354 |
|
| 355 |
For further information on configurating other components of |
| 356 |
the system, please refer to the components individual |
| 357 |
documentation. |
| 358 |
|
| 359 |
|
| 360 |
About |
| 361 |
----- |
| 362 |
|
| 363 |
This document was written by Alex Moore [ajm4@ukc.ac.uk] for |
| 364 |
use by the team working on a 3rd year Computer Science |
| 365 |
project called "i-scream". More details can be found on the |
| 366 |
project website; |
| 367 |
|
| 368 |
http://www.i-scream.org.uk |
