TIBCO ActiveMatrix Service Grid Installation and Configuration · The following documents form the TIBCO ActiveMatrix Service Grid documentation set: • Concepts: Read this manual

TIBCO ActiveMatrix® Service GridInstallation and ConfigurationSoftware Release 3.3.0September 2013

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDEDOR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITEDADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLEDSOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FORANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF ALICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT,OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENTWHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH ISDUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT ORCLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OFTHE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOURUSE 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 SoftwareInc.

TIBCO, Two-Second Advantage, TIBCO ActiveMatrix, and TIBCO Enterprise Message Service are either registeredtrademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

Enterprise Java Beans (EJB), Java Platform Enterprise Edition (Java EE), Java 2 Platform Enterprise Edition (J2EE),and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle Corporation in theU.S. and other countries.

All other product and company names and marks mentioned in this document are the property of their respectiveowners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALLOPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAMETIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFICOPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS ORIMPLIED, 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. CHANGESARE PERIODICALLYADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATEDIN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/ORCHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANYTIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY,BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITEDTO ANY RELEASE NOTES AND "READ ME" FILES.

Copyright (c) 2005-2013 TIBCO Software Inc. ALL RIGHTS RESERVED.

TIBCO Software Inc. Confidential Information

TIBCO ActiveMatrix Service Grid Installation and Configuration

Contents

Preface..................................................................................................7TIBCO Product Documentation................................................................................................8

Typographical Conventions......................................................................................................9

Connecting with TIBCO Resources........................................................................................12

Chapter 1 Setting Up an Enterprise...............................................13

Chapter 2 Installation Requirements and Pre-Installation Tasks.15Installation and Configuration Checklist.................................................................................16

Installation Requirements.......................................................................................................18

Installation Account Requirements..............................................................................18

Hardware Requirements..............................................................................................18

Software Requirements...............................................................................................19

Pre-installation Tasks..............................................................................................................22

Configuring External Databases..................................................................................22

Configuring Ant............................................................................................................24

Configuring Red Hat Linux 6 and AIX 6.1 32-bit Platforms.........................................24

Configuring AIX Platforms...........................................................................................25

Configuring the Environment Settings for AIX Platforms Versions 6.1 and Above......25

Configuring the Maximum Number of Open Files on Linux Platforms.........................26

Downloading Software Assemblies if No Internet Access is Available........................26

Chapter 3 Installation......................................................................27Preparing for Installation........................................................................................................28

Installing in GUI Mode............................................................................................................29

Installing in Console Mode.....................................................................................................31

Installing in Silent Mode.........................................................................................................32

Moving an Installation to a Destination Machine....................................................................33

Chapter 4 Post-Installation Tasks...................................................35Configuring Linux Platforms for TIBCO Business Studio.......................................................36

Prerequisites for Uninstalling .................................................................................................37

Chapter 5 Configuration..................................................................39Configuration Setup and Overview.........................................................................................40

Networking...................................................................................................................40


TOC | 5

TIBCO Configuration Tool Requirements....................................................................49

Running TIBCO Configuration Tool..............................................................................52

Using TIBCO Configuration Tool Scripts and Property Files.......................................56

Configuration Tool Wizards and Screens................................................................................62

Create Express Developer Environment.....................................................................62

Create TIBCO ActiveMatrix Administrator Server........................................................64

Create TIBCO Host Instance.......................................................................................84

Configure Third-Party Driver........................................................................................87

Replicate TIBCO ActiveMatrix Administrator Server...................................................88

Edit ActiveMatrix Administrator Server Configuration..................................................95

DDL Script Generator...........................................................................................................101

Overview of the DDL Script Generator Utility............................................................101

Creating the Database Schema................................................................................101

Cleaning up the Database Schema...........................................................................102

Database Models.......................................................................................................102

DDLGeneratorTask....................................................................................................103

Chapter 6 Upgrade.........................................................................105Upgrade Overview................................................................................................................106

Upgrade Impact.........................................................................................................107

Runtime Object State................................................................................................108

Determining a Runtime Object's Version...................................................................109

Supported Upgrade Scenarios..................................................................................109

Setting Permissions for Non-Admin Users During Upgrade......................................110

Performing an Upgrade........................................................................................................111

Upgrading an Enterprise with a Single Host Instance...............................................111

Upgrading an Enterprise with Multiple TIBCO Host Instances..................................111

Upgrading in a Replicated Setup with Multiple TIBCO Host Instances.....................112

Example Upgrade and Restore Scenarios...........................................................................113

Single TIBCO Host Instance Upgrade Example........................................................113

Single Host Instance Restore Example.....................................................................114

Multiple TIBCO Host Instance Upgrade Example......................................................115

Multiple Host Instance Restore Example...................................................................117

Upgrade Scripts....................................................................................................................118

Upgrade Script Targets..............................................................................................118

Upgrade Script Properties.........................................................................................120

Running the Upgrade Script......................................................................................121

Upgrading TIBCO Enterprise Message Service Server.......................................................123

Upgrading Runtime Objects.................................................................................................124

Chapter 7 Troubleshooting ..........................................................125


6 | TOC

Preface

TIBCO ActiveMatrix® Service Grid is a scalable and extensible platform for developing, deploying, andmanaging applications that conform to a service-oriented architecture.


TIBCO Product Documentation

This section lists documentation resources you may find useful.

The following documents form the TIBCO ActiveMatrix Service Grid documentation set:• Concepts: Read this manual before reading any other manual in the documentation set. This manual

describes terminology and concepts of the platform. The other manuals in the documentation set assumeyou are familiar with the information in this manual.

• Development Tutorials: Read this manual for a step-by-step introduction to the process of creating, packaging,and running composites in TIBCO Business Studio.

• Composite Development: Read this manual to learn how to develop and package composites.• Java Component Development: Read this manual to learn how to configure and implement Java components.• Mediation Component Development : Read this manual to learn how to configure and implement Mediation

components.• Mediation API Reference : Read this manual to learn how to develop custom Mediation tasks.• Spring Component Development : Read this manual to learn how to configure and implement Spring

components.• WebApp Component Development : Read this manual to learn how to configure and implement Web

Application components.• Administration Tutorial: Read this manual for a step-by-step introduction to the process of creating and

starting the runtime version of the product, starting TIBCO ActiveMatrix servers, and deployingapplications to the runtime.

• Administration: Read this manual to learn how to manage the runtime and deploy and manage applications.• Hawk ActiveMatrix Plug-in User’s Guide: Read this manual to learn about the Hawk plug-in and its optional

configurations.• Installation and Configuration: Read this manual to learn how to install and configure the software.• Release Notes: Read this manual for a list of new and changed features, steps for migrating from a previous

release, and lists of known issues and closed issues for the release.

The documentation for the following features is installed separately:• TIBCO ActiveMatrix Implementation Type for C++• TIBCO ActiveMatrix Binding Type for EJB• TIBCO ActiveMatrix Binding Type for Adapters• TIBCO ActiveMatrix Implementation Type for TIBCO Adapters• TIBCO ActiveMatrix Implementation Type for Microsoft CLR• TIBCO ActiveMatrix Binding Type for REST


8 | Preface

Typographical Conventions

Table 1: General Typographical Conventions

UseConvention

TIBCO products are installed into an installation environment. A product installed intoan installation environment does not access components in other installation environments.TIBCO_HOME

ENV_NAME Incompatible products and multiple instances of the same product must be installed intodifferent installation environments. An installation environment consists of the followingproperties:• Name - Identifies the installation environment. The name is appended to the name of

Windows services created by the installer and is a component of the path to the productshortcut in the Windows Start > All Programs menu. This name is referenced indocumentation as ENV_NAME .

• Path - The folder into which the product is installed. This folder is referenced indocumentation as TIBCO_HOME .

The folder that stores configuration data generated by TIBCO products. Configurationdata can include sample scripts, session data, configured binaries, logs, and so on. Thisfolder is referenced in documentation as CONFIG_HOME.

CONFIG_HOME

Code font identifies commands, code examples, filenames, pathnames, and outputdisplayed in a command window. For example:

code font

• Use MyCommand to start the foo process.• Code example:

public class HelloWorldImpl extends AbstractHelloWorldImpl {... public HelloResponseDocument sayHello(HelloRequestDocument firstName) { ... System.out.println("--> Generating Java Hello Component Response...");

String name = firstName.getHelloRequest()==null||firstName.getHelloRequest(). equals("")?"Friend":firstName.getHelloRequest(); HelloResponseDocument resp = HelloResponseDocument.Factory.newInstance(); resp.setHelloResponse("Hi " + name + "! " + "This is the Java component.\n");

System.out.println("--> Java Hello Component Response: \n\t\t" + resp.getHelloResponse()); ... }}

• CONFIG_HOME/admin/enterpriseName/samples/remote_props.properties

• Output example:C:\Program Files\tibco\amx-3\studio\3.6\eclipse>amx_eclipse_ant.exe -buildfile "C:/helloworld1/build.xml" -data "C:/hws"Buildfile: C:/helloworld1/build.xml

createApplicationDAA:[sds.createDAA] Waited for 47ms for workspace refreshes after building features.

all:BUILD SUCCESSFUL

BUILD SUCCESSFULTotal time: 2 minutes 18 seconds


Preface | 9

UseConvention

Bold code font is used in the following ways:bold code font

• 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]

Italic font is used in the following ways:italic font

• To indicate a document title. For example: See TIBCO BusinessWorks Concepts.• To define new terms. For example: A keystore is a database of keys and certificates.• 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.

Keycombinations

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 theinformation provided in the current section to achieve a specific result.

The warning icon indicates the potential for a damaging situation, for example, data lossor corruption if certain steps are taken or not taken.

Table 2: Syntax Typographical Conventions

UseConvention

An optional item in command 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 param1 | param2 | param3

A logical group of items in a command. Other syntax notations may appear within eachlogical group.

For example, the following command requires two parameters, which can be either thepair 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 beeither param1 or param2 and the second can be either param3 or param4:

MyCommand {param1 | param2} {param3 | param4}


10 | Preface

UseConvention

In the next example, the command can accept either two or three parameters. The firstparameter 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}


Preface | 11

Connecting with TIBCO Resources

How to Join TIBCOmmunity

TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts. It is a place toshare 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

After you join TIBCOmmunity, you can access the 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 username and password. If you do not have a username, you can request one.


12 | Preface

http://www.tibcommunity.com

http://docs.tibco.com

http://www.tibco.com/services/support

https://support.tibco.com

Chapter

1Setting Up an Enterprise

A TIBCO ActiveMatrix enterprise consists of an ActiveMatrix Administrator Server, one or more TIBCO Hosts,and one or more ActiveMatrix nodes either on a single machine or spread across multiple machines. This sectionexplains what you need to set up an enterprise on a single machine or on multiple machines.

Depending on the type of installation desired, you will need to meet the installation requirements and pre-requisitessummarized below:

A Trial, Demonstration, or Educational InstallationThis is the simplest configuration with minimal dependencies, a single user and on a single machine. You willneed:• An EMS server instance dedicated to the AMX installation.• To meet Installation Requirements given in the Installation Requirements section.• Install the product software on disk.• Run TIBCO Configuration Tool, choosing an "Express Configuration" to create ActiveMatrix Administrator

using the built-in HSQLDB database.• Start TIBCO BusinessStudio to develop AMX composite applications.• Use http://localhost:8120/amxadministrator to connect to AMX Administrator.

A Development, or Integration Test installation

This is a robust set up with multiple users, multiple developers on one or more machines. Typically you will havemultiple AMX developers using the TIBCO BusinessStudio developing applications locally, but deploying theirapplications for testing to a central AMX Administrator Server accessible to all the developers.

On the developer machines, you will need:• To meet Installation Requirements given in the Installation Requirements section.• Install the product software on disk, choosing "TIBCO BusinessStudio" and "Documentation" components.• Start TIBCO BusinessStudio and develop AMX composite applications.

On the ActiveMatrix Administrator machine, you will need:• An EMS server instance dedicated to the AMX installation.• A database server such as Oracle, Microsoft SQL Server, etc with some pre-requisites met.• To meet Installation Requirements given in the Installation Requirements section.• Install the product software on disk.• Run TIBCO Configuration Tool, choosing the following sequence of workflows:

– Configure Third-party Driver– Create ActiveMatrix Administrator Server– (optional) Create TIBCO Host instance– Connect to http://<admin-machine>:8120/amxadministrator, creating new user accounts as needed for each

developer.

Then on the TIBCO Business Studio, developers can register http://<admin-machine>:8120/amxadministrator asthe deployment server and directly deploy applications developed in Studio.


http://localhost:8120/amxadministrator



A Staging, Pre-Production, or Production Installation

This is a robust set up with multiple users, fault-tolerant ActiveMatrix Administrator, multiple TIBCO Hosts onone or more machines.


14 | Setting Up an Enterprise

Chapter

2Installation Requirements and Pre-Installation Tasks

Before you start installation, you must make sure your environment meets the installation requirements, and youmust perform pre-installation tasks.

You cannot install TIBCO Business Studio 3.3.0 on an earlier version of ActiveMatrix.

Topics

• Installation and Configuration Checklist• Installation Requirements• Pre-installation Tasks


Installation and Configuration ChecklistLists a set of tasks needed to install and configure the product.

Table 3: Checklist

StepsStages

Prerequisites 1. Installation Requirements on page 182. Hardware Requirements on page 183. Software Requirements on page 194. Configuring External Databases on page 22.5. Configuring Ant on page 24.6. Configuring Red Hat Linux 6 and AIX 6.1 32-bit Platforms on page 247. Configuring AIX Platforms on page 258. Configuring the Maximum Number of Open Files on Linux Platforms on

page 269. Downloading Software Assemblies if No Internet Access is Available on

page 26

Installation 1. Preparing for Installation on page 282. Choose one of the following ways of installing the product:

a. Installing in GUI Mode on page 29b. Installing in Console Mode on page 31c. Installing in Silent Mode on page 32

Post-installation 1. After installation, ensure that Enterprise Messaging Service is up andrunning before starting TIBCO Configuration Tool. For details, see:a. TIBCO Configuration Tool Requirements on page 49b. Enterprise Messaging Server Requirements on page 50c. SSL Requirements on page 50

2. If you have TIBCO Business Studio installed on Linux platforms, seeConfiguring Linux Platforms for TIBCO Business Studio on page 36.

The configuration steps vary based on your needs.Configuration

1. If you are using external databases, configure the third party driver byfollowing the steps in Configure Third-Party Driver on page 87.

2. Before this step, make sure that the EMS server is up and running. Thereare two ways of creating the TIBCO ActiveMatrix Administrator Server:a. If you want to select the default settings, follow the steps in Create

Express Developer Environment on page 62.b. Before this step, ensure that you have configured the external database

and configured the third-party driver. To to customize the port,environment, and database settings, follow the steps in Create TIBCOActiveMatrix Administrator Server on page 64.

3. If you have ActiveMatrix Administrator on one machine and the TIBCOHost on another machine, and they share the same EMS server, followthe steps in Create TIBCO Host Instance on page 84.


16 | Installation Requirements and Pre-Installation Tasks

StepsStages

4. For high availability, it is a best practice to replicate ActiveMatrixAdministrator. See Replicate TIBCO ActiveMatrix Administrator Serveron page 88.


Installation Requirements and Pre-Installation Tasks | 17

Installation RequirementsBefore you can run the installer on your Windows or Linux system, you must log in as a user with appropriatepermissions, and your system must meet the hardware and software requirements.

If you plan on installing in an existing installation environment, stop all processes that are using Java fromTIBCO_HOME.

At the end of installation, the installer launches TIBCO Configuration Tool. You can use the tool to createruntime objects such as an Administration server and perform other configuration tasks. Your environmentmust meet additional requirements to run the tool.

See Configuration Setup and Overview on page 40 and Configuration Tool Wizards and Screens on page62.

Installation Account RequirementsTo install on Microsoft Windows or on UNIX, you must have the appropriate privileges.

The privileges differ for different platforms.

• Microsoft Windows - Only users with administrator privileges can install the TIBCO ActiveMatrixproducts. If you do not have administrator privileges, the installer exits. To install the product on a networkdrive, ensure that the account used for installation has the permission to access the network drive.

On UAT enabled Windows platforms, non-default administrators may encounter permission issuesin certain circumstances. To avoid permission issues, start TIBCO Universal Installer, TIBCOConfiguration Tool, and Command Prompt with the Run as Administrator option.

• UNIX - Any type of user—regular (non-root) user and super-user (root)—can install the product. Use thesame installer account to install all the TIBCO ActiveMatrix products. A graphic environment such asCDE or X Windows is required to run the installer in the GUI mode.

For configuration, the user who runs TIBCO Configuration Tool must also have administrator privilegeson the TIBCO Enterprise Message Service servers that you want to use in your TIBCO ActiveMatrixenterprise. If you do not have administrator privileges, you can configure using additional setup. SeeConfiguring TIBCO Enterprise Message Service Servers for Non-Admin Users on page 50.

Hardware RequirementsInstallation requires a substantial amount of system memory and disk space.

Review the system memory and disk space requirements before you start installation.

System Memory

A minimum of 2 GB of physical memory is required.

Disk Space

The installer requires space in the temporary directory before installation, and additional space in the temporarydirectory for running the installer. You must also make that the directory you want to use as the installationenvironment (TIBCO_HOME) directory has sufficient space.

While installating, avoid running other processes that consume disk space in the installationenvironment directory. If another process consumes disk space while the installer is copying the files,the installer might fail and display a failure message.



Disk Space RequirementDirectory

Before you start the installation process, extract the contents of the installationarchive to a temporary directory. The installer files consume up to 990 MBof disk space.

Temporary directory beforeinstallation

The installer requires at least 70 MB of free space in the temporary directory.On Microsoft Windows, the default temporary directory location is

Temporary directory duringinstallation

%SystemDrive%:\Documents and Settings\user_name\LocalSettings\Temp.

If your system does not have sufficient free disk space in the defaulttemporary directory, you can use the is:tempdir option to run the installerwith a different temporary directory. For example:

TIBCOUniversalInstallerPlatform -is:tempdir \new_tmp

where \new_tmp has sufficient free disk space.

The installer calculates the disk space required in the installation environmentdirectory for the selected components. The calculation is done before the

Installation environmentdirectory

actual installation (copying of files to system) begins. The installer proceedsonly if sufficient free disk space is available in the installation environmentdirectory. A TIBCO ActiveMatrix product might consume 1GB of free spaceunder TIBCO_HOME.

Software RequirementsYour system must meet the software requirements before you run the installer. Some software is required,and others optional. An external database is required for production systems but not during development.

Before you run the installer, you must make sure you are running on a supported platform. See the readmefile for information about the supported operating system platforms and versions and about required patches.

You must also have required software installed. See the readme file for the supported products and versions.

Table 4: Required and Optional Software on page 19 lists the required and optional software. Several of therequired software components are downloaded by the installer.

Table 4: Required and Optional Software

DescriptionSoftware

Required. If necessary, the TIBCO Universal Installer automatically downloads Hibernateduring installation.

Hibernate

Required. On some operating system platforms, TIBCO Universal Installer automaticallydownloads certain Eclipse LGPL components during installation if necessary.

Eclipsecomponents

On some operating system platforms, you must download Oracle Java 7 Elliptic CurveCryptography (ECC) LGPL separately. Oracle ships the SunEC (an ECC implementation)

JRE Components

library as part of JRE 7. The SunEC library is covered by a different license (LGPL). Installthis library to take advantage of ECC. The TIBCO Universal Installer automaticallydownloads the library for you from download.tibco.com during installation.

If you do not wish to install the Elliptic Curve Cryptography library, you may delete thelibrary named libsunec.so (on Solaris and Linux systems) or sunec.dll (on Windowssystems) or libsunec.dylib (on MacOS) from the TIBCOJRE bin directory reserved fornative libraries.



DescriptionSoftware

IBM's implementation of Java 7 includes ECC, but ECC does not fall under aseparate license as it does in Oracle's implementation.

Several software components from TIBCO Software might be required. Some componentsare included in the installer package, others must be installed separately. See the readmefile for details about the required versions.

TIBCO Software

• Java Virtual Machine - Required. JRE 7 is included in the installation. Alternately, ifthe java version shipped by ActiveMatrix is older than the one on your machine, youcan use the JRE version installed on your machine. The minimum required versionsfor the following platforms are:– HP (HP-UX only) JRE 7.0.06– IBM JRE 1.7.0 SR2– Oracle JRE 7 update 25

If you are upgrading to or using JRE 7, apply MS SQL Server JDBC 3.x hotfix.

• TIBCO Enterprise Message Service - Required. Used as the notification and messagingbackbone for the TIBCO ActiveMatrix products. This software is not included in theinstaller package but is distributed and installed separately.

TIBCO Enterprise Message Service can also be used by the TIBCO ActiveMatrixSOAP/JMS and JMS binding types. The license for your TIBCO ActiveMatrix productdoes not cover this usage of the Enterprise Message Service software. You mustseparately license TIBCO Enterprise Message Service or another supported JMS productfor this usage.

Required to store administration information.

An embedded version of HSQLDB 1.8.400 is included for demonstration and trial setups.The TIBCO ActiveMatrix platform now supports Microsoft SQL Server 2012.

DBMS Software

HSQLDB 1.8.400 must not be used for production or any setup where data loss isunacceptable. This version of HSQLDB does not guard against database corruption.

See the readme file for the supported DBMS software for regular use.

Required by TIBCO ActiveMatrix Administrator and by associated services to access thedatabase resources. For the supported drivers, see the Third-Party drivers section in thisdocument. The ActiveMatrix platform now supports JDBC 4.0.

JDBC Drivers

JDBC connections to Microsoft SQL Server 2008 require updates from Microsoft.See Microsoft Knowledge Base article 2653857.

If you use the embedded version of HSQLDB 1.8.400 during development, you do nothave to install a third-party driver.

Optional. Supports the LDAP authentication realm that the Administrator server can usefor authenticating users. As an alternative, you can configure a database authenticationrealm.

LDAP Servers

Optional. Supports SOAP/JMS and JMS binding types.JMS Servers

Required to run the ActiveMatrix Administrator GUI.Web Browser



DescriptionSoftware

Required to view the Enterprise Graphical view and the monitoring dashboards in theActiveMatrix Administrator GUI.

Silverlight

Required to run TIBCO Configuration Tool, runtime object upgrade, and ActiveMatrixAdministrator CLI scripts. The current supported version is up to Apache ANT 1.8.2.

Apache ANT

Optional. ActiveMatrix Administrator integrates with UDDI servers that comply withthe UDDI V3 specification.

UDDI Registries

On some UNIX and Linux platforms, you must install the GTK2 libraries and theirdependencies and make them available in the library path (LD_LIBRARY_PATH). To

GTK2

determine the full set of libraries required for installation, download and install the gtk2rpm. When you do, all missing dependencies are listed. These dependencies should beavailable for download from the GTK2 download site. The GTK2 libraries are availablewhen you install Solaris 11.1.x86 graphical distribution.



Pre-installation TasksPre-installation tasks include customizing your environment for certain platforms. In a production environment,you must set up an external database before installation because the database included in the installation issupported only for development.

Configuring External DatabasesThe in-process HSQLDB database must only be used in trial setups where data loss is acceptable. It not, youmust use an external database with your ActiveMatrix enterprise.

Prerequisite: If you are using an external database, you have to perform database-specific configurationbefore you can create runtime objects such as the Administrator server.

Set up your database, depending on the database vendor. The database schema can either be createdautomatically or manually. The DDL Script Generator utility generates the database scripts that can beexecuted manually.The database permissions needed will vary accordingly.

To create an ActiveMatrix Administrator server, you must provide database information including a databaseusername. This database user account needs the right privileges for proper operation.

Table 5: Permissions Needed to Create the Database Schema

Database Privileges NeededCreation of The DatabaseSchema

Automatically 1. Grant DDL privileges, such as permissions to access create tables, indexes,constraints, and so on to the database user account.

