Chapter 7 Using the Configuration Files : tibemsd.conf

tibemsd.conf
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.
Several parameters accept boolean values. In the description of the parameter, one specific set of values is given (for example, enable and disable), but all parameters that accept booleans can have the following values:
enable, enabled, true, yes, on
disable, disabled, false, no, off
Parameters that take multiple elements cannot contain spaces between the elements, unless the elements are enclosed in starting and ending double quotes. Parameters are limited to line lengths no greater than 256,000 characters in length.
The following table summarizes the parameters in tibemsd.conf according to category. The sections that follow provide more detail on each parameter.
Guarantees that a message will not be redelivered after a client has successfully acknowledged its receipt from a routed queue.
Specifies the port on which the server is to listen for connections from clients.
Specifies when the server is to provide confirmation upon receiving a NON_PERSISTENT message from a producer.
Specifies conditions under which the server is to exit during its initialization sequence.
Specifies the source of authentication information used to authenticate users attempting to access the EMS server.
Specifies whether the EMS server validates CRC checksum data when reading the store files.
Specifies the amount of disk space to preallocate for EMS store files.
Specifies whether the EMS server is to periodically truncate the storage files to relinquish unused disk space.
Specifies the maximum number of simultaneous client connections to the server.
Specifies the amount of memory to reserve for use in emergency situations.
Specifies the size of the pool to be pre-allocated by the server to store messages.
Specifies the period of time server will wait for a client heartbeat before terminating the client connection.
Specifies the period of time this server will wait for a heartbeat from another server before terminating the connection to that server.
Specifies the interval this server is to send heartbeats to all of its clients.
Specifies the period of time a client will wait for a heartbeat from the server before terminating the connection.
Specifies the interval the active server is to send a heartbeat signal to the backup server to indicate that it is still operating.
Specifies the maximum length of time between heartbeat signals the backup server is to wait before assuming the active server has failed.
Specifies the maximum length of time the backup server is to wait for clients to reconnect after assuming the role of primary server in a failover situation.
Specifies whether the fault-tolerant server should verify the other server’s certificate.
Specifies whether the fault-tolerant server should verify the name in the CN field of the other server’s certificate.
Specifies the name the server is expected to have in the CN field of the fault-tolerant server’s certificate.
Specifies the configuration file where multicast channels are defined.
Specifies the default port on which the multicast daemon listens for connections from EMS clients.
Specifies how often, in seconds, multicast statistics are generated for each channel.
Enable or disable the translation of XML fields to byte arrays when importing messages from Rendezvous.
Specifies the directory for SmartSockets configuration and message files.
Specifies the trace options on the file defined by the logfile parameter.
Specifies the maximum log file size before the log file is copied to a backup and then emptied.
Enable or disable client generation of trace output for opening or closing a connection, message activity, and transaction activity.
Specifies whether the trace statements related to connections identify the host by its hostname, its IP address, or both.
Specifies the interval at which overall server statistics are averaged.
Enables or disables statistic gathering for producers, consumers, destinations, and routes.
Specifies the interval at which statistics for routes, destinations, producers, and consumers are averaged.
Specifies which objects should have detailed statistic tracking.
Specifies how long the server should keep detailed statistics if the destination has no activity.
Specifies the maximum amount of memory to use for detailed statistic gathering.
Specifies if the server is to only accept SSL connections from clients that have digital certificates.
Specifies if a client’s user name is to always be extracted from the CN field of the client’s digital certificate.
Specifies a special username to identify which clients are to have their usernames taken from their digital certificates.
Specifies the list of CA root certificates the server trusts as issuers of client certificates.
Specifies the pathname to the certificate revocation list (CRL) files.
Specifies whether the server allows clients to request the use of SSL only for authentication.
Specifies the password associated with the user defined in the ldap_principal property.
Specifies the maximum time that cached LDAP data is retained before it is refreshed.
Specifies the type of connection that the server uses to get LDAP information.
Specifies the file that contains the CA certificate the EMS server trusts to sign the LDAP server’s certificate.
When there are two or more CA certificates in the verify chain, use this parameter to specify the directory containing the CA certificates.
Specifies the cipher suite to use for encryption on secure LDAP connections.
Specifies the file containing the certificate that identifies the EMS server to the LDAP server.
Specifies the file containing the private key required by the LDAP server to authenticate the client.
Specifies the name of the attribute on the user object class that holds the name of the user.
Specifies the base distinguished name (DN) of the LDAP tree that contains the users.
Specifies the LDAP search filter for finding all users beneath the user base DN.
Specifies the base distinguished name (DN) of the LDAP tree that contains groups.
Specifies the LDAP search filter for finding a group with a given group name.
Specifies the LDAP search filter for finding all groups beneath the group base DN.
Specifies the name of the LDAP object class that stores static groups.
Specifies the name of the attribute on the static group object class that holds the name of the group.
Specifies the attribute of an LDAP static group object that specifies the distinguished names (DNs) of the members of the group.
Specifies the name of the LDAP object class that stores dynamic groups.
Specifies the name of the attribute on the dynamic group object class that holds the name of the group.
Specifies the attribute of the dynamic LDAP group object that specifies the URLs of the members of the dynamic group.
Includes the JAR files and dependent classes used by the JAAS LoginModule.
Specifies the location of the JAAS configuration file used to run a custom authentication LoginModule.
Specifies the length of time, in milliseconds, that the server waits for the JAAS authentication module to execute and respond.
Includes the JAR files and dependent classes used by the JACI custom permissions module.
Specifies the name of the class that implements the extensible permissions interface.
Specifies the length of time, in milliseconds, that the server waits for the JACI permissions module to execute and respond.
Global System Parameters
authorization
authorization = enabled | disabled
Enable or disable server authorization.
Authorization is disabled by default. If you require that the server verify user credentials and permissions on secure destinations, you must enable this parameter.
See Enabling Access Control for more information.
For example:
authorization = enabled
See Chapter 8, Authentication and Permissions for more information about these parameters.
compliant_queue_ack
compliant_queue_ack = enable | disable
Guarantees that, once a client successfully acknowledges a message received from a routed queue, the message will not be redelivered. This is accomplished by the EMS server waiting until the message has been successfully acknowledged by the queue’s home EMS server before sending the response to the client.
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.
flow_control
flow_control = enable | disable
Specifies whether flow control for destinations is enabled or disabled.
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.
listen
listen=protocol://servername:port
Specifies the port on which the server is to listen for connections from clients.
For example:
listen=tcp://localhost:7222
If you are enabling SSL, for example:
listen=ssl://localhost:7222
You can use multiple listen entries if you have computers with multiple interfaces. For example:
listen=tcp://localhost:7222
listen=tcp://localhost:7224
If the hostname is not present then the default host and interface will be used. For example:
listen=tcp://7222
listen=ssl://7243
npsend_check_mode
npsend_check_mode = [always | never | temp_dest | auth | temp_auth]
Specifies when the server is to provide confirmation upon receiving a NON_PERSISTENT message from a producer.
The npsend_check_mode parameter applies only to producers sending messages using NON_PERSISTENT delivery mode and non-transactional sessions.
Message confirmation has a great deal of impact on performance and should only be enabled when necessary. The circumstances in which a producer might want the server to send confirmation a NON_PERSISTENT message are:
When authorization is enabled, so the producer can take action if permission to send the message is denied by the server.
When sending to a temporary destination, so the producer can take action if the message is sent to a temporary destination that has been destroyed.
The possible npsend_check_mode parameter modes are:
default (no mode specified) - same behavior as in EMS 4.3 and prior. This means the server only provides confirmation of a NON_PERSISTENT message if authorization is enabled.
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.
password
password = password
Password used to log in to other routed servers that have authorization enabled.
See Routing and Authorization for details.
routing
routing = enabled | disable
Enables or disables routing functionality for this server.
For example:
routing = enabled
See Chapter 20, Working With Routes for more information about routing.
server
server = serverName
Name of server.
Server names are limited to at most 64 characters.
startup_abort_list
startup_abort_list=[SSL,TRANSPORTS,CONFIG_FILES,CONFIG_ERRORS,
DB_FILES,MULTICAST]
Specifies conditions that cause the server to exit during its initialization sequence.
You may specify any subset of the conditions in a comma-separated list. The list cannot contain spaces between the elements, unless the elements are enclosed in starting and ending double quotes. If a space is included but not enclosed in quotation marks, the server ignores any conditions following the space.
Conditions that do not appear in the list are ignored by the server. The default is an empty list.
The conditions are:
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.
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.
MULTICAST—If the server detects that it cannot send multicast messages, then it exits.
Note that if MULTICAST is not in the startup_abort_list and multicast initialization fails, applications creating consumers on multicast-enabled topics will receive messages over TCP. This is important to consider if your network cannot handle the bandwidth allocated for multicast when it is sent over a TCP connection.
user_auth
user_auth = [local, ldap, jaas]
Specifies the source of user authentication information.
This parameter can have one or more of the following values (separated by comma characters):
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).
jaas—obtain user authentication information from a custom authentication module (see Extensible Authentication).
Each time a user attempts to authenticate, the server seeks corresponding authentication information from each of the specified locations in the order that this parameter specifies. The EMS server accepts successful authentication using any of the specified sources.
Storage File Parameters
The parameters described here configure file-based stores. For information about database stores, see Chapter 10, Using Database Stores.
store
store = directory
Directory in which the server stores data files.
For example:
store = /usr/tmp
store_crc
store_crc = enable | disable
Specifies whether the EMS server validates CRC checksum data when reading the store files.
 
