TIBCO Runtime Agent

Installation
Software Release 5.8.0
November 2012

Important Information
SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR
BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED
ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED
SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY
OTHER PURPOSE.
USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A
LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT,
OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT
WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS
DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR
CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE LICENSE FILE(S) OF
THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR
USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.
This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part
of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.
TIBCO, The Power of Now, TIBCO Adapter, TIBCO Administrator, TIBCO BusinessWorks, TIBCO ActiveMatrix
BusinessWorks, TIBCO Designer, TIBCO Enterprise Message Service, TIBCO Rendezvous, TIBCO Repository, and
TIBCO Runtime Agent are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or
other countries.
EJB, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in
the U.S. and other countries.
All other product and company names and marks mentioned in this document are the property of their respective owners and
are mentioned for identification purposes only.
THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL
OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME
TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC
OPERATING SYSTEM PLATFORM.
THIS DOCUMENT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES
ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED
IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR
CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.
THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR
INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT
NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.
This Product is covered by U.S. Patent No. 6,970,981.
Copyright 1999-2012 TIBCO Software Inc. ALL RIGHTS RESERVED.
TIBCO Software Inc. Confidential Information

| iii

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v
Changes from the Previous Release of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
TIBCO Runtime Agent Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Other TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Connecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Access TIBCO Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

xii
xii
xii
xii

Chapter 1 Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
64-bit Installation Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
TIBCO Universal Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Installing Versions with Higher Version Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Product Dependency Checking During Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Installation Modes and Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Installation Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Chapter 2 Installing TIBCO Runtime Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7

Installation Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Supported Vendor-supplied Database Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Installer Account . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Installing to a Networked Drive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Installing on GUI Mode on Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Installing on Windows 2003 and 2008 Terminal Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Installation Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Install Using GUI Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Install Using Console Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Install Using Silent Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Uninstalling TIBCO Runtime Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Post Installation Requirements on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

TIBCO Runtime Agent Installation

iv

| Contents
Chapter 3 Installed Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
TIBCO Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Java Runtime Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
TIBCO Hawk Agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Third-Party Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
TIBCO Domain Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
TIBCO Wrapper Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Obfuscate Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
ae2xsd Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
tramodify Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
traUpgradeManager Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
traDBConfig Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Other Client Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Repository Client Libraries and Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TIBCO Enterprise Message Service Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XML Related Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Persistent Object Framework Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TIBCO Crypto Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

37
37
37
37
37
37

Unicode Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Schema Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Hotfix Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Documentation Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Chapter 4 Installation FAQs and Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Running Out of Disk Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
DISPLAY Variable FAQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
TIBCO Administrator: Cannot View Installed Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

TIBCO Runtime Agent Installation

|v

Preface

This software may be available on multiple operating systems. However, not all
operating system platforms for a specific software version are released at the same
time. Please see the readme file for the availability of this software version on a
specific operating system platform.
This manual explains how to install TIBCO Runtime Agent.

Topics

Changes from the Previous Release of this Guide, page vi

Related Documentation, page vii

Typographical Conventions, page ix

Connecting with TIBCO Resources, page xii

TIBCO Runtime Agent Installation

vi

| Changes from the Previous Release of this Guide

Changes from the Previous Release of this Guide
This section itemizes the major changes from the previous release of this guide.
TIBCO Rendezvous
The TIBCO Rendezvous section is removed from Chapter 3, Installed Components as
TIBCO Rendezvous is installed separately.

TIBCO Runtime Agent Installation

Preface vii

Related Documentation
This section lists documentation resources you may find useful.

TIBCO Runtime Agent Documentation

The TIBCO Runtime Agent software suite is a prerequisite for other TIBCO software
products. In addition to Runtime Agent components, the software suite includes the
third-party libraries used by other TIBCO products, TIBCO Designer, Java Runtime
Environment (JRE), TIBCO Rendezvous, and TIBCO Hawk.
The following documents form the TIBCO Runtime Agent documentation set:

TIBCO Runtime Agent Installation Read this manual for instructions on site
preparation and installation.

TIBCO Runtime Agent Installing Into a Cluster Read this manual for instructions on
installing TIBCO applications into a cluster environment.

TIBCO Runtime Agent Upgrading to Release 5.8 Read this manual for instructions on
upgrading from release 5.x to release 5.8.

TIBCO Runtime Agent Domain Utility Users Guide Read this manual for instructions
on using TIBCO Domain Utility to create and manage administration domains.

TIBCO Runtime Agent Scripting Deployment Users Guide Read this manual for
instructions on using the AppManage scripting utility to deploy applications.

TIBCO Runtime Agent Authentication API User's Guide Read this manual for
instructions on using Authentication API.

TIBCO Runtime Agent Release Notes Read the release notes for a list of new and
changed features. This document also contains lists of known issues and closed issues
for this release.

Other TIBCO Product Documentation

You may find it useful to read the documentation for the following TIBCO products:

TIBCO Administrator : TIBCO Administrator allows you to manage users,

machines and applications defined in a TIBCO administration domain. The TIBCO
Administrator graphical user interface enables users to deploy, monitor, and start and
stop TIBCO applications.

TIBCO Designer: This graphical user interface is used for designing and creating
integration project configurations and building an Enterprise Archive (EAR) for the

TIBCO Runtime Agent Installation

viii

| Related Documentation
project. The EAR can then be used by TIBCO Administrator for deploying and
running the application.

TIBCO Hawk: This is a tool for monitoring and managing distributed applications and
operating systems.

TIBCO Rendezvous: Rendezvous enables programs running on many different kinds

of computers on a network to communicate seamlessly. It includes two main
components: the Rendezvous application programming interface (API) in several
languages, and the Rendezvous daemon.

TIBCO Enterprise Message Service: This software lets application programs send
and receive messages using the Java Message Service (JMS) protocol. It also
integrates with TIBCO Rendezvous and TIBCO SmartSockets messaging products.

TIBCO ActiveMatrix BusinessWorks: ActiveMatrix BusinessWorks is a scalable,

extensible, and easy to use integration platform that allows you to develop integration
projects. ActiveMatrix BusinessWorks includes a GUI for defining business processes
and an engine that executes the process.

TIBCO Adapter software: TIBCO Runtime Agent is a prerequisite for TIBCO

Adapter products. You will therefore find TIBCO Adapter product documentation
useful.

TIBCO Runtime Agent Installation

Preface ix

Typographical Conventions
The following typographical conventions are used in this manual.
Table 1 General Typographical Conventions
Convention

Use

ENV_NAME

TIBCO products are installed into an installation environment. A product installed into
an installation environment does not access components in other installation
environments. Incompatible products and multiple instances of the same product must be
installed into different installation environments.

TIBCO_HOME
TRA_HOME

An installation environment consists of the following properties:

Name Identifies the installation environment. This name is referenced in

documentation as ENV_NAME. On Microsoft Windows, the name is appended to the

name of Windows services created by the installer and is a component of the path to
the product shortcut in the Windows Start > All Programs menu.

Path The folder into which the product is installed. This folder is referenced in
documentation as TIBCO_HOME.

TIBCO TRA installs into a directory within TIBCO_HOME. This directory is referenced
in documentation as TRA_HOME. The default value of TRA_HOME depends on the
operating system. For example on Windows systems, the default value is C:\tibco\tra\5.8.
code font

Code font identifies commands, code examples, filenames, pathnames, and output
displayed in a command window. For example:
Use MyCommand to start the foo process.

bold code font

Bold code font is used in the following ways:

In procedures, to indicate what a user types. For example: Type admin.

In large code samples, to indicate the parts of the sample that are of particular
interest.

