iRODS Fuse lite (irodsfs)

While you can access your RDMS collections by connecting to the RDMS remotely when using iCommands, you can also create a space on your machine where you can access the RDMS directly as if it were part of your local directory hierarchy. This action of making a remote directory available on your local system is called “mounting” in technical terms.

Linux users are able to mount iRODS collections and data objects (i.e. the iRODS version of directories and files) in their local directory hierarchy by using irodsfs, a FUSE implementation of the iRODS client that you can download here: https://github.com/cyverse/irodsfs.

In this way, you can access data stored on an iRODS system, in our case on the RDMS, via the local directory hierarchy. This also allows you to use common Linux tools, e.g. rsync, cp, mkdir or vi, to transfer, read, and/or organize the files present on the RDMS.

The irodsfs package is pre-installed on the (virtual) Linux workplace and can be invoked by running the irodsfs command from the terminal.

For other Linux systems, the developer of irodsfs provides pre-built binaries which you can download from Releases on the official Github instance of the project (https://github.com/cyverse/irodsfs/releases).

To install and set up irodsfs on your personal Linux environment, follow steps 1-4. If you use the LWP instead, irodsfs is already preinstalled, and steps 1 and 2 can be skipped.

1. Download the correct irodsfs version from Github (https://github.com/cyverse/irodsfs), either via browser or terminal. In this example, the download is performed using wget and the file is downloaded to your home directory.

$ cd 
$ wget https://github.com/cyverse/irodsfs/releases/download/vX.X.X/irodsfs-vX.X.X-linux-amd64.tar.gz

Be sure that you substitute vX.X.X with the current version, and also change amd64 to the correct parameters for the CPU that you are using.

Alternatively, you can use the following command to check for the newest version of irodsfs and download the .tar.gz to the current working directory:

$ curl -s https://api.github.com/repos/cyverse/irodsfs/releases/latest | grep "browser_download_url.*amd64.tar.gz\"" | cut -d ':' -f 2,3 | tr -d \" | wget -i -

2. Extract the downloaded .tar.gz file:

tar -xvf irodsfs-vX.X.X-linux-amd64.tar.gz

You can directly run the extracted irodsfs binary from every location, provided you specify the path to it in your terminal command. You can also add the path to the binary to your $PATH environment variable to make it available globally, without having to specify its location every time you call the command. In this tutorial, we will assume that you did NOT add the path to the binary to the $PATH environment variable.

3. Create a configuration file for irodsfs:

$ touch ~/.irods/config.yaml

Open the created config.yaml file and paste the following content in it, then save the file (take notes below into account):

irods_host: store.data.rug.nl
irods_port: 1247
irods_user_name: <username>@rug.nl
irods_zone_name: rug
irods_user_password: "<your_password"

irods_authentication_scheme: "pam_password"
irods_ssl_ca_certificate_file: "/etc/ssl/certs/ca-certificates.crt"
irods_encryption_key_size: 32
irods_encryption_algorithm: "AES-256-CBC"
irods_encryption_salt_size: 8
irods_encryption_num_hash_rounds: 16

path_mappings:
  - irods_path: /rug/home/<username>@rug.nl
    mapping_path: /
    resource_type: dir

Notes:

• Older version of irodfs used different termins in the config file, please be sure that you use the current irodsfs version.
• Depending on your Linux distribution (e.g. CentOS), you might need to adjust /etc/ssl/certs/ca-certificates.crt to /etc/ssl/certs/ca-bundle.crt or equivalent.
• Keep in mind that your UG mail addressed needs to be specified in lowercase!

Another important aspect is that you take care to verify that the correct username is specified in the configuration file. To access the RDMS, you need to input your RUG email as your username.

Before you can mount the RDMS location onto your system, you also need to create an empty mount point in your Linux environment. This can be done with:

$ mkdir ~/irods_mount/

which will create the empty folder irods_mount/ in your home directory, which will then be used as the mount point for irodsfs.

Now that the set-up of irodsfs is complete and working, you can mount your RDMS/iRODS collection to your local file system by running:

$ PATH-TO-IRODSFS-LOCATION/irodsfs --config ~/.irods/config.yaml ~/irods_mount/

You will be prompted for your password, and if no error messages are shown, you can now access your personal RDMS directory mounted at ~/irods_mount/ or wherever you chose to mount the RDMS location in the previous command.

If you are using the version of irodsfs that is preinstalled on the LWP or if you specified the location of the irodsfs binary in your $PATH environment variable, you do not need to provide the absolute path to irodsfs in your command. The syntax to mount the drive therefore becomes:

$ irodsfs --config ~/.irods/config.yaml ~/irods_mount/

Once you are done and wish to unmount the previously mounted collection, in this example ~/irods_mount/, you can use the following command:

$ fusermount -u ~/irods_mount/

You can also map multiple RDMS collections to your chosen mount point using irodsfs. To do so you have to adjust the `path_mapping` variable in the config.yaml file that contains the irodsfs configuration.

The example below shows the configuration needed to mount your personal RDMS Home Drive at ~/irods_mountpoint/RDMS_Home, along with a RDMS Team Drive that you belong to at ~/irods_mountpoint/RDMS_Team.

irods_host: store.data.rug.nl
irods_port: 1247
irods_user_name: <username>@rug.nl
irods_zone_name: rug
irods_user_password: "<your_password"

irods_authentication_scheme: "pam_password"
irods_ssl_ca_certificate_file: "/etc/ssl/certs/ca-certificates.crt"
irods_encryption_key_size: 32
irods_encryption_algorithm: "AES-256-CBC"
irods_encryption_salt_size: 8
irods_encryption_num_hash_rounds: 16

path_mappings:
  - irods_path: /rug/home/<username>@rug.nl
    mapping_path: /RDMS_Home
    resource_type: dir
  - irods_path: /rug/home/<Team_Drive_Name>
    mapping_path: /RDMS_Team
    resource_type: dir

While it is possible to provide your password directly in the config.yaml file as shown above, we strongly advise against doing so for security reasons.

You can also install and use irodsfs on other environments besides your own personal Linux machine. For example you can follow the guide above to install irodsfs on a Windows Subsystem for Linux (WSL) instance. In the same way you can install and use irodsfs on the Hábrók HPC cluster. Just connect via ssh to the cluster and follow the manual above as if working on your local Linux machine.