Index
  • Environment Variable Expansion
  • Environment Variable Definition
    • "set.<X>"
    • "set.default.<X>"
  • Default Environment Variable Definitions
    • WRAPPER_ARCH
    • WRAPPER_BASE_NAME
    • WRAPPER_BIN_DIR
    • WRAPPER_BITS
    • WRAPPER_CONF_DIR
    • WRAPPER_EDITION
    • WRAPPER_FILE_SEPARATOR
    • WRAPPER_HOSTNAME
    • WRAPPER_INIT_DIR
    • WRAPPER_JAVA_HOME
    • WRAPPER_JAVA_VENDOR
    • WRAPPER_JAVA_VERSION
    • WRAPPER_JAVA_VERSION_MAJOR
    • WRAPPER_JAVA_VERSION_MINOR
    • WRAPPER_JAVA_VERSION_REVISION
    • WRAPPER_LANG
    • WRAPPER_OS
    • WRAPPER_PATH_SEPARATOR
    • WRAPPER_PID
    • WRAPPER_RUN_MODE
    • WRAPPER_VERSION
    • WRAPPER_WORKING_DIR
  • Pseudo-environment Variable Definitions
    • WRAPPER_PERCENTAGE
    • WRAPPER_RAND_NNNNNN
    • WRAPPER_SYSMEM_PP.P
    • WRAPPER_TIME_YYYYMMDDHHIISS
  • Event Handler Variable Definitions
    • WRAPPER_NAME
    • WRAPPER_DISPLAYNAME
    • WRAPPER_DESCRIPTION
    • WRAPPER_EVENT_JVM_ID
    • WRAPPER_EVENT_JVM_PID
    • WRAPPER_EVENT_NAME
    • WRAPPER_EVENT_RAND_NNNNNN
    • WRAPPER_EVENT_TIME_YYYYMMDDHHIISS
    • WRAPPER_EVENT_WRAPPER_PID

Environment Variable Expansion

The Wrapper supports environment variable expansion at run time within the values of any property. To maintain the platform independent nature of the configuration file "wrapper.conf", the Windows syntax is used for all platforms.

When the Wrapper is run as a service, environment variables will be loaded from the system registry rather than from the environment. This is necessary because Windows loads the environment variables which are available to services when the machine is booted. Any changes to the system environment variables in the registry (set directly or through the system control panel) are not made available to the services until the machine is once again rebooted. By loading the environment variables from the registry, the reboot can be avoided while providing the same functionality.

Example referencing the JAVA_HOME environment variable: 
wrapper.java.command=%JAVA_HOME%/bin/java

This will expand at runtime to a fully qualified path on any system which defines the JAVA_HOME environment variable.

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

NOTE

If a referenced environment variable is not defined, then a warning will be logged and it will be left unchanged in the property value.

Starting from version 3.5.55, it is possible to disable variable expansion in sections of the configuration file (and avoid warning messages) using the #variables.expand directive.

Environment Variable Definition

The Wrapper supports the ability to define environment variables from within the configuration file "wrapper.conf" or from the command line. Once defined, the environment variable can be referenced like any other environment variable. This includes use in variable expansion as described above.

Special Property Name starting with "set." and "set.default." :

Environment variables are defined by using special property names which begin with "set." or "set.default." followed by the name of the environment variable. The value of the property will be the value of the new environment variable. 

set.EXTERN_APP=C:/ExternAppHome

If the "set.default." property name is used, the environment variable will only be set if it does not exist yet. This can be useful for defining a series of default environment variable values. 

set.default.EXTERN_APP=C:/ExternAppHome

Example:

The ability to define environment variables makes it possible to easily modify values that may be used throughout a configuration file. The example below shows how an environment variable can be used to specify the location of an external application. 

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

The use of environment variables definitions can be very powerful if you understand how and when their values are set. Environment variables which were set before the Wrapper is launched, can, of course, be used as usual. If the same variable name is specified in the configuration file, then the value in the configuration file will override the existing value.

