“Instead of maximizing usability at the expense of utility, we should focus on making powerful tools and fostering a culture of mentorship".

The icommands iCommands are a powerful high performant set of tools that can be installed in on any unix environment.
It can be Unix environment and used both for administrative tasks and (big) data handling.
It is especially powerful, because it makes full The high performance of iCommands comes from its use of the full ability of iRODS to transfer files in parallel.
It can securely send a large file completely saturating the available network.

Note that the icommands iCommands can be solely operated from within the terminal.
Following information is based on assuming The following information assumes basic proficiency of commandline command line tools.

Note that most (Most of this information can also be found on docs.irods.org/4.2.8/icommands.)

Credentials

To access Yoda via the command line, a Data Access Password is required (How to get a Data Access Password).

The Data Access Password must be entered when a password is requested.

Installation

For Ubuntu 18.04:

wget -qO - https://packages.irods.org/irods-signing-key.asc | sudo apt-key add -
echo "deb [arch=amd64] https://packages.irods.org/apt/ xenial main" | sudo tee /etc/apt/sources.list.d/renci-irods.list
sudo apt-get update
sudo apt -y install irods-icommands

For CentOS:

sudo yum -y install wget epel-release
sudo rpm --import https://packages.irods.org/irods-signing-key.asc
wget -qO - https://packages.irods.org/renci-irods.yum.repo | sudo tee /etc/yum.repos.d/renci-irods.yum.repo
sudo yum -y install irods-icommands

...