2. Grant DML privileges, such as permissions to select, insert, update, deleterecords in the tables, or query for table meta-data.

The permissions are specific to the database type and are listed underDatabase Permissions Needed for Automatic Schema Creation.

Grant DML privileges, such as permissions to select, insert, update, deleterecords in the tables, or query for table meta-data. The permissions are specific

Manually

to the database type and are listed under Database Privileges Needed forManual Schema Creation.

Database Privileges Needed for Automatic Schema CreationLists the privileges needed specific to database type for automatic schema creation.

Table 6: Privileges Granted Based on the Database Type

PrivilegesDatabase Type

Required : You must not have the DBA privilege, andyou must be assigned to the database schema.

Permissions: grant connect, resource to <amx-user>.

Oracle

Required: Set 'read_committed_snapshot' to ON byexecuting:

Microsoft SQL Server

1. alter database <amx-database> set

read_committed_snapshot on




2. Use the case insensitive collation setting for<amx-database>

3. Assign <amx-user> the default database<amx-database>

Permissions: grant db_owner role to <amx-user> forthe <amx-database>.

Required: Configure the database with a 32KB pagesize (instead of the default 4KB page size).Permissions:

IBM DB2

Postrequisite: After installation, you have to use TIBCO Configuration Tool to configure the third-partyJDBC driver for your database.

Database Privileges Needed for Manual Schema CreationLists the privileges needed specific to database type for manual schema creation.



Required : You must not have the DBA privilege, andyou must be assigned to the database schema.

Permissions: Grant the following permissions:

Oracle

grant create session

Required: Set 'read_committed_snapshot' to ON byexecuting:






Permissions: grant db_datareader, db_datawriterto <amx-user> for the <amx-database>.

Required: Configure the database with a 32KB pagesize (instead of the default 4KB page size).

IBM DB2

Permissions: Create dmluser with connect databasepermission.

To run the DDL Script Generator utility, see DDLGeneratorTask on page 103.

What to do next

After installation, use TIBCO Configuration Tool to configure the third-party JDBC driver for your database.



Configuring AntThe default setup of Ant might have an insufficient amount of memory available for running CLI scripts orconfigurations scripts from the TIBCO Configuration Tool. You can increase that value for your Windowsor Linux system.

About this taskPerform the following steps to ensure that Ant does not run out of memory when executing scripts.

Procedure

1. Increase the JVM permgen size.

– Windows Edit %USERPROFILE%\antrc_pre.bat and add following line:

set ANT_OPTS=-Xmx1024m -XX:MaxPermSize=256m -XX:PermSize=128m

– UNIX Edit ~/.antrc and add the following line:

export ANT_OPTS="-Xmx1024m -XX:MaxPermSize=256m -XX:PermSize=128m"

2. Confirm the value of ANT_OPTS before you execute scripts from the command prompt.

Configuring Red Hat Linux 6 and AIX 6.1 32-bit PlatformsOn 32-bit systems, you must install a number of additional 32-bit packages.

About this taskYou can use yum to install the packages. This example illustrates how to perform the task on Red Hat Linux6.

See the readme file for your product for a list of supported platforms. This document may describeplatforms that are not supported for your product.

Procedure

1. Mount a Red Hat 6 64-bit ISO file such as rhel-server-6.1-x86_64-dvd.iso.mount /dev/cdrom /mnt/cdrom rhel-server-6.1-x86_64-dvd.iso

2. Back up the properties file /etc/yum.repos.d/rhel-source.repo.cp /etc/yum.repos.d/rhel-source.repo /etc/yum.repos.d/rhel-source.repo.bak

3. Edit the following properties in /etc/yum.repos.d/rhel-source.repo.baseurl=file:///mnt/cdrom/Server enabled=1 gpgcheck=0

4. Install the packages.yum install glibc.i686 yum install gtk2.i686 yum install PackageKit-gtk-module.i686 yum install libcanberra-gtk2.i686 yum install gtk2-engines.i686yum install eclipse-swt* yum install libstdc++.so.5

5. On AIX change the maximum allowable size of the ARG/ENV list. If you do not make this change, TIBCOHost instances cannot start. Open a terminal window and run the following command.chdev -l sys0 -a ncargs=16



Configuring AIX PlatformsOn AIX, change the maximum allowable size of the ARG/ENV list. If you do not change, TIBCO Hostinstances cannot start.

Before you begin

If you installed a product that supports AIX 6.1 and you want to use that platform, you must install severalprerequisite packages. See Configuring Red Hat Linux 6 and AIX 6.1 32-bit Platforms on page 24.

About this task

See the readme file for your product for a list of supported platforms. This document may describeplatforms that are not supported for your product.

Procedure

1. Log in as root.2. Open a terminal window, and run the following command.

chdev -l sys0 -a ncargs=16

Configuring the Environment Settings for AIX Platforms Versions 6.1 and AboveTo run native executables such as, a wrapper that launches Java, requires special configuration on the AIX6.1 and above. This section lists the environment variables that should be set to improve the performance onAIX.

Following are some configuration parameters that may affect the performance and memory profile ofActiveMatrix and Business Process Management nodes. For details, refer tohttp://pic.dhe.ibm.com/infocenter/java7sdk/v7r0/index.jsp for details on Running Java Applications forJava Version 7 on the AIX platform.

Setting the Java Heap Size

The maxdata setting controls the size of the Java heap used by the executable launching the JVM (AMX orBPM Node). The ActiveMatrix and Business Process Management node executables are compiled withmaxdata value of 0x80000000. This value can be changed by running the following command:

ldedit -bmaxdata:<value> tibamx_BPMNode

where <value> is the value of the the maxdata; this value can be changed to be unlimited.

Setting the Environment Variables That Have an Impact on JVM Runtime

On AIX, here are some environment variables that have an impact on the JVM runtime:

LDR_CNTRL=USERREGS: Used to set the modType flag to 1L. This improves the performances of the garbagecollector.

The following environment variables are suggested by IBM to improve the performance of JVM.• AIXTHREAD_SCOPE=S

• AIXTHREAD_MUTEX_DEBUG=OFF

• AIXTHREAD_RWLOCK_DEBUG=OFF

• AIXTHREAD_COND_DEBUG=OFF

The AIXTHREAD_SCOPE=S environment variable is used to bind a user thread to a dedicated kernel thread. Ifomitted the default behavior is to bind multiple user threads with a single kernel thread. This can cause both



http://pic.dhe.ibm.com/infocenter/java7sdk/v7r0/index.jsp

concurrency and performance issues. Refer to the IBM documentation for details on the usage of each of theseenvironment variables.

Configuring the Maximum Number of Open Files on Linux PlatformsYour Linux platform default settings might have a limit on the maximum number of open files and filedescriptors that is too low for the product you want to install. You can change this number by editing thelimits.conf configuration file.

About this task

On all Linux systems, the operating system controls the maximum number of open files and file descriptors.The threshold is typically too low and must be increased. The exact number depends on the features youselect during installation and configuration and on the size of the workspace. In most cases, 10000 files issufficient.

Procedure

1. Edit /etc/security/limits.conf and add the following line:* hard nofile 10000

2. Log out of the system and log back in.

Downloading Software Assemblies if No Internet Access is AvailableIf your machine will not be connected to the Internet during installation, you must download several softwareassemblies from the TIBCO download site before you start the installation process. Download the assembliesafter you download and extract the installer, but before you run the installer.

Procedure

1. Decide on the download location for the assemblies.

– To streamline the process, save the software assemblies to the assemblies subdirectory of the temporarydirectory that you extracted the installer package in.

– You can also download the assemblies to a different temporary directory.

2. To download the Hibernate software assembly, clickTIB_assembly_tibco_com_tibco_tpcl_org_hibernate_feature_3.2.4.001_all html on the TIBCO downloadsite.assembly_tibco_com_tibco_tpcl_org_hibernate_feature_3.2.400.001.zip is downloaded to thelocation you select.

3. On Linux, HP, AIX, and Solaris, download the following Eclipse LGPL software assemblies from theTIBCO download site.In the following steps, OSplatform is one of linux24gl23_x86, linux24gl23_x86_64, sol10_x86, sol10_x86_64,linux26gl24_s390x, sol9_sparc_64, sol9_sparc, aix53_power_64, hpux112_ia64,.a) Click TIB_product_tibco_eclipse_lgpl_3.7.2.001_OSplatform.html.

product_tibco_eclipse_lgpl_3.7.2.001_OSplatform.zip is downloaded to the location you select.b) Click TIB_product_tibco_eclipse_lgpl_rcp_3.7.2.001_OSplatform.html.

product_tibco_eclipse_lgpl_rcp_3.7.2.001_OSplatform.zip is downloaded to the location youselect.

c) Click TIB_product_tibco_sunec_1.7.0.021_OSplatform.html.product_tibco_sunec_1.7.0.021_OSPlatform.zip is downloaded to the location you select.



Chapter

3Installation

Install TIBCO products with TIBCO Universal Installer. The installer runs on multiple platforms. You can run theinstaller in the GUI mode, console mode, and silent mode.

After you have complete the installation, run TIBCO Configuration Tool. The tool displays a list of wizards for theproducts that are installed in TIBCO_HOME. For some products, configuration includes creating runtime objectssuch as a TIBCO Host instance or an Administrator server. For other products, configuration includes other tasks.

For some products, the tool is included in the installation and the GUI installer prompts you to run TIBCOConfiguration Tool when you complete the installation. For other products, install TIBCO Configuration Tool usinga separate installer.

In all cases, you can also run TIBCO Configuration Tool explicitly.

Topics

• Preparing for Installation• Installing in GUI Mode• Installing in Console Mode• Installing in Silent Mode• Moving an Installation to a Destination Machine


Preparing for InstallationBefore you start with installation, make sure your system meets all prerequisites, decide on the installationenvironment name and folder, and download and extract the installation package.

About this task

If you have an existing 64-bit version of the product, do not install a 32-bit version on top of it.

TIBCO_HOME is the top-level installation directory for TIBCO_HOME products. TIBCO_HOME is referred to asthe installation environment. Installation environments isolate product installations; a product installed intoan installation environment does not access components in other environments.

An installation environment consists of a name and a folder.

• The name identifies the environment, is appended to the name of the Windows services created by theinstaller, and is a component of the path to the product in the Windows Start > All Programs menu.

• The folder contains the installed software. When you install you can choose a new installation environmentor an existing installation environment.

If a previous installation of a TIBCO product did not use the TIBCO Universal Installer, then the TIBCOUniversal Installer does not detect the folder those older products use as an installation environment folder.To use the existing location as the installation folder, create a new installation environment and choose thefolder where the other products exist. See the Release Notes for restrictions on the installation environment.

Before applying the service pack, ensure that there is sufficient room in the TIBCO_HOME directoryto hold a backup of the files to be updated. This is approximately half the size of the service pack ZIPfile.

Procedure

1. Make sure your environment meets all requirements and perform the pre-installation tasks.See Installation Requirements on page 18 and Pre-installation Tasks on page 22.

If you do not have Internet access, be sure to download the required software assemblies. SeeDownloading Software Assemblies if No Internet Access is Available on page 26.

2. Decide on the installation environment (TIBCO_HOME) you want to use. The installer will prompt you fora name and a folder.

3. Set up your environment for the installation you are planning.ActionChoice

Stop all processes that are using Java fromTIBCO_HOME.

If you plan on installing in an existing installationenvironment.

Stop all the processes corresponding to theobjects.

If you plan on installing on a machine on which runtimeobjects (Administrator server, TIBCO Host instances, andnodes) are running.

Create a new installation environment.If you plan on installing the SOA Development profile or acustom profile containing TIBCO Business Studio.

4. Extract the service pack to a temporary directory different from where the product installer archive wasextracted.

5. Perform the installation based on the mode you selected.


28 | Installation

Installing in GUI ModeWhen you run the installer in the GUI mode, the installer prompts you for information about the installationenvironment, and allows other customizations.

Before you beginPrepare your system. See Preparing for Installation on page 28.

Procedure

1. Run TIBCOUniversalInstaller.2. Click Next on the Welcome screen.3. Read through the license agreement, select I accept the terms of the license agreement, and click Next.4. Select a new installation environment (TIBCO_HOME) or an existing installation environment and click

Next.ProcedureOption

Specify properties:Create a NewTIBCO_HOME • Directory The directory into which the product is installed. The directory

cannot be the same as the directory of an existing installationenvironment.

The directory path cannot contain special characters such as "*", "#", "?",">", "<", "%", "&", "$", "`" or "|".

• Name Identifies the installation environment. The name cannot containspecial characters such as "*", "?", ">", "<", ":", "|", "/", "\", or quotes (").

Select an installation environment from the drop-down list.Use an ExistingTIBCO_HOME

5. Follow these steps to accept license agreements for third-party software and to optionally install thatsoftware.a) When the Hibernate license agreement appears, read the text and click I accept the terms of the license

agreement.b) On Linux and Solaris, the LGPL License Agreement appears. Read the text and click I accept the terms

of the license agreement.c) If the Hibernate software is not in the assemblies subdirectory of your temporary directory, you are

prompted for a Download Hibernate option.• Download Hibernate assembly from TIBCO. Select this option if you are connected to the Internet

or you do not want to use a previously downloaded assembly. The assembly is automaticallydownloaded and stored in the assemblies subdirectory of the directory where you extracted theinstaller.

• Select the Hibernate assembly previously downloaded from TIBCO. Choose this option if youare not connected to the Internet. Click Browse to navigate to the directory where a Hibernateassembly that was previously downloaded is stored and click Open. See Downloading SoftwareAssemblies if No Internet Access is Available on page 26.

To download Hibernate, the wizard displays the Hibernate download process.d) On Linux and Solaris, if you install Development Tool, and if the

product_tibco_eclipse_lgpl_3.7.2.001 assembly is not in the assemblies subdirectory of yourtemporary directory, the LGPL Assembly Download screen displays. Select a download option:


Installation | 29

• Download Gnome Binding assembly from TIBCO. Select this option if you are connected to theInternet or do not want to use a previously downloaded assembly. The assembly is automaticallydownloaded and stored into the assemblies subdirectory of the directory where you extracted theinstaller.

• Provide the location for the assembly previously downloaded from TIBCO. Select this option ifyou are not connected to the Internet. Click Browse to navigate to the directory where theproduct_tibco_eclipse_lgpl_3.7.2.001 assembly that was previously downloaded is stored.Select the assembly and click Open. See Downloading Software Assemblies if No Internet Accessis Available on page 26.

e) On Linux and Solaris, if you install TIBCO Host software and theproduct_tibco_eclipse_lgpl_rcp_3.7.2.001 assembly is not in the assemblies subdirectory ofyour temporary directory, the LGPL Assembly Download screen displays. Select a download option:• Download GNOME Binding assembly from TIBCO. Select this option if you are connected to the

Internet or do not want to use a previously downloaded assembly. The assembly is automaticallydownloaded and stored into the assemblies subdirectory of the directory where you extracted theinstaller.

• Provide the location for the assembly previously downloaded from TIBCO. Select this option ifyou are not connected to the Internet. Click Browse to navigate to the directory where theproduct_tibco_eclipse_lgpl_rcp_3.7.2.001 assembly that was previously downloaded isstored. Select the assembly and click Open. See Downloading Software Assemblies if No InternetAccess is Available on page 26.

6. On the Installation Profile Selection screen, select one or more of the previously configured profiles, orclick Customize Installation and explicitly select the components you want to install. Click Next.

7. From the Java Home screen, select a JVM provided by TIBCO or specify a existing installation of Java.Click Next.

8. Shut down all TIBCO processes if the installer prompts you to do so.The installer prompts if the features are already installed on the target system. Reinstalling features is notusually recommended.

9. On the Pre-Install summary screen, verify the list of products selected for installation, and click Install.a) When the installation is complete, click Finish.

10. When installation completes, you can select to launch TIBCO ConfigurationTool to create TIBCO Host orAdministrator server instances. If you do not want to run TIBCO Configuration Tool right away, clearthe Launch TIBCO Configuration Tool checkbox.


30 | Installation

Installing in Console ModeAfter you prepare your system and the installation media, you can run the installer in the console mode.

Before you beginPrepare your system. See Preparing for Installation on page 28.

If you expect to have no Internet access when you install, be sure to download the software assembliesbefore you run the installer. See Downloading Software Assemblies if No Internet Access is Availableon page 26.

Procedure

1. In a console window, navigate to the temporary directory to which you extracted the files.2. Run TIBCOUniversalInstaller -console.

The installer launches a second console window.3. Respond to the prompts in the second console window.

The installer prompts for installation information and you can return to a previous selection periodically.The process is similar to Installing in GUI Mode on page 29.

4. When installation completes, press Enter to exit the installer.The console installer does not prompt you to run TIBCO Configuration Tool. To create servers and otherruntime objects, you can run TIBCO Configuration Tool explicitly.

What to do nextAfter you exit the installer, you perform post-installation tasks and configuration. To configure yourenvironment, you can run TIBCO Configuration Tool in the GUI mode, console mode, or silent mode.1. Continue with Post-Installation Tasks on page 35.2. Run TIBCO Configuration Tool. See Configuration Tool Wizards and Screens on page 62.

If you are installing TIBCO BusinessWorks Service Engine, you have to perform additional Post-InstallationTasks.


Installation | 31

Installing in Silent ModeYou can run the installer without user input by pointing the installer to a response file. A default previouslyconfigured response file exists.

Before you beginPrepare your system.

If you expect to have no Internet access when you install, be sure to download software assembliesbefore you run the installer. See Downloading Software Assemblies if No Internet Access is Availableon page 26. If you have Internet access, the installer silently installs the required assemblies andcompletes installation.

About this taskIn the silent mode, the installer does not prompt for inputs during installation but reads the inputs from aresponse file. By default, the installer uses the TIBCOUniversalInstaller-product_version.silent file, whichis included in the directory that contains the universal installer.

You can customize the silent installer as follows:• Make a backup copy of the TIBCOUniversalInstaller-product_version.silent file and edit the file itself.

You can then run the silent installer with or without the response file argument.• Make a copy of the TIBCOUniversalInstaller-product_version.silent file and name the copy. You can

then run the silent installer, passing in your custom response file.

Procedure

1. Make a copy of the TIBCOUniversalInstaller.silent file and name the file, for example, myfilename.silent.2. Using a text editor, open the copied file and update the installation location and features to install.3. Run the silent installer with or without the optional response file.

– Windows: TIBCOUniversalInstaller.cmd -silent [-V responseFile="myfile.silent" ]– UNIX: TIBCOUniversalInstaller.bin -silent [-V responseFile='myfile.silent']

What to do nextAfter exiting the installer, perform the post-installation tasks and configuration. You can run TIBCOConfiguration Tool in the GUI mode, console mode, or silent mode.1. Continue with Post-Installation Tasks on page 35.2. Run TIBCO Configuration Tool.

See the documentation for your TIBCO ActiveMatrix product.

If you are installing TIBCO BusinessWorks Service Engine, you have to perform additional Post-InstallationTasks.


32 | Installation

Moving an Installation to a Destination MachineYou can install the TIBCO ActiveMatrix products on a source machine and move the installed software andscripts to a destination machine. With this procedure, you can create TIBCO Host instances and Administratorserver on destination machines without running the installer on each destination machine.

Procedure

1. Install the product on the source machine.2. If you are using the GUI installer, clear the Launch TIBCO Configuration Tool checkbox on the final

installer panel.3. Package the contents of TIBCO_HOME using an archive utility.4. Unpack the archive on the target machine. Use the same location on the destination machine as you did

on the source machine. For example: C:\Program Files\tibco\amx-3.5. On the destination machine, run TIBCO Configuration Tool to create TIBCO Host instances and an

ActiveMatrix Administrator server.

What to do nextAfter you have moved the installation, you can run TIBCO Configuration Tool on each target machine toconfigure your setup.


Installation | 33

Chapter

4Post-Installation Tasks

You must perform certain post-installation tasks before you can create and configure runtime objects such asAdministrator.

Topics

• Configuring Linux Platforms for TIBCO Business Studio• Prerequisites for Uninstalling


Configuring Linux Platforms for TIBCO Business StudioOn machines on which TIBCO Business Studio is installed, you have to edit the initialization script.

Procedure

1. Open the file TIBCO_HOME /studio/version/eclipse/TIBCOBusinessStudio.ini.2. TIBCO Business Studio is not compatible with Xulrunner 1.9, which is used by Firefox v3.5 and above

and typically installed as part of the Firefox browser. The compatible versions of Xulrunner are shownhere: http://www.eclipse.org/swt/faq.php#browserlinux. On machines on which TIBCO Business Studiois installed, download a compatible version and add the following line to your TIBCOBusinessStudio.inifile:-Dorg.eclipse.swt.browser.XULRunnerPath=path_to_xulrunner_1_8


36 | Post-Installation Tasks

http://www.eclipse.org/swt/faq.php#browserlinux

Prerequisites for Uninstalling

Before you begin

If you want to uninstall TIBCO Implementation Type for TIBCO Adapters, follow these steps before youuninstall the product.1. From the Administrator GUI, undeploy and delete all applications that were deployed from EAR files.2. From the System folder of the deployed applications, undeploy and delete the com.tibco.amx.it.proxy.apt

application.3. In the Administrator GUI, select Software Management > Application Templates and delete TIBCO

Proxy Implementation Type Application Template.4. In the TIBCO Administrator GUI, select Admin Configuration > Plug-ins and undeploy and delete the

TIBCO Implementation Type for the TIBCO Adapters plugin.5. Stop the TIBCO Hawk Agent and TIBCO Hawk Monitoring Agent processes and all nodes running from

connected environments.6. In the CONFIG_HOME directory of the environment where the TIBCO Hawk Agent was configured, delete

the ext directory.7. Stop the TIBCO Host and Administrator server processes.


Post-Installation Tasks | 37

Chapter

5Configuration

Use TIBCO Configuration Tool to configure the product. You can configure immediately after installation or at alater time. Available options depend entirely on the products installed in the TIBCO_HOME directory for whichyou are running the tool.

Topics

• Configuration Setup and Overview• Configuration Tool Wizards and Screens• DDL Script Generator


Configuration Setup and OverviewUse TIBCO Configuration Tool to specify the properties of the ActiveMatrix Administrator servers and TIBCOHost instances and also properties of third-party drivers you want to add to the ActiveMatrix Administratorservers.

You can run TIBCO Configuration Tool in the GUI mode, console mode, silent mode, or script mode.

Silent mode and script mode are for advanced users.

• In the GUI mode, the tool prompts for configuration information with a set of wizards.• In the console mode, the tool prompts for configuration information on the command line.• In the silent mode, you generate a configuration file by running a wizard in the GUI or console mode and

responding to the prompts. Edit the configuration file, and then run the tool without user input.• In the script mode, run a wizard in the GUI mode or console mode and explicitly save the configuration

file, or edit one of the sample configurations. You then execute an Ant build from the command windowof the folder in which your configuration is located.

NetworkingBefore you start configuration, check whether the default ports that TIBCO Configuration Tool uses areavailable. You must also decide whether you want to use SSL, and might have to set up keystores and truststores.

Default PortsThe default ports in an ActiveMatrix environment must be available before you can start configuration withthe default values. You can specify a different port during configuration, or change the ports explicitly later.

Figure 1: Default Ports on page 41, Table 8: TIBCO ActiveMatrix Runtime Object Default Ports on page 41,and Table 9: Server Default Ports on page 41 summarize the default values of the ports configured in TIBCOConfiguration Tool. You can change the defaults in TIBCO Configuration Tool wizards. For information onhow to change the ports after you have created runtime objects with TIBCO Configuration Tool, see theTIBCO ActiveMatrix Service Grid Administration guide.


40 | Configuration

Figure 1: Default Ports

Table 8:TIBCO ActiveMatrix Runtime Object Default Ports

Default PortRuntime Object

6051SystemHost TIBCO Host instance management

6001Standalone TIBCO Host instance management

6021System node management

6038Development node management

8120TIBCO ActiveMatrix Administrator external HTTP

19767TIBCO ActiveMatrix Administrator internal HTTP

