Command line use

For using IDA through command line, you will need a connection configuration file and command line tools, also known as "i-commands".

 

Configuration file
The connection configuration file should be created using a text editor of your choice to the user's home directory (/home/<username>/.irods/irods_environment.json) and the contents of the file should be as follows:

{

    "irods_home": "/ida/<organization>/<project>",
    "irods_user_name": "<username>",
    "irods_host": "ida.csc.fi",
    "irods_zone_name": "ida",
    "irods_port": 1247,
    "irods_authentication_scheme": "native"

}

Note: Since version 4.1.0 the field irods_zone has been changed to irods_zone_name. If you are using Taito, change the irods_zone_name to irods_zone.

Command line commands

Installation
The command line tools are available from irods.org/download page under the heading "iCommands CLI". Installation instructions for RHEL and Debian/Ubuntu Linux distribuutions can be found on the same page.

 

Command line tools usage
Note! Every command line command provides usage instructions and list of the available options to use with the command when executed with the '-h' option. For example:

$ iput -h

 

 

Some useful commands

Note: We highly recommend NOT using the 'irsync' command anymore, due to its numerous problems. See below for a link to a script to replace irsync.
iinit For opening a connection to IDA. The command asks once for your IDA password unless it already hasn't been saved to the ~/.irods/.irodsA file.
iexit For closing a connection to IDA. Stores the weakly encrypted password in a file at ~/.irods/.irodsA
iexit full For closing a connection to IDA. Removes the weakly encrypted password. After this command, the 'iinit' command require you to re-enter your password.
ipwd Shows your current working IDA directory..
ils Lists your current directory.
icd Changes your current directory.
imkdir Creates a directory.
irm For removing a file or directory.
icp For copying a file or directory inside IDA.
iput For uploading a file or directory to IDA.
iget For downloading a file or directory from IDA.
imeta For adding/removing/changing/displaying metadata information of a file or directory.
ichmod For changing file or directory permissions.
iquest A very useful tool for making more complex queries about your files and directories.
 

Big uploads to IDA

When doing big uploads (lots of files, deep directory structures, etc.) to IDA, we recommend using a special script: https://github.com/ida-csc/iput_wrapper. Other useful scripts: https://github.com/ida-csc

Typical use cases:
(Note: the following use cases assume that command line tools are installed)

Creating a configuration file (you only need to do this once):

Lets assume that the user 'exampleuser' has a home directory of /home/exampleuser on his local machine (or as it is often expressed in its shortened form: ~/):

$ pwd
/home/exampleuser

The user creates a new directory /home/exampleuser/.irods (or in shortened form: ~/.irods):

$ mkdir /home/exampleuser/.irods

OR

$ mkdir ~/.irods

The user creates a configuration file using her preferred text editor:

$ nano ~/.irods/irods_environment.json

The user writes, or copies, the following rows to the configuration file:

{

    "irods_home": "/ida/<organization>/<project>",
    "irods_user_name": "<username>",
    "irods_host": "ida.csc.fi",
    "irods_zone_name": "ida",
    "irods_port": 1247,
    "irods_authentication_scheme": "native"

}

From the above information, the user changes <organization>, <project> ja <username> to correspond to her personal organization, project and username information (which she should have gotten when an IDA account was created for her).

Note: Since version 4.1.0 the field irods_zone has been changed to irods_zone_name.

Connecting to IDA:

The user connects to IDA using the following command:

$ iinit
Enter your current iRODS password:
$

When connecting for the first time, the command asks your IDA-password, which will be saved weakly encrypted to the file ~/.irods/.irodsA

Closing the connection to IDA:

$ iexit
$

If required, the user can use the 'iexit' command to remove the stored password (created by 'iinit'):

$ iexit -h
Exits iRODS session (cwd) and optionally removes
the scrambled password file produced by iinit.
Usage: iexit [-vh] [full]
If 'full' is included the scrambled password is also removed.
-v verbose
-V very verbose
-h this help
$ iexit full

In the above example, the user used the '-h' option for the 'iexit' command to read the instructions and options, and then used 'iexit' with the option 'full'.

The next combined example will demonstrate a practical use case wherein the user connects to IDA and executes several commands:

$ iinit
Enter your current iRODS password:
$ ipwd
/ida/exampleorganisation/exampleproject

The user has one file and one directory in her home directory:

$ ils
/ida/exampleorganisation/exampleproject:
  test_file.dat
  C- /ida/exampleorganisation/exampleproject/published
