FTL Server Configuration Parameters

Parameters in the globals section of the configuration file apply to all FTL servers in the cluster, including all core and auxiliary servers.

Parameters in the ftlserver.properties item apply to the FTL server as a whole. The ftlserver.properties item is part of the definition of one FTL server in the servers section of the configuration file.

Certain parameters must be defined in the ftl item instead. These also apply to the FTL server as a whole. The ftl item is part of the definition of one FTL server in the servers section of the configuration file. In general, the ftl item is used only to define auxiliary servers.

Refer to the tables below to determine where each parameter belongs.

Important: Do not use relative paths.

Servers and Locations

Parameter Location Arguments Description

Parameter	Location	Arguments	Description
core.servers	globals	servers	Required. Supply a map from server names to their locations. Use the following form for each server: <server_name>: <host>:<port> Each location is a connect address, used by other FTL servers in the cluster when connecting to the given FTL server. By default, the FTL server binds all interfaces on the specified port. However, if `<host>` is "localhost", FTL server binds only "localhost". Include in this map only core servers. Omit any auxiliary servers. For more information, see Core Servers.
server	ftl	<host>:<port>	Specify the location of an auxiliary server. The location is a connect address, used by other FTL servers in the cluster when connecting to the given FTL server. By default, FTL server binds all interfaces on the specified port. However, if `<host>` is "localhost", FTL server binds only "localhost". For more information, see Auxiliary Servers
`spin.limit`	ftl	<microseconds>	Optional. Set the limit for the amount of spin time, in microseconds, for an FTL server receiving data from a connection. The default value is `0`. Use caution with this parameter and adjust it only when necessary and with full understanding of its effect on CPU and thread performance. The default value should provide optimal performance in most cases.

core.servers

globals

servers

Required.

Supply a map from server names to their locations.

Use the following form for each server:

<server_name>: <host>:<port>

Each location is a connect address, used by other FTL servers in the cluster when connecting to the given FTL server.

By default, the FTL server binds all interfaces on the specified port. However, if <host> is "localhost", FTL server binds only "localhost".

Include in this map only core servers. Omit any auxiliary servers.

For more information, see Core Servers.

server

ftl

Specify the location of an auxiliary server. The location is a connect address, used by other FTL servers in the cluster when connecting to the given FTL server.

By default, FTL server binds all interfaces on the specified port. However, if <host> is "localhost", FTL server binds only "localhost". For more information, see Auxiliary Servers

spin.limit

ftl

Optional.

Set the limit for the amount of spin time, in microseconds, for an FTL server receiving data from a connection. The default value is 0.

Use caution with this parameter and adjust it only when necessary and with full understanding of its effect on CPU and thread performance. The default value should provide optimal performance in most cases.

Authentication Providers

When one or more authentication providers are configured, authentication is enabled for the REST API, UI, realm connections from FTL clients, and connections between affiliated FTL servers. Authentication for other services (for example, persistence services or eftl services) may be optionally enabled through the realm configuration. For more information, see Authentication and Authorization .

Important: Files and passwords should not be read/write accessible to non-privileged use.

