ibun

Usage: ibun -x [-hfb] [-R resource] structFilePath
               irodsCollection
Usage: ibun -c [-hf] [-R resource] [-D dataType] structFilePath
               irodsCollection
Usage: ibun --add [-h] structFilePath irodsCollection

Bundle file operations. This command allows structured files such as tar files to be uploaded and downloaded to/from iRODS.

A tar file containing many small files can be created with normal unix tar command on the client and then uploaded to the iRODS server as a normal iRODS file. The 'ibun -x' command can then be used to extract/untar the uploaded tar file. The extracted subfiles and subdirectories will appeared as normal iRODS files and sub-collections. The 'ibun -c' command can be used to tar/bundle an iRODS collection into a tar file.

For example, to upload a directory mydir to iRODS:

tar -chlf mydir.tar -C /x/y/z/mydir .
iput -Dtar mydir.tar .
ibun -x mydir.tar mydir

Note the use of -C option with the tar command which will tar the content of mydir but without including the directory mydir in the paths. The 'ibun -x' command extracts the tar file into the mydir collection. The target mydir collection does not have to exist nor be empty. If a subfile already exists in the target collection, the ingestion of this subfile will fail (unless the -f flag is set) but the process will continue.

If the -x and -R option are used together, the source structFile must already have a replica on the named resource.

It is generally a good practice to tag the tar file using the -Dtar flag when uploading the file using iput. But if the tag is not made, the server assumes it is a tar dataType. The dataType tag can be added afterward with the isysmeta command. For example: isysmeta mod /tempZone/home/rods/mydir.tar datatype 'tar file'

The following command bundles the iRods collection mydir into a tar file:

ibun -cDtar mydir1.tar mydir

If a copy of a file to be bundled does not exist on the target resource, a replica will automatically be made on the target resource. Again, if the -D flag is not used, the bundling will be done using tar.

The -b option when used with the -x option, specifies bulk registration which does up to 50 registrations at a time to reduce overhead.

Options are: -b bulk registration when used with -x to reduce overhead -R resource - specifies the resource to store to. This is optional in your environment -D dataType - the structFile data type. Valid only for -c option for specifying the target data type. Valid dataTypes are - t|tar|'tar file' for tar file. g|gzip|gzipTar for gzipped tar file, b|bzip2|bzip2Tar for bzip2 file, and z|zip|zipFile for an archive using 'zip'. If -D is not specified, the default is the tar dataType -x extract the structFile and register the extracted files and directories under the input irodsCollection -c bundle the files and sub-collection underneath the input irodsCollection and store it in the structFilePath -f force overwrite the structFile (-c) or the subfiles (-x). --add add or append to existing structFile. -h this help

icd

Changes iRODS the current working directory (collection)
Usage: icd [-vh] [directory]
If no directory is entered, the cwd is set back to your home
directory as defined in your .rodsEnv file.
Like the unix 'cd', '..' will move up one level and 
'/name' starts at the root.
 -v  verbose
 -V  very verbose
 -h  this help

ichksum

Usage: ichksum [-harvV] [-K|f] [-n replNum] [-R resource] [--silent]
           dataObj|collection ... 
Checksum one or more data-object or collection from iRODS space.

By default, objects are silently ignored if they already have a catalog checksum. Any checksum failure is logged to stderr, the command's exit code will be non-zero. If the command cannot execute its tasks for any reason, it may stop processing entirely.

Options are: -f force - checksum data-objects even if a checksum already exists in iCAT Overwrites checksum in catalog to achieve a consistent state, in case file checksum and catalog checksum differ. (This event is not logged.) -a checksum all replicas. ils -L should be used to list the values of all replicas If used together with -K, and the replicas have different checksums, an error message is displayed, but no checksum is updated in the catalog. -K verify the checksum value in iCAT. If the checksum value does not exist, compute and register one. If the catalog checksum exists and the file checksum differs, returns USER_CHKSUM_MISMATCH and does not update in the catalog. -n replNum - the replica to checksum; use -a to checksum all replicas. Return CAT_NO_ROWS_FOUND if the given replica number does not exist. If used in combination with -R, the replica number will take precedence. -R resource - the resource of the replica to checksum, If used in combination with -n, the replica number will take precedence. -r recursive - checksum the whole subtree; the collection, all data-objects in the collection, and any subcollections and sub-data-objects in the collection. --silent - No checksum output except error (in recursive mode, all directory names are still listed) -v verbose -V Very verbose -h this help

ichmod

Usage: ichmod [-rhvVM] null|read|write|own userOrGroup dataObj|Collection ...
 or    ichmod [-rhvVM] inherit Collection ...
 or    ichmod [-rhvVM] noinherit Collection ...
 -r  recursive - set the access level for all dataObjects
             in the entered collection and subCollections under it
 -v  verbose
 -V  Very verbose
 -M  Admin Mode
 -h  this help

Modify access to dataObjects (iRODS files) and collections (directories).

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 if you give 'own' to someone else, they can also give (and remove) access to others.

You can remove access by changing the access to 'null'.

Multiple paths can be entered on the command line.

If the entered path is a collection, then the access permissions to that collection will be modified. For example, you can give write access to a user or group so they can store files into one of your collections. Access permissions on collections are not currently displayed via ils.

The inherit/noinherit form sets or clears the inheritance attribute of one or more collections. When collections have this attribute set, new dataObjects and collections added to the collection inherit the access permisions (ACLs) of the collection. 'ils -A' displays ACLs and the inheritance status.

If you are the iRODS administrator, you can include the -M option to run in administrator mode and set the permissions on the collection(s) and/or data-objects as if you were the owner. This is more convenient than aliasing as the user.

Like Unix, if you remove your own access to an object ('null'), you will not be able to read it, but you can restore access via another 'ichmod' because for ichmod, you are still the owner.

icp

Usage: icp [-fkKPQrTvV] [-N numThreads] [-p physicalPath] [-R resource]
-X restartFile] srcDataObj|srcColl ...  destDataObj|destColl
icp copies an irods data-object (file) or collection (directory) to another
data-object or collection.