This parameter is not compatible with the use of multiple store files. If you have configured the stores.conf file, or enabled database stores, then including the store_crc parameter will cause a mixed mode error. See Store Messages in Multiple Stores for more information.
This parameter is deprecated in Software Release 5.0. Prepare to migrate to a multiple stores configuration, where the same functionality can be achieved through store definitions in the stores.conf file.
store_minimum
store_minimum = size [KB|MB|GB]
store_minimum_sync = size [KB|MB|GB]
store_minimum_async = size [KB|MB|GB]
This set of parameters preallocates disk space for EMS store files. Preallocation occurs when the server first creates a store file.
You can specify units of KB, MB, or GB.
Zero is a special value, which specifies no minimum preallocation. Otherwise, the value you specify must be greater than or equal to 8MB.
If store_minimum_sync or store_minimum_async are absent, they default to store_minimum.
If store_truncate is enabled, these parameters limit truncation to minimum values.
For example:
store_minimum_sync = 32MB
 
This parameter is not compatible with the use of multiple store files. If you have configured the stores.conf file, or enabled database stores, then including the store_minimum parameter will cause a mixed mode error. See Store Messages in Multiple Stores for more information.
This parameter is deprecated in Software Release 5.0. Prepare to migrate to a multiple stores configuration, where the same functionality can be achieved through store definitions in the stores.conf file.
store_truncate
store_truncate = enable | disable
Specifies whether the EMS server occasionally attempts to truncate the storage files, relinquishing unused disk space.
When enabled, the storage files may be truncated, but not below the size specified in the store_minimum parameters.
 
