ICommands

Les commandes iRODS (iCommands) sont toutes auto-documentées (option -h). Par exemple:

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

La page web des iCommands se trouve ici: https://docs.irods.org/master/icommands/user/

On présente cependant un résumé de ces commandes et quelques informations supplémentaires dans ce qui suit.

Manipulation de la session utilisateur

iinit

iinit [-ehvVl] [--ttl TimeToLive]

Crée un fichier d'identification contenant une version cryptée du mot de passe iRODS de l'utilisateur. Cela permet de créer une "session" dans laquelle l'utilisateur n'a plus besoin de donner son mot de passe à chaque commande iRODS.

iexit

Usage: iexit [-vh] [full]

Réinitialise le répertoire courant iRODS. Si l'option full est donnée, le mot de passe enregistré avec iinit est aussi effacé.

Commandes de type Unix

ipasswd

Usage: ipasswd [-hvVl]

Permet le changement du mot de passe iRODS. L'ancien mot de passe iRODS est préalablement demandé pour vérification.

ils

Usage : ils [-ArlLv] dataObj|collection ... 
Usage : ils --bundle [-r] dataObj|collection ...

Liste le contenu d'un répertoire logique (une "collection")

On notera les très utiles options "-l" et "-L" qui donnent un listing détaillé (avec la liste des répliques des fichiers pour "-L").

imkdir

icd

ipwd

imv

icp

Attention cette commande ne sert que pour copier des données déjà présentes sur iRODS d'un site vers un autre ou d'un dossier vers un autre.
Pour copier des données vers iRODS depuis un serveur distant utiliser la commande iput ou irsync

irm

Similaire à la commande rm.

  • NOTE: Lors d'un irm, si l'erreur CAT_NOT_A_DATAOBJ_AND_NOT_A_COLLECTION ci-dessous apparaît, il faut alors vider la corbeille à l'aide de irmtrash.
    En effet, irods ne peut supprimer (placer dans la corbeille) l'objet puisqu'il existe déjà dans la corbeille.
    ERROR: rmUtil: rm error for /MCIA/home/user/file, status = -836000 status = -836000 CAT_NOT_A_DATAOBJ_AND_NOT_A_COLLECTION

ichmod

Cette commande permet de gérer les droits d'accès aux fichiers (ACL pour Access Control List).

Usage: ichmod [-rhvVM] null|read|write|own userOrGroup dataObj|Collection ...
 or    ichmod [-rhvVM] inherit Collection ...
 or    ichmod [-rhvVM] noinherit Collection ...

Ces ACLs sont différentes des ACLs Unix. On peut notamment en associer autant qu'on veut à un fichier ou une collection.

Les ACLs read et write sont évidentes. l'ACL null n'en est pas une à proprement parler.

L'ACL own permet à son bénéficiaire de gérer les ACLs de ce fichier/collection. Le créateur d'un fichier ou d'une collection peut toujours se réaffecter une ACL own.

Note: own implique write, qui implique à son tour read.

Attention: Les droits d'accès en lecture fonctionnent d'une manière particulière dans MCIA-iRODS. En effet, un fichier ou collection sur laquelle on n'a pas l'ACL read est invisible même si on peut lire dans sa collection parente. Après une mauvaise manipulation, on peut imaginer avoir perdu des données alors qu'il n'en est rien. Pour réparer cette situation:

ichmod -r own .

ichksum

Usage : ichksum [-harvV] [-K|f] [-n replNum] [-R resource] [--silent] dataObj|collection ... 

Calcule et/ou vérifie la somme de contrôle des fichiers stockés.

  • avec l'option -K: vérification de somme de contrôle entre ce qui est inscrit dans le catalogue et la réalité du fichier stocké sur disque (dans la ressource iRODS)
  • avec l'option -f: recalcul de la somme de contrôle depuis le disque et enregistrement de la nouvelle valeur dans le catalogue
  • sans option -f ou -K: impression de la valeur enregistrée dans le catalogue sans vérification

Dans le cas de l'option de vérification -K, il faudra soit spécifier un numéro de réplique à vérifier (-n X) soit demander la vérification de toutes celles-ci (-a).

irsync

Envoyer le contenu du repertoire local "moi" sur irods:
# L'indication i: indique comme source ou destination "irods".
# -r recursif
# -v verbeux
# -K Mets à jour les checksums
# -a Mets à jour les répliques (copies)

irsync -K -a -v -r /home/moi i:/MCIA/home/moi

Ne pas hésiter a enregistrer la sortie de irsync pour pouvoir facilement contrôler le résultat de la copie.

irsync -K -a -v -r /home/moi i:/MCIA/home/moi 2>&1 | tee irsync_output.log

