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 [-haMrvV] [-f|K|--verify] [-n replNum|-R resource] [--silent]
           dataObj|collection ... 

Checksum one or more data objects or collections.

The checksum algorithm used by this function is determined by the client and server's configuration, but defaults to SHA256.

There are two modes of operation: - Lookup/Update (default): Computes and updates checksum information. - Verification: Detects and reports issues related to checksum information.

In Lookup/Update mode, the following operations are performed: 1. Compute a new checksum and updates the catalog. 2. Reports if the replicas do NOT share identical checksums.

Lookup/Update mode will process the highest voted replica unless -a is present. If -f is not present and the replica already has a checksum, that checksum will be printed to the terminal. If a specific replica is targeted, step 2 is not performed.

Lookup/Update mode supports operations on replicas marked as good or stale.

In Verification mode, the following operations are performed: 1. Reports replicas with mismatched size information (physical vs catalog). 2. Reports replicas with missing checksums. (Halts if missing checksums are found) 3. Reports replicas with mismatched checksums (computed vs catalog). 4. Reports if the replicas do NOT share identical checksums.

Verification mode operates on all replicas unless a specific replica is targeted. If a specific replica is targeted, step 4 is not performed.

Verification mode supports operations on replicas marked as good.

Operations that target multiple replicas will only affect replicas that are marked as good. This means intermediate, locked, and stale replicas will be ignored.

Operations that target a specific replica are allowed to operate on stale replicas unless stated otherwise.

Options: -f Computes and stores a checksum for one or more replicas. This option always results in a catalog update. -a Apply operation to all good replicas. -K, --verify Verifies the state of the checksums for one or more replicas. --no-compute When used with -K, no checksums are computed. This option causes step 3 of -K to be skipped. This option is provided as a way to avoid long running checksum computations when a size check is adequate. -M Run the command as an administrator. -n REPLICA_NUMBER The replica number of the replica to checksum or verify. -R RESOURCE_NAME The leaf resource that contains the replica to checksum or verify. -r Checksum data objects recursively. --silent Suppresses output of checksums and output related to -r. -v Verbose. -V Very verbose. -h Prints this message.

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
DEPRECATED - Remotely Execute a command installed in the msiExecCmd_bin
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 physical 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 [-hKrR] srcPhysicalFile|srcPhysicalDirectory ... 

Check if a local file or local directory content is consistent in size (and optionally its checksum) with its registered size (and optionally its checksum) in iRODS.

Allows detection of managed data that has been corrupted or modified outside the iRODS framework on the local filesystem.

srcPhysicalFile or srcPhysicalDirectory must be a fully qualified path.

To check files registered to the leaf of a resource hierarchy, use the -R option with a full resource hierarchy (semicolon delimited): ifsck -R 'pt1;r1;s1' /localdir/full/path/to/file.txt

Options are: -K verify the checksum of the local file against the one registered in iRODS. Ignored if the checksum has not already been calculated and stored. -r recursive - scan srcPhysicalDirectory and its local subdirectories -R rescHier - if provided, will match replicas on this leaf resource, rather than using the hostname of the root of each file's resolved hierarchy. -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 - Specify a resource from which to get the data. If no such resource exists or a replica does not exist on the specified resource, an error will be returned. -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] [password]
 -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

Note that the password will be in clear-text if provided via the command line. Providing the password this way will bypass the password prompt.

ilocate

Usage: ilocate [options] searchPattern [searchPattern] [searchPattern] ...

Search through the local Zone for data-object(s) with fullpaths with components which match the provided search pattern. Use '%' as a wildcard (emulates the sql 'like' operand). If you need to express % as a literal, you must encapsulate the search pattern with quotes.

Options are: -0 Separate output via NULL characters instead of newlines (like find -print0) -t Also show objects in trash -i Use case-insensitive search

ils

Usage: ils [-ArlLv] dataObj|collection ... 
Usage: ils --bundle [-r] dataObj|collection ... 
Display data objects and collections stored in iRODS.

The following is typical output for ils with no arguments: $ ils /tempZone/public: big foo The only information displayed are the names of data objects in the current working collection.

