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

Knowledgebase


Add a New Target Grid to the caGrid Installer


Contents

Authors:

Sarah Honacki, Justin Permar, Mark Grand

Audience

This article is an advanced article intended for Grid administrators. This article walks a Grid administrator through the process of adding a new Grid to the list of choices that are presented in the caGrid installer. The primary motivation is to allow others to easily integrate with and utilize the Grid services that you have deployed for your own Grid.

Background Information

This guide assumes prior knowledge of the caGrid target Grid configuration process. Please read the following documentation if you are not familiar with the "target Grid" concept in caGrid: How to Change Target Grid

About this Document

Throughout this document, we denote portions that should be changed by you by putting an indicator of the contents surrounded by "[" and "]". An example is [GRID_NAME], where you should replace everything including the brackets with the indicated contents. An example for a Grid name of "abc" is to replace "[GRID_NAME]" with "abc". This guide was designed using caGrid 1.3.

Introduction

The caGrid installer has the ability to configure a caGrid installation for a chosen target grid. When using the installer, there are several choices available as possible target grids. This article presents the steps to follow to add a new target Grid configuration to the list of choices in your own custom caGrid installer.

Add a New Target Grid to the Installer


There are 3 phases in this guide:

  1. Download a caGrid distribution.
  2. Create a new target Grid and add it to the distribution.
  3. Update the installer to use the custom caGrid distribution.

Phase 1: Download a caGrid Distribution

To begin, download caGrid 1.3 Source Distribution from Obtain caGrid 1.3 Source. Unzip the file to a temporary location. We will now refer to this location as CAGRID_HOME.

Phase 2: Create a new target Grid and add it to the distribution


In this phase there are 5 steps that must be completed:

  1. Create your Grid directory
  2. Copy the Files
  3. Modify the Files
  4. Modify the ivy xml
  5. Re-zip the file

First, navigate to CAGRID_HOME and locate the target_grid directory.

Example:

CAGRID_HOME\repository\caGrid\target_grid

Here you will see several target grid file folders along with several corresponding Ivy XML files. We need to create our own grid folder and then copy existing (template)target grid files to this folder. Then we will copy an Ivy XML file and modify it to provide information about our new target grid configuration.

Create your Grid directory

Then create a new folder with a name that has the following format: [GRID_NAME]-1.3. For example, if your one-word grid name is "abc" then the folder would be named "abc-1.3".

Copy the files

For this tutorial we are going to copy and modify the Training Grid files. Open training-1.3. You will see the following:

Copy the directory contents (all files including all sub-folders) into the [GRID_NAME]-1.3 folder you just created.

Also copy the corresponding ivy XML file from the target_grid directory (e.g., ivy-training-1.3.xml) and give it a new name with the following format: ivy-[GRID_NAME]-1.3.xml. For example, ivy-abc-1.3.xml.

Modify the Configuration Files

In this step, you will update the files you just copied to point to the services in your Grid. These files are copied to various locations in the caGrid installation when you configure caGrid with a chosen target Grid.

For example, the target Grid configuration files will have URLs of the "core" services in your Grid deployment (e.g,. Dorian). This step involves updating those URLs as outlined below.

The files that you will modify are in the [GRID_NAME]-1.3 directory.

Configuration for CDS, Dorian, GridGrouper and GTS

In the [GRID_NAME]-1.3 directory, modify the following XML files:

  • cds-services-configuration
  • dorian-services-configuration
  • gridgrouper-services-configuration
  • gts-services-configuration

For these files, use a text editor to change the values of the <DisplayName>, <ServiceURL> and <ServiceIdentity> elements to the proper values for your grid.

The recommended value for the <DisplayName> element is the name of the grid followed by the name of the service, like this:
[GRID_NAME] serviceName
For a grid named "abc", the respective recommended values for the <DisplayName> element in these files would be

  • abc CDS
  • abc Dorian
  • abc Grid Grouper
  • abc GTS

For the <ServiceURL> element in each file, just change the host name and port number to the appropriage value. Leave the rest of each URL as is.

The value of the <ServiceIdentity> element is the grid identity of the host that will be running the service that the file is named for. If you are setting up this target grid configuration for an existing grid, then check the identity in each host's actual grid certificate.