In command syntax, to indicate the default parameter for a command. For example,
if no parameter is specified, MyCommand is enabled:
MyCommand [enable | disable]

TIBCO Runtime Agent Installation

| Typographical Conventions
Table 1 General Typographical Conventions (Contd)
Convention

Use

italic font

Italic font is used in the following ways:

Key
combinations

To indicate a document title. For example: See TIBCO ActiveMatrix BusinessWorks

Concepts.

To introduce new terms For example: A portal page may contain several portlets.
Portlets are mini-applications that run in a portal.

To indicate a variable in a command or code syntax that you must replace. For
example: MyCommand PathName

Key name separated by a plus sign indicate keys pressed simultaneously. For example:
Ctrl+C.
Key names separated by a comma and space indicate keys pressed one after the other.
For example: Esc, Ctrl+Q.
The note icon indicates information that is of special interest or importance, for example,
an additional action required only in certain circumstances.
The tip icon indicates an idea that could be useful, for example, a way to apply the
information provided in the current section to achieve a specific result.
The warning icon indicates the potential for a damaging situation, for example, data loss
or corruption if certain steps are taken or not taken.

Table 2 Syntax Typographical Conventions

Convention

Use

[]

An optional item in a command or code syntax.

For example:
MyCommand [optional_parameter] required_parameter

A logical OR that separates multiple items of which only one may be chosen.
For example, you can select only one of the following parameters:
MyCommand para1 | param2 | param3

TIBCO Runtime Agent Installation

Preface xi

Table 2 Syntax Typographical Conventions

Convention

Use

{}

A logical group of items in a command. Other syntax notations may appear within each
logical group.
For example, the following command requires two parameters, which can be either the
pair param1 and param2, or the pair param3 and param4.
MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parameter can be
either param1 or param2 and the second can be either param3 or param4:
MyCommand {param1 | param2} {param3 | param4}

In the next example, the command can accept either two or three parameters. The first
parameter must be param1. You can optionally include param2 as the second parameter. And
the last parameter is either param3 or param4.
MyCommand param1 [param2] {param3 | param4}

TIBCO Runtime Agent Installation

xii

| Connecting with TIBCO Resources

Connecting with TIBCO Resources

How to Join TIBCOmmunity

TIBCOmmunity is an online destination for TIBCO customers, partners, and resident
experts. It is a place to share and access the collective experience of the TIBCO
community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To
register, go to http://www.tibcommunity.com.

How to Access TIBCO Documentation

You can access TIBCO documentation here:
http://docs.tibco.com

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, contact TIBCO
Support as follows:

For an overview of TIBCO Support, and information about getting started with
TIBCO Support, visit this site:
http://www.tibco.com/services/support

If you already have a valid maintenance or support contract, visit this site:
https://support.tibco.com
Entry to this site requires a user name and password. If you do not have a user name,
you can request one.

TIBCO Runtime Agent Installation

|1
Chapter 1

Installation Overview

This chapter provides an overview of the installer program.

Topics

Introduction, page 2

Installing Versions with Higher Version Numbers, page 4

Installation Modes and Disk Space, page 5

TIBCO Runtime Agent Installation

| Introduction
Introduction
The TIBCO Runtime Agent package provides the following products and product
components:

TIBCO Designer (designer/version folder) The GUI component used at design-time to

configure TIBCO Adapter instances, TIBCO ActiveMatrix BusinessWorks processes
and other TIBCO applications.

TIBCO Runtime Agent (tra/version folder) Runtime Agent includes TIBCO Domain
Utility and other TIBCO libraries and tools. The folder also includes the TIBCO
Wrapper utility, a number of repository management utilities, and more.

Third-party libraries (tpcl/version folder) Contains third-party libraries used by

TIBCO applications. For a complete list, see the version.txt file in the tra/version/ folder.

Java Runtime Environment (tibcojre/version folder)

TIBCO Rendezvous (tibrv/version folder) Complete installation of TIBCO

Rendezvous, as required by your installed TIBCO applications.

TIBCO Hawk (hawk/version folder) TIBCO Runtime Agent leverages TIBCO Hawk
to deploy, manage, and monitor applications.

If you decide to perform a custom installation, and choose not to install one or more
products or product components, you should review the list of required software that is
listed in the readme.txt file.

64-bit Installation Packages

Use one of the 64-bit installation packages if you want to utilize the advantages of the
64-bit JRE over the 32-bit JRE. After installation using a 64-bit installation package on a
machine, all administration servers, TIBCO Hawk agents, and applications on that
machine will run in 64-bit mode.
Note the following if you have an existing TIBCO Runtime Agent installation:

If you have an existing 32-bit TIBCO Runtime Agent installation, you can either use
the 32-bit installer or uninstall your existing installation completely before using the
64-bit installer. You can, however, configure your existing installation to run in 64-bit
mode by following the instructions provided by the documentation accompanying
your software release, then use the 64-bit installer.

If you have an existing 64-bit TIBCO Runtime Agent installation because you
installed your software version using a 64-bit installer provided for your platform,
then you must use the 64-bit installer.

TIBCO Runtime Agent Installation

|3

If you have manually configured your TIBCO Runtime Agent installation to run in
64-bit mode, then you must use the 64-bit installer.

If you have an existing 32-bit TIBCO Runtime Agent installation, using the 64-bit
installer will render the existing 32-bit installation non-operational. The same is true if
you have a 64-bit installation and use the 32-bit installer.

TIBCO Universal Installer

TIBCO Runtime Agent 5.8 is installed with the TIBCO UniversalInstaller.
The TIBCO Universal Installer supports multiple TIBCO_HOME directories on a system
and displays a panel asking whether to use a new or existing one. When using TIBCO
Runtime Agent and products that depend on it, you should always use the same
TIBCO_HOME directory. This is because, for backward compatibility, the old installation
registry (vpd.properties) is still utilized and will be shared by all TIBCO_HOMEs created
by the universal installer.

TIBCO Runtime Agent Installation

| Installing Versions with Higher Version Numbers

Installing Versions with Higher Version Numbers
TIBCO products use a three-digit release number which makes it possible to specify
major, minor, and service pack releases. For example, release 2.1.3 uses major version 2,
minor version1, and service pack 3.

If you are installing using a service pack release (for example, 5.6.1 over 5.6.0), the
installer will silently overwrite the existing version of the software. You do not need to
uninstall the existing installation. Simply stop all running TIBCO software before
installing.

If you are installing a major or minor release, the installer will create a new directory
in the old installation directory that is named after the two-digit release number. For
example, if your prior version was installed in c:\tibco\tra\5.7, and you install version
5.8, the product will be installed in c:\tibco\tra\5.8. The old installation is not
removed, and must be uninstalled separately if you wish to remove it.

If you install a product and that product is already installed on your machine, you cannot
choose a different location from that specified above. If you wish to install the product in a
different location, you must completely remove the product from the machine.

Product Dependency Checking During Installation

TIBCO Runtime Agent has dependencies on other TIBCO products. For example,
Runtime Agent depends on TIBCO Rendezvous and TIBCO Hawk. These product
dependencies are enforced and bound during installation. Install time binding is done by
substituting the values of various tags (such as %TIBCO_HAWK_HOME%, %TIBCO_RV_HOME%)
and updating properties in many properties files.
Since dependencies are enforced during installation, the installer can determine the
version and location of all dependent products through the installation registry. Version
and location information is then substituted in many properties files, typically *.tra files.
Moreover, many properties such as tibco.env.CUSTOM_PALETTE_PATH, tibco.env.CUSTOM_CP_EXT
and tibco.env.CUSTOM_PATH are also updated during installation. Enforcing dependency
checking allows out-of-the-box product functionality.

