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

Dorian

Dorian Installation Guide

Dorian: Administrators Guide | Developers Guide | Users Guide | caGrid: Documentation Guides

Contents

Overview

This guide provides step-by-step details on how to install and configure Dorian version 1.3.

Prerequisites

To install and run Dorian, the following prerequisite software must be installed:

  1. Java 1.5 JDK or Greater
  2. Mysql 5 or Greater
  3. (Optional) Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files (Java 5, Java 6) must be installed in the JVM if you are operating Dorian with a SafeNet Protect Server Gold Hardware Security Module.

Step 1: Install caGrid/Dorian

In this step you download and install Dorian using the caGrid Installer. If you already have caGrid 1.3 installed, you may proceed to the next step. To install caGrid/Dorian, complete the following steps:

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

  1. Download the caGrid 1.3 Installer. The downloaded installer should be contained in the file caGrid-installer-1.3.zip.
  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.
The installer installs caGrid to the directory you specified during installation. From this point forward we refer to this directory as CAGRID_HOME. Dorian can be found in the directory CAGRID_HOME/projects/dorian; from this point forward we refer to this directory as DORIAN_HOME. The GAARDS UI or graphical user interface for administrating Dorian is located in CAGRID_HOME/projects/gaardsui; from this point forward, we refer to this directory as GAARDS_UI_HOME.

Step 2: Configure Dorian

For most installations of Dorian, only minor edits to the Dorian properties file are required. Most installations only require edits to the database properties and certificate authority properties.

Edit the following properties in the file DORIAN_HOME/etc/dorian.properties:

Property Name
Description
gaards.dorian.db.host The host name of the server running the Mysql database.
gaards.dorian.db.port The port that the Mysql database binds to.
gaards.dorian.db.user The user ID of the Mysql database user that Dorian should use for connecting to Mysql.
gaards.dorian.db.password The password of the Mysql database user that Dorian should use for connecting to Mysql.
gaards.dorian.ca.auto.create.subject The Distinguished Name to use in creating the Dorian Certificate Authority Certificate.

**It is important to note that the configuration changes specified thus far are the minimum configuration required for simple deployments of Dorian. Complete details on configuring Dorian can be accessed by clicking here_ These details include configuring some of the more advanced features such as using a Hardware Security Module (HSM) for the storage of keys or for details on integrating Dorian with the Grid Trust Service (GTS).**_

Step 3: Edit Service Metadata

Dorian 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 Dorian service metadata file, DORIAN_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, Dorian 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 Dorian. 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 4: Generate Host Credentials for Dorian

Dorian operates as a secure web service that requires all communication between clients and Dorian to be encrypted. To run as a secure service, the container hosting the service must run with a host credential. A host credential consists of an X.509 certificate and a private key. Dorian can issue and manage host credentials. Although you may obtain a host credential elsewhere, Dorian has a command line utility that can be used to issue a host credential for the container in which it will run. To leverage this command line utility, type the following from a command prompt:

 $ cd DORIAN_HOME
 $ ant createDorianHostCredentials
You are immediately prompted for the name of the host that will be running Dorian. Enter the host name and press Enter. You are then prompted to enter a directory to which the host certificate and private key should be written. Enter the directory location and press Enter. The utility then creates a host certificate and private key for Dorian and informs you where on the file system they were written. The entire output of the program is shown below:

$ ant createDorianHostCredentials
Buildfile: build.xml

setGlobus:

checkGlobus:
     [echo] Globus: C:\ext\ws-core-4.0.3

createDorianHostCredentials:
    [input] Please enter the host:
somehost.example.com
    [input] Please enter the directory to write out the host credentials:
c:/certificates
     [java] /C=US/O=abc/OU=xyz/OU=caGrid/OU=Dorian IdP/CN=dorian
     [java] Successfully created the host certificate:
     [java] Subject: C=US,O=abc,OU=xyz,OU=caGrid,OU=Services,CN=host/somehost.ex
