How to set up a Globus RLS server
=================================

After installing the globus-rls-server package the server's database
backend must be configured and its database tables created. The Globus
RLS server is built using unixODBC and the server administrator
therefore can choose between different database backends. Database
definitions are provided for MySQL, postgres, sqlite and oracle.

The Globus RLS server consists of two parts, the local replica catalog
(LRC) and the replica location index (RLI). A server can run either
one or both. The instructions below enables both services. If only one
of the services is needed the instruction for creating the database
tables for the other service can be ignored. The default configuration
file /etc/globus-rls-server.conf have both lrc_server and rli_server
set to true. If only one of the services is required the entry for the
other one should be changed to false.


A) MySQL

MySQL version 4.0.1 or later is required in order to have support for
the database transaction features used by the Globus RLS
server. Without proper support for these features the reference
counters in the MySQL tables will get out of synch.

The MySQL ODBC driver is needed. It can be installed using:

  apt-get install libmyodbc

The MySQL server used as a backend can be running on the same host as
the Globus RLS server or on a different host if that is preferred.

A-1) Creating tables

Start the mysql tool and issue the following commands, replacing the
dbuser and dbpassword with the database username and password you will
be using for the Globus RLS server.

mysql> use mysql;
mysql> grant all on lrc1000.* to dbuser@localhost identified by 'dbpassword';
mysql> grant all on rli1000.* to dbuser@localhost identified by 'dbpassword';

If you are using a MySQL database on a different host than the one
running the Globus RLS server repeat the two last lines with localhost
replaced with the hostname of the Globus RLS Server.

Create the databases by running the following commands, replacing
dbuser with the database username you specified above. If you are
using a different database host than the Globus RLS server host you
can either copy the database definition files to the MySQL host or run
the commands on the Globus RLS server host and add a -h flag
indicating the hostname of the MySQL server. You will be promted for
the password.

  mysql -p -u dbuser < /usr/share/globus/setup/globus-rls-lrc-mysql.sql
  mysql -p -u dbuser < /usr/share/globus/setup/globus-rls-rli-mysql.sql

A-2) Configuring the Globus RLS server

Edit the file /etc/globus-rls-server.conf and specify the database
username and password you have been using. Also change the lrc_dbname
and rli_dbname to lrc1000_mysql and rli1000_mysql respectivley. Make
sure this file is not world readable to protect the password.

If you are not using a MySQL server on the same host as the Globus RLS
server, edit the /etc/globus-rls-server-odbc.ini file and add a
Servername entry to the definitions of lrc1000_mysql and rli1000_mysql
providing the hostname of the MySQL server.

The default access control list gives all users the right to do
everything. If this is not what is intended, you should modify the acl
entry in the /etc/globus-rls-server.conf file.

A-3) Starting the server

Enable automatic start up of the server by changing RUN=no to RUN=yes
in /etc/default/globus-rls-server, then start the server using:

  invoke-rc.d globus-rls-server start

Once the server is running you can use the globus-rls-admin command to
let the LRC and/or RLI send updates to RLI servers. If the server is
running both an LRC and an RLI you can let the LRC send updates to the
RLI in the same server. Sending RLI updates is optional.


B) postgres

The postgres ODBC driver is needed. It can be installed using:

  apt-get install odbc-postgresql

The postgres server used as a backend can be running on the same host
as the Globus RLS server or on a different host if that is preferred.

B-1) Creating tables

Create a database user for the Globus RLS server using the following
command on the database host, replacing dbuser with the database
username you will be using. You will be prompted for a password for
the new user.

  createuser -P dbuser

Create the databases using the following commands, replacing dbuser
with the database username created above. If you are using a different
database host than the Globus RLS server host you can either copy the
database definition files to the postgresql host or run the commands
on the Globus RLS server host and add a -h flag indicating the
hostname of the postgresql server. You will be promted for the
password.

  createdb -O dbuser -U dbuser -W lrc1000
  createdb -O dbuser -U dbuser -W rli1000
  psql -W -U dbuser -d lrc1000 -f /usr/share/globus/setup/globus-rls-lrc-postgres.sql
  psql -W -U dbuser -d rli1000 -f /usr/share/globus/setup/globus-rls-rli-postgres.sql

B-2) Configuring the Globus RLS server

Edit the file /etc/globus-rls-server.conf and specify the database
username and password you have been using. Also change the lrc_dbname
and rli_dbname to lrc1000_psql and rli1000_psql respectivley. Make
sure this file is not world readable to protect the password.

If you are not using a postgresql server on the same host as the
Globus RLS server, edit the /etc/globus-rls-server-odbc.ini file and
change the Servername entry in the definitions of lrc1000_psql and
rli1000_psql providing the hostname of the postgresql server.

The default access control list gives all users the right to do
everything. If this is not what is intended, you should modify the acl
entry in the /etc/globus-rls-server.conf file.

B-3) Starting the server

Enable automatic start up of the server by changing RUN=no to RUN=yes
in /etc/default/globus-rls-server, then start the server using:

  invoke-rc.d globus-rls-server start

Once the server is running you can use the globus-rls-admin command to
let the LRC and/or RLI send updates to RLI servers. If the server is
running both an LRC and an RLI you can let the LRC send updates to the
RLI in the same server. Sending RLI updates is optional.


C) sqlite

The sqlite ODBC driver is needed. It can be installed using:

  apt-get install libsqliteodbc

C-1) Creating tables

Use sqlite to create the database tables:

  mkdir -p /var/lib/globus-rls-server
  sqlite3 /var/lib/globus-rls-server/lrc1000.db < /usr/share/globus/setup/globus-rls-lrc-sqlite.sql
  sqlite3 /var/lib/globus-rls-server/rli1000.db < /usr/share/globus/setup/globus-rls-rli-sqlite.sql

C-2) Configuring the Globus RLS server

The default access control list gives all users the right to do
everything. If this is not what is intended, you should modify the acl
entry in the /etc/globus-rls-server.conf file.

C-3) Starting the server

Enable automatic start up of the server by changing RUN=no to RUN=yes
in /etc/default/globus-rls-server, then start the server using:

  invoke-rc.d globus-rls-server start

Once the server is running you can use the globus-rls-admin command to
let the LRC and/or RLI send updates to RLI servers. If the server is
running both an LRC and an RLI you can let the LRC send updates to the
RLI in the same server. Sending RLI updates is optional.


D) oracle

Configuring the Globus RLS server for the oracle backend is left as en
exercise for the reader.