This parameter is not compatible with the use of multiple store files. If you have configured the stores.conf file, or enabled database stores, then including the store_truncate parameter will cause a mixed mode error. See Store Messages in Multiple Stores for more information.
This parameter is deprecated in Software Release 5.0. Prepare to migrate to a multiple stores configuration, where the same functionality can be achieved through store definitions in the stores.conf file.
Connection and Memory Parameters
max_connections
max_connections = number
Maximum number of simultaneous client connections.
Set to 0 to allow unlimited simultaneous connections.
max_msg_memory
max_msg_memory = size [KB|MB|GB]
Maximum memory the server can use for messages.
This parameter lets you limit the memory that the server uses for messages, so server memory usage cannot grow beyond the system’s memory capacity.
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.
When the server swaps a message to disk, a small record of the swapped message remains in memory. If all messages are swapped out to disk, and their remains still exceed this memory limit, then the server has no room for new incoming messages. The server stops accepting new messages, and send calls in message producers result in an error. (This situation probably indicates either a very low value for this parameter, or a very high message volume.)
Specify units as KB, MB or GB. The minimum value is 8 MB. The default value of 0 (zero) indicates no limit.
For example:
max_msg_memory = 512MB
msg_swapping
msg_swapping = enable | disable
This parameter enables and disables the message swapping feature (described above for max_msg_memory).
The default value is enabled, unless you explicitly set it to disabled.
reserve_memory
reserve_memory = size
When reserve_memory is non-zero, the daemon allocates a block of memory for use in emergency situations to prevent the EMS server from being unstable in low memory situations. When the daemon 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 EMS server attempts to reallocate its reserve memory once the number of pending messages in the server has dropped to 10% of the number of pending messages that were in the server when it experienced the allocation error. If the server successfully reallocates memory, it begins accepting new messages.
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.
 
There are a variety of limits that the user can set to prevent the EMS server from storing excessive messages, which can lead to situations where the EMS server runs out of memory. These include global parameters, such as max_msg_memory, as well as destination properties such as maxbytes. These limits should be used to prevent the reserve_memory mechanism from triggering.
msg_pool_block_size
msg_pool_size
msg_pool_block_size size
msg_pool_size size
 
To lessen the overhead costs associated with malloc and free, the server pre-allocates pools of storage for messages. These parameters determine 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 64K.
msg_pool_size instructs the server to allocate a fixed pool. After the server exhausts this pool, the server calls malloc each time it requires additional storage. The value may be in the range 16K to 1024M.
When neither parameter is present, the default is msg_pool_block_size 128 (an expandable pool). These two parameters represent two different and mutually exclusive modes for allocating storage pools. You may specify at most one of these two parameters; it is illegal to set both parameters explicitly.
Detecting Network Connection Failure Parameters
This feature lets servers and clients detect network connection failures quickly. When these parameters are absent, or this feature is disabled, tibemsd closes a connection only upon the operating system notification.
client_heartbeat_server
client_heartbeat_server interval
In a server-to-client connection, clients send heartbeats to the server at this interval (in seconds).
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.
server_timeout_client_connection
server_timeout_client_connection limit
In a server-to-client connection, if the server does not receive a heartbeat for a period exceeding this limit (in seconds), it closes the connection.
We recommend setting this value to approximately 3 times the heartbeat interval, as it is specified in client_heartbeat_server.
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.
Zero is a special value, which disables heartbeat detection in the server (although clients still send heartbeats).
server_heartbeat_server
server_heartbeat_server interval
In a server-to-server connection, this server sends heartbeats at this interval (in seconds).
The two servers can be connected either by a route, or as a fault-tolerant pair.
server_timeout_server_connection
server_timeout_server_connection limit
In a server-to-server connection, if this server does not receive a heartbeat for a period exceeding this limit (in seconds), it closes the connection. This parameter applies to connections from other routes and to the backup server connection.
We recommend setting this value to approximately 3.5 times the heartbeat interval of the other server. When the other server or the network are heavily loaded, or when client programs send very large messages, we recommend a larger multiple.
 
