This box searches only documentation in the Data Store space. To search the entire CyVerse wiki, use the box at the upper right.


For overview information, see Data Store or Manage Data on the CyVerse website.

DATA STORE USER MANUAL
 

 

Skip to end of metadata
Go to start of metadata
IMPORTANT NOTE ABOUT UPGRADING TO 4.1.9

iCommands 4.1.9, the latest supported version for CyVerse services, has been released by iRODS. For a list of affected services and testing done, see Upgrading to iRODS 4.1.9.

About iCommands

iCommands is a collection of commands for Linux and Mac OS operating systems that are used in the iRODS system to interact with the CyVerse Data Store. Many commands are very similar to Unix utilities. For example, to list files and directories, in Linux you use ls, but in iCommands you use ils.

While iCommands are great for all transfers and for automating tasks via scripts, they are the best choice for large files (2-100 GB each) and for bulk file transfers (many small files). For a comparison of the different methods of uploading and downloading data items, see Downloading and Uploading Data.

iCommands must be installed and configured for your system. Once set up, CyVerse users can use iCommands to access files that have been shared by other users, as well as manage metadata, change permissions on data files and folders you own, and more.

Even if you don't have an account, you can download public files using iCommands. For more information, see the iCommands section on the  Downloading Data Files Without a User Account page. For information on using iCommands, see Using iCommands.

Setting up iCommands

iCommands must be set up and configured on each user's local machine or server, as outlined below, before you can transfer data to (with a CyVerse user account) and from the CyVerse Data Store using iCommands. Note that iCommands cannot be used to upload files into Data Store via URL from other sites (ftp, http, etc.). Without a CyVerse account, you can download public data from the Data Commons Repository (DCR).

For account users, you can download data from an external site using iCommands. To do so, download the file to a local machine using wget or a similar mechanism and then use iput to upload it to the Data Store. If you have a significant amount of external data to import from an external site, you may want to perform the transfer using a utility, such as Import by URL in the DE (not available using iCommands), or an Atmosphere instance.

Before you begin, you may want to watch a CyVerse video about iCommands.

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.

Using FUSE?

Icon

 If you plan to use FUSE independent of an Atmosphere image, please see Using FUSE to Mount the CyVerse Data Store to install the optimized FUSE client.

IMPORTANT! -- BEFORE YOU UPGRADE

Icon

Before upgrading to the 4.1.9 version, see Upgrading to iRODS 4.1.9 to view the list of services and testing done on the affected CyVerse offerings.

The most recent supported version for use with most CyVerse services is iRODS 4.1.9 (9/26/16 release).

 Not sure which version you have?

To find the version you have installed, use ienv to find the client version or imiscsvrinfo to find the server version.

Linux

Icon

This Linux installer was tested for iCommands 4.1.9 compatibility with CentOS 6 and Ubuntu 14.04 only.

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 the iRODS Download page. If using iCommands with FUSE, you should install the optimized FUSE client; see Using FUSE to Mount the CyVerse Data Store. Download the package appropriate for your distribution. The Ubuntu 14.04 package appears to also work for Ubuntu 16.04.CentOS 6 and 7 need FUSE dependencies installed before irods-icommands can be installed; run the following (Ubuntu 12.04 through 16.04 include these dependencies with the distribution):

Run the package installation commands appropriate for your package manager, replacing the filename as appropriate for your distribution and version, as in the following example:

For Debian/Ubuntu:

Code for Debian/Ubuntu

For RHEL/CentOS:

Code for RHEL/CentOS

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 6 and Ubuntu 14.04 that don't require special privileges to use. To do so, do the following.

iCommands can be installed into any directory without the requirement for elevated permissions. You must have write permission to the directory (such as /home/cyverse-user in the above example). If you encounter difficulties, you may want to seek assistance from your local IT support staff.

  1. Download the correct installer: CentOS 6 Installer or Ubuntu 14.04 Installer.
    Also available are the following three untested installers:
         
  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.

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

  4. Open a new terminal window, if necessary, and run ienv to check that the new version was installed.  
  5. Continue to Step 2 to configure iCommands.
Icon

If using iCommands in an HPC environment, which has many systems with iCommands installed, run the module load irods command to get access to iRODS iCommands.   

Mac OS

Icon

This Mac OS installer was tested for iCommands 4.1.9 compatibility with Mac OS 10.9 to 10.11 only.

iRODS does not currently offer a 4.1.9 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 package, hold down the control button, and select the downloaded package.
  3. Click Open to give permission for Mac to open the package.
  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.

Microsoft Windows (not available)

iRODS does not currently offer a 4.1.9 download for Windows users. If you already had version 3 of iCommands for Windows installed, the main functionality should work, but it has not been tested by CyVerse.  If necessary, you can use Cyberduck instead.   

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.

  1. 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:

     Example: iinit
    Terminal window displays:
  2. For both platforms, enter the following:

    For this line:

    Enter this:Comments
    Host:
    • irodsHost (for iRODS)
    • Host (for iDrop)
    data.iplantcollaborative.org 
    Port1247If required

    User:

    • irodsUserName (for iRODS)
    • User (for iDrop)

    (your CyVerse username) 
    If no CyVerse account or only accessing public data sets, use anonymous.

     

    Zone:

    • irodsZone (for iRODS)
    • Zone (for iDrop)
    iplant 

    Password:

    • Current iRODS password (for iRODS)
    • Password (for iDrop)

    (your CyVerse password) 
    If using the anonymous username, no password is required.

     
    Default Resource(leave blank)Defaults to whatever is available
    About Firewalls

    Transfers to the Data Store require firewalls to allow TCP port 1247 and TCP and UDP ports 20000-20399 to be open. For more information on firewalls and connecting to the Data Store, see Configuring Your Firewall to Connect to the Data Store.

    If you notice that long running transfers are terminated abruptly: Some institutional firewalls have policies governing the duration allowed for idle connections that may interfere with data transfers. 

    CyVerse staff can provide additional networking and subnet information for firewall policies upon request. For more information, contact CyVerse Support at support@cyverse.org.

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

  4. 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)

FOR POWER USERS ONLY

The following settings allow power users to apply more advanced configuration settings for iRODS, but may be safely ignored by others.

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 using the iCommands.

Setting up Bash autocomplete for iCommands

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

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

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

Next steps

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

  • No labels

1 Comment

  1. I published an Ansible role which installs iCommands (including irodsFs) for CentOS 5+ and Ubuntu 12+. This is designed to be modular and consumable by anyone, at CyVerse or elsewhere.

    https://github.com/CyVerse-Ansible/ansible-irods-icommands

    Whoever maintains these instructions, feel free to work this in as an installation option.