# uscrontab ~~~ uscrontab: lancer une suite de commande en respectant une planification de type cron USAGE uscrontab [options] [/path/to/uscrontab] [var=value...] uscrontab -e [/path/to/uscrontab] uscrontab -l La première forme du script doit normalement être lancé toutes les minutes par une tâche cron. Utiliser l'option --install pour ajouter automatique la ligne dans la crontab de l'utilisateur. Avec la première forme du script, le fichier spécifié est traité. Si aucun fichier n'est spécifié, fusionner s'il existe le fichier /var/local/uscrontab/users/jclain avec chacun des fichiers du répertoire /var/local/uscrontab/users.d/jclain dans un fichier temporaire, puis exécuter le fichier résultat avec le nom virtuel /var/local/uscrontab/jclain note: le nom virtuel est utilisé pour le verrouillage avec --lock A chaque lancement de ce script, le fichier /path/to/uscrontab spécifié est examiné pour déterminer quels commandes doivent être exécutées. Ce fichier est composé de lignes dans un format particulier, qui sont analysées et traitées dans l'ordre. Quelles que soient les lignes qui sont sélectionnées pour l'exécution, elles sont garanties de s'exécuter dans l'ordre du fichier, l'une après l'autre. Les définitions var=value mentionnées sur la ligne de commande sont des définitions de variables à effectuer avant de lancer les commandes. Les lignes commençant par # sont des commentaires et sont ignorées == Définitions de variables et exécution de commandes == Les lignes de la forme suivante sont des définitions de variable: [export] var="valeur de la variable" Ces lignes sont des définitions de variable bash qui sont exécutées telles quelles. Il n'est donc pas autorisé de mettre des espaces autour de =. Par exemple, les lignes suivantes sont des erreurs de syntaxe: var = bad var=pas de quotes autour de la valeur alors que celles-ci sont correctes: var=ok var="valeur avec des espaces" var='on peut utiliser des quotes aussi' Il est possible de manipuler les variables de type PATH avec une syntaxe particulière de l'opérateur d'assignation. Les opérateurs += et %= utilisent uaddpath(), #= utilise uinspath() et -= utilise udelpath(). Par exemple, les lignes suivantes ajoutent respectivement /usr/local/nutools puis enlèvent /opt/rogue au PATH: PATH+=/usr/local/nutools PATH-=/opt/rogue Bien sûr, il ne faut pas oublier de quoter les espaces: PATH+="/path/to/dir with spaces" La syntaxe ?= permet de définir la valeur d'une variable si elle n'est pas déjà définie: var?=default Les lignes de la forme suivante permettent d'exécuter une commande qui est exécutée systématiquement et ignore la planification: $one-line-command Une variante permet de spécifier des commandes sur plusieurs lignes. ATTENTION! ${ et $} doivent être tous seuls sur la ligne. ${ several commands ... $} Ces commandes sont exécutées systématiquement et ignorent la planification. On peut s'en servir notamment pour lire un fichier de configuration qui définit des variables ou des fonctions: $source path/to/file Le code d'erreur de ces commandes est ignoré, contrairement à ce qui se passe pour les commandes qui font l'objet d'une planification. == Planification de commandes == Les autres lignes doivent être au format d'une ligne de crontab: minutes hours days months dows command-line command-line peut être n'importe quelle ligne de commande bash, pourvu qu'elle soit sur une seule ligne. Certaines extensions par rapport à la syntaxe de crontab sont autorisées. Il est en particulier possible de spécifier plusieurs planifications pour une seule commande. Par exemple, les lignes suivantes permettent d'exécuter 'command' toutes les heures ET à 1h05: 0 * * * * 5 1 * * * command Il est aussi possible d'utiliser la même planification pour plusieurs commandes sans devoir répéter la définition de la planification. Les lignes suivantes planifient command1 et command2 toutes les heures: 0 * * * * command1 command2 Pour être prise en compte, la ligne command2 doit commencer par au moins un espace ou une tabulation. Pour la lisibilité, la syntaxe suivante est supportée aussi: 0 * * * * command1 command2 Les deux formats peuvent être utilisés ensemble. Par exemple les lignes suivantes exécutent command1 et command2 toutes les heures ET à 1h05: 0 * * * * 5 1 * * * command1 command2 Par défaut, le script s'arrête à la première commande planifiée qui retourne avec un code d'erreur. Il est possible d'ignorer le code d'erreur d'une commande avec nostop, e.g: 0 * * * * nostop command Cf aussi l'option --continuous pour modifier le comportement par défaut == Fonctions disponibles == La fonction check_pidfile() est disponible, et permet de vérifier qu'une opération n'est pas déjà en cours. Si cette fonction est utilisée, il ne faut pas modifier la valeur de -k. Par exemple: 0 1 * * * check_pidfile /path/to/pid [args] long-running-script check_pidfile() doit être utilisée toute seule sur la ligne et s'utilise avec les argument suivants: check_pidfile PIDFILE [DESC] [BARRIER] - PIDFILE est le fichier de PID qui est vérifié - DESC est la description du traitement qui est effectué. La valeur par défaut est "Une synchronisation". Si le fichier de PID est présent, le message suivant est affiché: DESC est en cours. Si vous pensez que c'est une erreur, veuillez vérifier le process de pid PID puis supprimez le cas échéant le fichier PIDFILE - BARRIER est un fichier qui est créé avec le contenu 'PID' s'il n'existe pas encore, et si la vérification du fichier de PID est faite avec succès. La présence de ce fichier peut-être vérifiée par un processus externe pour empêcher par exemple de mettre à jour les scripts pendant qu'il sont en train de tourner. Son contenu peut être examiné pour connaître le PID du processus qui l'a créé initialement. Le fichier est automatiquement supprimé à la fin de ce script. Attention: ce fichier n'est pas un verrou, il peut être supprimé à tout moment. Notamment, si deux scripts sont configurés pour créer le même fichier barrière, le premier script supprimera le fichier barrière avant la fin de l'exécution du second script. La fonction remove_pidfile() permet de supprimer un fichier de pid pour spécifier qu'une opération est terminée. Considérons l'exemple suivant: 0 1 * * * check_pidfile /path/to/pid script1 script2 remove_pidfile /path/to/pid script3 Dans cet exemple, il ne faut pas qu'une autre occurence de script1 tourne pendant que script2 tourne. Par contre, plusieurs occurences de script3 peuvent tourner en parallèle. La fonction elogto() permet de spécifier un fichier vers lequel toutes les sorties sont redirigées. OPTIONS -A, --install Installer une planification toutes les minutes du script dans la crontab de l'utilisateur. Si l'argument /path/to/uscrontab n'est pas spécifié, c'est une planification générique qui exécute les fichiers par défaut qui est installée. -R, --uninstall Désinstaller la planification toutes les minutes du script de la crontab de l'utilisateur. Si l'argument /path/to/uscrontab est spécifié, cette instance est désinstallée. Sinon, ne désinstaller que la planification générique. -d, --disable-only Avec l'option -R, désactiver la planification au lieu de la supprimer. -e, --edit Lancer un editeur pour modifier l'uscrontab spécifiée. Si aucun fichier n'est spécifié, éditer /var/local/uscrontab/users/jclain -a, --add Installer un script uscrontab dans le répertoire approprié. L'argument doit être de la forme [name:]/path/to/uscrontab Si name n'est pas spécifié, le nom de base du fichier spécifié est utilisé. Si name est vide ou vaut $USER (soit jclain en l'occurence), copier le fichier spécifié vers le chemin /var/local/uscrontab/users/jclain Sinon, copier le fichier spécifié vers /var/local/uscrontab/users.d/jclain/name -r, --remove Supprimer le script uscrontab spécifié. L'argument doit être le nom du script à supprimer. Si l'argument n'est pas spécifié ou vaut $USER (soit jclain en l'occurence), supprimer le fichier /var/local/uscrontab/users/jclain s'il existe -l, --list Si l'argument /path/to/crontab est spécifié, afficher le contenu de ce fichier. Sinon, lister les contenus des fichiers crontab qui sont exécutés avec la planification actuelle. Si une planification générique est installée, ou si aucune planification n'est en cours, afficher le contenu du fichier /var/local/uscrontab/users/jclain et chacun des fichiers du répertoire /var/local/uscrontab/users.d/jclain -n, --fake Afficher au lieu de les exécuter les commandes qui doivent être lancées -P, --pause-for NBMINS Désactiver les planifications pendant NBMINS minutes. Utiliser -1 pour désactiver les planifications sans limite de durée. Pendant la période de pause, toutes les invocations de uscrontab n'ont aucun effet, sauf si on utilise l'option --force -Y, --unpause Réactiver les planifications après une mise en pause -p, --pause Désactiver les planifications pendant 1 journée. Equivalent à -P 1440 -f, --force Forcer l'exécution de la planification, même si elle a été mise en pause avec l'option --pause OPTIONS AVANCEES --lock LOCKFILE Inscrire dans le fichier spécifié des informations permettant d'éviter les invocations simultanées de ce script. Si selon ce fichier, le script tourne depuis plus de 8 heures, un message d'erreur est consigné et un message d'avertissement est affiché au plus une fois. Utiliser --lock '' pour désactiver cette fonctionnalité Par défaut, si ce script est lancé en root, le fichier utilisé pour le verrouillage est de la forme /var/run/uscrontab/abspath/to/crontab Si le script est lancé avec un compte utilisateur, aucun verrouillage n'est effectué. --lockdelay LOCKDELAY[=8] Changer le nombre d'heures pendant lesquelles on autorise le script a verrouiller l'exécution avant d'afficher un avertissement. -c, --continuous Par défaut, ce script s'arrête à la première commande planifiée qui retourne avec un code d'erreur. Notez que les codes d'erreur des commandes sans planification sont toujours ignorés. Avec cette option, ce script ne s'arrête jamais, bien qu'il retourne toujours un code d'erreur si une erreur s'est produite. Il est possible d'ignorer le code d'erreur pour une commande en particulier avec le préfixe nostop -k, --stopec EXITCODE[=101] Spécifier un code d'erreur spécial qui arrête ce script sans erreur, ou '' pour désactiver cette fonctionnalité. Ceci permet en début de script de faire des tests par exemple sur l'environnement avant de lancer les scripts planifiés. Si l'environnement ne convient pas, il suffit au script de contrôle de retourner le code d'erreur spécifique pour arrêter le traitement. --show-ctnow Afficher l'heure de référence au format crontab 'min hou day mon dow' Cette valeur peut être utilisée avec l'option --force-ctnow dans des tests pour reproduire une condition spécifique. --force-ctnow 'min hou day mon dow' Pour le développement ou des tests, forcer la valeur de l'heure de référence. Il faut respecter le format, sinon les résultats ne sont pas garantis. Le mieux est de reprendre le résultat de l'option --show-ctnow en le modifiant un peu si nécessaire. -G, --any-ctnow Pour le développement ou des tests, lancer toutes les commandes dans l'ordre sans tenir compte de l'heure de référence. Cette commande ne devrait pas être utilisée en temps normal, mais elle existe pour simplifier les tests avec --show-ctnow + --force-ctnow dans les cas simples. ~~~ -*- coding: utf-8 mode: markdown -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8:noeol:binary