Slave GTS Installation Guide

[ GTS: Administrators Guide | Developers Guide | caGrid: Documentation Guides ]

This Page is Part of a Multi-Page Set of Directions
The instructions on this page are intended to be used a part of the instructions for installing a new grid that start on the Grid Installation Guide.


	Contents GTS specific host requirements: Step 1: Create a Slave GTS Host Certificate Step 2: Copy Certificates from Master Host to Slave Host Copy CA Certificate from Master GTS Copy Slave Host Certificate from Master Step 3: Install caGrid/GTS Installer Prerequisites Installing caGrid 1.4 Using the Installer Step 4: Configure the Container Step 5: Configure SyncGTS to Use the Master GTS Step 6: Configure the GTS Step 7: Edit the GTS Service Metadata Step 8: Add Initial Administrators Step 9: Deploy the GTS Step 10: Start GTS Step 11: Verify the Installation

This guide explains how to install and configure a Slave Grid Trust Service (GTS) version 1.4.

GTS specific host requirements:

MySQL 5.0.45 database (configured with case-insensitive table names)
Java 6 JDK

Step 1: Create a Slave GTS Host Certificate

The host certificate for the slave GTS host needs to be created on the Master GTS host using the trust fabric certificate authority.

To create host credentials please complete the following steps from a command prompt(illustrated below):

Connect to MASTER_GTS_HOST
Open a terminal
Type cd GTS_HOME.
Type ant createAndSignHostCertificate.
Enter the location of the CA's private key (TRUST_CA_KEY).
Enter the password used to encrypt the CA's private key.
Enter the location of the CA's certificate (TRUST_CA_CERTIFICATE).
Enter the name of the SLAVE_GTS host.
Use of the fully qualified hostname is highly recommended.
Enter the number of days that the host credentials should be valid for.
Enter a location to which to write the host private key.
Enter a location to which to write the host certificate.

Sample output from executing the above steps is shown below:

$ ant createAndSignHostCertificate
Buildfile: build.xml

setGlobus:

checkGlobus:
     [echo] Globus: /Users/cagrid/ext/ws-core-4.0.3

defineClasspaths:

defineExtendedClasspaths:

init:

checkValidate:

preInit:

configure:
     [copy] Copying 1 file to /Users/cagrid/releases/caGrid-1.3/projects/gts

postInit:

createAndSignHostCertificate:
    [input] Please enter the location of the CA's private key:
/Users/cagrid/certificates/gts-example/trustca-key.pem
    [input] Please enter the CA's password:
test
    [input] Please enter the location of the CA's certificate:
/Users/cagrid/certificates/gts-example/trustca-cert.pem
    [input] Please enter the Hostname [mastergts.examplegrid.org]: [mastergts.examplegrid.org]
slavegts.examplegrid.org
    [input] Please enter the number of days the host certificate will be valid for:
1000
    [input] Please enter a location to write the host key:
/Users/cagrid/certificates/slavegts.examplegrid.org-key.pem
    [input] Please enter a location to write the host certificate:
/Users/cagrid/certificates/slavegts.examplegrid.org-cert.pem
     [java] Successfully created the host certificate:
     [java] O=caGrid,OU=GTS Example,OU=Trust Fabric,CN=host/slavegts.examplegrid.org
     [java] Host certificate issued by:
     [java] O=caGrid,OU=GTS Example,OU=Trust Fabric,CN=GTS Example Trust Fabric CA
     [java] Host certificate valid till:
     [java] Sun Nov 13 15:42:32 EST 2011
     [java] Host private key written to:
     [java] /Users/cagrid/certificates/slavegts.examplegrid.org-key.pem
     [java] Host certificate written to:
     [java] /Users/cagrid/certificates/slavegts.examplegrid.org-cert.pem

BUILD SUCCESSFUL
Total time: 1 minute 44 seconds

Note down the location to which the host certificate and private key were written. You will need these later to configure your container.

Step 2: Copy Certificates from Master Host to Slave Host

Follow these instructions to copy the trust fabric certificate authority and Slave GTS host credentials from the Master GTS host to the Slave GTS host.

Copy CA Certificate from Master GTS

Execute the following commands, substituting the appropriate user ID for "user".

mkdir saved_certificates
scp user@mastergts:.globus/certificates/cacert.0 saved_certificates

Copy Slave Host Certificate from Master

Save these to a backup location on the Slave GTS host.
Execute the following commands, substituting the appropriate user ID for "user".

scp user@mastergts:certificates/slavegts.examplegrid.org-cert.pem saved_certificates
scp user@mastergts:certificates/slavegts.examplegrid.org-key.pem saved_certificates

