Grid Grouper 1.1 Quick Start Guide

	Table of Contents 1 Grid Grouper 1.1 Quick Start Guide 2 Grid Grouper Installation and Configuration 2.1 Step 1: Install Prerequisite Software 2.2 Step 2: Building Grid Grouper 2.3 Step 3: Obtain a Host Credential 2.4 Step 4: Configure Globus to Trust Grid Grouper 2.5 Step 5: Configuring a Secure Container 2.6 Step 6: Configuring Grid Grouper 2.7 Step 7: Adding Initial Grid Grouper Administrator(s) 2.8 Step 8: Deploying Grid Grouper 2.9 Step 9: Verifying the Installation

Grid Grouper Installation and Configuration

Grid Grouper is distributed as standalone project as well as part of other projects such as caGrid. Each of the distributions contains a gridgrouper directory herein referred to as GRID_GROUPER_LOCATION. To install and configure Grid Grouper please follow the steps below.

Step 1: Install Prerequisite Software

In order to install and run Grid Grouper, it is required that the following prerequisite software is installed:

• Java 1.5 JDK
• Ant 1.6.5
• Globus WS-Core with WS-Enum Support
• MySQL
• (Optional) If you want to deploy services to tomcat, you will need Tomcat 5.0.28

Step 2: Building Grid Grouper

If you have obtained a source release of Grid Grouper you will need to build Grid Grouper. To build Grid Grouper type the following from a command prompt:

%> cd GRID_GROUPER_LOCATION
%> ant clean all

**Depending on the Grid Grouper distribution it may be required to build the entire project that Grid Grouper is distributed with prior to building Grid Grouper. For example if you have obtained a caGrid source distribution this is required, if you received a Grid Grouper standalone distribution this is not required.**

Step 3: Obtain a Host Credential

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. One of the features Dorian provides is the ability to issue and manage host credentials. There are many methods of retrieving host credentials, these methods include but are not limited to the following:

1. Requesting a credential from a known/trusted certificate authority (caGrid Certificate Authority).
2. Standing up a Dorian service.
3. Standing up a simple certificate authority.

For production environments it is recommended that you obtain a host credential from a trusted certificate authority (option 1), such as a caGrid Certificate Authority. Standing up a Dorian(option 2) is another solid option especially if you wish to run your own production Certificate Authority. Standing up a simple certificate authority (option 3) is not recommended for production environments but is an excellent option for quickly obtaining a host credential for testing purposes.

If you have a host credential already or you have a method of obtaining (option 1 or option 2) one please proceed to the next step, otherwise for the purposes of this guide we will create our own certificate authority (option 3) and use it to issue a host credential. To create a certificate authority please complete the following steps from a command prompt(illustrated below):

1. cd GRID_GROUPER_LOCATION
2. Type ant generateCA
3. Enter the distinguished name (DN) for the CA (i.e O=xyz,OU=abc,CN=My CA).
4. Enter the number of days that the CA will be valid for (i.e 3650)
5. Enter a password which will be used to encrypt the CA's private key.
6. Enter a file to write the CA private key to.
7. Enter a file to write the CA certificate to.

   %> cd GRID_GROUPER_LOCATION
   %> ant generateCA
   Buildfile: build.xml
   
   setGlobus:
   
   checkGlobus:
        [echo] Globus: C:\ext\ws-core-4.0.3
   
   generateCA:
       [input] Please enter the DN for the new CA (ex. O=xyz,OU=abc,CN=My CA):
   O=xyz,OU=abc,CN=My CA
       [input] Please enter the number of days the new CA will be valid for:
   3650
       [input] Please enter a password for the new CA:
   password
       [input] Please enter a location to write the new CA's private key:
   cakey.pem
       [input] Please enter a location to write the new CA's certificate:
   cacert.pem
        [java] Successfully create the CA certificate:
        [java] O=xyz,OU=abc,CN=My CA
        [java] CA Certificate Valid Till:
        [java] Fri Jun 23 12:47:10 EDT 2017
        [java] CA Private Key Written to:
        [java] cakey.pem
        [java] CA Certificate Written to:
        [java] cacert.pem
   
   BUILD SUCCESSFUL
   Total time: 46 seconds
   

Once we have created a certificate authority we can use it to issue a host credentials. To create host credentials please complete the following steps from a command prompt(illustrated below):