6041TIBCO Credential Server

Table 9: Server Default Ports

Default PortServer

7222 or 7243 (SSL)Enterprise Message Service

Oracle 1521Database

Microsoft SQL 1433

IBM DB2 5000

389LDAP


Configuration | 41

Secure Communication ChannelsThe ActiveMatrix platform is partitioned across many components. You can secure the correspondingcommunication channels during the initial configuration or later.

ActiveMatrix components communicate with each other and with third-party applications over severalcommunication protocols. Figure 2: Communication Channels on page 42 illustrates the components andcommunication protocols.

Figure 2: Communication Channels

By default, the communication channels are not secure. To secure them, you can configure the channels touse the Secure Sockets Layer (SSL) protocol. SSL is a cryptographic protocol that provides security and dataintegrity for communications over TCP/IP networks.

An SSL client and server negotiate a connection by using a handshaking procedure. During this handshake,the client and server agree on various parameters to establish the connection's security, as follows:1. A client requests a secure connection from an SSL-enabled server requesting a secure connection.2. The server sends back its identification in the form of a digital certificate.

The certificate usually contains the server name, the trusted certificate authority (CA), and the server'spublic encryption key.

You can specify the SSL configuration of the communication channels at different times in the life cycle of adeployment. Table 10: SSL Configuration Summary on page 43 lists how to perform the initial SSLconfiguration and how to upgrade, downgrade, and change the configuration of each channel. The Keycolumn in the table points to the numbers in Figure 2: Communication Channels on page 42.


42 | Configuration

Table 10: SSL Configuration Summary

Upgrade, Downgrade, or ChangeConfiguration

Initial ConfigurationChannelKey

Upgrade or downgrade: AdministratorCLI

Change SSL configuration:Administrator CLI

When creating the Administratorserver in TIBCO Configuration Tool.

Administratorserver (externalHTTP port) - weband CLI clients

1

Upgrade or downgrade: Administratorweb UI or CLI

Change SSL configuration:Administrator web UI or CLI


Administratorserver (internalHTTP port) - hostsand nodes

2

Upgrade or downgrade: Administratorweb UI or CLI

Change SSL configuration:Administrator web UI or CLI


Administratorserver - EnterpriseMessage Serviceserver

(NotificationServer andMessaging Bus)

3

Upgrade or downgrade: AdministratorCLI


When creating the Administratorserver or TIBCO Host instance inTIBCO Configuration Tool.

TIBCO Hostinstance - TIBCOEnterpriseMessage Service

4



Administratorserver - externaldatabase andLDAP servers

5

Upgrade: Administrator web UI or CLI


When creating Administrator inTIBCO Configuration Tool.Administrator

server - hosts andnodes(management)

6

Same procedure as initial configurationManually import the UDDI servercertificate into the Administratorserver trust store using keytool.

Enable secure communication inAdministrator web UI or CLI.

Administrator-UDDI server

7

Administrator Upgrade or downgrade:Administrator CLI


Administrator - When creatingAdministrator server in TIBCOConfiguration Tool.

TIBCO Business Studio - When youconnect to Administrator.

Administratorserver (externalHTTP port) -TIBCO BusinessStudio

8

Administrator web UI or CLIAdministrator web UI or CLIResource instances(JDBC, JMS,

9

SMTP, LDAP,


Configuration | 43

Upgrade, Downgrade, or ChangeConfiguration

Initial ConfigurationChannelKey

HTTP) - externalservers

KeystoresIf you set up your environment for SSL, you have to set up a keystore. As part of the process, you configurea keystore provider.

SSL uses keys and certificates when it establishes the secure connection. A keystore is a database of keys andcertificates. A keystore password is required to access or modify the keystore.

Access to keystores is provided by a Keystore Provider resource instance. Keystores can be stored internallyin Administrator or externally.

Keystore Entries

A keystore has two types of entries:• Private key - holds a cryptographic private key, which is optionally stored in a protected format to prevent

unauthorized access. The private key is accompanied by a certificate chain for the corresponding publickey. Private keys and certificate chains are used by a given entity for self-authentication.

• Trusted certificate - contains a single public key certificate. It is called a trusted certificate because thekeystore owner trusts that the public key in the certificate belongs to the identity identified by the subject(owner) of the certificate. This type of entry can be used to authenticate other parties.

Certificates of trusted entities are typically imported into a keystore as trusted certificates.

Keystore Entries and Aliases

Each entry in a keystore is identified by an alias. In the case of private keys and their associated certificatechains, these aliases distinguish among the different ways in which the entity may authenticate itself. Forexample, the entity may authenticate itself using different certificate authorities, or using different publickey algorithms. An alias might be named after the role in which the keystore owner uses the associated key,or might identify the purpose of the key.

Keystore Passwords and Private Key Passwords

The private keys in a keystore are encrypted with a keystore password, which should be several words long.

You can also protect each private key with its individual password, which may or may not be the same asthe keystore password.

If a password is lost, the associated keys cannot be recovered.

Keystore ProviderThe Keystore Provider resource template provides access to a keystore.

General

DescriptionAcceptsSVars?

Editable?Required?Property

Location of the keystore:NYYKeystore ServedFrom • Store the keystore in Administrator and serve it

from here• The keystore is hosted externally at URL


44 | Configuration

DescriptionAcceptsSVars?

Editable?Required?Property

Path to the keystore to be uploaded intoAdministrator. After the keystore is uploaded, a linkdisplays from which the keystore can be downloaded.

NYYAdministrator -Upload KeystoreFrom

Location of the external keystore.YYYURL

Password for the keystore.

(Administrator only) For superusers, passwordsdisplay encrypted. For non-superusers, the password

YYYPassword

doesn't display even if it was set when it was created.If you have permission to edit the password, you canspecify a new value and save. If you edit other fields,the old value for the password field is retained. If youwant to set an empty value as password, click the linkSet Blank Password.

Name of the keystore provider:YYNProvider• SunJCE (JCEKS format)• SUN (JKS format)• IBMJCE (IBM JREs)• SunJSSE (PKCS12 format)

Default: Empty. The first matching providersupporting the format will be chosen.

Type of the keystore: JCEKS, JKS, PKCS12.

Default: JKS.

YYYType

Refresh interval, greater than 0. If the keystoreprovider is accessed after the refresh interval hasexpired:

YYYRefresh Interval (ms)

1. The keystore provider is refreshed from its backingkeystore.

2. The refresh timer is reset to zero.3. Operations on the keystore provider are performed

on the refreshed copy.

Default: 3600000.

Creating a Keystore Containing a User Name and PasswordYou can create a keystore that contains a username and password by editing data and build files and runningan Ant script.

Procedure

1. Go to the CONFIG_HOME/admin/enterpriseName/samples/ directory.2. Open the keystore_data.xml data file and edit the following attributes of the CredentialEntry element:

DescriptionAttribute

Alias identifying the keystore entryalias

Password that protects the keystore entryprotectionParam


Configuration | 45


Usernameusername

Passwordsecret

3. Open the keystore_build.xml build file and edit the following attributes of the AMXKeyStoreTaskelement in the addCredential target:


The name of the file to contain the keystore.adminKeyStorelocation

The password protecting the keystore.adminKeyStorePassword

4. Run ant -f keystore_build.xml addCredential.

Example<?xml version="1.0" encoding="UTF-8"?><amxdata_base:Enterprise xmlns:amxdata="http://tibco.com/amxadministrator/command/line/types" xmlns:amxdata_base="http://tibco.com/amxadministrator/command/line/types_base" xmlns:amxdata_reference="http://tibco.com/amxadministrator/command/line/types_reference"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://tibco.com/amxadministrator/command/line/types_base ../schemas/amxdata_base.xsd http://tibco.com/amxadministrator/command/line/types ../schemas/amxdata.xsd">

<AMXKeyStore xsi:type="amxdata:AMXKeyStore"> <CredentialEntry alias="myDatabase" protectionParam="databaseKeyAliasPassword" username="scott" secret="tiger" /> <CredentialEntry alias="myLDAP" protectionParam="ldapKeyAliasPassword" username="cn=Manager,dc=example,dc=com" secret="password" /> </AMXKeyStore>

</amxdata_base:Enterprise>

<target name="addCredential"> <AMXKeyStoreTask dataFile="keystore_data.xml" adminKeyStorelocation = "my_keystore.jceks" adminKeyStorePassword = "password" action="add"/></target>

>ant -f keystore_build.xml addCredentialBuildfile: C:\amx330data\admin\amxadmin\samples\keystore_build.xml

addCredential:[AMXKeyStoreTask] INFO - Keystore file C:\amx330data\admin\amxadmin\samples\my_keystore.jceks does not exist; creating a new keystore file[AMXKeyStoreTask] Adding entry for alias 'myDatabase'...[AMXKeyStoreTask] Adding entry for alias 'myLDAP'...[AMXKeyStoreTask] Saving to keystore file C:\amx330data\admin\amxadmin\samples\my_keystore.jceks

BUILD SUCCESSFULTotal time: 12 seconds

Trust StoresA trust store is a keystore that contains trusted certificates. Each time you configure an external serverconnection for SSL, you create and configure a trust store for that connection.

You can create a trust store by using certificates imported from trusted servers or by uploading a keystorefile.


46 | Configuration

Creating a Trust Store KeystoreYou can create a trust store with keytool if you have a trusted public certificate.

Procedure

1. Acquire the public certificate for your server or the root CA certificate authority that signed the certificate.A root CA is an entity like VeriSign that digitally signs your certificate. The certificate will be in a file witha special extension such as .pem extension.

2. Use the JDK keytool utility to create a keystore containing the certificate from step 1.JAVA_HOME\bin\keytool -import -v -trustcacerts -alias MyCert-file server.cer -keystore MyTrustStore.jks -keypass secret -storepass keystorePassword

Record the values of the keytool options because you must supply them when you upload the trust storekeystore into TIBCO Configuration Tool or Administrator.

Configuring a Trust StoreTo configure a trust store, you can either upload certificates and have TIBCO Configuration Tool create thetrust store, or you upload a keystore file that contains certificates.

About this task

If you configure a trust store for use with an SSL-enabled Microsoft SQL Server, you must upload a keystore.For Microsoft SQL databases, the Configure a Trust Store button does not work.

Procedure

1. Choose the method for configuring the trust store and follow the appropriate procedure.DescriptionMethod

Import 1. Click Create a Trust Store.2. Specify a password to protect the keystore and click Next.

The SSL setup wizard displays certificates imported from the trusted server.

3. In the Trust Selected Certifications area, select the checkboxes next to the certificatesto trust and click Finish.

A keystore file is created containing the selected certificates and the Keystore Location,Keystore Type, and Keystore Password fields are filled in with the keystore information.

Upload 1. Create a keystore containing the certificates from the trusted server.2. Click Browse and navigate to the location of the keystore you created.3. Click the keystore and click Open.

The wizard fills in the Keystore Location field.

4. From the Keystore Type drop-down list, select the keystore type.5. Type the keystore password.

2. Click Test Connection to verify that the keystore enables an SSL connection.

Related TopicsAdministrator Server Notification and Messaging Bus Server on page 63

The Administrator Server Notification and Messaging Bus Server screen prompts you for theconnection information for one or more TIBCO Enterprise Message Service server instances. The


Configuration | 47

http://download.oracle.com/javase/1.3/docs/tooldocs/win32/keytool.html

Notification and Messaging Bus servers in your express developer environment are then associatedwith that server.

Administrator Server Database Details on page 71You can choose to use the Administrator server with a default in-process database during development.In production systems, use an external database instead. This screen allows you to configure databasedetails.

Administrator Server Database Authentication Realm on page 72If you select a database authentication realm, Administrator stores information about users andgroups in a database. You can select the same database as the Administrator server, or configure adifferent database.

Administrator Server LDAP Authentication Realm on page 74If you select an LDAP authentication realm, Administrator stores information about users and groupsin LDAP. You are prompted for the user and password, name resolution context, and server URLs.You can also specify the user search configuration and optional group information.

Administrator Server Monitoring Service Notification Server on page 78The monitoring service is an ActiveMatrix application that aggregates performance data from runtimeobject, that is, TIBCO Host instances and nodes. TIBCO Configuration Tool deploys the monitoringservice application on the SystemNode node, which is the node that runs the Administrator server.

Administrator Server Monitoring Service Database on page 79The monitoring service is an ActiveMatrix application that aggregates performance data from runtimeobjects. The monitoring service application is deployed on SystemNode, the node that runs theAdministrator server.

Administrator Server Log Service Database on page 80A log service is a TIBCO ActiveMatrix application that offers logging services. The log serviceapplication is deployed in the environment SystemEnvironment on SystemNode, the node that runsthe Administrator server. A log service receives log entries sent to a JMS destination and stores theentries in a database.

Administrator Server Payload Service Database on page 82A payload service supports archiving, persisting and retrieving large size payload data. It is anindependent service and does not depend on a log service. However, a log record sent to a log servicecan include a payload URL field to link a log message and payload data. You can store payload datain the same database used by Administrator server or use another database.

TIBCO Host Instance Notification Server on page 85When you create a standalone TIBCO Host instance, you can specify an associated notification server.This notification server can be the same server as that used by the Administrator, or you can definea different notification server.

IPv6 SupportIf an object has a property that can contain an IP address, the address is usually set to the unspecified IPaddress (0.0.0.0). That means the object listens on IPv4 and IPv6 addresses. By default clients use the IPv4address. You can override this behavior so that clients use the IPv6 address.

Prerequisites

Before using an IPv6 supported network, perform the following tasks:1. Complete all the network configuration changes required for network traffic routing.2. Enable all physical machines participating in the installation topology for IPv4 and IPv6 addressing in

dual-stack IP implementations.3. Configure the names of all machines to resolve to at least one IPv4 or IPv6 address.4. Configure clients to communicate with the servers in one of the following ways:

a. Use explicit IPv4 or IPv6 addresses.


48 | Configuration

b. Use the addresses returned by the address translation mechanism (DNS or local host files) performedon the machine name.

IPv6 Address Support

IPv6 addresses are supported by machine names and URLs in the following tools and objects:• TIBCO Configuration Tool• Administrator and TIBCO Business Studio wizards and CLI property files• Components that use dynamic wiring• Resource templates

IPv6 Address Representation

IPv6 address representation is described in the IPv6 Addressing Architecture and Format for Literal IPv6Addressing in URLs specifications, and summarized in Table 11: IPv6 Address Representation on page 49.

Table 11: IPv6 Address Representation

RepresentationAddress Type

Eight fields of four hexadecimal digits, where each field is separated by a colon.If the field is non-zero there must be at least one digit. For example,

All

2001:db8:1234:ffff:4354:45ab:3455:ab45. You can apply the following shorteningprocedures:• Omit leading zeros in a field. For example, :00db: can be represented as :db:.• Replace one or more consecutive fields of zeros and separators (:0:0:0:0:) with

a single empty field (::). For example, 2001:db8:0:0:0:0:3455:ab45 can berepresented as 2001:db8::3455:ab45.

0:0:0:0:0:0:0:1 or ::1.Localhost or loopback

0:0:0:0:0:0:0:0 or ::. This address is equivalent to the unspecified IPv4 address0.0.0.0.

Unspecified

Enclose the address in square brackets ([]). For example, the URL of anAdministrator server running on a machine at the address

Embedded in a URL

FEDC:BA98:7654:3210:FEDC:BA98:7654:3210 ishttp://[FEDC:BA98:7654:3210:FEDC:BA98:7654:3210]:8120/amxadministrator.

IP Address Use and Resolution

The default configuration of the Administrator server network adapter is the unspecified IP address (0.0.0.0),which means that it listens on IPv4 and IPv6 addresses. When clients access the Administrator server bymachine name, the name lookup resolves to both addresses. By default, Administrator clients use the IPv4address. To override this behavior and use the IPv6 address, set the value of the JVM system propertyjava.net.preferIPv6Addresses to true. The Nodes chapter in Administration explains how to set a JVMproperty for a node.

TIBCO Configuration Tool RequirementsYou can run TIBCO Configuration Tool right after installation or at a later time. To run the tool successfully,you must first make sure your system meets the requirements.

Each product installation has a set of requirements. TIBCO Configuration Tool has additional requirements.• You must have access to a running instance of TIBCO Enterprise Message Service server. See Enterprise

Messaging Server Requirements on page 50.


Configuration | 49

http://www.ietf.org/rfc/rfc2373.txt



• If you do not have administrator privileges for the Enterprise Message Service server, you must set upEnterprise Message Service for a non-administrator user. See Configuring TIBCO Enterprise MessageService Servers for Non-Admin Users on page 50.

• If you want to secure communication with SSL, you must perform additional setup. See SecureCommunication Channels on page 42 for background and setup information and SSL Requirements onpage 50 for specific requirements.

See the readme file for additional requirements.

Enterprise Messaging Server RequirementsTo run successfully, TIBCO Configuration Tool must have access to a TIBCO Enterprise Message Service thatmeets certain requirements.

A TIBCO Enterprise Message Service server acts as a notification server for the ActiveMatrix Administratorservers and TIBCO Host instances within an enterprise. The enterprise is defined by the enterprise name andthe TIBCO Enterprise Message Service server that you specify when you run one of the configuration wizards.Ensure that the following requirements and prerequisites are satisfied:• Each enterprise must use a different TIBCO Enterprise Message Service server.• The TIBCO Enterprise Message Service server must be running before you run the Create TIBCO

ActiveMatrix Administrator Server and Create TIBCO Host Instance wizards or create these componentsin the console mode or silent mode.

• If you manually start the TIBCO Enterprise Message Service server, make sure you use the sameconfiguration files as the Windows service. Use the following command:

TIBCO_HOME/ems/version number/bin/tibemsd -configEMS_CONFIG_HOME/tibco/cfgmgmt/ems/data/tibemsd.conf

where EMS_CONFIG_HOME is the configuration folder for TIBCO Enterprise Message Service.• The clocks of machines within the same enterprise must be synchronized to within to 30 minutes. You

can run an NTP synchronization daemon on each machine to achieve synchronization.• If you do not have administrator privileges for TIBCO Enterprise Message Service, you can request

privileges or configure the service for a non-admin user from the TIBCO Enterprise Message Service serverconsole. See Configuring TIBCO Enterprise Message Service Servers for Non-Admin Users on page 50.

SSL RequirementsBy default, ActiveMatrix runs with SSL disabled. You can enable SSL for individual connections or for allconnections in your environment.

See Secure Communication Channels on page 42 for information on setting up SSL. If you intend to enableSSL, ensure the following prerequisites are satisfied.• TIBCO Enterprise Message Service server - The TIBCO Enterprise Message Service server must be enabled

with SSL and configured with a certificate file that contains both the server and issuer certificates beforeyou run the Create TIBCO Administrator server and Create TIBCO Host Instance wizards or before youcreate these components in console mode or silent mode.

ActiveMatrix 3.3.0 and later ships with Java 7. As a result, you must either use an Enterprise MessageService server 6.3 or later version or use a stream cipher.

• Database and LDAP Servers - Database and LDAP servers must be enabled with SSL before you run theCreate TIBCO Administrator Server wizard or before you create these components in the console modeor silent mode.

See Secure Communication Channels on page 42.

Configuring TIBCO Enterprise Message Service Servers for Non-Admin UsersConfiguration of TIBCO ActiveMatrix runtime objects and services is easiest if you have administrativeprivileges on the TIBCO Enterprise Message Service server you want to use. If you do not have administrative


50 | Configuration

privileges, you can set up the TIBCO Enterprise Message Service server to configure Enterprise MessageService servers for non-admin users.

About this taskIf you want to configure TIBCO ActiveMatrix runtime objects and services, and you do not have administratorprivileges on the TIBCO Enterprise Message Service server you want to use, you can configure the TIBCOEnterprise Message Service server to configure Enterprise Message Service servers for non-admin users. Thefollowing steps list the most restrictive permissions necessary.

Procedure

1. In the TIBCO Enterprise Message Service server console, set permissions for the Administrator serverusers. In the following commands, replace username and password with the username and password valuesappropriate for each bus.

– Messaging Busdelete queue >delete topic >create user username "Description of the user" password=passwordcreate queue AMX_SV.>grant queue AMX_SV.> user=username create, delete, modify, send, receive

– Notification Busdelete queue >delete topic >create user username "Description of the user" password=passwordcreate topic EMSGMS.>grant topic EMSGMS.> user=username create, modify, subscribe, publishgrant topic $sys.monitor.connection.* user=username subscribegrant admin user=username view-connection,view-servercreate topic AMX_MGMT.>grant topic AMX_MGMT.> user=username create, modify, subscribe, publishcreate queue AMX_MGMT.>grant queue AMX_MGMT.> user=username create, delete, modify, send, receive

– Management Busdelete queue >delete topic >create user username "Description of the user" password=passwordcreate queue com.tibco.amf.admin.deploymentServerQueue.>grant queue com.tibco.amf.admin.deploymentServerQueue.> user=username create, delete, send, receive

– Logging and Payload Busesdelete queue >delete topic >create user username "Description of the user" password=passwordcreate queue cl_logservice_queue.physicalcreate queue cl_payload_queue.physicalgrant queue cl_logservice_queue.physical user=username send, receivegrant queue cl_payload_queue.physical user=username send, receivecreate jndiname cl_logservice_queue queue cl_logservice_queue.physicalcreate jndiname cl_payload_queue queue cl_payload_queue.physical

– Monitoring Busdelete queue >delete topic >create user username "Description of the user" password=passwordcreate queue amx.governance.statsgrant queue amx.governance.stats user=username send, receivecreate queue amx.governance.internal.statsgrant queue amx.governance.internal.stats user=username send, receive

2. If you intend to manually separate notification, management, and messaging buses, group their constraintsfirst.


Configuration | 51

The Notification, Management, and Messaging buses are initially grouped together as are the Monitoring,Logging, and Payload buses.

– Messaging, Notification, and Management Busesdelete queue >delete topic >create user username "Description of the user" password=passwordcreate queue AMX_SV.>grant queue AMX_SV.> user=username create, delete, modify, send, receivecreate topic EMSGMS.>grant topic EMSGMS.> user=username create, modify, subscribe, publishgrant topic $sys.monitor.connection.* user=username subscribecreate queue com.tibco.amf.admin.deploymentServerQueue.>grant admin user=username view-connection,view-servergrant queue com.tibco.amf.admin.deploymentServerQueue.> user=username create, delete, send, receive

create topic AMX_MGMT.> grant topic AMX_MGMT.> user=username create, modify, subscribe, publish

create queue AMX_MGMT.> grant queue AMX_MGMT.> user=username create, delete, modify, send, receive

– Monitoring, Logging, and Payload Busesdelete queue >delete topic >create user username "Description of the user" password=passwordcreate queue cl_logservice_queue.physicalcreate queue cl_payload_queue.physicalcreate queue amx.governance.statscreate queue amx.governance.internal.statsgrant queue cl_logservice_queue.physical user=username send, receivegrant queue cl_payload_queue.physical user=username send, receivegrant queue amx.governance.stats user=username send, receivegrant queue amx.governance.internal.stats user=username send, receivecreate jndiname cl_logservice_queue queue cl_logservice_queue.physicalcreate jndiname cl_payload_queue queue cl_payload_queue.physical

create queue AMX_SV.>grant queue AMX_SV.> user=username create, delete, modify, send, receivecreate topic EMSGMS.>grant topic EMSGMS.> user=username create, modify, subscribe, publish

3. Configure and create the Administrator server and TIBCO Host instances as described in Create TIBCOActiveMatrix Administrator Server on page 64 and Create TIBCO Host Instance on page 84.

Running TIBCO Configuration ToolYou can run TIBCO Configuration Tool using the GUI, console, or silent mode.

About this taskIf you did not deploy the logging and payload services when you created the Administrator server using theTIBCO Configuration Tool, see TIBCO_HOME\administrator\version\scripts\logging\readme.txt.

Running TIBCO Configuration Tool in GUI ModeWhen you run TIBCO Configuration Tool in the GUI mode, you are prompted to select a configurationwizard. The wizard prompts you for information about that component.