If you are setting up this target grid configuration for a new grid, then if you follow the naming pattern described below, the names will be right. For the cds-services-configuration, dorian-services-configuration and gridgrouper-services-configuration files, the pattern to use for the value of the <ServiceIdentity> element is
/O=[GRID_NAME]/OU=LOA1/OU=Services/CN=hostName
For example, if the grid name is "abc" and the name of the host that the service runs on is dorian.abc.example.org, then the value for the <ServiceIdentity> element should be
/O=abc/OU=LOA1/OU=Services/CN=dorian.abc.example.org

The pattern for the <ServiceIdentity> element in the gts-services-configuration file is different:
/O=[GRID_NAME]/OU=GTS/OU=Trust Fabric/CN=host/hostName
For example, if the grid name is "abc" and the name of the host that the service runs on is mastergts.abc.example.org, then the value for the <ServiceIdentity> element should be
/O=abc/OU=GTS/OU=Trust Fabric/CN=host/mastergts.abc.example.org

The gts-services-configuration file differes from the other files in another way. Because there may be multiple GTS services, there may be multiple sets of <DisplayName>, <ServiceURL> and <ServiceIdentity> elements. There should be one set of elements enclosed in a <ServiceDescriptor> element for each GTS service. Here is an example of what this looks like:

<Services>
  <ServiceDescriptor>
    <DisplayName>ABC Master GTS</DisplayName>
    <ServiceURL>https://mastergts.abc.example.org:8443/wsrf/services/cagrid/GTS</ServiceURL>
    <ServiceIdentity>/O=abc/OU=GTS/OU=Trust Fabric/CN=host/mastergts.abc.example.org</ServiceIdentity>
  </ServiceDescriptor> 
  <ServiceDescriptor> 
    <DisplayName>ABC Slave GTS</DisplayName>
    <ServiceURL>https://slavegts.aku.edu:8443/wsrf/services/cagrid/GTS</ServiceURL>
    <ServiceIdentity>/O=abc/OU=GTS/OU=Trust Fabric/CN=host/slavegts.abc.example.org</ServiceIdentity>
  </ServiceDescriptor>
</Services>

The above example shows what the gts-services-configuration file looks like for new grids that are configured with a master GTS and a slave GTS. If you are configuring for a grid that has just one GTS service, then this file will contain only one <ServiceDescriptor> element rather than two.

websso

If the grid you are configuring for uses websso, you will need to edit the websso-properties.xml file in the [GRID_NAME]-1.3 directory. There are three parts of this XML file that you will need to change.

First, in the <credential-delegation-service-information> element, you will need to change the value of the <service-url> and <service-identity> elements to the same values that they have in the cds-services-configuration file.

<credential-delegation-service-information>
    <service-url>https://cds.abc.example.org:8443/wsrf/services/cagrid/CredentialDelegationService</service-url>
    <service-identity>/O=abc/OU=LOA1/OU=Services/CN=cds.abc.example.org</service-identity>
    <delegation-lifetime-hours>8</delegation-lifetime-hours>
    <delegation-lifetime-minutes>0</delegation-lifetime-minutes>
    <delegation-lifetime-seconds>0</delegation-lifetime-seconds>
    <issued-credential-path-length>0</issued-credential-path-length>
</credential-delegation-service-information>

Next, in the <dorian-services-information> element, you will need to change the value of the <display-name>, <service-url> and <service-identity> elements to the same values that they have in the dorian-services-configuration file.

<dorian-services-information>
  <dorian-service-descriptor>
    <display-name>ABC Dorian</display-name>
    <service-url>https://dorian.abc.example.org:8443/wsrf/services/cagrid/Dorian</service-url>
    <service-identity>/O=abc/OU=LOA1/OU=Services/CN=dorian.abc.example.org</service-identity>
    <proxy-lifetime-hours>12</proxy-lifetime-hours>
    <proxy-lifetime-minutes>0</proxy-lifetime-minutes>
    <proxy-lifetime-seconds>0</proxy-lifetime-seconds>		
  </dorian-service-descriptor>		
</dorian-services-information>

Finally, you will need to configure the services to which websso will delegate credentials. Edit the <delegated-applications-group> element so that it contains a name and host identity for each such service:

<delegated-applications-group>
  <group-name>Main Apps</group-name>
  <delegated-application-list>
    <delegated-application>
      <application-name>SNPDataService</application-name>
      <host-identity>/O=abc/OU=LOA1/OU=Services/CN=snp.abc.example.org</host-identity>
    </delegated-application>
    <delegated-application>
      <application-name>HL7</application-name>
      <host-identity>/O=abc/OU=LOA1/OU=Services/CN=hl7.abc.example.org</host-identity>
    </delegated-application>
  </delegated-application-list>
