TIBCO Hawk Installation and Configuration - TIBCO Product ...

TIBCO Hawk ®Installation and ConfigurationSoftware Release 4.9November 2010

Important InformationSOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDEDOR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITEDADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLEDSOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FORANY OTHER PURPOSE.USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF ALICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSEAGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USERLICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THESOFTWARE (AND WHICH IS DUPLICATED IN LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARELICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATEDIN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMSAND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND ANAGREEMENT TO BE BOUND BY THE SAME.This document contains confidential information that is subject to U.S. and international copyright laws andtreaties. No part of this document may be reproduced in any form without the written authorization of TIBCOSoftware Inc.TIBCO, The Power of Now, TIBCO ActiveMatrix BusinessWorks, TIBCO Hawk, TIBCO Designer, TIBCORendezvous, TIBCO Enterprise Message Service, TIBCO Runtime Agent, TIBCO Administrator, TIBCOActiveEnterprise and TIBCO Repository 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 SunMicrosystems, Inc. in the U.S. and other countries.All other product and company names and marks mentioned in this document are the property of theirrespective owners and are mentioned for identification purposes only.THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALLOPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAMETIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFICOPERATING SYSTEM PLATFORM.THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS ORIMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS.CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BEINCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKEIMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED INTHIS DOCUMENT AT ANY TIME.THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY ORINDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDINGBUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.Copyright © 1996-2010 TIBCO Software Inc. ALL RIGHTS RESERVED.TIBCO Software Inc. Confidential Information

| iiiContentsFigures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ixTables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiPreface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiiiChanges from the Previous Release of this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xivRelated Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvTIBCO Hawk Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvOther TIBCO Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xviThird Party Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xviTypographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiConnecting with TIBCO Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xixHow to Join TIBCOmmunity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xixHow to Access All TIBCO Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xixHow to Contact TIBCO Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xixChapter 1 Overview of the TIBCO Hawk System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1Components of the TIBCO Hawk System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Chapter 2 Installation Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3Installer Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Installation Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Installing TIBCO Hawk over Previous Releases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Universal Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Uninstalling TIBCO Hawk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Product Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Uninstallation Instructions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Chapter 3 Installing on Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9Installation Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Supported Operating Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10User Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Disk Space and Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Installing TIBCO Hawk. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13TIBCO Hawk Installation and Configuration

iv| ContentsInstallation Media. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Installation Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Installation Profile Selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Installation Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Post-Installation Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Reboot the System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Verify the Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17External JRE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Configure Microsoft Windows Services Logon Account (Optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Chapter 4 Installing on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Installation Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Supported Operating Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Installer Privileges . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Disk Space and Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Reconfigure Two-Button Mouse Devices (Solaris Only) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Installing TIBCO Hawk on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Installation Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Installation Profile Selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Installation Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Post-Installation Tasks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Starting TIBCO Hawk Components Automatically at System Boot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Solaris Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32HP-UX Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32AIX Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33LINUX Instructions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Mac OS X Instructions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Chapter 5 Installing on IBM i5/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Installation Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Supported Operating Systems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Preparing for Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Installing TIBCO Hawk on IBM i5/OS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38Starting TIBCO Hawk Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Chapter 6 Configuring TIBCO Hawk Software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Startup Scripts/Wrappers and Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42TIBCO Hawk Display Configuration File (hawkdisplay.cfg) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45TIBCO Hawk Agent Configuration File (hawkagent.cfg) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52TIBCO Hawk Installation and Configuration

Contents| v-M Self . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54-M RuleBaseEngine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61-M AMIService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65-M LogService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66-M TIBProtocolAdapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67-M Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68-M LogfileMicroAgent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68-M CustomMicroAgent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69TIBCO Hawk HMA Configuration File (hawkhma.cfg) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70TIBCO Hawk Event Service Configuration File (hawkevent.cfg) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73Configuring the Event Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Configuring the Event Service with an External Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Creating a TIBCO Hawk Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84Creating a TIBCO Rendezvous Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Default Session Values. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Setting up a TIBCO Rendezvous Daemon Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Chapter 7 Using the Configuration Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .87Configuration Utility Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88General Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Domain Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91HMA Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92Advanced Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Transport Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Primary Transport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95Using TIBCO EMS as the Transport. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97Defaults. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Connecting to TIBCO EMS using SSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100TIBCO Rendezvous Daemon Session Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102AMI Rendezvous Session Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102TIBCO Hawk Display Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Defaults. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106TIBCO Hawk Agent Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Configuration Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111MicroAgent Plugins. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111TIBCO Hawk Installation and Configuration

vi| ContentsLogfile Microagent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Heartbeat. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112TIBCO Hawk Event Service Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Agent Dead Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Event Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114AMI Rendezvous Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Database Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114Fault Tolerance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Logging File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Disabling and Enabling the Event Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117Chapter 8 Using the TIBCO Hawk Messaging Microagent . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120Configuration File Elements and Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Specifying Field Names in Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133Chapter 9 Using TIBCO Hawk Across Nets or Subnets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Agents and the Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136Configuring for Network Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Configuring Hawk Rendezvous Subjects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Monitoring TIBCO Hawk Agents Using TIBCO Rendezvous and TIBCO EMS . . . . . . . . . . . . . . . . . . . . . . 138Routing TIBCO Hawk Messages with EMS server Across Networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139Setting up Network Communication on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Routing Daemon Configuration for UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140Setting Up Network Communication in Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Installing a Routing Daemon as a Microsoft Windows Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141Starting the Routing Daemon Service Automatically in Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . 141Making TIBCO Hawk Services Depend on the Routing Daemon Microsoft Windows Service . . . . . . . . . . 142Using the TIBCO Hawk Display over a Dial-up Network Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Establishing a Dial-up Connection in UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Establishing a Dial-up Connection in Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Chapter 10 TIBCO Hawk Sample Rulebases and Applications . . . . . . . . . . . . . . . . . . . . . . . . 147Using the Sample TIBCO Hawk Rulebases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148Using the TIBCO Hawk Sample Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149The Sample AMI API Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151TIBCO Hawk AMI C API Sample Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151TIBCO Hawk AMI C++ API Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152TIBCO Hawk AMI Java API Sample Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153TIBCO Hawk Installation and Configuration

viii| ContentsCode Page Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203TIBCO Hawk Installation and Configuration

Figures| ixFiguresFigure 1 General Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Figure 2 Advanced Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Figure 3 Transport Configuration using TIBCO Rendezvous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96Figure 4 Transport Configuration using TIBCO Enterprise Message Service . . . . . . . . . . . . . . . . . . . . . . . . 97Figure 5 Add AMI Rendezvous Session. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103Figure 6 Display Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105Figure 7 Agent Configuration Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107Figure 8 Rulebase Configuration Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110Figure 9 TIBCO Hawk Event Service Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Figure 10 Sample Routing Daemon Configuration for TIBCO Hawk Messaging . . . . . . . . . . . . . . . . . . . . . . 137TIBCO Hawk Installation and Configuration

x| FiguresTIBCO Hawk Installation and Configuration

Tables| xiTablesTable 1 General Typographical Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviiTable 2 Supported Microsoft Windows Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Table 3 Installation Package Filenames for Microsoft Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Table 4 Supported UNIX Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Table 5 Required Disk Space in the Temp and Installation Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Table 6 UNIX Installation tar Package Filenames. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Table 7 TIBCO Hawk Components, Startup Scripts/Wrappers, and Configuration Files . . . . . . . . . . . . . . 42Table 8 hawkdisplay.cfg Functions and Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Table 9 hawkagent.cfg Modules and Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52Table 10 -M Self Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54Table 11 -M RuleBaseEngine Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Table 12 -M TIBProtocolAdapter Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Table 13 -M LogfileMicroAgent Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Table 14 -M CustomMicroAgent Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69Table 15 hawkhma.cfg Functions and Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70Table 16 hawkevent.cfg Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74Table 17 Database Configuration Value: Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Table 18 Database Configuration Value: Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Table 19 TIBHAWK_AMI Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121Table 20 microagent Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124Table 21 method Element Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127Table 22 inputParameter Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129Table 23 valueChoices Element Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Table 24 legalValueChoices Element Attribute. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130Table 25 constantParameter Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131Table 26 outputParameter Element Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Table 27 Access Control File Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161Table 28 TIBCO_HOME Files and Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190TIBCO Hawk Installation and Configuration

xii| TablesTable 29 TIBCO HAWK_HOME Files and Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191Table 30 CONFIG_FOLDER Files and Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Table 31 Code Page Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196TIBCO Hawk Installation and Configuration

| xiiiPrefaceThis software may be available on multiple operating systems. However, notall operating system platforms for a specific software version are released at thesame time. Please see the readme file for the availability of this softwareversion on a specific operating system platform.This manual covers the installation of the TIBCO Hawk ® software on MicrosoftWindows 2003, Microsoft Windows XP, Microsoft Windows Vista, Solaris, HP-UX,AIX, UNIX, Linux, and i5/OS. Custom configuration is also covered in thismanual.This manual assumes you are familiar with TIBCO Rendezvous architecture andthe concepts of system monitoring.Topics• Changes from the Previous Release of this Guide, page xiv• Related Documentation, page xv• Typographical Conventions, page xvii• Connecting with TIBCO Resources, page xixTIBCO Hawk Installation and Configuration

xiv Changes from the Previous Release of this Guide|Changes from the Previous Release of this GuideThis section itemizes the major changes from the previous release of this guide.• A new chapter on how to configure the TIBCO Hawk Java Virtual MachineMicroAgent, TIBCO Hawk Common Logging Publisher MicroAgent, andTIBCO Hawk AMXHost MicroAgent Plug-ins, is added. For details, refer toChapter 12, Configuring Plugins and Adapters.• TIBCO Hawk Configuration Utility provides a new option Advanced >Custom Microagent that allows you to load the microagents selectively. Thecustom microagent configuration module deals with the -timeout commandline option which relates to the timeout value. For details, refer to Chapter 6,Configuring TIBCO Hawk Software.TIBCO Hawk Installation and Configuration

Preface| xvRelated DocumentationThis section lists documentation resources you may find useful.TIBCO Hawk DocumentationThe following documents form the TIBCO Hawk documentation set:• TIBCO Hawk Installation and Configuration Read this book first. It containsstep-by-step instructions for installing TIBCO Hawk software on variousoperating system platforms. It also describes how to configure the softwarefor specific applications, once it is installed. An installation FAQ is included.• TIBCO Hawk Administrator’s Guide This manual includes basic descriptions ofTIBCO Hawk concepts, instructions for using TIBCO Hawk Display,monitoring strategies with examples, a comprehensive FAQ, and a glossary.All books in the documentation set refer to features explained in this book.• TIBCO Hawk Plug-in for TIBCO Administrator Contains detailed descriptionsof the TIBCO Hawk plug-ins accessed via TIBCO Administrator.• TIBCO Hawk Programmer’s Guide All programmers should read this manual.It covers the AMI protocol, AMI messages, the AMI Workbench developmenttool, and the TIBCO Hawk security framework and its classes. Programmersshould then refer to the appropriate language reference for the AMI API. TheTIBCO Hawk Application Management Interface (AMI) exposes internalapplication methods to TIBCO Hawk.• TIBCO Hawk AMI C Reference Contains detailed descriptions of each datatypeand function in the TIBCO Hawk C AMI API.• TIBCO Hawk AMI C++ Reference Contains detailed descriptions of eachdatatype and function in the TIBCO Hawk C++ AMI API.• TIBCO Hawk AMI Java Reference Contains detailed descriptions of each classand method in the TIBCO Hawk Java AMI API.• TIBCO Hawk Console API Reference Contains detailed descriptions of eachclass and method in the TIBCO Hawk Console API, a set of Java interfacesthat allow you to manage and interact with TIBCO Hawk agents and monitoralerts generated by these agents.• TIBCO Hawk Configuration Object API Reference Contains detailed descriptionsof each class and method in the TIBCO Hawk Configuration Object API.• TIBCO Hawk Methods Reference A reference to the microagents and methodsused by a TIBCO Hawk Agent for system and application monitoring.TIBCO Hawk Installation and Configuration

xvi| Related Documentation • TIBCO Hawk HTTP Adapter User’s Guide Contains information aboutperforming discovery, monitoring of agent status, monitoring of agent alerts,method invocation, method subscription, and many more activities on TIBCOHawk and third-party products.• TIBCO Hawk Enterprise Message Service Administrator Plug-in MicroagentReference Contains details about the microagent methods that are used toadminister and monitor the TIBCO Enterprise Message Service server.• TIBCO Hawk Release Notes Read the release notes for a list of new and changedfeatures. This document also contains lists of known issues and closed issuesfor this release.Other TIBCO Product DocumentationYou may find it useful to read the documentation for the following TIBCOproducts:• TIBCO Rendezvous ®— TIBCO Rendezvous Concepts— TIBCO Rendezvous Administration— TIBCO Rendezvous Configuration Tools• TIBCO Enterprise Message Service— TIBCO Enterprise Message Service Installation— TIBCO Enterprise Message Service User’s Guide• TIBCO Administator— TIBCO Administrator Installation GuideThird Party DocumentationYou may find the following third-party documentation useful.• The Java Language Specification by Gosling, Joy, and SteeleTIBCO Hawk Installation and Configuration

Preface| xviiTypographical ConventionsThe following typographical conventions are used in this manual.Table 1 General Typographical ConventionsConventionTIBCO_HOMECONFIG_FOLDERHAWK_HOMEcode fontbold code fontUseMany TIBCO products CAN be installed within the same directory. Thisdirectory is referenced in documentation as TIBCO_HOME. The value ofTIBCO_HOME depends on the operating system. For example, on Windowssystems, the default value is C:\tibco.Incompatible products and multiple instances of the same product should beinstalled into different installation environments.A TIBCO configuration folder stores configuration data generated by TIBCOproducts. Configuration data can include sample scripts, session data,configured binaries, logs, and so on. This folder is referenced in documentationas CONFIG_FOLDER.TIBCO Hawk installs into a directory within . This directory isreferenced in documentation as HAWK_HOME. The value of HAWK_HOMEdepends on the operating system. For example on Windows systems, thedefault value is C:\tibco\hawk\4.9.Code font identifies commands, code examples, filenames, pathnames, andoutput displayed in a command window. For example:Use MyCommand to start the foo process.Bold code font is used in the following ways:• In procedures, to indicate what a user types. For example: Type admin.• In large code samples, to indicate the parts of the sample that are ofparticular interest.• In command syntax, to indicate the default parameter for a command. Forexample, if no parameter is specified, MyCommand is enabled:MyCommand [enable | disable]TIBCO Hawk Installation and Configuration

xviii Typographical Conventions|Table 1 General Typographical Conventions (Cont’d)Conventionitalic fontKey combinationsUseItalic font is used in the following ways:• To indicate a document title. For example: See TIBCO BusinessWorksConcepts.• To introduce new terms For example: A portal page may contain severalportlets. Portlets are mini-applications that run in a portal.• To indicate a variable in a command or code syntax that you must replace.For example: MyCommand pathnameKey name separated by a plus sign indicate keys pressed simultaneously. Forexample: Ctrl+C.Key names separated by a comma and space indicate keys pressed one afterthe other. For example: Esc, Ctrl+Q.The note icon indicates information that is of special interest or importance, forexample, an additional action required only in certain circumstances.The tip icon indicates an idea that could be useful, for example, a way to applythe 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 Hawk Installation and Configuration

Preface| xixConnecting with TIBCO ResourcesHow to Join TIBCOmmunityTIBCOmmunity is an online destinaton for TIBCO customers, partners, andresident experts—a place to share and access the collective experience of theTIBCO community. TIBCOmmunity offers forums, blogs, and access to a varietyof resources. To register, go to http://www.tibcommunity.com.How to Access All TIBCO DocumentationAfter you join TIBCOmmunity, you can access the documentation for allsupported product versions here:http://docs.tibco.com/TibcoDocHow to Contact TIBCO SupportFor comments or problems with this manual or the software it addresses, pleasecontact TIBCO Support as follows.• For an overview of TIBCO Support, and information about getting startedwith 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.comEntry to this site requires a user name and password. If you do not have a username, you can request one.TIBCO Hawk Installation and Configuration

xx Connecting with TIBCO Resources|TIBCO Hawk Installation and Configuration

| 1Chapter 1Overview of the TIBCO Hawk SystemThis chapter gives a basic overview of the TIBCO Hawk monitoring system, itscomponents, and the components supported on the various platforms. Not allcomponents run on all platforms, so determine what is supported on your systembefore beginning installation and configuration.This book provides instructions for installing the TIBCO Hawk software on eachsoftware platform, as well as how to configure the software for specificapplications after installation.Topics• Components of the TIBCO Hawk System, page 2TIBCO Hawk Installation and Configuration

2 Chapter 1 Overview of the TIBCO Hawk System|Components of the TIBCO Hawk SystemThe TIBCO Hawk monitoring system consists of the following main softwarecomponents.TIBCO Hawk AgentA TIBCO Hawk agent is an autonomous process that resides on each computerand monitors systems and applications on that computer. Agents runindependently of the TIBCO Hawk Display.Agents operate autonomously and are active whenever the operating system theymonitor is active. Agents use sets of rules, called rulebases, to configure systemmanagement, status, and automation tasks.A TIBCO Hawk agent must be installed on each computer you wish to monitor.TIBCO Hawk MicroagentA TIBCO Hawk Microagent (HMA) is a partner process to the TIBCO Hawk agentand provides the local agent with methods for monitoring the host operatingsystem.Like the agent, a TIBCO Hawk Microagent is generally installed on eachcomputer you wish to monitor.TIBCO Hawk Display ProgramThe TIBCO Hawk Display program is used by system administrators to viewnetwork health and to create rulebases (sets of rules that automate monitoringactivities).A TIBCO Hawk Display should be installed on any computers you wish to use formonitoring the network or for building rulebases.TIBCO Hawk Event ServiceThe TIBCO Hawk Event Service is a process that records TIBCO Hawk alerts andchanges in agent status. When communication with an agent is lost, the EventService can invoke a user-provided script. Alerts and notifications can berecorded to log files or a database.Typically, the TIBCO Hawk Event Service is installed on a minimal number ofcomputers in the network.TIBCO Hawk Installation and Configuration

| 3Chapter 2Installation OverviewThis chapter provides an overview of the installer program.Appendix C, TIBCO Hawk Directories and Files, contains a complete list of the filesand folders installed for the various platforms.Installing TIBCO Hawk on Microsoft Windows updates the system path toinclude TIBCO Rendezvous 8.3. If you have TIBCO applications installed that useJava, and if those applications are using the TIBCO Rendezvous bundled in TRA5.1.x (instead of a separately installed TIBCO Rendezvous), the applications willnot be able to start the TIBCO Rendezvous daemon, rvd.exe, after you installTIBCO Hawk.To allow the previous TIBCO applications to start rvd.exe again, remove theTIBCO Rendezvous 8.3 directory from the system path (for example,c:\tibco\tibrv\bin). This will not affect the operation of TIBCO Hawk.TIBCO applications that use Java include TIBCO Adapter 4.x, TIBCO Designer4.x, TIBCO ActiveMatrix BusinessWorks 5.x, and others.Topics• Installer Overview, page 4• Uninstalling TIBCO Hawk, page 6TIBCO Hawk Installation and Configuration

4 Chapter 2 Installation Overview|Installer OverviewInstallation DirectoryIf this is the first TIBCO software product you are installing on the system, youcan specify the installation directory where TIBCO Hawk will be installed. OnMicrosoft Windows, the default installation directory is C:\tibco. On UNIX, thedefault installation directory is /opt/tibco.If you already have a TIBCO ActiveEnterprise 5.x product on your machine, youcan install TIBCO Hawk on any other specified location of your choice other thanthe default location.install-pathThe directory into which you install TIBCO Hawk is referred to in thisdocumentation as install-path.For example, if you accept the default installation path on Microsoft Windows,install-path is C:\tibco\hawk\.config-pathThe directory CONFIG_FOLDER is the folder where all the configuration files ofTIBCO Hawk are located.The default config folder for TIBCO Hawk isCONFIG_FOLDER/tibco/cfgmgmt/hawk.If the plugin folder does not exist under CONFIG_FOLDER/tibco/cfgmgmt/hawk,you need to create it.Installing TIBCO Hawk over Previous ReleasesIf TIBCO Hawk 4.9 is installed over existing TIBCO Hawk installation, thepreviously installed Windows services will be replaced by the services of the newinstallation.You do not need to uninstall the previous or current version of TIBCO Hawk onthe system before installing the new version.The new version of TIBCO Hawk Universal Installer now does not detect thepreviously installed versions of the product. However, it enables you to install theproduct into multiple TIBCO homes on the same machine.See Uninstalling TIBCO Hawk on page 6.TIBCO Hawk Installation and Configuration

Installer Overview| 5Universal InstallerUniversal Installer enables TIBCO Hawk 4.9 to be installed in multipleTIBCO_HOME. During installation, you can select the existing TIBCO_HOME orcreate a new TIBCO_HOME. If the existing TIBCO_HOME is selected, it may haveother products installed including TIBCO Hawk. However, incase of apre-installed Hawk installation in the TIBCO_HOME, the existing installation will:• Replace, if the same version (major, minor) is installed.• Upgrade to the latest version, if the patch version is latest.• Add, incase of newer major or minor version.The installer is responsible to create and setup directories under HAWK_HOME/4.9.All the files under HAWK_HOME/4.9 should not be modified by any othercomponent except the installer. An installation properties file that includessettings required for runtime is placed in the installation directory.Installation Property FileDuring the installation, the installer creates or updates the properties file namedinstall.properties under the installation directory. This file contains thesettings that will be used by TIBCO Hawk runtime modules.Only Windows installation uses this file to replace the registry entries setup by theprevious version on the installer.TIBCO Hawk Installation and Configuration

6 Chapter 2 Installation Overview|Uninstalling TIBCO HawkThe uninstaller removes all files that were installed as a part of TIBCO Hawkinstallation, even if those files were modified by the user or the application. Filesthat were created by the user are not deleted or modified.Make sure you have a backup of user-modified files before proceeding with theuninstallation.Product DependenciesTIBCO Designer (only version 2.x) and TIBCO Runtime Agent (TRA) aredependent on TIBCO Hawk being present on the machine.When multiple products like TIBCO Runtime Agent 5.7 and TIBCO Hawk 4.9 areinstalled under the same TIBCO_HOME, there is only one uninstaller for both underTIBCO_HOME_uninstall.• Uninstall TIBCO Hawk (TIBCO_HOME/_uninstall).If both TRA and TIBCO Hawk are selected for uninstallation, TIBCO Hawk willbe uninstalled first followed by TIBCO Runtime Agent .If you have TIBCO Designer or TRA installed on your machine and you want touninstall only TIBCO Hawk, uninstall them in the following order:1. Uninstall TIBCO Runtime Agent (tra-install-path\version\_uninst) and any ofits product dependencies.2. Uninstall TIBCO Hawk (TIBCO_HOME/_uninstall).If you do not have TIBCO Designer or TRA installed on your machine, you canuninstall TIBCO Hawk without prerequisite.Uninstallation InstructionsMicrosoft WindowsUninstall TIBCO Hawk using one of the following methods:• Use Add/Remove Programs from the Control Panel.• Navigate to the _uninstall directory located in install-path and invoke theuniversal_uninstall.exe program.TIBCO Hawk Installation and Configuration

Uninstalling TIBCO Hawk| 7UNIX SystemsUninstall TIBCO Hawkby navigating to the _uninst directory located inuniversal_uninstall.bin program.IBM i5 SystemsDLTLICPGM LICPGM(1TIBHK1)This will uninstall directory path /usr/tibco/hawk/4.9 and library TIBHAWK.TIBCO Hawk Installation and Configuration

8 Chapter 2 Installation Overview|TIBCO Hawk Installation and Configuration

| 9Chapter 3Installing on Microsoft WindowsThis chapter explains how to install and uninstall TIBCO Hawk on computersrunning the Microsoft Windows 2003, 2008, or XP operating system. Informationin this chapter applies to all three platforms unless otherwise noted.Topics• Installation Prerequisites, page 10• Installing TIBCO Hawk, page 13• Post-Installation Tasks, page 17TIBCO Hawk Installation and Configuration

10 Chapter 3 Installing on Microsoft Windows|Installation PrerequisitesRead this section before you start installation.Supported Operating SystemsThe following tables lists the supported Microsoft Windows platforms:Table 2 Supported Microsoft Windows PlatformsOSMicrosoft Windows 7Microsoft Windows XPHardwarex86(32-bit and 64-bit)Microsoft Windows VistaMicrosoft Windows 2003 ServerMicrosoft Windows 2008 ServerMicrosoft Windows 2008 Server R2x86 (64-bit)User PrivilegesYou must have administrator privileges to install TIBCO Hawk. If you do not, theinstaller will exit. You must then log out of the system and log in as a user withadministrator privileges.Installing to a Networked DriveIf you intend to install the product onto a networked drive, you must havepermissions to write to that drive.If you do not know how to do this, go to the machine so you can install locally, orconsult Microsoft Windows online help.Disk Space and MemoryThis section lists the minimum free disk space and memory required for eachplatform.TIBCO Hawk Installation and Configuration

Installation Prerequisites| 11During installation, the entire package is extracted into a temporary directory,typically one of the following:• SystemDrive:\Temp• SystemDrive:\Documents & Settings\user_name\Local Settings\TempBefore actually installing the files, the installer calculates the disk space that theselected components will require in the installation directory. The installer willproceed only if sufficient free disk space is available in the installation directory.If some of the required disk space is taken by another process during installation,the installer may fail and display a failure message.Temp DirectoryAt least 150 MB free space is required in the temp directory.Installation DirectoryAt least 150 MB free space is required in the TIBCO Hawk installation directory.RAMAll platforms require at least 512 MB RAM.SoftwareThe following software is required as indicated on the target machine.TIBCO Software• TIBCO Rendezvous 8.1.1 or above is required, with any available patches.If you have already installed TIBCO Rendezvous software on a network-widebasis, you will not need additional TIBCO Rendezvous licenses unless youwill be running TIBCO Rendezvous Routing Daemon (RVRD) processes on aparticular machine. In this case, you need a valid RVRD license in thetibrv.tkt file for that machine.During installation, TIBCO Rendezvous is automatically installed if notpresent. Any earlier version of TIBCO Rendezvous will be upgraded to theversion 8.3.TIBCO Rendezvous is used for inter-process communication even if TIBCOEnterprise Message Service (EMS) is chosen as the primary transport.• (Optional) TIBCO Enterprise Message Service 5.1.5 and 6.0.0.TIBCO Hawk Installation and Configuration

12 Chapter 3 Installing on Microsoft Windows|IF you plan to use TIBCO EMS as the primary messaging transport, at leastone EMS server must be installed on the network and you must select toinstall the TIBCO EMS Java client during installation on every machinerunning TIBCO Hawk Agent and TIBCO Hawk Console applications.• (Optional) TIBCO Administrator 5.4.0, 5.6.1• (Optional) TIBCO Runtime Agent 5.5.4, 5.6.2If you plan to use any Hawk plug-ins, TIBCO Administrator and TIBCORuntime Agent are required.JRETIBCO Hawk bundles Java Runtime Environment (JRE) version 1.6 or above,with any available patches, on the target machine. It is not a pre-requisite asduring the installation process, you can uncheck the JRE checkbox in the HawkComponent, if JRE is already installed on your machine.TIBCO Hawk Installation and Configuration

Installing TIBCO Hawk| 13Installing TIBCO HawkBefore you begin installation, close all open TIBCO programs (including allTIBCO Rendezvous processes). If any errors appear during installation, consultAppendix B, Troubleshooting, page 179, for possible solutions.Installation MediaYou can either download the TIBCO Hawk installation package or install thecomponents from a CD.Installation PackagesThe following table lists the installation packagesTable 3 Installation Package Filenames for Microsoft WindowsOSMicrosoft Windows XPMicrosoft Windows 2003 ServerMicrosoft Windows 2008 Server(32-bit)Microsoft Windows XPMicrosoft Windows 2003 ServerMicrosoft Windows 2008 Server(64-bit)Package FilenameTIB_hawk__win_x86_vc8.zipTIB_hawk__win_x86_64_vc8.zipFor developers using Visual Studio 2005.Installation Profile SelectionDuring installation, you can choose from the following installation profiles.• Hawk Agent- This installation profile installs only Hawk Agent relatedcomponents.• Hawk Components- This installation profile installs all Hawk components.• Hawk Display- This installation profile installs only Hawk Display.• Hawk SDK- This installation profile installs only Hawk development tools tobuild the microagent, AMI, or the console application.TIBCO Hawk Installation and Configuration

14 Chapter 3 Installing on Microsoft Windows|The following sections discuss the different modes of installing TIBCO Hawk.Installation ModesThe installer allows you to install in different modes. Each mode is supported onall platforms.• GUI mode allows you to select which components to install, where to installthem, and so on. GUI mode is the installer’s default mode.• Console mode allows you to run the installer from the command line andallows you to select which components to install.• Silent mode installs using values in .silent file. Silent mode installs in consolemode without prompting you for input. It installs using either the defaultsettings or a response file that was saved during an earlier installation.You can use any of the following options to install TIBCO Hawk:• Install Using GUI, page 28• Install Using Console, page 28• Install in Silent Mode, page 28These options and the instructions for installing TIBCO Hawk are provided in thefollowing sections. The following examples use the 32-bit installation packageMicrosoft Windows.Install Using GUIGUI mode performs the installation in an interactive graphical interface. Theinstaller prompts you for values specific to your environment.To install, doubleclick the icon namedTIBCOUniversalInstaller.exe.Install Using ConsoleConsole mode allows you to install the software from a Microsoft Windowscommand window. The installer prompts you for values. When installing inconsole mode you move through the installation process as shown:• Enter moves forward in the installer.• 2 returns to the previous screen.• 3 cancels the installer and exits the installation or uninstallation.• 4 redisplays the current screen.TIBCO Hawk Installation and Configuration

Installing TIBCO Hawk| 15To install from a Microsoft Windows command window, type:TIBCOUniversalInstaller -consoleInstall in Silent ModeThe following procedure explains how to install a TIBCO Hawk product in silentmode. It installs TIBCO Hawk using default values. TheTIBCOUniversalInstaller.silent file is packaged in the directory thatcontains the universal installer. You must edit the file with information for yourenvironment before launching the silent installation. The file includes commentsthat describe the installation properties you can set.While you can use the TIBCOUniversalInstaller.silent file, it is a goodpractice to copy the file to a different name and edit that file for the silent install.If errors occur during installation, they will be listed in the installation log file (seethe User_Home/.TIBCO directory).1. Open the physical media or download the TIBCO Hawk product package.2. Extract the TIBCO Hawk product archive file to a temporary directory.3. Using a console window, navigate to the temporary directory that contains theuniversal installer.4. Copy the TIBCOUniversalInstaller.silent file and rename the copy.5. Using a text editor, open the copied file and update the install location, andfeatures to install.6. Run the installer using this command line:TIBCOUniversalInstaller.exe -silentIf .silent file is not named TIBCOUniversalInstaller.silent then thecommand to call silent installation is TIBCOUniversalInstaller.exe -silent-V responseFile="" where is theabsolute directory path and file name to the .silent file.A line similar to the following is written to the installer log file wheninstallation completes:... Install, com.tibco.installer.util.TIBCOInstaller,dbg.Debug, Executing Event:::OnEndInstallNew in .silent fileThe following elements can be set to "true" or "false" in the .silent file for installingyour choice of components.TIBCO Hawk Installation and Configuration

16 Chapter 3 Installing on Microsoft Windows|• true• true• true• true• true• true• true• true• trueTIBCO Hawk Installation and Configuration

Post-Installation Tasks| 17Post-Installation TasksAfter the installation program has finished, it automatically starts the TIBCOHawk configuration utility, described in Chapter 7, Using the ConfigurationUtility.Before using the configuration utility, perform the following post-installationtasks as noted.Reboot the SystemIf you upgraded to TIBCO Rendezvous 8.1.1 during installation, reboot thesystem now.Verify the InstallationTo verify the installation, check that all directories and files have been addedcorrectly. For details, see Appendix C, TIBCO Hawk Directories and Files,page 189.External JREFor JVM, CLEvent, and AMXHost microagents: If you have specified externalJRE 1.6.0 when installing TIBCO Hawk, then tools.jar in the .hma file mustpoint to a JDK installation location.If you have installed JRE 1.6.0 from the TIBCO Hawk 4.9 installer, then tool.jaris present under the lib folder.Configure Microsoft Windows Services Logon Account (Optional)The TIBCO Hawk software components (TIBCO Hawk agent, HMA, and TIBCOHawk Event Service) are installed as Microsoft Windows services. The MicrosoftWindows services run independently of any logged-on user and, therefore,require a Microsoft Windows user account, under which the service can log onand run.Windows services must be in a running state from the latest installation, if youinstall TIBCO Hawk into multiple TIBCO_HOME on a single machine. Also, thetibhawkconfig utility from all the installations will use the same configurations.TIBCO Hawk Installation and Configuration

18 Chapter 3 Installing on Microsoft Windows|By default, the installation program configures the TIBCO Hawk MicrosoftWindows services to use the built-in system account. This is the account used bythe majority of Microsoft Windows services. If you don’t want to use the systemaccount, you must do the following:a. Set up the Administrator User Account.b. Give the Administrative User the "Log On as Service" Privilege.c. Change the Logon Account for TIBCO Hawk Windows Services.These instructions follow.Task A Set up the Administrator User AccountYou can use an existing user account or create a new one under which to run theTIBCO Hawk services. If you want to use an existing account that doesn’t alreadyhave administrator privileges, you must assign administrative privileges to it.These steps may differ on other Windows Operating System, hence refer toWindows OS Guide for details.The following steps allow you to set up the administrator account on Windows:1. Click Start>Administrative Tools>Computer Management>SystemTools>Local Users and Groups.— On Windows XP, click Start>Programs>Administrative Tools>UserManager.— On Windows 7, click Start>Control Panel>User Accounts orStart>Control Panel>Administrative Tools>ComputerManagement>System Tools>Local Users and Groups.— On Windows 2008 R2, click Start>Control Panel>User Accounts orStart>Control Panel>Administrative Tools>ComputerManagement>System Tools>Local Users and Groups.2. If you are adding administrator privileges to an existing account, skip tostep 3. If you are creating a new user to be the administrator, proceed asfollows:a. Choose the User>New User menu item. You see the New User dialog.b. Complete the New User dialog and click OK to return to the UserManager window. (Refer to the Windows documentation for help on thefields required by the New User dialog.)TIBCO Hawk Installation and Configuration

Post-Installation Tasks| 193. In the lower half of the User Manager window, double-click theAdministrators group. You see the Local Group Properties dialog.4. Click Add to access the Add Users and Groups dialog.5. Select the desired user account and click Add. The selected user accountappears in the Add Names list in the lower half of the dialog.6. Click OK to add the user to the group and return to the Group Propertiesdialog. The user account is now in the Members list.7. Click OK to return to the User Manager window.Task B Give the Administrative User the "Log On as Service" PrivilegeIf your administrator user account doesn’t already have the "Log on as a service"right, give it this right as follows.1. In the User Manager window, choose the menu item Policies>User Rights.You see the User Rights Policy dialog.2. In the User Rights Policy dialog do the following:a. Click the Show Advanced User Rights check box.b. From the drop-down list labeled Right, choose the line Log on as aservice.c. Click Add. The Add Users and Groups dialog appears.3. Navigate to the desired user name and select it, as follows:a. In the List Names From list box, select your machine name, if it is notselected.b. In the Names box, select the Administrators group and click Members.The Local Group Members box appears.c. Select the desired user account and click Add.The desired user account appears in the Add Names box at the bottom of theAdd Users and Groups dialog.4. Click OK to grant the selected user the "Log on as a service" right and returnto the User Rights Policy dialog. The user account you selected now appearsin the Grant To box.5. Click OK to return to the User Manager window, then choose User>Exit toleave this window.TIBCO Hawk Installation and Configuration

20 Chapter 3 Installing on Microsoft Windows|Task C Change the Logon Account for TIBCO Hawk Windows ServicesNow you must change the logon account for the TIBCO Hawk Windows servicesto the selected administrative user account, as follows.1. Choose Start>Settings>Control Panel and double-click on the Services icon.You see the Services dialog.2. Select the desired TIBCO Hawk service from the list, right-click, and clickProperties. You see the Service dialog.3. In the Log On As tab, click This Account and enter the desired user accountand password.4. Click OK to save your action and return to the Services dialog.5. Repeat from step 2 for each TIBCO Hawk Windows service in the services list.Task D Configure Processes to Run in ForegroundYou can now configure processes started by the TIBCO Hawk agent to run in theforeground. This is optional; if you don’t want to do this, skip to step 4.1. Select the TIBCO Hawk Agent service from the list and click Startup. You seethe Service dialog.2. In the Log On As tab, click System Account and Allow Service to Interactwith Desktop enter the desired user account and password.3. Click OK to save your action and return to the Services dialog.4. Click Close to exit the Services dialog, then close the Control Panel window.You must reboot the machine for the TIBCO Hawk service configurationchanges to take effect.TIBCO Hawk Installation and Configuration

| 21Chapter 4Installing on UNIXThis chapter explains how to install and uninstall the TIBCO Hawk monitoringsystem on computers running the UNIX operating system.Topics• Installation Prerequisites, page 22• Installing TIBCO Hawk on UNIX, page 26• Post-Installation Tasks, page 30• Starting TIBCO Hawk Components Automatically at System Boot, page 32TIBCO Hawk Installation and Configuration

22 Chapter 4 Installing on UNIX|Installation PrerequisitesRead this section before you start installation.Supported Operating SystemsTable 4 Supported UNIX PlatformsThe following platforms are supported, with patches required as listed.Make sure that all patches required by other TIBCO products or third-partysoftware (such as the JRE) are installed before installing TIBCO Hawk.OS Hardware PatchesSolaris 8Solaris 9Solaris 10SPARC (32- and 64-bit)None required for TIBCO Hawk.Solaris 10 x86 None required for TIBCO Hawk.HP-UX 11i(v1, v2,v3)HP-UX 11i(v2 and v3)AIX 5.3AIX 6.1Red Hat EnterpriseLinux 4, 5PA-RISCIA64 (Itanium)POWER(32-bit and 64-bit)x86(32-bit and 64-bit)If using TIBCO Rendezvous: PHNE_26250,ARPA patch PHNE_20436 (PHNE_17662), andstreams patch PHNE_20008 (PHNE_17794) arerequired.For HP-UX 11.00 64 bit systems, HP-UX kernelpatch PHKL_27282 is required.None required for TIBCO Hawk.Apply 5.0.0.4 xlC libraries as indicated byAPAR IY14529None required for TIBCO Hawk.SUSE 10, 11IBM i5 OSMac OS X 10.5, 10.6(32-bit and 64-bit)x86(32-bit and 64-bit)None required for TIBCO Hawk.TIBCO Hawk Installation and Configuration

Installation Prerequisites| 23If 64-bit kernel is used and you have installed 32-bit TIBCO Hawk, some statisticswill remain undefined.Installer PrivilegesTIBCO Hawk can be installed by a regular (non-root) user or super-user (root).If a non-root user installs TIBCO Hawk, change the permissions and ownership ofthe tibhawkhma binary to root after installation, as shown:#> chmod 4555 tibhawkhma#> chown root:bin tibhawkhmaDifferent users can install the same product at different locations.Product dependencies at install time are resolved at user level through theinstallation registry maintained at user's home directory.TIBCO Hawk HMA Process Runs as rootThe TIBCO Hawk HMA process must run as user root to operate correctly. Theinstallation program, accordingly, creates setuid permissions with rootownership for the TIBCO Hawk HMA binary.The HMA only reads system information and cannot perform any actions. Itcannot manipulate, modify, or stop processes.Disk Space and MemoryDuring installation, the entire package is extracted into a temporary directory.Before actually installing the files, the installer calculates the disk space that theselected components will require in the installation directory. The installer willproceed only if sufficient free disk space is available in the installation directory.If some of the required disk space is taken by another process during installation,the installer may fail and display a failure message.If the required JRE version is already on your system, significantly less disk spaceis required in the temp directory.If your system does not have sufficient free disk space in the temp directory listedin the table below, you can use a different temp directory by including thefollowing option when starting the installer, where /new_tmp has sufficient freedisk space:TIBCO Hawk Installation and Configuration

24 Chapter 4 Installing on UNIX|-is:tempdir /new_tmpTable 5Required Disk Space in the Temp and Installation DirectoriesOperating SystemTemp Directory Free SpaceInstallationDirectoryFree SpaceSolaris 150 MB in /var/tmp 150 MBHP-UX 200 MB in /var/tmp 200 MBAIX 150 MB in /tmp 150 MBLINUX 150 MB in /tmp 150 MBMac OS X 150 MB 150 MBHome DirectoryThe user's home directory must at least have 150 MB of free disk space for theinstallation registry.RAMAll platforms require at least 512 MB RAM.SoftwareThe following software is required as indicated.TIBCO Software• TIBCO Rendezvous 8.1.1 or above is required, with any available patches.If you have already installed TIBCO Rendezvous software on a network-widebasis, you will not need additional TIBCO Rendezvous licenses unless youwill be running TIBCO Rendezvous Routing Daemon (RVRD) processes on aparticular machine. In this case, you need a valid RVRD license in thetibrv.tkt file for that machine.During installation, TIBCO Rendezvous is automatically installed if notpresent. Any earlier version of TIBCO Rendezvous will be upgraded toversion 8.3.TIBCO Rendezvous is used for inter-process communication even if TIBCOEnterprise Message Service (EMS) is chosen as the primary transport.TIBCO Hawk Installation and Configuration

Installation Prerequisites| 25• (Optional) TIBCO Enterprise Message Service 5.1.5 and 6.0.0.IF you plan to use TIBCO EMS as the primary messaging transport, at leastone EMS server must be installed on the network and you must select toinstall the TIBCO EMS Java client during installation on every machinerunning TIBCO Hawk Agent and TIBCO Hawk Console applications.• (Optional) TIBCO Administrator 5.4.0, 5.6.0, or above• (Optional) TIBCO Runtime Agent 5.5.4, 5.6.2If you plan to use either any Hawk plug-ins, TIBCO Administrator andTIBCO Runtime Agent are required.GUI Environment (Optional)If you are running the installer in GUI mode, a GUI environment such as CDE(X Windows) is required. It is not required for a console or silent installation. Alsosee DISPLAY Variable Error on page 180.JRERequired. JRE 1.6.0 is packaged with TIBCO Hawk as a convenience.Reconfigure Two-Button Mouse Devices (Solaris Only)Solaris systems using a two-button mouse must be configured with thethree-button mouse setting. Configure the two-button mouse as follows:1. Log in as superuser (root).2. From the command-line prompt, enter kdmconfig and select Built in PS/2[3 button mouse].3. Reboot the system.TIBCO Hawk Installation and Configuration

26 Chapter 4 Installing on UNIX|Installing TIBCO Hawk on UNIXBefore you begin installation, close all open applications. If any errors appearduring installation, consult Appendix B, Troubleshooting, for possible solutions.On all UNIX platforms, if you are upgrading to TIBCO Rendezvous 8.1.1, stop allTIBCO Rendezvous processes before installing TIBCO Hawk.Installation PackagesCopy the appropriate tar file from the download site or the CD and unpack it onyour system. The following table lists the platform-specific installation packages,where is the TIBCO Hawk software release number.Table 6 UNIX Installation tar Package FilenamesOSSolaris 8, 9, 10 (Sun SPARC)(32-bit)Solaris 8, 9, 10 (Sun SPARC)(64-bit)Solaris 10 (x86)(32-bit)Solaris 10 (x86)(64-bit)HP-UX 11i (32-bit)HP-UX 11i (64-bit)HP-UX IA64 (32-bit)HP-UX IA64 (64-bit)AIX (32-bit)AIX (64-bit)Linux (32-bit)Linux (64-bit)tar Package FilenameTIB_hawk__sol8_sparc.zipTIB_hawk__sol8_sparc_64.zipTIB_hawk__sol10_x86.zipTIB_hawk__sol10_x86_64.zipTIB_hawk__hpux111_hppa.zipTIB_hawk__hpux111_hppa_64.zipTIB_hawk__hpux112_ia64_32.zipTIB_hawk__hpux112_ia64.zipTIB_hawk__aix52_power.zipTIB_hawk__aix52_power_64.zipTIB_hawk__linux26gl23_x86.zipTIB_hawk__linux26gl23_x86_64.zipTIBCO Hawk Installation and Configuration

Installing TIBCO Hawk on UNIX| 27Table 6 UNIX Installation tar Package Filenames (Cont’d)OSMac OS X 10.5 (32-bit)Mac OS X 10.5 (64-bit)tar Package FilenameTIB_hawk__macosx_x86.zipTIB_hawk__macosx_x86_64.zipInstallation Profile SelectionDuring installation, you can choose from the following installation profiles.• Hawk Agent- This installation profile installs only Hawk Agent relatedcomponents.• Hawk Components- This installation profile installs all Hawk components.• Hawk Display- This installation profile installs only Hawk Display.• Hawk SDK- This installation profile installs only Hawk development tools tobuild the microagent, AMI, or the console application.The following sections discuss the different modes of installing TIBCO Hawk.Installation ModesThe installer allows you to install in different modes. Each mode is supported onall platforms.• GUI mode allows you to select which components to install, where to installthem, and so on. GUI mode is the installer’s default mode.• Console mode allows you to run the installer from the command line andallows you to select which components to install. You can create a responsefile or template file using console mode.• Silent mode installs in console mode without prompting you for input. Itinstalls using either the default settings or a response file that was savedduring an earlier installation.You can use any of the following options to install TIBCO Hawk:• Install Using GUI, page 28• Install Using Console, page 28• Install in Silent Mode, page 28These options and the instructions for installing TIBCO Hawk are provided in thefollowing sections. The following examples use the installation package for SUNSPARC Solaris 2.8.TIBCO Hawk Installation and Configuration

28 Chapter 4 Installing on UNIX|Install Using GUIGUI mode performs the installation in an interactive graphical interface. Theinstaller prompts you for values specific to your environment.To install, doubleclick the iconTIBCOUniversalInstaller-sol-sparc.bin.Install Using ConsoleConsole mode allows you to install the software from a UNIX terminal window.The installer prompts you for values. When installing in console mode you movethrough the installation process as shown:• Enter moves forward in the installer.• 2 returns to the previous screen.• 3 cancels the installer and exits the installation or uninstallation.• 4 redisplays the current screen.To install from a UNIX terminal window, type:TIBCOUniversalInstaller-sol-sparc.bin -is:javaconsole -consoleInstall in Silent ModeThe following procedure explains how to install a TIBCO Hawk product in silentmode. The TIBCOUniversalInstaller.silent file is packaged in the directorythat contains the universal installer. You must edit the file with information foryour environment before launching the silent installation. The file includescomments that describe the installation properties you can set.While you can use the TIBCOUniversalInstaller.silent file, it is good practiceto copy the file to a different name and edit that file for the silent install.If errors occur during installation, they will be listed in the installation log file (seethe User_Home/.TIBCO directory).1. Open the physical media or download the TIBCO Hawk product package.2. Extract the TIBCO Hawk product archive file to a temporary directory.3. Using a console window, navigate to the temporary directory that contains theuniversal installer.4. Copy the TIBCOUniversalInstaller.silent file and rename the copy.5. Using a text editor, open the copied file and update the install location, andfeatures to install.TIBCO Hawk Installation and Configuration

Installing TIBCO Hawk on UNIX| 296. Run the installer using this command line:TIBCOUniversalInstaller-sol-sparc.bin -is:silent -silentIf you are using the TIBCOUniversalInstaller.silent file (rather than acopy), you need not supply the file name and can use this command line:TIBCOUniversalInstaller -silentA line similar to the following is written to the installer log file wheninstallation completes:... Install, com.tibco.installer.util.TIBCOInstaller,dbg.Debug, Executing Event:::OnEndInstallTIBCO Hawk Installation and Configuration

30 Chapter 4 Installing on UNIX|Post-Installation TasksAfter installing TIBCO Hawk on UNIX, the root user must perform the followingpost-installation tasks as noted.Task A Verify the InstallationCheck that all directories and files have been added correctly. For details, seeTIBCO Hawk Directories and Files, page 189.Task B Modify Permission for tibhawkhmaModify the permissions of the TIBCO Hawk HMA (tibhawkhma) as shown:cd $TIBCO_HAWK_HOME/bin/tibhawkhmachown root tibhawkhmachmod u+s tibhawkhmaOn AIX and MacOS platforms, the tibhawkhma must be run as root and mustnot use setuid.On all other platforms, the TIBCO Hawk HMA (tibhawkhma) is dynamicallylinked with the TIBCO Rendezvous client libraries. Follow these steps to enablethe tibhawkhma to find the libraries:• HP-UX 11i PA-RISC 32-bitAdd RV library path to:/etc/dld.sl.conf file which contains trusted paths to search the libraries. Ifyou have the September 2005 Quality Pack patch bundle installed, specifiy alist of trusted paths in /etc/dld.sl.conf. If a path in an environmentvariable is a trusted path, it will be searched for libraries as usual.• Linux x86 32-bit/64-bitUpdate the /etc/ld.so.conf file add $RVHOME/lib to the list. This must bethe actual path and not $RVHOME variable.Run ldconfig.TIBCO Hawk Installation and Configuration

Post-Installation Tasks| 31• SolarisAdd the $RVHOME/lib directory to the trusted list using the crle command onthe 32-bit and 64-bit platforms.The crle command can be used as follows:— Solaris 8-10 SPARC 32-bit/64-bit - The crle command can be used asfollows:Run "crle -u -s $RVHOME/lib" or "crle -u -s $RVHOME/lib -64"— Solaris 10 x86 32-bit/64-bit - The crle command can be used as follows:Run "crle -u -s $RVHOME/lib" or "crle -u -s $RVHOME/lib -64"where:-u specifies that the configuration file needs to be updated.-s specifies the new trusted directory for the secure objects.TIBCO Hawk Installation and Configuration

32 Chapter 4 Installing on UNIX|Starting TIBCO Hawk Components Automatically at System BootThe TIBCO Hawk agent and TIBCO Hawk HMA components can be configuredto start automatically during the system boot cycle. A sample autostart script,Hawk2, is provided in the $HAWK_ROOT/samples/etc directory. It invokes thestarthma and startagent scripts during the boot cycle. You can modify thisscript for your environment. It can be used on all supported UNIX platforms.The following sections list the steps involved in starting TIBCO Hawkcomponents automatically at system boot. Refer to the correct section for youroperating system.• Solaris Instructions on page 32• HP-UX Instructions on page 32• AIX Instructions on page 33• LINUX Instructions on page 33• Mac OS X Instructions on page 34Solaris InstructionsThis section describes how to start TIBCO Hawk components automatically atsystem boot on a SUN SPARC Solaris or Intel Solaris operating system.1. Copy the hawk2 file as follows:cp $HAWK_ROOT/samples/etc/hawk2 /etc/init.d/hawk22. Modify (if not already present) tibhawkagent.tra file.Change "application.args -file hawkagent.cfg" to"application.args -file$CONFIG_FOLDER/tibco/cfgmgmt/hawk/bin/hawkagent.cfg"3. Create a link as follows:ln -s /etc/init.d/hawk2 /etc/rc2.d/S99hawk4. Use root user to modify /etc/inittab to match system boots level.HP-UX InstructionsThis section describes how to start TIBCO Hawk components automatically atsystem boot on an HP operating system.1. Copy the hawk2 file as follows:cp $HAWK_ROOT/samples/etc/hawk2 /sbin/init.d/hawk2TIBCO Hawk Installation and Configuration

Starting TIBCO Hawk Components Automatically at System Boot| 332. Modify (if not already present) tibhawkagent.tra file.Change "application.args -file hawkagent.cfg" to"application.args -file$CONFIG_FOLDER/tibco/cfgmgmt/hawk/bin/hawkagent.cfg"3. Create a link as follows:ln -s /etc/init.d/hawk2 /etc/rc2.d/S99hawk4. Use root user to modify /etc/inittab to match system boots level.AIX InstructionsThis section describes how to start TIBCO Hawk components automatically atsystem boot on an IBM operating system.1. Modify (if not already present) tibhawkagent.tra file.Change "application.args -file hawkagent.cfg" to"application.args -file$CONFIG_FOLDER/tibco/cfgmgmt/hawk/bin/hawkagent.cfg"2. Add an entry to the /etc/inittab file as follows:"hawk:2:once:/samples/etc/hawk2 start >/dev/console2>&1"LINUX InstructionsThis section describes how to start TIBCO Hawk components automatically atsystem boot on a LINUX operating system.1. Copy the hawk2 file as follows:cp $HAWK_ROOT/samples/etc/hawk2 /etc/init.d/hawk22. Modify (if not already present) tibhawkagent.tra file.Change "application.args -file hawkagent.cfg" to"application.args -file$CONFIG_FOLDER/tibco/cfgmgmt/hawk/bin/hawkagent.cfg"3. Create a link as follows:ln -s /etc/init.d/hawk2 /etc/rc2.d/S98hawk4. Use root user to modify /etc/inittab.By default, the run level on RHEL is 5. Change this to 2, such asid:2:initdefault:TIBCO Hawk Installation and Configuration

34 Chapter 4 Installing on UNIX|Mac OS X InstructionsThis section describes how to start TIBCO Hawk components automatically atsystem boot on a Mac 0S X 10.3.x operating system.Install JRE 1.6 or above before installing TIBCO Hawk.1. Create a directory under /System/Library/StartupItems as follow:mkdir /System/Library/StartupItems/hawk22. Copy the hawk2 file as follows:cp $HAWK_ROOT/samples/etc/hawk2/System/Library/StartupItems/hawk2/hawk23. Copy the StartupParameters.plist file as follows:cp $HAWK_ROOT/samples/etc/StartupParameters.plist/System/Library/StartupItems/hawk2/StartupParameters.plistRunning Hawk2 as Service at System BootTo run Hawk2 as service when system boots:1. Modify (if not already present) tibhawkagent.tra file.Change "application.args -file hawkagent.cfg"to"application.args -file$CONFIG_FOLDER/tibco/cfgmgmt/hawk/bin/hawkagent.cfg"2. Copy hawk2 to /etc/init.d and create a softlink to /etc/rc2.d asmentioned in the following sections.3. Use root user to modify /etc/inittab.By default, the run level on RHEL is 5. Change this to 2, such asid:2:initdefault:TIBCO Hawk Installation and Configuration

| 35Chapter 5Installing on IBM i5/OSThis chapter explains how to install the TIBCO Hawk monitoring system oncomputers running the IBM i5/OS operating system.Topics• Installation Prerequisites, page 36• Installing TIBCO Hawk on IBM i5/OS, page 38• Starting TIBCO Hawk Components, page 39• Starting TIBCO Hawk Components, page 39TIBCO Hawk Installation and Configuration

36 Chapter 5 Installing on IBM i5/OS|Installation PrerequisitesRead this section before you start installation.Supported Operating SystemsTIBCO Hawk supports IBM i5/OS version V5R3MO or higher.SoftwareThe following software is required as indicated.TIBCO Software• TIBCO Rendezvous 8.1.1 or above is required, with any available patches.If you have already installed TIBCO Rendezvous software on a network-widebasis, you will not need additional TIBCO Rendezvous licenses unless youwill be running TIBCO Rendezvous Routing Daemon (RVRD) processes on aparticular machine. In this case, you need a valid RVRD license asTIBRV(TKT) that is member TKT in file TIBRV.• (Optional) The Java client for TIBCO Enterprise Message Service 4.4.2 withany available patches.The tibhawkpassword utility (which encrypts the user password for connectingto the EMS server) is not supported on IBM i5/OS.JRETIBCO Hawk requires Java Runtime Environment (JRE) version 1.6 or above withany available patches, on the target machine.JRE is not included with the TIBCO Hawk installation package.TIBCO Hawk Installation and Configuration

Preparing for Installation| 37Preparing for InstallationThe installation package for IBM i5 is delivered in file xxx.zip. This zip filecontains savefile TIBHAWKSF which contains all the objects required to install theTIBCO Hawk product on IBM i5.Here is a sample set of steps for downloading the savefile to the IBM i5.On IBM i5:1. Login to your IBM i5 machine using your personal user profile.2. Create a library for receiving the savefile. For this exercise, let us assume thatthe library is called MYHAWKLIB.— CRTLIB MYHAWKLIB— or, use a library that you already have access to.On Windows:1. Unzip the distribution archive on a Microsoft Windows system.— Extract file TIBHAWKSF.sav from xxx.zip to one of your directories andname it as for example, md c:\myHawkDirExtract file TIBHAWKSF.sav from xxx.zip to c:\myHawkDir2. cd C:\myHawkDir3. ftp 4. Enter personal user profile and password.5. Quote site namefmt 16. cd MYHAWKLIB.LIB7. bin8. put TIBHAWKSF.sav TIBHAWKSF.savf9. Quit.TIBCO Hawk Installation and Configuration

38 Chapter 5 Installing on IBM i5/OS|Installing TIBCO Hawk on IBM i5/OSTo install the software, follow these steps:1. Signin as QSECOFR.2. Perform the installation using the command RSTLICPGM as follows:RSTLICPGM LICPGM(1TIBHK1) DEV(*SAVF) SAVF(MYHAWKLIB/TIBHAWKSF)This will restore both the product library, TIBHAWK, and all files in the IFS,/usr/tibco/hawk/4.9.TIBCO Hawk Installation and Configuration

Starting TIBCO Hawk Components| 39Starting TIBCO Hawk ComponentsTo Start TIBCO Hawk Microagent• ADDLIBLE TIBHAWK• SBMJOB CMD(CALL PGM(TIBHKHMA) PARM('-rvd_session' '7474' '''tcp:7474')) JOBQ(QUSRNOMAX) MSGQ(*USRPRF) ALWMLTTHD(*YES)ALWMLTTHD(*YES) must be specified to enable the multi-threaded application.Ensure that JOBQ(QUSRNOMAX) is active in your environment.To Start TIBCO Hawk Agent• ADDLIBLE TIBHAWK• Edit the default hawkagent.cfg file EDTFSTMF('/usr/tibco/hawk/4.9/bin/hawkagent.cfg')— Change occurrence of "%TIBCO_HAWK_ROOT_ESC%/config" to"/usr/tibco/hawk/4.9/config"• CALL PGM(TIBHKAGT) PARM( 1.6 )• The default codepage used for reading output from the TIBCO Hawkmethods Custom::ExecuteForString and Custom::ExecuteForNumber isCp037. You can override this default value by specifying the codepage in theJava property customMA.codepage.For example, to change the code page to Cp500, add the following line-DcustomMA.codepage="Cp500"before specifying the classpath in the startagent script.• When using TIBCO EMS as the primary transport, TIBCO Hawk agentcannot be started using CL script. You have to start TIBCO Hawk agentusing Q shell (qsh).TIBCO Hawk Installation and Configuration

40 Chapter 5 Installing on IBM i5/OS|TIBCO Hawk Installation and Configuration

| 41Chapter 6Configuring TIBCO Hawk SoftwareThis chapter describes how to edit the configuration files for the TIBCO HawkDisplay, Agent, HMA and Event Service components on Microsoft Windows andUNIX platforms. It also describes how to use the startup scripts, create a TIBCOHawk domain, and create a TIBCO Rendezvous session.On Microsoft Windows platforms, you can alternatively use a GUI interface toconfigure TIBCO Hawk General, Display, Agent, and Event Service components.This is described in Chapter 7, Using the Configuration Utility.Topics• Startup Scripts/Wrappers and Configuration Files, page 42• TIBCO Hawk Display Configuration File (hawkdisplay.cfg), page 45• TIBCO Hawk Agent Configuration File (hawkagent.cfg), page 52• TIBCO Hawk HMA Configuration File (hawkhma.cfg), page 70• TIBCO Hawk Event Service Configuration File (hawkevent.cfg), page 73• Creating a TIBCO Hawk Domain, page 84• Creating a TIBCO Rendezvous Session, page 85TIBCO Hawk Installation and Configuration

42 Chapter 6 Configuring TIBCO Hawk Software|Startup Scripts/Wrappers and Configuration FilesPlease read this chapter and determine your system’s particular configurationand setup requirements before changing any values.A set of startup wrappers/scripts and configuration files is provided with theTIBCO Hawk software. A startup wrapper/scripts and default configuration fileare supplied for each component. The configuration files and options aredescribed in the next sections.Table 7 TIBCO Hawk Components, Startup Scripts/Wrappers, and Configuration FilesComponentStartupScripts/WrapperConfiguration FileDescribedon PageTIBCO HawkDisplayTIBCO HawkAgenttibhawkdisplay hawkdisplay.cfg 45tibhawkagent hawkagent.cfg 52TIBCO HawkHMAtibhawkhma(Windows)starthma(UNIX)hawkhma.cfg 70TIBCO HawkEvent Servicetibhawkevent hawkevent.cfg 73Startup wrappers and configuration files are located inTIBCO_CONFIG_FOLDER/tibco/cfgmgmt/hawk/bin.On UNIX platform, user should edit the .cfg files to modify the configurations.On Windows, user should use tibhawkconfig.exe to modify the configurations.In the configuration files, if any folder or file has to be configured with a space init, then the full path has to be provided within double quotes.This chapter describes the command line options you can use in the configurationfiles. If no command line options are specified, the startup wrappers use thesupplied default values in the configuration files (as shipped) by default.On Mac OS X, TIBCO Hawk display must be started using startdisplay scriptinstead of tibhawkdisplay.TIBCO Hawk Installation and Configuration

Startup Scripts/Wrappers and Configuration Files| 43Wrapper HelpHandling Passwords for TIBCO EMS TransportOn Microsoft Windows, the password entered from the Configuration Utility isobfuscated before it is stored in the Microsoft Windows registry.In order to use the EMS password encrypt/decrypt functionality, all TIBCOHawk components (including the tibhawkpassword wrapper) have to use JRE1.6 or above.If you need to change the username and password information for the EMS serverafter installation, a utility is provided to encrypt your password. The followingsteps detail the use of this utility:1. Invoke the command line using the syntaxtibhawkpassword -encrypt where is the password you want to encrypt.2. Copy and paste the output of the utility within quotes ("") into theconfiguration file.For example,-ems_transport tcp://emsServer:7222 username"#!FrHOG/QbvQMdVk4/wMv/1DA0"3. Re-start the TIBCO Hawk component whose configuration file you updatedin step 2.Using AMI applications with TIBCO EMS TransportApplications implementing the TIBCO Hawk Application Management Interface(AMI) for manageability by a TIBCO Hawk Agent use TIBCO Rendezvous as themessaging transport. As it is much more efficient to keep all AMI-relatedmessages within the same machine as the Agent and the AMI application, TIBCORendezvous will continue to be used for AMI communication even if TIBCO EMSis used for all external TIBCO Hawk messaging.If it is desired to isolate all TIBCO Rendezvous traffic, including the TIBCORendezvous Advisory messages, to the local machine when using TIBCO EMS asa network transport, the TIBCO Rendezvous network parameter should be set touse the loopback interface (127.0.0.1) address for all AMI applications and theAgent's AMI Rendezvous transports.For example, the ami_rvd_session option would be configured as:-ami_rvd_session 7474 127.0.0.1 tcp:7474TIBCO Hawk Installation and Configuration

44 Chapter 6 Configuring TIBCO Hawk Software|Using TIBCO Hawk in the TIBCO Runtime Agent EnvironmentThe configuration file for TIBCO Hawk agent (hawkagent.cfg) is located in thedirectory /tra/domain/.For example (on Microsoft Windows) ,c:\tibco\tra\domain\qaserver\hawkagent.cfgThe executable used by the configuration file is hawkagent_(on the Microsoft Windows platform, it is hawkagent_.exe)For example, hawkagent_qaserver.The default rulebase configuration is Automatic Configuration. Any rulebasesdeployed by TIBCO Administrator are stored in specified auto configurationdirectory.The configuration file should be edited in the same manner as a TIBCO Hawkagent configuration file. For instructions on customizing the configuration filesee, TIBCO Hawk Agent Configuration File (hawkagent.cfg), on page 52.TIBCO Hawk Installation and Configuration

TIBCO Hawk Display Configuration File (hawkdisplay.cfg)| 45TIBCO Hawk Display Configuration File (hawkdisplay.cfg)The options in the hawkdisplay.cfg configuration file are used to configure thefollowing functions related to TIBCO Hawk Display. The functions and optionsare described in the next sections.Table 8 hawkdisplay.cfg Functions and OptionsFunctionTIBCO Hawk DomainTIBCO Rendezvous (RVD)SessionTIBCO EnterpriseMessage Service (EMS)TransportTIBCO EnterpriseMessage Service (EMS)Transport using SSLOptions-hawk_domain -rvd_session -ems_transport -ssl_vendor -ssl_no_verify_host-ssl_trusted -ssl_expected_hostname -ssl_identity -ssl_private_key -ssl_password -ssl_no_verify_hostname-ssl_ciphers Character EncodingLogging Information-character_encoding -logdir -logmaxsize -logmaxnum -log_format Display FileSecurity PolicyVariables-display_file -security_policy -variables TIBCO Hawk Installation and Configuration

46 Chapter 6 Configuring TIBCO Hawk Software|TIBCO Hawk Domain-hawk_domain Separate domains create independent TIBCO Hawk systems. Agents and thedisplay must share the same Hawk Domain name in order to communicate. Thedefault is to monitor an entire network as one group. To use the default, omit the-hawk_domain option. See Creating a TIBCO Hawk Domain, page 84, for moredetails.TIBCO Rendezvous (RVD) Session-rvd_session This option must be omitted if using TIBCO EMS as the primary transport.Because the TIBCO Hawk software uses the functionality of the TIBCORendezvous system, it must connect to a TIBCO Rendezvous daemon by creatinga session.If TIBCO Rendezvous is only used on one network and no special TIBCORendezvous sessions are needed, use the TIBCO Rendezvous daemon sessiondefault values. To use the default TIBCO Hawk session parameters, omit the-rvd_session command-line options.If you use this option, all three parameters must be present and separated bywhite space. Use a semicolon (;) to indicate a null value, or use an empty string,for example:-rvd_session 7474 "" tcp:7474See Creating a TIBCO Rendezvous Session, page 85, for more details.TIBCO Enterprise Message Service TransportSpecifies that the TIBCO Hawk Display should use TIBCO EMS forcommunicating with the agent. This option must be omitted if using TIBCORendezvous as the primary transport.There are two ways to specify the TIBCO EMS transport parameters:• Specify only the location of the EMS server.For example,-ems_transport tcp://server1:7222If communicating with the EMS server using SSL, specify the location of theEMS server as follows for the above example-ems_transport ssl://server1:7222TIBCO Hawk Installation and Configuration

TIBCO Hawk Display Configuration File (hawkdisplay.cfg)| 47and also specify the additional options as outlined in TIBCO EnterpriseMessage Service (EMS) Transport using SSL on page 48.• Specify the location of the EMS server and a valid username and password forthe EMS server. These parameters are separated by a space and can be anempty string to indicate a null value.For example,-ems_transport tcp://server1:7222 admin "#!NhAD1NBC"For instructions to modify the password which was specified duringinstallation, see Handling Passwords for TIBCO EMS Transport on page 43.If communicating with the EMS server using SSL, specify the location of theEMS server as follows for the above example-ems_transport ssl://server1:7222 admin "#!NhAD1NBC"and also specify the additional options as outlined in TIBCO EnterpriseMessage Service (EMS) Transport using SSL on page 48.Re-Connection SetupTo ensure the TIBCO EMS client attempts re-connection after losing connection tothe EMS server, repeat the server URL in the URL list. For example,-ems_transport tcp://H1:7222,tcp://H1:7222Fault Tolerance SetupYou can specify backup servers to connect to in the event of the failure of theprimary server. The serverURLs for the primary and backup server(s) arespecified as a comma-separated list of URLs.For example,-ems_transport tcp://server1:7222,tcp://server2:7344If a connection to the first URL fails, the next URL in the list is used to attempt areconnection. The connections in the list are attempted in sequence (wrapping tothe start of the list, if the first connection was not the failed connection) until allURLs have been tried. If no connection is established after all URLs have beentried, the connection fails.In addition to specifying the -ems_transport options, the following parametersin the EMS server configuration file, tibemsd.conf, should be considered:• ft_active, the name of the active server.• ft_reconnect_timeout, the amount of time a backup server waits for clientsto reconnect.• store, the directory to store TIBCO EMS data.For more information, see TIBCO Enterprise Message Service documentation.TIBCO Hawk Installation and Configuration

48 Chapter 6 Configuring TIBCO Hawk Software|TIBCO Enterprise Message Service (EMS) Transport using SSLSpecifies the SSL parameters used by TIBCO Hawk Display when connecting tothe EMS server.If the -ems_tranport parameter is not used, the following options are ignored.-ssl_vendor The name of the vendor of the SSL implementation. The valid choices are— j2se-defaultUse this option when you want to use the default JCE bundled with theJava JRE.On IBM platforms (such as AIX), this option defaults to ibm.— j2se— entrust61Use this option when you want to use the Entrust libraries.— ibmOn non-IBM platforms, this option can be used only if the IBM version ofJCE is installed.-ssl_ciphers When specifying this option to specify the cipher suites that can be used, usethe ^ qualifier instead of a - qualifier. For more information on specifyingcipher suites, refer to the TIBCO Enterprise Message Service documentation.In addition, the following sets of options are used:For TIBCO Hawk components to verify the EMS server-ssl_no_verify_hostIf this option is present, it this indicates that the TIBCO Hawk componentshould not verify the server. Conversely, if this option is not included in theconfiguration file, it indicates that TIBCO Hawk component should verify theserver.-ssl_trustedThe option specifies the file name of the server certificates. This option can berepeated if more than one certificate file is used.-ssl_no_verify_hostnameThis option specifies that the client should not verify the name in the CN fieldof the server certificate. Conversely, if this option is not included in theconfiguration file, it indicates that TIBCO Hawk component should verify thename in the CN field of the server certificate.TIBCO Hawk Installation and Configuration

TIBCO Hawk Display Configuration File (hawkdisplay.cfg)| 49-ssl_expected_hostnameThe name that is expected in the name of the CN field of the server certificatesis specified by this option. The value of this option is used when the-ssl_no_verify_hostname option absent from the configuration file.If the -ssl_no_verify_host is not specified, the option -ssl_trusted has to beused. Along with the option-ssl_trusted specify either-ssl_no_verify_hostname or -ssl_expected_hostname.For the EMS server to verify TIBCO Hawk components-ssl_identityThis option specifies the digital certificate of the TIBCO Hawk components.-ssl_private_keyThis option indicates the private key of the TIBCO Hawk component. If thekey is included in the digital certificate in -ssl_identity, then you may omitthis parameter.-ssl_passwordThe password to decrypt the identity file of the Hawk component. For details,see Handling Passwords for TIBCO EMS Transport on page 43.Character Encoding-character_encoding Specifies the character encoding to be used for strings sent over all TIBCORendezvous transports.Logging Information-logdir -logmaxsize -logmaxnum -log_format The TIBCO Hawk system creates rolling log files for display events(display.log) in the directory named in the -log_dir option.When one file has reached the size specified in the -logmaxsize option, it isclosed and renamed, and a new log file with the same name is started. When thenumber of log files exceeds the number set in the -logmaxsize option, log entriesroll over to reuse the oldest log file.TIBCO Hawk Installation and Configuration

50 Chapter 6 Configuring TIBCO Hawk Software|By default, the unit of measure for -logmaxsize is kilobytes and the default sizeis 1024. To specify a value in megabytes, use the suffix m or M. For example, 10Mspecifies ten megabytes. Note that the maximum log file size is 2097151 kilobytes.You can enter at minimum 5 and at maximum 999 as a value for -logmaxnum. If,for example, you have configured a maximum of five log files, log files roll overuntil there are five files (named file1, file2… file5). At this point, the nextrollover eliminates file5 and renames file4 to file5, thus maintaining a totalof five rollover files. The log thus retains the latest log information and discardsthe oldest.The -log_format option allow you to select the format of log file entries. Eitherthe existing Hawk format or the ActiveEnterprise format can be specified.Display File-display_file Specify the location of a display file to be loaded automatically. To use the default,omit this option.Security Policy-security_policy Because security needs vary greatly, the TIBCO Hawk system provides amechanism by which you can develop your own security policy plug-in. To createa security policy, you must write a Java class that implements a security policyspecific to your needs. For more information on creating a security policy class,see the TIBCO Hawk Programmer’s Guide.Depending on your security needs, complete the -security_policy option asfollows.• If you are not using a security policy, omit this option.• To use a specific security policy, on each machine where you want to use thepolicy, specify the name of the security policy class. Do not enter the fileextension. For example, if your Java class file is namedASecurityPolicy.class you would specify ASecurityPolicy.• To use the TIBCO Hawk Trusted Security Policy, use:COM.TIBCO.hawk.security.trusted.TrustedorCOM.TIBCO.hawk.security.trusted.TrustedWithDomainFor more information on the Trusted security policy that comes with TIBCOHawk software, see Chapter 11 on page 155.TIBCO Hawk Installation and Configuration

TIBCO Hawk Display Configuration File (hawkdisplay.cfg)| 51Variables-variables Use the Variables option to specify a variables file. The variables file can pass datato define external variables to be used in either host or tool menu commands.On UNIX systems, the env command outputs environment values in the correctformat. However, in Microsoft Windows, the following restrictions apply toexternal variables:• The variables file to support External variables in the agent must conform tothe Java properties file format.• Variables and variable names cannot include spaces or any of the followingcharacters: equals sign (=), period (.), or forward slash(\).• Any special characters must be escaped to be evaluated properly.For example, to use a variable for c:\tibco\hawk, you would specify in the file:HAWK_ROOT=c:\\tibco\\hawk. Also, due to the Java file path separator format,HAWK_ROOT=c:/tibco/hawk will also work properly on the Microsoft Windowsplatform.TIBCO Hawk Installation and Configuration

52 Chapter 6 Configuring TIBCO Hawk Software|TIBCO Hawk Agent Configuration File (hawkagent.cfg)The options in the hawkagent.cfg configuration file relate to agent functionality.The agent command line options are organized in a modular fashion. Each sectionof the file begins with -M followed by the module name, such as -M Self. Withineach modular section are command line options relating to the function of themodule.The command line options within each module of the TIBCO Hawk agentconfiguration file are described in the next sections.Table 9hawkagent.cfg Modules and OptionsModule Name Options Page-M Self -cluster -agent_name -agent_domain -hawk_domain -rvd_session -ems_transport -ssl_vendor -ssl_no_verify_host-ssl_trusted -ssl_expected_hostname -ssl_identity -ssl_private_key -ssl_password -ssl_no_verify_hostname-ssl_ciphers -use_thread_pool -character_encoding -hma_plugin_dir -file 54TIBCO Hawk Installation and Configuration

TIBCO Hawk Agent Configuration File (hawkagent.cfg)| 53Table 9hawkagent.cfg Modules and OptionsModule Name (Cont’d) Options Page-M RuleBaseEngine -rulebases . . .61-config_path -auto_config_dir -repository_path -repository_cache_dir -variables -M AMIService -ami_rvd_session 65-M LogService -log_dir 66-log_max_size -log_max_num -log_format -M TIBProtocolAdapter -interval 67-security_policy -M Repository -repository_name 68-repository_dir -M LogfileMicroAgent -scan_rate 68-block_size < size in kilobytes>-eval_rate Note:On Windows: If using .cfg file to configure, thencomment/un-comment:• -M LogfileMicroAgent• -scan_rate 10On UNIX: If using configurationutility, set the scan rate tozero or non-zero value to disable/enable LogfileMicroAgent.-M CustomMicroAgent -time_out 69TIBCO Hawk Installation and Configuration

54 Chapter 6 Configuring TIBCO Hawk Software|-M SelfTable 10 -M Self OptionsThis module of the agent configuration file deals with the following commandline options which relate to the agent itself:Option-cluster DescriptionThe name of the container in which this agent will appear in thedisplay by default. The display will create the container if it doesnot already exist. Allows for grouping of multiple agents.The default name for the container is the IP subnet address. Thecluster name must be enclosed within quotes, if the namecontains spaces.-agent_name The agent name as it appears in the TIBCO Hawk Display. Thedefault name for the TIBCO Hawk agent is the host name of thecomputer on which it is installed.Each agent being managed must have a unique combination ofagent_name, agent_domain, and hawk_domain values.To use the host name as the agent name, omit this option. To use adifferent name, specify a name as desired.Note: Agent names with multiple words separated by dots arenot supported.-agent_domain Sets the agent domain name. The default value is "none". Eachagent being managed must have a unique combination ofagent_name, agent_domain, and hawk_domain values.An agent domain must be specified when two computers withinthe same TIBCO Hawk domain have the same name but reside indifferent network domains. For example, you might specify thisoption as: -agent_domain pa.tibco.com.TIBCO Hawk Installation and Configuration

TIBCO Hawk Agent Configuration File (hawkagent.cfg)| 55Table 10 -M Self Options (Cont’d)Option (Cont’d)-hawk_domain Description (Cont’d)Sets the hawk domain name. The agents and the display musthave the same hawk domain value in order to communicate. Eachagent being managed must have a unique combination ofagent_name, agent_domain, and hawk_domain values.Separate domains create independent TIBCO Hawk systems.Agents and the display must share the same Hawk Domain namein order to communicate. The default is to monitor an entirenetwork as one group. To use the default, omit the -hawk_domainoption. See Creating a TIBCO Hawk Domain, page 84, for moredetails.-rvd_session Specifies the primary TIBCO Rendezvous transport used by theagent. Because the TIBCO Hawk software uses the functionalityof the TIBCO Rendezvous system, it must connect to a TIBCORendezvous daemon by creating a session.If TIBCO Rendezvous is only used on one network and no specialTIBCO Rendezvous sessions are needed, use the TIBCORendezvous daemon session default values. To use the defaultTIBCO Hawk session parameters, omit the -rvd_sessioncommand-line options.If you use this option, all three parameters must be present andseparated by white space. Use an empty string to indicate a nullvalue, for example:-rvd _session 7474 "" tcp:7474See Creating a TIBCO Rendezvous Session, page 85, for moredetails.When using TIBCO EMS as the primary transport, if neither-rvd_session nor -ami_rvd_session is specified, a TIBCORendezvous session for the AMI instrumented applications iscreated using null values. If -rvd_session is specified but not the-ami_rvd_session, TIBCO Rendezvous session for the AMIinstrumented applications uses the one created by the-rvd_session parameter.When using TIBCO EMS as the primary transport, it isrecommended that the loopback interface address (127.0.0.1) beused as the network parameter.TIBCO Hawk Installation and Configuration

56 Chapter 6 Configuring TIBCO Hawk Software|Table 10 -M Self Options (Cont’d)Option (Cont’d)-ems_transport Description (Cont’d)Specifies the TIBCO EMS transport parameters used by the agent.There are 2 ways of specifying the EMS transport• Using only one argument, serverURL, for example-ems_transport tcp://dev_server:7222If communicating with the EMS server using SSL, specify thelocation of the EMS server as follows for the above example:-ems_transport ssl://server1:7222• Specify the location of the EMS server and a valid usernameand password for the EMS server. These parameters areseparated by a space and can be an empty string to indicate anull value.-ems_transport tcp://dev_srv:7222 admin "#!NhAD1C"For instructions to modify the password which was specifiedduring installation, see Handling Passwords for TIBCO EMSTransport on page 43.If communicating with the EMS server using SSL, specify thelocation of the EMS server as follows for the above example :-ems_transport ssl://server1:7222 admin"#!NhAD1NBC"Re-Connection SetupTo ensure the TIBCO EMS client attempts re-connection afterlosing connection to the EMS server, repeat the server URL in theURL list. For example,-ems_transport tcp://H1:7222,tcp://H1:7222However, the agent tries to reconnect for a maximum of 1800times even if multiple server URLs are not specified for-ems_transport.TIBCO Hawk Installation and Configuration

TIBCO Hawk Agent Configuration File (hawkagent.cfg)| 57Table 10 -M Self Options (Cont’d)Option (Cont’d)-ems_transport ContdDescription (Cont’d)Fault Tolerance SetupYou can specify backup servers to connect to in the event of thefailure of the primary server. The serverURLs for the primary andbackup server(s) are specified as a comma-separated list of URLs.For example,-ems_transport tcp://server1:7222,tcp://server2:7344If a connection to the first URL fails, the next URL in the list isused to attempt a reconnection. The connections in the list areattempted in sequence (wrapping to the start of the list, if the firstconnection was not the failed connection) until all URLs havebeen tried. If no connection is established after all URLs havebeen tried, the connection fails.In addition to specifying the -ems_transport options, thefollowing parameters in the EMS server configuration file,tibemsd.conf, should be considered:• ft_active, the name of the active server.• ft_reconnect_timeout, the amount of time a backup serverwaits for clients to reconnect.• store, the directory to store TIBCO EMS data.For more information, refer to the TIBCO Enterprise MessageService documentation.When using TIBCO EMS as the primary transport, if neither-rvd_session nor -ami_rvd_session is specified, a TIBCORendezvous session for the AMI instrumented applications iscreated using null values. If -rvd_session is specified but not the-ami_rvd_session, TIBCO Rendezvous session for the AMIinstrumented applications uses the one created by the-rvd_session parameter.TIBCO Hawk Installation and Configuration

58 Chapter 6 Configuring TIBCO Hawk Software|Table 10 -M Self Options (Cont’d)Option (Cont’d)-ems_transport ContdDescription (Cont’d)Using SSL to connect to the EMS ServerWhen using SSL to connect to the EMS Server, the followingoptions are used:-ssl_vendor-ssl_cipherIn addition, the following sets of options are used:For TIBCO Hawk components to verify the EMS server-ssl_no_verify_host-ssl_trusted-ssl_no_verify_hostname-ssl_expected_hostnameIf the -ssl_no_verify_host is not specified, the option-ssl_trusted has to be used. Along with theoption-ssl_trusted specific either -ssl_no_verify_hostnameor -ssl_expected_hostname.For the EMS server to verify TIBCO Hawk components:-ssl_identity-ssl_private_key-ssl_password-use_thread_pool This option optimizes the number of threads the agent creates forevery microagent it discovers. It is advisable to turn this optionon if the agent is going to discover over 100 microagents. Thedefault value is 256. This value is OS dependent and should be setto the maximum number of threads allowable per process.TIBCO Hawk Installation and Configuration

TIBCO Hawk Agent Configuration File (hawkagent.cfg)| 59Table 10 -M Self Options (Cont’d)Option (Cont’d)-ssl_vendor -ssl_no_verify_host-ssl_trusted -ssl_expected_hostnameDescription (Cont’d)Specifies the name of the vendor of the SSL implementation.The valid choices are:• j2se-defaultUse this option when you want to use the default JCEbundled with the Java JRE.On IBM platforms (such as AIX), this option defaults to ibm.• j2se• entrust61Use this option when you want to use the Entrust libraries.• ibmOn non-IBM platforms, this option can be used only if theIBM version of JCE is installed.Specifies that the TIBCO Hawk component should not verify theserver. Conversely, if this option is not included in theconfiguration file, it indicates that TIBCO Hawk componentshould verify the server.Specifies the file name of the server certificates. This option can berepeated if more than one certificate file is used.Specifies the name that is expected in the name of the CN field ofthe server certificates.The value specified by this option is used when the-ssl_no_verify_hostname option absent from theconfiguration file.-ssl_identity Specifies the digital certificate of the TIBCO Hawk components-ssl_private_key-ssl_password Specifies the private key of the TIBCO Hawk component.If the key is included in the digital certificate in -ssl_identity,then you may omit this parameter.Specifies the password to decrypt the identity file of the Hawkcomponent.For details, see Handling Passwords for TIBCO EMS Transport onpage 43.TIBCO Hawk Installation and Configuration

60 Chapter 6 Configuring TIBCO Hawk Software|Table 10 -M Self Options (Cont’d)Option (Cont’d)-ssl_no_verify_hostname-ssl_ciphers -character_encoding-hma_plugin_dir -file Description (Cont’d)Specifies that the client should not verify the name in the CN fieldof the server certificate. Conversely, if this option is not includedin the configuration file, it indicates that TIBCO Hawkcomponent should verify the name in the CN field of the servercertificate.Specifies the cipher suites that can be used. When specifying thisoption, use the ^ qualifier instead of a - qualifier. For moreinformation on specifying cipher suites, refer to the TIBCOEnterprise Message Service documentation.Specifies the character encoding to be used for strings sent overall TIBCO Rendezvous transports.Specifies the directory the TIBCO Hawk Agent should searchwhen loading microagent plug-ins.Read more command line arguments from a config file. Thecontents of the file have the same syntax and semantics ascommand lines. Multiple lines are permitted. All characters from# to the end of a line are treated as a comment. This option is notallowed in a config file. You may supply no more than one -fileparameter.TIBCO Hawk Installation and Configuration

TIBCO Hawk Agent Configuration File (hawkagent.cfg)| 61-M RuleBaseEngineTable 11 -M RuleBaseEngine OptionsThis module of the agent configuration file deals with the following commandline options which relate to the rulebases used by this agent.If you are using the rulebase map, you usually do not need to list any rulebases inthe -rulebases option. Using both a rulebase map and the -rulebases optionincreases the complexity of managing your monitoring configuration.The -rulebases option is provided to maintain backward compatibility withprevious versions of TIBCO Hawk that do not contain the rulebase map feature.Three mutually-exclusive configuration modes are available for determiningwhich configuration objects to use. Combining these options to implement eachconfiguration mode is discussed in the following sections:• Automatic Configuration Mode on page 62• Manual Configuration Mode on page 63• Repository Configuration Mode on page 64Option-rulebases . . .DescriptionTypically used only if rulebase map is not being usedIf manual or repository configuration mode is used, specify a list ofrulebases to be loaded at startup.If -rulebases option is used, you must omit the -auto_config_diroption and use either manual configuration mode or repositoryconfiguration mode options.Do not use a file extension when entering rulebase names. The .hrbextensions are only used for rulebase files.When entering more than one rulebases, the rulebase names shouldbe separated by a space.See RuleBaseEngine:loadRuleBase() andRuleBaseEngine:loadRuleBaseFromFile() for more information-config_path If manual configuration mode is used, specify the path to be searchedfor configuration objects. The delimiter for path entries is a colon (:).The default used if this option is omitted is the current workingdirectory.If -config_path is used, omit the -auto_config_dir,-repository_path, and -repository_cache_dir options.TIBCO Hawk Installation and Configuration

62 Chapter 6 Configuring TIBCO Hawk Software|Table 11 -M RuleBaseEngine Options (Cont’d)Option (Cont’d)-auto_config_dir-repository_path -repository_cache_dir-variables Description (Cont’d)If this option is present, the agent will run in automatic configurationmode.Specify the directory from which rulebase and schedule configurationobjects will be loaded at startup. The default directory, /autoconfig, is used if a value is omitted.If you use automatic configuration, omit the following options:-config_path, -repository_path, -repository_cache_dir,-rulebasesIf repository configuration mode is used, specify the path to besearched for repositories. The delimiter for path entries is a colon (:).The default used if this option is omitted is the current workingdirectory.If -repository_path is used, omit the -auto_config_dir and-config_path options.If repository configuration mode is used, all configuration objectsloaded from the repository may be cached in a local directory,specified in this option. This cache is used in the event of a repositoryfailure, and also to minimize network traffic.If -repository_cache_dir is used, omit the -auto_config_dir and-config_path options.Use this option to specify a variables file. The variables file can passdata to define external variables to be passed to rules for use inrulebase configurations.Automatic Configuration ModeThis section explains how you use the -M RuleBaseEngine options to implementan Automatic Configuration mode. This is one of three mutually-exclusive modesavailable for determining which configuration objects to use. The other twomodes are Manual Configuration and Repository Information, both of which aretypes of manual configuration mode.To use Automatic configuration, specify the -auto_config_dir option.When Automatic Configuration mode is used, all load-by-reference rulebaseloading mechanisms are disabled. Therefore, you will omit the following options:-rulebasesTIBCO Hawk Installation and Configuration

TIBCO Hawk Agent Configuration File (hawkagent.cfg)| 63-config_path-repository_path-repository_cache_dirIn addition, the RuleBaseInclude feature, rulebase maps, and theRuleBaseEngine:loadRuleBase() microagent method are not used. However,the microagent method RuleBaseEngine:loadRuleBaseFromFile() is allowed.See the TIBCO Hawk Administrator’s Guide and the TIBCO Hawk Methods Referencefor more on these features and microagent methods.With automatic configuration, the agent will load the Schedule configuration fileand all rulebase configuration files from the automatic configuration directory atstartup. The only other mechanism by which an agent can load a rulebase afterthis point is through invocation of RuleBaseEngine:loadRuleBaseFromFile()using fully qualified filenames, or by using SendTo from the Display.When a rulebase is sent to an agent via SendTo or Apply Changes from theDisplay, the rulebase is stored in the autoconfiguration directory. When a rulebaseis removed from an agent via the Display, the rulebase is also removed from theautoconfiguration directory. Use of the methodsRuleBaseEngine:loadRuleBaseFromFile() andRuleBaseEngine:unloadRuleBase() do not affect the autoconfigurationdirectory.Manual Configuration ModeThis section explains how you use the -M RuleBaseEngine options to implement aManual Configuration mode. This is one of three mutually exclusive modesavailable for determining which configuration objects to use. The other twomodes are Automatic Configuration and Repository Information. ManualConfiguration and Repository Information are both types of manualconfiguration mode.To use manual configuration, specify a configuration path and a list of rulebases,using the -rulebases and -config_path options.Use of -rulebases is optional. However, if no RuleBase Map is supplied by therepository, the use of -rulebases is recommended.When Manual Configuration mode is used, omit the following options:-auto_config_dir-repository_path-repository_cache_dirTIBCO Hawk Installation and Configuration

64 Chapter 6 Configuring TIBCO Hawk Software|When manual configuration is selected, the agent searches the ManualConfiguration Path for the Schedule file and the rulebase map file at startup. Afterevaluating the rulebase map, the agent has a list of rulebase names. It searches forthese using the Manual Configuration Path.Note that the loaded startup rulebases may have RuleBaseInclude lists that willtrigger further searches of the manual configuration path for additional rulebases.Also at startup, the agent searches the path for any rulebases specified in theRulebases dialog and loads them.Note that any rulebases loaded by the agent are not written to a local cache. Thereis no notion of an autoconfiguration directory. The only rulebases an agent mayload at startup are those specified by the rulebase map, those listed in theRulebases dialog, and rulebases in any contained RuleBaseIncludes.See the TIBCO Hawk Administrator’s Guide for more on these features. Note thatmanual configuration mode is also known as Configuration Path mode.Repository Configuration ModeThis section explains how you use the -M RuleBaseEngine options to implement aRepository Configuration mode. This is one of three mutually-exclusive modesavailable for determining which configuration objects to use. The other twomodes are Automatic Configuration and Manual Configuration. ManualConfiguration and Repository Information are both types of manualconfiguration mode.To use repository configuration, specify a repository path and a repository cachedirectory, using the -repository_path and -repository_cache_dir options,and a list of rulebases, using the -rulebases option.Use of -rulebases is optional. However, if no RuleBase Map is supplied by therepository, the use of -rulebases is recommended.When Repository Configuration mode is used, omit the following options:-config_path-auto_config_dirRepository mode is also a type of manual configuration mode and operates in asimilar way to Manual Configuration mode. Instead of a configuration path, youspecify a repository path. The agent communicates with a list of repositories inthis path to obtain all configuration objects (rulebases, schedules, and rulebasemaps). Repositories are kept on the network and can be accessed by multipleagents. See the TIBCO Hawk Administrator’s Guide for an explanation ofrepositories.TIBCO Hawk Installation and Configuration

TIBCO Hawk Agent Configuration File (hawkagent.cfg)| 65Unlike Manual Configuration Mode, with Repository mode all configurationobjects loaded from the Repository may be cached in a local directory, specified inthe -repository_cache_dir option. This cache is used in the event of arepository failure, and also to minimize network traffic. Agents can determine if aconfiguration object in their cache is identical to the one in the repository and willload it directly from the cache or update it from the Repository as appropriate.-M AMIServiceThis module of the agent configuration file deals with the following commandline option which relates to monitoring an AMI-instrumented application.-ami_rvd_session Applications instrumented with AMI must create and use a TIBCO Rendezvoussession to connect with a TIBCO Rendezvous daemon (rvd).To monitor an AMI instrumented application that uses the same sessionparameters as those used in the Self section of the agent configuration file (theprimary session), omit the AMIService options.To monitor AMI instrumented applications that use different session parametersthan those used in the TIBCO Hawk configuration, you must create additionalAMI sessions.If you use these options, all three parameters must be present and separated bywhite space. Use an empty string to indicate a null value, for example:-ami_rvd_session 7474 "" tcp:7474You can specify any number of additional TIBCO Rendezvous sessions for aTIBCO Hawk agent to monitor. Applications using these sessions appear asprimary sessions in the TIBCO Hawk Display in the same list as managedapplications (and microagents). TIBCO Hawk agents can use rulebases that referto the applications, as long as those applications are running.See Creating a TIBCO Rendezvous Session, page 85, for more on definingsessions.When using TIBCO EMS as the primary transport, if neither -rvd_session nor-ami_rvd_session is specified, a TIBCO Rendezvous session for the AMIinstrumented applications is created using null values. If -rvd_session isspecified but not the -ami_rvd_session, TIBCO Rendezvous session for the AMIinstrumented applications uses the one created by the -rvd_session parameter.When using TIBCO EMS as the primary transport, it is recommended that theloopback interface address (127.0.0.1) be used as the network parameter. Forexample,-ami_rvd_session 7474 127.0.0.1 tcp:7474.TIBCO Hawk Installation and Configuration

66 Chapter 6 Configuring TIBCO Hawk Software|-M LogServiceThis module of the agent configuration file deals with the following commandline options which relate to log files used by this agent.-log_dir -log_max_size -log_max_num -log_format The TIBCO Hawk system creates rolling log files for agent events (Hawk.log) inthe directory named in the -log_dir option.When one file has reached the size specified in the -log_max_size option, it isclosed and renamed, and a new log file with the same name is started. When thenumber of log files exceeds the number set in the -log_max_size option, logentries roll over to reuse the oldest log file.By default, the unit of measure for -logmaxsize is kilobytes and the default sizeis 1024. To specify a value in megabytes, use the suffix m or M. For example, 10Mspecifies ten megabytes.If, for example, you have configured a maximum of five log files, log files roll overuntil there are five files (named file1, file2… file5). At this point, the nextrollover eliminates file5 and renames file4 to file5, thus maintaining a totalof five rollover files. The log thus retains the latest log information and discardsthe oldest.The -log_format option allows you to select the format of log file entries. Eitherthe existing Hawk format or the Active Enterprise format can be specified.TIBCO Hawk Installation and Configuration

TIBCO Hawk Agent Configuration File (hawkagent.cfg)| 67-M TIBProtocolAdapterTable 12 -M TIBProtocolAdapter OptionsThis module of the agent configuration file deals with the following commandline options which relate to agent heartbeat and security used by this agent.Option-intervalDescriptionThe TIBCO Hawk agent heartbeat interval can be set on each computerwhere an agent is installed. The TIBCO Hawk Display uses this value todetermine when to mark an agent dead.To use the default value of 30 seconds, omit this option. To use a differentvalue, enter a number of seconds, as desired.-security_policyTIBCO Hawk provides a mechanism by which you can develop your ownsecurity policy plug-in. To create a security policy, you must write a Java classthat implements a security policy specific to your needs.(For more information on creating a security policy class, see the TIBCO HawkProgrammer’s Guide. For more information on the Trusted security policy, seeChapter 11 on page 155.)Depending on your security needs, complete this option as follows:• If you are not using a security policy, omit this option.• To use the TIBCO Hawk Trusted Security Policy, specify:COM.TIBCO.hawk.security.trusted.TrustedorCOM.TIBCO.hawk.security.trusted.TrustedWithDomainTo use a specific security policy, specify the name of the security policy classon each machine where you want to use the policy. Ensure that this class fileis placed in /Java. Do not enter the fileextension. For example, if your Java class file is namedASecurityPolicy.class you would specify ASecurityPolicy.Note: If your security policy class is not part of the default package (forexample, if you used the Java "package" directive in your code), you willneed to create the appropriate directory structure beneath /Java that corresponds to your package name and placeyour class file in the appropriate location. For example, if your fully qualifiedclass name is com.mycorp.MySecurity, you will place MySecurity.class in/Java/com/mycorp.TIBCO Hawk Installation and Configuration

68 Chapter 6 Configuring TIBCO Hawk Software|-M RepositoryThis module of the agent configuration file deals with the following commandline options which relate only to agents used as repositories for the TIBCO Hawksystem.-repository_name -repository_dir If a TIBCO Hawk agent is to act as a repository for the TIBCO Hawk system, entera name (with no spaces or periods) for the repository and a path for storage of theconfiguration object files.If these options are not specified, the agent does not start as a repository.-M LogfileMicroAgentTable 13 -M LogfileMicroAgent OptionsThis module of the agent configuration file deals with the following commandline options which relate to agent heartbeat and security used by this agent. Wecan also selectively load or unload the custom microagent by commenting oruncommenting the -M LogfileMicroAgent option.Option-scan_rate -block_size < size in kilobytes>-eval_rate DescriptionThe TIBCO Hawk agent scan rate is the rate at which logfiles arescanned. The default scan rate is 10 seconds. To use the defaultvalue of 10 seconds, omit this option. To use a different value,enter a number in the range of 0 to 2147483647 (seconds).The TIBCO Hawk agent block size is the maximum number ofkilobytes to read on each scan. The default value is 16 kilobytes. Touse the default value of 16 kilobytes, omit this option. To use adifferent value, enter a number in the range of 1 to 2147483647(KB).The TIBCO Hawk agent eval rate is the rate at which all thelogfiles being monitored are re-evaluated. The default eval rate is300 seconds. To use the default value of 300 seconds, omit thisoption. To use a different value, enter a number in the range of 300to 2147483647 (seconds).TIBCO Hawk Installation and Configuration

TIBCO Hawk Agent Configuration File (hawkagent.cfg)| 69-M CustomMicroAgentTable 14 -M CustomMicroAgent OptionsThis module of the agent configuration file deals with the following commandline option which relates to the timeout value. We can also selectively load orunload the custom microagent by commenting or uncommenting the -MCustomMicroAgent option.Option-timeout DescriptionThe timeout value for commands executed by the custommicroagent.TIBCO Hawk Installation and Configuration

70 Chapter 6 Configuring TIBCO Hawk Software|TIBCO Hawk HMA Configuration File (hawkhma.cfg)The options in the hawkhma.cfg configuration file are used to configuremicroagent-related functions:Table 15 hawkhma.cfg Functions and OptionsFunctionTIBCO Rendezvous (RVD)SessionLogging InformationOptions-rvd_session -logdir -logmaxsize -logmaxnum -log_format TimeoutTrace LevelUNIX Signal Handling-timeout -tracelevel -ignore_sigint-ignore_sigterm-ignore_sigabrtTIBCO Rendezvous (RVD) Session-rvd_session Because the TIBCO Hawk software uses the functionality of the TIBCORendezvous system, it must connect to a TIBCO Rendezvous daemon by creatinga session.If TIBCO Rendezvous is only used on one network and no special TIBCORendezvous sessions are needed, use the TIBCO Rendezvous daemon sessiondefault values. To use the default session parameters (specified in the Self moduleof the agent configuration file), omit the -rvd_session command-line options.If you use this option, all three parameters must be present and separated bywhite space. Use an empty string to indicate a null value, for example:-rvd_session 7474 "" tcp:7474See Creating a TIBCO Rendezvous Session, page 85, for more details.TIBCO Hawk Installation and Configuration

TIBCO Hawk HMA Configuration File (hawkhma.cfg)| 71Logging Information-logdir -logmaxsize -logmaxnum -log_format The TIBCO Hawk system creates rolling log files for microagent events in thedirectory named in the -logdir option.The HMA produces a log file for each of its microagents and names them usingthe format hawk_.log, for example, hawk_performance.log.When one file has reached the size specified in the -logmaxsize option, it isclosed and renamed, and a new log file with the same name is started. When thenumber of log files exceeds the number set in the -logmaxsize option, log entriesroll over to reuse the oldest log file.By default, the unit of measure for -logmaxsize is kilobytes and the default sizeis 1024. To specify a value in megabytes, use the suffix m or M. For example, 10Mspecifies ten megabytes.If, for example, you have configured a maximum of five log files, log files roll overuntil there are five files (named file1, file2… file5). At this point, the nextrollover eliminates file5 and renames file4 to file5, thus maintaining a totalof five rollover files. The log thus retains the latest log information and discardsthe oldest.The -log_format option allow you to select the format of log file entries. Eitherthe existing Hawk format or the Active Enterprise format can be specified.Timeout-timeout Specifies the amount of time the Hawk Agent should wait for HMA methodinvocations to complete before timing them out. The default is 10000milliseconds. Normally there is no need to change this value, however, onmachines under extreme stress where method invocations are timing out, thisnew option allows the timeout value to be increasedTrace Level-tracelevel TIBCO Hawk Installation and Configuration

72 Chapter 6 Configuring TIBCO Hawk Software|Specifies the level of diagnostic trace output. You can choose -1 to enable alltracing, 0 to enable no tracing, or calculate a desired trace level by adding togethervalues from the following table:Value Purpose1 enables information level trace messages2 enables warning level trace messages4 enables error level trace messages8 enables debug level trace messages16 enables AMI level trace messages32 adds source filename and line numbers to all tracemessagesThe default value for tracing is 7, or 1+2+4 (information, warning and error).UNIX Signal Handling-ignore_sigint-ignore_sigterm-ignore_sigabrtThese options specify that the TIBCO Hawk HMA should ignore the SIGINT,SIGTERM, and SIGABRT signals, respectively. These options will cause the HMAto set the disposition of the corresponding signal to SIG_IGN.By default, the HMA installs a signal handler for these signals that performs agraceful shutdown of the HMA in response to one of these signals. For mostcircumstances, this is the desired behavior and these options would not bespecified.These options can be used to configure the HMA not to shutdown or terminate inresponse to any of these signals. For example, the HMA can be started as abackground process from a UNIX console with -ignore_sigint so that the HMAwill not be shutdown if Ctrl-C is entered from the console.TIBCO Hawk Installation and Configuration

TIBCO Hawk Event Service Configuration File (hawkevent.cfg)| 73TIBCO Hawk Event Service Configuration File (hawkevent.cfg)The TIBCO Hawk Event Service has two main purposes: to record the activity ofTIBCO Hawk agents, and to detect and respond to agent termination.The event service records:• all alerts raised and cleared by TIBCO Hawk agents across the network, aswell as changes in an agent’s alert level (as would be shown by a color in theTIBCO Hawk Display)• all instances of agent activation and expirationThe event service also can call a script (using the -script option in the EventService configuration file) when the heartbeat of a TIBCO Hawk agent is lost (notreceived for a specified length of time). This usually means that the agent processhas terminated or that network communication has been interrupted. This facilitycould be used to send an e-mail or page, or to take some other automated action.You will normally run the TIBCO Hawk Event Service on a single system in aTIBCO Hawk managed network. Multiple instances can be run on separatesystems for fault tolerance.If you want to configure the TIBCO Hawk Event Service to write Hawk alerts andchanges in agent status to a database, make sure you have specified values for thefollowing fields:• -JDBCdriverClassName• -JDBCuserName• -JDBCpassword• -JDBCurl• -JDBCalertTableFieldsSee Table 16, hawkevent.cfg Options, on page 74 for a description of these fields.Additionally make sure the JAR files for the database client have been included inthe classpath.Be careful not to confuse TIBCO Hawk Event Service data files (Event.dat) withEvent Service log files (Event.log).• Event.dat data files contain the data produced by the Event Service.• Event.log log files record the state of the Event Service itself.The Event.log file is discussed in the TIBCO Hawk Administrator’s Guide.TIBCO Hawk Installation and Configuration

74 Chapter 6 Configuring TIBCO Hawk Software|Configuring the Event ServiceTable 16 hawkevent.cfg OptionsThe Event Service is configured through a command-line interface. The optionsare described below.Option-hawk_root-hawk_domain-rvd_sessionDescriptionThe TIBCO Hawk root installation directory.Sets the hawk domain name. The agents and the event service musthave the same hawk domain value in order to communicate.The default is to monitor an entire network as one group. To use thedefault, omit this option. See the TIBCO Hawk Installation andConfiguration Guide for more details.Separate domains create independent TIBCO Hawk systems.Specifies the TIBCO Rendezvous session used by TIBCO HawkEvent Service.This option must be omitted if using TIBCO EMS as the primarytransport.If you use this option, the following three parameters must bepresent and separated by white space:-rvd_session Use an empty string to indicate a null value. For example:-rvd _session 7474 "" tcp:7474The default session uses null values.If TIBCO Rendezvous is only used on one network and no specialTIBCO Rendezvous sessions are needed, you can omit thisparameter to use the default TIBCO Rendezvous daemon sessionvalues. Those values are specified in the Self module of the agentconfiguration file.See the TIBCO Hawk Installation and Configuration Guide for moredetails.TIBCO Hawk Installation and Configuration

TIBCO Hawk Event Service Configuration File (hawkevent.cfg)| 75Table 16 hawkevent.cfg Options (Cont’d)Option (Cont’d)-ems_transportDescription (Cont’d)Specifies the TIBCO EMS transport parameters used by TIBCOHawk Event Service.There are 2 ways of specifying the TIBCO EMS transport• Using only one argument, serverURL, for example-ems_transport tcp://dev_server:7222If communicating with the EMS server using SSL, specify thelocation of the EMS server as follows for the above example:-ems_transport ssl://server1:7222• Specify the location of the EMS server and a valid username andpassword for the EMS server. These parameters are separated bya space and can be an empty string to indicate a null value.-ems_transport tcp://dev_srv:7222 admin "#!NhAD1C"If communicating with the EMS server using SSL, specify thelocation of the EMS server as follows for the above example :-ems_transport ssl://server1:7222 admin "#!NhAD1NBC"For instructions to modify the password which was specifiedduring installation, see Handling Passwords for TIBCO EMSTransport on page 43.Re-Connection SetupTo ensure the TIBCO EMS client attempts re-connection after losingconnection to the EMS server, repeat the server URL in the URL list.For example,-ems_transport tcp://H1:7222,tcp://H1:7222TIBCO Hawk Installation and Configuration

76 Chapter 6 Configuring TIBCO Hawk Software|Table 16 hawkevent.cfg Options (Cont’d)Option (Cont’d)-ems_transport(Contd)Description (Cont’d)Fault Tolerance SetupYou can specify backup servers to connect to in the event of thefailure of the primary server. The serverURLs for the primary andbackup server(s) are specified as a comma-separated list of URLs.For example,-ems_transport tcp://server1:7222,tcp://server2:7344If a connection to the first URL fails, the next URL in the list is usedto attempt a reconnection. The connections in the list are attemptedin sequence (wrapping to the start of the list, if the first connectionwas not the failed connection) until all URLs have been tried. If noconnection is established after all URLs have been tried, theconnection fails.In addition to specifying the -ems_transport options, thefollowing parameters in the EMS server configuration file,tibemsd.conf, should be considered:• ft_active, the name of the active server.• ft_reconnect_timeout, the amount of time a backup serverwaits for clients to reconnect.• store, the directory to store TIBCO EMS data.For more information, refer to the TIBCO Enterprise Message Servicedocumentation.Using SSL to connect to the EMS ServerWhen using SSL to connect to the EMS Server, the following optionsare used:-ssl_vendor-ssl_cipherTIBCO Hawk Installation and Configuration

TIBCO Hawk Event Service Configuration File (hawkevent.cfg)| 77Table 16 hawkevent.cfg Options (Cont’d)Option (Cont’d)-ems_transport(Contd)Description (Cont’d)In addition, the following sets of options are used:For TIBCO Hawk components to verify the EMS server-ssl_no_verify_host-ssl_trusted-ssl_no_verify_hostname-ssl_expected_hostnameIf the -ssl_no_verify_host is not specified, the option-ssl_trusted has to be used. Along with the option-ssl_trusted specify either -ssl_no_verify_hostname or-ssl_expected_hostname.For the EMS server to verify TIBCO Hawk components:-ssl_identity-ssl_private_key-ssl_password-ssl_vendor Specifies the name of the vendor of the SSL implementation.The valid choices are:• j2se-defaultUse this option when you want to use the default JCE bundledwith the Java JRE.On IBM platforms (such as AIX), this option defaults to ibm.• j2se• entrust61Use this option when you want to use the Entrust libraries.• ibmOn non-IBM platforms, this option can be used only if the IBMversion of JCE is installed.-ssl_no_verify_host-ssl_trusted Specifies that the TIBCO Hawk component should not verify theserver. Conversely, if this option is not included in the configurationfile, it indicates that TIBCO Hawk component should verify theserver.Specifies the file name of the server certificates. This option can berepeated if more than one certificate file is used.TIBCO Hawk Installation and Configuration

78 Chapter 6 Configuring TIBCO Hawk Software|Table 16 hawkevent.cfg Options (Cont’d)Option (Cont’d)-ssl_expected_hostnameDescription (Cont’d)Specifies the name that is expected in the name of the CN field ofthe server certificates.The value specified by this option is used when the-ssl_no_verify_hostname option absent from the configurationfile.-ssl_identity Specifies the digital certificate of the TIBCO Hawk components.-ssl_private_key-ssl_password -ssl_no_verify_hostname-ssl_ciphers-ami_rvd_sessionSpecifies the private key of the TIBCO Hawk component.If the key is included in the digital certificate in -ssl_identity,then you may omit this parameter.Specifies the password to decrypt the identity file of the Hawkcomponent.For details, see Handling Passwords for TIBCO EMS Transport onpage 43.Specifies that the client should not verify the name in the CN field ofthe server certificate. Conversely, if this option is not included in theconfiguration file, it indicates that TIBCO Hawk component shouldverify the name in the CN field of the server certificate.Specifies the cipher suites that can be used. When specifying thisoption, use the ^ qualifier instead of a - qualifier. For moreinformation on specifying cipher suites, refer to the TIBCOEnterprise Message Service documentation.Specifies the TIBCO Rendezvous (rvd) session used by the TIBCOHawk Event Service for AMI communications. If this options isused, all three parameters must be present and separated bywhitespace but any of them may be an empty string to indicate anull value.When using TIBCO EMS as the primary transport, it isrecommended that the loopback interface address (127.0.0.1) beused as the network parameter. For example,-ami_rvd_session 7474 127.0.0.1 tcp:7474.See Using AMI applications with TIBCO EMS Transport on page 43for details.The default ami_rvd_session uses rvd_session values.TIBCO Hawk Installation and Configuration

TIBCO Hawk Event Service Configuration File (hawkevent.cfg)| 79Table 16 hawkevent.cfg Options (Cont’d)Option (Cont’d)-character_encoding-datadirDescription (Cont’d)Specifies the character encoding to be used for strings sent over allTIBCO Rendezvous transports.The directory in which TIBCO Hawk will create rolling data files(event.dat) for the event service. Default is /data.-datamaxnum The maximum number of rolling data files to keep. The default is 5.Values lower than the default number are ignored, and the default isused instead.-datamaxsize-ft-ft_rvd_sessionWhen one rolling data file has reached this size, it is closed andrenamed, and a new data file with the original name is started.By default, the unit of measure for -datamaxsize is kilobytes andthe default size is 1024. To specify a value in megabytes, use thesuffix m or M. For example, 10M specifies ten megabytes. Valueslower than the default size are ignored, and the default is usedinstead. You can, however, enter a value greater than the default.Fault Tolerant weight for TibrvFtMember. Default is no faulttolerance.Specifies the TIBCO Rendezvous session used for fault tolerance byTIBCO Hawk Event Service.If you use this option, the following three parameters must bepresent and separated by white space:-ft_rvd_session Use an empty string to indicate a null value. For example:-ft_rvd _session 7474 "" tcp:7474When using TIBCO EMS as the primary transport, a Rendezvoussession using default values is created.When using TIBCO Rendezvous as the primary transport, if thisfield is not specified, the primary Rendezvous session is used forfault tolerance.When specifying a remote daemon, use the fully qualified domainname of the host. For example,-ft_rvd _session 7474 ""tcp:host1.mycompany.com:7474This option is ignored if the -ft option is not specified.TIBCO Hawk Installation and Configuration

80 Chapter 6 Configuring TIBCO Hawk Software|Table 16 hawkevent.cfg Options (Cont’d)Option (Cont’d)-JDBCalertTableFieldsDescription (Cont’d)User-defined, comma-separated alert action property fields of typeVARCHAR(256) to be created as additional columns in theHawkAlertClearInfo table. When the event service receives an"onAlert" event that contains the specified properties, thecorresponding values are inserted into the database. For example,the command-JDBCalertTableFields x, y, zcreates three additional columns (x, y and z) of typeVARCHAR(256) in the HawkAlertClearInfo table.-JDBCdriverClassName Class name for the vendor's JDBC driver as described in Table 17.-JDBCuserName-JDBCpasswordUser name to connect to the database.User password to connect to the database.-JDBCurl URL that identifies the database connection as specified in Table 18.-JDBCdbType-log_format-logdir-logmaxnum-logmaxsize-scriptDatabase vendor name. Supported values are SQLSERVER, ORACLE,DB2, INFORMIX and SYBASE.The format of log file entries. Valid values are default (Hawkformat) or ae4 (Active Enterprise format).The directory in which to store Event.log files generated by TIBCOHawk Event Service. To print all log messages to the screen, omitthis option.The maximum number of rolling log files to keep. When thenumber of rolling log files exceeds this number, log entries roll overto reuse the oldest log file. The default is 4. Values lower than thedefault number are ignored, and the default is used instead.When one rolling log file has reached this size, it is closed andrenamed, and a new log file with the original name is started.By default, the unit of measure for -logmaxsize is kilobytes and thedefault size is 1024. To specify a value in megabytes, use the suffixm or M. For example, 10M specifies ten megabytes.The script to execute on lost agent heartbeat. Hawk passes the agenthostname and IP address to the script to identify which agent died.TIBCO Hawk Installation and Configuration

TIBCO Hawk Event Service Configuration File (hawkevent.cfg)| 81Table 16 hawkevent.cfg Options (Cont’d)Option (Cont’d)-file-helpDescription (Cont’d)Reads more command line arguments from this file. The file hasexactly the same syntax and semantics as if it were a continuation ofthe command line. If you supply -file, it must be the lastparameter on the command line. You may supply no more than one-file parameter.Prints a help message.Configuring the Event Service with an External DatabaseBefore starting any tasks, you must obtain the JDBC driver from the databasevendor, and deploy it in a location that is listed in the classpath. We recommendplacing the driver .jar file one of these directories (as appropriate):• TIBCO_HOME /tibcojre/1.6.0/lib/ext• TIBCO_HOME/tibcojre64/1.6.0/lib/extConfiguration ValuesThis section presents values that you must enter when you do the configurationsteps in subsequent sections.After configuration, start the Event Service with the hawkevent.cfg file that ispassed as the config file parameter - file.DriverTable 17 Database Configuration Value: DriverDatabaseOracle 10g, 11gOracle RACMS SQL Server 2008DB2 9.xSybase 15.xDriver Stringoracle.jdbc.OracleDrivercom.microsoft.sqlserver.jdbc.SQLServerDrivercom.ibm.db2.jcc.DB2Drivercom.sybase.jdbc3.jdbc.SybDriverTIBCO Hawk Installation and Configuration

82 Chapter 6 Configuring TIBCO Hawk Software|Connection StringThe connection strings in Table 18 incorporate elements that can vary:• Hostname identifies the database host computer.• PortNumber is the TCP port where the database accepts connections. (Unlessyou specify a port, Microsoft configures port 1433.)• DatabaseName identifies the database. This element is required.• DBinstance identifies a specific database instance within Microsoft SQL Server2008.Table 18 Database Configuration Value: Connection (Sheet 1 of 2)DatabaseOracle 10g, 11gOracle RACConnection Stringjdbc:oracle:thin:@Hostname:PortNumber:DatabaseNameOracle has a synonym for the DatabaseName—the system ID (SID).Use either of these two formats.• If you know the service name of the Oracle RAC, use this format:jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=Hostname_1)(PORT=PortNumber_1))(ADDRESS=(PROTOCOL=TCP)(HOST=Hostname_2)(PORT=PortNumber_2))(LOAD_BALANCE=yes)(FAILOVER=on)(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=ServiceName)))• If you know the SID names of the Oracle RAC nodes, use this format:jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=Hostname_1)(PORT=PortNumber_1)(SID=DatabaseName_1))(ADDRESS=(PROTOCOL=TCP)(HOST=Hostname_2)(PORT=PortNumber_2))(LOAD_BALANCE=yes)(CONNECT_DATA=(SID=DatabaseName_2)))You can add as many ADDRESS clauses as needed.MS SQL Server 2008jdbc:sqlserver://Hostname\DBinstance:PortNumber;DatabaseName=DatabaseName;If your database is not configured with instances, you may omit theDBinstance, and the preceding backslash (\) character. The default value isthe null string (which corresponds to the default instance, MSSQLSERVER).You may omit the PortNumber, and the preceding colon (:) character. Thedefault value is port 1433.TIBCO Hawk Installation and Configuration

TIBCO Hawk Event Service Configuration File (hawkevent.cfg)| 83Table 18 Database Configuration Value: Connection (Sheet 2 of 2)DatabaseDB2 9.xSybase 15.xConnection Stringjdbc:db2://Hostname:PortNumber/DatabaseNamejdbc:sybase:Tds:Hostname:PortNumber/DatabaseNameTIBCO Hawk Installation and Configuration

84 Chapter 6 Configuring TIBCO Hawk Software|Creating a TIBCO Hawk DomainCreate a TIBCO Hawk domain if you wish to isolate groups of TIBCO Hawkagents into independent monitoring sets. Remember that each TIBCO Hawkagent can belong to only one TIBCO Hawk domain and cannot communicate withthe TIBCO Hawk Display program on other domains.The default is to monitor an entire network as one group. To use the default, omitthe -hawk_domain option.Testing a DomainTo test the domain option, temporarily set the TIBCO Hawk domain on a singlesystem to a name such as test, then start (or restart) the TIBCO HawkDisplay. If you entered a unique domain name, only one discovered host shouldappear in the TIBCO Hawk Display main window. This shows that only the localagent and the local TIBCO Hawk Display are using the test domain.If the domain is as desired, you can now install it on the network systems whereyou want to assign specific computers to that domain. All systems assigned tothat TIBCO Hawk domain appear on the Display as part of that domain.When finished with testing, change back to the default domain and restart theTIBCO Hawk Display to verify that it was correctly restored.TIBCO Hawk Installation and Configuration

Creating a TIBCO Rendezvous Session| 85Creating a TIBCO Rendezvous SessionA TIBCO Rendezvous session is a direct conduit through which an applicationand a TIBCO Rendezvous daemon communicate.Default Session ValuesIf TIBCO Rendezvous is only used on one network and no special TIBCORendezvous sessions are needed, use the TIBCO Rendezvous daemon sessiondefault values.To use the default TIBCO Hawk session parameters with port 7474, omit the-rvd_session command-line options.If you use this option, all three parameters must be present and separated bywhite space. Use an empty string to indicate a null value, for example:-rvd _session 7474 "" tcp:7474Setting up a TIBCO Rendezvous Daemon SessionThis section provides a brief overview of session parameters used to set up aTIBCO Rendezvous Daemon (RVD) session for TIBCO Hawk monitoring. TheService parameter specifies which User Datagram Protocol (UDP) service groupthe TIBCO Rendezvous daemon should use for session communications. Thedefault configuration uses the service port number 7474. A service can bespecified either by its name or its port number.• The Network parameter specifies what network to use for outbound sessioncommunications when a computer is connected to more than one network. Anetwork can be specified by its name or by its IP address. This parameter isalso used to specify the multicast groups to use for communication.When using TIBCO EMS as the primary transport, it is recommended that theloopback interface address (127.0.0.1) be used as the network parameter.For more information, see Using AMI applications with TIBCO EMSTransport on page 43.• The Daemon parameter specifies which TIBCO Rendezvous daemon is tohandle communication for the session. A local daemon is specified by thecommunications type (always tcp) and a socket number (e.g., 7474). Thedefault configuration uses the local daemon with the TCP socket number7474.Specify a remote daemon by inserting its host name or IP address between thetcp entry and the port number of the daemon parameter, for example:TIBCO Hawk Installation and Configuration

86 Chapter 6 Configuring TIBCO Hawk Software|tcp:remote_computer:7800For more information on interacting with TIBCO Rendezvous daemons andsessions, refer to the books TIBCO Rendezvous Concepts and the TIBCO RendezvousAdministrator’s Guide.TIBCO Hawk Installation and Configuration

| 87Chapter 7Using the Configuration UtilityThis chapter explains how to configure TIBCO Hawk using the ConfigurationUtility GUI.The Configuration Utility GUI interface is available only on Windows platforms.For UNIX, all TIBCO Hawk configuration is done by modifying the .cfg files.This is discussed in Chapter 6, Configuring TIBCO Hawk Software.Topics• Configuration Utility Overview, page 88• General Configuration, page 89• Transport Configuration, page 95• TIBCO Hawk Display Configuration, page 105• TIBCO Hawk Agent Configuration, page 107• TIBCO Hawk Event Service Configuration, page 113TIBCO Hawk Installation and Configuration

88 Chapter 7 Using the Configuration Utility|Configuration Utility OverviewWhen the TIBCO Hawk installation program is finished on Microsoft Windows, itautomatically starts the TIBCO Hawk configuration utility. The configurationutility can also be run at any time by selecting Start > Programs > > TIBCO Hawk > Hawk Configuration.The tabs in the configuration utility correspond to the four configuration filesdescribed in Chapter 6, Configuring TIBCO Hawk Software.TIBCO Hawk Installation and Configuration

General Configuration| 89General ConfigurationThe General tab contains basic TIBCO Hawk configuration items common to allTIBCO Hawk components. When you start TIBCO Hawk, the fields in thesedialogs are populated with values appropriate for your configuration. In mostcases, you do not need to change those values.Figure 1 General ConfigurationDomain InformationSeparate domains create independent TIBCO Hawk systems. Each TIBCO Hawkagent can belong to only one TIBCO Hawk domain and cannot communicate withTIBCO Hawk Display programs monitoring on other domains. Use TIBCO Hawkdomains if you want to isolate groups of TIBCO Hawk agents into independentmonitoring sets.Leave the Hawk Domain field blank to use the default domain.TIBCO Hawk Installation and Configuration

90 Chapter 7 Using the Configuration Utility|To give the agent a domain name, enter the desired name in the Hawk Domainfield. Give this same name to all agents that you want to include in the domain,when you configure them on the systems where they are installed. The domainyou enter here is used for both the TIBCO Hawk agent and for any instance of theTIBCO Hawk Display program running on that system.SecurityBecause security needs vary greatly, the TIBCO Hawk system provides amechanism by which you can develop your own security policy plug-in. To createa security policy, you must write a Java class that implements a security policyspecific to your needs. For more information on creating a security policy class,see the TIBCO Hawk Programmer’s Guide.For more information on the Trusted and Certified security policies that comewith TIBCO Hawk software, see Chapter 11 on page 155.Depending on your security needs, complete the Security Policy field as follows.• If you are not using a security policy, leave the Security Policy Class fieldblank.• To use the TIBCO Hawk Trusted Security Policy, enter:COM.TIBCO.hawk.security.trusted.TrustedorCOM.TIBCO.hawk.security.trusted.TrustedWithDomain• To use a specific security policy, on each machine where you want to use thepolicy, enter the name of the security policy class. Ensure that this class file isplaced in \Java. Do not enter the fileextension. For example, if your Java class file is namedASecurityPolicy.class you would enter ASecurityPolicy.If your security policy class is not part of the default package (for example, ifyou used the Java "package" directive in your code), you will need to createthe appropriate directory structure beneath \Java that corresponds to your package name and place your classfile in the appropriate location. For example, if your fully qualified class nameis com.mycorp.MySecurity, you will place MySecurity.class in \Java\com\mycorp.TIBCO Hawk Installation and Configuration

General Configuration| 91LoggingThe TIBCO Hawk system logs specific events as they occur. The events arecategorized as errors, warnings, or informational events. The logs provide adetailed picture of the status and health of each of the TIBCO Hawk componentsto aid in diagnosing problems.The settings configured in the Logging panel control logging of the followingcomponents:• The TIBCO Hawk agent (Hawk.log).• The TIBCO Hawk Display (Display.log).• The TIBCO Hawk Event Service (Event.log).Log to Windows Event LogEnable this setting to log TIBCO Hawk events in the Application section of theWindows Event Log.These events can be viewed using the Windows Event Viewer. To access theviewer, select Start>Programs>Administrative Tools>Event Viewer, then selectLog>Application from the Event Viewer menu to view Application events.Events logged by the TIBCO Hawk system contain the component name (forexample, the TIBCO Hawk agent) under the Source column.Log to Hawk Log FilesEnable this setting to log TIBCO Hawk events using a set of log files in thedirectory you specify in the Log Files Directory field.The TIBCO Hawk system creates rolling log files for each component; when onefile has reached the size specified in the Maximum Size of Log Files field, it isclosed and renamed, and a new log file with the same name is started. When thenumber of log files exceeds the number set in the Maximum Number of Log Filesfield, log entries roll over to reuse the oldest log file. If, for example, you haveconfigured a maximum of five log files, log files roll over until there are five files(named file1, file2… file5). At this point, the next rollover eliminates file5and renames file4 to file5, thus maintaining a total of five rollover files. Thelog thus retains the latest log information and discards the oldest.• Log Files DirectoryEnter the name of the directory where the TIBCO Hawk system should placeits log files. The default value isTIBCO_CONFIG_FOLDER\tibco\cfgmgmt\hawk\log.• Maximum Number of FilesTIBCO Hawk Installation and Configuration

92 Chapter 7 Using the Configuration Utility|Enter the maximum number of rolling log files to create. You can enter atminimum 5 and at maximum 999. The default value is 5.• Maximum Size of Log FileIn this edit field, enter the maximum log file size, in kilobytes. Enter onlydigits. The default is 1024. Note that the maximum log file size is 2097151kilobytes.Log Message FormatThis field allow you to select the format of log file entries. Either the existingHawk format (Default) or the ActiveEnterprise format (ae4) can be specified.HMA ConfigurationAMI TimeoutSpecifies the amount of time the Hawk Agent should wait for HMA methodinvocations to complete before timing them out. The default is 10000milliseconds. Normally there is no need to change this value, however, onmachines under extreme stress where method invocations are timing out, thisoption allows the timeout value to be increased.CodepageThe Codepage configuration option indicates the desired character encoding to beused by the HMA when converting multi-byte characters (MBCS) to UNICODE.The default codepage identifier is 65001, which is the Microsoft Windows ID forUTF-8, and which will work for all locales.The only reason to change this value is for compatibility with other TIBCORendezvous applications not using UTF-8. This value is specified using MicrosoftWindows code page values, as listed at the following URL:http://msdn.microsoft.com/library/default.asp?url=/library/en-us/intl/unicode_81rn.aspIf you change the Codepage value, you must also change the value of theCharacter Encoding, page 94. For example, if you want to specify Latin-1 locales(such as French), the Codepage value must be 1252 and the Character Encodingvalue must be ISO-8859-1. See Code Page Identifiers on page 195 for the list ofcode page identifiers.TIBCO Hawk Installation and Configuration

General Configuration| 93Advanced ConfigurationOn the General configuration tab, click the Advanced button to access theAdvanced Configuration dialog.Figure 2 Advanced ConfigurationConfiguration File OptionsThis section allows you to specify configuration files (such as hawkagent.cfg).When you specify a configuration file, the values in that file override thecorresponding values entered into the configuration utility.For example, if an option in the configuration file you select is blank but a customvalue is specified for that option in the configuration utility, TIBCO Hawk will usethe default (blank) value for that option.TIBCO Hawk Installation and Configuration

94 Chapter 7 Using the Configuration Utility|Character EncodingThe Character Encoding configuration option indicates the desired characterencoding to be used by the Agent, Display, and Event Service. This is also theencoding used for the character data that TIBCO Hawk transmits over TIBCORendezvous.The default setting of UTF-8 will work for all locales. The only reason to changethis setting is for compatibility with other TIBCO Rendezvous applications. If youchange this value, you must also change the Codepage value, which sets thecharacter encoding for the TIBCO Hawk HMA.Possible Character Encoding values are listed in Table 31, Code Page Identifiers,on page 196.Custom Microagent ConfigurationSelect or unselect the Enable checkbox in the Advanced Configuration dialog boxto selectively load or unload the custom microagent.TIBCO Hawk Installation and Configuration

Transport Configuration| 95Transport ConfigurationThis tab contains information specific to the chosen messaging transport.Primary TransportYou can specify either TIBCO Rendezvous or TIBCO EMS as the primarytransport. The communication between TIBCO Hawk HMA and primary AMIsession remains through TIBCO Rendezvous. Which means that if you chooseTIBCO EMS as the primary transport, you still have to specify the TIBCORendezvous settings for the TIBCO Hawk HMA and primary AMI session.Using TIBCO Rendezvous as the TransportThis tab contains details of the TIBCO Rendezvous settings which will be used forcommunication by all TIBCO Hawk components. Because the TIBCO Hawksoftware uses the functionality of the TIBCO Rendezvous system, it must connectto a TIBCO Rendezvous daemon by creating a session.The following processes in the TIBCO Hawk system communicate with a TIBCORendezvous daemon through sessions:• TIBCO Hawk Agent• TIBCO Hawk HMA• TIBCO Hawk Display• TIBCO Hawk Event ServiceTIBCO Hawk Installation and Configuration

96 Chapter 7 Using the Configuration Utility|Figure 3 Transport Configuration using TIBCO RendezvousRendezvous Settings for All Hawk ComponentsA TIBCO Rendezvous session is a direct conduit through which an applicationand a TIBCO Rendezvous daemon communicate.For details on the parameters of the TIBCO Rendezvous session used by theTIBCO Hawk HMA for communicating with the primary AMI session see TIBCORendezvous Daemon Session Parameters on page 102.Rendezvous Settings for Addition AMI SessionsApplications instrumented with AMI must create and use a TIBCO Rendezvoussession to connect with a TIBCO Rendezvous daemon (rvd).To monitor an AMI-instrumented application that uses the same sessionparameters as those used in the TIBCO Hawk configuration, no additional actionis required.TIBCO Hawk Installation and Configuration

Transport Configuration| 97To monitor AMI-instrumented applications that use different session parametersthan those used in the TIBCO Hawk configuration, you must create additionalAMI sessions as required. See AMI Rendezvous Session Configuration onpage 102 for details.Using TIBCO EMS as the TransportThis tabs contains details of the TIBCO EMS settings which will be used forcommunication by all TIBCO Hawk components including TIBCO Hawk HMA.TIBCO Hawk HMA uses TIBCO Rendezvous for communicating with theprimary AMI session.Figure 4 Transport Configuration using TIBCO Enterprise Message ServiceEMS Settings for Console CommunicationThe following processes in the TIBCO Hawk system communicate using TIBCOEMS:• TIBCO Hawk Agent• TIBCO Hawk DisplayTIBCO Hawk Installation and Configuration

98 Chapter 7 Using the Configuration Utility|• TIBCO Hawk Event ServiceThis following parameters are used to connect to the EMS server. For moreinformation on TIBCO EMS, refer to the books TIBCO EMS Installation Guide andTIBCO EMS User’s Guide.• The Server URL parameter is used to connect to the EMS server at thespecified location.• When the TIBCO EMS server has authentication enabled, valid username andpassword parameters enable you to connect to the EMS server.Re-Connection SetupTo ensure the TIBCO EMS client attempts re-connection after losing connection tothe EMS server, repeat the server URL in the URL list. For example,tcp://H1:7222,tcp://H1:7222Fault Tolerance SetupYou can specify backup servers to connect to in the event of the failure of theprimary server. The serverURLs for the primary and backup server(s) arespecified as a comma-separated list of URLs.For example,tcp://server1:7222,tcp://server2:7344If a connection to the first URL fails, the next URL in the list is used to attempt areconnection. The connections in the list are attempted in sequence (wrapping tothe start of the list, if the first connection was not the failed connection) until allURLs have been tried. If no connection is established after all URLs have beentried, the connection fails.In addition to specifying the -ems_transport options, the following parametersin the EMS server configuration file, tibemsd.conf, should be considered:— ft_active, the name of the active server.— ft_reconnect_timeout, the amount of time a backup server waits forclients to reconnect.— store, the directory to store TIBCO EMS data.For more information, refer to the TIBCO Enterprise Message Servicedocumentation.When connecting to the EMS server using SSL, specify the Server URL parameteras follows:ssl://:portand click the Configure SSL button to specify additional SSL parameters. SeeConnecting to TIBCO EMS using SSL on page 100 for details.TIBCO Hawk Installation and Configuration

Transport Configuration| 99The concepts of specifying the user credentials (when the EMS server hasauthentication enabled), re-connection setup, and fault tolerance setup asexplained in the earlier sections are also applicable when using SSL to connect tothe EMS server.Rendezvous Settings for HMA and Primary AMI SessionA TIBCO Rendezvous session is a direct conduit through which an applicationand a TIBCO Rendezvous daemon communicate.For details on the parameters of the TIBCO Rendezvous session used by theTIBCO Hawk HMA for communicating with the primary AMI session see TIBCORendezvous Daemon Session Parameters on page 102.Rendezvous Settings for Addition AMI SessionApplications instrumented with AMI must create and use a TIBCO Rendezvoussession to connect with a TIBCO Rendezvous daemon (rvd).To monitor an AMI-instrumented application that uses the same sessionparameters as those used by the TIBCO Hawk HMA, no additional action isrequired.To monitor AMI-instrumented applications that use different session parametersthan those used by TIBCO Hawk HMA, you must create additional AMI sessionsas required. See AMI Rendezvous Session Configuration on page 102 for details.DefaultsThis button clears all fields and returns them to their default values.TIBCO Hawk Installation and Configuration

100 Chapter 7 Using the Configuration Utility|Connecting to TIBCO EMS using SSLThis dialog contains details of the SSL settings used when connecting to the EMSserver.SSL ConfigurationSpecify the name of the vendor of the SSL implementation in the Vendor field.The valid choices are— j2se-defaultUse this option when you want to use the default JCE bundled with theJava JRE.On IBM platforms (such as AIX), this option defaults to ibm.— j2se— entrust61Use this option when you want to use the Entrust libraries.— ibmOn non-IBM platforms, this option can be used only if the IBM version ofJCE is installed.In the Ciphers field specify the cipher suites that can be used. When specifyingthe cipher suite, use the ^ qualifier instead of a - qualifier. For more informationon specifying cipher suites, refer to the TIBCO Enterprise Message Servicedocumentation.TIBCO Hawk Installation and Configuration

Transport Configuration| 101Settings for Hawk Components to verify EMS serverSelect the Authenticate EMS Server checkbox if you want the TIBCO Hawkcomponents to verify the server.If you want the TIBCO Hawk components to verify the name in the CN field ofthe server certificate, specify it in the Server Name field.Maintain the list of server certificates in the Trusted field using the Add, Edit, andDelete buttons.Settings for EMS server to verify Hawk ComponentsSpecify the digital certificate of the TIBCO Hawk components in the Identityfield.The private key of the TIBCO Hawk component is specified in the Private Keyfield.The password to decrypt the identity file of the TIBCO Hawk component isspecified in the Password field.TIBCO Hawk Installation and Configuration

102 Chapter 7 Using the Configuration Utility|TIBCO Rendezvous Daemon Session ParametersThis section describes the session parameters used to set up a TIBCO RendezvousDaemon (RVD) session for TIBCO Hawk monitoring. If TIBCO Rendezvous is onlyused on one network and no special TIBCO Rendezvous sessions are needed, usethe TIBCO Rendezvous daemon session default values.• The Service parameter specifies which User Datagram Protocol (UDP) servicegroup the TIBCO Rendezvous daemon should use for sessioncommunications. The default configuration uses the service port number7474. A service can be specified either by its name or its port number.• The Network parameter specifies what network to use for outbound sessioncommunications when a computer is connected to more than one network. Anetwork can be specified by its name or by its IP address. This parameter isalso used to specify the multicast groups to use for communication.When using TIBCO EMS as the primary transport, it is recommended that theloopback interface address (127.0.0.1) be used as the network parameter.For more information, see Using AMI applications with TIBCO EMSTransport on page 43.• The Daemon parameter specifies which TIBCO Rendezvous daemon is tohandle communication for the session. A local daemon is specified by thecommunications type (always tcp) and a socket number (e.g., 7474). Thedefault configuration uses the local daemon with the TCP socket number7474.Specify a remote daemon by inserting its host name or IP address between thetcp entry and the port number of the daemon parameter, for example:tcp:remote_computer:7800.For more information on interacting with TIBCO Rendezvous daemons andsessions, refer to the books TIBCO Rendezvous Concepts and the TIBCO RendezvousAdministrator’s Guide.AMI Rendezvous Session ConfigurationTo monitor AMI-instrumented applications that use different session parametersthan those used in the TIBCO Hawk configuration, you must create additionalAMI sessions.You can specify any number of additional TIBCO Rendezvous sessions for aTIBCO Hawk agent to monitor. Applications using these sessions appear asprimary sessions in the TIBCO Hawk Display in the same list as managedapplications (and microagents). TIBCO Hawk agents can use rulebases that referto the applications, as long as those applications are running.TIBCO Hawk Installation and Configuration

Transport Configuration| 103You can add, edit, and delete sessions using the AMI Rendezvous SessionConfiguration dialog. The next section describes how to add a session. Allsessions in the list will be accessible to the TIBCO Hawk agent.To Create an AMI SessionThe Rendezvous Setting for Additional Agent’s AMI Sessions panel of the Transporttab of the TIBCO Hawk Configuration Utility lists any AMI Rendezvous sessionsalready created.1. Do one of the following:— To create a new session click Add. You see the Add AMI RendezvousSession dialog.— To create a new session based on an existing one, highlight the desiredsession and click Derive. You see the Add AMI Rendezvous Session dialog(Figure 5), showing the values for the session you selected. Change theSession Name and other values as required (see next steps).Figure 5 Add AMI Rendezvous Session2. Enter a Session Name.3. In the Session Parameters panel, enter values for Service, Network, andDaemon. Use the same values as those used by the application to initialize itsTIBCO Rendezvous daemon session. To determine these values, check theapplication’s configuration files or documentation. (Although AMI sessionparameters are named differently from their non-AMI counterparts, thearguments are the same and the resulting sessions are similar.)TIBCO Hawk Installation and Configuration

104 Chapter 7 Using the Configuration Utility|The default values for an AMI session are RVD, with session parametersspecified as— Service: 7474— Network: ;— Daemon: TCP: 74744. Click OK to close the AMI Session window and add the AMI session to the listof sessions.TIBCO Hawk Installation and Configuration

TIBCO Hawk Display Configuration| 105TIBCO Hawk Display ConfigurationThe Display tab allows you to specify a previously created layout to be loadedautomatically at startup and to specify a variables file.Figure 6 Display ConfigurationDisplayUse the Display option to specify the previously created layout you want loadedautomatically at startup.VariablesUse the Variables option to specify a variables file. The variables file can pass datato define external variables to be used in either host or tool menu commands. Theformat of the file is that used by the standard Java class java.util.Properties.There is one line per variable where each line has the format variablename=value.TIBCO Hawk Installation and Configuration

106 Chapter 7 Using the Configuration Utility|DefaultsThis button clears all fields and returns them to their default values.TIBCO Hawk Installation and Configuration

TIBCO Hawk Agent Configuration| 107TIBCO Hawk Agent ConfigurationThe Agent tab allows you to configure options specific to the TIBCO Hawk agent.Figure 7 Agent Configuration TabIdentificationAgent NameThe agent name appears in the TIBCO Hawk Display. The default name for theTIBCO Hawk agent is the host name of the computer on which it is installed.To use the host name as the agent name, leave the Agent Name field blank. To usea different name, enter a name as desired.Agent names with multiple words separated by dots are not supported.TIBCO Hawk Installation and Configuration

108 Chapter 7 Using the Configuration Utility|Agent DomainAn agent domain must be specified when two computers within the same TIBCOHawk domain have the same name but reside in different network domains. Tospecify an agent domain for a TIBCO Hawk agent, enter the desired domain inthe Agent Domain field, for example, pa.tibco.com.ClusterEnter the container name in which this agent is to appear in the TIBCO HawkDisplay. The default name for the container is the IP subnet address. The clustername must be enclosed within quotes, if the name contains spaces.Configuration ModesUse the options in this panel to set up what mode the agent is to use when itsearches for configuration objects. The default is to use Automatic configuration.Automatic, Manual, and Repository configuration modes are mutually exclusive.When the radio button for one of these modes is selected, the other options aredisabled.The delimiter for path entries is a semicolon ( ; ).If you are using the rulebase map, you usually do not need to list any rulebases inthe rulebase list dialog. Using both a rulebase map and the rulebase list dialogincreases the complexity of managing your monitoring configuration.The rulebase list dialog (which corresponds to the UNIX or file config option-rulebases) is provided to maintain backward compatibility with previousversions of TIBCO Hawk that do not contain the rulebase map feature.Automatic Configuration ModeTo use Automatic configuration, enable the Auto radio button. You can either usethe default auto configuration directory(TIBCO_CONFIG_FOLDER\tibco\cfgmgmt\hawk\autoconfig) or specify anotherdirectory.When Automatic Configuration mode is enabled, all load-by-reference rulebaseloading mechanisms are disabled. Therefore, the Manual Configuration Path,Repository Path, Repository Cache Directory, and the Rulebases button are notenabled. In addition, the RuleBaseInclude feature, rulebase maps, and theRuleBaseEngine:loadRuleBase() microagent method are not used. However,the microagent method RuleBaseEngine:loadRuleBaseFromFile() is allowed.TIBCO Hawk Installation and Configuration

TIBCO Hawk Agent Configuration| 109See the TIBCO Hawk Administrator’s Guide and the TIBCO Hawk Methods Referencefor more on these features and microagent methods. See the TIBCO Hawk ConsoleAPI Reference for information on configuring microagent plug-ins.With automatic configuration, the agent will load the Schedules configuration fileand all rulebase configuration files from the automatic configuration directory atstartup. The only other mechanism by which an agent can load a rulebase afterthis point is through invocation of RuleBaseEngine:loadRuleBaseFromFile()or via SendTo from the Display, using fully qualified filenames.When a rulebase is sent to an agent via SendTo or Apply Changes from theDisplay, the rulebase is stored in the autoconfiguration directory. When a rulebaseis removed from an agent via the Display, the rulebase is also removed from theautoconfiguration directory. Use of the methodsRuleBaseEngine:loadRuleBaseFromFile() andRuleBaseEngine:unloadRuleBase() do not affect the autoconfigurationdirectory.Manual Configuration ModeWhen manual configuration is selected, at startup, the agent searches the ManualConfiguration Path for the Schedule file and the rulebase map file. Afterevaluating the rulebase map, the agent has a list of rulebase names. It searches forthese using the Manual Configuration Path. Note that the loaded startuprulebases may have RuleBaseInclude lists that will trigger further searches ofthe manual configuration path for additional rulebases. Also at startup, the agentsearches the path for any rulebases specified in the Rulebases dialog and loadsthem.See the TIBCO Hawk Administrator’s Guide for more on these features. Note thatmanual configuration mode is also known as Configuration Path mode.Any rulebases loaded by the agent are not written to a local cache. There is nonotion of an autoconfiguration directory. The only rulebases an agent may load atstartup are the ones:• specified by the rulebase map.• listed in the Rulebases dialog.• contained in any RuleBaseIncludes.To set up manual configuration, you specify a configuration path to use, and a listof rulebases, as follows.1. Select the Manual radio button.2. In the Manual Configuration Path field, specify a list of directories to besearched by separating directory entries with semicolons. The defaultdirectory is TIBCO_CONFIG_FOLDER\tibco\cfgmgmt\hawk\config.TIBCO Hawk Installation and Configuration

110 Chapter 7 Using the Configuration Utility|3. Click Rulebases to bring up the Rulebase Configuration dialogFigure 8 Rulebase Configuration Dialog4. Do either of the following until your list is as desired, then click OK:— To add a rulebase to the list, click Add, enter a a rulebase filename, and clickOK.— To remove a rulebase from the list, select it and click Delete.Do not use a file extension when entering rulebase names. The .hrb extensionsare only used for rulebase files. See RuleBaseEngine:loadRuleBase() andRuleBaseEngine:loadRuleBaseFromFile() for more information.Repository Configuration ModeRepository mode is also a type of manual configuration mode and operates in asimilar way to Manual Configuration mode. Instead of a configuration path, youspecify a repository path. The agent communicates with a list of repositories inthis path to obtain all configuration objects (rulebases, schedules, and rulebasemaps). You can also specify a list of rule bases. Repositories are kept on thenetwork and can be accessed by multiple agents. See the TIBCO HawkAdministrator’s Guide for an explanation of repositories.Unlike Manual Configuration Mode, with Repository mode all configurationobjects loaded from the Repository may be cached in a local directory, specified inthe Repository Cache Directory field. This cache is used in the event of arepository failure, and also to minimize network traffic. Agents can determine if aconfiguration object in their cache is identical to the one in the repository and willload it directly from the cache or update it from the Repository as appropriate.TIBCO Hawk Installation and Configuration

TIBCO Hawk Agent Configuration| 111To use repository mode, specify a path for the repository and a repository cache touse in case the repository is off-line, and a list of rulebases, as follows.1. Select the Repository radio button.2. In the Repository Path field, specify the list of repositories to be searched. Thelist should consist of the repository names separated by semicolons (;).3. In the Repository Cache Directory field, specify a repository cache directory.The default is TIBCO_CONFIG_FOLDER\tibco\cfgmgmt\hawk\cache.Step 4 is optional. However, if no rulebase map is supplied by the repository,this step is recommended.4. Click Rulebases to bring up the Rulebase Configuration dialog (Figure 8). Doeither of the following until your list is as desired, then click OK:— To add a rulebase to the list, click Add, enter a a rulebase filename, and clickOK.— To remove a rulebase from the list, select it and click Delete.RepositoryIf a TIBCO Hawk agent is to act as a repository for the TIBCO Hawk system, entera name (with no spaces or periods) for the repository and a path for storage of theconfiguration object files. The default isTIBCO_CONFIG_FOLDER\tibco\cfgmgmt\hawk\Repository.MicroAgent PluginsUse the Plugins Directory option to specify the directory that the TIBCO HawkAgent should search when loading microagent plugins.VariablesUse the Variables option to specify a variables file. The variables file can pass datato define external variables to be passed to rules for use in rulebaseconfigurations.TIBCO Hawk Installation and Configuration

112 Chapter 7 Using the Configuration Utility|Logfile MicroagentScan Rate (secs)The rate at which the log file that is being monitored is scanned for new entries.The default is 10 seconds.Block Size (KB)The size of the block that is read from the log file each time it is scanned. Thedefault is 16 KB.Evaluation Rate (secs)The rate at which all the logfiles being monitored by the agent are evaluated. Thedefault is 300 seconds.HeartbeatThe TIBCO Hawk agent heartbeat interval can be set on each computer where anagent is installed. The default heartbeat interval is 30 seconds. The TIBCO HawkDisplay uses this value to determine when to mark an agent dead.To use the default value of 30 seconds, leave the value in the Interval field set to30. To use a different value, enter a number of seconds, as desired.DefaultsThis button clears all fields and returns them to their default values.TIBCO Hawk Installation and Configuration

TIBCO Hawk Event Service Configuration| 113TIBCO Hawk Event Service ConfigurationThe Event Service tab allows you to configure options specific to the TIBCOHawk Event Service.Figure 9 TIBCO Hawk Event Service DialogAgent Dead HandlingThe Event Service can call a command-line script or executable when theheartbeat of a TIBCO Hawk agent is lost (not received for a specified length oftime). This usually means that the agent process has terminated or that networkcommunication has been interrupted. This facility could be used to send an e-mailor page, or to take some other automated action.Script FileSpecify the name of this script file. By default, this field is blank and no script iscalled when the agent does not respond.TIBCO Hawk Installation and Configuration

114 Chapter 7 Using the Configuration Utility|Two command-line arguments are sent to the script, in this order:1. The name of the agent (by default, identical to the name of the computer onwhich the agent is installed).2. The IP address of the computer on which the agent is installed.Event DataCheck the Enable Event Service Data Files box to enable logging. The TIBCOHawk Event Service writes to rolling data files in the same way that the standardTIBCO Hawk logging system writes to rolling log files (see Logging, page 91).As with TIBCO Hawk log files, you can set the following options:• The directory in which to store data files. The default data file directory isTIBCO_CONFIG_FOLDER\tibco\cfgmgmt\hawk\Data.• The maximum number of data files to keep. The default is five.• The maximum size of a data file. The default maximum is 1024 kilobytes.AMI Rendezvous SessionCheck Enable Dedicated AMI Session if your Event Service process needs to use adedicated Rendezvous session for AMI transport. When the session is enabled,specify the following values. You can leave a parameter field empty (blank) toindicate a null value.• Service number• Network• TCP daemonFor more information on these, see TIBCO Rendezvous Daemon SessionParameters on page 102.Database ConfigurationCheck the Enable Event Persistence box to enable event persistence.When this feature is enabled, fill in the following fields:• User Name: User name to connect to the database.• Password: User password to connect to the database.• Database Type: The database vendor. Select the appropriate vendor from thedropdown menu.TIBCO Hawk Installation and Configuration

TIBCO Hawk Event Service Configuration| 115• Database Connection: URL that identifies the database connection.• JDBC Driver Class Name: Class name for the vendor's JDBC driver. Forexample, com.microsoft.jdbc.sqlserver.SQLServerDriver. You need toadd the vendor’s JDBC drivers to your classpath using the Advanced dialogin the General tab.• TIBCO Hawk Event Service logs alerts generated by Agents in the Hawkdomain. If you want to add any additional alert action property field, clickDefine Column and enter the property name in the Add Alert Propertydialog. The user-defined property field is added as an additional column inthe HawkAlertClearInfo table.Fault ToleranceCheck the Enable Fault Tolerance box to enable fault tolerance on this instance.This instance joins a fault tolerant group namedHawkEventService:hawkdomain, where hawkdomain is the value specified in theGeneral tab.Separate instances of TIBCO Hawk must be running on at least two machines inorder to use fault tolerance. Fault tolerance must be enabled on each instance.WeightAssign the weight of this instance using a positive integer. The member with thehighest weight receives rank 1 (so it outranks all other members). When aninstance fails, the next-highest instance is activated and the member with the nexthighest weight receives rank 2; and so on. When two or more members have thesame weight, Rendezvous fault tolerance software ranks them in a way that isopaque to programs.Enable Dedicated FT SessionCheck the Enable Dedicated FT Session checkbox to specify the dedicatedRendezvous session for fault tolerance.• Service number• Network• TCP daemonWhen specifying a remote daemon, use the fully qualified domain name of thehost. For example, tcp:host1.mycompany.com:7555.If using TIBCO EMS as the primary transport and fault tolerance is enabled but aTIBCO Hawk Installation and Configuration

116 Chapter 7 Using the Configuration Utility|Dedicated FT Session is not specified, a Rendezvous session is created using defaultvalues.If using TIBCO Rendezvous as the primary transport and fault tolerance isenabled but a Dedicated FT Session is not specified, the primary Rendezvoussession is used for fault tolerance.For more information on these, see TIBCO Rendezvous Daemon SessionParameters on page 102.Note the following considerations:• Each TIBCO Hawk Event Service instance in the fault tolerance group must beassigned a weight.• Each weight must be a positive integer, starting with 1.• Each service should have a unique weight.• The weights do not need to be consecutive.If two or more TIBCO Hawk Event Services have the same weight, Rendezvousfault tolerance software assigns a rank to them but does not update the Weightfield in this dialog with the new value.DefaultsThis button clears all fields and returns them to their default values.Logging FileThe event service records the following items:• All alerts raised and cleared by TIBCO Hawk agents across the network, aswell as changes in an agent’s alert level (as would be shown by a color in theTIBCO Hawk Display).• All instances of agent activation and expiration.Some example event.dat log file service entries are shown below.MICROAGENT_REMOVED : AgentID={ host-name=hk-win05.tibco.com,dns=none, host-ip=10.107.196.28, network-ip=WINDOWS },MicroAgentID=COM.TIBCO.hawk.hma.TibRendezvous:2 ## Wed Jul 0212:30:24 PDT 2004 ##RULEBASE_STATE_CHANGED : AgentID={ host-name=PPRASAD-LT, dns=none,host-ip=10.105.160.131, network-ip=10.105.160.131 },rulebase=HawkWindowsEventLog, new-rulebase-state=50 ## Wed Jul 0715:31:34 PDT 2004 ##TIBCO Hawk Installation and Configuration

TIBCO Hawk Event Service Configuration| 117MICROAGENT_ADDED : AgentID={ host-name=hkwin05.tibco.com,dns=none, host-ip=10.107.196.28, network-ip=WINDOWS },MicroAgentID=COM.TIBCO.hawk.hma.TibRendezvous:3 ## Wed Jun 0712:50:27 PDT 2004 ##ALERT_RECEIVED : alert={ agent={ host-name=IMLOAN.TIBCO.COM,dns=none, host-ip=10.107.138.30, network-ip=AS400 }, alert-id=113,rulebase=Stress-Custom-AS400, alert-state=0, alert-text=Returnstring Wed Jul 07 14:31:12 2004 , time-received=Wed Jul 0715:31:43 PDT 2004 } ## Wed Jul 07 15:31:59 PDT 2004 ##MICROAGENT_ADDED : AgentID={ host-name=SMITH-LT, dns=none,host-ip=10.105.152.146, network-ip=10.105.114.0 },MicroAgentID=TomcatMBeanTester:1 ## Wed Jul 07 15:41:15 PDT 2004 ##ALERT_CLEARED : agent={ host-name=hkwin05.tibco.com, dns=none,host-ip=10.107.196.28, network-ip=WINDOWS } alert-id=1050,reason=Valid DataSource is now available:MicroAgentID{name=COM.TIBCO.hawk.hma.Process, displayName=Process,instance=3, isService=false, checksum=3743856314,hostingAgent=Agent{name=hk-win05.tibco.com, dns=none,hawkDomain=mmdomain1, starttime=1085445353093}} ## Mon Jul 1204:10:27 PDT 2004 ##AGENT_EXPIRED : agent={ host-name=SMITH-LT, dns=none,host-ip=10.105.152.146, network-ip=10.105.114.0 } ## Tue Jul 1315:51:37 PDT 2004 ##RULEBASE_REMOVE : AgentID={ host-name=ultrahawk1, dns=none,host-ip=160.101.246.16, network-ip=160.101.246.0 },rulebase=Solaris2x,at Sun Jul 18 11:50:05 EST 2004AGENT_REINITIALIZED : agent={ host-name=lexus, dns=nytek.com,host-ip=160.101.110.169, network-ip=160.101.110.0 },alert-state=50, atMon Jul 19 11:50:36 EST 2004AGENT_ALIVE : agent={ host-name=hk-win05, dns=none,host-ip=10.107.196.28, network-ip=10.107.196.0 }, alert-state=75## Wed Jul 28 08:35:55 PDT 2004 ##RULEBASE_ADDED : AgentID={ host-name=hk-win05, dns=none,host-ip=10.107.196.28, network-ip=10.107.196.0 },rulebase=HawkWindowsEventLog, state=75 ## Wed Jul 28 08:35:55 PDT2004 ##Disabling and Enabling the Event ServiceThe Event Service is not enabled by default. You must manually enable it.Enabling theEvent ServiceTo enable the TIBCO Hawk Event Service,1. Choose Start>Settings>Control Panel, then double-click on the Services icon.TIBCO Hawk Installation and Configuration

118 Chapter 7 Using the Configuration Utility|2. Select TIBHawk Event in the list of services and click Startup.3. In the Service window, click the Automatic radio button, then click OK. Theservice is shown in the list as Automatic.4. Click Start to start the Event Service. The service is shown in the list asStarted.Disabling theEvent ServiceTo disable the TIBCO Hawk Event Service, disable the TIBCO Hawk EventService in the Windows Services control panel as follows:1. Choose Start>Settings>Control Panel, then double-click on the Services icon.2. Select TIBHawk Event in the list of services and click Startup.3. In the Service window, click the Disabled radio button, then click OK. Theservice is shown in the list as disabled.4. If the service is already running, click Stop to stop it. The status in the list isblank, indicating the service is stopped.Be careful not to confuse TIBCO Hawk Event Service data files (Event.dat) withEvent Service log files (Event.log).• Event.dat data files contain the data produced by the Event Service.• Event.log log files record the state of the Event Service itself.The Event.log file is discussed in the TIBCO Hawk Administrator’s Guide.TIBCO Hawk Installation and Configuration

| 119Chapter 8Using the TIBCO Hawk MessagingMicroagentThe Messaging microagent provides methods to send and receive messages usingeither TIBCO Rendezvous or TIBCO EMS. This chapter gives an overview of thismicroagent and describes how to configure and use the microagent.Topics• Overview, page 120• Configuration File Elements and Attributes, page 121• Specifying Field Names in Parameters, page 133TIBCO Hawk Installation and Configuration

120 Chapter 8 Using the TIBCO Hawk Messaging Microagent|OverviewThe Messaging microagent provides methods to send and receive messages usingeither TIBCO Rendezvous or TIBCO EMS. For a detailed description of thesemethods refer TIBCO Hawk Method Reference Guide.Using XML configuration files, you can specify the subject and message structureto be sent or received for each method. If transport parameters are not specified inthe configuration files, the transport specified for TIBCO Hawk Agent will beused. If using RVCM, the transport parameters have to be specified in the methodelement for each method. If using EMS as the default transport, only messagessend or received with JMS topic are supported.A set of sample configuration files are copied to the installation area in thesamples/msghma directory. These files contain sample methods, as well as severaldefault method definitions that are helpful for performing routine tasks. Theconfiguration file, msghma.xml, used by the default Messaging microagent islocated in the TIBCO_CONFIG_FOLDER/tibco/cfgmgmt/hawk/bin directory. Youcan configure additional Messaging microagents by using the TIBCO Hawkplug-in microagent mechanism. To configure additional Messaging microagents:1. Copy the .hma file for the microagent to the plugin directory. The plugindirectory is specified by the -hma_plugin_dir option in the hawkagent.cfgfile. If using the Configuration Utility, the plugin directory is specified by thePlugin field in the Agent tab.2. Make sure the xml file specified in the hma file is present in the expectedlocation.3. Re-start the TIBCO Hawk Agent.Do not edit or delete the msghma.xml file used by the default Messagingmicroagent.Configuration files of the TIBCO Hawk Rendezvous Messaging Adapter can beused as-is. However, any non-applicable attributes will be ignored and if morethan one microagent is defined, only the first microagent configuration will beloaded.TIBCO Hawk Installation and Configuration

Configuration File Elements and Attributes| 121Configuration File Elements and AttributesThe msghma.dtd file defines the grammar for all the constructs used in anmicroagent XML configuration file. With this file included, the XMLconfiguration file can be syntax checked using any validating XML parser.The following tables describe the attributes that can be set in an XMLconfiguration file:• TIBHAWK_AMI Element Attributes• microagent Element Attributes• method Element Attributes• inputParameter Element Attributes• valueChoices Element Attribute• legalValueChoices Element Attribute• constantParameter Element Attributes• outputParameter Element AttributesThe top level element, TIBHAWK_AMI describes transport parameters andtracing attributes that can applied to all microagents. Some of the attributes can beredefined for an individual method in the method element.You can specify different transport parameters for each method as attributes ofthe method element. The attributes of the method element take precedence overthose specified by the microagent or TIBHAWK_AMI elements.Table 19 TIBHAWK_AMI Element AttributesAttribute Type Descriptiondtd_typeenume REQUIRED. (MSGHMA).rationdtd_versionenumerationREQUIRED. (1.0).xml_file_version string IMPLIED. Can be used to identify theversion of this XML file. It must be in theform of .., forexample, 1.1.0.TIBCO Hawk Installation and Configuration

122 Chapter 8 Using the TIBCO Hawk Messaging Microagent|Table 19 TIBHAWK_AMI Element AttributesAttribute Type Descriptionami_rvd_serviceami_rvd_networkami_rvd_daemonstringIMPLIED. These attributes togetherconfigure the TIBCO Rendezvousparameters for creating an TIBCORendezvous transport for thecommunication with the TIBCO Hawkagent.These attributes are maintained forbackward compatibility only and is notused.rvServicervNetworkrvDaemonems_urlems_uidems_pwssl_tracessl_debug_tracessl_vendorssl_trustedssl_expected_hostnamessl_identityssl_identity_encodingssl_passwordssl_verify_hostnamessl_verify_hostssl_cipherstringstringstringIMPLIED. These attributes togetherconfigure the TIBCO Rendezvousparameters for creating a TIBCORendezvous transport.These attributes together configure theTIBCO EMS parameters for creating aTIBCO EMS transport.These attributes are used when using SSLto connect to the EMS server.When specifying values for attributesssl_verify_hostname andssl_verify_host, valid values areenabled and disabled.When specifying values for attributes forssl_trace and ssl_debug_trace, validvalues are true and false.TIBCO Hawk Installation and Configuration

Configuration File Elements and Attributes| 123Table 19 TIBHAWK_AMI Element AttributesAttribute Type DescriptioncmNamecmLedgerNamestringIMPLIED. These attributes together forman RVCM (TIBCO Rendezvous CertifiedMessage) transport. All methods in thismicroagent that use RVCM will use thisRVCM transport.cmName is the RVCM reusable namewhich represents a persistentcorrespondent.If cmLedgerName is specified, it must be avalid file name. The cmLedgerNameattribute is ignored if cmName is notspecified.rvAdvisoryTraceLevelenumerationIMPLIED. One of: ERROR, WARN orINFO. Specifies the lowest level of TIBCORendezvous advisory messages to betracked by the microagent.For example, if WARN is specified, then allWARN or ERROR advisory messages aretracked by this microagent.The default value WARN. If an advisorymessage not tracked by the microagent isreceived, it will be sent to the microagentstandard output if of class WARN orERROR and discarded if of class INFO.rvAdvisoryForward string IMPLIED. Either true or false. Specifieswhether a tracked advisory message willbe sent to the TIBCO HAWK Agent as anunsolicited message.The default is false, which means trackedadvisory messages are logged to theadapter's log file.ftGroupName string IMPLIED. Specifies the name of the TIBCORendezvous fault tolerance group.This attribute is maintained for backwardcompatibility only and is not used.TIBCO Hawk Installation and Configuration

124 Chapter 8 Using the TIBCO Hawk Messaging Microagent|Table 19 TIBHAWK_AMI Element AttributesAttribute Type DescriptionftWeightftActiveGoalftHeartbeatIntervalftPrepIntervalftActiveIntervalstringIMPLIED. These attributes together defineTIBCO Rendezvous fault toleranceparameters. The default values are:• ftWeight 100.• ftActiveGoal 1• ftHeartbeatInterval 30 seconds• ftPrepInterval 60 secondsThese attributes are used only if theftGroupName is specified.These attributes are maintained forbackward compatibility only and are notused.traceFiletraceFileMaxSizetraceFileMaxNumbertraceLevelstringIMPLIED. These attributes togetherspecify the tracing parameters. If notdefined, tracing is sent to stdout.traceFile. Absolute pathname of the tracefile.traceFileMaxSize. Maximum size (in KB)the trace file is allowed to grow.traceFileMaxNumber. Maximum numberof roll over trace files to be maintained.traceLevel. Starting trace level.At least one method must be defined for the microagent. .Table 20 microagent Element AttributesAttribute Type Descriptionname string REQUIRED. Name for the microagent.help string IMPLIED. Help text describing themicroagent. Each help attribute is pairedwith a name attribute. If not defined, thename attribute value is used as the helptext.TIBCO Hawk Installation and Configuration

Configuration File Elements and Attributes| 125Table 20 microagent Element AttributesAttribute Type DescriptiondisplayName string IMPLIED. Name that is displayed in theTIBCO Hawk Display.rvService,rvNetwork, andrvDaemonorems_urlems_uidems_pwssl_tracessl_debug_tracessl_vendorssl_trustedssl_expected_hostnamessl_identityssl_private_keyssl_passwordssl_verify_hostnamessl_verify_hostssl_cipherstringIMPLIED. These attributes togetherconfigure the transport parameters forthe microagent.If any of the attributes are specifieddifferently from those specified for theTIBHAWK_AMI element, a new rvdtransport is created and all the methodsbelong to this microagent will use thenew transport.If the attributes are not specified, thevalues specified for the correspondingattributes associated with theTIBHAWK_AMI element are used.When specifying values for attributesssl_verify_hostname andssl_verify_host, valid values areenabled and disabled.When specifying values for attributes forssl_trace and ssl_debug_trace, validvalues are true and false.TIBCO Hawk Installation and Configuration

126 Chapter 8 Using the TIBCO Hawk Messaging Microagent|Table 20 microagent Element AttributesAttribute Type DescriptioncmNamecmLedgerNamestringIMPLIED. These attributes together forman RVCM (TIBCO Rendezvous CertifiedMessage) transport. All methods in thismicroagent that use RVCM will use thisRVCM transport.cmName is the RVCM reusable namewhich represents a persistentcorrespondent.If cmLedgerName is specified, it must bea valid file name. The cmLedgerNameattribute is ignored if not specified.maxThreads string IMPLIED. Defines the maximumnumber of threads a microagent canhave to perform method invocations inparallel. The default value is 1.This attribute is maintained forbackward compatibility only and is notused.traceFiletraceFileMaxSizetraceFileMaxNumbertraceLevelstringIMPLIED. These attributes togetherspecify the tracing parameters for thismicroagent. If not defined, tracing is sentto stdout. The attributes override thecorresponding attributes associated withthe TIBHAWK_AMI element.• traceFile. Absolute pathname of thetrace file.• traceFileMaxSize. Maximum size (inKB) the trace file is allowed to grow.• traceFileMaxNumber. Maximumnumber of roll over trace files to bemaintained.• traceLevel. Starting trace level.These attributes are maintained forbackward compatibility only and are notused.TIBCO Hawk Installation and Configuration

Configuration File Elements and Attributes| 127If a method has parameters, the method must have at least one input or constantparameter. If a method has a return value, it must have at least one outputparameter.Table 21 method Element AttributesAttribute Type Descriptionname string REQUIRED. The method name.help string IMPLIED. Help text describing the method. Eachhelp attribute is paired with a name attribute. Ifnot defined, the name attribute value is used as thehelp text.index string IMPLIED. If a method returns more than one rowof information, the index attribute must bespecified with the name of the output parameterwhich can uniquely identify each row.If multiple output parameters are required touniquely identify a row (that is, a compositeindex), the index attribute must be specified withparameter names separated by commas.subject string IMPLIED. Specifies the subject to subscribe or topublish. For a subscription subject, the subjectname segments may contain "*", and the lastsegment may be ">".The attribute is required if the first inputparameter is not named Subject or if the methodpublishes RVCM messages.timeout string IMPLIED. The timeout attribute is meaningful(and required) only for RPC methods. If thetimeout interval expires and no reply is received,the first return timeout parameter is set to true.Note that the thread executing the RPC is blockedwhile waiting for the reply. If a microagent expectsmultiple simultaneous RPC calls, the maxThreadsattribute for the microagent must be adjustedhigher accordingly.TIBCO Hawk Installation and Configuration

128 Chapter 8 Using the TIBCO Hawk Messaging Microagent|Table 21 method Element AttributesAttribute Type DescriptionheartbeatIntervalstringIMPLIED The heartbeatInterval attribute (inseconds) is meaningful only for publishermethods. If this heartbeatInterval attributeexists, in additional to the normal behavior, atevery heartbeat interval, a message is published.Note that this kind of method can not haveinputParameters; only constantParameter's can beused.handlerTypeenumerationREQUIRED. One of: P, SU, RPC, DS, T or SSpecifies how a method should be handled:• P. Publishers sending messages.• SU. Subscribers receiving messages.• RPC. RPC client sending messages, thenwaiting for the reply.• DS. Used for the factory provided methodstibrvlisten, tibrvecho anddynamicSubscribe.• T. Used for the factory provided methodtimeoutTest only.• S. Used for factory provided system methods,which include reviewLedger and shutdown.For subscriber and RPC methods (withhandlerType SU and RPC respectively) thespecified fields must have a one to onecorrespondence with the method’s return (output)parameters.For publisher methods (with handlerType P andRPC respectively), the message publish subject andall fields must be specified in the message.useCM string IMPLIED. If set to true, the method is an RVCMpublisher or subscriber. If not specified, RVCM isnot used.TIBCO Hawk Installation and Configuration

Configuration File Elements and Attributes| 129Table 21 method Element AttributesAttribute Type DescriptioncmListenerList string IMPLIED. Only meaningful if the useCM attributeis set to true and the method handlerType valueis P (is a publisher method). The cmListenerListattribute specifies a list of cmName names in theform:, , , ...For methods with handlerType SU, P, or RPC, if the first inputParameter isnamed Subject, it is used as the subject for subscription or publish. (Note: In thiscase, the subject attribute for the method should not be defined.) This allowssubjects to be specified at runtime.For each parameter, you can define either one or more acceptable choices in avalueChoices element, or one or more legal choices in a legalValueChoiceselement. If one of these elements is included in the parameter definition, users canselect method argument values from a dropdown list in TIBCO Hawk Display. Ifneither is included, the corresponding method argument is represented by aneditable field.Table 22 inputParameter Element AttributesAttribute Type Descriptionname string REQUIRED. Name for the input parameter.help string IMPLIED. Help text describing the input parameter.Each help attribute is paired with a name attribute. Ifnot defined, the name attribute value is used as thehelp text.typeenumerationREQUIRED. The supported datatypes are:BOOL, F32, F64, I8, I16, I32, I64, U8, U16, U32,STRING, XMLfieldName string IMPLIED. Must be in the form of F1[.F2[...[.FN]]]where F1 - FN are the message field names in eachnested level.If the fieldName attribute is not specified, it isassumed to be the same as the name attribute.See Specifying Field Names in Parameters, page 133for details.TIBCO Hawk Installation and Configuration

130 Chapter 8 Using the TIBCO Hawk Messaging Microagent|Table 22 inputParameter Element AttributesAttribute Type Descriptionpattern string IMPLIED. Specifies a pattern to convert string data toa desired form. The pattern syntax is based on thejava.text.MessageFormat class specification.For example, a pattern {0, number} KB could be usedto convert a string 123 KB to a number 123 (not astring). If the pattern in the example is {0} KB, a stringof 123 is extracted.Note that only the first argument placeholder (that is,{0..} ) is used to extract the value for the parameterand others are ignored.An input parameter may have an optional element, valueChoices orlegalValueChoices but not both.The valueChoices element defines some acceptable values for aninputParameter element. These values are included in the dropdown list formethod arguments in TIBCO Hawk Display. Users can also type a value not in thelist. This element is optional, and can only be used if the legalValueChoiceselement is not specifiedTable 23 valueChoices Element AttributeAttribute Type Descriptionvalue string IMPLIED. Defines suggested values. The valuesare separated by comma characters. Forexample: 0, 30, 45, 60, 90The legalValueChoices element defines the only possible values that can bespecified in an inputParameter method. This element is optional, and can onlybe used if valueChoices is not specified. Use this element to limit users tospecific values, which are included in the dropdown list for method arguments inTIBCO Hawk Display. Users can only specify values included in the list.Table 24 legalValueChoices Element AttributeAttribute Type Descriptionvalue string IMPLIED. Defines legal values only. The valuesare separated by comma characters. Forexample: 0, 30, 45, 60, 90TIBCO Hawk Installation and Configuration

Configuration File Elements and Attributes| 131Constant parameters are not exposed to the TIBCO Hawk Agent or TIBCO HawkDisplay. Constant parameter values are passed to the msghma method internally.This type of parameters are used when some fixed constant values need to bepassed to msghma methods.Constant parameters are used to fill in constant value fields in the message.Table 25 constantParameter Element AttributesAttribute Type Descriptionname string REQUIRED. Name for the constant parameter.help string IMPLIED. Help text describing the input parameter.Each help attribute is paired with a name attribute. Ifnot defined, the name attribute value is used as thehelp text.typeenumerationREQUIRED. The supported datatypes are:BOOL, F32, F64, I8, I16, I32, I64, U8, U16, U32,STRING, XMLfieldName string IMPLIED. Must be in the form of F1[.F2[...[.FN]]]where F1 - FN are the message field names in eachnested level.If the fieldName attribute is not specified, it isassumed to be the same as the name attribute.See Specifying Field Names in Parameters, page 133for details.For subscriber methods (with method handlerType SU or DS), there are threespecial outputParameter names:• Subscription Subject. Returns the subject used in the subscription. It cancontain wild card characters.• Message Subject. Returns the actual subject used by the publisher to publishthe received message.• Reply Subject. Returns the reply subject of the received message. The replysubject is blank if the sender does not specify a reply subjectTIBCO Hawk Installation and Configuration

132 Chapter 8 Using the TIBCO Hawk Messaging Microagent|For RPC methods (with method handlerType RPC), there is a specialoutputParameter with the name Timeout and type BOOL. It is required and mustbe the first outputParameter. It is used to indicate whether a timeout hasoccurred while waiting for the reply.Table 26 outputParameter Element AttributesAttribute Type Descriptionname string REQUIRED. Name for the output parameter.help string IMPLIED. Help text describing the input parameter.Each help attribute is paired with a name attribute. Ifnot defined, the name attribute value is used as the helptext.typeenumerationREQUIRED. The datatypes follow the TIBCORendezvous 6.x datatypes convention:BOOL, F32, F64, I8, I16, I32, I64, U8, U16, U32, STRINGfieldName string IMPLIED. Must be in the form of F1[.F2[...[.FN]]]where F1 - FN are the message field names in eachnested level.If the fieldName attribute is not specified, it isassumed to be the same as the name attribute.See Specifying Field Names in Parameters, page 133for details.pattern string IMPLIED. Specifies a pattern to convert string data to adesired form. The pattern syntax is based on thejava.text.MessageFormat class specification.For example, a pattern {0, number} KB could be usedto convert a string 123 KB to a number 123 (not astring). If the pattern in the example is {0} KB, a stringof 123 is extracted.Note that only the first argument placeholder (that is,{0..} ) is used to extract the value for the parameterand others are ignored.TIBCO Hawk Installation and Configuration

Specifying Field Names in Parameters| 133Specifying Field Names in ParametersThe fieldName attribute in an inputParameter, outputParameter, orconstantParameter element can specify a single field name, nested fields,repeating fields or arrays.The following example shows how to specify a single field name:A nested field must be in the form of F1[.F2[...[.FN]]] where F1 - FN are themessage field names in each nested level. For example, a message has a fieldNESTED_FIELD, which is another message and that message has a field L2. For aparameter corresponding to the value of the field L3 in NESTED_FIELD.L2, itsfieldName attribute should be:If a field is a repeating field, the instance number (starting from 1) must also bespecified using the notation of {instance number} appended after the field name. Forexample, NESTED_FIELD.L2.L3R{1} means the field L3R belongs to the firstinstance of the repeating field L3R of NESTED_FIELD.L2. In the second example,NESTED_FIELD.L2.L3R{2} means the field L3R belongs to the second instance ofthe repeating field L3R of NESTED_FIELD.L2.TIBCO Hawk Installation and Configuration

134 Chapter 8 Using the TIBCO Hawk Messaging Microagent|If a field is an array, a parameter can be used to represent only one element in anarray. The element index number (starting from 0) must be specified using thenotation of [index number] appended after the field name. For example,NESTED_FIELD.L2.L3A[0] means the first array element in field L3A where L3A isa field of L2 and L2 is field of NESTED_FIELD. In the second example,NESTED_FIELD.L2.L3A[1] means the second array element in field L3A whereL3A is a field of L2 and L2 is field of NESTED_FIELD.Note that the type of "array of TibrvMsg" is not supported and a fieldName suchas F1.F2[2].F3 is not valid. When repeating fields or array fields appear in theinput or constant parameters (for sending), the sequence numbers or the indexnumbers must be in order, that is., no skipping is allowed.TIBCO Hawk Installation and Configuration

| 135Chapter 9Using TIBCO Hawk Across Nets or SubnetsThis chapter explains how to configure TIBCO Hawk monitoring for use acrossnetworks or subnets when using TIBCO Rendezvous as the primary transport. Italso explains how to access TIBCO Hawk monitoring through a dial-upconnection.Topics• Agents and the Network, page 136• Configuring for Network Communication, page 137• Setting up Network Communication on UNIX, page 140• Setting Up Network Communication in Microsoft Windows, page 141• Using the TIBCO Hawk Display over a Dial-up Network Connection, page 144TIBCO Hawk Installation and Configuration

136 Chapter 9 Using TIBCO Hawk Across Nets or Subnets|Agents and the NetworkThe TIBCO Rendezvous messaging software that TIBCO Hawk uses operateswithin either IP Broadcast or IP Multicast protocols. Network traffic for theseprotocols is not generally routed openly between subnets or networks.IP Multicast traffic can be passed through configuration of the network routers,but IP Broadcast must use other means to reach other subnets. TIBCORendezvous software uses a process known as a routing daemon (rvrd) to allowTIBCO Rendezvous messages to transcend multiple networks.If all TIBCO Hawk agents are installed on computers within one subnet, noconfiguration changes are necessary, but if the TIBCO Hawk agents are installedon computers in different subnets or networks, you must change theirconfiguration to allow them to communicate using the routing daemon, rvrd.TIBCO Hawk Installation and Configuration

Configuring for Network Communication| 137Configuring for Network CommunicationFigure 10 shows a sample routing daemon implementation where all TIBCOHawk messages are available throughout the network, and there is only oneTIBCO Hawk domain. Host B acts as the hub. All other rvd processes in eachsubnet will obtain information from the other subnets through rvrd processes onhost A, B or C, as applicable.On these machines, the rvrd process would replace the regular rvd process.However, in addition to its routing functions, the rvrd will support the localapplications just as rvd would.Figure 10 Sample Routing Daemon Configuration for TIBCO Hawk MessagingSubnet 1 Subnet 2 Subnet 3RouterhostChostAhostB(hub)RouterneighborconnectionConfiguring Hawk Rendezvous SubjectsWhen creating Rendezvous routing daemon (rvrd) routes between networks, youmust specify the Rendezvous message subject names that can be passed betweenthe networks. These are configured using the routing daemon's BrowserConfiguration Interface. For details on using the Browser AdministrationInterface and creating Rendezvous routes, see TIBCO Rendezvous Administration.For TIBCO Hawk networks, the routed subjects can be used to control whichagents can be discovered by TIBCO Hawk Console instances located on differentparts of the network.TIBCO Hawk Installation and Configuration

138 Chapter 9 Using TIBCO Hawk Across Nets or Subnets|Full VisibilityThe simplest TIBCO Hawk routing configuration is full visibility of all agentsfrom any TIBCO Hawk Console, anywhere on the network. In this case, thesubject configuration of the Rendezvous routing daemons is identical across allrouting daemons, as shown:Import and Export: "_HAWK.>"If Hawk Event service is used in the fault tolerant mode across networks, thesubject configuration is as follows:Import and Export: "_RVFT.>"Isolated Spokes and DMZ networksIn many large enterprises, application groups may be allowed to discover TIBCOHawk agents on their own networks, but not on networks outside their control.However, a central hub network can be used to view all agents for the purposes ofTIBCO Hawk alert management, centralized rulebase administration, and so on.In this case, the routing daemons running on the spoke networks are configuredto allow traffic in only from the central hub network consoles. This is configuredas shown, with references to Figure 10:On the spoke networks (Hosts A and C):Import: "_HAWK.*.nl.pa.p1.console.>"Export: "_HAWK.*.nl.pa.p1.agent.>"Export: "_HAWK.*.nl.pa.p1.agent4.>"On the central hub network (Host B):Export: "_HAWK.*.nl.pa.p1.console.>"Import: "_HAWK.*.nl.pa.p1.agent.>"Import: "_HAWK.*.nl.pa.p1.agent4.>"If a Hawk Repository is used, add the following to both sides:Import and Export: "_HAWK.*.nl.repository.>"The second subject segment, * , is the Hawk Domain parameter.When used on DMZ networks, this subject configuration will prevent any of the"inside" agents being discovered in the event a Hawk Console is launched fromthe "outside."Monitoring TIBCO Hawk Agents Using TIBCO Rendezvous and TIBCO EMSIn a network where some TIBCO Hawk agents use TIBCO EMS as the primarytransport and some use TIBCO Rendezvous as the primary transport, the EMSserver needs to be set up to allow a TIBCO Hawk monitoring application or aconsole application such as the TIBCO Hawk display to see all the TIBCO HawkTIBCO Hawk Installation and Configuration

Configuring for Network Communication| 139agents. The console application may use TIBCO EMS or TIBCO Rendezvous asthe primary transport. The operations that enable the EMS server for this tohappen are the Import and Export TIBCO Hawk messages. Importing andexporting messages on an EMS server is based on topics and all TIBCO Hawkmessages have a topic. The topics of the TIBCO Hawk messages when TIBCOEMS is used as the transport has same the subject as that of the TIBCO Hawkmessages when TIBCO Rendezvous is used as the transport.There are files that are involved on EMS server for importing and exportingmessages: (assuming using the default filenames)• tibemsd.confThe parameter tibrv_transports has to be enabled to exchange messageswith TIBCO Rendezvous.• transports.confIn this file, specify transport definitions that will be used. For example[RVHAWK]type = tibrvservice =7475network =;daemon =tcp:7475The network, service, daemon parameters used in the transport definitionshould match the TIBCO Rendezvous parameters used by TIBCO Hawkagent.• topics.confThis file contains the import and export definitions. For example,_HAWK.> global,import=RVHAWK,export=RVHAWKFor more information, see TIBCO Enterprise Message Service documentation.Routing TIBCO Hawk Messages with EMS server Across NetworksEMS servers can be configured to route messages between networks where rvrd isnot setup to do so. In order to do this both networks must have an EMS serverrunning. Messages from one network are routed to the other via the EMS serverinstead of the rvrd.For more information, see TIBCO Enterprise Message Service User’s Guide.To route TIBCO Hawk messages, each EMS server needs to be setup for importingand exporting TIBCO Hawk topics. For more information, see Monitoring TIBCOHawk Agents Using TIBCO Rendezvous and TIBCO EMS on page 138.TIBCO Hawk Installation and Configuration

140 Chapter 9 Using TIBCO Hawk Across Nets or Subnets|Setting up Network Communication on UNIXWhen starting the rvrd process, use the -store argument, which isspecific to TIBCO Rendezvous, to store the parameters that configure rvrd. rvrdreads this file when the process starts, and writes this file each time you changethe configuration using the browser administration interface. For details on usingthe Browser Administration Interface, see TIBCO Rendezvous Administration.A TIBCO Rendezvous license file is required to use TIBCO Hawk with rvrd.Routing Daemon Configuration for UNIXWhen any Rendezvous application starts, the libraries will cause a Rendezvousdaemon (rvd) process to start if one is not already running. Once the rvd processis running, a Rendezvous routing daemon (rvrd) process cannot be started withthe same transport parameters. This can cause coordination issues in starting thervrd prior to any applications, and becomes a problem if the rvrd dies duringrun time and an rvd is restarted in its place.You can avoid these problems by creating a simple wrapper script to always startthe rvrd process in lieu of an rvd process. When the Rendezvous libraries searchthe PATH for an executable named rvd, they will find the rvrd wrapper scriptinstead of the rvd process itself. This will always ensure that the rvrd process isstarted or restarted properly.To set up the script:1. Move or rename the rvd binary from the rv_install_dir/bin directory.2. Create a shell script named rvd that starts the rvrd process with the desiredcommand line arguments.3. Place the rvd script in the rv_install_dir/bin directory of each machine wherean rvrd process is required to run.For details on the routing daemon command line parameters, see TIBCORendezvous Administration.TIBCO Hawk Installation and Configuration

Setting Up Network Communication in Microsoft Windows| 141Setting Up Network Communication in Microsoft WindowsIt is recommended that you make the TIBCO Hawk services dependent on theEMS server service when it is installed on the same machine. To make the TIBCOHawk services depend on the EMS server service, follow steps outlined inMaking TIBCO Hawk Services Depend on the Routing Daemon MicrosoftWindows Service, page 142, adding the EMS server service name in step 7.Installing a Routing Daemon as a Microsoft Windows ServiceBecause TIBCO Hawk processes are installed as Microsoft Windows services, youmust install the TIBCO Rendezvous routing daemon as a Microsoft Windowsservice and configure the TIBCO Hawk services to depend on it. If this is notdone, the TIBCO Hawk services may start first, causing an rvd to launch andpreventing the rvrd from running.For TIBCO Hawk to use rvrd, the daemon parameter specified in the-rvd_session option should match the port that rvrd is listening to.For example, if the arguments for rvrd include -listen 7555 then specify thervd_session for TIBCO Hawk as-rvd_session tcp:7555, where and are your service and network parameters.To configure the appropriate command line parameters for the rvrd process andinstall it as a Microsoft Windows service, use the TIBCO Rendezvous ServicesConfiguration Program, rv_install_dir\bin\rvntscfg.exe. For further details onthis program and routing daemon command line parameters, see TIBCORendezvous Administration.Starting the Routing Daemon Service Automatically in Microsoft WindowsOnce you have configured the rvrd process as a Microsoft Windows service, set itup to start automatically when the operating system starts, as shown in thefollowing steps:1. Choose Start > Settings > Control Panel > Services.2. Select the service in the list of services.3. Click Startup.4. Click the Automatic radio button.5. Click OK.TIBCO Hawk Installation and Configuration

142 Chapter 9 Using TIBCO Hawk Across Nets or Subnets|Making TIBCO Hawk Services Depend on the Routing Daemon MicrosoftWindows ServiceOnce the rvrd service has been installed, add a DependOnService parameter inthe service registry to each of the installed TIBCO Hawk services (TIBHawkAgent,TIBHawkHMA, and TIBHawkEvent), as shown in the following steps.1. Log on with administrative privileges.2. Run the Microsoft Windows registry editor, regedt32, as follows:a. Select Start > Run.b. In the Run dialog that appears, enter regedt32 in the Open drop-downlist box and click OK.3. In the registry editor, navigate through the hierarchy to the TIBCO Hawkservice.The following figure shows the service:HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\TIBHawkAgent4. Right click and choose New>Multi-String Value.TIBCO Hawk Installation and Configuration

Setting Up Network Communication in Microsoft Windows| 1435. Rename this value to DependOnService.6. Double-click this new value to bring up its Multi-String Editor dialog box.7. Add the name of the service to the Value data edit box.8. Click OK.9. Exit regedt32.10. Reboot your system.TIBCO Hawk Installation and Configuration

144 Chapter 9 Using TIBCO Hawk Across Nets or Subnets|Using the TIBCO Hawk Display over a Dial-up Network ConnectionThe TIBCO Hawk system supports remote monitoring. If you are using a machinethat has dial-in access to your network, you can monitor your network remotely.Standard connection techniques such as PPP and a simple configuration changeare all that are required. The dial-in computer must have an IP address on thenetwork, and should only run the TIBCO Hawk Display, and no other TIBCOHawk services (such as HMA, agent, or event service).The remote host must already be running a correctly configured TIBCORendezvous daemon. You cannot spawn a remote daemon. The easiest way toachieve a dial-up connection is to choose a machine that already has a properlyconfigured TIBCO Hawk agent or TIBCO Hawk Display running.This procedure can also be used for remote networks without an rvrd.Establishing a Dial-up Connection in UNIXTo establish a dial-up connection using UNIX, supply the command-line option-rvd_session to the startdisplay script:startdisplay -rvd_session tcp::For example:startdisplay -rvd_session 7474 123.123.123tcp:office_computer:7474orstartdisplay -rvd_session 7474 123.123.123 tcp:123.123.123.12:7474When the dial-up connection is established, restart the TIBCO Hawk Display.Establishing a Dial-up Connection in WindowsBy setting the TIBCO Hawk daemon parameter to point to a TIBCO Rendezvousdaemon on your network, you effectively make your TIBCO Hawk Displayappear to be located on that system.1. From the offsite system, enter the Windows TIBCO Hawk Configurationprogram.2. Enter the remote computer’s name as part of the Daemon parameter, asfollows:tcp::TIBCO Hawk Installation and Configuration

Using the TIBCO Hawk Display over a Dial-up Network Connection| 145where is any computer on the internal network which aTIBCO Rendezvous daemon process is running. For example:tcp:office_computer:7474ortcp:123.123.123.12:74743. When the dial-up connection is established, restart the TIBCO Hawk Display.TIBCO Hawk Installation and Configuration

146 Chapter 9 Using TIBCO Hawk Across Nets or Subnets|TIBCO Hawk Installation and Configuration

| 147Chapter 10TIBCO Hawk Sample Rulebases andApplicationsIf, on UNIX, the TIBCO Hawk software is installed in any location other than thedefault path of /usr/tibco/hawk, you must update all rules using thelogfile:onNewLine data source in the sample rulebases. For example,HawkAgent-Unix (in the directory $HAWK_INSTALLATION/samples) must beupdated to reflect the correct path to $HAWK_ROOT/log.Topics• Using the Sample TIBCO Hawk Rulebases, page 148• Using the TIBCO Hawk Sample Applications, page 149• The Sample AMI API Applications, page 151TIBCO Hawk Installation and Configuration

148 Chapter 10 TIBCO Hawk Sample Rulebases and Applications|Using the Sample TIBCO Hawk RulebasesThe TIBCO Hawk sample rulebases are installed in the directory$HAWK_INSTALLATION/samples/rulebases. To use any of these rulebases, followthe instructions below:1. In the TIBCO Hawk Display, right-click on the desired agent and select GetConfiguration>Rulebases from the menu.The Rulebase List for Agent dialog displays.2. Choose File>Load From File.The Open dialog displays.3. Navigate to the desired rulebase file and click Open.— If a rulebase with this name is not already loaded, it is added to theRulebase List.— If a rulebase with this name is loaded on the agent, a dialog displays youroptions. Click OK to overwrite the existing rulebase, or Cancel to leave thedialog.4. To save changes to memory, click Apply Changes to Agent.If you are using Automatic Configuration mode, the loaded rulebase is copied toyour auto-configuration directory and will be loaded at startup.NoDataSource errors can result if any rules in the rulebase use data sources thatare unavailable on the agent where the rulebase is loaded. You cannot edit thoserules.On UNIX, if the TIBCO Hawk software is not installed in the default location(/usr/tibco/hawk), you must update all rules using the logfile:onNewLinedata source in the sample rulebases. For example, HawkAgent-Unix (in thedirectory $HAWK_INSTALLATION/samples) must be updated to reflect the correctpath to $HAWK_ROOT/log.TIBCO Hawk Installation and Configuration

Using the TIBCO Hawk Sample Applications| 149Using the TIBCO Hawk Sample ApplicationsThe TIBCO Hawk software distribution includes source code for sampleapplications that demonstrate the use of the TIBCO Hawk ApplicationManagement Interface (AMI). AMI is used to instrument applications so thatTIBCO Hawk agents can directly monitor them. AMI is a specification of TIBCORendezvous messages that define the interactions that take place between aTIBCO Hawk agent and an AMI application. Please refer to the TIBCO HawkProgrammer's Guide for a complete description of AMI.Using AMI Protocol Versus the AMI APIsThere are two ways to write an AMI application. You can use the TIBCORendezvous APIs to directly implement the AMI protocol or you can use theTIBCO Hawk AMI APIs which implement the AMI protocol for you.Use of the TIBCO Hawk AMI APIs is recommended because they handle all theTIBCO Rendezvous and AMI details for you, making programming AMI simplerand more foolproof. Use of the APIs also ensures that your applications will becompatible with future releases of TIBCO Hawk and AMI.Configuring TIBCO Rendezvous Session ParametersAll the sample applications require TIBCO Rendezvous session parameters inorder for those applications to establish a TIBCO Rendezvous session with thelocal TIBCO Hawk agent. These session parameters must match the primarysession parameters configured for the TIBCO Hawk agent or one of the AMIsessions configured for the TIBCO Hawk agent.The TIBCO Rendezvous session parameters are hard-wired into the code of thesesample applications. To change the session parameters you must edit the files andchange the values of the TIBCO Rendezvous session constant.For information on configuring primary and AMI session parameters for a TIBCOHawk agent on the Windows platform, refer to Using TIBCO Hawk Across Netsor Subnets, page 135. For UNIX, refer to Chapter 6, Configuring TIBCO HawkSoftware.Sample AMI Application NamesThese samples, like all AMI applications, have both a display name and aninternal name. The internal name is the name by which the TIBCO Hawk systemuniquely identifies this AMI application and distinguishes it from other AMIapplications. The display name is a user-friendly name that is used in the TIBCOHawk Display.TIBCO Hawk Installation and Configuration

150 Chapter 10 TIBCO Hawk Sample Rulebases and Applications|• To see the list of AMI application internal names for a particular TIBCO Hawkagent, invoke its Self:getMicroAgentInfo method.• To view the display name, right-click on the desired agent in TIBCO HawkDisplay, and select GetMicroAgents from the menu. The MicroAgents,Methods, and Arguments dialog appears. When the sample applications aresuccessfully executed you should see their names appear on the associatedTIBCO Hawk agent.TIBCO Rendezvous License Tickets and AMITIBCO Rendezvous software is licensed using license tickets, which are characterstrings that encode licensing information. License tickets are stored in files such astibrv.tkt (for the TIBCO Rendezvous daemon and routing daemon). TIBCO Hawkemploys an embedded TIBCO Rendezvous license that allows the TIBCO Hawksoftware to use the TIBCO Rendezvous solely in support of the TIBCO Hawkproduct. A TIBCO Rendezvous license ticket is not required to run the TIBCOHawk product with the TIBCO Rendezvous daemon (rvd). The use of TIBCOHawk with the TIBCO Rendezvous routing daemon (rvrd), however, still requiresa valid TIBCO Rendezvous license ticket.The AMI APIs allow applications to be AMI instrumented so that they use thesame embedded TIBCO Rendezvous license as the TIBCO Hawk product. Thislicense only allows the AMI instrumented application to use TIBCO Rendezvousin support of the AMI communication with the TIBCO Hawk agent. Any otheruse of TIBCO Rendezvous by the AMI application would require a valid TIBCORendezvous license ticket.TIBCO Hawk Installation and Configuration

The Sample AMI API Applications| 151The Sample AMI API ApplicationsThe TIBCO Hawk AMI API sample applications can be found in the directory:$HAWK_INSTALLATION/samples/ami_api directoryThis directory contains three sub-directories c, cpp, and java that contain sampleapplications for the C, C++, and Java TIBCO Hawk AMI APIs, respectively. Theseapplications are discussed in the following sections.TIBCO Hawk AMI C API Sample ApplicationsThe TIBCO Hawk AMI C API sample directory contains four sample applications.They have the following filenames and AMI application names, with the numbers1-4 substituted for the x:TIBCO Hawk AMI C API sample x:— Filename: ami_samplex.c— Display name: ami_samplex— Internal name: COM.TIBCO.hawk.ami_api.c.ami_samplexThe four sample applications can be built by following the instructions in theMakefile.sample file, which is also located in the sample directory.• ami_sample1.cThis sample shows how to AMI instrument a non-Rendezvous application.The AMI API does all the Rendezvous work under the covers.This method limits the number of dispatching threads to one thread. This isthe only thread which will call the user applications AMI API callbackfunctions. As a result, the users application can be single threaded. If the usersapplication is to be multi-threaded then the code in this sample would run ona dedicated thread. The users application would be responsible for threadsafety regarding any of its own data structures.• ami_sample2.cThis sample shows how to AMI instrument a Rendezvous application. Theusers application creates a Rendezvous transport and queue and isresponsible for dispatching that queue.The users application is free to be single or multiple threaded. The usersapplication is responsible for synchronizing access to user application data inthe multi-threaded case.• ami_sample3.cTIBCO Hawk Installation and Configuration

152 Chapter 10 TIBCO Hawk Sample Rulebases and Applications|This sample is identical to ami_sample1.c except that it demonstrates how tocreate methods that return tabular data.• ami_sample4.cThis sample shows how to create an asynchronous AMI method for asynchronous data source. This technique is used when synchronous dataneeds to be polled at a certain rate, possibly calculations performed on thedata across samples, and the results returned at that rate or another rate. Thistechnique makes use of the auto-invoke feature of the AMI C API.Executing Sample Programs• To execute, for example, ami_samplex program, use the following commandline:ami_samplexUsing Sample Applications on IBM i5/OSThe names of the TIBCO Hawk AMI C API sample programs have been truncatedto fit the IBM i5/OS name limit. On IBM i5/OS, the sample programs have thefollowing names, with the numbers 1-4 substituted for the x:ami_samplx.cA sample CL program is provided to compile the sample programs. This sampleCL program is included with the HAWKAMI library in QCSRC. The sample CLprogram assumes the source for the sample programs is present inTIBHAWK/QCSRC.To compile the sample programs, execute the following command:CALL TIBHAWK/AMICMP AMI_SAMPL1You can execute the TIBCO HAWK AMI C sample programs as a job or from qsh.To submit a job, execute the following command:SBMJOB CMD(CALL PGM(TIBHAWK/AMI_SAMPL1)) JOBQ(QUSRNOMAX)MSGQ(*USRPRF) ALWMLTTHD(*YES)TIBCO Hawk AMI C++ API Sample ApplicationThe TIBCO Hawk AMI C++ API sample directory contains one sampleapplication, which has the following filename and AMI application names:• AmiSample1.cppFilename: AmiSample1.cppTIBCO Hawk Installation and Configuration

The Sample AMI API Applications| 153Display name: AmiSample1Internal name: COM.TIBCO.hawk.ami_api.cpp.AmiSample1This sample creates an AMI session to support methods that demonstrate howto:— pass data to an instrumented application,— receive data from an instrumented application,— return tabular data,— return data asynchronously, and— shutdown an application.The sample application can be built by following the instructions in theMakefile.sample file, also located in the sample directory.Executing the Sample Program• To execute AmiSample1 program, use the following command line:AmiSample1TIBCO Hawk AMI Java API Sample ApplicationThe TIBCO Hawk AMI Java API sample directory contains the following files:• AmiSample.Java:a sample application designed to illustrate how toinstrument a Java application using the TIBCO Hawk AMI API for Java.• Spot.java: a simple GUI application using TIBCO Hawk AMI API for Java.• SpotAmi.java: AMI Java API instrumentation for the Spot application.This sample demonstrates how an existing application, Spot.java, can beinstrumented with the AMI Java API.The AMI sample spot.java has the following AMI application names:• Display name: Spot• Internal name: COM.TIBCO.hawk.ami_api.java.SpotExecuting the Sample ProgramIn order to compile and execute this sample, the following must be in your JavaCLASSPATH:• ami.jar and util.jar from the TIBCO Hawk java directoryTIBCO Hawk Installation and Configuration

154 Chapter 10 TIBCO Hawk Sample Rulebases and Applications|• tibrvj.jar from the TIBCO Rendezvous java directoryIt is recommended that you use Java 1.6 or higher.The Spot application is executed with the following command:java Spot -rvd_session Using the Sample ProgramsEach sample program represents a separate application. Compile and link themusing your C/C++ development environment.Do not use any class libraries (such as MFC) in your build; make the application aconsole application only.To Compile the Program SamplesSee the TIBCO Hawk AMI C Reference and TIBCO Hawk AMI C++ Reference booksfor information about compiling the program samples.TIBCO Hawk Installation and Configuration

| 155Chapter 11SecurityThis chapter discusses the two security models supplied with the TIBCO Hawksystem. For details on creating a custom security model, refer to the TIBCO HawkProgrammer’s Guide.Topics• Overview, page 156• Trusted Model, page 157• To Use the Trusted Model, page 159TIBCO Hawk Installation and Configuration

156 Chapter 11 Security|OverviewThe TIBCO Hawk product supports a security mechanism which enables allmethod invocation requests made of a TIBCO Hawk agent to be verified forauthenticity and integrity and then authorized (or not) based on the identity ofthe user making the request.The security implementation you choose will depend on your securityrequirements for authorization, authentication, integrity and privacy. You can useone of the security models provided with the TIBCO Hawk product (Trusted orCertified), or develop a custom security model (as explained in the TIBCO HawkProgrammer's Guide).The definitions of security terms used in this manual are as follows:AuthenticationAuthentication is the practice of determining that an entity (e.g. person, process,etc.) is who they say they are.IntegrityData integrity is the ability to guarantee that the content of a message that is sentfrom one party to another is received just as it was sent.AuthorizationAuthorization is the practice of granting and denying privileges to users of aservice or resource. The ability to authorize a request requires two pieces ofinformation: the identity of the user and the nature of the request. The system canthen determine if the user has sufficient privileges for the request.PrivacyPrivacy is the ability to guarantee that the content of a message that is sent fromone party to another is hidden from other parties.TIBCO Hawk Installation and Configuration

Trusted Model| 157Trusted ModelThe Trusted model provides a simple yet effective mechanism for addressingauthorization concerns. It addresses security issues as follows:• Authentication: the Trusted security model does not guarantee theauthenticity of the request.• Integrity: the Trusted security model does not guarantee the integrity of therequest.• Authorization: the Trusted security model guarantees that only authorizedusers can perform restricted actions. See below.• Privacy: the Trusted security model does not address the privacy of therequest. All requests are sent using plain text.AuthorizationThe Trusted model uses an ASCII file as a simple yet effective entitlement server.This has the benefit of being easily distributed to all nodes, making it a veryscalable mechanism. A scan of the ASCII file for information about the userdetermines if the request will be granted.Users are explicitly granted or denied access through the access control file. Auser who is not in this file is not allowed to perform any operations on the TIBCOHawk system. Access control information is in a plain ASCII file located in theTIBCO_HOME\hawk\\samples\security folder.Copy this file to TIBCO_CONFIG_FOLDER/tibco/cfgmgmt/hawk/securitymanually. See Access Control File, page 160, for more details.LoggingAll trusted requests (both Trusted and TrustedWithDomain) can be logged torolling log files in a directory of your choice.The current log file is named Trusted.log. When it reaches the maximum size(size), it is closed and renamed Trusted1.log, and a new Trusted.log isstarted. When the number of logs exceeds the maximum (n), log entries roll overto reuse the oldest log file.To activate logging, add the following line to the access control file: -log_dir -log_max_size -log_max_num TIBCO Hawk Installation and Configuration

158| Chapter 11 Security where:OptionlogDirsizenDescriptionThe directory where the log file is saved.Make sure this directory exists before you activate logging.The maximum size of the rolling log file in KB. The suffix m or M canbe used for indicating MB.The maximum number of rolling log files.Example Log File EntriesThis is an example log entry for an authorized request:Tue Dec 31 11:14:13 EST 2002: Trusted operation:userID=HAWK-TRUSTDMN\hawkuser, node=hawkuser-DT:none:default,microagent=COM.TIBCO.hawk.microagent.SysInfo, method=getOperatingSystem.This is an example of an entry for an unauthorized request:Tue Dec 31 11:19:54 EST 2002: Trusted operation: userID=HAWK-TRUSTDMN\hawkuser, node=hawkuser-DT:none:default, microagent=COM.TIBCO.hawk.microagent.Repository, method= getRBMap -permission denied.Using both Trusted and TrustedWithDomainAn agent using the Trusted or TrustedWithDomain security model allows userswith either Trusted or TrustedWithDomain to access the agent.• To allow access to a user who starts Hawk Display (or the Console APIapplication) in Trusted security mode, the entry for specified in theagent’s Trusted.txt or TrustedWithDomain.txt should not include thedomain of the user who actually starts Hawk Display (or the Console APIapplication).• To allow access to a user who starts Hawk Display in TrustedWithDomainsecurity mode, the entry for specified in the agent’s Trusted.txt orTrustedWithDomain.txt should include the domain of the user who actuallystarts Hawk Display.TIBCO Hawk Installation and Configuration

To Use the Trusted Model| 159To Use the Trusted ModelTwo sample access control files are included with TIBCO Hawk.• Trusted.txt can be used on UNIX or Microsoft Windows. It is used when thecommand line specifies Trusted.• TrustedWithDomain.txt is for use on Microsoft Windows only, and is usedwhen the command line specifies TrustedWithDomain.The access control files, Trusted.txt and TrustedWithDomain.txt, aredescribed in the next section.To use the Trusted model:If you have multiple Hawk agents running on a machine and these Hawkagents, in turn, belong to different Hawk domains, you can specify separateaccess control files for each domain.1. For each Hawk domain create a directory:TIBCO_CONFIG_FOLDER/tibco/cfgmgmt/hawk/domain//security where is the name of the Hawk domain.2. Modify the appropriate sample access control file, Trusted.txt orTrustedWithDomain.txt, according to the requirements of your system.3. Save the modified file in the directory you created, without changing thefilename. The program automatically searches for the access control file in thisdirectory.4. Start the TIBCO Hawk agent and Display as follows:— On UNIX, specify the following in the agent configuration file:COM.TIBCO.hawk.security.trusted.Trusted— On Microsoft Windows, enter one of the following in the Security PolicyClass dialog of the Microsoft Windows Configuration Utility:orCOM.TIBCO.hawk.security.trusted.TrustedCOM.TIBCO.hawk.security.trusted.TrustedWithDomainThe Trusted model is now in effect. The security policy will stay in force as long asthe process is running.TIBCO Hawk Installation and Configuration

160 Chapter 11 Security|Access Control FileTo store access control information, the Trusted model uses an ASCII file. Twosample access control files are included with TIBCO Hawk: Trusted.txt andTrustedWithDomain.txt.Sample access control files are shipped with the TIBCO Hawk software, in thedirectory /samples/security/.Trusted.txtThis access control file can be used with UNIX or with Microsoft Windows XP.The user for authorization is the login ID of the TIBCO Hawk Display owner.TrustedWithDomain.txtThis file can only be used with Microsoft Windows XP, and only when specified inthe command used to start TIBCO Hawk agent and Display, as in-security_policy COM.TIBCO.hawk.security.trusted.TrustedWithDomain.The user is the login ID and the domain where the user is logged on. For example,for user1 in domainX, the user is \user1.Group OperationsA group operation effectively performs a method invocation simultaneously onall of the specified target microagents. It is useful for affecting a group ofmicroagents in a single operation. There are two kinds of group operation:network query and network action. See the TIBCO Hawk Administrator’s Guide formore details.Wildcard characters + and * affect permissions on group operations andpoint-to-point invocations as shown in Access Control File Settings, page 161.• Use + in node access to allow access to group operations.• Use * in node access to allow access to point-to-point invocations.• Use + in method access to allow access to all INFO and ACTION methods.• Use * in method access to allow access.Access Control File ConventionsThe access control file uses the following conventions to grant or deny access.• Explicit access for a particular resource implicitly denies access to all otherresources in the same class. The defined classes are nodes, microagents, andmethods.TIBCO Hawk Installation and Configuration

To Use the Trusted Model| 161• Explicit restriction for a particular resource implicitly allows access to all otherresources in the same class, provided they have been explicitly granted. Thedefined classes are nodes, microagent, and methods.• Permissions always default to the most restrictive case.Table 27 Access Control File SettingsFile Settings for the Trusted ModelThis table presents how individual restrictions and permissions are defined fornodes, microagents, and methods. Individual node, microagent, and methodnames can be specified. In addition, wildcard characters can be used as shown inthe table.Each individual setting is represented by one line in the access control file.Complex permissions and restrictions can be defined using sets of related lines.For example, you can give a user access to all methods on a node in one line, thenin the following line, restrict that user’s access to one of those methods. SeeDisable Custom Microagent, page 164, for further details.Permissions are granted to a user using the user name. Restrictions are defined byprefixing a bang (!) character to the user name, as shown in the table.Effect User Node Microagent MethodFull AccessGrants full access to all methods on all microagentson all nodes, including group operations.Full RestrictionDenies access to all methods on all microagents onall nodes, including group operationsNode Access: All NodesGrants point-to-point and group operationinvocation access to all methods on all microagents.Node Access: All NodesGrants point-to-point invocation access to allmethods on all microagents.Does not grant group operation invocation access.! + *TIBCO Hawk Installation and Configuration

162 Chapter 11 Security|Table 27 Access Control File Settings (Cont’d)Effect (Cont’d) User Node Microagent MethodNode Access: Named nodeGrants invocation access to all methods on allmicroagents on the named node.You can add several lines for one user to provideaccess to a set of nodes.Node Restriction: All NodesDenies point-to-point and group operationinvocation access to all methods on all microagents.Node Restriction: All NodesDenies group operation invocation access to allmethods on all microagents. (Does not denypoint-to-point operation invocations.)! *! +Node Restriction: Named nodeDenies invocation access to all methods on allmicroagents on the named node. You can addseveral lines for one user to provide access to a setof nodes.!Microagent AccessGrants access to all methods on the specifiedmicroagent.Wildcard characters can be used in place of aspecific node name. See Node Access above.Microagent RestrictionDenies access to all methods on the specifiedmicroagent.Wildcard characters can be used in the Nodecolumns. See Node Restriction above. ! TIBCO Hawk Installation and Configuration

To Use the Trusted Model| 163Table 27 Access Control File Settings (Cont’d)Effect (Cont’d) User Node Microagent MethodMethod AccessGrants access to all ACTION and INFO methods onthe specified microagent (but not ACTIONINFOmethods).Wildcard characters can be used in the Node andMicroagent columns. +Method AccessGrants access to all INFO methods on the specifiedmicroagent (but not ACTION or ACTIONINFOmethods).Wildcard characters can be used in the Node andMicroagent columns.Method AccessGrants access to the specified method on thespecified microagent.Wildcard characters can be used in the Node andMicroagent columns.Method RestrictionDenies access to all methods on the specifiedmicroagent.Wildcard characters can be used in the Node andMicroagent columns.Method Restriction * ! *! +Denies access to all ACTION and ACTION_INFOmethods on the specified microagent.Wildcard characters can be used in the Node andMicroagent columns.TIBCO Hawk Installation and Configuration

164 Chapter 11 Security|Table 27 Access Control File Settings (Cont’d)Effect (Cont’d) User Node Microagent MethodMethod Restriction! Denies access to the specified method on thespecified microagent.Wildcard characters can be used in the Node andMicroagent columns.Disable Custom MicroagentThe Custom microagent can be disabled by leveraging the Security TrustModelsupported by TIBCO Hawk. Users are explicitly granted or denied access throughthe access control file.The following steps describe how to disable Custom microagent execution.1. If multiple Hawk agents are running on a machine and these Hawk agents inturn belong to different Hawk domains, specify separate access control filesfor each domain.For each Hawk domain create a directoryHAWK_HOME/domain//security where isthe name of the Hawk domain.2. According to the requirements of your system copy theHAWK_HOME/samples/secuirty/Trusted.txt orHAWK_HOME/samples/secuirty/TrustedWithDomain.txt toTIBCO_CONFIG_FOLDER/tibco/cfgmgmt/hawk/security/.3. Modify the file to add the following lines:* * **none * COM.TIBCO.hawk.microagent.Custom +The first line grants access to all users, on all nodes, and for all microagentmethods.The second line grants access only to the user none, on all nodes for theCustom microagent, where none is a non-existant user. This effectivelyprevents anyone from executing the Custom microagent.4. Start the TIBCO Hawk agent and display as follows:On UNIX, specify the following in the agent configuration file:COM.TIBCO.hawk.security.trusted.TrustedTIBCO Hawk Installation and Configuration

To Use the Trusted Model| 165On Microsoft Windows, enter one of the following in the Security Policy Classdialog of the Microsoft Windows Configuration Utility:COM.TIBCO.hawk.security.trusted.Trusted orCOM.TIBCO.hawk.security.trusted.TrustedWithDomainTrusted.txt and TrustedWithDomain File ExamplesThe following example files demonstrates how a Trusted.txt andTrustedWithDomain.txt access control file might be constructed. Thepermissions and restrictions defined in this file are explained in the previoussection.Explanation of SettingsThe settings in the example files below provide access to the following users asshown here:• Grant user1 point-to-point access to all methods on all microagents, except:— All ACTION methods on the Custom microagent on all nodes.— The specified methods on the Repository microagent on all nodes.— The specified methods on the RuleBaseEngine microagent on nodeA.• Grant user2 point-to-point and group operation invocation access to allmethods on all microagents, except:— All ACTION methods on the Custom microagent on all nodes.— All ACTION methods on the Repository microagent on all nodes.— All ACTION methods on the RuleBase microagent on all nodes.• Grant user3 point-to-point and group operation invocation access to allmethods on all microagents on all nodes, except:— group operation invocation access to all ACTION methods on the RuleBasemicroagent.• Grant user4 full access to all methods on all microagents on nodeB.• Grant user5 point-to-point access to all INFO methods on all microagents onall nodes.Trusted.txt Example File## This file is used by agent running with COM.TIBCO.hawk.security.trusted.TrustedTIBCO Hawk Installation and Configuration

166 Chapter 11 Security|# security model.### Explanation of Settings:## Grant "user1" point-to-point access to all methods on all Microagents, EXCEPT# - all ACTION methods on the Custom microagent on all nodes.# - the specified methods on the Repository microagent on all nodes.# - the specified methods on the RuleBaseEngine microagent on "nodeA".## Grant "user2" point-to-point and network access to all methods on all# Microagents, EXCEPT# - all ACTION methods on the Custom microagent on all nodes.# - all ACTION methods on the Repository microagent on all nodes.# - all ACTION methods on the RuleBase microagent on all nodes.## Grant "user3" point-to-point and network access to all methods on all# Microagents on all nodes, EXCEPT# - network access to all ACTION methods on the RuleBase microagent.## Grant "user4" full access to all methods on all microagents on nodeB.## Grant "user5" point-to-point access to all INFO methods on all microagents# on all nodes.### Wildcard characters + and * usage:## - Use + in node access for allowing access to group operations.# - Use * in node access for allowing access to point-to-point invocations.# - Use + in method access for allowing access to all INFO and ACTION methods.# - Use * in method access for allowing access to all INFO methods only.### File format:## user node microagent method# access access access# & & &# restrictions restrictions restrictions#user1 *!user1 * COM.TIBCO.hawk.microagent.Custom +!user1 * COM.TIBCO.hawk.microagent.Repository addRuleBase!user1 * COM.TIBCO.hawk.microagent.Repository updateRuleBase!user1 * COM.TIBCO.hawk.microagent.Repository deleteRuleBase!user1 * COM.TIBCO.hawk.microagent.Repository setSchedules!user1 * COM.TIBCO.hawk.microagent.Repository setRBMap!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine addRuleBase!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine updateRuleBase!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine deleteRuleBase!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine loadRuleBase!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine unloadRuleBase!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine loadRuleBaseFromFile!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine setSchedules!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine setRBMapTIBCO Hawk Installation and Configuration

To Use the Trusted Model| 167user2 + * +!user2 * COM.TIBCO.hawk.microagent.Custom +!user2 * COM.TIBCO.hawk.microagent.Repository +!user2 * COM.TIBCO.hawk.microagent.RuleBaseEngine +user3!user3 + COM.TIBCO.hawk.microagent.RuleBaseEngine +user4nodeBuser5 * * *## To activate logging, uncomment the following:# -log_dir logDir -log_max_size size -log_max_num n## where: logDir is the directory where the log file will be stored# size is the maximum size of a rotating log file in KB.# A suffix m or M can be used for indicating MB .# n is the maximum number of rotating log files.TrustedWithDomain.txt Example File## This file is used by agent running with# COM.TIBCO.hawk.security.trusted.TrustedWithDomain security model.## To allow a user running with COM.TIBCO.hawk.security.trusted.TrustedWithDomain# security model on Windows platform to access this agent, the user# specified should include the domain of the user.# For example, for user1 in domainX, the user should be specified as# "domainX\user1".## Note that agents using the TrustedWithDomain security model also allow# users running with COM.TIBCO.hawk.security.trusted.Trusted security model# to access this agent. For these users, the domain should not be# included in the user.### Explanation of Settings:## Grant "user1" point-to-point access to all methods on all Microagents, EXCEPT#- all ACTION methods on the Custom microagent on all nodes.# - the specified methods on the Repository microagent on all nodes.# - the specified methods on the RuleBaseEngine microagent on "nodeA".## Grant "user2" point-to-point and network access to all methods on all# Microagents, EXCEPT#- all ACTION methods on the Custom microagent on all nodes.#- all ACTION methods on the Repository microagent on all nodes.#- all ACTION methods on the RuleBase microagent on all nodes.## Grant "user3" point-to-point and network access to all methods on allTIBCO Hawk Installation and Configuration

168 Chapter 11 Security|# Microagents on all nodes, EXCEPT#- network access to all ACTION methods on the RuleBase microagent.## Grant "user4" full access to all methods on all microagents on nodeB.## Grant "user5" point-to-point access to all INFO methods on all microagents# on all nodes.### Wildcard characters + and * usage:## - Use + in node access for allowing access to group operations.# - Use * in node access for allowing access to point-to-point invocations.# - Use + in method access for allowing access to all INFO and ACTION methods.# - Use * in method access for allowing access to all INFO methods only.### File format:## user node microagent method# access access access# & & &# restrictions restrictions restrictions#user1 *!user1 * COM.TIBCO.hawk.microagent.Custom +!user1 * COM.TIBCO.hawk.microagent.Repository addRuleBase!user1 * COM.TIBCO.hawk.microagent.Repository updateRuleBase!user1 * COM.TIBCO.hawk.microagent.Repository deleteRuleBase!user1 * COM.TIBCO.hawk.microagent.Repository setSchedules!user1 * COM.TIBCO.hawk.microagent.Repository setRBMap!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine addRuleBase!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine updateRuleBase!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine deleteRuleBase!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine loadRuleBase!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine unloadRuleBase!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine loadRuleBaseFromFile!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine setSchedules!user1 nodeA COM.TIBCO.hawk.microagent.RuleBaseEngine setRBMapuser2 + * +!user2 * COM.TIBCO.hawk.microagent.Custom +!user2 * COM.TIBCO.hawk.microagent.Repository +!user2 * COM.TIBCO.hawk.microagent.RuleBaseEngine +user3!user3 + COM.TIBCO.hawk.microagent.RuleBaseEngine +user4nodeBuser5 * * *## To activate logging, uncomment the following:# -log_dir logDir -log_max_size size -log_max_num n## where: logDir is the directory where the log file will be storedTIBCO Hawk Installation and Configuration

To Use the Trusted Model| 169# size is the maximum size of a rotating log file in KB.# A suffix m or M can be used for indicating MB .# n is the maximum number of rotating log files.Running with a localhost rvdAs a further precaution, AMI applications will be required to specify localhostas part of the TIBCO Rendezvous daemon parameter in order to prevent remoteconnections to its rvd daemon. Instructions to do this for UNIX and MicrosoftWindows platforms are given below.UNIX Procedure1. Add a command to start the localhost rvd prior to starting any TIBCO Hawkprocesses, as follows:rvd -listen tcp:127.0.0.1:2. Modify hawkagent.cfg and hawkhma.cfg and, in the -rvd_sessionparameter, specify the following:tcp:127.0.0.1:Microsoft Windows ProcedureUse rvntsreg.exe to install a localhost rvd as a Microsoft Windows service. Theprocedure is similar to that given in Setting Up Network Communication inMicrosoft Windows, page 141. See that section for a fuller description.1. Create an rvd service using rvntsreg.exe. See Installing a Routing Daemonas a Microsoft Windows Service, page 141, for details. Use the followingparameters:-listen tcp:127.0.0.1:2. Make all TIBCO Hawk services dependent upon this new rvd service. SeeMaking TIBCO Hawk Services Depend on the Routing Daemon MicrosoftWindows Service, page 142, for details.3. In the Configuration Utility, modify the daemon parameter to the following:tcp:127.0.0.1:TIBCO Hawk Installation and Configuration

170 Chapter 11 Security|Trusted Security Sample ImplementationThe sample implements the Trusted model describes in Trusted Model. Thisimplementation is similar to the default security model provided by Hawk.CodeThe sample implementation for Trusted Security is provided in the/samples/security directory.CompileWhile compiling the security sample, your CLASSPATH must includeconsole.jar from TIBCO Hawk lib folder.RunTo enable the security for the Hawk Agent and Display, refer to -security_policyon page 53 for more details.TIBCO Hawk Installation and Configuration

Configuring Plugins and Adapters| 171Chapter 12Configuring Plugins and AdaptersThis chapter provides a detailed procedure to install and configure the Pluginsand Adapters. Adapter and plugins are installed to their repective "adapters" and"plugins" folder. Within the folder, there is a readme.txt file that describes whatconfiguration needs to be edited before manually copying it to the Webapps orplugin directory.Topics• Configuring TIBCO Hawk Java Virtual Machine MicroAgent Plug-in,page 172• Configuring TIBCO Hawk Common Logging Publisher MicroAgent Plug-in,page 173• Configuring TIBCO Hawk AMXHost MicroAgent Plug-in, page 174TIBCO Hawk Installation and Configuration

172 Chapter 12 Configuring Plugins and Adapters|Configuring TIBCO Hawk Java Virtual Machine MicroAgent Plug-inTIBCO Hawk Java Virtual Machine Plug-in software enables TIBCO Hawk tomonitor and manage Java virtual machine processes started by the same user onthe local machine.To configure this plug-in into your TIBCO Hawk installation:1. Copy the hawkvm.hma file from /hawk/4.9/plugin/jvm to/hawk/plugin.2. Edit and verify hawkvm.hma in /hawk/plugin to correctversion and path of jars and Trace Log Configuration.--traceDir%TIBCO_HAWK_HOME_ESC%/plugin/jvm/log--traceFilenamejvmhma.log--traceLevel73. Edit /hawk/bin/tibhawkagent.tra to add/lib/tools.jar in tibco.class.path.extended, ifusing external JRE and not already added.4. Make sure the -hma_plugin_dir property is uncommented and have a value"/hawk/4.9/plugin" in/hawk/bin/hawkagent.cfg.5. Make sure the "application.args -file hawkagent.cfg" uncommented in/hawk/bin/tibhawkagent.tra.6. Restart the Hawk Agent.TIBCO Hawk Installation and Configuration

Configuring TIBCO Hawk Common Logging Publisher MicroAgent Plug-in| 173Configuring TIBCO Hawk Common Logging Publisher MicroAgentPlug-inTIBCO Hawk Common Logging Event Publisher Plug-in software enables TIBCOHawk to emit events from Hawk using TIBCO Common Logging in Base EventFormat (BEF)/Common Base Event (CBE), default is Base Event Format.To configure this plug-in into your TIBCO Hawk installation:1. Copy the hawkcleventpublisher.hma file from/hawk/4.9/plugin/commonlogging to/hawk/plugin.2. Create Event Definitions file to define the Event Publisher details:a. Create Event Definitions file using commonlogging/eventdefs.xsd andrefer the existing sample event definitions file sampleEventdefs.xml.b. Create Common Logging configurtion file (refer/use existingsample_log4j.xml) and provide entry of file into event defintions file.3. Edit hawkcleventpublisher.hma in /hawk/plugin.a. Provide correct name and path of the event definitions file.b. Ensure the correct version number of plugins.4. Copy the -hma_plugin_dir in hawkagent.cfg to/hawk/plugin.5. Restart the Hawk Agent.TIBCO Hawk Installation and Configuration

174 Chapter 12 Configuring Plugins and Adapters|Configuring TIBCO Hawk AMXHost MicroAgent Plug-inTIBCO Hawk AMXHost Plug-in software enables the TIBCO Hawk to monitorand manage TIBCO ActiveMatrix 3.0 Host Instance.To configure this plug-in into your TIBCO Hawk installation:1. Copy the hawkamxhpa.hma file from /hawk/4.9/plugin/amxto /hawk/plugin.2. To provide AMX Host Management URL and other details, edit theAMXHostPluginConfig.xml in /hawk/4.9/plugin/amx.3. Edit and verify hawkamxhpa.hma in /hawk/plugin tocorrecta. Version and path of jars, andb. Trace Configuration--traceDir%TIBCO_HAWK_HOME_ESC%/plugin/amx/log : Make sure thisdirectory exists.--traceFilenameamxhosthma.log--traceLevel74. Ensure that the -hma_plugin_dir property is uncommented and has avalue "/hawk/4.9/plugin" in the/hawk/bin/hawkagent.cfg.5. Edit /hawk/bin/tibhawkagent.tra to add/lib/tools.jar in the tibco.class.path.extended, ifusing external JRE and not already added.6. Ensure that the "application.args -file hawkagent.cfg" isuncommented in tibhawkagent.tra.7. Restart the Hawk Agent.TIBCO Hawk Installation and Configuration

| 175Appendix AMigrationThis appendix discusses issues related to migration.Topics• Re-Linking C and C++ Applications to Libraries, page 176• Changing the Codepage Setting, page 176• Using 3.x and 4.x Agents Together, page 176• Using the Scheduler, page 176• Converting Commands from Previous Releases, page 176TIBCO Hawk Installation and Configuration

176 Appendix A Migration|Migration IssuesThe following considerations apply when migrating from a previous version ofTIBCO Hawk.Re-Linking C and C++ Applications to LibrariesThe AMI C and C++ libraries were renamed to eliminate a naming conflict withOS libraries. After installing TIBCO Hawk, all AMI C or C++ applications must bere-linked against the renamed libraries.Changing the Codepage Setting(Microsoft Windows only)The TIBCO Hawk installation program automatically retains your previousconfiguration. If the previous version of TIBCO Hawk specified a codepagesetting for the HMA other than 65001 (Microsoft Windows identifier for UTF-8),you will need to manually change the codepage setting to 65001 after installingthis version. UTF-8 is now the default for all TIBCO Hawk components.Using 3.x and 4.x Agents TogetherYou can include TIBCO Hawk 4.x and 3.x Agents in the same environment.However, if you load the same rulebase on each agent, TIBCO Hawk Display willshow the rulebases as being different versions.Using the SchedulerThe Scheduler in TIBCO Hawk 4.1 uses 1-minute intervals instead of 15-minuteintervals, as were used in 4.0.x. TIBCO Hawk 4.0.x agents using schedules that aresent to 4.1 will be converted to minutes instead of the 15-minute interval.Likewise, TIBCO Hawk 4.1 schedules that are send to a 4.0.x agent will have theminute converted to the nearest 15-minute interval.Converting Commands from Previous ReleasesCommands created prior to the TIBCO Hawk 4.1.0 will automatically beconverted when executed using the current release.• If an agent command in a previous release has Append Agent Name checked,the variable ${Internal.Agent Name} will be appended to the command.TIBCO Hawk Installation and Configuration

Migration Issues| 177• If an agent command in a previous release has Append Agent IP Addresschecked, the variable ${Internal. Agent IP Address} will be appended tothe command.TIBCO Hawk Installation and Configuration

178 Appendix A Migration|TIBCO Hawk Installation and Configuration

| 179Appendix BTroubleshootingThis appendix presents some common problems and error conditionsencountered during TIBCO Hawk installation and describes how to resolve them.Topics• UNIX Errors, page 180• Microsoft Windows Errors, page 182• General Errors, page 184TIBCO Hawk Installation and Configuration

180 Appendix B Troubleshooting|UNIX ErrorsThis section lists possible installation errors on UNIX along with solutions.DISPLAY Variable Error(Only when installing in a GUI environment)The installer on UNIX must open an additional window, generally for graphics. Ituses the DISPLAY environment variable to tell it on which computer to open thewindow. If the environment variable is not set, the installer will either wait orabort after displaying the following message:InstallShield WizardInitializing InstallShield Wizard...Preparing Java(tm) Virtual Machine.................................................................................The DISPLAY variable must be set to the IP address or name of the computer (onwhich the installer graphics window are to be displayed), followed by a screenaddress, which can be :0.0. For example:# Bourne shellDISPLAY=:0.0; export DISPLAY# Korn shellexport DISPLAY=:0.0# C-shellsetenv DISPLAY :0.0For example, consider a scenario where you install TIBCO Hawk on a remoteHP-UX machine (named itaska). Because you have a Solaris machine (namedalaska) with a video card and monitor, you can run an X-window application onit. So you decide to telnet to itaska from alaska.When you telnet to itaska, you will not get access to itaska's monitor and willbe unable to display an X-window application. That is why you must set theDISPLAY variable, which instructs the X-server to redirect all windows to thecomputer set in the variable. Before doing so, the computer (specified in theDISPLAY variable) must give permissions to share its monitor.alaska> xhost + # give permission for all to its share monitoralaska> telnet itaskaWelcome to HPUX itaska 11.00User:Password:itaska> export DISPLAY=alaska:0.0 # set display on alaskaitaska> TIB_hawk-simple_4.6.0_s4_56.binTIBCO Hawk Installation and Configuration

UNIX Errors| 181PID Error (HP-UX 11.00 64 bit Platform Only)The following error can occur only on HP-UX 11.00 64 bit systems. It does nothappen on an HP-UX 11.00 32 bit system or an HP-UX 11.11 (or 11.i) system.Installation on a HP-UX 11.00 64 bit system may crash with the following errormessage:Pid nnn killed due to trashed stack.Pid nnn was killed due to failure in writing the signal context.If this error occurs, install HP-UX kernel patch PHKL_27282 and then installTIBCO Hawk.Assertion Failed Error (HP-UX Only)When installing as root user on HP-UX, you may get the following error:Assertion failed: so->so_hard_contents, file softobj.c, line 363If this happens, reinstall TIBCO Hawk as non-root user.TIBCO Hawk Installation and Configuration

182 Appendix B Troubleshooting|Microsoft Windows ErrorsThis section lists possible installation errors on Microsoft Windows along withsolutions.Packet Fragmentation Errors with MulticastYou may encounter packet fragmentation errors when using multicast onMicrosoft Windows XP. This is due to a known issue in Microsoft Windows.You may need to apply a Microsoft hot fix. Information about obtaining the fix isin Microsoft Knowledge Base Article Q319627.String Variable ErrorIn Microsoft Windows, a command line has a limit of 1024 characters. The startupcommand for TIBCO Hawk (which includes the installation path and a largenumber of required jar files) may be longer than 1024 characters if TIBCO Hawkwas installed into a directory with a long installation pathname.If the startup command is too long, the following error message appears whenyou try to start TIBCO Hawk:String variable is not large enough for string.Check the string declarations.Error 401In this case, you must reinstall Hawk with a shorter installation path.Incompatible LibrariesIf the versions of libeay32.dll and ssleay32.dll in the directoryC:\Windows\system32 are not compatible with TIBCO Rendezvous, then TIBCOapplications may fail when trying to use TIBCO Rendezvous. When running orinstalling TIBCO applications, the following message appears.Ordinal xxxx could not be found in the dynamic link libraryLIBEAY32.dll.orOrdinal xxxx could not be found in the dynamic link librarySSLEAY32.dll.TIBCO Hawk Installation and Configuration

Microsoft Windows Errors| 183Rename, remove, or replace the files libeay32.dll and ssleay32.dll in theC:\Windows\system32 directory with the files in TIBCO_RV_HOME\bin. Be sure torename, remove, or replace both files or the problem will persist.TIBCO Hawk Installation and Configuration

184 Appendix B Troubleshooting|General ErrorsThis section lists installation errors that can occur on both UNIX and MicrosoftWindows.Errors Using the Password ScriptOn UNIX platforms, if TIBCO Runtime Agent is the first installed TIBCO productand you use the /bin/tibhawkpassword script, you see thefollowing error :Exception in thread "main" java.lang.NoClassDefFoundError:com/tibco/security/AXSecurityExceptionThis error is because the script is unable to locate the TIBCO EMS libraries. Installthe TIBCO EMS Java client and set the EMS_ROOT environment variable (eitherfrom the command-line or in your login shell) with the location of TIBCO EMSdirectory before using the script.Directory Path Too LongThe command line for starting the Java processes specifies the Hawk directorypath you provide during installation, along with the names of a number of jarfiles. The installer checks the length of the directory path as you enter it duringinstallation. If the Hawk directory path plus the jar files result in a Java processcommand line longer than 1024 characters (the Microsoft Windows limit), theinstaller displays the following error message after you enter the directory path:String variable is not large enough for string.Check the string declarations.Error 401Specify a shorter installation path. Also make sure the jar files specified in thecommand line are all required files.Cannot Initialize DisplayTIBCO Hawk Display stops after the Initializing subscriptions screen anddisplays the message Unable to Initialize TIBCO Hawk Display.This is usually caused by missing files in the CLASSPATH. Check your CLASSPATHenvironment variable and make sure it includes the file:/lib/tibrvj.jarSpecify only tibrvj.jar in your CLASSPATH.TIBCO Hawk Installation and Configuration

General Errors| 185TIBCO Hawk Service Failed to Install (Error 1057)Either form of the following error message can be generated by the MicrosoftWindows Service Manager:Hawk agent service failed to install. Error code is 1057Event Service Failed to Install. Status is 1057This means that the user account specified for starting the TIBCO Hawk servicesdoes not have sufficient privileges to start the services.Because this error occurs during installation, you will not be able to change theaccount used to start the services (the services will not appear in the list ofservices in your Services control panel).To resolve the situation, uninstall the TIBCO Hawk software, then install thesoftware again giving a valid account. To uninstall the software, selectStart>Programs>TIBCO Hawk Software>UnInstall.No Administrator PrivilegeDuring TIBCO Hawk installation on Microsoft Windows, if you encounter thefollowing message:Severe - You must have administrator privilege to install HawkServices.You need to log back into the machine as a user with local administratorprivileges to correctly install TIBCO Hawk software.Installation Problems (Error 1073)If you encounter any of the following messages, you need to re-install TIBCOHawk:• HMA Service failed to install. Error code is 1073• Hawk Agent Service failed to install. Error code is 1073• Event Service failed to install. Status is 1073Service Not Started (Error 1069)The system displays the following message:Could not start the TIBCO Hawk service ... Error 1069: Theservice did not start due to a logon failure."This error indicates one of the following situations:• An invalid account was specified.• The account on which the TIBCO Hawk services are being run does not haveadministrative privileges.TIBCO Hawk Installation and Configuration

186 Appendix B Troubleshooting|• The account on which the TIBCO Hawk services are being run does not have"Log on as a service" privileges. Make sure the account has the correctprivileges.• The wrong password was given for the account on which the TIBCO Hawkservices are being run.See Installing on Microsoft Windows, page 9, for more information on thesesettings.TIBCO Hawk Services Fail to Start After InstallationAfter you have completed TIBCO Hawk installation on Microsoft Windows, ifnone of the TIBCO Hawk services will start, use the Event Viewer to check forerror messages related to the TIBCO Hawk services in the Application Log.If any messages contain the text "... could not be spawned", make sure thatTIBCO Rendezvous is correctly installed, and that you rebooted the machine afterboth the TIBCO Rendezvous and TIBCO Hawk installations. (After each newinstallation or re-installation of TIBCO Rendezvous or TIBCO Hawk software onMicrosoft Windows, you must reboot the machine before using the software.)Internal Error 2140The system displays the following message:Error 2140: An internal Windows error occurred.This message probably means the services cannot find crucial TIBCO Rendezvousfiles. Usually this is because one of two environment variables, CLASSPATH orPATH, is set incorrectly.To view and change environment variables:1. Choose Start>Settings>Control Panel, double-click the System icon, and clickthe Environment tab.2. In System Variables, check that your CLASSPATH variable includes the file\lib\tibrvj.jar.3. In System Variables, check that your PATH environment variable includes thedirectory \bin.To change an environment variable:1. Select the variable in the System Variables list.2. Change the text in the edit box labeled Value.3. Click Set.If, after checking these variables, you still get the error, try removing all other filesTIBCO Hawk Installation and Configuration

General Errors| 187from your CLASSPATH, so that it includes only the tibrvj.jar file (writingdown the names of the removed files is recommended, to make sure none areomitted on re-installation). Reboot and try the services again. If this corrects theerror, re-add other files to the CLASSPATH one at a time, after the TIBCORendezvous file.You can also determine your CLASSPATH and PATH settings by opening a DOScommand-line window and typing echo %CLASSPATH% or echo %PATH%.Because TIBCO Hawk is a Microsoft Windows service, all changes made to theenvironment and registry require that the Microsoft Windows machine berebooted for the changes to propagate to the Microsoft Windows Service.If you have checked all of these possibilities, and you still get Error 2140, verifythat the Microsoft Windows Service Pack 4 was reinstalled after any recent majorchanges were made, before contacting TIBCO Hawk technical support.Initial Never ReceivedWhen using TIBCO EMS as the primary transport, you see the following errormessage when starting TIBCO Hawk DisplayInitial Never ReceivedMake sure tibrvjms.jar is placed before tibrvj.jar in your CLASSPATH.Failed to connect to EMS server. Exception: When using TIBCO EMS as the primary transport, if the EMS server hasauthentication enabled and you are using multiple URLs to specify the EMStransport parameters and you may get the error:Failed to connect to EMS server. Exception .Make sure the username and password specified in the EMS transport parametersare valid even though the error does not mention failed user authentication to bethe cause of the error message.TIBCO Hawk Installation and Configuration

188 Appendix B Troubleshooting|TIBCO Hawk Installation and Configuration

| 189Appendix CTIBCO Hawk Directories and FilesThis appendix lists the files installed with TIBCO Hawk on Microsoft Windowsand UNIX platforms.Topics• TIBCO Hawk Directory Structure, page 190TIBCO Hawk Installation and Configuration

190 Appendix C TIBCO Hawk Directories and Files|TIBCO Hawk Directory StructureThis section explains the directory structure and general placement of files inTIBCO_HOME, HAWK_HOME and CONFIG_FOLDER.Table 28 explains the directory structure and general placement of files in theTIBCO_HOME of TIBCO Hawk software installation subdirectories. The datadirectory is created only if the TIBCO Hawk event service is installed, and files areplaced in it only when the event service is started.Table 28 TIBCO_HOME Files and DirectoriesDirectory Description ContentsTIBCO_HOME = TIBCO_HOME\components\shared\1.0.0TIBCO_HOME\components\shared\1.0.0\featuresTIBCO_HOME\components\shared\1.0.0\pluginsTIBCO_HOME\hawk\ =TIBCO_Hawk_HOMETIBCO_HOME\tibcojreTIBCO_HOME\tibrvThe directory in which TIBCO Hawksoftware is installed.Contains all the features and eclipseplug-ins required by Hawk componentslike AMXHPAMicroAgent,JVMMicroagent andCLEventPublisherMicroAgent. It alsocontains plug-ins shared by componentssuch as common logging, JMS, TIBCORendezvous, and so on.Contains all the features required forHawk components.Contains all the Eclipse plugins requiredfor Hawk features.Stores all the files and folders for TIBCOHawk.Contains files used by JRE.Contains files used by TIBCORendezvous.\features\plugins\uninstaller_archivestib_hawk__readme.txttib_hawk_release_notes.pdfTIBCO Hawk Installation and Configuration

TIBCO Hawk Directory Structure| 191Table 28 TIBCO_HOME Files and Directories (Cont’d)Directory Description ContentsTIBCO_HOME\tools\lib\machinemodel\scripts\universal_installer\vcredist_x86\wrapperTIBCO_HOME\uninstaller_archivesTIBCO_HOME\_installInfo\assembly_registryrv_8.3_prodInfo.xmlhawk_4.9_prodInfo.xmlTIBCO_HOME\_uninstallTable 29 explains the directory structure and general placement of files in theHAWK_HOME.Table 29 TIBCO HAWK_HOME Files and DirectoriesDirectory Description ContentsTIBCO_Hawk_HOME\adapters\httpTIBCO_Hawk_HOME\admin-pluginsContains all the files required by HTTPAdapter.Contains the files for the Hawk plug-ins.\css\jsp\META-INF\TIBHawk\WEB-INF\xsd\xslindex.htmlreadme.txtallalertconsole.warhawkconfig.warmonitoringconsole.warTIBCO Hawk Installation and Configuration

192 Appendix C TIBCO Hawk Directories and Files|Table 29 TIBCO HAWK_HOME Files and Directories (Cont’d)Directory Description ContentsTIBCO_Hawk_HOME\ami_apiTIBCO_Hawk_HOME\autoconfigTIBCO_Hawk_HOME\binTIBCO_Hawk_HOME\configContains all header files required forsample programs.Used to store rulebase files that will beloaded by the TIBCO Hawk agentautomatically at startup.Contains TIBCO Hawk executable filesand starting scripts.Used to store rulebase files if usingmanual rulebase configuration.\binNote: There is no bin folder onUNIX based system afterinstallation.\include\libNote: Files differ on Windows andUNIX based system afterinstallation.\src.hrbschedules.hsfAdditional files for UNIX, Linux,and IBM i5/OSConfigureMonitoringmarspottibhawkagenttibhawkdisplaytibhawkhmastarthmaAdditional files for MicrosoftWindowsEventLogClass.dllHawkRandomAccessFile.dllHawkTrustedUserID.dllmsvcr80.dlltibhawkconfig.exetibhawkmsg.dlltibhawkregistry.dlltibhawkservice.dllTibRendezvous.hrbTIBCO Hawk Installation and Configuration

TIBCO Hawk Directory Structure| 193Table 29 TIBCO HAWK_HOME Files and Directories (Cont’d)Directory Description ContentsTIBCO_Hawk_HOME\dataTIBCO_Hawk_HOME\docTIBCO_Hawk_HOME\libTIBCO_Hawk_HOME\pluginTIBCO_Hawk_HOME\resourceTIBCO_Hawk_HOME\samplesTIBCO_Hawk_HOME\setupTIBCO_Hawk_HOME\uninstaller_archivesContains TIBCO Hawk event service datafiles. Files are placed in this directory onlywhen the event service is started.Contains TIBCO Hawk documentation inHTMl and PDF format.Contains TIBCO Hawk Java class jar files.Contains files used by plugins of TIBCOHawk.Contains files used by TIBCO HawkDisplay.Contains sample applications with AMIinterfaces, sample rulebases, scripts, andother files.Lists the archives that will be removedduring uninstallation.Event.datEvent1.dat.\html\pdflicense.pdf\amx\commonlogging\ems\jvmHawkGui.propertiesami_apiconsole_apima_pluginmsghmarbmap_apirulebase_apirulebasesschedule_apisecurityinstall.propertiesinstall.properties_backupinstall.properties_templatepost-install.xmlTIBCO Hawk Installation and Configuration

194 Appendix C TIBCO Hawk Directories and Files|Table 29 TIBCO HAWK_HOME Files and Directories (Cont’d)Directory Description ContentsTIBCO_Hawk_HOME\_uninstallContains executable for universaluninstaller.universal_uninstaller.exeTable 30 explains the directory structure and general placement of files in theCONFIG_FOLDER.Table 30 CONFIG_FOLDER Files and DirectoriesDirectory Description Contentscfgmgmt\hawk Contains configuration files. autoconfigbincacheconfigdatalogpluginresourcesecurityTIBCO Hawk Installation and Configuration

| 195Appendix DCode Page IdentifiersThis appendix lists code page identifiers that can be specified to indicate thelocale of the machine running the HMA.Topics• Code Page Identifiers, page 196TIBCO Hawk Installation and Configuration

196 Appendix D Code Page Identifiers|Code Page IdentifiersCode page identifiers are specified as a value in the Codepage field. SeeCodepage on page 92 for details.Table 31 Code Page IdentifiersIdentifier Name037 IBM EBCDIC - U.S./Canada437 OEM - United States500 IBM EBCDIC - International708 Arabic - ASMO 708709 Arabic - ASMO 449+, BCON V4710 Arabic - Transparent Arabic720 Arabic - Transparent ASMO737 OEM - Greek (formerly 437G)775 OEM - Baltic850 OEM - Multilingual Latin I852 OEM - Latin II855 OEM - Cyrillic (primarily Russian)857 OEM - Turkish858 OEM - Multilingual Latin I + Euro symbol860 OEM - Portuguese861 OEM - Icelandic862 OEM - Hebrew863 OEM - Canadian-French864 OEM - ArabicTIBCO Hawk Installation and Configuration

Code Page Identifiers| 197Table 31 Code Page Identifiers (Cont’d)Identifier Name (Cont’d)865 OEM - Nordic866 OEM - Russian869 OEM - Modern Greek870 IBM EBCDIC - Multilingual/ROECE (Latin-2)874 ANSI/OEM - Thai (same as 28605, ISO 8859-15)875 IBM EBCDIC - Modern Greek932 ANSI/OEM - Japanese, Shift-JIS936 ANSI/OEM - Simplified Chinese (PRC, Singapore)949 ANSI/OEM - Korean (Unified Hangeul Code)950 ANSI/OEM - Traditional Chinese (Taiwan; Hong Kong SAR, PRC)1026 IBM EBCDIC - Turkish (Latin-5)1047 IBM EBCDIC - Latin 1/Open System1140 IBM EBCDIC - U.S./Canada (037 + Euro symbol)1141 IBM EBCDIC - Germany (20273 + Euro symbol)1142 IBM EBCDIC - Denmark/Norway (20277 + Euro symbol)1143 IBM EBCDIC - Finland/Sweden (20278 + Euro symbol)1144 IBM EBCDIC - Italy (20280 + Euro symbol)1145 IBM EBCDIC - Latin America/Spain (20284 + Euro symbol)1146 IBM EBCDIC - United Kingdom (20285 + Euro symbol)1147 IBM EBCDIC - France (20297 + Euro symbol)1148 IBM EBCDIC - International (500 + Euro symbol)1149 IBM EBCDIC - Icelandic (20871 + Euro symbol)1200 Unicode UCS-2 Little-Endian (BMP of ISO 10646)TIBCO Hawk Installation and Configuration

198 Appendix D Code Page Identifiers|Table 31 Code Page Identifiers (Cont’d)Identifier Name (Cont’d)1201 Unicode UCS-2 Big-Endian1250 ANSI - Central European1251 ANSI - Cyrillic1252 ANSI - Latin I1253 ANSI - Greek1254 ANSI - Turkish1255 ANSI - Hebrew1256 ANSI - Arabic1257 ANSI - Baltic1258 ANSI/OEM - Vietnamese1361 Korean (Johab)10000 MAC - Roman10001 MAC - Japanese10002 MAC - Traditional Chinese (Big5)10003 MAC - Korean10004 MAC - Arabic10005 MAC - Hebrew10006 MAC - Greek I10007 MAC - Cyrillic10008 MAC - Simplified Chinese (GB 2312)10010 MAC - Romania10017 MAC - Ukraine10021 MAC - ThaiTIBCO Hawk Installation and Configuration

Code Page Identifiers| 199Table 31 Code Page Identifiers (Cont’d)Identifier Name (Cont’d)10029 MAC - Latin II10079 MAC - Icelandic10081 MAC - Turkish10082 MAC - Croatia12000 Unicode UCS-4 Little-Endian12001 Unicode UCS-4 Big-Endian20000 CNS - Taiwan20001 TCA - Taiwan20002 Eten - Taiwan20003 IBM5550 - Taiwan20004 TeleText - Taiwan20005 Wang - Taiwan20105 IA5 IRV International Alphabet No. 5 (7-bit)20106 IA5 German (7-bit)20107 IA5 Swedish (7-bit)20108 IA5 Norwegian (7-bit)20127 US-ASCII (7-bit)20261 T.6120269 ISO 6937 Non-Spacing Accent20273 IBM EBCDIC - Germany20277 IBM EBCDIC - Denmark/Norway20278 IBM EBCDIC - Finland/Sweden20280 IBM EBCDIC - ItalyTIBCO Hawk Installation and Configuration

200 Appendix D Code Page Identifiers|Table 31 Code Page Identifiers (Cont’d)Identifier Name (Cont’d)20284 IBM EBCDIC - Latin America/Spain20285 IBM EBCDIC - United Kingdom20290 IBM EBCDIC - Japanese Katakana Extended20297 IBM EBCDIC - France20420 IBM EBCDIC - Arabic20423 IBM EBCDIC - Greek20424 IBM EBCDIC - Hebrew20833 IBM EBCDIC - Korean Extended20838 IBM EBCDIC - Thai20866 Russian - KOI8-R20871 IBM EBCDIC - Icelandic20880 IBM EBCDIC - Cyrillic (Russian)20905 IBM EBCDIC - Turkish20924 IBM EBCDIC - Latin-1/Open System (1047 + Euro symbol)20932 JIS X 0208-1990 & 0121-199020936 Simplified Chinese (GB2312)21025 IBM EBCDIC - Cyrillic (Serbian, Bulgarian)21027 Extended Alpha Lowercase21866 Ukrainian (KOI8-U)28591 ISO 8859-1 Latin I28592 ISO 8859-2 Central Europe28593 ISO 8859-3 Latin 328594 ISO 8859-4 BalticTIBCO Hawk Installation and Configuration

Code Page Identifiers| 201Table 31 Code Page Identifiers (Cont’d)Identifier Name (Cont’d)28595 ISO 8859-5 Cyrillic28596 ISO 8859-6 Arabic28597 ISO 8859-7 Greek28598 ISO 8859-8 Hebrew28599 ISO 8859-9 Latin 528605 ISO 8859-15 Latin 929001 Europa 338598 ISO 8859-8 Hebrew50220 ISO 2022 Japanese with no halfwidth Katakana50221 ISO 2022 Japanese with halfwidth Katakana50222 ISO 2022 Japanese JIS X 0201-198950225 ISO 2022 Korean50227 ISO 2022 Simplified Chinese50229 ISO 2022 Traditional Chinese50930 Japanese (Katakana) Extended50931 US/Canada and Japanese50933 Korean Extended and Korean50935 Simplified Chinese Extended and Simplified Chinese50936 Simplified Chinese50937 US/Canada and Traditional Chinese50939 Japanese (Latin) Extended and Japanese51932 EUC - Japanese51936 EUC - Simplified ChineseTIBCO Hawk Installation and Configuration

202 Appendix D Code Page Identifiers|Table 31 Code Page Identifiers (Cont’d)Identifier Name (Cont’d)51949 EUC - Korean51950 EUC - Traditional Chinese52936 HZ-GB2312 Simplified Chinese54936 Microsoft Windows XP: GB18030 Simplified Chinese (4 Byte)57002 ISCII Devanagari57003 ISCII Bengali57004 ISCII Tamil57005 ISCII Telugu57006 ISCII Assamese57007 ISCII Oriya57008 ISCII Kannada57009 ISCII Malayalam57010 ISCII Gujarati57011 ISCII Punjabi65000 Unicode UTF-765001 Unicode UTF-8TIBCO Hawk Installation and Configuration

| 203IndexAAdding AMI sessions 96, 99agent heartbeat intervalSetting 140, 144, 144, 144agent name 140, 144, 144, 144-ami_rva_session 96, 99-ami_rvd_session 96, 99automatically, Starting the routing daemonservice 141Cchanges from the previous release xiv-cluster 140, 144, 144, 144Communicating with EMS server using SSL 46, 48, 56,59, 75, 98, 100Configuration Filehawkagent.cfg 52, 52hawkdisplay.cfg 45hawkevent.cfg 73hawkhma.cfg 70configuration on Unix, Setting up the routingdaemon 144configuration, Planning TIBCO Hawk 88Csh users 32customer support xvii, xixrouting 141daemon service, Making TIBCO Hawk servicesdepend on the routing 142default container for the TIBCO Hawk Display 140,144, 144, 144default TIBCO Hawk agent name (-host), Overridingthe 140, 144, 144, 144depend on the routing daemon service, MakingTIBCO Hawk services 142Designating a security policy 140, 144, 144, 144dial-up network connection, Using the TIBCO HawkDisplay over a 140, 144, 144, 144Disk Space and Memory 10, 23, 36EExample TIBCO Rendezvous routing daemon configurationfor TIBCO Hawk messaging 137Hheartbeat intervalSetting 140, 144, 144, 144-host 140, 144, 144, 144Ddaemon configuration for TIBCO Hawk messaging,Example TIBCO Rendezvous routing 137daemon configuration on Unix, Setting up therouting 144daemon service automatically, Starting theIInstall and Generate a Response File 29Install and Generate a Template File 29Install in Silent Mode 15, 28Install Using a Response File 29Install Using Console 14, 28Install Using GUI 14, 28TIBCO Hawk Installation and Configuration

204| IndexInstallation Directories 4Installation Directory 11Installation Media 13, 26Installation Options 14, 27-interval 140, 144, 144, 144Llicense tickets 150RRAM 11, 24routing daemon configuration for TIBCO Hawk messaging,Example TIBCO Rendezvous 137routing daemon configuration on Unix, Setting upthe 144routing daemon service automatically, Startingthe 141routing daemon service, Making TIBCO Hawk servicesdepend on the 142-rva_session 96, 99-rvd_session 96, 99MMessaging microagentconfiguration 121overview 120Nnetwork connection, Using the TIBCO Hawk Displayover a dial-up 140, 144, 144, 144Oover a dial-up network connection, Using the TIBCOHawk Display 140, 144, 144, 144Overriding the default TIBCO Hawk agent name 140,144, 144, 144Ssecurity policy, designating 140, 144, 144, 144security_policy 140, 144, 144, 144service, Making TIBCO Hawk services depend on therouting daemon 142services depend on the routing daemon service, MakingTIBCO Hawk 142Setting the TIBCO Hawk agent heartbeat interval 140,144, 144setting the TIBCO Hawk agent heartbeat interval 144Setting up a TIBCO Rendezvous session 96, 99Setting up the routing daemon configuration onUnix 144Software 11, 24, 36Starting the routing daemon service automatically 141support, contacting xvii, xixTPPlanning TIBCO Hawk configuration 88technical support xvii, xixTemp Directory 11TIBCO Hawk agent heartbeat interval (-interval),Setting 140, 144, 144, 144TIBCO Hawk agent name (-host), Overriding thedefault 140, 144, 144, 144TIBCO Hawk configuration, Planning 88TIBCO Hawk Installation and Configuration

Index| 205TIBCO Hawk Display over a dial-up network connection,Using the 140, 144, 144, 144TIBCO Rendezvous routing daemon configuration forTIBCO Hawk messaging, Example 137TIBCO Software 11, 24, 36TIBCO_HOME xviiTrace level 71tracing 72UUNIX installation 21User Privileges 10, 22, 36Using SSL to connect to EMS server 48, 58, 76, 100EMS server verifying TIBCO Hawk components 49,58, 77, 101TIBCO Hawk components verifying EMS server 48,58, 77, 101Using the TIBCO Hawk Display over a dial-up networkconnection 140, 144, 144, 144Using TIBCO EMS as primary transport 46, 56, 75, 97TIBCO Hawk Installation and Configuration