Software Links
Getting Started
- Doc Structure
- A Globus Primer
- Quickstart
- Installing GT
- Platform Notes
- Migrating from GT2
- Migrating from GT3
Reference
- PDF version
- Best Practices
- Coding Guidelines
- API docs
- Public Interfaces
- Resource Properties
- Samples
- Glossary
- Index
- Performance Studies
Common Runtime
Security
Data Mgt
Information Svcs
Execution Mgt
Table of Contents
This guide contains advanced configuration information for system administrators working with WS RLS. It provides references to information on procedures typically performed by system administrators, including installation, configuring, deploying, and testing the installation.
![[Important]](/docbook-images/important.gif) | Important |
|---|---|
This information is in addition to the basic Globus Toolkit prerequisite, overview, installation, security configuration instructions in the GT 4.1.0 System Administrator's Guide. Read through this guide before continuing! |
WS RLS is distributed with the Globus Toolkit 4.1.0 and is available in both the binary bundles and the source bundle. For most purposes, the binary bundle provides the simplest means of installing the WS RLS and its requirements. There are three typical ways to access and install the WS RLS:
| Important |
|---|---|
Before proceding with installation of WS RLS, please familiarize yourself with the installation procedures for RLS (see GT 4.1.0 RLS). |
Follow instructions provided by GT 4.1.0 System Administrator's Guide and Installing GT 4.1.0 in order to install the WS RLS from one of the available binary bundles of the Globus Toolkit.
Once you have unpackaged the binary bundle, the following commands may be used to install WS RLS:
% ./configure --prefix=$GLOBUS_LOCATION --enable-rls --enable-wsrls
% make
% make install
WS RLS is not installed as part of the default source install. In order to install WS RLS, you will need to ensure that RLS is also installed as part of the build by reviewing its installation procedures. Along with RLS configure settings (e.g., ODBC related settings) the --enable-wsrls flag is required as part of the configuration step.
The following commands will install the WS RLS (optionally you may use the "gt4-wsrls" make target to build only WS RLS and its requirements:
% ./configure --prefix=/path/to/install --with-iodbc-includes=/path/to/iodbc/include --with-iodbc-libs=/path/to/iodbc/lib --enable-rls --enable-wsrls % make [[rls] gt4-wsrls] % make install
Additionally, you may access the WS RLS from the Globus Toolkit CVS repository. You may deploy the 4.1.x WS RLS on top of an existing GT 4.1.x installation using trunk.
| Important |
|---|---|
Please review Accessing the Globus Alliance's Code via CVS for the authoratative information on building and installing the Globus Toolkit from source in our CVS. |
The following instructions may be used to build and install the WS RLS:
setenv CVSROOT :pserver:anonymous@cvs.globus.org:/home/globdev/CVS/globus-packages cvs co packaging/ cd packaging ./make-packages.pl --bundles=gt4-wsrls --deps [--verbose] setenv GPT_LOCATION /path/to/packaging/gpt-3.2globus2 $GPT_LOCATION/sbin/gpt-build [-verbose] ./bundle-output/custom-deps-1.0-src_bundle.tar.gz gcc32dbgpthr
![[Note]](/docbook-images/note.gif) | Note |
|---|---|
Changes to the toolkit (WS Core and WSAA) made between the 4.0.x release and the latest code base, make the GT 4.0.x build environment unsuitable for GT 4.1.0 components. As such the WS RLS cannot be deployed on an existing GT 4.0.x installation. The good news, if you will, is that the WS RLS can use your existing GT 4.0.x RLS without modification. If you have an existing RLS installation, and you want to try out the WS RLS interface layer, you need not reinstall RLS. Of course, you may want to reinstall RLS exclusively for testing with the WS RLS interface, but it is up to your own choosing. |
The WS RLS requires certain WSDD and JNDI settings to be properly configured. The installed JNDI configuration file may be found at $GLOBUS_LOCATION/etc/globus_wsrf_replicalocation_resource/jndi-config.xml. To view the default JNDI file (current snapshot) from the Globus CVS repository click here. The installed WSDD configuration file may be found at $GLOBUS_LOCATION/etc/globus_wsrf_replicalocation_service/server-config.wsdd. To view the default WSDD file (current snapshot) from the Globus CVS repository click here. In most cases, you will not need to alter either of these files.
This information is in addition to the basic configuration instructions in the GT System Administrator's Guide.
The WS RLS's WSDD determines which services will be activated by the GT Java WS Core container. By default, the WS RLS defines two services.
ReplicaLocationCatalogService. The
ReplicaLocationCatalogServiceservice provides the WS interface to the RLS Local Replica Catalog capabilities. If you intend to activate this service, you need not alter the WSDD. If you do not wish to activate this service, simply remove it from the WSDD and restart the container.... <service name="ReplicaLocationCatalogService" provider="Handler". use="literal" style="document"> ... </service> ...ReplicaLocationIndexService. The
ReplicaLocationIndexServiceservice provides the WS interface to the RLS Replica Location Index capabilities. If you intend to activate this service, you need not alter the WSDD. If you do not wish to activate this service, simply remove it from the WSDD and restart the container.... <service name="ReplicaLocationIndexService" provider="Handler". use="literal" style="document"> ... </service> ...
The WS RLS's JNDI configuration determines the resource class to be used for each service defined by the WS RLS WSDD. It also determines other critical settings used by these resources. In this file, you will find settings for the two default services defined in the WSDD.
Each service has a JNDI Resource of name RLSConnectionSource. This JNDI Resource is used by the WS RLS service to open a connection to the backend RLS service. In many cases, you may find that the default settings require no modification for your setup. The url parameter sets the endpoint for the backend RLS. The certfile and keyfile parameters set the certificate and key files to be used by the WS RLS to communicate securely with the backend RLS.
You will notice that the default settings use the container's suggested certificate and key file paths. If you have chosen different paths in which to keep these files, please adjust the settings accordingly. At present, the WS RLS uses a single identity (defined by the certificate and key) to authenticate itself with the RLS in order to perform any user requested operations. When the WS RLS interface is finalized, it will most likely use a different approach to authentication between WS RLS and the back end RLS. At this time, we expect that the interface will change such that the caller's credentials will be used to make calls between the WS RLS and the back end RLS on behalf of the originating caller.
...
<resource
name="RLSConnectionSource"
type="org.globus.replica.rls.connection.impl.PooledRLSConnectionSource">
<resourceParams>
<parameter>
<name>factory</name>
<value>org.globus.wsrf.jndi.BeanFactory</value>
</parameter>
<parameter>
<name>url</name>
<value>rls://localhost</value>
</parameter>
<parameter>
<name>certfile</name>
<value>/etc/grid-security/containercert.pem</value>
</parameter>
<parameter>
<name>keyfile</name>
<value>/etc/grid-security/containerkey.pem</value>
</parameter>
</resourceParams>
</resource>
...
Security recommendations include:
The following paragraph describes our INITIAL IMPLEMENTATION in this first look of the WS RLS interface -- THIS IS NOT INTENDED TO BE A FINAL SOLUTION.
Users of the WS RLS authenticate themselves to the WS RLS in the usual manner based on their credential. The WS RLS uses the WSAA and Authorization Framework to make authorization decisions. Then, the WS RLS uses a single certificate and key file to identify itself to the RLS irregardless of the user accessing the WS RLS. Thus users that can access the WS RLS are given the fixed WS RLS identity to access the RLS. Users accustomed to using RLS may not feel comfortable with this approach -- if it may be an issue for your environment, we suggest that you not use it with your production RLS. If you think of WS RLS as the gating interface to the RLS, as you should, then you should apply the appropriate authorization restrictions at the WS RLS level, which can be done using WSAA. This will in effect achieve a level of authorization similar to that of the RLS.
Increasing log verbosity
Generating verbose log output is a critical aid in troubleshooting of the WS RLS and is useful when communicating problems to Globus support lists. To increase logging detail, add the following lines to the $GLOBUS_LOCATION/container-log4j.properties file.
... log4j.category.org.globus.replica.location=DEBUG log4j.category.org.globus.replica.rls=DEBUG ...Error: java.lang.NullPointerException
When invoking the WS RLS command-line clients, a system-level exception like the one above may be encountered. The admin should check the container logs for the exact error.
Error: A server error occured while processing the request.
When invoking the WS RLS command-line clients, a server error like the one above may be encountered. The admin should check the container logs for the exact error.
java.lang.UnsatisfiedLinkError
... Unexpected error during request processing java.lang.UnsatisfiedLinkError: init at org.globus.replica.rls.RLSClient.init(Native Method) ...An
java.lang.UnsatisfiedLinkErrorexception when using the WS RLS may indicate that the native RLS libraries that WS RLS depends on could not be located. To correct this problem, ensure that the$GLOBUS_LOCATION/libdirectory is in the library search path (on some systems this is theLD_LIBRARY_PATHvariable).Unable to connect to localhost:39281
... Error: java.rmi.RemoteException: globus_rls_client: Globus I/O error: globus_xio: Unable to connect to localhost:39281; nested exception is: org.globus.replica.location.CatalogInternalException: globus_rls_client: Globus I/O error: globus_xio: Unable to connect to localhost:39281 ...The WS RLS is an interface layer that depends on the RLS for the replica location functionality. You must install and run RLS and configure WS RLS to use the RLS via its JNDI configuration. Check that RLS is installed, running, and check that the WS RLS JNDI configuration uses the correct hostname and port to connect to the RLS.
org.globus.common.ChainedIOException: Failed to initialize security context
An
org.globus.common.ChainedIOExceptionexception when using the WS RLS may indicate that the user's proxy is invalid.... Error: ; nested exception is: org.globus.common.ChainedIOException: Failed to initialize security context [Caused by: Defective credential detected [Caused by: Proxy file (/tmp/x509up_u1234) not found.]] ...To correct the error, the user must properly initialize the user proxy. See
grid-proxy-initfor more information on proxy initialization.Error: org.xml.sax.SAXException: Unregistered type: class org.globus.replica.location.generated.ObjectEnumerationType
An
org.xml.sax.SAXException: Unregistered type: class XXXexception when using the WS RLS may indicate that an Axis generated XML type, defined by the WS RLS XSD, was not properly registered. While all the XML types should get registered upon deployment without intervention by the user, sometimes they do not. To remedy the situation add atypeMappingto the$GLOBUS_LOCATION/etc/globus_wsrf_replicalocation_service/server-config.wsddfile. Note that this exception is not limited to theorg.globus.replica.location.generated.ObjectEnumerationTypetype.... <typeMapping. encodingStyle="". qname="ns1:ObjectEnumerationType". deserializer="org.apache.axis.encoding.ser.SimpleDeserializerFactory". serializer="org.apache.axis.encoding.ser.SimpleSerializerFactory" type="java:org.globus.replica.location.generated.ObjectEnumerationType" xmlns:ns1="http://www.globus.org/namespaces/2005/08/replica/location" /> ...
The WS RLS does not collect usage statistics in addition to what the RLS collects. Please consult the RLS documentation to familiarize yourself with usage statistics collected by it.
Also, please see our policy statement on the collection of usage statistics.