Índice

Expansión de Variables de Entorno

El Wrapper permite la expansión de variables de entorno en tiempo de ejecución dentro de los valores de cualquier propiedad. Para mantener la naturaleza independiente de plataforma en el archivo de configuración "wrapper.conf", la sintaxis de Windows se usa en todas las plataformas.

Cuando el Wrapper se ejecuta como un servicio, las variables de entorno se cargarán desde el registro del sistema, en lugar de desde el entorno. Esto es necesario porque Windows carga las variables de entorno que están disponibles a los servicios cuando la máquina se inicia. Cualquier cambio en las variables de entorno del sistema en el registro (establecidas directamente ó desde el panel de control del sistema) no se hacen disponible a los servicios hasta que la máquina se reinicie nuevamente. Al cargar las variables de entorno desde el registro, se puede evitar el reinicio mientras se proporciona la misma funcionalidad.

Ejemplo referenciando la variable de entorno JAVA_HOME:
wrapper.java.command=%JAVA_HOME%/bin/java

Esto se expandirá en tiempo de ejecución a una ruta completamente calificada en cualquier sistema que defina la variable de entorno JAVA_HOME .

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

NOTA

Si una variable de entorno a la que se hace referencia no está definida, se registrará una advertencia y se dejará sin cambios en el valor de la propiedad.

A partir de la versión 3.5.55, es posible deshabilitar la expansión de variables en secciones del archivo de configuración (y evitar mensajes de advertencia) usando la directiva #variables.expand.

Definición de Variables de Entorno

El Wrapper admite la capacidad de definir variables de entorno desde el archivo de configuración "wrapper.conf" o desde la línea de comandos. Una vez definida, se puede hacer referencia a la variable de entorno como cualquier otra variable de entorno. Esto incluye el uso en expansión de variable como se describió anteriormente.

Nombre Especial de Propiedad Empezando con "set." y "set.default." :

Las variables de entorno se definen al usar nombres especiales de propiedad que empiezan con "set." o "set.default.", seguidos por el nombre de la variable de entorno. El valor de la propiredad será el valor de la nueva variable de entorno.

set.EXTERN_APP=C:/ExternAppHome

se usa el nombre de propiedad "set.default.", la variable de entorno solamente se definirá si aún no existe. Esto puede ser útil para definir una serie de valores de variables de entorno predeterminados.

set.default.EXTERN_APP=C:/ExternAppHome

Ejemplo:

La capacidad de definir variables de entorno permite modificar fácilmente los valores que se pueden utilizar en un archivo de configuración. El ejemplo a seguir muestra como una variable de entorno puede ser usada para especificar la ubicación de una aplicación externa.

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

El uso de las definiciones de las variables de entorno puede ser muy potente si entiende como y cuando sus valores se definen. El uso de definiciones de variables de entorno puede ser muy potente si comprende cómo y cuándo se establecen sus valores. Las variables de entorno que se establecieron antes de que se lanzara el Wrapper, por supuesto, pueden usarse como de costumbre. Si se especifica el mismo nombre de variable en el archivo de configuración, el valor en el archivo de configuración anulará el valor existente.

Desde la Línea de Comandos:

Las variables de entorno definidas desde la línea de comandos funcionan de manera un poco diferente. Estos valores desde la línea de comandos anularán cualquieres valores desde el sistema o las establecidas en el archivo de configuración. Estos valores de la línea de comando anularán cualquier valor del sistema o de los establecidos en el archivo de configuración. Esto hace posible definir variables de entorno predeterminadas dentro del archivo de configuración "wrapper.conf" y luego también cambiar ese valor desde la línea de comando.

Línea de Comandos en Windows: (NOTA: Un espacio está incluido en el valor de una propiedad.)
wrapper.exe -c ..\conf\wrapper.conf "set.EXTERN_APP=C:\Program Files\ExternAppHome"
Línea de Comandos en UNIX:
wrapper ../conf/wrapper.conf set.EXTERN_APP=/usr/lib/externapphome

NOTA

