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

Grid Grouper

Grid Grouper Installation Guide

Grid Grouper: Administrators Guide | Developers Guide | caGrid: Documentation Guides

Contents

Overview

This guide provides step by step details on how to install and configure Grid Grouper version 1.3.

Prerequisites

In order to install and run Grid Grouper, the following prerequisite software must be installed:

  1. Java 1.5 JDK or Greater
  2. Mysql 5 or Greater

Step 1: Install caGrid/Grid Grouper

In this step you download and install Grid Grouper using the caGrid Installer. If you already have caGrid 1.3 installed on your machine, proceed to the next step. To install caGrid/Grid Grouper, do the following.

Installer Prerequisites

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

  • Java 1.5 JDK
  • (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.
  • Make sure the JAVA_HOME environment variable is set and points to the correct location.

Installing caGrid 1.3 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:
  1. Download the caGrid 1.3 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.3.zip. If you are using a customized installer the name may vary.

  2. Unzip the file caGrid-installer-1.3.zip. This creates the directory caGrid-installer-1.3. This documentation refers to this directory as CAGRID_INSTALLER_LOCATION.

  3. From a command prompt, launch the installer using the following command: 
     > cd <CAGRID_INSTALLER_LOCATION>
    
> java -jar caGrid-installer-1.3.jar
  4. Select the I agree to this license checkbox and then click  Next.
  5. Select the Install/Configure caGrid Software checkbox and then click  Next.
  6. 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.

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

  8. 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.
  9. 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.
  10. Once the installer has completed installing all the components, click  Next.
  11. 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.
  12. 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.
  13. 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 places caGrid in the directory you specified during installation. From this point forward we refer to this directory as CAGRID_HOME. Grid Grouper can be found in the directory CAGRID_HOME/projects/gridgrouper, from this point forward we will refer to this directory as GRID_GROUPER_HOME.  The GAARDS UI or graphical user interface for administrating Grid Grouper is located in CAGRID_HOME/projects/gaardsui, from this point forward we will refer to this directory as GAARDS_UI_HOME.

Step 2: Obtain Host Credentials

Grid Grouper requires that it runs as a secure service. In order to run a secure service, the container hosting the service must run with a host credential. A host credential consist of a X.509 certificate and private key.  In production environment it is very important that this credential be issued by a certificate authority that your environment trusts.  For the purposes of this guide we will provide instructions on how to obtain a host credential from Dorian.  Dorian is an open source service framework for issuing PKI credentials and is a trusted certificate authority in many Grid environments.   Most target Grids (selected in the last step) are configured with one or more Dorian instances.  For the purposes of this guide we will provide documentation on requesting a host credential from the Training Dorian, similiar steps can be used for requesting a host credential from other Dorian instances.

To request a host credential from the Training Dorian, you must have must have an account.  Any user may request an account from the Training Dorian.  If you have an account with the Training Dorian, please complete the steps below to get a host credential, other wise click here for directions on requesting an account and then proceed with the steps below:

  1. Launch the GAARDS UI
  2. Log onto the Grid.
  3. From the MyAccount menu, select Request a Host Certificate, this will launch the Request a Host Certificate window.
  4. From the Service drop down select the Dorian you wish to request a host certificate from.
  5. In the Host text box, enter the name of the host you are requesting a host certificate for.
  6. Next you must specify the directory on the file system where the host credentials should be written to, this can be done by clicking the Browse button.
  7. Click the Request Certificate button.

Request Host Certificate

Immediately after clicking the Request Certificate button, the UI will submit the host certificate request to Dorian. Upon receiving the request Dorian will either immediately approve the request or submit the request to administrator for approval. In the case where the request is immediately approved, the host credentials (certificate and private key) will be written to the directory specified. The file containing the certificate will be named THE_HOSTNAME_YOU_ENTERED-cert.pem, the file containing the private key will be named THE_HOSTNAME_YOU_ENTERED-key.pem.

In the case where host certificate request requires approval of an administrator, the file containing the private key will be named THE_HOSTNAME_YOU_ENTERED-key.pem. The host certificate WILL NOT be written since it is not issued until the request is approved.  You will need to wait for an administrator to approve your request before proceeding forward.  The GAARDS UI provide a means of checking the status of your request, for directions on how to do this click here.

Please note down the location that the host certificate and private key were written to. These will be needed later to configure your container.

Step 3: Configure a Secure Container

In this step we will configure a web service container that will host Grid Grouper.   Grid Grouper can be deployed to the Tomcat, JBoss, and Globus containers.  For the purposes of this guide we will  provide detailed 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.

Have a Copy of the .cagrid/certificates Directory
Make sure that you have a copy of the $HOME/.cagrid/certificates directory. There is a bug in the installer that can sometimes corrupt the files in this directory.

After you are finished performing the following steps, check the contents of the $HOME/.cagrid/certificates directory. If the files in this directory have a zero length, they are corrupted. In this case, copy the files from the copy of the $HOME/.cagrid/certificates directory into the directory.

  1. From a command prompt, launch the caGrid Installer: 
     > cd <CAGRID_INSTALLER_LOCATION> 
     > java -jar caGrid-installer-1.3.jar
  2. Select the I agree to this license checkbox and then click Next.
  3. Select the Install/Configure Grid Service Container checkbox and then click Next.
  4. Select the Container you to which you want to deploy your service. This guide will use Tomcat. Select the Should this container be secure? checkbox and then click Next.
  5. In the hostname checkbox, 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 edit configuration files manually 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, then select Use GAARDS to obtain host credentials.
    • If you have host credentials that are not in the default location, then select Browse to host credential on the file system
    • If you have host credentials that are in the default location, then select Host credentials are already installed

    Note: Use of the Copy in host credentials manually option is not recommended. Use the Browse to host credential on the file system option instead.


    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. Enter the location of your host certificate into the Certificate text checkbox. Enter the location of your private key into Key text checkbox. Click Next. Note: after this step, verify that your host certificate and private key files exist. Verify that the size of these files is greater than zero. If the filesize is zero for either file, restore it from a backup copy.
  8. The next screen asks where you want to install Tomcat. Enter that location in the Directory text checkbox and click Next.
    Avoid Blanks in the Container Path
    Do not choose a name or path for the container that contains any blanks. In particular, in a Windows environment, do not put the container under directories such as "Documents and Settings" or "My Documents".
  9. A list of tasks appears that the installer will perform to install and configure Tomcat. Click Next.
  10. Once the installer has completed installing all 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 4: Configure Grid Grouper

To configure Grid Gouper you must specify the database information for your MySQL database.  This is specified in the configuration file, GRID_GROUPER_HOME/resources/conf/grouper.hibernate.properties. To configure the database information for grid grouper open up the file, GRID_GROUPER_HOME/resources/conf/grouper.hibernate.properties and edit the following properties:

Property
Description
hibernate.connection.url The connection URL for the Mysql database, this includes the name of the database.
hibernate.connection.username The username of the database user.
hibernate.connection.password The password of the database user.

Step 5: Initialize Grouper Database

In this step we will create and initialize the Grid Grouper database.  To create the database please type the following from the command line:

 > mysql -u YOUR_DATABASE_USER -p
 Enter password: YOUR_DATABASE_PASSWORD 
 create database grouper;
Once you have created the database, it can be initialized by typing the following from the command line:

 > cd GRID_GROUPER_HOME
 > ant grouperInit
At this point the initialization utility, will initialize the grouper database, you should output suggesting that the database has been successfully initialized.

Step 6: Configure Default Storage Engine

The default storage engine for MySQL, MyIASM, cannot handle a large number of concurrent write operations in a short amount of time. We'll need to change the storage engine of the Grouper tables to InnoDB. InnoDB was developed to handle a larger number of transactions.

 > mysql -u YOUR_DATABASE_USER -p
 Enter password: YOUR_DATABASE_PASSWORD 
 
> use grouper;

> ALTER TABLE gridgrouper_membershiprequests ENGINE = InnoDB;

> ALTER TABLE grouper_attributes ENGINE = InnoDB;

> ALTER TABLE grouper_composites ENGINE = InnoDB;

> ALTER TABLE grouper_fields ENGINE = InnoDB;

> ALTER TABLE grouper_groups ENGINE = InnoDB;

> ALTER TABLE grouper_groups_types ENGINE = InnoDB;

> ALTER TABLE grouper_members ENGINE = InnoDB;

> ALTER TABLE grouper_memberships ENGINE = InnoDB;

> ALTER TABLE grouper_owners ENGINE = InnoDB;

> ALTER TABLE grouper_sessions ENGINE = InnoDB;

> ALTER TABLE grouper_settings ENGINE = InnoDB;

> ALTER TABLE grouper_stems ENGINE = InnoDB;

> ALTER TABLE grouper_types ENGINE = InnoDB;

> ALTER TABLE subject ENGINE = InnoDB;

> ALTER TABLE subjectattribute ENGINE = InnoDB;

Step 7: Add Initial Administrator

In order to administrate Grid Grouper, Grid Grouper must be initially provided with at least one administrator. Grid Grouper provides a command line tool for bootstrapping GridGrouper and initially adding administrator(s). To levergage this command line utility type the following from a command prompt:

 > cd GRID_GROUPER_HOME
 > ant addAdmin
This will prompt you for the grid identity of the initial administrator to add, please enter the grid identity of the user you want to add as an initial administrator and hit enter.

Step 8: Edit Service Metadata

Grid Grouper 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 Grid Grouper service metadata file, GRID_GROUPER_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, Grid Grouper 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 Grid Grouper. 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.

Step 9: Deploy Grid Grouper

At this point we have completed configuring Grid Grouper and the Tomcat container Grid Grouper will run in.  We are now ready to deploy Grid Grouper to the Secure Tomcat Container. This can be done as follows from a command prompt:

 >cd GRID_GROUPER_HOME
 > ant deployTomcat

If you chose to use a JBoss container, Grid Grouper can easily be deployed by typing the following at a command prompt:

 > cd GRID_GROUPER_HOME
 > ant deployJBoss

Although the installer does not support configuring a secure Globus container, Grid Grouper can be deployed to a secure Globus container by typing the following at the command prompt:

 > cd GRID_GROUPER_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: Verifying the Installation

Once you have deployed Grid Grouper, you have completed the installation and configuration of Grid Grouper. Next we will verify that the installation was successful, however before doing so we must start the Grid Grouper service. This is done by starting the container that Grid Grouper was deployed to. To start a secure Tomcat container run the startup script (startup.sh or startup.bat) located in CATALINA_HOME/bin.   Please 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.   Once the container has started we are ready to verify that the Grid Grouper installation was successful.   To accomplish this we will use the GAARDS UI which is a graphical user interface for administering security services such as Grid Grouper.   Specifically we verify that the administrators group was successfully created and that the initial administrators of the group were added.  In order to accomplish this we must first configure the GAARDS UI to be able to communicate with the Grid Grouper we just instantiated, to accomplish this please complete the following steps:

Type the following from a command prompt:

$ cd GAARDS_UI_HOME
$ ant ui
  1. From the Window menu select Preferences , this will launch the Preference window.
  2. On the left side of the window there will be a preferences tree, expand the Group Management node and then click on the Grid Grouper Service(s) node. On the right side of the screen you should see a list of Grid Grouper Service(s).
  3. In the Display Name text field, enter Localhost.
  4. In the Service URL text field, enter "https://localhost:8443/wsrf/services/cagrid/GridGrouper", replacing the port (8443) with the port you configured during installation.
  5. Click the Add button.
  6. Click the Save button.

Next we must Login in as one of the initial administrators we created earlier.  To accomplish this complete the following steps:

  1. Click the Login button. The Login screen appears.
  2. From the Credential Provider list, select the Dorian that issued your administrators credential.
  3. From the Organization list, select the identity provider of the administrator.
  4. In the User Id text box enter the user id of the administrator.
  5. In the Password text box enter the password of the administrator.
  6. Click the Authenticate button.

Next we will verify that we can view the administrators group for Grid Grouper. To accomplish this, complete the following steps:

  1. Select Group Management > Group Browser. The Group Browser window appears.
  2. Click the Add Grid Grouper button. The Add Grid Grouper window appears.
  3. From the Grid Grouper list, select Localhost.
  4. From the Credentials list, select Globus Default Proxy.
  5. Click the Add button. This adds the Grid Grouper to the tree in the Group Management window.
  6. Expand the https://localhost:8443/wsrf/services/cagrid/GridGrouper node.
  7. Expand the Grouper Administration node.
  8. Select the Grid Grouper Administrators group.
  9. Click the View button. The details of this group appear to the right of the tree.
  10. Select the Member tab.
  11. Click the Search button.

This lists all the members of the grid grouper administrators group in the table below the Search button. You should see the grid identity of the initial administrator you added earlier through the command line.

Congratulations! You have successfully installed Grid Grouper.

Grid Grouper Preferences

Login Window

Grid Grouper Administrators
Last edited by
Sarah Honacki (738 days ago) , ...
Adaptavist Theme Builder Powered by Atlassian Confluence