Chapter 7 Using the Configuration Files : Using Other Configuration Files

Using Other Configuration Files
In addition to the main configuration file, there are several other configuration files used for various purposes:
See Page
Defines the multicast channels over which multicast messages are broadcast.
Defines the locations, either store files or a database, where the EMS server will store messages.
Defines the TIBCO Rendezvous certified messaging (RVCM) listeners for use by topics that export messages to a tibrvcm transport.
Defines transports used by EMS to import messages from or export messages to external message service, such as Rendezvous and SmartSockets.
These configuration files can be edited by hand, but you can also use the administration tool or the administration APIs to modify some of these files. See Chapter 6, Using the EMS Administration Tool for more information about using the administration tool.
The following sections describe the configuration files.
acl.conf
This file defines all permissions on topics and queues for all users and groups.
The format of the file is:
TOPIC=topic USER=user PERM=permissions
TOPIC=topic GROUP=group PERM=permissions
QUEUE=queue USER=user PERM=permissions
QUEUE=queue GROUP=group PERM=permissions
ADMIN USER=user PERM=permissions
ADMIN GROUP=group PERM=permissions
 
Name of the group to which you wish to add permissions. The designation all specifies a predefined group that contains all users.
The permissions which can be assigned to queues are send, receive and browse. The permissions which can be assigned to topics are publish, subscribe and durable and use_durable. The designation all specifies all possible permissions. For information about these permissions, refer to When Permissions Are Checked and Inheritance of Permissions.
Administration permissions are granted to users to perform administration activities. See Administrator Permissions for more information about administration permissions.
Example
ADMIN USER=sys-admins PERM=all
TOPIC=foo USER=user2 PERM=publish,subscribe
TOPIC=foo GROUP=group1 PERM=subscribe
bridges.conf
This file defines bridges between destinations. See Destination Bridges for more information about destination bridges.
The format of the file is:
[destinationType:destinationName] # mandatory -- include brackets
destinationType=destinationToBridgeTo1 [selector="msg-selector"]
destinationType=destinationToBridgeTo2 [selector="msg-selector"]
...
The destination-name can be any specific destination or a wildcard pattern to match multiple destinations.
 
This optional property specifies a message selector to limit the messages received by the bridged destination.
For detailed information about message selector syntax, see the ’Message Selectors’ section in description for the Message class in TIBCO Enterprise Message Service Java API Reference.
Example
[topic:myTopic1]
topic=myTopic2
queue=myQueue1
channels.conf
This file defines the multicast channels over which messages published to multicast-enabled topics are broadcast. Each channel defined in this file has a unique name, and can have a different multicast address, multicast port, and property values.
The format of the file is:
[multicast-channel-name]
  address = multicast-group-address:multicast-port
  [ttl = hops]
  [priority = priority]
  [maxrate = size [KB|MB|GB]]
  [maxtime = seconds]
  [interface = ip-address]
 
[multicast-channel-name]
[multicast-channel-name] is the name that identifies this multicast channel.
Note that the square brackets [ ] DO NOT indicate that the multicast-channel-name is an option; they must be included around the name.
multicast-group-address  is the multicast group IP address to which messages will be sent. The address must be between 224.0.0.0 and 239.255.255.255.
multicast-port  is the multicast port destination to which messages will be sent. The multicast port must be between 1 and 65535.
For example, this will cause messages sent over the channel to be directed to the IP address 234.5.6.7 and multicast port 99:
Specifies the maximum number of hops that messages can make between the server and the multicast daemon.
The number of hops between the server and multicast daemon is one plus the number of routers between them. For example, if the server and multicast daemon are in the same subnet, then there is one hop between them. If the server and multicast daemon are separated by a router, then there are two hops between them. Therefore, a ttl value of 1 means that the multicast data will remain on the local subnet while a ttl value of 2 will allow the messages to travel through one router into the next subnet.
Specifies the channel's transmission priority when bandwidth is allocated. priority is given as a numerical ranking, where the highest priority is -5 and the lowest is 5.
Specifies the maximum rate at which messages can be transmitted over the channel. You can specify units of KB or MB.
Specifies the maximum length of time, in seconds, that the server will retain sent messages for retransmission. Messages are retransmitted when a multicast daemon detects a lost message and sends a negative acknowledgement to the EMS server.
Note that a long maxtime will increase the amount of memory used by the server. The maximum amount of memory used by a channel will be maxrate * maxtime. For example, specifying a maxrate of 10MB and a maxtime of 10 seconds may require the server to buffer 100 megabytes of data for retransmissions.
Specifies the IP address over which the server will send multicast traffic on this channel.
The IP address must be a multicast capable interface. On UNIX systems, you can determine whether an IP interface is multicast capable by running the ifconfig UNIX command.
When this parameter is not included, the default value is 0.0.0.0, which causes the EMS server to use the system’s default interface.
Example
[channel-1]
  address=234.5.6.7:99
  maxrate=10MB
  maxtime=10
  ttl=4
 
