Add a New Target Grid to the caGrid Installer


	Table of Contents Audience Background Information About this Document Introduction Add a New Target Grid to the Installer Phase 1: Download a caGrid Distribution Phase 2: Create a new target Grid and add it to the distribution Create your Grid directory Copy the files Modify the Files Modify the ivy xml Re-zip the file Phase 3: Update the installer to use the custom caGrid distribution. Modify the installer.properties file Update the download.properties file Create a new jar Run the Installer and Verify

Authors:

Sarah Honacki, Justin Permar

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 "osu" is to replace "[GRID NAME]" with "osu". 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:

Download a caGrid distribution.
Create a new target Grid and add it to the distribution.
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:

Create your Grid directory
Copy the Files
Modify the Files
Modify the ivy xml
Re-zip the file

First, navigate to CAGRID_HOME and locate the target_grid directory.

Example:

CAGRID_HOME\caGrid\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

Pick a one-word name for your Grid. For example, "osu". Then create a new folder with a name that has the following format: [GRID NAME]-1.3. For example, the folder would be named "osu-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-osu-1.3.xml.

Modify the Files

In this step, you will update the files you just copied to point to the services you have deployed 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.

1. Open the [GRID NAME]-1.3 directory. Here you will need to 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 <ServiceURL>, <ServiceIdentity>, and <DisplayName> elements to the proper values for your grid. Save the file.

2. For websso-properties.xml, you will need to change the values of the <ServiceURL> and <ServiceIdentity>, and <host-identity> elements to the proper values for your grid. Save the file.

3. For sync-description.xml, you will need to modify the following values to match your grid properties: <ns1:gtsServiceURI>,<ns1:GTSIdentity>, and <ns1:CASubject>. Save the file.

4. For workflow-ui-configuration.xml, you will need to modify the <value> property to match your grid properties. Save the file.

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

6. Replace the root certificate and signing policy file in the certificates folder with your Grid's root certificate and policy file.

Note: the certificate to add is the Grid's trusted root certificate, which is the certificate that corresponds to the CA used to generate the GTS host certificates.

Modify the ivy xml

Now that all files have been copied to your grid folder and modified, we can change 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 names to match your root certificate.

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

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:

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

Modify the installer.properties file

Download the caGrid installer that corresponds to your version of caGrid.
Unzip the file. We will refer to this directory as ORIG_CAGRID_LOCATION.
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
Locate and open the download.properties file in a text editor
Copy the url from the file and paste it into a web browser.
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
Open the file in a text editor

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.

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.

Re-open the download.properties file.

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.

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.