Note que, como todas las propiedades establecidas desde la línea de comandos, las propiedades que incluyen espacios se pueden definir incluyendo el conjunto completo de "nombre y valor de propiedad" entre comillas.

NOTA

Existe un problema conocido en el que las variables configuradas con referencias circulares crecerían cada vez que se recarga la configuración (que se requiere al menos una vez al iniciar y opionalmente al reiniciar la JVM).

Un ejemplo típico es cuando se agrega una ruta a la variable de entorno PATH:

set.PATH=my_path%WRAPPER_PATH_SEPARATOR%%PATH%.
La definición anterior haría que 'my_path' se agregara a PATH cada vez que se recarga la configuración.

Actualmente estamos trabajando en una solución para solucionar este problema, pero mientras tanto, una solución alternativa es hacer uso de una variable temporal que solo se establece una vez:

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

Definiciones por Defecto de Variables de Entorno

Al iniciarse, el Wrapper establece las siguientes variables de entorno en su propio entorno. Estas variables se pueden utilizar dentro del archivo de configuración "wrapper.conf" o accediendo al entorno de la JVM o cualquiera de sus procesos hijo.

  • La variable WRAPPER_ARCH se establece al nombre de la arquitectura para la que se creó el Wrapper que se está ejecutando actualmente. (Desde ver. 3.3.0)

  • La variable WRAPPER_BASE_NAME se configura al nombre del binario sin la extensión y sin el sistema operativo, la arquitectura y los bits (si se incluyen en el nombre). (Desde ver. 3.5.41)

  • La variable WRAPPER_BIN_DIR se configura a la ubicación del binario del Wrapper en el inicio. Se puede usar para definir rutas relativas a esta ubicación, aún que se modifique el directorio de trabajo actual. (Desde ver. 3.3.0)

  • La variable WRAPPER_BITS se configura a la profundidad de 32 bits o 64 bits para la que se creó el Wrapper que se está ejecutando actualmente. (Desde ver. 3.3.0)

  • La variable WRAPPER_EDITION se configura a la edición del Wrapper que se está ejecutando actualmente. Los valores posibles son "Community" (Comunidad), "Standard" (Estándar) y "Professional" (Profesional). (Desde ver. 3.5.36)

  • La variable WRAPPER_FILE_SEPARATOR se configura a '\' en Windows y '/' en plataformas Linux/UNIX, como un separador de archivos. La variable se puede usar para configurar valores independiented de plataforma para variables de entorno y propiedades adicionales. (Desde ver. 3.1.0)

    En general, es seguro usar siempre '/' como un separador de archivos para rutas usadas dentro de Java. Java es designado para trabajar correctamente en todas las plataformas cuando se usa '/'.

  • Las variables WRAPPER_HOSTNAME y WRAPPER_HOST_NAME se configuran al nombre resuelto de la máquina donde el Wrapper se está ejecutando actualmente. (WRAPPER_HOST_NAME Desde ver.3.3.2, WRAPPER_HOSTNAME Desde ver.3.3.6)

  • La variable WRAPPER_INIT_DIR se confugura al directorio de trabajo del proceso que lanzó el proceso del Wrapper. El Wrapper siempre primero fuerza al directorio de trabajo a la ubicación del binario del Wrapper mientras se carga la configuración (vea la variable WRAPPER_BIN_DIR). Entonces, si el usuario ha configurado otro directorio de trabajo, éste se cambiará a la ubicación especificada en la propiedad wrapper.working.dir. Sin embargo, algunas aplicaciones necesitan saber dónde estaba el usuario cuando inició el Wrapper. Esta variable se puede usar en estos casos, (Desde ver. 3.5.6)

    Ejemplo de Archivo de Configuración:
    wrapper.java.additional.1=-myinit.working.dir="%WRAPPER_INIT_DIR%"
    wrapper.java.additional.1.stripquotes=TRUE
    
  • La variable WRAPPER_JAVA_HOME se configura en plataformas Windows cuando se ubica el comando Java usando el registro del sistema. En otros casos, se recomienda que se configure una variable JAVA_HOME. (Desde ver. 3.3.0)

  • La variable WRAPPER_JAVA_VENDOR se configura después de cargar la configuración y después de analizar la salida del comando 'java -version' enviada a la JVM. El valor es una cadena que representa el proveedor de Java (implementación de JVM) que se utiliza actualmente. (Desde ver. 3.5.37)

    Es posible utilizar esta variable en cualquier valor de propiedad cargado después de que se haya analizado la versión de Java. Esto incluye propiedades de eventos, wrapper.java.additional_file y wrapper.app.parameter_file.

  • La variable WRAPPER_JAVA_VERSION se establece después que se carga la configuración y después de analizar la salida del comando 'java -version' enviada a la JVM. El valor es una cadena que representa la versión de Java utilizada actualmente. (Desde ver. 3.5.36)

    Es posible utilizar esta variable en cualquer valor de propiedad cargado después que la versión de Java se haya analizado. Esto incluye propiedades de eventos, wrapper.java.additional_file y wrapper.app.parameter_file.

  • Las variables WRAPPER_JAVA_VERSION_MAJOR, WRAPPER_JAVA_VERSION_MINOR y WRAPPER_JAVA_VERSION_REVISION se establecen después de cargar la configuración y después de analizar la salida del comando 'java -version' enviado a la JVM. Contienen los números de componente "mayor", "menor" y "revisión" de la versión de Java que se utiliza actualmente. (Desde ver. 3.5.36)

    Es posible utilizar esta variable en cualquier valor de propiedad cargado después de analizar la versión de Java. Esto incluye propiedades de eventos, wrapper.java.additional_file y wrapper.app.parameter_file.

  • La variable WRAPPER_LANG se configura a un código de dos caracteres en minúsculas que representa el idioma utilizado por el Wrapper. En la versión Comunidad, el valor es siempre 'en' (inglés). Uno de sus usos es incluir fragmentos del archivo de configuración que tienen valores localizados. (Desde ver. 3.5.5)

    El siguiente ejemplo muestra cómo localizar el nombre de visualización y las descripciones del servicio de Windows. Tenga en cuenta que el inglés se carga explícitamente primero (o sus propiedades pueden definirse primero). Esto es para asegurar que los valores en inglés existen por defecto. El Wrapper los sobrescribirá con valores en el "archivo de inclusión" localizado (estilo en cascada).

    Ejemplo (wrapper.conf):
    #encoding=UTF-8
    #include ../conf/wrapper-en.conf
    #include ../conf/wrapper-%WRAPPER_LANG%.conf
    ...
    wrapper.ntservice.name=myapp
    ...
    
    Ejemplo (wrapper-en.conf):
    #encoding=UTF-8
    wrapper.ntservice.displayname=My App Server
    wrapper.ntservice.description=Application Server that does cool stuff.
    
    Ejemplo (wrapper-de.conf):
    #encoding=UTF-8
    wrapper.ntservice.displayname=My App Server
    wrapper.ntservice.description=Application Server that does cool stuff.
    
  • La variable WRAPPER_OS se configura al nombre del sistema operativo para el que se creó el Wrapper que se está ejecutando actualmente. (Desde ver. 3.3.0)

    Ejemplo de Archivo de Configuración:
    wrapper.java.library.path.1=../lib
    wrapper.java.library.path.2=../lib/native/%WRAPPER_OS%-%WRAPPER_ARCH%-%WRAPPER_BITS%
    

    El ejemplo anterior resuelve a lo siguiente:

    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_PATH_SEPARATOR se congifura a ';' en Windows y ':' en plataformas Linux/UNIX. Se puede utilizar esta variable para crear rutas independientes de plataformas. (Desde ver. 3.1.0)

    Ejemplo de Archivo de Configuración:
    set.PATH=..%WRAPPER_FILE_SEPARATOR%lib%WRAPPER_PATH_SEPARATOR%%PATH%
    

    El ejemplo anterior resuelve a lo siguiente:

    Windows:
    set.PATH=..\lib;%PATH%
    
    UNIX:
    set.PATH=../lib:%PATH%
    
  • La variable WRAPPER_PID se configura al PID del proceso del Wrapper cuando éste es lanzado. Se puede utilizar en nombres de archivos como archivo PID o archivo de registro de salida para asegurar que tendrá un numbre único de archivo al lanzar multiples copias del Wrapper con el mismo archivo de configuración. (Desde ver. 3.3.7)

    Ejemplo de Archivo de Configuración:
    wrapper.logfile=../logs/wrapper-%WRAPPER_PID%.log
    
  • La variable WRAPPER_RUN_MODE se configura a "console" cuando se ejecuta en modo consola, o "service" cuando se ejecuta como servicio de Windows / demonio Unix. (Desde ver. 3.5.41)

  • La variable WRAPPER_VERSION se configura a la versión del Wrapper que se está ejecutando actualmente. (Desde ver. 3.5.36)

  • La variable WRAPPER_WORKING_DIR se configura a la ubicación del binario del Wrapper al inicio, pero se cambiará para reflejar el directorio de trabajo actual del Wrapper cuando los procesos hijo lo hagan referencia. (Desde ver. 3.3.0)

    El directorio de trabajo del Wrapper puede ser cambiado usando la propiedad wrapper.working.dir. Asegúrese de leer la documentación, ya que su uso es un poco complicado.

    Sin embargo, tenga en cuenta que, debido a la forma en que se establece esta propiedad, siempre será igual a la variable WRAPPER_BIN_DIR cuando se haga referencia a ella en el archivo de configuración del Wrapper. No obstante, la variable se establece con precisión dentro del entorno, y cualquier proceso hijo verá el directorio que se estableció con la propiedad wrapper.working.dir.