The long format (given by -l) will display some more information: $ ils -l /tempZone/public: rods 0 demoResc 41943040 2021-04-29.17:57 & big rods 2 comp;arch 40236581 2021-04-19.03:00 X big alice 2 repl1;child1 283 2021-04-29.17:54 ? foo alice 3 repl1;child2 283 2021-04-29.17:56 ? foo alice 4 repl1;child3 283 2021-04-29.17:57 ? foo This displays replica information and system metadata for the replicas of the data objects in the current working collection. This information includes the owner of the data object and the replica's number, resource hierarchy, size, last modified time, and status.

The very long format (given by -L) will display even more information:

$ ils -L
/tempZone/public:
  rods              0 demoResc              41943040 2021-04-29.17:57 & big
    sha2:gKNyEYjkAhiwiyZ3a8U72ugeR4T/9x1xRQoZcxnLoRM=    generic    /var/lib/irods/Vault/public/big
  rods              2 comp;arch             40236581 2021-04-19.03:00 X big
    sha2:KNyEYjkhiwyZ3a8U72ugeR4T/9x1xRQoZcxnLoRMigg=    generic    /var/lib/irods/archVault/public/big
  alice             2 repl1;child1               283 2021-04-29.17:54 ? foo
        generic    /var/lib/irods/child1vault/public/foo
  alice             3 repl1;child2               283 2021-04-29.17:56 ? foo
        generic    /var/lib/irods/child2vault/public/foo
  alice             4 repl1;child3               283 2021-04-29.17:57 ? foo
        generic    /var/lib/irods/child3vault/public/foo

This displays even more replica information and system metadata such as each replica's checksum, data type, and physical location in the storage resource.

The different replica statuses are represented by the following characters which can be seen between the last modified time and the data object name. 0. X: stale - The replica is no longer known to be good. Usually indicates that a more recently written-to replica exists. This does not necessarily mean that the data is incorrect but merely that it may not reflect the "truth" of this data object. 1. &: good - The replica is good. Usually the latest replica to be written. When a replica is good, all bytes and system metadata (size and checksum, if present) are understood to have been recorded correctly. 2. ?: intermediate - The replica is actively being written to. The state of the replica cannot be determined because the client writing to it still has the replica opened. Replicas which are intermediate cannot be opened for read or write, nor can they be unlinked or renamed. 3. ?: write-locked - One of this replica's sibling replicas is actively being written to but is itself at rest. Replicas which are write-locked cannot be opened for read or write nor can they be unlinked or renamed. These replica statuses correspond with the data_is_dirty column in r_data_main.

Options are: -A ACL (access control list) and inheritance format -d List collections themselves, not their contents -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.

The source replica must be specified by its full hierarchy and it must exist at the provided resource hierarchy location. The resource hierarchy for the destination replica must also be specified in full, but may or may not exist at the specified location. Specifying a leaf resource is acceptable in lieu of a full resource hierarchy as it can be reverse-resolved to the root. See these example usages: iphymv -S demoResc -R 'pt1;r1;s1' /tempZone/home/alice/test.txt iphymv -S demoResc -R 's1' /tempZone/home/alice/test.txt

If the leaf resource targeted for a phymv refers to the archive of a compound resource hierarchy, DIRECT_ARCHIVE_ACCESS will be returned because direct access to an archive resource is not allowed.

iphymv cannot overwrite a replica which is not marked stale. iphymv cannot move a replica which is not at rest. iphymv cannot move a replica which is part of an already locked data object.

iphymv returns a few unique error codes based on the type of error which occurred within the system: 0: Success 1: There was a problem with the client configuration or parsing the user input 2: There was a problem connecting to the iRODS server (rcConnect failed) 3: Historic exit code returned for all errors other than those listed above and below 4: There was a mismatch between the source and destination replica's checksums 5: There was a problem with the supplied source logical path 6: The resource to host the destination replica has run out of space (ENOSPC) 7: The source or destination replica failed to be opened for any other reason

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.

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. -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 through 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_string] 
  or:  iquest --sql  [format_string] [arguments]
  or:  iquest attrs

Options: format_string C-style format string restricted to character strings. query_string selection query string. See the section 'Selection query syntax'.

-z zone_name the zone to query (default or invalid uses the local zone) --no-page do not prompt to continue after printing a large number of results (500) --sql execute 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). -h display this help and exit

If 'no-distinct' appears before the query_string, the normal distinct option on the SQL will be bypassed (this is useful in rare cases).

If 'uppercase' (or 'upper') appears before the query_string, the database value in the 'WHERE' condition will be made upper case so one can do case-insensitive tests (using upper-case literals).