From Command Line:

Environment variables defined from the command line work a little differently. These values from command line will override any values from either the system or those set in the configuration file. This makes it possible to define default environment variables within the configuration file "wrapper.conf" and then also to change that value from the command line.

Command Line on Windows: (NOTE: A space is included in a property value) 
wrapper.exe -c ..\conf\wrapper.conf "set.EXTERN_APP=C:\Program Files\ExternAppHome"
Command Line on UNIX: 
wrapper ../conf/wrapper.conf set.EXTERN_APP=/usr/lib/externapphome

NOTE

Notice that, like all properties set from the command line, properties including spaces can be defined by including the entire pair of "property name and value" in quotes.

NOTE

There is a known issue where variables set with circular references would grow up each time the configuration is reloaded (which is required at least one time on startup and optionaly when restarting the JVM).

A typical example is when appending a path to the PATH environment variable: 

set.PATH=my_path%WRAPPER_PATH_SEPARATOR%%PATH%.
The above definition would cause 'my_path' to be added to PATH each time the configuration is reloaded.

We are currently working on a solution to fix this issue, but in the meantime a workaround is to make use of a temporary variable that is only set once: 

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

Default Environment Variable Definitions

On startup, the Wrapper sets the following environment variables into its own environment. These variables can be used within the configuration file "wrapper.conf" or by accessing the environment of the JVM or any of its child processes.

  • The WRAPPER_ARCH variable is set to the name of the architecture for which the currently running Wrapper was built. (Since ver. 3.3.0)

  • The WRAPPER_BASE_NAME variable is set to the binary name without the extension, and without the OS, architecture and bits (if included in the name). (Since ver. 3.5.41)

  • The WRAPPER_BIN_DIR variable is set to the location of the Wrapper binary on startup. It can be used to define paths relative to this location even if the current working directory is modified. (Since ver. 3.3.0)

  • The WRAPPER_BITS variable is set to the 32-bit or 64-bit depth for which the currently running Wrapper was built. (Since ver. 3.3.0)

  • The WRAPPER_EDITION variable is set to the edition of the Wrapper currently running. Possible values are "Community", "Standard" and "Professional". (Since ver. 3.5.36)

  • The WRAPPER_FILE_SEPARATOR variable is set to '\' on Windows and '/' on Linux/UNIX platforms, as a file separator. The variable can be used to set platform independent values for additional environment variables or properties. (Since ver. 3.1.0)

    In general it is safe to always use '/' as a file separator for paths used within Java. Java is designed to work correctly on all platforms when '/' is used.

  • The WRAPPER_HOSTNAME and WRAPPER_HOST_NAME variables are set to the resolved name of the machine where the Wrapper is currently running. (WRAPPER_HOST_NAME Since ver.3.3.2, WRAPPER_HOSTNAME Since ver.3.3.6)

  • The WRAPPER_INIT_DIR variable is set to the working directory of the process that launched the Wrapper process. The Wrapper always first forces the working directory to the location of the Wrapper binary while the configuration is loaded (see WRAPPER_BIN_DIR variable). Then if the user has configured another working directory, it will be changed to the location specified with the wrapper.working.dir property. This is all needed to make sure that the Wrapper runs 100% reliably with a given configuration regardless of where the Wrapper was launched from. Some applications need to know where the user was when they launched the Wrapper however. In those cases this variable can be used. (Since ver. 3.5.6)

    Example of Configuration file: 
    wrapper.java.additional.1=-myinit.working.dir="%WRAPPER_INIT_DIR%"