TIBCO Runtime Agent Installation

|5
Installation Modes and Disk Space
This section explains the installation modes and disk space requirements.

Installation Modes
Three installation modes are available: GUI, console, and silent. GUI mode provides a
typical installation experience for a GUI environment. Console mode can be used with a
command line environment when a GUI environment is not available. Silent mode is
suitable for scripted, non-interactive installation.
Installer Log File
The installer log file, tibco_universal_installer.timestamp.username_install.log, is written
to the .TIBCO/install_<timestamp> folder of the user's home directory. The installer log
file captures the following information:

Installation environment details such as user that invoked the installer, hostname, Java
home in the environment, operating system details, and so on.

List of assemblies installed.

Information related to the ANT scripts that are executed by the installer.

To change the location of the installer log file, specify the option -V logFile="myLogFile"
when you run the installer.
System Memory
A minimum of 2 GB of physical memory is recommended.

Disk Space
Disk Space Before Installation
The installer files may consume up to 500 MB of disk space depending on the operating
system platform being installed.
Temporary Disk Space Required by the Installer
The installer requires at least 150 MB of free space in the temporary directory. On
Microsoft Windows, the temporary directory location is %SystemDrive%:\Documents
and Settings\user_name\Local Settings\Temp.

TIBCO Runtime Agent Installation

| Installation Modes and Disk Space

The installer calculates the disk space required in product home location for the selected
components. The calculation is done before the actual installation (copying of files to
system) begins. The installer will proceed only if sufficient free disk space is available in
product home location.
However, if disk space is consumed by another process while the installer is copying the
files, and if the required disk space is thereby reduced, the installer may fail and will then
give a failure message.
While performing installation, avoid running other processes that consume disk space in
product home location.

TIBCO Runtime Agent Installation

|7
Chapter 2

Installing TIBCO Runtime Agent

This guide explains how to install TIBCO Runtime Agent on all supported platforms

Topics

Installation Prerequisites, page 8

Installation Options, page 10

Uninstalling TIBCO Runtime Agent, page 13

Post Installation Requirements on UNIX, page 14

TIBCO Runtime Agent Installation

| Installation Prerequisites
Installation Prerequisites
The following is a list of prerequisites for installing TIBCO Runtime Agent.

Supported Platforms
See the TIBCO Runtime Agent readme file for a list of supported platforms.

Supported Vendor-supplied Database Drivers

The following vendor-supplied database drivers are supported:

Oracle
Oracle Thin-driver
Oracle Thick-driver

When using an Oracle thick driver, an Oracle client must be installed on all Administrator
client machines.

Microsoft SQL Server

Microsoft JDBC driver

IBM DB2 Universal Database

See the TIBCO Runtime Agent readme file for versions of supported vendor-supplied
database drivers.

Installer Account
On Windows, to install this product, the account you use to log into the machine must
have administrator privileges.
On Unix, the product can be installed by a regular (non-root) user and super-user (root).
Different users can install the same product at different locations. You must have write
permission to the /tmp directory or the installer will throw output permission denied error
in the console.

Installing to a Networked Drive

If you intend to install the product onto a networked drive, you must have permissions to
write to that drive.

TIBCO Runtime Agent Installation

|9
If you do not know how to do this, go to the machine so you can install locally, or consult
Microsoft Windows online help.

Installing on GUI Mode on Unix

A GUI environment such as CDE (that is, X Windows) is required to run the installer in
GUI mode. It is not required for a console or silent installation.
See DISPLAY Variable FAQ on page 45 for information about installing on Unix systems.

Installing on Windows 2003 and 2008 Terminal Server

There are two modes in Windows Terminal Server: Execute and Install. Users are logged
on by default in Execute mode, which allows them to run applications. To install TIBCO
Runtime Agent so that everyone can use it, log on as administrator in Install mode. When
the adapter is installed in the Install mode, the installation registry is maintained in
SystemDrive:\WINDOWS.
Windows Terminal Server must be running in remote admin mode, not application sharing
mode. TIBCO Runtime Agent is not supported if installed on a machine that is using
Windows Terminal Server in application sharing mode.
The best way to install the TIBCO Runtime Agent on Windows Terminal Server is to use
the Add/Remove Programs control panel applet. This automatically sets your mode to
Install during the installation and then back to Execute afterwards. Alternatively, you can
manually change your mode to Install before starting the installation by typing the
following at a command prompt:
C:\> change user /install

Change back to Execute mode after installation is complete by typing:

C:\> change user /execute

To check your current mode, type the following:

C:\> change user /query

TIBCO Runtime Agent Installation

10

| Installation Options
Installation Options
TIBCO Installer can run in GUI, console, or silent modes. Each mode is supported on all
platforms.

GUI mode presents panels that allow you to make choices about product selection,
product location, and so on.

Console mode allows you to run the installer from the command line. This is useful if
your machine does not have a window environment or if you wish to install in silent
mode. Silent mode installs without prompting you for information.

Silent mode installs using values in .silent file. Silent mode installs in console mode
without prompting you for input.

TIBCO Rendezvous software (licensed for use with TIBCO Runtime Agent) can be
installed prior to TIBCO Runtime Agent installation or it can be installed in conjunction
with TIBCO Runtime Agent.

To install TIBCO Rendezvous before installing TIBCO Runtime Agent, follow the
installation instructions in the TIBCO Rendezvous Installation Guide. Then proceed
with the TIBCO Runtime Agent installation following the steps below, ignoring the
references to TIBCO Rendezvous since they will no longer be applicable.

To install TIBCO Rendezvous in conjunction with TIBCO Runtime Agent, perform

the following steps.
TIBCO Runtime Agent requires TIBCO Rendezvous 8.4.0 as the minimum
version.
TIBCO Rendezvous software need not be extracted (unzipped). It can be copied in
the location where the TIBCO Runtime Agent has been extracted. The installer
uses the TIBCO Rendezvous package for installing TIBCO Rendezvous without
the need to unpack the package contents.

When installing TIBCO Runtime Agent on UNIX platforms, you are prompted to provide
the location for the TIBCO installation home. The location you provide must not contain
the space character.
On Windows platforms, TRA_HOME can contain the space character.

Install Using GUI Mode

To install TIBCO Runtime Agent in GUI mode:
1. Open the physical media or download the package(s) you wish to install:

TIBCO Runtime Agent

TIBCO Runtime Agent Installation

| 11

TIBCO Rendezvous

2. Extract the package(s) to a temporary directory.

3. Navigate to the temporary directory.
4. Run TIBCOUniversalInstaller. The Welcome screen displays.
5. Click Next. The License Agreement screen appears. After reading through the license
text, click I accept the terms of the license agreement and then click Next.
6. The Installation Profile Selection screen displays. Click a profile on the left or check
the Customize Installation checkbox and check the checkboxes next to the features to
install on the right.
7. Click Next. The TIBCO Installation Home screen displays.

Create a new TIBCO_HOME To install the product into a new installation

environment, specify the following properties:

Name Identifies the installation environment. The name cannot contain special
characters such as "*", "?", ">", "<", ":", "|", "/", "\", or quotes (").
The name is appended to the name of Windows services created by the installer and
is a component of the path to the product in the Windows Start > All Programs
menu.
Path The directory into which the product is installed. Type a path or click Browse
to specify the path or accept the default location.
The path cannot contain special characters such as "*", "#", "?", ">", "<", "%", "&",
"$", "`" or "|". The path cannot be the same as the path of an existing environment.