Par défaut, irsync contrôle la date et le checksum du fichier.
La synchronistation n'est pas "destructrice" sur la destination (si le fichier n'existe pas sur la source, il est laissé intacte sur la destination)

ATTENTION!: Dans le contexte MCIA-iRODS, lorsqu'on effectue une synchronisation vers iRODS, il est TRES VIVEMENT conseillé d'utiliser les options "-K -a" afin de garder la cohérence des répliques des fichiers déjà présents modifiés.

Quelques erreurs courantes:

  • Erreur "-4013 status = -4013 SYS_HEADER_READ_LEN_ERR, Permission denied"
    A noter que l'erreur se transforme ensuite en "-5032 SYS_HEADER_WRITE_LEN_ERR, Broken pipe".
    C'est une erreur sur les permissions d'accès au fichier (lecture du fichier impossible).
    Il faut simplement avoir les bonnes permissions d'accès.
  • Erreur "stat error for /..., errno = 2" ou "rsyncDirToCollUtil -317000 USER_INPUT_PATH_ERR"
    L'erreur est dûe à un problème d'accès à un fichier. Souvent un lien symbolique cassé.
    Le lien/fichier est pointé par la première erreur 'stat error'.
    On peut utiliser l'option --link pour ignorer les liens symboliques (pour un irsync local vers irods) ou simplement corriger le lien (ln -s ...).
    Exemple (le fichier k20 est un lien symbolique erroné):
    ERROR: rsyncDirToCollUtil: stat error for /home/Esturgeons/Tests/transabyss-test/k20, errno = 2
    A noter qu'avec l'option récursif (-r), l'erreur peut remonter ainsi jusqu'au dossier parent:
    ERROR: rsyncDirToCollUtil: put /home/Esturgeons/Tests/transabyss-test failed. status = -317000 status = -317000 USER_INPUT_PATH_ERR
    ERROR: rsyncDirToCollUtil: put /home/Esturgeons/Tests failed. status = -317000 status = -317000 USER_INPUT_PATH_ERR
    ERROR: rsyncDirToCollUtil: put /home/Esturgeons failed. status = -317000 status = -317000 USER_INPUT_PATH_ERR
    ERROR: rsyncUtil: rsync error for /MCIA/home/cbib/Esturgeons status = -317000 USER_INPUT_PATH_ERR

iquota

Usage: iquota [-uavVh] [UserName] [usage]
permet d'interroger la limite et l'utilisation du quota. Le logiciel iRODS différencie plusieurs types de quotas:
  • par ressource ou globaux
  • par utilisateur ou par groupe

Dans le cadre de l'infrastructure MCIA-iRODS, nous n'utilisons que les quotas globaux par utilisateur.

Attention: la commande iquota indique des valeurs en octets (bytes) bruts. Il ne faut les pas confondre avec un quota répliqué. En effet, un fichier de 1ko répliqué en trois endroits va consommer 3ko de quota brut. Dans le cadre de l'infrastructure MCIA-iRODS, nous parlons sauf mention contraire de quota répliqué (la taille des fichiers que vous pouvez stocker dans la solution sans considération sur la place occupée sur les serveurs).

Commandes de type ftp

iput

Usage : iput [-abfIkKPQrtTUvV] [-D dataType] [-N numThreads] [-n replNum]
             [-p physicalPath] [-R resource] [-X restartFile] [--link]
             [--lfrestart lfRestartFile] [--retries count] [--wlock]
             [--purgec]
               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]
               localSrcFile

Transfère un plusieurs fichiers locaux dans iRODS. Cette commande est très puissante et très configurable, mais attention aux options dangereuses ("-f", par exemple).

L'option -P est particulièrement intéressante pour suivre la progression du transfert.

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

Transfère un ou plusieurs fichiers depuis iRODS vers l'ordinateur local.

L'option -P est particulièrement intéressante pour suivre la progression du transfert.

Commandes sur les métadonnées

imeta

Usage: imeta [-vVhz] [command]
 -v verbose
 -V Very verbose
 -z Zonename  work with the specified Zone
 -h This help