Parameter	Location	Arguments	Description
auth.providers	globals	<provider_list>	Optional. Set this parameter to enable authentication. The `<provider_list>` is a comma-separated list of one or more auth providers. The following are valid providers. Specify at most one of each type. "file:<path>" "http://<host>:<port>/<path>" or "https://<host>:<port>/<path> "ldap://<host>:<port>" or "ldaps://<host>:<port>" "mtls" "oauth2" Example: "file:/path/users.txt,oauth2" For information about how to use each provider type, see Authentication.
auth.user	globals	<user_name>	Optional. The FTL server identifies itself to an external authentication service using this username credential. This parameter is used only for the http(s) and ldap(s) auth providers.
auth.password	globals	<password>	Optional. The FTL server identifies itself to an external authentication service using this password credential. This parameter is used only for the http(s) and ldap(s) auth providers. To hide the password from casual observers, see Password Security.
auth.trust	globals	<path>	Optional. When using an https authentication provider, use this parameter to specify the location of the authentication service's public certificate file (in PEM format). The FTL server uses the certificate to verify the identify of the external authentication service. If not specified, FTL server uses the system trust store to verify the identity of the authentication service. This parameter is only used for https auth providers.
auth.timeout	globals	<seconds>	Optional. Timeout for requests to a remote authentication service, in seconds. If the remote authentication service does not respond after this period, the FTL server returns an error. The default value is 15 seconds.
auth.rolemap	ftlserver.properties	<path>	Optional. This file can be used to map an authorization group returned by an auth provider to different authorization groups. If mapped, FTL server considers the user to be a member of both the original and the mapped groups. For example, a group from LDAP might be mapped to the `ftl-admin` group in a particular FTL environment. You might specify different mappings for different auth providers. The format of this file is described in Mapping Authorization Groups. Also see FTL Server Authorization Groups
ldap.config	globals	<path>	Required when the ldap(s) authentication provider is configured. The file specifies configuration for connecting to the LDAP server and authenticating user. The contents of this file are described inUsing the Built in LDAP Authentication Service.
tls.server.trust.file	ftlserver.properties	<path>	Required when the mtls auth provider is configured. When clients or other FTL servers connect to this FTL server using mTLS authentication, the incoming connection includes a client certificate. This file contains the trust certificates used by FTL server to verify the incoming client certificate. When the mtls provider is configured, you must also enable TLS user-defined certificates by specifying "tls.server.cert". For more information, see Using the Built in mTLS Based Authentication Service.
oauth2.claim.roles	globals	<string>	Required when the oauth2 authentication provider is configured. When validating an oauth2 access token, FTL server interprets this claim as an array of authorization groups. Default: group
oauth2.claim.username	globals	<string>	Required when the oauth2 authentication provider is configured. When validating an oauth2 access token, FTL server interprets this claim as a username. Default: preferred_username
oauth2.audience	globals	<string>	Required when the oauth2 authentication provider is configured. When validating an access token, FTL server ensures that the audience ("aud") claim matches this value. If it does not match, the token is rejected.
oauth2.validation.key	ftlserver.properties	<url>	Required when the oauth2 authentication provider is configured. When a client or another FTL server authenticates to this FTL server using an oauth2 access token, FTL server validates the signature of the access token using one of the given validation keys. The <url> specifies the location of the validation keys. There are two valid forms: "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(s)" url is specified, FTL server will fetch the JWKS file by making an http(s) request to the specified url. For "https" urls, "oauth2.provider.trust.file" may be specified as well.
oauth2.provider.trust.file	ftlserver.properties	<path>	Optional. If "oauth2.validation.key", "oauth2.ui.endpoint.auth", "oauth2.ui.endpoint.token", or "oauth2.svr.endpoint.token" is an https url, this parameter specifies the location of the oauth2 provider’s public certificate file (in PEM format). The FTL server uses the certificate to verify the identify of the oauth2 provider. If not specified, FTL server uses the system trust store to verify the identity of the oauth2 provider.
disable.default.security	globals		Optional. This parameter is intended for backward compatibility with FTL 6.x in certain unusual situations. If you are upgrading normally from FTL 6.x, there is no need to use this parameter. This parameter only takes effect when there is no pre-existing realm database, authentication is enabled, and TLS is not enabled. When set, the default persistence cluster and the group service do not use secure transports by default. This preserves compatibility with 6.x clients. Set this parameter only if you are starting FTL servers with no pre-existing realm configuration, where authentication is enabled and TLS is not enabled, and where compatibility with 6.x clients is required.

Single Sign-On with OAuth2

By default, users of the UI must authenticate directly to FTL server using basic authentication (username/password). To enable single sign-on via an oauth2 provider, use the following parameters. The "oauth2" authe provider must also be configured.

