Sections in the FTL Server Cluster Configuration

Provided below is a brief description of each section of the YAML configuration file and a list of all required and optional parameters that can be included in those sections in the context of FTL stores.

Note: Most parameters relating to FTL server cluster security are not listed here. Please refer to the FTL Server Cluster Security section for more information.

globals

The globals section contains parameters that directly affect the operation of the FTL servers in the cluster.

Parameter Name Description
core.servers

This parameter is mandatory.

A list of the names of the FTL servers in the cluster along with their location.

oauth2.claim.username

Required when oauth2 is configured in the user_auth parameter.

When validating an OAuth 2.0 access token, the TIBCO FTL server will interpret this claim as a username.

This property is shared with the EMS server and overrides the oauth2_user_claim EMS server property.
oauth2.claim.roles

Required when oauth2 is configured in the user_auth parameter.

When validating an OAuth 2.0 access token, the TIBCO FTL server will interpret this claim as an array of authorization groups.

This property is shared with the EMS server and overrides the oauth2_group_claim EMS server property.
oauth2.audience

Optional. When validating an OAuth 2.0 access token, the TIBCO FTL server will ensure that the audience ('aud') claim matches this value. If it does not match, the token is rejected.

This property is shared with the EMS server and overrides the oauth2_audience EMS server property.

servers

The servers section must contain a list of all FTL servers in the cluster. For each server in the list, a sub-list of services whose behavior is to be configured can be specified. No service should be specified more than once for a given server.

The table below details the parameters available to configure each service.

Parameter Name Description
tibemsd Service Parameters
exepath

This parameter is mandatory and must be configured for each FTL server in the cluster.

The path to the tibemsd executable. This executable is located at EMS_HOME/bin/tibemsd.
-license

The path to a license file or the URL to the TIBCO Activation Service.

The URL to the TIBCO Activation Service may optionally include a fingerprint. If a fingerprint is provided, the EMS server will only connect to the TIBCO Activation Service if the fingerprint matches the public certificate of the TIBCO Activation Service.

This parameter must be used in place of the license EMS server parameter when using FTL stores.

See the License section for syntax and information about EMS license requirements and behavior.
-listens

A comma-separated list of one or more listen URLs for the EMS server.

This parameter must be used in place of the listen EMS server parameter when using FTL stores. If not specified, the EMS server will start with the default listen URL tcp://7222.

Refer to the listen section for information about EMS server listen URL syntax.
-config_wait

When this parameter is specified for all tibemsd services, the EMS servers within the FTL server cluster will wait for an EMS configuration to become available in the cluster before starting up. This parameter does not accept a value.

If this parameter is not specified for all tibemsd services, and an EMS configuration is not available in the cluster, the EMS servers will start with default configuration.

See the Server Configuration Upload/Download section for instructions on uploading the EMS configuration to the FTL server cluster.
-standby_only

This parameter informs the FTL server that its EMS server is configured to be standby_only, meaning that it cannot ever transition to active state. This parameter does not accept a value.

Only one of the 3 FTL servers in this section should have this parameter set for its tibemsd service. The selected FTL server will be the one whose EMS server will not be part of the fault-tolerant EMS server pair, and whose URL will not be used by clients.

This parameter should not be specified if the configuration is for a standalone FTL server.

-preferred_active

Setting this parameter designates the EMS server as the preferred active server.

In situations where either EMS server in the fault-tolerant pair could potentially enter the active state, the server configured with -preferred_active, will always be the one to activate.

Configuring this parameter for an EMS server does not guarantee that the server will always be in the active state. The preferred active server will enter the standby state if its fault-tolerant peer EMS server is already in the active state.
-store The path to the directory where the FTL server will write out FTL store-specific data. If not specified, FTL store data will be written to the current working directory by default.
-monitor_listen

The URL at which the EMS server will listen for health check and Prometheus metrics requests.

This URL should follow the same syntax as described in the monitor_listen section.

-oauth2_disable_verify_hostname

Optional. If set, the name in the CN field of the HTTPS server’s certificate will not be verified.

Hostname verification is enabled by default. This parameter is only relevant when the value of
oauth2.validation.key is the URL of an HTTPS JWKS endpoint.

This parameter should be used in place of the oauth2_disable_verify_hostname EMS server parameter.
-oauth2_expected_hostname

Optional. The name that the EMS server expects in the CN field of the HTTPS server’s certificate.

This parameter is optional and only relevant when oauth2.validation.key is the URL of an HTTPS JWKS endpoint and
-oauth2_disable_verify_hostname is not set to true.

