Server configuration overview

The Open Liberty server configuration 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">
    <featureManager>
        <feature>jsp-2.3</feature> (1)
    </featureManager>
    <httpEndpoint id="defaultHttpEndpoint"
                  httpPort="9080" (2)
                  httpsPort="9443" />
    <applicationManager autoExpand="true" /> (3)
</server>
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 configuration can be used to refer to all of the files that make up the server configuration or specifically to the configuration that’s in the XML files. If it’s not clear in context, the term server XML configuration might be used to refer to the configuration in the XML files.

Configuration files

The server configuration 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. bootstrap.properties - This file influences the startup of the Open Liberty server.

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

server.env

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 configuration 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 configuration is read from. However, in some secure profiles the server configuration 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:

JAVA_HOME=/opt/ibm/java
WLP_USER_DIR=/opt/wlp-usr

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.

jvm.options

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:

-Xmx512m
-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.

bootstrap.properties

The bootstrap.properties file is optional.

This file is read during Open Liberty bootstrap to provide configuration 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 bootstrap.properties file is a simple Java properties file and is located in ${server.config.dir}. A common use of the bootstrap.properties file is to configure logging because it can affect logging behavior before the server.xml file is read.

The bootstrap.properties 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.

server.xml

The most important and only required configuration 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 configuration is ignored.

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

Server configuration 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 configuration 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 configuration. To resolve variable references to their values, the following sources are consulted in order:

  1. server.xml file default variable values

  2. environment variables

  3. bootstrap.properties

  4. Java system properties

  5. server.xml file configuration

  6. variables declared on the command line

Variables are referenced by using the ${variableName} syntax.

Specify variables in the server configuration 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 19.0.0.3, 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

  3. MY_ENV_VAR

For versions 19.0.0.3 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"
              host="${env.HOST}"
              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.

  • wlp.server.name - the name of the server.

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

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

  • shared.config.dir - the directory of shared configuration 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 configuration is stored. The default is ${wlp.user.dir}/servers/${wlp.server.name}.

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

Configuration merging

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

Merging singleton configuration

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

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

is treated as:

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

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

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

is treated as:

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

Configuration is sometimes provided by using child elements that take text.

In these cases, the configuration is merged by using all of the values specified. The most common scenario is configuring features. For example:

<server>
    <featureManager>
        <feature>servlet-4.0</feature>
    </featureManager>
    <featureManager>
        <feature>restConnector-2.0</feature>
    </featureManager>
</server>

is treated as:

<server>
    <featureManager>
        <feature>servlet-4.0</feature>
        <feature>restConnector-2.0</feature>
    </featureManager>
</server>

Merging factory configuration

Factory configuration merges use the same rules as singleton configuration except elements are not automatically merged just because the element names match. With factory configuration 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:

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

Include processing

In addition to the default locations, additional configuration files can be brought in by using the include element. When a server configuration 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:

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

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:

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

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:

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

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

Configuration references

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

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

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

Dynamic updates

The server monitors the server XML configuration for updates and dynamically reloads when changes are detected. Changes to non-XML files (server.env, bootstrap.properties, and jvm.options) are not dynamic because they are only read at startup. Any server XML configuration file on the local disk is monitored for updates every 500ms. You can configure the frequency of XML configuration 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 configuration. The references in the log use an XPath-like structure to specify configuration elements. The element name is given with the value of the id attribute inside square brackets. If no id is specified in the server configuration an id is automatically generated. Based on the following server XML configuration example, the dataStore element and the child dataSource are identified in the logs as dataStore[myDS] and dataStore[myDS]/dataSource[default-0].

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