TIBCO Administrator Server Configuration Guide

Software Release 5.6 July 2008

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 TIBCO ADMINISTRATOR INSTALLATION) 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 Adapter, Predictive Business, Information Bus, The Power of Now, TIBCO Adapter, TIBCO Administrator, TIBCO BusinessWorks, TIBCO ActiveMatrix BusinessWorks, TIBCO Designer, TIBCO Enterprise Message Service, TIBCO Rendezvous, TIBCO Repository, and TIBCO Runtime Agent are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. EJB, 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. 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 1999-2008 TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information

| iii

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x TIBCO Administrator Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x Other TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . x Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii How to Contact TIBCO Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

Chapter 1 Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Architecture Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Administration Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TIBCO Hawk Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LDAP Directory Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Client Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Application Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2 3 4 4 5

Database and File-based Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 Client Application Data Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Deployment Choices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Using Local Application Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Using Server-based Application Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Security Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access to Domain Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Domain Transport Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Access to the TIBCO Administrator GUI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Deployed Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Domain Password Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Administration Server Shutdown String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Password Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Changing the Password Policy for Existing Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Distributing Changed Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Domains Integrated with an LDAP Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Password Policy Choices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 12 13 14 14 15 15 16 16 17 17 17

Chapter 2 Fault Tolerance and Load Balancing in a Rendezvous Administration Domain . . 21

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 Multiple Secondary Administration Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

TIBCO Administrator Server Configuration Guide

iv

| Contents
Load-Balanced Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 One Server in One Subnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Multiple Load-Balanced Servers in a Subnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Multiple Administration Domains in a Subnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Multiple Administration Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Multiple Servers Using Different Daemon and Service Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Administration Domain Spanning Subnets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setup Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 32 33 40

Multiple Load-Balanced Servers Spanning Subnets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Chapter 3 Administration Server Properties File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 General Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 File Storage Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Database Storage Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 TIBCO Rendezvous Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Logging Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Security Audit Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Load Balancing Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Server Security Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Persist Commit History Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 TIBCO Hawk Agent Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Chapter 4 Advanced Topics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Server-based Repository Locator String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 TIBCO Rendezvous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 HTTP and HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 Local Repository Locator String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Using a Properties File to Encapsulate Locator String Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 Configuring Connection Pool Size for the Database Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 Enabling an SSL Connection to an LDAP Directory Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 Maintaining Connections to an LDAP Directory Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

TIBCO Administrator Server Configuration Guide

Contents v

Design-Time Encoding vs. Runtime Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Setting Encoding for an Administration Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 Users and Passwords with Double-Byte Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Configuring EHCache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 Writing Cache Statistics to a Log File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Authenticating Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Authentication Using the JAAS Authentication Web Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Authentication Code Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logging Information to a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 85 86 87

Repository Locking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 How to Break the Lock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89 Remote Server Shutdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90 Global Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining Variables in TIBCO Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Defining Service-Settable Variables in TIBCO Designer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Variable Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 91 91 92

Chapter 5 Command Line Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

Command List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 CorpRoleSynchronizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 DeleteInvalidUsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 CorpUserSynchronizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 ExportDomainSecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 ImportDomainSecurity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 MoveMachine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105 RedeployAllAppsForUser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 RepoConvert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 RepoPing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116 RepoCreateInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 RepoDelete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 RepoDeleteInstance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119 RepoDiff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 RepoExport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121 RepoImport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123 RepoListInstances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126 RepoRename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

Appendix A Log Files Generated for an Administration Domain . . . . . . . . . . . . . . . . . . . . . . 129

TIBCO Administrator Server Configuration Guide

vi

| Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 Installer Logs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 Tomcat Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132 Administration Server Log. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 TIBCO Hawk Agent Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134 Application Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135 Audit Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136 TIBCO Domain Utility Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Repository Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 Standard TIBCO Trace Message Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