</delegated-applications-group>

sync-description.xml

You must edit the sync-description.xml file in the [GRID_NAME]-1.3 directory. you will need to modify the values of the following elements to match your grid's properties:

  • <ns1:gtsServiceURI>
    The value of this element is the URL of the GTS service that most other services will user the synchronize with the trust fabric. This value should be copied from the value of a <ServiceURL> element in the gts-services-configuration file. If there is more then one <ServiceURL> element in the gts-services-configuration file, use the URL for the slave GTS service. Here is an example of a <ns1:gtsServiceURI> element
    <ns1:gtsServiceURI>https://slavegts.abc.example.org:8443/wsrf/services/cagrid/GTS</ns1:gtsServiceURI>

  • <ns1:GTSIdentity>
    The value of this element is the expected grid identity for the host that the runs the GTS service whose URL is the value of the <ns1:gtsServiceURI> element. This should be the same as the value of the <ServiceIdentity> that was with the <ServiceURL> element that the value of the <ns1:gtsServiceURI> element came from. Here is an example
    <ns1:GTSIdentity>/O=abc/OU=GTS/OU=Trust Fabric/CN=host/slavegts.abc.example.org</ns1:GTSIdentity>

  • <ns1:CASubject>
    The value of this element is the distinguished name of the certificate authority that issued the host certificate for the host that the GTS runs on. If you don't know this, you can find it out be logging onto the GTS host and issuing the Windows or Unix/Max version of the following command:

    You may also verify the issuer of your user certificates and host certificates using functionality provided by Globus:
  • Windows:

    $ %GLOBUS_LOCATION%\bin\grid-cert-info.bat -file %USER_HOME%\.cagrid\certificates\<hostname>-cert.pem

  • Unix / Mac

    $ $GLOBUS_LOCATION/bin/grid-cert-info -file $HOME/.cagrid/certificates/<hostname>-cert.pem

    Here is an example of what a <ns1:CASubject> element might look like:
    <ns1:CASubject>O=abc,OU=GTS,OU=Trust Fabric,CN=Trust Fabric CA</ns1:CASubject>

Workflow Factory Service

If the grid you are configuring for will be running an instance of the Workfow Factory Service, then you will need to edit the workflow-ui-configuration.xml file. You will need to modify the value of the <value> element to be the URL of the service. Here is an example of what this looks like:
<value>https://workflow-bpel.abc.example.edu:8443/wsrf/services/cagrid/WorkflowFactoryService</value>

service_urls.properties

For the service_urls properties file, modify all of the urls except cagrid.master.cadsr.data.service.url to point to the corresponding service on your grid.

CA Certificate

Remove the files in the certificates directory. You will need to copy into this directory the certificate for the certificate authority that signed the GTS host's certificate. You can find this file on the host you specified for the master GTS in the gts-services-configuration file, in the $HOME/.globus/certificates directory.

If this directory contains just one file, whose names ends with ".0", that is probably the file you want. If there are multiple ".0" files or just to verify that you have the right file, issue a command like

  • Windows:

    %GLOBUS_LOCATION%\bin\grid-cert-info.bat -file %USER_HOME%\.globus\certificates\fileName.0

  • Unix / Mac

    $GLOBUS_LOCATION/bin/grid-cert-info -file $HOME/.cagrid/certificates/fileName.0

Replace fileName.0 with the name of a ".0" file in the directory. The output of this command looks like

subject     : O=abc,OU=Trust Fabric,CN=ABC Trust Fabric CA
issuer      : O=abc,OU=Trust Fabric,CN=ABC Trust Fabric CA
start date  : Thu Aug 27 17:35:59 EDT 2009
end date    : Sun Aug 25 17:40:59 EDT 2019

What you are looking for is for the subject and issuer to be the same as each other and to also be the same as issuer of the GTS hots's host certificate. The file that fits this description is the correct file. Copy the correct file from the $HOME/.globus/certificates directory on the GTS host to the certificates directory.

Modify the ivy xml

