Index

Expansion des variables d'environnement

Le Wrapper prend en charge l'expansion des variables d'environnement à l'exécution dans les valeurs de n'importe quelle propriété. Pour conserver le caractère indépendant de la plate-forme du fichier de configuration "wrapper.conf", la syntaxe Windows est utilisée pour toutes les plates-formes.

Lorsque le Wrapper est exécuté en tant que service, les variables d'environnement seront chargées à partir du registre système plutôt qu'à partir de l'environnement. Cela est nécessaire car Windows charge les variables d'environnement disponibles pour les services au démarrage de la machine. Toute modification des variables d'environnement système dans le registre (définie directement ou via le panneau de configuration système) n'est pas mise à la disposition des services tant que la machine n'a pas été à nouveau redémarrée. En chargeant les variables d'environnement à partir du registre, le redémarrage peut être évité tout en offrant les mêmes fonctionnalités.

Exemple référençant la variable d'environnement JAVA_HOME :
wrapper.java.command=%JAVA_HOME%/bin/java

Cela sera développé à l'exécution en un chemin d'accès complet sur tout système qui définit la variable d'environnement JAVA_HOME.

JAVA_HOME sous Windows :
wrapper.java.command=C:\Sun\jdk1.3\bin\java
JAVA_HOME sous UNIX :
wrapper.java.command=/opt/IBMJava2-131/bin/java

NOTE

Si une variable d'environnement référencée n'est pas définie, un avertissement sera consigné dans le journal et elle restera inchangée dans la valeur de la propriété.

À partir de la version 3.5.55, il est possible de désactiver l'expansion des variables dans des sections du fichier de configuration (et d'éviter les messages d'avertissement) à l'aide de la directive @variables.expand.

Définition des variables d'environnement

Le Wrapper prend en charge la possibilité de définir des variables d'environnement à partir du fichier de configuration "wrapper.conf" ou à partir de la ligne de commande. Une fois définie, la variable d'environnement peut être référencée comme n'importe quelle autre variable d'environnement. Cela inclut l'utilisation dans l'expansion des variables comme décrit ci-dessus.

Nom de propriété spécial commençant par "set." et "set.default."

Les variables d'environnement sont définies à l'aide de noms de propriétés spéciaux commençant par "set." ou "set.default." suivis du nom de la variable d'environnement. La valeur de la propriété sera la valeur de la nouvelle variable d'environnement.

set.EXTERN_APP=C:/ExternAppHome

Si le nom de propriété "set.default." est utilisé, la variable d'environnement ne sera définie que si elle n'existe pas encore. Cela peut être utile pour définir une série de valeurs de variables d'environnement par défaut.

set.default.EXTERN_APP=C:/ExternAppHome

Exemple :

La possibilité de définir des variables d'environnement permet de modifier facilement des valeurs susceptibles d'être utilisées dans tout un fichier de configuration. L'exemple ci-dessous montre comment une variable d'environnement peut être utilisée pour spécifier l'emplacement d'une application externe.

set.EXTERN_APP=C:/ExternAppHome

wrapper.java.classpath.1=../lib/wrapper.jar
wrapper.java.classpath.2=%EXTERN_APP%/lib/jar1.jar
wrapper.java.classpath.3=%EXTERN_APP%/lib/jar2.jar
wrapper.java.classpath.4=%EXTERN_APP%/lib/ext/jar3.jar
wrapper.java.classpath.5=%EXTERN_APP%/lib/ext/jar4.jar

L'utilisation des définitions de variables d'environnement peut être très puissante si vous comprenez comment et quand leurs valeurs sont définies. Les variables d'environnement qui ont été définies avant le lancement du Wrapper peuvent, bien entendu, être utilisées comme d'habitude. Si le même nom de variable est spécifié dans le fichier de configuration, alors la valeur du fichier de configuration remplacera la valeur existante.

Portée de la plate-forme

À partir de la version 3.7.0, il est possible de restreindre les variables d'environnement à des systèmes d'exploitation spécifiques à l'aide du modificateur facultatif [.<platform>]. Cela permet des configurations multi-plates-formes au sein d'un seul fichier sans avoir besoin d'un fichier d'inclusion. En ajoutant .windows, .unix ou .linux à la directive set de base, la variable ne sera évaluée et appliquée que lorsque le Wrapper s'exécute sur le système d'exploitation ciblé.

