
Overview
--------

The UNICORE XUUDB is is used to map Grid user identity (an X.509 
certificate or X.500 distinguished name (DN)) to a set of attributes. The attributes
are typically used to provide local account details (uid, gid(s)) and sometimes
also to provide authorization information: user's role.

The UNICORE XUUDB is best suited as a site-service. Theoretically it can be used for multiple
sites, however as it offers limited authorization capabilities and doesn't allow 
for grouping users, it is better to use the more flexible UVOS server in such case. 
In case of the simple one host-service XUUDB sometimes can be replaced by the simple file
storing the mappings.

The XUUDB offers two web services, one for querying, and one for 
administration of the users' database. There are several clients which can use the XUUDB server:

 - Admin client (see <<sec_admin>>) can be used to control the XUUDB database contents.
 - UNICORE 6 servers include the XUUDB client code (it is named XUUDB Attribute Information Point) and
 can consume and process the XUUDB information.
 - UNICORE Rich client plugin allows for editing the XUUDB contents remotely, however it is not 
 enabled by default and it is not always up to date so some features might be missing.

Both admin and client access to the XUUDB can be protected by a client-authenticated SSL.

Since the version 2, XUUDB can map users using two different mechanisms:

 - _classic_ or _static_ mechanism, where administrator enters mappings 
 for each DN (or certificate) manually,
 - _dynamic_ mechanism, where administrator only define rules stating what attributes
 should be assigned to Grid users fulfilling rule's condition.   

The classic mapping
~~~~~~~~~~~~~~~~~~~

The classic or static mechanism was the only one available in XUUDB 1.x. It is useful
when number of users is small and easy to maintain or when UNICORE is used as a
gateway to HPC site, with a well defined set of users. It is also useful in Grid scenarios 
when a dedicated, external infrastructure is build to maintain a global list of users.

Using it it is possible to set a list of Unix logins (aka XLogins or uids), a list of 
UNIX groups (aka projects or gids) and the role attribute used for authorization. 
The first uid and the first gid is assumed to be the default one but Grid users are 
allowed to choose any of the available. 

In case of the default authorization policy the 'user' role is required to get a normal access
to the site, the 'admin' role grants super-user privileges, and the 'banned' role bans the user.    

The XUUDB stores either X.509 certificates ('normal' mode) or distinguished 
names ('dn' mode), see <<sec_certdn>>.

Multiple Grid sites can share the XUUDB, even if the attributes are
different per Grid site. Grid sites are grouped by the so-called GCID
(grid component ID).

The dynamic mapping
~~~~~~~~~~~~~~~~~~~

The dynamic mechanism was introduced in XUUDB 2. It is used to map users who 
_were already authorized_, therefore it doesn't make sense (and is not possible) 
to assign the authorization attributes as 'role'. The dynamic mechanism is 
useful in case of typical Grid deployments, when a site doesn't know a precise list of its 
users (which are maintained by the supported Virtual Organizations), or simply doesn't
want to define manually a local account for each grid user. In other words, site rely on a 
trusted 3rd party (a Virtual Organization) to maintain a list of genuine and authorized users,
and automatically assigns a local account to each user.

As it will be shown later on dynamic mappings can be also used in other scenarios, also 
being complementary to static mappings. 

Dynamic mappings configuration is described in the section <<dynamic>>.

    

[NOTE]
.IMPORTANT NOTE ON PATHS
=========================================================
XUUDB is distributed either as an platform independent and portable
bundle (as a part of UNICORE quickstart package) or as an 
installable, platform dependent package such as RPM. 

Depending on the installation package used paths are different. If 
installing using distribution-specific package the following path prefixes
are used:

  CONF=/etc/unicore/xuudb
  BIN=/usr/sbin
  ADMIN=/usr/sbin/unicore-xuudb-admin
  LOG=/var/log/unicore/xuudb

If installing using portable bundle all XUUDB's files are installed
under a single directory. Path prefixes used then are as follows, where INST 
is a directory where XUUDB was installed:

  CONF=INST/conf
  BIN=INST/bin
  ADMIN=BIN/admin.sh
  LOG=INST/log

The above variables (CONF, BIN, ADMIN and LOG) are used throughout the rest of this
manual.
=========================================================


Installation
------------

