ITCAM For SOA Installation Guide (7.1.1)

Tivoli Composite Application Manager for SOA
Version 7.1.1
Installation Guide
GC23-8803-01
Tivoli Composite Application Manager for SOA
Version 7.1.1
Installation Guide
GC23-8803-01
Note Before using this information and the product it supports, read the information in Appendix C, Notices, on page 277.
This edition applies to version 7.1.1 of IBM Tivoli Composite Application Manager for SOA (product number 5724-M07 for the distributed version, and 5698-B16 for the Enterprise version) and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation 2005, 2009. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix About this publication . . . . . . . . . . . . . . . . . . . . . . xi Intended audience . . . . . . . . . . . . . . . . . . . . . . . . xi What this publication contains. . . . . . . . . . . . . . . . . . . . xi Publications . . . . . . . . . . . . . . . . . . . . . . . . . . xiii IBM Tivoli Composite Application Manager for SOA library . . . . . . . . xiii Related publications . . . . . . . . . . . . . . . . . . . . . . xv Accessing terminology online . . . . . . . . . . . . . . . . . . . xv Accessing publications online. . . . . . . . . . . . . . . . . . . xv Ordering publications . . . . . . . . . . . . . . . . . . . . . xvi Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . . xvi Tivoli technical training . . . . . . . . . . . . . . . . . . . . . . xvi Support information . . . . . . . . . . . . . . . . . . . . . . . xvi Conventions used in this publication . . . . . . . . . . . . . . . . . xvii Typeface conventions . . . . . . . . . . . . . . . . . . . . . xvii Operating system-dependent variables and paths . . . . . . . . . . . xvii Tivoli command syntax . . . . . . . . . . . . . . . . . . . . xviii Resolving directory path variables . . . . . . . . . . . . . . . . xviii
Part 1. Installing the product . . . . . . . . . . . . . . . . . . . . . . . . . 1

Chapter 1. Planning for installation . . . . . . . . . . . . . . Supported hardware platforms and operating systems . . . . . . . . Software and hardware prerequisites . . . . . . . . . . . . . . Supported operating systems . . . . . . . . . . . . . . . . Required hardware . . . . . . . . . . . . . . . . . . . . Required software. . . . . . . . . . . . . . . . . . . . Understanding your IBM Tivoli Monitoring distributed environment . . . Data collector considerations . . . . . . . . . . . . . . . . Planning database support . . . . . . . . . . . . . . . . . Database support for historical data collection . . . . . . . . . Database support for service-to-service topology and service registry integration . . . . . . . . . . . . . . . . . . . . . . Installation methods . . . . . . . . . . . . . . . . . . . . Installation and configuration roadmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 . 3 . 4 . 4 . 9 . 10 . 12 . 13 . 13 . 13
. . . 14 . . . 15 . . . 16 . . . . . . . . . . . . 19 19 19 19 19 21
Chapter 2. Upgrading from a previous installation . . . . . . . . . Disabling data collection for your monitored environments . . . . . . . Disabling data collection for version 6.0.0 . . . . . . . . . . . . Disabling data collection for version 6.1.0 . . . . . . . . . . . . Disabling data collection for version 7.1.0 . . . . . . . . . . . . Upgrading your IBM Tivoli Monitoring environment . . . . . . . . . . Upgrading IBM Tivoli Composite Application Manager for SOA from version 6.0.0 . . . . . . . . . . . . . . . . . . . . . . . . . . Upgrading IBM Tivoli Composite Application Manager for SOA from version 6.1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . Changes to subnode names in Tivoli Enterprise Portal . . . . . . . Upgrading IBM Tivoli Composite Application Manager for SOA from version 7.1.0 . . . . . . . . . . . . . . . . . . . . . . . . . . Changes in historical data for WebSphere Message Broker . . . . . Running the IBM Tivoli Composite Application Manager for SOA installation program . . . . . . . . . . . . . . . . . . . . . . . .
Copyright IBM Corp. 2005, 2009
. . 22 . . 22 . . 24 . . 24 . . 25 . . 26
iii
Additional upgrade tasks . . . . . . . . . . . . . . . . . . . . . 26 Chapter 3. Installing IBM Tivoli Composite Application Manager for SOA Installing application support on the monitoring server, portal server, and desktop client . . . . . . . . . . . . . . . . . . . . . . . Installing application support on monitoring servers . . . . . . . . . Installing application support on the Tivoli Enterprise Portal Server . . . . Installing application support on the desktop client . . . . . . . . . . Installing the monitoring agent . . . . . . . . . . . . . . . . . . Permissions needed to install the monitoring agent . . . . . . . . . Windows: Installing the monitoring agent . . . . . . . . . . . . . Linux, AIX, HP-UX, or Solaris: Installing the monitoring agent . . . . . . 29 . . . . . . . . 29 29 41 47 52 53 54 60
Chapter 4. Configuring topology support . . . . . . . . . . . . . . 65 Minimum space requirements on the file system . . . . . . . . . . . . 67 Creating the SOA Domain Management Server database . . . . . . . . . 67 Manually creating a local SOA Domain Management Server database . . . 67 Manually creating a remote SOA Domain Management Server database 70 Creating the Tivoli Common Object Repository database . . . . . . . . . 74 Manually creating a local Tivoli Common Object Repository database . . . . 75 Manually creating a remote Tivoli Common Object Repository database . . . 76 Running the SOA Domain Management Server Configuration Utility . . . . . 78 Upgrading from a previous version . . . . . . . . . . . . . . . . 79 Database and user permissions. . . . . . . . . . . . . . . . . . 81 Tivoli Enterprise Portal Server on Windows . . . . . . . . . . . . . 91 Tivoli Enterprise Portal Server on Linux or AIX . . . . . . . . . . . . 93 ConfigDMS command options . . . . . . . . . . . . . . . . . . 94 Running the SOA Domain Management Server Configuration Utility graphical user interface . . . . . . . . . . . . . . . . . . . . . . . 96 Running the SOA Domain Management Server Configuration Utility in console mode . . . . . . . . . . . . . . . . . . . . . . . 111 Running the SOA Domain Management Server Configuration Utility in silent mode . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Re-configuring the Tivoli Enterprise Portal Server . . . . . . . . . . . . 122
Part 2. Configuring for data collection . . . . . . . . . . . . . . . . . . . . 125

Chapter 5. Overview . . . . . . . . . . . . . . . . . . . . Permissions needed to configure for data collection . . . . . . . . . Running the Data Collector Configuration Utility . . . . . . . . . . ConfigDC script options . . . . . . . . . . . . . . . . . . Running the Data Collector Configuration Utility graphical user interface Running the Data Collector Configuration Utility in console mode . . . Running the Data Collector Configuration Utility in silent mode . . . . Additional configuration options . . . . . . . . . . . . . . . Running the KD4configDC script . . . . . . . . . . . . . . . . Getting help for KD4configDC . . . . . . . . . . . . . . . . Configuring data collection for your environment . . . . . . . . . . Chapter 6. Configuring data collection: WebSphere Application Server About the Service Component Architecture . . . . . . . . . . . . Enabling data collection . . . . . . . . . . . . . . . . . . . Disabling data collection . . . . . . . . . . . . . . . . . . . Configuring managed SCA mediation primitive runtime support . . . . . Configuring support using the Data Collector Configuration Utility . . . Configuring support using available scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 127 130 130 131 133 134 146 147 148 148 149 149 150 151 152 152 155
. . . . . .
. . . . . .
iv
Installation Guide
Deploying and managing your applications . . . . . . . . . . . . . 156 Limitations when monitoring SCA messages . . . . . . . . . . . . 156 Logging and Filtering . . . . . . . . . . . . . . . . . . . . . . 157 Chapter 7. Configuring data collection: Microsoft .NET . . . . . . . . 159 Enabling data collection . . . . . . . . . . . . . . . . . . . . . 159 Disabling data collection . . . . . . . . . . . . . . . . . . . . . 160 Chapter 8. Configuring data collection: BEA WebLogic Server . About Apache Axis . . . . . . . . . . . . . . . . . . . BEA client side configuration . . . . . . . . . . . . . . . BEA server side configuration . . . . . . . . . . . . . . . Enabling data collection in a single server environment . . . . . Using the Data Collector Configuration Utility . . . . . . . . Using the KD4configDC command . . . . . . . . . . . . Disabling data collection in a single server environment . . . . . Using the Data Collector Configuration Utility . . . . . . . . Using the KD4configDC command . . . . . . . . . . . . Enabling data collection in a BEA WebLogic multi-server environment Disabling data collection in a BEA WebLogic multi-server environment Apache Axis Limitations . . . . . . . . . . . . . . . . . Additional considerations . . . . . . . . . . . . . . . . . Chapter 9. Configuring data Enabling data collection . . Disabling data collection . . Additional considerations . . collection: JBoss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161 161 161 162 163 163 165 166 166 166 167 168 170 170 171 171 173 174
Chapter 10. Configuring data collection: CICS Transaction Server . . . . 175 Chapter 11. Configuring data collection: SAP NetWeaver Enabling data collection . . . . . . . . . . . . . . All server applications under a SAP system ID . . . . . A server application not located under a SAP system ID . A standalone client application not under a SAP system ID A Web services client packaged in its own JAR file . . . A deployable client application . . . . . . . . . . . Enabling data collection using the KD4configDC command Disabling data collection . . . . . . . . . . . . . . Disabling data collection using the KD4configDC command Additional considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 178 178 179 181 183 183 184 185 187 188 191 191 192 194 198 198 199 200 201 201 202 203 204
Chapter 12. Configuring data collection: WebSphere Community Enabling WebSphere CE applications for data collection . . . . . Running the KD4configDC command . . . . . . . . . . . Enabling data collection manually . . . . . . . . . . . . Disabling data collection . . . . . . . . . . . . . . . . . Running the KD4configDC command . . . . . . . . . . . Disabling data collection manually . . . . . . . . . . . . Additional considerations . . . . . . . . . . . . . . . . . Chapter 13. Configuring data collection: The DataPower data collector as a proxy . Planning for deployment . . . . . . . Aggregation . . . . . . . . . . Deployment steps . . . . . . . .
Edition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . .
DataPower SOA Appliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Contents
Configuring the DataPower SOA appliance for monitoring. . . . . . . . . Upgrading the DataPower firmware version . . . . . . . . . . . . . Configuring a user account on the DataPower SOA appliance . . . . . . Enabling the XML Management Interface . . . . . . . . . . . . . . Checking additional optional settings . . . . . . . . . . . . . . . Configuring DataPower Processing Rules . . . . . . . . . . . . . Configuring the AAA policy . . . . . . . . . . . . . . . . . . . Enabling data collection . . . . . . . . . . . . . . . . . . . . . The DataPower configuration file . . . . . . . . . . . . . . . . . Enabling data collection using the Data Collector Configuration Utility . . . Enabling data collection using the KD4configDC command . . . . . . . Disabling data collection . . . . . . . . . . . . . . . . . . . . . Upgrading the data collector . . . . . . . . . . . . . . . . . . Disabling data collection using the Data Collector Configuration Utility . . . Disabling data collection using the KD4configDC command . . . . . . . Starting and stopping the data collector . . . . . . . . . . . . . . . Running the DataPower data collector as a Windows service or UNIX daemon Registering the DataPower data collector as a Windows service or UNIX daemon . . . . . . . . . . . . . . . . . . . . . . . . . Starting the registered DataPower data collector . . . . . . . . . . . Stopping the registered DataPower data collector. . . . . . . . . . . Removing the DataPower data collector from the list of Windows services Error handling . . . . . . . . . . . . . . . . . . . . . . . . Communicating between data collector and appliance . . . . . . . . . . Optimizing performance . . . . . . . . . . . . . . . . . . . . . Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . Communication failures . . . . . . . . . . . . . . . . . . . . Synchronizing time between computer systems . . . . . . . . . . . Password problems. . . . . . . . . . . . . . . . . . . . . . Logging and Tracing . . . . . . . . . . . . . . . . . . . . . . Displaying the DataPower Console interface . . . . . . . . . . . . . Considerations when displaying the DataPower Console view . . . . . . Chapter 14. Configuring data collection: WebSphere Upgrading the data collector directory structure . . . Enabling data collection . . . . . . . . . . . . Considerations for multiple brokers . . . . . . . Disabling data collection . . . . . . . . . . . . Considerations for multiple brokers . . . . . . . Using the Data Collector Configuration Utility . . . . Using the KD4configDC command . . . . . . . . Message Broker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
204 204 205 205 205 205 211 212 213 214 215 224 224 224 224 225 225 226 226 226 227 227 227 228 228 229 229 229 229 229 230 230 233 233 234 235 235 237 237 238
. . . . . . .
. . . . . . .
Part 3. Completing your installation . . . . . . . . . . . . . . . . . . . . . 241

Chapter 15. Verifying the installation and configuration Verifying the properties file . . . . . . . . . . . . Verifying IBM Tivoli Monitoring components . . . . . . Optional: Configuring the ITCAM for SOA monitoring agent Starting and stopping the monitoring agent . . . . . . Generating initial metric log files . . . . . . . . . . Verifying Tivoli Enterprise Portal workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 243 244 244 245 246 247
Chapter 16. Configuring for historical data collection . . . . . . . . . 251 Chapter 17. Installing Discovery Library Adapters . . . . . . . . . . 257
vi
Installation Guide
Chapter 18. Configuring for Remote Deployment . Populating the deployment depot . . . . . . . . Deploying the bundle to the remote system . . . . Upgrading a remotely deployed monitoring agent . Enabling data collection on the remote system . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
. . . . .
259 259 260 260 261
Chapter 19. Installing Language Support . . . . . . . . . . . . . . 263 Installing a language pack on a supported Windows operating system . . . . 263 Installing a language pack on a supported UNIX or Linux operating system 263 Chapter 20. Configuring IBM Tivoli Monitoring to forward events . . . . 265 Event Integration with WebSphere Service Registry and Repository . . . . . 265 Appendix A. Performing a silent installation of ITCAM for SOA . . Creating and using a Windows response file . . . . . . . . . . Running the silent installation from the command line with parameters Running the silent installation using SMS . . . . . . . . . . . Performing a silent installation on a Linux or Unix computer . . . . . Installing components with a response file . . . . . . . . . . Configuring components with a response file . . . . . . . . . . . . 267 . . . 267 268 . . . 268 . . . 268 . . . 269 . . . 270
Appendix B. Uninstalling IBM Tivoli Composite Application Manager for SOA . . . . . . . . . . . . . . . . . . . . . . . . . . Before uninstalling the monitoring agent . . . . . . . . . . . . . . Windows: Uninstalling the monitoring agent . . . . . . . . . . . . . Uninstalling Tools . . . . . . . . . . . . . . . . . . . . . Removing tables from the warehouse database . . . . . . . . . . Removing files and folders . . . . . . . . . . . . . . . . . . Removing SOA Domain Management Server and Tivoli Common Object Repository databases . . . . . . . . . . . . . . . . . . . Linux, AIX HP-UX, or Solaris: Uninstalling the monitoring agent . . . . . Uninstalling Tools . . . . . . . . . . . . . . . . . . . . . Removing tables from the warehouse database . . . . . . . . . . Removing files and folders . . . . . . . . . . . . . . . . . . Removing the SOA Domain Management Server database . . . . . .
. . . . . . . . . . . .
273 273 274 274 274 274 274 274 275 275 275 275
Appendix C. Notices . . . . . . . . . . . . . . . . . . . . . . 277 Trademarks. . . . . . . . . . . . . . . . . . . . . . . . . . 278 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Contents
vii
viii
Installation Guide
Tables
1. Supported operating systems for the monitoring agent and Tools . . . . . . . . . . . . . 4 2. Supported operating systems for the SOA Domain Management Server and Tivoli Common Object Repository. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3. Broker processes supported by operating system and version of WebSphere Message Broker 9 4. Supported versions of Middleware components. . . . . . . . . . . . . . . . . . . . 10 5. Windows operating system protocol settings for communicating between the monitoring agent and Tivoli Enterprise Monitoring Server . . . . . . . . . . . . . . . . . . . . . . . . 36 6. Linux, AIX, HP-UX, and Solaris Protocol settings for communicating between the monitoring agent and Tivoli Enterprise Monitoring Server. . . . . . . . . . . . . . . . . . . . . . . 62 7. Available properties for running the SOA Domain Management Server Configuration Utility in silent mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 8. Extraction methods and priorities used by the DataPower DC to obtain the user identity. 212 9. DataPower key and value pairs for the KD4configDC command . . . . . . . . . . . . . 216 10. Linux, AIX, HP-UX, and Solaris Protocol settings for communicating between the monitoring agent and Tivoli Enterprise Monitoring Server . . . . . . . . . . . . . . . . . . . . 245 11. Attribute groups to configure for historical data collection. . . . . . . . . . . . . . . . 252 12. Recommendations for summarization and pruning of ITCAM for SOA attribute groups . . . . . 253 13. Silent installation parameters for UNIX . . . . . . . . . . . . . . . . . . . . . . 269
ix
Installation Guide
About this publication

IBM Tivoli Composite Application Manager for SOA, version 7.1.1 delivers a comprehensive solution for managing services in a service oriented architecture (SOA) running on Web application servers. For supported distributed and managed z/OS environments, ITCAM for SOA monitors message traffic and performs simple control of messages flowing between services in the SOA. The IBM Tivoli Composite Application Manager for SOA Installation Guide provides information about installing monitoring agent functions to monitor services on Microsoft Windows, Linux, AIX, HP-UX, and Solaris computers. This product can also be installed in the z/OS environment. See IBM Tivoli Composite Application Manager for SOA library on page xiii for additional information about installing and configuring the product on the z/OS operating system.
Intended audience
This guide is for services architects and services application support personnel who install IBM Tivoli Composite Application Manager for SOA to monitor and manage services in a service oriented architecture (SOA) environment on distributed Microsoft Windows, Linux, AIX, HP-UX, and Solaris systems. The installation tasks require a working knowledge of these operating systems, and a basic knowledge of networking. This product can also be installed on the z/OS operating system, but those procedures are not covered in this document. See IBM Tivoli Composite Application Manager for SOA library on page xiii for information on available z/OS documentation. Users of this publication should be familiar with these topics: v Monitoring concepts v The commonly shared components of IBM Tivoli Management Services v The Tivoli Enterprise Portal user interface v IBM Tivoli Monitoring 6.2.0 environment v Services that you want to monitor, including Web services and services running in an enterprise service bus environment, such as DataPower, WebSphere Message Broker, or SCA applications.
What this publication contains

This publication is divided into three main parts, containing the following chapters: v Part 1 describes the procedures for upgrading or installing the IBM Tivoli Composite Application Manager for SOA product into the IBM Tivoli Monitoring environment, and includes these chapters: Chapter 1, Planning for installation, on page 3 Provides information to help you plan for the deployment and installation of the product on supported operating systems. For installation on z/OS systems, refer to the Program Directory for IBM Tivoli Composite Application Manager for SOA (GI11-8685) which is provided with the installation media for installing on z/OS operating systems. Chapter 2, Upgrading from a previous installation, on page 19
xi
Provides information on upgrading your existing IBM Tivoli Composite Application Manager for SOA installation. Chapter 3, Installing IBM Tivoli Composite Application Manager for SOA, on page 29 Provides instructions on installing monitoring agent application support for the components of IBM Tivoli Monitoring, including Tivoli Enterprise Monitoring Server, Tivoli Enterprise Portal Server, and the Tivoli Enterprise Portal desktop client. Provides instructions on installing the monitoring agent on distributed computer systems where services are to be monitored. This procedure assumes that components of IBM Tivoli Monitoring are installed on other computers in your environment. Provides instructions for installing the Tivoli Common Object Repository database, which is populated with data from one or more Discovery Library Adapters. This data is then displayed in topology views in the Tivoli Enterprise Portal. Chapter 4, Configuring topology support, on page 65 Provides information on running the SOA Domain Management Server Configuration Utility to configure SOA Domain Management Server and Tivoli Common Object Repository topology support. v Part 2 describes the procedures for enabling and disabling data collection for the various runtime environments supported with this version. Refer to these chapters for details: Chapter 5, Overview, on page 127 Chapter 6, Configuring data collection: WebSphere Application Server, on page 149 Chapter 7, Configuring data collection: Microsoft .NET, on page 159 Chapter 8, Configuring data collection: BEA WebLogic Server, on page 161 Chapter 9, Configuring data collection: JBoss, on page 171 Chapter 10, Configuring data collection: CICS Transaction Server, on page 175 Chapter 11, Configuring data collection: SAP NetWeaver, on page 177 Chapter 12, Configuring data collection: WebSphere Community Edition, on page 191 Chapter 13, Configuring data collection: DataPower SOA Appliance, on page 201 Chapter 14, Configuring data collection: WebSphere Message Broker, on page 233 v Part 3 includes additional information you need to complete the basic installation steps and verify the configuration. See these chapters for appropriate information: Chapter 15, Verifying the installation and configuration, on page 243 Chapter 16, Configuring for historical data collection, on page 251 Chapter 17, Installing Discovery Library Adapters, on page 257 Chapter 18, Configuring for Remote Deployment, on page 259 Chapter 19, Installing Language Support, on page 263 Chapter 20, Configuring IBM Tivoli Monitoring to forward events, on page 265
xii
Installation Guide
Several appendices at the end of the publication provide additional useful information: v Appendix A, Performing a silent installation of ITCAM for SOA, on page 267 v Appendix B, Uninstalling IBM Tivoli Composite Application Manager for SOA, on page 273 Provides information about uninstalling the monitoring agent. v Appendix C, Notices, on page 277 Provides IBM, Tivoli, and other company notices and trademark information as they apply to the product.
Publications
This section lists publications in the product library and other related documents. It also describes how to access Tivoli publications online and how to order Tivoli publications.
IBM Tivoli Composite Application Manager for SOA library

The IBM Tivoli Composite Application Manager for SOA library contains the following publications: v IBM Tivoli Composite Application Manager for SOA Quick Start Guide, GI11-8110 Provides a brief overview of the product, pointing you to available documentation and information on how to get started quickly. v IBM Tivoli Composite Application Manager for SOA Release Notes, GI11-4096 Provides late-breaking information about ITCAM for SOA product limitations and workarounds, and pointers to other documentation to help you begin installing and using the product. v IBM Tivoli Composite Application Manager for SOA Installation Guide, GC23-8803 Provides an overview of the IBM Tivoli Management Services environment and the planning information and procedures you need to install and upgrade the application support files and the monitoring agent in a distributed operating system environment. This guide also includes procedures for configuring support for the service-to-service topology function, including creating databases and configuring SOA Domain Management Server and Tivoli Common Object Repository in your Tivoli Enterprise Portal Server environment. This guide also includes procedures for enabling and disabling the various supported runtime environments for data collection by the ITCAM for SOA, version 7.1.1 monitoring agent, and optional administrative tasks to further configure your installation. This product can also be installed in the z/OS operating system enterprise environment. Refer to the Program Directory for IBM Tivoli Composite Application Manager for SOA, V7.1.1, Program Number 5698-B16, for Use with z/OS, GI11-8685, provided with the z/OS version of the product for information on installing and upgrading the monitoring agent. v IBM Tivoli Composite Application Manager for SOA Users Guide, SC23-8804 Provides information on monitoring and managing resources in the Tivoli Enterprise Portal environment, including details about Take Action commands, situations, workspaces and views, including service-to-service topology workspaces and views. Some problem determination information about the various components of ITCAM for SOA is also provided, as well as information
xiii
about log files and informational, warning, and error messages. This publication complements the Tivoli Enterprise Portal online help information for this monitoring agent. v Configuring IBM Tivoli Composite Application Manager for SOA on z/OS, SC32-9493 Provides information about configuring ITCAM for SOA to operate in the z/OS operating system environment. Before using this publication, you must complete the installation procedures as documented in the Program Directory for IBM Tivoli Composite Application Manager for SOA, V7.1 for Use with z/OS, GI11-8685. This publication is written for system administrators and others who are responsible for installing and configuring ITCAM for SOA in the z/OS environment. v IBM Tivoli Composite Application Manager for SOA Tools, GC32-1539 Provides information about installing and using the following tools: The IBM Web Services Navigator, an Eclipse based plugin for extracting services information that has been collected by monitoring agents and stored, either locally or in a historical database. This tool provides the capability to retrieve historical metric data from a connected database, or assemble several locally stored metric and content log files, and display the resulting data in several views to assist a services architect in visualizing relationships between services. A set of managed SCA mediation primitives that you can insert into the wiring of a mediation flow component using the WebSphere Integration Developer (WID) tooling. An operator can then use IBM Tivoli Composite Application Manager for SOA to set and change, at run time, the behavior of the mediations by turning on and off the individual primitives by name. Eclipse is an open source community whose projects are focused on providing an extensible development platform and application frameworks for building software. Eclipse provides extensible tools and frameworks that span the software development lifecycle, including support for modeling, language development environments for Java, C/C++, PHP and others, testing and performance, business intelligence, rich client applications and embedded development. A large, vibrant ecosystem of major technology vendors, innovative start-ups, universities and research institutions and individuals extend, complement and support the Eclipse Platform. The Eclipse Foundation is a not-for-profit, member supported corporation that hosts the Eclipse projects. Full details of Eclipse and the Eclipse Foundation are available at www.eclipse.org. v IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide, xxxx-xxxx Provides information about recovering from problems that you might encounter while installing, configuring, and using the product. Typical problem scenarios are described, and recovery procedures are provided. Error messages for the product are also documented in this guide. v IBM Tivoli Composite Application Manager for SOA User Assistance User assistance is available from the online help system in the Tivoli Enterprise Portal, helps operators understand and use the provided data, attributes, commands, and situations to monitor performance and availability, in the context of the product.
xiv
Installation Guide
An index is provided for searching the library. If you have Adobe Acrobat on your system, you can use the Search command to locate specific text in the library. For more information about using the index to search the library, see the online help for Acrobat. For the latest product information on IBM Tivoli Composite Application Manager for SOA, including a link to the product documentation and updated troubleshooting information through Technotes, see the IBM Support Web site for IBM Tivoli Composite Application Manager for SOA at:
http://www.ibm.com/software/sysmgmt/products/support /IBMTivoliCompositeApplicationManagerforSOA.html
Related publications
IBM Tivoli Composite Application Manager for SOA version 7.1.1 is provided as a monitoring agent that operates in the IBM Tivoli Monitoring environment. For the latest product information on IBM Tivoli Monitoring, including a link to the product documentation and updated troubleshooting information through Technotes, see the IBM Support Web site for IBM Tivoli Monitoring at:
http://www.ibm.com/software/sysmgmt/products/support/IBMTivoliMonitoringV6.html
Accessing terminology online

The Tivoli Software Glossary includes definitions for many of the technical terms related to Tivoli software. The Tivoli Software Glossary is available at the following Tivoli software library Web site:
http://publib.boulder.ibm.com/tividd/glossary/tivoliglossarymst.htm
Access the glossary by clicking the Glossary link on the left pane of the Tivoli software library window. The IBM Terminology Web site consolidates the terminology from IBM product libraries in one convenient location. You can access the Terminology Web site at the following Web address:
http://www.ibm.com/software/globalization/terminology
Accessing publications online

The documentation media contains the publications that are in the product library. The format of the publications is in PDF and HTML. IBM posts publications for this and all other Tivoli products, as they become available and whenever they are updated, to the Tivoli software information center Web site at
http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/index.jsp
Note: If you print PDF documents on other than letter-sized paper, set the option in the File Print window that allows Adobe Reader to print letter-sized pages on your local paper. The IBM Software Support Web site provides the latest information about known product limitations and workarounds in the form of technotes for your product. You can view this information at the following Web site:
http://www.ibm.com/software/support
xv
Ordering publications
You can order many IBM and Tivoli publications online at the following Web site:
http://www.elink.ibmlink.ibm.com/publications/servlet/pbi.wss
You can also order by telephone by calling one of these numbers: v In the United States: 800-879-2755 v In Canada: 800-426-4968 In other countries, contact your software account representative to order Tivoli publications. To locate the telephone number of your local representative, perform the following steps: 1. Go to http://www.elink.ibmlink.ibm.com/publications/servlet/pbi.wss. 2. Select your country from the list and click Go. 3. Click About this site in the main panel to see an information page that includes the telephone number of your local representative.
Accessibility
Accessibility features help users with a physical disability, such as restricted mobility or limited vision, to use software products successfully. With this product, you can use assistive technologies to hear and navigate the interface. You can also use the keyboard instead of the mouse to operate most features of the graphical user interface. See the IBM Tivoli Monitoring documentation for more information about accessibility features in the IBM Tivoli Monitoring environment.
Tivoli technical training

For Tivoli technical training information, refer to the following IBM Tivoli Education Web site: http://www.ibm.com/software/tivoli/education/
Support information
If you have a problem with your IBM software, you want to resolve it quickly. IBM provides the following ways for you to obtain the support you need: Online Go to the IBM Software Support site at http://www.ibm.com/software/ support/probsub.html and follow the instructions. IBM Support Assistant The IBM Support Assistant (ISA) is a free local software serviceability workbench that helps you resolve questions and problems with IBM software products. The ISA provides quick access to support-related information and serviceability tools for problem determination. To install the ISA software, go to http://www.ibm.com/software/support/isa. For updated support information for IBM Tivoli Composite Application Manager for SOA go to http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/ index.jsp?toc=/com.ibm.itcamsoa.doc/toc.xml and click Support for Composite Application Manager for SOA.
xvi
Installation Guide
Problem determination guidance For more information about resolving problems, see the problem determination information in this guide and in the IBM Tivoli Composite Application Manager for SOA Users Guide.
Conventions used in this publication

This publication uses several conventions for special terms and actions, and operating system-dependent commands and paths.
Typeface conventions
This publication uses the following typeface conventions: Bold v Lowercase commands and mixed case commands that are otherwise difficult to distinguish from surrounding text v Interface controls (check boxes, push buttons, radio buttons, spin buttons, fields, folders, icons, list boxes, items inside list boxes, multi-column lists, containers, menu choices, menu names, tabs, property sheets), labels (such as Tip:, and Operating system considerations:) v Keywords and parameters in text Italic v Words defined in text v Emphasis of words to signify importance v New terms in text (except in a definition list) v Variables and values you must provide Monospace v Examples and code examples v File names, programming keywords, and other elements that are difficult to distinguish from surrounding text v Message text and prompts addressed to the user v Text that the user must type v Values for arguments or command options
Operating system-dependent variables and paths

The direction of the slash for directory paths might vary in this documentation. No matter which type of slash you see in the documentation, use the following guidelines for a slash: v If using Linux, AIX, HP-UX, or Solaris operating systems, use a forward slash (/). v If using Windows operating systems, use a backslash (\). The names of environment variables are not always the same in Windows, Linux, AIX HP-UX, or Solaris operating systems. For example, %TEMP% in Windows is equivalent to $tmp in Linux, AIX, HP-UX, and Solaris operating systems. For environment variables, use the following guidelines: v If using Linux, AIX, HP-UX, or Solaris operating systems, use $variable. v If using Windows operating systems, use %variable%.
xvii
Note: If you are using the bash shell on a Windows operating system, you can use the Linux, AIX, HP-UX, or Solaris operating system conventions.
Tivoli command syntax

The following special characters define Tivoli command syntax: [] ... Identifies elements that are optional. Required elements do not have brackets around them. Indicates that you can specify multiple values for the previous element. Separate multiple values by a space, unless otherwise directed by command information. If the ellipsis for an element follows a closing bracket, use the syntax within the brackets to specify multiple values. For example, to specify two administrators for the option [-a admin]..., use -a admin1 -a admin2. If the ellipsis for an element is within the brackets, use the syntax of the last element to specify multiple values. For example, to specify two hosts for the option [-h host...], use -h host1 host2. | {} Indicates mutually exclusive information. You can use the element on either the left or right of the vertical bar. Delimits a set of mutually exclusive elements when a command requires one of them. Brackets ([ ]) are around elements that are optional.
In addition to the special characters, Tivoli command syntax uses the typeface conventions described in Typeface conventions on page xvii. The following example illustrates the typeface conventions used in Tivoli command syntax: KD4configDC {-enable | -disable} -env 8 -host {hostname | ip_address} -user user_ID [-pswd password] [-port port number] [-path path string] [-poll polling interval] [-domainlist "domainA,domainB, ..."] [-displaygroup display_group] This example is specific to the KD4configDC command syntax when the -env parameter is set to 8 (see the documentation for additional valid values for this parameter). In this example, the -env parameter is required, and when the value of -env is set to 8, the -host and -user parameters are required. The braces surrounding {-enable|-disable} indicate that you must specify whether to enable or disable data collection, and the braces surrounding {hostname|ip_address} indicate that the host value must be expressed as either a host name or an IP address. The brackets around the -pswd, -port, -path, -poll, -domainlist, and -displaygroup parameters indicate that they are optional.
Resolving directory path variables

This section describes directory path naming conventions used in this guide.
The ITM home directory

Throughout this guide, reference is made to the <ITM_Home> variable, which is the directory location where IBM Tivoli Monitoring is installed. These are the default operating system dependent values for this variable: v For Windows: C:\IBM\ITM\ v For Linux, HP-UX, AIX, and Solaris: /opt/IBM/ITM v For z/OS UNIX System Services: /CandleHome
xviii
Installation Guide
Note: For z/OS operating systems, you specify the value of <ITM_Home> for the HFS CandleHome directory parameter when you are configuring the ITCAM for SOA monitoring agent. If you installed IBM Tivoli Monitoring in a different directory location, substitute your install path location for <ITM_Home>.
The IBM Tivoli Composite Application Manager for SOA home directory
Throughout the product library, reference is made to the <ITCAM4SOA_Home> variable, which is the directory location where IBM Tivoli Composite Application Manager for SOA monitoring agent is installed in the IBM Tivoli Monitoring environment. These are the default operating system dependent values for this variable: v For Windows systems: <ITM_Home>\TMAITM6 v For Linux, HP-UX, AIX, and Solaris systems: <ITM_Home>/<platform>/d4 v For z/OS systems: <ITM_Home>
Determining the platform value in directory paths

Throughout this product library, reference is made to the <platform> variable, which is part of the Linux or UNIX directory path specification for certain files that you need to access, for example:
<ITM_Home>/<platform>/<product>
In this example, the two-character <product> variable is also part of the directory path, and is typically specified as cq, d4, or iw in this guide. On supported Linux and UNIX operating systems, you can find the value for <platform> with this short procedure: 1. From a command prompt, navigate to the <ITM_Home>/bin directory. 2. Run the following command:
./cinfo -d
3. Locate the line for product code <product>, for example: cq iw d4 Locate this product code when you are looking up the <platform> value for Tivoli Enterprise Portal Server. Locate this product code when you are looking up the <platform> value for Tivoli Enterprise Portal Server Extension.
Locate this product code when you are looking up the <platform> value for the IBM Tivoli Composite Application Manager for SOA monitoring agent. The platform designation is found under the Platform column. The platform designation depends on the operating system, the computer type, and the version of IBM Tivoli Monitoring that is installed. The platform for the d4 product code is typically not the same as for the cq and iw product codes. The following example shows the output of the cinfo command when ITCAM for SOA version 7.1.1 and IBM Tivoli Monitoring version 6.2.1 are installed on a supported Red Hat Linux operating system on a 32bit Intel computer:
"ProdCode","Description","Platform","Version","Release" "ax","IBM Tivoli Monitoring Shared Libraries","li6263","06210000","100"
xix
"cq","Tivoli Enterprise Portal Server","li6263","06210000","100" "cw","Tivoli Enterprise Portal Browser Client","li6263","06210000","100" "d4","ITCAM for SOA","li6243","07110000","100" "gs","IBM Tivoli GSKit","li6243","07303100","100" "iw","IBM Tivoli Enterprise Portal Server Extensions","li6263","06101300","100" "jr","Tivoli Enterprise-supplied JRE","li6263","05050000","100" "kf","IBM Eclipse Help Server","li6263","06210000","100" "ms","Tivoli Enterprise Monitoring Server","li6263","06210000","100" "sh","Tivoli Enterprise Monitoring SOAP Server","li6263","06210000","100" "ui","Tivoli Enterprise Services User Interface","li6263","06210000","100"
This example shows the following information: v li6263 is the platform for Tivoli Enterprise Portal Server (product code cq ) v li6243 is the platform for the ITCAM for SOA monitoring agent (product code d4) v li6263 is the platform for Tivoli Enterprise Portal Server Extensions (product code iw)
xx
Installation Guide
Part 1. Installing the product

This part of the guide describes the procedures for upgrading or installing the IBM Tivoli Composite Application Manager for SOA product into the IBM Tivoli Monitoring environment, including: v Planning for installation, including system requirements, database support, an overview of the installation process, and certain considerations to keep in mind. v Upgrading or installing application support for distributed IBM Tivoli Monitoring components v Upgrading or installing the ITCAM for SOA monitoring agent on computer systems in your environment where services are being monitored v Configuring additional support for the service-to-service topology function, including configuring SOA Domain Management Server and Tivoli Common Object Repository in your Tivoli Enterprise Monitoring Serverenvironment v Configuring your runtime environment for data collection by ITCAM for SOA v Additional administrative tasks you can complete to further configure your installation. These chapters are included in this part of the guide: v Chapter 1, Planning for installation, on page 3 v Chapter 2, Upgrading from a previous installation, on page 19 v Chapter 3, Installing IBM Tivoli Composite Application Manager for SOA, on page 29 v Chapter 4, Configuring topology support, on page 65
Installation Guide
Chapter 1. Planning for installation

This chapter describes the overall prerequisites and procedures for installing or upgrading IBM Tivoli Composite Application Manager for SOA (ITCAM for SOA) in supported versions of the IBM Tivoli Monitoring environment. As you plan to install or upgrade ITCAM for SOA in your environment, you should become familiar with the following information: v Supported hardware platforms and operating systems for the various components of IBM Tivoli Monitoring and ITCAM for SOA. v Understanding your distributed IBM Tivoli Monitoring environment, to install ITCAM for SOA application support files and the monitoring agent where services are being monitored. v Database support for storing relationship and topology information, and historical metric data that is retrieved and displayed in your Tivoli Enterprise Portal workspaces and views and in the IBM Web Services Navigator tool and Tivoli Common Reports. v Installing the various components of ITCAM for SOA using several installation programs based on the InstallShield MultiPlatform (ISMP) tool. This also includes Eclipse-based tools, and methods of installing support for displaying topology data. v A set of discovery library adapters that is provided with this product. See the book, IBM Tivoli Composite Application Manager for SOA Discovery Library Adapters for additional planning and installation information.
Supported hardware platforms and operating systems

If you are installing IBM Tivoli Composite Application Manager for SOA version 7.1.1 on a supported Windows, Linux, AIX, HP-UX, or Solaris operating system, familiarize yourself with the following software and hardware prerequisites. See also the IBM Tivoli Composite Application Manager for SOA Release Notes, (GI11-4096), which contains late-breaking information that might replace information in this document or in other installation guides. Refer to the planning and installation information in the IBM Tivoli Monitoring Installation and Setup Guide (GC32-9407) provided with IBM Tivoli Monitoring. If you plan to write historical data to a warehouse database for later retrieval and analysis by Tivoli Enterprise Portal workspaces, the IBM Web Services Navigator or Tivoli Common Reporting, see the additional information about setting up data warehousing (including configuring the Warehouse Proxy agent and Summarization and Pruning agent). If you are installing IBM Tivoli Composite Application Manager for SOA on a supported z/OS operating system, refer to the Program Directory for IBM Tivoli Composite Application Manager for SOA (GI11-8685) for those installation procedures, and then refer to Configuring IBM Tivoli Composite Application Manager for SOA on z/OS (SC32-9493) for additional configuration information. Other environment planning decisions about the Tivoli Enterprise Monitoring Server on z/OS are found in Configuring Tivoli Enterprise Monitoring Server on z/OS (SC32-9463).
Software and hardware prerequisites

The following sections provide specific information about the memory, software, and hardware requirements for installing the IBM Tivoli Composite Application Manager for SOA monitoring agent and Tools in the IBM Tivoli Monitoring environment. Versions of all the required products are provided in the product package. However, if you already have a supported version of IBM Tivoli Monitoring installed in your enterprise, you can use the currently installed product, provided that you upgrade the IBM Tivoli Monitoring environment to any of these minimum supported levels: v IBM Tivoli Monitoring version 6.1 Fix Pack 7 (or later fix pack) for the ITCAM for SOA monitoring agent and data collector components v IBM Tivoli Monitoring version 6.2 v IBM Tivoli Monitoring version 6.2 Fix Pack 1 (or later fix pack) v IBM Tivoli Monitoring version 6.2.1 Warehouse Summarization and Pruning: If you plan to enable summarization and pruning of the ITCAM for SOA attribute groups, you should use either IBM Tivoli Monitoring version 6.2 Fix Pack 2 (or later fix pack), or IBM Tivoli Monitoring version 6.2.1 Interim Fix 1 (or later interim fix). IBM Tivoli Monitoring version 6.2.1 is provided with this release of IBM Tivoli Composite Application Manager for SOA for your convenience.
Supported operating systems

Table 1 identifies the supported operating systems for installing IBM Tivoli Composite Application Manager for SOA monitoring agents and Tools in the IBM Tivoli Monitoring environment.
Table 1. Supported operating systems for the monitoring agent and Tools IBM Tivoli Composite Application Manager for SOA monitoring agent X X X X X IBM Tivoli Composite Application Manager for SOA Tools (see Note #3 below)
Operating system AIX V5.1 AIX V5.2 AIX V5.3 (32-bit, 64-bit) AIX V6.1 (64-bit) Solaris Operating Environment V8 (SPARC) (32-bit, 64-bit) Solaris Operating Environment V9 (SPARC) (32-bit, 64-bit) Solaris Operating Environment V10 (SPARC) (32-bit, 64-bit) HP-UX 11i v1 on PA-RISC(*) (32-bit, 64-bit) HP-UX 11i v2 on PA-RISC(*) (32-bit, 64-bit)
Installation Guide
Table 1. Supported operating systems for the monitoring agent and Tools (continued) IBM Tivoli Composite Application Manager for SOA monitoring agent X IBM Tivoli Composite Application Manager for SOA Tools (see Note #3 below)
Operating system HP-UX 11i v3 on PA-RISC(*) (32-bit, 64-bit) HP-UX 11i v2 on Itanium (IA64) HP-UX 11i v3 on Itanium (IA64) Windows 2000 Professional Windows 2000 Server Windows 2000 Advanced Server Windows 2003 Server Standard and Standard R2 32 bit Windows 2003 Server Enterprise and Enterprise R2 32 bit Windows 2003 Server Standard and Standard R2 x86-64 bit Windows 2003 Server Enterprise and Enterprise R2 x86-64 bit Windows 2003 Server Data Center 32 bit Windows 2003 Server Data Center x86-64 bit Windows XP Professional Windows 2008 Server Standard (32bit, 64bit) Windows 2008 Server Enterprise (32bit, 64bit) Windows Vista Enterprise (32bit) z/OS 1.8 and later RedHat Enterprise Linux Advanced Server and Enterprise Server v3(x86-32)
X X X X X X X X X X
X X X See Note #3 below.
X X X X
See Note #3 below.
X X X
See Note #2 below.
Table 1. Supported operating systems for the monitoring agent and Tools (continued) IBM Tivoli Composite Application Manager for SOA monitoring agent X IBM Tivoli Composite Application Manager for SOA Tools (see Note #3 below)
Operating system RedHat Enterprise Linux Advanced Server and Enterprise Server v3 (zSeries) RedHat Enterprise Linux v4 (x86-32) RedHat Enterprise Linux v4 (iSeries, pSeries, zSeries, AMD64/EM64T, x8664) RedHat Enterprise Linux v5 (x86-32) RedHat Enterprise Linux v5 (iSeries, pSeries, zSeries, AMD64/EM64T, x8664) SuSE Linux Enterprise Server v8 (x86-32) SuSE Linux Enterprise Server v8 (zSeries) SuSE Linux Enterprise Server v9 (x86-32) SuSE Linux Enterprise Server v9 (iSeries, pSeries, zSeries, AMD64/EM64T, x8664) SuSE Linux Enterprise Server v10 (x86-32) SuSE Linux Enterprise Server v10 (iSeries, pSeries, zSeries, AMD64/EM64T, x8664)
X X
X X
X X X X
X X
Notes: 1. (*) For this release, only a subset of application server runtime environments are supported on HP-UX on PA-RISC. These are the supported application server environments: v WebSphere Application Server version 6.0.2 v WebSphere Application Server version 6.1 v WebSphere Application Server version 7.0 v IBM WebSphere Process Server version 6.0, 6.1, and 6.2 v IBM WebSphere Enterprise Service Bus version 6.0, 6.1, and 6.2 2. The IBM Web Services Navigator tool is supported on the Microsoft Vista operating system if you install it into an existing Eclipse, Rational Application
Installation Guide
Developer, Rational Software Architect, or WebSphere Integration Developer environment and that environment also supports this operating system. Managed SCA mediation primitives are supported in Microsoft Vista if your version of WebSphere Integration Developer supports this operating system. 3. The IBM Tivoli Composite Application Manager for SOA Tools column in this table indicates the operating systems into which the ITCAM for SOA Tools can be installed. If you plan to install the tools into WebSphere Integration Developer, Rational Application Developer, Rational Software Architect, or an existing Eclipse environment, you must also verify that the version of those environments that you plan to use also supports the appropriate operating system listed in this table. 4. The monitoring agent is supported on Windows 2008, but only if you install IBM Tivoli Monitoring as the Administrator user on Windows 2008. See the tech note at http://www-01.ibm.com/support/docview.wss?uid=swg21303845 for installation and runtime limitations for this operating system. 5. See the Tivoli Platform and Database Support Matrix at this link to determine if additional operating systems have been certified for use with ITCAM for SOA version 7.1.1:
http://www.ibm.com/support/docview.wss?rs=203&uid=swg21067036
6. See your IBM Tivoli Monitoring documentation for operating system patches that may be required on these operating systems. The SOA Domain Management Server and Tivoli Common Object Repository do not support all the operating systems where Tivoli Enterprise Portal Server is supported. Table 2 specifies the operating systems supported by SOA Domain Management Server and Tivoli Common Object Repository.
Table 2. Supported operating systems for the SOA Domain Management Server and Tivoli Common Object Repository Operating system AIX V5.3 (32-bit, 64-bit) (*) AIX V6.1 (64-bit) Windows 2000 Server Windows 2000 Advanced Server Windows 2003 Server Standard Edition and Standard Edition R2 (32-bit, 64-bit) Windows 2003 Server Enterprise Edition and Enterprise R2 Edition (32-bit, 64-bit) Windows 2008 Server Standard and Enterprise Editions (32-bit and 64-bit) RedHat Enterprise Linux v4 (Intel 32-bit) RedHat Enterprise Linux v4 (zSeries) (31-bit and 64-bit) RedHat Enterprise Linux v5 (Intel 32-bit) RedHat Enterprise Linux v5 (zSeries) (31-bit and 64-bit) SuSE Linux Enterprise Server v9 (Intel 32-bit) SuSE Linux Enterprise Server v9 (zSeries) (31-bit and 64-bit) SOA Domain Management Server and Tivoli Common Object Repository X X X X X X See Note #2 below. X X X X X X
Table 2. Supported operating systems for the SOA Domain Management Server and Tivoli Common Object Repository (continued) Operating system SuSE Linux Enterprise Server v10 (Intel 32-bit) SuSE Linux Enterprise Server v10 (zSeries) (64-bit) SOA Domain Management Server and Tivoli Common Object Repository X X
Notes: 1. (*) For more information on this operating system, see Tivoli Enterprise Portal Server virtual memory errors on the AIX operating system. 2. The SOA Domain Management Server and Tivoli Common Object Repository is supported on Windows 2008, but only if you install IBM Tivoli Monitoring as the Administrator user on Windows 2008. See the tech note at http://www-01.ibm.com/support/docview.wss?uid=swg21303845 for installation and runtime limitations for this operating system. 3. Verify that your version of IBM Tivoli Monitoring supports Tivoli Enterprise Portal Server on the operating system where you plan to install SOA Domain Management Server and Tivoli Common Object Repository. See the IBM Tivoli Monitoring documentation for the list of supported operating systems. The IBM Tivoli Monitoring documentation also indicates whether Tivoli Enterprise Portal is supported in 64-bit mode on a 64-bit computer. 4. See the Tivoli Platform and Database Support Matrix at this link to determine if additional operating systems have been certified for use with ITCAM for SOA version 7.1.1:
Tivoli Enterprise Portal Server virtual memory errors on the AIX operating system
If you install the Tivoli Enterprise Portal Server on the AIX operating system, perform the procedure described in the IBM Tivoli Monitoring technote (TEPS crash sig 11 or loop virtual memory shortage AIX only). This procedure prevents virtual memory errors on the Tivoli Enterprise Portal Server especially when it is used with a DB2 database server. If you do not perform this procedure, you might not see the correct metrics in the Operational Flow workspaces when you specify a time frame that retrieves metrics from the Tivoli Data Warehouse. For more information on this problem, refer to the tech note at this Web location:
WebSphere Message Broker cross product dependency

The IBM Tivoli Composite Application Manager for SOA Version 7.1.1 message broker data collector supports new versions of WebSphere Message Broker, and provides support for both 32-bit and 64-bit broker processes on various platforms. Table 3 on page 9 describes the specific operating system, version of WebSphere Message Broker, and bit mode combinations that are supported.
Installation Guide
Table 3. Broker processes supported by operating system and version of WebSphere Message Broker Operating system AIX HP-Itanium Linux-x86 Linux-ppc Linux-s390 Solaris-SPARC Windows z/OS X X X X X X X X X WebSphere Message Broker 6.0 32-bit process X X X 64-bit process WebSphere Message Broker 6.1 32-bit process X 64-bit process X X X X X X
The WebSphere Message Broker data collector is supported on all operating systems supported by IBM Tivoli Composite Application Manager for SOA except for HP-UX PA-RISC which is supported for the WebSphere Application Server data collector.
Required hardware
Generally, there are no additional requirements for the IBM Tivoli Composite Application Manager for SOA monitoring agent above the required hardware for the IBM Tivoli Monitoring environment. See the IBM Tivoli Monitoring documentation for more information. These would be typical minimum system requirements: v Minimum CPU Requirements for the computer where Tivoli Enterprise Portal Server is installed: 1 CPU at 2 GHZ v Memory required to run SOA Domain Management Server and Tivoli Common Object Repository where Tivoli Enterprise Portal Server is installed: 2 GB v Additional disk space for application support files on the computer where Tivoli Enterprise Portal Server is installed: 450 MB If you choose to install and configure the optional Tivoli Common Object Repository as part of the Tivoli Enterprise Portal Server, you need to add 1 GB of additional disk space for the for Tivoli Common Object Repository database. Ensure that this space is available on the database server, which can either be on the same computer as Tivoli Enterprise Portal Server or on a separate computer. If you are using the WebSphere Service Registry and Repository Discovery Library Adapter and you have a large number of Web Services Description Language documents (more than 100) then you should also add the size of your Web Services Description Language documents (and any .XSD or WS-Policy documents that they reference) when estimating the Tivoli Common Object Repository database size or configure the discovery library adapter so that it does not include Web Services Description Language documents in the data that it discovers. Refer to the IBM Tivoli Composite Application Manager for SOA Discovery Library Adapters guide for more information on this discovery library adapter. If you choose to install and configure the optional SOA Domain Management Server as part of the Tivoli Enterprise Portal Server, you need to add additional disk space
for the SOA Domain Management Server database. The amount of space to add depends on the number of call relationships between operation instances that will be discovered by the ITCAM for SOA data collectors. The following range of sizes provides a general guideline for planning: v 1 to 1000 relationships: 400 MB v 1000 to 10,000 relationships: 3 GB v 10,000 to 25,000 relationships: 7 GB v 25,000 to 50,000 relationships: 12 GB v 50,000 to 70,000 relationships: 17 GB Ensure that this space is available on the database server, which can either be on the same computer as Tivoli Enterprise Portal Server or on a separate computer. If you enable message content logging or historical data collection, you need to plan for more storage space, depending on the amount of Web services traffic data you plan to collect. Be sure to plan the size of your warehouse database to ensure that you have a large enough database server to contain your data. See the IBM Tivoli Monitoring Installation and Setup Guide for planning considerations for estimating the size of your Tivoli Data Warehouse database. The guide references a spreadsheet that describes how to estimate the size of the warehouse. This spreadsheet has a tab for the ITCAM for SOA monitoring agent. To determine which ITCAM for SOA attribute groups can be enabled for historical data collection, see Chapter 16, Configuring for historical data collection, on page 251.
Required software
The following software is required for IBM Tivoli Composite Application Manager for SOA: v IBM Tivoli Monitoring, at one of these supported versions: Version 6.1 with Fix Pack 7 (or later fix pack) for the ITCAM for SOA monitoring agent and data collector components Version 6.2 Version 6.2 with Fix Pack 1 (or later fix pack) Version 6.2.1 v Middleware components:
Table 4. Supported versions of Middleware components Middleware component IBM WebSphere Application Server (32 bit Edition or 64 bit Edition) Supported versions v5.1.0.5 with PQ89492 or later fix packs v6.0.1.x v6.0.2.x v6.1.x (non-restricted mode) v6.1.x with WebSphere Feature Pack for Web Services (note: use of this feature pack is optional) v7.0.x IBM WebSphere Business Integration Server v5.1.1.1 Foundation
10
Installation Guide
Table 4. Supported versions of Middleware components (continued) Middleware component IBM WebSphere Process Server IBM WebSphere Enterprise Service Bus IBM CICS Transaction Server BEA WebLogic Server Microsoft .NET
Supported versions v6.0.1.x, v6.0.2.x, v6.1.x, v6.2.x v6.0.1.x, v6.0.2.x, v6.1.x, v6.2.x v3.x with at least the version 3.1 maintenance level applied v8.1 SP4, v8.1 SP5, v9.1, v9.2 v1.1 with Service Pack 1 v2.0 v3.0
JBoss WebSphere Community Edition SAP NetWeaver IBM WebSphere DataPower SOA Appliance (XS40 and XI50 Models)
v4.0.3 v1.0.1.1 (v1.0.1.2 on AIX) v6.40 with Service Pack 9 or later service packs (but not versions after 6.40) Firmware version 3.6.1 or later for monitoring the Web Services proxy Firmware version 3.7.1 Fix Pack 4 or later for monitoring Multi-Protocol Gateway
Apache Axis SOAP engine (with all v1.2 supported versions of BEA WebLogic Server) v1.3 v1.4 IBM WebSphere Message Broker (32-bit, 64-bit) (see Note 1) v6.0.0.5 (Version 6.0 Fix Pack 5 or later) v6.1.0.2 (Version 6.1 Fix Pack 2 or later)
Notes: 1. Refer to Table 3 on page 9 for the operating systems and WebSphere Message Broker versions for which ITCAM for SOA supports 32-bit and 64-bit processes. 2. See the Tivoli Platform and Database Support Matrix at this link to determine if additional application server environments have been certified for use with ITCAM for SOA version 7.1.1:
v Tivoli Data Warehouse database: IBM DB2 Universal Database v8.1 with Fix Pack 10 or later Fix Packs IBM DB2 Universal Database v8.2 Fix Pack 3 or later Fix Packs IBM DB2 Universal Database v9.1 and Fix Packs IBM DB2 Universal Database v9.5 and Fix Packs Microsoft SQL Server 2000 with service pack 3 Microsoft SQL Server 2005 Microsoft SQL Server 2008 Oracle v9.2, 10g Release 1 or 2, and 11g (supported for warehouse database only, not the Tivoli Enterprise Portal Server database or SOA Domain Management Server database) Each database requires a JDBC driver:
11
JDBC-DB2 for DB2 MS SQL JDBC driver for MS SQL Oracle JDBC driver for Oracle Note: See your IBM Tivoli Monitoring documentation for more details on the warehouse database support and to verify the operating systems on which these database versions are supported, and whether your version of IBM Tivoli Monitoring supports all of these database versions. v Tivoli Common Object Repository database: IBM DB2 Universal Database v8.1 with Fix Pack 10 or later Fix Packs (32/64 bit) IBM DB2 Universal Database v8.2 with Fix Pack 3 or later Fix Packs (32/64 bit) IBM DB2 Universal Database v9.1 with Fix Pack 3a or later Fix Packs (32/64 bit) IBM DB2 Universal Database v9.5 and Fix Packs (with IBM Tivoli Monitoring version 6.2.1 or later) v SOA Domain Management Server database: Microsoft SQL Server 2000 with service pack 3 and later service packs (when Microsoft SQL Server is installed on Windows operating systems) Microsoft SQL Server 2005 with service packs (when Microsoft SQL Server is installed on Windows operating systems) IBM DB2 Universal Database v8.1 with Fix Pack 10 or later Fix Packs (32/64 bit) IBM DB2 Universal Database v8.2 with Fix Pack 3 or later Fix Packs (32/64 bit) IBM DB2 Universal Database v9.1 with Fix Pack 3a or later Fix Packs (32/64 bit) IBM DB2 Universal Database v9.5 and Fix Packs (with IBM Tivoli Monitoring version 6.2.1 or later) v Web browser: If you are running the Tivoli Enterprise Portal browser client, Internet Explorer version 6 or later with the Java 1.5 Plug-in. Mozilla Firefox browser is also supported. See the IBM Tivoli Monitoring documentation for more information on configuring Tivoli Enterprise Portal browser clients. v Eclipse: If you plan to use the IBM Web Services Navigator tool to view Web services data, you must install it into a supported version of Eclipse. See IBM Tivoli Composite Application Manager for SOA Tools for more information. v WebSphere Integration Developer: If you plan to use the managed SCA mediation primitives provided with IBM Tivoli Composite Application Manager for SOA Tools, you must install them into either WebSphere Integration Developer version 6.0.1 or version 6.0.2 or version 6.1.
Understanding your IBM Tivoli Monitoring distributed environment

This publication is written assuming that you are already familiar with the IBM Tivoli Monitoring management infrastructure installed in a distributed enterprise environment, including the use of the Tivoli Enterprise Portal (also referred to as either the desktop client or the browser client) to navigate workspaces and views, the Tivoli Enterprise Monitoring Server (referred to as the monitoring server), and
12
Installation Guide
Tivoli Enterprise Portal Server (referred to as the portal server), and how they are controlled using the Manage Tivoli Enterprise Monitoring Services utility. Refer to the documentation provided with IBM Tivoli Monitoring for more information.
Data collector considerations

As you plan to upgrade or install IBM Tivoli Composite Application Manager for SOA into your runtime environment, note that you must disable and re-enable data collection during the upgrade process. Due to shared code between supported runtime environments (IBM WebSphere Application Server, JBoss, and BEA WebLogic Server in particular), be sure to follow this general procedure when upgrading existing runtime environments: 1. Disable data collection for any existing ITCAM for SOA data collector runtime environments before upgrading or installing ITCAM for SOA version 7.1.1. Refer to your current ITCAM for SOA documentation for specific procedures on disabling data collection for your supported runtime environments. 2. Upgrade or install your ITCAM for SOA product to version 7.1.1, following the procedures in this guide. 3. Re-enable data collection after installation completes for these existing runtime environments that are deployed on the same system, to ensure that all data collectors on the local computer system are running at the same product level for all runtime environments. See Part 2, Configuring for data collection, on page 125 details on enabling your runtime environments for data collection. The computer systems on which you install ITCAM for SOA might already have applications (or servers, depending on your runtime environment) enabled for other ITCAM for SOA data collectors. Any combination of supported ITCAM for SOA data collector types (for WebSphere, JBoss, DataPower, and others) can coexist on a single system, however each data collector type must be operating at the same level on any one system. You can enable applications (or servers) for as many environment types as you choose. Note that throughout this document we refer to enabling applications for data collection, but for environments such as WebSphere, assume we are referring to enabling the server. User permissions: Enabling and disabling data collection requires the user to have permissions to update the application server environment. See Part 2, Configuring for data collection, on page 125 for details on the requirements for each unique application server environment.
Planning database support

This section discusses considerations for database support for collection of historical data and discovered relationship information.
Database support for historical data collection

This release of IBM Tivoli Composite Application Manager for SOA supports IBM DB2, Oracle, and Microsoft SQL Server warehouse databases for collection of historical data. You might need to consult your local system or database administrator to set up the database if it is not already defined, or refer to your IBM Tivoli Monitoring documentation for the procedures to follow, including these tasks: v Creating user IDs and passwords with required authority to access the database v Creating the warehouse database that receives historical data Be sure to plan the size of your warehouse database to ensure that you have a large enough database server to contain your data. See the IBM Tivoli Monitoring
13
Installation and Setup Guide for planning considerations for estimating the size of your Tivoli Data Warehouse database. The guide includes a spreadsheet that describes how to estimate the size of the warehouse. This spreadsheet has a tab for the ITCAM for SOA monitoring agent. To determine which ITCAM for SOA attribute groups can be enabled for historical data collection, see Chapter 16, Configuring for historical data collection, on page 251. v Configuring an ODBC database connection to the database v Configuring and registering the Warehouse Proxy Refer to IBM Tivoli Composite Application Manager for SOA Tools for information on connecting to a supported database and retrieving historical data collected by IBM Tivoli Composite Application Manager for SOA for display using IBM Web Services Navigator. You can also use ITCAM for SOA reports imported into Tivoli Common Reporting to retrieve and analyze historical data. See the appendix in the IBM Tivoli Composite Application Manager for SOA Users Guide for information about Tivoli Common Reporting.
Database support for service-to-service topology and service registry integration

ITCAM for SOA provides support for topology displays with the SOA Domain Management Server and the Tivoli Common Object Repository components, which are used to store and retrieve information about service resources such as application servers, service ports, operations, and the relationships between them. These components also provide integration with service registry and business process information. These service-to-service relationships and flows can then be displayed in Tivoli Enterprise Portal topology workspaces and views. These additional components of ITCAM for SOA are installed in a runtime environment called Tivoli Enterprise Portal Server Extensions, a feature that is provided when you install or upgrade your IBM Tivoli Monitoring environment to version 6.2 or later. If you plan to use support for displaying service-to-service topology flows in Operational Flow workspaces, you need to configure support for SOA Domain Management Server and its associated database. If you plan to use support for service registry integration, you need to configure support for both SOA Domain Management Server and Tivoli Common Object Repository along with their associated databases, and you also need to install and run one or more of the Discovery Library Adapters provided with this product. You have the option of configuring the SOA Domain Management Server to operate with or without the Tivoli Common Object Repository database. ITCAM for SOA also includes a graphical user interface configuration utility to help you create and configure the SOA Domain Management Server and the Tivoli Common Object Repository databases. On Windows, Linux, and AIX operating systems, console mode and silent mode (using a response file) are also supported. The SOA Domain Management Server database, containing information about service-to-service relationships, can be created on either a supported DB2 server or a supported Microsoft SQL server. This server can be the same database server used by Tivoli Enterprise Portal Server if located on the same computer as Tivoli Enterprise Portal Server, or this server can be located on a separate, remote computer.
14
Installation Guide
The Tivoli Common Object Repository database that contains service registry and business process integration data must be created on a supported DB2 database server. The DB2 server can be installed on either the Tivoli Enterprise Portal Server computer or on a different, remote database server. You can have the SOA Domain Management Server Configuration Utility create these databases for you locally, or you can create them yourself on local or remote database servers, using database creation scripts provided with the product. If you create your own databases manually, you still need to run the SOA Domain Management Server Configuration Utility on the Tivoli Enterprise Portal Server to complete the configuration of topology support. See Chapter 4, Configuring topology support, on page 65 for more information about creating databases, creating database users, and running the SOA Domain Management Server Configuration Utility. You might need to consult your local database administrator for assistance with these tasks.
Installation methods
IBM Tivoli Composite Application Manager for SOA is comprised of several different components that you can install in a variety of configurations. Some of these components are used to build and configure the systems management environment used by your operations staff to monitor and control your production SOA environment. Other components are Eclipse-based tools intended for software architects and development teams to use in the development and pre-deployment testing of new services. These types of components are installed using two different installation methods: v Application support files for the Tivoli Enterprise Monitoring Server, Tivoli Enterprise Portal Server, Tivoli Enterprise Portal, and the monitoring agent (with data collectors for each supported monitoring environment) are installed using the ITCAM for SOA installation support provided by the base IBM Tivoli Monitoring infrastructure, or by using SMP/e on supported z/OS operating systems. Configuration utilities for the SOA Domain Management Server, Tivoli Common Object Repository, and data collectors are available with this version of the product. These configuration utilities run in graphical user interface mode, console mode, and silent mode. v The Eclipse tools are also installed using the InstallShield MultiPlatform tool. v Discovery Library Adapters that are provided with this product are installed using a separate set of procedures documented in the IBM Tivoli Composite Application Manager for SOA Discovery Library Adapters guide. You can install these operational components of ITCAM for SOA and the Eclipse-based tools in a variety of configurations (ranging from a single machine to a large collection of development, operations and application server machines) and on a variety of platforms (operating systems or development environments). This publication describes the ITCAM for SOA version 7.1.1 installation support in terms of these components, configurations and environments. It also describes the supported scenarios for upgrading from a previous version of IBM Tivoli Composite Application Manager for SOA. For more information about installing the Eclipse-based tools available with this release, see IBM Tivoli Composite Application Manager for SOA Tools, GC32-1539.
15
Installation and configuration roadmap

Follow this general installation roadmap to complete required and optional steps, according to your needs: 1. Locate IBM Tivoli Monitoring components: Identify the computer systems in your environment where your IBM Tivoli Monitoring components (monitoring servers, portal servers, and desktop clients) are located. These are the systems on which you will install or upgrade application support for IBM Tivoli Composite Application Manager for SOA version 7.1.1. Multiple Tivoli Enterprise Portal Servers: The ITCAM for SOA topology workspaces and views are not supported when there is more than one Tivoli Enterprise Portal Server per Hub Tivoli Enterprise Monitoring Server in your IBM Tivoli Monitoring deployment. In this situation the results are unpredictable. 2. Install IBM Tivoli Monitoring: If you do not already have IBM Tivoli Monitoring installed in your environment, perform that product installation following the documented procedures in the IBM Tivoli Monitoring publications library. A supported version of IBM Tivoli Monitoring is included with this release for your convenience. 3. Upgrade IBM Tivoli Monitoring: If you already have IBM Tivoli Monitoring installed in your environment, you might need to upgrade it to a minimum supported level for this version of IBM Tivoli Composite Application Manager for SOA. Obtain any necessary upgrades or fix packs and apply them to your environment, following the documented procedures with those upgrades. See Chapter 2, Upgrading from a previous installation, on page 19 for more information. 4. Determine what you plan to monitor: Identify the computer systems in your enterprise where you want to monitor services, as well as supported SCA environments, DataPower appliances to be monitored, proxy systems where the DataPower data collector is to be located, and WebSphere Message Broker environments. These are the systems on which you will install or upgrade the monitoring agent for IBM Tivoli Composite Application Manager for SOA version 7.1.1. 5. Install database support: You might need to install or upgrade a supported version of database application software (IBM DB2, Microsoft SQL Server, or Oracle) in your environment in order to support collection, storage, and retrieval of historical data, or managing discovered service registry and business process integration topology data or service-to-service topology data. Verify that you have the required database application software installed in your environment. Refer to Planning database support on page 13 for more information, and consult with your local database administrator for assistance if needed. 6. Install or upgrade ITCAM for SOA application support: Use the installation and configuration procedures described in the chapters in this part of the guide, along with the general agent installation information found in the IBM Tivoli Monitoring library, to upgrade or install IBM Tivoli Composite Application Manager for SOA v7.1.1 on supported operating systems. In a typical distributed environment, you might have the Tivoli Enterprise Monitoring Server on one system, the Tivoli Enterprise Portal Server on another system, and monitoring agents installed on additional application server systems where services traffic is to be monitored. In a smaller environment you might be monitoring services on the same systems where IBM Tivoli Monitoring components are installed, or you might have everything operating on a single system. Refer to the following chapters for procedures on
16
Installation Guide
installing the application support files for IBM Tivoli Composite Application Manager for SOA on distributed IBM Tivoli Monitoring components: v To upgrade existing application support, see Chapter 2, Upgrading from a previous installation, on page 19. v To install ITCAM for SOA application support on a computer system where your monitoring server is installed, see Installing application support on monitoring servers on page 29. v To install ITCAM for SOA application support on a computer system where your portal server is installed, see Installing application support on the Tivoli Enterprise Portal Server on page 41. v To install ITCAM for SOA application support on a computer system where the Tivoli Enterprise Portal desktop client is installed, see Installing application support on the desktop client on page 47. 7. Install the monitoring agent: Install the ITCAM for SOA monitoring agent on a computer system where a supported application server environment is to be monitored. See Installing the monitoring agent on page 52. 8. Configure service-to-service topology and service registry integration support: Run the SOA Domain Management Server Configuration Utility to configure the SOA Domain Management Server and the optional Tivoli Common Object Repository. See Chapter 4, Configuring topology support, on page 65 for the procedure. 9. Configure your environment for data collection: Configure your application server runtime environment for data collection by enabling the ITCAM for SOA data collectors. See Part 2, Configuring for data collection, on page 125 for details on enabling and disabling data collection in supported application server runtime environments. Note that you might need to stop and restart your application servers before data collection is activated in that environment. 10. Additional configuration and administrative tasks: After installing the ITCAM for SOA monitoring application support and enabling your runtime environment for data collection, you can perform additional configuration and administrative tasks to complete your installation. Part 3, Completing your installation, on page 241 describes these additional tasks: v Chapter 15, Verifying the installation and configuration, on page 243 v Chapter 16, Configuring for historical data collection, on page 251 v Chapter 18, Configuring for Remote Deployment, on page 259 v Chapter 19, Installing Language Support, on page 263 v Chapter 20, Configuring IBM Tivoli Monitoring to forward events, on page 265 11. Install ITCAM for SOA Tools: Install additional tools (the IBM Web Services Navigator, and managed SCA mediation primitives). See the IBM Tivoli Composite Application Manager for SOA Tools publication for more information. For the IBM Web Services Navigator, you might also need to establish a connection to one or more supported databases where historical metric data is being stored. See the Tools guide for more information. 12. Install Discovery Library Adapters: You can install one or more Discovery Library Adapters that populate the Tivoli Common Object Repository database with relationship information to display in Tivoli Enterprise Portal topology workspaces and views. See the IBM Tivoli Composite Application Manager for SOA Discovery Library Adapters guide for complete information.
17
13. Import ITCAM for SOA Reports into Tivoli Common Reporting: This version includes ITCAM for SOA reports that you can import into the Tivoli Common Reporting component of IBM Tivoli Monitoring for retrieving and analyzing historical data collected by the ITCAM for SOA monitoring agent. See the appendix in the IBM Tivoli Composite Application Manager for SOA Users Guide for more information about importing, configuring, and running these reports. After completing these tasks to upgrade, install and configure IBM Tivoli Composite Application Manager for SOA in your environment, see the IBM Tivoli Composite Application Manager for SOA Users Guide as well as the online product help system along with the rest of the documentation library provided with this product to help you monitor and manage your services.
18
Installation Guide
Chapter 2. Upgrading from a previous installation

This chapter describes the general procedures and considerations for upgrading a previous installation of IBM Tivoli Composite Application Manager for SOA in supported IBM Tivoli Monitoring environments. You perform an upgrade from a previous installation by completing the following general steps: 1. Disable all data collection for your monitored environments, using the procedures documented in the publication library for your current IBM Tivoli Composite Application Manager for SOA installation. 2. If necessary, upgrade your IBM Tivoli Monitoring installation to one of the minimum supported versions. 3. Upgrade any IBM Tivoli Composite Application Manager for SOA version 6.0.0 monitoring agents to at least Version 6.1.0. Monitoring agents from version 6.0.0 are no longer supported. 4. Upgrade your IBM Tivoli Composite Application Manager for SOA installation to version 7.1.1. 5. Re-enable data collection for your monitored environments, using the procedures in this guide.
Disabling data collection for your monitored environments

Disable all data collection before upgrading: Before performing any upgrade of your current IBM Tivoli Monitoring or IBM Tivoli Composite Application Manager for SOA installation, be sure to disable data collection for all runtime environments, and then plan to re-enable data collection for your runtime environments after the upgrade is completed.
Disabling data collection for version 6.0.0

For IBM Tivoli Composite Application Manager for SOA version 6.0.0, see Appendix A in the Installation and User's Guide for information about running the KD4configDC script using the disable option. See the online Information Center for IBM Tivoli Composite Application Manager for SOA at http:// publib.boulder.ibm.com/infocenter/tivihelp/v3r1/topic/com.ibm.itcamsoa.doc_6.0/ kd4ugmst140.htm.

For IBM Tivoli Composite Application Manager for SOA version 6.1.0, see Chapter 5, Configuring for data collection, in the Installation and User's Guide for the procedures specific to each runtime environment on running the KD4configDC script using the disable option to disable data collection. You can find this information in the online Information Center for IBM Tivoli Composite Application Manager for SOA at http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/topic/ com.ibm.itcamsoa.doc_6.1/kd4ugmst49.htm.

For IBM Tivoli Composite Application Manager for SOA version 7.1.0, see the multiple chapters under Part 2, Configuring for data collection, in the Installation Guide, for the procedures specific to each runtime environment on disabling data collection. See the online Information Center for IBM Tivoli Composite Application
19
Manager for SOA at http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/topic/ com.ibm.itcamsoa.doc_7.1/kd4inmst57.htm#part2
Important: For DataPower environments: For the DataPower environment, do not use the disable option of the KD4configDC script or the Data Collector Configuration Utility. Instead, you should complete the following steps: 1. Stop the DataPower data collector using the stopDPDC command (see Starting and stopping the data collector on page 225 for more information. 2. Deregister the service or daemon, if applicable. See Running the DataPower data collector as a Windows service or UNIX daemon on page 225 for the procedures to stop a registered DataPower data collector, and deregistering the service to remove it from the list of Windows services, if applicable. For WebSphere Message Broker: Be sure to disable data collection for all brokers, execution groups, and message flows before upgrading your IBM Tivoli Composite Application Manager for SOA installation. You also must disable all message broker data collection when you upgrade WebSphere Message Broker from Version 6.0 to Version 6.1.0.2 or later. This version of IBM Tivoli Composite Application Manager for SOA provides a data collector for WebSphere Message Broker Version 6.1.0.2, and the user exit filename and directory structure for the data collector has changed. Disabling all data collection before performing these upgrades helps to ensure a smooth upgrade to the new structure. For WebSphere Message Broker on z/OS: If you are running the data collector for WebSphere Message Broker on supported z/OS operating systems, you must also disable data collection on all brokers, execution groups, and message flows before upgrading your IBM Tivoli Composite Application Manager for SOA installation. Refer to the publication, Configuring IBM Tivoli Composite Application Manager for SOA on z/OS for the procedure to disable data collection and perform the necessary steps to upgrade your data collector for the WebSphere Message Broker environment before you upgrade your IBM Tivoli Composite Application Manager for SOA installation to version 7.1.1 or later. Recovering from an error when re-enabling data collection: If you do not disable all message broker data collection before upgrading to IBM Tivoli Composite Application Manager for SOA Version 7.1.1, you will receive an error message when you attempt to enable data collection, indicating that configuration files from a previous version have been detected. In this situation you must run a special script to disable message broker data collection for prior versions of IBM Tivoli Composite Application Manager for SOA. For more information about this script, see Upgrading the data collector directory structure on page 233.
20
Installation Guide
Upgrading your IBM Tivoli Monitoring environment

Before upgrading your IBM Tivoli Composite Application Manager for SOA installation to version 7.1.1, you must upgrade your IBM Tivoli Monitoring installation to one of the following minimum supported versions: v IBM Tivoli Monitoring Version 6.2.0 or later fix pack v IBM Tivoli Monitoring Version 6.2.1 This upgrade must be performed on each computer in your enterprise where these components of IBM Tivoli Monitoring are installed: v Tivoli Enterprise Monitoring Server v Tivoli Enterprise Portal Server v Tivoli Enterprise Portal desktop client Each of these IBM Tivoli Monitoring components must be upgraded before installing or upgrading to IBM Tivoli Composite Application Manager for SOA version 7.1.1. Refer to your IBM Tivoli Monitoring documentation for complete details about installing, upgrading, and configuring the IBM Tivoli Monitoring environment. For your convenience, IBM Tivoli Monitoring Version 6.2.0 Fix Pack 1 is provided with the IBM Tivoli Composite Application Manager for SOA version 7.1.1 product. You might prefer to install or upgrade to a later supported version or fix pack level. Refer to the IBM Tivoli Monitoring support Web site for more information on available fix packs and installation procedures. Upgrading the Tivoli Enterprise Monitoring Agent: For computers in your monitored environment that do not have an IBM Tivoli Monitoring component installed, but have an IBM Tivoli Composite Application Manager for SOA monitoring agent from a previous version, the IBM Tivoli Monitoring monitoring agent infrastructure is upgraded to the version 6.1 Fix Pack 7 level automatically during the upgrade of IBM Tivoli Composite Application Manager for SOA to version 7.1.1. Upgrading other monitoring agents: Existing monitoring agents for other Tivoli products might also need to be upgraded. Refer to your monitoring agent product documentation for information about upgrades, and check if upgrading to one of these supported versions of IBM Tivoli Monitoring affects your existing monitoring agents. Be sure to install or upgrade the following additional components of IBM Tivoli Monitoring as needed: v Tivoli Enterprise Portal Web browser enablement (optional, also referred to as the browser client) v Warehouse Proxy (if you intend to use historical reporting or save historical data to a database for later retrieval and analysis using IBM Web Services Navigator, or for displaying historical data in certain ITCAM for SOA workspaces and views) v IBM Eclipse Help Server, which is used to display searchable online help information in the IBM Eclipse Help System environment. v The Java Runtime Environment (JRE) for running the desktop version of the Tivoli Enterprise Portal. v Internet Explorer version 6 or higher, with the Java Plug-in (at the same version as the JRE) for running the Web browser version of the Tivoli Enterprise Portal.
21
Upgrading IBM Tivoli Composite Application Manager for SOA from version 6.0.0
After you have upgraded your IBM Tivoli Monitoring environment to one of the minimum supported levels, you can upgrade your existing IBM Tivoli Composite Application Manager for SOA installation. Any existing IBM Tivoli Composite Application Manager for SOA monitoring agents from Version 6.0.0 (or either of its Sparkler, or Interim Feature versions) in your environment must be upgraded to at least Version 6.1.0, and then optionally to Version 7.1.1. IBM Tivoli Composite Application Manager for SOA Version 6.0.0 monitoring agents are no longer supported when you install or upgrade to IBM Tivoli Composite Application Manager for SOA Version 7.1.0 or later. See the documentation provided with IBM Tivoli Composite Application Manager for SOA Version 6.1.0 or with Version 6.1.0 Fix Pack 1 for information on upgrading from Version 6.0.0 and its interim feature levels. This library is available in the online Information Center for IBM Tivoli Composite Application Manager for SOA at http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/topic/ com.ibm.itcamsoa.doc_6.1/welcome.htm.
You can upgrade your existing IBM Tivoli Composite Application Manager for SOA Version 6.1.0 (or later fix pack) installation directly to Version 7.1.1. During the upgrade to Version 7.1.1, complete the following tasks: 1. If you have not already done so, disable data collection for all runtime environments, following the procedures found in the version 6.1.0 product documentation. See Disabling data collection for version 6.1.0 on page 19 for more information about disabling data collection. 2. Upgrade any existing IBM Tivoli Composite Application Manager for SOA Version 6.0.0 monitoring agents to Version 6.1.0. In the IBM Tivoli Composite Application Manager for SOA Version 6.1.0 environment, you might have had a mixture of Version 6.1.0 and Version 6.0.0 agents. Version 6.1.0 agents are still supported after you upgrade to IBM Tivoli Composite Application Manager for SOA Version 7.1.1, however, ITCAM for SOA Version 6.0.0 agents are no longer supported. Refer to the documentation library for IBM Tivoli Composite Application Manager for SOA Version 6.1.0 for the procedures to upgrade all of your Version 6.0.0 agents to Version 6.1.0 or later. This library is available in the online Information Center for IBM Tivoli Composite Application Manager for SOA at http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/topic/ com.ibm.itcamsoa.doc_6.1/welcome.htm. 3. Install IBM Tivoli Composite Application Manager for SOA Version 7.1.1 application support files for the Tivoli Enterprise Monitoring Server, Tivoli Enterprise Portal Server, and Tivoli Enterprise Portal components of IBM Tivoli Monitoring, running the installation program provided with this release. See Running the IBM Tivoli Composite Application Manager for SOA installation program on page 26 for instructions and any special considerations. 4. If preferred, you can upgrade any existing Version 6.1.0 agents to Version 7.1.1. Note that you do not have to upgrade all of your IBM Tivoli Composite Application Manager for SOA Version 6.1.0 monitoring agents in the IBM Tivoli Monitoring environment at the same time. During the period when there is a mixture of Version 6.1.0, Version 7.1.0, and Version 7.1.1 agents in your
22
Installation Guide
environment, the Version 6.1.0 and Version 7.1.0 agents are supported only at their respective levels of functionality. Services discovered by IBM Tivoli Composite Application Manager for SOA Version 6.1.0 agents are not displayed in the service-to-service topology views. Instead they are displayed as unmanaged clients or operations. When you upgrade IBM Tivoli Composite Application Manager for SOA monitoring agents to Version 7.1.1, each of the existing runtime environments for the IBM Tivoli Composite Application Manager for SOA data collectors on that computer must be upgraded to Version 7.1.1 by using the following general procedure: v Disable data collection for all runtime environments on that computer. Refer to the documentation for your existing version of IBM Tivoli Composite Application Manager for SOA for the procedures to disable data collection for your runtime environments. v On each computer system where the monitoring agent is installed, upgrade the monitoring agent to version 7.1.1, running the installation program provided with this release. See Running the IBM Tivoli Composite Application Manager for SOA installation program on page 26 for instructions and any special considerations. v Re-enable data collection for each runtime environment. Refer toPart 2, Configuring for data collection, on page 125 for the procedures to enable data collection for your runtime environments. IBM Tivoli Composite Application Manager for SOA Version 6.1.0 Fix Pack 1: Additional features for version 6.1.0 agents are provided in this fix pack. Before you can take advantage of these features, you must upgrade any version 6.1.0 monitoring agents to at least the Fix Pack 1 level, if you plan to keep these agents at this older version. See the upgrade procedures in the documentation provided with this fix pack for more information on upgrading. You can also upgrade these agents to Version 7.1.1. Metric log file format change: Be aware that the metric log file format has changed for IBM Tivoli Composite Application Manager for SOA Version 7.1.0 and later. As a result, metric log files that are created by previous versions of the data collectors are not read and processed by the Version 7.1.0 (and later) monitoring agent. Before upgrading an agent from a previous version, ensure that all of the metric files with historical data have been backed up or warehoused as needed. 5. During the upgrade process on supported Windows operating systems, the KD4ENV file is renamed from <ITM_Home>\CMA\KD4ENV to <ITM_Home>\CMA\KD4ENV.xxx, and a new KD4ENV file is created in <ITM_Home>\TMAITM6\KD4ENV with default values. If your previous installation had customized changes in your KD4ENV file, you will need to manually merge them from the backed up KD4ENV.xxx file into the new KD4ENV file to restore your customized changes to the upgraded installation. 6. In your previous ITCAM for SOA Version 6.1.0 installation, you might have installed additional support for the Tivoli Common Object Repository database, which stores service registry and business process integration data from one or more Discovery Library Adapters. In addition, the SOA Domain Management Server feature of ITCAM for SOA Version 6.1.0 would have been used to display this data in topology views. After upgrading your ITCAM for SOA installation to version 7.1.1, you must upgrade this topology support for Tivoli Common Object Repository and SOA Domain Management Server using the SOA Domain Management Server
23
Configuration Utility. This utility detects the presence of your existing configuration and guides you through the steps to perform the upgrade. Be sure to re-configure and restart Tivoli Enterprise Portal Server for this upgrade to take effect. See Running the SOA Domain Management Server Configuration Utility on page 78 for more information on running this utility, and see the specific section, Upgrading a previous topology configuration on page 97 for steps to upgrade a previous configuration of Tivoli Common Object Repository and SOA Domain Management Server. When upgrading from ITCAM for SOA version 6.1 to version 7.1.1, you must create the SOA Domain Management Server database. The existing Tivoli Common Object Repository database will be automatically upgraded during the process.
Changes to subnode names in Tivoli Enterprise Portal

After you upgrade to ITCAM for SOA version 7.1.1, the subnode names that are displayed in the Navigator Physical view use a shorter format than subnode names used in ITCAM for SOA version 6.1.0. Previously existing subnodes names used a longer format that included the fully qualified hostname. Subnodes with these longer names are considered obsolete and should be removed by completing these steps: 1. From the Navigator Physical view of the Tivoli Enterprise Portal, select the Enterprise node. 2. Right-click the Enterprise node and select Workspace > Managed System Status. 3. Locate the obsolete subnode name in the list that is displayed in the Managed System Status view. It should be marked with a status of *OFFLINE. 4. Right-click the obsolete subnode row and select Clear offline entry from the context menu to remove the offline entry from the table.
You can upgrade your existing IBM Tivoli Composite Application Manager for SOA Version 7.1.0 installation directly to Version 7.1.1. During the upgrade of Version 7.1.0 to Version 7.1.1, complete the following tasks: 1. If you have not already done so, disable data collection for all runtime environments, following the procedures found in the version 7.1.0 product documentation. See Disabling data collection for version 7.1.0 on page 19 for more information about disabling data collection, in particular the information regarding the WebSphere Message Broker environment. 2. Install IBM Tivoli Composite Application Manager for SOA Version 7.1.1 application support files for the Tivoli Enterprise Monitoring Server, Tivoli Enterprise Portal Server, and Tivoli Enterprise Portal components of IBM Tivoli Monitoring, running the installation program provided with this release. See Running the IBM Tivoli Composite Application Manager for SOA installation program on page 26 for instructions and any special considerations. 3. If preferred, you can upgrade any existing Version 7.1.0 agents to Version 7.1.1. Note that you do not have to upgrade all of your IBM Tivoli Composite Application Manager for SOA Version 7.1.0 monitoring agents in the IBM Tivoli Monitoring environment at the same time. During the period when there is a mixture of Version 7.1.0 and Version 7.1.1 agents in your environment, the agents are supported at their respective levels of functionality. When you upgrade IBM Tivoli Composite Application Manager for SOA monitoring agents to Version 7.1.1, each of the existing runtime environments
24
Installation Guide
for the IBM Tivoli Composite Application Manager for SOA data collectors on that computer must be upgraded to Version 7.1.1 by using the following general procedure: v Disable data collection for all runtime environments on that computer. Refer to the documentation for your existing version of IBM Tivoli Composite Application Manager for SOA for the procedures to disable data collection for your runtime environments. v Upgrade the monitoring agent for each monitored system to IBM Tivoli Composite Application Manager for SOA version 7.1.1, running the installation program provided with this release on each computer where the monitoring agent is installed. See Running the IBM Tivoli Composite Application Manager for SOA installation program on page 26 for instructions and any special considerations. v Re-enable data collection for each runtime environment. Refer to Part 2, Configuring for data collection, on page 125 for the procedures to enable data collection for your runtime environments. 4. In your previous ITCAM for SOA Version 7.1.0 installation, you would also have an existing SOA Domain Management Server database and support for service-to-service topology views. After upgrading your ITCAM for SOA installation to version 7.1.1, you must upgrade this topology support for Tivoli Common Object Repository and SOA Domain Management Server using the SOA Domain Management Server Configuration Utility. This utility detects the presence of your existing configuration and guides you through the steps to perform the upgrade. In ITCAM for SOA version 7.1.0, SOA Domain Management Server might have been configured to use Microsoft SQL Server 2000. In this case the port number did not need to be specified in version 7.1.0, but when you upgrade SOA Domain Management Server to version 7.1.1, you must specify the port number so that the SOA Domain Management Server Configuration Utility can test the JDBC connection. Be aware that during the upgrade process you will be prompted to specify the port number for Microsoft SQL Server 2000. Be sure to re-configure and restart Tivoli Enterprise Portal Server for this upgrade to take effect. See Running the SOA Domain Management Server Configuration Utility on page 78 for more information on running this utility, and see the specific section, Upgrading a previous topology configuration on page 97 for steps to upgrade a previous configuration of Tivoli Common Object Repository and SOA Domain Management Server. Note that you do not need to recreate an existing SOA Domain Management Server database or Tivoli Common Object Repository database (local or remote). When you run the SOA Domain Management Server Configuration Utility, the databases are migrated to the database schema for ITCAM for SOA version 7.1.1. 5. You can also optionally install the newest versions of the ITCAM for SOA Tools (see the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide) and one or more discovery library adapters (see the IBM Tivoli Composite Application Manager for SOA Discovery Library Adapters guide) provided with this product.
Changes in historical data for WebSphere Message Broker

After you upgrade your WebSphere Message Broker data collector from Version 7.1.0 to Version 7.1.1, you might see different service port names, service port namespaces, operation names, and operation namespaces in Client Response and Server Leave events in the historical data for non-SOAP messages. See the IBM
25
Tivoli Composite Application Manager for SOA Users Guide for more information about service port names, service port namespaces, operation names, and operation namespaces for WebSphere Message Broker.
Running the IBM Tivoli Composite Application Manager for SOA installation program
To upgrade your installation, follow the same procedures for running the IBM Tivoli Composite Application Manager for SOA installation program as documented in Chapter 3, Installing IBM Tivoli Composite Application Manager for SOA, on page 29, keeping in mind the following considerations when installing on Windows operating systems: v In the Select Features page, select the features to install. If you expand the nodes, notice that the check boxes for Composite Application Manager for SOA are already selected. v If you are planning to remotely deploy monitoring agents, and you are installing on a computer where the Tivoli Enterprise Monitoring Server is installed, on the Agent Deployment page, select the check box to configure the environment for remote deployment of the IBM Tivoli Composite Application Manager for SOA monitoring agent. v In the Start Copying Files page, you should see a message saying that a previous installation has been detected and will be updated. Note that the target installation directory is the same directory that you used for the previous IBM Tivoli Monitoring installation (for example, C:\IBM\ITM). The program folder is also reused.
Additional upgrade tasks

After completing the upgrade tasks described previously in this chapter, you should also perform the following additional tasks as needed: 1. Check for locked JAR files: If you installed the ITCAM for SOA monitoring agent on a supported Windows operating system, check the agent installation log file, located at <ITM_Home>\InstallITM\IBM Tivoli Composite Application Management*.log) for a message similar to one of the following examples:
CheckLockedFiles - File C:\IBM\ITM\TMAITM6\KD4\lib\kd4dcagent.jar is locked. CheckLockedFiles - File C:\IBM\ITM\TMAITM6\KD4\lib\kd4dpdcagent.jar is locked.
If you see a locked file message for either of the JAR files listed above, your data collector JAR files were not upgraded. Contact IBM Support for assistance in obtaining the JAR files for the upgraded version of ITCAM for SOA. Similarly, if you see a message about the kd4ui.jar file being locked, the ITCAM for SOA application client support for the desktop client was not upgraded because the desktop client was not stopped prior to the upgrade. Contact your Tivoli Enterprise Portal Server administrator to get a copy of the kd4ui.jar file from the <ITM_Home>\CNB\classes directory on Windows operating systems, or from the <ITM_Home>/<platform>/cw/classes directory on Linux or UNIX operating systems, and copy it to the <ITM_Home>\CNP directory for your desktop client. Then reconfigure your desktop client to pick up the updated jar file. 2. Configure your environment for data collection: Configure your application server runtime environment for data collection by enabling the ITCAM for SOA data collectors. See Part 2, Configuring for data collection, on page 125 for details on enabling and disabling data collection in supported application server runtime environments.
26
Installation Guide
Note that you might need to stop and restart your application servers before data collection is activated in that environment. 3. Additional configuration and administrative tasks: Perform the following additional configuration and administrative tasks as needed, described in Part 3, Completing your installation, on page 241: v Chapter 15, Verifying the installation and configuration, on page 243 Chapter 16, Configuring for historical data collection, on page 251 Chapter 18, Configuring for Remote Deployment, on page 259 Chapter 19, Installing Language Support, on page 263 Chapter 20, Configuring IBM Tivoli Monitoring to forward events, on page 265 4. Install ITCAM for SOA Tools: Install additional tools (the IBM Web Services Navigator, and managed SCA mediation primitives). See the IBM Tivoli Composite Application Manager for SOA Tools publication for more information. If you are upgrading from a previous installation of the Tools, see the information about uninstalling the previous installation before installing the current version. For the IBM Web Services Navigator, you might also need to establish a connection to one or more supported databases where historical metric data is being stored. See the Tools guide for more information. 5. Install Discovery Library Adapters: Install the latest versions of one or more Discovery Library Adapters that populate the Tivoli Common Object Repository database with relationship information to display in Tivoli Enterprise Portal topology workspaces and views. See the IBM Tivoli Composite Application Manager for SOA Discovery Library Adapters guide for complete information. v v v v 6. Import ITCAM for SOA Reports into Tivoli Common Reporting: Import the latest version of ITCAM for SOA reports into the Tivoli Common Reporting component of IBM Tivoli Monitoring for retrieving and analyzing historical data collected by the ITCAM for SOA monitoring agent. See the appendix in the IBM Tivoli Composite Application Manager for SOA Users Guide for more information about importing, configuring, and running these reports.
27
28
Installation Guide
Chapter 3. Installing IBM Tivoli Composite Application Manager for SOA

The following sections contain operating system specific procedures for installing the monitoring agent and application support files. Use the procedure that best applies to your environment. The installation procedures in the following sections provide information for installing the monitoring agent on a computer with no IBM Tivoli Monitoring components installed, and installing monitoring application support files for a single IBM Tivoli Monitoring component (such as the monitoring server) on one computer. If you want to install the monitoring agent on a computer with one or more IBM Tivoli Monitoring components installed, or if you want to install application support for multiple components (such as the monitoring server and the portal server) simultaneously on the same computer, the actual steps might vary from the following procedures. Refer to the individual sections for required configuration information during your installation. Single installation: IBM Tivoli Composite Application Manager for SOA supports only a single installation per computer system.
Installing application support on the monitoring server, portal server, and desktop client
The IBM Tivoli Composite Application Manager for SOA monitoring agent requires that application support files containing agent-specific information be installed into the monitoring server, portal server, and portal desktop and browser clients. Use the instructions in the following sections to install application support: v Installing application support on monitoring servers v Installing application support on the Tivoli Enterprise Portal Server on page 41 v Installing application support on the desktop client on page 47
Installing application support on monitoring servers

When you install the IBM Tivoli Composite Application Manager for SOA monitoring agent on one or more computer systems in your environment where you plan to monitor services, you must also install application support files containing agent specific information for the monitoring agent on the computer system where Tivoli Enterprise Monitoring Server is installed. When you install the application support on your Tivoli Enterprise Monitoring Server, you should be logged in as the user who installed Tivoli Enterprise Monitoring Server. Note that the monitoring server is stopped and started several times during the installation of application support. If the monitoring server was stopped when you started the installation process and you want it stopped after the installation process is finished, you must manually stop it. Use the following sections to install application support on each monitoring server (hub and remote) in your environment: v Windows: Installing application support on monitoring servers on page 30 v Linux or AIX: Installing application support on monitoring servers on page 39
29
Application support on z/OS: This guide does not describe installing and configuring application support for a monitoring server installed on a supported z/OS operating system. For more information and instructions, see these documents: v Configuring the Tivoli Enterprise Monitoring Server on z/OS in the IBM Tivoli Monitoring library, for general information on installing application support files and using the Installation and Configuration Assistance Tool (ICAT) to configure the environment. v Configuring IBM Tivoli Composite Application Manager for SOA on z/OS for additional information specific to this monitoring agent in z/OS operating systems.
Windows: Installing application support on monitoring servers

Complete these steps to install application support for IBM Tivoli Composite Application Manager for SOA on a monitoring server installed on a supported Windows operating system: Note: The monitoring server is stopped during this process. 1. Start the installation program using the IBM Tivoli Composite Application Manager for SOA product installation media (DVD or downloaded installation image). If the installation program does not start automatically, open a command prompt, navigate to the appropriate drive on your local computer, open the \WINDOWS folder, and enter the following command:
setup.exe
One or more welcome pages are displayed. 2. Click Next. A Prerequisites page is displayed, as shown in Figure 1 on page 31, reminding you that the monitoring agent requires certain minimum supported versions of the IBM Global Security ToolKit and IBM Java. Any current versions are shown on the page. Select the option to upgrade to the minimum supported levels, if needed. If your current version is the same as the required version, bypass this step. Select your desired options and click Next to continue.
30
Installation Guide
Figure 1. The Prerequisites page
3. The Software License Agreement page is displayed. Read the terms in the license agreement as presented in the scrollable window and, if you agree to abide by those terms, click Accept. You must accept the terms of the license agreement to continue the installation. 4. The Select Features page is displayed, similar to Figure 2 on page 32, showing the available features that you can install for this product. If you have already installed a monitoring agent or other IBM Tivoli Monitoring components on this computer, the check boxes for these features are already selected. Select Tivoli Enterprise Monitoring Server and click Next.
31
Figure 2. The Select Features page for installing application support on TEMS
Is the Tivoli Enterprise Portal Server or Tivoli Enterprise Portal desktop client also installed on this computer?: If so, you can also select those components to install application support for IBM Tivoli Composite Application Manager for SOA now, or follow the procedures in the sections that follow to separately install application support for these components at a later time. 5. The Agent Deployment page is displayed, as shown in Figure 3 on page 33.
32
Installation Guide
Figure 3. The Agent Deployment page
About remote agent deployment: IBM Tivoli Composite Application Manager for SOA supports the IBM Tivoli Monitoring feature of remotely deploying the monitoring agent across your environment from a central location, the monitoring server. This procedure consists of the following general steps: a. Add the IBM Tivoli Composite Application Manager for SOA monitoring agent to the deployment depot. You can do this now by selecting the check box on this Agent Deployment page for the monitoring agent and continuing with this installation. If you do not select this check box now, you can add the monitoring agent to the deployment depot at a later time by either running the installation program again (and selecting the Modify option) or by using the tacmd addBundles command as documented in the IBM Tivoli Monitoring: Installation and Setup Guide (GC32-9407). To deploy the monitoring agent to a remote operating system other than Windows, run the tacmd addBundles command to add the operating system specific bundle to the deployment depot. Note that this step adds only the Windows (or operating system specific) monitoring agent to the deployment depot, and does not actually deploy the monitoring agent. b. After you complete this installation of application support for the monitoring server, see Chapter 18, Configuring for Remote Deployment, on page 259 for additional steps to deploy the Windows (or operating system specific) monitoring agent from the deployment depot to one or more remote computers where you are monitoring services. c. After you remotely deploy the monitoring agent to one or more managed systems, you must enable the data collectors for the application server runtime environments being monitored on each remote system as described in Part 2, Configuring for data collection, on page 125.
33
If you do not want to configure the monitoring agent for remote deployment, do not select the check box in this Agent Deployment page. Click Next to continue. 6. The Start Copying Files page is displayed. Review the installation summary details and verify your selections. Click Next to start the installation. 7. After the files are copied, the Setup Type configuration page is displayed, similar to the example shown in Figure 4.
Figure 4. The Setup Type page
This page offers several configuration options to install and configure application support for Tivoli Enterprise Monitoring Server: v Select Install application support files for a Local/Remote Tivoli Enterprise Monitoring Server to add application support for IBM Tivoli Composite Application Manager for SOA workspaces and situations in Tivoli Enterprise Monitoring Server. v Select Configure agents default connection to Tivoli Enterprise Monitoring Server to define the default connection between the monitoring agent and the monitoring server. v Select Launch Manage Tivoli Monitoring Services to automatically launch the Manage Tivoli Enterprise Monitoring Services utility after these configuration steps are completed, to support additional configuration tasks and to start monitoring functions. By default, all of the setup types are already selected for configuration. In most cases, accept the default selection of these configuration options. You can also clear any of the selections to postpone these configuration tasks until after the installation is completed. When you are satisfied with your selected options, click Next to continue.
34
Installation Guide
Application support for the portal server: If the Tivoli Enterprise Portal Server component of IBM Tivoli Monitoring is also installed on this same computer, and if you selected to add application support for the Tivoli Enterprise Portal Server on the Select Features page (see Figure 2 on page 32), the Configure Tivoli Enterprise Portal Server check box is also displayed on this page, as shown in Figure 4 on page 34. You can select that check box to add application support for IBM Tivoli Composite Application Manager for SOA workspaces and situations in the portal server. For the remainder of this discussion, however, assume that the Tivoli Enterprise Portal Server is installed on a different computer, and you are only installing application support for the monitoring server. See Installing application support on the Tivoli Enterprise Portal Server on page 41 for more information about installing application support for the portal server. 8. Because the monitoring server is installed on this computer, the Tivoli Enterprise Monitoring Server Configuration page is displayed, as shown in Figure 5:
Figure 5. The Tivoli Enterprise Monitoring Server Configuration page
In the TEMS Type area, if this system is configured as a hub Tivoli Enterprise Monitoring Server, the Hub radio button is selected by default. If the system is configured as a remote Tivoli Enterprise Monitoring Server, the Remote radio button is selected by default. The TEMS Name field is pre-filled with HUB_<hostname> or REMOTE_<hostname>, where <hostname> is the hostname of the system where the Tivoli Enterprise Monitoring Server is installed. In the Protocol for this TEMS area, the Protocol 1 check box is selected, and the corresponding entry field is pre-filled with IP.PIPE. Select the type of protocol that the monitoring agent uses to communicate with the monitoring server. You have four choices: IP.UDP, IP.PIPE, IP.SPIPE, or SNA. Accept these defaults, or select another protocol option. You can specify up to three methods of communication to provide backup methods if needed, depending on your environment. If the method you have identified as Protocol 1 fails, Protocol 2 is used. Refer to the IBM Tivoli Monitoring documentation for more information about available protocol selections. Verify these selections and click OK.
35
9. If you configured the monitoring server on this system as a Hub server, the Hub TEMS Configuration page is displayed, similar to Figure 6.
Figure 6. The Hub TEMS Configuration page
If you configured the monitoring server on this system as a remote server, the Remote TEMS Configuration page is displayed, similar to Figure 6, but showing the host name for the primary Hub Tivoli Enterprise Monitoring Server. Depending on which communication protocols (IP.UDP, IP.PIPE, IP.SPIPE, or SNA) you selected in the previous step, the hostname, port number, and other fields show default values for these communication settings. The example shown in Figure 6 shows the fields under IP.PIPE Settings that you can configure, with default values provided. In each group of selected protocol settings, verify the default values or change them to your preferred settings. Table 5 describes the settings for each type of protocol. Click OK.
Table 5. Windows operating system protocol settings for communicating between the monitoring agent and Tivoli Enterprise Monitoring Server Protocol IP.UDP Field Hostname or IP Address Port # and/or Port Pools IP.PIPE Hostname or IP Address Port Number Description The host name or IP address for the Tivoli Enterprise Monitoring Server to which this monitoring agent is connected. The listening port for the Tivoli Enterprise Monitoring Server to which this monitoring agent is connected. The host name or IP address for the Tivoli Enterprise Monitoring Server to which this monitoring agent is connected. The listening port for the Tivoli Enterprise Monitoring Server to which this monitoring agent is connected. The default value is 1918. The host name or IP address for the Tivoli Enterprise Monitoring Server to which this monitoring agent is connected. The listening port for the Tivoli Enterprise Monitoring Server to which this monitoring agent is connected. The default value is 3660.
IP.SPIPE
Hostname or IP Address Port Number
36
Installation Guide
Table 5. Windows operating system protocol settings for communicating between the monitoring agent and Tivoli Enterprise Monitoring Server (continued) Protocol SNA Field Network Name LU Name Description The SNA network identifier for your location. The LU name for the Tivoli Enterprise Monitoring Server. This LU name corresponds to the local LU Alias in your SNA communications software. The name of the LU6.2 LOGMODE. The default value is CANCTDCS. The transaction program name for the Tivoli Enterprise Monitoring Server. The LU alias.
LU 6.2 LOGMODE TP Name Local LU Alias
10. Because you selected the Install application support files for a Local/Remote Tivoli Enterprise Monitoring Server check box in Figure 4 on page 34, the Add application support to the TEMS page is displayed, as shown in Figure 7, to add application support to the monitoring server.
Figure 7. The Add application support to the TEMS Configuration page
Specify the location of the monitoring server. These are the choices: v On this computer v On a different computer In this case, select On this computer and click OK. 11. Select the data that you want to add to the monitoring server. By default, the application support for IBM Tivoli Composite Application Manager for SOA is already selected, shown in Figure 8.
Figure 8. The Select the application support to add to the TEMS page
This is identified under the Application support file column askd4.sql (however, if you are upgrading an ITCAM for SOA version 6.1.0 installation, the name of this file is kd4_upg.sql. Click OK. 12. After the application support for IBM Tivoli Composite Application Manager for SOA is added to the monitoring server, a message is displayed, similar to
37
Figure 9. Click Next.
Figure 9. Return code for successfully adding application support for IBM Tivoli Composite Application Manager for SOA to the Tivoli Enterprise Monitoring Server
13. The InstallShield Wizard Complete page is displayed as shown in Figure 10 on page 39, indicating that the installation was successful, and offering you the option to view the README file for the product, which might contain additional information of interest to you. The check box for displaying the README file is already selected. Leave the check box selected to automatically display the README, or clear this check box to not display the README file if you have already seen it (this readme.txt file is also available in the \WINDOWS directory on the installation media), and click Finish to close the installation program.
38
Installation Guide
Figure 10. The InstallShield Wizard Complete page
14. Because you selected the Launch Manage Tivoli Monitoring Services check box in Figure 4 on page 34, the Manage Tivoli Enterprise Monitoring Services utility is displayed, showing the Tivoli Enterprise Monitoring Server (see Figure 11). If additional components of IBM Tivoli Monitoring are installed on this system, they are also displayed.
Figure 11. The Tivoli Enterprise Monitoring Server in the Manage Tivoli Enterprise Monitoring Services utility
If you did not select the option to launch the Manage Tivoli Enterprise Monitoring Services utility, you can launch it manually by selecting Start > All Programs > IBM Tivoli Monitoring > Manage Tivoli Monitoring Services. Verify that the Configured column shows Yes, meaning that Tivoli Enterprise Monitoring Server is successfully configured and started.
Linux or AIX: Installing application support on monitoring servers

Use the following steps to install application support for IBM Tivoli Composite Application Manager for SOA on a monitoring server installed on a supported Linux
39
or AIX operating system. Refer to the IBM Tivoli Monitoring documentation for general procedures for installing application support for monitoring agents on these operating systems. 1. Change to the <ITM_Home>/bin directory. 2. Optionally stop the monitoring server by running the following command:
./itmcmd server stop tems_name
3. Close the Manage Tivoli Enterprise Monitoring Services utility if it is open. 4. Mount the IBM Tivoli Composite Application Manager for SOA installation media at the location you have chosen on the local system, following the standard procedures for your operating system. 5. From the root directory of the installation media, enter the following command to start the installation program:
./install.sh
6. When prompted for the IBM Tivoli Monitoring home directory, press Enter to accept the default (/opt/IBM/ITM) or type the full path to the installation directory that you used. 7. The following prompt is displayed:
Select one of the following: 1) Install products to the local host. 2) Install products to depot for remote deployment (requires TEMS). 3) Exit install. Please enter a valid number:
8. 9. 10. 11.
Type 1 to start the installation and press Enter. Type the number that corresponds to the language in which you want to display the software license agreement and press Enter. Press Enter to display the agreement. Type 1 to accept the agreement and press Enter. You might be prompted to type a 32 character encryption key and press Enter. This key should be the same as the key that was used during the installation of the monitoring server.
12. A numbered list of available options is displayed. Type the number that corresponds to Tivoli Enterprise Monitoring Server support and press Enter. 13. Type y to confirm and press Enter. 14. A list of the components to install is displayed. Type the number that corresponds to selecting all components to install and press Enter. 15. Type y to confirm the installation. The installation begins. 16. After all of the components are installed, you are asked whether you want to install components for a different operating system. Type n and press Enter. 17. Start the monitoring server by running the following command:
./itmcmd server start tems_name
18. Enter the following command to activate the application support on the monitoring server:
./itmcmd support -t tems_name d4
In this command, tems_name is the name of the monitoring server and d4 is the product code for the IBM Tivoli Composite Application Manager for SOA monitoring agent. 19. Stop the monitoring server by running the following command:
./itmcmd server stop tems_name
20. Enter the following command to restart the monitoring server:
40
Installation Guide
./itmcmd server start tems_name
Installing application support on the Tivoli Enterprise Portal Server

When you install the IBM Tivoli Composite Application Manager for SOA monitoring agent on one or more computer systems in your environment where you plan to monitor services, you must also install application support files containing agent specific information for the monitoring agent on the computer system where Tivoli Enterprise Portal Server is installed. When you install the application support on your Tivoli Enterprise Portal Server, you should be logged in as the user who installed Tivoli Enterprise Portal Server. Use the following sections to install application support on the portal server in your environment: v Windows: Installing application support on the portal server v Linux or AIX: Installing application support on the portal server on page 46
Windows: Installing application support on the portal server

Use the following steps to install application support for IBM Tivoli Composite Application Manager for SOA on a Tivoli Enterprise Portal Server installed on a supported Windows operating system: Note: The portal server is stopped during this process. 1. Open Manage Tivoli Enterprise Monitoring Services. 2. Stop the Tivoli Enterprise Portal Server by right-clicking it and clicking Stop. 3. Insert the IBM Tivoli Composite Application Manager for SOA installation media into the appropriate drive. The installation program starts automatically. 4. If the installation program does not start automatically, open a command prompt window, navigate to the appropriate drive, open the \WINDOWS folder, and enter the following command:
setup.exe
A Welcome page is displayed. Click Next. 5. A Prerequisites page is displayed, as shown in Figure 1 on page 31, reminding you that the monitoring agent requires certain minimum supported versions of the IBM Global Security ToolKit and IBM Java. Any current versions are shown on the page, and you have the option to upgrade to the minimum supported levels or bypass this step. Select your desired options and click Next to continue. 6. A Software License Agreement page might be displayed. Read the terms in the license agreement as presented in the scrollable window and, if you agree to abide by those terms, click Accept. You must accept the terms of the license agreement to continue the installation. 7. The Select Features page is displayed, similar to Figure 12 on page 42, showing the available features that you can install for this product. If you have already installed a monitoring agent or application support files for other IBM Tivoli Monitoring components on this computer, the title of this page is Add or Remove Features, and check boxes for these features are already selected. Select Tivoli Enterprise Portal Server and click Next.
41
Figure 12. The Select Features page for installing application support on TEPS
Is the Tivoli Enterprise Monitoring Server or Tivoli Enterprise Portal desktop client also installed on this computer?: If so, you can also select those components to install application support for IBM Tivoli Composite Application Manager for SOA if you have not already done so, or follow the procedures in this publication to separately install application support for these components at a later time. 8. The Start Copying Files page is displayed, similar to Figure 13 on page 43. Review the installation summary details and verify your selections. Click Next to start the installation.
42
Installation Guide
Figure 13. The Start Copying Files page for installing application support on TEPS
9. After installation is complete, the Setup Type configuration page is displayed, as shown in Figure 14 on page 44.
43
This window offers several configuration options to install and configure application support for Tivoli Enterprise Portal Server: v The Configure Tivoli Enterprise Portal Server check box is selected to add application support for IBM Tivoli Composite Application Manager for SOA workspaces and situations in the portal server. v The Launch Manage Tivoli Monitoring Services check box is selected to automatically launch the Manage Tivoli Enterprise Monitoring Services utility after these configuration steps are completed, to support additional configuration tasks and to start monitoring functions. By default, all of the setup types are already selected for configuration. In most cases, accept the default selection of these configuration options, and click Next to continue. You can clear any of the selections to postpone these configuration tasks until after the installation is completed. 10. Because the portal server is installed on this computer, the TEPS Hostname window is displayed, as shown in Figure 15 on page 45:
44
Installation Guide
Figure 15. The TEPS Hostname window
The hostname for the local computer is displayed in the field, indicating the default location for the portal server. Accept this default or type in the host name of the computer where the portal server is installed. Click Next. 11. The InstallShield Wizard Complete window is displayed as shown in Figure 10 on page 39, indicating that the installation was successful, and offering you the option to view the README file for the product, which might contain additional information of interest to you. The check box for displaying the README file is already selected. Leave the check box selected to automatically display the README, or clear this check box to not display the README file if you have already seen it (this readme.txt file is also available in the \WINDOWS directory on the installation media), and click Finish to close the installation program. 12. Because you selected the Launch Manage Tivoli Monitoring Services check box in Figure 14 on page 44, the Manage Tivoli Enterprise Monitoring Services utility is displayed, showing the Tivoli Enterprise Portal Server (see Figure 16 on page 46). If additional components of IBM Tivoli Monitoring are installed on this system, they are also displayed.
45
Figure 16. The Tivoli Enterprise Portal Server in the Manage Tivoli Enterprise Monitoring Services utility
If you did not select the option to launch the Manage Tivoli Enterprise Monitoring Services utility, you can launch it manually by selecting Start > All Programs > IBM Tivoli Monitoring > Manage Tivoli Monitoring Services. Verify that the Configured column shows Yes, meaning that Tivoli Enterprise Portal Server is successfully configured and started.
Linux or AIX: Installing application support on the portal server

Use the following steps to install application support for IBM Tivoli Composite Application Manager for SOA on the portal server installed on a supported Linux or AIX operating system. Refer to the IBM Tivoli Monitoring documentation for general procedures for installing application support for the portal server on these operating systems. 1. Change to the <ITM_Home>/bin directory. 2. Stop the Tivoli Enterprise Portal Server by running the following command:
./itmcmd agent stop cq
3. Close the Manage Tivoli Enterprise Monitoring Services utility if it is open. 4. Mount the IBM Tivoli Composite Application Manager for SOA installation media at the location you have chosen on the local system, following the standard procedures for your operating system. 5. From the root directory of the installation media, enter the following command to start the installation program:
./install.sh
Type 1 to start the installation and press Enter. 8. Type the number that corresponds to the language in which you want to display the software license agreement and press Enter. 9. Press Enter to display the agreement. 10. Type 1 to accept the agreement and press Enter.
46
Installation Guide
11. A numbered list of available operating systems and installation components is displayed. Type the number that corresponds to Tivoli Enterprise Portal Server Browser Client support and press Enter. 12. Type y to confirm and press Enter. 13. A list of the components to install is displayed. Type the number that corresponds to selecting all components to install and press Enter. 14. Type y to confirm the installation. The installation begins. 15. After all of the components are installed, you are asked whether you want to install components for a different operating system. Type y and press Enter. 16. A numbered list of available operating systems and installation components is displayed. Type the number that corresponds to Tivoli Enterprise Portal Server support and press Enter. 17. Type y to confirm and press Enter. 18. A list of the components to install is displayed. Type the number that corresponds to selecting all components to install and press Enter. 19. Type y to confirm the installation. The installation begins. 20. After all of the components are installed, you are asked whether you want to install components for a different operating system. Type n and press Enter. 21. Stop the portal server by running the following command:
./itmcmd agent stop cq
22. Run the following command to configure the portal server with the new agent information:
./itmcmd config A cq
Complete the configuration as prompted, accepting default values where possible. For information regarding configuring the portal server, see the section on Configuring the portal server on Linux, in the IBM Tivoli Monitoring: Installation and Setup Guide. 23. Start the portal server by running the following command:
./itmcmd agent start cq
Installing application support on the desktop client

When you install the IBM Tivoli Composite Application Manager for SOA monitoring agent on one or more computer systems in your environment where you plan to monitor services, you must also install application support files containing agent specific information for the monitoring agent on the computer system where the Tivoli Enterprise Portal desktop client is installed. When you install the application support on your Tivoli Enterprise Portal desktop client, you should be logged in as the user who installed Tivoli Enterprise Portal. Use the following sections to install application support on the desktop client in your environment: v Windows: Installing application support on the desktop client v Linux: Installing application support on the desktop client on page 51
Windows: Installing application support on the desktop client

Use the following steps to install application support for IBM Tivoli Composite Application Manager for SOA on theTivoli Enterprise Portal desktop client installed on a supported Windows operating system: Note: The desktop client is stopped during this process.
47
Use the following steps to install required application support on a Windows desktop client: 1. Stop the Tivoli Enterprise Portal desktop client, either by exiting the client console, or by opening the Manage Tivoli Enterprise Monitoring Services utility and by right-clicking on the desktop client and clicking Stop. 2. Insert the IBM Tivoli Composite Application Manager for SOA installation media into the appropriate drive. The installation program starts automatically. 3. If the installation program does not start automatically, open a command prompt window, navigate to the appropriate drive, open the \WINDOWS folder, and issue the following command:
setup.exe
One or more welcome pages are displayed. Click Next. 4. A Software License Agreement page might be displayed. Read the terms in the license agreement as presented in the scrollable window and, if you agree to abide by those terms, click Accept. You must accept the terms of the license agreement to continue the installation. 5. The Select Features page is displayed, similar to Figure 17, showing the available features that you can install for this product. If you have already installed a monitoring agent or other IBM Tivoli Monitoring components on this computer, the check boxes for these features are already selected. Select Tivoli Enterprise Portal Desktop Client and click Next.
Figure 17. The Select Features page for installing application support on the desktop client
Is the Tivoli Enterprise Monitoring Server or Tivoli Enterprise Portal Server also installed on this computer?: If so, you can also select those components to install application support for IBM Tivoli Composite Application Manager for SOA now, or follow the procedures in this publication to separately install application support for these components at a later time.
48
Installation Guide
6. The Start Copying Files page is displayed, similar to Figure 18. Review the installation summary details and verify your selections. Click Next to start the installation.
Figure 18. The Start Copying Files page for installing application support on Tivoli Enterprise Portal desktop client.
7. After installation is complete, the Setup Type configuration page is displayed, as shown in Figure 19 on page 50.
49
This page offers several configuration options to install and configure application support for the desktop client: v Select Configure Tivoli Enterprise Portal to add application support for IBM Tivoli Composite Application Manager for SOA workspaces and situations in Tivoli Enterprise Portal desktop client. v Select Launch Manage Tivoli Monitoring Services to automatically launch the Manage Tivoli Enterprise Monitoring Services utility after these configuration steps are completed, to support additional configuration tasks and to start monitoring functions. By default, all of the setup types are already selected for configuration. In most cases, accept the default selection of these configuration options, and click Next to continue. You can clear any of the selections to postpone these configuration tasks until after the installation is completed. 8. Because you installed the Tivoli Enterprise Portal desktop client on this computer, the TEPS Hostname page is displayed, as shown in Figure 15 on page 45. Specify the host name for the computer system where the Tivoli Enterprise Portal Server is installed. Click Next. 9. The InstallShield Wizard Complete page is displayed as shown in Figure 10 on page 39, indicating that the installation was successful, and offering you the option to view the README file for the product, which might contain additional information of interest to you. The check box for displaying the README file is already selected. Leave the check box selected to automatically display the README, or clear this check box to not display the README file if you have already seen it (this readme.txt file is also available in the \WINDOWS directory on the installation media), and click Finish to close the installation program.
50
Installation Guide
10. Because you selected the Launch Manage Tivoli Monitoring Services check box in Figure 14 on page 44, the Manage Tivoli Enterprise Monitoring Services utility is displayed, showing the Tivoli Enterprise Portal desktop client (see Figure 20). If additional components of IBM Tivoli Monitoring are installed on this system, they are also displayed.
Figure 20. The Tivoli Enterprise Portal desktop client in the Manage Tivoli Enterprise Monitoring Services utility
If you did not select the option to launch the Manage Tivoli Enterprise Monitoring Services utility, you can launch it manually by selecting Start > All Programs > IBM Tivoli Monitoring > Manage Tivoli Monitoring Services. Verify that the Configured column shows Yes, meaning that the Tivoli Enterprise Portal desktop client is successfully configured and started.
Linux: Installing application support on the desktop client

Use the following steps to install application support for IBM Tivoli Composite Application Manager for SOA on the Tivoli Enterprise Portal desktop client installed on a supported Linux operating system. Refer to the IBM Tivoli Monitoring documentation for general procedures for installing application support for the Tivoli Enterprise Portal desktop client on this operating system. 1. Change to the <ITM_Home>/bin directory. 2. Stop the Tivoli Enterprise Portal desktop client by running the following command:
./itmcmd agent stop cj
3. Close the Manage Tivoli Enterprise Monitoring Services utility if it is open. 4. Mount the IBM Tivoli Composite Application Manager for SOA installation media at the location you have chosen on the local system, following the standard procedures for your operating system. 5. From the root directory of the installation media, run the following command to start the installation program:
./install.sh
Type 1 to start the installation and press Enter.

51
8. Type the number that corresponds to the language in which you want to display the software license agreement and press Enter. 9. Press Enter to display the agreement. 10. Type 1 to accept the agreement and press Enter. 11. A numbered list of available operating systems and installation components is displayed. Type the number that corresponds to Tivoli Enterprise Portal Desktop Client support and press Enter. 12. Type y to confirm and press Enter. 13. A list of the components to install is displayed. Type the number that corresponds to selecting all components to install and press Enter. 14. Type y to confirm the installation. The installation begins. 15. After all of the components are installed, you are asked whether you want to install components for a different operating system. Type n and press Enter. 16. Run the following command to configure the Tivoli Enterprise Portal desktop client with the new agent information:
./itmcmd config A cj
Complete the configuration as prompted. For information regarding configuring the Tivoli Enterprise Portal desktop client, see the section on Configuring the portal desktop client on Linux, in the IBM Tivoli Monitoring: Installation and Setup Guide. 17. Start the Tivoli Enterprise Portal desktop client by running the following command:
./itmcmd agent start cj
Installing the monitoring agent

This procedure describes how to install the IBM Tivoli Composite Application Manager for SOA monitoring agent in an application server environment where services are to be monitored, or, in the case of DataPower, where the monitoring agent, acting as a DataPower proxy, is running. You must perform the installation of IBM Tivoli Composite Application Manager for SOA on each computer with one or more supported application server runtime environments (for example, IBM WebSphere Application Server, Microsoft .Net, JBoss, WebSphere CE, BEA WebLogic Server, and others) that are hosting services (or, in the case of DataPower, where the DataPower proxy data collector is to be located). On each of these systems, you must run the IBM Tivoli Composite Application Manager for SOA installation program and select to install the Tivoli Enterprise Monitoring Agent components. This includes the monitoring agent and the data collector component that intercepts request and response messages for services that you want to monitor. This installation procedure is based on the following assumptions: v You have already installed or upgraded your IBM Tivoli Monitoring environment to one of the minimum supported levels (see Upgrading your IBM Tivoli Monitoring environment on page 21. v As part of the process for installing or upgrading your IBM Tivoli Monitoring environment, you should have also installed and configured one or more supported database applications (IBM DB2, Microsoft SQL Server, or Oracle). This is useful if you are planning to collect monitoring data for services and write it to a historical database, for later retrieval and visualizing using IBM Web
52
Installation Guide
Services Navigator or other applications. You also need database application support if you plan to view service registry and business process integration data and service-to-service topology data in IBM Tivoli Monitoring workspaces and views. See Planning database support on page 13 for general information about planning for databases in your ITCAM for SOA environment. v You should have previously completed upgrading or installing application support as described in these sections of this guide: Installing application support on monitoring servers on page 29 Installing application support on the Tivoli Enterprise Portal Server on page 41 Installing application support on the desktop client on page 47 The following sections describe the procedures for installing the Tivoli Enterprise Monitoring Agents feature of IBM Tivoli Composite Application Manager for SOA into your application server runtime environment where services traffic is to be monitored. v Windows: Installing the monitoring agent on page 54 v Linux, AIX, HP-UX, or Solaris: Installing the monitoring agent on page 60 If you have monitoring agents for other products installed on the computer where you plan to install the ITCAM for SOA monitoring agent, you should install the ITCAM for SOA agent under the same directory.
Permissions needed to install the monitoring agent

To install the monitoring agent, be sure that you have the following required permissions: v For supported Windows operating systems: You must have Administrator privileges on a computer to install a component such as a monitoring agent. You must also run the IBM Tivoli Monitoring component (in this case the monitoring agent) as a user with Administrator privileges. All IBM Tivoli Monitoring components on a computer should be installed and run using the same user. See the User Authority section of the IBM Tivoli Monitoring Installation and Setup Guide for more information on permissions. v For supported Linux and UNIX operating systems: If you have multiple ITM components (including multiple monitoring agents) installed on the same computer, you should install all of the agents using the same user. (The only exception is the TEPS which must be installed as root.) If you do not want to install ITM components such as monitoring agents as root on Linux and UNIX, the Create an IBM Tivoli account for installing and maintaining the installation directory section in the ITM Install and Setup Guide, indicates you should create an account/user on the computer where you plan to install a ITM component such as a monitoring agent and use it to install all ITM related components (except for TEPS) on that computer. Refer to that section for more details. When you install the ITCAM for SOA monitoring agent as a non-root user on Linux and AIX, you should follow this procedure: 1. Install ITCAM for SOA monitoring agent 2. Copy the KD4BaseDirConfig.properties from the <ITM_home>/<platform>/d4/ KD4/config directory to the /etc directory after the installation completes. This step might require your user to have root authority.
53
3. Follow the instructions in Changing the file permissions for agents on page 62. These instructions direct you to create a group (for example, itmusers) that owns all of the IBM Tivoli Monitoring component files on the computer system.
Windows: Installing the monitoring agent

To install the IBM Tivoli Composite Application Manager for SOA monitoring agent on a supported Windows operating system, complete the following steps on each computer hosting one or more application servers where you are monitoring services.
Before running the installation program

Before running the installation program, complete the following steps: 1. If the Manage Tivoli Enterprise Monitoring Services utility is open on this application server, close it. 2. Stop BEA WebLogic Servers: If you already have BEA WebLogic Server running on the same target computer system where you are installing IBM Tivoli Composite Application Manager for SOA, stop the BEA WebLogic Server before installing the product. 3. If you are installing over an existing installation: If your supported application server runtime environment is already running on this system, with the exception of BEA WebLogic Server, you do not need to stop the application server before running the installation program, unless you are installing over an existing installation of IBM Tivoli Composite Application Manager for SOA. If you already installed the monitoring agent on this system and are installing it again over the existing installation, complete these steps: a. Stop all application servers on the computer where the monitoring agent is being installed. b. If you have the Microsoft .Net application server environment running on this application server, stop the w3svc service. c. If you have a DataPower data collector proxy running on this computer system, stop it before you proceed. d. Disable any existing ITCAM for SOA data collectors on the local system, using the existing documented procedures for the existing version of data collectors.
Running the installation program

Run the installation program provided on the IBM Tivoli Composite Application Manager for SOA installation media on a supported Windows operating system by completing the following steps for each computer (or, in the case of DataPower, on the computer where the DataPower proxy data collector will be located) where you are installing the monitoring agent: 1. Insert the IBM Tivoli Composite Application Manager for SOA installation media into the appropriate drive. The installation program starts automatically. 2. If the installation program does not start automatically, open a command prompt, navigate to the appropriate drive, open the \WINDOWS folder, and run the following command:
setup.exe
3. A Welcome page is displayed. Click Next.
54
Installation Guide
4. The Software License Agreement page is displayed. Read the terms in the license agreement as presented in the scrollable window and, if you agree to abide by those terms, click Accept. You must accept the terms of the license agreement to continue the installation. 5. If you do not have a database (IBM DB2 or Microsoft SQL Server) installed on this computer, a message regarding potentially missing software is displayed. You do not need a database to install the monitoring agent on this computer, so ignore this message and click Next. A database is required only if you have the Tivoli Enterprise Portal Server installed on this computer. Note that this database is only used by the Tivoli Enterprise Portal Server for temporarily storing data before forwarding it on to the monitoring server. This is not the IBM DB2, Microsoft SQL Server, or Oracle warehouse database that is used for historical data collection. 6. If you are installing on a computer that does not already have one or more components of IBM Tivoli Monitoring installed, you are prompted for the target destination location for this installation, as shown in Figure 21. The default location is C:\IBM\ITM. Accept this default or specify the directory path where IBM Tivoli Monitoring is installed. Note: If you are installing over an existing installation, the existing installation directory location is used.
Figure 21. Choosing the destination installation directory.
7. If you are installing IBM Tivoli Composite Application Manager for SOA over an existing installation, you might receive a message if there are newer versions of products to install. Note that newer version of support files might not work correctly with previous versions of the agent. This message reminds you that as you select the features to install in the windows that follow, you can choose to not install newer versions of products. Click OK.
55
8. The User Data Encryption Key page is displayed, as shown in Figure 22. You can enter a unique 32 character key for encrypting your Secure Socket Layer (SSL) connections with Tivoli Enterprise Monitoring Server to protect sensitive data being transmitted. If you do enter your own unique encryption key, be sure to use the same key consistently across your enterprise (if you have IBM Tivoli Monitoring components already installed on other computer systems, you might already have specified an encryption key for your enterprise. Consult with your local system administrator for assistance to make sure you specify the right key). A default value, IBMTivoliMonitoringEncryptionKey, is provided in the Key field. Either accept this default value, or enter your own encryption key, and click Next to continue. Note that this key must be identical across your enterprise.
Figure 22. The User Data Encryption Key page
9. The Select Features page is displayed, showing the available features that you can install for this product. The Tivoli Enterprise Monitoring Agents feature includes the monitoring agent and associated data collectors that monitor services on this system. If a component is already installed on this computer system, the check box is already selected, but if this is a new installation, the Tivoli Enterprise Monitoring Agents check box is cleared. Expand the Tivoli Enterprise Monitoring Agents node to see the Monitoring Agent for Composite Application Manager for SOA check box. Select this check box and notice that a second check box for Tivoli Enterprise Monitoring Agent Framework is automatically selected for you (both of these check boxes must be selected to install IBM Tivoli Composite Application Manager for SOA), as shown in Figure 23 on page 57. Click Next to continue.
56
Installation Guide
Figure 23. The Select Features page, showing the expanded Tivoli Enterprise Monitoring Agents node.
10. The Select Program Folder page is displayed as shown in Figure 24 on page 58, prompting you for the name of the program folder where program icons are stored. Accept the default folder name, for example, IBM Tivoli Monitoring, or type over the default name in the Program Folder field and click Next to continue.
57
Figure 24. Specifying the program folder name
11. The Start Copying Files page is displayed, as shown in Figure 25 on page 59. Verify your selection, and click Next to start copying files.
58
Installation Guide
Figure 25. The Start Copying Files page
12. The Setup Status page is displayed, with a progress indicator bar as the files are copied to your workstation. 13. After the files are successfully copied to your workstation, the Setup Type page is displayed. This page offers the Launch Manage Tivoli Monitoring Services check box. Select this check box to automatically launch the Manage Tivoli Enterprise Monitoring Services utility after these configuration steps are completed, to support additional configuration tasks and to start monitoring functions. In most cases, accept the default selection of configuration options on this page, and click Next to continue. You can clear any of the selections to postpone these configuration tasks until after the installation is completed. 14. The InstallShield Wizard Complete page is displayed (see Figure 10 on page 39), indicating that the installation was successful, and offering you the option to view the README file for the product, which might contain additional information of interest to you. The check box for displaying the README file is already selected. Leave the check box selected to automatically display the README, or clear this check box to not display the README file if you have already seen it (this readme.txt file is also available in the \WINDOWS directory on the installation media), and click Finish to close the installation program. 15. Because you selected the Launch Manage Tivoli Monitoring Services check box in step 13, the Manage Tivoli Enterprise Monitoring Services utility is displayed, showing the IBM Tivoli Composite Application Manager for SOA monitoring agent as ITCAM for SOA (see Figure 26 on page 60). If additional components of IBM Tivoli Monitoring are installed on this system, they are also displayed.
59
Figure 26. The ITCAM for SOA monitoring agent in the Manage Tivoli Enterprise Monitoring Services utility
If you did not select the option to launch the Manage Tivoli Enterprise Monitoring Services utility, you can launch it manually by selecting Start > All Programs > IBM Tivoli Monitoring > Manage Tivoli Monitoring Services. Verify that the Configured column shows Yes and the Status column shows Started, meaning that the monitoring agent is successfully configured and started.
After running the installation program

After completing these steps, continue with these additional configuration procedures: v Chapter 4, Configuring topology support, on page 65 v Part 2, Configuring for data collection, on page 125 v Part 3, Completing your installation, on page 241
Linux, AIX, HP-UX, or Solaris: Installing the monitoring agent

To install IBM Tivoli Composite Application Manager for SOA on a supported Linux, AIX, HP-UX, or Solaris operating system, complete the following steps on each Linux, AIX, HP-UX, or Solaris computer system where you plan to monitor services. See the IBM Tivoli Monitoring documentation for general procedures for installing monitoring agents on these operating systems. 1. Close the Manage Tivoli Enterprise Monitoring Services utility if it is open. 2. If you are upgrading or reinstalling the monitoring agent over an existing installation, stop the appropriate application servers and disable existing data collectors before upgrading or reinstalling. 3. Mount the IBM Tivoli Composite Application Manager for SOA installation media at the location you have chosen on the local system, following the standard procedures for your operating system. 4. From the root directory of the installation media, run the ./install.sh script to start the installation program. 5. When prompted for the IBM Tivoli Monitoring home directory, press Enter to accept the default (/opt/IBM/ITM) or type the full path to a different directory. Note: If you are installing over an existing installation, you must use the existing installation directory. 6. If the installation directory does not already exist, you are asked if you want to create it. Type y to create this directory and press Enter. The following prompt is displayed:
Select one of the following: 1) Install products to the local host. 2) Install products to depot for remote deployment (requires TEMS) 3) Exit install. Please enter a valid number:
60
Installation Guide
7. 8. 9. 10. 11.
12.
Note: This prompt might vary depending on the installation image from which you are installing. Type 1 to start the installation and press Enter. Type the number that corresponds to the language (for example, English) in which you want to display the software license agreement, and press Enter. Press Enter to display the agreement. Type 1 to accept the agreement and press Enter. Type a 32 character key for encrypting your Secure Socket Layer (SSL) connections with Tivoli Enterprise Monitoring Server to protect sensitive data being transmitted. This key should be the same key that is specified during the installation of the Tivoli Enterprise Monitoring Server to which this monitoring agent connects. A numbered list of available operating systems is displayed. Type the number for the operating system on which you are installing. The default value is your current operating system. Press Enter. Installing on Linux x86-64 operating systems: When installing on a supported Linux x86-64 operating system, choose the ITCAM for SOA V07.11.00.00 for Linux AMD64 R2.6 (64 bit) option.
13. Type y to confirm your operating system and press Enter. 14. A numbered list of available agents is displayed. Find the IBM Tivoli Composite Application Manager for SOA agent and type the corresponding number and press Enter. 15. A list of the components to install is displayed. Type y to confirm the installation. 16. The installation begins. After all of the components are installed, you are asked if you want to install additional products or product support packages. Accept the default response of n and press Enter.
Configuring the monitoring agent

Use the following steps to configure the monitoring agent on Linux, AIX, HP-UX, or Solaris operating systems: 1. Navigate to the <ITM_Home>/bin directory, and run the following command:
./itmcmd config -A d4
2. Press Enter when you are asked if the monitoring agent connects to a monitoring server. 3. Type the hostname for the monitoring server. 4. Type the type of protocol that the monitoring agent uses to communicate with the monitoring server. You have four choices: ip, sna, ip.spipe, or ip.pipe. Press Enter to accept the default protocol (IP.PIPE). 5. If you want to set up a backup protocol, enter that protocol and press Enter. If you do not want to use backup protocol, press Enter without specifying a protocol. If the method you have identified as Protocol 1 fails, Protocol 2 is used. See the IBM Tivoli Monitoring documentation for more information about available protocol selections. 6. Depending on the types of protocols you specified, provide the information described in Table 6 on page 62 when prompted:
61
Table 6. Linux, AIX, HP-UX, and Solaris Protocol settings for communicating between the monitoring agent and Tivoli Enterprise Monitoring Server Protocol IP.UDP Value IP Port Number Description The listening port for the Tivoli Enterprise Monitoring Server to which this monitoring agent is connected. The default value is 1918.
IP.PIPE
IP.PIPE Port Number The listening port for the Tivoli Enterprise Monitoring Server to which this monitoring agent is connected. The default value is 1918. IP.SPIPE Port Number Network Name LU Name The listening port for the Tivoli Enterprise Monitoring Server to which this monitoring agent is connected. The default value is 3660. The SNA network identifier for your location. The LU name for the Tivoli Enterprise Monitoring Server. This LU name corresponds to the local LU Alias in your SNA communications software. The name of the LU6.2 LOGMODE. The default value is CANCTDCS.
IP.SPIPE
SNA
Log Mode
7. Press Enter to not specify the name of the KDC_PARTITION. 8. Press Enter when you are asked if you want to configure the connection to a secondary monitoring server. The default response is no. 9. Press Enter to accept the default for the Optional Primary Network Name (none).
Changing the file permissions for agents

If you used a non-root user to install the monitoring agent on a Linux, AIX, HP-UX, or Solaris operating system, the file permissions are initially set to a low level. Use the following procedure to change these file permissions: 1. Log on to the computer as root, or become the root user by running the su command. 2. Create a new group (such as itmusers) to own all of the files in the IBM Tivoli Monitoring installation directory. For supported Linux HP-UX,, and Solaris operating systems, run the following command:
groupadd itmusers
For supported AIX operating systems, run the following command:

mkgroup itmusers
3. Change to <ITM_Home> (for information about this variable, see Resolving directory path variables on page xviii. Important: Running the following steps in the wrong directory can change the permissions on every file in every file system on the computer. 4. Run the following command to ensure that you are in the correct directory:
pwd
5. Run the following commands:

chgrp -R itmusers . chmod -R g+rwx .
6. Run the following command to change the ownership of additional agent files:
bin/SetPerm
62
Installation Guide
7. If you want to run the agent as a particular user, add the user to the itmusers group. To do this, edit the /etc/group file and ensure that the user is in the list of users for the itmusers group. For example, if you want to run the agent as user test1, ensure that the following line is in the /etc/group file:
itmusers:x:504:test1
8. Run the su command to switch to the user that you want to run the agent as or log in as that user. 9. For all monitored environments except for DataPower: a. If the application servers being monitored were installed as a different user than the one used to install and run the ITCAM for SOA monitoring agent, add the user which owns the application server environment to the group created in the previous step. (See the data collector specific chapters in part 2 of this book for the access permissions needed by the application server user.) b. Navigate to the <ITM_home>/<platform>/d4/ KD4 directory and run the following command:
chmod -R g+rwx
c. Switch to the user for the application server runtime environment. d. Enable the data collector using the procedures documented in part 2 of this guide for the specific application server runtime environment. 10. If you are monitoring a DataPower environment, enable the data collector with the same user that runs the monitoring agent (this can be the same user who installed the agent). See Chapter 13, Configuring data collection: DataPower SOA Appliance, on page 201 for more information about enabling data collection for the DataPower environment. Note: During installation, you might see messages displayed similar to these examples:
tar: tar: tar: tar: tar: tar: tar: tar: tar: can't can't can't can't can't can't can't can't can't set set set set set set set set set time time time time time time time time time on on on on on on on on on gsk7bas64/install: Not owner gsk7bas64/reloc/ibm/gsk_64/bin: Not owner gsk7bas64/reloc/ibm/gsk_64/classes/jre: Not owner gsk7bas64/reloc/ibm/gsk_64/classes/jre/lib: Not owner gsk7bas64/reloc/ibm/gsk_64/classes/jre/lib/ext: Not owner gsk7bas64/reloc/ibm/gsk_64/classes: Not owner gsk7bas64/reloc/ibm/gsk_64/classes/native: Not owner gsk7bas64/reloc/ibm/gsk_64/icc/icclib: Not owner gsk7bas64/reloc/ibm/gsk_64/icc: Not owner
These messages do not affect the installation, and can be ignored. You might choose to change the permissions on these files to eliminate these messages. After completing these steps, continue with these additional configuration procedures: v Chapter 4, Configuring topology support, on page 65 v Part 2, Configuring for data collection, on page 125 v Part 3, Completing your installation, on page 241
63
64
Installation Guide
Chapter 4. Configuring topology support

IBM Tivoli Composite Application Manager for SOA supports the discovery, storage, and display of information about service resources (application servers, service ports, and operations) and relationships between them. These service-to-service relationships and flows can then be displayed in Tivoli Enterprise Portal topology workspaces and views. IBM Tivoli Composite Application Manager for SOA provides two key components for this topology support: v The Tivoli Common Object Repository component, which stores topology data from one or more Discovery Library Adapters, including service registry and business process integration relationships. v The SOA Domain Management Server component, which stores information about service resources and service-to-service relationships and flows, and also retrieves topology data from Tivoli Common Object Repository for displaying in topology workspaces and views. Both the SOA Domain Management Server component and the Tivoli Common Object Repository component of IBM Tivoli Composite Application Manager for SOA use local or remote databases to contain their service resource and topology data. You have the option of configuring the SOA Domain Management Server to operate with or without Tivoli Common Object Repository: v If you want to display only service-to-service topology views, then you only need to configure support for SOA Domain Management Server, and you do not need to configure support for Tivoli Common Object Repository. v If you want both service-to-service topology views and service registry and business process integration topology views, then you must configure both the SOA Domain Management Server and Tivoli Common Object Repository support. v If you want to display only service registry and business process integration topology views, you still must configure support for both the SOA Domain Management Server and Tivoli Common Object Repository. v You can choose to configure SOA Domain Management Server only, and then return at a later time to configure Tivoli Common Object Repository. As in previous releases, the SOA Domain Management Server and Tivoli Common Object Repository support are configured on your Tivoli Enterprise Portal Server in the runtime environment called Tivoli Enterprise Portal Server Extensions, which is an additional feature provided with IBM Tivoli Monitoring Version 6.2 or later. The configuration process involves the following general steps: 1. Create a local or remote SOA Domain Management Server database? The SOA Domain Management Server database that contains information about service-to-service relationships can be created on either a supported DB2 server or a supported Microsoft SQL server. This server can be installed on either the local Tivoli Enterprise Portal Server computer or on a different, remote database server. If this server is installed on the same computer as Tivoli Enterprise Portal Server, it is typically the same database server used by Tivoli Enterprise Portal Server. When creating the SOA Domain Management Server database, you have the following options:
65
v Let the SOA Domain Management Server Configuration Utility create and configure the SOA Domain Management Server database locally on your Tivoli Enterprise Portal Server computer. v Manually create the SOA Domain Management Server database locally before running the SOA Domain Management Server Configuration Utility. v Manually create the SOA Domain Management Server database remotely before running the SOA Domain Management Server Configuration Utility. See Creating the SOA Domain Management Server database on page 67 for more information about creating a local or remote SOA Domain Management Server database. 2. Create a local or remote Tivoli Common Object Repository database? The Tivoli Common Object Repository database that contains information about service registry and business process integration data must be created on a supported DB2 database server. The DB2 server can be installed on either the local Tivoli Enterprise Portal Server computer or on a different, remote database server. When creating the Tivoli Common Object Repository database, you have the following options: v Let the SOA Domain Management Server Configuration Utility create and configure the Tivoli Common Object Repository database locally on your Tivoli Enterprise Portal Server computer. v Manually create the Tivoli Common Object Repository database locally before running the SOA Domain Management Server Configuration Utility. v Manually create the Tivoli Common Object Repository database remotely before running the SOA Domain Management Server Configuration Utility. See Creating the Tivoli Common Object Repository database on page 74 for more information about creating a local or remote Tivoli Common Object Repository database. 3. Run the SOA Domain Management Server Configuration Utility: The SOA Domain Management Server Configuration Utility provides a graphical user interface to help you configure SOA Domain Management Server and Tivoli Common Object Repository on supported Windows, Linux, and AIX operating systems. Console mode and silent mode options are also available. Run the SOA Domain Management Server Configuration Utility to configure SOA Domain Management Server support, and optionally configure Tivoli Common Object Repository support. You are prompted for all required information to complete these configuration steps. See Running the SOA Domain Management Server Configuration Utility on page 78 for more information on this utility. Database permissions: You need database administrative authority to create the databases used with SOA Domain Management Server and Tivoli Common Object Repository. You should coordinate this with your local database administrator to get the database created, and to set up an appropriate database user if you do not have this authority. See the sections below for more information about the type of database authority that you need. Microsoft 2005 JDBC driver support: If you are planning to create databases using Microsoft SQL Server, you must use the Microsoft 2005 JDBC driver with ITCAM for SOA version 7.1.1. The Microsoft SQL Server 2005 JDBC 1.2 driver jar file must be used for both Microsoft SQL Server 2000 and Microsoft SQL Server 2005, and is available as a free download from the Microsoft Download Center:
http://www.microsoft.com/downloads
66
Installation Guide
The sections that follow describe how to configure the SOA Domain Management Server and optional Tivoli Common Object Repository support on supported operating systems and on local and remote database servers.
Minimum space requirements on the file system

Before you configure SOA Domain Management Server and optional Tivoli Common Object Repository, you must ensure that you have enough available space on the partition where IBM Tivoli Monitoring is installed. When you install the ITCAM for SOA support files on Tivoli Enterprise Portal Server, you need at least 150MB of available space. When you configure SOA Domain Management Server and optional Tivoli Common Object Repository, you need an additional 300 MB to accommodate the files needed for these components, including room for growth for Tivoli Common Object Repository bulk load results files.
Creating the SOA Domain Management Server database

When creating the SOA Domain Management Server database, you have the following options: v Let the SOA Domain Management Server Configuration Utility create and configure the SOA Domain Management Server database locally on your Tivoli Enterprise Portal Server computer. If you plan to locate the SOA Domain Management Server database locally on the same computer as Tivoli Enterprise Portal Server and do not want to create your own database before running the SOA Domain Management Server Configuration Utility, then no action is required at this time. The database will be created automatically for you when you run the configuration utility. Note that you must have database administrative privileges if you use the SOA Domain Management Server Configuration Utility to create the SOA Domain Management Server database. v Manually create the SOA Domain Management Server database locally before running the SOA Domain Management Server Configuration Utility. You might choose this option if your database administrator wants to create the local database for you, before you run the configuration utility to configure topology support. v Manually create the SOA Domain Management Server database remotely before running the SOA Domain Management Server Configuration Utility. You might choose this option if you do not want to use the local database server, or if your database administrator wants to create the remote database for you, before you run the configuration utility to configure topology support.
Manually creating a local SOA Domain Management Server database

To create and configure the SOA Domain Management Server database locally, use the scripts found in the <TEPS_Home>/Products/KD4/latest/bin directory on the computer where Tivoli Enterprise Portal Server is installed.
Running the script on a local Windows operating system

On supported Windows operating systems, you can use either DB2 or Microsoft SQL Server to create the SOA Domain Management Server database. To run the script on the local computer for DB2, complete these steps: 1. Ensure that your user name has Windows and DB2 administrative privileges on the local computer (for example, a user in the Administrators and DB2ADMNS groups).
67
2. Open a DB2 Command Line Processor window (select Start > Run and enter the db2cmd command). 3. In the DB2 Command Line Processor window, navigate to the <ITM_Home>\CNPS\Products\KD4\latest\bin directory. Verify that your user has read, write, and execute permissions for this directory. 4. Run the kd4MakeDB2db.bat script and provide a name for the SOA Domain Management Server database, such as KD4SDMS. The name can have a maximum of eight characters. For example:
kd4MakeDB2db KD4SDMS
Note: If this database already exists on the local system, it is dropped and recreated. If you do not want to drop an existing database, specify a different name. 5. Wait for the database creation process to complete. The script verifies the database version and displays a message if it is at an unsupported level. The output generated by this script is written to a file called createDB2DBResults.txt in the same directory where the script is run. See the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide for assistance with any errors that you encounter. 6. Close the DB2 command line window. Database user access: When you later run the SOA Domain Management Server Configuration Utility to configure the SOA Domain Management Server database, you are prompted for a database username and password to access the database. If you do not want to specify a database administrator username (such as the default, db2admin), use DB2 utilities to create a user authorized to access the SOA Domain Management Server database. This user must be authorized to connect to the database, create tables, and must be able to perform select, insert, update, and delete operations on all tables in the database. To run the script on the local computer for Microsoft SQL Server, complete these steps: 1. Ensure that your user name has appropriate Windows and Microsoft SQL Server database permissions. To create the SOA Domain Management Server database using Microsoft SQL Server, the Authentication mode for the SQL server must be configured for Mixed Mode (Windows Authentication and SQL Server Authentication). With this authentication mode, both Windows Authentication and Microsoft SQL Server Authentication are enabled. When using Microsoft SQL Server Authentication, a user logging in to Microsoft SQL Server must supply a username and a password that Microsoft SQL Server validates against a system table. Using this security model, login as a user that is a member of the SQL Server sysadmin role group to create the SOA Domain Management Server database. 2. No specialized command line environment is required. Open a command line window. 3. Navigate to the <ITM_Home>\CNPS\Products\KD4\latest\bin directory. Verify that your user has read, write, and execute permissions for this directory. 4. Run the kd4MakeMSSQLdb.bat script using this syntax:
kd4MakeMSSQLdb <dbname> <dbuser> <dbpassword> <dbtype> [<dbInstance>]
Specify these parameters:
68
Installation Guide
<dbname> Specifies the SOA Domain Management Server database name, for example, KD4SDMS. The name can have a maximum of 128 characters. Note: If this database already exists on the local system, it is dropped and recreated. If you do not want to drop an existing database, specify a different name. <dbuser> Specifies the Microsoft SQL Server database server login name, for example, sdms. This name can be any existing or non-existing user, except for the reserved user name, sa. If the name that you specify does not already exist, it is created in the Microsoft SQL Server registry. The user is granted the db_owner role for the database. <dbpassword> Specifies the database password for the specified user <dbuser>. <dbtype> Specifies the version of your Microsoft SQL Server installation. Valid values are MSSQL2000 or MSSQL2005. <dbInstance> Optional: Specifies a named instance of Microsoft SQL Server, in the form of <database_hostname>\<instance_name>, where <database_hostname> is the name of the computer where the database server is installed, and <instance_name> is the instance name, for example, localhost\MyInstance. If no value is specified, the default instance is assumed. 5. Wait for the database creation process to complete. The script verifies the database version and displays a message if it is at an unsupported level. The output generated by this script is written to a file called createMSSQLDBResults.txt in the same directory where the script is run. 6. Close the command line window. Database user access: When you later run the SOA Domain Management Server Configuration Utility to configure the SOA Domain Management Server database, you are prompted for a database username and password to access the database. You must use the same user name and password that were used when the kd4MakeMSSQLdb script was run to create the database.
Running the script on a local Linux or UNIX operating system

On supported Linux or UNIX operating systems, you can only use DB2 to create the SOA Domain Management Server database. To run the script on the local computer for DB2, complete these steps: 1. Ensure that your user name belongs to the DB2 instance administrative group (for example, db2grp1). 2. Source the DB2 instance profile by performing the following steps: v Navigate to /home/<dbuser>/sqllib, where <dbuser> is the DB2 instance user name (for example, db2inst1). v Run the following command:
. ./db2profile
69
Note: Be sure to leave a space between the first period and the ./db2profile command 3. Navigate to the <ITM_Home>/<platform>/cq/Products/KD4/latest/bin directory. For information about resolving directory path variables, see Resolving directory path variables on page xviii. 4. Ensure that your user name has permission to read and execute the kd4MakeDB2db.sh script and write permission for the directory containing the script. 5. Run the kd4MakeDB2db.sh script and provide a name for the SOA Domain Management Server database, such as KD4SDMS. The name can have a maximum of eight characters. For example:
./kd4MakeDB2db.sh KD4SDMS
Note: If this database already exists on the local system, it is dropped and recreated. If you do not want to drop an existing database, specify a different name. 6. Wait for the database creation process to complete. The script verifies the database version and displays a message if it is at an unsupported level. The output generated by this script is written to a file called createDB2DBResults.txt in the same directory where the script is run. See the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide for assistance with any errors that you might encounter. Database user access: When you later run the SOA Domain Management Server Configuration Utility to configure the SOA Domain Management Server database, you are prompted for a database username and password to access the database. If you do not want to specify a database administrator username (such as the default, db2inst1), use DB2 utilities to create a user authorized to access the SOA Domain Management Server database. This user must be authorized to connect to the database, create tables, and must be able to perform select, insert, update, and delete operations on all tables in the database.
Manually creating a remote SOA Domain Management Server database

To create and configure the SOA Domain Management Server database remotely, copy the kd4RemoteDB.zip (for Windows) or kd4RemoteDB.tar.gz (for UNIX or Linux) file from the <TEPS_Home>/Products/KD4/latest/db directory (on the computer where your Tivoli Enterprise Portal Server is installed) to the remote computer where you plan to create the SOA Domain Management Server database, unpack this file into any directory, and run the scripts provided to create the database as needed. Note that this kd4RemoteDB file is only available after ITCAM for SOA application support is installed. On Linux or UNIX operating systems, use the following command to unpack the file:
tar -xzvf kd4RemoteDB.tar.gz
Use gunzip utility for AIX systems: The tar command for AIX operating systems does not support the z option to extract files from a tar.gz file. If you are using the AIX operating system, you should download the gunzip utility, which you can use to extract files from a .tar.gz file. The kd4RemoteDB compressed file includes a subset of the following files, depending on the operating system you are using:
70
Installation Guide
kd4MakeMSSQLdb.bat Creates the SOA Domain Management Server database and database schema for Microsoft SQL Server 2000 and Microsoft SQL Server 2005 on Windows operating systems. sdms_mssql.sql Contains the SOA Domain Management Server schema definition for Microsoft SQL Server 2000 and Microsoft SQL Server 2005 (this file is input for kd4MakeMSSQLdb.bat) kd4MakeDB2db.bat Creates the SOA Domain Management Server database and database schema for DB2 on Windows operating systems kd4MakeDB2db.sh Creates the SOA Domain Management Server database and database schema for DB2 on UNIX or Linux operating systems sdms_db2.sql Contains the SOA Domain Management Server schema definition for DB2 (this file is input for kd4MakeDB2db.bat or kd4MakeDB2db.sh) sdms_mssql_delta.sql Contains the SOA Domain Management Server schema changes from IBM Tivoli Composite Application Manager for SOA version 7.1.0 to version 7.1.1. You can use this file to upgrade a Microsoft SQL Server version 2000 or version 2005 SOA Domain Management Server database from version 7.1.0 to version 7.1.1. (Note that IBM Tivoli Composite Application Manager for SOA version 7.1.0 does not actually support remote SOA Domain Management Server databases. This file is included in the kd4RemoteDB compressed file for completeness.) sdms_db2_delta.sql Contains the SOA Domain Management Server schema changes from IBM Tivoli Composite Application Manager for SOA version 7.1.0 to version 7.1.1. You can use this file to upgrade an IBM DB2 database from version 7.1.0 to version 7.1.1. (Note that IBM Tivoli Composite Application Manager for SOA version 7.1.0 does not actually support remote SOA Domain Management Server databases. This file is included in the kd4RemoteDB compressed file for completeness.) kd4UpdateIP.bat Updates IP Addresses in the Managed System table of your SOA Domain Management Server database on Windows operating systems (works with IBM DB2, Microsoft SQL Server 2000 and Microsoft SQL Server 2005 databases). See the IBM Tivoli Composite Application Manager for SOA User's Guide for more information about updating IP addresses for operation instances. kd4UpdateIP.sh Updates IP Addresses in the Managed System table of your SOA Domain Management Server database on UNIX or Linux operating systems (works with DB2 databases). See the IBM Tivoli Composite Application Manager for SOA User's Guide for more information about updating IP addresses for operation instances.
Running the script on a remote Windows operating system

On supported Windows operating systems, you can use either DB2 or Microsoft SQL Server to create the SOA Domain Management Server database.
71
To run the script on the remote computer for DB2, complete these steps: 1. Ensure that your user name has Windows and DB2 administrative privileges on the remote computer (for example, the user name should be included in the Administrators and DB2ADMNS groups). 2. Open a DB2 Command Line Processor window (select Start > Run and enter the db2cmd command). 3. In the DB2 Command Line Processor window, navigate to the directory where the kd4MakeDB2db.bat script is located. Verify your user has read, write, and execute permissions for this directory. 4. Run the kd4MakeDB2db.bat script and provide a name for the SOA Domain Management Server database, such as KD4SDMS. The name can have a maximum of eight characters. For example:
kd4MakeDB2db KD4SDMS
Note: If this database already exists on the remote system, it is dropped and recreated. If you do not want to drop an existing database, specify a different name. 5. Wait for the database creation process to complete. The script verifies the database version and displays a message if it is at an unsupported level. The output generated by this script is written to a file called createDB2DBResults.txt in the same directory where the script is run. See the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide for assistance with any errors that you might encounter. 6. Close the DB2 command line window. Database user access: When you later run the SOA Domain Management Server Configuration Utility to configure the SOA Domain Management Server database, you are prompted for a database username and password to access the database. If you do not want to specify a database administrator username (such as the default, db2admin), use DB2 utilities to create a user authorized to access the SOA Domain Management Server database. This user must be authorized to connect to the database, create tables, and must be able to perform select, insert, update, and delete operations on all tables in the database. To run the script on the remote computer for Microsoft SQL Server, complete these steps: 1. Ensure that your user name has Windows and Microsoft SQL Server administrative privileges (typically a user in the Windows Administrators group). To create the SOA Domain Management Server database using Microsoft SQL Server, the Authentication mode for the SQL server must be configured for Mixed Mode (Windows Authentication and SQL Server Authentication). With this authentication mode, both Windows Authentication and Microsoft SQL Server Authentication are enabled. When using Microsoft SQL Server Authentication, a user logging in to Microsoft SQL Server must supply a username and a password that Microsoft SQL Server validates against a system table. Using this security model, login as a user that is a member of the SQL Server sysadmin role group to create the SOA Domain Management Server database. 2. No specialized command line environment is required. Open a command line window. 3. Navigate to the directory where the kd4MakeMSSQLdb.bat script is located. 4. Run the kd4MakeMSSQLdb.bat script using this syntax:
kd4MakeMSSQLdb <dbname> <dbuser> <dbpassword> <dbtype> [<dbInstance>]
72
Installation Guide
Specify these parameters: <dbname> Specifies the SOA Domain Management Server database name, for example, KD4SDMS. The name can have a maximum of 128 characters. Note: If this database already exists on the remote system, it is dropped and recreated. If you do not want to drop an existing database, specify a different name. <dbuser> Specifies the Microsoft SQL Server database server login name, for example, sdms. This name can be any existing or non-existing user, except for the reserved user name, sa. If the name that you specify does not already exist, it is created in the Microsoft SQL Server registry. This user is granted the db_owner role for the database. <dbpassword> Specifies the database password for the specified user <dbuser>. <dbtype> Specifies the version of your Microsoft SQL Server installation. Valid values are MSSQL2000 or MSSQL2005. <dbInstance> Optional: Specifies a named instance of Microsoft SQL Server, in the form of <database_hostname>\<instance_name>, where <database_hostname> is the name of the computer where the database server is installed, and <instance_name> is the instance name, for example, localhost\MyInstance. If no value is specified, the default instance is assumed. 5. Wait for the database creation process to complete. The script verifies the database version and displays a message if it is at an unsupported level. The output generated by this script is written to a file called createMSSQLDBResults.txt in the same directory where the script is run. 6. Close the command line window. Database user access: When you later run the SOA Domain Management Server Configuration Utility to configure the SOA Domain Management Server database, you are prompted for a database username and password to access the database. You must use the same user name and password that were used when the kd4MakeMSSQLdb script was run to create the database.
Running the script on a remote Linux or UNIX operating system

On supported Linux or UNIX operating systems, you can only use DB2 to create the SOA Domain Management Server database. To run the script on the remote computer for DB2, complete these steps: 1. Login to the remote computer as a user that belongs to the DB2 instance administrative group (for example, db2grp1). 2. Source the DB2 profile for the instance user. v Navigate to /home/<dbuser>/sqllib, where <dbuser> is the DB2 instance user name (for example, db2inst1). v Run the following command:
. ./db2profile
73
Note: Be sure to leave a space between the first period and the ./db2profile command 3. Navigate to the directory where the kd4MakeDB2db.sh script is located. 4. Ensure that the user has permission to read and execute the unpacked files and write permission for the directory containing the unpacked files. 5. Run the kd4MakeDB2db.sh script and provide a name for the SOA Domain Management Server database, such as KD4SDMS. The name can have a maximum of eight characters. For example:
./kd4MakeDB2db.sh KD4SDMS
Note: If this database already exists on the remote system, it is dropped and recreated. If you do not want to drop an existing database, specify a different name. 6. Wait for the database creation process to complete. The script verifies the database version and displays a message if it is at an unsupported level. The output generated by this script is written to a file called createDB2DBResults.txt in the same directory where the script is run. See the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide for assistance with any errors that you might encounter. Database user access: When you later run the SOA Domain Management Server Configuration Utility to configure the SOA Domain Management Server database, you are prompted for a database username and password to access the database. If you do not want to specify a database administrator username (such as the default, db2inst1), use DB2 utilities to create a user authorized to access the SOA Domain Management Server database. This user must be authorized to connect to the database, create tables, and must be able to perform select, insert, update, and delete operations on all tables in the database.
Creating the Tivoli Common Object Repository database

When creating the Tivoli Common Object Repository database, you have the following options: v Let the SOA Domain Management Server Configuration Utility create and configure the Tivoli Common Object Repository database locally on your Tivoli Enterprise Portal Server computer. If you plan to locate the Tivoli Common Object Repository database locally on the same computer as Tivoli Enterprise Portal Server and do not want to create your own database before running the SOA Domain Management Server Configuration Utility, then no action is required at this time. The database will be created automatically for you when you run the configuration utility. You must have database administrative privileges if you use the SOA Domain Management Server Configuration Utility to create the Tivoli Common Object Repository database. v Manually create the Tivoli Common Object Repository database locally before running the SOA Domain Management Server Configuration Utility. You might choose this option if your database administrator wants to create the local database for you, before you run the configuration utility to configure topology support. v Manually create the Tivoli Common Object Repository database remotely before running the SOA Domain Management Server Configuration Utility. You might choose this option if you do not want to use the local database server for this database, or if the local database server uses Microsoft SQL Server, or your database administrator wants to create the remote database for you, before you run the configuration utility to configure topology support.
74
Installation Guide
Manually creating a local Tivoli Common Object Repository database

To create and configure the Tivoli Common Object Repository database locally, use the make_db2_db.bat script (for Windows) or make_db2_db.sh script (for Linux or UNIX) found in the <TEPS_Home>/Products/KD4/latest/tcore/db directory on the computer where Tivoli Enterprise Portal Server is installed. Note that this script creates the Tivoli Common Object Repository database but does not create the database schema or tables. The schema and tables are created when you run the SOA Domain Management Server Configuration Utility to configure Tivoli Common Object Repository.
Running the script on a local Windows operating system

Complete these steps if your Tivoli Enterprise Portal Server is installed on a Windows operating system: 1. Ensure that your user name has Windows and DB2 administrative privileges. 2. Open a DB2 Command Line Processor window (select Start > Run and enter the db2cmd command). 3. In the DB2 Command Line Processor window, navigate to the <ITM_Home>\CNPS\Products\KD4\latest\tcore\db directory. Verify your user has read and execute permission for the make_db2_db.bat script in this directory. 4. Run the make_db2_db.bat script and provide a name for the Tivoli Common Object Repository database, such as KD4TCORE. The name can have a maximum of eight characters. For example:
make_db2_db KD4TCORE
Note: If this database already exists on the local system, it is dropped and recreated. If you do not want to drop an existing database, specify a different name. 5. Wait for the database creation process to complete. 6. Close the DB2 Command Line Processor window. See the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide for assistance with any errors that you might encounter. Database user access: When you later run the SOA Domain Management Server Configuration Utility to configure the Tivoli Common Object Repository database, you are prompted for a database username and password to access the database. If you do not want to specify a database administrator username (such as the default, db2admin), use DB2 utilities to create a user authorized to access the Tivoli Common Object Repository database. This user must have database administrative authority for the Tivoli Common Object Repository database.
Running the script on a local Linux or UNIX operating system

Complete these steps if your Tivoli Enterprise Portal Server is installed on a Linux or UNIX operating system: 1. Ensure that you are logged in as a user that belongs to the DB2 instance administrative group (for example, db2grp1). 2. Source the DB2 profile for the instance user. v Navigate to /home/<dbuser>/sqllib, where <dbuser> is the DB2 instance user name (for example, db2inst1). v Run the following command:
. ./db2profile
75
Note: Be sure to leave a space between the first period and the ./db2profile command 3. Navigate to the <ITM_Home>/<platform>/cq/Products/KD4/latest/tcore/db/ directory. For information about resolving directory path variables, see Resolving directory path variables on page xviii. 4. Ensure that your user name has permission to read and execute the make_db2_db.sh file. 5. Run the make_db2_db.sh script and provide a name for the Tivoli Common Object Repository database, such as KD4TCORE. This name can have a maximum of eight characters. For example:
./make_db2_db.sh KD4TCORE
Note: If this database already exists on the local system, it is dropped and recreated. If you do not want to drop an existing database, specify a different name. 6. Wait for the database creation process to complete. See the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide for assistance with any errors that you might encounter. Database user access: When you later run the SOA Domain Management Server Configuration Utility to configure the Tivoli Common Object Repository database, you are prompted for a database username and password to access the database. If you do not want to specify a database administrator username (such as the default, db2inst1), use DB2 utilities to create a user authorized to access the Tivoli Common Object Repository database. This user must have database administrative authority for the Tivoli Common Object Repository database.
Manually creating a remote Tivoli Common Object Repository database

To create and configure the Tivoli Common Object Repository database remotely, you need to copy the make_db2_db.bat script (for Windows) or make_db2_db.sh script (for UNIX or Linux) from the <TEPS_Home>\Products\KD4\latest\tcore\db directory (on the computer where your Tivoli Enterprise Portal Server is installed) to the remote computer where you plan to create the Tivoli Common Object Repository database, and run this script to create the database. The following sections provide more details.
Running the scripts on a remote Windows operating system

Complete these steps: 1. Locate the make_db2_db.bat script on your Tivoli Enterprise Portal Server computer: v If your Tivoli Enterprise Portal Server is computer is running in a supported Windows operating system, navigate to the <ITM_Home>\CNPS\Products\ KD4\latest\tcore\db directory. v If your Tivoli Enterprise Portal Server is computer is running in a supported Linux or UNIX operating system, navigate to the <ITM_Home>/<platform>/cq/ Products/KD4/latest/tcore/db/ directory. For information about resolving these directory path variables, see Resolving directory path variables on page xviii. 2. Copy the make_db2_db.bat script file to a temporary directory on your remote DB2 server computer.
76
Installation Guide
3. Switch to your remote DB2 server computer, and login as a user with Windows and DB2 administrative privileges. 4. Open a DB2 Command Line Processor window (select Start > Run and enter the db2cmd command). 5. In the DB2 Command Line Processor window, navigate to the directory containing the make_db2_db.bat file. Verify your user has read and execute permission for the make_db2_db.bat script in this directory. 6. Run the make_db2_db.bat script and provide a name for the Tivoli Common Object Repository database, such as KD4TCORE. The name can have a maximum of eight characters. For example:
make_db2_db KD4TCORE
Note: If this database already exists on the remote system, it is dropped and recreated. If you do not want to drop an existing database, specify a different name. 7. Wait for the database creation process to complete. 8. Close the DB2 Command Line Processor window. See the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide for assistance with any errors that you might encounter. Database user access: When you later run the SOA Domain Management Server Configuration Utility to configure the Tivoli Common Object Repository database, you are prompted for a database username and password to access the database. If you do not want to specify a database administrator username (such as the default, db2admin), use DB2 utilities to create a user authorized to access the Tivoli Common Object Repository database. This user must have database administrative authority for the Tivoli Common Object Repository database.
Running the scripts on a remote Linux or UNIX operating system

Complete these steps: 1. Locate the make_db2_db.sh script on your Tivoli Enterprise Portal Server computer: v If your Tivoli Enterprise Portal Server is computer is running in a supported Windows operating system, navigate to the <ITM_Home>\CNPS\Products\ KD4\latest\tcore\db directory. v If your Tivoli Enterprise Portal Server is computer is running in a supported Linux or UNIX operating system, navigate to the <ITM_Home>/<platform>/cq/ Products/KD4/latest/tcore/db/ directory. For information about resolving these directory path variables, see Resolving directory path variables on page xviii. 2. Copy the make_db2_db.sh script file to a temporary directory on your remote DB2 server computer. 3. Switch to your remote DB2 server computer, and login as a user that belongs to the DB2 instance administrative group (for example, db2grp1). 4. Ensure that your user name has permission to read and execute the make_db2_db.sh file. 5. Source the DB2 profile for the instance user. v Navigate to /home/<dbuser>/sqllib, where <dbuser> is the DB2 instance user name (for example, db2inst1). v Run the following command:
. ./db2profile
77
Note: Be sure to leave a space between the first period and the ./db2profile command 6. Run the make_db2_db.sh script and provide a name for the Tivoli Common Object Repository database, such as KD4TCORE. This name can have a maximum of eight characters. For example:
./make_db2_db.sh KD4TCORE
Note: If this database already exists on the remote system, it is dropped and recreated. If you do not want to drop an existing database, specify a different name. 7. Wait for the database creation process to complete. See the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide for assistance with any errors that you might encounter. Database user access: When you later run the SOA Domain Management Server Configuration Utility to configure the Tivoli Common Object Repository database, you are prompted for a database username and password to access the database. If you do not want to specify a database administrator username (such as the default, db2inst1), use DB2 utilities to create a user authorized to access the Tivoli Common Object Repository database. This user must have database administrative authority for the Tivoli Common Object Repository database.
Running the SOA Domain Management Server Configuration Utility

IBM Tivoli Composite Application Manager for SOA provides the SOA Domain Management Server Configuration Utility that simplifies the configuration of SOA Domain Management Server and Tivoli Common Object Repository topology support. The utility runs in either a graphical user interface mode or in console mode. A silent configuration method is also supported, and optional logging controls are provided to help you diagnose problems. In addition to configuring topology support, the SOA Domain Management Server Configuration Utility can create local SOA Domain Management Server and Tivoli Common Object Repository databases for you if you have not previously created them yourself. If preferred, you (or your database administrator) can manually create these databases ahead of time, either locally on the Tivoli Enterprise Portal Server computer, or on a remote computer, using the database creation scripts provided with IBM Tivoli Composite Application Manager for SOA. See Creating the SOA Domain Management Server database on page 67 and Creating the Tivoli Common Object Repository database on page 74 for the procedures to create these databases before running the SOA Domain Management Server Configuration Utility. You can use the utility to perform any of the following functions: v If you are performing a fresh install of ITCAM for SOA Version 7.1.1, use the SOA Domain Management Server Configuration Utility to configure SOA Domain Management Server and optionally configure Tivoli Common Object Repository. v If you are upgrading from a previous version of ITCAM for SOA, you use the SOA Domain Management Server Configuration Utility to upgrade SOA Domain Management Server and Tivoli Common Object Repository (if it is configured). v If you have configured SOA Domain Management Server for ITCAM for SOA Version 7.1.1 but not Tivoli Common Object Repository, you can use the SOA Domain Management Server Configuration Utility to configure Tivoli Common Object Repository at a later point.
78
Installation Guide
v If your SOA Domain Management Server database password has changed, you use the SOA Domain Management Server Configuration Utility to update the database password used to access the SOA Domain Management Server database. v If your Tivoli Common Object Repository database password has changed, you use the SOA Domain Management Server Configuration Utility to update the database password used to access the Tivoli Common Object Repository database. v If you are installing an ITCAM for SOA fix pack that updates SOA Domain Management Server and Tivoli Common Object Repository, you use the SOA Domain Management Server Configuration Utility to update these components.
Upgrading from a previous version

This version of IBM Tivoli Composite Application Manager for SOA includes the ability to upgrade your SOA Domain Management Server and Tivoli Common Object Repository configuration from a previous version.
Upgrading from Version 6.1

When you upgrade from a previous ITCAM for SOA version 6.1 configuration to a version 7.1.1 configuration, you run the SOA Domain Management Server Configuration Utility to configure the SOA Domain Management Server for the first time, and upgrade the configuration for Tivoli Common Object Repository. Because Tivoli Common Object Repository was always configured in version 6.1, the SOA Domain Management Server Configuration Utility presents you with only one option, to upgrade both SOA Domain Management Server and Tivoli Common Object Repository together. Upgrading SOA Domain Management Server: Because the SOA Domain Management Server component did not have a database in IBM Tivoli Composite Application Manager for SOA version 6.1, the SOA Domain Management Server Configuration Utility prompts you for the same information as if you were configuring SOA Domain Management Server during a first time configuration in version 7.1.1 If preferred, you can create the SOA Domain Management Server local or remote database manually, using the procedures described in Creating the SOA Domain Management Server database on page 67, or you can let the SOA Domain Management Server Configuration Utility create a local SOA Domain Management Server database for you. If you create the database using Microsoft SQL Server, the configuration utility checks for the existence of the version 2005 JDBC drivers in the default location, C:\Program Files\Microsoft SQL Server 2005 JDBC Driver\sqljdbc_1.2\enu\sqljdbc.jar. If these drivers are not found, you must enter the location of these drivers manually. Upgrading Tivoli Common Object Repository: The SOA Domain Management Server Configuration Utility upgrades the existing Tivoli Common Object Repository configuration automatically. User credentials and Tivoli Common Object Repository properties are saved and copied over to the upgraded configuration. User settings in properties files such as collation.properties and bulkload.properties are also preserved. When you upgrade from a previous ITCAM for SOA version 6.1 configuration to a version 7.1.1 configuration, you are prompted to enter SOA Domain Management Server database information so that the database can be created. After the SOA Domain Management Server database is created successfully, the upgrade of Tivoli Common Object Repository occurs automatically (that is, you are not first prompted to continue with the upgrade of Tivoli Common Object Repository). If either part of
79
this upgrade process does not complete successfully, an error message is displayed. You will need to resolve the problem and then run ConfigDMS again.
Upgrading from Version 7.1.0

When you upgrade from a previous ITCAM for SOA version 7.1.0 installation to a 7.1.1 installation, you run the SOA Domain Management Server Configuration Utility to upgrade the configuration for SOA Domain Management Server, and optionally, for Tivoli Common Object Repository, if it exists. In version 7.1.0, the Tivoli Common Object Repository component was optional. The SOA Domain Management Server Configuration Utility automatically detects whether Tivoli Common Object Repository is configured, and presents you with one of two options: v If Tivoli Common Object Repository is not configured, an option to upgrade only SOA Domain Management Server is presented. After SOA Domain Management Server is successfully upgraded, an option to configure Tivoli Common Object Repository is presented. v If both SOA Domain Management Server and Tivoli Common Object Repository are configured from the previous version, an option to upgrade both components together is presented. Upgrading SOA Domain Management Server: The SOA Domain Management Server Configuration Utility automatically upgrades the SOA Domain Management Server component. Keep in mind the following considerations: v In version 7.1.0, the SOA Domain Management Server database always resides on the same computer as SOA Domain Management Server, so the local database is updated. v You should not create the SOA Domain Management Server database manually because it already exists and will be upgraded when you run the SOA Domain Management Server Configuration Utility. v For version 7.1.0, the SOA Domain Management Server database could be created only with IBM DB2 or Microsoft SQL Server 2000. If your existing database uses Microsoft SQL Server 2000, you must ensure that the Microsoft SQL Server 2005 JDBC drivers are located in your environment, as this is the supported JDBC driver for SOA Domain Management Server version 7.1.1. The SOA Domain Management Server Configuration Utility verifies if the Microsoft SQL Server 2005 JDBC drivers exists in the default location, C:\Program Files\Microsoft SQL Server 2005 JDBC Driver\sqljdbc_1.2\enu\sqljdbc.jar. If the drivers are not found in this location, you must manually specify the location where they are located. v In version 7.1.0, the configuration of SOA Domain Management Server with Microsoft SQL Server 2000 did not require specifying a port number. However, during the upgrade to version 7.1.1, you are prompted to specify the port number for use with the Microsoft SQL Server 2000 database Upgrading Tivoli Common Object Repository: The SOA Domain Management Server Configuration Utility automatically upgrades the Tivoli Common Object Repository component to the version 7.1.1 level if it is configured. User credentials and properties are preserved during the upgrade. User settings in properties files such as collation.properties and bulkload.properties are also preserved. When you upgrade both SOA Domain Management Server and Tivoli Common Object Repository from a previous ITCAM for SOA version 7.1 configuration to a version 7.1.1 configuration, SOA Domain Management Server is upgraded first, and then the upgrade of Tivoli Common Object Repository occurs automatically (you are not first prompted to continue with the upgrade of Tivoli Common Object
80
Installation Guide
Repository). If either part of this upgrade process does not complete successfully, an error message is displayed. You will need to resolve the problem and then run ConfigDMS again.
Upgrading in silent mode

The upgrade_tcore property in the silent response file is replaced in this version with the upgrade property. This property specifies whether or not to upgrade a previous configuration of both SOA Domain Management Server and Tivoli Common Object Repository to version 7.1.1, depending on already configured components: v If Tivoli Common Object Repository version 6.1 is configured, SOA Domain Management Server and Tivoli Common Object Repository are upgraded to version 7.1.1. v If only SOA Domain Management Server version 7.1 is configured, SOA Domain Management Server is upgraded to version 7.1.1. v If SOA Domain Management Server and Tivoli Common Object Repository version 7.1 is configured, both are upgraded to version 7.1.1. See Table 7 on page 114 for the silent response file properties that you need to specify while upgrading using silent mode.
Database and user permissions

When you run the SOA Domain Management Server Configuration Utility (also referred to in this section by its script name, ConfigDMS), you need certain minimum user permissions, depending on the task you are performing. The following sections describe the permissions that you need for each task. This section also describes the authorization required for the database user that is specified when you run the SOA Domain Management Server Configuration Utility.
Permissions needed when configuring SOA Domain Management Server

When you configure SOA Domain Management Server, you can either use ConfigDMS to create the SOA Domain Management Server database as a new database, or you can run ConfigDMS after separately creating the SOA Domain Management Server database. Using ConfigDMS to create the local SOA Domain Management Server database: If you use ConfigDMS to create the local SOA Domain Management Server database, you need certain permissions depending on whether you create the database in DB2 or Microsoft SQL Server: When creating the SOA Domain Management Server database in DB2: Running ConfigDMS on Windows operating systems Your user must have Windows and DB2 administrative privileges, and be the user who installed IBM Tivoli Monitoring. For example, the user should be included in both the Administrators and DB2ADMNS groups.In addition, the user must have read, write, and modify permissions for these directories: v <ITM_Home>\CNPS directory and its subdirectories v <ITM_Home>\CNPSJ directory and its subdirectories v <ITM_Home>\logs directory Running ConfigDMS on Linux or AIX operating systems The user must be the user used to install IBM Tivoli Monitoring (root or
81
db2inst1) and must have permission to reconfigure and run Tivoli Enterprise Portal Server, and must have read, write, and execute permissions for the following directories: v v v v <ITM_Home>/<platform>/cq directory and its subdirectories <ITM_Home>/<platform>/iw directory and its subdirectories <ITM_Home>/config directory <ITM_Home>/logs directory
In addition, if you are running the SOA Domain Management Server Configuration Utility as the root user, your root user must also have the following capabilities: v The user must be able to source the DB2 instance profile. v The user must be authorized to issue the following command:
su - <DB_USER>
In this command, <DB_USER> refers to the database administrator user that is configured for the SOA Domain Management Server database using ConfigDMS. The user specified by <DB_USER> must have read, write, and execute permissions for the <ITM_Home>/<platform>/cq/ Products/KD4/latest/bin directory. If your database administrator user does not have read, write, and execute permissions for these directories, you can use the following alternative procedure: 1. Copy the kd4RemoteDB.tar.gz file from the <ITM_Home>/<platform>/ cq/Products/KD4/latest/db directory to a local directory on the computer where the DB2 administrator has read, write, and execute permission and extract the files. 2. Run the kd4MakeDB2db script while logged in as the database administrator. 3. Run the SOA Domain Management Server Configuration Utility as the user who installed IBM Tivoli Monitoring and select the option to use an existing database. See Creating the SOA Domain Management Server database on page 67 for more information about manually creating the SOA Domain Management Server database using the kd4MakeDB2db script and the permissions that are required. Authorization of database user specified using ConfigDMS The user must be an existing DB2 administrator user (for example, db2admin on Windows operating systems, or db2inst1 on Linux or AIX operating systems). This user is the same user as specified by <DB_USER>. On Linux or AIX operating systems, the DB2 profile must automatically be sourced when you login as this user. This user is not used as the database schema name. The schema name is always SDMS. When creating the SOA Domain Management Server database in Microsoft SQL Server: Running ConfigDMS on Windows operating systems To create the SOA Domain Management Server database using Microsoft SQL Server, the Authentication mode for the SQL server must be configured for Mixed Mode (Windows Authentication and SQL Server Authentication). With this authentication mode, both Windows Authentication and Microsoft SQL Server Authentication are enabled. When using Microsoft SQL Server Authentication, a user logging in to Microsoft SQL
82
Installation Guide
Server must supply a username and a password that Microsoft SQL Server validates against a system table. Using this security model, login as a user that is a member of the SQL Server sysadmin role group to create the SOA Domain Management Server database.In addition, the user must have read, write, and modify permissions for these directories: v <ITM_Home>\CNPS directory and its subdirectories v <ITM_Home>\CNPSJ directory and its subdirectories v <ITM_Home>\logs directory Authorization of server login specified using ConfigDMS The server login user can be any existing or non-existing user, except for the reserved user, sa. If the server login user that you specify does not already exist, it is created in the SQL Server registry. ConfigDMS assigns this user the db_owner role for the SOA Domain Management Server database. Using ConfigDMS after the SOA Domain Management Server database has been previously created: You or your database administrator might have already created the SOA Domain Management Server database using the procedures documented in Creating the SOA Domain Management Server database on page 67. If so, the user permissions needed to configure SOA Domain Management Server depend on the database application used to create the database: When the SOA Domain Management Server database was created in DB2: Running ConfigDMS on Windows operating systems Your user must have Windows administrative privileges and be the user who installed IBM Tivoli Monitoring. For example, the user should be included in the Administrators group. In addition, the user must have read, write, and modify permissions for these directories: v <ITM_Home>\CNPS directory and its subdirectories v <ITM_Home>\CNPSJ directory and its subdirectories v <ITM_Home>\logs directory Running ConfigDMS on Linux or AIX operating systems The user must be the user used to install IBM Tivoli Monitoring (root or db2inst1) and must have permission to reconfigure and run Tivoli Enterprise Portal Server, and must have read, write, and execute permissions for the following directories: v <ITM_home>/<platform>/cq directory and its subdirectories v <ITM_home>/<platform>/iw directory and its subdirectories v <ITM_home>/config directory v <ITM_home>/logs directory Authorization of database user specified using ConfigDMS The user must be either of the following types: v A DB2 administrator user (for example, db2admin on Windows operating systems, or db2inst1 on Linux or AIX operating systems) v A database user specific to the SOA Domain Management Server database that has at least the following authorizations: Connect to the database Create tables Perform select, insert, update, and delete operations on the tables in the database.
83
This user must already exist, and is used by SOA Domain Management Server to access the database at runtime. This user is not used as the database schema name. The schema name is always SDMS. When the SOA Domain Management Server database was created in Microsoft SQL Server: Running ConfigDMS on Windows operating systems Your user must have Windows administrative privileges and be the user who installed IBM Tivoli Monitoring. For example, the user should be included in the Administrators group. In addition, the user must have read, write, and modify permissions for these directories: v <ITM_Home>\CNPS directory and its subdirectories v <ITM_Home>\CNPSJ directory and its subdirectories v <ITM_Home>\logs directory Authorization of server login specified using ConfigDMS The user must be the server login user specified when the kd4MakeMSSQLdb script was run on the database server.
Permissions needed when configuring Tivoli Common Object Repository

When you configure Tivoli Common Object Repository, you can either use ConfigDMS to create the Tivoli Common Object Repository database as a new database, or you can run ConfigDMS after separately creating the Tivoli Common Object Repository database. Note that the Tivoli Common Object Repository database can only be created in DB2. Using ConfigDMS to create the local Tivoli Common Object Repository database: When you use ConfigDMS to create the Tivoli Common Object Repository database: Running ConfigDMS on Windows operating systems Your user must have Windows and DB2 administrative privileges and be the user who installed IBM Tivoli Monitoring. For example, the user should be included in both the Administrators and DB2ADMNS groups. In addition, the user must have read, write, and modify permissions for these directories: v <ITM_Home>\CNPS directory and its subdirectories v <ITM_Home>\CNPSJ directory and its subdirectories v <ITM_Home>\logs directory Running ConfigDMS on Linux or AIX operating systems The user must be the user used to install IBM Tivoli Monitoring (root or db2inst1) and must have permission to reconfigure and run Tivoli Enterprise Portal Server, and must have read, write, and execute permissions for the following directories: v <ITM_Home>/<platform>/cq directory and its subdirectories v <ITM_Home>/<platform>/iw directory and its subdirectories v <ITM_Home>/config directory v <ITM_Home>\logs directory In addition, if you are running the SOA Domain Management Server Configuration Utility as the root user, your root user must also have the following capabilities:
84
Installation Guide
v The user must be able to source the DB2 instance profile. v The user must be authorized to issue the following command:
su - <DB_USER>
In this command, <DB_USER> refers to the database administrator user that should be used when creating the database. The user specified by <DB_USER> must have read, write, and execute permissions for the <ITM_Home>/<platform>/cq/Products/KD4/latest/bin directory. If your database administrator user does not have read, write, and execute permissions for these directories, you can use the following alternative procedure: 1. Copy the make_db2_db.sh file from the <ITM_Home>/<platform>/cq/ Products/KD4/latest/tcore/db directory to a local directory on the computer where the DB2 administrator has read, write, and execute permissions. 2. Run the make_db2_db.sh script while logged in as the database administrator. 3. Run the SOA Domain Management Server Configuration Utility as the user who installed IBM Tivoli Monitoring and select the option to use an existing Tivoli Common Object Repository database. See Creating the Tivoli Common Object Repository database on page 74 for more information about manually creating the Tivoli Common Object Repository database using the make_db2_db.sh script and the permissions that are required. Authorization of database user specified using ConfigDMS The user must be a DB2 administrator user (for example, db2admin on Windows operating systems, or db2inst1 on Linux or AIX operating systems). This user must already exist, and is used to create the database and to access the database at runtime. On Linux or AIX operating systems, the DB2 profile must automatically be sourced when you login as this user. This user is also used as the database schema name. Using ConfigDMS after the Tivoli Common Object Repository database has been previously created: You or your database administrator might have already created the Tivoli Common Object Repository database using the procedures documented in Creating the Tivoli Common Object Repository database on page 74. If so, the user must have the following permissions when you use ConfigDMS to configure Tivoli Common Object Repository: Running ConfigDMS on Windows operating systems Your user must have Windows administrative privileges and be the user who installed IBM Tivoli Monitoring. For example, the user should be included in the Administrators group. In addition, the user must have read, write, and modify permissions for these directories: v <ITM_Home>\CNPS directory and its subdirectories v <ITM_Home>\CNPSJ directory and its subdirectories v <ITM_Home>\logs directory Running ConfigDMS on Linux or AIX operating systems The user must be the user used to install IBM Tivoli Monitoring (root or db2inst1) and must have permission to reconfigure and run Tivoli Enterprise Portal Server, and must have read, write, and execute permissions for the following directories:
85
v v v v
<ITM_Home>/<platform>/cq directory and its subdirectories <ITM_Home>/<platform>/iw directory and its subdirectories <ITM_Home>/config directory <ITM_Home>\logs directory
Authorization of database user specified using ConfigDMS The user must be either of the following types: v A DB2 administrator user (for example, db2admin on Windows operating systems, or db2inst1 on Linux or AIX operating systems) v A database user specific to the Tivoli Common Object Repository database that has administrative authority for the database. This user is also used as the Tivoli Common Object Repository database schema name.
Permissions needed when upgrading SOA Domain Management Server and Tivoli Common Object Repository from ITCAM for SOA version 6.1 to version 7.1.1
When you upgrade SOA Domain Management Server and Tivoli Common Object Repository from ITCAM for SOA version 6.1 to version 7.1.1, you must have certain user permissions when running ConfigDMS, depending on whether you use ConfigDMS to create the local SOA Domain Management Server database, or if you run ConfigDMS after the database has been previously created. Using ConfigDMS to create the local SOA Domain Management Server database: If you use ConfigDMS to create the local SOA Domain Management Server database, you need certain permissions depending on whether you create the database in DB2 or Microsoft SQL Server: When creating the SOA Domain Management Server database in DB2: Running ConfigDMS on Windows operating systems Your user must have Windows and DB2 administrative privileges and be the user who installed IBM Tivoli Monitoring. For example, the user should be included in both the Administrators and DB2ADMNS groups. In addition, the user must have read, write, and modify permissions for these directories: v <ITM_Home>\CNPS directory and its subdirectories v <ITM_Home>\CNPSJ directory and its subdirectories v <ITM_Home>\logs directory Running ConfigDMS on Linux or AIX operating systems The user must be the user used to install IBM Tivoli Monitoring (root or db2inst1) and must have permission to reconfigure and run Tivoli Enterprise Portal Server, and must have read, write, and execute permissions for the following directories: v v v v <ITM_Home>/<platform>/cq directory and its subdirectories <ITM_Home>/<platform>/iw directory and its subdirectories <ITM_Home>/config directory <ITM_Home>\logs directory
In addition, if you are running ConfigDMS as the root user, your root user must also have the following capabilities: v The user must be able to source the DB2 instance profile. v The user must be authorized to issue the following command:
su - <DB_USER>
86
Installation Guide
In this command, <DB_USER> refers to the database administrator user that should be used when creating the database.The user specified by <DB_USER> must have read, write, and execute permissions for the <ITM_Home>/<platform>/cq/Products/KD4/latest/bin directory. If your database administrator user does not have read, write, and execute permissions for these directories, you can use the following alternative procedure: 1. Copy the kd4RemoteDB.tar.gz file from the <ITM_Home>/<platform>/cq/ Products/KD4/latest/db directory to a local directory on the computer where the DB2 administrator has read, write, and execute permission and extract the files. 2. Run the kd4MakeDB2db script while logged in as the database administrator. 3. Run the SOA Domain Management Server Configuration Utility as the user who installed IBM Tivoli Monitoring and select the option to use an existing database. See Creating the SOA Domain Management Server database on page 67 for more information about manually creating the SOA Domain Management Server database using the kd4MakeDB2db script and the permissions that are required. Authorization of database user specified using ConfigDMS The user must be an existing DB2 administrator user (for example, db2admin on Windows operating systems, or db2inst1 on Linux or AIX operating systems). This user is the same user as specified by <DB_USER>. On Linux or AIX operating systems, the DB2 profile must automatically be sourced when you login as this user. This user must already exist and is used to create the database and to access the database at runtime. This user is not used as the database schema name. The schema name is always SDMS. When creating the SOA Domain Management Server database in Microsoft SQL Server: Running ConfigDMS on Windows operating systems To create the SOA Domain Management Server database using Microsoft SQL Server, the Authentication mode for the SQL server must be configured for Mixed Mode (Windows Authentication and SQL Server Authentication). With this authentication mode, both Windows Authentication and Microsoft SQL Server Authentication are enabled. When using Microsoft SQL Server Authentication, a user logging in to Microsoft SQL Server must supply a username and a password that Microsoft SQL Server validates against a system table. Using this security model, login as a user that is a member of the SQL Server sysadmin role group to create the SOA Domain Management Server database. In addition, the user must have read, write, and modify permissions for these directories: v <ITM_Home>\CNPS directory and its subdirectories v <ITM_Home>\CNPSJ directory and its subdirectories v <ITM_Home>\logs directory Authorization of server login specified using ConfigDMS The server login user can be any existing or non-existing user, except for the reserved user, sa. If the server login user that you specify does not
87
already exist, it is created in the SQL Server registry. ConfigDMS assigns this user the db_owner role for the SOA Domain Management Server database. Using ConfigDMS after the SOA Domain Management Server database has been previously created: You or your database administrator might have already created the SOA Domain Management Server database using the procedures documented in Creating the SOA Domain Management Server database on page 67. If so, the user permissions needed to configure SOA Domain Management Server depend on the database application used to create the database: When the SOA Domain Management Server database was created in DB2: Running ConfigDMS on Windows operating systems Your user must have Windows administrative privileges and be the user who installed IBM Tivoli Monitoring. For example, the user should be included in the Administrators group. In addition, the user must have read, write, and modify permissions for these directories: v <ITM_Home>\CNPS directory and its subdirectories v <ITM_Home>\CNPSJ directory and its subdirectories v <ITM_Home>\logs directory Running ConfigDMS on Linux or AIX operating systems The user must be the user used to install IBM Tivoli Monitoring (root or db2inst1) and must have permission to reconfigure and run Tivoli Enterprise Portal Server, and must have read, write, and execute permissions for the following directories: v <ITM_Home>/<platform>/cq directory and its subdirectories v <ITM_Home>/<platform>/iw directory and its subdirectories v <ITM_Home>/config directory v <ITM_Home>\logs directory Authorization of database user specified using ConfigDMS The user must be either of the following types: v A DB2 administrator user (for example, db2admin on Windows operating systems, or db2inst1 on Linux or AIX operating systems) v A database user specific to the SOA Domain Management Server database that has at least the following authorizations: Connect to the database Create tables Perform select, insert, update, and delete operations on the tables in the database. This user must already exist, and is used to create the database and to access the database at runtime. This user is not used as the database schema name. The schema name is always SDMS. When the SOA Domain Management Server database was created in Microsoft SQL Server: Running ConfigDMS on Windows operating systems Your user must have Windows administrative privileges and be the user who installed IBM Tivoli Monitoring. For example, the user should be
88
Installation Guide
included in the Administrators group.In addition, the user must have read, write, and modify permissions for these directories: v <ITM_Home>\CNPS directory and its subdirectories v <ITM_Home>\CNPSJ directory and its subdirectories v <ITM_Home>\logs directory Authorization of server login specified using ConfigDMS The user must be the server login user specified when the kd4MakeMSSQLdb script was run on the database server.
Permissions needed when upgrading SOA Domain Management Server and optionally Tivoli Common Object Repository from ITCAM for SOA version 7.1 to version 7.1.1
When you upgrade SOA Domain Management Server and Tivoli Common Object Repository from ITCAM for SOA version 7.1 to version 7.1.1, you must have certain user permissions when running ConfigDMS, depending on whether the existing SOA Domain Management Server database is in DB2 or in Microsoft SQL Server. When the SOA Domain Management Server database is in DB2: When the SOA Domain Management Server database is in DB2, you need certain permissions when you run ConfigDMS to upgrade SOA Domain Management Server and optionally Tivoli Common Object Repository: Running ConfigDMS on Windows operating systems Your user must have Windows and DB2 administrative privileges and be the user who installed IBM Tivoli Monitoring. For example, the user should be included in both the Administrators and DB2ADMNS groups. In addition, the user must have read, write, and modify permissions for these directories: v <ITM_Home>\CNPS directory and its subdirectories v <ITM_Home>\CNPSJ directory and its subdirectories v <ITM_Home>\logs directory Running ConfigDMS on Linux or AIX operating systems The user must be the user used to install IBM Tivoli Monitoring (root or db2inst1) and must have permission to reconfigure and run Tivoli Enterprise Portal Server, and must have read, write, and execute permissions for the following directories: v <ITM_Home>/<platform>/cq directory and its subdirectories v <ITM_Home>/<platform>/iw directory and its subdirectories v <ITM_Home>/config directory v <ITM_Home>\logs directory In addition, if you are running ConfigDMS as the root user, your root user must also have the following capabilities: v The user must be able to source the DB2 instance profile. v The user must be authorized to issue the following command:
su - <DB_USER>
In this command, <DB_USER> refers to the database administrator user that was configured as the SOA Domain Management Server database user when SOA Domain Management Server was configured for ITCAM for SOA V7.1. The user specified by <DB_USER> must have read, write, and execute permissions for the <ITM_Home>/<platform>/cq/Products/ KD4/latest/bin directory.
89
When the SOA Domain Management Server database is in Microsoft SQL Server: When the SOA Domain Management Server database is in Microsoft SQL Server, you need certain permissions when you run ConfigDMS to upgrade SOA Domain Management Server and optionally Tivoli Common Object Repository: v You need to login as a user who is a member of the SQL Server sysadmin role group and is the user who installed IBM Tivoli Monitoring. v In addition, the user must have read, write, and modify permissions for these directories: <ITM_Home>\CNPS directory and its subdirectories <ITM_Home>\CNPSJ directory and its subdirectories <ITM_Home>\logs directory
Permissions needed when updating authentication for SOA Domain Management Server
When you use ConfigDMS to update the authentication for SOA Domain Management Server, you need certain permissions: Running ConfigDMS on Windows operating systems Your user must have Windows administrative privileges. For example, the user should be included in the Administrators group. In addition, the user must have read, write, and modify permissions for these directories: v <ITM_Home>\CNPS directory and its subdirectories v <ITM_Home>\CNPSJ directory and its subdirectories v <ITM_Home>\logs directory Running ConfigDMS on Linux or AIX operating systems The user must either be the user used to install IBM Tivoli Monitoring (root) or must have permission to reconfigure and run Tivoli Enterprise Portal Server, and must have read, write, and execute permissions for the following directories: v <ITM_Home>/<platform>/cq directory and its subdirectories v <ITM_Home>/<platform>/iw directory and its subdirectories v <ITM_Home>/config directory v <ITM_Home>\logs directory
Permissions needed when updating authentication for Tivoli Common Object Repository
When you use ConfigDMS to update the authentication for Tivoli Common Object Repository, you need certain permissions: Running ConfigDMS on Windows operating systems Your user must have Windows administrative privileges. For example, the user should be included in the Administrators group. In addition, the user must have read, write, and modify permissions for these directories: v <ITM_Home>\CNPS directory and its subdirectories v <ITM_Home>\CNPSJ directory and its subdirectories v <ITM_Home>\logs directory Running ConfigDMS on Linux or AIX operating systems The user must either be the user used to install IBM Tivoli Monitoring (root) or must have permission to reconfigure and run Tivoli Enterprise Portal Server, and must have read, write, and execute permissions for the following directories: v <ITM_Home>/<platform>/cq directory and its subdirectories
90
Installation Guide
v <ITM_Home>/<platform>/iw directory and its subdirectories v <ITM_Home>/config directory v <ITM_Home>\logs directory
Permissions needed when updating SOA Domain Management Server by applying a fix pack or interim fix
When updating SOA Domain Management Server by applying a fix pack or interim fix, see the documentation provided with the fix pack or interim fix for information about any special user permissions needed.
Permissions needed when updating Tivoli Common Object Repository when applying a fix pack or interim fix
When updating Tivoli Common Object Repository by applying a fix pack or interim fix, see the documentation provided with the fix pack or interim fix for information about any special user permissions needed.
Additional considerations
If you are using ConfigDMS to configure both SOA Domain Management Server and Tivoli Common Object Repository, you must be signed in as a user that has the permissions for configuring both components. For example, in the special case in which you configure topology support with SOA Domain Management Server in Microsoft SQL Server and Tivoli Common Object Repository on a local DB2 server, you must be signed in with a user name that has appropriate database administrator privileges for both Microsoft SQL Server and DB2, to configure both SOA Domain Management Server and Tivoli Common Object Repository in a single run of ConfigDMS. In addition, you must run ConfigDMS from a DB2 Command Line Processor window. If you do not have a single user with the appropriate permissions, you must sign in twice to run the ConfigDMS utility: v The first time, sign in with a user name that has permissions to run the ConfigDMS script to configure only SOA Domain Management Server. After this task completes successfully, you must re-configure Tivoli Enterprise Portal Server before proceeding. v Then sign in a second time with a user name that has permissions to run the ConfigDMS script to configure Tivoli Common Object Repository. After this task completes successfully, you must re-configure Tivoli Enterprise Portal Server and then start the portal server.
Tivoli Enterprise Portal Server on Windows

Complete the following steps on the local Windows computer system where Tivoli Enterprise Portal Server is installed. 1. Ensure that you are logged in with a user that has the appropriate permissions as described in Database and user permissions on page 81. 2. Depending on your intended task, open one of these command prompt windows: v Open a DB2 Command Line Processor window by selecting Start > Run and entering db2cmd if any of the following conditions are met: You are using the SOA Domain Management Server Configuration Utility to create a local SOA Domain Management Server or Tivoli Common Object Repository database in DB2. You might do this for one of the following reasons:
91
- You are configuring SOA Domain Management Server or Tivoli Common Object Repository for the first time. - You are upgrading from ITCAM for SOA version 6.1 to version 7.1.1, and are using DB2 for the SOA Domain Management Server database. You are using the SOA Domain Management Server Configuration Utility to upgrade from ITCAM for SOA version 7.1 to version 7.1.1 and SOA Domain Management Server is configured to use a local DB2 database. Combining configuration steps: In the special case where you want to configure SOA Domain Management Server to use Microsoft SQL Server and Tivoli Common Object Repository to use DB2 in a single run of the SOA Domain Management Server Configuration Utility, you must run the configuration utility from a DB2 Command Line Processor window. v Open a regular command prompt window by selecting Start > All Programs > Accessories > Command Prompt if any of the following conditions are met: You are using the SOA Domain Management Server Configuration Utility to create a local SOA Domain Management Server database in Microsoft SQL Server and are not using the utility to create a local Tivoli Common Object Repository database in DB2. You might do this for one of the following reasons: - You are configuring SOA Domain Management Server for the first time. - You are upgrading from ITCAM for SOA version 6.1 to version 7.1.1 and are using Microsoft SQL Server for the SOA Domain Management Server database. You are using the SOA Domain Management Server Configuration Utility to configure SOA Domain Management Server and optionally Tivoli Common Object Repository, and the databases have previously been created manually. You might do this for one of the following reasons: - You are configuring SOA Domain Management Server and optionally Tivoli Common Object Repository for the first time. - You are upgrading from ITCAM for SOA version 6.1 to version 7.1.1 and you have manually created the SOA Domain Management Server database. You are using the SOA Domain Management Server Configuration Utility to upgrade from ITCAM for SOA version 7.1 to version 7.1.1, and SOA Domain Management Server is using a Microsoft SQL Server database. You are only using the SOA Domain Management Server Configuration Utility to update the authentication parameters for the SOA Domain Management Server or Tivoli Common Object Repository database. 3. Depending on your intended task, you must run the SOA Domain Management Server Configuration Utility from one of two possible locations. v Navigate to the <ITM_Home> \CNPS\Products\KD4\latest\bin directory if any of the following conditions apply: You are initially running the SOA Domain Management Server Configuration Utility to configure SOA Domain Management Server or Tivoli Common Object Repository for the first time. You are running the SOA Domain Management Server Configuration Utility to upgrade from a previous configuration. v Navigate to the <ITM_Home> \CNPS\Products\KD4\bin directory if the following conditions apply:
92
Installation Guide
You have previously configured or upgraded SOA Domain Management Server and Tivoli Common Object Repository at the version 7.1.1 level. You are now running the SOA Domain Management Server Configuration Utility again to update the authentication to access SOA Domain Management Server or Tivoli Common Object Repository databases. 4. Run the ConfigDMS.bat script. This script provides several command options, described by the following syntax:
ConfigDMS [{console | silent [<dir_path>\]<silent_file>} debug [<dir_path>\]<debug_file>]
For example, to run the configuration utility using the InstallShield graphical user interface wizard, run the script with no options:
ConfigDMS
To run the configuration utility in console mode, specify the script with the console option:
ConfigDMS -console
These command options are described further in ConfigDMS command options on page 94
Logging information
Logging information is written to a log file in the <ITM_Home>/logs directory, named in this format: kd4_sdms_config<date_timestamp>.log. Scroll to the bottom of this log file for the most recent information. See the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide for assistance with problems you might encounter while configuring support for SOA Domain Management Server and Tivoli Common Object Repository. If errors are encountered during configuration, messages are displayed with information to assist you in determining the problem. See the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide for more information about typical errors you might encounter, and a more complete description of error messages and possible recovery options.
Tivoli Enterprise Portal Server on Linux or AIX

Complete the following steps on the local Linux or AIX computer system where Tivoli Enterprise Portal Server is installed. 1. Ensure that you are logged in with a user that has the appropriate permissions as described in Database and user permissions on page 81. 2. If you are running the SOA Domain Management Server Configuration Utility in graphical user interface mode on Linux or UNIX operating systems, verify that you can run X Windows-based applications to ensure that you have appropriate permissions. 3. Complete these steps to source the DB2 instance profile if one of the following conditions applies: v You are using the SOA Domain Management Server Configuration Utility to configure SOA Domain Management Server or Tivoli Common Object Repository for the first time and the utility will be used to create a local DB2 database. v You are using the SOA Domain Management Server Configuration Utility to upgrade from ITCAM for SOA V6.1 to 7.1.1 and the utility will be used to create a local DB2 database for SOA Domain Management Server.
93
v You are using the SOA Domain Management Server Configuration Utility to upgrade from ITCAM for SOA V7.1 to 7.1.1 (in which case SOA Domain Management Server is using a local DB2 database). a. Navigate to /home/<dbuser>/sqllib, where <dbuser> is the DB2 instance user name (for example, db2inst1). b. Run the following command:
. ./db2profile
Note: Be sure to leave a space between the first period and the ./db2profile command 4. Depending on your intended task, you must run the SOA Domain Management Server Configuration Utility from one of two possible locations. v Navigate to the <ITM_Home>/<platform>/cq/Products/KD4/latest/bin directory if either of the following conditions apply: You are running the SOA Domain Management Server Configuration Utility to configure SOA Domain Management Server or Tivoli Common Object Repository for the first time. You are running the SOA Domain Management Server Configuration Utility to upgrade from a previous configuration. v Navigate to the <ITM_Home>/<platform>/cq/Products/KD4/bin directory if both of the following conditions apply: You have previously configured or upgraded SOA Domain Management Server and Tivoli Common Object Repository at the version 7.1.1 level. You are now running the SOA Domain Management Server Configuration Utility again to update the authentication to access SOA Domain Management Server or Tivoli Common Object Repository databases. For information about resolving these directory path variables, see Resolving directory path variables on page xviii. 5. Run the ConfigDMS.sh script. This script provides several command options, described by the following syntax:
./ConfigDMS.sh [{console | silent [<dir_path>/]<silent_file>} debug [<dir_path>/]<debug_file>]
These command options are described further in ConfigDMS command options
Logging information
Logging information is written to a log file in the directory <ITM_Home>/logs, named in this format: kd4_sdms_config<date_timestamp>.log. Scroll to the bottom of this log file for the most recent information. See the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide for assistance with problems you might encounter while configuring support for Tivoli Common Object Repository and SOA Domain Management Server. If errors are encountered during configuration, messages are displayed with information to assist you in determining the problem. See the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide for more information about typical errors you might encounter, and a more complete description of error messages and possible recovery options.
ConfigDMS command options

Running the ConfigDMS script with no command options starts the SOA Domain Management Server Configuration Utility in the default graphical user interface mode. This configuration utility prompts you for the necessary parameters to create
94
Installation Guide
databases and configure the SOA Domain Management Server and optional Tivoli Common Object Repository support. See Running the SOA Domain Management Server Configuration Utility graphical user interface on page 96 for more information. These are the command options for the ConfigDMS script: console This option runs the SOA Domain Management Server Configuration Utility in command line mode, if you prefer to use that over the InstallShield graphical user interface. This option cannot be specified together with the silent option. See Running the SOA Domain Management Server Configuration Utility in console mode on page 111 for more information. Examples:
ConfigDMS -console ./ConfigDMS.sh -console
silent [<dir_path>/]<silent_file> This option runs the SOA Domain Management Server Configuration Utility in silent mode. The <silent_file> file is a simple properties file that you create, containing the necessary parameters to create databases and configure the SOA Domain Management Server and optional Tivoli Common Object Repository support. If this file is not stored in the same directory path where you run the ConfigDMS script (either <ITM_Home>\CNPS\Products\KD4\latest\bin or <ITM_Home>\CNPS\ Products\KD4\bin (for Windows, or the equivalent directory paths for Linux or AIX operating systems), specify the fully qualified directory path where this file is located. This option cannot be specified together with the console option. See Running the SOA Domain Management Server Configuration Utility in silent mode on page 112 for more information. Examples:
ConfigDMS -silent dmsconfig_silent.txt ConfigDMS -silent C:\Configurations\configdms.silent ./ConfigDMS.sh -silent config.properties
debug [<dir_path>/]<debug_file> This option can be specified alone, or after specifying either the console or silent options. The SOA Domain Management Server Configuration Utility is run in either graphical user interface mode, console mode, or silent mode, and log information is written to the <debug_file> file for later examination and diagnosis of problems by IBM Software Support. The debug log file is a plain text file stored in a specified directory path, or, if no directory path is specified, in the same directory where you run the ConfigDMS script (either <ITM_Home>\CNPS\Products\KD4\latest\bin or <ITM_Home>\CNPS\Products\KD4\bin (for Windows, or the equivalent directory paths for Linux or AIX operating systems). If you do not specify a file name for <debug_file>, the utility is not started, and you are presented with the syntax information as a reminder. Examples:
ConfigDMS -debug configdms_log.txt ./ConfigDMS.sh -console -debug debuglog ConfigDMS -silent C:\Properties\config.props -debug C:\KD4\logs\cnfgdms.log
95
Running the SOA Domain Management Server Configuration Utility graphical user interface
Running the ConfigDMS script without specifying either the console or silent options starts the SOA Domain Management Server Configuration Utility using the InstallShield wizard graphical user interface. After you select the preferred language, a welcome page is presented with some brief information about the SOA Domain Management Server Configuration Utility.
Figure 27. The SOA Domain Management Server Configuration Utility welcome screen
After you click Next, the SOA Domain Management Server Configuration Utility detects one of the following conditions: v SOA Domain Management Server or Tivoli Common Object Repository support from a previous version of ITCAM for SOA is already configured. In this case the utility prompts you for the necessary information to upgrade your configuration to the current version. See Upgrading a previous topology configuration on page 97 for the procedure. v ITCAM for SOA version 7.1.1 support for SOA Domain Management Server and Tivoli Common Object Repository are not yet configured. In this case the utility offers you choices to configure SOA Domain Management Server and, optionally, Tivoli Common Object Repository at the version 7.1.1 level. See Configuring topology support for the first time on page 98 for the procedure. v ITCAM for SOA version 7.1.1 support for the SOA Domain Management Server is configured (but not the optional support for Tivoli Common Object Repository). In this case the utility offers you one or more of the following configuration choices: If your SOA Domain Management Server database password has been changed recently, you can update the authentication in your current SOA Domain Management Server configuration. See Updating authentication for SOA Domain Management Server on page 109 for the procedure.
96
Installation Guide
You can update the existing configuration for SOA Domain Management Server, if an update is available. See Updating the existing SOA Domain Management Server configuration on page 111 for the procedure. You can configure the optional support for Tivoli Common Object Repository. See Configuring Tivoli Common Object Repository support on page 107 for the procedure. v ITCAM for SOA version 7.1.1 support for the SOA Domain Management Server and Tivoli Common Object Repository are both already configured. In this case the utility offers you several configuration choices: If your SOA Domain Management Server database password has been changed recently, you can update the authentication in your current SOA Domain Management Server configuration. See Updating authentication for SOA Domain Management Server on page 109 for the procedure. If your Tivoli Common Object Repository database password has been changed recently, you can update the authentication in your current Tivoli Common Object Repository configuration. See Updating authentication for Tivoli Common Object Repository on page 110 for the procedure. You can update the existing configuration for SOA Domain Management Server, if an update is available. See Updating the existing SOA Domain Management Server configuration on page 111 for the procedure. You can update the existing configuration for Tivoli Common Object Repository, if an update is available. See Updating the existing Tivoli Common Object Repository configuration on page 111 for the procedure. You can update the existing configuration for both SOA Domain Management Server and Tivoli Common Object Repository, if an update for both is available. The following sections describe how the SOA Domain Management Server Configuration Utility handles each of these conditions.
Upgrading a previous topology configuration

If you already have a configuration of SOA Domain Management Server and Tivoli Common Object Repository support from a previous version of ITCAM for SOA in your Tivoli Enterprise Portal Server environment, the SOA Domain Management Server Configuration Utility upgrades this support to ITCAM for SOA version 7.1.1. v If you are upgrading from ITCAM for SOA version 6.1 to version 7.1.1, you are prompted to configure the SOA Domain Management Server. See Configuring support for SOA Domain Management Server on page 99 for the procedure. v If you are upgrading from ITCAM for SOA version 7.1 to version 7.1.1 and the SOA Domain Management Server database is in DB2, the utility does not prompt you for upgrade information. v If you are upgrading from ITCAM for SOA version 7.1 to version 7.1.1 and the SOA Domain Management Server database is in Microsoft SQL Server, the utility prompts you for different information. Follow the on screen prompts in the utility to complete the upgrade. Note that if you are also upgrading Tivoli Common Object Repository, the process might take some time to complete as the database is upgraded, depending on its size. It can take 15 minutes or longer, so be patient and do not stop the SOA Domain Management Server Configuration Utility in the middle of an upgrade. First, the configuration utility prompts you to upgrade support for the SOA Domain Management Server to the current version. The configuration utility then attempts to
97
upgrade the Tivoli Common Object Repository support to the current version. If there are errors, you are notified and the only option is to exit the utility. If you experience errors while upgrading your SOA Domain Management Server or Tivoli Common Object Repository support, consult with your local database administrator for assistance or contact IBM Software Support. You are notified when the upgrade completes successfully, and can exit the utility. Properties files renamed: The collation.properties and bulkload.properties file in <ITM_Home>\CNPS\Products\KD4\tcore\etc on Windows and <ITM_Home>/<platform>/cq/Products/KD4/tcore/etc on Linux and AIX are renamed to bulkload.properties.backup and collation.properties.backup1. If you modified any properties in a previous version of these files, you must manually merge the changes into ITCAM for SOA version 7.1.1 files after migration is complete. Re-configure and restart TEPS: After completing this upgrade you must re-configure and restart Tivoli Enterprise Portal Server for the upgrade to take effect. See Re-configuring the Tivoli Enterprise Portal Server on page 122 for more information.
Configuring topology support for the first time

If you do not have a previous configuration of SOA Domain Management Server version 7.1.1 topology support (with or without the optional Tivoli Common Object Repository support) in your Tivoli Enterprise Portal Server environment, then the SOA Domain Management Server Configuration Utility configures this support for you. You are asked to select one of the following options: v Configure support for SOA Domain Management Server only. v Configure support for both SOA Domain Management Server and Tivoli Common Object Repository.
98
Installation Guide
Figure 28. Configuring topology support for the first time
See Configuring support for SOA Domain Management Server and Configuring Tivoli Common Object Repository support on page 107 for the procedures.
Configuring support for SOA Domain Management Server

You are prompted to provide the following parameters for configuring the SOA Domain Management Server: v You are asked whether to create the SOA Domain Management Server database locally, or to use an existing (local or remote) database that you have previously created. See Creating the SOA Domain Management Server database on page 67 for information on using script files to manually create the local or remote SOA Domain Management Server database before running ConfigDMS.
99
Figure 29. Specifying to create the SOA Domain Management Server database or use an existing database
If you prefer to use an existing local or remote database, select the Use an existing database radio button and type the hostname of the computer where the SOA Domain Management Server database is located. You can also specify localhost to use an existing local database. v The database type, DB2 or one of the two supported versions of Microsoft SQL Server. This parameter is automatically obtained from the Tivoli Enterprise Portal Server configuration, and the default value for this parameter is set to the current database type.
100
Installation Guide
Figure 30. Configuring the SOA Domain Management Server
Depending on the database type selected, you are also prompted to accept the default database port number, or consult your database administrator to specify a different port number. For DB2, the default port number is 50000. For either Microsoft SQL Server 2000 or Microsoft SQL Server 2005, the default port number is 1433. v For a DB2 database: The fully qualified directory path to the JDBC driver class files. The utility searches for the driver files based on where your database application is installed, and presents these as defaults. You can accept these defaults or specify others as needed. These are the specific files that the utility searches for: - On Windows operating systems:
C:\Program Files\IBM\SQLLIB\java\db2jcc.jar C:\Program Files\IBM\SQLLIB\java\db2jcc_license_cu.jar
101
Figure 31. Specifying the JDBC drivers
- On AIX and Linux operating systems:

<Instance_Owner_Home_Directory>/sqllib/java/db2jcc.jar <Instance_Owner_Home_Directory>/sqllib/java/db2jcc_license_cu.jar
The <Instance_Owner_Home_Directory> path is typically/home/db2inst1 and <Instance_Owner_Home_Directory>/sqllib/java is a symbolic link to the Java directory for your DB2 installation (for example, /usr/opt/db2_08_01/java when DB2 8.1 is installed). These JDBC drivers, obtained from the database server, are needed on the computer where Tivoli Enterprise Portal Server is installed (where SOA Domain Management Server support is being configured). The name of the SOA Domain Management Server database. The default name is KD4SDMS and has a limit of eight characters. Existing database name: If you had specified to create the SOA Domain Management Server database locally and this database name already exists on the local system, it is dropped and recreated. If you want the configuration utility to create this database for you and you do not want to drop an existing database, specify a different name.
102
Installation Guide
Figure 32. Specifying the SOA Domain Management Server database name and database user
The database administrative user name and password (for example, the default user name and password, db2admin). This user name must already exist, and the configuration utility validates the specified password before continuing. See Database and user permissions on page 81 for more information about authorization required for this database user. v For a Microsoft SQL Server database on supported Windows operating systems: The fully qualified directory path to the JDBC driver class files. The utility searches for the driver files based on where your database application is installed, and presents these as defaults. You can accept these defaults or specify others as needed. The JDBC drivers for Microsoft SQL Server are always installed to the same location:
C:\Program Files\Microsoft SQL Server 2005 JDBC Driver \sqljdbc_1.2\enu\sqljdbc.jar
103
Figure 33. Specifying the Microsoft SQL Server JDBC drivers
Only the Microsoft JDBC driver is supported. The Microsoft SQL Server 2005 JDBC 1.2 driver jar file must be used for both Microsoft SQL Server 2000 and Microsoft SQL Server 2005, and is available as a free download from the Microsoft Download Center:
http://www.microsoft.com/downloads
The self-extracting file, sqljdbc_1.2.2828.100_enu.exe includes the file sqljdbc.jar containing the Microsoft SQL Server 2005 JDBC Driver. This driver, at version 1.2, is the minimum supported version. The SOA Domain Management Server Configuration Utility verifies that the minimum supported version of the JDBC driver is used. The name of the SOA Domain Management Server database to be created. The default name is KD4SDMS and has a limit of 128 characters. New database server level login: The configuration utility displays a message noting that, with Microsoft SQL Server, a new database server level login is created if one does not already exist. Existing database name: If you had specified to create the SOA Domain Management Server database locally and this database name already exists on the local system, it is dropped and recreated. If you want the configuration utility to create this database for you and you do not want to drop an existing database, specify a different name. The Server login name and password. You can specify any login name except the reserved name, sa. If the Server login name already exists, the configuration utility validates the password before continuing, but if the Server login name does not already exist, the configuration utility creates a server level login for the specified name in the SQL Server registry and assigns it the password that you specify. If you ran the kd4MakeMSSQLdb script to manually create the database, then specify the server login name and password that were passed to that script.
104
Installation Guide
Figure 34. Specifying the SOA Domain Management Server database name and server login access
The Microsoft SQL Server instance name. To use a named instance instead of the default instance, select the check box and type the preferred instance name in the provided field. The full instance name consists of the hostname and instance name separated by a backslash character (\), similar to the example shown in Figure 35 on page 106. The hostname should match the short hostname (that is, the portion of the hostname without the domain designation) of your Microsoft SQL Server.
105
Figure 35. Specifying the Microsoft SQL Server instance name other than the default value
The SOA Domain Management Server Configuration Utility validates the specified user name and password and attempts to configure the SOA Domain Management Server. If there are errors, you are notified and can go back and correct any specified parameters to try again, or you can exit the configuration utility. When the configuration completes successfully, you are notified. At this point if you had selected to configure only the SOA Domain Management Server, you can exit the configuration utility. If you had selected to configure both SOA Domain Management Server and Tivoli Common Object Repository, you are prompted to click Next to continue that configuration. See Configuring Tivoli Common Object Repository support on page 107. If you are upgrading from ITCAM for SOA version 6.1 to version 7.1.1, the configuration utility will start upgrading the Tivoli Common Object Repository database. This will take a significant time to complete, so be patient and wait for it to complete successfully. Re-configure and restart Tivoli Enterprise Portal Server: After you exit the configuration utility, you must re-configure and restart Tivoli Enterprise Portal Server for the configuration to take effect. See Re-configuring the Tivoli Enterprise Portal Server on page 122 for the procedure. Re-configuring Tivoli Enterprise Portal Server might take 5-10 minutes to complete. During this time the Manage Tivoli Enterprise Monitoring Services utility might appear to be inoperable. Please be patient and wait for the reconfiguration to complete. Additional verification steps: Note that Part 3, Completing your installation, on page 241 of this guide includes a number of additional steps that are required to verify the installation and to enable access to the ITCAM for SOA Navigator in the Tivoli Enterprise Portal that is used to display some of the topology workspaces. Be sure to complete all of the installation and verification steps documented in this guide before using the product.
106
Installation Guide
At some later time if you want to configure the Tivoli Common Object Repository support, run the SOA Domain Management Server Configuration Utility again, and follow the procedures in Configuring Tivoli Common Object Repository support.
Configuring Tivoli Common Object Repository support

If you selected to configure the optional support for Tivoli Common Object Repository, the configuration utility prompts you to provide the following parameters: v You are asked whether to create the Tivoli Common Object Repository database locally, or to use an existing (local or remote) database that you have previously created, as shown in Figure 36. See Creating the Tivoli Common Object Repository database on page 74 for information on using script files to manually create the local or remote Tivoli Common Object Repository database before running ConfigDMS. v The database hostname. If you prefer to use an existing local or remote database, select the Use already existing database radio button and type the hostname of the computer where the Tivoli Common Object Repository database is located. The default is localhost to use an existing local database. If you are configuring a remote Tivoli Common Object Repository database that you previously created (for example, using the make_db2_db script for a DB2 database), specify the fully qualified hostname for the computer where the remote database server is located. v The database port number. The default DB2 value of 50000 is provided in the field, and is used if you leave this field empty. Accept the default or type over it to specify a different port number.
Figure 36. Specifying to create the Tivoli Common Object Repository database new or use an existing database
v The Tivoli Common Object Repository database name. The default value is KD4TCORE and has a limit of eight characters. Existing database name: If you had specified to create the Tivoli Common Object Repository database locally and this database name already exists on the
107
local system, it is dropped and recreated. If you want the configuration utility to create this database for you and you do not want to drop an existing database, specify a different name. v The database administrative user name and password (for example, the default user name and password, db2admin). This user name must already exist. See Database and user permissions on page 81 for more information about the authorization required for this database user.
Figure 37. Specifying the Tivoli Common Object Repository database name and database user information
If the Tivoli Common Object Repository database hostname is on a remote DB2 server, the configuration utility asks you to confirm that you have already run the make_db2_db script to create the remote database before starting this configuration. If not, you should cancel this configuration and see Creating the Tivoli Common Object Repository database on page 74 for instructions on creating the Tivoli Common Object Repository database on a remote DB2 server. The configuration utility validates the parameters provided and attempts to configure the Tivoli Common Object Repository database on the local or remote DB2 server. If there are errors, you are notified and can go back and correct any specified parameters to try again. Note: The configuration process might take 5-15 minutes to complete. Wait for the configuration to complete. Re-configure and restart Tivoli Enterprise Portal Server: At this point click Finish to exit the utility. You must re-configure and restart Tivoli Enterprise Portal Server for the configuration to take effect. See Re-configuring the Tivoli Enterprise Portal Server on page 122 for the procedure.
108
Installation Guide
Figure 38. You must re-configure and restart Tivoli Enterprise Portal Server
Re-configuring Tivoli Enterprise Portal Server might take 5-10 minutes to complete. During this time the Manage Tivoli Enterprise Monitoring Services utility might appear to be inoperable. Please be patient and wait for the reconfiguration to complete. Additional verification steps: Note that Part 3, Completing your installation, on page 241 of this guide includes a number of additional steps that are required to verify the installation and to enable access to the ITCAM for SOA Navigator in the Tivoli Enterprise Portal that is used to display some of the topology workspaces. Be sure to complete all of the installation and verification steps documented in this guide before using the product. After re-configuring and restarting Tivoli Enterprise Portal Server you can run the SOA Domain Management Server Configuration Utility again to continue with further configuration as needed.
Updating authentication for SOA Domain Management Server

You can update the SOA Domain Management Server authentication if the DB2 or Microsoft SQL Server password is changed in your database application. Note that this action does not change the password, it only updates the SOA Domain Management Server configuration with the new password information. You must still use the database application to actually change and manage your database user passwords. You must restart Tivoli Enterprise Portal Server after updating the password information in the configuration. To update the SOA Domain Management Server authentication, complete these steps: 1. Ensure that Tivoli Enterprise Portal Server is started to perform this procedure. 2. Open a command prompt window. 3. Depending on your operating system, run the SOA Domain Management Server Configuration Utility from one of these directories:
109
v For Windows:
<ITM_Home>/CNPS/Products/KD4/bin
v For Linux or AIX:

<ITM_Home>/<platform>/cq/Products/KD4/bin
4. Select the radio button to Update SOA Domain Management Server Authentication. 5. Specify the new value in the field provided. The configuration utility verifies the new password by connecting to the database, and you are notified of any errors and given the opportunity to return to the previous configuration utility page and correct your input before trying again. 6. Exit the utility. 7. Restart Tivoli Enterprise Portal Server: You do not need to re-configure Tivoli Enterprise Portal Server after updating the authentication, but you do need to restart the Tivoli Enterprise Portal Server for the authentication update to take effect.
Updating authentication for Tivoli Common Object Repository

You can update the Tivoli Common Object Repository authentication, if the DB2 password has been changed in your database application. Note that this action does not change the password, it only updates the Tivoli Common Object Repository configuration with the new password information. You must still use the database application to actually change and manage your database user passwords. You must restart Tivoli Enterprise Portal Server after the updating the password information in the configuration. To update the Tivoli Common Object Repository authentication, complete these steps: 1. Ensure that Tivoli Enterprise Portal Server is started to perform this procedure. 2. Open a command prompt window. 3. Depending on your operating system, run the SOA Domain Management Server Configuration Utility from one of these directories: v For Windows:
<ITM_Home>/CNPS/Products/KD4/bin
v For Linux or AIX:

<ITM_Home>/<platform>/cq/Products/KD4/bin
4. Select the radio button to Update Tivoli Common Object Repository Authentication. 5. Specify the new value in the field provided. The configuration utility verifies the new password by connecting to the database, and you are notified of any errors and given the opportunity to return to the previous configuration utility page and correct your input before trying again. 6. Exit the utility. 7. Restart Tivoli Enterprise Portal Server: You do not need to re-configure Tivoli Enterprise Portal Server after updating the authentication, but you do need to restart the Tivoli Enterprise Portal Server for the authentication update to take effect.
110
Installation Guide
Updating the existing SOA Domain Management Server configuration

You can choose to update the SOA Domain Management Server configuration. This option is only presented if an update is available. Typically this update is provided to you through a fix pack release. Obtain the fix pack and refer to the instructions in the accompanying ReadMe file to update your configuration. Re-configure and restart Tivoli Enterprise Portal Server: You must re-configure and restart Tivoli Enterprise Portal Server for the configuration update to take effect. See Re-configuring the Tivoli Enterprise Portal Server on page 122 for the procedure.
Updating the existing Tivoli Common Object Repository configuration

You can choose to update the Tivoli Common Object Repository configuration. This option is only presented if an update is available. Typically this update is provided to you through a fix pack release. Obtain the fix pack and refer to the instructions in the accompanying ReadMe file to update your configuration. Re-configure and restart Tivoli Enterprise Portal Server: You must re-configure and restart Tivoli Enterprise Portal Server for the configuration update to take effect. See Re-configuring the Tivoli Enterprise Portal Server on page 122 for the procedure.
Running the SOA Domain Management Server Configuration Utility in console mode
Running the ConfigDMS script with the console option starts the SOA Domain Management Server Configuration Utility in the command line processor window, if you prefer to use that over the InstallShield graphical user interface. You are prompted to select a language, and then a welcome response is displayed in the command line processor window, and you are prompted to continue by typing a numerical response: v Type 1 to continue. v Type 3 to cancel the wizard. v Type 5 to display the response message and your choices again. Throughout the use of the wizard in console mode, you must respond by typing one of several valid responses. The wizard presents the same basic selection options as described in Running the SOA Domain Management Server Configuration Utility graphical user interface on page 96. Note: The ConfigDMS script might take 5-15 minutes to complete configuration of Tivoli Common Object Repository. Re-configuring and restarting Tivoli Enterprise Portal Server: After exiting the utility, if you only updated authentication, you only need to restart Tivoli Enterprise Portal Server for the update to take effect. If you configured or upgraded support for SOA Domain Management Server or Tivoli Common Object Repository, you must re-configure and restart Tivoli Enterprise Portal Server for the configuration to take effect. See Re-configuring the Tivoli Enterprise Portal Server on page 122 for the procedure.
111
Changing the character set code page

In some situations you might find that some characters on the SOA Domain Management Server Configuration Utility pages are not displayed correctly, possibly substituted with question mark (?) or other unexpected characters. This might occur if, for example, you are running on a Windows operating system in Japanese and you choose to run the SOA Domain Management Server Configuration Utility in German. To resolve this problem in console mode, you can change the Microsoft Windows character set code page for the current command prompt, using the CHCP command before running the SOA Domain Management Server Configuration Utility: v For Italian, French, Spanish, and German languages, run this command:
chcp 1252
v For Brazilian Portuguese, run this command:

chcp 850
After running the CHCP command, run the SOA Domain Management Server Configuration Utility again in console mode and select the desired language. If the problem persists, you might need to change the font that is displayed by the console.
Running the SOA Domain Management Server Configuration Utility in silent mode
Running the ConfigDMS script with thesilent [<dir_path>/]<silent_file> option starts the SOA Domain Management Server Configuration Utility in silent mode, using properties defined in the <silent_file> properties file instead of interacting with you in the graphical user interface or in console mode. Note that you cannot use the silent mode and console mode together. When you run the SOA Domain Management Server Configuration Utility in silent mode, the configuration parameters are read from a simple text properties file, <silent_file>, that you create in advance. A typical properties file might look similar to the following example:
# Sample silent configuration file # - silent file to deploy SDMS and TCORE # File version - make sure that you are # using proper version of silent file. version=7.11.00.00 config_sdms=yes config_tcore=no update_sdms_auth=no update_tcore_auth=no update_sdms=no update_tcore=no upgrade=no # SDMS section # Supported values on Windows are "db2", "mssql2000" and "mssql2005" sdms_db_type=db2 # Use default port - uncomment the property to set to a different value #sdms_db_port= # Sample JDBC path when SDMS is configured to use DB2 sdms_jdbc_path=C\:\\Program Files\\IBM\\SQLLIB\\java\\db2jcc.jar; C\:\\Program Files\\IBM\\SQLLIB\\java\\db2jcc_license_cu.jar
112
Installation Guide
# Sample JDBC path when SDMS is configured to use MS SQL 2000 # or MS SQL 2005 # sdms_jdbc_path=C\:\\Program Files\\Microsoft SQL Server 2005 JDBC Driver \\sqljdbc_1.2\\enu\\sqljdbc.jar # Supported values are: # 'yes' if SDMS database needs to be created locally # 'no' if SDMS is configured to use existing database sdms_db_create_locally=yes sdms_db_name=KD4SDMS # IMPORTANT: For MS SQL database the user ID sa is a reserved name that # cannot be used for logging in to the database server. sdms_db_user=sdms sdms_db_password=secret1 # Uncomment this property when SDMS is configured to use existing database # on host different than 'localhost' # sdms_db_host=localhost # # # # Uncomment this property when SDMS is configured to MS SQL 2000 or MS SQL 2005 and an instance other than default should be used. The instance name should be in the form hostname\instance_name. sdms_mssql_instance=hostname\\sample_instance
# TCORE section # Supported values are: # 'yes' if TCORE database need to be created locally # 'no' if TCORE is configured to use existing database tcore_db_create_locally=yes # Uncomment this property when TCORE is configured to use existing database # on host different than 'localhost' # tcore_db_host=localhost # Use default port - uncomment the property to set to a different value # tcore_db_port= tcore_db_name=KD4TCORE tcore_db_user=tcore tcore_db_password=secret1
When you create your silent response properties file, keep these considerations in mind: v A line in the file starting with the # character is treated as a comment, and is not processed. If the # character is used elsewhere in the line, it is not considered to be the start of a comment. This means that you can use the # character in passwords or for other uses. v The properties file is coded using the ISO 8859-1 character set. v The properties file can include only one version property. For this release the only valid value of this property is the predefined value 07.11.00.00. v Each property is described on a separate line, in the following format: <property> = <value>. <property> This is the name of property. The list of valid properties that you can configure is shown in Table 7 on page 114. <value> This is the value of the property. Default values for some properties are already provided. You can erase default values to leave property values blank, or empty. Note that an empty value is treated as if the property is
113
not specified, as opposed to using the default value. If you want to use default values, you can simply comment out the property in the file. v Passwords are in plain text. v Properties and their values are case sensitive. v Sample properties files (sample_silent_unix.cfg and sample_silent_win.cfg) are packaged with the SOA Domain Management Server Configuration Utility. Depending on your operating system, these files are available in one of these directories, where <ITM_Home> is the location where IBM Tivoli Monitoring is installed: For Windows:
<ITM_Home>/CNPS/Products/KD4/latest/bin
For Linux or AIX:

<ITM_Home>/<platform>/cq/Products/KD4/latest/bin Table 7. Available properties for running the SOA Domain Management Server Configuration Utility in silent mode Specify if upgrading: SDMS and TCORE 6.1 to SDMS and TCORE 7.1.1 SDMS and TCORE 7.1 to SDMS and TCORE 7.1.1
Property version
Possible Required (Yes/No) values Yes
SDMS 7.1 to SDMS 7.1.1
Comment This is the version number of the properties file, and must be set to the value of 7.11.00.00.
config_sdms
No
Yes or No
This property specifies whether or not to configure SOA Domain Management Server. If this property is not specified, the default value of No is assumed. This property specifies whether or not to configure the Tivoli Common Object Repository. If this property is not specified, the default value of No is assumed
config_tcore
No
Yes or No
114
Installation Guide
Table 7. Available properties for running the SOA Domain Management Server Configuration Utility in silent mode (continued) Specify if upgrading: SDMS and TCORE 6.1 to SDMS and TCORE 7.1.1 SDMS and TCORE 7.1 to SDMS and TCORE 7.1.1
Property update_sdms
Possible Required (Yes/No) values No Yes or No
Comment This property specifies whether or not to update the configuration of SOA Domain Management Server to the latest version when a fix pack or interim fix is installed. If this property is not specified, the default value of No is assumed. This property specifies whether or not to update the configuration of Tivoli Common Object Repository to the latest version when a fix pack or interim fix is installed. If this property is not specified, the default value of No is assumed. This property specifies whether or not to update the authentication for SOA Domain Management Server by changing the database password. If this property is not specified, the default value of No is assumed This property specifies whether or not to update the authentication for Tivoli Common Object Repository by changing the database password. If this property is not specified, the default value of No is assumed
update_tcore
No
Yes or No
update_sdms_auth
No
Yes or No
update_tcore_auth
No
Yes or No
115
Table 7. Available properties for running the SOA Domain Management Server Configuration Utility in silent mode (continued) Specify if upgrading: SDMS and TCORE 6.1 to SDMS and TCORE 7.1.1 X SDMS and TCORE 7.1 to SDMS and TCORE 7.1.1 X
Property upgrade
Possible Required (Yes/No) values No Yes or No
SDMS 7.1 to SDMS 7.1.1 X
Comment This property specifies whether or not to upgrade a previous configuration of SOA Domain Management Server and Tivoli Common Object Repository to version 7.1.1, depending on already configured components. If this property is not specified, the default value of No is assumed.
sdms_db_type
No
X db2 or mssql2000 or mssql2005
This property specifies the type of database server being used for the SOA Domain Management Server database. If this property is not specified, the value is obtained from the Tivoli Enterprise Portal Server configuration. Note that the Microsoft SQL Server database type is supported only on Windows operating systems. X (only if using MS SQL Server data base) X (only if using MS SQL Server database) This property specifies the port number for the DB2 or Microsoft SQL Server database server where the SOA Domain Management Server database is created. If this property is not specified, the default value of 50000 is used for DB2, or 1433 for Microsoft SQL Server 2000 or Microsoft SQL Server 2005.
sdms_db_port
Yes, when upgrading from SOA Domain Management Server version 7.1 to version 7.1.1 when SOA Domain Management Server is configured to use Microsoft SQL Server.
116
Installation Guide
Table 7. Available properties for running the SOA Domain Management Server Configuration Utility in silent mode (continued) Specify if upgrading: SDMS and TCORE 6.1 to SDMS and TCORE 7.1.1 X SDMS and TCORE 7.1 to SDMS and TCORE 7.1.1 X (only if using a MS SQL Server 2000 database)
Property sdms_jdbc_path
Possible Required (Yes/No) values Yes, in these cases: v the config_sdms property has the value of Yes v the upgrade property has the value of Yes and you are upgrading from ITCAM for SOA version 6.1 to version 7.1.1 v the upgrade property has the value of Yes and you are upgrading from ITCAM for SOA version 7.1 to version 7.1.1, and SDMS is configured to use Microsoft SQL Server 2000. In this case you must set the path to the location of the Microsoft SQL Server 2005 JDBC driver JAR file.
SDMS 7.1 to SDMS 7.1.1 X (only if using a MS SQL Server 2000 data base)
Comment This property specifies the fully qualified directory paths where the JDBC driver class files for the SOA Domain Management Server database being created are located. To include more than one directory path and JAR file, separate them in the list with a semicolon. See Configuring support for SOA Domain Management Server on page 99 for the list of JDBC driver class files required for DB2 or Microsoft SQL Server.
sdms_db_create_locally Yes
Yes or No
This property specifies whether the configuration utility should create the SOA Domain Management Server database locally or use an existing (local or remote) SOA Domain Management Server database.
117
Table 7. Available properties for running the SOA Domain Management Server Configuration Utility in silent mode (continued) Specify if upgrading: SDMS and TCORE 6.1 to SDMS and TCORE 7.1.1 X SDMS and TCORE 7.1 to SDMS and TCORE 7.1.1
Property sdms_db_name
Possible Required (Yes/No) values No
Comment This property specifies the name of the SOA Domain Management Server database being created. For DB2, the name can be a maximum of 8 characters. For Microsoft SQL Server, the name can be up to 128 characters. If this property is not specified, the default value of KD4SDMS is assumed. Note: If this database already exists, it is dropped and recreated. If you do not want to drop an existing database, specify a different name. This property specifies the DB2 administrative database user name or the Microsoft SQL Server login name that is authorized to access the SOA Domain Management Server database. For Microsoft SQL Server, the reserved user name of sa is not valid. See Database and user permissions on page 81 for more information about authorization required for this user.
sdms_db_user
Yes, in these cases: v the config_sdms property has the value of Yes v the upgrade property has the value of Yes and you are upgrading from ITCAM for SOA version 6.1 to version 7.1.1
118
Installation Guide
Property sdms_db_password
Possible Required (Yes/No) values Yes, in these cases: v the config_sdms property has the value of Yes v the update_sdms_ auth property has the value of Yes v the upgrade property has the value of Yes and you are upgrading from ITCAM for SOA version 6.1 to version 7.1.1.
Comment This property specifies the database password associated with the user name specified in the sdms_db_user property.
sdms_db_host
Yes, if your SOA Domain Management Server database is on a computer other than where Tivoli Enterprise Portal Server is installed.
X Fully qualified host name or localhost
This property specifies the hostname for the database server computer where the SOA Domain Management Server database is located. If your database is located on a computer other than where Tivoli Enterprise Portal Server is installed, specify the fully qualified remote hostname. If this property is not specified, the default value of localhost is used.
119
Property sdms_mssql_instance
Comment This property can be used if the value of the sdms_db_type property is mssql2000 or mssql2005, and specifies a named instance to be used instead of the default instance. Specify the full instance name, separated from the host name with two backslash characters (\\) This property specifies whether the configuration utility should create the Tivoli Common Object Repository database locally or use an existing (local or remote) Tivoli Common Object Repository database. This property specifies the hostname for the database server computer where the Tivoli Common Object Repository database is located. If your database is located on a computer other than where Tivoli Enterprise Portal Server is installed, specify the fully qualified remote hostname. If this property is not specified, the default value of localhost is used.
tcore_db_create_locally
Yes
Yes or No
tcore_db_host
Yes, if your Tivoli Common Object Repository database is on a computer other than where Tivoli Enterprise Portal Server is installed.
Fully qualified host name or localhost
120
Installation Guide
Table 7. Available properties for running the SOA Domain Management Server Configuration Utility in silent mode (continued) Specify if upgrading: SDMS and TCORE 6.1 to SDMS and TCORE 7.1.1 SDMS and TCORE 7.1 to SDMS and TCORE 7.1.1
Property tcore_db_port
Comment This property specifies the DB2 port number for the Tivoli Common Object Repository database. If this property is not specified, the default value of 50000 is assumed. This property specifies the name of the Tivoli Common Object Repository database. If this property is not specified, the default value of KD4TCORE is assumed. The name can be a maximum of 8 characters. Note: If you specified to create the database locally and this database already exists, it is dropped and recreated. If you do not want to drop an existing database, specify a different name. This property specifies the administrative database user name that is authorized to create and access the Tivoli Common Object Repository database.See Database and user permissions on page 81 for more information about the authorization required for this user. This property specifies the database password associated with the user name specified in the tcore_db_user property.
tcore_db_name
No
tcore_db_user
Yes, if config_tcore has the value of Yes
tcore_db_password
Yes, if config_tcore or update_tcore_ auth has the value of Yes
121
Combining silent operations

If you create a silent response file to contain more than one operation (for example, configure Tivoli Common Object Repository and update SOA Domain Management Server), the operations are always performed in the following sequence: 1. Upgrade (when upgrading from ITCAM for SOA version 6.1 to version 7.1.1, SOA Domain Management Server is also configured.) 2. Configure SOA Domain Management Server 3. Configure Tivoli Common Object Repository 4. Update SOA Domain Management Server authentication credentials 5. Update Tivoli Common Object Repository authentication credentials Some operations are mutually exclusive, and cannot be defined in the same silent response file. These operations can be performed using the same silent response file: v config_sdms and config_tcore v update_sdms and config_tcore v update_sdms and update_tcore v update_sdms_auth and update_tcore_auth
Silent mode errors and messages

The SOA Domain Management Server Configuration Utility validates the operations and their values in the silent response file and displays a message when required values are missing or when a property is assigned a value that is not valid. The SOA Domain Management Server Configuration Utility displays messages describing the operations that are being performed by the utility and results of those operations (success or failure). When an error occurs, the error code and the error message are displayed describing the cause of the failure, if possible. If the silent response file contains several operations that can be performed from the same file, the first error that occurs stops the SOA Domain Management Server Configuration Utility. For example, if you are configuring both SOA Domain Management Server and Tivoli Common Object Repository and an error occurs during the configuration of SOA Domain Management Server, the SOA Domain Management Server Configuration Utility does not start the configuration of Tivoli Common Object Repository. After the configuration or upgrade of SOA Domain Management Server or Tivoli Common Object Repository completes, you must re-configure and restart Tivoli Enterprise Portal Server. Note that this reconfiguration can take some time to complete. Be sure to wait for completion before attempting to run the SOA Domain Management Server Configuration Utility again. If you are only updating authentication credentials, you only need to restart Tivoli Enterprise Portal Server.
Re-configuring the Tivoli Enterprise Portal Server

After the SOA Domain Management Server Configuration Utility completes the tasks of upgrading, configuring, or updating SOA Domain Management Server or Tivoli Common Object Repository, re-configure Tivoli Enterprise Portal Server.
122
Installation Guide
If you are only updating the authentication credentials, you do not need to re-configure Tivoli Enterprise Portal Server, but you do have to restart Tivoli Enterprise Portal Server for the changes to take effect. To reconfigure Tivoli Enterprise Portal Server, complete the following steps: v For Windows operating systems: 1. Open the Manage Tivoli Enterprise Monitoring Services console. 2. Right-click the Tivoli Enterprise Portal Server component and select Re-configure from the context menu. v For Linux and AIX operating systems, run this command:
<ITM_Home>/bin/itmcmd config -A cq
As you re-configure the Tivoli Enterprise Portal Server, be aware of the following conditions: v You do not need to re-configure any of the Tivoli Enterprise Portal Server parameters, so accept the current values that are displayed in the configuration steps. v You do not need to re-configure the warehouse connection information, so when you are prompted for that option, respond with No. v The first time that you configure SOA Domain Management Server and Tivoli Common Object Repository, re-configuring Tivoli Enterprise Portal Server takes at least 5-15 minutes to complete, and during this time the Manage Tivoli Enterprise Monitoring Services console might appear to be inoperable. Please be patient and wait for the process to complete. v After the re-configure process completes, restart the Tivoli Enterprise Portal Server.
123
124
Installation Guide
Part 2. Configuring for data collection

After you run the installation program to install application support for the monitoring server, portal server, and desktop client, and after you install and configure the monitoring agent on the systems where services are to be monitored, you must enable the various supported runtime environments for data collection. This part of the IBM Tivoli Composite Application Manager for SOA Installation Guide describes the procedures for enabling and disabling data collection for the various runtime environments supported with this version. Refer to these chapters for details: v Chapter 5, Overview, on page 127 v Chapter 6, Configuring data collection: WebSphere Application Server, on page 149 v Chapter 7, Configuring data collection: Microsoft .NET, on page 159 v Chapter 8, Configuring data collection: BEA WebLogic Server, on page 161 v Chapter 9, Configuring data collection: JBoss, on page 171 v Chapter 10, Configuring data collection: CICS Transaction Server, on page 175 v Chapter 11, Configuring data collection: SAP NetWeaver, on page 177 v Chapter 12, Configuring data collection: WebSphere Community Edition, on page 191 v Chapter 13, Configuring data collection: DataPower SOA Appliance, on page 201 v Chapter 14, Configuring data collection: WebSphere Message Broker, on page 233
125
126
Installation Guide
Chapter 5. Overview
IBM Tivoli Composite Application Manager for SOA provides two ways that you can enable or disable data collection for your runtime environments. You can use the graphical user interface of the Data Collector Configuration Utility, which you can also run in console mode or with a silent response file, or you can run the KD4configDC command line script. If your application server is currently running: You do not have to stop your application server before running the Data Collector Configuration Utility or the KD4configDC script, but because the ITCAM for SOA data collectors are integrated into the applications or the application server, you must stop and restart the application server sometime after enabling or disabling your data collectors and before starting the monitoring agent, in order for the data collection configuration to take effect. You might prefer to restart the application server during off-shift hours. Refer to the specific chapters in this guide related to your runtime environment for details. Keep in mind the following special cases: v For the BEA WebLogic Server, the application server must be running before you run the Data Collector Configuration Utility or the KD4configDC script. If you later add additional applications to your BEA WebLogic Server, you might need to enable or disable data collection again. v While you are configuring your WebSphere Message Broker environment for data collection, the Data Collector Configuration Utility or the KD4configDC script automatically stops the message broker before performing the enable or disable operation. You receive a warning message before this configuration takes place, so you can confirm that the message broker can be stopped at this time. The messages broker is automatically restarted by the utility after configuration is completed. If you are installing over an existing IBM Tivoli Composite Application Manager for SOA installation: You might need to stop the application server before running the configuration utility or the KD4configDC script, otherwise the existing JAR file might be locked and unable to be updated. If you are upgrading an existing IBM Tivoli Composite Application Manager for SOA installation: You must disable data collection before upgrading the monitoring agent. Refer to the documentation provided with the existing product for information about disabling data collection. See Part 1, Installing the product, on page 1 for more information about upgrading your existing installation. Before enabling or disabling data collection: Some runtime environments require you to complete a few manual configuration tasks before running the Data Collector Configuration Utility or the KD4configDC script. Refer to the chapters for each supported runtime environment in this guide for details on any manual steps you must complete before enabling or disabling data collection.
Permissions needed to configure for data collection

In general, you must have permission to execute scripts in the <ITCAM4SOA_Home>/KD4/bin directory and you must have permission to add a handler to the application server you intend to monitor. The details of these permissions vary greatly according to the application server environment in question. Refer to the specific chapters for each application server for those details.
127
Setting up user permissions for non-root users: It is important on Linux and UNIX operating systems that the user who installed the monitoring agent and the user who owns the application server environment are in the same group (for example, itmusers) if non-root users are used. See Permissions needed to install the monitoring agent on page 53 for more information about setting up permissions. To run the Data Collector Configuration Utility, the following permissions are needed: v Run a Java application (and to use the XWindows server on UNIX operating systems) v Read and run additional shell scripts located in <ITCAM4SOA_Home>/KD4/bin. Additional permissions might be needed depending on the type of application server runtime environment for which data collection is being configured: WebSphere Application Server Permissions needed: v Copy files from <ITCAM4SOA_Home>/KD4/lib to <WAS_HOME>/lib/ext v For WebSphere 6.1 and later, you also need permission to copy files from <ITCAM4SOA_Home>/KD4/lib to <WAS_HOME>/plugins. v For WebSphere 6.1 and later, you also need permission to run the <WAS_HOME>/bin/osgiCfgInit command. The WebSphere application server typically must be stopped and restarted for the data collection configuration to take effect. If your user does not have permission to perform these tasks, coordinate your configuration actions with another user with these permissions. Microsoft .NET Permissions needed: v Copy files from <ITCAM4SOA_Home>/KD4/lib to the .NET Global Assembly Cache. v Locate and edit the machine.config file, which is found inside the .NET directory structure. BEA WebLogic Server To configure the data collector to monitor requester applications (both standalone and those hosted inside server applications), you must edit the application as described in Chapter 8, Configuring data collection: BEA WebLogic Server, on page 161. To perform these tasks, your user must have all the permissions normally associated with application development and deployment. In addition, you must have the authority to perform the following tasks: v Stop and restart the application server. v Add the ITCAM for SOA JAR file to the class path for the server. You should edit the server startup scripts to reference the JAR file that is installed into <ITCAM4SOA_Home>/KD4/lib. v Have read access to %BEA_HOME%/registry.xml. For BEA WebLogic Server version 8: v You must provide a username and password with permission to connect to the t3 service on the application server. v You must have JDNI and JMX authority to access the weblogic.management.adminhome mbean.
128
Installation Guide
v You must have JMX permission to discover web applications using WebServiceComponentMBean instances and to edit the webservices.xml files for each, or in the case of an Axis-based application, server-config.wsdd and client-config.wsdd. For BEA WebLogic Server version 9: v You must provide a username and password with permission to connect to the t3 service on the application server. v You must have JDNI and JMX authority to access the weblogic.management.mbeanservers.domainruntime mbean. v You must have JMX authority to manipulate Web applications using the DomainRuntimeService mbeans. v You must have authority to use these MBeans to edit the deployment descriptors of applications discovered by them. v You must have authority to add JAR files from <ITCAM4SOA_Home>/ KD4/lib/ into an applications WEB-INF/lib directory. JBoss Permissions needed: v Copy files from <ITCAM4SOA_Home>/KD4/lib to <JBOSS_HOME>/ server/server/lib v Make backup copies of deployment descriptors in the deploy/jboss-ws4ee.sar/META-INF/ directory for each server instance. v Edit axis-server-config.wsdd and axis-client-config.wsdd v Create a temporary directory under java.io.tmpdir, and read and write files within that directory. SAP NetWeaver Permissions needed: v Copy a jar from <ITCAM4SOA_Home>/KD4/lib to the WEB-INF/ directory tree for each application. v Edit lports_1.xml, protocols.txt, and application-j2ee-engine.xml files as appropriate for your application. v Certain categories of applications must have programmatic changes in order to support monitoring, as described in Chapter 11, Configuring data collection: SAP NetWeaver, on page 177. For these cases, your user must have the authority normally associated with application development and deployment. WebSphere Community Edition Permissions needed: v Edit <WASCE_HOME>/bin/setenv.bat/sh v Create and delete files in <WASCE_HOME>/temp/KD4 v Create and edit a file that will contain a list of applications. v Edit the plan file for each affected application, webservices.xml, web.xml, and ejb-jar.xml files, as needed. DataPower To configure the DataPower environment for data collection, you need file system access to create and edit files in <ITCAM4SOA_Home>/KD4/config. However, you must supply a username and password that has authority to subscribe to the WS-Management Endpoint feature on the DataPower appliance. See Configuring a user account on the DataPower SOA appliance on page 205 for more information on this procedure.
Chapter 5. Overview
129
Running the Data Collector Configuration Utility

ITCAM for SOA provides the Data Collector Configuration Utility to simplify the enabling and disabling of data collection for many of the supported runtime environments. The utility runs in either a graphical user interface mode, in console mode, or in silent mode. Logging functions are also provided to help you troubleshoot problems. You start the Data Collector Configuration Utility by running the ConfigDC script, located in the <ITCAM4SOA_Home>/KD4/bin directory where IBM Tivoli Composite Application Manager for SOA is installed. See The IBM Tivoli Composite Application Manager for SOA home directory on page xix for information on resolving the value of <ITCAM4SOA_Home>. On supported Windows operating systems, open a command prompt window and run the ConfigDC script using the following general format:
ConfigDC [console | silent [<dir_path>/]<silent_file>] [debug [<dir_path>/]<debug_file>]
On supported AIX, Solaris, HP-UX, and Linux operating systems, including z/OS UNIX System Services, run the ConfigDC script using the following general format:
./ConfigDC.sh [console | silent [<dir_path>/]<silent_file>] [debug [<dir_path>/]<debug_file>]
These command options are described further in ConfigDC script options.
ConfigDC script options

Running the ConfigDC script with no options starts the Data Collector Configuration Utility in the default graphical user interface mode. This is an InstallShield-based wizard that prompts you through several on-screen pages for the necessary parameters to enable or disable data collection for your supported runtime environment. See Running the Data Collector Configuration Utility graphical user interface on page 131 for more information. You can specify the following options with the ConfigDC script: console This option runs the Data Collector Configuration Utility in the command prompt window, if you prefer to use that instead of the InstallShield graphical user interface , or if you have no graphic console available. This option cannot be specified together with the silent option. See Running the Data Collector Configuration Utility in console mode on page 133 for more information about running the configuration utility in console mode. Examples:
ConfigDC -console ./ConfigDC.sh -console
silent [<dir_path>/]<silent_file> This option runs the Data Collector Configuration Utility in silent mode. The <silent_file> file is a simple properties file that you create, containing the necessary parameters to enable or disable data collection for your supported runtime environment. If this file is not stored in the <ITCAM4SOA_Home>\KD4\bin directory (see The IBM Tivoli Composite Application Manager for SOA home directory on page xix for information on determining the value of <ITCAM4SOA_Home>), specify the fully qualified directory path <dir_path>, where this file is located. This option cannot be
130
Installation Guide
specified together with the console option. See Running the Data Collector Configuration Utility in silent mode on page 134 for more information about running the configuration utility in silent mode. Examples:
ConfigDC -silent configdc_silent.txt ConfigDC -silent C:\silentFiles\configdc.silent ./ConfigDC.sh -silent configdc.properties
debug [<dir_path>/]<debug_file> This option can be specified alone, or after specifying either theconsole or silent options. The Data Collector Configuration Utility is run in either graphical user interface mode, console mode, or silent mode, and log information is written to the <debug_file> file for later examination and diagnosis of problems. The debug log file is a plain text file stored in the \KD4\bin directory if the optional <dir_path> is not specified, and can be opened using your preferred text editor. If you do not specify a file name for <debug_file>, then the operation is not performed, and you are presented with the syntax of the command as a reminder. Examples:
ConfigDC -debug configdc_log.txt ./ConfigDC.sh -console -debug debuglog ConfigDC -silent C:\Properties\configdc.properties -debug configdc.log
Running the Data Collector Configuration Utility graphical user interface

Running the ConfigDC script without specifying either the console or silent options starts the Data Collector Configuration Utility using the default graphical user interface. Complete these steps: 1. You are prompted to select a language to be used while in the configuration utility. Select an appropriate language and click OK. 2. The configuration utility is initialized and a welcome page with some brief information about the utility is presented. Click Next. 3. The Data Collector Configuration Utility presents you with a selection menu of supported runtime environments for which you can enable or disable data collection, as shown in Figure 39 on page 132. Select a runtime environment and click Next.
Chapter 5. Overview
131
Figure 39. Selecting a runtime environment to configure data collection
Figure 40 shows an example of specifying the parameters for enabling data collection in the WebSphere Application Server runtime environment. In this example, the Enable radio button is selected, and the directory path location for the WebSphere Application Server is typed.
Figure 40. Specifying configuration parameters to enable data collection on WebSphere Application Server.
Some runtime environments might require the Data Collector Configuration Utility to display one or more additional pages prompting you for the parameters needed to configure data collection for the selected runtime environment. The list of parameters varies depending on which runtime environment you select, but in all cases you can specify whether to enable or disable data collection by selecting the appropriate radio button. Refer to additional chapters in this guide (see Configuring data collection for your environment on page 148) for more details about the parameters needed to configure data collection for each supported runtime environment. 4. Follow the on-screen prompts, and wait for the completion of the configuration. An indication of successful or unsuccessful completion is displayed, and you are
132
Installation Guide
prompted to return to the main selection page to configure another runtime environment, or you can quit the Data Collector Configuration Utility at any time. If an error occurs during the configuration process, an appropriate error message is displayed, along with the directory path where the log file is located. You can then examine the log file for more information and take corrective action as needed. Figure 41 shows an example of how the configuration utility responds to an error caused during configuration of the JBoss runtime environment.
Figure 41. An example of an error message displayed during configuration
Running the Data Collector Configuration Utility in console mode

Running the ConfigDC script with the console option starts the Data Collector Configuration Utility in the command window, if you prefer to use that instead of the default graphical user interface. You are prompted to select a language to use in the configuration utility, and a welcome response is displayed in the command window. You are prompted to continue by typing a numerical response. Be sure to choose a language for which your command window includes the necessary code page. See the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide for additional information. Throughout the use of the utility in console mode, you must respond by typing one of several valid responses. The wizard presents the same basic selection options as described in Running the Data Collector Configuration Utility graphical user interface on page 131.
Changing the character set code page

In some situations you might find that some characters on the Data Collector Configuration Utility pages are not displayed correctly, possibly substituted with a question mark (?) or other unexpected characters. This might occur if, for example, you are running on a Windows operating system in Japanese and you choose to run the Data Collector Configuration Utility in German. To resolve this problem in console mode, you can change the Microsoft Windows character set code page for the current command prompt, using the CHCP command before running the Data Collector Configuration Utility:
Chapter 5. Overview
133
v For Italian, French, Spanish, and German languages, run this command:
chcp 1252
v For Brazilian Portuguese, run this command:

chcp 850
After running the CHCP command, run the Data Collector Configuration Utility again in console mode and select the desired language. If the problem persists, you might need to change the font that is displayed by the console.
Running the Data Collector Configuration Utility in silent mode

Running the ConfigDC script with the silent <silent_file> option starts the Data Collector Configuration Utility in silent mode. Silent mode uses properties defined in the <silent_file> response file instead of interacting with you in the graphical user interface or in console mode. Note that you cannot specify both silent mode and console mode together. When you run the Data Collector Configuration Utility in silent mode, the configuration parameters are read from a simple text response file, <silent_file>, that you create in advance. A typical response file might look similar to the following example:
# Sample silent configuration file # silent file to configure WebSphere Application Server and DataPower # File version, might be useful when migrating to future releases version=7.10.00.00 #WAS section WAS.action=enable WAS.home=/opt/IBM/WAS #DataPower section DataPower.action.1=disable DataPower.hostname.1=dp_box1 DataPower.port.1=6000 DataPower.user_id.1=admin DataPower.user_password.1=secret DataPower.path.1=/ DataPower.poll.1=20 DataPower.domains.1=
When you create your silent response file, keep these considerations in mind: v A sample silent mode response file, sample_silent.cfg, is provided for your use with the Data Collector Configuration Utility in the <ITCAM4SOA_Home>/KD4/ bin directory (see The IBM Tivoli Composite Application Manager for SOA home directory on page xix for information on determining the value of <ITCAM4SOA_Home>). Note that all lines are commented out using the # character. Be sure to remove the comment markings for each property that you plan to use, and save your changes to a unique file name. v A line in the file starting with the # character is treated as a comment, and is not processed. If the # character is used elsewhere in the line, it is not considered to be the start of a comment. This means that you can use the # character in passwords or for other uses. v The response file is coded using the ISO 8859-1 character set. If you specify any characters not in this character set, they must be represented with Unicode escapes. v The properties file can include only one version property. This property might be useful for future releases if the format of the response file changes.
134
Installation Guide
v Each property is described on a separate line, in the following format:

<data collector>.<property>.[<instance>]=<value>
<data collector> This is the name of the data collector for the given runtime environment, such as WAS, DataPower, JBoss, and others. The list of valid properties that you can configure is described in Silent mode properties. <property> This is the name of property. The list of available properties is unique for every <data collector>. The action property is available for all data collectors, and can be one of two possible values, enable or disable. The list of valid properties that you can configure is described in Silent mode properties. <instance> This is an optional designation for some data collectors, such as DataPower, that might monitor a set of application servers and DataPower appliances. For every such instance, use a unique value for <instance>. Using this additional qualifier, you can create multiple sections of your response file for a single data collector type. For example, you might create two DataPower sections in the response file, each section containing a group of uniquely defined DataPower properties. The first group of properties is specified with an <instance> value of 1, and the second group with an instance value of 2. See the descriptions in the sections that follow for data collector types that support multiple instances. <value> This is the value of the property. Property values can be left blank, or empty. Note that an empty value results in the property not specified, as opposed to using a default value. To use the default value (if any), do not specify the property in the response file (or include it in a comment line). v If a data collector is not specified in the silent response file, its parameters are not changed. v Passwords are in plain text. When the configuration utility stores the password, it is hidden from view at that time for security. v Properties and their values are case sensitive. v You can use a single silent response file to enable and disable multiple data collectors (for example, WAS, BEA, DataPower)
Silent mode properties

This section describes each group of property values that you can specify in the silent response file. The sample response file, sample_silent_cfg, also contains descriptive comments to help you understand when to use each property. Version: The version property is placed at the top of the response file and represents the version of the response file format. By default, this property is set to a value of 7.11.00.00:
version=7.11.00.00
Unless otherwise directed by IBM Software Support, do not change this value. This might be used for upgrading to future versions if the property formats change. If you are using a response file from version 7.1.0, this value is set to 7.10.00.00, and is still supported by this version of the ConfigDC script.
Chapter 5. Overview
135
WebSphere Application Server: The WebSphere Application Server data collector type has these available properties:
WAS.action={enable | disable} WAS.home=<WAS_Home_Dir>
The WAS.action property specifies whether to enable or disable data collection on the WebSphere application server installed at <WAS_Home_Dir>. This is equivalent to the enable and disable options specified with the KD4configDC script. Examples (specify either of these properties, but not both):
WAS.action=enable WAS.action=disable
The WAS.home property specifies the base installation directory path for IBM WebSphere Application Server, such as C:\IBM\WebSphere\AppServer. Examples:
WAS.home=C:\\IBM\\WebSphere\\AppServer WAS.home="C:\\Program Files\\WebSphere\\AppServer"
Notes: 1. The directory path backslash (\) character must be doubled (\\). 2. A forward slash (/) character can be used for Linux and UNIX operating systems. 3. If the directory path contains a blank space, such as C:\Program Files\WebSphere\AppServer, the path must be enclosed in double quotation marks. Properties for WebSphere Application Server do not have multiple instances, meaning you can only define one group of WAS properties in the response file, and the <instance number> format is not used. Microsoft .NET: The Microsoft .NET data collector type has this available property:
DotNET.action={enable | disable}
The DotNET.action property specifies whether to enable or disable data collection in the Microsoft .NET runtime environment. This is equivalent to the enable and disable options specified with the KD4configDC script. Examples (specify either of these properties, but not both):
DotNET.action=enable DotNET.action=disable
Properties for Microsoft .NET do not have multiple instances, meaning you can only define one group of .NET properties in the response file, and the <instance number> format is not used. BEA WebLogic Server: The BEA WebLogic Server data collector type has these available properties:
BEA.action={enable | disable} BEA.modified_env_file={true | false} BEA.axis={true | false} BEA.url=<WebLogic_Server_URL> BEA.user_id=<user_ID> BEA.user_password=<password>
The BEA.action property specifies whether to enable or disable data collection in the BEA WebLogic Server runtime environment installed at
136
Installation Guide
<WebLogic_Server_URL>. This is equivalent to the enable and disable options specified with the KD4configDC script. Examples (specify either of these properties, but not both):
BEA.action=enable BEA.action=disable
The BEA.modified_env_file property confirms that you have modified the BEA application server classpath and prepended the kd4dcagent.jar file to the WEBLOGIC_CLASSPATH environment variable. For details on this manual modification, see step 2 on page 162. Examples (specify either of these properties, but not both):
BEA.modified_env_file=true BEA.modified_env_file=false
The BEA.axis property specifies whether to configure data collection for the Apache Axis Web Services Engine, an optional feature of the BEA WebLogic Server. To configure the Apache Axis version, set this property to true, otherwise set it to false. If you do not specify this property, false is assumed as the default value. Examples (specify either of these properties, but not both):
BEA.axis=true BEA.axis=false
The BEA.url property specifies the Web address (URL) of the BEA WebLogic Server, for example, t3://localhost:7001 (t3 and t3s are proprietary BEA protocols). This is equivalent to the <URL> option specified with the KD4configDC script. Example:
BEA.url=t3://localhost:7001
The BEA.user_id property specifies a valid BEA WebLogic Server user name with authority to configure applications. This is equivalent to the <userID> option specified with the KD4configDC script. Example:
BEA.user_id=user01
The BEA.user_password property specifies a valid password associated with the value specified for the BEA WebLogic Server user name, BEA.user_id. This is equivalent to the <password> option specified with the KD4configDC script. Example:
BEA.user_password=password
Refer to your BEA WebLogic documentation for more information on passwords for your authorized user names. Properties for BEA WebLogic Server do not have multiple instances, meaning you can only define one group of BEA WebLogic Server properties in the response file, and the <instance number> format is not used. JBoss: The JBoss Application Server data collector type has these available properties:
JBoss.action={enable | disable} JBoss.configuration={default | all} JBoss.home=<JBoss_Home_Dir>
The JBoss.action property specifies whether to enable or disable data collection on the JBoss application server installed at <JBoss_Home_Dir>. This is equivalent to the enable and disable options specified with the KD4configDC script. Examples (specify either of these properties, but not both):
Chapter 5. Overview
137
JBoss.action=enable JBoss.action=disable
The JBoss.configuration property specifies the type of JBoss application server to configure. These are the valid values: default This configuration type contains everything needed to run a standalone J2EE server. all This configuration type starts all available services, including the RMI/IIOP and clustering services, and the Web services deployer, which are not loaded in the default configuration.
A third configuration type, minimal, is not supported, because this configuration does not include support for Web services. Examples (specify either of these properties, but not both):
JBoss.configuration=default JBoss.configuration=all
You can also create a custom configuration with a unique name, if preferred. The JBoss.home property specifies the base installation directory path for the JBoss application server, such as C:\JBoss. Examples:
JBoss.home=C:\\JBoss JBoss.home="C:\\Program Files\\JBoss"
Notes: 1. The directory path backslash (\) character must be doubled (\\). 2. If the directory path contains a blank space, such as C:\Program Files\JBoss, the path must be enclosed in double quotation marks. Properties for JBoss Application Server do not have multiple instances, meaning you can only define one group of JBoss properties in the response file, and the <instance number> format is not used. SAP NetWeaver: The SAP NetWeaver data collector type has these available properties:
SAP.action.<instance>={enable | disable} SAP.component.<instance>={1 | 2 | 3} SAP.sapappsdir.<instance>=<apps_dir> SAP.sid_home.<instance>=<SAP_Home> SAP.sid.<instance>=<sid_ID>
Properties for SAP NetWeaver can have multiple instances, meaning you can define more than one group of SAP NetWeaver properties in the response file, using the additional <instance> qualifier in the property name. Example:
# SAP NetWeaver Instance 1 # All server applications under SID: j2e SAP.action.1=enable SAP.component.1=3 # SAP.sapappsdir.<instance>=<apps_dir> SAP.sid_home.1=C:\\usr\\sap SAP.sid.1=j2e # # SAP NetWeaver Instance 2 # Client side standalone Web services application SAP.action.2=enable
138
Installation Guide
SAP.component.2=2 SAP.sapappsdir.2=//opt//IBM//appsdir # SAP.sid_home.<instance>=<SAP_Home> # SAP.sid.<instance>=<sid_ID>
In the above example, notice that each group is defined with its own unique instance number, and only those properties that are required by the specified type are defined. The unused properties are left commented out. The SAP.action.<instance> property specifies whether to enable or disable data collection in the SAP NetWeaver runtime environment. This is equivalent to the enable and disable options specified with the KD4configDC script. Examples (specify either of these properties, but not both):
SAP.action.1=enable SAP.action.1=disable
The SAP.component.<instance> property specifies the type of SAP NetWeaver application to configure. These are the valid integer values: 1 Specify this value for a server side Web services application if your server side application is not located under the a common SAP system ID (SID). This is equivalent to specifying the sapappsdir option with the KD4configDC script. When you specify this type, you must also define the SAP.sapappsdir.<instance> property. Specify this value for a client side standalone Web services application. This is equivalent to specifying the clientappsdir option with the KD4configDC script. When you specify this type, you must also define the SAP.sapappsdir.<instance> property. Specify this value to configure all server side Web services applications under a specific SAP system ID (SID). This is equivalent to specifying the sid option with the KD4configDC script. When you specify this type, you must also define the SAP.sid_home.<instance> and the SAP.sid.<instance> properties. Use option 3 whenever possible: Using option 3 provides some additional error checking of the directory structure for the SAP system ID that you specify, and avoids having to search the entire system for applications to configure. The SAP.sapappsdir.<instance> property specifies the directory path for the services application being monitored. You must include this property in your response file if the SAP.component.<instance> property is defined with a value of 1 or 2. In the case of a standalone client side application JAR file, specify the fully qualified directory path to the file. Examples:
SAP.sapappsdir.1=C:\\SAP_Apps\\ SAP.sapappsdir.1=/usr/sap_apps/Customer/EnterpriseSTDClientProxy.jar
Notes: 1. The directory path backslash (\) character must be doubled (\\). 2. If the directory path contains a blank space, such as C:\Program Files\SAP_apps, the path must be enclosed in double quotation marks. The SAP.sid_home.<instance> property specifies the SAP home directory, typically /usr/sap or C:\usr\sap, though the directory can be located anywhere on your system. You must include this property in your response file if the
Chapter 5. Overview
139
SAP.component.<instance> property is defined with a value of 3. This is equivalent to specifying the <home> parameter for the sid option when running the KD4configDC script. Examples:
SAP.sid_home=/usr/sap SAP.sid_home=C:\\usr\\sap
Notes: 1. The directory path backslash (\) character must be doubled (\\). 2. If the directory path contains a blank space, such as C:\Program Files\usr\sap, the path must be enclosed in double quotation marks. The SAP.sid.<instance> property specifies a common SAP system ID (SID). If you have multiple server side Web services applications under a common SID, you can configure all of them for data collection at the same time, by specifying the SID. This is equivalent to specifying the <sid> parameter for the sid option when running the KD4configDC script. Example:
SAP.sid.1=j2e
DataPower: The DataPower data collector type has these available properties:
DataPower.action.<instance>={enable | disable} DataPower.host.<instance>=<hostname> DataPower.user_id.<instance>=<user_ID> DataPower.user_password.<instance>=<password> DataPower.port.<instance>=<port> DataPower.poll.<instance>=<polling_interval> DataPower.path.<instance>=<DP_SOA_appliance_path> DataPower.domainlist.<instance>=<domain1>,<domain2>,...<domainN> DataPower.displaygroup.<instance>=<display_group_name>
Properties for DataPower can have multiple instances, meaning you can define more than one group of DataPower properties in the response file, using the additional <instance> qualifier in the property name. Example:
# DataPower Instance 1 DataPower.action.1=enable DataPower.host.1=dpbox1 DataPower.user_id.1=admin DataPower.user_password.1=xxa1b2c3 # DataPower.port.1=5550 DataPower.poll.1=60 # DataPower.path.1=/ DataPower.domainlist.1=default1 DataPower.displaygroup.1=dpbox_disp1 # # DataPower Instance 2 DataPower.action.2=enable DataPower.host.2=dpbox2 DataPower.user_id.2=user12 DataPower.user_password.2=q1w2e3r4 # DataPower.port.2=5550 # DataPower.poll.2=10 # DataPower.path.2=/ DataPower.domainlist.2="userdom1,userdom2,userdom3" DataPower.displaygroup.2=all_doms
In the above example, notice that each group is defined with its own unique instance number, and only those properties that are required by the specified type are defined. The unused properties are left commented out. The data collector uses the values in the DataPower.host.<instance>, DataPower.port.<instance>, and DataPower.path.<instance> properties to
140
Installation Guide
construct the Web address that is used as the target for messages sent to the DataPower SOA appliance. The Web address is constructed in this format:
https://<host>:<port>/<path>
The DataPower.action.<instance> property specifies whether to enable or disable data collection in the DataPower runtime environment. This is equivalent to specifying the enable and disable options with the KD4configDC script. Examples (specify either of these properties, but not both):
DataPower.action.1=enable DataPower.action.1=disable
The DataPower.host.<instance> property defines the DataPower SOA appliance hostname or IP address. This hostname is used to establish a socket connection, and is used as part of the Web address that points to the DataPower SOA appliance. This can be any length string, with no blank characters. This is equivalent to specifying the <host> parameter for the host option when running the KD4configDC script. Example:
DataPower.host.1=dpbox1
See Creating node names in Tivoli Enterprise Portal on page 217 regarding possible truncation of this value in the node name. See Considerations for enabling data collection for DataPower monitoring on page 220 for more information on using this property. The DataPower.user_id.<instance> property defines the DataPower SOA appliance authenticated user name. This user must be a valid user for the DataPower SOA appliance defined by the Host parameter. This is equivalent to specifying the <user ID> parameter for the user option when running the KD4configDC script. Example:
DataPower.user_id.1=admin123
The DataPower.user_password.<instance> property defines the DataPower SOA appliance authentication password, entered in clear text (not encoded). This password must be valid for the user specified in the DataPower.user_id.<instance> property. This is equivalent to specifying the <password> parameter for the password option when running the KD4configDC script. Example:
DataPower.user_password.1=xx123abc
The DataPower.port.<instance> property is an optional property that defines the DataPower SOA appliance port number. This port number is used to establish a socket connection and is used as part of the Web address pointing to the DataPower SOA appliance. The value specified must be an integer from 0 to 65535. If this parameter is not specified, the default value of 5550 is used. This is equivalent to specifying the <port number> parameter for the port option when running the KD4configDC script. Example:
DataPower.port.1=5550
The DataPower.poll.<instance> property is an optional property that defines the DataPower SOA appliance polling interval, in seconds. The data collector waits this amount of time between each poll of the DataPower SOA appliance. The value of this property must be an integer from 5 to 300 (5 seconds to 5 minutes). If this parameter is not specified, the default value of 10 is used. This is equivalent to specifying the <polling interval> parameter for the poll option when running the KD4configDC script. Example:
DataPower.poll.1=60
Chapter 5. Overview
141
The DataPower.path.<instance> property is an optional property that defines the path to the DataPower SOA appliance. This path is used as part of the Web address pointing to the DataPower SOA appliance. This can be any valid path string, with no blank characters. If this parameter is not specified, the default value of / is used. This is equivalent to specifying the <path string> parameter for the path option when running the KD4configDC script. Example:
DataPower.path.1=/
The DataPower.domainlist.<instance> property is an optional property that defines the list of domains to be monitored on the DataPower SOA appliance. The value for this property is specified in the form of a comma separated list of domain names. Any domains in this list that are not authorized to the user defined by the DataPower.user_id.<instance> property are not monitored. Specify each domain name as any string, with no blank characters. If you specify more than one domain name, the entire list of comma separated names must be enclosed in double quotes. This is equivalent to specifying the list of domain names for the domainlist option when running the KD4configDC script. Examples:
DataPower.domainlist.1=domain1 DataPower.domainlist.1="domain1,domain2,domain3"
See Considerations for enabling data collection for DataPower monitoring on page 220 for more information on using this property. The DataPower.displaygroup.<instance> property is an optional property that defines the DataPower SOA appliance display name. The name can be any string, with no blank characters, up to 16 characters long. This is equivalent to specifying the <display group> parameter for the displaygroup option when running the KD4configDC script. Example:
DataPower.path.1=/
See Creating node names in Tivoli Enterprise Portal on page 217 regarding possible truncation of this value in the node name. See Considerations for enabling data collection for DataPower monitoring on page 220 for more information on using this property. DataPower as a service: A special silent mode response file property is available for you to register the DataPower data collector as a Windows service or UNIX daemon:
DataPowerService.action={enable | disable}
This is equivalent to specifying the registerService or deregisterService options with the KD4configDC script. Examples (specify either of these properties, but not both):
DataPowerService.action=enable DataPowerService.action=disable
Properties for registering DataPower as a service or daemon do not have multiple instances, meaning you can only define one group of properties in the response file, and the <instance number> format is not used. WebSphere Message Broker: The WebSphere Message Broker data collector type has these available properties:
142
Installation Guide
MessageBroker.action.<instance>={enable | disable} MessageBroker.allow_to_stop_mb.<instance>={true | false} MessageBroker.broker_name.<instance>=<broker> MessageBroker.execution_group_name.<instance>=<group> MessageBroker.message_flow_name.<instance>=<flow>
Properties for WebSphere Message Broker can have multiple instances, meaning you can define more than one group of WebSphere Message Broker properties in the response file, using the additional <instance> qualifier in the property name. Example:
# WebSphere Message Broker Instance 1 MessageBroker.action.1=enable MessageBroker.allow_to_stop_mb.1=true MessageBroker.broker_name.1=testbroker MessageBroker.execution_group_name.1=testGroup MessageBroker.message_flow_name.1=testFlow # # WebSphere Message Broker Instance 2 MessageBroker.action.2=enable MessageBroker.allow_to_stop_mb.2=true MessageBroker.broker_name.2=WM_Broker MessageBroker.execution_group_name.2=WMGroup1 MessageBroker.message_flow_name.2=WMFlow
In the above example, notice that each group is defined with its own unique instance number, and that all properties are required. The MessageBroker.action.<instance> property specifies whether to enable or disable data collection in the WebSphere Message Broker runtime environment. This is equivalent to specifying the enable and disable options with the KD4configDC script. Examples (specify either of these properties, but not both):
MessageBroker.action=enable MessageBroker.action=disable
The MessageBroker.allow_to_stop_mb.<instance> property confirms that the message broker can be automatically stopped while data collection is configured, and then restarted after configuration is complete. Examples (specify either of these properties, but not both):
MessageBroker.allow_to_stop_mb.1=true MessageBroker.allow_to_stop_mb.1=false
The MessageBroker.broker_name.<instance> property specifies the name of the message broker to be configured. This is equivalent to specifying the <broker_name> parameter with the KD4configDC script. Example:
MessageBroker.broker_name.1=BrokerName
The MessageBroker.execution_group_name.<instance> property specifies the name of the execution group in the specified message broker to be configured. This is equivalent to specifying the <execution_group_name> parameter with the KD4configDC script. Example:
MessageBroker.execution_group_name.1=MB1_exgroup1
The MessageBroker.message_flow_name.<instance> property specifies the name of the message flow within the specified execution group to be configured. This is equivalent to specifying the <message_flow_name> parameter with the KD4configDC script. Example:
MessageBroker.message_flow_name.1=messageFlow1
Chapter 5. Overview
143
Configure managed SCA mediation primitive support in IBM WebSphere Process Server and IBM WebSphere Enterprise Service Bus: Special silent mode response file properties are available for you to configure your IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus runtime environment to support deployed SOA applications that contain managed SCA mediation primitives. These are the available properties:
SCAMediationPrimitives.action={enable | disable} SCAMediationPrimitives.home=<WPS_WESB_Home>
Specifying these properties in your response file is equivalent to running the kd4configMediationInstall script to configure this support. The SCAMediationPrimitives.action property specifies whether to configure or remove support for deployed SOA applications that contain managed SCA mediation primitives. This is equivalent to specifying the enable and disable options with the kd4configMediationInstall script. Examples (specify either of these properties, but not both):
SCAMediationPrimitives.action=enable SCAMediationPrimitives.action=disable
The SCAMediationPrimitives.home property specifies the directory location where IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus is installed. This is equivalent to specifying the <WPS_WESB_InstallDir> parameter with the kd4configMediationInstall script. Examples:
SCAMediationPrimitives.home=C:\\IBM\\WESB SCAMediationPrimitives.home="C:\\Program Files\\WPS"
Notes: 1. The directory path backslash (\) character must be doubled (\\). 2. If the directory path contains a blank space, such as C:\Program Files\WPS, the path must be enclosed in double quotation marks. Properties for configuring support for deployed SOA applications that contain managed SCA mediation primitives do not have multiple instances, meaning you can only define one group of properties in the response file, and the <instance number> format is not used. Deploy EAR file to application servers to support SOA applications with managed SCA mediation primitives: Special silent mode response file properties are available for you to deploy the configuration support EAR file to each application server in your IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus runtime environment. These are the available properties:
SCAMediationPrimitivesApps.action.<instance>={enable | disable} SCAMediationPrimitivesApps.home.<instance>=<WPS_WESB_ProfileDir> SCAMediationPrimitivesApps.node_name.<instance>=<node> SCAMediationPrimitivesApps.server_name.<instance>=<server> SCAMediationPrimitivesApps.cluster_name.<instance>=<cluster> SCAMediationPrimitivesApps.user_id.<instance>=<user> SCAMediationPrimitivesApps.user_password.<instance>=<password>
Specifying these properties in your response file is equivalent to running the kd4configMediationDeploy script to configure this support. These properties can have multiple instances, meaning you can define more than one group of properties in the response file, using the additional <instance> qualifier in the property name. Example:
144
Installation Guide
# Configure SCA Mediation Primitives support, Instance 1 SCAMediationPrimitivesApps.action.1=enable SCAMediationPrimitivesApps.home.1=C:\\IBM\\WESB\\profile # SCAMediationPrimitivesApps.node_name.1=ServNode1 # SCAMediationPrimitivesApps.server_name.1=Server_B SCAMediationPrimitivesApps.cluster_name.1=Cluster_B1 # SCAMediationPrimitivesApps.user_id.1=<user> # SCAMediationPrimitivesApps.user_password.1=<password> # # Configure SCA Mediation Primitives support, Instance 2 SCAMediationPrimitivesApps.action.2=enable SCAMediationPrimitivesApps.home.2="C:\\WebSphere Process Server\Profiles" SCAMediationPrimitivesApps.node_name.2=node123 SCAMediationPrimitivesApps.server_name.2=server123a # SCAMediationPrimitivesApps.cluster_name.2=Cluster123 SCAMediationPrimitivesApps.user_id.2=admin007 SCAMediationPrimitivesApps.user_password.2=q1w2e3r4
In the above example, notice that each group is defined with its own unique instance number, and only those properties that are required by the specified type are defined. The unused properties are left commented out. The SCAMediationPrimitivesApps.action.<instance> property specifies whether to deploy or remove the mediation configuration support EAR file. This is equivalent to specifying the enable and disable options with the kd4configMediationDeploy script. Examples (specify either of these properties, but not both):
SCAMediationPrimitivesApps.action.1=enable SCAMediationPrimitivesApps.action.1=disable
The SCAMediationPrimitivesApps.home.<instance> property specifies the directory location for the IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus profile. This is equivalent to specifying the <profile_directory> parameter with the kd4configMediationDeploy script. Example:
SCAMediationPrimitivesApps.home.1=C:\\IBM\\WESB\\profile SCAMediationPrimitivesApps.home.1="C:\\Program Files\\WESB\\profile"
Notes: 1. The directory path backslash (\) character must be doubled (\\). 2. If the directory path contains a blank space, such as C:\Program Files\WPS\profile, the path must be enclosed in double quotation marks. The SCAMediationPrimitivesApps.node_name.<instance> property specifies the node name of the target application server to receive the EAR file support. This is equivalent to specifying the <nodeName> parameter with the kd4configMediationDeploy script. Example:
SCAMediationPrimitivesApps.node_name.1=Node1
If you specify this property, keep in mind these conditions: v You must also specify the SCAMediationPrimitivesApps.server_name.<instance> property. v You cannot specify the SCAMediationPrimitivesApps.cluster_name.<instance> property in the same <instance> grouping. The SCAMediationPrimitivesApps.server_name.<instance> property specifies the name of the target application server to receive the EAR file support. This is equivalent to specifying the <serverName> parameter with the kd4configMediationDeploy script. Example:
SCAMediationPrimitivesApps.node_name.1=Node1
Chapter 5. Overview
145
If you specify this property, you must also specify the SCAMediationPrimitivesApps.node_name.<instance> property. The SCAMediationPrimitivesApps.cluster_name.<instance> property specifies the name of the target cluster of application servers to receive the EAR file support. This is equivalent to specifying the <clusterName> parameter for the cluster option when running the kd4configMediationDeploy script. Example:
SCAMediationPrimitivesApps.cluster_name.1=Cluster1
If you specify this property, you cannot specify either the SCAMediationPrimitivesApps.node_name.<instance> property, or the SCAMediationPrimitivesApps.server_name.<instance> property in the same <instance> grouping. The SCAMediationPrimitivesApps.user_id.<instance> property is an optional property that is only required if security is configured for the runtime environment. In this case, the user name connects to the Deployment Manager (the manager of the cell). If security is not configured, this property can be commented out in the response file. This is equivalent to specifying the <username> parameter with the kd4configMediationDeploy script. Example:
SCAMediationPrimitivesApps.user_id.1=admin1
The SCAMediationPrimitivesApps.user_password.<instance> property is an optional property that is only required if security is configured for the runtime environment. In this case, this property defines the valid password associated with the user ID specified in the SCAMediationPrimitivesApps.user_id.<instance> property, entered in clear text (not encoded). This is equivalent to specifying the <password> parameter with the kd4configMediationDeploy script. Example:
SCAMediationPrimitivesApps.user_password.1=xx123abc
Silent mode errors and messages

The Data Collector Configuration Utility validates the operations and their values in the silent response file and displays a message when required values are missing or when a property is assigned to a value that is not valid. The Data Collector Configuration Utility displays messages describing the operations that are being performed by the utility and results of those operations (success or failure). Properties and their values in the silent response property file are validated by the utility. When an error occurs, the error code and the error message are displayed describing the cause of the failure, if possible. If the silent response file contains configuration properties for several data collectors, and errors occur while attempting to configure one of the data collectors, the utility attempts to continue to configure the remaining data collectors specified in the file. If you attempt to configure multiple instances of a data collector that does not support multiple instances, error messages are displayed and the configuration of all instances of that data collector are ignored. The utility attempts to configure other data collectors specified in the silent response property file.
Additional configuration options

In addition to enabling or disabling data collection for supported runtime environments, the Data Collector Configuration Utility also provides options to perform these additional configuration tasks:
146
Installation Guide
v Register or deregister DataPower as a system service or UNIX daemon. See Chapter 13, Configuring data collection: DataPower SOA Appliance, on page 201 for more information about this feature. v Installing and configuring SCA mediation primitive runtime support on IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus. See Configuring managed SCA mediation primitive runtime support on page 152 for more information, and refer to the IBM Tivoli Composite Application Manager for SOA Tools guide for more information about managed SCA mediation primitives.
Running the KD4configDC script

As an alternative to using the Data Collector Configuration Utility to enable or disable data collection for supported runtime environments, you can use the KD4configDC script, located in the <ITCAM4SOA_Home>/KD4/bin directory where IBM Tivoli Composite Application Manager for SOA is installed. See The IBM Tivoli Composite Application Manager for SOA home directory on page xix for information about how to determine the value of <ITCAM4SOA_Home>. On supported Windows operating systems, run the KD4configDC script using the following general format:
KD4configDC {enable | disable} env x <environment specific arguments>
On supported AIX, Solaris, HP-UX, and Linux operating systems, including z/OS UNIX System Services, run the KD4configDC script using the following general format:
./KD4configDC.sh {-enable | -disable} -env x <environment specific arguments>
The following parameters and values are defined for these commands: enable Specify this required parameter to enable the specified runtime environment for data collection. You must specify either the enable or disable parameter, but not both. disable Specify this required parameter to disable the specified runtime environment for data collection. You must specify either the enable or disable parameter, but not both. env x Specify this required parameter to identify the type of runtime environment to be enabled or disabled for data collection. The value of x is an integer from 1 to 10, indicating one of the following supported runtime environments: v 1 = IBM WebSphere Application Server v 2 = Microsoft .Net v 3 = BEA WebLogic Server v 4 = JBoss v 5 = Customer Information Control System (CICS) Transaction Server v 6 = SAP NetWeaver v 7 = WebSphere Community Edition v 8 = DataPower SOA Appliance v 10 = Message Broker
Chapter 5. Overview
147
<environment specific arguments> This parameter is actually one or more parameters unique to each type of supported runtime environment. Depending on the value specified for x in the env x parameter, the parameters specified with the KD4configDC script vary. These runtime environment specific arguments are further detailed in the sections that follow, along with more detailed information about each supported runtime environment.
Getting help for KD4configDC

You can type the following command to view the online help for the KD4configDC script:
KD4configDC -h
For Linux, AIX, HP-UX, or Solaris operating systems, type the following command to view the online help for the KD4configDC script:
./KD4configDC.sh -h
Messages related to running the KD4configDC script are documented in the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide.
Configuring data collection for your environment

Refer to the following chapters for more information about each supported runtime environment and the specific parameters and values needed to enable and disable data collection in each environment. If you have problems with the Data Collector Configuration Utility or in running the KD4configDC script, refer to the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide for more information. v Chapter 6, Configuring data collection: WebSphere Application Server, on page 149 v Chapter 7, Configuring data collection: Microsoft .NET, on page 159 v Chapter 8, Configuring data collection: BEA WebLogic Server, on page 161 v Chapter 9, Configuring data collection: JBoss, on page 171 v Chapter 10, Configuring data collection: CICS Transaction Server, on page 175 v Chapter 11, Configuring data collection: SAP NetWeaver, on page 177 v Chapter 12, Configuring data collection: WebSphere Community Edition, on page 191 v Chapter 13, Configuring data collection: DataPower SOA Appliance, on page 201 v Chapter 14, Configuring data collection: WebSphere Message Broker, on page 233
148
Installation Guide
Chapter 6. Configuring data collection: WebSphere Application Server

Since the first release of ITCAM for SOA, monitoring of Web services message traffic between services in a service oriented architecture (SOA) in the IBM WebSphere Application Server runtime environment continues to expand and evolve. The initial focus on topology and pattern and sequence discovery in WebSphere and IBM WebSphere Enterprise Service Bus environments was later broadened to include support for additional versions of IBM WebSphere Application Server and WebSphere Community Edition (CE). In order to provide a more complete solution, additional capabilities were provided, including discovery and monitoring of Web services, Service Component Architecture (SCA) components, and mediations hosted by IBM WebSphere Enterprise Service Bus and IBM WebSphere Process Server. A set of configurable mediation primitives was also provided for use in the WebSphere Integration Developer environment. These managed SCA mediation primitives can be added to a mediation flow component that can then be included in an SCA-based application. When that application is then deployed in your IBM WebSphere Enterprise Service Bus or IBM WebSphere Process Server environment, you have the ability to configure these mediations at runtime. Additional support is included for monitoring message traffic through the JAX-WS application programming interface in WebSphere Application Server version 6.1 (assuming that you have also installed the Web Services Feature pack) and later versions. For WebSphere environment, the monitoring method uses the AXIS2 implementation. The JAX-WS interface also supports SOAP version 1.2 requests and Web Services Description Language version 1.2. Note that filter controls are not supported.
About the Service Component Architecture

IBM WebSphere Process Server and IBM WebSphere Enterprise Service Bus introduced a way to model services in an SOA, called the Service Component Architecture (SCA). SCA is designed to separate business logic from its implementation, so that you can focus on assembling an integrated application without knowing implementation details. The Service Component Architecture is based on SCA modules and SCA components. An SCA module is made up of multiple SCA components. In ITCAM for SOA, SCA components are treated as Web Services Description Language (WSDL) service ports. With additional support for IBM WebSphere Enterprise Service Bus and IBM WebSphere Process Server, ITCAM for SOA discovers information about messages flowing between SCA components. The ITCAM for SOA data collector is installed and application servers are configured once in the IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus environment. The data collector does not require each SCA application to be configured separately. When you deploy new SCA applications into your monitored environment, they are automatically monitored as well.
149
The SCA data collector supports both synchronous and asynchronous interactions flowing through the application server runtime environment. Note that in the IBM WebSphere Process Server version 6.0 and IBM WebSphere Enterprise Service Bus version 6.0 environments, some asynchronous interactions between SCA components might result in requests or responses being reported multiple times or not at all. This is caused by thread switching in the SCA application server runtime environment and limitations of the data collector in tracking flows across these thread switches. Monitoring of asynchronous interactions is provided to give you a more complete picture of the services that exist in the environment, however you should not expect the metrics collected for asynchronous interactions to be precise. An improved monitoring interface in version 6.1 of these products provides for more reliable monitoring results. Refer to your WebSphere Integration Developer documentation for more information about these synchronous and asynchronous interactions. See Configuring managed SCA mediation primitive runtime support on page 152 for more information on configuring your IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus runtime environment to support deployed SOA applications that contain managed SCA mediation primitives.
Enabling data collection

To enable the IBM WebSphere Application Server environment for data collection, complete the following steps: 1. Optionally stop the WebSphere Application Server before enabling the application for data collection. You do not have to stop the application server before running the KD4configDC command, but the data collector does not begin to collect data until after the application server is stopped and restarted. You might prefer to stop and restart the application server during off-shift hours. Refer to your WebSphere documentation for the specific procedure to stop the application server. 2. Enable data collection using either the Data Collector Configuration Utility or by running the KD4configDC command. v Using the Data Collector Configuration Utility: Complete these steps:
Figure 42. Enabling data collection on WebSphere Application Server.
150
Installation Guide
a. Start the Data Collector Configuration Utility in either the default graphical user interface mode, in console mode, or in silent mode. See Running the Data Collector Configuration Utility on page 130 for more information. b. Select the option to configure IBM WebSphere Application Server. c. Select the option to enable data collection. d. Specify the WebSphere Application Server directory (the path location where the application server is located). For example, on Windows operating systems, C:\WebSphere\AppServer. e. Wait for the configuration utility to complete the operation. f. Exit the utility. v Using KD4configDC: Run the following command from a command prompt window (see Running the KD4configDC script on page 147 for more information):
KD4configDC -enable -env 1 <WAS_HOME>
<WAS_HOME> This argument specifies the base installation directory for WebSphere Application Server. The typical default value is C:\Program Files\WebSphere\AppServer (note that because this path name contains a blank space, the entire path is surrounded with quotation marks). Examples: KD4configDC -enable -env 1 In this example, the %WAS_HOME% environment variable is used to specify the WebSphere base installation directory. The command completes with a return code of 0, as shown in the following example:
C:\IBM\ITM\TMAITM6\KD4\bin>kd4configdc -enable -env 1 Configuration command = "C:\\IBM\\ITM\\TMAITM6\\"\KD4\bin\configWASDC.BAT -enable USE_ENV_VAR 1 file(s) copied. Return code from configWASDC.bat = 0 KD4configDC -enable -env 1 C:\WebSphere\Appserver
In this example, the WebSphere base installation directory is explicitly specified, and because there are no blank spaces in the path, the argument can be specified without surrounding quotation marks. KD4configDC -enable -env 1 "C:\Program Files\WebSphere\Appserver" In this example, the WebSphere base installation directory is specified explicitly, and because there is a blank space in the path, the argument is surrounded by quotation marks. ./KD4configDC.sh -enable -env 1 /opt/IBM/WebSphere/Appserver This example is for running KD4configDC on a supported AIX or Solaris operating system. 3. Restart the WebSphere application server (refer to your WebSphere documentation for the specific procedure). The data collector becomes active after the WebSphere application server is restarted.
Disabling data collection

To disable data collection in the IBM WebSphere Application Server environment, you must first stop the WebSphere application server, and then either use the Data Collector Configuration Utility or run the KD4configDC command using the -disable parameter to disable data collection. v Using the Data Collector Configuration Utility: Complete these steps:
151
1. Run the Data Collector Configuration Utility in either the default graphical user interface mode, in console mode, or in silent mode. See Running the Data Collector Configuration Utility on page 130 for more information. 2. Select the option to configure IBM WebSphere Application Server. 3. Select the option to disable data collection. 4. Specify the WebSphere Application Server directory (the path location where the application server is located). For example, on Windows operating systems, C:\WebSphere\AppServer. 5. Wait for the configuration utility to complete the operation. 6. Exit the utility. v Using KD4configDC: Run the following command from a command prompt window (see Running the KD4configDC script on page 147 for more information):
KD4configDC -disable -env 1 <WAS_HOME>
After the disable task completes successfully, restart the application server.
Configuring managed SCA mediation primitive runtime support

This section describes how to configure your IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus runtime environment to support deployed SOA applications that contain managed SCA mediation primitives. You can use either the Data Collector Configuration Utility or you can run individual scripts from a command prompt.
Configuring support using the Data Collector Configuration Utility

To configure these runtime environments for managed SCA mediation primitives using the Data Collector Configuration Utility, complete the following steps (note that you must run the Data Collector Configuration Utility twice; the first time to configure the runtime environment to support managed SCA mediation primitives, and again to deploy the configuration support EAR file to each application server): 1. Run the Data Collector Configuration Utility to configure the runtime environment: a. Start the Data Collector Configuration Utility in either the default graphical user interface mode, in console mode, or in silent mode. See Running the Data Collector Configuration Utility on page 130 for more information. b. Select the option to configure SCA Mediation Primitives. c. Select the option to Configure IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus for managed SCA mediation primitives support.
152
Installation Guide
Figure 43. Configuring runtime environments for managed SCA mediation primitives
d. Click Next. e. On the next page, select the Enable radio button. f. Specify the home directory path for IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus. If the directory path contains a blank space, surround the entire directory path with double quotation marks. Examples:
C:\WPS "C:\Program Files\WPS" /opt/IBM/WPS
g. Click Next. Wait for the configuration utility to complete the operation. h. Exit the utility. 2. Restart your IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus server after running the configuration utility. 3. For each target application server in the runtime environment, or for a cluster containing one or more target application servers, run the Data Collector Configuration Utility again, to deploy the configuration support EAR file: a. Start the Data Collector Configuration Utility in either the default graphical user interface mode, in console mode, or in silent mode. See Running the Data Collector Configuration Utility on page 130 for more information. b. Select the option to configure SCA Mediation Primitives. c. Select the option to Deploy the support ear file to IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus for managed SCA mediation primitives support (see Figure 43). d. Click Next. e. On the next page, select the Enable radio button. f. Specify the home profile directory for IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus. If the directory path contains a blank space, surround the entire directory path with double quotation marks. Examples:
C:\WPS\profiles "C:\Program Files\WPS\profiles" /opt/IBM/WPS/profiles/ProcSrv01
g. Click Next. Select either of the following options: v Configure with the node and server name
153
If you select this option, enter the node name of the application server and the name of the target server where the ear file is to be deployed. v Configure with the cluster name If you select this option, enter the cluster name for one or more target application servers where the ear file is to be deployed.
Figure 44. Deploying the configuration support EAR file for managed SCA mediation primitives
h. Click Next. If security is configured for the runtime environment, select the check box on the next page and enter the user name and password authorized to connect to either the application server (for non-clustered environments, or to the Deployment Manager (the manager of the cell) for clustered environments. If security is not configured for the runtime environment, you can skip this step.
Figure 45. Specifying the authorized user name and password to access a secure environment
i. Click Next. Wait for the configuration utility to complete the operation. You might need to wait several minutes for this operation to complete
154
Installation Guide
j. Exit the utility.
Configuring support using available scripts

To configure these runtime environments for managed SCA mediation primitives using available scripts, complete the following steps: 1. Depending on your operating system, from a command prompt, navigate to the <ITCAM4SOA_Home>/KD4/bin directory location. See The IBM Tivoli Composite Application Manager for SOA home directory on page xix for information on resolving the value of <ITCAM4SOA_Home>. 2. Run the KD4configMediationInstall script using the following syntax: v On Windows:
KD4configMediationInstall [-enable | -disable] <WPS_WESB_InstallDir>
v On Linux, AIX, HP-UX, and Solaris:

./KD4configMediationInstall.sh [-enable | -disable] <WPS_WESB_InstallDir>
In these commands: enable Configures the runtime environment to support managed SCA mediation primitives. disable Removes the support from the runtime environment. <WPS_WESB_InstallDir> Specifies the directory location where IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus is installed 3. Restart your IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus server after running the script. 4. For each target application server, or for a cluster that contains one or more target application servers on the computer system, deploy the configuration support ear file by running the KD4configMediationDeploy script. Depending on your operating system, from a command prompt, navigate to the <ITCAM4SOA_Home>/KD4/bin directory location and run KD4configMediationDeploy, using the following syntax: v For Windows:
KD4configMediationDeploy {enable | disable} <profile_directory> {nodeName serverName | cluster clusterName} [username password]
v For Linux, AIX, and HP-UX, Solaris:

./KD4configMediationDeploy.sh {enable | disable} <profile_directory> {nodeName serverName | cluster clusterName} [username password]
In these commands: enable Deploys the mediation configuration support ear file. disable Removes the mediation configuration support ear file. <profile_directory> Specifies the directory location of the IBM WebSphere Process Server or IBM WebSphere Enterprise Service Bus profile nodeName Specifies the node name of the server.
155
serverName When nodeName is specified, this is the name of the server to deploy. cluster Declares that you are deploying to a cluster. clusterName When cluster is specified, this is the name of the cluster. username If security is configured for the runtime environment, this is the user name to connect to either the application server (for non-clustered environments, or to the Deployment Manager (the manager of the cell) for clustered environments. If security is not configured, this parameter can be omitted. password If the username is specified, this is the valid password for that username. You might need to wait several minutes for this operation to complete.
Deploying and managing your applications

After completing these configuration steps, you can deploy your applications that use managed SCA mediation primitives and then use the Mediation Configuration workspace in the Tivoli Enterprise Portal to see the enabled or disabled state of each managed SCA mediation primitive. Use the ConfigureMediation_610 and DeletePrimitiveProperty_610 Take Action commands to configure the state of the managed SCA mediation primitives dynamically in your runtime environment. See the IBM Tivoli Composite Application Manager for SOA Users Guide and the online help for information about these Take Action commands and their resulting return codes.
Limitations when monitoring SCA messages

Be aware of the following limitations on data collector support in the SCA environment: v The data collector in the SCA environment only supports monitoring, not filtering. You can define monitoring controls to limit which SCA services or operations are monitored, but any filter controls defined to reject messages are ignored. Use the Tivoli configurable fail mediation instead. v Monitor control for the message content parameter (none, headers, body, full) only supports the none value. All other values are ignored and treated as none. Use the Tivoli configurable logging mediation instead. v The message length for SCA interactions is always reported as zero. v The SCA data collector supports correlation of cross-module flows using SCA binding or Web service binding. v The SCA data collector does not support remote host or remote IP address. v SCA monitoring information collected in the IBM WebSphere Process Server version 6.0 environment might not render properly in the IBM Web Services Navigator topology, sequence diagram and patterns views. v Some asynchronous interactions between SCA components in IBM WebSphere Process Server version 6.0 environments might result in requests or responses being reported multiple times or not at all. This is caused by thread switching in the SCA application server runtime environment and limitations of the data collector in tracking flows across these thread switches. Monitoring of
156
Installation Guide
asynchronous interactions is provided to give you a more complete picture of the services that exist in the environment, however you should not expect the metrics collected for asynchronous interactions to be precise.
Logging and Filtering

The data collector in the SCA environment supports the monitor controls to define which SCA services and operations to monitor, but ignores the message content logging setting (none, headers, body, full) and never records message content. The filter controls (rejection of messages) are not supported by the data collector in the SCA environment. This function is supported by IBM WebSphere Enterprise Service Bus and IBM WebSphere Process Server mediations to manage the rejection of messages. To record message content, use the log mediation function of IBM WebSphere Enterprise Service Bus or IBM WebSphere Process Server.
157
158
Installation Guide
Chapter 7. Configuring data collection: Microsoft .NET

IBM Tivoli Composite Application Manager for SOA provides support for monitoring of Web services running in the Microsoft .NET application server runtime environment.

Enable data collection using either the Data Collector Configuration Utility or by running the KD4configDC command. v Using the Data Collector Configuration Utility: Complete these steps:
Figure 46. Enabling data collection on Microsoft .NET
1. Start the Data Collector Configuration Utility in either the default graphical user interface mode, in console mode, or in silent mode. See Running the Data Collector Configuration Utility on page 130 for more information. 2. Select the option to configure Microsoft .Net. 3. Select the option to enable data collection. 4. Wait for the configuration utility to complete the operation. 5. Exit the utility. v Using KD4configDC: Run the following command from a command prompt window (see Running the KD4configDC script on page 147 for more information):
KD4configDC enable env 2
For this command, no additional application server runtime environment specific parameters are required. Multiple messages: The configuration process attempts to configure data collection for all instances of the Microsoft .NET framework that it finds on the computer. This might result in certain messages being repeated, once for each Microsoft .NET instance found. You do not need to restart the Microsoft .Net server after enabling the environment for data collection.
159

To disable data collection in the Microsoft .Net, environment, run either the Data Collector Configuration Utility or the KD4configDC command. v Using the Data Collector Configuration Utility: Complete these steps: 1. Run the Data Collector Configuration Utility in either the default graphical user interface mode, in console mode, or in silent mode. See Running the Data Collector Configuration Utility on page 130 for more information. 2. Select the option to configure Microsoft .Net. 3. Select the option to disable data collection. 4. Wait for the configuration utility to complete the operation. 5. Exit the utility. v Using KD4configDC: Run the following command from a command prompt window (see Running the KD4configDC script on page 147 for more information):
KD4configDC disable env 2
Multiple messages: The configuration process attempts to configure data collection for all instances of the Microsoft .NET framework that it finds on the computer. This might result in certain messages being repeated, once for each Microsoft .NET instance found. You do not need to restart the Microsoft .Net server after disabling the environment for data collection.
160
Installation Guide
Chapter 8. Configuring data collection: BEA WebLogic Server

This chapter describes the ITCAM for SOA data collector support for the BEA WebLogic Server runtime environment. Support is also provided for the Apache Axis version 1.2 SOAP engine running in the BEA WebLogic application server runtime environment. You can optionally choose to enable this Apache Axis support if needed. In the BEA WebLogic Server environment, the process of configuring for data collection adds the JAX-RPC handler to the web-services.xml deployment descriptor for each deployed service running on a local BEA application server. Before you can enable this environment for data collection, you must perform a few additional steps to prepare for both Client Side and Server Side configuration.
About Apache Axis

Apache Axis is a SOAP engine, defined on the official Apache Axis Web site (http://ws.apache.org/axis/java/install.html) as a framework for constructing SOAP processors such as clients, servers, gateways, etc. Axis runs as several servlets, while the BEA WebLogic application server provides the Web container for these Axis servlets. Conceptually, consider this environment as a BEA WebLogic server with Axis version 1.2 service support. When Axis is installed according to the basic Axis installation instructions (see the Apache Axis Web site for more information on basic and advanced installation options), Axis is deployed as a Web application to the Web container in either an exploded directory or a packaged war file, for example axis.war. You deploy your services into this Axis Web application by adding new classes and registering the new service into the Axis Web application. The Axis data collector, when enabled for the Axis Web application, monitors these services. If you deploy additional services after the Axis data collector is enabled for data collection, the newly deployed services are monitored automatically. Message logging and message rejection are supported in the same manner as the BEA WebLogic data collector.
BEA client side configuration

Because BEA client applications that use the Web Services stack do not have deployment descriptors, you must add the IBM Tivoli Composite Application Manager for SOA handler programmatically using the javax.xml.rpc.handler.HandlerInfo and javax.xml.rpc.handler.HandlerRegistry classes. The following example is sample client application for BEA WebLogic version 8:
import import import import import import java.util.ArrayList; java.io.IOException; javax.xml.namespace.QName; javax.xml.rpc.ServiceException; javax.xml.rpc.handler.HandlerInfo; javax.xml.rpc.handler.HandlerRegistry;
public class Main{ public static void main( String[] args ){ . . . }

161
public Main( String wsdl ){ try { someService service = new someService_Impl( wsdl ); someServicePort port = service.getSomeServicePort(); . . . QName listQname[] = new QName[1]; listQname[0] = new QName("http://www.ibm.com/KD4","ITCAM_for_SOA"); List handlerList = new ArrayList(); handlerList.add( new HandlerInfo( com.ibm.management.soa.agent.bea.ITMBEAClientHandler.class, null, listQname) ); HandlerRegistry registry = service.getHandlerRegistry(); registry.setHandlerChain( portName, handlerList ); port.someWSCall(); } catch( IOException e ) { . . . } catch( ServiceException e ) { . . . } } }
BEA Version 9 class name: For BEA WebLogic Server version 9, the sample application is the same as for version 8, except that the class name should be com.ibm.management.soa.agent.bea9.ITMBEAClientHandler.class. See the following Web site for more information:
http://e-docs.bea.com/wls/docs81/webserv/interceptors.html
BEA server side configuration

Before you enable data collection, complete the following steps: 1. Shut down the BEA Server, following the instructions in the product documentation. You can use the Administration Console or the BEA WebLogic Administrative utility. 2. Modify the BEA application server classpath. To modify the classpath for all domains, edit the commEnv.cmd (or, for UNIX operating systems, commEnv.sh) script file in <WebLogic_HOME>/common/bin and append the kd4dcagent.jar file to the WEBLOGIC_CLASSPATH environment variable. For example: v On Windows operating systems, edit the commEnv.cmd script:
set WEBLOGIC_CLASSPATH= %JAVA_HOME%\lib\tools.jar;...;C:\IBM\ITM\tmaitm6\KD4\lib\kd4dcagent.jar
v On AIX operating systems, edit the commEnv.sh script:

WEBLOGIC_CLASSPATH= "${JAVA_HOME}/lib/tools.jar... ${CLASSPATHSEP}/candle/aix513/d4/KD4/lib/kd4dcagent.jar" export WEBLOGIC_CLASSPATH
v On Solaris operating systems, edit the commEnv.sh script:

WEBLOGIC_CLASSPATH= "${JAVA_HOME}/lib/tools.jar... ${CLASSPATHSEP}/candle/sol283/d4/KD4/lib/kd4dcagent.jar" export WEBLOGIC_CLASSPATH
162
Installation Guide
To modify the Classpath for a specific BEA WebLogic Server domain, edit the setDomainEnv.cmd or setDomainEnv.sh script, in the \bin directory for the domain, and prepend the kd4dcagent.jar file onto the PRE_CLASSPATH environment variable. 3. Start the BEA WebLogic Server, following the instructions in the product documentation. You can use the Administration Console or the BEA WebLogic Administrative utility.
Enabling data collection in a single server environment

After you complete the previous steps to prepare for client side and server side installation, enable the environment for data collection using either the Data Collector Configuration Utility or by running the KD4configDC command. Before enabling data collection, do these initial steps as needed: 1. On supported HP-UX operating systems, switch to the Korn shell (/usr/bin/ksh) interactive command interpreter. 2. Run a script to set up all the environment variables and Java options before enabling the environment for data collection. v For Windows operating systems:
<DOMAIN_HOME>\setDomainEnv.cmd (or setEnv.cmd)
v For Linux, AIX, HP-UX, or Solaris operating systems:

. /<DOMAIN_HOME>/setDomainEnv.sh (or setEnv.sh)
Using the Data Collector Configuration Utility

Using the Data Collector Configuration Utility, complete these steps: 1. Start the Data Collector Configuration Utility in either the default graphical user interface mode, in console mode, or in silent mode. See Running the Data Collector Configuration Utility on page 130 for more information. 2. Select the option to configure BEA WebLogic Server. 3. If the BEA_HOME system variable is not set, you are instructed to exit the configuration utility, run the setEnv script, and then run the utility again. 4. You are prompted to confirm that you have modified either the common environment (commEnv.cmd or commEnv.sh) or the domain specific environment (setDomainEnv.cmd or setDomainEnv.sh) script to include the kd4dcagent.jar in the class path, and that the BEA WebLogic server should have been restarted. Confirm that these steps have been completed, and proceed with configuration.
163
Figure 47. Confirm that you have included kd4dcagent.jar in BEA application server classpath.
5. Select the option to enable data collection. 6. If you are using the optional Apache Axis support for the BEA WebLogic environment, select the check box to Configure Apache Axis WebServices Engine. Otherwise verify that this check box is cleared. 7. Specify the Web address of the BEA WebLogic Server (for example, t3://localhost:7001, where t3 and t3s are proprietary BEA protocols).
Figure 48. Select the enable option and specify the URL for the BEA WebLogic server.
8. Specify the BEA WebLogic user name and password with the authority to configure applications.
164
Installation Guide
Figure 49. Specifying the BEA WebLogic user name and password
9. Wait for the configuration utility to complete the operation. 10. Repeat these steps as needed to enable data collection for other Web services implementations. 11. Exit the utility. Restart the BEA WebLogic Server: After enabling data collection on your BEA WebLogic Server, stop and restart the server to complete the configuration.
Using the KD4configDC command

Using the KD4configDC command, run the following command from a command prompt window (see Running the KD4configDC script on page 147 for more information):
KD4configDC -enable -env 3 <URL> <userID> <password> [-axis]
In this command, these options and parameters are passed: <URL> The Web address of the BEA WebLogic Server (for example, t3://localhost:7001). t3 and t3s are proprietary BEA protocols. <userID> A valid WebLogic user name with the authority to configure applications. <password> A valid password associated with the specified WebLogic user name. axis This is an optional parameter that, when included in the command, enables the Apache Axis version of the data collector in the BEA WebLogic Server environment.
Examples:
KD4configDC -enable -env 3 "t3://localhost:7001" KD4configDC -enable -env 3 "t3://localhost:7001" weblogic weblogic weblogic weblogic -axis
Restart the BEA WebLogic Server: After enabling data collection on your BEA WebLogic Server, stop and restart the server to complete the configuration.
165
Disabling data collection in a single server environment

To disable data collection in the BEA WebLogic Server, environment, run either the Data Collector Configuration Utility or the KD4configDC command. Before disabling data collection, do these initial steps as needed: 1. On supported HP-UX operating systems, switch to the Korn shell (/usr/bin/ksh) interactive command interpreter. 2. Run a script to set up all the environment variables and Java options before disabling the environment for data collection. v For Windows operating systems:
v For Linux, AIX, HP-UX, or Solaris operating systems:


Using the Data Collector Configuration Utility, complete these steps: 1. Start the Data Collector Configuration Utility in either the default graphical user interface mode, in console mode, or in silent mode. See Running the Data Collector Configuration Utility on page 130 for more information. 2. Select the option to configure BEA WebLogic Server. 3. Select the option to disable data collection. 4. Specify the Web address of the BEA WebLogic Server (for example, t3://localhost:7001, where t3 and t3s are proprietary BEA protocols). 5. If you are using the optional Apache Axis support for the BEA WebLogic environment, select the check box to Configure Apache Axis WebServices Engine. Otherwise verify that this check box is cleared. 6. Specify the user name and password with the authority to configure applications. 7. Wait for the configuration utility to complete the operation. 8. Repeat these steps as needed to disable data collection for other Web service implementations. 9. Exit the utility.

Using the KD4configDC command, run the following command from a command prompt window (see Running the KD4configDC script on page 147 for more information):
KD4configDC -disable -env 3 <URL> <userID> <password> [-axis]
In this command, these options and parameters are passed: <URL> The Web address of the BEA WebLogic Server (for example, t3://localhost:7001). t3 and t3s are proprietary BEA protocols. <userID> A valid WebLogic user name with the authority to configure applications. <password> A valid password associated with the specified WebLogic user name.
166
Installation Guide
axis
This is an optional parameter that, when included in the command, disables the Apache Axis version of the data collector in the BEA WebLogic Server environment.
Examples:
KD4configDC -disable -env 3 "t3://localhost:7001" KD4configDC -disable -env 3 "t3://localhost:7001" weblogic weblogic weblogic weblogic -axis
Restart the BEA WebLogic Server: After disabling data collection on your BEA WebLogic Server, stop and restart the server to complete the configuration.
Enabling data collection in a BEA WebLogic multi-server environment

A typical BEA WebLogic domain contains one administrative server and one or more managed servers. To enable data collection in the domain, you need to enable data collection on only the administrative server, and then restart the managed servers for the configuration to take effect. To enable data collection on BEA WebLogic servers in a domain, complete the following steps: 1. If you have not already done so, install the IBM Tivoli Composite Application Manager for SOA monitoring agent on each BEA WebLogic managed and administrative server computer. 2. Modify the BEA application server classpath on all of the affected computer systems in the domain, using the procedure described in BEA server side configuration on page 162. 3. Before enabling the environment for data collection on supported HP-UX operating systems, switch to the Korn shell (/usr/bin/ksh) interactive command interpreter. 4. Run a script to set up all of the environment variables and Java options before enabling the environment for data collection. v For Windows operating systems:
v For Linux, AIX, or HP-UX, Solaris operating systems:

5. Ensure that all of the servers in the cluster, including the administrative server, are running. 6. Enable the environment for data collection using either the Data Collector Configuration Utility or by running the KD4configDC command. v Using the Data Collector Configuration Utility: Complete these steps: a. Start the Data Collector Configuration Utility in either the default graphical user interface mode, in console mode, or in silent mode. See Running the Data Collector Configuration Utility on page 130 for more information. b. Select the option to configure BEA WebLogic Server. c. If the BEA_HOME system variable is not set, you are instructed to exit the configuration utility, run the setEnv script, and then run the utility again. d. You are prompted to confirm that you have modified either the common environment (commEnv.cmd or commEnv.sh) or domain specific environment (setDomainEnv.cmd or setDomainEnv.sh) script to include the kd4dcagent.jar in the class path, and that the BEA WebLogic
167
administrative server should have been restarted. Confirm that these steps have been completed, and proceed with configuration. e. Select the option to enable data collection. f. Specify the Web address of the BEA WebLogic administrative server (for example, t3://localhost:7001, where t3 and t3s are proprietary BEA protocols). g. If you are using the optional Apache Axis support for the BEA WebLogic environment, select the check box to Configure Apache Axis WebServices Engine. Otherwise verify that this check box is cleared. h. Specify the user name and password with the authority to configure applications. i. Wait for the configuration utility to complete the operation. j. Exit the utility. v Using KD4configDC: Run the following command from a command prompt window (see Running the KD4configDC script on page 147 for more information):
KD4configDC.sh enable env 3 <URL> <userID> <password> [axis]
<URL> The Web address of the BEA WebLogic Server (for example, t3://localhost:7001). t3 and t3s are proprietary BEA protocols. <userID> A valid WebLogic user name with the authority to configure applications. <password> A valid password associated with the specified WebLogic user name. axis This is an optional parameter that, when included in the command, enables the Apache Axis version of the data collector in the BEA WebLogic Server environment.
weblogic weblogic weblogic weblogic -axis
Example:
KD4configDC -enable -env 3 "t3://localhost:7001" KD4configDC -enable -env 3 "t3://localhost:7001"
7. Restart the servers: After enabling data collection, stop and restart all of the servers in the cluster, including the administrative server, to complete the configuration.
Disabling data collection in a BEA WebLogic multi-server environment

A typical BEA WebLogic domain contains one administrative server and one or more managed servers. To disable the AXIS data collector in the domain, you only need to disable the AXIS data collector on the administrative server and then restart the managed servers for the change to take effect. This procedure assumes that the IBM Tivoli Composite Application Manager for SOA monitoring agent is already installed on each BEA WebLogic server computer. To disable the AXIS data collector on WebLogic servers in a domain, complete the following steps: 1. Before disabling the environment for data collection on supported HP-UX operating systems, switch to the Korn shell (/usr/bin/ksh) interactive command interpreter.
168
Installation Guide
2. Run a script to set up all of the environment variables and Java options before disabling the environment for data collection. v For Windows operating systems:
v For Linux, AIX, or HP-UX, Solaris operating systems:

3. Ensure that all of the servers in the cluster, including the administrative server, are running. 4. Run either the Data Collector Configuration Utility or the KD4configDC command. v Using the Data Collector Configuration Utility: Complete these steps: a. Start the Data Collector Configuration Utility in either the default graphical user interface mode, in console mode, or in silent mode. See Running the Data Collector Configuration Utility on page 130 for more information. b. Select the option to configure BEA WebLogic Server. c. Select the option to disable data collection. d. Specify the Web address of the BEA WebLogic administrative server (for example, t3://localhost:7001, where t3 and t3s are proprietary BEA protocols). e. If you are using the optional Apache Axis support for the BEA WebLogic environment, select the check box to Configure Apache Axis WebServices Engine. Otherwise verify that this check box is cleared. f. Specify the user name and password with the authority to configure applications. g. Wait for the configuration utility to complete the operation. h. Exit the utility. v Using KD4configDC: Run the following command from a command prompt window (see Running the KD4configDC script on page 147 for more information):
KD4configDC -disable -env 3 <URL> <userID> <password> [-axis]
<URL> The Web address of the BEA WebLogic administrative server (for example, t3://localhost:7001). t3 and t3s are proprietary BEA protocols. <userID> A valid WebLogic user name with the authority to configure applications. <password> A valid password associated with the specified WebLogic user name. axis This is an optional parameter that, when included in the command, disables the Apache Axis version of the data collector in the BEA WebLogic Server environment. Example:
KD4configDC -disable -env 3 "t3://localhost:7001" KD4configDC -disable -env 3 "t3://localhost:7001" weblogic weblogic weblogic weblogic -axis
5. Restart the servers: After disabling data collection, stop and restart all of the servers in the cluster, including the administrative server, to complete the configuration.
169
Apache Axis Limitations

The Apache Axis version of the data collector in the BEA WebLogic Server environment has these limitations: v The Axis data collector supports monitoring services in Axis SOAP engines that are installed with basic installation (Web application) and advanced installation (adding Axis to an existing enterprise application) procedures. ITCAM for SOA does not support the enabling of monitoring for customized installations. See the Axis documentation for more details. v The Axis data collector monitors both requester side and provider side service events, but only within supported application server runtime environments. Stand-alone client Axis applications are not supported. v When monitoring both the Axis SOAP engine and the native SOAP engine of BEA WebLogic application servers, all services are displayed in the Tivoli Enterprise Portal as though they are running in the same runtime environment. There is no way to tell from the Tivoli Enterprise Portal which services are deployed to the Axis SOAP engine and which are deployed to the native SOAP engine.
The port number attribute for the application server is always displayed with a value of 0 in the ITCAM for SOA attribute groups when running on BEA WebLogic v9.2. If you have more than one server instance using the same name, and they are on the same computer, the data collected and processed for these instances is displayed as if they all came from a single server. See the documentation library and online help information provided with IBM Tivoli Composite Application Manager for SOA for information on starting and stopping data collectors, configuring monitoring and filtering settings, understanding workspaces, views, Take Action commands, and other features that help you monitor and manage your services in the BEA WebLogic application server runtime environment.
170
Installation Guide
Chapter 9. Configuring data collection: JBoss

This section describes the support for JAX-RPC services running in the JBoss Java 2 Enterprise Edition (J2EE) version 4.0.3 application server runtime environment.

To enable JBoss applications for data collection, complete the following steps: 1. Optionally stop the JBoss application server before you enable the application for the data collector. You do not have to stop the application server before enabling the environment for data collection, but the data collector does not begin to collect data until after the JBoss application server is stopped and restarted. You might prefer to stop and restart the JBoss application server during off-shift hours. Refer to your JBoss documentation for the specific procedure to stop the JBoss application server. 2. Enable data collection using either the Data Collector Configuration Utility or by running the KD4configDC command. v Using the Data Collector Configuration Utility: Complete these steps:
Figure 50. Enabling data collection on JBoss
a. Start the Data Collector Configuration Utility in either the default graphical user interface mode, in console mode, or in silent mode. See Running the Data Collector Configuration Utility on page 130 for more information. b. Select the option to configure JBoss. c. Select the option to enable data collection. d. Specify the JBoss data collector server configuration profile. A value of default is already provided. You can either accept that value, or specify all, or the name of a customized configuration profile that you have previously created. e. Specify the JBoss application server installation directory. For example, on Windows operating systems, C:\Program Files\jboss. f. Wait for the configuration utility to complete the operation. g. Exit the utility.
171
v Using the KD4configDC command: When there are multiple server instances within the same JBoss application server runtime environment, you must run the KD4configDC command for each instance. Enter the KD4configDC command from a command prompt window (see Running the KD4configDC script on page 147 for more information): a. Depending on your operating system, navigate to <ITCAM4SOA_Home>/ KD4/bin directory location. See The IBM Tivoli Composite Application Manager for SOA home directory on page xix for information on resolving the value of <ITCAM4SOA_Home>. b. Enter the following command: For supported Windows operating systems:
KD4configDC.bat -enable -env 4 <server configuration> <JBoss_Home>
For supported AIX, Solaris, HP-UX, and Linux operating systems:

KD4configDC.sh -enable -env 4 <server configuration> <JBoss_Home>
The following parameters are specified in these commands: <server configuration> is the type of JBoss application server to be configured. These are the valid values: default This configuration type contains everything needed to run a standalone J2EE server. all This configuration type starts all available services, including the RMI/IIOP and clustering services, and the services deployer, which are not loaded in the default configuration. A third default configuration type, minimal, is not supported, because this configuration does not include support for services.
You can also create your own server configuration type by modifying the default or all types, or mixing and matching capabilities from either or both, and saving it as a new server configuration type name. Then specify that new server configuration name in the KD4configDC command. <JBoss_Home> is the directory path name where the JBoss application server is installed, for example, C:\JBoss on a Windows operating system (note that if this path name contains a blank space, the entire path is surrounded with quotation marks). If you have this directory path defined in the environment variable, JBOSS_HOME, then this parameter is optional. Examples: KD4configDC.bat -enable -env 4 default In this example, the default server configuration is used, and the JBOSS_HOME environment variable is used to specify the JBoss base installation directory. The command completes with a return code of 0. KD4configDC.bat -enable -env 4 all C:\JBoss In this example, the all server configuration type is specified to enable monitoring for the JBoss configuration that has all services started. The JBoss base installation directory is explicitly specified, and because there are no blank spaces in the path, the argument can be specified without surrounding quotation marks. KD4configDC.bat -enable -env 4 myConfig In this example, the user-customized server configuration type myConfig is specified, and the JBOSS_HOME environment variable is used by default to specify the JBoss base installation directory.
172
Installation Guide
KD4configDC.bat -enable -env 4 default "C:\App Servers\JBoss" In this example, the JBoss base installation directory is specified explicitly, and because there is a blank space in the path, the argument is surrounded by quotation marks. KD4configDC.sh -enable -env 4 all /opt/IBM/JBoss This example is for running KD4configDC on a supported AIX, Solaris, HP-UX, or Linux operating systems. 3. Restart the JBoss application server (refer to your JBoss documentation for the specific procedure). The data collector becomes active after the JBoss application server is restarted. You only need to enable the JBoss application for the data collector once in the JBoss application server runtime environment. If you add new applications to the environment, the data collector begins monitoring the new applications automatically.

To disable data collection in the JBoss application server runtime environment, either use the Data Collector Configuration Utility or run the KD4configDC command. v Using the Data Collector Configuration Utility: Complete these steps: 1. Run the Data Collector Configuration Utility in either the default graphical user interface mode, in console mode, or in silent mode. See Running the Data Collector Configuration Utility on page 130 for more information. 2. Select the option to configure JBoss. 3. Select the option to disable data collection. 4. Specify the JBoss data collector server configuration profile. A value of default is already provided. You can either accept that value, or specify all, or the name of a customized configuration profile that you have previously created. 5. Specify the JBoss application server installation directory. For example, on Windows operating systems, C:\Program Files\JBoss. 6. Wait for the configuration utility to complete the operation. 7. Exit the utility. v Using the KD4configDC command: When there are multiple server instances within the same JBoss application server runtime environment, you must run the KD4configDC command for each instance. Enter the KD4configDC command from a command prompt window (see Running the KD4configDC script on page 147 for more information): 1. Depending on your operating system, navigate to <ITCAM4SOA_Home>/ KD4/bin directory location. See The IBM Tivoli Composite Application Manager for SOA home directory on page xix for information on resolving the value of <ITCAM4SOA_Home>. 2. Enter the following command: For supported Windows operating systems:
KD4configDC.bat -disable -env 4 <server configuration> <JBoss_Home>
For supported AIX, Solaris, HP-UX, and Linux operating systems:

KD4configDC.sh -disable -env 4 <server configuration> <JBoss_Home>
3. After the command completes, restart the JBoss application server.
Chapter 9. Configuring data collection: JBoss
173
The JBoss data collector continues to collect data until after the JBoss application server is restarted.
As you enable and use data collection in the JBoss environment, keep in mind that if you attempt to enable or disable the application for data collection multiple times in a row (for example, an enable followed by another enable), only the first invocation takes effect. See the online help information and the IBM Tivoli Composite Application Manager for SOA Users Guide for information on configuring monitoring and filtering settings, understanding workspaces, views, Take Action commands, and other features that help you monitor and manage your services in the JBoss application server runtime environment.
174
Installation Guide
Chapter 10. Configuring data collection: CICS Transaction Server

IBM Customer Information Control System Transaction Server (CICS TS) running on the z/OS operating system acts as both an SOA server and client. This version of CICS TS features the following capabilities, which make it more feasible to implement CICS TS services using SOA in your production environment: v Multiple message handlers per CICS region v Multiple pipelines v v v v Use of either HTTP transport or WebSphere/MQ transport Support for simple object access protocol (SOAP) version 1.2 New resources to ease configuration of services New APIs to manage SOA requests
The IBM Tivoli Composite Application Manager for SOA CICS TS data collector monitors service flows to and from a CICS TS region, and provides the same services management and availability information that IBM Tivoli Composite Application Manager for SOA currently provides for other application server runtime environments. Services data is presented in the Tivoli Enterprise Portal using the usual workspaces and views associated with IBM Tivoli Composite Application Manager for SOA. Running within the CICS TS region, IBM Tivoli Composite Application Manager for SOA acts as an SOA request monitor, intercepting incoming and outgoing SOA requests, rejecting incoming and outgoing messages according to user-configured filtering criteria, storing message information, metrics and rejection information into log files for later processing, and controlling the amount of monitoring and message rejection that is performed. These functions are accomplished with minimal effect on the function being monitored as well as the overall performance of the CICS region. Because message correlation is not supported in this data collector, services data collected in the CICS TS environment is not supported by the IBM Web Services Navigator tool. For more information about configuring the IBM Tivoli Composite Application Manager for SOA CICS TS data collector in the z/OS environment, see the Configuring IBM Tivoli Composite Application Manager for SOA on z/OS guide.
175
176
Installation Guide
Chapter 11. Configuring data collection: SAP NetWeaver

This section describes the support for monitoring of services flows in the SAP NetWeaver version 6.40 SR9 (or later service release) environment. Depending on the types of services applications you plan to monitor, you might need to enable or disable your SAP NetWeaver applications for the data collector using these different procedures: v For a server side application or for a standalone (running as a Java application) client application, you need to run only the Data Collector Configuration Utility or the KD4configDC command to enable or disable the SAP NetWeaver application environment for data collection. v For a deployable (running on a J2EE container) client application, you must manually modify the client code as described in the following sections. Manually enabling applications with open-source projects: The data collector for SAP NetWeaver includes third party software (also referred to as excluded components) as a part of monitoring services traffic in the SAP NetWeaver environment. See the license files in your appropriate language for more information on this third party software. These files are located in the <ITM_Home>\license\ D4V710 directory on the computer systems where the data collector support for IBM Tivoli Monitoring is installed. If any of the applications in your server use any of these excluded components, you should manually enable your applications as described in the sections that follow. As with any change, back up your application prior to making this change, and test it thoroughly afterward. If this is not a concern for your installed applications, use the Data Collector Configuration Utility or the KD4configDC command to enable all of the applications in your server. These methods, however, cannot enable services client calls made from within another service. These calls must be enabled manually as described in the sections that follow in order to be monitored. You run the Data Collector Configuration Utility or the KD4configDC command once to enable all SAP NetWeaver applications for data collection, and the data collector monitors all of the SAP NetWeaver related applications. If you add more SAP NetWeaver applications to the environment, you must run the Data Collector Configuration Utility or the KD4configDC command again to enable these new applications for data collection. Applications that are already enabled are not affected. Standalone client restriction: A supported SAP NetWeaver standalone client application must include an instance of the implementation for com.sap.engine.services.webservices.jaxrpc.wsdl2java.ServiceBase. To create an instance of java.rmi.Remote,javax.xml.rpc.Stub, the standalone client application must call getPort() or getLogicalPort() for the instance of com.sap.engine.services.webservices.jaxrpc.wsdl2java.ServiceBase. Do not use new to create the instance of java.rmi.Remote,javax.xml.rpc.Stub. User permission to write to log files: After enabling the data collector to monitor your SAP applications, ensure that the user ID that you use to start the SAP server has permission to write into the \KD4\logs directory.
177

There are several different patterns through which services components can operate on your SAP NetWeaver application server, and each is configured slightly differently. Use the following sections to identify the correct mechanisms for your applications, and choose whether to use the Data Collector Configuration Utility or the KD4configDC command to enable or disable data collection, or whether you should do so manually: v All server applications under a SAP system ID v A server application not located under a SAP system ID on page 179 v A standalone client application not under a SAP system ID on page 181 v A Web services client packaged in its own JAR file on page 183 v A deployable client application on page 183 File changes in the SAP NetWeaver applications directory: If you use the Data Collector Configuration Utility or the KD4configDC command to enable or disable data collection for your application server, certain changes are made to files in your SAP applications directory, and the undeploy operation of the SAP administration utilities might not remove all of those changed files. To ensure that upgraded versions of your applications deploy successfully, check the directory for each application after undeploying and delete any residual files that you might not have been expecting. You must enable upgraded applications for data collection again using the Data Collector Configuration Utility or the KD4configDC command if they were not manually enabled during the upgrade.
All server applications under a SAP system ID

If you have a number of services applications under a common SAP system ID, you can enable all of them for data collection at the same time. You can specify the SAP home directory and the SAP system ID to confirm that the directory corresponding to the specified SAP system ID exists under the specified home directory. All services applications that are found under the SAP system ID are enabled. This method also performs some error checking to assist you. To enable data collection for all server applications under a specific SAP system ID, complete these steps: v Using the Data Collector Configuration Utility: 1. Stop the SAP NetWeaver application server following the procedures in your SAP NetWeaver documentation. 2. Run the Data Collector Configuration Utility (see Running the Data Collector Configuration Utility on page 130):
178
Installation Guide
Figure 51. Enabling data collection for all servers under a SAP NetWeaver system ID
a. Select the SAP NetWeaver runtime environment. b. Select the All server side Web Services applications installed in SAP server option. c. Select the option to enable data collection. d. Specify the SAP system ID, for example, j2e. e. Specify the directory path for the SAP NetWeaver home directory, typically /usr/sap or C:\usr\sap, though it might reside on any drive. f. Wait for the configuration utility to complete the operation. g. Exit the utility. 3. Restart the SAP NetWeaver application server following the procedures in your SAP NetWeaver documentation. v Using the KD4configDC command: 1. Stop the SAP NetWeaver application server following the procedures in your SAP NetWeaver documentation. 2. Run the KD4configDC command with the -sid parameter to enable for data collection all of the services applications found under a commons SAP system ID. Be sure to specify the SAP NetWeaver home directory, and the SAP system ID (see Enabling data collection using the KD4configDC command on page 184). 3. Restart the SAP NetWeaver application server following the procedures in your SAP NetWeaver documentation.
A server application not located under a SAP system ID

To enable data collection for a server application not located under a SAP system ID, complete these steps: v Using the Data Collector Configuration Utility: 1. Stop the SAP NetWeaver application server following the procedures in your SAP NetWeaver documentation. 2. Run the Data Collector Configuration Utility (see Running the Data Collector Configuration Utility on page 130):
179
Figure 52. Enabling data collection on a SAP NetWeaver server side application
a. Select the SAP NetWeaver runtime environment. b. Select the Server side Web Services application option. c. Select the option to enable data collection. d. Specify the directory path for the location of the services application to be monitored. e. Wait for the configuration utility to complete the operation. f. Exit the utility. 3. Restart the SAP NetWeaver application server following the procedures in your SAP NetWeaver documentation. v Using the KD4configDC command: 1. Stop the SAP NetWeaver application server following the procedures in your SAP NetWeaver documentation. 2. Run the KD4configDC command with the -sapappsdir parameter to enable the application for data collection (see Enabling data collection using the KD4configDC command on page 184). 3. Restart the SAP NetWeaver application server following the procedures in your SAP NetWeaver documentation. v Enabling data collection manually: 1. Add the kd4dcagent.jar and ibm-jaxrpc-client.jar files to your application, typically in the /WEB-INF/lib directory. If your application uses a Sun distribution of Java 1.4.2, you must also add xercesImpl.jar and xml-apis.jar. All of these jar files are provided in the KD4/lib directory. 2. Add the IBM Tivoli Composite Application Manager for SOA servlet filter to the web.xml file for the application, similar to the following example:
<?xml version="1.0" encoding="UTF-8"?> <web-app> <display-name>SayHelloWS_Config1.war</display-name> <servlet> <servlet-name>SayHelloWS_Config1_SoapServlet</servlet-name> <display-name>SayHelloWS_Config1_SoapServlet</display-name> <servlet-class>SoapServlet</servlet-class> <load-on-startup>0</load-on-startup> </servlet> <servlet-mapping> <servlet-name>SayHelloWS_Config1_SoapServlet</servlet-name> <url-pattern>/*</url-pattern>
180
Installation Guide
</servler-mapping> <session-config> <session-timeout>1</session-timeout> </session-config> <filter> <filter-name>KD4ServletFilter</filter-name> <filter-class>com.ibm.management.soa.agent.sap.WebServiceFilter </filter-class> </filter> <filter-mapping> <filter-name> KD4ServletFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping></web-app>
3. Install your upgraded application into your application server.
A standalone client application not under a SAP system ID

To enable data collection for a standalone client application not located under a SAP system ID, complete these steps: v Using the Data Collector Configuration Utility: 1. Run the Data Collector Configuration Utility (see Running the Data Collector Configuration Utility on page 130):
Figure 53. Enabling data collection on a SAP NetWeaver standalone client side application
a. Select the SAP NetWeaver runtime environment. b. Select the Client side standalone Web Services application option. c. Select the option to enable data collection. d. Specify the directory path for the location of the services application to be monitored. e. Wait for the configuration utility to complete the operation. f. Exit the utility. 2. Modify the classpath used to launch the standalone application to include the kd4dcagent.jar file, which is provided in the /KD4/lib directory. 3. Run the application. v Using the KD4configDC command: 1. Run the KD4configDC command with the -clientappsdir parameter to enable the application for data collection (see Enabling data collection using the KD4configDC command on page 184).
181
2. Modify the classpath used to launch the standalone application to include the kd4dcagent.jar file, which is provided in the /KD4/lib directory. 3. Run the application. v Enabling data collection manually: 1. Modify the classpath used to launch the standalone application to include the kd4dcagent.jar file, which is provided in the /KD4/lib directory: 2. Update the lports_1.xml file to define the feature needed for the IBM Tivoli Composite Application Manager for SOA protocol, similar to the following example (see the text in bold type):
<?xml version="1.0" encoding="UTF-8"?> <LogicalPorts Name='CalculatorServer' InterfaceName='test.proxy.CalculatorServer'> <LogicalPort Name='Config1Port_Document' Endpoint='http://tive10:50000/CalculatorServer /Config1?style=document' BindingName='Config1Binding' BindingUri='urn:CalculatorServerWsd/Config1/document' BindingImplementation='SOAP 1.1 HTTP Binding with Attachments' StubName='test.proxy.Config1BindingStub' Default='true' InterfaceName='test.proxy.CalculatorServerViDocument' Original='true' Valid='true'> <globalFeatures> <Feature Name='http://www.sap.com/webas/630/soap/features /authentication' Provider='SecurityProtocol' Original='true'> <Property Name='AuthenticationLevel' Value='None'> </Property> <Property Name='AuthenticationMechanism' Value='None'> </Property> </Feature> <Feature Name='http://www.sap.com/webas/630/soap/features /transportguarantee' Original='true'> <Property Name='Level' Value='No'></Property> </Feature> <Feature Name='http://www.sap.com/webas/630/soap/features/headers/' Provider='SoapHeadersProtocol' Original='false'> </Feature> <Feature Name='http://www.sap.com/webas/630/soap/features/session/' Provider='SessionProtocol' Original='false'> <Property Name='SessionMethod' Value='httpCookies'> </Property> </Feature> <Feature Name=' http://www.ibm.com/tivoli/itcam4soa//' Provider='KD4Protocol' Original='false'> <Property Name='portName' Value='Config1Port_Document'> </Property> </Feature> </globalFeatures> <localFeatures> <Operation Name='add'> </Operation> <Operation Name='divide'> </Operation> <Operation Name='multiply'> </Operation> <Operation Name='subtract'> </Operation> </localFeatures> </LogicalPort> </LogicalPorts>
3. Update the protocols.txt file to declare the IBM Tivoli Composite Application Manager for SOA protocol, similar to the following example (see the text in bold type):
182
Installation Guide
#Default Protocol implementations #Fri Nov 18 13:54:53 GMT+08:00 2005 SessionProtocol=com.sap.engine.services.webservices.jaxrpc .wsdl2java.features.builtin.SessionProtocol MessageIdProtocol=com.sap.engine.services.webservices.jaxrpc .wsdl2java.features.builtin.MessageIdProtocol SecurityProtocol=com.sap.security.core.client.ws.SecurityProtocol SoapHeadersProtocol=com.sap.engine.services.webservices.jaxrpc .wsdl2java.features.builtin.SoapHeadersProtocol KD4Protocol= com.ibm.management.soa.agent.sap.ITCAMClientProtocol
4. Deploy your upgraded application.
A Web services client packaged in its own JAR file

To enable data collection for a Web services client packaged in its own JAR file but being used by a WAR, complete these steps: 1. Modify the classpath for the application to include the kd4dcagent.jar file. This jar is provided in the /KD4/lib directory. 2. Do one of the following tasks to enable data collection: v Using the Data Collector Configuration Utility: a. Run the Data Collector Configuration Utility (see Running the Data Collector Configuration Utility on page 130) b. c. d. e. Select the SAP NetWeaver runtime environment. Select the Client side standalone Web Services application option. Select the option to enable data collection. Specify the directory path for the location of the services application to be monitored. Because your standalone client application is a .jar file, be sure to specify the full directory path for the location of the .jar file.
f. Wait for the configuration utility to complete the operation. g. Exit the utility. v Using the KD4configDC command: Run the KD4configDC command with the -clientappsdir parameter to enable the application for data collection (see Enabling data collection using the KD4configDC command on page 184). Because your standalone client application is a .jar file, be sure to specify the full directory path for the location of the .jar file. v Enabling data collection manually: Add the IBM Tivoli Composite Application Manager for SOA protocol to the appropriate deployment descriptors as described in manual steps 2 on page 182 and 3 on page 182 for the standalone client application. 3. Install your upgraded application into your application server.
A deployable client application

To enable data collection for a deployable client application such as a JSP or another service, complete these steps: 1. You do not need to stop the SAP NetWeaver application server if it is already running. 2. Manually add the kd4dcagent.jar file to the \lib directory for the application. 3. Manually modify application-j2ee-engine.xml, adding the following reference shown in bold text:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE application-j2ee-engine SYSTEM "application-j2ee-engine.dtd"> <application-j2ee-engine> <reference reference-type="hard">
183
<reference-target provider-name="sap.com" target-type="application">MathDepProxy</reference-target> </reference> <reference reference-type="hard"> <reference-target provider-name="sap.com" target-type="library">sapxmltoolkit</reference-target> </reference> <provider-name>sap.com</provider-name> <fail-over-enable mode="disable"/> </application-j2ee-engine>
4. Manually modify the application code to add the ITCAMClientProtocol protocol to the protocol list for each of your client stubs. Following is an example of how to modify a deployable client side application:
// initialization of the web service client ..... // create a deployable proxy object. SystemDetail service = new SystemDetailImpl(); SystemDetailViDocument port = service.getLogicalPort(); BaseGeneratedStub stub = (BaseGeneratedStub)port; ProtocolList list = stub._getGlobalProtocols(); ITCAMClientProtocol protocol = new ITCAMClientProtocol(); list.add(protocol); // call web service .....
5. Install your upgraded application into your application server.
Enabling data collection using the KD4configDC command

Run the KD4configDC command to enable data collection for your SAP NetWeaver application. 1. Enter the following command: v For supported Windows operating systems:
KD4configDC.bat enable env 6 {sid <home> <sid> | sapappsdir <apps_dir> | clientappsdir <apps_dir>}
v For supported AIX, Solaris, HP-UX, and Linux operating systems:

KD4configDC.sh enable env 6 {sid <home> <sid> | sapappsdir <apps_dir> | clientappsdir <apps_dir>}
The following parameters are specified in these commands: -enable Causes the command to enable the application for data collection. -env 6 Defines the environment to be enabled as SAP NetWeaver. sid <home> <sid> For this parameter, <home> is the SAP home directory, typically /usr/sap or C:\usr\sap, but it could reside on any drive. The <sid> argument is the SAP system ID. Both of these arguments are used to confirm that the directory corresponding to the specified SID exists under the specified home. All services applications that are found under the SID are enabled. This is the preferred option to specify, because it does the same tasks as sapappsdir parameter, and some error checking is also performed to assist you. -sapappsdir <apps_dir> Specifies that the directory path specified by <apps_dir> is the location
184
Installation Guide
of the services application to be monitored. Use this parameter for a server side application if your application directory is not located under the SID. -clientappsdir <apps_dir> Specifies that the directory path specified by <apps_dir> is the location of the services application to be monitored. Use this parameter for a standalone client application. There is no default path for the clientappsdir parameter. If your standalone client application is a .jar file, be sure to specify the full directory path for the location of the .jar file. See the examples that follow. <apps_dir> Specifies the directory path of the services application to be monitored. Examples: v KD4configDC.bat -enable -env 6 -sid C:\usr\sap j2e In this example, the C:\usr\sap SAP home directory is specified, along with the system ID j2e. All services applications found under this combination of home directory and SID are enabled for the data collector. v KD4configDC.bat -enable -env 6 -sapappsdir /appl1 In this example, the services application directory location /appl1 is specified. This might be for enabling a server side or deployable client side application for the data collector. v KD4configDC.bat -enable -env 6 -clientappsdir /appl2 In this example, the services application directory location /appl2 is specified. This command enables the standalone client side application for the data collector. v KD4configDC.bat -enable -env 6 -sapappsdir
"C:\SAP\My Sap\j2e\JC000\j2ee\cluster\server0\apps"
In this example, the services application directory is not located under the SID home, and is specified fully qualified. This example also shows the directory path surrounded by quotation marks, which are needed if the path contains one or more blank characters. v KD4configDC.sh -enable -env 6 -clientappsdir /opt/IBM/appsdir This example is for running KD4configDC on a supported AIX, Solaris, HP-UX, or Linux operating systems. v KD4configDC.sh -enable -env 6 -clientappsdir
/usr/sap/Customer/EnterpriseSTDClientProxy.jar
In this example, the standalone client application is a .jar file, so the full directory path location of the file is specified.

To disable the SAP NetWeaver application for the data collector, depending on the type of application, complete the following steps: v For all server applications under a common SAP system ID: 1. Stop the SAP NetWeaver application server following the procedures in your SAP NetWeaver documentation. 2. Disable data collection for the SAP NetWeaver environment by running either the Data Collector Configuration Utility or the KD4configDC command. Using the Data Collector Configuration Utility: a. Select the SAP NetWeaver runtime environment.
185
b. Select the All server side Web Services applications installed in SAP server option. c. Select the option to disable data collection. d. Specify the SAP system ID. e. Specify the SAP home directory. f. Wait for the configuration utility to complete the operation. g. Exit the utility. Using the KD4configDC command: See Disabling data collection using the KD4configDC command on page 187). Specify the sid parameter along with the SAP home directory and SAP system ID. 3. Restart the SAP NetWeaver application server following the procedures in your SAP NetWeaver documentation. v For a server application: 1. Stop the SAP NetWeaver application server following the procedures in your SAP NetWeaver documentation. 2. Disable data collection for the SAP NetWeaver environment by running either the Data Collector Configuration Utility or the KD4configDC command. Using the Data Collector Configuration Utility: a. Select the SAP NetWeaver runtime environment. b. Select the Server side Web Services application option. c. Select the option to disable data collection. d. Specify the directory path for the location of the services application to be monitored. e. Wait for the configuration utility to complete the operation. f. Exit the utility. Using the KD4configDC command: See Disabling data collection using the KD4configDC command on page 187. Specify the sapappsdir parameter. 3. Restart the SAP NetWeaver application server following the procedures in your SAP NetWeaver documentation. If you manually enabled the server application for the data collector: Remove the kd4dcagent.jar and ibm-jaxrpc-client.jar files from your application classpath, along with the xercesImpl.jar and xml-apis.jar files if your application uses a Sun distribution of Java 1.4.2. Remove the changes you made to the web.xml file during the manual enable process. Then reinstall your application into the application server. v For a standalone client application: 1. Disable data collection for the SAP NetWeaver environment by running either the Data Collector Configuration Utility or the KD4configDC command. Using the Data Collector Configuration Utility: a. Select the SAP NetWeaver runtime environment. b. Select the Client side standalone Web Services application option. c. Select the option to disable data collection. d. Specify the directory path for the location of the services application to be monitored. e. Wait for the configuration utility to complete the operation. f. Exit the utility.
186
Installation Guide
Using the KD4configDC command: See Disabling data collection using the KD4configDC command. Specify the clientappsdir parameter. 2. Modify the classpath used to launch the standalone client application to remove the kd4dcagent.jar file. 3. Run the application. If you manually enabled the standalone client application for the data collector: Remove the kd4dcagent.jar file from the classpath, and remove the changes you made to the lports_1.xml and protocols.txt files during the manual enable process. Then reinstall your application into the application server. v For a deployable client application: 1. You do not need to stop the SAP NetWeaver application server if it is already running. 2. Manually remove the modifications you made to the application code when you enabled the application for the data collector. 3. Remove the kd4dcagent.jar file from the deployable client application. 4. Redeploy the application.
Disabling data collection using the KD4configDC command

Run the KD4configDC command to disable the application for the data collector: v For supported Windows operating systems:
KD4configDC.bat -disable -env 6 {sid <home> <sid> | sapappsdir <apps_dir> | clientappsdir <apps_dir>}

KD4configDC.sh -disable -env 6 {sid <home> <sid> | sapappsdir <apps_dir> | clientappsdir <apps_dir>}
The following parameters are specified in these commands: -disable Causes the command to disable the data collector for the specified environment. -env 6 Defines the environment to be disabled as SAP NetWeaver. sid <home> <sid> For this parameter, <home> is the SAP home directory, typically /usr/sap or C:\usr\sap, but it could reside on any drive. The <sid> argument is the SAP system ID. Both of these arguments are used to confirm that the directory corresponding to the specified SID exists under the specified home. All services applications that are found under the SID are disabled. This is the preferred option to specify, because it does the same tasks as the sapappsdir parameter, and some error checking is also performed to assist you. -sapappsdir Specifies that the directory path specified by <apps_dir> is the location of the services application being monitored. Use this parameter for either a server side application or a deployable client side application. -clientappsdir Specifies that the directory path specified by <apps_dir> is the location of the services application being monitored. Use this parameter for a standalone client side application. There is no default path for the clientappsdir parameter.
187
If your standalone client application is a .jar file, be sure to specify the full directory path for the location of the .jar file. See the examples that follow. <apps_dir> Specifies the directory path of the services application being monitored. Examples: v ./KD4configDC.sh -disable -env 6 -sid /usr/sap J2E In this example, SAP_HOME and the SAP system name are provided to disable the application for the data collector. The /usr/sap directory is the directory where SAP NetWeaver is installed. J2E is the SAP system name. v KD4configDC.bat -disable -env 6 -sapappsdir /appl1 In this example, the services application directory location /appl1 is specified. This might be for disabling a server side or deployable client side application. v KD4configDC.bat -disable -env 6 -clientappsdir /appl2 In this example, the services application directory location /appl2 is specified. This command disables a standalone client side application. v KD4configDC.bat -disable -env 6 -sapappsdir
"C:\SAP\My Sap\j2e\JC000\j2ee\cluster\server0\apps"
In this example, the services application directory is not located under the SID home, and is specified as fully qualified. This also shows the directory path surrounded in quotation marks, which must be used if the path contains blank spaces. v KD4configDC.sh -disable -env 6 -clientappsdir
/usr/sap/j2e/JC000/j2ee/cluster/server0/apps
This example is for running the KD4configDC command on supported AIX, Solaris, HP-UX, or Linux operating systems. v KD4configDC.sh -disable -env 6 -clientappsdir
/usr/sap/Customer/EnterpriseSTDClientProxy.jar
In this example, the standalone client application is a .jar file, so the full directory path location of the file is specified.
As you enable SAP NetWeaver applications for the data collector, keep in mind these additional considerations: v In the Tivoli Enterprise Portal, the display pattern for server instances is D4:<hostname>-<SID>_<instance>_<server>. This format displays each server uniquely in the Tivoli Enterprise Portal. For example, suppose there are two different SAP NetWeaver servers, server1 and server2, on the same computer system: The hostname of the system is tiv121. The SID for both servers is J2E The instance for both servers is 00 These two servers are each displayed uniquely in the Tivoli Enterprise Portal as D4:tiv121-J2E_00_S0 and D4:tiv121-J2E_00_S1. v IBM Tivoli Composite Application Manager for SOA uses the service port name to identify services. If you have two or more service ports deployed that have the same name, these will appear to be the same service port in the Tivoli Enterprise Portal displays. v The first time that the service is called, there might be a delay of several seconds due to the data collector loading the WSDL related information for the service. On subsequent calls of the service, however, data is retrieved as expected.
188
Installation Guide
v When you enable and disable data collection for your applications, the configuration file is automatically backed up. For a server application, the web.xml file is backed up in the same directory where it is currently located. For example, if the original web.xml file is located in <apps_dir>/<app01>/web.xml, the file is backed up to <apps_dir>/<app01>/ web.xml.kd4backup.<timestamp>, where <timestamp> is a timestamp for when the backup is performed. For a standalone client application that is not a JAR file, the lport_1.xml file is backed up in the same directory where it is currently located. For example, if the original lport_1.xml file is located in <standalone_dir>/ lport_1.xml, the file is backed up to <standalone_dir>/ lport_1.xml.kd4backup.<timestamp>, where <timestamp> is a timestamp for when the backup is performed. For a standalone client application that is a JAR file, the lport_1.xml file is backed up as lport_1.xml.kd4backup.<timestamp>, and packed into the JAR file. If you experience errors after enabling or disabling your applications for data collection, you can restore the backed up configuration file manually. See the documentation library and online help information provided with IBM Tivoli Composite Application Manager for SOA for information on configuring monitoring and filtering settings, understanding workspaces, views, Take Action commands, and other features that help you monitor and manage your services in the SAP NetWeaver application server runtime environment.
189
190
Installation Guide
Chapter 12. Configuring data collection: WebSphere Community Edition

This section describes the support for monitoring of services flows in the WebSphere Community Edition (CE) J2EE Application Server version 1.0.1.1 environment. In general, the data collector for the WebSphere CE environment operates in the same way as the WebSphere Application Server, BEA WebLogic Server, and JBoss environments. The same types of log files are used, messages are filtered in a similar fashion, and performance is comparable. WebSphere CE server instances are identified in the Tivoli Enterprise Portal navigator view in the form of d4::<hostname>-<port>. You run the KD4configDC command once to enable all available WebSphere CE applications for monitoring. If additional applications are added to the environment after running the KD4configDC command, you must run it again to recognize the newly added applications. Applications that are already enabled are not affected. Note that you cannot use the Data Collector Configuration Utility to configure data collection for WebSphere CE.
Enabling WebSphere CE applications for data collection

To enable WebSphere CE applications for data collection, complete the following steps: 1. Before enabling the application for data collection, increase the WebSphere CE JVM maximum heap size (Xmx) to 256 MB, and the JVM maximum permanent generation size (MaxPermSize) to 128MB. You can set these values in the JAVA_OPTS keyword: v For supported Windows operating systems, edit the <WASCE_HOME>\bin\ setenv.bat script file:
set JAVA_OPTS=-Xms128m -Xmx256m -XX:PermSize=64m -XX:MaxPermSize=128m "-Djava.endorsed.dirs=%GERONIMO_BASE%/lib/endorsed" %JAVA_OPTS%
v For supported AIX and Linux operating systems, edit the <WASCE_HOME>/bin/setenv.sh script file:
export JAVA_OPTS=-Xms128m -Xmx256m -XX:PermSize=64m -XX:MaxPermSize=128m -Djava.endorsed.dirs=$GERONIMO_BASE/lib/endorsed %JAVA_OPTS%
2. Ensure that the application server is running before enabling the application for data collection. Follow the procedures in your WebSphere CE documentation for starting the server. 3. Optional: Run the KD4configDC command using the list parameter to create a list of applications to be enabled with subsequent runs of the KD4configDC command. 4. Optional: Review and manually modify the file (specified by the file <filename> argument specified when you ran the KD4configDC command) containing the list of applications to be enabled, to exclude those applications that should not be enabled. 5. Run the KD4configDC command again to enable the applications in the file list, this time not specifying the list parameter. As a result of enabling the applications, each J2EE services application is redeployed automatically. 6. During this process each J2EE application is backed up as <name>.<date>.<hour>.<min>.<sec>.bak.<type> (where <type> is the file type,
191
such as jar, war, or ear), and stored in the <WASCE_HOME>/temp/KD4 directory, where <WASCE_HOME> is the location where WebSphere CE is installed. These backup files are not automatically removed during the enable or disable process. You should consider removing them when they are no longer needed, to conserve available disk storage.
Running the KD4configDC command

Run the KD4configDC command to enable the application for data collection: v For supported Windows operating systems:
KD4configDC.bat enable env 7 {<WASCE_HOME>} user <user name> passwd <password> [list] file <filename>
v For supported AIX and Linux operating systems:

KD4configDC.sh enable env 7 {<WASCE_HOME>} user <user name> passwd <password> [list] file <filename>
The following parameters are specified in these commands: enable Causes the command to enable the application for the specified environment. env 7 Defines the application server runtime environment for which the application is enabled as WebSphere CE. <WASCE_HOME> This is an optional parameter that specifies the directory path where WebSphere CE is installed. If you have already created a WASCE_HOME system environment variable, then this parameter is not required. Typical values for this variable are: v For supported Windows operating systems:
C:\Program Files\IBM\WebSphere\AppServerCommunityEdition

/opt/IBM/WebSphere/AppServerCommunityEdition
user <user name> Specifies a valid WebSphere CE user name that has Administrator authority. See your WebSphere CE documentation for more information about creating Administrator user names and passwords. See your local system administrator for assistance, if needed. passwd <password> Specifies a valid password that is associated with the specified WebSphere CE user name. See your WebSphere CE documentation for more information about creating Administrator user names and passwords. See your local system administrator for assistance, if needed. list This is an optional parameter that, when specified, causes the utility to create a list of available applications that can be later enabled or disabled, and store this list in the specified file name indicated by the file <filename> parameter. Note that the specified enable or disable operation is not performed at this time, only the file is created for future enable or disable operations (in this special case you must specify either the enable or disable parameter in the command, but it is ignored).
192
Installation Guide
You should examine this file and modify it as needed to exclude certain applications from the list that you do not want to enable or disable with subsequent runs of the KD4configDC command. Is your application deployed with an external plan file? The application is redeployed as part of the enable or disable operation, so if your application must be deployed with an external plan file, you should exclude that application from the list. Subsequent runs of the KD4configDC command use the list of files in the specified <filename> until you overwrite the contents of the file with another command using the list parameter. file <filename> This parameter is used in two different ways, depending on whether or not the list parameter is also specified in the KD4configDC command: v If the list parameter is specified, the file name indicated by <filename> is created relative to the current directory location. For example, if you navigated to /KD4/bin to run the KD4configDC command, this file is created in that directory. You can also specify a fully qualified file and path. All WebSphere CE services applications that are eligible to be enabled or disabled in subsequent runs of the KD4configDC command are discovered and listed in the designated file. Note that no enable or disable operation is performed on these applications at this time, only the list is created and stored in the file. After the list is created, you can modify this list manually to exclude applications that you do not want to be enabled or disabled with subsequent runs of the KD4configDC command (for example, those deployed with an external plan file). v If the list parameter is not specified, then it is assumed that this file already exists (from a previous run of the KD4configDC command) and contains the list of WebSphere CE applications that you want to enable or disable. The KD4configDC command reads the file specified by <filename> and performs the enable or disable operation on each application that is not already enabled or disabled. Note that applications in the list that are already enabled or disabled are not changed. A message is displayed indicating that they are ignored for this operation. If the specified file name already exists, it is overwritten. Do not use reserved file names: When you specify the file name to be created with the list file <filename> parameters, do not use the name of a reserved file that is already in the current directory. For example, if you are in the \KD4\bin directory, do not use existing file names, such as KD4configDC.bat, or configWASCEDC.bat. This will overwrite these files and cause errors in operation, and you will need to recover these files from the installation media. You should either specify a fully qualified unique file and directory path, create a separate folder for this file within the current directory, or create a unique file name and use it consistently each time when you run the KD4configDC command using the list parameter. If you use different file names with different runs of the KD4configDC command, they are all stored in the current directory and you must keep track of which file to specify in subsequent enable or disable operations. Examples:
193
v KD4configDC.bat enable env 7 C:\WASCE user system -passwd manager

list file filelist01
In this example, the value of WASCE_HOME has been provided, along with a valid user name and password. Because the list parameter is specified, the utility initiates a discovery of the eligible WebSphere CE applications that can be enabled or disabled with later runs of the KD4configDC command, and writes that list to the file name filelist01 in the current directory. Even though the enable parameter is specified, it is ignored for this command and no applications are enabled. After this command completes, you have the opportunity to manually modify this file and remove any applications that you do not want to be enabled or disabled with subsequent runs of the KD4configDC command. v KD4configDC.bat enable env 7 C:\WASCE user system -passwd manager
list file files\filelist01
In this example, the list of eligible files is stored in filelist01, which is created in the \files folder under the current directory. Specifying a separate folder might be a good practice to avoid potentially writing over existing reserved files in the current directory. v KD4configDC.bat enable env 7 C:\WASCE user system -passwd manager
list file "D:\WASCE files\filelist01"
In this example, the list of eligible files is stored in filelist01, which is created in the "\WASCE files" folder on the D: drive. This example shows that you can specify a fully qualified file name and path for the file list. Also, if the fully qualified path contains a blank character, the path is surrounded with quotation marks. v KD4configDC.bat enable env 7 C:\WASCE user system -passwd manager
file filelist01
In this example, the list parameter is not specified, and now KD4configDC reads the contents of the file filelist01 in the current directory, and performs the enable operation on all applications in the list that are not already enabled for this data collector. If an application in the list is already enabled, it is ignored and its state is not changed. If an application is specified in the list that cannot be found, a message is displayed and the command continues to the next application in the file. If the specified file is not found in the current directory, an error message is displayed. v KD4configDC.bat -enable -env 7 -user cde321 -passwd xxx111xxx file filelist01 In this example, the WASCE_HOME environment variable has been set, and is used by default when the command is run. v KD4configDC.bat enable env 7
"C:\Program Files\IBM\WebSphere\AppServerCommunityEdition" user abc123 -passwd xyz010 file filelist01
In this example, the value of WASCE_HOME is specified, and because it includes a blank space, is surrounded with quotation marks. v KD4configDC.sh -enable -env 7 /opt/IBM/WebSphere/AppServerCommunityEdition
-user user1 -passwd zz11zz file filelist01
This example is for running the KD4configDC command on a supported AIX or Linux operating system.
Enabling data collection manually

You might have used a custom plan file to deploy your WebSphere CE application. If so, then you need to perform some additional manual steps to enable these WebSphere CE applications for the data collector: 1. If you have not already run the KD4configDC command to enable other WebSphere CE applications that use the default plan file, you must run the
194
Installation Guide
KD4configDC command (using the procedure described in the previous section) once to place the necessary JAR files into their correct locations. Specify an empty file as the value for the file parameter. This results in the message KD4CF0038E being displayed, indicating that there are no applications to be enabled. You can ignore this message. If you have already run the KD4configDC command for at least one WebSphere CE application that uses the default plan file, then this step is already completed and you do not need to run the utility again. 2. Edit the custom deployment plan file. Within each <web-app> or <openejb-jar> element, add the following <dependency> and <hidden-classes> elements:
<dependency xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0"> <uri>KD4/kd4dcagent/6.0/jar</uri> </dependency> <dependency xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0"> <uri>KD4/ibm-jaxrpc-client/6.0.2/jar</uri> </dependency> <hidden-classes xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0"> <filter>com.ibm.wsdl</filter> </hidden-classes> <hidden-classes xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0"> <filter>javax.wsdl.factory.WSDLFactory</filter> </hidden-classes>
The following example shows how to add <dependency> and <hidden-classes> elements within a <web-app> element:
<web-app xmlns="http://geronimo.apache.org/xml/ns/web" xmlns:sys="http://geronimo.apache.org/xml/ns/deployment-1.0" xmlns:naming="http://geronimo.apache.org/xml/ns/naming-1.0" xmlns:security="http://geronimo.apache.org/xml/ns/security-1.0" configId="com/ibm/j2g/webservices.war"> <dependency xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0"> <uri>KD4/kd4dcagent/6.0/jar</uri> </dependency> <dependency xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0"> <uri>KD4/ibm-jaxrpc-client/6.0.2/jar</uri> </dependency> <hidden-classes xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0"> <filter>com.ibm.wsdl</filter> </hidden-classes> <hidden-classes xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0"> <filter>javax.wsdl.factory.WSDLFactory</filter> </hidden-classes> <context-root>/webservices</context-root> <context-priority-classloader>false</context-priority-classloader> </web-app>
The following example shows how to add <dependency> and <hidden-classes> elements within an <openejb-jar> element:
<openejb-jar xmlns="http://www.openejb.org/xml/ns/openejb-jar" configId="com/ibm/dw/bookshop" parentId="BookShopDB"> <dependency xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0"> <uri>KD4/kd4dcagent/6.0/jar</uri> </dependency> <dependency xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0"> <uri>KD4/ibm-jaxrpc-client/6.0.2/jar</uri> </dependency> <hidden-classes xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0"> <filter>com.ibm.wsdl</filter> </hidden-classes> <hidden-classes xmlns="http://geronimo.apache.org/xml/ns/deployment-1.0"> <filter>javax.wsdl.factory.WSDLFactory</filter> </hidden-classes>
195
<enterprise-beans> <entity> <ejb-name>CategoryBean</ejb-name> <jndi-name>CategoryBean</jndi-name> <table-name>categories</table-name> <cmp-field-mapping> <cmp-field-name>catId</cmp-field-name> <table-column>catId</table-column> </cmp-field-mapping> <cmp-field-mapping> <cmp-field-name>name</cmp-field-name> <table-column>name</table-column> </cmp-field-mapping> <resource-ref> <ref-name>jdbc/basic/BookShopDatabase</ref-name> <application>null</application> <module>BooksShopDB</module> <name>BookShopDBPool</name> </resource-ref> </entity> </enterprise-beans> </openejb-jar>
3. Add the IBM Tivoli Composite Application Manager for SOA server side handler to all of the handler chains in the webservices.xml files within the application (if the application does not contain webservices.xml, skip this step). Modify the webservices.xml files by adding the following lines:
<handler> <handler-name>KD4ServerHandler</handler-name> <handler-class> com.ibm.management.soa.agent.wasce.ITMWASCEServerHandler </handler-class> </handler>
The following example shows how to add the server side handler to the webservices.xml file:
<?xml version="1.0" encoding="UTF-8"?> <webservices xmlns="http://java.sun.com/xml/ns/j2ee" version="1.1"> <webservice-description> <webservice-description-name>SearchPhones</webservice-description-name> <wsdl-file>WEB-INF/wsdl/search-phones-service.wsdl</wsdl-file> <jaxrpc-mapping-file> WEB-INF/search-phones-server-mapping.xml </jaxrpc-mapping-file> <port-component> <port-component-name>SearchPhonesService</port-component-name> <wsdl-port>SearchPhonesService</wsdl-port> <service-endpoint-interface> com.ibm.j2g.webservices.server.SearchPhonesPortType <service-endpoint-interface> <service-impl-bean> <servlet-link>SearchPhonesServer</servlet-link> </service-impl-bean> <handler> <handler-name>KD4ServerHandler</handler-name> <handler-class> com.ibm.management.soa.agent.wasce.ITMWASCEServerHandler </handler-class> </handler> </port-component> </webservice-description> </webservices>
If there are multiple <port-component> elements, you must add one <handler> element within each <port-component> element. 4. If the application contains a web.xml file and the web.xml file includes a <service-ref> element, you must add the IBM Tivoli Composite Application
196
Installation Guide
Manager for SOA client handler to the handler chain in the web.xml file. If there is no web.xml file or an existing web.xml file does not include a <service-ref> element, skip this step. Modify the web.xml file by adding the following lines:
<handler> <handler-name>ClientHandler</handler-name> <handler-class> com.ibm.management.soa.agent.wasce.ITMWASCEClientHandler </handler-class> </handler>
The following example shows how to add the client handler to the handler chain in the web.xml file:
<?xml version="1.0" encoding="UTF-8"?> <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4"> <servlet> <servlet-name>SearchPhonesServer</servlet-name> <servlet-class> com.ibm.j2g.webservices.server.SearchPhonesServer </servlet-class> </servlet> <servlet-mapping> <servlet-name>SearchPhonesServer</servlet-name> <url-pattern>/server</url-pattern> </servlet-mapping> <service-ref> <service-ref-name>service/SearchPhones</service-ref-name> <service-interface> com.ibm.j2g.webservices.client.SearchPhonesService </service-interface> <wsdl-file>WEB-INF/wsdl/search-phones-service.wsdl</wsdl-file> <jaxrpc-mapping-file> WEB-INF/search-phones-client-mapping.xml </jaxrpc-mapping-file> <handler> <handler-name>KD4ClientHandler</handler-name> <handler-class> com.ibm.management.soa.agent.wasce.ITMWASCEClientHandler </handler-class> </handler> </service-ref> </web-app>
5.
If the application contains the ejb-jar.xml file and the ejb-jar.xml file includes the <service-ref> element, you must add the IBM Tivoli Composite Application Manager for SOA client handler to the handler chain in ejb-jar.xml file. If there is no ejb-jar.xml file in the application, or if an existing ejb-jar.xml file does not include the <service-ref> element, skip this step. The following example shows how to add the client handler to the handler chain in the ejb-jar.xml file:
<?xml version="1.0" encoding="UTF-8"?> <ejb-jar xmlns="http://java.sun.com/xml/ns/j2ee" version="2.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/ejb-jar_2_1.xsd"> <enterprise-beans> <session> <ejb-name>BookShopEJB</ejb-name> <local-home>com.ibm.dw.bookshop.ejb.BookShopLocalHome</local-home> <local>com.ibm.dw.bookshop.ejb.BookShopLocal</local> <ejb-class>com.ibm.dw.bookshop.ejb.BookShopBean</ejb-class>
197
<session-type>Stateless</session-type> <transaction-type>Container</transaction-type> <service-ref> <service-ref-name>service/Service</service-ref-name> <service-interface>javax.xml.rpc.Service</service-interface> <wsdl-file>META-INF/wsdl/CurrencyExchangeService.wsdl</wsdl-file> <jaxrpc-mapping-file> META-INF/client-jaxrpc-mapping.xml </jaxrpc-mapping-file> <service-qname xmlns:ns= "http://www.xmethods.net/sd/CurrencyExchangeService.wsdl"> ns:CurrencyExchangeService </service-qname> <handler> <handler-name>KD4ClientHandler</handler-name> <handler-class> com.ibm.management.soa.agent.wasce.ITMWASCEClientHandler </handler-class> </handler> </service-ref> </session> </enterprise-beans> </ejb-jar>
6. Redeploy the application into the application server.

To disable WebSphere CE applications for data collection, complete the following steps: 1. Ensure that the application server is running. 2. Optional: Run the KD4configDC command using the list parameter to create a list of applications to be disabled with subsequent runs of the KD4configDC command. 3. Optional: Review and manually modify the file containing the list of applications to be disabled, to exclude those applications that should not be disabled. 4. Run the KD4configDC command again to disable the applications in the file list, this time not specifying the list parameter. As a result of disabling the applications, each J2EE services application is redeployed automatically. 5. If ALL services applications are disabled for this data collector, do the following: a. Shut down the application server. b. Navigate to the <WASCE_HOME>/repository/KD4 directory and manually remove the entire directory and all contents. c. Restart the WebSphere CE application server.
Running the KD4configDC command

Run the KD4configDC command to disable applications for the data collector: v For supported Windows operating systems:
KD4configDC.bat disable env 7 {<WASCE_HOME>} user <user name> passwd <password> [list] file <filename>

KD4configDC.sh disable env 7 {<WASCE_HOME>} user <user name> passwd <password> [list] file <filename>
The parameters specified in these commands are similar to those specified when enabling data collection. See the previous section for details.
198
Installation Guide
Examples: v KD4configDC.bat disable env 7 C:\WASCE user system -passwd manager

list file filelist01
In this example, the value of WASCE_HOME has been provided, along with a valid user name and password. Because the list parameter is specified, the utility initiates a discovery of the eligible WebSphere CE applications that can be enabled or disabled with later runs of KD4configDC, and writes that list to the file name filelist01 in the current directory. Even though the disable parameter was specified, it is ignored for this command and no applications are disabled. After this command completes, you have the opportunity to manually modify this file and remove any applications that you do not want to be enabled or disabled with subsequent runs of the KD4configDC command. v KD4configDC.bat disable env 7 C:\WASCE user system -passwd manager
list file files\filelist01
In this example, the list of eligible files is stored in filelist01, which is created in the \files folder under the current directory. Specifying a separate folder might be a good practice to avoid potentially writing over existing reserved files in the current directory. v KD4configDC.bat disable env 7 C:\WASCE user system -passwd manager
list file "D:\WASCE files\filelist01"
In this example, the list of eligible files is stored in filelist01, which is created in the "\WASCE files" folder on the D: drive. This example shows that you can specify a fully qualified file name and path for the file list. Also, if the fully qualified path contains a blank character, the path is surrounded with quotation marks. v KD4configDC.bat disable env 7 C:\WASCE user system -passwd manager
file filelist01
In this example, the list parameter is not specified, and now KD4configDC reads the contents of the file filelist01 in the current directory, and performs the disable operation on all applications in the list that are not already disabled for this data collector. If an application in the list is already disabled, it is ignored and its state is not changed. If an application is specified in the list that cannot be found, an message is displayed and the command continues to the next application in the file. If the specified file is not found in the current directory, an error message is displayed. v KD4configDC.bat -disable -env 7 -user cde321 -passwd xxx111xxx file filelist01 In this example, the WASCE_HOME environment variable has been set, and is used by default when the command is run. v KD4configDC.bat enable env 7
"C:\Program Files\IBM\WebSphere\AppServerCommunityEdition" user abc123 -passwd xyz010 file filelist01
In this example, the value of WASCE_HOME is specified, and, because it includes a blank space, is surrounded with quotation marks. v KD4configDC.sh -enable -env 7 /opt/IBM/WebSphere/AppServerCommunityEdition
-user user1 -passwd zz11zz file filelist01
This example is for running KD4configDC on a supported AIX or Linux operating system.
Disabling data collection manually

You might have used a custom plan file to deploy your WebSphere CE application. If so, you need to perform some additional manual steps to remove the <handler>, <dependency>, and <hidden-classes> elements that you added manually when the data collector was enabled for these applications. See Enabling data collection manually on page 194 for more information on these declarations that were manually added.
199
If this is the last WebSphere CE application using the data collector for IBM Tivoli Composite Application Manager for SOA, then after manually removing the elements, run the KD4configDC command to remove the associated JAR files from their locations. After manually disabling the data collector, redeploy the WebSphere CE application.
When you configure filter controls to block messages, the WebSphere CE data collector only supports the asterisk wild card (*) character in the IP field. If you specify a hostname or IP address in that field, the data collector filtering will not match any messages.
200
Installation Guide
Chapter 13. Configuring data collection: DataPower SOA Appliance

This section describes the support for monitoring of service flows through an IBM WebSphere DataPower SOA appliance, where the ITCAM for SOA data collector acts as a proxy between the services clients and servers. IBM WebSphere DataPower SOA appliances are used for processing XML messages, and providing message transformation, services acceleration, and security functions. A DataPower appliance is typically used to improve the security and performance of services by offloading functions from the application server that is hosting the target service to a DataPower SOA appliance. Typical functions that are off-loaded include authentication and authorization, XML schema validation, and services encryption and decryption. IBM Tivoli Composite Application Manager for SOA provides a DataPower data collector that operates as a proxy and monitors services flows through a DataPower SOA appliance, providing similar services management and availability information that IBM Tivoli Composite Application Manager for SOA currently provides for application server runtime environments. This information is displayed in the Tivoli Enterprise Portal using the usual predefined or user-defined workspaces and views. DataPower supports two proxy types that can process SOA messages: The Web Services Proxy You configure a Web Services Proxy by importing one or more WSDL files and then telling the appliance where to direct those messages. Thus, the Web Services Proxy receives only SOAP messages. The Multi-Protocol Gateway The Multi-Protocol Gateway is more versatile than the Web Services Proxy. You can use it to process nearly any type of message, including SOAP, non-SOAP XML, text, or binary. For XML messages (including SOAP), XSL transforms are used to manipulate the message. For non-XML messages, similar transform actions can be built using IBM WebSphere Transformation Extender (for more information about this product, see http://www-306.ibm.com/software/integration/wdatastagetx/). Upgrade your firmware: Before using the DataPower data collector proxy, you must upgrade the firmware on DataPower SOA appliances that you want to monitor, to include the necessary monitoring and data transformation capabilities. v Upgrade your firmware to at least version 3.6.1 or later to monitor traffic through the Web Services Proxy. v Upgrade your firmware to at least version 3.7.1 Fix Pack 4 or later to monitor traffic through a Multi-Protocol Gateway. Consult your DataPower Appliance documentation for information on upgrading your firmware level.
The DataPower data collector as a proxy

Data collectors provided with IBM Tivoli Composite Application Manager for SOA are usually installed directly into the application server runtime environment hosting the services being monitored. The DataPower SOA appliance, however, does not support the installation of additional software, such as a data collector. Unlike other
201
application server runtime environments, the ITCAM for SOA data collector for the DataPower environment is installed on a separate computer system and uses a special communication mechanism that allows external software applications to receive data from its internal transaction log. This communication mechanism is used to retrieve monitoring data about services requests flowing through one or more DataPower SOA appliances, and to convert the data into a format that IBM Tivoli Composite Application Manager for SOA can process. In this way, the DataPower data collector acts as a proxy between the DataPower SOA appliances and the IBM Tivoli Composite Application Manager for SOA monitoring agent. The DataPower data collector can be installed on a dedicated computer system, or it can run on a computer that is also hosting data collectors for other application server runtime environments. Note that IBM supports only one instance of the DataPower data collector running on any given system. This one data collector instance, however, can monitor any number of domains on any number of appliances, subject to available resources. When data collection is enabled for the DataPower environment, the data collector subscribes to each monitored DataPower SOA appliance and then polls the appliance for monitoring data at an interval that you can configure. The data retrieved from the DataPower SOA appliance is written to metric log files in the format used by IBM Tivoli Composite Application Manager for SOA. When this data is later displayed in the Tivoli Enterprise Portal, nodes are displayed in the Tivoli Enterprise Portal Navigator view that represent the DataPower SOA appliances being monitored. You can select workspaces under these nodes and view the services management data for the service requests flowing through the monitored DataPower SOA appliances. The DataPower data collector can subscribe to multiple DataPower SOA appliances, and retrieve and manage data from multiple domains. This data can then be separated by DataPower domain or aggregated across multiple domains and appliances, depending on how you configure the data collector. The DataPower data collector uses a configuration file that contains information about which DataPower SOA appliances are being monitored and information needed to establish communication with each monitored appliance.
Planning for deployment

DataPower proxies are defined within application domains, and DataPower users can be restricted to access some or all domains. When configuring the DataPower data collector, you must understand how the domains and users are defined on the monitored DataPower SOA appliances, to ensure that the data collector uses valid authentication credentials. This refers to user IDs and passwords that have access to the DataPower domains containing the services proxies to be monitored. In addition, you must decide how you want to aggregate or separate the data collected from those domains for display in the Tivoli Enterprise Portal. You can use DataPower SOA appliances in several typical configurations: v Single appliance, single domain: The data collector monitors a single DataPower SOA appliance, with all of the monitored resources defined in a single domain on the appliance.
202
Installation Guide
v Single appliance, multiple domains: The data collector monitors a single DataPower SOA appliance, but that appliance has monitored resources that are defined in more than one domain on the appliance. v Multiple appliances with different configurations: The data collector monitors multiple DataPower SOA appliances, and each appliance has a different configuration of resources to be monitored. Each appliance is configured for a particular job, with no intention of load-balancing or fail-over between appliances. v Multiple appliances with identical configurations: The data collector monitors multiple DataPower SOA appliances, and all of the appliances have an identical configuration of resources being monitored. All of the appliances are configured for the same job, taking advantage of load-balancing and fail-over capabilities between appliances. Given these typical configurations, the DataPower data collector provides a great deal of flexibility in defining how the collected monitoring data should be separated or aggregated, across a single appliance or multiple appliances, for display in the Tivoli Enterprise Portal. The following examples illustrate how data can be separated or aggregated for managing the data from various domains and appliances: v Separation of data at the domain: You can view the services management data for the resources in a single domain, separate from the data for resources in other domains. v Aggregation of data across domains: You can view the services management data for the resources in several domains (for example, all of the domains on a given DataPower SOA appliance) in an aggregated form, with no regard for the domain in which individual resources are defined. v Separation of data at the appliance: You can view the services management data for resources on a single DataPower SOA appliance, separate from the data for resources on other appliances. v Aggregation of data across appliances: You can view the services management data for the resources on several DataPower SOA appliances (for example, all of the appliances in a load-balancing cluster) in an aggregated form, with no regard for what activity occurs on each individual appliance. By default, the DataPower data collector aggregates data for all of the monitored domains on a single DataPower SOA appliance (even if the domains are accessed using different credentials), and keeps the data from each DataPower SOA appliance separated. See Enabling data collection on page 212 for more information. Note that operational flow data is collected only by individual domain. Refer to Creating node names in Tivoli Enterprise Portal on page 217 for additional details. A single instance of the DataPower data collector can monitor any number of DataPower SOA appliances, limited only by the memory, CPU power and other resources available to it. Note that IBM only supports running a single instance of the data collector on any given system.
Aggregation
For most IBM Tivoli Composite Application Manager for SOA data collectors, aggregation of data is performed for each application server runtime environment. The nodes in the Tivoli Enterprise Portal Navigator view represent individual application server runtime environments that have their own individual data collectors. Because the DataPower data collector can monitor multiple DataPower
203
SOA appliances and multiple domains within each appliance, this single application server runtime environment, single data collector model no longer applies. Using the DataPower data collector, you assign names to groups of data, referred to as display groups. Each group of data is displayed as its own node in the Tivoli Enterprise Portal. Using these named display groups, you can configure the DataPower data collector to gather information from any domains on any DataPower SOA appliances for aggregation and display. By carefully managing the way in which you name these display groups, the DataPower data collector can separate or aggregate the data in different ways, such as isolating data specific to an individual domain on a single DataPower SOA appliance, or aggregating data across several DataPower SOA appliances into a single display group. This simple display group naming mechanism gives you great flexibility in the separation and aggregation of the data displayed in the Tivoli Enterprise Portal. Note that operational flow views are displayed by domain, not by display group. See Creating node names in Tivoli Enterprise Portal on page 217 for additional details.
Deployment steps
To deploy the DataPower data collector in your environment, complete the following general steps: 1. Configure your DataPower SOA appliances for monitoring (see Configuring the DataPower SOA appliance for monitoring for details). 2. Enable the DataPower data collector (see Enabling data collection on page 212 for details). 3. Run the startDPDC script to start the data collector (see Starting and stopping the data collector on page 225 for details), or configure the data collector to run in the background and start the background task.
Configuring the DataPower SOA appliance for monitoring

Before a DataPower SOA appliance can be monitored by the DataPower data collector, configure the DataPower SOA appliance by completing these tasks, described in more detail in the sections that follow: v Upgrade your DataPower firmware to the minimum supported version. v Configure a user account on the DataPower SOA appliance for use with the DataPower data collector. v Enable the XML Management Interface on the appliance. v Check additional optional settings for each domain to be monitored. v Enable the ITCAM for SOA transforms for the Web Services Proxy gateways and the Multi-Protocol gateways as needed. v Configure the AAA policy for the Web Services Proxy gateways and the Multi-Protocol gateways if you plan to monitor Web service requesters by user ID.
Upgrading the DataPower firmware version

Before using the DataPower data collector proxy, you must upgrade the firmware on DataPower SOA appliances that you want to monitor, to include the necessary monitoring and data transformation capabilities. You must upgrade the firmware to version 3.6.1 or later to use the Web Services Proxy. To use the Multi-Protocol Gateway Proxy services on your DataPower appliance, you must upgrade the firmware to version 3.7.1 Fix Pack 4 or later.
204
Installation Guide
Whenever you upgrade your firmware, be sure to go back and verify that all of your configuration settings are set correctly.
Configuring a user account on the DataPower SOA appliance

The DataPower user ID used by the data collector must belong to a user group with the following permissions: v Read permission on the Login XML-Mgmt Resource Type in the default domain. v Read permission on the XML-mgmt Resource Type in each domain to be monitored using this user ID. v Read permission on the (any) Resource Type in each domain to be monitored using this user ID. See your DataPower WebGUI Guide or DataPower CLI Reference Guide for details on configuring user group permissions.
Enabling the XML Management Interface

The XML Management Interface on the appliance must be enabled using the DataPower administration console. To enable this service, complete the following steps: 1. Start the DataPower administration console in a Web browser (https://hostname:9090/login.xml). 2. Login to the administration console as admin in the default domain. 3. In the list at the left side of the console, navigate to Objects > Management > XML Management Interface. 4. Make note of the port number that is displayed. You will need to specify this port number later when you enable or disable data collection. 5. In the Main tab, find the WS-Management Endpoint option and select the on check box. 6. Click Apply to activate the changes and enable the WS-Management Endpoint.
Checking additional optional settings

For each domain to be monitored, check the following settings: v In the list at the left side of the console, navigate to Services > Miscellaneous > Web Services Agent. v Set Admin State to enabled. v Optional: If you want the DataPower SOA appliance to save metrics records when the DataPower data collector is not running, set BufferMode to buffer. With this setting, the appliance reports the saved metric data when the data collector starts. v Optional: Adjust the values for MaxRecords and MaxMemoryKB v Optional: If you want the data collector to record message content in addition to summary metrics, change CaptureMode from faults to all-messages.
Configuring DataPower Processing Rules

In addition to upgrading your DataPower firmware, you might need to add XSL transforms to the action rules in each Processing Rule for each affected Web Services Proxy or Multi-Protocol Gateway Proxy object: v If you are monitoring a WS-Proxy without topology support, no transforms are necessary.
205
v If you are monitoring topology in a WS-Proxy, the preloaded transforms must be added to your processing rules. v If you are monitoring a Multi-Protocol gateway, certain transforms must be created. v If you are monitoring topology on a Multi-Protocol gateway, more logic needs to be added either to those transforms or into additional transforms. This section describes the procedures for configuring DataPower processing rules for Web Services Proxy gateways and DataPower Multi-Protocol gateways.
Configuring processing rules for DataPower Web Services Proxy gateways

This section describes the procedures for configuring DataPower processing rules for Web Services Proxy gateways. For each Web Services Proxy object, you need to add these transforms, which are included in your DataPower firmware: v soapreq.xsl v soaprsp.xsl v soaperror.xsl Generally the procedure to add these XSL transforms to the request and response paths involves these steps: 1. Open the Web Services Proxy Object. 2. Select the Policy tab.
Figure 54. Enabling IBM Tivoli Composite Application Manager for SOA transforms in DataPower
3. If you currently do not have a processing rule defined, expand the node tree to display subnodes (proxy, wsdl, service, and others). 4. Select the desired Add Rule icon and continue to configure this new rule as if it was already existing. 5. For an existing or newly added rule, complete these steps: a. Add a Match action to the rule (the equal sign (=) icon), as needed, to match all messages, or to only match those you intend to monitor.
206
Installation Guide
b. Add a Transform action (the three-prong swirl icon) to add the IBM Tivoli Composite Application Manager for SOA transforms that are preloaded in the firmware. v For a Request rule, use the store:///soapreq.xsl transform. v For a Response rule, use the store:///soaprsp.xsl transform. v For an Error rule, use the store:///soaperror.xsl transform. Note: For an Error rule, your Match action must match errors, not normal responses. This is an option when you configure your Match. c. Add a Results action to the rule (the arrow icon) to return the transformed message. 6. Apply and save your changes. Refer to the you WebSphere DataPower documentation for more information about processing rules.
Configuring processing rules for DataPower Multi-Protocol Gateways

A DataPower Multi-Protocol Gateway service handles SOA messages in a variety of transport protocols and message formats. It can process almost any incoming message and transform the message into a completely different format, if needed, before forwarding it to a server to perform additional business processing. For example, you might use a Multi-Protocol Gateway to provide an HTTP front end that receives a SOAP message, transforms it into a proprietary XML format, and places it on an queue for the Message Queue transport protocol. Unlike a Web Service Proxy, a Multi-Protocol Gateway is not restricted to processing messages that are described by Web Services Description Language documents. Because of its flexibility and its independence from Web Services Description Language document restrictions, configuring a Multi-Protocol Gateway is different from configuring a Web Service Proxy. The Web Service Proxy knows the service port name and namespace, and the operation name and namespace of a SOAP message from information in the Web Services Description Language documents. The Multi-Protocol Gateway, however, cannot recognize this information because it has no Web Services Description Language documents, and therefore it cannot pass this information along to the ITCAM for SOA data collector. Instead, you must provide this information about service port name, service port namespace, operation name, and operation namespace, by writing the necessary logic into an XSLT processing rule in your DataPower Multi-Protocol Gateway. As shown in Figure 55 on page 208, DataPower gateways receive a request message from a client, process it in some way, and forward it to a server for additional processing. Later, the gateway usually receives a response message from the server, processes that message as needed, and forwards that response back to the client. When you monitor these message flows with ITCAM for SOA, you must modify the processing logic for each of these message flows: v At the end of each transaction, typically on response rules and error rules, you must call the dp:wsm-agent-append() function. This function (represented in green in Figure 55 on page 208) sends monitoring data about this transaction to the ITCAM for SOA data collector. v To include this message in the ITCAM for SOA operational flow topology workspaces and views, you must also add XSL logic (represented in yellow in
207
Figure 55) to handle the ITCAM for SOA KD4SoapHeaderV2 SOAP header, and call the dp:exter-correlator() function for each request and response message in the transaction.
Figure 55. DataPower gateways process requests and responses
The wsm-agent-append() function: The wsm-agent-append() function reports the various attributes of this transaction to the IBM Tivoli Composite Application Manager for SOA data collector. At any point prior to invoking this function, you must construct a processing variable containing a <dpwsm:wsa-record> nodeset and provide it as an argument to this method (see Call dp:wsm-agent-append in Figure 55). This nodeset contains the various attributes that describe the message and the transaction. Refer to the DataPower Extension Elements and Functions Catalog for the contents of this nodeset. Most of the elements in this nodeset can be set to their default values from the processing context. However, due to the absence of Web Services Description Language, the following elements must be set explicitly in your XSL: ws-operation The fully qualified operation namespace and operation name (for example, {www.opnamespace.com}myOperation). service-port The fully qualified service port namespace and service port name (for example, {www.spnamespace.com}myServicePort). is-one-way Set to true() if this operation is one-way, or false() if this operation is two-way. webservice Specifies one of the following numerical values that identify the format of the message being processed: v The value 8 refers to a SOAP message. v The values 9 refers to an XML message. v The value 10 refers to a non-XML or binary message. You should not set explicit values for any of the following elements, because they are calculated automatically by various processing tasks: v ws-correlator-sfid
208
Installation Guide
v v v v v v v v v v v
ws-client-socode ws-dp-socode ws-server-socode ws-client-hopcount ws-server-hopcount start-time duration-ms front-latency-ms back-latency-ms request-size response-size
Your processing rules should call wsm-agent-append() as close as possible to the end of the response processing rules and error processing rules. The exter-correlator() function: If you intend for this transaction to appear in IBM Tivoli Composite Application Manager for SOA operational flow topology views, you must also call the exter-correlator() function before calling the wsm-agent-append() function. The exter-correlator() function invokes a proprietary algorithm to calculate a correlator that IBM Tivoli Composite Application Manager for SOA uses to track relationships among related Web services. Using this correlator, each of several concurrent messages are tracked independently and accurately, without errors from heuristic algorithms. Handling the correlator: When the IBM Tivoli Composite Application Manager for SOA data collector monitors a Web Service Proxy, the correlator is handled by the soapreq.xsl and soaprsp.xsl style sheets shipped with the appliance firmware. When you use IBM Tivoli Composite Application Manager for SOA to monitor a Multi-Protocol Gateway, however, you must invoke the logic necessary to calculate and propagate the correlator. This process generally is as simple as extracting a string, calling this function, and attaching the result. To handle the correlator using the exter-correlator() function, complete these steps: 1. Receive an incoming correlator, if one is present. If your Multi-Protocol Gateway will be receiving SOAP messages from a Web application server that is monitored by IBM Tivoli Composite Application Manager for SOA, then you should include logic to receive an attached correlator string, if one is available. The IBM Tivoli Composite Application Manager for SOA data collector on the sending server adds a standard SOAP header named {http://www.ibm.com/ KD4Soap}KD4SoapHeaderV2 to each message that is sent. Your XSL should check for the presence of this header, and if it is present, extract the text node from within this element, similar to the following example:
<xsl:choose xmlns:kd4="http://www.ibm.com/KD4Soap"> <xsl:when test=".//kd4:KD4SoapHeaderV2"> <xsl:value-of select=".//kd4:KD4SoapHeaderV2"/> </xsl:when> <xsl:otherwise> <xsl:text>NEW_CORRELATOR</xsl:text> </xsl:otherwise> </xsl:choose>
2. Calculate the correlator for the transition of this message through the Multi-Protocol Gateway, by completing the following steps:
209
a. Identify the message by setting the following service variables: var://service/wsm/operation The fully qualified operation namespace and operation name (for example, {www.opNamespace.com}myOperation). var://service/wsm/service-port The fully qualified service port namespace and service port name (for example, {www.spNamespace.com}myServicePort). var://service/soap-oneway-mep Set to true() if this operation is one-way, or false() otherwise. var://service/wsm/service Specifies one of the following numerical values that identify the format of the message being processed: v The value 8 refers to a SOAP message. v The values 9 refers to an XML message. v The value 10 refers to a non-XML or binary message. When you set these attributes in these service variables, allow the ws-operation, service-port, webservice, and is-one-way elements of the wsa-record nodeset to take their default values. These elements default to these service variables. b. Invoke the dp:exter-correlator() function, providing the following arguments: v The first argument is the incoming correlator string. If you do not have an incoming correlator, use the literal string NEW_CORRELATOR instead. v For a request message, specify 0 for the second argument. 3. The return value from the dp:exter-correlator() function is the new correlator. Attach this string to the data collectors on the back-end servers. If you are sending SOAP messages, add XSL logic to construct a {http://www.ibm.com/ KD4Soap}KD4SoapHeaderV2 header and add it to the SOAP Header section of the outbound message. When processing a response message, follow this basic procedure, illustrated in the response processing logic flow in Figure 55 on page 208 : 1. Extract an incoming correlator if one is present (see Extract correlator (rsp_corr) in Figure 55 on page 208). 2. Calculate a new correlator and pass in the newly extracted correlator, but use 1 instead of 0 for the second argument (see Call rsp2 = dp:exter_correlator(rsp_corr, 1) in Figure 55 on page 208). 3. Attach the newly calculated correlator if your response is a SOAP message (see Attach new correlator (rsp2) in Figure 55 on page 208). Be sure these steps are done before calling the dp:wsm-agent-append() function. For an error processing rule, be careful to identify whether the error is on a request or a response, setting the direction according to the var://service/response-mode variable, as shown in the following example code:
{noformat}  <xsl:variable name="rmode"> <xsl:value-of select="dp:variable('var://service/response-mode')"/> </xsl:variable>  <xsl:variable name="newCorrelator">
210
Installation Guide
<xsl:choose> <xsl:when test="$rmode='2'"> <xsl:value-of select="dp:exter-correlator($InboundCorrelator,'1')"/> </xsl:when> <xsl:otherwise> <xsl:value-of select="dp:exter-correlator($InboundCorrelator,'0')"/> </xsl:otherwise> </xsl:choose> </xsl:variable> <dp:set-variable name="'var://context/kd4/responseCorrelatorOut'" value="$newCorrelator"/> {noformat}
The processing-rule context automatically populates the error details, and the response is identified as a fault to IBM Tivoli Composite Application Manager for SOA. You should include the same XSL logic on an error rule that you include on a response rule. Additional considerations: Service Port Name Type: Because of known limitations, the Service Port Name Type attribute SPNAMETYPE is always set to 1 (WSDL Port Name), regardless of the values used in the var://service/wsm/service variable and the webservice element. Accurate values are necessary for correct calculation of various other identifiers within the context, however, so be sure to set them accurately. Logging return codes: Log the return code from dp:wsm-agent-append(). If there is an error in this function, or a problem with the set of data you collected for it to log, the return value from this function will describe the error. In order to debug problems with this function, your XSL logic must make this return value available. XSL variables and syntax: Pay careful attention to references to XSL variables and DataPower context variables, and to use single quotes, and double quotes, correctly as needed. Troubleshooting: Other troubleshooting tools and techniques, including using a multistep probe and referring to the log files on both the DataPower appliance and on the IBM Tivoli Composite Application Manager for SOA Data Collector are still useful in troubleshooting issues with monitoring the Multi-Protocol Gateway service.
Configuring the AAA policy

If you plan to use the requester identity monitoring function provided with IBM Tivoli Composite Application Manager for SOA to monitor by user identity, an AAA policy for the Web Services Proxy Gateway and Multi-Protocol Gateway must be configured on each processing rule that you intend to monitor. IBM Tivoli Composite Application Manager for SOA can only return client ID requester identity information for the given message when the AAA policy is in effect. If you currently have an AAA policy in place, no changes to that policy are required If no AAA policy exists on the processing rule, you can optionally open a DataPower administrative console to add and configure the AAA policy. Refer to the procedures documented in Chapter 30 of the IBM WebSphere DataPower XML Security Gateway XS40 WebGUI Guide, version 3.6.1, for more information. The feature to monitor by requester identity provided in IBM Tivoli Composite Application Manager for SOA is disabled by default. To enable monitoring by requester identity, use the available Tivoli Enterprise Portal Take Action commands
211
AddRequesterIdentity_610 and EnableReqIDMntr_610, and others, as described in the IBM Tivoli Composite Application Manager for SOA Users Guide.
Extraction methods and priorities

Like most SOA environments, there are many ways to configure AAA policy, and many different types of credentials are available. ITCAM for SOA selects the first available identity type from the prioritized list in Table 8.
Table 8. Extraction methods and priorities used by the DataPower DC to obtain the user identity. Client ID extraction method Client ID type http-basic-auth LTPA-auth Saml-attr-name Saml-authen-name Wssec-username Custom Client-IP-address Client-ssl Signer-dn Wssec-binary-token Ws-secure-conversation Kerberos LTPA-token Ws-trust Cookie-token Xpath Saml-artifact User name User ID User name User name User name Result of XSL process IP address Dn Dn Token Context Token Token Token Token Token Artifact Priority 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
All of the supported extraction methods are listed in the first column. The extraction methods are prioritized by the following rules: v Sort the extraction methods by the precision of the corresponding user identity, from most specific to least specific:
Username > IP address > Dn > Token
v Within the extraction methods that extract the user name and user ID, system-level authentication takes priority over message-level authentication:
(http-basic-auth, LTPA-auth, Saml-attr-name, Saml-authen-name) > (Wssec-username)
These priorities are only considered when multiple extraction methods are configured in the AAA policy. You cannot adjust these priorities.

This section describes how to configure the DataPower environment for data collection.
212
Installation Guide
The DataPower configuration file

For the DataPower data collector, the Data Collector Configuration Utility and the KD4configDC command manipulate the contents of a special DataPower configuration file by adding sections to the file when new DataPower monitoring is enabled, and removing sections from the file when monitoring is disabled. Each invocation of the Data Collector Configuration Utility or the KD4configDC command adds, updates, or removes one section of the DataPower configuration file. Each section of the DataPower configuration file might be associated with its own data group, or it might be part of a larger data group to which other sections of the configuration file also belong. The DataPower data collector uses this configuration file to identify the DataPower SOA appliances that are to be monitored and to specify all of the information needed to communicate with those appliances. Typical information that is stored for each connection includes hostname and port, user ID and password, domains to monitor, and polling interval. The configuration file is located in the <ITCAM4SOA_Home>/KD4/config directory and is called KD4.dpdcConfig.properties. This file is maintained separately from the existing KD4.dc.properties configuration file. This is a sample DataPower configuration file:
# Sample DataPower data collector configuration file DataPower.count=3 # DataPower.host.1=dpbox1 DataPower.port.1=5550 DataPower.path.1=/ DataPower.poll.1=60 DataPower.user.1=admin DataPower.encpswd.1=#$%*& DataPower.domainlist.1=default,testdom1 DataPower.displaygroup.1=dpbox1 # DataPower.host.2=dpbox2 DataPower.port.2=5550 DataPower.path.2=/ DataPower.poll.2=30 DataPower.user.2=user1 DataPower.encpswd.2=&*%$# DataPower.domainlist.2=userdom1,userdom2,userdom3 DataPower.displaygroup.2=user_doms # DataPower.host.3=dpbox2 DataPower.port.3=5550 DataPower.path.3=/ DataPower.poll.3=30 DataPower.user.3=admin DataPower.encpswd.3=*%$#& DataPower.displaygroup.3=all_doms
In this example, there are three sections in the configuration file. The properties in each of the three sections provide all of the information needed to establish and manage a single connection or session with each DataPower SOA appliance. Change the information in this configuration file using either the Data Collector Configuration Utility or the KD4configDC command. Using various combinations of parameters in the Data Collector Configuration Utility input pages or in the KD4configDC command, you can achieve different monitoring configurations to
213
separate or aggregate data among domains and appliances. See Considerations for enabling data collection for DataPower monitoring on page 220 for more information. Before configuring your DataPower environment for data collection, consult with your local systems management planners to understand which domains on which DataPower SOA appliances are to be monitored and how the data from these domains and appliances should be separated or aggregated for display in the Tivoli Enterprise Portal.
Enabling data collection using the Data Collector Configuration Utility

To enable data collection using the Data Collector Configuration Utility, complete these steps: 1. Run the Data Collector Configuration Utility (see Running the Data Collector Configuration Utility on page 130): a. Select the DataPower SOA Appliance runtime environment. b. Select the Configure DataPower Instance option.
Figure 56. Enabling data collection on a SAP NetWeaver standalone client side application
c. Select the option to enable data collection. For the remaining input parameters, refer to Table 9 on page 216 for a description of the information that is required, and see the additional information and examples of running the KD4configDC command to learn more about how to specify these parameters for your environment. d. Specify the DataPower Host Name. e. Specify the DataPower user ID. f. Specify the DataPower password.
214
Installation Guide
Figure 57. Enabling data collection in a DataPower runtime environment
g. The default DataPower port number (5500) and the default polling interval (10 seconds) is provided. Accept these defaults or type over them to specify different values. h. Specify the DataPower Path. i. Specify the DataPower Domain List. j. Optionally specify the DataPower Display Group.
Figure 58. Enabling data collection in a DataPower runtime environment
k. Wait for the configuration utility to complete the operation. l. Exit the utility.
Enabling data collection using the KD4configDC command

The syntax for running the KD4configDC command for the DataPower environment is similar to the syntax for other supported IBM Tivoli Composite Application Manager for SOA data collector environments. To run the KD4configDC command, first navigate to the following location, depending on your operating system: Enter the KD4configDC command:
215
v For supported Windows operating systems:

KD4configDC {-enable | -disable} -env 8 <env specific parameters>

KD4configDC.sh {-enable | -disable} -env 8 <env specific parameters>
Specifying KD4configDC parameters

The <env specific parameters> defined for the DataPower invocation of the KD4configDC command are a series of key and value pairs that define the necessary properties for the affected section of the DataPower configuration file. These key and value pairs, which you can specify in any order on the command line, are shown in Table 9.
Table 9. DataPower key and value pairs for the KD4configDC command Parameter Optional / Required Default value Description Defines the DataPower SOA appliance hostname or IP address. This hostname is used to establish a socket connection and is used as part of the Web address pointing to the DataPower SOA appliance. This can be any length string, with no blank characters. See Creating node names in Tivoli Enterprise Portal on page 217 regarding possible truncation of this value in the node name. Defines the DataPower SOA appliance authentication user. This user must be a valid user for the DataPower SOA appliance defined by the -host parameter. See your DataPower documentation for information about creating and managing user IDs for DataPower SOA appliances. See Configuring a user account on the DataPower SOA appliance on page 205 for more information. User is prompted, if necessary Defines the DataPower SOA appliance authentication password, entered in clear text (not encoded). This password must be valid for the user defined in the user parameter, and must be valid for the DataPower SOA appliance defined by the host parameter. This password is automatically converted to an encoded (masked) form and is stored in the DataPower configuration file. See your DataPower documentation for information about creating and managing passwords for DataPower SOA appliances. Defines the DataPower SOA appliance port number. This port number is used to establish a socket connection and is used as part of the Web address pointing to the DataPower SOA appliance. This value must be an integer from 0 to 65535. If this parameter is not specified, the default value is used.
host Required <hostname or IP address>
user <user ID>
Required
pswd <password>
Optional
port <port number>
Optional
5550
216
Installation Guide
Table 9. DataPower key and value pairs for the KD4configDC command (continued) Parameter path <path string> Optional / Required Default value Description Optional / Defines the DataPower SOA appliance path. This path is used as part of the Web address pointing to the DataPower SOA appliance. This can be any valid path string, with no blank characters. Defines the DataPower SOA appliance polling interval (in seconds). The data collector waits this amount of time between each poll of the DataPower SOA appliance. This must be an integer value, specified in seconds, between 5 and 300 (5 seconds to 5 minutes). Defines the DataPower SOA appliance domain list. This is a comma-separated list of domains to be monitored on the associated DataPower SOA appliance. Any domains in this list that are not authorized to the user defined by the -user parameter are not monitored. Each domain can be any string, with no blank characters. If you specify more than one domain name, separated by commas, the entire domain list must be enclosed in double quotes (for example, domainlist "domain1,domain2,domain3". See Considerations for enabling data collection for DataPower monitoring on page 220 for more information on using this domain list. Defines the DataPower SOA appliance display name. The name can be any string, with no blank characters, up to 16 characters long. See Creating node names in Tivoli Enterprise Portal regarding possible truncation of this value in the node name. See Considerations for enabling data collection for DataPower monitoring on page 220 for more information on the use of this property.
poll <polling interval>
Optional
10 seconds
domainlist domainA, domainB, ...domainZ
Optional
No domainlist property is generated
displaygroup <display group>
Optional
No displaygroup property is generated
Creating node names in Tivoli Enterprise Portal

The DataPower data collector host name is combined with the value of the displaygroup parameter, separated by a hyphen, to form the node name seen in the Tivoli Enterprise Portal Navigator view. For example, suppose that the KD4configDC command is run with the displaygroup parameter specified with a value of dispName:
KD4configDC -enable -env 8 host appHost user user1 displaygroup dispName
In this example, appHost is the hostname of the DataPower SOA appliance. Recall that the DataPower data collector acts as a proxy on a different computer, and for this example assume that the proxy hostname is dpdcHost. With the
217
displaygroup parameter specified in the KD4configDC command, the node name that is displayed in the Tivoli Enterprise Portal Navigator view is D4:dpdcHost-dispName. If the displaygroup parameter is not specified in the KD4configDC command, then the value of the host parameter is used instead of displaygroup to define the node name. For example, suppose the KD4configDC command is run without specifying the displaygroup parameter:
KD4configDC -enable -env 8 host appHost user user1
The value of the host parameter (appHost) is combined with the DataPower data collector host name dpdcHost to form the node name that is displayed in the Tivoli Enterprise Portal Navigator view. In this case the node name that is displayed in the Tivoli Enterprise Portal Navigator view is D4:dpdcHost-appHost. Truncation of the node name: If the length of the node name exceeds 20 characters (including the hyphen), the node name is truncated from the end, meaning that the displaygroup or host parameter portion is truncated. You should be aware of this limitation of the Tivoli Enterprise Portal and choose values for the displaygroup and host parameters of appropriate length, to avoid truncation and possible confusion between similar names.
Examples of configuring for data collection

This section provides several examples of the kinds of monitoring that you can configure by running the KD4configDC command using various combinations of parameters. The simplest form of the command: When you run the KD4configDC command to enable monitoring of a DataPower SOA appliance, this is the simplest format of the command:
KD4configDC -enable -env 8 host <host> user <user>
For example, with a host name of dpbox1 and a user name of admin, this is the following command:
KD4configDC enable env 8 host dpbox1 user admin
The DataPower configuration file is searched for an existing section that matches the specified host and user, and that has no domain list and no display group properties defined. v If a matching section is found, you are prompted for a password, and the matching section is updated only by encoding the password and storing it in the configuration file for that section. v If a matching section is not found in the configuration file, you are prompted for a password. A new section of the configuration file is created, with the specified values for the host, user and pswd parameters stored in the configuration file for that section. Note that no values for domainlist or displaygroup parameters are defined, and other optional properties for the section are set to their default values. Because no value for the displaygroup parameter is specified, the host name dpbox1 is used as part of the node name that is displayed in the Tivoli Enterprise Portal (for example, D4:dpdcHost-dpbox1)
218
Installation Guide
Specifying domain list or display group parameters: If the domainlist or displaygroup parameters are specified in the KD4configDC command, they become part of the matching criteria that determines whether the section already exists or must be created as new. If a new section must be created, the values provided for the domainlist and displaygroup parameters are stored in the new section of the configuration file. For example, if you have two domains, domainA and domainB that you are monitoring on a DataPower SOA appliance defined by a host named host1 and authorized to user userABC, run the KD4configDC command:
KD4configDC enable env 8 host host1 user userABC domainlist "domainA,domainB"
Note that the list of domains is surrounded by quotation marks, and there are no blank characters in the domain list. As another example, suppose you want to create a node name to be displayed in the Tivoli Enterprise Portal Navigator view that contains the display group name of all_domains. This node name would be in the form of D4:dpdcHost-all_domains. Specifying these parameters to run the KD4configDC command, with authorized user userABC:
KD4configDC enable env 8 host host1 user userABC displaygroup all_domains
Changing existing values for the domain list or display group: To update an existing section of the configuration file by changing the value of either the domainlist or displaygroup parameter, you must first disable that section of the configuration file by running the KD4configDC command using the disable parameter (see Disabling data collection on page 224), specifying the current values for the domainlist or displaygroup parameters. After the section is disabled, run the KD4configDC command again, using the enable parameter and specifying the desired values for the domainlist and displaygroup parameters. Specifying the password parameter: The values specified by the user and pswd parameters are used to perform an HTTP basic authentication over the HTTPS session. The user and password combination must be a valid user ID and password defined using the administration interface of the DataPower SOA appliance. See the DataPower documentation for more information about creating authorized user names and passwords. If the pswd parameter is specified in the KD4configDC command, its value is immediately encoded and saved in the configuration file, and you are not prompted for the password. Any password that had previously been specified for an existing section (that matches the search according to the other parameters) is replaced by the new password value. For example, if an existing section for host name H100 specified an authorized user of u2233, there would already be an encoded value of the valid password stored in the configuration file. To change the password value to x1y2z3, run the KD4configDC command:
KD4configDC enable env 8 host H100 user u2233 pswd x1y2z3
Specifying optional parameters: If any of the remaining optional parameters, (port, path, or poll) are specified as part of running the KD4configDC command, their values are stored in the configuration file in either the existing or
219
newly created section. These values are not used as part of the matching criteria for locating existing sections of the configuration file. The data collector uses the values in the host, port, and path parameters to construct the URL in the form of https://host:port/path that is used as the target of the messages sent to the DataPower SOA appliance.
Considerations for enabling data collection for DataPower monitoring

As previously described, you can use variations of the parameters specified in the KD4configDC command to define properties that configure the monitoring of one or more DataPower SOA appliances. The following sections illustrate several possible configurations. Multiple connections to the same DataPower SOA appliance: The DataPower configuration file supports multiple connections to the same DataPower SOA appliance by defining multiple sections of the configuration file with the same host and port properties. There are several reasons why you might want to do this, but the most obvious reason is to allow the data collector to use more than one set of authentication credentials. For example, a DataPower SOA appliance might have three domains (dom1, dom2 and dom3) and two users (userA, with access only to dom1 and dom2, and userB with access only to dom3). In this situation, neither userA nor userB can be used to access all of the domains on the appliance. To monitor all of the domains on the appliance, you must define two sections in the DataPower configuration file, one that specifies userA in one section and userB in the other section. To define the two sections in the configuration file, run KD4configDC command twice, once for each user:
KD4configDC enable env 8 host dpHost1 user userA domainlist "dom1,dom2" KD4configDC enable env 8 host dpHost1 user userB domainlist dom3
Restricting the list of domains being monitored: You can use the domainlist parameter to restrict the list of domains being monitored for a given user. For example, if userA has access to dom1 and dom2, but you are interested in monitoring only dom1, the domainlist parameter can specify only dom1 to instruct the data collector to not monitor domain dom2:
KD4configDC enable env 8 host dpHost1 user userA domainlist dom1
For each section in the DataPower configuration file, the domains that are monitored depend on the domains to which the user in that section has authorization, and the list of domains specified in the domainlist parameter for that section. If this property is not specified, then all domains that are authorized to the user for that section are monitored. Separating and aggregating data with the displaygroup parameter: The displaygroup parameter gives you substantial control over how the information from DataPower SOA appliances is separated or aggregated in the Tivoli Enterprise Portal views. Following are some examples of the ways that the displaygroup parameter can be used to separate or aggregate data. Separating data by host name or display group: Suppose that you have two DataPower SOA appliances (with different users and domains defined on each) and
220
Installation Guide
you want to view the information from these two appliances separately under two different nodes in the Tivoli Enterprise Portal Navigator view. Because there are two DataPower SOA appliances, there must be at least two sections in the DataPower configuration file, one for each appliance hostname or IP address. Separation of the information from these two appliances can be done without using the displaygroup parameter if the two sections of the configuration file have different values for the host parameter. For example:
KD4configDC enable env 8 host dpHost1 user userA KD4configDC enable env 8 host dpHost2 user userB
Note that the node name that is displayed in the Tivoli Enterprise Portal is based on the value of the host parameter if the displaygroup parameter is not specified. As long as the two sections of the configuration file have different values for the host parameter, IBM Tivoli Composite Application Manager for SOA separates the data between the two appliances and displays it under two different nodes (for example, D4:dpdcHost-dpHost1 and D4:dpdcHost-dpHost2) in the Tivoli Enterprise Portal Navigator view. Alternatively, you could use the displaygroup parameter to specify a more meaningful string than by using the value of the host parameter. As long as the values fordisplaygroup for the two sections are different, the data is separated under different Tivoli Enterprise Portal Navigator nodes. For example:
KD4configDC enable env 8 host dpHost1 user userA displaygroup host1Domains KD4configDC enable env 8 host dpHost2 user userB displaygroup host2Domains
Because the displaygroup parameter is specified, the node name is created from those values and should be displayed in the Tivoli Enterprise Portal Navigator view as D4:dpdcHost-host1Domains and D4:dpdcHost-host2Domains. However, note also that in this case, the length of the node name exceeds 20 characters, so each node name is truncated, as D4:dpdcHost-host1Dom and D4:dpdcHost-host2Dom. Separating data between domains by domain list: Suppose that you have a DataPower SOA appliance with a single user, userA, and two domains, dom1 and dom2. You can configure the data collector to separate the information from these two domains under two different nodes in the Tivoli Enterprise Portal Navigator view by creating two sections in the DataPower configuration file. The first section specifies a domainlist parameter of dom1 and a displaygroup parameter of, for example, Dom1, and the second section specifies a domainlist parameter of dom2 and a displaygroup parameter of, for example, Dom2. Example:
KD4configDC enable env 8 host dpHost1 user userA domainlist dom1 displaygroup Dom1 KD4configDC enable env 8 host dpHost1 user userA domainlist dom2 displaygroup Dom2
The different values for the displaygroup parameter cause IBM Tivoli Composite Application Manager for SOA to create two display groups that map to two different Tivoli Enterprise Portal Navigator view nodes: D4:dpdcHost-Dom1 and D4:dpdcHost-Dom2, and the domainlist parameters restrict the data collected in each of those display groups to just the intended domain, even though userA happens to have access to both domains.
221
Aggregating data across multiple domains: Suppose that you have a DataPower SOA appliance with a single user, userA, and two domains, dom1 and dom2. If the displaygroup parameter is not specified in the section of the configuration file, the node name is created from the host parameter, and the information for both dom1 and dom2 is aggregated under a single node (D4:dpdcHost-dpHost) in the Tivoli Enterprise Portal Navigator view. Aggregating data across multiple domains under multiple nodes: To aggregate the data from domains domA1 and domB1 under one node name and the data from domA2 and domB2 under a different node name, configure four sections in the DataPower configuration file: v user userA, domainlist domA1, displaygroup Group1 v user userB, domainlist domB1, displaygroup Group1 v user userA, domainlist domA2, displaygroup Group2 v user userB, domainlist domB2, displaygroup Group2 Example:
KD4configDC enable env displaygroup Group1 KD4configDC enable env displaygroup Group1 KD4configDC enable env displaygroup Group2 KD4configDC enable -env displaygroup Group2 8 host dpHost user userA domainlist "domA1" 8 host dpHost user userB domainlist "domB1" 8 host dpHost user userA domainlist "domA2" 8 host dpHost user userA domainlist "domB2"
This causes IBM Tivoli Composite Application Manager for SOA to aggregate the information from domA1 and domB1 under the Tivoli Enterprise Portal Navigator node D4:dpdcHost-Group1 and to aggregate the information from domA2 and domB2 under the Tivoli Enterprise Portal Navigator node D4:dpdcHost-Group2. Aggregating data across all domains on a single host with multiple users: Suppose that you have a DataPower SOA appliance with two users (userA and userB) that each have access to different sets of domains (userA has access to domains named domA1 and domA2. the other user, userB, has access to domains named domB1 and domB2, respectively). To monitor all of these domains, the DataPower configuration file must have at least two sections, one with a user parameter value of userA and one with a user parameter value of userB, but each specifying the same value for the host name in the host parameter. Example:
KD4configDC enable env 8 host dpHost user userA KD4configDC enable env 8 host dpHost user userB
If the displaygroup parameter is not specified, the information from all four domains would be aggregated under the same Tivoli Enterprise Portal Navigator node, for example, D4:dpdcHost-dpHost. Aggregating data for a cluster of appliances: You might have a collection of DataPower SOA appliances that are identically configured because they are used in a load-balancing or fail over situation. Because each appliance has its own hostname or IP address, there must be at least one section in the configuration file for each appliance to inform the data collector how to communicate with each appliance.
222
Installation Guide
If the displaygroup parameter is not used, then the information for each of these appliances is separated into different nodes in the Tivoli Enterprise Portal Navigator view (for example, D4:dpdcHost-dpHost1), because the host parameter is used by default. To see how this cluster of appliances is performing as a whole, without regard to the performance of individual appliances, specify the same displaygroup parameter (for example, Clust1) for every appliance. This causes the data collector to aggregate the data from all of these devices into a single display group, which is then displayed under a single Tivoli Enterprise Portal Navigator node (for example, D4:dpdcHost-Clust1) Example:
KD4configDC enable env 8 host dpHost1 user userA displaygroup Clust1 KD4configDC enable env 8 host dpHost2 user userA displaygroup Clust1
Additional considerations: Combining configurations: You can mix and match any of the various configurations described in this chapter, which gives you a great deal of flexibility in defining how to aggregate or separate data in the Tivoli Enterprise Portal views. This flexibility might result in some DataPower domains being specified in more than one section. This is not considered an error. Duplicated domains: You might want one section defined to allow data for a domain to be displayed on its own under one Tivoli Enterprise Portal Navigator node, and another section (or sections) defined to show the data for that domain aggregated with other domains, on the same or on a different machine. This is possible, but be aware that this results in the data for duplicated domains being retrieved multiple times by the data collector (once for each section in which it is configured). In this situation performance might be affected. Aggregation defaults: By default, if no domainlist parameter and no displaygroup parameter are used at all in the DataPower configuration file, the DataPower data collector aggregates data for all of the monitored domains on a single DataPower SOA appliance (even if the domains are accessed using different credentials), and keeps the data from each DataPower SOA appliance separated. Adding appliances to, or removing appliances from display groups: As you define your display groups, you should decide if the display group will always monitor only one appliance or multiple appliances, and once that display group is put into production, do not modify it by adding a second appliance, or by removing appliances to leave only one appliance monitored in the display group. If your goal in this display group is to monitor a single domain on a single appliance, then after it is put into production, do not add a second appliance to that display group. If your goal is to monitor one domain across a set of appliances, then add at least the second appliance while you are still in development and test mode. After you put this display group into production, ensure that there are always at least two appliances monitored. You can increase from a cluster of two appliances to three or more as needed. However, if you remove appliances from the display group so that there is only one remaining appliance, the node name attribute changes, and a new subnode identifier is displayed in the Tivoli Enterprise Portal Navigator Physical view. If you modify a display group that contains a single appliance by adding a second appliance, its subnode identifier will also change, and a new subnode with the same name is displayed on the Tivoli Enterprise Portal Navigator Physical view. You must
223
then delete the offline subnode to remove the duplicate names in the view. Any historical data that you collected with the original subnode name is no longer associated with the new subnode name.

This section describes the procedures for disabling data collection in the DataPower environment.
Upgrading the data collector

If you are upgrading the data collector for the DataPower environment, do not use the disable option of the KD4configDC script or the Data Collector Configuration Utility described in this section. Instead, you should complete the following steps: 1. Stop the DataPower data collector using the stopDPDC command (see Starting and stopping the data collector on page 225 for more information. 2. Deregister the service or daemon, if applicable. See Running the DataPower data collector as a Windows service or UNIX daemon on page 225 for the procedures to stop a registered DataPower data collector, and deregistering the service to remove it from the list of Windows services, if applicable. See Chapter 2, Upgrading from a previous installation, on page 19 for more information about upgrading your monitoring environment from a previous version.
Disabling data collection using the Data Collector Configuration Utility

To disable data collection using the Data Collector Configuration Utility, complete these steps: 1. Run the Data Collector Configuration Utility (see Running the Data Collector Configuration Utility on page 130): a. Select the DataPower SOA Appliance runtime environment. b. Select the Configure DataPower Instance option. c. Select the option to disable data collection. For the remaining input parameters, refer to Table 9 on page 216 for a description of the information that is required, and see the additional information and examples of running the KD4configDC command to learn more about how to specify these parameters for your environment. d. Specify the DataPower Host Name. e. Specify the DataPower user ID. f. Specify the DataPower password. g. The default DataPower port number (5500) and the default polling interval (10 seconds) is provided. Accept these defaults or type over them to specify different values. h. Specify the DataPower Path. i. Specify the DataPower Domain List. j. Optionally specify the DataPower Display Group. k. Wait for the configuration utility to complete the operation. l. Exit the utility.
Disabling data collection using the KD4configDC command

When you run the KD4configDC command to disable monitoring of a DataPower SOA appliance, use the simplest syntax for running the KD4configDC command:
224
Installation Guide
KD4configDC disable env 8 host <host> user <user>
The DataPower configuration file is searched for an existing section that matches the specified host and user and that has no domainlist parameter and no displaygroup parameters defined. If a matching section is found, the section is removed from the file. If no matching section is found, an error message is issued and the file remains unchanged. If the domainlist or displaygroup parameters are specified in the KD4configDC command, they become part of the matching criteria that determines whether the section exists and removed if found. All other parameters (port, path, poll, or password) are not required and are ignored, if specified on the command line.
Starting and stopping the data collector

To start the DataPower data collector, open a command prompt, navigate to /KD4/bin and run the startDPDC script. Optionally, you can specify the background option to start the data collector proxy as a disconnected task. Examples:
startDPDC.bat startDPDC -background ./startDPDC.sh
Once started, the data collector monitors the console for commands entered by the user. The only supported commands are stop, quit, and exit, all of which initiate an orderly shutdown of the DataPower data collector. When one of these commands is entered, the data collector waits for all communication sessions to end before the process terminates. When in background mode, you can stop the data collector by running the stopDPDC script. While the data collector is running, you can use the KD4configDC command to update the DataPower data collector configuration file and change which DataPower SOA appliances and domains are being monitored. You do not need to stop and restart the data collector to activate these changes. The running data collector detects the changed configuration file within 40 seconds and adjust its monitoring to reflect the updated configuration.
Running the DataPower data collector as a Windows service or UNIX daemon

IBM Tivoli Composite Application Manager for SOA provides the capability to register and start the DataPower data collector as a service on supported Windows operating systems, or as a daemon on supported UNIX operating systems. Running the DataPower data collector in this way improves availability, because the data collector can be automatically restarted in the event of a system restart. After installing ITCAM for SOA, the DataPower data collector is not automatically registered as a service or daemon, so you can still start the data collector using the startDPDC script as described in Starting and stopping the data collector.
225
Registering the DataPower data collector as a Windows service or UNIX daemon

To register the DataPower data collector as a Windows service or UNIX daemon, complete the following steps: 1. If the data collector is already started, stop the data collector. 2. Register the DataPower data collector using either the Data Collector Configuration Utility or the KD4configDC command. v Using the Data Collector Configuration Utility (see Running the Data Collector Configuration Utility on page 130): a. Start the Data Collector Configuration Utility. b. Select the DataPower SOA Appliance runtime environment. c. Select the option to Register or unregister DataPower as a service or daemon. d. Select the option to Register DataPower as service or daemon e. You are reminded to stop the DataPower data collector before registering it. Click Next to continue. f. Wait for the operation to complete. g. Exit the Data Collector Configuration Utility. v Using the KD4configDC command (see Running the KD4configDC script on page 147), on Windows, run this command:
KD4configDC.bat registerService env 8
On AIX, Linux, Solaris, or HP-UX operating systems, run this command:

./KD4configDC.sh registerService env 8
Starting the registered DataPower data collector

After the DataPower data collector is registered as a service or daemon, it is set to start automatically when the system is rebooted. The data collector is not started immediately, however, in case the data collector is already running in console mode. To start the DataPower data collector manually for Windows operating systems, use the Windows Service Manager, or run either of these commands:
net start kd4dpdc startDPDC.bat [background]
To start the DataPower data collector manually for Linux, AIX, Solaris, or HP-UX operating systems, you can run this command:
./startDPDC.sh [background]
You can still start the DataPower data collector using the existing startDPDC script. If the data collector is registered as a Windows service, however, the service starts instead of a console session.
Stopping the registered DataPower data collector

To stop the DataPower data collector manually on Windows, use the Windows Service Manager, or run either of these commands:
net stop kd4dpdc stopDPDC.bat [background]
To stop the DataPower data collector manually for Linux, AIX, Solaris, or HP-UX operating systems, run this command:
226
Installation Guide
./stopDPDC.sh [background]
Removing the DataPower data collector from the list of Windows services
To remove the DataPower data collector from the list of Windows services, complete the following steps: 1. If the data collector is already running, stop it. 2. Remove the DataPower data collector from the list of Windows services using either the Data Collector Configuration Utility or the KD4configDC command. v Using the Data Collector Configuration Utility (see Running the Data Collector Configuration Utility on page 130): a. Start the Data Collector Configuration Utility. b. Select the DataPower SOA Appliance runtime environment. c. Select the option to Register or unregister DataPower as a service or daemon. d. Select the option to Unregister DataPower. e. You are reminded to stop the DataPower data collector before unregistering it as a service. Click Next to continue. f. Wait for the operation to complete. g. Exit the Data Collector Configuration Utility. v Using the KD4configDC command (see Running the KD4configDC script on page 147), run this command:
KD4configDC.bat deregisterService env 8
Deregister before uninstalling the product: Note that when you uninstall IBM Tivoli Composite Application Manager for SOA, the process does not include removing the DataPower data collector from the list of Windows services. Because this process uses the Data Collector Configuration Utility and the KD4configDC script, you should always deregister the DataPower data collector Windows service before uninstalling the product.
Error handling
Errors that occur while registering, starting, stopping, or deregistering the service are written to the Windows event log, and also to the IBM Tivoli Monitoring RAS logs found in <ITM_Home>\logs directory. This logfile name follows the IBM Tivoli Monitoring logfile naming convention for ITCAM for SOA, <machinename>_d4_<logid>.log (for example, omut3_d4_463742c2-01.log) Consult both the Windows event log and the IBM Tivoli Monitoring RAS logs in case of service errors.
Communicating between data collector and appliance

Approximately every 10 minutes, the data collector queries the DataPower SOA appliance to see if the domain list has changed. If the domain list has changed, the data collector updates its information as needed and begins monitoring new domains defined on the Data Power appliance. The data collector polls for data at a frequency defined by the poll parameter (the default is 10 seconds). Communication errors between the data collector and the DataPower SOA appliance that prevent the collection of data are logged to the console (the
227
command line session where the startDPDC script was executed) and to the operations log. If the data collector is running in background mode, errors are written to the operations log. Additional information concerning the communications between the data collector and DataPower SOA appliance can be obtained by setting the operations logging level for the data collector from error to info using the updateLogging Take Action command from the Tivoli Enterprise Portal.
Optimizing performance
The data collector is configured by default to monitor all services and operations, but with no logging of message content. This configuration optimizes the performance of processing data by not having to handle message content when it is not needed. When you modify any monitor controls to specify a content logging setting other than none, all of the full message content for all services and operations is retrieved from the appliance, and the data collector applies the configured monitor control rules (headers/body/full) by service and by operation. See Checking additional optional settings on page 205 for information about configuring the CaptureMode setting.
Limitations
You can control the monitoring to limit the collection of data to specific services and operations, but you cannot use filter controls to reject messages to specific services or operations. To filter (reject) messages, use the Policy Rules and Actions of the DataPower Web Services Proxy configuration. If the transforms (as described in Configuring processing rules for DataPower Web Services Proxy gateways on page 206) are not activated, the data collector does not generate a meaningful correlator for messages flowing through the DataPower SOA appliance, so this data does not render properly in the topology, sequence diagram, and pattern views in the IBM Web Services Navigator. The DataPower data collector creates metric, content, operation and trace log files, but because message filtering is not supported, it does not create any action log files. Depending on your configuration, the data collector creates multiple metric and content log files to describe the existence of several different display groups. Each display group is represented as a separate node in the Tivoli Enterprise Portal Navigator view. The log files for each display group hold the data for all of the DataPower SOA appliances that are configured for that display group, which might span multiple DataPower domains and include data from multiple DataPower SOA appliances. Before you attempt to delete an application domain from DataPower that is being monitored by the DataPower data collector, you must either run the KD4configDC command to disable monitoring of that application domain, or stop the data collector. Otherwise, when you attempt to delete the domain using the DataPower administration console, you receive an error and the domain cannot be deleted.
228
Installation Guide
Troubleshooting Communication failures

In the event of a communications failure, the data collector attempts to initialize itself again and reestablish communication with the target DataPower SOA appliance after the next polling interval (the polling interval is specified by the poll parameter. This process is repeated each polling interval until communication is successfully reestablished, or until the data collector is stopped. Setting the operations logging level to info gives you the best indication of status of the communications between the data collector and the appliance.
Synchronizing time between computer systems

For data to display properly in the Tivoli Enterprise Portal, the DataPower SOA appliance, the data collector system and the Tivoli Enterprise Monitoring Server system must have their clocks synchronized within 5 minutes of each other, in terms of the UTC time they report.
Password problems
User IDs and passwords for DataPower SOA appliances are created and maintained at the appliance. See the documentation that is provided with your DataPower SOA appliance for information about creating and managing user IDs and passwords. When you have reset this information at the DataPower SOA appliance, use the KD4configDC command to update the DataPower configuration file with the latest user ID and password values for the appropriate section of the file.
Logging and Tracing

The data collector in the DataPower environment uses the same operation and trace log files as other environment types supported by the IBM Tivoli Composite Application Manager for SOA, but rather than creating separate operation and trace files for each display group, it creates a single operation file and a single trace file for all display groups. The view in the Tivoli Enterprise Portal continues to operate as though you can configure logging and tracing for each display group, but the settings for all DataPower display groups are considered when the settings for the single log or trace writer instance are initialized, as follows: v If any display group has trace set to ON, the DataPower data collector records tracing information for all display groups to the trace log. v The DataPower data collector uses the lowest severity log setting (Info, Warning, or Error) of all display groups. For example, if a display group has a log setting of Info, then all informational, warning, and error messages for all display groups are written to the operations log. The DataPower data collector does not update the global configuration settings seen in the Tivoli Enterprise Portal to reflect the actual settings being used for the various display groups. As a result, the Tivoli Enterprise Portal might still show different log and trace settings for each display group, even though the data collector is using common settings for all display groups. In addition to the operations log, the DataPower data collector issues messages to the console where the startDPDC script was run. All messages issued to the
229
console are also recorded in the operations log. In background mode, information is written to the operations log. On Windows, errors might also be displayed in the Windows Application Event log.
Displaying the DataPower Console interface

You can select a DataPower SOA appliance that is displayed in a row of the Services Inventory attributes table in the Performance Summary workspace of the Tivoli Enterprise Portal, or select an instance of a DataPower mediation operation from one of the Operational Flow displays, and follow the procedure described in this section to display the DataPower Console user interface in a Tivoli Enterprise Portal view. You can then use this sophisticated interface to configure the DataPower SOA appliance and the policies that the appliance applies to services traffic. To display the DataPower Console user interface, complete the following steps: 1. From the Tivoli Enterprise Portal, navigate to the Performance Summary workspace and display the Services Inventory attributes table view. 2. Select a row in the table from the DataPower system referenced in the Node Name column, and click the link icon to select the DataPower Console option. The DataPower Console is displayed in a Tivoli Enterprise Portal view, similar to the example shown in Figure 59.
Figure 59. The DataPower Console
Considerations when displaying the DataPower Console view

The following sections provide additional limitations, restrictions, and considerations to keep in mind as you launch the DataPower Console user interface.
230
Installation Guide
Start only from a row representing a DataPower environment

You cannot start a DataPower Console session from a row in the Services Inventory attributes table that represents a non-DataPower application server runtime environment. DataPower SOA appliances are identified by a value of DataPower in the Application Server Environment column of the Services Inventory attributes table. If you select a row that does not represent metrics data from a DataPower application server runtime environment, a browser session is started with the KD4LN0001E error message displayed. If you select a row that does not represent a DataPower appliance, the link to the DataPower Console is not displayed.
Cannot start from a row with aggregated DataPower metrics

Because of how the data collector works and the way that the Application Server Node Name field is populated by the DataPower data collector, you cannot display the DataPower Console from a Services Inventory attributes table row that represents metrics aggregated from more than one physical DataPower SOA appliance. In the case of aggregated metric data from more than one DataPower SOA appliance, the Node Name field is blank to prevent possibly displaying the DataPower Console for the wrong DataPower SOA appliance. If you select a row in the table that represents metrics aggregated from more than one physical DataPower SOA appliance, a browser session is started with error message KD4LN0002E displayed.
The DataPower Console must be configured for Port 9090

The link to the DataPower Console operates correctly only if the DataPower Console is configured for port 9090 (port 9090 is also the default port number). See the DataPower WebGUI Guide and the DataPower CLI Reference Guide for information on configuring the port.
Logging in to DataPower
If you have not previously logged in to the DataPower Console user interface in the current browser session, the Web browser session opens to the login page. You need to log in with a valid user name and password to continue. If you have previously logged in, the session opens to the main page of the user interface. See your DataPower documentation for more information about user names and password, and consult your local system administrator for assistance if needed.
231
232
Installation Guide
Chapter 14. Configuring data collection: WebSphere Message Broker

IBM Tivoli Composite Application Manager for SOA provides support for data collection in the following IBM WebSphere Message Broker environments: v IBM WebSphere Message Broker Version 6.0.0.5 or later. v IBM WebSphere Message Broker Version 6.1.0.2 or later. Refer to your IBM WebSphere Message Broker documentation for procedures on installing or upgrading to these minimum supported versions. After configuring your WebSphere Message Broker environment for data collection, see the IBM Tivoli Composite Application Manager for SOA Users Guide for information about displaying WebSphere Message Broker data in service-to-service topology views.
Upgrading the data collector directory structure

For this version of IBM Tivoli Composite Application Manager for SOA, the directory structure used for maintaining WebSphere Message Broker data collector information is changed from previous releases. Before you enable data collection for this version of ITCAM for SOA, you must complete the following general steps: 1. Disable data collection on all of your existing brokers, execution groups, and message flows, using the procedures described in the Installation Guide for your previous version of ITCAM for SOA. If you are monitoring WebSphere Message Broker on supported z/OS operating systems, see the Configuring IBM Tivoli Composite Application Manager for SOA on z/OS for the procedure to disable all data collection before upgrading your ITCAM for SOA installation to version 7.1.1. The Data Collector Configuration Utility and the KD4configDC script provided with ITCAM for SOA Version 7.1.1 are only aware of the directory structure provided with this release. When you attempt to enable data collection, if any configuration files from a previous version are detected, an error message is issued, reminding you that all previous data collection must be disabled before you can enable data collection using the utility or scripts from this version of the product. 2. After disabling data collection, upgrade your ITCAM for SOA installation to Version 7.1.1 if you have not already done so. See Chapter 2, Upgrading from a previous installation, on page 19 for the upgrade procedures. If you upgraded your ITCAM for SOA installation to Version 7.1.1 without first disabling previous message broker data collection, you can run a special script, KD4disableMBDC-71.bat (on Windows operating systems, or KD4disableMBDC-71.sh on Linux and UNIX operating systems), to disable data collection and remove configuration files from previous versions of ITCAM for SOA, before enabling data collection again for ITCAM for SOA Version 7.1.1. Locate the KD4disableMBDC-71.bat script in the <ITCAM4SOA_Home>/KD4/ bin directory. Run the script using the same syntax as the KD4configDC script for WebSphere Message Broker. For example:
KD4disableMBDC-71.bat disable env 10 <broker_name> <execution_group_name> <message_flow_name>
233
The script accepts only the disable parameter (not enable), and only the value of 10 for the environment parameter env, signifying WebSphere Message Broker. Specify the broker name, execution group name, and message flow name as usual. 3. Enable data collection using the Data Collector Configuration Utility or the KD4configDC script provided with ITCAM for SOA Version 7.1.1. For WebSphere Message Broker on supported z/OS operating systems, see the Configuring IBM Tivoli Composite Application Manager for SOA on z/OS for the procedure to upgrading and enabling data collection.

You can enable data collection in the WebSphere Message Broker environment for all operating systems supported by IBM Tivoli Composite Application Manager for SOA version 7.1.1 except for HP-UX PA-RISC. Use either the Data Collector Configuration Utility or the KD4configDC script to enable data collection for a specified message broker, execution group, and message flow. The following steps outline the general procedure for enabling data collection: v On supported Windows operating systems: 1. Log in as the user who installed the ITCAM for SOA monitoring agent. This user should also be a member of the mqm and mqbrkrs groups. 2. Bring up the correct Message Broker Command Console for your version of WebSphere Message Broker: If you are enabling data collection for WebSphere Message Broker Version 6.0.0.5 or later, select Start > All Programs > IBM WebSphere Message Broker 6.0 > Command Console. If you are enabling data collection for WebSphere Message Broker Version 6.1.0.2 or later, select Start > All Programs > IBM WebSphere Message Broker 6.1 > Command Console. Multiple broker installations: You might have both versions of WebSphere Message Broker installed on your system. Be sure to bring up the correct command console for the version of the broker whose message flows are being enabled for data collection. 3. Do either of the following tasks: Run the Data Collector Configuration Utility (see Using the Data Collector Configuration Utility on page 237). Run the KD4configDC.bat script (see Using the KD4configDC command on page 238). v On supported Linux and UNIX operating systems: 1. Log in as the user who installed the ITCAM for SOA monitoring agent. This user should also be a member of the mqm and mqbrkrs groups. 2. Ensure that the Message Broker profile is in your shell profile, or source it manually by running one of the following commands: For WebSphere Message Broker Version 6.0.0.5 or later:
. /opt/IBM/mqsi/6.0/bin/mqsiprofile
For WebSphere Message Broker Version 6.1.0.2 or later:

Multiple broker installations: You might have both versions of WebSphere Message Broker installed on your system. Be sure to source the proper profile in your shell. Make sure only to source one profile, as sourcing multiple profiles can lead to unexpected results.
234
Installation Guide
3. Do either of the following tasks: Run the Data Collector Configuration Utility (see Using the Data Collector Configuration Utility on page 237). Run the KD4configDC.sh script (see Using the KD4configDC command on page 238). v For supported z/OS operating systems, refer to Configuring IBM Tivoli Composite Application Manager for SOA on z/OS for the procedures to enable data collection for WebSphere Message Broker. Enabling data collection in the WebSphere Message Broker environment involves these tasks that are automatically performed when you run either the Data Collector Configuration Utility or the KD4configDC script: v Add the runtime directory of the data collector user exit code (also known as the LEL file) to the WebSphere Message Broker user exit path. v Update the list of active user exits for the specified message broker, execution group and message flow to include the data collector user exit. Note that the specified message broker is restarted as part of the data collection configuration process.
Considerations for multiple brokers

In environments where multiple brokers are defined on the same machine, all execution groups for all brokers will load the LEL file from the same runtime library directory: v For WebSphere Message Broker Version 6.0.0.5, the runtime directory is <ITCAM4SOA_Home>\KD4\config\wmb\lib. v For WebSphere Message Broker Version 6.1.0.2, the runtime directory is <ITCAM4SOA_Home>\KD4\config\wmb61\lib. This might result in file sharing or locking problems on some platforms when enabling data collection for the message broker data collector. For example, when data collection for a message flow for one broker is enabled while another broker on the same computer is running and already has a message flow enabled, the enable process on some platforms might not be able to copy the LEL file from the install directory (<ITCAM4SOA_Home>KD4\lib) to the runtime library directory, because the file already exists in the target directory and is loaded and locked by the other broker process. In this case, any copy errors are written to the configMBDC.log file, but are not displayed to you, because the LEL file already exists in the target directory. When this occurs, the LEL file in the runtime library directory cannot be updated to a new level until you stop all brokers and enable data collection again.

You can disable data collection in the WebSphere Message Broker environment for all operating systems supported by IBM Tivoli Composite Application Manager for SOA version 7.1.1 except for HP-UX PA-RISC. You can disable data collection for a specified message broker, execution group, and message flow using either the Data Collector Configuration Utility or the KD4configDC script. The following steps outline the general procedure for disabling data collection: v On supported Windows operating systems:
235
1. Log in as the user who installed the ITCAM for SOA monitoring agent. This user should also be a member of the mqm and mqbrkrs groups. 2. Bring up the correct Message Broker Command Console for your version of WebSphere Message Broker: If you are enabling data collection for WebSphere Message Broker Version 6.0.0.5 or later, select Start > All Programs > IBM WebSphere Message Broker 6.0 > Command Console. If you are enabling data collection for WebSphere Message Broker Version 6.1.0.2 or later, select Start > All Programs > IBM WebSphere Message Broker 6.1 > Command Console. Multiple broker installations: You might have both versions of WebSphere Message Broker installed on your system. Be sure to bring up the correct command console for the version of the broker whose message flows are being disabled for data collection. 3. Do either of the following tasks: Run the Data Collector Configuration Utility (see Using the Data Collector Configuration Utility on page 237). Run the KD4configDC.bat script (see Using the KD4configDC command on page 238). v On supported Linux and UNIX operating systems: 1. Log in as the user who installed the ITCAM for SOA monitoring agent. This user should also be a member of the mqm and mqbrkrs groups. 2. Ensure that the Message Broker profile is in your shell profile, or source it manually by running one of the following commands: For WebSphere Message Broker Version 6.0.0.5 or later:
For WebSphere Message Broker Version 6.1.0.2 or later:

Multiple broker installations: You might have both versions of WebSphere Message Broker installed on your system. Be sure to bring up the correct command console for the version of the broker whose message flows are being disabled for data collection. 3. Do either of the following tasks: Run the Data Collector Configuration Utility (see Using the Data Collector Configuration Utility on page 237). Run the KD4configDC.sh script (see Using the KD4configDC command on page 238). v For supported z/OS operating systems, refer to Configuring IBM Tivoli Composite Application Manager for SOA on z/OS for the procedures to disable data collection for WebSphere Message Broker. Disabling data collection in the WebSphere Message Broker environment includes these tasks that are automatically performed when you run either the Data Collector Configuration Utility or the KD4configDC script: v Update the list of active user exits for the specified message broker, execution group and message flow to remove the data collector user exit. v Remove the data collector user exit runtime directory from the WebSphere Message Broker user exit path when data collection for all message flows has been disabled.
236
Installation Guide
Note that the specified message broker is restarted as part of the data collection configuration process.
Considerations for multiple brokers

In environments where multiple brokers are defined on the same machine, all execution groups for all brokers will load the LEL file from the same runtime library directory: v For WebSphere Message Broker Version 6.0.0.5, the runtime directory is <ITCAM4SOA_Home>\KD4\config\wmb\lib. v For WebSphere Message Broker Version 6.1.0.2, the runtime directory is <ITCAM4SOA_Home>\KD4\config\wmb61\lib. This might result in file sharing or locking problems on some platforms when disabling data collection for the message broker data collector. For example, When data collection is disabled for the last message flow (of all brokers), the disable process attempts to delete the LEL files from the runtime library directories. If another broker (other than the one whose message flow is being disabled) is running, it is possible for this other broker to load and lock the LEL file, even if there are no flows on that broker that are enabled for monitoring. In this case, the deletion of the LEL files might fail on some platforms. The disable process issues a warning message when this condition occurs, and after the disable process completes, you will need to stop all brokers and manually delete the LEL files.

Using the Data Collector Configuration Utility, complete these steps: 1. Start the Data Collector Configuration Utility in either the default graphical user interface mode, in console mode, or in silent mode. See Running the Data Collector Configuration Utility on page 130 for more information. 2. Select the option to configure WebSphere Message Broker. 3. You are reminded that the message broker will be stopped to enable or disable data collection. Click Next to continue, or, if you do not want to stop the message broker at this time, click Cancel or Back. 4. Select the option to enable or disable data collection. 5. Specify the name of the Message Broker to be enabled for data collection. 6. Specify the name of the Execution Group within the specified Message Broker. Click Next.
237
Figure 60. Enabling data collection for WebSphere Message Broker
7. Specify the name of the Message Flow within the specified Execution Group. You can specify multiple message flows in this field by typing the list of message flow names, separated by commas. Click Next.
Figure 61. Enabling data collection for WebSphere Message Broker
8. Wait for the configuration utility to complete the operation. 9. Exit the utility.

This is the syntax of the KD4configDC script in the distributed environment:
KD4configDC.bat/.sh [enable | disable] env 10 broker_name execution_group_name message_flow_name1 [message_flow_name2 ... message_flow_namen]
In this version of the script, these are the options: enable Enable data collection for the specified message flow within the specified message broker and execution group.
238
Installation Guide
disable Disable data collection on the specified message flow. env The application server environment to configure, 10 (Message Broker)
Broker_name Name of the message broker. Execution_group_name Name of the execution group within the specified message broker to be configured. Message_flow_name Name of the message flow within the specified execution group to be configured. You must specify at least one message flow name. You can optionally specify more than one message flow name, separated by blank spaces. When you run the KD4configDC script, you are prompted to confirm that you want to stop the specified message broker to complete the configuration. If you want to stop the message broker, press Enter to continue. If you do not want to stop the message broker, enter CTRL-C to exit the script. The script verifies that there is not already another instance of the script running by looking for the file <ITCAM4SOA_Home>/KD4/config/configMBDC.running. This file is usually created each time the script is run, and then deleted automatically after the script completes. If another instance of KD4configDC is running on the same message broker, a message is displayed informing you that another instance is already running, and your instance of the script is stopped. You should wait for the other instance of the script to complete, and then run your script again. If, however, you are sure that another instance of the KD4configDC script is not currently running, it is possible that this configMBDC.running file might not have been deleted from a previous run of the KD4configDC script. You can delete this file manually and then run your script again. Enable Example: To enable a message flow named testFlow, which is associated with the Execution Group named testEGroup, which in turn belongs to the message broker named testBroker on Windows, run the KD4configDC script as follows:
KD4ConfigDC.bat -enable -env 10 testBroker testEGroup testFlow
Disable Example: To disable a message flow named testFlow, which is associated with the Execution Group named testEGroup, which in turn belongs to the message broker named testBroker on Windows, run the KD4configDC script as follows:
KD4ConfigDC.bat -disable -env 10 testBroker testEGroup testFlow
Upgrading: If you later upgrade an existing ITCAM for SOA v7.1.1 environment, you must re-enable at least one message flow within the Message Broker. All of the message flows within that Message Broker are then upgraded. Repeat this for all enabled Message Brokers as needed. Disabling data collection on message flows: If you have data collection enabled for a message flow that you no longer need to monitor, be sure to disable data collection for the message flow before the Message Broker is stopped when uninstalling the monitoring agent. If you do not disable the message flow first, you will not be able to list the message flow using the mqsilist command.
239
If this problem occurs, use one of the following procedures to recover the message flow: v Using the Toolkit, remove the message flow and then re-deploy it. v Restore the original data collector user exit code (LEL file) to the correct location by completing the following steps: 1. Reinstall the ITCAM for SOA version 7.1.1 monitoring agent. 2. Copy the correct LEL files for your version of WebSphere Message Broker: For WebSphere Message Broker Version 6.0.0.5: a. Create the directory <ITCAM4SOA_Home>\KD4\config\wmb\lib\. b. Obtain the mqsisoauserexit_wmb60_32bit.lel file or the mqsisoauserexit_wmb60_64bit.lel file (or both) from the <ITCAM4SOA_Home>\KD4\lib directory. c. Copy these files to <ITCAM4SOA_Home>\KD4\config\wmb\lib\. For WebSphere Message Broker Version 6.1.0.2: a. Create the directory <ITCAM4SOA_Home>\KD4\config\wmb61\lib\. b. Obtain the mqsisoauserexit_wmb61_32bit.lel file or the mqsisoauserexit_wmb61_64bit.lel file (or both) from the <ITCAM4SOA_Home>\KD4\lib directory. c. Copy these files to <ITCAM4SOA_Home>\KD4\config\wmb61\lib\. 3. Restart the message broker 4. Use the mqsilist command to verify that the message flow exists. After recovering the message flow, disable data collection using the KD4configDC script.
240
Installation Guide
Part 3. Completing your installation

At this point you should have completed all the appropriate steps in Part 1, Installing the product, on page 1 to install application support files and the monitoring agent in your IBM Tivoli Monitoring environment. If you are using the topology support for service registry and business process integration or service-to-service topology workspaces and views, you should have already configured SOA Domain Management Server and Tivoli Common Object Repository topology support. You should have configured your various runtime environments for data collection on each computer in your environment where services are being monitored, using the information in Part 2, Configuring for data collection, on page 125 of this guide. Now, use the remaining information in this part of the guide to complete the basic installation steps and verify the configuration. See these chapters for appropriate information: v Chapter 15, Verifying the installation and configuration, on page 243 v Chapter 16, Configuring for historical data collection, on page 251 v Chapter 17, Installing Discovery Library Adapters, on page 257 v Chapter 18, Configuring for Remote Deployment, on page 259 v Chapter 19, Installing Language Support, on page 263 v Chapter 20, Configuring IBM Tivoli Monitoring to forward events, on page 265 See also the IBM Tivoli Composite Application Manager for SOA Troubleshooting Guide for information about recovering from problems you might encounter while performing the installation.
241
242
Installation Guide
Chapter 15. Verifying the installation and configuration

After you have upgraded or installed IBM Tivoli Composite Application Manager for SOA into your IBM Tivoli Monitoring environment, configured for topology support, and enabled your runtime environments for monitoring and data collection by the ITCAM for SOA monitoring agent, complete these additional tasks, described in the sections that follow, to verify your installation and configuration. 1. Verify that the KD4BaseDirConfig.properties properties file was created successfully. See the section, Verifying the properties file, for details. 2. Verify that the components of IBM Tivoli Monitoring are started. See Verifying IBM Tivoli Monitoring components on page 244 for details. 3. Stop and restart your application server services as needed. 4. The monitoring agent is automatically configured during installation. You can configure it again at any time by completing the steps in Optional: Configuring the ITCAM for SOA monitoring agent on page 244. 5. The monitoring agent is automatically started during installation. See Starting and stopping the monitoring agent on page 245 for details on starting and stopping the monitoring agent. 6. Verify that metric log files are generated as expected when services traffic is monitored in your environment. See Generating initial metric log files on page 246 for details. 7. Start the Tivoli Enterprise Portal desktop client and verify that basic ITCAM for SOA workspaces are displayed. See Verifying Tivoli Enterprise Portal workspaces on page 247 for details.
Verifying the properties file

Check for a file named KD4BaseDirConfig.properties that is created automatically during installation. v For Windows operating systems, navigate to the %SYSTEMROOT%\system32\ drivers\etc directory and verify that the file exists and has an entry similar to the following example:
INSTALLDIR=C:\\IBM\\ITM\\TMAITM6\\
This example assumes that IBM Tivoli Monitoring is installed in the default directory, C:\IBM\ITM. If you installed to a different directory location, verify that this entry is correctly specified. v For Linux, AIX, HP-UX, or Solaris operating systems, navigate to the /etc directory and verify that the file exists and contains an entry similar to the following examples: For AIX operating systems:
INSTALLDIR=/opt/IBM/ITM/aix513/d4
For HP-UX on RISC processors:

INSTALLDIR=/opt/IBM/ITM/h11/d4
For HP-UX on Itanium processors:

INSTALLDIR=/opt/IBM/ITM/hpi116/d4
For Linux:
INSTALLDIR=/opt/IBM/ITM/li6243/d4
For Solaris:
INSTALLDIR=/opt/IBM/ITM/sol283/d4
For zLinux:
243
INSTALLDIR=/opt/IBM/ITM/ls3243/d4
These examples assume that IBM Tivoli Monitoring is installed in the default directory, /opt/IBM/ITM. If you installed to a different directory location, verify that this entry is correctly specified. See Resolving directory path variables on page xviii to determine the correct platform designation. The value in the INSTALLDIR variable represents the directory location where the \KD4 directory is located. The \KD4 directory contains logging and properties files used with IBM Tivoli Composite Application Manager for SOA. If the KD4BaseDirConfig.properties file does not already exist, the installation has likely failed to complete successfully. Check the installation log files and try the installation again. The file might not exist if you installed the monitoring agent using a non-root user on Linux or UNIX operating systems. In this case, you must manually copy the file from the <ITM_Home>/<platform>/d4/KD4/config directory to the /etc directory while logged in as a user with write access to the /etc directory.
Verifying IBM Tivoli Monitoring components

Open the Manage Tivoli Enterprise Monitoring Services utility and complete these steps: 1. Verify that the Tivoli Enterprise Monitoring Server is started. 2. Verify that the Tivoli Enterprise Portal Server is started. 3. If you plan to write services data to the data warehouse using the Warehouse Proxy, verify that the Warehouse Proxy is started. 4. Verify that the ITCAM for SOA agent is started. 5. Verify that the Eclipse Help Server is started, to access the searchable online help files for the monitoring agent in the IBM Eclipse Help System.
Optional: Configuring the ITCAM for SOA monitoring agent

After you have completed the documented procedures for installing and configuring the ITCAM for SOA monitoring agent, at a later time you might choose to modify the host name for the Tivoli Enterprise Monitoring Server. You can configure the monitoring agent again at any time by completing the following steps: v For supported Windows operating systems: 1. Right-click the ITCAM for SOA agent name and select Reconfigure to configure the agent. 2. Follow any on-screen prompts to configure the agent for your environment. When completed, the icon to the left of the ITCAM for SOA entry turns to a green circle with a check mark, indicating the configuration completed successfully. v For Linux, AIX, HP-UX, or Solaris operating systems: 1. Enter the following command:
./itmcmd config -A d4
2. Press Enter when you are asked if the monitoring agent connects to a monitoring server. 3. Type the hostname for the monitoring server. 4. Type the type of protocol that the monitoring agent uses to communicate with the monitoring server. You have four choices: IP, SNA, IP.SPIPE, or IP.PIPE. Press Enter to accept the default protocol (IP.PIPE).
244
Installation Guide
5. If you want to set up a backup protocol, enter that protocol and press Enter. If you do not want to use backup protocol, press Enter without specifying a protocol. If the method you have identified as Protocol 1 fails, Protocol 2 is used. See the IBM Tivoli Monitoring documentation for more information about available protocol selections. 6. Depending on the types of protocols you specified, provide the information described in Table 10 when prompted:
Table 10. Linux, AIX, HP-UX, and Solaris Protocol settings for communicating between the monitoring agent and Tivoli Enterprise Monitoring Server Protocol IP.UDP Value IP Port Number Description The listening port for the Tivoli Enterprise Monitoring Server to which this monitoring agent is connected. The default value is 1918.
IP.PIPE
IP.PIPE Port Number The listening port for the Tivoli Enterprise Monitoring Server to which this monitoring agent is connected. The default value is 1918. IP.SPIPE Port Number Network Name LU Name The listening port for the Tivoli Enterprise Monitoring Server to which this monitoring agent is connected. The default value is 3660. The SNA network identifier for your location. The LU name for the Tivoli Enterprise Monitoring Server. This LU name corresponds to the local LU Alias in your SNA communications software. The name of the LU6.2 LOGMODE. The default value is CANCTDCS.
IP.SPIPE
SNA
Log Mode
7. Press Enter to not specify the name of the KDC_PARTITION. 8. Press Enter when you are asked if you want to configure the connection to a secondary monitoring server. The default response is no. 9. Press Enter to accept the default for the Optional Primary Network Name (none). 10. Continue with the next section, Starting and stopping the monitoring agent.
Starting and stopping the monitoring agent

Start the agent from the Manage Tivoli Enterprise Monitoring Services utility by right-clicking the agent name, ITCAM for SOA, and selecting Start from the menu. Select Stop from the menu to stop the agent. On supported Linux, AIX, HP-UX, or Solaris operating systems you can also start the IBM Tivoli Composite Application Manager for SOA monitoring agent by running the following command:
./itmcmd agent start d4
Similarly, stop the agent by running this command:

./itmcmd agent stop d4
Starting the monitoring agent using a telnet session: If you use a telnet session to start the IBM Tivoli Composite Application Manager for SOA monitoring agent from a Bourne shell, the monitoring agent might be unexpectedly terminated when you exit the telnet session. To avoid this potential problem in a telnet session, enter the Korn shell (ksh), and then start the monitoring agent.
245
Generating initial metric log files

Complete these steps to verify the initial generation of metric log files: 1. Optionally stop the operation of the ITCAM for SOA agent by right-clicking it in the Manage Tivoli Enterprise Monitoring Services console and selecting Stop. 2. Generate some initial appropriate services traffic for your application server runtime environment. 3. Navigate to the <ITCAM4SOA_Home>\KD4\logs directory and verify that a metric log file was created with a name similar in format to KD4.<field1>.<field2>.<field3>.<field4>.<field5>.metric.log. Where: <ITCAM4SOA_Home> is the location where the ITCAM for SOA monitoring agent is installed. For example: v On Windows: C:\IBM\ITM\TMAITM6 v On Linux and AIX: /opt/IBM/ITM/<platform>/d4, where <platform> is one of several values, depending on the operating system, the type of computer system, and version of IBM Tivoli Monitoring installed. See Resolving directory path variables on page xviii for the procedure to determine the value of <platform>. <field1> Is an integer indicating the type of supported application server. Valid values include: v 1 = IBM WebSphere Application Server v 2 = Microsoft .Net v 3 = BEA WebLogic Server v 4 = JBoss v 5 = Customer Information Control System (CICS) Transaction Server v 6 = SAP NetWeaver v 7 = WebSphere Community Edition v 8 = DataPower SOA Appliance v 10 = WebSphere Message Broker <field2> This is the name of the cluster containing the application server, and might be a null value (that is, an empty text string) if the application server is not part of a cluster (for example, in the DataPower environment, there is no concept of a cluster, so this field is not used). <field3> This is the name of the cell associated with the node for the application server, and might be a null value. For DataPower, this field contains the short hostname of the computer where the DataPower appliance is located. <field4> This is the node name, usually corresponding to a logical or physical computer system with a unique IP host address, where the application server is located, and serves as a logical grouping of one or more managed application servers. Typically this is identical to the hostname for the computer, and might be a null value. For DataPower, this field contains the name of the DataPower domain.
246
Installation Guide
<field5> This is the name of the application server (for example, server1 on WebSphere). For DataPower, this field contains the name of the DataPower display group. For certain default configurations, this display group name might be the same as the domain name or the appliance hostname. Note: If <field2>, <field3>, or <field4> names contain null values, the log file name will still include the separator period characters, for example, kd4.<field1>....<field5>.metric.log. Examine the contents of this log file and verify that it contains expected metric information. Note that this log file is only present when the IBM Tivoli Composite Application Manager for SOA monitoring agent is not started. When the monitoring agent is started, these metric log files are processed and stored in the directory named \KD4.DCA.CACHE. 4. If you have previously stopped the monitoring agent, start it again from the Manage Tivoli Enterprise Monitoring Services console. After a few seconds, examine the \KD4\logs directory again and notice that any metric log files have now been processed by the monitoring agent and have been moved into the \KD4.DCA.CACHE directory.
Verifying Tivoli Enterprise Portal workspaces

Do these steps to verify that the basic workspaces provided with IBM Tivoli Composite Application Manager for SOA are displayed in the Tivoli Enterprise Portal as expected. You might need to refer to the online help and the IBM Tivoli Composite Application Manager for SOA Users Guide for information about navigating among the various workspaces, and for detailed descriptions of workspace nodes and other Tivoli Enterprise Portal features. 1. Sign in to the Tivoli Enterprise Portal: a. Open the Manage Tivoli Enterprise Monitoring Services console. b. From the console, double-click the Tivoli Enterprise Portal desktop client. c. Type your valid sign-in name (for example, the default user name sysadmin), and its valid password. After your credentials are validated, the Tivoli Enterprise Portal is displayed showing the default ITCAM for SOA workspaces and views. 2. View your generated services traffic: a. Expand the node tree in the Navigator Physical view in the upper left portion of the workspace, selecting your desired operating system, computer system node, and the Services Management Agent node. b. Select the Services Management Agent Environment node or one of its data collector subnodes (if available) to view various bar charts of your services traffic (note that this node and its subnodes are not displayed in the view until after you run services traffic in your environment). c. If these charts show no data, generate some additional Web traffic and wait approximately five minutes, then refresh the display to see your monitored metric data displayed in the views. Refresh you view automatically: You can configure the workspace to refresh automatically from the menu bar at the top of the workspace by selecting View > Refresh Every and then selecting your desired interval, from every 30 seconds to every 60 minutes.
247
If you configured SOA Domain Management Server support for topology data, complete these additional steps: 1. Assign topology views to your user name: If your user name has administrative authority, complete these steps: a. From the workspace menu bar, select Edit > Administer Users. The Administer Users configuration page is displayed. b. Highlight your user ID in the table. c. Click the Navigator Views tab. d. Under the Available Views section, locate the ITCAM for SOA Navigator View. e. Select this view and click the left arrow to move it under Assigned Views for your user ID. Your user name is now authorized to select the optional ITCAM for SOA topology views and workspaces. If you do not have administrative authority to add this capability, see your local administrator for assistance. 2. Display service-to-service topology workspaces and views: If your user name is configured to display ITCAM for SOA topology workspaces and views, complete these steps: a. If you have a large monitored environment with multiple application servers, you might want to navigate to a particular Services Management Agent Environment node and then select an application server subnode in the Navigator Physical view, to limit the amount of topology data that is displayed in the topology workspaces and views. If you only have a single application server associated with a selected Services Management Agent Environment node, then select that node instead. b. Right-click the application server subnode (or the selected Services Management Agent Environment node) and select Workspace > Operational Flow. c. An Operational Flows for Application Server workspace is displayed, showing the relationship information collected from your services traffic for operation flows that invoke services for the selected application server runtime environment. d. Move your cursor over the various icons and connecting lines in the topology view to display additional flyover help text. e. Double-click an icon in the Operation Flow view to display more detailed information in the Interaction Details view of the workspace. Cleaning up unmanaged objects: If you upgraded from ITCAM for SOA version 6.0 or version 6.1 to ITCAM for SOA version 7.1.0, you might see unmanaged clients and unmanaged operations in the Operational Flow workspaces. These objects represent services that were being monitored by earlier versions of the ITCAM for SOA monitoring agents. After you complete the upgrading of your monitoring agents to version 7.1.1, run the SOA Domain Management Server deleteUnmanagedClientsAndOperations script to remove these unmanaged objects from your topology view. Refer to the online help and the IBM Tivoli Composite Application Manager for SOA Users Guide for more information about viewing metric and topology data in these workspaces and views, and about running the deleteUnmanagedClientsAndOperations script. 3. Display topology workspaces and views for service registry integration: If you configured the optional Tivoli Common Object Repository support for topology data, you can view service registry and business process integration topology workspaces and views by doing these steps:
248
Installation Guide
a. In the View field at the top of the Navigator Physical views, select the ITCAM for SOA Navigator logical view. b. Right-click the Services Management node, and select Workspace > Services Management. The Services Overview table view is displayed, but the table is empty until you use the Tivoli Common Object Repository bulk load program to populate the database with service registry and business process data from Discovery Library Adapter books. See Chapter 17, Installing Discovery Library Adapters, on page 257 and the IBM Tivoli Composite Application Manager for SOA Users Guide for more information about Discovery Library Adapters.
249
250
Installation Guide
Chapter 16. Configuring for historical data collection

You might want to store the metric information from the data collectors into a database for later retrieval and viewing using IBM Web Services Navigator, or you might want to include historical data in your service-to-service topology workspaces, or the Performance Summary or Performance Summary for Requester Identity workspaces. If so, you must have the Warehouse Proxy configured, and you must configure IBM Tivoli Composite Application Manager for SOA for historical data collection. When this configuration is complete, Tivoli Enterprise Monitoring Server begins processing the locally stored log files of services data on each application server and sends the data to the warehouse database. The Warehouse Proxy should already be configured and running as part of the setup of the IBM Tivoli Monitoring environment. See the IBM Tivoli Monitoring documentation for more information on configuring the Warehouse Proxy and configuring for historical data collection. To configure IBM Tivoli Composite Application Manager for SOA for historical collection, complete the following steps: 1. Open and sign in to either the Desktop or Browser version of the Tivoli Enterprise Portal. 2. From the toolbar, select the History Configuration icon, or from the menu bar, select Edit -> History Configuration, as shown in Figure 62.
Figure 62. Selecting History Configuration from the menu bar
The History Collection Configuration window is displayed. 3. In the Select a product field, scroll down the list and select ITCAM for SOA. 4. IBM Tivoli Composite Application Manager for SOA provides a set of attribute groups that you can configure for historical data collection, depending on where you want to display the data. Table 11 on page 252 shows the various attribute groups that you can configure for historical data collection, depending on how you want to display the historical data.
251
Table 11. Attribute groups to configure for historical data collection Attribute groups for historical data collection v Relationships v Environment_Mapping v Svc_Port_Oper_Mapping v Service_Flow_Metrics v Rel_Resp_Metrics v Rel_Req_Metrics Services_Inventory_610 Services_Inventory_ReqID_610 Performance Summary workspace Performance Summary for Requester Identity workspace Service-to-service topology workspaces Where historical data is displayed IBM Web Services Navigator
In the Select Attribute Groups area, highlight one or more of these attribute groups for configuration. You only need to enable history collection for attribute groups used by the IBM Web Services Navigator if the Navigator is used to import data from the data warehouse (the IBM Web Services Navigator can also import data from metric log files). If you upgraded your ITCAM for SOA installation from version 6.1.0 to version 7.1.0 or 7.1.1, and are now monitoring only version 7.1.0 or later monitoring agents, the Services_Messages_Metric_610 attribute group is no longer used, unless you have a custom purpose. If historical data collection had been previously configured and started on this attribute group, you can stop collection for this group. Do not enable history collection for both the Services_Flow_Metrics attribute group and Services_Message_Metric_610 table as this will impact the ITCAM for SOA agents performance. 5. In the Configuration Controls area, do these tasks (click Help for online help information about these controls): v Select the desired Collection Interval. This is the frequency at which the metric log files are collected by the monitoring agent and stored in a temporary location to await sending their data to the warehouse database. The recommended value is 5 minutes. The ITCAM for SOA monitoring agent does not support a collection interval greater than 1 hour. v Leave the Collection Location selection at TEMA to have the log files collected at the Tivoli Enterprise Monitoring Agent for processing. v Select the desired Warehouse Interval. This is the frequency at which the metric log data is sent to the warehouse database for historical collection. You can select a frequency of once every hour or once per day. The recommended interval is 1 hour. Note that you must wait this amount of time before you can retrieve the data from the database for viewing. v Select the preferred configuration options for summarization and pruning of data. Table 12 on page 253 shows the general recommendations of which ITCAM for SOA attribute groups should be configured for summarization and pruning, based on the anticipated volume of data in each.
252
Installation Guide
Table 12. Recommendations for summarization and pruning of ITCAM for SOA attribute groups Attribute group name ServicesInventory_610 ServicesInventoryReqID_610 EnvironmentMapping Rel_Resp_Metrics Rel_Req_Metrics Relationships Service_Flow_Metrics SVC_Port_Oper_Mapping Summarize Yes Yes No No No No No No Prune Yes Yes No Yes Yes No Yes No
Note: If the Environment Mapping, Relationships, or SVC_Port_Oper_Mapping tables are pruned, the IBM Web Services Navigator is not able to correctly display service topology and transaction flows. Estimating the size of warehouse tables for historical data collection: See the table in Appendix B in the IBM Tivoli Composite Application Manager for SOA Users Guide for more information on estimating the size of these tables. 6. Click Configure Groups to apply these settings to the selected attribute groups. In the Select Attribute Groups area, the table is updated to show the specified control values for the selected groups, similar to the example shown in Figure 63 on page 254. You can continue to configure other attribute groups with different settings by highlighting those groups and selecting the preferred configuration controls.
253
Figure 63. Historical data collection configuration
7. Highlight one or more attribute groups for which you want to start historical data collection, and click Start Collection. Click Refresh Status to update the configuration controls in the table, and verify that the Collection column in the Select Attribute Groups table contains Started, signifying that historical data collection has started for that attribute group. A number in parentheses is also displayed in this column, indicating the number of monitoring servers on which data collection is taking place. If you do not want to have historical data collection always activated, you can selectively turn it on and off during testing, when making changes, or while debugging. 8. Click Close to complete the configuration. 9. The warehouse database and Warehouse Proxy should now be configured and activated. After services data is written to the warehouse database for the first time (after approximately one hour or one day, depending on the Warehouse Interval value you specified), use your database software administrative tools to check the contents of the database tables and verify that a table with the corresponding name for each configured attribute group is created in the database, as shown in the following DB2 example (DB2 is supported for warehouse databases in IBM Tivoli Monitoring).
254
Installation Guide
Figure 64. ITCAM for SOA attribute group tables displayed in the DB2 Control Center
255
256
Installation Guide
Chapter 17. Installing Discovery Library Adapters

After you have installed and configured support for the SOA Domain Management Server, and the Tivoli Common Object Repository, you need to install one or more Discovery Library Adapters that populate the Tivoli Common Object Repository database with relationship information from the WebSphere Service Registry and Repository (WSRR), from Business Process Execution Language (BPEL) information, and from services data obtained from the IBM Tivoli Composite Application Manager for SOA monitoring agents. The following three DLAs are provided with IBM Tivoli Composite Application Manager for SOA: v WebSphere Service Registry and Repository Discovery Library Adapter: Discovers the relationships between service ports, operations, services, port types, and metadata documents. v Business Process Execution Language Discovery Library Adapter: Discovers the relationships between port types, operations and business processes. v IBM Tivoli Composite Application Manager for SOA Discovery Library Adapter: Discovers the relationships between service ports and operations and the application servers and computer systems on which they are deployed, using data collected by ITCAM for SOA monitoring agents and retrieved from Tivoli Enterprise Monitoring Server. You install these DLAs from the IBM Tivoli Composite Application Manager for SOA product installation media. See the IBM Tivoli Composite Application Manager for SOA Discovery Library Adapters guide for installation and configuration procedures, and additional information on how to use the bulk load program to load the DLA information into the Tivoli Common Object Repository database.
257
258
Installation Guide
Chapter 18. Configuring for Remote Deployment

IBM Tivoli Composite Application Manager for SOA supports the IBM Tivoli Monitoring feature of remotely deploying the monitoring agent across your environment from a central location, the monitoring server. See IBM Tivoli Monitoring publications: These procedures are provided for your convenience. Be sure to check for the latest procedures for remote deployment of agents, documented in the IBM Tivoli Monitoring: Installation and Setup Guide (GC32-9407).
Populating the deployment depot

Before you can deploy the monitoring agent to a remote computer, the operating system specific monitoring agent bundle must be added to the deployment depot. For example, if you are deploying the monitoring agent to a Linux operating system, the Linux specific bundle must be added to the deployment depot. If you installed application support files on a Windows Tivoli Enterprise Monitoring Server, you might have already populated the deployment depot during the installation (see step 5 on page 32). If not, however, you can populate the deployment depot with any available operating system specific bundle at this time using either of the following two methods: v Run the installation program again and select the options presented to add the monitoring agent to the deployment depot (for example, on Windows, select the check box on the Agent Deployment page as described in step 5 on page 32). Complete the rest of the installation steps and wait for completion. v Run the tacmd addBundles command and specify the operating system specific bundle for the monitoring agent that you want to deploy. For example, on Windows, do the following: 1. From a command prompt, log in to the Tivoli Enterprise Monitoring Server using the tacmd login command:
tacmd login -s machine01.raleigh.ibm.com -u user01 -p a1b2c3d4
In this command, machine01 is the hostname where the Tivoli Enterprise Monitoring Server is located, user01 is a user name with administrator authority, and a1b2c3d4 is the password to sign on to machine01. 2. Optionally list the available bundle for the specific operating system in the D:\Windows\deploy directory on the Windows installation media using the tacmd listBundles command:
tacmd listBundles -i D:\Windows\deploy
You should receive a reply similar to the following:

Product Code : Version : Description : Host Type : Host Version : Prerequisites: D4 071000000 Monitoring Agent for Composite Application Manage for SOA WINNT WINNT
3. Run the tacmd addBundles command to populate the deployment depot with the bundle available from this location:
tacmd addBundles -i D:\Windows\deploy
259
You should receive a reply similar to the following, where <Depot_Dir> is the location where the deployment depot is located, for example, C:\IBM\ITM\CMS:
KUICAB023I : Are you sure you want to add the following bundles to the <Depot Dir>\depot\ depot? Product Code : D4 Version : 071000000 Description : Monitoring Agent for Composite Application Manage for SOA Host Type : WINNT Host Version : WINNT Prerequisites: KUICAB024I : Enter Y for yes or N for no:
You should respond with Y to add the agent bundle to the deployment depot. Wait for the process to complete. A confirmation message is displayed when the bundle is added. You can use the tacmd viewDepot command to display the bundles that have been added to the deployment depot. Procedures for both methods are fully documented in the IBM Tivoli Monitoring: Installation and Setup Guide (GC32-9407).
Deploying the bundle to the remote system

Before you can deploy the ITCAM for SOA monitoring agent to a remote system, you must first deploy an OS monitoring agent to the remote system. See the IBM Tivoli Monitoring documentation for details. You can deploy the monitoring agent bundle from the deployment depot to the remote system using the Tivoli Enterprise Portal by completing the following steps: 1. From the physical Navigator view in the Tivoli Enterprise Portal, navigate to the computer where you want to deploy the agent. 2. Right-click on the remote computer and select Add Managed System. 3. Select Monitoring Agent for Composite Application Manager for SOA from the list of available bundles and click OK. 4. The New Managed System Configuration window is displayed. v For Windows, either accept the default to use the local system account or specify a valid account and password. v For other operating systems, specify the user name (for example, root) and group name (for example, root). 5. Click Finish to complete the deployment. You can also deploy the agent from a command prompt using the tacmd addSystem command, specifying d4 as the product code for the ITCAM for SOA monitoring agent. For example:
tacmd addSystem -t d4 -n Primary:SOAWIN48:NT
These procedures are fully documented in the IBM Tivoli Monitoring: Installation and Setup Guide (GC32-9407).
Upgrading a remotely deployed monitoring agent

If you want to upgrade an existing remotely deployed monitoring agent on a specified managed system to a newer version, add the new version of the monitoring agent to the deployment depot and then use the tacmd updateAgent command. This command is documented in the IBM Tivoli Monitoring: Installation and Setup Guide (GC32-9407).
260
Installation Guide
Upgrading a version 6.0.0 or version 6.1.0 monitoring agent: You might already have a version 6.0.0 or version 6.1.0 monitoring agent deployed to a remote system in your environment. Using the remote agent deployment function of IBM Tivoli Monitoring, you can populate the deployment depot with newer versions of your monitoring agent and use the remote deployment function to upgrade to the newer version. Notes: 1. You must upgrade any version 6.0.0 monitoring agents to at least version 6.1.0. This release of ITCAM for SOA no longer supports the version 6.0.0 monitoring agent. 2. You cannot upgrade a version 6.0.0 monitoring agent directly to version 7.1.0. You must first upgrade to version 6.1.0, and then upgrade your version 6.1.0 agent to version 7.1.0. 3. IBM Tivoli Composite Application Manager for SOA supports only a single installation per computer system. Before you upgrade, keep in mind the following considerations: v Before you can remotely deploy your version 6.1.0 or version 7.1.0 monitoring agent, you must first deploy an OS agent to the remote system. IBM recommends that this OS agent be deployed to the same IBM Tivoli Monitoring installation directory (<ITM_Home>) as that of the existing version 6.0.0 or version 6.1.0 monitoring agent. When you deploy the version 7.1.0 monitoring agent, you must also specify the same directory where the OS agent is installed. This ensures that the version 6.1.0 monitoring agent is upgraded to the version 7.1.0 agent level. v If you choose to remotely deploy the OS agent in a different directory location than the existing version 6.0.0 or version 6.1.0 monitoring agent, you must complete the following basic steps: 1. Remotely deploy the OS agent to the new directory location, referred to here as <NEW_ITM_Home>. 2. Remotely deploy the version 6.0.0 or version 6.1.0 monitoring agent to <NEW_ITM_Home>. 3. Copy the KD4.dc.properties file from<ITM_Home>/<platform>/d4/KD4/config/ to <NEW_ITM_Home>/<platform>/d4/KD4/config/. See Resolving directory path variables on page xviii to determine the value of <platform> for the d4 product code and your operating system. 4. If you want to keep the data collected by the version 6.1.0 monitoring agent in the warehouse database, copy the log files from <ITM_Home>/<platform>/ d4/KD4/logs/ and its subdirectory to <NEW_ITM_Home>/<platform>/d4/KD4/ logs/. 5. Uninstall the v6.1.0 monitoring agent from the <ITM_Home> directory, because only one version of the monitoring agent can run on a single system. 6. Restart the v7.1.0 monitoring agent.
Enabling data collection on the remote system

After you remotely deploy the monitoring agent to one or more managed systems, you must enable the data collectors for the application server runtime environments being monitored on each remote system by running the Data Collector Configuration Utility as described in Part 2, Configuring for data collection, on page 125.
Chapter 18. Configuring for Remote Deployment
261
262
Installation Guide
Chapter 19. Installing Language Support

You can optionally install language support on each computer where the Tivoli Enterprise Portal Server and the Tivoli Enterprise Portal desktop client is located by completing the following steps. This procedure assumes that language support for IBM Tivoli Monitoring is already installed. If not, see the IBM Tivoli Monitoring documentation and install the base language support for IBM Tivoli Monitoring before installing agent language support.
Installing a language pack on a supported Windows operating system

To install a language pack, first make sure that you have already installed the product in English, then perform the following steps: 1. Double-click lpinstaller.bat in the language pack CD to launch the installation program. 2. Select the language of the installer and click OK. 3. Click Next on the Introduction panel. 4. Click Add/Update and click Next. 5. Select the folder in which the National Language Support package (NLSPackage) files are located. Note: Typically the NLSPackage files are located in the nlspackage folder where the installer executable is located. 6. Select the language support for the agent of your choice and click Next. Note: You can hold down the Ctrl key for multiple selections. 7. Select the languages that you want to install and click Next. 8. Examine the installation summary page and click Next to begin installation. 9. Click Finish after installation completes to exit the installer. 10. Restart Tivoli Enterprise Portal Desktop Client, Tivoli Enterprise Portal Server, and the Eclipse Help Server if any of these components are installed.
Installing a language pack on a supported UNIX or Linux operating system

To install a language pack, first make sure that you have already installed the product in English, then perform the following steps: 1. Run the following command to create a temporary directory on the computer. Make sure that the full path of the directory does not contain any spaces:
mkdir <dir_name>
2. Mount the language pack CD to the temporary directory you just created. 3. Run the following commands to launch the installation program:
cd dir_name lpinstaller.sh -c <ITM Home Directory>
Note: <ITM Home Directory> is the location where you installed IBM Tivoli Monitoring. For Linux and AIX operating systems, it is typically /opt/IBM/ITM. 4. Select the language of the installer and click OK. 5. Click Next on the Introduction panel. 6. Click Add/Update and click Next.
263
7. Select the folder in which the National Language Support package (NLSPackage) files are located. Note: Typically the NLSPackage files are located in the nlspackage folder where the installer executable is located. 8. Select the language support for the agent of your choice and click Next. Note: You can hold down the Ctrl key for multiple selections. 9. Select the languages that you want to install and click Next. 10. Examine the installation summary page and click Next to begin installation. 11. Click Finish after installation completes to exit the installer. 12. Restart Tivoli Enterprise Portal Desktop Client, Tivoli Enterprise Portal Server, and Eclipse Help Server if any of these components are installed.
264
Installation Guide
Chapter 20. Configuring IBM Tivoli Monitoring to forward events

If you configure IBM Tivoli Monitoring to forward events to an event server, this version of ITCAM for SOA includes a kd4.baroc and kd4.map file that you can use to define the events that are generated by the ITCAM for SOA monitoring agent. These files are both available on the IBM Tivoli Composite Application Manager for SOA installation media in the \kd4\tec directory on Windows and in the /kd4/tec directory on Linux, AIX, HP-UX, and Solaris. These files are also copied to the following directory locations on the computer where Tivoli Enterprise Monitoring Server is installed: v On Windows operating systems, the kd4.map file and kd4.baroc file are in the <ITM_Home>\CMS\TECLIB directory, where <ITM_Home> is the directory where you installed IBM Tivoli Monitoring. v On Linux, AIX, HP-UX, and Solaris operating systems, the kd4.map file and kd4.baroc file are in the <ITM_Home>/tables/<ms_name>/TECLIB directory, where <ms_name> is the name of the monitoring server. Refer to the IBM Tivoli Monitoring documentation for information on how to install the .baroc file for a monitoring agent on the event server.
Event Integration with WebSphere Service Registry and Repository

IBM Tivoli Composite Application Manager for SOA includes the ability to send status events to WebSphere Service Registry and Repository when a situation is detected for a service port and operation. For information about configuring IBM Tivoli Monitoring, Tivoli Enterprise Console, or IBM Tivoli Netcool/OMNIbus to forward IBM Tivoli Composite Application Manager for SOA situation events to the WebSphere Service Registry and Repository Event Handler, see the WebSphere Service Registry and Repository SA04 SupportPac available from this site:
http://www.ibm.com/support/docview.wss?rs=171&uid=swg27008751#1
See this same Web site for information about installing and configuring the IBM Tivoli Composite Application Manager for SOA Event Handler for WebSphere Service Registry and Repository, which processes the events and updates metadata properties for the service port in WebSphere Service Registry and Repository.
265
266
Installation Guide
Appendix A. Performing a silent installation of ITCAM for SOA

This appendix provides information about installing IBM Tivoli Composite Application Manager for SOA version 7.1.1 using the silent installation method. This method of installation is useful for advanced users who prefer to input installation information once through a response file instead of repeatedly through an installation wizard. You might run through the installation wizard one time to determine the values that you need to set for your monitoring needs and then use silent installation to install the rest of your environment. For more information about installing through the installation wizard, see Chapter 3, Installing IBM Tivoli Composite Application Manager for SOA, on page 29. The information in this appendix is based on more general procedures for silently installing IBM Tivoli Monitoring components and agents, found in Appendix B of the IBM Tivoli Monitoring Installation and Setup Guide, version 6.2.0 (GC32-9407).
Creating and using a Windows response file

A sample Windows silent installation response file is provided on the ITCAM for SOA product installation media. Use the following steps to edit that response file as appropriate for your environment: 1. Locate the silent.txt file on the product installation media. Copy this file to a temporary directory on your system. 2. Open your copy of the silent.txt file in a text editor. 3. Change the parameters as appropriate for your environment. The silent.txt file contains descriptions of all the parameters, including directions on how to use them. Complete all of the steps listed in the file. Each line of the file must be either a comment (containing a semi-colon in column one) or a meaningful statement that starts in column one. Note: If you want to use the TCP/IP protocol, make sure to specify IP.UDP. If you specify TCP/IP, IP.PIPE is used by default. Attention: Do not modify any other files that come with the installation (for example, the SETUP.ISS file). 4. Save the file and close the editor. 5. Run the silent installation using one of the following methods: v Running the silent installation from the command line with parameters on page 268 v Running the silent installation using SMS on page 268 Note: If the installation fails for any reason, a log file, Abort IBM Tivoli Monitoring <date>:<time>.log is created to document the problem. If the installation fails before reading in the installation location, the log file is written to the Windows boot drive, typically the C:\ drive. If the installation fails after reading the installation location, the log file is written to an \install subdirectory in the installation directory. For example, if you use the default installation directory, the log file is written to the C:\IBM\ITM\installITM directory.
267
Running the silent installation from the command line with parameters
Use the following steps to run the installation from the command line: 1. Start a DOS Command Shell. 2. From the shell, change to the directory containing this installation (where setup.exe and setup.ins are located). 3. Run the setup as follows. You must specify the parameters in the same order as listed.
start /wait setup /z"/sfC:\temp\SILENT.TXT" /s /f2"C:\temp\silent_setup.log"
In this command, these parameters are specified: /z/sf Specifies the name of the installation driver you customized for your site. This is a required parameter. This file must exist. /s /f2 Specifies that this is a silent installation. This causes nothing to be displayed during installation. Specifies the name of the InstallShield log file. If you do not specify this parameter, the default is to create Setup.log in the same location as the setup.iss file. In either case, the Setup program must be able to create and write to this file.
Running the silent installation using SMS

Use the following steps to run the installation using SMS: 1. Copy all the installation files to a LAN-based disk that SMS will mount on the desired computers. (Copy all files in the directory that contains the setup.exe and setup.ins files.) 2. Replace the original SILENT.TXT file on the LAN disk with your modified version. 3. Edit the PDF file located with the setup.exe file and change the Setup invocation as follows:
Setup /z"/sfC:\temp\SILENT.TXT" /s /f2"C:\temp\silent_setup.log"
Performing a silent installation on a Linux or Unix computer

Just as the interactive installation on Linux and UNIX requires both an installation of code and then a separate configuration, so does the silent installation method. Both the installation and configuration use parameter files to define what you are installing or configuring. Sample installation and configuration parameter files are shipped with ITCAM for SOA. The files are located in the following locations: v Silent installation files: On the ITCAM for SOA product installation media. After installation, a sample file is located in the <install_dir>/samples directory. v Silent configuration files: After you install the product, a configuration file for each component that requires configuration is located in the <install_dir>/samples directory. There is also a sample configuration file that you can use to configure any component. Before editing any of the response files, note the following syntax rules: v Comment lines begin with a pound sign (#). v Blank lines are ignored. v Parameter lines are in the format PARAMETER=value. Do not use a space before the parameter; you can use a space before or after an equal sign (=).
268
Installation Guide
v Do not use any of the following characters in any parameter value: Dollar sign ($) Equal sign (=) Pipe sign (|) Use the following procedures to perform silent installations: v Installing components with a response file v Configuring components with a response file on page 270
Installing components with a response file

The silent_install.txt response file specifies the installation parameters for ITCAM for SOA components. To use this file to perform a silent installation, edit the file to identify what you want to install and then run the following command:
./install.sh -q -h <install_dir> -p <response_file>
In this command, these parameters are specified: install_dir Identifies the installation location for the IBM Tivoli Monitoring component. The default installation location is /opt/IBM/ITM. response_file Identifies the response file that you edited to specify installation parameters. Specify the absolute path to this file. The parameters that you can configure in the silent_install.txt file vary depending on the component that you are installing. Each of the files contains comments that explain the options. The following procedure is an example of installing all available components on one computer. Use this to get an idea of what type of information you need to gather when you are setting up your own silent installation. Use the following steps to perform a silent installation on a UNIX computer: 1. Edit the silent_install.txt file. 2. Set the following parameters as appropriate for your environment:
Table 13. Silent installation parameters for UNIX Parameter INSTALL_ENCRYPTION_KEY Definition REQUIRED. The data encryption key used to encrypt data sent between systems. This key must be the same for all components in your IBM Tivoli Monitoring environment. Do not use the following characters in the key: v $ v = v |
269
Table 13. Silent installation parameters for UNIX (continued) Parameter INSTALL_FOR_PLATFORM Definition The operating system for which to install the components. You can specify an architecture code. If you do not specify an architecture code, the operating system for the current computer is used. You can find a list of the architecture codes for the supported architectures in archdsc.tbl in the registry directory. To install ITCAM for SOA agent support files for the TEMS, TEPS, and TEPS Desktop Client, the INSTALL_FOR_PLATFORM property in the silent response file must be set to one of these values: v INSTALL_FOR_PLATFORM=tpd (TEP Desktop support) v INSTALL_FOR_PLATFORM=tps (TEP Server support) v INSTALL_FOR_PLATFORM=tpw (TEP Browser support) v INSTALL_FOR_PLATFORM=tms (TEMS server) To install the monitoring agent and all four sets of application support, you must prepare five different response files and run install.sh separately for each of them. INSTALL_PRODUCT The product code for the ITCAM for SOA monitoring agent, which is d4. You can use the ./cinfo command to view the product codes for the applications installed on this computer. You can also find a list of the product codes in the registry directory in proddsc.tbl. If you are installing a monitoring server, use this parameter to specify the name for the monitoring server, such as HUB_hostname. Do not specify an IP address or fully qualified host name.
MS_CMS_NAME=
3. Save and close the file. 4. Run the following command to install ITCAM for SOA in the /opt/IBM/ITM directory:
./install.sh -q -h /opt/ibm/itm -p /tmp/silent_install.txt
Configuring components with a response file

You can use the itmcmd config command with the p <filename> parameter to configure ITCAM for SOA silently. The following sample configuration response files are provided with ITCAM for SOA: ms_silent_config.txt Used to configure the monitoring server
270
Installation Guide
cq_silent_config.txt Used to configure the portal server cj_silent_config.txt Used to configure the portal desktop client silent_config.txt A generic configuration file used to configure agents that do not require unique configuration parameters If the agent requires unique configuration parameters, configure the agent by using the itmcmd config command or the Manage Tivoli Enterprise Monitoring Services utility. Use the following steps to configure a component using the silent method: 1. Edit the configuration file for the component that you want to configure. 2. Complete the parameters identified in the file. Each file contains comments that define the available parameters and the values to specify. 3. Save the file and exit. 4. Run one of the following commands. To configure the monitoring server:
./itmcmd config -S -p <response_file> -t <ms_name>
To configure the portal server, desktop client, or the agent:

./itmcdm config -A -p <response_file> pc
In these commands: response_file The name of the configuration response file. Use an absolute path to this file. ms_name The name of the monitoring server that you want to configure. pc The product code for the IBM Tivoli Monitoring component or the ITCAM for SOA monitoring agent (d4). See Appendix D of the IBM Tivoli Monitoring Installation and Setup Guide, version 6.2.0 (GC32-9407) for the list of product codes.
271
272
Installation Guide
Appendix B. Uninstalling IBM Tivoli Composite Application Manager for SOA

IBM Tivoli Monitoring does not support backing out to a previously installed version. This means that after you upgrade your IBM Tivoli Monitoring environment, there is no way to restore the environment to the previous level. If you uninstall IBM Tivoli Monitoring after an upgrade, all of IBM Tivoli Monitoring is removed, and any subsequent installation is equivalent to installing for the first time. The same is true for ITCAM for SOA. After you upgrade your environment from a previous version of ITCAM for SOA to version 7.1.1, there is no way to return to the previous version. If you uninstall ITCAM for SOA after an upgrade, all of ITCAM for SOA is removed, and any subsequent installation is equivalent to installing for the first time. IBM Tivoli Monitoring does not support uninstalling the ITCAM for SOA application support files from the IBM Tivoli Monitoring environment. After you install the ITCAM for SOA support files on a Tivoli Enterprise Portal, Tivoli Enterprise Portal Server or Tivoli Enterprise Monitoring Server computer, there is no way to remove these support files without completely uninstalling all of IBM Tivoli Monitoring. This also means that you cannot uninstall the SOA Domain Management Server or Tivoli Common Object Repository support from the Tivoli Enterprise Portal Server configuration, or remove it from the Tivoli Enterprise Portal Server computer. To uninstall IBM Tivoli Composite Application Manager for SOA from your services environment, complete the tasks in this appendix.
Before uninstalling the monitoring agent

Before uninstalling the monitoring agent, complete the following tasks: 1. If the system is currently running a Tivoli Enterprise Portal desktop or browser client, close it. 2. Open Manage Tivoli Enterprise Monitoring Services. If any of the following services are running, stop them (by right-clicking on them and selecting Stop from the menu): v The ITCAM for SOA monitoring agent v Tivoli Enterprise Portal Server v Tivoli Enterprise Monitoring Server 3. Close the Manage Tivoli Enterprise Monitoring Services utility. 4. If you have not already done so, disable data collection for your runtime environments, following the procedures documented in Part 2, Configuring for data collection, on page 125. You might need to stop affected application servers as part of the procedure. Note: If you are running BEA WebLogic Server application server environments, you do not have to stop this service now to perform the agent uninstallation. However, after uninstalling the agent, stop and restart the application server at a later time (for example, during off-shift hours).
273
Windows: Uninstalling the monitoring agent

On each Windows computer where you have the IBM Tivoli Composite Application Manager for SOA monitoring agent installed, remove it using Add or Remove Programs from the Windows Control Panel. Select Start > Control Panel > Add or Remove Programs, and select IBM Tivoli Composite Application Manager for SOA and click Remove. The uninstallation wizard is started. Follow the on-screen prompts to complete the uninstallation.
Uninstalling Tools
You might also have the ITCAM for SOA Tools installed on the local computer. This is shown as a separate entry in under Add or Remove Programs in the Control Panel. You can also uninstall the Tools at this time, if desired. See the IBM Tivoli Composite Application Manager for SOA Tools for more information.
Removing tables from the warehouse database

You might still have a database installed if you configured for historical data collection. The database is not deleted as part of this uninstall process, because other IBM Tivoli monitoring agents might also be using it. Follow the procedures documented in your database software publications for removing any unwanted tables from the warehouse database.
Removing files and folders

After completing the uninstallation of IBM Tivoli Composite Application Manager for SOA, navigate to \KD4\config and either clear or delete the KD4.dc.properties file. If you do not clear or delete this properties file, and later install the monitoring agent again, the configuration settings for data collector control remain at the settings used for the previous installation, and not the default settings. You should also delete the <ITCAM4SOA_Home>/KD4 folder, where <ITCAM4SOA_Home> is the directory location where ITCAM for SOA is installed. See The IBM Tivoli Composite Application Manager for SOA home directory on page xix for information on how to determine the value of <ITCAM4SOA_Home>.
Removing SOA Domain Management Server and Tivoli Common Object Repository databases
The databases used with SOA Domain Management Server and Tivoli Common Object Repository are not deleted as part of the uninstallation process. Follow the procedures documented in your database application software publications information about removing an unused database.
Linux, AIX HP-UX, or Solaris: Uninstalling the monitoring agent

Uninstall the monitoring agent on supported Linux, AIX, HP-UX, and Solaris operating systems by navigating to <ITM_Home>/bin and running the ./uninstall.sh command. Follow the on-screen prompts to complete the uninstallation.
274
Installation Guide
Uninstalling Tools
You might also have the ITCAM for SOA Tools installed on the local computer. You can also uninstall the Tools at this time, if desired. See the IBM Tivoli Composite Application Manager for SOA Tools for more information.
Removing tables from the warehouse database

You might still have a database installed if you configured for historical data collection. The database is not deleted as part of this uninstall process, because other IBM Tivoli monitoring agents might also be using it. Follow the procedures documented in your database software publications for removing any unwanted tables from the warehouse database.
Removing files and folders

After completing the uninstallation of IBM Tivoli Composite Application Manager for SOA, navigate to <ITCAM4SOA_Home>/KD4/config and either clear or delete the KD4.dc.properties file. If you do not clear or delete this properties file, and later install the monitoring agent again, the configuration settings for data collector control remain at the settings used for the previous installation, and not the default settings. You should also delete the <ITCAM4SOA_Home>/KD4 folder, where <ITCAM4SOA_Home> is the directory location where the ITCAM for SOA monitoring agent is installed. See The IBM Tivoli Composite Application Manager for SOA home directory on page xix for information on how to determine the value of <ITCAM4SOA_Home>. This also assumes that you installed IBM Tivoli Monitoring at its default UNIX location, /opt/IBM/ITM.
Removing the SOA Domain Management Server database

The database used with SOA Domain Management Server is not deleted as part of the uninstallation process. Follow the procedures documented in your database application software publications information about removing an unused database.
Appendix B. Uninstalling IBM Tivoli Composite Application Manager for SOA
275
276
Installation Guide
Appendix C. Notices
This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the users responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement might not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you.
277
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation 2Z4A/101 11400 Burnet Road Austin, TX 78758 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental.
Trademarks
IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. If these and other IBM trademarked terms are marked on their first occurrence in this information with a trademark symbol ( or ), these symbols indicate U.S. registered or common law trademarks owned by IBM at the time this information was published. Such trademarks may also be registered or common law trademarks in other countries. A current list of IBM trademarks is available on the Web at Copyright and trademark information at http://www.ibm.com/legal/ copytrade.shtml. Adobe is a registered trademark or trademark of Adobe Systems Incorporated in the United States, and/or other countries. Intel and Itanium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Linux is a trademark of Linus Torvalds in the United States, other countries, or both. Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries.
278
Installation Guide
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.
Other company, product, and service names may be trademarks or service marks of others.
Appendix C. Notices
279
280
Installation Guide
Index A
accessibility xvi Acrobat Search command (for library search) xv agent deployment 16 installing 52 remote deployment 33, 259 agent, changing file permissions 62 agent, configuring 61 aggregation 203 across multiple domains 222 all domains, single host, multiple users 222 cluster of appliances 222 DataPower 202, 220 planning for 202 using display group 220 appliance aggregating multiple, DataPower 202 cluster, DataPower 222 communicating with data collector 227 DataPower 201 application domain DataPower 202 application server prerequisites 10 application support, installing 29 asynchronous flows in SCA 149 AXIS2 implementation JAX-WS support 149 conventions operating system typeface xvii xvii
D
data collection enabling BEA WebLogic Server applications for 161 enabling IBM CICS Transaction Server applications for 175 enabling IBM WebSphere Application Server applications 150 enabling JBoss applications for 171 enabling Microsoft .Net applications for 159 enabling SAP NetWeaver applications for 177 data collection, configuring 127 data collector applications enabled for multiple 13 communicating with appliance 227 configuring in DataPower environment 212 DataPower 201 DataPower, deploying 204 DataPower, starting 225 DataPower, stopping 225 disabling for DataPower 224 disabling JBoss applications for 173 disabling SAP NetWeaver application for 185 disabling WebSphere CE applications for 198 enabling WebSphere CE applications for 191 WebSphere Community Edition (CE) 191 Data Collector Configuration Utility 127 for IBM WebSphere Application Server 150 database prerequisites 11 database, DB2 13 DataPower 54, 201 appliance, cluster 222 appliance, configuring 204 appliance, polling 202 configuration file 213 configuring environment for the data collector 212 configuring optional settings 205 Console user interface in TEP 230 data collector, background mode 225 data collector, starting and stopping 225 disabling data collector 224 firmware upgrade 201, 204 logging in 231 multiple connections 220 proxy 201 user account, configuring 205 user password 219 DataPower Console considerations 230 DataPower proxy 52 DB2 13, 52 DB2 database 8 DeletePrimitiveProperty_610 156
B
background mode DataPower data collector 225 baroc file, kd4.baroc 265 BEA WebLogic Server 10, 54 enabling applications for data collection 161 books see publications xiii, xv BPEL 257 browser client Tivoli Enterprise Portal browser client 3 bulk load program, DLA 257 Business Process Execution Language 257
C
cluster DataPower SOA appliances 222 configuration file DataPower 202, 213 ConfigureMediation_610 156 configuring forward events 265 Tivoli Common Object Repository 65 configuring, data collection 127
281
deployment 16 deployment depot 33, 259 desktop client Tivoli Enterprise Portal desktop client 3 desktop client, application support 47 directory names, notation xvii Discovery Library Adapter 65, 257 display group aggregation and separation 220 changing current value 219 DataPower 203 displaygroup in node name, DataPower 217 DLA bulk load program 257 domain aggregating multiple, DataPower 202 application, DataPower 202 domain list changing current value 219 restricting user access 220
IBM WebSphere Enterprise Service Bus 152 IBM WebSphere Process Server 152 index for searching the library xv installation, planning for 3 installing 29 installing language support 263 installing, application support 29, 41, 47 installing, monitoring agent 52 interim feature 22 itmcmd, agent start, stop 245 itmcmd, config 61
J
JAX-RPC JBoss 171 JAX-WS support 149 JBoss disabling applications for data collector 173 enabling applications for data collection 171
E
Eclipse xiv Help Server 52 education see Tivoli technical training xvi environment variables, notation xvii
K
kd4.baroc 265 kd4.map 265 KD4BaseDirConfig.properties 243 KD4configDC 127 DataPower, optional parameters 219 for BEA WebLogic Server 161 for DataPower 215 for IBM CICS Transaction Server 175 for IBM WebSphere Application Server 150 for JBoss 171 for Microsoft .Net 159 for SAP NetWeaver 177, 184, 187 for WebSphere CE 192, 198 parameters, DataPower 216 KD4configMediationDeploy 155 KD4configMediationInstall 155 KD4LN0001E error message 231 KD4LN0002E error message 231 knowledge base searching xvi
F
filtering SCA 157 firmware DataPower requirement 204 DataPower requirements 201
G
glossary xv
H
hardware required 9 historical data collection 13, 251 host in node name, Datapower 217
L
language pack, installing 263 library search (Acrobat Search command) limitations DataPower 228 logging DataPower 229 SCA 157 175 xv
I
IBM CICS Transaction Server enabling applications for data collection IBM Support Assistant contacting xvi IBM Tivoli Monitoring 3 IBM Web Services Navigator xiv IBM WebSphere Application Server enabling applications for data collection
M
150 managed SCA mediation primitive xiv configuring runtime support 152 manuals see publications xiii, xv
282
Installation Guide
mediation 149 managed SCA mediation primitive xiv Microsoft .Net 54 enabling applications for data collection 159 Microsoft .NET 10 Microsoft SQL database 13 Microsoft SQL Server 52 warehouse database 11 Middleware components supported 10 monitoring agent, starting and stopping 245 monitoring server Tivoli Enterprise Monitoring Server 3 Multi-Protocol Gateway DataPower 201 multiple connections DataPower 220
N
NetWeaver see SAP NetWeaver 177 node name in TEP, for DataPower 217 notation environment variables xvii path names xvii typeface xvii
prerequisites (continued) hardware 4 Microsoft SQL Server 11 Oracle 11 SOA Domain Management Server 12 software 4 Tivoli Common Object Repository 12 Web browser 12 problem determination guidance xvi problem determination, ITCAM for SOA xiv program directory, z/OS xiv proxy DataPower 201 publications accessing online xv feedback xiii online xiii ordering xiii, xvi
R
remote agent deployment 33, 259 removing the product 273 runtime support configuring for managed SCA mediation primitive 152
O
online help, ITCAM for SOA xiv online publications accessing xv operating systems supported 4 SOA Domain Management Server 7 Tivoli Common Object Repository 7 Oracle 52 warehouse database 11 Oracle database 13 ordering publications xvi
S
SAP 177 SAP NetWeaver disabling application for the data collector 185 enabling applications for data collection 177 SCA components 149 filtering 157 IBM Web Services Navigator 156 limitations 156 logging 157 managed SCA mediation primitive xiv modules 149 search command, Acrobat (for library search) xv separation between domains by domain list 221 by display group 220 by host name 220 DataPower 220 using display group 220 Services Inventory attributes table 230 silent installation 267 SOA Domain Management Server 65, 257 database 12 software required 10 Sparkler 1 22 Sparkler 2 22 start DPDC starting DataPower data collector 204 start monitoring agent 245 startDPDC 225, 227
Index
P
parameters KD4configDC for DataPower, optional password DataPower, specifying 219 path names, notation xvii performance DataPower 228 Performance Summary workspace 230 permission, agent 62 planning 3 poll DataPower SOA appliance 202 portal server Tivoli Enterprise Portal Server 3 prerequisites Eclipse 12 219
283
stop monitoring agent stopDPDC 225 support obtaining xvi online xvi synchronous flows in SCA 149
245
virtual memory errors AIX operating system
W
web services proxy DataPower 201 WebSphere 10 WebSphere Business Integration - Server Foundation 10 WebSphere CE 191 disabling applications for data collector 198 disabling applications manually 199 enabling applications manually 194 enabling for the data collector 191 WebSphere Community Edition 191 WebSphere Integration Developer 150 WebSphere Service Registry and Repository 257 WSRR 257
T
take action ConfigureMediation_610 156 DeletePrimitiveProperty_610 156 technote IBM Tivoli Monitoring 8 telnet, starting from 245 TEMS, application support 29 TEP desktop, application support 47 TEPS, application support 41 terminology xv Tivoli Common Object Repository 14, 65, 257 database 12 Tivoli Data Warehouse database DB2 warehouse database 11 prerequisites 11 DB2 11 Tivoli Enterprise Monitoring Server 3 Tivoli Enterprise Portal 3 display group, DataPower 203 node names, DataPower 217 Tivoli Enterprise Portal Server 3, 14, 65 multiple 16 Tivoli software information center xv Tivoli technical training xvi tracing DataPower 229 training, Tivoli technical xvi transaction log service DataPower 201 troubleshooting 229 appliance password 229 communication 229 synchronizing time 229 troubleshooting, ITCAM for SOA xiv typeface conventions xvii
X
XML Management Interface enabling, for DataPower 205
Z
z/OS 3 z/OS, configuring xiv
U
uninstall on Linux, AIX, HP-UX, Solaris 274 on Windows 274 uninstalling 273 updateLogging Take Action 227 upgrading 19 upgrading, IBM Tivoli Monitoring 21 user assistance, ITCAM for SOA xiv
V
variables, notation for xvii
284
Installation Guide
Printed in USA
GC23-8803-01

ITCAM For SOA Installation Guide (7.1.1)

Загружено:

Сведения о документе

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

ITCAM For SOA Installation Guide (7.1.1)

Загружено:

Авторское право:

Доступные форматы

Tivoli Composite Application Manager for SOA

Tivoli Composite Application Manager for SOA

Part 1. Installing the product . . . . . . . . . . . . . . . . . . . . . . . . . 1

Part 2. Configuring for data collection . . . . . . . . . . . . . . . . . . . . 125

DataPower SOA Appliance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Part 3. Completing your installation . . . . . . . . . . . . . . . . . . . . . 241

259 259 260 260 261

Appendix C. Notices . . . . . . . . . . . . . . . . . . . . . . 277 Trademarks. . . . . . . . . . . . . . . . . . . . . . . . . . 278 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

Copyright IBM Corp. 2005, 2009

About this publication

What this publication contains

Copyright IBM Corp. 2005, 2009

IBM Tivoli Composite Application Manager for SOA library

Accessing terminology online

Accessing publications online

About this publication

Tivoli technical training

Conventions used in this publication

Operating system-dependent variables and paths

About this publication

Tivoli command syntax

Resolving directory path variables

The ITM home directory

Determining the platform value in directory paths

About this publication

Part 1. Installing the product

Copyright IBM Corp. 2005, 2009

Chapter 1. Planning for installation

Supported hardware platforms and operating systems

Copyright IBM Corp. 2005, 2009

Software and hardware prerequisites

Supported operating systems

X X X See Note #3 below.

See Note #3 below.

See Note #2 below.

Chapter 1. Planning for installation

Chapter 1. Planning for installation

WebSphere Message Broker cross product dependency

Understanding your IBM Tivoli Monitoring distributed environment

Data collector considerations

Planning database support

Database support for historical data collection

Database support for service-to-service topology and service registry integration

Chapter 1. Planning for installation

Installation and configuration roadmap

Chapter 1. Planning for installation

Chapter 2. Upgrading from a previous installation

Disabling data collection for your monitored environments

Disabling data collection for version 6.0.0

Disabling data collection for version 6.1.0

Disabling data collection for version 7.1.0

Copyright IBM Corp. 2005, 2009

Manager for SOA at http://publib.boulder.ibm.com/infocenter/tivihelp/v3r1/topic/ com.ibm.itcamsoa.doc_7.1/kd4inmst57.htm#part2

Upgrading your IBM Tivoli Monitoring environment

Chapter 2. Upgrading from a previous installation

Changes to subnode names in Tivoli Enterprise Portal

Changes in historical data for WebSphere Message Broker

Additional upgrade tasks

Chapter 2. Upgrading from a previous installation

Chapter 3. Installing IBM Tivoli Composite Application Manager for SOA

Installing application support on monitoring servers

Copyright IBM Corp. 2005, 2009

Windows: Installing application support on monitoring servers