Java CoG Toolkit FAQ 
====================

0. What License does CoG have?

   The Java CoG Kit is licensed under the Globus Toolkit Public License 
   (http://www.globus.org/toolkit/download/license.html)

   If you would like to use CoG and any software that is built on top of CoG,
   we request that you notify us so we can keep track of the
   usefulness of CoG. This directly affects our funding. Please, be so
   kind to send an e-mail to gregor@mcs.anl.gov with the following
   description:
   
	Project Name:
	Institution:
	Main Contact Person:
	E-mail:
	Web Page:
	Description of your project:

   Furthermore, if your project uses Java CoG Kit, or you use a
   software package that uses Java CoG Kit, we request that you cite
   the following paper in your publications:

	 A Java Commodity Grid Kit, Gregor von Laszewski, 
	 Ian Foster, Jarek Gawor, Peter Lane, 
	 Concurrency and Computation: Practice and Experience, 
	 pages 643-662, Volume 13, Issue 8-9, 2001. 
	 http://www.globus.org/cog/java/

   We also would like to be notified about publications that you write
   while using CoG, as this will help us to document the usefulness of
   CoG.
 
   If you have difficulties with these requirements please contact us.

I. Setup

  1. How do I setup the Java CoG Kit?

	Assuming you have Globus credentials installed locally
	(including a user private key, a user certificate, and trusted
	CA certificates), the Java CoG Kit still needs to be
	configured before any of the tools and libraries can be used.

	The configuration process consists of creating a simple
	configuration file that contains pointers to the locations of
	the Globus credentials.  (See II.4 for details)

	The configuration should not be necessary with Java CoG Kit
	version 0.9.11+ as it is able to automatically detect the
	locations of the Globus credentials. However, this will only
	work if the credentials are placed in the standard Globus
	locations (see question II.9 for details)

	There are a few ways to configure the Java CoG Kit:

	 o using a GUI
	     
            Run the 'setup' script in the bin/ directory. It will run
            a configuration wizard which will prompt you for the
            location of your user certificate, private key, and CA
            certificates.
 
	 o manual
	
	    Create the cog.properties file in the user's home
	    directory under the '.globus' directory. A sample
	    cog.properties file can be found in the etc/
	    directory. (See II.4 for more details on the
	    cog.properties file)

II. General

  1. How do I enable debugging?

	The Java CoG Toolkit uses Log4j (http://jakarta.apache.org/log4j/)
        for debugging. Please see Log4j documentation for configuration
        details. The CoG Kit uses etc/log4j.properties as its configuration
        file for log4j. Also, the Java CoG Kit defines an additional level 
        of debugging called TRACE that is used to log protocol messages, etc.
        To specify TRACE level debugging in the configuration file, set
        level as:

        TRACE#org.globus.util.log4j.CoGLevel

        Example:

        log4j.rootLogger=TRACE#org.globus.util.log4j.CoGLevel, STDOUT
 
  2. Why does the Java CoG Toolkit version of grid-proxy-init echo my
     passphrase to the screen?

	Currently Java does not have a portable way of reading the
	passphrase securely from the console (without echoing it to
	the screen first) Any solution would sacrifice the portability
	of the code.
 
        A GUI front-end to grid-proxy-init is provided and can be used
 	instead to avoid having your passphrase echoed to the screen.

  3. Why do some of the Java CoG tools take several seconds to
     initialize?

	Java must initialize a secure seed for the random number generator
        for security purposes. On some platforms this might be a very
	computationally expensive process. However, the seed for the 
        random number generator only needs to be initialized once per
        JVM instance.

        The Java CoG Kit can be configured to use an arbitrary 
        SecureRandom implementation (which can be optimized for 
        particular platform(s)) by adding the following properties 
	into the cog.properties file:

	random.provider=<Provider class>
	random.algorithm=<algorithm name>

	For example, if you are using the ISNetworks' implementation
	of SecureRandom (http://www.isnetworks.com/infinitemonkey/)
	add the following into the cog.propertis file:

	random.provider=com.isnetworks.provider.random.InfiniteMonkeyProvider
	random.algorithm=InfiniteMonkey

	Of course, you must first install the provider correctly.
	The next time you use CoG tool or library the startup time
	should be faster (on the platforms supported by the provider
	otherwise the default seed generator will be used)

   4. What and where is the cog.properties file?

	The cog.properties file is a configuration file used by the
	Java CoG Toolkit primarily to store the location of the user's
	security credentials.  More specifically, it stores the
	location to the user certificate, user key, CA certificates
	and other miscellaneous configuration information.  This file
	can be configured manually or by using the configuration
	wizard included with the Java CoG Toolkit.

	The file is usually located in the user's home directory under
	the .globus directory.

	For example, the cog.properties file would be located in the
	following location:

	 - on Unix machines:

		~gawor/.globus/cog.properties

	 - on Windows machines (assuming Windows NT):

		c:\winnt\profiles\gawor\.globus\cog.properties

	Note: Windows 95/98 might have a different notion of user home
              directories. [The location of user home directories is
	      determined by the java.home property.]

	In the 0.9.11+ version of the Java CoG Toolkit the
	cog.properties file is not required if everything is located
	in default locations.  If the file exists, the CoG Toolkit
	will use the settings specified in the file. If the file does
	not exist or a required property is not defined in the
	configuration file, the CoG Toolkit will try to find the
	required files in default locations.  Please see question 9
	for details.

  5. How do I specify multiple CA certificates?

	You can specify multiple CA certificates in the cog.properties
	file by setting the 'cacerts' property. The value of the
	property is a list of comma-separated CA certificates or directories
        of certificates. 

	Example:
	  cacert = /home/gawor/MyCaCert.pem, /etc/grid-security/certificates/
 
        If a directory is specified in the list, all certificate files within
        that directory with .<digit> extension will be loaded.

  6. What other things can I set in the cog.properties file?

	In the cog.properties file, you can also specify the ip
	address of your machine in case Java cannot determine the real
	ip address from DHCP. For details on this property please see
	the question 7 below.

	In addition, the tcp port range property can be set to bound
	the range of the port numbers used by the Java CoG
	Toolkit. Please see the question 8 below for details.

  7. Globusrun hangs with interactive jobs.  What do I do?

	This might happen on machines with DHCP enabled or machines
	behind a firewall.  

	Globusrun starts a callback handler (a server) that listens
	for the job state changes on the local machine. Globusrun will
	not terminate until it receives a 'job finish' callback event.

	If you are running behind a firewall, the job might not be
	able to send any state changes back to the callback handler;
	and, therefore, globusrun might wait forever. See question 8
	below for more information about firewall support in the Java
	CoG Toolkit.

	If you are running on a machine with DHCP enabled, the local
	IP address of the machine might be incorrectly detected by
	Java.  Most commonly the IP address detected might be the
	local loop-back address - 127.0.0.1.  To verify that the
	detected IP address is correct, run the globusrun program with
	debugging turned on and see what the IP address if of the
	callback handler (use debug level 3 to see that information)
	If it's incorrect, you can fix it by editing the
	cog.properties file.  Just add the following line:

	    ip=[current ip]

	Examples:

	    ip=64.34.58.128
	    ip=myhost.mydomain.com

        Optionally, you can set the correct ip/hostname of the machine
        by setting the GLOBUS_HOSTNAME system property.

  8. Can the Java CoG Toolkit work behind a firewall? How do I limit the
     range of ports that Java CoG Toolkit will use?

	It is possible to restrict the port numbers that Java CoG
	Toolkit will use.  The port range can be either set by in the
	cog.properties file or through the Java system properties,
	e.g. set from the command line.  To set the port range in the
	configuration file just add the following line:

	   tcp.port.range=<min>,<max>

	Example:

	   tcp.port.range=6000,6060

	To set the port range using the system properties, set the
	"org.globus.tcp.port.range" variable. For example:
	
	   java -Dorg.globus.tcp.port.range="6000,6060" -classpath ...

	Also, Java itself has also built-in SOCKS 4 support. However,
	SOCKS 4 only supports regular sockets but will not work with
	secure sockets.
	
	To enable SOCKS support, you need to set two system properties
	that tell the Java platform your SOCKS host and port number.
	For example:

	  java -DsocksProxyPort=1080 -DsocksProxyHost=socks.mydomain.com 

  9. How does Java CoG find the required files?

	If the configuration file does not exist or a required
	property is not defined in the configuration file, the CoG
	Toolkit will try to find the required files in default
	locations according to the following rules:

	o user certificate ('usercert' property)
	
	   If the 'usercert' property is not set, first the
	   X509_USER_CERT system property is checked. If the system
	   property is not set, the value defaults to
	   ${user.home}/.globus/usercert.pem

        o user private key ('userkey' property)

           If the 'userkey' property is not set, first the
           X509_USER_KEY system property is checked. If the system
           property is not set, the value defaults to
           ${user.home}/.globus/userkey.pem

	o trusted certificates ('cacert' property)

	   If the 'cacert' property is not set, first the
	   X509_CERT_DIR system property is checked. If the system
	   property is not set, then the ${user.home}/.globus/certificates
	   directory is checked. If the directory does not exist, and
	   on a Unix/Linux machine, the
	   /etc/grid-security/certificates directory is checked next.
	   If one of these directories with certificates is found, all
	   the certificates in that directory will be loaded and
	   used. If no directory is found, the Java CoG will not work.

	o proxy file ('proxy' property)

	   If the 'proxy' property is not set, first the
	   X509_USER_PROXY system property is checked. If the system
	   property is not set, then it defaults to a value based on
	   the following rules: If a UID system property is set, and
	   running on a Unix/Linux machine it returns
	   /tmp/x509up_u${UID}. If any other machine then Unix/Linux,
	   it returns ${tempdir}/x509up_u${UID}, where tempdir is a
	   platform-specific temporary directory as indicated by the
	   java.io.tmpdir system property. If a UID system property is
	   not set, the username will be used instead of the UID.
	   That is, it returns ${tempdir}/x509up_u_${username}

 10. What sort of things are not currently supported in Java CoG?

	o DUROC
	   
	   We do not provide a pure Java Duroc API. We implemented the
	   Duroc API through JNI in the past but currently we do not
	   support them. Nevertheless, this version is still
	   distributed in source form. Again, we do not have the
	   resources to support DUROC in native or in pure Java
	   form. If you like to do this, please notify us so we can
	   include your source with a future release of CoG.

	   You can still start a DUROC or MPICH/G job by submitting 
	   the request through a Globus gatekeeper (a GRAM job that
	   starts a DUROC job) You must perform full delegation
	   to accomplish this.

 11. I'm getting following error "java.lang.NoClassDefFoundError: 
     java/security/interfaces/RSAKey." What does it mean and how can I 
     fix it?

	The source code was probably compiled against Java 1.3 compiler
	and is now executed with Java 1.2 interpreter. 
	Java 1.3 contains this interface but Java 1.2 does not. That is,
	the interfaces for the RSA private/public keys have changed 
	between these two Java versions by introduction of the 
	intermediate RSAKey interface in Java 1.3.

	There is no solution or work-around for this problem that we 
	know of. Just make sure to run the 1.3 compiled code with the
	1.3 interpreter. However, the 1.2 compiled code still should
	work with 1.3+ interpreters.

 12. How do I report a bug or contact the Java CoG group?

	To report a bug or request an enhancement, please use our 
	bug tracking system, bugzilla, available at:

        http://bugzilla.globus.org

	To contact the Java CoG group about anything else, please
 	send mail to java@globus.org [Please note, you must
 	be a member of this list to post mail, otherwise your
	message will simply disappear].

III. Security questions

  1. I'm getting following error when connecting to a gatekeeper:
     "Server certificate rejected by ChainVerifier." What does it mean
     and how can I fix it?

        Each time a connection is established with a gatekeeper, the
        client checks if it 'trusts' the server certificate. It does
        that by comparing that the CA certificate of the server
        certificate against the local list of trusted certificates. If
        the certificate is found the server is trusted and connection
        is successfully established.  If not, the server is not
        trusted and above error message returned.  In most cases, it
        means that the client does not have the CA certificate that
        signed the server certificate.  To correct this problem,
        obtain the server CA certificate and add it to the CA
        certificate list in your cog.properties file. See I.5 for
        details on how to do this.  To see the server certificate
        details while connecting to the gatekeeper set the debug level
        to greater then 2. See I.1 for details.
     
  2. I'm getting following error when connecting to a server:
     "Handshake failure." What does it mean and how can I fix it?

     The Java version of grid-proxy-init by default generates
     a GSI-3 style proxy. The GSI-3 style proxies are not 
     compatible with older servers (such as GT 2.2, 2.0). To
     generate a proxy that is compatible with older GT version
     add "-old" argument to the grid-proxy-init command line.

IV. FTP questions

  1. I'm getting following error when I'm trying to transfer a file or
     do a file listing: "425 Can't build data connection: Connection
     refused." What does it mean and how can I fix it?

	In most cases, this error message is related to the presence
	of firewalls. By default, whenever transferring a file or
	doing a file listing, the ftp server will connect to the
	client on the data channel and send the data. If the client is
	behind a firewall this connection might be refused. Because of
	this problem, the ftp servers also support passive mode data
	channels. In this case, the ftp server will be listening for
	the client connection. 

  2. Why does the file listing function not work with my ftp server? 

	The output of the list function in ftp servers depends on the
	operating system and the architecture of the machine that the
	server is running on. Even the same ftp server running on
	various Unix platforms might produce different results. Any
	non-unix ftp server might even produce completely different
	representation.

	The FTP library in the Java CoG is designed to handle the
	following unix-like file list formats:

	-rw-r--r--   1 gawor    globus        528 Nov 23 15:10 Makefile
	and
	-rw-rw-r--   1 globus    117579 Nov 29 13:24 AdGriP.pdf

	Any other file list format will not be parsed and an exception
	will be returned to the user.


V. Binary distribution questions

  1. How do I switch between different version of the Java CoG Kit?

	To switch between the different versions of the Java CoG Kit
	(binary distribution), just set the COG_INSTALL_PATH variable
	to the installation directory of an appropriate Java CoG
	version.  Each version of the Java CoG Kit extracts into a
	separate directory distinguishable by a separate version
	number.

VI. Source code questions

  1. How do I obtain the latest source code to the Java CoG Kit?

	The latest source code for the Java CoG Toolkit can be
	obtained from our CVS pserver.  [Note: This source code may be
	newer than that of the latest released version.]

	To login used the following command:

	cvs -d :pserver:anonymous@cvs.globus.org:/home/dsl/cog/CVS login
	<at password, hit enter>
	 
	Then, to download the entire source use the following command:

	cvs -d :pserver:anonymous@cvs.globus.org:/home/dsl/cog/CVS checkout jglobus

  2. What is Ant and how do I use it to build the Java CoG?

	Ant is a Java based build tool. It allows the CoG Kit to be
	built on multiple platforms without any modifications to the
	build files.
	
        To use ant, you must first download and
	install it on your machine. Ant is available at:
        http://ant.apache.org/

	The latest binary distribution can be downloaded from:
        http://ant.apache.org/bindownload.cgi

	Installation is fairly easy and is described in the ./doc/
	directory in the ant distribution.

	After installing ant, you can try out building CoG by running
	'ant' in the top-most directory of the source code
	tree. (where the build.xml file is located)

	You can also inspect the build.xml file for other possible
	build options.