diff --git a/README.md b/README.md index c1ac79d..fb62bfe 100755 --- a/README.md +++ b/README.md @@ -192,9 +192,9 @@ Note : Les lignes commençant par 2 "#" sont utilisées pour générer l'aide, l pour garantir la fiabilité de l'information. Ce sont ces lignes, qui sont lues lors de l'utilisation de l'option par defaut "-h". -### 1.1 Elements du cartouche +#### 1.1 Elements du cartouche -#### 1.1.1 Meta-données +##### 1.1.1 Meta-données : peut prendre les valeurs suivantes -> cre, ano, evo, typo * cre : Création du script. @@ -207,7 +207,7 @@ l'option par defaut "-h". : Format x.y.z Pour le suivi des versions on utilisera le versionnement sémantique (voir paragraphe III-1.2). -#### 1.1.2 Paragraphe +##### 1.1.2 Paragraphe * Mise a jour : Ce paragraphe est utilisé pour suivre l'evolution des versions. La dernière version en vigueur doit être reportée dans le premier paragraphe. @@ -222,7 +222,9 @@ Si aucune déclaration n'est présente alors la bibliothèque params.lib ne fait Dans ce cas les options par défaut -h, -log, -hist, -cpt, -s et -dbg ne seront pas disponible. Si le script ne nécessite pas d'option mais que l'on souhaite disposer des options par défaut, il -faudra déclarer une option bidon. ex: "# @OPT: f:bidon::::::" +faudra déclarer une option bidon. + + # @OPT: f:bidon:::::: Si la déclaration existe alors le socle gèrera les paramètres en entrée du script, ainsi que les options par défaut -h, -log, -hist, -cpt, -s et -dbg. Ces mots clé sont reservés et ne @@ -232,9 +234,10 @@ La déclaration est réalisée dans le paragraphe "Liste des options et argument option est identifiée par l'entête de ligne "# @OPT:" suivi de la description. La description consiste en une liste de paramètres séparés par ":" + ::::::: -L'ordre des paramètre est figé et tous doivent etre présents. +L'ordre des paramètres est figé et tous doivent etre présents. 8 champs sont obligatoires, soit 7 caracteres ":" (on ne compte pas le caracatere ":" suivant @OPT). Exemple de déclaration valide : @@ -298,486 +301,253 @@ Les options par défaut réalisent les actions suivantes : -dbg N : Activation du mode debug au niveau "N". Active les messages gérés par la librairie fct_message dont l'option -debug est utilisée. -* Arguments : La declaration des argument du script n'est pas obligatoire - Attention : Si aucune option "@OPT:" n est declaree alors il n y auras pas de prise en charge des arguments. - Si votre script ne necessite pas d option, mais qu il presente des arguments, alors il faudras declarer - une option bidon :"# @OPT: f:bidon::::::" +* Arguments : La déclaration des argument du script n'est pas obligatoire - La declaration est realise dans le paragraphe "Liste des options et arguments". - Elle est identifiee par l entete de ligne "# @ARG:" suivi de la description. - Il ne peut y avoir qu une ligne de description pour les arguments. - (Si plusieurs lignes avec le marqueur @ARG existe, alors seul la premiere et prise en compte) +Attention : Si aucune option "@OPT:" n'est déclarée alors il n y aura pas de prise en charge des arguments. +Si votre script ne nécessite pas d'option, mais qu'il presente des arguments, il faudra alors déclarer une +option bidon : - La description consiste en une liste de parametres separes par ":" - :::: + # @OPT: f:bidon:::::: - L ordre des parametres est fige et tous doivent etre presents. +La déclaration est réalisé dans le paragraphe "Liste des options et arguments". +Elle est identifiée par l'entête de ligne "# @ARG:" suivi de la description. - : Propriete de l attribu defini par l agregation des lettres suivantes - f -> Argument falcultative - o -> Argument obligatoire - M -> Argument transforme en majuscule +Il ne peut y avoir qu'une ligne de description pour les arguments. (Si plusieurs lignes avec le +marqueur @ARG existent, alors seule la premiere est prise en compte). - : nom de la variable dans laquelle sera stockee le(s) argument(s) - si plusieurs arguments alors un tableau sera initialise - L index [n] commence a zero. - Le nombre d arguments effectivement passes a la commande est "${#[*]}". - L valeur max de l index [n] est "${#[*]} - 1". +La description consiste en une liste de paramètres séparés par ":" - Si n est pas renseigne alors la variable SH\_ARGS[] est initialisee + :::: - : nombre d arguments attendus de la forme "min/max", "min/", "max" ou "". - si vide alors on considere que le nombre d arguments est a minima de 1. - la forme "min/" considere le nombre est a minima de "min". +L'ordre des paramètres est figé et tous doivent être présents. - : Valeur par defaut assignee a - Fonctionne si vaut 0/1 1/1 + * : Propriéte de l'attribu défini par l'aggrégation des lettres suivantes: -ATTENTION - Si le caractere "&" est present dans la valeur d un argument, alors cette valeur doit etre encadree - par une simple cote et le caractere "&" doit etre proteger par un anti-slash "\". + f -> Argument falcultative + o -> Argument obligatoire + M -> Argument transforme en majuscule - Le cas echeans le shell generera un fils qui tentera l execution d'un script portant le nom de la valeur de l argument. + * : nom de la variable dans laquelle sera stockée le(s) argument(s) +si plusieurs arguments alors un tableau sera initialisé +L'index [n] commence a zero. +Le nombre d'arguments effectivement passés à la commande est "${#[*]}". +La valeur max de l'index [n] est "${#[*]} - 1". -1.2 Versionnement semantique - 1.2.1 Usage - L idee de l utilisation du versionnement semantique est de definir clairement les intentions - d un changement dans un code pour les clients de ce dernier. Ceci permet de fiabiliser la mise en - place de dependances et de determiner les impacts d un changement. +Si n'est pas renseigné alors la variable SH\_ARGS[] est initialisée - 1.2.2 Format - Le format utilise est le suivant x.y.z - x est l identifiant de version majeure. - y est l identifiant de version mineure. - z est l identifiant de version de correction. + * : nombre d'arguments attendus de la forme "min/max", "min/", "max" ou "". +si vide alors on considère que le nombre d'arguments est a minima de 1. +la forme "min/" considère le nombre est a minima de "min". + + * : Valeur par défaut assignée a +Fonctionne si vaut 0/1 1/1 + +ATTENTION: +Si le caractère "&" est présent dans la valeur d'un argument, alors cette valeur doit être encadrée +par une simple quote et le caractère "&" doit être protégé par un anti-slash "\". + +Dans le cas contraire le shell génèrera un fils qui tentera l'execution d'un script portant le nom de la valeur +de l'argument. + +#### 1.2 Versionnement sémantique + +##### 1.2.1 Usage + +L'idée de l'utilisation du versionnement sémantique est de définir clairement les intentions +d'un changement dans un code pour les clients de ce dernier. Ceci permet de fiabiliser la mise en +place de dépendances et de déterminer les impacts d'un changement. + +##### 1.2.2 Format + +Le format utilisé est le suivant: X.Y.Z + +* X est l'identifiant de version majeure. +* Y est l'identifiant de version mineure. +* Z est l'identifiant de version de correction. - 1.2.3 Semantique - - Version majeure X : Il vaut "0" lors du developpement, le script est considere non valide et ne - devrait pas etre appele par d autre script. Une fois le script valide la version - doit etre 1.0.0 (premiere version stable). - Il doit etre incremente si des changements dans le code n assure plus la compatibilite - ascendante. Les identifiants de version mineure et de correction doivent etre remis - a zero quand l identifiant de version majeure est incremente. +##### 1.2.3 Sémantique - - Version mineur y : Doit etre incremente lors de l ajout de nouvelle fonctionnalite ou d amelioration - du code qui n on t pas d impact sur la compatibilite ascendante. L identifiant de - version de correction doit être remis a zero lorsque l identifiant de version mineure - est incremente. +* Version majeure X : Il vaut "0" lors du développement, le script est considéré non valide et ne +devrait pas être appelé par d'autres scripts. Une fois le script valide la version doit etre 1.0.0 +(première version stable). - - Version de correction z : Doit être incremente si seules des corrections retro-compatibles sont introduites. - Une correction est definie comme un changement interne qui corrige un comportement incorrect. - Il peut etre incremente lors de correction typographique ou grammaticale. +Il doit etre incrementé si des changements dans le code n'assure plus la compatibilité ascendante. +Les identifiants de version mineure et de correction doivent etre remis à zero quand l'identifiant +de version majeure est incrementé. + +* Version mineur Y : Doit être incrementé lors de l'ajout de nouvelles fonctionnalités ou d'amélioration +du code qui n'ont pas d'impact sur la compatibilité ascendante. L'identifiant de version de correction doit +être remis a zero lorsque l'identifiant de version mineure est incrementé. + +* Version de correction Z : Doit être incrementé si seules des corrections rétro-compatibles sont introduites. +Une correction est définie comme un changement interne qui corrige un comportement incorrect. +Il peut être incrementé lors de correction typographique ou grammaticale. - 2 - Initialisation du socle. - Par defaut les librairies du socle sont chargees a la connexion. Mais pour qu elles puissent etre operationnelles - il faut initialiser les variables de session. - Ceci est realise en sourcant le fichier "${NC\_EXPL\_CFG}/init.conf" au debut du script : +### 2 - Initialisation du socle - Rem : L analyse des options et arguments est aussi realise par "${NC\_EXPL\_CFG}/init.conf". +Par défaut les bibliothèques du socle sont chargées à la connexion. Mais pour qu'elles puissent être operationnelles +il faut initialiser les variables de session. - +----------------------------------------------------------------------------------------------------+ - | | - | #!/bin/bash | - | ##---------------------------------------------------------------------------- | - | . | - | | - | . | - | ##---------------------------------------------------------------------------- | - | #----------------------------------------------------------------------------- | - | # Initialisation de l environement | - | #----------------------------------------------------------------------------- | - | if [ ! -f ${NC\_EXPL\_CFG}/init.conf ] | - | then | - | echo "Fichier d initialisation du socle \${NC\_EXPL\_CFG}/init.conf n existe pas !" | - | echo "Arret du script par securite" | - | exit 250 | - | else | - | . ${NC\_EXPL\_CFG}/init.conf | - | fi | - | . | - | . | - | | - +----------------------------------------------------------------------------------------------------+ +Ceci est réalisé en sourcant le fichier "${NC\_EXPL\_CFG}/init.conf" au debut du script : - 3 - Structure d un script - Voici les elements qui devraient etre present a minima dans les script Bash. Ceci est recommande pour - assurer une homogeneite dans l ensemble du socle. +Remarque: L'analyse des options et arguments est aussi réalisée par "${NC\_EXPL\_CFG}/init.conf". - +----------------------------------------------------------------------------------------------------+ - | | - | #!/bin/bash | - | ##---------------------------------------------------------------------------- | - | . | - | | - | . | - | ##---------------------------------------------------------------------------- | - | #----------------------------------------------------------------------------- | - | # Initialisation de l environement | - | #----------------------------------------------------------------------------- | - | if [ ! -f ${NC\_EXPL\_CFG}/init.conf ] | - | then | - | echo "Fichier d initialisation du socle \${NC\_EXPL\_CFG}/init.conf n existe pas !" | - | echo "Arret du script par securite" | - | exit 250 | - | else | - | . ${NC\_EXPL\_CFG}/init.conf | - | fi | - | | - | #----------------------------------------------------------------------------- | - | # Definition des fonctions | - | #----------------------------------------------------------------------------- | - | # | - | function fct\_un | - | { ... | - | } | - | | - | #----------------------------------------------------------------------------- | - | function fct\_deux | - | { ... | - | } | - | | - | #----------------------------------------------------------------------------- | - | # Programme principal MAIN | - | #----------------------------------------------------------------------------- | - | # | - | fct\_message "${SH\_PROG}" | - | fct\_message "version ${SH\_PROG\_VERSION}" | - | | - | # -- Initialisation des variables par defaut | - | # -- --------------------------------------- | - | G\_VAR1=${G\_AVR1:="Valeur par defaut"} # | - | ... | - | | - | # -- Control de coherence des options | - | # -- -------------------------------- | - | | - | # -- Traitement | - | # -- ---------- | - | | - | < ... Code du script ...> | - | | - | fct\_erreur 0 | - | | - +----------------------------------------------------------------------------------------------------+ + +----------------------------------------------------------------------------------------------------+ + | | + | #!/bin/bash | + | ##---------------------------------------------------------------------------- | + | . | + | | + | . | + | ##---------------------------------------------------------------------------- | + | #----------------------------------------------------------------------------- | + | # Initialisation de l environement | + | #----------------------------------------------------------------------------- | + | if [ ! -f ${NC_EXPL_CFG}/init.conf ] | + | then | + | echo "Fichier d initialisation du socle ${NC_EXPL_CFG}/init.conf n existe pas !" | + | echo "Arret du script par securite" | + | exit 250 | + | else | + | . ${NC_EXPL_CFG}/init.conf | + | fi | + | . | + | . | + | | + +----------------------------------------------------------------------------------------------------+ - Note : La construction /G\_VAR1=${G\_AVR1:="Valeur par defaut"}/ permet de definir une variable avec une - valeur par defaut, qui peut etre surchargee dans le fichier de configuration {NC\_EXPL\_CFG}/.conf - Concernant les fonctions /fct\_message/ et /fct\_erreur/ voir le chapitre V. +### 3 - Structure d'un script - 4 - Actions realisees au lancement d un script - Le script commence par le chargement de la configuration ". ${NC\_EXPL\_CFG}/init.conf" - un certain nombre d action sont effectuees par defaut en plus de l initialisation des variables de session. +Voici les éléments qui devraient être présents a minima dans les script Bash. Ceci est recommandé pour +assurer une homogénéite dans l'ensemble du socle. + + +----------------------------------------------------------------------------------------------------+ + | | + | #!/bin/bash | + | ##---------------------------------------------------------------------------- | + | . | + | | + | . | + | ##---------------------------------------------------------------------------- | + | #----------------------------------------------------------------------------- | + | # Initialisation de l environement | + | #----------------------------------------------------------------------------- | + | if [ ! -f ${NC_EXPL_CFG}/init.conf ] | + | then | + | echo "Fichier d initialisation du socle ${NC_EXPL_CFG}/init.conf n existe pas !" | + | echo "Arret du script par securite" | + | exit 250 | + | else | + | . ${NC_EXPL_CFG}/init.conf | + | fi | + | | + | #----------------------------------------------------------------------------- | + | # Definition des fonctions | + | #----------------------------------------------------------------------------- | + | # | + | function fct_un | + | { ... | + | } | + | | + | #----------------------------------------------------------------------------- | + | function fct_deux | + | { ... | + | } | + | | + | #----------------------------------------------------------------------------- | + | # Programme principal MAIN | + | #----------------------------------------------------------------------------- | + | # | + | fct_message "${SH_PROG}" | + | fct_message "version ${SH_PROG_VERSION}" | + | | + | # -- Initialisation des variables par defaut | + | # -- --------------------------------------- | + | G_VAR1=${G_AVR1:="Valeur par defaut"} # | + | ... | + | | + | # -- Control de coherence des options | + | # -- -------------------------------- | + | | + | # -- Traitement | + | # -- ---------- | + | | + | < ... Code du script ...> | + | | + | fct_erreur 0 | + | | + +----------------------------------------------------------------------------------------------------+ + +Note : La construction /G\_VAR1=${G\_AVR1:="Valeur par défaut"}/ permet de définir une variable avec une +valeur par défaut, qui peut être surchargée dans le fichier de configuration {NC\_EXPL\_CFG}/.conf + +Concernant les fonctions /fct\_message/ et /fct\_erreur/ voir le chapitre V. + + +### 4 - Actions réalisées au lancement d un script + +Le script commence par le chargement de la configuration ". ${NC\_EXPL\_CFG}/init.conf" +un certain nombre d'actions sont effectuées par défaut en plus de l'initialisation des variables de session. + +* Initialisation des variables de session (Cf. II.3) +* Génération d'un numéro de session unique sous la varable ${SH\_SESSION\_ID} +* Chargement du fichier ${SH\_FICCFG} +* Rotation des fichiers ${SH\_FICLOG} et ${SH\_FICCPT} selon les rétentions respective ${SH\_RETENTION\_LOG} et ${SH\_RETENTION\_CPT} +* Purge des fichiers temporaires (${NC\_EXP\_ROOT}/tmp) antérieurs selon la retentions ${SH\_RETENTION\_LOG} et +suppression des fichiers générés par le script utilsant le socle dans ${NC\_EXP\_ROOT}/log et ${NC\_EXP\_ROOT}/cpt +* Ecriture dans le fichier ${SH\_FICTRC} de la date de début exécution ainsi que les arguments passés au script +* Initialisation du fichier ${SH\_FICLOG} à vide +* Analyse des paramètres passés au script + +Cette analyse ne fonctionne que si les options ont été déclarées dans l'entête du script (Cf. III.1.1.2) + + + +## IV - Nomenclature + +### 1 - Fichiers temporaires + +Les fichiers temporaires doivent etre écrits dans le répertoire ${NC\_EXPL\_TMP}. +Les noms des fichiers temporaires sont de la forme : \_${SH\_SESSION\_ID}.tmp +De cette facon il seront gérés par le socle (Suppresion automatique). + +### 2 - Nom des exécutables (fichiers du dossier ${EXPL\_ROOT}/bin ) + +Les noms des fichiers doivent être de la forme : + + 
_
+    
_.
+    
__[_].
+    _.
+
+* 
 : est une des valeurs suivantes : "sys", "dba", "exp", "ctl", "aud", "int"