[channel-2]
  address=234.5.3.9:99
  maxrate=15MB
  maxtime=10
  ttl=3
durables.conf
This file defines static durable subscribers.
The file consists of lines with either of these formats:
topic-name durable-name
  [route]
  [clientid=id]
  [nolocal]
  [selector="msg-selector"]
 
When present, the subscriber is another server, and the durable-name is the name of that server.
When present, the subscriber does not receive messages published from its own connection.
selector="string"
When present, this selector narrows the set of messages that the durable subscriber receives.
For detailed information about message selector syntax, see the ’Message Selectors’ section in description for the Message class in TIBCO Enterprise Message Service Java API Reference.
Example
topic1 dName1
topic2 dName2 clientid=myId,nolocal
topic3 dName3 selector="urgency in (’high’,’medium’)"
topic4 Paris route
Conflicting Specifications
When the server detects an conflict between durable subscribers, it maintains the earliest specification, and outputs a warning. Consider these examples:
A static durable subscription takes precedence over a client attempting to dynamically unsubscribe (from the same topic and durable name).
Conflict can also arise because of wildcards. For example, if a client dynamically creates a durable subscriber for topic foo.*, and an administrator later attempts to define a static durable for topic foo.1, then the server detects this conflict and warns the administrator.
Configuration
To configure durable subscriptions in this file, we recommend using the create durable command in the tibemsadmin tool; see create durable on page 117.
If the create durable command detects an existing dynamic durable subscription with the same topic and name, it promotes it to a static subscription, and writes a specification to the file durables.conf.
factories.conf
This file defines the connection factories for the internal JNDI names.
The file consists of factory definitions with this format:
[factory-name] # mandatory -- square brackets included
  type = generic|xageneric|topic|queue|xatopic|xaqueue|
  url = url-string
  metric = connections | byte_rate
  clientID = client-id
  [connect_attempt_count|connect_attempt_delay|
  connect_attempt_timeout|reconnect_attempt_count|
  reconnect_attempt_delay|reconnect_attempt_timeout = value]
  [ssl-prop = value]*
 
[factory-name]
[factory-name] is the name of the connection factory.
Note that the square brackets [ ] DO NOT indicate that the factory-name is optional; they must be included around the name.
generic: Generic connection (JMS 1.1)
xageneric: Generic XA connection (JMS 1.1)
topic: Topic connection (JMS 1.0.2b)
queue: Queue connection (JMS 1.0.2b)
xatopic: XA topic connection (JMS 1.0.2b)
xaqueue: XA queue connection (JMS 1.0.2b)
A set of URLs separated by vertical bars specifies a load balancing among those servers. For example:
The load balancing operator (|) takes precedence over the fault-tolerance operator (,). This example defines two servers (a and b), each of which has a fault-tolerant backup. The client program checks the load on the primary a server and the primary b server, and connects to the one that has the smaller load.
connections—Connect to the server with the fewest client connections.
byte_rate—Connect to the server with the lowest byte rate. Byte rate is a statistic that includes both inbound and outbound data.
The factory associates this client ID string with the connections that it creates. The client ID cannot exceed 255 characters in length.
A client program attempts to connect to its server (or in fault-tolerant configurations, it iterates through its URL list) until it establishes its first connection to an EMS server. This property determines the maximum number of iterations. When absent, the default is 2.
When attempting a first connection, the client sleeps for this interval (in milliseconds) between attempts to connect to its server (or in fault-tolerant configurations, iterations through its URL list). When absent, the default is 500 milliseconds.
When attempting to connect to the EMS server, you can set this connection timeout period to abort the connection attempt after a specified period of time (in milliseconds).
After losing its server connection, a client program configured with more than one server URL attempts to reconnect, iterating through its URL list until it re-establishes a connection with an EMS server. This property determines the maximum number of iterations. When absent, the default is 4.
When attempting to reconnect, the client sleeps for this interval (in milliseconds) between iterations through its URL list. When absent, the default is 500 milliseconds.
When attempting to reconnect to the EMS server, you can set this connection timeout period to abort the connection attempt after a specified period of time (in milliseconds).
Use the parameter to specify the TCP port that the client will use when establishing a connection to the multicast daemon.
This parameter 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. 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.
See Chapter 13, Using Multicast for information on multicast.
By default, a connection factory is always multicast-enabled if the EMS server to which it is connecting is enabled for multicast. If a client does not wish to receive messages over multicast from a multicast-enabled server, then this property can be set to disabled:
enabled—multicast is enabled in the factory.
disabled—multicast is disabled in the factory
See Chapter 13, Using Multicast for more information on multicast.
Example
[north_america]
  type = topic
  url = tcp://localhost:7222,tcp://server2:7222
  clientID = "Sample Client ID"
  ssl_verify_host = disabled
