Note: Please make sure to have the JAAS library installed if running with J2SE 1.3.1.

Java WS Core provides per- gar configuration and supports configuration profiles. The configuration information of a service is mainly encapsulated in two separate configuration files:

A service that support security might also have the security-config.xml (security deployment descriptor) file. Please see the Security Descriptor page in the GT4 WS Authorization Framework documentation for details.

All these configuration files are dropped into the $GLOBUS_LOCATION/etc/<gar.id>/ directory during the deployment process.

The standalone Java WS Core container can be started and stopped with the provided globus-start-container and globus-stop-container programs. There are also helper programs (available only with the full GT installation) to start and stop the container detached from the controlling terminal (globus-start-container-detached and globus-stop-container-detached). These commands are documented in the Java WS Core Command Reference.

 $ setenv GLOBUS_OPTIONS -Xmx512M
 $ $GLOBUS_LOCATION/bin/globus-start-container

To deploy a Java WS Core installation into Tomcat run:

$ cd $GLOBUS_LOCATION
$ ant -f share/globus_wsrf_common/tomcat/tomcat.xml deploySecureTomcat -Dtomcat.dir=<tomcat.dir>

Where <tomcat.dir> is an absolute path to the Tomcat installation directory. Also, -Dwebapp.name=<name> can be specified to set the name of the web application under which the installation will be deployed. By default "wsrf" web application name is used.

The deploySecureTomcat task will update an existing Tomcat deployment if Java WS Core was already deployed under the specified web application name. The redeploySecureTomcat task can be used instead to overwrite the existing deployment.

	Note
	Please note that during deployment a subset of the files from Java WS Core installation is copied into Tomcat. Also, the copied files in Tomcat might have different permissions then the originals.

In addition to the above deployment step you will also need to modify the Tomcat <tomcat_root>/conf/server.xml configuration file. In particular you will need to add the following configuration entries:

Also, you may have to edit <tomcat.dir>/webapps/wsrf/WEB-INF/web.xml if you are running Tomcat on a non-default port, i.e. not using port 8443 (HTTPS). For example, if you run Tomcat on port 443 using HTTPS then the WSRF servlet entry should be modified as follows:

<web-app>
...
    <servlet>
        <servlet-name>WSRFServlet</servlet-name>
        <display-name>WSRF Container Servlet</display-name>
        <servlet-class>
            org.globus.wsrf.container.AxisServlet
        </servlet-class>
        <init-param>
            <param-name>defaultProtocol</param-name>
            <param-value>https</param-value>
        </init-param> 
        <init-param>
            <param-name>defaultPort</param-name>
            <param-value>443</param-value>
        </init-param>   
        <load-on-startup>true</load-on-startup> 
    </servlet>
...
</web-app>

	Note
	We recommend running Tomcat with Java 1.4.2+.

 > cd <tomcat.dir>
 > set CLASSPATH=<tomcat.dir>\common\lib\axis-url.jar
 > bin\startup

 $ cd <tomcat.dir>
 $ setenv CLASSPATH <tomcat.dir>/common/lib/axis-url.jar
 $ bin/startup

 $ cd $GLOBUS_LOCATION
 $ ant -f share/globus_wsrf_common/tomcat/tomcat.xml war -Dwar.file=<war.file>

4.2.4. Deploying and undeploying services

To deploy a service into Tomcat, first deploy the service into a regular GT installation using the globus-deploy-gar tool and then deploy the GT installation into Tomcat (as described in Section 4, “Deploying”). Similarly, to undeploy a service, first undeploy the service from a regular GT installation using globus-undeploy-gar tool and then deploy the GT installation into Tomcat.

	Note
	Some GT services may not work properly in Tomcat.

The service configuration files such as jndi-config.xml or server-config.wsdd (located under $GLOBUS_LOCATION/etc/<gar>/ directory) may contain private information such as database passwords, etc. Ensure that these configuration files are only readable by the user that is running the container. The deployment process automatically sets the permissions of the jndi-config.xml and server-config.wsdd files as user readable only. However, this might not work correctly on all platforms and this does not apply to any other configuration files.

