
[[configuration]]
Configuration
-------------

Database configuration
~~~~~~~~~~~~~~~~~~~~~~
The database configuration is done in properties file +CONF/datamap.properties+. 
You should uncomment and then edit the section which matches your DBMS. For a correct setup, 
you need to specify a username, password and a connection URL. The connection URL must be changed 
only if your database name is different than "uvosdb".

NOTE: When using an embedded DB the default +datamap.properties+ file need not to be modified.

Final step (required also for the embedded DB) is to initialize DB contents. 
This is done by invoking a script:

 $ BIN/initdb.sh

or in case of distribution specific package:

 $ BIN/unicore-uvos-server-initdb
 
[[server_configuration]]
Server configuration
~~~~~~~~~~~~~~~~~~~~

Basic server configuration (security, network addresses, authentication options, etc.) 
is done in the +CONF/uvosServer.conf+ file. The file is well commented, with an explanation
for all options and has to be reviewed by every administrator. 

After installation vast majority of options have reasonable values. However the following options
require a review and often need to be updated:

 * Security settings, i.e. server trust settings and server credential. 
 By default after installing with distribution package there are no certificates
 provided. The portable archive bundle provides example, insecure certificates and keys
 (don't use them in production, never!). 
 * Network host address and port to use.

The options of the UVOS server are presented in the following table. Note that some of the options (most importantly 
those to set up credential and truststore) are described in separate tables - the table below only gives
prefixes for those options. 

include::uvos-ref-main.txt[]

:leveloffset: 2

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

:leveloffset: 0


Authentication
^^^^^^^^^^^^^^

The UVOS server provides several ways of authenticating incoming requests. 
All authentication options are in fact a result of an authentication identity format
and authentication source combination, i.e. security material used to establish the
identity. The authenticated requester must be known to the VO service (but does not
need to be a member of any VO/group). The possible options are listed below.

* *TLS* - it is possible when the request uses a HTTPS connection AND (!) the client
 was successfully authenticated. Note that when allowAnonymous is true then the
 request may arrive through a HTTPS channel, but still be unauthenticated. In such
 a case this authentication method will not succeed. The resulting identity format is
 either a X.509 certificate or DN of the HTTPS client. The order in which formats
 are tried (DN or certificate) can be configured.
* *HTTP* - possible when the requester used HTTP simple authentication 
 (i.e. login and password encoded in HTTP header). The resulting identity format is
 an email address. The user is authenticated when the UVOS password check is successful.

The order in which the above options are tried can be configured by the server administrator. 
It is possible to set which authentication data source is tried first (TLS or HTTP). 
Whenever there is no authentication material the server jumps to the next available
option. It might happened that authentication material, for a specified option,
is present but is invalid. In such a case the server can either fail the authentication
immediately or skip to the next option - this behaviour is also configurable. 

.Example: 
=============================================================================
Let's assume that HTTPS is the only transport enabled with +uvos.server.https.allowAnonymous+
parameter set to true, the authentication order is as follows: "HTTP TLS". 
Moreover, let's assume that the incoming request is arriving through a
client-authenticated TLS session, but has incorrect HTTP auth data in the header
(user is not registered in VO DB). 

 * _Case 1: the server doesn't trust the client's certificate and +uvos.server.authn.failOnError+ is true._ 
 The +uvos.server.https.allowAnonymous+ setting will cause the request not to be denied 
 at transport level. 
 What follows is the authentication step. TLS will be skipped (no input data). 
 As a result, the request will be processed by HTTP module which will fail and 
 cause authentication process to stop.
 * _Case 2: the server doesn't trust the client's certificate and +uvos.server.authn.failOnError+ is false._ 
 The behaviour will be the same as above.
 * _Case 3: the server trusts the client's certificate and +uvos.server.authn.failOnError+ is true._ 
 The first TLS will succeed if the DN from certificate is registered in the VO database. 
 Otherwise authN will fail immediately.
 * _Case 4: the server trusts the client's certificate and +uvos.server.authn.failOnError+ is false._ 
 The TLS will succeed if the DN from certificate is registered in the VO database. 
 Otherwise authN will be continued. HTTP will fail (incorrect data).
=============================================================================


Using X509 certificates as DNs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Starting from the release 1.3 server allows for using identities of X.509 certificate type
as DN type identities. This feature is turned on by default. It works only for SAML attribute
queries (so normal queries made for instance by Unicore server or clients) and in SAML
authentication protocol. In case of attribute query this functionality is activated when:

 1. the query subject is of DN type identity (note that it is a standard case),
 2. there is no identity in the database which is equal to the query subject and
  which has a DN type,
 3. there is an identity A in DB which is of X.509 certificate type and the subject
  of this certificate is the same as the query subject.

When all the above conditions are met, then the server will return attributes of A. 
If the certificate mapping feature is turned off, then in such a case server will
respond with error saying that the query subject is unknown.

:leveloffset: 2
include::sec-jetty.txt[]
:leveloffset: 0


Mail notification configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

One of the features of the UVOS server is to collect VO applications (or registration requests). 
It is possible to use an email notification mechanism along with the application process. 
The notification can be generated in two specific cases:

 * whenever a new application arrives (notification is sent to the VO administrator).
 * whenever a application is processed (notification is sent to its owner).

Moreover, from version 1.2 upwards, it is possible to configure UVOS to send notifications
as a result of nearly every management operation. There are two configuration files that 
control email notifications: one containing general configuration and the another containing 
templates of messages to be sent.

The location of the basic mail configuration file is specified in the main configuration
file. The default location is +CONF/mail.properties+. The table below shows the configuration
options along with the type, default value and the description.

[width="100%",cols="<35%m,12%<,23%<m,30%<",frame="topbot",options="header"]
|===========================================================
|Property name|Type|Default value|Description
|mailx.enable|'true' or 'false'|false|Set it to true to enable email notification sending. The rest of the mail configuration is ignored if the value is set to false.
|mailx.sendTestMessageTo|email address d|unset|Use this property only if you want to debug the email configuration. When set, the server will send a test message to the specified address upon every startup. 
|mail.from|email address|root@localhost|User name which will be used for the From: field of the email. It is also used as a SMTP envelope return address if it is not overridden below.
|mail.smtp.host|host address|localhost|The SMTP server to connect to.
|mail.smtp.starttls.enable|'true' or 'false'|false|If true it enables the use of the STARTTLS command (if supported by the server) to switch the connection to a TLS-protected connection before issuing any login commands. IMPORTANT! SMTP server's certificate must be trusted to establish the connection. The software will use the same truststore that is defined in main configuration of the server. It is therefore important to add the SMTP server's CA certificate to the main truststore
|mail.smtp.from|email address d|as in +mail.from+|Email address to use for the SMTP MAIL command. Is also sets the envelope return address.
|mail.smtp.auth|'true' or 'false'|false|If true, attempt to authenticate the user using the AUTH command.
|mailx.smtp.auth.username|string d|unset|The username used when authentication is enabled by mail.smtp.auth.
|mailx.smtp.auth.password|string d|unset|The password used when authentication is enabled by mail.smtp.auth.
|mail.smtp.timeoutSocket|integer number d|infinite|I/O timeout value in milliseconds.
|mail.smtp.connectiontimeout|integer number d|infinite|Socket connection timeout value in milliseconds.
|mail.smtp.port|1-65535|25|The SMTP server port to connect to.
|mail.debug|'true' or 'false'|false|Set this property to true if you want to see debug messages (are printed to the standard error, not logged!). 
d|OTHER OPTIONS|- d|-|For other options see the SUN Java Mail documentation. http://java.sun.com/products/javamail/javadocs/com/sun/mail/smtp/package-summary.html
|===========================================================


The location of the template configuration file is defined in the main UVOS configuration file
and is set to +CONF/mailTemplates.properties+ by default. In this file you can specify the
subject and the body of all notifications. There are also special entries for VO applications.
If a customised notification template is not specified then the default template will be used. 
It is possible to create dynamic emails by using variables denoted with ${...}. If such 
variables are used the server will replace the variable with it's actual value e.g. for
variable ${CALLER} an event initiator or event subject for ${SUBJECT}.

The table below shows the properties that can be defined in the template configuration file
along with their description.

[width="100%",cols="<35%m,12%<,23%<,30%<",frame="topbot",options="header"]
|==============================================================
|Property name|Type|Default value|Description
|mailtemplate.newApplication.subject|string|give a try to see|Defines the subject of a message sent to the VO admin (who is defined in an application form) when a new application is submitted. The runtime variables, available for this message are: +$\{FORM_NAME}+ - application's form name, +$\{FORM_ID}+ - application's form id, +$\{FORM_GROUP}+ - application's base group 
|mailtemplate.newApplication.body|string|give a try to see|Defines the body of the message sent to the VO admin (who is defined in applications form) when a new application is submitted. Available runtime variables as the same as above.
|mailtemplate.applicationProcessed.subject|string|give a try to see|Defines the subject of the message sent after an application is processed (but not REMOVED).The runtime variables, available for this message are: +$\{APP_ID}+ - ID of application, +$\{APP_ADMIN_NOTES}+ - application's notes as appended by admin, +$\{APP_STATUS}+ - new application's status (e.g. REJECTED or ACCEPTED), +$\{FORM_NAME}+ - application's form name, +$\{FORM_GROUP}+ - application's base group 
|mailtemplate.applicationProcessed.body|string|give a try to see|Defines the body of the message sent after an application is processed (but not REMOVED).Available runtime variables as the same as above.
|mailtemplate.subject|string|give a try to see|Defines the default subject for messages sent as a result of of management events.
|mailtemplate.body|string|give a try to see|Defines the default body for messages sent as a result of management events.
|mailtemplate.<ACTION>.subject|string|unset|Redefines the subject of messages sent as a result of an event with the name specified by the <ACTION> param.
|mailtemplate.<ACTION>.body|string|unset|Redefines the body of messages sent as a result of an event with the name specified by the <ACTION> param.
|==============================================================

Although the available runtime variables will usually depend on the action, there 
are two common variables:

 * +$\{ACTION}+ - the name of the action, e.g. addGroup
 * +$\{CALLER}+ - the person that performed the action.

The following variables are action-dependent:

 * +$\{SUBJECT}+ - the value of the identity (e.g. which was added/removed...) or a group scoped
  identity (e.g. whose group scoped attribute was added)
 * +$\{GROUP}+ - the name of the affected group (e.g. created/removed)
 * +$\{TARGET}+ - (for copyGroup) the new name of a copied group
 * +$\{MOVED}+ - (for copyGroup) simple 'moved' or 'copied' string
 * +$\{EQUIVALENT}+ - (for addEquivalentIdentity) the name of an already existing, equivalent 
 identity
 * +$\{ATTRIBUTE}+ - the attribute, which was either set or removed
 * +$\{STATUS}+ - (for setIdentityStatus) 'disabled' or 'enabled'
 * +$\{DATE}+ - (for purgeHistoricalData) the date up to this date historical data was cleared.



:leveloffset: 2
include::sec-logging.txt[]
:leveloffset: 0

Several logging categories common in UVOS server:

[options="header"]
|===============================
|Log category      			| Description
|unicore           			| All of UNICORE 
|unicore.security  			| Generic UNICORE security layer
|unicore.client    			| Client calls (to other servers, mostly registry registrations) 
|unicore.uvos     			| Everything UVOS related
|unicore.uvos.server     	| UVOS server logging
|====================================================================




Defining attribute types
~~~~~~~~~~~~~~~~~~~~~~~~

Although you can add, delete or modify attribute types using client tools when server
is running, it is convenient to load a predefined set of attribute types with descriptions. 
It is a possible to define attribute types in a files, which are read on server startup.
The server can either add new or even update existing attribute types with the data
from these files. See +uvos.server.attributeType...+ configuration options for further details. 
The standard location of the files containing attribute types is under the +CONF/attributeTypes/+
directory.

The format of the attribute definition files of the UVOS system is extremely simple. 
It is line based and obeys the following rules:

 * Every line that begins with a '#' is ignored.
 * Every AT is defined by a block of consecutive lines. 
 * Every block is separated from other blocks by at least one empty line.
 
A block contains 4 lines:

 1. 'AT' (literal),
 2. attribute name (key),
 3. attribute short description or full name,
 4. attribute full description.

Moreover, the UVOS distribution contains a tool to translate LDAP schema files to
the above format. The +BIN/convertLDAPSchema.sh+ (or +BIN/unicore-uvos-server-convertLDAPSchema+) 
invokes a converter that translates 
its standard input in LDAP schema format to the UVOS format. E.g.:

 # BIN/convertLDAPSchema.sh <someLDAP.schema >additionalUVOSats.at

The default UVOS distribution contains two examples of files with attribute type
definitions. One contains core UNICORE authorization attributes (e.g. xlogin
attribute) while the other holds a set of common LDAP attributes.


Attribute release policy (aka attribute filtering)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

UVOS provides two clients' interfaces allowing for quering for attributes.
One of them is included in UVOS proprietary interface and is 
used by management tools like UVOS CLC or VOManager. The other, SAML interface
is used by UVOS consumers like Unicore/X. 

Up to version 1.4.1 of the UVOS server, the SAML interface always returned all attributes
for which requester asked (only except of attributes defined in the groups where requester 
does not have permission to read). From version 1.4.2 of the UVOS server it is possible to 
control what attributes are released to the SAML consumers. This is especially useful to 
optimize the amount of network traffic by releasing only the attributes which are 
externally meaningful and useful. Good example of an attribute which is useful only internally
is +urn:authz:intervo:vo+ attribute which is used to control internal UVOS server authorization.
  
The configuration file defined by the property +uvos.server.saml.attributeFiltersConfig+
in the +CONF/uvosServer.conf+ (by default it is +CONF/attributeFilters.properties+) 
controls the whole attribute release policy subsystem. 

The policy is composed of two main parts: 

 - a list of excluded attributes and
 - a list of explicitly exposed attributes. 

The list of excluded attributes always takes precedence, i.e. only attributes which 
are on the exposed attributes list and are not on the excluded list are presented 
to the requester. 

NOTE: If the list of exposed attributes is not defined, then by default
all attributes are exposed. If the list of excluded attributes is undefined then 
by default no attribute is excluded.

Typically if you want to expose all attributes except few, you only define 
the excluded attributes list. If you want to expose only few attributes and hide 
the rest then define the exposed attributes list only.
 
The basic syntax is as follows:

-----------
exposedAttribute.1=<regularExpression1>
exposedAttribute.2=<regularExpression2>
...
excludedAttribute.1=<regularExpression1>
excludedAttribute.2=<regularExpression2>
...
-----------

The rule numbers in each list must be consecutive, starting from 1. An attribute matches
a rule if its name matches the rule's regular expression.

Additionally you may define rules which are used for attributes scoped in 
particular groups only. To do so define a normal rule (exposed or excluded)
and add additional group filters as follows:

---------------
exposedAttribute.x=roleAttribute
exposedAttribute.x.scope.1=/VO-medicine.*
exposedAttribute.x.scope.not.1=/VO-medicine/public
---------------

In the above example the 'roleAttribute' will be exposed in '/VO-medicine' and
all its subgroups, except of '/VO-medicine/public'. The defaults and behavior
of the +scope+ and +scope.not+ rules is analogous as in the case of base 
'exposed' and 'excluded' rules.

Server operation
----------------

The server management scripts can be found in the BIN directory. 
Their names along with their descriptions are listed below (in brackets name
used by distribution specific package (e.g. RPM) is provided):

 * +initdb.sh+ (+unicore-uvos-server-initdb+) - initializes the db. This script can also be used to clean
  an existing database, and therefore it should be used with an extreme caution!
 * +startServer.sh+ (+unicore-uvos-server-startServer+) - starts a server in the background.
 * +stopServer.sh+ (+unicore-uvos-server-stopServer+) - stops a running server.
 * +createExampleContents.sh+ (+unicore-uvos-server-createExampleContents+) - creates an example contents of the service, 
 as it is presented in the accompanying overview document. 
 You should use it just after initializing the database (using the initdb.sh) 
 and before starting the server.