Configuration
To configure connection factories in this file, we recommend using the tibemsadmin tool; see create factory on page 117.
Load Balancing
 
If a client program that a creates durable subscriber connects to server A using a load-balanced connection factory, then server A creates and supports the durable subscription. If the client program exits and restarts, and this time connects to server B, then server B creates and supports a new durable subscription—however, pending messages on server A remain there until the client reconnects to server A.
groups.conf
This file defines all groups. The format of the file is:
group-name1:"description"
   user-name1
   user-name2
group-name2:"description"
   user-name1
   user-name2
 
The name of the group. The group name cannot exceed 127 characters in length.
Example
administrators: "TIBCO Enterprise Message Service administrators"
   admin
   Bob
jaas.conf
This file directs the TIBCO Enterprise Message Service server to the JAAS LoginModule. See Loading the LoginModule in the EMS Server for more information about the jaas.conf file.
queues.conf
This file defines all queues. The format of the file is:
[jndi-name1, jndi-name2, ...]queue-name property1, property2, ...
Note that, while including JNDI names is optional, the square brackets [ ] must be included around JNDI names if they are included. For more information about setting JNDI names, see create jndiname on page 118.
For example, you might enter:
test store=mystore,secure,prefetch=2
Only queues listed in this file or queues with names that match the queues listed in this file can be created by the applications (unless otherwise permitted by an entry in acl.conf). For example, if queue foo.* is listed in this file, queues foo.bar and foo.baz can be created by the application.
Properties of the queue are inherited by all static and dynamic queues with matching names. For example, if test.* has the property secure, then test.1 and test.foo are also secure. For information on properties that can be assigned to queues, see Destination Properties.
For further information on the inheritance of queue properties, refer to Wildcards * and > and Inheritance of Properties.
In the sample file, a > wildcard at the beginning of the file allows the applications to create valid queues with any name. A > at the beginning of the queue configuration file means that name-matching is not required for creation of queues.
Restrictions and rules on queue names are described in Destination Name Syntax.
routes.conf
This file defines routes between this TIBCO Enterprise Message Service server and other TIBCO Enterprise Message Service servers.
Routes may only be configured administratively, using the administration tool (see Chapter 6), or the administration APIs (see com.tibco.tibjms.admin.RouteInfo in the online documentation). Directly editing the routes.conf file causes errors.
The format of the file is:
[route-name] # mandatory -- square brackets included.
  url=url-string
  zone_name=zone_name
  zone_type=zone_type
  [selector]*
  [ssl-prop = value]*
 
[route-name]
[route-name] is the name of the passive server (at the other end of the route); it also becomes the name of the route. Note that the square brackets [ ] DO NOT indicate that the route-name is an option; they must be included around the name.
The route belongs to the routing zone with this name. When absent, the default value is default_mhop_zone (this default yields backward compatibility with configurations from releases earlier than 4.0).
You can set this parameter when creating a route, but you cannot subsequently change it.
The zone type is either 1hop or mhop. When omitted, the default value is mhop.
You can set this parameter when creating a route, but you cannot subsequently change it.
The EMS server will refuse to start up if the zone type in the routes.conf file does not match the zone type already created in the $sys.meta file that holds the shared state for the primary and backup server.
Topic selectors (for incoming_topic and outgoing_topic parameters) control the flow of topics along the route.
Example
[test_route_2]
url = tcp://server2:7222
ssl_verify_host = disabled
stores.conf
This file defines the locations, either store files or a database, where the EMS server will store messages or metadata (if the default $sys.meta definition is overridden). You can configure one or many stores in the stores.conf file.
Each store configured is either a file-based store or a database store. File-based store parameters are described here. Database store parameters are described in Chapter 10, Using Database Stores.
The format of the file is:
[store_name] # mandatory -- square brackets included
  type = file
  file = name
  [file_crc = true | false]
  [file_minimum = value]
  [file_truncate = value]
  [mode = async | sync]
 