Before you beginMake sure your system meets all requirements. See TIBCO Configuration Tool Requirements on page 49.

Procedure

1. Execute TIBCO_HOME/tct/1.4/TIBCOConfigurationTool.


52 | Configuration

The TIBCO Configuration Folder dialog is displayed. The TIBCO configuration folder stores configurationdata generated by TIBCO products. Configuration data can include sample scripts, session data, configuredbinaries, logs, and so on. The configuration folder is referred to as CONFIG_HOME.

2. Accept the default folder for CONFIG_HOME, type a folder name, or click Browse to select a folder, andclick OK.

3. TIBCO Configuration Tool displays with links to the following configuration wizards:FunctionWizard

Specify the name and server properties of anActiveMatrix Administrator server and the machine

Create Express Developer Environment on page 62

name, port, and credentials of the TIBCO EnterpriseMessage Service server used by the Administratorserver. The TIBCO Host instance named SystemHostand the SystemNode node that runs ActiveMatrixAdministrator server are started. The rest of theconfiguration properties are set to the default valuesdescribed in the section Create TIBCO ActiveMatrixAdministrator Server on page 64.

Create TIBCO ActiveMatrix Administrator Serveron page 64

• Specify the properties of an ActiveMatrixAdministrator server and optionally create theserver. The SystemHost TIBCO Host instanceand the SystemNode node that runsActiveMatrix Administrator server are started.

• Optionally specify a development environmentand node and start the node.

• Specify the properties of monitoring, logging,and payload services running on SystemNodeand optionally deploy the monitoring andlogging services.

• Specify the database that serves as a persistentstore for ActiveMatrix Administrator server andthe monitoring, logging, and payload services.

Specify the communication and managementproperties of a standalone TIBCO Host instance and

Create TIBCO Host Instance on page 84

optionally create and launch the TIBCO Hostinstance.

Package and install third-party client driver librariesthat implement APIs such as JDBC and JMS into the

Configure Third-Party Driver on page 87

ActiveMatrix Administrator server softwarerepository.

Configure a Replica server for a clusteredenvironment.

Replicate TIBCO ActiveMatrix Administrator Serveron page 88

Edit an existing ActiveMatrix Administrator serverconfiguration.

Edit ActiveMatrix Administrator ServerConfiguration on page 95

TIBCO Hawk ActiveMatrix® Plug-in gets installed with the following three wizards:• Create Express Developer Environment• Create TIBCO ActiveMatrix Administrator Server• Create TIBCO Host Instance

For further information, see TIBCO Hawk ActiveMatrix® Plug-in User’s Guide.


Configuration | 53

4. Click a wizard link and follow the prompts.The wizard reference, also available as online help, can help guide your decisions.

5. Optionally, select the Configure to Secure All Communication with SSL checkbox.When you enable SSL, the wizards containing communication channels display the SSL configurationfields. For information on the supported communication channels, see Secure Communication Channelson page 42.

6. Optionally, click Load to load the values saved from a previous configuration session. See Saving a TIBCOConfiguration Tool Configuration on page 57.

7. On any screen, click Finish to accept the default values for all the configuration properties and move tothe Summary screen.

8. Review the Summary screen and select or clear check boxes for wizard actions.9. Click Configure.

Running TIBCO Configuration Tool in Console ModeYou can run TIBCO Configuration Tool from the command prompt on the platform of your choice.

Before you beginMake sure your system meets all requirements. See TIBCO Configuration Tool Requirements on page 49.

About this taskYou can run TIBCO Configuration Tool in the GUI mode, console mode, or silent mode. The mode you usedfor running the installer does not affect the mode in which you run TIBCO Configuration Tool.

Procedure

1. In a console window, go to the TIBCO_HOME\tct\version directory and run the following command.DescriptionPlatform

TIBCOConfigurationTool -consoleModeLinux, UNIX

TIBCOConfigurationToolc.exe -consoleModeWindows

On Windows, the name ends with a c; do not type TIBCOConfigurationTool -consoleMode.

2. Select one of the configuration options and press Enter.3. Type 1 or press Enter to configure all communications with SSL, or type N to continue.

For information on the supported communication channels, see Secure Communication Channels on page42.

4. Follow the configuration tool prompts to set up your environment. After you review the pre-installationsummary, type G to start the configuration process.When configuration completes, you can select a second configuration option or type q to quit.

Running TIBCO Configuration Tool in Silent ModeYou can configure your system without user input by running TIBCO Configuration Tool in silent mode.You can supply parameters that specify which wizard you want to run, and you can specify whichconfiguration file you want to use.

About this taskBefore you run in the silent mode, you should run the tool in GUI mode to generate a configuration file(build.properties). You can then run in silent mode, pointing to the configuration file you generated.


54 | Configuration

Each build.properties file specifies the machine name and operating system. If you want to use thatproperties file to run in the silent mode on a different machine, potentially with a different operating system,you can edit the properties file. You might have to change the following values in the configuration file.• Machine name (must be changed)• ActiveMatrix installation location• ActiveMatrix runtime configuration data location• ActiveMatrix enterprise name• Operating system (optional)

You must be an advanced user with an in-depth understanding of the configuration process tosuccessfully run TIBCO Configuration Tool in the silent mode.

Procedure

1. Run the tool in the GUI mode or in console mode to generate a properties file.build.properties file is stored in CONFIG_HOME/tct/subfolder/date-time/scripts.

The name of subfolder depends on the wizard you run in the GUI or console mode.

2. Edit the build.properties file and customize the configuration. In most cases, you specify a differentmachine name, Administrator server, and so on.See Using TIBCO Configuration Tool Scripts and Property Files on page 56.

3. Decide on the wizard you want to run.Wizard IDWizard

com.tibco.tct.adminCreate TIBCO ActiveMatrix Administrator Server

com.tibco.tct.admin.editorEdit TIBCO ActiveMatrix Administrator Server

com.tibco.tct.ede.adminCreate Express Developer Environment

com.tibco.tct.tibcohostCreate TIBCO Host Instance

com.tibco.tct.tpclshellsConfigure Third-Party Driver

com.tibco.tct.admin.repliateReplicate TIBCO ActiveMatrix Administrator Server

4. From a console window, run TIBCO Configuration Tool in silent mode.CommandPlatform

TIBCOConfigurationTool -silentMode -wizard.id wizard_idwizard.props build_properties [wizard.target ant_target-name]

Linux, UNIX

TIBCOConfigurationToolc.exe -silentMode -wizard.id wizard_idwizard.props build_properties [wizard.target ant_target-name]

Windows

• wizard_id can be one of the IDs listed in Step 3.• build.properties is a properties file for that wizard. You must customize most properties files before you

run the wizard.• wizard_target is an optional parameter that is used to set a non-default build target. By default, the

build.xml file of the wizard you invoke is used.

ExampleRunning in Silent Mode

TIBCOConfigurationToolc.exe -silentMode -wizard.id com.tibco.tct -wizard.props

C:/build.properties -wizard.target end-to-end


Configuration | 55

Using TIBCO Configuration Tool Scripts and Property FilesYou save and edit property files that TIBCO Configuration Tool generates, and perform configuration withthose files by using an Ant script.

The generated scripts and structures of ActiveMatrix 3.1.5 , 3.2.0, and 3.3.0 are different, Script propertiesof ActiveMatrix 3.1.5 , 3.2.0, and 3.3.0 are also different. Load the data.xml file of ActiveMatrix 3.1.5to TIBCO Configuration Tool version 3.3.0 or later and generate the scripts from there.

When you run TIBCO Configuration Tool, the tool creates property files and Ant build script files and storesthem in the following location:

CONFIG_HOME/tct/subfolder/date-time/scripts.• Table 12: Configuration Subfolders and Files on page 56 lists the subfolders in CONFIG_HOME and includes

information about the files in each folder.• Table 13: Configuration Settings on page 56 lists some of the properties that you might change in the

properties file.

Table 12: Configuration Subfolders and Files

FilesSubfolder

build.xml - Ant build file

build.properties - Driver specification and JAR file location

tpclshells


build.properties - Property settings and locations of configuration files

tibcohost

tibcohost-instance.properties - TIBCO Host instance configuration


build.properties - Property settings and locations of configuration and propertyfiles

admin

integration_create_admin.xml - ActiveMatrix Administrator server bootstrapconfiguration

admin-instance.properties - ActiveMatrix Administrator server configuration

admin-tibcohost-instance.properties - TIBCO Host instance configuration thatmanages the node running the ActiveMatrix Administrator server

admin-envt-data.xml - ActiveMatrix development environment configuration

cl_logservice_data.xml - Log service configuration file

cl_payloadservice_data.xml - Payload service configuration file

governance_integration_data.xml - Monitoring service configuration file

Table 13: Configuration Settings

DescriptionProperty

ActiveMatrix installation locationTIBCO_HOME

ActiveMatrix runtime configuration data foldertibco.config.mgmt.home

ActiveMatrix Administrator machine nametcs.host


56 | Configuration

DescriptionProperty

ActiveMatrix Administrator server base URLadminURL

ActiveMatrix Administrator enterprise nameadmin.enterprise.name

TIBCO Enterprise Message Service server URL for ActiveMatrixAdministrator

admin.ems.url

ActiveMatrix Administrator database URLadmin.db.url

TIBCO Host instance name for ActiveMatrix Administratoradmin.instance.name

th.jmx.host

TIBCO Host instance management portamx.th.hpa.jmx.port

TIBCO Enterprise Message Service server URL for standalone TIBCO Hostinstance

tibcohost.qin.server.url

TIBCO Credential Server URL for standalone TIBCO Host instancetibcohost.trinity.tcs.url

Saving a TIBCO Configuration Tool ConfigurationYou can run a TIBCO Configuration Tool wizard in GUI mode to configure a component, and save thosesettings as a configuration file with an associated script.

About this task

A script that TIBCO Configuration Tool generates only works for the same minor version, even if youinstall other versions later. For example, if you generate a script in 3.2.x, that script uses the 3.2.xfeatures and cannot use 3.3.x features even if 3.3.x is installed.

Procedure

1. Run TIBCO Configuration Tool and select one of the wizards.2. Specify configuration settings.3. On the Session Scripts and Log Folder field of the Summary screen, accept the location of the configuration

folder or click Browse to specify a new location.4. Click Save.

The configuration properties file and script is saved in the specified folder. The default folder isCONFIG_HOME/data/tct/subfolder/date-time/scripts, where• CONFIG_HOME is the folder you specify when you run the TIBCO Configuration Tool in one of the

supported modes.• subfolder depends on the wizard you run.

5. Click OK to complete configuration.

Reusing a TIBCO Configuration Tool ConfigurationAfter you have saved a configuration file, you can run an Ant script to reuse the configuration.

Before you beginInstall and configure Ant on the target machine.


Configuration | 57

About this taskYou can run TIBCO Configuration Tool and reuse the configuration on a different machine and operatingsystem, if you edit the properties files to account for the following differences between the originating machineand the target machine.• Machine name• ActiveMatrix installation location• ActiveMatrix runtime configuration data location• ActiveMatrix enterprise name• Operating systemBecause all the property files specify the machine name, you must always replace the source machine namewith the target machine name.

A script that TIBCO Configuration Tool generates only works for the same minor version, even if youinstall other versions later. For example, if you generate a script in 3.2.x, that script uses the 3.2.xfeatures and cannot use 3.3.x features even if 3.3.x is installed. See Modifying Scripts from EarlierReleases on page 61.

Procedure

1. Make the required changes in the property files.2. If using SSL, edit integration_create_admin_data.xml and update the value of the keyStoreLocation

attribute in the KeyStoreResource target element.3. Open a command line window in the folder that has the properties file for the configuration you want to

reuse. For example, open CONFIG_HOME/tct/pd/<timestamp>/scripts.4. Run ant [-logfile logfilename] –f build.xml end-to-end register-pd-services. The actions occur

in the following subfolders:DescriptionOption

Adds plug-ins to TIBCO_HOME\components\shared\1.0.0\plugins.tpclshells

Creates the tibcohost\hostName data folder, where hostName is the name youspecified for the TIBCO Host instance.

tibcohost

Creates the admin\enterpriseName data folder and the tibcohost\hostName datafolder, where hostName is the name you specified for the TIBCO Host instanceand enterpriseName is the name you specified for the enterprise.

admin

See Using TIBCO Configuration Tool Scripts and Property Files on page 56.

Configure Third-Party Driver PropertiesYou can configure third-party drivers by setting properties in a build.properties file and running a script.

To configure drivers, set the following properties in tpclshells/build.properties:

DescriptionProperty

Package name of the driver. See Table 14: Shell Namesand Versions on page 59.

shell.name

Driver version.shell.version

Driver JAR file location.source.jar.folders

Machine model file.machine.model.location

ActiveMatrix installation location.TIBCO_HOME


58 | Configuration

Table 14: Shell Names and Versions

Shell VersionShell NameDriver

11.1.0.112100com.tibco.tpcl.gen.oracle.jdbcOracle Database 11g

10.2.0.112100Oracle Database 10g

2.0.0.300com.tibco.tpcl.gen.sqlserver.jdbcMicrosoft SQL Server 2.0.0



4.12.55.4130com.tibco.tpcl.gen.db2.jdbc.featureIBM DB2 4.12.55

2.3.63.4130com.tibco.tpcl.gen.db2.jdbc.featureIBM DB2 2.3.63

6.1.0.620com.tibco.tpcl.gen.sonic.jmsJMS Sonic

7.0.0.001com.tibco.tpcl.gen.websphere.jmsJMS WebSphere

5.0.1.510com.tibco.tpcl.gen.jboss.ejbEJB JBoss 5.0.1

8.1.6.1020com.tibco.tpcl.gen.weblogic.ejbEJB WebLogic 8.1.6

9.2.0.1020com.tibco.tpcl.gen.weblogic.ejbEJB WebLogic 9.2.0

10.0.0.1020EJB WebLogic 10.0.0

6.1.0.710com.tibco.tpcl.gen.websphere.ejbEJB WebSphere 6.1.0

7.0.0.710EJB WebSphere 7.0.0

6.0.0.001com.tibco.tpcl.gen.siteminderSiteMinder Agent 6.0.0

12.0.0.001com.tibco.tpcl.gen.siteminderSiteMinder Agent 12.0.0

In most cases, you must modify the folder locations in the following properties.• source.jar.folders• TIBCO_HOME

• machine.model.location

Update the following properties to conform to target operating system path conventions:

DescriptionProperty

Driver JAR file location.source.jar.folders

Installation location.TIBCO_HOME

Machine model file.machine.model.location

Create TIBCO Host Instance PropertiesYou can create a TIBCO instance by editing the appropriate properties in the appropriate files and runninga script.

Use the scripts in the tibcohost folder to create a TIBCO Host instance on a new machine or an additionalTIBCO Host instance on the machine where an ActiveMatrix Administrator server is running.

For creating an instance on a new ActiveMatrix machine, update only the build.properties file. Otherwise,you must modify configuration properties in the tibcohost-instance.properties. For example, to createan additional TIBCO Host instance on the same machine, change the value of the amx.th.hpa.jmx.portproperty.


Configuration | 59

First TIBCO Host Instance

To create a standalone TIBCO Host instance, update the following properties before running the script:

DescriptionPropertyFile Name

TIBCO Host instance nameamx.th.instance.namebuild.properties

TIBCO Host instance machinename

tibcohost.jmx.host

Additional TIBCO Host Instances


TIBCO Host instance nameamx.th.instance.namebuild.properties

TIBCO Host instance managementport

amx.th.hpa.jmx.porttibcohost-instance.properties

Enterprise Name


ActiveMatrix enterprise nametibcohost.enterprise.namebuild.properties

Installation Location

Update the following property when the ActiveMatrix software is not installed in the default location.


ActiveMatrix installation location.TIBCO_HOMEbuild.properties

Configuration Folder Location

Update the following property when using a different configuration data folder location.


ActiveMatrix runtime stateconfiguration location.

tibco.config.mgmt.homebuild.properties

In addition to the changes listed in Additional TIBCO Host Instances on page 60, update the followingproperties to conform to the target operating system path conventions:



tibco.config.mgmt.home

Create ActiveMatrix Administrator Server PropertiesYou can create an ActiveMatrix Administrator server by editing the appropriate properties in the appropriatefiles and running a script.

Machine Name

Update the following properties with the correct machine name:


60 | Configuration


Machine on which ActiveMatrixAdministrator runs.

tcs.hostbuild.properties

ActiveMatrix Administrator serverURL.

adminURLadmin-instance.properties

Enterprise Name

Update the following property if the ActiveMatrix enterprise name has changed.


ActiveMatrix enterprise nameadmin.enterprise.namebuild.properties

Installation Location

Update the following property when the ActiveMatrix software is installed in a different location.



Configuration Folder Location

Update the following property when using a different configuration data folder location.



tibco.config.mgmt.homebuild.properties

Update the following properties in addition to the changes required for machine name to conform to thetarget operating system path conventions.





Modifying Scripts from Earlier ReleasesYou cannot use ActiveMatrix 3.1.5 Configuration Tool scripts with ActiveMatrix 3.2.0 or later, but you canload a script from an earlier release.

Procedure

1. Find the script that you want to modify in your AMX 3.1.5 directory hierarchy.The location depends on the script. For example, look inTIBCO_CONFIG_HOME\data\<wizard>\YYYY-MM-DD-hh-mm-ss\scripts, for example,TIBCO_CONFIG_HOME\data\tct\admin\YYYY-MM-DD-hh-mm-ss\scripts for the Create AdministratorServer wizard. To find TIBCO_CONFIG_HOME, look in for tct.config.home in theTIBCOConfigurationTool.ini file. This file is in TIBCO_HOME/tct/version/

2. When the wizard associated with ActiveMatrix 3.2.0 or later starts, click the Load button and browse tothe ActiveMatrix 3.1.4 script you want to use.


Configuration | 61

Configuration Tool Wizards and ScreensWhen you run TIBCO Configuration Tool in the GUI mode or in console mode, the system prompts you forinformation about the component or components you selected for configuration.

Create Express Developer EnvironmentThe Create Express Developer Environment wizard prompts for minimal configuration information andcreates a host, a node, and an ActiveMatrix Administrator server running on the host. If you want morecontrol over the configuration details, run the Create Administrator Server wizard.

When you select Create Express Developer Environment, a wizard prompts you for information about theAdministrator server and the Enterprise Message Service to be used. When you complete the wizard, it createsan Administrator server, a host named SystemHost, and a node named SystemNode. At runtime, thesecomponents communicate using the Enterprise Message Service server you specify. The following tablesummarizes the information you need when running the wizard.

Options and ActionsFunctionComponent

Provide the name of the communication group withinwhich status messages are exchanged and the name

Administers TIBCO ActiveMatrixapplications and infrastructure.

AdministratorServer

of the Administrator server. Provide communicationproperties for the Administrator server.

Provide configuration details for the EnterpriseMessage Service server.

Propagates status messagesbetween hosts, nodes, and theActiveMatrix Administrator server

Notification andMessaging BusServer

and messages betweenapplications.

Administrator ServerWhen you create an Express Developer Environment, you specify the enterprise name you want to use andthe name of the Administrator server you want to create in the Administrator Server screen.

DescriptionField

Communication group for status messages that are sent between the Administratorserver, the hosts that are bound to the server, and the nodes that are managed by thosehosts.

Default:

Enterprise Name

• amxadmin for ActiveMatrix Administrator

Name of the Administrator server.

Default:

Server Name

• instanceOne for ActiveMatrix Administrator


62 | Configuration

Administrator Server Notification and Messaging Bus ServerThe Administrator Server Notification and Messaging Bus Server screen prompts you for the connectioninformation for one or more TIBCO Enterprise Message Service server instances. The Notification andMessaging Bus servers in your express developer environment are then associated with that server.

You must have access to a running instance of TIBCO Enterprise Message Service Server before you cancomplete this screen. See TIBCO Configuration Tool Requirements on page 49. If you intend to enable SSLcommunications, see Secure Communication Channels on page 42.

DescriptionField

Comma-separated list of machinename:port addresses for a TIBCO Enterprise MessageService server.

Default: machinename:port, where machinename is the host on which TIBCO ConfigurationTool is being executed and port is 7222. The default machinename:port is

Machine Name PortList

tcp://hostname:7222. If the the Enterprise Message Service server is SSL enabled,the hostname will be ssl://hostname:7222.

Username for the TIBCO Enterprise Message Service server. The user must haveadministrator privileges in the TIBCO Enterprise Message Service server. If the user

Username

does not have administrator privileges, configure your TIBCO Enterprise MessageService server as described in Configuring TIBCO Enterprise Message Service Serversfor Non-Admin Users on page 50.

Default: admin.

Password for the TIBCO Enterprise Message Service user.

Default: None.

Password

Related TopicsConfiguring a Trust Store on page 47

To configure a trust store, you can either upload certificates and have TIBCO Configuration Toolcreate the trust store, or you upload a keystore file that contains certificates.

SummaryWith each TIBCO Configuration Tool wizard's summary screen, you can check the configuration that youspecified and see the effects of that configuration. You can click Back to make changes, save the configurationfor use by the silent installer, or click Configure to start the configuration. If you are using the consoleconfiguration tool, you can perform the same actions by typing single-letter commands.

DescriptionField

Folder containing the script configured in the wizard and the log file if the script isexecuted.

Session Scripts andLog Folder

If an Administrator server was configured in the wizard, a link to the URL of theAdministrator server.

Administrator URL

Actions that will be performed when the Configure button is clicked. All actions areselected by default. Clear the checkboxes next to the actions you do not want executed.

Actions


Configuration | 63

DescriptionField

Product applications that will be deployed on the node if one has been configured.All products are selected by default. Clear the checkboxes next to products you donot want deployed.

If you did not deploy the logging and payload services when you created theAdministrator server using the TIBCO Configuration Tool, seeTIBCO_HOME\administrator\version\scripts\logging\readme.txt.

Products to Deploy

Saves the configuration in the location specified in the Session Scripts and Log Folderfield.

Save

Saves the configuration in the location specified in the Session Scripts and Log Folderfield and performs the actions specified in Actions and Products to Deploy.

Configure

Returns to the wizard selector screen.Cancel

Create TIBCO ActiveMatrix Administrator ServerThe Create TIBCO ActiveMatrix Administrator Server wizard is used to configure many aspects of yourserver including the database, authentication method, monitoring, log service, and more.

You can review this wizard documentation before you start the configuration, to decide how you want toset up the server.

The wizard takes 15 minutes or more to complete depending on the configuration options.

Database Requirements

When you run the wizard, specify a database for Administrator server and for several system services. If youare using an external database (and do not use HSQLDB as an external database), set up the external databasebefore you run the wizard.1. Package, install, and configure the database driver using the Configure Third-Party Driver on page 87

wizard.2. Configure the external database.



Required : You must not have the DBA privilege,and you must be assigned to the database schema.

Permissions: Grant the following permissions:

Oracle

grant create session

Required: Set 'read_committed_snapshot' to ONby executing:







64 | Configuration


Permissions: grant db_datareader, db_datawriterto <amx-user> for the <amx-database>.

Required: Configure the database with a 32KB pagesize (instead of the default 4KB page size).

IBM DB2

Permissions: Create dmluser with connectdatabase permission.

3. Start the database server.

If you use an HSQLDB external database, concurrent user access to the Administrator server is notsupported.

Database Requirements For DDL Generator Users

ActiveMatrix 3.3.0 supports a DDL generator utility that you can use before you run TIBCO ConfigurationTool. When you use DDL scripts produced by the DDL generator, you need different database permissionsthan if you do not use DDL scripts. The database user must have connect and resource privileges, and mustnot have DBA privileges. The database user must be assigned to the default schema.

Components Configured by the Create TIBCO ActiveMatrix Administrator Server Wizard

The following table summarizes the components that are configured in the Create TIBCO ActiveMatrixAdministrator Server wizard, their function, and the decisions you must take, the information you mustgather, and actions you must perform before running the wizard.