Use an existing TIBCO_HOME To install the product into an existing installation

environment, select the environment from the Environment drop-down list.

Refer TIBCO Runtime Agent Release Notes for any known restrictions.
8. Click Next. The Pre-Install summary screen displays. Verify the list of products
selected for install and then click Install.
9. The Post-Install Summary screen appears. This screen summarizes the installation
process. Click Finish to complete the installation process and close the installer
window.

Install Using Console Mode

To install the software in console mode:
1. Open the physical media or download the package(s) you wish to install:

TIBCO Runtime Agent

TIBCO Runtime Agent Installation

12

| Installation Options

TIBCO Rendezvous

2. Extract the package(s) to a temporary directory.

3. Using a console window, navigate to the temporary directory.
4. Run TIBCOUniversalInstaller -console.
5. Complete the installation by responding to the console window prompts.

Install Using Silent Mode

In silent mode, the universal installer does not prompt for any inputs during installation.
Instead, the inputs are read from a response file that can be provided as a command-line
parameter. If no value is specified, the installer uses the default
TIBCOUniversalInstaller_TRA_version_number.silent file.
The TIBCOUniversalInstaller_TRA_version_number.silent file is packaged in the directory that
contains the universal installer. Edit the file with information for your environment before
launching the silent installation. The file includes comments that describe the installation
properties you can set. While you can use the TIBCOUniversalInstaller_TRA_version_number.silent
file, its good practice to copy the file to a different name and use that file for the silent
install.
The following procedure explains how to install a TIBCO Runtime Agent in silent mode.
If errors occur during installation, they will be listed in the installation log file contained in
User_Home/.TIBCO directory.
1. Open the physical media or download the package(s) you wish to install:

TIBCO Runtime Agent

TIBCO Rendezvous

2. Extract the package(s) to a temporary directory.

3. Using a console window, navigate to the temporary directory.
4. Make a copy of the TIBCOUniversalInstaller_TRA_version_number.silent file and rename the file.
5. Using a text editor, open the copied file and update the install location and features to
install.
6. Run the following:
Windows TIBCOUniversalInstaller.cmd -silent -V responseFile="myfilename.silent"
UNIX TIBCOUniversalInstaller.bin -silent -V responseFile="myfilename.silent"

TIBCO Runtime Agent Installation

| 13
Uninstalling TIBCO Runtime Agent
This section explains how to uninstall TIBCO Runtime Agent.
When you uninstall TIBCO Runtime Agent, only files that were created during
installation are uninstalled. Other files, such as files created as a result of a deployment are
not uninstalled.
To Uninstall TIBCO Runtime Agent:
1. Shut down all running TIBCO applications.
2. Navigate to TIBCO_HOME/tools/universal_installer and run TIBCOUniversalInstaller to
launch the InstallShield wizard.
3. Select the Uninstall Products From Selected TIBCO Home Location radio button.
4. Specify the TIBCO_HOME where TIBCO Runtime Agent is installed and click the
Next button.
5. The Welcome dialog appears. Click the Next button.
6. Choose the Custom Uninstall (Select The Products To Be Removed) radio button.
The wizard provides two uninstallation options:
Custom Uninstall You can select the products to be removed.
Typical Uninstall The universal uninstaller removes all the products in this
TIBCO_HOME.
7. Click the Next button. Check the checkboxes of the products to be uninstalled and
click the Next button.
8. Review the Pre-Uninstall Summary and click the Uninstall button to start the
uninstallation process.
9. Review the Post-Uninstall Summary and click the Finish button to exit the wizard.
Use the same way to uninstall TIBCO ActiveMatrix BusinessWorks 5.9. If
TIBCO_HOME\_uninstall\univeral_uninstall is used to uninstall TIBCO ActiveMatrix
BusinessWorks 5.9, TIBCO ActiveMatrix BusinessWorks 5.9 cannot be re-installed
successfully.

TIBCO Runtime Agent Installation

14

| Post Installation Requirements on UNIX

Post Installation Requirements on UNIX
This section describes the post installation requirements on UNIX.
Set Permissions for PGM Transport
After installing TIBCO Runtime Agent on an HPIA platform using PGM as the transport
protocol with either a 32-bit or 64-bit package, the PGM variant requires privileged access
to raw sockets on each daemon host computer. In some environments, raw access is
considered a security risk. If this privilege is not available, use the TRDP variant. To
determine whether this privilege is available in your environment, consult your local
system and network administrators.
Change TIBCO Hawk HMA Permissions
Modify the permissions of the TIBCO Hawk HMA (tibhawkhma) as shown:
cd $TIBCO_HAWK_HOME/bin/tibhawkhma
chown root tibhawkhma
chmod u+s tibhawkhma

On the AIX platforms, the tibhawkhma must be run as root and must not use setuid.
Link TIBCO Hawk HMA with TIBCO Rendezvous Library
On all supported platforms, the TIBCO Hawk HMA (tibhawkhma) is dynamically linked
with the TIBCO Rendezvous client libraries. This section describes the required
post-install steps.

HP-UX 11i PA-RISC 32-bit

Add TIBCO Rendezvous library path to the /etc/dld.sl.conf file.
The dld.sl.conf file contains trusted paths to search the libraries. If you have the
September 2005 Quality Pack patch bundle installed, specify a list of trusted paths in
/etc/dld.sl.conf. If a path in an environment variable is a trusted path, it will also be
searched for libraries.
No post-install steps are required for the HP-UX 64-bit platforms.

Linux x86 32-bit/64-bit

Update the /etc/ld.so.conf file and add $RVHOME/lib to the list. This must be the actual path
and not an $RVHOME variable.
Run ldconfig.

TIBCO Runtime Agent Installation

| 15

Solaris
Add the $RVHOME/lib directory to the trusted list using the crle command on the 32-bit
and 64-bit platforms.
The crle command allows you to create and display a runtime linking configuration
file.
Solaris 8-10 SPARC 32-bit/64-bit
Run "crle -u -s $RVHOME/lib" or "crle -u -s /path/to/directory -64"
Solaris 10 x86 32-bit/64-bit - The crle command can be used as follows:
crle -u -s <path to the $RVHOME/lib directory>

where:
-u specifies that the configuration file needs to be updated.
-s specifies the new trusted directory for the secure objects.
Post Installation Steps for HP-UX (IA-64/Itanium) 11.23
When using HP-UX (IA-64/Itanium) 11.23, complete the following steps:
1. Install the patch PHSS_38134.
2. Add TIBCO_HOME/tibrv/version_number/lib to the /etc/dld.sl.conf file.

TIBCO Runtime Agent Installation

16

| Post Installation Requirements on UNIX

TIBCO Runtime Agent Installation

| 17
Chapter 3

Installed Components

This chapter introduces the components installed with TIBCO Runtime Agent.

Topics

Overview, page 18

TIBCO Designer, page 19

Java Runtime Environment, page 21

TIBCO Hawk Agent, page 22

Third-Party Libraries, page 23

TIBCO Domain Utility, page 24

TIBCO Wrapper Utility, page 26

Obfuscate Utility, page 27

ae2xsd Utility, page 29

tramodify Utility, page 30

traUpgradeManager Utility, page 32

traDBConfig Utility, page 34

Other Client Libraries, page 37

Unicode Conversion, page 39

Schema Files, page 40

Hotfix Libraries, page 41

Documentation Locations, page 42

TIBCO Runtime Agent Installation

18