1. cd GRID_GROUPER_LOCATION
2. Type ant createAndSignHostCertificate
3. Enter the location of the CA's private key.
4. Enter the password used to encrypt the CA's private key.
5. Enter the location of the CA's certificate.
6. Enter the name of the host.
7. Enter the number of days that the host credentials should be valid for.
8. Enter a location to write the host private key.
9. Enter a location to write the host certificate.

   %> cd GRID_GROUPER_LOCATION
   %> ant createAndSignHostCertificate
   Buildfile: build.xml
   
   setGlobus:
   
   checkGlobus:
        [echo] Globus: C:\ext\ws-core-4.0.3
   
   createAndSignHostCertificate:
       [input] Please enter the location of the CA's private key:
   cakey.pem
       [input] Please enter the CA's password:
   password
       [input] Please enter the location of the CA's certificate:
   cacert.pem
       [input] Please enter the Hostname [${env.HOST}]:
   myhost
       [input] Please enter the number of days the host certificate will be valid f
   or:
   365
       [input] Please enter a location to write the host key:
   hostkey.pem
       [input] Please enter a location to write the host certificate:
   hostcert.pem
        [java] Successfully create the user certificate:
        [java] O=xyz,OU=abc,CN=host/myhost
        [java] User certificate issued by:
        [java] O=xyz,OU=abc,CN=My CA
        [java] User Certificate Valid Till:
        [java] Wed Jun 25 13:58:37 EDT 2008
        [java] User Private Key Written to:
        [java] hostkey.pem
        [java] User Certificate Written to:
        [java] hostcert.pem
   
   BUILD SUCCESSFUL
   Total time: 52 seconds
   

Step 4: Configure Globus to Trust Grid Grouper

In order to securely invoke Grid Grouper, we MUST configure Globus to trust the CA that issued the host credentials we obtained in the previous step. To do this we place a copy of the certificate for the CA that issued the host credentials in the Globus trusted certificates directory. Unless otherwise specified during installation, the Globus trusted certificate directory 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 than in order to configure Globus to trust this certificate authority it should be copied in to the directory USER_HOME/.globus/certificates (create directory if needed) with the file name cacert.0

Step 5: Configuring a Secure Container

Now that you have obtained host credentials, you may use them to configure a secure container. Grid Grouper can be run from a secure Globus container or a secure Tomcat container. For directions on how to configure a secure Globus container CLICK HERE. For directions on how to configure a secure Tomcat container CLICK HERE.

Step 6: Configuring Grid Grouper

To configure GridGouper you must specify your Mysql database information in the grouper.hibernate.properties configuration file located in GRID_GROUPER_LOCATION/resources/conf/. The properties you need to edit are highlighted in bold in below, mainly the database connection URL, database username, and database password.

#MySQL
hibernate.dialect                     =net.sf.hibernate.dialect.MySQLDialect
hibernate.connection.driver_class     = com.mysql.jdbc.Driver
hibernate.connection.url              = jdbc:mysql://localhost:3306/grouper
hibernate.connection.username         = root
hibernate.connection.password         = YOUR_PASSWORD

Once you have edited the Grid Grouper configuration file, initialize the Grid Grouper database by manually creating the grouper database in MySQL. The database should be name as configured in the hibernate.connection.url property of the grouper.hibernate.properties configuration file. Once you have created the database, enter ant grouperInit to build out and initialize the Grouper/Grid Grouper database.

Step 7: Adding Initial Grid Grouper Administrator(s)

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_LOCATION
%> ant addAmin

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: Deploying Grid Grouper

Once you have configured a secure container (Globus or Tomcat) you need to deploy Grid Grouper to that container. To deploy Grid Grouper to a secure Globus container type the following from a command prompt:

%> cd GRID_GROUPER_LOCATION
%> ant deployGlobus

To deploy Grid Grouper to a secure Tomcat container type the following from a command prompt:

%> cd GRID_GROUPER_LOCATION
%> ant deployTomcat

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

Step 9: 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. For directions on starting a secure Globus container CLICK HERE. To start a secure Tomcat container run the startup script (startup.sh or startup.bat) located in TOMCAT_INSTALLATION_DIRECTORY/bin. If the container starts up we are ready to verify that the Grid Grouper installation was successful. To do so type the following from the command prompt:

%> cd GRID_GROUPER_LOCATION
%> ant ui

This will bring up a the Grid Grouper Administration UI, after the UI opens please complete the following steps:

1. Click the Group Browser button, this will bring up a Group Browser window.
2. Click the Add Grid Grouper button, this will bring up the Add Grid Grouper Dialog
3. From the Grid Grouper drop down select https://localhost:8443/wsrf/services/cagrid/GridGrouper
4. Click the Add button.

After clicking the Add button the UI will add the Grid Grouper, https://localhost:8443/wsrf/services/cagrid/GridGrouper to the Grid Grouper Service(s) tree and will populate a stem/group hierarchy in a sub tree. In the hierarchy the should be one stem, Grouper Administration and under that stem there should be one group, Grid Grouper Administrators. This is illustrated in the screen shot below. Congratulations you have successfully installed and configured Grid Grouper.