Introduction

DjeShellSteps est une bibliothèque pour le shell bash, permettant de créer des scripts shell organisés en étapes, pour simplifier et améliorer vos scripts d’exploitation. Si le programme détecte un problème pendant l’exécution, le script s’arrête, renvoyant un code d’erreur et un message explicatif. Lorsqu’un utilisateur le redémarre, le programme reprend à la dernière étape en erreur et continue son travail.

Chaque exécution de script génère un fichier de log, capturant toutes les sorties des commandes (stdout et stderr).

DjeShellSteps est très utile pour automatiser certains processus et sécuriser des scripts shell. Chaque shell peut être redémarré à la dernière étape en erreur, à partir d’une étape particulière, ou depuis le début. Le log complet peut être affiché en temps réel sur stdout ou caché. Un résumé en direct de l’exécution du script est également disponible.

J’ai commencé à travailler sur DjeShellSteps pour mes besoins en scripts d’exploitation de mon site en 2007. Ayant constaté des besoins similaires sur les forums et sur Internet, j’ai décidé de le publier en tant que produit Open Source.

Ce manuel est destiné à DjeShellSteps version 1.01.

Fonctionnalités

Voici une liste des principales fonctionnalités de DjeShellSteps :

• Tous vos scripts shell peuvent être gérés dans une seule arborescence.
• Interface en ligne de commande commune pour vos scripts shell.
• Permet d'exécuter un script shell étape par étape. En cas de problème, le script peut redémarrer après la dernière étape réussie.
• Méthode de redémarrage facile : le script peut redémarrer depuis le début ou une étape spécifique.
• Facilité pour retrouver les dernières erreurs.
• Toutes les informations écrites sur stdout sont enregistrées dans un fichier de log.
• Seul un résumé de l'exécution peut être affiché sur stdout (ou aucun affichage).
• Le dernier log d'exécution peut être affiché via une commande simple.
• Le script peut être arrêté par une commande unique.
• Vous pouvez vérifier le statut du script en temps réel (via la ligne de commande).
• Gestion simplifiée des fichiers de configuration.
• Pas besoin de se préoccuper du débogage, DjeShellSteps s'en charge.
• Affiche toutes les étapes de votre script depuis la ligne de commande.

Prérequis

DjeShellSteps nécessite un système d'exploitation avec un interpréteur de commandes Bash installé. Certains outils de base du système d'exploitation sont utilisés par DjeShellSteps. Votre système doit disposer des commandes bash et tee.

Fonctionnement

Lorsque vous lancez un script shell avec DjeShellSteps, le programme va :

Créer un fichier de log avec le nom de votre script et la date/heure.
Capturer toutes les sorties vers le fichier de log et stdout (par défaut).
Générer un fichier PID pendant toute l'exécution du script.
Créer un fichier RST (de redémarrage) pendant toute l'exécution du script.
Si aucun problème n'est détecté, les fichiers PID et RST sont supprimés après l'exécution.
En cas de problème, le fichier PID est supprimé, le fichier de log est renommé avec un suffixe « _E », et le fichier RST reste pour vous permettre de relancer le script à partir de la dernière étape échouée.

Supported Operating systems

DjeShellSteps fonctionne sur :

• AIX
• BSD (OpenBSD, FreeBSD)
• Linux
• Solaris
• Windows, en utilisant par exemple http://babun.github.io/.

Installation

Pour installer DjeShellSteps, vous devez décompresser le fichier .tar.gz dans le répertoire de votre choix. Exemple d'installation dans le répertoire /opt/exploitation :

mkdir /opt/exploitation
cd /opt/exploitation
gzip -d /tmp/djeshellsteps.tar.gz
tar xvf /tmp/djeshellsteps.tar
rm /tmp/djeshellsteps.tar

L’arborescence suivante sera créée :

 + opt.
  + exploitation.
   + bin.
    + djeshellsteps.sh.
    + example1.sh.
   + cfg.
    + djeshellsteps.cfg.default
   + data.
   + doc.
   + logs.
   + tmp.