In a fault-tolerant configuration, the server_timeout_server_connection parameter has no effect on the backup server following a switchover. The backup server activates only after the timeout set by the ft_activation parameter.
server_heartbeat_client
server_heartbeat_client interval
In a server-to-client connection, the server sends heartbeats to all clients at this interval (in seconds).
When omitted or zero, the default is 5 seconds.
client_timeout_server_connection
client_timeout_server_connection limit
In a server-to-client connection, if a client does not receive a heartbeat for a period exceeding this limit (in seconds), it closes the connection.
We recommend setting this value to approximately 3.5 times the heartbeat interval.
Zero is a special value, which disables heartbeat detection in the client (although the server still sends heartbeats).
Fault Tolerance Parameters
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.
ft_active
ft_active = URL
Specifies the URL of the active server. If this server can connect to the active server, it will act as a backup server. If this server cannot connect to the active server, it will become the active server.
ft_heartbeat
ft_heartbeat = seconds
Specifies the interval (in seconds) the active server is to send a heartbeat signal to the backup server to indicate that it is still operating. Default is 3 seconds.
ft_activation
ft_activation = seconds
Activation interval (maximum length of time between heartbeat signals) which indicates that active server has failed. Set in seconds: default is 10. This interval should be set to at least twice the heartbeat interval.
For example:
ft_activation = 60
 
