Server configuration overview

The Open Liberty server config is made up of one mandatory file, the server.xml file, and a set of optional files. The server.xml file must be well-formed XML and the root element must be server. When the server.xml file is processed, any elements or attributes that are not understood are ignored.

This example server.xml file configures the server to do the following things:

<server description="new server">
        <feature>jsp-2.3</feature> (1)
    <httpEndpoint id="defaultHttpEndpoint"
                  httpPort="9080" (2)
                  httpsPort="9443" />
    <applicationManager autoExpand="true" /> (3)
1 Support the JavaServer Pages 2.3 feature
2 Listen to incoming traffic to localhost on port 9080
3 Automatically expand WAR files when they are deployed

The term server config can be used to refer to all of the files that make up the server config, or specifically to the config that’s in the XML files. If it’s not clear in context, the term server XML config might be used to refer to the config in the XML files.

Config files

The server config files are processed in the following order:

  1. server.env - Environment variables are specified in this file.

  2. jvm.options - JVM options are set in this file.

  3. - This file influences the startup of the Open Liberty server.

  4. server.xml - This mandatory file specifies the server config and features.


The server.env files are optional. These files are read by the bin/server shell script and specify environment variables that are primarily used to influence the behavior of the bin/server script. server.env files are read from the following locations in order:

  1. ${wlp.install.dir}/etc/

  2. ${wlp.user.dir}/shared/

  3. ${server.config.dir}/

If the same property is set in multiple locations, then the last value found is used.

The most common use of these files is to set the following environment variables:

  • JAVA_HOME - Indicates which JVM to use. If this is not set, the system default is used.

  • WLP_USER_DIR - Indicates the location of the usr directory that contains the server config. This can only be set in the etc/server.env file because the other locations are relative to the usr directory.

  • WLP_OUTPUT_DIR - Indicates where the server writes files to. By default, the server writes to the directory structure that the config is read from. However, in some secure profiles the server config needs to be read-only so the server must write files to another location.

The server.env file is in KEY=value format, as shown in the following example:


Key values must not contain spaces. The values are interpreted literally so you don’t need to escape special characters, such as spaces. These files don’t support variable substitution.


The jvm.options files are optional. These files are read by the bin/server shell script to determine what options to use when the JVM is launched for Open Liberty. jvm.options files are read from the following locations in order:

  1. ${wlp.user.dir}/shared/jvm.options

  2. ${server.config.dir}/configDropins/defaults/

  3. ${server.config.dir}/

  4. ${server.config.dir}/configDropins/overrides/

If no jvm.options files exist in these locations, then the server script looks for the file in ${wlp.install.dir}/etc, if such a directory exists.

Common uses of jvm.options files include:

  • Setting JVM memory limits

  • Enabling Java Agents that are provided by monitoring products

  • Setting Java System Properties

The jvm.options file format uses one line per JVM option, as shown in the following example:

-Dmy.system.prop=This is the value.

You don’t need to escape special characters, such as spaces. Options are read and provided to the JVM in order. If you provide multiple options, then they are all seen by the JVM. These files do not support variable substitution.

The file is optional. This file is read during Open Liberty bootstrap to provide config for the earliest stages of the server startup. It is read by the server earlier than the server.xml file so it can affect the startup and behavior of the Open Liberty kernel from the start. The file is a simple Java properties file and is located in ${server.config.dir}. A common use of the file is to configure logging because it can affect logging behavior before the server.xml file is read.

The file supports a special optional property, bootstrap.include, which specifies another properties file to also be read during the bootstrap stage. For example, this boostrap.include file can contain a common set of bootstrap properties for multiple servers to use. Set the bootstrap.include file to an absolute or relative file path.


The most important and only required config file is the server.xml file. The server.xml file must be well-formed XML and the root element must be server. The exact elements that are supported by a server depend on which features are configured, and any unknown config is ignored.

Open Liberty uses a principle of configuration by exception, which allows for succinct config files. The runtime environment operates from a set of built-in config default settings. You only specify config that overrides those default settings.

Server config files are read from the following locations in order:

  1. ${server.config.dir}/configDropins/defaults/

  2. ${server.config.dir}/server.xml

  3. ${server.config.dir}/configDropins/overrides/

The ${server.config.dir}/server.xml file must be present, but the other files are optional. You can flexibly compose config by dropping server-formatted XML files into directories. Files are read in alphabetical order in each of the two configDropins directories.

Variable substitution

You can use variables to parameterize the server config. To resolve variable references to their values, the following sources are consulted in order:

  1. server.xml default variable values

  2. environment variables


  4. Java system properties

  5. server.xml config

  6. variables declared on the command line

Variables are referenced by using the ${variableName} syntax. Specify variables in the server config, as shown in the following example:

<variable name="variableName" value="some.value" />

Default values, which are specified in the server.xml file, are used only if no other value is specified:

<variable name="variableName" defaultValue="some.default.value" />

You can also specify variables at startup from the command line. If you do, the variables that are specified on the command line override all other sources of variables and can’t be changed after the server starts.

Environment variables can be accessed as variables. As of version, you can reference the environment variable name directly. If the variable cannot be resolved as specified, the server.xml file looks for the following variations on the environment variable name:

  • Replace all non-alphanumeric characters with the underscore character (_)

  • Change all characters to uppercase

For example, if you enter ${my.env.var} in the server.xml file, it looks for environment variables with the following names:

  1. my.env.var

  2. my_env_var