Step 3: Install caGrid/GTS

In this step you download and install the GTS using the caGrid Installer that you modified in a previous step to be aware of your target grid.

Do not Target the Training Grid
The following instructions for using the installer to install caGrid suggest that you should select the training grid as the target grid. Do not select the training grid as the target grid. Select the grid that this GTS will actually be part of.

Installer Prerequisites

The caGrid Installer installs all prerequisites except for Java and MySQL.

Java 6 JDK
- Make sure the JAVA_HOME environment variable is set and points to the location where the JDK has been installed.
(Optional) If you are deploying caGrid core services locally, you may also need a MySQL database.
Note
MySQL is only required for the security services and GME. You can use 4.x (with transaction enabled; i.e., use InnoDB engine) or 5.x.

Installing caGrid 1.4 Using the Installer

Internet Resources Required by the Installer
Unless you are using a customized installer, the installer will need to be able to access these internet resources:

http://gforge.nci.nih.gov to download caGrid and Globus
http://archive.apache.org to download ant and tomcat (if you create a tomcat container)
http://downloads.sourceforge.net to download JBoss if you create a JBoss container.
https://ncisvn.nci.nih.gov to download the default installer properties and configuration file

Download the caGrid 1.4 Installer, unless you have a customized installer that you have been instructed to use for your grid. The downloaded installer should be contained in the file caGrid-installer-1.4.zip. If you are using a customized installer the name may vary.
Unzip the file caGrid-installer-1.4.zip. This creates the directory caGrid-installer-1.4. This documentation refers to this directory as CAGRID_INSTALLER_LOCATION.
From a command prompt, launch the installer using the following command:
Do not launch the installer by double-clicking the jar file
```
 > cd *CAGRID_INSTALLER_LOCATION*

> java -jar caGrid-installer-1.4.jar 
```

Select the I agree to this license checkbox and then click Next.

Select the Install/Configure caGrid Software checkbox and then click Next.

The installer detects whether or not you have already installed Ant. It installs or reinstalls it, depending on your installation status. In either case, you must specify the location where you want to install Ant.
The installer detects whether or not you have already installed Globus. It installs or reinstalls it, depending on your installation status. In either case, you must specify the location where you want to install Globus.

The installer asks you for a location on your local file system to install caGrid. Specify a location to install caGrid and click Next.

To select a file location that is not in the User's Home directory, Click the Look In: drop down list and select a new starting location.

The installer displays a list of tasks that the installer will perform. Click Next to begin the installation process. At this time the installer downloads, builds, and installs several components. This process takes several minutes.
Once the installer has completed installing all the components, click Next.

The installer prompts you to specify which Grid you want to configure your installation to use. The installer supports configuring caGrid to work out of the box with many community Grid environments. For testing and development purposes, we recommend selecting the Training Grid. If you do not want to configure caGrid to work with an existing Grid you may select that as well. The installer can also be modified to support additional Grids.

The installer shows a summary of the tasks to be completed. Click Next to configure caGrid to use the selected target Grids. This process takes several minutes.
Once the installer has finished configuring caGrid to use the target Grid, click Next. The final screen reminds you to set your ANT_HOME and GLOBUS_LOCATION environment variables. Set these variables immediately and click Finish.

Congratulations! You have successfully installed caGrid.

Add ANT_HOME/bin to PATH
You will be running the ant program from the command line so add ANT_HOME/bin to PATH.

The installer installs caGrid to the directory you specified during installation. From this point on we refer to this directory as CAGRID_HOME.

You can find the GTS in the directory CAGRID_HOME/projects/gts; from this point on we refer to this directory as GTS_HOME.

The GAARDS UI (user interface) for administrating the GTS is located in CAGRID_HOME/projects/gaardsui; from this point on we refer to this directory as GAARDS_UI_HOME.

Step 4: Configure the Container

In this step we will configure a secure web service container that will host the GTS. The GTS can be deployed to the Tomcat, JBoss, and Globus containers. This guide includes instructions on how to use the caGrid Installer to install and configure a secure Tomcat container. You will need to supply the installer with the host credentials you created in the last step.

At Step 6 of the installer, browse to the host certificate and key that were copied to the Slave GTS host in Step 2.

From a command prompt, launch the caGrid Installer:

> cd \ CAGRID_INSTALLER_LOCATION

> java -jar caGrid-installer-1.4.jar

Select the I agree to this license box and then click Next.

Select the Install/Configure Grid Service Container box and then click Next.

Select the Container to which you want to deploy your service. Because this guide will use a secure Tomcat, select the Should this container be secure? box and then click Next.

