Contact usRequest a demo

Configuring the Collaboration Server

The Collaboration Server supports a wide range of configuration properties. See the configuration properties reference.

While most configuration properties can be set dynamically (and in different scopes, see the Account Configuration interface on the running server and go through the various scopes in the navigation sidebar on the left), some configuration properties must already be known when the Unblu server starts up.

This page describes the steps required to use configuration settings in your server installation.

Configuration settings keys are case-insensitive. For better readability, configuration setting keys are written in camel case in the documentation and references.

Using configuration files

The most common way to set (immutable) configuration settings is to use configuration files. Unblu configuration files use the Java properties file format. They consist of lines with the name of the configuration property, the "equals" sign =, and the value of the configuration property. The line below, for example, enables universal co-browsing:

Listing 1. Unblu configuration file entry to enable universal co-browsing

To use a configuration file, you need to specify where the Collaboration Server should load the configuration file from using the com.unblu.propertyoverlay JNDI or Java System Property.

The value of com.unblu.propertyoverlay (JNDI or 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 (such as 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’re escaped properly.

How JNDI Properties are set depends on the server software you are using. On Tomcat, for instance, JNDI properties can be set using Environment Entries in the Context configuration file ($CATALINA_BASE_DIR/conf/Catalina/localhost/ROOT.xml for the root context in a default tomcat setup).


	<Environment name="product" value="" type="java.lang.String" override="false"/>
	<Environment name="com.unblu.propertyoverlay" value="" type="java.lang.String" override="false"/>
	<Environment name="com.unblu.textoverlay" value="" type="java.lang.String" override="false"/>

For more on configuring JNDI for your servlet container see the following links:

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

Configuration file format

Configuration files use the 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 pair 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. See for more details about the Java properties file format.

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

Using multiple configuration files

Instead of using a single configuration file, it’s also possible to split configuration across multiple files. Multiple configuration files are specified using a comma-separated list of file paths or URLs in the com.unblu.propertyoverlay System or JNDI Property instead of a single value.

# example for using multiple configuration files (using the JAVA_OPTS OS
# environment variable, i.e. in Tomcat)
export JAVA_OPTS="$JAVA_OPTS -Dcom.unblu.propertyoverlay=http://configurationserver/unblu/,/etc/unblu/"

This example specifies two configuration files: http://configurationserver/unblu/ and /etc/unblu/

When using multiple configuration files, the ones that are defined later will always take precedence over the ones defined earlier.

In the example above this means that properties defined in /opt/unblu/ will take precedence over properties defined in http://configurationserver/unblu/

Using multiple configuration files can make sense, for instance, when there are multiple environments (for example "production", "staging", and "development") that share most of the configuration but still need some individual configuration.

Using JNDI directly

Instead of using a configuration file (specified via JNDI or a system property) it’s also possible to use configuration properties in JNDI directly.

Using system properties directly

As an alternative to using a configuration file, you can also pass configuration properties directly via system properties.

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

Configuration setting types

Every configuration setting 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 expect list values. These can be declared in two ways: as comma-separated lists 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