Introduction
------------

This package called 'uvos-client' contains client side libraries and a 
command line application (CLC) for accessing UVOS Server. 

For a general introduction of UVOS please refer to its website: http://uvos.chemomentum.org
	
A complete overview of the UVOS is available in the initial chapters of the "UVOS Server manual"
available there.


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

UVOS Client is distributed in the following formats:

 1. As a platform independent archive.
 2. As a binary, platform-specific package, available currently for Scientific Linux 5,
 Scientific Linux 6 and Debian 6 platforms. The 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).  

Depending on the installation source used, installation method and paths after installation 
are different. In case of platform-specific packages, the default configuration 
of the client is placed in +/etc/unicore/uvos-clc/uvosClient.conf+
Upon a first start of the client it will be copied to +.uvos-clc/+ folder in 
your home directory. You should edit it there (see xref:configuration[Configuration] for details). 
The executable program is called +uvos-clc+.


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

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

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 UVOS Client:
 
 $> yum install unicore-uvos-clc


Installation from the DEB package (Debian distributions) 
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	
The preferred installation way is to use apt to install and subsequently update UVOS Client.
	 
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 UVOS Client:

 $> apt-get install unicore-uvos-clc


Installation from the archive
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

If installing using a portable archive:

 1. Download the uvos-client archive from the UNICORE download site and unpack it.
 2. The default configuration of the client is placed in +conf/uvosClient.conf+
 You should edit it there (see xref:configuration[Configuration] for details). 
 The program can be found in the +bin/+ subdirectory and is called +uvoscmd.sh+


Using the command line UVOS client
----------------------------------

UVOS Command Line Client can operate in batch or interactive mode. Invoking it without
arguments provides you with usage instructions. When invoking UVOS CLC user must select 
one of the available commands and provide arguments for it. 

UVOS CLC offers a built in help system: it allows you to list all commands and get
help on each of them. The following command outputs help for the operation +addIdentity+ 
(assuming you are invoked UVOS CLC in interactive mode, similarly you can invoke it in 
batch mode):

 help addIdentity

Note that in interactive mode in order to pass arguments which contain spaces
you should surround them with double quotes "like this". 

The command line client uses a configuration file to get information about:

 - UVOS server address.
 - How to authenticate to the server.
 - Trusted certificates for TLS connection.
 
See xref:configuration[Configuration] for details. 


Using other available clients
-----------------------------

Other clients which are available in this package are usually not useful for 
UVOS users. The sole exception is SAMLSelfClient. 
This program gets all attributes which are defined for the identity making the
call (i.e. this one which is set in client's configuration file).

The 'WebClient' program serves as an example for developers only so you can 
ignore it.


Developing with uvos-client
---------------------------

If you intend to use this package as a library please refer to the JavaDocs documentation
(it is available from the download site, and from the documentation site which is preferred, 
the most accurate source). Remember that there are two VO APIs implemented by this library:

 - *SAML API* It uses SAML 2.0 and so is standard-complaint, can be used to access 
 any version of UVOS server and possibly other SAML services. However it offers only 
 a read-only access. If you can then use use this API. It is included in the 
 package: pl.edu.icm.unicore.uvos.wsclient.samlapi
 - *UVOS API* It uses an own UVOS web services interface. It is not guaranteed
 that using this API will work perfectly with older UVOS server releases (however 
 most of fundamental functions should work). Also this API in not standards 
 complaint. On the other hand it allows you to use all UVOS features. 
 It is included in the package: pl.edu.icm.unicore.uvos.wsclient.api

Also note that if intend to simply add UVOS support for your XFire or WSRFLite or UAS 
service then you should use xfire-voutils or uas-authz packages which provides a
ready to use solution for such cases. 

For additional information please contact UVOS or UNICORE developers at: 
unicore-devel@lists.sourceforge.net
