- iRODS admins
- iRODS users that need to work with data on the command line
- 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:
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:
This will prompt your for your 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:
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:
You can now try a simple iCommand such as the following:
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:
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:
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:
You can find help for the iCommands with:
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:
- an account on an iRODS instance
- 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:
- On the SURF Research cloud portal, go to the profile tab
- 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.