The -Q option specifies the use of the RBUDP transfer mechanism which uses the UDP protocol for data transfer. The UDP protocol is very efficient if the network is very robust with few packet losses. Two environment variables - rbudpSendRate and rbudpPackSize are used to tune the RBUDP data transfer. rbudpSendRate is used to throttle the send rate in kbits/sec. The default rbudpSendRate is 600,000. rbudpPackSize is used to set the packet size. The default rbudpPackSize is 8192.

The -X option specifies that the restart option is on and the restartFile input specifies a local file that contains the restart info. If the restartFile does not exist, it will be created and used for recording subsequent restart info. If it exists and is not empty, the restart info contained in this file will be used for restarting the operation. Note that the restart operation only works for uploading directories and the path input must be identical to the one that generated the restart file

The -T option will renew the socket connection between the client and server after 10 minutes of connection. This gets around the problem of sockets getting timed out by the firewall as reported by some users.

Options are: -Q use RBUDP (datagram) protocol for the data transfer -f force - write data-object even it exists already; overwrite it -k checksum - calculate a checksum on the data -K verify checksum - calculate and verify the checksum on the data -N number specifies the number of I/O threads to use, by default a rule is used to determine the best value. -p physicalPath specifies the path on the storage resource on which to store. Normally, you let the irods system automatically determine this. -P output the progress of the copy. -R resource - specifies the resource to store to. This can also be specified in your environment or via a rule set up by the administrator. -r recursive - copy the whole subtree -T renew socket connection after 10 minutes -v verbose - display various messages while processing -V very verbose -X restartFile - specifies that the restart option is on and the restartFile input specifies a local file that contains the restart info. -h this help

ienv

Usage: ienv [-h]
Display current irods environment. Equivalent to iinit -l.
Options are:
 -h  this help

ierror

Converts an irods error code to text.
Usage: ierror [-vVh] errorNumber
The errorNumber can be preceeded with minus sign (-) or not
 -h  this help

iexecmd

Usage: iexecmd [-hv] [-p hintPath]|[-P hintPath] [-H hostAddr] command
Remotely Execute a command installed in the server/bin/cmd directory of 
the server.
The input parameter 'command' is the remote command to execute. Input
arguments  for the command is supported by appending arguments to the
command to be executed. The command and arguments must be in quotes to
differentiate the arguments from the arguments of the iexecmd. e.g.:
    iexecmd -H zero.sdsc.edu "hello Mary"
If neither -H, -p nor -P is specified, the command will be executed on
the host where the client is connected.

Options are: -H hostAddr - the host address where the command will be executed. -p hintPath - A full iRODS file path. The command will be executed on the host where this file is stored. -P hintPath - Same as the -p option except that the resolved pphysical path from the logical hintPath will be used as the first argument the command -v verbose -h this help

iexit

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

ifsck

Usage: ifsck [-rhK] srcPhysicalFile|srcPhysicalDirectory ... 
Check if a local data object or a local collection content is
consistent in size (or optionally its checksum) with its
registered size (and optionally its checksum) in iRODS.
It allows to detect iRODS files which have been corrupted or
modified outside the iRODS framework on the local filesytem.
srcPhysicalFile or srcPhysicalDirectory must be a full path name.
Options are:
 -K  verify the checksum of the local file wrt the one registered in iRODS.
     Only relevant if the checksum has been computed for the iRODS objects.
 -r  recursive - scan local subdirectories
 -h  this help

iget

Usage: iget [-fIKPQrUvVT] [-n replNumber] [-N numThreads] [-X restartFile]
[-R resource] [--lfrestart lfRestartFile] [--retries count] [--purgec]
[--rlock] srcDataObj|srcCollection ... destLocalFile|destLocalDir

Usage: iget [-fIKPQUvVT] [-n replNumber] [-N numThreads] [-X restartFile] [-R resource] [--lfrestart lfRestartFile] [--retries count] [--purgec] [--rlock] srcDataObj|srcCollection

Usage: iget [-fIKPQUvVT] [-n replNumber] [-N numThreads] [-X restartFile] [-R resource] [--lfrestart lfRestartFile] [--retries count] [--purgec] [--rlock] srcDataObj ... -

Get data-objects or collections from iRODS space, either to the specified local area or to the current working directory.

Data Objects with multiple replicas in iRODS may have one or more 'stale' replicas (will not display the & before the filename in ils -l or ils -L). iRODS will not serve a stale or 'dirty' replica unless asked specifically (by using the -R option). Without the -R option, a clean replica will be selected and served to the client.

If the destLocalFile is '-', the files read from the server will be written to the standard output (stdout). Similar to the UNIX 'cat' command, multiple source files can be specified.

The -X option specifies that the restart option is on and the operation is restartable. The restartFile input specifies a local file that contains the restart info. If the restartFile does not exist, it will be created and used for recording subsequent restart info. If it exists and is not empty, the restart info contained in this file will be used to restart the operation. Note that the operation is not restarted automatically when it failed. Another iget -X run must be made to continue from where it left off using the restart info. But the -X option can be used in conjunction with the --retries option to automatically restart the operation in case of failure. Also note that the restart operation only works for downloading directories and the path input must be identical to the one that generated the restart file.

The --lfrestart option specifies that the large file restart option is on and the lfRestartFile input specifies a local file that contains the restart info.

The --lfrestart option can be used together with the -X option to do large file transfer restart as part of the overall collection download restart.

Large files are defined by the 'maximum_size_for_single_buffer_in_megabytes' advanced configuration setting.

The -Q option specifies the use of the RBUDP transfer mechanism which uses the UDP protocol for data transfer. The UDP protocol is very efficient if the network is very robust with few packet losses. Two environment variables - rbudpSendRate and rbudpPackSize are used to tune the RBUDP data transfer. rbudpSendRate is used to throttle the send rate in kbits/sec. The default rbudpSendRate is 600,000. rbudpPackSize is used to set the packet size. The default rbudpPackSize is 8192. The -V option can be used to show the loss rate of the transfer. If the lost rate is more than a few %, the sendrate should be reduced.

The -T option will renew the socket connection between the client and server after 10 minutes of connection. This gets around the problem of sockets getting timed out by the firewall as reported by some users.