UNICORE XUUDB is distributed in the following formats:

 1. As a part of platform independent installation bundle called UNICORE Quickstart.
 UNICORE Quickstart is provided in two forms: one with graphical installer and one with a 
 command line installer.
 2. As a binary, platform-specific packages available currently for Scientific Linux 5,
 Scientific Linux 6 and Debian 6 platforms. Those packages are tested on
 the enumerated platforms, but should work without any problems with other versions of 
 similar distributions (e.g. version for SL6 works well on Centos 6 or recent Fedora 
 distributions. Differences between SL5 and SL6 version are only in the RPM tools used 
 to create packages (so SL5 version should be more universal, while SL6 version can require
 a newer rpm software).  

In both cases installation of XUUDB installs both XUUDB Server and XUUDB admin client.

After installing the server you will have to configure it. This is described in the section 
<<server-cfg>>.

Installation from Quickstart package
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Download the quickstart bundle from the UNICORE project website. 

If you use graphical installer follow the on screen instructions and do not forget to
check click the XUUDB checkbox when prompted.

If you use text installer then for generic installation instruction review the 
README file available after extracting the Quickstart bundle. You don't 
have to change any defaults as XUUDB installation is enabled by default.

In both cases you can preconfigure the XUUDB server during installation (of course 
this can be done also later) by choosing the XUUDB server host, port and mode.

Installation from RPM package (RedHat distributions) 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The preferred way is to use Yum  to install (and subsequently update) XUUDB.

To perform the Yum installation, EMI Yum repository must be installed first. 
Refer to the EMI release documentation (available at the EMI website http://www.eu-emi.eu/releases ) 
for detailed instructions. Typically installation of the EMI repository requires to 
download a single RPM file and install it. 

After the EMI repository is configured, the following command installs XUUDB:
 
 $> yum install unicore-xuudb


Installation from the DEB package (Debian distributions) 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	
The preferred installation way is to use apt to install and subsequently update XUUDB.
	 
To perform the apt installation, EMI apt repository must be installed first. 
Refer to the EMI release documentation (available at the EMI website http://www.eu-emi.eu/releases ) 
for detailed instructions. Typically installation of the EMI repository requires to 
download a single DEB file and install it. 

After the EMI repository is configured, the following command installs XUUDB:

 $> apt-get install unicore-xuudb


Upgrade from 1.x version
------------------------

XUUDB 2 introduces a lot of new features and therefore the update form the version 1.x requires 
special attention. In particular:

 * Configuration files format have changed for both +xuudb_server.conf+ and +xuudb_client.conf+
 * New configuration file is required to configure dynamic mappings: +dap-configuration.xml+. 
 * Database schema in case of H2 was extended but also MySQL can be used (and other databases in future).
 
The general update procedure is presented below, with possible variations:

 1. Dump database contents of the 1.x XUUDB using admin client +export+ command.
 2. Stop the 1.x XUUDB server.
 3. Update the server. This step mostly applies for RPM/DEB managed installations. For Quickstart installation
 it is advised to install XUUDB along with other needed components to a separate directory.
 4. Port configuration of 1.x server to the new syntax. It can be done in two ways:
   * Manually by applying all old values to the new template configuration. There are only few properties to be 
   ported so this is not a big task. The advantage of manual porting is that the new template files with new 
   options and updated comments are used. Note: for RPM installations the new files will be named +*.rpmnew+.
   * Automatically, using UNICORE configurator. You have to install the +unicore-configurator+ package. It is included in 
   Quickstart, for distributions install simply run appropriate command: +yum install unicore-configurator+ or 
   +apt-get install unicore-configurator+. Using the configurator you can update the old files automatically:
      ** For RPM/DEB installations it is enough to run +unicore-config-update.py xuudb+. 
      ** For Quickstart put your old configuration files in the folder with the newly installed XUUDB 
      and specify its directory with +-c+ option: +./unicore-config-update.py -c XUUDB_CONFIG_DIR xuudb+.
   Carefully read the output of the program - there can be some problems reported. 
   Option +-h+ provides help, with information about the usage: how to perform dry run, how to recover files 
   from backup etc.
 5. If needed you can update your DB configuration to use MySQL.
 6. Start the newly installed XUUDB.
 7. Verify log file and fix any problems reported.
 8. Use admin client to +import+ the database dump created in the step 1.    