Selection query syntax: Used for 'query_string' argument

SELECT [, ] [WHERE [AND ]] attribute name of an attribute from 'iquest attrs' condition conditional statement. See the section 'Conditional statement syntax'.

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

Conditional statement syntax: Used for 'WHERE' conditional statements in selection queries

attribute name of an attribute from 'iquest attrs'. rel-op relational operator (e.g. =, <>, >, <, LIKE, NOT LIKE, BETWEEN, etc.) value either a constant or a wild-carded expression. Use % and _ as wild-cards, and use \ to escape them.

Examples: iquest "SELECT DATA_NAME, DATA_CHECKSUM WHERE DATA_RESC_NAME LIKE 'demo%'" recorded checksum for each object in a demo resource iquest "For %-12.12s size is %s" "SELECT DATA_NAME, DATA_SIZE WHERE COLL_NAME = '/tempZone/home/rods'" format object names as a left-justified 12-character column iquest "SELECT COLL_NAME WHERE COLL_NAME LIKE '/tempZone/home/%'" home- and sub-colections 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'" user access for each object in the rods home collection 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'" alternate formatting for user access iquest no-distinct "SELECT META_DATA_ATTR_NAME" allow multiple instances of the same result iquest uppercase "select COLL_NAME, DATA_NAME WHERE DATA_NAME LIKE 'F1'" use uppercase values during WHERE for case-insensitive search iquest "SELECT RESC_NAME, RESC_LOC, RESC_VAULT_PATH, DATA_PATH WHERE DATA_NAME = 't2' AND COLL_NAME = '/tempZone/home/rods'" vault storage for a single object 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" storage used for each user on each resource iquest "SELECT SUM(DATA_SIZE) WHERE COLL_NAME = '/tempZone/home/rods'" aggregate size of objects in the immediate rods home collection iquest "SELECT SUM(DATA_SIZE) WHERE COLL_NAME LIKE '/tempZone/home/rods%'" aggregate size of rods home- and sub-collections iquest "SELECT SUM(DATA_SIZE), RESC_NAME WHERE COLL_NAME LIKE '/tempZone/home/rods%'" aggregate size of rods home- and sub-collections for each resource iquest "SELECT ORDER_DESC(DATA_ID) WHERE COLL_NAME LIKE '/tempZone/home/rods%'" ordered list of object IDs in rods home- and sub-collections iquest "SELECT COUNT(DATA_ID) WHERE COLL_NAME LIKE '/tempZone/home/rods%'" count objects in rods home- and sub-collections iquest "SELECT RESC_NAME WHERE RESC_CLASS_NAME IN ('bundle','archive')" bundle and archive resources iquest "SELECT DATA_NAME, DATA_SIZE WHERE DATA_SIZE BETWEEN '100000' '100200'" objects between 100kB and 100.2kB iquest "%s/%s %s" "SELECT COLL_NAME, DATA_NAME, DATA_CREATE_TIME WHERE COLL_NAME LIKE '/tempZone/home/rods%' AND DATA_CREATE_TIME LIKE '01508165%'" objects in rods home- and sub-collections created 2017-10-16 between UTC 14:43 and 15:00 iquest "%s/%s" "SELECT COLL_NAME, DATA_NAME WHERE DATA_RESC_NAME = 'replResc' and DATA_REPL_STATUS = '0'" objects replicated successfully to replResc

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.

The -R option cannot be used to target a destination resource that is a child resource within a resource hierarchy. Doing so will result in a DIRECT_CHILD_ACCESS error. Child resources are managed and their replication policy is handled by their hierarchy.

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.

Registered non-vault replicas are never deleted from the filesystem. They are unregistered and left on disk as-is.

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.

Note that -n has been deprecated. Please use itrim instead.

Note that -U has been deprecated. Please use iunreg instead.

Options are: -f force - Immediate removal of data-objects without putting them in trash . -n replNum - [Deprecated] 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 [Deprecated] 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

irmdir

Removes the directory (collection) specified by each directory,
   provided that it is empty
Usage: irmdir [-fpUvVh] [directory] ...
 -f  Force immediate removal of collections without putting
     them in the trash.
 -U  Unregister collections instead of removing them.
 -p  Each directory (collection) argument is treated as a
     pathname of which all components will be removed, as
     long as they are empty, starting with the lastmost.
 -v  verbose
 -V  very verbose
 -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 can be found at: https://github.com/irods/irods_client_icommands/tree/master/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)

