Using Other Configuration Files


In addition to the main configuration file, there are several other configuration files used for various purposes. They control configuration for the following:

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 8, Using the Administration Tool for more information about using the administration tool.

The following sections describe the configuration files.

users

This file defines all users. The format of the file is:

<username>:<password>:"<description>" 

Item
Description
<username>
The name of the user
<password>
Leave this item blank when creating a new user. This is assigned by the system when the user chooses a password. For example:
bob::"Bob Smith" 

There is one predefined user, the administrator. The administrator password is not entered in this configuration file, and it will not be assigned by the system. It will remain empty (and therefore not secure) until you set it using the administration tool; see , Assign a Password to the Administrator.

<description>
A string describing the user.

Example
admin: $1$urmKVgq78:"Administrator" 
Bob::"Bob Smith" 
Bill::"Bill Jones" 

groups

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> 

Item
Description
<group-name>
The name of the group.
<description>
A string describing the group.
<user-name>
One or more users that belong to the group.

Example
administrators: "TIBCO Enterprise Message Service administrators"     
   admin     
   Bob 

topics

This file defines all topics. The format of the file is:

<topic-name> <property1>, <property2>, ... 

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. 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.

queues

This file defines all queues. The format of the file is:

<queue-name> <property1>, <property2>, ... 

For example, you might enter:

test failsafe,secure,prefetch=2 

Only queues listed in this file or topics with names that match the topics listed in this file can be created by the applications. 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 (or topic) configuration file means that name-matching is not required for creation of queues (or topics).

acl

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> 

Item
Description
TOPIC
Name of the topic to which you wish to add permissions.
QUEUE

Name of the queue to which you wish to add permissions.

ADMIN
Specifies that you wish to add administrator permissions.
USER
Name of the user to whom you wish to add permissions.
GROUP
Name of the group to which you wish to add permissions. The designation all specifies a predefined group that contains all users.
PERM
Permissions to add.
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. 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

This file defines bridges between destinations. See Destination Bridges for more information about destination bridges.

The format of the file is:

[<destinationType>:<destination-name>] 
<destinationType>=<destinationToBridgeTo1> selector="<message-selector>" 
<destinationType>=<destinationToBridgeTo2> selector="<message-selector>" 
... 

The <destination-name> can be any specific destination or a wildcard pattern to match multiple destinations.

Item
Description
<destinationType>
The type of the destination. That is, topic or queue.
<destinationToBridgeTo>
One or more names of destinations to which to create a bridge.
selector
This property is optional and specifies a message selector to limit the messages received by the bridged destination.

For detailed information about message selector syntax, see documentation for the Message class in TIBCO Enterprise Message Service Java API Reference.

routes

This file defines routes between this TIBCO Enterprise Message Service server and other TIBCO Enterprise Message Service servers.

The format of the file is:

[<route-name>] 
url=<url-string> 
zone_name=<zone_name> 
zone_type=<zone_type> 
[<selector>]* 
[<ssl-prop = value>]* 

 

Item
Description
<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.
url
The URL of the server to and from which messages are routed.
zone_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.
For further information, see these sections:
zone_type
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.
<selector>
Topic selectors (for incoming_topic and outgoing_topic parameters) control the flow of topics along the route.
For syntax and semantics, see Selectors for Routing Topic Messages.
<ssl-prop>
SSL properties for this route.
For further information on SSL, refer to Chapter 12, Using the SSL Protocol.

Example
[test_route_2]  
url = tcp://server2:7222 
ssl_verify_host = disabled 

factories

This file defines the connection factories for the internal JNDI names.

The file consists of factory definitions with this format:

[<factory-name>] 
type = topic | queue 
url = <url-string> 
metric = connections | byte_rate 
clientID = <client-id> 
[<prop = value>]* 
[<ssl-prop = value>]* 

(Sheet 1 of 3)

Item
Description
type
Type of the ConnectionFactory. The value can be topic, queue, generic, xatopic, xaqueue, xageneric.
url
This string specifies the servers to which this factory creates connections:
  • A single URL specifies a unique server. For example:
  •      tcp://host1:8222 
    
  • A pair of URLs separated by a comma specifies a pair of fault-tolerant servers. For example:
  •      tcp://host1:8222,tcp://backup1:8222 
    
  • A set of URLs separated by vertical bars specifies a load balancing among those servers. For example:
  •      tcp://a:8222|tcp://b:8222|tcp://c:8222 
    
  • You can combine load balancing with fault tolerance. For example:
  •      tcp://a1:8222,tcp://a2:8222|tcp://b1:8222,tcp://b2
    :8222 
     

    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.

For cautionary information, see Load Balancing.
metric
The factory uses this metric to balance the load among a group of servers:
  • 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.

When this parameter is absent, the default metric is connections.

For cautionary information, see Load Balancing.
clientID
The factory associates this client ID string with the connections that it creates.
Properties

Connection factory properties override corresponding properties set using API calls.

connect_attempt_count
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.
connect_attempt_delay
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.
reconnect_attempt_count
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.
reconnect_attempt_delay
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.
<ssl-prop>
SSL properties for connections that this factory creates.
For further information on SSL, refer to Chapter 12, Using the SSL Protocol.

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 .

Load Balancing

Do not specify load balancing in situations with durable subscribers.
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.
Do not specify load balancing when your application requires strict message ordering.
Load balancing distributes the message load among multiple servers, which inherently violates strict ordering.

transports

This file defines transports for importing messages from or exporting messages to external message service:

tibrvcm

This file defines the TIBCO Rendezvous certified messaging (RVCM) listeners for use by topics that export messages to a tibrvcm transport. The server preregisters with 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 with 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> 

Item
Description
<transport>
The name of the transport for this RVCM listener.
If you are using the deprecated topic properties and configuration settings for communicating with TIBCO Rendezvous, then do not specify the transport name here. For more information about the deprecated method of exporting to RVCM, TIBCO Rendezvous Parameters—Deprecated, and Deprecated Properties.
<listenerName>
The name of the RVCM listener to which topic messages are to be exported.
<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 

durables

This file defines static durable subscribers.

The file consists of lines with either of these formats:

<topic-name> <durable-name> 
<topic-name> <durable-name> <properties> 

Item
Description
<topic-name>
The topic of the durable subscription.
<durable-name>
The name of the durable subscriber.
<properties>
A list of properties, separate by commas. Property names and values are described below.
Durable Subscriber Properties
route

When present, the subscriber is another server, and the <durable-name> is the name of that server.

When this property is present, no other properties are permitted.

clientid=<id>

The client ID of the subscriber’s connection.

nolocal

When present, the subscriber does not receive messages published from its own connection.

selector="<sel>"

When present, this selector narrows the set of messages that the durable subscriber receives.

Examples

topic1 dName1 
topic2 dName2 clientid=myId,nonlocal 
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:

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 tibemsadmin tool; see create durable .

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.


TIBCO Enterprise Message Service™ User’s Guide
Software Release 4.3, February 2006
Copyright © TIBCO Software Inc. All rights reserved
www.tibco.com