Options are: -f force - write local files even it they exist already (overwrite them) -I redirect connection - redirect the connection to connect directly to the best (determiined by the first 10 data objects in the input collection) resource server. -K verify the checksum -n replNumber - retrieve the copy with the specified replica number -N numThreads - the number of thread to use for the transfer. A value of 0 means no threading. By default (-N option not used) the server decides the number of threads to use. --purgec - Purge the staged cache copy after downloading a COMPOUND object -P output the progress of the download. -r recursive - retrieve subcollections -R resource - the preferred resource -T renew socket connection after 10 minutes -Q use RBUDP (datagram) protocol for the data transfer -v verbose -V Very verbose -X restartFile - specifies that the restart option is on and the restartFile input specifies a local file that contains the restart info. --retries count - Retry the iget in case of error. The 'count' input specifies the number of times to retry. It must be used with the -X option --lfrestart lfRestartFile - specifies that the large file restart option is on and the lfRestartFile input specifies a local file that contains the restart info. -t ticket - ticket (string) to use for ticket-based access. --rlock - use advisory read lock for the download --kv_pass - pass quoted key-value strings through to the resource hierarchy, of the form key1=value1;key2=value2 -h this help

ihelp

Usage: ihelp [-ah] [icommand]
Display iCommands synopsis or a particular iCommand help text
Options are:
 -h  this help
 -a  print the help text for all the iCommands

Run with no options to display a synopsis of the iCommands

iinit

Creates a file containing your iRODS password in a scrambled form,
to be used automatically by the icommands.
Usage: iinit [-ehvVl] [--ttl TimeToLive]
 -e  echo the password as you enter it (normally there is no echo)
 -l  list the iRODS environment variables (only)
 -v  verbose
 -V  Very verbose
--ttl ttl  set the password Time To Live (specified in hours)
           Run 'iinit -h --ttl' for more
 -h  this help

ils

Usage: ils [-ArlLv] dataObj|collection ... 
Usage: ils --bundle [-r] dataObj|collection ... 
Display data Objects and collections stored in irods.
Options are:
 -A  ACL (access control list) and inheritance format
 -l  long format
 -L  very long format
 -r  recursive - show subcollections
 -t  ticket - use a read (or write) ticket to access collection information
 -v  verbose
 -V  Very verbose
 -h  this help
 --bundle - list the subfiles in the bundle file (usually stored in the
     /myZone/bundle collection) created by iphybun command.

ilsresc

ilsresc lists iRODS resources
Usage: ilsresc [-lvVh] [--tree] [--ascii] [Name]
If Name is present, list only that resource, 
otherwise list them all 
Options are:
 -l Long format - list details
 -v verbose
 -V Very verbose
 -z Zonename  list resources of specified Zone
 --tree - tree view
 --ascii - use ascii character set to build tree view (ignored without --tree)
 -h This help

imcoll

Usage: imcoll -m mountType [-R resource] mountDirectory|structuredFilePath
               irodsCollection
Usage: imcoll -Usp irodsCollection

Used to manage (mount, unmount, link, synchronize and purge of cache) iRODS collections and the associated cache. Full path must be supplied for both physicalFilePath and irodsPath.

The -m option can be used to associate (mount) an iRODS collection with a a physical directory (e.g.,a UNIX directory) or a structured file. If the mountType is 'f' or 'filesystem', the first argument is the UNIX directory path to be mounted. Only the top level collection/directory will be registered. The entire content of the registered directory can then be accessed using iRODS commands such as iput, iget, ils and the client APIs. This is similar to mounting a UNIX file system except that a UNIX directory is mounted to an iRODS collection. For example, the following command mounts the /temp/myDir UNIX directory to the /tempZone/home/myUser/mymount collection: imcoll -m filesystem /temp/myDir /tempZone/home/myUser/mymount

An admin user will be able to mount any Unix directory. But for normal user, he/she needs to have a UNIX account on the server with the same name as his/her iRODS user account and only UNIX directory created with this account can be mounted by the user. Access control to the mounted data will be based on the access permission of the mounted collection.

If the mountType is 'l' or 'link', the request is for a collection soft link. the first argument is the iRODS collection to be linked or the target collection name. The second argument is the link collection name The link collection must not exist or must be an empty collection. If the mountType is 't' or 'tar', the first argument is the iRODS logical path of a tar file which will be used as the 'structured file' for the mounted collection. The [-R resource] option is used to specify the resource to create this tar structured file in case it does not already exist. Once the tar structured file is mounted, the content of the tar file can be accessed using iRODS commands such as iput ils, iget, and the client APIs. For example, the following command mounts the iRODS tar file /tZone/home/myUser/tar/foo.tar to the /tZone/home/myUser/tarcoll collection: imcoll -m tar /tZone/home/myUser/tar/foo.tar /tZone/home/myUser/tardir

The tar structured file implementation uses a cache on the server to cache the mounted tar file. i.e., the tar file is untarred to a cache on the server before any iRODS operation. The 'ils -L' command can be use to list the properties of a mounted collection and the status of the associated cache. For example, the following is the output of the ils command:

C- /tZone/home/myUser/tardir tarStructFile /tZone/home/myUser/tar/foo.tar /data/Vault8/rods/tar/foo.tar.cacheDir0;;;demoResc;;;1

The output shows that /tZone/home/myUser/tardir is a tar structured file mounted collection. The iRODS path of the tar file is in /tZone/home/myUser/tar/foo.tar. The last item actually contains 3 items separated the string ;;;. It showed that the tar file is untarred into the /data/Vault8/rods/tar/foo.tar.cacheDir0 directory in the demoResc resource. The value of '1' for the last item showed that the cache content has been changed (dirty) and the original tar file needs be synchronized with the changes. The -s option can be used to synchronize the tar file with the cache. For example:

imcoll -s /tZone/home/myUser/tardir

The -p option can be used to purge the cache.

For example:

imcoll -p /tZone/home/myUser/tardir

The -s and -p can be used together to synchronize the tar file and then purge the cache.

The -U option can be used to unmount an iRODS collection. For example, the following command unmounts the /tempZone/home/myUser/mymount collection: imcoll -U /tempZone/home/myUser/mymount

Options are: -R resource - specifies the resource to store to. This can also be specified in your environment or via a rule set up by the administrator. -m mountType - mount a directory or structured file to a collection Valid mountType are f|filesystem, l|link, t|tar -U unmount the collection -s synchronize the tar file with the cache -p purge the associated cache -h this help