Parameter	Location	Arguments	Description
oauth2.ui.endpoint.auth	globals	<url>	Required for SSO with oauth2. Specifies the URL of the oauth2 auth endpoint. For "https" urls, you may need to specify "oauth2.provider.trust.file"
oauth2.ui.endpoint.token	globals	<url>	Required for SSO with oauth2. Specifies the URL of the oauth2 token endpoint. For "https" urls, you may need to specify "oauth2.provider.trust.file".
oauth2.ui.client.id	ftlserver.properties	<string>	Required for SSO with oauth2. Specifies the oauth2 client id to use for authorization code Specifies the oauth2 client id to use for authorization code flow with the UI.
oauth2.ui.client.secret	ftlserver.properties	<password>	Required for SSO with oauth2. Specifies the oauth2 client secret to use for authorization code flow with the UI. To hide the password from casual observers, see Password Security.
oauth2.ui.endpoint.logout	string	<password>	URL of the oauth2 logout endpoint; if not specified, FTL UI with oauth2 may not logout properly.
oauth2.validation.key	ftlserver.properties	<url>	Required when the oauth2 authentication provider is configured. When a client or another FTL server authenticates to this FTL server using an oauth2 access token, FTL server will validate the signature of the access token using one of the given validation keys. The <url> specifies the location of the validation keys. There are two valid forms: "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(s)" url is specified, FTL server will fetch the JWKS file by making an http(s) request to the specified URL. For "https" urls, "oauth2.provider.trust.file" may be specified as well.

Authenticating to other FTL Servers

When authentication is enabled, FTL server must authenticate itself to other FTL servers. FTL server must be configured to do basic authentication, mTLS authentication, or oauth2 authentication. It is an error to specify multiple authentication modes for outgoing connections. (It is not an error to specify multiple authentication providers for incoming connections.)

For more information, see Authenticating to FTL Server.

Parameter	Location	Arguments	Description
user	ftlserver.properties	<username>	Used for basic authentication to other FTL servers. If specified alongside "oauth2.svr.endpoint.token", this parameter is instead used for the oauth2 password credentials grant. It is an error to specify this parameter alongside "tls.client.cert" or "oauth2.access.token".
password	ftlserver.properties	<password>	Used for basic authentication to other FTL servers. Used for basic authentication to other FTL servers. Required when "user" is present. If specified alongside "oauth2.svr.endpoint.token", this parameter is instead used for the oauth2 password credentials grant. It is an error to specify this parameter alongside "tls.client.cert" or "oauth2.access.token". To hide the password from casual observers, see Password Security.
tls.client.cert	ftlserver.properties	<path>	Used for mTLS authentication to other FTL servers. Specifies the location of the identity certificate used when FTL server connects as a TLS client to another FTL server. The file must be in PEM format. Intermediate certificates may be appended to the file. It is an error to specify this parameter alongside "user", "oauth2.svr.endpoint.token", or "oauth2.access.token".
tls.client.private.key	ftlserver.properties	<path>	Used for mTLS authentication to other FTL servers. The file must contain the private key corresponding to the identity certificate in "tls.client.cert". The file must be in PEM format. The private key may be encrypted or unencrypted. It is an error to specify this parameter alongside "user", "oauth2.svr.endpoint.token", or "oauth2.access.token".
tls.client.private.key.password	ftlserver.properties	<password>	Used for mTLS authentication to other FTL servers. Required when "tls.client.private.key" contains an encrypted private key. The password is used to decrypt the private key. It is an error to specify this parameter alongside "user", "oauth2.svr.endpoint.token", or "oauth2.access.token". To hide the password from observers, see Password Security.
oauth2.svr.endpoint.token	globals	<url>	Used for oauth2 authentication to other FTL servers. FTL server fetches an access token from this endpoint For "https" URLs, you might need to specify "oauth2.provider.trust.file". It is an error to specify this parameter alongside "tls.client.cert" or "oauth2.access.token".
`oauth2.svr.client.id`	ftlserver.properties	<string>	Used for oauth2 authentication to other FTL servers. Required when "oauth2.svr.endpoint.token" is specified. Specifies the oauth2 client id for oauth2 authentication. It is an error to specify this parameter alongside "tls.client.cert" or "oauth2.access.token".
oauth2.svr.client.secret	ftlserver.properties	<password>	Used for oauth2 authentication to other FTL servers. Required when "oauth2.svr.endpoint.token" is specified. Specifies the oauth2 client secret for the oauth2 client credentials grant. If "user" and "password" are specified, the oauth2 password credentials grant is used instead. It is an error to specify this parameter alongside "tls.client.cert" or "oauth2.access.token". To hide the password from observers, see Password Security.
oauth2.access.token	ftlserver.properties	<password>	Used for oauth2 authentication to other FTL servers. Instead of fetching an access token from an oauth2 endpoint, FTL server uses this access token as long as it is running. The access token must be long-lived. It is an error to specify this parameter alongside "user", "tls.client.cert" or "oauth2.svr.endpoint.token". To hide the password from observers, see Password Security.