DjeShellSteps est maintenant installé. Veuillez consulter le chapitre suivant pour la configuration.

Configuration

Fichier de configuration de DjeShellSteps

Le fichier djeshellsteps.cfg contient toute la configuration de DjeShellSteps. Par défaut, ce fichier est situé dans le répertoire cfg. Le répertoire bin peut également être utilisé. Pour configurer le fichier pour la première fois, il vous suffit de copier le fichier djeshellsteps.cfg.default en djeshellsteps.cfg.

cd /opt/exploitation/cfg
copy djeshellsteps.cfg.default djeshellsteps.cfg

Fichier de configuration par défaut :

##########################################################
# File:     djeshellsteps.cfg                            #
# Version:  1.00                                         #
# Description:                                           #
#  Configuration file for DjeShellSteps                  #
##########################################################
#Specify bellow all the directories for DjeShellTools
BaseDir=/opt/exploitation                      # Update with your installation path
ShDir=$BaseDir/bin
LogDir=$BaseDir/logs
DataDir=$BaseDir/datas
SQLDir=$BaseDir/sql
IncludeDir=$BaseDir/bin
CfgDir=$BaseDir/cfg
### DjeShellSteps Options ###
DJSOption_StdoutEnabled=1                       # 0: Write only in logfile, 1: Write all informations to log, and stdout
DJSOption_SummaryInfosToStdout=0                # 0: Do nothing, 1: Write summary informations to stdout (better when DJSOption_StdoutEnabled=0)

Écrire le contenu des logs dans Stdout (DJSOption_StdoutEnabled)

Cette variable peut être définie sur 0 ou 1.

Valeur	Description
0	Rien affiché sur Stdout. Le fichier log est utilisé uniquement.
1	Toutes les informations de sortie sont affichées dans le fichier log et dans Stdout.

Écrire des informations de résumé dans Stdout (DJSOption_SummaryInfosToStdout)

Cette variable peut être définie sur 0 ou 1.

Valeur	Description
0	Aucune information de résumé affichée dans stdout.
1	Les informations de résumé sont écrites dans stdout.

Cette option est utilisée si vous ne souhaitez pas que tout le contenu des journaux soit affiché dans stdout, mais uniquement quelques courtes informations pour savoir quand une nouvelle étape commence, si le programme a échoué ou a été redémarré, etc.

Répertoires de DjeShellSteps

bin

Contient DjeShellSteps et vos scripts shell.

cfg

Contient le fichier de configuration de DjeShellSteps et celui de vos scripts shell.

data

Peut être utilisé pour stocker les données de vos scripts.

doc

Manuel de DjeShellSteps

logs

Fichiers journaux pour tous vos scripts shell

tmp

Peut être utilisé pour stocker vos données temporaires (pour vos scripts).

Vos premiers scripts

Ce chapitre contient des scripts simples pour expliquer la méthode de programmation de DjeShellSteps.

Exemple 1 : Premier script avec 3 étapes

Explication du script

Voici un premier exemple de DjeShellSteps qui est simplement un script simple avec trois étapes.

Pour démarrer un script, nous devons commencer par lancer bash en tant que moteur Shell pour notre script.

#!/bin/bash

Ensuite, la meilleure façon de se souvenir de ce que fait le script et qui le fait, est d'ajouter une bannière avec nos informations.

###########################################################
# File: example1.sh                                       #
# Author: Jerome DESMOULINS - djeshellsteps@desmoulins.fr #
# Description:                                            #
#   DjeShellSteps example 1: sample shell script          #
#   with 3 steps.                                         #
###########################################################

Chaque script doit commencer par appeler la bibliothèque principale de DjeShellSteps en utilisant :

. `dirname $0`/djeshellsteps.sh

Cet appel chargera toutes les variables et procédures de DjeShellSteps en mémoire, permettant ainsi d'initialiser les étapes.

La bibliothèque étant chargée, DjeShellSteps doit être initialisé en utilisant :

BeginSteps

Cela initiera DjeShellSteps, créera le fichier .log, le fichier .pid, le fichier de redémarrage .rst et commencera à suivre les commandes.