| Overview
Overview
TIBCO Runtime Agent runs on each machine on which TIBCO software is installed and
executes scripts, sends alerts, and performs recovery as specified. The TIBCO Runtime
Agent has two main functions:

Supplies an agent that is running in the background on each machine.

The agent is responsible for starting and stopping processes that run on a machine
according to deployment information.
The agent monitors the machine. That information is then visible via TIBCO
Administrator Enterprise Edition.

Supplies the run-time environment, that is, all shared libraries including third-party
libraries used by TIBCO products. The run-time environment includes the following:
TIBCO Designer (see page 19)
Java Runtime Environment (see page 21)
TIBCO Hawk agent (see page 22)
TIBCO Rendezvous
Third-party libraries (see page 23)
TIBCO runtime libraries

When you install a new version of TIBCO Runtime Agent, the installer creates a folder
named after the software version and places all TIBCO Runtime Agent folders and files
into that folder. This chapter describes the components, lists the files and folders that are
part of that component and gives additional comments as appropriate.

TIBCO Runtime Agent Installation

| 19
TIBCO Designer
TIBCO Runtime Agent includes the TIBCO Designer product, which allows you to
configure TIBCO products. Depending on the product you installed, you can, for example,
use TIBCO Designer to create TIBCO ActiveMatrix BusinessWorks process definitions or
create adapter configurations.
TIBCO Designer is an easy to use graphical user interface for creating integration
projects. TIBCO Designer allows you to drag and drop components into a project and then
specify configuration information for each component.
When you install TIBCO Designer, it includes the framework, and a small number of
palettes. Information is available as follows:
Table 3 TIBCO Designer Components
Component

Functionality and Documentation

Framework

TIBCO Designer GUI. Includes drag and drop instantiation,

customizable layout, and online help. Available palettes depend
on installed product(s).
TIBCO Designer Users Guide. Available via Help > Designer
Help online.

Adapter Resources
palette

The Generic Adapter configuration and associated Adapter

Resources palette allow developers of custom adapters to define
the adapter configuration to be associated with their Adapter
SDK-based adapter program.
If no custom palette exists for an adapter, and you open that
adapter from TIBCO Designer, the elements are represented as
resources inside a Generic Adapter Configuration.
TIBCO Designer Palette Reference discusses how to use the
resources in this palette.

Adapter Schema
palette

The AESchemas folder and associated Adapter Schemas folder

can be used to define schema for a custom adapter.
TIBCO Designer Palette Reference discusses how to use the
resources in this palette.

TIBCO Runtime Agent Installation

20

| TIBCO Designer
Table 3 TIBCO Designer Components
Component

Functionality and Documentation

Repository palette

By default, the Repository palette is not displayed because in

almost all cases, it is appropriate to edit project repositories by
editing the project directly. In some cases, for example, editing
custom properties, using the Repository palette is appropriate.
TIBCO Designer Palette Reference documents the Repository
palette.

TIBCO Runtime Agent Installation

| 21
Java Runtime Environment
TIBCO Runtime Agent bundles the Java Runtime Environment (JRE).
A JRE installer is embedded in the TIBCO Runtime Agent suite installer. TIBCO Runtime
Agent requires that the TIBCO installable JRE be installed. TIBCO Java applications will
use the JRE installed by TIBCO.
You can manually configure environment variables and configuration files to force use of
a different JRE.

TIBCO Runtime Agent Installation

22

| TIBCO Hawk Agent

TIBCO Hawk Agent
The TIBCO Runtime Agent installation includes a TIBCO Hawk agent. An Hawk agent is
an autonomous process that resides on each computer on which TIBCO Runtime Agent is
installed and monitors TIBCO applications on that computer.
The TIBCO Hawk agent operates autonomously and is active whenever the operating
system it monitors is active. The Hawk agent uses a set of rules, called rulebases, to
configure system management, status, and automation tasks. The Hawk agent monitors
conditions on its local machine and send alerts over the network only when problems are
detected.

TIBCO Runtime Agent Installation

| 23
Third-Party Libraries
A number of third-party libraries are included with the TIBCO Runtime Agent
installation. What exactly is installed depends on the machines operating system. The
license files for third-party software are listed in the license file.
A Third-Party Core Libraries (tpcl) installer is part of the TIBCO Runtime Agent suite
installer.
The tpcl folder does not contain jre, which is included in its own folder. See Java Runtime
Environment on page 21 for details.

TIBCO Runtime Agent Installation

24

| TIBCO Domain Utility

TIBCO Domain Utility
TIBCO Runtime Agent includes TIBCO Domain Utility that is used to manage the
components available in an administration domain.
TIBCO Domain Utility provides:

Machine Management
Add the machine on which TIBCO Domain Utility is running to an existing
administration domain.
Join a node that is part of a cluster to an administration domain.

Domain Configuration
Create a new administration domain for an existing TIBCO Administrator
installation.
Add a secondary server to an administration domain.
Delete an administration domain. The administration server and the TIBCO Hawk
agent for the administration domain must be shutdown before proceeding with this
task.
Enable and configure HTTPS for a selected administration domain on the machine
on which TIBCO Domain Utility is running.

Server Settings
Change TIBCO Rendezvous parameters used by TIBCO Administrator and
TIBCO Hawk for a selected administration domain on the machine on which
TIBCO Domain Utility is running.
Change the administration user name and password for a selected administration
domain.
Change LDAP configuration for a selected administration domain.
Change database configuration for a selected administration domain.

Migration
Upgrade a release 5.x administration domain to release 5.8.

TIBCO Runtime Agent Installation

| 25

TIBCO EMS Plug-in

Add a TIBCO Enterprise Message Service server to a selected administration
domain.
Remove a TIBCO Enterprise Message Service server from a selected
administration domain.
Update a TIBCO Enterprise Message Service server in a selected administration
domain.

Add a Servlet Engine Plug-in

Add or remove a servlet engine plug-in.

See the TIBCO Runtime Agent Domain Utility Users Guide for more information.

TIBCO Runtime Agent Installation

26

| TIBCO Wrapper Utility

TIBCO Wrapper Utility
The TIBCO Wrapper utility allows deployment of a TIBCO product or TIBCO Adapter
SDK based custom adapter as a service. Among other benefits, the wrapper allows the
operating system to start the application automatically upon reboot, regardless of the
operating system being used.

On Microsoft Windows systems, a wrapped application can be installed and run as a

Windows Service.

On UNIX systems, the functionality serves as a process abstraction. Hooks for TIBCO
Administrator mean that wrapped applications can be restarted on reboot under UNIX
and monitored using TIBCO Administrator.
When invoked, the Wrapper searches its current directory for the appname.tra file. If that
file is not found, it searches the PATH for appname.tra.
If a .tra file is not found in one of those locations, the Wrapper cannot start.

If you installed the TIBCO Runtime Agent package, TIBCO Wrapper will be transparent
to you. If you installed the TIBCO Adapter SDK package, you can use the TIBCO
Wrapper utility for both Java or C++ adapters. The utility uses standard Java properties
files for configuration of Service and Java Virtual Machine (JVM) parameters.
The Wrapper fails if it is not started from the bin directory. The error message is "Failed to
load shared library". The wrapper searches in the current directory for the appname.tra file. If
that's not found, it searches the PATH for appname.tra. You can explicitly specify the
location of the .tra using the --propFile argument for the wrapper.

TIBCO Runtime Agent Installation

| 27
Obfuscate Utility
The obfuscate utility allows you to encrypt confidential information such as passwords in
property files using an encryption key. The obfuscate utility rewrites a Java property file by
encrypting property values that start with a #!! or #! prefix. It supports three types of
encryption keys. They are as follows:

