Server configuration overview

The server configuration files are processed in the following order:

Variables define reusable values that are substituted with actual values at runtime. In Open Liberty server configuration files, you can reference variables by using the ${variable.name} syntax. The dollar sign ($) indicates the start of a variable reference. Curly brackets ({}) enclose the name of the variable.

For example, if you define a variable that is named database.url with the value jdbc:mysql://localhost:3306/mydb, you can reference it in your server configuration files by using ${database.url}. At runtime, Open Liberty replaces ${database.url} with the actual value jdbc:mysql://localhost:3306/mydb.

For more information about specifying variables, see Variable substitution precedence.

You can use variables to parameterize the server configuration. To resolve variable references to their values, the following sources are consulted in order, in increasing order of precedence, meaning that later sources supersede and take precedence over earlier sources:

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

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

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

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

The VARIABLE_SOURCE_DIRS environment variable specifies directories from which variables can be loaded. If this environment variable is not specified, the default location for the variable directory is ${server.config.dir}/variables. To define a list of directories as the value for this variable, separate each directory with the path separator for your operating system. For Windows, the path separator is a semicolon (;). For Unix-based systems, the path separator is a colon (:).

The name of the file is used as the variable name, and the contents of the file are used as the variable value. For example, you can create a file in the variables directory that is named httpPort with the text string 9080 as the only content. You can then use the variable ${httpPort} in the server.xml file and it resolves to 9080.

If you create a file in a directory within the variables directory, then the parent directory is added to the variable name. For example, you can create a ${httpPort} file in the ports subdirectory within the variable directory, the variable name is ${ports/httpPort}.

Variables in the VARIABLE_SOURCE_DIRS directories can also be defined in properties files. If the name of the file ends in .properties, each property in the file is used to create a variable. For example, you can create a file that is named ports.properties with the following contents:

With this configuration, you can specify the ${httpPort} and ${httpsPort} variables in your server.xml file and their values resolve to 9080 and 9443.

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:

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:

The following predefined variables exist:

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.

You can include additional configuration resources in your server configuration by using the include element. When a server configuration file contains an include reference to another resource, the server processes the contents of the referenced resource 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:

You can set the location attribute for the include element to a relative or absolute file path, a directory, or to a URI for a remote resource.

When you specify a directory as the location value, the server processes only the files that are directly within the specified directory and ignores any subdirectories. The server processes the files within the directory in alphabetical order.

In this example, configuration files within the ./common/ directory are processed alphabetically on server startup.

When the server processes configuration files within directories, it switches the file names into lowercase and sorts them alphabetically to ensure that the file processing order is consistent and predictable. However, if two files are specified in the same directory with the same name except for case variations (such as extraConfig.xml and ExtraConfig.xml), the ordering behavior is indeterminate.

When you specify a directory in the include location, you must append a slash (/) to the directory name. For example, location="./common/". Omitting the slash after the directory name (location="./common") results in an error.

When you include configuration from a URI for a remote resource, the location attribute must point to a single remote resource file and not a directory. For example, https://website.com/path/to/server.xml is supported, but https://website.com/path/to/directory is not.

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

When you include a resource, 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:

For configuration files that are brought in from a directory by using the include element, the onConflict attribute is applied to each file in that directory separately. For example:

Functionally, this configuration is the same as including each file separately with its own onConflict attribute, as shown in the following example:

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:

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:

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

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