imiscsvrinfo

Usage: imiscsrvinfo [-hvV]
 -v  verbose
 -V  Very verbose
 -h  this help
Connect to the server and retrieve some basic server information.
Can be used as a simple test for connecting to the server.

imkdir

Usage: imkdir [-phvV] collection ...
Create one or more new collections
Options are:
 -p  make parent directories as needed
 -v  verbose
 -V  Very verbose
 -h  this help

imv

Usage: imv [-hvV] srcDataObj|srcColl ...  destDataObj|destColl
imv moves/renames an irods data-object (file) or collection (directory) to
another, data-object or collection. The move works if both the source and
target are normal (registered in the iCAT) iRODS objects. It also works when
the source object is in a mounted collection (object not registered in the
iCAT) and the target is a normal object. In fact, this may provide a way
to design a drop box where data can be uploaded quickly into a mounted
collection and then in the background, moved to the eventual target
collection (where data are registered in the iCAT). But currently, the
move from a normal collection to a mounted collection is not supported.

If you do a move and rename at the same time, for example, 'imv file1 coll1/file2', it will normally succeed if there's no conflicting data-object name in the source collection (file2) but fail (giving error CAT_NAME_EXISTS_AS_DATAOBJ) if there is, since, internally IRODS is doing a rename and then a move. Please handle this by running multiple separate 'imv' commands.

Options are: -v verbose - display various messages while processing -V very verbose -h help - this help

ipasswd

Changes your irods password and, like iinit, stores your new iRODS
password in a scrambled form to be used automatically by the icommands.
Prompts for your old and new passwords.
Usage: ipasswd [-hvVl]
 -v  verbose
 -V  Very verbose
 -l  long format (somewhat verbose)
 -e  echo the password as entered
 -f  force: do not ask user to reenter the new password
 -h  this help

iphybun

Usage: iphybun [-hK] [-D dataType] [-S srcResource] [-R resource] [-s maxSize_in_GB] [-N numOfSubFiles] collection ... 
DEPRECATED - iphybun allows iRODS administrators to physically bundle files in a collection into
a number of tar files to make it more efficient to store these files on tape.
The tar files are placed into the /myZone/bundle/.... collection with file
names - collection.aRandomNumber. A new tar file will be created whenever
the number of subfiles exceeds 5120 (default value or the value given by
the -N option) or the total size of the subfiles exceeds 4 GBytes
(default value or the value given by the -s option).
A replica is registered for each bundled sub-files with
a fictitious resource - 'bundleResc' and a physical file path pointing to
the logical path of the tar bundle file. Whenever this copy of the subfile
is accessed, the tar file is untarred and staged automatically to the 
'cache' resource. Each extracted file is registered as a replica of its
corresponding subfiles.

iphymv

Usage: iphymv [-hMrvV] [-n replNum] [-S srcResource]  [-R destResource] 
dataObj|collection ... 

Physically move a file in iRODS to another storage resource.

Note that if the source copy has a checksum value associated with it, a checksum will be computed for the replicated copy and compared with the source value for verification.

Note that if the source or destination resource is within a hierarchy, a full resource hierarchy (semicolon delimited) must be specified: iphymv -S demoResc -R 'pt1;r1;s1' /tempZone/home/alice/test.txt

Options are: -r recursive - phymove the whole subtree -M admin - admin user uses this option to phymove other users files -n replNum - the replica to be phymoved, typically not needed -S srcResource - specifies the source resource for the move. If specified, the replica stored on this resource will be moved. Otherwise, any one of the replicas will be moved -R destResource - specifies the destination resource for the move. This can also be specified, in your environment or via a rule set up by the administrator. -v verbose -V Very verbose -h this help

ips

Usage: ips [-ahv] [-R resource] [-z zone] [-H hostAddr]

Display connection information of iRODS agents currently running in the iRODS federation. By default, agent info for the iCAT enabled server (IES) is displayed.

The -H and -R option can be used to specify other servers for the info display. The -z option can be used to specify a remote zone for the info display. If the -a option is used, agent info for all servers in the iRODS federation will be displayed.

By default, a line is output for each connection. Each line contains items given in the following order: - pid of the agent process - client user - wall clock time of the connection - the client process - the 'from' address of the connection

If the -v option is specified, the proxy user of the connection is added following the client user.

Options are:

-a all servers -h this help -H hostAddr - the host address of the server -R resource - the server where the resource is located -v verbose -z zone - the remote zone

iput

Usage: iput [-abfIkKPQrtTUvV] [-D dataType] [-N numThreads] [-n replNum]
             [-p physicalPath] [-R resource] [-X restartFile] [--link]
             [--lfrestart lfRestartFile] [--retries count] [--wlock]
             [--purgec] [--kv_pass=key-value-string] [--metadata=avu-string]
             [--acl=acl-string]  localSrcFile|localSrcDir ...  destDataObj|destColl
Usage: iput [-abfIkKPQtTUvV] [-D dataType] [-N numThreads] [-n replNum] 
             [-p physicalPath] [-R resource] [-X restartFile] [--link]
             [--lfrestart lfRestartFile] [--retries count] [--wlock]
             [--purgec] [--kv_pass=key-value-string] [--metadata=avu-string]
             [--acl=acl-string]  localSrcFile

Store a file into iRODS. If the destination data-object or collection are not provided, the current iRODS directory and the input file name are used.

The -X option specifies that the restart option is on and the operation is restartable. The restartFile input specifies a local file that contains the restart information. If the restartFile does not exist, it will be created and used for recording subsequent restart information. If it exists and is not empty, the restart information contained in this file will be used to restart the operation. Note that the operation is not restarted automatically when it failed. Another iput -X run must be made to continue from where it left off using the restart information. But the -X option can be used in conjunction with the --retries option to automatically restart the operation in case of failure. Also note that the restart operation only works for uploading directories and the path input must be identical to the one that generated the restart file.

The --lfrestart option specifies that the large file restart option is on and the lfRestartFile input specifies a local file that contains the restart information. Currently, only files larger than 32 Mbytes will be restarted. The --lfrestart option can be used together with the -X option to do large file transfer restart as part of the overall directory upload restart.