Provide the name of the communication group withinwhich status messages are exchanged and the name

Administers TIBCO ActiveMatrixapplications and infrastructure.

AdministratorServer

of the Administrator server. Provide communicationproperties for the Administrator server.

Provide configuration details for the TIBCO Hostinstance.

The TIBCO Host instance thatmanages the SystemNode node onwhich the Administrator serverruns.

TIBCO HostInstance

Provide the name and management port of thedevelopment node and the name of the environment

A node on which to deployapplications.

DevelopmentNode

that contains the node. If you intend to complete thetutorials in Administration Tutorials, you must createthe development node, accept the default values forthe environment and node names, and deploy allproduct applications on the developmentnode.Customize the name and management port ofthe node and the name of the environment thatcontains the node.

Provide configuration details for the EnterpriseMessage Service server.

Propagates status messagesbetween hosts, nodes, and theActiveMatrix Administrator server

Notification andMessaging BusServer

and messages betweenapplications.


Configuration | 65


Choose an internal or external database. If you choosean external database, provide configuration detailsfor the database server.

Stores ActiveMatrix Administratorconfiguration data.

Database

Choose a database or LDAP authentication realm.Provide configuration details for the authenticationrealm.

Stores user and group data.AuthenticationRealm

• A database authentication realm stores user andgroup authentication data in a database. Users andgroups in this realm can be edited withinActiveMatrix Administrator. You have the optionto use the same database for authentication andadministration data.

If you choose database, and are using a databasedifferent than the one the ActiveMatrixAdministrator server uses, provide theconfiguration details for the database server. SeeDatabase Requirements on page 64.

• An LDAP authentication realm uses the user andgroup authentication data stored in an LDAPserver. Users and groups in this realm can only beedited with LDAP server management tools.

If you choose an LDAP realm, the LDAP servermust be running.

Choose an autogenerated or external keystore. If youchoose an external keystore, provide configurationdetails for the keystore.

Provides credentials to enablesecure interactions betweenActiveMatrix Administratorservers, hosts, and nodes.

TIBCOCredentialServer

Choose the ActiveMatrix Administrator notificationserver and database or another notification server and

Aggregates monitoring data.MonitoringService

database. If the latter, provide the notification serverand database configuration details according toDatabase Requirements on page 64.

Choose whether the monitoring system shouldcapture enhanced statistics.

Choose the ActiveMatrix Administrator database oranother database. If you are using a database different

Aggregates and stores log entrydata.

Log Service

than the one the ActiveMatrix Administrator serveruses, see Database Requirements on page 64.

Choose the ActiveMatrix Administrator database oranother database. If you do not use the ActiveMatrix

Stores large payloads associatedwith log entries.

Payload Service

Administrator database, see Database Requirementson page 64.

DescriptionField

Check to secure all communication channels with SSL. When you select thischeckbox, the Enable SSL checkbox on the Notification and Messaging Bus Server

Configure to Secure AllCommunication with SSL


66 | Configuration

DescriptionField

and ActiveMatrix Administrator server screens are selected. See SecureCommunication Channels on page 42 for background information.

Default: Cleared.

Administrator ServerThe Administrator Server screen is used to specify the enterprise name and the name of the AdministratorServer instance.

DescriptionField

Communication group for status messages that are sent between the Administratorserver, the hosts that are bound to the server, and the nodes that are managed by thosehosts.

Default:

Enterprise Name

• amxadmin for ActiveMatrix Administrator

Name of the Administrator server.

Default:

Server Name

• instanceOne for ActiveMatrix Administrator

Administrator Server TIBCO Host InstanceEach Administrator server runs on a TIBCO Host instance. You can specify the instance on which the serverwill run, configure server characteristics such as a Windows shortcut, and specify the environment and thenode.

DescriptionField

Name of the machine on which the TIBCO Host instance runs. The value of thisproperty must either be a hostname resolvable through DNS or 0.0.0.0; it cannotbe an IP address.

Default: machineName, where machineName is the machine on which TIBCOConfiguration Tool is being executed.

Machine Name

Management port of the TIBCO Host instance.

Default: 6051.

Port

Select to register the TIBCO Host instance as a Windows service named TIBCOActiveMatrix Admin-enterpriseName-serverName with the startup type Automatic.The service is not started.

Default: Clear.

Register as WindowsService

Select to add a shortcut named TIBCO ActiveMatrixAdmin-enterpriseName-serverName that points to

Create Windows Shortcut

CONFIG_HOME\tibcohost\Admin-enterpriseName-serverName\host\bin\tibcohost.exeto the Windows desktop.

Default: Clear.


Configuration | 67

DescriptionField

Select to create a development environment and node . When selected, theEnvironment Name, Node Name, and Node Management Port fields display.Default: Selected

Create DevelopmentNode

Name of the environment that contains the node.

Default:

Environment Name

• DevEnvironment for ActiveMatrix

Name of the node.

Default:

Node Name

• DevNode for ActiveMatrix

Management port of the node.

Default: 6038.

Node Management Port

Administrator Server Connection SettingsThe Administrator Server Connection Settings screen is used to specify non-default adapters and ports andto enable and configure SSL for the external HTTP port. You can also choose to enable an HTTP load balancer.

DescriptionField

Address of the network adapter on the machine on which the Administratorserver runs. The default is set to 0.0.0.0 so that Administrator will listen on all

Network Adapter