wrapper.java.additional.1.stripquotes=TRUE

  • The WRAPPER_JAVA_HOME variable is set on Windows platforms when the Java command is located using the system registry. In other cases, it is recommended that a JAVA_HOME variable be set. (Since ver. 3.3.0)

  • The WRAPPER_JAVA_VENDOR variable is set after the configuration is loaded and after parsing the output of the 'java -version' command sent to the JVM. The value is a string representing the Java vendor (JVM implementation) currently used. (Since ver. 3.5.37)

    It is possible to use this variable in any property value loaded after the Java version is parsed. This includes events properties, wrapper.java.additional_file and wrapper.app.parameter_file.

  • The WRAPPER_JAVA_VERSION variable is set after the configuration is loaded and after parsing the output of the 'java -version' command sent to the JVM. The value is a string representing the Java version currently used. (Since ver. 3.5.36)

    It is possible to use this variable in any property value loaded after the Java version is parsed. This includes events properties, wrapper.java.additional_file and wrapper.app.parameter_file.

  • The WRAPPER_JAVA_VERSION_MAJOR, WRAPPER_JAVA_VERSION_MINOR and WRAPPER_JAVA_VERSION_REVISION variables are set after the configuration is loaded and after parsing the output of the 'java -version' command sent to the JVM. They contain the 'major', 'minor', 'revision' component numbers of the Java version currently used. (Since ver. 3.5.36)

    It is possible to use this variable in any property value loaded after the Java version is parsed. This includes events properties, wrapper.java.additional_file and wrapper.app.parameter_file.

  • The WRAPPER_LANG variable is set to a lowercase two characters code representing the language being used by the Wrapper. On the Community edition, the value is always 'en'. One use for this is to include configuration file fragments which have localized values. (Since ver. 3.5.5)

    The following example shows how to localize the Windows Service display name and descriptions. Note that English is loaded explicitly first (or its properties could be defined first). This is to make sure that the English values exist as a default. The Wrapper will then overwrite them with values in the localized "include file" (cascading style).

    Example (wrapper.conf): 
    #encoding=UTF-8
#include ../conf/wrapper-en.conf
#include ../conf/wrapper-%WRAPPER_LANG%.conf
...
wrapper.ntservice.name=myapp
...
    Example (wrapper-en.conf): 
    #encoding=UTF-8
wrapper.ntservice.displayname=My App Server
wrapper.ntservice.description=Application Server that does cool stuff.
    Example (wrapper-de.conf): 
    #encoding=UTF-8
wrapper.ntservice.displayname=My App Server
wrapper.ntservice.description=Application Server that does cool stuff.

  • The WRAPPER_OS variable is set to the name of the OS for which the currently running Wrapper was built. (Since ver. 3.3.0)

    Example of Configuration file: 
    wrapper.java.library.path.1=../lib
wrapper.java.library.path.2=../lib/native/%WRAPPER_OS%-%WRAPPER_ARCH%-%WRAPPER_BITS%

    The example above resolves to the following:

    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

  • The WRAPPER_PATH_SEPARATOR variable is set to ';' on Windows and ':' on Linux/UNIX platforms. The variable can be used to build up platform independent paths. (Since ver. 3.1.0)

    Example of Configuration file: 
    set.PATH=..%WRAPPER_FILE_SEPARATOR%lib%WRAPPER_PATH_SEPARATOR%%PATH%

    The example above resolves to the following:

    Windows: 
    set.PATH=..\lib;%PATH%
    UNIX: 
    set.PATH=../lib:%PATH%

  • The WRAPPER_PID variable is set to the PID of the Wrapper process when it is launched. It can be used in file names like the PID file or log file to make sure that you get a unique file name when launching multiple copies of the Wrapper with the same configuration file. (Since ver. 3.3.7)

    Example of Configuration file: 
    wrapper.logfile=../logs/wrapper-%WRAPPER_PID%.log

  • The WRAPPER_RUN_MODE variable is set to "console" when running as a console, or "service" when running as a Windows Service / Unix Daemon. (Since ver. 3.5.41)

  • The WRAPPER_VERSION variable is set to the version of the Wrapper currently running. (Since ver. 3.5.36)

  • The WRAPPER_WORKING_DIR variable is set to the location of the Wrapper binary on startup, but will be changed to reflect the current working directory of the Wrapper when referenced by child processes. (Since ver. 3.3.0)

    The working directory of the Wrapper can be changed using the wrapper.working.dir property. Be sure to read the documentation, as its usage is a bit tricky.

    Please note however, that because of the way this property is set, it will always equal the WRAPPER_BIN_DIR variable when referenced in the Wrapper configuration file. The variable is set accurately within the environment however, and any child processes will see the directory which was set with the wrapper.working.dir property.

