Tib Amx Administration

TIBCO ActiveMatrix®

AdministrationSoftware Release 2.3February 2010

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN LICENSE.PDF) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.TIB, TIBCO, TIBCO ActiveMatrix, TIBCO Adapter, TIBCO Administrator, TIBCO AutoMeditate, TIBCO Enterprise Message Service, ActiveMatrix, AutoMediate, Predictive Business, Information Bus, The Power of Now, and TIBCO Rendezvous are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. PLEASE SEE THE README.TXT FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.Copyright © 2005-2010 TIBCO Software Inc. ALL RIGHTS RESERVED.TIBCO Software Inc. Confidential Information

| iii

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii

Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiiTIBCO ActiveMatrix Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiiOther TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiiThird Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix

Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx

How to Contact TIBCO Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiii

Chapter 1 TIBCO ActiveMatrix Administrator Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2TIBCO ActiveMatrix Administrator Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2ActiveMatrix Administrator Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Life Cycle of the ActiveMatrix Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Configuring the Runtime. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Two-Step Configuration: First Define, Then Install . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Starting Installed Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Deploying Service Assemblies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8Two-Step Deployment: First Configure, Then Deploy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9Life Cycle Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Shared Resource Life Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Customizing HTTP Shared Resource Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 2 Infrastructure Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

ActiveMatrix Database Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Database Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14HSQLDB Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

TIBCO Management Daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Starting TIBCO Management Daemon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Stopping TIBCO Management Daemon. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18UDP, Discovery, and Management Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

TIBCO ActiveMatrix Administration

iv | Contents

Changing Management Daemon Status Reporting and Polling Intervals . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

TIBCO Enterprise Message Service™ Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Starting the TIBCO Enterprise Message Service Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

TIBCO Administrator™ and TIBCO Hawk® . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Starting TIBCO Administrator and TIBCO Hawk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Chapter 3 ActiveMatrix Administrator Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Creating the First ActiveMatrix Administrator Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Before Running the ActiveMatrix Administrator Server Creation Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Running the ActiveMatrix Administrator Server Creation Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27ActiveMatrix Administrator Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Deleting the ActiveMatrix Administrator Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Authentication Realm Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Local XML File Realm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31TIBCO Administrator Realm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Database Realm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35LDAP Realm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Updating the Authentication Realm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Database Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Database Configuration Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Updating the Database Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Pre-creating ActiveMatrix Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Default Runtime Node Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Starting and Stopping the ActiveMatrix Administrator Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Starting and Stopping the ActiveMatrix Administrator Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Chapter 4 ActiveMatrix Administrator Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

ActiveMatrix Administrator Interfaces Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Graphical Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66Command-Line Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66checkstatus Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

ActiveMatrix Administrator Graphical Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Logging in to the ActiveMatrix Administrator Graphical Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Graphic Interface Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Perspective Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Working with the Graphical User Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

ActiveMatrix Administrator Command-Line Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Invoking the Command-Line Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87AMXAdminTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89AMXAdminConfigTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99


Contents | v

Chapter 5 Configuring Enterprise Assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Managing Machines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102Binding Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Unbinding Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Bound Machines Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Bound Machine Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Add Search Parameters Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Search Parameters Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Discovered Machines Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Managing Shared Resource Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Creating a Shared Resource Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Editing a Shared Resource Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Setting a Shared Resource Definition Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Deleting a Shared Resource Definition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Resource Definition Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Managing Users, Groups, and Permissions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Users and Groups Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Managing UDDI Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

Managing Keystores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Keystores Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158Creating an Internal Keystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159Creating an External Keystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Deleting a Keystore. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Editing a Keystore Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Reloading an Internal Keystore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Keystore Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Managing ActiveMatrix Administrator Clusters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Database Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162Monitoring Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Log Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163Plug-ins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163ActiveMatrix Administrator Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Working with Substitution Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Creating a Substitution Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Deleting a Substitution Variable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169Editing a Substitution Variable Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169


vi | Contents

Chapter 6 Defining Environments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Environments Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172Environments Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Creating an Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173Environment Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Enable Assets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174Configure Messaging Bus Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Working with Environments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Deleting an Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175Editing an Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Configuring Messaging Bus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Configuring Messaging Bus Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176Managing Messaging Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178

Enabling Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Enabling Machines in an Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Disabling Machines in an Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184Machines Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Enabling UDDI Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Enabling UDDI Servers in an Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186Disabling UDDI Servers in an Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186UDDI Servers Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

Working with Shared Resource Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188Enabling and Disabling Shared Resource Definitions in an Environment . . . . . . . . . . . . . . . . . . . . . . . . . . 188

Chapter 7 Configuring Environments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

Working with Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190Enabling Assets in Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Creating a Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Installing and Uninstalling Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Starting and Stopping Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195Editing a Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196Node Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197Setting Permissions for Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Installing a Shared Library in a Node. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Deleting Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199Configuring Multiple Messaging Servers in Multinode Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Working with the Default Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201Default Connector Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Working with Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Enabling and Disabling Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204Activating and Deactivating a Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Container Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206


Contents | vii

Working with Shared Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Enabling and Disabling Shared Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209Installing and Uninstalling Shared Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Enabling and Disabling Resource Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210Shared Resource Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Working with Substitution Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Overriding a Substitution Variable Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Reverting a Substitution Variable Back to the Global Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213Local Substitution Variables Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Working With Logging Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Chapter 8 Deploying Service Assemblies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

Deployment Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Configuring Service Assemblies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218Deploying a Service Assembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

Uploading a Service Assembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Importing Shared Resource Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220Service Assemblies Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Configuring a Service Assembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Configuring Service Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222Mapping Shared Resource Profiles to Shared Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

Working with Service Assemblies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Deploying and Redeploying Service Assemblies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Starting and Stopping Service Assemblies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224Editing Service Assembly Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225Updating a Service Assembly Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229Downloading a Service Assembly Archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Updating Service Assemblies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230Undeploying Service Assemblies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231Deleting Service Assemblies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Working with Service Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Service Units Table Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Service Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Mapping Shared Resource Profiles to Shared Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Shared Resource Profiles Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Working with Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237Topics Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Working with Substitution Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Working with Logging Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

Working with Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240Services Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240


viii | Contents

Chapter 9 Monitoring Infrastructure and Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

Enabling Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244Monitoring Configuration Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Accessing the Monitor & Manage Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Dashboard View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247Service Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247System Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Infrastructure View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250Environment View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250Machine View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253Node View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Service View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261Searching for Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Integrated Service View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264Service Trail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Service Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266Provides & Consumes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268Deployment Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273UDDI Publishing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Service Instance View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Service Instance Trail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280Service Instance Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Deployment View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285Environment View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285Service Assembly View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287Service Unit View. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

Browse Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

Chapter 10 Managing Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296Event Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Log Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297Starting and Stopping the TIBCO Common Logging Plug-in. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Working with Log Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302Creating a Log Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302Setting the Default Log Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303


Contents | ix

Starting and Stopping a Log Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304Editing a Log Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304Deleting a Log Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305Purging a Log Service Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

Working with Logging Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310Logging Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Using the Log Viewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Displaying the Log Viewer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318Working with the Query Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319Working with Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323Working with the Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326Viewing Log Event Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328Event Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329

Server Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

Appendix A Securing TIBCO ActiveMatrix Communication Channels . . . . . . . . . . . . . . . . . 339

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340

Keystores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342ActiveMatrix Administrator Server Keystores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342ActiveMatrix Node Keystores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343Management Daemon Keystores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344ActiveMatrix Administrator Command-line Tool Keystores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

Enabling HTTPS for ActiveMatrix Administrator Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346Setting up ActiveMatrix Administrator Keystores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346Enabling HTTPS in ActiveMatrix Administrator Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346Enabling HTTPS in ActiveMatrix Administrator Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Enabling SSL for Management Daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

Securing JDBC Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349Oracle Native Thin Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349

Enabling Secure Connections Between Nodes and ActiveMatrix Components . . . . . . . . . . . . . . . . . . . . . . . . 351Enabling Secure Communications Between Nodes and Messaging Servers . . . . . . . . . . . . . . . . . . . . . . 351Enabling Secure Connections Between Nodes and ActiveMatrix Servers . . . . . . . . . . . . . . . . . . . . . . . . . 353

Enabling Secure Connections to Auxiliary Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355Enabling Secure Connections to LDAP Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355Enabling Secure Connections to UDDI Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

TRA File Locations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

Appendix B Messaging Scenarios for In-only MEPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Race Condition Between Consumer and Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

Messages In AMX Binding Queue. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

Messages in JMS Container Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361


x | Contents

Appendix C Session and Thread Pools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364Configuration Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364Life Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365

Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

Interaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

Best Practices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368Session Count and Max Pool Size. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368Service Optimization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368Local Invocations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368Session Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369

Appendix D ActiveMatrix Server Performance Tuning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372

JVM Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373Using Client and Server Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373Allocated Memory Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

ActiveMatrix Administrator Server Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376Number of Web-worker Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376Acceptor-Thread Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Appendix E Publishing Services to ActiveMatrix Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

Enabling Non-Administrator Users to Publish to the ActiveMatrix Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

Adding Permission to Publish to a Business. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

Appendix F checkstatus Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381

checkstatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

StatusCheckerConfig.properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387


| xi

Figures

Figure 1 TIBCO ActiveMatrix Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Figure 2 SQL Server DDL User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Figure 3 SQL Server DML User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55

Figure 4 Welcome Page. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Figure 5 Enterprise Assets Tab Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Figure 6 Configure Enterprise Assets Perspective. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Figure 7 Configure Environments Perspective. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

Figure 8 Deploy to Environment Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

Figure 9 Monitor & Manage Perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Figure 10 System Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Figure 11 Parent-Child Relationships. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Figure 12 Object Association . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Figure 13 Local Network Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Figure 14 Bridged Network Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Figure 15 Relationships between ActiveMatrix Administrator, Machines, and Environments . . . . . . . . . . . . 107

Figure 16 Components. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

Figure 17 Node Status Life Cycle. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194

Figure 18 Container Status Life Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Figure 19 Shared Resource Status Life Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

Figure 16 Service Assembly State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229

Figure 20 Services and Service Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261

Figure 21 UDDI Publishing Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Figure 22 ActiveMatrix Logging Environment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Figure 23 Log Navigator and Log Viewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Figure 24 Node and Container Logging Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Figure 25 Service Assembly and Service Unit Logging Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311

Figure 26 Query Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

Figure 27 Model Selection Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321


xii | Figures

Figure 28 Filter Area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Figure 29 Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326

Figure 30 Log Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Figure 31 TIBCO ActiveMatrix Communication Channels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341


| xiii

Tables

Table 1 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xx

Table 2 Syntax Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii

Table 3 ActiveMatrix Administrator Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Table 4 Local XML File Realm Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Table 5 TIBCO Administrator Realm Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Table 6 Database Realm Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Table 7 Database Realm Authentication Superuser Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Table 8 LDAP Realm Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Table 9 Search Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Table 10 LDAP Mapping Details Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Table 11 Superuser Registration Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Table 12 Database Configuration Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Table 13 Default Runtime Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Table 14 Actions and Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

Table 15 Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Table 16 Supported Objects and Their Attribute Reference Sections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Table 17 Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Table 18 Bound Machines Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111

Table 19 Bound Machine Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112

Table 20 Add Search Parameters Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

Table 21 Search Parameters Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Table 22 Discovered Machines Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114

Table 23 HTTP Server Shared Resource Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Table 24 Identity Shared Resource Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123

Table 25 JDBC Shared Resource Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Table 26 Database Drivers and URL Templates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Table 27 JMS Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

Table 28 JNDI Shared Resource Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131


xiv | Tables

Table 29 JNDI SSL Application Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Table 30 Rendezvous Shared Resource Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Table 31 SSL Server Shared Resource Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

Table 32 Groups List Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147

Table 33 UDDI Server Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

Table 34 Keystore Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Table 35 Database Configuration Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162

Table 36 Plug-ins Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Table 37 Administrator Servers Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Table 38 Administrator Server Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Table 39 Environments Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

Table 40 Environment Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Table 41 Messaging Server Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Table 42 Machines Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

Table 43 UDDI Server Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Table 44 Nodes Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192

Table 45 Node Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

Table 46 Default Connector Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201

Table 47 Container Type Attribute Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

Table 48 Container Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Table 49 Shared Resource Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Table 50 Local Substitution Variables Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Table 51 Service Assemblies Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Table 52 Service Assembly Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

Table 53 Actions and Service Assembly Status Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230

Table 54 Service Units Table Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Table 55 Mapped Nodes Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Table 56 Substitution Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Table 57 Shared Resource Profiles Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236

Table 58 Topics Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237

Table 59 Substitution Variables Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Table 60 Services Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240


Tables | xv

Table 61 Monitoring Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244

Table 62 Top 20 Hits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Table 63 Top 20 Faults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Table 64 Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

Table 65 Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

Table 66 Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250

Table 67 Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

Table 68 Machine Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253

Table 69 Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254

Table 70 Node Trail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Table 71 Node Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

Table 72 Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Table 73 Shared Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Table 74 Service Instances. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Table 75 Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

Table 76 Service Trail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Table 77 Services Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

Table 78 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Table 79 Provides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Table 80 Interface Consumed By . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Table 81 Consumes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Table 82 Interface Invokes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270

Table 83 Composite Service Consumes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Table 84 Interface Invokes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271

Table 85 Composite Reference Provides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Table 86 Interface Consumed By . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

Table 87 Interfaces and Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Table 88 Nodes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274

Table 89 UDDI Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276

Table 90 Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278

Table 91 Endpoint Chosen for Publication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279

Table 92 Service Instance Trail. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280


xvi | Tables

Table 93 Service Instance Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

Table 94 Performance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283

Table 95 Interface and Operations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

Table 96 Service Assemblies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286

Table 97 Service Assembly Trail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Table 98 Service Assembly Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287

Table 99 Service Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

Table 100 Service Trail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Table 101 Service Unit Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Table 102 Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

Table 103 Log Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Table 104 Log Service Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306

Table 105 Parent-Child Logging Configuration Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Table 106 Object Logging Configuration Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Table 107 Object Logging Configuration Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

Table 108 Filter Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Table 109 Base Event Format Attribute Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Table 110 Situation Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Table 111 Engine Event Format Attribute Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Table 112 BW Engine Event Format Attribute Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Table 113 Server Log Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

Table 114 JNDI SSL Application Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351

Table 115 TRA File Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356

Table 116 Role (Consumer/Provider), MEP, and Session/Thread Pool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

Table 117 JVM Client and Server Mode Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373


| xvii

Preface

The TIBCO ActiveMatrix® Administrator is a web-based user interface and server for configuring ActiveMatrix® environments and deploying ActiveMatrix services into them. ActiveMatrix provides a scalable and extensible platform for developing, deploying, and managing applications that conform to a service-oriented architecture.

Topics

• Related Documentation, page xviii

• Typographical Conventions, page xx

• How to Contact TIBCO Support, page xxiii


xviii | Related Documentation

Related Documentation

This section lists documentation resources you may find useful.

TIBCO ActiveMatrix DocumentationThe following documents form the core of the TIBCO ActiveMatrix documentation set:

• TIBCO ActiveMatrix Concepts: Read this manual before reading any other manual in the documentation set. This manual describes terminology and concepts of the ActiveMatrix platform. The other manuals in the documentation set assume you are familiar with the information in this manual.

• TIBCO ActiveMatrix Composite Editor User’s Guide: Read this manual to learn how to develop and package ActiveMatrix composites.

• TIBCO ActiveMatrix Administration: Read this manual to learn how to manage the ActiveMatrix runtime and deploy and manage ActiveMatrix services.

Other TIBCO Product DocumentationYou may find it useful to read the documentation for the following TIBCO products:

• TIBCO ActiveMatrix® Service Bus

• TIBCO ActiveMatrix® Service Grid

• TIBCO ActiveMatrix® BusinessWorks

• TIBCO ActiveMatrix® Registry

• TIBCO ActiveMatrix® Policy Manager

• TIBCO Enterprise Message Service™

• TIBCO Adapter™

• TIBCO Administrator™

• TIBCO Hawk®

• TIBCO Rendezvous®


Preface | xix

Third Party DocumentationTIBCO ActiveMatrix software supports the following standards:

• Service Component Architecturehttp://www.osoa.org/display/Main/Service+Component+Architecture+Specifications

• World Wide Web Consortium web services activityhttp://www.w3.org/2002/ws/

— Simple Object Access Protocol (SOAP) 1.1 W3C Notehttp://www.w3.org/TR/2000/NOTE-SOAP-20000508/

— WSDL 1.1 W3C Note http://www.w3.org/TR/wsdl

• OASIS http://www.oasis-open.org/committees/tc_cat.php?cat=ws

— UDDI Version 3 OASIS Standard http://www.oasis-open.org/specs/index.php#uddiv2


http://www.osoa.org/display/Main/Service+Component+Architecture+Specifications

xx | Typographical Conventions

Typographical Conventions

The following typographical conventions are used in this manual.

Table 1 General Typographical Conventions

Convention Use

TIBCO_HOME

ENV_NAME

ENV_HOME

AMX_HOME

AMX_ADMIN_HOME

Many TIBCO products are installed within the same home directory. This directory is referenced in documentation as TIBCO_HOME. The value of TIBCO_HOME depends on the operating system. For example, on Windows systems the default value is C:\tibco.

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

• Name Identifies the installation environment. The name is appended to the name of Windows services created by the installer and is used in the path to the product in the Windows Start > All Programs menu. This directory is referenced in documentation as ENV_NAME.

• Description Provides information about what the environment contains or is used for.

• Path The directory into which the product is installed. This directory is referenced in documentation as ENV_HOME. The value of ENV_HOME depends on the operating system. For example, on Windows systems the default value is C:\tibco.

TIBCO ActiveMatrix installs into a directory inside ENV_HOME. This directory is referenced in documentation as AMX_HOME. The value of AMX_HOME depends on the operating system. For example, on Windows systems the default value is C:\tibco\amx\.

TIBCO ActiveMatrix Administrator installs into a directory inside ENV_HOME. This directory is referenced in documentation as AMX_ADMIN_HOME. The value of AMX_ADMIN_HOME depends on the operating system. For example, on Windows systems the default value is C:\tibco\amxadministrator\.

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

Use MyCommand to start the foo process.


Preface | xxi

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

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

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

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

italic font Italic font is used in the following ways:

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

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

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

Key combinations Key name separated by a plus sign indicate keys pressed simultaneously. For example: Ctrl+C.

Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q.

The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result.

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

Table 1 General Typographical Conventions (Cont’d)

Convention Use


xxii | Typographical Conventions

Table 2 Syntax Typographical Conventions

Convention Use

[ ] An optional item in a command or code syntax.

For example:

MyCommand [optional_parameter] required_parameter

| A logical ’OR’ that separates multiple items of which only one may be chosen.

For example, you can select only one of the following parameters:

MyCommand para1 | param2 | param3

{ } A logical group of items in a command. Other syntax notations may appear within each logical group.

For example, the following command requires two parameters, which can be either the pair param1 and param2, or the pair param3 and param4.

MyCommand {param1 param2} | {param3 param4}

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

MyCommand {param1 | param2} {param3 | param4}

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

MyCommand param1 [param2] {param3 | param4}


Preface | xxiii

How to Contact TIBCO Support

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

• For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site:

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

• If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a user name and password. If you do not have a user name, you can request one.


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

https://support.tibco.com

xxiv | How to Contact TIBCO Support


| 1

Chapter 1 TIBCO ActiveMatrix Administrator Overview

This chapter summarizes the tasks involved in setting up a TIBCO ActiveMatrix runtime using TIBCO ActiveMatrix Administrator.

Topics

• Introduction, page 2

• Life Cycle of the ActiveMatrix Runtime, page 7

• Shared Resource Life Cycle, page 10


2 | Chapter 1 TIBCO ActiveMatrix Administrator Overview

Introduction

This manual explains how to set up and administer a TIBCO ActiveMatrix runtime.

This manual does not explain basic ActiveMatrix concepts. If you are not yet familiar with them, read at least the first chapter in TIBCO ActiveMatrix Concepts.

TIBCO ActiveMatrix Administrator ArchitectureTIBCO ActiveMatrix Administrator is the utility used to create, configure, manage, and monitor various objects in the ActiveMatrix runtime. These objects include enterprise assets, environments, machines, nodes, shared resources, containers, service assemblies, service units, and services. Figure 1 on page 3 shows TIBCO ActiveMatrix Administrator components, the relationship between ActiveMatrix Administrator and other processes, and relationship between TIBCO ActiveMatrix Administrator and ActiveMatrix machines and nodes.


Introduction | 3

Figure 1 TIBCO ActiveMatrix Administrator

The TIBCO ActiveMatrix Administrator administration architecture consists of the following components:

• ActiveMatrix Administrator Server Gathers management data from nodes, responds to requests from the ActiveMatrix Administrator graphical and command-line UIs, interacts with the authentication realm to authenticate users, and interacts withTIBCO Management Daemon to manage nodes.

• ActiveMatrix Administrator Cluster Groups one or more ActiveMatrix Administrator servers. ActiveMatrix Administrator servers within a cluster share a database and authentication realm and are kept synchronized.

• ActiveMatrix Database Stores ActiveMatrix administration data.

AMA Machine 1

AM Machine 2Authentication

Realm

AMAServer 1

AMA Graphical UI

Management Daemon

Database

Management Daemon

AM Node

AMA Command-Line

Interface

AMAServer 2

AM Machine 1

AM Node

Legend

AM

AMA

TIBCO ActiveMatrix

TIBCO ActiveMatrix Administrator

AMA Cient Machine

AMAMachine 2

AMA Cluster

www



• Authentication Realm Manages user authentication data. The authentication realm can be provided either by TIBCO Administrator (see Relationship to TIBCO Administrator™ Software) or by another server or a file.

• ActiveMatrix Administrator Graphical UI Provides a graphical user interface.

• ActiveMatrix Administrator Command-Line Interface Provides a script-based interface.

• Management Daemon Gathers installation information and exposes ActiveMatrix node life cycle operations. For details, see Relationship to TIBCO® Management Daemon Software on page 4.

Relationship to TIBCO® Management Daemon Software

ActiveMatrix Administrator uses TIBCO Management Daemon software to enable configuration and management of ActiveMatrix infrastructure. TIBCO Management Daemon provides bootstrap and machine-level management functionality. It runs on all the machines where ActiveMatrix software is installed.

From ActiveMatrix Administrator you specify Management Daemon process properties so you can administer the ActiveMatrix runtime on the machines managed by those processes.

Relationship to TIBCO Administrator™ Software

TIBCO Administrator software and ActiveMatrix Administrator perform some similar functions for different TIBCO product families. Both allow you to perform deployment, management, and monitoring tasks for products in their respective product families.

TIBCO Administrator software is required in an ActiveMatrix Administrator runtime only if you use the TIBCO Administrator authentication realm (see TIBCO_HOME/tra/domain/domainName/bin/hawkagent_domainName.exe on page 23).

While TIBCO Administrator uses TIBCO Rendezvous® and TIBCO Hawk® for communication, ActiveMatrix Administrator uses the protocols SOAP/HTTP and JMX/JMXMP.

ActiveMatrix Administrator SetupThis section gives an overview of the relationships you set up between ActiveMatrix Administrator servers, clusters, machines, and environments. See ActiveMatrix Administrator Cluster, Machine, and Environment Relationships on page 106 for more details on these relationships.


Introduction | 5

TIBCO ActiveMatrix Administrator Servers and Clusters

The first step in setting upActiveMatrix Administrator is to create one or more ActiveMatrix Administrator servers. ActiveMatrix Administrator servers are members of a cluster. The cluster is created when the first server is created. ActiveMatrix Administrator automatically keeps the servers within a cluster synchronized.

Each cluster administers a different set of environments. You may need only one cluster, or you may require more, for example, one for each geographic region of a global enterprise. Conversely, an environment can be administered by only one cluster.

Within each cluster, it is recommended that you create more than one server for the following reasons:

• To permit one server to take over from another in the event of server failure. This is particularly recommended in production systems.

• To enable flexibility in administering multiple ActiveMatrix runtimes, that is, different sets of ActiveMatrix environments and their nodes.

Database Tables

ActiveMatrix Administrator data is stored in a database.

You select and configure database tables when creating the first server in a cluster. AllActiveMatrix Administrator servers in a cluster use the same database tables and you cannot change databases after you create the first server in the cluster.

The database tables are used only for servers in that cluster and not for any other cluster. This keeps different sets of environments administered by different clusters separate from each other for better management. Thus, when you invoke the URL of any server in a cluster in the ActiveMatrix Administrator user interface you access the administration data for the entire cluster, not just for that particular server.

Authentication Realms

An authentication realm describes the method of storing information about ActiveMatrix Administrator users and groups. Access to ActiveMatrix Administrator UI functions and ActiveMatrix runtimes is controlled based on permissions granted to specific users and groups.

You select and configure the authentication realm when creating the first server in a cluster. All ActiveMatrix Administrator servers in the same cluster use the same authentication realm and you cannot change realms after you create the first server in the cluster. Therefore, before you create the first ActiveMatrix



Administrator server in a cluster, decide which kind of authentication realm you will use: Local XML File, Database, TIBCO Administrator, or LDAP. See the following sections for feature and configuration information for the different types of realms:

• Local XML File Realm on page 31

• TIBCO Administrator Realm on page 32

• Database Configuration on page 48

• LDAP Realm on page 39

Binding Machines to ActiveMatrix Administrator Clusters

ActiveMatrix software must be installed on all machines that participate in the ActiveMatrix runtime that you are to setting up. Using the ActiveMatrix Administrator graphical or command-line interfaces, you bind machines to the ActiveMatrix Administrator cluster. You choose machines that to use for the ActiveMatrix runtime administered by this cluster. Finally, for each bound machine, you specify which environments can use the ActiveMatrix installations it manages.


Life Cycle of the ActiveMatrix Runtime | 7

Life Cycle of the ActiveMatrix Runtime

After you have created and started the servers and connected the Management Daemon process on machines you want to use, you are ready to configure and start the TIBCO ActiveMatrix runtime and deploy services to it.

Before You BeginBefore you set up the runtime, ensure that you have a clear deployment plan. The plan determines where service units run. It also specifies the interactions with enterprise applications outside the ActiveMatrix platform, and what physical resources are needed by the service units that are deployed to the various containers.

Configuring the RuntimeAfter you have bound machines to use in your ActiveMatrix runtime, you use the ActiveMatrix Administrator user interface to configure enterprise assets and define and configure one or more environments on those machines. Enterprise asset configuration involves:

• Configuring UDDI servers. See Managing Users, Groups, and Permissions on page 139.

• Setting up users, groups, and permissions. See Managing Users, Groups, and Permissions on page 139.

• Configuring shared resource definitions. These define connection details for physical resources required by the deployed service units. See Managing Shared Resource Definitions on page 116.

• Registering keystores. See Managing Keystores on page 158.

• Defining Environments. See Defining Environments on page 171.

Environment configuration involves the following activities:

• Configuring Messaging Bus settings and setting up the messaging server or servers for each environment. See Configuring Messaging Bus on page 176.

• Configuring nodes and containers for each environment and installing them. See Working with Nodes on page 190 and Working with Containers on page 204.

• Specifying shared resources for each node. These enable the services deployed in each node’s containers to connect with physical resources as required. Each shared resource points to a shared resource definition for connection details.



The indirection introduced by shared resources enables you to control use of the physical resource at the node level (after deployment). See Working with Shared Resources on page 209.

Two-Step Configuration: First Define, Then InstallWhen you are configuring an environment’s nodes and shared resources you first define each object and then you install it. The object definitions are stored in the database. The definitions persist even if you uninstall an installed object. You can later reinstall it as needed.

The objects are installed onto machines that have been bound to the ActiveMatrix Administrator cluster.

Before you can change the definition of an installed object, first uninstall it. Then change the definition as required, and install it again.

Starting Installed Nodes You can define, install, and start nodes following different practices to suit your needs. You may define a node, install it, and then start it to ensure that it is running correctly. This way you can ensure that your runtime is working as expected at each step. Or you can define several nodes, then start them all.

Before you can deploy a service assembly, the nodes and containers that service units will deploy into must be running. See Working with Nodes on page 190 and Working with Containers on page 204 for related procedures.

Deploying Service AssembliesAfter you have configured, installed, and started the nodes, and installed the shared resources you need in each node, you are ready to deploy. Deployment involves the following activities:

• Uploading a service assembly archive.

• Configuring the service assembly. This involves determining on which nodes the service assembly’s service units will be deployed and which shared resources to use for the shared resource profiles specified in the service units. As needed, you can also override substitution variables set in the service assembly archive.

• Deploying the service assembly.

• Starting the service assembly.


Life Cycle of the ActiveMatrix Runtime | 9

You can upload and deploy multiple service assemblies, and you can upload one service assembly multiple times, configuring it for different deployment needs each time.

See Chapter 8, Deploying Service Assemblies, on page 217 for details on these activities.

For more details on the design-time activities whose output is the service assembly, see TIBCO ActiveMatrix Composite Editor User’s Guide and TIBCO ActiveMatrix Service Grid Component Developer’s Guide product.

Two-Step Deployment: First Configure, Then DeployAfter you upload a service assembly archive, you configure it before deployment.

You can upload multiple service assembly archives and configure each of them, providing each one with a unique service assembly name. You can then start and stop each one separately.

You can also upload the same service assembly archive multiple times, configuring the service assembly differently in each case, as needed, for example, deploying into different nodes, or into a different environment. You save each configuration with a different service assembly name.

Life Cycle ManagementAfter this point, you perform life cycle management on the nodes and containers and service assemblies as required, and continue to make configuration changes as the runtime develops over time. You can start and stop each service assembly separately.



Shared Resource Life Cycle

Shared resources provide connection details for specific physical resources used by services, components, and references. During development, services, components, and references do not explicitly contain connection details. Instead, a composite or component developer specifies a shared resource profile that declares the types of physical resources the service, component, or reference require. The profiles may then bound to shared resources or may be left unbound. When the service assembly is configured for deployment, shared resource profiles are mapped to shared resources available on the nodes on which the assembly will be deployed.

You create a node’s shared resources from shared resource definitions defined at the enterprise assets level. The life cycle of shared resources and the interaction of the life cycle with service assembly deployment is:

1. Create shared resource definitions in enterprise assets. See Managing Shared Resource Definitions on page 116.

2. Enable shared resource definitions in an environment. See Working with Shared Resource Definitions on page 188.

3. Enable shared resource definitions in a node. When you start the node, shared resources are installed in the node for each enabled definition. If a shared resource definition is enabled for a node after the node is started, you must manually install the shared resource in the node. See Working with Shared Resources on page 209.

4. Upload service assembly. If a shared resource definition required by the service assembly is not present in the environment, you can import shared resources defined in the service assembly to the enterprise and environment when you upload a service assembly. See Uploading a Service Assembly on page 220.

5. Map shared resource profiles to shared resources. If a node to which you have mapped the service assembly is missing shared resources that you have specified in the mapping between shared resource profiles and shared resource, you can add them to the node. See Mapping Shared Resource Profiles to Shared Resources on page 236.


Shared Resource Life Cycle | 11

Customizing HTTP Shared Resource DefinitionsAt design-time, a service with a SOAP binding uses a HTTP shared resource profile which is mapped to an HTTP shared resource. When the service assembly containing the resource is uploaded the shared resource is imported into the enterprise as an HTTP server shared resource definition. When the service assembly is configured for deployment, the shared resource profile is mapped to exactly one shared resource of type HTTP server, often the resource that was imported. This constraint can lead to scalability limitations.

Suppose you want to run this SOAP service on multiple nodes for load balancing or fault tolerance or both. The nodes may be running on one machine or across multiple machines. An HTTP server shared resource must be available on all nodes where that SOAP service runs.

If the nodes run on the same machine, the HTTP server shared resources on each node must use different port numbers to avoid conflicts. If the nodes run on different machines, the HTTP server shared resources on each node must use a different host name.

However, because a single HTTP server shared resource definition is used to create the shared resource, when configuring the definition you cannot explicitly specify the hostname and port number variations required to run it on multiple nodes.

The solution is to use a template shared resource definition that can be customized for each node. A template shared resource definition has at least one property bound to a substitution variable. Substitution variables are constants specified at the enterprise level, but can be overridden at the node level.

Depending on your requirements (multiple nodes on one machine or multiple nodes on multiple machines or a mixture of both), you bind the hostname and port properties to substitution variables in the shared resource definition and customize the substitution variables per node as follows:

• If the node is running on a different machine than the value specified in the shared resource definition, override the hostname property value for each node.

• If the nodes are running on the same machine, override the port property value for each node.




| 13

Chapter 2 Infrastructure Servers

This chapter discusses the infrastructure servers that must be running in order for the ActiveMatrix runtime to be operational.

In a development or test setting, ActiveMatrix administrators may be responsible for all these servers. In a production environment, however, other administrators may be responsible for some or all the servers.

Topics

• ActiveMatrix Database Server, page 14

• TIBCO Management Daemon, page 17

• TIBCO Enterprise Message Service™ Server, page 22

• TIBCO Administrator™ and TIBCO Hawk®, page 23


14 | Chapter 2 Infrastructure Servers

ActiveMatrix Database Server

The ActiveMatrix database server maintains ActiveMatrix administration data. You must start the database server before creating or running an ActiveMatrix Administrator server (see ActiveMatrix Administrator Server on page 25) or creating or starting an ActiveMatrix node (see Working with Nodes on page 190).

Database OverviewThis section describes how to set up and start the ActiveMatrix database server.

Setting up the Database Server

Setting up HSQLDB

You can use the HSQLSDB database server provided with ActiveMatrix products. When you complete the Database Details dialog during ActiveMatrix Administrator server creation, you specify a datastore name. One database (datastore), amx, is available without any prior setup. If you use the provided database with the default user credentials, you do not have to do any setup ahead of time.

To create a another datastore, follow the procedure described in Creating a New HSQLDB Datastore on page 15. All new datastores use the following default user credentials: username sa and no password. The sa user has DBA privileges by default.

To add users to HSQLDB or change existing user attributes, you can use a client tool such as DBVisualizer.

Setting up Oracle, SQL Server, or Sybase

Each cluster requires exclusive use of user-defined tables (that is, not the system tables) in an Oracle, SQL server, or Sybase database. Before you create the ActiveMatrix Administrator server, ensure that you have the credentials of a user with connect and resource privileges to user-defined tables. You specify the user and database information in the Database Details dialog during installation.


ActiveMatrix Database Server | 15

Starting the Database Server

You must start your database server before you start the ActiveMatrix Administrator server creation wizard. To start the HSQLDB server, follow the procedure in Starting the HSQLDB Database Server on page 15. If you are using a third-party database product, consult your database product documentation for the procedure.

HSQLDB DatabaseThis section describes how to start the HSQLDB database server and how to create a new HSQLDB datastore.

Starting the HSQLDB Database Server

The HSQLDB database server stores environment configuration data. You can use the HSQLDB database provided with ActiveMatrix software, or another supported database. See the installation manual for your product for details on which database products are supported.

To start the HSQLDB database server, do one of the following

• Windows From the Start menu, select All Programs > TIBCO > TIBCO ActiveMatrix > Start HSQLDB Server

• Windows or UNIX From the command line, run AMX_HOME/hsqldb/bin/amx-db.

Creating a New HSQLDB Datastore

You can serve multiple ActiveMatrix Administrator clusters using one HSQLDB database server. To do this you create a datastore for each cluster by adding two lines in the server.properties file. The first line specifies location of the data files for the datastore. The second line specifies the datastore name. When you create an ActiveMatrix Administrator server, you specify this datastore name. Here is an example properties file. It shows two lines added for a datastore called acme:

#database connection url would be 'jdbc:hsqldb:hsql://localhost:<server.port>/<server.dbname.0>'server.port=1234server.database.0=../data/amxserver.dbname.0=amxserver.database.1=../dataAcme/acmeserver.dbname.1=acmeserver.silent=trueserver.trace=false



Note that the number is incremented to 1 in both lines. Use the same number for each pair of lines used to define a datastore’s properties; the number must be different for each datastore.

Specifying the Location of the Datastore Data Files

The value of the line server.database.n specifies the location of the directory that holds the datastore’s data files and the prefix for the data file names. The directory path is relative to the installation directory of the database server. For example, if you specify ../dataAcme/acme, the directory is AMX_HOME/hsqldb/dataAcme

and the data files in that directory are acme.lck, acme.log., and acme.properties.

To Create a New HSQLDB Datastore

1. Open the following file for editing:

AMX_HOME/hsqldb/bin/server.properties

2. For each datastore, add a section (as explained in the introduction) using the following format:

server.database.n=../Filepath/DbName server.dbname.n=DbName

3. Save the file.


TIBCO Management Daemon | 17

TIBCO Management Daemon

TIBCO Management Daemon software bootstraps the management infrastructure and supports node life cycle operations. The Management Daemon process on each machine running ActiveMatrix software must be running at all times.

This section describes how to start the TIBCO Management Daemon process, how to configure ports that it listens on, and how to configure status reporting and polling intervals.

Starting TIBCO Management Daemon• Windows From the Start menu, select All Programs > TIBCO > ENV_NAME >

TIBCO Management Daemon 2.0 > Management Daemon

You can also start the Management Daemon Windows service as follows:

a. Open Control Panel > Administrative Tools > Services.

b. Right-click the service TIBCO Management Daemon 2.0 and select Start.

• Windows or UNIX From the command line, run

ENV_HOME/managementdaemon/2.0/bin/managementdaemon

The last lines of the output are similar to the following:

Oct 26, 2007 5:18:35 PM com.tibco.neo.launch.osgi.Activator mainINFO: TIBCO Launch Activator launched at 10/26/07 5:18 PM.********************* ActiveMatrix Daemonlet Started *********************

Machine names having underscore "_" characters in their hostname are not supported by TIBCO Management Daemon.

Due to a limitation of JDK 1.5, Management Daemon broadcasts on all available network interfaces on the machine. When the Management Daemon process starts up, you may observe exceptions on the Management Daemon console for interfaces that are not connected. You can ignore the exceptions or use the error messages, which indicate the connected interfaces, to fine tune the configuration of the UDP listening port by following the instructions in the next section.



Stopping TIBCO Management Daemon• Windows

a. Open Control Panel > Administrative Tools > Services.

b. Right-click the service TIBCO Management Daemon 2.0 and select Stop.

• UNIX Management Daemon does not support a –stop argument to shut down gracefully. You can shut down Management Daemon by using Ctrl+C in the console or using kill or kill -9 commands. Using Ctrl+C causes any nodes running on that machine to be shut down as well.

UDP, Discovery, and Management Ports

UDP Listening Port

By default, the port on which the Management Daemon processes listen for requests sent using the UDP protocol is set to 1965.

Management Daemon reads its port from its configuration file: ENV_HOME/managementdaemon/2.0/config/configuration.xml

The information is located in the discoverySocketAddresses element. For example:

<list name="discoverySocketAddresses"><string>udp://239.100.106.107:1965</string></list>

There can be multiple items in the list. The address format can be:

• udp://239.100.106.107:port With no fragment, Management Daemon multicasts on all network interfaces, and any errors are logged as SEVERE.

• udp://239.100.106.107:port#* The wildcard fragment instructs Management Daemon to multicast on the default network interface. That is, it does not specify a network interface and lets the JDK 1.5 implementation choose one. In many cases this works as expected.

• udp://239.100.106.107:port#interface interface is the name of the network interface to use in the multicast.

Discovery Port

By default, the port on which Management Daemon listens for JMX discovery requests is set to 9999.



The JMX discovery URL is set in the discoveryJMXAddress element. For example:

<string name="discoveryJMXAddress">service:jmx:jmxmp://Hostname:9999</string><string name="discoveryPolicy">ALWAYS</string>

where Hostname is the hostname of the machine running the Management Daemon process. The discovery policy can be ALWAYS, to enable discovery, or NEVER, to prohibit discovery.

Management Port

By default, the port on which Management Daemon listens for node management requests is set to 9998.

The JMX management port is set in the managementAddress element. For example:

<string name="managementAddress">service:jmx:jmxmp://Hostname:9998</string>

Changing the Port Values

To change the default port values used by Management Daemon:

1. Open the ENV_HOME/managementdaemon/2.0/managementscript.txt file in a text editor.

2. Add the appropriate commands before the exit command:

— UDP Listening Port

clear discoverySocketAddressesadd discoverySocketAddress address

where address is in one of the formats described in UDP Listening Port on page 18.

— Discovery Port

set discoveryJMXAddress service:jmx:jmxmp://Hostname:Port

— Management Port

set managementJMXAddress service:jmx:jmxmp://Hostname:Port

3. Run ENV_HOME/managementdaemon/2.0/bin/managementscript.



Changing Management Daemon Status Reporting and Polling IntervalsYou can change Management Daemon status reporting and polling intervals to suit your requirements.

For example, in nonproduction environments, you may not need very up-to-date status on nodes and daemons, so you would increase the value of the nodePollingInterval and daemonStatusInterval properties. In a mission-critical production environment, on the other hand, you may want to get status updates every 15 seconds instead of the default of 30 seconds.

On the other hand, if you know that software inventory on machines do not change very often, you can set a large interval for inventory polling to save some processing power on the machines.

Status Reporting Interval

Management Daemon processes report the status of the nodes installed on their machines to all the ActiveMatrix Administrator servers. They also report status of the Management Daemon process itself.

Inventory Polling Interval

A Management Daemon process periodically checks (polls) the local file system for the following changes:

• Addition of new containers and removal of existing containers

• Installation of new versions of installed products or uninstallation of existing products

When a Management Daemon process encounters such a change, it updates the databases of all ActiveMatrix Administrator servers bound to the machine on which it is running. The server databases therefore hold accurate information about containers and installed software.

To configure this polling interval, edit the inventoryPollingInterval property.

In a production system where software is not installed or uninstalled very often, you can set this interval to a very large number.

Node Polling Interval

A Management Daemon process uses JMX to ping all nodes on the machine and report if they are alive. They report directly to the ActiveMatrix Administrator servers.

To configure the interval between each ping, edit the nodePollingInterval property.



Set the interval according to how critical it is to know the current node state. It is strongly recommended that you set the interval to 20 seconds or more. Intervals of less than 20 seconds can result in performance degradation.

Editing the Reporting and Polling Intervals

You edit the intervals for each Management Daemon process in a configuration file in the Management Daemon installation directory. The file is created after you bind the machine on which the Management Daemon process running to an ActiveMatrix Administrator cluster and associate the machine with an environment.

To Change the Reporting and Polling Intervals

1. On the machine running the Management Daemon process, open the following file for editing:

ENV_HOME/managementdaemon/2.0/daemonlets/com.tibco.matrix.daemonlet/amxdaemonlet.xmi

2. Locate the entries whose interval you want to change and change them as desired.

3. Save the file.

Example

<?xml version="1.0" encoding="ASCII"?><xmi:XMI xmi:version="2.0" xmlns:xmi="http://www.omg.org/XMI" xmlns:mgmtdaemonmodel="http://xsd.tns.tibco.com/matrix/models/mgmtdaemonmodel"> <mgmtdaemonmodel:ManagementDaemonStore adminClusterDetails="/1" inventoryPollingInterval="30000" nodePollingInterval="30" daemonStatusInterval="30" pluginPollingInterval="30000"/> <mgmtdaemonmodel:AdminClusterDetails dbDriver="org.hsqldb.jdbcDriver" dbURL="jdbc:hsqldb:hsql://hostname:1234/amx" clusterName="amx"> <dbCredentials username="sa" password=""/> </mgmtdaemonmodel:AdminClusterDetails></xmi:XMI>

The time unit for inventoryPollingInterval is milliseconds. Other time units are seconds.



TIBCO Enterprise Message Service™ Server

ActiveMatrix software uses TIBCO Enterprise Message Service server for the Messaging Bus communications backbone. You can create and start TIBCO ActiveMatrix Administrator before running the Enterprise Message Service server. The Enterprise Message Service server must be running before invoking the following operations:

• Starting a node. See Starting and Stopping Nodes on page 195.

• Using Log and Monitoring services. Viewing statistics about or logs from a node is dependent on these two services. See Chapter 10, Managing Logging, on page 295 and Chapter 9, Monitoring Infrastructure and Services, on page 241.

• Testing the connection when creating a JMS shared resource definition. See Creating a Shared Resource Definition on page 116.

You can choose to use the same Enterprise Message Service server for all of these operations.

This section describes how to start the Enterprise Message Service server. For information on installing and configuring the server, see TIBCO Enterprise Message Service product documentation.

Starting the TIBCO Enterprise Message Service ServerTIBCO Enterprise Message Service is the messaging backbone for the ActiveMatrix runtime.

To start the messaging server or servers do one of the following:

• Windows From the Start menu, select All Programs > TIBCO > TIBCO EMS version > Start EMS Server

The Enterprise Message Service server is installed as an Windows service, so you can also start the server as follows:

a. Select All Programs > Administrative Tools > Services.

b. Right-click TIBCO EMS Server and select Start.

• Windows or UNIX From the command line, run TIBCO_HOME/ems/bin/tibemsd.


TIBCO Administrator™ and TIBCO Hawk® | 23

TIBCO Administrator™ and TIBCO Hawk®

TIBCO Administrator and TIBCO Hawk are required only if you authenticate ActiveMatrix users using a TIBCO Administrator authentication realm.

This section describes how to start the TIBCO Administrator server and TIBCO Hawk agent. For information on how to configure TIBCO Administrator to be an ActiveMatrix Administrator authentication realm see Creating a TIBCO Administrator Authentication Realm on page 33. For complete information on configuring TIBCO Administrator, see TIBCO Administrator product documentation.

Starting TIBCO Administrator and TIBCO HawkWhen you use a TIBCO Administrator authentication realm, the TIBCO Administrator server and TIBCO Hawk agent for your domain must be running.

To start the services on Windows, you can use the Services dialog. Find the entry for TIBCO Administrator version (domain) and click Start. Repeat for the TIBCO Hawk Agent (domain) entry.

You can also start the TIBCO Administrator and TIBCO Hawk services using the command-line versions of these services. Useful information is written to a command window when you start the services in this way. To stop a service, close its window.

To start TIBCO Administrator server at the command line, run the following:

TIBCO_HOME/administrator/domain/domainName/bin/tibcoadmin_domainName.exe

To start TIBCO Hawk agent at the command line, run the following:

TIBCO_HOME/tra/domain/domainName/bin/hawkagent_domainName.exe




| 25

Chapter 3 ActiveMatrix Administrator Server

This chapter explains how to create the first ActiveMatrix Administrator server in a cluster, configure the authentication realm, database, and default runtime node, and start and stop the ActiveMatrix Administrator server.

Topics

• Creating the First ActiveMatrix Administrator Server, page 26

• Authentication Realm Configuration, page 31

• Database Configuration, page 48

• Default Runtime Node Configuration, page 60

• Starting and Stopping the ActiveMatrix Administrator Server, page 61


26 | Chapter 3 ActiveMatrix Administrator Server

Creating the First ActiveMatrix Administrator Server

This section describes how to create the first ActiveMatrix Administrator server in a cluster using the ActiveMatrix Administrator server creation utility. Once you have created the first Administrator server you can use the ActiveMatrix Administrator graphical interface (see Creating an ActiveMatrix Administrator Server on page 165) to create additional servers.

Before Running the ActiveMatrix Administrator Server Creation UtilityBefore running the ActiveMatrix Administrator server creation utility you must do the following:

• Decide whether you want to secure the communication channels between ActiveMatrix components. For detailed instructions on how to configure the components, see Appendix A, Securing TIBCO ActiveMatrix Communication Channels, on page 339.

• Start the ActiveMatrix Administrator cluster database server. The same database server can be used for the authentication realm, if you are using a database for authentication. You can also configure a different database server for use with the cluster. If you plan to use the packaged HSQLDB database, it can be started as part of the installation process.

• Choose an authentication realm: Local XML File, TIBCO Administrator, Database, or LDAP. All ActiveMatrix Administrator servers in the same cluster must use the same authentication realm. For information on authentication realms, see Authentication Realm Configuration on page 31.

If you are using a TIBCO Administrator authentication realm for your cluster perform the tasks described in Creating a TIBCO Administrator Authentication Realm on page 33 before starting the ActiveMatrix Administrator server creation utility.

Pre-creating Database Tables by Running DDL Scripts

You can pre-create the ActiveMatrix schema (database tables) before running the ActiveMatrix Administrator server creation utility. Doing so allows you to run ActiveMatrix with a database user that has minimum privileges. See Pre-creating ActiveMatrix Schema on page 53 for details.

The ActiveMatrix Administrator server creation utility cannot connect to the database if a firewall is running on your machine. The firewall must be disabled before running the utility.


Creating the First ActiveMatrix Administrator Server | 27

If you are using Microsoft SQL Server and have pre-created the database tables by running DDL scripts generated with dbscriptgenerator, and then run ActiveMatrix Administrator server creation utility using a database account with no permissions to create database tables, you must:

• Create the administration server cluster table with an upper case name AMXADM_CLUSTER_NAME_IN_CAPS.

• Create the database schema for all tables the same, for example db_owner and the same schema must be set as the default schema for the database user provided in the JDBC parameters in the ActiveMatrix Administrator server creation utility. For example:

Running the ActiveMatrix Administrator Server Creation UtilityDuring installation you are prompted to run the ActiveMatrix Administrator server creation utility to create the first server. If you do not run the utility during installation, you can run the utility in interactive mode, console mode, or silent mode.

In all modes you provide configuration details following the guidelines in the sections:

— Database Configuration on page 48

— ActiveMatrix Administrator Configuration on page 29

— Authentication Realm Configuration on page 31

— Database Configuration on page 48

— Default Runtime Node Configuration on page 60.

If you are using Sybase as the TIBCO ActiveMatrix Administrator database you can run the utility only in silent mode.



GUI Mode

In GUI mode, the utility prompts for input in a series of dialogs. To run the utility in GUI mode:

Windows From the Start menu, select All Programs > TIBCO > TIBCO ActiveMatrix > Administrator Server Creation Wizard

Windows or UNIX Change directory to AMX_ADMIN_HOME/2.3/bin/. From the command line, run createadminserver.

Console Mode

In console mode, the utility prompts for input in the command window. To run the utility in console mode:

Windows or UNIX change directory to AMX_ADMIN_HOME/2.3/bin/. From the command line, run:createadminserver -console

Silent Mode

In silent mode, the utility does not prompt for any inputs. Instead, the inputs are read from a properties file provided as a command-line parameter. The properties file must specify all the properties you would provide to the wizard. The directory contains the sample properties file createadminserver.properties. You must replace the variable @HOSTNAME@ in this file with your hostname and edit values for other parameters as needed. Values for password fields can either be entered as clear text or as obfuscated passwords (see Creating an Obfuscated Password) using . To run the utility in silent mode:

Windows or UNIX Change directory to AMX_ADMIN_HOME/2.3/bin/. From the command line, run createadminserver -silent propertiesFilePath.

Creating an Obfuscated Password

The password obfuscator obfuscates passwords two encryption algorithms: TIBCO or Platform Server. To create an obfuscated password:

1. Change directory to AMX_ADMIN_HOME/2.3/bin/.

2. Run passwordobfuscator.

TIBCO Encryption

Syntax: passwordobfuscator password

Example: passwordobfuscator tibco


Creating the First ActiveMatrix Administrator Server | 29

Output:

Encrypted password, contained in brackets: [#!LjNSm/lIwW7uwiLvcZQwuA==]

Platform Server Encryption

Syntax: passwordobfuscator -p username password

Example: passwordobfuscator -p root tibco

ActiveMatrix Administrator ConfigurationTable 3 on page 29 describes the fields that define the ActiveMatrix Administrator cluster and server.

Table 3 ActiveMatrix Administrator Reference

Field Description

Server Name A name to identify the server. A name must be a valid directory name in Windows or UNIX operating systems. The name must be unique among servers on the machine. The name must be less than 23 characters long and can contain only alphanumeric and underscore (_) characters.

Default: admin

Cluster Name A name to identify the cluster. A name must be a valid directory name in Windows or UNIX operating systems. A cluster name is required even if you do not plan to add more servers to the cluster. The name must be less than 23 characters long and can contain only alphanumeric and underscore (_) characters.

Default: amx

HTTP Port Port on which the web container that hosts the ActiveMatrix Administrator user interface listens.

Default: 8120

Management Port Port on which the ActiveMatrix Administrator server for node management and control functions using JMX protocol.

Default: 8110

Authentication Realm The method of storing authentication information about users and groups: Local XML File, TIBCO Administrator, Database, LDAP.

See Authentication Realm Configuration on page 31.



Deleting the ActiveMatrix Administrator Windows ServiceOn Windows, you delete the ActiveMatrix Administrator Window service by invoking the deleteadminserver utility against the AMX_ADMIN_HOME/data/cluster_server.xml file. The database server used by the ActiveMatrix Administrator server must be running. For example, on Windows for a cluster named amx and ActiveMatrix Administrator server named admin:

1. Change directory to AMX_ADMIN_HOME/2.3/bin/.

2. Run deleteadminserver ../../data/cluster_server.xml.

If the ActiveMatrix Administrator server creation utility was run by a DML (Data Manipulation Language) user, the deleteadminserver utility does not drop the tables from the database because the DML user does not have sufficient privileges. A DDL (Data Definition Language) user must manually remove the tables from the database.


Authentication Realm Configuration | 31

Authentication Realm Configuration

When you configure the first ActiveMatrix Administrator server in a cluster you specify an authentication realm. All servers in the same ActiveMatrix Administrator cluster use the same authentication realm. For a description of how to change the authentication realm after you have created the first server in a cluster, see Updating the Authentication Realm on page 45.

For reference information for each type of realm supported by ActiveMatrix Administrator see the sections:


• TIBCO Administrator Realm on page 32

• Database Realm on page 35


Local XML File RealmWhen you use the local XML file realm, one username—root—and a password of your choice is stored in a local file. You must use the same password for all servers in a cluster. Local XML File Realm is an appropriate choice for demonstration installations and other non-production uses.

There is one screen to configure the Local XML File Realm:


Local XML File Realm

Adding a User to a Local XML File Realm

To add a new user (user1) to a local XML file realm:

1. Open the file AMX_ADMIN_HOME/data/clustername/servername/config/system-security.xml in a text editor.

Table 4 Local XML File Realm Reference

Field Description

Username The username root.

Password A password of your choice.



2. Create an obfuscated password for the new user using the -p option (see Creating an Obfuscated Password on page 28).

3. Add the new user and password under the <users> tag within a <user> tag. You can optionally add the user to a group using the <group-mapping> tag.

<users><user>

<name>root</name><password>toiP3D2RYKw=</password>

</user><user>

<name>user1</name><password>297SLWvlCAY=</password>

</user><user>

<name>guest</name><password>30ojcikAopk=</password>

</user></users><group-mapping>

<group-name>administrator</group-name><user-name>root</user-name><user-name>user1</user-name>

</group-mapping>

4. Save and exit the system-security.xml file.

5. Change to the directory AMX_ADMIN_HOME/2.3/bin/.

6. Run cluster_server -uploadconfig.

TIBCO Administrator RealmWhen you use the TIBCO Administrator realm, users are authenticated against the HTTPS-enabled TIBCO Administrator domain shared by every server in a cluster. As a result of the setup, all users who can authenticate to this TIBCO Administrator domain can also authenticate to the ActiveMatrix Administrator servers you create. Users and groups in this realm can only be edited with TIBCO Administrator user management tools.

When you create the ActiveMatrix Administrator server, you provide the authority URL for the TIBCO Administrator server and the credentials for the domain superuser. You also specify a file-based location of the certificate, which can be either a self-signed or third-party certificate. One TIBCO administration domain and one certificate can be shared by all ActiveMatrix Administrator clusters in your enterprise.

The final step is to add the ActiveMatrix Administrator user credentials to the TIBCO Administrator domain. Full details about how to add users to the TIBCO Administrator domain are provided in that product’s documentation.



Creating a TIBCO Administrator Authentication Realm

This section explains how to create a TIBCO Administrator authentication realm for use by ActiveMatrix Administrator servers.

Task A Create an HTTPS-enabled TIBCO Administrator Domain

1. Install a supported version of TIBCO Administrator software on a machine or use an existing installation. See TIBCO ActiveMatrix Service Grid Installation for supported versions of required hardware and software.

2. On the machine where you installed TIBCO Administrator, use Domain Utility to create a domain. (At the Select a Task dialog, select Domain Configuration > Create a new administration domain.) This domain is for use by the ActiveMatrix Administrator cluster (or clusters).

The username and password you enter for the domain are the superuser credentials.

3. Using Domain Utility, enable HTTPS. (At the Select a Task dialog, select Domain Configuration > Enable HTTPS.)

Select the domain and provide the superuser credentials.

a. In the HTTPS Configuration dialog, select the appropriate option to suit your needs: Self Signed Certificate, or a Third Party Certificate option.

b. In the Server Certificate dialog, provide the server certificate details.

c. In the Server Settings dialog, enter the port numbers or accept the defaults. Also enter the username and password for the keystore.

4. Click Next. Domain Utility performs various tasks and creates a keystore in the location:

TIBCO_HOME/tibco/administrator/domain/DomainName/SSL/keystore

Task B Extract the Certificate with Keytool

1. Open a command window and navigate to the following directory:

TIBCO_HOME/tibco/administrator/domain/DomainName/SSL/

2. At the command line, execute this command:

keytool -keystore KeystoreFile -list

When prompted for the password, enter changeit (the default) or the current password value.

A list of all certificates and their alias names displays (followed by the date). Note the alias name of the certificate for use in the next step.



3. At the command line, execute this command:

keytool -keystore KeystoreFile -export -alias AliasName -filefilename.cer

The certificate is exported to the file filename.cer in the SSL directory.

4. Put the certificate in a file system location accessible to the machine on which you run the ActiveMatrix Administrator server.

Configuring the TIBCO Administrator Authentication Realm

There is one screen to configure the TIBCO Administrator Realm:

• TIBCO Administrator Realm Reference on page 34.

Table 5 TIBCO Administrator Realm Reference

Field Description

Authority URL The URL used to log in to TIBCO Administrator. The format of the URL is Hostname:HTTPSPort, where Hostname is the URL you use to login to the TIBCO Administrator GUI, and HTTPSPort is the HTTPS port you defined in the Domain Utility Server Settings dialog.

Default: localhost:8080

Note that the default port in Domain Utility is 8443.

Username The superuser username defined for the TIBCO Administrator domain.

Password The superuser password defined for the TIBCO Administrator domain.

Client Certificate The client certificate file. Click Browse to locate and select the file you specified in step 4 in the preceding section.



Database Realm When you use the database realm, users and groups are declared in a database shared by every server in a cluster. Users and groups in this realm can be edited within ActiveMatrix Administrator. You also have the option to use the same database for authentication data and ActiveMatrix administration data (see Database Configuration on page 48).

TIBCO ActiveMatrix supports secure access to Oracle databases. For information on how to enable secure connections to Oracle database servers, see Securing JDBC Connections on page 349.

There are two screens to configure the Database Realm:

• Database Realm on page 36

• Database Authentication Superuser on page 37



Database Realm

Table 6 Database Realm Reference

Field Description

Database Driver The name of the JDBC driver class. You can select from a list of supported drivers. When you select a driver, the Database URL field is populated with a template for the URL of the driver.

For HSQL: org.hsqldb.jdbcDriver

For Oracle: tibcosoftwareinc.jdbc.oracleOracleDriver

For Microsoft SQL Server: tibcosoftwareinc.jdbc.sqlserver.SQLServerDriver

Default: org.hsqldb.jdbcDriver.

Database URL The URL to use to connect to the database. A template of the URL is supplied for the selected JDBC driver. You must supply the portions of the URL shown between angle brackets and remove the angle brackets.

For HSQLDB the template is:

jdbc:hsqldb:hsql://<hostname>:<portnumber>/amx

You must supply the hostname and port number.

For Oracle, the template is:

jdbc:tibcosoftwareinc:oracle://<host>:<port>;SID=<SID>

You must supply the hostname, port number, and database instance name (SID).

For Microsoft SQL Server, the template is:jdbc:tibcosoftwareinc:sqlserver://<host>:<port>;databaseName=<databaseName>

You must supply the hostname, port number, and database instance name (databaseName).

Note: If you use localhost as the hostname, you can only connect to Management Daemon processes running on the local machine.

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

Username A name for the database user.

Default: sa.



Database Authentication Superuser

The Database Authentication Realm User screen allows you to specify an ActiveMatrix Administrator user. A user added through this screen is automatically a superuser. See Superusers on page 140. There are two cases that can occur:

• The database has no users. You enter a username and password. A user is added to the user database.

• The database is an existing user database populated with users.You can skip the Database Authentication Realm User screen, leaving all the fields empty. or you can also choose to enter a new username and password, in which case the user is added. If an existing username is entered, it is ignored.

Password A password for the database user.

Note: On 64 bit Linux the password text box for the database authentication realm screen in the Administrator Server Creation Wizard is not rendered. The lack of visibility of the text box does not affect the function. Click the text box and type the password.

Max Connections Maximum number of simultaneous connections to the database that can be open.

Default: 5

Login Timeout Amount of time in seconds allowed for login before giving up the attempt.

Default: 30 seconds.

Table 6 Database Realm Reference (Cont’d)

Field Description



If you are using Microsoft SQL Server, the database authentication realm user specified must have the db_owner permission set. For example:

If you want to update the database realm superuser credentials after running the ActiveMatrix Administrator server creation utility, you use the ActiveMatrix Administrator command-line interface (see ActiveMatrix Administrator Command-Line Interface on page 79). To update bootstrap credentials:

1. Create build.xml and datafile.xml files with the appropriate action, and username and obfuscated password (see Creating an Obfuscated Password on page 28).

2. Run the command-line.

3. Restart all ActiveMatrix nodes and ActiveMatrix Administrator servers.

Table 7 Database Realm Authentication Superuser Reference

Field Description

Username A name for an ActiveMatrix superuser.

Password A password for an ActiveMatrix superuser.

Confirm Password The password provided in the Password field.



For example:

build.xml

<target name="edit_bootstrapUser"><AMXAdminTask...

action="edit"dataFile="datafile.xml"objectSelector="AdminCluster/BootStrapUser"overwrite="true"merge="true"createIfNotExists="true"fore="true"failOnError="true"/>

</target>

datafile.xml

<BootStrapUser username="username" password="password"/>

LDAP RealmWhen you use the LDAP authentication realm, users and groups are managed by an LDAP server shared by every server in a cluster. Users and groups in this realm can only be edited with LDAP server management tools.

The samples folder under AMX_ADMIN_HOME/2.3/bin has a sample build file and data file for updating the bootstrap credential. If that file is used instead of creating a new build file and data file, then the login.properties file in the folder must be updated with the curent username and password of the server.If a new build file and data file is created, then the username and password of the ActiveMatrix Administrator server must be specified in the build file target:

<AMXAdminTask adminURL="http://localhost:8120/amxadministrator"username="admin"password="#!VHteZnPoIZ8/gOZ9VxixcWJlUuwkiuXt"action="edit"dataFile="../samples/admin_server_data.xml"objectSelector="AdminCluster/BootStrapUser"overwrite="true"merge="true"createIfNotExists="true"force="true"failOnError="true"/></target>



TIBCO ActiveMatrix supports secure access to LDAP servers. For information on how to enable secure connections to LDAP servers, see Enabling Secure Connections to LDAP Servers on page 355.

To use non-default LDAP attributes as usernames, see Configuring LDAP Attributes as Usernames on page 43.

The LDAP server must be running before configuring it for the ActiveMatrix Administrator server.

There are four screens to configure the LDAP realm:


• Search on page 41

• LDAP Mapping on page 43

• Superuser Registration on page 43



LDAP Realm

Search

In the search screen you provide user and group configuration details.

If the Base DN to search users and Base DN to search groups is the same (that is, users and groups are under the same tree node in the LDAP hierarchy), enter more specific LDAP queries that differentiate users and groups for the Search Filter for Users and Search Filter for Groups parameters.

For example, if in Search Filter for Users, you enter: (&(objectClass=person)(uid=%U))

Table 8 LDAP Realm Reference

Field Description

Context Factory The factory object that provides the starting point for resolution of names within the LDAP server.

Default: com.sun.jndi.ldap.LdapCtxFactory

LDAP Server URL The URL used to log in to the LDAP server.

Default: ldap_server:port

Username (Bind DN) The superuser's distinguished name or superuser's name to be used to connect to the server.

Default: cn=Directory Manager

Password LDAP server password.

Use SSL When checked, the ActiveMatrix Administrator server can communicate with an LDAP Server over SSL. This enables secure communication between the LDAP server and ActiveMatrix Administrator. For addition configuration requirements, see Enabling Secure Connections to LDAP Servers on page 355.

Default: Unchecked.

Authentication Type Authentication type to be used for connection to LDAP Server. One of Simple, Strong, or None.

A strong authentication mechanism requires you to possess a Public Key Certificate (PKC).

Default: Simple



and in Search Filter for Groups, you enter: (&(objectClass=groupOfUniqueNames)(cn=%G))

The LDAP search query filter for users never matches groups, and the LDAP search query filter for groups never matches users. This is a required condition.

Table 9 Search Reference

Field Description

Base DN to Search Users Base distinguished name from which the search starts.

Default: ou=<--->,dc=<--->,dc=com

Search Filter for Users Filter to be used for searching a user. An example for this filter is (CN=%U). '%U' is replaced by the username being searched for. You can define any complex filter like (&(cn=%U)(objectClass=account)).

Default: (uid=%U)

Search Scope for Users Scope for searching for the user. Possible values are OneLevel and Subtree. Use OneLevel to search for the user immediately under the Base distinguished name. Use SubTree to search for the user in the subtree as well.

Base DN to Search Groups

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

ou=<--->,dc=<--->,dc=com

Default: The value in Base DN to Search Users.

Search Filter for Groups Filter to be used for searching a group. An example for this filter is (OU=%G). Here '%G' is replaced by the group name being searched at the runtime.

Default: (OU=%G)

Search Scope for Groups Scope for searching the group. Specifies whether to search only under the Group base distinguished name or traverse into the subtree. Possible values for this are SubTree and OneLevel.



LDAP Mapping

Select one field and provide the mapping details.

Superuser Registration

The LDAP user you provide becomes a superuser in ActiveMatrix Administrator.

Configuring LDAP Attributes as Usernames

When using an LDAP authentication realm by default the value of the CN attribute is used as the username. You can configure a different LDAP attribute (such as sAMAccountName in the case of Microsoft Active Directory) to display as a username in the Users tab of the Enterprise Assets perspective.

Existing ActiveMatrix Administrator Server

To apply this configuration change to an existing ActiveMatrix Administrator server:

1. Stop the ActiveMatrix Administrator server.

2. Edit the file: AMX_ADMIN_HOME/data/cluster/server/config/security-config.xml.

Table 10 LDAP Mapping Details Reference

Field Description

Group has User and Subgroup as its Attributes

The values for User and Subgroup attribute keys. The attribute keys refer to the keys with which Users and Subgroups are associated with the Group.

User/Subgroup has Group as Attribute

The value for the Group attribute key with which the parent group is associated with this user/subgroup.

User DN has Group The Key name for the group in the user distinguished name.

Table 11 Superuser Registration Reference

Field Description

Username Name of an existing user in the LDAP server to register as an ActiveMatrix superuser. See Superusers on page 140.

Password Password for the user.



3. In the realm element, add new entry subelements:

<security-service>...<realm><realm-name>system</realm-name><user-manager><class-name>com.tibco.matrix.administration.server.util.TibcoLD

APUserManager</class-name><init-options><entry><name>...</name><value>...</value></entry>...</init-options></user-manager></realm>...</security-service>

4. To specify a different attribute for username, insert a new entry element and replace sAMAccountName in the example with your LDAP attribute name. This entry is optional. If absent, then the leftmost attribute occurring in the DN (typically CN) is used for the username.

<entry><name>UserUniqueAttribute</name><value>sAMAccountName</value></entry>

Ensure that the UserFilter uses the same attribute name as specified in UserUniqueAttribute and if necessary change it in the existing XML entry. For example, change UserFilter from (CN=%U) to (sAMAccountName=%U). The UserFilter may also specify filter additional criteria (such as objectClass=person).

5. To specify a different attribute for group name, insert a new entry element. and replace sAMAccountName in the example with your LDAP attribute name. This entry is optional. If absent, then the leftmost attribute occurring in the DN (typically CN) is used for the group name.

<entry><name>GroupUniqueAttribute</name><value>sAMAccountName</value></entry>

Ensure that the GroupFilter uses the same attribute name as specified in GroupUniqueAttribute and if necessary change it in the existing XML entry. For example, change GroupFilter from (CN=%G) to (sAMAccountName=%G). The GroupFilter may also specify additional filter criteria (such as objectClass=groupofuniquenames).

6. Locate the following entry and change the value from 1 (default value) to 10:



<entry><name>RetrievalPageSize</name><value>10</value></entry>

7. Ensure that the ActiveMatrix database is running and start the ActiveMatrix Administrator server with the -uploadconfig option:

AMX_ADMIN_HOME/2.3/bin/cluster_server –uploadconfig

The server starts, stores the LDAP configuration changes to the database, and upgrades the ActiveMatrix Administrator server.

8. Stop and restart the ActiveMatrix Administrator server without any parameters.

New ActiveMatrix Administrator Cluster

To enable a non-default attribute as a username in a new ActiveMatrix Administrator cluster, create the cluster using the createadminserver utility in silent mode (see Silent Mode on page 28). In the createadminserver.properties file, enable (by deleting the '#' comment instruction from the beginning of the lines), the following LDAP realm settings:

cluster.realm.ldap.user_unique_attribute=sAMAccountName

cluster.realm.ldap.group_unique_attribute=sAMAccountName

Enable cluster.realm.ldap.user_unique_attribute to specify a different attribute for username, and replace sAMAccountName with your attribute name (the default is valid for Microsoft Active Directory). Enable cluster.realm.ldap.group_unique_attribute to specify a different attribute for group name.

Updating the Authentication RealmOnce you have created a cluster you may decide to change from one realm to another or to change realm properties.

To update the authentication realm after running the ActiveMatrix Administrator server creation utility use the ActiveMatrix Administrator command-line interface (see ActiveMatrix Administrator Command-Line Interface on page 79). To update the authentication realm:

If you decide to change to another type of realm, the current bootstrap user of the ActiveMatrix Administrator server must be present in the new realm with same password.



1. Create build.xml and datafile.xml files with the appropriate action and realm configuration.

2. Run the command-line with the specified files.

3. Restart all ActiveMatrix Administrator servers.

Example

The following sections contain example build and data files for updating the authentication realm.

build.xml<target name="edit_realm_details"><AMXAdminConfigTask

username="${username}"password="${password}"action="edit"dataFile="datafile.xml"objectSelector="AdminCluster/AuthenticationRealm"adminServerName="servername"adminClusterName="clustername"failOnError="true"/>

</target>

datafile.xml

<AdminCluster><AuthenticationRealm xsi:type="amxdata:AuthenticationRealm">

<RealmDetails realmType="DatabaseAuthentication"><DatabaseAuthenticationProperties

driver="org.hsqldb.jdbcDriver" url="jdbc:hsqldb:hsql://host:1234/amx" userName="user" password="password" maxConnections="10" >

</DatabaseAuthenticationProperties></RealmDetails >

</AuthenticationRealm></AdminCluster>

Manual Recovery

To recover from an error:

1. Edit the properties in the AMX_ADMIN_HOME/data/clustername/servername/config/security-config.xml file for one ActiveMatrix Administrator server in the cluster. In the password entries provide an obfuscated password created using TIBCO encryption (see Creating an Obfuscated Password on page 28).

<realm><realm-name>system</realm-name>



<user-manager>...

<init-options><entry>

<name>url</name><value>jdbc:hsqldb:hsql://hostname:1234/amx</value>

</entry><entry>

<name>password</name><value>#!IvK2PkOuX9laHarIhbxoyA==</value>

</entry><entry>

<name>driver</name><value>org.hsqldb.jdbcDriver</value>

</entry><entry>

<name>username</name><value>sa</value>

</entry>...

</init-options></user-manager>

</realm><configuration>

<login-module-configuration><realm-name>system</realm-name><config-entry>...<options>

<entry><name>hibernate.connection.driver_class</name><value>org.hsqldb.jdbcDriver</value>

</entry><entry><name>hibernate.connection.username</name><value>sa</value>

</entry><entry><name>hibernate.connection.url</name><value>jdbc:hsqldb:hsql://hostname:1234/amx</value>

</entry><entry><name>hibernate.connection.password</name><value>#!IvK2PkOuX9laHarIhbxoyA==</value>

</entry>...

</options></config-entry>

</login-module-configuration><configuration>

2. Change to the directory AMX_ADMIN_HOME/2.3/bin/.

3. Run cluster_server -uploadconfig

4. Restart the other ActiveMatrix Administrator servers in the cluster.



Database Configuration

The ActiveMatrix database server maintains ActiveMatrix administration data. All servers in the same ActiveMatrix Administrator cluster use the same database.

When you run the ActiveMatrix Administrator server creation utility you specify the database configuration. For a description of how to update the database configuration after you have created the first server in a cluster, see Updating the Database Configuration on page 50.

TIBCO ActiveMatrix supports secure access to Oracle databases. For information on how to enable secure connections to Oracle database servers, see Securing JDBC Connections on page 349.

The ActiveMatrix Administrator server creation utility creates the ActiveMatrix administration data tables. For a description of how to pre-create the tables, see Pre-creating ActiveMatrix Schema on page 53.

Database Configuration ReferenceThe fields in Table 12 are used to configure the ActiveMatrix Administrator database. See ActiveMatrix Database Server on page 14 for details.

Table 12 Database Configuration Reference

Field Description

Use Configuration Details from Database Authentication Realm

Indicates whether to use the same database for ActiveMatrix administration data as used for authentication data (see Database Realm on page 35).

If checked, each field value is copied from the Database Authentication Realm screen into this screen and all the text fields are noneditable.

If unchecked, the text fields are editable and should be set according to the fields described in this table.

Default: Checked.


Database Configuration | 49

Database Driver The name of the JDBC driver class. You can select from a list of supported drivers. When you select a driver, the Database URL field is populated with a template for the URL of the driver.

For HSQLDB: org.hsqldb.jdbcDriver

For Oracle: tibcosoftwareinc.jdbc.oracleOracleDriver

For Microsoft SQL Server: tibcosoftwareinc.jdbc.sqlserver.SQLServerDriver

Database URL The URL to use to connect to the database. A template of the URL is supplied for the selected JDBC driver. You must supply the portions of the URL shown between angle brackets and remove the angle brackets.

For HSQLDB the template is:

jdbc:hsqldb:hsql://<hostname>:<port>/<Datastore>

You must supply the hostname, port number, and the datastore name. Default: jdbc:hsqldb:hsql://<hostname>:1234/amx

For Oracle, the template is:

jdbc:tibcosoftwareinc:oracle://<hostname>:<port#>;SID=<SID>

You must supply the hostname, port number, and database instance name (SID). Default: jdbc:tibcosoftwareinc:oracle://<host>:1521;SID=XE

For Microsoft SQL server, the template is:jdbc:tibcosoftwareinc:sqlserver://<hostname>:<port#>;databaseName=<databaseName>

You must supply the hostname, port number, and database instance name (databaseName). Default: jdbc:tibcosoftwareinc:sqlserver://<hostname>:1433;databaseName=<database>

Note: If you use localhost as the hostname, you can only connect to Management Daemon processes running on the local machine.

Username The database user name.

Default: sa.


Max Connections Maximum number of simultaneous connections to the database that can be open.

Table 12 Database Configuration Reference (Cont’d)

Field Description



Updating the Database ConfigurationTo update the database configuration after running the ActiveMatrix Administrator server creation utility use the ActiveMatrix Administrator command-line interface (see ActiveMatrix Administrator Command-Line Interface on page 79).

The Management Daemon processes on all machines must be bound and available. A partial success is also supported when some Management Daemon processes are unavailable.

To update database configuration properties:

1. Create build.xml and datafile.xml files with the appropriate action and new database configuration.

2. Run the command-line.

3. Restart all ActiveMatrix nodes and ActiveMatrix Administrator servers.

You can update the following parameters:

• URL

• Driver class

• Username and password

• Maximum number of connections

Example

The following sections contain example build and data files for updating the database configuration.

build.xml

<target name="edit_db_details"><AMXAdminConfigTask

username="${username}"password="${password}"action="edit"

Login Timeout Amount of time in seconds allowed for login before giving up the attempt.

Default: 30 seconds.

Table 12 Database Configuration Reference (Cont’d)

Field Description



dataFile="datafile.xml"objectSelector="AdminCluster/DBParameters"adminServerName="servername"adminClusterName="clustername"failOnError="true"/>

</target>

datafile.xml

<AdminCluster><DBParameters url="jdbc:hsqldb:hsql://hostname:1234/amx"

driver="org.hsqldb.jdbcDriver" username="sa" password="" ></DBParameters>

</AdminCluster>

Use Cases

When updating the database configuration, you should keep in mind the implications of the following use cases:

• Parameters reference the old database

The application database remains the same, even when some parameters are updated. For example, when the password is changed, the application database is still the same. In some cases, even changing the username, driver, and JDBC URL still uses the same application database.

• Parameters reference a new database

Some parameters, for example, changing the hostname in the JDBC URL, may cause the JDBC connection to use a new database. Using a new database is supported only when you migrate all tables, views, rules and data from the old database to the new database. ActiveMatrix Administrator does not do this automatically, and does not work if you don’t perform the migration.

• Database shared with authentication realm

If your installation uses the same database for both the application and authentication realm, then you must first update the authentication realm database (see Updating the Authentication Realm on page 45), and then the application database. Restart the ActiveMatrix Administrator server only after both updates are completed.

<target name="edit_db_realm_details"><AMXAdminConfigTask

username="${username}"password="${password}"action="edit"dataFile="datafile.xml"objectSelector="AdminCluster/DBParameters |

AdminCluster/AuthenticationRealm"adminServerName="servername"adminClusterName="clustername"



failOnError="true"/></target>

Failure Scenarios

Failure may occur in the following scenarios:

• Incorrect parameters

If you run the command with incorrect parameters, the ActiveMatrix Administrator server will not start. You must rerun the command using correct parameters before starting the ActiveMatrix Administrator server.

• Failed command

A failure will occur for a given machine if the Management Daemon is down, unreachable, or not bound. This matters only if there were runtime nodes or administration servers on that machine.

The errors indicate where the propagation of new database parameters has failed. There are two recovery options:

• Restart the Management Daemon on that machine and execute the command-line again.

• Manually edit certain files for each node or admin server on the machines where the failures occurred. To manually recover from an error:

a. Stop all nodes from the ActiveMatrix Administrator UI. If you see database related errors while doing this, you must go to each machine and manually stop the nodes.

b. Edit the boldface items in the ActiveMatrix Administrator and node server-config.xml files:

<configuration-persistence use="db"><persistence type="file"/><persistence type="db"><property name="driver"

value="tibcosoftwareinc.jdbc.sqlserver.SQLServerDriver"/><property name="url"

value="jdbc:tibcosoftwareinc:sqlserver://host:1433;databaseName=amx"/>

<property name="user" value="amx"/><property name="password" value="TX1DOe1AvDc="/>...

</persistence></configuration-persistence>

In the password entry provide an obfuscated password created using the -p option (see Creating an Obfuscated Password on page 28).

— ActiveMatrix Administrator server:



AMX_ADMIN_HOME/data/clustername/servername/config/server-config.xml

— Each node on all remote machines:

AMX_HOME/data/environmentname/nodename/config/server-config.xml

c. Restart all ActiveMatrix Administrator servers. Upon restart they use the new database credentials.

d. In the ActiveMatrix Administrator UI > Configure Enterprise Assets > Machines tab, unbind all machines. Discover and rebind to the same machines Upon rebind, the Management Daemon processes use the new database credentials.

e. Start nodes from the ActiveMatrix Administrator UI. Upon restart, nodes use the new database credentials.

Pre-creating ActiveMatrix SchemaYou can pre-create the ActiveMatrix schema (database tables) before running the ActiveMatrix Administrator Server creation utility. Doing so allows you to run ActiveMatrix with a database user that has minimum privileges (no table create or drop, but insert, update, and delete table records).

Two types of database users are involved when setting up the ActiveMatrix schema: a data definition language (DDL) user and a data manipulation language (DML) user. A DDL user can create and drop tables and is used when pre-creating the ActiveMatrix schema before running the ActiveMatrix Administrator server creation utility. A DML user can insert, update, and delete table records and is used by ActiveMatrix when running the ActiveMatrix Administrator server creation utility.

To pre-create schema for the supported databases, see the sections:

• Microsoft SQL Server on page 54

• Oracle on page 55

• Sybase on page 58



Microsoft SQL Server

To pre-create ActiveMatrix schema in Microsoft SQL Server:

1. Configure users:

a. The DDL user and the DML user must have the same default schema.

b. The DDL user has the following roles: db_datareader, db_datawriter, and db_owner. See Figure 2 on page 54.

c. The DML user has the following roles: db_datareader and db_datawriter. See Figure 3 on page 55.

Figure 2 SQL Server DDL User



Figure 3 SQL Server DML User

2. Create the tables following the instructions in Creating the ActiveMatrix Schema Files on page 56, Creating the ActiveMatrix Schema on page 56, and Creating the ActiveMatrix Tables on page 56.

3. Run the ActiveMatrix Administrator server creation utility as described in Running the ActiveMatrix Administrator Server Creation Utility on page 57.

Oracle

In Oracle the DML user temporarily functions as DDL user. To pre-create ActiveMatrix schema:

1. Generate the DDL files and edit the cluster schema SQL file as described in Creating the ActiveMatrix Schema Files on page 56.

2. Give the files to the Oracle DBA and request the creation of a DML user and schema using the DDL and SQL files.

3. The DBA creates a DML user and then temporarily grants the user connect and resource permissions.

4. The DBA logs in as the DML user and runs the DDL and SQL files to create the schema as described in Creating the ActiveMatrix Schema on page 56.

5. Use the DML username and password to create a cluster following the procedure described in Creating the ActiveMatrix Tables on page 56.



6. The DBA revokes the resource permission to the DML user.

7. Run the ActiveMatrix Administrator server creation utility as described in Running the ActiveMatrix Administrator Server Creation Utility on page 57.

Each you create a new environment, the DBA must create a new schema for the environment.

Creating the ActiveMatrix Schema Files

To create the ActiveMatrix schema files:

1. Create the ActiveMatrix Administrator cluster and the environment tables. Scripts for creating these tables are in AMX_ADMIN_HOME/2.3/scripts/ddl/createclusterschema_db.sql.

where db is hsql, oracle, or sqlserver depending on the database you are using.

2. Edit the SQL file and replace <ADMIN_CLUSTER_NAME>, <ENV_NAME_IN_CAPS>, (and <USER_SCHEMA> for Oracle) by the values you want to use. <ADMIN_CLUSTER_NAME> is the ActiveMatrix administration cluster (in upper case). <ENV_NAME_IN_CAPS> is the ActiveMatrix environment (in upper case). <USER_SCHEMA> is the DML user that is utilized by ActiveMatrix (in upper case).

Note that you can duplicate the statements if you want to create several environments.

Creating the ActiveMatrix Schema

To create the ActiveMatrix schema:

• Log in as the DDL user to any SQL tool permitted by your database system (SqlPlus for Oracle, SQLServer Studio for SQLServer, and so on) and run the script you created in the preceding section.

Creating the ActiveMatrix Tables

To create the ActiveMatrix tables:

1. Edit AMX_ADMIN_HOME/2.3/bin/dbscriptgenerator/dbscriptgenerator.properties with the database properties and DDL username and password here.

2. Open an terminal window and change to the directory AMX_ADMIN_HOME/2.3/bin/.



3. Run dbscriptgenerator. The script creates the file AMX_ADMIN_HOME/2.3/scripts/ddl/dbschema.ddl containing drop and create SQL statements.

4. Copy the create, alter, and create sequence statements into a file named dbcreateschema.sql.

5. If you are going to use the database authentication realm, rerun dbscriptgenerator after making following changes in AMX_ADMIN_HOME/2.3/bin/dbscriptgenerator/dbscriptgenerator.properties:

a. Comment the line containing the com.tibco.matrix.persistence.dbscriptgen.modelsfolder property.

b. Add the line

com.tibco.matrix.persistence.dbscriptgen.models=AMX_ADMIN_HOME/2.3/scripts/models/auth/usermgmt.model

replacing AMX_ADMIN_HOME with the location of the ActiveMatrix Administrator directory.

c. Set com.tibco.matrix.persistence.dbscriptgen.ddl to usermanagement_dbschema.ddl.

d. Set teneo.mapping.inheritance to JOINED.

The script creates the file AMX_ADMIN_HOME/2.3/scripts/ddl/usermanagement_dbschema.ddl containing drop and create SQL statements.

6. Copy the create, alter, and create sequence statements into a file named usermanagement_dbcreateschema.sql.

7. Login with the DDL user to any SQL tool permitted by your database system (it can be SqlPlus for Oracle, SQLServer Studio for SQLServer, and so on) and run dbcreateschema.sql (and usermanagement_dbcreateschema.sql if you performed step 5 and step 6). The ActiveMatrix tables are created.

Running the ActiveMatrix Administrator Server Creation Utility

When running the ActiveMatrix Administrator server creation utility:

• Use the administration cluster you have given for <ADMIN_CLUSTER_NAME> (in lower case or upper case).

• Use the environment name you have given for <ENV_NAME_IN_CAPS> above (in lower case or upper case).



• Use the DML username and password when the utility asks for the database parameters.

Sybase

This section describes how to create a non-sa user and sandbox database in a Sybase instance and create the ActiveMatrix schema in the sandbox database.

Creating a User and a Database in Sybase 15.x

This section describes how to create a sandbox database for a user in your Sybase instance. If you have a centralized production Sybase database you will probably want such a sandbox database and user.

1. Run Sybase Central and log in as sa.

2. Create a new database named sandbox-db-name. Go to Databases and click Add Database on the right hand side.

3. Create a user named sandbox-user-name. Go to Logins and click Add Login.

4. Run sybase-home-dir/OCS-15_0/bin/isql.exe -U sa -P sa-password -D sandbox-db-name, where sandbox-db-name is the database you created in step 1.

5. Change the owner of the current database to the user you created in step 3. Type sp_changedbowner sandbox-user-name, press Enter. Type go and press Enter.

6. Set the sandbox user's default database to the sandbox database. Type sp_modifylogin sandbox-user-name, defdb, sandbox-db-name and press Enter. Type go and press Enter.

Generating the Schema Using DB Script Generator

1. Package and install the Sybase native driver as described in Packaging and Installing Native Database Drivers in TIBCO ActiveMatrix Service Grid Installation.

2. Open a command window. Change to ENV_HOME/tools/bin and run flattener.exe -file

AMX_ADMIN_HOME/2.3/bin/dbscriptgenerator.tra.

3. Edit dbscriptgenerator.properties. Set the username and password to the values you specified in the preceding section and in the #Sybase Properties section, set the correct driver URL for the Sybase driver.

4. Run dbscriptgenerator.exe. By default, the schema are created in AMX_ADMIN_HOME/2.3/scripts/ddl/dbschema.ddl.



Creating Schema Generated by DB Script Generator

You cannot create schema in the database using the iAnywhere graphical tool because Sybase 15 server allows up to 255 byte table names, but iAnywhere does not support 30 byte table name length used by ActiveMatrix. To create the schema:

1. Run sybase-home-dir/OCS-15_0/bin/isql.exe -U sandbox-user-name -P sandbox-user-password (if you followed the instructions in Creating a User and a Database in Sybase 15.x on page 58, by default the database is the sandbox database).

2. Enable quoted identifiers, because ActiveMatrix generates schema with some names quoted and this is not the default for Sybase. Type set quoted_identifier on and press Enter.

3. Cut the create/alter part of the schema from the dbschema.ddl file created in Generating the Schema Using DB Script Generator on page 58 and paste it into isql.

4. Type go in the next line. The schema is created.

When you create the schema you will see the following warning messages. These can be ignored as they are benign.

Warning: Row size (3463 bytes) could exceed row size limit, which is 1962 bytes.Warning: Row size (5426 bytes) could exceed row size limit, which is 1962 bytes.Warning: Row size (2129 bytes) could exceed row size limit, which is 1962 bytes....Warning: Row size (2110 bytes) could exceed row size limit, which is 1962 bytes.Warning: Row size (17617 bytes) could exceed row size limit, which is 1962 bytes.Non-clustered index (index id = 2) is being rebuilt.Non-clustered index (index id = 2) is being rebuilt.Non-clustered index (index id = 2) is being rebuilt.Non-clustered index (index id = 2) is being rebuilt.



Default Runtime Node Configuration

The fields in Table 13 are used to configure the default runtime node. The fields are active when the Create a default runtime node checkbox is checked in the ActiveMatrix Administrator server creation utility. For detailed information on node properties and behavior, see Working with Nodes on page 190.

Table 13 Default Runtime Node

Field Description

Environment Name The name of the environment that contains the default node. The name must be less than 23 characters in length and can contain only alphanumeric and underscore (_) characters.

Default: development.

Node Name The default node’s name. The name must be less than 23 characters in length and can contain only alphanumeric and underscore (_) characters.

Default: node1.

Node Management Port

Management port on which the node listens and responds for management and control functions using JMX protocol.

Default:9992.

Provider URL The messaging server provider URL that specifies the Enterprise Message Service server that the node connects to.

Default: http://localhost:7222.

Username The messaging server user name for the node’s connection to the Enterprise Message Service server.

Default: admin.

Password The password for the messaging server user name account.

Default: No password.


Starting and Stopping the ActiveMatrix Administrator Server | 61

Starting and Stopping the ActiveMatrix Administrator Server

This section describes how to start and stop the ActiveMatrix Administrator server you created in Creating the First ActiveMatrix Administrator Server on page 26.

After you have performed one of the startup procedures described in the following sections, you can confirm that the server has started successfully by logging in to the ActiveMatrix Administrator user interface (see Logging in to the ActiveMatrix Administrator Graphical Interface on page 67.) If you cannot log in to the user interface, review the log (see Server Logs on page 337) for error conditions.

After you have started the first ActiveMatrix Administrator server in a cluster, you can add ActiveMatrix Administrator servers to the cluster and manage all the servers in a cluster using the procedures described in ActiveMatrix Administrator Servers on page 165.

The following preconditions must be satisfied before starting the server:

• The TIBCO Management Daemon process must be running. See Starting TIBCO Management Daemon, page 17.

• The database server must be running. See Starting the Database Server on page 15.

• The authentication realm must be available.

Starting and Stopping the ActiveMatrix Administrator ServerThis section describes procedures for starting up an ActiveMatrix Administrator server on all platforms.

In the following sections, cluster is the name of the cluster and server is the name of the server you provide when you create the server. If you accept the default values when you create the server, cluster is amx and server is admin.

First-time startup is slower than subsequent startups because the ActiveMatrix Administrator web application is deployed.



Windows

The ActiveMatrix Administrator server is installed as an Windows service with its Startup Type set to Manual. You can start the server in the Control Panel or via a batch script.

Control Panel

1. Open Control Panel > Administrative Tools > Services.

2. Right-click the service with a name of the form: TIBCO ActiveMatrix Administrator Server (cluster:server) and select Start.

To configure the server to start automatically when the machine starts, change the Startup Type to Automatic. To stop the server, right-click the service and select Stop.

To remove the ActiveMatrix Administrator server from Services:

1. Change directory to AMX_ADMIN_HOME/data/clustername/servername/bin.

2. Run cluster_server.exe --uninstall.

To add the ActiveMatrix Administrator server to Services:

1. Run cluster_server.exe --install.

Batch Script

To start the ActiveMatrix Administrator server in console mode:

1. Change directory to AMX_ADMIN_HOME/2.3/bin.

2. Run cluster_server. bat.

If you start the server from this script, you can stop it by Ctrl+C termination.

The last lines of the output are similar to the following:

**********************************************************TIBCO ActiveMatrix Administrator Server is initialized and ready.You can access it using the URL: http://AdminMachineName:8120/amxadministrator/**********************************************************7:07:47 AM- Started Application : amxadministrator.ear7:07:48 AM- Auto Deploy directory : [C:\tibco\ amxadministrator\data\amx\admin\archives\

The first time you start the service the Services application reports that the service has started before it has completely deployed and initialized. Wait a few minutes after the Services application reports that startup is complete before attempting to access the ActiveMatrix Administrator GUI.


Starting and Stopping the ActiveMatrix Administrator Server | 63

autodeploy]7:07:48 AM- Auto Deploy poll interval : [5 seconds]7:07:48 AM- Deploying Application : default_defaultApp7:07:48 AM- JSP precompilation is off. Skipping JSP pre-compilation for [default_defaultApp]7:07:48 AM- Started Application : default_defaultApp7:07:48 AM- Application [default_defaultApp] successfully Deployed7:07:48 AM- Accepting Web client requests:7:07:48 AM- Starting 5 HTTP Acceptor Threads [ OK ]7:07:48 AM- Starting 50 Worker Threads with max [ OK ] keep-alive waiting threads 10.7:07:49 AM- Configuration files backup [ OK ]

7:07:50 AM- Server [admin] started [ OK ]Thread[pool-1-thread-2] registered with management daemon: .C:\tibcoThread[pool-1-thread-1] registered with management daemon: MDMachine.C:\tibcoSUN version 1.5

where AdminMachineName is the name of the machine on which the ActiveMatrix Administrator server is running and MDMachine is the name of the machine on which a Management Daemon process is running. You see one such line for each Management Daemon process bound to the ActiveMatrix Administrator server.

UNIX

To start the ActiveMatrix Administrator server in console mode, run the following in a terminal window:

AMX_ADMIN_HOME/2.3/bin/cluster_server.sh

To start the ActiveMatrix Administrator server in background mode, run the following in a terminal window:

nohup AMX_ADMIN_HOME/2.3/bin/cluster_server.sh &

You can log out of the terminal and the ActiveMatrix Administrator server continues to run.




| 65

Chapter 4 ActiveMatrix Administrator Interfaces

This chapter describes the ActiveMatrix Administrator user interfaces.

Topics

• ActiveMatrix Administrator Interfaces Overview, page 66

• ActiveMatrix Administrator Graphical Interface, page 67

• ActiveMatrix Administrator Command-Line Interface, page 79


66 | Chapter 4 ActiveMatrix Administrator Interfaces

ActiveMatrix Administrator Interfaces Overview

ActiveMatrix Administrator provides three interfaces for interacting with the ActiveMatrix Administrator server: graphical, command line, and the checkstatus utility.

Graphical InterfaceThe graphical interface provides access to all ActiveMatrix Administrator functionality through a browser. In the ActiveMatrix Administrator graphical interface functionality is divided into perspectives. A perspective is a set of controls used to carry out a category of administration tasks.

ActiveMatrix Administrator Graphical Interface on page 67 describes how to log in to the ActiveMatrix Administrator graphical interface and provides an overview of the standard perspectives. The remaining chapters in this book provide extensive task and reference information on each perspective.

Extending theperspectives

TIBCO ActiveMatrix Administrator is extensible. This means that other TIBCO products can add functionality, such as new perspectives and new screens within the standard perspectives, to ActiveMatrix Administrator. The product-specific functionality is added to ActiveMatrix Administrator by uploading and deploying a plug-in containing new features. For information on managing plug-ins, see Plug-ins on page 163.

Command-Line InterfaceThe command-line interface provides access to most ActiveMatrix Administrator functions. In particular, it supports adding, editing, and deleting ActiveMatrix objects and actions such as starting and stopping, installing and uninstalling, and deploying and undeploying objects. You use the command-line interface for repetitive application of standard actions on large numbers of objects.

To use command-line interface you set up a data file that specifies the objects on which to perform actions and a build file that specifies the actions to be performed. For information on how to create the required files and run the interface, see ActiveMatrix Administrator Command-Line Interface on page 79.

checkstatus UtilityThe checkstatus utility compares the state of ActiveMatrix runtime objects to an expected state and reports the result. For information on checkstatus, see checkstatus Utility on page 381.


ActiveMatrix Administrator Graphical Interface | 67

ActiveMatrix Administrator Graphical Interface

This section describes how to log in to the ActiveMatrix Administrator graphical interface and provides an overview of the perspectives available in the interface.

Logging in to the ActiveMatrix Administrator Graphical Interface

To Access the Login Page From a Browser Window

In your browser’s address field, type a URL of the following format:

http://Hostname.Domain.com:HTTPPort/amxadministrator

For example: http://amxserver.acme.com.:8120/amxadministrator. The port is the HTTP port you specified for the server when you created it. (The domain name may not be required by your browser.)

To Access the Login Page From the Windows Start Menu

1. Select All Programs > TIBCO > TIBCO ActiveMatrix > Administrator Servers. You see a list of ActiveMatrix Administrator servers installed on the local machine.

2. Click the name of a server:



To Log in to the ActiveMatrix Administrator Graphical Interface

At the login screen, enter a valid username and password:

The ActiveMatrix Administrator session timeout is set to 15 minutes. If you do not actively use the ActiveMatrix Administrator graphical interface for a length of time equal to the timeout period you are automatically logged out the next time you interact with the interface.



Graphic Interface OverviewOnce you have logged into the graphical user interface, you see the Welcome page shown in Figure 4. The page is divided into header and welcome areas.

Figure 4 Welcome Page

Header

The main control in the header area is the Perspective drop-down list from which you can choose a perspective. If you select either the Configure an Environment or Deploy to an Environment perspectives, the Environment drop-down list, from which you can choose an environment, displays just below it.

The header also has links for logging out, changing the current user’s password (see Changing a User Password on page 143), displaying online help (see Help on page 77), displaying information about ActiveMatrix Administrator, and system messages (see System Messages on page 77).

The header appears in all screens in the graphical interface.



Welcome Area

The welcome area contains a list of perspectives (see Perspective Overview on page 70). This list is permissions-based; it displays only those perspectives that you have the right to use (see Permissions on page 147).

When you mouse over a perspective, a description of the perspective displays to the right of the perspective list.

You select a perspective by clicking a perspective in the list. If you click either the Configure an Environment or Deploy to an Environment perspectives, a menu listing available environments appears just below the perspective. Clicking one of the environments opens the selected environment in the parent perspective. Clicking any other perspective simply opens the perspective.

Once you open a perspective from the Welcome page, you leave the Welcome page. To return to the Welcome page you must log out and log in again.

Perspective OverviewThis section provides an overview of the four standard perspectives provided when ActiveMatrix Administrator is installed:

• Configure Enterprise Assets on page 71

• Configure Environments on page 72

• Deploy to an Environment on page 72

• Monitor & Manage on page 73

The Configure Enterprise Assets and Monitor & Manage perspectives have a tab bar below the header that allows you to select screens within each perspective. For example, the Configure Enterprise Assets tab bar has the tabs shown in Figure 5.

Figure 5 Enterprise Assets Tab Bar

The Configure Environments and Deploy to an Environment perspective have an Environment drop-down list in the header that allows you to select the environment on which to work.

The remaining sections in this chapter provide an overview of each perspective and the standard behaviors of the graphical interface. The remaining chapters in this manual provide complete task and reference information for each perspective.



Configure Enterprise Assets

In the Configure Enterprise Assets perspective , an IT administrator manages the hardware, software, and other enterprise assets that are made available to an ActiveMatrix runtime. Specifically, the administrator uses this perspective to perform the following actions on enterprise assets:

• Binds machines to the administrator cluster

• Creates environments and allocates machines to environments

• Configures administrator, database, messaging, registry, and policy servers

• Creates a user base and assigns permissions to users

• Creates shared resource definitions

• Creates a central keystore and populates it

Figure 6 on page 71 shows the Configure Enterprise Assets perspective.

Figure 6 Configure Enterprise Assets Perspective

For details on the functionality offered in this perspective, see Chapter 5, Configuring Enterprise Assets, on page 101 and Chapter 6, Defining Environments, on page 171.



Configure Environments

In the Configure Environments perspective , a TIBCO ActiveMatrix architect configures and manages the life cycle of ActiveMatrix runtime components: nodes, containers, and shared resources. Specifically the architect installs runtime components on allocated machines and configures them.

Figure 7 on page 72 shows the Configure Environments perspective.

Figure 7 Configure Environments Perspective

For details on the functionality offered in this perspective, see Chapter 7, Configuring Environments, on page 189.

Deploy to an Environment

In the Deploy to an Environment perspective , a TIBCO ActiveMatrix architect manages service assemblies: uploading, allocation of service units to nodes, deployment, and life cycle functions. Specifically the architect

• Distributes deployment artifacts to various nodes, configures them and deploys

• Performs initial verification and monitoring of system health and performance



Figure 8 on page 73 shows the Deploy to Environment perspective.

Figure 8 Deploy to Environment Perspective

For details on the functionality offered in this perspective, see Chapter 8, Deploying Service Assemblies, on page 217.

Monitor & Manage

In the Monitor & Manage perspective , an operations engineer manages the ActiveMatrix infrastructure and services deployed on the infrastructure. Specifically, the engineer

• Monitors the health and performance of infrastructure and services.

• Troubleshoots problems by

— Viewing current and historic statistics

— Tracking dependencies

— Viewing logs for infrastructure objects and services

• Takes corrective actions. For example, restarts infrastructure objects or services.

Figure 9 on page 74 shows the Monitor & Manage perspective.



Figure 9 Monitor & Manage Perspective

For details on the functionality offered in this perspective, see Chapter 9, Monitoring Infrastructure and Services, on page 241.

Working with the Graphical User InterfaceThe following sections describe various facets of working with the graphical user interface:

• Status Icons on page 74

• Screens on page 75

• Fields on page 75

• Tables on page 75

• Help on page 77

• System Messages on page 77

• Help on page 77

Status Icons

The user interface employs a rich set of icons to convey the status of components. The following icons are used across all perspectives:

Defined, Not Deployed Out of sync Unknown

Installed, Deployed Install Failed

Uninstalled Uninstall Failed

Running, Active Start Failed

Installed/Stopped, Not Active

Stop Failed



Other icons used in specific contexts are described in the following sections.

Screens

When a screen is selected, the screen selected icon displays to the left of the screen label.

Screens support view mode and edit mode. Within a screen there may be more than one area that can be edited, saved, and cancelled independently.

View Mode

View mode provides a read-only view of object details. The Edit button is displayed in View mode, allowing you to click Edit to edit the selection. When an item is successfully created or added, View mode is displayed by default.

Edit Mode

Edit mode allows you to edit objects. An area in Edit mode displays Cancel and Save buttons. If an object could not be successfully created or added, the object remains in Edit mode, allowing you to fix the error. The error is displayed in an Error dialog with an OK button. See System Messages on page 77 for more information. Cancel cancels any changes before saving. Save saves the changes and returns to View mode.

When an area is in Edit mode, a pencil icon is displayed to the left of the screen selected icon. You do not have to save changes before switching to another area. The pencil icon can appear multiple times in one screen.

Fields

Mandatory fields are indicated with an asterisk * at the end of the field label.

When there is a field-level problem, such as a validation error, the requested action cannot be completed. A dialog, with an OK button, is displayed and the screen behind is grayed out. The dialog describes the problem and is dismissed by clicking OK. The error message gives enough information so that you can fix the error. The display remains in Edit mode so the object can be edited.

Tables

Selecting Rows

When a screen containing a table is displayed, there is no default row selection.

Delete Delete Failed



Single row To select a single row in the table, click the row. Once a row that has been selected, the row is colored with a yellow gradient and details about the properties of the selected object are displayed in a form below the table.

Multiple rows Some tables support multiselect. For example, you could multiselect several nodes and click the Start button to start all of the nodes at once. When you select multiple rows, no properties are displayed in the form below the table. To select multiple rows, press Shift or Ctrl and click the rows.

Filtering Table Entries

Some tables allow you to filter the entries displayed in the table by usage or type. For example, the Enterprise Assets > Shared Resource Definitions table allows you to display specific types of definitions. Tables that support filtering have one or more View drop-down lists where you can select the objects to display in the table.

Sorting Table Rows

To sort table based on the value of a specific column, click the column header. If you click the column header more than once, the rows toggle between being sorted according to ascending or descending values in the column.

Hierarchical Lists

Some tables display their entries alternately as hierarchical and nonhierarchical lists. For example, in the Monitor & Manage > Infrastructure > Machine view you can toggle the Nodes list to display the environments and the nodes within each environment or as a list of nodes. In a hierarchical list, you toggle between displaying only the parent or the parent and it’s child objects by clicking the + to the left of the parent.

To toggle from a hierarchical to flat list, click the hierarchical list icon .

To toggle from a flat to hierarchical list, click the nonhierarchical list icon .

Performing Actions

The actions supported by entries in a table appear as buttons across the top of the table. The actions are specific to the objects listed in the table.



Updating Object Status

While the operations are in progress, the user interface displays the Working icon in the header and "working" icons—installing , uninstalling , starting , stopping , and deleting —in the status column of the object. When

the operation has completed, the user interface automatically updates the status to Installed or Install Failed, Defined or Uninstall Failed, Running, or Installed/Stopped. You can also manually update the status of objects by clicking the Refresh icon located at the top right of the table.

Certain long-running operations, such as installing and starting a node, are performed asynchronously. This means that the user interface continues to respond to user actions while the operation is in progress and does not automatically update the status. To update the object status for such operations, you must click the Refresh button .

Help

To display the online help for ActiveMatrix Administrator, click the Help link in the header.

To display help about a specific screen, click the help icon next to the screen title.

System Messages

When there is a system-level problem, such as a server communication problem or an environment name in use when attempting a delete operation, the requested action cannot be completed. A dialog, with an OK button, is displayed. The dialog refers you to system messages for details.

You can then click the Messages link in the right side of the header

to view the most recent system messages. The system messages alert icon displays next to the link when there are messages that haven’t been viewed. Once you click the link to view the messages, the icon disappears.

As shown in Figure 10 on page 78, the messages contains details about all errors that have occurred since the Messages link was last cleared. You can clear the messages by clicking the delete icon in the dialog frame.



Figure 10 System Messages

Limitations

The user interface is not the definitive source of information about the state of the ActiveMatrix system.

In some cases the status of nodes, containers, and shared resources shown in ActiveMatrix Administrator may not reflect the actual status of the objects. For example:

• A node is running, but the status has not yet been updated in ActiveMatrix Administrator to show the node as Running, but instead is shown as Installed/Stopped.

• A node is stopped, but the status has not yet been updated in ActiveMatrix Administrator to show the node as Installed/Stopped, but instead is shown as Running.

• A node is running, but the Management Daemon process is stopped and the but the node status is shown as Unknown.

The Log Viewer displays the log entries in existence when you run a query. Since log entries are generated continuously, after some time has elapsed since running the query the Log Viewer does not show the most recent log entries. You can configure the Log to periodically refresh itself.

Similarly, the Monitoring & Management perspective displays the state of the system when you retrieve information from the monitoring service. The data on every screen in this perspective is updated every minute.


ActiveMatrix Administrator Command-Line Interface | 79

ActiveMatrix Administrator Command-Line Interface

This section describes the actions you can perform with the command-line interface, the objects on which you can perform actions, how to specify the objects, and how to invoke the command-line interface.

ActionsThis section describes the actions that can be performed with the command-line interface.

Database Actions

These actions modify the objects contained in the ActiveMatrix Administrator database.

• Add Adds an object to the ActiveMatrix Administrator database. Add is also used to add associations between objects, such as between an environment and a shared resource definition.

• Edit Edits an object in the ActiveMatrix Administrator database.

• Delete Deletes an existing object from the ActiveMatrix Administrator database. Delete is also used to delete associations between objects, such as between an environment and a shared resource definition. When you delete an object, the entire tree rooted at the object is deleted starting at the leaves.

Runtime Actions

These actions modify the state of the objects contained in the ActiveMatrix runtime.

• Start Starts an object

• Stop Stops an object

• Install Installs an object

• Uninstall Uninstalls an object

• Activate Activates a container

• Deactivate Deactivates a container

Sometimes you must do some cleanup before you can delete an environment. In particular, you must stop and uninstall all nodes contained in the environment. After that you can delete the environment and all of its children.



• Deploy Deploys a service assembly

• Redeploy Redeploys a service assembly.

• Undeploy Undeploys a service assembly

ObjectsThis section describes the objects that can be accessed from the command-line interface, object attributes, relationships between objects, and the formats for expressing objects.

Supported Objects

The objects supported by the command-line interface are: Enterprise, Environment, Machine, LogServiceConfiguration, MonitoringConfiguration, AdminCluster, BootStrapUser, DBParameters, AuthenticationRealm, AdminServer, UDDIServer, User, ListOfSuperUser, Group, Permissions, SharedResourceDefinition, UIElement, SubstitutionVariable, Keystore, MessagingBus, MessagingServer, Node, Container, DefaultConnector, SharedResource, ServiceAssembly, ServiceUnit, SubstitutionVariable, Topic, Service, Logger, and SharedResourceProfile.

Each object has a set of attributes that describe that object. Some of these attributes, such as the name of the object, can be used to uniquely identify a particular object assuming the location of the object in the data hierarchy is known. We refer to such identifying attributes as ID attributes. The rest of the attributes are referred to as description attributes. For information about the attributes, see Supported Objects and Attribute Reference on page 94.

Table 14 summarizes the actions and the objects that support those actions.

Enterprise, AdminCluster, and ServiceUnit are container objects that do not support any actions.

Table 14 Actions and Objects (Sheet 1 of 3)

Add Edit Delete StartStop

InstallUninstall

DeployUndeploy

ActivateDeactivate

Environment Environment Environment

Machine Machine

User User User



ListOfSuperUser

ListOfSuperUser

Group Group Group

Keystore Keystore Keystore

SharedResourceDefinition



UDDIServer UDDIServer UDDIServer

UIElement

SubstitutionVariable



Permissions

AdminServer

AdminServer

AdminServer

AdminServer

LogServiceConfiguration

LogServiceConfiguration

MonitoringConfiguration

BootStrapUser

DBParameters

AuthenticationRealm

MessagingBus

MessagingServer

MessagingServer

MessagingServer

Node Node Node Node Node



InstallUninstall

DeployUndeploy

ActivateDeactivate



Inter-Object Relationships

Aside from attributes, each object has relationships with other objects. Relationships can be either parent-child or associative. In a parent-child relationship, such as that between an Environment and a Node, one of the objects is a child of the other object and is contained in that parent object. The possible parent-child relationships are illustrated in Figure 11 on page 83. In the figure, parents are on the left and children are on the right. User and Group are marked with an asterisk because they are children of Enterprise only when using the Database authentication realm.

Container

DefaultConnector

SharedResource

SharedResource

SharedResource

ServiceAssembly

ServiceAssembly

ServiceAssembly

ServiceAssembly

ServiceAssembly


Topic

Service

Logger Logger Logger

SharedResourceProfile



InstallUninstall

DeployUndeploy

ActivateDeactivate



Figure 11 Parent-Child Relationships

In an associative relationship, such as that between an Environment and a Machine, one object is not a child of the other, but the two objects need to work with each other. In such situations you must create a reference from one object to the other object. The possible associative relationships are illustrated in Figure 12. In the figure, the referencing objects are on the left and the referenced objects are on the right.

Enterprise

Environment

Machine

User*

ListOfSuperUser

Group*

Keystore

SharedResource Definition

UDDIServer

UIElement


Admin Cluster

MessagingBus

Node

Service Assembly

Container

DefaultConnector

Permissions

Logger

SharedResource


SharedResource Profile


Topic

Permissions

Logger

Service Unit

Service


Logger

Permissions

Permissions

Logger

MessagingServer

Permissions

AdminServer* LogService Configuration

Monitoring Configuration

BootStrapUser

DBParameters

AuthenticationRealm

Group*

Permissions

UIElement

Permissions



Figure 12 Object Association

Regardless of the type of relationship, the cardinality of the relationship a set of objects can have with each other can be one-to-one, many-to-one, or many-to-many. For example, the cardinality of the relationship between Environment and MessagingBus is one-to-one. The cardinality of the relationship between Node and Environment is many-to-one. The cardinality of the relationship between SharedResourceDefinition and Environment is many-to-many.

Object Formats

You specify the objects on which the command-line interface operates in an XML data file. The data file is input to the command-line interface along with a build file that specifies the actions to be performed on the data.

ActiveMatrix Administrator provides XSD schemas for the data files that capture all of the ID attributes, description attributes, parent-child relationships, and associative relationships of ActiveMatrix objects (see Data File Schemas on page 94). Every object is described in an XML element. The attributes of that object (both ID and descriptive) are attributes of the XML element, and the relationships this object has with other objects are subelements of the XML element. In these schemas, every ActiveMatrix object can be specified in three types of formats: base, full, and reference.

Base Format

• Captures the ID attributes of an object as XML attributes

• Captures the parent-child relationships of an object as XML elements

• Doesn’t capture any parent information about the object as that information is derived from the XML structure

You use the base format to:

• Delete an object

• Perform a runtime action on an object

Environment

Machine

SharedResource Definition

UDDIServer

Group User

ListOfSuperUser User

Node

Shared Resource Definition

Shared Resource Definition

Shared Resource Profile

Service Unit

UDDI Server



• Add a child to an object

• Perform an action on a child of an object

Full Format

• Is derived from base format

• Captures the ID and description attributes of an object as XML attributes

• Captures the parent-child and associative relationships of an object as XML elements

• Doesn’t capture any parent information about the object as that information is derived from the XML structure

You use full format:

• Whenever the base format can be used

• To add or edit an object

Reference Format

• Captures the ID attributes of an object as XML attributes

• Objects not residing directly under the Enterprise have parent information because it cannot be derived from the XML structure

You use reference format:

• When associating that object to another object

Examples

A node in base format has:

• ID attribute: name

• Parent-child relationships: Container, DefaultConnector

Data file element:

<Node name="node1"><Container type="com.tibco.matrix.container.javase.runtime"

version="2.0.0"/></Node>

An node in full format has:

• ID attribute: name

• Other required attributes: hostname, productInstallDirectory, and so on

• Description attribute: description



• Parent-child relationships: Container, DefaultConnector

Data file element:

<Nodexsi:type="amxdata:Node" name="node1"description="desc" hostName="Hostname"tibcoHome="ENV_HOME"productInstallDirectory="AMX_HOME"productVersion="2.3.0"messagingServerName="ms1" namingPort="namingPort ><Container type="com.tibco.matrix.container.javase.runtime"

version="2.0.0"/></Node>

A node in reference format has:

• Id attributes: nodeName

• Parent attribute: environmentName

Data file element:

<ServiceUnit xsi:type="amxdata:ServiceUnit" name="SOAP SU">...<Node environmentName="env1" nodeName="node1"/>

...</ServiceUnit>

Notice that when using the base format you do not need to include the xsi:type attribute in the node element because the base format is the default format expected by the Enterprise object. You must include the xsi:type attribute only when you want to override the default type as specified in the XSD.

For example, in amxdata_base, an Enterprise contains zero or more Environment_base objects. If you want to create an Environment_base object, then you don’t need to include an xsi:type attribute required because that is what is declared in the XSD. However, if you want to define an Environment object under the Enterprise, where Environment is a type that derives from Environment_base, you need to use the xsi:type attribute to tell the XML parser that you are using a different type than the default. The XML parser internally verifies that the type used derives from the default type.

As another example, consider associating a Node with a ServiceUnit. In the schema, a ServiceUnit can have a list of zero or more Node_references. If you intend to use the Node_reference type, then you don’t have to use xsi:type because that is what is specified in the schema. Also there is nothing in the schemas that derives from Node_reference, so you don’t have the ability to override what type to use. Thus there would never be a reason why you should need xsi:type for associating Nodes with ServiceUnits. You should note that the XML parser parses elements even if you do use xsi:type attribute; it’s just a convenience to only have to use it when overriding default types in schemas.



Invoking the Command-Line InterfaceThe command-line interface is based on Ant, an open source build tool (http://ant.apache.org). It is implemented as an Ant tasks named AMXAdminTask (see AMXAdminTask on page 89) and AMXAdminConfigTask (see AMXAdminConfigTask on page 99). AMXAdminTask is used for operations on most objects. AMXAdminConfigTask is used to change the properties of the cluster objects DBParameters and AuthenticationRealm. You specify one these Ant tasks in a build target within a build file, an XML format build configuration file that is the input to the tool admincmdline. To invoke the command-line interface:

1. Change to the directory AMX_ADMIN_HOME/2.3/bin.

2. Run admincmdline build.xml, where build is the name of the build configuration file.

The following sections describe the structure of the build file and the syntax of AMXAdminTask and AMXAdminConfigTask.

Build File

The build file must contain the following four elements: project, taskdef, target, and AMXAdminTask or AMXAdminConfigTask.

project Element

The project element declares the default build target for the build.xml file. taskdef and target are subelements of project. The value of the name attribute of the target element must be the same as the value of the default attribute of the project element.

<project default="target"><taskdef ... /><target name="target" ... />

</project>

taskdef Element

The taskdef element specifies the class that implements the Ant task. It must include the name and classname attributes defined exactly as follows:

<taskdef name="AMXAdminTask" classname="com.tibco.matrix.administration.command.line.ant.AMXAdminTask"/>

or

<taskdef name="AMXAdminConfigTask" classname="com.tibco.matrix.administration.command.line.ant.AMXAdminConfigTask"/>


http://ant.apache.org


target Element

The target element specifies the actions performed for an execution of the command line interface via the AMXAdminTask or AMXAdminConfigTask subelement.

<target name="target"><AMXAdminTask ... />

</target>

or

<target name="target"><AMXAdminConfigTask ... />

</target>


AMXAdminTask | 89

AMXAdminTaskAnt Task

Description Specifies the administrative action and objects on which the action is performed.

Syntax <AMXAdminTask action="action" dataFile="dataFile" adminURL="URL" username="username" password="password"[actionTimeoutSecs="timeout"][failOnError="{true|false}"][objectSelector="XPath_Expression"][overwrite="{true|false}"][merge="{true|false}"][createIfNotExists ="{true|false}"][force="{true|false}"] /></AMXAdminTask>

Options

You authenticate from the command-line interface either by providing a username and obfuscated password in build.xml or in response to a prompt. See Creating an Obfuscated Password on page 28.

Table 15 Options (Sheet 1 of 4)

Attribute Type Req? Description

action String Yes One of the actions listed in Actions on page 79. The action is case insensitive.

• Unless objectSelector is specified, the action is applied to every object in the data file.

• The order in which the action is applied to the objects is either breadth first or depth first. The method used is determined by the action.

— Add, Edit, Install, Start, Stop, Activate, Deactivate, Deploy, Undeploy: breadth first

— Delete, Uninstall: depth first

• Some actions are not performed against certain object formats (see Object Formats on page 84).

— For the most part, Add and Edit are applied only to objects specified in full format. Objects not in this format are skipped.



actionTimeoutSecs String No Set the timeout for node actions that are performed asynchronously (install, uninstall, start, stop). The timeout controls how long the tool waits for the actions to complete. Note that the tool does not stop the actions when the timeout is reached but continues processing the rest of the objects in the data file.

The default timeout is 180 seconds. The default timeout time is configurable. To set the default timeout time, set the property java.property.node.runtime.action.timeout in the file AMX_ADMIN_HOME/bin/admin_cmdline.tra.

adminURL URL Yes The URL of the ActiveMatrix Administrator server.

createIfNotExists Boolean No Relevant to the Edit action. If an object is to be edited but doesn’t yet exist and this flag is true, then the object is added.

Default: false.

dataFile String Yes The absolute path to the XML file containing the object data. See Data File on page 94.

failOnError Boolean No Causes the Ant task to fail when an unrecoverable error is reported.




AMXAdminTask | 91

force Boolean No Relevant to the Delete and Uninstall actions. Force delete is supported for service assemblies and nodes and force uninstall is supported for nodes.

A node must be in the Uninstalled state before it can be deleted and it must be Stopped before it can be uninstalled. If any problems occur moving the node to one of these states, and force is true, the node is deleted even if it is not in the uninstalled state or uninstalled even if it is not stopped.

A service assembly must be in the Undeployed state before it can be deleted and it must be Stopped before it can be undeployed. If any problems occur moving the service assembly to one of these states, and force is true, the service assembly is deleted even if it is not in the Undeployed state.

Default: false.

merge Boolean No Relevant to the Add action, and only if the overwrite flag was used and is true.

If an object to be added already exists and

• If this flag is true and the overwrite flag is true, then the existing object is overwritten by merging with the new object. That is, the old object's data is updated with the new object's data.

• If this flag is false but the overwrite flag is true, then the existing object is deleted altogether and replaced by the new object. The old object's children, if any, are lost in the process.

Default: false.





Examples This section contains examples of the AMXAdminTask task attributes and describes the effect of using the attributes.

objectSelector• objectSelector="//*"

Process all objects.• objectSelector="//Node"

Process all nodes.• objectSelector=”/Environment[@name=’env1’]/Node[@name=’node1’]"

Process node1 in environment env1.

objectSelector String No Specifies the set of objects to be processed. The set of objects is defined by an XPath expression. For information on the XPath language, see http://www.w3.org/TR/xpath.

If this attribute is not specified:

• All of the objects in the data file are processed.

• The heuristic used to determine the order in which the objects are processed depends on the action attribute.

overwrite Boolean No Relevant to the Add action. If an object to be added already exists and this flag is true, then the existing object is overwritten.

There are two ways in which an object can be overwritten: it can be merged, or created from scratch. The strategy used is determined by the merge flag.

Default: false.

password Obfuscated String

Yes The obfuscated password of the ActiveMatrix user executing the task. See Creating an Obfuscated Password on page 28.

Note: The password is not masked when you type it into the command line.

username String Yes The name of the ActiveMatrix user executing the task.




http://www.w3.org/TR/xpath

AMXAdminTask | 93

overwrite and merge

Assume you have a data file with environment env1 and node node1, and nothing in the database. You add both objects. If you then do another add with the same data file

• With overwrite = false (merge is then ignored), the interface processes env1, determine that it already exists, and does nothing. The interface then processes node1, determines that it already exists, and does nothing.

• With overwrite = true and merge = false, the interface processes env1, determines that it already exists. It deletes the existing env1 and replaces it with the new env1. The old node1 is deleted in the process. When the interface processes node1 in the data file, it doesn’t exist yet and so it is just added.

• With overwrite = true and merge = false, the interface processes env1, determines that it already exists, and updates the existing env1 with data from the new env1. It processes node1, determines that it already exists, and updates the existing node1 with data from the new node1.

create

Assume you have an environment env1 in the database. Your data file has environment env1 and a node node1. If you do an edit and

• create = false, the interface processes env1, determines that it already exists, and edits the data to match that of the new env1. It then processes node1, determines that it doesn’t exist, and does nothing.

• create = true, the interface processes env1, determines that it already exists, and edits the data to match that of the new env1. It then processes node1, determines that it doesn’t exist, and adds node1 to env1.

force

Assume you have an environment env1 and node node1 in both the database and the data file. node1 is in the Started state. If you do a delete and

• force = false, the interface processes node1 (depth-first search), notices that it is in the Started state, and attempts to stop it and then uninstall it. There are two possible outcomes:

— The stop and uninstall are successful. node1 is deleted. The interface processes env1 and since env1 doesn’t support life cycle management, it deletes it.

— The stop or uninstall fails. node1 is not in the uninstalled state so it cannot be deleted. The interface then quits out of the delete command.



• force = true, the interface processes the node1 (depth-first search), notices that it is in the Started state, and attempts to stop it and then uninstall it. There are two possible outcomes:

— The stop and uninstall are successful. node1 is deleted. The interface processes env1 and since env1 doesn’t support life cycle management, deletes it.

— The stop or uninstall fails. node1 is not in the uninstalled state but it is forcefully deleted. The interface processes env1 and since env1 doesn’t support life cycle management, deletes it.

Data File

The data file is an XML file that specifies attributes of the objects that are operated on by the AMXAdmin task. This section describes the data file schemas and the location of reference information for object attributes.

Data File Schemas

The data file schemas are located in AMX_ADMIN_HOME/2.3/schemas and are named

• amxdata.xsd Full format definitions.

• amxdata_base.xsd Base format definitions.

• amxdata_detailed.xsd Details of shared resource definitions, permissions, and logger appenders. You cannot perform any actions on the objects defined in this schema.

• amxdata_reference.xsd Reference format definitions.

Supported Objects and Attribute Reference

Table 16 lists the objects specified in the schema and provides links to the sections containing attribute reference information.

Table 16 Supported Objects and Their Attribute Reference Sections

Object Attribute Reference Section

AdminServer Administrator Server Reference on page 167.

Container Container Reference on page 206.

DefaultConnector Default Connector Reference on page 201.

Enterprise Configuring Enterprise Assets on page 101.


AMXAdminTask | 95

Environment Working with Environments on page 175.

Group Groups on page 145.

Keystore Managing Keystores on page 158.

ListofSuperUser Superusers on page 140.

Logger Object Logging Configuration Reference on page 316.

Machine Bound Machine Reference on page 112.

MessagingBus Configuring Messaging Bus on page 176.

MessagingServer Messaging Server Reference on page 180.

Node Node Reference on page 197.

Permissions Permissions on page 147.

Service Services Reference on page 240.

ServiceAssembly Service Assembly Reference on page 226.

ServiceUnit Service Units Table Reference on page 233.

SharedResource Shared Resource Reference on page 211.

SharedResourceDefinition Resource Definition Reference on page 120.

SharedResourceProfile Shared Resource Profiles Reference on page 236.

SubstitutionVariable Substitution Variables on page 118, Local Substitution Variables Reference on page 214, Substitution Variables Tab on page 235.

Topic Topics Reference on page 237.

UDDIServer UDDI Server Reference on page 157.

User Users on page 140.

Table 16 Supported Objects and Their Attribute Reference Sections

Object Attribute Reference Section



Examples

This section contains an example build.xml file and an example data file, single_node_data.xml, referenced in the build.xml file. For more examples, see AMX_ADMIN_HOME/2.3/samples/.

build.xml

The tasks in build.xml add a machine, an environment, a node and its containers, a shared resource definition, and a shared resource. The machine is enabled for the environment, the containers are enabled for the node, and the shared resource definition is enabled for the environment and the shared resource is enabled for the node.

<project default="main"><property file="login.properties"/><taskdef name="AMXAdminTask"

classname="com.tibco.matrix.administration.command.line.ant.AMXAdminTask"/>...<target name="init" description="Set up Environment, Machine,

Messaging Bus"><AMXAdminTaskadminURL="http://localhost:8120/amxadministrator"username="${username}"password="${password}"action="add"dataFile="node_data.xml"objectSelector="Machine | Environment |

Environment/MessagingBus/MessagingServer | Environment/Machine"overwrite="true"merge="true"createIfNotExists="true"failOnError="true"force="true"/>

</target>

<target name="node-add" description="Add Nodes and Containers"><AMXAdminTaskadminURL="http://localhost:8120/amxadministrator"username="${username}"password="${password}"action="add"dataFile="single_node_data.xml"objectSelector="Environment/Node | Environment/Node/Container"overwrite="true"merge="true"createIfNotExists="true"force="true"/>

</target>

<target name="sr-add" description="Add Shared Resource Definitions"><AMXAdminTask


AMXAdminTask | 97

adminURL="http://localhost:8120/amxadministrator"username="${username}"password="${password}"action="add"dataFile="node_data.xml"objectSelector="SharedResourceDefinition |

Environment/SharedResourceDefinition | Environment/Node/SharedResource"

overwrite="true"merge="true"createIfNotExists="true"force="true"/>

</target></project>

single_node_data.xml

This data file creates an environment named env1, a messaging server named ms1, a shared resource definition named conn8989, a node named node1, containers in the node, and a shared resource in the node.

<amxdata_base:Enterprise...<Machinexsi:type="amxdata:Machine"hostName="sbodoff-lt"tibcoHome="C:/tibco"managementURL="service:jmx:jmxmp://sbodoff-lt:9998"/>

<Environmentxsi:type="amxdata:Environment"name="env1"description="desc"><MachinehostName="sbodoff-lt"tibcoHome="C:/tibco"/>

<SharedResourceDefinition name="conn8989"/>

<MessagingBus<MessagingServer

xsi:type="amxdata:MessagingServer"name="ms1"description="desc"clientID=""username="admin"password=""><DirectConfigurationproviderURL="tcp://localhost:7222"useXAConnectionFactory="false"/>

</MessagingServer></MessagingBus>

<Nodexsi:type="amxdata:Node"



name="node1"description="desc"hostName="sbodoff-lt"tibcoHome="C:/tibco"productInstallDirectory="C:/tibco/amx/2.3"productVersion="2.3.0"managementPort="4432"><Container type="com.tibco.matrix.soapbinding.runtime"

version="2.0.0"></Container><Container type="com.tibco.matrix.javase.runtime"

version="2.0.0"></Container><SharedResource

xsi:type="amxdata_reference:SharedResourceDefinition_reference" name="conn8989"/>

<MessagingServer name="ms1"/></Node></Environment>

<SharedResourceDefinition name="conn8989" xsi:type="amxdata:SharedResourceDefinition"><HTTPSharedResourceDefinition

port="8989" host="sbodoff-lt"connectionTimeoutMillis="20000" disableUploadTimeout="false"enableDnsLookups="true" maxPostSizeBytes="1000" maxThreads="150"minThreads="25" redirectPort="12346" />

</SharedResourceDefinition>

</amxdata_base:Enterprise>


AMXAdminConfigTask | 99

AMXAdminConfigTaskAnt Task

Description Specifies the administrative action and objects on which the action is performed.

Syntax <AMXAdminConfigTask action="action" dataFile="dataFile" adminServerName="server" adminClusterName="cluster" username="username" password="password"[failOnError="{true|false}"][objectSelector="XPath_Expression"]</AMXAdminTask>

Options

You authenticate from the command-line interface either by providing a username and obfuscated password in build.xml or in response to a prompt. See Creating an Obfuscated Password on page 28.



action String Yes One of the actions listed in Actions on page 79. The action is case insensitive.

• Unless objectSelector is specified, the action is applied to every object in the data file.

• The order in which the action is applied to the objects is either breadth first or depth first. The method used is determined by the action.

— Add, Edit, Install, Start, Stop, Activate, Deactivate, Deploy, Undeploy: breadth first

— Delete, Uninstall: depth first

• Some actions are not performed against certain object formats (see Object Formats on page 84).

— For the most part, Add and Edit are applied only to objects specified in full format. Objects not in this format are skipped.

adminClusterName String Yes The name of the ActiveMatrix Administrator cluster.

adminServerName String Yes The name of the ActiveMatrix Administrator server.



dataFile String Yes The absolute path to the XML file containing the object data. See Data File on page 94.

failOnError Boolean No Causes the Ant task to fail when an unrecoverable error is reported.

objectSelector String No Specifies the set of objects to be processed. The set of objects is defined by an XPath expression. For information on the XPath language, see http://www.w3.org/TR/xpath.

If this attribute is not specified:

• All of the objects in the data file are processed.

• The heuristic used to determine the order in which the objects are processed depends on the action attribute.

password Obfuscated String

Yes The obfuscated password of the ActiveMatrix user executing the task. See Creating an Obfuscated Password on page 28.

Note: The password is not masked when you type it into the command line.

username String Yes The name of the ActiveMatrix user executing the task.




http://www.w3.org/TR/xpath

| 101

Chapter 5 Configuring Enterprise Assets

This chapter describes how to configure the hardware, software, and other enterprise assets used by an ActiveMatrix runtime.

Topics

• Managing Machines, page 102

• Managing Shared Resource Definitions, page 116

• Managing Users, Groups, and Permissions, page 139

• Managing UDDI Servers, page 156

• Managing Keystores, page 158

• Managing ActiveMatrix Administrator Clusters, page 162

• Working with Substitution Variables, page 169


102 | Chapter 5 Configuring Enterprise Assets

Managing Machines

You use ActiveMatrix Administrator to discover and bind to machines you want to include in the ActiveMatrix runtime. You associate each bound machine with one or more environments. When you configure an environment, you can use only the machines associated with that environment.

OverviewThis section describes how ActiveMatrix Administrator discovers and binds to machines.

Discovering Machines

You can discover machines on the same subnet and on different subnets using search parameters that you define and save for reuse. ActiveMatrix Administrator supports discovery in a wide variety of network topologies which include point to point, multicast, and broadcast.

Discovery of machines on the same subnet is achieved using broadcast or multicast. Discovery of machines on a different subnet is achieved using JMX to tunnel to one machine on the subnet, then broadcast or multicast to discover other machines in the subnet.

Local Network Discovery

Figure 13 on page 103 illustrates how you discover machines running on local networks using multicast or broadcast URLs. The broadcast address for a subnet is determined by a combination of the subnet mask and network class defined by the network administrator. Ask your network administrator for the multicast and broadcast IP addresses used in your network. Some companies choose not to use broadcast addresses.

To determine the current settings for the port number, see UDP, Discovery, and Management Ports on page 18.

By default, the port on which the Management Daemon processes listen for requests sent using the UDP protocol is set to 1965.

The default broadcast mask is often 255, but it can be more or less in any network, depending on configuration.


Managing Machines | 103

Figure 13 Local Network Discovery

Each Management Daemon process returns a datagram with the following information:

• Management Daemon process name and description

• TIBCO home that the Management Daemon process is managing

• The Management Daemon’s discovery JMX address

Then ActiveMatrix Administrator uses the discovery JMX addresses to query the Management Daemon processes for the management JMX address you can use to connect to and control the nodes on each machine.

Bridged Network Discovery

Figure 14 on page 104 illustrates how you discover machines running on a different subnet from ActiveMatrix Administrator. First you connect to one machine using the JMX discovery URL and initiate the discovery process. That machine discovers other machines on its subnet using broadcast or multicast.

Broadcast/Multicast

MD3 on M3

MD5 on M5

MD8 on M8

User enters search parameters and discovers Management Daemon instances on remote machines

Legend

ASM

MD

Administrator serverMachineTIBCO Management Daemon

AS1 on M1 AS2 on M2

Admin Cluster 1



Figure 14 Bridged Network Discovery

In addition to the multicast or broadcast and UDP information, you enter the hostname and JMX port for the Management Daemon you plan to use. ActiveMatrix Administrator uses this information to construct the JMX discovery URL. The format for the URL is:

service:jmx:jmxmp://Hostname:Port

To determine the current settings for the port number, see UDP, Discovery, and Management Ports on page 18.

When you execute the search, ActiveMatrix Administrator establishes the JMX connection with the Management Daemon process (step 1 in Figure 14). Then the Management Daemon process issues the broadcast or multicast discovery requests (step 2 in Figure 14).

Broadcast/Multicast

JMX/JM

XMP

User enters JMX discovery URL and initiates discovery process with Management Daemon M16, on a different subnet

MD14 on M14

MD12 on M12

MD16on M16

M16 broadcasts to subnet; returns all discovered management JMX URLs to AS1.

2

1

AS1 on M1 AS2 on M2

Admin Cluster 1Legend

ASM

MD

Administrator serverMachineTIBCO Management Daemon



Binding Machines

Of the available machines that meet your discovery search criteria, you select the ones you want to bind to. Binding connects the ActiveMatrix Administrator cluster to the ActiveMatrix installations that you use for your ActiveMatrix runtime.

Up-to-date status on the bound machines and the ActiveMatrix software installed on the machines displays in the Machines list available in the Configure Enterprise Assets perspective.

For details on how to bind machines, see Binding Machines on page 107.

Automatically Binding to the ActiveMatrix Administrator Server Machine

During startup of an ActiveMatrix Administrator server, the server attempts to automatically bind to the machine on which the server is running. In order for automatic binding to occur, the Management Daemon process on the machine must be running before the ActiveMatrix Administrator server is started.

To bind to the machine, the ActiveMatrix Administrator server performs the following steps:

1. Reads the Management Daemon configuration file and extracts the bind URL.

2. Attempts to bind to the machine (equivalent to a manual bind action as described in the preceding section).

Whether the auto-bind operation is successful or not, the ActiveMatrix Administrator server starts up normally.

Auto-bind Success

If the auto-bind operation is successful, then the machine is listed in the Bound Machines table with status Connected | Available.

Auto-bind Failure

The auto-bind operation is attempted only when the ActiveMatrix Administrator server starts up. If at that time, the Management Daemon is not running, or if a ping hostname command fails, where hostname is the literal hostname of the machine, then auto-bind fails. There is no task in the server that attempts the auto-bind operation after server startup. If auto-bind has failed at startup, then you must manually discover and bind to the machine.

If this operation fails for any reason, a warning is logged and displayed. If the machine was already bound in the past, it is listed in the Bound Machines table with status Connected | Unavailable. If the machine was never bound in the past, then it is not listed in the Bound Machines table.



Enabling Bound Machines in Environments

For each bound machine, you specify which machines are enabled in a given environment. Specifically, you can install an environment’s nodes on any machine that is enabled in the environment.

You add new environments in the Configure Enterprise Assets perspective and then enable one or more machines. You define new environments using the Environment Definition screen available at the Configure Enterprise Assets perspective.

You can change the list of machines enabled in an environment at any time. During the design and configuration phase of setting up your ActiveMatrix runtime, for example, changes in plan may require changes in the configurations you have set up.

If you disable a machine in an environment, the ActiveMatrix runtime still runs but cannot be administered. If you later enable the machine in the environment again, administration can resume.

For details on how to enable machines, see Enabling Machines on page 184.

ActiveMatrix Administrator Cluster, Machine, and Environment Relationships

Figure 15 illustrates the possible relationships that can exist between ActiveMatrix Administrator clusters, machines, and environments:

• An environment is administered by only one ActiveMatrix Administrator cluster. The environment can be administered from any of the ActiveMatrix Administrator servers within the cluster. Environment 1 is administered by Admin Cluster 1 and Environment 2 and Environment 3 are administered by Admin Cluster 2.

• One ActiveMatrix Administrator cluster can administer multiple environments. Admin Cluster 2 administers Environment 2 and Environment 3.

• A machine can be bound to more than one ActiveMatrix Administrator cluster. In Figure 15, Machine 1 is bound to Admin Cluster 1 and Admin Cluster 2.

If you bind a machine to more than one cluster, the clusters must have different names. Otherwise, when you bind the machine to the second cluster, the first cluster’s configuration maintained by the machine is overwritten by the second cluster’s configuration and the following message appears on the Management Daemon console on that machine:

"Will overwrite old datastore: firstcluster".



Figure 15 Relationships between ActiveMatrix Administrator, Machines, and Environments

Binding MachinesTo bind machines to an ActiveMatrix Administrator cluster:

1. Select Configure Enterprise Assets from the Perspective drop-down list.

2. Click the Machines link.

3. Click Discover. The Discover Machines dialog is displayed.

Add searchparameters

4. Click Add. The Add Search Parameters dialog displays.

Admin Cluster 1 Admin Cluster 2

Bound Bound

Administer Administer

Environment 2Environment 1

Administer

Environment 3

Machine 2Machine 1

Bound

Database1 Database2



See Discovering Machines on page 102 and Add Search Parameters Reference on page 113 for details on specifying search parameters and for default values.

a. Enter a name and description to help you identify the purpose of this search parameter.

b. In the Subnet field, select one of the following:

— Local Searches for machines on the same subnet as the ActiveMatrix Administrator cluster.

— Bridged Searches for machines on a different subnet from the ActiveMatrix



Administrator cluster.

c. If you selected Bridged in the Subnet field, enter the hostname and JMX discovery port of the Management Daemon on one machine in that network.

d. Enter the broadcast or multicast address and UDP port for the search.

e. Click Add. The parameter you added appears in the Search Parameters list.



Select searchparameters and

search

5. Select one or more search parameters in the table. When you use multiple search parameters, a superset is returned, that is, the combination functions as a union rather than an intersection.

a. In the Timeout field, specify a timeout value as desired. The amount of time it takes to discover machines varies depending on the network topology and load. Set the timeout value appropriately.

b. Click Search. The list of machines matching the search parameters displays in the Discovered Machines table.

Select and bindmachines

6. In the Discovered Machines table, select the machines to which you want to bind and click Bind.

7. Dismiss the dialog. The bound machines appear in the Bound Machines table on the left. You can view various details about the bound machines. See Bound Machine Reference on page 112.

Each bound machine must be enabled in one or more environments. See Enabling Machines in an Environment on page 184 for details.

Command-Line Interface

The discovery process described in the preceding section applies when you are binding using the graphical interface. If you are using the command-line interface, you must determine the JMX management URL by examining the Management Daemon configuration file (see UDP, Discovery, and Management Ports on page 18) and provide it as an attribute when you bind the machine to the enterprise as follows:

<Machine

Bridged searches usually need a larger timeout value.

Local searches return matching machines as soon as they are discovered. Bridged searches iterate through the entire timeout period and then return the result.



xsi:type="amxdata:Machine"hostName="Hostname"tibcoHome="TIBCO_HOME"managementURL="service:jmx:jmxmp://Hostname:9998"/>

Unbinding MachinesYou can bind and unbind machines to suit your needs.

If you unbind a machine, ActiveMatrix nodes still runs but you can’t perform management actions because ActiveMatrix Administrator is not able to determine node status.

To unbind machines from an ActiveMatrix Administrator cluster:



3. In the Bound Machines table, select the machines you want to unbind and click Unbind.

Bound Machines TableThis table displays view-only details about the machines in the Bound Machines table.

Table 18 Bound Machines Reference

Column Description

Hostname Name of the machine.

TIBCO Home Installation directory for ActiveMatrix software installed on this machine. (On UNIX there can be more than one TIBCO home on a machine).

OS The operating system installed on the machine.

Status The status of the machine. Possible values are:

• Bound | Available The machine has been bound to the ActiveMatrix Administrator cluster and is available.

• Bound | Not Available The machine has been bound to the ActiveMatrix Administrator cluster but is not available.

• Agent Down The machine is not accessible. This could be because it stopped or because the network connection failed.



Bound Machine ReferenceThis area displays view-only details about the machine currently selected in the Bound Machines table.

Table 19 Bound Machine Reference

Field Description

Hostname Name of the machine.

TIBCO Home Installation directory for ActiveMatrix software installed on the machine. (On UNIX there can be more than one TIBCO home on a machine).

Bound By The user that bound the machine. If the machine has been bound automatically (see Automatically Binding to the ActiveMatrix Administrator Server Machine on page 105), the field displays (auto-bound).

Discovery URL A JMX URL used to discover the management URL. The URL is empty if the machine has been bound through the command-line interface because the management URL is not discovered. See Command-Line Interface on page 110.

Management URL The JMX URL used to communicate node status and send life cycle commands such as Stop and Start to the node.

Operating System The operating system installed on the machine.

Daemon Name The name of the Management Daemon process managing the TIBCO resources on the machine.

Daemon Description

A short description of the Management Daemon process.



Add Search Parameters Reference

Table 20 Add Search Parameters Reference

Field Description

Name A name for the search parameter. The name displays in the Search Parameters table.

Description A short description of the search parameter.

Network Interface The name of the network interface used by the Management Daemon process. In most cases, this field can be left blank.

If you want to specify the network interface, use the value in the Management Daemon configuration file described in UDP, Discovery, and Management Ports on page 18.

Subnet A drop-down list specifying the subnet in which to search for machines:

• Bridged Search for machines running in a different subnet from the one where ActiveMatrix Administrator is running.

• Local Search for machines in the same subnet as the one where ActiveMatrix Administrator is running.

Hostname Displays only when Bridged is selected for Subnet. The hostname of a machine on the subnet. The machine must be running a Management Daemon process.

JMX Port Displays only when Bridged is selected for Subnet. The discovery JMX port of the machine whose hostname you specified in Hostname field.

The JMX port is declared in the configuration.xml file of the Management Daemon. See Bridged Network Discovery on page 103.

Default: 9999.

Multicast or Broadcast Address

The address used for multicast or broadcast search.

Default: 239.100.106.107.

UDP Port The UDP port used for search.

Default: 1965.



Search Parameters Reference

Discovered Machines Reference

Table 21 Search Parameters Reference

Column Description

Name The name of the search parameter.

Multicast/Broadcast Address

The address used for multicast or broadcast search.

Default: 239.100.106.107.

UDP Port The UDP port used for search.

Default: 1965.

Discovery URL A JMX URL used to connect to the Management Daemon process on the machine to discover the management URL. Used for bridged subnet search only.

Timeout A number of seconds after which the search stops if no machines are found using the search parameter or parameters.

Table 22 Discovered Machines Reference

Column Description

Name The name of the machine.

TIBCO Home Installation directory for ActiveMatrix software installed on the machine. (On UNIX there can be more than one TIBCO home on a machine).

Management URL The JMX URL used to communicate node status and send life cycle commands such as Stop and Start to the node.



Status The binding status of the machine. One of:

• Binding ActiveMatrix Administrator is attempting to bind to the machine.


• Bound | Not Available The machine has been bound to the ActiveMatrix Administrator cluster but is not available. The Management Daemon could not reach the machine. Rebinding might solve the problem.

• Not Bound The machine is not bound and a connection has been attempted.

Table 22 Discovered Machines Reference (Cont’d)

Column Description



Managing Shared Resource Definitions

A shared resource definition is a template for a shared resource. Shared resource definitions specify connection details for specific physical resources. Creating multiple shared resources from one shared resource definition allows you to reuse definitions and control use of the resources at the node level.

Once you have created shared resource definitions, you instantiate the definitions by installing them as shared resource objects in nodes. If a shared resource definition changes, all shared resources that reference it are updated with the changes when you restart the node on which the shared resource is installed.

How JNDI Shared Resource Definitions Are Used

All shared resource definition types except JNDI are used when defining shared resources of the same type. For example, you use an HTTP server shared resource definition when defining an HTTP shared resource.

JNDI shared resource definitions are used only when defining JDBC and JMS shared resource definitions. When you define a JDBC or JMS shared resource definition, you can select the JNDI connection type. You then choose a JNDI shared resource definition that provides the necessary connection details.

From the Shared Resource Definitions screen you can perform the following tasks:

• Creating a Shared Resource Definition on page 116

• Editing a Shared Resource Definition on page 117

• Deleting a Shared Resource Definition on page 119

Creating a Shared Resource DefinitionTo create a shared resource definition:


2. Click Shared Resource Definitions.

3. In the Shared Resource Definitions panel, click New > Type, where Type is one of the available shared resource types shown next.

If you don’t know what shared resource definitions are required by the services you plan to deploy, you can import the definitions when you upload a service assembly. See Importing Shared Resource Definitions on page 220.


Managing Shared Resource Definitions | 117

4. In the right panel, complete the details as explained in the reference section:

— HTTP Server See HTTP Server Shared Resource Definition Reference on page 120

— Identity See Identity Shared Resource Definition Reference on page 123

— JDBC See JDBC Shared Resource Definition Reference on page 123

— JMS See JMS Shared Resource Definition Reference on page 127

— JNDI See JNDI Shared Resource Definition Reference on page 130

— Rendezvous See Rendezvous Shared Resource Definition Reference on page 134

— SSL Server SSL Server Shared Resource Definition on page 137

5. Test the connection to a JDBC or JMS resource by clicking the Test Connection button.

6. Click Save.

Editing a Shared Resource DefinitionOnce a shared resource definition has been created you cannot edit its name, but other fields are editable. To edit a shared resource definition:



3. Click an existing shared resource definition.

4. In the right panel, click Edit and then modify properties as described in Setting a Shared Resource Definition Property on page 117.

5. Click Save.

6. Uninstall and reinstall the shared resources on all nodes that use this shared resource definition. See Installing and Uninstalling Shared Resources on page 210 for details.

Changes to a shared resource definition are picked up by the shared resources that use the definition after you restart the node on which they are installed.

Setting a Shared Resource Definition PropertyThere are three ways to set the value of a shared resource property:

• Inline on page 118

• Substitution Variables on page 118



• Shared Resources on page 119

Inline

To set the value of a shared resource property, type the value in the property field.

Substitution Variables

Certain properties of an HTTP server shared resource definition (see HTTP Server Shared Resource Definition Reference on page 120) can be bound to a substitution variable. Some reasons bind properties to variables are described in Customizing HTTP Shared Resource Definitions on page 11.

The value of a substitution variable is validated when it is applied. For example, the port number must be between 1 and 65536. If invalid, an error citing the limitations on the value of the property displays.

Binding a Shared Resource Property to a Substitution Variable

Shared resource properties can be bound to substitution variables (see Working with Substitution Variables on page 169). To bind a shared resource configuration property to a substitution variable:

1. Click the icon to the right of the field. A dialog box containing substitution variables of the appropriate type displays.

a. Click the row of a substitution variable to apply to the target property and close the dialog box. The icon displays to the left of the field. The value %%subvarname%%:subvarvalue displays in the field.

Clearing a Binding Between a Shared Resource Property and a Substitution Variable

To clear a binding between a shared resource property and a substitution variable, click the field and type a new value. The icon to the left of the field disappears.



Shared Resources

Binding a Shared Resource Property to a Shared Resource

Sometimes the value of a shared resource property definition is another shared resource definition. For example, the SSL Configuration property of an HTTP server is an SSL Server shared resource definition. Such properties are configured in two ways:

• Clicking a link named Choose XXX Configuration, where XXX is the type of shared resource definition. Clicking the link displays a dialog containing a list of matching definitions. The link is displayed when the number of items in the list is expected to be too long for a drop-down list.

• Selecting from a drop-down list of definitions.

To configure such properties:

1. Edit the resource definition as described in Editing a Shared Resource Definition on page 117.

2. Click the link, click the desired definition, and click OK or select the definition from the drop-down list.

Deleting a Shared Resource DefinitionBefore you can delete a shared resource definition, you must remove any references to it from other shared resource definitions or shared resources. For example, if an HTTP server shared resource definition is referencing an SSL server shared resource definition, you must first remove the reference to the SSL server definition from the HTTP server definition before you can delete the SSL server definition. In the case of shared resources, uninstall all shared resources that use the definition. See Working with Shared Resources on page 209 for details.

The following sections summarize the various scenarios in which a shared resource definition can be deleted:

• Associate with an environment.

• Associate with an environment, associate with a node, disassociate from the node.

• Associate with an environment, associate with a node, install the shared resource on a running node, uninstall the shared resource from the node (which also disassociates it from the node).

• Import a shared resource definition from a service assembly, install the shared resource on a running node, use the service assembly, delete the service assembly, uninstall the shared resource from the node.



• Reference a shared resource definition from another shared resource definition. Dereference the shared resource definition from the first definition or delete the first definition.

Deleting a Shared Resource Definition

To delete a shared resource definition:



3. Click an existing shared resource definition.

4. Click Delete.

Resource Definition Reference

HTTP Server Shared Resource Definition Reference

An HTTP server shared resource describes an HTTP connection. HTTP server shared resources are used by services.

Table 23 HTTP Server Shared Resource Reference

Field Description

Name The name of the resource. Names are case sensitive.

The name must be unique across all shared resource definitions in all environments administered by the same ActiveMatrix Administrator cluster.

Default: HTTP Server Shared Resource Definition.

Shared Resource Type

HTTP Server.

Description Short description of the resource.



Host Specifies the name of the host that accepts the incoming requests. For machines that have only one network card, the default value localhost specifies the current machine. For machines that have more than one network card, this field specifies the host name of the card that will be used to accept incoming HTTP requests.

If there is more than one network card on the machine, and you specify localhost in this field, all network cards on the machine will listen for incoming HTTP requests on the specified port. Only one HTTP server can be started on each port. Therefore make certain that all HTTP connection resources that use the same host name specify different port numbers.

Default: localhost. Note that localhost signifies the host on which the ActiveMatrix node is running, not the ActiveMatrix Administrator server.

This property can be bound to a substitution variable.

Port Port number on which to listen for incoming HTTP requests.

Default: 80.


Enable DNS Lookups

Enables a Domain Name System (DNS) lookup for HTTP clients so that the IP address is resolved to a DNS name. This can adversely affect throughput, so enable this field only when required.

Maximum Post Size

Maximum size allowed for HTTP POST data.

Redirect Port If the HTTP connection supports non-SSL requests, and a request received requires SSL transport, the request is redirected to the port you specify here.

Default: 8081.


Connection Timeout

The number of milliseconds the connector waits, after accepting a connection, for the specific URI the request is sending to be presented.

Default: 0. Unit is milliseconds.

Table 23 HTTP Server Shared Resource Reference (Cont’d)

Field Description



Minimum Threads The minimum number of threads available for incoming HTTP requests. The HTTP server creates the number of threads specified by this parameter when it starts up.

Default: 10.


Maximum Threads The maximum number of threads available for incoming HTTP requests. The HTTP server will not create more than the number of threads specified by this parameter.

When a client sends a request that cannot be processed because no threads are available, the ActiveMatrix node returns a ConnectionRefused exception to the client.

Default: 75.


Disable Upload Timeout?

If not checked, an additional connection timeout period is used while a SOAP message is being executed. If checked, the additional timeout period is not used.

Default: false (not checked).

Use SSL? Check to require SSL encrypted communication with the connection.

Default: No.

SSL Configuration Name

The SSL server shared resource to use for the connection.

This property can be bound to a substitution variable. The field label is a link to the resource.

Table 23 HTTP Server Shared Resource Reference (Cont’d)

Field Description



Identity Shared Resource Definition Reference

An identity shared resource contains identity information that is used to authorize a connection. Identity resources are used by SSL servers.

JDBC Shared Resource Definition Reference

A JDBC shared resource describes a JDBC connection. JDBC connections are used by components and logging configurations

Table 24 Identity Shared Resource Reference

Field Description



Default: Identity.


IDENTITY.


Identity Type When you choose an identity type, appropriate fields display for you to enter the values required:

Public Key Identity A keystore provides the identity. See Public Key Identity.

Public Key Identity

Keystore URL The URL to the keystore.

Select from the drop-down list of keystore. The drop-down list displays keystores already created in the Enterprise Assets > Keystores screen.

Type the keystore URL or Browse to one by clicking the Browse button.

Entry Alias A private key in the keystore that identifies a user.

Alias Password The password used to access the private key.



You can configure a JDBC shared resource so that it communicates with the database server over an SSL connection. See Enabling SSL Connections on page 126..

Table 25 JDBC Shared Resource Reference

Field Description



Default: JDBC Shared Resource Definition.


JDBC.


Connection Type When you choose a connection type, appropriate fields appear for you to enter the values required:

• JDBC See JDBC Connection Type, page 124

• JNDI See JNDI Connection Type, page 125

JDBC Connection Type

JDBC Driver Required. The name of the JDBC driver class. You can select from a drop-down list of supported drivers or type the name of a custom driver. For a list of drivers in the drop-down list, see Table 26 on page 125.

When you select a driver, the Database URL field is populated with a template for the URL of the driver.

Default: org.hsqldb.jdbcDriver.

Using Custom Drivers

To use a custom JDBC driver, follow the procedure described in Packaging and Installing Native Database Drivers in your installation manual.



Database URL Required. The URL to use to connect to the database. A template of the URL is supplied for the driver you select in the JDBC Driver field or you can type the name of a custom URL. For a list of templates, see Table 26 on page 125.

You must supply the portions of the URL shown between angle brackets and remove the angle brackets.

Default: jdbc:hsqldb:hsql://localhost:<port#>/<db_instancename>.

Username User name to use when connecting to the database.

Default: Your username.

Password Password to use when connecting to the database.

Maximum Connections

The maximum number of database connections to allocate.

Default: 10. The minimum value that can be specified is 0.

Login Timeout Time (in seconds) to wait for a successful database connection. Only JDBC drivers that support connection timeouts can use this configuration field. If the JDBC driver does not support connection timeouts, the value of this field is ignored. Most JDBC drivers support connection timeouts.

Default: 0.

JNDI Connection Type

JNDI Configuration Name

The JNDI Configuration shared resource definition that specifies the JNDI connection information.

Datasource Name The JNDI name of the data source that is registered in the JNDI provider.

Table 26 Database Drivers and URL Templates

Database Driver URL Template

HSQLDB org.hsqldb.jdbcDriver jdbc:hsqldb:hsql://localhost:<port#>/<db_instancename>


DataDirect driver

tibcosoftwareinc.jdbc.sqlserver.SQLServerDriver

jdbc:tibcosoftwareinc:sqlserver://<hostname>:<port#>;databaseName=<databaseName>

Table 25 JDBC Shared Resource Reference (Cont’d)

Field Description



Enabling SSL Connections

SSL connections are supported only with Oracle databases. To enable SSL connections on ActiveMatrix Administrator server and ActiveMatrix nodes:

1. Shut down the ActiveMatrix Administrator server and ActiveMatrix nodes.

2. If you are using the Oracle thin driver, install the Oracle driver as described in the Packaging and Installing Native Database Drivers section in the Post-Installation Procedures in the installation manual for your product on the ActiveMatrix Administrator server machine and the machines on which you run ActiveMatrix nodes.

3. Import the issuer certificate of the Oracle server’s certificate into the ActiveMatrix Administrator server and the ActiveMatrix node trusted certificate stores.


native driver

com.microsoft.sqlserver.jdbc.SQLServerDriver

jdbc:sqlserver://<host>:<port#>;databaseName=<databaseName>

Oracle

DataDirect driver

SSL

tibcosoftwareinc.jdbc.oracle.OracleDriver

jdbc:tibcosoftwareinc:oracle://<hostname>:<port#>;SID=<db_instancename>

jdbc:tibcosoftwareinc:oracle://host:port;SID=SID;EncryptionMethod=SSL

Oracle

native driver1

SSL

oracle.jdbc.driver.OracleDriver

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=10.107.171.106)(PORT=1521)))(CONNECT_DATA=(SERVICE_NAME=orcl)(SERVER=dedicated)))

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=10.107.171.106)(PORT=2484)))(CONNECT_DATA=(SERVICE_NAME=orcl)(SERVER=dedicated)))

Sybase1 jdbc.7.driver=com.sybase.jdbc3.jdbc.SybDriver

jdbc.7.url_template=jdbc:sybase:Tds:<host>:<port#>/<databaseName>

1. Oracle and Sybase native drivers are not distributed with ActiveMatrix products and the driver classand URL template are not available in the drop-down lists for those fields. To use the native drivers,type the driver class and URL into the fields and follow the Custom Drivers instructions in JDBCDriver on page 124.

Table 26 Database Drivers and URL Templates (Cont’d)

Database Driver URL Template



4. Perform the procedures described in Managing the Trusted Keystore on page 342 and Managing the Trusted Keystore on page 344.

5. In the ActiveMatrix Administrator UI, create a JDBC shared resource that uses the SSL URI .

JMS Shared Resource Definition Reference

A JMS shared resource describes a JMS connection. JMS connections are used by services and references.

SSL Configuration

You can configure a JMS shared resource so that it communicates with the JMS server over an SSL connection. SSL communication is supported only when the connection type of the JMS shared resource is JNDI lookup. Direct connection to the JMS server is not supported.

To create an SSL connection to the JNDI server configure the JNDI shared resource for SSL.

A JMS shared resource can be enabled for both server and client verification.

Server Verification

The JMS client can verify the Enterprise Message Service server before creating a secure connection. To configure the Enterprise Message Service server for server verification, perform the steps in Configure Server Credentials on page 130.



Client Verification

The Enterprise Message Service server can verify the JMS client before creating a secure connection. To configure the Enterprise Message Service server for client verification, perform the steps in Configure Client Credentials on page 130 and set the Client Certificate Password field.

Table 27 JMS Settings

Field Description


The name of a shared resource definition must be unique across all shared resource definitions in all environments administered by the same ActiveMatrix Administrator cluster.

Default: JMS Shared Resource Definition.


JMS.


Username User name used to create a connection from the connection factory.

If the JMS provider does not require access control, this field can be empty.

Not all JMS servers require user names and passwords. Refer to your JMS provider documentation and consult your system administrator to determine if your JMS server requires a user name and password.

Password Password used to create a connection from the connection factory.

If the JMS provider does not require access control, this field can be empty.

Connection Type

When you choose a connection type, appropriate fields display for you to enter the values required:

Direct See the Direct Connection Type section.

JNDI See the JNDI Connection Type section.

Direct Connection Type

Provider URL The server URL used to create the connection factory. This field is required only for connections to a TIBCO Enterprise Message Service server. See documentation for TibjmsConnectionFactory in TIBCO Enterprise Message Service product documentation (Javadoc) for more information.

Default: tcp://localhost:7222.



Enabling SSL for the JMS Server

To enable SSL for the JMS server you configure server and client credentials. The supported file formats for the credentials are:

• Single URI Identity

— PKCS12

• Public Private Identity

— PEM, P7 for public identity

— P8 for private key

• Trusted CAs

— PEM

Connection Factory

The factory for creating connections to the JMS server. Set to com.tibco.tibjms.TibjmsConnectionFactory for Enterprise Message Service or progress.message.jclient.ConnectionFactory for SonicMQ.

Default: com.tibco.tibjms.TibjmsConnectionFactory.

JNDI Connection Type

JNDI Configuration

A JNDI shared resource definition that specifies the JNDI connection information.

Connection Factory

The ConnectionFactory object stored in JNDI. This object is used to create a topic or queue connection with a JMS application.

See your JNDI provider documentation for more information about creating and storing ConnectionFactory objects.

Default: GenericConnectionFactory.

To create an SSL connection to the JMS server, specify SSLGenericConnectionFactory or any other connection factory with SSL configuration provisioned on the JNDI server.

Client Certificate Password

The password of the client certificate used to verify the identity of SSL clients.

Table 27 JMS Settings (Cont’d)

Field Description



To enable SSL for the JMS server do the following tasks:

Task A Configure Server Credentials

To configure server credentials:

1. Create an SSL connection factory in the TIBCO Enterprise Message Service server by adding the following properties to ENV_HOME/ems/version/bin/factories.conf:

[SSLGenericConnectionFactory]type = genericurl = ssl://7243ssl_vendor = entrust61ssl_verify_host = enabled

ssl_trusted = certs/server_root.cert.pem

ssl_identity = certs/client_identity.p12

ssl_verify_hostname = enabled

ssl_expected_hostname = server

2. Restart the Enterprise Message Service server with the command ENV_HOME/ems/version/bin/tibemsd –config tibemsdssl.conf.

Task B Configure Client Credentials

To configure client credentials:

1. Edit ENV_HOME/ems/version/bin/tibemsdssl.conf and set the properties:

ssl_require_client_cert = disabled

ssl_server_trusted = certs/client_root.cert.pem


JNDI Shared Resource Definition Reference

The JNDI shared resource provides a way to specify JNDI connection information that can be shared by other resources. This resource can be referenced in any resource that permits JNDI connections. JDBC and JMS shared resources can use JNDI connections.



You can configure a JNDI shared resource so that it communicates with the JNDI server over an SSL connection. A JNDI connection can be only be enabled to perform server verification. You enable SSL by configuring security application properties as described in SSL Configuration Properties on page 132.

Table 28 JNDI Shared Resource Reference

Field Description



Default: JNDI Shared Resource Definition.


JNDI.


Context Factory The name of the JNDI context factory. You can select from a drop-down list of supported initial context factory classes for accessing a JNDI service provider. (javax.naming.Context.INITIAL_CONTEXT_FACTORY) or type the name of a custom context factory class.

Default: com.tibco.tibjms.naming.TibJmsInitialContextFactory.

To use a custom context factory class, you must copy the custom JNDI driver JARs to two locations:

• AMX_ADMIN_HOME/2.3/lib/ext/ on the machine hosting the ActiveMatrix Administrator server. This allows you to test the connection from the ActiveMatrix Administrator server.

• AMX_HOME/2.3/server/lib/ext/ on the machines hosting nodes that will access the driver. This allows services running on those nodes to access the driver.

Context URL The URL to the JNDI service provider (javax.naming.Context.PROVIDER_URL). An example URL is provided when one of the supported JNDI context factory classes is selected.

See your JNDI provider documentation for the syntax of the URL.

To configure SSL , specify tibjmsnaming://localhost:7243. See SSL Configuration Properties, page 132.



SSL Configuration Properties

In the Application Properties area, add the following properties and values prepending each property name with com.tibco.tibjms.naming.

Username User name for logging into the JNDI server (javax.naming.Context.SECURITY_PRINCIPAL). If the JNDI provider does not require access control, this field can be empty.

Password Password for logging into the JNDI server (javax.naming.Context.SECURITY_CREDENTIALS). If the JNDI provider does not require access control, this field can be empty.

Application Properties

You can add and define application properties as needed.

Name The name of the property. Names are case sensitive.

Default: Application_Property.

Type Data type of the property.

Value Value of the property.

Table 28 JNDI Shared Resource Reference (Cont’d)

Field Description

Table 29 JNDI SSL Application Properties

Property Value Notes

security_protocol ssl ssl is the only security protocol supported. Required.

ssl_vendor entrust61 entrust61 is the only supported vendor. Required.

ssl_enable_verify_host true Specifies whether the client should verify the server’s certificate. Required.



ssl_enable_verify_hostname true Set to true if the name on the server's certificate must be verified against the server's hostname. If the server's hostname is different than the name on the certificate, SSL connection will fail. The name on the certificate can be verified against another name by specifying the ssl_expected_hostname property.

ssl_trusted_certs /certs/server_root.cer.pem Contains the CAs the client trusts for server verification. Required only if ssl_enable_verify_host is set to true.

ssl_expected_hostname server Hostname given at the time of creating the certificate. Required only if ssl_enable_verify_hostname is set to true. Required.

ssl_trace true May be specified for SSL tracing.

ssl_debug_trace true May be specified for SSL debug tracing.

Table 29 JNDI SSL Application Properties (Cont’d)




Rendezvous Shared Resource Definition Reference

A Rendezvous shared resource describes a TIBCO Rendezvous transport. Rendezvous resources are used by services and references. See the TIBCO Rendezvous documentation for more information about specifying these fields.

Rendezvous character encoding represents the encoding of Rendezvous messages when they are sent across the network.The default Rendezvous character encoding is UTF-8. To change Rendezvous character encoding to another encoding such as ISO-8859-1, add the following line to AMX_HOME/data/envName/nodeName/bin/envName_nodeName.tra file for all nodes on which Rendezvous shared resources are installed:java.property.com.tibco.matrix.rv.character.encoding=ISO8859-1

Table 30 Rendezvous Shared Resource Reference (Sheet 1 of 3)

Field Description



Default: Rendezvous Shared Resource Definition.


Rendezvous.


Daemon The host name followed by the socket number of the machine on which the Rendezvous daemon is running.

Network The network to be used by the Rendezvous daemon. Contains the host name, IP address, network name, or interface name.

Service Service name in one of the following formats: service_name or port_number.

Connection Type When you choose a delivery method, appropriate fields display for you to enter the values required:

Certified See Certified, page 135.

Distributed Queue See Distributed Queue, page 135.

Reliable No additional settings are required when you choose Reliable.

See TIBCO Rendezvous documentation for details.



Certified

CM Name The name of the delivery-tracking session. This name is in the same format as Rendezvous subject names.

Ledger File The name and location of the persistent ledger file that tracks certified messages. If not specified, the certified message ledger is kept in memory only.

Sync Ledger File? Specifies whether to keep the ledger file synchronous with the current messages.

Default: No.

Relay Agent Name of the relay agent to use. Relay agents are useful when clients are disconnected from the network from time to time. The relay agents store inbound certified messages and labeled messages (and other messages related to certified delivery features) on behalf of their disconnected client programs. When a client is connected, it receives inbound messages immediately.

Require Old Messages?

Specifies whether to require the retention of messages for which delivery has not been confirmed. These messages will be resent.

Default: No.

Message Timeout The time limit (in seconds) for certified message delivery.

Default: 0.

Distributed Queue

CMQ Name The name of the distributed queue. This name is in the same format as Rendezvous subject names.

Worker Weight The weight of the worker (this pertains to the worker processing queue requests, not to BusinessWorks process engines). Relative worker weights assist the scheduler in assigning tasks. When the scheduler receives a task, it assigns the task to the available worker with the greatest worker weight.

Default: 1


Field Description



Worker Tasks Sets the task capacity for the worker (this pertains to the worker processing queue requests). Task capacity is the maximum number of tasks that a worker can accept. When the number of accepted tasks reaches this maximum, the worker cannot accept additional tasks until it completes one or more of them.

Default: 10

Worker Complete Time

The amount of time the scheduler waits for a worker process to complete. If the worker process does not complete in the specified period, the scheduler reassigns the message to another worker.

Default: 0.

Scheduler Weight Weight represents the ability of this member to fulfill the role of scheduler, relative to other members with the same name. Cooperating distributed queue transports use relative scheduler weight values to elect one transport as the scheduler; members with higher scheduler weight take precedence. Acceptable values range from 1 to 65535.

Default: 1.

Scheduler Heartbeat

The scheduler sends heartbeat messages at this interval (in seconds). All members with the same name must specify the same value for this parameter. The value must be positive.

Default: 0.1.

Scheduler Activation

When the heartbeat signal from the scheduler has been silent for this interval (in seconds), the member with the greatest scheduler weight takes its place as the new scheduler. All members with the same name must specify the same value for this parameter. The value must be positive.

Default: 0.3.


Field Description



SSL Server Shared Resource Definition

An SSL server shared resource describes an SSL server. SSL server shared resources are used by HTTPS server shared resources.

Table 31 SSL Server Shared Resource Reference

Field Description



Default: SSL Server Shared Resource Definition.


SSL Server.


Identity An identity shared resource of type public key identity.

Cipher Strength Specifies the number of bits in the key used to encrypt data. The greater the number of bits in the key (cipher strength), the more possible key combinations and the longer it would take to break the encryption.

• No Restriction

• No Export Grade

• At Least 128

• More Than 128

• At Least 256

Client Authentication Required?

When checked clients are required to present their digital certificate before connecting to the HTTP server.

When checked, the Trusted Certificate Authorities fields will be displayed.

Trusted Certificate Authorities

File Type Only the Java keystore type is supported.

Certificate Store URL

The location of the certificate store.

The location must be the URL of an object accessible over the network.

Password The password for the certificate store.




Managing Users, Groups, and Permissions | 139

Managing Users, Groups, and Permissions

The ActiveMatrix Administrator supports centralized authentication and authorization. An ActiveMatrix user is a person that has an authentication credential. An ActiveMatrix group is a collection of users. Authorization (or permission) to access ActiveMatrix objects can be assigned to users and groups. Using ActiveMatrix Administrator, a user with the appropriate permissions can define which users and groups should have access to ActiveMatrix Administrator features and ActiveMatrix runtime objects.

Authorization for all ActiveMatrix runtime objects is provided by the ActiveMatrix Administrator server. Hence, a server must be running and connectivity must be available from each ActiveMatrix node for any kind of management action on the nodes.

To manage users, groups, and permissions:

1. Log in to ActiveMatrix Administrator as a superuser.


3. Click the Users & Groups link.

4. Click a button based on the type of configuration you want to perform:

— Users on page 140

— Groups on page 145

— Permissions on page 147

Users and Groups OverviewUsers and groups can be searched for, viewed, and optionally edited.

The asterisk wildcard is supported in all search areas in Users and Groups.

The availability of editing capability depends on the type of authentication realm you have chosen:

• Local XML File Realm Read-only access provided within ActiveMatrix Administrator. You can manually add users and groups to the realm. See Adding a User to a Local XML File Realm on page 31 and Group Hierarchy on page 145.

• Database Realm Read-write access provided within ActiveMatrix Administrator. Managing Users in the Database Authentication Realm on page 141.



• TIBCO Administrator Realm Read-only access provided within ActiveMatrix Administrator. You must use TIBCO Administrator to edit users and groups (roles).

• LDAP Realm Read-only access provided within ActiveMatrix Administrator. Edit functionality is limited to that provided by your LDAP vendor.

UsersA user has the following attributes:

• User ID Required. A string identifier that is unique within the realm. I18n characters are allowed.

• Password Required. A string containing at least one character.

Superusers

ActiveMatrix Administrator defines a category of users—called superusers—that have implicit Owner permission (see Permissions on page 147) for all objects. Superusers can manage objects that have no owners. For example:

• An owner of an object is on vacation, leaves the company, or is otherwise unreachable.

• An owner of an object removes himself from the Owner permissions and saves the object. From then on, the object has no explicit owner.

• A group had been granted Owner permission for an object. The group initially had 2 users. Over a period of time, the two users left the company, and each one got removed from that group. The object's permissions were unchanged during this time, but effectively it has no owner.

All superusers are users in the ActiveMatrix Administrator authentication realm. For example, for the LDAP realm, the users must be present in the LDAP server. If a superuser is deleted from LDAP server, the user loses superuser privilege only in the next login session. A current login session still treats the user as a superuser.

Caution must be exercised when assigning superuser privileges, because of the potential for a rogue superuser to vandalize the system. For this reason, ActiveMatrix Administrator does not allow adding groups as superusers.



Resetting the Superuser Password

When you create an ActiveMatrix Administrator cluster you specify the superuser username and password. If you forget the superuser password, you can reset it as follows:

1. Run AMX_ADMIN_HOME/2.3/bin/createadminserver and add a second ActiveMatrix Administrator server to the ActiveMatrix Administrator cluster.

2. When the wizard prompts you for a superuser username and password enter a new username and password. The new user you specify is added to the user database.

3. Start an ActiveMatrix Administrator server.

4. Start the ActiveMatrix Administrator UI.

5. Log in using the new username and password.

6. Follow the procedure in Changing a User Password on page 143 to reset the password for the original user for whom you forgot the password.

Managing Users in the Database Authentication Realm

In the database authentication realm you can search for users, create and delete users, add and remove superusers, reset user passwords, and add and remove users from groups.

Searching for Users

To search for users:

1. Type a wildcard expression in the text box to the left of the Search button.

2. Click the Search button.

3. A paginated list of users matching the expression is returned. The maximum number of users is limited to 500.

Creating a User

To create a user:



3. Click the Users button.

4. Click New.

5. In the User ID field, type the user identifier.



6. In the Password field, type a password with at least one character.

7. In the Confirm Password field, type the same password.

8. Click Save.

Deleting a User

To delete a user:




4. Select the user in the Users list.

5. Click Delete.

Adding Superusers

To add superusers:




4. Click the Superusers button. The Superusers dialog displays.

a. Click the Add Users button.

b. Optionally type a wildcard expression to narrow the list of users.

c. Click the Search button.

d. Drag the users from the left to the right panel.

e. Click Save.

f. Dismiss the dialog.

Removing Superusers

To remove superusers:






4. Click the Superusers button. The Superusers dialog displays.

a. Click Remove in the row of the user to remove.

b. Dismiss the dialog.

Changing a User Password

There are two ways to change a user password:

• Click the Profile link in the top right corner of the header. The Change Password dialog is displayed and requires you to enter the old and new passwords and confirm the new password.

• Select the Configure Enterprise Assets perspective:

a. Click the Users & Groups link.

b. Click the Users button.

c. Select the user in the Users list.

d. Click the Reset Password button. The Reset Password dialog is displayed and requires you to enter the new password and confirm the password.

A superuser can change the password of any user.

Adding a User to Groups

Before you can add a user to a group you must add a root group or subgroup following the procedures described in Managing Groups in the Database Authentication Realm on page 146.


2. Click the Users & Groups link. There are two ways to add a user to groups: through the Users area and through the Groups area.

Users area To add a user to groups through the Users area:

1. Click the Users link.

2. Select a user in the Users list.

3. Click the Add Groups button in the Groups area.

4. Type a wildcard expression in the text box.

5. Click the Search button. The Add Groups dialog displays.

a. Select groups from the Add Group list and drag them to the right panel.

6. Click Save. The groups are added to the Groups list in the right panel.



Groups area To add a user to groups through the Groups area:

1. Click the Groups link.

2. Select a group in the Groups list.

3. Click the Add Users button in the Users area.

4. Type a wildcard expression in the text box.

5. Click the Search button. The Add Users dialog displays.

a. Select users from the Add User list and drag them to the right panel.

6. Click Save. The users are added to the Users list in the right panel.

Removing a User from a Group



3. Click the Users link.



4. Select a user in the Users list.

5. In the Groups list on the right panel, click the Remove link in the row containing the group from which you want to remove the user. Only a direct member (see Member Type on page 147) can be removed.

GroupsA group is a collection of users. It has the following attributes:

• Name Required. A string identifier that is unique among all groups. I18n characters are allowed.

• Description Optional. A string that describes the group.

• Members A list of users that belong to that group. A user may belong to zero or more groups.

Group Hierarchy

Groups can exist within a hierarchy. The existence and nature of a group hierarchy depends on the type of the authentication realm. This section describes the group hierarchy available in each type of authentication realm.

Database

The Database authentication realm supports a group hierarchy. In the Database realm, groups do not have a common root element; ActiveMatrix Administrator allows multiple groups at the root level.

A group can contain zero or more subgroups. A group is either at the root level, or it has one and only one parent group. The parent-subgroup relationship always implies membership inclusion from subgroups to parent groups. For example, if the Company Staff group contains the City Staff group, the members of the City Staff group are also members of the Company Staff group.

LDAP

The LDAP authentication realm supports a group hierarchy as it exists in your LDAP server. A change in the structure in LDAP is reflected in ActiveMatrix Administrator, but only after a cache-expiry interval.

Local XML File

The local XML file authentication realm supports a default group named administrator and you can add groups. For information on the file syntax, see Adding a User to a Local XML File Realm on page 31.



TIBCO Administrator

The TIBCO Administrator authentication realm supports a group hierarchy. In TIBCO Administrator, a role (functionally identical to a group) can have multiple parents.

Managing Groups in the Database Authentication Realm

In the database realm you can create root and subgroups and delete groups.

Creating a Root Group

To create a root group:



3. Click the Groups button.

4. Select New Root Group.

5. In the Name field, type a name for the group.

6. In the Description field, type a description.

7. Click Save.

Creating a Subgroup

To create a subgroup:



3. Click the Groups button.

4. Click a root group to serve as the parent group.

5. Click New Subgroup.

6. In the Name field, type a name for the group.

7. In the Description field, type a description.

8. Click Save. The group is added to the Groups list as a subgroup of the parent group.

Deleting a Group or Groups

Within ActiveMatrix Administrator you can delete groups only within the Database realm.



To delete a group:

1. Select the group or groups in the Groups list.

2. Click Delete. If the group is a parent group, the subgroups are promoted to parent-level status. The group or groups are removed from the Groups list.

Groups List Reference

PermissionsAccess to ActiveMatrix Administrator features is enabled by permissions. The following sections describe the interaction of permissions with the following ActiveMatrix Administrator features:

• User Interface Functions on page 147

• Objects on page 149

User Interface Functions

Permissions affect user interface functions in the following ways:

• ActiveMatrix Administrator displays UI components for which you have View permission. Figure 16 on page 148 shows the UI components for which permissions can be granted.

• ActiveMatrix Administrator displays ActiveMatrix objects for which you have View permission.

Table 32 Groups List Reference

Column Description

Name Required. The name of the group.

Description Required. The group description.

Member Type The type of membership the user has in the group. One of:

• Direct The user is a direct member of this group.

• Indirect The user is an indirect member of this group. This occurs when the group is a parent group and the user is a member of a subgroup of the parent group.

Remove Link to remove the user from group.



• You are only allowed to perform actions for which you are authorized. ActiveMatrix Administrator disables or hides UI components, such as buttons and menu items, if you do not have permission for the corresponding actions.

Figure 16 Components



Objects

Objects such as nodes, shared resource definitions, and so on have permissions that grant access of a particular type to a single user or a group of users. ActiveMatrix Administrator allows you to set permissions on objects displayed in the following screens:

• Configure Enterprise Assets

— Environment Definition > Environments

— Shared Resource Definitions > Shared Resource Definitions

— Servers > UDDI Servers

— Keystores > Keystores

— Administrator Cluster > Plug-ins

• Configure an Environment > Nodes

• Deploy to an Environment > Service Assemblies

Permission Types

There are three types of permissions: view, edit, and owner. Each type provides different capabilities:

• View Allows you to browse objects in a list or view details for the objects.

• Edit Allows you to

— Perform all the actions allowed with View permission

— Edit the properties of an object.

— Add items to a parent object. See Adding Child Objects to a Parent Object on page 150.

— Perform runtime actions such as start, stop, install, uninstall, activate, deactivate, deploy, and undeploy on the object

• Owner Allows you to

— Perform all the actions allowed with Edit permission

— View and modify the object’s permissions

— Delete the object



Adding Child Objects to a Parent Object

You are allowed to add child objects to parent objects for which you have Edit permission. For example, if a you have Edit permission for an environment, then you can add a node to that environment, service assemblies, shared resource definitions, or any other type of object that belongs to an environment. Figure 11 on page 83 illustrates the parent-child relationships supported by ActiveMatrix Administrator.

When you add an object, its parent’s permissions are copied into that new object. Additionally, the you are granted Owner permission for that object, provided that you do not already gain ownership by virtue of the parent object’s permissions.

Since environments have no parent, enterprise permissions cover them. Granting Edit permissions to the enterprise allows you to create environments.

Displaying Permissions

UI Components

To display permissions for the UI components in Figure 16 on page 148:



3. Click the Permissions button.

4. Click a UI component in the Permissions tree.

Objects

To display object permissions:

1. Navigate to one of the screens described in Objects on page 149 containing the objects to which you are adding the permission.

2. Click one or more objects. The Set Permission button displays.

3. Click the Set Permission button.

Setting Permissions

You can set permissions for single objects, as well as multiple objects. For a single object, both add and remove are accomplished from the same dialog. For multiple selections, add and remove are accomplished with two different dialogs.



Single Object

To add permissions to users or groups for one or more UI components or a single object:

1. Display permissions as described in Displaying Permissions on page 150.

a. To add permissions for a UI component, click the Edit button over the permissions table. To add permissions for a runtime object, click the Set Permission button over the object table. The Add Users and Groups to Permissions dialog displays.

2.

a. To add a permission for a user, click the Users button. To add a permission for a group, click the Groups button.

b. To narrow the list of users or groups, type a wildcard expression in the text box and click Search.

c. Select one or more users or groups in the list and drag to a permission type box in the right column.

d. Click Save.



Multiple Objects

To add permissions to users or groups for multiple objects:


2. To add permissions for runtime objects, select Set Permission > Add Permission over the object table. The Add Users and Groups to Permissions dialog displays.

a. To add a permission for a user, click the Users button. To add a permission for a group, click the Groups button.

b. To narrow the list of users or groups, type a wildcard expression in the text box and click Search.

c. Select one or more users or groups in the list and drag to a permission type box in the right column.

d. To overwrite all existing permissions with your new selections, click the Overwrite existing permissions? checkbox.

e. Click Save.



Removing Permissions

Single Object

To remove permissions from users or groups from a UI component or a single object:


2. Click the icon next to the users or groups for which you want to remove a permission.

3. Click Save.

Multiple Objects

To remove permissions from users or groups for multiple objects:




2. To remove permissions for runtime objects, select Set Permission > Remove Permission over the object table. The Remove Permissions dialog displays.

a. Click Select All to select all users and groups. Click Deselect All to turn off all selections.

b. Use the option buttons at the bottom of the dialog to select the type of permission to remove for the selected users:

— Remove from all permissions Removes all permissions for the selected users or groups.

— Remove from View permissions Removes only View permissions for the selected users or groups.

— Remove from Edit permissions Removes only Edit permissions for the



selected users or groups.

— Remove from Owner permissions Removes only Owner permissions for the selected users or groups.

c. Click Save.



Managing UDDI Servers

UDDI is a platform-independent, XML-based framework for describing services, discovering businesses, and integrating business services. UDDI servers enable service providers to publish service listings and consumers to discover service providers.

In the Monitor & Manage perspective, you can publish ActiveMatrix services (see UDDI Publishing on page 275) to the UDDI servers registered as an enterprise asset. Before a service can be published, the UDDI server must also be enabled in the environment (see Enabling UDDI Servers in an Environment on page 186).

TIBCO ActiveMatrix supports secure access to UDDI servers. For information on how to enable secure connections to UDDI servers, see Enabling Secure Connections to UDDI Servers on page 355.

This section describes how to manage UDDI servers. To perform all tasks described in this section:


2. Click the Servers link.

Adding a UDDI Server

To add a UDDI server:

1. Click the Add button.

2. Specify the server details according to the descriptions in Table 33 on page 157.

3. Click Save.

Editing a UDDI Server

To edit a UDDI server:

1. Select the UDDI server in the UDDI Servers list.

2. Click the Edit button in the server details panel and edit the server details according to the descriptions in Table 33 on page 157

If you are using TIBCO ActiveMatrix Registry, the format of the URLs are described in the Installation Summary section (2.3.2) of TIBCO ActiveMatrix Registry Installation Guide and the registry startup scripts in the Command-line Scripts section (2.4).


Managing UDDI Servers | 157

3. Click Save.

Removing a UDDI Server

To remove a UDDI server:

1. Select the UDDI server in the UDDI Servers list.

2. Click the Remove button.

UDDI Server Reference

Table 33 UDDI Server Reference

Field Description

Name The name of the UDDI server.

Inquiry URL The URL to use when performing inquiries on the UDDI server.

Publish URL The URL to use when publishing to the UDDI server.

Username Name of the user that has publish access to the UDDI server.

Password Password for the specified user.

Authentication Model

The mechanism to use to authenticate with the UDDI server:

• Basic Authentication Use basic authentication to authenticate with the UDDI server. The provided username and password are used as the authentication credentials.

Use Proxy? Use an HTTP proxy to access the UDDI server. When checked, the Host, Port, Username, and Proxy fields are displayed.

Host Specifies the HTTP proxy host to be used for accessing the UDDI server.

Port Specifies the HTTP proxy port to be used for accessing the UDDI server.

Default: 8080.

Username Specifies the user name for the proxy host for HTTP proxy authentication, if one is required.

Password Specifies the password for the proxy host for HTTP proxy authentication, if one is required.



Managing Keystores

Keystores OverviewA keystore is a database of keys and certificates. Keystores contain keystore entries, which serve as identities for participants in SSL sessions. See Identity Shared Resource Definition Reference on page 123 and SSL Server Shared Resource Definition on page 137.

A keystore password is required to access or modify the keystore.

Keystore Entries

A keystore has two types of entries:

• Private key

This type of entry holds a cryptographic private key, which is optionally stored in a protected format to prevent unauthorized access. It is also accompanied by a certificate chain for the corresponding public key. Private keys and certificate chains are used by a given entity for self-authentication.

• Trusted certificate

This type of entry contains a single public key certificate. It is called a trusted certificate because the keystore 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.

Identifying Keystore Entries

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


Managing Keystores | 159

Protecting Keystore Entries

The private keys in a keystore are stored in encrypted form to make it difficult to disclose these keys inappropriately. The private keys are encrypted using the keystore password, which should be several words long. If the password is lost, those keys cannot be recovered.

In addition, each private key in the keystore can be protected using its own individual password, which may or may not be the same as the password that protects the keystore's overall integrity.

Keystore Types

Keystores are internal or external. An internal keystore is one that has been uploaded into the database of the ActiveMatrix Administrator server. Reloading a keystore file is supported on internal keystores. An external keystore is a reference to a keystore via a URL. The URL can point to a keystore managed by another ActiveMatrix Administrator server or a keystore in a file system.

To manage keystores:


2. Click the Keystores link.

From the keystores screen you can perform the following tasks:

• Creating an Internal Keystore on page 159

• Creating an External Keystore on page 160

• Deleting a Keystore on page 160

• Editing a Keystore Description on page 160

• Reloading an Internal Keystore on page 160

Creating an Internal KeystoreTo create an internal keystore:

1. Click New > Internal Keystore.

2. Type a name and description.

3. Click the Browse... button next to the Location field and navigate to the directory containing the keystore.

a. Select the keystore and click Open.

4. Type the password used to access the keystore in the Password field.

5. Click Save.



Creating an External KeystoreTo create an external keystore:

1. Click New > External Keystore.

2. Type a name and description.

3. In the Keystore URL field, type a URL (protocol http: or file:) that when accessed returns a keystore file. To URL format for a keystore in an ActiveMatrix Administrator server is: http://hostname:port/amxadministrator/keystorefetch?name=keystorename.

4. Type the password used to access the keystore in the Password field.

Deleting a KeystoreTo delete a keystore.

1. Select a keystore from the Keystores table.

2. Click Delete.

Editing a Keystore DescriptionTo edit a keystore’s description:

1. Select a keystore from the Keystores table.

2. Click the Edit button on the right.

3. Edit the description.

4. Click Save.

Reloading an Internal KeystoreTo reload an internal keystore:

1. In the Keystores table, select an internal keystore.

2. Click the Reload Keystore button on the right.

3. Click the Browse button to the right of the Keystore Location field and browse to the location of the keystore.

a. Select the keystore and click Open.

4. Click Save.


Managing Keystores | 161

Keystore Reference

Table 34 Keystore Reference

Field Description

Name The name that identifies the keystore.

Type The type of the keystore: External or Internal.

Description A short description of the keystore.

Password The password used to access the keystore.



Managing ActiveMatrix Administrator Clusters

To manage ActiveMatrix Administrator clusters:


2. Click the Administrator Cluster link. The Administrator Cluster screen displays. The heading of the screen is

Administrator Cluster (cluster: server)

where cluster is the cluster whose properties are accessed and server is the ActiveMatrix Administrator server to which you are connected.

3. Click a link based on the type of configuration you want to perform:

— Database Details on page 162

— Monitoring Configuration on page 163

— Log Services on page 163

— Plug-ins on page 163

— ActiveMatrix Administrator Servers on page 165

Database DetailsA database configuration describes the connection attributes of the database containing ActiveMatrix Administrator configuration and runtime data. The attributes are configured when you create the ActiveMatrix Administrator cluster and first server (see Creating the First ActiveMatrix Administrator Server on page 26). In the Database Details screen, the attributes are read-only. To view the database configuration, click the Database Details link.

To update the database configuration, follow the procedure in Updating the Database Configuration on page 50.

Table 35 Database Configuration Reference

Field Description

Driver The name of the JDBC driver class.

URL The URL used to connect to the database.

Username The database user name.



Managing ActiveMatrix Administrator Clusters | 163

Monitoring ConfigurationFor information on how to configure monitoring, see Enabling Monitoring on page 244.

Log ServicesFor information on how to configure log services, see Working with Log Services on page 302.

Plug-insTIBCO ActiveMatrix Administrator is extensible. This means that other TIBCO products can add functionality, such as new perspectives and new screens within the standard perspectives, to ActiveMatrix Administrator. The product-specific functionality is added to ActiveMatrix Administrator by uploading and deploying a plug-in containing new features. The plug-in is packaged as a WAR file.

You can deploy, start, stop, and undeploy plug-ins without restarting the ActiveMatrix Administrator server. A plug-in automatically gets deployed to all other servers. Also, the state of a plug-in is the same on all servers.

Both the Metrics Manager (see Metrics Manager Server on page 245) and the Log Service and Log Viewer (see Working with Log Services on page 302 and Using the Log Viewer on page 318) are implemented as plug-ins to ActiveMatrix Administrator.

This section describes how to manage the life cycle of a plug-in.

Deploying a Plug-in

Only one version of a plug-in can be deployed at any point in time.

There are two ways to deploy a plug-in: automatically and manually. To automatically deploy a plug-in, copy the WAR file containing the plug-in to the AMX_ADMIN_HOME/plugins directory.

Plug-ins are automatically started when they are deployed.

To manually deploy a plug-in:

1. Click the Plug-ins link.

2. Click Deploy.

3. Click Browse.... Navigate to a directory containing the plug-in and select the plug-in WAR file.



4. Click Open.

5. Click Upload.

6. Click OK.

Undeploying a Plug-in

Plug-ins are automatically stopped when they are undeployed. To undeploy a plug-in:


2. In the Plug-ins table, select the plug-in you want to undeploy.

3. Click Undeploy.

Starting and Stopping a Plug-in

To start or stop a plug-in:


2. In the Plug-ins table, select the plug-in.

3. Click Start or Stop.

You cannot undeploy a plug-in by deleting the WAR file from the AMX_ADMIN_HOME/plugins directory.



Plug-ins Reference

ActiveMatrix Administrator ServersThis section describes how to mange ActiveMatrix Administrator servers once you have already created the first server in a cluster (see Creating the First ActiveMatrix Administrator Server on page 26).

Creating an ActiveMatrix Administrator Server

The first ActiveMatrix Administrator server in a cluster is created with the ActiveMatrix Administrator server creation utility. The ActiveMatrix Administrator server creation action creates additional server replicas within the cluster. The primary reason to create ActiveMatrix Administrator servers is to achieve fault-tolerance. See TIBCO ActiveMatrix Administrator Servers and Clusters on page 5.

To create an ActiveMatrix Administrator server:

1. Click the Administrator Servers link.

2. Click the New button on top of the Administrator Servers table.

3. Provide values for the properties described in Table 38 on page 167.

4. When you are finished editing, click the Save button. The newly created ActiveMatrix Administrator server is automatically installed on the machine.

Table 36 Plug-ins Reference

Column Description

Display Name The name of the plug-in.

Version The version of the plug-in.

State The state of the plug-in.

Uploaded By The user that uploaded the plug-in.

Uploaded Date The date the plug-in was uploaded.



Deleting an ActiveMatrix Administrator Server

There are various reasons why you might want to delete an ActiveMatrix Administrator server. For example, you may want to use that machine on which the server is running for another purpose, and create a replacement server on another machine. When you delete a server, the database entries for the server are also deleted. All runtime configuration data, however, is preserved. A server can only be deleted when it has the following status: Installed/Stopped, Install Failed, Delete Failed, or Unknown. To delete an ActiveMatrix Administrator server:


2. Select a server in the Administrator Servers table.

3. Click the Delete button.

Starting and Stopping ActiveMatrix Administrator Servers

To start or stop ActiveMatrix Administrator servers:


2. Select one or more servers in the Administrator Servers table.

3. Select Start or Stop.

Editing Administrator Server Properties

To edit the properties of an ActiveMatrix Administrator server:


2. Select an server in the Administrator Server table.

3. Click the Edit button.

4. Edit the non-read-only properties described in Table 38 on page 167.

5. Click Save.

If you stop all the servers in a cluster, the runtime administered by that cluster becomes unusable.



Administrator Servers Reference

Administrator Server Reference

Table 37 Administrator Servers Reference

Column Description

Name The name of the ActiveMatrix Administrator server.

Hostname The name of the machine on which the ActiveMatrix Administrator server is running.

TIBCO Home Installation directory for ActiveMatrix software installed on this machine. (On UNIX there can be more than one TIBCO home directory on a machine).

Status The status of the ActiveMatrix Administrator server:

• Installing Server configuration files are in the process of being generated on the machine.

• Installed/Stopped The server configuration files have been installed on the machine but it is not running.

• Running The server has been started successfully.

• Uninstalling Server configuration files are in the process of being removed from the machine.

• Unknown The status of the server cannot be determined.

Table 38 Administrator Server Reference

Field Description

Name The name of the ActiveMatrix Administrator server.

Management Port

Port on which the ActiveMatrix Administrator server listens and responds for management and control functions using JMX protocol.

Default: 8110

HTTP Port Port on which the web container that hosts the ActiveMatrix Administrator user interface listens and responds.

Default: 8120

Description A short description of the ActiveMatrix Administrator server.



Hostname The name of the machine hosting the server. One of the machines listed in the drop-down list containing the names of machines bound to the cluster.

A Management Daemon process must be running on the machine before you create the ActiveMatrix Administrator server.

TIBCO Home Installation directory for ActiveMatrix software installed on this machine. (On UNIX there can be more than one TIBCO home directory on a machine).

Table 38 Administrator Server Reference (Cont’d)

Field Description


Working with Substitution Variables | 169

Working with Substitution Variables

Substitution variables are global variables defined at the enterprise assets level and are bound to shared resource definition properties (see Binding a Shared Resource Property to a Substitution Variable on page 118) such as HTTP servers.

The value of a substitution variable can be overridden at the node level (see Working with Substitution Variables on page 213).

To work with substitution variables:


2. Click the Substitution Variables link.

Creating a Substitution VariableTo create a substitution variable:

1. Click the New button above the Substitution Variables table. A new row is added to the table.

2. In the Name column, type a name. The name must be unique and the name and value are case sensitive.

3. In the Type column, select the variable’s type from the drop-down list.

4. In the Value column type a value.

5. Click Save.

Deleting a Substitution VariableDeleting a substitution variable being used in a shared resource is not allowed. To delete a substitution variable:

1. Click the variable in the Substitution Variables table.

2. Click the Delete button above the table.

Editing a Substitution Variable ValueTo edit a substitution variable value:

1. Click the Edit button above the Substitution Variables table.

2. Click the variable in the table.

3. Edit the variable’s value.



4. Click Save.

There are two caveats you should keep in mind when editing substitution variables used by shared resource definitions:

• Changing the value of a substitution variable does not trigger validation of shared resource definition properties. Therefore, changing the value could invalidate the shared resource definition, which would prevent you from installing the shared resource definition on a node.

• The new value does not take effect in a running node using that shared resource definition. You must restart the node or reinstall the shared resource. If the substitution variable is used in a resource referenced by a service assembly running on that node, you must undeploy, redeploy, and start the service assembly after you reinstall the shared resource.


| 171

Chapter 6 Defining Environments

This chapter explains at a high level how to define environments. It provides procedures for adding and deleting environments and configuring hardware and software used by the environments.

Topics

• Environments Overview, page 172

• Creating an Environment, page 173

• Working with Environments, page 175

• Configuring Messaging Bus, page 176

• Enabling Machines, page 184

• Enabling UDDI Servers, page 186

• Working with Shared Resource Definitions, page 188


172 | Chapter 6 Defining Environments

Environments Overview

This chapter explains how to define environments. The next chapter explains how to work with an environment’s nodes, and the containers and shared resources required by each node.

To access environment definition functions:


2. Click the Environment Definition link.

From the environment definition screen you can perform the following tasks:

• Creating an Environment on page 173

• Working with Environments on page 175

• Configuring Messaging Bus on page 176

• Enabling Machines on page 184

• Enabling UDDI Servers on page 186

• Working with Shared Resource Definitions on page 188

Environments Reference

Table 39 Environments Reference

Field Description

Name. Name of the environment.

Description Short description of the environment.

Created By The user that created the environment.

Created On The date the environment was created.


Creating an Environment | 173

Creating an Environment

To create an environment perform the following in the environment definition screen:

1. Click the New button over the Environments table.

2. Enter a name and description for the environment.

Each environment created on a machine must have a unique name, even those administered by different ActiveMatrix Administrator clusters.

3. Click Save.



Environment Reference

Enable AssetsCertain assets used by environments are specified at the enterprise level. These include:

• Machines

• UDDI servers

• Shared resource definitions

In order to use these assets within a particular environment, you must specify that the asset is enabled in the environment. When you are configuring an environment each of the asset types contains a table of available assets and information on whether they have been enabled in the environment. To enable an asset, click the Edit button over the table listing the assets, check the Yes radio button in the row containing the asset you want to enable, and click Save.

Before you can configure a new environment’s nodes, you must enable one or more machines in the environment. See Enabling Machines on page 184 for details.

Configure Messaging Bus SettingsBefore you can configure an environment’s nodes, you must also configure the environment’s Messaging Bus settings to define the transport for messages between the various nodes and containers. See Configuring Messaging Bus Settings on page 176.

Table 40 Environment Reference

Field Description

Name Required. The node’s name. The name must be a valid directory name in the Windows and UNIX operating systems. The name can contain only alphanumeric characters, hyphens, underscores, and dots (periods). Spaces are not permitted. Names are not case sensitive.

The name must be unique among all environments administered by the same ActiveMatrix Administrator cluster. The name must also be unique among environments on one machine, including environments created in different ActiveMatrix Administrator clusters.

Description A description for the environment.


Working with Environments | 175

Working with Environments

At the environment level, you can delete an environment and change the environment’s description.

Deleting an EnvironmentYou can’t delete an environment if any of its nodes are installed. First uninstall any installed nodes. See Installing and Uninstalling Nodes on page 194 for details.

When you delete an environment all the defined nodes, containers, and shared resources are also deleted.

To delete an environment:

1. Select an environment in the Environments table.

2. Click Delete. Confirm the deletion.

Editing an EnvironmentTo edit an environment:


2. Click the General Information link.


4. Edit the Description field.

5. Click Save.



Configuring Messaging Bus

You must define a Messaging Bus for each environment and configure its quality of service setting. The Messaging Bus uses TIBCO Enterprise Message Service servers to provide messaging services between nodes in the environment. (These are called messaging servers). When you configure the Messaging Bus, you create o one or more messaging servers that you want to use for the environment. Messaging servers can be shared across multiple environments.

In addition, you can also configure Messaging Bus properties at the node level. See Appendix C, Session and Thread Pools, on page 363.

Configuring Messaging Bus SettingsEach environment has one Messaging Bus. To configure the Messaging Bus for an environment, perform the following in the environment definition screen:


2. Click the Messaging Bus link.

3. Click Edit.

4. Choose the desired setting for

— Quality of Service See Quality of Service on page 176.

5. Click Save.

Quality of Service

The quality of service (QoS) setting determines message delivery qualities for message exchanges. The selected QoS applies to each message in a message exchange.

Once nodes have been added to an environment, any changes to the QoS must be carefully considered. Although there is no adverse implication of mismatch in QoS setting across different nodes QoS changes should be applied uniformly to across the environment. It is important to note that QoS applies to each JMS message that is sent. A typical distributed in-out message exchange it is comprised of two JMS messages (one for request and other for reply).

Message exchanges may not be impacted if nodes in an environment are using different QoS settings. This may happen if environment is configured with multiple Messaging Bus configurations using different QoS settings. Or if one or more nodes in an environment have been restarted after changes to QoS configuration while some other nodes have not been restarted. An individual


Configuring Messaging Bus | 177

node uses the QoS setting that it retrieves from the database during startup. For example, node1 restarted after a QoS change may start sending messages using Best Effort QoS while node2 which did not restart may continue to send messages using At Most Once QoS.

Best Effort

Also known as Reliable Delivery. Best Effort mode has the best throughput performance of the available quality of service modes.

Messages are resent if the Enterprise Message Service server or target node is down. If the target node is down, messages are delivered when the node is up, provided the Enterprise Message Service server continues running without restarting in the interim.

The characteristics of Best Effort delivery are:

• Messages can be dropped if the server has undelivered messages and is then restarted.

• Duplicate messages can be delivered if Messaging Bus fails to acknowledge the message, or if acknowledgement is not received by the server.

• Messages are not logged to persistent storage.

At Least Once

Also known as Persistent. Messages are guaranteed to be delivered at least once. Throughput performance is not as good as At Most Once and Best Effort.

Messages are resent if the Enterprise Message Service server or target node is down. If the target node is down, messages are delivered when the node is up (whether or not the Enterprise Message Service server continues running without restarting in the interim).

The characteristics of At Least Once delivery are:

• Messages are not dropped if the server has undelivered messages and if server is restarted. This is because messages are stored for delivery when the server restarts.

• Duplicate messages can be delivered if Messaging Bus fails to acknowledge the message, or if acknowledgement is not received by the server.

• Messages are logged to persistent storage.

• A message confirming message receipt by the server is sent to the message sender (and this adversely affects performance).



At Most Once

Also known as non-persistent. If authorization is turned off in the TIBCO Enterprise Message Service product, there is little difference in throughput performance between Best Effort and At Most Once. It is only when authorization is in effect that performance slows with At Most Once mode.

Messages are resent if the Enterprise Message Service server or target node is down. If the target node is down, messages are delivered when the node is up, provided the Enterprise Message Service server continues running without restarting in the interim.

The characteristics of At Most Once delivery are:

• Messages can be dropped if the server has undelivered messages and is then restarted.

• Duplicate messages cannot be delivered (Messaging Bus discards messages if the JMXRedelivered header is set).

• Messages are not logged to persistent storage.

Time-to-Live

To set the time-to-live for Messaging Bus response messages, configure the following property in a node’s TRA file (AMX_HOME/data/environment/node/bin/environment_node.tra):

java.property.com.tibco.matrix.amxframework.messaging.response.tl

The property value is in seconds, and the default is 600 seconds.

Managing Messaging ServersYou must configure a connection to one or more TIBCO Enterprise Message Service servers used for an environment’s Messaging Bus. Before you can add and configure connections to messaging servers, you must install and configure TIBCO Enterprise Message Service software. See TIBCO Enterprise Message Service product documentation and Starting the TIBCO Enterprise Message Service Server on page 22 for details.

To manage an environment’s messaging servers:


2. Click the Messaging Bus link.

In the Messaging Bus screen you can perform the following tasks:

• Adding a Messaging Server to an Environment on page 179



• Removing a Messaging Server from an Environment on page 183

Adding a Messaging Server to an Environment

1. In the Messaging Servers area, click Add. The panel on the right displays configuration fields.

2. Enter a name and description. The name must be unique within the environment.

3. In the Connection Type field, select one of the following and complete the values as appropriate:

— Direct Defines a direct connection to the server.

— JNDI Defines a connection based on JNDI lookup.

4. Complete the values according to the descriptions in Table 41 on page 180.

5. If you select JNDI, then you must create a JNDI Shared Resource as described in Managing Shared Resource Definitions on page 116 and then select the JNDI Configuration, as follows:

a. Click the JNDI Configuration link. You see the Choose JNDI Configuration dialog.

b. Select a JNDI Configuration from the list and click Choose. You return to the Messaging Bus dialog.

6. Click Save.



Messaging Server Reference

Table 41 Messaging Server Reference

Field Description

Name Required. A name that is unique across all messaging servers and shared resource definitions in all environments administered by the same ActiveMatrix Administrator cluster. Names are not case sensitive.

Description A short description of the messaging server.

Reconnect Attempt Count

The number of attempts that should be made to connect to the messaging server. Applies only to connections of type Direct. 1

Reconnect Attempt Delay

The amount of time to delay between attempts to reconnect to the messaging server. Applies only to connections of type Direct.1

Connection Type The type of the connection to the messaging server:

• Direct See Direct Connection.

• JNDI See JNDI Connection.

When you choose a connection type, fields display for you to enter the values required for the connection type.

EMS Username User name used to create a connection to the connection factory. 1

EMS Password Password used to create a connection to the connection factory. If a password has not been defined, leave this field empty. 1



Direct Connection

Table 41 Messaging Server Reference (Cont’d)

Field Description



Provider URL The server URL used to create the connection factory. For more information, see the API documentation for TibjmsConnectionFactory in TIBCO Enterprise Message Service product documentation.

Default: tcp://localhost:7222

The default setting for the Provider URL works in the following circumstances:

• All nodes created in the environment are collocated with the TIBCO Enterprise Message Service server

• The TIBCO Enterprise Message Service server is configured to use the default port of 7222

Since in most cases all nodes in an environment are collocated with the TIBCO Enterprise Message Service server, you should change the host portion of the Provider URL to a fully-qualified hostname and confirm the server port.1Once nodes are created within an environment, any modification of the provider URL must be carefully considered. Under some circumstances it is quite useful. For example, adding second a URL to enable reconnection. Changing the provider URL to a completely different server has the following implications:

• Message exchanges between nodes may break down between nodes using the old server and nodes using a new server.

• Message exchanges between nodes pointing to old server may continue seemingly inconsistent with broken interaction with nodes using the new server.

• Message exchanges between nodes using the new server may take place seemingly inconsistent with broken interaction with nodes using the old server.

• In- flight message exchanges may result in orphan requests or replies depending on the location of consumers and providers in running nodes and consumer and providers in restarted nodes.

The following use cases may be considered useful:

• Adding a second URL to enable reconnection

• Restarting all nodes in environment after applying provider URL changes.


Field Description



Removing a Messaging Server from an Environment

1. In the Messaging Servers area, select a messaging server.

2. Click Remove.

JNDI Connection

JNDI Configuration Choose a JNDI shared resource definition that specifies the JNDI connection information. For information on how to create a JNDI shared resource definition, see JNDI Shared Resource Definition Reference on page 130.

Changes to the JNDI configuration change are considered safe with no implications since it is only a conduit to lookup the connection factory; the connection factory is used to make the actual connection.

Connection Factory The ConnectionFactory object stored in JNDI. See your JNDI provider documentation for more information about creating and storing ConnectionFactory objects.

Default: GenericConnectionFactory.

The implications of modifying the connection factory are identical to those for modifying the provider URL change because the provider URL is embedded in the connection factory. See Provider URL on page 182.

Client Certificate Password

The password of the certificate of messaging server clients. See Enabling Secure Communications Between Nodes and Messaging Servers on page 351.

1. Any modification of the parameter takes effect when nodes in the environment are restarted. Onlynodes that have restarted after the configuration changes were applied use the modified parameter.Nodes that have not been restarted continue to use the old parameter.


Field Description



Enabling Machines

When you plan an environment, you decide where its nodes (and their containers and shared resources) will be installed. A well-developed environment might span 300 machines located anywhere in the network, with 1,000 nodes and 10,000 containers installed across them.

Machines are specified at the enterprise assets level. Before you can define nodes in an environment, you must enable the machines where you want to install the nodes. Each machine where ActiveMatrix software is installed has one or more Management Daemon process, one for each TIBCO home. Windows machines have one TIBCO home. UNIX machines can have more than one.

To specify which machines are enabled and disabled for an environment, perform the following in the environment definition screen:



From the Machines screen you can perform the following tasks:

• Enabling Machines in an Environment on page 184

• Disabling Machines in an Environment on page 184

Enabling Machines in an Environment

To enable machines in an environment:

1. Click Edit.

2. Click the Yes radio button next to the machines you want to enable.

3. Click Save.

Disabling Machines in an EnvironmentTo disable machines in an environment:

1. Click Edit.

The Machines link in the Environment Definition screen shows a list of all machines bound to the ActiveMatrix Administrator cluster. If the machine you want to use does not appear in the list, then you must first bind it to the ActiveMatrix Administrator cluster. See Binding Machines on page 107 for instructions.


Enabling Machines | 185

2. Click the No radio button next to the machines you want to disable.

3. Click Save.

Machines ReferenceThe Machines table contains the machines available to the selected environment. The properties of the features on each machine are described by the columns listed in Table 42.

Table 42 Machines Reference

Column Description


TIBCO Home Installation directory for ActiveMatrix software installed on this machine. (On UNIX platforms there can be more than one TIBCO home on a machine).

When you expand a machine node, under the directory are the ActiveMatrix installation version and the features in the ActiveMatrix installation.

Software Type The type of the features available in the installation directory.

Version The version of the available features.

Enabled? Indicates whether the machine is enabled for this environment.



Enabling UDDI Servers

UDDI servers are specified at the enterprise assets level. See Managing UDDI Servers on page 156.

To specify which UDDI servers are enabled in an environment, perform the following in the environment definition screen:


2. Click the UDDI Servers link.

From the UDDI Servers screen you can perform the following tasks:

• Enabling UDDI Servers in an Environment

• Disabling UDDI Servers in an Environment

Enabling UDDI Servers in an EnvironmentTo enable UDDI servers in an environment:

1. Click Edit.

2. Click the Yes radio button next to the UDDI servers you want to enable.

3. Click Save.

Once you have enabled a UDDI server for an environment, you can publish ActiveMatrix services in the Monitor & Manage perspective. See UDDI Publishing on page 275.

Disabling UDDI Servers in an EnvironmentTo disable UDDI servers in an environment:

1. Click Edit.

2. Click the No radio button next to the UDDI servers you want to disable.

3. Click Save.

UDDI Servers ReferenceThe UDDI Servers table contains the UDDI servers available to the selected environment. The properties of the features on each server are described by the columns listed in Table 43 on page 187.


Enabling UDDI Servers | 187

Table 43 UDDI Server Reference

Column Description


Publish URL The URL to use when publishing to the UDDI server.

Authentication Model

The mechanism to use to authenticate with the UDDI server:

• Basic Authentication Use basic authentication to authenticate with the UDDI server. The provided username and password are used as the authentication credentials.

Enabled? Indicates whether the machine is enabled for this environment.



Working with Shared Resource Definitions

Shared resource definitions are specified at the enterprise assets level. See Managing Shared Resource Definitions on page 116.

To specify which shared resource definitions are enabled in an environment, perform the following in the environment definition screen:


2. Click the Shared Resource Definitions link.

Only parent resources like HTTP, JDBC, JMS, Rendezvous, and so on are visible in the Shared Resource Definitions screen. All referenced resources, such as Identity and JNDI, do not appear. Such resources are automatically enabled by enabling the parent resource.

From the Shared Resource Definitions screen you can perform the following tasks:

• Enabling and Disabling Shared Resource Definitions in an Environment

Enabling and Disabling Shared Resource Definitions in an EnvironmentTo enable or disable a shared resource definition in an environment:

1. Click Edit.

2. Click the Yes radio button next to the shared resource definitions you want to enable and the No radio button next to the shared resource definitions you want to disable.

3. Click Save.


| 189

Chapter 7 Configuring Environments

This chapter describes how to configure the nodes managed by the environment, and the connector, containers, shared resources, and keystore entries contained in the nodes.

Topics

• Working with Nodes, page 190

• Working with the Default Connector, page 201

• Working with Containers, page 204

• Working with Shared Resources, page 209


• Working With Logging Configurations, page 215


190 | Chapter 7 Configuring Environments

Working with Nodes

A node is a Java virtual machine running ActiveMatrix containers and Messaging Bus. When you are setting up an environment, you add as many nodes as are needed for your architecture and specify on which machines they will be installed. Then you install the nodes and start them.

One approach to setting up the environment is to create one node, install it and start it, and then configure its containers and shared resources. Then move on to the next node and do the same kinds of actions again. Node configuration could also be done using a different order. For example, you can create all the nodes, then install and start them all.

A node must be running before you can perform deploy service assemblies to it.

All procedures in this section are performed in the Nodes screen. To access this screen:

1. Select Configure an Environment from the Perspective drop-down list.

2. Select the environment you want to configure from the Environment drop-down list.

Node operations are described in the following sections:

• Enabling Assets in Nodes on page 191

• Creating a Node on page 192

• Installing and Uninstalling Nodes on page 194

• Starting and Stopping Nodes on page 195

• Editing a Node on page 196

• Setting Permissions for Nodes on page 199

• Installing a Shared Library in a Node on page 199

• Deleting Nodes on page 199

Certain long-running operations, such as installing and starting a node, are performed asynchronously. This means that the user interface continues to respond to user actions while the operation is in progress and does not automatically update the status. To update a node’s status for such operations, click the Refresh button .


Working with Nodes | 191

Enabling Assets in NodesCertain assets used by nodes may be available to the nodes, but disabled. These include:

• Containers Containers are enabled by default.

• Shared resources Shared resources are disabled by default.

In order to use such an asset within a particular node, you must specify that the asset is enabled in the node.

In the ActiveMatrix Administrator graphical interface, when you are configuring a node, viewing one of the asset types displays a table of available assets and information on whether they have been enabled in the node. To enable an asset, click the Edit button over the table of assets, check the Yes radio button in the row containing the asset you want to enable, and click Save.



Creating a NodeBefore you create the first node in an environment, decide whether you want communications between the environment’s nodes and other ActiveMatrix components to be secured. If you want secure communications, perform the configuration changes described in Appendix A, Securing TIBCO ActiveMatrix Communication Channels, on page 339.

When you create a node, its details are stored in the database. To create a node:

1. Click the New button above the Nodes table. The General panel displays configuration fields.

2. Type a name in the name field.

3. Complete the rest of the fields following the guidelines in Table 45 on page 197.

4. Ensure that the values of the node’s default connector are unique. See Working with the Default Connector on page 201.

5. Click Save.

After a few seconds, the node appears in the Nodes table, which contains all the nodes that have been added to the selected environment. Table 44 describes the Nodes table columns.

Table 44 Nodes Reference

Column Description

Name The node’s name.



Status The node’s status:

• Defined The node is defined in the database but the configuration files have not been installed on the machine.

• Installed Node configuration files have been successfully generated on the machine, but whether the node process is running or stopped is not known.

• Installing Node configuration files are in the process of being generated on the machine.

• Install Failed1 Node installation has failed.

• Installed/Stopped1 The node configuration files have been installed on the machine but the node is not running. This state occurs after the node has been installed but before it has been started or after it has been started and then stopped.

• Start Failed1 Node startup has failed.

• Starting The node is in the process of being started.

• Stop Failed1 Node stop has failed.

• Stopping The node is in the process of being stopped.

• Running1 The node is running.

• Uninstall Failed1 Node uninstallation has failed.

• Uninstalling Node configuration files are in the process of being removed from the machine.

• Unknown The status of the node cannot be determined.

See Figure 17 on page 194.

Machine The machine on which the node is installed.

1. The status is a link that you can click to display a screen with information about the error.

Table 44 Nodes Reference (Cont’d)

Column Description



Figure 17 Node Status Life Cycle

When the node has been fully configured, the Containers and Shared Resources links display information about the containers and shared resources that are available on this node. See Working with Containers on page 204 and Working with Shared Resources on page 209 for more details.

Installing and Uninstalling Nodes

Installing Nodes

Installing a node creates configuration files on the machine on which the node will run. To install a node:

1. In the Nodes table, select the nodes you want to install and click Install. The nodes’ status changes to Installing.

2. Click the Refresh button located at the top right of the table until the node’s status changes to Installed/Stopped.

A node installation directory is created in AMX_HOME/data/environmentname/nodename/. The node executable is located in the bin subdirectory of the installation directory and is named environmentname_nodename.exe.

DefinedNew

Installing

Install

Installed/Stopped

[success]

Install Failed

[failure]

Uninstalling

Uninstall

Starting

Start

Delete

[success]

Uninstall Failed

[failure]

Start Failed

[failure]

Running

[success]

Uninstall

Stopping

Stop

Stop Failed

[failure]

[success]

Uninstall

Stop

Uninstall



Uninstalling Nodes

Uninstallation removes the node’s configuration files from the machine where you installed it. When you uninstall a node, all its containers and shared resources are also uninstalled. The node definition remains in the database and the node status changes to Defined.

The node must be stopped and all service units unmapped from the node before you can uninstall it. To uninstall a node:

1. In the Nodes table, select one or more nodes and click Uninstall. The nodes’ status changes to uninstalling.

2. Click the Refresh button located at the top right of the table until the nodes’ status changes to Defined.

Starting and Stopping NodesAfter you have installed a node you can perform life cycle actions on it such as start and stop.

Starting Nodes

To start a node:

1. In the Nodes table, select one or more nodes and click Start. The nodes’ status changes to Starting.

2. Click the Refresh button located at the top right of the table until the nodes’ status changes to Running.

Windows

On Windows platforms, you have the option to install the node as a Windows service. When you attempt to start the node from the Services application in the Control Panel a timeout error may be displayed. The node status appears incorrect for some time and then is corrected. This occurs because the default timeout period Windows applies to services is too small for nodes. To modify this timeout period, follow these steps:

1. Create a file name SvcTimeOut.bat containing the following commands:

@echo offif {%1}=={} @echo Syntax: SvcTimeOut TimeOutMilliseconds&goto :EOF@echo REG ADD "HKLM\SYSTEM\CurrentControlSet\Control" /V ServicesPipeTimeout /T REG_DWORD /F /D %1



REG ADD "HKLM\SYSTEM\CurrentControlSet\Control" /V ServicesPipeTimeout /T REG_DWORD /F /D %1

2. Run SvcTimeOut TimeOutMilliseconds, where TimeOutMilliseconds is the number of milliseconds that the Service Control Manager should wait. TimeOutMilliseconds should be at least 600000, which is 10 minutes.

3. Shut down and restart your computer.

Starting a Node on Machine Startup

When you create a node you can specify whether the node should be started when the machine on which it is installed is started.

Windows

To configure a Windows service node to start when the machine starts:

1. Open the Windows Services application.

2. Right-click the Windows service and select Properties.

3. Select Automatic from the Startup type drop-down list.

UNIX

On UNIX platforms, you must add a node startup script to the UNIX startup configuration files that control daemon startup.

Stopping Nodes

To stop a node:

1. In the Nodes table, select one or more nodes and click Stop. The nodes’ status changes to Stopping.

2. Click the Refresh button located at the top right of the table until the nodes’ status changes to Installed/Stopped.

When you stop a node, its containers are also stopped.

Editing a NodeBefore you install a node (or after you uninstall it), you can edit the node definition and change the machine on which the node will be installed.

SvcTimeOut.bat uses REG.EXE, built into Windows XP, Windows Server 2003, and later, or installed from the Windows 2000 Support Tools.



When a node is installed, the only editable field is the Description field. If you want to make more changes, you must first uninstall the node.

1. In the Nodes table, select a node.

2. Click the General Information link. In the General Information area, click Edit. If the node is not yet installed, you can edit all fields in this section. If it is installed, you can edit only the description. See Table 45 for details on all the fields.

3. Click Save.

Node Reference

Table 45 Node Reference (Sheet 1 of 2)

Field Description

Name Required. The node’s name. The name must be a valid directory name in the Windows and UNIX operating systems. The name must be unique within the environment. The name can contain only alphanumeric characters, hyphens, underscores, and dots (periods). Spaces are not permitted. Names are not case sensitive.

You cannot edit the name after you install the node.

Description A short description of the node.

Messaging Server Required. The messaging server to use for this node’s transport requirements. Select a machine from the drop-down list containing the messaging servers in the environment.

Each node is associated with one messaging server. For example, in geographically distributed environments, you might use a messaging server in the same region in which the node is created. If the nodes in an environment are using different messaging servers, you must configure routes between the servers. See Configuring Multiple Messaging Servers in Multinode Scenarios on page 200.

Management Port Required. Port on which the node listens and responds for management and control functions using JMX protocol.



Machine Name Required. The machine on which the node will run. Select a machine from the drop-down list containing the machines enabled in the environment.

If you want to use a machine that is not in the drop-down list you must bind the machine as described in Binding Machines on page 107 and enable it in the environment as described in Enabling Machines in an Environment on page 184.

Windows Service? Specify whether the node runs as a Windows service.

The name of the Windows service is TIBCO ActiveMatrix environmentname_nodename ENV_NAME. The startup type is Manual.

You cannot edit this setting after you install the node.

Default: No.

Product Required. The path to the ActiveMatrix installation directory on the machine on which the node is installed.

Table 45 Node Reference (Sheet 2 of 2)

Field Description



Setting Permissions for NodesTo set permissions for nodes:

1. In the Nodes table, select the node or nodes for which you want to set permissions.

2. Click the Set Permission button.

3. Follow the procedures described in Permissions on page 147.

Installing a Shared Library in a NodeSometimes you might want to share a library between multiple service units running on a node instead of packaging the library into every service unit. ActiveMatrix allows you to install a library in a node. The library must be packaged in an Eclipse feature. To install a library:

1. Unzip the library into the ENV_HOME/components/eclipse folder on the machine where the node is installed.

2. Change to the directory AMX_HOME/2.3/server/bin.

3. Run SyncInstallation.

Deleting NodesBefore you can delete a node, you must stop and uninstall the node if it has been installed and started. To delete nodes:

1. In the Nodes table, select the nodes you want to delete.

2. Click Delete.

3. If the delete fails, the node status changes to Delete Failed and a Resolve link appears in the column to the right of the status column. To force the delete, click the Resolve link. A dialog displays offering you the option to force anyway.

4. Click Yes to complete the delete.



Configuring Multiple Messaging Servers in Multinode ScenariosIt is possible to configure ActiveMatrix environment with multiple messaging servers and assign different servers to the nodes within the environment. If the nodes in an environment are configured to use a different Enterprise Message Service server for each node, you must enable routing at the Enterprise Message Service server level. For example, assume you have three nodes in an environment and 3 Enterprise Message Service servers:

• Node1 is configured to use Enterprise Message Service server 1



Suppose you deploy a service assembly across the nodes as follows:

SOAP - Java (Node1) - Java (Node2) - Java (Node3)

For this scenario you must configure the Enterprise Message Service server configuration files as follows:

• Create a unique name for each Enterprise Message Service server in the tibemsd.conf file.

• Enable the route property in tibemsd.conf file. By default this property is disabled.

• Add the following queue names to the Enterprise Message Service server 1 queues.conf file:

EnvironmentName.Node1.JavaContainerName.Queue.Destination globalEnvironmentName.Node2.JavaContainerName.Queue.Destination@EMS-Server2 global

• Add the following queue names to the Enterprise Message Service server 2 queues.conf file:

EnvironmentName.Node2.JavaContainerName.Queue.Destination globalEnvironmentName.Node3.JavaContainerName.Queue.Destination@EMS-Server3 global


Working with the Default Connector | 201

Working with the Default Connector

The default connector is used to access system services, such as WSDL generation, provided by a node.

All procedures in this section are performed in a node’s Default Connector screen. To access this screen:



3. In the Nodes list, select a node.

4. Click the Default Connector link.

To edit the default connector:


2. Edit the fields according to the descriptions in Table 46.

3. Click Save.

Default Connector Reference

Table 46 Default Connector Reference

Field Description

Host Specifies the name of the host that accepts the incoming requests. For machines that have only one network card, the default value localhost specifies the current machine. For machines that have more than one network card, this field specifies the host name of the card that used to accept incoming HTTP requests.

If there is more than one network card on the machine, and you specify localhost in this field, all network cards on the machine listen for incoming HTTP requests on the specified port. Only one HTTP server can be started on each port. Therefore make certain that all HTTP connection resources that use the same host name specify different port numbers.

Default: localhost.



Port Port number on which to listen for incoming HTTP requests.

Default: 10866.

Note: If you create more that one node on a machine you should ensure that the port numbers are unique.

Status The status of HTTP server shared resource that implements the default connector: Installed.

Enable DNS Lookups

Enables a Domain Name System (DNS) lookup for HTTP clients so that the IP address is resolved to a DNS name. This can adversely affect throughput, so enable this field only when required.

Maximum Post Size

Maximum size allowed for HTTP POST data.

Default: 1000. Unit is bytes.

Redirect Port If the HTTP connection supports non-SSL requests, and a request received requires SSL transport, the request is redirected to the port you specify here.

Default: 8081.

Connection Timeout

The number of milliseconds the connector waits, after accepting a connection, for the specific URI the request is sending to be presented.

Default: 20000. Unit is milliseconds.

Minimum Threads

The minimum number of threads available for incoming HTTP requests. The HTTP server creates the number of threads specified by this parameter when it starts up.

Default: 25

Maximum Threads

The maximum number of threads available for incoming HTTP requests. The HTTP server does create more than the number of threads specified by this parameter.

When a client sends a request that cannot be processed because no threads are available, the ActiveMatrix node returns a ConnectionRefused exception to the client.

Default: 150

Table 46 Default Connector Reference (Cont’d)

Field Description


Working with the Default Connector | 203

Disable Upload Timeout

If not checked, an additional connection timeout period is used while a SOAP message is being executed. If checked, the additional timeout period is not used.

Default: false (not checked)

Table 46 Default Connector Reference (Cont’d)

Field Description



Working with Containers

Containers are the runtime environments for a component implementations and service and reference bindings. The ActiveMatrix software installed on a machine determines what containers are available to nodes on that machine. While you are defining, installing, and starting nodes, the containers available on the nodes can be either enabled or disabled and active or not active.

When a node is created, by default the containers whose software is available on the machine are enabled. Enabled containers are activated when the node is started and only active containers can run service units.

You can disable a container at any point in the container’s life cycle. Disabled containers are not activated when the node is started. For example, if you will not be deploying any services with JMS bindings, you would disable the JMS container so that it does not consume resources when the node is started.

If you disable a container when the node is running, then you must manually deactivate the container. Conversely, if you re-enable a container when the node is running, you must manually activate the container.

In summary, enabling and disabling a container permanently affects the container’s behavior across node startup. On the other hand, activate and deactivate are transient actions that is they don’t affect any configuration permanently; they simply change the state of a container on a running node.

All procedures in this section are performed in a node’s Containers screen. To access this screen:



Enabling and Disabling ContainersTo enable or disable containers:


2. Click the Containers link.


4. In the Enabled at Startup column, click the Yes radio button next to the containers you want to enable. Click the No radio button next to the containers you want to disable.

5. Click Save.


Working with Containers | 205

Command-Line Interface

To enable or disable a container, you add or delete a container to a node in full or base format. The container element requires a type attribute in the format:

com.tibco.matrix.container.containerNamecontainerType.runtime

where the values that containerName and containerType can assume are listed in Table 47

For example, to add a node and then enable the Java container, use the following AMXAdminTask definitions and data file elements:

<target name="node-add" description="Add Node"><AMXAdminTaskserviceBaseURL="serviceURL" username="userName" password="password"action="add" dataFile="dataFile" objectSelector="Environment/Node"overwrite="true" merge="true" createIfNotExists="true" forceDelete="true"/></target>

<Node xsi:type="amxdata:Node" name="nodeName"hostName="hostname" tibcoHome="ENV_HOME"productInstallDirectory="AMX_HOME" productVersion="2.3.0"messagingServerName="messagingServerName" namingPort="namingPort"</Node>

<target name="container-add" description="Add Container"><AMXAdminTaskserviceBaseURL="serviceURL" username="userName" password="password"action="add" dataFile="dataFile" objectSelector="Environment/Node/Container"overwrite="true" merge="true" createIfNotExists="true" forceDelete="true"/></target>

<Node name="nodeName"<Container type="com.tibco.matrix.container.javase.runtime"

version="2.3.0" />

Table 47 Container Type Attribute Components

Container containerName containerType

Java java se

.NET clr se

Mediation mediation se

Adapter adapter binding

SOAP soap binding

JMS jms binding



</Node>

Activating and Deactivating a ContainerA container of the required type must be activated on a node in order for a service unit to be deployed to that node.

If a container is enabled for a node, either of the following actions activates the container:

• Explicitly invoking the activate action for the container

• Restarting the node

To explicitly invoke the activate or deactivate actions:


2. Click the Containers link.

3. In the Containers list, select a container.

4. To activate a container, click the Activate button. To deactiveate a container, click the Deactivate button.

Container Reference

Table 48 Container Reference

Field Description

Name The name of the container.

Version The version of the container.

When specifying the version in the command-line interface data file you are required to provide only as much of the version as you know. For example, if you know that you have a container of version 1.0.1 but don’t know the version qualifier, you can specify the version as 1.0.1. The command-line interface finds all containers of version 1.0.1 and choose the one with the highest version qualifier. If you don’t know the maintenance version, you can specify 1.0. The command-line interface finds all containers of version 1.0 and choose the one with the highest maintenance version.


Working with Containers | 207

Status The status of the container. One of

• Active The container is active. A service unit cannot be deployed to a node without at least one active container of the required type.

• Marked for Activation The contained has been enabled. When the node starts up, the container is activated.

• Marked for Deactivation The container has been disabled. When the node starts up, the container is not activated.

• Not Active The container is not activated.

• Error An error occurred while attempting to activate or deactivate the container.

• Unknown The status is unknown.

See Figure 18.

Enabled at Startup?

Indicates whether the container is enabled for this node.

If any service units in a service assembly have been bound to this container you cannot change the setting. (See Chapter 8, Deploying Service Assemblies, on page 217 for more details on deploy-time activities.)

Table 48 Container Reference (Cont’d)

Field Description



Figure 18 Container Status Life Cycle

Active

Marked for Deactivation Marked for Activation

Not Active

Activate

Deactivate

Activate Disabled

Deactivate Enabled Start Node Start Node


Working with Shared Resources | 209

Working with Shared Resources

A shared resource enables services to connect with physical resources they need to function. ActiveMatrix Administrator enables you to specify resources that can be shared across all the services running on a node.

The actions you perform on shared resources are enabling and disabling, installing and uninstalling. Before you can enable and install a shared resource, you must have created the shared resource definition that it uses. See Managing Shared Resource Definitions on page 116 for an overview and more details.

Once the definition has been created you first enable the resource for the node and then you install the resource in the node. Installing a resource allocates files on the node. Once a shared resource is enabled for a node, either of the following actions installs the resource:

• Explicitly installing the resource through a user interface command


Similarly, once a shared resource has been disabled for a node, either of the following actions uninstalls the resource:

• Explicitly uninstalling the resource through a user interface command


HTTP shared resources can be customized through the use of local substitution variables. See Customizing HTTP Shared Resource Definitions on page 11 and Overriding a Substitution Variable Value on page 213.

Enabling and Disabling Shared ResourcesYou cannot disable a shared resource if it is installed or if a shared resource profile is mapped to the resource. For further information, see Mapping Shared Resource Profiles to Shared Resources on page 236. To enable or disable shared resources:

1. Select a node.

2. Click the Shared Resources link.


4. In the Enabled at Startup column, click the Yes radio button next to the shared resources you want to enable. Click the No radio button next to the shared resources you want to disable.

5. Click Save.



Installing and Uninstalling Shared Resources

Installing Shared Resources

After you enable shared resources you install the resources on the nodes. You can install the resource only if no other shared resource of the same name has been installed on the node.

To install shared resources:

• If the node status is Running, select one or more shared resources and click Install.

• If the node status is Installed/Stopped, select one or more shared resources, enable the resources, and start the node.

Uninstalling Shared Resources

When you uninstall a shared resource, its files are removed from the node where you earlier installed it and it is disabled.

You cannot uninstall a shared resource if any shared resource profile is mapped to it. See Mapping Shared Resource Profiles to Shared Resources on page 236.

To uninstall shared resources:

• If the node status is Running, select one or more shared resources and click Uninstall.

• If the node status is Installed/Stopped, select one or more shared resources, disable the resources, and start the node.

Enabling and Disabling Resource FunctionsResource functions modify the behavior of the shared resource. The resource functions are:

• WS-Addressing An HTTP server shared resource with the WS-Addressing resource function enable must be installed in any node hosting SOAP references that require non-anonymous WS-Addressing support. Once the resource is installed, the shared resource is enabled to receive WS-Addressing reply and fault messages. See WS-Addressing in TIBCO ActiveMatrix Composite Editor User’s Guide.

The installation will fail if the IP of the machine hosting the node changes after the node is created. To proceed with installation, first restart the node.


Working with Shared Resources | 211

For each node, only one shared resource can have a resource function enabled. To enable a resource function for a shared resource:

1. Select the resource.


3. Click the -Select- link. The Select Resource Functions dialog box displays.

a. To enable the function, check the checkbox next to the function. To disable the function, uncheck the checkbox.

b. Click Apply.

4. Click Save.

Shared Resource Reference

Table 49 Shared Resource Reference

Field Description

Name Required. A name that is unique within the node where it is installed. (Names can be the same across nodes.) Names are not case sensitive.

Type The type of the shared resource.

Status The status of the shared resource:

• Uninstalled Before the shared resource is enabled for the first time, after you uninstall the resource, after you restart a node and the resource was Marked for Uninstall.

• Marked for Install After you enable a resource.

• Installed After you install the resource or restart a node and the resource was Marked for Install.

• Marked for Uninstall After you disable an installed resource.


Enabled on Startup?

Indicates whether the shared resource is enabled for this node. If you enable the resource, it installs when the node is restarted. If you disable the resource, it is uninstalled when the node is restarted.

If any service units in a service assembly have been bound to this resource you cannot change the setting. See Chapter 8, Deploying Service Assemblies, on page 217 for details on deploy-time procedures.



Figure 19 Shared Resource Status Life Cycle

Resource Functions

The resource function enabled for the shared resource.

The field is empty if no resource functions have been enabled for the shared resource.

Table 49 Shared Resource Reference (Cont’d)

Field Description

Installed

Marked for Uninstall Marked for Install

Uninstalled

Install

Uninstall

Install Disabled

Uninstall Enabled Start Node Start Node


Working with Substitution Variables | 213


Substitution variables are global variables defined at the enterprise assets level (see Working with Substitution Variables on page 169) and bound to shared resources, such as HTTP servers (see Binding a Shared Resource Property to a Substitution Variable on page 118). The value of a substitution variable can be overridden at the node level.

To work with substitution variables:


2. Click the Local Substitution Variables link.

Overriding a Substitution Variable ValueTo override a substitution variable value:

1. Click the Edit button above the Local Substitution Variables table.

2. Edit the variable’s type or value.

3. Click Save.

There are two caveats you should keep in mind when overriding substitution variables used by shared resource definitions:

• Changing the value of a substitution variable does not trigger validation of shared resource definition properties. Therefore, changing the value could invalidate the shared resource definition, which would prevent you from installing the shared resource definition on the node.

• The new value does not take effect in a running node using that shared resource definition. You must restart the node or reinstall the shared resource.

Reverting a Substitution Variable Back to the Global ValueTo revert a substitution variable value back to the value defined at the enterprise assets level:

1. Click the Edit button above the Local Substitution Variables table.

2. Click the Revert link.

3. Click Save.



Local Substitution Variables Reference

Table 50 Local Substitution Variables Reference

Column Description

Name The variable’s name.

Type The variable’s type.

Value The variable’s value.

Either a Revert link, which indicates that the value has been overridden locally or text, which indicates that the global value is being used.


Working With Logging Configurations | 215

Working With Logging Configurations

See Working with Logging Configurations on page 310.




| 217

Chapter 8 Deploying Service Assemblies

This chapter explains how to upload a service assembly archive, configure it, and deploy it.

Topics

• Deployment Overview, page 218

• Uploading a Service Assembly, page 220

• Configuring a Service Assembly, page 222

• Working with Service Assemblies, page 223

• Working with Service Units, page 233

• Mapping Shared Resource Profiles to Shared Resources, page 236

• Working with Topics, page 237


• Working with Logging Configurations, page 239

• Working with Services, page 240


218 | Chapter 8 Deploying Service Assemblies

Deployment Overview

At deploy time you upload an archive containing a service assembly, configure it, and deploy it. The archive is the output of the design-time ActiveMatrix activities. A service assembly might have 1-50 service units, and each service unit might have one to 100 services.

All procedures in this chapter are performed in the Deploy to an Environment screen. To access this screen:

1. Select Deploy to an Environment from the Perspective drop-down list.

2. Select the environment you want to deploy to from the Environment drop-down list.

Configuring Service AssembliesTo configure a service assembly, you:

• Upload the service assembly and choose whether to import shared resource definitions.

• Map service units to nodes. The service units contained in the service assemblies are deployed to the appropriate containers on those nodes.

• Map shared resource profiles to shared resources.

• Edit substitution variables as needed.

Service assembly configuration details are stored in the ActiveMatrix Administrator database, so even if you undeploy a service assembly, the configuration details are retained and you can redeploy it without having to go through the configuration steps again.


Deployment Overview | 219

Reusing Archives

Each archive contains files for one service assembly. You can create more than one service assembly configuration using one archive. To do so you upload the archive file again and give it a different service assembly name. Then you can configure and deploy it as needed. For example, you might want to deploy the same archive in environments set up for different geographical regions, or to implement different service level agreements, or for testing and later for staging.

Deploying a Service Assembly After the service assembly is configured you can deploy it. All nodes required for the deployment must be running, all containers required for the deployment must be activated, and all shared resources must be installed.

After a service assembly is deployed and running, you can start and stop the service assembly and shut it down. You can also undeploy it.

It is not possible to deploy more than one service assembly with the same namespace in an environment. You can upload the same service assembly archive or different archives with the same namespace but if any one of these service assemblies is deployed, the Deployable status of all other service assemblies with the same namespace is No.



Uploading a Service Assembly

Uploading a service assembly transfers a local service assembly archive file to the ActiveMatrix Administrator database. To upload a service assembly archive file:

1. Click Upload Service Assembly.

2. In the Name field, enter a name for the service assembly. The name can contain only letters, digits, '-', '_' and '.’.

3. Click Browse... to choose a service assembly archive file from the file system. A service assembly archive file has a .zip extension.

Import sharedresource

definitions

4. Check the Import Shared Resource Definitions checkbox to create shared resources definitions from definitions in the service assembly archive. See Importing Shared Resource Definitions.

5. Click OK.

The service assembly is added to the Service Assemblies table. The service assembly status is Not Deployed and the Deployable? column is No. Table 51 on page 221 describes the Service Assemblies table columns.

You can select the service assembly you just added and the General Information screen for the service assembly displays the Name, Archive File, and Namespace properties (see Service Assembly Reference on page 226).

Importing Shared Resource DefinitionsDuring service assembly upload, the Import Shared Resource Definitions option creates the shared resource definition in the enterprise and enables it for the environment. If the shared resource name already exists within the enterprise, the name is appended with the string _N, where N is an increasing integer. For example, if you upload a resource named HTTPSR and that resource name already exists, the imported resource is named HTTPSR_1, and so on..

HTTP client and SSL client shared resources defined in a service assembly archive are not supported in ActiveMatrix Administrator and cannot be imported.


Uploading a Service Assembly | 221

Once the upload is complete, you must enable and install the shared resource on each nodes where the shared resource is used (see Working with Shared Resources on page 209).

Service Assemblies Reference

If you import shared resource definitions from the service assembly archive and those definitions use substitution variables for the value of resource properties, the property values are hardcoded with the value of the substitution variables at the time of upload. Once the property values are hardcoded, you cannot edit the value of the resource properties by edited the value of the substitution variables in the service assembly (see Substitution Variables Reference on page 235) or service unit (see Working with Substitution Variables on page 238).

Table 51 Service Assemblies Reference

Column Description

Name The name of the service assembly.

Version The version of the service assembly.

Deployable? Indicates whether the service assembly has been configured for deployment or whether the service assembly’s namespace is unique.

Status The status of the service assembly.

Packaged By The user that created the service assembly.

Last Modified By The user that last modified the service assembly.

Last Modified On The date and time that the service assembly was last modified.

Deployed By The user that deployed the service assembly.



Configuring a Service Assembly

Configuring a service assembly requires you to specify the nodes on which service units in the service assembly are deployed. You must also map shared resource profiles to shared resources as appropriate for the service assembly.

Configuring Service UnitsTo configure the service units in a service assembly:

1. In the Service Assemblies table, select the service assembly or assemblies.

2. Click the Service Units button.

3. For each service unit in the service assembly:

a. Select the service unit in the Service Units table.

Map service unitsto nodes

b. In the Node Mapping tab, map the service units to nodes as described in Mapping Service Units to Nodes on page 233.

Edit substitutionvariables

c. Click the Substitution Variable tab if you want to edit the substitution variables for the service unit. Follow the procedure described in Substitution Variables Reference on page 235.

Mapping Shared Resource Profiles to Shared ResourcesA shared resource profile specifies the kind of physical resource needed by services. Shared resource profiles are defined at design time and packaged in the service assembly archive. Before deployment you must map each shared resource profile to a shared resource available in the node that the service unit is mapped to as described in Mapping Shared Resource Profiles to Shared Resources on page 236.


Working with Service Assemblies | 223

Working with Service Assemblies

After you have uploaded and configured one or more service assemblies, these actions are available:

• Deploying and Redeploying Service Assemblies on page 223

• Starting and Stopping Service Assemblies, page 224

• Editing Service Assembly Configurations on page 225

• Updating a Service Assembly Archive on page 229

• Downloading a Service Assembly Archive on page 230

• Updating Service Assemblies on page 230

• Undeploying Service Assemblies, page 231

• Deleting Service Assemblies, page 231

Nodes must be running in order to execute the deploy, start, and stop actions.

Deploying and Redeploying Service AssembliesA service assembly is considered deployable only when all service units are mapped to nodes, all shared resource profiles are mapped to shared resources, and the target namespace of the composite packaged in the service assembly is unique within the environment. When all of these conditions are met, the service assembly’s value the Deployable? column is Yes.

However, to actually deploy the service assembly, all nodes required for the deployment must be running, all containers required for the deployment must be activated, and all shared resources must be installed. In some cases the status of nodes, containers, and shared resources shown in ActiveMatrix Administrator may not reflect the actual state of the objects. For example:

• The node is running, but the status has not yet been updated in ActiveMatrix Administrator to show the node as Running, but instead is shown as Installed/Stopped.

• The node is stopped, but the status has not yet been updated in ActiveMatrix Administrator to show the node as Installed/Stopped, but instead is shown as Running.

• The node is running, but the Management Daemon process is stopped and the but the node status is shown as Unknown.



Likewise, the reported status of containers and shared resources may be different than the actual status. In such cases, if you know that the object is in the correct state you can optimistically attempt to deploy the service assembly. If any object is not in the correct state, an error is returned when you try to deploy the service assembly describing why it could not be deployed.

To deploy a service assembly, in the Service Assemblies table, select one or more service assemblies and click Deploy. The Status column changes to Deploying.

If the service assembly is deployed successfully, the status changes to Deployed. If there are errors, the Status column changes to Deployed with Errors. After resolving deployment errors (the status is a link you can click to display a screen with information about the error) click the Redeploy button to complete deployment.

You can also redeploy a service assembly after changing the mapping of service units to nodes. See Updating Service Assemblies on page 230.

Starting and Stopping Service AssembliesAfter a service assembly has been successfully deployed, you can start it, and, as needed, stop it.

Starting Service Assemblies

To start service assemblies:

1. In the Service Assemblies table, select one or more service assemblies.

2. Click Start. The Status column changes to Starting.

If the service assembly starts successfully the Status column changes to Running. If there are errors, the Status column changes to Running with Errors. After resolving the errors (the status is a link you can click to display a screen with information about the error) click the Redeploy button to start the assembly.

Stopping Service Assemblies

The service assemblies must be started in order for you to stop them.

To stop service assemblies:


2. Click Stop. Status changes to Stopping, then Deployed.



Editing Service Assembly ConfigurationsYou can edit the configuration of service assemblies that are deployed, as well as those that are not deployed. Once you save the settings the service assembly’s status is Out of Sync and you must update the service assembly. See Updating Service Assemblies on page 230.

To edit service assembly configurations:

1. In the Service Assemblies table, select the service assembly.

2. Click the General Settings button.

3. Click the General Information link.


5. As needed, edit the fields in the General Information area. See Table 52 for details on all the fields.

6. Click Save.



Service Assembly Reference

Table 52 Service Assembly Reference

Field Description

Name Name of the service assembly.

Archive File The name of the service assembly archive file that contains the service units to be deployed. The name is a link that you can click to download the file.

Description Descriptive information about the service assembly.

Packaged By The user that packaged the service assembly.

Contact Contact information for the maintainer of the service assembly.

Namespace The namespace defined in the service assembly. In order for the service assembly to be deployable, the namespace must be unique within an environment.



Status Current status of the service assembly. One of:

• Deployed The service assembly has been deployed but has not been started.

• Deployed with Errors1 The service assembly has been deployed, but errors need to be resolved before it can be started. After you resolve the errors, click the Redeploy button to complete deployment.

• Running The service assembly is running.

• Running with Errors1 The service assembly has been started on some nodes, but errors need to be resolved before it can be started on all nodes. After you resolve the errors, click the Redeploy button to complete starting the assembly.

• Not Deployed The service assembly archive has been uploaded but has not been deployed or has been deployed and then undeployed.

• Not Deployed with Errors1 The service assembly has been undeployed with errors.


In addition, the status columns can display two flags:

• Out of Sync Indicates that configuration changes have been made to a deployed or running service assembly, and the service assembly in the node does not match the version in the database. For the appropriate action to take, see Updating Service Assemblies on page 230.

• Redeployable Indicates that configuration changes have been made to a deployed or running service assembly and the service assembly must be redeployed by clicking the Redploy button. For further information on the circumstances that cause this flag, see Updating Service Assemblies on page 230.

Table 52 Service Assembly Reference (Cont’d)

Field Description



Expose Endpoints

Determines which endpoints in the service assembly are exposed to Policy Manager when deployed. One of the following values:

• All Both internal and external endpoints are exposed to Policy Manager. An internal endpoint is accessible only to consumers within an ActiveMatrix environment. An external endpoint has a binding that provides access to consumers outside the ActiveMatrix environment.

• None No endpoints are exposed to Policy Manager.

• External Only external endpoints are exposed to Policy Manager.

Note: Policy Manager does not enforce policies for out-only endpoints.

Default: External.

To further qualify external endpoints for synchronization with Policy Manager, set the property java.property.com.tibco.policy.ExposeExternalEndpointsQualifier in a node’s TRA file. This new property can take the values All, Service, and Reference, extending the existing All, None, and External options of the Expose Endpoints feature.

If this property is set and the user selects General Information > Expose Endpoints > External in the service assembly, the endpoint synchronization behaves as follows for the property's values:

All All the external endpoints are synchronized with Policy Manager

Service Only external service endpoints are synchronized with Policy Manager

Reference Only external reference endpoints are synchronized with Policy Manager

This property does not affect the behavior if it is not set, or if the user selects All or None from the Expose Endpoints dropdown list.

Prefer Local Providers?

If checked and the consumer and provider are collocated on same node then requests are routed to the local provider. Since messages are not routed through the Enterprise Message Service server, requests are not load balanced among other provider instances available on other nodes.

This option does not apply to topics because topic messages are always routed through the Enterprise Message Service server. Since topic messages are always go through Enterprise Message Service server, multiple deployments of the provider wired a topic are always automatically load balanced.

Default: Yes.

Table 52 Service Assembly Reference (Cont’d)

Field Description



Updating a Service Assembly ArchiveOften you need to update the archive file of a service assembly after it has been deployed. For example, during iterative development you might need to fix a defect in a component implementation.

When you update a service assembly archive file the service assembly configuration is retained. Saving the configuration allows you to repeatedly update a service assembly while ensuring that configuration is performed once. To update a service assembly archive:

1. In the Service Assemblies table, click the service assembly.

2. Click the Stop button and then click the Undeploy button.


4. Click the Edit button at the right of the Service Assemblies table.

5. In the General Information area, click the Update button next to the Archive File field. A browse dialog displays.

a. Click Browse and navigate to the directory containing the updated archive file.

b. Select the archive file and click OK.

1. The status is a link you can click to display a screen with information about the error. You can drilldown to the Service Unit node mapping level to see the details.

Figure 16 Service Assembly State

Not DeployedUpload

Deploy [success] Deployed

Deployed with Errors

Deploy [failure] Delete

Start [failure]

RunningStart [success]

Stop

Running with Errors

Undeploy

Undeployed with Errors

Undeploy [failure]

Out of SyncRedeployable

Change Configuration Change Configuration

Undeploy Change Node Mapping

Change Node Mapping Redeploy

Redeploy



Downloading a Service Assembly ArchiveYou can download the archive file of any service assembly you have uploaded. The downloaded archive is in its original form; it does not contain any service assembly configuration data. To download a service assembly archive:

1. In the Service Assemblies table, click the service assembly.


3. In the General Information area, click the link in the value of the Archive File field. The browser displays a file save dialog.

4. Specify the location to save the file and exit the dialog.

Updating Service AssembliesWhen you update a service assembly, you must propagate the changes to the nodes on which the assembly is deployed. Table 53 shows the various types of changes you can make to the service assembly, and the actions you must perform to update the service assembly on the nodes given the state of the service assembly when the changes were made. For example, if you remove a node mapping when the service assembly status is Deployed, you must first undeploy and then deploy the service assembly

Table 53 Actions and Service Assembly Status Changes

ActionService Assembly Status

Deployed or Deployed with Errors

Running or Running with Errors

Update service assembly Undeploy, Deploy Stop, Undeploy, Deploy, Start

Add mapping from one or more service units to one or more nodes

Redeploy. The Redeploy action deploys the service units on the newly added nodes.

Redeploy. The redeploy action deploys and starts the service units on the newly added nodes and has no effect on the service units on existing nodes.

Remove mapping between one or more service units and one or more nodes

Redeploy. The action undeploys the service units from the removed nodes.

Redeploy. The action undeploys the service units from the removed nodes.



Undeploying Service AssembliesWhen you undeploy a service assembly, the configuration values you set up are retained in the database. You can redeploy with the same configuration, or you can edit the settings and then redeploy.

To undeploy service assemblies, in the Service Assemblies table, select one or more service assemblies and click Undeploy. The status changes to Not Deployed.

When you initiate the undeploy action on a running service assembly, it is stopped and then it is undeployed.

Deleting Service AssembliesWhen you delete a service assembly, the service assembly archive and all the configuration values are removed from the database.

In general, before deleting a service assembly, you must stop and undeploy the assembly. However, if you are unable to stop and undeploy the assembly you can force it to be deleted by checking the Force delete the service assembly if necessary checkbox that is displayed in the delete confirmation dialog. When you confirm the delete action on the service assembly, it is stopped, then undeployed, and then it is deleted.

To delete services assemblies:


2. Click Delete. A confirmation dialog is displayed.

Update:

• Expose Endpoints and Prefer Local Providers

• Topic queue

• Service queue

• Shared resource profile to shared resource mapping

• Substitution variable

Undeploy, Deploy Stop, Undeploy, Deploy, Start

Table 53 Actions and Service Assembly Status Changes (Cont’d)

ActionService Assembly Status

Deployed or Deployed with Errors

Running or Running with Errors



3. Click Yes to confirm the deletion.


Working with Service Units | 233

Working with Service Units

To view the service units in a service assembly:


2. Click the Service Units button. The service units in the service assembly will display in the Service Units table whose columns are described in Table 54.

Service Units Table Reference

Service UnitsTo view the properties of a service unit, click the service unit in the Service Units table. The service unit’s properties are displayed in two tabs:

• Node Mapping Tab on page 233

• Substitution Variables Tab on page 235

Node Mapping Tab

The contents of the Node Mapping tab varies depending on whether you are in View or Edit mode.

In View mode, the Node Mapping tab contains a list of mapped nodes, which are the nodes to which the service unit is deployed when the service assembly containing the service unit is deployed.

In Edit mode, the Node Mapping tab contains a list of available nodes, that is, nodes running containers whose type matches the service unit, and a list of mapped nodes.

Mapping Service Units to Nodes

A service unit specifies a container type and a compatible version range. For

Table 54 Service Units Table Reference

Column Description

Name The name of the service unit.

Version The version of the service unit.

Type The type of the service unit.



example Java container, versions 1.0.0 to 2.0.0. You map a service unit to a node. In case of multiple container software versions, the highest version that falls within the specified compatible range is used.

If a service unit is deployed to multiple nodes that host different versions of a container, the highest version of a container is picked for deployment and may resolve to different versions on different nodes. For example, suppose node N1 has two Java containers with different versions 1.0.0 and 2.0.0, and node N2 has a 1.0.0 Java container. A service unit deployed on both N1 and N2 is deployed to Java 2.0.0 on N1 and Java 1.0.0 on N2.

To map service units to nodes:

1. Click the Service Units button.

2. In the Service Units table, select the service unit.

3. In the Node Mapping tab, select the nodes that you want to deploy the service unit to in the Available Nodes list, and click the right arrow button or drag the nodes from the Available to Selected Nodes list. The nodes will appear in the Mapped Nodes list.

If the nodes you want to deploy to do not appear in the table, follow the procedure in Adding Nodes to the Mapped Nodes List on page 234 to add the nodes.

4. Click Save. The mapped nodes will appear in the Mapped Nodes table, and a mapped icon will display next to the service unit in the Service Units table.

Adding Nodes to the Mapped Nodes List

To add nodes to the Mapped Nodes list on the Node Mapping tab:


2. Select the nodes that you want to deploy to from the Available Nodes list. If the nodes that you want to deploy to do not appear in the table, follow the procedure in Creating a Node on page 192 to add the node to the environment.

3. Click the right arrow button. The selected nodes are moved from the Mapped Nodes to the Mapped Nodes list.

4. Click Save.

Removing Nodes from the Mapped Nodes List

To remove nodes from the Mapped Nodes list on the Node Mapping tab:



Working with Service Units | 235

2. Select the nodes that you want to remove from the Mapped Nodes list and click the left arrow button. The selected nodes are moved from the Mapped Nodes to the Available Nodes list.

3. Click Save.

Mapped Nodes Reference

Substitution Variables Tab

The Substitution Variables tab allows you to specify the value of a service unit’s substitution variables.

When you edit any substitution variable in a service unit, you break the connection between all the service unit’s substitution variables and those maintained at the service assembly level. Subsequent changes made at the service assembly level do not affect the service unit’s substitution variables.

Substitution Variables Reference

Table 55 Mapped Nodes Reference

Column Description

Node Name The name of the node on which the service unit is deployed.

Status The status of the node.

Machine The machine on which the node is running.

Table 56 Substitution Variables

Column Descriptions

Name The name of the variable you want to set, including the path to the variable if it is contained in a folder. The folder path acts like a namespace allowing use of different sets of substitution variables.

Value The value for the substitution variable. Click Edit to change any values as needed. The type of the value you enter is validated when you save.



Mapping Shared Resource Profiles to Shared Resources

A shared resource profile specifies the kind of physical resource needed by services in the service unit. Shared resource profiles are defined at design time and packaged in the service assembly archive. Before deployment you must map each shared resource profile to a shared resource available in the node that the service unit is mapped to. To map a shared resource profile to a shared resource:



3. Click the Shared Resources link.

4. Click the Edit button over the Shared Resource Profiles table.

5. In the row containing the shared resource profile to map, select the shared resource in the drop-down list in the Shared Resources column.

6. Click Save. If a shared resource does not yet exist on the nodes to which you are deploying the service assembly, the Create New Shared Resource dialog is displayed where you can choose to install the shared resource on the nodes.

7. Click Create to install the shared resource on the nodes. A dialog is displayed the results of the create operation. Click Close to dismiss the dialog.

Shared Resource Profiles Reference

Table 57 Shared Resource Profiles Reference

Column Description

Name The name of the shared resource profile.

Parent Name The name of the composite element that references the profile.

The combination of service unit, profile name, and composite element name identifies each profile uniquely.

Parent Type The type of the composite element that references the profile.

Shared Resource Name of the shared resource that has been mapped to this profile.


Working with Topics | 237

Working with Topics

Topics are implemented by topics in the Enterprise Message Service server. Topics are automatically mapped to default topic names. To edit a topic name:

1. In the Service Assemblies table, select a service assembly.

2. Click the Topics link.

3. Click the Edit button above the Topics table.

4. In the row containing the topic you want to modify, edit the value in the Physical Name column.

5. Click Save.

Topics Reference

Topic subscribers get messages sent to a topic from a queue. A bridge from topic to the queue must be created in the Enterprise Message Service server. If you specify a username and password in the messaging server configuration (see Adding a Messaging Server to an Environment on page 179), then Messaging Bus automatically creates the bridge from topic to queue. Otherwise you must manually create the bridge. For information on how to create a bridge, see the Enterprise Message Service documentation.

Table 58 Topics Reference

Column Description

Name The name of the topic.

MEP The message exchange pattern supported by the topic.

Port Type The port type supported by the topic.

Physical Name The topic name that implements the topic in the Enterprise Message Service server.




Substitution variables specify constants that can be used throughout the service assembly. See Substitution Variables Tab on page 235 for the relationship between substitution variables specified at the service assembly and service unit levels.

Table 59 Substitution Variables Reference

Column Description

Name The name of the variable you want to set, including the path to the variable if it is contained in a folder. The folder path acts like a namespace allowing use of different sets of substitution variables.

Value The value for the substitution variable. Click Edit to change any values as needed. The data type of the values you enter is validated when you save.


Working with Logging Configurations | 239

Working with Logging Configurations

See Working with Logging Configurations on page 310.



Working with Services

Services are implemented by queues in the Enterprise Message Service server. Services are automatically mapped to default queue names.

To edit the queue names used by a service:

1. In the Service Assemblies table, select a service assembly.

2. Click the Services link.

3. Click the Edit button above the Services table.

4. In the row containing the queue you want to modify, edit the value in the Queue column.

5. Click Save.

Services Reference

Table 60 Services Reference

Column Description

Name The name of the service.

Resource Type The type of the service. Composite Service, Component, or Composite Reference.

Queue The name of the internal Messaging Bus queue to which messages for the service are sent.


| 241

Chapter 9 Monitoring Infrastructure and Services

This chapter describes how to monitor the performance of the ActiveMatrix infrastructure and the services running on the infrastructure. It provides various views such as dashboard, infrastructure, service, deployment, and log view.

Topics

• Overview, page 242

• Enabling Monitoring, page 244

• Accessing the Monitor & Manage Perspective, page 246

• Dashboard View, page 247

• Infrastructure View, page 250

• Service View, page 261

• Integrated Service View, page 264

• Service Instance View, page 280

• Deployment View, page 285

• Browse Mode, page 291


242 | Chapter 9 Monitoring Infrastructure and Services

Overview

TIBCO ActiveMatrix Administrator not only allows you to configure and deploy applications, but also lets you monitor and manage the deployed applications. Monitoring the system performance is not a one time activity but needs to be performed on a day-to-day basis. Monitoring is performed in the Monitor & Manage perspective.

This chapter explains how you can monitor the overall health and performance of the infrastructure, applications, and services. You can monitor performance at various levels such as environment, machine, node, service assembly, and service units. Some content-based metrics are used to measure the service performance, availability of services, service usage, and the number of successful to faulty service responses. These metrics provide real-time values by fetching data every minute and updating the values of the metrics. This real time data is then displayed in a web-based dashboard provided with pre-defined views and visual alerts.

Using the Monitor & Manage perspective, you can get answers to the following questions:

• What is the overall health of my system?

• Which nodes or services are currently down?

• What is the performance of machines that host my environment?

• Which services are deployed in a service assembly?

• Which service instances are running on the given environments, nodes, and machines?

• Which are the top 20 most used services?

• Which are the top 20 faulting services?

• What is the performance of a service based on interface, operation, node, consumer, and provider?

If needed, you can take corrective actions to get the system back to normal. You can start and stop nodes and service assemblies.

ViewsThe Monitor & Manage perspective provides the following views:

• Dashboard View View summary information about the overall health of the services and system.


Overview | 243

• Infrastructure View Monitor environments, machines, nodes, containers, shared resources, and service instances running on nodes.

• Service View Search for services along with their details such as service provider and consumer. You can search for a specific service and get details of a service instance.

• Deployment View View environments, service assemblies, service units, and services in service units.

• Log View Build log queries and view log entries.



Enabling Monitoring

You can view metrics data in the Monitor & Manage perspective only if you enable monitoring. To enable monitoring:


2. Click the Administrator Cluster link.

3. Click the Monitoring Configuration link.


5. Configure the fields according to the descriptions in Table 61.

6. Click Save. When you save a Monitoring Configuration, all ActiveMatrix Administrator servers and all runtime nodes are notified of the new configuration.

Monitoring Configuration ReferenceThe Monitoring Configuration specifies whether monitoring is enabled, the messaging channel on which monitoring messages are received from nodes, and which ActiveMatrix Administrator server in a cluster is responsible for managing monitoring messages.

In addition to configuring the monitoring service, you must also configure at least one node in an environment before any data is displayed in any views of the Monitor & Manage perspective.

Table 61 Monitoring Configuration

Field Description

Enable Monitoring?

Determines whether monitoring is enabled. Enabling monitoring starts the Metrics Manager engine and starts the service probes running on nodes sending messages.

The Metrics Manager plug-in (see Plug-ins on page 163) needs to be running to either enable or disable monitoring. Stopping the Metrics Manager plug-in without disabling monitoring stops the Metrics Manager engine but nodes continue to send messages on the JMS connection. Messages accumulate until the Metrics Manager plug-in is restarted.


Enabling Monitoring | 245

JMS Connection The JMS connection on which all the ActiveMatrix Administrator servers in a cluster receive metrics information. A drop-down list containing existing JMS shared resource definitions.

Before selecting a connection you must configure a JMS shared resource definition as described in JMS Shared Resource Definition Reference on page 127. If the Connection Type of the JMS shared resource is JNDI you must set the Connection Factory field to QueueConnectionFactory. To configure SSL connections to the JMS server set the Connection Factory field to SSLQueueConnectionFactory.

By default, when SSL is configured via JNDI the monitoring system assumes that a topic connection factory with the name SSLTopicConnectionFactory exists on the JMS server. In the case of non-SSL, the default topic connection factory name is TopicConnectionFactory. If you have configured the JMS server with a different topic connection factory name, you can specify the factory name as a JNDI property named com.tibco.tibjms.naming.topic_connection_factory.

Selecting a JMS shared resource restarts the Metrics Manager engine with the new JMS configuration.

If you change the JMS shared resource definition referenced by this field you must restart the Metrics Manager plug-in. See Plug-ins on page 163.

Metrics Manager Server

The ActiveMatrix Administrator server within the cluster responsible for managing the flow of metrics information from nodes. A drop-down list containing the all the servers in the cluster.

Selecting a Metrics Manager server stops the currently running Metrics Manager engine and starts a new Metrics Manager engine on a different ActiveMatrix Administrator server.

Metrics Manager processes metrics messages from service probes on nodes and aggregates them into a monitoring model. Periodically (once in 5 minutes) Metrics Manager persists changed objects to a database. The Monitoring and Management perspective queries this database for metrics.

If the ActiveMatrix Administrator server that is configured as the Metrics Manager becomes unavailable, you must select a new Metrics Manager. While the Metrics Manager is unavailable, nodes keep collecting statistics. The messages are delivered to the JMS connection. When a new Metrics Manager becomes active it immediately starts processing the stored messages.

Table 61 Monitoring Configuration (Cont’d)

Field Description



Accessing the Monitor & Manage Perspective

To view the monitoring and management screens:

1. Select Monitor & Manage from the Perspective drop-down list.

Select view 2. Select a view from the view selection bar:

— Dashboard Observe the overall health and status of the system or the selected environment. See Dashboard View on page 247.

— Infrastructure Monitor environments, machines, and nodes. See Infrastructure View on page 250.

— Service Search for services. See Service View on page 261.

— Deployment Display deployment data in an environment. You can check details about the service assemblies and service units belonging to the environment. See Deployment View on page 285.

— Log Build log queries and view log entries. For details on this view, see Using the Log Viewer on page 318.

Selectenvironment

3. If available for the selected view, select the name of the environment from the Environment drop-down list to view metrics data related to a specific environment. Only the system and service metrics belonging to that environment are displayed.

Select period 4. By default, you can view the metrics data for the past 24 hours. To change the period for monitoring, select any of the following options from the Period drop-down list:

— Past Hour Provides metrics for the past hour.

— Past 24 Hours Provides metrics for the past 24 hours.

— Past 7 Days Provides metrics for the past 7 days.

— Since Started Provides metrics since the component was started or monitoring was enabled.

Metrics are displayed based on the period that you select.


Dashboard View | 247

Dashboard View

When you select the Monitor & Manage perspective, you enter in the Dashboard view by default. The dashboard is an operational view of services and is updated automatically without intervention at regular frequency. The Dashboard view displays the overall health of the system including a summary of service and system performance.

The Dashboard view is divided into two areas:

• Service Metrics on page 247

• System Metrics on page 248

Service MetricsThe service metrics area allows you to view the services with respect to the specified period.

Top 20 Hits

The top 20 services that were the most active with respect to the specified period are displayed in this table. The columns in the table specify the following details about a service.

Table 62 Top 20 Hits

Column Description

Name The service name. You can click the service name to view the details of the service in the Service view as described in Service View on page 261.

Hits Number of times the service has been invoked. A graphical representation of the hit history over the specified time period is displayed as a bar graph next to the Hits value.



Top 20 Faults

The top 20 services that were failing the most with respect to the specified period are displayed in this table. The columns in the table specify the following details about a service.

System MetricsThe system metrics area allows you to view machine and node details with respect to the specified environment.

Machines

The Machines table displays information about machines enabled in the selected environment. The properties of the features on each machine are described by the columns listed in the following table.

Table 63 Top 20 Faults

Column Description

Name The service name. You can click the service name to view the details of the service in the Service view as described in Service View on page 261.

Status The current status of the service, either Stopped or Running.

Faults Number of times the service failed to fulfill the request.

By default only system faults are logged. To enable declared fault logging, set the property java.property.monitormanage.LoggingDeclaredFaults to true in a node TRA file. This property does not affect the behavior if it is not set, or if it is set to false.

To exclude counting declared faults, set the property java.property.monitormanage.FaultCountExcludeDeclaredFaults to true in the ActiveMatrix Administrator server TRA file.

Table 64 Machines

Column Description

Hostname The name of the machine. Hostname is a link that you can click to see the details of the machine. After you click Hostname, the details are displayed as described in Machine View on page 253.

OS The details of the operating system available on the machine.


Dashboard View | 249

Nodes

The Nodes table displays information about the nodes added in the selected environment. The properties of each node are described by the columns described in Table 65.

Memory The amount of memory consumed by the services running on the machine against the available memory is displayed as a bar graph. The bar signifies the amount of memory in use. The green, yellow, and red values indicate the amount of memory consumed by the machine (Green = 0-50%, Yellow = 51-75%, and Red = 76-100%). For example, if the bar becomes red, it signifies that the memory consumption is very high and it may degrade the system performance.

Table 64 Machines

Column Description

Table 65 Nodes

Column Description

Name The name of the node. Name is a link that you can click to see the details of the node. After you click Name, the details are displayed as described in the Node View on page 256.

Status The current status of the node, either Installed/Stopped, Running, Starting, StartFailed.

# of Services Number of services deployed on the node.

Faults/Successes The number of fault to successful responses of services on a node.

JVM Memory The JVM memory consumed by various services from the total available memory is displayed as a bar graph in Megabytes. The bar signifies the amount of memory in use. The green, yellow, and red values indicate the amount of memory consumed by the machine (Green = 0-50%, Yellow = 51-75%, and Red = 76-100%). For example, the number 68/120 specifies that 68 MB is in use from the total 120 MB available.

Hostname The name of the machine on which the node is running. Hostname is a link that you can click to see the details of the machine. After you click Hostname, the details are displayed as described in Machine View on page 253.



Infrastructure View

The Infrastructure view allows you to see the status of machines and nodes within an environment. You can navigate to the Infrastructure view by using either of the following ways:

• Click the Infrastructure link.

• In Browse mode (see Browse Mode on page 291), click Infrastructure, select a value in the Environments, Machines, or Node columns, and then click View Environment, View Machine, or View Node.

The Infrastructure view consists of three subviews:

• Environment View on page 250

• Machine View on page 253

• Node View on page 256

Environment ViewIn the top area, the following details are displayed:

• The name of the selected environment.

• Total number of active nodes against the total number of available nodes in the selected environment.

• Total number of active services against the total number of available services in the selected environment.

Machines

The Machines table displays details of the machines enabled in the selected environment. The following machine properties are displayed as columns in the table.

Table 66 Machines

Column Description

Hostname The name of the machine. Hostname is a link that you can click to see the details of the machine. After you click Hostname, the details are displayed as described in Machine View on page 253.


Infrastructure View | 251

Nodes

The Nodes table displays the details of the nodes in the selected environment. The following properties of nodes are displayed as columns in the table.

OS The operating system running on the machine.

Memory The amount of memory in use. The bar signifies the amount of memory in use. The green, yellow, and red values indicate the amount of memory consumed on the machine (Green = 0-50%, Yellow = 51-75%, and Red = 76-100%).

The memory usage is displayed as a bar graph where the used memory is displayed as a yellow bar against the total available memory. If the memory usage is low, the yellow bar turns green. However, if the memory usage is too high, the yellow bar turns red.

Table 66 Machines (Cont’d)

Column Description

Table 67 Nodes

Column Description

Name The name of the node. Name is a link that you can click to see the details of the node. After you click Name, the details are displayed as described in the Node View on page 256.
















• Unknown The status of the node cannot be determined.

# of Services The number of services deployed on the node.

# of Containers The number of containers on the node.

Uptime The amount of time that has elapsed since the node was started. The uptime is displayed in terms of days, hours, and minutes.

CPU Time The amount of CPU time consumed by the node since the node was started. The CPU time is displayed in terms of days, hours, and minutes.

Faults/Successes The number of fault to successful responses of services on a node.

Table 67 Nodes (Cont’d)

Column Description



Machine ViewTo open the Machine view, click a machine name in the Machines table. The Machine view provides details of a particular machine and information about the nodes running in various environments on that machine.

View Logs

Select the View Logs button to open the View Logs dialog where you choose the logs to view for the selected element. See Using the Log Viewer on page 318 for details.

Overview

The overview contains the following information about the selected machine.

JVM Memory The amount of JVM used by the node against the total available memory (in use/Total MB) is displayed as a bar graph. The bar signifies the amount of memory in use. The green, yellow, and red values indicate the amount of memory consumed by the machine (Green = 0-50%, Yellow = 51-75%, and Red = 76 - 100%).

Hostname The name of the machine on which the node is running. You can click the hostname to get more details about the machine as described in Machine View.



Column Description

Table 68 Machine Details

Metric Description


OS The operating system running on the machine.

TIBCO Home The path where TIBCO products are installed on the machine.



Nodes

The Nodes table displays all the nodes configured on the specified machine in different environments. The following details of each node are displayed as columns in this table.

Memory The amount of memory consumed by the services running on the machine against the available memory is displayed as a bar graph. The bar signifies the amount of memory in use. The green, yellow, and red values indicate the amount of memory consumed by the machine (Green = 0-50%, Yellow = 51-75%, and Red = 76 - 100%).

The green bar signifies the amount of memory in use. If the bar becomes orange, it signifies that the memory consumption is very high and it may degrade the system performance.

Status The status of the machine. Possible values are:


• Bound | Not Available The machine has been bound to the ActiveMatrix Administrator cluster but is not available.

• Agent Down The machine is not accessible. This could be because it stopped or because the network connection failed.

Table 68 Machine Details (Cont’d)

Metric Description

Table 69 Nodes

Column Description

Name The names of the nodes added to different environments on the selected machine are displayed. You can click the node name to get details of the node as described in Node View on page 256.
















Unknown The status of the node cannot be determined.

# of Services Total number of services deployed on the node.

# of Containers Total number of containers activated on the node.

Uptime The amount of time that has elapsed since the node was installed. The uptime is displayed in terms of days, hours, and minutes.

CPU Time The amount of CPU time consumed by the nodes running on that machine. The CPU time is displayed in terms of days, hours, and minutes.

Faults/Successes The number of fault to successful responses.


Column Description



Node ViewTo display the Node view, click a node name in the Nodes table. The Node view provides overview and details about containers, shared resources, and service instances in a tabular format.

The Node view is divided into the following areas:

• Node Trail on page 257

• Overview on page 257

• Containers on page 258

• Shared Resources on page 259

• Service Instances on page 259

JVM Memory The amount of JVM memory used by the node against the total available memory is displayed as a bar graph. The bar signifies the amount of memory in use. The green, yellow, and red values indicate the amount of memory consumed by the machine (Green = 0-50%, Yellow = 51-75%, and Red = 76 - 100%).

Hostname The name of the machine on which the node is running. You can click the hostname to get more details about the machine as described in Machine View on page 253.



Column Description



Node Trail

The node trail is displayed in the top area as shown:

Overview

Below the node trail, the node name and its status is displayed. You can start and stop the node using the Start or Stop button. In either case, click the Refresh icon

located at the top right of the table until the node’s status changes to Running or Installed/Stopped.

The View Logs button opens the View Logs dialog where you choose the logs to view for the selected element.

The following details about the selected node are displayed in the overview section.

Table 70 Node Trail

Column Description

envName envName is the name of environment containing the node.

When you click envName, it opens the Environment subview of the Deployment view.

Physical Displays the physical trail to the node. The trail shows where the node was physically installed as follows:

PHYSICAL machineName

where machineName is the name of the machine.

When you click machineName, it opens the Machine subview of the Infrastructure view.

Table 71 Node Details

Metric Description

Name The name of the node.

Description The description of the node.

Date Installed The date and time when the node was installed on the machine.



Containers

The Containers table displays the containers enabled on the selected node. The following properties of containers are displayed as columns of this table.

Installed By The name of the person who installed the node.

Messaging Server

The messaging server used for this node’s transport requirements. Each node is associated with one messaging server.

Start Date The date and time when the node was started.

Uptime The amount of time that has elapsed since the node was started.

CPU Time The amount of CPU time consumed by the node since the node was started.

JVM Memory The amount of JVM memory consumed by the node against the total amount of memory available is displayed along with a bar graph. The bar signifies the amount of memory in use. The green, yellow, and red values indicate the amount of memory consumed by the machine (Green = 0-50%, Yellow = 51-75%, and Red = 76 - 100%).

Availability Time Period The amount of time when the node was down against the time when the node was up and running (that is, downtime versus uptime percentage) in the selected period.

Since Started The amount of time when the node was down against the time when the node was up and running (that is, downtime versus uptime percentage) since the node was started.

Faults Time Period The number of faults encountered in the selected period.

Since Started The number of faults encountered since the node was started.

Successes Time Period The number of successful responses in the selected period.

Since Started The number of successful responses since the node was started.

Table 71 Node Details

Metric Description

Table 72 Containers

Column Description

Name The name of the container running on the selected node.

Version The version of the container.



Shared Resources

The Shared Resources table displays the shared resources available on the selected node.

Service Instances

The Service Instances table displays the services running on the selected node. In the top bar right corner, the total number of services displayed in the table against the total number of services available is displayed. Table 74 describes the properties of the services.

To limit the number of services, use the Filter option on the top bar. You can set the filter criteria based on the number Hits, Fault/Success Ratio, and Implementation type. For information on how to set the filter criteria, see Specify the service filter on page 262.

Table 73 Shared Resources

Column Description

Name The name of the shared resource available on the selected node.

Type The type of the shared resource: HTTP, JDBC, JMS, JNDI, Rendezvous, or SSL.

Table 74 Service Instances

Column Description

Name The name of the service. You can click Name to get details about the service as described in Service Instance View on page 280.

Version The version of the service.

Container Type The type of service implementation in a container such as TIBCO ActiveMatrix Java, SOAP, JMS, Mediation, Adapter, and .NET.

Resource Type The type of resource:

• Composite Service Specifies that this service belongs to an outside composite.

• Composite Reference Specifies that this service is not provided by the same composite and is referenced externally to services provided by an outside composite.

• Component Specifies the name of the component to which the service belongs in the same composite.



Start Date The date the service was started.

Uptime The amount of time that has elapsed since the service was started. The uptime is displayed in terms of days, hours, and minutes.

Hits The number of service invocations since the service was started or the time period was set, whichever is later.

Fault/Successes Number of requests that resulted in a fault message/Number of request messages that arrived at the endpoint.

Throughput The number of service invocations per second.

Responses per second during the interval; calculated as response count/interval.

Average Response Time The mean response time (in milliseconds) of all successful responses to request messages during the interval.

Table 74 Service Instances (Cont’d)

Column Description


Service View | 261

Service View

The Service view allows you to search for and see a summary of the status of services. Detailed information about services can be viewed in one of the following subviews:

• Integrated Service View on page 264 Provides details about services.

• Service Instance View on page 280 Provides details about service instances.

To understand the difference between services and service instances, consider the configuration illustrated in Figure 20. In this configuration there are three services—S1, S2, and S3—whose metrics you would view in the Integrated Service view.

S1and S2 each have two service instances: S1 has service instances SI1a and SI2b and S2 has service instances SI2a and SI2b. Service S3 has only one instance, SI3. You view the metrics of service instances—SI1a, SI1b, SI2a, SI2b, and SI3—in the Service Instance view.

For absolute metrics, the value of a service metric is simply the sum of the values of that metric for all the service’s instances. For average metrics, the value of a service metric is the average over all the service instances.

Figure 20 Services and Service Instances

Node 1

SI1a

Node 2

SI1b

S2S1

Node 3

SI2b

S3

SI3SI2a



Searching for ServicesTo search for services:

Specify searchcriteria

1. Specify zero or more of the search criteria fields:

— Name The name of the service you are searching for. This is a matching string search, so no wild cards are allowed. For example, if you enter Ser for the name, all service names beginning with Ser are displayed, if other criteria are met.

— Resource Type The resource type. By default, All Types is selected. You can select Composite Service, Component, or Composite Reference from the drop-down list.

— Interface Name The name of interface. The names of all the services implementing the specified interface are displayed.

— Namespace The service namespace. The names of all the services identified with the specified namespace are displayed.

If you specify no fields, all services are returned.

2. Click Search to get results matching the search criteria. The services matching the specified search criteria are displayed in the Services table in the search results area. Table 75 on page 263 describes the properties of services.

Specify theservice filter

3. You can filter the services further by defining filter criteria. Click Filter on the to display the filter criteria. The area expands and displays the existing filter criteria.

The filter criteria are:

— Hits Set the arrows on the slider to define a range for filtering the services based on the number of hits. The endpoints of the slider are the minimum and maximum values of hits from the service results. Only the services with hits within the specified range are displayed in the results area.

— Faults/Hits Ratio Set the arrows on the slider to define a range for filtering the services based on the Fault/Hits ratio. The endpoints of the slider are the minimum and maximum values of the Fault/Hits ratio based on the service results. Only the services with ratio within the specified range are displayed in the results area.

— Container Type Select the services of specific implementation type from the drop-down list. The default is All Types. Based on the Service Instances displayed in the table, the container types are displayed in the drop-down.


Service View | 263

Click the Refresh icon to display the results based on the filter criteria. To discard the filter criteria and display all the services, click the Reset button.

By default, all the results are sorted by service name, in ascending alphabetical order. If there are too many results, the first 500 matching results are displayed.

Table 75 Services

Column Description

Name The name of the service that satisfies the search criteria. Click the service name to get details about the service as described in Integrated Service View on page 264.

Version The service version.

Container Type The type of the service implementation. The types can be TIBCO ActiveMatrix Java, SOAP, JMS, Mediation, Adapter, and .NET.

Resource Type The type of resource:

• Composite Service Specifies that this service belongs to an outside composite.

• Composite Reference Specifies that this service is not provided by the same composite and is referenced externally to services provided by an outside composite.

• Component Specifies the name of the component to which the service belongs in the same composite.

Start Date The date and time when the service was started.


Hits The number of times the service has been invoked during the selected period.

Faults/Successes The ratio of number of failed hits to the number of successful hits for the selected service for the selected period.

Throughput (requests/minute)

The performance data such as the average number of requests processed per minute for the selected period. The data changes for the selected time period.

Average Response Time

The average amount of time in milliseconds between receiving a request and returning a response over the selected period.



Integrated Service View

The Integrated Service view provides a view of services. You navigate to the Integrated Service view as follows:

• Click Dashboard and select a service name link from the Service Metrics tables.

• Click Service and specify a Search Criteria to view only the required services. Click the service name in the Services table from the displayed results in the search results area.

• In Browse mode (see Browse Mode on page 291):

— Click Deployment and select a value in the Environments and Service Assemblies columns. After you select a service assembly, click the View Services On Service Assembly button.

— Click Deployment and select a value in the Environments, Service Assemblies, and Service Units columns. After you select a service unit, click the View Services On Service Unit button.

The Integrated Service view is divided into the following areas:

• Service Trail on page 265

• Service Details on page 265

• Tabbed Notebook:

— Overview on page 266

— Provides & Consumes on page 268

— Deployment Details on page 273

— UDDI Publishing on page 275


Integrated Service View | 265

Service TrailThe service trail is provided in the top area:

The name of the service and number of nodes the service is deployed to are also displayed.

Service DetailsThe top section displays the service name with number of nodes that the service is deployed to. For example, myService on 10 Nodes.

View Logs

The View Logs button opens the View Logs dialog where you choose the logs to view for the selected element. See Using the Log Viewer on page 318 for details.

Table 76 Service Trail

Metric Description



Logical Displays the logical trail to the service. The trail shows how the service was deployed.

LOGICAL serviceAssemblyName > serviceUnitName

where,

• serviceAssemblyName is the service assembly with which this service is associated.

• serviceUnitName is the service unit with which this service is associated.

When you click a name, it opens the respective subview of the Deployment view.



Generate WSDL

The Generate WSDL button is displayed if the service is a composite service. You cannot generate WSDL for a component service or a composite reference. Concrete, not abstract, WSDL is generated.

When you click the button, the WSDL file is displayed in a dialog. To download the WSDL file, click the Click to download file link. You are offered the option to save a file named service.wsdl or display the file.

Click the Cancel button to dismiss the dialog.

OverviewThe Overview tab provides information about the service such as name, description, number of requests, and performance data.

Faults/Successes

The number of failed hits to successful hits for the selected period is displayed as a pie chart. The available periods are Time Period or Since Started.

Table 77 Services Details

Metric Description

Name The name of the service.

Description The description of the service.

Implementation The type of the service implementation: TIBCO ActiveMatrix Java, SOAP, JMS, Mediation, Adapter, and .NET.

Namespace The namespace that identifies the web service that implements the service.



The data on the graph is displayed in color where green represents successful hits and red represents failed hits. Moving the cursor on the graph opens a pop-up windows that provides details such as Successful Requests % and Faults %.

Total Requests

A graph, plotted between the number of requests against the selected period, is displayed and updated in real time. The total number of requests, categorized into successes and faults, are plotted on the Y-axis. The selected period is displayed on the X-axis. Note that the graph is to scale.

The data in the graph builds from left to right in real time and moves relative to the selected period. The values of the metrics are updated every minute and displayed in the graph. The graph in green displays the number of successful hits and the graph in red displays the number of faults at the given time. Selecting a location on the graph opens a pop-up window that provides details such as date and time, number of faults, number of successes, and response time.

A bar graph below the Total Requests graph shows the service response time in milliseconds. The X-axis represents the selected period and the Y-axis displays the response time in milliseconds.

Performance

The Performance table provides details about the service performance. Table 78 describes the details about a service performance.

Table 78 Performance

Metric Description

Start Date The date and time when the service was started.

Availability The amount of time when the service was down against the time when the service was up and running (that is, downtime versus uptime percentage). The percentage is displayed in color: green indicates a percentage in the range 51-100% and red represents 0 – 50%.




Provides & ConsumesThe Provides & Consumes tab display details on the interfaces provided and consumed by the service. The tables that appear depend on the type of the service:

• Component on page 269

• Composite Service on page 270

• Composite Reference on page 271


The performance data for the selected period. The data changes for the type of period:

• Time Period The average number of requests processed per minute in the selected time period.

• Since Started The total number of requests processed by the service per minute. This is the average per minute since the start date and time.


The average amount of time in milliseconds between receiving a request and returning a response over the selected period:

• Time Period The average request response time in milliseconds. This is the average over the selected period.

• Since Started The average request response time in milliseconds. This is the average since the start date and time.

Total Requests The total number of service requests received in the selected period and since the service was started. If the period is already set to Since Started, the column Since Started does not appear in the Performance table.

Table 78 Performance (Cont’d)

Metric Description



Component

Provides

The Provides table gives details on the provided interface. Table 79 describes the details about the interfaces.

Interface Consumed By

The services consumed by the interface selected in the Provides table are displayed in the Interface Consumed By table. Table 80 describes the details about the services.

Table 79 Provides

Column Description

Interface Name The name of the interface. The names are sorted in ascending alphabetical order.

Port Type The port type supported by the service.

Fault/Success The ratio of faults to successful hits for the selected period.

Hits The number of times the service is invoked for the selected period.

Table 80 Interface Consumed By

Column Description

Name The names of the services. The services are sorted in ascending alphabetical order. Click the service to see information about the service as described in the Service Instance View, page 280.

Type The composite element type of the consuming service.





Consumes

The Consumes table provides details about the interfaces that are implemented by a consumed service. Table 81 describes the details about the consumer interface.

Interface Invokes

The services consumed by the interface selected in the Consumes table are displayed in the Interface Invokes table. Table 82 describes the details about the services.

Composite Service

A composite service is a provider and provides a binding URL for external access. You can generate a concrete WSDL file for a composite service.

External Endpoint

The provided service can be accessed from external services using an external endpoint, which is the binding URL provided by the composite service.

Table 81 Consumes

Column Description

Interface Name The name of the interface implemented by the consumed service. The names appear in ascending order.

Port Type The port type supported by the consumed service.

Fault/Success The ratio of failed to successful hits for the selected period.


Table 82 Interface Invokes

Column Description

Name The name of the service. Click the service to see information about the service as described in the Service Instance View, page 280.

Type The composite element type of the consumed service.





Consumes

The Consumes table lists the services the composite service is consuming. Table 83 describes the details of the services.

Interface Invokes

The services invoked by the interface selected in the Consumes table are displayed in the Interface Invokes table. Table 84 describes the details about the services.

Composite Reference

A composite reference is a provider and consumes an external binding URL.

Table 83 Composite Service Consumes

Column Description

Interface Name The name of the service being consumed by the service. The names appear in ascending order.

Port Type The port type being consumed by the service.


Hits The number of time the service is invoked for the selected period.

Table 84 Interface Invokes

Column Description

Name The name of the service consumed by the selected interface.

For example, if you select interface S3R1 in the Consumes table and select Component Service S4I1 in the Interface Invokes table, the Provides & Consumes tab for Component S4 is opened. Component Service S4I1 is pre-selected in the Provides table and in the Interfaces Consumed By table, S3R1 is selected.

Type The composite element type of the consumed service.





Provides

The Provides table displays information about the interfaces the composite reference provides. Table 85 describes the details about the provided interfaces.

Interface Consumed By

The services consuming the interface that you select in the Provides table appear in Interface Consumed By table. Table 86 describes the details about the services.

External Endpoint

The binding URL referenced by the composite reference.

Table 85 Composite Reference Provides

Column Description

Interface Name The name of the interface.

Port Type The port type supported by the service.



Table 86 Interface Consumed By

Column Description

Name The name of the service consuming the selected interface. The services are sorted in ascending alphabetical order.

For example, if you select interface S1I1 in the Provides table and select Component Reference S2R1 in the Interfaces Consumed By table, the Provides & Consumes link for Component S2 is opened. Component Reference S2R1 is pre-selected in the Consumes table. In the Interface Invokes table, S1I1 is selected. You can click the S1I1 link to return to this screen.

Type The composite element type of the provided service.

Fault/Success The ratio faults to successful hits for the selected period.




Deployment DetailsThe Deployment Details tab provides deployment details for the service, including the nodes the service is deployed to. It also provides performance details by interface and operation across all nodes.

Interfaces & Operations

The Interfaces & Operations table lists all the operations defined in services deployed on nodes. The operations are grouped under interfaces.

Table 87 Interfaces and Operations

Column Description

Name The interface and operation names. The interfaces and operations are sorted in ascending alphabetical order. You can expand or collapse the data for each interface.

Hits The total number of requests for the selected operation for the selected time period. This is across all nodes the service is deployed to.

Fault/Success The ratio of the number of failed hits to the number of successful hits for the selected period. This is across all nodes the service is deployed to.

Throughput Number of requests per minute for the selected time period across all nodes the service is deployed to.

Response Time (millisecond)

The average response time for the selected operation for the selected period categorized by:

• Minimum The minimum request response time for the selected operation.

• Maximum The maximum request response time for the selected operation.

• Average The average request response time for the selected operation.

Message Size (KB)

The average message size for the selected operation for the selected period categorized by:

• Minimum The minimum message size for the selected operation.

• Maximum The maximum message size for the selected operation.

• Average The average message size for the selected operation.



Service Deployed to N Nodes

This table provides details about how the selected service is deployed across all nodes. Table 88 describes the details of the service.

Table 88 Nodes

Column Description

Node Name The names of the nodes on which the service is deployed.

Status The status of the node on which service is running. The status can be:

• Defined The node definition is added but the node is not installed or has been uninstalled after installation. Same status as Uninstalled.

• Install Failed Node installation has failed.


• Installed/Stopped The node has been installed on the machine but the node is currently not running. This state occurs after the node has been installed but before it has been started or after it has been started and then stopped.

• Start Failed Node startup failed.

• Stop Failed The node stop routine has failed to stop the node process.

• Running The node process is running.

• Unknown The state of the node cannot be determined.

In addition, there are three transient states that can be displayed: Installing, Starting, and Stopping.

If there is a problem, an error icon is displayed next to the message.

Fault/Success The ratio of failed to successful hits for the selected period across all nodes on which the service is deployed.

Hits Number of times the service is used.

View Service Instance Details

Link to the Service Instance view on the specified node as described in Service Instance View, page 280.



UDDI PublishingUDDI Publishing tab allows you to publish, unpublish, and sync the publish state of a service. You can publish a composite service to any number of UDDI servers. Only UDDI servers added to the enterprise and enabled for the environment are available. See Adding a UDDI Server on page 156 and Enabling UDDI Servers in an Environment on page 186

Publishing a Service

To publish a service:

1. Select a UDDI server. See UDDI Servers on page 276.

2. Select a business. See Business on page 277.

3. Optionally add metadata. See Metadata on page 278.

4. In the Action column, click Publish.

Syncing or Unpublishing a Service

You may need to resynchronize the publish status of a service with the UDDI server for the following reasons:

• The service is out of sync with the deployed service instances. For example, you may have deployed the service to a new node after you initially published to the UDDI server.

• The system crashed during a publish and the service was not published across all UDDI servers.

• Permission to publish to a business was not granted to the user.

To sync or unpublish a service:

1. Select a UDDI server.

2. In the Action column, click Sync or Unpublish.

UDDI Publishing Reference

Figure 21 on page 276 shows the UDDI Publishing tab for the service JavaSOAPService. The service is published to one UDDI server. The areas of the tab are described in the sections:

• UUID on page 276

• UDDI Servers on page 276

• Metadata on page 278



• Endpoint Chosen for Publication on page 279

Figure 21 UDDI Publishing Tab

UUID

The UUID (universally unique identifier) for the service.

UDDI Servers

Table 89 UDDI Servers

Column Description


If you are publishing to ActiveMatrix Registry and you are not the admin user of the registry, you must first transfer ownership of a specific tModel to a non-admin user. See Enabling Non-Administrator Users to Publish to the ActiveMatrix Registry on page 378.

Publish URL The publish URL of the UDDI server.



Status The publish status:

• Published The service has been published to the selected UDDI server. The Action button is set to Unpublish.

• Unpublished The service is not published. The Business is set to -Select- and the Action button is set to Publish.

• Publish Incomplete Displays for one of the following reasons:

— The service is out of sync with the deployed service instances. For example, you may have deployed the service to a new node after you initially published to the UDDI server.

— The system crashed during a publish and the service was not published across all UDDI servers.

— Permission to publish to a business was not granted to the user.

The Action buttons are set to Publish and Unpublish.

Business A drop-down list of the businesses registered in the selected UDDI server. If not yet published, -Select- is displayed as the first item in the drop-down list and the Publish button is enabled.

The business name must contain only alphanumeric characters. If the business name contains special character such as $, %, ^, or &, the business name does not appear in the list.

In order for a user to publish services to a business created by another user, correct access permissions need to be granted. For ActiveMatrix Registry, you must provide read, write, and access permissions for the business to a special group that contains all users (such as user, group, and system). For strict control, system#everyone group can be granted read access and the publishing user can be granted read and write access. For details, see Adding Permission to Publish to a Business on page 380.

Table 89 UDDI Servers (Cont’d)

Column Description



Metadata

To add metadata at the logical service level (that is, parent service):

1. Click Add.

a. The Add Metadata dialog appears.

b. Enter data in the Name and Value text fields.

c. Click Save.

ActiveMatrix Administrator automatically publishes the metadata to all UDDI servers.

You delete the metadata by clicking the Remove link in the same row.

Action Based on the status, the following buttons display:

• Unpublish Unpublishes to the selected Publish URL and Business. If status is set to Published, the button state is Unpublish.

If the UDDI server is unavailable when you perform this action, the status changes to Unpublished and the button label changes to Publish reflecting the publish status of the service in the ActiveMatrix Administrator database, but the service is not removed from the UDDI server. You must remove the service from the UDDI server when it is available.

• Publish Publishes to the selected UDDI server and business. If status is set to Unpublished, the button state is Publish.

Table 89 UDDI Servers (Cont’d)

Column Description

Table 90 Metadata

Column Description

Name The name of the metadata.

Value The value of the metadata.



Endpoint Chosen for Publication

A composite service that has been deployed to multiple nodes has multiple service instances. However, most enterprises will maintain a load balance URL for the service that will dispatch requests to the service instances. Therefore, only one of those service instances is chosen to be published to the UDDI server. To use the load balance URL, you must manually edit the service instance endpoint and replace it with the URL of the load balancer. Table 91 displays the deployment details of the service instance chosen for publication for the selected service.

Table 91 Endpoint Chosen for Publication

Column Description

Service Instance Name The name of the service instance.

Node The node on which the service instance is deployed.

Unique ID The UUID (Universally Unique Identifier) for the service instance.



Service Instance View

You navigate to the Service Instance view as follows:

• Open the Integrated Service view as described in Integrated Service View on page 264 and click the Deployment Details tab. Click the View Service Instance Details link.

• Select the Infrastructure link and click a node in the Nodes table. Select the service name link from the Service Instances table.

• In Browse mode (see Browse Mode on page 291), click Infrastructure and select a values in the Environments, Machines, and Nodes columns. After you select an environment, machine, or node, click the View Service Instances button. From the displayed list of services, select a service name from the Name column.

The Service Instance view is divided into the following areas:

• Service Instance Trail on page 280

• Service Instance Details on page 281

• Tabbed Notebook:

— Overview on page 282

— Operations on page 283

Service Instance TrailThe service instance trail is displayed in the top area:

Table 92 Service Instance Trail

Column Description

envName envName is the name of environment containing the service instance.



Service Instance View | 281

Service Instance DetailsBelow the service instance trail, the service name with the associated node is displayed. For example, myService on Node32.

Click View Service on All Nodes to open the Deployment Details tab where you view interface and operation deployment details for the service.

The View Logs button opens the View Logs dialog where you choose the logs to view for the selected element. See Using the Log Viewer on page 318 for details.

Logical Displays the logical trail of the service instance. The trail shows how the service instance was deployed as follows:

LOGICAL serviceAssemblyName > serviceUnitName

where

• serviceAssemblyName: The service assembly the service instance is associated with.

• serviceUnitName: The service unit this service instance is associated with.

When you click a name, it opens the respective subview of the Deployment view.

Physical Displays the physical trail to the service instance. The trail shows where the service was physically deployed as follows:

PHYSICAL machineName > nodeName

where

• machineName: The name of the machine the service instance is running on.

• nodeName: The name of the node the service instance is deployed to.

When you click a name, it opens the respective subview of the Infrastructure view.

Table 92 Service Instance Trail (Cont’d)

Column Description



OverviewThe Overview tab provides summary of service instances.

Faults/Successes

The the number of failed hits to the successful hits for the selected period is displayed as a Pie chart. The available periods are Time Period or Since Started.

The data on the graph is displayed in color where green represents successful hits and red represents failed hits.

Total Requests

A graph, plotted between the number of requests against the selected period, is displayed and updated in real time. Total number of requests, categorized into successes and faults, are plotted on the Y-axis. The selected period is displayed on the X-axis. Note that the graph is not to scale.

The data in the graph builds from left to right in real time and moves relative to the selected period. The values of the metrics are updated every minute and displayed in the graph. The graph in green displays the number of successful hits and the graph in red displays the number of faults at the given time. Selecting a location on the graph opens a pop-up window that provides details such as date and time, number of faults, number of successes, and response time.

A bar graph below the requests graph shows the service response time in milliseconds for that moment in time. The X-axis represents the selected period and the Y-axis displays the response time in milliseconds.

Table 93 Service Instance Overview

Metric Description

Name The name of the service instance.

Description The description of the service instance.

Implementation The type of the service implementation. It can be TIBCO ActiveMatrix Java, SOAP, JMS, Mediation, Adapter, and .NET.

Namespace The namespace that identifies the web service that implements the service.


Service Instance View | 283

Performance

The chart shows performance data for the service instance per selected period and since the service started.

OperationsThe Operations tab provides list of interfaces and operations available in the service instance.

Table 94 Performance

Column Description

Start Date The date and time that the service was started.

Availability The amount of time as a percentage that the service was down against the time when the service was up and running (that is, downtime versus uptime percentage). The percentage is displayed in color: green indicates a percentage in the range of 51-100% and red represents 0 – 50%.



The performance data for the selected period. The data changes for the selected period:

• Time Period The average number of requests processed per minute in the specified period. Past 24 hours is the default period.

• Since Started The total number of requests processed by the service per minute. This is the average per minute since the start date and time.


The average amount of time in milliseconds between receiving a request and returning a response during the selected period:

• Time Period The average request response time in milliseconds in the specified period. Past 24 hours is the default period.

• Since Started The average request response time in milliseconds. This is the average per millisecond since the start date and time.

Total Requests The total number of service requests received in the specified period and since the service started.

If Period is already set to Since Started, the column Since Started does not appear in the Performance table.



Interfaces & Operations

The Interfaces and Operations table lists all the operations supported by the service instance. The operations are grouped under various interfaces. Table 95 describes the details of the operations.

Table 95 Interface and Operations

Column Description

Name The interface and operation name.

The interfaces and operations are sorted in ascending alphabetical order. You can expand or collapse the data for each interface.

Hits Number of times the operation has been invoked.

Fault/Success The number of fault and successful responses.

Throughput The number of times the operation is invoked per second.

Response Time (milliseconds)

The average response time for the selected operation for the selected period. It is categorized into:

• Minimum The minimum response time for the selected operation.

• Maximum The maximum response time for the selected operation.

• Average The average response time for the selected operation.

Message Size (KB)

The average message size for the selected operation for the selected period.

• Minimum The minimum message size for the selected operation.

• Maximum The maximum message size for the selected operation.

• Average The average message size for the selected operation.


Deployment View | 285

Deployment View

In the Deployment view you view data about service assemblies and service units. You navigate to the Deployment view as follows:

• Click the Deployment link.

• In Browse mode (see Browse Mode on page 291), click Deployment, select a values from the Environments, Service Assemblies, or Service Units columns, and then click View Service Assembly or View Service Unit.

The Deployment view consists of three subviews:

• Environment View on page 285

• Service Assembly View on page 287

• Service Unit View on page 288

Environment ViewIn the top area, the environment details are displayed:

• The name of the environment.

• Total number of active service assemblies against the total number of available service assemblies in the selected environment.

• Total number of active services against the total number of available services in the selected environment.

Service Assemblies

After you select the environment and period for monitoring, all the data related to service assemblies in the selected environment is displayed in the Service Assemblies table.



Based on the current status of a selected service assembly, you can start or stop the service assembly by clicking the Start and Stop buttons. The columns in the table specify the following details about the service assemblies. Table 96 describes the details of the service assemblies.

Table 96 Service Assemblies

Column Description

Name The service assembly name. Name is a link that you can click to see the details of the service units bundled in that service assembly. After you click Name, the service assembly details are displayed as described in Service Assembly View on page 287.

Status The status of the service assembly.

• Deployed The service assembly has been deployed but has not been started.

• Deployed with Errors1 The service assembly has been deployed, but errors need to be resolved before it can be started.

• Running The service assembly is running.

• Running with Errors1 The service assembly is running with errors.

• Not Deployed The service assembly archive has been uploaded but has not been deployed or has been deployed and then undeployed.

• Not Deployed with Errors1 The service assembly has been undeployed with errors.

Deployability The relationship between the deployed service assembly versus the service assembly configuration in the ActiveMatrix Administrator database. Displays one of the following:

• In Sync Indicates that the deployed service assembly matches the version in the database.

• Out of Sync Indicates that changes have been made to the service assembly configuration, and the deployed service assembly does not match the version in the database. Redeployment is necessary.

# of Service Units Total number of service units bundled in a service assembly.

1. The status is a link that you can click to display a screen with information about the error. You candrill down to the Service Unit node mapping level to see the details.



Service Assembly ViewThe Service Assembly view is divided into three areas:

• Service Assembly Trail on page 287

• Service Assembly Details on page 287

• Service Units Table on page 288

Service Assembly Trail

The service assembly trail is provided in the top area:

Service Assembly Details

Below the service assembly trail, the service assembly name and its status is displayed. You can start and stop the service assembly using the Start or Stop button.

Select the View Logs button to open the View Logs dialog where you choose the logs to view for the selected element. See Using the Log Viewer on page 318 for details.

The following details about the selected service assembly are also displayed:

Table 97 Service Assembly Trail

Metric Description

envName envName is the name of environment containing the service assembly.


Table 98 Service Assembly Details

Metric Description

Name The name of the service assembly.

Description The description of the service assembly.

Date Deployed The date and time when the service assembly was deployed.

Deployed By The user who deployed this service assembly.



Service Units Table

The details about the service units bundled in the selected service assembly are displayed in the Service Units table. The columns in the table specify the properties of each bundled service unit in the service assembly. The data displayed in the table is updated every minute.

Service Unit ViewThe details about a service unit are displayed in the Service Unit view. The Service Unit view is divided into three areas:

• Service Unit Trail on page 289

• Overview on page 289

• Services on page 290

Status The current status of the service assembly.

Deployable? Whether the service assembly has been configured for deployment.

Table 98 Service Assembly Details (Cont’d)

Metric Description

Table 99 Service Units

Metric Description

Name The name of the service unit. Name is a link that you can click to see the details about the service unit. After you click Name, the service unit details are displayed as described in Service Unit View on page 288.

Status The current status of the service unit.


Type The name of the container type. For example, com.tibco.matrix.container.soapbinding.runtime or com.tibco.matrix.container.javase.runtime.

Nodes Mapped The names of the nodes on which the service unit is deployed.

You can click a node name to view its details as described in the Node View on page 256.



Service Unit Trail

The service unit trail is provided in the top area:

Below the trail the name of the selected service unit is displayed with details provided in the Overview and Services tabs.

Overview

The Overview tab displays the following details about the selected service unit. It also displays the Node table which contains the names of the nodes on which the service unit is deployed.

Table 100 Service Trail

Metric Description



Logical Displays the logical trail of the service. The trail shows how the service was deployed.

LOGICAL serviceAssemblyName

where serviceAssemblyName is the service assembly containing the service unit.

When you click serviceAssemblyName, it opens the Service Assembly subview of the Deployment view.

Table 101 Service Unit Details

Metric Description

Name The name of the service unit.

Type The name of the container type. For example, com.tibco.matrix.container.soapbinding.runtime or com.tibco.matrix.container.javase.runtime.




Nodes

The Nodes table displays the list of nodes on which the service unit is deployed. The columns in the table displays the following data corresponding to each node.

Services

The Services tab displays the Services table which lists the names of services in the selected service unit. The properties of each service are displayed as columns in the Services table. For information about the Services table, see Table 75 on page 263.

Table 102 Nodes

Column Description

Name The name of the node on which the selected service unit is deployed. You can click Name to display the details of that node as described in Node View on page 256.

Status The status of the node.

# of Services Total number of services deployed on the selected node.

# of Containers Total number of containers activated on the selected node.

Uptime The amount of time that has elapsed since the service was deployed on the node. The uptime is displayed in terms of days, hours, and minutes.

CPU Time Total amount of CPU time consumed by the node since the node was started.

Fault/Successes The number of faulty and successful responses.

JVM Memory The amount of JVM memory consumed by the nodes against the total amount of memory available is displayed as a bar graph. The bar signifies the amount of memory in use. The green, yellow, and red values indicate the amount of memory consumed by the machine (Green = 0-50%, Yellow = 51-75%, and Red = 76 - 100%). For example, if the bar becomes red, it signifies that the memory consumption is very high and it may degrade the system performance.

Hostname The name of the machine on which the node is running. You can click the hostname to get more details about the machine as described in Machine View on page 253.


Browse Mode | 291

Browse Mode

Using the Browse mode enables you to browse for data, then drill down to monitor the data in different ways. Browse mode is available in all the views and allows you to view physical data or deployment data. To access data in Browse mode:

1. Click the Browse button on the top right corner of any view. A window shade appears on your screen.

2. Click one of the following:

— Infrastructure Allows you to browse physical data.

— Deployment Allows you to browse deployment data.

• If you select Infrastructure, columns for Environments, Machines, and Nodes appear on the window shade.

a. Select an environment from the Environments column to drill down the data. Based on the selected environment, data is displayed in the Machines column. After you select an environment, the following buttons appear:

View Environment Details about the selected environment in the Environment View. For details about this view, see Environment View on page 250.

View Service Instances On Environment Details about the services running in the selected environment in the Service view. For details about this view, see Service View on page 261.

b. To get details about a machine, select a machine name in the Machines column.

By default All Machines is selected. Based on the selected machine name(s), data is displayed in the Nodes column. When the default option All Machines is selected, the names of all the nodes existing on all the machines



are displayed in the Nodes column. After you select a machine name, the following buttons appear:

View Machine Details about the selected machine in the Environment View. For details about this view, see Machine View on page 253.

View Service Instances On Machine Details about the services running on the selected machine in the Service view. For details about this view, see Service View on page 261.

c. To get details about a node, select a node name in the Nodes column. After you select a node name, the following buttons appear on the window.

View Node Details about the selected node in the Node View. For details about this view, see Node View on page 256.

View Service Instances On Node Details about the services running on the selected node in the Service view. For details about this view, see Service View on page 261.

• If you select Deployment, columns for Environments, Service Assemblies, and Service Units appear on the window shade.

a. Select an Environment to drill down the data. Based on the selected environment, data is displayed in the Service Assemblies column. After you select an environment, the following buttons appear:

View Environment Details about the selected environment in the Environment View. For details about this view, see Environment View on page 250.

View Services On Environment Details about the services running in the selected environment in the Service view. For details about this view, see Service View on page 261.


Browse Mode | 293

b. To get details about a service assembly, select a service assembly name in the Service Assemblies column. Based on the selected service assembly names, data is displayed in the Service Units column. After you select a service assembly name, the following buttons appear:

View Service Assembly Details about the selected service assembly in the Service Assembly subview of the Deployment view. For details about this view, see Service Assembly View on page 287.

View Services On Service Assembly Details about the services running in the selected service assembly in the Service view. For details about this view, see Service View on page 261.

c. To get details about a service unit, select the name of the service unit in the Service Units column. After you select a service unit name, the following buttons appear on the window:

View Service Unit Details about the selected node in the Service Unit subview of the Deployment view. For details about this view, see Service Unit View on page 288.

View Services On Service Unit Details about the services running in the selected service unit in the Service view. For details about this view, see Service View on page 261.

1. Click Close to close the window shade.




| 295

Chapter 10 Managing Logging

This chapter describes how to create log services, create logging configurations, use the Log Viewer to query for and display log events and view server logs.

Topics


• Working with Log Services, page 302

• Working with Logging Configurations, page 310

• Using the Log Viewer, page 318

• Server Logs, page 337


296 | Chapter 10 Managing Logging

Overview

ActiveMatrix supports a flexible logging architecture that enables runtime objects to log events to a variety of destinations. Events logged to log services can be stored to a database, analyzed using the Log Viewer, or forwarded for further processing. An ActiveMatrix logging environment is depicted in Figure 22.

Figure 22 ActiveMatrix Logging Environment

An ActiveMatrix logging environment involves five types of participants:

• Event destination A consumer of log events. ActiveMatrix supports the following destination types: console, file, log service, database. Log events are sent to destinations by log event generators and log services.

• Event generator An ActiveMatrix runtime object (node or object running on a node) that generates log events. You specify the destination to which nodes

AMA Server

Log Viewer UI

LegendAM

AMAEMS

LSQ

TIBCO ActiveMatrixTIBCO ActiveMatrix AdministratorTIBCO Enterprise Message ServiceLog ServiceLog Service Queue

AM Node 2

Database

AM Node 1

LS 3(Default)LS 2

LS 1

Log File

Log Event Processor

TIBCO Common Logging Plug-in

Log Viewer

Log File

www

Console

Q1 Q2 Q3 (Default)

EMS Server


Overview | 297

and ActiveMatrix objects send log events in a logging configuration. See Logging Configurations on page 310. In Figure 22 on page 296, Node 1 sends message to the console. Node 2 sends messages to a log file and the default log service.

• Log service A destination that accepts events that conform to specific types of event models. Log services store events to files and databases and forward events for further processing. See Working with Log Services on page 302.

• Log Viewer A browser-based server and client UI for viewing log events stored to or loaded into a database. See Using the Log Viewer on page 318.

• TIBCO Common Logging Plug-in ActiveMatrix Administrator server plug-in that implements log services and the Log Viewer. See Starting and Stopping the TIBCO Common Logging Plug-in on page 301.

Event ModelsAn event model specifies the type of attributes associated with a log event. The supported event models are:

• Base Event Format (BEF) The root of all event formats. It includes the most common attributes of an event. See Base Event Format Attribute Reference on page 331.

• Engine Event Format (EEF) Adds engine-level attributes to the Base Event Format. This is the default model. See Engine Event Format Attribute Reference on page 335.

• BW Engine Event Format Adds BusinessWorks-specific engine attributes to the Engine Event Format. See BW Engine Event Format Attribute Reference on page 335.

Log FilesActiveMatrix logging architecture works with log files in Common Base Event (CBE) format. For information about the CBE file format, see the CBE specification at http://www.eclipse.org/tptp/platform/documents/resources/cbe101spec/CommonBaseEvent_SituationData_V1.0.1.pdf.

This section describes:

• Log File Generation on page 298

• Importing Log Files into a Log Service Database on page 298

• Viewing Log Files on page 299


http://www.eclipse.org/tptp/platform/documents/resources/cbe101spec/CommonBaseEvent_SituationData_V1.0.1.pdf



Log File Generation

Log files are generated in the following circumstances:

• When the destination of a log service is a file. See Working with Log Services on page 302.

• When log events displayed in the Log Viewer are exported to a log file. See Exporting Log Events to a File on page 327.

• When an ActiveMatrix logging configuration appender is set to a file. See Logging Configurations on page 310.

Importing Log Files into a Log Service Database

If you want to view the log events in a log file in the Log Viewer, you must import the log file into a log service whose destination is database. To import a log file you use the ActiveMatrix Administrator command-line interface (see ActiveMatrix Administrator Command-Line Interface on page 79), invoking the add action on a AdminCluster/LogServiceConfiguration object in the build file and specifying a value for the LogServiceConfiguration element in the data file. The LogServiceConfiguration element contains the following subelements:

• ImportLogFile The fully-qualified path to the CBE format log file.

• ImportDestination The name of a log service whose destination is a database.

The following sections contain example build file task definition and data file elements.

Build File

<AMXAdminTask...action="add"dataFile="datafile"objectSelector="AdminCluster/LogServiceConfiguration"overwrite="true"merge="true"createIfNotExists="true"force="true"failOnError="true"/>

Data File

<AdminCluster><LogServiceConfiguration>

<ImportLogFile>PathToLogFile</ImportLogFile><ImportDestination>LogServiceName</ImportDestination>

</LogServiceConfiguration></AdminCluster>


Overview | 299

Viewing Log Files

There are two ways to view log files:

• Log Viewer

• TIBCO Business Studio

Log Viewer

In order to view a log file in the Log Viewer (see Using the Log Viewer on page 318) you must first import the file into a log service database by following the procedure described in Importing Log Files into a Log Service Database on page 298. Log Viewer allows more complex and sophisticated query capability than the log viewer available in TIBCO Business Studio.

TIBCO Business Studio

If you have installed the design component of ActiveMatrix you can also analyze a log file using the profiling and analysis tools available in TIBCO Business Studio. For information on how to use the profiling and analysis tools, see Help > Help Contents > Monitoring and profiling applications.

To import the exported log file and display the profiling and analysis perspective:

1. Start TIBCO Business Studio and create an ActiveMatrix SOA project following the procedures described in Starting TIBCO Business Studio and Creating an ActiveMatrix SOA Project in TIBCO ActiveMatrix Composite Editor User’s Guide.



2. Select File > Import. The import wizard will display.

a. Select Profiling and Logging > Log File.

b. Click Next.

c. Click Add.... The Add Log File dialog will display.

d. In the Filter table, select Common Base Event XML log.

e. In the Log details area, click Browse to the right of the Common Base Event XML log file path field. The Import log sets dialog will display.

f. Click the Browse button next to the From directory field and navigate to the directory containing the log file you have exported and saved to disk.

g. Check the checkbox next to the log file.

h. Click OK twice.

i. Click Finish. A dialog asking whether you want to switch to the Profiling and Logging Perspective will display. Click Yes.

j. The Log Navigator will display. Expand the Logs node and click the Common Base Event XML log node. The Log Viewer will display.

Figure 23 Log Navigator and Log Viewer


Overview | 301

Starting and Stopping the TIBCO Common Logging Plug-inWhen you restart the TIBCO Common Logging plug-in, all the contained log services are restarted. To start and stop the TIBCO Common Logging Plug-in:




4. In the Plug-ins table, select TIBCO Common Logging.

5. Click Start or Stop.

If you stop the TIBCO Common Logging plug-in, objects that are configured to send log events to a log service (see Logging Configurations on page 310) will continue to generate log events. The log events will accumulate in the TIBCO Enterprise Message Service server and the log services will process those messages the next time the plug-in starts up. To configure the log message queue to handle the messages, see TIBCO Enterprise Message Service User’s Guide.



Working with Log Services

Log services encapsulate a destination and a set of event models. Log services can:

— Collect log events across the entire enterprise

— Collect specific class(es) of events, such as audit events, SPM events, or alerts

— Collect log events and forward to another process

— Import log events from a file

— Send events to a database or log file

For example, in Figure 22 on page 296:

— Log service LS1 receives events on Q1. A queue bridge routes the events to another process.

— Log service LS2 receives events on Q2 and stores them in a log file.

— Log service LS3 is the default log service. It receives events on Q3 and stores them in a database. It also imports the log file created by Node 2.

ActiveMatrix nodes and objects running on the nodes can log only to the log service designated as the default log service.

Operations on log services are described in the following sections:

• Creating a Log Service on page 302

• Setting the Default Log Service on page 303

• Starting and Stopping a Log Service on page 304

• Editing a Log Service on page 304

• Deleting a Log Service on page 305

• Purging a Log Service Database on page 308

Creating a Log ServiceTo create a log service:



3. Click the Log Services link.


Working with Log Services | 303

4. Click the New button. The Log Service dialog displays.

a. Edit the fields according to the descriptions in Table 104 on page 306. For example:

b. Click Save. The dialog is dismissed and the log service is added to the Log Services table.

5. Start the log service following the procedure described in Starting and Stopping a Log Service.

Setting the Default Log ServiceActiveMatrix nodes and objects running on the nodes can log only to the log service designated as the default log service. To set the default log service:




4. In the Log Services table, click a log service.

5. Click the Set Default button.



6. Start the log service following the procedure described in Starting and Stopping a Log Service. After performing these steps, the Log Service table event for the log service will appear similar to:

Starting and Stopping a Log ServiceTo start or stop a log service:





5. Click the Start or Stop button.

Editing a Log ServiceTo edit a log service:





5. Click Edit.

6. Edit the fields according to the descriptions in Table 104 on page 306.

7. Click Save.

8. Restart the log service.

Whenever you change the JMS Connection setting you must also restart all nodes that satisfy the following conditions:

• The node’s logging configuration appender is set to JMS.

• The node hosts objects (containers, service assemblies, or service units) whose logging configuration appender is set to JMS.



Deleting a Log ServiceTo delete a log service:




4. In the Log Services table, click the log service.

5. Click Stop.

6. Click Delete.



Log Services Reference

Log Service Reference

Table 103 Log Services

Column Description

Name The name of the log service.

JMS Connection The JMS connection from which the log service receives events.

JMS Queue The queue on which the log service receives log events from ActiveMatrix objects.

Destination The destination to which the log service sends log events.

Pending Messages The number of log events in the queue.

Default? Indicates whether the log service is the default log service.

Status The status of the log service.

Table 104 Log Service Reference

Field Description

Name The name of the log service.

JMS Connection

The JMS connection on which the service receives log events. A drop-down list containing existing JMS shared resource definitions. Before selecting a connection you must configure a JMS shared resource definition as described in JMS Shared Resource Definition Reference on page 127.

JMS Queue The queue on which a log service receives log events from ActiveMatrix objects. By default, all ActiveMatrix objects are configured to send the log events to the default log service’s JMS queue. For configuring a log client to use a queue for a non-default log service, contact TIBCO product support.

If the queue doesn't exist on the Enterprise Message Service server, the log service will create the queue.



Command-Line

You can also configure a log service from the ActiveMatrix Administrator command-line interface (see ActiveMatrix Administrator Command-Line Interface on page 79). To configure a log service, you invoke the edit action in the build file and specify a value for the LogServiceConfiguration element in the data file. The format of a LogServiceConfiguration varies depending on the type of the destination. All LogServiceConfiguration elements have subelements: LogServiceName, JMSSharedResourceName, QueueName, Destination, and ModelList.


Destination The destination to which the log service sends log events. One of:

• Database Append events to a database. Database drop-down list specifies the JDBC shared resource definition for the database. Before selecting a connection you must configure a JDBC shared resource definition as described in JDBC Shared Resource Definition Reference on page 123. If you want the JDBC shared resource definition to use a log datastore in the HSQLDB database, you must first configure the datastore as described in Creating a New HSQLDB Datastore on page 15.

• File Append events to a CBE format log file (see Log Files on page 297). The The File field specifies the file name and optionally the location. If the file location is not specified, the file location defaults to AMX_ADMIN_HOME/data/cluster/server/logs. The file name is appended with a number as described in Max Backup Index.

— Max File Size The maximum size of each log file.

— Max Backup Index The number of log files you wish to keep. When a log file reaches the maximum size, a new log file is created. After the number of files matches the number specified, the oldest is deleted when a new file is created. Each file is appended with a number.

• No Configuration The messages are not directed to a destination. The log service acts as a bridge for log events consumed by another process listening on the queue.

Models The types of event models handled by the log service. Use the left and right arrows to move models between the Available Models and Selected Models lists.

Table 104 Log Service Reference (Cont’d)

Field Description



Build File

<AMXAdminTask...action="edit"dataFile="datafile"objectSelector="AdminCluster/LogServiceConfiguration"overwrite="true"merge="true"createIfNotExists="true"force="true"failOnError="true"/>

Data File


<LogServiceName>test</LogServiceName><JMSSharedResourceName>test_JMS</JMSSharedResourceName><QueueName>test_queue</QueueName><Destination>DB</Destination><JDBCSharedResourceName>test_jdbc</JDBCSharedResourceName><ModelList>

<ModelName>BaseEventFormat</ModelName><ModelName>EngineEventFormat</ModelName>

</ModelList></LogServiceConfiguration>

</AdminCluster>

Purging a Log Service DatabaseTo purge a log service database of log events you use ActiveMatrix Administrator command-line interface (see ActiveMatrix Administrator Command-Line Interface on page 79) invoking the delete action in the build file and specifying a value for the PurgeCommandParameter element in the data file. The possible values for PurgeCommandParameter are:

• all Delete all log data.

• –d <yyyy-MM-dd> Delete all logging data created before the specified date.

• -t <yyyy-MM-dd hh:mm:ss> Delete all log data created before the specified time.

Examples• all

• -d <2007-08-10>

• -t <2007-08-10 13:05:00>




Build File

<AMXAdminTask...action="delete"dataFile="datafile"objectSelector="AdminCluster/LogServiceConfiguration"overwrite="true"merge="true"createIfNotExists="true"force="true"failOnError="true"/>

Data File


<PurgeDestination>log service</PurgeDestination><PurgeCommandParameter>all</PurgeCommandParameter>

</LogServiceConfiguration></AdminCluster>



Working with Logging Configurations

ActiveMatrix objects (nodes, containers, service assemblies, and service units) can send log events to the console, a file, or a log service. You configure how objects log in a logging configuration. For information on how to generate log events from component implementations, see TIBCO ActiveMatrix Service Grid Component Developer’s Guide and TIBCO ActiveMatrix Service Grid Mediation Design Guide.

Logging ConfigurationsA logging configuration specifies the type of events an ActiveMatrix object logs and the destination for log events. Logging configurations are organized in the parent-child sets shown in Table 105.

A child logging configuration is set in the logging configuration screen of its parent. If you do not specify a logging configuration for a child object, the child object inherits its parent’s logging configuration. Table 106 shows how to navigate to the screen where you configure the logging configuration for each type of parent-child set.

Figure 24 on page 311 illustrates various types of node and container logging configurations and Figure 25 on page 311 illustrates various types of service assembly and service unit logging configurations.

Table 105 Parent-Child Logging Configuration Set

Parent Child

Node Container

Service assembly Service unit

Table 106 Object Logging Configuration Screens

Parent Screen

Node Configure an Environment > node

Service assembly Deploy to an Environment > service assembly



Figure 24 Node and Container Logging Configurations

Figure 25 Service Assembly and Service Unit Logging Configurations

Editing a Logging Configuration

To edit a logging configuration:

1. Navigate to a screen containing a logging configuration according to Table 106 on page 310.

2. Click the Logging Configurations link.

3. Click the Edit button above the Logging Configurations table.

4. In the Logging Configurations table, click a configuration.

5. Edit the parameters of the logging configuration following the descriptions in Table 107 on page 316.

6. Click the Apply button.

Adding Child Logging Configurations

To add child logging configurations:

1. Navigate to a screen containing a logging configuration according to Table 106 on page 310.

2. Click Logging Configurations.

3. Click the XXX Logging button above the Logging Configurations table, where XXX can be either Container or Service Unit. The Choose XXX to Log dialog appears.

4. Check the checkboxes next to the child objects you want to log.

5. Click Save.



6. For each child logging configuration, specify the parameters of the logging configuration following the procedure described in Editing a Logging Configuration on page 311.

Adding Logging Configurations to Objects

TIBCO ActiveMatrix uses the log4j mechanism to write log events to the desired location. The log4j mechanism uses appenders and loggers. Appenders describe locations to append log events. Loggers describe the items that you wish to log and the associated appender to use to write the log event. A default appender and logger is provided for the default logging behavior. You can modify the default configuration or add appenders and loggers as needed. There are a variety of third-party references that describe the complete set of log4j functionality. You can also view the log4j documentation at http://logging.apache.org/log4j/1.2/index.html.

In the ActiveMatrix Administrator GUI, a logger is called a logging configuration. The ActiveMatrix Administrator GUI allows you to define only one logging configuration (or logger) per object. You can add additional loggers to the objects running on a particular node by defining them in the bootStrap.xml file in AMX_HOME/data/environmentname/nodename/config. The loggers specified in bootStrap.xml are merged with the logging configurations you specify in the ActiveMatrix Administrator GUI.

bootStrap.xml has a base_hierachy tag and system-defined hierarchy tags. There are two hierarchies relevant to TIBCO ActiveMatrix logging configurations: node-container and service assembly-service unit. The two pairs do not share a hierarchy. A node's logging configuration captured inside the base_hierarchy tag is the default for the container unless container has its own configuration via the tag <hierarchy name="...">. The same is true for the service assembly-service unit hierarchy. The base hierarchy configuration in bootStrap.xml is applied to each hierarchy when bootStrap.xml and TIBCO ActiveMatrix configuration is merged at runtime.

To edit bootStrap.xml:

1. In the directory AMX_HOME/data/environmentname/nodename/config, locate the logging configuration template file bootStrap.xml. In the same directory, make a copy of the template file with a different suffix, before modifying bootStrap.xml as your working copy.

2. Open the working copy in a text or XML editor.


http://logging.apache.org/log4j/1.2/index.html


3. Add an appender. For example appenders, see:

— Example 1 Adding a Logging Configuration with a FIle Appender on page 313

— Example 2 Adding a Logging Configuration with a JMS Appender on page 314

— Example 3 Configuring BEFJMSAppender to Support JNDI and SSL Connections to the Enterprise Message Service Server on page 314.

4. Save the modified configuration file. The configuration is automatically loaded by the node.

Example 1 Adding a Logging Configuration with a FIle Appender

To configure logging to a file, create appender and logger elements of the following form before the closing log4j:configuration tag. Bold type indicates values that you can modify.

<base_hierarchy><log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">...<appender name="ExampleFileAppender"

class="com.tibco.commonlogging.appender.CommonRollingFileAppender">

<param name="File" value="example.log"/><param name="MaxFileSize" value="1024KB"/><param name="MaxBackupIndex" value="4"/>

<layoutclass="com.tibco.commonlogging.appender.BEF2CBELayout"/></appender><logger name="com.tibco.example">

<level value ="INFO"/><appender-ref ref="ExampleFileAppender"/>

</logger> ...<log4j:configuration></base_hierarchy>

The element properties are:

• A file appender with the following configurable properties:

— File The log file name.

— MaxFileSize The maximum size of each log file.

— MaxBackupIndex The number of log files you wish to keep.

• A logger that specifies a level and references the file appender



Example 2 Adding a Logging Configuration with a JMS Appender

To define a logging configuration with a JMS appender, create appender and logger elements of the following form before the closing log4j:configuration element. Bold type indicates values that you should configure.

<base_hierarchy> <log4j:configuration

xmlns:log4j="http://jakarta.apache.org/log4j/">...<appender name="ExampleJMSAppender"

class="com.tibco.commonlogging.appender.BEFJMSAppender"><param name="serverUrl" value="tcp://localhost:7222"/> <param name="retry" value="1"/><param name="queueName" value="DefaultLogServiceQueue"/> <param name="userName" value="admin"/>

</appender><logger name="com.tibco.example">

<level value ="INFO"/><appender-ref ref="ExampleJMSAppender"/>

</logger> ...<log4j:configuration></base_hierarchy>

The element properties are:

• A JMS appender with the following configuration properties:

— serverURL The Provider URL property of the JMS shared resource selected for the log service. See JMS Shared Resource Definition Reference on page 127.

— retry The number of attempts that should be made to connect to the messaging server represented by the JMS shared resource.

— queueName The JMS queue on which the default log service is listening (see JMS Queue on page 306).

— userName The username property of the JMS shared resource definition selected for the log service.

• A logger that specifies a level and references the JMS appender.

Example 3 Configuring BEFJMSAppender to Support JNDI and SSL Connections to the Enterprise Message Service Server

To configure BEFJMSAppender to support JNDI and SSL connections to the Enterprise Message Service server, add an appender using BEFJMSAppender and a logger referring to this appender into the configuration of the hierarchy.

<base_hierarchy> <log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">



...<appender

class="com.tibco.commonlogging.appender.BEFJMSAppender" name="JMSAppender"> <param name="queueName" value="queue_ssl"/> <param name="userName" value="admin"/> <param name="password" value="#!SDSJWPVWFm51lmPQCkDYug=="/>

<param name="type" value="jndi"/><param name="serverUrl"

value="tibjmsnaming://localhost:7243"/> <param name="providerContextFactory"

value="com.tibco.tibjms.naming.TibjmsInitialContextFactory"/>

<param name="retry" value="1"/>

<param name="ssl" value="true"/> <param name="sslVerifyHostName" value="true"/> <param name="sslExpectedHostName" value="server"/> <param name="sslVerifyHost" value="true"/> <param name="sslTrustedCertificates"

value="ENV_HOME/ems/version/bin/certs/server_root.cert.pem"/> <param name="sslVendor" value="entrust61"/> <param name="sslPassword"

value="#!aMzD1eOJOkGgLfKujKD8NeXN7npa+7rBwqDjfJgUDCk="/> </appender>

<logger name="com.tibco.commonlogging" additivity="false"><level value="INFO"/><appender-ref ref="JMSAppender"/>

</logger>...

</log4j:configuration> </base_hierarchy>

The properties for JNDI support include:

• type Set as jndi to use JNDI connections to Enterprise Message Service server.

• serverUrl Must be declared as tibjmsnaming://address:port instead of tcp://address:port to support JNDI lookup.

• providerContextFactory Should be declared as com.tibco.tibjms.naming.TibjmsInitialContextFactory or some other context factories. If the parameter isn't declared, JMSAppender will use com.tibco.tibjms.naming.TibjmsInitialContextFactory as the default value.

The properties for SSL support include:

• ssl Set as true to support SSL connections.

The password element should be obfuscated (see Creating an Obfuscated Password on page 28)



• sslVerifyHostName Specifies whether the appender should verify the name in the CN field of the Enterprise Message Service server’s certificate.

• sslExpectedHostName The name the appender expects in the CN field of the Enterprise Message Service server’s certificate. If this parameter is not set, the expected name is the hostname of the server.

This property is used when sslVerifyHostName is set as true and should match the value of the ssl_expected_hostname property set in the file ENV_HOME/ems/version/bin/factories.conf.

• sslVerifyHost Specifies whether the appender should verify the Enterprise Message Service server’s certificate.

• sslTrustedCertificates The name of certificate keystores containing the issuer certificates of Enterprise Message Service server certificates.

This property is used when sslVerifyHost is set as true and should match the value of the ssl_trusted property set in the file ENV_HOME/ems/version/bin/factories.conf.

• sslVendor The vendor name of the SSL implementation that the appender uses.

• sslPassword Private key or password for the Enterprise Message Service server’s certificate. It should be obfuscated (see Creating an Obfuscated Password on page 28) and the original password should match the value of ssl_password property set in the file ENV_HOME/ems/version/bin/factories.conf.

Object Logging Configuration Reference

Table 107 Object Logging Configuration Reference

Column Description

objectName The object for which you are configuring logging.



Severity Required. Determines the type of events that to be logged:

• All All events.

• Debug Fine-grained informational events used for debugging an application.

Note: You should not use Debug severity with the JMS appender for an extended period of time. Debug severity generates a large volume of messages which could overwhelm a log service.

• Info Coarse-grained informational messages that highlight the progress of the application.

• Warn Potentially harmful events.

• Error Application errors that allow the application to continue running.

• Fatal Very severe errors that will cause the process to abort.

Default: Warn.

Appender Required. Determines the destination to which log events are appended:

• File Append events to a CBE format log file (see Log Files on page 297). If File is the selected, the File, Max File Size, and Max Backup Index fields are displayed and required.

• JMS Append events to a log service. Only log events appended to the JMS appender are viewable in the Log Viewer (see Using the Log Viewer on page 318).

• Console Append events to System.out or System.err.

Default: Console.

File The name and optionally the location of the file. If the file location is not specified, the file location defaults to AMX_HOME/data/environmentname/nodename/logs. The filename is appended with a number as described in Max Backup Index. Displayed if Appender is set to File.

Max File Size The maximum size of each log file. Displayed if Appender is set to File.

Max Backup Index The number of log files you wish to keep. When a log file reaches the maximum size, a new log file is created. After the number of files matches the number specified, the oldest is deleted when a new file is created. Each file is appended with a number. Displayed if Appender is set to File.

Table 107 Object Logging Configuration Reference (Cont’d)

Column Description



Using the Log Viewer

The Log Viewer provides extensive facilities for querying ActiveMatrix object logs and customizing the query display.

Displaying the Log ViewerTo display the Log Viewer:

1. Select Monitor & Manage from the Perspective drop-down list.

2. Click the Log link in the Monitor & Manage heading. The Log Viewer will display.

The Log link in the Monitor & Manage heading does not display until you configure at least one log service with a database destination. For information on log services, see Working with Log Services on page 302.

You can also view log events by clicking the View Logs button that appears in various screens in the Monitor & Manage perspective. For further information, see Monitoring Infrastructure and Services on page 241.


Using the Log Viewer | 319

3. Select the log service whose events you want to view from the Log Service drop-down list.

The Log Viewer contains three areas:

• Query Builder Contains the attributes and attribute values used to filter log events and actions to perform various types of queries.

• Log Displays the log events that satisfy the query parameters.

• Log Detail Displays the details of a log event selected in the Log area.

Working with the Query BuilderThe query builder is illustrated in Figure 26 on page 320.



Figure 26 Query Builder

The query builder is divided into three areas:

• Toolbar Contains actions for displaying the query builder, selecting and running queries, and clearing the filter area.

• Model Contains an event model selector and a tree of the attributes available for each type of event model.

• Filter Contains a canvas displaying the active filters.

Toolbar Area

The toolbar provides action buttons for:

• Maximizing and minimizing the query builder.

• Building, saving, and deleting queries. See Building Queries on page 323 and Saving and Deleting Queries on page 324.

• Displaying query result hints and running queries. See Running Queries on page 324.

Maximizing and Minimizing the Query Builder

The Log Viewer allows you to control the screen real estate used by the query builder. Minimizing the query builder provides more real estate for viewing log events, but you can only view saved queries. Maximizing the query builder gives you full access to all query builder functions. To minimize the query builder, click the Minimize button in the toolbar. To maximize the query builder, click the Maximize button.



Model Area

The Log Viewer allows you to query for and view log events based on different log event models.

As shown in Figure 27 on page 321, all extensions to the BEF model, including BEF itself are listed in the model selection control. Only attributes from the currently selected model are displayed in the attribute tree. The models in the drop-down list are limited to the models that you selected when you created the log service (see Creating a Log Service on page 302).

Figure 27 Model Selection Control

Setting the Model

To set the model, select the model from the Model drop-down list.

When you change the model selection, all the filters displayed in the filter area are cleared.



Filter Area

You create new queries by adding filters to the filter area. Figure 28 shows the filter area with the creation time filter and two optional filters: ActiveMatrix Logical Component ID and EEF Severity. See Building Queries on page 323 for information on how to add and remove filters.

Figure 28 Filter Area

BEF Creation Time Filter

The BEF Creation Time filter causes log events to be filtered based on when the events were created. The creation time filter is always present in the Filter area. You can set the creation time filter as a relative or absolute time. To set a relative creation time, click the Relative radio button and select a time from the drop-down list. To set an absolute creation time, click the Absolute radio button and specify From and To date and times using the respective date and time pickers.

Filter Operators

Some filters allow you to provide an attribute value against which the attribute in log event is compared. For example, the filter in Figure 28 shows the = operator selected for the EEF Severity filter. The Log Viewer supports the operators listed in Table 108:

Table 108 Filter Operators

Operator Description

= The attribute value you provide exactly matches (strings) or equals (numbers) the attribute value in the log event.



Working with QueriesThis section describes the operations you can perform on queries:

• Building Queries on page 323

• Saving and Deleting Queries on page 324

• Running Queries on page 324

Building Queries

Adding Filters

There are four ways to add filters to queries:

• Drag and drop attributes from the model to the filter area.

• Right-click a cell in the Log and select Add filter with cell value. This operation appends the selected cell value to the filter area.

• Select a row and then drag and drop a cell from the Log to the filter area.

• Double-click the attributes from the model attributes tree.

Removing Filters

There are three ways to remove filters displayed in the filter area:

• Click the icon next to a filter.

• Click the Clear Filters button.

>= The attribute value you provide is greater than or equal to the attribute value in the log event. Available only for EEF Severity and EEF Priority.

<= The attribute value you provide is less than or equal to the attribute value in the log event. Available only for EEF Severity and EEF Priority.

CONTAINS The attribute value you provide contains a substring of the attribute value in the log event. For example, the value MyContext for a Context ID attribute, matches the following Context ID values: MyContext, MyContextXXX, XXXMyContextXXX

Table 108 Filter Operators (Cont’d)

Operator Description



• Change the model selected in the Model drop-down list. This action removes all the filters.

Saving and Deleting Queries

Saving a Query

To save a query:

1. Select Saved Queries > Save Query. The Save Query dialog is displayed.

a. To overwrite an existing query, select an query from the Name drop-down list. To create a new query, type a name in the Name list.

b. Check the appropriated checkboxes to make the query visible to other users or to mark it as the default query that is executed every time the Log Viewer is started.

c. Click Save.

Deleting Saved Queries

To delete a saved query:-

1. Select Saved Queries > Delete Queries. The Delete Query dialog is displayed.

a. Check the checkboxes next to the queries you want to delete.

b. Click Delete.

Running Queries

The Log Viewer supports a flexible approach to running queries. You can run newly constructed queries, saved queries, queries that are stored in the session, or a modified query. Before running a query you can obtain an estimate of the number of events that would be returned by a query.

Obtaining the Result Count Hint

Before running a query you can obtain the approximate number of events that would be returned by the query. Since a large number of events would be difficult to retrieve and view, the result count hint allows you to decide whether to first narrow a query by specifying more filters before actually running it. To obtain the result count hint, click the Hint button. The result count is displayed next to the Hint button.

The BEF Creation Time filter is mandatory, so is not removed by any method.



Running a Query

To run a new query:

1. Build a new query using the query builder.

2. Click the Run Query button.

Running an Existing Query

All the queries that you perform during a given session are stored in the Prev Queries drop-down list. The queries are identified by the time that you ran the query.

To run an existing query:

1. Select a query from the Prev Queries drop-down list.


Running a Saved Query

To run a saved query:

1. Select a query from the Saved Queries drop-down list. The filters specified in the query are displayed in the query builder.


Running a Modified Query

To run a modified query:

1. After running a query, select a row in the Log.

2. Right-click a cell within the row and select:

— Add filter with cell value and run query Adds a filter with the cell value to the filter area and runs the query.

— Replace filters with cell value and run query Replaces all the filters in the filter area with a filter with the cell value and runs the query.

Query will dsplay a warning if the record count is greater than 20k.

When you change perspective or restart ActiveMatrix Administrator, all the queries in the Prev Queries list are removed.



Working with the LogThe Log displays log events retrieved by queries. An example Log is displayed in Figure 29. By default, all BEF attributes are displayed.

Copy/paste is now available for log columns and event details. Note that the Internet Explorer browser has a problem that affects the copy function for log columns; Mozilla Firefox works correctly.

To customize the columns, follow the procedure in Customizing the Log Columns on page 326. For descriptions of the columns, see Event Formats on page 329.

Figure 29 Log

Customizing the Log Columns

All columns are sortable. Sorting by column is according to all query results, not the current displayed results.

To customize the Log columns:

1. Click Customize Display.

2. Check the checkboxes next to the attributes you wish to display.

3. Click Save.

Highlighting Log Events with Error Severity

You can highlight log events whose severity is Error or Fatal. When log events are highlighted, they are displayed in bold, red font.

When you change perspective or restart ActiveMatrix Administrator, the display reverts to the default state.



There are two ways to highlight log events whose severity is Error or Fatal:

• Through the display customization dialog. To invoke this dialog and enable highlighting:

a. Click Customize Display.

b. Check the Highlight error entries checkbox.

c. Click Save.

• Right-click a row in the log and select Highlight error entries.

To turn off highlighting, uncheck the checkbox or deselect Highlight error entries.

The two methods reflect the same setting, so choosing one changes the setting in the other method.

Setting the Log Refresh Rate

The Log displays the log events in existence when you run a query. Since log events are generated continuously, after some time has elapsed since the query was run the Log will not show the most recent log events. You can configure the Log to refresh itself to display newly generated log events. To set the rate at which the events in the Log are refreshed, click the Refresh Rate drop-down list and select one of the available rates: Off, 5, 10, 20, or 30 seconds. The default rate is Off.

Paging Through the Log

When a large number of events is returned from a query the Log is split into multiple pages. Only one page of 20 events is displayed at a time. To scroll through the pages, click the arrows in the page control above the Log or type a page number in the text box.

Exporting Log Events to a File

You can export the log events returned from a query to a file in Common Base Event (CBE) format.

To export events, click the Export button over the log. Only the log events currently displayed in the log viewer are exported. A file named LogExport.xml containing the log events is created.

You can choose to display the file or save it to disk in the file LogExport.xml.



Export displays the approximate processing time, and notifies you if an export function might take a long time. Logs will not be exported if the log count is greater than 30K, but a warning message displays.

Viewing Log Event DetailsThere are three ways to view details of a specific event in the Log:

• Click the Show Detail button above the Log. The Log Details area displays the details of the currently selected log event.

• Select a row in the Log, then right-click and select Show detail of this entry.

• Hover over the Creation Time column in the log event. A spyglass will display with the log details.

Figure 30 on page 328 shows an example log detail.

Figure 30 Log Detail

The log event details are displayed in five screens: Event Detail, Logical Component, Physical Component, Situation, and Additional Attributes.

Event Detail

The Event Detail screens shows the attributes of Base Event Format. See Table 109 on page 331.

Logical Component

The Logical Component screen shows the details of the components of the logical component ID. See Logical Component ID on page 331.



Physical Component

The Physical Component screen shows the details of the components of the physical component ID. See Physical Component ID on page 331.

Situation

The Situation screen shows the details of the situation that caused the log event to be generated. For the list of situation types and the contexts in which the situation applies, see the CBE specification at http://www.eclipse.org/tptp/platform/documents/resources/cbe101spec/CommonBaseEvent_SituationData_V1.0.1.pdf.

In the Situation screen, the structure of the URN field is constructed from situation details as follows:

• Start Situation startSituation:successDisposition:situationQualifier

• Stop Situation stopSituation:successDisposition:situationQualifier

• Connect Situation connectSituation:successDisposition:situationDisposition

• Configure Situation configureSituation:successDisposition

• Request Situation requestSituation:successDisposition:situationQualifier

• Feature Situation featureSituation:featureDisposition:

• Dependency Situation dependencySituation:dependencyDisposition

• Available Situation availableSituation:operationDisposition:availabilityDisposition:processingDisposition

• Create Situation createSituation:successDisposition

• Destroy Situation destroySituation:successDisposition

• Report Situation reportSituation:reportCategory

• Other Situation otherSituation

Additional Attributes

The Additional Attributes screen shows the attributes of the two models—Engine Event Format and BW Engine Event Format—that extend Base Event Format. See Table 111 on page 335 and Table 112 on page 335.

Event FormatsThis section provides attribute reference information for the event formats supported by the Log Viewer:





• Base Event Format Attribute Reference on page 331

• Engine Event Format Attribute Reference on page 335

• BW Engine Event Format Attribute Reference on page 335



Base Event Format Attribute Reference

Table 109 Base Event Format Attribute Reference

Attribute Description

Global Instance ID Globally unique identifier of the log event.

Creation Time The time the log event was created.

Location ID A physical address that corresponds to the location of a component.

Conversation ID An identifier of the conversation with which the log event is associated. Conversations span multiple message exchanges.

Context ID An identifier of the context with which the log event is associated.

Parent Context ID An identifier of the parent of the context with which the log event is associated.

Physical Component ID

Physical component identifier category. Subcategories are either generic or identified by a scheme. Contains a scheme field and fields defined by the scheme.

Generic Physical Component ID

A generic physical component identifier. Contains a scheme field and up to eight fields defined by the scheme. Used to search for log events that don't have a scheme or whose scheme is not supported by the Log Viewer. For example, an application could specify a Generic Physical Component ID with field1 named cluster_name and field2 called machine_name.

AMX Physical Component ID

An ActiveMatrix physical component identifier. The ActiveMatrix scheme identifier is amx. The ID is: amx#environment name#machine name#node name#container name.

Logical Component ID Logical component identifier category. Subcategories are either generic or identified by a scheme. Contains a scheme field and fields defined by the scheme.

Generic Logical Component ID

A generic logical component identifier. Contains a scheme field and up to eight fields defined by the scheme. Used to search for log events that don't have a scheme or whose scheme is not supported by the Log Viewer.

AMX Logical Component ID

An ActiveMatrix logical component identifier. The ActiveMatrix scheme identifier is amx. The ID is: amx#service assembly name#service unit name#service name#operation name.



Table 110 enumerates the situation types that cause components to log events and describes the types of contexts in which the situation applies.

Classifiers A set of name-value pairs. The name and the value are strings composed of any alphanumeric characters.

Supports searching for log events based on log event contents. For example, you could search for log records with the following classifiers:

classifierA: name=PONumber value=0001classifierB: name=BuyerName value=aBuyer

Situation The situation that caused the log event to be generated. For the list of situation types and the contexts in which the situation type applies, see Table 110.

Security Principal The authenticated entity that created the log event.

Msg ID Identifier of the log event message.

Msg The event message string.

Scheme The logger name’s type: amx or bw.

Logger Name The name of the destination for the log events.

Class Loader The class loader active at the time the event was logged.

Hierarchy The hierarchy of entities when the event was logged.

Table 109 Base Event Format Attribute Reference (Cont’d)


Table 110 Situation Types (Sheet 1 of 3)

Situation Type Description

StartSituation Deals with the component startup process. Messages indicate that a component has finished the startup process or that it has aborted the startup process. Existing messages include words such as: starting, started, initializing, and initialized.

StopSituation Deals with the component shutdown process. Messages indicate that a component has begun to stop, that it has stopped, or that the stopping process has failed. Existing messages include words such as: stop, stopping, stopped, completed, and exiting.



ConnectSituation Deals with aspects of a component’s connection to another component. Messages indicate that a connection failed, that a connection was created, or that a connection was ended. Existing messages include words such as: connection reset, connection failed, and failed to get a connection.

RequestSituation Deals with the situations that identify the completion status of a request. Typically these requests are complex management tasks or transactions that a component undertakes on behalf of a requestor and not the mainline simple requests or transactions. Existing messages include words such as: configuration synchronization started and backup procedure complete.

ConfigureSituation Deals with components identifying their configuration. Any changes that a component makes to its configuration or that describe current configuration state should be logged using this category. Existing messages include words such as: port number ID, address ID, and process ID.

AvailableSituation Deals with component operational state and availability. Provides a context for operations that can be performed on the component by distinguishing if a product is installed, operational and ready to process functional requests, or operational and ready or not ready to process management requests. Existing messages include words such as: ready to take requests, online, and offline.

ReportSituation Deals with the situations reported from the component, such as heartbeat or performance information. Messages indicate current CPU utilization and current memory heap size. Existing messages include words such as: utilization value is, buffer size is, and number of threads is.

CreateSituation Deals with the situations documenting when a component creates an entity. Messages indicate a document was created or a file was created. Existing messages include words such as: was created, about to create, and now exists.

DestroySituation Deals with the situations documenting when a component removes or destroys an entity. Messages indicate that a document was destroyed or a file was deleted. Existing message include words such as: was created, about to create, and now exists.





FeatureSituation Deals with the situations that announce that a feature of a component is ready (or not ready) for service requests. Message indicate services being available and services or features being unavailable. Existing messages include words such as: now available, currently available, and transport is listening on port 123.

DependencySituation Deals with the situations in which components cannot find some component or feature that they require. Messages indicate a resource was not found, that an application or subsystem that was unavailable, or that the expected version of a component was not found. Existing messages include words such as: could not find and no such component.

OtherSituation Provides support for product-specific situations other than the predefined categories.





Engine Event Format Attribute Reference

BW Engine Event Format Attribute Reference

Table 111 Engine Event Format Attribute Reference


Severity The perceived severity of the status the event is describing in the context of the application that reports the event:

• Debug Fine-grained informational events used for debugging an application.

• Info Coarse-grained informational messages that highlight the progress of the application.

• Warn Potentially harmful events.

• Error Application errors that allow the application to continue running.

• Fatal Very severe errors that will cause the process to abort.

Priority The importance of the event: Low, Medium, or High.

Thread ID The thread ID of the component or subcomponent that generated the event.

OS Process ID The ID of the operating system process hosting the engine.

Class Name The name of the class that implements the engine.

Table 112 BW Engine Event Format Attribute Reference


Host Name The name of the machine hosting the BusinessWorks engine.

Engine Name BusinessWorks engine name.

Job ID BusinessWorks job ID.

Process Name BusinessWorks process name.

Activity BusinessWorks activity name.

Project Name BusinessWorks project name.

Starter Name BusinessWorks process starter name.

Tracking Info BusinessWorks tracking identifier.



Custom ID BusinessWorks custom identifier.

Table 112 BW Engine Event Format Attribute Reference (Cont’d)



Server Logs | 337

Server Logs

Table 113 lists the locations of logs for all servers used in the ActiveMatrix runtime. The logs are text files and can be viewed in a text editor.

Table 113 Server Log Locations

Server Log Location

HSQLDB AMX_HOME/hsqldb/data/amx.log

Management Daemon ENV_HOME/managementdaemon/logs/managementdaemon.log.n

ActiveMatrix Administrator All logs are stored in AMX_ADMIN_HOME/data/logs/. The log file names for specific components are:

• Server cluster_server.log

• Audit Log cluster_server_audit.log

• Command-Line admincmdline.log

• Server Creation Utility amxadministrator.log

Enterprise Message Service Configured in tibemsd.conf. The default is no log.




| 339

Appendix A Securing TIBCO ActiveMatrix

Communication Channels

This appendix describes how to protect communication channels between TIBCO ActiveMatrix components.

Topics


• Keystores, page 342

• Enabling HTTPS for ActiveMatrix Administrator Servers, page 346

• Enabling SSL for Management Daemon, page 348

• Securing JDBC Connections, page 349

• Enabling Secure Connections Between Nodes and ActiveMatrix Components, page 351

• Enabling Secure Connections to Auxiliary Servers, page 355


340 | Appendix A Securing TIBCO ActiveMatrix Communication Channels

Overview

The TIBCO ActiveMatrix platform is partitioned across many components. These components communicate with each other and with third-party applications. The communication occurs by different communication protocols. The components and communication channels are illustrated in Figure 31 on page 341.

By default, these communication protocols are not secure. However, they can be secured by configuring the communication channels to use the Secure Sockets Layer (SSL) protocol. SSL is a cryptographic protocol that provides security and data integrity for communications over TCP/IP networks. SSL encrypts the segments of network connections at the Transport Layer end-to-end.

An SSL client and server negotiate a stateful connection by using a handshaking procedure. During this handshake, the client and server agree on various parameters to establish the connection's security. The handshake begins when a client connects to an SSL-enabled server requesting a secure connection. 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's public encryption key. The client may contact the server that issued the certificate (the trusted CA as above) and confirm that the certificate is authentic before proceeding.

This appendix describes the steps to protect TIBCO ActiveMatrix components. It describes the impact of those steps on other components in the system and details the steps to configure those components to communicate securely with the protected components.


Overview | 341

Figure 31 TIBCO ActiveMatrix Communication Channels

AM Machine 2Authentication Realm

AMAServer

AMA Graphical UI

Management Daemon

Database

Management Daemon

AM Node

AMA Command-Line

Interface

AM Machine 1

AM Node

Legend

AM

AMA

DE

TIBCO ActiveMatrix

TIBCO ActiveMatrix Administrator

Data Encryption

www

HTTPS HTTPS

JDBC/SSL DE

UDDI Registry

JMX/SSL

HTTPS

HTTPS

HTTPS

LDAP/SSL

JMX/SSL

JMX/SSL

JMX/SSL

JDBC/SSL, DE

TIBCO Enterprise Message Service

SSL

JMX/SSL

createadminserverdeleteadminserver

Utilties

LDAP/SSL



Keystores

This section describes how to configure TIBCO ActiveMatrix component keystores.

ActiveMatrix Administrator Server Keystores

Managing the Server Keystore

Installing a Server Certificate

The ActiveMatrix Administrator server loads the server certificate from the keystore located at:

AMX_ADMIN_HOME/data/cluster/server/config/servercerts

By default the servercerts keystore contains a self-signed test certificate. To use a commercial certificate:

1. Generate a key and a CSR in the servercerts keystore.

2. Obtain a server certificate from a CA using the CSR.

3. Import the server certificate into the servercerts keystore:

keytool -keystore AMX_ADMIN_HOME/data/cluster/server/config/servercerts -import -file servercert -storepass pramati

4. Restart the ActiveMatrix Administrator server from the command line: AMX_ADMIN_HOME/2.3/bin/ cluster_server.bat -uploadconfig.

Managing the Trusted Keystore

Configuring the Keystore Location and Password

To configure the ActiveMatrix Administrator server so that it loads trusted certificates from the trustedcacerts file, add the following property to the ActiveMatrix Administrator server TRA file (see ActiveMatrix Administrator Server on page 356):

java.property.javax.net.ssl.trustStorePassword.obfuscated=obfuscated password where obfuscated password is the trusted keystore password that has been obfuscated using the command for TIBCO encryption described in Creating an Obfuscated Password on page 28.


Keystores | 343

Importing Issuer Certificates

To import an issuer certificate into the trustedcacerts keystore execute the command:

keytool -keystore AMX_ADMIN_HOME/data/cluster/server/config/trustedcacerts -import -file cacert -storepass pramati

Restart the ActiveMatrix Administrator server using the -uploadconfig option from the command line every time a new certificate is imported into the trustedcacerts keystore.

Changing Keystore Passwords

The default password for the servercerts and trustedcacerts keystores is pramati.

To change the password of the server or trusted certificate keystore:

1. Open the ActiveMatrix Administrator TRA file (see ActiveMatrix Administrator Server on page 356).

2. Locate the string application.args and remove the command line argument -noshell true

3. Open a terminal window and run AMX_ADMIN_HOME/data/cluster/server/bin/cluster_server.exe.

4. At the command prompt j2eeadmin@admin> type secsh.

5. To change the server keystore password type help change_server_store_password and follow the instructions.

6. To change the trusted certificate password, type help change_trusted_store_password and follow the instructions.

ActiveMatrix Node Keystores

Installing a Server Certificate

ActiveMatrix nodes load the server certificate from the keystore located at:

AMX_HOME/data/environment/node/config/servercerts

To install a server certificate in an ActiveMatrix node, follow the procedure described in Installing a Server Certificate on page 342.




To manage the trusted keystore for an ActiveMatrix node, follow the procedures described in Managing the Trusted Keystore on page 342. The location of ActiveMatrix node TRA files is described in ActiveMatrix Node on page 356.

Restart the node using the -uploadconfig option from the command line every time a new certificate is imported into the trustedcacerts keystore. If there are multiple nodes in an environment, it is sufficient to do this for one node in that environment.

Changing Keystore Passwords

The default password for the servercerts and trustedcacerts keystores is pramati. To change keystore passwords for an ActiveMatrix node, follow the procedure described in Changing Keystore Passwords on page 343.

Management Daemon KeystoresManagement Daemon loads its server certificate from the keystore located at:

ENV_HOME/managementdaemon/2.0/config/configuration.keystore

The password for this keystore is specified in the configuration.xml file located in the same folder in the following XML element:

<password name=keyStorePassword">#!bXxkZESHjW95pKS0JiaM6HB9yRxvWm1Cyarg55U8Irk="</password>


To manage the trusted keystore for Management Daemon, follow the procedures described in Managing the Trusted Keystore on page 342. In the Management Daemon TRA file set the java.property.javax.net.ssl.trustStore property to any keystore that contains issuer certificates required by Management Daemon to communicate with other components. The location of the Management Daemon TRA file is described in Management Daemon on page 356):

The usage of the keystores should be consistent in all Management Daemon SSL configurations.


Keystores | 345

ActiveMatrix Administrator Command-line Tool Keystores


To manage the trusted keystore for the ActiveMatrix Administrator command-line tool to be consistent with other ActiveMatrix components, follow the procedures described in Managing the Trusted Keystore on page 342. In the ActiveMatrix Administrator command-line tool TRA file, set the java.property.javax.net.ssl.trustStore property to the same keystore that contains issuer certificates required by ActiveMatrix Administrator command-line tool to communicate with other components. The location of the ActiveMatrix Administrator command-line tool TRA file is described ActiveMatrix Administrator Command-line Tool on page 356. You can use the same keystore as that used by Management Daemon.



Enabling HTTPS for ActiveMatrix Administrator Servers

ActiveMatrix Administrator servers are accessed from a browser and from the ActiveMatrix Administrator command-line tool over the HTTP protocol. The ActiveMatrix Administrator server is a web application deployed and run inside a web server. By default the web server starts an HTTP listener. To protect communication between a browser and an ActiveMatrix Administrator server, you enable the HTTPS listener.

Enabling HTTPS for ActiveMatrix Administrator servers involves three steps:

1. Install an ActiveMatrix Administrator server certificate into the ActiveMatrix Administrator server keystore following the procedure in Installing a Server Certificate on page 343.

2. Enable HTTPS in the ActiveMatrix Administrator configuration file.

3. Enable HTTPS in ActiveMatrix Administrator server clients.

Setting up ActiveMatrix Administrator KeystoresFor the details on how to set up the keystores used by ActiveMatrix Administrator server see ActiveMatrix Administrator Server Keystores on page 342.

Enabling HTTPS in ActiveMatrix Administrator ServerTo enable HTTPS in an ActiveMatrix Administrator server:

1. Open the file AMX_ADMIN_HOME/data/cluster/server/config/web-config.xml.

2. Search for the element ssl-enabled and set the value to true.

The HTTPS port used by this server is defined in AMX_ADMIN_HOME/data/cluster/server/config/server-config.xml by the property https-port.

3. To disable the HTTP port, set the property http-enabled to false.

4. Restart the ActiveMatrix Administrator server from the command line: AMX_ADMIN_HOME/2.3/bin/ cluster_server.bat -uploadconfig.


Enabling HTTPS for ActiveMatrix Administrator Servers | 347

Enabling HTTPS in ActiveMatrix Administrator ClientsActiveMatrix nodes, Management Daemon, and the ActiveMatrix Administrator command-line tool all communicate with ActiveMatrix Administrator server on HTTP as clients. If the ActiveMatrix Administrator server is enabled with HTTPS, then configure each of these components to access ActiveMatrix Administrator on HTTPS.

Enabling HTTPS in ActiveMatrix Nodes

To enable HTTPS in ActiveMatrix nodes:

1. Edit the file AMX_HOME/data/environment/node/config/security-config.xml.

2. Change the value of the two instances of scheme property from http to https.

3. Import the issuer certificate of the ActiveMatrix Administrator server into the trusted certificate store of the node. For the details on the keystores used by ActiveMatrix nodes see ActiveMatrix Node Keystores on page 343.

4. Restart the node from the command line using the following command: AMX_HOME/data/environment/node/environment_node.exe -uploadconfig.

Enabling HTTPS in Management Daemon

Management Daemon communicates with ActiveMatrix Administrator server on HTTPS. Therefore, when ActiveMatrix Administrator server is enabled with HTTPS import the issuer certificate of the ActiveMatrix Administrator server into the trusted certificate store of Management Daemon following the procedures described in Management Daemon Keystores on page 344.

Enabling HTTPS in ActiveMatrix Administrator Command-line Tool

To enable the ActiveMatrix Administrator command-line tool to communicate with ActiveMatrix Administrator server using HTTPS:

1. Change the URL in the Ant build file to use the https protocol instead of http.

2. Import the issuer certificate of the ActiveMatrix Administrator server into the trusted certificate store of the command-line tool following the procedures described in ActiveMatrix Administrator Command-line Tool Keystores on page 345.



Enabling SSL for Management Daemon

By default Management Daemon is configured to use SSL. The configuration can be found in the file ENV_HOME/managementdaemon/2.0/config/configuration.xml and it uses the keystore located in the same folder to load the server certificate. Refer to Management Daemon Keystores on page 344 for more details.

Additional configuration required for Management Daemon to communicate over SSL with other components is described in the context of those components.


Securing JDBC Connections | 349

Securing JDBC Connections

TIBCO ActiveMatrix components use JDBC connections to access application and authentication data. The Oracle database server supports a variety of security features under its Advanced Security Option (ASO). For complete details on ASO refer to Oracle's documentation.

TIBCO ActiveMatrix supports two types of Oracle database drivers: DataDirect and Oracle native thin. TIBCO ActiveMatrix packages and supports DataDirect drivers for Oracle. TIBCO ActiveMatrix supports Oracle native thin drivers but does not ship these drivers. Before you can use this driver in any TIBCO ActiveMatrix components you must package it as a feature and deploy it to the environment following the instructions in Post-Installation Procedures in the installation manual for your product.

DataDirect's JDBC driver does not support native data encryption in Oracle's ASO, however it supports SSL. For further information, see:

http://www.datadirect.com/products/security/documentation/wwhelp/wwhimpl/js/html/wwhelp.htm

Oracle's native thin driver supports all the features available in ASO. This section focuses on three features of ASO: SSL, data encryption, and data integrity.

This section describes how to configure secure JDBC connections to Oracle databases for the two supported drivers.

Oracle Native Thin DriverOracle native thin drivers support all the features of the ASO. TIBCO ActiveMatrix supports data encryption and data integrity. This section describes the steps to configure these security features in various types of components.

Data Encryption

Task A Configure Data Encryption in Oracle Server

For the steps to configure data encryption in Oracle server, refer to the Oracle documentation.


http://www.datadirect.com/products/security/documentation/wwhelp/wwhimpl/js/html/wwhelp.htm


Task B Configure Data Encryption in ActiveMatrix Clients

To encrypt the JDBC data from the createadminserver and deleteadminserver utilities, ActiveMatrix Administrator server, Management Daemon, and ActiveMatrix nodes to an Oracle server:

1. Add the following properties to the TRA file (see TRA File Locations on page 356) of each component:

java.property.oracle.net.encryption_types_client=Encryption Algorithm

For the names of the supported encryption algorithms, refer to the Oracle documentation.java.property.oracle.net.encryption_client=REQUIRED

2. Restart the component.

Data Integrity

Task A Configure Data Integrity in Oracle Server

For the steps to configure data integrity in Oracle server, refer to the Oracle documentation.

Task B Configure Data Integrity in ActiveMatrix Clients

To ensure the integrity of JDBC data from the createadminserver and deleteadminserver utilities, ActiveMatrix Administrator server, Management Daemon, and ActiveMatrix nodes to an Oracle server:

1. Add the following properties to the TRA file (see TRA File Locations on page 356) of each component:

java.property oracle.net.crypto_checksum_types_client = Checksum Algorithm

For the names of the supported checksum algorithms, refer to the Oracle documentation.

java.property.oracle.net.crypto_checksum_client = REQUIRED

2. Restart the component after adding the properties.


Enabling Secure Connections Between Nodes and ActiveMatrix Components | 351

Enabling Secure Connections Between Nodes and ActiveMatrix

Components

Enabling Secure Communications Between Nodes and Messaging ServersYou can secure connections between nodes and messaging servers only when the connection to the messaging server is achieved via JNDI lookup. To secure communication for all the nodes in an environment you configure the messaging server to use SSL and configure SSL in the Enterprise Message Service server for the ActiveMatrix node clients. The following sections contain the steps to configure messaging server authentication to ActiveMatrix nodes and how to configure ActiveMatrix node client authentication to messaging servers.

Configuring Messaging Server

To configure messaging server to use SSL:

1. In the ActiveMatrix Administrator UI Configure Enterprise Assets Perspective, select Shared Resource Definitions.

2. Select New > JNDI.

In the Application Properties area, add the following properties and values prepending each property name with com.tibco.tibjms.naming.

Table 114 JNDI SSL Application Properties


security_protocol ssl ssl is the only security protocol supported. Required.

ssl_vendor entrust61 entrust61 is the only supported vendor. Required.

ssl_enable_verify_host true Specifies whether the client should verify the server’s certificate. Required.



3. In the ActiveMatrix Administrator UI Configure Enterprise Assets Perspective, select an environment in the Environments table.

4. In the environment details area, click the Messaging Bus link.

5. In the Messaging Servers table, click Add.

a. In the Connection Type drop-down list, select JNDI.

b. If you want to enable client authentication for the nodes, set the Client Certificate Password field to the password of the client certificate used by the nodes accessing the server. You must also set the ssl_identity

ssl_enable_verify_hostname true Set to true if the name on the server's certificate must be verified against the server's hostname. If the server's hostname is different than the name on the certificate, SSL connection will fail. The name on the certificate can be verified against another name by specifying the ssl_expected_hostname property.

ssl_trusted_certs /certs/server_root.cer.pem Contains the CAs the client trusts for server verification. Required only if ssl_enable_verify_host is set to true.

ssl_expected_hostname server Hostname given at the time of creating the certificate. Required only if ssl_enable_verify_hostname is set to true. Required.

ssl_trace true May be specified for SSL tracing.

ssl_debug_trace true May be specified for SSL debug tracing.

Table 114 JNDI SSL Application Properties (Cont’d)



Enabling Secure Connections Between Nodes and ActiveMatrix Components | 353

property, described in the following section, in the TIBCO Enterprise Message Service server configuration file.

Configuring SSL in TIBCO Enterprise Message Service Server

To configure SSL in TIBCO Enterprise Message Service server:

1. Create an SSL connection factory in the TIBCO Enterprise Message Service server by adding the following properties to ENV_HOME/ems/version/bin/factories.conf:

[SSLGenericConnectionFactory]type = genericurl = ssl://7243ssl_vendor = entrust61ssl_verify_host = enabled

ssl_trusted = certs/server_root.cert.pem

ssl_identity = certs/client_identity.p12

ssl_verify_hostname = enabled

ssl_expected_hostname = server


Enabling Secure Connections Between Nodes and ActiveMatrix ServersActiveMatrix Administrator servers and Management Daemon communicate with ActiveMatrix nodes using Java Management Extension (JMX) protocol. In addition, ActiveMatrix nodes communicate with each other over JMX. To protect the communication between the JMX servers you can enable SSL for the JMX server in ActiveMatrix nodes. If you enable SSL, you must do it for all the nodes in an environment.

Enabling JMX/SSL for ActiveMatrix Nodes

Enabling JMX/SSL involves the following steps:

1. Import certificates into the last node added to the environment and restart the node to upload the changed configuration.

ActiveMatrix nodes act as clients to each other over JMX/SSL. Therefore you must import the issuer certificate of the server certificate used by all nodes in

ssl_identity is required only if you want ActiveMatrix nodes to authenticate themselves to the messaging server. If this property is set, then set the client certificate password when you create the messaging server.



the environment into the trusted certificate keystore of the last ActiveMatrix node added to the environment. Refer to ActiveMatrix Node Keystores on page 343 for details on the location of the keystore.

2. Import certificates into the trusted keystores of ActiveMatrix Administrator and Management Daemon.

ActiveMatrix Administrator and Management Daemon act as JMX/SSL clients, Therefore you must import the issuer certificate of the server certificate of the ActiveMatrix nodes into the trusted certificate keystores of those components. Refer to Managing the Trusted Keystore on page 342 and Managing the Trusted Keystore on page 345 for the details on the location of the keystores.

You import the certificates into the last node added to the environment as follows:

a. Import the server certificate into the node’s server keystore.

b. Import the issuer certificate into the trusted keystore.

c. Restart the node from the command line using the following command: AMX_HOME/data/environment/node/environment_node.exe -uploadconfig.

3. Enable JMX/SSL in the nodes’ configuration file:

a. Edit the file:

AMX_HOME/data/environment/node/config/server-config.xml

b. Set the value of the ssl-protocol-enabled attribute of the rmi-properties element to true.

c. Restart the nodes.


Enabling Secure Connections to Auxiliary Servers | 355

Enabling Secure Connections to Auxiliary Servers

This section describes how to enable secure connections to auxiliary servers.

Enabling Secure Connections to LDAP ServersActiveMatrix Administrator supports the LDAP authentication realm. The ActiveMatrix Administrator server and the ActiveMatrix Administrator server management utilities createadminserver and deleteadminserver can be configured to access the LDAP server over SSL. When ActiveMatrix Administrator server and utilities are configured to access the LDAP server over SSL, they act as an SSL client to the LDAP server.

To enable SSL connections between ActiveMatrix Administrator servers and server management utilities and the LDAP server:

1. Check the Use SSL checkbox when you configure the LDAP authentication realm for an ActiveMatrix Administrator cluster. See LDAP Realm on page 39.

2. Import the issuer certificate of the LDAP server certificate into the ActiveMatrix Administrator trusted certificate keystore. Refer to ActiveMatrix Administrator Server Keystores on page 342 for the location of keystore.

3. Import the issuer certificate of the LDAP server certificate into the createadminserver and deleteadminserver trusted certificate keystore. Refer to Management Daemon Keystores on page 344 for the location of keystore.

Enabling Secure Connections to UDDI ServersActiveMatrix Administrator allows you to publish services to UDDI registries. When a UDDI server is configured with HTTPS, the ActiveMatrix Administrator server acts as an SSL client to the UDDI server.

To enable SSL connections between ActiveMatrix Administrator servers and the UDDI server:

1. Specify the HTTPS protocol in the URLs you provide when you add the UDDI server to the enterprise. See Adding a UDDI Server on page 156.

2. Import the issues certificate of the UDDI Registry server certificate into the ActiveMatrix Administrator trusted certificate keystore. Refer to ActiveMatrix Administrator Server Keystores on page 342 for the location of the keystore.



TRA File Locations

To enable security features requires you to add properties to ActiveMatrix component TRA files. Table 115 lists the locations of the TRA files:

Table 115 TRA File Locations

Component TRA File Location

ActiveMatrix Administrator Server

AMX_ADMIN_HOME/data/cluster/server/cluster_server.tra

ActiveMatrix Node AMX_HOME/data/environment/node/environment_node.tra or AMX_HOME/2.3/server/bin/server.tra

Management Daemon ENV_HOME/managementdaemon/2.0/bin/managementdaemon.tra

ActiveMatrix Administrator Command-line Tool

AMX_ADMIN_HOME/2.3/bin/admincmdline.tra

createadminserver

deleteadminserver

AMX_ADMIN_HOME/2.3/bin/createadminserver.tra

AMX_ADMIN_HOME/2.3/bin/deleteadminserver.tra


| 357

Appendix B Messaging Scenarios for In-only MEPs

This appendix describes mechanisms for handling message loss scenarios in services that use In-only MEPs.

To prevent message loss when processing In-only MEPs in addition to the configuration steps described in this appendix you must also enable guaranteed message delivery (which by default is disabled) in the Messaging Bus. You enable guaranteed message delivery by configuring the Messaging Bus' quality of service as At Least Once (see Quality of Service on page 176).

Guaranteed message delivery incurs overhead, because messages are persisted in TIBCO Enterprise Message Service server and message delivery is transacted. TIBCO Enterprise Message Service 4.4 is the minimum required version for guaranteed message delivery.

Topics

• Race Condition Between Consumer and Provider, page 358

• Messages In AMX Binding Queue, page 359

• Messages in JMS Container Queue, page 361


358 | Appendix B Messaging Scenarios for In-only MEPs

Race Condition Between Consumer and Provider

During the startup of a service assembly messages received in the interval between the startup of a consumer service unit and its associated provider service unit are sometimes lost and result in a "Provider not up" error. To mitigate message loss, you can configure the retry count and the interval between retries of AMX bindings by specifying the following properties in the node’s TRA file: AMX_HOME/data/environment/node/bin/environment_node.tra.

java.property.com.tibco.matrix.amxframework.messaging.targetendpoint.retrycount

java.property.com.tibco.matrix.amxframework.messaging.targetendpoint.retryinterval

AMX binding reports "Provider not up" only after retrying a configurable number of times and it is expected that provider will eventually come up during the retries. The default value for these properties are 0 and 1 second, so by default retry is not enabled. After modifying the properties, restart the node.


Messages In AMX Binding Queue | 359

Messages In AMX Binding Queue

This section describes the behavior of the ActiveMatrix runtime in various scenarios when messages are handled by AMX bindings.

• An AMX binding fetches a message from its queue, delegates the message to provider, but the provider is not able to process the message and throws javax.transaction.TransactionRolledbackException.

The error is sent back to the AMX binding. The AMX binding performs a JMS local transaction and commits in case of success and rolls back in case of failure. A rollback causes the message to be delivered again immediately, which is not desired behavior. To mimic timeout redelivery, you can configure ActiveMatrix to perform a delayed rollback by specifying the property java.property.com.tibco.matrix.amxframework.messaging.redeliver

y.timeout (default value 10 seconds) in the node’s TRA file: AMX_HOME/data/environment/node/bin/environment_node.tra.

To avoid overloading the system with a wrong message, after certain number of failed redelivery attempts the message is put on an error queue. You can configure the redelivery count by specifying the property java.property.com.tibco.matrix.amxframework.messaging.redeliver

y.maxcount (default value 30) in the TRA file.

The Enterprise Message Service error queue, which is $sys.undelivered, is used for error messages. Before the error message is put on the error queue, the following properties are set for postprocessing: SourceDestinationName (Provider queue name), SourceDestinationType (Provider queue type) and DeliveryFailureReason (The reason behind delivery failure).

• An AMX binding fetches message from its queue, delegates the message to provider but provider is not able to process the message but it also wants message to be discarded. So it throws any exception other than TransactionRolledbackException.

AMX binding checks that the exception is not TransactionRolledbackException and removes the message from original queue, puts it on the error queue, and logs the exception.

• An AMX binding fetches message from its queue. Before the provider can process the message some unforeseen event, for example a node crash, occurs.

A message is committed only upon successful return from provider. If a node crashes before that, the message does not get committed so it will still be on AMX binding queue. On node restart the message will be delivered again.



• An AMX binding fetches a message from its queue and delegates the message to the provider. The provider does not process the message but does not throw any error.

The message will be removed from the queue. A provider should throw an exception for message to be delivered again.


Messages in JMS Container Queue | 361

Messages in JMS Container Queue

This section describes the behavior of the ActiveMatrix runtime in various scenarios when messages are handled by JMS bindings.

• The JMS container fetches a message from its queue and delegates the message to AMX binding. The AMX binding reports a "Provider is not up" error.

AMX binding reports "Provider is not up" only after retrying (see Messages In AMX Binding Queue on page 359). Spline layer is fixed for reporting the error back to JMS container. On error the JMS container puts the message on an error queue named SourceQueue.errorqueue.

• The JMS container fetches a message from its queue and delegates the message to AMX binding. The AMX binding is not able to put message to AMX provider queue, and throws an error back to the JMS container. The message delivery is guaranteed only in case when the service assembly is deployed with the prefer local provider property set to false.

On error the JMS container puts the message on the corresponding error queue. It should be noted that message delivery is not retried in the same manner as the AMX binding. If the JMS binding is not able to put message on a provider queue, there is a good chance that Enterprise Message Service server is down and if will remain down for some time. So whatever retry logic is put in JMS container, it’s likely that the message will end up in the error queue eventually.

• The JMS container fetches message from its queue. The format of message is wrong and ActiveMatrix reports a "Wrong format format" error.

JMS container will send a message to the corresponding error queue.

• The JMS container fetches message from its queue. The node crashes when message is somewhere in memory before being put on provider queue.

The JMS container acknowledges the message only upon successful delivery to AMX binding. In this case the message will not get acknowledged and will remain in the JMS container queue. When node restarts the message will be processed again.




| 363

Appendix C Session and Thread Pools

This appendix describes the session and thread pools provided by the ActiveMatrix Messaging Bus implementation.

Topics


• Usage, page 366

• Interaction, page 367

• Best Practices, page 368


364 | Appendix C Session and Thread Pools

Overview

The session and thread pool configuration influences the message processing on a ActiveMatrix node vis-à-vis service providers and consumers. Session and thread pool configuration enables fine-grained control over appropriation of such resources as JMS sessions and threads enabling efficient management of message flows depending on certain business criteria (for example, expected quality of service). It is important to understand the implication of session and thread pool configuration on the system and their inter-relationships.

Definitions

Session and Session Pool

The session represents a JMS session. A session may create and service multiple message producers and consumers. The sessioncount property represents a pool of such session objects. The session is used by the JMS provider to process one or more messages that have arrived.

Thread and Thread Pool

The thread pool implemented by ActiveMatrix Messaging Bus is intended to provide flexibility for concurrent message processing. Availability of thread pool to the service has the potential for better performance, throughput and scaling, only limited by the available system resources.

Configuration PropertiesThere are two system properties defined in a node TRA file, located in AMX_HOME/data/environment/node/bin/environment_node.tra. You can edit these properties at any time. The node must be restarted to apply the new settings.

java.property.com.tibco.matrix.amxframework.messaging.maxpoolsize

This property determines the maximum thread pool size. This property is applicable to every service deployed on that node. The threads in the thread pool are used to deliver and process the messages for the service.

java.property.com.tibco.matrix.amxframework.messaging.sessioncount

This property determines the maximum number of JMS sessions that may be created to handle incoming messages from the server. Like max thread pool property, this property also applies to every service deployed on that node.


Overview | 365

Session Count and Max Pool Size Normalization

maxpoolsize must be greater than or equal to sessioncount. If maxpoolsize is less than sessioncount then the sessioncount is made equal to maxpoolsize. The normalization of such a configuration enhances message reliability as it limits the sessions (for message delivery) to same as thread pool size (for message processing).

Life Cycle

StartThe sessions and thread pool are created when the service is started. The thread pool may contain minimum number of threads during its creation. Additional threads may be created as required until pool size reaches maximum count.

StopThe sessions and thread pool are removed when the service is stopped. The thread pool does orderly shutdown by finishing all running threads.



Usage

The session and thread pool are intertwined when it comes to message processing. In case of distributed message processing, the JMS provider tries to get a session object from the session pool to deliver the messages. The session object in turn tries to get a thread from the thread pool thus providing thread of control to invoke message listeners.

The session pool may serve as throttling mechanism to limit the delivery of messages from the Enterprise Message Service server. This architecture provides tremendous reliability to the application as messages are safely stored in the Enterprise Message Service server instead of getting backed up in the application process.

The thread pool may serve as sandbox available to every service for concurrent message processing. It avoids any interference or contention for threads by other services running in the node.


Interaction | 367

Interaction

The services, components, and references in a composite are internally wired through ActiveMatrix bindings. Like all other bindings, there is ActiveMatrix service and ActiveMatrix reference. Each port type is assigned a corresponding ActiveMatrix binding during serialization to a composite file.

The initialization of an ActiveMatrix service results in the creation of sessions and thread pool for the service. If a component is both provider and a consumer then the thread pool is shared for requests (from consumers) and responses (from services it consumes).

The initialization of an ActiveMatrix reference also results in the creation of sessions and thread pool for the consumer to process the responses. It must be noted that if consumer is invoking one way message exchanges (that is, in-only) then no session or thread pool is created. But if the consumer is invoking request-response (that is, in-out) type of message exchanges then session and thread pool is created to process the responses.

The properties are configured in the node’s .tra file so it is coarse grained as it applies to all services deployed in that node.

Table 116 maps the session and thread pool creation vis-à-vis consumer-provider roles and message exchange patterns.

Table 116 Role (Consumer/Provider), MEP, and Session/Thread Pool

MEP in-only in-out out-only out-in

Role C P C P C P C P

Session

Pool

N Y Y Y Y N Y Y

Thread

Pool

N Y Y Y Y N Y Y



Best Practices

Session Count and Max Pool Size

The maxpoolsize property almost always must be set to higher value than session count. The rationale being the system resource (that is, a thread from the thread pool) must be always available when the message is received from Enterprise Message Service server for processing. It is best to control message flow limit via sessioncount property so that message delivery is blocked until a session is available. That results in more reliable message delivery since the messages continue to be persisted in Enterprise Message Service server.

Service Optimization

Service message processing optimization is possible by fine tuning the sessioncount and maxpoolsize properties based on some pre-defined business criteria for e.g. average response time. By increasing the sessioncount and maxpoolsize for a service enables the messaging bus to dramatically increase concurrent message delivery and processing. This is especially useful in case of services whose average response time is very small or services whose throughput must be high.

Since every service has its own session and thread pool the services that have demanding QoS (quality of service) may not be affected by “slower” services deployed on the same node as the “slower” services will have its own session and thread pool to process its messages.

Local Invocations

It must be noted that the sessioncount property is only applicable for messages exchanged in a distributed environment i.e. messages delivered by Enterprise Message Service server. The maxpoolsize property is applicable for both local and distributed service invocation. The message delivery and its subsequent processing rely on making one of the available threads from the thread pool as the thread of control. It is particularly important to set maxpoolsize value higher than the sessioncount if the service is expected to be invoked by both local and remote consumers. For example, if the service is expected to be invoked in equal measure by local and remote consumers then desirable maxpoolsize is two times the value of sessioncount.

In case of local invocation, one of the available threads from thread pool is utilized to initiate the provider processing. If thread pool does not have idle threads then the processing will continue on the consumer’s thread.


Best Practices | 369

Session Release

The JMS session is not released back to the session pool until the message listener is finished. Since the message listener invokes the service synchronously the session is blocked until the service processing is complete. This makes message delivery more reliable as newer messages are not delivered until there is session available from the session pool.




| 371

Appendix D ActiveMatrix Server Performance Tuning

This appendix covers various options that can be modified to tune the performance of ActiveMatrix Administrator servers and Management Daemon processes.

Topics


• JVM Configuration, page 373

• ActiveMatrix Administrator Server Configuration, page 376


372 | Appendix D ActiveMatrix Server Performance Tuning

Overview

The use cases this appendix addresses are:

• Production environments

• Non-production environments

These two use cases have different requirements. In production environments load can be high and faster response time is more important. In non-production environments the load is minimal and the memory footprint is expected to be low. The factors discussed in the following sections can be managed according to the use case. These factors can be categorized into two categories:

• JVM Configuration on page 373

• ActiveMatrix Administrator Server Configuration on page 376

The factors discussed in the JVM section are applicable to both ActiveMatrix Administrator server and Management Daemon. The factors discussed in the ActiveMatrix Administrator Server section are applicable only to the ActiveMatrix Administrator server.


JVM Configuration | 373

JVM Configuration

Both ActiveMatrix Administrator server and Management Daemon are Java-based software systems. Hence in both cases you can make modifications to the Java Virtual Machine (JVM) configuration to achieve desired performance. This section describes some of these modifications, which you perform in the following TRA configuration files:

• ActiveMatrix Administrator AMX_ADMIN_HOME/data/cluster/server/bin/cluster_server.tra

• Management Daemon ENV_HOME/managementdaemon/2.0/bin/managementdaemon.tra

Using Client and Server ModesThe JVM used to run ActiveMatrix Administrator server and Management Daemon can run in one of two modes: client or server. Table 117 shows some of the differences between the modes:.

In addition, when client mode is used, the JVM de-allocates unused memory space faster.

Table 117 JVM Client and Server Mode Properties

Server Client

Application Types

Intended for executing long-running server applications, which need the fastest possible operating speed. Specially tuned to maximize peak operating speed.

Intended for executing applications with shorter life span which need fast start-up time or smaller runtime memory footprint.

Startup Time Slower startup time as the compiler tries to proactively perform all possible optimizations.

Faster startup time as the compiler does not try to execute complex optimizations.

Memory Usage More code optimizations require a larger footprint. This option requires a larger memory footprint.

As the client doesn't perform optimizations proactively, it requires a smaller memory footprint.



Both ActiveMatrix Administrator and Management Daemon have client mode enabled by default. This is the ideal option for environments which require these processes to run with low memory footprint. In production environments though, these should be updated to use server mode. The relevant TRA file properties are tibco.env.JVM_LIB_PATH and tibco.env.JVM_LIB_DIR. In the following example the -client option is active:

#tibco.env.JVM_LIB_PATH=%TIBCO_JVM_LIB_SERVER_ESC%tibco.env.JVM_LIB_PATH=%TIBCO_JVM_LIB_CLIENT_ESC%#tibco.env.JVM_LIB_DIR=%TIBCO_JVM_LIB_SERVER_DIR_ESC%tibco.env.JVM_LIB_DIR=%TIBCO_JVM_LIB_DIR_ESC%

If the value of ENV_HOME is C:/tibco, the properties would be:

#tibco.env.JVM_LIB_PATH=C:/tibco/tibcojre/1.5.0/bin/server/jvm.dlltibco.env.JVM_LIB_PATH=C:/tibco/tibcojre/1.5.0/bin/client/jvm.dll#tibco.env.JVM_LIB_DIR=C:/tibco/tibcojre/1.5.0/bin/servertibco.env.JVM_LIB_DIR=C:/tibco/tibcojre/1.5.0/bin/client

To switch from client (default) to server mode, uncomment the server options and comment the client options.

Allocated Memory SizePerformance is affected by size of the allocated memory and garbage collection (GC) mechanisms. Memory is managed in generations as memory pools holding objects of different ages. GC occurs in each generation when the memory fills up. Allocating insufficient amount of memory can lead to OutOfMemory exceptions. To avoid this situation, make sure that enough memory is allocated to the VM. These values can be set based on a continuous monitoring of the system.

Heap Size

Objects in Java are created using the new operator. The JVM allocates memory for these objects at runtime. This memory is finite and can be exhausted if too many objects are created. When this happens, the VM throws an OutOfMemory exception.

To avoid this situation, make sure that enough heap memory is allocated to the VM. In the TRA file, these settings are specified in the java.heap.size.initial and java.heap.size.max properties.

On Linux, the value of java.heap.size.max controls the size of the virtual memory allocated. This behavior is different from the behavior on Windows. On Windows, the size of the virtual memory is close to the actual memory allocated. Hence for non-production environments running on Linux, if VM size is a concern, the memory size specified in java.heap.size.max can be lowered.


JVM Configuration | 375

Permanent Generation Size

The TRA file also specifies a PermSize attribute of the java.extended.properties property. This is the part of the memory where classes and long term objects are loaded. Currently, for ActiveMatrix Administrator, the lower bound is set at 64 MB and higher bound at 128 MB. In cases where there are requirements to support more resource intensive service engines, the higher bound can be increased. More plug-ins mean more space is required for loading the classes. An OutOfMemory exception generated because of permanent generation size will mention 'PermGen space' in the exception message.



ActiveMatrix Administrator Server Configuration

ActiveMatrix Administrator server runs as an application on a web server. The web server spawns worker threads to support the load experienced by applications. The following sections discuss two settings that control the number of threads that web server creates in the file: AMX_ADMIN_HOME/data/cluster/server/config/webconfig.xml. After updating web-config.xml, the ActiveMatrix Administrator server must be started once from the command line with the -uploadconfig parameter. All instances in an ActiveMatrix Administrator cluster share the uploaded parameters.

Number of Web-worker ThreadsWorker-thread count is the number of requests that can be processed concurrently by the web server. The entry in web-config.xml is:

<worker-thread-count>15</worker-thread-count>

The default value is 15. The value can be modified as follows:

• For a lower request rate with high process time, you can set the count to 20 or 30. If set to a higher value, the inactive threads consume memory and flood the listener sockets to check with new requests. This degrades the VM performance.

• For a high load server, the count can be 200 or more. If set to a lower value, many requests are queued before they can be processed.

• Web sites with many hits but less processing time, static pages, and dynamic pages with lower process times should have high worker thread count. Web sites having high processing time with comparably low hit rate, the worker thread count value should be lower.

Acceptor-Thread CountAcceptor-thread count is the number of threads that accept client connections. The entry in web-config.xml is:

<acceptor-thread-count>3</acceptor-thread-count>

The default value is 3. The value can be increased depending on the load on the server.

The value can be decreased to 1/10th of total number requests received at peak loads collected by statistics.


| 377

Appendix E Publishing Services to ActiveMatrix Registry

Topics

• Enabling Non-Administrator Users to Publish to the ActiveMatrix Registry, page 378

• Adding Permission to Publish to a Business, page 380


378 | Appendix E Publishing Services to ActiveMatrix Registry

Enabling Non-Administrator Users to Publish to the ActiveMatrix

Registry

This section describes how to publish to the ActiveMatrix Registry when you are a non-admin user of the ActiveMatrix Registry.

The UDDI publish functionality in ActiveMatrix Administrator generates custom UDDI keys (of the form uddi:custom-key-generator:custom-key) rather than standard UDDI keys generated by the ActiveMatrix Registry. Custom keys can be accepted by the ActiveMatrix Registry either if they are being used by the admin user, or by a non-administrator user who has ownership of a tModel in the UDDI server named uddi:custom-key-generator:keyGenerator. To transfer ownership of a tModel to a non-administrator user, start and log in to the ActiveMatrix Registry Administration Console and follow the tasks listed below. For details on the Administration Console see the ActiveMatrix Registry product documentation.

Task C Add a Non-Administrator User

1. Log in to the ActiveMatrix Registry Administration Console as the admin user.

2. Click MANAGE.

3. Click Account management.

4. Click Create Account

5. Edit the required fields.

6. Click Create account.

Task D Add a tModel

1. Click the PUBLISH tab.

2. In the Publish area, click Add tModel.

3. In the name field, enter a name for the tModel.

4. In the tModel key field, enter uddi:amx:keyGenerator.

5. Click Add tModel.

Task E Create the Transfer Token

1. Click Custody transfer.

2. Click Request transfer token.


Enabling Non-Administrator Users to Publish to the ActiveMatrix Registry | 379

3. Check the checkbox next to the tModel you created in Task D, Add a tModel, on page 378.

4. Click Request transfer token.

5. Click Save to file.

6. Log out of the ActiveMatrix Registry Administration Console.

Task F Transfer Custody to a Non-Administrator User

Log in as non-admin user you created in Task C, Add a Non-Administrator User, on page 378.

1. Click PUBLISH.

2. Click Custody transfer.

3. Click Transfer custody.

4. Click Browse and navigate to the file you saved in Task E, Create the Transfer Token, on page 378.

5. Click the file and click Open.

6. Click Load from file.

7. Click Transfer.

8. Click PUBLISH.

9. Expand the tModels node. Notice that the tModel you created in Task D, Add a tModel, on page 378 has been added.


380 | Appendix E Publishing Services to ActiveMatrix Registry

Adding Permission to Publish to a Business

To add permission to a publish to a business to the system#everyone group:

1. Click MANAGE.

2. Click Search.

3. Click Find business.

4. Click the business.

5. Click Edit.

6. Click the Permissions tab.

7. Click the group radio button.

8. Check the system#everyone checkbox.

9. Click Add selected groups.

10. Click the edit icon in the system#everyone row.

11. Select allowed in all the drop-down lists.

12. Click Save changes.


| 381

Appendix F checkstatus Utility

The checkstatus utility compares the state of ActiveMatrix runtime objects to an expected state and reports the result.

Topics

• checkstatus, page 382

• StatusCheckerConfig.properties, page 384


382 | Appendix F checkstatus Utility

checkstatusCommand

Syntax All Platforms

ant -f AMX_ADMIN_HOME/utilities/samples/build.xml

Windows

AMX_ADMIN_HOME/utilities/samples/checkstatus.bat

UNIX

AMX_ADMIN_HOME/utilities/samples/checkstatus.sh

Description Compares the state of ActiveMatrix runtime objects to an expected state and reports the result. The state is checked at a specified interval until a specified timeout. The supported runtime objects are:

• TIBCO Management Daemon

• Nodes

• Services assemblies

• Shared resources

To use this command, create a properties file:

AMX_ADMIN_HOME/utilities/samples/StatusCheckerConfig.properties

The folder AMX_ADMIN_HOME/utilities/samples/ contains a template properties file:

AMX_ADMIN_HOME/utilities/samples/StatusCheckerConfig.properties_template

Exit Codes If successful, the exit code is 0. If a timeout occurs, the exit code is 1.

Example Output Successful State Match

When the expected state matches the actual state, checkstatus reports:

[INFO] Redirect requested but followRedirects is disabledStatus check successful!

Timeout

[INFO] Redirect requested but followRedirects is disabledWarning The status "Installed/Stopped" of node node2(environment: development) is not as expected as "Running"Warning The status "Installed/Stopped" of node node2(environment: development) is


checkstatus | 383

not as expected as "Running" Exception: Status check timeout

failOnError Set to true and State Mismatch

[INFO] Redirect requested but followRedirects is disabledException: The status "Installed/Stopped" of node node2(environment: development) is not as expected as "Running"

See Also StatusCheckerConfig.properties on page 384



StatusCheckerConfig.properties Configuration File

Description The StatusCheckerConfig.properties file configures the behavior of the checkstatus utility.

Properties Property Description

amxPlugins The ActiveMatrix plug-ins directory. For example, C:\tibco\components\eclipse\plugins.

host The hostname or IP address of the ActiveMatrix Administrator server.

port The port of the ActiveMatrix Administrator server.

username The username of an ActiveMatrix Administrator server user.

password The password of an ActiveMatrix Administrator server user. The password can be obfuscated with AMX_ADMIN_HOME\2.x\bin\passwordobfuscator.

type The runtime object to check. One of:

• managementdeamon

• node

• serviceassembly

• sharedresource

expectedState Expected state of the object:

• managementdeamon: "Bound | Available", "Bound | Not available"

• node: Running, Unknown

• serviceassembly: DEPLOYED_WITH_ERROR, NOTDEPLOYED

• sharedresource: Installed

You can specify multiple expected states, separated by the || (or) operator. The state comparison is case sensitive.


StatusCheckerConfig.properties | 385

Example The following is an example of a StatusCheckerConfig.properties file:

amxPlugins=C:/tibco/components/eclipse/plugins

timeout Timeout in milliseconds. The length of time checkstatus will check that the actual state matches the expected state before returning a timeout exception.

interval Polling interval in milliseconds. The length of time that checkstatus will wait before polling for the state of a object.

failOnError If true, throw an exception if polling fails. Does not throw an exception if the server configuration (hostname or port) is incorrect.

If you want to poll periodically when the object state doesn’t match the expected state, set failOnError to false, otherwise polling will fail the first time the state does not match the expected state.

outputFile The file to which status will be written. The file has the latest snapshot of the status of the queried objects. For example:

node node1(environment: development): Runningnode node2(environment: development): Installed/Stopped

machineName Name of the machine to check. Set to * to check all machines.

environmentName Name of the environment to check. Set to * to check all environments.

nodeName Name of the node to check. Set to * to check all nodes.

serviceAssemblyName Name of the service assembly to check. Set to * to check all service assemblies.

sharedResourceName Name of the resource to check. Set to * to check all resources.

Property Description



host=192.168.67.54port=8120username=adminpassword=#!YtafJdVTzc5Tn3cLoKdhFAMAQ5EyvJq7type=nodeexpectedState=Running || Unknowntimeout=21000interval=10000failOnError=trueoutputFile=result.txtmachineName=*environmentName=*nodeName=*serviceAssemblyName=*sharedResourceName=*


| 387

Index

A

Acceptor-Thread count 376access the login page from a browser window 67access the login page from the Windows Start

Menu 67accessing the Monitor & Manage perspective 246actions 79activating and deactivating a container 206ActiveMatrix Administrator cluster, machine, and

environment relationships 106ActiveMatrix Administrator command-line

interface 79ActiveMatrix Administrator command-line tool

keystores 345ActiveMatrix Administrator configuration 29ActiveMatrix Administrator graphical interface 67ActiveMatrix Administrator interfaces overview 66ActiveMatrix Administrator server configuration 376ActiveMatrix Administrator server keystores 342ActiveMatrix Administrator servers 165ActiveMatrix Administrator setup 4ActiveMatrix database server 14ActiveMatrix node keystores 343Add Search Parameters reference 113adding a messaging server to an environment 179adding a UDDI server 156adding a user to a local XML File realm 31adding a user to groups 143adding child logging configurations 311adding child objects to a parent object 150adding filters 323adding logging configurations to objects 312adding nodes to the Mapped Nodes list 234adding permission to publish to a business 380adding superusers 142additional attributes 329Administrator Server reference 167Administrator Servers reference 167

allocated memory size 374At Least Once 177At Most Once 178Authentication realm configuration 31Authentication realms 5Auto-bind failure 105Auto-bind success 105automatically binding to the ActiveMatrix Adminis-

trator server machine 105

B

Base Event Format Attribute reference 331Base Format 84Batch script 62BEF Creation Time filter 322before running the ActiveMatrix Administrator Server

creation utility 26before you begin 7Best Effort 177best practices 368binding a shared resource property to a shared

resource 119binding a shared resource property to a substitution

variable 118binding machines 105, 107binding machines to ActiveMatrix Administrator

clusters 6Bound Machine reference 112Bound Machines table 111bridged network discovery 103browse mode 291build file 87, 298, 308, 309build.xml 39, 46, 50, 96building queries 323BW Engine Event Format Attribute reference 335


388 | Index

C

change the reporting and polling intervals 21changing a user password 143changing keystore passwords 343, 344changing Management Daemon status reporting and

polling intervals 20changing the port values 19clearing a binding between a shared resource property

and a substitution variable 118command-line 307command-line interface 66, 110, 205component 269composite reference 271composite service 270configuration properties 364configure enterprise assets 71configure environments 72configure Messaging Bus settings 174configuring a service assembly 222configuring LDAP attributes as usernames 43configuring Messaging Bus 176configuring Messaging Bus settings 176configuring messaging server 351configuring multiple messaging servers in multinode

scenarios 200configuring service assemblies 218configuring service units 222configuring SSL in TIBCO Enterprise Message Service

server 353configuring the keystore location and password 342configuring the runtime 7configuring the TIBCO Administrator authentication

realm 34connection type

JDBC shared resources 123console mode 28consumes 270, 271container reference 206containers 258control panel 62create 93create a new HSQLDB datastore 16creating a log service 302creating a new HSQLDB datastore 15

creating a node 192creating a root group 146creating a shared resource definition 116creating a subgroup 146creating a substitution variable 169creating a TIBCO Administrator authentication

realm 33creating a user 141creating a user and a database in Sybase 15.x 58creating an ActiveMatrix Administrator server 165creating an environment 173creating an external keystore 160creating an internal keystore 159creating an obfuscated password 28creating schema Generated by DB Script Generator 59creating the ActiveMatrix schema 56creating the ActiveMatrix schema files 56creating the ActiveMatrix tables 56creating the First ActiveMatrix Administrator

server 26customizing HTTP shared resource definitions 11customizing the log columns 326

D

dashboard view 247data encryption 349data file 94, 298, 308, 309data file schemas 94data integrity 350database 145database actions 79database authentication superuser 37database configuration 48database configuration reference 48database details 162database overview 14database realm 35, 36database tables 5datafile.xml 39, 46, 51default connector reference 201default runtime node configuration 60definitions 364


Index | 389

deleting a group or groups 146deleting a keystore 160deleting a log service 305deleting a shared resource definition 119, 120deleting a substitution variable 169deleting a user 142deleting an ActiveMatrix Administrator server 166deleting an environment 175deleting nodes 199deleting saved queries 324deleting service assemblies 231deleting the ActiveMatrix Administrator Windows

service 30deploy to an Environment 72deploying a plug-in 163deploying a service assembly 219deploying and redeploying service assemblies 223deploying service assemblies 8deployment details 273deployment overview 218deployment view 285direct connection 181Direct connection type, in JMS shared resources 128disabling machines in an environment 184disabling UDDI Servers in an environment 186Discovered Machines reference 114discovering machines 102discovery port 18displaying permissions 150displaying the log viewer 318downloading a service assembly archive 230

E

edit mode 75editing a keystore description 160editing a log service 304editing a logging configuration 311editing a node 196editing a shared resource definition 117editing a substitution variable value 169editing a UDDI server 156editing Administrator Server properties 166

editing an environment 175editing service assembly configurations 225editing the reporting and polling intervals 21enable assets 174enabling and disabling containers 204enabling and disabling resource functions 210enabling and disabling shared resource definitions in

an environment 188enabling and disabling shared resources 209enabling assets in nodes 191enabling bound machines in environments 106enabling HTTPS for ActiveMatrix Administrator

servers 346enabling HTTPS in ActiveMatrix Administrator

clients 347enabling HTTPS in ActiveMatrix Administrator com-

mand-line tool 347enabling HTTPS in ActiveMatrix Administrator

server 346enabling HTTPS in ActiveMatrix nodes 347enabling HTTPS in Management Daemon 347enabling JMX/SSL for ActiveMatrix nodes 353enabling machines 184enabling machines in an environment 184enabling monitoring 244enabling non-administrator users to publish to the

ActiveMatrix Registry 378enabling secure communications between nodes and

messaging servers 351enabling secure connections between nodes and

ActiveMatrix components 351enabling secure connections between nodes and

ActiveMatrix servers 353enabling secure connections to auxiliary servers 355enabling secure connections to LDAP servers 355enabling secure connections to UDDI servers 355enabling SSL for Management Daemon 348enabling UDDI servers 186enabling UDDI servers in an environment 186endpoint chosen for publication 279engine event format attribute reference 335environment reference 174environment view 250, 285environments overview 172environments reference 172


390 | Index

event detail 328event formats 329event models 297Example 46example 21, 50Example 1 Adding a Logging Configuration with a

FIle Appender 313Example 2 Adding a Logging Configuration with a

JMS Appender 314Example 3 Configuring BEFJMSAppender to Support

JNDI and SSL Connections to the Enterprise Mes-sage Service Server 314

examples 85, 96, 308existing ActiveMatrix Administrator server 43exporting log events to a file 327external endpoint 270, 272

F

failure scenarios 52faults/successes 266, 282fields 75filter area 322filter operators 322filtering table entries 76force 93full format 85

G

generate WSDL 266generating the schema using DB Script Generator 58graphic interface overview 69graphical interface 66group hierarchy 145groups 145groups list reference 147GUI mode 28

H

header 69heap size 374help 77hierarchical lists 76highlighting log events with error severity 326host and port

HTTP shared resources 121how JNDI shared resource definitions are used 116how to contact TIBCO support xxivHSQLDB database 15HTTP server shared resource definition reference 120HTTP shared resources 120

host and port 121minimum and maximum threads 122

I

Identity shared resource definition reference 123importing issuer certificates 343importing log files into a log service database 298importing shared resource definitions 220infrastructure view 250inline 118installing a server certificate 342, 343installing a shared library in a node 199installing and uninstalling nodes 194installing and uninstalling shared resources 210installing nodes 194installing shared resources 210integrated service view 264interaction 367interface consumed by 269, 272interface invokes 270, 271interfaces & operations 273, 284inter-object relationships 82introduction 2inventory polling interval 20invoking the command-line interface 87


Index | 391

J

JDBC connection type, in JDBC shared resources 124JDBC drivers and database URLs 124JDBC shared resource definition reference 123JDBC shared resources 123

connection type 123JDBC connection type 124JNDI connection type 125

JMS shared resource definition reference 127JMS shared resources 127

direct connection type 128JNDI connection type 129

JNDI connection 183JNDI connection type, in JDBC shared resources 125JNDI connection type, in JMS shared resources 129JNDI shared resource definition reference 130JVM configuration 373

K

keystore reference 161keystores 342keystores overview 158

L

LDAP 145LDAP mapping 43LDAP realm 39, 41life cycle management 9life cycle of the ActiveMatrix runtime 7life cycle 365limitations 78local invocations 368local network discovery 102local substitution variables reference 214local XML file 145local XML File Realm 31local XML file realm 31log file generation 298

log files 297log in to the ActiveMatrix Administrator graphical

interface 68log service reference 306log services 163log services reference 306log viewer 299logging configurations 310logging in to the ActiveMatrix Administrator graphi-

cal interface 67logical component 328

M

machine view 253machines 248, 250machines reference 185Management Daemon keystores 344management port 19managing ActiveMatrix Administrator clusters 162managing groups in the database authentication

realm 146managing keystores 158managing machines 102managing messaging servers 178managing shared resource definitions 116managing the server keystore 342managing the trusted keystore 342, 344, 344, 345managing UDDI servers 156managing users in the database authentication

realm 141managing users, groups, and permissions 139manual recovery 46mapped nodes reference 235mapping service units to nodes 233mapping shared resource profiles to shared

resources 222, 236maximizing and minimizing the query builder 320messages In AMX binding queue 359messages in JMS container queue 361messaging server reference 180metadata 278Microsoft SQL Server 54


392 | Index

minimum and maximum threads, HTTP shared resources 122

model area 321monitor & manage 73monitoring configuration 163monitoring configuration reference 244multiple objects 152, 153

N

new ActiveMatrix Administrator cluster 45node mapping tab 233node polling interval 20node reference 197node trail 257node view 256nodes 249, 251, 254, 290number of web-worker threads 376

O

object formats 84object logging configuration reference 316objects 80, 149, 150objectselector 92obtaining the result count hint 324operations 283Oracle 55Oracle native thin driver 349overriding a substitution variable value 213overwrite and merge 93

P

paging through the log 327performance 267, 283performing actions 76permanent generation size 375permission types 149

permissions 147perspective overview 70physical component 329platform server encryption 29plug-ins 163plug-ins reference 165pre-creating ActiveMatrix schema 53pre-creating database tables by running DDL

scripts 26project element 87provides 269provides & consumes 268publishing a service 275purging a log service database 308

Q

quality of service 176

R

race condition between consumer and provider 358reference format 85related documentation xviiirelationship to TIBCO Administrator™ Software 4relationship to TIBCO® Management Daemon

Software 4reloading an internal keystore 160removing a messaging server from an

environment 183removing a UDDI server 157removing a user from a group 144removing filters 323removing nodes from the mapped nodes list 234removing permissions 153removing superusers 142Rendezvous shared resource definition reference 134Rendezvous shared resources 134resetting the superuser password 141resource definition reference 120reusing archives 219


Index | 393

reverting a substitution variable back to the global value 213

running a modified query 325running a query 325running a saved query 325running an existing query 325running queries 324running the ActiveMatrix Administrator Server cre-

ation utility 27, 57runtime actions 79

S

saving a query 324saving and deleting queries 324screens 75search 41search parameters reference 114searching for services 262searching for users 141securing JDBC connections 349selecting rows 75server logs 337service assemblies 285service assemblies reference 221service assembly details 287service assembly reference 226service assembly trail 287service assembly view 287service deployed to n nodes 274service details 265service instance details 281service instance trail 280service instance view 280service instances 259service metrics 247service optimization 368service trail 265service unit trail 289service unit view 288service units 233service units table 288service units table reference 233

service view 261services 290services reference 240session and session pool 364session count and max pool size normalization 365session count and max pool size 368session release 369setting a shared resource definition property 117setting permissions 150setting permissions for nodes 199setting the default log service 303setting the log refresh rate 327setting the model 321setting up ActiveMatrix Administrator keystores 346setting up HSQLDB 14setting up Oracle, SQL Server, or Sybase 14setting up the database server 14shared resource life cycle 10shared resource profiles reference 236shared resource reference 211shared resources 119, 259

HTTP 120JDBC 123JMS 127Rendezvous 134

silent mode 28single object 151, 153single_node_data.xml 97situation 329sorting table rows 76specifying the location of the datastore data files 16SSL server shared resource definition 137start 365starting a node on machine startup 196starting and stopping a log service 304starting and stopping a plug-in 164starting and stopping ActiveMatrix Administrator

servers 166starting and stopping nodes 195starting and stopping service assemblies 224starting and stopping the ActiveMatrix Administrator

server 61, 61starting and stopping the TIBCO Common Logging

Plug-in 301starting installed nodes 8


394 | Index

starting nodes 195starting service assemblies 224starting the database server 15starting the HSQLDB Database server 15starting the TIBCO Enterprise Message Service

server 22starting TIBCO Administrator and TIBCO Hawk 23starting TIBCO Management Daemon 17status icons 74status reporting interval 20stop 365stopping nodes 196stopping service assemblies 224substitution variables 118substitution variables reference 235substitution variables tab 235superuser registration 43superusers 140supported objects 80supported objects and attribute reference 94sybase 58syncing or unpublishing a service 275system messages 77system metrics 248

T

tables 75target element 88taskdef element 87thread and thread pool 364TIBCO ActiveMatrix Administrator architecture 2TIBCO ActiveMatrix Administrator servers and

clusters 5TIBCO Administrator 146TIBCO Administrator realm 32TIBCO Administrator™ and TIBCO Hawk® 23TIBCO Business Studio 299TIBCO Encryption 28TIBCO Enterprise Message Service™ Server 22TIBCO Management Daemon 17TIBCO_HOME xxtoolbar area 320

top 20 faults 248top 20 hits 247topics reference 237total requests 267, 282TRA file locations 356two-step configuration

first define, then install 8two-step deployment

first configure, then deploy 9

U

UDDI publishing 275UDDI publishing reference 275UDDI server reference 157UDDI servers 276UDDI servers reference 186UDP listening port 18UDP, discovery, and management ports 18UI components 150unbinding machines 111undeploying a plug-in 164undeploying service assemblies 231uninstalling nodes 195uninstalling shared resources 210UNIX 63, 196updating a service assembly archive 229updating object status 77updating service assemblies 230updating the authentication realm 45updating the database configuration 50uploading a service assembly 220usage 366use cases 51user interface functions 147users 140users and groups overview 139using client and server modes 373using the log viewer 318UUID 276


Index | 395

V

view logs 253, 265view mode 75viewing log event details 328viewing log files 299views 242

W

welcome area 70working with containers 204working with environments 175working with log services 302working with logging configurations 215, 239, 310working with nodes 190working with queries 323working with service assemblies 223working with service units 233working with services 240working with shared resource definitions 188working with shared resources 209working with substitution variables 169, 213, 238working with the default connector 201working with the graphical user interface 74working with the log 326working with the query builder 319working with topics 237


396 | Index


Documents

Tib Amx Administration