[store_name]
[store_name] is the name that identifies this store file configuration.
Note that the square brackets [ ] DO NOT indicate that the store_name is an option; they must be included around the name.
Identifies the store as either a file-based store or a database store. The type can be:
file — for file-based stores.
dbstore — for database stores.
file=name
The filename that will be used when creating this store file. For example, mystore.db.
The location for this file can be specified using absolute or relative path names. If no path separators are present, the file will be saved in the location specified by the store parameter in the tibemsd.conf file, if any is specified there.
This parameter specifies whether the EMS server uses CRC to validate data integrity when reading the store files.
This parameter preallocates disk space for the store file. Preallocation occurs when the server first creates the store file.
You can specify units of MB or GB. Zero is a special value, which specifies no minimum preallocation. Otherwise, the value specified must be greater than 4MB.
If file_truncate is set to true, the file_minimum parameter prevents the EMS server from truncating the file below the set size.
When this parameter is absent, there is no default minimum preallocation.
Determines whether the EMS server will occasionally attempt to truncate the store file, relinquishing unused disk space.
When file_truncate is true, the store file may be truncated, but not below the size set in file_minimum.
When this parameter is absent, the default is true, and the server will periodically attempt to truncate the store file.
The mode determines whether messages will be written to the store file synchronously or asynchronously. Mode is either:
async — the server stores messages in this file using asynchronous I/O calls.
sync — the server stores messages in this file using synchronous I/O calls.
Example
[my_sync]
  type = file
  file = /var/local/dleshc/rundir/my_sync.db
  file_crc = true
  file_minimum = 10MB
  file_truncate = true
  mode = sync
tibrvcm.conf
This file defines the TIBCO Rendezvous certified messaging (RVCM) listeners for use by topics that export messages to a tibrvcm transport. The server preregisters these listeners when the server starts up so that all messages (including the first message published) sent by way of the tibrvcm transport are guaranteed. If the server does not preregister the RVCM listeners before exporting messages, the listeners are created when the first message is published, but the first message is not guaranteed.
The format of this file is
transport listenerName subjectName
 
The RVCM subject name that messages are published to. This should be the same name as the topic names that specify the export property.
Example
RVCM01 listener1 foo.bar
RVCM01 listener2 foo.bar.bar
topics.conf
This file defines all topics. The format of the file is:
[jndi-name1, jndi-name2, ...]topic-name property1, property2, ...
Note that, while including JNDI names is optional, the square brackets [ ] must be included around JNDI names if they are included. For more information about setting JNDI names, see create jndiname on page 118.
For example, you might enter:
business.inventory global, import="RV01,RV02", export="RV03", maxbytes=1MB
Only topics listed in this file or topics with names that match the topics listed in this file can be created by the applications (unless otherwise permitted by an entry in acl.conf). For example, if topic foo.* is listed in this file, topics foo.bar and foo.baz can be created by the application.
Properties of the topic are inherited by all static and dynamic topics with matching names. For example, if test.* has the property secure, then test.1 and test.foo are also secure. For information on properties that can be assigned to topics, see Destination Properties.
For further information on the inheritance of topic properties, refer to Wildcards * and > and Inheritance of Properties.
Restrictions and rules on topic names are described in Destination Name Syntax.
transports.conf
This file defines transports for importing messages from or exporting messages to external message services, such as TIBCO Rendezvous and TIBCO SmartSockets.
The format of the file is:
[transport_name] # mandatory -- square brackets included
   type = tibrv | tibrvcm | tibss # mandatory
   [topic_import_dm = TIBEMS_PERSISTENT |
                      TIBEMS_NON_PERSISTENT |
                      TIBEMS_RELIABLE]
   [queue_import_dm = TIBEMS_PERSISTENT |
                      TIBEMS_NON_PERSISTENT |
                      TIBEMS_RELIABLE]
   [export_headers = true | false]
   [export_properties = true | false]
   transport-specific-parameters