This parameter should be used in place of the oauth2_expected_hostname EMS server parameter.
load

The path to the state file from which the FTL server will load its state information during startup.
<EMS server command line option>

Any EMS server command line option can be included in this section. For example, -ssl_trace.

realm Service Parameters
data

The general data directory for the FTL server. This directory will contain all non-FTL store specific data. If not specified, the default is the current working directory.
drto

When present, this FTL server cluster recognizes another given FTL server cluster as belonging to a disaster recovery site and attempts to connect to it.

Supply a pipe-separated list of the URLs of the FTL servers in the disaster recovery site’s FTL server cluster. Each URL should be of the form:

<FTL server name>@<host>:<port>

(You must also configure the disaster recovery FTL servers using the drfor parameter.)
drfor

When present, this FTL server cluster recognizes that it is in the disaster recovery site for a primary site FTL server cluster.

Supply a pipe-separated list of URLs of the FTL servers in the primary site’s FTL server cluster. Each URL should be of the form:

<FTL server name>@<host>:<port>

(You must also configure the primary site FTL servers using the drto parameter.)
user

The username that the FTL server clusters at the primary and DR sites will use to authenticate each other.

If the authentication data for the primary and DR sites was created based on the steps in FTL Server Cluster Security, the value passed to this option should be admin.

This parameter must be specified if setting up disaster recovery with secure FTL server clusters.

password

The password that the FTL server clusters at the primary and DR sites will use to authenticate each other.

The value for this parameter should be of the form:

file:<path to password_file>

where password_file is a file containing the chosen password for authentication. See FTL Server Cluster Security for details.

This parameter must be specified if setting up disaster recovery with secure FTL server clusters.

ftlserver.properties Parameters
logfile

The prefix for the filenames of the rolling log files generated by the FTL server.

If the prefix includes a directory path, the FTL server’s log files will be generated under that directory. If not, the FTL server will generate its log files in the current directory.

Any directories included in the prefix value must already exist.

If this parameter is not specified, the FTL server will send log output to the console.
max.log.size The maximum size of each FTL server log file in bytes.
max.logs The maximum number of rolling log files that can be created.
oauth2.validation.key

Required when oauth2 is configured in the user_auth parameter.

The TIBCO FTL server will validate the signature of the access token using one of the given validation keys.

The value for this parameter must be of the form:

  • file:path

  • http://host:port/path or

  • https://host:port/path

If a file URL is specified, the file may be a PEM file or a JWKS file. If an http or https URL is specified, the TIBCO FTL server will fetch the JWKS file by making an HTTP(S) request to the specified URL.

This property is shared with the EMS server and overrides the oauth2_server_validation_key EMS server property.
oauth2.provider.trust.file

Optional. This parameter specifies the path to a file containing one or more PEM-encoded public certificates.

The TIBCO FTL server uses the trust file to verify the identify of the OAuth 2.0 provider, such as when the oauth2.validation.key is an HTTPS URL.

If not specified, the TIBCO FTL server uses the system trust store to verify the identity of the OAuth 2.0 provider.

This property is shared with the EMS server and overrides the oauth2_server_trust_file EMS server property.
oauth2.jwks.refresh.interval

Optional. Sets the regular interval (in seconds) at which the JWKS is refreshed.

This property is relevant when oauth2.validation.key is an HTTP(S) URL.

This property is shared with the EMS server and overrides the oauth2_key_refresh_interval EMS server property.
oauth2.jwks.refresh.threshold

Optional. Sets the duration (in seconds) that FTL must wait between JWKS refresh attempts prompted by OAuth 2.0 access token validation issues.

This property is relevant when oauth2.validation.key is an HTTP(S) URL.

This property is shared with the EMS server and overrides the oauth2_key_refresh_threshold EMS server property.

Examples

Example 1
Configuration for a standalone FTL server that does not have security enabled and is using the default data directories.

globals:
  core.servers:
    ftls1: host1:8080
servers:
  ftls1:
  - tibemsd:
      -license: file:///opt/deployment/license.bin
      -listens: tcp://host1:7222
      exepath: /opt/tibco/ems/10.3/bin/tibemsd
      -config_wait:

Example 2
Configuration for an FTL server cluster that is secured with user-defined TLS certificates and OAuth 2.0 authentication (for EMS server as well as FTL server cluster), has generic and FTL store-specific data directories defined, has logging parameters configured, and is also configured to replicate data to a disaster recovery site.

