UNICORE Files

**
** UNICORE Spaces
**

This is a JavaSpace-inspired component that stores XML documents in a 
shared "space", modelling each entry as a WS-Resource.

Operations available on the space are
 - write() : write an XML document to the space
 - read()  : read a document, using a XML template as query
 - take()  : read and remove a document from the space, 
             again using an XML template

A client operation "space" for UCC is provided that allows to store and
retrieve documents, optionally signing them and checking the existence and
validity of signatures.

An example application is provided that uses the Space as a shared job 
queue for high-throughput processing using a set of UNICORE sites.
A UCC command "space-batch" allows to batch process jobs, similar to the
usual UCC "batch" command.


The component is installed as an extension to a UNICORE/X server.

**
** Installation:
**

Prerequisites:
**************
Java 6 or later
UNICORE server version 6.4.2 or later,
UCC version 6.4.2

Space service:
*************

The Space service needs to be deployed into a UNICORE/X instance.

Ideally (for optimum performance), you should set up a dedicated 
UNICORE/X instance which does not run the usual UNICORE services, 
but only the new space services and the local registry.

There are two services, a plain web service "Space" that offers the read(),
write() and take() operations and a second, WSRF, service "SpaceEntry" that
holds the entries in the space. To install,

1) place the jar files from the UNICORE Spaces distribution into 
the UNICORE/X lib directory.
 
2) add the following to wsrflite.xml
 <!-- SPACE SERVICES -->
   <service name="Space" wsrf="false">
     <interface class="de.fzj.unicore.spaces.Space" />  
     <implementation class="de.fzj.unicore.spaces.SpaceImpl"/>
   </service>
   <service name="SpaceEntry" wsrf="true" persistent="true">
     <interface class="de.fzj.unicore.spaces.SpaceEntry" />  
     <implementation class="de.fzj.unicore.spaces.SpaceEntryHomeImpl"/>
   </service>
   
3) the Space is initialised and published to the registry
by adding an entry to the uas.config property "uas.onstartup":

#setup space
uas.onstartup.NN=de.fzj.unicore.spaces.util.PublishSpace

4) optionally enable access control on the space entries, for details see
section "Security Considerations" below

  unicore.spaces.accesscontrol=true

By default the Space service will grant access to other servers. To disallow 
other services (for example execution sites) from accessing space entries, you 
may set addionally:

  unicore.spaces.accesscontrol.services=true

5) It is possible to retrieve more than a single entry using the read() or take() 
operations. By default, a maximum of 10 results are retrieved. To change this default 
server-side limit, set

  unicore.spaces.bulklimite=NNN

where 'NNN' is the desired limit.

UCC extension commands
**********************

Place the jar files from the UNICORE Spaces distribution into the ucc/lib directory.

This will extend UCC with two additional commands:

 - the "space" command provides the general XML Space operations write, read and take.
 - the "space-batch" command is used for high-throughput job processing similar to the 
   usual UCC batch command. See "ucc <command> -h" for more usage information.

**
** Sample application: High-throughput job execution
**

As sample application, we provide a job execution system aimed at high-throughput
computing. It works as follows.

 - clients submit their jobs to the space (marked "NEW")
 
 - workers at the target system retrieve jobs from the space and execute them locally.
 
 - the worker writes the job back to the space, these jobs are marked "SUBMITTED", 
   and have the job EPR attached.
 - when done, the the worker writes the job entry to the space marked "DONE"
 
 - clients periodically check the space for any DONE jobs and retrieve them.

Not all types of jobs are suitable for this kind of processing. If you need to
stage in files from the local machine, or want to stage out files to the local
machine, this will not be possible. All data should be staged to/from other UNICORE 
servers. 

Setup
*****

Workers can be deployed on a UNICORE/X server by adding some properties to
uas.config:

# setup job application
uas.onstartup= .... \
de.fzj.unicore.spaces.job.SetupJobTaker

#
# configure job takers
# (changing this will require a restart)
#

# how many jobtakers (changing this will require a restart)
unicore.spaces.jobtaker.number=2

# how often should they run (milliseconds)
unicore.spaces.jobtaker.updatePeriod=200

# initial run delay (milliseconds)
unicore.spaces.jobtaker.initialDelay=200

# limit on concurrently running jobs for each job taker
unicore.spaces.jobtaker.concurrentJobs=10;

# how many jobs to take from the space in one run of the JobTaker
# this will influence how fast jobs are submitted into the batch queues
# setting it large will drain jobs from the space faster, but jobs will
# take longer to actually get submitted  
unicore.spaces.jobtaker.batchSize=10;

# require valid trust delegation from client? (defaults to true)
unicore.spaces.jobtaker.requireDelegation=true

# check signatures? (defaults to false)
unicore.spaces.jobtaker.secureMode=false

# job takers active (can be used to disable/enable at runtime without
# having to restart UNICORE/X)
unicore.spaces.jobtaker.active=true

Hints
*****
To get maximum throughput, you should tune the number of workers and the 
maximum number of concurrent jobs to the capabilities of your compute 
cluster. A reasonable starting point would be to aim for a maximum 
of 100-200 jobs per JobTaker, and one job per available compute node.


Security Considerations
***********************

Jobs are executed under the real user ID of the client, by using SAML
trust delegation. The usual UNICORE authorisation (e.g. the XUUDB) is used
to retrieve the correct xlogin from the user's certificate.

If you want to prevent users from accessing entries that are not their
own, you can enable access control on the space entries. To do so, edit the 
unicorex/conf/uas.config file on the server running the Space service, and set

  unicore.spaces.accesscontrol=true

The usual UNICORE security applies, which means that the XACML security policy has to
allow access. By default, this means that just the owner of each Space entry can
read or take it.

To simplify applications, access by other servers (that are listed in the registry) 
is allowed by default. If you want to control which services are allowed to access the
space, you need to set additionally:

  unicore.spaces.accesscontrol.services=true

In this case, all servers that want to access the space need to be listed in the XUUDB (or
any other attribute source that is configured for the Space server), and the security 
policy of the Space server needs to be adapted. For example, you might
assign the role "server" to each allowed server in the XUUDB:

  bin/admin.sh add <SPACE-GCID> <SERVER-PEM> nobody server


where <SPACE-GCID> is the GCID used for the Space server and <SERVER-PEM> is the server's 
public key. This will assign the required role (together with the xlogin "nobody").


The XACML security policy of the Space server finally needs to be extended.
If you are using XACML2.0 (default since 6.4.0), you can find a policy file in the 
conf/xacml2Policies folder in the distribution. Simply copy this file into the
conf/xacml2Policies folder of your Space server installation.

After copying the file, issue the command 'touch conf/xacml2.config' to update the
configuration.

Credits:
********
The original prototype was implemented in a diploma thesis by Miriam Schumacher
at Forschungszentrum Juelich :
"Realisierung eines XML-Tupelraumes unter Verwendung des Web Service Resource Framework",
FH Aachen/Juelich, February 2008
A paper on this work is available:

  Schuller, B.; Schumacher, M.
  Space-Based Approach to High-Throughput Computations in UNICORE 6 Grids
  in: Proceedings of 4th UNICORE Summit 2008 
  Springer LNCS 5415, Euro-Par 2008 Workshops: Parallel Processing, pp 75 - 83


Contact:
********

For more information and support contact unicore-support@lists.sf.net or directly 
the developer Bernd Schuller (bschuller@users.sourceforge.net)