diff --git a/README.rst b/README.rst index a6e06d1..16ab40c 100644 --- a/README.rst +++ b/README.rst @@ -3,7 +3,9 @@ Documentation utilisateur Les documentations pour les utilisateurs des services France Grilles hébergés sur cet entrepôt sont : -* ̀ FG-iRODS Users Guide `_ (en) + + * `FG-iRODS Users Guide `_ (en) + * `Guide d'utilisation du service FG-iRODS `_ (fr) La documentation est rédigée à l'aide du langage de balisage léger `reStructuredTExt `_. diff --git a/irods-fr/Makefile b/irods-fr/Makefile new file mode 100644 index 0000000..a4380cb --- /dev/null +++ b/irods-fr/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = UtilisationduserviceFG-iRODS +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/irods-fr/_static/fg_logo.png b/irods-fr/_static/fg_logo.png new file mode 100644 index 0000000..0900279 Binary files /dev/null and b/irods-fr/_static/fg_logo.png differ diff --git a/irods-fr/conf.py b/irods-fr/conf.py new file mode 100644 index 0000000..8f236ab --- /dev/null +++ b/irods-fr/conf.py @@ -0,0 +1,169 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# Utilisation du service FG-iRODS documentation build configuration file, created by +# sphinx-quickstart on Wed Feb 24 10:58:35 2021. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'Guide d\'utilisation du service FG-iRODS' +copyright = '2021, CNRS et Université de Strasbourg' +author = 'Jérôme Pansanel' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.0' +# The full version, including alpha/beta/rc tags. +release = '1.0' + +today = '29 avril 2021' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'fr' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# This is required for the alabaster theme +# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars +html_sidebars = { + '**': [ + 'relations.html', # needs 'show_related': True theme option to display + 'searchbox.html', + ] +} + + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'guide-utilisation-fg-irods' + + +# -- Options for LaTeX output --------------------------------------------- +latex_logo = '_static/fg_logo.png' +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + 'papersize': 'a4paper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'guide-utilisation-fg-irods.tex', 'Guide d\'utilisation du service FG-iRODS', + 'Jérôme Pansanel', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'guide-utilisation-fg-irods', 'Guide d\'utilisation du service FG-iRODS', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'guide-utilisation-fg-irods', 'Guide d\'utilisation du service FG-iRODS', + author, 'guide-utilisation-fg-irods', 'One line description of project.', + 'Miscellaneous'), +] + diff --git a/irods-fr/guide-utilisation-fg-irods.rst b/irods-fr/guide-utilisation-fg-irods.rst new file mode 100644 index 0000000..2623e1d --- /dev/null +++ b/irods-fr/guide-utilisation-fg-irods.rst @@ -0,0 +1,481 @@ +Introduction +============ + +À propos de ce document +----------------------- + +Ce document présente l'utilisation du client `iRODS `_ +avec le `service iRODS +`_ +(FG-iRODS) proposé par France Grilles. Il est basé sur sur le contenu +de la documentation en ligne du service FG-iRODS rédigée par Catherine +Biscarat, Pierre Gay et Jérôme Pansanel. + +La dernière version de ce document est disponible sur : +https://github.com/FranceGrilles/user-docs/tree/main/irods-fr. + +| Copyright (c) 2021 CNRS et Université de Strasbourg. +| Ce document est distribué sous la licence `Creative Commons Attribution 4.0 International license `_. + + +Le service FG-iRODS +------------------- + +Le service FG-iRODS, proposé par l'infrastructure de recherche +`France Grilles `_ a pour objectif +de faciliter la gestion des données de recherche. Il repose sur : + +* une infrastructure de stockage géographiquement distribuée + de niveau *production* hautement disponible ; + +* l'utilisation du logiciel iRODS ; + +* un accompagnement personnalisé des utilisateurs ; + +* un ensemble d'outils permettant d'en simplifier l'usage. + +L'accès à ce service est nominatif et réalisé par une simple demande +adressée à `info@france-frilles.fr `_. +Après étude de la demande et avant création des comptes, il est demandé +aux utilisateurs : + +* de signer les conditions d'accès au service FG-iRODS : http://www.france-grilles.fr/IMG/pdf/iRODS_Service_Policy.pdf ; + +* de fournir un plan de gestion de données (PGD). Plusieurs exemples de PGD + sont disponibles sur le site de DMP OPIDoR ``_ . + +Une fois les documents reçus, l'accès au service est ouvert, les +identifiants et la documentation du service transmis aux +utilisateurs. + + +Installation du client +====================== + +Prérequis +--------- + +L'installation du client iRODS nécessite de disposer d'un poste client +fonctionnant avec le système CentOS 7 ou Ubuntu (16.04, 18.04), sur +lequel il est possible d'installer de nouveaux logiciels. + + +Environnement +------------- + +Le client en ligne de commande iRODS utilise un fichier pour stocker +la configuration pour se connecter à l'infrastructure iRODS. Ce fichier +est *~/irods/irods_environment.json* et doit être créé avec le contenu +suivant : + +.. code-block:: console + + { + "irods_host": "ccirodsfg.in2p3.fr", + "irods_port": 5555, + "irods_zone_name": "FranceGrillesZone", + "irods_user_name": "", + "irods_default_resource": "", + "irods_client_server_negotiation": "request_server_negotiation", + "irods_client_server_policy": "CS_NEG_REQUIRE", + "irods_default_hash_scheme": "SHA256", + "irods_default_number_of_transfer_threads": 4, + "irods_encryption_algorithm": "AES-256-CBC", + "irods_encryption_key_size": 32, + "irods_encryption_num_hash_rounds": 16, + "irods_encryption_salt_size": 8, + "irods_match_hash_policy": "compatible", + "irods_maximum_size_for_single_buffer_in_megabytes": 32, + "irods_ssl_verify_server": "cert" + } + +Les valeurs ** et ** doivent être remplacées par +les valeurs qui vous ont été transmises lors de l'enregistrement auprès du service. + + +Installation des paquets +------------------------ + +Les paquets pour le client iRODS sont disponibles pour les systèmes +CentOS 7, Ubuntu 16.04 et Ubuntu 18.04. + +Les instructions d'installation pour les systèmes de gestion de paquets +*APT* et *YUM* sont détaillées sur la page https://packages.irods.org. + +Une fois que le dépôt est correctement configuré, il faut installer le +paquet ``irods-icommands``. + +La vérification de l'installation du client est réalisée avec : + +.. code-block:: shell-session + + $ iinit + +La commande **iinit** permets d'ouvrir une session vers l'instance iRODS. +Elle vous demande le mot de passe pour vous connecter. Une fois que vous +avez terminé votre transfert de données, vous pouvez terminer la session +avec la commande **iexit**. + +La commande **ienv** affiche l'environnement iRODS : + +.. code-block:: console + + irods_version - 4.2.8 + irods_client_server_negotiation - request_server_negotiation + irods_encryption_key_size - 32 + irods_environment_file - /home//.irods/irods_environment.json + irods_default_hash_scheme - SHA256 + irods_default_number_of_transfer_threads - 4 + irods_host - ccirodsfg.in2p3.fr + irods_client_server_policy - CS_NEG_REQUIRE + irods_session_environment_file - /home//.irods/irods_environment.json.15934 + irods_default_resource - + irods_encryption_algorithm - AES-256-CBC + irods_encryption_num_hash_rounds - 16 + irods_encryption_salt_size - 8 + irods_match_hash_policy - compatible + irods_ssl_verify_server - cert + irods_maximum_size_for_single_buffer_in_megabytes - 32 + irods_port - 5555 + irods_user_name - + irods_zone_name - FranceGrillesZone + + +Utilisation du service FG-iRODS +=============================== + +Aide en ligne +------------- + +**ihelp** permet d'afficher la liste des commandes iRODS, ainsi que l'aide +sur une commande spécifique : + +.. code-block:: shell-session + + $ ihelp ils + Usage: ils [-ArlLv] dataObj|collection ... + Usage: ils --bundle [-r] dataObj|collection ... + Display data Objects and collections stored in irods. + Options are: + -A ACL (access control list) and inheritance format + -l long format + -L very long format + -r recursive - show subcollections + -t ticket - use a read (or write) ticket to access collection information + -v verbose + -V Very verbose + -h this help + --bundle - list the subfiles in the bundle file (usually stored in the + /myZone/bundle collection) created by iphybun command. + + iRODS Version 4.2.8 ils + +La liste complète des commandes disponibles est également disponible dans +la `documentation officielle iRODS `_. + + +Répertoire de travail +--------------------- + +La commande **ils** affiche le contenu du répertoire courant avec lequel +vous travaillez sur le système FG-iRODS (par défaut, il s'agit de votre +répertoire utilisateur) : + +.. code-block:: shell-session + + $ ils + /FranceGrillesZone/home/: + +* *FranceGrillesZone* : le nom de la zone iRODS + +* */home/* : votre répertoire personnel + + +Chargement des données +---------------------- + +Dans cette section, des fichiers vont être chargés vers FG-iRODS. Tout d'abord, +créez un fichier exemple, tel que ``foo.txt``. + +Le fichier est copié vers l'infrastructure iRODS avec la commande : + +.. code-block:: shell-session + + $ iput -K foo.txt + +L'option *-K* permet de vérifier le *checksum* et de le stocker dans la base +de données. Il est recommandé de l'utiliser systématiquement. Le fichier +est maintenant disponible sur FG-iRODS : + +.. code-block:: shell-session + + $ ils + /FranceGrillesZone/home/: + foo.txt + +Le fichier peut être supprimé avec la commande suivante : + +.. code-block:: shell-session + + $ irm foo.txt + + +Espace de nom et chemin physique +-------------------------------- + +iRODS fournit une abstraction de l'emplacement physique des fichiers. +Par exemple, ``/FranceGrillesZone/home//foo.txt`` est le chemin +logique utilisé par iRODS. Pour savoir où sont réellement stockées +les données, il faut utiliser l'option **-L** avec la commande **ils** : + +.. code-block:: shell-session + + $ ils -L + /FranceGrillesZone/home/: + 0 mcia;mcia-fgirods1 483 2020-11-20.09:30 & foo.txt + sha2:veVzp+ApMzyVRzZN0BZIkDyFuqUp/4tM4sLVACp00B8= generic /vault1/resc/home//foo.txt + + +Cette commmande nous indique que : + + * le fichier ``foo.txt`` est enregistré par FG-iRODS comme : + ``/FranceGrillesZone/home//foo.txt`` ; + + * son propriétaire est ** ; + + * il a été chargé sur la ressource de stockage *mcia* ; + + * il n'y a qu'un seul réplica, dont l'identifiant est *0* ; + + * sa taille est de 483 octets ; + + * son *checksum* a été enregistré (*sha:veVzp+ApMzyVRzZN0BZIkDyFuqUp/4tM4sLVACp00B8=*). + + +Téléchargement de données +------------------------- + +Le fichier stocké dans FG-iRODS peut être téléchargé avec : + +.. code-block:: shell-session + + $ iget -K foo.txt foo-restore.txt + +Le fichier ``foo.txt`` a été téléchargé et nommé ``foo-restore.txt``. +Avec l'option **-K** option, le *checksum* du fichier local est comparé +avec le *checksum* du fichier sur FG-iRODS. + + +Structuration des données +------------------------- + +Création d'une collection ++++++++++++++++++++++++++ + +Sur votre ordinateur, les données sont organisées dans des répertoires. +Avec iRODS, elles sont organisées de la même manière, sauf que ces dossiers +sont appelés des *collections*. + +Pour créer une collection iRODS : + +.. code-block:: shell-session + + $ imkdir mycollection + +Le fichier ``foo.txt`` peut être déplacé dans la collection +*mycollection* avec : + +.. code-block:: shell-session + + $ imv foo.txt mycollection + $ ils -L mycollection + /FranceGrillesZone/home//mycollection: + 0 mcia;mcia-fgirods1 483 2020-11-20.10:18 & foo.txt + sha2:veVzp+ApMzyVRzZN0BZIkDyFuqUp/4tM4sLVACp00B8= generic /vault1/resc/home//mycollection/foo.txt + +Vous pouver voir que le chemin logique de la collection +``/FranceGrillesZone/home//mycollection`` a un +répertoire physique : ``/vault1/resc/home//mycollection``. +Ainsi, les données n'arrivent pas n'importe où sur un serveur iRODS, +mais se placent dans cette structure. + +Les données peuvent être chargées directement dans une collection : + +.. code-block:: shell-session + + $ iput -K -r bar.txt mycollection + $ ils /FranceGrillesZone/home//mycollection + /FranceGrillesZone/home//mycollection: + bar.txt + foo.txt + + +L'option **-r** permet un chargement récursif. + + +Naviguer à travers les collections +++++++++++++++++++++++++++++++++++ + +Pour afficher votre répertoire courant sur iRODS, utilisez : + +.. code-block:: shell-session + + $ ipwd + /FranceGrillesZone/home/ + +Si vous ne spécifiez pas le chemin complet, mais uniquemenet un chemin +relatif tel que ``mycollection/``, iRDS utilise automatiquement +le répertoire courant de travail comme préfixe. Le répertoire courant +de travail peut être modifié avec : + +.. code-block:: shell-session + + $ icd mycollection + + +Gestion des métadonnées +----------------------- + +iRODS est un logiciel disposant de nombreuses fonctionnalités reposant +sur l'utilisation des métadonnées. + +Création de métadonnées ++++++++++++++++++++++++ + +Il est possible d'ajouter à chaque fichier une ou plusieurs métadonnées +représentées sous forme de triplet *Attribute*, *Value*, *Unit* (AVU). +Ces triplets sont ajoutés dans la base iCAT d'iRODS et peuvent être +recherchés. Les métadonnées sont ajoutées avec la commande : + +.. code-block:: shell-session + + $ imeta add -d foo.txt 'length' '20' 'words' + + +Le champs *Unit* peut être vide : + +.. code-block:: shell-session + + $ imeta add -d foo.txt 'project' 'example' + +Les métadonnnées peuvent également être ajoutées à une collection : + +.. code-block:: shell-session + + $ imeta add -C mycollection 'author' 'John Smith' + + +Affichage des métadonnées ++++++++++++++++++++++++++ + +Pour afficher les métadonnées d'un objet de données (fichier), il +faut entrer : + +.. code-block:: shell-session + + $ imeta ls -d foo.txt + AVUs defined for dataObj /FranceGrillesZone/home//mycollection/foo.txt: + attribute: length + value: 20 + units: words + +et pour une collection, la commande suivante : + +.. code-block:: shell-session + + $ imeta ls -C mycollection + AVUs defined for collection /FranceGrillesZone/home//mycollection: + attribute: author + value: John Smith + units: + + +Recherche avec les métadonnées +------------------------------ + +La recherche de fichiers ou de collections à l'aide des métadonnées +est effectuée avec la commande suivante : + +.. code-block:: shell-session + + $ imeta qu -d 'length' = '20' + collection: /FranceGrillesZone/home//mycollection + dataObj: foo.txt + + + +Recherche avancée +----------------- + +Afin d'effectuer une recherche plus fine de fichiers ou de collections, +il est possible d'interroger directement le catalogue iCAT avec la +commande **iquest** : + +.. code-block:: shell-session + + $ iquest "select COLL_NAME, META_COLL_ATTR_VALUE where META_COLL_ATTR_NAME like 'author'" + COLL_NAME = /FranceGrillesZone/home//mycollection + META_COLL_ATTR_VALUE = John Smith + ------------------------------------------------------------ + +Les résultats peuvent être filtrés en fonction d'une valeur spécifique : + +.. code-block:: shell-session + + $ iquest "select COLL_NAME, META_COLL_ATTR_VALUE where META_COLL_ATTR_NAME like 'author' \ + and META_COLL_ATTR_VALUE like 'John%'" + COLL_NAME = /FranceGrillesZone/home//mycollection + META_COLL_ATTR_VALUE = John Smith + ------------------------------------------------------------ + + +**NOTE**: le caractère '%' est un caractère générique (*wildcard*). + +Si vous recherchez un objet de données plutôt qu'une collection, il +faut remplacer *META_COLL_ATTR_NAME* par *META_DATA_ATTR_NAME*. De +nombreux attributs peuvent être utilisés pour les recherches. Pour +les afficher, utilisez : + +.. code-block:: shell-session + + $ iquest attrs + + +Contrôle d'accès +---------------- + +iRODS propose un mécanisme de droits d'accès similaire au système +disponible sur les systèmes UNIX (ACL). Il permet de contrôler les +droits de lecture, d'écriture et de propriété. Pour afficher les droits +d'accès à la collection actuelle : + +.. code-block:: shell-session + + $ ils -r -A + /FranceGrillesZone/home//mycollection: + ACL - #FranceGrillesZone:own + Inheritance - Disabled + bar.txt + ACL - #FranceGrillesZone:own + foo.txt + ACL - #FranceGrillesZone:own + + +Les droits d'accès à un fichier sont spécifiés après le mot-clé *ACL*. +Dans cet exemple, ** est propriétaire de tous les fichiers +affichés. Aucune autre personne ne peut y accéder. + +Les collections ont un attribut *Inheritance*. Lorsque la valeur de cet +attribut est égale à *Enabled*, l'ensemble du contenu de la collection +hérite des droits d'accès de la collection. Cet héritage ne s'applique +qu'aux nouveaux fichiers copiés dans la collection. + +La modification des droits d'accès pour autoriser un collègue à accéder +à ses données se fait avec : + +.. code-block:: shell-session + + $ ichmod read foo.txt + +L'utilisateur ** peut maintenant accéder en lecture au +fichier ``foo.txt``. diff --git a/irods-fr/index.rst b/irods-fr/index.rst new file mode 100644 index 0000000..eac6179 --- /dev/null +++ b/irods-fr/index.rst @@ -0,0 +1,17 @@ +.. + Copyright 2021 CNRS and University of Strasbourg + + This work is licensed under the Creative Commons Attribution 4.0 + International License. To view a copy of this license, visit + http://creativecommons.org/licenses/by/4.0/ or send a letter to Creative + Commons, PO Box 1866, Mountain View, CA 94042, USA. + +======================================= +Guide d'utilisation du service FG-iRODS +======================================= + +.. toctree:: + :maxdepth: 2 + :caption: Sommaire + + guide-utilisation-fg-irods.rst