Pseudo-environment Variable Definitions

Además de las variables de entorno anteriores, el Wrapper genera las siguientes variables sin que realmente se almacenen en el entorno.

Las variables WRAPPER_RAND_NNNNNN y WRAPPER_TIME_YYYYMMDDHHIISS pueden ser referenciadas varias veces en el archivo de configuración y pueden generar valores diferentes para cada referencia. Por esta razón, no se almacenan en el entorno. Sin embargo, se puede almacenar el valor generado para una referencia única en su propia variable de entorno usando la sintaxis "set.<X>", pero tenga en cuenta que cada vez que se cambia el valor de una variable de entorno, la llamada a la función del sistema subyacente dará como resultado una pequeña pérdida de memoria. Esto debe tenerse en cuenta si el archivo de configuración se puede volver a cargar varias veces, ya que el valor de estas variables se regenerará y cambiará cada vez.

Ejemplo de un valor aleatorio que se almacena en una variable de entorno personalizada:
set.RAND_NNNNNN=%WRAPPER_RAND_NNNNNN%

Definiciones de Variables de Controlador de Eventos

Se puede hacer referencia a las siguientes variables en las propiedades de eventos y usarlas cuando se disparan esos eventos. Estas variables también son pseudo-variables de entorno, lo que significa que no se almacenan en el entorno.

  • La variable WRAPPER_NAME se configura al valor de la propiedad wrapper.name. (Desde ver. 3.3.0)

  • La variable WRAPPER_DISPLAYNAME se configura al valor de la propiedad wrapper.displayname. (Desde ver. 3.3.0)

  • La variable WRAPPER_DESCRIPTION se configura al valor de la propiedad wrapper.description. (Desde ver. 3.3.0)

  • La variable WRAPPER_EVENT_JVM_ID se configura a un valor entero que comienza con 1, lo que indica cuántas veces se ha reiniciado la JVM. Sólo se configura para eventos "jvm_*". (Desde ver. 3.3.0)

  • La variable WRAPPER_EVENT_JVM_PID se configura a un valor entero que contiene el PID del proceso de la JVM. Sólo se configura para "eventos jvm_*", con la excepción del evento "jvm_prelaunch". (Desde ver. 3.3.0)

  • La variable WRAPPER_EVENT_NAME se configura al nombre del evento que se dispara. (Desde ver. 3.3.0)

  • La variable WRAPPER_EVENT_RAND_NNNNNN se configura a un número aleatorio cuyo valor cambia cada vez que se dispara un evento. (Desde ver. 3.5.25)

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

    El ejemplo anterior hará que se generen dos números aleatorios. El primero, WRAPPER_RAND_NNNNNN, se establecerá una vez , cada vez que el archivo de configuración del Wrapper se cargue, pero el segundo, WRAPPER_EVENT_RAND_NNNNNN, cambiará para cada evento. No es posible reutilizar el mismo valor de WRAPPER_EVENT_RAND_NNNNNN debido a la forma en que su valor se resuelve dinámicamente.

    Existen formatos adicionales con números aleatorios compuestos de 1 a 6 dígitos: WRAPPER_EVENT_RAND_N, WRAPPER_EVENT_RAND_NN, WRAPPER_EVENT_RAND_NNN, WRAPPER_EVENT_RAND_NNNN, WRAPPER_EVENT_RAND_NNNNN y WRAPPER_EVENT_RAND_NNNNNN.

  • La variable WRAPPER_EVENT_TIME_YYYYMMDDHHIISS se configura a una marca de tiempo cada vez que se dispara el evento. (Desde ver. 3.5.25)

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

    El ejemplo anterior referenciará dos marcas de tiempo. La primera, WRAPPER_TIME_YYYYMMDDHHIISS, se establecerá una vez, cada vez que el archivo de configuración del Wrapper se cargue, pero la segunda, WRAPPER_EVENT_TIME_YYYYMMDDHHIISS, cambiará para cada evento. Se utilizará el mismo tiempo durante toda la ejecución del evento, por lo que es posible hacer uso de múltiples referencias de tiempo.

    También se pueden hacer referencia a los siguientes formatos adicionales: WRAPPER_EVENT_TIME_YYYYMMDD_HHIISS, WRAPPER_EVENT_TIME_YYYYMMDDHHII, WRAPPER_EVENT_TIME_YYYYMMDDHH, y WRAPPER_EVENT_TIME_YYYYMMDD.

  • La variable WRAPPER_EVENT_WRAPPER_PID se configura a un valor entero que contiene el PID del proceso del Wrapper. (Esta variable de entorno es un alias de la variable de entorno WRAPPER_PID y se mantiene solo por compatibilidad con versiones anteriores.) (Desde ver. 3.3.0)