TLS Security

TLS can be enabled for FTL server using FTL-generated certificates or user-defined certificates. It is an error to configure both. When enabling TLS, authentication must also be enabled.

When set, by default TLS is enabled for the REST API, UI, realm connections from FTL clients, connections from eFTL clients, and connections between affiliated FTL servers. TLS for other services (for example, persistence services) may be optionally enabled through the realm configuration. For more details, see Enabling TLS for FTL Server.

Parameter	Location	Arguments	Description
tls.secure	globals	<password>	When present, TLS is enabled for FTL server using FTL-generated certificates. The password argument decrypts the TLS key file, which was generated before starting the FTL server. It is an error to combine this with "tls.server.cert". For more information, see Enabling TLS for FTL Server. To hide the password from observers, see Password Security.
`tls.server.cert`	ftlserver.properties	<path>	When present, TLS is enabled for FTL server using user-defined certificates. The file must contain the FTL server's identity certificate in PEM format. Intermediate certificates, also in PEM format, might be appended to the file. The certificate must have one or more subject alternative names. When clients or other FTL servers connect to this FTL server, they compare the host in their connect address to the set of subject alternative names. One of the names must match. One level of wildcarding is permitted in DNS names. It is an error to combine this with "tls.secure".
`tls.server.private.key`	ftlserver.properties	<path>	Required when "tls.server.cert" is specified. The file must contain the private key corresponding to the identity certificate in "tls.server.cert". The file must be in PEM format. The private key may be encrypted or unencrypted.
`tls.server.private.key.password`	ftlserver.properties	<password>	Required when "tls.server.private.key" contains an encrypted private key. The password is used to decrypt the private key. To hide the password from observers, see Password Security.
`tls.security.level`	globals	<level>	Optional. When specified, set the openssl security level for TLS connections. The <level> must be an integer from 1 to 5. When absent, the default value is 2. In general, a higher security level causes FTL to enforce stricter requirements for key sizes and encryption. Refer to the openssl documentation for full details. For example, if an RSA key is too small for the given security level, FTL will reject the TLS connection. The openssl security level applies to: TLS connections among FTL clients and FTL servers TLS connections accepted by FTL server for the REST API, UI, or eFTL clients
`tls.client.trust.file`	ftlserver.properties	<path>	Optional. It is an error to specify this parameter when using FTL-generated certificates (that is, when "tls.secure" is set). When using FTL-generated certificates, administrators must place the "ftl-trust.pem" file in the realm data directory of the FTL server. See Enabling TLS for FTL Server. Otherwise, when using user-defined certificates ("tls.server.cert"), this file identifies the trust certificates when FTL server connects as a TLS client to other FTL servers. The file must be in PEM format. When absent, FTL server loads the system trust store when connecting to other FTL servers.
`tls.trust.everyone`	globals		Optional. The FTL server trusts any other FTL server without verifying trust in the other service's certificate. Warning: Do not use this parameter except for convenience in development and testing. It is not secure.

Administrative URL Configuration

This section describes the admin.url configuration parameter, which enables administrators to configure a dedicated port for REST API and administrative UI access.

The admin.url parameter separates administrative traffic from client messaging traffic by providing a dedicated endpoint for REST API requests and UI access.

When admin.url is configured, all REST API requests must be sent to the configured URL. REST requests sent to the FTL server's primary messaging port are rejected.