+  * "sys" : Scrits d'administration système.
+  * "dba" : Scripts d'administration base de données
+Ces scripts peuvent présenter des risques et doivent faire l'objet d'une attention particulière
+lors de leurs exécution.
+  * "exp" : Scripts d'exploitation dévolus principalement aux traitements réccurents
+Ces scripts sont réservés à l'exploitation courante. Il peuvent modifier le système dans le cadres de
+traitements réccurents.
+Leurs exécution est de risque modére, comme respecter une date d'execution.
+Il sont reservés à l'exploitation système uniquement.
+Dans le cas d'un traitement réccurrent pour le compte d'une application le nom doit
+être de la forme \_.
+  * "int" : Scripts dédiés aux interfaces entre applications
+Ces scripts doivent faire l'objet d'une attention particulière car il peuvent modifier
+les données applicatives et peuvent être contraints par des conditions d'execution.
+  * "ctl" : Script de contrôle (dévolu principalement au système de monitoring)
+  * "aud" : Script d'audit ne modifiant pas le système.
+Ces scripts peuvent être executés sans aucun risque.
+
+*  est libre, doit refléter si possible la fonction du script.
+
+*  est une des valeurs suivantes :
+
+    "sh" : Script Bash.
     
-          - Initialisation des variables de session (Cf. II.3)
-
-          - Generation d'un numero de session unique sous la varable ${SH\_SESSION\_ID}
-
-          - Chargement du fichier ${SH\_FICCFG}
-          
-          - Rotation des fichiers ${SH\_FICLOG} et ${SH\_FICCPT} selon les retentions respective ${SH\_RETENTION\_LOG} et ${SH\_RETENTION\_CPT}
-          
-          - Purge des fichiers temporaires (${NC\_EXP\_ROOT}/tmp) anterieurs selon la retentions ${SH\_RETENTION\_LOG}
-            et suppression des fichiers generes par le script utilsant le socle dans ${NC\_EXP\_ROOT}/log et ${NC\_EXP\_ROOT}/cpt
-          
-          - Ecriture dans le fichier ${SH\_FICTRC} de la date de debut execution, ainsi que des arguments passes au script
-          
-          - Initialisation du fichier ${SH\_FICLOG} a vide
-
-          - Analyse des parametres passes au script
-            Cette analyse ne fonctionne que si les options ont ete declarees dans l entete du script (Cf. III.1.1.2)
-
-
-
-IV  - Nomenclature
-      ------------
-      1 - Fichier temporaire
-          Les fichiers temporaires doivent etre ecrits dans le repertoire ${NC\_EXPL\_TMP}.
-          Les noms des fichiers temporaires sont de le forme : \_${SH\_SESSION\_ID}.tmp
-          De cette facon il seront geres par le socle (Suppresion automatique)
-
-      2 - Nom des executables ( fichiers du dossier {racine}/bin )
-          Les noms des fichiers doit etre de la forme :
-            
\_
-            
\_.
-            
\_\_[\_].
-            \_.
-
-          
      est une des valeurs suivantes : "sys", "dba", "exp", "ctl", "aud", "int"
