[[ux_configuration]]
Configuration of UNICORE/X
--------------------------

Overview of the main configuration options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

UNICORE/X is a fairly complex software which has many interfaces to other UNICORE components
and configuration options. This section tries to give an overview of what can 
and should be configured. The detailed configuration guide follows in the next sections.

==== Mandatory configuration

 - Certificates and basic security: UNICORE uses X.509 certificates for all servers. 
For UNICORE/X these are configured in the wsrflite.xml config file

 - Attribute sources: to map clients (i.e. X.509 certificates) to local attributes such as 
user name, groups and role, various attribute sources are available. For details,
consult xref:ux_aip.

 - Backend / target system access: to access a resource manager like SGE or Torque, the
UNICORE TSI needs to be installed and UNICORE/X needs to be configured accordingly. Please
consult xref:ux_xnjs.

UNICORE/X has several sub-components. These are configured using
several config files residing in the CONF directory, see 
xref:ux_install for the location of the CONF directory.

Config file overview
~~~~~~~~~~~~~~~~~~~~

The following table indicates the main configuration files. Depending on
configuration and installed extensions, some of these files may not be present, or
more files may be present.

UNICORE/X watches some most configuration files for changes, and tries to reconfigure 
if they are modified, at least where possible. This is indicated in the
"dynamically reloaded" column.
are indicated.