A custom encryption key. The encryption key is derived from a password provided by
you. To use it, add the prefix #!! to the data you want to encrypt and use -password or
-passwordFile command line parameters as appropriate. The password can contain any
keyboard characters and has no length limit. If encrypting sensitive date in the
deployment configuration file using your custom password, you need to provide the
same password when using -passwordFile (See -passwordFile Option on page 26 in
TIBCO Runtime Agent Scripting Deployment Users Guide).

A machine key. To use a machine key, add the prefix #!! to the data you want to
encrypt and do not use -password or -passwordFile.It can be used to encrypt a custom key in
a properties file. Then you can use -passwordFile to encrypt data using the encrypted key
in the properties file. If using a machine key, the data can not be decrypted on another
machine.

A fixed key. To use a fixed key, add the prefix #! to the data you want to encrypt. The
fixed key is compatible with earlier versions of TIBCO Runtime Agent but does not
provide the same level of security as the use of a machine key or a custom encryption
key. It is used to encrypt an administration domains password (See , Working with
Passwords, on page 10 in TIBCO Runtime Agent Scripting Deployment Users Guide).

Passwords encrypted using Obfuscate Utility cannot be decrypted. Ownership is with

customers to remember passwords in clear text. There is no utility provided by TIBCO to
decrypt passwords encrypted using Obfuscate Utility.
The obfuscate utility supports the following flags:

-password

(to prompt you to type in a password)

-passwordFile

(to read a encrypted password from a given file)

Example
To use -password, follow these steps:
1. In the property file, add the prefix #!! to the data you want to encrypt. For example:
Repo.serverCredential = #!!mysecret

2. Invoke the utility from the command line.

TIBCO_HOME/tra/version/bin/obfuscate.exe -password property_file_name

TIBCO Runtime Agent Installation

28

| Obfuscate Utility
3. Type in a password on the command line. For example:
Please type in encryption password* ****

To use -passwordFile, you need to specify the path to the file that contains an encrypted
password. That password is encrypted by a machine key. To do this, follow these steps:
1. Encrypt the password in a properties file using a machine key.
a. Add the prefix #!! to the custom password you want to encrypt in a property file.
For example:
Only.one.key = #!!passwords-can_be-long-and-have-signs()@#$%^-etc.123

You can use only one custom key for password encryption at a time.

b. Invoke the utility from the command line.

TIBCO_HOME/tra/version/bin/obfuscate.exe Encrypted_password_property_file_name

2. Use -passwordFile to encrypt the data using the encrypted password in the property file
from step 1.
a. In the property file, add the prefix #!! to the data you want to encrypt. For
example:
Repo.serverCredential = #!!mysecret

b. Invoke the utility from the command line.

TIBCO_HOME/tra/version/bin/obfuscate.exe property_file_name -passwordFile
Encrypted_password_property_file_name

TIBCO Runtime Agent Installation

| 29
ae2xsd Utility
The ae2xsd utility generates XSD schemas from a project metadata (TIBCO
ActiveEnterprise classes and operations). The utility can be used for canonical models, the
XML renderer in TIBCO IntegrationManager, as a source or target for XSLT mapping,
and to share with downstream consumers of ActiveEnterprise generated XML.
The input is a multi-file project saved in ActiveEnterprise XML format. You cannot use
this tool directly on a .dat file.
The syntax follows:
ae2xsd -project path-to-multi-file-project-root-folder
[ -output path-to-output-folder ]

Both paths can be absolute file paths, or relative to the current working directory.
The -output argument and path are optional. If omitted, a folder named AE2XSD-generated is
created in the current working directory.
The tool assumes that your PATH variable points to your Java SDK location and your
CLASSPATH points to the TIBCO Adapter SDK or TIBCO Runtime Agent .jar files.
The schemas are generated in a nested folder hierarchy that reflects their namespaces,
which in turn reflects the locations of the .aeschema files within the project. When type name
collisions occur, schema namespaces (and therefore output locations) will differ from the
original project structure.
The utility has the same functionality as the TIBCO Designer Tools Export AS XML Schemas
menu command.
Location
The utility is found in TIBCO_HOME/tra/version/bin.

TIBCO Runtime Agent Installation

30

| tramodify Utility
tramodify Utility
This utility is deprecated. Use the traUpgradeManager utility instead.

The tramodify utility is used to switch adapter dependency from one TIBCO Runtime Agent
version to another. The tool is also used to upgrade the references in a TIBCO products
template .tra files to use a new release. For example, the utility can be used to upgrade the
TIBCO BusinessWorks 5.5 template file to use TIBCO Runtime Agent release 5.8.
Consider a scenario where TIBCO Runtime Agent 5.7 and TIBCO Adapter for
ActiveDatabase 6.0 is installed. Then, TIBCO Runtime Agent 5.8 is installed and the
adapter is to run against the new version. The adapter dependency on TIBCO Runtime
Agent 5.7 can be changed to a dependency on TIBCO Runtime Agent 5.8 by running this
utility.
Syntax
> tramodify Product-Home n.n

Directory

Parameter

Description

Product Home

Home directory of TIBCO adapter for which TIBCO Runtime

Agent dependency need to be changed.

n.n

Two digit TIBCO Runtime Agent version number to which

adapter dependency needs to be changed.

Directory

The absolute location of the directory that contains set of

custom TIBCO Runtime Agent files to be modified.

Options
The following options can also be specified:
Parameter

Description

tramodify --usage

Displays tramodify online help.

tramodify --ladapters

Generates a text file under TIBCO_HOME/log that lists

the adapters installed on the machine, install location
and dependent TIBCO Runtime Agent version for each
adapter.

TIBCO Runtime Agent Installation

| 31
Examples
To migrate TIBCO Adapter for Siebel 6.0 from TIBCO Runtime Agent 5.7 to version 5.8:
> tramodify C:\tibco\adapter\adsbl\5.7 5.8

To migrate TIBCO Adapter for R/3 5.4 from TIBCO Runtime Agent 5.6 to version 5.8
and also to modify custom files (not installed by adapter package) located in the
C:\tibco\customfiles directory:
> tramodify C:\tibco\adapter\adr3\5.7 5.8 C:\tibco\customfiles

Location
The tramodify utility is found in TIBCO_HOME/tra/version/bin.

TIBCO Runtime Agent Installation

32

| traUpgradeManager Utility
traUpgradeManager Utility
The traUpgradeManager utility is used to

change the Rendezvous version that TIBCO Runtime Agent uses

change the versions that a deployed application or TIBCO product uses (for example,
updating TIBCO BusinessWorks 5.6 to use TIBCO Runtime Agent 5.8). This includes
updating references to TRA, JRE, and TPCL directories.

Do not use the traUpgradeManager utility to upgrade a domain. See TIBCO Runtime Agent
Upgrading to Release 5.8 for detailed instructions on upgrading a domain.
Also, make sure that you update the administration domain and the applications in the
domain to use the same Rendezvous version.
Syntax
>traUpgradeManager -path path -traversion tra_version -rv rv_version
>traUpgradeManager -path path -revert
>traUpgradeManager -help

Parameter

Description

-path

The path of a .tra file you wish to modify, or a directory that

includes multiple .tra files you wish to modify. Specify a
directory if you wish to change all .tra files in the directory.

-include

The location of a file containing one entry per line that each
act as <path>.

-exclude

The location of a file containing one name per line which will
be excluded from replacement. The name can match either a
directory or a file, which is not the path but just a simple name.

