Use of parameters in configuration files

To make the deployment of Content Delivery software in different environments easier, most Content Delivery configuration files allow you to specify configuration values in the form of a parameter, rather than in the form of a hardcoded literal string. Content Delivery determines the actual configuration value at runtime by resolving the parameter using system settings. This allows you to reuse the same configuration files in different environments without having to modify those configuration files. The software behaves differently depending on the system settings in the specific environment.

General use

In the configuration files, you can replace any hardcoded literal value enclosed in quotes with a parameter, also enclosed in quotes. For example, say that the configuration file contains the following:
<Namespace default="tcm">
You can replace this with something like the following:
<Namespace default="${namespaceprefix:-tcm}">

In this new element, the hardcoded value tcm was replaced by a parameter, recognizable by its delimiters, ${ and }.

Parameter formats

The parameter takes one of the following formats:

${PROPERTYNAME:-DEFAULT}

If you use the format above, Content Delivery first tries to resolve the property by checking for a system setting called PROPERTYNAME. If that fails, it sets the property value to DEFAULT. Content Delivery logs the resolved value in the debug logs.

${PROPERTYNAME:-DEFAULT:-*HIDDEN*}

If you use the format above, Content Delivery first tries to resolve the property by checking for a system setting called PROPERTYNAME. If that fails, it sets the property value to DEFAULT. The :-*HIDDEN* modifier instructs Content Delivery to not log the resolved value in the debug logs (typically because it is a sensitive value, like a password).

${PROPERTYNAME}

If you use the format above, Content Delivery tries to resolve the property by checking for a system setting called PROPERTYNAME. You must have configured a system setting called PROPERTYNAME. Content Delivery logs the resolved value in the debug logs.

${PROPERTYNAME:-*HIDDEN*}

If you use the format above, Content Delivery tries to resolve the property by checking for a system setting called PROPERTYNAME. You must have configured a system setting called PROPERTYNAME. The :-*HIDDEN* modifier instructs Content Delivery to not log the resolved value in the debug logs (typically because it is a sensitive value, like a password).

Whichever format you use, neither PROPERTYNAME nor DEFAULT can contain the string :- or the character }.

Parameter resolution through system settings

There are several ways in which you can set a system setting for the property name:
  • You can set the value within the context of the Content Delivery microservice, using the -D startup switch for your PowerShell (.ps1) or Linux (.sh) installation script.
  • You can set the value within the context of your Java Virtual Machine, using the -D startup switch for java.exe.
  • You can set the value system-wide, using the operating system itself, for example using the SET (Windows) or env (Linux) command.
Content Delivery tries to resolve the parameter in this order:
  1. First, it checks for a value for the property in the context of the microservice.
  2. Failing that, it then checks for a value for the property in the context of the JVM.
  3. Failing that, it then checks for a value for the property in the context of the operating system.
  4. Failing that, it then checks for a default value specified in the configuration file itself.

Predefined parameters

Some Content Delivery configuration files already have parameters set up. For example, the Storage Layer configuration file, cd_storage_conf.xml, contains the following parameters, among others:
${discoveryurl:-http://localhost:8082/discovery.svc}
This property value specifies that Content Delivery should check for a system setting called discoveryurl, and to use a value of http://localhost:8082/discovery.svc if it fails to find such a system setting.
${systempassword:-changeme:-*HIDDEN*}
This property value specifies that Content Delivery should check for a system setting called systempassword, and to use a value of changeme if it fails to find such a setting. Regardless of how it resolves the parameter, it does not record the resolved value in the logs, for security reasons.
${systempassword:-*HIDDEN*}
This property value specifies that Content Delivery should check for a system setting called systempassword. You must have specified a system setting by that name, or the software will not work. For security reasons, Content Delivery does not record the resolved value in the logs.

Excluded configuration files

The following configuration files do not allow you to use parameters, because they are third-party configuration files:
  • web.xml
  • logback.xml

However, the Logback framework allows you to perform a very similar task in logback.xml through a mechanism called variable substitution. For more information, refer to the heading "Variable substitution" on this webpage: http://logback.qos.ch/manual/configuration.html.