====== iRODS Fuse lite (irodsfs) ======
===== General Information =====

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).


===== Setup of irodsfs =====

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.
<code>

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

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:

<code>
$ 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 -
</code>

2. Extract the downloaded ''.tar.gz'' file:

<code>
tar -xvf irodsfs-vX.X.X-linux-amd64.tar.gz
</code>

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'':

<code>
$ touch ~/.irods/config.yaml
</code>

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

<code>
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
</code>

**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:

<code>
$ mkdir ~/irods_mount/
</code>

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

===== Mounting and unmounting iRODS collections with 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:

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

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:

<code>
$ irodsfs --config ~/.irods/config.yaml ~/irods_mount/
</code>

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

<code>
$ fusermount -u ~/irods_mount/
</code>

===== Additional tips =====

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''.

<code>
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
</code>


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.