Introduction
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 Installing GT 4.2.1. Read through this guide before continuing! |
Table of Contents
Table of Contents
WS RLS is distributed with the Globus Toolkit 4.2.1 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 Replica Location Service (RLS)). |
Follow instructions provided by Installing GT 4.2.1 and Installing GT 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 --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.2.1 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. |
Table of Contents
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 Installing GT 4.2.1.
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>
...
Table of Contents
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.
Table of Contents
The following information is from Java WS Core, on which WS RLS is based.
The following information applies to Java WS Core and all services built on Java WS Core.
Java WS Core server side has two types of loggers. One logger is used for development logging and by default writes to standard out. The other logger includes system administration information and is CEDPs best practices compliant.
On client side, only developer logging is available and is configured using log4j.properties.
The following information applies to Java WS Core and those services built on it.
Logging in the Java WS Core is based on the Jakarta Commons Logging API. Commons Logging provides a consistent interface for instrumenting source code while at the same time allowing the user to plug-in a different logging implementation. Currently we use Log4j as a logging implementation. Log4j uses a separate configuration file to configure itself. Please see Log4j documentation for details on the configuration file format.
Server side logging can be configured in $GLOBUS_LOCATION/container-log4j.properties, when the container is stand alone container. For tomcat level logging, refer to Logging for Tomcat, . The logger log4j.appender.A1 is used for developer logging and by default writes output to the system output. By default it is set for all warnings in the Globus Toolkit package to be displayed.
Additional logging can be enabled for a package by adding a new line to the configuration file. Example:
#for debug level logging from org.globus.package.FooClass log4j.category.org.globus.package.name.FooClass=DEBUG #for warnings from org.some.warn.package log4j.category.org.some.warn.package=WARN
Client side logging can be configured in $GLOBUS_LOCATION/log4j.properties. The logger log4j.appender.A1 is used for developer logging and by default writes output to the system output. By default it is set for all warnings in the Globus Toolkit package to be displayed.
The specific logger to edit will be
log4j.logger.sysadmin in
$GLOBUS_LOCATION/container-log4j.properties. There
you can configure the following properties:
log4j.appender.infoCategory=org.apache.log4j.RollingFileAppender log4j.appender.infoCategory.Threshold=INFO log4j.appender.infoCategory.File=var/containerLog log4j.appender.infoCategory.MaxFileSize=10MB log4j.appender.infoCategory.MaxBackupIndex=2
Above implies the logging file is rolling with each file size
limited to 10MB and the logging information is stored in
$GLOBUS_LOCATION/var/containerLog.
The sample log file contains many log entries for various scenarios in the Java WS container.
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 ...
Table of Contents
For sys admin debugging information, see Chapter 5, Debugging.
For a list of common errors in GT, see Error Codes.
Table 6.1. WS Replica Location Service (WS RLS) Errors
| Error Code | Definition | Possible Solutions |
|---|---|---|
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 | This exception 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/lib directory is in the library search path (on some systems this is the LD_LIBRARY_PATH variable).
|
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 | If this exception occurs while using WS RLS, it may indicate that the user's proxy is invalid. | To correct the error, the user must properly initialize the user proxy. See grid-proxy-init for more information on proxy initialization. |
Error: org.xml.sax.SAXException: Unregistered type: class xxx | If this exception occurs when using the WS RLS, it 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 a typeMapping to the server-config.wsdd file under globus_wsrf_replicalocation_service.
Use the format shown here.
|
Table of Contents
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.
E
- errors, Troubleshooting, Errors
I
- installing
- from binary, Installing WS RLS using Globus Toolkit Binary Bundle
- from CVS, Installing WS RLS using Globus CVS
- from source, Installing WS RLS using Globus Toolkit Source Bundle
L
- logging, Debugging
U
- usage statistics, Usage statistics collection by the Globus Alliance