Using Substitution Variables and Files in MMS Configuration

Introduction

TIBCO Streaming Model Management Server (MMS) configuration supports substitution variables and substitution files to simplify and manage MMS configurations efficiently. This allows you to dynamically set values when running MMS and as a result making configurations more flexible and manageable.

Substitutions can be defined in:

• MMS configuration files (HOCON format).
• Java properties files.
• Command-line options during startup.

Note: Substitutions set through the command line override those in configuration files but do not persist after a restart.

Defining Substitution Variables

A substitution variable is defined using the below syntax:

${variable-name[:-default-value]}

Where, variable-name: Name of the variable. default-value: (Optional) Value used if the variable is not provided.

Rules for Substitution Variables

• Variable names can only include letters, numbers, and underscores ([a-zA-Z0-9_]).
• Variables cannot contain \ (HOCON escape character).
• Nested variables cannot be used. For instance, ${${foo}} is not allowed.
• Substitutions work inside quoted strings.
• The last occurrence of a variable in the command line takes precedence.
• Command-line substitutions always override values in a substitution file.

Using Substitution Variables in MMS Configuration Files

An example of an MMS configuration file using substitution variables is given below:

security:
  auth:
    localRealm:
      userDataFileURI: file:///C:/Users/User/AppData/Local/tibco/mms/conf/passwords.txt
      adminPassword: ${ADMIN_PASSWORD:-admin} # Uses 'admin' as default if not provided
      adminGroup: admin

internalAPIListener:
  idleTimeoutMS: 60000
  listenPort: ${LISTEN_PORT:-2192} # Uses 2192 as listen-port value if not provided

space:
  spaces:
    name: space
    description: default space
    permissionBindings:
      mms-all-users:
        - read
        - update
    repository:
      description: local git repo
      url: file:///C:/Users/User/AppData/Local/tibco/mms/default/git-remote-repository/gitrepo/
      repositoryRefreshIntervalSeconds: 300
      

In this example:

ADMIN_PASSWORD is replaced by the value provided in the command line. admin is the default value.

Using Substitution Variables in a Properties File

A substitution file follows the standard Java properties format:

ADMIN_PASSWORD=securePass123
LISTEN_PORT=8080

A substitution file allows multiple properties which can be specified in the command line.

Providing Substitutions in the Command Line

You can pass values at runtime using -substitutions or -substitutionfile.

The following example shows setting variables directly:

mms-launcher start -substitutions ADMIN_PASSWORD=securePass123,LISTEN_PORT=8080

The following example shows using a substitution file:

mms-launcher start --substitutionfile ../mms/conf/mms-config.properties

The following example shows combining substitutions and files. Note that command-line variables override file variables:

mms-launcher start --substitutions ADMIN_PASSWORD=securePass123 \
--substitutionfile ../mms/conf/mms-config.properties

If ADMIN_PASSWORD is present in the file and command line, then the value from the command line is used.

Best Practices

• Always define default values in the configuration file wherever applicable.
• Use substitution files for managing multiple properties instead of a long command-line string.
• Ensure that there are no spaces after commas in --substitutions.
• Use command-line substitutions only when necessary to override predefined values.
• Use hashed password generated from Hash a Password instead of a plain-text password.

By using substitution variables and files, you can streamline and manage MMS configurations dynamically.