Tibco EMS installation and setup

Installation & Basic Server Setup

Requirements & Preliminaries

Choose a host machine (Linux/Unix or Windows) with sufficient CPU, memory, disk.
Install Java (usually Java 8 or whatever version EMS supports).
Create an EMS installation directory (e.g. TIBCO_HOME/ems/<version>).
Make sure directory permissions, networking (ports) are open (firewall), etc.
Decide on the base port(s) you’ll use (default EMS listens on 7222 for non-SSL).

Installing / Unpacking

Unpack the EMS distribution (zip/tar).
Set environment variables (e.g. TIBCO_HOME, EMS_HOME, update PATH, etc.).
Copy sample configuration files (often there are sample queues.conf, topics.conf, routes.conf, factories.conf, users.conf, acl.conf, etc.).
You may have a “config / data / cfmgmt / logs” directory structure per EMS installation.

Basic Start / Stop

The EMS server executable is typically tibemsd
You can start it with a specific config file, e.g.:

cd $EMS_HOME/bin
./tibemsd –config path/to/tibemsd.conf

By default, EMS may look in its config directory for tibemsd.conf.
To stop, you can send shutdown via admin tool or kill the process.
On Windows, use the .exe version or as a Windows service, if configured.

2. Key Configuration Files & Server Parameters (`tibemsd.conf` and more)

The heart of EMS’s configuration lies in tibemsd.conf (plus companion files). TIBCO Docs

Important parameters in tibemsd.conf:

Parameter	Purpose / Notes
`listen`	The protocol(s) / ports that EMS listens on. For example `listen = tcp://7222` (non-SSL) or `ssl://7243` for SSL.
`authorization`	Enables or disables permission checking (ACLs). Use `enabled` to turn on authorization.
`routing`	Enable or disable routing functionality in this EMS instance.
SSL / TLS parameters	A set of parameters: `ssl_server_identity`, `ssl_server_key`, `ssl_password`, `ssl_server_trusted`, `ssl_server_issuer`, `ssl_auth_only`, etc.
Security / Authentication	E.g. `jaas_config_file`, `jaci_class`, `user_auth` (if using LDAP or local), etc.

You often also have these supporting configuration files:

queues.conf — default properties for queues
topics.conf — default properties for topics
routes.conf — definitions of inter-broker routes
factories.conf — JMS / connection factory definitions (types, URLs, SSL settings)
users.conf — list of EMS users and (encrypted) passwords
acl.conf — access control list — which users/groups have what permissions on which queue/topic

These define defaults or override behavior.

Important: many changes in tibemsd.conf require a restart of EMS to take effect (not all changes are dynamic).

3. Admin Tool & Connection / Basic Commands

EMS includes an administration tool called tibemsadmin (on Unix) / tibemsadmin.exe (Windows). This is how you issue commands interactively or via scripts.

Starting tibemsadmin

cd $EMS_HOME/bin
./tibemsadmin -server tcp://hostname:7222 -user admin -password <pwd>

If SSL is used:

./tibemsadmin -server ssl://hostname:7243 -user admin -password <pwd>

Once connected, you’ll see a prompt like:

tcp://hostname:7222>

Useful commands

Here’s a mapping of common admin commands (from blogs / docs).