If the -f option is used to overwrite an existing data-object, the copy in the resource specified by the -R option will be picked if it exists. Otherwise, one of the copies in the other resources will be picked for the overwrite. Note that a copy will not be made in the specified resource if a copy in the specified resource does not already exist. The irepl command should be used to make a replica of an existing copy.

The -I option specifies the redirection of the connection so that it can be connected directly to the resource server. This option can improve the performance of uploading a large number of small (<32 Mbytes) files. This option is only effective if the source is a directory and the -f option is not used.

The -Q option specifies the use of the RBUDP transfer mechanism which uses the UDP protocol for data transfer. The UDP protocol is very efficient if the network is very robust with few packet losses. Two environment variables - rbudpSendRate and rbudpPackSize are used to tune the RBUDP data transfer. rbudpSendRate is used to throttle the send rate in kbits/sec. The default rbudpSendRate is 600,000. rbudpPackSize is used to set the packet size. The default rbudpPackSize is 8192. The -V option can be used to show the loss rate of the transfer. If the loss rate is more than a few %, the rbudpSendRate should be reduced.

The -T option will renew the socket connection between the client and server after 10 minutes of connection. This gets around the problem of sockets getting timed out by the server firewall as reported by some users.

The -b option specifies the bulk upload operation which can do up to 50 uploads at a time to reduce overhead. If the -b option is specified with the -f option to overwrite existing files, the operation will work only if there is no existing copy at all or if there is an existing copy in the target resource. The operation will fail if there are existing copies but not in the target resource because this type of operation requires a replication operation and bulk replication has not been implemented yet. The bulk option does work for mounted collections which may represent the quickest way to upload a large number of small files.

Options are: -a all - update all existing copies -b bulk upload to reduce overhead -D dataType - the data type string -f force - write data-object even it exists already; overwrite it -I redirect connection - redirect the connection to connect directly to the resource server. -k checksum - calculate a checksum on the data server-side, and store it in the catalog. -K verify checksum - calculate and verify the checksum on the data, both client-side and server-side, and store it in the catalog. --link - ignore symlink. -n replNum - the replica to be replaced, typically not needed -N numThreads - the number of threads to use for the transfer. A value of 0 means no threading. By default (-N option not used) the server decides the number of threads to use. --purgec Purge the staged cache copy after uploading an object to a COMPOUND resource -p physicalPath - the absolute physical path of the uploaded file on the server -P output the progress of the upload. -Q use RBUDP (datagram) protocol for the data transfer -R resource - specifies the resource to store to. This can also be specified in your environment or via a rule set up by the administrator. -r recursive - store the whole subdirectory -t ticket - ticket (string) to use for ticket-based access -T renew socket connection after 10 minutes -v verbose -V Very verbose -X restartFile - specifies that the restart option is on and the restartFile input specifies a local file that contains the restart information. --retries count - Retry the iput in case of error. The 'count' input specifies the number of times to retry. It must be used with the -X option --lfrestart lfRestartFile - specifies that the large file restart option is on and the lfRestartFile input specifies a local file that contains the restart information. --wlock - use advisory write (exclusive) lock for the upload --kv_pass - pass quoted key-value strings throught to the resource hierarchy, of the form key1=value1;key2=value2 --metadata - atomically assign metadata after a data object is registered in the catalog. Metadata is encoded into a quoted string of the form attr1;val1;unit1;attr2;val2;unit2; --acl - atomically apply ACLs of the form 'perm user_or_group;perm user_or_group;' where 'perm' is defined as null|read|write|own -h this help

ipwd

Shows your iRODS Current Working Directory.
Usage: ipwd [-vVh]
 -v  verbose
 -V  very verbose
 -h  this help

iqdel

Usage: iqdel [-vVh] ruleId [...]
Usage: iqdel [-a] [-u user]

iqdel removes delayed rules from the queue. multiple ruleIds may be included on the command line. The -a option specifies the removal of all delayed rules The -u option specifies the removal of all delayed rules of the given user The -a and -u options cannot be used together

Also see iqstat and iqmod.

iqmod

Usage: iqmod [-vVh] ruleId FIELD_NAME fieldValue

iqmod modifies values in existing delayed rules.

FIELD_NAME can be: ruleName reiFilePath userName exeAddress exeTime exeFrequency priority estimateExeTime notificationAddr lastExeTime or exeStatus

Also see iqstat and iqdel.

iqstat

Usage: iqstat [-luvVh] [-u user] [ruleId]
Show information about your pending iRODS rule executions
or for the entered user.
 -a        display requests of all users
 -l        for long format
 -u user   for the specified user
 ruleId for the specified rule

See also iqdel and iqmod

iquest