ample.com
     [java] Created: Thu Jun 21 19:21:45 EDT 2007
     [java] Expires: Sat Jun 21 19:21:45 EDT 2008
     [java] Succesfully wrote private key to c:\certificates\somehost.example.co
m-key.pem
     [java] Succesfully wrote certificate to c:\certificates\somehost.example.co
m-cert.pem

BUILD SUCCESSFUL
Total time: 29 seconds

Step 5: Configure the Container

In this step we configure a web service container that will host Dorian.  Dorian can be deployed to the Tomcat, JBoss, and Globus containers. This guide provides 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 earlier.

  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 Browse host credentials on the file system and click Next.
    If you do not yet have credentials for your service, then Request Credentials.
  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.
  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 6: Configuring the Container to Trust the Dorian CA

To administer Dorian through its web service interface you will need to authenticate with Dorian using your credentials issued by Dorian.  Authentication is handled by the Globus , the underlying toolkit on top of which Dorian is built. Dorian/Globus only accepts credentials from certificate authorities that it trusts, thus we must configure the Globus environment to trust and accept credentials from the Dorian instance. Dorian provides a command line utility for accomplishing this, which can be run as follows:

$ cd DORIAN_HOME
$ ant configureGlobusToTrustDorian
Buildfile: build.xml

setGlobus:

checkGlobus:
     [echo] Globus: /Users/langella/ext/ws-core-4.0.3

defineClasspaths:

defineExtendedClasspaths:

init:

checkValidate:

preInit:

configure:
     [copy] Copying 1 file to /Users/langella/releases/caGrid-1.3/projects/dorian

postInit:

configureGlobusToTrustDorian:
     [java] Succesfully configured Globus to trust the Dorian CA: C=US,O=abc,OU=xyz,OU=caGrid,CN=caGrid Dorian CA
     [java] Succesfully wrote CA certificate to /Users/langella/.globus/certificates/2d45eee5.0
     [java] Succesfully wrote CA signing policy to /Users/langella/.globus/certificates/2d45eee5.signing_policy

BUILD SUCCESSFUL
Total time: 2 seconds
For additional details on Authentication and for configuring Dorian/Globus Authentication, consult the [Grid Authentication Guide].

Step 7: Configure SyncGTS to Ignore the Dorian CA

If you DID NOT select a Target Grid when installing Dorian/caGrid, please proceed to the next step. If you selected a Target Grid when you installed Dorian/caGrid, the installer will install a plugin called SyncGTS which will configure Dorian/Globus to ONLY accept credentials from credential providers that are trusted by the target grid you selected. This means that when the container starts, it does not trust the Dorian CA that we told it to trust in the last step. To fix this, we edit SyncGTS's configuration such that it also accepts credentials from the Dorian we are instantiating. This is more of a temporary solution to get things up and running for testing purposes.  In a production environment, the Dorian you are instantiating should be added to the list of trusted credential providers for the Grid in which it is operating, otherwise other services will not accept credentials from this instance of Dorian. For more details on this, read about configuring the trust fabric.

To edit SyncGTS's configuration such that it Dorian/Globus trusts the Dorian being installed and the credential providers trusted in the target grid, make the following edits to the file, CATALINA_HOME/webapps/wsrf/WEB-INF/etc/cagrid_SyncGTS/sync-description.xml.

  1. Locate the element ExcludedCAs (Shown Below): 
    <ns1:ExcludedCAs>
    <ns1:CASubject>O=caBIG,OU=caGrid,OU=Training Trust Fabric,CN=caGrid Training Trust Fabric CA</ns1:CASubject>
</ns1:ExcludedCAs>
  2. Add an additional child element CASubject containing the value you entered for the gaards.dorian.ca.auto.create.subject property in DORIAN_HOME/etc/dorian.properties. 
    <ns1:ExcludedCAs>
    <ns1:CASubject>O=caBIG,OU=caGrid,OU=Training Trust Fabric,CN=caGrid Training Trust Fabric CA</ns1:CASubject>
    <ns1:CASubject>C=US,O=abc,OU=xyz,OU=caGrid,CN=caGrid Dorian CA</ns1:CASubject>
