Dorian Installation Guide
Dorian: Administrators Guide | Developers Guide | Users Guide | caGrid: Documentation Guides
Overview
This guide provides step-by-step details on how to install and configure Dorian version 1.4.
Prerequisites
To install and run Dorian, the following prerequisite software must be installed:
- Java 6 JDK or Greater
- Mysql 5 or Greater

- (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.4 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 6 JDK
- Make sure the JAVA_HOME environment variable is set and points to the location where the JDK has been installed.
- (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.
Installing caGrid 1.4 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:
|
- Download the caGrid 1.4 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.4.zip. If you are using a customized installer the name may vary.
- Unzip the file caGrid-installer-1.4.zip. This creates the directory caGrid-installer-1.4. This documentation refers to this directory as CAGRID_INSTALLER_LOCATION.
- From a command prompt, launch the installer using the following command:

Do not launch the installer by double-clicking the jar file 
> cd *CAGRID_INSTALLER_LOCATION*
> java -jar caGrid-installer-1.4.jar - Select the I agree to this license checkbox and then click Next.
- Select the Install/Configure caGrid Software checkbox and then click Next.
- 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.
- 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.
- 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. - 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.
- Once the installer has completed installing all the components, click Next.
- 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.
- 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.
- 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. |
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. For security reasons, the recomended value is localhost. |
| 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.
If you are installing Dorian for a new grid, then the value for this property should be based on the one-word grid name you chose while working through the caGrid Installation Guide. The pattern you should use for the value of this property is O=[GRID_NAME],OU=LOA1,CN=[GRID_NAME] Dorian CA For example, if the one-word grid name is abc then the value for this property should be O=abc,OU=LOA1,CN=abc Dorian CA |
| gaards.dorian.federation.certificate.lifetime.years | This is the number of years until the Dorian certificate authority will need to have its certificate renewed. A good value for this is 5 |
| gaards.dorian.federation.crl.publish | If you are installing Dorian for a new grid, this will be the URL for the master GTS service. |
| There is More! It is important to note that the configuration changes specified above are the minimum configuration changes 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 more 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:
- Open the Dorian service metadata file, DORIAN_HOME/etc/serviceMetadata.xml.
- In the hostingResearchCenter element near the bottom of the file, do the following.
- Supply your ResearchCenter infomation.
- Supply your Address. This is the address that is used when mapping your service on the caGrid Portal.
- 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: Configuring the Container to Trust the Dorian CA
| If you Repeat this Step This step creates the MySql database for which you supplied parameters in step 2. If you are repeating this step for any reason, you must log into MySql using those parameters and drop the Dorian database before proceeding. From the command line, dropping the Dorian database looks like this: mysql --user=root -p Enter password: mysql> drop database Dorian; mysql> \q |
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: /home/gridAdmin/ws-core-4.0.3
defineClasspaths:
defineExtendedClasspaths:
init:
checkValidate:
preInit:
configure:
[copy] Copying 1 file to /home/gridAdmin/caGrid/projects/dorian
postInit:
configureGlobusToTrustDorian:
[java] Succesfully configured Globus to trust the Dorian CA: O=abc,OU=LOA1,CN=abc Dorian CA
[java] Succesfully wrote CA certificate to /Users/gridAdmin/.globus/certificates/2d45eee5.0
[java] Succesfully wrote CA signing policy to /home/gridAdmin/.globus/certificates/2d45eee5.signing_policy
BUILD SUCCESSFUL
Total time: 2 seconds
For additional details on Authentication and for configuring Dorian/Globus Authentication, consult the caGrid Security - The Trust Fabric (Powerpoint Presentation)
.
| Backup the Dorian CA Certificate Backup the CA Cerfiticate and Signing Policy to a safe location. |
Step 5: Generate Host Credentials for Dorian
| If you Repeat this Step You should not repeat this step without first repeating Step 4. |
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: /home/gridAdmin/ws-core-4.0.3
createDorianHostCredentials:
[input] Please enter the host:
dorian.abc.example.org
[input] Please enter the directory to write out the host credentials:
/home/gridAdmin/.cagrid/certificates
[java] O=abc,OU=LOA1,CN=abc Dorian CA
[java] Successfully created the host certificate:
[java] Subject: O=abc,OU=LOA1,CN=host/dorian.abc.example.org
[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 /home/gridAdmin/.cagrid/certificates/dorian.abc.example.org-key.pem
[java] Succesfully wrote certificate to home/gridAdmin/.cagrid/certificates/dorian.abc.example.org-cert.pem
BUILD SUCCESSFUL
Total time: 29 seconds
| Make a copy of the certificates directory. This will be useful if something bad happens to either of the files in the directory. We recommend that this copy be under the same parent .cagrid directory. |
Step 6: 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.
- From a command prompt, launch the caGrid Installer:

> cd \ CAGRID_INSTALLER_LOCATION
> java -jar caGrid-installer-1.4.jar - Select the I agree to this license box and then click Next.
- Select the Install/Configure Grid Service Container box and then click Next.
- Select the Container to which you want to deploy your service. Because this guide will use a secure Tomcat, select the Should this container be secure? box and then click Next.
- In the hostname box, 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 manually edit configuration files later to correct this. - 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, select Use GAARDS to obtain host credentials.
- If you have host credentials that are not in the default location, then select Browse to host credentials on the file system.
- If you have host credentials that are in the default location, then select Host credentials are already installed.
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".
- If you selected Browse to host credentials on the file system, the next screen will prompt you for the location of your credentials. Enter the location of your host certificate in the Certificate text box. Enter the location of your private key in the Key text box. Click Next.
- The next screen asks where you want to install Tomcat. Enter that location in the Directory text box and click Next.
- A list of tasks appears that the installer will perform in order to install and configure Tomcat. Click Next.
- Once the installer has completed installing all of the components, click Next.
- 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 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. Replace [GRID_NAME] with the one-word name you chose for the grid.
- Locate the element ExcludedCAs (Shown Below):
<ns1:ExcludedCAs> <ns1:CASubject>O=[GRID_NAME]OU=GTS,OU=Trust Fabric,CN=Trust Fabric CA</ns1:CASubject> </ns1:ExcludedCAs>
- 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=[GRID_NAME],OU=GTS,OU=Trust Fabric,CN=Trust Fabric CA</ns1:CASubject> <ns1:CASubject>O=[GRID_NAME],OU=LOA1,CN=[GRID_NAME] 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

$ cd DORIAN_HOME
$ ant deployGlobus
Step 9: Start Dorian
- 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. - If you chose a JBoss container, start JBoss as follows:
- Windows:

$JBOSS_HOME\run.bat
- Unix/Mac:

$JBOSS_HOME/run.sh
- Windows:
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:
- Type the following from a command prompt:

$ cd GAARDS_UI_HOME
$ ant ui - Select Window > Preferences. The Preference window appears.
- From the preferences tree on the left side of the window, expand the User Management node and then click the Dorian node.
- In the Display Name field on the right side of the window, enter Localhost.
- 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.
- Click Add.
- Click Save.
- Click Login. A Login screen appears.
- From the Credential Provider list, select Localhost.
- From the Organization list, select Dorian.
- In the User Id text box, enter dorian
- In the Password text box, enter DorianAdmin$1
- Click Login.
After clicking the Login 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 successfully logged on. Congratulations you have successfully installed and configured Dorian!!!
| Change the Dorian Password It is important to change the password for dorian to something that will be a secret. We suggest that you use a particularly strong password for this ID and any other IDs that have Dorian administrative privileges. Most user IDs maintained by Dorian become temporarily locked out if there are too many consecutive failed login attempts. This makes it much more difficult for hackers to crack passwords. However, Dorian user IDs that have administrative privileges for Dorian do not become locked out when there are failed login attempts. For this reason, it is important for Dorian administrator passwords to be particularly strong. |
Step 11: Configure Other Administrator IDs
| If you are NOT Installing Dorian as Part of a New Grid This step is not needed when you are adding a second Dorian to an existing grid. If the Dorian you are installing is not for a new grid, then skip to the step titled Add Dorian Certificate Authority to GTS |
Use the GAARDS UI to configure administrator IDs in Dorian for GTS and other services. When you installed the master GTS service you configured it to treat a particular user as a GTS administrator. Now that Dorian is working, you configure Dorian to provide grid credentials for that user.
There are some other services you may be installing that will also need to be configured to treat some user as its administrator. If you are going to be installing them, now is also a good time to set up the users that will administer CDS (Credential Delegation Service) or grid grouper, if you will be installing them.
There are two steps to creating new user IDs in Dorian.
- The first step is to use the GAARDS UI to register the new user ID.
- After a user ID is registered with Dorian, you must approve the registration before the user ID can be used. To approve account registrations, you use the use the GAARDS UI to login as a user that is a Dorian administrator. You then do a user search to find the pending user registration. Then select the found account and use the account information tab of the Manage User dialog to change the user status from Pending to either Active or Rejected.
Step 12: Configure GTS to Trust Itself
| If you are NOT Installing Dorian as Part of a New Grid This step is not needed when you are adding a second Dorian to an existing grid. If the Dorian you are installing is not for a new grid, then skip to the step titled Add Dorian Certificate Authority to GTS |
Before the GTS can tell Dorian who to trust, it must be configured to trust itself. We could not do that when we were working with GTS before, because this configuration requires having user credentials that authenticate you as the GTS administrator. Now that dorian is working, we can do this step with GTS that is necessary for Dorian to trust the certificate authorities it needs to trust.
To accomplish this last bit of configuration for GTS, we use the GAARDS UI. The GAARDS UI is a graphical user interface for administering security services such as the GTS. We will use the GAARDS UI to add the certificate authority we created to the trust fabric.
In order for the GAARDS UI to configure GTS, globus must first trust the Dorian certificate authority. After we are done with configuration, globus will trust the Dorian certificate authority because GTS, through syncGTS, tells it to trust. Until then we must make a temporary change to force globus and syncGTS to trust the Dorian certificate authority.
First we will edit SyncGTS's configuration so that Dorian/Globus trusts the Dorian certificate, first make the following edits to the file,
CATALINA_HOME/webapps/wsrf/WEB-INF/etc/cagrid_SyncGTS/sync-description.xml. Replace [GRID_NAME] with the one-word name you chose for the grid.
- Locate the element ExcludedCAs (Shown Below):
<ns1:ExcludedCAs> <ns1:CASubject>O=[GRID_NAME]OU=GTS,OU=Trust Fabric,CN=Trust Fabric CA</ns1:CASubject> </ns1:ExcludedCAs>
- 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=[GRID_NAME],OU=GTS,OU=Trust Fabric,CN=Trust Fabric CA</ns1:CASubject> <ns1:CASubject>O=[GRID_NAME],OU=LOA1,CN=[GRID_NAME] Dorian CA</ns1:CASubject> </ns1:ExcludedCAs>
After we are done will all of our Dorian and GTS configuration, be sure to undo the above edit.
| Do Not Forget to Undo the Edit Do not forget to undo the above edit to the sync-description.xml file. While this edit remains in place, if the Dorian becomes compromised, clients using certificates signed by the compromised Dorian will still be allowed to connect to the GTS, even though the dorian is not trusted by the GTS! |
Next, shut down the GTS tomcat with the commands

cd $CATALINA_HOME
bin/shutdown.sh
Copy the dorian certificate file(s) from the Dorian VM/s USER_HOME/.globus/certificates directory to the GTS VM's USER_HOME/.globus/certificates directory. This will be the file(s) whose name does not begin with cacert.
Now restart the GTS tomcat with the commands

cd $CATALINA_HOME
bin/startup.sh
This completes the temporary trust arrangement. You are now ready to configure GTS with GAARDS-UI.
Complete the following steps:
|
Login in as one of the initial administrators we created earlier. To accomplish this, complete the following steps:
|
|
Create a Level of Assurance to which to assign the trust fabric CA we create. Complete the following steps:
|
|
Add the certificate authority we created earlier to the GTS as a trusted certificate authority. Complete the following steps:
|
Step 13: Add Dorian Certificate Authority to GTS
|
The GAARDS UI provides a method of adding certificate authorities to the GTS as trusted certificate authorities. To add a certificate authority to the GTS you will need to provide the CA's certificate. The CA's certificate is required for authentication and verifying the CA's signature. In addition you need to select which Level(s) of Assurance the CA complies with. To add a certificate authority to the GTS using the GAARDS UI, please complete the following steps:
|
Step 14: Add GTS Authorization for the New Dorian Identity
- Enter the following at a command prompt.

$ cd $CAGRID_HOME
$ ant security - Click Login.
- Enter a user and password of a user with Dorian administration privileges.
- Click Login.
- Select Trust Fabric > Access Control. The Access Control window appears.
- From the Service list, select the Master GTS.
- Click Add to give the new Dorian Identity rights to publish a CRL. The Add Permission Window appears.
- In the Grid Identity text box, enter the grid identity of your Dorian.
- From the Trusted Authority list, select the certificate authority Dorian manages.
- From the Role list, make sure TrustAthorityManager is selected.
- Click Add. This adds the permission to the GTS.