There are no up-to-date packages for MacOS at time of writing this document.
The icommands iCommands can be built from source (https://github.com/irods/irods_client_icommands), however it is not trivial.

We have also worked successfully with iCommands using Docker containers. Please let us know at servicedesk@surfsaraby opening a request on https://servicedesk.surf.nl if you would like a more supported version of icommands for MacOSto explore this option.

For Windows:

The icommands iCommands work in Linux.
They should be installable via the Ubuntu method using the linux subsystem of Windows 10.

Connecting to Yoda/iRODS

To connect to Yoda/iRODS you have to create the `~/.irods/irods_environment.json` file and edit it as follows:

{
"irods_authentication_scheme": "pam",
"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_host": "YODA_HOST_ADDRESS",
"irods_home": "/YODA_ZONE/home",
"irods_port": 1247,
"irods_user_name": "YODA_USERNAME",
"irods_zone_name": "YODA_ZONE"
}

Note to change the specific details:

• Check Yoda hostnames and Hosting (URLs) for choosing the correct YODA_HOST_ADDRESS
• Your username, YODA_USERNAME, is either the identity from your institute or the e-mail address you were invited through.
• The zone, YODA_ZONE, is usually the acronym of your institute (for example: tue or aumc), but sometimes it is just "yoda" or "tempZone". These are the zones for the institutes that use Yoda:

You can then Subsequently you can run the command:

iinit

Enter your password, and a token will be stored locally which will be used when running subsequent icommandsiCommands.

You can find help for the icommands iCommands with:

ihelp

which will show you all the possible commands.

Basic data/collection handling

Note that in iRODS files are called data objects, and folders are called collections.

The icommands iCommands have basic file handling functionality that have their (almost) equivalent in the Linux bash commands but with an `i` 'i' in front of the name, *e.g.* `ls` and `ils`, `cp` and `icp`, `mv` and `imv`, `pwd` and `ipwd`, `mkdir` and `imkdir`, `cd` and `icd`. `rm` and `irm`.
Try out `icommand -h` 'ls' and 'ils', 'cp' and 'icp', 'mv' and 'imv', 'pwd' and 'ipwd', 'mkdir' and 'imkdir', 'cd' and 'icd'. 'rm' and 'irm'. Try running 'icommand -h' or 'ihelp' if you want to know more about the available options.

However, please do realize note that iRODS is not a filesystem like you have on your personal computer .
Data - data handling is done differently.

Create collections and navigate

Use `ils` 'ils' to see what collections are available to you and navigate to that collection with `icd`'icd':

ils

icd <collection name>

...

You can create a collection with `imkdir`'imkdir'.

If you get an error that you are not allowed to create a collection, be sure to have navigated to a collection where you do have the permission to write.
You can use:

ils -A 

to check the permissions (`'-A` A' stands for Access Control Lists) of data objects and collections.

Sharing data objects and/or collections with other users

With `ils 'ils -A` A' you can view what the current Access Control Lists are, *i.e.* a list who has what type of access to the data objects and collections in the current working directory of iRODS.
The ACLs can be changed by using `ichmod`'ichmod'.
With this command you modify the access to data objects and collections for specific user or groups.

When you store a file, you are the owner and have full control - you can read, write or delete it and, by default, no one else can.
With chmod you can give access to other users or groups, either just read access, or read and write, or full ownership.
You can only give (or remove) access to others if you own the file yourself.
But , but if you give 'own' to someone else, they can also give (and remove) access to others.

For example, if you like to give user or group `alice` 'alice' recursive read permissions on folder `fruit` 'fruit' which is located in your iRODS current working directory (you could also use the full iRODS path), you should do the following:

...

For more information, see `ichmod 'ichmod -h`h'.

Tickets are another way to provide access to iRODS data - objects (files) or collections (directories or folders).
The 'iticket' command allows you to create, modify, list, and delete tickets.
When you create a ticket, its 15 character string is given to you which you can share with others.

For example, if you would like to give read permission for a collection `fruit`'fruit':

iticket create read fruit

This command will print out the ticket string to screen.

Note that you can view all active tickets with `iticket ls`'iticket ls'.

You can use `iticket 'iticket mod ticket-string-or-id` id'` to modify the restrictions on the ticket.
Restrictions can be set on who is able to use the ticket, how many times the ticket can be used, which host or IP is able to use the ticket or the expiration date of the ticket.

Uploading a file with

...

'iput'

To upload a file, use the 'iput' commandIn order to get a file in Yoda:

iput <source_file> <dest_do>

when When no destination data object is given, the local filename will be used.

iRODS will issue a warning if the file already exists (which you can force to do with the `-f` option).

In order to get a folder in iRODSThe same command is used to upload a folder (and its contents):

iput -r <source_folder> <dest_coll>

Note that you need to add the `'-r` r' option for recursively putting data in into Yoda/iRODS.

Downloading a file with

...

'iget'

iget <source_do> <dest_file>

...

To download a collection you have to specify the `'-r` optionr' option (for 'recursive'):

iget -r <source_coll> <dest_folder>

Metadata and querying for data

In Yoda/iRODS a data object is not only the bitstream and the filename, but also includes user defined metadata is part of the data object. This makes it very powerful for the findability of data. Data objects can be found by querying for metadata.

Querying based on metadata

Metadata attached to data objects and collections becomes very useful when you want to query for data. Queries can are mainly be performed by using the `iquest` 'iquest' command, but simple queries can also be done by using the `imeta` 'imeta' command:

#find data objects where distance is larger than 12
imeta qu -d distance '<=' 12

#find collections where key a is value b and key c smaller than value 10
imeta qu -C a = b and c '<' 10

#find data objects where r is not in between 5 and 7
imeta qu -d r '<' 5 or '>' 7

#find data-objects with attribute 'a' with a value that starts with 'b'.
imeta qu -d a like b%

#find data-objects with attribute 'a' defined (with any value).
imeta qu -d a like %

You can enter the `imeta` 'imeta' prompt by just typing `imeta` 'imeta' and hitting Enter. You can then get more helpful tips by then doing `help qu`.executing 'help qu'.

To see all You can look up the available keys you can query for via:

iquest attrs

General `iquest` 'iquest' queries look like:

iquest "select COLL_NAME, DATA_NAME, META_DATA_ATTR_VALUE where \
META_DATA_ATTR_NAME like 'author'" 

In the above command, we wanted to look looked for everything which has with the metadata attribute name (metadata key) that resembles 'author' and retrieve retrieved the collection name, data name and metadata attribute value (metadata value).
iRODS will respond with something likesimilar to:

COLL_NAME = /yoda/home/research-dms
DATA_NAME = testfile
META_DATA_ATTR_VALUE = val1
------------------------------------------------------------

You can change the format of the iRODS response by using a C-like format string after `iquest` 'iquest' like so:

iquest "User %-6.6s has %-5.5s access to file %s" "SELECT USER_NAME, DATA_ACCESS_NAME, DATA_NAME WHERE COLL_NAME = '/yoda/home/research-dms'"

where after `iquest` 'iquest' there is the format string and the second string is again the SQL-like query. This can be convenient for making reports, but also for retrieving absolute filepaths:

...