[[ucc_install]]
Installation and configuration
------------------------------

Prerequisites
~~~~~~~~~~~~~  

To run UCC, you need the Sun/Oracle or OpenJDK Java 6 JRE or SDK (or later). 
If not installed on your system, you can download it from this 
http://java.sun.com[download page].

Download
~~~~~~~~

You can get the latest version from the SourceForge 
http://sourceforge.net/project/showfiles.php?group_id=102081&package_id=263954[UNICORE download page].

Installation and configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To install, unpack the distribution in a directory of your choice. It's a good idea
to add the bin/ directory to your PATH variable,

--------------
export PATH=$PATH:<UCC_HOME>/bin
--------------

where UCC_HOME is the directory you installed UCC in.

[NOTE]
==================
*Windows only* 
Please do not install UCC into a directory containing spaces such 
as "Program files".

Setting environment variables can be done (as administrator) 
using the Control panel->System->Extras panel.
==================

Though you can specify your keystore location and other parameters on the commandline,
it is easiest to place this information in a file, so that you do not have to key in this
information repeatedly.

Preferences file
~~~~~~~~~~~~~~~~

UCC checks by default whether the file <userhome>/.ucc/preferences exists, and reads it.
To specify keystore, password and your preferred UNICORE 6 registry URL,
the file should look as follows.
  
--------------
credential.path=<your keystore>
credential.password=<your password>
truststore.type=keystore
truststore.keystorePath=<your keystore>
truststore.keystorePassword=<your password>
client.serverHostnameChecking=NONE

registry=<your registry>
--------------


[NOTE]
=================
If you are worried about security, and do not want specify the password: UCC will ask for it if it
is not given in the preferences or on the commandline.
==================

[NOTE]
==================
*Windows only* 
The preferences are usually searched in the "c:\Documents and Settings\<user_name>\.ucc" 
folder.

To create the .ucc folder, you might have to use the 
command prompt "mkdir" command. 

When specifying paths in the preferences file, the backslash '\' 
character needs to be written using an extra backslash '\\'
==================

For example, if you are using a local UNICORE 6 installation for 
testing, you could use

--------------
registry=https://localhost:8080/DEMO-SITE/services/Registry?res=default_registry
--------------

[NOTE]
====================
If you wish to change the default property file location, you can
set a Java VM property in the UCC start script, for example by editing the command
that starts UCC

--------------
java .... -Ducc.preferences=<preferences location> ....
--------------

=====================


Security
~~~~~~~~

UCC supports many keystore/truststore options.
You need a <<keystore>> that contains your user certificate and private key,
and you need to setup the certificate(s) of the certificate authorities that you trust. 
The trusted certificates can reside in a Java keystore file in jks format, or in a directory in .pem 
format. Please refer to 'ucc help-auth' for full information.

Here is a configuration example.

--------------
credential.path=<your keystore>
credential.password=<your password>
truststore.type=keystore
truststore.keystorePath=<your keystore>
truststore.keystorePassword=<your password>
client.serverHostnameChecking=NONE
--------------

Logging
~~~~~~~

UCC writes some messages to the console, more if you choose the verbose mode (-v option). If
you need real logging (e.g. when using the batch mode), you can edit the <UCC_HOME>/conf/logging.properties
file, which configures the Log4J logging infrastructure used in UNICORE.
  
Installing UCC extensions
~~~~~~~~~~~~~~~~~~~~~~~~~

UCC can be extended with additional commands. It is enough
to copy the libraries (.jar files) of the extension into a directory
that is scanned by UCC: in general these are the UCC +lib+
and the +${HOME}/.ucc/lib+ directory. 


Testing the installation
~~~~~~~~~~~~~~~~~~~~~~~~ 

To test your UCC installation and to get information about the resources on the Grid you're connecting
to, do

--------------
  ucc system-info -l -v
--------------



