XDirectory Service - System Administrator's / Installation Documentation

Overview of Installation

We'll begin by installing needed support software.  Then we will build the XDirectory Service.  Next, we'll prep the database in which the XDirectory Service's contents will be stored.  Then we will start the database and configure system scripts to run the XDirectory Service as a server process.  Finally, this document describes how to enable grid security with the XDirectory service.

Prerequisites

Java SDK 1.4.2+
Download and install the latest Java SDK 1.4.2+ from Sun's Java site.
  1. Follow the given instructions.
  2. Set the environment variable JAVA_HOME to the installation directory.
  3. Add $JAVA_HOME/bin to your PATH environment.
Ant 1.5+
Download and install the latest stable version of Ant from Jakarta's Ant site.
  1. Follow the given instructions.
  2. Set the environment variable ANT_HOME to the installation directory.
  3. Add $ANT_HOME/bin to your PATH environment.
Globus Toolkit (OPTIONAL)
Download and install the latest stable version of the Globus Toolkit from Globus' website.  Follow the given instructions.

Building the software

  1. Untar the source bundle in the XDirectory installation directory: tar zxvf xdirectory-service-x.y.z.tgz
  2. Change to the untarred directory.
  3. Type ant.  This will compile and build the source code.  If all goes well you will see at the end something like 
    compile:
    BUILD SUCCESSFUL
    Total time: 8 seconds
     

Running the XDirectory

There are currently three database systems that the XDirectory service can use: MySQL, PostgreSQL, and HSQLDB. The simplest of these is HSQLDB, because it does not require any external database system. HSQLDB is a lightweight 100% SQL database engine, which primarily runs in memory with a persistent option for storing the database contents.

The run_service.sh script is provided for starting the XDirectory service.
Customizing the run_service.sh script

The run_service.sh script is provided as a template.  Customize this to suit your own setup.  This script does basically two things:

  1. Set up the Java classpath.  You would only modify this if you extend the XDirectory with additional functionality.
  2. Set up the default database configuration.  This specifies which database you are using and which table of that database to use for the XDirectory.  See information below on the various databases available for specific information.
run_service.sh arguments
The run_service.sh script also takes several command line arguments.  (Note: these are actually options that the script passes on to the Java application, so if starting the XDirectory service directory, these options are available as well.)
Java Environment Variables
A number of options depend on the some Java environment variables being set.  Java environment variables are those that are passed to the "java" command using the "-D" option, i.e. java -Dname=value. If you are using the run_service.sh script, and not java directly, you can specify these variables using a JAVA_OPTS shell environment variable, i.e. performing a setenv JAVA_OPTS -Dname=value before invoking the run scripts. Otherwise, you can just add them directly to the Java command-line. Below are instructions on what the different database systems understand in the way of Java environment variables.

There is also an optionvthat all database systems understand: clean_database. It should only be used when you want to delete all the existing data in the database before the XDirectoryService starts up. It basically just performs an SQL DROP on all the tables that are being using in the database, and therefore cannot be undone. "clean_database" can be used by giving it a value of "true", i.e. setenv JAVA_OPTS -Dclean_database=true.

The preferred way of setting the Java environment variables is to set them in your modified copy of run_service.sh.
HSQLDB Instructions
The HSQLDB implementation supports two modes of operation, either in memory, which is not persistent across runs, or in memory with persistence, which is persistent across runs. By default the non-persistent in memory version is used. If you want to use the persistent mode you need to set the Java environment variable called "xdrs_hsqldb_dbname" to some value other than ".". The value will be the name of the file used to hold the database information between runs. Note, the value of "." means the non-persistent in memory version will be used.

MySQL Instructions
The MySQL implementation requires a MySQL database to be running, specifically one that supports the InnoDB table type (for transactions), and a user and database exists that the XDirectoryService can use to CREATE/DROP tables in. To create such a database:
  1. Start the MySQL database.
  2. As the root user (or some user with administrative privileges in your MySQL database), type mysql, bringing up the MySQL prompt.
  3. The following captures a sample session:
mysql> create database xdrs_test;
Query OK, 1 row affected (0.00 sec)

mysql> grant all on xdrs_test.* to xdrs_user@localhost identified by 'secret_password';
Query OK, 0 rows affected (0.01 sec)

mysql> grant all on xdrs_test.* to xdrs_user@'%' identified by 'secret_password';
Query OK, 0 rows affected (0.00 sec)
Once such a setup exists the MySQL database can be used by specifying "--impl mysql" on startup and defining a "xdrs_mysql_url" to be a MySQL connection URL such as: jdbc:mysql://mysql_server/database_name?user=username,password=user_password, specifying the username and password that you set up in the MySQL database.

PostgreSQL Instructions
The PostgreSQL implementation requires a PostgreSQL database be running, and a user and database must exists that the XDirectory service can use to CREATE/DROP tables in. Once the PostgreSQL system is setup it can be used by specifying "--impl postgres" on startup and defining a "xdrs_postgresql_url" to be a PostgreSQL connection URL such as: jdbc:postgresql://postgresql_server/database_name?user=username, specifying the username and password that you set up in the PostgreSQL database.

Installing as a system service

To install as a Unix system service, copy the provided etc.init.d.xdrs file to /etc/init.d/xdrs, or renaming it however you wish.  This script starts the XDirectory service as a normal, non-privileged (i.e., non-root) user.  It does this by executing a file in the user's ~/bin directory which calls the run_service.sh script with the necessary command line options after setting up needed environment variables.  This script also sends a report of what was written to STDERR to specified recipients.  Configure as needed.  Depending on your flavor of Unix/Linux, you'll need to make appropriate links to this script from the various run-level directories.

Using Security

The XDirectory Service is designed to use Grid Security protocols in order to provide secure transactions.  To run the XDirectory service with security enabled, you must first tell it which set of secure credentials to use.  There are two different options.  You can run the XDirectory using your own proxy grid credentials.  Since proxy grid credentials are short lived, this is of limited utility, but may be useful for a personal, short term XDirectory service that you need to run to perform a certain task.  The other option is create service grid credentials for the XDirectory service.  These are very similar to host grid credentials; the private key is stored unencrypted, but file permissions disallow other users to read it.  This option requires a bit more set up, but is more appropriate when running the XDirectory as a persistent service.

If you don't wish to run the XDirectory in secure mode, be sure to pass the command line argument --unsecure to the run_service.sh script.

Using your Proxy Certificate
The first thing to do is generate a proxy certificate using the Globus Toolkit provided tools.  In particular, issue the grid-proxy-init command to generate a proxy certificate.  Then start up the XDirectory service as specified earlier.

Using a Service Certificate
You'll need to contact your Certificate Authority administrator and request a certificate with the common name "xdrs/hostname", where hostname is the fully qualified domain name of the machine on which the XDirectory service will be running.  Install the certificate and key in /etc/grid-security/xdrs, and make sure that only the user under which you will run the XDirectory service will be able to read these files (note: this isn't strictly necessary, since we will specify in the command line option where these files are; however, it is the convention to put service certificates here).  Then use the --cert and --key options to the run_service.sh script specifying the path to the cert and key files.  Now your XDirectory service should be fully enabled for security.