For versions and earlier, you can access environment variables by adding env. to the start of the environment variable name, as shown in the following example:

<httpEndpoint id="defaultHttpEndpoint"
              httpPort="9080" />

Variable values are always interpreted as a string with simple type conversion. Therefore, a list of ports (such as 80,443) might be interpreted as a single string rather than as two port numbers. You can force the variable substitution to split on the , by using a list function, as shown in the following example:

<mongo ports="${list(mongoPorts)}" hosts="${list(mongoHosts)}" />

Simple arithmetic is supported for variables with integer values. The left and right sides of the operator can be either a variable or a number. The operator can be +, -, *, or /, as shown in the following example:

<variable name="one" value="1" />
<variable name="two" value="${one+1}" />
<variable name="three" value="${one+two}" />
<variable name="six" value="${two*three}" />
<variable name="five" value="${six-one}" />
<variable name="threeagain" value="${six/two}" />

There are a number of predefined variables:

  • wlp.install.dir - the directory where the Open Liberty runtime is installed.

  • - the name of the server.

  • wlp.user.dir - the directory of the usr folder. The default is ${wlp.install.dir}/usr.

  • - the directory of shared applications. The default is ${wlp.user.dir}/shared/apps.

  • shared.config.dir - the directory of shared config files. The default is ${wlp.user.dir}/shared/config.

  • shared.resource.dir - the directory of shared resource files. The default is ${wlp.user.dir}/shared/resources.

  • server.config.dir - the directory where the server config is stored. The default is ${wlp.user.dir}/servers/${}.

  • server.output.dir - the directory where the server writes the workarea, logs, and other runtime-generated files. The default is ${server.config.dir}.

Config merging

Since the config can consist of multiple files, it is possible that two files provide the same config. In these situations, the server config is merged according to a set of simple rules. In Open Liberty, config is separated into singleton and factory config, each of which has its own rules for merging. Singleton config is used to configure a single element (for example, logging). Factory config is used to configure multiple entities, such as an entire application or data source.

Merging singleton config

For singleton config elements that are specified more than once, the config is merged. If two elements exist with different attributes, both attributes are used. For example:

    <logging a="true" />
    <logging b="false" />

is treated as:

    <logging a="true" b="false" />

If the same attribute is specified twice, then the last instance takes precedence. For example:

    <logging a="true" b="true" />
    <logging b="false" />

is treated as:

    <logging a="true" b="false" />

Config is sometimes provided by using child elements that take text. In these cases, the config is merged by using all of the values specified. The most common scenario is configuring features. For example:


is treated as:


Merging factory config

Factory config merges use the same rules as singleton config except elements are not automatically merged just because the element names match. With factory config, it is valid to configure the same element and mean two different logical objects. Therefore, each element is assumed to configure a distinct object. If a single logical object is configured by two elements, the id attribute must be set on each element to indicate they are the same thing. Variable substitution on an id attribute is not supported.

The following example configures two applications. The first application is myapp.war, which has a context root of myawesomeapp. The other application is myapp2.war, which has myapp2 as the context root:

    <webApplication id="app1" location="myapp.war" />
    <webApplication location="myapp2.war" />
    <webApplication id="app1" contextRoot="/myawesomeapp" />

Include processing

In addition to the default locations, additional config files can be brought in by using the include element. When a server config file contains an include reference to another file, the server processes the contents of the referenced file as if they were included inline in place of the include element. In the following example, the server processes the contents of the other.xml file before it processes the contents of the other2.xml file:

    <include location="other.xml" />
    <include location="other2.xml" />

By default, the include file must exist. If the include file might not be present, set the optional attribute to true, as shown in the following example:

    <include location="other.xml" optional="true" />

When you include a file, you can specify the onConflict attribute to change the normal merge rules. You can set the value of the onConflict attribute to IGNORE or REPLACE any conflicting config:

    <include location="other.xml" onConflict="IGNORE" />
    <include location="other2.xml" onConflict="REPLACE" />

You can set the location attribute to a relative or absolute file path, or to an HTTP URL.

Config references

Most config in Open Liberty is self-contained but it is often useful to share config. For example, the JDBC driver config might be shared by multiple data sources. You can refer to any factory config element that is defined as a direct child of the server element.

A reference to config always uses the id attribute of the element that is being referenced. The config element that makes the reference uses an attribute that always ends with Ref, as shown in the following example:

  <dataSource jndiName="jdbc/fred" jdbcDriverRef="myDriver" />
  <jdbcDriver id="myDriver" />

Dynamic updates

The server monitors the server XML config for updates and dynamically reloads when changes are detected. Changes to non-XML files (server.env,, and jvm.options) are not dynamic because they are only read at startup. Any server XML config file on the local disk is monitored for updates every 500ms. You can configure the frequency of XML config file monitoring. For example, to configure the server to monitor every 10 minutes, specify:

<config monitorInterval="10m" />

To disable file system polling and reload only when an MBean is notified, specify:

<config updateTrigger="mbean" />

Log messages

When the server runs, it might output log messages that reference config. The references in the log use an XPath-like structure to specify config elements. The element name is given with the value of the id attribute inside square brackets. If no id is specified in the server config, an id is automatically generated. Based on the following server XML config example, the dataStore element and the child dataSource are identified in the logs as dataStore[myDS] and dataStore[myDS]/dataSource[default-0].

    <dataStore id="myDS">
        <dataSource />