globals: 
    core.servers: 
        ftls1: host1:8080 
        ftls2: host2:8085 
        ftls3: host3:8090 
    auth.providers: oauth2
    oauth2.claim.roles: group
    oauth2.claim.username: preferred_username
    oauth2.audience: ems
    oauth2.svr.endpoint.token: https://host1:32223/oauth2/token
servers: 
    ftls1: 
    - tibemsd: 
        -license: file:///opt/deployment/license.bin
        -listens: ssl://host1:7222 
        exepath: /opt/tibco/ems/10.4/bin/tibemsd 
        -store: /opt/deployment/ftls1/ftlstore_data
        -oauth2_expected_hostname: server
        -config_wait:
    - realm: 
        data: /opt/deployment/ftls1/ftlserver_data 
        drto: dr_ftls1@host4:8080|dr_ftls2@host5:8085|dr_ftls3@host6:8090
    - ftlserver.properties:
        tls.server.cert: /opt/deployment/tls-user/server_cert.pem
        tls.server.private.key: /opt/deployment/tls-user/server_key.pem
        tls.server.private.key.password: password
        tls.client.trust.file: /opt/deployment/tls-user/client_trust.pem
        oauth2.validation.key: file:/opt/deployment/oauth2/oauth2.json
        oauth2.provider.trust.file: /opt/deployment/oauth2/oauth2_provider.crt
        oauth2.jwks.refresh.interval: 129600
        oauth2.jwks.refresh.threshold: 600
        oauth2.svr.client.id: ems-client
        oauth2.svr.client.secret: file:/opt/deployment/oauth2/secret.txt
        logfile: /opt/deployment/ftls1/logs/log 
        max.log.size: 1048576 
        max.logs: 100 
    ftls2: 
    - tibemsd: 
        -license: file:///opt/deployment/license.bin
        -listens: ssl://host2:7224 
        exepath: /opt/tibco/ems/10.4/bin/tibemsd 
        -store: /opt/deployment/ftls2/ftlstore_data
        -oauth2_expected_hostname: server
        -config_wait: 
    - realm: 
        data: /opt/deployment/ftls2/ftlserver_data 
        drto: dr_ftls1@host4:8080|dr_ftls2@host5:8085|dr_ftls3@host6:8090
    - ftlserver.properties:
        tls.server.cert: /opt/deployment/tls-user/server_cert.pem
        tls.server.private.key: /opt/deployment/tls-user/server_key.pem
        tls.server.private.key.password: password
        tls.client.trust.file: /opt/deployment/tls-user/client_trust.pem
        oauth2.validation.key: file:/opt/deployment/oauth2/oauth2.json
        oauth2.provider.trust.file: /opt/deployment/oauth2/oauth2_provider.crt
        oauth2.jwks.refresh.interval: 129600
        oauth2.jwks.refresh.threshold: 600
        oauth2.svr.client.id: ems-client
        oauth2.svr.client.secret: file:/opt/deployment/oauth2/secret.txt
        logfile: /opt/deployment/ftls2/logs/log 
        max.log.size: 1048576 
        max.logs: 100
    ftls3: 
    - tibemsd: 
        -license: file:///opt/deployment/license.bin
        -listens: ssl://host3:7226 
        exepath: /opt/tibco/ems/10.4/bin/tibemsd 
        -store: /opt/deployment/ftls3/ftlstore_data
        -oauth2_expected_hostname: server
        -config_wait: 
        -standby_only: 
    - realm: 
        data: /opt/deployment/ftls3/ftlserver_data 
        drto: dr_ftls1@host4:8080|dr_ftls2@host5:8085|dr_ftls3@host6:8090
    - ftlserver.properties:
        tls.server.cert: /opt/deployment/tls-user/server_cert.pem
        tls.server.private.key: /opt/deployment/tls-user/server_key.pem
        tls.server.private.key.password: password
        tls.client.trust.file: /opt/deployment/tls-user/client_trust.pem
        oauth2.validation.key: file:/opt/deployment/oauth2/oauth2.json
        oauth2.provider.trust.file: /opt/deployment/oauth2/oauth2_provider.crt
        oauth2.jwks.refresh.interval: 129600
        oauth2.jwks.refresh.threshold: 600
        oauth2.svr.client.id: ems-client
        oauth2.svr.client.secret: file:/opt/deployment/oauth2/secret.txt
        logfile: /opt/deployment/ftls3/logs/log 
        max.log.size: 1048576 
        max.logs: 100