The iRODS Connector allows Globus Connect Server to access storage resources on an iRODS server.

The iRODS Connector requires Globus Connect Server v5.4, and is available as an add-on subscription to organizations with a Globus Standard subscription - please contact us for pricing.

This document describes how to create an iRODS storage gateway and mapped collection. After the installation and configuration is complete, any authorized user can access iRODS data via the mapped collection, or create a guest collection and share data, by following our user documentation: access a collection and share data.

The installation must be performed by a system administrator, and has the following distinct set of steps:

  • Install and configure a Globus Connect Server endpoint.

  • Install the iRODS connector package on each node of the endpoint.

  • Prepare an iRODS environment file and authentication file.

  • Create an iRODS storage gateway.

  • Create an iRODS mapped collection.

Please contact us at support@globus.org if you have questions or need help with installation and use of the iRODS Connector.


Requirements

  • The currently supported iRODS server version is 4.2.

  • The parent directory entries (i.e. /, /ZONE, and /ZONE/home) should be readable by all users. Recursive transfers into any directory require that it’s parent directory entries be readable.

  • Supported platforms are listed on iRODS downloads.

Installing the iRODS Connector

Ensure the Globus Connect Server package repositories are enabled before continuing.

The iRODS connector package is provided by the iRODS Consortium, and is not available in the Globus Connect Server repository. The following instructions will install the iRODS package repository, and then the iRODS connector package and dependencies from that repository.

# install iRODS package repository
sudo rpm --import https://packages.irods.org/irods-signing-key.asc
curl -s https://packages.irods.org/renci-irods.yum.repo | sudo tee /etc/yum.repos.d/renci-irods.yum.repo
# install iRODS connector packages and dependencies
sudo yum install irods-gridftp-client
# install iRODS package repository
curl -s https://packages.irods.org/irods-signing-key.asc | sudo apt-key add -
echo "deb [arch=amd64] https://packages.irods.org/apt/ $(lsb_release -sc) main" | sudo tee /etc/apt/sources.list.d/renci-irods.list
sudo apt-get update
# install iRODS connector packages and dependencies
sudo apt-get install irods-gridftp-client

If you had previously installed the package from source, remove the file /etc/gridftp.d/irods.

sudo rm /etc/gridftp.d/irods
sudo systemctl restart globus-gridftp-server

iRODS Connector Virtual Filesystem

The iRODS Connector filesystem reflects the file system hierarchy on the configured zone of the iRODS resource. The usual directory structure is /ZONE/<data> with home directories at /ZONE/home/USER.

When accessing data on an iRODS collection, if the storage gateway’s restrict_paths or a mapped collection’s sharing_restrict_paths property are set to disallow all access to a file or directory, those directory entries will not be visible in the collection.

Also, if a collection_base_path value is set on collection creation, it will act similar to a POSIX chroot, and that value will act as the root of a collection’s virtual filesystem.

Storage Gateway

A iRODS Connector Storage Gateway is created with the command globus-connect-server storage-gateway create irods, and can be updated with the command globus-connect-server storage-gateway update irods.

Before looking into the policy options specific to the iRODS Connector, please familiarize yourself with the Globus Connect Server v5 Data Access Guide which describes the steps to create and update a storage gateway, using the POSIX connector as an example. The commands to create and update a storage gateway for the iRODS Connector are similar.

iRODS Connector Storage Gateway Policies

The iRODS Connector has policies to manage the iRODS client environment and client authentication configuration.

iRODS client environment file

The --irods-environment-file command-line option is used by Globus Connect Server to authenticate to the iRODS server as an admin user. The file must contain the following minimum set of entries:

irods_host

The iRODS server hostname

irods_port

The iRODS server port

irods_user_name

The iRODS admin username

irods_zone_name

The iRODS Zone name

irods_default_resource

The default iRODS resource

Example 1. Specifying the iRODS client environment file

For our example, we’ll use the environment file /var/irods/irods_environment.json. This file must exist on each data transfer node in order for the connector to work properly.

--irods-environment-file /var/irods/irods_environment.json
iRODS Environment File Permissions

