L'écran Scripts de Portail ZAPP (menu Administration › Connecteurs et automatisation › Scripts) tient le registre des scripts d'administration que l'on peut ensuite exécuter sur le serveur ou sur des machines équipées d'un agent Outpost. Il est réservé aux Administrateurs.
La liste des scripts
Chaque script affiche son Nom, son Moteur, son Ciblage, son Auteur et la date de Dernière modification (celle de sa version la plus récente). Tapez une partie du nom dans Rechercher, puis Filtrer ; Réinitialiser revient à la liste complète. Cliquez sur une ligne pour ouvrir le script.
Créer un script
Créer un script demande :
- Nom et Description. Le nom est unique : deux scripts ne peuvent pas porter le même nom, sans tenir compte des majuscules, des accents ni des espaces au début et à la fin (« Purge temp » et « purge TEMP » sont le même nom) ;
- Moteur : Windows PowerShell 5.1, PowerShell 7 (pwsh), Bash, sh (POSIX) ou Shebang (#!). Choisissez un moteur disponible sur les machines visées ;
- Ciblage : Local uniquement (sur le serveur), Outposts uniquement (sur des agents) ou Local et Outposts. Un script ne peut pas être lancé sur une cible que son ciblage exclut ;
- Timeout par défaut (secondes) : au-delà, l'exécution est arrêtée et passe à l'état Expirée (timeout). Laissé vide, il vaut 300 secondes ; 24 heures (86 400 secondes) au plus ;
- Nombre de tentatives par défaut : la valeur est enregistrée, mais elle n'entraîne aujourd'hui aucune nouvelle tentative automatique ; 10 au plus ;
- Contenu : le texte du script, 2 Mo au plus (2 097 152 octets une fois encodé en UTF-8 ; une lettre accentuée compte deux octets). La même limite vaut pour chaque nouvelle version ;
- Paramètres (facultatif) : Ajouter un paramètre pour chaque valeur demandée au lancement.
Pour chaque paramètre, indiquez son Nom, son Type (String, Integer, Boolean ou Enum), s'il est Requis, son Ordre d'affichage et, selon le type, une Regex de validation, un Min et un Max, ou des Valeurs autorisées séparées par des virgules (obligatoires pour un Enum). Les valeurs saisies au lancement sont contrôlées avec ces règles.
Créer enregistre le script et sa version 1. Après la création, le nom, la description, le moteur, le ciblage, le timeout et le seuil de confirmation ne se modifient ni depuis l'écran ni par l'API : une nouvelle version ne change que le contenu et les paramètres. Une mise en service (GOLIVE) les recopie en revanche depuis l'instance source. Le seuil de confirmation d'un lancement sur un groupe de machines vaut 25 machines ; seule la création par l'API (POST /api/v1/scripts, champ groupConfirmationThreshold) permet d'en fixer un autre.
Utiliser un secret
Ne collez jamais un mot de passe dans un script : référencez un secret du module Secrets avec la syntaxe {{secret:nom-du-secret}}. La valeur est insérée au moment de l'exécution ; elle n'est ni enregistrée dans le script ni conservée dans l'historique. Pour une exécution sur une machine distante, la commande en attente d'envoi est chiffrée en base, puis effacée dès que l'exécution est terminée. Attention : si le script affiche lui-même le secret (par exemple en écrivant ses variables), la valeur apparaît dans la sortie de l'exécution. Une référence mal écrite est refusée à l'enregistrement. Si le secret n'existe pas ou si le module Secrets n'est pas activé, l'exécution est refusée.
Versions
La fiche d'un script liste ses Versions (numéro, auteur, date). Cliquez sur une version pour afficher son Contenu et ses Paramètres.
Nouvelle version reprend le contenu et les paramètres de la dernière version ; modifiez-les puis Créer. Une version enregistrée n'est plus modifiable : chaque changement crée une nouvelle version, ce qui garde la trace de ce qui a été exécuté. Une nouvelle version est utilisable aussitôt, sans étape d'approbation.
Depuis la version affichée, Exécuter lance le script et Historique montre ses exécutions (voir « Exécuter un script »). Vous pouvez ainsi relancer une version antérieure.
Autorisation par cible
La section Autorisation par cible décide qui peut lancer ce script sur quels agents Outpost. Chaque règle associe un Rôle (un groupe d'utilisateurs) à un Groupe de machines (défini dans le module Agents Outpost). Choisissez les deux, puis Ajouter ; Supprimer retire une règle.
- Sans aucune règle, le script ne peut être lancé sur aucun agent distant.
- Pour lancer le script sur un agent, il faut appartenir à un groupe d'une règle dont le groupe de machines contient cet agent. Un agent qui n'appartient à aucun groupe de machines ne peut recevoir aucun script.
- Ces règles ne concernent pas l'exécution locale sur le serveur.
Quand le module Agents Outpost n'est pas activé, la section l'indique et aucune règle ne peut être ajoutée.
Dépannage : création refusée
Quand Créer refuse un script ou une nouvelle version, l'écran l'explique dans votre langue au-dessus du formulaire et garde tout ce que vous avez saisi : corrigez puis enregistrez de nouveau. L'API (POST /api/v1/scripts, POST /api/v1/scripts/{id}/versions) répond 400 (404 pour un script supprimé, ScriptNotFound) avec le code stable (error), une phrase en anglais (message), la clé de traduction (messageKey) et ses valeurs (parameters). Le message technique reste dans le journal du serveur. Par l'API, un champ obligatoire absent ou vide (nom, contenu, nom d'un paramètre) ou une valeur d'énumération inconnue sous forme de texte est refusé avant, par la validation standard de l'API (400 au format ProblemDetails).
| Code | Cause | Que faire |
|---|---|---|
ScriptNameRequired |
Le nom est vide | Donner un nom au script |
ScriptContentRequired |
Le contenu est vide | Écrire le script |
UnknownScriptEngine |
Le moteur reçu par l'API n'existe pas | Choisir un moteur de la liste (GET /api/v1/scripts/engines) |
UnknownTargetScope |
Le ciblage reçu par l'API n'existe pas | LocalOnly, AgentsOnly ou Both |
InvalidDefaultTimeout |
Le timeout par défaut est inférieur à 1 seconde | Saisir 1 seconde ou plus, ou laisser vide |
DefaultTimeoutAboveMaximum |
Le timeout par défaut dépasse 24 heures (86 400 secondes) | Saisir 86 400 secondes ou moins |
InvalidDefaultRetryCount |
Le nombre de tentatives est négatif | Saisir 0 ou plus |
DefaultRetryCountAboveMaximum |
Le nombre de tentatives dépasse 10 | Saisir 10 ou moins |
InvalidGroupConfirmationThreshold |
Le seuil de confirmation (API) est négatif | Saisir 0 ou plus |
DuplicateScriptName |
Un autre script porte déjà ce nom (majuscules, accents et espaces de bord ignorés) ; deux créations simultanées du même nom : la seconde reçoit ce refus | Choisir un autre nom |
ScriptContentTooLarge |
Le contenu dépasse 2 Mo (taille et maximum affichés, en octets) | Alléger le script, ou placer les données volumineuses dans un fichier lu par le script |
MalformedSecretReference |
Une référence de secret est mal écrite | Écrire {{secret:nom-du-secret}} |
ParameterNameRequired |
Une ligne de paramètre n'a pas de nom | Nommer le paramètre ou supprimer la ligne |
DuplicateParameterName |
Deux paramètres portent le même nom (nom affiché) ; pour PowerShell, majuscules et minuscules comptent pour la même lettre | Garder une seule ligne par nom |
InvalidParameterRegex |
La regex de validation du paramètre (nom affiché) est invalide | Corriger l'expression régulière |
InvalidParameterBounds |
Le Min du paramètre (nom affiché) dépasse son Max | Inverser ou corriger les bornes |
EnumParameterWithoutValues |
Un paramètre Enum (nom affiché) n'a aucune valeur autorisée |
Saisir les valeurs séparées par des virgules |
ScriptNotFound |
Le script a été supprimé pendant la saisie d'une nouvelle version : l'écran l'explique sans reproposer le formulaire, l'API répond 404 |
Retour à la liste des scripts |
VersionConflict |
D'autres versions du même script étaient enregistrées au même moment, plusieurs fois de suite ; l'API répond 409 |
Enregistrer de nouveau |
Un contenu trop gros est toujours refusé par ce code, jamais par une erreur du serveur sur la taille de la requête.
Toute autre erreur n'est pas un refus : l'écran affiche la page d'erreur et l'API répond 500, sans le message technique.
GOLIVE : scripts écartés
Lors d'un GOLIVE, chaque script promu passe les mêmes contrôles que l'écran Créer : nom, bornes du timeout et du nombre de tentatives, taille et références de secret du contenu, paramètres des versions à ajouter, et nom libre dans l'instance cible. Un script qui ne les passe pas apparaît dès l'aperçu avec un avertissement « Script écarté » et la raison (par exemple « un autre script de cette instance porte déjà ce nom »), suivie de la valeur en cause et, pour une version, de son numéro (v3). Ce script n'est pas appliqué, ni un processus qui l'utilise ; le reste du GOLIVE s'applique. Corrigez-le dans l'instance source (ou renommez le script de l'instance cible), puis promouvez-le de nouveau.
Un script est rapproché d'une instance à l'autre par son identifiant, le même partout : il est mis à jour, jamais recréé. Un script créé à la main dans chaque instance est retrouvé par son nom.
Voir aussi
- « Exécuter un script » : lancer un script et suivre son résultat.
- « Suivre les agents Outpost » : les agents et les groupes de machines.