Les valeurs possibles pour <platform> sont :

  • unix
  • windows
  • aix
  • freebsd
  • alpine
  • linux
  • macos
  • solaris

Exemple : (variable uniquement pour Windows)
set.windows.APP_HOME=C:\Program Files\MyApp

Exemple : (variable uniquement pour Unix)
set.unix.APP_HOME=/opt/myapp

Exemple : (valeurs par défaut par plate-forme)
# default value for all systems
set.default.MAX_MEMORY=512M

# default values specifically for Linux and freeBSD
set.linux.default.MAX_MEMORY=1024M
set.freebsd.default.MAX_MEMORY=1024M

À partir de la ligne de commande

Les variables d'environnement définies à partir de la ligne de commande fonctionnent un peu différemment. Ces valeurs de la ligne de commande remplaceront toutes les valeurs provenant soit du système, soit de celles définies dans le fichier de configuration. Cela permet de définir des variables d'environnement par défaut dans le fichier de configuration "wrapper.conf" puis également de modifier cette valeur à partir de la ligne de commande.

Ligne de commande sous Windows : (REMARQUE : un espace est inclus dans une valeur de propriété)
wrapper.exe -c ..\conf\wrapper.conf "set.EXTERN_APP=C:\Program Files\ExternAppHome"
Ligne de commande sous UNIX :
wrapper ../conf/wrapper.conf set.EXTERN_APP=/usr/lib/externapphome

NOTE

Notez que, comme pour toutes les propriétés définies à partir de la ligne de commande, les propriétés contenant des espaces peuvent être définies en incluant la paire complète « nom de propriété et valeur » entre guillemets.

Références circulaires

NOTE

Avant la version 3.6.3 du Wrapper, il existait un problème connu où les variables avec des références circulaires s'allongeaient à chaque rechargement de la configuration (ce qui se produit au moins une fois au démarrage et éventuellement lors du redémarrage de la JVM).

Un exemple typique est l'ajout d'un chemin à la variable d'environnement PATH :

set.PATH=my_path%WRAPPER_PATH_SEPARATOR%%PATH%.
La définition ci-dessus entraînerait l'ajout de 'my_path' à PATH à chaque rechargement de la configuration.

Une solution de contournement pour les versions antérieures à 3.6.3 consiste à utiliser une variable temporaire qui n'est définie qu'une seule fois :

set.default.MYPATH=my_path%WRAPPER_PATH_SEPARATOR%%PATH%.
set.PATH=%MYPATH%

Définitions des variables d'environnement par défaut

