Installing Candle Products - IBMpublib.boulder.ibm.com/tividd/td/CanInstallDoclnk/GC32...Computing Architecture, Patent Pending; User Interface for System Management Applications,

Installing Candle Productson UNIX

Version CT350

GC32-9217-00

October 2004

Candle Corporation100 North Sepulveda Boulevard

El Segundo, California 90245

2 Installing Candle Products on UNIX (version CT350)

Registered trademarks and service marks of Candle Corporation: AF/OPERATOR, AF/REMOTE, Availability Command Center, Candle, Candle CIRCUIT, Candle Command Center, Candle Direct logo, Candle eDelivery, Candle Electronic Customer Support, Candle logo, Candle Management Server, Candle Management Workstation, CandleLight, CandleNet, CandleNet Command Center, CandleNet eBusiness Platform, CandleNet Portal, CL/CONFERENCE, CL/SUPERSESSION, CommandWatch, CT, CT/Data Server, CT/DS, DELTAMON, DEXAN, eBA, eBA*ServiceMonitor, eBA*ServiceNetwork, eBusiness at the speed of light, eBusiness Assurance, eBusiness Institute, ELX, EPILOG, ESRA, ETEWatch, IntelliWatch, IntelliWatch Pinnacle, MQSecure, MQView, OMEGACENTER, OMEGAMON, OMEGAMON II, OMEGAMON Monitoring Agent, OMEGAMON Monitoring Agents, OMEGAVIEW, OMEGAVIEW II, PQEdit, Response Time Network, Roma, SitePulse, Solutions for Networked Applications, Solutions for Networked Businesses, TMA2000, Transplex, and Volcano.Trademarks and service marks of Candle Corporation: AF/Advanced Notification, AF/PERFORMER, Alert Adapter, Alert Adapter Plus, Alert Emitter, AMS, Amsys, AutoBridge, AUTOMATED FACILITIES, Availability Management Systems, Business Services Composer, Candle Alert, Candle Business Partner Logo, Candle Command Center/SentinelManager, Candle CommandPro, Candle eSupport, Candle Insight, Candle InterFlow, Candle Managing what matters most, Candle Service Suite, Candle Technologies, CandleNet, CandleNet 2000, CandleNet Conversion, CandleNet eBP, CandleNet eBP Access for S.W.I.F.T., CandleNet eBP Administrator, CandleNet eBP Broker Access for Mercator or MQSI, CandleNet eBP Configuration, CandleNet eBP Connector, CandleNet eBP File Transfer, CandleNet eBP Host Connect, CandleNet eBP Object Access, CandleNet eBP Object Browser, CandleNet eBP Secure Access, CandleNet eBP Service Directory, CandleNet eBP Universal Connector, CandleNet eBP Workflow Access, CandleNet eBusiness Assurance, CandleNet eBusiness Exchange, CandleNet eBusiness Platform Administrator, CandleNet eBusiness Platform Connector, CandleNet eBusiness Platform Connectors, CandleNet eBusiness Platform Powered by Roma Technology, CandleNet eBusiness Platform Service Directory, Candle Vision, CCC, CCP, CCR2, CEBA, CECS, CICAT, CL/ENGINE, CL/GATEWAY, CL/TECHNOLOGY, CMS, CMW, Command & Control, Connect-Notes, Connect-Two, CSA ANALYZER, CT/ALS, CT/Application Logic Services, CT/DCS, CT/Distributed Computing Services, CT/Engine, CT/Implementation Services, CT/IX, CT/Workbench, CT/Workstation Server, CT/WS, !DB Logo, !DB/DASD, !DB/EXPLAIN, !DB/MIGRATOR, !DB/QUICKCHANGE, !DB/QUICKCOMPARE, !DB/SMU, !DB/Tools, !DB/WORKBENCH, Design Network, e2e, eBA*SE, eBAA, eBAAuditor, eBAN, eBANetwork, eBAAPractice, eBP, eBusiness Assurance Network, eBusiness at the speed of light, eBusiness at the speed of light logo, eBusiness Exchange, eBX, End-to-End, eNotification, ENTERPRISE, Enterprise Candle Command Center, Enterprise Candle Management Workstation, Enterprise Reporter Plus, ER+, ERPNet, ETEWatch Customizer, HostBridge, InterFlow, Candle InterFlow, Lava Console, Managing what matters most, MessageMate, Messaging Mastered, Millennium Management Blueprint, MMNA, MQADMIN, MQEdit, MQEXPERT, MQMON, NBX, NC4, NetGlue, NetGlue Extra, NetMirror, NetScheduler, New Times, New Team, New Readiness, OMA, OMC Gateway, OMC Status Manager, OMEGACENTER Bridge, OMEGACENTER Gateway, OMEGACENTER Status Manager, OMEGAMON/e, OMEGAMON Management Center, OSM, PathWAI, PC COMPANION, Performance Pac, Powered by Roma Technology, PowerQ, PQConfiguration, PQScope, Roma Application Manager, Roma Broker, Roma BSP, Roma Connector, Roma Developer, Roma FS/A, Roma FS/Access, RomaNet, Roma Network, Roma Object Access, Roma Secure, Roma WF/Access, Roma Workflow Access, RTA, RTN, SentinelManager, Somerset, Somerset Systems, Status Monitor, The Millennium Alliance, The Millennium Alliance logo, The Millennium Management Network Alliance, Tracer, Unified Directory Services, WayPoint, and ZCopy.Trademarks and registered trademarks of other companies: AIX, DB2, MQSeries and WebSphere are registered trademarks of International Business Machines Corporation. Citrix, WinFrame, and ICA are registered trademarks of Citrix Systems, Inc. Multi-Win and MetaFrame are trademarks of Citrix Systems, Inc. SAP is a registered trademark and R/3 is a trademark of SAP AG. UNIX is a registered trademark in the U.S. and other countries, licensed exclusively through X/Open Company Ltd. HP-UX is a trademark of Hewlett-Packard Company. SunOS is a trademark of Sun Microsystems, Inc. All other company and product names used herein may be trademarks or registered trademarks of their respective owners.

Copyright © October 2004, Candle Corporation, a California corporation. All rights reserved. International rights secured.

Threaded Environment for AS/400, Patent No. 5,504,898; Data Server with Data Probes Employing Predicate Tests in Rule Statements (Event Driven Sampling), Patent No. 5,615,359; MVS/ESA Message Transport System Using the XCF Coupling Facility, Patent No. 5,754,856; Intelligent Remote Agent for Computer Performance Monitoring, Patent No. 5,781,703; Data Server with Event Driven Sampling, Patent No. 5,809,238; Threaded Environment for Computer Systems Without Native Threading Support, Patent No. 5,835,763; Object Procedure Messaging Facility, Patent No. 5,848,234; End-to-End Response Time Measurement for Computer Programs, Patent No. 5,991,705; Communications on a Network, Patent Pending; Improved Message Queuing Based Network Computing Architecture, Patent Pending; User Interface for System Management Applications, Patent Pending.

NOTICE: This documentation is provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to restrictions set forth in the applicable license agreement and/or the applicable government rights clause.This documentation contains confidential, proprietary information of Candle Corporation that is licensed for your internal use only. Any unauthorized use, duplication, or disclosure is unlawful.

Citrix is a registered trademark and MetaFrame is a trademark of Citrix Systems, Inc.

Contents 3

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Adobe Portable Document Format . . . . . . . . . . . . . . . . . . . . . . . . . . 16Documentation Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Candle Customer Service and Satisfaction . . . . . . . . . . . . . . . . . . . . 20

What’s New in This Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Chapter 1. Preparing for Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25What Are OMEGAMON XE and OMEGAMON DE? . . . . . . . . . . . . . 26CandleNet Portal Components in This Package. . . . . . . . . . . . . . . . . 32Installation Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Configuring OMEGAMON XE Across a Firewall . . . . . . . . . . . . . . . . 39Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42To Do Before Beginning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Chapter 2. Preparing for Upgrading and Migrating from a Previous Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Upgrade and Migration Planning. . . . . . . . . . . . . . . . . . . . . . . . . . . . 66To Do Before Beginning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Chapter 3. GUI Installation Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Running the Installation Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Manage Candle Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Basic Configuration of Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88CMS Configuration Changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92File Permission Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Security Validation on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95What to Do Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Chapter 4. Command Line Installation Steps . . . . . . . . . . . . . . . . . . . . . . . 99Summary of Steps for Command Line Install . . . . . . . . . . . . . . . . . 100

Contents


Using install.sh to Install from CD-ROM. . . . . . . . . . . . . . . . . . . . . . 101CandleConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Manual Seeding Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115CandleServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118CandleAgent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120CandleAudit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122CandleDBAgent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124cinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126CandleExecute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Verifying Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

Chapter 5. CMS Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137Setting Permissions for a Non-NIS Solaris CMS . . . . . . . . . . . . . . . . 138Overview of the CMS Seeding Process . . . . . . . . . . . . . . . . . . . . . . 139CMS Seeding Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140CMS Name (seeding error 171). . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Hot Standby Operation (optional) . . . . . . . . . . . . . . . . . . . . . . . . . . 144Firewall Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147CandleMigrate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150What to do next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

Chapter 6. Additional Agent Configuration . . . . . . . . . . . . . . . . . . . . . . . 153BEA WebLogic Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154DB2 UDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156eBA Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Oracle and Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158OMEGAMON XE for WebSphere MQ Configuration. . . . . . . . . . . . 170OMEGAMON XE for WebSphere MQ Monitoring . . . . . . . . . . . . . . 172OMEGAMON XE for WebSphere Integration Brokers . . . . . . . . . . . 175R/3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Remedy ARS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Tuxedo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Universal Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197UNIX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204UNIX Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Contents 5

WebSphere InterChange Server . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Chapter 7. Starting and Stopping Candle Products . . . . . . . . . . . . . . . . . 215Using the Manage Candle Services Window . . . . . . . . . . . . . . . . . . 216Verifying Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220CMS Shut Down Using IP.PIPE Protocol . . . . . . . . . . . . . . . . . . . . . 222

Chapter 8. CandleClone Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223Differences between CandleClone and CandleRemote . . . . . . . . . . 224CandleClone Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Using CandleClone in GUI Mode . . . . . . . . . . . . . . . . . . . . . . . . . . 227Using CandleClone in Command Line Mode . . . . . . . . . . . . . . . . . 231

Chapter 9. CandleRemote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Differences between CandleRemote and CandleClone . . . . . . . . . . 234CandleRemote Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Using CandleRemote in GUI Mode . . . . . . . . . . . . . . . . . . . . . . . . . 238Using CandleRemote in Command Line Mode . . . . . . . . . . . . . . . . 242

Appendix A. Multi-platform Installation Configuration Files. . . . . . . . . . . . . 245Multi-platform Installation Program . . . . . . . . . . . . . . . . . . . . . . . . . 246Configuration File Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

Appendix B. Candle Product Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251Product Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252

Appendix C. Maintaining the EIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255EIB Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Appendix D. Candle Architecture Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . 257Architecture Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

Appendix E. Display Setup for Hummingbird eXceed. . . . . . . . . . . . . . . . . 261Procedure for display setup for version 5.xx . . . . . . . . . . . . . . . . . . 262Procedure for display setup for version 6.xx . . . . . . . . . . . . . . . . . . 264

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267


Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Tables 7

Table 1. Symbols in Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Table 2. Products and Versions for Current Release . . . . . . . . . . . . . . . . . . . . 21Table 3. Variables in the Name of Aforementioned Configuration File . . . . . . 37Table 4. CMS Hardware Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Table 5. CMS Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Table 6. Agent Hardware and Software Requirements . . . . . . . . . . . . . . . . . . 47Table 7. SNA Communication Settings for CMSs . . . . . . . . . . . . . . . . . . . . . . 59Table 8. FTP File Types and Names To Copy . . . . . . . . . . . . . . . . . . . . . . . . . 63Table 9. New and Old Directory Structure Equivalents . . . . . . . . . . . . . . . . . . 67

Table 10. Parameters for install.sh Command . . . . . . . . . . . . . . . . . . . . . . . . . . 77Table 11. install.sh Prompts for Install Type to Use . . . . . . . . . . . . . . . . . . . . . . 78Table 12. CMS Configuration Basic Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Table 13. CMS Advanced Settings Parameter Values . . . . . . . . . . . . . . . . . . . . 82Table 14. Manage Candle Services Action Menu . . . . . . . . . . . . . . . . . . . . . . . 85Table 15. Manage Candle Services Options Menu . . . . . . . . . . . . . . . . . . . . . . 86Table 16. Manage Candle Services Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Table 17. Agent to CMS Connection Settings . . . . . . . . . . . . . . . . . . . . . . . . . . 88Table 18. Secondary CMS for Agent Connections Settings . . . . . . . . . . . . . . . . 90Table 19. Parameters for the SetPerm Command . . . . . . . . . . . . . . . . . . . . . . . 93Table 20. Parameters for the SetPerm Command . . . . . . . . . . . . . . . . . . . . . . . 95Table 21. Parameters for Executing install.sh . . . . . . . . . . . . . . . . . . . . . . . . . 102Table 22. Numbers for Types of Installations . . . . . . . . . . . . . . . . . . . . . . . . . . 103Table 23. Options in CandleConfig Commands . . . . . . . . . . . . . . . . . . . . . . . 109Table 24. Parameters for the Command for Starting a CMS . . . . . . . . . . . . . . 115Table 25. Parameters for the CandleSeed Command . . . . . . . . . . . . . . . . . . . 116Table 26. Parameters for the Command for Stopping a CMS . . . . . . . . . . . . . 117Table 27. Parameters for the Command for Restarting a CMS . . . . . . . . . . . . 117Table 28. Options for the CandleServer Command . . . . . . . . . . . . . . . . . . . . 118Table 29. Arguments for the CandleServer Command . . . . . . . . . . . . . . . . . . 118Table 30. Options for the CandleAgent Command . . . . . . . . . . . . . . . . . . . . . 120Table 31. Options for the CandleAudit Command . . . . . . . . . . . . . . . . . . . . . 122

Tables


Table 32. Arguments for the CandleAudit Command . . . . . . . . . . . . . . . . . . . 122Table 33. Options for the CandleDBAgent Command . . . . . . . . . . . . . . . . . . 124Table 34. Arguments for the CandleDBAgent Command . . . . . . . . . . . . . . . . 125Table 35. Options for the cinfo Command . . . . . . . . . . . . . . . . . . . . . . . . . . . 126Table 36. Arguments for the cinfo Command . . . . . . . . . . . . . . . . . . . . . . . . . 127Table 37. Options for the CandleExecute Command . . . . . . . . . . . . . . . . . . . 132Table 38. Parameters of Lock File Name. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135Table 39. Parameters for the QuickSeed Procedure . . . . . . . . . . . . . . . . . . . . 140Table 40. Parameters for Commands for Migrating Tables. . . . . . . . . . . . . . . . 151Table 41. JMX Collector for BEA WebLogic Server Configuration Values . . . . 154Table 42. Agent for eBA Solutions Advanced Configuration Values . . . . . . . . 157Table 43. Parameters for the CandleSeed Command to Seed cf . . . . . . . . . . . 170Table 44. R/3 Agent Parameter Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182Table 45. SAP Values in sa_[System_Name].config . . . . . . . . . . . . . . . . . . . . 187Table 46. R/3 Logon Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . 190Table 47. Special Values for SAPUSER and SAPPASSWORD. . . . . . . . . . . . . 190Table 48. AA for Remedy ARS Agent Configuration Values . . . . . . . . . . . . . . 193Table 49. Tuxedo Monitoring Agent Parameter Configuration Values . . . . . . . 194Table 50. API Client Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198Table 51. Agent ID Field Description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206Table 52. Parameters for the Commands to Start the Manage Candle

Services Window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216Table 53. Parameters of Log File Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221Table 54. Difference Summary Between CandleClone and CandleRemote. . . 224Table 55. Options for CandleClone Command . . . . . . . . . . . . . . . . . . . . . . . . 226Table 56. Arguments for CandleClone Command. . . . . . . . . . . . . . . . . . . . . . 226Table 57. Options for Starting CandleClone . . . . . . . . . . . . . . . . . . . . . . . . . . 227Table 58. CandleClone – Set Clone Options Fields and Descriptions . . . . . . . 229Table 59. Options for Starting CandleClone . . . . . . . . . . . . . . . . . . . . . . . . . . 231Table 60. Options for Starting CandleClone in Command Line Mode . . . . . . 231Table 61. Difference Summary Between CandleRemote and CandleClone. . . 234Table 62. Options for the CandleRemote Command . . . . . . . . . . . . . . . . . . . 236Table 63. Arguments for the CandleRemote Command . . . . . . . . . . . . . . . . . 236Table 64. Options for Creating Remote Packages . . . . . . . . . . . . . . . . . . . . . . 238Table 65. Options for Creating Remote Packages . . . . . . . . . . . . . . . . . . . . . . 242Table 66. Options for Creating Remote Packages in Command Line Mode. . . 242

Tables 9

Table 67. Additional Configuration Files Supported . . . . . . . . . . . . . . . . . . . . 250Table 68. Product Codes for UNIX Systems . . . . . . . . . . . . . . . . . . . . . . . . . . 252Table 69. Product Codes for non-UNIX Systems. . . . . . . . . . . . . . . . . . . . . . . 253Table 70. EIB Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256Table 71. Candle Operating System Architecture Abbreviations . . . . . . . . . . . 258


Figures 11

Figure 1. OMEGAMON XE Platform Components . . . . . . . . . . . . . . . . . . . . . . 27Figure 2. Configuration Including a Remote CMS . . . . . . . . . . . . . . . . . . . . . . 31Figure 3. Using NFS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Figures


Preface 13

Preface

IntroductionThis installation guide contains instructions for installing the OMEGAMON® XE product family on the following UNIX platforms:

� AIX

� Solaris

� HP-UX

� Linux

Preface contents

About This Book . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

Adobe Portable Document Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16Documentation Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Candle Customer Service and Satisfaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

P

About This Book


About This Book

Who should read this bookThis guide was written for individuals who install and configure Candle® products on UNIX systems. Installers should have a working knowledge of the UNIX operating system and a basic knowledge of networking.

Users of this guide must know the planned configuration for their OMEGAMON XE environment. They should consult with their Candle system administrator to ensure that they know where the Candle Management Server® (CMS™), CandleNet Portal® Servers, Candle Management Workstation® (CMW™), CandleNet Portal, and the agents are to be installed.

Scope of this guideNotice many of the applications require prior purchase and installation of third-party software. It is beyond the scope of this guide to instruct you in how to install or configure non-Candle software.

Documentation set informationThis guide covers the UNIX operating system platforms; however, most Candle installations comprise several platforms. Refer to the following guides:

On the mainframe (CICAT™, version 300, users):

� Installation and Configuration of Candle Products on OS/390 and z/OS

On the mainframe (versions of CICAT prior to version 300):

� Installing Candle Products on MVS

� Installing Candle Products and Candle Management Server on MVS

On distributed platforms:

� Installing Candle Products on Windows

� Installing Candle Products on OS/400

� Installing Candle Products on HP NonStop Kernel

As in previous releases, product-specific Configuration and Customization Guides may also be provided.

Preface 15

About This Book

Where to look for more informationFor more information related to this product and other related products, please see the

� Technical documentation CD-ROM that came with your product.

� Technical documentation information available on the Candle Web site at https://www.candle.com/www1/techdocs/red.html.

� Online help provided with this and the other related products.

Adobe Portable Document Format



Printing this bookCandle supplies documentation in the Adobe Portable Document Format (PDF). The Adobe Acrobat Reader will print PDF documents with the fonts, formatting, and graphics in the original document. To print a Candle document, do the following:

1. Specify the print options for your system. From the Acrobat Reader Menu bar, select File > Page Setup… and make your selections. A setting of 300 dpi is highly recommended as is duplex printing if your printer supports this option.

2. To start printing, select File > Print... on the Acrobat Reader Menu bar.

3. On the Print pop-up, select one of the Print Range options for� All� Current page� Pages from: [ ] to: [ ]

4. (Optional). Select the Shrink to Fit option if you need to fit oversize pages to the paper size currently loaded on your printer.

Printing problems?The print quality of your output is ultimately determined by your printer. Sometimes printing problems can occur. If you experience printing problems, potential areas to check are:� settings for your printer and printer driver. (The dpi settings for both your

driver and printer should be the same. A setting of 300 dpi is recommended.)

� the printer driver you are using. (You may need a different printer driver or the Universal Printer driver from Adobe. This free printer driver is available at www.adobe.com.)

� the halftone/graphics color adjustment for printing color on black and white printers (check the printer properties under Start > Settings > Printer). For more information, see the online help for the Acrobat Reader.

� the amount of available memory in your printer. (Insufficient memory can cause a document or graphics to fail to print.)

For additional information on printing problems, refer to the documentation for your printer or contact your printer manufacturer.

Preface 17


Contacting AdobeIf additional information is needed about Adobe Acrobat Reader or printing problems, see the Readme.pdf file that ships with Adobe Acrobat Reader or contact Adobe at www.adobe.com.

Adding annotations to PDF filesIf you have purchased the Adobe Acrobat application, you can add annotations to Candle documentation in .PDF format. See the Adobe product for instructions on using the Acrobat annotations tool and its features.

http://www.adobe.com

Documentation Conventions



IntroductionCandle documentation adheres to accepted typographical conventions for command syntax. Conventions specific to Candle documentation are discussed in the following sections.

Panels and figuresThe panels and figures in this document are representations. Actual product panels may differ.

Required blanksThe slashed-b (!) character in examples represents a required blank. The following example illustrates the location of two required blanks.

!!!!eBA*ServiceMonitor!!!!0990221161551000

Revision barsRevision bars (|) may appear in the left margin to identify new or updated material.

Variables and literals in command syntax examplesIn examples of command syntax for the OS/390, VM, OS/400, and NonStop Kernel platforms, uppercase letters indicate actual values (literals) that the user should type; lowercase letters indicate variables that represent data supplied by the user:

LOGON APPLID (cccccccc)

However, for the Windows and UNIX platforms, variables are shown in italics:

-candle.kzy.instrument.control.file=instrumentation_control_file_name-candle.kzy.agent.parms=agent_control_file_name

Note: In ordinary text, variable names appear in italics, regardless of platform.

Preface 19


SymbolsThe following symbols may appear in command syntax:

Table 1. Symbols in Command Syntax

Symbol Usage

| The “or” symbol is used to denote a choice. Either the argument on the left or the argument on the right may be used. Example:

YES | NOIn this example, YES or NO may be specified.

[ ] Denotes optional arguments. Those arguments not enclosed in square brackets are required. Example:

APPLDEST DEST [ALTDEST]In this example, DEST is a required argument and ALTDEST is optional.

{ } Some documents use braces to denote required arguments, or to group arguments for clarity. Example:

COMPARE {workload} -REPORT={SUMMARY | HISTOGRAM}

The workload variable is required. The REPORT keyword must be specified with a value of SUMMARY or HISTOGRAM.

_ Default values are underscored. Example:

COPY infile outfile - [COMPRESS={YES | NO}]In this example, the COMPRESS keyword is optional. If specified, the only valid values are YES or NO. If omitted, the default is YES.

Candle Customer Service and Satisfaction


Candle Customer Service and Satisfaction

BackgroundTo assist you in making effective use of our products, Candle offers a variety of easy-to-use online support resources. The Candle Web site provides direct links to a variety of support tools that include these services:

eSupport allows you to create and update service requests opened with Customer Service and Satisfaction (CSS).

eDelivery allows you to download products, documentation, and maintenance 24 hours a day, 7 days a week.

eNotification notifies you of product updates and new releases.

In addition, you can find information about training, maintenance plans, consulting and services, and other useful support resources. Refer to the Candle Web site at www.candle.com for detailed customer service information.

Candle Customer Service and Satisfaction contactsYou will find the most current information about how to contact Candle CSS by telephone or email on the Candle Web site. Go to the www.candle.com support section, and choose the link to Support Contacts to locate your regional support center.

http://www.candle.com

http://www.candle.com

What’s New in This Release 21

What’s New in This Release

Major enhancements and changes affecting installation of the OMEGAMON XE product family are summarized below.

Product versionsThe information in this installation guide applies to the products and versions shown below, some of which involve enhancements from the previous release.

Table 2. Products and Versions for Current Release

Product Version

Alert Adapter™ for OMEGACENTER Gateway™ for MVS 150

Alert Adapter for Peregrine ServiceCenter 202

Alert Adapter for Remedy ARS 202

Alert Adapter for TME 10 NetView for AIX 200

Alert Adapter for AF/Remote® 121

CandleNet Portal 195

CMS 350

CMW 350

Command & Control™ 110

Log Alert Agent 200

OMEGAMON Alert Manager for HP OpenView IT/Operations 201

OMEGAMON Alert Manager for HP OpenView NNM 201

OMEGAMON Alert Manager for Tivoli/Enterprise Console 250

W


OMEGAMON DE 195

OMEGAMON Monitoring Agent® for eBA Solutions 251

OMEGAMON XE for BEA WebLogic Server 100

OMEGAMON XE for CASP 320

OMEGAMON XE for CICS 100

OMEGAMON XE for CICSplex 220

OMEGAMON XE for DB2 on zOS 300

OMEGAMON XE for DB2 Universal Database (DB2 UDB) 102

OMEGAMON XE for DB2 Universal Database (DB2 UDB) 400

OMEGAMON XE for DB2plex 220

OMEGAMON XE for IBM Cryptographic Coprocessors 100

OMEGAMON XE for IMS 100

OMEGAMON XE for IMSplex 220

OMEGAMON XE for Linux 120

OMEGAMON XE for Microsoft SQL Server 301

OMEGAMON XE for Mainframe Networks 100

OMEGAMON XE for NetWare 301

OMEGAMON XE for Oracle 301

OMEGAMON XE for OS/390 140

OMEGAMON XE for OS/390 UNIX System Services 220

OMEGAMON XE for OS/400 300

OMEGAMON XE for R/3™ a 301

OMEGAMON XE for Storage 100

OMEGAMON XE for Sybase 301

OMEGAMON XE for Sysplex 220

OMEGAMON XE for Tuxedo 301

OMEGAMON XE for UNIX 201

Table 2. Products and Versions for Current Release (continued)

Product Version

What’s New in This Release 23

Renamed products or platforms� The product formerly known as Candle Command Center® for MQSeries

has been renamed to OMEGAMON XE for WebSphere MQ Monitoring.

� The product formerly known as Candle Command Center for MQSeries Configuration has been renamed to OMEGAMON XE for WebSphere MQ Configuration.

OMEGAMON XE for WebSphere Application Server 130

OMEGAMON XE for WebSphere Integration Brokers 120

OMEGAMON XE for WebSphere InterChange Server 100

OMEGAMON XE for WebSphere MQ Configuration 360

OMEGAMON XE for WebSphere MQ Monitoring 360

OMEGAMON XE for Windows Active Directory Servers 400

OMEGAMON XE for Windows Servers 400

OMEGAMON XE for Windows Management Web Service 100

OMEGAMON XE Web Services 350

OMEGAVIEW II® for the Enterprise 300

Universal Agent 410

Warehouse Proxy 350

a. R/3 is a trademark of SAP AG.

CandleNet Portal (version 195)

CandleNet Portal supersedes the CMW as the primary interface into your OMEGAMON XE products. CandleNet Portal (version 195) is included in the current release. For information on installing CandleNet Portal, refer to Installing Candle Products on Windows.

CMS (version 350)

Version 350 of the CMS is included in the current release.

Table 2. Products and Versions for Current Release (continued)

Product Version


� The product formerly known as OMEGAMON XE for WebSphere MQ Integrator has been renamed to OMEGAMON XE for WebSphere Integration Brokers.

AIX versions no longer supportedAIX (version 4.3.3) and below is no longer supported.

WebSphere Application Server monitoring agent packagingOMEGAMON XE for WebSphere Application Server (version 120 and above) is now included on the product installation CD instead of being supplied on a separate CD.

Support for agents on LinuxThese products support Linux (Intel and z/OS) platforms:

� OMEGAMON XE for WebSphere Application Server

� OMEGAMON XE for WebSphere Integration Brokers

� OMEGAMON XE for WebSphere MQ Monitoring

� OMEGAMON XE for WebSphere MQ Configuration

This product supports Linux (Intel only) platforms.

� Universal Agent

(See “Agents” on page 47 for details.)

Oracle (verson 10g) supportOMEGAMON XE for Oracle supports Oracle (version 10g).

New command-line installation commandThere is a new command that can be used in the command-line installation process: CandleExecute. See “CandleExecute” on page 132.

Preparing for Installation 25

Preparing for Installation

Chapter contentsWhat Are OMEGAMON XE and OMEGAMON DE?. . . . . . . . . . . . . . . . . . . . . . . 26CandleNet Portal Components in This Package. . . . . . . . . . . . . . . . . . . . . . . . . . . 32Installation Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Configuring OMEGAMON XE Across a Firewall . . . . . . . . . . . . . . . . . . . . . . . . . . 39Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42To Do Before Beginning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

1

What Are OMEGAMON XE and OMEGAMON DE?



What OMEGAMON XE doesOMEGAMON XE is a suite of Candle products that monitor and manage system and network applications on a variety of platforms. These products keep track of the availability and performance of all parts of your enterprise from one or more designated workstations, and provide reports you can use to track trends and troubleshoot problems.

How you can use OMEGAMON XEYou can use OMEGAMON XE to:

� Create situations (conditions to test when monitoring).

� Establish performance thresholds, and raise alerts when thresholds are exceeded or values are matched.

� Trace the causes leading up to an alert.

� Create and send commands to systems in your managed enterprise by means of the Take Action feature.

� Create comprehensive reports about system conditions.

� Define your own queries, using the attributes from an installed agent or from an ODBC-compliant data source, to monitor conditions of particular interest.

Components of the OMEGAMON XE platformThe client, server, and agent implementation includes

� A client, CandleNet Portal, with a Java-based user interface for viewing and monitoring your enterprise. CandleNet Portal offers two modes of operation: desktop and browser.

� A CandleNet Portal Server, placed between the client and the CMS, that enables retrieval, manipulation, and analysis of data from the agents. The CandleNet Portal Server is the central repository for all user data.



� A CMS, which acts as a collection and control point for alerts received from the agents, and collects their performance and availability data. It also serves as a repository for historical data. The CMS runs on OS/390, z/OS, UNIX, Windows XP Professional Edition, Windows 2000, or Windows 2003 Server.

� Agents installed on the systems or subsystems you want to monitor. These agents collect and distribute data to a CMS.

� (if necessary) A CMW, required primarily for the maintenance task of removing obsolete managed systems from the user interface. Although the CandleNet Portal client replaces the CMW as the user interface for your Candle monitored environment, the CMW still offers some features not otherwise available, such as the Universal Message Console and the Policy Microscope.

Figure 1. OMEGAMON XE Platform Components

Managed SystemsCMS

CMW

CandleNet Portal

desktop mode

browser modeBrowser ClientCandle Web server

CandleNetPortaldatabase

CandleNet Portal Server



What OMEGAMON DE doesOMEGAMON DE offers a dashboard view of your enterprise. It gives you a single point of control for managing the resources your business-critical applications rely on, including a range of operating systems, servers, databases, mainframes, and Web components. For example, a typical IT network might have a Web server running on Windows, an application server running on UNIX, a database on OS/390, and a transaction processor on CICS on the mainframe. OMEGAMON DE brings all these views together in a single window, so you can see when any component is not working as expected.

What CandleNet Portal doesRunning on Windows XP Professional Edition, Windows 2000, or Windows 2003 Server, CandleNet Portal is the interface into your OMEGAMON XE products. In the same way you use your browser home page as a starting point for navigating the Internet, you use CandleNet Portal to get a high-level overview of your network environment. One section of the window displays the Navigator, a tree-like view of your monitored network, with alert icons that appear when problems arise. The rest of the window is filled with views pertinent to the chosen item in the Navigator tree. From the top level or from your home workspace, you can navigate to specific locations to check activity and investigate problems.

Also see “CandleNet Portal Components in This Package” on page 32.

Two modes of operation� Desktop mode, whereby the CandleNet Portal client is installed on your

workstation and runs as a desktop application.

� Browser mode, whereby you can start CandleNet Portal from your browser, at which time the thin client software is downloaded to your system and thereafter only for software updates.

When using CandleNet Portal in browser mode, you can start it from any workstation by entering the web server URL.

What the agents doThe agents are the data collectors. The agents monitor systems, subsystems, or applications, collect data, and pass the data to CandleNet Portal or the



CMW through the CMS. The agents pass commands from the user to the system, subsystem, or application. An agent interacts with a single system or application and, in most cases, resides on the same machine where the system or application is running.

Types of agents include:

� Monitoring agents

These agents collect performance and analysis data for many systems (such as UNIX), subsystems (such as WebSphere MQ), and applications (such as R/3).

� Alert Managers

These agents monitor non-Candle monitoring products for a remote system, subsystem, or application, and relay alert information to the CMS.

Sources of alerts include console and message logs, network-management products, and system-management products. An Alert Adapter also may have an Alert Emitter™ feature that can export Candle alerts to a non-Candle monitoring product.

� Alert Emitters

These agents monitor events (that is, exceptions) from any product running under control of the CMS and, if applicable, relay them to the monitored system, subsystem, or application for corrective action.

� Gateways

These agents communicate events to a management application running on a supported platform using a network service. Examples include the SNMP Gateways, which communicate events to an SNMP management application running on AIX or Windows.

Agents run on OS/390, z/OS, UNIX, Windows XP Professional Edition, Windows 2000, Windows 2003 Server, HP NonStop Kernel, and OS/400; however, not all agents are supported on all platforms.

CMSThe CMS can run as a stand-alone server, or as a remote server in a hierarchy of servers that report to a master server called the hub CMS. A CMS can be installed on UNIX, OS/390, z/OS, Windows XP Professional Edition, Windows 2000, or Windows 2003 Server.



Hub CMS

The hub CMS serves as the focal point for managing your environment. The hub CMS may receive data from:

� Agents running on the same or remote systems.

� Other CMSs running as remote servers in a hierarchical configuration.

Depending on the complexity of your environment, the number of agents you install, and the amount of data you choose to collect, a single CMS may be all that you need. Or, you may want to configure a hierarchical set of CMSs where remote CMSs report to a hub CMS to distribute the activity.

Remote CMSs

If large amounts of network data are to be collected, excessive traffic can be minimized with the installation of remote CMSs which collect data from the agent and forward it to the hub CMS. Each remote CMS must reside on its own machine and have a unique CMS name (node), but the architectures of various remote CMSs may differ from each other as well as from the hub.

Naming your CMS

You must decide how the CMSs are to be named. In general, the names selected should be short, but meaningful within your environment. For the best performance, Candle recommends that you use the following guidelines:

� Each name must be unique. One name cannot match another CMS name for its entire length. (For example, “candle” and “candleremote” are unique and permitted; “server1” and “server1” are not unique and not permitted).

