Overview: Configuration File Directives

As the Java Service Wrapper parses its configuration file, in most cases, it will ignore all text that comes after a '#' character and treat it as a comment. There are a small set of exceptions to this rule, however.

The Wrapper historically followed the C language pattern of defining special directives which are processed as the configuration file is loaded.

Configuration File Encoding

Starting with Wrapper version 3.5.0, it became possible to specify the encoding of individual configuration files. The most portable encoding is UTF-8, but other encodings are supported on some platforms.

The encoding directive must be specified on the first line of a configuration file. The Wrapper will log a warning if any file is missing the directive. It is possible to specify different encodings in include files (cascading style)

UTF-8 Example: 
#encoding=UTF-8

wrapper.debug=FALSE
...

Include Cascading Configuration File

It is possible to split a configuration in one or more optional configuration files and then include them from the main file. See the Cascading Configuration File ("include file") page for more information.

Example: 
#include ../conf/wrapper-settings.conf

By design, the Wrapper will silently skip over any include files that it is unable to locate or read for any reason. This can be very powerful, as it makes it possible to create platform specific configurations or optionally override existing property values.

In some cases, however, an include file is required for proper operation of an application. Starting with Wrapper version 3.5.5, it is possible to specify a required include, which will cause an error and prevent the Wrapper from starting if it is missing.

Example: 
#include.required ../conf/wrapper-settings.conf

Debug Include Files

Starting with Wrapper version 3.3.0, it is possible to debug the way the #include directive works by seeing exactly what is and isn't being included. See the Debug Messages in the "include file" (cascading style) page for more information.

Example: 
#include.debug

Debug Properties

Starting with Wrapper version 3.5.4, it is possible configure the Wrapper so that it outputs a message on startup whenever any property is overwritten by another declaration, or when a property can not be set because its value is fixed.

Wrapper version 3.5.27 improves this feature. It is now possible to control the log level of these messages and to specify if the Wrapper should exit after logging them. You could also apply different settings per sections of your configuration files and thus allow to be more or less strict in some parts. This can be achieved using two new directives:

Depending on the nature of the properties, the Wrapper will output different messages. These messages are described below.

NOTE

These messages are only logged on debug mode by default because it is common practice to overwrite property values using optional Cascading Configuration File ("include file"), or other methods.

WARNING

Because the properties wrapper.name and wrapper.displayname are defined in the UNIX shell script, if you use this script to launch the Wrapper and if you debug the properties using the above directives, you may get warning messages as those variables are also defined by default in the configuration file.

You can avoid these messages by either removing the redundant properties in the configuration file or by uncommenting the line '#APP_NAME_PASS_TO_WRAPPER=false' in the script file.

The second option will cause the script to no longer pass these parameters to the Wrapper. Be careful not to deactivate the properties 'APP_NAME' and 'APP_LONG_NAME', which are required to the proper functioning of the script.

Messages

To help understand why a property has a specific value, it can be useful to visualize when its value has been changed, or on the contrary, when it has been ignored despite an attempt to overwrite it.

Here are the messages you can get:

Overlapped Properties:

The Wrapper is setup so that the last defined instance of a specific property will be used. This can be very powerful as default values can be setup and then reference an optional include file which could contain values specific to a system.

Property Redefinition Example: 
STATUS | wrapper  | The "foo.bar" property was redefined on line #8 of configuration file: /home/wrapper/conf/wrapper.conf
STATUS | wrapper  |   Old Value foo.bar=123
STATUS | wrapper  |   New Value foo.bar=XYZ

Command line Properties:

Property values specified on the Wrapper command line are 'final', meaning that they can not be changed or overwritten by values in the configuration file. This is very useful because a user can run the Wrapper with a test value without having to actually edit the configuration file.

Final Property Redefinition Example: 
STATUS | wrapper  | The "foo.bar" property was defined on the Wrapper command line and can not be overwritten.
STATUS | wrapper  |   Ignoring redefinition on line #8 of configuration file: /home/wrapper/conf/wrapper.conf
STATUS | wrapper  |   Fixed Value foo.bar=123
STATUS | wrapper  |   Ignored Value foo.bar=XYZ

Internal Environment Variables:

The Wrapper also sets several internal environment variables. These are done using final properties. If the user configuration file attempts to set any of these, then the Wrapper will ignore them and maintain the values set by the Wrapper.

Final Property Redefinition Example: 
STATUS | wrapper  | The "set.WRAPPER_ARCH" property is defined by the Wrapper internally and can not be overwritten.
STATUS | wrapper  |   Ignoring redefinition on line #10 of configuration file: /home/wrapper/conf/wrapper.conf
STATUS | wrapper  |   Fixed Value set.WRAPPER_ARCH=x86
STATUS | wrapper  |   Ignored Value set.WRAPPER_ARCH=special

#properties.on_overwrite.loglevel
Compatibility :3.5.27
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

This directive is used to set the log level at which the messages should be logged.

Valid values include:

  • AUTO: a default value to automatically resolve the log level (see below).

  • NOTICE: to log at the NOTICE log level.

  • ADVICE: to log at the ADVICE log level.

  • FATAL: to log at the FATAL log level.

  • ERROR: to log at the ERROR log level.

  • WARN: to log at the WARN log level.

  • STATUS: to log at the STATUS log level.

  • INFO: to log at the INFO log level.

  • DEBUG: to log at the DEBUG log level.

