====== Utilisation de la grappe de processeurs ======
La commande **cluster** a été développée à l'origine
par Jean-Louis Martineau pour gérer l'accès à une grappe de 24 noeuds,
les clacs.
Actuellement, elle permet de coordonner
les accès à plusieurs grappes associées à un laboratoire de recherche
ou à tout le département.
====== Principe de fonctionnement ======
L'idée de base est de réserver une machine pour y exécuter un certain nombre de tâches et de la libérer lorsque les tâches sont terminées.
C'est la raison d'être des actions **reserve** et **libere** de la commande **cluster**.
A cela s'ajoutent les actions **liste** et **charge** qui montrent respectivement les réservations et la charge des machines.
Finalement l'action **execute** combine à la fois la réservation, la soumission d'une tâche et la libération de la réservation.
L'action **libere** peut être utilisée pour libérer une réservation orpheline.
Il faut aussi noter que l'action **libere** n'agit que sur la réservation de la machine et n'affecte en rien les tâches qui s'y exécutent.
====== Syntaxe ======
La syntaxe de la commande **cluster** suit à peu près le schéma suivant : un mot clé précédé de "--"
et possiblement suivi d'une ou plusieurs valeurs séparées par des ",".
Les mots clés peuvent être séparés des valeurs, soit par un espace, soit par un "=".
Les mots clés peuvent être abrégés tant qu'il n'y a pas d'ambiguité et l'ordre n'importe pas.
En cas d'ambiguité, les valeurs possibles sont énumérées dans le message d'erreur.
Lorsqu'un mot clé est répété, seule la dernière instance est utilisée.
Un des mots clés présents et un seul doit préciser l'action voulue.
Un mot clé absent (**--** tout seul) permet de stopper l'interprétation des mots clés
et de spécifier à sa suite les paramètres de la commande à exécuter.
On peut aussi spécifier la commande et ses paramètres entre "".
Voici quelques exemples de la syntaxe :
cluster --aide
cluster --os=fc14 --liste
cluster --execute uname --os=fc9 -- -a
cluster --mem 20 --execute "uname -nrp"
cluster --libere --id=1234567
====== Réservations ======
Les réservations faites par l'usager ont une durée
de vie (8 heures par défaut).
L'action **prolonge** permet de spécifier
une nouvelle durée pour la réservation.
La valeur maximum est de 31 jours,
ce qui correspond à la durée de vie d'un ticket Kerberos.
En plus de la durée, on peut spécifier un certain
nombre de critères caractérisant les machines à réserver.
En particulier, la quantité de mémoire et le système d'exploitation.
A l'origine, les machines du cluster avaient un ou deux processeurs
et réserver toute une machine pour un usager était acceptable.
Avec les machines récentes qui peuvent avoir des dizaines de processeurs,
ces machines ont été partitionnées en pseudo-machines distinguées
par une lettre majuscule ajoutée au nom
afin d'affiner le mécanisme de réservation.
Ce partitionnement est flexible et peut être ajusté au besoin.
====== Actions ======
Les actions de la commande **cluster**
sont présentées en ordre alphabétique.
Les options facultatives sont mentionnées entre **[]**.
Dans la liste qui suit, le préfixe **--** a été omis.
Les chaines présentées entre **' '** représentent des valeurs
spécifiées par l'usager.
Ainsi, 'mach' représentera un nom de machine,
'num' un nombre entier, etc.
Le détail des valeurs est expliqué dans la section **Options**.
La notation **['criteres']** qui a été choisie pour alléger la présentation,
représente un certain nombre d'options ('os', 'memoire', etc.)
précisant surtout le type de machine voulue.
===== aide =====
Imprime un aide-mémoire des actions et des options.
===== charge [--os='os'] [--machine='mach'] =====
Donne la charge et la réservation de chaque machine.
Les options facultatives permettent de restreindre l'affichage aux machines se qualifiant.
Il faut aussi noter que seules les machines auxquelles l'usager a accès seront montrées.
La sortie comprend : le nom de la machine,
l'usager ayant réservé et les trois valeurs numériques (//load average//) données par la commande 'uptime'.
===== execute 'commande' ['criteres'] [--proc='num'] [-- 'args ...'] =====
L'action **execute** est de loin la plus élaborée de la commande **cluster**.
Une réservation est d'abord tentée avec les critères fournis ('os', 'memoire', etc.) ou leurs valeurs par défaut.
Si la réservation échoue, un message d'erreur est retourné.
Cette action réserve automatiquement les processeurs et les libère lorsque la commande se termine.
En cas de succès, la commande 'commande' est exécutée comme suit sur la machine réservée :
cd 'dir'
'commande' [format] 'args ...'
'dir' est le répertoire courant de la commande **cluster** ou celui mentionné via l'option **cwd**.
[format] indique une chaine facultative qui sera ajoutée avant les paramètres (args) de la commande
si l'option **format** a été mentionnée.
Par défaut, la commande est lancée sur un seul processeur.
La commande n'est pas limitée à un seul programme.
En fait toute expression acceptée par le //shell// de l'usager peut être utilisée.
Il faut cependant faire attention aux caractères d'échappement (' " et \ ) reconnus par le //shell//.
===== help =====
Synonyme de **aide**.
===== libere --id='id' =====
Libère les machines de la réservation 'id'.
Attention, **libere** ne termine pas les tâches
en cours d'exécution.
===== liste [--os='os'] [--machine='mach'] =====
Imprime la liste des réservations et des machines.
Les options facultatives permettent de restreindre
l'affichage aux machines se qualifiant.
Il faut aussi noter que seules les machines auxquelles
l'usager a accès seront montrées.
===== prolonge --id='id' [--duree='val'] =====
Prolonge la réservation 'id' de la durée spécifiée par 'val'.
Si la durée est absente,
la valeur par défaut est utilisée.
===== reserve ['criteres'] [--proc='num'] [--duree='val'] =====
Réserve 'num' processeurs en respectant les critères mentionnés.
Par défaut, un seul processeur est réservé.
Si la réservation est réussie, la sortie contiendra les valeurs : 'id' 'num' 'machine ...', précisant le numéro de la réservation, le nombre de processeurs et les machines réservées.
Cette action n'est plus directement accessible.
===== -- =====
Termine l'interprétation des options,
permettant ainsi de spécifier à sa suite
les paramètres de la commande à exécuter.
====== Options ======
Les options sont présentées en ordre alphabétique.
Certaines options ne sont utiles qu'avec certaines actions,
elles sont simplement ignorées autrement.
Dans la liste qui suit, le préfixe **--** a été omis.
===== cpu='num' =====
Cette option permet de spécifier le nombre de processeurs (cpu) requis.
Par défaut, un seul processeur sera requis.
===== cwd='dir' =====
Cette option permet de spécifier le répertoire 'dir'
où sera exécutée la commande sinon c'est le répertoire
où la commande **cluster** est exécutée
qui sera utilisé.
===== duree='val' =====
'val' est une valeur numérique exprimée en secondes.
Les suffixes 'm', 'h', 'j' indiquent que 'val' représente
respectivement des minutes, des heures ou des jours.
La durée par défaut d'une réservation est de 8 heures.
La durée maximum est de 31 jours,
ce qui correspond à la durée de vie d'un ticket Kerberos.
===== format='chaine' =====
'chaine' spécifie la chaine à passer comme premier argument à la commande à exécuter.
Dans cette chaine, les séquences suivantes seront remplacées par les valeurs correspondantes :
%n par le nombre de processus
%m par le nom de la machine
%M par les noms des machines
===== id='id' =====
'id' est le numéro de la réservation.
Ce numéro apparait dans la première section de l'action **liste**.
===== machine='nom' =====
'nom' est le nom spécifique (nom court sans la partie .iro.umontreal.ca)
d'une machine.
Ce nom permet de restreindre les actions **charge**,
**execute**,
**liste** à la seule machine mentionnée.
===== memoire='val' =====
Cette option permet de spécifier la quantité de mémoire requise.
La mémoire est exprimée en méga-octets et la valeur par défaut est de 512.
===== minproc='num' =====
Normalement, si le nombre de processeurs disponibles est inférieur
au nombre requis par l'option **proc**,
la réservation échoue.
Par contre, s'il y a au moins 'num' processeurs disponibles,
la réservation s'effectuera quand même
avec le nombre maximum de processeurs disponibles
jusqu'à concurrence de la valeur spécifiée par l'option **proc**.
===== os='os' =====
Cette option permet de spécifier la version du système d'exploitation
des machines à réserver en précisant la distribution voulue :
fc9 pour des noeuds avec Fedora core 9
fc14 pour des noeuds avec Fedora 14
all pour des noeuds avec fc9 ou fc14
La valeur par défaut est présentement 'fc14' pour l'action **execute** et 'fc9,fc14' pour les actions **charge** et **liste**.
===== proc='num' =====
Cette option permet de spécifier le nombre de processeurs requis.
La valeur par défaut est de un.
===== stdin =====
L'action **execute** ignore par défaut
l'entrée standard (commande ssh avec l'option -n).
Cette option permet de connecter l'entrée standard à la commande à exécuter
s'il n'y a qu'un seul processeur requis (**proc=1**).
===== wait =====
Cette option permet d'attendre que la réservation puisse
s'effectuer lorsqu'il n'y a pas assez de machines disponibles.
====== Les fichiers d'entrée/sortie ======
Par défaut,
l'entrée standard (stdin) n'est pas connectée à la commande à exécuter à moins
que l'option **stdin** ne soit mentionnée.
La sortie standard (stdout) et la sortie d'erreur (stderr) le sont.
En cas de longue exécution, il est recommandé de rediriger ces sorties
vers des fichiers pour éviter leur perte en cas d'erreur ou de panne.
====== Exemples ======
===== cluster --charge =====
kiwi0g , : 0.00, 0.00, 0.00
kiwi0h , : 0.00, 0.00, 0.00
malaga01A, usagerxx : 5.00, 5.00, 5.00
malaga01B, usagerxx :
malaga01C, usagerxx :
malaga01D, usagerxx :
===== cluster --liste =====
Liste des réservations:
ID : USAGER : EXPIRATION :PROC: MEM : MACHINES
263560 : usagerxx :EX Thu Sep 29 04:41:57 2011: 1 : 64000 : ilar01A
Liste des machines:
MACHINE CARACTERISTIQUES ( USAGER : EXPIRATION :PROC: MEM : ID*)
...
giga0h , 2 cpu (x86_64) (fc7) 8192M ---
ilar01A , 2 cpu (x86_64) (fc9) 64000M --- (usagerxx :EX Thu Sep 29 04:41:57 2011: 1 : 64000 : 263560)
...
Sur 90 machines, 13 sont réservées et 77 sont disponibles.
===== cluster --os=fc9 --mem=2000 --duree=24h --execute 'ma_commande' -- 'params ...' =====
Réserver une machine avec fc9 et 2 giga-octets de mémoire pour 24 heures
et y exécuter 'ma_commande' avec les paramètres 'params'.
===== cd /tmp ; cluster --format "-FMT: n=%n m=%m-" --exec "uname -nrp; pwd; echo" -- "etc." =====
acgt01.iro.umontreal.ca 2.6.23.17-88.fc7 x86_64
/tmp
-FMT: n=1 m=acgt01- etc.
====== Problèmes connus ======
Il n'y a pas de page de manuel
et la documentation donnée par **aide** laisse à désirer.
On ne peut libérer qu'une réservation à la fois.
La valeur par défaut de l'option **os**
est source de confusion.
Il peut rester des réservations orphelines.
Le message BAD libere/prolonge n'est pas très clair.
Il y a une certaine confusion entre CPU et PROC
(processeur et processus).
Certaines validations pourraient être effectuées
directement par la commande **cluster**.
====== Auteurs ======
2001-2006 Jean-Louis Martineau.\\
2006-2011 Claude Goutier.\\