Au démarrage, le Wrapper définit les variables d'environnement suivantes dans son propre environnement. Ces variables peuvent être utilisées dans le fichier de configuration "wrapper.conf" ou en accédant à l'environnement de la JVM ou de n'importe lequel de ses processus enfants.

  • La variable WRAPPER_ARCH est définie sur le nom de l'architecture pour laquelle le Wrapper actuellement en cours d'exécution a été compilé. (Depuis la ver. 3.3.0)

  • La variable WRAPPER_BASE_NAME est définie sur le nom du binaire sans l'extension, et sans le système d'exploitation, l'architecture et les bits (s'ils sont inclus dans le nom). (Depuis la ver. 3.5.41)

  • La variable WRAPPER_BIN_DIR est définie sur l'emplacement du binaire du Wrapper au démarrage. Elle peut être utilisée pour définir des chemins relatifs à cet emplacement même si le répertoire de travail actuel est modifié. (Depuis la ver. 3.3.0)

  • La variable WRAPPER_BITS est définie sur la profondeur 32 bits ou 64 bits pour laquelle le Wrapper actuellement en cours d'exécution a été compilé. (Depuis la ver. 3.3.0)

  • La variable WRAPPER_CONF_DIR est définie sur l'emplacement du fichier de configuration du Wrapper au démarrage. Elle peut être utilisée pour définir des chemins relatifs à cet emplacement même si le répertoire de travail actuel est modifié. (Depuis la ver. 3.5.8)

  • La variable WRAPPER_EDITION est définie sur l'édition du Wrapper actuellement en cours d'exécution. Les valeurs possibles sont « Community », « Standard » et « Professional ». (Depuis la ver. 3.5.36)

  • La variable WRAPPER_FILE_SEPARATOR est définie sur '\' sous Windows et '/' sur les plates-formes Linux/UNIX, en tant que séparateur de fichiers. La variable peut être utilisée pour définir des valeurs indépendantes de la plate-forme pour des variables d'environnement ou des propriétés supplémentaires. (Depuis la ver. 3.1.0)

    En général, il est sans danger d'utiliser toujours '/' comme séparateur de fichiers pour les chemins utilisés dans Java. Java est conçu pour fonctionner correctement sur toutes les plates-formes lorsque '/' est utilisé.

  • Les variables WRAPPER_HOSTNAME et WRAPPER_HOST_NAME sont définies sur le nom résolu de la machine sur laquelle le Wrapper s'exécute actuellement. (WRAPPER_HOST_NAME depuis la ver. 3.3.2, WRAPPER_HOSTNAME depuis la ver. 3.3.6)

  • La variable WRAPPER_INIT_DIR est définie sur le répertoire de travail du processus qui a lancé le processus Wrapper. Le Wrapper force d'abord toujours le répertoire de travail vers l'emplacement du binaire du Wrapper pendant le chargement de la configuration (voir la variable WRAPPER_BIN_DIR). Ensuite, si l'utilisateur a configuré un autre répertoire de travail, il sera modifié vers l'emplacement spécifié avec la propriété wrapper.working.dir. Tout cela est nécessaire pour garantir que le Wrapper s'exécute de manière 100 % fiable avec une configuration donnée quel que soit l'endroit d'où le Wrapper a été lancé. Certaines applications ont toutefois besoin de savoir où se trouvait l'utilisateur lorsqu'il a lancé le Wrapper. Dans ces cas, cette variable peut être utilisée. (Depuis la ver. 3.5.6)

    Exemple de fichier de configuration :
    wrapper.java.additional.1=-myinit.working.dir=%WRAPPER_INIT_DIR%
    
  • La variable WRAPPER_JAVA_HOME est définie sur les plates-formes Windows lorsque la commande Java est localisée à l'aide du registre système. Dans les autres cas, il est recommandé de définir une variable JAVA_HOME. (Depuis la ver. 3.3.0)

  • La variable WRAPPER_JAVA_VENDOR est définie après le chargement de la configuration et après l'analyse de la sortie de la commande 'java -version' envoyée à la JVM. La valeur est une chaîne représentant le fournisseur Java (implémentation de la JVM) actuellement utilisé. (Depuis la ver. 3.5.37)

    Il est possible d'utiliser cette variable dans n'importe quelle valeur de propriété chargée après l'analyse de la version Java. Cela inclut les propriétés d'événements, wrapper.java.additional_file et wrapper.app.parameter_file.

  • La variable WRAPPER_JAVA_VERSION est définie après le chargement de la configuration et après l'analyse de la sortie de la commande 'java -version' envoyée à la JVM. La valeur est une chaîne représentant la version Java actuellement utilisée. (Depuis la ver. 3.5.36)

    Il est possible d'utiliser cette variable dans n'importe quelle valeur de propriété chargée après l'analyse de la version Java. Cela inclut les propriétés d'événements, wrapper.java.additional_file et wrapper.app.parameter_file.

  • Les variables WRAPPER_JAVA_VERSION_MAJOR, WRAPPER_JAVA_VERSION_MINOR et WRAPPER_JAVA_VERSION_REVISION sont définies après le chargement de la configuration et après l'analyse de la sortie de la commande 'java -version' envoyée à la JVM. Elles contiennent les numéros de composant « major », « minor », « revision » de la version Java actuellement utilisée. (Depuis la ver. 3.5.36)

    Il est possible d'utiliser ces variables dans n'importe quelle valeur de propriété chargée après l'analyse de la version Java. Cela inclut les propriétés d'événements, wrapper.java.additional_file et wrapper.app.parameter_file.

  • La variable WRAPPER_LANG est définie sur un code de deux caractères en minuscules représentant la langue utilisée par le Wrapper. Dans l'édition Community, la valeur est toujours 'en'. Une utilisation de cette variable consiste à inclure des fragments de fichier de configuration contenant des valeurs localisées. (Depuis la ver. 3.5.5)

    L'exemple suivant montre comment localiser le nom d'affichage et les descriptions du service Windows. Notez que l'anglais est chargé explicitement en premier (ou que ses propriétés pourraient être définies en premier). Cela permet de s'assurer que les valeurs anglaises existent par défaut. Le Wrapper les écrasera ensuite avec les valeurs du « fichier d'inclusion » localisé (style en cascade).

    Exemple (wrapper.conf) :
    @encoding=UTF-8
    @include ../conf/wrapper-en.conf
    @include ../conf/wrapper-%WRAPPER_LANG%.conf
    ...
    wrapper.ntservice.name=myapp
    ...
    
    Exemple (wrapper-en.conf) :
    @encoding=UTF-8
    wrapper.ntservice.displayname=My App Server
    wrapper.ntservice.description=Application Server that does cool stuff.
    
    Exemple (wrapper-de.conf) :
    @encoding=UTF-8
    wrapper.ntservice.displayname=Mein App-Server
    wrapper.ntservice.description=Ein Anwendungsserver, der coole Sachen macht.
    
  • La variable WRAPPER_OS est définie sur le nom du système d'exploitation pour lequel le Wrapper actuellement en cours d'exécution a été compilé. (Depuis la ver. 3.3.0)

    Exemple de fichier de configuration :
    wrapper.java.library.path.1=../lib
    wrapper.java.library.path.2=../lib/native/%WRAPPER_OS%-%WRAPPER_ARCH%-%WRAPPER_BITS%
    

    L'exemple ci-dessus se résout comme suit :

    Windows :
    wrapper.java.library.path.1=../lib
    wrapper.java.library.path.2=../lib/native/windows-x86-32
    
    Linux :
    wrapper.java.library.path.1=../lib
    wrapper.java.library.path.2=../lib/native/linux-x86-32
    
    Solaris :
    wrapper.java.library.path.1=../lib
    wrapper.java.library.path.2=../lib/native/solaris-sparc-32
    
  • La variable WRAPPER_OS_FAMILY est définie sur la famille de système d'exploitation pour laquelle le Wrapper en cours d'exécution a été compilé. (Depuis la ver. 3.7.0)

    Exemple de fichier de configuration :
    @include ../conf/wrapper-%WRAPPER_OS_FAMILY%.conf
    

    L'exemple ci-dessus se résout comme suit :

    Windows :
    @include ../conf/wrapper-windows.conf
    
    Linux :
    @include ../conf/wrapper-unix.conf
    
    Solaris :
    @include ../conf/wrapper-unix.conf
    
  • La variable WRAPPER_PATH_SEPARATOR est définie sur ';' sous Windows et ':' sur les plates-formes Linux/UNIX. La variable peut être utilisée pour construire des chemins indépendants de la plate-forme. (Depuis la ver. 3.1.0)

    Exemple de fichier de configuration :
    set.PATH=..%WRAPPER_FILE_SEPARATOR%lib%WRAPPER_PATH_SEPARATOR%%PATH%
    

    L'exemple ci-dessus se résout comme suit :

    Windows :
    set.PATH=..\lib;%PATH%
    
    UNIX :
    set.PATH=../lib:%PATH%
    
  • La variable WRAPPER_PID est définie sur le PID du processus Wrapper lors de son lancement. Elle peut être utilisée dans des noms de fichiers comme le fichier PID ou le fichier journal pour garantir un nom de fichier unique lors du lancement de plusieurs copies du Wrapper avec le même fichier de configuration. (Depuis la ver. 3.3.7)

    Exemple de fichier de configuration :
    wrapper.logfile=../logs/wrapper-%WRAPPER_PID%.log
    
  • La variable WRAPPER_RUN_MODE est définie sur "console" lors de l'exécution en tant que console, ou "service" lors de l'exécution en tant que service Windows / démon Unix. (Depuis la ver. 3.5.41)

  • La variable WRAPPER_VERSION est définie sur la version du Wrapper actuellement en cours d'exécution. (Depuis la ver. 3.5.36)

  • La variable WRAPPER_WORKING_DIR est définie sur l'emplacement du binaire du Wrapper au démarrage, mais sera modifiée pour refléter le répertoire de travail actuel du Wrapper lorsqu'elle est référencée par des processus enfants. (Depuis la ver. 3.3.0)

    Le répertoire de travail du Wrapper peut être modifié à l'aide de la propriété wrapper.working.dir. Veillez à lire la documentation, car son utilisation est un peu délicate.

    Veuillez toutefois noter que, en raison de la façon dont cette propriété est définie, elle sera toujours égale à la variable WRAPPER_BIN_DIR lorsqu'elle est référencée dans le fichier de configuration du Wrapper. La variable est toutefois définie correctement dans l'environnement, et tous les processus enfants verront le répertoire qui a été défini avec la propriété wrapper.working.dir.

