documentation/specification/configuration.txt

I-Scream System Configuration - initial draft
=============================

ajm4, 26/11/2000

This document will address all three areas of concern
regarding the configuration operational parameters of the 
i-scream system to date.  These areas being:

    1) Configuration Mechanisms 
           - maintenance documentation
    
    2) Using the Configuration System
           - developer documentation
    
    3) Configuring the I-Scream System
           - user documentation
           
Configuration Mechanisms
------------------------

Configuration of the I-Scream system is predominantly 
carried out through the ConfigurationManager component.
However there is another configuration option which should
be used to an absolute minimum, yet it is necessary to
explain it here as it is used!

Any configuration that should be carried out before any 
component can initialise the ORB and obtain a reference to
the ConfigurationManager should be placed in a "properties"
file that is local to that component.  At the time of
writing the only component to require this is the CORE. This
is because is requires some initialisation to get the system
up and running.  However, it is NOT the norm to use this
method, and all elements of the system should make an effort
to attach to the orb and obtain the ConfigurationManager
before requiring any specific configuration. For information
on what is currently contained within the
"default.properties" file please refer to the user 
documentation.

The main form of configuration mechanism is the afore
mentioned ConfigurationManager.  This component acts as a
centralised holder for configuration for every part of the 
system.  Components get a referance to this well known
service either directly through the CORBA Naming Service
(see to-be-published conventions on Naming for the I-Scream
project).  Or via a local proxy, in the case of a Host this
is through the FilterManager, a hosts first connection to 
the system.  This allows both CORBA aware and 
non-aware components to be configured through this system.
The ConfigurationManager also provides support for
determining if a configuration has changed and thus (if the
component is programmed in such a way), support for dynamic
re-loading of configuration.  For information on how to use
the ConfigurationManager, please see the next section on
"Using the Configuration System".  For information on the 
file format and structure, together with what is currently
contained with the standard configuraton file, please refer
to "Configuring the I-Scream System".


Using the Configuration System
------------------------------

The configuration system itself has two main components.  
The ConfigurationManager and the Configuration objects.
It is currently envisaged that there will only ever be one
instance of the ConfigurationManager registered with the ORB
in use at any given time.  It has the well known service 
name of "iscream.ConfigurationManager" which a component 
can used to get a reference to it.

Once a component has reference to the ConfigurationManager
it should then request its configuration using the
getConfiguration(<name>) method.  eg,

    Configuration myConfig = 
        configManager.getConfiguration("FilterManager");
        
The above request causes the ConfigurationManager to look
in the system configuration file for the property:

    "config.FilterManager=<config file>"

It then creates a Configuration object based on the contents
of <config file> using the system configuration for the 
defaults of any values.  The ConfigurationManager also has
support for including other configurations within a file.
For more information on this feature please refer to the
next section on "Configuring the I-Scream System".

A refernce to this Configuration object is then passed back
to the calling component.  At which point that component can
interrogate the Configuration object to obtain its
configuration.  It should be noted that the Configuration
object uses a java.util.Properties object to store the 
configuration internally, so essentially Configuration acts
as a CORBA wrapper for a java.util.Properties object.

If the entry cannot be found, the component is returned a
reference to the system configuration.  This allows
components to be configured without the need to a
configuration file is only a small amount is needed.

If there is an error at any stage of obtaining the
configuration, an appropriate entry will be made in the log,
but the component will be returned a NULL reference.

To obtain entries from a Configuration, a component calls
the getProperty(<name>) method.  eg,

    myConfig.getProperty("FilterManager.listenPort")

This will return the String value for that property.  The 
entry in the configuration file would appear as:

    FilterManager.listenPort = <value>

The configuration system also has support for detecting that
a currently loaded configuration has been changed.  It 
achieves this by monitoring the date stamps of the
configuration files.  The interface to this functionality is
provided in two areas.  The Configuration object has two 
further methods, getFileList() and getLastModified().  The 
first returns a ";" separated list of filenames used to
obtain the configuration that was built for that instance. 
The second returns a long (in the programming sense) number
of representing the date stamp of the most recently modified
file in the list.  Using these two attributes a component 
can ask the ConfigurationManager to see if its configuration
has changed.  This is done by calling the isModified(<list>,
<last modified>) method.  eg,

    configManager("conf1.conf;conf2.conf", 2897938472)
    
The ConfigurationManager would then check the file list 
given together with the system configuration file (as that
file is the root of all configurations) to see if the date
stamp on any of them is more recent than the given date.  If
a change is detected this method returns "true" otherwise
it returns false.  It is then up to the calling component to
act, the system does not enforce configuration changes it
mearly supports the facility to detect it.

(note: this next section deals with the naming conventions
 used withing the configuration files ONLY.  ie, from a
 sys admins point of view (ie, our users).)


Configuring the I-Scream System
-------------------------------

Although there are three main configuration sections to be 
delt with, all configuration files use the same formatting
conventions.  These follow.

Formatting
----------