The default value is AUTO which is resolved to 'WARN' whenever a property is overridden within the same configuration file or in a file with a lower include depth than the file of the earlier definition. It is also resolved to 'WARN' when a final property embedded during customization is overridden. In all other cases, it is resolved to 'DEBUG'.

NOTE

Prior to version 3.5.36, the default value of this directive was DEBUG.

Example (log the overwritten properties at a warning level): 
#properties.on_overwrite.loglevel=WARN

NOTE

Use of the directive #properties.debug has been deprecated as of Wrapper version 3.5.27 in favor of those new directives that offer finer control on debugging properties. For backwards compatibility #properties.debug will have the same effect as #properties.on_overwrite.loglevel=STATUS.

#properties.on_overwrite.exit
Compatibility :3.5.27
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

This directive is used to specify if the Wrapper should exit if any property is overwritten.

Valid values include:

  • TRUE: specifies that the Wrapper should exit if any property following this directive is overwritten.

  • FALSE: specifies that the Wrapper should not exit if any property following this directive is overwritten.

The default value is FALSE.

Example (exit if any overwritten property is encountered): 
#properties.on_overwrite.exit=TRUE

Usage

A directive is valid from the line where it is inserted in the configuration file until the end of the file or until a next directive with the same name is encountered. If found, the value of the new directive will then become valid for the section following in the configuration file.

When #properties.on_overwrite.exit is set to TRUE, the value of #properties.on_overwrite.loglevel is automatically raised to FATAL (if set to a lower level). This remains as long as #properties.on_overwrite.exit is not reset to FALSE.

Example: 
wrapper.name=@app.name@
wrapper.lang.folder=../lang
...

#properties.on_overwrite.loglevel=STATUS
wrapper.lang.folder=../../lang
...

#properties.on_overwrite.loglevel=INFO
wrapper.name=newAppName
...

#properties.on_overwrite.exit=TRUE
wrapper.app.parameter.3=start
...

wrapper.app.parameter.3=start_app
...

#properties.on_overwrite.exit=FALSE
...

In the above configuration, wrapper.lang.folder will be logged with a 'STATUS' level, wrapper.name will be logged with an 'INFO' level, and wrapper.app.parameter.3 will be logged at a 'FATAL' level causing the Wrapper to exit. Any property following '#properties.on_overwrite.exit=FALSE' will not cause the Wrapper to exit and will be logged with an 'INFO' level, as previously set.

NOTE

Starting with version 3.5.27, the Wrapper will also log messages if the command line contains duplicated properties or attempts to set an internal environment variable.

You can still use #properties.on_overwrite.loglevel and #properties.on_overwrite.exit to control the log level at which these messages should appear and to specify if the Wrapper should exit after logging them. If several directives are set in the configuration file, the last directive of each type will apply.

Toggle Variable Expansion
Compatibility :3.5.55
Editions :Professional EditionStandard EditionCommunity Edition
Platforms :WindowsMac OSXLinuxIBM AIXFreeBSDHP-UXSolarisIBM z/Linux

Any configuration property value can reference variables with the following syntax: %MYVAR%. For more details on how to define a variable and the list of predefined variables, please refer to this page.

Starting with Wrapper version 3.5.55, it is possible to enable or disable variable expansion (i.e. the replacement of above syntactic notation with the value of the variable) for sections of the configuration file.

By default (if this directive is not used), variables expansion is enabled. You can disable it by adding '#variables.expand=FALSE' anywhere in your configuration file. The properties referenced on subsequent lines will not expand variables. '#variables.expand=TRUE' allows you to re-enable variable expansion starting from a certain line.

Example: 
set.MYVAR=some_value

#variables.expand=FALSE

# %MYVAR% will not be expanded
wrapper.app.parameter.1=%MYVAR% 

#variables.expand=TRUE

# %MYVAR% will be expanded to 'some_value'
wrapper.app.parameter.2=%MYVAR%

NOTE

Disabling variable expansion only applies to the current configuration file, and not to include files. If a file is included after #variables.expand was set to FALSE, the variables referenced in the include file will expand unless the file itself also specifies #variables.expand=FALSE.

Why is it useful?

In some cases, you may need to use the '%' character in a property value. When this character is referenced two times in the same value, they will be interpreted as delimiters for a variable, even if you did not intend to reference a variable.

Example: (the following value will generate a warning 'The '20with' environment variable was referenced but has not been defined.') 
wrapper.app.parameter.1=http://url%20with%20spaces

To work around this issue, a possibility is to use a special variable %WRAPPER_PERCENTAGE% which value is a single '%' character.

Example: (will expand to 'http://url%20with%20spaces' without generating a warning) 
wrapper.app.parameter.1=http://url%WRAPPER_PERCENTAGE%20with%WRAPPER_PERCENTAGE%20spaces

However, this can make the value more difficult to read, especially if '%' is used many times.

#variables.expand offers an alternative to completely disable variable expansion if you know that certain parts of your configuration do not reference any variable and should use the '%' character without being interpreted as variable delimiters.

Reference: Loglevel