In the hostname box, enter the hostname of your server. This should match the hostname you used when you created your host credentials. Click Next.

If you plan on using this container to deploy a service that registers to an existing grid, it is important that you use a publicly resolvable DNS name (or static IP). Otherwise, you will need to manually edit configuration files later to correct this.

From the Obtain host credentials method list, select the option that applies to your situation and click Next.

Options:

If you do not yet have credentials for your service, select Use GAARDS to obtain host credentials.
If you have host credentials that are not in the default location, then select Browse to host credentials on the file system.
If you have host credentials that are in the default location, then select Host credentials are already installed.

Default credential location:

On Windows, this will be a path like "C:\Documents and Settings\<USERNAME>\.cagrid\certificates".
On Linux/MAC this will be a path like "/Users/YOUR_USERNAME/.cagrid/certificates".

If you selected Browse to host credentials on the file system, the next screen will prompt you for the location of your credentials. Enter the location of your host certificate in the Certificate text box. Enter the location of your private key in the Key text box. Click Next.

The next screen asks where you want to install Tomcat. Enter that location in the Directory text box and click Next.

A list of tasks appears that the installer will perform in order to install and configure Tomcat. Click Next.

Once the installer has completed installing all of the components, click Next.

Click Next. The final screen reminds you to set your ANT_HOME, GLOBUS_LOCATION and CATALINA_HOME environment variables. Set these variables immediately and click Finish.

Congratulations! You have successfully installed and configured your Tomcat container.

Step 5: Configure SyncGTS to Use the Master GTS

When you created the secure tomcat container, the installer installs a plugin called SyncGTS that configures the container to ONLY accept credentials from trusted credential providers. If you followed the instructions for configuring your target grid for a master and slave GTS instance, SyncGTS was configured to work with the slave GTS instance.

Working with the slave GTS instance is the correct configuration for every service and client on your new grid, except for the master and slave GTS instances.

To edit SyncGTS's configuration so that Dorian/Globus will trust the Dorian being installed and the credential providers trusted in the target grid, edit the file as follows.

Open the sync-description.xml file for editing
$CATALINA_HOME/webapps/wsrf/WEB-INF/etc/cagrid_SyncGTS/sync-description.xml
Locate the gtsServiceURI element (Shown Below):
```
<ns1:gtsServiceURI>https://slavegts.abc.example.org:8443/wsrf/services/cagrid/GTS</ns1:gtsServiceURI>
```
Set to the URI for the master GTS. The master GTS URI is the correct value for both master and slave GTS instances.

Locate the GTSIdentity element (Shown Below):

<ns1:GTSIdentity>/O=abc/OU=GTS/OU=Trust Fabric/CN=host/slavegts.abc.example.org</ns1:GTSIdentity>

Set this to the grid identity of the host that runs the master GTS service in this element.

If you don't know the grid identity of the master GTS service's host, you can get it by logging onto the host and using a program provided by globus the the identity from the host's host certificate. If HOST_CERT is the name of the host certificate file, issue the command
$GLOBUS_LOCATION/bin/grid-cert-info -file HOST_CERT
The output from this command will look like this

subject : O=abc,OU=GTS,OU=Trust Fabric,CN=host/mastergts.abc.example.org
issuer : O=abc,OU=GTS,OU=Trust Fabric,CN=Trust Fabric CA
start date : Tue Sep 21 23:56:50 GMT+05:00 2010
end date : Thu Aug 20 00:01:50 GMT+05:00 2020

The subject field contains the information you need in a slightly different form than it is needed in the gtsServiceURI element. The subject field separates sub-fields with a comma ",". The identity in the gtsServiceURI element introduces each sub-field with a forward slash "/".

Step 6: Configure the GTS

The GTS is configured through a configuration file which is located at GTS_HOME/etc/gts-conf.xml(shown below). The GTS uses a Mysql Database as its backend data store; you must provide the GTS with the connection details for your Mysql database.

<gts>
    <resource name="GTSConfiguration" class="gov.nih.nci.cagrid.gts.service.Configuration">
      <gts-config>
        <gts-internal-id>GTS</gts-internal-id>
        <sync-authorities hours="0" minutes="2" seconds="0"/>
        <database>
            <name/>
	    <driver>com.mysql.jdbc.Driver</driver>
	    <urlPrefix>jdbc:mysql:</urlPrefix>
	    <host>localhost</host>
	    <port>3306</port>
	    <username>root</username>
	    <password></password>
	    <pool>1</pool>
	</database>
      </gts-config>
    </resource>
</gts>