Parameter	`admin.url`
Location	ftlserver.properties
Arguments	url
Description	Optional. Specifies a dedicated URL for administrative REST API and UI access. When set, REST API requests on the primary FTL server port are rejected.

URL Formats

The admin.url parameter accepts the following formats:

`*:<port>`	Listen on all network interfaces on the specified port
`<host>:<port>`	Listen on a specific host or IP address and port
`http://<host>:<port>`	Equivalent to `<host>:<port>`; the `http://` prefix is stripped internally
`http://*:<port>`	Equivalent to `*:<port>`; the `http://` prefix is stripped internally

Important: The following restrictions apply to admin.url:

Port-only syntax (:<port>) is not allowed. You must specify a host. Use *:<port> for all interfaces or <host>:<port> for a specific host.

HTTPS is not supported. Specifying https:// causes the FTL server to exit with an error.

Behavior

When admin.url is configured:

The REST API and administrative UI listen exclusively on the specified URL.
REST API requests sent to the FTL server's primary messaging port are rejected.
Client messaging traffic remains isolated from administrative traffic.

When admin.url is not configured:

The REST API and administrative UI listen on the FTL server's primary messaging port alongside client messaging traffic (default behavior).

REST Requests

If admin.url is configured, you must sent the REST requests to the configured administrative URL. See Administrative URL Configuration.

Parameter	Location	Arguments	Description
origins.allowed	globals	<string array>	When absent, the default behavior rejects all cross-origin requests. When present, allows REST requests that originate from hostnames in the specified array of strings. The FTL server rejects cross-origin requests from any other origin. The special value * allows all origins. Note: This parameter must be specified as a yaml string array. For example: origins.allowed: - host1 - host2 - *

Parameter

Location

Arguments

Description

origins.allowed

globals

When absent, the default behavior rejects all cross-origin requests.

When present, allows REST requests that originate from hostnames in the specified array of strings. The FTL server rejects cross-origin requests from any other origin.

The special value * allows all origins.

Note: This parameter must be specified as a yaml string array. For example:

origins.allowed:
  - host1
  - host2
  - *

Affiliated FTL Servers