Nous pouvons maintenant passer à nos étapes. Pour déclarer une étape, il suffit de l'inclure avec un numéro :

Step 10 "List all files on current directory"

Ensuite, nous devons vérifier si cette étape doit être lancée (en fonction du fichier de redémarrage ou des paramètres fournis en ligne de commande) :

if [ $RunThisStep -eq 1 ]; then

Nous y sommes. À partir de là, nous pouvons mettre toutes les commandes que nous souhaitons exécuter, des boucles, des déclarations de variables, .... C'est un script shell ici. Pour cet exemple, nous allons simplement lister les fichiers dans le répertoire courant :

  ls

Ensuite, nous devons terminer l'étape en fermant l'instruction if :

fi

L'étape est maintenant définie. Nous pouvons définir d'autres étapes si nécessaire. Après la dernière étape, il n'est rien à faire. Vous pouvez sauvegarder votre script, lui donner les droits d'exécution et le lancer.

Le code source complet du script

Créez un fichier appelé example1.sh dans le répertoire bin de DjeShellSteps :

#!/bin/bash
###########################################################
# File: example1.sh                                       #
# Author: Jerome DESMOULINS - djeshellsteps@desmoulins.fr #
# Description:                                            #
#   DjeShellSteps example 1: sample shell script          #
#   with 3 steps.                                         #
###########################################################
### Calling DjeShellSteps ###
. `dirname $0`/djeshellsteps.sh
BeginSteps
###########################################################
Step 10 "List all files on current directory"
###########################################################
if [ $RunThisStep -eq 1 ]; then
  ls
fi
###########################################################
Step 20 "Sleep for two seconds"
###########################################################
if [ $RunThisStep -eq 1 ]; then
  sleep 2
fi
###########################################################
Step 30 "Display kernel version"
###########################################################
if [ $RunThisStep -eq 1 ]; then
  uname -a
fi
### End of Shell Script ###
EndSteps

Lancement de votre script

Pour lancer votre script, vous devez rendre votre script exécutable :

chmod 755 example1.sh

Ensuite, il vous suffit de le lancer :

./example1.sh

Votre script sera lancé. Un fichier .log a été généré dans le répertoire logs.

Variables Internes de DjeShellSteps

Spécifier ShellName pour avoir un nom de fichier de log particulier

DjeShellSteps permet de spécifier votre ShellName en tant que variable. Si ShellName est défini, votre script sera appelé par cette valeur, au lieu du nom par défaut (votre script shell, sans extension). Par exemple, si votre shell s'appelle apache_control.sh et que vous souhaitez avoir un fichier de logs appelé apache_*.log, vous devez spécifier :

ShellName=apache

et DjeShellSteps créera des fichiers journaux sous la forme apache_YYYYMMDD_HHMMSS.log.

Message d'aide pour la ligne de commande

DjeShellSteps permet de gérer l'aide en ligne de commande, en utilisant une méthode très simple. Pour ajouter votre message d'aide (paramètres), il vous suffit de remplir la variable $Help au début de votre script shell. Exemple :

Help="<input>;Input file name|<output>;Output file name"

Lorsque vous lancerez votre shell en utilisant le paramètre --help depuis la ligne de commande, deux nouveaux paramètres seront affichés : input et output. Résultat :

$./my_script.sh --help
./my_script.sh                                (powered by DjeShellSteps v1.01)
                                              (c) Jerome DESMOULINS
Usage:
  ./my_script.sh <input> <output>
Where:
     <input>              Input file name
     <output>             Output file name
...
...

Vous pouvez ensuite contrôler si deux paramètres ont été spécifiés en ligne de commande, en utilisant le code suivant :

