== UNICORE configuration utility ==

The tool allows for easy and repeatable configuration of UNICORE components.
Both Quickstart and RPM/deb installed components are supported: 
if the program was installed via RPM/deb, system-wide then
also the system wide configuration of UNICORE components is updated. Otherwise
the tool updates local configuration of the Quickstart installation.

The main program, without extra switches takes a list of configurations as arguments. 
Each configuration is loaded. Section name of the configuration (the syntax is described below)
is used to establish which configurator shall be used. Configurator is responsible for configuring 
a particular UNICORE component as Unicore/X or Gateway. 
The configurator is searched in the proper folder (dependent on installation type) 
and invoked with the loaded configuration and parsed command line options.

For each configurator it is possible to list its variables in a format suitable to create a template 
configuration when invoked with -h <configuratorName>

Each configurator should have common parameters: -d (dry run), -s (silent), -n (no backup)
-B (do backup even if older backup exists - with timestamp)

Generic help is printed with -h

What follows is the description of the syntax of the configuration file, 
which must be created/edited by administrator before using this tool.

=== Standard sections ===

[${name}]

For every such section named ''${name}'' there should exist a configurator.  
It is loaded and executed with the configuration read from its section.

The section contents is made from key value pairs, concatenated with '=':

key=value

The value can refer an other, previously defined value by specifying it
using this expression: %(KEY)s
Example:

uxHost=localhost
...
tsiHost=%(uxHost)s

There is one special section called DEFAULT. This section is loaded always
(and first) regardless of which configuration was activated.

The lines starting with # are ignored. 

The rest of this README is intended for the advanced administrators, 
that want to perform a highly customized configuration tasks. 


=== Hidden sections ===

[_${name}]

Every such a section is skipped during processing. Underscore helps to disable
easily one section in config file.


=== Raw sections ===

Those sections are only for experienced administrators and should not be used
in normal scenarios. So this part of manual may by skipped.

Nevertheless, it is worth to know, that raw sections may be used to make some 
site-specific changes, additionally to those defined in configurator(s). The advantage
of such approach is, that custom changes of the original configuration can be simply
re-added after components update.

As an example, administrator can modify logging levels for her/his
purposes or always add an additional site-specific storage.

So, raw sections works a bit different then normal configurators.
There is no configurator related with name of section. 
The name is composed of three parts separated with a slash character ('/'):
- component name,
- operation type,
- filename.   

Processing every raw section starts with loading all properties and removing 
all default ones from ''[DEFAULT]'' section (note that if there will be the 
same key, it will be removed).

Next, those keys are treated as properties names, shell variables or xml 
properties depends on the type. 


==== Raw Java properties file sections ===== 

[${name}/props/${file}]

For every such section, properties are passed to method which substitute all 
of them in UNICORE configuration file named ''${file}'' located in 
configuration directory of component ''${name}''.
   

==== Raw shell variables file sections ===== 

[${name}/shell/${file}]

For every such section, properties are passed to method which treat them as 
a shell variables and substitute them in UNICORE configuration file named 
''${file}'' located in configuration directory of component ''${name}''.


==== Raw UNICORE xml file sections ===== 

[${name}/xml/${file}]

This section works only for files named 'xnjs.xml', 'xnjs_legacy.xml' or 
'wsrflite.xml'. The section's properties are treated as XML properties in 
appropriate file.

In case of file:
- 'wsrflite.xml', there is added or set value attribute of property	element 
	''/services/property[@name="${key}"]'',
- 'xnjs.xml' or 'xnjs_legacy.xml', there is added or set value attribute of 
	property element 
	''/eng:EngineConfiguration/eng:Properties/eng:Property[@name="${key}"]''.

Other operations like adding processor class to processing chains have to be 
done by a configurator.


==== Raw append to file sections ===== 

[${name}/append/${file}]

This sections first selects only keys started with prefix ''line.'', which are
formed as a list. Next, those lines are added to a file ''${file}'' located in 
a directory of component ''${name}''.

There are added only lines which did not exists so far. This way there is no
way to add the line more then once, even if the config file is used several 
times.
