XDirectory Service - System Administrator's / Installation
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.
Java SDK 1.4.2+
Download and install the latest Java SDK 1.4.2+ from Sun's Java site.
- Follow the given instructions.
- Set the environment variable JAVA_HOME to
the installation directory.
- Add $JAVA_HOME/bin
to your PATH environment.
Download and install the latest stable version of Ant from Jakarta's Ant site.
- Follow the given instructions.
- Set the environment variable ANT_HOME to
the installation directory.
- 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
- Untar the source bundle in the XDirectory installation directory:
- Change to the untarred directory.
- Type ant.
This will compile and build the source code. If all goes well you
will see at the end something like
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
script is provided for starting the XDirectory service.
Customizing the run_service.sh script
script is provided as a template. Customize this to suit your own
setup. This script does basically two things:
- Set up the Java classpath. You would only modify this if
you extend the XDirectory with additional functionality.
- 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.
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.)
PORT_NUM - this option specifies the port number that the
XDirectory will listen to, and is required.
PORT_NUM is an integer.
XDRS_IMPL - this option specifies the type of database system to
use for storing data in the XDirectory. Appropriate values for XDRS_IMPL are mysql and postgres. This argument
is optional, and, if not specified, the default database used is HSQLDB.
- this option suppresses output to the terminal except for error
- this option specifies that the XDirectory service should run in
non-secure mode. Optional.
X509_CERT - this option specifies the file path to the X509
certificate to be used to identify the XDirectory service.
Optional, but must be specified if --key is specified.
PRIVATE_KEY - this option specifies the file path to the
unencrypted key corresponding to the public key in the X509
certificate. Optional, but must be specified if --cert is specified.
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.
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
The preferred way of setting the Java environment variables is to set
them in your modified copy of run_service.sh.
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.
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
- Start the MySQL database.
- As the root user (or some user with administrative privileges in
your MySQL database), type mysql,
bringing up the MySQL prompt.
- The following captures a sample session:
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
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)
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
specifying the username and password that you set up in the PostgreSQL
Installing as a system
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.
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
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