istream

Usage: istream read [-R RESC_NAME] [-o INTEGER] [-c INTEGER] LOGICAL_PATH
Usage: istream read [-n REPLICA_NUMBER] [-o INTEGER] [-c INTEGER] LOGICAL_PATH
Usage: istream write [-R RESC_NAME] [-k] [-o INTEGER] [-c INTEGER] [--no-trunc] [-a] LOGICAL_PATH
Usage: istream write [-n REPLICA_NUMBER] [-k] [-o INTEGER] [-c INTEGER] [--no-trunc] [-a] LOGICAL_PATH

Streams bytes to/from iRODS via stdin/stdout. Reads bytes from the target data object and prints them to stdout. Writes bytes from stdin to the target data object.

Writing to a non-existent data object will create it by default. Writing to an existing data object always truncates it. Truncation can be disabled by passing --no-trunc. However, using --no-trunc disables creation of data objects.

If the client-side of the connection is interrupted before the data object is closed, then the catalog will not be updated and the data object will have a replica status of intermediate or stale. Information such as data object size and checksum will not be available.

If the target data object does not reside on the connected server, istream will not attempt to redirect to the server hosting the replica. Traffic will always flow through the connected server.

Options: -R, --resource The root resource to read from or write to. Cannot be used with --replica. -n, --replica The replica number of the replica to read from or write to. Replica numbers cannot be used to create new data objects. Cannot be used with --resource. -o, --offset The number of bytes to skip within the data object before reading/writing. Value must be positive. Defaults to zero. -c, --count The number of bytes to read/write. Value must be positive. Defaults to all bytes. -a, --append Appends bytes read from stdin to the data object. Implies --no-trunc. --no-trunc Does not truncate the data object. Disables creation of data objects. Ignored by write operations when --append is set. -k, --checksum Compute checksum. -h, --help Prints this message

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

itouch

itouch - Change logical path timestamp

Usage: itouch [OPTION]... LOGICAL_PATH

Update the modification time of a logical path to the current time.

A LOGICAL_PATH argument that does not exist will be created as an empty data object, unless -c is supplied.

If LOGICAL_PATH does not exist and no options are specified, the server will create a data object at the resource defined by msiSetDefaultResc().

If multiple replicas exist and a target replica is not specified via a replica number or leaf resource, the latest good replica will be updated.

Mandatory arguments to long options are mandatory for short options too.

Options: -c, --no-create Do not create a data object. -n, --replica The replica number of the replica to update. This option applies to data objects only. Cannot be used with -R. -R, --resource The leaf resource that contians the replica to update. This option applies to data objects only. If the data object does not exist and this option is used, the replica will be created on the resource specified. Cannot be used with -n. -r, --reference=LOGICAL_PATH Use the modification time of LOGICAL_PATH instead of the current time. Cannot be used with -s. -s, --seconds-since-epoch=SECONDS Use SECONDS instead of the current time. Cannot be used with -r. -h, --help Display this help message and exit. -v, --version Display version information and exit.

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.

Registered non-vault replicas are never deleted from the filesystem. They are unregistered and left on disk as-is.

Note that if both are used at the same time, the server will return an error if -n violates the requirements of -N.

Note that -S and -n are incompatible.

Note that -N has been deprecated.

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 - [Deprecated] 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

iunreg

Usage: iunreg [-hMrvV] dataObj|collection ... 

Unregister all replicas of one or more data-object or collection from iRODS space. All replicas will remain on disk but the entry in the catalog will be removed. This usage replaces the previously supported -U option for irm.

Usage: iunreg [-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 unregistering 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 replicas to unregister.

Note that if both are used at the same time, the server will return an error if -n violates the requirements of -N.

Note that -S and -n are incompatible.

Options are: -M admin - admin user uses this option to unregister other users files -n replNum - the replica number of the replica to be unregistered -N numCopies - minimum number of most current replicas to keep. The default value is 2. -r recursive - unregister all data objects in the whole subtree -S srcResource - specifies the resource of the replica to be unregistered. If specified, only replicas stored in this resource will be candidate for the unregistration. -v verbose -V Very verbose --age age_in_minutes - The minimum age of the replica in minutes for unregistering. i.e., a replica will not be unregistered if its age is less. --dryrun - Do a dry run. No replica will actually be unregistered. NOTE: Option only valid when targeting specific replicas. -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