Usage: iquest [-hz] [--no-page] [ [hint] format]  selectConditionString 
Usage: iquest --sql 'pre-defined SQL string' [format] [arguments] 
Usage: iquest attrs
Options are:
 -h  this help
 -z Zonename  the zone to query (default or invalid uses the local zone)
 --no-page    do not prompt asking whether to continue or not
              (by default, prompt after a large number of results (500)
format is C format restricted to character strings.
selectConditionString is of the form: SELECT  [, ] [WHERE  [ AND ]]
attribute can be found using 'iquest attrs' command
condition is of the form:   
rel-op is a relational operator: eg. =, <>, >,<, like, not like, between, etc.,
value is either a constant or a wild-carded expression.
One can also use a few aggregation operators such as sum,count,min,max and avg,
or order and order_desc (descending) to specify an order (if needed).
Use % and _ as wild-cards, and use \ to escape them.
If 'no-distinct' appears before the selectConditionString, the normal
distinct option on the SQL will bypassed (this is useful in rare cases).
If uppercase (or upper) appears before the selectConditionString, the
database value in the 'where' condition will be made upper case so one can do
case-insensitive tests (using upper-case literals).

The --sql option executes a pre-defined SQL query. The specified query must match one defined by the admin (see 'iadmin h asq' (add specific query)). A few of these may be defined at your site. A special alias 'ls' ('--sql ls') is normally defined to display these. You can specify these via the full SQL or the alias, if defined. Generally, it is better to use the general-query (non --sql forms herein) since that generates the proper SQL (knows how to link the ICAT tables) and handles access control and other aspects of security. If the SQL includes arguments, you enter them following the SQL. As without --sql, you can enter a printf format statement to use in formatting the results (except when using aliases).

Examples: iquest "SELECT DATA_NAME, DATA_CHECKSUM WHERE DATA_RESC_NAME like 'demo%'" iquest "For %-12.12s size is %s" "SELECT DATA_NAME , DATA_SIZE WHERE COLL_NAME = '/tempZone/home/rods'" iquest "SELECT COLL_NAME WHERE COLL_NAME like '/tempZone/home/%'" iquest "User %-6.6s has %-5.5s access to file %s" "SELECT USER_NAME, DATA_ACCESS_NAME, DATA_NAME WHERE COLL_NAME = '/tempZone/home/rods'" iquest " %-5.5s access has been given to user %-6.6s for the file %s" "SELECT DATA_ACCESS_NAME, USER_NAME, DATA_NAME WHERE COLL_NAME = '/tempZone/home/rods'" iquest no-distinct "select META_DATA_ATTR_NAME" iquest uppercase "select COLL_NAME, DATA_NAME WHERE DATA_NAME like 'F1'" iquest "SELECT RESC_NAME, RESC_LOC, RESC_VAULT_PATH, DATA_PATH WHERE DATA_NAME = 't2' AND COLL_NAME = '/tempZone/home/rods'" iquest "User %-9.9s uses %14.14s bytes in %8.8s files in '%s'" "SELECT USER_NAME, sum(DATA_SIZE),count(DATA_NAME),RESC_NAME" iquest "select sum(DATA_SIZE) where COLL_NAME = '/tempZone/home/rods'" iquest "select sum(DATA_SIZE) where COLL_NAME like '/tempZone/home/rods%'" iquest "select sum(DATA_SIZE), RESC_NAME where COLL_NAME like '/tempZone/home/rods%'" iquest "select order_desc(DATA_ID) where COLL_NAME like '/tempZone/home/rods%'" iquest "select count(DATA_ID) where COLL_NAME like '/tempZone/home/rods%'" iquest "select RESC_NAME where RESC_CLASS_NAME IN ('bundle','archive')" iquest "select DATA_NAME,DATA_SIZE where DATA_SIZE BETWEEN '100000' '100200'"

iquota

Usage: iquota [-uavVh] [UserName] [usage]

Show information on iRODS quotas (if any). By default, information is displayed for the current iRODS user.

The 'over' values indicate whether the user or group is over quota or not and by how much; positive values are over-quota. The 'usage' information shows how much data is stored on each resource, when last determined.

Options: -a All users -u UserName[#ZoneName] - for the specified user usage - show usage information

Examples: iquota iquota -a iquota usage iquota -a usage iquota -u josh

ireg

Usage: ireg [-hfCkKvV] [--repl] [-D dataType] [-R resource]
               physicalFilePath, irodsPath

Register a file or a directory of files and subdirectory into iRODS. The file or the directory of files must already exist on the server where the resource is located. The full path must be supplied for both the physicalFilePath and the irodsPath.

With the -C option, the entire content beneath the physicalFilePath (files and subdirectories) will be recursively registered beneath the irodsPath. For example, the command:

ireg -C /tmp/src1 /tempZone/home/myUser/src1

grafts all files and subdirectories beneath the directory /tmp/src1 to the collection /tempZone/home/myUser/src1

By default, only rodsAdmin users are allowed to register files or directories. More permissive registration policies can be set in the server's rule base using the acNoChkFilePathPerm() rule.

It is considered best practice for the target resource be a single local storage resource. A side effect of not following this best practice could be unwanted extra replicas of a mounted collection or other structured file. Registered files should be well-understood by the administrator so the line between iRODS-managed data and user-managed data can be properly maintained.

Options are: -R resource - specifies the target storage resource. This can also be specified in your environment or via a rule set up by the administrator. -C the specified path is a directory. The default assumes the path is a file. -f Force. If the target collection already exists, register the files and subdirectories that have not already been registered in the directory. -k calculate a checksum on the iRODS client and store with the file details. -K calculate a checksum on the iRODS server and store with the file details. --repl register the physical path as a replica. --exclude-from filename - don't register files matching patterns contained in the specified file. The file must be readable on the server where the resource is located and must be an absolute pathname. -v verbose -V Very verbose -h this help

irepl

Usage: irepl [-aBMPQrTvV] [-n replNum] [-R destResource] [-S srcResource]
[-N numThreads] [-X restartFile] [--purgec]  [--rlock]dataObj|collection ... 

Replicate a file in iRODS to another storage resource.

The -Q option specifies the use of the RBUDP transfer mechanism which uses the UDP protocol for data transfer. The UDP protocol is very efficient if the network is very robust with few packet losses. Two environment variables - rbudpSendRate and rbudpPackSize are used to tune the RBUDP data transfer. rbudpSendRate is used to throttle the send rate in kbits/sec. The default rbudpSendRate is 600,000. rbudpPackSize is used to set the packet size. The default rbudpPackSize is 8192.

The -X option specifies that the restart option is on and the restartFile input specifies a local file that contains the restart info. If the restartFile does not exist, it will be created and used for recording subsequent restart info. If it exists and is not empty, the restart info contained in this file will be used for restarting the operation. Note that the restart operation only works for uploading directories and the path input must be identical to the one that generated the restart file

The -T option will renew the socket connection between the client and server after 10 minutes of connection. This gets around the problem of sockets getting timed out by the firewall as reported by some users.

Note that if -a and -U options are used together, it means update all stale copies.

Note that if the source copy has a checksum value associated with it, a checksum will be computed for the replicated copy and compare with the source value for verification.

Note that replication is always within a zone. For cross-zone duplication see irsync which can operate within a zone or across zones.

Options are: -a all - if used with -U, update all stale copies -B Backup mode - if a good copy already exists in this resource, don't make another copy. -P output the progress of the replication. -Q use RBUDP (datagram) protocol for the data transfer -U Update (Synchronize) an old replica with the latest copy. (see -a) -M admin - admin user uses this option to backup/replicate other users files -N number specifies the number of I/O threads to use, by default a rule is used to determine the best value. -r recursive - copy the whole subtree -n replNum - the replica to copy, typically not needed -R destResource - specifies the destination resource to store to. This can also be specified in your environment or via a rule set up by the administrator. -S srcResource - specifies the source resource of the data object to be replicated. If specified, only copies stored in this resource will be replicated. Otherwise, one of the copy will be replicated. -T renew socket connection after 10 minutes -v verbose -V Very verbose -X restartFile - specifies that the restart option is on and the restartFile input specifies a local file that contains the restart info. --purgec Purge the staged cache copy after replicating an object to a COMPOUND resource --rlock - use advisory read lock for the replication -h this help

Also see 'irsync' for other types of iRODS/local synchronization.

irm

Usage: irm [-rUfvVh] [-n replNum] [--empty] dataObj|collection ... 
Remove one or more data-object or collection from iRODS space. By default, 
the data-objects are moved to the trash collection (/myZone/trash) unless
either the -f option or the -n option is used.

The -U option allows the unregistering of the data object or collection without deleting the physical file. Normally, a normal user cannot unregister a data object if the physical file is located in a resource vault. The acNoChkFilePathPerm rule allows this check to be bypassed.

There is no -R option (remove replica from a named resource) at this time. Please use itrim (with the -S option) instead.

The irmtrash command should be used to delete data-objects in the trash collection.

Options are: -f force - Immediate removal of data-objects without putting them in trash . -n replNum - the replica to remove; if not specified remove all replicas. This option is applicable only to the removal of data object and will be ignored for collection removal. -r recursive - remove the whole subtree; the collection, all data-objects in the collection, and any subcollections and sub-data-objects in the collection. -U unregister the file or collection -v verbose -V Very verbose --empty If the file to be removed is a bundle file (generated with iphybun) remove it only if all the subfiles of the bundle have been removed. -h this help

irmtrash

Usage: irmtrash [-hMrvV] [--orphan] [-u user] [-z zoneName] [--age age_in_minutes] [dataObj|collection ...] 
Remove one or more data-object or collection from a RODS trash bin.
If the input dataObj|collection is not specified, the entire trash bin
of the user (/$myZone/trash/$myUserName) will be removed.

The dataObj|collection can be used to specify the paths of dataObj|collection in the trash bin to be deleted. If the path is relative (does not start with '/'), the path assumed to be relative to be the user's trash home path e.g., /myZone/trash/home/myUserName.

An admin user can use the -M option to delete other users' trash bin. The -u option can be used by an admin user to delete the trash bin of a specific user. If the -u option is not used, the trash bins of all users will be deleted.

Options are: -r recursive - remove the whole subtree; the collection, all data-objects in the collection, and any subcollections and sub-data-objects in the collection. -M admin mode --orphan remove the orphan files in the /myZone/trash/orphan collection It must be used with the -M option. -u user - Used with the -M option allowing an admin user to delete a specific user's trash bin. -v verbose -V Very verbose -z zoneName - the zone where the rm trash will be carried out -h this help

irsync

Usage: irsync [-rahKsvV] [-N numThreads] [-R resource] [--link] [--age age_in_minutes]
          sourceFile|sourceDirectory [....] targetFile|targetDirectory

Synchronize the data between a local copy (local file system) and the copy stored in iRODS or between two iRODS copies. The command can be in one of the three modes : synchronization of data from the client's local file system to iRODS, from iRODS to the local file system, or from one iRODS path to another iRODS path. The mode is determined by the way the sourceFile|sourceDirectory and targetFile|targetDirectory are specified. Files and directories prepended with 'i:' are iRODS files and collections. Local files and directories are specified without any prefix. For example, the command:

 irsync -r foo1 i:foo2

synchronizes recursively the data from the local directory foo1 to the iRODS collection foo2 and the command:

 irsync -r i:foo1 foo2

synchronizes recursively the data from the iRODS collection foo1 to the local directory foo2.

 irsync -r i:foo1 i:foo2

synchronizes recursively the data from the iRODS collection foo1 to another iRODS collection foo2.

The command compares the checksum values and file sizes of the source and target files to determine whether synchronization is needed. Therefore, the command will run faster if the checksum value for the specific iRODS file, no matter whether it is a source or target, already exists and is registered with iCAT. This can be achieved by using the -k or -K options of the iput command at the time of ingestion, or by using the ichksum command after the data have already been ingested into iRODS. If the -s option is used, only the file size (instead of the the size and checksum value) is used for determining whether synchronization is needed. This mode gives a faster operation but the result is less accurate.

The command accepts multiple sourceFiles|sourceDirectories and a single targetFile|targetDirectory. It pretty much follows the syntax of the UNIX cp command with one exception- irsync of a single source directory to a single target directory. In UNIX, the command:

 cp -r foo1 foo2

has a different meaning depending on whether the target directory foo2 exists. If the target directory exists, the content of source directory foo1 is copied to the target directory foo2/foo1. But if the target directory does not exist, the content is copied to the target directory foo2.

With the irsync command,

 irsync -r foo1 i:foo2

always means the synchronization of the local directory foo1 to collection foo2, no matter whether foo2 exists.

-K verify checksum - calculate and verify the checksum on the data -N numThreads - the number of threads to use for the transfer. A value of 0 means no threading. By default (-N option not used) the server decides the number of threads to use. -R resource - specifies the target resource. This can also be specified in your environment or via a rule set up by the administrator. -r recursive - store the whole subdirectory -v verbose -V Very verbose -h this help -l lists all the source files that needs to be synchronized (including their filesize in bytes) with respect to the target without actually doing the synchronization. --link - ignore symlink. Valid only for rsync from local host to iRODS. -a synchronize to all replicas if the target is an iRODS dataobject/collection. -s use the size instead of the checksum value for determining synchronization. --age age_in_minutes - The maximum age of the source copy in minutes for sync. i.e., age larger than age_in_minutes will not be synced.

Also see 'irepl' for the replication and synchronization of physical copies (replica).

irule

Usage: irule [--available]
Usage: irule [--test] [-v] [-r instanceName] rule inputParam outParamDesc
Usage: irule [--test] [-v] [-l] [-r instanceName] -F inputFile [prompt | arg_1 arg_2 ...]

Submit a user defined rule to be executed by an iRODS server.

The first form above requires 3 inputs: 1) rule - This is the rule to be executed. 2) inputParam - The input parameters. The input values for the rule is specified here. If there is no input, a string containing "null" must be specified. 3) outParamDesc - Description for the set of output parameters to be returned. If there is no output, a string containing "null" must be specified.

