Globus GridFTP Ceph DSI
=======================

The Globus GridFTP Ceph DSI (Ceph DSI) implements a data storage interface
between a Globus GridFTP server and a Ceph RADOS Gateway providing the
S3-compatible REST API to its object store.

It attempts to make the object store look like a filesystem.  The namespace
served by this DSI is rooted at the Ceph object store root.
Items seen as "directories" in the top level are "buckets" in S3 terminology.
Creating a new toplevel directory creates a new bucket. Creating a directory
within a bucket or a subdirectory of a bucket adds a 0 byte placeholder object
to the object store, with a name that ends with the '/' character and metadata
indicating it's to be viewed as a directory by Globus.

The Ceph DSI is compatible with gridmap files and GSI authorization callouts.
When a GridFTP session begins, the local user name is interpreted by the Ceph
DSI as a Ceph user_id. The DSI queries the Rados Gateway Admin database
to determine the ceph credentials to use for data operations.

== Installation

Install the package globus-gridftp-server-ceph from the Globus respository.

For Red Hat-based systems:

  % yum install globus-gridftp-server-ceph

For Debian-based systems:

  % apt-get install globus-gridftp-server-ceph

For SLES 11-based systems:

  % zypper install globus-gridftp-server-ceph

== Configuration

The Ceph DSI requires the following steps for configuration:

- Create a RADOS Gateway User with users:read capabilities
- Configure the Ceph DSI
- Enable the Ceph DSI
- Restart the GridFTP server

=== Create a RADOS Gateway User with users:read capabilities

This identity is used by the Ceph DSI to look up keys associated
with the Ceph user_id that the GridFTP session is authorized to run
as.

This command must be run on a host with access to the ceph client.admin keyring
in order to create the gridftp Ceph user_id:

  # radosgw-admin user create \
        --uid=gridftp \
        --display-name "GridFTP Ceph DSI" \
        --caps="users=read"

Note in the output for this command the "access_key" and "secret_access_key"
fields of the "keys" object, as those will be needed in the next step. If
you forget to record those, you can use the following command to retrieve
the same information:

  # radosgw-admin user info --uid=gridftp

=== Configure the Ceph DSI

The package contains an example configuration file in
/etc/globus/globus-gridftp-server-ceph.conf

The format of the file is very simple:

- Comments begin with #
- Configuration values are set by a line of the form
  name = value

There is no special quoting syntax, and whitespace is ignored between tokens.

At the very minimum, the configuration values "host_name",
"ceph_rg_admin_access_key_id", and "ceph_rgw_admin_secret_access_key" must
be set. There are comments in the file describing all available configuration
options.

NOTE: This file contains the keys for the gridftp Ceph user which can read
all Ceph user's keys---do not change the permissions of this file to make
it readable by anyone besides root.

=== Enable the Ceph DSI

Create the file /etc/gridftp.d/gridftp-ceph containing these lines:

------------------------------------------------------------------------------
 threads 2
 load_dsi_module ceph
 auth_level 4
------------------------------------------------------------------------------

=== Restart the GridFTP Server

  # service globus-gridftp-server restart

== Troubleshooting

To enable a debugging log for the ceph dsi, set the environment
variable GLOBUS_S3_DEBUG "1023,/tmp/s3.log" to enable a highly verbose log
of the DSI. This can be easily done for a gridftp configuration by creating
a file /etc/gridftp.d/ceph-debug with the contents

------------------------------------------------------------------------------
 $GLOBUS_S3_DEBUG "1023,/tmp/s3.log"
------------------------------------------------------------------------------