� Each name must begin with an alpha character. No blanks or special characters (“$#@”) can be used. An underline (“ _ “) is permitted and conforms to ISO 9660 standards.

� Each name must be between 2 and 32 characters in length.

� CMS naming is case-sensitive on all platforms.



Figure 2. Configuration Including a Remote CMS

CandleNet Portal Server or CMW

CandleNet Portal Components in This Package


CandleNet Portal Components in This Package

CandleNet PortalCandleNet Portal includes its own server and two types of client interface components. Here is a brief description of the components you can install at your site.

CandleNet Portal Server

The CandleNet Portal Server communicates directly with your hub CMS. Install at least one CandleNet Portal Server in your network to deploy CandleNet Portal.

CandleNet Portal Browser Client interface (automatically installed with CandleNet Portal)

In your Internet browser, to start CandleNet Portal browser mode, you can enter the URL for a specific CandleNet Portal browser client installed on your Web server.

CandleNet Portal Desktop Client interface

The installation choice labeled “CandleNet Portal Client (Desktop Edition)” installs a Java-based graphical user interface on a Windows workstation. Once the Desktop Client is installed and configured, you can use it to start CandleNet Portal in desktop mode.

Candle products compatible with this releaseFor a list of the Candle products that are compatible with CandleNet Portal (version 195), see the What’s New in This Release chapter of this manual.


Installation Planning


Upgrading and migrating from a previous installationSee “Preparing for Upgrading and Migrating from a Previous Installation” on page 65. That chapter includes information you need to know and tasks you need to do to prepare for upgrading and migrating your previously installed OMEGAMON XE or CandleNet Command Center® (CCC™) to the new OMEGAMON XE (version CT350).

Key issuesTo successfully install and operate OMEGAMON XE, you will need to determine:

� What systems do you want to monitor? This tells you which agents you need to install.

� Where do those monitored systems reside? This is where you will install the agents.

� Will you install into an NFS? If so, you will need to consider the possible impact on performance and how you will compensate.

� Where do you want to collect data? This is where you will install the CMS.

� How much data will you collect? Depending on the amount of data and the network traffic it creates, you may want to consider installing multiple CMSs. You can only install one CMS per host system.

� Will the CMS be on UNIX or another supported platform?

� If you install multiple CMSs, will each act as a stand-alone (hub) or will you configure remote CMSs to report to a hub?

� Where do you want to run the user interface to look at data and interact with the system? How many users need to use the interface? Do you want users to use the Browser Client or the Desktop Client? The user interface components run on Windows platforms.

� What communications protocols are available? You may use TCP/IP, IP:PIPE, or SNA for communication between OMEGAMON XE components.



� Does your site have a requirement for 24 x 7 operation? If so, you’ll need to consider the Hot Standby feature.

Use the information that follows to answer these questions and plan your installation. See “Prerequisites” on page 42 for a list of hardware and software requirements for components of OMEGAMON XE that reside on UNIX. You can use this information to confirm that your environment includes the hardware, software, and disk space you will need to install your OMEGAMON XE.

Specific information to have readyDuring installation, you must supply the following information:

� Name of the CMS you are installing or that the agent will connect to

� Host name of the system where the product (a CMS or one instance of an agent) will execute. Refer to the note below.

� Whether the CMS is configured as a hub or remote CMS

� Hub host

� Port number

Note: Once an agent is installed, there are various strategies for configuring where it can run and what CMS it reports to.

Function of the installation shell scriptThe shell script that you use to install OMEGAMON XE does the following:

� Creates the directory structure for $candlehome

� Installs tools for managing the installation and execution environment

� Installs and completes a basic configuration of the OMEGAMON XE products. Some components require advanced configuration.

General order of installation or upgradeNew and existing customers should install or upgrade in the following order:

1. Hub CMS2. Remote CMS3. CandleNet Portal Server



4. CandleNet Portal Desktop Client and (if necessary) CMW5. Agents

Note: Once the CMSs have been installed, the CMW and the agents can be installed in any order.

For new customers, this order provides maximum efficiency. For existing customers, this order prevents communication problems between components.

CMS installation and upgrade instructionsThis section explains where to look for installation and upgrade instructions. Unless otherwise specified, the instructions are the same whether you are installing or upgrading.

� For a CMS on UNIX, use the instructions in this guide. For a CMS on another platform, refer to the following guides, as needed:

– Installing Candle Products on Windows

– Installing Candle Products and Candle Management Server on OS/390 and z/OS

Installing into an NFS environmentCandle now fully supports installing OMEGAMON XE in NFS environments. Using NFS, you can concentrate your software and data in a specific location, minimizing maintenance, administrative overhead, and disk space.

Although using NFS to support multiple hosts simplifies the maintenance of installed Candle products, its use can impact performance. When considering NFS, weigh the administrative savings to the possible impact on the performance of your network.

Consider the number of hosts that share a single $candlehome as well as the effects of network congestion and file system performance on the overall response time of your Candle products.

NFS also has some trade-offs in how you manage your Candle environment. While you can have your entire OMEGAMON XE in one place, there may be additional configuration required in order to define the execution of specific products or processes in your $candlehome. Will every product on every host



system execute using the same configuration; or will you tailor the configuration to the particular environment?

Figure 3. Using NFS

Determining the number of agents to installIf you intend to run the same agent on several host systems, you must install and configure the agent once per host machine. This allows you to define the association between the agent, the CMS it reports to, and the host machine that the agent will run on.

Multiple logon IDsIf you plan to use multiple UNIX logon IDs to operate your OMEGAMON XE installation, you should set their umasks in such a way that each can write to files created by the other. Candle does not recommend you use multiple UNIX logons, but if you do, they should be in the same UNIX group, and their umasks should be set to 002 so they have write authority to each other's files. Consult your UNIX system documentation for “umask” and “passwd” for more details.



Multiple Network Interface Cards in CMSWhen more than one Network Interface Card (NIC) exists in the computer on which the CMS is installed, you need to identify which NIC to use when specifying the CMS Name and Hostname. Additionally, the Hostname of the system might not match the interface name, even when only one NIC exists. In either of these cases, to obtain connectivity between the CMS and agents or between the CMS and CMW you will need to specify an additional variable when configuring the CMS or Agents. This variable is listed under the Optional Primary Network Name in the configuration dialogs or during the command line installation.

Considerations for installing on AIX

Installing Agents for UNIX on AIX� Named Pipes are not supported by OMEGAMON XE on AIX operating

systems using AFS.

� Recommended display settings for Hummingbird eXceed: See Appendix D:“Display Setup for Hummingbird eXceed” on page 261.

Special instance of specifying an environment variable in a configuration file

For version CT350 on AIX, if the CMS uses the SNA communications protocol and you want to run the location brokers outside of the CMS (not a recommended configuration), the CMS_EXTERNALBROKERS='YES' environment variable must be specified in the following configuration file: $candlehome/config/Host_ms_cmsname.config.

where:

For additional information in adding or changing variables, see“Multi-platform Installation Configuration Files” on page 245.

Table 3. Variables in the Name of Aforementioned Configuration File

$candlehome The directory in which you installed the CMS.

Host Name of the computer on which the CMS was installed.

cmsname The name of the CMS



slibclean command

Occasionally, the AIX operating system does not remove “no-longer-used” modules from system memory. If this happens during an install, you could see error messages similar to the following:

ERROR - unarchive failed for prerequisite package axaix513.jar

ERROR - could not unzip the prerequisite package “axaix513.jar”

If you receive error messages like the above, change to a root user ID and run the /usr/sbin/slibclean command. This will remove any unused modules from system memory and allow you to install Candle products.


Configuring OMEGAMON XE Across a Firewall


OverviewThis section provides an overview of Candle’s implementation of firewall support. It explains basic concepts and gives sample scenarios of various configurations. This section does not include specific steps for configuring OMEGAMON XE across a firewall; those steps can be found either in the installation chapters of this guide or in the other platform-specific installation guides, depending upon which operating systems you are configuring on.

Basic implementationAt this release, OMEGAMON XE supports most common firewall configurations, including those that use address translation (application proxy firewall is a notable exception). To enable this support, Candle uses the IP.PIPE socket address family, a TCP-based protocol that opens a single port on the firewall for communication by OMEGAMON XE components. If your target OMEGAMON XE environment includes a firewall between any CandleNet Command Center® (CCC™) components, you must specify IP.PIPE as your communication protocol during configuration. No other special configuration is needed unless your firewall also uses address translation.

Implementation with address translationAddress translation is an enhanced security feature of some firewall configurations. With this feature, components that must be reached across the firewall have two unique, but corresponding addresses: the external address (valid for components outside the firewall) and the internal address (valid for components inside the firewall).

With regard to OMEGAMON XE, the component that typically must be reached for connection is the CMS; however, the Warehouse Proxy, which runs on Windows as a server-type application, must also be accessible to clients and would also require an external and internal address. A component on either side of the firewall only knows about the address that is valid for its side (its “partition”).

To accommodate sites with address translation, Candle uses a partition-naming strategy. This strategy requires two steps:



� The creation of a text file called a partition file as part of the configuration of a hub or remote CMS (or Warehouse Proxy). The partition file contains an entry that defines that component’s address in the other partition.

� The specification of a partition name (any alphanumeric string up to 32 characters), as part of the configuration of any agent, a hub or remote CMS, a CMW, or Warehouse Proxy. A partition name must be specified for each component regardless of which side of the firewall it resides in.

Sample scenariosAssuming that your site has one firewall, there would be two partitions: one outside the firewall, one inside the firewall. In the sample scenarios that follow we will specify the names OUTSIDE and INSIDE, respectively, for these partitions. (If your site’s configuration includes more than one firewall, Candle recommends that you contact Candle customer service for assistance in configuring OMEGAMON XE.)

Note: Whatever the platform, the command-line examples in the following scenarios adhere to the UNIX and Windows text formatting conventions for literals and variables.

Scenario 1: hub CMS INSIDE, agents and CMW OUTSIDE

As part of the configuration of the hub CMS, we specify the name of the partition that it resides in INSIDE. We also create a partition file parthub.txt, containing the following entry:

OUTSIDE ip.pipe:hub’s_external_address

OUTSIDE is the partition name outside the firewall and hub’s_external_address is the address of the hub CMS that is valid for the agents and the CMW.

As part of the configuration of each agent and the CMW, we specify the name of the partition that each resides in OUTSIDE.

When an agent or the CMW starts, parthub.txt is searched for an entry that matches the partition name OUTSIDE and sees the CMS address that is valid for the agents and the CMW (the external address).

Scenario 2: hub and remote CMSs INSIDE, agents OUTSIDE

Note: In Scenarios 2 and 3 we will assume that all agents report to the remote CMS.



As part of the configuration of the hub CMS, we specify the name of the partition that it resides in INSIDE. No partition file is needed because the only component that reports to it (the remote CMS) is also inside the firewall.

As part of the configuration of the remote CMS, we specify the name of the partition that it resides in INSIDE. A partition file partremote.txt must also be created at the remote CMS. It contains the following entries:

OUTSIDE ip.pipe:remote’s_external_address

When configuring the agents (all of which are outside the firewall, reporting to the remote CMS), we specify the name of the partition that they reside in OUTSIDE. When the agents start, partremote.txt is searched for an entry that matches the partition name OUTSIDE and sees the remote CMS address that is valid for them (the external address).

Scenario 3: hub CMS INSIDE, remote CMS and agents OUTSIDE

As part of the configuration of the hub CMS, we specify the name of the partition that it resides in INSIDE. We also create a partition file parthub.txt, containing the following entry:

OUTSIDE ip.pipe:hub’s_external_address

OUTSIDE is the partition name outside the firewall and hub’s_external_address is the address of the hub CMS that is valid for the remote CMS.

As part of the configuration of both the agents and the remote CMS, we specify the name of the partition they reside in OUTSIDE.

A partition file partremote.txt also must be created at the remote CMS. It contains the following entry:

INSIDE ip.pipe:remote’s_internal_address

If the hub CMS needs to communicate with the remote CMS (for example, to issue a report request from an agent that is connected to the remote CMS), partremote.txt is searched for an entry that matches the partition name INSIDE and sees the remote CMS address that is valid for it (the internal address).

Prerequisites


Prerequisites

Caution: Many of the applications require prior purchase and installation of third-party software. It is beyond the scope of this guide to instruct you in how to install or configure non-Candle software.

Platform supportThe guidelines below explain which platforms support the various Candle products and components and where to look for installation and upgrade instructions. Unless otherwise specified, the instructions are the same whether you are installing or upgrading.

� Your site may install a CMS on OS/390, z/OS, UNIX, OS/400, Windows XP Professional Edition, Windows 2000, or Windows 2003 Server.

For a CMS on UNIX, use the instructions in this guide. For a CMS on another platform, see “Documentation set information” on page 14.

� Your site may install a CandleNet Portal on Windows XP Professional Edition, Windows 2000, or Windows 2003 Server. Refer to Installing Candle Products on Windows for instructions.

� Your site may install agents on OS/390, z/OS, HP NonStop Kernel, UNIX, Windows XP Professional Edition, Windows 2000, Windows 2003 Server, or OS/400. For agents on UNIX, refer to the instructions in this guide. For agents on another platform, see “Documentation set information” on page 14.

OMEGAMON XE

General requirements� Communications (TCP/IP, SNA or IP.PIPE) between components

� Allow 5Mb of free /tmp space in addition to the other requirements listed in this appendix. Also allow additional space for log file growth.

� A Korn shell command interpreter

To determine the remainder of your needs, use the information in this chapter to determine the requirements for the specific agents and any CMS that you install on UNIX.


Prerequisites

Use of fully-qualified path names

Due to the wide variety of UNIX operating systems and possible user environments, Candle strongly urges the use of fully-qualified path names when entering a directory during the installation process (no pattern-matching characters). Candle scripts use the Korn shell and when a new process or shell is invoked, use of symbolic links, environmental variables, or aliases can potentially cause unexpected results.

CMSThis section lists the hardware and software requirements for a CMS running on AIX, HP-UX, or Solaris.

The CMS requires a minimum of 1 Gb of RAM.

Hardware

Table 4. CMS Hardware Requirements

Operating System Requirements

AIX � IBM RS/6000 Server� Ethernet or token ring LAN capability� CD-ROM drive� 49 Mb of disk space� Native X-Term monitor for UNIX or Hummingbird Exceed X-windows

emulators for PCs only

HP-UX � HP-9000� Ethernet or token ring LAN capability� CD-ROM drive� 67 Mb of disk space� Native X-Term monitor for UNIX or Hummingbird Exceed X-windows


Prerequisites


Tip: Candle recommends running your X-windows display in a 768 x 1024 super VGA mode with scroll bars and greater than 25 line screen length.

Software

Depending on your system architecture the following software requirements are required.

Note: The operating system must support Java (version 1.1.6) or higher. The Candle product CD-ROM ships with a runtime version of Java.

IP.PIPE patch for HP-UX

If you are installing a CMS on HP-UX (version 11) you will need to install the following patches for support of the IP.PIPE protocol.

For version 11.00 32-bit:

1. Apply patch PHNE_21767 cumulative ARPA Transport Patch, which supersedes PHNE_20735.

2. HP-UX (version 11.0) uses ndd as opposed to nettune.

Solaris � Sparc or UltraSparc Workstation capable of running Solaris v2.6 or 7 (32-bit or 64-bit)

� Ethernet or token ring LAN capability� CD-ROM drive� 49 Mb of disk space� Native X-Term monitor for UNIX or Hummingbird Exceed X-windows


Table 5. CMS Software Requirements

Operating System Versions Supported

AIX V5.1 or 5.2 (32-bit or 64-bit)

HP-UX V11.x, including HP11i (32-bit or 64-bit)

Solaris V2.6, 7 (32-bit or 64-bit), 8 (32-bit or 64-bit), or 9 (32-bit or 64-bit)

Table 4. CMS Hardware Requirements (continued)

Operating System Requirements


Prerequisites

Check the current value:

ndd -get /dev/tcp tcp_fin_wait_2_timeout

3. Set the FIN_WAIT2 time-out to 11 minutes:ndd -set /dev/tcp tcp_fin_wait_2_timeout 660000

4. To survive a reboot the tunable should be set in /etc/rc.config.d/nddconf using the nddconf example entries below.

TRANSPORT_NAME[0]=tcp

NDD_NAME[0]=tcp_fin_wait_2_timeout

NDD_VALUE[0]=660000

For version 11.00 64-bit:

Apply the following patches required to run the UNIX agent:

� PHSS_21906

� PHSS_21947

� PHSS_21950

� PHCO_22076

The following HP patches should be replaced:

� PHCO_14044 – replaced by PHCO_22021

� PHKL_20410 – replaced by PHKL_22208

� PHSS_20578 – replaced by PHSS_21950


� PHCO_20869 – go back to PHCO_19656

� PHKL_21349 – no replacement, see patch documentation at the ITRC for further information


� PHKL_21165 – no replacement, suggest going back to previous patch PHKL_20151

Prerequisites


File descriptor (maxfiles) limit

The CMS requires a minimum of 256 files descriptors (maxfiles) for the operating system. (See your system administrator for assistance in changing the system kernel parameters.)

Warning: For the CMS to function properly, the maximum file descriptor (MAX_FILES parameter of the configurable kernel parameter) should be greater than 256. Under POSIX shell, ulimit -a displays nofiles (descriptors) which should be unlimited or greater than 256. It is recommended that you closely monitor storage usage. (Also see “Providing sufficient storage to the CMS” on page 47.)

1. To determine the number of per process file descriptors (maxfiles), run one of the following commands:

sysdef | grep maxfiles

ulimit -a

or, for AIX systems:

ulimit -d

The maxfiles or nofiles number must be 256 or greater, such as in:

nofiles(descriptors) 256

2. For HP-UX systems, the following kernel parameters need to be adjusted to the levels indicated:

maxdsiz 0x08000000** recommendedmaxssiz 0x01000000** recommendedmaxtsiz 0x08000000** recommendedmaxfiles 256* required for CMS200 (pre-fixpack 13)max_thread_proc320* required for CMS200, 300 & CT350 * Larger if CMS is heavily used

3. For AIX systems, if the ulimit -d settings from step 1 are less than 256:1. Increase the maxfiles limit to 256.2. If this is still not sufficient (as evidenced by ie malloc failures in the CMS

log), follow the instructions in the next section, “Providing sufficient storage to the CMS” on page 47.


Prerequisites

Providing sufficient storage to the CMS

If the 256 MB referred to in the previous section (See “File descriptor (maxfiles) limit” on page 46.) does not suffice, call Candle Customer Support and ask for the Memory Upgrade patch (which will allow you to use multiple user segments of 256 MB).

Note: AIX only: AIX will by default only allow the process to use 1 segment.

The above mentioned Memory Upgrade Patch needs to be reapplied to the KDSMAIN module at every product or maintenance installation.

AgentsThis section lists the hardware and software requirements for each of the agents you can install on UNIX. Unless otherwise stated, agents require the same hardware as the operating systems under which they execute. In addition, you will need:

� Ethernet or token ring LAN capability

� CD-ROM drive

� Native X-Term monitor for UNIX or Hummingbird Exceed X-windows emulators for PCs only

� On Solaris, X11 is required

See the table below for the requirements.

Table 6. Agent Hardware and Software Requirements

Candle ProductHardware

Requirements

Software Requirements

Agent Framework (required base for all agents)

8 Mb disk space

Prerequisites


BEA WebLogic Server monitoring agent

12 Mb � AIX 5.1, 5.2� Solaris 2.8, 2.9� HP-UX 11, 11i (PA RISC)� Linux

Note: OMEGAMON XE for BEA WebLogic Server does not run on Linux, but it can be configured to monitor a server running on a Linux system.)� WebLogic Server v7 or v8 � JRE 1.3.1 (for WebLogic v7) or JRE 1.4.x (for

WebLogic v8)

Tuxedo monitoring agent

2 Mb on AIX,

3 Mb on HPUX,

3 Mb on Solaris

� HP-UX, v11.x (32-bit or 64-bit)� AIX, v5.1 or above (32-bit or 64-bit)� Solaris, v2.6, 7 (32-bit or 64-bit), or 8 (32-bit

or 64-bit)

Note: Installs locally on the Tuxedo Application Server machine or remotely on the Tuxedo Client Workstation machine.� BEA Tuxedo v6.3, 6.4, or 6.5

DB2 UDB monitoring agent (version 102)

DB2 UDB v6, 7, or 8 on AIX and Solaris

DB2 UDB monitoring agent (version 400)

DB2 UDB v8.1

Depending on your system architecture:� Solaris v2.8 (32 or 64 bit), 9 (32 or 64 bit)� AIX 5.1 or 5.2 (32 or 64 bit)

eBA® Solutions monitoring agent

15 Mb disk space

Depending on your system architecture:� AIX, v5.1 or above (32-bit or 64-bit)� HP-UX, v11.x (32-bit or 64-bit)� Solaris, v2.6 or 7 (32-bit or 64-bit)

Table 6. Agent Hardware and Software Requirements (continued)


Requirements



Prerequisites

OMEGAMON XE for Linux

128 Mb of real memory and 100 MB of disk space

Depending on your system architecture:� Linux on zSeries,

– SuSE, 2.2x kernel level (32-bit)– SuSE, 2.4x kernel level (32-bit or 64-bit)– Red Hat, 2.2x kernel level (32-bit)– Red Hat, 2.4x kernel level (32- and 64-bit)

� Linux on Intel,– SuSE, 2.4x kernel level (32-bit)– RedHat, 2.4x kernel level (32-bit)

� The FTP Daemon must be installed and running on the Linux system.

� The Linux version must support the Korn shell and Motif Window Manager (libmotif).



Requirements


Prerequisites


OMEGAMON XE for WebSphere Integration Brokers

10 Mb disk space

Depending on your system architecture:� AIX, v5.1 or above (32-bit or 64-bit)� Solaris, v7 or 8 (32-bit or 64-bit)� HP-UX, v11.x (32-bit or 64-bit). Note that

only POSIX threads are supported on HP-UX v11.

� Linux on zSeries, – SuSE Linux Enterprise Server v8, 2.4x

kernel level (31-bit)� Linux on Intel,

– RedHat Enterprise Linux AS v2.1 (formerly known as Red Hat Advanced Server v2.1), 2.4x kernel level

Note: The minimum level of maintenance required for the agent on Intel Linux is CSD05 for IBM’s WebSphere MQ v5.3 or above.� IBM’s broker product, which includes any of

the following:– WebSphere MQ Integrator v2.1– WebSphere MQ Integrator Broker v2.1– WebSphere MQ Event Broker v2.1– IBM WebSphere Business Integration

Event Broker v5– IBM WebSphere Business Integration

Message Broker v5– IBM WebSphere Business Integration

Message Broker with Rules and Formatter Extension v5

Note: The agent must be installed on the same machine on which the WebSphere message broker is installed.



Requirements



Prerequisites

OMEGAMON XE for WebSphere InterChange Server monitoring agent and data sources

2 Mb disk space

For the monitoring agent:� AIX V5.1 and above (32-bit or 64-bit) � HP-UX V11.x (32-bit or 64-bit)� Solaris V2.6 and above (32-bit or 64-bit)For the data sources:� AIX Version 5.1, maintenance level 4 or

Version 5.2, maintenance level 1� HP-UX 11.11 (11i) with the following

Goldpacks released in June 2003: GOLDBASE11i,r=B.11.11.0306.4 and GOLDAPPS11i,r=B.11.11.0306.4

� Solaris 7 or 8 with Recommended Patch Cluster as of July 23, 2003

In addition:� One of the IBM SNMP agents that come with

WebSphere Interchange Server must be installed and configured to monitor each server you want to monitor. The OMEGAMON XE for WebSphere InterChange Server monitoring agent must be configured as the SNMP manager for the agent. The SNMP Polling Interval (set in the SNMP Agent Configuration Wizard) should not exceed 5 minutes.

� Only one OMEGAMON XE for WebSphere InterChange Server monitoring agent (KICAgent) should be installed, preferably on the same host as the Candle Management Server.

� One WebSphere InterChange Server Data Source should be installed on the host of each monitored WebSphere InterChange Server.

Please refer to the OMEGAMON XE for WebSphere InterChange Server Getting Started Guide for an overview of the installation and configuration process.



Requirements


Prerequisites


OMEGAMON XE for WebSphere MQ Configuration

15 Mb disk space

Depending on your system architecture:� AIX, v5.1 or above (32-bit or 64-bit)� HP-UX, v11.x (32-bit or 64-bit). Note that


� Solaris, v2.6, 7 (32-bit or 64-bit), 8 (32-bit or 64-bit), or 9 (32-bit or 64-bit)

Note: OMEGAMON XE for WebSphere MQ Configuration does not support a CMS on Solaris.� Linux on zSeries,

– SuSE Linux Enterprise Server v8, 2.4 kernel level (32-bit)

– Red Hat for S/390, 2.4 kernel level (32-bit)

Note: Further requirements for the agent on zSeries Linux: glibc (v2.1), Red Hat Package Manager (RPM). Also see “OMEGAMON XE for WebSphere MQ for Linux for zSeries: Compiler runtime environment” on page 58.� Linux on Intel,

– SuSE, 2.4x kernel level (32-bit)– RedHat, 2.4x kernel level (32-bit)

� IBM WebSphere MQ, v5.2 or 5.3.

Note: The agent running on Linux zSeries only supports IBM WebSphere MQ v5.3.



Requirements



Prerequisites

OMEGAMON XE for WebSphere MQ Monitoring

20 Mb disk space

Depending on your system architecture:� AIX, v5.1 or above (32-bit or 64-bit)� HP-UX, v11.x (32-bit or 64-bit). Note that


� Solaris, v2.6, 7 (32-bit or 64-bit), 8 (32-bit or 64-bit), or 9 (32-bit or 64-bit)

� Linux on zSeries,– SuSE Linux Enterprise Server v8, 2.4

kernel level (32-bit)– Red Hat for S/390, 2.4 kernel level (32-bit)

Note: Further requirements for the agent on zSeries Linux: glibc (v2.1), Red Hat Package Manager (RPM). Also see “OMEGAMON XE for WebSphere MQ for Linux for zSeries: Compiler runtime environment” on page 58.� Linux on Intel,


� IBM WebSphere MQ, v5.2 or 5.3.

Note: The agent running on Linux zSeries only supports IBM WebSphere MQ v5.3.

Oracle monitoring agent

4 Mb disk space

For agent on Oracle v10g: 30Mb disk space

Depending on your system architecture:� AIX, v5.1 or above (32-bit or 64-bit)� HP-UX, v11.x (32-bit or 64-bit)� Solaris, v2.6, 7 (32-bit)� Oracle, v8.0.x (including 8.0.5), 8.1.x, 9.2, or

10g– For agent on Oracle v10g on AIX: Fixpack

ORA76001– For agent on Oracle v10g on HP-UX:

Fixpack OR3H6002– For agent on Oracle v10g on Solaris:

Fixpack OR7S6001



Requirements


Prerequisites


R/3 monitoring agent 3Mb disk space

� Install on the target R/3 Server or on a remote UNIX host with TCP/IP access to the target R/3 Server

� SAP® R/3 v3.1H through 4.6B

Note: SAP is a registered trademark of SAP AG.

Remedy ARS Alert Manager

6 Mb disk space

Depending on your system architecture:� AIX, v5.1 or above (32-bit or 64-bit).� Solaris, v2.6 or 7 (32-bit or 64-bit)� Remedy, v3.0

Sybase monitoring agent

31 Mb disk space

Note: Agents for Sybase uses the temporary database to create its own stored procedures. If your tempdb size is too small, you will receive an error message indicating that the tempdb is full.

Depending on your system architecture:� AIX, v5.1 or above (32-bit or 64-bit) including

the following shared libraries:– HP-UX, v11.x (32-bit or 64-bit)– Solaris, v2.6, 7 (32-bit)– Sybase SQL Server, v10.0 or 11.0.x– Sybase Adaptive Server v11.5– Sybase Open Client connected to Sybase.

Note: Sybase Open Client contains the routines necessary to allow C programs to connect to Sybase. It is available from the Sybase web site at http://www.sybase.com.

TME 10 Enterprise Console Alert Manager

2 Mb disk space

Depending on your system architecture:� AIX, v5.1 or above (32-bit or 64-bit)� HP-UX, v11.x (32-bit or 64-bit)� Solaris, v2.6 or 7� Tivoli Management Environment, v3.6.� Tivoli Enterprise Console, v3.6.



Requirements



Prerequisites

UNIX Logs monitoring agent

20 Mb or more disk space depending on logs being monitored

Depending on your system architecture:� AIX, v5.1 or above (32-bit or 64-bit)� HP-UX, v11.x (32-bit or 64-bit)� Solaris, v2.6, 7 (32-bit or 64-bit), 8 (32-bit or

64-bit).� A POSIX-compliant threads package must be

installed on the monitored machine.

Note: Log Alert Agent for UNIX works with syslog, errlog, and utmp logs only.

UNIX monitoring agent 30 Mb disk space

Depending on your system architecture:� AIX, v5.1 or above (32-bit or 64-bit).� HP-UX, v11.x (32-bit or 64-bit)� Solaris, v2.6, 7 (32-bit or 64-bit), 8 (32-bit or

64-bit).� A POSIX-compliant threads package must be

installed on the monitored machine.



Requirements


Prerequisites


OMEGAMON XE for WebSphere Application Server

Note: Refer to IBM's “WebSphere Application Server - System Requirements” at http://www-306.ibm.com/software/webservers/appserv/doc/latest/prereq.html to determine the hardware requirements for your particular operating system and version of WebSphere Application Server.

Operating Systems

One of these versions:� AIX, v5.1 or v5.2� HP-UX, v11.0 or v11i� Solaris, v8 or v9Linux on zSeries,� Red Hat (2.4 kernel)� SuSE (2.4 kernel)� SuSE (2.2 kernel)� United Linux 1.0Linux on Intel,� Red Hat (2.4 kernel)� SuSE (2.4 kernel)� United Linux v1.0IBM WebSphere Application Server

One of these versions:� v5.0.x or v5.1� Advanced Edition v4.0.x� Enterprise Edition v4.1� Network Deployment v5.0.x or v5.1

Note: Not all of the above operating systems are supported by all versions of WebSphere Application Server. Refer to IBM's “WebSphere Application Server - System Requirements” at http://www-306.ibm.com/software/webservers/appserv/doc/latest/prereq.html to determine which operating system environments are supported for each version of WebSphere Application Server.



Requirements



Prerequisites

Universal Agent 10 Mb disk space

� AIX, v5.1 or above (32-bit or 64-bit).� HP-UX, v11.x (32-bit or 64-bit)� Solaris v2.6 or 7 (32-bit or 64-bit).� Linux on Intel,


� Additional vendor SNMP metafiles per request from Candle representatives.



Requirements


To Do Before Beginning



OMEGAMON XE for WebSphere MQ for Linux for zSeries: Compiler runtime environment

OMEGAMON XE for WebSphere MQ Monitoring and OMEGAMON XE for WebSphere MQ Configuration for Linux for zSeries are built using the GNU C and C++ compilers, version 2.95.3. If you intend to run SSL channels then you must have installed the g++ version 2.95.3 runtime libraries, and if you intend to build C++ applications which connect to WebSphere MQ through SSL then you must have installed the g++ version 2.95.3 compiler.

The GNU g++ runtime library is called libstdc++-libc6.1-2.so.3 and is normally found in the directory /usr/lib. If this is not installed on your system, locate and install the RPM package from your distribution vendor that contains this library.

OMEGAMON XE for WebSphere Integration Brokers: Installing gnu compiler 2.95.3 on zSeries Linux

IBM’s WebSphere MQ for Linux for zSeries is built using the GNU C and C++ compilers, version 2.95.3. Therefore OMEGAMON XE for WebSphere Integration Brokers uses and requires this level of compiler, which is available from SuSe support as a Service Pack, in order to run the agent.

You need to install the ISO image for the Service Pack CD from SuSE that contains the required SuSE compiler.

� Downloading and installing from SuSE’s Web site:

1. Go to SuSE’s Linux portal: http://portal.suse.com/sdb/en/2002/02/drahn_patch_update.html.

2. Follow the directions in SuSE’s Linux portal to access their Maintenance Web to download and install the required files.

Note: Your aim will be to install the Service Pack that contains the required version of GCC (2.95.3) within the package gcc_old. The Service Pack should apply to the products that are based on SuSE Linux Enterprise Server 8.

The compiler will be installed into the directory /opt/gcc295/ in addition to the one that is already installed.



3. To use the compiler, you will have to change the PATH variable: export PATH=/opt/gcc295/bin/:$PATH

After this change, every time gcc is called without a leading path, the old one will be used.

� Installing the package manually:

1. Mount (via NFS preferably) the Service Pack CD that you obtained from SuSE.

2. Change to this directory on the CD: s390/update/SuSE-SLES/8/rpm/s390/.

3. Install the package: rpm -Uhv gcc_old-2.95.3-4.s390.rpm

SNA communication protocol note (OS/390 example)If you will be using SNA communications between Candle components, complete the installation and configuration of your CMSs on OS/390/VTAM before beginning the installation of Candle components on UNIX. During the VTAM SNA configuration using the CICAT installer, you should record the names used for the following SNA configuration settings:

� Network identified for your VTAM network = (Net Name).

� APPLIDs for each CMS installed (APPLIDs are unique for each Logical Unit (LU) = LU Name.

� LU6.2 Logmode table name = LOG Mode (Candle default is CANCTDCS).

These parameters are required during the configuration of components on UNIX. Contact the System Administrator or VTAM SysProg for this information and add it to the table below.

Table 7. SNA Communication Settings for CMSs

Parameter Hub CMS Remote CMS2 Remote CMS3 RemoteCMS4

Net Name

LU Name

LOG Mode



Creating a Candle account for installing and maintaining the $candlehome

1. (GUI installation only) Before starting the GUI installation, set up your UNIX environment for the following:� If using Exceed X-windows emulator software, see “Display Setup for

Hummingbird eXceed” on page 261.

2. (GUI installation only) Set your DISPLAY environment variable. For KSH use the following command:

export DISPLAY=[Network_Interface_Name]:0.0

where Network_Interface_Name is the name of the interface card or IP address.

3. Create a Candle account for installing and maintaining the $candlehome. For best performance, follow these guidelines:� You can use any valid name. Candle recommends the name “candle”.

Do not start the installation using the root ID, as it will cause problems with running the product after installation. However, certain Candle products may require root authority to properly configure them. In those cases, the installation or configuration command may prompt for the root password at the time it's needed.

� If you are using NFS or a local file system, you should establish your $candlehome directory according to the guidelines used in your environment.

� Candle recommends using the Korn shell for your Candle account; however, you can use any shell that is shipped with the UNIX operating system.

Note: Candle products do not support third-party vendor shells such as BASH and TCSH.

� If you are installing OMEGAMON XE for WebSphere MQ Monitoring or OMEGAMON XE for WebSphere MQ Configuration, this account must have “mqm” as the primary group.

Transferring files to your UNIX system via FTPIf your UNIX system does not have a CD-ROM drive from which it can directly access the files from the Candle product CD, or if your UNIX system cannot



access the NFS to which the Candle product CD’s contents were copied, you must transfer files from a machine with a CD-ROM drive to your UNIX system.

In this case, the UNIX system is relatively isolated (from a file access standpoint) and the Candle product CD files must be manually copied (via FTP) to the system through this process:

1. Log on to the machine on which you have loaded the Candle product CD (Windows or UNIX)

2. Go to the root directory of the cdrom_driveE:cd\

or

mount device mount_pointcd mount_point

where:

– device is the device driver for the CD-ROM.

– mount_point is the directory where the device will be mounted.

Note: The Candle product CD conforms to ISO 9660 standards. The mount command may require additional options based on the OS platform you are running. Candle does not document basic operating systems commands that are the responsibility of your system administrator to oversee. Consult the man pages or your operating system documentation if necessary.

3. FTP from that window to your UNIX machineftp [unix_machine_name]

4. Enter your user ID and password.FTP places you in your home directory on the receiving machine.

5. Create a receiving directory in your home directorymkdir candleimage

6. Change to the receiving directorycd candleimage

7. Print the full pathname of the current directorypwd



(Note the location displayed as you will need this when logging into the UNIX machine.)_________________________________________________________

8. Make a directory under the current directory called “unix”:mkdir unix

Enter the following commands to copy the files, and retain the lower case requirement:

ascii

put install.sh install.sh

put license.txt license.txt

cd unix

lcd unix

put readme.txt readme.txt

binary

put cienv.tar cienv.tar

put cienv1.tar cienv1.tar

prompt

mput ??architecture*

ls

where architecture is one of these:

� aix (for the AIX platform)

� hp (for the HP-UX platform)

� sol (for the Solaris platform)

� li6 (for the Linux on Intel platform)

� ls3 (for the Linux on zSeries platform)

9. Verify that the list of files displayed matches the list documented below. Files must be in lower case following the transfer



The file FTP types and names needed are:

where architecture is one of the platform abbreviations listed in Step 8.

quit

10. Now log on to the UNIX machine to which you copied the files.

11. Change to the directory noted in Step 7 above.

12. Enable the execution bit on the install.sh script by entering the following command:

chmod +x install.sh

13. Set the timezone environment variable ($TZ)to properly collect historical data through the agent. This variable information can be found in the timezone file which is located in /usr/share/zoneinfo. Ask the system administrator if you are not familiar with setting environment variables.

14. Run the installation as documented starting at “Running the Installation Program”, Step 2 “From the root directory of the CD-ROM, execute install.sh by entering:” on page 76.

Note: You are in the sub-directory noted in Step 7, rather than in the CD-ROM drive. Remember to supply fully-qualified path to the $candlehome directory when starting install.sh.

Table 8. FTP File Types and Names To Copy

File Type File Location/Name

ascii /cdrom_drive/install.sh

ascii /cdrom_drive/unix/license.txt

bin /cdrom_drive/unix/cienv.tar

bin /cdrom_drive/unix/cienv1.tar

bin /cdrom_drive/unix/??architecture*



Preparing for Upgrading and Migrating from a Previous Installation 65

Preparing for Upgrading andMigrating from a

Previous Installation

IntroductionThis chapter includes information you need to know and tasks you need to do to prepare for upgrading and migrating your previously installed OMEGAMON XE or CCC to the new OMEGAMON XE (version CT350).

Tip: You can determine your existing level of Candle products by referring to the readme.txt file located in the /$candlehome/docs subdirectory.

Chapter contents

Upgrade and Migration Planning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

To Do Before Beginning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

2

Upgrade and Migration Planning



OverviewThis section discusses some issues you should consider before upgrading Candle products.

Staging Your upgrade—version compatibilityExisting customers who wish to upgrade their Candle products in stages should review the following guidelines:

� After you upgrade your hub CMS to version CT350, it will continue to communicate properly with earlier versions of remote CMSs and CMWs.

� After you upgrade your hub CMS to version CT350, it will continue to communicate properly with agents built on version CT98 (version CT200) and above. It must be understood that some older products may not have the same level of Y2K compliance as the latest versions. For information regarding the level of compliance for each Candle product, please go to the Candle Web site at www.candle.com and click the Customer Support link.

� After you upgrade your CMW to version CT350, you may experience loss of function with the agent versions listed above. Therefore, Candle recommends that you maintain a CMW (version CT200 or CT300) connected to the back-level versions of the agents. As you upgrade each agent, reconnect it to the CMW (version CT350).

� After you upgrade one or more agents to the versions provided with this release, they will continue to operate properly in an environment with those agents that have not yet been upgraded.

Note: Until your upgrade is complete, you may not experience the full capabilities of this release.

Product versions earlier than those listed above may not be compatible with this release. Contact your Candle customer service representative for assistance.



Migrated information when upgrading from a previous version If you have an existing version of OMEGAMON XE software (CCC (version 300 or above)), when you upgrade that version (install over it, into the same Candle subdirectory) with OMEGAMON XE (version CT350) the following information is migrated into version CT350:

� Situations

Because of changes in the CMS configuration file to support firewall and multiple protocols, it is necessary for you to configure the new CMS (version CT350) with your site’s protocols and port values.

Directory structure changesThe directory structure of OMEGAMON XE (version CT350) differs significantly from the version CT98 (version CT200) and version CT130 directory structures. The most important difference is the addition of a new layer of directories that allow multiple CMSs to be installed under a single $candlehome. Also, all scripts in the $candlehome/bin have been completely replaced.

The existing and new directory structure equivalents are given below:

� $pc = Two letter product code

� $arch = Operating system architecture

Table 9. New and Old Directory Structure Equivalents

Old Installer version CT98 (version CT200)

New Installer version CT99 (version CT300) and

version CT350

$candlehome/$arch/bin $candlehome/$arch/bin

$candlehome/$arch/cma/$pc/bin $candlehome/$arch/$pc/bin

$candlehome/$arch/cma/$pc/catrsql $candlehome/$arch/$pc/tables

$candlehome/$arch/cma/$pc/config $candlehome/$arch/$pc/config

$candlehome/$arch/cma/$pc/files $candlehome/$arch/$pc/files

$candlehome/$arch/cma/$pc/lib $candlehome/$arch/$pc/lib

$candlehome/$arch/cma/$pc/other $candlehome/$arch/$pc/other

$candlehome/$arch/cms/bin Duplicate — Removed



In the new structure, the $candlehome/lib/$arch directory has been eliminated. All libraries are now installed in $candlehome/$arch/lib. The cma and cms directories have been removed. All product specific code whether for an agent or CMS now resides under its two character product code entry. See“Candle Product Codes” on page 251.

Six new directories have been added to $candlehome. The /JRE/$arch directory contains the Java run-time environment specific to an operating system architecture. The Java code for the installer is placed under $candlehome/classes, and files needed for versioning are installed in the registry directory.

$candlehome/$arch/lib $candlehome/$arch/lib

$candlehome/bin $candlehome/bin

$candlehome/config $candlehome/config

$candlehome/lib/$arch Duplicate — Removed

$candlehome/locks Removed

$candlehome/logs $candlehome/logs

$candlehome/misc $candlehome/misc

$candlehome/pipes Removed

$candlehome/tables $candlehome/tables

$candlehome/tmp $candlehome/tmp

$candlehome/xfer $candlehome/xfer

$candlehome/HTML (New)

$candlehome/classes (New)

$candlehome/docs (New)

$candlehome/images (New)

$candlehome/JRE/$arch (New)

$candlehome/registry (New)

Table 9. New and Old Directory Structure Equivalents (continued)

Old Installer version CT98 (version CT200)

New Installer version CT99 (version CT300) and

version CT350



$candlehome directory structure: upwards compatibility

OMEGAMON XE (version CT350) includes changes to the structure of the $candlehome directories and to the products themselves.

Products built on one level of an operating system may run on newer levels of the same operating system. This is known as upwards compatibility, and it is used to reduce disk space requirements and decrease installation time.

Here are some examples:

1. If the AIX CMS package were built on AIX 5.1, but it would also run on the newer AIX 5.2. If a user selected AIX 5.1 on which to install a CMS, the CMS package would be unloaded into an aix513 directory. This directory would reflect the operating system level used to build the product. Since the CMS for AIX 5.1 is upwardly compatible with AIX 5.2, it would run on either 5.1 or 5.2 systems. A separate CMS for AIX 5.2 would not need to be installed.Because of operating system constraints, not all products are upwardly compatible. In such cases, there are separate packages for each level of the operating system.

2. If a user were to select AIX 4.3.3 on which to install the UNIX agent, it would be unloaded into an aix433 directory. For some products with an AIX 4.3.3 specific package but with prerequisite products (for example, shared libraries) built on AIX 4.3, the installed directory structure will have both aix43 and aix433 components.

Note: AIX (version 4.3.3) and below is no longer supported.

Note: The AIX operating system was used to explain Candle's directory structure However, similar directory structures also result on HP-UX and Solaris because of upwards compatibility.

Installing OMEGAMON XE (version CT350) in a new directoryYou must install OMEGAMON XE (version CT350) in a new directory, and let it migrate your CMS tables (Enterprise Information Base (EIB) data: situations, templates, and so forth that you may have customized) into the new $candlehome. During this migration, products in the old and new $candlehome can co-exist; version CT98 (version CT200) applications work correctly with the new version CT350 applications.



While this interoperability permits you to connect version CT98 (version CT200) agents to a CMS (version CT350), you cannot have two identical agents monitoring the same system and reporting to the same hub CMS. For example, if you were running the UNIX (kux) agent on version CT98 (version CT200), it would have to be stopped prior to the starting of the version CT350 agent to monitor the same machine and report to the same hub CMS, even if different remote CMSs are used.




Migrating predefined situations from previous installationsThe latest version of OMEGAMON XE includes changes to the EIB, a set of tables which define the report structure of your data.

If you have modified any of your predefined situations or created situations of your own, you will probably want to migrate them to your new OMEGAMON XE. You may also want to delete any unwanted situations at this time.

Before you begin your installation, please do the following:

1. All predefined situations get overwritten by the CMS seeding process during installation. If you have edited a predefined situation that you wish to keep, copy it with Create Another before you start the upgrade. See Administering OMEGAMON Products: CandleNet Portal for instructions.

2. Delete any unwanted situations.

3. Back up your existing EIB. EIB files are located in your $candlehome/tables directory. See ““Maintaining the EIB” on page 255, for a full list of files. Following installation, you will run the CandleMigrate script to copy your existing tables to the new OMEGAMON XE install.

Note: You can only migrate to a similar operating system architecture. For example, you can migrate from HP-UX (version 10) to HP-UX (version 11) but you cannot migrate from HP-UX (version 10) to AIX (version 5.1).

New $candlehome directory requiredIf you have a version of OMEGAMON XE prior to version CT99 (version CT300), the new UNIX installer requires a new directory structure for the OMEGAMON XE. You must specify a new $candlehome directory for the version CT350 install on UNIX.

By creating a new $candlehome you are able to run parallel OMEGAMON XEs. If not, you are unable to use the new version CT350 installation until it is fully operational.



Stopping software components that are being upgradedTo upgrade a software component, that software component must be stopped before performing the installation.

Handling of existing historical dataThis information applies to these products:

� OMEGAMON XE for WebSphere Integration Brokers

� OMEGAMON XE for WebSphere MQ Configuration� OMEGAMON XE for WebSphere MQ Monitoring

� OMEGAMON XE for WebSphere Application Server

If you are upgrading from a previous version of one of these products (for example, from version 110 to version 120 of OMEGAMON XE for WebSphere Integration Brokers), you should use standard procedures to archive and clear out any existing historical data prior to doing an upgrade. (Consult the Historical Data Collection Guide for OMEGAMON XE and CandleNet Command Center for information about handling history files.) If this is not done, it is likely that any previously existing historical data will not be archived properly once the new agent is run. Also, historical reports will not show data.

If there is no concern for archiving the previous historical data, the history files can just be deleted. These files are in one or more of these locations:

1. the $candlehome/platform/pc/hist/agentid subdirectory2. if history was configured to be collected at the CMS, the

$candlehome/tables/cmsname subdirectorywhere

� $candlehome is the directory

� platform is the architecture code (See “Candle Architecture Codes” on page 257.) in which you installed the Candle products)

