JClarens Installation Guide

Prerequisites

The only prerequisite for installing/running JClarens is the Java development Kit 1.4.2 and above.

If you do NOT wish to install JClarens using the JClarens installer executable, the JClarens RPM or the jclarens-full zip file, then Jakarta Tomcat 5.0.28 and above is also required.

Procedure

Installing JClarens from the VDT

Installing JClarens using the JClarens RPM /install package:

Linux Installation:

1. Download the JClarens RPM from http://sourceforge.net/project/showfiles.php?group_id=53073&package_id=114981, which will have a name of the form jclarens-w.x.y-z.i386.rpm.

2. As root, run the rpm by issuing the commands:

export JAVA_HOME=/path/to/java/home

rpm -ivh <rpm filename>

3. Start the Tomcat servlet container using the command:

/usr/lib/jclarens/jakarta-tomcat-5.0.28/bin/startup.sh

4. Test the installation by using your browser to navigate to http://localhost:8080/jclarens/xmlrpc?status. A successful initialization message indicates that the servlet is running and deployed. To test if the web interface is up, simply point your browser to http://localhost:8080/jclarens/. The Clarens web interface should load up.

5. (Optional) To use the web interface, you will have to install in your browser either the JClarens client certificate (available at http://clarens.sourceforge.net/jclarens/client.p12), or a certificate issued by a valid certificate authority (email to: thomas@hep.caltech.edu for a certificate by the GAE certificate authority). Most US and European Grid CAs are accepted by JClarens. Once that is done, you can point your browser to https://localhost:8443/jclarens/. Click the Login link, and then click the Login to https://localhost:8443/jclarens/xmlrpc button. However, to use most of the facilities offered by the web interface, you will need to add ACLs to allow access from your certificate. See Adding Access Control Lists for information on how to do this

6. (Optional) To get JClarens to run automatically during system startup/shutdown, you will need to download and install the jclarens-service*.rpm package from http://sourceforge.net/project/showfiles.php?group_id=53073&package_id=114981. After that you only need to run the following command once:

chkconfig --level 35 jclarens on

Windows Installation:

1. Download the JClarens installer exe from http://sourceforge.net/project/showfiles.php?group_id=53073&package_id=114981

2. Run the installer program, and follow the instructions. The installer will add a program folder named JClarens in the Start Menu, and will also optionally create a JClarens service in the Windows Services list.

3. You can start and stop JClarens either using the icons provided in the JClarens program folder in the Start menu, or from the Windows Services list.

4. Test the installation by using your browser to navigate to http://localhost:8080/jclarens/xmlrpc?status. A successful initialization message indicates that the servlet is running and deployed. To test if the web interface is up, simply point your browser to http://localhost:8080/jclarens/. The Clarens web interface should load up.

5. (Optional) To use the web interface, you will have to install in your browser either the JClarens client certificate (available at http://clarens.sourceforge.net/jclarens/client.p12), or a certificate issued by a valid certificate authority (email to: thomas@hep.caltech.edu for a certificate by the GAE certificate authority). Most US and European Grid CAs are accepted by JClarens. Once that is done, you can point your browser to https://localhost:8443/jclarens/. Click the Login link, and then click the Login to https://localhost:8443/jclarens/xmlrpc button. However, to use most of the facilities offered by the web interface, you will need to add ACLs to allow access from your certificate. See Adding Access Control Lists for information on how to do this

Installing JClarens in pre-installed Tomcat:

First of all you need to make sure Java is installed on your system and the JAVA_HOME environment variable is set. Secondly, Apache Tomcat 5.0.28 and above is required. The zip file for Tomcat can be downloaded from http://jakarta.apache.org/site/binindex.cgi. Unzip this file into a suitable directory. From here onwards, the directory created by unzipping this file will be termed as TOMCAT_HOME.

1. Download the file named like jclarens-w.x.y.zip from http://sourceforge.net/project/showfiles.php?group_id=53073

2. Extract the jclarens.war file from the zip file.

3. Place the jclarens.war file in the $TOMCAT_HOME/webapps directory, where $TOMCAT_HOME is the directory where Jakarta Tomcat is installed.

4. Create a directory named "jclarens" in the $TOMCAT_HOME/webapps directory. Extract the war file into the $TOMCAT _HOME/webapps/jclarens directory.

5. Setup the paths of the server's host certificate and host key in the xmlrpc_handlers.properties file (properties service.system.hostCertFile and service.system.hostKeyFile). Setup the path where you want the HSQLDB database to be stored in the xmlrpc_handlers.properties file as well.

Note: In case of Windows, paths should have double backslashes (\\) in place of backslashes (\).

6(Optional). If Clarens authentication using SSL certificates is required instead of auth() style Basic Authentication, then you will need to do the following steps:

a. To configure Tomcat and JClarens for operation over SSL connections, go to $TOMCAT_HOME\conf\server.xml. Uncomment the SSL Connector configuration, and modify it as shown below:

<Connector port="8443"
sSLImplementation="org.glite.security.trustmanager.tomcat.TMSSLImplementation"
sslCAFiles="/path/to/etc/grid-security/certificates/*.0"
crlFiles="/path/to/etc/grid-security/certificates/*.crl_url"
sslCertFile="/path/to//etc/grid-security/hostcert.pem"
sslKey="/path/to/etc/grid-security/hostkey.pem"
log4jConfFile="/path/to/jakarta-tomcat-5.0.28/conf/log4j-trustmanager.properties"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" disableUploadTimeout="true"
acceptCount="100" debug="0" scheme="https" secure="true"
clientAuth="true" sslProtocol="TLS" />

JClarens' sample server certificate (hostcert.pem) and private key (hostkey.pem) is available in the jclarens-w.x.y.zip file you downloaded in the jclarens-0.5.4/etc/grid-security/ directory.

b. Secondly, you will have to copy the glite-*.jar files from the downloaded jclarens-w.x.y.zip file, and bcprov.jar and log4j-1.2.8.jar from $TOMCAT_HOME/webapps/jclarens/WEB-INF/lib to the $TOMCAT_HOME\server\lib directory.

7. Start up tomcat by running Tomcat's startup script, startup.bat (Windows) or startup.sh (Linux).

8. Test the installation by using your browser to navigate to http://localhost:8080/jclarens/xmlrpc?status. A successful initialization message indicates that the servlet is running and deployed.

9 (Optional). It is recommended that the maximum http header size is increased to 8192 for the http Connector in server.xml using maxHttpHeaderSize="8192" as shown below:

Adding Access Control Lists

JClarens uses an internal database to store access control lists. The access control lists allow the server administrator to restrict access to individual services and service methods to specific users and groups. By default, the query methods find and find_server in the Discovery Service are open to everyone; no access control check is performed. The publication method register is by default only accessible to the admin user as defined by the clarens.admin property in xmlrpc_handlers.properties. There are two ways to open up access to this method. First, you can simply set clarens.admin to an empty string. This is the easiest and least secure way, but is suitable for doing installation testing. Second, you can log into the web browser interface of jclarens and set the access control for the rendezvous.register method. The clarens.admin certificate must be loaded into your web browser in order for this to work.

1. Go to https://localhost:8443/jclarens and click on the 'login' link on the left.
2. Click on the Login button.
3. Select the 'Method ACL Management' link.
4. Browse to the rendezvous.register method, select it, and press the 'Edit ACL' button.
5. In the popup window, press 'ACL Allow User' then 'Add DN'.
6. Type in the certificate subject (or subject substring) for users who are allowed to access this service method.