The RLS depends on a DBMS for persistent storage of replica location information. The RLS is designed to work with MySQL, PostgreSQL, SQLite, and Oracle DBMS software. In the case of MySQL, it is important to use the transaction-capable InnoDB database engine. For complete information on installation and configuration of third-party DBMS software, please refer to:

We provide the following tips from the troubleshooting section of this guide:

The RLS depends on an ODBC manager for standardised database connectivity. The unixODBC or iODBC libraries may be used for this purpose. Please confirm that one of these libraries is installed and configured before proceeding with RLS installation. If you need more information on the ODBC managers, consult their respective project home pages.

You may also find that unixODBC or (less likely) iODBC are included along with a vendor's odbc driver. This appears to be the case with MySQL Connector/ODBC drivers at the time of writing this document.

We provide the following tips from the troubleshooting section of this guide:

	Note
	If you are installing RLS from a Globus Toolkit binary bundle, you do not need to install the unixODBC or iODBC software. The binary installation of RLS is linked to iODBC version 3.51.2 included with the GT bundle.

The RLS depends on an ODBC driver for vendor-specific database connectivity via the vendor neutral ODBC manager. For each vendor you will find a related ODBC driver. You may find relevant information at the following sites:

We provide the following tips from the troubleshooting section of this guide:

We have used or know of users who have used the following combinations of software packages on the following platforms. What we provide in this section is a small subset of available options when choosing DBMS & ODBC software.

(*) See troubleshooting tip Section 12, “Building unixODBC failed on OS X”

If you build from source, be aware that some versions of a vendor's drivers do not build against some versions of the same vendor's clients. For instance, MySQL Connector/ODBC 3.51.06 does not appear to build againt MySQL 4.1.x client libraries, instead it requires MySQL 4.0.x client libraries. Also, we have noticed that psqlodbc-07.03.x will build against pgsql-7.4.x but when using the driver it fails with little or no information to indicate why it failed. We have found that psqlodbc-08.00.x works well with postgres-7.4.6. In all cases, consult the vendor's documentation.

Support RLS development by sending your working RLS + ODBC Manager + ODBC Driver + RDBMS configuration to the rls-user@globus.org list! We cannot test on all platforms with all combinations so we rely on our user community to help advise new users. Your support in this matter is appreciated.

We provide the following tips from the troubleshooting section of this guide:

Follow instructions provided by Installing GT 4.2.0 and Installing GT in order to install the RLS from one of the available binary bundles of the Globus Toolkit. As noted in Section 1.2, “ODBC Manager”, the globus-rls-server found in the binary bundles is linked to the default ODBC Manager.

Once you have unpackaged the binary bundle, the following commands may be used to install RLS (the --enable-rls option is not required):

% ./configure --prefix=$GLOBUS_LOCATION --enable-rls
% make
% make install
            

Follow instructions provided by Installing GT 4.2.0 and Installing GT in order to install the RLS from the available source bundle of the Globus Toolkit. In addition to the general requirements, you may optionally set environment variables pertaining to the include and lib path for your ODBC Manager installation. The following environment variables are not required to install RLS.

If you wish to use unixODBC, set the following environment variables.

% setenv GLOBUS_UNIXODBC_INCLUDES /path/to/unixODBC/include
% setenv GLOBUS_UNIXODBC_LIBS /path/to/unixODBC/lib
            

If you wish to use iODBC, set the following environment variables.

% setenv GLOBUS_IODBC_INCLUDES /path/to/libiodbc/include
% setenv GLOBUS_IODBC_LIBS /path/to/libiodbc/lib
            

	Note
	Your shell format for setting environment variables may be export VAR=VAL instead of setenv VAR VAL.

Alternatively, instead of setting the above environment variables you may choose to specify the includes and libs path for your ODBC Manager using the Globus Toolkit configure script's options, which include --with-unixodbc-includes=DIR and --with-unixodbc-libs=DIR or --with-iodbc-includes=DIR and --with-iodbc-libs=DIR.

Once you have unpackaged the source bundle, the following commands may be used to install RLS (the --enable-rls option is not required):

% ./configure --prefix=$GLOBUS_LOCATION --enable-rls
% make
% make install
            

In some situations, you may wish to update an RLS installation using RLS source from the Globus Toolkit Source Bundle. For instance, the RLS found in the Globus Toolkit binary bundles is linked against an ODBC Manager. If you would like to link to a different ODBC Manager, it may be easier to install the toolkit from the binary bundle and just update the RLS server package from source. This may save considerable time compared to building the entire Globus Toolkit from source.

To do this, you must first follow the complete instructions found in Section 2.1, “Installing RLS using Globus Toolkit Binary Bundle” then set the environment according to the instructions found in Section 2.2, “Installing RLS using Globus Toolkit Source Bundle”. If you have not already set the GPT_LOCATION then set it to the GLOBUS_LOCATION (i.e., setenv GPT_LOCATION $GLOBUS_LOCATION).

Once you have unpackaged the source bundle, the following commands may be used to install RLS:

% cd source-trees-thr/replica/rls/server/
% $GPT_LOCATION/sbin/gpt-build -verbose -force gcc32dbgpthr
...
% $GPT_LOCATION/sbin/gpt-postinstall
...
            

You may select a flavor other than gcc32dbgpthr that is suitable to your platform and existing installation environment. You may omit the -verbose flag.

Decide which database(s) the RLS server will use:

An RLI server can receive updates from LRC servers in one of two forms, as LFN lists (in which case the RLI database must be created) or as highly compressed Bloom filters. Since Bloom filters are relatively small, they are kept in memory and no database is required (though if you plan to use the hierarchical RLI updates feature, you will still need the RLI database). An RLS server can be configured as both an LRC and RLI server.

The RLS Server configuration file ($GLOBUS_LOCATION/etc/globus-rls-server.conf) contains a few settings related to your database setup. Throughout this guide we refer to the username as dbuser and the password as dbpassword and to the LRC database as lrc1000 and the RLI database as rli1000. Substitute your chosen username, password, and database names where applicable. Also, you may change the odbcini setting to reflect the location of your ODBC Manager's odbc.ini file. You should be familiar with the location of this file from the installation of your ODBC Manager. As of the GT 4.1.x release, the RLS setup includes a default odbc.ini file installed to $GLOBUS_LOCATION/var/odbc.ini which is the initial default value of the odbcini configuration parameter. We discuss more about odbc.ini in Section 3.5, “Specify Data Source Names (DSNs)”.

Edit the following fields in $GLOBUS_LOCATION/etc/globus-rls-server.conf:

# Database connection options
db_user             dbuser 
db_pwd              dbpasswordgoeshere
odbcini             /path/to/var/odbc.ini
...
# LRC options
lrc_server          true
lrc_dbname          lrc1000  # optional (if LRC server)
...
#RLI options
rli_server          true
rli_dbname          rli1000  # optional (if RLI server)
...
rli_bloomfilter     false
...
            

You or your system administrator must create a DBMS user account to be used by the RLS Server to log on to the DBMS. SQLite users may safely skip this step.

For MySQL users, the command may look something like this:

% /path/to/mysql/bin/mysql -u root -p
Enter password:
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 71 to server version: 4.0.18-standard-log
 
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.
 
mysql> use mysql;
Database changed
mysql> grant all on lrc1000.* to dbuser@localhost identified by 'dbpassword';
mysql> grant all on rli1000.* to dbuser@localhost identified by 'dbpassword';
            

For PostgreSQL user, the command may look something like this:

% /path/to/pgsql/bin/createuser -P dbuser -W
Enter password for new user:
Enter it again:
Shall the new user be allowed to create databases? (y/n) y
Shall the new user be allowed to create more new users? (y/n) n
Password:
CREATE USER
            

We provide SQL Data Definition (DDL) scripts to create the databases required by the RLS Server. Configure the script(s) for the database(s) you will create. The SQL scripts for the LRC and RLI databases are installed in $GLOBUS_LOCATION/setup/globus.

For PostgreSQL, use:

For MySQL, use:

For SQLite, use:

For Oracle DBMS, use:

Edit these files to set the name of the database user you created for RLS and the names of the databases configured in $GLOBUS_LOCATION/etc/globus-rls-server.conf.

Create the database(s) using the appropriate tool for your chosen DBMS.

For PostgreSQL, the commands should look like this:

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

For MySQL, the commands should look like this:

% mysql -p -u dbuser  < $GLOBUS_LOCATION/setup/globus/globus-rls-lrc-mysql.sql
% mysql -p -u dbuser  < $GLOBUS_LOCATION/setup/globus/globus-rls-rli-mysql.sql
            

For SQLite, the commands should look like this:

% sqlite3 $GLOBUS_LOCATION/var/globus-rls-lrc1000.db  < $GLOBUS_LOCATION/setup/globus/globus-rls-lrc-sqlite.sql
% sqlite3 $GLOBUS_LOCATION/var/globus-rls-rli1000.db  < $GLOBUS_LOCATION/setup/globus/globus-rls-rli-sqlite.sql
            

Data Source Names (DSNs) are used by ODBC software (and the applications that depend on ODBC software) to define connection settings between the database client and the DBMS. The RLS depends on the data source names configured in Section 3.2, “Configure database related RLS settings” for the lrc_dbname and rli_dbname settings.

DSNs are configured in a file named odbc.ini. Most ODBC Managers find this file in the following search order.

DSNs may be configured in a variety of ways, but they essentially contain the same information which includes:

As of the Globus Toolkit 4.1.x release, the RLS setup includes a default odbc.ini file installed to $GLOBUS_LOCATION/var/odbc.ini. The settings of the included odbc.ini are appropriate for usage with the psqlODBC driver and reference psqlODBC libraries installed to $GLOBUS_LOCATION/lib/psqlodbc.so, which is the location of the libraries as installed by the Globus Toolkit binary installer and the source installer by using the make globus_database_psqlodbc target. When using the installed odbc.ini file, you may still need to set your ODBCINI environment variable to the odbc.ini file's location.

We provide the following tips from the troubleshooting section of this guide: