293 lines
13 KiB
Plaintext
293 lines
13 KiB
Plaintext
|
# -*- coding: utf-8 mode: markdown -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8
|
||
|
|
##@creator: jclain
|
||
|
|
##@created: 27/04/2016 03:19
|
||
|
|
##@modifier: jclain
|
||
|
|
##@changecount: 1
|
||
|
|
##@tags:
|
||
|
|
##@title: 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.
|
||
|
|
}}}
|