Using variables in configuration files

You can use variables in the configuration to avoid hardcoding values that might not be appropriate when the configuration is reused in different environments.

About this task

Variables can be defined by setting a property in any of the following places:
  • in the server configuration file, or an included file
  • in the file
The following predefined variables can be referenced:
If the same variable is specified in multiple places, the precedence is as follows:
  • variables in override the process environment variables
  • variables in server.xml, or included XML files, override the variables in and process environment variables
Best practice: Variables that are specific to a particular server, for example port numbers, are specified in the file, allowing the server.xml to be shared across multiple servers while you keep those values different in each server. Variables that are shared across a group of servers, for example database configuration for a particular host, is better specified in an xml file that is included into the parent configuration file.
Best practice: Variable names must begin with an alphabetic character, and must contain the following characters only: alphabetic characters, numeric characters, and the "_" and "." characters.


  • Specify a variable in a configuration file.

    The variable definition syntax is variable_name=value. If the value contains a path, it is normalized during configuration processing by replacing repeated forward and backward slashes with a single forward slash, unless the value starts with double forward or backward slashes, which remain unchanged.

    Best practice: If you need to set the value of a variable to contain repeated forward slashes, as are sometimes used for JDBC driver connection URLs, break the value into two parts at the double slashes. By placing the double forward slashes as the initial characters, normalization is avoided. For example, to store the value "jdbc:db2://", use two variables:
    Variables that are defined in the configuration files are scoped to the configuration elements by which they are used. For example, the following code fragment creates a variable that is called updateTrigger_var to be used in applicationMonitor configuration elements:
    <applicationMonitor updateTrigger_var="mbean" />
    To create a variable that is used in a particular configuration instance (such as an application or resource entry), you must also specify the instance identifier. For example:
    <httpEndpoint id="defaultHttpEndpoint" HTTP_default_var="8889" />
  • Specify a variable in the file.
    Variables that are defined in the file are not scoped to particular configuration elements. You enter the variables as key-value pairs. For example:
  • Use a defined variable in the configuration.
    The variable substitution syntax is ${variable_name}. Multiple variable values can be concatenated by specifying ${variable_name1}${variable_name2}. For example, to use the HTTP_default_var variable, add the following code fragment to the configuration file:
    <httpEndpoint id="defaultHttpEndpoint"
  • Use variable element in the configuration.
    You can use the variable element to define a variable globally in the server configuration. If the same variable is defined in an included file, it is overridden by the one in the server.xml file. For example, to use the variable element, add the following code fragment to the configuration file:
    <variable name="HTTP_default_var" value="8889" />
  • Use process environment variables in the configuration.

    Process environment variables are available if you use the env. configuration variable prefix, for example:

    <fileset dir="${env.LIBRARY_DIR}" includes="*.jar"/>

    For more information on specifying environment variables, see Customizing the Liberty environment.

  • Use list variables in the configuration.
    Normally variables cannot express a comma-separated list of values for use in a multi-valued configuration attribute. Variables that contain commas are interpreted as a single String rather than multiple values. It is possible to interpret a variable as a comma-separated list of values by specifying the variable name with ${list(...)}. For example:
    <variable name="ports" value="80,9080"/>

    ${ports} is interpreted as the string "80, 9080".

    ${list(ports)} is interpreted as a collection containing the strings "80" and "9080".

  • Use variable expressions in configuration.
    For configuration variables, you can use a limited variable expression syntax with the format ${<operand><operator><operand>}. The description of the variable is as follows:
    Operands can either be long integer literals or the name of a variable that contains a long integer value. Variable names must begin with an alphabetic character, and must contain the following characters only: alphabetic characters, numeric characters, and the "_" and "." characters.
    The available operators are as follows:
    • + for addition
    • - for subtraction
    • * for multiplication
    • / for division
    If the expression cannot be parsed, a non-integer value is used, or an arithmetic error occurs, then the behavior is undefined.
    For example, if the HTTP_port_base variable is defined, a variable expression might be used to define multiple httpEndpoints:
    <httpEndpoint id="defaultHttpEndpoint" httpPort="${HTTP_port_base+0}"/>
    <httpEndpoint id="httpEndpoint2" httpPort="${HTTP_port_base+1}"/>
  • Override inheritable attributes in the configuration.

    You can override the default values of inheritable attributes in the configuration. The inheritable attributes are listed on the Liberty features page. You can identify the elements with the inherited attributes by looking for Inherits type. For example, the onError attribute is one of inheritable attributes. You can define a variable name for the onError attribute globally by either setting it in the or server.xml file with a variable element. If the same variable name is specified in both files, the value in the server.xml file is used. If the attribute is not explicitly set in either of two files, it uses the default value. If an invalid value is set to the inheritable attribute, the attribute value falls back to the global value defined in or server.xml file or the default value if not defined at the global level.

    Another example is logging properties in Liberty.