Pseudo-environment Variable Definitions

In addition to the above environment variables, the following variables are generated by the Wrapper without actually being stored in the environment.

The WRAPPER_RAND_NNNNNN and WRAPPER_TIME_YYYYMMDDHHIISS variables can be referenced multiple times in the configuration file, and may generate different values for each reference. For this reason they are not stored in the environment. You can however store the generated value for a single reference in your own environment variable using the "set.<X>" syntax, but be aware that each time the value of an environment variable is changed, the call to the underlying system function will result in a small memory leak. This should be taken into account if the configuration file can be reloaded multiple times as the value of these variables will be regenerated and change each time.

Example of a random value being stored in a custom environment variable: 
set.RAND_NNNNNN=%WRAPPER_RAND_NNNNNN%

  • The WRAPPER_PERCENTAGE variable is set to a single '%' character. Its usage is recommended to avoid a syntactic ambiguity when a property value contains two '%' characters, in which case a warning about a missing environment variable would be reported (the content between the two '%' being thought as a name of a variable). (Since ver. 3.3.38)

    Example (gc log file name will be correctly expanded to 'gc_%t_%p.log') 
    wrapper.java.additional.1=-Xloggc:C:\logs\gc_%WRAPPER_PERCENTAGE%t_%WRAPPER_PERCENTAGE%p.log

  • The WRAPPER_RAND_NNNNNN variable is set to a random number at each location it is used within the Wrapper configuration file. (Since ver. 3.3.4)

    Example of Configuration file: 
    wrapper.app.parameter.1=mytempfile-%WRAPPER_RAND_NNNNNN%.txt

    The value is set once when the configuration file is loaded and parsed. If the value should be set each time a JVM is launched, it is necessary to specify the wrapper.restart.reload_configuration=TRUE configuration property to cause the configuration to be reparsed prior to each JVM invocation.

    A different random number will be generated each place that the variable is specified. If it is necessary to reference the same random number in multiple locations, please first store the value into a local variable and then reference that as needed. For example:

    Example of Configuration file: 
    set.RNUM=%WRAPPER_RAND_NNNNNN%
wrapper.java.additional.1=-Dtempid=%RNUM%
wrapper.app.parameter.1=mytempfile-%RNUM%.txt

    Additional formats exist with random numbers composed of 1 to 6 digits: WRAPPER_RAND_N, WRAPPER_RAND_NN, WRAPPER_RAND_NNN, WRAPPER_RAND_NNNN, WRAPPER_RAND_NNNNN, and WRAPPER_RAND_NNNNNN.

  • The WRAPPER_SYSMEM_PP.P variable is set to a value calculated from a percentage of the amount of physical memory available on the system. (Since ver. 3.5.29)

    PP.P refers to the percentage of the system memory. Its value should be greater than 0 and up to 100. Out of this range, the variable will be ignored. The percentage can have decimals but the calculated value will be rounded to the next closest megabyte.

    This variable can be used in the wrapper.java.additional.<n> properties to set some JVM options like:

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

  • The WRAPPER_TIME_YYYYMMDDHHIISS variable is set to a timestamp at each location it is used within the Wrapper configuration file. The time returned is the time that the configuration file is loaded. The variable will return the same value when referenced multiple times in the same configuration file. (Since ver. 3.3.4)

    The following example demonstrates how to generate a timestamped file name and pass it to the JVM:

    Example of Configuration file: 
    wrapper.app.parameter.1=mytempfile-%WRAPPER_TIME_YYYYMMDDHHIISS%.txt

    The above example results in a value like:

    The result: 
    wrapper.app.parameter.1=mytempfile-20090409124532.txt

    The value is set once when the configuration file is loaded and parsed. If the value should be set each time a JVM is launched, it is necessary to specify the wrapper.restart.reload_configuration=TRUE configuration property to cause the configuration to be reparsed prior to each JVM invocation.

    The following additional formats can also be referenced: WRAPPER_TIME_YYYYMMDD_HHIISS, WRAPPER_TIME_YYYYMMDDHHII, WRAPPER_TIME_YYYYMMDDHH, and WRAPPER_TIME_YYYYMMDD.