[transport_name]
The name of the transport. Note that the square brackets [ ] DO NOT indicate that the transport_name is an option; they must be included around the name.
tibrv identifies TIBCO Rendezvous transport
tibrvcm identifies TIBCO Rendezvous Certified Messaging transport
tibss identifies TIBCO SmartSockets transport
Each transport includes additional transport-specific-parameters:
EMS sending clients can set the JMSDeliveryMode header field for each message. However, Rendezvous clients cannot set this header. Instead, these two parameters determine the delivery modes for all topic messages and queue messages that tibemsd imports on this transport.
When absent, the default is TIBEMS_NON_PERSISTENT.
When true, tibemsd includes JMS header fields in exported messages.
When false, tibemsd suppresses JMS header fields in exported messages.
When true, tibemsd includes JMS properties in exported messages.
When false, tibemsd suppresses JMS properties in exported messages.
 
If you have multiple TIBCO Rendezvous transports configured in your transports.conf file, and if the EMS server fails to create a transport based on the last entry, the server will continue to traverse through the entries and attempt to create further transports.
Transport-specific Parameters
If type = tibrv, the extended syntax is:
   [service = service]
   [network = network]
   [daemon = daemon]
   [temp_destination_timeout = seconds]
   [rv_queue_policy = [TIBRVQUEUE_DISCARD_NONE |
                    TIBRVQUEUE_DISCARD_FIRST |
                    TIBRVQUEUE_DISCARD_LAST]:max_msgs:qty_discard]
See Rendezvous Parameters for descriptions.
If type = tibrvcm, the extended syntax is:
   rv_tport = name # mandatory
   [cm_name = name]
   [ledger_file = file-name]
   [sync_ledger = true | false]
   [request_old = true | false]
   [explicit_config_only = true | false]
   [default_ttl = seconds]
   [rv_queue_policy = [TIBRVQUEUE_DISCARD_NONE |
                    TIBRVQUEUE_DISCARD_FIRST |
                    TIBRVQUEUE_DISCARD_LAST]:max_msgs:qty_discard]
See Rendezvous Certified Messaging (RVCM) Parameters for descriptions.
If type = tibss, the extended syntax is:
   [username = name]
   [password = password]
   [server_names = single_or_list_of_servers]
   [project = name]
   [delivery_mode = best_effort | gmd_all | gmd_some | ordered]
   [lb_mode = none | round_robin | weighted | sorted]
   [override_lb_mode = enable | disable]
   [gmd_file_delete = enable | disable]
   [import_ss_headers = none | type_num | all]
   [preserve_gmd = always | receivers | never]
See SmartSockets Parameters for descriptions.
Example
[RV01]
   type = tibrv
   topic_import_dm = TIBEMS_RELIABLE
   queue_import_dm = TIBEMS_PERSISTENT
   service = 7780
   network = lan0
   daemon = tcp:host5:7885
[RVCM01]
   type = tibrvcm
   export_headers = true
   export_properties = true
   rv_tport = RV02
   cm_name = RVCMTrans1
   ledger_file = ledgerFile.store
   sync_ledger = true
   request_old = true
   default_ttl = 600
[SS01]
   type = tibss
   server_names = tcp:rtHost2A:5555, ssl:rtHost2B:5571
   username = emsServer6
   password = myPasswd
   project = mfg_process_control
   override_lb_mode = enable
   delivery_mode = gmd_some
[RV02]
   type = tibrv
   topic_import_dm = TIBEMS_PERSISTENT
   queue_import_dm = TIBEMS_PERSISTENT
   service = 7780
   network = lan0
   daemon = tcp:host5:7885
   rv_queue_policy = TIBRVQUEUE_DISCARD_LAST:10000:100
users.conf
This file defines all users. The format of the file is:
username:password:"description"
 
User passwords are not entered in this configuration file, and remain empty (and therefore not secure) until you set them using the administration tool; see Assign a Password to the Administrator. You can also create users and assign passwords using API calls; see the API reference for the language you are working with.
Example
admin::"Administrator"
Bob::"Bob Smith"
Bill::"Bill Jones"
After the server has started and passwords have been assigned, the file will look like this:
admin:$1$urmKVgq78:"Administrator"
Bob:$2$sldfkj;lsafd:"Bob Smith"
Bill:$3$tyavmwq92:"Bill Jones"