Meant for:

  • iRODS admins
  • iRODS users that need to work with data on the command line

Requirements:

  • account on an iRODS instance
  • connection details for iRODS: username, password, hostname and iRODS zonename (contact your iRODS admin for these details)
  • iCommands (iRODS CLI tool) installed (these tools are installed on all SURF HPC clusters: Lisa, Cartesius, Snellius, Spider)
  • all commands need to be run in a command line application

For using iCommands in a workspace on SURF Research Cloud, please see below.

Creating an iRODS environment file

To connect to iRODS, you have to create the '~/.irods/irods_environment.json' file. This file contains information used by iCommands to connect to an iRODS instance. The 'irods_encryption_*' keys are used to create a secure connection over TLS/SSL. Some keys need to be adjusted with your specific connection details. An example environment file looks like this:

{
"irods_client_server_negotiation": "request_server_negotiation",
"irods_encryption_algorithm": "AES-256-CBC",
"irods_encryption_key_size": 32,
"irods_encryption_num_hash_rounds": 16,
"irods_encryption_salt_size": 8,
"irods_port": 1247,
"irods_host": "<IRODS_HOST_ADDRESS>",
"irods_user_name": "<IRODS_USERNAME>",
"irods_zone_name": "<IRODS_ZONE_NAME>"
}

Please note that you must provide the details presented in capitals between angled brackets <>.

Connect using iinit

Once you have created and edited '~/.irods/irods_environment.json', you should be able to connect using the 'iinit' command:

iinit

This will prompt your for your password:

user@login:~$ iinit
Enter your current iRODS password:

Type in your password (it will not be shown on the screen) and hit enter. An error is given for any failed attempts.

Note that if your iRODS environment is connected to an external identity provider (i.e., identity of your institute), an additional line is required in the iRODS environment file:

{
...
    "irods_authentication_scheme": "pam",
...
}

By default iRODS will try a 'native' authentication.  However, when the 'irods_authentication_scheme' is set to 'pam', iRODS will try to authenticate using the external identity which is configured by your iRODS admin. Login as above:

user@login:~$ iinit
Enter your current PAM password:

You can now try a simple iCommand such as the following:

ils

This prints any data objects and collections in the current working collection to your screen. Now you know you have connected successfully to iRODS.

Typical errors while connecting

Note that if an error occurred, iRODS may return a myriad of details. For example, entering the wrong password (using PAM) will result in the following error message:

user@login:~$ iinit
Enter your current PAM password:
[-]	/irods/plugins/auth/pam/libpam.cpp:241:irods::error pam_auth_client_request(irods::plugin_context &, rcComm_t *) :  status [PAM_AUTH_PASSWORD_FAILED]  errno [] -- message [call to rcAuthRequest failed.]

 failed with error -993000 PAM_AUTH_PASSWORD_FAILED

This is a lot to take in, but the important hint is the last section: 'PAM_AUTH_PASSWORD_FAILED'.

If you made a mistake in the connection details (e.g., hostname is spelled wrongly), you may receive the following error:

user@login:~$ iinit
 ERROR: getaddrinfo_with_retry address resolution timeout [<WRONGLY_SPELLED_IRODS_HOST_NAME>] [ai_flags: [0] ai_family: [2] ai_socktype: [0] ai_protocol: [0]]
 ERROR: _rcConnect: setRhostInfo error, IRODS_HOST is probably not set correctly status = -303000 USER_RODS_HOSTNAME_ERR
 ERROR: Saved password, but failed to connect to server <WRONGLY_SPELLED_IRODS_HOST_NAME>

Note that you will then also not be prompted for a password. Typically, if the connection hangs for a long time after invoking the 'iinit' command, something is wrong with the connection details.

If you have forgotten or misspelled the zone name you will not receive an error. However, subsequent usage of iCommands will show something is wrong:

user@login:~$ ils
[-]	/irods/plugins/auth/native/libnative.cpp:342:irods::error native_auth_client_response(irods::plugin_context &, rcComm_t *) :  status [CAT_INVALID_USER]  errno [] -- message [Call to rcAuthResponseFailed.]

 failed with error -827000 CAT_INVALID_USER

Further help

You can find help for the iCommands with:

ihelp


which will show you all the possible commands.

iCommands in a workspace on SURF Research Cloud

iCommands (4.3.0) are now being made available by default on all Ubuntu-based applications on SURF Research Cloud. Once a workspace based on Ubuntu is started, you will automatically have access to iCommands version 4.3.0 without having to install anything or create/modify an iRODS environment file as described above. The requirements to have access to this set up are:

  1. an account on an iRODS instance
  2. an account on SURF Research Cloud and a valid budget (see here for details)

These accounts are necessary but not sufficient! You should also request access to this setup via a servicedesk ticket. In this step, we enable you to be automatically and securely authenticated on your Research Cloud workspace via your iRODS account for your respective iRODS instance. This step is not automated at this point so we need to manually enable your account to be authenticated.

Once this has been enabled, you need to point to your respective iRODS instance in SURF Research Cloud Portal before starting the workspace. Perform the following steps:

  1. On the SURF Research cloud portal, go to the profile tab
  2. Click on the CO from where you will start the workspace and go to the storage tab as shown below:

3. Click on the "Irods not Linked" and type in the respective iRODS instance name you have an account on, as shown below, and click save. (The "instance" would reflect your iRODS instance name.) In response to the servicedesk request above, we will inform you of the url to be inserted below.

4. The above steps ensure a smooth authentication process. You may now proceed to start your workspace.

5. Please make sure you choose Ubuntu-based applications only. Once the workspace is created, login to the workspace and you can start using iCommands immediately.

Please bear in mind that your iRODS instance may have a different iRODS version (most likely 4.2.x) than the iCommands version 4.3.0 on the Research Cloud workspace. Although 4.3.0 is backwards compatible, this may lead to errors.

  • No labels