Now that all files have been copied to your grid folder and modified, we can edit the ivy-[GRID_NAME]-1.3.xml file in the CAGRID_HOME/caGrid/repository/caGrid/target_grid directory. In this file, set revision= to your grid folder file ([GRID_NAME]-1.3). Also set the <description> value to an appropriate description of your Grid.

<?xml version="1.0"?>
<ivy-module version="2.0"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:noNamespaceSchemaLocation="http://incubator.apache.org/ivy/schemas/ivy.xsd">
  <info organisation="caGrid"module="target_grid" revision="[_GRID_NAME_]-1.3">
    <description>[A description of your grid goes here]</description>
  </info>...

Also in the ivy-[GRID_NAME]-1.3.xml file, change the artifact name to match your root certificate.

<!-- certificates -->
<artifact name="certificates/<CERTIFICATE FILE PREFIX>" type="certificate" ext="0" conf="certs"/>

If the certificates directory contains a corresponding .signing_policy file, then edit the following line to match the actual name:

<artifact name="certificates/<CERTIFICATE FILE PREFIX>" type="certificate" ext="signing_policy" conf="certs"/>

If there is no .signing_policy file in the certificates directory, then delete the artifact element that specifies ext="signing_policy" from the ivy-[GRID_NAME]-1.3.xml file.

Re-zip the file

1. Next, re-zip the caGrid-1.3.0.1 directory (which now contains your target grid).

Phase 3: Update the installer to use the custom caGrid distribution.


Now that we have zipped our version of caGrid with your Grid, we can create a new custom installer containing your grid for selection.

There are 4 steps to this phase:

  1. Modify the installer.properties file
  2. Update the download.properties file
  3. Create a new jar
  4. Run the Installer and Verify

Modify the installer.properties file

  1. Download the caGrid installer that corresponds to your version of caGrid.
  2. Unzip the file. We will refer to this directory as ORIG_CAGRID_LOCATION.
  3. Among the extracted files is a caGrid-installer-1.3.jar. Extract this jar to a temporary location located in the same directory. We will call this location TEMP_CAGRID_LOCATION
  4. Locate and open the download.properties file in a text editor
  5. Copy the url from the file and paste it into a web browser.
  6. Save the page (For windows, right-click and select "Save page as.."). The page should default to save with a file name of cagrid-1.3.installer.properties
  7. Open the file in a text editor
  8. Set cagrid.download.url= to the location of the caGrid.1.3.0.1.zip we bundled earlier.
    Remember to use "file:///". Also remember to use "/" as the path separator (and NOT "\"). Wordpad should not be used for editing as it adds non-ascii characters. Notepad is acceptable to use.
  9. Set cagrid.md5.checksum to the checksum for the new caGrid.1.3.0.1.zip file.
    If the program you are using to create the zip file does not provide an easy way to find out what the md5 checksum of the file is, you can get it by running the installer with the old checksum. It will fail with an error message that contains the correct checksum for the new file.
  10. Save the file

Update the download.properties file

Now we need to update the download.properties file to point to the modified cagrid-1.3.installer.properties file.

  1. Re-open the download.properties file.
  2. Set download.url= to the cagrid-1.3.installer.properties file we modified.
    Remember to use "file:///". Also remember to use "/" in all of the pathnames. Wordpad should not be used for editing as it causes complications. Notepad is acceptable to use.
  3. Save the file.

Create a new jar

Now that the files have been updated, we can create a new jar file for the installer. The following commands will create a new jar file that includes the updated download.properties file that points to your local cagrid-1.3.installer.properties file (which is now set to use your modified version of caGrid with your Grid as a possible selection).

In a command prompt, change directory to TEMP_CAGRID_LOCATION and type the following command:

 > cd TEMP_CAGRID_LOCATION > jar cmf META-INF/MANIFEST.MF caGrid-installer-1.3.jar *
Once the new jar file is created, we need to use it to replace the original installer jar. To do this, open the TEMP_CAGRID_LOCATION. Copy the caGrid-installer-1.3.jar that you created. Paste it in the ORIG_CAGRID_LOCATION directory. When asked if you want to overwrite the existing file, select Yes.

Run the Installer and Verify

You can now run the installer using from a command prompt using the following command:

 > cd ORIG_CAGRID_LOCATION > java -jar caGrid-installer-1.3.jar
Verify that you can install caGrid and select your new target Grid.

Last edited by
Mark Grand (1306 days ago) , ...
Adaptavist Theme Builder Powered by Atlassian Confluence