Commands are:
 add -d|C|R|G|u Name AttName AttValue [AttUnits] (Add new AVU triplet)
 addw -d Name AttName AttValue [AttUnits] (Add new AVU triplet
                                           using Wildcards in Name)
 rm  -d|C|R|G|u Name AttName AttValue [AttUnits] (Remove AVU)
 rmw -d|C|R|G|u Name AttName AttValue [AttUnits] (Remove AVU, use Wildcards)
 mod -d|C|R|G|u Name AttName AttValue [AttUnits] [n:Name] [v:Value] [u:Units]
      (modify AVU; new name (n:), value(v:), and/or units(u:)
 set -d|C|R|G|u Name AttName newValue [newUnits] (Assign a single value)
 ls  -[l]d|C|R|G|u Name [AttName] (List existing AVUs for item Name)
 lsw -[l]d|C|R|G|u Name [AttName] (List existing AVUs, use Wildcards)
 qu -d|C|R|G|u AttName Op AttVal [...] (Query objects with matching AVUs)
 cp -d|C|R|G|u -d|C|R|G|u Name1 Name2 (Copy AVUs from item Name1 to Name2)
 upper (Toggle between upper case mode for queries (qu)

Manipulation des métadonnées.

Les options -d|C permettent d'agir notamment sur les métadonnées de fichiers (-d), de collection (-C). (-R|G|u concernent les métadonnées de ressource, ResourceGroups et utilisateurs, mais ce n'est pas accessible aux simples utilisateurs).

Les métadonnées suivent un format AVU (Attribute, Value, Unit). Les unités sont facultatives.

Les sous-commandes suivantes seront le plus souvent utilisées:
  • add ajoute une métadonnée. On peut ajouter plusieurs métadonnées ayant le même nom (mais pas la même valeur)
  • mod modifie une métadonnée existante
  • set positionne une métadonnée à une certaine valeur. Attention, utiliser set sur un objet ayant plusieurs métadonnées ayant le même nom efface toutes les valeurs.
  • ls liste les métadonnées associées à un objet
  • rm supprime une métadonnée
  • qu sélectionne les objets selon une condition sur une métadonnée. Par exemple:
    imeta qu -d somemeta = thirdvalue
    

Commandes informatives

ienv

Usage : ienv [-h]

Affiche l'environnement iRODS de l'utilisateur (serveur catalogue, port, nom d'utilisateur, etc...). Utile pour débugger les problèmes.

Exemple:

$ ienv
NOTICE: Release Version = rods3.3.1, API Version = d
NOTICE: irodsHost=icat0.mcia.univ-bordeaux.fr
NOTICE: irodsPort=1247
NOTICE: irodsZone=MCIA
NOTICE: irodsUserName=pigay
NOTICE: irodsDefResource=siterg-ubx
NOTICE: irodsAuthScheme=password
NOTICE: irodsAuthFileName=/home/pigay/.irods/.irods-mcia
NOTICE: environment variable set, irodsAuthScheme=password
NOTICE: created irodsHome=/MCIA/home/pigay
NOTICE: created irodsCwd=/MCIA/home/pigay

ilsresc

Usage: ilsresc [-lvVhA] [Name]

Liste les ressources ou les RG (Resource Group)

iuserinfo

imiscsvrinfo

iquest

Les commandes iquest permettent d'interroger le système sur les données, les collections, les ressources, les utilisateurs, etc. via une syntaxe proche de SQL.
La liste des éléments interrogeables est fournie par la commande: iquest attrs

Extrait:

$ iquest -h
Usage : iquest [-hz] [--no-page] [ [hint] format]  selectConditionString 
Usage : iquest --sql 'pre-defined SQL string' [format] [arguments] 
Usage : iquest attrs
Options are:
 -h  this help
 -z Zonename  the zone to query (default or invalid uses the local zone)
 --no-page    do not prompt asking whether to continue or not
              (by default, prompt after a large number of results (500)
format is C format restricted to character strings.
selectConditionString is of the form: SELECT <attribute> [, <attribute>]* [WHERE <condition> [ AND <condition>]*]
attribute can be found using 'iquest attrs' command
condition is of the form: <attribute> <rel-op> <value>
rel-op is a relational operator: eg. =, <>, >,<, like, not like, between, etc.,
value is either a constant or a wild-carded expression.
[...]

Voici quelques exemples d'utilisation:

  • Connaître la taille d'une collection (un répertoire iRODS)
    # Le '%' est important si l'on veut comptabiliser toutes les sous-collections
    iquest "%s" "select sum(DATA_SIZE) where COLL_NAME like 'full_path%'" 
    
  • Vérifier le nombre de réplicas
    # On peut afficher pour chaque donnée, le nombre de réplicas: 
    iquest --no-page "%s/%s  %s" "select COLL_NAME,DATA_NAME,count(DATA_REPL_NUM)" 
    
  • Connaître l'espace utilisé sur chaque ressource (i.e. serveur/baie)
    # La sortie est en octets
    iquest "select sum(DATA_SIZE), RESC_NAME where COLL_NAME like '/tempZone/home/rods%'" 
    
  • Espace utilisé sur chaque ressource pour chaque utilisateur
     # Cette requête liste chaque utilisateur, l'espace utilisé et le nombre de fichier stocké pour chaque ressource
    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" 
    # De facon ordonnée:
    iquest "User %-9.9s uses %14.14s bytes in %8.8s files in '%s'" "SELECT order(USER_NAME), sum(DATA_SIZE),count(DATA_NAME),RESC_NAME" 
    # Uniquement l'espace utilisé (en octets) et le fichiers:
    iquest "User %-9.9s uses %14.14s bytes in %8.8s files" "SELECT USER_NAME, sum(DATA_SIZE),count(DATA_NAME)" 
    
  • Liste des utilisateurs
    # Utilisateurs enregistrés
    iquest "%s" "SELECT USER_NAME  WHERE USER_TYPE = 'rodsuser'" 
    # Utilisateurs valides:
    iquest "%s" "SELECT USER_NAME  WHERE USER_TYPE = 'rodsuser' AND USER_COMMENT LIKE '%valide%'" 
    # Utilisateurs supprimés
    iquest "%s" "SELECT USER_NAME  WHERE USER_TYPE = 'rodsuser' AND USER_COMMENT LIKE '%removed%'" 
    
  • Liste des groupe
    iquest "%s" "SELECT USER_NAME  WHERE USER_TYPE = 'rodsgroup'"
  • Liste des utilisateurs ayant au moins déposé 1 fichiers:
    iquest "%s" "SELECT DATA_OWNER_NAME"
  • Nombre de métadonnées
    iquest "%s" "SELECT count(META_DATA_ATTR_ID)"
  • Espace total disponible (restant)
    # Uniquement les ressources nommées "irods*" qui sont actives (UP). Sortie (RESC_FREE_SPACE) en Méga-octets
    iquest "%s" "select RESC_FREE_SPACE WHERE RESC_STATUS like '%up%' AND RESC_NAME like 'irods%'" | awk '{s+=$1} END {print s}'
    
  • Espace utilisé sur chaque ressource
    iquest "%s usage: %s bytes (%s files)" "SELECT DATA_RESC_NAME, sum(DATA_SIZE),count(DATA_NAME)"
  • Espace utilisé sur chaque ressource groupe
    iquest "%s usage: %s bytes (%s files)" "SELECT DATA_RESC_GROUP_NAME, sum(DATA_SIZE),count(DATA_NAME)"
  • Espace total utilisé
    iquest "%s" "SELECT sum(DATA_SIZE)"
  • Nombre total de fichier
    iquest "%s" "SELECT count(DATA_NAME)"
  • Nombre total de fichiers réplicas (<> 0), de fichiers non réplicas (= 0) ?
    iquest "%s" "SELECT count(DATA_NAME) where DATA_REPL_NUM <> '0'" 
    iquest "%s" "SELECT count(DATA_NAME) where DATA_REPL_NUM = '0'" 
    
  • Taille totale des réplicas (<> 0), des non réplicas (= 0) ?
    iquest "%s" "SELECT sum(DATA_SIZE) where DATA_REPL_NUM <> '0'" 
    iquest "%s" "SELECT sum(DATA_SIZE) where DATA_REPL_NUM = '0'" 
    
  • Nombre de règle en cours d'exécution (pending)
    iquest "%s" "SELECT count(RULE_EXEC_ID)"

Autres commandes

irmtrash

Nettoyage immédiat de la corbeille. L'infrastructure MCIA effectue régulièrement un nettoyage des fichiers plus vieux que X jours. Voir: Fonctionnalités#Corbeille

irepl

irule

iqstat

Extensions MCIA

Nous avons créé un ensemble d'extensions aux iCommands: https://github.com/mesocentre-mcia/mcia-irods-utils. Ces extensions sont installées sur Avakas. Si vous avez installé vos clients avec la procédure fournie ici, elles auront été installées dans le même temps.

wildcards

Ce sont des wrappers autour de iCommands qui ne peuvent pas normalement bénéficier des wildcards (* et ?) du shell car elles manipulent des chemins iRODS (et pas locaux, donc le shell ne peut pas deviner correctement l'expansion de ces motifs).

Quitte à protéger les wildcards entre des guillemets (par exemple: "*") pour éviter la collision avec l'expansion des wildcards du shell, ces wrappers permettent l'utilisation de motifs en interrogeant le catalogue de manière adéquate.

Remarque:
  • ces wrappers sont écrits pour ressembler au comportement des wildcards du shell. Ils sélectionnent aussi bien des fichiers que des répertoires.

ilsw

Exemples

$ ilsw "*.txt" 
  /MCIA/home/pigay/tuto/test1.txt
  /MCIA/home/pigay/tuto/test2.txt
  /MCIA/home/pigay/tuto/test3.txt
$ ilsw "*/img???.jpg" 
  /MCIA/home/pigay/tuto/a/img000.jpg
  /MCIA/home/pigay/tuto/b/img000.jpg
  /MCIA/home/pigay/tuto/c/img000.jpg

Notons que la commande "ilsw "*"" sélectionnera des fichiers du répertoire courant, mais aussi des répertoires s'il y en a. Dans ce cas, elle affichera le listing de ces répertoires aussi.

irmw

commande à manipuler avec précaution...

igetw

Attention au mélange de wildcards et de fichiers locaux. Il faut impérativement terminer les arguments par un répertoire local.

Exemple:

$ igetw -v "*.txt" .
   test1.txt                       0.000 MB | 5.268 sec | 0 thr |  0.000 MB/s
   test2.txt                       0.000 MB | 0.019 sec | 0 thr |  0.001 MB/s
   test3.txt                       0.000 MB | 0.018 sec | 0 thr |  0.002 MB/s

icpw

Dans le cas où l'expansion de wildcard donne plus de 2 arguments, le dernier doit nécessairement être un répertoire.

Exemple:

imkdir newdir
icpw "*.txt" newdir/

imvw

Dans le cas où l'expansion de wildcard donne plus de 2 arguuents, le dernier doit nécessairement être un répertoire.

Exemple:

imkdir newdir
imvw "*.txt" newdir/

iechow

Cette commande permet d'imprimer l'expansion des wildcards iRODS. Elle est principalement utile pour débugguer.

Autres utilitaires

idu

Une commande pour connaître la taille des fichiers dans une collection et ses descendantes. Copiée sur la commande shell "du".

L'option "--logical-size" permet de ne comptabiliser qu'une seule réplique (la plus grande des répliques). On a ainsi l'espace utilisé sans les réplications.

irepl-check

Permet de vérifier et éventuellement corriger le nombre de répliques des fichiers d'une arborescence.

Pour le manuel, faire irepl-check -h.

Option -c pour renseigner le répertoire à analyser (par défaut le répertoire courant).

Afin que la réparation du nombre de répliques (option "--repair") fonctionne correctement dans l'environnement MCIA, votre fichier "~/.irods/.irodsEnv" doit contenir les lignes suivantes

# mcia-irods-utils configuration
irodsRescList 'irule(mciaRGListWrite)'
irodsUseRescGroups true

Exemple:
  • Trouver les fichiers qui n'ont pas 3 répliques:
    $ irepl-check 3
    /MCIA/home/pigay/tuto/test3.txt: 1
    /MCIA/home/pigay/tuto/test1.txt: 1
    /MCIA/home/pigay/tuto/test2.txt: 1
    

    Ici, on voit 3 fichiers qui n'ont qu'une réplique (la contrainte demandée est "exactement 3 répliques").
  • trouver les fichiers qui ne suivent pas la règle de 3 répliques ou le nombre de répliques spécifié par la métadonnée replFactor (voir l'exemple de imeta-coll):
    $ irepl-check replFactor+3 -r
    /MCIA/home/pigay/.irods/.profile : 1
    /MCIA/home/pigay/testdir/a/b/c/setup.py : 4
    /MCIA/home/pigay/testdir/a/setup.py : 2
    

Attention: le processus de réplication automatique peut-être parfois retardé pour diverses raisons. Utiliser la commande irepl-check trop tôt peut relever des erreurs alors que les instructions de réplications pour ce fichier sont en attente de traitement. (Pour savoir si des instructions de réplication sont encore en attente: iqstat

imeta-coll

Permet de manipuler les métadonnées d'une collection (éventuellement de manière récursive).

Pour le manuel, faire imeta-coll -h.

Exemples:
  • connaître les sous-collections qui possèdent une métadonnée replFactor:
    $ imeta-coll -r replFactor
    /MCIA/home/pigay/testdir/a : replFactor=1 
    /MCIA/home/pigay/testdir/a/b : replFactor=2 
    /MCIA/home/pigay/testdir/a/b/c : replFactor=3 
    
  • positionner la métadonnée replFactor à 2 pour la collection courante et ses sous-collections:
    $ imeta-coll -r replFactor=2
    
  • détruire la métadonnée metadata1 pour la sous arborescence de la collection courante:
    $ imeta-coll -r "~metadata1" 
    

iextract

Permet d'extraire des données (fichiers) et les métadonnées associées hors d'iRODS. Utile si on souhaite migrer vers un autre système de stockage.