Access Keys:
Skip to content (Access Key - 0)

GTS

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

This guide explains how to install Grid Trust Service (GTS) version 1.4 and configure to function independently of any other GTS instance.

GTS specific host requirements:

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

Step 1: Targeting the New Grid

As a previous step in configuring a new grid, you should have created a new target grid configuration for your grid and a modified caGrid installer that includes the new target grid. If you have not already done so, re-install caGrid on the host that will be running the new grid's master GTS service and select the new grid as the target grid.

Step 2: Configure the Container

In this step, we will configure a 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 previously.

  1. From a command prompt, launch the caGrid Installer: 
    > cd \ CAGRID_INSTALLER_LOCATION
    
> java -jar caGrid-installer-1.4.jar
  2. Select the I agree to this license box and then click Next.
  3. Select the Install/Configure Grid Service Container box and then click Next.
  4. 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.
  5. 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.
  6. 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".
  7. 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.
  8. The next screen asks where you want to install Tomcat. Enter that location in the Directory text box and click Next.
  9. A list of tasks appears that the installer will perform in order to install and configure Tomcat. Click Next.
  10. Once the installer has completed installing all of the components, click Next.
  11. 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 3: Configure SyncGTS to Use the Master GTS

This step is needed only if you are configuring a new grid to run a master GTS instance and a slave GTS instance. If you are setting up a new grid that only runs one instance of the GTS service you should skip this step.

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.

  1. Open the sync-description.xml file for editing
    $CATALINA_HOME/webapps/wsrf/WEB-INF/etc/cagrid_SyncGTS/sync-description.xml

  2. 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.

  3. 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 4: Bypass the First Run of SyncGTS

Edit syncGTS service.properties of the deployed SyncGTS as follows to bypass the first run of SyncGTS after starting your container.

  1. Open the SyncGTS jndi-config.xml in your editor.
    1. $CATALINA_HOME/webapps/wsrf/WEB-INF/etc/cagrid_SyncGTS/jndi-config.xml
  2. Find the performFirstSync setting.
  3. Replace the "true" value with "false".
  4. The final configuration should look like this: 
    <parameter>
  <name>performFirstSync</name>
  <value>false</value>
</parameter>

Step 5: 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
  1. Open the GTS configuration file to edit the commonly changed values.
    • GTS_HOME/etc/gts-conf.xml
  2. 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.
  3. Save the file.

Step 6: 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:

  1. Open the GTS service metatada file, GTS_HOME/etc/serviceMetadata.xml.
  2. In the hostingResearchCenter element near the bottom of the file, do the following.
    1. Supply your ResearchCenter infomation.
    2. Supply your Address. This is the address that is used when mapping your service on the caGrid Portal.
    3. 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="John.Doe@osumc.edu"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.
  3. 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 7: 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 GTS. Within this document, we will use that user ID gts 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 gts, then the grid identity will be
/O=abc/OU=LOA1/OU=Dorian/CN=gts

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=gtsAdmin

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=gtsAdmin was succesfully added as an administrator of the GTS (GTS)
BUILD SUCCESSFUL
 Total time: 2 seconds
In order for the initial administrators to work with the GTS, Globus must trust the certificate authority that issued their credentials. If your credentials were issued by a certificate authority in the target grid you chose, you do not have to worry about this because SyncGTS handles it for you. Otherwise, you would have to manually copy the CA certificate to the Globus trusted certificates directory, which is usually USER_HOME/.globus/certificates. Globus requires all CA certificates in its trusted certificates directory to be in PEM format and to have a digit extension (0-9). For example, if a CA certificate is stored in the file cacert.pem in PEM format, then to configure Globus to trust this certificate authority, you would need to copy it into the directory USER_HOME/.globus/certificates (create directory if needed) with the file name cacert.0. Once the initial trust fabric has been set up, SyncGTS should be deployed. It then takes over the management of the Globus trusted certificates directory, keeping in it sync with the trust fabric.

Step 8: 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 9: Start GTS

  1. 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.
  2. If you chose a JBoss container, start JBoss as follows:
    1. Windows: 
       $JBOSS_HOME\run.bat
    2. Unix/Mac: 
       $JBOSS_HOME/run.sh

Step 10: Verify the Installation

It is customary for documentation of caGrid services to have a section describing how to verify the service's installation. Because installation of a master GTS service is part of a larger bootstrapping process, it is not possible at this time to verify the installation of the master GTS service.

Verification of the master GTS service requires that the Dorian service is also running. The steps that will verify the installation of the master GTS service are included in the installation steps for the Dorian service. The grid installation guide that directed you to this installation of the master GTS service will also direct you to the setup of the Dorian service at the appropriate time.

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

You have not yet configured the GTS to trust the trust fabric certificate authority. GTS will not function properly until that is done. This last bit of master GTS configuration cannot be done until Dorian is working. The instructions for doing this to GTS are included in the Dorian Installation guide.
Last edited by
Joe George (648 days ago) , ...
Adaptavist Theme Builder Powered by Atlassian Confluence