� pc is the product code:

– “qi” for OMEGAMON XE for WebSphere Integration Brokers

– “mc” for OMEGAMON XE for WebSphere MQ Configuration

– “mq” for OMEGAMON XE for WebSphere MQ Monitoring



– “we” for OMEGAMON XE for WebSphere Application Server

� agentid is the agent ID entered for the previous configuration

� cmsname is the name of the CMS entered for the previous configuration

These files have names of the format

� “kqit*.hdr” and “kqit*.” for OMEGAMON XE for WebSphere Integration Brokers

� “kmc*.hdr” and “kmc*.” for OMEGAMON XE for WebSphere MQ Configuration

� “kmq*.hdr” and “kmq*.” for OMEGAMON XE for WebSphere MQ Monitoring

� “kwe*.hdr” and “kwe*.” for OMEGAMON XE for WebSphere Application Server

Note: These formats for filenames

– kqit*.

– kwe*.

– kmc*.

– kmq*.

denote filenames that do not have associated extensions.



GUI Installation Steps 75

GUI Installation Steps

IntroductionThis chapter contains step-by-step instructions for installing Candle products from the Candle OMEGAMON XE CDROM on UNIX.

The instructions in this chapter use the Candle GUI installation tool. If you prefer to use the command line installation scripts, turn to “Command Line Installation Steps” on page 99.

Note: The installation procedure is based on a first-time installation of OMEGAMON XE. If this is an upgrade of your components, see “Preparing for Upgrading and Migrating from a Previous Installation” on page 65 before continuing with these steps.

Chapter contents

Running the Installation Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Manage Candle Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85Basic Configuration of Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88CMS Configuration Changes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92File Permission Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93Security Validation on UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95What to Do Next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

3

Running the Installation Program



In this step you run the installer through a shell script to install OMEGAMON XE components. The installer installs the CMS and the agents you select. The GUI installation is a dynamic install. The dialog order and dialog content is based on the products you select to install. For example, if you are not installing a CMS you will not see the dialogs associated with setting up the CMS.

Warning: DO NOT press “Ctrl-C” to stop the installation and configuration process!The installation and configuration process updates an install database while running. If values requested are not currently available, you should proceed with the process to completion by skipping the entry or entering a dummy value (and noting the location). When the values or resources needed to fill the dummy entries become available later (and before trying to execute the product), you should re-visit the configuration process and fill in the missing values. If you abort the installation and configuration process pressing “Ctrl-C”, the recommendation is to completely re-install from scratch (for example, using a new $candlehome), as the integrity of the configuration database is no longer assured.

Follow these steps:

1. Mount the Candle product CD-ROM at the location you have chosen on the host:


where:




2. From the root directory of the CD-ROM, execute install.sh by entering:./install.sh [-h $candlehome] [-d cdrom path] [-v] [-c] [-s]



where:

If the directory specified does not exist, you see the following prompt:

3. Type y

and press “Enter”.

Table 10. Parameters for install.sh Command

-h An optional parameter used to specify $candlehome. If you do not include -h, and do not have an environmental variable named $candlehome present, install.sh prompts you for the installation directory.

Also use this option to take action on a $candlehome other than the $candlehome in the current system.

$candlehome A home directory created for OMEGAMON XE.

-d An optional parameter used to specify the path to the root of the CD-ROM drive.

cdrom path The full path to the root of the CD-ROM drive or the full path to the CD-ROM image.

-c An optional parameter used to print diagnostic messages to the console.

-v An optional parameter used to display the version and release levels of the current installer.

-s (optional) Option to specify safe mode operation.

Safe mode invokes the JRE with the "-nojit" option (no just-in-time compiler). If you encounter a java failure error, try running the command as before, but also specifying the “-s” option. This appears to solve at least some random java exceptions that occur on a small number of machines.

Entering the above commands with “-?” displays the syntax for using the “-s” option.

%./install.sh -h candlehome

“candlehome” does not exist.Try to create it [y or n: “y” is default]?



The following prompt appears to choose the type of installation you want to complete.

4. Enter the number of the type of install you want to complete

5. If you chose “1” in the preceding step, click Agree in the window displaying the license agreement to accept the terms of the license agreement and proceed with the installation.

Note: If you receive error messages similar to the following:ERROR - unarchive failed for prerequisite package axaix513.jarERROR - could not unzip the prerequisite package “axaix513.jar”see “slibclean command” on page 38.

6. From the Welcome screen, click Install.

7. On the Main menu screen, select “Install”.The Install Candle Products dialog is presented.

8. Do one or more of the following:� To select all of the components, click Select All.

� To select individual components, click the box to the left of the component.

Table 11. install.sh Prompts for Install Type to Use

Number Install Type Where to go next...

1 Install products using GUI Continue to the next step in this chapter.

2 Install products using command line

See “Command Line Installation Steps” on page 99.

3 Create remote packages using GUI See “CandleRemote” on page 233.

4 Create remote packages using command line

See “CandleRemote” on page 233.

5 Exit install Return to the command line.

Select one of the following:

1) Install products using GUI.2) Install products using command line.3) Create remote packages using GUI.4) Create remote packages using command line.5) Exit install.

Please enter a valid number: 1



� To remove a component from the install list, uncheck the box to the left of the component you want to remove.

Note: In selecting the components to install, keep in mind that most agents must be installed for each operating system you wish to monitor. One exception is the monitoring agent for R/3 which does not require installation on the same server on which R/3 is running. With NFS, the monitoring agents can all be installed under a single $candlehome.For non-NFS systems, installation can be performed on each server or installed under a single $candlehome followed by the use of CandleRemote to distribute the configured agents to the remote machines. See “Command Line Installation Steps” on page 99.

9. Select the operating system on which to install the Candle components.� To add components for other operating systems, select another OS from

the drop-down list box and repeat selecting components to install for the additional OSs.

You can repeat this procedure for all the operating systems and components you want to install.

10. Click Install.

Note: If you are installing a different version of Candle products, you will receive pop-up dialogs warning you that you are about to install a different version of the software. Click OK to continue or Cancel to abort.

11. After the selected components are installed, you are presented with dialogs to complete the installation of the components selected for install.

12. If you are installing a CMS, you are presented with a dialog to configure the CMS on your system. � You can select up to three communications protocols (Priority 1, Priority

2, and Priority 3) for the CMS. The CMS will use Priority 1, if it is available. If not, it will use Priority 2. If that is not available, it will use Priority 3.

� Initially, configure only one network protocol. Others can be added after installation has completed.



Complete the CMS dialog as indicated in the table below.

Table 12. CMS Configuration Basic Settings

Field Description

CMS Type Specify the CMS as HUB or REMOTE

CMS Name Enter the unique name you want to assign to this CMS. The name must be alphanumeric (2-32 characters) and must begin with an alpha character. No blanks or special characters are allowed.

Host Name If you are configuring the hub CMS now on this machine, enter the hostname or IP address of this machine.

If you are configuring a remote CMS now, enter the hostname or IP address of the machine where the associated hub CMS resides.

If you have multiple NICs installed in your server, see “Multiple Network Interface Cards in CMS” on page 37. Specify the Optional Primary Network Name on the Advanced Settings Tab.

Network Connection Priority 1

Protocol Select the priority 1 network protocol from the list box: � TCP/IP� SNA� IP.PIPEThe ip.pipe network protocol is used for transport through a firewall. It supports address translation and allows you to edit or modify the Partition File.

TCP/IP Port Number

The TCP/IP listening port for the CMS. Candle recommends that you use port number 1918; however, if you must change it (if port 1918 is already in use at your site), enter the new port number (1025 to 65535).

You must specify the same port number for the hub CMS and all remote CMSs reporting to it.

SNA Protocol

Net Name Your site’s SNA network identifier.



13. After entering the Basic Settings for the CMS, select the Advanced Settings tab. The Advanced Settings dialog is displayed.

14. Fill in the fields as indicated in the table below:

LU Name Hub CMS:

The LU name for this CMS. This LU name corresponds to the Local LU alias in your SNA communications software. This is also referred to as the APPLID when setting up SNA on VTAM. Each APPLID must be unique.

Remote CMS:

The LU name (APPLID) for this remote CMS.

LOG Mode The name of the LU6.2 logmode table. This Log Mode table is created by CICAT for VTAM SNA communication configuration.

IP.PIPE Protocol

Use Address Translation Select the check box if you are using address translation at your site.

Port Number The listening port for the CMS. Candle recommends that you use port number 1918; however, if you must change it (if port 1918 is already in use at your site), enter the new port number (Candle recommends numbers 1025 to 65535).

Partition File (Required only by sites using address translation.) A text file containing the name of a partition and its constituent interface address. Enter the fully-qualified path and name to the file.

If a Partition file exists, enter the fully-qualified path and name. If you want to modify the file, click Modify.

If a Partition file does not exist, and you want to create one, enter a fully-qualified path and name and click Modify to create the file and enter its contents.

Partition (Required only by sites using address translation.) A specific namespace (up to 32 alphanumeric characters).

Table 12. CMS Configuration Basic Settings (continued)

Field Description



Table 13. CMS Advanced Settings Parameter Values

Field Description

Optional Primary Network Name

Network Name If you have multiple network cards in the CMS designated machine, enter the name or ip address of the primary network card to use.

Configuration Auditing Specifies whether or not configuration auditing data will be collected at this CMS. The default is yes (checked). To disable this feature, click it.

Security: Validate User Check the box to turn User Security Validation on for OMEGAMON XE on UNIX. See “Security Validation on UNIX” on page 95.

Specify Hot Standby Specifies whether or not data being collected at this CMS will switch to a hot-standby CMS if this CMS or its host goes offline. The default is no (not checked). To enable this feature, click it. You must also enter the name of the host machine where the hot-standby CMS resides (see next item).

Standby CMS Site: The name of the host machine where the hot-standby CMS resides. No default.

Protocol (hot-standby CMS)

You can select up to three communications protocols (Priority 1, Priority 2, and Priority 3) for the hot-standby CMS. The CMS will use Priority 1, if it is available. If not, it will use Priority 2. If that is not available, it will use Priority 3. The same protocols must be entered as requested for the Primary CMS, the priority order can be different.

Specify the protocol used by choosing from the dropdown listbox.� TCP/IP� SNA� IP.PIPE

TCP/IPPort Number

The TCP/IP listening port for the hot-standby CMS. This is the same port number you entered for the hub CMS

SNA Protocol



15. When you have entered all the Basic and Advanced CMS Settings for your site, click Save. The Setup program continues installing the remainder of the components.

Note: Click Reload to reload a previously saved configuration file. Click Cancel to exit the dialog

16. If you are installing agents for eBA Solutions, you are presented with a dialog for that product. Refer to “eBA Solutions” on page 157 for completing this dialog.

17. If you are installing the WebSphere Application Server monitoring agent, you are presented with a dialog for that product. Refer to “WebSphere Application Server” on page 206 for information about these parameters.

18. If you are installing any of the Distributed Database components (agent for Oracle, agent for Sybase), UNIX OS Agent (agents for UNIX), UNIX Log monitoring agent, or Universal Agent, you are presented with a separate x-term window. These agents require root authority. Enter the root password.

Net Name Your site’s SNA network identifier. Enter the same information you entered for the hub CMS.

LU Name Hot-standby CMS:

Enter the same information you entered for the hub CMS.

LOG Mode Enter the same information you entered for the hub CMS

IP.PIPE Protocol


Port Number Enter the same port number that you entered for the hub CMS

Partition File (Required only by sites using address translation.) Enter the same information you entered for the hub CMS.

Partition (Required only by sites using address translation.) Enter the same information you entered for the hub CMS.

Table 13. CMS Advanced Settings Parameter Values (continued)

Field Description



19. If you are installing PeopleSoft monitoring agent, Tuxedo monitoring agent, or the R/3 monitoring agent, you are presented with a dialog for the product. Enter

Default Domain

System Name

or

Default R/3 Configuration Name

(Depending on the agent, this dialog creates a default Domain Name, System Name, or Configuration Name for the agent.)

Each of these agents allows you to monitor multiple instances of the applications. You can configure additional instances after completing the initial installation.


Manage Candle Services


After completing the CMS and agent installations, you are presented with the Manage Candle Services window. The Manage Candle Services window allows you to configure the individual installed components. Additionally, it provides you the ability to start and stop the individual components from the correct operating system.

For example, components configured for sol2.6 must be started and stopped after logging onto that system. System messages are presented in the bottom dialog.

See “Starting and Stopping Candle Products” on page 215 for additional information.

Manage Candle Services Action menuThe Manage Candle Services Action menu provides the following options.

Table 14. Manage Candle Services Action Menu

Menu Option Description

Configure Select to complete the Configuration, Basic and Advanced, for each agent. The configuration dialog has two tabs if advanced configuration is required.

Configure Advanced Select to complete the Advanced Configuration for agents that require additional configuration steps such as the Distributed Databases.

Start Service Select to start the selected component.



Manage Candle Services Options menuThe Manage Candle Service Options menu provides the following options.

Stop Service Select to stop the selected component.

Seed Select to add Seed data to the CMS for all installed components (“Quick Seed”). (If you want to selectively seed components select “Advanced Seed” and refer to “Overview of the CMS Seeding Process” on page 139.)

Exit Select to close the Manage Candle Services x-term window.

Table 15. Manage Candle Services Options Menu


Manage Log Files Select to manage the log files created by OMEGAMON XE

Set Agent Permissions A few of the OMEGAMON XE components require root user authority. If you did not complete the Set Agent Permissions X-term window during the installation process, you can perform this action using this option.

Table 14. Manage Candle Services Action Menu (continued)




Manage Candle Services iconsThe icons to the left of the installed components visually display the status of the component.

Proceed to “Basic Configuration of Agents” on page 88.

Table 16. Manage Candle Services Icons

Icon Description

Component is configured and ready to start.

Component has not been configured. You must complete the configuration before you can start the component.

Component is running.

Start Service menu option

Stop Service menu option

Basic Configuration of Agents



The Setup program completes a default configuration for the CMS and the installed components. To change the CMS basic configuration, see “CMS Configuration Changes” on page 92.

You can change the default configuration for the agents using the procedure below.

Configuring or changing the CMS connection for agentsTo configure or change the CMS connection of the agents, use the following procedure. The CMS Connection tab is the same for all agents.

1. In the Manage Candle Services window, highlight the agent whose connection you want to configure. You can select multiple agents by holding down the Shift key or Control key and highlighting agents.

2. From the menu bar, select “Actions > Configure”.An Agent to CMS connection dialog is presented.

3. Complete the dialog as indicated in the table below.

Table 17. Agent to CMS Connection Settings

Field Description

CMS Hostname This is the hostname of the UNIX machine this CMS will run on.

Note: In the main configuration dialog, if "No CMS" is checked, the entire dialog except for "Edit host specific configuration" is disabled.

Connection protocol For Protocol 1, select the connection protocol from the list box (you can specify up to 3 connection protocols):� TCP/IP� SNA� IP.PIPE

Connect Through Firewall

If this box is selected, the "Protocol Type" is forced to "IP.PIPE" and the Protocol 2 and 3 tabs are disabled.

TCP/IPPort Number

The TCP/IP listening port for the CMS. Candle recommends that you use port number 1918; however, if you must change it (if port 1918 is already in use at your site), enter the new port number (1025 to 65535).



SNA Protocol

Net Name Your site’s SNA network identifier.

LU Name Hub CMS:

The LU name for this CMS. This LU name corresponds to the Local LU alias in your SNA communications software. This is also referred to as the APPLID when setting up SNA on VTAM. Each APPLID must be unique.

Remote CMS:

The LU name (APPLID) for this remote CMS.

LOG Mode The name of the LU6.2 logmode table. This Log Mode table is created by CICAT for VTAM SNA communication configuration.

IP.PIPE Protocol Note: If an agent will connect through a firewall, you must use the IP.PIPE protocol for communication with the CMS.


Port Number The listening port for the CMS. Candle recommends that you use port number 1918; however, if you must change it (if port 1918 is already in use at your site), enter the new port number (Candle recommends numbers 1025 to 65535).

Partition File (Required only by sites using address translation.) A text file containing the name of a partition and its constituent interface address. Enter the fully-qualified path and name of the file.

Optional Primary Network Name

Network Name If you have multiple network cards in the CMS designated machine, enter the name or ip address of the primary network card to use.

Secondary CMS (optional)

Specify Secondary CMS

Check the box to activate the Secondary CMS feature. This is not, a hot-standby CMS, but rather a second CMS to which the agent can connect.

Secondary CMS Enter the Hostname (IP address) of the Secondary CMS.

Protocol Click to select the network protocol to use for the Secondary CMS.

Table 17. Agent to CMS Connection Settings (continued)

Field Description



4. If you select Secondary CMS, enter the name of the Secondary CMS and select Protocols.

5. Complete the settings for the Secondary CMS protocols as indicated in the table below.

Edit host specific configuration

(Seldom used option for specific agent-to-CMS connectivity) Selecting this option creates a configuration file that is specific for running on the specified host. This option overrides the generic OS configuration file. (Same as using the -t option during the command line configuration—See “CandleConfig” on page 109.)

This option should only be used in those instances where an agent configuration requires different parameters for the host OS on which it will run.

Warning: If reconfiguring an agent that has been configured using this option, you must use this option again to update the existing configuration.

Table 18. Secondary CMS for Agent Connections Settings

Field Description

Protocol 1

Connect Through Firewall If this box is selected, the "Protocol Type" is forced to "IP.PIPE" and the Protocol 2 and 3 tabs are disabled.

Protocol Type Select the protocol type from the drop-down listbox. (You must select the same protocols that you specified for the Primary CMS but they can be in a different order.� TCP/IP� SNA� IP.PIPE

TCP/IPPort Number

Enter the same port number that you entered for the Primary CMS

SNA Protocol

Net Name Your site’s SNA network identifier. (Same as the information you entered for the Primary CMS.)

Table 17. Agent to CMS Connection Settings (continued)

Field Description



6. Click Save to save your configuration or Cancel to exit without saving. Click Reload to reload a previously saved configuration file.

Advanced configurationSeveral agents require advanced configuration to properly monitor the applications at your site.

To complete the Advanced configuration for OMEGAMON XE components, refer to “Additional Agent Configuration” on page 153. Keep the Manage Candle Services window open to complete the advanced configuration.

LU Name Hub CMS:

Enter the same information you entered for the Primary CMS.

Remote CMS:

Enter the same information you entered for the Primary CMS.

LOG Mode Enter the same information you entered for the Primary CMS.

IP.PIPE Protocol Note: If an agent will connect through a firewall, you must use the IP.PIPE protocol for communication with the CMS.


Port Number Enter the same port number you entered for the Primary CMS.

Partition File (Required only by sites using address translation.) A text file containing the name of a partition and its constituent interface address. Enter the fully-qualified path and name of the file.

Protocol 2 Enter the information for a second protocol connection between the CMS and agent.

Protocol 3 Enter the information for a third protocol connection between the CMS and agent.

Table 18. Secondary CMS for Agent Connections Settings (continued)

Field Description

CMS Configuration Changes


CMS Configuration Changes

To change the basic configuration of the CMS, use the following procedure.

1. In the Manage Candle Services window, highlight the CMS.

2. From the menu bar, select “Actions > Configure“.

3. A CMS configuration dialog is presented.

4. Complete or change the field entries as needed. Refer to Table 12: CMS Configuration Basic Settings on page 80 for CMS Basic Settings and Table 13: CMS Advanced Settings Parameter Values on page 82 for CMS Advanced Settings.

Note: Since support is available for multiple CMSs, in order to configure different CMSs you need to type in the CMS name of the one you want to change and then click Reload. When the CMS configuration dialog comes up a default CMS name is provided (the first CMS that was installed).

5. When finished, click Save to save the CMS configuration. Click Reload to reload a previously saved configuration file. Click Cancel to exit the dialog without saving.


File Permission Requirements


OverviewDuring the installation procedure, you are required to enter the root password to change the permission settings for certain files required for OMEGAMON XE components to function properly. If you have difficulty in connecting components, please run the procedure below to set file permissions to ensure that the permissions were set properly during the installation procedure.

Procedure to set file permissionsThe $candlehome subdirectory and all files within the directory and below it must have the general file permissions of “755”.

You can set all the file permissions easily using the Manage Candle Services window by selecting from the main menu “Options > Set Agent Permissions“ or use the procedure below from the command line:

1. Log on as “root” on the machine that physically owns the disk (required in most UNIX installations).

2. Change to the $candlehome/bin subdirectory

3. Type SetPerm [-h $candlehome] [-a] [-s]

A product selection list appears. This list is sorted and contains the run architectures within each product description. Again, you must have logged

Table 19. Parameters for the SetPerm Command

-a (optional) Use this option to set permissions for all agents without user intervention

-h (optional) Use this option when $candlehome is not defined in the current environment. Also use this option to take action on a $candlehome other than the $candlehome in the current system.

-s (optional) Use this option to set security validation on selected CMSs. Refer to “Security Validation on UNIX” on page 95

$candlehome The SetPerm command first looks at the value of $candlehome. If the value is not set, SetPerm sets $candlehome to the directory where SetPerm is located.



on with root authority to run SetPerm, or the program will exit with the error message

you must be ‘root’ to run this command

4. From the list of installed products, enter a valid number or numbers separated by commas or spaces. Here are examples for entering numbers:

1

1,2,3,4

3 4

The SetPerm script changes the file permissions for all agents that require special handling of select files. These agents include:

� Distributed Databases —Oracle (or) and Sybase (oy)

For Sybase and Oracle, see “Task 1. All—Setting UNIX permissions for kddos” on page 158.

� UNIX Agent (ux)

� UNIX Log Alert Agent (ul)

� Universal Agent (um)


Security Validation on UNIX


OverviewSome sites prefer to maintain security validation of users between the CMS and the CMW. The security validation procedure has been greatly simplified and no longer requires you to manually edit files or create links.

If you selected the “Security: Validate User” option from the GUI or command line install procedures, you must enable Security Validation between the CMS and CMW using the procedure below.

Procedure to enable Security Validation

Note: You must have already installed the CMW on Windows and set up a user ID and valid password (same as UNIX password) before completing this procedure. To install the CMW, refer to “Installing Candle Products on Windows.” Additionally, refer to “Administering OMEGAMON Products: CandleNet Portal.”

1. Shut down the CMS using the procedure in “Starting and Stopping Candle Products” on page 215.

2. Log on as “root” on the machine that physically owns the disk (required in most UNIX installations).

3. From the command line, type:cd $candlehome/bin/

./SetPerm [-h $candlehome] -s

where:

Table 20. Parameters for the SetPerm Command

-h (optional) Use this option when $candlehome is not defined in the current environment. Also use this option to take action on a $candlehome other than the $candlehome in the current system.

-s Use this option to set security validation on selected CMSs.

$candlehome The SetPerm command first looks at the value of $candlehome. If the value is not set, SetPerm sets $candlehome to the directory where SetPerm is located.



The following screen menu is displayed.

4. From the list of configured CMSs, enter a valid number or numbers separated by commas or spaces. Examples are:

1 2 or

1,2

5. If you are running on an HP workstation, you may see an additional prompt prior to the list of CMSs.

The SetPerm script changes the file permissions and creates the required links needed for security validation.

6. Make sure the user ID for the CMW is the same user ID as it is for your UNIX system.

7. Start the CMS using the procedure in “Starting and Stopping Candle Products” on page 215.

8. Start the CMW using the procedure in the Installing Candle Products on Windows manual.

9. When prompted for a user ID and password, type a valid user ID and password (the same user ID and password you use to log on to the UNIX system).

Select from the following:

1. CMS “aixcms” on host “vulcan”2. CMS “hpcms” on host “athens”3. CMS “suncms” on host “verdi”4. All of the above.5. Exit this program.

Please enter a valid number or numbers separated by commas or spaces.

Type your selection here:

Is this a trusted system [ y or n; “y” is the default ]? n

Select from the following:

1. CMS “aixcms” on host “vulcan”2. CMS “hpcms” on host “athens”3. CMS “suncms” on host “verdi”4. All of the above.5. Exit this program.

Please enter a valid number or numbers separated by commas or spaces.Type your selection here:


What to Do Next

What to Do Next

You have installed OMEGAMON XE in your UNIX environment. To ready your products for operation:

1. To install a CandleNet Portal or other product on a non-UNIX system, see the installation guide that you received for that platform.

2. For information on how to customize the UNIX Log Alert Agent for your environment, please see the OMEGAMON Monitoring Agents for UNIX User’s Guide (from the Candle documentation for superseded products).

3. To add product-provided solutions to your CMS for accessing reports and situations from the CMW, see “Overview of the CMS Seeding Process” on page 139.

4. To start and stop OMEGAMON XE components see “Starting and Stopping Candle Products” on page 215 and “Additional Agent Configuration” on page 153.

Note: If you do not see your Candle product in “Additional Agent Configuration” on page 153, there is no additional configuration required for the initial startup of the product. Also see the appropriate User’s Guide to learn how to tailor the product for your environment.

What to Do Next


Command Line Installation Steps 99

Command Line InstallationSteps

IntroductionThis chapter contains step-by-step instructions for installing Candle products from the Candle OMEGAMON XE CD-ROM on UNIX, using command line scripts. If you prefer to use the Candle GUI installation tool, turn to “GUI Installation Steps” on page 75.

Note: The installation procedure is based on a first-time installation of OMEGAMON XE. If this is an upgrade of your components, see “Preparing for Upgrading and Migrating from a Previous Installation” on page 65 before continuing with these steps.

Chapter contents

Summary of Steps for Command Line Install . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Using install.sh to Install from CD-ROM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101CandleConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109Manual Seeding Procedure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115CandleServer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118CandleAgent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120CandleAudit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122CandleDBAgent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124cinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126CandleExecute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132Verifying Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

4

Summary of Steps for Command Line Install


Summary of Steps for Command Line Install

To complete a command line installation, follow these steps:

1. Run install.sh from the CD-ROM. See “Using install.sh to Install from CD-ROM” on page 101.

2. Configure the CMS and agents using CandleConfig. See “CandleConfig” on page 109.

3. Seed the hub CMS using the manual seeding procedure described in “Manual Seeding Procedure” on page 115.

4. Seed any remote CMSs using the manual seeding procedure described in “Manual Seeding Procedure” on page 115.

5. If you are configuring Distributed Databases, follow the instructions in the advanced configuration chapters and refer to “CandleDBAgent” on page 124.

6. Check file permission settings if necessary. See “File Permission Requirements” on page 93.

Manually starting and stopping the CMS and agents� To manually start or stop the CMS, refer to “CandleServer” on page 118.

� To manually start or stop the agents, refer to “CandleAgent” on page 120.


Using install.sh to Install from CD-ROM


DescriptionUse install.sh to install Candle products from the CD-ROM. This optional command line installation procedure is available for those instances when an x-terminal is not available. The procedure assumes you are an experienced user on the UNIX operating system of choice.

Warning: DO NOT press “Ctrl-C” to stop the installation and configuration process!The installation and configuration process updates an install database while running. If values requested are not currently available, you should proceed with the process to completion by skipping the entry or entering a dummy value (and noting the location). When the values or resources needed to fill the dummy entries become available later (and before trying to execute the product), you should re-visit the configuration process and fill in the missing values.If you abort the install and configuration process pressing “Ctrl-C”, the recommendation is to completely re-install from scratch (for example, using a new $candlehome), as the integrity of the configuration database is no longer assured.

Installing productsIn this step you run the install.sh installation program through a shell script to install OMEGAMON XE components. The install program installs both the CMS and the agents.

Follow these steps:

1. Mount the Candle product CD-ROM at the location you have chosen on the host:


where:






2. From the root directory of the CD-ROM, execute install.sh by entering:./install.sh [-h $candlehome] [-d cdrom path] [-v] [-c] [-s]

where:

Table 21. Parameters for Executing install.sh

-h An optional parameter used to specify $candlehome. If you do not include -h, and do not have an environmental variable named $candlehome present, install.sh prompts you for the installation directory.



-d An optional parameter used to specify the path to the CD-ROM drive

cdrom path The full path to the root of the CD-ROM drive or the full path to the CD-ROM image.

-c An optional parameter used to print diagnostic messages to the console.

-v An optional parameter used to display the version and release levels of the current installer.


Safe mode invokes the JRE with the "-nojit" option (no just-in-time compiler). If you encounter a java failure error, try running the command as before, but also specifying the "-s" option. This appears to solve at least some random java exceptions that occur on a small number of machines.

Entering the above commands with “-?“ displays the syntax for using the “-s“ option.



If you have not created the $candlehome directory, you will get the following prompt:

3. Entery

and press “Enter”. The following prompt is presented:

4. Enter the number of the type of install you want to complete

Table 22. Numbers for Types of Installations

Number Install Type Where to go next...

1 Install products using GUI See “GUI Installation Steps” on page 75.

2 Install products using command line

Continue to the next step in this chapter.

3 Create remote packages using GUI See “CandleRemote” on page 233. (Under development)

4 Create remote packages using command line

See “CandleRemote” on page 233. (Under development)

5 View readme files Select to view the readme files on the CD-ROM.

% ./install.sh -h candlehome

“candlehome” does not exist.Try to create it [y or n: “y” is default]?

Select one of the following:

1) Install products via GUI.2) Install products via command line.3) Create remote packages via GUI.4) Create remote packages via command line.5) View readme files6) Exit install.

Please enter a valid number: 2

install.sh : processing base CI package. Do you agree to the terms of the license in the file LICENSE.TXT on the CD?Enter Yes, No, or R to read the agreement now.(choosing "No" exits the installation process) (Y/N/R): y



5. If you chose “2” in the preceding step, you are given the following prompt:Do you agree to the terms of the license in file LICENSE.TXT on the CD? Enter Yes, No, or R to read the agreement now. (choosing "No" exits the installation process) (Y/N/R):

Note: Candle has changed its License Agreement which is much longer than the previous agreement. You must read and agree to the license to continue the installation.

6. Answer Y

to agree with the terms of the license agreement and proceed with the command line installation.

7. Something similar to the following screen is presented to select the first operating system on which to install Candle product packages.

6 Exit install Return to the command line.

Table 22. Numbers for Types of Installations (continued)

Product packages are available for the following operating systems:1) AIX R5.1 (32 bit)2) AIX R5.1 (64 bit)3) AIX R5.2 (32 bit)4) AIX R5.2 (64 bit)5) HP-UX R10.206) HP-UX R117) HP-UX R11 (64 bit)8) Linux Intel R2.49) Linux S390 R2.210) Linux S390 R2.411) Solaris R2.612) Solaris R7 (32 bit)13) Solaris R7 (64 bit)14) Solaris R8 (32 bit)15) Solaris R8 (64 bit)16) Solaris R9 (32 bit)17) Solaris R9 (64 bit)

Type the number for the OS you want, or type “q” to quit selection[ number “1” or “AIX R5.1 (32 bit)” is default ]: ❚



8. Type the number for the Operating System you want, or type “q” to quit. Something similar to the following screen is presented.

If you receive error messages similar to the following:

ERROR - unarchive failed for prerequisite package axaix513.jarERROR - could not unzip the prerequisite package “axaix513.jar”

see the “slibclean command” on page 38.

9. Type y

or

n

and press “Enter” to continue. The following product selection information is presented.

10. Type the numbers for the products you want to install or type q

You selected number “1” or “AIX R5.1”

Is the operating system correct [ y or n; “y” is default ]? ❚



to quit. If you enter more than one number, separate the numbers by a comma or a space as shown in the examples below.

1,2,3,4 ...

1 2 3 4 ...

11. After listing the numbers, press “Enter”.

12. A confirmation screen is displayed. Enter y

or

n

and press “Enter”. The selected components are installed.

13. After the selected components are installed, you are prompted to enter another operating system or complete the installation.

14. Entery

or

n

and press “Enter”. (The default is “n”.)

Note: If you are using an NFS file system, you can install and configure agents for multiple operating systems during the install process. You can then use CandleRemote to transfer the configured agent to a remote system of the same OS architecture. You can also start the agent from the remote machine in this $candlehome.

15. If you are installing a CMS, you are prompted for the name of the CMS. Enter a name for the CMS and press “Enter”.

Do you want to select another operating system [ y or n: “n” is default ]? ❚



16. If you are installing PeopleSoft monitoring agent, Tuxedo monitoring agent, or R/3 monitoring agent, you are presented with a question as illustrated below:

Please enter R/3 system name:

Enter the

Default Domain

System Name

or

Configuration Name

(Depending on the agent, this question creates a default Domain Name, System Name, or Configuration Name for the agent.)

Each of these monitoring agents allow you to monitor multiple instances of the applications. You can configure additional instances after completing the initial installation. (The OMEGAMON XE for WebSphere MQ Monitoring agent monitors multiple queue managers rather than having multiple instances.)