network adapters (including http://localhost and http://hostname). If you leavethe default, clients can connect to the Administrator server using any of theconventions (localhost, IP address, hostname). The value of this property musteither be a hostname resolvable through DNS or 0.0.0.0; it cannot be an IP address.

Management port of the node that runs Administrator server.

Default: Depends on the product you are configuring.

Management Port

Port on which Administrator clients access the Administrator server.

Default: 8120.

External HTTP Port

Length of time before an inactive Administrator GUI login session times out.

Default: 30.

Browser Idle SessionTimeout (m)

Select to secure communication between Administrator server and clients withSSL. When selected, the Self-Signed Certificate and Imported Certificate radiobuttons display.

Default: Cleared.

Enable SSL for ExternalHTTP Port

Indicates that clients can identify the Administrator server with a self-signedcertificate. When selected, it uses the self signed certificate from the samplesfolder.

Self-Signed Certificate

Do not use a self-signed certificate in production environments.

Default: Selected.


68 | Configuration

DescriptionField

Indicates that clients can identify the Administrator server with a certificateimported into the Administrator server. When selected, the Keystore fields andFetch Keystore button are enabled.

Imported Certificate

Location of the keystore to import.Keystore Location

Type of keystore.Keystore Type

Password that protects the keystore.Keystore Password

When you click this button, you can select one of the available key aliases, specifythe keystore password, and click Verify Keystore to verify that the passwordyou entered is valid.

Fetch Keystore

Administrator Server Internal HTTP Port

DescriptionField

Number of the internal Administrator HTTP port.

Default: 19767.

Internal HTTP Port

Select to secure communication between Administrator server and hosts with SSL.

Default: Cleared.

Enable SSL

Administrator Server Notification and Messaging Bus ServerThe notification server is an Enterprise Message Service server that delivers status messages sent by hostsand nodes to the Administrator server.

As part of configuration, set up the notification and messaging bus server.To use SSL, see SecureCommunication Channels on page 42. To enable SSL communications, see SSL Requirements on page 50.

DescriptionField






Username


Default: admin.


Default: None.

Password


Configuration | 69

DescriptionField

Select to enable the database server for SSL. When checked, the SSL KeystoreConfiguration fields are enabled.

Default: Cleared.

TIBCO EnterpriseMessage Serviceserver is SSLenabled

This is an example of a scenario when the TIBCO Enterprise Message Service server is SSL enabled.In this example, Enterprise Message Service server is configured with SSL forGenericConnectionFactory. Edit the factories.conf and include the following:

[GenericConnectionFactory]type = genericurl = ssl://7243ssl_verify_host = enabledssl_trusted = EMS_HOME/6.3/samples/certs/server_root_cert.pem

In the tibemsd.conf, include the following:listen = ssl://7243authorization = enabledssl_server_identity = EMS_HOME/6.3/samples/certs/server.cert.pemssl_server_key = EMS_HOME/6.3/samples/certs/server.key.pemssl_password = passwordssl_server_trusted = EMS_HOME/6.3/samples/certs/server_root.cert.pem

DescriptionField

Invokes a wizard to import certificates from a server and create the trust store.Create a TrustStore...

Invokes a dialog to navigate to a keystore file.Browse

Location of the keystore.Keystore Location

Type of the keystore: JKS or JCEKS.

Default: JKS.

Keystore Type


Adminstrator Server Enterprise Message Service Connection FactoryThis screen helps you select a connection factory configured for fault-tolerance. This must match with yourinput of multiple Enterprise Message Service servers.

DescriptionField

Select one of the following:Connection FactoryName • GenericConnectionFactory

• QueueConnectionFactory• TopicConnectionFactory• FTTopicConnectionFactory• SSL TopicConnectionFactory• SSL QueueConncectionFactory• FTQueueConnectionFactory


70 | Configuration

Administrator Server Database DetailsYou can choose to use the Administrator server with a default in-process database during development. Inproduction systems, use an external database instead. This screen allows you to configure database details.

DescriptionField

Select to use the embedded in-memory database, or clear to use an external database.If cleared, the database configuration fields display.

Default: Selected.

Use DefaultIn-Process Database

If you decide to use a non-default database, the wizard prompts you for database details.

Use the default embedded database only during development.

If you are using an external database, see Database Requirements on page 64. To enable SSL communications,see Secure Communication Channels on page 42 and SSL Requirements on page 50.

The properties that the wizard sets in the build.properties file depend on the context in which theprompts are displayed. By default, specify the properties for the Administrator Server database andthe information is then used for the Notification Service database, the Log Service database, and thePayload Service database. You can, however, overwrite the values for the Notification Service, LogService, and Payload Service, and you can change them in the build.properties file.

DescriptionField

Driver for the external database:Database Driver• TIBCO enabled JDBC driver for Oracle 10.2.0• TIBCO enabled JDBC driver for Oracle 11.1.0• TIBCO enabled JDBC driver for Microsoft SQL Server 2.0.0• TIBCO enabled JDBC driver for Microsoft SQL Server 3.0.0• TIBCO enabled JDBC driver for Microsoft SQL Server 4.0.0• TIBCO enable JDBC driver for IBM DB2 4.12.55• TIBCO enabled JDBC driver for IBM DB2 2.3.63

Default: JDBC driver provided for HSQL 1.8.400.

URL of the external database.Database URL

Default: jdbc:hsqldb:hsql://localhost:1234/amx.

External database username.

Default: sa.

Username

External database password.

Default: None.

Password

Maximum number of database connections to allocate.

Default: 30.

Max Connections

Check to enable the database server for SSL. When checked, the SSL KeystoreConfiguration fields are enabled.

Default: Cleared.

Database Server isSSL Enabled


Configuration | 71

DescriptionField





Default: JKS.

Keystore Type




Administrator Server Authentication RealmAdministrator stores information about users and groups in an authentication realm. You can let Administratorstore the information in a database or in LDAP. TIBCO Configuration Tool will then prompt you for moreinformation about the authentication realm.

DescriptionField

Authentication Realm

Type of authentication realm:Realm Type• Database - See Administrator Server Database Authentication Realm on page 72• LDAP - See Administrator Server LDAP Authentication Realm on page 74

Default: Database.

Superuser Credentials

Name of the initial superuser.

Default: root.

Username

Password of the superuser.

Default: t.

Password

In the properties file, this value is obfuscated.

Administrator Server Database Authentication RealmIf you select a database authentication realm, Administrator stores information about users and groups in adatabase. You can select the same database as the Administrator server, or configure a different database.

DescriptionField

Select if the database authentication realm should use the same database as theAdministrator server. If cleared, the database configuration fields display.

Default: Cleared.

Use ActiveMatrixAdministrator ServerDatabase



72 | Configuration




DescriptionField






Default: sa.

Username


Default: None.

Password


Default: 30.

Max Connections


Default: Cleared.


DescriptionField





Default: JKS.

Keystore Type



Configuration | 73



Administrator Server LDAP Authentication RealmIf you select an LDAP authentication realm, Administrator stores information about users and groups inLDAP. You are prompted for the user and password, name resolution context, and server URLs. You canalso specify the user search configuration and optional group information.

If you intend to enable SSL communications, see Secure Communication Channels on page 42and SSLRequirements on page 50.

DescriptionField

Distinguished name or name of the superuser to be used to connect to the server.

Default: uid=Manager,ou=people,dc=example,dc=com.

Bind DN Name

LDAP server password.

Default: None.

Password

Factory object that provides the starting point for resolution of names within the LDAPserver.

Default: com.sun.jndi.ldap.LdapCtxFactory

Context Factory

Comma-separated list of URLs for an LDAP server. To achieve fault tolerance, youcan specify multiple URLs. For example, server1.example.com:686,server2.example.com:1686.

Default: machinename:389, where machinename is the machine on which TIBCOConfiguraton Tool is being executed.


You can retrieve the base DN (distinguished name) of the LDAP server.Fetch DN

User Search Configuration

Base distinguished name from which the search starts.

Default: ou=people,ou=na,dc=example,dc=org

User Search BaseDN (optional)

Expression used for searching a user. For example: (CN=%U). '%U' is replaced by theusername being searched for. You can define any complex filter such as(&(cn=%U)(objectClass=account)).

Default: (&(uid={0})(objectclass=person)).

User SearchExpression(optional)

Name of the attribute in the user object that contains the user's name.

Default: uid.

User Attribute withUser Name(optional)

Time to wait for a response from the LDAP server. A values less than 90 seconds yieldsin a warning message.

Default: 30000.

Search Timeout (ms)


74 | Configuration

DescriptionField

Select to follow LDAP referrals. If you select this check box, requests to LDAP can beredirected to another server. Use this check box to indicate that the LDAP informationmight be available at another location, or possibly at another server or servers.

Ask your LDAP administrator whether LDAP referrals are used in your domain.

Follow Referrals

DescriptionField

Specifies how a user’s group memberships are found. Administrator uses groupinformation when a user, once authenticated, performs other activities in the system.Options:

Group Indication(optional)

• Group has users - List of users that belong to the group. When selected, the GroupAttribute with User Names field is enabled.

• User has groups - List of groups to which the user belongs. When selected, theUser Attribute with Group Names field is enabled.

Default: Group has users.

Base distinguished name from which the search for the group starts.

Default: ou=groups,ou=na,dc=example,dc=org.

Group Search BaseDN (optional)

Search by matching this expression against potential groups.

Default: cn={0}.

Group SearchExpression(optional)

Name of the attribute in the group object containing its users.

Example: uniqueMember (OpenLDAP) or member (ActiveDirectory).

Group Attributewith User Names(optional)

Default: uniqueMember.

Name of the attribute in the group object that contains the name of the group.

Example: cn (OpenLDAP) or sAMAccountName (ActiveDirectory).

Group Attributewith Group Name(optional)

Default: cn.

Name of the attribute in the group object that contains its subgroups.

Example: uniqueMember (OpenLDAP) or member (ActiveDirectory).

Group AttributeSubgroup Names(optional)

Default: uniqueMember.

Name of the attribute in the user object that lists the groups to which the user belongs.

Default: None.

User Attribute withGroup Names

When searching the group, indicate whether to traverse into the subtree or to searchonly under the group base distinguished name.

Default: Selected.

Group Search ScopeSubtree

DescriptionField

LDAP Realm


Configuration | 75

DescriptionField

Select to have the search include the entire subtree starting at the base DN. Otherwise,search only the nodes one level below the base DN.

Default: Selected.

User Search ScopeSubtree

Value of Simple Authentication and Security Layer (SASL) authentication protocol touse. Values are implementation-dependent. Some possible values are simple, none,md-5.

SecurityAuthentication

Default: simple.

LDAP Authentication

Template by which the User DN, used to connect to the LDAP server, is generated.Because the full DN is always supplied, the template should always be 0 (zero).

Default: uid={0},ou=people,ou=na,dc=org.

User DN Template(optional)

Optional list of user attributes to retrieve from the LDAP directory duringauthentication.

Default: Empty (no additional attributes will be retrieved for the user).

User AttributesExtra (optional)

Select to enable the LDAP server for SSL. When selected, the SSL KeystoreConfiguration fields are enabled.

Default: Cleared.

LDAP Server is SSLEnabled

DescriptionField





Default: JKS.

Keystore Type




Administrator Server TIBCO Credential Server DetailsYou can specify credential server details to identify the TIBCO Credential Server that you want to use withyour Administrator server installation.

DescriptionField

Address of the network adapter on the machine on which TIBCO Credential Serverruns. The default is set to 0.0.0.0 so that TIBCO Credential Server will listen on all

Network Adapter

network adapters (including http://localhost and http://hostname). With the default


76 | Configuration

DescriptionField

setting, clients can connect to TIBCO Credential Server using any of the conventions(localhost, IP address, hostname). The value of this property must either be a hostnameresolvable through DNS or 0.0.0.0; it cannot be an IP address.

Default: 0.0.0.0.

Management port number of the node, SystemNode, that runs TIBCO CredentialServer.

Default: 6041.

Port

User identifier for TIBCO Credential Server clients.

Default: user1.

Username

Password for the client.Password

Administrator Server TIBCO Credential Server KeystoreIf you enable SSL, you can use Administrator server with an auto-generated keystore or specify keystoreinformation.

DescriptionField

Select to generate a TIBCO Credential Server keystore will be generated. When selected,the Common Name field displays.

Default: Selected.

Auto-generatedKeystore

Issuer name of TIBCO Credential Server.

Default: amxadmin.

Common Name

Check to provide TIBCO Credential Server keystore information. When selected, thekeystore fields display.

Default: Cleared.

Provided Keystore


Type of keystore.

Default: Autodetect.

Keystore Type

Password for the keystore.Keystore Password

Name of the alias used to access the identity.Key Alias

Password for the alias.Key Password


Configuration | 77

Administrator Server Monitoring Service Notification ServerThe monitoring service is an ActiveMatrix application that aggregates performance data from runtime object,that is, TIBCO Host instances and nodes. TIBCO Configuration Tool deploys the monitoring service applicationon the SystemNode node, which is the node that runs the Administrator server.

DescriptionField

Select if you want the monitoring service to use the same notification server as theAdministrator server. If cleared, the wizard allows you to configure the monitoringservice explicitly.

Default: Selected.

Use ActiveMatrixAdministratorNotification Server

As part of configuration, set up the notification and messaging bus server.To use SSL, see SecureCommunication Channels on page 42. To enable SSL communications, see SSL Requirements on page 50.

DescriptionField






Username


Default: admin.


Default: None.

Password


Default: Cleared.


This is an example of a scenario when the TIBCO Enterprise Message Service server is SSL enabled.In this example, Enterprise Message Service server is configured with SSL forGenericConnectionFactory. Edit the factories.conf and include the following:

[GenericConnectionFactory]type = genericurl = ssl://7243ssl_verify_host = enabledssl_trusted = EMS_HOME/6.3/samples/certs/server_root_cert.pem

In the tibemsd.conf, include the following:listen = ssl://7243authorization = enabledssl_server_identity = EMS_HOME/6.3/samples/certs/server.cert.pemssl_server_key = EMS_HOME/6.3/samples/certs/server.key.pem


78 | Configuration

ssl_password = passwordssl_server_trusted = EMS_HOME/6.3/samples/certs/server_root.cert.pem

DescriptionField





Default: JKS.

Keystore Type




Administrator Server Monitoring Service DatabaseThe monitoring service is an ActiveMatrix application that aggregates performance data from runtime objects.The monitoring service application is deployed on SystemNode, the node that runs the Administrator server.

DescriptionField

Select to have the monitoring service use the same database as the Administrator server.If cleared, the database fields display and let you configure a non-default database.

Default: Selected.

UseActiveMatrixAdministratorServer Database





DescriptionField



Configuration | 79

DescriptionField





Default: sa.

Username


Default: None.

Password


Default: 30.

Max Connections


Default: Cleared.


DescriptionField





Default: JKS.

Keystore Type




Administrator Server Log Service DatabaseA log service is a TIBCO ActiveMatrix application that offers logging services. The log service application isdeployed in the environment SystemEnvironment on SystemNode, the node that runs the Administratorserver. A log service receives log entries sent to a JMS destination and stores the entries in a database.

If you did not deploy the logging and payload services when you created the Administrator server using theTIBCO Configuration Tool, see TIBCO_HOME\administrator\version\scripts\logging\readme.txt.

DescriptionField

Select to have the log service use the same database as the Administrator server. Ifcleared, the database fields display.

Default: Selected.

Use ActiveMatrixAdministratorServer Database


80 | Configuration





DescriptionField






Default: sa.

Username


Default: None.

Password


Default: 30.

Max Connections


Default: Cleared.


DescriptionField





Default: JKS.

Keystore Type


Configuration | 81

DescriptionField




Administrator Server Payload Service DatabaseA payload service supports archiving, persisting and retrieving large size payload data. It is an independentservice and does not depend on a log service. However, a log record sent to a log service can include a payloadURL field to link a log message and payload data. You can store payload data in the same database used byAdministrator server or use another database.

If you did not deploy the logging and payload services when you created the Administrator server using theTIBCO Configuration Tool, see TIBCO_HOME\administrator\version\scripts\logging\readme.txt.

DescriptionField

Select to have the payload service use the same database as the Administrator server. Ifcleared, the database configuration fields display to let you specify database information.

Default: Selected.

UseActiveMatrixAdministratorServer Database





DescriptionField






82 | Configuration

DescriptionField


Default: sa.

Username


Default: None.

Password


Default: 30.

Max Connections


Default: Cleared.


DescriptionField





Default: JKS.

Keystore Type




SummaryWith each TIBCO Configuration Tool wizard's summary screen, you can check the configuration that youspecified and see the effects of that configuration. You can click Back to make changes, save the configurationfor use by the silent installer, or click Configure to start the configuration. If you are using the consoleconfiguration tool, you can perform the same actions by typing single-letter commands, as prompted.

DescriptionField


Session Scripts andLog Folder

If an Administrator server was configured in the wizard, a link to the URL of theAdministrator server.

Administrator URL

Actions that will be performed when you click the Configure button. All actions areselected by default. Clear the check boxes next to the actions you do not want executed.

Actions


Configuration | 83

DescriptionField

Product applications that will be deployed on the node if one has been configured.All products are selected by default. Clear the check boxes next to products you donot want deployed.

If you do not deploy the logging and payload services when you created theAdministrator server using the TIBCO Configuration Tool, seeTIBCO_HOME\administrator\version\scripts\logging\readme.txt.

Products to Deploy

Saves the configuration in the location specified in the Session Scripts and Log Folderfield.

Save

Saves the configuration in the location specified in the Session Scripts and Log Folderfield and performs the actions specified in Actions and Products to Deploy.

Configure

Returns to the wizard selector screen.Cancel

Create TIBCO Host InstanceA TIBCO Host instance is one of the central components of any product in the TIBCO ActiveMatrix familyof products. You can create an instance explicitly and give custom information about the instance, associatednotification server, and associated Administrator server.

If you create a TIBCO Host instance, you cannot use that instance with an older version of theAdministrator server.

DescriptionField

Select to secure all communication channels with SSL. When you select thischeckbox, the Enable SSL checkbox on the Notification and Messaging Bus Server

Configure to Secure AllCommunication with SSL

and ActiveMatrix Administrator server screens are selected. See SecureCommunication Channels on page 42 for background information.

Default: Cleared.

TIBCO Host InstanceWhen you create a TIBCO Host instance, you are first prompted for the basic information that includes thename, enterprise and machine name, and behavior as a Windows application.

DescriptionField

Name of the TIBCO Host instance. The name must be unique within the enterprise.

Default: None.

Name

Name that defines a communication group for status messages sent betweenActiveMatrix Administrator server and the hosts that are bound to the server.

Default: amxadmin.

Enterprise Name

Name of the machine on which the TIBCO Host instance runs.

Default: hostname, where hostname is the machine on which TIBCO Configuration Toolis being executed.

Machine Name

Management port of the TIBCO Host instance.

Default: 6001.

Management Port


84 | Configuration

DescriptionField

Select to register the TIBCO Host instance as a Windows service named TIBCOActiveMatrix instanceName, where instanceName is the name you specified in the Namefield, with startup type Automatic. The service is not started.

Default: Cleared.

Register asWindows Service

Select to create a shortcut named instanceName on the Windows desktop that points toCONFIG_HOME\tibcohost\instanceName\host\bin\tibcohost.exe and launchesthe TIBCO Host instance.

Default: Cleared.

Create WindowsShortcut

TIBCO Host Instance Notification ServerWhen you create a standalone TIBCO Host instance, you can specify an associated notification server. Thisnotification server can be the same server as that used by the Administrator, or you can define a differentnotification server.

The Notification Server is an Enterprise Message Service server that performs two essential system functionswithin the TIBCO ActiveMatrix platform. It delivers status messages sent by hosts and nodes to theAdministrator server.

See TIBCO Configuration Tool Requirements on page 49. If you intend to enable SSL communications, seeSecure Communication Channels on page 42.

DescriptionField






Username


Default: admin.


Default: None.

Password


Default: Cleared.


DescriptionField




Configuration | 85

DescriptionField



Default: JKS.

Keystore Type




TIBCO Host Instance Administrator ServerWhen you create a TIBCO Host instance, you can immediately bind it to an Administrator server and specifyconnection information for that server, or choose not to bind the TIBCO Host instance to an Administratorserver. You can assign the host to all environments. You can enable the connection for SSL.

DescriptionField

Select to bind the TIBCO Host instance to an Administrator server. When selected,the Administrator server configuration fields are enabled.

Default: Selected.

Bind toAdministratorServer

Name of the machine on which the Administrator server is running. The value of thisproperty must either be a hostname resolvable through DNS or 0.0.0.0; it cannot bean IP address.

Machine Name

Browser port used to access the Administrator server.

Default: 8120.

Port

ID of the initial superuser.

Default: root.

Username


Default: t.

Password

By default, a host is assigned to all environments. Uncheck this check box to assignthe host to no environment initially, and to explicitly assign the host to selectedenvironments after configuration is complete.

Assign this Host toAll Environments

Select to enable the Administrator server internal port (see Administrator ServerInternal HTTP Port on page 69) for SSL. When selected, the SSL Keystore Configurationfields are enabled.

AdministratorServer is SSLEnabled

Click Test Connection to check whether the host can connect to the specifiedAdministrator server.

Test connection

DescriptionField




86 | Configuration

DescriptionField



Default: JKS.

Keystore Type


SummaryEach TIBCO Configuration Tool wizard's summary screen allows you to check the configuration that youspecified and see the effects of that configuration. You can click Back to make changes, save the configurationfor use by the silent installer, or click Configure to start the configuration. If you are using the consoleconfiguration tool, you can perform the same actions by typing single-letter commands, as prompted.

The Summary screen displays the following information:

DescriptionField


Session Script andLog Folder

Select this option to create a TIBCO instance.Create TIBCOInstance

Select this option to launch a TIBCO instance.Launch TIBCOInstance

Select this option to register a TIBCO instance with the Administrator server.Register TIBCOInstance to theAdministratorServer

Configure Third-Party DriverYou can package a third-party driver into a feature and upload the feature with the Configure Third-PartyDriver wizard. After the feature has been uploaded, you can add it to a node. See Administration.

When you select the Configure Third-Party Driver wizard, you are prompted for information about the driveritself and for the driver JAR files.

Third-Party Driver DetailsThe third-party driver details screen is used to provide detailed information about the driver you want toadd to Administrator and install on nodes in your environment.

DescriptionField

Type of driver being configured: JDBC, JMS, SiteMinder.

Default: JDBC.

Driver Type

Supported drivers:Driver• JDBC

– TIBCO enabled JDBC driver for Microsoft SQL Server 4.0.0– TIBCO enabled JDBC driver for Microsoft SQL Server 3.0.0– TIBCO enabled JDBC driver for Microsoft SQL Server 2.0.0. ( ActiveMatrix

Administrator does not support this version.)


Configuration | 87

DescriptionField

– TIBCO enabled JDBC driver for Oracle 10.2.0– TIBCO enabled JDBC driver for Oracle 11.1.0– TIBCO enabled JDBC driver for IBM DB2 2.3.63 ( ActiveMatrix Administrator

and ActiveMatrix JDBC resource templates do not support this version.)– TIBCO enabled JDBC driver for IBM DB2 4.12.55

• JMS

– TIBCO enabled JMS client for Sonic 6.1.0– TIBCO enabled JMS client for WebSphere 7.0.0. Support for WebSphere MQ

6.0 is based on the backward compatibility of the WebSphere MQ 7.0 clientlibrary. When a JMS binding is configured with JMS topics and needs to workwith WebSphere MQ 6.0, you must provide the 7.0.1.3 version of the clientlibrary.

• SiteMinder

– TIBCO-enabled SiteMinder SDK libraries for SiteMinder Agent 6.0.0– TIBCO-enabled SiteMinder SDK libraries for SiteMinder Agent 12.0.0

Third-Party Driver JAR FolderWhen you configure a third-party driver or other feature, you are prompted for the folder that contains theJARs to deploy to the Administrator server.

DescriptionField

Folder containing the driver JARs to deploy to the Administrator server.JAR Folder

source.jar.folders

Third-Party Driver Summary

After all your selections, the Third-Party Driver Summarty page is displayed.

DescriptionField

Specify a folder for session logs and script files or accept the default.Sessions Scripts and Log Folder

Select this option to configure the third-part driver. Click Save to savethe configuration.

Configure Third-Party Driver

Replicate TIBCO ActiveMatrix Administrator ServerIn a production environment, you can set up your system to include a replica Administrator server on asecond machine. Requests can be processed by either server. If one server is unavailable, the other server canprocess requests.

Overview

In TIBCO ActiveMatrix 3.3, you can replicate an Administrator server on a second machine by running TIBCOConfiguration Tool. Before you run the TIBCO Configuration Tool wizard that performs replication, youmust set up the source environment and the destination requirement.


88 | Configuration

Shared File System Requirements and Overview

TIBCO Configuration Tool needs only read or write access for the shared file system. However, you shoulduse a highly available filesystem in production environments. Consider using a SAN (storage area network)solution for shared folders and files. Place the TIBCO Administrator database on the SAN as well. Yourstorage needs depend on the number of DAA files you upload, on the number of application instances inuse, and on the number of nodes you deploy the applications to.

After setup of the replica server, TIBCO Administrator reads from or writes to the shared file system eachtime it performs one of the following tasks:

• Lifecycle action for an application, such as create, delete, deploy, undeploy, start, stop, or upload DAAfiles.

• Lifecycle action for resource instances (installation)• Changes to node features or logging configuration• Startup of a runtime node

In a steady state, when no deployment is being performed and the applications are running, TIBCOAdministrator does not read from or write to the shared filesystem.

If the shared file system is not available while deploying, the deployment task fails. To recover, retry the task.If you are using a SAN solution, this problem does not occur; only a highly available storage solution supportshigh availability for replicated TIBCO Administrator server setups.

Setting Up Your Environment for Replication

Before you run TIBCO Configuration Tool for replication, you must set up your environment.1. Install and configure Ant on both machines.2. Set up an external database and use TIBCO Configuration Tool to configure the third-party driver for the

corresponding database.3. Set up a shared network drive on each machine. The shared network location must be the same on both

machines. For example, if you create a network drive or folder on Machine 1 and map it to x:/shared ,the shared drive or folder must be mapped to x:/shared as well.

On Windows 7 and Windows 2008, if you run the ActiveMatrix Administrator on a replicated setupas a Windows NT service:• Ensure that you use the UNC path while setting up replication using TIBCO Configuration Tool.• Also ensure that the "Log In" credentials for the Windows NT service is set to the credentials that

were used to create the mapped drive.

Machine 1 - Set up the first Administrator server on machine 1 by using the Create TIBCO ActiveMatrixAdministrator Server wizard.1. Install and configure your Administrator server and note down the following information.

– TIBCO_HOME location– CONFIG_HOME location– Any passwords you provide.

2. On Machine 1, change the staging area folder location as follows.a. Copy the folder CONFIG_HOME/admin/enterprise_name/shared to a location accessible from Machine

2.b. To let the Administrator server on Machine 1 know about the new location of the shared folder, Open

a command prompt at TIBCO_Home\administrator\3.3\scripts.c. Run the following commands to update the folder information and restart the system node.

ant -f sharedWorkFolder_build.xml -Dadmin.shared.folder="NEW SHARED FOLDER LOCATION"

-Dconfig.home="CONFIG_HOME" -Denterprise.name="ENTERPRISE_NAME"


Configuration | 89

d. Restart the SystemNode node. FromCONFIG_HOME/tibcohost/Admin-enterprise_name-instance_name/host/bin, run the following commands.tibcohost.exe stopNodes -nodeName SystemNode tibcohost.exe startNodes -nodeName SystemNode

Machine 2 - Replicate the Administrator server on Machine 2.1. Run the installer, specifying the same TIBCO_HOME location as Machine 1 is using.2. On Machine 1, copy the content of CONFIG_HOME/tct/keystore and put it in the same folder on Machine

2. Create the folder if it does not exist.3. Launch TIBCO Configuration Tool and select the same CONFIG_HOME as was used on Machine 1.4. Configure the same third-party driver as you did on Machine 1.5. When TIBCO Configuration Tool returns to the wizard selection screen, click Replicate TIBCO

ActiveMatrix Administrator Server and configure the replica server by responding to the wizard prompts.a. In the Remote Administrator Details screen, enter the information to connect to the first Administrator

server. This information is used to fetch the current configuration.b. When you click Next, Machine 2 settings are validated. As part of validation, the wizard checks that.

– Both machines use the same CONFIG_HOME.– The shared folder is accessible and contains valid data.– The first administrator server is using an external database.

c. When validation is successful, you can provide a unique host name and node name for the replicaserver on the next screen.

The wizard displays the current Administrator server configuration. You cannot edit the configuration.

d. Enter passwords when prompted.e. After entering the configuration details, click Configure to replicate the Administrator server.

The TIBCO Configuration Tool Replicate TIBCO ActiveMatrix Administrator Server wizard doesnot show the configuration details for Monitoring, Logging, and Payload services. If those servicesare configured and deployed on the first Administrator server, they are automatically deployedon the replica server as part of the replication process.

While planning replication, ensure that both the Administrator servers have the same set of softwareversions including the hotfixes that were applied before upgrading to ActiveMatrix 3.3.0.

When you log in to one of the Administrator servers (or access the load balancing URL), you see the followingsystem setup:• Two hosts exist in the Infrastructure > Hosts screen.• Two nodes exist in the SystemEnvironment environment in the Infrastructure > Nodes screen.After completing the setup, requests can be processed by either server. If one server is unavailable, the otherserver can process requests.

Remote Administrator Server DetailsThe Remote Administrator Server Details screen is used to specify the machine name and port for the primaryserver. You must also specify the username and password. If you configured the primary server with SSL,you must perform SSL configuration for the replica server as well.

DescriptionField

Name of the machine on which the primary Administrator server runs. The valueof this property must a hostname resolvable through DNS or an IP address.

Machine Name

Management port that the primary Administrator server is using.

Default: 8120

Port


90 | Configuration

DescriptionField

User name of the administrator of the primary Administrator server. This usermust be a super user. This credential is used to access the first admin server to

Username

get the current configuration. Only super user is allowed to query the currentconfiguration.

Default: root

Specify the password of the administrator of the primary Administrator server.Password

If the primary Administrator server is SSL enabled, select this check box so thatTIBCO Configuration Tool uses SSL to connect to the primary Administrator

Administrator server isSSL enabled

server. If you select the check box, you are prompted for keystore configurationinformation.

Click this button to verify that TIBCO Configuration Tool can access the serveryou specified using the username and password you specified.

Test Connection

DescriptionField





Default: JKS.

Keystore Type


Create Replicated Instance Validation InfoThe Create Replicated Instance Wizard Validation Info screen appears only if your system setup meets allrequirements.

The requirements are listed in Setting Up Your Environment for Replication on page 89.

Administrator Server Configuration DetailsYou must specify a host name and node name for your replica server.

DescriptionField

Displays the enterprise name of the remote Administrator server. You cannotchange the enterprise name; the remote server and the replica server must be inthe same enterprise.

Enterprise Name

Name of the SystemHost instance that will be associated with the replica server.The host name must be unique. You cannot use the name you used for the hostassociated with the remote Administrator server.

Default: SystemHostReplica

Host Name

Name of the SystemNode instance to be associated with the replica server. Thenode name must be unique. You cannot use the name you used for the nodeassociated with the remote Administrator server.

Default: SystemNodeReplica

Node Name


Configuration | 91

Administrator Server TIBCO Host ConfigurationAs part of the replica server setup, specify the machine and port for the TIBCO host on which the replicaserver runs. This information is for the local machine, not the remote machine.

DescriptionField

Machine on which the TIBCO Host instance runs.Machine

Port for the TIBCO Host instance to communicate with other services in theenvironment.

Port

Select to register the TIBCO Host instance as a Windows service named TIBCOActiveMatrix Admin-enterpriseName-serverName with startup type Automatic. Theservice is not started.

Default: Cleared.

Register as WindowsService

Select to add a shortcut named TIBCO ActiveMatrixAdmin-enterpriseName-serverName that points to

Create Windows Shortcut

CONFIG_HOME\tibcohost\Admin-enterpriseName-serverName\host\bin\tibcohost.exeto the Windows desktop.

Default: Cleared.

Administrator Server Connection Settings

DescriptionField

Address of the network adapter on the machine on which the Administratorserver runs. The default is set to 0.0.0.0 so that Administrator listens on all

Network Adapter


Management port of the node that runs Administrator server.

Default: 6021.

Management Port

Port on which Administrator clients access the Administrator server.

Default: 8120.

External HTTP Port

Select to secure communication between the Administrator server and clientswith SSL. When selected, the Self-Signed Certificate and Imported Certificateradio buttons display.

Default: Same as for remote server.


Indicates that the Administrator server identifies itself to clients with a self-signedcertificate generated by TIBCO Credential Server.



Default: Same as for remote server.

Indicates that the Administrator server identifies itself to clients with a certificateimported into the Administrator server. When selected, the Keystore fields andFetch Keystore button are enabled.



92 | Configuration

DescriptionField





Fetch Keystore

Administrator Server Notification and Messaging Bus ServerThe notification server is an Enterprise Message Service server that delivers status messages sent by hostsand nodes to the Administrator server.

This screen displays the Enterprise Messaging Service server details used by the first Administrator server.You cannot edit the configuration, except for the Password field. If SSL is enabled in the first admin serverthe SSL settings are displayed as well, but are not editable.

Click Test Connection to make sure that they can connect to EMS from the replica administrator machine.

Administration Server Database DetailsThe administrator server that you are replicating must be set up to use an external database. This screendisplays the information about the external database used by the first admin server. You cannot change thisinformation for the replica server.

Click Test Connection to make sure you can connect to the database from the replica machine.

DescriptionField






Default: sa.

Username


Default: None.

Password


Default: 30.

Max Connections


Configuration | 93

DescriptionField

Select to enable the database server for SSL. When selected, the SSL KeystoreConfiguration fields are enabled.

Default: Cleared.


Administrator Server Database Authentication Realm DetailsIf you selected a database authentication realm on the remote server, both Administrator server instanceswill store information about users and groups in a database. This screen displays connection information forthe database you set up from the remote server.

You can review connection information in this screen, then enter the password for the specified database andclick Test Connection.

Administrator Server Configuration LDAP Authentication RealmIf you select an LDAP authentication realm when you configure the remote Administrator server, Administratorretrieves information about users and groups from LDAP. This screen shows the LDAP configuration usedby the first administrator server.

Click the Test Connection button to make sure the connection between LDAP server and the replica serverworks properly.

Administrator Server Configuration SummaryEach TIBCO Configuration Tool wizard's summary screen allows you to check the configuration that youspecified and see the effects of that configuration. You can click Back to make changes, save the configurationfor use by the silent installer, or click Configure to start the configuration. If you are using the consoleconfiguration tool, you can perform the same actions by typing single-letter commands, as prompted.

The Administrator Server Configuration Summary screen displays information about the session scripts andlog folder and about the Administrator URL. For this wizard, you can only choose to replicate the remoteserver, or cancel the replication.

Deleting an Administrator ServerIf you are using a replica Administrator server, the TIBCO Configuration Tool wizard does not allow you todelete a replica instance, if you want to. You can delete from the command line.

Before you begin

Make sure that the super user specified in the remote_props.properties has force_delete permission.Only users with explicit force_delete and super user permission are allowed to delete the Administratorserver instance.

About this task

Do not run the deletion script on the machine on which the Administrator instance you want to deleteis running. For example, assume your cluster consists of Administrator instance A running on machineX and Administrator instance B running on machine Y. To delete instance B, run the script frominstance A running on machine X.

Procedure

1. Open a command window.2. Go to the following directory.

CONFIG_HOME/admin/enterprise_name/samples


94 | Configuration

3. Edit the deleteAdminInstance_data.xml file to update the node and host name properties.4. Run the following command.

ant -f deleteAdminInstance_build.xml

When you run this command, the replica node is deleted from the environment and the replica host willbe unregistered. If the replica host has any runtime nodes, the replica host is not unregistered.

5. If the replica host is unregistered, got to the machine on which the administrator instance was runningand terminate the TIBCO Host process.

Edit ActiveMatrix Administrator Server ConfigurationYou can edit some aspects of the configuration for an existing Administrator server with TIBCO ConfigurationTool.

This section describes the process of updating configuration settings that were initially specified when creatingthe Administrator server using TIBCO Configuration Tool.

To edit an existing configuration, follow these steps:1. Start TIBCO Configuration Tool.2. Select a CONFIG_HOME location for the Administrator server that you want to change.3. Click Edit TIBCO ActiveMatrix Administrator Server Configuration - V3.3

DescriptionField

Select an Administrator server configuration from the drop-down list.Select serverconfiguration

Edit Administrator Server ConfigurationYou can edit the connection settings, database settings, or authentication realm settings for your Administratorserver.

DescriptionField

Edit the connection settings for the ActiveMatrix Administrator server.Edit HTTPConnection Settings

Edit the configuration details for the ActiveMatrix Administrator database.Edit DatabaseSettings

Edit the configuration details for the Administrator authentication realm.Edit AuthenticationRealm Settings

Administrator Server Connection SettingsWhen you edit the connection settings, you can specify the network adapter and external port or enable SSLfor HTTP communications. If you enable SSL, you are prompted to specify the certificate information. Thedefaults this screen displays show the current configuration settings.

DescriptionField

Address of the network adapter on the machine on which the Administratorserver runs. The default is set to 0.0.0.0 so that Administrator will listen on all

Network Adapter



Configuration | 95

DescriptionField

Port on which the Administrator clients access the Administrator server.External HTTP Port

Select to secure communication between Administrator server and clients withSSL. When selected, the Self-Signed Certificate and Imported Certificate radiobuttons display.


Indicate that the Administrator server will identify itself to clients with aself-signed certificate. When selected it uses the self signed certificate from thesamples folder.



Indicate that Administrator server will identify itself to clients with a certificateimported into Administrator server. When selected, the Keystore fields and FetchKeystore button are enabled.






Fetch Keystore

Edit Administrator Server Database DetailsThe Edit Administrator Server Database Details screens is used to change the database details for your server.Using the wizard requires that you prepare your environment and that you perform some post-processingsteps.

Changing Database Details

To change the database details, perform the following steps:1. From the TIBCO Administrator user interface, stop the following applications from the System environment:

– com.tibco.amx.commonlogging.logservice.app– com.tibco.amx.commonlogging.payloadservice.app– com.tibco.amx.mcr.aggregator

2. Perform the following steps to uninstall the resource instances:a. Make sure that you uninstall Log Service and Payload Service first. (TIBCO ActiveMatrix Payload

Service Teneo Resource, TIBCO ActiveMatrix Log Service Teneo Resource).b. Uninstall the Teneo resource instances from the system node (TIBCO ActiveMatrix Governance Teneo

Resource).c. Uninstall the Hibernate Resource Instance from the system node (TIBCO ActiveMatrix Governance

Hibernate Resource).d. Uninstall in the following order : Log Service or Payload Service in any order followed by the

Governance JDBC shared resource instances from the system node. Ensure that the Governance JDBCshared resource instance must be the last to be uninstalled. It is recommended to use the Force Uninstalloption for JDBC Resource Instance.

If you skip steps 3 to 7, please restart TIBCO Host manually.

3. If required, change the configuration of the user or database.


96 | Configuration

4. Start TIBCO Configuration Tool and select Edit TIBCO ActiveMatrix Administrator Server Configuration- V3.3.

5. Select the enterprise name and server name from the Server Configuration drop down menu, and selectEdit Database settings.

6. Edit the database configuration, and click Configure.

When update is complete, TIBCO Configuration Tool restarts the SystemNode node.

7. When the SystemNode node becomes available, log in to the TIBCO Administrator GUI and update theGovernance JDBC resource with the new database configuration information. Cancel the pop-up toautomatically synchronize the resource instances and applications.

8. Install the following:a. JDBC Resource Instance for Governance JDBC Resource Instance. Make sure that Governance Service

is installed before installating Log Service and Payload Service.b. Install the Hibernate Resource Instance (TIBCO ActiveMatrix Governance Hibernate Resource).c. Install the Teneo Resource Instances. Make sure Governance Service is done first before installation of

Log Service and Payload Service.

If the data base URL is changed to point to a different database, make sure you migrate all the datafrom the old database location to the new database location. Editing the configuration alone does notmigrate the data.

DescriptionField

This will be checked if the current administrator uses an in-process database. TCTdoes not support editing the in-process database details.

Use DefaultIn-Process Database

DescriptionField






Default: sa.

Username


Default: None.

Password


Default: 30.

Max Connections


Configuration | 97

DescriptionField


Default: Cleared.


DescriptionField




Type of the keystore: JKS or JCEKS.Keystore Type


If ActiveMatrix Administrator is not starting due to database connection failure, refer to the resolutionlisted in the Troubleshooting section.

Making Planned Database Configuration ChangesThis section lists the steps to update the database configuration in a planned manner when you have theActiveMatrix Administrator running.

Procedure

1. Edit the JDBC resource templates and reinstall resource instances using the following steps:a) In ActiveMatrix Administrator GUI, navigate to Shared Objects > Resource Templates.b) Select TIBCO ActiveMatrix PayloadService JDBC Resource.

If you upgraded from a prior release, select payloadJdbcSharedResource.

c) In the Details section, update the database configuration and click Save. However, in the Apply Changesin Resource Template to Runtime window, click Cancel .

d) In the Resource Instances tab of the Details section, verify that the resource instance shows Out ofSync.

e) Click the Install button.f) Wait and refresh till the status of the resource instance switches to Running and In Sync.

2. Repeat step 1, but for the resource templates -TIBCO ActiveMatrix LogService JDBC Resource andTIBCO ActiveMatrix Governance JDBC Resource. The order is important, and the TIBCO ActiveMatrixGovernance JDBC Resource must be the last one.

If you upgraded from a prior release, select cl_logservice_jdbc andGovernanceJDBCSharedResource.

3. Make the planned database configuration change on the database server. For example, changing thepassword.

4. Using TIBCO Configuration Tool, update the database configuration for the ActiveMatrix Administratoras follows:a) Select Edit TIBCO ActiveMatrix Administrator Server Configuration.b) From the Select Server Configuration drop-down list, select the enterprise name and server name.c) Check Edit Database Settings.


98 | Configuration

d) If the users or groups are defined in the Administrator database and not in an LDAP server, select EditAuthentication Realm Settings .

e) Click Test Connection to verify the settings.f) Click Configure to apply the changes. When the update is complete, TIBCO Configuration Tool restarts

the system node.g) Wait for a few minutes for the system node to become available.