Définitions des pseudo-variables d'environnement

En plus des variables d'environnement ci-dessus, les variables suivantes sont générées par le Wrapper sans être réellement stockées dans l'environnement.

Les variables WRAPPER_RAND_NNNNNN et WRAPPER_TIME_YYYYMMDDHHIISS peuvent être référencées plusieurs fois dans le fichier de configuration, et peuvent générer des valeurs différentes pour chaque référence. Pour cette raison, elles ne sont pas stockées dans l'environnement. Vous pouvez toutefois stocker la valeur générée pour une seule référence dans votre propre variable d'environnement à l'aide de la syntaxe "set.<X>", mais sachez que chaque fois que la valeur d'une variable d'environnement est modifiée, l'appel à la fonction système sous-jacente entraînera une petite fuite de mémoire. Cela doit être pris en compte si le fichier de configuration peut être rechargé plusieurs fois, car la valeur de ces variables sera régénérée et changera à chaque fois.

Exemple d'une valeur aléatoire stockée dans une variable d'environnement personnalisée :
set.RAND_NNNNNN=%WRAPPER_RAND_NNNNNN%

Définitions des variables du gestionnaire d'événements

Les variables suivantes peuvent être référencées dans les propriétés d'événements et utilisées lorsque ces événements sont déclenchés. Ces variables sont également des pseudo-variables d'environnement, ce qui signifie qu'elles ne sont pas stockées dans l'environnement.

  • La variable WRAPPER_NAME est définie sur la valeur de la propriété wrapper.name. (Depuis la ver. 3.3.0)

  • La variable WRAPPER_DISPLAYNAME est définie sur la valeur de la propriété wrapper.displayname. (Depuis la ver. 3.3.0)

  • La variable WRAPPER_DESCRIPTION est définie sur la valeur de la propriété wrapper.description. (Depuis la ver. 3.3.0)

  • La variable WRAPPER_EVENT_JVM_ID est définie sur une valeur entière commençant par 1, indiquant le nombre de fois que la JVM a été redémarrée. Définie uniquement pour les événements "jvm_*". (Depuis la ver. 3.3.0)

  • La variable WRAPPER_EVENT_JVM_PID est définie sur une valeur entière contenant le PID du processus JVM. Définie uniquement pour les événements "jvm_*" à l'exception de l'événement "jvm_prelaunch". (Depuis la ver. 3.3.0)

  • La variable WRAPPER_EVENT_NAME est définie sur le nom de l'événement en cours de déclenchement. (Depuis la ver. 3.3.0)

  • La variable WRAPPER_EVENT_RAND_NNNNNN est définie sur un nombre aléatoire dont la valeur change à chaque déclenchement de l'événement. (Depuis la ver. 3.5.25)

    Exemple :
    wrapper.event.default.message=Event: %WRAPPER_EVENT_NAME% %WRAPPER_RAND_NNNNNN% %WRAPPER_EVENT_RAND_NNNNNN%
    

    L'exemple ci-dessus entraînera la génération de deux nombres aléatoires. Le premier, WRAPPER_RAND_NNNNNN, sera défini une fois à chaque chargement du fichier de configuration du Wrapper, mais le second, WRAPPER_EVENT_RAND_NNNNNN, changera pour chaque événement. Il n'est pas possible de réutiliser la même valeur de WRAPPER_EVENT_RAND_NNNNNN en raison de la façon dont sa valeur est résolue dynamiquement.

    Des formats supplémentaires existent avec des nombres aléatoires composés de 1 à 6 chiffres : WRAPPER_EVENT_RAND_N, WRAPPER_EVENT_RAND_NN, WRAPPER_EVENT_RAND_NNN, WRAPPER_EVENT_RAND_NNNN, WRAPPER_EVENT_RAND_NNNNN et WRAPPER_EVENT_RAND_NNNNNN.

  • La variable WRAPPER_EVENT_TIME_YYYYMMDDHHIISS est définie sur un horodatage à chaque déclenchement de l'événement. (Depuis la ver. 3.5.25)

    Exemple :
    wrapper.event.default.message=Event: %WRAPPER_EVENT_NAME% %WRAPPER_TIME_YYYYMMDDHHIISS% %WRAPPER_EVENT_TIME_YYYYMMDDHHIISS%
    

    L'exemple ci-dessus référencera deux horodatages. Le premier, WRAPPER_TIME_YYYYMMDDHHIISS, sera défini une fois à chaque chargement du fichier de configuration du Wrapper, mais le second, WRAPPER_EVENT_TIME_YYYYMMDDHHIISS, changera pour chaque événement. La même heure sera utilisée tout au long de l'exécution de l'événement, il est donc possible d'utiliser plusieurs références temporelles.

    Les formats supplémentaires suivants peuvent également être référencés : WRAPPER_EVENT_TIME_YYYYMMDD_HHIISS, WRAPPER_EVENT_TIME_YYYYMMDDHHII, WRAPPER_EVENT_TIME_YYYYMMDDHH et WRAPPER_EVENT_TIME_YYYYMMDD.

  • La variable WRAPPER_EVENT_WRAPPER_PID est définie sur une valeur entière contenant le PID du processus Wrapper. (Cette variable d'environnement est un alias de la variable d'environnement WRAPPER_PID et n'est conservée que pour la rétrocompatibilité.) (Depuis la ver. 3.3.0)

Masquage des données sensibles

Compatibilité :3.5.57
Éditions :Édition ProfessionnelleÉdition StandardÉdition Community
Plateformes :WindowsMac OSXLinuxAlpine LinuxFreeBSDSolarisIBM z/Linux

La notation %...|mask% peut être utilisée pour masquer des portions de texte du fichier de configuration dans la sortie du journal.

Cette notation ne doit pas être confondue avec une définition de variable. Elle utilise simplement les mêmes délimiteurs '%' que pour les variables afin d'indiquer qu'elle sera développée lors du traitement du fichier de configuration.

Le texte ou les données sensibles à masquer dans la sortie du journal doivent être écrits entre le délimiteur d'ouverture '%' et le caractère '|'. Pour l'utilisation interne du Wrapper ou de l'application Java, cette notation sera développée pour ne conserver que les données sensibles, en supprimant les délimiteurs '%' ainsi que la partie '|mask'. Pour la sortie du journal, les données sensibles seront remplaçées par des caractères '*'.

Cette notation est particulièrement utile pour masquer les mots de passe, par exemple dans la valeur d'une propriété wrapper.app.property.<n>.

Exemple (masquer les valeurs des propriétés transmises à l'application) :
wrapper.app.property.1=mypassword=secretpassword
wrapper.app.property.2=mysecret=this is a %secret|mask%!

La configuration ci-dessus générera la sortie de journal suivante si vous définissez wrapper.properties.dump.loglevel sur INFO.

Exemple (sortie) :
INFO   | wrapper  |   F |   | wrapper.app.property.1 | mypassword=**************
INFO   | wrapper  |   F |   | wrapper.app.property.2 | mysecret=this is a ******!

NOTE

À partir de la version 3.6.0 du Wrapper, la notation %...|mask% n'est pas autorisée dans les valeurs de propriétés utilisées pour construire la ligne de commande Java, car cela exposerait des données sensibles aux outils de visualisation des processus tels que le Gestionnaire des tâches (sous Windows) ou ps (sous Unix).