Configuration File Element	Purpose
gts-internal-id	Specifies the name of the GTS database that will be created
sync-authorities	Specifies how often the GTS should sync with its authorities
driver	The Standard MySQL driver
urlPrefix	Standard MySQL URL Prefix
host	Database hostname
port	Database port
username	Username of user with database creation privileges
paassword	Database user password
pool	Database connection pool size

Open the GTS configuration file to edit the commonly changed values.
- GTS_HOME/etc/gts-conf.xml
MySQL Database connection information:
1. Replace localhost with the appropriate hostname if you are using a database on another server.
2. Replace port if not using the standard MySQL port.
3. Replace username with another user with database creation privileges if you choose not to use the root account.
4. Provide the password for the username that you have provided.
Save the file.

Step 7: Edit the GTS Service Metadata

The GTS provides service metadata to clients and other services that describes information about the service, operations supported by the service, and information on the organization hosting the service.

Edit the service metadata to reflect your organization as follows:

Open the GTS service metatada file, GTS_HOME/etc/serviceMetadata.xml.

In the hostingResearchCenter element near the bottom of the file, do the following.

Supply your ResearchCenter infomation.
Supply your Address. This is the address that is used when mapping your service on the caGrid Portal.

Supply the PointOfContact. This is the person responsible for maintaining the service.
A completed example:

<ns1:hostingResearchCenter>
  <ns53:ResearchCenter displayName="Ohio State University" shortName="OSU" xmlns:ns53="gme://caGrid.caBIG/1.0/gov.nih.nci.cagrid.metadata.common">
   <ns53:Address country="US" locality="Columbus" postalCode="43210" stateProvince="OH" street1="3190 Graves Hall" street2="333 W. 10th Ave."/>
   <ns53:pointOfContactCollection>
    <ns53:PointOfContact affiliation="OSU" email="knowledge@osu-citih.org" firstName="John" lastName="Doe" phoneNumber="(555) 555-5555" role="Maintainer"/>
   </ns53:pointOfContactCollection>
  </ns53:ResearchCenter>
 </ns1:hostingResearchCenter>

Note
By default, the GTS registers with and publishes its service metadata to the Index Service. The default Index Service is configured as the Index Service of the target grid you selected when you installed the GTS. You can find configuration details on registering and publishing to the Index Service, including disabling registration and changing which Index Service to register with, on the Registration and Discovery page.

Edit the GTS deploy.properties file to bypass Index Service registration as follows:
1. Open the GTS_HOME/deploy.properties file.
2. Locate the index.service.url entry and replace the current URL with the URL of your Index Service.
3. Locate the perform.index.service.registration entry and temporarily set it to "false" to avoid communication errors caused by missing Index Service.

Step 8: Add Initial Administrators

The GTS provides many operations for administrating the trust fabric; these operations are restricted to GTS administrators. GTS Administrators are "super users" and can perform any operation on a GTS (i.e., manage certificate authorities, manage trust levels, manage permissions, etc). To bootstrap the GTS so that it may be administered through its service interface, we must provide the GTS with at least one initial administrator.

We recommend that you set up one user ID that will be used exclusively as the initial administrator for the slave GTS. Within this document, we will use that user ID slaveGts for this purpose. We also recommend that you choose some other user ID to use in your installation.

Note the GTS Administrator User ID
Make a careful note of the GTS administrator ID that you choose so that you will be able to configure it in Dorian after you have Dorian running.

The GTS provides a command line program for adding initial administrators. This program needs to be given a grid identity rather than a user ID. Since you have not yet set up Dorian, you cannot yet configure the user ID or see what grid identity Dorian creates from the user ID.

Fortunately, Dorian follows a predictable pattern in how it creates grid identities. If you configure Dorian exactly as described in its installation guide, the pattern that Dorian will follow in creating a grid identity from a user ID is
/O=[GRID_NAME]/OU=LOA1/OU=Dorian/CN=userId
where [GRID_NAME] is the one-word grid name that you chose previously and userId is the user ID. For example, if the one-word grid name is abc and the userId is slaveGts, then the grid identity will be
/O=abc/OU=LOA1/OU=Dorian/CN=slaveGts

Follow Directions Carefully
Be careful to follow all directions related to naming patterns carefully. Any mistakes in this can prevent grid services from trusting each other.

To use this program, type the following from a command prompt:

 $ cd GTS_HOME $ ant addAdmin

You are prompted for the grid identity of the initial administrator to add. Enter that information as follows.

ant addAdmin
Buildfile: build.xml setGlobus: checkGlobus:
[echo] Globus: /Users/langella/ext/ws-core-4.0.3 addAdmin:
[input] Please enter the grid identity for the admin you wish to add:
/O=abc/OU=LOA1/OU=Dorian/CN=slaveGts