Each line should be terminated by a line terminator (\n or
\r or \r\n).  A line that contains only whitespace or whose
first non-whitespace character is an ASCII # or ! is ignored
(thus, # or ! indicate comment lines). Every line other than
a blank line or a comment line describes one property to be
added to the table (except that if a line ends with \, then
the following line, if it exists, is treated as a 
continuation line, as described below). The key consists of
all the characters in the line starting with the first
non-whitespace character and up to, but not including, the
first ASCII =, :, or whitespace character. All of the key
termination characters may be included in the key by
preceding them with a \. Any whitespace after the key is
skipped; if the first non-whitespace character after the key
is = or :, then it is ignored and any whitespace characters
after it are also skipped. All remaining characters on the
line become part of the associated element string. Within
the element string, the ASCII escape sequences \t, \n, \r,
\\, \", \', \ (a backslash and a space), and \uxxxx are
recognized and converted to single characters. Moreover, if
the last character on the line is \, then the next line is
treated as a continuation of the current line; the \ and
line terminator are simply discarded, and any leading
whitespace characters on the continuation line are also
discarded and are not part of the element string.

As an example, each of the following four lines specifies
the key "Truth" and the associated element value "Beauty": 


 Truth = Beauty
        Truth:Beauty
 Truth                  :Beauty
 
As another example, the following three lines specify a 
single property: 

 fruits                         apple, banana, pear, \
                    cantaloupe, watermelon, \
                    kiwi, mango
 
The key is "fruits" and the associated element is: 

"apple, banana, pear, cantaloupe, watermelon,kiwi, mango"

Note that a space appears before each \ so that a space will
appear after each comma in the final result; the \, line
terminator, and leading whitespace on the continuation line
are merely discarded and are not replaced by one or more
other characters.  As a third example, the line: 

cheeses
 
specifies that the key is "cheeses" and the associated
element is the empty string.

default.properties
------------------

This file is loaded by the CORE.  The CORE either loads this
file from the working directory, or from a specific location
using the "-l" command line option.  This file provides
intial bootstrapping configuration to the system to get the
whole thing on its feet.  The requirement for entries here
is kept to a bare minimum, however all entries listed below
MUST have an option set for the system to start.  Current
configurable options in this file are:

----
org.omg.CORBA.ORBClass= jacorb.orb.ORB
org.omg.CORBA.ORBSingletonClass= jacorb.orb.ORBSingleton

These two options specifiy which ORB the sytem is to use.
By default these are set to the above values, as the JacORB 
ORB is the one that is distributed with the system, however
should you wish to change ORB's to fit with your
organisation, it is supported.

----
uk.ac.ukc.iscream.Verbosity= 5

This sets the logging verbosity to be used by the system,
ie, how much information will be printed to the log file,
where the number is:

    FATAL   - (0) Fatal or Critical Errors
    ERROR   - (1) All Errors
    WARNING - (2) Warnings
    SYSMSG  - (3) System Component messages
    SYSINIT - (4) System Component initialisation
    DEBUG   - (5) All debugging messages

----
uk.ac.ukc.iscream.ConfigurationLocation=../etc
uk.ac.ukc.iscream.SystemConfigurationFile=system.conf

These set up the configuration component.  The first entry
tells where the root directory of all configurations for the
system are to be found.  The second entry specifies the name
of the system configuration file to be used.

----
uk.ac.ukc.iscream.LoggerClass=ScreenLogger
uk.ac.ukc.iscream.LoggerClassParam=

These set up the logging facility.  The first entry is a
class name of the Logger class to be used by the system.
The second line may or may not appear depending on the
logging class in use.  Logging classes require different 
configuration options to operate, please refer to their 
documentation for details.  A variety of logging classes
will be included with the i-scream system, again, please 
refer to their documentation for what functionality they 
provide.

System Configuration File
-------------------------

This file is used as the defaults for all configurations 
used by the system.  When a property is requested from a 
configuration, if it can't be found in any of the other
files in its configuration tree, this file is checked before
returning null.  This allows for global defaults to be
placed here.  Another function of this file is that if no
individual configuration file exists for a component it is 
returned a reference to this file alone.  This means that 
a configuration file does not HAVE to be created for every 
component.

There are several key things to be noted for this file.
Individual entries for various components are not detailed
in this document, but are instead listed in the 
documentation for the component in question.

config.<elementname> = <config file>

where <elementname> can be:

    Host.<hostname>
    Client.<clientname>
    <componentname>

The <hostname> must FQDN, it should all be in lower case.
The <clientname> is the configured name for the particular
client.
The <componentname> the name as given in the component for
any particular component.

The <config file> is file name of a configuration under the
configurtion root directory.

An example of how this can be used:

    FilterManager.listenPort=4567
    
This line for the <componentname> of FilterManager can
appear in the system configuration.  Or if the following
line exists in the system configuration:

    config.FilterManager = filterManager.conf

The file "filterManager.conf" and any included files will 
be checked for the entry, before looking for it in the
system configuration.

Other Configuration Files
-------------------------

The main entry of other configuration files to be aware of
is the:

    include = file1.conf;file2.conf;file3.conf

This line can be in the configuration file. Each include
would will be processed in turn, checking to see if they 
have any includes. All of these would then be brought 
together into one list.

Assuming a configuration above, and that each of the
includes has two includes, we would get the following list
of configuration files, which are checked for configuration
properties in the following order:

  conf.conf;file1.conf;file1a.conf;file1b.conf;
  file2.conf;file2a.conf;file2b.conf;file3.conf;
  file3a.conf;file3b.conf;system.conf

Note the order of precedence of the includes of the included
files, namely that their includes take higher priority over
the includes of the lower down includes.  Also note that
they system configuration appears last, allowing global
values to be placed there.


For further information on configurating other components of
the system, please refer to the components individual 
documentation.


About
-----

This document was written by Alex Moore [ajm4@ukc.ac.uk] for 
use by the team working on a 3rd year Computer Science 
project called "i-scream". More details can be found on the 
project website;

http://www.i-scream.org.uk
Revision:	1.2
Committed:	Mon Nov 27 23:13:22 2000 UTC (24 years ago) by ajm
Content type:	text/plain
Branch:	MAIN
CVS Tags:	PROJECT_COMPLETION
Changes since 1.1:	+1 -2 lines
Log Message:	removed the spec to have an ip as a hostname
#	User	Rev	Content
1	ajm	1.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	ajm	1.2	The <hostname> must FQDN, it should all be in lower case.
304	ajm	1.1	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