$

The user creates a second directory 'datasets':

$ imkdir datasets
$ ils
/ida/exampleorganisation/exampleproject:
  test_file.dat
  C- /ida/exampleorganisation/exampleproject/datasets
  C- /ida/exampleorganisation/exampleproject/published
$ icd datasets
$ ils
/ida/exampleorganisation/exampleproject/datasets:
$

The user has a local file 'example_local_file.dat', which the user transfers to the 'datasets' directory:

$ ls example_local_file.dat
example_local_file.dat
$ iput example_local_file.dat
$ ils
/ida/exampleorganisation/exampleproject/datasets:
  example_local_file.dat

The user removes the 'datasets' directory along with all of its contents:

$ icd ..
$ ipwd
/ida/exampleorganisation/exampleproject
$ irm -rf /ida/exampleorganisation/exampleproject/datasets
$ ils
  test_file.dat
  C- /ida/exampleorganisation/exampleproject/datasets
  C- /ida/exampleorganisation/exampleproject/published

 

(Note: the user can at any time read instructions about a command by giving the '-h' option for a command. For example, 'irm -h')

The user downloads for her local machine the 'test_file.dati' file and closes the connection to IDA:

$ iget test_file.dat
$ ls test_file.dat
test_file.dat
$ iexit

 

Metadata handling
Metadata can be handled using the following commands:

imeta ls -d <filepath> Displays all the metadata of a file.
imeta ls -C <directory path> Displays all the metadata of a directory.
imeta add -d <filepath> "Result" "42" Adds the metadata field 'Result', which has a value of '42', for a file
imeta rm -d <filepath> "Result" "42" Removes the metadata field 'Result', which has a value of '42', from a file
imeta rm -C <directory path> "Result" "42" Removes the metadata field 'Result', which has a value of '42', from a directory
imeta rmw -d <filepath> "Result" % % Removes all the metadata fields named 'Result' from a file
imeta rmw -C <directory path> "Result" % % Removes all the metadata fields named 'Result' from a directory
 

Generally speaking, the 'imeta' command has a syntax of 'imeta <command> <target type> <target> <field> <value> <unit>'. More instructions are available by using the command 'imeta -h'.

The character set used in IDA is UTF-8. In practice this means that, for example, Latin-1 character set characters can not be used in metadata.

If you intend to use spaces in metadata fields or values, use double quotes around the fields or values. For example, "The results".

 

File and directory permissions
The following commands can be used to change file and directory permissions:

ichmod null <user> <path> Removes the user's permissions from a file/directory.
ichmod read <user> <path> Sets read permissions for the user for a file/directory.
ichmod write <user> <path> Sets write permissions for the user for a file/directory.
ichmod own <user> <path> Sets owner permissions for the user for a file/directory..
ils -A <path> Lists the file/directory permissions.
 

Often when using the 'ils -A' command, you will notice the attribute 'Inheritance - Enabled' for a directory. This is a setting that defines how the permissions of a directory will apply to its subdirectories. When it is set to 'Enabled', the files and subdirectories created under that directory will automatically inherit the same permissions as the directory has. This setting can be changed using the following command:

$ ichmod noinherit <hakemistopolku>

OR

$ ichmod inherit <hakemistopolku>

Further options are available with 'ichmod -h'.

 

 

Automating metadata handling and scripting

Example 1. Metadata entry, using shell/command line
The command line tools can be used like any other Linux commands and called from shell scripts. Lets assume for example that the user has metadata in the following text format which she wants to import to IDA:

version|2.0
size|420|bytes
length|10|rows

Lets assume that the above rows have been saved into a file 'file1.met'. By using the example script 'itext2meta', the above metadata can be added in IDA to the file 'myfile.dat' using the following command:

$ itext2meta myfile.dat < file1.met

Before executing the command, the user must have logged in by using 'iinit'.

The script calls the 'imeta' command to add metadata, taking into account IDA's metadata model. The example script 'itext2meta' can be used as a learning tool or a part of automation.

A visualised example of transferring data and metadata from a local system to IDA:

In a shell environment, multiple file metadata operations can be done from the command line without separate script files. For example, setting the metadata field "Rights Category" to "Public Domain" for all files with the file type '.c' in the current working directory:

$ ils | grep '\.c$' | while read i; do imeta set -d "$i" 'Rights Category' 'PUBLIC DOMAIN'; done

Note: when working with one-liners like these, you should be careful.