-traversion

TIBCO Runtime Agent version number.

-rv

The full path of the Rendezvous version to be used.

-jre

The location of a JRE to use. If not specified, the one that is

associated with target TRA will be used.

-hawk

The location of Hawk. If neither -hawk or -nohawk is specified,

the highest version of Hawk installed will be used.

-nohawk

Do not update the hawk home directory.

TIBCO Runtime Agent Installation

| 33
Parameter

Description

-keepRVDir

If not specified, any instances of RV_HOME/lib in the classpath

will be replaced with RV_HOME/lib/tibrvj.jar.

-revert

Revert the latest substitution by removing the tra file and

rename the backup file to it.

-help

Print this help information, but take no action.

Examples
To update the .tra files of an administration domain to use TIBCO Runtime Agent 5.8 and
Rendezvous 8.0 (which resides at C:\tibrv80 in this example):
> traUpgradeManager -path C:\tibco\tra\domain\sample_domain -traversion 5.8 -rv C:\tibrv80

To update the .tra files of TIBCO Adapter for Siebel 6.0 from TIBCO Runtime Agent 5.6
to version 5.8 and Rendezvous 8.3 (which resides at C:\tibrv80 in this example):
> traUpgradeManager -path C:\tibco\adapter\adsbl\6.0 -traversion 5.8 -rv C:\tibrv80

Location
The traUpgradeManager utility is found in TIBCO_HOME/tra/version/bin.

TIBCO Runtime Agent Installation

34

| traDBConfig Utility
traDBConfig Utility
The traDBConfig utility is used to configure a supported vendor-supplied database driver.
If you choose not to specify a vendor-supplied driver during installation, and later wish to
use it, you can use this utility to update your files quickly.
You must restart TIBCO Administrator and the TIBCO Hawk agent after using this utility
for the changes to be reflected. See TIBCO Runtime Agent Upgrading to Release 5.8 for
detailed instructions on changing to a vendor-supplied database driver for your existing
installations and domains, as well as issues and limitations associated with this utility.
Syntax
>traDBConfig -type dbtype -dbPath db_driver_path (-ociPath oci_client_path) [-product product|-path
directory|-filelist listfile]

Parameter

Description

-type

The choices are: SQLServer, DB2, OracleThin and OracleThick.

-dbPath

The path of the vendor-supplied driver. For example:

C:\oracle\product\10.1.0\db_1\jdbc\lib

Specify the directory of the Oracle thick client if you specify

OracleThick in -type.
-ociPath

The path of the Oracle OCI client directory. You must specify this
field if you specify OracleThick in -type.
On Windows, this is typically the ORACLE_CLIENT_HOME/BIN
directory. On Unix systems, this is typically the
ORACLE_CLIENT_HOME/lib or ORACLE_CLIENT_HOME/lib32
directory.
For example:
C:\oracle\product\10.2.0\client\BIN

-product

The product to configure: either tra for Runtime Agent or admin for
TIBCO Administrator.
If you use this parameter, the traDBConfig utility automatically
updates the application files for Runtime Agent or TIBCO
Administrator, respective, listed in Table 4 on page 35. However, it
does not update the domain files. To do so, use the -file option. See
Notes for more information.

TIBCO Runtime Agent Installation

| 35
Parameter

Description

-path

The path of a .tra file you wish to update, or a directory that

includes multiple .tra files you wish to update. Specify a directory
path if you wish to change a single .tra files in that directory.

-filelist

A text file that contains the lists of files to update. This file can
include any combination of the files listed in Table 4 on page 35.
Be sure to include all the files applicable to your installation,
including application files as well as domain files. See Notes for
more information.
This file should be in the following format:
FILES file1;file2;file3;...

Notes
In order for your installation of Runtime Agent or TIBCO Administrator and all your
domains to function properly after using this utility, you must ensure that the utility
updates all the files relevant to your installation.
If you have just installed Runtime Agent and TIBCO Administrator but have not added
the machine to a domain, you may simply use the -product tra parameter and -product admin
parameter to update the Runtime Agent and TIBCO Administrator files. After you update
both the Runtime Agent and TIBCO Administrator files, you can use the vendor-supplied
driver when creating new domains.
If you have installed both Runtime Agent and TIBCO Administrator, as well as created
domains, then you must also update all the .tra files for the existing Hawk agents and
administration servers. In this case, you can prepare a text file that contains a list of all the
files that need to be updated and use the -filelist parameter, or you can execute traDBConfig
with the -path parameter for each of the domain directories.
Table 4 Files for Update with traDBConfig Utility
Files
Runtime Agent Files
(Under
TIBCO_HOME/tra/versio
n)

template/domainutility/hawkagenttra.template
bin/domain_create.tra
bin/CorpUserSynchronizer.tra
bin/CorpRoleSynchronizer.tra
bin/AppManage.tra
bin/RedeployAllAppsForUser.tra
bin/MoveMachine.tra
bin/ImportDomainSecurity.tra
bin/Import2xSecurity.tra
bin/ExportDomainSecurity.tra
bin/domainutilitycmd.tra
bin/domainutility.tra

TIBCO Runtime Agent Installation

36

| traDBConfig Utility
Table 4 Files for Update with traDBConfig Utility
Files
Domain Hawk Agent
Files

TIBCO_HOME/tra/domain/domain/
hawkagent_domain.tra

TIBCO Administrator
Files

template/tibcoadmintra.template

(Under TIBCO_HOME/
administrator/

version)

Domain
Administration Server
Files

TIBCO Runtime Agent Installation

TIBCO_HOME/administrator/domain/domain/
tibcoadmin_domain.tra

| 37
Other Client Libraries
This section lists the various client libraries that are part of TIBCO Runtime Agent.

Repository Client Libraries and Utilities

The repository client libraries and utilities are included with the TIBCO Runtime Agent
installation. The repository client interacts with the TIBCO Administrator server. See the
TIBCO Administrator Server Configuration Guide for detailed information about the
command line utilities available.

TIBCO Enterprise Message Service Libraries

TIBCO Enterprise Message Service software allows you to send messages from your
applications according to the Java Messaging Service (JMS) protocol. A set of client
libraries are included that support the EMS plug-in, which allows you to configure a
TIBCO Enterprise Message Service server using TIBCO Administrator.

XML Related Libraries

A collection of XML-related libraries developed by TIBCO Software and used by TIBCO
ActiveMatrix BusinessWorks, TIBCO IntegrationManager, TIBCO Designer, and other
TIBCO applications that manipulate XML are included in TIBCO Runtime Agent.
Currently, these libraries do not expose a public API for use by customer applications.

Persistent Object Framework Libraries

The Persistent Object Framework (POF) libraries are used by TIBCO Administrator and
TIBCO Domain Utility to implement domain management. The APIs are not intended for
customer use.

TIBCO Crypto Library

The TIBCO Crypto library includes APIs used by TIBCO applications to encrypt data.
The APIs are not intended for customer use. They are included as TIBCrypt.jar.
The TIBCO Crypto library does not include encryption but provides an interface that
allows plugable support of third-party encryption libraries. The installation package
includes the following security vendors:

TIBCO Runtime Agent Installation

38

| Other Client Libraries

Entrust The default vendor. You can configure it to operate in FIPS 140-2 compliant

mode. We use version 7.2 of the Security Toolkit for Java.

IBM Also an FIPS 140-2 compliant vendor. This is only available for IBM systems.
When using it, you need to install the the Unlimited Strength Jurisdiction policy that is
from IBM.

Sun The Java cryptography extension provided by J2SE.