17. After the components are installed, you are prompted to enter the root password. (This is necessary and required to complete the configuration of some components that require root authority.)

18. Do the following:1. Enter the root password. 2. If you want to exit the install program, press “Enter” twice. The following

prompt is presented when the program completes.



For additional information on file permission settings, see “File Permission Requirements” on page 93.

19. After installing the Candle components, you must configure the agent environments using the CandleConfig program. See“CandleConfig” on page 109.


CandleConfig

CandleConfig

DescriptionUse CandleConfig to configure or reconfigure the OMEGAMON XE execution environment on UNIX. Use CandleConfig to establish:

� The IP port that the hub CMS will use to listen for requests.

� Which hosts can execute a product.

� Where the hub CMS is in the network.

� Which CMS an agent connects to.

� Whether a CMS is a hub or a remote server.

Only one product may be configured at a time. If you reconfigure a CMS, you must stop and restart that CMS before the changes will take effect.

CandleConfig has been simplified with less command line options. You are prompted for input for the parameters necessary. Scripts are located in the $candlehome/bin directory where $candlehome is the directory into which you installed OMEGAMON XE.

Refer to “Candle Product Codes” on page 251 for a listing of UNIX and non-UNIX Candle product codes when necessary.

Reconfiguring agents

You can use CandleConfig to reconfigure installed agents to connect to a new or different CMS.

Syntax� To configure an agent:

./CandleConfig -A [-h $candlehome] [-s] [-a arch] [-o domain/system] [-t agent_host_name] pc

� To configure a CMS:

./CandleConfig -S [-h $candlehome] [-s] [-a arch] [-u] -t cms_name

Table 23. Options in CandleConfig Commands

-A Use this option to configure an agent. (Required)

CandleConfig


-S Use this option to configure a hub or remote CMS. (Required)

-a Optional command to specify the architecture where arch is one of the abbreviations used by Candle. For the most current listing, see “Candle Architecture Codes” on page 257.

This flag allows you to configure an agent and a CMS for an architecture other than the one that you are on. For example, if you are on AIX (version 5.1), and want to configure for an HP 10.20 machine, then this option is required. Otherwise the default is the machine you are on, which in this case is AIX (version 5.1). This allows you to install and configure on any machine.

-h Use this optional command when $candlehome is not defined in the current environment.


-o Applies to PeopleSoft (ps), Tuxedo (tx) and R/3 (sa) agents ONLY.

This option is required for the above three agents and configures the agent for a specific domain or system name.

-t For agents only (Seldom used option for specific agent-to-CMS connectivity) Selecting this option creates a configuration file that is specific for running on the specified host. This option overrides the generic OS configuration file. (Same as “Edit host specific configuration file” from the GUI install procedure—See “Agent to CMS Connection Settings” on page 88.)

This option should only be used in those instances where an agent configuration requires different parameters for the host OS on which it will run.

Note: If reconfiguring an agent that has been configured using this option, you must use this option again to update the existing configuration.

This option is no longer applicable to the PeopleSoft (ps), Tuxedo (tx) or R3 (sa) agents. (See the -o option above.)

-t For CMS only. Used to specify the name of the CMS.

-u (optional) Command to add seed data (catalog and attribute files) to a CMS for agents that were not installed or for non-UNIX based agents. This option is not required for the current install and manual seeding procedure. Only used with the -S option.

Table 23. Options in CandleConfig Commands (continued)


CandleConfig

Agent configurationWhen configuring agents, the following prompts are asked after starting CandleConfig:

CMS Host Name (Default is: <your host name>):

Will the agent connect through a firewall? [YES or NO] (Default is: NO):

Network Protocol 1 [ip, sna, or ip.pipe] (Default is: ip):

Network Protocol 2 [ip, sna, or ip.pipe] (Default is: none):


IP Port Number (Default is: 1918):

Configure connection for a secondary CMS? [YES or NO] (Default is NO):

Secondary CMS HostName (Default is $MIRROR$):


Secondary CMS protocol [ip, sna, ip.pipe] (Default is none):

Secondary CMS protocol 2 [ip, sna, ip.pipe] (Default is none):

Secondary CMS protocol 3 [ip, sna, ip.pipe] (Default is none):

Secondary CMS IP Port Number (Default is: 1918):

Secondary CMS Net Name (Default is: CANDLE):

Secondary CMS LU Name (Default is: LUNAME):

Secondary CMS Log Mode (Default is: LOGMODE):

Secondary CMS IP.PIPE Port Number (Default is: 1918)



Entering the above commands with -? displays the syntax for using the -s option.

pc Indicates the product code of the agent you are configuring. See “Candle Product Codes” on page 251.

Table 23. Options in CandleConfig Commands (continued)

CandleConfig


Enter Optional Primary Network Name or "none" (Default is: none)

Enter Optional Primary Network Name or "none" (Default is: none)

Are you installing this product into a clustered environment (Default is: NO)

Generic managed system name (Default is: goby)

Note: Secondary IP and IP.PIPE port numbers should match any that were entered for primary.

� Remember also that some prompts like “Network Protocol 2” will have the allowed or suggested values displayed on separate lines preceding the actual prompt as shown below:

Now choose the next protocol from one of these:

- ip.pipe

- sna

- none

– If “sna” is specified above for Network Protocol, three additional prompts are requested:

Net Name

LU Name

LOG Mode

– If “ip.pipe” is specified above for Network Protocol, additional prompts requested are:

IP.Pipe Port Number (Default is 1918):

Name of KDC_PARTITION (Default is:Null) (enter fully-qualified path and name):

� For agents that have advanced configuration parameters, then those are prompted as well (for example, ez, um). For more information on advanced agent parameter descriptions refer to “Additional Agent Configuration” on page 153.

Note: Secondary IP and IP.PIPE port numbers should match any that were entered for primary.

� After all questions are answered, a config file is generated for the agent in $candlehome/config directory with the format:


CandleConfig

<2 letter product code>.config

� Some agent configuration files will have the format

<2 letter product code>_<Instance>.config

– This applies to the following agents:

–Agents for Distributed Databases (Oracle and Sybase)

–Agent for PeopleSoft

–Agent for R/3

–Agent for Tuxedo

CMS configurationWhen configuring CMSs, the following prompts are asked after starting CandleConfig:

Hub or Remote [*LOCAL/*REMOTE] (Default is:*LOCAL):

CMS Host Name (Default is: <your host name>:

HUB CMS Host Name (Default is: <your host name>:

Network Protocol 1 [ip, sna, or ip.pipe] (Default is: ip):



IP Port Number (Default is: 1918):

Configuration Auditing (Default is: YES):

Hot Standby? (Default is: NO):

Standby CMS Site (Default is: $MIRROR$):

Hot Standby Protocol 1 [ip, sna, or ip.pipe) (Default is: ip):

Hot Standby Protocol 2 (Default is: none):

Hot Standby Protocol 3 ([Default is: none):

HS IP Port Number (Default is: 1918):

HS Net Name (Default is: CANDLE):

HS LU Name (Default is: LUNAME):

HS Log Mode (Default is: LOGMODE):

CandleConfig


HS IP.PIPE Port Number (Default is: 1918):

Enter Optional Primary Network Name or "none" (Default is: none):

Security: Validate User? [YES or NO] (Default is: NO):

� If “sna” is specified above, three additional prompts are requested:

Net Name

LU Name

LOG Mode

� If “ip.pipe” is specified above as a network protocol, additional prompts are requested as follows:

IP.Pipe Port Number (Default is 1918):

Name of KDC_PARTITION (Default is: null):

Name of KDC_PARTITIONFILE (Default is: null) (enter fully-qualified path and name):

� After all questions are answered, a config file is generated for this CMS in $candlehome/config directory with the format:

<hostname>_ms_<CMSName>.config

Exit statusAn exit status of 0 indicates that the command executed successfully. An exit status greater than 0 indicates that there was a failure in the process.


Manual Seeding Procedure


IntroductionTo successfully complete this process, the CMS must be in the same $candlehome structure as defined by the $candlehome environment variable or the command line “-h” option. Scripts are located in $candlehome/bin.

You seed the hub CMS first. If you have remote CMSs, you seed them after seeding the hub CMS.

Note: A hub CMS should be running before proceeding with a remote CMS seed. Remote CMSs must be seeded for support of product-provided solutions.

Task 1. Starting the CMSThis step starts the CMS using the CandleServer command so that you can add product-provided seed data to the CMS.

To start the CMS, enter

./CandleServer [-h $candlehome] start cms_name

where:

Table 24. Parameters for the Command for Starting a CMS

-h (optional) Parameter to specify $candlehome if it is not the one in which this script is located (usually not necessary). Also use this option to take action on a $candlehome other than this one.

$candlehome The home directory that you created for OMEGAMON XE.

start Specifies that you want to start the CMS. CandleServer also accepts the argument “stop”.

cms_name Specifies the CMS name of the CMS you are configuring. This argument is required.

Note: The CMS must be specified within the structure of $candlehome.



Task 2. Executing CandleSeedThis step describes how to execute the CandleSeed command in order to configure the CMS for the products you want to connect to this CMS. CandleSeed adds product specific SQL data to the CMS tables. (See also the “-u” option for CandleConfigure on page 109.)

To execute CandleSeed, enter:

./CandleSeed [-h $candlehome] [-s] -t cms_name pc pc pc pc pc ...

where:

Task 3. Stopping the CMSTo stop the CMS, enter

Table 25. Parameters for the CandleSeed Command

-h (optional) Parameter to specify $candlehome if it is not the one in which this script is located. Usually not necessary. Also use this option to take action on a $candlehome other than this one.





-t Use this required option to specify the CMS name.



pc The product code of the product that will connect to this CMS. You can specify one or more products to seed. If multiple products, you must separate the product codes with either a space or comma as illustrated above.

See “Candle Product Codes” on page 251 for a list of product codes.



./CandleServer [-h $candlehome] stop cms_name

where:

The CMS will pick up the new seed data the next time you start your CMS.

Task 4. Restarting the CMSTo restart the CMS, enter

./CandleServer [-h $candlehome] start cms_name

where:

Table 26. Parameters for the Command for Stopping a CMS


$candlehome is the home directory that you created for OMEGAMON XE.

stop specifies that you want to stop the CMS. CandleServer also accepts the argument “start”.



Table 27. Parameters for the Command for Restarting a CMS



start Specifies that you want to start the CMS. CandleServer also accepts the argument “stop”.



CandleServer


CandleServer

DescriptionUse CandleServer to start and stop CMSs that are defined in directories under the $candlehome/tables subdirectory. You must invoke CandleServer from the executing host machine.

Syntax./CandleServer [-h $candlehome] [-s] start cms_name

./CandleServer [-h $candlehome] [-l] [-s] stop cms_name

Table 28. Options for the CandleServer Command

-h Optional argument used to specify $candlehome if it is not the one in which the script is located.


-l Use this option to delete the log file associated with the server that is being stopped. The default is to save the log when the CMS is stopped.




Table 29. Arguments for the CandleServer Command

$candlehome Use with the -h option to specify the location of $candlehome if $candlehome is not defined in the current environment.

start|stop Specifies whether you want to start or stop the designated CMS.




CandleServer


The CMS stop message may actually appear before the processes have completely shutdown. It may take a minute for the processes to completely disappear based on the system load.

Note: When the CMS stops normally, the logfile for that session is saved. Use the “-l” option to delete the log files.

CandleAgent


CandleAgent

DescriptionCandleAgent is used to start and stop most agents. It must be executed on the architecture for which the agent is installed.

To start or stop agents for Distributed Databases, see “CandleDBAgent” on page 124. However, CandleAgent can start and stop agents for Distributed Databases, it just cannot select monitors for individual database servers or activate debugging options. You can start or stop one agent, all agents, or multiple agents using the syntax below.

Syntax ./CandleAgent [-h $candlehome] [-o opt,...] [-l] [-c] [-s] start | stop pc

./CandleAgent [-h $candlehome] [-o opt,...] [-l] [-c] [-s] start | stop all

./CandleAgent [-h $candlehome] [-o opt,...] [-l] [-c] [-s] start | stop pc,pc,pc,...

./CandleAgent [-h $candlehome] [-o opt,...] [-l] [-c] [-s] start | stop pc pc pc ...tr

Table 30. Options for the CandleAgent Command

-c Optional argument used to not refresh the configuration file used on agent startup. The default is to refresh the configuration file each time the agent is started.




CandleAgent


Note: The logfile for the agent session is always saved, regardless of whether the agent was stopped using CandleAgent or any other means, unless the “-l” option is specified on the CandleAgent command. Additionally, when the agent is stopped using the CandleAgent command, the logfile for that session will end with a terminating message that reads:

"** Process terminated by user **"

-o (PeopleSoft, Tuxedo, R/3, WebSphere MQ, DB2 UDB agent, and Universal Agent only)

Optional command to specify product specific options that you want to pass to the agent. (Required for the agents listed above, except the OMEGAMON XE for WebSphere MQ Monitoring agent.) If used for multiple agents, the commands are passed to all agents specified.

The opt argument is the parameter that you pass to the agent on startup. The parameters are agent dependent and you should consult the advanced agent configuration procedures in “Additional Agent Configuration” on page 153.

Note: You cannot use the all argument when using the “-o” option.

-l Use this option to delete the log file associated with the agent that is being stopped. The default is to save the log when the agent is stopped normally using CandleAgent stop.




Table 30. Options for the CandleAgent Command (continued)

CandleAudit


CandleAudit

DescriptionUse CandleAudit to manage log files from the command line.

Note: The functions of CandleAudit have been reduced from prior releases.

Depending on the number of products you install and the amount of activity on your system, managing the size and number of log files in your $candlehome can be critical. CandleAudit -l provides the means for you to remove or truncate log files according to your needs.

CandleAudit -l only takes action on those log files that are stored in the $candlehome/logs subdirectory for the $candlehome in which it is executed.

Note: Candle recommends that you run this command during off hours as, depending on your environment, it may be time and resource consuming.Candle recommends that you run CandleAudit to trim or delete files only when the agent is not running.

SyntaxTo manage log files in the logs subdirectory of a $candlehome:

./CandleAudit [-h $candlehome] [-c] -l age [LOGDAYS]

./CandleAudit [-h $candlehome] [-c] -l size [LOGSIZE]

./CandleAudit [-h $candlehome] [-c] -l both [LOGDAYS LOGSIZE]

Table 31. Options for the CandleAudit Command

-c (optional) Use this option to send the results of the command to the console (monitor).

-h (optional) Use this command to specify $candlehome if not defined in the current environment

-l Required option to run the log management function.

Table 32. Arguments for the CandleAudit Command

$candlehome Use with the -h option to specify the location of $candlehome if $candlehome is not defined in the current environment


CandleAudit


Note: The GUI version of CandleAudit is available by selecting “Options > Manage Log Files” in the Manage Candle Services window. See Figure 15, “Manage Candle Services Options Menu,” on page 86. In addition, the functions of CandleAudit are described under “Managing log files” on page 218.

age Use to remove all log files that are older than a specified number of LOGDAYS. Age is determined by the last modification date. The default age is thirty (30) days.

size Use to trim log files to LOGSIZE kilobytes. Trimming starts from the top of the file (oldest entries first). The default size is 1024 kilobytes.

both Use to first remove log files older than LOGDAYS days and then to trim the remaining log files to LOGSIZE kilobytes.

Table 32. Arguments for the CandleAudit Command (continued)

CandleDBAgent


CandleDBAgent

DescriptionCandleDBAgent is used to start and stop the following agents:

� Monitoring agent for Oracle

� Monitoring agent for Sybase

CandleDBAgent must be executed on the system for which the agent is installed. CandleDBAgent can also be used to generate a list of agents installed for the system where the command is executed.

To start or stop other agents, see “CandleAgent” on page 120.

Syntax./CandleDBAgent [-d ALL] [-h $candlehome] [-s server,...] start | stop pc,pc

Table 33. Options for the CandleDBAgent Command

-d Use this option to enable diagnostic reporting for one or all monitored database tables. Enables debug tracing for the listed items, which can be� “Table” – Turns on KBB_RAS1 tracing for table (korxxxx, kraxxxx). Table

names are case-insensitive, ksh wildcards OK (not regexp)� “debug” – Turns on collector and agent internal tracing via -dddd� “d's” – Fine tune internal tracing level: -d, -dd, -ddd, -dddd, -ddddd (debug or

ddd's also change col.out to wrap after 100000 lines, and keep col.ou[1-9])� “all” – *,debug� “ALL” – ddddd + all possible agent KBB_RAS1: (UNIT:K ALL)

Note: Any form of tracing also turns on KBB_RAS1 (UNIT:KDD ALL)



-s Use this option to start monitoring only for the specified servers.

Note: This is not the same as the Safe Mode -s command.


CandleDBAgent

Exit statusAn exit status of 0 indicates that the command executed successfully. An exit status greater than 0 indicates a failure in the process.

Table 34. Arguments for the CandleDBAgent Command

Trace Arguments Enables debug tracing for the listed items, which can be� “Table”– Turns on KBB_RAS1 tracing for table (korxxxx, kraxxxx).

Table names are case-insensitive, ksh wildcards OK (not regexp)� “debug”– Turns on collector and agent internal tracing via -dddd� “d's”– Fine tune internal tracing level: -d, -dd, -ddd, -dddd, -ddddd

(debug or ddd's also change col.out to wrap after 100000 lines, and keep col.ou[1-9])

� “all”– *,debug� “ALL”– ddddd + all possible agent KBB_RAS1: (UNIT:K ALL)

Note: Any form of tracing also turns on KBB_RAS1 (UNIT:KDD ALL)

$candlehome Use with the “-h” option to specify the location of $candlehome if $candlehome is not defined in the current environment.

server Use with the “-s” option to specify the servers that you want to monitor. The ellipsis indicates that the command string can include multiple values for this argument.

Arguments must be separated by a comma without intervening spaces.

start|stop Specifies whether you want to start or stop the designated agent.

pc Specifies the agent you want to take action on.

If you have installed agents for more than one kind of database, Oracle and Sybase for example, you can specify the product code for the database type whose agent you want action taken upon. The default is that CandleDBAgent applies to all.

To take action on a specific agent, include the product code of the agent (“pc”) in the command. Multiple arguments are allowed. Arguments must be separated by commas. See “Candle Product Codes” on page 251.

cinfo


cinfo

Descriptioncinfo is intended to be an acronym for CandleINFOrmation. The script, which resides in $candlehome/bin with all the other scripts, allows you to:

� Show the running Candle processes (such as agents or CMS).

� Show an inventory of installed Candle products.

� Show configuration settings for products.

� Show the installed CD versions in the current $candlehome.

� Show the configuration settings for products in the context of the actual variables used by the installer.

� Show the running Candle processes, after first performing an update on the tracking database, to remove stale PIDs (processes logged as "running" but not found when attempting to verify using the "ps" command).

Syntaxcinfo [-h $candlehome [-c pc] [-i] [-r] [-s pc | all] [-R]

Table 35. Options for the cinfo Command

-c <pc> Displays configuration prompts and values



-i Displays an inventory of installed products

-r Shows running processes

-s <pc> Displays configuration parameters and settings for the product specified

-R Shows running processes, after updating a tracking database

-v Shows the installed CD versions in this $candlehome


cinfo

UsageThe command can be run in several ways.

� Simply typing

cinfo

gets this menu:

� The command can also be invoked without a menu, so the four numbered options above can be invoked as:

cinfo -i

cinfo -r

cinfo -c <pc>

cinfo -v

� Typing

cinfo -?

Table 36. Arguments for the cinfo Command

$candlehome Use with the -h option to specify the location of $candlehome if $candlehome is not defined in the current environment.

pc | all Specifies the agent you want to take action on.

To get information on a specific agent, include the product code of the agent (“pc”) in the command. Only one product code can be specified at a time. See “Candle Product Codes” on page 251.

If you want all products, use all instead of the product code.

-- CINFO Menu --1) Show products installed in this CandleHome2) Show which products are currently running3) Show configuration settings4) Show installed CD release versionsX) Exit CINFO

cinfo


will display this help:

Sample output of the script options

1. Show installed products:cinfo -i

2. Show running processes:cinfo -r

3. Show configuration settings:

cinfo -?cinfo [-h candle_directory] [-c product] [-i] [-r] [-s product] [-R] [-v] -c <product> Displays configuration prompts and values -i Displays an inventory of installed products -r Shows running processes -s <product> Displays configuration parameters and settings -R Shows running processes, after updating a tracking database -v Shows the installed CD versions in this CandleHome

...Product inventoryax Candle Shared Libraries aix513 Version: 350 Rel: 240cf CMS Configurator aix513 Version: 300 Rel: 122ms Candle Management Server aix513 Version: 350 Rel: 242 hp11 Version: 350 Rel: 219sa R/3 Monitoring Agent aix513 Version: 300 Rel: 210

Host Prod PID Owner Start ID ..Statusmanta mq 104254 longl 07:48:13 larry ..runningmanta mq 44270 longl 07:48:13 moe ** process not running **manta mq 79456 longl 07:48:27 curley ..running


cinfo

cinfo -c um

4. Show installed CD versionscinfo -v

Advanced options

[ -s ] Displaying the configuration parameters and settings

This is somewhat similar to the “[-c]” option, but rather than showing the prompts for a configuration setting, it shows the variable used by the installer to store the setting.

This is considered an advanced option (not listed in the default menu) because many customers will not know about the installer variable names. This is primarily provided as a tool for the Candle SE.

Configuration Settingum aix513 "IP Port Number " = 3141um aix513 "Data Provider" = ASFSum aix513 "Network Protocol [ip, sna, or ip.pipe] " = ipum aix513 "Net Name " = CANDLEum aix513 "LU Name " = LUNAMEum aix513 "Log Mode " = LOGMODEum aix513 "CMS Host Name " = mantaum aix513 "Enter Optional Primary Network Name or "none" " = noneum aix513 "IP.PIPE Port Number " = 1918um aix513 "Secondary CMS Net Name " = CANDLEum aix513 "Secondary CMS LU Name " = LUNAMEum aix513 "Secondary CMS Log Mode " = LOGMODEum aix513 "Secondary CMS IP Port Number " = 1918um aix513 "Secondary CMS IP.PIPE Port Number " = 1918um aix513 "Network Protocol 2 " = noneum aix513 "Network Protocol 3 " = noneum aix513 "Secondary CMS Protocol 2 " = noneum aix513 "Secondary CMS Protocol 3 " = noneum aix513 "Will this agent connect to a CMS? [YES or NO] " = YESum aix513 "Will the agent connect through a firewall? [YES or NO] " = NOum aix513 "Configure connection for a secondary CMS? [YES or NO] " = NO

Installed CD release versions in this Candlehome.. 02R3M4 CD.. detected possible 99Rx version directories.. detected possible 98Rx version directories

cinfo


A sample output looks like this:

[-R] Showing running processes after updating the tracking database

All started Candle processes started and stopped by Candle commands are logged in a tracking database that does not automatically update itself if the process abnormally terminates or is stopped without using a Candle command (for example, using the UNIX "kill" command directly on the process). The “[-r]” option normally shows even these defunct processes in its report. In contrast, the “[-R]” option updates the tracking database prior to reporting the results. This results in a cleaner report, but permanently erases the history of processes normally kept in the tracking database. The output of the “[-R]” option looks the same as the “[-r]” option, but any “process not running” messages will be absent.

Use of product codes

Some options accept a product code. For example, displaying the configuration settings “[-c]” or “[-s]” normally displays the settings for all installed products on all platforms.

� You can restrict the output to only a single product by adding the product code. For example,

Platform Parameter=Settingum aix513 ARCHITECTURE = aix513um aix513 CANDLEHOME = /users/longl/inst/01r1g1um aix513 CELLNAME = CANDLEum aix513 PRODUCTCODE = umum aix513 PORTNUMBER = 3141um aix513 DATAPROVIDER = ASFSum aix513 NETWORKPROTOCOL = ipum aix513 NETNAME = CANDLEum aix513 LUNAME = LUNAMEum aix513 LOGMODE = LOGMODEum aix513 BINARCH = aix513um aix513 HOSTNAME = mantaum aix513 COMMENT = #um aix513 PRIMARYIP = noneum aix513 IPPIPEPORTNUMBER = 1918um aix513 HSNETNAME = CANDLEum aix513 HSLUNAME = LUNAMEum aix513 HSLOGMODE = LOGMODEum aix513 HSPORTNUMBER = 1918um aix513 HSIPPIPEPORTNUMBER = 1918um aix513 BK1NETWORKPROTOCOL = noneum aix513 BK2NETWORKPROTOCOL = noneum aix513 BK1HSNETWORKPROTOCOL = noneum aix513 BK2HSNETWORKPROTOCOL = noneum aix513 CMSCONNECT = YESum aix513 FIREWALL = NOum aix513 FTO = NO


cinfo

cinfo -c mq

will only display the settings for the OMEGAMON XE for WebSphere MQ Monitoring agent.

� Likewise on the menu, you could enter this:

3 mq

to do the same.

� Only one product code is allowed, if any is entered at all, but you can also use “all” to display the values for all of the installed products:

cinfo -c all

or if running from the menu mode:

3 all

Output redirection

cinfo output can be directed to a file in case you or a Candle SE needs to E-mail the information; for example, to output to a file called products.txt, enter

cinfo -i > products.txt

-- CINFO Menu -- 1) Show products installed in this CandleHome 2) Show which products are currently running 3) Show configuration settings 4) Show installed CD release versions X) Exit CINFO

CandleExecute


CandleExecute

DescriptionCandleExecute is used to run a user's script or command when its execution requires the same environment settings as for a particular Candle product. CandleExecute does this by building the necessary environment settings for the intended script or command, and then combines them into a temporary shell script before executing it.

The process is similar to how the CandleAgent command processes an agent startup, but unlike CandleAgent, CandleExecute does not spawn a subshell to execute the script before deleting the script. Instead, CandleExecute "sources" the temporary shell script (in $candlehome/config/pc.sh so that the environment settings become available to the current shell, from which the user command is then also executed as the last instruction.

CandleExecute must run on the platform architecture for which the agent is installed.

To use this command, makes sure that you are in the right directory:

cd $candlehome/bin

where $candlehome is the location where you installed your Candle software.

Syntax CandleExecute [-h $candlehome] [-s] [-k] pc [command]

Table 37. Options for the CandleExecute Command

pc the product code for the agent for which you want to perform this command. (See “Candle Product Codes” on page 251.)

command (optional) The full pathname of the script for which you want to build env settings. To set your agent’s env settings for your current console ksh shell, leave this option blank.

-k (keep option) specifies that the temporary script created to run the user command should not be deleted on completion. The name of the created script is displayed during execution.


CandleExecute


$candlehome (optional) argument used to specify $candlehome if it is not the one in which the script is located. Also use this option to take action on a $candlehome other than the $candlehome in the current system.

-s (optional) option to specify safe mode operation

Table 37. Options for the CandleExecute Command (continued)

Verifying Processes


Verifying Processes

IntroductionAs you start and stop components of the OMEGAMON XE, you may want to verify that the processes associated with that component started or stopped successfully. To do so, check for the existence of log files.

Log filesWhen a process is started, a log file is created to record the activity of the process. When the component stops, using the appropriate command, the log is saved as part of the normal shut down process.

Note: When you issue most Candle commands, you can set the “-l” option to delete the log unconditionally.

Log file naming format

In the past, log file names were based on the process ID (pid) of the process, for example, zola_ux_47598.log. Due to several technical issues, this naming convention was not working with the desired results. Therefore, a naming convention was instituted using a time stamp to uniquely identify the log file. This results in a long number at the end of the log file name which is actually an encoded time stamp.

Additionally, you will notice that there are actually two files generated for each execution of an agent, for example: “zola_ux_952453434.log” and “zola_ux_952453434.pid47598“.

The second (empty) file is generated to link the date and time stamp with the real process ID of the agent. This allows you to easily identify the true log file for a particular process by completing a simple “ls” command.

Verifying that the command executed successfullyTo verify that the process or executable associated with the component has started or stopped, look for a log file:

1. Change to the $candlehome/logs directory.

2. List the files in the directory.


Verifying Processes

3. Look for the appropriate log file. The name should mirror that of the corresponding lock file: “host_pc_timestamp.log“,where:

If there is not a log file, either:

� The process never started.

� The “-l” option was specified to delete the log file.

4. Check the contents of the log for more information.

Table 38. Parameters of Lock File Name

host the hostname of the system where the process is running.

pc the two-character product code. See “Candle Product Codes” on page 251.

timestamp a dynamically assigned time and date stamp number.

Verifying Processes


CMS Configuration 137

CMS Configuration

IntroductionThis chapter describes the procedures available to seed a CMS on UNIX. The Seed procedure should be performed on the hub and remote CMSs. This chapter also contains additional information on the Hot Standby feature.

Chapter contents

Setting Permissions for a Non-NIS Solaris CMS. . . . . . . . . . . . . . . . . . . . . . . . . . 138

Overview of the CMS Seeding Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139CMS Seeding Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140CMS Name (seeding error 171) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143Hot Standby Operation (optional). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144Firewall Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147CandleMigrate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150What to do next . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

5

Setting Permissions for a Non-NIS Solaris CMS


Setting Permissions for a Non-NIS Solaris CMS

IntroductionThese permissions must only be set on a CMS that runs on a non-NIS system. You should not have to modify permissions for CMSs on NIS AIX, HP-UX, or Solaris systems.

ProcedureSet permissions for a CMS on a non-NIS Solaris system as follows:

1. Go to the CMS bin directory where kdsvlunx is located. ($candlehome/arch/ms/bin, where arch is the operating system on which the CMS was installed (See “Candle Architecture Codes” on page 257.)

2. Change the su to “root” if you have the root password, otherwise obtain the password from an administrator:

chown root kdsvlunxchmod u+s kdsvlunx

3. Return to your regular ID once you have changed the su to “root”.


Overview of the CMS Seeding Process

Overview of the CMS Seeding Process

This section provides an overview of the CMS seeding process. After you install a CMS, you must prepare that CMS to collect data from agents and distribute it to a CandleNet Portal.

This procedure, called seeding, consists of adding product-specific seed data (parameters) to the CMS. Seed data includes SQL data for product-provided situations.

All products require that the CMS be restarted after being seeded before the product is fully functional. To minimize disruption, it is best to “seed” the CMS, then recycle (stop, then restart) the CMS before doing anything else.

Two procedures are available for seeding the CMS. These are:

� Using Manage Candle Services window (recommended)

� Using the manual seeding procedure. See “Manual Seeding Procedure” on page 115.

Note: If the seed data is for an agent that reports to a remote CMS, complete this process for both the hub and the remote CMS. A hub CMS should be running before proceeding with a remote CMS seed.

CMS Seeding Procedures



IntroductionUsing the Manage Candle Services window is the recommended procedure for seeding the CMS. Seeding the CMS adds product-provided solutions that you can view and use from the CandleNet Portal. You can perform a Quick Seed or an Advance Seed procedure. Use the procedures that follow to complete the seed procedure.

Quick Seed procedureThe Quick Seed procedure adds seed data to all the products you installed on the CMS. To start the Manage Candle Services window:

1. Change to the bin directory:cd $candlehome/bin

2. Type the following and press Enter.CandleManage [-h $candlehome] [-s]

where:

The Manage Candle Services window displays.

3. Highlight “Candle Management Server”.

Table 39. Parameters for the QuickSeed Procedure

-h (optional) An option used to specify $candlehome.

$candlehome The home directory created for OMEGAMON XE.



Entering the above commands with -”?” displays the syntax for using the “-s” option.



4. From the menu bar, select “Actions > Seed > Quick Seed”.

The seed process starts the CMS, adds the seed data for each product installed, and stops the CMS.

Advanced seeding

Usage

Under certain circumstances, you might want to seed selected OMEGAMON XE components or seed for components installed on platforms (operating systems) other than UNIX. If this is the case, use the Advanced Seed procedure.

Advanced seeding Procedure

To seed individual OMEGAMON XE components, use the procedure below.

1. On the Manage Candle Services window, highlight “Candle Management Server”.



2. Select “Actions > Seed > Advanced Seed”.

The Seed Products dialog displays.

3. Select one or more products to seed. To select more than one product, hold down the Shift or Ctrl key while highlighting the product with the mouse.

4. Click Seed to complete the seeding procedure. The seeding process starts the CMS, adds the seed data, and stops the CMS.

Note: If the CMS is already started, the seeding process will add the seed data, stop the CMS, and then restart the CMS.

Manual seeding procedureIf you plan on seeding manually, refer to “Manual Seeding Procedure” on page 115.


CMS Name (seeding error 171)

CMS Name (seeding error 171)

IntroductionThis error message generally occurs when a CMS is not up and running or perhaps the wrong "CMS Name" was keyed in—often users enter the host name instead of the CMS name.

Where to find the CMS name?On distributed systems, the hub CMS Name is assigned to CMS_NODEID.

� If the hub CMS executes on Windows, you can view this value using “Manage Candle Services > (right-click the CMS) > Browse Settings”.

� If the hub CMS executes on UNIX, this value is visible in the KBBENV file located in the $candlehome/tables/<CMS_Name> subdirectory.

� If the hub CMS executes on OS/390 or z/OS, the CMS name is specified during RTE configuration. If you view the RTE values, you will see the CMS name which by default is set to the RTENAME.

On OS/390 and z/OS, CMS_NODEID is defined in the KDSENV member of RKANPAR.

Hot Standby Operation (optional)



IntroductionThe Hot Standby feature lets you define a standby hub CMS. If the primary hub CMS should fail, the OMEGAMON XE automatically switches hub functions to the standby hub.

The standby hub must be on the same platform type (operating system) as the primary hub. OMEGAMON XE automatically reconnects all remote CMSs, agents, and CMWs to the standby hub.

Activation of this feature is only necessary in enterprises that must maintain 24 x 7 uptime.

Setting up Hot Standby operationTo successfully implement the Hot Standby feature, make sure that the following items are true.

� The Hot Standby option is configured on the primary hub CMS.

On each CMS, use the Manage Candle Services window to access the Candle Management Server Configuration dialog.

Note: The primary and standby hub CMSs must be configured to be backups for each other.

For dialog instructions see “CMS Configuration Changes” on page 92.

� Both the primary and standby hub CMSs must be running.

� Seed data (attribute and catalog files) must be at the same level at both the primary and standby hub CMSs.

� You must configure the CMS tables that will be replicated when the Hot Standby option is initiated, by selecting them in advance. None are selected by default. This control is accessed from the CMW Managed Systems container. Use the following procedure:

Procedure to configure the CMW Hot Standby option.

1. Log on to the primary CMS.



2. From the Managed Systems - Detail View, select the CMS, right-click and select the “Migrate Tables” action.The Copy tables to CMS dialog is displayed. On this dialog you can select from the list of eligible tables, the tables to be copied to the backup CMS when the Hot Standby operation is performed.

3. The Hot Standby tab of the CMW - Startup dialog must be filled in with the names of the primary and Hot Standby CMSs.If the Primary and Standby fields of this dialog are left blank, then Hot Standby Operation cannot be performed.

To have the CMW restart automatically after a takeover and connect to the secondary CMS, check the box at the bottom of the window.

Testing Hot Standby The control to manually initiate the Hot Standby feature is accessed from the CMW Managed Systems container.

1. After all Hot Standby configuration is implemented, logon to the primary CMS.

2. From the Managed Systems – Detail View, select a CMS.

3. Right-click and select the “Switch Hub” action.

How Hot Standby worksHot Standby switches remote agents, CMSs, and CMWs to the standby in the following instances:

� When there is a failure on the acting primary hub CMS

� When the switch is initiated by a user on a CMW

There is no automatic switch done when the primary comes back up. Hot Standby expects the primary hub CMS and the alternate (standby) hub CMS to be at the same capacity. Internally, Hot Standby considers them peers and doesn’t distinguish in terms of a primary and a secondary. Rather it handles them as acting-primary and acting-secondary. Both hub CMSs will alternate between being acting-primary and acting-secondary.

By default the algorithm that Hot Standby follows to determine which is the acting-primary hub CMS is to query the two CMSs to determine how long they have been up. The hub CMS that has been up the longest wins. There



could be cases where your CMW is connected to a CMS which it thinks is the primary at a given time. This can happen for example when there is a disconnect between the primary and secondary or even during startup. In such cases when the Hot Standby tasks reconnect to their peers they make an independent determination as to who should be the acting-primary and acting-secondary. The algorithm above is followed.


Firewall Support

Firewall Support

OverviewThis version of OMEGAMON XE supports firewalls using the ip.pipe communications protocol which supports address translation. Agents connecting to the CMS must use the ip.pipe communications protocol.

If your site is using address translation, it is necessary to create a Partition File which is a text file containing the name of a partition and its constituent interface address. If you are installing using the GUI interface, you can create and modify the Partition File during the CMS configuration. If you are installing from the command line, you must create or modify this file before implementing firewall support with the CMS and agents.

When OMEGAMON XE components need to communicate across a firewall that performs NAT, an OMEGAMON XE component must be able to retrieve an ip address of the other component that is valid on its side of the firewall. To support this capability, the location broker namespace is logically divided into partitions with unique partition id’s. Partition id’s are specified using the KDC_PARTITION environment variable. The partition file is the means to insert appropriate ip addresses into the location broker namespaces.

When an OMEGAMON XE component performs a location broker lookup operation, the partition id of its partition will automatically be supplied. The location broker will only return addresses that have been defined for that partition namespace and no other. In effect, the OMEGAMON XE component will only see addresses that are valid for its partition.

A partition file is a standard text file (like this one) and is defined to the system using the KDC_PARTITIONFILE environment variable. Within this file, each line describes a partition name with its constituent ip addresses using space delimited tokens. The format is as follows:

PARTITION-ID IP.PIPE:nn.nn.nn.nn IP.PIPE:nn.nn.nn.nn

The first token on each line is used as a case-insensitive partition id. The partition id can be any alphanumeric string with a maximum length of 32 characters. Subsequent tokens specified are treated as interface addresses in standard NCS format (address-family:address). For communication across firewalls, only IP.PIPE should be used for address-family.

The expected default location of the file is: /$candlehome/tables/cms_name.

Firewall Support


Sample partition fileBelow is a sample partition file illustrating the format and content expected.

# SAMPLE PARTITION FILE## IMPORTANT: Do not overwrite this file. Copy to another directory # before making changes.## Lines beginning with a ‘#’ are treated as comments and are ignored.# Note: Do not specify a line that starts with an ‘*’ as it might prevent# the proper functioning of CCC. ## Basic Format# PARTITION-ID IP.PIPE:nn.nn.nn.nn IP.PIPE:nn.nn.nn.nn

## Procedure to edit this sample partition file.# To create a CMS partition file for a typical CCC scenario (CMA/CMW outside of a

# NAT firewall connecting to a CMS behind the firewall). Do the following:# 1) Replace the “$OUTSIDE-PID$” with the partition id of your CMA/CMW# 2) Replace the “$OUTSIDE-CMS-HOST-ADDRESS$” with the ip address of the CMS host# outside of the firewall. # 3) Add additional IP.PIPE:nn.nn.nn.nn addresses on a single line for multiple# Network Interface Cards (NICs) as in the format above. # Separate entries with 2 spaces.# Lines can be continued by placing a backslash (‘\’) char at the end of the # line.###############################################################################$OUTSIDE-PID$ IP.PIPE:$OUTSIDE-CMS-HOST-ADDRESS$

Editing the partition file in Manage Candle ServicesIf you are using the Mange Candle Services interface, you can create or modify the partition file using the CMS Configuration option.

1. Highlight the CMS you want to configure.

2. Select “Action > Configure > Basic Settings“.

3. Choose “IP.PIPE” as the communications protocol.

4. Select the “Use Address Translation” checkbox.

5. Enter the full path and file name for the partition file.

6. Click Modify to create the file (if it does not exist) or modify to edit the file.

7. Enter the partition ID in the first column.


Firewall Support

8. Enter the ip address in the second column. If you require a second ip address, enter it in the third column. (If more than two ip addresses are required for a partition ID, use a text editor to add the additional addresses. See “Sample partition file” on page 148.)

9. Click Save to save the file and exit or Cancel to return to the previous screen without modification of the file.

CandleMigrate


CandleMigrate

OverviewCandleMigrate is a UNIX script you can use to migrate your EIB tables to your new OMEGAMON XE (version CT350) installation.

After completing the installation, configuration, and seeding of your CMS (version 350) you should run CandleMigrate to update the new installation with your previously modified product-provided situations and situations you created yourself. The installation can be done using the new graphical interface or from the command line. Remember that this is not an upgrade, the OLD and NEW directories need to be separate.

Migration installation sequenceMigration should be done in the following sequence:

1. Install the CMS (use the GUI installer or command line install).

2. Configure the CMS (use the GUI installer or command line install).

3. Seed the product-provided objects (use CandleSeed from the command line or the Quick Seed option in the Manage Candle Services window.

4. Issue CandleMigrate.

Note: You should open an X-term session to issue this command when using GUI installation since there is no CandleMigrate support in the GUI installation.IMPORTANT: The old CMS name and the new CMS must match exactly when migration is required. This includes case sensitivity.

Procedure for migratingUse the procedure below to migrate the table information from your prior installation.

1. From the UNIX command line, typecd /$candlehome/bin

where $candlehome is the new directory into which you installed OMEGAMON XE (version CT350).


CandleMigrate

2. TypeCandleMigrate [-h $candlehome] -o old$candlehome/tables/old_cms_name -n cms_name

where:

Note: Users migrating from a version CT98 (version CT200) CMS to version CT99 (version CT300) or version CT350 using CandleMigrate must specify the new CMS name (using the “-n” option) in upper case characters if they have a need to maintain compatibility with existing agents that reference the old CMS name.

Table 40. Parameters for Commands for Migrating Tables

-h (Optional) An option parameter used to specify $candlehome. Also use this option to take action on a $candlehome other than the $candlehome in the current system.


old$candlehome The old directory into which you installed OMEGAMON XE

-o Parameter must include the fully-qualified path to the old CMS tables and includes the old_cms-name.

-n The name of the new CMS. (See the Note below)

-z Used to migrate Admin_Pac data to version CT350. This flag is mutally exclusive with the -o flag. See the Admin Pac install guide for more information.

What to do next


What to do next

Your CMS is now fully functional. Ready the remainder of your OMEGAMON XE for operation:

� To install a CMW or other products on non-UNIX systems, see the installation guide that you received for that platform.

� If you installed an agent, there may be additional product specific configuration that you must do. See “Additional Agent Configuration” on page 153 for additional information relating to your agent.

� To start and stop OMEGAMON XE components see “Starting and Stopping Candle Products” on page 215.

Additional Agent Configuration 153

Additional Agent Configuration

IntroductionThis chapter contains additional configuration steps that are required for specific agents, adapters, and emitters.

Chapter contentsBEA WebLogic Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154DB2 UDB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156eBA Solutions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157Oracle and Sybase . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158OMEGAMON XE for WebSphere MQ Configuration . . . . . . . . . . . . . . . . . . . . . 170OMEGAMON XE for WebSphere MQ Monitoring . . . . . . . . . . . . . . . . . . . . . . . . 172OMEGAMON XE for WebSphere Integration Brokers . . . . . . . . . . . . . . . . . . . . . 175R/3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181Remedy ARS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193Tuxedo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194Universal Agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197UNIX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204UNIX Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205WebSphere Application Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206WebSphere InterChange Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

6

BEA WebLogic Server


BEA WebLogic Server

OverviewEach JMX collector needs to be configured with information about the location and configuration of the WebLogic server instance it will be monitoring. It also needs to know on what port the BEA WebLogic Server agent is listening for it.

Configuring the collector

After you have configured the agent connection to the CMS, you are prompted to configure the JMX collector. Accept the defaults or provide the appropriate values for your site, as described in the following table.

Note: Do not configure the collector while the agent is running. If the agent is running while the collector is being configured, the agent must be stopped and restarted.

Table 41. JMX Collector for BEA WebLogic Server Configuration Values

Host The name of the host on which the monitored WebLogic server instance is installed. By default, this is localhost.

Port The admin port for the WebLogic server. By default, this is 7001.

User ID The user ID used to connect to this server

Password The password associated with the user ID

Display name The name you want used as the node name or managed system name for this Weblogic server in the CandleNet Portal Navigation tree. If you do not specify a name, this parameter takes the value WebLogic_hostname-portnumber (for example, Server1-7001).

WebLogic version

Either version 7 or 8

WebLogic JAR location

The path to the directory in which the weblogic.jar file for the appropriate version resides (for example, /weblogic)


BEA WebLogic Server

Starting and stopping agent and collectorTo start the agent and collector:

./CandleAgent start wl

To stop the collector enter:

./CandleAgent stop wl

To stop the agent:

CandleAgent -o kwlagent stop wl

For more information about the CandleAgent command, refer to “CandleAgent” on page 116.

Reconfiguring agent and collectorIf you need to reconfigure the agent or the collector at some later date (for example, to connect to a different CMS or a different WebLogic server), use the CandleConfig command with wl for the product code (pc):

./CandleConfig -A wl

The CandleConfig command steps through the CMS connection parameters for the agent before prompting for the collector parameters. Refer to “CandleConfig” on page 105 for more information on the command.

JRE path The path to the appropriate JRE for the version of BEA WebLogic Server on this host (1.3.x for WebLogic 7 and 1.4.x for WebLogic 8).

For JRE v. 1.3.x, use the classic directory. For JRE v. 1.4.x, use the client directory.

Table 41. JMX Collector for BEA WebLogic Server Configuration Values

DB2 UDB


DB2 UDB

The DB2 UDB monitoring agent does not require advanced configuration. However, you must start DB2 UDB using a user ID that has DB2SysAdmin, SysCtrl, or SysMaint authority.

You can run multiple copies of the DB2 UDB agent by specifying different database instance names. Only one process can be started for each database instance.

Starting and stopping DB2 UDB agents using Candle Manage Services

When starting the DB2 UDB agent using Candle Manage Services, you are prompted for a database instance name.

When stopping the DB2 UDB agent using Candle Manage Services, you are prompted for which database instance name to stop.

Starting and stopping DB2 UDB agents using CandleAgentWhen you execute CandleAgent to start the DB2 UDB agent, you need to use the “-o” option to specify the database instance to start or stop. The database instance name must match the name used for starting the database. For example:

CandleAgent -o DB2inst1 start | stop ud

CandleAgent -o Preface_DB2inst2 start | stop ud

CandleAgent -o DB2inst3_suffix start | stop ud

If you start the agent without specifying the “-o” option, you receive an error message:

“This agent requires the -o option...”

The hostname of the system is automatically added to the instance name in the managed system list of the user interfaces.

For more information about using CandleAgent, see “CandleAgent” on page 120.


eBA Solutions

eBA Solutions

Before configuring the eBA Solutions monitoring agent, ensure that the following is complete:

� eBA Solutions Manager Server must be installed to utilize agents for eBA Solutions.

� ETEWatch® and eBA Solutions monitoring agent must involve a 1 to 1 relationship and they must reside on the same machine.

Advanced configuration procedure

1. From the Manage Candle Services window, select (highlight) “eBA Solutions Monitoring Agent”.

2. Select “Actions > Configure > Agent Parameters”.The Configure eBA Solutions Monitoring Agent parameters dialog is displayed.

3. Enter the values for your site in the appropriate fields. Use the information in the following table to complete the dialog.

4. Click OK to save your settings.

Table 42. Agent for eBA Solutions Advanced Configuration Values

Field Description

eBA Home Directory The directory in which your eBA products are installed.

JDBC Drivers Class Path The JDBC class path or the name of the JDBC driver. Refer to the JDBC driver vendor user’s guide for the path or class name.

If you are using JDBC-ODBC bridge/ODBC driver, leave this field blank.

Oracle and Sybase


Oracle and Sybase

This section describes the advanced configuration procedure for agents for Distributed Databases (Oracle and Sybase). The configuration procedure is basically the same for all database agents and specific differences are noted.

Task 1. All—Setting UNIX permissions for kddos

Note: If you completed the File Permissions Setting step during the GUI or command line installation procedure, you can skip this step as permissions were set during install.

The agents for Distributed Databases have a common executable named kddos, which requires UNIX root authority. Note that if you installed the agent for Oracle or Sybase for this UNIX architecture (AIX, HP-UX, or Solaris), and have granted root authority to kddos, you have already completed this step. If you have installed the agent for more than one UNIX architecture, you need to complete this step for each copy of kddos.

All three architectures, AIX, HP, and Solaris, now have the same requirement, that you set kddos to “root”. The UNIX group settings no longer matter. See “File Permission Requirements” on page 93 for the GUI and command line procedures.

Where to go next...� For Oracle, proceed to “Task 2. Oracle—Verifying that the Oracle V$

Dynamic views are installed correctly” on page 158.

� For Sybase, proceed to “Task 4. Sybase—Installing Sybase Open Client” on page 161.

Task 2. Oracle—Verifying that the Oracle V$ Dynamic views are installed correctly

Note: To Oracle 7.1.4 users: If you are running Oracle 7.1.4, skip this task. The agent for Oracle reads the performance tables directly and does not require the public synonyms and views.

If they do not already exist in your Oracle environment, create the public synonyms and views of the Oracle V$ Dynamic Performance Tables that the agent for Oracle requires to report performance data.


Oracle and Sybase

To determine whether the views already exists, ask your Oracle DBA to connect to Oracle as the user SYS and issue this statement:

desc v_$database

If the response is “Object does not exist”, the performance synonyms and views have not been created. In this case, your Oracle database administrator must run the catalog.sql script to create the necessary performance views and synonyms. This is a normal part of the Oracle installation, but this step may not have been completed for your database. If the catalog.sql script does not run correctly, contact Oracle support for help.

This tests the existence of only one of the various performance views and synonyms on which the product relies. However, we have seen some Oracle systems with some, but not all of these missing. The “Installation Verification” option of CandlDBConfig tests for the existence of ALL required objects.

The catalog.sql script you will need is in your $ORACLEHOME/rdbms/admin directory.

Note: To Oracle 7.1.4 users: You may be running both Oracle 7.1.4 and other releases. If so, only the 7.1.4 system is exempt.

Task 3. Oracle—Granting connect and select authority to the Oracle database

Each monitored Oracle instance must have a connect ID (oralogin) that the Oracle agent can use. The value for oralogin can be an existing connect ID or a new one. The default value is “candle”.

Before running the procedure to grant authority, your database administrator must create the oralogin connect ID. Oracle login ID’s are NOT case-sensitive.

Oracle 7.1.4

The Oracle logon must be “SYS”, which has all required authority. This is necessary because Oracle 7.1.4 does not allow any other user to read the V_$ system views.

Oracle 7.1.6

To grant select permissions, the database administrator must issue the following SQL statement:

grant select any table to oralogin

Oracle and Sybase


where oralogin is the Oracle connect ID for the instance of Oracle. This is necessary because Oracle 7.1.6 does not honor grants to the V_$INSTANCE performance view.

Oracle 7.2.2 and higher

Run the following Candle-provided korgrant.sql script as described in the following procedure.

1. Change to the agent for Oracle directory:cd $candlehome/misc/

where $candlehome is your $candlehome directory.

2. Set the environment to start SQLPLUS or your tool for issuing SQL statements. At a minimum, all the tools require that the following environment variables be set:

ORACLE_SID

ORACLE_HOME

where:

� ORACLE_SID is the Oracle instance. Oracle instances are case sensitive.

� ORACLE_HOME is the home directory of the Oracle instance.

Note: For your convenience, the configuration files created by CandleDBconfig are Bourne shell scripts that export these two variables. In the Bourne or Korn shell, you can use the scripts directly. If you are using C shell, start a Bourne or Korn shell, then complete the rest of this procedure in the shell just started. To use the shell scripts, type:

cd $candlehome/config. ./hostname_or_instance

where “hostname” is the name of your host, and “instance” is the name of the Oracle instance.

3. To run korgrant.sql, start your tool for issuing SQL statements.

4. Log on as “sys”.

5. Once you have logged in, type:@korgrant oralogin

where oralogin is the Oracle connect ID for the instance of Oracle.


Oracle and Sybase

Output will be logged to the korgrant.log file.

6. Exit your tool for issuing SQL statements.

7. For Oracle 7.2, Oracle ignores grants to the V$LATCH table. To correct this, apply the Oracle patch for base bug #254661 so that you can view data in the Cache Totals Report for Server report.

8. If you do not install this Oracle patch, you may want to change the Oracle connect ID (oralogin) to “sys”.

Task 4. Sybase—Installing Sybase Open ClientThe agent for Sybase requires the runtime portion of the Sybase Open Client product.

1. You can obtain this product from Sybase, or you can obtain the runtime portion of it free of charge from Candle customer service.

2. If you have installed Open Client at a location other than what is recommended, create a softlink (symbolic link) to the subdirectory where ct_lib resides.

Sybase Open Client 10.04 locale files required for the Sybase monitoring agent collector

If your Open Client is not installed or properly linked, you will see the message,

ct_init() failed

when you attempt to start the monitoring agent for Sybase. When you get that error message in the collector log, follow these steps to rectify:

1. If you have the file on a PC, you need to ftp to UNIX using binary mode.

2. Login on UNIX as user “sybase”.

3. Copy the file SybRun.$os.tar.Z to the $SYBASE directory1. Where $os = aix, hp or sol

4. Enterzcat SybRun.$os.tar.Z | tar -xvof -

This will extract the following directories into the $SYBASE directory:

� charsets

Oracle and Sybase


� include

� init

� locales

� scripts

5. Set proper permissions on these directories.1. You must be in the $SYBASE directory.2. Enter

chmod -R 755 charsets init locales

6. Restart the Sybase monitoring agent collector and see if it is working.

7. (optional) Delete the file SybRun.$os.tar.Z in the $SYBASE directory.

Task 5. Sybase—Granting connect and select authority to the database

The Sybase system administrator must first create the Sybase login. The normal stored procedure for doing this is sp_addlogin candle, where candle is the Sybase login you have selected. Note that Sybase login names are case-sensitive. To grant select permissions to the Sybase database user, the Sybase system administrator must complete the following procedure for each Sybase database to be monitored.

1. Change to the monitoring agent for Sybase directory:cd $candlehome/misc/


2. The koygrant.sql script is designed to grant permissions to user ID “candle”. If your Candle user ID is not “candle”, edit the grant statements in koygrant.sql.For example, the following command will create an SQL script named newgrant.sql with all occurrences of “candle” changed to “monitor”:

sed ‘s/candle/monitor/’ koygrant.sql >newgrant.sql

3. Execute the koygrant.sql:$SYBASE/bin/isql -U sa -i koygrant.sql

4. At the password prompt, type the Sybase system password.


Oracle and Sybase

Task 6a. All—Manage Candle Services advanced configurationUse the following procedure to begin the advanced configuration of the database agents from the Manage Candle Services window.

1. In the Manage Candle Services window, select (highlight) the Database (Oracle or Sysbase) Monitoring Agent.

2. From the menu bar, select “Actions > Configure Advanced”.An X-term window is opened to complete the remainder of the configuration using CandleDBConfig.

You will get the following error message if you have not completed Task 1.

Your kddos root permission is not set. This will impede database self-discovery.

See “Task 1. All—Setting UNIX permissions for kddos” on page 158.

3. Proceed to “Task 7. All—Configuring the agent to your installed databases and verifying installation” on page 164.

Task 6b. All—command-line advanced configurationUse the following procedure to begin the advanced configuration of the database agents from the command line:

1. Logon to the machine on which the database server runs.



3. Type: CandleDBConfig

You will get the following error message if you have not completed Task 1.

Your kddos root permission is not set. This will impede database self-discovery.

See “Task 1. All—Setting UNIX permissions for kddos” on page 158.

4. If you have installed the monitoring agent for Sybase or the monitoring agent for Oracle in your environment, a menu will display the installed products. Select the agent you wish to configure.

Oracle and Sybase


5. Proceed to “Task 7. All—Configuring the agent to your installed databases and verifying installation” on page 164.

Task 7. All—Configuring the agent to your installed databases and verifying installation

Use this procedure to configure the agents to work with the specific database servers located on each machine and to verify that the agents are ready for use. During this procedure, you will use the CandleDBConfig program to locate the agent servers on the system you wish to monitor. The search process is very reliable if the servers are running when CandleDBConfig searches for them, but CandleDBConfig can often find non-running servers as well. Additionally, the CandleDBConfig program can verify that the installation and configuration are complete.

1. At the first menu, you would normally select the first option, “Confine automatic search to running databases”. The program will then search for your databases, and display the results. If it found all your servers, you may continue with the next step. Otherwise, continue with step 6 below.

2. Once the search is complete, the Database Options menu appears. If the initial search found all your databases, configuration is complete. However, Candle strongly recommends that you verify the installation by selecting the fifth option, “Verify Database OMA installation”.

3. If a database you want to monitor is not running, or is running on another machine, then the initial search may not have found it. CandleDBConfig can find non-running database servers by searching disk files. This process is slower and less reliable than searching running servers. This step and succeeding steps outline a progression of search techniques, which range from the easiest to the most labor-intensive. Use only those which you need. To do this kind of search, exit CandleDBConfig, re-enter it, then select the second option, “Also search for non-running databases”. Press “Enter”.

4. You will be taken to the Database Options menu. If the initial search did not find your database servers, select the second option, “Optional disk searches, manually add servers...”.

5. The menu which appears represents a hierarchy of alternate search techniques, listed in the order of the amount of manual input they require. Note that the list of UNIX users also displays the name of the filesystem on which each user’s $HOME is located. Also note that searches through NFS file


Oracle and Sybase

systems can take some time. The last option presented in the menu, “Manually add a server”, is a tool of last resort. It can be used to define any server which is located on a filesystem that you cannot currently access.

6. Return to the Database Options menu. If the various searches found databases you do not want monitored, or which run on other UNIX machines, you should exclude them from consideration by selecting the fourth option, “Exclude/Include a server from the configuration”. Any server excluded will be ignored by future searches, but it can be manually included at any time.

7. You may review the details of the servers by selecting the third option, “Display or Modify defined servers...” on the Database Options menu.

8. When you have finished all of the configuration steps, verify the installation by selecting the fifth option, “Verify Database OMA installation” on the Database Options menu.

9. When you exit CandleDBConfig, you will see a message which names a file containing a log of your CandleDBConfig activity, which can help Candle customer service diagnose any configuration problems.

Note: The “Verify Database OMA Installation” option will not inform the user if they enter the wrong user ID or password.

CandleDBConfig procedure for “I” (incomplete) status messageUse the procedure below when running CandleDBConfig if a database search is done and a database comes back with an “I” (incomplete) status.

1. Start CandleDBConfig

2. Pick any of the menu items that do a database search. For example, pick item 1 from the menu (“Confine Automatic Search to Running Databases”).

3. If the database returns with an “I” next to it, that means the configuration is in incomplete status. If this occurs, from the next menu pick item # 1: “All Servers Found. Ready to specify logins/passwords...”.

4. On the Candle DB Config: Login/Password for Servers menu, under item #1, it displays the database name of the database in question. Next to it is the version, the installation status (“Incomplete”) and the login. Select item #1.

5. The following prompt appears: Enter connect-id for [system]:

Enter the login here or press “Enter” (for default of “candle").

Oracle and Sybase


6. The following prompt appears: Enter password for candle.

Enter the password.

7. The Candle DB Config: Login/Passwords for Servers menu reappears with installation status shown in item #1 as “Fully Configured”.

Setting the managed system name for Distributed DatabasesThe managed system name for a database agent consists of three parts—the database server name, the hostname and a static portion that is the type of agent—ORA, SYB; for example, SY11S26:earth:SYB.

In a high availability cluster environment, the system hostname of the two machines (primary and failover) will be different, so the hostname part must be set so that it does not change when the agent is swapped to the failover machine.

Environment variablesThere are two environment variables which influence the setting of the hostname part of the managed system name for the database agent—COLL_HOSTNAME, and KDCB0_HOSTNAME. If neither of these variables is set, then the agent will use the system hostname which is returned by the hostname command.

Besides the hostname part of the managed system name, these two variables govern other aspects of the database agent. Here is a more detailed explanation.

Two things COLL_HOSTNAME governs

1. The names of temporary and log files which are generated by the database agents

2. The hostname part of the managed system nameIf the variable is not set, then the system hostname, as returned by the hostname command, will be used for these two purposes.

Two things KDCB0_HOSTNAME governs

1. The network interface that the agent uses to connect to the CMS2. The hostname part of the managed system name


Oracle and Sybase

This variable overrides the COLL_HOSTNAME setting for the hostname part of the managed system name, but it does not influence the other things which COLL_HOSTNAME governs.

Recommendations

In a clustered-server environment, such as HP Service Guard or AIX HACMP, it is assumed that the "virtual hostname" interface will provide a bi-directional path to the system where the CMS is running. (The term“virtual hostname” varies with the OS vendor and is the IP address or DNS name that automatically moves from the primary to the failover machine when the primary machine gives control to the failover machine.)

It is also assumed that the hostname will be different for the primary and the failover machines.

Candle recommends that the KDCB0_HOSTNAME be set to the "virtual hostname" DNS name in the clustered-server environment, and that COLL_HOSTNAME should not be set. The reasons for this are:

� The database agent is able to connect to the CMS from either the primary or the failover machine, using the "virtual hostname", IP address, or the DNS name.

� The managed system name will not change when the database agent swaps from the primary to the failover machine.

� The temporary files and log files will have slightly different names because the hostname is different, so we will be able to distinguish between logs generated by the primary or the failover system. This assists with any necessary debugging.

Localization of temporary filesIf you have installed the agent for Distributed Databases, by default, temporary files that are created are stored under the default UNIX temporary directory, for example /tmp/kdd.<userid>/<HOSTNAME>_pc_<instance>where pc = product code.

� Temporary files include *.out, *_col.out, and all *_pipe files.

� If you do not want localization of these temporary files, you can edit the configuration file for the Sybase agent and add the following variable under “# User-defined environment variables”:

Oracle and Sybase


export KDD_PREFIXLOCAL="NONE"

The temporary files will then be stored in the following sub-directory under $candlehome

$candlehome/tmp/kdd.<userid>/<HOSTNAME>_pc_<instance>

Note: The KDD_PREFIXLOCAL=xxxx environment variable if you want it to apply to all configured databases could be placed in the profile for the user that starts the agents. Any environment variables set in the configuration file only applies to that agent.

� If you want to collect the temporary files in a specific sub-directory, you can include the full path name for any one of the following variable definitions in the configuration file:

db_pipedir=”<full path name>” (This variable takes precedence)

KDD_PREFIX=”<full path name>”

KDD_PREFIXLOCAL=”<full path name>”

Sample configuration fileThe following is a sample agent for Oracle configuration file. Other Distributed Database configuration files are similar in format.

#Candle Omegamon Monitoring Agent (OMA) for Oracle#Configuration file: mars_or_O805.config#Written by CandleDBconfig version: 1.26 on 29Sep99 11:13:36

#Note: this is a Korn-shell script that is “sourced” to create#the environment for a Candle OMA. It can be used to create the#environment to run the Candle-supplied database grant scripts.

#Candle does not recommend that you modify this file, but you can#change the data values or add new exported variables as long as#the file is a valid ksh script that executes with zero return#code, and values remain quoted with ““.

#Following environment variables are set for convenience in#running grants.export ORACLE_SID=”O805”export ORACLE_HOME=”/oracle/app/oracle/product/8.0.5”

#Following variables are set for the setup scriptdb_sid=”O805”db_home=”/oracle/app/oracle/product/8.0.5”db_initfilename=””db_login=”candle”


Oracle and Sybase

db_password=”12D0539”db_ver=”8.0.5.0.0”db_type=”kor”db_hostname=”mars”db_reason=”fuser”db_pipedir=”local_dir_path”db_installstatus=”CONFIGSUCCESS”

# User-defined environment variablesexport KDD_PREFIXLOCAL=”NONE”




Although the OMEGAMON XE for WebSphere MQ Configuration agent does not require an advanced configuration procedure, you must ensure that you have seeded the CMS Configurator component (product code cf).

Using the Manage Candle Services window to seed cf� If you installed the OMEGAMON XE for WebSphere MQ Configuration

agent on UNIX, run the Quick Seed seeding procedure described in “Quick Seed procedure” on page 140.

� If you did not install the OMEGAMON XE for WebSphere MQ Configuration agent on UNIX but will be connecting to an agent on another platform, run the Advanced Seed procedure described in “Advanced seeding” on page 141. Select the “CMS Configurator” from the list of products to seed.

Using CandleSeed to seed cfIf you are using the command line to seed the CMS, use the following command to seed for cf.

./CandleSeed [-h $candlehome] [-s] -t cms_name cf

where:

Table 43. Parameters for the CandleSeed Command to Seed cf






-t Use this required option to specify the CMS name.





Table 43. Parameters for the CandleSeed Command to Seed cf (continued)




This section contains instructions for completing the configuration of the OMEGAMON XE for WebSphere MQ Monitoring agent.

1. From the Manage Candle Services window, select “OMEGAMON WMQ Monitoring Agent”.

2. From the menu bar, select “Actions > Configure”. You are presented with a dialog to complete the agent to CMS connection.

3. Enter the CMS connection information in the fields.

4. To complete the CMS connection settings, see Table 17, “Agent to CMS Connection Settings,” on page 88.

5. Click Save to exit, Reload to reload a previous configuration, or Cancel to quit. You are returned to the Manage Candle Services window. This completes initial agent configuration, the agent is ready to start.

About the OMEGAMON XE for WebSphere MQ Monitoring agentEach OMEGAMON XE for WebSphere MQ Monitoring agent monitors a single WebSphere MQ Queue Manager. You can use No Queue Manage or you can monitor multiple queue managers. Use the procedure below to begin monitoring

Procedure to monitor none or multiple queue managers

If you are monitoring multiple queue managers, follow the procedure below:

1. From the Manage Candle Services window, highlight “OMEGAMON WMQ Monitoring Agent”.

2. Select “Actions > Start Service”. The Specify Queue Manager dialog is displayed.

3. Do one of these:� Specify “No Queue Manager” by selecting the top radio button.

� Specify “one or more Queue Managers” by selecting the second radio button, then enter the WebSphere MQ Queue Manager names in the blank fields. Up to 8 queue managers can be specified.

4. Click Start.



5. Configuration files are created for each WebSphere MQ Queue Manager using the default configuration. The configuration files reside in $candlehome/config directory.

Starting or stopping multiple agents for OMEGAMON XE for WebSphere MQ Monitoring using CandleAgent

When using CandleAgent from the command line, you can specify the MQ Queue Manager name using the “-o” option to monitor multiple agents for OMEGAMON XE for WebSphere MQ Monitoring.

� The “-o” option is used to specify the WebSphere MQ Queue Manager Name. For example,

CandleAgent -o qmgr1 start | stop mq

CandleAgent -o qmgr1,qmgr2 start | stop mq

where qmgr1 is the WebSphere MQ queue manager name.

� If you are using “No Queue Manager” (the “-o” option is not necessary)

CandleAgent start | stop mq

The [Hostname]_mq_[queue_manager_name].cfg file is created automatically when using this option. If using No Queue Manager, a mq.cfg file is created and used.

� For additional information on the CandleAgent command, see “CandleAgent” on page 120.

Default monitoring optionsCandle provides a default set of monitoring options for the OMEGAMON XE for WebSphere MQ Monitoring agent. These are stored in the agent’s configuration (*.cfg) file which is read at agent startup time.

Default objects must existBefore starting the OMEGAMON XE for WebSphere MQ Monitoring agent, WebSphere MQ default objects (such as SYSTEM.DEFAULT.MODEL.QUEUE) must exist. If they do not exist in your environment, create them before starting the agent.



Customizing monitoring optionsIf necessary, you can change the monitoring options for an OMEGAMON XE for WebSphere MQ Monitoring agent at any time by editing the agent’s configuration (*.cfg) file. For example, if you wish to collect historical monitoring data, you must set HISTORY(YES) in the agent’s configuration (*.cfg) file.

The configuration file for a given instance of the OMEGAMON XE for WebSphere MQ Monitoring agent has the following naming convention:

[Hostname]_mq_[queue_manager_name].cfg

� For information on historical data collection, see the Historical Data Collection Guide for OMEGAMON XE and CandleNet Command Center.

� For information on the various monitoring options for the OMEGAMON XE for WebSphere MQ Monitoring agent and the commands to enable them, see the OMEGAMON XE for WebSphere MQ Monitoring User’s Guide.




This section contains instructions for completing the configuration of the OMEGAMON XE for WebSphere Integration Brokers agent.

To customize the agent configuration data for your site, consult IBM’s documentation for its broker product and Candle’s OMEGAMON XE for WebSphere Integration Brokers User’s Guide for more information.

Note: Product installation for all UNIX platforms prompts you to optionally provide a root user ID to define softlinks for integrating the CandleMonitor node into the broker environment. Please see the section “Integrating the CandleMonitor node into Broker Environments” in Chapter 3 of the “OMEGAMON XE for WebSphere Integration Brokers User's Guide” for an explanation of the softlinks and other important requirements for using the CandleMonitor node in the broker.

Installing gnu compiler 2.95.3 on zSeries LinuxIn order for it to run, the agent on zSeries Linux requires installation of a particular IBM compiler. The installation of the compiler should be performed prior to installation of the agent. See “OMEGAMON XE for WebSphere Integration Brokers: Installing gnu compiler 2.95.3 on zSeries Linux” on page 58 for the description of this procedure.

Creation of library links to start the agent on Intel Linux

Note: This step is required only if the softlinks could not be defined during product installation. The softlinks must be in place prior to starting the monitoring agent.

In order to successfully start the OMEGAMON XE for WebSphere Integration Brokers agent on Linux Intel, some links have to be created so that the library names are resolved correctly.

If these links are not created, the agent will fail to start, and the following message is displayed in the agent's log:

.../kqiagent : error while loading shared libraries: <library name>: cannot open shared object file: No such file or directory

1. The following links in /opt/mqm/lib should point to the 2.95.2 GNU-compiler-built version of libraries provided by IBM.



If these are pointing to a 3.0.3 GNU version of libraries, then you need to redefine the links as follows:

ln -sf /opt/mqm/lib/2.95.2/libimqb23gl_r.so /opt/mqm/lib/libimqb23gl_r.so

ln -sf /opt/mqm/lib/2.95.2/libimqs23gl_r.so /opt/mqm/lib/libimqs23gl_r.so

You need root authority to be able to define these links.

2. Check if the file named libstdc++-libc6.1-2.so.3 exists in /usr/lib. If not, then you have to define the following link.ln -s /usr/lib/libstdc++-3-libc6.2-2-2.10.0.so /usr/lib/libstdc++-libc6.1-2.so.3

You may have to substitute libstdc++-3-libc6.2-2-2.10.0.so with another (equivalent) library name available in you/usr/lib directory.

After upgrading from a previous releaseAfter upgrading from a previous release to a 03R1 level image (or later) of the monitoring agent on a UNIX platform, make sure that the following directories are empty:

� AIX: $candlehome/<platform>/qi/lib, where platform is the architecture code of the platform on which you installed the agent (See “Candle Architecture Codes” on page 257.)

� Solaris: $candlehome/sol273/qi/lib

� HP-UX: $candlehome/hp11/qi/lib

Authorizing the agentTo authorize the agent to receive the correct broker data, follow the steps below.

1. Create a user ID account for the agent, if necessary. The agent’s user ID account must:� Have authority to subscribe to broker event publications.

� Belong to groups “mqm” (this must be the primary group) and “mqbrkrs”.

The agent’s user ID account requirements are similar to the broker’s, however the agent’s user ID account does not have to exactly match the broker’s for groups not mentioned above. If desired, you can use the broker’s account.



2. Start the agent with either the same user ID as the broker or with a user ID that belongs to similar groups as the broker’s user ID (as described in Step 1). However, never start the agent using a user ID that has a higher authority than the broker’s authority or that has root authority unless the broker also runs with root authority.� The user ID that is used to start the agent should be running with the

profile supplied in the broker samples directory (located in /opt/mqsi/sample/profiles, or on AIX, in /usr/opt/mqsi/sample/profiles). This is the same profile that the service user ID for the broker must be running with. Note that if you use the "switch user" command to change user IDs, you must make sure that the profile is invoked by using the "su - <user ID>" form of the command. If the agent's user ID is not running with the proper environmental settings from the profile, several Take-Action commands will fail.

� If you are starting the agent with a different user ID than the one you used for the installation, or if you have performed a GUI installation, you will need to make sure that permissions to the following directories allow creating and writing files:

– $candlehome/logs

– $candlehome/config

– $candlehome/$arch/qi/hist

where $candlehome is the directory in which you installed OMEGAMON XE for WebSphere Integration Brokers and $arch is the Candle architecture code (See “Candle Architecture Codes” on page 257.).

For OMEGAMON XE for WebSphere Integration Brokers, $arch will be one of the following: sol273, hp11, ls3243, li6243, or the Candle architecture code for the version of AIX on which you installed the agent.

3. Depending on your site's ACL entries, you may be required to authorize the agent to receive broker event publications in the Control Center or Message Brokers Toolkit. You do not have to perform this step if your site uses the IBM defaults. However, if ACL entries in the Topics tab of the Control Center or Message Brokers Toolkit have been modified such that subscribe access to topics beginning with “$SYS/Broker” has been restricted, this step is required.



4. An ACL entry for topics beginning with “$SYS/Broker” must be added to set “Subscribe” access to “Allow” for the user ID of the agent. The principal for the ACL entry should give the user ID of the agent, or it can give a group to which the agent's user ID belongs, such as “mqbrkrs”. The ACL entry must be deployed to all brokers to be monitored by the OMEGAMON XE for WebSphere Integration Brokers agent. This change will allow the agent to receive the broker event publications. If the agent is restricted from receiving these publications, much data in OMEGAMON XE for WebSphere Integration Brokers reports will be missing or inaccurate. (Specifically, the Broker Events workspace will display no data.)

Note: The simplest way to make sure that the agent's user ID is fully authorized for all product features is to use the broker's service user ID (the one that is used to start the broker) for starting the agent.

Product code for OMEGAMON XE for WebSphere Integration BrokersUse the following product code for OMEGAMON XE for WebSphere Integration Brokers when installing from the command line.

qi

Using the Manage Candle Services window to configure the agentYou can configure the connection between the CMS and the OMEGAMON XE for WebSphere Integration Brokers agent from the Manage Candle Services window. See “GUI Installation Steps” on page 75 for information about the Manage Candle Services window.

Using CandleConfig to configure the agent (command line)To configure the agent from a command line, use the CandleConfig script. CandleConfig resides in $candlehome/bin. Execute CandleConfig as follows:

cd /$candlehome/bin

./CandleConfig -A [-h $candlehome] [-s] [-a arch] qi

where arch is replaced with either “sol273”, “hp11” or the Candle architecture code for the version of AIX on which you installed the agent (See “Candle Architecture Codes” on page 257.)



CandleSeed

Note: Use if you installed a CMS on UNIX or if you are connecting to a previously installed CMS. If you are not connecting to a UNIX-based CMS, you can proceed to the next step.

If you installed a CMS on UNIX or if you are connecting to a previously installed UNIX-based CMS, complete the seeding procedure from the Manage Candle Services window or from the command line.

The seeding procedure installs predefined situations and take action commands for use with the CandleNet Portal.

Removing broker entries from Manage Candle ServicesTo remove a broker entry from the Specify Brokers pop-up in the Manage Candle Services window, go to $candlehome/config and delete the xml parameter file for the entry. The file is named: hostname_qi_brokername_##_agentID.xml

where:

hostname is the local host name, brokername is the name of the broker entry you want to remove, and agentID is the entry you want to remove.

Starting or stopping multiple agents using CandleAgentWhen using CandleAgent from the command line, you can optionally specify the broker name using the “-o” option to give a broker name and the “-p” option to specify an agent ID so that you can use multiple agents for OMEGAMON XE for WebSphere Integration Brokers on the same system (to monitor different brokers).

� The “-o” option specifies the broker name.

� The “-p” option specifies the monitoring agent ID (4 characters or less).

For example:

CandleAgent -o brokername -p agentID start | stop qi

The [Hostname]_qi_[brokername]_##_[agentID].xml file is created automatically when using this option.

To run a single monitoring agent on the system using the default monitoring parameters in kqi.xml, run CandleAgent as follows:



CandleAgent start | stop qi

What to do nextRefer to the procedures in “Starting and Stopping Candle Products” on page 215.

The Message Broker must be restarted for changes to take affect to allow monitoring of the broker. It is best if the Message Broker is taken down during installation if this is an upgrade to a new version. (It is not necessary to take it down for the first install, but it is still necessary to restart the broker.)


R/3

R/3

OverviewOMEGAMON XE for R/3 agent must be configured with values specific to your environment. In addition, there are modules that you must add to your R/3 environment to allow OMEGAMON XE for R/3 to collect data. Multiple R/3 agents can be monitored by identifying and configuring the agents using the three character R/3 system identifier.

Password encryption (optional)Among the values that you will set when you edit sa_[System_Name].config is SAPPASSWORD. With OMEGAMON XE for R/3 (version 300) and higher, you can encrypt the password used by the ksaagent when it logs on to the R/3 system, or by OMEGAMON XE when you navigate to R/3. You can enter the value for SAPPASSWORD in the following ways:

� As plain text

� Encrypt the password into a file (using the utility ksar3pwd) and specify this filename in the SAPPASSWORD variable.

� As the keyword “FILE(KSA.PWD)” to read the password from a file named KSA.PWD

� As the keyword and value “FILE(ffffff)” to read the password from a file named ffffff

Passwords are encrypted using the ksar3pwd utility.

ksar3When you request navigation from OMEGAMON XE to R/3, OMEGAMON XE calls ksar3 with the appropriate parameters to invoke the required R/3 transaction. These parameters normally include the R/3 logon parameters used by the ksaagent. If you require specific R/3 logon parameters for OMEGAMON XE, set them in the ksar3 file. If these logon parameters are set in the ksar3 file, they override the logon parameters passed by OMEGAMON XE. If the same logon parameters are used by the agent and OMEGAMON XE, ksar3 need not set any logon parameters.

R/3


If you want to prevent the ksaagent R/3 logon parameters from being sent to the OMEGAMON XE workstation for security reasons, set the SAPNOLOGONPARMS to 1 for the ksaagent.

The SAPHOST parameter is always passed by the OMEGAMON XE workstation to ksar3.

Note: If a situation requires action within R/3, the situation should be defined to call ksar3.

Configuring agent parametersUse the following procedure to configure the agent parameters for the R/3 monitoring agent. To complete the R/3 configuration, the SAP R/3 Administrator should be available.

1. In the Manage Candle Services window, highlight “Monitoring Agent for R/3”.

2. From the menu bar, select “Actions > Configure > Agent Parameters“.

3. The R/3 advanced configuration dialog is presented.

4. Complete the fields with the values for your site.

Table 44. R/3 Agent Parameter Settings

Field Description

R/3 System Information

System Name Enter the three-character R/3 system identifier (SID).

The name you supply will be used to identify this instance of the R/3 monitoring agent and will appear in the Task/Subsystem column of the Manage Candle Services window.

Hostname Enter the hostname of the R/3 central instance. Defaults to the hostname where the agent is running. (This is the NIC Hostname if more than one NIC is installed on the system.

System number Enter the two-character R/3 system number. Defaults to 00.

R/3 Logon Information

Client number Enter the R/3 client number for the RFC logon to R/3. Defaults to 000.

User ID Enter the R/3 user ID for the RFC logon to R/3. Defaults to SAPCPIC.


R/3

5. Click OK.The configuration file name for any given instance of the R/3agent has the following format:

sa_[System_Name].config

Installing remote function modules into R/3This procedure installs skeleton remote function module code. The actual code is installed by the ksaagent when it starts. The installed code will not be

Password One of the following options for Password:� “Password”: Enter the R/3 password for the user ID you specified.

Defaults to ADMIN. � “Password File”: The name of the file that an encrypted password

can be read from. (Refer to “Password encryption (optional)” on page 181.) If the password file is not in the same directory as the R/3 monitoring agent, specify the full path and file name of the password file.

R/3 Flags

Language Enter the one-character identifier for the messages value. Defaults to E (English).

RFC Trace Set the RFC trace flag:� “0” =no trace (Default)� “0” =trace.

RFC Connection Set the RFC connection flag to request that the connection be closed after data has been collected:� “0” =keep the RFC connection open. (Default)� “1” =close the RFC connection.Candle strongly recommends setting this flag to 0. Set to 1 if the agent is only to sample data very infrequently.

Send Parms to CMW

Set the flag to prevent the agent logon parameters, defined above, which are used by the agent, from being sent to the CMW:� “0” =send the agent logon parameters to the CMW.� “1” =do not send the agent logon parameters to the CMW

Table 44. R/3 Agent Parameter Settings (continued)

Field Description

R/3


visible within R/3 and may not be modified or generated. To insert the remote function modules:

1. Change to the R/3 agent directory:cd $candlehome/arch/cma/sa/bin

where: $candlehome is your $candlehome directory and arch is:

� aix513 (for AIX R5.1 32-bit systems).




� hp102 (for HP-UX R10.20 systems).

� hp11 (for HP-UX R11.x systems).

� sol26 (for Solaris R2.6.x systems).

� sol273 (for Solaris R7 32-bit systems).

� sol276 (for Solaris R7 64-bit systems).

2. Copy the file, RSAV300.CAN, to the Transport System data directory, usually /usr/sap/trans/data:

cp RSAV300.CAN /usr/sap/trans/data/RSAV300.CAN

3. Copy the file, KSAV300.CAN, to the Transport System co-files directory, usually /usr/sap/trans/data:

cp KSAV300.CAN /usr/sap/trans/cofiles/KSAV300.CAN

4. Verify that the following names are not already in use:� SAP R/3 Development Class ZCAN\

� SAP R/3 Function Group YCAN

� SAP R/3 Function modules that begin with Y_CAN

� SAP R/3 Transaction YCAL

� SAP R/3 Module Pool SAPMYCAL

� SAP R/3 Tables or Structures that begin with YCAN

� SAP R/3 Authorities that begin with YCAN_


R/3

If these names are already in use, rename them or contact Candle for another Transport Data file.

5. Change to the bin directory where the Transport Administrators reside:cd /usr/sap/trans/bin

6. Issue these commands:tp addbuffer CANKSAV300 SID pf=/usr/sap/trans/bin/TPPARAM

tp import CANKSAV300 SID clientnnn U16 pf=/usr/sap/trans/bin/TPPARAM

where:

� SID is the target R/3 system id.

� nnn is the target client number.

Verifying R/3 user authorizationThe R/3 user ID specified in the SAPUSER variable must have sufficient authority to execute the Remote Function Call (RFC) code that was installed when you imported the RSAV300.can file. Use the following procedure to verify the user authorization for that user ID.

1. Verify that the user ID is at least authorized for Authority Object S_DATASET as follows:

Field Value

ABAP/4 Program Name=SAPLSPFL, SAPLSTUW, SAPLY210

Activity=33

SAP External File Name=*

Note: The Candle supplied Authorization YCAN_DATASET in profile YCANDLE contains the required authority object S_C_FUNC.

2. Verify that the user ID is at least authorized for object S_C_FUNC as follows:

Field Value

ABAP/4 Program Name=SAPLY210

Activity=16

SAP External File Name=SYSTEM

R/3


Note: The Candle supplied authorization YCAN_C_FUNC in profile YCANDLE contains the required authority for object S_C_FUNC.

3. Verify that the user ID is at least authorized for object S_ADMI_FCD:

Field Value

System administration function=STOR

Note: The Candle supplied authorization YCAN_ADMIFCD in profile YCANDLE contains the required authority for object S_ADMI_FCD.

4. If RFC authority checking is turned on for your system, (profile parameter rfc/authority_check=1), verify that the user ID is at least authorized for object S_RFC:

Field Value

Activity=16

Name of RFC=SLO2 SLST SMON STUB STUW Y210

Type of RFC object=FUGR

Note: The Candle supplied authorization YCAN_S_FRC in profile YCANDLE contains the required authority for object S_RFC.

5. Verify that the user ID is defined as a CPIC or DIALOG user.

Note: CPIC is preferable.

6. Additional authorization is required in order to run individual transaction using CMW reports. The required authorization can be found in table usobt using SE16, or it can be found using SE93 for most transactions.

Example

To find what is required to run st22, from SE16, enter table name usobt, then enter column name 'st22'. You will see s_develop is required.

Verifying that Collector_For_Performance_Job is scheduledVerify that the Collector_For_Performance_Job batch job is set up as described in the R/3 installation documentation and SAP OSS Note 16083.


R/3

Editing sa_[System_Name].configUse this procedure to add site-specific values to your sa_[System_Name].config, where [System_Name] is the R/3 System ID.

Note: The SAPUSER that you designate in this file must have the authority to execute the Remote Function Call that you will install as one of the configuration tasks. That user must also be defined as a CPIC or DIALOG user, preferably CPIC.

To update sa_[System_Name].config with values for your site:

1. Change to the directory in which the sa_[System_Name].config file resides:$candlehome/config


2. Enter your SAP values for the following:

3. Enter the following logon values:� For “SAPCLIENT”, enter the R/3 client for the RFC logon to R/3. Defaults

to 000.

� For “SAPUSER”, enter the R/3 user ID for the RFC logon to R/3. Defaults to SAPCPIC.

� For “SAPPASSWORD”, enter the R/3 password for SAPUSER. It defaults to ADMIN.

Table 45. SAP Values in sa_[System_Name].config

Variable Value to Add

SAPSYSTEMNAME Enter the three-character R/3 system identifier. Defaults to space.

SAPHOST Enter the hostname of the R/3 central instance. Defaults to the hostname where the agent resides.

SAPSYSTEMNUMBER Enter the two-character R/3 system number. Defaults to 00.

SAPGATEWAY Enter the hostname where the gateway process is running. Defaults to the same value as SAPHOST.

SAPGATEWAYSERVICE Enter the TCP/IP port number and type. Defaults to 33nn/tcp, where nn is equal to the SAPSYSTEMNUMBER.

R/3


4. Enter the one-character identifier for the messages value, “SAPLANGUAGE”. Defaults to E (English).

5. For “SAPLANGUAGE”, set the RFC trace flag:� “0” =no trace.

� “1” =trace.

Defaults to 0.

6. For “SAPCLOSERFC”, set the RFC connection flag to request that the connection be closed after data has been collected:� “0” =keep the RFC connection open.

� “1” =close the RFC connection.

Defaults to 0. Candle strongly recommends setting this flag to 0. Set to 1 if the agent is only to sample data very infrequently.

7. For “SAPNOLOGONPARMS”, set the flag to prevent the agent logon parameters, defined above, which are used by the agent, from being sent to the CMW:� “0” =send the agent logon parameters to the CMW.

� “1” =do not send the agent logon parameters to the CMW.

Note: The value SAPHOST will always be passed by the CMW to ksar3 based on the instance you are looking at when navigating to R/3.

Removing remote function modules from R/3Should you ever choose to remove OMEGAMON XE for R/3 from your system, use this procedure to remove the Remote Function Modules from R/3:

1. Change to the R/3 agent directory:cd $candlehome/arch/cma/sa/bin

where:

� $candlehome is your $candlehome directory.

� arch is one of the following, based on your operating system:

– aix513 (for AIX R5.1 32-bit systems).




R/3


– hp102 (for HP-UX R10.20 systems).

– hp11 (for HP-UX R11.x systems).

– sol26 (for Solaris R2.6.x systems).

– sol273 (for Solaris R7 32-bit systems).

– sol276 (for Solaris R7 64-bit systems).

2. Copy the file, RSAD300.CAN, to the Transport Systems data directory, usually /usr/sap/trans/data:

cp RSAD300.CAN /usr/sap/trans/data/RSAD300.CAN

3. Copy the file, KSAD300.CAN to the Transport System co-files directory, usually /usr/sap/trans/cofiles:

cp KSAD300.CAN /usr/sap/trans/cofiles/KSAD300.CAN

4. Change to the bin directory where the Transport Administrators reside:cd /usr/sap/trans/bin

5. Issue the following commands:tp addtobuffer CANKSAD300 SID pf=/usr/sap/trans/bin/TPPARAM

tp import CANKSAD300 SID clientnnn U16 pf=/usr/sap/trans/bin/TPPARAM

where:

SID is the target SAP R/3 System Name.

nnn is the target client number.

Environment variables in ksar3 and ksanfy script filesThese are the environment variables that can be set in both the ksar and the ksanfy script files to set the parameters that the ksar3exe and ksar3nfy utilities use to log on to the R/3 system.

To set an environment variable, remove the # sign and supply a value in place of the letters following the equal sign:

# export SAPHOST1=hhhhhh



R/3


# export SAPSYSTEMNAME=nnn

# export SAPSYSTEMNUMBER=nn

# export SAPCLIENT=ccc

# export SAPUSER=uuuuuuuu

# export SAPPASSWORD=pppppppp

Descriptions of each environment variable follow.

Special values for SAPUSER and SAPPASSWORD

The following special values can be set for the SAPUSER and SAPPASSWORD variables instead of supplying a user ID or password:

Table 46. R/3 Logon Environment Variables

SAPHOST1 The primary host name of the R/3 instance.

SAPHOST2 A second, alternative host name.

SAPHOST3 A third, alternative host name.

SAPSYSTEMNAME The 3-character R/3 system identifier.

SAPSYSTEMNUMBER The 2-character R/3 system number.

SAPCLIENT The R/3 client number.

SAPUSER The user ID.

SAPPASSWORD The user’s password.

Table 47. Special Values for SAPUSER and SAPPASSWORD

Value Description

CMW() Instructs the program to obtain the R/3 logon user ID and password from the CMW.

PROMPT(ONCE) The program will prompt the user only once to supply the R/3 logon user ID and password. This prompt is reissued only if the CMW is restarted.

PROMPT(EVERY) The program will prompt the user every time to supply the R/3 logon user ID and password.

Note: PROMPT(EVERY) overrules PROMPT(ONCE) which overrules CMW().


R/3

Configuring the R/3 agent using CandleConfigIf you are configuring the R/3 agent from the command line, use the following format for CandleConfig.

CandleConfig -A -o sa1 sa

The above command configures the R/3 agent for the System Name “sa1”.

You can have multiple configurations for the R/3 agent, one for each R/3 System Name. Each configuration must be created separately by running CandleConfig or the Agent Parameters window.

The “-t” option for CandleConfig is no longer applicable to the R/3agent configuration.

The sample screen below illustrates the command line prompts for the R/3 agent configuration. The previous table should be used for completing the prompts.

<vulcan:/users/longl/inst/didev/bin> ./CandleConfig -A -o sa1 saCandleConfig : installer level 350 / 220.CandleConfig : running aix513 jre.Agent configuration started...

Will this agent connect to a CMS? [YES or NO] (Default is: YES): CMS Host Name (Default is: vulcan):


Network Protocol [ip, sna, or ip.pipe] (Default is: ip):

Now choose the next protocol from one of these: - sna - ip.pipe - noneNetwork Protocol 2 (Default is: none): IP Port Number (Default is: 1918): 3141

Configure connection for a secondary CMS? [YES or NO] (Default is: NO): Enter Optional Primary Network Name or "none" (Default is: none): Hostname(Default is: vulcan): System Number(Default is: 00): Gateway(Default is: vulcan): Gateway Service(Default is: 3300/tcp): Client Number(Default is: 800): User ID(Default is: longl): Password(Default is: Null): Language(Default is: E): RFC Trace Flag(Default is: 0): RFC Connection Flag(Default is: 0): Send Agent Logon Parms to CMW(Default is: 1): ... Writing to database file for sa.Agent configuration completed...

R/3


Starting or stopping the R/3 agent using CandleAgent with -o optionWhen using the command line to start or stop the R/3 agent, you should use the -o option to specify which R/3 system to monitor. The -o option is used to specify the three character SAP system ID. For example,

CandleAgent -o sa1 start sa

or

CandleAgent -o sa1 stop sa

where sa1 is the SAP system ID.

For additional information on the CandleAgent command, see “CandleAgent” on page 120.


Remedy ARS

Remedy ARS

Advanced configuration procedure

1. From the Manage Candle Services window, select (highlight) Remedy ARS Alert Adapter.

2. Select “Actions > Configure > Agent Parameters“.

3. The Configure Remedy ARS Alert Adapter advanced dialog is displayed


5. Click OK to save your settings. Click Cancel to abort the configuration.

Table 48. AA for Remedy ARS Agent Configuration Values

Field Description

Server The Hostname or IP address where the Remedy Server is running.

User ID Enter the Remedy User ID to be used logging into the Remedy database.

Password Enter the password for the user ID specified above.

Note: This entry is encoded when typed

Server Port Enter the port number to be used in the range 1025 to 65535.

Tuxedo


Tuxedo

Advanced configuration procedureUse the procedure below to configure the agent parameters. For more configuration information see tmloadcf(1) in the BEA Systems’ TUXEDO Reference Manual. The configuration file name for any given instance of the Tuxedo agent has the following format:

tx_[Domain_Name].config

1. From the Manage Candle Services window, select (highlight) Tuxedo Monitoring Agent.

2. Select “Actions > Configure > Agent Parameters”.The Configure Tuxedo Agent Parameters dialog is displayed.


Table 49. Tuxedo Monitoring Agent Parameter Configuration Values

Field Description

Application Domain Name The domain name of the TUXEDO application being monitored. Example:

tx1This value is used to distinquish between Tuxedo agents that are installed on the same machine. The name you supply becomes the first part of the managed system name and is visible on many OMEGAMON XE displays.

Tuxedo Directory Path The home directory where the BEA TUXEDO software is installed. (Enter the same path you gave when you configured the domain.) Example:

/candlet/stage2/hr/tuxedo

Tuxedo Configuration File Path

The complete name and path of the binary configuration file for the TUXEDO domain that the agent will monitor. This is the compiled binary TUXCONFIG configuration file that is generated when you first run tmloadcf.exe to parse the ASCII UBBCONFIG configuration file. Example:

/candlet/stage2/hr/hr750/appserv/HRSTAGE/PSTUXCFG


Tuxedo

Note: *These parameters can be left empty if your environment does not use application queues.

4. Click OK to save your settings. Click Cancel to abort the configuration.

Configuring the Tuxedo agent using CandleConfigIf you are configuring the Tuxedo agent from the command line, use the following format for CandleConfig.

CandleConfig -A -o tx1 tx

The above command configures the Tuxedo agent for the Application Domain Name “tx1”.

You can have multiple configurations for the Tuxedo agent, one for each Tuxedo Application Domain Name. Each configuration must be created separately by running CandleConfig or the Agent Parameters window.

The “-t” option for CandleConfig is no longer applicable to the Tuxedo agent configuration.

Tuxedo Version Select the Tuxedo version you are running� Tuxedo 6.5� Tuxedo 7.x

Tuxedo Queue Name* Name of the application queue (QSPACE)

Tuxedo Queue Config File Path*

Absolute pathname of the file or device where the application queue space is located. An example is

/tuxedo/apps/msgq/QUE

Tuxedo Queue Logical Machine Identifier*

Identifier of the logical machine where the application queue space is located. Example:

SITE1

Table 49. Tuxedo Monitoring Agent Parameter Configuration Values (continued)

Field Description

Tuxedo


The sample screen below illustrates the command line prompts for the Tuxedo agent configuration. The previous table should be used for completing the prompts.

Starting or stopping Tuxedo agent using CandleAgent When using the command line to start or stop the Tuxedo agent, you should use the “-o” option to specify which Tuxedo system to monitor. The “-o” option is used to specify the three character Tuxedo Domain name. For example,

CandleAgent -o tx1 start | stop tx

where tx1 is the Tuxedo Domain Name.

For additional information on the CandleAgent command, see “CandleAgent” on page 120.

<vulcan:/users/longl/inst/didev/bin> ./CandleConfig -A -o tx1 txCandleConfig : installer level 350 / 220.CandleConfig : running aix513 jre.Agent configuration started...

Will this agent connect to a CMS? [YES or NO] (Default is: YES): CMS Host Name (Default is: vulcan):


Network Protocol [ip, sna, or ip.pipe] (Default is: ip):

Now choose the next protocol from one of these: - sna - ip.pipe - noneNetwork Protocol 2 (Default is: none): IP Port Number (Default is: 1918): 3141

Configure connection for a secondary CMS? [YES or NO] (Default is: NO): Enter Optional Primary Network Name or "none" (Default is: none): Tuxedo Version (6.5 or 7.x)(Default is: 6.5): Tuxedo Directory Path(Default is: /tuxedo/aix513): Tuxedo Config File Path(Default is: /tuxedo/aix513): Tuxedo Queue Name(Default is: null):Tuxedo Queue Config File Path(Default is: null):Tuxedo Queue Logical Machine Identifier(Default is: null): ... Writing to database file for tx.Agent configuration completed...


Universal Agent

Universal Agent

Editing um.configThe configuration file, um.config, allows you to modify Universal Agent and its Data Provider components for your environment. To edit the configuration file:

1. Change to the config directory:cd /$candlehome/config


2. Edit um.config with a text editor such as vi.

3. Add the variables and the values you want. You will need to refer to the Universal Agent User’s Guide for a complete list of the environment variables and how to set them.

4. Save the file. When you start Universal Agent using CandleAgent, the configuration is applied to the agent.

Using the API Server Data Provider with Universal Agent

If you are using the API Server Data Provider, you need to have the UA API client package on the same machine as the client program or the machine on which you are compiling the program. The UA API client package consists of the following:

� A library containing the binary executables of the API functions and containing export function definitions for linking customer-created API client applications

� A C header file

� A set of command line interface programs

The client package was developed in standard C language and it requires only a common C runtime environment and TCP/IP with a socket interface.

Universal Agent


To access the package, go to the \Candle\cma directory. Then copy the files in the table below to the target machine.

If the client program is sending data from a machine that is not the host of the data provider, or if you have changed the port on the host that the API server is listening on, set the environment variables below, as applicable. You may set these variables in the program or login script of the client host, or as part of the machine’s configuration:

KUMP_API_DPAPI_HOST

KUMP_API_DPAPI_PORT

Using the SNMP Data Provider with Universal Agent

The SNMP-MANAGER TRAP report contains information on traps received by the SNMP Data Provider. You must configure your SNMP agents to send traps to the host of the SNMP Data Provider to receive data in this report.

Table 50. API Client Packages

Part Name Description

KUMPAPI.h API C header file

KUMPAPI.lib API function export library file

KUMPAPI.dll API function runtime dynamic link library

KUMPBGNI dp_BeginInput console command

KUMPDEFN dp_Define console command

KUMPENDI dp_EndInput console command

KUMPINPT dp_InputData console command

KUMPPING dp_Ping console command

KUMPRDFN dp_Redefine console command

KUMPSHOW dp_ShowMessage console command

KUMPAREQ dp_AcceptRequest console command

KUMPRREQ dp_ReceiveRequest console command

KUMPRTDA dp_ReturnData console command


Universal Agent

Universal Agent GUI agent parameter configurationThe Manage Candle Services window provides an Advanced Agent Parameter dialog for Universal Agent. You can specify the data provider for the Universal Agent.

Procedure for advanced configuration

1. From the Manage Candle Services window, highlight “Universal Agent”.

2. From the menu, select “Actions > Configure > Agent Parameters”.

3. Select the radio button next to the Data Provider to specify.

4. Click OK.

Starting or stopping the Universal Agent using CandleAgentWhen you execute CandleAgent to start Universal Agent, you can include the following arguments as options in the command string:

� “ASFS” to start the consolidated Data Provider

� “APIS” to start the API Server Data Provider

� “FILE” to start the File Data Provider

� “POST” to start the Post Data Provider

� “SNMP” to start the SNMP Data Provider

� “SOCK” to start the Socket Data Provider

� “HTTP” to start the HTTP Data Provider

� “WBEM” to start the WBEM Data Provider

For examples:

CandleAgent -o SOCK start | stop um

CandleAgent -o FILE start | stop um

CandleAgent -o ASFS,SNMP start | stop um

If you start the agent without specifying an option, the Consolidated (ASFS) data provider or the variable KUMA_STARTUP_DP starts by default.

For more information about using CandleAgent, please see “CandleAgent” on page 120.

Universal Agent


Setting Universal Agent environment variablesSee the Universal Agent User’s Guide for a complete list of the environment variables and how to set them.

File Permissions required for Universal AgentFile permissions are normally set properly during the installation procedure if you entered the root password when prompted. If you encounter problems connecting with the Universal Agent, check to ensure that the following files have the file permissions set properly for Universal Agent to function properly:

� Kumsnetd

� Kumstrap

Setting file permissions

To set permissions for the Universal agent, follow the procedure under the following heading “File Permission Requirements” on page 93.

UNIX maximum files limitUNIX systems have a limit on the maximum number of open files a given process can have open. Opening TCP/IP sockets also count as open files. You can determine the maximum value on any UNIX system with the "ulimit -a" command.

The Universal Agent can attempt to open any number of TCP/IP sockets depending on the amount of work you have requested of it. For example, for every attribute group within every metafile, a socket gets opened. Other sockets are opened for other related work.

Most of the time these sockets get opened and closed within a short period of time and in some cases they remain open as long as a metafile is loaded. As you can see, the number of sockets open at any point in time can vary greatly. The maximum number of sockets a UNIX system allows open at any point in time affects the ability of the agent to do its work. When this happens, the agent will terminate with an error message in the RAS1 log.

For example, you are likely to encounter this situation if you try to import UA metafiles where the total attribute groups count exceeds 30 and the "ulimit -a" command shows a limit of 120 or less for "files open per process". If you encounter this, you have the following choices:


Universal Agent

� Increase the maximum files open per process limit. This typically requires UNIX Administration authority.

� Lower the amount of work you are requesting the UA to perform on that particular UNIX host. (Reduce the amount of metafiles being loaded in the UA.)

See “File descriptor (maxfiles) limit” on page 46.

Configuring multiple Universal AgentsYou can configure multiple instances of Universal Agent to run on the same node.

Configuring the agent (GUI)

To configure multiple instances of Universal Agent using in GUI mode, follow these steps:

1. From the Manage Candle Services window, select (highlight):Universal Agent

2. Right-click and select “Configure Advanced” from the drop-down menu.

3. Enter the Universal Agent instance name.

4. Be sure that “Create New Instance” is checked.

5. Click Configure.

6. Complete the Configure Universal Agent dialog; however, note that there is not provision to specify a “Host Specific” configuration.

7. Click Save.When you invoke the Universal Agent configuration dialog again, existing agents are displayed

8. You may change an existing agent’s configuration, or configure a new agent.

Starting the agent (GUI)

To start the agent, follow these steps.

1. Return to the Manage Candle Services window.

2. Select (highlight) the Universal Agent.

3. Click Start.

Universal Agent


This dialog opens:

4. Check “Universal Agent”.

5. Click Start.This dialog opens:

6. Select the instance from the list displayed. “Default” is the “No Instance” configuration (only one Universal Agent is configured on the local node).

Note: Once the instance is running, it no longer appears in the “Start Universal Agent” dialog until it has been stopped.

To stop the agent, select the agent and select “Stop Service”; then select the instance from the displayed list.


Universal Agent

Configuring the agent (command line)

To configure multiple instances of Universal Agent in command line mode, execute CandleConfig as follows:

CandleConfig -A -o instance um

This will result in a configuration file named um_instance.config. The binary specified is kuma410_instance. A copy of this binary is made from the main kuma410 binary during the execution of the CandleConfig script.

Note: The “-t” option to specify a "Host Specific" configuration should not be used, and if used will be ignored. Specifying an instance configuration overrides a "Host Specific" configuration.

Starting the agent (command line)

Execute CandleAgent as follows:

CandleAgent -o DataProvider -p instance start um

Note that in the CandleConfig script the instance is specified with the “-o” option, whereas in the CandleAgent script the instance is specified with “-p”. In the past when there were no instances, the CandleConfig script did not accept a “-o” option. The CandleAgent script accepted a “-o” option for DataProvider, but did not accept a “-p” option. In order to provide consistency with previous releases, the instance must be specified with “-p” when using CandleAgent to start Universal Agent.

As with the "No Instance" case, specifying the DataProvider is optional and if omitted, the DataProvider will be taken from the configuration data.

Stopping the agent

Execute CandleAgent as follows:

CandleAgent -p instance stop um

There is no need to use “-o” to specify the Data Provider when stopping the Universal Agent Instance.

UNIX


UNIX

Configuration for clustered environmentTo configure the UNIX monitoring agent for a clustered network environment, perform the general procedure for basic configuration of agents. (See “Basic Configuration of Agents” on page 88.) As you do this, in addition, complete the fields for Generic Host Name for Cluster Environment in the Configure UNIX OS Monitoring Agent dialog:

1. Select the box next to “Generic Host Name for Cluster Environment.”

2. Type in a hostname for the clustered environment (of your choosing) in the text box next to “Generic Hostname.” The name can be up to 64 alphanumeric characters long.

Setting file permissions on UNIX

Note: These tasks are only required if you have installed and did not enter the required root password during the normal installation procedure for monitoring agents for UNIX.

Once installed, some monitoring agents for UNIX executables require special privileges to run. You need to set these privileges for each agent for UNIX that you install.

To set permissions for the UNIX agent, follow the procedure under the following heading “File Permission Requirements” on page 93.


UNIX Logs

UNIX Logs

Setting agent parametersThe Manage Candle Services window provides an advanced Agent Parameter dialog for UNIX Logs Monitoring Agent. Follow the procedure below:

1. Highlight “UNIX Logs Monitoring Agent”.

2. Select “Actions > Configure > Agent Parameters”. A configuration dialog displays.

3. Enter the Hostname for the agent.

4. Click OK to save or Cancel to exit.

Setting permissions to read log filesFor the UNIX Logs Alert Agent to read some log files, the kulagent has to be run as a setuid program with an owner of root authority, for example, sulog. To set permissions for the UNIX Logs agent, follow the procedure under the following heading “File Permission Requirements” on page 93.

Customizing UNIX Logs Alert AgentFor additional information on how to customize the UNIX Log Alert Agent for your environment, see the OMEGAMON Monitoring Agents for UNIX User’s Guide (from the Candle documentation for superseded products).

WebSphere Application Server



This section contains instructions for configuring the WebSphere Application Server monitoring agent. At installation time, you will complete an initial configuration of the agent. You can reconfigure the agent at any subsequent time to customize its operation.

This section contains configuration information only for the basic parameters that allow you to successfully start the agent. Advanced configuration information is provided in the OMEGAMON XE for WebSphere Application Server User’s Guide.

To configure the WebSphere Application Server agent, follow these steps:

1. From the Manage Candle Services window, select (highlight): “WebSphere Application Server monitoring agent”.

2. Select “Actions > Configure > Agent Parameters”. A configuration dialog appears.

3. Set the parameters as described in the OMEGAMON XE for WebSphere Application Server User’s Guide.Note this special information about the “Agent ID” field:

4. Click Create when you have specified the required parameters.

5. Click Save.The configuration file is updated with your changes:

Table 51. Agent ID Field Description

Field Description

Agent ID A unique identifier for the WebSphere Application Server agent. You must specify an Agent ID if you intend to run multiple WebSphere Application Server agents on the same host system. The default configuration file is kwe.xml; however, if you specify an Agent ID in this field, the configuration process creates a unique configuration file for the WebSphere Application Server agent using the following naming convention: “kwe_agentID.xml”.

If you intend to run only one WebSphere Application Server agent on the host, you may leave this field blank.

Default: “ “(none)



$candlehome/config/kwe.xml

or

$candlehome/config/kwe_agentID.xml (if you specified an Agent ID).

You may reconfigure the agent at any time to customize its operation for your site. Consult the OMEGAMON XE for WebSphere Application Server User’s Guide for complete information.

Starting the agentThe WebSphere Application Server monitoring agent requires root authority to start the agent.

For details, see “UNIX Requirements” in the configuration section of the OMEGAMON XE for WebSphere Application Server User’s Guide.

Command line configurationTo configure or reconfigure the WebSphere Application Server monitoring agent from the command line, see “CandleConfig” on page 109. The product code for the WebSphere Application Server monitoring agent is “we”.

For further configuration information, see the OMEGAMON XE for WebSphere Application Server User’s Guide.

WebSphere InterChange Server



This section contains instructions for configuring the OMEGAMON XE for WebSphere InterChange Server monitoring agent to collect SNMP data from agents on server hosts and for changing the monitoring agent’s listening ports.

It also contains instructions for configuring a WICS Data Source to monitor a WebSphere InterChange Server log and send the data to the OMEGAMON XE for WebSphere InterChange Server monitoring agent, and for customizing the scripts the agent uses to start WebSphere InterChange Server instances.

Configuring the monitoring agentIn order to collect data from IBM SNMP agents, the monitoring agent must be configured with the host name, port number, and community name of each SNMP agent. You must also set the interval at which the monitoring agent will poll the SNMP agents.

Note: One of the IBM SNMP agents provided with WebSphere InterChange Server must be configured to monitor each server for which you want to collect data, and the OMEGAMON XE for WebSphere InterChange Server monitoring agent must be configured as its SNMP Manager. For instructions on configuring the IBM SNMP agents, please refer to to the section entitled "Using the SNMP Agent Configuration Manager" in Chapter 1 of the IBM WebSphere InterChange Server System Administration Guide.

GUI configuration

After the CMS and agent installations are completed, you are presented with the Manage Candle Services window. The Manage Candle Services window allows you to configure the individual installed components.

To configure the WebSphere Interchange Server monitoring agent:

1. Select (highlight) the WebSphere Interchange Server monitoring agent.

2. From the Action menu, select Configure.The Configure WICS Monitoring Agent window appears.

3. Select the Agent Parameters tab (if necessary).

4. For Poll Interval, specify in seconds the interval at which you want the monitoring agent to poll the IBM SNMP agents.



Specify an interval between 30 and 300 seconds (5 minutes).

5. For each IBM SNMP agent that you want to monitor, fill out the following fields:– For Host Name, specify the host name or IP address of the IBM SNMP

agent you want to monitor.

– For Port, specify the port to which the IBM SNMP agent is assigned.

By default, the port used by SNMP agents is 1161.

– For Community, specify the name used to contact the agent.

If you do not specify a community name, the default community name Administrator is used.

6. Click Save to close the window and configure the monitoring agent.Once you have initiated data collection, you do not need to start it again each time you start the monitoring agent. The agent maintains information about monitored IBM SNMP agents in a configuration file so that data collection will persist across restarts.

You can add additional SNMP agents, or stop monitoring for particular agents, at a later date, using Manage Candle Services. For more information, see the OMEGAMON XE for WebSphere InterChange Server Getting Started Guide.

Command line configuration

When configuration of the agent-to-CMS connection is completed, you will see the following:

*********************************************************

Define IBM SNMP agent locations, enter "/exit" when done:

*********************************************************

-> IBM SNMP agent location:

SNMP host(Default is: default):

1. At the prompt, enter the name of the host of an SNMP agent monitoring a WebSphere InterChange Server you want to monitor.You will see the following prompt:

SNMP port number(Default is: 1161):

2. Enter the port number for the SNMP agent. By default, this is 1161.



You will see the following prompt:

SNMP community name (Default is: Administrator):

3. Enter the community name used to connect to the SNMP agent. If you do not specify a community name, the default administrator is used.

4. When you have supplied the host name, port number, and community name for every SNMP agent you want to monitor, enter “/exit”.

Changing the monitoring agent listening portsThe OMEGAMON XE for WebSphere InterChange Server monitoring agent uses two listening ports to communicate with the WICS Data Sources. By default, the values for these two ports are 17600 and 17700. If one or both of these ports is already in use, you must specify an alternative value in the agent’s configuration file.

Note: Candle recommends that you do not change these ports unless absolutely necessary. You should back up the current .ini file before you make any changes to it.

To change the listening ports, use a text editor to edit the ic.ini file located in $candlehome/config where $candlehome is the directory where OMEGAMON XE for WebSphere InterChange Server is installed.

Edit one or both of the following variables, as necessary:

KUMP_API_DPAPI_PORT=17600

KUMP_DPCONSOLE_PORT=17700

If you edit these variables, you must specify the same values in the configuration file for every data source that sends data to the monitoring agent (see “Configuring a data source” on page 210).

Configuring a data sourceTo connect to the OMEGAMON XE for WebSphere InterChange Server monitoring agent, each WebSphere InterChange Server Data Source must be configured with the following information:

� the host name of the monitoring agent

� the data port of the monitoring agent

� the console port of the monitoring



In addition, the data source needs to know:

� the name of the WebSphere InterChange Server instance whose log it monitors

� the name and location of the server log it is monitoring

By default, the monitoring agent uses two listening ports for communicating with WebSphere InterChange Server Data Sources:17600 and 17700. If one or both of these ports is already in use, you must specify an alternative value in the agent’s configuration file, ic.ini, and specify those same port values when you configure each data source.

GUI configuration

After installation of a WebSphere InterChange Server Data Source is completed, the Manage Candle Services window opens.

1. Select (highlight) the WebSphere InterChange Server Data Source and select Action > Configure.The Configure WebSphere InterChange Server Data Source window appears.

2. If necessary, select the Agent Parameters tab and fill out the fields as follows:– For Agent Host field, specify the name of the host on which the

monitoring agent is executing.

– (optional) For Data Port, specify the value of the KUMP_API_DPAPI_PORT variable in the monitoring agent’s ic.ini file.

– (optional) For Console Port, specify the value of the KUMP_DPCONSOLE_PORT variable in the monitoring agent’s ic.ini file.

– For Server base directory, enter the fully qualified name of the WebSphere InterChange Server base directory. For example:

/IBM/WebSphereICS

– For Server Log File Name, enter the path to the WebSphere InterChange Server log, relative to the base directory. For example:

InterChangeServer.log

– For Server ID, enter the name of the WebSphere InterChange Server instance that owns the log.



3. Click Save to close the window and configure the WebSphere InterChange Server Data Source.

Command line data source configuration

After installation of the data source is completed, you will see the following:

*********************************************************

Define the location and ports for the OMEGAMON XE for WebSphere InterChange Server monitoring agent:

*********************************************************

-> OMEGAMON XE for WebSphere InterChange Server monitoring agent:

Monitoring agent host(Default is: default):

1. At the prompt, enter the name of the host of the OMEGAMON XE for WebSphere InterChange Server monitoring agent.You will see the following prompt:

Data port (Default is: 17600):

2. Enter the number of the port on which the WebSphere InterChange Server Data Source should check for the monitoring agent. By default, this is 17600. If you have not changed the default ports for the monitoring agent, accept the default. If you have changed the default, specify the value of the KUMP_API_DPAPI_PORT variable in the monitoring agent’s ic.ini file.


Console port (Default is: 17700):

3. Enter the number of the port to which the WebSphere InterChange Server Data Source should sent the log data. By default, this is 17700. If you have not changed the default ports for the monitoring agent, accept the default. If you have changed the default, specify the value of the KUMP_CONSOLE_PORT variable in the monitoring agent’s ic.ini file.


Server base directory :

4. Enter the fully qualified name of the WebSphere InterChange Server base directory. For example:



/IBM/WebSphereICS


Server log file name:

5. Enter the path to the server log, relative to the base directory. For example: InterChangeServer.log


Server ID:

6. Enter the name of the WebSphere InterChange Server instance that owns the log.You will see the message:

Agent configuration completed...

Configuring server startup One of the features of OMEGAMON XE for WebSphere InterChange Server is the ability to start a WebSphere InterChange Server from the CNP using a Take Action command. This feature is only available if you perform the following steps:

1. After you've installed and configured the Data Source, determine the user ID used to manage the WebSphere InterChange Server (for example, cwadmin).

2. Log on using any ID with root authority.

3. Navigate to the Data Source directory $candlehome/arch/ie/bin (where arch is the abbreviation for the operating system architecture—for example,AIX516).

4. Change the user ID for all the files to the user ID used to manage the WebSphere InterChange Server:

chown <UserID> *

5. Activate the Set UserID characteristic of the files:chmod u+s *

6. Logoff from the root user ID.

OMEGAMON XE for WebSphere InterChange Server uses a script to execute the Take Action Start Server command. If you want to issue other commands (for example, start the persistent naming server) or run other scripts before starting the server, you can modify this file.



The file is named Start<ServerName>.Sh. It is located on the server host in $CANDLEHOME/arch/ie/bin, where $CANDLEHOME is the base directory in which the OMEGAMON XE for WebSphere InterChange Server Data Source is installed and arch is the abbreviation used to represent the operating system architecture (see “Candle Architecture Codes” on page 257).

The file contains a single line similar to the following:

<Path>/bin/ics_manager -u $1 -p $2

To edit the file:

1. On the server host, open the file in a text editor.

2. Insert any commands you want to add before the existing line.

3. Save and close the file.You must edit the file on the host of each server you want to affect, or copy the edited file to the bin directory of each host.

Starting and stopping the agent and data sourcesTo start the agent and the data sources, use Manage Candle Services for a GUI installation (see “Manage Candle Services” on page 85) and CandleAgent for a command line installation (“CandleAgent” on page 120).

The product code for the monitoring agent is “ic”. The code for a WebSphere InterChange Server Data Source is “ie”.

Starting and Stopping Candle Products 215

Starting and StoppingCandle Products

IntroductionThis chapter describes the commands used to start and stop Candle products along with managing Log files from the GUI interface. The easiest way to start and stop Candle products is to use the c window.

If you prefer to use the command line, you will find a complete description of the syntax, options, and arguments used to start and stop the CMS and agents in “Command Line Installation Steps” on page 99. Selected products also contain start and stop command line syntax in the chapter “Additional Agent Configuration” on page 153.

Note: On UNIX, if you reconfigure a Candle product that is currently started, you must manually stop and restart the component before any changes are implemented.

Chapter contents

Using the Manage Candle Services Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216

Verifying Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220CMS Shut Down Using IP.PIPE Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

7

Using the Manage Candle Services Window



OverviewThe Manage Candle Services window is available for starting, stopping, and configuring the OMEGAMON XE components.

Starting the Manage Candle Services windowTo start the interface:


2. Type the following and press “Enter”.CandleManage [-h $candlehome] [-s]

where:

Table 52. Parameters for the Commands to Start the Manage Candle Services Window

-h (optional) An option used to specify $candlehome.

$candlehome The home directory created for OMEGAMON XE.






The Manage Candle Services window displays.

Starting or stopping componentsTo start or stop components:

1. Highlight the component to start or stop.

2. Do one of these:� Click the “Go” (Green) light or “Stop” (Red) light on the menu bar.

� From the menu bar, select “Actions > Start Service” or “Stop Service”.

Authority required for the Tuxedo monitoring agent on UNIXOn a UNIX system, only the Tuxedo Administrator can start (or stop) the Tuxedo monitoring agent. The TX agent can only be brought up or down by the same User ID and password that booted the TUXEDO domain.

Because Candle products are installed on UNIX systems using a Candle account, it is necessary to change the permissions on the $candlehome directory so that the Tuxedo Administrator has access to files associated with the Tuxedo monitoring agent (such as logs). Change the permissions as follows:

1. Log on using the Candle account you used to install the agent.



2. Change to the $candlehome directory.

3. Issue the following command:chmod o+w *

If the user ID is part of the “candle” user group, issue the following command

chmod g+rwx *

Managing log filesLog files are created as a standard action when starting agents and the CMS. You can manage log files using the Manage Candle Services Options menu. Use the procedure below to manage Log files:

1. From the Manage Candle Services Main menu, select “Options > Manage Log Files”. The Manage Log Files dialog displays.

The Manage Log Files dialog allows you to:

� Delete files.

� Delete files older than xx days (you can specify a time period, 0 or more).

� Trim files to xxxx Kbytes (you can specify a file size, 0 or more). Trimming starts from the top of file (oldest entries first).



Note: The command line version of “Managing Log Files” is CandleAudit. See “CandleAudit” on page 122.

Closing the Manage Candle Services window

1. To close the Manage Candle Services window, click the red X in the right corner of the window.

Verifying Processes


Verifying Processes

IntroductionAs you start and stop components of the OMEGAMON XE, you may want to verify that the processes associated with that component started or stopped successfully. To do so, check for the existence of log files. You can check for log files using the Manage Log Files option from the Manage Candle Services window (see “Managing log files” on page 218).

Log filesWhen a process is started a log file is created to record the activity of the process. When the component stops, using the appropriate command, the log is saved as part of the normal shut down process.

Note: When you issue most Candle commands, you can set the -l option to delete the log unconditionally.

Log file naming format

In the past, log file names were based on the process ID (pid) of the process, for example, zola_ux_47598.log. Due to several technical issues, this naming convention was not working with the desired results. Therefore, a naming convention was instituted using a time stamp to uniquely identify the log file. This results in a long number at the end of the log file name which is actually an encoded time stamp.

Additionally, you will notice that there are actually two files generated for each execution of an agent, for example:

zola_ux_952453434.log

zola_ux_952453434.pid47598

The second (empty) file is generated to link the date and time stamp with the real process ID of the agent. This allows you to easily identify the true log file for a particular process by completing a simple “ls” command.

Verifying that the command executed successfullyTo verify that the process or executable associated with the component has started or stopped, look for a log file:


Verifying Processes

1. Change to the $candlehome/logs directory.

2. List the files in the directory.

3. Look for the appropriate log file. The name should mirror that of the corresponding log file:

host_pc_timestamp.log

where:

If there is not a log file, either:

� The process never started.

� The “-l” option was used to delete the log.

4. Check the contents of the log for more information.

Note: If the process stopped abnormally, the CandleAgent or CandleServer “STOP” command must still be issued to clean up left over records in the installer database.

Table 53. Parameters of Log File Name

host is the hostname of the system where the process is running.

pc is the two-character product code.

timestamp is a dynamically assigned time and date stamp number.

CMS Shut Down Using IP.PIPE Protocol


CMS Shut Down Using IP.PIPE Protocol

OverviewOn all CMS-supported platforms, outside clients connected using the IP.PIPE protocol may not immediately release the TCP port number on the CMS host machine after the CMS is shut down. This behavior may cause a hub or remote CMS to disable their IP.PIPE brokers upon startup because the TCP port is "in use". This is due to the fact that when TCP closes a TCP connection, it sends a final Acknowledgment (ACK). In order for that ACK to be sent, the TCP port remains in use and under a specific status; for example, the "TIME_WAIT", "FIN_WAIT" or "CLOSE_WAIT" for twice the Maximum Segment Lifetime (2 x MSL). After the Maximum Segment Lifetime (2 x MSL) time, the TCP port numbers are automatically released and can be used by the CMS's IP.PIPE brokers. Depending on how TCP/IP is set up on your machine determines how long you will have to wait until you can restart the hub or remote CMS to utilize the IP.PIPE brokers. This may require that you configure TCP/IP to change the MSL value.

If you have a problem restarting, you can execute the following command to return a list of any and all clients (and their state) using the IP.PIPE port number <port#>. If the command returns an empty list, then the hub or remote CMS can be restarted using the IP.PIPE port number for its brokers.

On UNIX, use the following from the command line

netstat -a|grep <port#>

On Windows, open a DOS window and use

netstat -a|find “<port #>”

On OS/390 or z/OS (from a TSO prompt) use

TSO NETSTQ search_string (no count needed or used)

CMS using IP.PIPE running on HP-UXSee the requirements chapter under “IP.PIPE patch for HP-UX” on page 44.

CandleClone Command 223

CandleClone Command

IntroductionCandleClone is a new optional command for migration of agents to remote systems. This program allows you to “clone” or copy existing installed Candle products into packages for installation on remote systems. This command compliments the functions performed by CandleRemote. CandleClone is started from the command line and offers you the choice of using a GUI interface or command line interface.

Chapter contents

Differences between CandleClone and CandleRemote . . . . . . . . . . . . . . . . . . . . 224

CandleClone Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226Using CandleClone in GUI Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227Using CandleClone in Command Line Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

9

Differences between CandleClone and CandleRemote



SummaryThe table below is a summary of the differences between the two commands.

Note: This table compares CandleClone with the new CandleRemote command.

Limitations and Requirements for using CandleCloneThe following limitations exist in this release of the CandleClone command.

� Root permissions are not maintained unless you are running as “root”. Before using a cloned environment for the first time, you will need to run SetPerm to establish the correct file permissions in the cloned environment.

Table 54. Difference Summary Between CandleClone and CandleRemote

CandleClone CandleRemote

You select from the installed products in $candlehome

You select products including CMSs contained on the Candle product CD-ROM.

Creates a cloned package (tar file) containing the selected products. This package consists of a fully-configured $candlehome directory structure.

Creates a remote package (tar file) containing a CD-ROM image (*.jar files) of the products selected.

Transfers and unloads the cloned package on remote machines you specify.

Transfers the tar file to the remote machines you specify.

Once the tar file is unloaded, the Candle environment is ready to use. No installation or configuration is required.

After the transfer, you must log into each remote machine and untar the remote package. This creates a CD-ROM image on the remote machine. You must then install and configure the products from this image using install.sh.

Only agents can be cloned; you cannot clone a CMS.

Agents and CMSs can be contained in the CD-ROM image created.



Note: The SetPerm command will be found in the /$candlehome/bin directory on the remote machine. See “Procedure to set file permissions” on page 93.

� You cannot clone a CMS.

� The transfer operation does not check the available disk space on the receiving (remote) machines. It is your responsibility to ensure that the required disk space exists on the remote machines. Remember that space is needed for both the tar file and the final cloned products.

� The transfer and installation procedure relies on the UNIX commands “rcp” and “remsh”. It is your responsibility to ensure that the remote machine does not prompt for a password when CandleClone attempts a transfer and installation. If a password is required, the transfer will fail or hang.

CandleClone Command


CandleClone Command

OverviewCandleClone is started from the UNIX command line. The procedure that follows illustrates the GUI screen images with an explanation of the information required to complete the screen fields.

Command line prompts follow the GUI screen procedures for using CandleClone.

SyntaxThe syntax is:

CandleClone [-h $candlehome] [-c] [-s]

Table 55. Options for CandleClone Command

-h (optional) Option used to specify the $candlehome directory of the local host machine from which you are running CandleClone

-c (optional) Option to specify printing diagnostic messages to the console.


Safe mode invokes the Java Runtime Environment (JRE) with the "-nojit" option (no just-in-time compiler). If you encounter a java failure error, try running the command as before, but also specifying the "-s" option. This appears to solve at least some random java exceptions that occur on a small number of machines.


Table 56. Arguments for CandleClone Command

$candlehome Use with the -h option to specify the location of $candlehome on the local host machine.


Using CandleClone in GUI Mode


Procedure to start CandleCloneUse the following procedure to start and use the CandleClone command:

1. From the UNIX prompt, change to the $candlehome/bin directory

2. Type ./CandleClone [-h $candlehome] [-c] [-s]


3. Select one of the options presented by entering the number at the prompt and press “Enter”.

4. Type 1


Table 57. Options for Starting CandleClone

1 Clone/Transfer products in GUI mode.

2 Clone/Transfer products in command-line mode.

3 Exit this program.



The following screen is presented.

You can create a clone “env” or transfer (Trans) a previously created clone package. (See “Transferring or installing an existing “package” from a previous clone” on page 229.)

Cloning installed products

1. Select the operating system from the list box. (To view other operating systems, click the right-hand down arrow.)

2. Select the installed products to include in the cloned environment. Click Select All to choose all listed products.

3. Click Clone.If you clicked Clone, you must specify the cloning options.



The following Set Clone Options screen is presented.

4. Complete the field information using the descriptions provided in the table below:

5. Click OK to create the tar file. This file can then be sent to and installed on remote machines using the transfer (“Trans”) option. After the tar file is created you are returned to the screen presented on the previous page.

Transferring or installing an existing “package” from a previous clone

1. Press “Trans” (you do not have to select any products) to transfer and install an existing env contained in a tar file created during a previous clone operation.

Table 58. CandleClone – Set Clone Options Fields and Descriptions

Field Description

Target CandleHome Directory Enter the name of the remote directory into which the cloned environment will be installed.

Tar File Name Enter the name of the tar archive which will contain the cloned environment.



The following CandleClone Specify Receiving Locations screen is presented.

2. In the Tar File Name field, specify the tar file you want to transfer.

3. In the Host Name column, specify where (on what machines) you want to install the cloned environment. You can enter up to 20 remote machines on which to clone the environment.

4. In the Work Directory column, enter the temporary work directory to send the tar archive file on the remote machine.

5. Click OK, and the cloned environment is automatically installed into the Target CandleHome Directory on the remote machines.

6. Click Clear to delete all entries in the table. Click Cancel to cancel the “Trans” operation and return to the previous screen.

Note: See “Limitations and Requirements for using CandleClone” on page 224 for user requirements in using CandleClone.


Using CandleClone in Command Line Mode


Procedure to start CandleCloneUse the following procedure to start and use the CandleClone command:


2. Type CandleClone [-h $candlehome] [-c] [-s]



4. Type 2



6. Select one of the options. (The prompts for Option 3 are shown below, since this option executes both Option 1 and Option 2.)

7. Type 3

Table 59. Options for Starting CandleClone

1 Clone/Transfer products in GUI mode.

2 Clone/Transfer products in command-line mode.


Table 60. Options for Starting CandleClone in Command Line Mode

1 Clone an environment.

2 Transfer/Install a tar file.

3 Clone an environment and transfer/install a tar file.





8. Select an operating system from the menu that appears. Type the number and press “Enter”. You are asked to verify the operating system. Type

y


9. Select the products for the operating system, and confirm your selections.

10. At this point, you can select products for another operating system. After you have made all your selections, enter the options for the cloned environment (env). These options are described in Table 58: CandleClone – Set Clone Options Fields and Descriptions on page 229.

11. Specify where (on what machines) you want to install the cloned env. The Host name and Work Directory fields are described under “Transferring or installing an existing “package” from a previous clone” on page 229. The cloned env is then installed into the Target CandleHome Directory on each host that you specified.

CandleRemote 233

CandleRemote

IntroductionThis chapter describes the newly revised CandleRemote optional program that allows you to create packages of Candle products for installation on remote systems. These packages are created from the Candle product CD-ROM. The CandleRemote option can be completed in either GUI or command line mode.

To create remote packages of Candle products that have already been installed, see “CandleClone Command” on page 223.

Chapter contents

Differences between CandleRemote and CandleClone . . . . . . . . . . . . . . . . . . . . 234

CandleRemote Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236Using CandleRemote in GUI Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238Using CandleRemote in Command Line Mode . . . . . . . . . . . . . . . . . . . . . . . . . . 242

8

Differences between CandleRemote and CandleClone



SummaryThe table below is a summary of the differences between the two commands.

Note: This table compares CandleClone with the new CandleRemote command.

Limitations and requirements for using CandleRemoteThe following limitations exist in this release of the CandleRemote command.

� The transfer operation does not check the available disk space on the receiving (remote) machines. It is your responsibility to ensure that the required disk space exists on the remote machines. Remember that space is needed for both the tar file and the final cloned products.

Table 61. Difference Summary Between CandleRemote and CandleClone

CandleRemote CandleClone

You select products including CMSs contained on the Candle product CD-ROM.

You select from the installed products in $candlehome

Creates a remote package (tar file) containing a CD-ROM image (*.jar files) of the products selected.

Creates a cloned package (tar file) containing the selected products. This package consists of a fully-configured $candlehome directory structure.

Transfers the tar file to the remote machines you specify.

Transfers and unloads the cloned package on remote machines you specify.

After the transfer, you must log into each remote machine and untar the remote package. This creates a CD-ROM image on the remote machine. You must then install and configure the products from this image using install.sh.

Once the tar file is unloaded, the Candle environment is ready to use. No installation or configuration is required.

Agents and CMSs can be contained in the CD-ROM image created.

Only agents can be cloned; you cannot clone a CMS.

CandleRemote 235


� The transfer and installation procedure relies on the UNIX commands “rcp” and “remsh”. It is your responsibility to ensure that the remote machine does not prompt for a password when CandleRemote attempts a transfer and installation. If a password is required, the transfer will fail or hang.

Note: The operation of the new CandleRemote is different from that of the prior version, so custom shell scripts used to invoke the prior CandleRemote command will not work with the new one.

CandleRemote Command



OverviewCandleRemote is started from the UNIX command line. The procedure that follows illustrates the GUI screen images with an explanation of the information required to complete the screen fields.

Command line prompts follow the GUI screen procedures for using CandleRemote.

Note: CandleRemote can also be started from install.sh. For the CandleRemote prompts in install.sh, see Table 11, “install.sh Prompts for Install Type to Use,” on page 78.

SyntaxThe syntax is:

CandleRemote [-h $candlehome] [-d CD-ROM path] [-c] [-s]

Table 62. Options for the CandleRemote Command

-h (optional) Option used to specify the $candlehome directory of the local host machine from which you are running CandleClone

-d An optional parameter used to specify the path to the root of the CD-ROM drive.

-c (optional) Option to specify printing diagnostic messages to the console.


Safe mode invokes the JRE with the "-nojit" option (no just-in-time compiler). If you encounter a java failure error, try running the command as before, but also specifying the -s option. This appears to solve at least some random java exceptions that occur on a small number of machines.

Entering the above commands with "-?" displays the syntax for using the -s option.

Table 63. Arguments for the CandleRemote Command

$candlehome Use with the -h option to specify the location of $candlehome on the local host machine.

CandleRemote 237


CD-ROM path The full path to the root of the CD-ROM drive or the full path to the CD-ROM image.

Table 63. Arguments for the CandleRemote Command (continued)

Using CandleRemote in GUI Mode



Procedure to start CandleRemoteUse the following procedure to start and use the CandleRemote command:


2. Type ./CandleRemote [-h $candlehome] [-d CD-ROM path] [-c] [-s]


3. Select “1” from the options presented by entering the number at the prompt, and press “Enter”.

Table 64. Options for Creating Remote Packages

1 Create remote packages using GUI.

2 Create remote packages using command line.


CandleRemote 239


The following Candle Remote Packages dialog is presented.

You can create (“Create”) a remote package or transfer (“Trans”) a previously created package. (See “Transferring a remote package” on page 240.)

Creating a remote packageTo create a remote package, use the following procedure

1. Select the operating system from the list box. (To view other operating systems, click the right-hand down arrow.)

2. Select the products to include in the package. Click the Select All button to choose all listed products.

3. Click Create.The Set Packaging Options dialog prompts you for a Tar File Name.

4. Enter the name of the tar archive that will contain the remote package.

5. Click OK to create the tar file. You are returned to the Candle Remote Packages dialog.



Transferring a remote packageTo transfer a tar file, use the following procedure:

1. Press “Trans” (you do not have to select any products) to transfer and install a previously created tar file and complete the following Specify Receiving Locations dialog.

2. In the Tar File Name field, specify the tar file you want to transfer.

3. In the Host Name column, specify where (on what machines) you want to install the remote packages. You can enter up to 20 remote machines on which to transfer the remote package.

4. In the Work Directory column, enter the temporary work directory to send the tar archive file on the remote machine.

5. Press OK, and the tar file is automatically copied to the work directory on the remote machines.

6. Once the file is copied, you must log into each remote machine and untar the remote package. This creates a Candle CD-ROM image on the remote machine. You can then install and configure products from this image using install.sh.

CandleRemote 241


Note: The “-d” option for install.sh should now point to the CD-ROM image location on the remote machine.

7. Click Clear to delete all entries in the table. Press Cancel to cancel the “Trans” operation and return to the previous screen.

Note: See “Limitations and requirements for using CandleRemote” on page 234 for user requirements in using CandleClone.

Using CandleRemote in Command Line Mode



Procedure to use CandleRemote from the command lineUse the following procedure to start and use the CandleRemote command in command line mode:


2. Type ./CandleRemote [-h $candlehome] [-d CD-ROM path] [-c] [-s]


3. Select “2” from the options presented by entering the number at the prompt, and press “Enter”.

4. Select one of the options from the menu that appears.

(The prompts for Option 3 are shown below, since this option executes both Option 1 and Option 2.)

5. Type 3


6. Select an operating system from the menu that appears. Type the number and press “Enter”. You are asked to verify the operating system.

Table 65. Options for Creating Remote Packages

1 Create remote packages using GUI.

2 Create remote packages using command line.


Table 66. Options for Creating Remote Packages in Command Line Mode

1 Create a remote package (tar file).

2 Transfer a remote package.

3 Create a remote package, and transfer it.


CandleRemote 243


7. Typey


8. Select the products for the operating system, and confirm your selections.

9. At this point, you can select products for another operating system. After you have made all your selections, enter the tar file name for the remote package.

10. Specify where (on what machines) you want to install the remote packages. The Host Name and Work Directory fields are described under “Transferring a remote package” on page 240. You can specify up to 20 Host/Work Directory pairs for transferring the remote packages.

11. After the file has been transferred, you must log into each remote machine and untar the remote package.

12. Perform a regular installation on the remote machine using install.sh.

Note: The “-d” option for install.sh should now point to the CD-ROM image location on the remote machine.



Multi-platform Installation Configuration Files 245

Multi-platformInstallation Configuration Files

IntroductionThis appendix discusses the configuration files used by the new UNIX multi-platform installation program. The configuration files can be modified to customize your installation.

Appendix contents

Multi-platform Installation Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Configuration File Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247

A

Multi-platform Installation Program


Multi-platform Installation Program

OverviewThe old UNIX installer stored configuration information in the application code, for example, CandleNet® Commands, and in external files. Values for environmental variables (needed by the agents) were then derived at runtime from this information. Since configuration data was stored in multiple locations, it was not clear what data were assigned to the variables. Additionally, configuration information could only be changed, separate from installation, by manually editing the various files.

The new UNIX installer removes configuration information from the application code and stores the information in external files that are logically linked. It is obvious what information is being assigned to the environmental variables. With the linking of files, both basic and complex environments are supported. A basic or default agent to CMS configuration is presented when the agent configuration process is started. An advanced configuration tab is available to configure more complex environments.

Configuration information is generated from and stored in the following file types:

� User-Input

� Template

� Custom-Configuration


Configuration File Types


User-Input typeA User-Input file is generated automatically from information entered by the user, whether in dialogs or at the command line. The user-input data is stored in a database for reconfiguration. User-Input files are named according to the format:

kxxenv

where xx is the 2-letter product code; for example,

kumenv

for the Universal Agent.

Template typeTemplate files are shipped in the ./config directory and installed in $candlehome/config. These files contain all of the possible environmental variables for a product. Template files are edited manually, only when a variable needs to be added permanently to the environment. Each variable value (for example, “CANDLEHOME”), that will be replaced from the user-input file, needs to be surrounded by the “$” character as seen in the example below. These variable values keywords are not reserved words, but rather must match the keyword in the user-input file. For example, the keyword “$CELLNAME$” can be replaced with “$CMSNAME$” as long as the user-input file contains: “CMSNAME=’CANDLE’”.

Template files are named according to the format:

{2-letter product code}.ini (e.g. um.ini for the Universal Agent)

The Template and User-Input files are used to generate a Custom-Configuration file for a product.

Note: Any customization done to the .ini files will be overwritten when the products is upgraded or reinstalled. Candle suggests that you keep a backup of any .ini files that you customize.

Sample template file

The contents of a sample um.ini file follows.

# ===========================================



# Generic Settings # ===========================================KGL_KGLMSGBASE=$CANDLEHOME$/$BINARCH$/bin/KGLMSENUATTRLIB=$CANDLEHOME$/$BINARCH$/$PRODUCTCODE$/tables/ATTRLIBCT_CMSLIST=$NETWORKPROTOCOL$:$HOSTNAME$;$HSNETWORKPROTOCOL$$MIRROR$CTIRA_HIST_DIR=$CANDLEHOME$/$BINARCH$/$PRODUCTCODE$/histCTIRA_LOG_PATH=$CANDLEHOME$/logsKBB_RAS1=ERRORKDC_FAMILIES=$NETWORKPROTOCOL$LD_LIBRARY_PATH=$CANDLEHOME$/$ARCHITECTURE$/$PRODUCTCODE$/lib:

$CANDLEHOME$/$ARCHITECTURE$/libLIBPATH=$CANDLEHOME$/$ARCHITECTURE$/$PRODUCTCODE$/lib:$CANDLEHOME$/

$ARCHITECTURE$/libPATH=/usr/bin:$CANDLEHOME$/$BINARCH$/$PRODUCTCODE$/bin:$CANDLEHOME$/

$BINARCH$/bin:$CANDLEHOME$/$ARCHITECTURE$/$PRODUCTCODE$/lib:$CANDLEHOME$/$ARCHITECTURE$/lib:$CANDLEHOME$/$ARCHITECTURE$/bin

SHLIB_PATH=$CANDLEHOME$/$ARCHITECTURE$/$PRODUCTCODE$/lib:$CANDLEHOME$/$ARCHITECTURE$/lib

SQLLIB=$CANDLEHOME$/tables/cicatrsq/SQLLIBKDCB0_HOSTNAME=$HOSTNAME$KDC_PARTITION=$KDC_PARTITIONNAME$# ============================================= # Agent Specific Settings # =============================================KBB_RAS1=ERROR > $CANDLEHOME$/tables/ua.logKUM_DCH_HOSTNAME=$HOSTNAME$KUM_WORK_PATH=$CANDLEHOME$/tables/workKUMA_STARTUP_DP=$DATAPROVIDER$KUMP_DCH_HOST=$HOSTNAME$KUMP_INIT_CONFIG_PATH=$CANDLEHOME$/tables/workKUMP_META_PATH=$CANDLEHOME$/tables/work/mdlKUMP_SNMP_DEBUG_TRAP=N KUMP_SNMP_DEBUG_DISCOVERY_ROUTE=NKUMP_SNMP_DEBUG_DISCOVERY_ENTERPRISE=NKUMP_SNMP_DEBUG_DISCOVERY_NETWORK=NKUMP_SNMP_DEBUG_MIB_MANAGER=NKUMP_SNMP_DEBUG_MIB_IO=N KUMP_META_SERVER=$SERVERHOST$ KUMP_SNMP_MONITOR_TRAP=Y KUMP_SNMP_NET_DISCOVERY=Y KUMP_SNMP_NET_DISCOVER_ENTERPRISE=Y #============================================= # Install Specific Settings # =============================================COMMAND=kuma410

Custom-Configuration typeAll variables (those surrounded by the dollar (“$”) sign) in the Template file are replaced with their values from the User-Input file to create a



Custom-Configuration file. This file is generated automatically if it doesn’t already exist during the configuration of an agent or CMS. Custom-Configuration files can be edited by the user using the Advanced option in the installer. These files are named according to the format:

Agent

{2-letter product code}.config

CMS

Host_ms_cmsname.config

Example

The UNIX agent configuration file would be

ux.config

Sample um.config file

The contents of a sample um.config file follows:

#!/bin/kshKGL_KGLMSGBASE='/users/admin/candle/aix513/bin/KGLMSENU'ATTRLIB='/users/admin/candle/aix513/um/tables/ATTRLIB'export CT_CMSLIST='ip:ddlah1x5e'CTIRA_HIST_DIR='/users/admin/candle/aix513/um/hist'CTIRA_LOG_PATH='/users/admin/candle/logs'KBB_RAS1='ERROR'KBB_SIG1='-dumpoff -asyncoff'export KDC_FAMILIES='ip port:1918 ip.pipe use:n sna use:n'LD_LIBRARY_PATH='/users/admin/candle/aix513/um/lib:/users/admin/candle/aix513/lib:

/users/admin/candle/aix513/lib:/usr/ucblib'LIBPATH='/users/admin/candle/aix513/um/lib:/users/admin/candle/aix513/lib:/users/a

dmin/candle/aix513/lib'PATH='/usr/bin:/users/admin/candle/aix513/um/bin:/users/admin/candle/aix513/bin:/u

sers/admin/candle/aix513/um/lib:/users/admin/candle/aix513/lib:/users/admin/candle/aix513/lib:/users/admin/candle/aix513/bin:/usr/ucblib'

SHLIB_PATH='/users/admin/candle/aix513/um/lib:/users/admin/candle/aix513/lib:/users/admin/candle/aix513/lib'

SQLLIB='/users/admin/candle/tables/cicatrsq/SQLLIB'KDC_PARTITION=''KUM_WORK_PATH='/users/admin/candle/aix513/um/work'KUMA_STARTUP_DP='ASFS,HTTP'KUMP_INIT_CONFIG_PATH='/users/admin/candle/aix513/um/work'KUMP_META_PATH='/users/admin/candle/aix513/um/metafiles'KUMP_SNMP_DEBUG_TRAP='N'KUMP_SNMP_DEBUG_DISCOVERY_CANDLEAGENT='N'KUMP_SNMP_DEBUG_DISCOVERY_ROUTE='N'KUMP_SNMP_DEBUG_DISCOVERY_ENTERPRISE='N'



KUMP_SNMP_DEBUG_DISCOVERY_NETWORK='N'KUMP_SNMP_DEBUG_MIB_MANAGER='N'KUMP_SNMP_DEBUG_MIB_IO='N'KUMP_SNMP_MONITOR_TRAP='Y'KUMP_SNMP_NET_DISCOVERY='Y'KUMP_SNMP_NET_DISCOVER_CANDLEAGENT='N'KUMP_SNMP_NET_DISCOVER_ENTERPRISE='N'KIB_MAXCOLS='127'COMMAND='kuma410'’

Additional configuration file supportTo maintain configuration flexibility as implemented in the current installer, the following *.config files are also supported:

The order in which the files are read is from the most general to the most specific.

pc.config is created during agent configuration and Host_ms_cmsname.config is created during CMS configuration. The other .config files can be created and edited manually.

Table 67. Additional Configuration Files Supported

File Name Description

host_pc.config Read by a specific product on a specific system (host)

host_pc_opt.config Read by a specific product on a specific system using a specific option (opt)

env.config A configuration file that is used to store any environment variables applicable to all agents and the CMS. File is located in the $candlehome/config directory

mq.cfg Contains a default set of monitoring options for the OMEGAMON XE for WebSphere MQ Monitoring agent.

kqi.xml A configuration file for the OMEGAMON XE for WebSphere Integration Brokers agent.

host_mq_opt.cfg Read by the OMEGAMON XE for WebSphere MQ Monitoring agent on a specific system using a specific set of monitoring options (opt). If this file does not already exist, it is created automatically from mq.cfg when running CandleAgent.

Candle Product Codes 251

Candle Product Codes

IntroductionThe following tables list Candle products and their associated product codes.

“Product Codes for UNIX Systems” lists product codes that are used in many of the Candle commands to designate the product you want to take action on.

“Product Codes for non-UNIX Systems” lists product codes for products that do not reside on UNIX. These products do, however, have seed data that you may want to add to your UNIX-based CMS.

B

Product Codes


Product Codes

Table 68. Product Codes for UNIX Systems

Code Seed Product

vt NO Alert Emitter for Tivoli Enterprise Console

tr NO Alert Emitter for TME 10 NetView

ma ✔ Alert Manager for Remedy ARS

nv ✔ Alert Manager for TME 10 NetView

br ✔ CandleNet eBP Pipes Agent packaging

bl ✔ CandleNet eBP™ Directory Agent packaging

ms NO CMS

cf ✔ CMS Configurator (Must seed for WebSphere MQ Configuration agent)

hi ✔ HP OpenView IT/Operations Adapter

ul ✔ Log Alert Agent for UNIX

ih ✔ OMEGAMON Alert Manager for HP OpenView IT/Operations

ho ✔ OMEGAMON Alert Manager for HP OpenView NNM

tv ✔ OMEGAMON Alert Manager for Tivoli/Enterprise Console

ez ✔ OMEGAMON Monitoring Agent for eBA Solutions

wl ✔ OMEGAMON XE for BEA WebLogic Server

lz ✔ OMEGAMON XE for Linux

or ✔ OMEGAMON XE for Oracle

sa ✔ OMEGAMON XE for R/3

oy ✔ OMEGAMON XE for Sybase

tx ✔ OMEGAMON XE for Tuxedo

ux ✔ OMEGAMON XE for UNIX

we ✔ OMEGAMON XE for WebSphere Application Server, Distributed Systems

Candle Product Codes 253

Product Codes

qi ✔ OMEGAMON XE for WebSphere Integration Brokers

ic OMEGAMON XE for WebSphere InterChange Server

mc NO OMEGAMON XE for WebSphere MQ Configuration (See product code “cf”)

mq ✔ OMEGAMON XE for WebSphere MQ Monitoring

um ✔ Universal Agent

ud ✔ OMEGAMON XE for DB2 UDB

Table 69. Product Codes for non-UNIX Systems

Code Seed Product

am ✔ Alert Adapter for OMEGACENTER Gateway for MVS

a2 ✔ Alert Manager for AF/REMOTE

cp ✔ CCC for CICSplex

co ✔ Command & Control

c3 ✔ OMEGAMON XE for CICS

d3 ✔ OMEGAMON XE for DB2

dp ✔ OMEGAMON XE for DB2plex

i3 ✔ OMEGAMON XE for IMS

ip ✔ OMEGAMON XE for IMSplex

n3 ✔ OMEGAMON XE for Mainframe Networks

nw ✔ OMEGAMON XE for NetWare

m3 ✔ OMEGAMON XE for OS/390

oe ✔ OMEGAMON XE for OS/390 UNIX System Services

a4 ✔ OMEGAMON XE for OS/400

s3 ✔ OMEGAMON XE for SMS

os ✔ OMEGAMON XE for Sysplex

Table 68. Product Codes for UNIX Systems (continued)

Code Seed Product

Product Codes


nt ✔ OMEGAMON XE for Windows Servers

wo ✔ OMEGAVIEW II for the Enterprise

pt ✔ Peregrine ServiceCenter Alert Manager

Table 69. Product Codes for non-UNIX Systems (continued)

Code Seed Product

Maintaining the EIB 255

Maintaining the EIB

IntroductionTo ensure the effective operation of your CMS, you should back up your EIB tables as part of your routine maintenance. The EIB contains the attributes and other data that define the agents to the server. The following files, which are stored in the $candlehome/tables/eib directory, comprise the EIB.

C

EIB Files


EIB Files

Table 70. EIB Files

*.db Files *.idx Files

qa1cacts.db qa1daggr.db qa1cacts.idx qa1daggr.idx

qa1cckpt.db qa1dcct.db qa1cckpt.idx qa1dcct.idx

qa1ccobj.db qa1dcct2.db qa1ccobj.idx qa1dcct2.idx

qa1ccomm.db qa1dmobj.db qa1ccomm.idx qa1dmobj.idx

qa1ceibl.db qa1dmtmp.db qa1ceibl.idx qa1dmtmp.idx

qa1chost.db qa1dobja.db qa1chost.idx qa1dobja.idx

qa1ciobj.db qa1dpcyf.db qa1ciobj.idx qa1dpcyf.idx

qa1cmcfg.db qa1drnke.db qa1cmcfg.idx qa1drnke.idx

qa1cnodl.db qa1drnkg.db qa1cnodl.idx qa1drnkg.idx

qa1cplat.db qa1dsnos.db qa1cplat.idx qa1dsnos.idx

qa1cpset.db qa1dspst.db qa1cpset.idx qa1dspst.idx

qa1cruld.db qa1dstms.db qa1cruld.idx qa1dstms.idx

qa1csitf.db qa1dstsa.db qa1csitf.idx qa1dstsa.idx

qa1csmni.db qa1dstua.db qa1csmni. qa1dstua.idx

qa1cstsc.db qa1dswrs.db qa1cstsc.idx qa1dswrs.idx

qa1cstsh.db qa1dswus.db qa1cstsh.idx qa1dswus.idx

qa1cthre.db qa1dwgrp.db qa1cthre.idx qa1dwgrp.idx

qa1dactp.db qa1dwork.db qa1dactp.idx qa1dwork.idx

Candle Architecture Codes 257

Candle Architecture Codes

IntroductionCandle uses an abbreviation to represent the various operating system architectures. The table below is the most current listing of these abbreviations.

This information can also be found in the following file: $candlehome/registry/archdsc.tbl.

D

Architecture Codes


Architecture Codes

Table 71. Candle Operating System Architecture Abbreviations

Abbreviation OS Architecture

aix513 AIX v5.1 (32 bit)




citrix Citrix® Metaframe™

hp10 HP-UX v10.01/10.10

hp102 HP-UX v10.20

hp11 HP-UX v11

hp116 HP-UX v11 (64 bit)

li622 Linux Intel v2.2

li6223 Linux Intel v2.2 (32 bit)

li624 Linux Intel v2.4



ls322 Linux zSeries, 2.2 kernel

ls3223 Linux zSeries, v2.2 (32 bit)


ls324 Linux zSeries, v2.4



osf1 Digital UNIX (prior to V5.0)

os390 OS/390 or z/OS

os400 OS/400

sol24 Solaris v2.4

sol25 Solaris v2.5

Candle Architecture Codes 259

Architecture Codes

sol26 Solaris v2.6

sol273 Solaris v7 (32 bit)






tsf50 Tru64 v5.0

unix UNIX

winnt Windows 2000 and Windows 2003 Server

Table 71. Candle Operating System Architecture Abbreviations (continued)

Abbreviation OS Architecture

Architecture Codes


Display Setup for Hummingbird eXceed 261

Display Setup forHummingbird eXceed

IntroductionIf you are using Hummingbird eXceed X-windows emulation software, it is recommended that you configure your display settings using the guidelines in this appendix to maximize performance. This display setting procedure uses the UNIX Windows Manager rather than the Windows Manager native to the local machine.

Appendix contents

Procedure for display setup for version 5.xx . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262

Procedure for display setup for version 6.xx . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

E

Procedure for display setup for version 5.xx



1. Install Hummingbird eXceed according to the manufacturer’s guidelines for Windows.

2. After installation, select “Start > Programs > Exceed > Xconfig”.

3. Enter your password when requested. The eXceed Xconfig folder is displayed as shown below:

4. From the open folder, select “Window Mode”. The following dialog is displayed:

5. Under the Window Mode title, select “Single”.

6. Click OK to save the screen display definition.

Window Mode program



7. Begin an Xterm session connecting to the UNIX machine of choice.

8. To use the Motif Window Manager for AIX and HP-UX, at the prompt type:[path]mwm& (full path /usr/bin/x11)

9. Press “Enter” to continue.

10. To use the OpenLook Window Manger on Solaris, at the prompt type:[path]olwm&(full path /usr/openwin/bin)


12. Continue the installation of OMEGAMON XE under “GUI Installation Steps” on page 75.




1. Install Hummingbird eXceed according to the manufacturer’s guidelines for Windows.

2. After installation, select “Start > Programs > Exceed > Xconfig”.

3. Enter your password when requested. The eXceed Xconfig folder is displayed as shown below:

4. From the open folder, select “Screen Definition”. The following dialog is displayed:

Screen Definition program

Window Mode title

Window Manager title



5. Under the Window Mode title, select “Multiple”.

6. Under the Window Manager title, select “X” from the list box.

7. Click OK to save the screen display definition.

8. Begin an Xterm session connnecting to the UNIX machine of choice.

9. To use the Motif Window Manager for AIX and HP-UX, at the prompt type:[path]mwm& (full path /usr/bin/x11)


11. To use the OpenLook Window Manger on Solaris, at the prompt type:[path]olwm&(full path /usr/openwin/bin)


13. Continue the installation of OMEGAMON XE under “GUI Installation Steps” on page 75.



Glossary 267

$candlehome The execution environment that you will create in which to install, execute, and maintain OMEGAMON XE on UNIX. See also, execution environment.

A

Access Control List (ACL) A list of the services available on a server, each with a list of the hosts permitted to use the service.

ACL See Access Control List (ACL).

address A location of data, usually in main memory or on a disk.

Adobe Acrobat Reader An application that allows you to view various types of files.

affinity A symbol for dependence on, or support of, a certain collection of agents that may be installed as a unit on a user’s system.

agent An executable file that gathers and distributes information about system performance. There is always one agent per managed system.

alert A warning message that appears at a console to indicate that an event has occurred that may require intervention.

Alert Adapter An agent that monitors and relays alerts to OMEGAMON XE products.

Alert Emitter A feature of an Alert Adapter that acts as an agent and relays OMEGAMON XE data to other products. The destination can be either Candle or third-party products.

Alert Manager An agent that monitors non-Candle monitoring products for a remote system, subsystem, or application, and relays alert information to the CMS.

alias 2. One of several alternative hostnames with the same Internet address. For example, in the UNIX hosts database (/etc/hosts or NIS map) the first field on a line is the Internet address, the next is the official hostname (the "canonical name" or "CNAME"), and any others are aliases. Hostname aliases often indicate that the host with that alias provides a particular network service. The assignment of services to computers can then be changed simply by moving an alias from one Internet address to another, without the clients needing to be aware of the change.

API See Application Program Interface (API).

Glossary

B


Application Program Interface (API) The interface (calling conventions) by which an application program accesses operating system and other services. An API is defined at source code level and provides a level of abstraction between the application and the kernel (or other privileged utilities) to ensure the portability of the code. An API can also provide an interface between a high level language and lower level utilities and services which were written without consideration for the calling conventions supported by compiled languages. In this case, the API's main task may be the translation of parameter lists from one format to another and the interpretation of call-by-value and call-by-reference arguments in one or both directions.

architecture Term used in this guide to refer to the operating system upon which a product is intended to execute.Also used as a variable, arch, in many Candle commands.

argument A value or reference passed to a function, procedure, subroutine, command or program, by the caller. There are many different conventions for passing arguments to functions and procedures including call-by-value, call-by-name, call-by-need. These affect whether the value of the argument is computed by the caller or the callee (the function) and whether the callee can modify the value of the argument as seen by the caller (if it is a variable). Arguments to a program are usually given after the command name.

attribute A discrete characteristic or piece of information, or a property of that information, such as type, source, or severity, about a managed system. CandleNet Portal users use attributes to build predicates.

authorization The process of granting or denying access to a network resource. Most computer security systems are based on a two-step process. The first stage is authentication, which ensures that a user is who he or she claims to be. The second stage is authorization, which allows the user access to various resources based on the user's identity.

B

browser A software application used to locate and display Web pages.

C

Candle Management Server (CMS) The host data management component in an OMEGAMON XE environment. It sends out requests to, and receives data from, managed systems having a monitoring agent or Alert Adapter installed. It also sends the information it receives to the CandleNet Portal.

Candle Management Workstation (CMW) A workstation that may be a component of an OMEGAMON XE environment. It provides a

Glossary 269

C

programmable workstation-based graphical user interface for OMEGAMON XE, and allows users to define and control all the monitoring and automation that OMEGAMON XE products provide. The CMW uses symbol and color changes to reflect the status changes of every object you are monitoring.

CandleNet Portal A Java-based programmable graphical user interface that allows the user to view, define and control all the monitoring and automation of the CT environment.

CandleNet Portal Server A collection of software services for the CandleNet Portal that enables retrieval, manipulation, and analysis of data from agents. It connects to both the CandleNet Portal and the CMS.

Candle Technologies (CT) An integrated, layered architecture consisting of data access, communication, and presentation components that enable cross-platform operation and integration of data for systems management applications.

client an application that runs on a personal computer or workstation and relies on a server to perform some operations. For example, an e-mail client is an application that enables you to send and receive e-mail.

client and server An architecture in which the client (personal computer or workstation) is the requesting machine and the server is the supplying machine.

Servers can be high-speed microcomputers, minicomputers or even mainframes. The client provides the user interface and may perform some or all of the application processing. A database server maintains the databases and processes requests from the client to extract data from or update the database. An application server provides additional business processing for the clients. Client and server architecture is the equivalent of a mainframe system on a network of smaller computers.

CMS See Candle Management Server (CMS).

CMW See Candle Management Workstation (CMW).

command A character string which tells a program to perform a specific action. Most commands take arguments which either modify the action performed or supply it with input. Commands may be typed by the user or read from a file by a command interpreter. It is also common to refer to menu items as commands.

command interpreter A program which reads textual commands from the user or from a file and executes them. Some commands may be executed directly within the interpreter itself, and others may cause it to load and execute other files. UNIX's command interpreters are known as shells.

CT See Candle Technologies (CT).

D


D

database server A stand-alone computer in a local area network that holds and manages the database. It implies that database management functions, such as locating the actual record being requested, is performed in the server computer.

development environment An integrated suite of tools to aid the development of software in a particular language or for a particular application. Usually, this consists of a compiler and editor and may also include one or more of a debugger, profiler, and source code manager.

development tool See development environment.

distributed database A collection of several different databases that looks like a single database to the user. An example is the Internet DNS.

distributed environment A collection of (probably heterogeneous) automata whose distribution is transparent to the user so that the system appears as one local machine. This is in contrast to a network, where the user is aware that there are several machines, and their location, storage replication, load balancing and functionality is not transparent. Distributed systems usually use some kind of client and server organization.

DLL See Dynamically Linked Library (DLL).

DNS See Domain Name System (DNS).

domain A specific phase of the software life cycle in which a developer works. Domains define developers' and users' areas of responsibility and the scope of possible relationships between products.

Domain Name System (DNS) An Internet service that translates domain names into IP addresses. Because domain names are alphabetic, they're easier to remember. The Internet however, is really based on IP addresses. Every time you use a domain name, therefore, a DNS service must translate the name into the corresponding IP address. For example, the domain name www.example.com might translate to 198.105.232.4.

Dynamically Linked Library (DLL) A library which is linked to application programs when they are loaded or run rather than as the final phase of compilation. This means that the same block of library code can be shared between several tasks rather than each task containing copies of the routines it uses. The executable is compiled with a library of stubs which allow link errors to be detected at compile-time. Then, at runtime, either the system loader or the task's entry code must arrange for library calls to be patched with the addresses of the real shared library routines, possibly via a jump table. The alternative is to make library calls part of the operating system kernel and enter them via some

Glossary 271

E

kind of trap instruction. This is generally less efficient than an ordinary subroutine call. It is important to ensure that the version of a dynamically linked library is compatible with what the executable expects.

E

EIB See Enterprise Information Base (EIB).

EIB tables The set of tables that define your EIB.

Enterprise Information Base (EIB) The central repository for all persistent data, including situations, user definitions such as report formats, managed-object definitions, and historical data.

Enterprise object An aggregation that represents all of your enterprise. The CandleNet Portal automatically creates the Enterprise object at initial product start-up. The Enterprise object contains all of the managed systems in the enterprise that are running CT products.

environment variable A variable that is bound in the current environment. When evaluating an expression in some environment, the evaluation of a variable consists of looking up its name in the environment and substituting its value.

event A change in the status of a situation being monitored.

executable A binary file containing a program in machine language which is ready to be executed (run).

execution environment The environment in which Candle products reside and execute ($candlehome). This environment includes the hub CMS location, the hosts and hostnames in the environment, the installation and post-installation management commands that control the $candlehome.

F

file descriptor An integer that identifies an open file within a process. This number is obtained as a result of opening a file. Operations which read, write, or close a file would take the file descriptor as an input parameter. In many operating system implementations, file descriptors are small integers which index a table of open files. In UNIX, file descriptors 0, 1 and 2 correspond to the standard input, standard output and standard error files respectively.

File Transfer Protocol (FTP) A client-server protocol which allows a user on one computer to transfer files to and from another computer over a TCP/IP network. Also the client program the user executes to transfer files.

filter A higher-order function which takes a predicate and a list and returns

G


those elements of the list for which the predicate is true.

firewall Router or access server, or several routers or access servers, designated as a buffer between any connected public networks and a private network. A firewall router uses access lists and other methods to ensure the security of the private network.

framework The component of an agent that provides an interval timer and manager objects for managing agents and requests.

FTP See File Transfer Protocol (FTP).

function A method of evaluating the information that an attribute supplies. The functions used in CandleNet Portal are

1. Average *AVG2. Count *COUNT3. Make time *TIME4. Maximum *MAX5. Minimum *MIN6. String scan *SCAN7. Substring *STR8. Sum *SUM9. Value

G

Gateway An agent that communicates events to any management application.

GNU A recursive acronym: "GNU's Not UNIX!". The Free Software Foundation's

project to provide a freely distributable replacement for UNIX.

H

historical data collection A capability of reports that enables the user to access monitoring data in order to analyze past system performance.

host A computer system that is accessed by a user working at a remote location. Typically, the term is used when there are two computer systems connected by modems and telephone lines. The system that contains the data is called the host, while the computer at which the user sits is called the remote terminal.

hostname The unique name by which a computer is known on a network, used to identify it in electronic mail, Usenet news, or other forms of electronic information interchange. On the Internet, the hostname is an ASCII string which consists of a local part and a domain name. The hostname is translated into an Internet address either via the /etc/hosts file, NIS or by the DNS or resolver. It is possible for one computer to have several hostnames (aliases) though one is designated as its canonical name.

hub A central host system that collects the status of the situations and policies running on your managed systems.

Glossary 273

I

hub server A centrally configured CMS. The hub server accepts data from other servers (the remote servers) and from agents.

I

individual managed object A managed object that corresponds to a single resource at the user’s site.

install.sh A shell script that establishes the execution environment, installs Candle commands used for post-installation management of that environment, and calls other Candle commands that are required to complete the command line installation and basic configuration of Candle products.

installer A utility program to ease the installation of another, probably larger, application. It is also possible for hardware to have an installer accompany it, to install any low level device drivers required.

instance An individual object of a certain class. While a class is just the type definition, an actual usage of a class is called "instance". Each instance of a class can have different values for its instance variables.

Internet Protocol (IP) The network layer for the TCP/IP protocol suite widely used on Ethernet networks, defined in STD 5, RFC 791. IP is a connectionless, best-effort packet switching protocol. It provides packet routing, fragmentation

and re-assembly through the data link layer.

IP See Internet Protocol (IP).

J

Java Database Connectivity (JDBC) Part of the Java Development Kit which defines an application programming interface for Java for standard SQL access to databases from Java programs.

Java Runtime Environment (JRE) The part of the Java Development Kit (JDK) required to run Java programs. The JRE consists of the Java Virtual Machine, the Java platform core classes and supporting files. It does not include the compiler, debugger or other tools present in the JDK. The JRE is the smallest set of executables and files that constitute the standard Java platform.

JDBC See Java Database Connectivity (JDBC).

JRE See Java Runtime Environment (JRE).

K

keyword One of a fixed set of symbols built into the syntax of a language. Typical keywords would be if, then, else, print, goto, while, switch. There are usually restrictions about reusing keywords as names for user-defined

L


objects such as variables or procedures. Languages vary as to what is provided as a keyword and what is a library routine, for example some languages provide keywords for input/output operations whereas in others these are library routines.

L

library A collection of subroutines and functions stored in one or more files, usually in compiled form, for linking with other programs. Libraries are one of the earliest forms of organized code reuse. They are often supplied by the operating system or software development environment developer to be used in many different programs. The routines in a library may be general purpose or designed for some specific function such as three dimensional animated graphics. Libraries are linked with the user's program to form a complete executable. The linking may be static linking or, in some systems, dynamic linking.

literal A constant made available to a process, by inclusion in the executable text. Most modern systems do not allow texts to modify themselves during execution, so literals are indeed constant; their value is written at compile-time and is read-only at runtime. In contrast, values placed in variables or files and accessed by the process via a symbolic name, can be changed during execution. This may be an asset. For example, messages can be

given in a choice of languages by placing the translation in a file. Literals are used when such modification is not desired. Also see variable.

log CandleNet Portal records changes to situations and EIB objects in a log.

logical unit (LU) A primary component of SNA, an LU is a type of Network Addressable Unit that enables end users to communicate with each other and gain access to SNA network resources.

Logical Unit 6.2 (LU6.2) A type of logical unit that governs peer-to-peer SNA communications. LU6.2 supports general communication between programs in a distributed processing environment. LU6.2 is characterized by a peer relationship between session partners, efficient use of a session for multiple transactions, comprehensive end-to-end error processing and a generic application program interface consisting of structured verbs that are mapped into a product implementation.

LU See logical unit (LU).

LU6.2 See Logical Unit 6.2 (LU6.2).

M

managed object A visual representation, typically an icon, of one or more situations being monitored on one or more managed systems. As the status of a situation changes, the

Glossary 275

N

appearance of a managed object icon on your workstation changes.

managed system Any system, such as UNIX, Windows, or OS/390, that a CT is monitoring. When a new instance of a type of managed system comes online for the first time, information about it is placed automatically in the Managed Systems icon in the CandleNet Portal main window. See also type of managed system.

monitoring agent A process that probes a managed system for data and can make a managed system look like a set of objects on a CandleNet Portal.

N

NAT See Network Address Translation (NAT).

Network Address Translation (NAT) A hardware device currently being developed and used to extend the Internet addresses already in use. NAT has been suggested as an alternative to adopting IPv6 (Ping). It allows duplicate IP addresses to be used within a corporation and unique addresses outside.

Network File System (NFS) A protocol developed by Sun Microsystems, and defined in RFC 1094, which allows a computer to access files over a network as if they were on its local disks. This protocol has been incorporated in products by more than two hundred companies, and is now a

de facto standard. NFS is implemented using a connectionless protocol (UDP) in order to make it stateless.

Network Interface Card (NIC) An adapter circuit board installed in a computer to provide a physical connection to a network.

NFS See Network File System (NFS).

NIC See Network Interface Card (NIC).

node A single computer within a network of computers.

O

ODBC See Open DataBase Connectivity (ODBC).

OMEGAMON The name under which Candle delivers CT to its customers. See Candle Technologies (CT).

Open DataBase Connectivity (ODBC) A standard database access method developed by Microsoft Corporation. The goal of ODBC is to make it possible to access any data from any application, regardless of which database management system (DBMS) is handling the data. ODBC manages this by inserting a middle layer, called a database driver, between an application and the DBMS. The purpose of this layer is to translate the application's data queries into commands that the DBMS understands. For this to work, both the application and the DBMS must be ODBC-compliant - that is, the

P


application must be capable of issuing ODBC commands and the DBMS must be capable of responding to them.

operand An argument of an operator or of a machine language instruction.

operator A symbol used as a function, with infix syntax if it has two arguments (such as +) or prefix syntax if it has only one (such as Boolean NOT). Many languages use operators for built-in functions such as arithmetic and logic.

P

parameter See argument.

partition In a firewall environment, a term used to designate either the public network (outside the firewall) or the private network (inside the firewall).

patch A temporary addition to a piece of code, usually as a quick-and-dirty remedy to an existing bug or misfeature. A patch may or may not work, and may or may not eventually be incorporated permanently into the program. Distinguished from a diff or mod by the fact that a patch is generated by more primitive means than the rest of the program; the classical examples are instructions modified by using the front panel switches, and changes made directly to the binary executable of a program originally written in an HLL.

pathname The specification of a node (file or directory) in a hierarchical file system. The path is usually specified by

listing the nodes top-down, separating the directories by the pathname separator ("/" in UNIX, "\" in MS-DOS). A pathname may be an absolute pathname or a relative pathname. The part of the pathname of a file after the last separator is called the basename.

permission The ability to access (read, write, execute, traverse, etc.) a file or directory. Depending on the operating system, each file may have different permissions for different kinds of access and different users or groups of users.

persistence An object that exists after the program that created it has ended. See persistent object.

persistent data Data that exists from session to session. Persistent data is stored in a database on disk or tape.

persistent object An object that continues to exist after the program that created it has been unloaded. An object’s class and current state must be saved for use in subsequent sessions.

platform The underlying hardware or software for a system. The platform defines a standard around which a system can be developed. Once the platform has been defined, software developers can produce appropriate software and managers can purchase appropriate hardware and applications. The term is often used as a synonym of operating system.

policy A collection of activities that provides the capability of automating

Glossary 277

Q

responses to events or routine operator tasks.

port number The “channel” that is used for one or more components to communicate with one another via a communications protocol. There are three recognized ranges of port numbers: The Well Known Ports from 0 through 1023, the Registered Ports from 1024 through 49151, and the Dynamic and Private Ports from 49152 through 65535. Candle’s reserved port number is 1918.

post-installation management The processes, procedures, and commands you should use to maintain the fitness of $candlehome.

process The sequence of states of an executing program. A process consists of the program code (which may be shared with other processes which are executing the same program), private data, and the state of the processor, particularly the values in its registers. It may have other associated resources such as a process identifier, open files, CPU time limits, shared memory, child processes, and signal handlers.

Program Temporary Fix (PTF) An interim change to the program to modify its action until the change can be incorporated into the base code.

predicate The major portion of a situation that functions to compare a system condition (attribute) to a value. Predicates are of the form:

system condition - compared to - value

An example of a predicate isCPU usage - greater than - 90%

product-provided situations CandleNet Portal-provided set of predefined situations for you to use as-is or to modify. Using product-provided situations makes it unnecessary to create your own.

protocol A communications protocol is a set of rules or standard designed so that computers can exchange information with a minimum of errors.

Q

query A user's (or agent's) request for information, generally as a formal request to a database or search engine.

R

relational operator Predicate operators that compare attributes to a compare value. The six relational operators are

1. Greater than2. Less than3. Equal to4. Not equal to5. Greater than or equal to6. Less than or equal to

S


remote server Remote CMSs accept data from agents and report that data to a hub CMS. They are optional components of the CT environment that must communicate with a hub CMS first in order to send communication to a CandleNet Portal. It does so by collecting data from local agents and transmitting it to a hub CMS.

replication The process of creating and managing duplicate versions of a database. Replication not only copies a database but also synchronizes a set of replicas so that changes made to one replica are reflected in all the others. The beauty of replication is that it enables many users to work with their own local copy of a database but have the database updated as if they were working on a single, centralized database. For database applications where users are geographically widely distributed, replication is often the most efficient method of database access.

report Displays of data from managed systems. The data may be real-time or historical. Users filter the displays and produce charts.

root The UNIX superuser account (with user name "root" and user ID 0) that overrides file permissions. By extension, the privileged system-maintenance login on any operating system.

runtime The period of time during which a program is being executed, as opposed to compile time or load time.

runtime environment A collection of subroutines and environment variables that provide commonly used functions and data for a program while it is running.

S

seed data Product-specific catalog, attribute, and SQL data.

seeding The process of adding product-specific catalog, attribute, and SQL data (seed data) to a CMS. This process allows the CMS to recognize and acknowledge the product.

shell script A program written to be interpreted by the shell of an operating system, especially UNIX.

Simple Network Management Protocol (SNMP) A widely used network monitoring and control protocol. Data is passed from SNMP agents, which are hardware or software processes reporting activity in each network device (hub, router, bridge, etc.) to the workstation console used to oversee the network. The agents return information contained in a Management Information Base (MIB), which is a data structure that defines what is obtainable from the device and what can be controlled (turned off or on, etc.)

situation A logical expression involving one or more system conditions (attributes) that the user wants to monitor that are of the form:

Glossary 279

T

If - system condition - compared to - value - is true

An example of a situation is:IF - CPU usage - GT - 90% - TRUE

IF and TRUE appear in every situation.

SNA See System Network Architecture (SNA).

SNMP Gateway An SNMP proxy agent that acts as a bridge between the hub CMS and third-party SNMP management application. It uses the native SNMP services of its host operating system to send SNMP traps (alerts) from the CMS to the third-party application. It translates GET and GETNEXT requests from the application to the CMS

SQL See Structured Query Language (SQL).

state An indication associated with an icon, color, and severity level of the status of a managed object at any particular point in time. The five predefined states that each managed object can reflect are:

Unknown

Critical

Warning

Not Monitored

You can customize the default colors and add new states as needed.

status The TRUE or FALSE condition of a situation assigned to a managed object.

Structured Query Language (SQL) An industry-standard language for creating, updating and querying relational database management systems.

System Network Architecture (SNA) An IBM communications network protocol that connects systems and programs under any operating system image and allows them to participate in distributed processing.

system administrator CandleNet Portal users who have full access to data, full authority to product functions, and who can authorize and establish access and privileges for other users. By default, the first user of CandleNet Portal is a system administrator.

T

table A construction that holds the data returned from an agent when the agent returns data to a CMS in response to a request. It has a one-to-one correspondence to the agent it represents.

tar UNIX's general purpose archive utility and the file format it uses. Tar was originally intended for use with magnetic tape but, though it has several command line options related to tape, it is now used more often for packaging files

V


together on other media, such as for distribution via the Internet.

TCP/IP See Transmission Control Protocol/Internet Protocol (TCP/IP).

template A model the developer uses to create managed objects. Every managed object you create inherits the characteristics and behaviors of its template.

Transmission Control Protocol/Internet Protocol (TCP/IP). An open, highly portable communications protocol. TCP provides transport protocol functions which ensure that the total number of bytes sent is received correctly at the other end. IP provides the routing mechanism.

type of managed system An operating system, subsystem, or application system type that a CT agent is monitoring. Situation attributes are restricted to a specific managed system type.

V

value A predicate function that uses the raw value of an attribute. A value can be a number, text string, attribute, or modified attribute. Use this function with all relational operators.

variable A symbol or name that stands for a value. Variables can represent numeric values, characters, character strings, or memory addresses. Also see literal.

view A way of looking at information about an object. Each view displays information in a different format. CandleNet Portal has the following views:

1. Details2. Events3. Graphic4. Historical5. Icons6. Settings

Not all objects have every view.

W

workspace A collection of panels (views) in CandleNet Portal that represent system and application conditions.

Index 281

Index

AACL

authorization 177address translation 39Adobe portable document format 16advanced command-line configuration 163agent to Candle Management Server

connection 88agents 27, 28

configuring 88, 111, 153number to install 36platforms 29, 42prerequisites 47reconfiguring 109starting 120, 124starting and stopping

using CandleAgent 179stopping 120, 124types 29

AIXdisplay settings for Hummingbird

eXceed 37environment variables 37named pipes 37prerequisites

hardware 43versions 24, 44

Alert Adapters 29Alert Emitters 29Alert Managers 29API Server Data Provider 197architecture codes 257authorization

ACL 177authorizing


BBEA WebLogic Server monitoring agent

prerequisites 48broker entries

removing from Manage Candle Services 179

browser mode 28, 32

CCandle account 60Candle Command Center for MQSeries

Configuration, renamed 23Candle Command Center for MQSeries,

renamed 23Candle Management Server 27, 29, 115

configuring 79, 92, 113, 137IP.PIPE 222

HP-UX 222name

where to find 143naming conventions 30platforms 27, 29, 42prerequisites 43remote 30restarting 117seeding 115, 139seeding error 171 143setting permissions 138starting 96, 115, 118stopping 116, 118version 23

Candle Management Server to agent connection 88

Candle Management Workstation 27, 152starting 96

Candle Web site 15, 20CandleAgent 120, 156, 173

C


starting and stopping agents 179Tuxedo monitoring agent

starting and stopping 196Universal Agent

starting and stopping 199CandleAudit 122CandleClone 223, 226

CandleRemote 224, 234command line 231GUI 227limitations 224starting 227, 231transferring existing package from previous

clone 229CandleConfig 109


R/3 monitoring agent 191starting and stopping 192

Tuxedo monitoring agent 195CandleDBAgent 124CandleDBConfig 163

incomplete status message 165CandleExecute 132CandleManage 216CandleMigrate 150, 151CandleNet Portal 26, 28

compatible Candle products 21, 32components 32platforms 42version 23

CandleNet Portal Browser Client 28, 32CandleNet Portal Desktop Client 28, 32CandleNet Portal Server 26, 32CandleRemote 236

CandleClone 224, 234command line 242GUI 238limitations 234starting 238

CandleSeed 116, 170CandleServer 115, 118

cinfo 126advanced options 129output 128, 131product codes 130usage 127

cloning installed products 228clustered-server environment 167CMS

see Candle Management ServerCMW

see Candle Management Workstationcodes

architecture 257product 251

Collector_For_Performance_Job batch job 186

command-line configurationadvanced 163

command-line installation steps 99communications

firewalls 147prerequisites 42, 44protocols 59, 79

community name, specifying 209components

CandleNet Portal 32OMEGAMON XE 26order of installation 34selecting for installation 78starting and stopping 217

manually 100configuration

with remote Candle Management Server 31

configuration files 168, 194mult-platform 245OMEGAMON XE for WebSphere

Integration Brokers 250OMEGAMON XE for WebSphere MQ

Monitoring 250types 246, 247

Custom-Configuration 248configuring 109

Index 283

D

advancedfrom command line 163

agents 88, 111, 153Candle Management Server 79, 92, 113,

137CandleConfig 109connection between agents and Candle

Management Server 88DB2 Universal Database monitoring

agent 156eBA Solutions monitoring agent 157Hot Standby 144Hummingbird eXceed

display settings 261Manage Candle Services

Oracle and Sybase monitoring agents 163




Oracle monitoring agent 158, 164R/3 monitoring agent 181Remedy ARS Alert Adapter 193Sybase monitoring agent 158, 164Tuxedo monitoring agent 194Universal Agent 197

multiple 201UNIX Logs monitoring agent 205WebSphere Application Server monitoring

agent 206connect ID 159connection between Candle Management

Server and agents 88creating

Candle account 60default objects for OMEGAMON XE for

WebSphere MQ Monitoring 173library links for OMEGAMON XE for

WebSphere Integration Brokers 175remote package 239

Sybase login 162Custom-Configuration files 248

Ddatabase servers 164DB2 UDB

see DB2 Universal DatabaseDB2 Universal Database monitoring agent

configuring 156prerequisites 48starting and stopping 156

debug tracing 125desktop mode 28, 32disk space prerequisite 42documents

related 14, 35

EeBA Solutions monitoring agent

configuring 157prerequisites 48

environment variables 37, 166, 189, 200exit status 114, 121, 123, 125, 133

Ffile descriptor 46file permissions 93, 200, 204file types

configuration 246, 247, 248firewalls

address translation 39application proxy 39communications 147IP.PIPE 39partition-naming strategy 39sample partition file 148sample scenarios 40support for 39, 147Warehouse Proxy 39

FTPtransferring files to UNIX system 60

fully qualified path names 43

G


functions of OMEGAMON XE 26

GGateways 29gnu compiler 2.95.3 58GUI installation steps 75

Hhistoriical data 72home directory 194hostname 167Hot Standby 144

configuring 144overview 145prerequisites 144testing 145

HP-UXCandle Management Server

IP.PIPE 222kernel parameter adjustments 46prerequisites

hardware 43patches 44

versions 44Hummingbird eXceed

display settingsAIX 37configuring 261

X-windows emulator software 60

Iincomplete status message 165install.sh 76, 77, 101, 102installation types 78, 103installer program

multi-platform configuration files 246starting 76

IP 112IP port 109IP.PIPE 44, 112, 222

firewalls 39

Kkddos 158kernel parameter adjustments

HP-UX 46Korn shell 60

command interpreter, required 42

Llicense agreement 104Linux




Universal Agent 24WebSphere Application Server monitoring

agent 24Linux monitoring agent

prerequisites 49lock file name 135log files 134, 218, 220

format 220name 221

logical machine 195

MManage Candle Services

Action menu 85icons 87Options menu 86overview 85removing broker entries 179seeding 170, 178starting and stopping products 216

managed system name 166managing log files 218maxfiles limit 46, 200migrated information when upgrading 67migrating

CandleMigrate 150

Index 285

N

preparations 65required installation in a new directory 69

monitoring agents 29multi-platform configuration files 245

Nnamed pipes

AIX 37naming conventions for Candle

Management Server 30Network Interface Card

identifying which to use 37NFS 35, 60NIC

see Network Interface Card

OOMEGAMON DE

overview 28OMEGAMON XE

components 26order of installation 34

functions 26overview 26

OMEGAMON XE for WebSphere Application Server

archiving existing historical data 72OMEGAMON XE for WebSphere Integration

Brokersarchiving existing historical data 72authorizing 176CandleConfig 178CandleSeed 179configuration files 250configuring 175creating library links 175platforms

Linux 24prerequisites 50seeding

using Manage Candle Services 178starting and restarting 180

upgrading 176zSeries Linux

installing gnu compiler 2.95.3 58OMEGAMON XE for WebSphere

InterChange Serverconfiguring data sources 210configuring SNMP data collection 208prerequisites 51starting a data source 214starting the monitoring agent 214


configuring 170platforms

Linux 24prerequisites 52seeding

using Manage Candle Services 170user ID 60zSeries Linux

installing gnu compiler 2.95.3 58OMEGAMON XE for WebSphere MQ

Integrator, renamed 24OMEGAMON XE for WebSphere MQ

Monitoringconfiguration files 250configuring 172default objects 173monitoring options 173, 174platforms

Linux 24prerequisites 53user ID 60zSeries Linux

installing gnu compiler 2.95.3 58Open Client, installing 161operating systems

agents 29, 42Candle Management Server 27, 29, 42CandleNet Portal 42codes 257OMEGAMON XE for WebSphere

Integration BrokersLinux 24

P



Linux 24OMEGAMON XE for WebSphere MQ

MonitoringLinux 24

renamed 23selecting 79

for installation 104Universal Agent

Linux 24WebSphere Application Server monitoring

agentLinux 24

Oracle monitoring agentconfiguring 158, 164

Manage Candle Services 163connect ID 159environment variables 166managed system name 166prerequisites 53starting and stopping 124V$ Dynamic Performance Tables 158

order of component installations 34

Ppackaging

WebSphere Application Server monitoring agent 24

partition file 148partition-naming strategy 39password encryption 181path names 43PDF files, adding annotations 17planning

information to have ready 34key issues 33upgrade and migration 66

platformsagents 29, 42Candle Management Server 27, 29, 42CandleNet Portal 42codes 257


Linux 24OMEGAMON XE for WebSphere MQ

ConfigurationLinux 24


Linux 24renamed 23selecting 79

for installation 104Universal Agent

Linux 24WebSphere Application Server monitoring

agentLinux 24

Poll Interval field 208prerequisites 42

agents 47AIX 24, 43, 44BEA WebLogic Server monitoring

agent 48Candle Management Server 43CandleClone 224CandleRemote 234communications 42, 44DB2 Universal Database monitoring

agent 48disk space 42eBA Solutions monitoring agent 48Hot Standby 144HP-UX 43, 44

required patches 44Korn shell command interpreter 42Linux monitoring agent 49OMEGAMON XE for WebSphere

Integration Brokers 50OMEGAMON XE for WebSphere MQ

Configuration 52OMEGAMON XE for WebSphere MQ

Monitoring 53Oracle monitoring agent 53

Index 287

R

R/3 monitoring agent 54Remedy ARS Alert Manager 54Solaris 44Sybase monitoring agent 54TME 10 Enterprise Console Alert

Manager 54Tuxedo monitoring agent 48Universal Agent 57UNIX Logs monitoring agent 55UNIX monitoring agent 55WebSphere Application Server monitoring

agent 56printing problems 16product codes

non-UNIX systems 253UNIX systems 252

productscloning installed 228renamed 23selecting for installation 105starting and stopping 215

products and versions compatible with this release of CandleNet Portal 21

products compatible with this release of CandleNet Portal 32

protocols 79

RR/3 monitoring agent

CandleConfig 191configuring 181environment variables 189password encryption 181prerequisites 54remote function modules 183, 188starting and stopping

using CandleConfig 192user ID 185

reconfiguring 109agents 109

related documents 14, 35related information 15

Remedy ARS Alert Adapterconfiguring 193

Remedy ARS Alert Managerprerequisites 54

remote Candle Management Server 30configuration 31

remote function modules 183, 188remote package 239, 240renamed products or platforms 23restarting

Candle Management Server 117

Sscope of this guide 14security

validating users 95seeding

Candle Management Server 115, 139CandleSeed 170OMEGAMON XE for WebSphere

Integration Brokersusing Manage Candle Services 178


using Manage Candle Services 170seeding error 171 143selecting

components for installation 78platforms for installation 79, 104products for installation 105

SetPerm 93, 95setting permissions

Candle Management Server 138kddos 158

shell script 34slibclean 38SNA 59SNMP Data Provider 198SNMP Gateways 29Solaris

prerequisiteshardware 44

versions 44

T


startingagents 120, 124

using CandleAgent 179Candle Management Server 96, 115, 118Candle Management Workstation 96CandleClone 227, 231CandleRemote 238components 217

manually 100DB2 Universal Database monitoring

agent 156installer program 76products 215R/3 monitoring agent

using CandleConfig 192Tuxedo monitoring agent 217

using CandleAgent 196Universal Agent 201, 203

using CandleAgent 199WebSphere Application Server monitoring

agent 207WebSphere InterChange Server data

sources 214WebSphere InterChange Server

monitoring agent 214stopping

agents 120, 124using CandleAgent 179

Candle Management Server 116, 118components 217

manually 100DB2 Universal Database monitoring

agent 156products 215R/3 monitoring agent

using CandleConfig 192Tuxedo monitoring agent 217

using CandleAgent 196Universal Agent 203

using CandleAgent 199SuSe support 58Sybase login 162Sybase monitoring agent

configuring 158, 164Manage Candle Services 163

environment variables 166installing Open Client 161managed system name 166prerequisites 54starting and stopping 124Sybase login 162

Ttemplate 247template files 247temporary files 167testing

Hot Standby 145thin client 28TME 10 Enterprise Console Alert Manager

prerequisites 54tracing

debug 125transferring

files to UNIX system 60remote package 240

Transport Administrators 185Transport Data file 185Transport System co-files directory 184Transport System data directory 184Tuxedo monitoring agent

CandleConfig 195configuring 194prerequisites 48starting and stopping 217

using CandelAgent 196types of installations 103

UUniversal Agent

API Server Data Provider 197configuring 197

multiple 201environment variables 200file permissions 200

Index 289

V

maxfiles limit 200platforms

Linux 24prerequisites 57SNMP Data Provider 198starting and stopping 201, 203

using CandleAgent 199um.config 197

UNIX Logs Alert Agent 205UNIX Logs monitoring agent

configuring 205prerequisites 55

UNIX monitoring agentfile permissions 204prerequisites 55

upgradingin stages 66migrated information 67OMEGAMON XE for WebSphere

Integration Brokers 176preparations 65

upwards compatibility 69user ID 36



R/3 monitoring agent 185

VV$ Dynamic Performance Tables 158verifying processes 134, 220versions of products in this release 21

WWarehouse Proxy

firewalls 39Web site, Candle 15, 20WebSphere Application Server monitoring

agentconfiguring 206platforms

Linux 24prerequisites 56starting 207supplied CD 24


Part Number: CT36QNA

Documents

Installing Candle Products - IBMpublib.boulder.ibm.com/tividd/td/CanInstallDoclnk/GC32...Computing Architecture, Patent Pending; User Interface for System Management Applications,