Step 1: Download iCommands for your operating system

Because CyVerse products are interdependent with iRODS iCommands and iRODS products such as FUSE, the instructions for downloading iCommands vary according to your OS.

• Linux
• Mac OS
• Windows

Linux

Installation via Package Manager

If you are using Linux and have the ability to install software (that is, you have sudo or root access) through a package manager such as yum or apt, you may install the irods-icommands package obtainable from one of the following links.

• CentOS 6
• CentOS 7
• Ubuntu 12
• Ubuntu 14 (Ubuntu 16 & Ubuntu 18 can use this package)

The CentOS packages require the the yum be configured to access the EPEL repository. The Ubuntu 14 package appears to also work for Ubuntu 16.04. Run the package installation commands appropriate for your package manager, replacing the filename as appropriate for your distribution version, as in the following examples.

For Debian/Ubuntu:

wget https://files.renci.org/pub/irods/releases/4.1.10/ubuntu14/irods-icommands-4.1.10-ubuntu14-x86_64.deb
apt-get install ./irods-icommands-4.1.10-ubuntu14-x86_64.deb

For RHEL/CentOS:

yum install https://files.renci.org/pub/irods/releases/4.1.10/centos6/irods-icommands-4.1.10-centos6-x86_64.rpm

Next , continue to Step 2 to configure iCommands.

Installation for Unprivileged Users

If you cannot use one of the packages from iRODS, we provide some installers for CentOS and Ubuntu that don't require special privileges to use. To do so, do the following.

1. Download the correct installer.

   • CentOS 6
   • CentOS 7 (not fully tested)
   • Ubuntu 12 (not fully tested)
   • Ubuntu 14

   alternate installers compatible with performance enhanced FUSE client

   If you intend to heavily use the iRODS FUSE client, it requires version 4.1.9 of the iCommands to be installed. Here are the installers for this version.

   • CentOS 6
   • CentOS 7 (not fully tested)
   • Ubuntu 12 (not fully tested)
   • Ubuntu 14

2. From a terminal window, run the installer with  sh .

   For example, if you were installing iCommands on an Ubuntu 14.04 system as the user cyverse-user, you would do something like the following example. The iCommands would end up being placed in the directory /home/cyverse-user/icommands.

   prompt> sh irods-icommands-4.1.10-ubuntu-14.installer
   Where would you like to install it? [/home/cyverse-user] 
   Expanding contents under /home/cyverse-user.
   Updating .bashrc
   done!
   
   To make the changes take effect in the current shell, please source your bashrc file, i.e., enter either `. ~/.bashrc`. or `bash`.

   Important: To make the changes take effect in the current shell, you will need to source your .bashrc file by entering either `. ~/.bashrc` .

   If you aren't using bash, or if your .bashrc file can't be edited, the environment variable IRODS_PLUGINS_HOME will need to be set to $INSTALL_BASE/icommands/plugins/ , where $INSTALL_BASE is the directory you provided to the installer. It is also recommended that you add the iCommands to your path. Since setting the environment variable and modifying your path is the last thing the installer does, you don't need to run the installer again.

   
   

3. Open a new terminal window, if necessary, and run ienv to check that the new version was installed.

   
   

4. Continue to Step 2 to configure iCommands.

Mac OS

iRODS does not currently offer a 4.1 download for Mac OS. However, CyVerse has created a custom build of the iRODS 4.1.9 iCommands. To obtain these, do the following.

1. Download the   Mac OS X iCommands 4.1.9 installer .
2. Find the downloaded file in the finder window, hold down the control button, and select the downloaded package.
3. Click Open to give permission for Mac to open the package.
   Note: if you try to directly click and install the downloaded file, privacy and security setting in new release of Mac OS will prevent the installation and warn that "CyVerse is a unknown publisher", it is important to follow step #2 and 3 above.
4. Use the installer and follow the instructions .
5. Open a new terminal window, if necessary, and run ienv to check that the new version was installed.
6. Continue to Step 2 to configure iCommands.

Unlike in other operating systems, on Mac OS, the command line environment configuration is added to your .bash_profile file.

Microsoft Windows

