iCommands - Administrator

iadmin

Usage: iadmin [-hvV] [command]
A blank execute line invokes the interactive mode, where it
prompts and executes commands until 'quit' or 'q' is entered.
Single or double quotes can be used to enter items with blanks.
Commands are:
 lu [name[#Zone]] (list user info; details if name entered)
 lua [name[#Zone]] (list user authentication (GSI/Kerberos Names, if any))
 luan Name (list users associated with auth name (GSI/Kerberos)
 lt [name] [subname] (list token info)
 lr [name] (list resource info)
 ls [name] (list directory: subdirs and files)
 lz [name] (list zone info)
 lg [name] (list group info (user member list))
 lgd name  (list group details)
 lf DataId (list file details; DataId is the number (from ls))
 mkuser Name[#Zone] Type (make user)
 moduser Name[#Zone] [ type | zone | comment | info | password ] newValue
 aua Name[#Zone] Auth-Name (add user authentication-name (GSI/Kerberos)
 rua Name[#Zone] Auth-Name (remove user authentication name (GSI/Kerberos)
 rpp Name  (remove PAM-derived Password for user Name)
 rmuser Name[#Zone] (remove user, where userName: name[@department][#zone])
 rmdir Name (remove directory) 
 mkresc Name Type [Host:Path] [ContextString] (make Resource)
 modresc Name [name, type, host, path, status, comment, info, freespace, rebalance] Value (mod Resc)
 modrescdatapaths Name oldpath newpath [user] (update data-object paths,
      sometimes needed after modresc path)
 rmresc Name (remove resource)
 addchildtoresc Parent Child [ContextString]
 rmchildfromresc Parent Child
 mkzone Name Type(remote) [Connection-info] [Comment] (make zone)
 modzone Name [ name | conn | comment ] newValue  (modify zone)
 modzonecollacl null|read userOrGroup /remotezone (set strict-mode root ACLs)
 rmzone Name (remove zone)
 mkgroup Name (make group)
 rmgroup Name (remove group)
 atg groupName userName[#Zone] (add to group - add a user to a group)
 rfg groupName userName[#Zone] (remove from group - remove a user from a group)
 at tokenNamespace Name [Value1] [Value2] [Value3] (add token) 
 rt tokenNamespace Name [Value1] (remove token) 
 spass Password Key (print a scrambled form of a password for DB)
 dspass Password Key (descramble a password and print it)
 ctime Time (convert an iRODS time (integer) to local time; & other forms)
 suq User ResourceName-or-'total' Value (set user quota)
 sgq Group ResourceName-or-'total' Value (set group quota)
 lq [Name] List Quotas
 cu (calulate usage (for quotas))
 rum (remove unused metadata (user-defined AVUs)
 asq 'SQL query' [Alias] (add specific query)
 rsq 'SQL query' or Alias (remove specific query)
 help (or h) [command] (this help, or more details on a command)
Also see 'irmtrash -M -u user' for the admin mode of removing trash and
similar admin modes in irepl, iphymv, and itrim.
The admin can also alias as any user via the 'clientUserName' environment
variable.

lu

lu [name] (list user info; details if name entered)
list user information.
Just 'lu' will briefly list currently defined users.
If you include a user name, more detailed information is provided.
Usernames can include the zone preceded by #, for example rods#tempZone.
Users are listed in the userName#ZoneName form.
Also see the 'luz', 'lz', and 'iuserinfo' commands.

lua

lua [name[#Zone]] (list user authentication (GSI/Kerberos Names), if any)
list user authentication-names for one or all users
Just 'lua' will list all the GSI/Kerberos names currently defined
for all users along with the associated iRODS user names.
If you include a user name, then the auth-names for that user are listed.
Usernames can include the zone preceded by #, for example rods#tempZone.
Also see the 'luan', 'aua', 'rua', and 'iuserinfo' commands.

luan

luan Name (list users associated with auth name (GSI/Kerberos)
list the user(s) associated with a give Authentication-Name
For example: luan '/C=US/O=INC/OU=DICE/CN=Wayne Schroeder/UID=schroeder' will list the iRODS user(s) with the GSI DN, if any.

lt

lt [name] [subname]
list token information.
Just 'lt' lists the types of tokens that are defined
If you include a tokenname, it will list the values that are
allowed for the token type.  For details, lt name subname, 
for example: lt data_type email
The sql wildcard character % can be used on the subname,
for example: lt data_type %DLL

lr

lr [name] (list resource info)
Just 'lr' briefly lists the defined resources.
If you include a resource name, it will list more detailed information.

ls

ls [name] (list directory: subdirs and files)
This was a test function used before we had the ils command.
It lists collections and data-objects in a somewhat different
way than ils.  This is seldom of value but has been left in for now.

lz

 lz [name] (list zone info)
Just 'lz' briefly lists the defined zone(s).
If you include a zone name, it will list more detailed information.

lg

 lg [name] (list group info (user member list))
Just 'lg' briefly lists the defined groups.
If you include a group name, it will list users who are
members of that group.  Users are listed in the user#zone format.
In addition to 'rodsadmin', any user can use this sub-command; this is
of most value to 'groupadmin' users who can also 'atg' and 'rfg'

lgd

 lgd name (list group details)
Lists some details about the user group.

lf

 lf DataId (list file details; DataId is the number (from ls))
This was a test function used before we had the ils command.
It lists data-objects in a somewhat different
way than ils.  This is seldom of value but has been left in for now.

mkuser

 mkuser Name[#Zone] Type (make user)
Create a new iRODS user in the ICAT database

Name is the user name to create Type is the user type (see 'lt user_type' for a list) Zone is the user's zone (for remote-zone users)

Tip: Use moduser to set a password or other attributes, use 'aua' to add a user auth name (GSI DN or Kerberos Principal name)

moduser

 moduser Name[#Zone] [ type | zone | comment | info | password ] newValue
Modifies a field of an existing user definition.
For password authentication, use moduser to set the password.
(The password is transferred in a scrambled form to be more secure.)
Long forms of the field names may also be used:
user_name, user_type_name, zone_name, user_info, or 
r_comment
These are the names listed by 'lu' (and are the database table column names).
Modifying the user's name (user_name) is not allowed; instead remove the user
and create a new one.  rmuser/mkuser will remove (if empty) and create the
needed collections too.
For GSI or Kerberos authentication, use 'aua' to add one or more
user auth names (GSI Distinquished Name (DN) or Kerberos principal name).

aua

 aua Name[#Zone] Auth-Name (add user authentication-name (GSI/Kerberos)
Add a user authentication name, a GSI  Distinquished Name (DN) or
Kerberos Principal name, to an iRODS user.  Multiple DNs and/or Principal
names can be associated with each user.
This is used with Kerberos and/or GSI authentication, if enabled.
For example:
  aua rods '/C=US/O=INC/OU=DICE/CN=Wayne Schroeder/UID=schroeder'
Also see 'rua', 'lua', and 'luan'.

rua

 rua Name[#Zone] Auth-Name (remove user authentication-name (GSI/Kerberos)
Remove a user authentication name, a GSI Distinquished Name (DN) or
Kerberos Principal name, from being associated with an iRODS user.
These are used with Kerberos and/or GSI authentication, if enabled.
Also see 'aua', 'lua', and 'luan'.

rpp

 rpp Name (remove PAM-derived Password for user Name)
Remove iRODS short-term (usually 2 weeks) passwords that are created
when users authenticate via the iRODS PAM authentication method.
For additional security, when using PAM (system passwords), 'iinit' will
create a separate iRODS password that is then used (a subsequent 'iinit'
extend its 'life').  If the user's system password is changed, you
may want to use this rpp command to require the user to re-authenticate.

rmuser

 rmuser Name[#Zone] (remove user, where userName: name[@department][#zone])
 Remove an iRODS user.

rmdir

 rmdir Name (remove directory) 
This is similar to 'irm -f'.

mkresc

 mkresc Name Type [Host:Path] [ContextString] (make Resource)
Create (register) a new coordinating or storage resource.

Name is the name of the new resource. Type is the resource type. Host is the DNS host name. Path is the defaultPath for the vault. ContextString is any contextual information relevant to this resource. (semi-colon separated key=value pairs e.g. "a=b;c=d")

A ContextString can be added to a coordinating resource (where there is no hostname or vault path to be set) by explicitly setting the Host:Path to an empty string ('').

A list of available resource types can be shown with: iadmin lt resc_type

modresc

 modresc Name [name, type, host, path, status, comment, info, freespace, rebalance] Value
         (modify Resource)
Change some attribute of a resource.  For example:
    modresc demoResc comment 'test resource'
The 'host' field is the DNS host name, for example 'offsite.example.org',
this is displayed as 'resc_net', the resource network address.

Setting the resource status to 'down' will cause iRODS to ignore that resource and bypass communications with that server. 'up' or other strings without 'down' in them will restore use of the resource. 'auto' will allow the Resource Monitoring System (if running) to set the resource status to 'auto-up' or 'auto-down'.

The freespace value can be simply specified, or if it starts with + or - the freespace amount will be incremented or decremented by the value.

'rebalance' will trigger the rebalancing operation on a coordinating resource node.

modrescdatapaths

 modrescdatapaths Name oldpath newpath [user] (update data-object paths,
      sometimes needed after modresc path)

Modify the paths for existing iRODS files (data-objects) to match a change of the resource path that had been done via 'iadmin modresc Resc path'. This is only needed if the physical files and directories of existing iRODS files have been moved, via tools outside of iRODS; i.e the physical resource has been moved. If you only changed the path so that new files will be stored under the new path directory, you do not need to run this.

Each data-object has a physical path associated with it. If the old physical paths are no longer valid, you can update them via this. It will change the beginning part of the path (the Vault) from the old path to the new.

This does a pattern replacement on the paths for files in the named resource. The old and new path strings must begin and end with a slash (/) to make it more likely the correct patterns are replaced (should the pattern repeat within a path).

If you include the optional user, only iRODS files owned by that user will be updated.

When the command runs, it will tell you how many data-object rows have been updated.

The 'iadmin modresc Rescname path' command now returns the previous path of the resource which can be used as the oldPath for this modrescdatapaths command. It also refers the user to this command.

To see if you have any files under a given path, use iquest, for example: iquest "select count(DATA_ID) where DATA_PATH like '/iRODS/Vault3/%'" And to restrict it to a certain user add: and USER_NAME = 'name'

rmresc

 rmresc Name (remove resource)
Remove a storage resource.

addchildtoresc

 addchildtoresc Parent Child [ContextString] (add child to resource)
Add a child resource to a parent resource.  This creates an 'edge'
between two nodes in a resource tree.

Parent is the name of the parent resource. Child is the name of the child resource. ContextString is any relevant information that the parent may need in order to manage the child.

rmchildfromresc

 rmchildfromresc Parent Child (remove child from resource)
Remove a child resource from a parent resource.  This removes an 'edge'
between two nodes in a resource tree.

Parent is the name of the parent resource. Child is the name of the child resource.

mkzone

 mkzone Name Type(remote) [Connection-info] [Comment] (make zone)
Create a new zone definition.  Type must be 'remote' as the local zone
must previously exist and there can be only one local zone definition.
Connection-info (hostname:port) and a Comment field are optional.

The connection-info should be the hostname of the ICAT-Enabled-Server (IES) of the zone. If it is a non-IES, remote users trying to connect will get a CAT_INVALID_USER error, even if valid, due to complications in the way the protocol connections operate when the local server tries to connect back to the remote zone to authenticate the user.

Also see modzone, rmzone, and lz.

modzone

 modzone Name [ name | conn | comment ] newValue  (modify zone)
Modify values in a zone definition, either the name, conn (connection-info),
or comment.  Connection-info is the DNS host string:port, for example:
irods.example.org:1247
When modifying the conn information, it should be the hostname of the
ICAT-Enabled-Server (IES); see 'h mkzone' for more.

The name of the local zone can be changed via some special processing and since it also requires some manual changes, iadmin will explain those and prompt for confirmation in this case.

modzonecollacl

 modzonecollacl null|read userOrGroup /remotezone (set strict-mode root ACLs)
Modify a remote zone's local collection for strict-mode access.

This is only needed if you are running with strict access control enabled (see acAclPolicy in core.re) and you want users to be able to see (via 'ils /' or other queries) the existing remote zones in the root ('/') collection.

The problem only occurs at the '/' level because for zones there are both local and remote collections for the zone. As with any query in strict mode, when the user asks for information on a collection, the iCAT-generated SQL adds checks to restrict results to data-objects or sub-collections in that collection to which the user has read or better access. The problem is that collections for the remote zones (/zone) do not have ACLs set, even if ichmod is run try to give it (e.g. read access to public) because ichmod (like ils, iget, iput, etc) communicates to the appropriate zone based on the beginning part of the collection name.

The following iquest command returns the local ACLs (tempZone is the local zone and r3 is a remote zone): iquest -z tempZone "select COLL_ACCESS_TYPE where COLL_NAME = '/r3'" The '-z tempZone' is needed to have it connect locally instead of to the remote r3 zone. Normally there will be one row returned for the owner. With this command, others can be added. Note that 'ils -A /r3' will also check with the remote zone, so use the above iquest command to see the local information.

The command syntax is similar to ichmod: null|read userOrGroup /remoteZone Use null to remove ACLs and read access for another user or group.

For example, to allow all users to see the remote zones via 'ils /': iadmin modzonecollacl read public /r3

To remove it: iadmin modzonecollacl null public /r3

Access below this level is controlled at the remote zone.

rmzone

 rmzone Name (remove zone)
Remove a zone definition.
Only remote zones can be removed.

mkgroup

 mkgroup Name (make group)
Create a user group.
Also see atg, rfg, and rmgroup.

rmgroup

 rmgroup Name (remove group)
Remove a user group.
Also see mkgroup, atg, and rfg.

atg

 atg groupName userName[#userZone] (add to group - add a user to a group)
For remote-zone users, include the userZone.
Also see mkgroup, rfg and rmgroup.
In addition to the 'rodsadmin', users of type 'groupadmin' can atg and rfg
for groups they are members of.  They can see group membership via iuserinfo.

rfg

 rfg groupName userName[#userZone] (remove from group - remove a user from a group)
For remote-zone users, include the userZone.
Also see mkgroup, afg and rmgroup.
In addition to the 'rodsadmin', users of type 'groupadmin' can atg and rfg
for groups they are members of.  They can see group membership via iuserinfo.

at

 at tokenNamespace Name [Value1] [Value2] [Value3] [comment] (add token) 
Add a new token.  The most common use of this is to add
data_type or user_type tokens.  See lt to display currently defined tokens.

rt

 rt tokenNamespace Name [Value] (remove token) 
Remove a token.  The most common use of this is to remove
data_type or user_type tokens.  See lt to display currently defined tokens.

spass

 spass Password Key (print a scrambled form of a password for DB)
Scramble a password, using the input password and key.
This is used during the installation for a little additional security

dspass

 dspass Password Key (descramble a password and print it)
Descramble a password, using the input scrambled password and key

ctime

 ctime Time (convert a iRODSTime value (integer) to local time
Time values (modify times, access times) are stored in the database
as a Unix Time value.  This is the number of seconds since 1970 and
is the same in all time zones (basically, Coordinated Universal Time).
ils and other utilities will convert it before displaying it, but iadmin
displays the actual value in the database.  You can enter the value to
the ctime command to convert it to your local time.  The following two
additional forms can also be used:

ctime now - convert a current time to an iRODS time integer value.

ctime str Timestr - convert a string of the format Timestr (YYYY-MM-DD.hh:mm:ss) to an iRODS integer value time.

suq

 suq User ResourceName-or-'total' Value (set user quota)
Set a quota for a particular user for either a resource or all iRODS
usage (total).  Use 0 for the value to remove quota limit.  Value is
in bytes.  As with other sub-commands, 'user' is of the form
userName[#zone] where the local zone is default.
Also see sgq, lq and cu.

sgq

 sgq Group ResourceName-or-'total' Value (set group quota)
Set a quota for a user-group for either a resource or all iRODS
usage (total).  Use 0 for the value to remove quota limit.  Value is
in bytes.
Also see suq, lq, and cu.

lq

 lq [Name] List Quotas
List the quotas that have been set (if any).
If Name is provided, list only that user or group.
Also see suq, sgq, cu, and the 'iquota' command.

cu

 cu (calulate usage (for quotas))
Calculate (via DBMS SQL) the usage on resources for each user and
determine if users are over quota.
Also see suq, sgq, and lq.

rum

 rum (remove unused metadata (user-defined AVUs)
When users remove user-defined metadata (Attribute-Value-Unit triples
(AVUs)) on objects (collections, data-objects, etc), or remove the
objects themselves, the associations between those objects and the
AVUs are removed but the actual AVUs (rows in another table) are left
in place.  This is because each AVU can be associated with multiple
objects.  But this only needs to be run if the number of unused AVUs has
gotten large and is slowing down the DBMS.  This command runs SQL
to remove those unused AVU rows.  This is a slower command on MySQL
 than on PostgreSQL and Oracle.

asq

 asq 'SQL query' [Alias] (add specific query)
Add a specific query to the list of those allowed.
Care must be taken when defining these to prevent users from accessing
or updating information (in the iCAT tables) that needs to be restricted
(passwords, for example) as the normal general-query access controls are
bypassed via this.  This also requires an understanding of the iCAT schema
(see icatSysTables.sql) to properly link tables in your SQL.
If an Alias is provided, clients can use that instead of the full SQL
string to select the SQL.  Aliases are checked to be sure they are unique
but the same SQL can have multiple aliases.
These can be executed via 'iquest --sql'.
Use 'iquest --sql ls' to see the currently defined list.
If 'iquest --sql ls' fails, see icatSysInserts.sql for the definitions of two
built-in specific queries (r_specific_query) that are needed.
To add a specific query with single quotes(') within, use double
quotes(") around the SQL.
Also see rsq.

rsq

 rsq 'SQL query' or Alias (remove specific query)
Remove a specific query from the list of those allowed.
Use 'iquest --sql ls' to see the currently defined list.
Also see asq.

help

 help (or h) [command] (general help, or more details on a command)
 If you specify a command, a brief description of that command
 will be displayed.