Documentation Center

Use of parameters in configuration files

Most Content Delivery configuration files let you set configuration values not as hardcoded literal strings, but as parameters, resolved at runtime using system settings. This way, by using different system settings in different environments, you can reuse the same configuration files without having to modify them.

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.
The override order for determining the value of a parameter is as follows:
  1. The custom configuration of an Add-on (for Add-ons only). An Add-on will use the value specified for the parameter in its custom configuration file, if present.
  2. The environment variable in the operating system. Outside the scope of an Add-on, or if the Add-on custom configuration file did not provide a value, Content Delivery will use the value as set in the operating system on which the software runs. Specifically, it's the operating system environment varaible that is set globally, for the current user, or for the current local session in a console.
  3. The value of an -D startup parameter for either the microservice or the JVM. If the above values did not apply or were not set, Content Delivery will use the value as set in a microservice of JVM startup swithc of the for -DPARAM=VALUE, where PARAM is the name of the parameter whose value you are trying to determine, and VALUE is its value.
  4. The default value of the parameter as set in the Content Delivery configuration file itself. It the parameter did not get a value from any of the sources above, Content Delivery falls back on the default value as specified in the Content Delivery configuration file.

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
  • Web.config
  • 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.