ResultsAfter the restart, the new database settings are fully in effect.

Edit Administrator Server Authentication RealmAdministrator stores information about users and groups in an authentication realm. When you edit theAuthentication realm, you can change the settings of the current realm, switch from a database to LDAP, orswitch from LDAP to a database. TIBCO Configuration Tool will then prompt you for more informationabout the authentication realm.

Changing from a Database Realm to LDAP

Before you can change from a database realm to the LDAP realm, you have to add a new user in the currentDB realm and assign the user as superuser. This new user must already be a user in the LDAP realm youwant to use. See the Administration document for more information.

If you are changing from a Database realm to an LDAP realm, super user credentials are displayed. You needto enter the super user credentials you just created.

Enter the information about the authentication realm in the wizard screen.

Changing from LDAP to a Database Realm

What happens when you change from LDAP to a database realm depends on whether the database realm isempty or not.• If the new database realm is empty that is if it does not have any users in it, Administrator creates a new

user called tibco_user with a password 't'.

For this case, use the tibco_user superuser to log in to TIBCO Administrator after you have changed toa database realm and change the password. Consider creating a new superuser and deleting the defaulttibco_user user.

• If the new DB realm is not empty and does not contain any of the current superuser, a new user calledtibco_user with password 't' is created.

For this case, use the tibco_user superuser to log in to TIBCO Administrator after you have changed to adatabase realm and change the password. Consider creating a new superuser and deleting the defaulttibco_user user.

• If the new DB realm already contains a superuser that is also a superuser in LDAP, you can use thatsuperuser. Administrator does not create a new user.

Enter the information about the authentication realm in the wizard screen.

DescriptionField

Authentication Realm

Type of authentication realm:Realm Type• Database - See Administrator Server Database Authentication Realm on page 72• LDAP - See Administrator Server LDAP Authentication Realm on page 74

Superuser Credentials


Configuration | 99

DescriptionField

Name of the initial superuser.

Default: root.

Username


Default: t.

Password

In the properties file, this value is obfuscated.

SummaryWith each TIBCO Configuration Tool wizard's summary screen, you can check the configuration that youspecified and see the effects of that configuration. You can click Back to make changes, save the configurationfor use by the silent installer, or click Configure to start the configuration. If you are using the consoleconfiguration tool, you can perform the same actions by typing single-letter commands, as prompted.

When you edit the server configuration, the tasks you can perform depend entirely on selections made duringconfiguration.


100 | Configuration

DDL Script Generator

The DDL Script Generator is used to generate database specific DDL scripts defining the database schemaneeded to operate the ActiveMatrix Administrator server.

Overview of the DDL Script Generator UtilityUse the DDL Script Generator utility to manually create the database schema.

By default, when you create an ActiveMatrix Administrator server using Tibco Configuration Tool, thedatabase schema objects are created automatically when the ActiveMatrix Administrator server starts up thefirst time. If you do not want the software to automatically create the database schema objects at runtime,before creating the ActiveMatrix Administrator server, use the DDL Script Generator Utility. For a list ofpermissions needed to create the schema, see Configuring External Databases. After this step, the databaseadministrator (DBA) must execute the scripts to create the database schema objects that ActiveMatrixAdministrator server needs.

The utility is used in the following two scenarios:• While creating a new ActiveMatrix Administrator server, use the utility to generate scripts for creating

the database schema.• After deleting all ActiveMatrix Administrator server instances, while cleaning clean up a part or whole

of an existing schema.The utility generates scripts to cleanup the database schema.

Creating the Database SchemaYou can explicitly generate DDL scripts and use them to create the database schema.

Procedure

1. On the machine that runs ActiveMatrix Administrator, configure the drivers for database using TIBCOConfiguration Tool.

2. Navigate to the TIBCO_HOME/administrator3.3/samples/ddl folder.3. Edit the generate_ddl.xml file and modify the dbType and dialect for your database type under the

create target. See DDLGeneratorTask on page 103 for more information.<target name="create"> <DDLGeneratorTask action="create" targetDirectory="${admin.ddl.samples.directory}" dbType="oracle11g" dialect="com.tibco.amf.sharedresource.runtime.core.hibernate. dialects.Oracle10gDialect" /> </target>

If you are creating the second instance of a replicated ActiveMatrix Administrator Server, skipsteps 2 and 3 while creating the ActiveMatrix Administrator server.

4. Execute ant -f generate_ddl.xml create.5. Ensure that the Database Prerequisites mentioned under Configuring External Databases are met. Have

the DBA execute the script files - create_*.ddl in the corresponding databases as explained in theDatabase Models section.

6. (Optional) In addition to the generated scripts, if you want to use the Monitoring service, the DBA needsto execute an additional script corresponding to the monitoring data. It can be found under<TIBCO_HOME>/administrator/3.3/scripts/governance/ddl/create_*.sql. Use the scriptcorresponding to your database type.

7. Run TIBCO Configuration Tool again to create the AMX Administrator server.


Configuration | 101

ResultsThe DDL scripts are generated and can be used to execute on the database.

Example

Sample DDLGeneratorTask element

Cleaning up the Database SchemaUse the DDL Script Generator utility to generate scripts to clean up the database.

Procedure

1. On the machine that runs ActiveMatrix Administrator, configure the drivers for database using TIBCOConfiguration Tool.

2. Navigate to the TIBCO_HOME/administrator3.3/samples/ddl folder.3. Edit the generate_ddl.xml file and modify the dbType and dialect for your database type under the

drop target. See DDLGeneratorTask on page 103 for more information.<target name="drop"> <DDLGeneratorTask action="drop" targetDirectory="${admin.ddl.samples.directory}" dbType="oracle11g" dialect="com.tibco.amf.sharedresource.runtime.core.hibernate. dialects.Oracle10gDialect" /> </target>

4. Execute ant -f generate_ddl.xml drop.5. Depending on what portions of the schema you want to remove, have the DBA execute the script files -

drop_*.ddl in the corresponding databases as explained in the Database Models section.6. (Optional) In addition to the generated scripts, if you want to use the Monitoring service, the DBA needs

to execute an additional script corresponding to the monitoring data. It can be found under<TIBCO_HOME>/administrator/3.3/scripts/governance/ddl/drop_*.sql. Use the script correspondingto your database type.

Database ModelsTibco Configuration Tool allows you to configure separate databases for ActiveMatrix Administrator, Databaserealm, Common logging service and Monitoring service.

By default, the DDL Script Generator generates four separate scripts for each model:

DescriptionScripts

The database schema for the core functionality in ActiveMatrix Administratoradmin

The database schema for Database authentication realm, specifically needed to storeusers and groups in the database (not applicable for LDAP)

security

The database schema that stores log and payload records created by the CommonLogging service.

commonlogging

The database schema that stores metadata used by the Monitoring service. The metadatahas a separate schema than the actual monitoring data; although they can be in thesame database.

governance

By default, the DDL generator produces scripts for every model. Depending on which databases you wantin each model, execute the script for that model in its corresponding database. You can skip one or more DDLscripts if you do not want to use that functionality for the model. For example, while using LDAP authenticationrealm you skip the DDL scripts for the security model.


102 | Configuration

The default name for DDL files is composed of <action>_<model>.ddl (where <action> is create, drop orupdate).

For example, create_admin.ddl is the schema creation script for the core functionality in ActiveMatrixAdministrator. Similarly, drop_admin.ddl is the schema deletion script.

DDLGeneratorTask

DDLGeneratorTask specifies an action, data and property files, the objects on which the action is performed,and various behavioral attributes.

<DDLGeneratorTask action="action" targetDirectory="path to the samples directory" targetFilePrefix="targetFilePrefix" modelProfiles="modelProfiles" dbType="dbtype" dialect="dialect" username="username" password="password" dbUrl="dbUrl"/>

DescriptionReq?TypeAttribute

The action to be performed by the generated scripts.YesStringaction

• create - scripts to create tables and related database objects are created.• drop - scripts to delete tables and related database objects.

The action is case insensitive.

The location of the directory where the generated scripts files are stored.

Default: TIBCO_HOME/administrator/3.3/samples/ddl.

NoStringtargetDirectory

The name of generated script file. the location of the script file. If specified,this attribute takes precedence over the targetDirectory attribute.

NoStringtargetFile

The prefix for the generated scripts. Used only when thetargetFilePrefix attribute is used.

NoStringtargetFilePrefix

The database for which to generate the scripts. Valid values:NoStringdbtype

• sqlserver• oracle10g• oracle11g• db2

The dialect of the specified database.YesStringdialect

Used to connect to the database.NoStringusername

Used to connect to the database.

The password for the specified username attribute can be either clear textor encrypted value.

NoStringpassword

Used to connect to the database.YesStringdburl

Used to specify a model for which to generate the scripts. Multiple valuescan be specified using a comma-separated list.

Valid values:

YesStringmodelProfiles

• admin


Configuration | 103

DescriptionReq?TypeAttribute

• governance• commonlogging• security• all - generate scripts for all the models listed above.


104 | Configuration

Chapter

6Upgrade

Upgrading your ActiveMatrix enterprise means upgrading the configuration of certain services and runtime objects.TIBCO provides Ant scripts that you run to perform the upgrade process. The scripts also allow you to back upthe services and runtime objects of your enterprise that you want to upgrade.

For a successful upgrade process, you need to understand the supported scenarios, upgrade impact, and what thedifferent scripts do.

Topics

• Upgrade Overview• Performing an Upgrade• Example Upgrade and Restore Scenarios• Upgrade Scripts• Upgrading TIBCO Enterprise Message Service Server• Upgrading Runtime Objects


Upgrade OverviewBefore you start the upgrade process, make sure you understand the impact your upgrade will have on yourenvironment, and how versions can coexist.

Upgrade Basics

Upgrading your TIBCO ActiveMatrix environment requires that you install new software and upgrade theconfiguration of the different runtime objects such as TIBCO Host instances, ActiveMatrix Administratorservers, and ActiveMatrix nodes. Optionally, it might involve upgrading the Enterprise Message Serviceserver used by the ActiveMatrix Administrator servers and TIBCO Host instances.

You can perform TIBCO ActiveMatrix upgrades with upgrade scripts that are installed when you install anew version of the software.

If you plan to have a replicated configuration, do so before upgrading to ActiveMatrix 3.3.0.

Version Coexistence

After you have upgraded the Administrator server instance to ActiveMatrix 3.3.0, you can manage TIBCOHost instances and nodes that are running ActiveMatrix 3.2.0 and ActiveMatrix 3.1.x software.• Existing hosts can continue running earlier versions of TIBCO ActiveMatrix software.• When you create a node on an existing host, the node uses the version that the host is running (including

hotfixes).• When you upgrade a host, existing nodes can continue running earlier versions of TIBCO ActiveMatrix

software. However, any new nodes that you create will run the version to which you upgraded.

The result is an environment that can include hosts that are running different versions of the software. Onthe hosts, you can have nodes that are running different versions of the software.

Upgrade to TIBCO ActiveMatrix 3.3.0 is supported from TIBCO ActiveMatrix 3.1.2 or later. If youhave an earlier version, you must upgrade to TIBCO ActiveMatrix 3.1.2 first.

Exceptions to Version Coexistence

A DAA can only be used with nodes whose version is greater than or equal to the Studio version used tocreate the DAA. For example, a DAA created by ActiveMatrix 3.2.0 requires nodes running ActiveMatrix3.2.x or 3.3.x.

The following scenarios are an exception to Version coexistence:

Cannot Be Used WithCan Be Used WithDAA Version

ActiveMatrix 3.1.5 nodes

ActiveMatrix 3.2.0 nodes

ActiveMatrix 3.3.0 nodes and aboveActiveMatrix3.3.0

ActiveMatrix 3.1.5 nodesActiveMatrix 3.2.0 nodes and aboveActiveMatrix3.2.0

Nodes that are on versions prior to 3.1.5.ActiveMatrix 3.1.5 nodes and aboveActiveMatrix3.1.5

While planning replication, ensure that both the Administrator servers have the same set of softwareversions including the hotfixes that were applied before upgrading to ActiveMatrix 3.3.0.


106 | Upgrade

Removed Support for the Internal HTTP Load Balancer

When replicating servers, owing to the complexity posed by setting up an internal load balancer, all versionsfrom 3.2.0 onwards have removed support for an internal HTTP load balancer.The ActiveMatrix platformnow provides the option of keystores having 2 URLs (or as many as the number of Administrator serversavailable in a fault tolerant set up). TIBCO Host and runtime nodes fall back on the secondary URL todownload a keystore, should the primary be unavailable.

Upgrade Impact

When you upgrade the configuration of any of the components of your enterprise, Enterprise Message Service,Administrator servers, or TIBCO Host instances and nodes, the rest of the environment is affected.

If you are performing an upgrade on Microsoft Windows, make sure that the tibcohost configurationfolder (or any subfolder or file) is not locked by another process before you start an upgrade process.A folder is considered locked if it is displayed in Windows Explorer or if a command shell is openwith the folder as the current directory. If the folder is locked, the upgrade process will fail.

TIBCO Enterprise Message Service Server

Depending on your installation you might be using one or several Enterprise Message Service servers.

The Enterprise Message Service server deploys new applications, manages existing applications, and managesinfrastructure. The Enterprise Message Service server also handles ActiveMatrix messages. The servers youupgrade determine whether your applications remain available. For example, while you are upgrading theserver that handles communication between TIBCO Host instances, ActiveMatrix nodes, and the Administratorserver, you cannot perform administrative functions in your enterprise. However, your application servicescontinue to run and application clients do not experience service interruptions.

ActiveMatrix 3.3 and later ships with Java 7. If you upgrade your environment to ActiveMatrix 3.3.0or later, you must use an Enterprise Message Service Server version 6.3 or later or use a stream cipher.

The following table gives an overview.

EffectEnterprise Message Service Server BeingUpgraded

Cannot perform application deployment andmanagement.

Enterprise Message Service Server that handlesNotification Service messages (status messages fromhosts and nodes to the Administrator server)

Logging and monitoring statistics become unavailable.Enterprise Message Service Server that handles logand monitoring messages

External applications stop communicatingEnterprise Message Service Server that handlesapplication messages between ActiveMatrix services

Client applications might experience serviceinterruption. External applications stop running.

Enterprise Message Service Server that allowscommunication between a client application and anActiveMatrix hosted application service using theJMS or SOAP/JMS bindings.

On AIX platforms, you must apply the following hotfixes before upgrading to ActiveMatrix 3.3.0:1. ActiveMatrix 3.2.0 HF-0062. ActiveMatrix 3.1.5 HF-0103. ActiveMatrix 3.1.3. Contact support for details.4. ActiveMatrix 3.1.2. Contact support for details.


Upgrade | 107

ActiveMatrix Administrator Server

During upgrade of the ActiveMatrix Administrator, deployed applications continue to run without serviceinterruption. However, because the Administrator server itself is unavailable, you cannot deploy newapplications, manage existing applications, or manage infrastructure.

If you have multiple ActiveMatrix Administrator server instances, you must upgrade each server. An enterprisewith different Administrator server instances running different versions is not supported. During the upgrade,you cannot deploy new applications, or make changes to existing applications.

TIBCO Host Instances and Nodes

Upgrading a TIBCO Host instance and its nodes, stops applications deployed on the nodes. Clients of thoseapplications might experience service interruptions. You might be able to mitigate this by distributing thesame application (components and binding types) to two nodes managed by two different TIBCO Hostinstances.

TIBCO Hawk ActiveMatrix Plug-in gets installed with this upgrade. For further information, seeTIBCO Hawk ActiveMatrix® Plug-in User’s Guide.

Runtime Object StateBecause you need to back up parts of your environment for each stage of the upgrade process, you need tounderstand where runtime object state is stored.

The runtime object state consists of configuration data and binary executables. The runtime object state isstored in different locations for the different runtime objects.

The following variables are used in the locations listed below:• CONFIG_HOME is the folder containing runtime object configurations. Each time you run TIBCO

Configuration Tool, you are prompted for the CONFIG_HOME location you want to use. Select an existinglocation or set a new location.

• enterpriseName and administratorServerName are the names you specified when you initially ran TIBCOConfiguration Tool to create the Administrator server.

• hostInstanceName is the name you specified when you initially ran TIBCO Configuration Tool to create theTIBCO Host instance.

• nodeName is the name you specified when you created the node.

State for Administrator Server InstancesWhere Administrator server state is stored depends on the database you are using.• If you selected the In-Process Database option during Administrator server database configuration,

CONFIG_HOME/admin/enterpriseName contains Administrator server files and the in-process database.• If you selected an external database, the Administrator state information is on the external database.

Administrator Server Credentials

By default, upgrade scripts use the Administrator server URL and the credentials that were recorded at thetime the enterprise was created, inCONFIG_HOME/admin/enterpriseName/private/administratorServerName/cli-connectivity.properties andCONFIG_HOME/admin/enterpriseName/private/administratorServerName/temp/admin_bootstrap.properties.

These files may not have been updated if the user has changed the superuser username or password afteran Administrator server has already been created. If the default credentials fail during upgrade, the user isprompted for the username and password.


108 | Upgrade

State for TIBCO Host Instances

State information for TIBCO Host instances is stored in TIBCO_HOME/tibcohost/hostInstanceName. For thesystem host, state is typically stored in /tibcohost/Admin-enterpriseName-administratorServerName

State for Nodes

Runtime state for nodes is distributed. Some state is in the Administrator database, and some state is in thehostInstanceName folder. If there are pending tasks, additional information is in other locations in the hierarchy.

The location of some of the node's state depends on the version you are using.

ActiveMatrix 3.0.x and ActiveMatrix 3.1.x

CONFIG_HOME/tibcohost/hostInstanceName/nodes/nodeName and CONFIG_HOME/admin/enterpriseName

ActiveMatrix 3.2.x and 3.3.x

CONFIG_HOME/tibcohost/hostInstanceName/data_3.2.x/nodes/nodeName andCONFIG_HOME/admin/enterpriseName

Determining a Runtime Object's Version

To determine whether a runtime object has been upgraded, you can verify the version of TIBCO Host instancesand nodes. See the Administration manual for information on determining the version using the TIBCOAdministrator GUI.

Supported Upgrade ScenariosActiveMatrix supports several upgrade scenarios including upgrading a development installation, single-hostupgrade, and multi-host upgrade. In most cases, it makes sense to upgrade all nodes controlled by a TIBCOhost when you upgrade that host.

Planning for Upgrade

As part of your upgrade, you should plan frequent backups. You can use your own backup solution or usethe TIBCO upgrade scripts, as illustrated in Example Upgrade and Restore Scenarios on page 113.

If you use your own backup solution, set the "-Dforce.no.backup=true" property on the Antcommand line when running upgrade targets.

Single-Host Upgrade

In a single-host configuration the SystemHost TIBCO Host instance, the SystemNode node, and one or moreadditional nodes run on the same machine. The Administrator server runs on the SystemNode node. Whenyou upgrade a TIBCO host, you can upgrade the nodes controlled by that host, or you can wait until later.Performing a full upgrade of a single-host configuration is recommended but not required. See Upgradingan Enterprise with a Single Host Instance on page 111.

Multi-Host Upgrade

A multi-host configuration consists of at least two machines. One machine runs the SystemHost host andSystemNode node. One or more additional machines in the enterprise each run a TIBCO Host instance withone or more nodes. See Upgrading an Enterprise with Multiple TIBCO Host Instances on page 111.


Upgrade | 109

Setting Permissions for Non-Admin Users During Upgrade

If your infrastructure connects to its Enterprise Message Service servers with users that do not haveadministrator privileges during upgrade, the following permissions must be set for the Administrator server'sNotification Bus.

create topic AMX_MGMT.> grant topic AMX_MGMT.> user=username create, modify, subscribe, publish

create queue AMX_MGMT.> grant queue AMX_MGMT.> user=username create, delete, modify, send, receive


110 | Upgrade

Performing an Upgrade

Upgrading consists of installing new software and upgrading the configuration. Repeated backup operationsare recommended as part of the upgrade process.

The first step in the upgrade process is always installation of new software. For a feature release, this documentincludes information you need for the upgrade.

You cannot install TIBCO Business Studio 3.3.0 on an earlier version of ActiveMatrix.

After new software has been installed, you upgrade the configuration of the different enterprise components.The process differs depending on your enterprise (single host enterprise upgrade or multihost enterpriseupgrade). You can perform a full upgrade of all components in the enterprise or perform a rolling upgrade.

A node cannot be upgraded before its host has been upgraded, and the SystemNode(s) must beupgraded before any other nodes.

Upgrading an Enterprise with a Single Host InstanceYou upgrade a single Host instance enterprise by using upgrade script commands.

About this taskTo perform an upgrade of an enterprise that runs on a single TIBCO Host instance, you upgrade theSystemHost TIBCO Host instance, the SystemNode node, and all additional nodes. Backups before each stepare highly recommended, resulting in the following sequence of tasks.

See Single TIBCO Host Instance Upgrade Example on page 113.

If you are using an external database, use the vendor's backup process to back up the database.

Procedure

1. Back up the SystemHost TIBCO Host instance.2. Back up Administrator server files and the Administrator server database.3. Upgrade the SystemHost TIBCO Host instance.4. Upgrade the SystemNode node.

This step also upgrades the Administrator server.

5. Upgrade all other nodes.The target supports individual node upgrades, however, upgrading all nodes is highly recommended.

After upgrading to ActiveMatrix 3.3.0, to be able to create new 3.2.0 or 3.1.5 hosts using TCT, youneed to have an older version (3.2.0 or 3.1.5) installed in a separate TIBCO_HOME.

Upgrading an Enterprise with Multiple TIBCO Host InstancesYou can perform a full upgrade or a partial upgrade of an enterprise that includes multiple TIBCO Hostinstances by using the commands included in the upgrade script.

About this taskTo perform a full upgrade of a multiple TIBCO Host instance enterprise, upgrade all TIBCO Host instances,the SystemNode node, and all nodes.


Upgrade | 111

Upgrade all hosts in your enterprise if possible.

Backups are an important part of the upgrade process. If you are using an external database, you usethe vendor's backup process to back up the database.

Procedure

1. Back up the SystemHost TIBCO Host instance.2. Back up Administrator server files and the Administrator server database.3. Upgrade the SystemHost TIBCO Host instance.4. Upgrade the SystemNode node.5. Upgrade additional nodes associated with SystemHost.6. Backup one of the standalone TIBCO Host instance.7. Back up Administrator server files and the Administrator server database.8. Upgrade the standalone TIBCO Host instance you backed up in Step 6.9. Upgrade all nodes associated with the TIBCO Host instance you upgraded in step 8.10. Repeat step 7-9 until all hosts are upgraded.

After upgrading to ActiveMatrix 3.3.0, to be able to create new 3.2.0 or 3.1.5 hosts using TCT, youneed to have an older version (3.2.0 or 3.1.5) installed in a separate TIBCO_HOME.

Upgrading in a Replicated Setup with Multiple TIBCO Host InstancesIf you have a replicated setup in place, you need to upgrade the ActiveMatrix platforms on both the setups.This section lists the steps to upgrade the primary and secondary machine.

Before you beginEnsure that you have successfully replicated on older versions: ActiveMatrix 3.1.0 or ActiveMatrix 3.2.0

Procedure

1. Install ActiveMatrix 3.3.0 on both the machines.2. Backup the ActiveMatrix Administrator and System Hosts on both primary and secondary machines.3. Upgrade SystemHost on the primary machine.4. Upgrade SystemNode on the primary machine.5. Upgrade SystemHostReplica on the secondary machine.6. Upgrade SystemNodeReplica on the secondary machine.7. Upgrade all the runtime nodes; irrespective of the order.


112 | Upgrade

Example Upgrade and Restore Scenarios

The following examples of upgrade and restore scenarios illustrate a potential workflow. You perform therestore operations only if you encounter problems with the upgrade.

If you restore the runtime objects on a machine to an earlier state, you must uninstall the earlierversions of other TIBCO ActiveMatrix components from that machine.