Parameter	Location	Arguments	Description
satelliteof	globals	<urls>	When present, designate this FTL server as a satellite of a set of primary FTL servers. Supply a pipe-separated URL list of primary FTL servers. For example: https://<host1>:<port1>\|https://<host2>:<port2>\|https://<host3>:<port3> A satellite receives its realm definition and accepts realm updates from any primary realm service. The realm service in a satellite does not accept client connection requests until it first receives a realm definition from a primary.
`dr`	globals	<url list>	This parameter is used for the simplified DR model only. See Selecting a Disaster Recovery Model. Do not specify `drto` or `drfor` when using the simplified model. When present, the DR feature is enabled for FTL server. You must specify this parameter at both the primary and DR sites. At the primary site, the value should be the URL list used to connect to the DR site. At the DR site, the value must be the URL list used to connect to the primary site. If you are starting FTL servers for the first time, you must also identify the primary site. Do this either by specifying `auto.init.primary.on.first.startup` at one of the sites (see below), or issuing the `activate_dr` administrative command. See FTL Administration Utility.
`drfor`	globals	<URL_list>	This parameter is used for the classic DR model only. See Selecting a Disaster Recovery Model. Do not specify `dr` when using the classic model. When present, this FTL server starts as a disaster recovery server for a set of primary FTL servers. Supply a pipe-separated URL list of primary FTL servers. The primaries initiate the connection to disaster recovery servers.
`drto`	globals	<URL_list>	This parameter is used for the classic DR model only. See Selecting a Disaster Recovery Model. Do not specify `dr` when using the classic model. When present, the primary FTL server attempts to connect to a set of disaster recovery servers. Supply a pipe-separated URL list of disaster recovery FTL servers. (You must separately specify the `drfor` parameter in the configuration file of the disaster recovery servers.)
`timeout`	globals	<timeout>	Optional. FTL servers use this timeout for communication between other FTL servers in the same cluster. For example, this timeout applies to communication among core and auxiliary FTL servers at a given primary, satellite, or DR site.
`heartbeat`	globals	<hb_interval>	Optional. An FTL server sends its heartbeat signal at `<hb_interval>`, in seconds. Supply a positive number. When absent, the default value is 1 second. This applies to communication among core and auxiliary FTL servers at a given primary, satellite, or DR site.
`auto.init.primary.on.first.startup`	globals	boolean	This parameter is used for the simplified DR model only. See Selecting a Disaster Recovery Model. Do not specify `drto` or `drfor` when using the simplified model. Optional. When present (and the value is true), and you are starting FTL servers for the first time (that is there is no state on disk), this parameter indicates that the site must automatically become primary. The other site takes on the DR role. Specify this parameter in the FTL server yaml configuration file at only one of the sites. Do not specify this parameter at both sites. When the FTL server has initialized (and created state on disk), this parameter is ignored. You may leave this parameter in the FTL server yaml configuration file. Note that, by default, this parameter only takes effect if the two sites are able to contact each other. However, if you also specify `auto.init.primary.on.no.contact`, this parameter takes effect even if the other site is unreachable. If you do not specify `auto.init.primary.on.first.startup`, and you are starting FTL servers for the first time, you need to pick a primary site by issuing the `activate_dr` command at one of the sites. See FTL Administration Utility.
`auto.init.primary.on.no.contact`	globals	boolean	This parameter is used for the simplified DR model only. Do not specify `drto` or `drfor` when using the simplified model. Optional. By default, in the simplified DR model, if the primary site suffers a complete shutdown and restart (not a normal rolling upgrade/restart), and the other site is unreachable, the primary site remains out of service (no client connections) until it can contact the other site. If you do not specify this parameter, and the primary site suffers a complete shutdown and restart when the DR site is unreachable, you need to issue the `activate_dr` command at the primary site to resume servicing clients. See FTL Administration Utility. However, if this parameter is present (and true), and the site's most recent role was the primary role (not DR), the site resumes servicing clients automatically, even if it cannot contact the other site. Use this parameter when you want to ensure availability of the primary site in the event of failures at the DR site or failures of the network link to the DR site. If you use this parameter, specify it in the FTL server yaml configuration file at both sites. It is ignored at the DR site, unless the DR site is activated. When using this parameter, you must have a strategy for avoiding "split-brain" following an unplanned DR failover. If an unplanned DR failover occurs, and you want to fail back to the original primary site, you restart the FTL servers at the original primary site. If this parameter is present, and the network link to the DR site is still down, the original primary site resumes servicing clients, which is usually undesirable. See Simplified Disaster Recovery for a discussion of your choices.

Logging

Parameter	Location	Arguments	Description
loglevel	ftlserver.properties	<level>	When present, the FTL server logs events at this level of detail. You might specify any of the standard log level strings . See Tuning the Log Level in TIBCO FTL® - Enterprise Edition Development. You can set a general log level, or custom log levels for different elements. When this parameter is absent, the default level is info. See also Logging in the context of security.
`logfile`	ftlserver.properties	<logfile_prefix>	When present, the FTL server logs to a rolling set of log files instead of the console. The <logfile_prefix> argument might denote a path. All of the directories in the path must already exist. For more information about rotating log files, see Log Output Targets in TIBCO FTL® - Enterprise Edition Development. When absent, the FTL server sends log output to the console, ignoring the parameters max.log.size and max.logs.
max.log.size	ftlserver.properties	<size>	Optional Available if logfile is set. Limits the maximum size, in bytes, of log files. The value must be greater than 100 kilobytes (102400 bytes). If max.log.size is not specified, the default of 20 MB is used.
max.logs	ftlserver.properties	<logs>	Optional. Available if logfile is set. Limits the maximum number of rolling log files. max.logs can be: Not specified: The FTL server uses the default value of 20. Equal to 1: The max.log.size is ignored. A number greater than 1 and less than 1000.

Did you find this helpful?

Yes No