Introduction to Configuration

Configuration parameters are set in the configuration file. When setting configuration parameter values, you must use UTF-8.

This section describes how to enter parameter values in the configuration file.

Enter Boolean Values

The following settings for Boolean parameters are interchangeable:

TRUE = true = ON = on = Y = y = 1
FALSE = false = OFF = off = N = n = 0

Enter String Values

To enter a comma-separated list of strings when one of the strings contains a comma, you can indicate the start and the end of the string with quotation marks, for example:

ParameterName=cat,dog,bird,"wing,beak",turtle

Alternatively, you can escape the comma with a backslash:

ParameterName=cat,dog,bird,wing\,beak,turtle

If any string in a comma-separated list contains quotation marks, you must put this string into quotation marks and escape each quotation mark in the string by inserting a backslash before it. For example:

ParameterName="<font face=\"arial\" size=\"+1\"><b>","<p>"

Here, quotation marks indicate the beginning and end of the string. All quotation marks that are contained in the string are escaped.

Include an External Configuration File

You can reference an external configuration file to include shared settings. The following examples show how to include a configuration file, or a section or parameter from the file.

  • Include a whole configuration file:

    < "ConfigurationFile.cfg"
  • Include a section from another configuration file (including the section heading):

    < "ConfigurationFile.cfg" [SharedSection]
  • Include one or more parameters from another configuration file (the import does not include the section heading):

    [SectionName]
    < "ConfigurationFile.cfg" [SharedSection] ParameterName

    You can also include a default value to use if the shared configuration file does not contain the specified parameter:

    < "ConfigurationFile.cfg" [SharedSection] ParameterName=DefaultValue

    You can use wildcards to import multiple parameters, but this method does not support default values. The * wildcard matches zero or more characters. The ? wildcard matches any single character. Use the pipe character | as a separator between wildcard strings. For example:

    < "ConfigurationFile.cfg" [SharedSection] ParameterA*|ParameterB?|ParameterC
  • Include a parameter from another configuration file using a different name:

    < "ConfigurationFile.cfg" [OtherSection] OtherParameterName : ParameterName

    This example includes a parameter ParameterName, using the value of the OtherParameterName parameter in the OtherSection section of ConfigurationFile.cfg. You can also supply a default value to use if OtherParameterName is not found.

    < "ConfigurationFile.cfg" [OtherSection] OtherParameterName : ParameterName = DefaultValue
  • Merge a section of an external configuration file into a specified section with a different name:

    [SectionName] < "ConfigurationFile.cfg" [SharedSection]

    This example includes the values in [SharedSection] from the external configuration file into [SectionName] in your file.

In all these examples, ConfigurationFile.cfg is the path and file name of the shared configuration file. You can specify the file location by using absolute paths, relative paths, and network locations. For example:

../sharedconfig.cfg
K:\sharedconfig\sharedsettings.cfg
\\example.com\shared\shared.cfg
file://example.com/shared/sharedsettings.cfg

Relative paths are relative to the primary configuration file.

Include a Value from an External Source

You can include sensitive settings from an external source, to avoid storing the values directly in the configuration file. For this option, you can include the value of an environment variable, or import values by using a shared library.

  • Include the value of an environment variable:

    < :ENV ENVIRONMENT_VARIABLE_NAME : ParameterName = DefaultValue

    This example creates a parameter ParameterName with the value of the environment variable ENVIRONMENT_VARIABLE_NAME. The DefaultValue is optional, and is used if the environment variable does not exist.

  • Import a value from another external source by using a shared library:

    < :PROVIDER [Settings] KeyName : ParameterName

    In this example, PROVIDER is the name of the library to load to provide the import, providersecrets.dll (Windows) or libprovidersecrets.so (Unix). [Settings] is the name of a configuration section with details of how to connect to the external source, which you must define before the line that references it. KeyName is the key to look up in the external source, and ParameterName is the name of the parameter to populate with the value of KeyName.

Available Libraries

Your component installations have a secretsdlls directory, which includes the libraries that you can use to retrieve values from external sources.

  • HashiCorp® Vault. hashicorpvaultsecrets.dll or libhashicorpvaultsecrets.so. For example:

    [VaultSettings]
    SecretPath=secret/data/myapp/config
    VaultURL=https://myvault.example.com/
    VaultToken=xxxx
    
    [SectionName]
    < :HASHICORPVAULT [VaultSettings] KeyName : ParameterName

    This example connects to the Vault instance at myvault.example.com, which has a KV Secrets engine mounted at secret. The component accesses the secret at myapp/config and uses the value of KeyName for the configuration parameter ParameterName.

    You can use the following configuration settings to connect to HashiCorp Vault:

    SecretPath (Required) The path to the secret data. This path takes the form :secret-mount-path/data/:path
    VaultURL The address of the Vault instance. The default value is http://localhost:8200/. You can use this default value in a Kubernetes environment with an Agent sidecar injector.
    VaultToken

    A Vault authentication token.

    AuthPath

    The path of the Vault auth method to use, as an alternative to supplying a authentication token directly. This option supports methods that authenticate with a JSON Web Token. If you set AuthPath, you must also set AuthRole and JWT or JWTPath.

    AuthRole The role to use when authenticating.
    JWT or JWTPath

    The JSON Web Token, or the path to a file that the component can read the JSON Web Token from.