.UNICORE/X configuration files
[options="header"]
|===============================
|config file        | usage					| dynamically reloaded
|startup.properties |Java settings (e.g. memory), lib/log/conf directories    | no
|uas.config	    |General settings, startup behaviour, storages, AIP setup    | yes
|wsrflite.xml	    |Services to be deployed, SSL settings, Web server settings|yes
|simpleidb	    |Backend, installed applications, resources|yes
|xnjs.xml	    |Back end properties | no 
|xnjs_legacy.xml    |Back end properties preconfigured for the Perl TSI| no
|logging.properties |logging levels, logfiles and their properties|yes
|xacml2Policies/*.xml | Access control policy for securing the web services|yes, via xacml2.config (do 'touch xacml2.config' to trigger) 
|xacml2.config	    |Configure the XACML2 access control component|yes
|vo.config          |Configure the use of UVOS (optional attribute source) | no
|simpleuudb         |A file mapping user DNs to local attributes (optional attribute source) |yes
|jmxremote.password |Access control file for remote monitoring using the Java management extensions (JMX)  | no
|===============================

Settings for the UNICORE/X process (e.g. memory)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The properties controlling the Java virtual machine running the
UNICORE/X process are configured in
  
  - UNIX: the CONF/startup.properties configuration file
  
  - Windows: the "CONF\\wrapper.conf" configuration file
  

These properties include settings for maximum memory, and also the properties
for configuring JMX, see xref:ux_admin for more on JMX.  

General
  
Config file formats
~~~~~~~~~~~~~~~~~~~

UNICORE/X uses two different formats for configuration. 
  
==== Java properties

    - Each property can be assigned a value using the syntax "name=value"
  
    - Please do not quote values, as the quotes will be interpreted as part of the value

    - Comment lines are started by the "#" 
  
    - Multiline values are possible by ending lines with "\", e.g.
  
-------
      name=value1 \
      value2
-------
   
In this example the value of the "name" property will be "value1 value2".
    

==== XML

Various XML dialects are being used, so please refer to the example files distributed with
UNICORE for more information on the syntax. In general XML is a bit unfriendly to edit, and
it is rather easy to introduce typos. 

[NOTE]
============
It is advisable to run a tool such as 'xmllint' after editing XML files to check for
typos
============

Integration of UNICORE/X into a UNICORE infrastructure
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Since UNICORE/X is the central component, it is interfaced to other parts of the UNICORE architecture, 
i.e. the Gateway, the Registry and the TSI.

==== Gateway

The gateway address is usually hard-coded into CONF/wsrflite.xml, and on the gateway side
there is an entry VSITE_NAME=address pointing to the UNICORE/X container. In some
scenarios it's convenient to auto-register with a gateway. This can be enabled using the 
following properties.

.Gateway settings
[options="header"]
|===========================
|config file | property name 		| range of values		| description	| modifyable at runtime
|wsrflite.xml| Base URL                 | host/port                     | the host/port of the gateway | (yes)
|uas.config  |container.gateway.registration|true or false	        |whether autoregistration should be enabled| no 
|            |container.gateway.registrationUpdateInterval|an integer					|registration refresh interval in seconds | no
|            |container.gateway.checkSignature | true or false | whether gateway assertions must be signed (see also security) | no
|            |container.gateway.waitOnStartup        | true or false         |whether UNICORE/X should check if the gateway is up during startup | no
|=====================================

[NOTE]
=========
To use the autoregistration feature, the gateway configuration must be set up accordingly
=========

==== Registry

It is possible to configure UNICORE/X to contact one or more 
external or "global" Registries in order to publish information on crucial services
there. Most of the following properties deal with the automatic discovery 
and/or manual setup of the external registries being used.

.Registry settings
[options="header"]
|====================
|config file | property name 		| range of values		| description	| modifyable at runtime
|uas.config  |container.externalregistry.use	|"true", "false"	|whether to publish service information in an external registry|yes
|     	     |container.externalregistry.url			|a valid URL		| use this URL for external registry if automatic discovery is switched off or fails|yes
|    	     |container.externalregistry.url.*			|more valid URLs	| additional registry URLs | yes 
|wsrflite.xml|container.wsrf.sg.defaulttermtime|a long value       | alive-check interval for registry entries in seconds ; an external registry will enforce its own value |yes
|            |container.externalregistry.autodiscover	|"true", "false"	|if set to "true", try to autodiscover the external registry via UDP multicast | yes
|================================

Startup code
~~~~~~~~~~~~

In order to provide a flexible initialization process for the UAS, we 
introduce a property named "uas.onstartup", which is defined in the 
file "uas.config". The value string of this property consists of a 
whitespace separated list of java classes which must be implementing the 
"Runnable" interface. Many extensions for UNICORE/X rely on an entry 
in this property to initialise themselves.
  

.Startup code
[options="header"]
|=============================
| class name			   	    | description | usage
|de.fzj.unicore.uas.util.DefaultOnStartup   | initialises the job management system and the "local" registry; should usually be run on startup | normal UNICORE/X servers 
|de.fzj.unicore.bes.util.BESOnStartup   | initialises the OGSA-BES job management system | UNICORE/X servers that expose BES services
|de.fzj.unicore.cisprovider.impl.InitOnStartup | sets up the CIS infoprovider | UNICORE/X servers that want to provide information in GLUE2 format or want to be visible in the CIS
|com.intel.gpe.gridbeans.PublishGridBeanService |if available, publishes the GridBeanService to the registry | UNICORE/X servers that host a Gridbean service
|de.fzj.unicore.uas.util.CreateSMSOnStartup |creates and deploys a single instance of the SMS that is shared between users, named default_storage| if a shared storage is required
|============================


Security
~~~~~~~~
  
==== Overview

Security is a complex issue, and many options exist. On a high level, the following items
need to be configured.
   
   - SSL setup (keystore and truststore settings for securing the basic communication between components)

   - Attribute sources configuration (which will map Grid users to local properties such as role, Unix login and groups)
    
   - Access control setup (controlling in detail who can do what on which services)
  
   - Message level security (message signatures)
   
[[use-secref]]
==== General security options

This table presents all security related options, except credential and truststore settings
which are described in the subsequent section.

include::use-ref-security.txt[]

:leveloffset: 2

[[use-authtrust]]
include::sec-authtrustcfg.txt[]

:leveloffset: 0

==== SSL configuration

Here you configure the server identity and the certificates of other services that want to contact this server.

include::credProperties.txt[]

include::trustProperties.txt[]

==== Attribute sources configuration

Attribute sources provide information about which local role and properties a Grid user has.
UNICORE knows several attribute sources which can be combined using various combining algorithms.
These are configured in the uas.config file. Due to the complexity, the description of the
configuration options can be found in xref:use_aip.

   
==== Access control configuration

Access control works by checking a Grid user's attributes (obtained from the attribute sources)
against a set of policies. Again, several options exist, which are described in xref:use_pdp.


==== Message signatures
  
UNICORE/X will require important messages (like job submissions or file exports) to be signed.
The property controlling this is
 - container.security.signatures
If set to true (which is the default), signatures are required.

Configuring the XNJS and TSI
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Information on the configuration of the XNJS and TSI backend can be found in xref:ux_xnjs.

Configuring storages on TargetSystem instances
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Each TargetSystem instance can have one or more storages attached to it. Note that this 
is different case from the shared storage (the one created with CreateSMSOnStartup hook)
which is not attached to any particular TargetSystem. The practical difference is that to use 
storages attached to a TargetSystem, a user must first create one.
    
By default, only the HOME storage is created, which allows users access their home directory on
the target system. You can add storages easily, using configuration entries in uas.config.

include::tss-smsProperties.txt[]

Here, "N" stands for an identifier (e.g. 1,2, 3, ...) to distinguish the storages. For example, 
to configure two storages, one named TEMP pointing to "/tmp" and the other named DEISA_HOME 
pointing to "$DEISA_HOME", you would add the following configuration entries in uas.config:

-------------------
coreServices.targetsystem.storage.1.name=TEMP
coreServices.targetsystem.storage.1.type=FIXEDPATH
coreServices.targetsystem.storage.1.path=/tmp
coreServices.targetsystem.storage.1.protocols=UFTP BFT

coreServices.targetsystem.storage.2.name=DEISA_HOME
coreServices.targetsystem.storage.2.type=VARIABLE
coreServices.targetsystem.storage.2.path=$DEISA_HOMES

# example for a custom SMS implementation (e.g. for Hadoop or iRODS)
coreServices.targetsystem.storage.3.name=IRODS
coreServices.targetsystem.storage.3.type=CUSTOM
coreServices.targetsystem.storage.3.path=/
coreServices.targetsystem.storage.3.class=my.custom.sms.ImplementationClass
-------------------

Note that you can optionally control the file transfer protocols that should be enabled for each storage.

==== Controlling target system's storage resources

By default storage resource names (used in storage address) are formed from
the owning user's xlogin and the storage type name, e.g. "someuser-Home". This is quite useful 
as users can write a URL of the storage without prior searching for its address.
However if the site's user mapping configuration, maps more then one grid certificate to the same
xlogin then this solution is not acceptable: only the first user connecting would be able to access
her/his storage. This is as resource owners are expressed as grid user names (certificate DNs) and not xlogins.
To have an unique, but dynamically created and non user friendly names of storages 
(and solve the problem of non-unique DN mappings) set this option in uas.config:

------------------
coreServices.targetsystem.uniqueStorageIds=true
------------------

If you want to disable the default "Home" storage, you can set the following property in uas.config:

------------------
coreServices.targetsystem.homeDisable=true
-------------------
  
Configuring the StorageFactory service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The StorageFactory service allows clients to dynamically create storage instances.
These can have different types, for example you could have storages on a normal
filesystem, and other storages on an Apache Hadoop cluster.

The basic property controls which storage types are supported

----------------
coreServices.sms.enabledFactories=TYPE1 TYPE2 ...
----------------

Each supported storage type is configured using a set of properties

include::smf-smsProperties.txt[]

For example

----------------
coreServices.sms.factory.TYPE1.description=GPFS file system
coreServices.sms.factory.TYPE1.fixedpath=GPFS file system
coreServices.sms.factory.TYPE1.path=/mnt/gpfs/unicore/unicorex-1/storage-factory
coreServices.sms.factory.TYPE1.protocols=UFTP BFT

# if this is set to true, the directory corresponding to a storage instance will
# be deleted when the instance is destroyed. Defaults to "true"
coreServices.sms.factory.TYPE1.cleanup=true
----------------

The "path" parameter determines the base directory used for the storage instances 
(i.e. on the backend), and the unique ID of the storage will be appended automatically.

The "cleanup" parameter controls whether the storage directory will be deleted when the storage
is destroyed. 

The normal storage properties (see the previous section) are also accepted: "protocols",
"type", "class", "filterFiles" etc.

If you have a custom storage type, an additional "class" parameter defines the
Java class name to use (as in normal SMS case). For example:

----------------------
coreServices.sms.factory.TYPE1.type=CUSTOM
coreServices.sms.factory.TYPE1.class=de.fzj.unicore.uas.hadoop.SMSHadoopImpl
----------------------

HTTP proxy, timeout and web server settings
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The UNICORE Services Environment container has a number of settings related to 
the web server and to the HTTPClient library used for outgoing HTTP(s) calls.

The server options are shown in the following table.

include::http-serverProperties.txt[]


The client options are the following

include::http-clientProperties.txt[]
 

  
  