The second form above reads the rule and arguments from the file: inputFile - Arguments following the inputFile are interpreted as input arguments for the rule. - These arguments are interpreted in two ways: 1) The arguments require the "label=value" format. - Only named pairs are replaced. Any remaining arguments get their values from the inputFile. All labels start with *. 2) All arguments can be specified as inputs without any labels - The keyword "default" can be given to use the inputFile value. - Use \ as the first letter in an argument as an escape.

The inputFile should contain 3 lines of non-comments: 1) The first line specifies the rule. 2) The second line specifies the input arguments as label=value pairs separated by % - If % is needed in an input value, use %%. - An input value can begin with $. In such a case the user will be prompted. A default value can be listed after the $, as in *A=$40. If prompted, the default value will be used if the user presses return without giving a replacement. - The input line can just be the word null. 3) The third line contains output parameters as labels separated by %. - The built-in variable ruleExecOut stores output from the rule generated by microservices. - The output line can just be the word null.

'arg_1' is of the form arg=value. For example, using A=$ as one of the arguments in line 2 of the inputFile, irule will prompt for A or the user can enter it on the command line: irule -F filename A=23 (integer parameters can be unquoted) or irule -F filename "A='/path/of/interest'" B=24 irule -F filename "A=\"/path/of/interest\"" B=24 (string parameters must be quoted) (your shell may require escaping and/or single quotes)