Help="<input>;Input file name|<output>;Output file name"
### Calling DjeShellSteps ###
. `dirname $0`/djeshellsteps.sh
### Checking parameters ###
if [ $# -ne 2 ]
then
        ShowHelp
fi
...

Dans ce cas, si le script n'est pas lancé avec deux paramètres en ligne de commande, il s'arrêtera et affichera le message d'aide.

Arguments de ligne de commande

Ce chapitre explique tous les arguments de ligne de commande disponibles. Vous pouvez utiliser vos propres arguments de ligne de commande de la même manière que vous gérez les arguments de ligne de commande dans un script shell. DjeShellSteps ajoute des arguments de ligne de commande courants, permettant d'interagir avec un script DjeShellSteps. Les arguments disponibles sont :

• debug
• fromstep
• fromscratch
• help
• lastlog
• kill
• stdout
• stdoutsummary
• liststeps

Activer le mode débogage (debug)

Le paramètre debug activera le mode de débogage. Avec ce mode, toutes les commandes/instructions de votre script shell seront affichées dans le fichier de log. Exemple :

./myshell --debug 

pour activer le mode débogage.

Redémarrer à partir d'une étape particulière (fromstep)

Le paramètre fromstep permet à DjeShellSteps de redémarrer à partir d'une étape spécifiée. Exemple :

./myshell --fromstep 20 

pour redémarrer myshell à partir de l'étape 20.

Aide en ligne de commande (help)

Le paramètre help affichera toutes les options de ligne de commande. Exemple :

./myshell --help

pour afficher toutes les options disponibles (communes et celles de votre shell).

Pour ajouter un message d'aide dans votre shell, référez-vous au chapitre des variables internes.

Redémarrer depuis le début (fromscratch)

Le paramètre fromscratch permet à DjeShellSteps de redémarrer à partir de la première étape. Exemple :

./myshell --fromscratch 

pour redémarrer myshell depuis la première étape.

Ce paramètre est utile si la dernière exécution de votre script a échoué et que vous souhaitez redémarrer depuis le début.

Afficher le contenu du dernier fichier journal (lastlog)

Le paramètre lastlog ne démarrera pas votre script shell. Il affichera simplement le contenu du dernier fichier journal d'exécution et, si disponible, le contenu du fichier de redémarrage. Exemple :

./myshell --lastlog

pour afficher le dernier fichier journal d'exécution.

Ce paramètre est utile si la dernière exécution de votre script a échoué et que vous souhaitez afficher le dernier fichier journal.

Terminer un script en cours d'exécution (kill)

L'option kill mettra fin à l'exécution de votre script. Il sera arrêté, et un fichier de redémarrage sera créé avec l'étape actuelle. Lorsque vous tenterez de relancer votre script, il commencera à partir de la dernière étape d'exécution. Exemple :

./myshell --kill

pour terminer l'exécution de votre script.

Ce paramètre est utile si votre shell est bloqué ou gelé (fonction principalement utilisée à des fins de développement).

Forcer la sortie vers stdout (stdout)

L'option stdout forcera le script shell à afficher toutes les informations sur stdout. Le fichier journal sera écrit dans tous les cas. Exemple :

./myshell --stdout

pour forcer la sortie complète vers stdout (et garder le fichier journal).

Ce paramètre est utile lorsque vous souhaitez lancer un travail manuellement si l'option DJSOption_StdoutEnabled est définie sur 0.

Forcer la sortie résumée vers stdout (stdoutsummary)

L'option stdoutsummary forcera le script shell à afficher des informations résumées sur stdout. Cette option devrait être utilisée lorsque l'option DJSOption_StdoutEnabled est définie sur 0, mais que vous souhaitez avoir des informations minimales sur l'exécution de votre shell dans stdout. Exemple :

./myshell --stdoutsummary

pour forcer les informations résumées sur stdout (et garder le fichier journal).

Ce paramètre est utile lorsque vous souhaitez lancer un travail manuellement si l'option DJSOption_StdoutEnabled est définie sur 0.

Lister toutes les étapes du shell (liststeps)

L'option liststeps affichera toutes les étapes du shell. Cette option doit être utilisée par l'opérateur pour comprendre ce que fait le shell en cas de problèmes, savoir ce qui a été fait lors de la dernière exécution, et ce qu'il faut faire lorsqu'il sera redémarré. Exemple :

./myshell --liststeps

pour lister toutes les étapes du shell.

Ce paramètre est utile en mode opérationnel. Exemple :

./myshell --liststeps
Steps for myshell:
  -Step 10:   Checking for new invoice file
  -Step 20:   Converting file from CSV to JSON
  -Step 30:   Moving converted file to destination folder

Fichier de configuration pour votre script shell

Votre script shell peut utiliser un fichier de configuration. Pour utiliser cette fonctionnalité, vous devez créer un fichier de configuration dans le répertoire de configuration de DjeShellSteps. Toutes les variables du fichier de configuration peuvent être lues, et vous pouvez les utiliser directement dans votre script shell.

Pour lire votre fichier de configuration, vous devez utiliser la fonction ReadConfigFile.

Exemple :

ReadConfigFile 

pour lire le contenu de votre fichier de configuration de script shell et charger les variables dans votre shell. Toutes les variables de configuration seront disponibles après avoir utilisé ReadConfigFile.

Pour lire un autre fichier de configuration que celui de votre shell, vous pouvez spécifier son nom en appelant la fonction.

Exemple :

ReadConfigFile my_configuration_file.cfg

pour lire le contenu de ce fichier de configuration particulier et charger les variables dans votre shell.

Vous pouvez mettre des commentaires dans votre fichier de configuration. Toutes les variables doivent être définies selon la méthode suivante :

YourVariable=VariableValue

Exemple de fichier de configuration :

###########################################################
# File: example2.cfg                                      #
# Author: Jerome DESMOULINS - djeshellsteps@desmoulins.fr #
# Description:                                            #
#   DjeShellSteps example 2: sample configuration file    #
###########################################################
TmpDir=/tmp

Méthodes de travail

Ce chapitre décrit quelques méthodes de travail avec DjeShellSteps.

Sortir de DjeShellSteps avant la fin du script

Sortir et générer une erreur

Pour sortir et générer une erreur dans DjeShellSteps, il vous suffit d'utiliser la commande de sortie système. Exemple :

exit 1

Mettra fin à l'exécution de votre script shell, générera un fichier de redémarrage à l'étape actuelle. Votre script redémarrera à partir de cette étape lors de la prochaine exécution.

Sortir sans erreur

Pour sortir de DjeShellSteps sans générer d'erreur, vous pouvez utiliser le code suivant. Exemple :

# Force DjeShellSteps to terminate without playing next steps
EndSteps
exit 1

DjeShellSteps se terminera sans générer de fichier de redémarrage. La prochaine exécution commencera à partir de la première étape.

Codes d'erreur de DjeShellSteps

Ce chapitre contient tous les codes d'erreur internes de DjeShellSteps.

Code d'erreur	Explication
501	Échec de l'écriture du contenu du fichier de redémarrage. DjeShellSteps a échoué à écrire le contenu dans le fichier de redémarrage. Vérifiez les droits du fichier .rst.
502	Échec de la suppression du fichier de redémarrage. DjeShellSteps a échoué à supprimer le fichier .rst. Vérifiez les droits du fichier .rst.
503	Échec de l'écriture du fichier log. DjeShellSteps a échoué à écrire le contenu du fichier log. Vérifiez les droits du répertoire de log pour l'utilisateur qui lance votre script shell.
504	Une autre instance de votre script shell est déjà en cours d'exécution. Vérifiez le PID dans your_script.pid pour le confirmer. Si rien ne fonctionne et que le fichier PID est toujours là, vous pouvez le supprimer (cela ne devrait pas arriver, car DjeShellSteps supprime le fichier PID après l'exécution du script shell).
505	Échec de l'écriture du fichier PID. DjeShellSteps écrit un fichier avec le nom de votre script suivi de .pid, pour éviter plusieurs lancements du même script en même temps. DjeShellSteps n'a pas pu écrire your_script.pid dans le répertoire de log. Vérifiez les droits du répertoire de log.
506	Échec de la suppression du fichier PID. DjeShellSteps n'a pas pu supprimer your_script.pid dans le répertoire de log. Vérifiez les droits du répertoire de log.

Retour