The examples in this section assume you run scripts from the following location:

TIBCO_HOME/amx/3.3/scripts/upgrade/upgrade-to-3.3.0

Single TIBCO Host Instance Upgrade Example

About this task

This example describes how to upgrade a configuration on one machine M1. The SystemHost TIBCO Hostinstance, SystemNode node, and additional nodes DevNode1 and DevNode2 run on M1.

Upgrading System Host and System NodeThe first step in the upgrade process is running backup and upgrade scripts for the SystemHost, theSystemNode, and the Administrator server that runs on it.

Procedure

1. Back up SystemHost and the Administrator server.Before you start the Administrator server upgrade, back up the SystemHost host instance and theAdministrator server that runs on it. Back up the Administrator files and databases, as follows:a) Back up the SystemHost TIBCO Host instance.

backup-tibcohost -Dth.backup.tag=-preAdmin_330-Dtibcohost.instance.name=Admin-enterprise-hostInstance-Dtibco.config.mgmt.home=CONFIG_HOME

The names and locations depend on your environment.

b) Back up the Administrator server files and Administrator server database.1. Back up the Administrator server files. If the in-process database is in use, it gets backed up

automatically.backup-admin -Dadmin.backup.tag=-preAdmin_330-Dadmin.server.dir=CONFIG_HOME\admin\enterprise\private\hostInstance

Using the same tag as the tag you used for the SystemHost upgrade is recommended.

2. If you are using an external database, also use the backup tool provided by the database vendor.

2. Upgrade the SystemHost TIBCO Host instance.upgrade-tibcohost -Dtibcohost.instance.name=Admin-enterprise-hostInstance-Dtibco.config.mgmt.home=CONFIG_HOME

3. Upgrade the SystemNode node.Upgrading the SystemNode upgrades Administrator server.upgrade-node-Dnode.name=SystemNode -Dhost.name=SystemHost -Dadmin.server.dir=CONFIG_HOME\admin\enterprise\private\hostInstance


Upgrade | 113


Upgrading Other NodesAfter the SystemHost and SystemNode have been successfully upgraded, you can upgrade other nodes. Theupgrade is successful when the upgrade script completed successfully. You cannot examine nodes after anupgrade to know whether the upgrade completed; instead, you can attempt the upgrade again.

About this taskYou upgrade the Administrator Server, the System Host and the System Node on machine M1.

Procedure

1. Before you start node upgrades, back up the SystemHost host instance, and back up the Administratordatabase, as follows.a) Back up TIBCO Host instance SystemHost.

backup-tibcohost -Dth.backup.tag=-preNodes_330 -Dtibcohost.instance.name=Admin-enterprise-hostInstance-Dtibco.config.mgmt.home=CONFIG_HOME


automatically.backup-admin -Dadmin.server.dir=CONFIG_HOME\admin\enterprise\private\hostInstance-Dadmin.backup.tag=-preNodes_330


2. Upgrade the nodes.upgrade-nodes -Dhost.name=SystemHost-Dadmin.server.dir=CONFIG_HOME\admin\enterprise\private\hostInstance

Single Host Instance Restore ExampleIf errors occur during the upgrade process, you can restore the SystemHost TIBCO Host instance and thenodes you attempted to upgrade from the backups you made.

Restoring System HostIf errors occur during the upgrade of the SystemHost host, the SystemNode node, or the Administrator server,you can restore from the backup you made earlier.

Procedure

1. Restore the Administrator server database from the backup you created earlier.a) Restore the Administrator by pointing to the Administrator server directory.

restore-admin -Dadmin.restore.zip=CONFIG_HOME/admin/enterpriseupgrade-to-3.3.0/backups/date-time-preAdmin_330.zip -Dadmin.server.dir=CONFIG_HOME\admin\enterprise\private\hostInstance

b) If using an external database, also use the restore tool provided by the database vendor.

2. Restore SystemHost TIBCO Host instance.restore-tibcohost -Dth.restore.zip=CONFIG_HOME/tibcohost/Admin-enterprise-hostInstance/upgrade-to-3.3.0/backups/date-time-preAdmin_330.zip -Dtibcohost.instance.name=Admin-enterprise-hostInstance-Dtibco.config.mgmt.home=CONFIG_HOME


114 | Upgrade

Restoring Other NodesIf errors occur during the upgrade of other nodes, you can restore from the backup you made earlier.

Procedure

1. Restore Administrator server database from the backup created earlier.a) Run the following commands:

restore-admin -Dadmin.restore.zip=CONFIG_HOME/admin/enterprise/upgrade-to-3.3.0/backups/date-time-preNodes_330.zip-Dadmin.server.dir=CONFIG_HOME\admin\enterprise\private\hostInstance


2. Restore the SystemHost TIBCO Host instance.restore-tibcohost -Dth.restore.zip=CONFIG_HOME/tibcohost/Admin-enterprise-hostInstance/upgrade-to-3.3.0/backups/date-time-preNodes_330.zip-Dtibcohost.instance.name=Admin-enterprise-hostInstance-Dtibco.config.mgmt.home=CONFIG_HOME

Multiple TIBCO Host Instance Upgrade Example

About this taskWhen you upgrade an enterprise that consists of two machines, the upgrade process changes slightly. Thisexample illustrates a full upgrade of a configuration with two machines.• M1 - SystemHost (including Administrator server).• M2 - Standalone TIBCO Host instance H2, including managed nodes N2 and N4.

You always upgrade remote nodes running on remote TIBCO Host instances from the machine onwhich the SystemHost TIBCO Host instance runs (in this example, M1).

Upgrading System Host and System NodeThe first step in the upgrade process is running backup and upgrade scripts for the SystemHost, theSystemNode, and the Administrator server that runs on it.

Procedure

1. Back up SystemHost and the Administrator server.Before you start the Administrator server upgrade, back up the SystemHost host instance and theAdministrator server that runs on it. Back up the Administrator files and databases, as follows:a) Back up the SystemHost TIBCO Host instance.

backup-tibcohost -Dth.backup.tag=-preAdmin_330-Dtibcohost.instance.name=Admin-enterprise-hostInstance-Dtibco.config.mgmt.home=CONFIG_HOME



automatically.backup-admin -Dadmin.backup.tag=-preAdmin_330


Upgrade | 115

-Dadmin.server.dir=CONFIG_HOME\admin\enterprise\private\hostInstance

Using the same tag as the tag you used for the SystemHost upgrade is recommended.


2. Upgrade the SystemHost TIBCO Host instance.upgrade-tibcohost -Dtibcohost.instance.name=Admin-enterprise-hostInstance-Dtibco.config.mgmt.home=CONFIG_HOME

3. Upgrade the SystemNode node.Upgrading the SystemNode upgrades Administrator server.upgrade-node-Dnode.name=SystemNode -Dhost.name=SystemHost -Dadmin.server.dir=CONFIG_HOME\admin\enterprise\private\hostInstance


Upgrading TIBCO Host H2In a multi-host environment, you first upgrade the SystemHost TIBCO Host and then other hosts, in thisexample host H2.

Procedure

1. Perform backup operations to prepare for upgrade of nodes managed by host TIBCO Host instance H2.In this case, instanceRemote is the remote TIBCO Host instance.a) On machine M2, back up TIBCO Host instance H2:

backup-tibcohost -Dth.backup.tag=-preH2_330 -Dtibcohost.instance.name=instanceRemote-Dtibco.config.mgmt.home=CONFIG_HOME

b) On machine M1, back up Administrator server files and the Administrator server database.1. Back up the Administrator server files. If the in-process database is in use, it gets backed up

automatically. Even if you performed a backup before the upgrade of the SystemHost host instance,you should perform another backup now.backup-admin -Dadmin.backup.tag=-preH2_330-Dadmin.server.dir=CONFIG_HOME\admin\enterprise\private\hostInstance

The names and locations depend entirely on your environment.2. If using an external database, also back up the external database using the backup tool provided

by the database vendor.

2. Upgrade nodes N2 and N4, which are managed by Host H2.a) On machine M2, upgrade TIBCO Host instance H2:

upgrade-tibcohost -Dtibcohost.instance.name=instanceRemote-Dtibco.config.mgmt.home=CONFIG_HOME

b) On machine M1, upgrade nodes running on M2:upgrade-nodes -Dhost.name=H2 -Dadmin.server.dir=CONFIG_HOME\admin\enterprise\private\hostInstance


116 | Upgrade

Multiple Host Instance Restore ExampleIf errors occur during the upgrade process, you can restore the SystemHost TIBCO Host instance, other hosts,and the nodes you attempted to upgrade from the backups you made.

Restoring System HostIf errors occur during the upgrade of the SystemHost host, the SystemNode node, or the Administrator server,you can restore from the backup you made earlier.

Procedure

1. Restore the Administrator server database from the backup you created earlier.a) Restore the Administrator by pointing to the Administrator server directory.

restore-admin -Dadmin.restore.zip=CONFIG_HOME/admin/enterpriseupgrade-to-3.3.0/backups/date-time-preAdmin_330.zip -Dadmin.server.dir=CONFIG_HOME\admin\enterprise\private\hostInstance


2. Restore SystemHost TIBCO Host instance.restore-tibcohost -Dth.restore.zip=CONFIG_HOME/tibcohost/Admin-enterprise-hostInstance/upgrade-to-3.3.0/backups/date-time-preAdmin_330.zip -Dtibcohost.instance.name=Admin-enterprise-hostInstance-Dtibco.config.mgmt.home=CONFIG_HOME

Restoring Nodes Managed by Host H2If errors occur during the upgrade of other nodes, you can restore from the backup you made earlier.

Procedure

1. On machine M1, restore the Administrator server database from the backup created earlier.

– Run the following commands:restore-admin -Dadmin.restore.zip=CONFIG_HOME/admin/enterprise/upgrade-to-3.3.0/backups/date-time-preH2_330.zip -Dadmin.server.dir=CONFIG_HOME\admin\enterprise\private\hostInstance

– If using an external database, also use the restore tool provided by the database vendor.

2. On machine M2, restore TIBCO Host instance:restore-tibcohost -Dth.restore.zip=CONFIG_HOME/tibcohost/instanceRemote/upgrade-to-3.3.0/backups/date-time-preH2_330.zip -Dtibcohost.instance.name=instanceRemote-Dtibco.config.mgmt.home=CONFIG_HOME


Upgrade | 117

Upgrade Scripts

You upgrade runtime objects by running an Ant script and providing the appropriate target. The scriptsupports the following categories of targets:• Backup - Create a zip archive of object state• Restore - Restore object state from a backup archive• Upgrade - Upgrade object state• Start - Start an object• Stop - Stop an object• Uninstall - Uninstall the hotfix

TIBCO Business Studio does not support uninstalling a hotfix. To roll back to the previous versionof TIBCO Business Studio, reinstall the previous version of the product in a new installationenvironment and choose the SOA Development profile.

See Configuring Ant on page 24 for required settings.

Upgrade Script TargetsUpgrade script targets support different properties depending on the object you want to upgrade. The UpgradeProperties section includes a table that explains which property is required for which target.

Upgrade Script Targets for SystemHost, SystemNode, and Administrator Server

You run upgrade scripts for SystemHost, SystemNode, and Administrator server on the machine on whichthe SystemHost TIBCO Host instance is running.

Table 16: Upgrade Script Targets

ResultPropertiesTarget

Stops the SystemHost TIBCO Hostinstance, SystemNode node, and any

admin.server.dir

admin.backup.tag

backup-admin

additional nodes managed byunattended (optional) SystemHost. Creates an archive of an

Administrator server configuration.

In unusual configurations, specifyenterprise.name,tibco.config.mgmt.home,tibcohost.instance.name,admin.server.name instead ofadmin.server.dir

Upgrades the SystemNode node, theAdministrator server, logging,

admin.server.dir

node.name=SystemNode

upgrade-node

This target takes at least 15minutes to complete. monitoring, and payload services.

Starts the SystemNode node.host.name=SystemHost

unattended (optional)


118 | Upgrade


Stops the SystemNode node. Restoresan Administrator server configurationfrom the archive.

admin.server.dir

admin.restore.zip


restore-admin

Ensure that CONFIG_HOMEis not in use by anyapplication.

Upgrade Script Targets for Nodes

Node upgrade scripts are executed remotely, from the machine running ActiveMatrix Administrator (theSystemHost TIBCO Host instance) rather than from the machine running the nodes to be upgraded.

Table 17: Upgrade Script Targets for Nodes


Stops the nodeName node. Upgradesthe nodeName node managed by hosthostName. Starts the nodeName node.

admin.server.dir

node.name=nodeName

host.name=hostName

upgrade-node

hostName host must berunning.


Stops the nodes managed by hosthostName. Upgrades the nodes managed

admin.server.dir

host.name=hostName

upgrade-nodes

hostName host must berunning. by host hostName. Starts the nodes

associated with host hostName.unattended (optional)

Upgrade Script Targets for TIBCO Host Instances

TIBCO Host instance upgrade scripts are executed locally, from the machine running the TIBCO Host instanceto be upgraded.

Table 18: Upgrade Script Targets for TIBCO Host Instances


Stops TIBCO Host instance. Creates anarchive of a TIBCO Host instanceconfiguration.


tibcohost.instance.name

backup-tibcohost

th.backup.tag


Stops TIBCO Host instance. Restoresa TIBCO Host instance configurationfrom an archive.



restore-tibcohost

Ensure that CONFIG_HOMEis not in use by anyapplication. th.restore.zip


Stops a TIBCO Host instance.tibco.config.mgmt.homestop-tibcohost


Starts a TIBCO Host instancetibco.config.mgmt.homestart-tibcohost


Upgrade | 119



Stops a TIBCO Host instance. Stops allnodes managed by that instance.tibco.config.mgmt.home


upgrade-tibcohost

The TIBCO Host instancemust be running. Upgrades the TIBCO Host instance.

All features and applications deployedunattended (optional) to the nodes remain unaffected. Startsthe TIBCO Host instance.

Upgrade Script Properties

You can set properties in the following table in a properties fileTIBCO_HOME/amx/3.3/scripts/upgrade/upgrade-to-version/user-overrides.properties. Propertiesset on the script command-line override values set in the properties file.

Table 19: Upgrade Script Properties

DescriptionProperty

An identifier added to the Administrator server backup archive file name.admin.backup.tag

Path to the Administrator server backup archive file.CONFIG_HOME/admin/enterpriseName/upgrade-to-version/backups/date-timetag.zip,where tag is the identifier you specified when creating the backup.

admin.restore.zip

CONFIG_HOME/admin/enterpriseName/private/serverNameadmin.server.dir

Indicate that the upgrade script will pause at every banner until you hit return.upgrade.debug.steps

The name of the host managing the node being upgraded. To determine thehost name for a node, select Infrastructure > Nodes in the Administrator UI.In the nodes table, the host is the second column.

host.name

Name of the node being upgraded.node.name

An identifier added to the TIBCO Host instance backup archive file name.th.backup.tag

Path to the TIBCO Host instance backup archive file.CONFIG_HOME/tibcohost/

th.restore.zip

instanceName/upgrade-to-version/backups/date-timetag.zip, where tag is theidentifier you specified when creating the backup.

Folder containing runtime object configurations.tibco.config.mgmt.home

Name of the TIBCO Host instance on the machine on which the script is beingexecuted. For the *-tibcohost targets, the name of the instance you are


upgrading. For all other targets, the name of the instance that managesSystemNode. A TIBCO Host instance name is the last component in the pathto a TIBCO Host instance described in Runtime Object State on page 108.

Indicate that the target will not require acknowledgment that runtime objectswill be stopped as a side effect of the target. This property is optional.

unattended

Whether a property is required depends on the target.


120 | Upgrade

Required PropertiesTarget

tibco.config.mgmt.homebackup-tibcohost

upgrade-tibcohost tibcohost.instance.namerestore-tibcohost

Require either admin.server.dir (in that case the scriptinfers other properties) or

(enterprise.name, tibco.config.mgmt.home,tibcohost.instance.name, admin.server.name) if you

backup-admin,

restore-admin

upgrade-node

upgrade-nodes performed unusual customizations in yourenvironment.upgrade-enterprise

Requires host.name and requires eitheradmin.server.dir (in that case the script infers otherproperties) or

(enterprise.name, tibco.config.mgmt.home,tibcohost.instance.name, admin.server.name,) if you

upgrade-nodes

performed unusual customizations in yourenvironment.

Requires host.name and node.name and eitheradmin.server.dir (in that case the script infers otherproperties) or

(enterprise.name, tibco.config.mgmt.home,tibcohost.instance.name, admin.server.name) if you

upgrade-node

performed unusual customizations in yourenvironment.

Running the Upgrade ScriptAfter you have performed the appropriate backups, you can run upgrade scripts.

Procedure

1. Install and configure Ant.2. Open a terminal window.3. Run cdTIBCO_HOME/amx/3.3/scripts/upgrade/upgrade-to-version.4. Run ant [-logfile logfile] target -Dproperty1 ...-Dpropertyn where target is one of the targets listed

in Table 16: Upgrade Script Targets on page 118, and property* is one or more of the properties listed inTable 19: Upgrade Script Properties on page 120.Script output is redirected to logfile.

Do not manually terminate any runtime objects while the script is running.

5. If you have not defined the unattended property, when you run the upgrade-tibcohost target, a promptdisplays requiring you to approve the termination of runtime object processes:[input] stop processes? (yes|no) :

6. Type yes and press Enter. If you type anything else, the script will exit.


Upgrade | 121

7. If you have not defined the unattended property, when you run the upgrade-node or upgrade-nodestargets a prompt displays asking whether to interrupt service:[input] interrupt service? (yes|no) :

8. Type yes and press Enter. If you type anything else, the script will exit.9. When the script completes successfully, the following is output:

BUILD SUCCESSFULTotal time: ...

What to do next

If you encounter problems during the upgrade, you can examine the corresponding log file.


122 | Upgrade

Upgrading TIBCO Enterprise Message Service ServerAs part of the upgrade process, you might also have to upgrade TIBCO Enterprise Message Service Server.

Procedure

1. Stop all affected runtime objects (Administrator servers, TIBCO Host instances, and nodes) in the enterprisebeing upgraded.See Upgrade Impact on page 107 for information on the services that are affected when you upgradeparticular Enterprise Messaging Service servers.

2. Install the new version of TIBCO Enterprise Message Service .3. Restart the TIBCO Enterprise Message Service server using the same configuration as that used by the

Enterprise Message Service server prior to upgrade.4. Restart all the runtime objects.5. Use the Administrator GUI to verify that all the TIBCO Host instances, nodes, and applications are

operational.


Upgrade | 123

Upgrading Runtime Objects

Procedure

1. Stop all runtime objects (Administrator servers, TIBCO Host instances, and nodes) on the machine beingupgraded.

2. Install in an existing installation environment (TIBCO_HOME) with the same installation profile presentin the existing installation environment.

3. Upgrade all the runtime objects running on the machine.

What to do nextAfter you upgrade TIBCO ActiveMatrix runtime objects, you may need to perform additional upgrade stepsspecific to other TIBCO ActiveMatrix components and products such as TIBCO ActiveMatrix Binding Typefor EJB or TIBCO ActiveMatrix Implementation Type for C++. For information on the steps to upgrade thosecomponents, see the documentation for those components and products.


124 | Upgrade

Chapter

7Troubleshooting

If you encounter problems with installation, make sure that your system meets all prerequisites. Next, check theinstaller log file for potential problems.

Installer Log File

The installer log file, tibco_universal_installer.timestamp.username_install.log is available in the followinglocations.• Windows - Documents and Settings\username\.TIBCO\install_timestamp. If you are using Windows 7 and

above - Users\username\.TIBCO\install_timestamp.

• Linux - user_home_dir\.TIBCO\install_timestamp.

The installer log file captures the following information:• Installation home details such as the user that invoked the installer, hostname, Java home in the installation

home, operating system details, and so on• List of assemblies installed• Information related to the Ant scripts that are executed by the installerTo change the location of the installer log file, specify the option -V logFile="myLogFile" when you run the installer.

TIBCO_JRE Error Message During UpgradeProblem

When you perform an upgrade, the installer sometimes displays an error that states TIBCO_JRE files arelocked, even if JRE is not running and the installer is not using TIBCO_JRE.

Workaround

Reboot the system on which the installer is running.

CONFIGURE_FAILED Message in Single Machine SetupProblem

During development, you install all components on a single machine. After the Administrator serverconfiguration, select TIBCO Adapter Implementation Type App Template from the list of application templatesto deploy on the default node. A CONFIGURE_FAILED message results.

Workaround

Installation instructions clearly state not to select this option. Because the TIBCO Hawk Agent workflow isnot run at this time, deployment of this component results in a startup failure with a CONFIGURE_FAILEDmessage.


Installing ActiveMatrix Using a Non-default Administrator AccountScenario

This is a scenario on Windows 2008 or Windows 7 when the product is installed using a non-defaultAdministrator user. Assume you have two accounts: Administrator, which was created at the operationsystem setup, and tibco, which was created afterwards and added to Administrator group. As a result, tibcois considered as a non-default Administrator. With a non-default Administrator, there are some issues youmight encounter:

ResolutionProblem

Start TIBCO ConfigurationTool.exe with the Run AsAdministrator option.

The file, machine.xmi, is locked when you createTIBCO ActiveMatrix Administrator Server usingTIBCO Configuration Tool.

Start the command prompt using the Run asAdministrator option.

Access is denied while starting or stopping TIBCOHost from the command-prompt.

ActiveMatrix Administrator Not Starting Due to Database Connection FailureProblem

The ActiveMatrix Administrator server is not starting, or you are unable to login due to database connectionfailure.

Workaround

Perform the following procedure to update database configuration:1. Start the SystemNode and tibcohost, if stopped, even if the ActiveMatrix Administrator is not working.2. In your database server, unlock the user account. When several failed attempts are made at entering a

password, ActiveMatrix locks an account. This is often encountered while using ActiveMatrix Administratorwith Oracle, especially if an expired password has been changed.

For Oracle, you can unlock a user account by executing the following command in sqlplus as aDBA:SQL> alter user <username> account unlock;

3. Launch TIBCO Configuration Tool, update the database configuration for the core ActiveMatrixAdministrator as follows:a. Select Edit TIBCO ActiveMatrix Administrator Server Configuration .b. From the Select Server Configuration drop-down list, select the enterprise name and server name.c. Check Edit Database Settings.d. If the users or groups are defined in the Administrator database and not in an LDAP server, select Edit

Authentication Realm Settings .e. Click Test Connection to verify the settings.f. Click Configure to apply the changes. When the update is complete, TIBCO Configuration Tool restarts

the system node.g. Wait for a few minutes for the system node to become available.

4. Login to ActiveMatrix Administrator UI, and perform the following steps:a. Navigate to Shared Objects > Resource Templates, and select TIBCO ActiveMatrix Governance JDBC

Resource.

Select GovernanceJDBCSharedResource if you upgraded from a prior version. If you do notsee this resource template, it means monitoring services were not deployed, and hence you canskip this step.


126 | Troubleshooting

b. In the details section of this resource template, make corrective changes to the configuration, if neededand save the changes.

c. Reinstall resource instances and restart applications.d. From the Resource Instances tab of the details section, verify that the resource instance is successfully

installed and is in the Running state. There will be multiple resource instances if you have a replicatedAdministrator.

5. Repeat step 4 for the Resource Templates - TIBCO ActiveMatrix LogService JDBC Resource and TIBCOActiveMatrix PayloadService JDBC Resource.

If you upgraded from prior releases, the names will be cl_logservice_jdbc andpayloadJdbcSharedResource. If you do not see these resource templates, it means common loggingservices were not deployed, and hence you can skip this step.

6. Restart the SystemNode one more time using the following tibcohost commands:a. To stop tibcohost (.exe): stopNodes -nodeName SystemNode. Wait for a few minutes for a graceful

shutdown.b. To start tibcohost (.exe): startNodes -nodeName SystemNode. Wait for a few minutes for the

SystemNode to come up.After the restart, the new database settings are fully in effect.


Troubleshooting | 127