</ns1:ExcludedCAs>

Step 8: Deploy Dorian

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

 $ cd DORIAN_HOME
 $ ant deployTomcat
If you chose to use a JBoss container, Dorian can easily be deployed by typing the following at a command prompt:

 $ cd DORIAN_HOME
 $ ant deployJBoss
Although the installer does not support configuring a secure Globus container, Dorian can be deployed to a secure Globus container by typing the following at the command prompt:
 $ cd DORIAN_HOME
 $ ant deployGlobus
No matter which container you choose, you see a significant amount of output on the screen. If the deployment is successful, you see the words BUILD SUCCESSFUL on the screen.

Step 9: Start Dorian

  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

Once you have deployed Dorian, you have completed the installation and configuration of Dorian. Next we will verify that the installation was successful. Before doing so, however, we must start the Dorian service. This is done by starting the container to which Dorian was deployed.

To start a secure Tomcat container, run the startup script (startup.sh or startup.bat) located in CATALINA_HOME/bin. Check the Tomcat log files (CATALINA_HOME/log/catalina.out) to ensure that there are no error or stacktraces and that the container successfuly started and bound to the port you specified during the installation. Once the container starts, we are ready to verify that the Dorian installation was successful. To accomplish this we use the GAARDS UI, which is a graphical user interface for administering security services such as Dorian. Specifically, we use the GAARDS UI to ensure that we can successfully authenticate using Dorian's default administrative account. To do this, complete the following steps:

  1. Type the following from a command prompt:
     $ cd GAARDS_UI_HOME
     $ ant ui

  2. Select Window > Preferences. The Preference window appears.
  3. From the preferences tree on the left side of the window, expand the User Management node and then click the Dorian node.
  4. In the Display Name field on the right side of the window, enter Localhost.
  5. In the Service URL text field, enter "https://localhost:8443/wsrf/services/cagrid/Dorian", replacing the port (8443) with the port you configured during installation.
  6. Click Add.
  7. Click Save.
  8. Click Login. A Login screen appears.
  9. From the Credential Provider list, select Localhost.
  10. From the Organization list, select Dorian.
  11. In the User Id text box, enter dorian
  12. In the Password text box, enter DorianAdmin$1
  13. Click Authenticate.

Dorian Preferences

Login Window

After clicking the Authenticate button you will be logged onto Dorian using the default administrator (dorian). If the login is successful a dialog will be displayed informing you that you have succesfully logged on.  Congratulations you have successfully installed and configured Dorian!!!

Step 11: Add the Dorian Certificate Authority to GTS

See these instructions for adding the Dorian Certificate Authority to GTS.

Step 12: Add the GTS Authorization for the New Dorian Identity

  1. Enter the following at a command prompt. 
     $ cd $CAGRID_HOME 
    
 $ ant security
  2. Click Login.
  3. Enter a user and password of a user with administration privileges.
  4. Click Login.
  5. Select Trust Fabric > Access Control. The Access Control window appears.
  6. From the Service list, select the Master GTS.
  7. Click Search.
  8. Select the row in the table that shows Dorian's Training ID
    Grid Identity = "/O=caBIG/OU=caGrid/OU=Training/OU=Services/CN=dorian.training.cagrid.org"
    Trusted Authority = "O=caBIG,OU=caGrid,OU=Training,CN=caGrid Training CA"
    Role = "TrustAthorityManager"
  9. Click Remove. This removes the Training Grid Dorian identity's rights to publish a CRL.
  10. Click Add to give the new Dorian Identity rights to publish a CRL. The Add Permission Window appears.
  11. In the Grid Identity text box, enter the grid identity of your Dorian.
  12. From the Trusted Authority list, select the certificate authority Dorian manages.
  13. From the Role list, make sure TrustAthorityManager is selected.
  14. Click Add. This adds the permission to the GTS.
Last edited by Carolyn Kelley Klinger (72 days ago), ...
Adaptavist Theme Builder Powered by Atlassian Confluence
Free theme builder license