If you want to use the Entrust or IBM security vendor in FIPS 140-2 compliant mode, you
must add the following line in the .tra file for the application:
java.property.com.tibco.security.FIPS=true

For applications that require different cryptographic provider, follow these steps:
1. Make sure that the Java classpath includes the security vendors .jar files. For
example, to use the default Entrust provider, make sure that
TIBCO_HOME/tcpl/version/lib/entrust is in the classpath.
2. In the .tra file for the application, define a new property:
java.property.TIBCO_SECURITY_VENDOR=vendor

Where vendor can be entrust61, ibm, or j2se.

TIBCO Runtime Agent Installation

| 39
Unicode Conversion
If Unicode conversion to or from arbitrary encodings is required, a file containing a
lookup table is required. In that case, you must set the environment variable TIB_ICU_DATA
to point to the directory that contains the file tibicudata.dat, which contains the lookup table
used for conversion.
Location
The tibicudata.dat file is located in TIBCO_HOME/tra/version/config/g11n.

TIBCO Runtime Agent Installation

40

| Schema Files
Schema Files
TIBCO Runtime Agent includes schema files for verifying adapter configuration
information.
You can use the schema files to verify a configuration you prepared by editing an XML
file. Usually you use these schema before using RepositoryImport to convert the schema to
project format.
Location
The schema files are located in TIBCO_HOME/tra/version/schema.

TIBCO Runtime Agent Installation

| 41
Hotfix Libraries
A hotfix is a file or a collection of files that you can apply to TIBCO Runtime Agent to
correct a specific problem. Hotfixes are downloaded from the TIBCO Support site and
packaged in a tar or zip file. Instructions about installing the hotfix and the issues it
addresses are included in the download package.
Hotfixes are applied only to software that is already installed when you apply the hotfixes.
For example, if you remove TIBCO Runtime Agent and later reinstall it, you must also
reinstall any hotfixes that apply to that TIBCO Runtime Agent.
TIBCO Runtime Agent 5.x hotfix libraries, jars and other files are installed under the
hotfix folder. If you install a hotfix, you must ensure that the tra_home/hotfix/bin location is
specified before the tra_home/bin and tra_home/lib in your PATH, LIBPATH, SHLIB_PATH or
LD_LIBRARY_PATH, .tra file (if used) and so on. This allows your applications to use the
hotfix files.

TIBCO Runtime Agent Installation

42

| Documentation Locations
Documentation Locations
The following documentation is included with the TIBCO Runtime Agent installation.
Table 5 Documentation Locations
Component

Location

TIBCO Runtime Agent

TIBCO_HOME/tra/version/doc/tra

TIBCO Domain Utility

TIBCO_HOME/tra/version/doc/tra

TIBCO Designer

TIBCO_HOME/designer/version/doc

TIBCO Rendezvous

RV_HOME/doc or RV_HOME/version/doc

TIBCO Runtime Agent Installation

| 43
Chapter 4

Installation FAQs and Troubleshooting

This chapter lists answers to questions and potential issues.

Topics

Running Out of Disk Space, page 44

DISPLAY Variable FAQ, page 45

TIBCO Administrator: Cannot View Installed Software, page 46

TIBCO Runtime Agent Installation

44

| Running Out of Disk Space

Running Out of Disk Space
The installer calculates the disk space required in product home location, for the selected
components. The calculation is done before the actual installation (copying of files to
system) begins. The installer will proceed only if sufficient free disk space is available in
product home location.
However, if disk space is consumed by another process while the installer is copying the
files, and if the required disk space is thereby reduced, then the installer may fail, then the
installer may fail and will give a failure message.
Solution
While performing installation, avoid running other processes that consume disk space in
product home location.

TIBCO Runtime Agent Installation

| 45
DISPLAY Variable FAQ
Why and how should I set the DISPLAY variable on UNIX platforms for GUI mode?
The installer on UNIX, must open an additional window, generally for graphics. It uses the
DISPLAY environment variable to tell it on what computer to open the window. If the
environment variable is not set, the installer will either wait or abort after displaying:
InstallShield Wizard
Initializing InstallShield Wizard...
Preparing Java(tm) Virtual Machine...
...................................
...................................
........

The DISPLAY variable must be set to the IP address or name of the computer (on which
the installer graphics window are to be displayed), followed by a screen address, which
can be :0.0. For example:
# Bourne shell
DISPLAY=ip_address:0.0; export DISPLAY
# Korn shell
export DISPLAY=ip_address:0.0
# C-shell
setenv DISPLAY ip_address:0.0

For example, consider a scenario where you need to install the adapter on a remote
HP-UX machine (named itaska). Because you have a Solaris 5.6 machine (named alaska) that
has a video card and monitor installed, you can run an X-Window application on it. So you
decide to telnet to itaska from alaska.
When you telnet to itaska, you will not get access to itaska's monitor and will be unable to
display an X-Window application. That is why you must set the DISPLAY variable, which
instructs the X-Server to redirect all windows to the computer set in the variable. Before
doing so, the computer (specified in the DISPLAY variable) must give permissions to share
its monitor.
alaska xhost + # give permission for all to its share monitor
alaska telnet itaska
Welcome to HP-UX itaska 11.00
User:
Password:
itaska export DISPLAY=alaska:0.0 # set display on alaska
itaska ./TIB_tra-suite_version_h7_110.bin

TIBCO Runtime Agent Installation

46

| TIBCO Administrator: Cannot View Installed Software

TIBCO Administrator: Cannot View Installed Software
In TIBCO Administrator, you can view the installed TIBCO software in the Resource
Management > Installed Software dialog. If you cannot view the software for a machine
and an entry similar to the following exists in the TIBCO_HOME/tra/domain/domain/logs/tsm.log
file
2005 Sep 18 23:07:45:466 GMT -7 tsm Debug [] [TRA-000000] Thread TsmSyncInventory Waiting for a lock on a Vpd
file

delete the file with the extension .installerregistrylock in the TIBCO home directory.

TIBCO Runtime Agent Installation

| 47

Index

Numerics

64-bit Installation Packages 2

Installation
Options 10
Prerequisites 8, 8
installation home 10
Installer
Account 8
Installing
to a Networked Drive 8
Versions with Higher Version Numbers 4
Windows 2000 and 2003 Terminal Server 9

A
ae2xsd Utility 29

C
changes from the previous release vi
Client Libraries 37
Configuring Vendor Supplied Database Drivers 34
Custom Uninstall 14
customer support xii

J
Java Runtime Environment 21

O
D
Obfuscate Utility 27
DISPLAY Variable FAQ 45
Documentation Locations 42

P
F
FIPS 140-2 38

Persistent Object Framework Libraries 37

Post Installation Requirements 15
Prerequisites for TIBCO BusinessWorks 8

Hotfix Libraries 41

Repository Client Libraries and Utilities 37

Running Out of Disk Space 44
TIBCO Runtime Agent Installation

48

| Index
S
Schema Files 40
support, contacting xii

T
technical support xii
Third-Party Libraries 23
TIBCO BusinessWorks
Prerequisites 8
TIBCO Crypto Library 37
TIBCO Wrapper Utility 26
TIBCO_HOME ix
TRA_HOME ix, 10
tradbcconfig Utility 34
tramodify Utility 30
traUpgradeManager Utility 32
Typical Uninstal 14

U
Unicode Conversion 39
uninstalling the software 14
Uninstalling TIBCO Runtime Agent 14

V
Vendor-supplied Database Drivers 8

X
XML Related Libraries 37

TIBCO Runtime Agent Installation