Í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 hijos.

  • 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 hijos 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%

  • La variable WRAPPER_PERCENTAGE se configura a un un solo carácter '%' . Se recomienda su uso para evitar una ambigüedad sintáctica cuando el valor de una propiedad contiene dos caracteres '%', en cuyo caso se informaría una advertencia sobre una variable de entorno faltante (el contenido entre los dos '%' se imagina como el nombre de una variable). (Desde ver. 3.3.38)

    Ejemplo (nombre del archivo de salida de la recolección de elementos no utilizados se expandirá correctamente e 'gc_%t_%p.log') 
    wrapper.java.additional.1=-Xloggc:C:\logs\gc_%WRAPPER_PERCENTAGE%t_%WRAPPER_PERCENTAGE%p.log

  • La variable WRAPPER_RAND_NNNNNN se configura a un número aleatorio en cada ubicación en que se utiliza dentro del archivo de configuración del Wrapper. (Desde ver. 3.3.4)

    Ejemplo de Archivo de Configuración: 
    wrapper.app.parameter.1=mytempfile-%WRAPPER_RAND_NNNNNN%.txt

    El valor se establece una vez una vez cuando se carga y analiza el archivo de configuración. Si el valor debe establecerse cada vez que se lanza una JVM, es necesario especificar la propiedad de configuración wrapper.restart.reload_configuration=TRUE para que la configuración se vuelva a analizar antes de cada invocación de JVM.

    Se generará un número aleatorio diferente en cada lugar que se especifique la variable. Si es necesario hacer referencia al mismo número aleatorio en varias ubicaciones, primero almacene el valor en una variable local y luego haga referencia según sea necesario. Por ejemplo:

    Ejemplo de Archivo de Configuración: 
    set.RNUM=%WRAPPER_RAND_NNNNNN%
wrapper.java.additional.1=-Dtempid=%RNUM%
wrapper.app.parameter.1=mytempfile-%RNUM%.txt

    Existen formatos adicionales con números aleatorios compuestos de 1 a 6 dígitos: WRAPPER_RAND_N, WRAPPER_RAND_NN, WRAPPER_RAND_NNN, WRAPPER_RAND_NNNN, WRAPPER_RAND_NNNNN, y WRAPPER_RAND_NNNNNN.

  • La variable WRAPPER_SYSMEM_PP.P se configura a un valor calculado a partir de un porcentaje de la cantidad de memoria física disponible en el sistema. (Desde ver. 3.5.29)

    PP.P se refiere al porcentaje de la memoria del sistema. Su valor debe ser mayor que 0 y hasta 100. Fuera de este rango, la variable será ignorada. El porcentaje puede tener decimales, pero el valor calculado se redondeará al siguiente megabyte más cercano.

    Se puede utilizar esta variable en las propiedades wrapper.java.additional.<n> para configurar algunas opciones de la JVM, como:

    • -Xms
    • -Xmx
    • -Xmn
    • -XX:PermSize or XX:MaxPermSize (Java<8)
    • -XX:MetaspaceSize o -XX:MaxMetaspaceSize (Java>=8)
    • ...

  • La variable WRAPPER_TIME_YYYYMMDDHHIISS se configura a una marca de tiempo en cada ubicación que se utiliza dentro del archivo de configuración. La hora devuelta es la hora en que se carga el archivo de configuración. La variable devolverá el mismo valor cuando se haga referencia a ella varias veces en el mismo archivo de configuración. (Desde ver. 3.3.4)

    El siguiente ejemplo demuestra cómo generar un nombre de archivo con marca de tiempo y pasarlo a la JVM:

    Ejemplo de Archivo de Configuración: 
    wrapper.app.parameter.1=mytempfile-%WRAPPER_TIME_YYYYMMDDHHIISS%.txt

    El ejemplo anterior resulta en un valor como:

    Resultado: 
    wrapper.app.parameter.1=mytempfile-20090409124532.txt

    El valor se establece una vez cuando el archivo de configuración se carga y es analizado. Si el valor debe establecerse cada vez que se lanza una JVM, es necesario especificar la propiedad de configuración wrapper.restart.reload_configuration=TRUE para que la configuración se vuelva a analizar antes de cada invocación de la JVM.

    También se puede hacer referencia a los siguientes formatos adicionales: WRAPPER_TIME_YYYYMMDD_HHIISS, WRAPPER_TIME_YYYYMMDDHHII, WRAPPER_TIME_YYYYMMDDHH, y WRAPPER_TIME_YYYYMMDD.

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)