Command	Description / Use
`show server`	Show overall server status, connections, stats, etc.
`show config`	Show configuration parameters
`whoami`	Show the current admin user identity
`set server authorization = enabled	disabled`
`create queue <qname> [prop1,prop2,…]`	Create a queue with optional properties
`create topic <tname> [prop1,prop2,…]`	Create a topic
`delete queue <qname>`	Delete a queue
`delete topic <tname>`	Delete a topic
`purge queue <qname>`	Remove all messages in that queue
`purge topic <tname>`	Purge all messages for topic / subscribers
`setprop queue <qname> <properties>`	Set (override) properties on queue
`addprop queue <qname> <prop1,prop2…>`	Add (append) properties to a queue
`setprop topic <tname> <properties>`	Set topic properties
`addprop topic <tname> <prop1,prop2…>`	Add properties to a topic
`grant queue <qname> user=<user> <permissions>`	Give user permissions on queue (send, receive, browse)
`grant queue <qname> group=<group> <permissions>`	Grant group permissions on queue
`revoke queue <qname> user=<user> <permissions>`	Revoke permissions on queue
`grant topic <tname> user=<user> <permissions>`	Grant topic permissions (subscribe, publish, durable, use_durable)
`revoke topic <tname> user=<user> <permissions>`	Revoke topic permissions
`create durable <topic> <durableName> [props]`	Define a durable subscriber statically
`show durable <durableName>`	Show details of durable subscriber
`grant admin user=<user> <admin_permissions>`	Give global admin rights to a user (view-all, change-acl, etc.)
`purge all queues	topics [pattern]`
`delete all queues	topics
`shutdown`	Instruct the EMS server to shut down gracefully
`disconnect` / `exit` / `quit` / `bye`	Exit the admin tool

There are also more advanced commands:

show queues / show topics to list all destinations
show routes to show defined routes / connections
show stat consumers|producers|route|topic|queue to show statistics
time on / time off to include timestamps in output

You can also run commands in script mode. For example, create a file emsStat.script with commands, and then run:

tibemsadmin –server tcp://localhost:7222 –script emsStat.script –user admin –password pass

This allows periodic or batch execution.

4. Users, Groups & Permissions (ACLs)

As an administrator, controlling access is critical. TIBCO EMS supports:

Users
Groups
Permissions (on destinations and admin-level)
Secure destinations (i.e. check ACLs)

Enabling Authorization

In tibemsd.conf, set:

authorization = enabled

This causes EMS to enforce ACLs on destinations and user authentication.

Or via admin tool: set server authorization = enabled
If authorization is disabled, all clients can connect and perform operations without restriction.

Creating Users & Groups

Via tibemsadmin:

create user user1 password=pass1
create group group1
add member group1 user1

You can create multiple users and groups.
Assign users to groups.
When authorization is enabled, clients must authenticate with user + password.

Also, there is a file users.conf that holds user definitions (user : [password] : description). The admin tool may update it or it may read from it.

For example, in SSL / secure mode, the users.conf must contain entries for users (including other EMS servers in routing) when authorization is on.

Access Control / ACLs

The acl.conf file (or via admin tool) defines which users / groups have which permissions on which destinations (queues / topics).
Destinations must often be marked as secure (i.e. addprop queue q1 secure) so that authorization is enforced on them.
Permissions differ for queues vs topics.

Queue permissions include:

send — allow sending messages to the queue
receive — allow consuming messages
browse — allow browsing queue (peek)
Destination admin-level permissions: view, create, modify, delete, purge

Topic permissions include:

publish — allow publishing to topic
subscribe — allow non-durable subscription
durable — allow creating durable subscription
use_durable — allow usage of an existing durable subscription
Destination admin-level permissions: view, create, modify, delete, purge

To grant:

grant queue myQueue user=user1 send,receive
grant topic myTopic group=group1 publish,subscribe
grant admin user=user2 all

To revoke:

revoke queue myQueue user=user1 receive
revoke topic myTopic user=user1 subscribe

Admin-level grants (via grant admin) allow giving broad control (e.g. ability to change ACLs, routes).
If the EMS server is configured with LDAP-based authentication, the user_auth setting (LOCAL, LDAP, LOCAL,LDAP, etc.) matters. Permissions may be applied even for non-existing LDAP users (they appear with an asterisk).

Example: setting up groups with queue-level permissions (from TIBCO KB)

set server authorization = enabled
create group developers
create group testers
create user dev1 password=dev1
create user dev2 password=dev2
create user tester1 password=tester1
create user tester2 password=tester2
add member developers dev1,dev2
add member testers tester1,tester2
create queue developers.>
create queue testers.>
addprop developers.> secure
addprop testers.> secure
grant queue developers.> group=developers create,send,receive
grant queue testers.> group=testers create,send,receive

This restricts dev users to developers.* queues only.

Changing ACLs / authorization dynamically: You can change ACLs via admin tool while EMS is running. But some changes (especially in users.conf) may require restart or reload.

5. Inter‑Broker Routing / Broker Networks

In real environments, you often have multiple EMS brokers (e.g. regional brokers) and want them to forward messages between each other — i.e. routing.

Concepts

Each EMS can act as a route server to forward messages to/from other EMS servers.
Destinations intended to be globally accessible must be marked global (e.g. addprop topic myTopic global) so routing forwards message.
In tibemsd.conf, routing must be enabled (routing = enabled).
You define route entries in routes.conf (or via admin tool).

Defining Routes

In routes.conf you define route entries like:

<route name="route1">
    local  = brokerA
    remote = brokerB
    <connection>
        url = tcp://brokerB:7222
        user = routeUser
        password = routePw
    </connection>
</route>

Or via admin tool:

create route route1 name=brokerB url=tcp://brokerB:7222 user=routeUser password=routePw

Then commit.

After route creation, you’ll see connections in show routes.

Message Routing Behavior & Issues

When sending to a global destination, messages are forwarded across the route network.
Routing for queues has constraints: the home queue must be on one EMS, and routing to other EMS uses queueName@homeBroker notation. For routing to work, the consumer on the remote EMS must be running for the message to be forwarded.
For topics, routing is more straightforward: durable subscribers get messages across the network; non-durable subscribers require the subscriber to be active to receive routed messages.
If messages are not routed, check:
1. Routing is enabled on both brokers.
2. The destinations have global property.
3. ACLs permit the route user to use the destination (if authorization is enabled).
4. The route is properly created and shows up under show routes.
5. Enable tracing (e.g. set server log_trace = +ROUTE +ROUTE_DEBUG) and destination trace (e.g. addprop queue q1 trace) to debug.

6. SSL / TLS / Secure Connections

Securing EMS communication is essential in production. EMS supports SSL / TLS (one-way, two-way). The configuration involves both server and client side (factories).

Server SSL Configuration (`tibemsd.conf`)

In your EMS server’s tibemsd.conf:

Modify listen to include SSL:

listen = tcp://7222, ssl://7243

Specify SSL identity (certificate, key, etc.):

ssl_server_identity = /path/to/server.cert.pem
ssl_server_key = /path/to/server.key.pem
ssl_password = <private_key_password>
ssl_server_issuer = /path/to/issuerCert.pem
ssl_server_trusted = /path/to/trustedCA.pem

Optionally require client certificates (for 2‑way SSL):

ssl_require_client_cert = true

If only for authentication mode:

ssl_auth_only = true

Restart EMS after changes.

Client / Factory Configuration (`factories.conf`)

In factories.conf, define connection factories that use SSL:

[SSLQueueConnectionFactory]
type = queue
url = ssl://hostname:7243
ssl_verify_host = disabled
ssl_trusted = /path/to/server_root.cert.pem
ssl_expected_hostname = serverName
ssl_identity = /path/to/client_identity.p12

[SSLTopicConnectionFactory]
type = topic
url = ssl://hostname:7243
...

ssl_trusted indicates the CA certificates the client trusts.
ssl_identity is for client certificate (if 2‑way SSL) — i.e. client identity.
ssl_verify_host can be enabled or disabled.
ssl_expected_hostname is what client expects as the server’s CN.

When the client connects via JNDI or direct, it uses that factory.

One‑Way SSL vs Two‑Way SSL

One‑way SSL: client verifies server certificate; server does not verify client certificate.
Two‑way SSL (mutual TLS): client presents its certificate; server verifies it (requires ssl_require_client_cert = true). Then server must trust client’s issuing CA via ssl_server_trusted.

Permissions & SSL

If authorization is enabled, ensure that the SSL / route user is included in users.conf and has appropriate ACL permissions on destinations.
For routing over SSL, route users must have credentials/certs trusted by both brokers.

Example (from docs)

In tibemsd.conf:

listen = ssl://7243
ssl_server_identity = server.cert.pem
ssl_server_key = server.key.pem
ssl_password = password
ssl_server_trusted = client_root.cert.pem
ssl_server_issuer = server_root.cert.pem
ssl_require_client_cert = true

In factories.conf:

[QueueConnectionFactory]
type = queue
url = ssl://7243
ssl_trusted = server_root.cert.pem
ssl_expected_hostname = server

[SSLQueueConnectionFactory]
type = queue
url = ssl://7243
ssl_verify_host = disabled
ssl_identity = client_identity.p12

In client connection (JMS / JNDI), set the ssl_identity, ssl_trusted, etc. as required.

7. Putting It Together: Sample Admin Workflow

Here’s a sample workflow an EMS administrator might follow when setting up a new EMS environment.

Install EMS, set up directories, copy sample configs.
Edit tibemsd.conf, enable authorization, set listen = tcp://7222.
Configure queues.conf, topics.conf with default properties (e.g. max depth, etc.).
Configure factories.conf for basic non-SSL factories (QueueConnectionFactory, TopicConnectionFactory).
Configure users.conf — create at least admin user.
Configure acl.conf (initial) — maybe allow admin full rights, open some default ACLs.
Start EMS (non-SSL).
Connect via tibemsadmin, verify via show server, show queues, show topics, show factories.
Create application users, groups, set ACLs for queues & topics.
Create required queues & topics, set secure property if they should be enforced on.
For scaling / distribution: configure routes.conf for inter-broker routing, enable routing in tibemsd.conf, set global property on destinations.
Set up SSL: generate server certificate + key, client certificates if needed, configure tibemsd.conf SSL parameters, configure factories for SSL, restart EMS.
Test clients connecting via SSL, validate that permissions and ACLs are correctly enforced.
Monitor via show stat … commands, show routes, check logs.

8. Tips, Caveats & Best Practices

Always backup configuration files before making major changes.
Use tracing / logging (e.g. log_trace = +CONNECT, +ROUTE, +ROUTE_DEBUG) when debugging routing or connection issues.
Use destination properties (e.g. secure, global, trace) wisely.
For high availability, plan for failover routing and redundant brokers.
When enabling SSL, check certificate validity, trust chains, CN / hostname mismatches.
When changing tibemsd.conf, many changes require restart — plan downtime.
Be careful when granting broad permissions (especially grant admin) — limit privilege.
Monitor message throughput, queue backlogs, consumer lag, etc. Use show stat … commands.
Regularly audit ACLs / users to remove stale ones.
When routing, ensure that ACLs allow the route user to access the global destinations. Otherwise routing will fail.