-
-                     - "sys" : Scrit d administration systeme.
-                     - "dba" : Script d administration base de donnees
-                     Ces scripts peuvent presenter des risques et doivent faire 
-                     l objet d une attention particuliere lors de leurs execution.
-
-                     - "exp" : Script d exploitation devolue principalement au traitement reccurent
-                     Ces scripts sont reserves a l'exploitation courante. Il peuvent 
-                     modifier le systeme dans le cadres de traitements reccurents.
-                     Leurs execution est de risque modere, comme respecter une date d execution.
-                     Il sont reserves a l exploitation systeme uniquement. Dans le cas d un traitement
-                     reccurrent pour le compte d une application le nom doit etre de la forme \_.
-
-                     - "int" : Script dedier aux interfaces entre applications
-                     Ces script doivent fair l objet d une attention particuliere car il peuvent modifier
-                     les donnees applicative et peuvent etre contraint par des conditions d execution.
-
-                     - "ctl" : Script de controle (devolu principalement a icinga)
-                     - "aud" : Script d audit ne modifiant pas le systeme.
-                     Ces scripts peuvent etre executes sans aucun risque.
- 
-              est libre, doit refleter si possible la fonction du script.
-          
-           est une des valeurs suivantes :
-                      - "rb"            : Script Ruby.
-                      - "sh"            : Script Bash.
-                      - Pas d extention : Script C
-          
-                est le nom de  application a laquelle le script est dedie.
-                     Ces scripts sont reserves a une application particuliere, 
-                     dans le cadres de l exploitation reccurente de l'application.
-
-
-V   - Description et usage des Librairies
-      -----------------------------------
-    1 - fct\_message
-    --- -----------
-
-        Syntaxe  : fct\_message [-cpt] [-hist] [-nolog] [-debug N] [-color Couleur] ""
-        Usage    : Cette fonction est a utiliser en remplacement de la commande "echo".
-                   Elle ajoute l horadatage au message et gere la ventilation des ecritures dans les differents fichiers de traces.
-
-        Fonction : Par defaut le message est affiche sur le terminal et est ecrit dans le fichier journal ${NC\_EXPL\_LOG}/.log
-                   Les options modifient la destination de l ecriture :
-                   - cpt     : Ecrit en plus du journal dans le fichier de compte-rendu ${NC\_EXPL\_CPT}/.cpt
-                   - hist    : Ecrit uniquement dans le fichier d historique des executions ${NC\_EXPL\_TRC}/.hist
-                   - nolog   : inhibe l ecritutre dans le fichier journal
-                   - debug N : N'affiche pas le message sur le terminal mais uniquement dans le fichier journal, a condition
-                               que le script soit execute en mode debug de niveau equivalent a "N" via l'option "-dbg N".
-                               Par defaut le niveau de debug est 0, ainsi si "N" vaut zero alors le message est ecrit 
-                               uniquement dans le fichier journal.
-                   - color   : Affiche le message en couleur. Les couleurs reconues sont : vert,rouge,bleu,cyan,jaune,orange,blanc et noir
-
-
-    2 - fct\_affiche\_ligne
-    --- -----------------
-
-       Syntaxe  : fct\_affiche\_ligne [entete|pied] 
-       Usage    : Affiche un tableau sur la sortie standard et dans le fichier compte-rendu ${NC\_EXPL\_ROOT}/