iRODS does not currently offer a 4.1 download for Windows users. If you are running Windows 10, iCommands can be run on the Linux subsystem. See  https://docs.microsoft.com/en-us/windows/wsl/install-win10 for information on installing the Linux subsystem. Then follow the iCommands for Linux instructions to install iCommands.

Step 2: Initialize/start the iRODS connection and configure the settings (One-time only or after changing your configuration)

The first time you use iCommands, or after you change a configuration detail such as resetting your CyVerse password, you must initiate the connection to iRODS.

In a terminal window, enter iinit to initialize iCommands and your Data Store connection. For example, here's what you would do if your iRODS user name is cyverse-user:

bash-3.2$ iinit
One or more fields in your iRODS environment file (irods_environment.json) are
missing; please enter them.
Enter the host name (DNS) of the server to connect to: data.cyverse.org
Enter the port number: 1247
Enter your irods user name: cyverse-user
Enter your irods zone: iplant
Those values will be added to your environment file (for use by
other i-commands) if the login succeeds.

Enter your current iRODS password:
bash-3.2$

Here are the values to enter.

[-]iRODS/lib/core/include/irods_load_plugin.hpp:53:resolve_plugin_path :
status [SYS_INVALID_INPUT_PARAM] errno [] -- message [does not exist [/opt/icommands/plugins/network]]

export IRODS_PLUGINS_HOME=/var/lib/irods/plugins/

Once iinit has finished, use ils to check that the iCommands is working. You should see your home directory at /iplant/home/your_user_name

When done, log out of the Data Store (especially important if on a shared or public computer) by entering iexit full. (To log back in on the same device, enter iinit.)
After you are successfully connected, you do not need to reenter your password to use the CyVerse Data Store from that computer unless you log out.

Advanced configuration settings (for power users only)

A full list of iRODS environment variables that may be set can be determined from ~/.irods/irods_environment.json section of the official iRODS documentation. The names environment variables are the all capitals version of the corresponding JSON field. Only IRODS_HOST, IRODS_PORT, IRODS_USER_NAME, and IRODS_ZONE_NAME are required for using the iCommands.

Setting up Bash autocomplete for iCommands

If using the Bash shell, you can enable tab auto-complete when using iCommands:

Download i-commands-auto.bash.

In your home directory, rename i-commands-auto.bash to .i-commands-auto.bash.

In your .bashrc or .bash_profile, enter the following:
source .i-commands-auto.bash

NetCDF iCommands

For the Linux distributions CentOS 6 and 7 and Ubuntu 12.04 and 14.04, there are three extra iCommands that support common NetCDF operations.  inc performs data operations on a list of NetCDF files. incarch archives a open ended time series data. incattr performs operation on attributes of NetCDF files. Each of these commands accepts the -h command line option. When a command is called with this option, it displays the command's help documentation.  Please see this help documentation for more information.

Installation

It is assumed that the core iCommands are already installed on your system. To install the NetCDF iCommands, root or sudo access is required.

Step 1 - Install iRODS Run-time Library

Before the NetCDF iCommands can be installed, the version 4.1.10 of the iRODS run-time library needs to be installed. Please install the appropriate version of the irods-runtime-4.1.10. The distribution specific packages can be found on  RENCI's website.

Step 2 - Install iRODS NetCDF API

Once the run-time library is installed, the iRODS NetCDF API library needs to be installed. Please use the appropriate link to the download the installation package and install it. The package installer will likely warn that irods user and/or group don't exist, and that it will be using root instead. These warnings are harmless, since the package contents should be installed with root ownership.

• CentOS 6
• CentOS 7
• Ubuntu 12
• Ubuntu 14

Step 3 - Install iRODS NetCDF iCommands

Once the run-time and API libraries are installed, the NetCDF iCommands can be installed. Please use the appropriate link to download the installation package and install it. The package installer will likely warn that irods user and/or group don't exist, and that it will be using root instead. These warnings are harmless, since the package contents should be installed with root ownership.

• CentOS 6
• CentOS 7
• Ubuntu 12
• Ubuntu 14

Next steps

To learn more about using iCommands and some common commands to use, see Using iCommands.