The main configuration file controls the characteristics of the EMS server. This file is usually named tibemsd.conf, but you can specify another file name when starting the server. You can find more information about starting the server in
Running the EMS Server.
An example of the tibemsd.conf file is included in the
config-file-directory/cfmgmt/ems/data/ directory, where
config-file-directory is specified during TIBCO Enterprise Message Service installation. You can edit this configuration file with a text editor. There are a few configuration items in this file that can be altered using the administration tool, but most configuration parameters must be set by editing the file (that is, the server does not accept changes to those parameters). See
Chapter 6, Using the EMS Administration Tool for more information about using the administration tool.
•
|
enable, enabled, true, yes, on
|
The following table summarizes the parameters in tibemsd.conf according to category. The sections that follow provide more detail on each parameter.
See Chapter 8, Authentication and Permissions for more information about these parameters.
The compliant_queue_ack parameter is enabled by default. Because of the extra overhead incurred with compliant queue acknowledgments, you can disable this feature when performance is an issue. If compliant queue acknowledgement is disabled and a message is redelivered, the message’s
JMSRedelivered indicator will be set.
This parameter works in conjunction with the maxbytes and
maxmsgs destination properties. In situations where consumers consume messages but do not acknowledge them, the messages are held in the server until they are confirmed. This can push the server above the set limits.
When enabled, disconnect_non_acking_consumers causes the server to check the number and size of pending messages sent to a consumer. If the
maxbytes or
maxmsgs limit is reached and the consumer has not acknowledged its messages, the server discards the messages sent to the consumer and disconnects the consumer’s connection. This protects the server against applications that consume messages without ever acknowledging them.
Before enabling this property, ensure that the maxbytes and
maxmsgs limits are set with reference to the
prefetch setting, the size of the transaction (if transacted receive), or number of messages acknowledged when using client or explicit client acknowledgment mode. Otherwise the server may disconnect the consumer before it has a chance to acknowledge the messages.
When routes are deployed, all routed servers should use the same disconnect_non_acking_consumers setting. Additionally, if
maxbytes or
maxmsgs is set for a global destination, the same setting should be applied on all servers. The server does not discard or disconnect a routed consumer, since disconnecting the route may impact other well-behaved applications. Servers discard and disconnect their local consumers, which other servers involved are made aware of and discard messages for those remote consumers accordingly.
By default, flow control is disabled. When flow control is enabled, the flowControl property on each destination specifies the target maximum storage for pending messages on the destination.
See Flow Control for more information about flow control.
You can use multiple listen entries if you have computers with multiple interfaces. For example:
If localhost is specified, or if the
servername is not present, then the server uses every available interface. For example:
Specify signed 32-bit integer values as KB,
MB or
GB. The minimum permitted size is
1 KB. By default, the field limit is
1 KB.
Specify signed 32-bit integer values as KB,
MB or
GB. The minimum permitted size is
8 KB. By default, the field limit is
8 KB.
where shared-library-directory is the absolute path to the directory containing any library the server is dependent on. This may include TIBCO FTL, Rendezvous, or SmartSockets libraries, as well as OpenSSL or the JVM.
|
The module_path parameter is also used on AIX platform installations to load the IBM JVM. Specify the directories containing the libjvm.so and its dependent libraries.
|
The threads count can be any positive integer. The default value is
1.
The npsend_check_mode parameter applies only to producers sending messages using
NON_PERSISTENT delivery mode and non-transactional sessions.
•
|
When authorization is enabled, so the producer can take action if permission to send the message is denied by the server.
|
The possible npsend_check_mode parameter modes are:
•
|
always - the server always provides confirmation of a NON_PERSISTENT message.
|
•
|
never - the server never provides confirmation of NON_PERSISTENT messages.
|
•
|
temp_dest - the server provides confirmation of a NON_PERSISTENT message only when sending to a temporary destination.
|
•
|
auth - the server provides confirmation of a NON_PERSISTENT message only if authorization was enabled when the connection was created.
|
•
|
temp_auth - the server provides confirmation of a NON_PERSISTENT message if sending to a temporary destination or if authorization was enabled when the connection was created.
|
Specify the processor-id as an integer. Ask your system administrator for the valid processor IDs on the EMS Server host. Note that the IDs can be listed in any order. List IDs in a comma-separated list, with no spaces separating list items. For example:
See Chapter 20, Working With Routes for more information about routing.
The server evaluates operators until reaching the specified number of false conditions. The server then stops evaluating further to protect itself from too many recursive evaluations. A very long selector clause, such as one including many
OR conditions, can cause recursive selector evaluation and lead to a stack overflow in the EMS server.
number may be any positive integer. The default value is
5000. Zero is a special value, indicating no limit.
For example, if selector_logical_operator_limit = 10 and the selector is:
•
|
SSL—If SSL initialization fails, then it exits.
|
•
|
TRANSPORTS—If any of the transports cannot be created as specified in the configuration files, then it exits.
|
•
|
CONFIG_FILES—If any configuration file listed in tibemsd.conf does not exist, then it exits.
|
•
|
CONFIG_ERRORS—If the server detects any errors while reading the config files, then it exits.
|
Note that the tibemsd silently ignores any unknown parameters when it is started using the JSON configuration. For example, no configuration errors are thrown if the
tibemsd.json file contains an obsolete parameter.
•
|
DB_FILES—If the server cannot find one or more of its stores, then it exits. Stores include the default store files as well as any file or database stores configured in the stores.conf configuration file.
|
Note that if DB_FILES is
not included in the
startup_abort_list and the server cannot find a store, the server will create the missing file or database. For best results, do not include
DB_FILES the first time a server is started, allowing it to create the files. After after initial startup or a major store configuration change (such as the addition of a new store), include
DB_FILES in the list so that on restart the server will only start if all the configured files are present.
•
|
local—obtain user authentication information from the local EMS server user configuration.
|
•
|
ldap—obtain user authentication information from an LDAP directory server (see the LDAP-specific configuration parameters).
|
|
The user_auth setting does not affect authentication of the default administrator. The server always authenticates the admin user from the local configuration file. See Assign a Password to the Administrator for more information.
|
The specified number may be any positive value. When
destination_backlog_swapout is
0, the server attempts to immediately swap out the message.
Specifies the number of messages that an unbounded destination (a destination without either of its maxbytes or
maxmsgs properties set) can gather before the server starts logging warnings about that destination’s message count. By default,
large_destination_count is not set and the server establishes its own message count threshold. It can be set dynamically. Zero is a special value that disables the logging of the corresponding warning.
Specifies the size in memory that an unbounded destination (a destination without either of its maxbytes or
maxmsgs properties set) can grow to before the server starts logging warnings about that destination’s size. By default,
large_destination_memory is not set and the server establishes its own size threshold. It can be set dynamically. Zero is a special value that disables the logging of the corresponding warning.
Specify whole numbers as KB,
MB or
GB. The maximum value is 2 GB.
When msg_swapping is enabled, and messages overflow this limit, the server begins to swap messages from process memory to disk. Swapping allows the server to free process memory for incoming messages, and to process message volume in excess of this limit.
Specify units as KB,
MB or
GB. The minimum value is 8 MB. The default value of 0 (zero) indicates no limit.
To lessen the overhead costs associated with malloc and
free, the server pre-allocates pools of storage for messages. This parameter determines the behavior of these pools. Performance varies depending on operating system platform and usage patterns.
The size argument determines the approximate number of internal message structs that a block or pool can accommodate (not the number of bytes).
msg_pool_block_size instructs the server to allocate an
expandable pool. Each time the server exhausts the pool, the server increases the pool by this size, as long as additional storage is available. The value may be in the range
32 to
65536.
The default value is enabled, unless you explicitly set it to
disabled.
When reserve_memory is non-zero, the EMS server allocates a block of memory for use in emergency situations to prevent the EMS server from being unstable in low memory situations. When the server process exhausts memory resources, it disables clients and routes from producing new messages, and frees this block of memory to allow consumers to continue operation (which tends to free memory).
The reserve_memory parameter only triggers when the EMS server has run out of memory and therefore is a reactive mechanism. The appropriate administrative action when an EMS server has triggered release of reserve memory is to drain the majority of the messages by consuming them and then to stop and restart the EMS server. This allows the operating system to reclaim all the virtual memory resources that have been consumed by the EMS server. A trace option,
MEMORY, is also available to help show what the server is doing during the period when it is not accepting messages.
Specify size in units of MB. When non-zero, the minimum block is 16MB. When absent, the default is zero.
The specified size may be:
•
|
0 to use the default buffer size
|
•
|
-1 to skip the call for the specified buffer
|
The specified size may be:
•
|
0 to use the default buffer size
|
•
|
-1 to skip the call for the specified buffer
|
The client_heartbeat_server parameter must be specified when a server_timeout_client_connection is set. The
client_heartbeat_server interval should be no greater than one third of the
server_timeout_client_connection limit.
When omitted or zero, client_heartbeat_server is disabled.
When omitted or zero, the EMS server sends the offset time only when the EMS client connects to the server. If clock_sync_interval is
-1, the offset is never sent, not even on connect. Clients do not adjust their time values to match the server time.
|
If you do not set the client_heartbeat_server parameter when a server_timeout_client_connection is specified, a configuration error is generated during startup. If CONFIG_ERRORS is part of the startup_abort_list, the server will not start. If not, the error is printed but the server starts, and clients will be disconnected after server_timeout_client_connection seconds.
|
See Chapter 19, Fault Tolerance for more information about these parameters.
The fault tolerance parameters that begin with the prefix ft_ssl are used to secure communications between pairs of fault tolerant servers. See
SSL for additional information about this process.
See the server_timeout_server_connection parameter for more information on heartbeats.
See File Names for Certificates and Keys for more information on file types for digital certificates.
You can set passwords by way of the tibemsadmin tool. When passwords are set with this tool, the password is obfuscated in the configuration file. See
Chapter 6, Using the EMS Administration Tool for more information about using
tibemsadmin to set passwords.
See File Names for Certificates and Keys for more information on file types for digital certificates.
Specifies whether the fault-tolerant server should verify the other server’s certificate. The values for this parameter are enabled or
disabled. By default, this parameter is enabled, signifying the server should verify the other server’s certificate.
When this parameter is set to disabled, the server establishes secure communication with the other fault-tolerant server, but does not verify the server’s identity.
Specifies whether the fault-tolerant server should verify the name in the CN field of the other server’s certificate. The values for this parameter are enabled and
disabled. By default, this parameter is enabled, signifying the fault-tolerant server should verify the name of the connected host or the name specified in the
ft_ssl_expected_hostname parameter against the value in the server’s certificate. If the names do not match, the connection is rejected.
When this parameter is set to disabled, the fault-tolerant server establishes secure communication with the other server, but does not verify the server’s name.
This parameter is used when the ft_ssl_verify_hostname parameter is set to enabled.
See Specifying Cipher Suites for more information about the cipher suites available in EMS and the OpenSSL names and longer names for the cipher suites.
Enabling this parameter allows you to display messages using the show messages correlationID command in the administration tool.
When absent, ftl_discard_amount defaults to
5000.
Sets the com.tibco.ftl.client.discard.amount property. For more details, see the TIBCO FTL documentation on event queues.
When absent, ftl_discard_max_events defaults to
100000.
Sets the com.tibco.ftl.client.discard.max_events property. For more details, see the TIBCO FTL documentation on event queues.
When absent, ftl_discard_policy is
old.
Sets the com.tibco.ftl.client.discard.policy property. For more details, see the TIBCO FTL documentation on event queues.
Sets the com.tibco.ftl.client.userpassword property. For more details, see the TIBCO FTL documentation on realms.
For example, ftl_url=http://localhost:5633.
Sets the com.tibco.ftl.client.secondary property. For more details, see the TIBCO FTL documentation on realms.
Sets the com.tibco.ftl.client.username property. For more details, see the TIBCO FTL documentation on realms.
Unless you explicitly set this parameter to enabled, the default value is
disabled—that is, all transports are disabled and will neither send messages to external systems nor receive messages from them.
Unless you explicitly set this parameter to enabled, the default value is
disabled—that is, all transports are disabled and will neither send messages to external systems nor receive message from them.
Unless you explicitly set this parameter to enabled, the default value is
disabled—that is, all transports are disabled and will neither send messages to external systems nor receive message from them.
•
|
tal_ss.cat is a required file of messages. If it is missing, tibemsd outputs a warning message.
|
•
|
tibems_ss.cm is an optional file of SmartSockets RTclient configuration options.
|
When this parameter is absent, tibemsd searches for these files in its current working directory.
See Chapter 17, Monitoring Server Activity for more information about these parameters.
Administrators can trace a connection or group of connections. When this property is enabled, the server instructs each client to generate trace output for opening or closing a connection, message activity, and transaction activity. This type of tracing does not require restarting the client program.
Each client sends trace output to location, which may be either
stderr (the default) or
stdout.
The default behavior is to trace all connections. You can specify either user,
connid or
clientid to selectively trace specific connections. The
value can be a user name or ID (as appropriate).
Setting this parameter using the administration tool does not change its value in the configuration file tibemsd.conf; that is, the value does not persist across server restarts unless you set it in the configuration file.
Sets trace options for output to stderr. The possible values are the same as for
log_trace. However, console tracing is independent of log file tracing.
If logfile is defined, you can stop console output by specifying:
If the pathname contains spaces, it must be enclosed in double quotes.
Sets the trace preference on the file defined by the logfile parameter. If
logfile is not set, the values have no effect.
•
|
+ A trace option preceded by + adds the option to the current set of trace options.
|
•
|
- A trace option preceded by - removes the option from the current set of trace options.
|
If the secondary_logfile parameter is not set, the secondary server assumes the value of
logfile.
If the pathname contains spaces, it must be enclosed in double quotes.
See Chapter 17, Monitoring Server Activity for more information about these parameters.
See Chapter 18, Using the SSL Protocol for more information about these parameters.
See Specifying Cipher Suites for more information about the cipher suites available in EMS and the syntax for specifying them in this parameter.
If this parameter is set to enable, the server only accepts SSL connections from clients that have digital certificates. Connections from clients without certificates are denied.
If this parameter is set to disable, then connections are accepted from clients that do not have a digital certificate.
Whether this parameter is set to enable or
disable, clients that do have digital certificates are always authenticated against the certificates supplied to the
ssl_server_trusted parameter.
If ssl_require_route_cert_only is set to
enable, the server requires a digital certificate only for SSL connections coming from routes, regardless of the value of
ssl_require_client_cert. In this case, the server does not require a digital certificate for SSL connections coming from clients and from its fault-tolerant peer.
If ssl_require_route_cert_only is set to
disable, whether the server requires a digital certificate for SSL connections coming from all sources (routes, clients, and fault-tolerant peer) still depends on the value of
ssl_require_client_cert.
If this parameter is set to enable, a client’s user name is always extracted from the CN field of the client’s digital certificate, if the digital certificate is specified. If a different username is provided through the connection factory or API calls, then that username is discarded. Only the username from the CN is used.
|
When ssl_use_cert_username is enabled, the username given by the CN becomes the only valid username. Any permissions associated with a different username, for example one assigned with an API call, are ignored.
|
For example, you may wish all clients to specify their username when logging in. This means the ssl_use_cert_username parameter would be set to
disable. The username is supplied by the user, and not taken from the digital certificate. However, you may wish one username to signify that the client logging in with that name should have the name taken from the certificate. A good example of this username would be
anonymous. All clients logging in as
anonymous will have their user names taken from their digital certificates.
Also, the value of this parameter is ignored if ssl_use_cert_username is set to
enable, in which case all client usernames are taken from their certificates. This parameter has no effect for users that have no certificate.
You can set passwords by way of the tibemsadmin tool. When passwords are set with this tool, the password is obfuscated in the configuration file. See
Chapter 6, Using the EMS Administration Tool for more information about using
tibemsadmin to set passwords.
|
Because connection factories do not contain the ssl_password (for security reasons), the EMS server uses the password that is provided in the "create connection" call for user authentication. If the create connection password is different from the ssl_password, the connection creation will fail.
|
See File Names for Certificates and Keys for more information on file types for digital certificates.
See File Names for Certificates and Keys for more information on file types for digital certificates.
When enabled, the server allows clients to request the use of SSL only for authentication (to protect user passwords). For an overview of this feature, see
SSL Authentication Only.
When disabled, the server ignores client requests for this feature. When absent, the default value is
disabled.
When true, the EMS server is enabled to run in FIPS 140-2 compliant mode. When
false or excluded, the server is not FIPS compliant. For more information, see
Enabling FIPS Compliance.
See Chapter 8, Authentication and Permissions for more information about these parameters.
The password associated with the user defined in the ldap_principal property. This value must be specified and cannot be an empty string.
•
|
ldaps—Use SSL on the LDAP connection (secure).
|
•
|
startTLS—Use the startTLS extension to the LDAP version 3 protocol (secure).
|
You must provide ldap_tls_cacert_file in order to create secure connections. Optionally, ldap_tls_cacert_dir can be used
in addition to ldap_tls_cacert_file in order to specify a directory with additional individual CA certificates.
You must also provide ldap_tls_cacert_file in order to create secure connections.
ldap_tls_cacert_dir is an optional parameter that can be used
in addition to ldap_tls_cacert_file in order to specify a directory with additional individual CA certificates.
This parameter must follow the OpenSSL cipher string syntax; see Specifying Cipher Suites. You must use OpenSSL names when specifying the suite. For example, use
AES128-SHA rather than
TLS_RSA_WITH_AES_128_CBC_SHA. Using Java names results in an authorization error when connecting to a client.
See Chapter 8, Authentication and Permissions for more information about these parameters.
Specifies how deeply under the base DN to search for users. You can specify onelevel and
subtree for this parameter.
onelevel specifies to search only one level below the DN,
subtree specifies to search all sub-trees.
Optional LDAP search filter for finding a given user name. Use %s as the placeholder for the user name in the filter. For example:
See Chapter 8, Authentication and Permissions for more information about these parameters.
Specifies how deeply under the base DN to search for groups. You can specify onelevel and
subtree for this parameter.
onelevel specifies to search only one level below the DN,
subtree specifies to search all sub-trees.
Enables the JVM in the EMS server, where path is the absolute path to the JRE shared library file that is installed with the JRE. Depending on your platform, this could be
jvm.dll,
libjvm.so,
libjvm.dylib, and so forth. Note that
tibemsd must point to a 64-bit JVM.
If the path contains any spaces, the path must be enclosed in quotation marks.
Passes command line options to the JVM at start-up. The jre_option parameter can be used to define Java system properties, which are used by applications running in the JVM, such as extensible security modules.