The services using subscription persistence API or other basic persistence helper API will store all or part of its persistent data under the ~/.globus/persisted directory. Ensure that the entire ~/.globus/persisted directory is only readable by the user running the container.

A client can potentially invoke a service function that is not formally defined in the WSDL but it is defined in the service implementation class. There are two ways to prevent this from happening:

By default globus-stop-container must be executed with the same credentials as the container it is running with. If the ShutdownService or the container is configured with separate private key and certificate files (usually /etc/grid-security/containercert.pem and /etc/grid-security/containerkey.pem) do the following to stop the container:

 $ grid-proxy-init -cert /etc/grid-security/containercert.pem \
                   -key /etc/grid-security/containerkey.pem \
                   -out containerproxy.pem
 $ setenv X509_USER_PROXY containerproxy.pem
 $ globus-stop-container
 $ unsetenv X509_USER_PROXY
 $ rm containerproxy.pem

Alternatively, the ShutdownService can be configured with a separate gridmap file to allow a set of users to stop the container. Please see the WS Authentication & Authorization section for details.

By default Sun 1.4.x+ JVMs are configured to use /dev/random device as an entropy source. Sometimes the machine can run out of entropy and applications (such as the container) using the /dev/random device will block until more entropy is available. One workaround for this issue is to configure the JVM to use /dev/urandom (non-blocking) device instead. For Sun JVMs a java.security.egd system property can be set to configure a different entropy source. To set the system property and pass it to globus-start-container script do the following:

 export GLOBUS_OPTIONS=-Djava.security.egd=file:/dev/urandom

or

 setenv GLOBUS_OPTIONS -Djava.security.egd=file:/dev/urandom

The same issue can also affect client programs. If you are running a client program with a GT generated script, you can set the GLOBUS_OPTIONS environment property as described above. However, if you are using a custom script or directly launching a program using the java command line, make sure to set the java.security.egd system property explicitly on the java command line. For example:

 java -classpath $CLASSPATH -Djava.security.egd=file:/dev/urandom my.package.FooProgram

Note: This does not apply to Windows machines.

These errors might occur when running with J2SE 1.3.1 and the JAAS library is not installed. Either install the JAAS library or upgrade to J2SE 1.4.x or higher.

If the following exception is visible in the Tomcat logs at startup it might cause the HTTPSValve to fail:

java.util.ConcurrentModificationException
	at java.util.HashMap$HashIterator.nextEntry(HashMap.java:782)
	at java.util.HashMap$EntryIterator.next(HashMap.java:824)
	at java.util.HashMap.putAllForCreate(HashMap.java:424)
	at java.util.HashMap.clone(HashMap.java:656)
	at mx4j.server.DefaultMBeanRepository.clone(DefaultMBeanRepository.java:56)

The HTTPSValve might fail with the following exception:

java.lang.NullPointerException
	at org.apache.coyote.tomcat5.CoyoteRequest.setAttribute(CoyoteRequest.java:1472)
	at org.apache.coyote.tomcat5.CoyoteRequestFacade.setAttribute(CoyoteRequestFacade.java:351)
	at org.globus.tomcat.coyote.valves.HTTPSValve.expose(HTTPSValve.java:99)

These exceptions will prevent the transport security to work properly in Tomcat.

This is a Tomcat bug. Keep restarting Tomcat until it starts without the ConcurrentModificationException or switch to a different version of Tomcat.

If you see the "java.net.SocketException: Invalid argument or cannot assign requested address" error in the container log or on the client side try setting the following property:

 $ export GLOBUS_OPTIONS="-Djava.net.preferIPv4Stack=true"

In general, if you want to investigate a problem on your own please see the Debugging and Logging section for details on how to turn on debugging. Also, please note that most of the command line clients have a -debug option that will display more detailed error messages, including the error stack traces. Also, searching the mailing lists such as [email protected] or [email protected] (before posting a message) can also be very fruitful. Finally, if you think you have found a bug please report it in our Bugzilla system. Please include as much as detail about the problem as possible.