Unblu 4.1

Unblu Server Configuration

1. Introduction

The unblu server supports a wide range of configuration settings (see Unblu Server Configuration Reference). This page describes the steps required to use unblu configuration settings in your server installation.

Configuration settings are key/value pairs that are passed to the unblu server (using one of the mechanisms described below).

Unblu configuration settings are case insensitive (regarding keys). For better readability configuration setting keys are written in camel case ( in the documentation and references.

2. Using Configuration Files

The most common way to set configuration settings is to use a configuration file. Unblu configuration files use the java properties file format (see

In order to use a configuration file, you need to specify where the unblu server should load the configuration file from using the "com.unblu.propertyoverlay" Java System Property.

The value of the "com.unblu.propertyoverlay" Java System Property must point to a valid java properties file. It can be a local file system path (absolute or relative) or any valid url supported by Java (i.e. http://<host>/<pathtoconfigurationfile> or file:///etc/unblu/ We recommend always using forward slashes ("/") as the delimiter between path elements (also on windows systems) as using other delimiters (such as back slashes) only works if they are escaped properly.

How Java System Properties are specified depends on the server software you are using. A general way to set the "com.unblu.propertyoverlay" Java System Property is using the following notation when the Java process is started:

java -Dcom.unblu.propertyoverlay=/etc/unblu/ com.mycompany.mypackage.MyMainClass

Many Java Application Servers support OS environment variables for setting additional Java System Properties. Tomcat, for instance, supports the "JAVA_OPTS" OS environment variable for declaring additional System Properties

# example that adds a com.unblu.propertyoverlay System Property using the JAVA_OPTS environment variable
export JAVA_OPTS="$JAVA_OPTS -Dcom.unblu.propertyoverlay=/etc/unblu/"

3. Configuration File Format

Unblu configuration files use java properties file format. The java properties file format is a simple text-based format that consists of key/value pairs that are delimited by the equals sign ("="). Every key/value must start on a new line. You can use \ to escape newlines or other special characters. Blank lines are ignored. Lines that start with # are comments. Please see for more details about the java properties file format.

CAUTION: The Java properties file must always be encoded using the ISO-88591-1 character encoding. Make sure any special characters are escaped properly. (See

4. Using System Properties directly

In addition to using configuration files (or as an alternative), it is also possible to set configuration settings using Java System Properties directly. If you want to set the "com.unblu.logging.outputDirectory" configuration setting you can do this by defining "com.unblu.logging.outputDirectory" as a Java System Property directly (instead of using an external properties file as described above).

# example for how to use a Java System Property to set an unblu configuration setting using the -D notation in an OS level environment variable
export JAVA_OPTS="$JAVA_OPTS -Dcom.unblu.logging.outputDirectory=/var/log/unblu"


5. Configuration Setting Types

Every configuration settings has a type associated (one of Boolean, String, Enum, Integer, Float, URL and Pattern).

For Boolean settings the value must be either "true" or "false".

For Enum settings the value must be one of the allowed values.

For Integer settings the value must be a valid integer.

For Float settings the value must be a valid float.

For URL settings the value must be a valid (fully qualified) URL.

For Pattern settings the value must be a valid java regular expression.

Some configuration properties support lists of values (described in the configuration settings reference Unblu Server Configuration Reference). List values can be declared in two ways: separated by a comma or using the JSON list notation.

# example of a list using comma separated values (CAUTION: no way to escape the , character here)
# example of a list using the JSON format 

6. Further reading

Read about configuration validation in Unblu Server Configuration Validation.

All available configuration settings and their types are described in the Unblu Server Configuration Reference.

Read about i18n configuration in Unblu Server i18n Configuration.