AMS configuration files support substitution variables, substitution files, or both together to expedite AMS configuration.
You can define substitutions in the AMS configuration file, properties files, or at the command line. When starting the server, running substitutions at the command line override any values defined for that property in the AMS configuration (HOCON) file. When the server is restarted, AMS uses the properties defined in the AMS configuration file; existing command line substitutions (whether substitution variables or substitution files) do not persist upon server restart.
There is no support for using an environment variable value as a substitution variable value. This is different behavior than standard HOCON, which allows environment variable values to be used as a substitution variable value.
Substitution variables must follow these rules:
Defined using ${variable-name[:-default-value]}. This defines a substitution variable named variable-name with an optional default value of default-value.
variable-name can only contain characters specified by this regular expression [a-zA-Z0-9\\.-_]+.
variable-name cannot contain the HOCON escape character (\).
Substitution variable values, and default-value expressions, cannot contain unescaped newlines. Escaped newlines (\\n) are permitted, and will result in a newline character appearing in the substituted value.
Nested substitution variables are not allowed (these are allowed by standard HOCON). For example:
foo = bar
bar = biz
bar = biz ${${foo}} // returns an error instead of the value biz
Substitution variables are supported anywhere in a configuration file, including the left-hand side of an assignment. This is an extension to standard HOCON.
Substitution variables on the left-hand side of an assignment that contain the "." character must be surrounded with double quotes to prevent the value from being interpreted as a HOCON path. This is an extension to standard HOCON.
Substitution variables are supported in quoted strings. This is an extension to standard HOCON.
Substitution variables run in order of appearance.
Substitution variables run with precedence. For example, if an AMS port number value appears twice in the same command line, the last one specified is used.
If substitution variables and substitution files appear in the same command line, the variable always takes precedence regardless of the option order.
Substitution files can specify multiple Java properties.
Substitution files can specify multiple files in same command.
AMS runs all unique properties when multiple substitution variables, multiple substitution files, or a combination of both variables and files are used in the same command line.
Comma-separated substitution variables must not include blank spaces after the comma.
Use the following AMS command options to create substitutions at the command line:
name=value,name=value..."A comma separated list of name=value pairs used to replace substitution variables in the configuration files. This option is allowed multiple times, with the order of the substitution variables being the order in the command.
filenameA file containing newline terminated <name>=<value> pairs used to replace substitution variables in the configuration files. The file must conform to the standard Java properties file format. This option is allowed multiple times, with the order of the substitution files being the order in the command. Substitution variables from the --substitutions option take precedence over substitution variables in the file.
The following example defines two substitution variables in the AMS configuration file:
ClientAPIListener = {
portNumber = ${ams.listen.port}
secure = ${ams.listen.secure:-true}
}
Substitution variable names can be in any format supported within a Java properties file, although spaces in a substitution variable name are prohibited. Substitution variable names must be used exactly as specified in the configuration file.
See Configuration Resources for an example of a properties file containing substitutions.
Boolean and numeric values do not need to be enclosed in double quotes. Everything between the ${} characters is literally replaced with the substitution or default value:
ClientAPIListener = {
portNumber = ${ams.port.number:-2185}
secure = ${secureComms}
}
String values, even those within a string array, should be enclosed in double quotes:
LocalAuthenticationRealm = {
principals = [
{
userName = "${adminUserName:-admin}"
password = "${adminUserPassword}"
roles = ["${adminRole}"]
}
]
}
Specifying a port value for the defined substitution variable using a single --substitutions parameter: the specified port number appears in the console messages during server startup.
In the examples below, long lines wrap to the next for clarity.
ams-server --substitutions ams.listen.port=6000
Specifying a single --substitutions parameter with multiple comma separated name-values: the specified master secret decryption and port number value appear in the console messages during server startup.
ams-server --substitutions ams.listen.port=6000,ams.master.secret.path= ../ams/conf/AMS-MasterSecret.data
Specifying multiple --substitutions options: the specified master secret decryption and port number value appear in the console messages during server startup.
ams-server --substitutions ams.listen.port=6000 --substitutions ams.master.secret.path=../ams/conf/AMS-MasterSecret.data
Specifying the same --substitutions option appearing multiple times: the specified port number value that appears in the console messages during server startup is the value from the last substitutions option.
ams-server --substitutions ams.listen.port=6000 --substitutions ams.listen.port=6666
Specifying a single --substitutionfile option: the specified port number value appears in the console messages during server startup.
ams-server --substitutionfile ../ams/conf/AMS-5000.properties
Specifying multiple --substitutionfile options: the specified port number value that appears in the console messages during server startup is the value from the last properties file.
ams-server --substitutionfile ../ams/conf/AMS-5000.properties --substitutionfile ../ams/conf/AMS-7000.properties
Specifying multiple --substitutionfile options (reverse files): the specified port number value that appears in the console messages during server startup is the value from the last properties file.
ams-server --substitutionfile ../ams/conf/AMS-7000.properties --substitutionfile ../ams/conf/AMS-5000.properties
Specifying --substitutions and --substitutionfile options: AMS uses port 6000 since substitution variables override substitution files containing the same property.
ams-server --substitutions ams.listen.port=6000,ams.master.secret.path= ../ams/conf/AMS-MasterSecret.data --substitutionfile ../ams/conf/AMS-5000.properties