Event Handler Variable Definitions

The following variables can be referenced in event properties and used when those events are fired. These variables are also pseudo-environment variables, meaning that they are not stored in the environment.

  • The WRAPPER_NAME variable is set to the value of the wrapper.name property. (Since ver. 3.3.0)

  • The WRAPPER_DISPLAYNAME variable is set to the value of the wrapper.displayname property. (Since ver. 3.3.0)

  • The WRAPPER_DESCRIPTION variable is set to the value of the wrapper.description property. (Since ver. 3.3.0)

  • The WRAPPER_EVENT_JVM_ID variable is set to an integer value starting with 1, indicating how many times the JVM has been restarted. Only set for "jvm_*" events. (Since ver. 3.3.0)

  • The WRAPPER_EVENT_JVM_PID variable is set to an integer value containing the PID of the JVM process. Only set for "jvm_*" events with the exception of the "jvm_prelaunch" event. (Since ver. 3.3.0)

  • The WRAPPER_EVENT_NAME variable is set to the name of the event being fired. (Since ver. 3.3.0)

  • The WRAPPER_EVENT_RAND_NNNNNN variable is set to a random number whose value changes each time the event fires. (Since ver. 3.5.25)

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

    The above example will cause two random numbers to be generated. The first, WRAPPER_RAND_NNNNNN, will be set once each time the Wrapper configuration file is loaded, but the second, WRAPPER_EVENT_RAND_NNNNNN, will change for each event. It is not possible to reuse the same value of WRAPPER_EVENT_RAND_NNNNNN because of the way its value is dynamically resolved.

    Additional formats exist with random numbers composed of 1 to 6 digits: WRAPPER_EVENT_RAND_N, WRAPPER_EVENT_RAND_NN, WRAPPER_EVENT_RAND_NNN, WRAPPER_EVENT_RAND_NNNN, WRAPPER_EVENT_RAND_NNNNN and WRAPPER_EVENT_RAND_NNNNNN.

  • The WRAPPER_EVENT_TIME_YYYYMMDDHHIISS variable is set to a timestamp each time the event fires. (Since ver. 3.5.25)

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

    The above example will reference two timestamps. The first, WRAPPER_TIME_YYYYMMDDHHIISS, will be set once each time the Wrapper configuration file is loaded, but the second, WRAPPER_EVENT_TIME_YYYYMMDDHHIISS, will change for each event. The same time will be used throughout the execution of the event, so it is possible to make use of multiple time references.

    The following additional formats can also be referenced: WRAPPER_EVENT_TIME_YYYYMMDD_HHIISS, WRAPPER_EVENT_TIME_YYYYMMDDHHII, WRAPPER_EVENT_TIME_YYYYMMDDHH, and WRAPPER_EVENT_TIME_YYYYMMDD.

  • The WRAPPER_EVENT_WRAPPER_PID variable is set to an integer value containing the PID of the Wrapper process. (This environment variable is an alias of the WRAPPER_PID environment variable and is maintained only for backwards compatibility.) (Since ver. 3.3.0)