The ft_activation parameter is only used by the backup server after a fault-tolerant switchover. The active server uses the server_timeout_server_connection to detect a failed server.
ft_reconnect_timeout
ft_reconnect_timeout = seconds
The amount of time (in seconds) that a backup server waits for clients to reconnect (after it assumes the role of primary server in a failover situation). If a client does not reconnect within this time period, the server removes its state from the shared state files. The ft_reconnect_timeout time starts once the server has fully recovered the shared state, so this value does not account for the time it takes to recover the store files.
The default value of this parameter is 60.
ft_ssl_identity
ft_ssl_identity = pathname
The path to a file that contains the certificate in one of the supported formats. The supported formats are PEM, DER, or PKCS#12.
See File Names for Certificates and Keys for more information on file types for digital certificates.
ft_ssl_issuer
ft_ssl_issuer = chain_member
Certificate chain member for the server. Supply the entire chain, including the CA root certificate. The server reads the certificates in the chain in the order they are presented in this parameter.
The certificates must be in PEM, DER, PKCS#7, or PKCS#12 format.
See File Names for Certificates and Keys for more information on file types for digital certificates.
ft_ssl_private_key
ft_ssl_private_key = key
The server’s private key. If it is included in the digital certificate in ft_ssl_identity, then this parameter is not needed.
This parameter supports private keys in the following formats: PEM, DER, PKCS#12.
You can specify the actual key in this parameter, or you can specify a path to a file that contains the key. See File Names for Certificates and Keys for more information on file types for digital certificates.
ft_ssl_password
ft_ssl_password = password
Private key or password for private keys.
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.
ft_ssl_trusted
ft_ssl_trusted = trusted_certificates
List of trusted certificates. This sets which Certificate Authority certificates should be trusted as issuers of the client certificates.
The certificates must be in PEM, DER, or PKCS#7 format. You can either provide the actual certificates, or you can specify a path to a file containing the certificate chain.
See File Names for Certificates and Keys for more information on file types for digital certificates.
ft_ssl_rand_egd
ft_ssl_rand_egd = pathname
The path for the installed entropy gathering daemon (EGD), if one is installed. This daemon is used to generate random numbers for the EMS server.
ft_ssl_verify_host
ft_ssl_verify_host = enabled | disabled
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.
ft_ssl_verify_hostname
ft_ssl_verify_hostname = enabled | disabled
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.
ft_ssl_expected_hostname
ft_ssl_expected_hostname = serverName
Specifies the name the server is expected to have in the CN field of the fault-tolerant server’s certificate. If this parameter is not set, the expected name is the hostname of the server.
This parameter is used when the ft_ssl_verify_hostname parameter is set to enabled.
ft_ssl_ciphers
ft_ssl_ciphers = cipherSuite
Specifies the cipher suites used by the server; each suite in the list is separated by a colon (:). This parameter can use the OpenSSL name for cipher suites or the longer, more descriptive names.
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.
Message Tracking Parameters
track_message_ids
track_message_ids = enabled | disabled
Tracks messages by message ID. Default is disabled.
Enabling this parameter allows you to display messages using the show message messageID command in the administration tool.
track_correlation_ids
track_correlation_ids = enabled | disabled
Tracks messages by correlation ID. Disabled by default.
Enabling this parameter allows you to display messages using the show messages correlationID command in the administration tool.
Multicast Parameters
See Chapter 13, Using Multicast, for more information about multicast.
multicast
multicast = enabled | disabled
Enables or disables multicast in the EMS server. For example:
multicast = enabled
By default this feature is disabled.
multicast_channels
multicast_channels = file
Specifies the configuration file where multicast channels are defined.
For example:
multicast_channels = mychannels.conf
When this parameter is not included, the EMS server looks for channel definitions in the channels.conf file.
multicast_daemon_default
multicast_daemon_default = tcp-port
Specifies the TCP port on which the EMS client will attempt to connect to the multicast daemon. For example:
multicast_daemon_default = 9999
This parameter determines the TCP port that EMS clients use to connect to the multicast daemon, and is provided in the server to centrally configure all clients. It determines the behavior of the EMS client but does not affect the multicast daemon. The multicast daemon must listen for the client on the same port that the client uses to connect. If the multicast daemon is not listening on the same port that is specified by multicast_daemon_default, the client will be unable to connect to the daemon and an error will occur.
To change the TCP port that the multicast daemon listens on, use the -listen command line argument in the daemon. See Command Line Options for more information.
When this parameter is not included, the default port is 7444.
multicast_statistics_interval
multicast_statistics_interval = seconds
Specifies how often, in seconds, multicast statistics are published to the monitoring topic $sys.monitor.multicast.stats for each channel. Intervals of less than 5 seconds are not supported.
For example:
multicast_statistics_interval = 90
To disable multicast statistics, set the multicast_statistics_interval to 0 (zero).
When this parameter is not included, the default value is 0 (disabled).
TIBCO Rendezvous Parameters
See also, Chapter 15, Working With TIBCO Rendezvous.
tibrv_transports
tibrv_transports = enabled | disabled
Specifies whether TIBCO Rendezvous transports defined in transports.conf are enabled or disabled.
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.
tibrv_xml_import_as_string
tibrv_xml_import_as_string = enabled | disabled
When importing messages from Rendezvous, tibemsd translates XML fields to byte arrays. Releases earlier than 4.0 erroneously translated them to strings. If your client programs process XML as strings, then enable this parameter to revert to the earlier behavior (strings).
When absent, the default value is disabled (byte arrays).
(When importing from SmartSockets, XML fields translate to strings. This behavior is correct for SmartSockets, even though it differs from the correct behavior for Rendezvous.)
TIBCO SmartSockets Parameters
See also, Chapter 16, Working With TIBCO SmartSockets.
tibss_transports
tibss_transports = enabled | disabled
Specifies whether TIBCO SmartSockets transports defined in transports.conf are enabled or disabled.
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.
tibss_config_dir
tibss_config_dir = pathname
Specifies the directory for SmartSockets configuration files and message files:
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.
For more information about these files, see TIBCO SmartSockets User’s Guide.
Tracing and Log File Parameters
See Chapter 17, Monitoring Server Activity for more information about these parameters.
logfile
logfile = pathname
Name and location of the server log file.
log_trace
log_trace = traceOptions
Sets the trace preference on the file defined by the logfile parameter. If logfile is not set, the values have no effect.
The value of this parameter is a comma-separated list of trace options. For a list of trace options and their meanings, see Table 62, Server Tracing Options.
You may specify trace options in three forms:
plain  A trace option without a prefix character replaces any existing trace options.
+  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.
The following example sets the trace log to only show messages about access control violations.
log_trace=ACL
The next example sets the trace log to show all default trace messages, in addition to SSL messages, but ADMIN messages are not shown.
log_trace=DEFAULT,-ADMIN,+SSL
logfile_max_size
logfile_max_size = size [KB|MB|GB]
Specifies the recommended maximum log file size before the log file is rotated. Set to 0 to specify no limit. Use KB, MB, or GB for units (if no units are specified, the file size is assumed to be in bytes).
The server periodically checks the size of the current log file. If it is greater than the specified size, the file is copied to a backup and then emptied. The server then begins writing to the empty log file until it reaches the specified size again.
Backup log files are named sequentially and stored in the same directory as the current log.
console_trace
console_trace = traceOptions
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:
console_trace=-DEFAULT
Note that important error messages (and some other messages) are always output, overriding the trace settings.
This example sends a trace message to the console when a TIBCO Rendezvous advisory message arrives.
console_trace=RVADV
client_trace
client_trace = {enabled|disabled} [target=location]
               [user|connid|clientid=value]
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.
trace_client_host
trace_client_host = [hostname|address|both]
Trace statements related to connections can identify the host by its hostname, its IP address, or both. When absent, the default is hostname.
Statistic Gathering Parameters
See Chapter 17, Monitoring Server Activity for more information about these parameters.
server_rate_interval
server_rate_interval = seconds
Sets the interval (in seconds) over which overall server statistics are averaged. This parameter can be set to any positive integer greater than zero.
Overall server statistics are always gathered, so this parameter cannot be set to zero. By default, this parameter is set to 1.
Setting this parameter allows you to average message rates and message size over the specified interval.
statistics
statistics = enabled | disabled
Enables or disables statistic gathering for producers, consumers, destinations, and routes. By default this parameter is set to disabled.
Disabling statistic gathering resets the total statistics for each object to zero.
rate_interval
rate_interval = seconds
Sets the interval (in seconds) over which statistics for routes, destinations, producers, and consumers are averaged. By default, this parameter is set to 3 seconds. Setting this parameter to zero disables the average calculation.
detailed_statistics
detailed_statistics = NONE | [PRODUCERS,CONSUMERS,ROUTES,CHANNELS]
Specifies which objects should have detailed statistic tracking. Detailed statistic tracking is only appropriate for routes, channels, producers that specify no destination, or consumers that specify wildcard destinations. When detailed tracking is enabled, statistics for each destination are kept for the object.
Setting this parameter to NONE disabled detailed statistic tracking. You can specify any combination of PRODUCERS, CONSUMERS, ROUTES, or CHANNELS to enable tracking for each object. If you specify more than one type of detailed tracking, separate each item with a comma.
For example:
detailed_statistics = NONE
Turns off detailed statistic tracking.
detailed_statistics = PRODUCERS,ROUTES
Specifies detailed statistics should be gathered for producers and routes.
statistics_cleanup_interval
statistics_cleanup_interval = seconds
Specifies how long (in seconds) the server should keep detailed statistics if the destination has no activity. This is useful for controlling the amount of memory used by detailed statistic tracking. When the specified interval is reached, statistics for destinations with no activity are deleted.
max_stat_memory
max_stat_memory = size [KB|MB|GB]
Specifies the maximum amount of memory to use for detailed statistic gathering. If no units are specified, the amount is in bytes, otherwise you can specify the amount using KB, MB, or GB as the units.
Once the maximum memory limit is reached, the server stops collecting detailed statistics. If statistics are deleted and memory becomes available, the server resumes detailed statistic gathering.
SSL Server Parameters
See Chapter 18, Using the SSL Protocol for more information about these parameters.
ssl_dh_size
ssl_dh_size = [512 | 768 | 1024 | 2048]
Size of the Diffie-Hellman key. Can be 512, 768, 1024, or 2048 bits. The default value is 1024.
This key is not used for cipher suites available for export.
ssl_server_ciphers
ssl_server_ciphers = cipherSuites
Specifies the cipher suites used by the server; each suite in the list is separated by a colon (:). This parameter must follow the OpenSSL cipher string syntax.
For example, you can enable two cipher suites with the following setting:
ssl_server_ciphers = RC4-MD5:RC4-SHA
See Specifying Cipher Suites for more information about the cipher suites available in EMS and the syntax for specifying them in this parameter.
ssl_require_client_cert
ssl_require_client_cert = enable | disable
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.
ssl_use_cert_username
ssl_use_cert_username = enable | disable
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.
The CN field is either a username, an email address, or a web address.
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.
ssl_cert_user_specname
ssl_cert_user_specname = username
This parameter is useful if clients are required to supply a username, but you wish to designate a special username to use when the client’s username should be taken from the client’s digital certificate.
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.
The value specified by this parameter is the username that clients will use to log in when the username should be taken from their digital certificate. A good example of the value of this parameter would be anonymous.
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.
ssl_server_identity
ssl_server_identity = certificate
The server’s digital certificate in PEM, DER, or PKCS#12 format. You can specify the path to a file that contains the certificate in one of the supported formats.
This parameter must be specified if any SSL ports are listed in the listen parameter.
PEM and PKCS#12 formats allow the digital certificate to include the private key. If these formats are used and the private key is part of the digital certificate, then setting ssl_server_key is optional.
For example:
ssl_server_identity = certs/server.cert.pem
ssl_server_key
ssl_server_key = private_key
The server’s private key. If it is included in the digital certificate in ssl_server_identity, then this parameter is not needed.
This parameter supports private keys in the following formats: PEM, DER, PKCS#12.
You must specify a path to a file that contains the key.
ssl_password
ssl_password = password
Private key or password for private keys.
This password can optionally be specified on the command line when tibemsd is started.
If SSL is enabled, and the password is not specified with this parameter or on the command line, tibemsd will ask for the password upon startup.
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.
ssl_server_issuer
ssl_server_issuer = chain_member
Certificate chain member for the server. The server reads the certificates in the chain in the order they are presented in this parameter.
The same certificate can appear in multiple places in the certificate chain.
The certificates must be in PEM, DER, PKCS#7, or PKCS#12 format.
See File Names for Certificates and Keys for more information on file types for digital certificates.
ssl_server_trusted
ssl_server_trusted = certificates
List of CA root certificates the server trusts as issuers of client certificates.
Specify only CA root certificates. Do not include intermediate CA certificates.
The certificates must be in PEM, DER, or PKCS#7 format. You can either provide the actual certificates, or you can specify a path to a file containing the certificate chain.
For example:
ssl_server_trusted = certs\CA1_root.pem
ssl_server_trusted = certs\CA2_root.pem
See File Names for Certificates and Keys for more information on file types for digital certificates.
ssl_rand_egd
ssl_rand_egd = pathname
The path for the installed entropy gathering daemon (EGD), if one is installed. This daemon is used to generate random numbers for C clients and the EMS server. Java clients do not use this parameter.
ssl_crl_path
ssl_crl_path = pathname
A non-null value for this parameter activates the server’s certificate revocation list (CRL) feature.
The server reads CRL files from this directory. The directory should contain only CRL files. If other files are located in the pathname directory, SSL initialization will fail.
ssl_crl_update_interval
ssl_crl_update_interval = hours
The server automatically updates its CRLs at this interval (in hours).
When this parameter is absent, the default is 24 hours.
ssl_auth_only
ssl_auth_only = enable | disable
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.
fips140-2
fips140-2 = true | false
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.
LDAP Parameters
See Chapter 8, Authentication and Permissions for more information about these parameters.
ldap_url
URL of the external directory server. This can take the following forms:
LDAP://host:tcp_port
or
LDAPS://host:ssl_port
For example:
LDAP://myLdapServer:1855
ldap_principal
ldap_principal = DN
The distinguished name (DN) of the LDAP user that the EMS sever uses to bind to the LDAP server. This user must have privileges that allow it to bind and browse group users, but does not necessarily need to have administrative privileges.
For example:
ldap_principal = "cn=Manager"
ldap_credential
ldap_credential = password
The password associated with the user defined in the ldap_principal property. This value must be specified and cannot be an empty string.
ldap_cache_enabled
ldap_cache_enabled = enable | disable
Enables caching of LDAP data.
ldap_cache_ttl
ldap_cache_ttl = seconds
Specifies the maximum time (in seconds) that cached LDAP data is retained before it is refreshed.
ldap_conn_type
ldap_conn_type = [ldaps | startTLS]
Specifies the type of connection that the server uses to get LDAP information.
When this parameter is absent, LDAP connections use TCP (non-secure). For backward compatibility, this is the default setting.
ldaps—Use SSL on the LDAP connection (secure).
startTLS—Use the startTLS extension to the LDAP version 3 protocol (secure).
ldap_tls_cacert_file
ldap_tls_cacert_file = pathname
This file contains the CA certificate that the EMS server trusts to sign the LDAP server’s certificate.
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.
ldap_tls_cacert_dir
ldap_tls_cacert_dir = pathname
When there are two or more CA certificates in the verify chain, the server scans this directory for 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.
ldap_tls_cipher_suite
ldap_tls_cipher_suite = cipher_suite
Optional. You can specify the cipher suite to use for encryption on secure LDAP connections.
This parameter must follow the OpenSSL cipher string syntax; see Specifying Cipher Suites.
In addition to the actual cipher names, you may specify cipher quality; for example:
ldap_tls_rand_file
ldap_tls_rand_file = pathname
When the operating system does not include a random data feature, this file is the source of random data for encryption.
ldap_tls_cert_file
ldap_tls_cert_file = pathname
When the LDAP server requires client authentication, use the certificate in this file to identify the EMS server.
ldap_tls_key_file
ldap_tls_key_file = pathname
When the LDAP server requires client authentication, use the private key in this file.
When you plan to start the server remotely, we recommend that you do not password-encrypt the key file.
See Chapter 8, Authentication and Permissions for more information about these parameters.
ldap_user_class
ldap_user_class = class_name
Name of the LDAP object class that stores users.
For example:
ldap_user_class = person
ldap_user_attribute
ldap_user_attribute = attribute
Name of the attribute on the user object class that holds the name of the user.
For example:
ldap_user_attribute = uid
ldap_user_base_dn
ldap_user_base_dn = DN
Base distinguished name (DN) of the LDAP tree that contains the users.
For example:
ldap_user_base_dn = "ou=People,dc=Corp"
ldap_user_scope
ldap_user_scope = onelevel | subtree
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.
For example:
ldap_user_scope = subtree
ldap_user_filter
ldap_user_filter = filter
Optional LDAP search filter for finding a given user name. Use %s as the placeholder for the user name in the filter. For example:
uid=%s
The full LDAP search grammar is specified in RFC 2254 and RFC 2251.
If unspecified, then a default search filter is generated based on the user object class and user name attribute.
ldap_all_users_filter
ldap_all_users_filter = filter
An optional LDAP search filter for finding all users beneath the user base DN.
If not specified, then a default search filter is generated based on the user object class and user name attribute.
See Chapter 8, Authentication and Permissions for more information about these parameters.
ldap_group_base_dn
ldap_group_base_dn = DN
Base distinguished name (DN) of the LDAP tree that contains groups.
For example:
ldap_group_base_dn = "ou=Groups,dc=Corp"
ldap_group_scope
ldap_group_scope = onelevel | subtree
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.
For example:
ldap_group_scope = subtree
ldap_group_filter
ldap_group_filter = filter
Optional LDAP search filter for finding a group with a given group name. Use %s as the placeholder for the group name in the filter.
The full LDAP search grammar is specified in RFC 2254 and RFC 2251.
If unspecified, then a default search filter is generated based on the group object class and group attribute.
For example:
ldap_group_filter = "(|(&(cn=%s)(objectClass=groupofUniqueNames))(&(cn=%s)
(objectClass=groupOfURLs)))"
ldap_all_groups_filter
ldap_all_groups_filter = filter
Optional LDAP search filter for finding all groups beneath the group base DN.
If unspecified, then a default search filter is generated based on the group object class and group attribute.
ldap_static_group_class
ldap_static_group_class = name
Name of the LDAP object class that stores static groups.
For example:
ldap_static_group_class = groupofuniquenames
ldap_static_group_attribute
ldap_static_group_attribute = class
Name of the attribute on the static group object class that holds the name of the group.
For example:
ldap_static_group_attribute = cn
ldap_static_member_attribute
ldap_static_member_attribute = attribute
Attribute of an LDAP static group object that specifies the distinguished names (DNs) of the members of the group.
For example:
ldap_static_member_attribute = uniquemember
ldap_dynamic_group_class
ldap_dynamic_group_class = class
Name of the LDAP object class that stores dynamic groups.
For example:
ldap_dynamic_group_class = groupofURLs
ldap_dynamic_group_attribute
ldap_dynamic_group_attribute = attribute
Name of the attribute on the dynamic group object class that holds the name of the group.
For example:
ldap_dynamic_group_attribute = cn
ldap_dynamic_member_url_attribute
ldap_dynamic_member_url_attribute = attribute
Attribute of the dynamic LDAP group object that specifies the URLs of the members of the dynamic group.
For example:
ldap_dynamic_member_url_attribute = memberURL
Extensible Security Parameters
The extensible security feature allows you to write your own authentication and permissions modules for the server. For more information on this feature, see Chapter 9, Extensible Security.
jaas_classpath
jaas_classpath = classpath
Includes the JAR files and dependent classes used by the JAAS LoginModule. This parameter is required to enable the extensible security feature for authentication.
For example:
jaas_classpath = .:/usr/local/custom/user_jaas_plugin.jar
jaas_config_file
jaas_config_file = file-name
Specifies the location of the JAAS configuration file used by the EMS server to run a custom authentication LoginModule. For more information, see Loading the LoginModule in the EMS Server.
This parameter is required to enable the extensible security feature for authentication.
For example:
jaas_config_file = jaas.conf
jaas_login_timeout
jaas_login_timeout = milliseconds
Specifies the length of time, in milliseconds, that the EMS server will wait for the JAAS authentication module to execute and respond. This timeout is used each time the server passes a username and password to the LoginModule. If the module does not return a response, the server denies authentication.
This parameter is optional. If it is not included, the default timeout is 500 milliseconds.
For example:
jaas_login_timeout = 250
jaci_classpath
jaci_classpath = classpath
Includes the JAR files and dependent classes used by the JACI custom permissions module. This parameter is required to enable the extensible security feature for granting permissions.
For example:
jaci_classpath = .:/usr/local/custom/user_jaci_plugin.jar
jaci_class
jaci_class = class-name
Specifies the name of the class that implements the extensible permissions interface. The class must be written using the Java Access Control Interface (JACI). For more information about writing a custom application using JACI to grant permissions, see Writing a Permissions Module.
For example:
jaci_class = com.userco.auth.CustomAuthorizer
jaci_timeout
jaci_timeout = milliseconds
Specifies the length of time, in milliseconds, that the EMS server will wait for the JACI permissions module to execute and respond. This timeout is used each time the server passes a destination, username, and action to the permissions module. If the module does not return a response, the server denies authorization.
This parameter is optional. If it is not included, the default timeout is 500 milliseconds.
For example:
jaci_timeout = 250
JVM Parameters
These parameters enable and configure the Java virtual machine (JVM) in the EMS server. For more information on how JVM work in EMS, see Enabling the JVM.
jre_library
jre_library = path
Enables the JVM in the EMS server, where path is the absolute path to the jvm.dll shared library file that is installed with JRE. If this parameter is not included, the JVM is disabled by default.
If the path contains any spaces, the path must be enclosed in quotation marks.
For example:
jre_library = "C:\Program Files\Java\jdk1.6.0_04\jre\bin\server\jvm.dll"
jre_option
jre_option = JVMoption
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.
You can use multiple jre_option entries in order to pass more than one options to the JVM. Permitted values for JVMoption include most JVM options that are defined by Sun Microsystems.
For example, this restricts the maximum heap size of the JVM to 256 megabytes:
jre_option = -Xmx256m