Liferay Portal’s System Settings application is convenient for making system-scoped configuration changes and setting default configurations for other scopes. But there’s another supported configuration approach: configuration files. You can use configuration files to transfer configurations from pre-production systems to production systems, or between any other Liferay Portal systems. Sometimes developers choose to distribute the default configuration for their applications via configuration file. Whatever the reason, configuration files are a straightforward way of configuring Liferay Portal.
Creating Configuration Files
System Settings provides an Export option that becomes available once you modify a configuration entry. Exporting is the recommended way to create
.config files: you download a
.config file containing the entry’s settings in a
key=value format. Liferay Portal exports an entry’s total available configuration keys and values, even if only one value was changed. You can export a single configuration entry or the entire set of modified configurations in Liferay Portal.
To avoid a file name conflict, name configuration files using a unique identifier. For example, the Journal Service entry, which backs Liferay’s Web Content capabilities, has this file name:
Configuration files use the
.config property value format defined by the Apache Felix Configuration Admin framework.
.cfg file format is common in OSGi environments, so Liferay Portal supports it, but
.config files are preferable. You can specify a property value’s type, and have multi-valued properties. The syntax described below is for
The general syntax for all keys and values in a
.config file is the same:
For single value configurations without special characters, that’s all there is to know. Settings with multiple values and certain characters require slight modifications.
Configuration entries can have properties that accept multiple values. For example, a configuration property for specifying supported file extensions needs more than one value. Here’s how to write a multi-value setting in a
multiValueSetting=["Value 1","Value 2", ...]
Do not use a space character between values (after the comma). An errant space character can cause a failure to load the property.
Open the Web Content entry from System Settings and you’ll see what looks like multiple single value entries for Charactersblacklist:
In the configuration file, this is really a single key with an array of comma-separated values:
Double quotes (
") and equals signs (
=) must be escaped in
.config files. Escaping is using another character to denote that a character shouldn’t be used in its normal way. Since double quotes and equals signs are already used in
.config files, escaping them tells the framework not to read them the normal way, but to pass them through as part of the value. Use a
\ to escape characters in the
This setting illustrates a multi-value setting with a regular, unescaped character (
&), and two escaped ones (
Along with the mandatory escaping of double quotes and equals characters, it’s beneficial to escape spaces inside values to avoid problems.
blacklistBundleSymbolicNames=["Liferay\ Marketplace","Liferay\ Sharepoint\ Connector"]
In the above example, a
\ is used before each space character to ensure it’s read and processed properly. If you don’t escape spaces yourself, the framework adds the backslash for you after deployment.
Deploying a Configuration File
Once you have a configuration file, deploy it so Liferay Portal recognizes it and updates the targeted configuration values.
To deploy the
.config file, place it in your Liferay Home’s
osgi/configs folder. To change the configuration further, you can edit the
.config file directly or use System Settings.
.config file format supports specifying the type of a configuration value by inserting a special type marker character. Because Liferay Portal already knows the correct type for each configuration property, the type characters are only useful for informational purposes. For example, a configuration with a boolean type has B just before the value to mark it as a boolean type:
If you see type markers in
.config files, you can safely ignore them. The example included above functions identically without the type marker:
Configuration Files and Clustering
In a clustered environment, each node needs the same configuration values for each entry. For example, all nodes should use the same Blogs configuration settings. To accomplish this, deploy a
.config file to one node. Liferay Portal uses an internal system that appies the change to all nodes in the cluster.
Configurations supporting multiple independent occurrences of the same configuration entry are called factory configurations.
If a service is meant to support factory configuration, its System Settings entry has an Add button ().
As with single-instance configurations, you can accomplish factory configuration in the System Settings interface (as described in the example above) or via configuration files. Once you determine you must write a factory configuration file. Name a standard single-instance configuration file like this:
If your service supports factory configuration, use Liferay’s convention of calling the first instance of the configuration
The next instance contains a unique subname (something other than default). It’s smart to use a descriptive name:
To follow the CXF Endpoints example described above, if Liferay’s developers had shipped an initial CXF Endpoint
.config file with Liferay Portal, it would have been named
-default.config configuration specifies a context path for REST web services, and then you create another endpoint with a different context path for SOAP web services. Your second configuration file could be named
Now a note of warning. In many cases, configuration files can be used to force a factory configuration scenario, but not all configurations are designed to be used this way. It’s best to stick to the intended use cases. Use System Settings as described above to determine if factory configuration is a good idea. If not, stick to the single occurrence mode of configuration (specifying only one configuration file for the service).