Warning: Reference service.run.classpath has not been set at runtime, but was found during build file parsing, attempting to resolve. Future versions of Ant may support referencing ids defined in non-executed targets.
Warning: Reference service.run.extended.classpath has not been set at runtime, but was found during build file parsing, attempting to resolve. Future versions of Ant may support referencing ids defined in non-executed targets.
Warning: Reference service.build.classpath has not been set at runtime, but was found during build file parsing, attempting to resolve. Future versions of Ant may support referencing ids defined in non-executed targets.
Warning: Reference service.build.extended.classpath has not been set at runtime, but was found during build file parsing, attempting to resolve. Future versions of Ant may support referencing ids defined in non-executed targets.
Warning: Reference base.classpath has not been set at runtime, but was found during build file parsing, attempting to resolve. Future versions of Ant may support referencing ids defined in non-executed targets.
Warning: Reference base.extended.classpath has not been set at runtime, but was found during build file parsing, attempting to resolve. Future versions of Ant may support referencing ids defined in non-executed targets.
[java]
The user /O=abc/OU=LOA1/OU=Dorian/CN=slaveGts was succesfully added as an administrator of the GTS (GTS)
BUILD SUCCESSFUL
Total time: 2 seconds

Step 9: Deploy the GTS

At this point we have completed configuring the GTS and the container the GTS will run in.

From a command prompt, do the following if you want to deploy the GTS to the Secure Tomcat Container:

 >cd GTS_HOME


> ant deployTomcat

If you chose to use a JBoss container, deploy the GTS by typing the following at a command prompt:

 > cd GTS_HOME


> ant deployJBoss

Although the installer does not support configuring a secure Globus container, deploy the GTS to a secure Globus container by typing the following at the command prompt:

 > cd GTS_HOME


> ant deployGlobus

No matter which container you choose, you should see a significant amount of output to the screen. If the deployment is successful, the words BUILD SUCCESSFUL appear on the screen.

Step 10: Start GTS

If you chose a Tomcat container, start Tomcat as follows:
```
  $CATALINA_HOME/bin/startup.sh  
```
Check the $CATALINA_HOME/logs/catalina.out file for any errors.
If you chose a JBoss container, start JBoss as follows:
1. Windows:
```
 $JBOSS_HOME\run.bat 
```
2. Unix/Mac:
```
 $JBOSS_HOME/run.sh 
```

Check the Tomcat log files (CATALINA_HOME/log/catalina.out) to ensure that there are no error or stacktraces and that the container successfully started and bound to the port you specified during the installation.

If you sepcified the URL of an Index service that is not reachable or is not yet deployed you will receive errors related to advertising your service.

Step 11: Verify the Installation

Once you have deployed the GTS, you have completed the installation and configuration of the GTS. Next we will verify that the installation was successful.

Type the following from a command prompt:
```
$ cd GAARDS_UI_HOME
$ ant ui
```
Add your newly configured Slave GTS as a GTS Service for the Grid.
Select Window > Preferences. The Preference window appears.
From the preferences tree on the left side of the window, expand the Trust Fabric node and then click the Grid Trust Service(s) node. On the right side of the screen you should see a list of GTS Services.
In the Display Name text field enter the name for your Slave GTS. Example: MyGrid Slave.
In the Service URL field, enter https://<hostname>:<port>/wsrf/services/cagrid/GTS, replacing <hostname> and <port> with the values specific to your service.
Click Add.
Click Save.

Login in as one of the initial GTS administrators we created during the Master GTS install. To accomplish this complete the following steps:

Click Login. The Login window appears.
From the Credential Provider list, select the Dorian that issued your administrators credential.
From the Organization list, select the identity provider of the administrator.
In the User Id box, enter the user ID of the administrator.
In the Password box, enter the password of the administrator.
Click Authenticate.

Configure the Frust Federation to indicate that the authority of your Slave GTS is your Master GTS. Complete the following steps:

Select Trust Fabric > Trust Federation. The Trust Federation dialog appears.
In the Service list, select the newly added Slave GTS service.
Click Search. There should be no results.
Click the Add button, at the bottom. The Add Authority dialog appears.
1. In the GTS URL field, enter the URL of your Master GTS service.
2. In Perform Authorization, select true.
3. In Authorization Identity, provide the host identity of your Master GTS service.
4. In Trusted Authority Records Time to Live, select 4 hours (Training grid standard).
5. Click Add

Congratulations. You have succesfully installed the Grid Trust Service (GTS).

GTS Preferences

Login Window

Add Level of Assurance

Trust Federation Slave

Add Trust Fabric Authority

GTS