Appendix B Using TIBCO Hawk Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142 Starting TIBCO Hawk Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Starting TIBCO Hawk Software on Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 Starting TIBCO Hawk Software on Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 The Auto-Discovery Process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 Invoking Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 Available Microagent Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . onCopyInstance(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . onCreateInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . onDeleteInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . onModifyInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . onServerShutdown() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . onStartInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . onStopInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . onInstanceChange() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getConfigProperties(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getRvConfig(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getConfig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getQueueStats() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getLogConfig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getTraceIds() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . onContentChange() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setLogConfig() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . setTraceIds() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . doShutdownServer() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getInstanceInfos() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getInstanceStatus() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getSizeOfInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147 149 150 151 152 153 154 155 156 157 159 160 161 163 164 166 167 168 170 171 172 174 175

TIBCO Administrator Server Configuration Guide

Contents vii

getListOfLockedNodes() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . getConnectedClients() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . doStopInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . doStartInstance() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . doRefreshCache() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . doRefreshSecurity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . doTerminateClient() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

176 177 178 179 180 181 182

Appendix C Schema Files used when Exporting and Importing . . . . . . . . . . . . . . . . . . . . . . 185

XML Formats Used by TIBCO Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 Schema Files Included With TIBCO Runtime Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 Using RepoExport and RepoImport. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188 Creating a New Adapter Configuration Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 Including Custom Schemas During Import . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Appendix D System Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

AEREPO Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194 POF Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 POFUTIL Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 POOL Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 PLUGIN Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

TIBCO Administrator Server Configuration Guide

viii

| Contents

TIBCO Administrator Server Configuration Guide

| ix

Preface

This document provides server configuration information for administrator users of TIBCO Administrator. TIBCO Administrator Users Guide explains how to get started with TIBCO Administrator.

Topics
Related Documentation, page x Typographical Conventions, page xii How to Contact TIBCO Support, page xiv

TIBCO Administrator Server Configuration Guide

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

TIBCO Administrator Documentation

The following documents form the TIBCO Administrator documentation set: TIBCO Administrator Installation Read this manual for instructions on site preparation and installation. TIBCO Administrator Users Guide Read this manual for instructions on using the product to manage users, resources, and applications inside an administration domain. TIBCO Administrator Server Configuration Guide Read this manual for instructions on using the administration server to manage projects and repositories, using command-line tools, performing conversions, and so on. The manual is written primarily for system administrators. TIBCO Administrator Release Notes Read the release notes for a list of new and changed features. This document also contains lists of known issues and closed issues for this release.

Other TIBCO Product Documentation

You may find it useful to read the documentation for the following TIBCO products: TIBCO Runtime Agent software: Runtime Agent must be installed before installing TIBCO Administrator. Runtime Agent includes TIBCO libraries, third-party libraries, utilities, and other software used by TIBCO products. TIBCO Designer software: TIBCO Designer is installed as part of the TIBCO Runtime Agent installation. TIBCO Designer provides an easy to use GUI for design-time configuration of TIBCO applications. TIBCO Designer includes online help for each palette. TIBCO Hawk software: This is a tool for monitoring and managing distributed applications and operating systems. TIBCO Rendezvous software: Rendezvous is installed as part of the TIBCO Runtime Agent installation. Rendezvous is the default message transport for an administration domain. TIBCO Enterprise Message Service software: Enterprise Message Service lets application programs send and receive messages using the Java Message

TIBCO Administrator Server Configuration Guide

Preface xi

Service (JMS) protocol. Enterprise Message Service can be set as the message transport for an administration domain. TIBCO ActiveMatrix BusinessWorks software: ActiveMatrix BusinessWorks is a scalable, extensible, and easy to use integration platform that allows you to develop integration projects. ActiveMatrix BusinessWorks includes a GUI for defining business processes and an engine that executes the process. TIBCO Adapter software: Each TIBCO Adapter product provides documentation that explains how to implement TIBCO Adapter services, which can then be deployed from TIBCO Administrator.

TIBCO Administrator Server Configuration Guide

xii

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

Use Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example: Use M y C o m m a n d to start the foo process.

bold code font

Bold code font is used in the following ways: In procedures, to indicate what a user types. For example: Type a d m i n . 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, M y C o m m a n d is enabled: MyCommand [e n a b l e | disable]

italic font

Italic font is used in the following ways: To indicate a document title. For example: See TIBCO 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: M y C o m m a n d 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.

TIBCO Administrator Server Configuration Guide

Preface xiii

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 p a r a m 1 and p a r a m 2 , or the pair p a r a m 3 and p a r a m 4 .
MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parameter can be either p a r a m 1 or p a r a m 2 and the second can be either p a r a m 3 or p a r a m 4 :
MyCommand {param1 | param2} {param3 | param4}

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

TIBCO Administrator Server Configuration Guide

xiv

| How to Contact TIBCO Support

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.

TIBCO Administrator Server Configuration Guide

|1
Chapter 1

Introduction

This chapter introduces the administration server that is used to manage applications placed in an administration domain.

Topics
Architecture Overview, page 2 Database and File-based Storage, page 6 Deployment Choices, page 9 Security Considerations, page 12 Password Policy, page 16

TIBCO Administrator Server Configuration Guide

| Chapter 1

Introduction

Architecture Overview
An administration domain is a collection of users, machines, and services. A domain is managed by an administration server, which is assisted by a TIBCO Hawk agent running on each machine in the domain. The next diagram shows the basic components in an administration domain. TIBCO Hawk agent uses microagents and rulebases to monitor activity among the components in the administration domain. Depending on the transport used for inter-domain communication, domain information can be stored in a database or in files.

Adapter client

TIBCO Hawk Agent monitor

BusinessWorks client

<adapter>.tra file

bw.tra file

Administration Server tibcoadmin_<domain>.tra file

Domain repository (database) Corporate LDAP Users and groups

Application repositories (files or database)

Domain repository (files)

Administration Server
An administration server manages resources in an administration domain. A machine can have multiple domains, with each domain assigned a unique server. Each time a domain is created, a new server is created for the domain and named with the domain name. When configuring an administration server, you specify the transport to use for managing communications in the administration domain. Either TIBCO Rendezvous or TIBCO Enterprise Message Service can be used as the transport.

TIBCO Administrator Server Configuration Guide

Architecture Overview 3

If TIBCO Rendezvous is used as the transport in an administration domain, you can create secondary servers to load balance client-server activity in the domain. In this case, the initial administration server is known as a primary server and other servers are known as secondary servers. Multiple secondary servers are allowed in the same administration domain, but each must be on a different machine. The machine that hosts the primary server cannot also host a secondary server. If TIBCO Enterprise Message Service is used as the transport, there is no need for secondary servers. (You can create secondary servers, but they are just like primary servers.) The only deployment option is Local, which means that client applications run independent of the administration server (unless an application performs certain operations that require connecting to the administration server, such as HTTP and SOAP authentication). See Deployment Choices on page 9 for more information. The administration server runs under the Tomcat web server as a servlet. Tomcat ports are defined when using TIBCO Domain Utility to configure the administration domain. The ports can be changed later using Domain Utility. Data about the machines, registered software, users, roles, access control lists, application configurations and deployment history is maintained for an administration domain. If you have configured a domain to use the TIBCO Enterprise Message Service as the transport, domain storage must be in a database. Domains configured to use TIBCO Rendezvous can store data in a file repository or in database. See Database and File-based Storage on page 6 for details. Each administration domain contains one or more machines. You add a machine to a domain using TIBCO Domain Utility. You can start Domain Utility at any time to manage domain machines, domain configurations, administration server settings, upgrade domains and register a TIBCO Enterprise Message Service server.

TIBCO Hawk Agent

TIBCO Hawk agent is part of the TIBCO Runtime Agent package and is installed on each machine in an administration domain. TIBCO Hawk agent monitors local resources and conditions. An Agent uses collections of locally loaded rules organized into rulebases to apply monitoring logic. The Hawk agent also builds local client. t r a and . e x e files when a client application is deployed, and on Windows platforms, creates NT services for applications.

TIBCO Administrator Server Configuration Guide

| Chapter 1

Introduction

The administration server retrieves the monitoring information displayed in the TIBCO Administrator GUI from a Hawk Agent, which runs as a separate process on each machine in the domain. The TIBCO Administrator GUI provides a dialog to configure rulebases, set monitoring options, and display status. See the TIBCO Administrator Users Guide for more information.

LDAP Directory Server

You can integrate an administration domain with an LDAP directory server to use the users and groups defined in the LDAP directory. The groups then become visible in TIBCO Administrator GUI. As part of domain creation, the TIBCO Domain Utility prompts for the information to retrieve, the synchronization interval, and other options. The administration server only retrieves information from an LDAP directory server, it never sends or stores information there.

Client Applications
Applications can communicate directly with the administration server when configuration data for the application is stored in the administration domain repository. The administration server can also send application data directly to the machine on which that application is running, and the application will then work independently of the administration server. If you are using TIBCO Enterprise Message Service as the domain transport, application data is always sent to the local machine where the application is running. Associated with each client application is a . t r a file, which determines certain aspects of how the application is run. The . t r a file is created during deployment and available on the deployment machine in the TIBCO_TRA_DOMAIN_HOME/ domain-name/ a p p l i c a t i o n / application-name directory. You can manually edit the client applications . t r a file, however, each time you deploy (or redeploy) the corresponding client application, TIBCO Administrator overwrites the . t r a file. Using the TIBCO Administrator GUI to manage . t r a file content and not editing the file is therefore highly recommended. Programmatically, applications such as adapters use a project locator string to specify location and protocol information. See Server-based Repository Locator String on page 66 for details.

TIBCO Administrator Server Configuration Guide

Architecture Overview 5

Application Domains
If your TIBCO application supports this feature, you can create multiple application domains and assign client applications to use them. An application domain allows you to specify a repository to hold application data only. This is useful, for example, when your applications need to use a local database rather than that used by the administration domain.

TIBCO Administrator Server Configuration Guide

| Chapter 1

Introduction

Database and File-based Storage

An administration domain stores domain information in a database repository or file repository, depending on the transport type. If TIBCO Rendezvous is set as the transport, you can store domain data in a database repository or file repository. If TIBCO Enterprise Message Service is set as the transport, you can only store domain data in a database repository. In most cases, it is recommended to use a database for the domain repository and files for client application repositories. In the case of a file-based domain, domain data is stored in the and A U T H _ domain. d a t files. Data stored in the S Y S _ domain. d a t file is referred to as the administration domain while data stored in the A U T H _ domain. d a t file is referred to as the authorization domain.
S Y S _ domain. d a t

The authorization domain contains the users, roles and data access ACLs. Everything else is stored in the administration domain: installed software, machines, applications, plug-ins, TIBCO Administrator ACLs, and so on. As such, the administration domain file is usually much larger than the authorization domain file. Editing these files is not recommended. It can potentially lead to loss of all domain data and to unpredictable behavior of TIBCO Administrator. In a file-based domain, the Hawk agent accesses the domain repository through the administration server. If a database is used, the administration domain is stored in tables beginning with A d , while authorization domain data is stored in tables beginning with Au. In a database-based domain, the Hawk agent accesses the domain repository directly and does not go through the administration server. Performance can improve if domain data is saved into a database. During deployment, there are a number of steps during which domain data is committed. If domain data is stored in files, the files are loaded at startup and each time a change to the domain is saved, the contents of the corresponding file must be regenerated and the file saved. Each commit for a file-based domain requires writing the entire file, which is expensive both because of I/O and calculating the large number of individual strings. When using a file-based repository with a primary and secondary administration server, performance will be slower than when using a database to store administration domain data.

TIBCO Administrator Server Configuration Guide

Database and File-based Storage 7

When using a database, only the changed data is written. In addition to faster performance when saving domain data, there also is significant memory savings. Domain data will not be loaded and cached by TIBCO Administrator in the way that application data is. Note that moving application data to a database has no such savings and will slightly increase the server startup and deployment times. To migrate from a file-based domain to a database-based domain, simply create a new domain with database settings, then use the AppManage utility to export your applications from the old domain and import them into the new domain. Restrictions on Database Storage Database storage has the following restrictions: If two differently named administration servers use database storage and connect to the same database instance, you must create separate user accounts for each server. This prevents the servers from accessing the same set of database tables simultaneously. If applications that store data in databases are used inside an administration domain, the domain data must also be stored in a database. Note that the reverse is not true. Domain data can be stored in a database when application repositories are stored in files. Storing application data in databases has been deprecated with this release. It is recommended that you use the standard options for application deployment. In a database-based domain, the TIBCO Hawk agents on all client machines must have database connectivity because they access the domain repository directly instead of accessing it through the administration server.

Client Application Data Storage

TIBCO Administrator creates application repositories when you deploy an application. For information about the deployment process, see the TIBCO Administrator Users Guide. Application configurations are created using TIBCO Designer and are included in the enterprise archive file that is imported into TIBCO Administrator. The enterprise archive file contains information about the services and client application to run, such as TIBCO BusinessWorks processes and TIBCO Adapter services. The deployment process creates client application data in the administration server or sends the data to the applications target machine(s). If TIBCO

TIBCO Administrator Server Configuration Guide

| Chapter 1

Introduction

Enterprise Message Service is used as the transport, application data is always sent to the applications target machine. When application data is sent to the target machines, the application runs independently of the administration server (unless it performs operations that require connecting to the administration server in a file-based domain, such as HTTP or SOAP authentication). Security for access to application repositories is set using the TIBCO Administrator GUI.

TIBCO Administrator Server Configuration Guide

Deployment Choices 9

Deployment Choices
When configuring an administration domain, you can set how the administration server creates and stores application data. This section explains the choices available and discusses their implications. You have the following choices when configuring an administration domain that uses TIBCO Rendezvous. If TIBCO Enterprise Message Service is used, only the local application data choice is available. Server-based application data is not available. Using Local Application Data Using Server-based Application Data

For both choices, a directory is created for each deployed application on the target machine under TIBCO_TRA_DOMAIN_HOME\ domain-name\ a p p l i c a t i o n . The executables, property files and deployment files required for the application are stored under this directory. The TIBCO_TRA_DOMAIN_HOME\ domain-name\ d a t a f i l e s directory is also created as needed and only for local deployment. This directory contains the project files used by an applications non adapter components such as TIBCO BusinessWorks. Adapter repository files (. d a t ) are stored in the TIBCO_TRA_DOMAIN_HOME\ domain-name\ d a t a directory.

Using Local Application Data

When using TIBCO Domain Utility to create an administration domain, you can select the Local Application Data option. When the option is chosen, deployment files for an application are sent to target machines. This allows the application to run independently of the administration server (unless an application performs operations that require connecting to the administration server in a file-based domain, such as HTTP or SOAP authentication). Selecting the option makes it the default in the domain. For domains that use TIBCO Rendezvous, you can change the option per application to use Rendezvous, or HTTP/HTTPS when deploying the application in the TIBCO Administrator GUI or the appManage utility. Choosing the Local Application Data option results in the following benefits: Because the local service instances use no memory, thread or CPU resources on the administration server, the solution is infinitely scalable. At runtime, because there is no communication between the deployed application and the administration server, a server failure has no effect on the runtime application (unless an application performs certain operations that require connecting to the administration server in a file-based domain, such as HTTP or SOAP authentication).

TIBCO Administrator Server Configuration Guide

10

| Chapter 1

Introduction

Application data for TIBCO BusinessWorks is stored in its native format as a multifile project, while adapters use their native format . ( d a t files). The required storage format is determined based on the applications components installed on the target machine. For example, if an application uses a TIBCO Adapter, a . d a t file is written to the target machine. If the application uses TIBCO BusinessWorks, a project file is written to the target machine. For server-based domains, TIBCO BusinessWorks applications must do an in-memory transformation at startup.

Issues with this Choice The main issue with this choice is synchronization. If deployment is done cleanly, all client machines will remain synchronized as appropriate processes are stopped and each will receive updated deployment files. However, if a subset of client machines are unavailable during deployment and later started, their service instances, metadata and configurations can be out of sync. This could result in severely aberrant behavior. When using this option, you must ensure that each application deploys successfully. If an application does not deploy successfully, a warning message will appear in the TIBCO Administrator GUI Deployed Configuration pane. The person responsible for the application should ensure that the components on the failed machine are not started until they are successfully updated. The other significant concern is security. Repository instances can contain sensitive information such as database or application user ids and passwords. While the passwords are encrypted, the encryption algorithm used is 3DES. To protect this data, you must provide strong file system security on each machine to which applications are deployed.

Using Server-based Application Data

For domains using TIBCO Rendezvous as the transport, the server-based application data option is available. When deploying an application with this option set, a repository instance for the application is created on the administration server and the repository instance is referenced in each applications instances property file (.tra file). Two transport protocols are available for server-based communication, TIBCO Rendezvous, and HTTP/HTTPS. The default transport option is configured using TIBCO Domain Utility when creating the domain. The utility can be run later to change the default transport option for a domain. The transport can be changed when deploying an application, either in the TIBCO Administrator

TIBCO Administrator Server Configuration Guide

Deployment Choices 11

GUI or with the appManage utility. This allows one application in the domain to use Rendezvous, another application to use HTTP and another to use the local deployment option. If you configure an administration server for HTTPS, that servers GUI will not be accessible via HTTP. You can, however, access the same server programmatically using both HTTP and HTTPS. You must use TIBCO Rendezvous or the local deployment option to connect to a version 4.x TIBCO Adapter. HTTP or HTTPS cannot be used. Issues with this Choice Using this choice, there are no significant issues related to synchronization. The main concern with this approach is that each repository instance on the administration server consumes memory and threads. The memory requirement is 3-5 times the size of the . d a t file, which can range in size up to tens of megabytes. With many applications starting simultaneously, the server could become overwhelmed causing time-outs and application failures. Other issues include increased network traffic, and maintaining network and administration security. Another issue is related to fault tolerance. Runtime applications can not start, and in some cases can not function without being able to communicate with the administration server. This makes the administration server a single point of failure at runtime. The server does have some fault tolerance with the secondary servers, but deployment can be significantly slowed when secondary servers are used.

TIBCO Administrator Server Configuration Guide

12

| Chapter 1

Introduction

Security Considerations
This section outlines the security issues to consider when mapping out an administration domain. Read this section carefully and take all necessary security precautions if the environment in which you are setting up an administration domain is not secure. Examples of an insecure environment include: The subnet in which the domain operates is accessed by persons of varying security clearance. Elements of the domain (such as deployed applications) exist outside of the intranet firewall. The domain spans subnets that are configured with different levels of security. Communication between domain elements overlaps insecure network environments, such as the internet.

Access to Domain Data

Data storage locations and access methods may differ depending on your domain setup. Note that administration servers, Hawk agents, and deployed applications act as clients to the domain data and access it directly. Consult the table below to make sure that all connections in the course of data access are secure for your setup. See Domain Transport Security on page 13 for recommendations on transport security. Domain Setup File-based without LDAP Data Storage and Access Data kept on the administration server host and accessed using Rendezvous or Enterprise Message Service. Data kept on the administration server host and accessed using Rendezvous or Enterprise Message Service. Authentication delegated to the LDAP server, which is accessed directly. Security Considerations Consider changing to LDAP integration with SSL for better security of authentication tasks. LDAP connection can be secured with SSL. Note: Access to users and roles that are created in the TIBCO Administrator GUI cannot be secured by SSL.

File-based with LDAP

TIBCO Administrator Server Configuration Guide

Security Considerations 13

Domain Setup Database-based without LDAP

Data Storage and Access Data kept on the database server and accessed directly.

Security Considerations Database connection can be secured with SSL. Alternatively, consider changing to LDAP integration with SSL for better security of authentication tasks.

Database-based with LDAP

Data kept on the database server and accessed directly. Authentication delegated to the LDAP server, which is accessed directly.

Database connection can be secured with SSL. LDAP connection can be secured with SSL. Note: Access to users and roles that are created in the TIBCO Administrator GUI can be secured by securing the database connection.

Domain Transport Security

Two options are available for domain transport: Rendezvous or Enterprise Message Service. Rendezvous Underlying Protocol TCP between client and daemon (rvd) UDP between daemons within subnet (rvd) TCP between daemons spanning subnets (rvrd) Security Options No end-to-end security available: TCP traffic can be secured using Rendezvous secure daemon (rvsd). Traffic between subnets can be secured using Rendezvous secure routing daemon (rvrsd). UDP broadcast within subnet is not secure. Safe to use in all environments. End-to-end security available by enabling SSL. Enterprise Message Service TCP

Recommendation

Safe to use in a benign subnet or across subnets that are benign. Note that password-type data is always encrypted.

TIBCO Administrator Server Configuration Guide

14

| Chapter 1

Introduction

Access to the TIBCO Administrator GUI

The TIBCO Administrator GUI enables you to access and manipulate sensitive domain data and activity, including user and deployment management. When you access the administration server using the TIBCO Administrator GUI, all information is transmitted over the HTTP protocol by default. This is not secure when you access the TIBCO Administrator GUI from an insecure subnet or the Internet. You can secure your access to the TIBCO Administrator GUI by enabling HTTPS in TIBCO Domain Utility. See TIBCO Runtime Agent Domain Utility Users Guide for instructions.

Deployed Applications
The following table makes recommendations on different application deployment options. When an application is deployed, the deployment operation uses the domain transport. When the application is running, it accesses application data using the transport option you select at the time of deployment. See the table below for recommendations on the transport options for application data access. You can select HTTPS as a transport option for application data if you enable HTTPS in TIBCO Domain Utility. See TIBCO Runtime Agent Domain Utility Users Guide for instructions. An application may perform basic authentication tasks (for example, authenticating an application user) and may need to access domain data. See Access to Domain Data on page 12 for security recommendations. Deployment Option Local Application Data Transport Option Local Security Considerations The most secure option, since no network traffic is necessary to access application data. Use HTTPS to access application data securely.

Server-based Application Data

HTTP HTTPS Rendezvous

Note: Enterprise Message Service requires that applications are deployed as Local Application Data.

TIBCO Administrator Server Configuration Guide

Security Considerations 15

Domain Password Policy

See Password Policy on page 16 for more information.

Administration Server Shutdown String

While you can shutdown the administration server remotely via the shutdown port, you should define a shutdown string to protect the shutdown port. This shutdown string is not considered to be a password and is not governed by the password policy. However, it is best to specify a string that can pass the restrictive policy (see Stopping the Administration Server Remotely on page 19 in TIBCO Administrator Users Guide for more information).

TIBCO Administrator Server Configuration Guide

16

| Chapter 1

Introduction

Password Policy
When using TIBCO Domain Utility to configure an administration domain, you can specify whether to enforce a password policy in the domain. Doing so allows the applications running in the domain to meet the fundamental security requirements defined in the Sarbanes-Oxley Act. For example, to meet Sarbanes-Oxley security compliance, a password must meet the following policy: Minimum Password Length forcing a password to be at least a certain number of characters in length, for example, eight characters. Password Complexity forcing a password to include letters, numbers, and special characters such as punctuation. Password Aging forcing a password to be changed after a certain time period has passed, for example, three months. Forced Initial Password Change forcing a password to be changed on a user's first login. Account Lockout disabling a user account after a certain number of failed login attempts, for example, after five attempts. Password History forcing a certain number of recently used passwords to be remembered so that they cannot be used again, for example, not allowing the past four passwords to be used.

The password policy applies to user account passwords that allow access to TIBCO Administrator GUI modules and application passwords that are used to login to applications that have been deployed using the TIBCO Administrator GUI. When a user is deleted, the users password history is also deleted. The password policy that you configure in TIBCO Domain Utility applies to all users and groups in the administration domain. You should use an LDAP directory server if you wish to customize password policies for different users and groups.

Changing the Password Policy for Existing Domains

A user with write permission to the User console in the TIBCO Administrator GUI can change the password policy that was set when the administration domain was created. See the TIBCO Administrator Users Guide for details about changing the password policy.

TIBCO Administrator Server Configuration Guide

Password Policy 17

Distributing Changed Passwords

After a user changes his or her password successfully, the newly changed password must be distributed to all deployed applications on target machines, so that each application can use the newly changed password to login in an unattended mode. The easiest way to distribute changed passwords is to use the R e d e p l o y A l l A p p s F o r U s e r utility. See RedeployAllAppsForUser on page 109 for details.

Domains Integrated with an LDAP Directory

If your administration domain is integrated with an LDAP directory, you can have both LDAP users and local users (users defined directly in TIBCO Administrator GUI). The password policy applies only to local users and does not apply to LDAP users.

Password Policy Choices

This section lists the password policies that can be applied to an administration domain using TIBCO Domain Utility. The password policy is set when a domain is created and can be changed later in the TIBCO Administrator GUI Users console. No Policy This choice allows an administration domain to be created with no policy enforced for passwords. This allows user accounts to be created in the TIBCO Administrator GUI without assigning passwords. If passwords are assigned, they will not expire. A user can attempt any number of logons without having the account locked out. If you migrate a 5.1.x or 5.2.x administration domain to 5.5, by default, no password policy is defined. You can modify the password policy for the migrated domain. See Changing the Password Policy for Existing Domains on page 16 for details. Default Policy If selected, the following password policy is enforced. A password: Will be saved in encryption mode, and the algorithm used is 3DES-CBC with a 192-bit key. That is, SaveHashMode is set to false. Must contain at least three characters.

TIBCO Administrator Server Configuration Guide

18

| Chapter 1

Introduction

Normal Policy This is not a selectable policy in TIBCO Domain Utility, but is provided as a password policy template file. See Custom Policy on page 19 for information on finding this template file. If you use this template file, the following password policy is enforced. A password: Is saved in encryption mode, and the algorithm used is 3DES-CBC with a 192-bit key. That is, SaveHashMode is set to false. Must contain at least six characters. Must contain at least three of the following: One or more characters in lower case (a-z,) One or more characters in upper case (A-Z) One or more numeric characters (0-9) One or more punctuation characters (,!@#$%^&*()_+|~-=\`{}[]:";'<>?,./) Restrictive Policy If selected, the following password policy is enforced. A password: Is saved in hash mode, and the algorithm used is SHA1. That is, SaveHashMode is set to true. Must contain at least eight characters. Cannot contain the current password. Cannot contain the users name. Cannot contain the space character. Must contain at least three of the following: One or more characters in lower case (a-z,) One or more characters in upper case (A-Z) One or more numeric characters (0-9) One or more punctuation characters (,!@#$%^&*()_+|~-=\`{}[]:";'<>?,./) A password must be changed after 90 days. A password must be changed on a user's first login or when the password is reset. A user account is disabled after five failed login attempts.

TIBCO Administrator Server Configuration Guide

Password Policy 19

The last five passwords used cannot be reused.

Custom Policy You can provide a custom policy that is based on the password policy templates and schema file provided in the TIBCO_HOME/ t r a / version/ c o n f i g / s e c u r i t y directory. After copying a template to another location and modifying it, click the ... icon and load the custom policy file. The file contents are written to the administration domain.

TIBCO Administrator Server Configuration Guide

20

| Chapter 1

Introduction

TIBCO Administrator Server Configuration Guide

| 21
Chapter 2

Fault Tolerance and Load Balancing in a Rendezvous Administration Domain

This chapter discusses fault tolerance, which also provides load balancing for the TIBCO Administrator server when using a TIBCO Rendezvous administration domain. The needs of your integration project determine the complexity of your administration server configuration. This chapter also presents different configuration scenarios.

Topics
Overview, page 22 Load-Balanced Servers, page 25 One Server in One Subnet, page 27 Multiple Load-Balanced Servers in a Subnet, page 28 Multiple Administration Domains in a Subnet, page 30 Administration Domain Spanning Subnets, page 32 Multiple Load-Balanced Servers Spanning Subnets, page 41

TIBCO Administrator Server Configuration Guide

22

| Chapter 2

Fault Tolerance and Load Balancing in a Rendezvous Administration Domain

Overview
TIBCO Administrator provides fault tolerance and load balancing capabilities for client applications. To allow client applications to access the same data from multiple administration servers, a primary server and one or more secondary servers can be installed. Each server should be installed on a separate machine and each machine must be part of the same administration domain. Note that this chapter applies only to administration domains that use TIBCO Rendezvous as the message transport for communication within the domain. The chapter does not apply to your domain if it has been configured to use TIBCO Enterprise Message Service. Fault tolerance and load balancing is implemented using the TIBCO Rendezvous distributed queue protocol (RVDQ). Each logical server has a distributed queue based on the server name. The servers in a distributed queue group share the same server name. The TIBCO Administrator client just sees one logical server. Primary and secondary administration servers can be configured in one of these ways: During installation when using TIBCO Domain Utility to configure the initial administration domain. After installation, when using TIBCO Domain Utility to create or modify an administration domain. After installation, when editing the administration servers property file.

When a client application writes to the application or domain repository (for file-based domains), the primary administration server propagates the changes to the secondary administration servers. If the primary server goes down, clients continue to receive data from the secondary server. While all update requests are handled by the primary administration server, read requests are shared among the primary and secondary servers by use of RVDQ. Updates will automatically propagate from the primary to the secondary servers. You can have any number of secondary servers. Note that this is not full fault tolerance. If the primary server fails, the secondary servers do not automatically elect a new primary. If the primary will be down for an extended period of time, you can change a secondary to a primary by editing the r e p o . m a s t e r property in the primary servers properties file, t i b c o a d m i n _ domain. t r a and restarting the server.

TIBCO Administrator Server Configuration Guide

Overview 23

However, if you are using file storage, there is a small time gap between when the primary receives an update and when it is propagated to the secondary servers, so converting a secondary to a primary for short downtimes is not recommended, and definitely not to deal with network partitions. The most reliable configuration is to have your data stored in a fault tolerant, distributed database that is shared by all servers.

Multiple Secondary Administration Servers

If you install one or more secondary administration servers to run in a fault-tolerant mode, each client request for project information in the administration domain is load-balanced across all administration servers, even if the primary administration server is down. If multiple secondary administration servers are used: Each secondary administration server must run on a different machine and have its own t i b c o a d m i n _ domain-name. t r a file. If you make updates to the configuration using either the TIBCO Domain Utility (recommended) or by editing the t i b c o a d m i n _ domain-name. t r a files, you must restart the administration server on each machine so the changes take effect. If TIBCO Rendezvous is used as the transport between a client application and the administration server, the appropriate administration server responds automatically and there is load balancing across administration servers. For example, if a TIBCO BusinessWorks process uses Rendezvous to make a request to a primary administration server and that server fails, the process request will automatically go to the secondary administration server. If HTTP or HTTPS is used as the transport between a client and the administration server, you must either use an IP redirector or explicitly point to the secondary administration server to be used if the primary server fails. For example, if a TIBCO BusinessWorks process uses HTTP or HTTPS to communicate with TIBCO Administrator, when the primary administration server is unavailable, the process will be unable to communicate with the secondary server as it has different IP or hostname. In this case, the t i b c o . r e p o u r l property in the BusinessWorks process .tra file must be changed to point to the secondary server machines IP address or hostname. Alternatively an external IP redirector can be used to redirect the primary machines IP address or hostname to the secondary machine. See your IP Redirector or HTTP server documentation for information on how to do this.

TIBCO Administrator Server Configuration Guide

24

| Chapter 2

Fault Tolerance and Load Balancing in a Rendezvous Administration Domain

If the primary administration server fails, you can use the secondary server to start or stop processes, but other management tasks such as deploying, undeploying, or deleting application are not allowed. By default, all machines within an administration domain are expected to be in the same network subnet. You can, however, set up your system to use the TIBCO Rendezvous r v r d daemon so the server can communicate with machines on different subnets. See Administration Domain Spanning Subnets on page 32. If the secondary servers are distributed across a WAN, regions can be used to have clients use the local server. See Load-Balanced Servers on page 25 for details.

Secondary Administration Server Startup Fails When setting up a primary and a secondary administration server, if startup of the secondary server fails because it cannot get its initial data, a stack trace message starting with the following appears in the secondary server's console and log file:
java.lang.Exception: Load security program error:null

To resolve this, verify that the time zone settings on the machines that host the primary and secondary servers are in sync.

TIBCO Administrator Server Configuration Guide

Load-Balanced Servers 25

Load-Balanced Servers
If you wish to use multiple load-balanced servers, you must install TIBCO Administrator once for each server. You must designate one server as the primary, and all other servers as secondary servers. For the simplest case, you can just install multiple servers and designate them as a primary or secondary server using the TIBCO Domain Utility, which is launched at the end of installation and can also be invoked separately afterwards. In some cases you also edit properties in the t i b c o a d m i n _ domain. t r a file for each administration server in the domain and restart each server. Optionally, if you set up multiple servers to talk to each other across a WAN, you can use a subject prefix to specify a preference for local servers for clients communicating using TIBCO Rendezvous. The subject prefix is specified in the servers property file in the r e p o . p r e f i x R e g i o n a l S u b j e c t property as explained later in this section. The following properties affect load balancing. The properties are set in the administration servers configuration file, t i b c o a d m i n _ domain-name. t r a . The r e p o . m a s t e r property distinguishes the primary server from the secondary servers. If the value is set to a hostname or default IP address, it is a primary server. Any other value indicates a secondary server. For example, the bogus value 255.255.255.255 indicates a secondary server. As a side effect of enabling fault tolerance, a small _RVFT message is sent once a second. If you do not intend to run in fault tolerant mode, that is, you wish to use only a primary server and no secondary servers, you can disable fault tolerance by commenting out the r e p o . m a s t e r property in the configuration (. t r a ) file. In that case, the _RVFT message is no longer sent. If you comment out the r e p o . m a s t e r property, you cannot add secondary servers until you have manually removed the comment. If the r e p o . i s M a s t e r property is set true, it overrides the r e p o . m a s t e r property to allow the primary server to be specified in a cluster environment. The r e p o . s t a t e property defaults to R E A D _ W R I T E if the r e p o _ m a s t e r property is set. You can set this property to R E A D _ O N L Y explicitly to have a server come up in that state upon startup. The primary server and all secondary servers should have the same value set. This value indicates the global state for the set of servers. By default, the global state is R E A D _ W R I T E . This allows the primary server to handle both read and write requests, while the secondary servers only handle

TIBCO Administrator Server Configuration Guide

26

| Chapter 2

Fault Tolerance and Load Balancing in a Rendezvous Administration Domain

read requests. Some sites wish to limit updates to specific windows of time. The following states are supported: the primary has been set to R E A D _ O N L Y, and the client application tries to perform an operation that involves locking or writing to the application or domain repository, a S E R V E R _ S T A T E _ R E A D _ O N L Y exception results.
R E A D _ W R I T E The R E A D _ O N L Y If

primary servers state must be R E A D _ W R I T E if you wish to make changes to projects. Only the primary server can handle write request, but all secondary servers will continue serving read requests.

The r e p o . p r e f i x R e g i o n a l S u b j e c t property specifies a prefix for the TIBCO Rendezvous subject. In load balancing mode, servers with that prefix are considered preferred servers for read operations. This string is used for giving preference to a group of load balancing servers over the rest of load balancing servers. Each repository client and server which participates in load-balancing may have optional regional information. If this optional property is set, servers in load-balancing mode listen on the extra read subject that incorporates this region. If an optional regional subject is set for a client, the client directs read operations to that subject first. If no server is available, then the client retries using the regular (non-prefixed) read subject. You must set this property explicitly in the t i b c o a d m i n _ domain. t r a for each repository locator string used in client . t r a files.
file

and

The r e p o . u p d a t e S e c o n d a r y S e r v e r P e r s i s t e n t S t o r e property only applies to secondary servers. It determines whether or not secondary servers working in load balancing mode write data into their persistent backend. If the backend is shared by the primary server and this secondary server, this property should be set to f a l s e . If this property is set to t r u e , the secondary server will update not only its cache but also its backend whenever it synchronizes a change with the primary server. Currently this property cannot be set to t r u e for secondary servers that use a database backend. Default value for this property is t r u e . You must set this property explicitly in the t i b c o a d m i n _ domain. t r a
file.

TIBCO Administrator Server Configuration Guide

One Server in One Subnet 27

One Server in One Subnet

Using defaults, an administration server can communicate with multiple client applications. For example, a TIBCO Adapter instance could be requesting adapter configurations or a TIBCO BusinessWorks engine could be accessing information saved to an application repository. The next diagram shows a simple configuration in a single subnet. No setup is required because defaults are used. The default daemon is the default TIBCO Rendezvous daemon, but HTTP or HTTPS could also be used in this scenario. Note that you cannot use HTTP or HTTPS to connect to a 4.x adapter. You must configure HTTPS before using it. Figure 1 One Server in a Single Subnet

Administration Server Daemon: Default

Client 1 Daem on: Default

Client 2 Daem on: Default

Client 3 Daem on: Default

Options
You can use TIBCO Domain Utility to set the following options: Specify a database backend as the persistent store for domain data. Add secondary servers. Specify non-default TIBCO Rendezvous properties or configure HTTPS. Synchronize with an LDAP directory server to manage users and groups. Set Local Application Data as the default deployment option Specify a Password Policy Specify ports for a web server
TIBCO Administrator Server Configuration Guide

28

| Chapter 2

Fault Tolerance and Load Balancing in a Rendezvous Administration Domain

Multiple Load-Balanced Servers in a Subnet

You can install multiple load-balanced servers on different machines in a subnet. When you install TIBCO Administrator, you are prompted to install a primary or a secondary server. The first time you install TIBCO Administrator, you must install a primary server and create an administration domain. All subsequent installations must either create a differently named primary server or set up secondary servers, as follows:

All servers in a load balanced group must use the same TIBCO Rendezvous service and port properties. In Figure 2, all servers use the default TIBCO Rendezvous daemon. When a client sends a request for information, the next available server responds (this speeds up responses in a high-volume situation). When a client writes information, the primary server picks up the information and enters it into the appropriate project. It then automatically sends update notices to all secondary servers in the domain Figure 2 Multiple Load-Balanced Servers in One Administration Domain

Primary Administration Server Daemon: Default State: READ_WRITE

Secondary Administration Server Daemon: Default State: READ

Client 1 Daemon: Default

Secondary Administration Server Daemon: Default State: READ

Using TIBCO Rendezvous, load balancing is automatic. To get the load balancing and fault tolerance benefit with HTTP, you must either use an IP redirector or explicitly point to a backup server to be used when a server fails. See your IP Redirector or HTTP Server documentation for information on how to do this.

TIBCO Administrator Server Configuration Guide

Multiple Load-Balanced Servers in a Subnet 29

Options
You may decide to take advantage of the available options listed in Options on page 27. Updates are propagated automatically to secondary servers, which persistently store the updated data. However, this is a push process with version checks to handle synchronization issues rather than a distributed two-phase commit. To ensure that persistent storage for the server is always synchronized, a database or shared file system must be used. Otherwise, there is a small window of time during which an update may not have been propagated. If the primary server goes down at that time, the secondary server is not able to receive the update until both the secondary and the primary server are running again.

TIBCO Administrator Server Configuration Guide

30

| Chapter 2

Fault Tolerance and Load Balancing in a Rendezvous Administration Domain

Multiple Administration Domains in a Subnet

You can have multiple administration domains in a single subnet (or even on a single machine). The primary servers may be used in conjunction with multiple administration domains, or standalone without domains. Multiple Administration Domains discusses multiple TIBCO administration domains, each with its own primary server. Multiple Servers Using Different Daemon and Service Properties discusses the same scenario for situations where the domain management and security component is not installed.

Multiple Administration Domains

You can have multiple TIBCO administration domains in the same subnet or on the same machine. Each administration domain must have its own administration server. Each domain on a specific machine must have its own name. On each machine, each domain must be distinguished by having a different name. Within a subnet, either a different name or different connection properties will distinguish a domain. However, if connection properties are the same, then only one domain can have a project or application repository of any given name. Deployment will create an application repository name with the domain name prefix. However, for maximum security, it is recommended that you use a different name and different connection properties. In the next illustration, one server is using a domain D1 and another server is using a domain D2. Each server must be a primary server. You can choose to use HTTP for communication between the server and associated project or application repository. However, when you deploy applications or view machine inventory or alert information, the server retrieves this information using TIBCO Hawk agent and it can only communicate with the server using TIBCO Rendezvous.

TIBCO Administrator Server Configuration Guide

Multiple Administration Domains in a Subnet 31

Figure 3 Multiple domains in a single subnet

Primary Administration Server 1 Domain: D1 Access: READ_WRITE

Primary Administration Server 2 Domain: D2 Access: READ_WRITE

Client 1 Domain: D1

Client 2 Domain: D2

Multiple Servers Using Different Daemon and Service Properties

You can use the daemon port and service properties to set up multiple servers in a single subnet. The service port number defines the TIBCO Rendezvous service to be used for the subnet. The different service numbers assigned to different administration servers and their client applications can be used to partition subnets. You can assign different service and daemon port numbers using the TIBCO Domain Utility. Daemon and service port numbers are not required to be the same. However, the recommended practice is to use the same daemon and service port number to avoid confusion. Each client application must set the service and daemon to the port number of the administration server on the same subnet. The properties are set when a machine joins an administration domain and when an application is deployed. On computers with more than one network interface, the network parameter instructs the Rendezvous daemon to use a particular network for all communications involving this transport. To communicate over more than one network, a program must create a separate transport object for each network. See the TIBCO Rendezvous Concepts guide for details.

TIBCO Administrator Server Configuration Guide

32

| Chapter 2

Fault Tolerance and Load Balancing in a Rendezvous Administration Domain

Administration Domain Spanning Subnets

You can extend an administration domain to span subnets by using the TIBCO Rendezvous routing daemon (r v r d ). TIBCO Administrator does not provide built-in support for installation or configuration of r v r d ; this section explains how to do it using the rvrd setup utilities. It is recommended that you simplify network topology as much as possible in the analysis and planning phase. If at all possible, you should architect the solution to use a single subnet. Also, when you plan your networks firewalls, keep in mind that TIBCO Hawk agents in different subnets than the database server (in a database-based domain) must be able to connect directly to the domain repository on the database server.

Introduction
This section explains the basic setup that is required for having your administration domain span subnets. Setup needs to be performed: on two machines for the local and neighbor network for each daemon/service pair and for all appropriate associated TIBCO Rendezvous subjects (as discussed in Setup Tasks on page 33): Subject c o m . t i b c o . r e p o . > , using daemon and service (7500 by default). To filter out unneeded messages, you can also choose from this list. Replace repo_server_name with the name of your server and repo_instance with your server instance name.
c o m . t i b c o . r e p o . repo_server_name. repo_instance. > c o m . t i b c o . repo. instance_ d i s c o v e r y . r e q u e s t c o m . t i b c o . repo. server_ d i s c o v e r y . r e q u e s t c o m . t i b c o . repo. serverH e a r t b e a t . > c o m . t i b c o . repo. instance_ m g m t . repo_server_name. r e q u e s t

If you use secondary servers in your domain, you must also perform setup for these subjects:
_RVFT.> _RVCM.>

TIBCO Administrator Server Configuration Guide

Administration Domain Spanning Subnets 33

_RVCMQ.>

Subject _ H A W K . > (7474 by default) and subject c o m . t i b c o . p o f . It is also possible to set up for the TIBCO Rendezvous subject > (all subjects) if there is relatively little TIBCO Rendezvous traffic on the subnet. This setup can be used at development time for all platforms. At runtime, you have two options: On UNIX systems, you can prepare scripts that can start r v r d for both subjects automatically. On Windows systems, only one Windows Service for r v r d is allowed. Because you would need one service for each subject, using a Windows system for runtime monitoring may therefore be challenging and is not recommended.

Setup Tasks
If you need to set up your domain to span subnets, the following steps are involved: Install Administration Server Install an administration server on one machine (you may later install secondary servers on additional machines for load balancing). Specify the domain name, user name, and password and note them for later use. Decide the Services and Daemons the two Machines will use For each machine, specify the services and daemons used for the two subjects on which the administration server sends and receives messages, for example (by default): Table 3 Subject _HAWK.> com.tibco.repo.> com.tibco.pof.> service 7474 7500 daemon tcp:7474 tcp:7500

It is necessary to listen to each subject you are interested in. See page 32.

TIBCO Administrator Server Configuration Guide

34

| Chapter 2

Fault Tolerance and Load Balancing in a Rendezvous Administration Domain

Figure 4 illustrates how rvrd communicates within and across the subnet: On host drink, rvrd will send out messages via rvrd to other applications in the subnet using udp 7500. Locally, rvrd communicates with those applications that use it directly (for example, TIBCO Designer or TIBCO Administrator) using TCP 7500. rvrd communicates using TCP 7588 to connect to the rvrd on host priya-dt, which is also using tcp 7588. This rvrd is set up in this example to use the same sending and listening port on both machines. Its also possible to use a different port for sending and listening for added security. On host drink2, rvrd is sending out messages via TIBCO Rendezvous using udp 7500.

This description and diagram only illustrates the messages on the subject com.tibco.repo. The setup needs to be duplicated with different tcp and udp connections for the other subjects, for example, _ H A W K . > or c o m . t i b c o . p o f . > Figure 4 Setup of rvrd for Subject "com.tibco.repo.>"
Subnet 1
host drink TIBCO app tcp:7500 rvrd udp:7500 TIBCO Rendezvous

Subnet 2
tcp:7588 subject "com.tibco.repo.>" udp:7500

host drink2 rvrd tcp:7500 TIBCO app TIBCO Rendezvous

TIBCO Administrator Server Configuration Guide

Administration Domain Spanning Subnets 35

Set up and start rvrd on the Administration Server Machine On the administration server machine, TIBCO Rendezvous has been installed as part of the TIBCO Runtime Agent installation and you can set up rvrd without additional installation. Setting up rvrd communication on the first machine consists of these steps: 1. Shut down any TIBCO applications (for example, adapters, TIBCO BusinessWorks). 2. On Windows, use the Services Control Panel and shut down: TIBCO Hawk agent service for the administration domain Administration server service for the administration domain Any other TIBCO services that require a TIBCO Rendezvous daemon to be running. On UNIX systems, kill the above processes. 3. Using the task manager, stop any rvd processes. Make sure the process is not restarted. You cannot configure r v r d if r v d is running.

4. Start two local rvrd services, which write the appropriate storage and log files. As you start rvrd, it is also useful to specify the http port from which each daemon can be configured. You can start the services from the command-line, or using a batch file or script. Heres an example of a Windows batch file:
@echo on start c:\tibco\tibrv\bin\rvrd -store c:\tibco\drink7500.rvrd -listen 7500 -logfile c:\tibco\drink7500.out -http 7599 start c:\tibco\tibrv\bin\rvrd -store c:\tibco\drink7474.rvrd -listen 7474 -logfile c:\tibco\drink7474.out -http 7499

Configure the two rvrd daemons To configure the two rvrd daemons, follow these steps: 1. Open a web browser and go to the rvrd setup screen. To access the TIBCO Rendezvous browser administration interface, point your browser to h t t p : / / host_name: port. Host name can be a machine name or IP address, but sometimes a fully qualified name is required. Default port
TIBCO Administrator Server Configuration Guide

36

| Chapter 2

Fault Tolerance and Load Balancing in a Rendezvous Administration Domain

numbers are listed in TIBCO Rendezvous Administration. For example, http://ip-address:7580/. 2. In the Router Name field, give a name for the router (for example, drink7474), then click Add Router.

The router is listed, with a choice to configure local and neighbor interfaces.

TIBCO Administrator Server Configuration Guide

Administration Domain Spanning Subnets 37

3. Click the number under Local Network. In the screen that is displayed, type the local network name and the service, then click Add Local Network Interface. If you do not include the service, it defaults to 7500. This may result in an error if 7500 is already in use.

4. In the screen that appears, specify the subject to be used, either c o m . t i b c o . r e p o . > or _ H A W K . > , then click Import and Export. For _Hawk.> and the other subjects use different daemons and services. Be sure you are using the appropriate daemon and service for the subject.

TIBCO Administrator Server Configuration Guide

38

| Chapter 2

Fault Tolerance and Load Balancing in a Rendezvous Administration Domain

5. Click Routers again in the left column and choose the number under Neighbor.

6. In the next screen, specify the host, port, and router name for the local and remote port. It is convenient to use the same port locally and remotely, but it is not necessary.

TIBCO Administrator Server Configuration Guide

Administration Domain Spanning Subnets 39

7. Click Add Neighbor Interface. The information, including the IP address, is displayed.

8. Now repeat the steps for the neighbor machine. You have to specify: An interface ID. A router name. The local network name and service. A neighbor interface configuration. 9. Repeat the process for the second daemon and the associated subjects. You can find the HTTP address at which you can configure that daemon by displaying the . o u t file to the console. Restart Administration Server and TIBCO Hawk Agent on First Machine One easy way to do this on Windows platforms is to reboot the machine. Set up Second Machine The second machine is on a different subnet than the first. Setup of the second machine is similar to that of the first. Follow these steps: 1. Install TIBCO Rendezvous, either standalone or as part of TIBCO Runtime Agent. You can perform a custom installation of TIBCO Runtime Agent and only install the TIBCO Rendezvous product. 2. Start two rvrd daemons. See Set up and start rvrd on the Administration Server Machine on page 35. 3. Configure the two rvrd daemons. Follow the steps under Configure the two rvrd daemons on page 35. As you step through daemon configuration, you use the same ports and subjects but a different local and neighbor daemon.

TIBCO Administrator Server Configuration Guide

40

| Chapter 2

Fault Tolerance and Load Balancing in a Rendezvous Administration Domain

Second Machine Joins Domain The final step is to invoke the TIBCO Domain Utility on the second machine and have that machine join the administration domain.

Troubleshooting
If your setup is not successful, that is, the components from the second machine do not show up on the domain inventory, consider these points: The TIBCO Runtime Agent version on the two machines must be exactly the same. Consider restarting the administration server on the machine where it is located. Consider using the wildcard subject (>) if there isnt too much TIBCO Rendezvous traffic on your network.

TIBCO Administrator Server Configuration Guide

Multiple Load-Balanced Servers Spanning Subnets 41

Multiple Load-Balanced Servers Spanning Subnets

You can use the mechanism discussed in Administration Domain Spanning Subnets on page 32 to set up an administration domain with multiple load-balanced servers. To successfully work in this scenario, follow these steps: 1. Install the desired number of servers in the different subnets and configure them, as discussed in Administration Domain Spanning Subnets on page 32. Install only one primary server. All other servers should be secondary (read-only) servers. You must carefully consider which server should be the primary (read-write access) server. The primary server does all project management such as adding and deleting projects, and handles all updates. Consider reliability and network traffic when selecting the primary server. 2. Set up the t i b c o a d m i n _ domain. t r a file for each server to have a r e p o . p r e f i x R e g i o n a l S u b j e c t value. This is optional. The r e p o . p r e f i x R e g i o n a l S u b j e c t property is used to identify and give preference to local servers. If this optional property is set, servers in load-balancing mode listen on the extra read subject that incorporates this region. If an optional region subject is set for a client, the client directs read operations to that subject first. If no server is available, then the client retries using the regular (non-prefixed) read subject. However, deployment does not use this attribute so the repoURL values in each clients property (.tra) file must be updated each time a deployment occurs to take advantage of this.

TIBCO Administrator Server Configuration Guide

42

| Chapter 2

Fault Tolerance and Load Balancing in a Rendezvous Administration Domain

Figure 5 Multiple Load-Balanced Servers Across Subnets

Subnet 1 Primary Administration Server Daemon: pre1_Default Access: READ_WRITE Subnet 2 Secondary Administration Server Subject: pre2_Default Access: READ

Client 1 Subject: pre1_Default

Secondary Administration Server Subject: pre1_Default Access: READ

Client 1 Subject: pre2_Default

TIBCO Administrator Server Configuration Guide

| 43
Chapter 3

Administration Server Properties File

This chapter explains how to perform advanced TIBCO Administrator configuration by editing properties in the administration server properties file.

Topics
Introduction, page 44 General Properties, page 45 Database Storage Properties, page 50 TIBCO Rendezvous Properties, page 52 Logging Properties, page 53 Load Balancing Properties, page 57 Server Security Properties, page 59 Persist Commit History Properties, page 62 TIBCO Hawk Agent Properties, page 63

TIBCO Administrator Server Configuration Guide

44

| Chapter 3

Administration Server Properties File

Introduction
Administration server properties are stored in the t i b c o a d m i n _ domain. t r a file. The file is located in TIBCO_ADMIN_DOMAIN_HOME\ domain-name\ b i n . Most properties in the t i b c o a d m i n _ domain. t r a file that start with t i b c o a d m i n deal with administration server internal communications and should not be changed. Many TIBCO Administrator users need not view or edit properties in the administration server property file directly. Instead, they set up the administration domain and interact with the administration server using TIBCO Domain Utility or the TIBCO Administrator GUI, which writes changes to the property file. In some situations, however, it may be necessary to make explicit changes to the administration server property file. This chapter therefore explains the properties in each property file, what they mean, and possible values. Changes made to the property file take effect the next time the administration server or TIBCO Hawk agent is started.

TIBCO Administrator Server Configuration Guide

General Properties 45

General Properties
The following properties are available to all server-based projects:
f i l e . e n c o d i n g Optional.

Default value is ISO8859-1.

The encoding format for the t i b c o a d m i n _ domain. t r a property file. By default, the property file is encoded as ISO8859-1. The encoding can be changed to UTF-8 to support multibyte characters. Typically, this property is not required if the JVM encoding format and the property file encoding format are the same. However, if your JVM and the property file use different encoding formats, this property must be set to correspond to the property file encoding format.
r e p o . f o r c e I n s t a n c e L o c k s Optional.

Default value is f a l s e .

If this property is set to t r u e , the server takes over any existing instance locks. This automatically allows its projects to be modified by client requests. Warning. This property should only be changed if instance locks have been left hanging by another server and need to be broken. Careless use of this property causes the former lock holder to immediately become read-only, and any pending changes by any of its clients to be lost.
r e p o . i n s t a n c e N a m e s Optional.

Use of this option is not recommended.

A comma-separated list of projects to which the server connects. If the list is empty, the server connects to all projects matching its search criteria. A server-based project exists for a server under these circumstances: Storage is a file, there is a project with a . d a t extension in the servers search directory, and the files contents is a valid TIBCO project. Storage is a database and there is project entry in the database tables of the database to which the server connects with the specified JDBC properties and user ID. If the list contains entries, the server connects to the existing server-based projects and throws warnings for non-existing server-based projects.
r e p o . l o c k T i m e o u t Optional.

Default value is 120 seconds.

The number of seconds the server is willing to wait without hearing from a client that has locked various resources, before automatically freeing those resources. This option does not apply to project instance locks.

TIBCO Administrator Server Configuration Guide

46

| Chapter 3

Administration Server Properties File

r e p o . m i n i m i z e H a n d s h a k e I n t e r v a l Optional.

Default value is f a l s e .

Bypass delay while checking for duplicate servers during startup if t r u e . This is for use only while testing. Warning. This is an extremely dangerous option. If there are multiple servers in the environment, this could allow two servers with the same name to be operational simultaneously for a short period of time. During this time clients might get duplicate or contradictory messages leading to invalid states, exceptions, and possibly data corruption. Be absolutely sure to set this to f a l s e in production environments.
r e p o . q T h r e a d C n t Optional.

The default is 1. The value is set to 2 by the

TIBCO Domain Utility. The queue thread count controls how many threads the server uses to process client read requests for each project. If this value is 2 or more, read requests are processed during commits, but the required memory and number of threads increases. The number can be increased if client applications are waiting and the CPU is running at less than 100 percent.
r e p o . s e r v e r H e a r t b e a t I n t e r v a l Optional.

Default value is 30000 (30

seconds). Specifies the server heartbeat interval in milliseconds. Server heartbeats allow clients to detect when a server goes down. Consider increasing the interval if network delays are causing false time-outs after waits of less than the value given. Any number less than 1000 is considered to be in seconds. For example 900 is not 0.9 seconds, but rather 15 minutes.
r e p o . s e r v e r N a m e Required.

Name of the administration domain. Do not change this property. The server name is set during installation in multiple locations based on user input. Changing the name only here results in an inconsistent environment.
r e p o . s e r v e r P a s s w o r d Optional.

Use this password to avoid accidental changes to projects (for example, deleting projects) when security is turned off. This password is not used if you are running TIBCO Administrator and included the security and domain management component during installation.
TIBCO Administrator Server Configuration Guide

General Properties 47

r e p o . s e c u r e S t a t e m e n t U s e O l d L o c a l e This

property specifies the locale to be used by the statement generation logic when generating date and time strings. This is false by default and the default locale is US English. However, for compatibility with old clients, administrator may set this to true and it will generate date/time strings that are compatible with both older and new clients.

Security authentication does not work if the administration server is 5.0.1 or later and the client is pre-5.0.1. Setting the r e p o . s e c u r e S t a t e m e n t U s e O l d L o c a l e property to true allows this combination to work.
j a v a . p r o p e r t y . t r a _ d e p l o y _ t i m e o u t When

deploying large applications the TIBCO Hawk agent can time-out before deployment completes, causing it to fail. Depending on your TIBCO Runtime Agent installation version, this can be addressed as follows: If TIBCO Runtime Agent 5.2.1 or greater is installed on the deployment target machines and on the machine that hosts the administration server, you can increase the value for the j a v a . p r o p e r t y . t r a _ d e p l o y _ t i m e o u t property in the TIBCO_ADMIN_DOMAIN_HOME\ domain-name\ b i n \ t i b c o a d m i n _ domain-name. t r a file.

If you are using the appManage utility (version 5.2.1 or greater) to deploy applications, you can increase the value for the j a v a . p r o p e r t y . t r a _ d e p l o y _ t i m e o u t property in the TIBCO_TRA_HOME\ b i n \ A p p M a n a g e . t r a file. If TIBCO Runtime Agent 5.2.0 or greater is installed on the deployment target machines and TIBCO Runtime Agent 5.2.0 or greater is installed on the machine that hosts the administration server, you can increase the value for the t r a _ d e p l o y _ t i m e o u t property in the TIBCO_TRA_DOMAIN_HOME\ domain-name\ h a w k a g e n t . c f g file on each target machine where deployment is failing due to the Hawk agent timing out.
t i b c o a d m i n . c l i e n t . e n c o d i n g Specifies the character encoding that is used to encode the HTML sent to the browser. In most cases UTF-8 is the best choice as it can handle all character sets. In some cases, a different encoding that is tailored to the specific character set(s) being used may offer slightly better performance. t i b c o a d m i n . a u t o R e f r e s h I n t e r v a l Specifies the interval, in milliseconds, that is used for the auto-refresh feature on the monitor screens. Default is 20000. t i b c o a d m i n . m o n i t o r . t r a c e L o g M a x L i n e s Specifies

the maximum number of lines to retrieve during a trace log search. Default is 1000.

TIBCO Administrator Server Configuration Guide

48

| Chapter 3

Administration Server Properties File

D i s a b l e A d m i n i s t r a t o r C l e a r L o c k s Objects stored in the admininstration, authorization and application domains can acquire locks. By default, these locks are cleared when the administration server starts. You can change this behavior by setting D i s a b l e A d m i n i s t r a t o r C l e a r L o c k s to true so that locks are not cleared when the administration server starts for the administration domain where the property is set. The property can be set in the A d m i n i s t r a t i o n D o m a i n . p r o p e r t i e s and A u t h o r i z a t i o n D o m a i n . p r o p e r t i e s files, which are located in the TIBCO_HOME\ t r a \ d o m a i n \ domain-name folder.

TIBCO Administrator Server Configuration Guide

File Storage Properties 49

File Storage Properties

The following properties affect administration domains that use a file repository for storage.
r e p o . d i r e c t o r y Location

in which the server will look for file-based

projects. Set by TIBCO Domain Utility to

TIBCO_ADMIN_DOMAIN_HOME/ domain_name/ d a t a . If this property is

removed or commented out, the location is set to a d m i n i s t r a t o r / b i n . You can also specify the path. Note that you must use forward slashes, for example, c : / t i b c o / a d m i n i s t r a t o r / d a t a .
r e p o . f i l e T y p e Optional.

The file type is XML.

The format to use for storing projects on the server. The values are in XML. XML. XML has the advantage of being human readable, making it easy to use for development and debugging. However, XML format files are easily corrupted. TIBCO Designer can export all projects, regardless of storage format, to an XML file. Similarly, TIBCO Designer can also import the contents of a TIBCO Repository XML file to any project, however, the export file cannot be used as a project.

TIBCO Administrator Server Configuration Guide

50

| Chapter 3

Administration Server Properties File

Database Storage Properties

The following properties are required for administration server-based projects that use a database for storage. If values are not specified for any of these properties, the server uses a file for storage. These properties must be defined for a database backend for project and application repositories.
r e p o . j d b c D r i v e r Required

if database storage is used.

There is no default value. Name of the JDBC driver this server uses to connect server-based projects to their database. An example would be o r a c l e . j d b c . d r i v e r . O r a c l e D r i v e r. Must be commented for file-based storage.
r e p o . j d b c U R L Required

if database storage is used. There is no default

value. JDBC URL this server uses to connect its server-based projects to their database. Must be commented for file-based storage.
r e p o . u s e r n a m e Required

if database storage is used. No default value.

JDBC database account user name this server uses to connect its server-based projects to their database. Must be commented for file-based storage.
r e p o . p a s s w o r d Optional.

No default value.

JDBC database account password this server uses to connect its server-based projects to their database. This property is completely unrelated to TIBCO Administrator security or the password for the super user of the administration domain. Must be commented for file-based storage.
r e p o . d b t y p e Required

if database storage is used. No default value.

Database type. Values can be O r a c l e , D b 2 , S y b a s e or S q l (Sql is Microsoft SQL Server). Case is significant. Must be commented for file-based storage.
r e p o . d e l a y F o r D B S t a r t u p Optional.

Default value is 0.

TIBCO Administrator Server Configuration Guide

Database Storage Properties 51

Changing this property is useful if a database is not ready immediately. It allows for a delay between when the server is started and when it first tries to communicate with the database. The delay is in seconds. This property has no effect for file-based projects.
d a t a b a s e . d e f a u l t . m i n C o n n e c t i o n s Number

of database connections to cache per domain instance. No connections are allocated by default.

d a t a b a s e . d e f a u l t . r e c o n n e c t I n t e r v a l Interval in milliseconds to ping to determine if a server has come back online. Default is 5 seconds. d a t a b a s e . d e f a u l t . p i n g I n t e r v a l Interval in milliseconds to ping the server for keepalive through firewalls. Default is 5 minutes.

TIBCO Administrator Server Configuration Guide

52

| Chapter 3

Administration Server Properties File

TIBCO Rendezvous Properties

The following properties are optional. In most cases, the default settings for these properties are appropriate. Use TIBCO Domain Utility to change these properties. If you change these properties in the administration server properties file, your administration domain may become inconsistent.
r e p o . e n c o d i n g Optional.

The default value is ISO8859-1.

Specifies the character encoding for communication between the administration server and the components it manages. Valid values are ISO8859-1 or UTF-8. To use a character set other than Latin-1, use UTF-8. See Internationalization on page 78. If you do not set this value to UTF-8, data loss may result if your data are multi-byte characters.
r e p o . r v D a e m o n Optional.

The default value is t c p : 7 5 0 0 .

This property specifies where to find the TIBCO Rendezvous daemon for this session. This allows a client to access a server on a different subnet without using r v r d .
r e p o . r v N e t w o r k Optional.

No default value.

Network to use. If not given, the primary network interface for the host computer is used. Set this property on computers that have more than one network interface to specify the interface to use.
r e p o . r v S e r v i c e Optional.

Default is 7500.

Service group for this session. Set this property to partition servers on different networks.

TIBCO Administrator Server Configuration Guide

Logging Properties 53

Logging Properties
Information about administration server management operations can be logged to the console window, a file in a specified directory, or both. In addition, log records can be sent to the Windows event log if you are running on a Windows operating system. File names are of the form repo.logFileNamePrefix .number, where repo.logFileNamePrefix is based on the property listed below and number is a unique ID. Each time the administration server is started, a new log file is created. By default twenty log files are kept. Log files normally grow only to a certain maximum size (default is 100KB). After reaching this limit, the log file is closed and a new log file is opened. The following properties define how logging occurs. The properties listed in this section only apply to project (data store) logging operations. TIBCO Administrator has a separate log for administration server operations. To look at that log, see TIBCO_TRA_DOMAIN_HOME/domain-name/ l o g s / A d m i n i s t r a t o r . l o g
t i b c o a d m i n . m o n i t o r . t r a c e L o g M a x L i n e s Default

value is 1000.

Specifies the max number of lines to retrieve in trace log search. If the TIBCO Administrator GUI is not able to display the log because it is too big, change this number or add filters to the log search.
r e p o . l o g O p e r a t i o n s Optional.

Default value is f a l s e .

If set to t r u e , information about project management operations is logged. Information is logged to a file sink, as well as to the console. To set up a file sink, use the r e p o . l o g D i r e c t o r y property. To specify the level of the severity of events to log, use the r e p o . l o g L e v e l property.
repo.logDirectory

Optional. Default value is

TRA_HOME/ t r a / d o m a i n / domain/ a d m i n i s t r a t o r / version/ t o m c a t .

Path to directory. If set, logging is printed to the console and to a file in the specified directory. If the property is not set, then the l o g directory under the current working directory is used. File names are of the form repo.logFileNamePrefix. number, where number is a unique id, and the repo.logFileNamePrefix value is given as another property of this file. Each time the server is started, a new file is created.

TIBCO Administrator Server Configuration Guide

54

| Chapter 3

Administration Server Properties File

r e p o . l o g F i l e N a m e P r e f i x Optional.

R e p o s i t o r y S e r v e r . repo.serverName. l o g

Default value is where the repo.serverName value is

given as another property of this file. This property holds a prefix for the log file name. This property is effective only when r e p o . l o g O p e r a t i o n s is set to t r u e .
r e p o . l o g F i l e M a x N u m b e r Optional.

Default value is 20.

Maximum number of most recent log files that are maintained by the server. Only the most recent log files are kept.
r e p o . l o g F i l e M a x S i z e Optional.

Default value is 100KB.

Log file size limit. Log files normally grow only to a certain maximum size. After reaching this limit, the file is closed and a new file is opened. The limit is in bytes.
r e p o . l o g L e v e l Optional.

Default value is I n f o .

Specify the minimum severity level of events to log. The server supports the following logging levels.
Error:

only error messages are logged.

W a r n : warning messages are logged in addition to all the messages at E r r o r

level.
Info: Warning

informative messages are logged in addition to all the messages of level.

Verbose: Info

verbose messages are logged in addition to all the messages of level. This logs debugging messages. Default value is N o n e .

r e p o . w i n d o w s E v e n t L o g L o g L e v e l Optional.

Specifies the level of logging on Microsoft Windows Event Log. When the server is running on a Microsoft Windows system, it can write log messages on the Windows event log service as well as console or file. This property is effective only when the operating system is Microsoft Windows.

TIBCO Administrator Server Configuration Guide

Logging Properties 55

The server supports the following levels of logging.

None:

no messages are logged to the Microsoft Windows event log.

E r r o r : only error messages are logged to the Microsoft Windows event log. Warning: Error Info:

warning messages are logged in addition to all the messages of level.

Warning Debug:

informative messages are logged in addition to all the messages of level. debug messages are logged in addition to all the messages of I n f o

level.

TIBCO Administrator Server Configuration Guide

56

| Chapter 3

Administration Server Properties File

Security Audit Properties

The following properties affect the security audit file:
repo.auditFileSize

Specifies the default audit file size. Default value is 200,000.

repo.auditFileNum

Specifies the default audit file number. Default value is 20.

repo.auditFileName

Specifies the default audit file name. Default value is a u d i t . l o g .

TIBCO Administrator Server Configuration Guide

Load Balancing Properties 57

Load Balancing Properties

The following properties are available for load balancing of multiple administration servers.
r e p o . m a s t e r Optional.

Default is no value, in that case, the server does not

perform load balancing. The r e p o . m a s t e r property must be set to either the host name or the IP address of the administration server you want to use as the primary server. The property is set during installation and can be changed by editing this file. During domain creation, r e p o . m a s t e r is set to the hostname of the server. When secondary servers are added, it is given the value "255.255.255.255". As a side effect of enabling fault tolerance, a small _RVFT message is sent out once a second. If you started running in fault tolerant mode, but then wish to use only one server, you can disable fault tolerance by commenting out the r e p o . m a s t e r property in the configuration (. t r a ) file. In that case, the _RVFT message is no longer sent. If you comment out r e p o . m a s t e r, you cannot add secondary servers until you have manually removed the comment. If the r e p o . i s M a s t e r property is set true, it overrides the r e p o . m a s t e r property to allow the primary server to be specified in a cluster environment.
r e p o . s t a t e Optional.

Defaults to R E A D _ W R I T E .

Specifies the global state. If other servers in the load-balanced group are up, this server will switch to their state before processing client requests. You can set this property explicitly to R E A D _ O N L Y to have a primary server come up in that state upon startup.
r e p o . s t a t e will not effect Local deployment on a Database based domain, but will block RV or HTTP deployment on a Database based domain. Secondary servers should have the values set to the same as the primary server. This property should not be READ_ONLY unless the primary can lead to synchronization problems. repo.state

should not be used with file based domains.

r e p o . p r e f i x R e g i o n a l S u b j e c t Optional.

Default is no value.

TIBCO Administrator Server Configuration Guide

58

| Chapter 3

Administration Server Properties File

The r e p o . p r e f i x R e g i o n a l S u b j e c t property specifies a prefix for the TIBCO Rendezvous subject. In load balancing mode, this prefix is used to consider servers with that prefix preferred servers for read operations. This string is used for giving preference to a group of load balancing servers over the rest of the load balancing servers. Each client and server participating in load-balancing may have optional regional information. If this optional property is set, servers in load-balancing mode listen on the extra read subject that incorporates this region. If an optional region subject is set for a client, the client directs read operations to that subject first. If no server is available, then the client retries using the regular (non-prefixed) read subject.
r e p o . u p d a t e S e c o n d a r y S e r v e r P e r s i s t e n t S t o r e Optional. true.

Defaults to

The r e p o . u p d a t e S e c o n d a r y S e r v e r P e r s i s t e n t S t o r e property only applies to secondary servers. It determines whether or not secondary servers working in load balancing mode write data into their persistent backend. If the backend is shared by the primary server and this secondary server, this property should be set to f a l s e . If this property is set to t r u e , the secondary server will update not only its cache but also its backend whenever it synchronizes a change with the primary server. Currently this property cannot be set to t r u e for secondary servers that use a database backend. Default value for this property is f a l s e .

TIBCO Administrator Server Configuration Guide

Server Security Properties 59

Server Security Properties

The following properties govern how the administration server handles security.
r e p o . i s S e c u r i t y E n a b l e d Optional.

Default value is t r u e .

This is the master switch for security. If its value is f a l s e , other security related properties have no meaning. Specify whether the server is security-enabled. If this property value is a text string set to t r u e , the server is security-enabled. The server is always either secure or not. There is no way to programatically turn security on or off.
r e p o . c h e c k S e c u r i t y O n l y O n P o l i c y M a n a g e m e n t Optional. false.

Default value is

Specify whether the server checks security only on the operations that update security policies. If this property value is a text string set to t r u e , the server checks security only on the policy management operations that update security policies. Other operations do not get any security checked by the server. This property is relevant only if the r e p o . i s S e c u r i t y E n a b l e d property is set to t r u e for this server. This property is for production time when replacing an old version of a legacy server with a new, secured server. Users can configure security policies first while other operations are still being served without security checked. Using the default value is strongly recommended.
r e p o . s e c u r e G u e s t P a s s w o r d Optional.

Default value is an empty string.

repo.secureGuestUsername.

This property must match the password for the user specified by Use this option to allow 3.x applications to access an instance of a repository 4.x or later on a secure server. This property requires that security be enabled via the i s S e c u r i t y E n a b l e d property.

r e p o . s e c u r e G u e s t U s e r n a m e Optional.

Default value is g u e s t .

When security is enabled, this property specifies the user to use for 3.x applications. Use this option to allow 3.x applications to access an instance of a repository 4.x or later on a secure server. A client can continue accessing a project after its password has been changed until its security statement times out.
TIBCO Administrator Server Configuration Guide

60

| Chapter 3

Administration Server Properties File

Any message received from a client that doesn't contain an authentication statement is treated with the authority of the r e p o . s e c u r e G u e s t U s e r n a m e user. To create an authentication statement, the server uses r e p o . s e c u r e G u e s t U s e r n a m e user with its password specified in another property of this file, r e p o . s e c u r e G u e s t P a s s w o r d . The r e p o . s e c u r e G u e s t U s e r n a m e user must be explicitly defined in the security policy backend with its password specified by repo.secureGuestPassword. It is perfectly valid for the s e c u r e G u e s t U s e r n a m e user not to exist. Such a situation completely blocks access to unauthenticated users for all instances maintained by that server. Similarly, the s e c u r e G u e s t U s e r I d user must be explicitly granted access rights in the same way any other user would be granted rights. There are no automatic rights, nor are there any limits to the rights granted. All unauthenticated users share the same privileges.
isSecurityEnabled

This property requires that security be enabled be enabled via the property. Name of the user with full Administrator

r e p o . s e c u r e U s e r n a m e Optional.

privileges. This is the user specified as the domain administrator for the administration domain when it was created. The domain administrator can use the TIBCO Administrator user management module to specify additional users with full Administrator privileges. This property is meaningful only when r e p o . i s S e c u r i t y E n a b l e d property is set to t r u e .
r e p o . s e c u r e P a s s w o r d Optional.

Password for the u s e r n a m e specified in the r e p o . s e c u r e U s e r n a m e property.

This is the password specified for the domain administrator for the administration domain. This property is meaningful only when r e p o . i s S e c u r i t y E n a b l e d property is set to t r u e .
r e p o . s e c u r e S t a t e m e n t D u r a t i o n Optional.

Default value is 3600.

The number of seconds a security statement generated by a server is valid for a given client. Clients automatically renew their security statements when they expire.
r e p o . i s R e p o N a v i g a t o r E n a b l e d Optional.

Enables the use of the

Repository Navigator. When set (repo.isRepoNavigatorEnabled=true) the repository instances on the server can be viewed using the URL: http://host:port/administrator/repo.

TIBCO Administrator Server Configuration Guide

Server Security Properties 61

When this property is enabled, any user can view global variables, which may be a security risk. If security is a concern, this property should not be enabled.

TIBCO Administrator Server Configuration Guide

62

| Chapter 3

Administration Server Properties File

Persist Commit History Properties

The administration server enables records of commits for server-based application repositories when it is using HTTP to communicate with clients or when it is working in load-balanced mode. Commit history files are different than revision histories, which are created by the deployment process and stored in the administration domain data. It is always safe to delete commit history files. They are used as an optimization for synchronization and HTTP client applications.
r e p o . c o m m i t H i s t o r y D i r e c t o r y Directory

for commit history files. Default is a h i s t o r y directory inside the directory where Administrator was installed, for example, c : \ t i b c o \ a d m i n i s t r a t o r \ 5 . 1 \ b i n \ h i s t o r y.

If this property is set, commit files are generated in the specified directory. If the property is not set, then a h i s t o r y directory under current working directory will be created and used. File names are of the form "project. number. c o m m i t ", where project is a project name, number is a commit number. By default there is no limit on the number of files. This can be changed by the r e p o . c o m m i t H i s t o r y F i l e M a x N u m b e r property.
r e p o . c o m m i t H i s t o r y F i l e M a x N u m b e r Optional.

Default value is -1

This property specifies the maximum number of commit files that are maintained for a project. If the number of files exceeds this limit, the file that has oldest commit number will be overwritten. If the value is set to 0, then no external file will be generated. If the value is set to -1, then an unlimited number of external files is generated.
r e p o . d e p l o y m e n t D i r e c t o r y Deployment

variable directory

This property specifies the directory where deployment variables are stored persistently. The name of the file will be instanceName.s u b s t v a r. If this property is not set, the deployment variables will be stored in the directory holding file-based projects.

TIBCO Administrator Server Configuration Guide

TIBCO Hawk Agent Properties 63

TIBCO Hawk Agent Properties

Use TIBCO Domain Utility to change these properties. If you change these properties directly in the administration server properties file, your administration domain may become inconsistent. These values effect the administration servers own microagent.
r e p o . h a w k I m p l a n t Optional.

Default value is t r u e .

This property specifies whether the server must create a TIBCO Hawk microagent (implant) when it starts.
false,

If the value is set to t r u e , the server creates a microagent. If the value is set to the server does not create a microagent. If the value is set to t r u e , but TIBCO Hawk is not running, the server does not create a microagent. The default value is t c p : 7 4 7 4

r e p o . h a w k D a e m o n Optional.

The TIBCO Rendezvous daemon property that specifies the TIBCO Hawk Rendezvous session used by this server.
r e p o . h a w k N e t w o r k Optional.

No default value.

The r v d network for the server's Hawk RV session used by this Administrator process.
r e p o . h a w k S e r v i c e Optional.

Default value is 7 4 7 4 .

The r v d service for the server's Hawk RV session used by this Administrator process.
r e p o . h a w k M a x T h r e a d Optional.

Default is 2.

This value specifies how many threads should process TIBCO Hawk AMI requests for this server. This value is limited to 9. If a number larger than 9 is used, the server defaults to 9 and ignores the given value.
r e p o . h a w k M i c r o A g e n t N a m e Optional. COM.TIBCO.REPOSITORYSERVER.

Default value is

Specify the name of the TIBCO Hawk microagent for this server. This name uniquely identifies this server as a TIBCO Hawk microagent in the Hawk console.

TIBCO Administrator Server Configuration Guide

64

| Chapter 3

Administration Server Properties File

Java Properties java.heap.size.initialdefines the initial heap size for the Java VM that will be invoked. java.heap.size.maxspecifies the maximum heap size. The JVM reserves this much memory at start-up and memory used for object allocation cannot exceed this amount. java.thread.stack.sizeIf you are deploying an application on a Unix machine and get the following error,
java.io.IOException: Not enough space at java.lang.UNIXProcess.forkAndExec(Native Method)

you should increase the value for this property.

TIBCO Administrator Server Configuration Guide

| 65
Chapter 4

Advanced Topics

This chapter discusses advanced topics.

Topics
Server-based Repository Locator String, page 66 Local Repository Locator String, page 72 Using a Properties File to Encapsulate Locator String Components, page 74 Configuring Connection Pool Size for the Database Server, page 75 Enabling an SSL Connection to an LDAP Directory Server, page 76 Maintaining Connections to an LDAP Directory Server, page 77 Internationalization, page 78 Configuring EHCache, page 82 Authenticating Users, page 85 Repository Locking, page 89 Remote Server Shutdown, page 90 Global Variables, page 91

TIBCO Administrator Server Configuration Guide

66

| Chapter 4

Advanced Topics

Server-based Repository Locator String

Applications built using the TIBCO Adapter SDK use a locator string to specify their application datas repository location and other properties. The locator string is also used by repository management tools (see Chapter 5, Command Line Utilities), TIBCO BusinessWorks engines, and other TIBCO products. Depending on how a client accesses the domain repository (4.x legacy projects) or application repository, the locator string differs, as discussed in the following sections: TIBCO Rendezvous HTTP and HTTPS

TIBCO Rendezvous
In case of a TIBCO Rendezvous transport, the locator string begins with t i b c r : / / or t i b c r @ , followed by the instance name. In addition, the optional properties listed in Table 4 are supported. Each property is separated by a colon. Table 4 Optional properties for server-based locator string (TIBCO Rendezvous) Property daemon service network subject discoveryTime timeout operationRetry userName password Description TIBCO Rendezvous r v d daemon value. TIBCO Rendezvous r v d service value. TIBCO Rendezvous r v d network value. Instance discovery subject. Timeout value in seconds for instance discovery. Timeout value in seconds for server requests. Number of retries when timeout occurs. Any identifier (null or empty implies read only with guest privileges). User password for security.

TIBCO Administrator Server Configuration Guide

Server-based Repository Locator String 67

Table 4 Optional properties for server-based locator string (TIBCO Rendezvous) Property regionalSubject Description TIBCO Rendezvous subject prefix used for regional read-operation in the load balancing mode. For additional information see Load Balancing Properties on page 57. Type of client connection. Valid values are: urlFile
C L I E N T _ U S A G E _ D O N T _ C A R E Client reads until update, then switches to write. This is the default. C L I E N T _ U S A G E _ R E A D _ O N L Y Client

typeAccess

is not allowed to do can do both reads

updates.
C L I E N T _ U S A G E _ R E A D _ W R I T E Client

and updates. Property file. The property file identifier can either be a fully qualified path or a relative path. The legal properties in this file are the same as optional properties specified above. The properties in the file are appended to the repository locator string. If the same property appears in both locator string and property file, the properties in the locator string take precedence. Property values starting with #! are considered marked for encryption.
obfuscate

Encryption can be performed explicitly by running the tool in tibco_home\ t r a \ n.n\ b i n . The tool obfuscates all values starting with #!. For example, if a file contains this value:

repo.serverPassword=#!RepoTestServerPass

Running the obfuscate utility makes this change in the file:

repo.serverPassword=#!yecjXiS6JikkPrfNre8i/HqbO9a foyl6ACkGtzRPFFhaupSC1v0ApRLyyS+LOXtG

See the TIBCO Runtime Agent Installation guide for additional information. Examples
tibcr://myInst:service=5456:userName=ann:timeout=4000 tibcr@myInst:service=5456:urlFile=/tibco/props/fredsProps.txt tibcr://myInst:urlFile=/tibco/props/fredsProps.txt

TIBCO Administrator Server Configuration Guide

68

| Chapter 4

Advanced Topics

HTTP and HTTPS

In case of HTTP transports, the locator string begins with h t t p : / / . In case of HTTPS transports (HTTP over Secure Socket Layer) the locator string begins with h t t p s : / / . Host name and port number are next (h t t p : / / host: port). For Java clients, the port number is optional. If it is not specified, the default value used is 8080 for HTTP and 8443 for HTTPS. For C++ clients the port number is required.

The host name and port number are followed by the instance name, which is preceded by a question mark (?), for example, h t t p : / / h o s t : 8 0 8 0 / ? i n s t 1 Optionally, a d m i n i s t r a t o r / r e p o may be included as part of the instance name, for example, h t t p : / / h o s t : 8 0 8 0 / a d m i n i s t r a t o r / r e p o / ? i n s t 1 HTTPS-specific properties should be placed in a property file and that file should be specified using " u r l F i l e = " . If you do not wish to specify HTTPS validation properties, u r l F i l e is not a required property for HTTPS. In addition, remote HTTP or HTTPS clients support the following optional properties separated by &. Note that when & is used as the separator of properties, and the URL is specified on the command line, the URL should be enclosed in quotes so that the shell does not interpret it. Table 5 Optional properties for server-based locator string (HTTP) Property timeout operationRetry userName password Description Timeout value in seconds for server requests. Number of retries if a timeout occurs. Any identifier (null or empty implies read only with guest privileges). User password for security.

TIBCO Administrator Server Configuration Guide

Server-based Repository Locator String 69

Table 5 Optional properties for server-based locator string (HTTP) Property typeAccess Description Specifies whether access is read only or read-write. Valid values are: urlFile
C L I E N T _ U S A G E _ D O N T _ C A R E Client reads until update, then switches to write. This is the default. C L I E N T _ U S A G E _ R E A D _ O N L Y Client

is not allowed to do can do both reads

updates.
C L I E N T _ U S A G E _ R E A D _ W R I T E Client

and updates. Property file. The property file identifier can either be a fully qualified path or a relative path. The legal properties in this file are the same as optional properties specified above. The properties in the file are appended to the repository locator string. If the same property appears in both locator string and property file, the properties in the locator string take precedence. Property values starting with #! are considered marked for encryption.
obfuscate

Encryption can be performed explicitly by running the tool in tibco_home\ t r a \ n.n\ b i n . The tool obfuscates all values starting with #!. For example, if a file contains this value:

repo.serverPassword=#!RepoTestServerPass

Running the obfuscate utility makes this change in the file:

repo.serverPassword=#!yecjXiS6JikkPrfNre8i/HqbO9 afoyl6ACkGtzRPFFhaupSC1v0ApRLyyS+LOXtG

See the TIBCO Runtime Agent Installation guide for additional information. Examples
"http://host:8080?myInst&userName=ann&timeout=4000" "http://host:8080/administrator/repo?myInst&userName=ann&timeout= 4000" "https://host:8443?myInst&urlFile=httpsProps.ini" "https://host:8443/administrator/repo?myInst&server=s1&userName= bob&password=bswrd" "https://host:8443/administrator/repo?myInst&urlFile= httpsProps.ini"

TIBCO Administrator Server Configuration Guide

70

| Chapter 4

Advanced Topics

Creating a urlFile for Use With HTTPS To use HTTPS, the following information must be included in the properties file: Table 6 Properties Required for HTTPS urlFiles Property
trustedCertFormat

Description Format of the SSL certificate. Can be one of P12, P7, PEM, DER, EPF, or keystore. Only PEM is supported for C++ repository clients.

httpsVendor

Name of the SSL provider. For Java repository clients, this can be either j 2 s e or e n t r u s t 6 1 . This string is case sensitive. For C++ repository clients, openssl is the only vendor supported so this property is ignored.

keyFile

Key file. Keys can either be embedded (P12 and keystore) or non-embedded (PEM, P7, DER). Key file is relevant only for non-embedded key files, that is, PEM, DER, and P7.

keyPassword identityFile identityType trustedCertPassword

Password associated with the key file. Location of the identity file. Format of the identity file. Can be one of P12, P7, PEM, DER, keystore, EPF. Password for the certificate specified by This property is not relevant for C++ repository clients.
trustedCerts.

trustedCerts

Location of the trusted certificate or certificate chain. Not relevant for Java applications. For C++ applications, using HTTPS transport on UNIX platforms other than Linux, this property specifies the location of the socket from which to get the random number.

egdSocket

TIBCO Administrator Server Configuration Guide

Server-based Repository Locator String 71

Example for Java Applications Following is an example for a url file containing HTTPS-specific properties for Java applications:
httpsVendor=j2se trustedCerts=H:/downloads/certs/clientcerts/trustedcerts/RSA/PEM/ RSA1024ca1.cert.PEM trustedCertFormat=PEM trustedCertPassword=RSA1024ca1 identityFile=H:/downloads/certs/clientcerts/idcert/RSA/P12/ RSA1024ca2.cert.P12 identityType=P12 keyPassword=RSA1024ca2

Example for C++ Applications Following is an example for a url File containing HTTPS specific properties for a C++ application:
httpsVendor=j2se trustedCerts=H:/downloads/certs/clientcerts/trustedcerts/RSA/PEM/ RSA1024ca1.cert.PEM trustedCertFormat=PEM trustedCertPassword=RSA1024ca1 identityFile=H:/downloads/certs/clientcerts/idcert/RSA/P12/ RSA1024ca2.cert.P12 identityType=P12 keyPassword=RSA1024ca2 egdSocket=/etc/egd-pool

TIBCO Administrator Server Configuration Guide

72

| Chapter 4

Advanced Topics

Local Repository Locator String

Applications built using the TIBCO Adapter SDK use a locator string to specify the repository location and other properties. For local repositories, the string starts with the instance name, which can optionally be preceded by l o c a l r e p o @ . The instance name can either be a fully qualified path or a relative path. The . d a t extension is optional. In addition, clients support the following optional properties separated by colons: Table 7 Optional properties for local repository locator string. Property userName typeAccess Description Any identifier (if not present or empty makes a read-only client). Type of client connection. Valid values are:
C L I E N T _ U S A G E _ D O N T _ C A R E Client

reads until update, then switches to write. This is the default. is not allowed to do can do both reads

C L I E N T _ U S A G E _ R E A D _ O N L Y Client

updates.
C L I E N T _ U S A G E _ R E A D _ W R I T E Client

and updates.
C L I E N T _ U S A G E _ R E A C Q U I R E _ I N S T A N C E _ L O C K Client

is allowed to overwrite this local repository even if a lock file exists, as long as its the same user.

is allowed to overwrite this local repository even if a lock file exists. W A R N I N G : Using this option may result in other users overwriting your project.

C L I E N T _ U S A G E _ F O R C E _ I N S T A N C E _ L O C K Client

See Repository Locking on page 89 for additional information.

TIBCO Administrator Server Configuration Guide

Local Repository Locator String 73

Table 7 Optional properties for local repository locator string. Property urlFile Description Property file. The property file identifier can either be a fully qualified path or a relative path. The legal properties in this file are the same as optional properties specified above. The properties in the file are appended to the repository locator string. If the same property appears in both locator string and property file, the properties in the locator string take precedence. Property values starting with #! are considered marked for encryption. Encryption can be performed explicitly by running the o b f u s c a t e tool in tibco_home\ t r a \ n.n\ b i n . The tool obfuscates all values starting with #!. For example, if a file contains this value:
repo.serverPassword=#!RepoTestServerPass

Running the obfuscate utility makes this change in the file:

repo.serverPassword=#!yecjXiS6JikkPrfNre8i/HqbO9a foyl6ACkGtzRPFFhaupSC1v0ApRLyyS+LOXtG

See the TIBCO Runtime Agent Installation guide for additional information. Examples
./instances/myInst.dat:userName=deborah c:/tibco/administrator/myinstances/myInst.dat:urlFile=c:/tibco/ administrator/props/deborah myProj.dat myProj myProj/myrepo.dat

TIBCO Administrator Server Configuration Guide

74

| Chapter 4

Advanced Topics

Using a Properties File to Encapsulate Locator String Components

Locator strings are included in an applications properties file in the t i b c o . c o n f i g u r l and t i b c o . r e p o u r l fields. If, however, you do not want to expose the complete locator string, for example, to protect your passwords, you can instead point to a u r l F i l e as part of the locator string:
t i b c r @ d e f a u l t : u s e r N a m e = myName: u r l F i l e = abc

Any : name=value u r l option to a utility tool can be used as a property name/value pair in the property file. The name/value pairs in the property file are appended to the url string. Note that this option is designed for command line utilities and is not available through deployment using the TIBCO Administrator GUI. Defining a URL Suppose you want to define the following url.
t i b c r @ d e f a u l t : u s e r N a m e = myName: p a s s w o r d = myPassword

You can define the url using the m y P r o p e r t i e s F i l e as follows.

t i b c r @ d e f a u l t : u s e r N a m e = myName: u r l F i l e = myPropertiesFile

Then provide the password in m y P r o p e r t i e s F i l e . Obfuscate the file using the o b f u s c a t e tool in tibco_home/ t r a / n.n/ b i n . Property Precedence If the same name/value pair appears in both url string and property file, the name/value pair in the url string takes precedence. You can overwrite the name/value pair in property file with the value directly given in url string. For example, if you have the following:
t i b c r @ d e f a u l t : u s e r N a m e = m y N a m e : u r l F i l e = myPropertiesFile

and p a s s w o r d = m y N a m e is defined in m y P r o p e r t i e s F i l e . The final url string is

t i b c r @ d e f a u l t : u s e r N a m e = m y N a m e : p a s s w o r d = myPassword

TIBCO Administrator Server Configuration Guide

Configuring Connection Pool Size for the Database Server 75

Configuring Connection Pool Size for the Database Server

When using a database-based domain, it is recommended that you fine tune the database servers JDBC connection pool to avoid running out of connections. The following components in a domain keep their own JDBC connection pool for database access: each primary administration server each secondary administration server each application domain on an administration server each Hawk agent
AppManage

utility

The maximum JDBC connections available to each component described above is defined by the t i b c o a d m i n . d a t a b a s e . m a x C o n n e c t i o n s property in the following two files for your domain: TIBCO_HOME/ d o m a i n / domain-name/ A d m i n i s t r a t i o n D o m a i n . p r o p e r t i e s TIBCO_HOME/ d o m a i n / domain-name/ A u t h e n t i c a t i o n D o m a i n . p r o p e r t i e s By default, both . p r o p e r t i e s files set the property to 10. This means each of the components described above uses a maximum of 20 connections (the sum of the administration domain and the authentication domain). You must multiple this number by the total number of components running in your domain.
tibcoadmin.database.maxConnections

Consider a scenario where a domain is configured with the following specifications: a primary administration server and a secondary administration server three client machines two application domains
AppManage

utiltiy used on one of the machines

Your database servers maximum connection pool size is calculated as follows:

2servers + 2appdomains 2servers + 5Hawk + 1AppManage 20connections server

= 240 totalConnections

TIBCO Administrator Server Configuration Guide

76

| Chapter 4

Advanced Topics

Enabling an SSL Connection to an LDAP Directory Server

SSL (Secure Sockets Layer) is a network protocol that allows authentication and encryption of data. SSL provides a secure connection between a client and a server. You can use SSL to secure the user and group data transmitted to your TIBCO servers and applications from the LDAP directory server. Doing so ensures privacy, integrity, and authenticity of data from the LDAP directory server. TIBCO Domain Utility specifies SSL usage for the LDAP integration of an administration domain. Once SSL is specified for a domains LDAP integration, the administration servers and applications depend on the security features of the JVM they run on to establish SSL connections with the LDAP server (do not actively participate in establishing the SSL connections). To configure an administration domain to connect to the LDAP directory server over SSL, do the following: 1. Enable SSL authentication on the LDAP directory server. You may need to contact the IT department in your organization that manages your LDAP servers. This requires installing a valid server certificate and CA trust certificate from a certificate authority on the LDAP directory server. 2. Import the CA trust certificate for your LDAP server certificate into the keystores of all JREs associated with the administration domain on each machine. This includes JREs for all primary and secondary servers, as well as for BusinessWorks processes that perform basic authentication. Note that the TIBCO JRE keystores already contains certificates from well-known certificate authorities such as Verisign, Thawte and Entrust, so you can skip this step if your LDAP server certificate is issued by one of these certificate authorities. 3. When integrating your administration domain with the LDAP directory server using TIBCO Domain Utility (see Changing a Domains Integration With an LDAP Directory Server in TIBCO Runtime Agent Domain Utility Users Guide), select SSL in the LDAP Authentication drop-down list. See Configuring LDAP Integration With SSL Connections in TIBCO Runtime Agent Domain Utility Users Guide for detailed instructions.

TIBCO Administrator Server Configuration Guide

Maintaining Connections to an LDAP Directory Server 77

Maintaining Connections to an LDAP Directory Server

TIBCO applications maintain a pool of connections to an LDAP directory server for authorization purposes. These connections are automatically reconnected when these are found to be broken. The connection pool properties are defined with default values when the installer sets up TIBCO Administrator. The values for some of the properties can be overridden in the t i b c o a d m i n _ domain-name. t r a file, which is written in the TIBCO_ADMIN_DOMAIN_HOME\ domain-name\ b i n folder after the domain is created. These properties apply to both LDAP directory server connections and database connections. The properties are listed next with their default values:
java.property.tibcoadmin.database.maxConnections=10 java.property.tibcoadmin.database.expiryInterval=1800000 java.property.tibcoadmin.database.waitTimeoutInterval=30000

The e x p i r y I n t e r v a l and w a i t T i m e o u t I n t e r v a l property values are specified in milliseconds. At runtime if a value is specified for one of the above properties in the t i b c o a d m i n _ domain. t r a file, it is used instead of the value set at install time. The connections are maintained for subscribing to group information changes. They are automatically reconnected when found to be broken. These connections must be kept alive when a TIBCO application is across a firewall, since a firewall can break these connections after certain period of inactivity. When these connections are reconnected, it is necessary to perform complete synchronization of group information again. Similarly when real-time subscriber connections used by the TIBCO Administrator service are reconnected, the group-synchronized roles must be synchronized again. See the TIBCO Administrator Users Guide for details.

TIBCO Administrator Server Configuration Guide

78

| Chapter 4

Advanced Topics

Internationalization
This section discusses internationalization. You learn about the following topics: Introduction Design-Time Encoding vs. Runtime Encoding Setting Encoding for an Administration Domain

Introduction
TIBCO products can store, process, display and transmit data in multiple character sets including Latin-1, Korean, Japanese, Chinese, and so on. To support this, encoding is set as follows: To communicate with vendor applications (such as SAP, Oracle, Siebel), TIBCO products use native encodings (like ISO-8859 series, Microsoft Windows series, Shift_JIS, Big5, GB2312, etc.). The encoding for communicating with the vendor application depends on the nature of the data exposed by the application and must be set during configuration of the TIBCO product. For internal representation of text data, TIBCO products use UCS-2. The TIBCO products take care of the encoding conversion between UCS-2 and any vendor applications native encoding, according to the encoding specified during configuration of the TIBCO product. For internal communication, TIBCO products use ISO8859-1 or UTF-8 as the wireformat encoding ISO8859-1 is the preferred encoding for exchanging ASCII or Latin-1 (ISO8859-1) data between TIBCO products or product components UTF-8 must be used for data in character sets other than ASCII and Latin-1. This wireformat encoding is called TIBCO Messaging Encoding and is determined by the encoding property of the administration domain in which the TIBCO application is running. Having one encoding per administration domain ensures that all TIBCO products in the administration domain use the same encoding to communicate.

Design-Time Encoding vs. Runtime Encoding

At design-time, you specify a TIBCO messaging encoding for a project. This encoding is used when the project is running in debug mode, or if you run it as a legacy project using a local repository (that is, exported as . d a t file).
TIBCO Administrator Server Configuration Guide

Internationalization 79

After the project has become a deployed application in TIBCO Administrator, the administration domain encoding supersedes the project-level encoding. This assures all TIBCO products working in the domain use the same wireformat encoding to communicate. When an enterprise archive file is loaded, the design-time encoding is verified to be compatible with the domain encoding.

Setting Encoding for an Administration Domain

The encoding for an administration domain is set during domain creation. You can create multiple administration domains on the same machine, each using a different encoding. Secondary servers automatically use the same encoding as the primary server.

For the encoding: ISO8859-1 should be used as the preferred encoding for projects in which the text data to be exchanged is only ASCII or Western European data. UTF-8 must be used for projects that handle data other than ASCII and Western European character set. Note that all the world's major language characters can be represented using UTF-8.

Default Encoding When you install an administration server and create an administration domain, the default encoding used for the domain is ISO8859-1 (Latin-1). The value is used for different properties of which three are in the t i b c o a d m i n _domain. t r a file:
t i b c o a d m i n . c l i e n t . e n c o d i n g encoding that is used to encode the HTML that displays the TIBCO Administrator GUI. f i l e . e n c o d i n g encoding

of the t i b c o a d m i n _ domain. t r a file contents.

r e p o . e n c o d i n g TIBCO Messaging encoding (discussed in the previous section). This encoding used by TIBCO Administrator and other TIBCO products in the domain to communicate. -character_encoding

used by the TIBCO Hawk agent. The property is defined in the h a w k a g e n t . c f g file.

Changing Encoding for a Domain In some situations, it may be necessary to choose UTF-8 as the encoding for all

TIBCO Administrator Server Configuration Guide

80

| Chapter 4

Advanced Topics

these properties. TIBCO Administrator stores encoding information per domain in two files. One is the domains . t r a configuration file used to launch TIBCO Administrator, and the other is the configuration file used by the TIBCO Hawk agent. For example, to change the encoding for a domain called m y D o m a i n : 1. Change directory to TIBCO_ADMIN_DOMAIN_HOME\ domain-name\ b i n . 2. Using a text editor, open the t i b c o a d m i n _ m y D o m a i n . t r a file. 3. Change the t i b c o a d m i n . c l i e n t . e n c o d i n g entry to UTF-8. 4. Change the r e p o . e n c o d i n g entry to UTF-8. 5. Save the file and restart the administration server. 6. Change directory to TIBCO_TRA_DOMAIN_HOME\ domain-name. 7. Using a text editor, open the h a w k a g e n t . c f g file. 8. Change the - c h a r a c t e r _ e n c o d i n g entry to UTF-8. 9. Save the file and restart the TIBCO Hawk agent The c l i e n t . e n c o d i n g value can be any valid encoding value. It is used to enforce the encoding of the contents pushed to the browser. The r e p o . e n c o d i n g value is used as TIBCO Rendezvous encoding and only UTF-8 and ISO8859-1 are supported. If this domain has a secondary server or if other machines join this domain, you must apply the same changes on each secondary server and machine. Changing Selected Properties In some situations, you may wish to change the value of one, but not all properties. For example, if you are going to use a e X m l as the message format, you must change r e p o . e n c o d i n g to UTF-8 even if you are actually using ASCII characters. If you are using a . t r a file that uses non-Latin1 characters, you must change f i l e . e n c o d i n g to UTF-8. You can edit individual properties in the t i b c o a d m i n _domain-name. t r a file. The applications configuration data in persistent storage is always UTF-8. This includes TIBCO Designer projects in different formats (including legacy server-based projects with a database backend) and TIBCO Administrator application repositories. The encoding for these files is independent of the TIBCO Messaging encoding chosen for the administration domain.

TIBCO Administrator Server Configuration Guide

Internationalization 81

The following table shows some example for which project content should be used with what TIBCO Messaging encoding. Project Content Latin-1, ASCII 7-Bit Latin 2 (Eastern European) Korean characters, Chinese characters, Japanese characters TIBCO Message Encoding ISO8859-1 (preferred) or UTF-8 UTF-8

Users and Passwords with Double-Byte Characters

You can create users and assign passwords with double-byte characters if you configure the administration domain to use UTF-8. If Local Application Data is used, run-time encoding can be set at deployment time. If TIBCO Enterprise Message Service is used for administration domain communication, design-time encoding is used by default at runtime.

TIBCO Administrator Server Configuration Guide

82

| Chapter 4

Advanced Topics

Configuring EHCache
TIBCO Administrator includes the EHCache product that provides a simple, fast and thread-safe cache facility. A default cache configuration is configured in the e h c a c h e - f a i l s a f e . x m l file, which is included in e h c a c h e - 1 . 1 . j a r. It is used unless you create and configure a custom cache file. The default configuration stores 5000 objects of each object type in memory without expiration. EHCache allows you to configure caching per object type. You can specify that only certain objects are cached after the first iteration. More information about configuring EHCache is available from the following location: http://ehcache.sourceforge.net/documentation/ To create and configure a custom cache file, you must: 1. Use winzip or another similar utility to unpack the EHCache jar file in:
TIBCO_HOME\ t p c l \ n.n\ l i b \ e h c a c h e - 1 . 1 . j a r

2. Copy the e h c a c h e - f a i l s a f e . x m l file to a working directory and use an XML editor to configure the file for your environment. To configure the default cache to use for all object types in the store, edit the d e f a u l t C a c h e configuration in the e h c a c h e - f a i l s a f e . x m l file. To configure a cache for a specific object type, create a cache configuration with the full Java class name of the object type in the e h c a c h e - f a i l s a f e . x m l file. In such a configuration, typically only the m a x E l e m e n t s I n M e m o r y value is changed. For example:
< cache name= " class name" m a x E l e m e n t s I n M e m o r y = " number" e t e r n a l = " t r u e " overflowToDisk="false"/>

3. After modifying the e h c a c h e - f a i l s a f e . x m l file, copy it to the TIBCO_TRA_DOMAIN_HOME/ domain-name directory (the same directory that contains the A d m i n i s t r a t i o n D o m a i n . p r o p e r t i e s file). Note that if a cache is not specified for an object type, the default cache's configuration is used to create a new cache for the object type. 4. Copy the file to domainName_ e h c a c h e . x m l and A U T H _ domainName_ e h c a c h e . x m l for each domain, or put the e h c a c h e - f a i l s a f e . x m l file back into the jar file for use with all domains.

TIBCO Administrator Server Configuration Guide

Configuring EHCache 83

Writing Cache Statistics to a Log File

Periodically, cache statistics can be dumped to a log file. This provides information needed to alter the cache configurations. Each store can configure how often it wants all of its cache statistics dumped to the INFO role of the Administrator.log file. The following properties can be added to and configured for each store (in A d m i n i s t r a t i o n D o m a i n . p r o p e r t i e s and A u t h o r i z a t i o n D o m a i n . p r o p e r t i e s ):
C a c h e D u m p I n t e r v a l : Set to the number of milliseconds to dump the cache statistics to the INFO role. If less then 0 or not set, the statistics are never dumped. By default, this property is not set. CacheDumpSizeEnabled:

Set to "true" if the amount of memory used by the cache should be dumped as well. This is a separate option because determining the size of the cache is an expensive operation around one second per MB of cache size. All use of the cache stops for this period and the application will seem to stop as well. If this property is not set, it defaults to "false".

If your dump interval is shorter than the length of time it takes to generate the cache size, the application will effectively freeze until this is not the case, which may require termination. The INFO log message has the following form for the default cache or a store wide cache:
[ name = acmedb:admin: com.tibco.pof.admindomain.AdministrationDomain status = active eternal = true overflowToDisk = false maxElementsInMemory = 10000 timeToLiveSeconds=120 timeToIdleSeconds = 120 diskPersistent = false diskExpiryThreadIntervalSeconds = 600 hitCount = 50 memoryStoreHitCount = 50 diskStoreHitCount = 0 missCountNotFound = 203 inMemorySize = 76454 ]

See the EHCache documentation for details on each of these attributes (http://ehcache.sourceforge.net/documentation/). The i n M e m o r y S i z e element is the number of bytes of the objects in the cache. This number is the size of the Java serialization of the objects and does not account for any transient variables (which should not significantly add to the size).
ClassLoaderHashCode

The name of the cache is a concatenation of the following. The element is a number (an internal identifier).

storeName:userName:ClassLoaderHashCode/entityTypeClassName

Similarly, the name of a cache that is specific to an object type is a concatenation of the following. The s t o r e I m p l e m e n t a t i o n C l a s s N a m e element can be removed if each application domain is uniquely named.

TIBCO Administrator Server Configuration Guide

84

| Chapter 4

Advanced Topics

storeName:userName:storeImplementationClassName/objectTypeClassName

TIBCO Administrator Server Configuration Guide

Authenticating Users 85

Authenticating Users
TIBCO Administrator implements the Java Authentication and Authorization Service (JAAS) framework. The framework allows you to perform web authentication and authorization in applications that use the administration server. You must create an administration domain that uses HTTPS. The JAAS Authentication web service is then deployed on the tomcat server for the administration domain.

Authentication Using the JAAS Authentication Web Service

The Internet provides many tutorials for using the JAAS framework. See http://java.sun.com/developer/JDCTechTips/2001/tt0727.html for a tutorial that shows the JAAS Authentication web service checking the identity of a caller. Other tutorials may be available on the Internet that show the same functionality. The above URL displays a tutorial that provides an introduction to JAAS and explains how to configure a JAAS LoginModule to validate passwords. The only difference between what is presented in the tutorial and how to use the Authentication web service is in the tutorials Configuration File section where the following lines
SimpleLogin { SimpleLoginModule required; };

instead would be:

SimpleLogin { com.tibco.atlas.auth.jaas.AuthenticationServiceLoginModule required a u t h o r i t y = putYourAdministratorHostNameHere: 8 4 4 3 soap_username="JAASTestUser" soap_password="#!vFxOuNrLV/B/ANGyYxL15ggTOvsg2AFQUx7oRlNi/KI="; };

The password is encrypted using t he o b f u s c a t e utility. See the TIBCO Runtime Agent Installation guide for details about using the utility.

TIBCO Administrator Server Configuration Guide

86

| Chapter 4

Advanced Topics

Authentication Code Example

This example provides example code that shows how to validate a password for a user. The administration domain must have SSL enabled for the example to work. The following arguments specify the username and password to test and are used to configure the connection to the service provider.
username

name of the user to validate. the obfuscated password of the user.

obfuscatedPassword superuserName

the name of a superuser defined in TIBCO Administrator. the obfuscated password of the

obfuscatedSuperuserPassword

superuser.
authority

the host:port specification of the server where TIBCO Administrator is running. The default is l o c a l h o s t : 8 4 4 3

A m a l f o r m e d U R L E x c e p t i o n is thrown if the service's URL is not formed correctly. This occurs if an unknown authority is set.
package sample.com.tibco.atlas.authentication; import java.net.MalformedURLException; import com.tibco.atlas.auth.authentication.AuthenticationService; import com.tibco.atlas.auth.authentication.AuthenticationServiceFactory; public class AuthenticateUser { public static void main(String[] args) throws MalformedURLException { String username = (args.length>0) ? args[0] : "user"; String obfuscatedPassword = (args.length>1) ? args[1] : ""; String superuserName = (args.length>2) ? args[2] : "superuserName"; String obfuscatedSuperuserPassword = (args.length>3) ? args[3] : ""; String authority = (args.length>4) ? args[4] : "localhost:8443"; try{ boolean retVal = isUserValid(username, obfuscatedPassword, superuserName, obfuscatedSuperuserPassword, authority); System.out.println("Password for user " + username + " is " + ((retVal) ? "valid" : "not valid")); } catch(Exception ex) { ex.printStackTrace() } } public static boolean isUserValid(String username, String obfuscatedPassword, String superUserName, String obfuscatedSuperuserPassword, String authority) throws Exception { AuthenticationServiceFactory factory = new AuthenticationServiceFactory();

TIBCO Administrator Server Configuration Guide

Authenticating Users 87

factory.setAuthority(authority); factory.setSoapUsername(superUserName); factory.setObfuscatedSoapPassword(obfuscatedSuperuserPassword); AuthenticationService service = factory.createAuthenticationService(); return service.isPasswordValid(username, obfuscatedPassword); } }

Logging Information to a File

By default, the Authentication web service prints all runtime trace information to the TIBCO Administrator console. This section explains how to configure the Authentication web service to print trace information to a file. The following system property needs to be set to the path of a logging configuration file. The property is then specified at startup in the client application command line.
- D j a v a . u t i l . l o g g i n g . c o n f i g . f i l e = path

to logging properties file

Your logging properties file should be similar to the following:

# Logging Properties File # "handlers" specifies a comma separated list of log Handler # classes. These handlers will be installed during VM startup. # Note that these classes must be on the system classpath. # To log to the console use java.util.logging.ConsoleHandler below: handlers= java.util.logging.FileHandler # # # # # # Default global logging level. This specifies which kinds of events are logged across all loggers. For any given facility this global level can be overriden by a facility specific level Note that the ConsoleHandler also has a separate level setting to limit messages printed to the console. package. l e v e l = F I N E S T # The default file output is in user's home directory. j a v a . u t i l . l o g g i n g . F i l e H a n d l e r . p a t t e r n = path to log file java.util.logging.FileHandler.limit = 50000 java.util.logging.FileHandler.count = 1 java.util.logging.FileHandler.level = INFO # XML can be output using java.util.logging.XMLFormatter: java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter

handlers

specifies the set of handlers to be loaded on startup.

TIBCO Administrator Server Configuration Guide

88

| Chapter 4

Advanced Topics

package. l e v e l sets the default global logging level for each package. The

values are ALL, OFF, FINEST, FINER, FINE, CONFIG, INFO, WARNING, SEVERE. The global logging level can be overridden for a specific handle.
pattern

provides the path to the log file for the given handle. If the path is not specified, the file is placed in the users home directory. is the maximum size of the output file in bytes.

limit

c o u n t is the number of output files to use. An integer is appended to the base file name. level

is the logging level. It uses the same values as the global logging describes the output style, simple or XML. The value can be or

level.
formatter java.util.logging.SimpleFormatter java.util.logging.XMLFormatter

TIBCO Administrator Server Configuration Guide

Repository Locking 89

Repository Locking
When an administration server accesses a repository for update, the repository is marked as locked so that other servers cannot update the same repository. For server-based repositories, the actual lock occurs the first time a client tries to connect to the administration server in read/write mode, not at server initialization. For a local file repository, the locking occurs if the repository is accessed, the username is non-empty and the access type is not read-only.

Once a repository is locked, it remains so until the server is cleanly shut down. For local file repositories, the lock is released when the client is destroyed. Files. In the case of a file-based repository (for both local and server-based repositories), a lock file is created which specifies the locking user name or server name and lock time. The file exists in the same directory as the project file, but has a . l c k extension. Database. In the case of a database backend, the Instance table has the l o c k e r column set to the server name for that particular instance.

How to Break the Lock

In some situations, a repository may remain locked although it is actually no longer in use. For server-based repository, you can break the lock by setting the r e p o . f o r c e I n s t a n c e L o c k s property in the t i b c o a d m i n _ domain-name. t r a file to t r u e and restarting the administration server. See also Administration Server Properties File on page 43 for additional details. For local file repositories, a lock file exists in the same directory as the project file and has a . l c k extension rather than a . d a t extension. You can force the removal of a lock on a repository by deleting its . l c k file.

TIBCO Administrator Server Configuration Guide

90

| Chapter 4

Advanced Topics

Remote Server Shutdown

You define two parameters when creating an administration domain: Shutdown Port and Shutdown String. You can use these two parameters to shut down the administration server remotely. Follow the instructions below to shutdown an administration server remotely: 1. In a command prompt, execute the following the command, where hostname is the name of the administration server host and port is the shutdown port:
telnet

hostname port

2. Type the shutdown string and type Enter. You may not observe anything on the command prompt except that the operation exits. However, you can verify on the administration server host that the administration server is indeed shut down. See TIBCO Runtime Agent Domain Utility Users Guide for information on configuring Shutdown Port and Shutdown String.

TIBCO Administrator Server Configuration Guide

Global Variables 91

Global Variables
You can define variables for your project, either during configuration or at deployment. Global variables are defined in TIBCO Designer during configuration. A TIBCO project contains a number of predefined global variables. For some of the variables, default values are assigned. You can use TIBCO Designer to specify additional variables and, optionally, define their values. At runtime, a client application can choose to overwrite the variable values or use the predefined value for the global variable. Examples for global variables include: Use a variable for your TIBCO Rendezvous service. Then supply the value 7001 during testing and 7002 for production runs. Allow your clients to set a TIBCO Rendezvous subject. For example, the same adapter can be run in different applications using two different subjects.

Global variables are stored as XML data, so only valid XML characters are allowed for variable values.

Defining Variables in TIBCO Designer

To define and use variables within TIBCO Designer: 1. In the TIBCO Designer project window, choose the Global Variables tab. 2. Click the Pen icon. 3. Click the abc icon and specify the variable name and (optionally) the value as a string. 4. To use a variable, copy and paste the variable into any location in your project where you need it. 5. When you save the project, the variables and their values are included. If your application doesnt override the variable value, it is used. The program code can, however, override it. You can also override it upon startup using a command-line argument.

Defining Service-Settable Variables in TIBCO Designer

If you wish to be able to change the value of a variable on a per-service basis, you can do so following these steps:
TIBCO Administrator Server Configuration Guide

92

| Chapter 4

Advanced Topics

1. In the TIBCO Designer project window, choose the Global Variables tab. 2. Click the pen icon to bring up the Global Variables Editor 3. Specify the variable, an optional value, and whether it should be settable on a per-deployment, per-service basis, or both. For more information about defining variables, see the TIBCO Designer Users Guide.

Setting Variable Values

You can preset variable values when you define the variables. You can then override any existing values as part of your application code or in the properties file for the application. For some applications, you can also override variables using the command-line. Variables set on the command line override variables set in the properties file and variables set in the properties file override variables set in the application. Change a variable value using the TIBCO Administrator GUI by selecting: An applications A d v a n c e d tab to set application-specific variables. A services A d v a n c e d tab to set service-specific variables. A service instances A d v a n c e d tab to set service instance-specific variables.

A variable value can be changed in a properties file or on the command line: Locally define the value for a variable in the properties file for a specific domain repository using the t i b c o . c l i e n t V a r . varname property. The local value takes precedence over any global value. Specify a value for a variable through a command-line argument. This overrides all other specification.
-system:clientVar

varName= value

Multiple - s y s t e m : c l i e n t V a r options can be specified on the command line. If the same variable already exists in the command line, the later one replaces the first one. No space is allowed for either v a r N a m e or the value, when using - s y s t e m : c l i e n t V a r. You can also set variable values using the A p p M a n a g e utility. This can be useful if only a few out of a large number of global variables change between domains.

TIBCO Administrator Server Configuration Guide

| 93
Chapter 5

Command Line Utilities

This chapter provides the command-line syntax and a brief discussion of each command line utility used for project management. The AppManage command line utility is used to deploy applications. The utility is described in the TIBCO Runtime Agent Scripting Deployment Users Guide.

Topics
Command List, page 94 CorpRoleSynchronizer, page 96 CorpUserSynchronizer, page 98 ExportDomainSecurity, page 99 ImportDomainSecurity, page 103 MoveMachine, page 105 RedeployAllAppsForUser, page 109 RepoConvert, page 112 RepoPing, page 116

TIBCO Administrator Server Configuration Guide

94

| Chapter 5

Command Line Utilities

Command List
The user account used to run most command line utilities must have W r i t e permissions set in the TIBCO Administrator GUI for the application, application repository, and domain repository that is being changed. Some command utilities require the user to be a member of the Super Users role. Many of the commands use a repository URL to point to a project. The URL syntax is discussed in Server-based Repository Locator String on page 66 and Local Repository Locator String on page 72 Table 8 Command List Command CorpRoleSynchronizer DeleteInvalidUsers Description Syncs an administration domain with its associated LDAP directory. Removes the users from an LDAP domain if the users do not exist in the associated LDAP directory. Pre loads user objects into an application. Exports security data from a domain. This includes users and roles. Imports security data into a domain. Moves a domain from one machine to another. Updates password changes to all deployed applications in a given domain. Converts back and forth between single-file (. d a t ) and multi-file projects. Checks whether an administration server is running and communicating. Creates a new project. Deletes nodes from a domain repository. Deletes a repository instance.

CorpUserSynchronizer ExportDomainSecurity ImportDomainSecurity MoveMachine RedeployAllAppsForUser RepoConvert RepoPing RepoCreateInstance RepoDelete RepoDeleteInstance

TIBCO Administrator Server Configuration Guide

Command List 95

Table 8 Command List Command RepoDiff RepoExport RepoImport RepoListInstances Description Logically compares two projects and outputs the differences. Exports all parts of a project to an XML file. Loads data from a file created with R e p o E x p o r t into a project. Lists currently available projects found at the location specified by a URL. The URL can either be local or remote. Renames a node in a local single-file or server-based project. Do not use this command if you have saved the project in multi-file format.

RepoRename

TIBCO Administrator Server Configuration Guide

96

| Chapter 5

Command Line Utilities

CorpRoleSynchronizer
Command
CorpRoleSynchronizer -domain

domain-name [ - h | - ? ]

The command must be started with an option or an exception will result. Purpose The C o r p R o l e S y n c h r o n i z e r command line utility syncs an administration domain with its associated LDAP directory. The sync occurs based on the search criteria for LDAP groups that was defined when the administration domain was created. Your administration domain may be out of sync because the auto sync settings for the domain were not been enabled when using TIBCO Domain Utility to configure the domain, or significant changes have been made to the LDAP directory since the last automatic sync and you do want to wait for the next auto sync cycle to occur, or do not want to do an manual sync from the TIBCO Administrator GUI. A summary of results is provided in the console where you launched the command and in the TIBCO Administrator log file.

TIBCO Administrator Server Configuration Guide

DeleteInvalidUsers 97

DeleteInvalidUsers
Command
DeleteInvalidUsers -domain <domain> [-h|-?]

This command only applies to domains which sync with an LDAP server. Purpose It Removes the users from an LDAP domain if the users do not exist in the associated LDAP directory. You need to specify the name of the LDAP domain when using this command. The domain name is case sensitive. Location
tibco_home\ t r a \ version\ b i n \

TIBCO Administrator Server Configuration Guide

98

| Chapter 5

Command Line Utilities

CorpUserSynchronizer
Command
CorpUserSynchronizer -domain

domain-name [ - c l e a n ] [ - h | - ? ]

The command must be started with an option or an exception will result. Purpose When an application is running, a new user profile is created when a user first accesses the application. At that time, the default objects for the users profile are created in the administration domains LDAP repository. Because of this activity, the administration server can become overloaded if many new users access the application in a short period of time. For example, this is especially applicable to TIBCO PortalBuilder applications directly after they go into production. In these situations, performance will be improved if you run the C o r p U s e r S y n c h r o n i z e r command. Pre loading users is generally done before an application goes live, but can be done at any time when a mass import of users would be useful. Property domain-name clean Description Name of an administration domain. Removes users in the administration domain who are no longer found in the LDAP directory.

If you have a large number of users to import, the import operation may fail after processing only part of the LDAP directorys contents. This happens because of low default values in certain iPlanet and Sun ONE Directory Server settings. It is assumed that your corporate LDAP (primary as well as any referral LDAPs) is appropriately configured so that LDAP search queries return all matching users in that LDAP. For iPlanet and Sun ONE Directory Servers, the t i m e l i m i t , s i z e l i m i t and l o o k - t h r o u g h l i m i t are appropriately set. For Microsoft Active Directory, the N T D S U T I L utility is used to configure the appropriate settings. See the Active Directory documentation for instructions.

A summary of results is provided in the console where you launched the utility and in the TIBCO Administrator log file.

TIBCO Administrator Server Configuration Guide

ExportDomainSecurity 99

ExportDomainSecurity
Command
E x p o r t D o m a i n S e c u r i t y - d o m a i n domain [ - a l l U s e r s | - m i n i m a l U s e r s ] [ - u s e r I n c r e m e n t number] [ - r o l e M e m b e r s h i p ] [ - r o l e s [ role1: role2: . . . : roleN] ] [ - s u p e r ] [ - a c l s ] [ - d a t e date] [ - G U I D ] [ - w r i t e D a t e s ] [ - e n c r y p t K e y key] ( ( - u s e r user - p w password) | - c r e d cred) - f i l e file

Purpose This command exports administration domain information to an XML file. The file can be loaded back into the domain or into another domain using the I m p o r t D o m a i n S e c u r i t y command. The E x p o r t D o m a i n S e c u r i t y and I m p o r t D o m a i n S e c u r i t y commands are designed for data loading (for example, batch loading users into a domain), synchronizing user and role data between domains, and backing up domain data. You can use E x p o r t D o m a i n S e c u r i t y to create example templates. Either - a l l U s e r s or - m i n i m a l U s e r s must be specified to export users. Use the - G U I D flag to keep two domains synchronized.

Data exported from an administration domain integrated with an LDAP directory server can only be imported into another LDAP based domain. Similarly, data exported from a non-LDAP domain can only be imported into a non-LDAP domain. Circular role hierarchies can be defined in an LDAP directory. For example, as shown next, R1 is a child of R2 which is a child of R3 which is a child of R1.

R3

R2

R1

Circular role hierarchies are not supported in TIBCO Administrator. If you import a role hierarchy that contains circular role hierarchies into another LDAP based domain, the LDAP synchronization will fail. To resolve this, you must remove the roles that are part of the circular hierarchy from the exported file and import the file into your target LDAP based domain. When TIBCO Administrator syncs with the LDAP directory server, the roles you removed will be restored.
TIBCO Administrator Server Configuration Guide

100

| Chapter 5

Command Line Utilities

Property domain domain -allUsers -minimalUsers -userIncrement

number

Description Name of a domain to export from (case sensitive). Exports all users. Exports minimal set of users only (only relevant if r o l e M e m b e r s h i p is specified). If specified, a new file will be created after this many users has been exported. The file will have a dash and an incrementing number appended to the value of -file. Exports the list of users belonging directly to the role for standard roles. List the roles to export, each separated by a colon. If specified without any values, all roles are exported. If not specified, no roles are exported. If specified, members or the super users role are exported. If specified, all access control lists are exported. Only entities updated since the given date are exported. The syntax for date must conform to that required of the Java method, D a t e . p a r s e ( ) . For example, " S a t 1 3 N o v 2004 13:30:00 GMT". Include GUIDs for improved merge on import. Note that if you do not specify this property, there is no way to determine whether a user or role has been renamed. Without this property, all user and role names are considered new names. Outputs last modification dates (automatic if GUID is specified). User passwords will be encrypted using the specified key (and a DES3 encryption algorithm). If a key is used to encrypt, that key must be supplied to ImportDomainSecurity when importing the file. If you lose the key, the password data is lost. Name of an authorized user.

-roleMembership roles role1:role2: ...: roleN -super -acls date date

-GUID

-writeDates -encryptKey key

user user

TIBCO Administrator Server Configuration Guide

ExportDomainSecurity 101

Property pw password -cred cred

Description Password of an authorized user. The password is case sensitive and should not be encrypted. Name and path to a property file that contains the user name and encrypted password. Use the o b f u s c a t e utility to encrypt the password. The utility is documented in the TIBCO Runtime Agent Installation guide. For example, the property file could contain this entry after running the utility:
user=admin pw=#!YZIAIiZ5DnkhFMqP+RUQkiSYHqP6jIGU

If this property is used, -user and -pw should not be specified. file file Examples The following command line exports only users who have been created or changed after the given date.
exportdomainsecurity -domain tp0513 -allUsers -date "Tue 09 Nov 2004 12:30:00 GMT" -user admin -pw admin -file \tibco\export.xml

Name of the file in which the data is stored.

Given the following users and roles:

R1 U1

R2 U1

U2

U3

U4

The following command exports only users U1 and U2, and roles, R1 and R2.
exportdomainsecurity -domain tp0513 -roles -minimalUsers -user admin -pw admin -file \tibco\export.xml

TIBCO Administrator Server Configuration Guide

102

| Chapter 5

Command Line Utilities

Given the following roles:

R1

R2

R3

Ra

Rb

Rc

The following command exports roles R1, R2, R3, Ra, and Rb. exportdomainsecurity -domain tp0513 -roles R1 Ra -user admin -pw admin -file \tibco\export.xml The following command exports roles R3, and Rb. exportdomainsecurity -domain tp0513 -roles R3 Rb -user admin -pw admin -file \tibco\export.xml The following command exports roles R2, R3 and Rc. exportdomainsecurity -domain tp0513 -roles R2 Rc -user admin -pw admin -file \tibco\export.xml Location
tibco_home\ t r a \ version\ b i n \

TIBCO Administrator Server Configuration Guide

ImportDomainSecurity 103

ImportDomainSecurity
Command
I m p o r t D o m a i n S e c u r i t y - d o m a i n domain [ - n o U s e r s | - n o R o l e s ] [ - n o A C L s ] [ - o v e r w r i t e ] [ - e n c r y p t K e y key] ( ( - u s e r u s e r - p w password) | - c r e d cred) - f i l e file

Purpose This command imports domain security information from an XML file. The file is created using the E x p o r t D o m a i n S e c u r i t y command. The E x p o r t D o m a i n S e c u r i t y and I m p o r t D o m a i n S e c u r i t y commands are designed for data loading (for example, batch loading users into a domain), synchronizing user and role data between domains, and backing up domain data. You can use this command to load user, role and access control information from another source. The XML file you create must conform to the D o m a i n S e c u r i t y . x s d file. The D o m a i n S e c u r i t y . x s d file is located in the TIBCO_TRA_HOME\ t e m p l a t e \ d o m a i n u t i l i t y \ c m d l i n e directory. Only valid XML characters can be used in user names, role names and properties. Data exported from a domain integrated with an LDAP directory server can only be imported into another LDAP based domain. Similarly, data exported from a non-LDAP domain can only be imported into a non-LDAP domain. After exporting LDAP group synchronized roles from an LDAP based domain and importing the roles into another LDAP based domain, all the exported roles will display in the imported LDAP based domain. The roles that are not part of the imported LDAP based domain will disappear when the administration server synchronizes with its LDAP directory. An export file that contains circular role hierarchies is not supported. See the ExportDomainSecurity command for more information. Property domain domain -noUsers -noRoles -noACLs Description Name of the domain to import (case sensitive). Do not import users. Do not import roles. Do not import ACLs except those protecting an imported role.

TIBCO Administrator Server Configuration Guide

104

| Chapter 5

Command Line Utilities

Property -overwrite

Description If specified, existing role values are replaced. If not specified, existing role values will be appended. If a role in the file has no membership, even if this property is specified, the role members will be left unchanged. This property removes any parents to a role not found in the import file and removes any members from standard roles not found in the imports membership list, unless the membership list is empty. This property has no effect on users, non-standard role membership configurations, or role properties.

-encryptKey key

Provide the key that was used to used to encrypt the user passwords stored in the file. If you lose the key, the password data is lost. Name of a user in the domain that has Super User permissions assigned. Password of the authorized user (case sensitive). The password can either encrypted or be in clear text. Name and path to a property file that contains the user name and encrypted password. Use the o b f u s c a t e utility to encrypt the password. The utility is documented in the TIBCO Runtime Agent Installation guide. For example, the property file could contain this entry after running the utility:
user=admin pw=#!YZIAIiZ5DnkhFMqP+RUQkiSYHqP6jIGU

user user pw password -cred cred

If this property is used, -user and -pw should not be specified. file file Example
importDomainSecurity -domain tp0513 -user admin -pw admin -file \tibco\export.xml

Name of the file in which the data is stored.

Location
TIBCO_TRA_DO_HOME\ b i n

TIBCO Administrator Server Configuration Guide

MoveMachine 105

MoveMachine
Command
M o v e M a c h i n e - d o m a i n domain-name [ - o l d M a c h i n e old machine name] [ - n e w M a c h i n e n e w machine name] [ - d o A d m i n U I ] [ - h e l p ]

Purpose This command moves a domain from one machine to another machine. For example, the next diagram shows two machines, A and B that used the same shared drive. The m o v e M a c h i n e command can move the domain from machine A to machine B. Note that machine B must not be part of the administration domain.
Machine A Machine B

Shared Drive

The command changes all references from the old machine to the new machine in the specified domain. Note that: In all cases, the TIBCO Hawk agent must be stopped on the old machine for the specified domain and started on the new machine. All service instances and process engines running on the old machine must be stopped before running the M o v e M a c h i n e command. If you moving a 5.1 domain and have not upgraded the domain to 5.2 or greater, and have registered an EMS server in the domain, you should use TIBCO Domain Utility on the new machine to update the EMS server after using the M o v e M a c h i n e command. All TIBCO software installed on the old machine must be installed on the new machine. Both machines must be running the same operating system.

The command does not update HTTP repository URIs for deployed components.

TIBCO Administrator Server Configuration Guide

106

| Chapter 5

Command Line Utilities

Property -domain domain-name -oldMachine old machine

name

Description Name of the administration domain to move. The existing machine name in the domain files that is to be replaced. The name is also used for validation. If not specified, all domain files are updated, but without validation. The new machine name to put in the domain files. If not provided, the hostname of the machine on which the command is run is used. The new machine must not already be part of the administration domain specified in -domain. Two machines that share the same drive on <tibco_home> cannot be in the same administration domain.

-newMachine new
machine name

-doAdminUI

If specified, updates the TIBCO Administrator web page that lists all available domains. This changes entries for all domains from the old machine to new machine. The property is applied only if the oldMachine property was specified.

-help

Prints this help information.

Moving an Administration Domain on a Server Machine To move an administration domain on a machine that hosts the administration server to another machine: 1. Ensure that all TIBCO software installed on the server machine is installed on the new machine. 2. Stop the TIBCO Hawk agent on the server machine. 3. Stop all service instances and process engines that are running in the administration domain on the server machine. 4. Either use a shared drive, or copy the administration domain from the server machine to the new machine. For example, if the files are under c : \ t i b c o on the server machine, you must copy the entire directory (c : \ t i b c o ) to the new machine. The directory path on the new machine must be identical to that on the server machine.

TIBCO Administrator Server Configuration Guide

MoveMachine 107

5. Execute the following command on the new machine. In the example command line, m a c h i n e A is the server machine that hosts the administration server and m a c h i n e B is the machine to which the administration domain is moved.
MoveMachine -domain tp034 -oldMachine machineA -newMachine machineB

6. Stop the administration server on the server machine. 7. Start the administration server on the new machine. 8. Start the TIBCO Hawk agent on the new machine. 9. Start the service instances and business processes on the new machine. Moving an Administration Domain on a Client Machine To move an administration domain on a client machine to another machine: 1. Ensure that all TIBCO software installed on the client machine is installed on the new machine. 2. Stop all service instances and process engines that are running on the client machine in the administration domain. 3. Stop the TIBCO Hawk agent on the old machine. 4. Either use a shared drive, or copy the administration domain from the client machine to the new machine. For example, if the files are under c : \ t i b c o on the client machine, you must copy the entire directory (c : \ t i b c o ) to the new machine. The directory path on the new machine must be identical to that on the client machine. 5. Execute the following command on the new machine. In the example command line, m a c h i n e C is the client machine that hosts the administration domain and m a c h i n e D is the machine to which the administration domain is moved.
MoveMachine -domain tp987 -oldMachine machineC -newMachine machineD

6. Start the TIBCO Hawk agent on the new machine. 7. Start the service instances and business processes on the new machine. Moving an Administration Domain on a Secondary Server Machine To move an administration domain on a machine that hosts a secondary server to another machine: 1. Ensure that all TIBCO software installed on the secondary server machine is installed on the new machine. 2. Stop the TIBCO Hawk agent and secondary server on the old machine.
TIBCO Administrator Server Configuration Guide

108

| Chapter 5

Command Line Utilities

3. Stop all service instances and process engines that are running in the administration domain. 4. Copy the administration domain from the secondary server machine to the new machine. For example, if the files are under c : \ t i b c o on the secondary server machine, you must copy the entire directory (c : \ t i b c o ) to the new machine. The directory path on the new machine must be identical to that on the secondary server machine. 5. Execute the following command on the new machine. In the example command line, m a c h i n e E is the secondary server machine that hosts the administration domain and m a c h i n e F is the machine to which the administration domain is moved.
MoveMachine -domain tp987 -oldMachine machineE -newMachine machineF

6. Start the TIBCO Hawk agent on the new machine. 7. Start the secondary server on the new machine. Renaming a Machine To rename a machine: 1. Stop all service instances and process engines that are running in the administration domains on the machine. 2. Stop the TIBCO Hawk agent on the machine. 3. Execute the following command on the new machine. In the example command line, m a c h i n e G is the old machine name and m a c h i n e H is the new machine name.
MoveMachine -domain tp987 -oldMachine machineG -newMachine machineH

4. Stop the administration server if one is running on the machine. 5. Change the machine name. 6. Start the TIBCO Hawk agent on the machine. 7. Start the administration server on the machine. 8. Start the service instances and business processes on the machine. Location
tibco_home\ t r a \ version\ b i n \

TIBCO Administrator Server Configuration Guide

RedeployAllAppsForUser 109

RedeployAllAppsForUser
Command
RedeployAllAppsForUser - d o m a i n domain [ - d e s c description] ( - u s e r user - p w password | - c r e d cred ( - t a r g e t U s e r targetUser - n e w P W new pass | - f i l e

file)

TIBCO Administrator Server Configuration Guide

110

| Chapter 5

Command Line Utilities

Purpose Changes the password in all deployed applications properties files (. t r a files) that are used to retrieve configuration data from the administration server. The command determines which applications in the given domain use the specified userid, and then updates their configurations and redeploys them. This is a convenience compared to doing these steps manually either in the TIBCO Administrator GUI or through command line deployment. Property domain user password cred Description Name of the administration domain. The name is case sensitive. Name of a user that is authorized to change the deployed application. Password for the above user. Name of a file containing the user and encrypted password. Use the obfuscate utility to encrypt the values in the file. Each entry in the file must use the following syntax:
user= password

Use either the -cred property, or the -user and -password properties, not both. targetUser new pass file Name of a user that is used by the deployed application to read its administration server based configuration data. Updated password for the targetUser. Absolute path to a file that contains a list of target users and passwords. Each entry in the file must use the following syntax:
targetUser= password

Use either the -file property, or the -targetUser and -new pass properties, not both.

TIBCO Administrator Server Configuration Guide

RedeployAllAppsForUser 111

If the -file property is specified or if the -user property value doesn't match the -targetUser property value, then the user running this command must be a super user in the domain. Be very careful that you have no undeployed changes to the relevant applications as these will be propagated to the deployed applications when this command is run.

TIBCO Administrator Server Configuration Guide

112

| Chapter 5

Command Line Utilities

RepoConvert
Command
RepoConvert - i n repoURL1 [ - o u t repoURL2] [ - r project root] [-n] [-y] [ - v log file] [-o] [ - t trace property file] [ - d directive file] [ pattern] [ pattern] . . .

Purpose Converts projects from single-file (. d a t ) to multi-file format or back. By default (no - n or - o option): If the target project does not exist, create a new one. If the target project already exists, the content of the target project is completely deleted first, then new data is written in the target project.

For TIBCO BusinessWorks 2.x projects, use b w 2 0 m i g r a t e rather than R e p o C o n v e r t or TIBCO Designer. The b w 2 0 m i g r a t e command is in the TIBCO BusinessWorks bin folder. Property -in repoURL1 Description Source project.

TIBCO Administrator Server Configuration Guide

RepoConvert 113

Property -out repoURL2

Description Target project. If the source project is in single-file (. d a t ) format, the target project must be a multi-file project If the source project is a multi-file project, the target project must be in single-file (. d a t ) format If the target project does not exist, a new project is created. If the input is a multi-file project, and the output project does not exist, the output project created in that case is in XML. If the source project is in . d a t format, and the target project does not exist, - r <project root> must be specified.

Either this property or - r (for multi-file format) must be specified.

repoURL2

cannot be the same as r e p o U R L 1 .

-o

If you specify this flag, R e p o C o n v e r t appends new information to the target project and overwrites existing nodes in the target project if target project exists. For . d a t to multi-file project migration, append/overwrite applies to files in the multi-file project. For multi-file to. d a t migration, append/overwrite applies to project nodes.

When both -n and -o options are specified, -o option takes precedence. R e p o C o n v e r t behavior in that case is the same as if -o only had been specified. -v log file Validates the multi-file format during multi-file to . d a t migration. If not specified, no validation is performed. If a log file is specified, validation errors and warnings are written to it. A property file specifying trace options. Defaults to
repoConvert.ini

-t trace property
file

-d directive file

An directive file with a list of patterns. One pattern per line. You can specify -d or <pattern> but not both.

TIBCO Administrator Server Configuration Guide

114

| Chapter 5

Command Line Utilities

Property pattern

Description Pattern to be matched, such as / t i b c o / p r i v a t e / a d a p t e r / * You can specify either -d or <pattern>, but not both.

-r project root

A file URI specifying the root directory of the multi-file project. If no target project is specified, and the source project is in . d a t format, the project is migrated to the specified root directory. Either this property or - o u t must be specified.

-n

If you specify this flag, R e p o C o n v e r t appends to the target project but does not overwrite information in the target project if the target project exists. For . d a t to multi-file project migration, new files are appended and existing files are not overridden in the multi-file project directory. For multi-file to . d a t migration, new nodes are appended and existing nodes files are not overwritten in the . d a t file.

When both -n and -o options are specified, the -o option takes precedence. R e p o C o n v e r t behavior in that case is the same as if -o only had been specified. -y Enable rename of 4.x project components (no rename is the default). In TIBCO Designer 4.x, moving resources had no effect on the project file. In TIBCO Designer 5.x, the file layout corresponds to the GUI layout. If you convert a 4.x project to TIBCO Designer 5.x multi-file format, and you wish to use TIBCO Designer 4.x mapping information to rename the files that are generated, you can use the -y option. Single-file (. d a t ) to Multi-file Project Examples Convert... Local file Using...
RepoConvert -in sdk_example.dat -out c:/repos/se/vcrepo.dat

TIBCO Administrator Server Configuration Guide

RepoConvert 115

Convert... Server-based project using TIBCO Rendezvous Server-based project using HTTP Local file to directory Only classes

Using...
RepoConvert -in tibcr://sdk_example -out c:/repos/se/vcrepo.dat

RepoConvert -in http:/host:8080?sdk_example -out c:/repos/se/vcrepo.dat

RepoConvert -in sdk_example.dat -r c:/repos/se

RepoConvert -in sdk_example.dat -out ./se/vcrepo.dat /tibco/public/class/*

Multi-file to Single-file (. d a t ) Project Examples Convert... Local file Remote RV Local file with validation Only AE schemas (no overwrite) Using...
RepoConvert -in c:/repos/se/vcrepo.dat -out sdk_example.dat RepoConvert -in c:/repos/se/vcrepo.dat -out tibcr://sdk_example RepoConvert -in c:/repos/se/vcrepo.dat -out sdk_example.dat -v convert.log RepoConvert -in c:/repos/se/vcrepo.dat -out sdk_example.dat -n /AESchemas/*

Location
tibco_home\ t r a \ version\ b i n \

TIBCO Administrator Server Configuration Guide

116

| Chapter 5

Command Line Utilities

RepoPing
Command
RepoPing -url

url [ - r e t r i e s retries sleep_interval]

Purpose Checks whether a project can be accessed. Property -url url Description Standard repository locator string for the project. The URL must be specified and must be the first property. Use R e p o P i n g format.
-help url

for information on the URL

The URL must be specified. -retries retries Number of times to try connecting to the project. If you dont specify this number, the default number of retries is 10. This property is optional.
sleep_interval

Number of milliseconds to sleep between retries. If you dont specify this number, the default value is 600. This property is optional.

Returns Return values are: 0 1 2 Successful connection Instance unavailable Exception raised while connecting to instance - indicates a problem with the environment or a bad URL string

Examples
RepoPing -url c:/temp/instance1 RepoPing -url tibcr://instance1:server=test -retries 5 100

Location
tibco_home\ t r a \ version\ b i n
TIBCO Administrator Server Configuration Guide

RepoCreateInstance 117

RepoCreateInstance
Command
RepoCreateInstance -url

url [ - c o n f i g F i l e configFile]

Purpose Create a new project (repository instance). This command is primarily used with 4.x instances. Parameter -url url Description Location of the project. Type R e p o C r e a t e I n s t a n c e - h e l p u r l for information on the url format. (- u r l must be specified). To create a project managed by a remote server, the server name must be provided by the s e r v e r parameter inside u r l . See Server-based Repository Locator String on page 66. Name of the instance property file. Its contents is used to initialize the InstanceInfo properties. If this argument is not given, R e p o C r e a t e I n s t a n c e uses default property files. The default property files are l o c a l I n s t a n c e I n f o . i n i and r e m o t e I n s t a n c e I n f o . i n i . If the URL specifies a remote instance, the default property file is r e m o t e I n s t a n c e I n f o . i n i . If the url specifies a local instance, the default property file is l o c a l I n s t a n c e I n f o . i n i . Examples The following command (entered on one line) creates a server-based project.
RepoCreateInstance -url tibcr://myIns:server=serv1:service=9000:username=sky:password=blue RepoCreateInstance -url localrepo@/temp/myInst.dat

-configFile
configFile

Location
tibco_home\ t r a \ version\ b i n \

TIBCO Administrator Server Configuration Guide

118

| Chapter 5

Command Line Utilities

RepoDelete
Command
RepoDelete -url

url R o o t N o d e R o o t N o d e . . .

Purpose Delete the node at the specified location in the project. This command is primarily used with 4.x instances.
R e p o D e l e t e can be combined with R e p o E x p o r t to completely maintain a project through scripts.

Notes If url points to a project saved in Multi-Project format, the following applies: If all nodes mapped to the file are deleted, then the file will be deleted. If multiple nodes (as in the case of an adapter) map to the particular file, and only some of them are deleted, the file will merely be updated. Description Deletes from the specified URL. Type R e p o D e l e t e u r l for information on the url format. url must be specified. RootNode Node to delete. If the specified node is a directory node, all child nodes of the directory node are also deleted. At least one node must be specified. Examples
RepoDelete -url test.dat /tibco/public/ae/class/class1 /tibco/public/ae/union/union1 RepoDelete -url tibcr://test:service=7500 /tibco/public/ae/class/class1 -help

Parameter -url url

Location
tibco_home\ t r a \ version\ b i n

TIBCO Administrator Server Configuration Guide

RepoDeleteInstance 119

RepoDeleteInstance
Command
RepoDeleteInstances -url

url [ - h e l p url]

Purpose Used to delete a repository instance from the specified URL. Type 'R e p o D e l e t e I n s t a n c e s - h e l p u r l ' for information on the url format. This command is primarily used with 4.x instances. Parameter -url url Description Deletes from the specified URL. Type R e p o D e l e t e I n s t a n c e - h e l p u r l for information on the url format. url must be specified. Examples
RepoDeleteInstance -url test.dat RepoDeleteInstance -url tibcr://test:service=7500

Location
tibco_home\ t r a \ version\ b i n

TIBCO Administrator Server Configuration Guide

120

| Chapter 5

Command Line Utilities

RepoDiff
Command
repoDiff [-help | -?] [-i] [-s

url] [ - x url] [ v ] repoUrl1 repoUrl2

Purpose Logically compares two projects and outputs the differences. This command is primarily used with 4.x instances. The output report contains the following information: Differences in global variables and in instance variables. Differences in project tree content. Summary of all differences. Description When you use this option, a help message is displayed. Type R e p o D i f f - h e l p u r l for information on the url format. Compare the two projects ignoring case. Start node for comparison. Only nodes descending from url are included in the comparison. When an exclude url is specified, RepoDiff excludes the subtree that starts at this url. Verbose reporting. When specified, the complete content change is reported; otherwise, only the existence of a change is supported. URL for the two instances to compare.

Parameter -help -? -i -s url -x url -v

repoURL1 repoURL2

Examples
RepoDiff .\instance1.dat .\instance2.dat

RepoDiff -i tibcr://instance1 tibcr://instance2 RepoDiff -x /tibco/public http://localhost:8080?instance1 http://localhost:8080?instance2

Location
tibco_home\ t r a \ version\ b i n
TIBCO Administrator Server Configuration Guide

RepoExport 121

RepoExport
Command
RepoExport -url

url [ o p t i o n s ] f i l e [ R o o t N o d e ] [ R o o t N o d e ]

Purpose Use this command to export data from a project to an XML file. This command is primarily used with 4.x instances. Parameter -url url Description Exports from the specified URL. Type R e p o E x p o r t - h e l p u r l for information on the url format. A valid u r l must be specified. You can supply one or more options. See Options below. The file that will be written. The nodes from which to start exporting. If not specified, exports the entire project. Multiple root nodes are supported.

options file RootNode (Optional)

Option -bypassInvalidRoot -format format

Description Export process skips invalid roots, prints a warning, and continues exporting from other valid roots. Output file format. Valid file formats are g e n e r i c and A E X M L . If not specified, the default is g e n e r i c . If you use generic format, XSD validation cannot be performed when you re-import the file. Contents of referenced nodes are not exported. By default referenced nodes are exported as if they had been specified as root nodes. Do not export anything at or below the specified directory or object. Use multiple -exclude arguments to exclude multiple directories/objects.

-nochase

-exclude <obj>

TIBCO Administrator Server Configuration Guide

122

| Chapter 5

Command Line Utilities

Option -substitute [name=value...]

Description Substitute global variables in exported strings. If this option is not specified, the strings are exported in their raw format. There can be an arbitrary number of name=value pairs which override any matching global variables. Global names are not shortened in AEXML format. By default, they are shortened.

-fullname

Examples
RepoExport -url /repos/MyLocalRepo.dat -format AEXML MyRepo.exp RepoExport -url tibcr://MyRemoteRepo -format AEXML EntireRepo.exp RepoExport -url tibcr://MyRemoteRepo -exclude /tibco/public/class -exclude /tibco/public/sequence -format AEXML JustPrivate.exp /tibco/private

See Also Appendix C, Schema Files used when Exporting and Importing Location
tibco_home\ t r a \ version\ b i n

TIBCO Administrator Server Configuration Guide

RepoImport 123

RepoImport
Command
RepoImport -url

url [ o p t i o n s ] import file [ s c h e m a f i l e s ]

Purpose Import the specified file into a project using the specified options. This command is primarily used with 4.x instances. For more information see Appendix C, Schema Files used when Exporting and Importing. Parameter -url url Description Import from the specified URL. Type R e p o I m p o r t format.
-help url

for information on the url

-url must be specified. options

import file

You can set one or more options. See Options for AEXML or Generic format below. It is the instance file. The instance file may have any extension except . x s d . It must be in one of the formats used by R e p o E x p o r t . You can use one or more XML schema files. The schema file must have extension . x s d . This argument does not apply to instance files in generic format.

schema files

Options for AEXML or Generic format Option -overwrite Description If this option is used, imported objects replace existing objects if same name object exists. Otherwise, existing objects are left unchanged. Objects with names that dont currently exist are imported.

TIBCO Administrator Server Configuration Guide

124

| Chapter 5

Command Line Utilities

Option -overwriteVar

Description Imported objects replace existing global variable if variables of the same name exist. Otherwise, existing global variables are left unchanged. Objects with names that do not currently exist are imported.

-nullRef

If this option is t r u e , references that point to non-existing nodes are changed to null references. Otherwise, an empty object is created. Do not overwrite the contents of the given directory or object. Use multiple - e x c l u d e arguments to specify multiple objects and directories. New objects are still added to this directory.

-exclude object

Options for AEXML only Option -caseSensitive Description Case-sensitive XML validation in enumeration facet matching. This option does not apply if the instance file is in generic format. Continue the import after encountering a validation error in the instance file. By default, R e p o I m p o r t terminates if a validation error is encountered. The error/warning level generated by validator. 1 means error and warning, 2 means error only, 3 means warning only.

-continue

-lev 1|2|3

Default is 1. -novalidate -log file Do not validate instance files in AEXML format. Log validation error in the specified log file. If no log file is specified, validation errors can be found in d e f a u l t . l o g in the current directory.

TIBCO Administrator Server Configuration Guide

RepoImport 125

Examples
RepoImport -url /repos/MyLocalRepo.dat -continue MyLocalFile.exp Repository.xsd myAdapter.xsd AESDK.xsd AEService.xsd AESchema.xsd RepoImport -url tibcr://MyRemoteRepo -novalidate MyLocalFile.exp Repository.xsd RepoImport -url tibcr://MyRemoteRepo -exclude /tibco/public/class -exclude /tibco/public/sequence -continue JustPrivate.exp Repository.xsd

Location
tibco_home\ t r a \ version\ b i n

TIBCO Administrator Server Configuration Guide

126

| Chapter 5

Command Line Utilities

RepoListInstances
Command
RepoListInstances -url url

Purpose Use R e p o L i s t I n s t a n c e s to list instances at the location specified by a URL. The URL can either be local or remote. This command is primarily used with 4.x instances. If local, the directory should be specified rather than a specific instance. If remote, the server may be specified to get instances from a particular server, otherwise all instances will be lists.

The list goes to standard output and contains each instance name on a separate line. Parameter -url url Description URL specifying the project for which you want to list the instances. Type R e p o D e l e t e - h e l p u r l for information on the url format. The URL must be specified. Examples
RepoListInstances -url c:/temp RepoListInstances -url tibcr://:server=TEST RepoListInstances -url tibcr://

Location
tibco_home\ t r a \ version\ b i n

TIBCO Administrator Server Configuration Guide

RepoRename 127

RepoRename
Command
RepoRename -url

url [ - t y p e type] [ - i g n o r e E r r ] - f i l e file | oldName

newName

Purpose Renames a node in a project. This command is primarily used with 4.x instances. Do not rename the S Y S _ domain-name and A U T H _ domain-name repository instances that store domain information. If you do, the administration server can no longer operate properly. Parameter -url url -type type Description Renaming starts at this URL. The URL must be specified. Type R e p o R e n a m e - h e l p u r l for information on the url format. Specifies the type of node to rename. This provides a prefix for convenience. If you do not specify the type, you must fully qualify the node names. Even if you specify the type, you may use an absolute path for one or both names. See Types below for a list of legal types Names beginning with a slash are absolute paths and will not have the type prefix applied. This parameter is optional. -ignoreErr If this option is specified, errors are ignored and processing continues if multiple items were specified for rename. If this option is not specified, processing stops when the first error is encountered. This parameter is optional. -file file Specify a file with a list of name pairs for rename. There can be multiple nodes to rename, but only one per line. Format of the file is a set of lines each consisting of oldname = newname Either -file or <oldname newname> must be specified, but not both
oldname newname

Node name for the node existing in the project that is to be renamed, followed by the target name. Either -file or oldname newname must be specified, but not both

TIBCO Administrator Server Configuration Guide

128

| Chapter 5

Command Line Utilities

Types The following types can be used in conjunction with the - t y p e option. gn association class aeclass scalar aescalar sequence aesequence union channel endpoint session adapter mb Examples
RepoRename -url tibcr@inst1 -type aeclass foo bar RepoRename -url tibcr@inst1 -type scalar ae/i4 ae/integer RepoRename -url tibcr@inst1 -type scalar ae/i4 com/i4 RepoRename -url tibcr@inst1 -type scalar ae/myI4 /tibco/private/adapter/myAdapter/myScalars/I4 RepoRename -url tibcr@inst1 /tibco/private/foo/T1 /tibco/private/ba/typeT1 RepoRename -url c:/tibco/repos/foo.dat -file c:/temp/renList.txt RepoRename -url c:/tibco/repos/foo.dat -ignoreErr -file c:/temp/ren.txt

fully qualified global name /tibco/public/association/ae /tibco/public/class /tibco/public/class/ae /tibco/public/scalar /tibco/public/scalar/ae /tibco/public/sequence /tibco/public/sequence/ae /tibco/public/union/ae /tibco/public/channel /tibco/public/endpoint /tibco/public/session /tibco/private/adapter /tibco/private/mb

Location
tibco_home\ t r a \ version\ b i n

TIBCO Administrator Server Configuration Guide

| 129
Appendix A

Log Files Generated for an Administration Domain

This appendix briefly discusses the different log files created for an administration domain and the trace message format.

Topics
Introduction, page 130 Installer Logs, page 131 Tomcat Logs, page 132 Administration Server Log, page 133 TIBCO Hawk Agent Logs, page 134 Application Logs, page 135 Audit Logs, page 136 TIBCO Domain Utility Log, page 137 Repository Logs, page 138 Standard TIBCO Trace Message Format, page 139

TIBCO Administrator Server Configuration Guide

130

| Appendix A

Log Files Generated for an Administration Domain

Introduction
This appendix briefly lists the different log files generated inside an administration server. If you are facing an issue you need to resolve, you may need to look at one or two of the logs before you can determine what the problem is. In many cases, it is also recommended that you try starting the server from the command prompt to see the resulting errors. Appendix D, System Messages lists system messages that TIBCO Administrator may display in addition to information in the logs.

TIBCO Administrator Server Configuration Guide

Installer Logs 131

Installer Logs
For each TIBCO product you install, the installer creates a log file in the TIBCO_HOME\ l o g folder. The log includes information about all actions the installer performs.

TIBCO Administrator Server Configuration Guide

132

| Appendix A

Log Files Generated for an Administration Domain

Tomcat Logs
Tomcat is used by TIBCO Administrator, and keeps a separate set of logs in the TIBCO_ADMIN_HOME\ t o m c a t \ l o g s \ domain-name folder. A new set of files is created each day you use the software. Because of the way that TIBCO Administrator forces Tomcat to pre-compile JSPs, a number of error messages are stored in the Tomcat log file. These messages do not indicate a problem (though they are confusing). This log is generated by Tomcat and can help troubleshoot Tomcat issues.

TIBCO Administrator Server Configuration Guide

Administration Server Log 133

Administration Server Log

Most administration server traces are stored in the file
TIBCO_TRA_DOMAIN_HOME\ domain-name\ l o g s \ A d m i n i s t r a t o r . l o g . The file uses standard TIBCO trace message format. See Standard TIBCO Trace Message Format on page 139 for details.

If the file exceeds 500 KB, a new file is generated while the old file is maintained with a suffix. Five files are generated before the oldest file is overwritten. If that is too much space for your system or you want to maintain more log information, edit the values in the A d m i n i s t r a t i o n D o m a i n . P r o p e r t i e s file. The file is located in TIBCO_TRA_DOMAIN_HOME\ domain-name.
LogGenerations= //number of files LogGenerationsSize= //in kilobytes

TIBCO Administrator Server Configuration Guide

134

| Appendix A

Log Files Generated for an Administration Domain

TIBCO Hawk Agent Logs

Two different TIBCO Hawk agent logs are included in
TIBCO_TRA_DOMAIN_HOME\ domain-name\ l o g s :

tsm.log

includes the high-level Hawk Agent messages. includes the lower-level Hawk Agent messages.

HawkAgent.log

The TIBCO Hawk product creates a number of log files in TIBCO_TRA_DOMAIN_HOME\ l o g s \ h m a _ port.

TIBCO Administrator Server Configuration Guide

Application Logs 135

Application Logs
Application logs are stored under the domain in which the application is running. For example, if you created and deployed a TIBCO BusinessWorks application, the log for that application is stored in:
install_path\ t i b c o \ t r a \ d o m a i n \ domain-name\ a p p l i c a t i o n \ l o g s

The information in these logs depend on the monitoring setup for that application. The setup is performed in the TIBCO Administrator GUI, and the information in the application logs is available in Administrator. See TIBCO Administrator Users Guide.

TIBCO Administrator Server Configuration Guide

136

| Appendix A

Log Files Generated for an Administration Domain

Audit Logs
Audit logs track security events. Any TIBCO application that accesses the security module in a domain writes information to the audit log. The log is stored on the machine that hosts the administration server in TIBCO_ADMIN_DOMAIN_HOME\ domain-name\ l o g s .

TIBCO Administrator Server Configuration Guide

TIBCO Domain Utility Log 137

TIBCO Domain Utility Log

TIBCO Domain Utility creates a log in a file named d o m a i n u t i l i t y . l o g in the TIBCO_TRA_HOME\ l o g s folder. The log contains information about user selections in TIBCO Domain Utility.

TIBCO Administrator Server Configuration Guide

138

| Appendix A

Log Files Generated for an Administration Domain

Repository Logs
By default, no repository logs are written. You can change this behavior by setting the appropriate properties in the t i b c o a d m i n _ domain-name. t r a file. See Logging Properties on page 53 for more information.

TIBCO Administrator Server Configuration Guide

Standard TIBCO Trace Message Format 139

Standard TIBCO Trace Message Format

The implementation of the administration server tracing facility conforms to the tracing specification of TIBCO ActiveEnterprise. The ActiveEnterprise tracing specification provides a common framework for error messages and their handling across all TIBCO product lines (ActiveEnterprise, ActiveExchange, ActivePortal). Each trace message includes the following information: Field Name Timestamp ApplicationID Role Category Description Timestamp of occurrence. Name of the server Role of the trace message, which is one of
E R R O R , W A R N , I N F O , and V E R B O S E (D E B U G ) roles.

Example See the example in Installer Logs on page 131. Repository.server name
Error

Category of the message. One of the following:

Configuration CreateInstanceTool Database HawkImplant Security Server Servlet System TibRvComm

Configuration

MessageCode

Unique code for the message. The code consists of one alphanumeric key followed by a dash "-" and a six-digit numeric code.

AEREPO-100015

Message

Text message.

"Could not read server process property file abc"

TIBCO Administrator Server Configuration Guide

140

| Appendix A

Log Files Generated for an Administration Domain

TIBCO Administrator Server Configuration Guide

| 141
Appendix B

Using TIBCO Hawk Methods

TIBCO Hawk monitors and manages distributed applications and systems. A TIBCO Hawk microagent contains methods you can use to change and display application properties at run-time. The TIBCO Administrator microagent provides a number of methods that allow you to monitor and administer and control an administration server and its clients. Much of the information available via these methods is available from the TIBCO Administrator GUI. However, if you have purchased the TIBCO Hawk product, you can use these microagents for more sophisticated automatic monitoring management.

Topics
Introduction, page 142 Starting TIBCO Hawk Software, page 143 The Auto-Discovery Process, page 144 Invoking Microagent Methods, page 145 Available Microagent Methods, page 147

TIBCO Administrator Server Configuration Guide

142

| Appendix B

Using TIBCO Hawk Methods

Introduction
In a TIBCO Hawk environment, agents on each local computer perform the monitoring work. A TIBCO Hawk agent is an autonomous process that uses microagents to monitor local applications and systems activity. Microagents represent managed objects such as operating system subsystems, agent components, log files, event logs, and applications. Each microagent exposes a set of methods to the agent for collecting information and taking actions. This design allows for separation between management data and management rules or policies. TIBCO Hawk Display is an application for viewing and managing TIBCO Hawk objects on your network. The Display application is not a centralized console, but a local window into network activity. In TIBCO Hawk Display, an administrator can discover TIBCO Hawk agents that are running, and communicate with microagents on each agent machine. Using application menus and dialogs, administrators can also build and distribute rulebases, which control the monitoring behavior of TIBCO Hawk agents. For detailed information about TIBCO Hawk product components, see the TIBCO Hawk Administrators Guide.

TIBCO Administrator Server Configuration Guide

Starting TIBCO Hawk Software 143

Starting TIBCO Hawk Software

When running in a domain, the domain configuration for a machine will include a configured TIBCO Hawk agent. The following sections describe how to start TIBCO Hawk product components on Microsoft Windows NT and UNIX platforms on a non-domain machine.

Starting TIBCO Hawk Software on Unix

To start TIBCO Hawk product components on Unix: 1. In a command window, start the TIBCO Hawk agent by typing:
startagent

2. In a new command window, set the DISPLAY environment variable for your workstation by typing:
setenv DISPLAY

hostname: 0 . 0

3. Start TIBCO Hawk Display by typing:

startdisplay &

After TIBCO Hawk Display is started, the operation is the same on the Unix and Windows platforms.

Starting TIBCO Hawk Software on Microsoft Windows

Once installed, the TIBCO Hawk agent runs as a Windows service. The service is configured to start automatically. You must start the TIBCO Hawk Display application on your workstation to access the user interface. To start an instance of TIBCO Hawk Display on Microsoft Windows: Select TIBCO Hawk Software>Hawk Display from the Start menu, or double-click Hawk Display in the TIBCO Hawk program group.

TIBCO Administrator Server Configuration Guide

144

| Appendix B

Using TIBCO Hawk Methods

The Auto-Discovery Process

After you start an instance of TIBCO Hawk Display, it continually discovers machines running TIBCO Hawk agents on your network. Container icons are created for each agent, and arranged hierarchically. By default, agent icons are clustered according to subnets. At first, the Agents container is empty. Its counter displays a value of zero. On the right, the Discovered counter is also at zero. Both icons are initially green to show that no alerts or warning messages are in effect. As agents are discovered, the counters increment to reflect the current number of discovered agents:

Monitored network nodes are arranged in a hierarchical tree of containers. Clicking a container in the left panel displays nested items on the right. Icon colors change to reflect the highest level of alert found on discovered agents. For explanations of icon elements and characteristics, see the TIBCO Hawk Administrators Guide.

TIBCO Administrator Server Configuration Guide

Invoking Microagent Methods 145

Invoking Microagent Methods

A set of default microagents is loaded when a TIBCO Hawk agent is started. If requested during installation, TIBCO Repository microagents are dynamically added to the local agent. The following steps describe how to invoke a microagent method by specifying a microagent, method name, and optional method arguments. To invoke a microagent method on a TIBCO Hawk agent: 1. In TIBCO Hawk Display, right-click the agent icon and select Get Microagents. If TIBCO Hawk security is implemented on your system and you do not have access to microagents on this agent, an error dialog displays. Select another agent, or contact your system administrator to obtain access. 2. The Microagents, Methods and Arguments dialog displays. The panel on the upper left lists microagents you can access on the current agent.

This dialog has two modes, Invoke and Subscribe. Invoking a method immediately returns a single set of current results. Subscribing provides updates of current results at regular intervals. Radio buttons at the bottom of the dialog control these modes.

TIBCO Administrator Server Configuration Guide

146

| Appendix B

Using TIBCO Hawk Methods

3. Click the microagent name, such as TIBCO RepositoryServer microagent to display a list of associated methods and text descriptions in the panels below. 4. Click the name of the method to invoke, such as getComponentInfo.

If the method accepts arguments, fields for each argument display in the upper right panel. Detailed help text displays in the lower panel. 5. Specify any arguments for the method invocation. 6. Verify that the Invoke radio button is selected. 7. Click the Invoke button to invoke the selected method. The Invocation Results dialog displays the results returned by the method. 8. Click Done to close the dialog. These steps describe how to interactively invoke a microagent method and receive a single set of results in TIBCO Hawk Display. You can also use a microagent method as the data source of a TIBCO Hawk rule. Rules automatically receive method results, apply tests to evaluate them, then take action if necessary. For more information on building TIBCO Hawk rules and rulebases, see the TIBCO Hawk Administrators Guide.

TIBCO Administrator Server Configuration Guide

Available Microagent Methods 147

Available Microagent Methods

One microagent, named C O M . T I B C O . R E P O S I T O R Y . S E R V E R includes all methods for monitoring TIBCO Repository. The following table lists, in alphabetical order, each method available for the repository microagent and the page on which the method is explained. Method
doRefreshCache() doRefreshSecurity()

Description Refreshes the servers cache. Refreshes the security objects of the server. Shuts down the server process. Starts the specified instance. Stops the specified instance. Disconnects the specified client from the repository instance. Returns information about the server process. This method returns properties used for initializing the server. Returns the names of all clients connected to a specified instance. Returns properties of a specified instance. Returns information about the current state of the specified instance. Returns the names of all locked nodes. Returns information about the log configuration of this server.

Page 180 181 171 179 178 182 160 157 177 172 174 176 164

doShutdownServer() doStartInstance() doStopInstance() doTerminateClient()

getConfig()

getConfigProperties()

getConnectedClients()

getInstanceInfos()

getInstanceStatus()

getListOfLockedNodes( ) getLogConfig()

TIBCO Administrator Server Configuration Guide

148

| Appendix B

Using TIBCO Hawk Methods

Method (Contd)
getQueueStats()

Description (Contd) Returns information about the TIBCO Rendezvous queues of the server. Return information related to the TIBCO Rendezvous session the server uses. Returns the current size of an instance. Returns information about the current status of the server process. Returns the currently enabled trace IDs of the server. Notify local TIBCO Hawk agents when content is changed in any of the instances. Notify local TIBCO Hawk agents when a copy of a repository instance is made. Notify local TIBCO Hawk agents that a repository instance has been created. Notify local TIBCO Hawk agents that a repository instance has been deleted. Notify local TIBCO Hawk agents that a repository instance has been changed. Notify local TIBCO Hawk agents that a repository instance has been modified. Notify local TIBCO Hawk agents that a server is being shut down. Notify local TIBCO Hawk agents that a repository instance is started. Notify local TIBCO Hawk agents that a repository instance has been stopped. Controls logging properties. Sets current trace IDs.

Page 163 159 175 161 164 166

getRvConfig()

getSizeOfInstance() getStatus()

getTraceIds()

onContentChange()

onCopyInstance()

149 150 151 157 152 153 154 155 168 170

onCreateInstance()

onDeleteInstance()

onInstanceChange()

onModifyInstance()

onServerShutdown()

onStartInstance()

onStopInstance()

setLogConfig() setTraceIds()

TIBCO Administrator Server Configuration Guide

onCopyInstance() 149

onCopyInstance()
Purpose

Notify local TIBCO Hawk agents that a copy of a repository instance was made. The return value includes the names of the source and destination instance.

Type Parameters Returns

Open, Asynchronous, IMPACT_INFO None Name Source instance name Destination instance name Description Name of the instance that is used as the source. Name of the instance that is used as the destination.

TIBCO Administrator Server Configuration Guide

150

| Appendix B

Using TIBCO Hawk Methods

onCreateInstance()
Purpose

Notify local TIBCO Hawk agents when a repository instance is created. The return value is the name of the instance.

Type Parameters Returns

Open, Asynchronous, IMPACT_INFO None Name Instance name Description Name of the instance that is created.

TIBCO Administrator Server Configuration Guide

onDeleteInstance() 151

onDeleteInstance()
Purpose

Notify local TIBCO Hawk agents when a repository instance is deleted. The name of the instance is returned.

Type Parameters Returns

Open, Asynchronous, IMPACT_INFO None Name Instance name Description Name of the instance that is deleted.

TIBCO Administrator Server Configuration Guide

152

| Appendix B

Using TIBCO Hawk Methods

onModifyInstance()
Purpose

Notify local TIBCO Hawk agents that a repository instance has been modified. The name of the instance is returned. You modify instances in TIBCO Designer, which allows you to change instance properties such as the display name and description. To get notification when the content of the instance changes use onContentChange() on page 167.

Type Parameters Returns

Open, Asynchronous, IMPACT_INFO None Name Instance name Description Name of the instance that is modified.

TIBCO Administrator Server Configuration Guide

onServerShutdown() 153

onServerShutdown()
Purpose

Notify local TIBCO Hawk agents that a server is being shut down. The name of the server is returned.

Type Parameters Returns

Open, Asynchronous, IMPACT_INFO None Name Server name Description Name of the server that is being shut down.

TIBCO Administrator Server Configuration Guide

154

| Appendix B

Using TIBCO Hawk Methods

onStartInstance()
Purpose

Notify local TIBCO Hawk agents when a repository instance has started. The name of the instance is returned.

Type Parameters Returns

Open, Asynchronous, IMPACT_INFO None Name Instance name Description Name of the instance that has started.

TIBCO Administrator Server Configuration Guide

onStopInstance() 155

onStopInstance()
Purpose

Notify local TIBCO Hawk agents when a repository instance has stopped. You can stop instances using the TIBCO Hawk method doStopInstance(), page 178 or using TIBCO Designer. The name of the instance is returned.

Type Parameters Returns

Open, Asynchronous, IMPACT_INFO None Name Instance name Description Name of the instance that has stopped.

TIBCO Administrator Server Configuration Guide

156

| Appendix B

Using TIBCO Hawk Methods

onInstanceChange()
Purpose

Notify local TIBCO Hawk agents that a repository instance has changed. Changing an instance means copying, modifying, creating, or deleting an instance. It does not mean changing the contents of an instance. The return value includes the kind of operation performed and the name of the instance or instances.

Type Parameters Returns

Open, Asynchronous, IMPACT_INFO None Name Operation Description Name of the instance operation performed. Value is one of c o p y, m o d i f y, c r e a t e , or d e l e t e . Instance name Destination instance name Name of the instance that has been copied, modified, created, or deleted. Name of the instance that is used for destination in a copy operation.

TIBCO Administrator Server Configuration Guide

getConfigProperties() 157

getConfigProperties()
Purpose

This method returns properties used for initializing the server. Most of properties are read from the t i b c o a d m i n _ domain. t r a file this server is using. When a property is not specified explicitly in the t i b c o a d m i n _ domain. t r a file, this method returns the default value that the server is currently using. See Chapter 3, Administration Server Properties File. This method returns one row consisting of multiple columns. To retrieve the status of load-balancing mode, you can invoke the method getStatus() on page 161. To retrieve information about TIBCO Rendezvous parameters of the server, you can use getRvConfig() on page 159. To retrieve information about logging of the server, see getLogConfig() on page 164.

Type Parameters Returns

Open, Synchronous, METHOD_TYPE_INFO None Name repo.ServerName repo.lockTimeout Description Name of the server. Number of seconds a repository instance is willing to wait without hearing a heartbeat from a client that has locked various resources, before automatically freeing those resources. Name of the JDBC driver this repository process will use to connect its instances to their database. JDBC URL this repository process will use to connect its instances to their database. JDBC database account user name this repository process will use to connect its instances to their database. Type of backend to connect to. The dbtype has to be set to one of the following: Sql, Oracle8, Oracle7, Db2, Sybase.

repo.jdbcDriver repo.jdbcURL repo.username

repo.dbtype

TIBCO Administrator Server Configuration Guide

158

| Appendix B

Using TIBCO Hawk Methods

Name repo.directory repo.fileType

Description The directory which this repository process will search for repository instances. The format of this repository process's instance data files. Valid values are B I N , X M L , or V C .

repo.encoding repo.qThreadCnt repo.master

Character encoding for repository communication, either I S O 8 8 5 9 - 1 or U T F - 8 . The value specifies how many threads are used to process read requests for each instance. In the load-balancing mode, one server is designated as the primary and the other servers as secondary servers. The value is used to distinguish the primary server from secondary servers. The value of the r e p o . m a s t e r parameter is either the host name or the IP address of the primary server.

repo.hawkImplant repo.hawkMaxThread

The value specifies whether the server creates a TIBCO Hawk microagent when it starts. The value specifies how many threads should process TIBCO Hawk AMI requests for this server.

See Also

Chapter 3, Administration Server Properties File

TIBCO Administrator Server Configuration Guide

getRvConfig() 159

getRvConfig()
Purpose

This method returns information related to the TIBCO Rendezvous session that the server uses for network communication. Most of properties are read from the t i b c o a d m i n _ domain. t r a file this server is using. When a property is not specified explicitly in the t i b c o a d m i n _ domain. t r a file, this method returns the default value that the server is currently using. This method returns one row consisting of multiple columns. To retrieve other properties of the server, use getConfigProperties() on page 157.

Type Parameters Returns

Open, Synchronous, IMPACT_INFO None Name repo.rvDaemon repo.rvNetwork repo.rvService repo.instanceDiscoverySubject repo.instanceMgmtSubjectPrefix Description TIBCO Rendezvous daemon for this session. Network used by this session. TIBCO Rendezvous service used by this session. Subject for the instance discovery subject. Instance management subject prefix on which this server listens for instance management requests such as create and copy.

See Also

TIBCO Rendezvous Properties on page 52

TIBCO Administrator Server Configuration Guide

160

| Appendix B

Using TIBCO Hawk Methods

getConfig()
Purpose

This method returns information related to the server process. It includes the Java version and the TIBCO Hawk AMI version used by the server. It also includes the path of the t i b c o a d m i n _ domain. t r a file that the server uses for initialization properties.

Type Parameters Returns

Open, Synchronous, IMPACT_INFO None Name Server name IP address of machine OS name OS version Server start time JMV version Repository version Hawk AMI version RV version Path of used tibcoadmin_domain.tra Description Name of server. IP address of the machine on which the repository is running. Operating system of the machine on which the repository is running. Operating system version of the machine on which the repository is running. Time when the server started. Version of the Java Virtual Machine of the machine on which the repository is running. Version of the server. Version of the Hawk AMI which the repository is using. Version of the TIBCO Rendezvous java package server is using for its network communication. Path of the t i b c o a d m i n _ domain. t r a file which the server read for reading initialization properties.

TIBCO Administrator Server Configuration Guide

getStatus() 161

getStatus()
Purpose

This method returns information related to the current status of the server process. It includes the number of repository instances and clients that this server is serving. It also includes memory usage of this server process. The T i m e w h i l e s e r v e r h a s the server started, in seconds.
been up

represents the time that has passed since

Type Parameters Returns

Open, Synchronous, IMPACT_INFO None Name Number of instances Number of currently connected read-only clients Number of currently connected read-write clients Number of total connections made till now Total number of nodes Number of locked nodes Total memory of this process Description Number of project instances that the server is serving. Number of read-only clients currently connected to this server. Number of read-write clients currently connected to this server. Number of connections which have been made through this server. Total number of nodes in all instances connected to this server. Total number of nodes locked by instances connected to this server. Total amount of memory in the Java Virtual Machine. The total amount of memory currently available for allocating objects, measured in bytes. Free memory of this process Amount of free memory in the system. An approximation to the total amount of memory currently available for future allocated objects, measured in bytes.

TIBCO Administrator Server Configuration Guide

162

| Appendix B

Using TIBCO Hawk Methods

Name Time while server has been up

Description Time that has passed since the server started. Time is measured in seconds.

TIBCO Administrator Server Configuration Guide

getQueueStats() 163

getQueueStats()
Purpose

This method returns information related to the statistics of TIBCO Rendezvous queue lengths for the server. An administration server is queueing requests from clients before processing those requests. If the queue lengths are big, that means the server is busy. A server maintains different queues for different kind of requests from the different instances. This method provides information on these queues. Calling this method too often will degrade server performance. Therefore, if less than 10 seconds have passed since the previous call, this method returns the previous result.

Type Parameters Returns

Open, Synchronous, IMPACT_INFO None Name Sum of queue lengths Maximum queue length Description Sum of lengths of all TIBCO Rendezvous queues that this server currently maintains. Maximum queue length for all TIBCO Rendezvous queues this server currently maintains. If the maximum value is high and the average is relatively low, only requests on a certain instance are queued before being processed. Average queue length Total number of queues Average of TIBCO Rendezvous queues lengths that this server currently maintains. Number of TIBCO Rendezvous queues on the server.

TIBCO Administrator Server Configuration Guide

164

| Appendix B

Using TIBCO Hawk Methods

getLogConfig()
Purpose

This method returns information about the log operation of the repository server component of TIBCO Administrator. This method returns five columns, which represent the current log level as well as information about log files. Users can determine whether the server writes the log to files or not, by checking the I s l o g o n return column.

Type Parameters Returns

Open, Synchronous, IMPACT_INFO None Name Is log on Log level Description The value specifies whether the server should write log into a file or not. The value specifies the current level of logging. This value is to specify the level of log, which designates how detailed the content of log should be. The supported levels are error, warning, info, verbose Log directory If the level is set to e r r o r, only error messages are logged. If level is set to w a r n i n g , warning and error messages are logged. If level is set to i n f o , informative, warning, and error messages are logged. If level is set to v e r b o s e or d e b u g , verbose, info, warning, and error messages are logged.

This value specifies the directory where the log files are created. This value only has an effect if the I s
true. log on

return value is

TIBCO Administrator Server Configuration Guide

getLogConfig() 165

Name Log file max number

Description This value specifies the maximum number of log files that are maintained in a log directory by the repository server. This value only describes log files created in the directory specified by the L o g d i r e c t o r y return value of this method.

Log file max size

The value is to specify the max size that log files normally grow only to. After reaching this limit, the log file is closed and a new file is opened. This value only describes log files created in the directory specified in the L o g d i r e c t o r y return value of this method.

TIBCO Administrator Server Configuration Guide

166

| Appendix B

Using TIBCO Hawk Methods

getTraceIds()
Purpose

This method returns currently active trace IDs of repository server. Trace IDs are used for low-level debugging and should only be turned on at the request of TIBCO Support. Open, Synchronous, IMPACT_INFO None Name Trace Ids Type string Description Current trace IDs of repository server.

Type Parameters Returns

TIBCO Administrator Server Configuration Guide

onContentChange() 167

onContentChange()
Purpose

Notify local TIBCO Hawk agents of any content changes in any of the instances that this server is serving. If you want to track a specific instance rather than all the instances, you can use instance name in your rule base.

Type Parameters Returns

Open, Asynchronous, IMPACT_INFO None Name Instance name New commit number Description Name of repository instance in which the content change happened. Current commit number of the updated instance. This number is increased by one whenever any content change happens on the instance. Client which changed the instance. Description of changes.

Client Changes

TIBCO Administrator Server Configuration Guide

168

| Appendix B

Using TIBCO Hawk Methods

setLogConfig()
Purpose

This method can control whether log is written to files or not, and controls the log level. The repository server's logging is provided on both standard output and the log file if the log file is available. Users can control the level for both file and standard output logging. Users can decide whether server should write log or not, by setting the I s parameter.
Log On

Users can change properties of log files with optional parameters Log directory Log file max number, and Log file max size.
Type Parameters

Open, Synchronous, METHOD_TYPE_ACTION Name Is Log On Log Level Description This parameter decides whether the server should write the log into a file or not. This parameter specifies the current level of logging, which determines how detailed the content of log should be. This parameter is optional. The user leave it empty or can specify a certain level. Default value is info for new log files. The supported levels are error, warning, info, verbose If the level is set to e r r o r, only error messages are logged. If level is set to w a r n i n g , warning and error messages are logged. If level is set to i n f o , informative, warning, and error messages are logged. If level is set to v e r b o s e or d e b u g , verbose, info, warning, and error messages are logged.

TIBCO Administrator Server Configuration Guide

setLogConfig() 169

Name Log directory

Description This parameter is optional. The user can specify a certain directory or leave it as empty. This value only has an effect if the Is log on parameter set
true.

When this parameter is specified as a directory name, the repository server creates log files in the specified directory. When this parameter is not specified (left as empty string), and a previous log file exists, then the server writes the log to the same file. But if no log file has been created by the server and the r e p o . l o g D i r e c t o r y parameter in the t i b c o a d m i n _ domain. t r a file is also not set, then the repository server uses default directory . / l o g to create the log files. Log file max number This value specifies the maximum number of log files that are maintained in a log directory by the repository server. This value only describes log files created in the directory specified by the L o g d i r e c t o r y return value of this method. Log file max size This parameter is optional. The user can specify the size of each log file. If no value is specified, the size is zero, that is, no file is created. This value only has an effect when new log files are created under the directory specified in Log directory parameter of this method. Otherwise this parameter value is ignored. This parameter specifies the maximum size for log files. After reaching this limit, the log file is closed and a new file is opened.

TIBCO Administrator Server Configuration Guide

170

| Appendix B

Using TIBCO Hawk Methods

setTraceIds()
Purpose Type Parameters

This method sets the current trace IDs for the repository server. Open, Synchronous, IMPACT_INFO Name Trace Ids Type string Description Trace IDs of the repository server you want set.

TIBCO Administrator Server Configuration Guide

doShutdownServer() 171

doShutdownServer()
Purpose

This method shuts down the repository server process. The method sends a server shutdown notification. Its return value lists the names of clients who are connected to any instances of this server. Time-out for this method is set to 20 seconds.

Type Parameters

Open, Synchronous, METHOD_TYPE_ACTION_INFO Name Force shutdown Description This parameter determines whether the server is shut down forcibly if it is in the process of writing something to an instance. If the parameter is set to t r u e , this method forces a server shutdown even if some clients had unsaved changes. If the parameter is set to false, and some clients had unsaved changes, this method throws an exception rather than shutting down the server. Release Instance Lock This parameter determines whether the server removes locks of its instances when it is shut down. If the parameter is set to t r u e , this method not only kills the server process, but also releases all of its instance locks. If the parameter is set to false, instance locks remain even after the server process is killed, which encourages instances to be served by a server with the same name in the future.

Returns

Name Client Type Instance

Description Name of clients currently connected to any instances of this repository server. Type of client, either R e a d - o n l y or R e a d - w r i t e . Name of the repository instance to which this client is connecting.

TIBCO Administrator Server Configuration Guide

172

| Appendix B

Using TIBCO Hawk Methods

getInstanceInfos()
Purpose

This method returns the properties of a specified instance in the return values. If you leave the input parameter Instance name empty, the method finds all instances that this repository server is serving. If the specified instance is not available on this server, this method throws an exception.

Type Parameters

Open, Synchronous, IMPACT_INFO Name Instance Name Description Instance name that you are interested in. Leave it empty if you want list all the instances that this server is serving.

Returns

Name InstanceName InstanceType serverName displayName description encoding fileType isDefault

Description Name of the instance. Type of the instance. The value is either remoteRV or local File. Name of the server for this instance. Display name of the instance. Description of the instance. Encoding of the instance. File type of the instance. This value is only meaningful if you are dealing with a file repository. Specifies whether this instance is the default instance or not. If the instance is a default instance, the value is t r u e , otherwise f a l s e .

requestSubjectPrefix

Prefix for the subject on which this repository instance listens for various types of requests.

TIBCO Administrator Server Configuration Guide

getInstanceInfos() 173

Name responsiblePerson supportInfo version

Description Person responsible for the instance. Support information for the instance. Version of the instance.

TIBCO Administrator Server Configuration Guide

174

| Appendix B

Using TIBCO Hawk Methods

getInstanceStatus()
Purpose

This method returns information related to the current status of a repository instance. It includes the number of clients and nodes, and also the current commit number for the specified instance. The T o t a l n u m b e r o f c o n n e c t i o n s m a d e u n t i l n o w return value counts the number of connections which have been made by any clients since the instance had started. To retrieve the names of available instances, use getInstanceInfos() on page 172.

Exceptions

This method throws exceptions: If the client does not specify the instance name. If the specified instance is not available on this server.

Type Parameters

Open, Synchronous, IMPACT_INFO Name Instance name Description Name of the instance you are interested in. Description Name of the instance. Number of read-only clients that are connecting to the specified repository instance. Number of read-write clients that are connecting to the specified repository. Number of connections which have been made by any clients since the instance started. Total number of nodes in the specified repository instance. Number of the instances nodes that are locked by all repository clients. Number of commits made on the specified repository instance since its creation.

Returns

Name Instance name Number of currently connected read-only clients Number of currently connected read-write clients Total number of connections made until now Total number of nodes Number of locked nodes Commit number of instance

TIBCO Administrator Server Configuration Guide

getSizeOfInstance() 175

getSizeOfInstance()
Purpose

This method returns current size of the data of the specified instance, in bytes. The method counts each character as two bytes and each reference to another node as four bytes. Calling this method too often degrades repository server performance. This method therefore returns the previous result if less than 60 seconds has passed since the previous call. You must specify an instance that exists in the server, otherwise this method throws an exception.

Type Parameters

Open, Synchronous, IMPACT_INFO Name Instance name Type string Type string Description Name of the instance you are interested in. Description Size of the contents of this instance.

Returns

Name size in bytes

TIBCO Administrator Server Configuration Guide

176

| Appendix B

Using TIBCO Hawk Methods

getListOfLockedNodes()
Purpose

This method returns a list of names of all the nodes that are currently locked by any client. You must specify an instance that exists for the server, otherwise this method throws an exception.

Type Parameters

Open, Synchronous, IMPACT_INFO Name Instance name Description Name of the instance you are interested in. Description Names of all the objects that are currently locked by any client. Client that has locked each node.

Returns

Name Node name Locker

TIBCO Administrator Server Configuration Guide

getConnectedClients() 177

getConnectedClients()
Purpose

This method returns a list of names clients connected to the specified instance. If the instance name is not specified, it searches all the clients of all the instances that this server is serving. If the specified instance is not found in the server, then the server will throw an exception.

Type Parameters

Open, Synchronous, IMPACT_INFO Name Instance name Description Name of the instance you are interested in. If it is not specified, this method searches all the instances of this server. Description Name of the clients currently connected to the specified instance. Type of client, either r e a d - o n l y or r e a d - w r i t e . Name of the instance to which this client is connecting.

Returns

Name Client Type Instance

TIBCO Administrator Server Configuration Guide

178

| Appendix B

Using TIBCO Hawk Methods

doStopInstance()
Purpose

This method stops a repository instance being served by the monitored repository server. The method sends a notification that the instance has been stopped to TIBCO Hawk. Its return value will list the names of clients who are connected to any instances of this server.

Exceptions

The method throws exceptions: If the instance name is not specified or the specified named instance does not exist in the server. If there are any nodes locked by connected clients.

Type Parameters

Open, Synchronous, METHOD_TYPE_ACTION_INFO Name Instance name Description Name of the instance you are interested in. If the instance name is not specified or the specified named instance does not exist in the server, this method will throws an exception. This parameter determines whether the method removes the lock on this instance when the instance on this server is stopped. If the parameter is set to t r u e , this method stops the repository instance and release its instance lock. When the parameter is set to false, the instance lock will remain even after the instance is stopped, which encourages this instance to be served by a server of the same name in the future.

ReleaseInstanceLock

Returns

Name Client Type Instance

Description Name of the clients currently connected to the specified instance. Type of the client, either R e a d - o n l y or R e a d - w r i t e . Name of the instance to which this client is connecting.

TIBCO Administrator Server Configuration Guide

doStartInstance() 179

doStartInstance()
Purpose

This method starts a repository instance, so that the specified instance becomes available through this repository server. The method will send a notification that the instance has been started to the TIBCO Hawk system. When the server is operating in load-balancing mode, this method will throw an exception unless the global load-balancing mode of the repository servers is read-only. The timeout value for this method is therefore set to thirty minutes. If the instance name is not specified or the specified named instance does not exist in the server, this method will throw an exception.

Type Parameters

Open, Synchronous, IMPACT_ACTION Name Instance name Description Name of the instance you want to start. If the instance name is not specified or the specified named instance does not exist in the server, this method will throw an exception.

TIBCO Administrator Server Configuration Guide

180

| Appendix B

Using TIBCO Hawk Methods

doRefreshCache()
Purpose

Refresh the content of the repository server's cache by re-reading the content of the specified instance. If the server is operating in load-balancing mode, this method throws an exception if the global load-balancing mode of the repository server is not r e a d - o n l y. If the server has something to write in the cache, this method will throw an exception. If the server is shutting down, this method throws an exception. Because reloading can be time consuming, the timeout for this method is set to 60 minutes.

Exceptions

Type Parameters

Open, Synchronous, METHOD_TYPE_ACTION_INFO Name Instance Name Description Name of the instance that you want to read again from the backend. If the instance name is not specified or the specified named instance does not exist in the server, this method throws an exception.

Returns

Name Client Type Instance

Description Name of the clients currently connected to the specified instance. Type of the client, either read-only or read-write. Name of the instance to which this client is connecting.

TIBCO Administrator Server Configuration Guide

doRefreshSecurity() 181

doRefreshSecurity()
Purpose Type

Refresh the security objects of the Repository server. Open, synchronous, METHOD_TYPE_ACTION_INFO

TIBCO Administrator Server Configuration Guide

182

| Appendix B

Using TIBCO Hawk Methods

doTerminateClient()
Purpose

This method disconnects the specified client from the repository instance This means immediate rollback of any uncommitted data of the specified client, and removal of the client entry in the instance.

Exceptions

If the client name is not specified, or the specified named client does not exist in the instance, this method will throw an exception. If the instance name is not specified or the specified named instance does not exist in the server, this method will throw an exception.

Type Parameters

Open, Synchronous, IMPACT_ACTION Name Client Description Name of client that you want to terminate. If it is not specified or specified named client does not exist in the instance, this method will throw an exception. Instance name Name of the instance from which you want to disconnect a the client. If it is not specified or specified named instance does not exist in the server, this method will throw an exception.

TIBCO Administrator Server Configuration Guide

| 183

TIBCO Administrator Server Configuration Guide

184

| Appendix B

Using TIBCO Hawk Methods

TIBCO Administrator Server Configuration Guide

| 185
Appendix C

Schema Files used when Exporting and Importing

TIBCO Administrator includes import and export utilities. These utilities can be used in conjunction with predefined XML schema (.xsd) files to ensure that all data you have added to an XML project file are valid. Syntax and parameters are listed in Chapter 5, Command Line Utilities. This appendix gives some additional information about using the tools and about the schemas included.

Topics
XML Formats Used by TIBCO Projects, page 186 Schema Files Included With TIBCO Runtime Agent, page 187 Using RepoExport and RepoImport, page 188 Creating a New Adapter Configuration Schema, page 190 Including Custom Schemas During Import, page 191

TIBCO Administrator Server Configuration Guide

186

| Appendix C

Schema Files used when Exporting and Importing

XML Formats Used by TIBCO Projects

When you use the tools to export TIBCO projects to XML file(s), or import repository XML files into TIBCO projects, the following formats are available: Generic XML format uses a generic TIBCO Repository format. This format is unchanged from TIBCO Repository 3.x. Although this format is efficient to process, it does not permit any validation of the content. AEXML format, introduced in ActiveEnterprise 4.0, permits validation of its content using XSD schema files included with the release. Additional schemas for validation may be defined as discussed below. AEXML multi-file format differs slightly from base AEXML format. You can, however, save multi-file projects as single-file projects and vice versa. To find the XSDs that can be used to validate multi-file project files, unjar the file t r a / n.n/ l i b / T I B C O r t . j a r. Inside the file, all XSD files belonging to the package \ c o m \ t i b c o \ o b j e c t \ r e p o \ m a p p e r can be used to verify resource files. Even though AEXML format is similar to the format of multi-file projects but is not exactly the same. Files created with export cannot be used as projects; they must first be imported into a valid project.

TIBCO Administrator Server Configuration Guide

Schema Files Included With TIBCO Runtime Agent 187

Schema Files Included With TIBCO Runtime Agent

TIBCO Runtime Agent includes a number of schema files which you can use to validate AEXML files you import. The following files are included in the release:
Repository.xsd

Basic repository object definitions. class and sequence descriptions. and session definitions

A E S c h e m a . x s d AE

A E S e r v i c e . x s d Endpoint A E S D K . x s d Other

TIBCO Adapter SDK object definitions (tracing, monitoring, and so forth.)

To use the files, unjar the file TIBCO_TRA_HOME\ l i b \ T I B C O r t . j a r. You will see a number of XSDs. All XSDs belonging to the package c o m \ t i b c o \ i n f r a \ r e p o s i t o r y \ i m p o r t e x p o r t can be used for import/export validation. The four files are dependent on each other as follows:
Repository.xsd AESDK.xsd

is required by the three other .x s d files.

requires all of the other three . x s d files.

In the s c h e m a \ a p p s directory, A D B , p e o p l e s o f t , and M e s s a g e B r o k e r schema files are included. The R e p o I m p o r t and R e p o E x p o r t tools always check the S c h e m a s . x m l file for the location of schemas when AEXML format is used.

TIBCO Administrator Server Configuration Guide

188

| Appendix C

Schema Files used when Exporting and Importing

Using RepoExport and RepoImport

You can export and import projects in one of two ways: Use the TIBCO Designer import and export facilities. Use the R e p o E x p o r t or R e p o I m p o r t utilities. See RepoExport, page 121 and RepoImport, page 123.

Simple export and import operations are useful, for example, if you want to archive your configuration in XML format. They are even more frequently used by developers who want to import an existing project (or part of it) into another project. Example: Importing an Adapter into an Existing Project To import an adapter into an existing project, follow these steps: 1. Export the adapter instance.
R e p o E x p o r t - u r l url - f o r m a t A E X M L - n o c h a s e /tibco/private/adapter/ADB/ACME

exportfile

url is the location of the repository instance in which the adapter is stored.
/tibco/private/adapter/ADB/ACME

is the root node of the adapter.

The command creates an XML file of the adapter. The file uses AEXML format so validation during import is possible. The file does not include the contents of referenced nodes. As a result, the adapter wont overwrite, for example, metadata or sessions already defined in the repository into which you want to import. 2. Import the adapter into the project, using validation.
RepoImport -url

url importfile - c o n t i n u e

This command imports the adapter repository file importfile into the specified location inside a project. The import uses all schema files in the current directory for validation and continues import even when validation errors are found. Example: Exporting, Changing, and Importing an Adapter If you wanted to export an adapter to XML, make changes in the XML file, then the adapter into an existing project, follow these steps: 1. Export the adapter instance.
R e p o E x p o r t - u r l url - f o r m a t A E X M L - n o c h a s e /tibco/private/adapter/ADB/ACME

exportfile

url is the location of the project in which the adapter is stored.

TIBCO Administrator Server Configuration Guide

Using RepoExport and RepoImport 189

/tibco/private/adapter/ADB/ACME

is the root node of the adapter.

The command creates an XML file of the adapter. The file uses AEXML format so validation during import is possible. The file does not include the contents of referenced nodes. As a result, the adapter wont overwrite, for example, metadata or sessions already defined in the project into which you want to import. 2. Make changes to the adapter XML file. 3. Import the adapter into the project, using validation.
RepoImport -url

url importfile

This command imports the adapter project file importfile into the specified location inside a project. The import uses all schema files in the current directory for validation. The import process stops if errors are found.

TIBCO Administrator Server Configuration Guide

190

| Appendix C

Schema Files used when Exporting and Importing

Creating a New Adapter Configuration Schema

If you want to add new configuration elements to your adapter and benefit from validation, you must create a new . x s d schema file. Your custom schema file will then be used in conjunction with the four files discussed in Schema Files Included With TIBCO Runtime Agent on page 187. 1. Create a new . x s d file that extends the AESDK schema and defines the new elements. 2. Include a namespace definition for your . x s d . If using XML Authority, choose File > Schema Properties > Target Namespace. An example, m y A d a p t e r . x s d , which has the elements for a Clarify adapter, is included with the TIBCO Runtime Agent installation in the s c h e m a s folder. 3. Create an XML file for the adapter you want to define. An example, m y A d a p t e r . x m l , which specifies some attribute values for a Clarify adapter, is included with the TIBCO Runtime Agent installation. 4. Make sure that each element knows the namespace (that is, the . x s d ) to which it belongs. The example uses two namespace (xmlns) elements: The default namespace, AESDK. The custom namespace, ClarifyAdapter. 5. If you later want to export the file using R e p o s i t o r y E x p o r t , you must update the file repo_home\ b i n \ n a m e s p a c e . i n i file to include the custom namespace. For example, for the Clarify adapter, you would add:
/tibco/private/adapter/ClarifyAdapter = myAdapter

See Also

Schema Files used when Exporting and Importing on page 185

TIBCO Administrator Server Configuration Guide

Including Custom Schemas During Import 191

Including Custom Schemas During Import

If you have created a custom schema and want R e p o I m p o r t to use it, you have two options: Include the custom schema location(s) on the command line. Edit the file S c h e m a s . x m l to include the custom schema(s). The location of that file depends on the product you are using, for example, for TIBCO Runtime Agent, S c h e m a s . x m l is in TIBCO_TRA_HOME\ b i n . Adapters should have a s c h e m a s directory.

TIBCO Administrator Server Configuration Guide

192

| Appendix C

Schema Files used when Exporting and Importing

TIBCO Administrator Server Configuration Guide

| 193
Appendix D

System Messages

This appendix lists system messages sent by the administration server..

Topics
AEREPO Messages, page 194 POF Messages, page 228 POFUTIL Messages, page 256 POOL Messages, page 262 PLUGIN Messages, page 265

TIBCO Administrator Server Configuration Guide

194

| Appendix D

System Messages

AEREPO Messages
AEREPO-100001

Cannot start repository server as NT service: %1 Role: Error Category: System Resolution: Verify configuration of tibcoadmin_domain.tra file and verify the system environment variables are set correctly. Ensure that TIBCO Rendezvous and TIBCO Repository are in the CLASSPATH, and that a matching version of TIBCO Rendezvous is in the PATH.

AEREPO-100002

Cannot start repository server: %1 Role: Error Category: System Resolution: Verify proper configuration. If problem persists, contact TIBCO support.

AEREPO-100003

Cannot run instance: %1 Role: Error Category: System Resolution: Named instance is corrupted. If this is a file based instance: 1. Make a backup of the file. 2. Delete the file. 3. Create a new instance with the same name. 4. Restore the instance by using RepositoryImport with a backup. If this is a database instance, contact TIBCO Support.

AEREPO-100004

Error in sending server discovery response: %1 Role: Error Category: Server

TIBCO Administrator Server Configuration Guide

AEREPO Messages 195

Resolution: Indicates a problem with the network. Ensure that server machine has sufficient memory and is communicating successfully with the local area network.

AEREPO-100005

%1 Role: Error Category: Server Resolution: Historical, no longer used.

AEREPO-100006

Error in processing server state change: %1 Role: Error Category: Server Resolution: Retry setting the server state. If this fails, edit the t i b c o a d m i n _ domain. t r a files to set r e p o . s t a t e to the new desired value and shutdown all Load Balanced servers in the Load Balanced group, then restart the servers.

AEREPO-100007

Instances uninitialized for instance discovery response Role: Error Category: Server Resolution: Clients are attempting to communicate with the server before it is initialized. Wait and retry the client connections.

AEREPO-100008

Error in sending instance discovery response: %1 Role: Error Category: Server Resolution: Indicates an problem with TIBCO Rendezvous. If the problem persists, reboot the machine. If the problem still persists, contact TIBCO support.

AEREPO-100009

Getting connected client names has found unmatched size of list Role: Error Category: HawkImplant
TIBCO Administrator Server Configuration Guide

196

| Appendix D

System Messages

Resolution: Contact TIBCO support.

AEREPO-100010

Bad initialization parameter for servlet, configFile parameter of the web.xml file must be filled. Role: Error Category: Servlet Resolution: Indicates a problem with tomcat configuration. Delete and recreate your domain.

AEREPO-100011

Error in initializing servlet for repository: %1 Role: Error Category: Servlet Resolution: Contact TIBCO support.

AEREPO-100012

Error in running repository servlet: %1 Role: Error Category: Servlet Resolution: Contact TIBCO support.

AEREPO-100013

Error in create thread for checking db connection: %1 Role: Error Category: HawkImplant Resolution: Contact TIBCO support.

AEREPO-100014

Could not read InstanceInfo file %1 Role: Error Category: System Resolution: Either the userid running the server does not have read access to the file, or the instance file is corrupted. In the former case, grant file system access to the specified file. In the latter case, delete the file, recreate the instance and restore its contents from a backup using R e p o s i t o r y I m p o r t .

TIBCO Administrator Server Configuration Guide

AEREPO Messages 197

AEREPO-100015

Could not read server process property file %1 Role: Error Category: System Resolution: Make sure that the correct file is specified. Grant file system read privilege to the userid running the administration server.

AEREPO-100016

Error in creating instance with RepoCreateInstance tool: %1 Role: Error Category: CreateInstanceTool Resolution: Verify that configuration and environment variables are correct. Verify that database is up and communicating with the machine on which you are running the command. Verify the JDBC parameters. Verify that the specified userid has sufficient authority to drop and create the tables.

AEREPO-100017

Rendezvous error reading request or sending reply, no reply possible: %1 Role: Error Category: TibRvComm Resolution: Contact TIBCO support.

AEREPO-100018

Fatal error when reinitialization of security rules on instance %1 by user %2; Exception type:%3 content:%4 Role: Error Category: Security Resolution: Contact TIBCO support.

AEREPO-100019

Cannot start security enabled repository server with the user who does not have access right on the rule %1 on domain %2: %3 Role: Error Category: Security

TIBCO Administrator Server Configuration Guide

198

| Appendix D

System Messages

Resolution: Use TIBCO Domain Utility to set the user for the domain to the administrative super user. Never remove super user privileges from the admin user used to launch the server.

AEREPO-100020

Cannot start commit history: %1 Role: Error Category: Configuration Resolution: Verify that the directory specified for the property repo.commitHistoryDirectory in the t i b c o a d m i n _ domain. t r a file exists.

AEREPO-100024

Invalid database type %1. Currently supported database types are %2 Role: Error Category: Configuration Resolution: Verify that the value specified for the repo.dbtype parameter in the t i b c o a d m i n _ domain. t r a file is correct, has the correct capitalization and does not include extra spaces or punctuation. Supported values are: "Sql", "Oracle", "Db2", "Sybase"

AEREPO-100025

Cannot find one of parental nodes of the renamed node in the client cache while updating ACL. Role: Error Category: Security Resolution: Your authorization information is out of sync. Restart the server. If problems persist, contact TIBCO support.

AEREPO-100026

Found duplicate repository instances of different formats (single-file and multi-file repository): %1. Neither of the instances will be started Role: Error Category: Configuration Resolution: Make sure that the directory specified by the r e p o . d i r e c t o r y parameter does not contain both a file %1.dat and a directory %1.

AEREPO-100027

Found duplicate VC Instances: %1. None of them will be started

TIBCO Administrator Server Configuration Guide

AEREPO Messages 199

Role: Error Category: Configuration Resolution: Contact TIBCO support.

AEREPO-100028

Cannot get environment variable TIBCO_ADMIN_HOME: %1 Role: Error Category: Configuration Resolution: Verify that your t i b c o a d m i n _ domain. t r a file contains the property j a v a . p r o p e r t y . T I B C O _ A D M I N _ H O M E = X X where X X is the directory where TIBCO Administrator is installed (for example, C \ : / t i b c o / a d m i n i s t r a t o r / 5 . 1 ).

AEREPO-100029

Cannot get environment variable TIBCO_REPOSITORY_VERSION: %1 Role: Error Category: Configuration Resolution: Contact TIBCO support.

AEREPO-100030

Expected repository URL after -url Role: Error Category: CreateInstanceTool Resolution: Provide a valid repoUrl including server and instance names after the -url argument. On the command line type CreateInstanceTool -help url for a description of a valid repo url.

AEREPO-100031

Expected configFile name after -configFile Role: Error Category: CreateInstanceTool Resolution: Provide a file name following the -configFile argument. This can be either an absolute or relative path.

AEREPO-100032

Unknown argument %1 Role: Error

TIBCO Administrator Server Configuration Guide

200

| Appendix D

System Messages

Category: CreateInstanceTool Resolution: Remove the identified argument and rerun the tool.

AEREPO-100033

Expected -url to specify new repository to be created. Type 'RepoCreateInstance' for help Role: Error Category: CreateInstanceTool Resolution: Provide a valid repoUrl including server and instance names after the -url argument. On the command line type CreateInstanceTool -help url for a description of a valid repoUrl.

AEREPO-100034

Cannot get instance name from the given url. Type 'RepoCreateInstance -help url' for information on the url format Role: Error Category: CreateInstanceTool Resolution: Add the instance name immediately following t i b c r : / / for server-based repositories, or provide the path to . d a t file for file repositories.

AEREPO-100035

You must specify the server parameter in the url. Type 'RepoCreateInstance -help url' for information on the URL format Role: Error Category: CreateInstanceTool Resolution: Must provide parameter server=xx as part of the repo url where xx is the name of the server or domain where you wish to create the instance.

AEREPO-100036

Cannot find the repository server spiffiest in the url. Type 'RepoCreateInstance -help url' for information on the URL format Role: Error Category: CreateInstanceTool Resolution: Verify that the server name is specified correctly with the correct capitalization, and that it is running.

TIBCO Administrator Server Configuration Guide

AEREPO Messages 201

AEREPO-100037

To connect security-enabled server, the userName and password and parameters must be specified in the url. Type 'RepoCreateInstance -help url' for information on the URL format Role: Error Category: CreateInstanceTool Resolution: Specify an administrative userid and password in the repo url.

AEREPO-200001

Specified Master host %1 could not be found. Server running as slave Role: Warning Category: Resolution: May be safely ignored if this server was intended to be a slave. If the server was intended to be a primary server, correct the hostname specified on r e p o . m a s t e r parameter in the t i b c o a d m i n _ domain. t r a file.

AEREPO-200002

HAWK Implant disabled: If you want to enable the hawk microagent, include the installed hawk jar files in the CLASSPATH environment variable used to launch the Repository Server. Cannot enable Hawk because unable to find the class %1 Role: Warning Category: System Resolution: If TIBCO Hawk monitoring is not required, set the parameter r e p o . h a w k I m p l a n t in the t i b c o a d m i n _ domain. t r a file to false. If TIBCO Hawk monitoring is required, install TIBCO Hawk and add the Hawk jar files as described in the TIBCO Repository Installation and Administration Guide.

AEREPO-200003

Cannot start the specified instance %1 in the instance list in the tibcoadmin_domain.tra Role: Warning Category: Configuration Resolution: Either correct or comment out the repo.instanceNames parameter in the t i b c o a d m i n _ domain. t r a file.

AEREPO-200004

Configuration specifies empty or invalid instance list, no instances started

TIBCO Administrator Server Configuration Guide

202

| Appendix D

System Messages

Role: Warning Category: Configuration Resolution: Either correct or comment out the r e p o . i n s t a n c e N a m e s parameter in the t i b c o a d m i n _ domain. t r a file.

AEREPO-200005

Discovered another instance with same name on server %1; Instance %2 will not be started. Role: Warning Category: Configuration Resolution: Indicates a configuration problem. Identify which of the servers is correctly configured and change the configuration for the other one. If Load Balancing mode is desired, make sure that all servers in a Load Balanced group have the same server name and that the r e p o . m a s t e r parameter in the t i b c o a d m i n _ domain. t r a file is uncommented and is non-empty for all servers.

AEREPO-200006

Warning: file instance %1 conflicts with existing database instance, ignoring file instance Role: Warning Category: Configuration Resolution: Verify server configuration.

AEREPO-200007

Ignoring unknown incoming instance-management request %1 on %2 Role: Warning Category: Server Resolution: No action required. This indicates that a newer client is attempting to communicate with the server. The client will handle the server's response and retry in a way the server is able to handle.

AEREPO-200009

Detected another server with same name; This server is exiting. Role: Warning Category: Server

TIBCO Administrator Server Configuration Guide

AEREPO Messages 203

Resolution: Indicates a configuration problem. Identify which of the servers is correctly configured and change the configuration for the other one. If Load Balancing mode is desired, make sure that the r e p o . m a s t e r parameter in the t i b c o a d m i n _ domain. t r a file is uncommented and is non-empty for all servers.

AEREPO-200010

Detected another master for the LB group; This server is changing to slave Role: Warning Category: Server Resolution: Indicates a configuration problem. Identify which of the servers is correctly configured and correct the configuration for the other one.

AEREPO-200011

State of this server is out of sync with other members of the LB group; This server is changing its state to: %1 Role: Warning Category: Server Resolution: If the new state was not expected, explicitly change the Load Balanced group with either TIBCO Designer or TIBCO Repository Manager to the desired state. If this happens frequently it indicates that your network is being periodically partitioned or is dropping packets.

AEREPO-200012

Server is shutting down cleanly Role: Warning Category: Server Resolution: If server was not intended to be shutdown, restart as soon as it terminates. Set a server password to reduce the chance of inadvertent server shutdowns.

AEREPO-200013

Server is shutting down immediately, aborting unsaved changes Role: Warning Category: Server Resolution: If server was not intended to be shutdown, restart as soon as it terminates. Set a server password to reduce the chance of inadvertent server shutdowns.

TIBCO Administrator Server Configuration Guide

204

| Appendix D

System Messages

AEREPO-200014

Cannot shut down %1; Exception is thrown: %2 Role: Warning Category: Server Resolution: May have active clients that need to save their work. Use TIBCO Hawk console to get a list of active clients. If you intend to shutdown the server and the problem is something other than active clients, issue the kill command from UNIX or terminate with Task Manager if on Microsoft Windows.

AEREPO-200015

Exception in getting Queue Stats: %1 Role: Warning Category: HawkImplant Resolution: May be safely ignored.

AEREPO-200016

Exception in HAWK IMPLANT: notify On change of content: %1 Role: Warning Category: HawkImplant Resolution: Restart any TIBCO Hawk consoles that are monitoring the JDBC connection. If problems persist, contact TIBCO support.

AEREPO-200017

Exception in HAWK IMPLANT: notify On change of state of jdbc connection: %1 Role: Warning Category: HawkImplant Resolution: Restart any Hawk consoles that are monitoring the JDBC connection. If problems persist, contact TIBCO support.

AEREPO-200018

Exception in HAWK IMPLANT: notify On the event of server shutdown: %1 Role: Warning Category: HawkImplant Resolution: Restart Hawk console that issued the stop server request. If problems persist, contact TIBCO support.

TIBCO Administrator Server Configuration Guide

AEREPO Messages 205

AEREPO-200019

Exception in HAWK IMPLANT: notify On the event of stopping instance %1: %2 Role: Warning Category: HawkImplant Resolution: Restart Hawk console that issued the stop instance request. If problems persist, contact TIBCO support.

AEREPO-200020

Exception in HAWK IMPLANT: notify On the event of starting instance %1: %2 Role: Warning Category: HawkImplant Resolution: Restart Hawk console that issued the start instance request. If problems persist, contact TIBCO support.

AEREPO-200021

Exception in HAWK IMPLANT: notify On the event of deleting instance %1: %2 Role: Warning Category: HawkImplant Resolution: Restart Hawk console that issued the delete instance request. If problems persist, contact TIBCO support.

AEREPO-200022

Exception in HAWK IMPLANT: notify On the event of creating instance %1: %2 Role: Warning Category: HawkImplant Resolution: Restart Hawk console that issued the create instance request. If problems persist, contact TIBCO support.

AEREPO-200023

Exception in HAWK IMPLANT: notify On the event of modifying instance %1: %2 Role: Warning Category: HawkImplant

TIBCO Administrator Server Configuration Guide

206

| Appendix D

System Messages

Resolution: Restart Hawk console that issued the modify instance request. If problems persist, contact TIBCO support.

AEREPO-200024

Exception in HAWK IMPLANT: notify On the event of copying instance %1 to a new instance %2: %3 Role: Warning Category: HawkImplant Resolution: Restart Hawk console that issued the copy instance request. If problems persist, contact TIBCO support.

AEREPO-200025

Exception in HAWK IMPLANT: notify On change of global state of load balancing to "%1": %2 Role: Warning Category: HawkImplant Resolution: Restart Hawk console that issued the state change request. If problems persist, contact TIBCO support.

AEREPO-200026

Exception in sending unsolicited warning hawk message "%1": %2 Role: Warning Category: HawkImplant Resolution: Contact TIBCO support

AEREPO-200027

Exception in sending unsolicited error hawk message "%1": %2 Role: Warning Category: HawkImplant Resolution: Contact TIBCO support

AEREPO-200028

Exception in sending unsolicited info hawk message "%1": %2 Role: Warning Category: HawkImplant Resolution: May be safely ignored

TIBCO Administrator Server Configuration Guide

AEREPO Messages 207

AEREPO-200029

Server will shutdown after 10 seconds by hawk request Role: Warning Category: HawkImplant Resolution: A server shutdown was issued from a TIBCO Hawk console. If the server was not intended to be shut down, restart server after shutdown completes.

AEREPO-200030

Exception in doing rollback for user null: %1 Role: Warning Category: Server Resolution: Indicates a read only client issued a rollback. May be safely ignored.

AEREPO-200031

Exception in reading global variable substitution: %1 Role: Warning Category: System Resolution: Contact TIBCO support

AEREPO-200032

Exception in closing Rendezvous connection: %1 Role: Warning Category: TibRvComm Resolution: May need to manually kill the rvd daemon. If server cannot be restarted after this, reboot.

AEREPO-200033

Exception in migrating GSV from old schemas: %1 Role: Warning Category: Database Resolution: Only occurs with database backends. Indicates first time running a 4.x server on data created with a 3.x server. 1. Bring up the 3.x server. and export the data using the RepoExport script from a 4.x version.

TIBCO Administrator Server Configuration Guide

208

| Appendix D

System Messages

2. Stop the 3.x server. 3. Reinitialize the database with the appropriate DBInit script. 4. Start the 4.x server. 5. Recreate the instances and import the saved data using R e p o s i t o r y I m p o r t .

AEREPO-200034

Exception in closing result set during processing BLOB: %1 Role: Warning Category: Database Resolution: If multiple occurrences of this warning appear, backup all instances and restart the database server. If they continue to appear, restart the repository server.

AEREPO-200035

Exception in creating new statement from the buffer (binary array): %1 Role: Warning Category: Security Resolution: Indicates a problem with the security data. Restart the TIBCO Administrator server. If problem persists, contact TIBCO support.

AEREPO-200036

Custom rule[%1] on node %2 of instance %3 is invalid Role: Warning Category: Security Resolution: This may be safely ignored.

AEREPO-200037

Custom rule[%1] on node %2 of instance %3 has an inconsistent name /%4 Role: Warning Category: Security Resolution: This may be safely ignored.

AEREPO-200038

Exception in checking whether the user is administrator or not: %1 Role: Warning

TIBCO Administrator Server Configuration Guide

AEREPO Messages 209

Category: Security Resolution: Server is in a confused state or network is running very slowly. If it persists, verify your network connection and restart the TIBCO Administrator server.

AEREPO-200039

Node does not exist for security rule %1 Role: Warning Category: Security Resolution: May be able to fix by restarting server. Alternatively, back up, delete, recreate and restore the repository listed in the message.

AEREPO-200040

Cannot find the created rule "%1" in the rollback information Role: Warning Category: Security Resolution: May be safely ignored

AEREPO-200041

Exception in deleting rule %1 on the instance %2: %3 Role: Warning Category: Security Resolution: Eventually the extra rules will cause authentication to slow down, but otherwise they do no harm. To get rid of garbage rules, recreate and repopulate your domain.

AEREPO-200042

Exception in setting rule %1 on the instance %2: %3 Role: Warning Category: Security Resolution: Log out and then retry the action. If that fails, restart the server.

AEREPO-200043

Cannot find the deleted rule "%1" in the rollback information Role: Warning Category: Security

TIBCO Administrator Server Configuration Guide

210

| Appendix D

System Messages

Resolution: May be safely ignored.

AEREPO-200045

Cannot read policy domain for instance %1: %2 Role: Warning Category: Security Resolution: Verify that the server was started with the current version of software.

AEREPO-200046

Invalid type of parent rule Role: Warning Category: Security Resolution: Verify that the server was started with the current version of software.

AEREPO-200047

Invalid rule type of read rule Role: Warning Category: Security Resolution: Verify that the server was started with the current version of software.

AEREPO-200048

Duplicated commit ?? the specified rule %1 is not locked by %2 Role: Warning Category: Security Resolution: Restart your server

AEREPO-200049

Cannot find any rules for the instance %1 Role: Warning Category: Security Resolution: If the specified project does not show up in the authorization console, backup, delete, recreate and restore the instance to recreate the security rules.

AEREPO-200050

Exception in rolling back security; problem in removing created but not committed rule: %1

TIBCO Administrator Server Configuration Guide

AEREPO Messages 211

Role: Warning Category: Security Resolution: If the problem persists, restart your server.

AEREPO-200051

While rolling back security, we found unexpected IsUnderDeletion flag on rule %1 Role: Warning Category: Security Resolution: If the problem persists, restart your server.

AEREPO-200052

While rolling back security, we found unexpected IsUnderCreation flag on rule %1 Role: Warning Category: Security Resolution: If problem persists, restart your server.

AEREPO-200053

During committing security cache, user or instance is null; user:%1 instanceName:%2 Role: Warning Category: Security Resolution: In memory security is inconsistent, restart your server.

AEREPO-200054

Exception trying to find matched rule for %1 on the instance %2: %3 Role: Warning Category: Security Resolution: If problem persists, contact TIBCO Support

AEREPO-200055

Try to cache invalid User(null) Role: Warning Category: Security

TIBCO Administrator Server Configuration Guide

212

| Appendix D

System Messages

Resolution: May be safely ignored.

AEREPO-200055

File "%1" is not a valid instance file; Ignoring it Role: Warning Category: Security Resolution: Verify that file named %1.dat is an expected project. If not, move it to a different directory. If it is, restore the file.

AEREPO-200056

File "%1" is not a valid instance file; Ignoring it Role: Warning Category: Security Resolution: Verify that file named %1.dat is an expected project. If not, move it to a different directory. If it is, restore the file.

AEREPO-200057

Cannot create security policy domain and default rules for domain %1: %2 Role: Warning Category: Security Resolution: Check permission to the domain data directory, verify that the user running administrator has write permission.

AEREPO-200059

Cannot shut down %1, clients have unsaved changes Role: Warning Category: Security Resolution: Request all clients actively modifying the specified instance to close their applications. May shutdown with the force option if clients are unavailable.

AEREPO-200060

Cannot persistent commit history %1 for the instance %2: %3 Role: Warning Category: Security Resolution: Verify that the user running the Administrator server has update rights to the commit history directory and all of its files.

TIBCO Administrator Server Configuration Guide

AEREPO Messages 213

AEREPO-200061

Cannot delete commit history for deleted instance %1: %2 Role: Warning Category: Security Resolution: Verify that the user running the Administrator server has update rights to the commit history directory and all of its files

AEREPO-200063

Cannot load deployment variables due to cause: %1 Role: Warning Category: Security Resolution: Verify that the directory specified by the parameter r e p o . d e p l o y m e n t D i r e c t o r y exists and that the server has read access to the directory and all of its files.

AEREPO-200064

The number of returned ACL by getACL method is supposed to be more than 2 Role: Warning Category: Security Resolution: Verify that security rules exist for all instances.

AEREPO-200065

Read rule for root node is under being deleted Role: Warning Category: Security Resolution: Indicates that someone is trying to access a project that is being deleted. May be safely ignored.

AEREPO-200066

Inconsistency of Commit notification between rename and update Role: Warning Category: Client Resolution: May be safely ignored.

TIBCO Administrator Server Configuration Guide

214

| Appendix D

System Messages

AEREPO-200067

Failing in process Null Ref during handling renamed reference Role: Warning Category: Client Resolution: Verify that client application is working correctly. Generally safe to ignore.

AEREPO-200068

repo.updateSecondaryServerPersistentStore property cannot be set to true when database backend is used Role: Warning Category: Configuration Resolution: Use database configuration to do replication, or switch to file storage if you wish repo secondary servers to maintain independent copies of the server projects.

AEREPO-200069

Administration Domain is not installed Role: Warning Category: Configuration Resolution: Administrator was explicitly installed without a domain. If an administration domain is desired, use TIBCO Domain Utility in the TIBCO Runtime Agent menu to configure an administration domain.

AEREPO-200070

Authorization: mismatch between number of resource %1 and number of statusCodes %2 Role: Warning Category: Security Resolution: Restart the administration server.

AEREPO-200071

Exception in findAllTheRules: %1 Role: Warning Category: Security Resolution: Restart the administration server

TIBCO Administrator Server Configuration Guide

AEREPO Messages 215

AEREPO-200072

AssocKey %1 has reference to empty object %2 Role: Warning Category: Security Resolution: May be safely ignored.

AEREPO-200073

Cannot synchronize security data from the master server. So this server will use locally cached security data which could be out of sync with the master server. Role: Warning Category: Security Resolution: Indicates that master server is unavailable. Verify network connectivity and make sure that the primary server is running. If the primary server is known to be down, this message is expected and can be safely ignored.

AEREPO-300001

Repository server started in load balancing mode Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300002

This server is designated as the master for the LB group %1 Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300003

Global state for the LB group:%1 Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300004

Local state for the LB group:%1 Role: Information

TIBCO Administrator Server Configuration Guide

216

| Appendix D

System Messages

Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300005

Repository server "%1" is starting Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300006

Repository server starting time %1 Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300007

Repository server "%1" is used for character encoding Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300008

Repository server using %1 threads Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300009

Repository server using TIB/Rendezvous Java package version %1 Role: Information Category: Configuration Resolution: Information only, no resolution required.

TIBCO Administrator Server Configuration Guide

AEREPO Messages 217

AEREPO-300010

Security cache for previous authorization result will be refreshed every %1 seconds Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300011

Repository server "%1" is ready. Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300012

Server process specifies debug trace types: "%1" Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300013

Slave servers do not make file log in the load balancing mode. Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300014

Logging to files starting with %1 under the directory %2 Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300015

HAWK Implant enabled with TIB/Hawk AMI version %1 Role: Information Category: Configuration Resolution: Information only, no resolution required.
TIBCO Administrator Server Configuration Guide

218

| Appendix D

System Messages

AEREPO-300016

HAWK Implant disabled Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300017

starting file instance %1 Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300018

starting database instance %1 Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300019

Repository server verifying that no other servers named %1 are up. This may take some time. Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300020

NOTE: SERVER WILL BREAK ANY EXISTING INSTANCE LOCKS Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300021

RVD instance management session on daemon %1, Service %2 Role: Information

TIBCO Administrator Server Configuration Guide

AEREPO Messages 219

Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300022

Created Cm Queue transport for load balancing Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300023

Instance discovery subject is %1 Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300024

Instance management subject is %1 Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300025

Server discovery subject is %1 Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300026

State change subject for load balancing is %1 Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300027

Server global state changed to: %1

TIBCO Administrator Server Configuration Guide

220

| Appendix D

System Messages

Role: Information Category: Server Resolution: Information only, no resolution required.

AEREPO-300028

Server local state changed to: %1 Role: Information Category: Server Resolution: Information only, no resolution required.

AEREPO-300029

Server is stopped by server-based request Role: Information Category: Server Resolution: Information only, no resolution required.

AEREPO-300030

Another server with same name was trying to start; It is now exiting. Role: Information Category: Server Resolution: Information only, no resolution required.

AEREPO-300031

Another server with same name was trying to start as master of the LB group; It is now changing to slave. Role: Information Category: Server Resolution: Information only, no resolution required.

AEREPO-300032

Global state for the LB group:%1 Role: Information Category: Server Resolution: Information only, no resolution required.

TIBCO Administrator Server Configuration Guide

AEREPO Messages 221

AEREPO-300033

Local state for the LB group:%1 Role: Information Category: Server Resolution: Information only, no resolution required.

AEREPO-300034

Shutting down instance %1 Role: Information Category: Server Resolution: Information only, no resolution required.

AEREPO-300035

Cannot shut down %1, clients have unsaved changes Role: Information Category: Server Resolution: Information only, no resolution required.

AEREPO-300036

Logging to the directory %1 by hawk request Role: Information Category: HawkImplant Resolution: Information only, no resolution required.

AEREPO-300037

The server role in the load balancing mode is changed to "master" from "slave" Role: Information Category: HawkImplant Resolution: Information only, no resolution required.

AEREPO-300038

The server role in the load balancing mode is changed to "slave" from "master" Role: Information Category: HawkImplant Resolution: Information only, no resolution required.

TIBCO Administrator Server Configuration Guide

222

| Appendix D

System Messages

AEREPO-300039

Instance %1 stopped by hawk request Role: Information Category: HawkImplant Resolution: Information only, no resolution required.

AEREPO-300040

Client "%1" in the instance "%2" terminated by hawk request Role: Information Category: HawkImplant Resolution: Information only, no resolution required.

AEREPO-300041

RVD hawk communication session on daemon %1, Service %2 Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300042

Instance creation is completed Role: Information Category: CreateInstanceTool Resolution: Information only, no resolution required.

AEREPO-300043

Creating server-based database instance Role: Information Category: CreateInstanceTool Resolution: Information only, no resolution required.

AEREPO-300044

Creating server-based file instance Role: Information Category: CreateInstanceTool

TIBCO Administrator Server Configuration Guide

AEREPO Messages 223

Resolution: Information only, no resolution required.

AEREPO-300045

Creating local file instance Role: Information Category: CreateInstanceTool Resolution: Information only, no resolution required.

AEREPO-300046

Instance listener subject prefix is %1 Role: Information Category: CreateInstanceTool Resolution: Information only, no resolution required.

AEREPO-300047

Instance %1 is ready at: %2 Role: Information Category: CreateInstanceTool Resolution: Information only, no resolution required.

AEREPO-300053

Instance %1 created by user %2 Role: Information Category: Server Resolution: Information only, no resolution required.

AEREPO-300054

Instance %1 copied to instance %2 by user %3 Role: Information Category: Server Resolution: Information only, no resolution required.

AEREPO-300055

Instance %1 deleted by user %2 Role: Information

TIBCO Administrator Server Configuration Guide

224

| Appendix D

System Messages

Category: Server Resolution: Information only, no resolution required.

AEREPO-300056

Instance %1 modified by user %2 Role: Information Category: Server Resolution: Information only, no resolution required.

AEREPO-300057

Security enabled Role: Information Category: Security Resolution: Information only, no resolution required.

AEREPO-300058

Security disabled Role: Information Category: Security Resolution: Information only, no resolution required.

AEREPO-300059

No deployment directory for server %1 Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300060

No deployment variable file for instance %1 Role: Information Category: Server Resolution: Information only, no resolution required.

AEREPO-300061

Starting VC Instance: %1

TIBCO Administrator Server Configuration Guide

AEREPO Messages 225

Role: Information Category: Server Resolution: Information only, no resolution required.

AEREPO-300062

Instance %1 created successfully Role: Information Category: CreateInstanceTool Resolution: Information only, no resolution required.

AEREPO-300063

No Regional subjects prefix will be used for read-operation for the load balancing server Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300064

Regional subject prefix %1 will be used for read-operation for the load balancing server Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300065

This secondary load balancing server will %1 persist data synchronized from master server in its own backend Role: Information Category: Configuration Resolution: Information only, no resolution required.

AEREPO-300066

Dropped %1 Role: Information Category: Mapper

TIBCO Administrator Server Configuration Guide

226

| Appendix D

System Messages

Resolution: Information only, no resolution required.

AEREPO-300067

Succeed in authorization Role: Information Category: AUDIT Resolution: Information only, no resolution required.

AEREPO-300068

Timeout in authorization Role: Information Category: AUDIT Resolution: Information only, no resolution required.

AEREPO-300069

Statement expired Role: Information Category: AUDIT Resolution: Information only, no resolution required.

AEREPO-300070

Other cause of authorization failure %1 Role: Information Category: AUDIT Resolution: Information only, no resolution required.

AEREPO-300071

Security authentication failure Role: Information Category: AUDIT Resolution: Information only, no resolution required.

AEREPO-300072

Invalid user name or password Role: Information

TIBCO Administrator Server Configuration Guide

AEREPO Messages 227

Category: AUDIT Resolution: Information only, no resolution required.

AEREPO-300073

Timeout in authentication Role: Information Category: AUDIT Resolution: Verify that server is working correctly and that the server machine is not overloaded. Retry client application that received the timeout.

AEREPO-300074

Other cause of authentication failure %1 Role: Information Category: AUDIT Resolution: Information only, no resolution required.

AEREPO-300075

Succeed in authentication Role: Information Category: AUDIT Resolution: Information only, no resolution required.

AEREPO-300076

Internal error Role: Information Category: AUDIT Resolution: Information only, no resolution required.

TIBCO Administrator Server Configuration Guide

228

| Appendix D

System Messages

POF Messages
POF-12001: Could not find entity with id %1 of class %2
Role: errorRole Category: Application Description: Resolution:

POF-12002: Could not find entity with name %1 of class %2

Role: errorRole Category: Application Description: Resolution:

POF-12003: Entity with name %1 was locked by %2 at %3

Role: errorRole Category: Application Description: The specified object is locked. You cannot edit the object until the specified owner releases the lock or you break the lock. Breaking the lock will prevent the previous owner's changes from being saved. Resolution: TIBCO Administrator will prompt you for the option to break the lock. If you break the lock, then you can proceed to edit the object.

TIBCO Administrator Server Configuration Guide

POF Messages 229

POF-12004: Could not authenticate user %1

Role: errorRole Category: Application Description: The username and password were not correct. Resolution: Please check the username and password. Make sure the caps-lock key is not inadvertently pressed. Contact your system administrator if you cannot remember the password.

POF-12006: Domain with name %1 already exists

Role: errorRole Category: Application Description: A domain with the name specified already exists. Resolution: Please choose another name for the domain you are creating.

POF-12007: Duplicate %1 with name "%2". Please choose another name.

Role: errorRole Category: Application Description: Cannot create a new user with the same name as an existing user. Resolution: Please choose another name for the new user.

POF-12008: Duplicate %1 with name "%3" with parent "%2". Please choose another name.
Role: errorRole Category: Application Description: Cannot create a new role, application, or application folder with the same name as an existing role, application, or application folder with the same parent role or application folder. Resolution: Please pick a new name for the role or application being saved.

TIBCO Administrator Server Configuration Guide

230

| Appendix D

System Messages

POF-12009: A role name must be specified

Role: errorRole Category: Application Description: The role name field in TIBCO Administrator was empty. Resolution: Please specify a role name.

POF-12010: A user name must be specified

Role: errorRole Category: Application Description: The user name field in TIBCO Administrator was empty. Resolution: Please specify a user name.

POF-12012: Process %1 cannot support more than one deployment

Role: errorRole Category: Application Description: A container in one application was bound to a service in another application. Resolution: TIBCO Administrator should prevent this from ever happening. Contact TIBCO support if this exception is encountered.

POF-12015: Entity store configuration is missing required property %1

Role: errorRole Category: Application Description: Properties in the A d m i n i s t r a t i o n D o m a i n . p r o p e r t i e s or
AuthorizationDomain.properties

are not specified correctly.

Resolution: Please check that the parameters U s e r I D , C r e d e n t i a l and

EntityStoreImplementation

are defined in the property files. If not, then copy

them from another domain.

TIBCO Administrator Server Configuration Guide

POF Messages 231

POF-12016: Can not save your changes because a missing lock for entity %1 indicates another user has broken your lock
Role: errorRole Category: Application Description: While changing an object, another user broke your lock on the object. Resolution: All changes that have been made will be lost and have to be made

again.

POF-12021: Missing connection pool for caching Groups, membership and users
Role: errorRole Category: Application Description: Domain utility failed to configure these parameters when enabling integration with the corporate Repository. Resolution: Please contact TIBCO support.

POF-12023: Please close this browser instance to start new session.

Role: errorRole Category: Application Description: Authentication was configured to require starting a new browser

session before the user can log in again.

Resolution: Please close this browser instance to start new session.

POF-12024: Could not find child object of type %1 in entity %2 of type %3

Role: errorRole Category: Application Description: Expected to find the specified object. Resolution: Please contact TIBCO Support.

TIBCO Administrator Server Configuration Guide

232

| Appendix D

System Messages

POF-12025: Invalid name (URI) specified for an access control list - must have a | in it
Role: errorRole Category: Application Description: This internal error specifies an illegal name for an ACL. Resolution: Contact TIBCO support.

POF-12026: Please associate the machine with a region

Role: errorRole Category: Application Description: The machine being added was not added to a region. Resolution: Contact TIBCO Support

POF-12027: Invalid interval of %1 requested. Interval must be less than the difference(%2) of the current values of FROM_TIME(%3) and TO_TIME(%4)
Role: errorRole Category: Application Description: This internal error specifies an invalid interval. Resolution: Contact TIBCO Support

POF-12028: A name for entity of type %1 must be specified

Role: errorRole Category: Application Description: Name was not specified. Resolution: Please specify a name for the object.

TIBCO Administrator Server Configuration Guide

POF Messages 233

POF-12030: Product version for %1 must be of the form x.x was : %2

Role: errorRole Category: Application Description: The product major and minor version number was not specified. TIBCO Installer should set this attribute properly. Resolution: Please contact TIBCO Support.

POF-12031: Product maintenance version for %1 must be set

Role: errorRole Category: Application Description: The product maintenance version number was not specified. TIBCO Installer should set this attribute properly. Resolution: Please contact TIBCO Support.

POF-12032: Product is missing display name

Role: errorRole Category: Application Description: Poduct is missing display name. TIBCO Installer should set this attribute properly. Resolution: Please contact TIBCO Support.

POF-12033: Short name for product %1 must be set.

Role: errorRole Category: Application Description: Missing short name for product. TIBCO Installer should set this attribute properly. Resolution: Please contact TIBCO Support.

TIBCO Administrator Server Configuration Guide

234

| Appendix D

System Messages

POF-12035: Objects of type %1 must have parent object of type %2: found unexpected parent of type %3
Role: errorRole Category: Application Description: An attempt at saving an object in an inappropriate place in the model was made. Resolution: Please contact TIBCO Support.

POF-12036: Invalid fromTime of %1 requested. fromTime must be between 0 and %2

Role: errorRole Category: Application Description: An inappropriate number of milliseconds was specified for an

interval.
Resolution: Please contact TIBCO Support.

POF-12037: Invalid toTime of %1 requested. toTime must be between 0 and %2

Role: errorRole Category: Application Description: An inappropriate number of milliseconds was specified for an

interval.
Resolution: Please contact TIBCO Support.

POF-12038: Invalid time of day from time %1 to time %2 requested. The difference %3 of the current values of fromTime and toTime must be less than the current interval of %4
Role: errorRole Category: Application Description: An inappropriate number of milliseconds for the schedule interval was specified. The interval must fall between the fromTime and toTime. Resolution: Please contact TIBCO Support.

TIBCO Administrator Server Configuration Guide

POF Messages 235

POF-12039: Invalid time of day %1 was requested. All fire times must be between 0 and %2
Role: errorRole Category: Application Description: An inappropriate number of milliseconds since midnight was specified for a time of day. Resolution: Please contact TIBCO Support.

POF-12040: Missing ContainerConfiguration for ServiceContainerBinding %1

Role: errorRole Category: Application Description: The attempt at saving the application failed because no process was associated with the specified binding. TIBCO Administrator should prevent this from happening. Resolution: Please contact TIBCO Support.

POF-12041: Missing process name in component type %1

Role: errorRole Category: Application Description: TIBCO Installer failed to set a process name for product. Resolution: Please contact TIBCO Support.

POF-12042: ContainerConfiguration %1 cannot have ServiceContainerBindings for ServiceConfiguration %2 that have two different versions(%3,%4) of the Product %5
Role: errorRole Category: Application Description: An attempt was made to have a single process run two different versions of a product. This function is not supported at this time. TIBCO Administrator should prevent this from happening. Resolution: Please contact TIBCO Support.

TIBCO Administrator Server Configuration Guide

236

| Appendix D

System Messages

POF-12043: ContainerConfiguration %1 cannot have ServiceContainerBindings for ServiceConfigurations (%2,%3) that have two different process names(%4,%5) in their Products (%6,%7)
Role: errorRole Category: Application Description: An attempt was made to binding multiple products with different process names to the same process in the model. TIBCO Administrator should prevent this from happening. Resolution: Please contact TIBCO Support.

POF-12044: Product %1 cannot be added to Machine %2 because machine already has Product %3 of same version
Role: errorRole Category: Application Description: Cannot add a product of the same version more than once to the machine. TIBCO Installer should configure the version numbers appropriately. Resolution: Please contact TIBCO Support.

POF-12046: Failed to start fault tolerance: %1

Role: errorRole Category: Application Description: An error was encountered when starting TIBCO Administrator's fault tolerance support. Resolution: Please contact TIBCO support.

TIBCO Administrator Server Configuration Guide

POF Messages 237

POF-12048: Could not find user profile for user: %1

Role: errorRole Category: Application Description: The user profile information does not exist for this user. This should happen automatically if a Corporate Repository is in use. Resolution: Please contact TIBCO Support.

POF-12049: Created user %1 on the fly (Not saved yet)

Role: infoRole Category: Application Description: For information purposes only. Resolution:

POF-12050: Warning getting domain for cookie: %1

Role: warnRole Category: Application Description: For information purposes only. Resolution:

POF-12051: Missing group %1

Role: errorRole Category: Application Description: Missing group found when searching dynamic groups for membership. Resolution: Please contact TIBCO Support.

TIBCO Administrator Server Configuration Guide

238

| Appendix D

System Messages

POF-12052: Failure performing LDAP search: %1

Role: errorRole Category: Application Description: Failure while trying to integrate with the Corporate Repository. Resolution: Make sure the search query is valid.

POF-12053: Could not find method with signature get%1()

Role: errorRole Category: Application Description: Could not find the specified method when trying to substitute the value returned by the method. Resolution: Make sure the substitution variable was specified correctly.

POF-12054: Need to have a method with signature get%1() or methods with signatures get%2Names() and get%3(String)
Role: errorRole Category: Application Description: Could not find the specified iterator method when trying to substitute the value returned by the method. Resolution: Make sure the substitution variable was specified correctly.

POF-12055: Another user broke the lock on entity: %1

Role: warnRole Category: Application Description: Another user decided to override the changes the current lock owner was making. Resolution: Please redo all changes that were made.

TIBCO Administrator Server Configuration Guide

POF Messages 239

POF-12056: ********************************************************************************************
Role: infoRole Category: Initialization Description: For information purposes only. Resolution:

POF-12057: %1 %2 started by %3 running on %4 %5 %6

Role: infoRole Category: Initialization Description: For information purposes only. Resolution:

POF-12058: CLASSPATH=%1
Role: infoRole Category: Initialization Description: For information purposes only. Resolution:

POF-12061: Received %1 event with a %2 attached to it

Role: warnRole Category: Application Description: Resolution: For information purposes only.

TIBCO Administrator Server Configuration Guide

240

| Appendix D

System Messages

POF-12065: User %1 %2
Role: infoRole Category: Application Description: For information purposes only. Resolution:

POF-12066: No action specified. Must have: Alert, Email, and/or Command

Role: infoRole Category: Application Description: Please specify an alert, email and command for the rule. Resolution:

POF-12067: No command specified

Role: infoRole Category: Application Description: Please specify a command for the rule. Resolution:

POF-12068: No recipient specified in Email

Role: infoRole Category: Application Description: Please specify an email recipient for the alert Resolution:

TIBCO Administrator Server Configuration Guide

POF Messages 241

POF-12069: No mail server specified in Email

Role: infoRole Category: Application Description: Please contact TIBCO Support. Resolution:

POF-12070: Starting FaultTolerance for component %1 of type %2

Role: infoRole Category: Initialization Description: For information purposes only. Resolution:

POF-12071: Stopping FaultTolerance for component %1 of type %2

Role: infoRole Category: Initialization Description: For information purposes only. Resolution:

POF-12072: Component %1 of type %2 received fault tolerance action %3

Role: infoRole Category: FaultTolerance Description: For information purposes only. Resolution:

TIBCO Administrator Server Configuration Guide

242

| Appendix D

System Messages

POF-12073: New User

Role: infoRole Category: miscellaneous Description: For information purposes only. Resolution:

POF-12074: New Role

Role: infoRole Category: miscellaneous Description: For information purposes only. Resolution:

POF-12075: Cannot make role "%1" a child or member of role "%2" or a circular dependency would be created.
Role: errorRole Category: Application Description: The role heirarchy is a directed acyclical graph. This means that the same role can appear in many places of the tree of roles presented in TIBCO Administrator. In order to prevent loops when authorizing, loops in the tree of roles are not allowed. Also, Ror containing other roles can create loops which are not allowed either. Resolution: Please change group hierarchy in a Corporate Repository if that has cycles in it. Also, make sure you are not creating a cycle with changes made in the Role Tree tab or Role members tab or a combination of these.

TIBCO Administrator Server Configuration Guide

POF Messages 243

POF-12076: Cannot remove the root role from the role tree.
Role: errorRole Category: Application Description: The root role cannot be removed. Resolution: Authorization in TIBCO Administrator requires a single root role that

cannot be removed.

POF-12077: Management Consoles

Role: infoRole Category: Application Description: For information purposes only. Resolution:

POF-12078: Missing LDAP connection pool for verifying user authentication

Role: errorRole Category: Application Description: TIBCO Domain Utility should configure this pool correctly. Resolution: Please contact TIBCO Support.

POF-12079: Missing LDAP connection pool for synchronizing with a Corporate Repository
Role: errorRole Category: Application Description: TIBCO Domain Utility should configure this pool correctly. Resolution: Please contact TIBCO Support.

TIBCO Administrator Server Configuration Guide

244

| Appendix D

System Messages

POF-12080: Service instance with name %1 already exists or has illegal characters. Please choose another name for the container that is unique and only uses alphanumeric characters, space, _ and -.
Role: errorRole Category: Application Description: Service instance names must be unique within an application. Also, they are used in Hawk Microagent names and therefore have the specified character restrictions. Resolution: Please provide a valid service instance name.

POF-12081: Root role cannot be synchronized with a group. Trying to remove synchronization for a root role is also invalid.
Role: errorRole Category: Application Description: Cannot synchronize the root role with a group in the Corporate Repository. Resolution: Please contact TIBCO Support.

POF-12082: Role with members cannot be converted to a synchronized role. This is only possible, if group being synchronized was its only member.
Role: errorRole Category: Application Description: Cannot have a role with the same name as that of a group being synchronized from the Corporate Repository. Resolution: Please either remove the role in TIBCO Administrator and resynchronize with the Corporate Repository or remove the corresponding group from the Corporate Repository.

TIBCO Administrator Server Configuration Guide

POF Messages 245

POF-12083: This application has a TIBCO Repository instance name "%1" that is identical to the instance name in application "%2". Please choose another instance name.
Role: errorRole Category: Application Description: Every deployed application creates a new TIBCO Repository

instance in the TIBCO Repository Server embedded in TIBCO Administrator.

Resolution:

POF-12084: User %1 is a super user. Cannot be deleted.

Role: errorRole Category: Application Description: Cannot remove users that are super users. Resolution: Please remove the user from the list of super users before removing

the user.

POF-12085: Cannot remove all super users.

Role: errorRole Category: Application Description: There must be at least one super user. Resolution: Please keep at least one super user in the list of users.

POF-12086: Illegal character in TIBCO Repository instance name "%1". Name can only contain alphanumeric characters [a-zA-Z1-9], dash [-] and underscore [_]
Role: errorRole Category: Application Description: Invalid TIBCO Repository instance name. This name will be used in a TIBCO Hawk microagent name so the characters are limited to the specified ones. Resolution: Please use the appropriate characters in the name.

TIBCO Administrator Server Configuration Guide

246

| Appendix D

System Messages

POF-12087: Cannot connect to domain. Please upgrade TIBCO Runtime Agent from version %2 to version %1
Role: errorRole Category: Application Description: The schema of the domain is older than that required for the installed product. Resolution: Please consult product documentation on how to upgrade your

domain.

POF-12088: Cannot connect to domain. Domain was created with TIBCO Runtime Agent version %2 which does allow clients of TIBCO Runtime Agent version %1 or higher
Role: errorRole Category: Application Description: The schema of the domain is newer than the schema required for the installed product. Resolution: Please upgrade to the appropriate product version.

POF-12089: Cannot remove folder with name "%1", please undeploy the following applications first: %2
Role: errorRole Category: Application Description: All applications in the folder specified must be undeployed before the folder can be deleted. Resolution: Please undeploy the applications from the Configuration console before deleting the folder.

TIBCO Administrator Server Configuration Guide

POF Messages 247

POF-12090: Please undeploy application(s): %1 before deleting.

Role: errorRole Category: Application Description: The application must be undeployed before it can be deleted. Resolution: Please undeploy the application from the Configuration console before deleting the application.

POF-12091: Cannot change or set a user property "%1" in Corporate Repositories.

Role: errorRole Category: Application Description: Some properties available from a user profile are synchronized from the Corporate Repository. These values must be changed in the CorporateRepository and not the user profile. Resolution: Please contact TIBCO Support.

POF-12092: Cannot remove a user property "%1" from Corporate Repositories.

Role: errorRole Category: Application Description: Some properties available from a user profile are synchronized from the Corporate Repository. These values must be removed from the C o r p o r a t e R e p o s i t o r y and not from the user profile. Resolution: Please contact TIBCO Support.

TIBCO Administrator Server Configuration Guide

248

| Appendix D

System Messages

POF-12094: Cannot remove "%1", please undeploy the following applications that depend on this object first: %2
Role: errorRole Category: Application Description: This product or container is currently in use by deployed

applications and should not be removed.

Resolution: Please undeploy or redeploy the specified applications without depending on the product or container.

POF-12095: No longer have locks for objects or objects are locked by someone else
Role: errorRole Category: Application Description: While changing an object, another user broke your lock on the object. Resolution: All changes that have been made will be lost and need to be made

again.

POF-12096: TIBCO Repository instance name is invalid. It must start with the characters "%1"
Role: errorRole Category: Application Description: TIBCO Repository instance names must start with the domain name followed by a dash. This ensures the instance name is unique on the network. Resolution: Please change the instance name to start with the characters

specified.

TIBCO Administrator Server Configuration Guide

POF Messages 249

POF-12097: Cannot remove the guest role from the role tree.
Role: errorRole Category: Application Description: The guest role cannot be removed. Resolution: Authorization in TIBCO Administrator requires a guest role that cannot be removed. The guest role is used to support unauthorized access to resources.

POF-12098: User %4 failed to lock object with name %1. Object was locked by %2 at %3
Role: errorRole Category: Application Description: The specified object is locked. You cannot edit the object until the specified owner releases the lock or you break the lock. Breaking the lock will prevent the previous owner's changes from being saved. Resolution: TIBCO Administrator will prompt you with the option to break the lock. If you break the lock, you can proceed to edit the object.

POF-12099: The archive loaded contains data using encoding %1 which is not supported by the TIBCO Administrator that requires the archive encoding to be equivalent to or contained in encoding %2. Please change the value of parameters repo.encoding and tibcoadmin.client.encoding of the .tra file for TIBCO Administator to %3, restart TIBCO Administrator and reload the archive.
Role: errorRole Category: Application Description: Resolution: Each TIBCO Administrator domain can only support archives from a single encoding. Please choose an encoding that contains all the encodings for archives to be deployed.

TIBCO Administrator Server Configuration Guide

250

| Appendix D

System Messages

POF-12100: Number of matching entries exceeds the Limit for searching from Domain. Please specify a more restrictive search pattern.
Role: warnRole Category: Application Description: Resolution: Please narrow down the search pattern.

POF-12101: Role Membership Plug-in descriptor "%1" not found.

Role: errorRole Category: Application Description: Resolution: Please upgrade the domain appropriately to create descriptors for all out-of-box and installed Role Membership Plug-ins.

POF-12102: Cannot uninstall this Role Membership Plug-in since there exists roles for this membership.
Role: infoRole Category: Application Description: Resolution: Role Membership Plug-in cannot be uninstalled unless all the role defined for this membership are deleted.

POF-12103: You may need to migrate the domain to 5.2 release in order to use the 5.2 TRA client, due to the exception: %1
Role: errorRole Category: Application Description: Resolution: TIBCO Administrator Domain can be upgraded by upgrading TRA and TIBCO Administrator or the machine installed with Primary TIBCO Administrator Server.

TIBCO Administrator Server Configuration Guide

POF Messages 251

POF-12104: User %1 cannot delete itself.

Role: errorRole Category: Application Description: Resolution: Other TIBCO Administrators or Super users should be able to delete you as a user. For this operation, remove yourself from the list of users to be deleted.

POF-12105: Cannot remove Role %1 from a group sunchronized parent role %2.
Role: errorRole Category: Application Description: Resolution: This operation is not allowed because group hierarchy of group synchronized roles is governed by the Corporate LDAP.

POF-12106: Cannot remove Role %1 from the root role since it does not have any other parent.
Role: errorRole Category: Application Description: Resolution: This operation is not allowed because it leads to orphan roles.

POF-12107: Deployment name must have a maximum of %1 characters: %2

Role: errorRole Category: Application Description: Resolution: Please pick a shorter unique deployment name.

TIBCO Administrator Server Configuration Guide

252

| Appendix D

System Messages

POF-12108: Authentication Failed: %1

Role: infoRole Category: Application Description: Resolution: Please authenticate correctly as per Plug-in Authentication

requirements.

POF-12109: The credential specified does not conform to the password policy being enforced
Role: errorRole Category: Application Description: The password policy may enforce various constraints on new passwords. The specified password violates one of these constraints. Please check password to find the reason that the password was not accepted. Resolution: Please pick another password.

POF-12110: The user %1 failed to authenticate.

Role: errorRole Category: Application Description: Please see cause for more details. Either an invalid user was trying to authenticate, the password provided was incorrect, or the password has expired and needs to be changed. Resolution: Please pick another password.

POF-12111: Deleting server based project %1.

Role: infoRole Category: Application Description: Cleanup as part of deployment of a locally based project. The server-based instance is being removed. Resolution: This is a normal and expected activity.

TIBCO Administrator Server Configuration Guide

POF Messages 253

POF-12112: The old credential for user %1 was specified incorrectly.

Role: errorRole Category: Application Description: The old password must be specified correctly before a new password

can be set.
Resolution: The user should attempt to change the password again.

POF-12113: This application has a deployment name "%1" that is identical to the deployment name in application "%2". Please choose another name.
Role: errorRole Category: Application Description: Every application must have a unique deployment name. Resolution: The user should change the deployment name.

POF-12114: Cannot add a group synchronized role %1, that has parent groups in LDAP, to the root role.
Role: errorRole Category: Application Description: Only those group-synchronized roles could be added to root role

that do not have parent groups in LDAP. Any group synchronized role could be added to other regular roles though.
Resolution: The user should not attempt to add a group synchronized role to the root role if the group synchronized role has a parent group in LDAP.

TIBCO Administrator Server Configuration Guide

254

| Appendix D

System Messages

POF-12115: Cannot remove a group synchronized role %1, that has no parent groups in LDAP, from the root role.
Role: errorRole Category: Application Description: Group synchronized roles could only be removed from root role if they had parent groups in LDAP. Any group synchronized role could be removed from other regular roles, though. Resolution: The user should not attempt to remove a group synchronized role, that has no parent group in LDAP, from the root role.

POF-12116: A user with same name (%1) exists in LDAP. Creating or renaming this local user will remove the synchronized LDAP user including its security information in TIBCO Administration domain. Do you want to continue?"
Role: warnRole Category: Application Description: A user with same name (%1) exists in LDAP. Creating or renaming

this local user will remove the synchronized LDAP user including its security information in TIBCO Administration domain."
Resolution: Either do not create, name, or rename the local user with that name, or ignore the warning and continue. This will remove the synchronized user including its secuirty information from TIBCO Administration domain.

POF-12117: A local user with same name (%1) exists in TIBCO Administrayion domain. Creating or renaming this synchronized user will remove the local LDAP user including its security information in TIBCO Administration domain. Do you want to continue?"
Role: warnRole Category: Application Description: A local user with same name (%1) exists in the TIBCO Administration domain. Creating or renaming this synchronized user will remove the local LDAP user including its security information in TIBCO Administration domain." Resolution: Either do not create, name, or rename the local user with that name, or renamed, or ignore the warning and continue. This will remove the local user including its security information in TIBCO Administration domain.

TIBCO Administrator Server Configuration Guide

POF Messages 255

POF-12118: Please login using a valid local or an LDAP user.

Role: errorRole Category: Application Description: This domain requires LDAP usernames in a N e t B I O S format, for

exmaple, "ACME_HQ\\jsmith".
Resolution:

POF-12119: A runtime exception is raised by the Role Membership component: % l.

Role: errorRole Category: Application Description: Resolution:

POF-12120: This operation is not allowed on a read-only User object obtained from the User Manager.
Role: errorRole Category: Application Description: Resolution:

TIBCO Administrator Server Configuration Guide

256

| Appendix D

System Messages

POFUTIL Messages
POFUTIL-00001: Domain name must be specified after -domain flag
Role: Error Category: ParseArgs Description: Resolution: After the -domain flag, add the domain name that you wish to use.

POFUTIL-00002: Encryption key must be specified after -encryptKey flag

Role: Error Category: ParseArgs Description: Not supported in 5.2.0 Resolution: After the encryptKey flag, specify the encryption key that you wish

to use.

POFUTIL-00003: Date must be specified after -date flag

Role: Error Category: ParseArgs Description: Resolution: Either remove the date flag, or follow the date flag to specify the date.

Only entities modified after the specified date will be processed.

POFUTIL-00004: user must be specified after -user flag

Role: Error Category: ParseArgs Description: Resolution: After the user flag, specify the administrative user who has authorization to read and write to the security information.

TIBCO Administrator Server Configuration Guide

POFUTIL Messages 257

POFUTIL-00005: Password must be specified after -pw flag

Role: Error Category: ParseArgs Description: Resolution: After the - p w flag, specify the password for the administrative user

specified with the

-user

flag.

POFUTIL-00006: File path must be specified after -file flag

Role: Error Category: ParseArgs Description: Resolution: Specify the fully qualified location of the file that will hold the exported security information.

POFUTIL-00007: Credential must be specified after -cred flag

Role: Error Category: ParseArgs Description: Resolution: Credential file location must be specified after the -cred flag. Either remove this flag or specify the file path and name.

POFUTIL-00010: Could not find expected role {0}

Role: Error Category: ExportDomainSecurity Description: A role that was requested for export does not exist in the domain. Resolution: This is informational. Remove the role from the list of requested roles to avoid seeing the warning message.

TIBCO Administrator Server Configuration Guide

258

| Appendix D

System Messages

POFUTIL-00011: Property element must include the property name

Role: Error Category: ImportDomainSecurity Description: The XML representing the security information was malformed. A property element which should have had both a name and a value did not have a name element. Resolution: Update the XML stanza adding name=....

POFUTIL-00012: Property {0} does not have a value defined

Role: Error Category: ImportDomainSecurity Description: The XML representing the security information was malformed. A property element which should have had both a name and a value did not have a value element. Resolution: Update the XML stanza adding value=....

POFUTIL-00013: Error importing a child of user {0}

Role: Error Category: ImportDomainSecurity Description: Malformed XML describing User Profile information. Resolution: Correct the XML.

POFUTIL-00014: Invalid credential for user {0}

Role: Error Category: ImportDomainSecurity Description: The Password specified for the user was not a valid obfuscated

password.
Resolution: Provide a valid obfuscated password in the XML specifying the password for the listed user.

TIBCO Administrator Server Configuration Guide

POFUTIL Messages 259

POFUTIL-00015: Invalid syntax for Synchronized Group ID of role {0}

Role: Error Category: ImportDomainSecurity Description: Malforned XML Resolution: Correct XML specifying synchronzied group ID for specified role.

POFUTIL-00016: Expected parent missing for role {0}

Role: Error Category: ImportDomainSecurity Description: This is just a warning. A Role was specified with a name in the

format a/b where a was supposed to be its parent. However, no such role exists. It will be implicitly created.
Resolution: Ignore the message or update the XML to explicitly create the parent

role.

POFUTIL-00017: Invalid syntax for Synchronized Group ID of role {0}

Role: Error Category: ImportDomainSecurity Description: Malformed XML Resolution: Correct the xml specifying the synchronized group ID.

POFUTIL-00018: Skipping role:

Role: Error Category: ExportDomainSecurity Description: A problem was encountered processing the specified role, most likely it was not defined in the domain. Resolution: Correct the arguments and rerun.

TIBCO Administrator Server Configuration Guide

260

| Appendix D

System Messages

POFUTIL-00019: Error exporting role: {0} Role: Error Category: ExportDomainSecurity Description: A problem was encountered processing the specified role. Possibly the domain is corrupt. Resolution: Manually correct the exported XML to define the role or delete and recreate it in your domain.

POFUTIL-00020: Duplicate credential specified for user: {0} Role: Error Category: ImportDomainSecurity Description: The new password or other credential exactly matched another

credential already stored for this user.

Resolution: This is informational only.

POFUTIL-00021: Missing argument after flag {0}

Role: Error Category: ParseArgs Description: Specified flag must have an associated value and there is not one. Resolution: Provide the required argument on the command line.

POFUTIL-00022: Invalid key

Role: Error Category: ImportDomainSecurity Description: Resolution:

TIBCO Administrator Server Configuration Guide

POFUTIL Messages 261

POFUTIL-00023: Specified user must have Admin privileges

Role: Error Category: ImportDomainSecurity Description: Resolution:

POFUTIL-00024: Node of [ {0} ] not find! This ACL can not imported.
Role: WRAN Category: ImportDomainSecurity Description: Resolution:

TIBCO Administrator Server Configuration Guide

262

| Appendix D

System Messages

POOL Messages
POOL-12100: Connect failed to address: %1 : %2
Role: errorRole Category: Application Description: Resolution:

POOL-12101: Server not available at address %1

Role: errorRole Category: Application Description: Resolution:

POOL-12102: Timeout getting connection for address %1

Role: errorRole Category: Application Description: Resolution:

POOL-12103: Following potential problems are found in search parameters: %1

Role: warnRole Category: Application Description: Resolution:

TIBCO Administrator Server Configuration Guide

POOL Messages 263

POOL-12104: No matching entries found for %1

Role: warnRole Category: Application Description: Resolution:

POOL-12105: Attributes (%1) not found for %2

Role: warnRole Category: Application Description: Resolution:

POOL-12106: User Search Filter is not specified on any of the search parameter sets
Role: warnRole Category: Application Description: Resolution:

POOL-12107: Duplicate Search parameters sets are found

Role: warnRole Category: Application Description: Resolution:

TIBCO Administrator Server Configuration Guide

264

| Appendix D

System Messages

POOL-12108: Exception while Testing Search Parameters %1: %2

Role: warnRole Category: Application Description: Resolution:

POOL-12109: Corporate LDAP server is throwing Critical Extension Unavailable exception.

Role: errorRole Category: Application Description: Resolution: Narrowing down on the search criteria to return a smaller dataset will help. Otherwise additional indexes created on LDAP server may help avoid this situation.

TIBCO Administrator Server Configuration Guide

PLUGIN Messages 265

PLUGIN Messages
PLUG-12001: The singleton represented by the class %1 generates a circular references itself during construction.
Role: errorRole Category: Application Description: Resolution:

PLUG-12004: A component of the name %1 is already registered.

Role: errorRole Category: Application Description: Resolution:

PLUG-12005: A component of the name %1 could not be found.

Role: errorRole Category: Application Description: Resolution:

PLUG-12006: Unable to instantiate the class %1.

Role: errorRole Category: Application Description: Resolution:

TIBCO Administrator Server Configuration Guide

266

| Appendix D

System Messages

PLUG-12007: Unable to access either the class or its constructor for class %1.
Role: errorRole Category: Application Description: Resolution:

PLUG-12008: Difficult opening the JAR file %1.

Role: errorRole Category: Application Description: Resolution:

PLUG-12009: Plug-in file does not contain the plug-in configuration for: %1.
Role: errorRole Category: Application Description: Resolution:

PLUG-12010: Main class is not found for the plugin JAR %1.
Role: errorRole Category: Application Description: Resolution:

TIBCO Administrator Server Configuration Guide

PLUGIN Messages 267

PLUG-12011: The main class of plugin JAR %1 could not be instantiated because it is abstract or an interface.
Role: errorRole Category: Application Description: Resolution:

PLUG-12012: Unable to access either the class or its constructor for the main class of plugin %1.
Role: errorRole Category: Application Description: Resolution:

PLUG-12013: The main class of plugin JAR %1 does not implement the Plugin interface.
Role: errorRole Category: Application Description: Resolution:

PLUG-12014: The application failed to register its plugins: %1.

Role: errorRole Category: Application Description: Resolution:

TIBCO Administrator Server Configuration Guide

268

| Appendix D

System Messages

PLUG-12015: It is a class and not component factory interface.

Role: errorRole Category: Application Description: Resolution:

PLUG-12016: Be not able to load %1 from the application archive classloader..

Role: errorRole Category: Application Description: Resolution:

TIBCO Administrator Server Configuration Guide

| 269

Index

Symbols
.logOperations parameter 53

Configuring Connection Pool Size for the Database Server 75 creating adapter configuration schema 190 custom schema 191 custom schemas during import 191 customer support xiv

A
adapter schema 190 administration domains multiple 30 spanning subnets 32 argument (command-line) clientvar 92 auto-discovery process 144 TIBCO Hawk 144

D
data storage 91 database storage parameters 50 database domain storage 7 database projects 7 dbType parameter 50 defining a URL 74 defining variables 91 delayForDBStartup parameter 50 deploymentDirectory parameter 62 directory parameter 49 doRefreshCache() 180 doRefreshSecurity()() 181 doShutdownServer() 171 doStartInstance() 179 doStopInstance() 178 doTerminateClient() 182

B
breaking the lock 89

C
cache configuration 82 cache statistics 83 category message 139 standard 139 checkSecurityOnlyOnPolicyManagement parameter 59 clientvar command-line argument 92 clientvar property 92 commitHistoryDirectory parameter 62 commitHistoryFileMaxNumber parameter 62 components, retrieving through TIBCO Hawk 149

E
EHCache 82 enabling SSL on the LDAP server 76 encapsulating locator string components 74 encoding parameter 52

TIBCO Administrator Server Configuration Guide

270

| Index
example exporting, changing, and importing an adapter 188 importing an adapter into an existing repository 188 hawkService parameter 63 HTTP 68 HTTPS 68 URLfile 70

F
file xml import and export 93 file storage parameters 49 file.encoding 45 fileType parameter 49 forceInstanceLocks parameter 45

I
import custom schema 191 instanceNames parameter 45 invoking Microagent methods 145 isSecurityEnabled 59

J G
getcomponents, TIBCO Hawk method 149 getConfig() 160 getConfigProperties() 157 getConnectedClients() 177 getInstanceInfos() 172 getInstanceStatus() 174 getListoflLockedNodes() 176 getLogConfig() 164 getQueueStats() 163 getRvConfig() 159 getSizeofInstance() 175 getStatus() 161 getTraceIds() 166 getVersion() TIBCO Hawk method 148 global variables 91 java.heap.size.initial 64 java.heap.size.max 64 java.thread.stack.size 64 JDBC driver 50 JDBC URL 50

L
LDAP server enabling SSL 76 listing of utilities 94 load balancing 25 parameters 57 load-balanced servers 28, 41 Local Application Data 9 local repository locator string 72 locator string 72, 74 lock 89 locks 45, 89 lockTimeout parameter 45 logDirectory parameter 53 logFilemaxNumber parameter 54 logFileMaxSize parameter 54 logFileNamePrefix parameter 54

H
hawkDaemon parameter 63 hawkImplant parameter 63 hawkMaxThread parameter 63 hawkMicroAgentName parameter 63 hawkNetwork parameter 63
TIBCO Administrator Server Configuration Guide

Index 271

logging levels 54 logging parameters 53 logLevel parameter 54

M
message category 139 message trace description 139 methods 147 Microagent methods 147 minimizeHandshakeInterval parameter 46 multiple administration domains, single subnet 30 multiple load-balanced servers 28 multiple load-balanced servers spanning subnets 41

logging parameters 53 persist commit history 62 password parameter 50 password policy 16 password policy choices 17 persist commit history 62 precedence 74 prefixRegionalSubject parameter 57 project locking 89 projects managed by TIBCO Administrator 91 substitution variables 91 property precedence 74

Q
qThreadCnt parameter 46

O
onContentChange() 167 onCopyInstance() 149 onCreateInstance() 150 onDeleteInstance() 151 one administration domain, multiple load-balanced servers 28 one administration domain, one server in a single subnet 27 onInstanceChange() 156 onModifyInstance() 152 onServerShutdown() 153 onStartInstance() 154 onStopInstance() 155

R
repo.auditFileName 56 repo.auditFileNum 56 repo.auditFileSize 56 repo.checkSecurityOnlyOnPolicyManagement 59 repo.commitHistoryDirectory 62 repo.commitHistoryFileMaxNumber 62 repo.dbType 50 repo.delayForDBStartup 50 repo.deploymentDirectory 62 repo.directory 49 repo.encoding 52 repo.fileType 49 repo.forceInstanceLocks 45 repo.hawkDaemon 63 repo.hawkImplant 63 repo.hawkMaxThread 63 repo.hawkMicroAgentName 63 repo.HawkNetwork 63 repo.hawkService 63 repo.instanceNames 45 repo.isRepoNavigatorEnabled 60
TIBCO Administrator Server Configuration Guide

P
parameter database storage 50 parameters logging 53

272

| Index
repo.isSecurityEnabled 59 repo.jdbcDriver 50 repo.jdbURL 50 repo.lockTimeout 45 repo.logDirectory 53 repo.logFilemaxNumber 54 repo.logFilemaxSize 54 repo.logFileNamePrefix 54 repo.logLevel 54 repo.logOperations 53 repo.master parameter 57 repo.minimizeHandshakeInterval 46 repo.password 50 repo.prefixRegionalSubject 57 repo.qThreadCnt 46 repo.rvDaemon 52 repo.rvNetwork 52 repo.rvService 52 repo.secureGuestPassword 59 repo.secureGuestUsername 59 repo.securePassword 60 repo.secureStatementDuration 60 repo.secureUsername 60 repo.serverHeartbeatInterval 46 repo.serverName 46 repo.serverPassword 46 repo.state parameter 57 repo.updateSecondaryServerPersistentStore 58 repo.username 50 repo.windowsEventLogLogLevel 54 repo.windowsEventLogLogLevel parameter 54 RepoConvert 112 RepoDeleteInstance 119 RepoDiff 120 RepoExport 188 RepoImport 123, 188 RepoPing 116 restrictions on database project repositories 7 rvDaemon parameter 52 rvNetwork parameter 52 rvService parameter 52

S
schema 190, 191 schemas included with TRA 187 secureGuestPassword parameter 59 secureGuestUsername parameter 59 securePassword parameter 60 secureStatementDuration parameter 60 secureUsername parameter 60 security 59 enable server 59 secureStatementDuration 60 server 59 Security Considerations 12 server security 59 security enabled 59 TIBCO Hawk parameters 63 server parameters for TIBCO Rendezvous 52 server security 59 serverHeartbeatInterval parameter 46 serverName parameter 46 serverPassword parameter 46 setLogConfig() 168 setTraceIds() 170 setup tasks 33 spanning subnets 32, 41 starting TIBCO Hawk on UNIX 143 TIBCO Hawk on Windows 143 starting TIBCO Hawk software 143 storage parameters 50 subnets 32 substitution variables 91 support, contacting xiv

T
technical support xiv TIBCO Administrator managing projects 91 user password 60

TIBCO Administrator Server Configuration Guide

Index 273

TIBCO Designer defining variables 91 global variables 91 TIBCO Hawk 144 Microagent methods 147 server parameters 63 starting 143 TIBCO Hawk methods getcomponents 149 getversion() 148 TIBCO Hawk on Windows 143 TIBCO Rendezvous 66 server parameters 52 TIBCO Repository XML format 186 tibco.clientvar.<varname> property 92 TRA included schemas 187 trace message description 139 trace description 139 trace message format 131 traces location 131 troubleshooting 40

X
xml file import and export 93 XML format 186

U
Unicode support 78 updateSecondaryServerPersistentStore parameter 58 URL 72, 74 URLfile accessed via HTTPS 70 user password 60 username parameter 50 using properties file 74 utilities 94

V
variable values 92 variables 91

TIBCO Administrator Server Configuration Guide