The iRODS environment file must be readable by Globus Connect Server. This means it must have certain file permissions set on it. If SELinux is enforcing on your system it must also be labelled in a way that the Globus Connect Server services can access it. You can use the following commands as models to set the file permissions and SELinux label on the file. For these examples, we assume the IRODS_ENVIRONMENT_FILE environment variable is set to the actual path to the environment file.

Set environment file permissions
sudo chown gcsweb:gcsweb "${IRODS_ENVIRONMENT_FILE}"
sudo chmod 600 "${IRODS_ENVIRONMENT_FILE}"
Set SELinux label
sudo semanage fcontext -a -t gcs_manager_db_t "${IRODS_ENVIRONMENT_FILE}"
sudo restorecon "${IRODS_ENVIRONMENT_FILE}"

iRODS client authentication file

The --irods-authentication-file command-line option contains credentials used by Globus Connect Server to authenticate to the iRODS server as an admin user. This file should be created with the iRODS command iinit.

The authentication file must exist on each data transfer node, and must only be readable by the user gcsweb.

One way to create this file with the correct ownership is to run it as the user gcsweb:

sudo -u gcsweb env IRODS_ENVIRONMENT_FILE=/var/irods/irods_environment.json \
                   IRODS_AUTHENTICATION_FILE=/var/irods/.irodsA \
                   iinit
Example 2. Specifying the iRODS client authentication file

For our example, we’ll use the authentication file /var/irods/.irodsA. This file must exist on each data transfer node in order for the connector to work properly.

--irods-authentication-file /var/irods/.irodsA

Creating the Storage Gateway

Now that we have decided on all our policies, we’ll use the command to create the storage gateway.

% globus-connect-server storage-gateway create irods \
    "iRODS Storage Gateway" \
    --domain example.org \
    --irods-environment-file /var/irods/irods_environment.json \
    --irods-authentication-file /var/irods/.irodsA

Storage Gateway Created: 7187a9a0-68e4-48ea-b3b9-7fd06630f8ab

This was successful and outputs the ID of the new storage gateway (7187a9a0-68e4-48ea-b3b9-7fd06630f8ab in this case) for our reference. Note that this will always be a unique value if you run the command. If you forget the id of a storage gateway, you can always use the command globus-connect-server storage-gateway list to get a list of the storage gateways on the endpoint.

You can also add other policies to configure additional identity mapping and path restriction policies as described in the Globus Connect Server v5 Data Access Guide.

Note that this creates the storage gateway, but does not yet make it accessible via Globus and HTTPS. You’ll need to follow the steps in the next section and create a collection.

Collection

A iRODS Collection is created with the command globus-connect-server collection create, and can be updated with the command globus-connect-server collection update.

As the iRODS Connector does not introduce any policies beyond those used by the base collection type, you can follow the sequence in the Collections Section of the Globus Connect Server v5 Data Access Guide. Recall however, that the paths are interpreted as described above in iRODS Connector Virtual Filesystem.

Appendix A: Document Types for the iRODS Connector

IrodsStoragePolicies Document

This document contains one of the versioned iRODS specific storage gateway policies.

Name

Type

Description

IrodsStoragePolicies One of { IrodsStoragePolicies 1.0.0 ​ }

This document contains one of the versioned iRODS specific storage gateway policies.

{
  "irods_environment_file": "/var/irods/irods_environment.json",
  "irods_authentication_file": "/var/irods/.irodsA",
  "environment": [
    {
      "name": "VOLUME",
      "value": "/vol/0"
    }
  ],
  "DATA_TYPE": "irods_storage_policies#1.0.0"
}

IrodsCollectionPolicies Document

This document contains one of the versioned iRODS-specific collection policies.

Name

Type

Description

IrodsCollectionPolicies One of { IrodsCollectionPolicies 1.0.0 ​ }

This document contains one of the versioned iRODS-specific collection policies.

{
  "DATA_TYPE": "irods_collection_policies#1.0.0"
}

IrodsUserCredentialPolicies Document

This document contains one of the versioned iRODS-specific user credential policies.

Name

Type

Description

IrodsUserCredentialPolicies One of { object IrodsUserCredential 1.0.0 Policies ​ }

This document contains one of the versioned iRODS-specific user credential policies.

{
  "DATA_TYPE": "irods_user_credential_policies#1.0.0"
}