Enmascaramiento de datos confidenciales

Compatibilidad :3.5.57
Ediciones :Edición ProfesionaEdición EstándarEdición de la Comunidad
Plataformas :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

La sintaxis %...|mask% se puede utilizar para enmascarar partes de texto del archivo de configuración en la salida del registro.

Esta notación no debe confundirse con una definición de variable. Simplemente utiliza los mismos delimitadores '%' que para las variables para indicar que se expandirá al procesar el archivo de configuración.

El texto o los datos confidenciales que se enmascararán en la salida del registro se deben escribir entre el delimitador de apertura '%' y el carácter '|'. Para uso interno del Wrapper o de la aplicación Java, esta notación se expandirá a solamente los datos confidenciales, removiendo los delimitadores Para uso interno del Wrapper o de la aplicación Java, esta notación se ampliará solo a los datos confidenciales, eliminando los delimitadores '%' y la parte '|mask. Para la salida del registro, los datos confidenciales se reemplazarán por caracteres '*'.

Esta notación es especialmente útil para enmascarar contraseñas, por ejemplo en el valor de una propiedad wrapper.app.property.<n>.

Ejemplo (enmascarar valores de propiedades pasadas a la aplicación):
wrapper.app.property.1=mypassword=secretpassword
wrapper.app.property.2=mysecret=this is a %secret|mask%!

La configuración anterior generará la siguiente salida de registro si establece la propiedad wrapper.properties.dump.loglevel en INFO.

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