iCommands - Administrator
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 [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 [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 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 [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 [name] (list resource info) Just 'lr' briefly lists the defined resources. If you include a resource name, it will list more detailed information.
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 [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 [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 name (list group details) Lists some details about the user group.
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 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 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 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 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 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 Name[#Zone] (remove user, where userName: name[@department][#zone]) Remove an iRODS user.
rmdir Name (remove directory) This is similar to 'irm -f'.
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 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 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 Name (remove resource) Remove a storage resource.
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 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 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 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 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 Name (remove zone) Remove a zone definition. Only remote zones can be removed.
mkgroup Name (make group) Create a user group. Also see atg, rfg, and rmgroup.
rmgroup Name (remove group) Remove a user group. Also see mkgroup, atg, and rfg.
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 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 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 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 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 Password Key (descramble a password and print it) Descramble a password, using the input scrambled password and key
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 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 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 [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 (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 (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 '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 '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 (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.