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, 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 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, 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 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 will consider 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 may 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 will include a client certificate. This file contains the trust certificate(s) 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 will interpret 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 will interpret 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 will ensure 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 will validate the signature of the access token using one of the given validation keys. The <url> specifies the location of the validation key(s). 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.srv.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 key(s). 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 will fetch an access token from this endpoint For “https” urls, you may 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.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 will use 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, may 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 will 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 will cause 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 (i.e., when “tls.secure” is set). When using FTL-generated certificates, administrators should 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 certificate(s) when FTL server connects as a TLS client to other FTL servers. The file must be in PEM format. When absent, FTL server will load 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.

REST Requests

Parameter	Location	Arguments	Description
origins.allowed	globals	<<URLs>>	When absent, the default behavior rejects all cross-origin requests. When present, allow REST requests that originate from URLs in an array of strings. The realm service rejects cross-origin requests from any other origin. The special value * allows all origins. Warning: Do not supply this parameter except when necessary. Supplying a null string in the argument list of this parameter is not a recommended security practice.

Parameter

Location

Arguments

Description

origins.allowed

globals

<<URLs>>

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

When present, allow REST requests that originate from URLs in an array of strings. The realm service rejects cross-origin requests from any other origin.

The special value * allows all origins.

Warning: Do not supply this parameter except when necessary. Supplying a null string in the argument list of this parameter is not a recommended security practice.

Affiliated FTL Servers

For information about disaster recovery servers, see Disaster Recovery Prerequisites

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.
`drfor`	globals	<URL_list>	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>	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.

Logging

Parameter	Location	Arguments	Description
loglevel	ftlserver.properties	<level>	When present, the FTL server logs events at this level of detail. You may specify any of the standard log level strings . See “Tuning the Log Level” and its sub-topics in TIBCO FTL 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 may 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 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 than 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