Example rules are given in: clients/icommands/test/rules/

In either form, the 'rule' that is processed is either a rule name or a rule definition (which may be a complete rule or a subset).

To view the output parameters (outParamDesc), use the -v option.

Options are: --test,-t - enable test mode so that the microservices are not executed, instead a loopback is performed --string,-s - enable string mode, in string mode all command line input arguments do not need to be quoted and are automatically converted to strings string mode does not affect input parameter values in rule files --file,-F - read the named inputFile if the inputFile begins with the prefix "i:" then the file is fetched from an iRODS server --list,-l - list file if -F option is used --verbose,-v - verbose --available,-a - list all available rule engine instances --rule-engine-plugin-instance,-r - run rule on the specified rule engine instance --help,-h - this help

iscan

Usage: iscan [-rhd] srcPhysicalFile|srcPhysicalDirectory|srcDataObj|srcCollection

If the input is a local data file or a local directory, iscan checks if the content is registered in iRODS.

Full path must be used for local files and directories.

If the input is an iRODS file or an iRODS collection, iscan checks if the physical files corresponding to the iRODS object exists on the data servers. Scanning data objects and collections may only be performed by a rodsadmin.

If the operation is successful, nothing will be output and 0 will be returned.

Options are: -r recursive - scan local subdirectories or subcollections -h this help -d scan data objects in iRODS (default is scan local objects)

isysmeta

Usage: isysmeta [-lvVh] [command]
 Show or modify system metadata.
Commands are:
 mod DataObjectName Time (modify expire time)
 mod DataObjectName datatype Type (modify data-type)
 mod DataObjectName comment [replNum] Comment (modify the comment of the replica replNum or 0 by default)
 ls [-lvV] Name (list dataObject, -l -v for long form)
 ldt (list data types (those available))

Time can be full or partial date/time: '2009-12-01' or '2009-12-11.12:03' etc, or a delta time '+1h' (one hour from now), etc.

Examples: isysmeta mod foo +1h (set the expire time for file 'foo' to an hour from now) isysmeta mod /tempZone/home/rods/foo 2009-12-01 isysmeta mod /tempZone/home/rods/foo datatype 'tar file' isysmeta mod /tempZone/home/rods/foo comment 1 'my comment' isysmeta ls foo isysmeta -l ls foo isysmeta ls -l foo isysmeta ldt

itrim

Usage: itrim [-hMrvV] [--age age_in_minutes] [--dryrun] [-n replNum]|[-S srcResource] [-N numCopies] dataObj|collection ... 

Reduce the number of replicas of a dataObject in iRODS by deleting some replicas. Nothing will be done if this is less than or equal to numCopies. The -n and the -S options are used to specified which copies to delete. If neither of these options are used, the replicas will be trimmed until there are numCopies left. The old copies will be trimmed first, then the 'cache' class copies.

Options are: -M admin - admin user uses this option to trim other users files -n replNum - the replica number of the replica to be deleted -N numCopies - minimum number of most current copies to keep. The default value is 2. -r recursive - trim the whole subtree -S srcResource - specifies the resource of the replica to be deleted. If specified, only copies stored in this resource will be candidate for the deletion. -v verbose -V Very verbose --age age_in_minutes - The minimum age of the copy in minutes for trimming. i.e., a copy will not be trimmed if its age is less. --dryrun - Do a dry run. No copy will actually be trimmed. -h this help

iuserinfo

Usage: iuserinfo [-vVh] [user]

Show information about your iRODS user account or the entered user

ixmsg

DEPRECATED
Usage: ixmsg s [-t ticketNum] [-n startingMessageNumber] [-r numOfReceivers] [-H header] [-M message] 
Usage: ixmsg r [-n NumberOfMessages] [-t ticketNum] [-s startingSequenceNumber] [-c conditionString]
Usage: ixmsg t 
Usage: ixmsg d -t ticketNum 
Usage: ixmsg c -t ticketNum 
Usage: ixmsg c -t ticketNum -s sequenceNum 
    s: send messages. If no ticketNum is given, 1 is used 
    r: receive messages. If no ticketNum is given, 1 is used 
    t: create new message stream and get a new ticketNum 
    d: drop message Stream 
    c: clear message Stream 
    e: erase a message 

izonereport

Usage: izonereport
izonereport queries the entire iRODS Zone for configuration information.
This configuration information will be generated in the form of a JSON
document which will validate using schemas found at https://schemas.irods.org.

Configuration files that are included in the zone report are base64 encoded. They can be decoded from the command line by piping into 'base64 --decode'.

Only rodsadmin accounts can run izonereport.

-h this help