Installation and Setup Guide

Transcription

1 IBM Monitoring Installation and Setup Guide GC

2

3 IBM Monitoring Installation and Setup Guide GC

4 Note Before using this information and the product it supports, read the information in Notices on page 12.

5 Contents Chapter 1. Product oeriew Monitoring agents Integration packages Features Documentation Performance Management community on deeloperworks Conentions used in the documentation Accessibility Notices Chapter 2. System requirements Dependencies Configuring the firewall for incoming requests to the serer Chapter 3. Download instructions IBM Monitoring component installation images.. 28 IBM Tioli Monitoring bundled products Chapter 4. Installing your serer Setting HTTP or HTTPS communications Downloading and installing the serer Uninstalling the serer Bypassing the prerequisite scanner Chapter 5. Installing your agents Preconfiguring the agent images Installing agents on Linux and AIX systems Prerequisite tasks Installing agents Installing agents on Windows systems Prerequisite tasks Installing agents Installing agents silently Bypassing the prerequisite scanner Uninstalling monitoring agents WebSphere Applications agent: Unconfiguring the data collector Node.js agent: Remoing the monitoring plug-in 60 Microsoft.NET agent: Remoing the.net data collector Chapter 6. Configuring your agents.. 63 Configuring the DataPower agent Configuring DataPower Appliances Configuring the DB2 agent Configuring the HMC Base agent Configuring the HTTP Serer agent Reiewing the data collector configuration Configuring the JBoss agent Configuring the Linux KVM agent Configuring the Microsoft Exchange Serer agent. 84 Creating users Assigning administrator rights to the Exchange Serer user Making the Exchange Serer user a local administrator Configuring the Exchange Serer for reachability 91 Configuring the agent to run under the domain user Configuring the agent locally Configuration parameters for the Exchange Serer properties Configuration parameters for Exchange Serices 94 Configuration parameters for reachability Validation of configuration alues Configuring the agent by using the silent response file Configuring the Microsoft Hyper-V Serer agent.. 97 Configuring the Microsoft IIS agent Configuring the Microsoft.NET agent Microsoft.NET agent: Adanced configuration 100 Configuring the Microsoft SQL Serer agent Granting permissions for SQL Serer databases 106 Selecting the databases for monitoring Configuring local enironment ariables Configuring the agent by using the silent response file Configuring the MongoDB agent Configuring the MySQL agent Configuring the Node.js agent Node.js agent monitoring plug-in: Runtime configuration file Configuring the Oracle Database agent Granting priileges Configuring the PHP agent Configuring the PostgreSQL agent Configuring the Python agent Python agent: Runtime configuration Configuring the Response Time Monitoring agent 136 Adding applications Customizing data collected by Response Time Monitoring agent Configuring CPU oerhead limit Using the IBM HTTP Serer Response Time module Configuring the Ruby agent Configuring the Tomcat agent Configuring the VMware VI agent Enabling SSL communication with VMware VI data sources Configuring the WebSphere Applications agent Configuring and reconfiguring the data collector with the adanced utilities Additional data collector settings Dynamically configuring data collection on Agent Configuration page Configuring the WebSphere Infrastructure Manager agent Copyright IBM Corp iii

6 Configuring certificates between the serer and agents Configuring a default certificate Configuring a self-signed certificate Chapter 7. Integrating with other products Integrating with Tioli Monitoring Background information Preconfiguring the Hybrid Gateway image Installing the Hybrid Gateway Creating the managed system group Configuring the Hybrid Gateway Uninstalling the Hybrid Gateway Managing the Hybrid Gateway Integrating with Netcool/OMNIbus Configuring the integration for Netcool/OMNIbus Integrating with Operations Analytics - Log Analysis Chapter 8. Administering Starting the Performance Management console Managing applications Threshold Manager Resource Group Manager Managing user access Roles and Permissions Integrating LDAP with Performance Management Changing the default user Configure audit logging for role based access control actiity Administering agents Using agent commands Agent Configuration page Starting Manage Monitoring Serices on Windows systems Administering serer components Passwords and user IDs for components Starting and stopping serer components Managing the JVM heap size and DB2 bufferpool Backing up and restoring components Adanced Configuration Chapter 9. Agent reference Chapter 10. Agent Builder Chapter 11. Troubleshooting and support Collecting Performance Management infrastructure logs for IBM Support Collecting monitoring agent logs for IBM Support 252 Accessibility Notices Index i IBM Monitoring: Installation and Setup Guide

7 Chapter 1. Product oeriew IBM Monitoring is a comprehensie solution that helps manage the performance and aailability for complex applications that might be running in a data center, public cloud, or hybrid combination. Installation of your monitoring infrastructure is done in under an hour, installation of your agents is done in minutes, and you can immediately log on to the Performance Management console to see the Application Performance Dashboard for a status check of your managed systems. The Application Performance Dashboard naigator is hierarchical, giing a status oeriew of your applications, the health of their components, and the experience of their users. For more details about your monitored resource, you can click a naigator item or a link in the Status Oeriew tab. Consider, for example, that your application has slow response time. The issue is reealed in the dashboard. Starting from your dashboard, you can follow the problem to the source by clicking links to discoer the cause: high CPU utilization on a system due to an out-of-control process. The first on-premises release of the IBM Performance Management family of products is IBM Monitoring, which proides a set of monitoring agents for resource monitoring. Also aailable is the IBM Agent Builder package that you can install as a stand-alone set of tools to build custom agents and for any technology. IBM Monitoring This product proides the following agents: Monitoring Agent for DataPower Monitoring Agent for DB2 Monitoring Agent for HMC Base Monitoring Agent for HTTP Serer Monitoring Agent for JBoss Monitoring Agent for Linux KVM Monitoring Agent for Linux OS Monitoring Agent for Microsoft Exchange Serer Monitoring Agent for Microsoft Hyper-V Serer Monitoring Agent for Microsoft Internet Information Serices Monitoring Agent for Microsoft.NET Monitoring Agent for Microsoft SQL Serer Monitoring Agent for MongoDB Monitoring Agent for MySQL Monitoring Agent for Node.js Monitoring Agent for Oracle Database Monitoring Agent for PHP Monitoring Agent for PostgreSQL Monitoring Agent for Python Monitoring Agent for Ruby Monitoring Agent for Tomcat Copyright IBM Corp

8 Monitoring Agent for UNIX OS Monitoring Agent for VMware VI Monitoring Agent for WebSphere Applications Monitoring Agent for WebSphere Infrastructure Manager Monitoring Agent for Windows OS Response Time Monitoring Agent Monitoring agents Each agent monitors the resources that are specified in the name of the agent. You can find information about dashboards, group widgets, eenting thresholds, data sets, and attributes for the agents in one the following ways: Open the online help in the Performance Management console by clicking Help > Help Contents. Download a PDF of the agent Reference by clicking the link for the Reference in the following agent descriptions: Monitoring Agent for DataPower The DataPower agent proides a central point of monitoring for the DataPower Appliances in your enterprise enironment. You can identify and receie notifications about common problems with the appliances. Performance, resource, and workload information about the appliances is proided. For more information, see the DataPower agent Reference. Monitoring Agent for DB2 The DB2 agent offers a central point of monitoring for your DB2 enironment. You can monitor a multitude of serers from a single IBM Performance Management console, with each serer monitored by a DB2 agent. You can collect and analyze information in relation to applications, databases, and system resources. For more information, see the DB2 agent Reference. Monitoring Agent for HMC Base The HMC Base agent proides you with the capability to monitor the Hardware Management Console (HMC). The agent monitors the aailability and health of the HMC resources: CPU, memory, storage, and network. The agent also reports on the HMC inentory and configuration of Power serers, CPU pools, and LPARs. The CPU utilization of the Power serers, LPARs, and pools are monitored by using HMC performance sample data. For more information, see the HMC Base agent Reference. Monitoring Agent for HTTP Serer The HTTP Serer agent collects performance data about the IBM HTTP Serer. For example, serer information, such as the status and type of serer, the number of serer errors, and the number of successful and failed logins to the serer are shown. A data collector gathers the data that is sent to the HTTP Serer agent. The agent runs on the same system with the IBM HTTP Serer that it monitors. Each monitored serer is registered as a subnode. For more information, see the HTTP Serer agent Reference. Monitoring Agent for JBoss The JBoss agent monitors the resources of JBoss application serers and the JBoss Enterprise Application platform. Use the dashboards that are proided with JBoss agent to identify the slowest applications, slowest 2 IBM Monitoring: Installation and Setup Guide

9 requests, thread pool bottlenecks, JVM heap memory and garbage collection issues, the busiest sessions and other bottlenecks on the JBoss application serer. For more information, see the JBoss agent Reference. Monitoring Agent for Linux KVM The Linux KVM agent is a multi-instance and multi-connection agent. You can create multiple instances of this agent to monitor multiple hyperisors in an RHEV-M or KVM hyperisor enironment. You can monitor irtualized workloads and analyze the resource capacity across different irtual machines. The agent collects metrics by connecting remotely to a libirt hyperisor that manages the irtual machines. For more information, see the Linux KVM agent Reference. Monitoring Agent for Linux OS The Linux OS agent proides monitoring capabilities for the aailability, performance, and resource usage of the Linux OS enironment. You can collect and analyze serer-specific information, such as operating system and CPU performance, Linux disk information and performance analysis, process status analysis, and network performance. For more information, see the Linux OS agent Reference. Monitoring Agent for Microsoft Exchange Serer The Microsoft Exchange Serer agent proides capabilities to monitor the health, aailability, and performance of the Exchange Serers in your organization. You can use the Microsoft Exchange Serer agent to collect serer-specific information, such as mail traffic, state of mailbox databases, and actiities of clients. Additionally, the agent proides statistics of cache usage, mail usage, database usage, and client actiities to help you analyze the performance of Exchange Serers. For more information, see the Microsoft Exchange Serer agent Reference. Monitoring Agent for Microsoft Hyper-V Serer The Microsoft Hyper-V Serer agent proides capability to monitor the aailability and performance of all the Hyper-V systems in your organization. The Microsoft Hyper-V Serer agent proides configuration information such as the number of irtual machines, the state of the irtual machines, the number of allocated irtual disks, the allocated irtual memory, and the number of allocated irtual processors. Additionally, the agent proides statistics of physical processor usage, memory usage, network usage, logical processor usage, and irtual processor usage. For more information, see the Microsoft Hyper-V Serer agent Reference. Monitoring Agent for Microsoft Internet Information Serices The Microsoft Internet Information Serices agent proides you with the capability to monitor the aailability and performance of Microsoft Internet Information Serer. You can use the Microsoft Internet Information Serer agent to monitor website details such as request rate, data transfer rate, error statistics, and connections statistics. For more information, see the Microsoft IIS agent Reference. Monitoring Agent for Microsoft.NET The Microsoft.NET agent monitors Microsoft.NET applications that are based on Internet Information Serices (IIS) and Microsoft.NET Framework resources. The data collector component collects data from incoming HTTP requests. The data collector collects method calls and constructs a call tree, and collects request context and stack trace data. Use the dashboards that are proided with the Microsoft.NET agent to identify the problems that are associated with Microsoft.NET Framework, and also Chapter 1. Product oeriew 3

10 to identify the slowest HTTP requests from where you can drill down to stack trace information to isolate problems. For more information, see the Microsoft.NET agent Reference. Monitoring Agent for Microsoft SQL Serer The Microsoft SQL Serer agent proides you with the capability to monitor the Microsoft SQL Serer. The agent offers a central point of management for distributed databases. Use the Microsoft SQL Serer agent dashboards to monitor the aailability, performance, resource usage, and the oerall status of all the SQL Serer instances that are being monitored. For more information, see the Microsoft SQL Serer agent Reference. Monitoring Agent for MongoDB The MongoDB agent proides monitoring capabilities for the usage, status, and performance of the MongoDB deployment. You can collect and analyze information such as database capacity usage, percentage of connections open, memory usage, instance status, and response time in isualized dashboards. For more information, see the MongoDB agent Reference. Monitoring Agent for MySQL The MySQL agent proides monitoring capabilities for the status, usage, and performance of the MySQL deployment. You can collect and analyze information such as Bytes Receied s Sent, InnoDB Buffer Pool Pages, and Historical Performance. For more information, see the MySQL agent Reference. Monitoring Agent for Node.js Node.js is a software platform that employs JaaScript for serer-side solutions, which are often used for receiing and responding to HTTP requests. The Monitoring Agent for Node.js can be used to measure and collect data about the performance of Node.js applications. For example, throughput and response times for HTTP requests, and other measurements that relate to resource usage, are monitored and stored for display and analysis. For more information, see the Node.js agent Reference. Monitoring Agent for Oracle Database The Oracle Database agent proides monitoring capabilities for the aailability, performance, and resource usage of the Oracle database. You can configure more than one Oracle Database instance to monitor different Oracle databases. The remote monitoring capability is also proided by this agent. For more information, see the Oracle Database agent Reference. Monitoring Agent for PHP The PHP agent monitors PHP web applications by collecting web access metrics through an Apache web serer and performance statistics data from MySQL. The agent discoers all WordPress applications on an Apache serer and proides WordPress application statistics information. Use the PHP agent to monitor web serer aailability, Apache serer status, and GET/POST requests. For more information, see the PHP agent Reference. Monitoring Agent for PostgreSQL The PostgreSQL agent monitors the PostgreSQL database by collecting PostgreSQL metrics through a JDBC drier. The agent proides data about system resource usage, database capacity, connections that are used, indiidual status of running instances, statistics for operations, response 4 IBM Monitoring: Installation and Setup Guide

11 time for SQL query statements, database size details, and lock information. For more information, see the PostgreSQL agent Reference. Monitoring Agent for Python The Python agent monitors Python web applications. The agent proides information about Apache serer status and monitored Django applications, including details about slow and extremely slow HTTP requests. For more information, see the Python agent Reference. Monitoring Agent for Ruby The Ruby agent monitors the performance of your Ruby on Rails applications, including request traffic and configuration statistics. You can also use the diagnostic function to get a deeper iew into each application. For more information, see the Ruby agent Reference. Monitoring Agent for Tomcat The Tomcat agent monitors the resources of Tomcat application serers. Use the dashboards that are proided with the Tomcat agent to identify the slowest applications, slowest requests, thread pool bottlenecks, JVM heap memory and garbage collection issues, the busiest sessions, and other bottlenecks on the Tomcat application serer. For more information, see the Tomcat agent Reference. Monitoring Agent for UNIX OS The UNIX OS agent proides monitoring capabilities for the aailability, performance, and resource usage of the UNIX OS enironment. You can collect and analyze serer-specific information, such as operating system and CPU performance, UNIX disk information and performance analysis, process status analysis, and network performance. For more information, see the UNIX OS agent Reference. Monitoring Agent for VMware VI The VMware VI agent monitors the VMware Virtual Infrastructure by connecting to the VMware Virtual Center. You can use the VMware VI agent to iew the status summary for clusters, and monitor multiple components including clusters, irtual machines, data stores, and ESX serers from a single console. For more information, see the VMware VI agent Reference. Monitoring Agent for WebSphere Applications The WebSphere Applications agent monitors the resources of WebSphere Application Serers. The agent gathers PMI metrics for resource monitoring through a JMX interface on the application serer. If you configure the data collector within the application serer, aggregated request performance metrics are also displayed in the dashboards. If you hae Application Diagnostics, you can configure the data collector to track the performance of indiidual request and method calls. Use the dashboards that are proided with the agent to isolate specific problem areas of your application serer. Drill down to determine whether a problem lies with an underlying resource or if it relates to the application's code. For more information, see the WebSphere Applications agent Reference. Monitoring Agent for WebSphere Infrastructure Manager The WebSphere Infrastructure Manager agent proides the monitoring capabilities for the WebSphere Application Serer Deployment Manager and Node Agent, including serer status, resources, and transactions. You can use the data that is collected by the WebSphere Infrastructure Manager agent to analyze the performance of your Deployment Manager and Node Chapter 1. Product oeriew 5

12 Integration packages Agent, and whether a problem occurred. For more information, see the WebSphere Infrastructure Manager agent Reference. Monitoring Agent for Windows OS The Windows OS agent proides monitoring capabilities for the aailability, performance, and resource usage of the Windows OS enironment. You can collect and analyze serer-specific information, such as operating system and CPU performance, disk information and performance analysis, process status analysis, Internet session data, monitored logs information, Internet serer statistics, message queuing statistics, printer and job status data, Remote Access Serices statistics, and serices information. For more information, see the Windows OS agent Reference. Response Time Monitoring Agent The Response Time Monitoring agent uses network monitoring to capture HTTP and HTTPS transaction data such as response times and status codes. Use the Response Time Monitoring agent to monitor the performance and aailability of web applications for users, including transaction request, application, and serer information. Also, use this agent to monitor mobile deices, including authenticated user performance, and mobile deice aailability and session information. For more information, see the Transaction Monitoring Reference. Use the integration capabilities to integrate with Netcool/OMNIbus and Tioli Monitoring. The following integration packages are aailable: Netcool/OMNIbus You can forward your eents from IBM Performance Management into your on-premises Netcool/OMNIbus eent manager. For more information, see Configuring the integration for Netcool/OMNIbus on page 202. Operations Analytics - Log Analysis When your enironment includes IBM Operations Analytics - Log Analysis, you can bring together application log data and performance data to help find the root cause of problems that are experienced by your applications. For more information, see Integrating with Operations Analytics - Log Analysis on page 203. Tioli Monitoring If your enironment has both IBM Tioli Monitoring and IBM Performance Management products, you can install the IBM Performance Management Hybrid Gateway to proide a consolidated iew of managed systems from both domains. For the current list of supported Tioli Monitoring agents, see IBM Performance Management Wiki - Supported IBM Tioli Monitoring agents For instructions on installing and configuring the Hybrid Gateway, see Integrating with Tioli Monitoring on page 193. Features The Performance Management console proides dashboards and configuration options for monitoring the health and performance of your applications. Read an oeriew of the features with links to learn more. 6 IBM Monitoring: Installation and Setup Guide

13 Getting started page After logging in to the Performance Management console, you are presented with a Getting Started page. Click any of the User Tasks or Administrator Tasks to link to a scenario-based tour or ideo demonstration. Start now links take you directly to the feature, such as the Threshold Manager. Community Resources links go to Frequently Asked Questions, the Performance Management forum, and more. Dashboards The Application Performance Dashboards gie you a high leel status of the applications in your enironment. View areas of interest either by selecting from the naigator or by clicking in a summary box to drill down to the next leel. To learn about the features that are aailable at each dashboard leel, click Help. Eenting thresholds Eenting thresholds enable you to detect specific application behaiors and conditions based on actiely monitored definitions. Predefined thresholds are aailable for each agent and you can define new thresholds for monitoring. For more details, click the Learn more link in the Threshold Manager or Threshold Editor page. In the Application Performance Dashboard, after you select an application, the Eents tab is displayed. The Eents tab shows the open eents for the current application. You can drill down to detailed dashboards with performance metrics to help you determine the cause of the eent. For more details, click Help. Resource groups Managed systems in your monitored enterprise can be categorized by their purpose. Such managed systems often hae the same threshold requirements. Use the Resource Group Manager to organize monitored systems into groups that you can assign eenting thresholds to. For more details, click the Learn more link in the Resource Group Manager or Resource Group Editor page. Search through log files With IBM Operations Analytics - Log Analysis (SCALA) integration, you can find the root cause of a problem that is experienced by users, such as slowness or a failure, by searching through log data that is associated with your applications. For more information about SCALA, see the IBM SmartCloud Operations Analytics - Log Analysis Knowledge Center or the IBM Operations Analytics - Log Analysis Community ( deeloperworks/sericemanagement/ioa/log/index.html) on deeloperworks. For the integration procedure, see Integrating with Operations Analytics - Log Analysis on page 203. For information on using the feature, click Help > Help Contents and open the IBM Performance Management topic, Searching log files. View KPIs from the Tioli Monitoring and Performance Management domains in the same dashboards In an enironment that includes both IBM Tioli Monitoring and IBM Performance Management products, you can install the IBM Performance Chapter 1. Product oeriew 7

14 Documentation Management Hybrid Gateway to proide a consolidated iew of managed systems from both domains. To iew your hybrid enironment in the Performance Management console, you must create a managed system group, install the Hybrid Gateway in your Tioli Monitoring enironment, and configure communications with the Hybrid Gateway. For more information, see Integrating with Tioli Monitoring on page 193. Historical metrics Get isualizations of up to 24 hours of historical data on the Application Performance Dashboards. When a time selector is displayed in a dashboard's Status Oeriew tab, you can adjust the time range for the charts and tables whose alues are deried from historical data samples. For line charts, you can also compare the current data, up to the past 24 hours, with up to 8 days of historical data to spot abnormalities. For more details, click Help in the selected Application Performance Dashboard and click the link to Adjusting and comparing metrics oer time. Create your own chart and tables in the Attribute Details tab and share with others After you drill down from the All My Applications dashboard to a detailed dashboard for a managed system instance, the Attribute Details tab is displayed for you to create and manage custom historical line charts and tables that can be saed. You can sae additional chart or table pages for your iewing only or to be shared with all users in the same enironment. For more information, click Help > Help Contents and open the IBM Performance Management topic, Creating a custom chart or table. Role Based Access Control In Performance Management, a role is a group of permissions that control the actions you can perform, for example, create applications, or iew applications. Use the Role Based Access Control feature to create customized roles. The following four predefined roles are also aailable: Role Administrator, Monitoring Administrator, System Administrator, and Monitoring User. You can assign users to both customized roles or predefined roles, and users can be assigned to multiple roles. You can assign permissions to customized roles, or you can assign more permissions to existing default roles. Permissions are cumulatie, a user is assigned all the permissions for all the roles they are assigned to. For more information, see Roles and Permissions on page 215. Agent Builder tools for customizing agents You can build custom agents for any technology using IBM Agent Builder. For more information, see the IBM Agent Builder User's Guide. Various documentation is aailable for Performance Management. The following types of information are aailable: User interface help When you are logged in to the Performance Management console, you can access the online help by clicking the Help menu, and by clicking 8 IBM Monitoring: Installation and Setup Guide

15 in the upper-right corner of the Application Performance Dashboards or the Learn more link in the System Configuration pages. You can also access the online help when you explore Performance Management in IBM Serice Engage or when logged in to the Performance Management console. Click in the lower-left corner of the window and select Help Contents. IBM Knowledge Center Performance Management in IBM Knowledge Center contains topics of information for the product and links to reference and troubleshooting information. In IBM Knowledge Center, you can create a custom PDF that contains only the topics in which you are interested. See the directions for Creating your own set of topics. IBM Performance Management Wiki - Documentation This wiki contains links to reference and troubleshooting PDFs. You can obtain more technical documentation about monitoring products from other sources. See the following sources of technical documentation about monitoring products: IBM Terminology website proides terminology that is releant to IBM products consolidated in one conenient location. IBM Integrated Serice Management Library is an online catalog that contains integration documentation and other downloadable product extensions IBM Redbook publications include Redbooks publications, Redpapers, and Redbooks technotes that proide information about products from platform and solution perspecties. Technotes, which are found through the IBM Software Support website, proide the latest information about known product limitations and workarounds. Performance Management community on deeloperworks deeloperworks is a repository of technical information that is organized by communities. Access deeloperworks at IBM deeloperworks > Application Performance Management ( Connect, learn, and share with other professionals. Get access to deelopers and product support technical experts who proide their perspecties and expertise. You can use deeloperworks for these purposes: Become inoled with transparent deelopment, an ongoing, open engagement between other users and IBM deelopers of monitoring products. You can access early designs, sprint demonstrations, product roadmaps, and prerelease code. Connect one-on-one with the experts to collaborate and network about monitoring and the Performance Management community. Read blogs to benefit from the expertise and experience of others. Use wikis and forums to collaborate with the broader user community. Conentions used in the documentation Seeral conentions are used in the documentation for special terms, actions, commands, and paths that are dependent on your operating system. Chapter 1. Product oeriew 9

16 Typeface conentions The following typeface conentions are used in the documentation: Bold Lowercase commands, mixed-case commands, parameters, and enironment ariables that are otherwise difficult to distinguish from the surrounding text Interface controls (check boxes, push buttons, radio buttons, spin buttons, fields, folders, icons, list boxes, items inside list boxes, multicolumn lists, containers, menu choices, menu names, tabs, property sheets), labels (such as Tip:) Keywords and parameters in text Italic Citations (examples: titles of publications, diskettes, and CDs) Words and phrases defined in text (example: a nonswitched line is called a point-to-point line) Emphasis of words and letters (example: The LUN address must start with the letter L.) New terms in text, except in a definition list (example: a iew is a frame in a workspace that contains data.) Variables and alues you must proide (example: where myname represents...) Monospace Examples and code examples File names, directory names, path names, programming keywords, properties, and other elements that are difficult to distinguish from the surrounding text Message text and prompts Text that you must type Values for arguments or command options Bold monospace Command names, and names of macros and utilities that you can type as commands Enironment ariable names in text Keywords Parameter names in text: API structure parameters, command parameters and arguments, and configuration parameters Process names Registry ariable names in text Script names Operating system-dependent ariables and paths The direction of the slash for directory paths might ary in the documentation. Regardless of what you see in the documentation, follow these guidelines: For UNIX or Linux, use a forward slash (/). For Windows, use a backslash (\). 10 IBM Monitoring: Installation and Setup Guide

17 The names of enironment ariables are not always the same in Windows and UNIX. For example, %TEMP% in Windows is equialent to $TMPDIR in UNIX or Linux. For enironment ariables, follow these guidelines: For UNIX or Linux, use $ariable. For Windows, use %ariable%. If you are using the bash shell on a Windows system, you can use the UNIX conentions. Installation directory ariable and paths for agents install_dir is the installation directory for the agents. The default location depends on the operating system: C:\IBM\APM /opt/ibm/apm/agent /opt/ibm/ccm/agent Accessibility Accessibility features help users with physical disabilities, such as restricted mobility or limited ision, to use software products successfully. IBM Monitoring supports a command prompt interface for installation and a web-based interface for configuration and usage. Product functionality and accessibility features ary according to the interface. The major accessibility features in this product enable users in the following ways: Use assistie technologies, such as screen-reader software and digital speech synthesizer, to hear what is displayed on the screen. Consult the product documentation of the assistie technology for details on using those technologies with this product. Operate specific or equialent features using only the keyboard. Magnify what is displayed on the screen. In addition, the product documentation was modified to include the following features to aid accessibility: All documentation is aailable in both HTML and conertible PDF formats to gie the maximum opportunity for users to apply screen-reader software. All images in the documentation are proided with alternatie text so that users with ision impairments can understand the contents of the images. IBM Monitoring and its related publications, are accessibility-enabled. For more information about the accessibility features of the documentation, see Accessibility. Note: Some content presented in IBM Knowledge Center might not yet be in a format that a screen reader can process. If you need help, contact ibmkc@us.ibm.com. Interface information The interface offers the greatest range of functionality, but is not entirely accessible. Chapter 1. Product oeriew 11

18 Naigating the interface using the keyboard Standard shortcut and accelerator keys are used by the product and are documented by the operating system. See the documentation proided by your operating system for more information. Magnifying what is displayed on the screen You can enlarge information on the product windows using facilities proided by the operating systems on which the product is run. For example, in a Microsoft Windows enironment, you can lower the resolution of the screen to enlarge the font sizes of the text on the screen. See the documentation proided by your operating system for more information. IBM and accessibility See the IBM Human Ability and Accessibility Center for more information about the commitment that IBM has to accessibility. Notices This information was deeloped for products and serices offered in the U.S.A. IBM may not offer the products, serices, or features discussed in this document in other countries. Consult your local IBM representatie for information on the products and serices currently aailable in your area. Any reference to an IBM product, program, or serice is not intended to state or imply that only that IBM product, program, or serice may be used. Any functionally equialent product, program, or serice that does not infringe any IBM intellectual property right may be used instead. Howeer, it is the user's responsibility to ealuate and erify the operation of any non-ibm product, program, or serice. IBM may hae patents or pending patent applications coering subject matter described in this document. The furnishing of this document does not gie you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drie Armonk, NY 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: Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan, Ltd , Nihonbashi-Hakozakicho, Chuo-ku Tokyo , Japan The following paragraph does not apply to the United Kingdom or any other country where such proisions are inconsistent with local law : INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER 12 IBM Monitoring: Installation and Setup Guide

19 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 improements 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 proided for conenience only and do not in any manner sere 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 beliees appropriate without incurring any obligation to you. Licensees of this program who wish to hae 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/ Burnet Road Austin, TX U.S.A. Such information may be aailable, 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 aailable for it are proided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equialent agreement between us. Any performance data contained herein was determined in a controlled enironment. Therefore, the results obtained in other operating enironments may ary significantly. Some measurements may hae been made on deelopment-leel systems and there is no guarantee that these measurements will be the same on generally aailable systems. Furthermore, some measurement may hae been estimated through extrapolation. Actual results may ary. Users of this document should erify the applicable data for their specific enironment. Information concerning non-ibm products was obtained from the suppliers of those products, their published announcements or other publicly aailable 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. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objecties only. Chapter 1. Product oeriew 13

20 This information is for planning purposes only. The information herein is subject to change before the products described become aailable. 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 indiiduals, 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. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on arious operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of deeloping, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples hae not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, sericeability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of deeloping, using, marketing, or distributing application programs conforming to IBM's application programming interfaces. Each copy or any portion of these sample programs or any deriatie work, must include a copyright notice as follows: (your company name) (year). Portions of this code are deried from IBM Corp. Sample Programs. Copyright IBM Corp All rights resered. If you are iewing this information in softcopy form, the photographs and color illustrations might not be displayed. Trademarks IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and serice names might be trademarks of IBM or other companies. A current list of IBM trademarks is aailable on the web at Copyright and trademark information at Adobe, Acrobat, PostScript and all Adobe-based trademarks are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, other countries, or both. IT Infrastructure Library is a registered trademark of the Central Computer and Telecommunications Agency which is now part of the Office of Goernment Commerce. Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Linux is a trademark of Linus Toralds in the United States, other countries, or both. 14 IBM Monitoring: Installation and Setup Guide

21 Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. ITIL is a registered trademark, and a registered community trademark of The Minister for the Cabinet Office, and is registered in the U.S. Patent and Trademark Office. UNIX is a registered trademark of The Open Group in the United States and other countries. Jaa and all Jaa-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates. Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in the United States, other countries, or both and is used under license therefrom. Linear Tape-Open, LTO, the LTO Logo, Ultrium, and the Ultrium logo are trademarks of HP, IBM Corp. and Quantum in the U.S. and other countries. Priacy policy considerations IBM Software products, including software as a serice solutions, ( Software Offerings ) may use cookies or other technologies to collect product usage information, to help improe the end user experience, to tailor interactions with the end user or for other purposes. In many cases no personally identifiable information is collected by the Software Offerings. Some of our Software Offerings can help enable you to collect personally identifiable information. If this Software Offering uses cookies to collect personally identifiable information, specific information about this offering s use of cookies is set forth below. Depending upon the configurations deployed, this Software Offering may use session cookies that collect each user s user name for purposes of session management, authentication, and single sign-on configuration. These cookies can be disabled, but disabling them will also likely eliminate the functionality they enable. If the configurations deployed for this Software Offering proide you as customer the ability to collect personally identifiable information from end users ia cookies and other technologies, you should seek your own legal adice about any laws applicable to such data collection, including any requirements for notice and consent. For more information about the use of arious technologies, including cookies, for these purposes, See IBM s Priacy Policy at and IBM s Online Priacy Statement at the section entitled Cookies, Web Beacons and Other Technologies and the IBM Software Products and Software-as-a-Serice Priacy Statement at Chapter 1. Product oeriew 15

22 16 IBM Monitoring: Installation and Setup Guide

23 Chapter 2. System requirements For the IBM Monitoring agents, arious operating systems are supported and each agent has specific requirements. The Performance Management serer has other requirements, which ary depending on the number of agents that you want to use for monitoring data sources. Time zone Use NTP (Network Time Protocol) on managed systems and on the system where the Performance Management serer is installed to ensure that the time is accurate. The time zone must be set correctly for the time zone that the system is in, such as UTC-03:00 for Brasilia and UTC +06:30 for Yangon. Hardware and software requirements Obtain information about the hardware and software requirements for each monitoring agent that you plan to install. For information about the requirements for the monitoring agents and the Performance Management serer, see the IBM Performance Management Wiki - System requirements on deeloperworks. Prerequisite scanner After you start the installation script for the Performance Management serer, a prerequisite scanner runs automatically and displays the results. The results include a log file that you can reiew if any of the prerequisites are not met. An out-of-date library or insufficient disk space stops the installation. You must address the missing prerequisite before you can start the installation again. A soft prerequisite, such as low aailable memory, does not stop the installation, but is displayed in the results. The minimum requirements for installation are proided in Table 2 on page 20 in the column Extra small. The Performance Management serer must be installed on a RHEL 6 (64-bit) or later operating system. Certain ports must be aailable before you begin installing the Performance Management serer. The prerequisite scanner checks if they are aailable and returns FAIL for each port that is not aailable: Table 1. Aailable ports for installation. Port Description 80 HTTP port for the Agent Subscription Facility (ASF) and Central Configuration Serer. The port is labeled ASFRESTHTTP in the prerequisite scanner output. 443 HTTPS port for the Agent Subscription Facility (ASF) and Central Configuration Serer. The port is labeled ASFRESTHTTPS in the prerequisite scanner output HTTP port for the Performance Management console user interface. The port is labeled APMUIHTTP in the prerequisite scanner output HTTPS port for the Performance Management console user interface. The port is labeled APMUIHTTPS in the prerequisite scanner output. Copyright IBM Corp

24 Table 1. Aailable ports for installation (continued). Port Description Port 1 for role-based access control Port 2 for role-based access control Port 3 for role-based access control Port 4 for role-based access control Port for DB2. The port is labeled DB2 in the prerequisite scanner output. If a firewall is blocking the ports, you can either configure the firewall to allow traffic on certain ports or disable the firewall. For more information, see Configuring the firewall for incoming requests to the serer on page 25. The following example of prerequisite scanner results shows an example where the prerequisite checks failed. You must correct the problems that were found and start the installation again. (See Tips for resoling unmet dependencies in Dependencies on page 21.) IBM Prerequisite Scanner Version: Build : OS name: Linux User name: root Machine Information Machine name: somehost Serial number:... Scenario: Prerequisite Scan KIM - IBM Monitoring [ersion ]: Property Result Found Expected ======== ====== ===== ======== Memory WARN 3.48GB 0-12GB Disk FAIL 14.00GB 100GB os.swapsize WARN 3.81GB 2-4GB numlogicalcpu WARN 2 4 db2.usersnotpresent FAIL db2fenc1,dasusr1 db2inst1,db2fenc1,dasusr1,db2iadm1,db2fadm1, db2.groupsnotpresent FAIL db2iadm1,db2fadm1,dasadm1 db2iadm1,db2fadm1,dasadm1 os.lib.pam_32 FAIL Unaailable regex{libpam.so.*} os.package.sg3_utils FAIL Unaailable sg3_utils Aggregated Properties for Scanned Products: Property Result Found Expected ======== ====== ===== ======== / FAIL 14.00GB GB Memory WARN 3.48GB GB Oerall result: FAIL Detailed results are also aailable in /tmp/smai_prs_ _053249/result.txt The following example of prerequisite scanner results shows operating system, aailable ports, and library information. The report section titled Required for DB2 indicates that libraries required for DB2 are missing and that the installation could not proceed. You must first install the missing libraries, and start the installation again. (See Tips for resoling unmet dependencies in Dependencies on page 21.) 18 IBM Monitoring: Installation and Setup Guide

25 # Validate supported Operating Systems OS Version=Red Hat Enterprise Linux 6.* FRESH.Memory=7.5GB os.space.home=1gb os.space.opt=[dir:root=/opt/ibm]60gb Temp=2-3GB os.swapsize=2-4gb os.dir.home=[dir:/home,type:permission]755+ os.dir.opt=[dir:/opt/ibm,type:permission]755+ os.dir.tmp=[dir:/tmp,type:permission]777+ CpuArchitecture=x86_64 numlogicalcpu=2 # DB2-related checks. db2.isinstalled=false db2.usersnotpresent=[se:warn]db2apm,db2fenc1,dasusr1,apmuser db2.groupsnotpresent=[se:warn]db2iadm1,db2fadm1,dasadm1 db2.sericesnotpresent=db2_db2apm,db2_db2apm_1,db2_db2apm_2,db2_db2apm_end,db2c_db2apm db2.sericesnotpresent=50000 os.kernelersion= os.kernelsnotsupported=[se:warn] ; # Check for aailable ports network.aailableports.asfresthttp=80 network.aailableports.asfresthttps=443 network.aailableports.apmuihttp=8080 network.aailableports.apmuihttps=9443 network.aailableports.server1http=8090 network.aailableports.server1https=8091 network.aailableports.oslcpm=10001 network.aailableports.fngaiandb=6414 network.aailableports.fneifrcvr=9998 network.aailableports.fnintmsg=32105 network.aailableports.scrderbydb=1527 network.aailableports.scrjavabkend=12315 network.aailableports.db2=50000 network.aailableports.rbacserver1=13245 network.aailableports.rbacserver2=13246 network.aailableports.rbacserver3=13247 network.aailableports.rbacserver4=13248 [OSType:LINUX] os.package.bash=bash [OSType:LINUX][OSArch:64-bit] os.lib.libc_64=regex{libc.so*} os.lib.libgcc_64=regex{libgcc.*.so*} os.lib.libstdc++_64=regex{libstdc++.so.5} os.lib.libstdc++_64=regex{libstdc++.so.6} # Required for DB2 os.lib.libstdc++_32=regex{libstdc++.so.6} os.lib.pam_64=regex{libpam.so.*} os.lib.pam_32=regex{libpam.so.*} os.package.sg3_utils=sg3_utils # Required for Summarization and Pruning Agent os.package.ksh=ksh The 32-bit libraries are DB2 prerequisites. The prerequisite scanner also checks for the maximum user processes and maximum open files: Chapter 2. System requirements 19

26 os.ulimit=[type:maxprocesseslimit]4096+ os.ulimit=[type:filedescriptorlimit] For guidance in checking the limits and changing them, see Dependencies on page 21. Hardware requirements based on system configuration The results of scale testing indicate that a Performance Management serer installed on a VM with the minimum requirements that are shown in the following table can support up to 10 concurrent users. Table 2 displays the minimum requirements for each hardware component on the serer. The serer can be installed on systems with different memory, processor, and disk space configurations. The installer adjusts the requirements for the serer based on how the system configuration is classified: extra small, small, or medium. Table 2. Memory, processor, and storage requirements based on system configuration. Hardware Component Medium configuration minimum requirements Small configuration minimum requirements Free memory 16 GB 12 GB 8 GB Number of processors Aailable disk space 120 GB 80 GB 60 GB Extra small configuration minimum requirements Based on how the installer classifies the system, the JVM heap size is set for the Performance Management serices to the following alues: Table 3. JVM heap size setting.. System size Performance Management serer) Serer1 application serer APMUI serice Asfrest (Liberty serer instance) Medium 768 MB 2048 MB 4096 MB 768 MB Small 768 MB 1536 MB 3072 MB 512 MB Extra small 512 MB 1024 MB 2048 MB 512 MB Table 4 gies system requirements and proides an estimate of the number of monitoring agents that can be effectiely managed in small and medium enironments. Although at least 16 GB of free memory is required if you plan to hae more than 500 agents, there is no way to know how many agents that you plan to hae. The prerequisite scanner displays a message about increasing the memory only if memory is under 8 GB. An extra small enironment can hae fewer than 50 agents. Table 4. Memory, processor, and storage requirements based on agent load. Component Fewer than 50 agents Between 50 and 500 agents Between 500 and 1000 agents Free memory 8 GB 12 GB 16 GB Number of processors IBM Monitoring: Installation and Setup Guide

27 Table 4. Memory, processor, and storage requirements based on agent load (continued). Component Fewer than 50 agents Between 50 and 500 agents Between 500 and 1000 agents Aailable disk 60 GB 80 GB 120 GB space Swap space 4 GB 4 GB 4 GB The number of agents that can be supported by the Performance Management serer depends on the type of agents being monitored. The number of data rows that are generated by each agent can ary widely based on the specific monitored enironment or workload. The Performance Management serer was tested with up to 1000 agents and a total data olume of up to 55,000 rows per minute. To help you estimate the number of rows per minute for your monitored enironment, you can use the IBM Monitoring Prefetch Database Load Projections spreadsheet and usage instructions that are aailable for download from the deeloperworks IBM Performance Management Wiki. Dependencies The Performance Management serer and supporting components are installed on a Linux system. Reiew the dependencies to ensure a successful installation. Linux dependencies RPM dependencies The Performance Management serer uses Red Hat Package Manager (RPM) files to install the software. The following example is the prerequisite scanner configuration file, which lists the dependencies that the RPMs hae for a successful installation: # Validate supported Operating Systems OS Version=Red Hat Enterprise Linux 6.* FRESH.Memory=7.0GB os.space.home=1gb os.space.opt=[dir:root=/opt/ibm]60gb Temp=2-3GB os.swapsize=2-4gb os.dir.home=[dir:/home,type:permission]755+ os.dir.opt=[dir:/opt/ibm,type:permission]755+ os.dir.tmp=[dir:/tmp,type:permission]777+ CpuArchitecture=x86_64 numlogicalcpu=2 # Check if RPM database is intact. rpm.dbstatuscorrect=true # Check if localhost is defined. os.localhostinhostsfile=true # Maximum number of user processes. os.ulimit=[type:maxprocesseslimit]4096+ # Maximum number of open files os.ulimit=[type:filedescriptorlimit] # DB2-related checks. db2.isinstalled=false db2.usersnotpresent=[se:warn]db2apm,db2fenc1,dasusr1,itmuser db2.groupsnotpresent=[se:warn]db2iadm1,db2fadm1,dasadm1 Chapter 2. System requirements 21

28 db2.sericesnotpresent=db2_db2apm,db2_db2apm_1,db2_db2apm_2,db2_db2apm_end,db2c_db2apm db2.sericesnotpresent=50000 os.kernelersion= os.kernelsnotsupported=[se:warn] ; # Check for aailable ports network.aailableports.asfresthttp=80 network.aailableports.asfresthttps=443 network.aailableports.apmuihttp=8080 network.aailableports.apmuihttps=9443 network.aailableports.server1http=8090 network.aailableports.server1https=8091 network.aailableports.oslcpm=10001 network.aailableports.fngaiandb=6414 network.aailableports.fneifrcvr=9998 network.aailableports.fnintmsg=32105 network.aailableports.scrderbydb=1527 network.aailableports.scrjavabkend=12315 network.aailableports.db2=50000 network.aailableports.rbacserver1=13245 network.aailableports.rbacserver2=13246 network.aailableports.rbacserver3=13247 network.aailableports.rbacserver4=13248 network.pingself=true [OSType:LINUX] os.package.bash=bash [OSType:LINUX][OSArch:64-bit] os.lib.libc_64=regex{libc\.so.*} os.lib.libgcc_64=regex{libgcc.*\.so.*} os.lib.libstdc++_64=regex{libstdc++\.so\.5} os.lib.libstdc++_64=regex{libstdc++\.so\.6} # Required for DB2 os.lib.libstdc++_32=regex{libstdc++\.so\.6} os.lib.pam_64=regex{libpam\.so.*} os.lib.pam_32=regex{libpam\.so.*} os.package.sg3_utils=sg3_utils # Required for Summarization and Pruning Agent os.package.ksh=ksh For details on the port names, see Table 1 on page 17 in Chapter 2, System requirements, on page 17. Without the required libraries and other software, the prerequisite scanner fails and displays a failure explanation, such as: Expected Property Result Found regex(libstdc++.so.6 os.lib.libstdc++_32 FAIL Unaailable A Red Hat Enterprise Linux client that is correctly configured to use the yum (Yellowdog Updater, Modified) package manager can resole and install any missing dependencies that are required by the RPMs. For more information on yum commands, see What is yum? How do I use it? ( Tips for resoling unmet dependencies When the prerequisite scanner returns errors because of failed dependencies, you can run the yum proides feature_name command to learn what is required, and the yum install feature_name command to install the missing dependency. For example: 22 IBM Monitoring: Installation and Setup Guide

29 Error The prerequisite scanner shows the following failure message: error: Failed dependencies: libstdc++.so.6 is needed by... Command yum proides Enter the following command: yum proides libstdc++.so.6 The following report is displayed: libstdc el6.i686 : GNU Standard C++ Library Repo : installed Matched from: Other : Proides-match: libstdc++.so.6 Command yum install Enter the following command to satisfy the missing feature: yum install libstdc el6.i686 Command yum install Enter the following command to install all prerequisites: yum -y install --setopt=protected_multilib=false ksh libstdc++.i686 pam.i686 pam.x Table 5. Sample error messages for failed dependencies on Linux and the possible resolution RPM Error message Possible resolution error: Failed dependencies: rpm -Uh libstdc el6.i686.rpm libstdc++.so.6 is needed by... error: Failed dependencies: rpm -Uh libgcc el6.i686.rpm libgcc_s.so.1 is needed by libstdc el6.i686 libgcc_s.so.1(gcc_3.0) is needed by libstdc el6.i686 libgcc_s.so.1(gcc_3.3) is needed by libstdc el6.i686 libgcc_s.so.1(gcc_4.2.0) is needed by libstdc el6.i686 libgcc_s.so.1(glibc_2.0) is needed by libstdc el6.i686 error: Failed dependencies: compat-libstdc++-33(i686) is needed by... rpm -Uh compat-libstdc el6.i686.rpm Maximum number of user processes and open files dependencies The prerequisite scanner checks for the following limitations: Maximum number of user processes, which is displayed as os.ulimit=[type:maxprocesseslimit] The operating system must allow a user to hae at least 4096 processes. Below that alue, the prerequisite scanner returns FAIL and the Performance Management serer installation fails. Maximum number of open files, which is displayed as os.ulimit=[type:filedescriptorlimit] The operating system must allow a user to hae at least 10,000 open files. Below that alue, the prerequisite scanner returns FAIL and the serer installation fails. To check the current system limits, you can issue the following commands: ulimit -a returns all limits Chapter 2. System requirements 23

30 ulimit -u returns the maximum number of processes aailable to a single user ulimit -n returns the maximum number of open file descriptors To increase the limit for the current shell session, you can issue the following commands: ulimit -u new_limit sets the maximun number of processes. Example: ulimit -u 4096 ulimit -n new_limit sets the maximum number of open files descriptors. Example: ulimit -n If you want to set the limits permanently rather than for only the current shell session, edit the /etc/security/limits.conf file. User Interface dependencies Required libraries Refer to the libraries listed under the heading # Required for CandleManage in the sample prerequisite configuration file. Without the required libraries, the prerequisite scanner fails and displays a failure explanation. DB2 dependencies The prerequisite scanner checks that the DB2 dependencies are met. Required libraries Please refer to the libraries listed under the heading # Required for DB2 in the sample prerequisite configuration file. Without the required libraries, the prerequisite scanner fails and displays a failure explanation. DB2 requires a Linux Kernel of ersion or higher. No preious installation of DB2 A DB2 database must not already exist on the system where you plan to install the Performance Management serer. Specific product users If any of the following users exist on the system where you plan to install the Performance Management serer, you must update default user password in the install.properties file, which is aailable in the root directory of the installation media: itmuser dasusr1 db2apm db2fenc1 Kernel ersions that are not supported for the Performance Management serer or DB2 agent: When you install the DB2 agent on the Performance Management serer and on some VMs, certain kernel ersions are not supported. The following kernel ersions are not supported: From to If the Linux kernel matches this range, a warning error is displayed. As a result, DB2 might hang and you must upgrade to one of the supported ersions. Any other kernel starting from or higher is alid. 24 IBM Monitoring: Installation and Setup Guide

31 Configuring the firewall for incoming requests to the serer Before installing the Performance Management serer, you might want to temporarily disable your firewall or configure ports for incoming requests. Before you begin TCP connections are made between the monitoring agent and serer. Thus, any firewall must allow connections in both directions. Typical Network Address Translation (NAT) configurations do not allow such connections and are not supported. About this task Take one of the following steps to either open ports or disable the firewall: Procedure Set your firewall for incoming requests on ports used by the serer. Ensure that the following ports are free (no application is listening on them): Disable your firewall and run the following Red Hat Linux commands: serice iptables stop chkconfig iptables off If IP6 (Internet Protocol Version 6) is enabled, also run the following commands: serice ip6tables stop chkconfig ip6tables off What to do next Install the Performance Management serer and monitoring agents. Chapter 2. System requirements 25

32 26 IBM Monitoring: Installation and Setup Guide

33 Chapter 3. Download instructions Download the IBM Monitoring installation images from IBM Passport Adantage website. Installation images are aailable for the Performance Management serer, the monitoring agents, and the following optional packages: IBM Agent Builder toolkit for creating custom agents to extend the resources that you can monitor. IBM Performance Management Hybrid Gateway component for enironments with IBM Tioli Monitoring agents Download and install the Performance Management serer on a computer system where you want the monitoring infrastructure to be installed. You hae three options for downloading the agent images: Download the agent images to the system where you downloaded the Performance Management serer installation image. The agent images can be mounted on an NFS partition but must be accessible using the file system. Preconfigure the agent images when prompted during the installation of the serer and copy the preconfigured images to the system where the applications that you want to monitor are installed. Before or after you install the serer, download the agent images to any system in your enironment. On the system where you installed the serer, create configuration packages for connecting the agents to the serer. Copy the configuration packages to the system where the agent images are downloaded, preconfigure the agent images, and download the preconfigured images to the system where the applications that you want to monitor are installed. Before or after you install the serer, download the agent images to the system where the applications that you want to monitor are installed. After you install the serer, create configuration packages for connecting the agents to the serer. Copy the preconfiguration packages to the system where you downloaded the agent images, and preconfigure the agent images. Important: Do not change the installation image file name for the agents or Hybrid Gateway during or after download. If the installation image file name is changed, it is not recognized by preconfiguration tools and preconfiguration fails. The monitoring agents are autonomous and hae no infrastructure other than what is proided by the Performance Management serer for data sharing. Both the performance and size footprint on indiidual nodes is small. Data retention is local and short term. If your enironment includes IBM Tioli Monitoring products that you want to iew in the Performance Management console, you can download and install the IBM Performance Management Hybrid Gateway image. You hae the same choices as for the agent images to download and preconfigure the Hybrid Gateway image, and you can download the Hybrid Gateway at the same time and to the same system as the agent images. You can also download and install the IBM Agent Builder toolkit to build custom agents for any technology. Copyright IBM Corp

34 IBM Monitoring component installation images Reiew the descriptions of the IBM Monitoring component images and Passport Adantage part numbers to identify the components to download for your IBM Monitoring installation. You can download IBM Monitoring installation images from IBM Passport Adantage website. Performance Management serer IBM Monitoring Serer Install 8.1 RHEL 6 64bit (MONITORING_SI_V8.1_RHEL_6_64B_ML.tar) Performance Management serer, including the DB2 database and the Summarization and Pruning agent. The DB2 database stores agent resource, attribute, and relationship information in the Serice Component Repository (SCR). The DB2 prefetch database is a warehouse for agent metric data. The Summarization and Pruning agent is preconfigured and performs the aggregation and pruning functions for the historical data in the DB2 database. Performance Management console, which is the user interface for the dashboards. Eclipse help serer, which proides the support for the Performance Management console and monitoring agent help systems. For instructions on installing the Performance Management serer and supporting components, see Chapter 4, Installing your serer, on page 33. Monitoring agents IBM Monitoring Agents Install 8.1 Linux 64bit (ibm-monitoringagents_8.1_xlnx64.tar) Monitoring agent framework Monitoring Agent for DataPower Monitoring Agent for DB2 Monitoring Agent for HTTP Serer Monitoring Agent for JBoss Monitoring Agent for Linux KVM Monitoring Agent for Linux OS Monitoring Agent for MongoDB Monitoring Agent for MySQL Monitoring Agent for Node.js Monitoring Agent for Oracle Database Monitoring Agent for PHP Monitoring Agent for PostgreSQL Monitoring Agent for Python Monitoring Agent for Ruby Monitoring Agent for Tomcat Monitoring Agent for VMware VI Monitoring Agent for WebSphere Applications Monitoring Agent for WebSphere Infrastructure Manager 28 IBM Monitoring: Installation and Setup Guide

35 Response Time Monitoring Agent For instructions on installing these monitoring agents, see Installing agents on Linux and AIX systems on page 42. IBM Monitoring Agents Install 8.1 AIX (ibm-monitoring-agents_8.1_aix.tar) Monitoring agent core framework Monitoring Agent for DataPower Monitoring Agent for DB2 Monitoring Agent for HMC Base Monitoring Agent for HTTP Serer Monitoring Agent for Oracle Database Monitoring Agent for UNIX OS Monitoring Agent for WebSphere Applications Response Time Monitoring Agent For instructions on installing these monitoring agents, see Installing agents on Linux and AIX systems on page 42. IBM Monitoring Agents Install 8.1 Windows 32bit (ibm-monitoringagents_8.1_win32.zip) Monitoring agent core framework Monitoring Agent for Microsoft Internet Information Serices Monitoring Agent for Microsoft SQL Serer Monitoring Agent for Windows OS For instructions on installing these monitoring agents, see Installing agents on Windows systems on page 50. IBM Monitoring Agents Install 8.1 Windows 64bit (ibm-monitoringagents_8.1_win64.zip) Monitoring agent core framework Monitoring Agent for DataPower Monitoring Agent for DB2 Monitoring Agent for Microsoft Exchange Serer Monitoring Agent for Microsoft Hyper-V Serer Monitoring Agent for Microsoft Internet Information Serices Monitoring Agent for Microsoft.NET Monitoring Agent for Microsoft SQL Serer Monitoring Agent for MySQL Monitoring Agent for Oracle Database Monitoring Agent for VMware VI Monitoring Agent for WebSphere Applications Monitoring Agent for Windows OS Response Time Monitoring Agent For instructions on installing these monitoring agents, see Installing agents on Windows systems on page 50. Agent Builder IBM Agent Builder toolkit for creating custom agents to extend the resources that you can monitor. Chapter 3. Download instructions 29

36 IBM Agent Builder (IBM_AGENT_BUILDER_V8.1_MP_ML.tar) Agent Builder component For instructions on installing the Agent Builder stand-alone toolkit for multiple platforms, download the IBM Agent Builder User's Guide from deeloperworks. Hybrid Gateway IBM Performance Management Hybrid Gateway component for enironments with IBM Tioli Monitoring agents IBM Hybrid Gateway (ibm-monitoring-hybrid-gateway8.1.tar) Hybrid Gateway component For instructions on installing the Hybrid Gateway, see Integrating with Tioli Monitoring on page 193. Passport Adantage Go to IBM Passport Adantage ( passportadantage/pao_customers.htm) to purchase and download the software and the production license. Use the following contact information for Passport Adantage online support: ecustomer care contact information The order part number is for a twele month or monthly licence: IBM Monitoring Managed Virtual Serer Lic + SW S&S 12 Mo (D1FWULL) IBM Monitoring Managed Virtual Serer MONTHLY LICENSE (D1G3QLL) Table 6. IBM Performance Management downloadable software from Passport Adantage eassembly part number to download eimage part number to download Title of image on Passport Adantage CRV70ML CN4K3ML IBM Monitoring Serer Install 8.1 RHEL 6 64bit CRV70ML CN4K0ML IBM Monitoring Agents Install 8.1 XLinux 64bit CRV70ML CN4K1ML IBM Monitoring Agents Install 8.1 AIX CRV70ML CN4JZML IBM Monitoring Agents Install 8.1 Windows 32bit CRV70ML CN4JYML IBM Monitoring Agents Install 8.1 Windows 64bit Contents Monitoring infrastructure installation tar file Monitoring agent installation tar files for Linux 64-bit systems Monitoring agent installation tar file for AIX systems Monitoring agent installation zip file for Windows 32-bit systems Monitoring agent installation zip file for Windows 64-bit systems CRV70ML CN4K2ML IBM Agent Builder IBM Agent Builder toolkit installation tar file for multiple platforms 30 IBM Monitoring: Installation and Setup Guide

37 Table 6. IBM Performance Management downloadable software from Passport Adantage (continued) eassembly part number to download eimage part number to download Title of image on Passport Adantage Contents CRV70ML CN4K4ML IBM Hybrid Gateway Hybrid Gateway installation tar file IBM Tioli Monitoring bundled products Aailable with the IBM Monitoring product are the bundled products based on the IBM Tioli Monitoring infrastructure. Reiew the guidelines to determine which Tioli Monitoring bundled product to install. If you don t currently hae any of the Tioli Monitoring bundled products installed, install the IBM Monitoring components. If you currently use any of the included Tioli Monitoring products, follow these guidelines: If you hae a serer or serers (irtual or physical) that already hae Tioli Monitoring based agents installed and you d like to install additional agents, use the Tioli Monitoring based agents. If you want to monitor serers that don t currently hae any of the Tioli Monitoring based agents installed, you can use either the Tioli agents or IBM Monitoring agents. Howeer, the Tioli agents require that you also deploy the Performance Management serer. When the IBM Performance Management Hybrid Gateway component is installed, you can iew monitored resources from your Tioli Monitoring and Performance Management domains in the same dashboards. After you purchase your IBM Monitoring license, you can download any or all of the Tioli Monitoring bundled software shown in Table 7 from IBM Passport Adantage ( pao_customers.htm). Use the following contact information for Passport Adantage online support: ecustomer care contact information Table 7. Software for IBM Tioli Monitoring bundled products that are downloadable from Passport Adantage for use with IBM Monitoring eassembly to download CRVJ1ML CRVI4ML CRVI5ML CRVI7ML CRVJ2ML Title on Passport Adantage IBM InfoSphere Federation Serer for IBM Monitoring IBM Operations Analytics Log Analysis for IBM Monitoring IBM SmartCloud Application Performance Management Entry Edition for IBM Monitoring IBM Tioli Composite Application Manager for Applications for IBM Monitoring IBM Tioli Composite Application Manager for Applications for IBM Monitoring Product documentation Click here Click here Click here Click here Click here Chapter 3. Download instructions 31

38 Table 7. Software for IBM Tioli Monitoring bundled products that are downloadable from Passport Adantage for use with IBM Monitoring (continued) eassembly to download CRVI8ML Title on Passport Adantage IBM Tioli Composite Application Manager for Microsoft Applications for IBM Monitoring Product documentation Click here CRVI6ML IBM Tioli Composite Application Manager Click here for Transactions for IBM Monitoring CRVI9ML IBM Tioli Monitoring for IBM Monitoring Click here CRVJ0ML IBM Tioli Monitoring for Virtual Click here Enironments for IBM Monitoring CRVI3ML IBM Tioli OMEGAMON XE on z/vm and Linux for IBM Monitoring Click here 32 IBM Monitoring: Installation and Setup Guide

39 Chapter 4. Installing your serer The Performance Management serer and supporting components proide the infrastructure for monitoring with the Performance Management console. Install the Performance Management serer as the first step in setting up your IBM Performance Management enironment. If you hae downloaded the monitoring agent images, you can preconfigure the images as part of the monitoring infrastructure installation process. If you intend to monitor with agents from your IBM Tioli Monitoring enironment, you can also download the IBM Performance Management Hybrid Gateway image and preconfigure the image as part of the installation process. Setting HTTP or HTTPS communications The default communication protocol between the Performance Management serer and agents is HTTP. Before installing the serer, you can use an enironment ariable to change the protocol to HTTPS for secure communications between the serer and monitoring agents. Before you begin Communications between the serer and agents must be consistently HTTP or HTTPS. If you preconfigure the agents during Performance Management serer serer installation, the communications protocol for the agents is set to match what is set for the serer. Howeer, if you choose to preconfigure the agents at a later time, be sure to set the communications protocol to the same setting as the serer is using. You might notice a degradation in performance when the secure HTTPS protocol is used, depending on how many monitoring agents you are running. Procedure Complete the following step before installing the Performance Management serer to change the communications protocol: On the system where you plan to install the serer, enter one of the following commands: To set HTTPS (secure) communications: export APM_SECURE_COMMUNICATION=y To set HTTP (non-secure) communications: export APM_SECURE_COMMUNICATION=n (Unless the APM_SECURE_COMMUNICATION enironment ariable was used to set HTTPS, this step is not necessary because the default protocol is HTTP. Thus, while using a clean shell session, such as just after logging in, you can start the serer installation to establish HTTP communications.) What to do next Run the installation script to begin installing the serer. Related tasks: Copyright IBM Corp

40 Downloading and installing the serer Before installing the monitoring agents and, optionally, the IBM Performance Management Hybrid Gateway, install the Performance Management serer on a irtual machine or computer in your network that is running Red Hat Enterprise Linux. Configuring certificates between the serer and agents on page 188 To enable communication between the Performance Management serer and agents, you can configure default, custom, or self-signed certificates. Downloading and installing the serer The installation procedure inoles downloading the Performance Management serer installation media, decompressing the installation files on the system, and running the installation script. Before installing the monitoring agents and, optionally, the IBM Performance Management Hybrid Gateway, install the Performance Management serer on a irtual machine or computer in your network that is running Red Hat Enterprise Linux. Before you begin Reiew the Chapter 2, System requirements, on page 17 and Dependencies topics for the supported platforms and requirements for the Performance Management serer. You must run as the root user to install the serer. The installation of the serer installs a DB2 database and Summarization and Pruning agent on the same system as the serer. Do not install the serer on a computer system with an existing installation of DB2. If any of the following user IDs exist on the system where you plan to install the serer, you must update default user password in the install.properties file, which is aailable in the root directory of the installation media: itmuser dasusr1 db2apm db2fenc1 Agent installation images must be preconfigured to connect to the serer. If you plan to preconfigure the agent images during installation of the serer rather than at a later time, you must first download the agent images to the same system where the serer will be installed. The agent images can be mounted on an NFS partition but the images must be accessible using the file system. Do not change the installation image file name for the agents during or after download. If the installation image file name is changed, it is not recognized by preconfiguration tools and preconfiguration fails. For more information, see Chapter 3, Download instructions, on page 27. As with agent images, if you plan to preconfigure the Hybrid Gateway during installation of the serer rather than at a later time, you must first download the Hybrid Gateway image to the same system where the serer will be installed. Do not change the ibm-monitoring-hybrid-gateway8.1.tar file name for the Hybrid Gateway during or after download. If the installation image file name is changed, it is not recognized by preconfiguration tools and preconfiguration fails. For more information, see Chapter 3, Download instructions, on page IBM Monitoring: Installation and Setup Guide

41 After you obtain the Performance Management serer installation media, decompress the archie file, and start the installation, a prerequisite checker reiews your Red Hat Enterprise Linux system to ensure that it meets the software, memory, and disk requirements. Any missing prerequisites are shown in a message. An absolute prerequisite, such as an out of date library or insufficient disk space, stops the installation. You must address the missing prerequisite before you can start the installation again. A soft prerequisite, such as low aailable memory, does not stop the installation, but is displayed in a message. For more information, see Dependencies. About this task Complete the following steps to download, decompress and install the serer and supporting components on a Red Hat Enterprise Linux system. Procedure 1. Download the Performance Management serer installation file from the download site to a staging location of your choosing. For details, see Chapter 3, Download instructions, on page If you plan to preconfigure the agent images or Hybrid Gateway image (or both) during installation of the serer, download the images to the same system where the serer will be installed. For details, see Chapter 3, Download instructions, on page Extract the serer installation files: tar -xf MONITORING_SI_V8.1_RHEL_6_64B_ML.tar 4. Naigate to the directory where you extracted the serer installation files. 5. If you want to change the protocol from the default HTTP to HTTPS (secure) communications, enter the following command: export APM_SECURE_COMMUNICATION=y (See Setting HTTP or HTTPS communications on page 33.) 6. Install the Performance Management serer on the VM or your computer system: a. Run the following script:./install.sh A prerequisite scan of your enironment starts and takes a few moments to complete. If any requirements are missing, a message directs you to a log file with the reason for the failure. A prerequisite such as a missing library or insufficient disk space stops the installation. You must address the failure and start the installation again. A soft prerequisite such as low aailable memory does not stop the installation but you must enter 1 to continue installing or 2 to stop. For more information, including the yum proides feature_name and yum install feature_name commands, see Dependencies. If the prerequisite scan detects that the RPM database is corrupted, the rpm.dbstatuscorrect property returns a FAIL status. For a possible solution, see the IBM Monitoring Troubleshooting Guide (download from IBM Performance Management Wiki - Documentation). b. If the International Program License Agreement is displayed for you to read, you can press Enter to read the next screen of text, enter 1 to accept the agreement, 2 to decline it, 3 to print it, or 99 to go back to the preious screen. c. After you are prompted to change the default password for the administrator account, enter either 1 (yes) and create a new encrypted Chapter 4. Installing your serer 35

42 password or 2 (no) to keep the default apmpass unencrypted password. If you change the password, keep a copy in a safe place; you cannot recoer the password if you forget it. After you answer the prompt to change the administrator password, the installation continues. d. After you are asked whether you want to preconfigure your agent installation images and Hybrid Gateway installation image (if used) to connect to the serer, enter either 1 (yes) to preconfigure the images now or 2 (no) to defer preconfiguration of the agent and Hybrid Gateway images. If you entered 1 (yes), you are prompted to confirm the following information: The path to the directory on the serer where the agent images and Hybrid Gateway (if used) are stored. Tip: The agent images and Hybrid Gateway images can be mounted on an NFS partition but must be accessible using the file system. The serer IP address or host name for the agents and Hybrid Gateway to use. The format of the IP address can be IP4 or the fully qualified domain name. The installer creates the directory /opt/ibm/ccm/depot for storing the preconfigured agent and Hybrid Gateway images. Howeer, if the installer fails to create the directory or the directory is not writeable, you are prompted to specify the output directory. Results Uninstalling the serer If you entered 2 (no), this step is skipped. The installer installs the serer components and support files; no further user input is required. After serer installation, the installer configures the components, which can take up to 1 hour to complete. What to do next If you did not preconfigure the agent installation images during installation of the serer, follow the instructions in Preconfiguring the agent images on page 39. Install the agents on the systems where the applications that you want to monitor are installed, as described in Chapter 5, Installing your agents, on page 39. If you forgot to set the correct password for itmuser before installation, run the script to proide the correct password. See Changing a password on page 227. If you no longer want the Performance Management serer on your VM or computer system, you can uninstall it. The serer uninstall procedure does not remoe the monitoring agents other than the Summarization and Pruning agent agent that was installed with the serer. Before you begin If the DB2 agent is installed on the Performance Management serer system and is monitoring the Performance Management serer DB2 database, the agent must be stopped before you uninstall the serer. Otherwise, the uninstallation might fail. 36 IBM Monitoring: Installation and Setup Guide

43 Procedure 1. On the system where the Performance Management serer is installed, open the command prompt. 2. Run the following command in the /opt/ibm/ccm directory: uninstall.sh Results The Performance Management serer components are uninstalled. Bypassing the prerequisite scanner When you install the Performance Management serer, a prerequisite scan of your enironment starts and takes a few moments to complete. If any requirements are missing, a message directs you to a log file with the reason for the failure. You can enter a command to bypass the prerequisite check. Best practice is to enable the prerequisite scan but, for certain test scenarios, you can bypass the prerequisite scan to sae time. About this task After downloading and extracting the installation files, take this step to bypass the prerequisite scan. Procedure On the system where you plan to install the serer, enter the following command: export SKIP_PRECHECK=1 What to do next Run the installation script to begin installing the serer without the prerequisite scan. Chapter 4. Installing your serer 37

44 38 IBM Monitoring: Installation and Setup Guide

45 Chapter 5. Installing your agents Install monitoring agents on the systems where the corresponding applications that you want to monitor are located. Preconfiguring the agent images Preconfigure the agent images to connect to the Performance Management serer. If you selected the option to preconfigure your agent images when you installed the serer, and that configuration completed successfully, you can skip this task. Een if you hae already preconfigured your agent images, if you want to change between the HTTP and HTTPS protocol, you can preconfigure agent images and specify HTTP or HTTPS. Before you begin Download the agent images to a system in your enironment (see Chapter 3, Download instructions, on page 27). If you downloaded the agent images to the system where the applications you want to monitor are installed, unpack the agent images. If you downloaded the agent images to another system, you can leae the agent images unpacked. Later, you can preconfigure the agent images archie file and copy the archie file to the system where the applications that you want to monitor are installed. Do not change the installation image file name for the agents during or after download. If the installation image file name is changed, it is not recognized by preconfiguration tools and preconfiguration fails. On the system where you installed the Performance Management serer, create configuration packages with the parameters for connecting the monitoring agents to the serer. Use the make_configuration_packages.sh script to create these packages: a tar file for Linux or AIX systems; a zip file for Windows systems. To create the configuration packages, complete the following steps: 1. Naigate to the /opt/ibm/ccm directory on the system where the serer is installed. 2. To create the configuration packages in interactie mode, complete the following steps: a. Enter:./make_configuration_packages.sh b. Enter the IP address or host name of the Performance Management serer or accept the default alue. c. Enter the directory where you want to store the configuration packages after you create them or accept the default alue of /tmp/ mkcustpkg_workdir.process_id_of_script, for example, /tmp/mkcustpkg_workdir d. Select the HTTPS protocol if you want secure communications between the serer and agents; select the HTTP protocol for non-secure communications. Copyright IBM Corp

46 The communications protocol between serer and agents must be the same. For more information, see Setting HTTP or HTTPS communications on page To create the configuration packages in batch mode, complete the following steps: a. Enter:./make_configuration_packages.sh -s serer_ip [-d config_packages_dir] [-p {http https}] Where: serer_ip IP address or fully qualified domain name of the serer. config_packages_dir Optional. Path to the directory where you want to store the configuration packages after you create them. http or https Optional. The default communication protocol between the serer and agents is HTTP. If you set the protocol before installing the serer to secure HTTPS, enter -p https to change the protocol for the agents to HTTPS so that it matches what was set for the serer. (For more information, see Setting HTTP or HTTPS communications on page 33.) 4. Copy a configuration package that you created to the system where you downloaded the agent images and, optionally, unpack the configuration package. About this task The configure_agent_images scripts are used to preconfigure the agents that are in the configuration package. Take the following steps to preconfigure the agent images: Procedure 1. If you unpacked the configuration package, naigate to the directory where you unpacked the configuration package. 2. To preconfigure unpacked agent images in interactie mode, complete the following steps: a. Enter:./configure_agent_images.sh or configure_agent_images.bat b. If you did not unpack the configuration package, enter the path to the directory where you stored the configuration package. c. Enter the path to the directory where you unpacked the agent images that you downloaded. 3. To preconfigure unpacked agent images in batch mode, complete the following steps: a. Enter:./configure_agent_images.sh [-p configuration_package_dir] [-s agent_images_dir] 40 IBM Monitoring: Installation and Setup Guide configure_agent_images.bat [-p configuration_package_dir] [-s agent_images_dir]

47 Where: configuration_package_dir If you did not unpack the configuration package, enter the path to the directory where you stored the configuration package. agent_images_dir Path to the directory where you unpacked the agent images that you downloaded. 4. To preconfigure the agent images archie file in interactie mode, complete the following steps: a. Enter:./configure_agent_images.sh or configure_agent_images.bat b. If you did not unpack the configuration package, enter the path to the directory where you stored the configuration package. c. Enter the path to the directory where you downloaded the agent images archie file. d. Enter the path to the directory where you want to store the preconfigured agent images archie file. The default is /opt/ibm/ ccm/depot or current_directory\output. 5. To preconfigure the agent images archie file in batch mode, complete the following steps: a. Enter:./configure_agent_images.sh [-p configuration_package_dir] [-s agent_images_dir] [-d preconfigured_images_dir] Results configure_agent_images.bat [-p configuration_package_dir] [-s agent_images_dir] [-d preconfigured_images_dir] Where: configuration_package_dir If you did not unpack the configuration package, enter the path to the directory where the configuration package is located. agent_images_dir Path to the directory where you downloaded the agent images archie file. preconfigured_images_dir Path to the directory where you want to store the preconfigured agent images archie file. The installer preconfigures the agent images or the agent image archie file. A status message is displayed to indicate that the agent images or the agent images archie file are preconfigured and proides the location of the files. What to do next Complete one of the following steps: Chapter 5. Installing your agents 41

48 If you preconfigured the unpacked images on the system where the applications that you want to monitor are installed, install the agents. If you preconfigured the agent images archie file on another system, copy the preconfigured agent images archie file to the system where the applications that you want to monitor are installed, and install the agents. For details see, Chapter 5, Installing your agents, on page 39. Installing agents on Linux and AIX systems Install monitoring agents on your Linux and AIX systems for the resources that you want to manage. The following agents are aailable for installation on Linux systems: Monitoring Agent for DataPower Monitoring Agent for DB2 Monitoring Agent for HTTP Serer Monitoring Agent for Linux OS Monitoring Agent for Linux KVM Monitoring Agent for MongoDB Monitoring Agent for MySQL Monitoring Agent for Node.js Monitoring Agent for Oracle Database Monitoring Agent for PHP Monitoring Agent for PostgreSQL Monitoring Agent for Python Monitoring Agent for Ruby Monitoring Agent for Tomcat Monitoring Agent for VMware VI Monitoring Agent for WebSphere Applications Monitoring Agent for WebSphere Infrastructure Manager Response Time Monitoring Agent The following agents are aailable for installation on AIX systems: Monitoring Agent for DataPower Monitoring Agent for DB2 Monitoring Agent for HMC Base Monitoring Agent for HTTP Serer Monitoring Agent for Oracle Database Response Time Monitoring Agent Monitoring Agent for UNIX OS Monitoring Agent for WebSphere Applications Prerequisite tasks Reiew the agent prerequisite tasks to ensure a successful installation on Linux and AIX systems. 42 IBM Monitoring: Installation and Setup Guide

49 Reiew the Software Product Compatibility Reports ( software/reports/compatibility/clarity/index.html) for your agent to get the current ersion requirements and dependencies. Non-root user install You must hae read, write, and execute permissions for the installation directory. Otherwise, the installation is canceled. You must install and configure all agents on the Linux or AIX system with the same user account. For example, if you install the Monitoring Agent for Linux OS and Monitoring Agent for DB2 in one session and later decide to install the Response Time Monitoring Agent, use the same non-root user account for both installation sessions and to configure the DB2 agent. After a non-root installation, two scripts (SetPerm and UpdateAutoRun.sh) must be run with root user access. Installation path is limited to 70 characters The installation directory and the path to it must be no more than 70 characters. Tar file names limited to 100 characters The default tar command on AIX systems cannot handle file names that are longer than 100 characters. To aoid installation issues, complete the following steps: 1. Download and install the GNU ersion of the tar command from the AIX Toolbox for Linux Applications website. 2. Make the GNU ersion your default tar command. Complete one of the following steps: In the PATH enironment ariable, put the following ariable first: export PATH=/opt/freeware/bin:$PATH Replace /bin/tar with symbolic link to /opt/freeware/bin/tar Alternatiely, upgrade to the latest ersion of AIX to receie the code fix for handling file names longer than 100 characters. For details, see the the TAR command technote for AIX V6.1 or the the TAR command technote for AIX V7.1. ITCAM agents IBM Tioli Composite Application Manager agents are not supported in your Performance Management enironment. You cannot install a Performance Management agent in a directory where ant ITCAM agent that uses Jaa is installed. The installation of the agent is blocked. HTTP Serer agent You should install and run this agent as a root user. You should use the same user ID to install and run the agent. If you install and run the agent as a non-root user, the non-root user must hae the same user ID as the user who started the IBM HTTP Serer. Otherwise, the agent will run into problems in discoering the IBM HTTP Serer. Install the lynx utility or the curl application. Also, AIX V 6.1 TL5 is the minimum operating system that is required. Linux KVM agent Install the required operating system prerequisite libirt*.rpm. MySQL agent To monitor a MySQL enironment, the MySQL serer, and MySQL JDBC Chapter 5. Installing your agents 43

50 44 IBM Monitoring: Installation and Setup Guide drier must be installed before you install the Monitoring Agent for MySQL. For example, to install the JDBC drier on Red Hat Enterprise Linux, use the following command: yum install mysql-connector-jaa After you start the agent installation and during the prerequisite check for the MySQL package name, you might get a warning if a proider other than RedHat is used, such as Oracle. If the MySQL Serer and JDBC drier are aailable, the warning does not cause the installation to fail, and you can disregard the message. Sample output: Scenario: Prerequisite Scan KSE - Monitoring Agent for MySQL Prerequisite Checker [ersion ]: Property Result Found Expected ======== ====== ===== ======== os.package.mysql-serer WARN Unaailable mysql-serer os.package.mysql-connector-jaa WARN Unaailable mysql-connector-jaa Node.js agent You must hae a stable ersion of Node.js, V0.8.0 or higher installed before you install the agent. The ersion of Node.js that you use to run your monitored application must be the same as the default installed ersion. Oracle Database agent On Red Hat Enterprise Linux ersion 5, ersion 6 and SUSE Linux Enterprise Serer ersion 10, and ersion 11 x64, if the Oracle Database agent monitors the Oracle database remotely, you must install the Oracle instant clients first from Oracle Technology Network - Instant Client Downloads. The instant client 10.x, 11.x,and 12.x are supported by the Oracle Database agent. PHP agent If the PHP application is deployed by using the root user, you must use the root user to install, configure, start, or stop the agent. If the PHP application is deployed by using a non-root user, you can use root user or the same non-root user to install, configure, start, or stop the agent. You must hae an Apache HTTPD serer V2.4 or higher installed before you install the agent. PHP must be at V5.3.3 or higher. You must hae an existing WordPress-based application installed. The PHP agent monitors WordPress V3.7.1 or higher The agent ealuates only the performance of PHP requests in WordPress applications. CSS and JS loading are not ealuated. The agent does not use URL arguments to identify URLs PostgreSQL agent You must hae PostgreSQL V9.2 or higher installed. You must install PostgreSQL JDBC drier before you install this agent. Otherwise, you will not be able to configure the agent properly. You must modify the postgresql.conf configuration file to add pg_stat_statements: 1. Open the postgresql.conf file in a text editor and update the shared_preload_libraries line as follows:

51 shared_preload_libraries = pg_stat_statements If you want to monitor SQL functions, you must specify the following: shared_preload_libraries = pg_stat_statements pg_stat_statements.track_utility = false 2. Restart the PostgreSQL serer after you add the pg_stat_statements. 3. Execute the following SQL command by using Psql: create extension pg_stat_statements; select pg_stat_statements_reset(); Python agent If the Python application is deployed by using the root user, you must use the root user to install, configure, start, or stop the agent. If the Python application is deployed by using a non-root user, you can use root user or the same non-root user to install, configure, start, or stop the agent. You must hae an Apache HTTPD serer V or higher installed before you install the agent. The Apache serer must include mod_wsgi V3.2 or higher. Python must be at V2.6.6 or higher. The Python agent monitors Django V or higher. The agent ealuates only the performance of iew requests in Django applications. The agent does not use URL arguments to identify URLs. Installing agents To install a monitoring agent on a Linux or AIX system, you must download an agent installation image archie file from the IBM download site, preconfigure the agent image, and then install the agents. For details about the options for downloading the agent images, see Chapter 3, Download instructions, on page 27. For a list of the agents that run on a Linux or AIX system, see Prerequisite tasks on page 42. Before you begin Before installing the agents, make sure to preconfigure the agent images with the connection details for the Performance Management serer. For instructions, see Preconfiguring the agent images on page 39. You can install any combination of monitoring agents on a managed system. For example, if you install the Monitoring Agent for Ruby for monitoring Ruby On Rails applications, you might want to also install the Response Time Monitoring Agent to gather more response time information for your Ruby applications, and the Monitoring Agent for Linux OS to monitor other aspects of the system, such as the oerall CPU, memory, and disk. About this task Some of the agents are configured and started automatically. Other agents must be configured before data is reported: Chapter 5. Installing your agents 45

52 The following agents are configured and started automatically: Linux OS agent UNIX OS agent HTTP Serer agent Response Time For the HTTP Serer agent, you must reiew the configuration file that the agent creates for the HTTP Serer. Then, you must add the data collector configuration manually to the serer configuration file. Jaa Runtime is installed only when the agent requires it and it not always aailable. Also, ksh is no longer required to perform agent installation, and SELinux in enforcing mode is supported. The following agents are multiple instance agents. You must create the first instance and start the agent manually. A multiple instance agent means a single installation of the agent instantiates a unique monitoring instance for each unique application instance. These instances are isualized from the Performance Management console as a result. DataPower agent DB2 agent HMC Base agent JBoss agent Linux KVM agent MongoDB agent MySQL agent Oracle Database agent PHP agent PostgreSQL agent Python agent Tomcat agent Ruby agent VMware VI agent WebSphere Infrastructure Manager agent DataPower agent: Before the agent is installed, the prerequisite checker checks that ulimit is set to unlimited on AIX. You must run the ulimit -d unlimited command to ensure that the max data segment size system enironment ariable is set to unlimited. HMC Base agent: If you install the agent as a root user you must ensure that system TL07 is installed. If you install the agent as a non-root user you must ensure that system TL08 is installed for AIX6 only. The Linux KVM agent is also a multi-connection agent. It supports connection to both the Enterprise Linux based KVM hyperisor and Red Hat Enterprise Virtualization Manager (RHEVM) enironments. Node.js agent: The agent must be configured before data is reported. You must add a monitoring plug-in to your Node.js application. Ruby agent: For deep die diagnostics, the agent must be configured before data is reported. To enable the diagnostics dashboards, you must install and configure the diagnostics data collector. WebSphere Applications agent: The agent is started automatically but the agent must be configured before data is reported. 46 IBM Monitoring: Installation and Setup Guide

53 You can install monitoring agents as the root user or non-root user. Complete these steps to install monitoring agents on VMs and systems where Red Hat Enterprise Linux or SUSE Linux Enterprise Serer is installed. Complete these steps to install the monitoring agent on LPARs and systems where AIX is installed. Procedure 1. Naigate to the directory where your preconfigured agent images are located. 2. Extract the monitoring agent installation files by using one of the following commands depending on your serice subscription leel: tar -xf ConsumerMedia.tar where ConsumerMedia is the name of the archie file. 3. As the root user, run the installation script from the directory named for the APM_Agent_Install_8.1.0 directory. To install the agents in silent mode, see Installing agents silently on page 53. The installer checks that the agent images were preconfigured with parameters for connecting to the infrastructure node. If the agents images were not preconfigured, the installation is stopped. 4. Specify whether to install indiidual agents, a combination of the agents, or all of the agents. 5. Enter the agent installation home directory. The default directory is: /opt/ibm/apm/agent /opt/ibm/ccm/agent Directory names in the path can contain only the following characters: abcdefghijklmnopqrstuwxyzabcdefghijklmnopqrstuvwxyz _-./. Spaces are not allowed. Path and directory names must not exceed system-specific constraints. If an older ersion of the agents exists in /opt/ibm/ccm/agent, you must specify a new installation directory. In next step you are asked if you want to migrate agent configuration from /opt/ibm/ccm/agent. 6. Accept the license agreements. A prerequisite scan of your enironment starts and takes a few moments to complete. If any requirements are missing, a message directs you to a log file with the reason for the failure. A prerequisite, such as a missing library or insufficient disk space, stops the installation. You must address the failure, and start the installation again. 7. If your monitoring agent requires configuration or you want to reiew the default settings, see Chapter 6, Configuring your agents, on page If you want to confirm that your agent is started, enter one of the following commands: Command./name-agent.sh start./name-agent.sh status Description Start the monitoring agent from the new install location. Verify that the monitoring agent reports data to the console. 9. If you installed the agents using a non-root user ID, you must complete the following steps as user root to finish setup: Chapter 5. Installing your agents 47

54 a. Run the following script: install_dir/bin/setperm -a Where install_dir is the installation directory of the agents. b. Run the following script: install_dir/bin/updateautorun.sh c. Restart the OS agent and any other agents that were started as the non-root user. (Step 8 on page 47) 10. After installation is complete and the command-line is aailable, you can repeat steps 3 on page 47 and 7 on page 47 to install more monitoring agents on the managed system. What to do next If a firewall is enabled, ensure that TCP port 80 for HTTP or 443 for HTTPS on the monitoring agent is open for incoming connections from the Performance Management serer. These are the default firewall ports for incoming HTTP and HTTPS requests and are likely open. If you want to iew managed systems from your IBM Tioli Monitoring domain in the Application Performance Dashboards, complete the tasks described in Integrating with Tioli Monitoring on page 193. If you are not logged in, follow the instructions in Starting the Performance Management console on page 205. For more information about the monitoring agent commands, including the name to use, see Using agent commands on page 223 Installing and configuring agents with non-root user If you do not hae root priileges and you want to install a monitoring agent, you can install the agent as a non-root user. Also, you can install the agent as a non-root user if you are a host administrator and you do not want to run the monitoring agent as a root user. Installation flow is the same as for root user. Procedure 1. Install your monitoring agents on Linux or AIX as described in Installing agents on page After agent installation is complete, run the following scripts, and proide the root password when prompted: a. To set the correct agent permission, enter install_dir/bin/setperm -a b. To update the system startup scripts, enter install_dir/bin/ UpdateAutoRun.sh What to do next If you want to run agents using different users, best practice is to create a common group on the system and make each user a member of this group. All agent files and directories should be owned by this group. You can execute the following utility to update ownership: install_dir/bin/secure.sh -g common_group_name. For more information about this utility, see Securing the agent installation files on page 49. Best practice is to use the same user ID for agent installation and upgrades. 48 IBM Monitoring: Installation and Setup Guide

55 Securing the agent installation files After installing monitoring agents as a non-root user on Linux or AIX systems, you can run the secure.sh script to secure the agent installation by remoing world write permissions and setting correct file ownership. Before you begin You must hae read, write, and execute permissions for the installation directory. Installation of the monitoring agents and any agent configuration must be completed on the system and the agents successfully started. If you are running agents as different user accounts, they must be members of the same group. (See option -g.) About this task Complete this step to lock down the file permissions in your installation. Options are aailable to require no root password, to specify a group name, and to iew help for the command. Procedure Run the following command from the install_dir/bin directory. Usage: secure.sh [-g common_group] [-n] [-h] In the simplest mode, run the./secure.sh script, which remoes world write permissions, and sets the current user and user's group as the file owners. If the script is run by a non-root user, the user is prompted for the root password. If a non-root user runs the./secure.sh script with the -n option, this user is not prompted for a root password. In this case, changing file permissions and changing ownership are done by using this user's priileges. If the installation directory contains files that are owned by different users and the current user has no priileges to modify permissions and ownership of other user's files, this mode can fail. If you want to set a certain group as the group owner, the owner must proide the -g option with a alid group name as an argument to that option. (See Example.) Run secure.sh -g common_group. The command changes ownership of the files and directories recursiely. Run the./secure.sh script with the h option to get help information for the script. Results The installation directory allows access to only the user who ran the script or to only the users in the specified group. Example If user Alice is a member of the system group that is named apmgroup, she can use the group to set file group ownership with the following command:./secure.sh -g apmgroup After the script is run, all files in install_dir hae apmgroup set for the group. Chapter 5. Installing your agents 49

56 Installing agents on Windows systems You can install some of the monitoring agents on a Windows systems. The following monitoring agents are supported on Windows 64-bit systems and, where noted, on Windows 32-bit systems: Monitoring Agent for DataPower Monitoring Agent for DB2 Monitoring Agent for Microsoft Exchange Serer Monitoring Agent for Microsoft Hyper-V Serer Monitoring Agent for Microsoft Internet Information Serices * Monitoring Agent for Microsoft.NET Monitoring Agent for Microsoft SQL Serer * Monitoring Agent for MySQL Monitoring Agent for Oracle Database Monitoring Agent for VMware VI Monitoring Agent for WebSphere Applications Monitoring Agent for Windows OS * Response Time Monitoring Agent * Supported on both 64-bit and 32-bit Windows systems Prerequisite tasks Reiew the agent prerequisite tasks to ensure a successful installation on Windows systems. Install from the command prompt on a local drie Use the Windows command prompt to start the installation script. Do not use Windows PowerShell to start the installation script. Copy the installation files to a local disk or a mapped network drie, and then start the installation script. Do not start the installation script from a network location. Start the installation script from a new command prompt. Do not start the installation script from an existing command prompt because the command prompt might hae outdated enironment ariables. Oracle Database agent If the Oracle Database agent monitors the Oracle database remotely, you must install the Oracle instant clients first from Oracle Technology Network - Instant Client Downloads on the following systems: Windows Serer bits Windows Serer 2012 R2 64-bits Windows Serer 2008 R2 Datacenter 64-bits Windows Serer 2008 R2 Enterprise 64-bits Windows Serer 2008 R2 Standard 64-bits The instant clients 10.x, 11.x, and 12.x are supported by the Oracle Database agent. MySQL agent For the Monitoring Agent for MySQL, you must install the MySQL serer and MySQL JDBC drier before you install the MySQL agent on that 50 IBM Monitoring: Installation and Setup Guide

57 system. To install the JDBC drier, see MySQL Connector/J JDBC drier ( If you are installing the agent on a VM that you plan to use as the base library image, do not configure the MySQL agent before you instantiate the other VMs. The MySQL agent must be configured on each instantiated VM Response Time agent For the Response Time Monitoring Agent, WinPcap is required before you can install the agent. You can download the drier from For detailed instructions, see Installing Windows packet capture library ( knowledgecenter/ss5md2_7.4.0/com.ibm.itcamt.doc_ /rt/ Install_Guide/win_net_mon.html) ITCAM agents IBM Tioli Composite Application Manager agents are not supported in your Performance Management enironment. You cannot install a Performance Management agent in a directory where ant ITCAM agent that uses Jaa is installed. The installation of the agent is blocked. Windows OS agent One of the serices installed with the agent is KNTCMA_FCProider. This OS agent serice was added to support future features. Installing agents To install a monitoring agent on a Windows system, you must download an agent installation image archie file from the IBM download site, pre-configure the agent image, and then install the agents. For details about the options for downloading the agent images, see Chapter 3, Download instructions, on page 27. Before you begin The monitoring agent installation archie file is named differently depending on where you obtained the file and which monitoring agents you are installing. Replace the name of the ConsumerVM_Media.zip in the instructions with the name of the file (or files) that you downloaded. Before installing the agents, make sure to pre-configure the agent images with the connection details for the Performance Management serer. For instructions, see Preconfiguring the agent images on page 39. You can install any combination of monitoring agents on a managed system. For example, if you install the Monitoring Agent for MySQL for monitoring MySQL serers, you might want to also install the Response Time Monitoring Agent to gather more response time information for your Ruby applications, and the Monitoring Agent for Windows OS to monitor other aspects of the system, such as the oerall CPU, memory, and disk. Reiew the agent prerequisites before you install the agents. For details, see Prerequisite tasks on page 50. About this task Be aware that when you install agents on a Windows system, some of the agents are configured and started automatically. Other agents must be configured before data is reported: Chapter 5. Installing your agents 51

58 The following agents are configured and started automatically: Response Time Windows OS agent Microsoft IIS agent Microsoft Hyper-V Serer agent The following agents are multiple instance agents. You must create the first instance and start the agent manually. A multiple instance agent means a single installation of the agent instantiates a unique monitoring instance for each unique application instance. These instances are isualized from the Performance Management console as a result. DB2 agent MySQL agent Oracle Database agent VMware VI agent Microsoft SQL Serer agent WebSphere Applications agent: The agent is started automatically but the data collector must be configured before data is reported. Microsoft.NET agent: The data collector must be configured before data is reported. Microsoft Exchange Serer agent: This agent is started automatically. Howeer, you must configure the agent to iew data for all attributes. Complete these steps to install monitoring agents on VMs and systems where the Windows operating system is installed. Procedure 1. Naigate to the directory where your pre-configured agent images are located. 2. Extract the agent installation files to the location where you want to install the monitoring agent software. 3. Run the installation script with Administrator priileges by using the command-line prompt: cd APM_Agent_Install_8.1.0 installapmagents.bat Restriction: For the WebSphere Applications agent, the Administrator priileges must be the same priileges that were used to install the WebSphere Application Serer. To install the agents in silent mode, see Installing agents silently on page 53. If you are upgrading the agent, this step is skipped, and the agent installs into the preious installation directory. 4. The installer checks that the agent images were preconfigured with parameters for connecting to the infrastructure node. If the agents images were not preconfigured, the installation is stopped. 5. Specify whether to install indiidual agents, a combination of the agents, or all of the agents. After selecting the agents to install, proide the name of the installation directory. The default path is C:\IBM\APM. The name of the installation directory cannot exceed 80 characters or contain non-ascii, special, or double-byte characters. Directory names in the path can contain only the following characters: abcdefghijklmnopqrstuwxyzabcdefghijklmnopqrstuvwxyz _\: ()~-./. 52 IBM Monitoring: Installation and Setup Guide

59 6. A prerequisite scan of your enironment starts and takes a few moments to complete. If any requirements are missing, a message directs you to a log file with the reason for the failure. 7. If your monitoring agent requires configuration or you want to reiew the default settings, see Chapter 6, Configuring your agents, on page If the monitoring agent is not started or you want to confirm that it is started, enter one of the following commands where name is db2, dotnet, mysql, oracle_database, os, rt, was, msexch, mssql, msiis, sap, ormware_i: Command name-agent.bat start Description Start the monitoring agent. Note: For multi-instance agents, you must specify the instance name also. See Using agent commands on page 223. name-agent.bat status Verify that the monitoring agent is started. Installing agents silently 9. After installation is complete and the command prompt is aailable, repeat steps 2 on page 52 and 7 to install and configure more monitoring agents. What to do next If a firewall is enabled, ensure that TCP port 80 for HTTP or 443 for HTTPS on the monitoring agent is open for incoming connections from the Performance Management serer. These are the default firewall ports for incoming HTTP and HTTPS requests and are likely open. If you are not logged in, follow the instructions in Starting the Performance Management console on page 205. To install a monitoring agent in silent mode, you must download an agent installation image archie file from the IBM download site, pre-configure the agent images, extract the agent installation files, prepare a silent response file, and run the installation script in silent mode. Before you begin 1. Reiew the prerequisite tasks for installing the monitoring agents, and download and extract the agent installation files. For details, see Installing agents on Linux and AIX systems or Installing agents on Windows systems. 2. Prepare a silent response file for the agent installation. Complete these steps: a. Locate the silent installation file APMaaS_silent_install.txt, make a copy of this file, and open it in a text editor. b. Uncomment the license agreement. c. Specify the agents to be installed. Complete one of the following steps: Uncomment the indiidual agents to be installed. For example: INSTALL_AGENT=os INSTALL_AGENT=ruby Uncomment INSTALL_AGENT=all to install all agents. d. Specify the agent installation directory. Uncomment AGENT_HOME and specify the directory. e. Sae the file. Chapter 5. Installing your agents 53

60 Procedure 1. Change to the directory where you extracted the installation script. Enter cd offering_agent_install_ersion 2. Run the installation command:./installapmagents.sh -p path_to_silent_response_file installapmagents.bat -p path_to_silent_response_file Results The agents are installed. What to do next Configure the agent. See the procedure and table of commands for Linux and AIX systems and for Windows systems. Bypassing the prerequisite scanner When you install your monitoring agents, a prerequisite scan of your enironment starts and takes a few moments to complete. If any requirements are missing, a message directs you to a log file with the reason for the failure. In an enironment where you hae irtual machine images that sere as templates, the prerequisite scan that is undertaken before installation begins can be done on only the first template image. If a VM image passes the scan, the other VMs created from that image will also pass. You can sae time by bypassing the prerequisite check for other VMs that were created from the same image. About this task After downloading and extracting the installation files, take this step to bypass the prerequisite scan. Procedure On the system where you plan to install monitoring agents, enter one of the following commands: export SKIP_PRECHECK=1 set SKIP_PRECHECK=1 What to do next Run the installation script to begin installing the monitoring agents without the prerequisite scan. Uninstalling monitoring agents Uninstall a single agent or all the agents from a managed system. 54 IBM Monitoring: Installation and Setup Guide

61 Before you begin For the Monitoring Agent for HTTP Serer, in the http.conf file, you must delete the Include statement, for example, "Include "/opt/ibm/apm/agent/tmp/khu/ km65s2_8044.conf", and restart the IBM HTTP serer before you uninstall the agent. For the Monitoring Agent for Python, run install_dir/lx8266/pg/bin/ uninstall.sh to remoe injection codes before you uninstall the agent. For the Monitoring Agent for PHP, run install_dir/bin/lx8266/pj/lib/ uninstall.instance_name.sh to moe injection codes before you uninstall the agent. For the Monitoring Agent for WebSphere Applications, you must unconfigure the data collector for all monitored serer instances before you uninstall the agent. Follow the instructions in WebSphere Applications agent: Unconfiguring the data collector on page 56. For the Node.js agent, you must remoe the monitoring plug-in from your Node.js application before you uninstall the agent. Follow the instructions in Node.js agent: Remoing the monitoring plug-in on page 60. For the Microsoft.NET agent, you must remoe the data collector from your.net applications before you uninstall the agent. Follow the instructions in Microsoft.NET agent: Remoing the.net data collector on page 61. About this task The Oracle agent on Windows systems can be uninstalled only by using the command prompt. Procedure 1. On the VM or system where the monitoring agent (or agents) is installed, start a command line and change to the binary directory: install_dir/bin install_dir\bin where install_dir the installation directory of the monitoring agent or agents. 2. To uninstall a specific monitoring agent, enter the agent script name and the uninstall option where name is the agent script name:./name-agent.sh uninstall name-agent.bat uninstall For a list of the agent script names, see Using agent commands on page 223. Remember: For the Monitoring Agent for Microsoft.NET, you must run the command with Administrator priileges. The monitoring agent is uninstalled from the managed system. If you hae uninstalled all of your monitoring agents indiidually, complete the next step to remoe the framework files. 3. To uninstall all the monitoring agents from the managed system with a confirmation prompt, enter the script name and uninstall all option:./smai-agent.sh uninstall_all Chapter 5. Installing your agents 55

62 smai-agent.bat uninstall_all A confirmation prompt is displayed, type 1 to continue, or type 2 to cancel. On Windows, you are not prompted for confirmation and the uninstallation starts immediately. All monitoring agents are uninstalled from the system or VM. 4. On Linux, and AIX, to force the uninstall of all the monitoring agents without a prompt for confirmation, enter the script name and the force uninstall all option:./smai-agent.sh uninstall_all force What to do next For the Monitoring Agent for HTTP Serer, after you uninstall the agent, you must remoe the following files manually: /tmp/khu_cps.properties /tmp/httpserer-disc.error For the Monitoring Agent for Python: 1. Delete the Django pyc configuration file to ensure the restored Django pyc file generates its binary. 2. Restart the Apache serer to remoe the loaded middleware in the Apache processes. For the Monitoring Agent for Ruby, to uninstall the diagnostics data collector: 1. Naigate to the home directory of your application, open its Gemfile, and remoe the following line from the file: gem stacktracer 2. Restart your Ruby on Rails application. 3. Uninstall the diagnostics data collector. Enter: gem uninstall Gemfile 4. Remoe the runtime directory of the data collector. The default location of this directory is install_dir/install-images/kkm/dchome For the Monitoring Agent for Microsoft.NET, complete these steps: 1. Remoe the data collector dll files using one of the following options: Reboot your operating system. Try to delete the file install_dir\qe\bin64\corproflog.dll. A File in Use dialog is displayed. It identifies the.net processes that are currently running. Restart each of the.net processes. 2. Restart your.net applications. WebSphere Applications agent: Unconfiguring the data collector To remoe the data collector from an application serer instance, you can use the interactie utility or the silent unconfiguration process. For instances monitored with PMI resource monitoring, unconfiguration is not aailable. Monitoring of PMI data continues while the serer is aailable. Unconfiguring the data collector interactiely If you no longer want the data collector to monitor one or more application serer instances, you can unconfigure the data collector for them. 56 IBM Monitoring: Installation and Setup Guide

63 About this task The unconfiguration utility (unconfig.sh/bat) is a menu drien command-line utility for unconfiguring the data collector. Procedure To unconfigure the data collector by responding to prompts, complete these steps: 1. Naigate to the dc_home\bin directory. 2. Optionally, set the location of the Jaa home directory before you start the utility. For example: export JAVA_HOME=/opt/IBM/AppSerer80/jaa set JAVA_HOME=C:\Progra~1\IBM\WebSphere\AppSerer80\jaa 3. Start the script. Run the command unconfig.sh Run the command unconfig.bat 4. The utility searches for all serer instances that are monitored by the data collector. Remember: For a stand-alone enironment, application serer instances must be running during the configuration. (A WebSphere Application Serer Liberty instance does not need to be running). For a Network Deployment enironment, the Node Agent and Deployment Manager must be running. Enter the number that corresponds to the application serer instance to unconfigure for data collection or enter an asterisk (*) to unconfigure data collection for all application serer instances. To specify a subset of serers, enter the numbers, separated by commas, that represent the serers. For example: 1,2,3. 5. The utility prompts you to specify whether you want to create a backup of your current WebSphere Application Serer configuration. Enter 1 to create a backup of the current configuration. Otherwise, enter 2 and skip to step The utility prompts you to specify the directory in which to store the backup of the configuration. Specify a directory in which to store the backup of the configuration or accept the default directory. The utility displays the name of the WebSphere home directory and the WebSphere profile for which a backup is created. 7. The utility indicates whether WebSphere Global Security is enabled for the WebSphere Application profile that you specified. If global security is not enabled, skip to step 10 on page The utility prompts you to specify whether to retriee security settings from a client properties file: The data collector communicates with the WebSphere Administratie Serices using the RMI or the SOAP protocol. If global security is enabled for a profile, you must specify the user ID and password of a user who is authorized to log in to the IBM WebSphere Application Serer administratie console for the profile. Alternatiely, you can encrypt the user name and password and store them in client properties files before configuring the data collector. You must use the sas.client.props file for an RMI connection, or the soap.client.props file for an SOAP connection. Chapter 5. Installing your agents 57

64 Enter 1 to allow the utility to retriee the user name and password from the appropriate client properties file and skip to step 10. Otherwise, enter 2 to enter the user name and password. 9. If you selected the option to back up the current WebSphere configuration, the utility starts backing up the configuration. 10. The utility unconfigures the data collector for the specified application serer instances. A status message is displayed to indicate that the data collector was successfully unconfigured. 11. After unconfiguring the data collector to monitor application serer instances, you must restart the instances. The data collector unconfiguration takes effect when the application serer instances are restarted. Results Data collection is unconfigured for the specified application serer instances. What to do next PMI resource monitoring for the serer instance is still aailable. If you want to use resource monitoring for a serer instance after unconfiguring the data collector, restart the monitoring agent by running the following commands: cd install_dir\bin was-agent.bat stop was-agent.bat start cd install_dir/bin./was-agent.sh stop./was-agent.sh start 58 IBM Monitoring: Installation and Setup Guide Unconfiguring the data collector in silent mode You can unconfigure the data collector using the unconfiguration utility in silent mode. When you unconfigure the data collector in silent mode, you first specify configuration options in a properties file. A sample properties file, sample_silent_unconfig.txt, is packaged with the unconfiguration utility. The file is aailable in the following directories: dc_home\bin dc_home/bin The dc_home ariable is the location where the data collector is installed. Complete the following steps to perform a silent unconfiguration: 1. Specify configuration options in the properties file. 2. Go to the following directory: dc_home\bin dc_home/bin 3. Run the following command: unconfig.bat -silent [dir_path]\silent file

65 unconfig.sh -silent [dir_path]/silent file 4. After unconfiguring the data collector to monitor application serer instances, you must restart the instances. The data collector configuration takes effect when the application serer instances are restarted. PMI resource monitoring for the serer instance is still aailable. If you want to use resource monitoring for a serer instance after unconfiguring the data collector, restart the monitoring agent by running the following commands: cd install_dir\bin was-agent.bat stop was-agent.bat start cd install_dir/bin./was-agent.sh stop./was-agent.sh start Properties file When you create your silent response properties file, keep in mind these considerations: A line in the file that starts with a number sign (#) is treated as a comment, and is not processed. If the number sign is used elsewhere in the line, it is not considered to be the start of a comment. Each property is described on a separate line, in the following format: property = alue. property This is the name of property. The list of alid properties that you can configure is shown in Table 8. alue This is the alue of the property. Default alues for some properties are already proided. You can delete default alues to leae property alues blank, or empty. An empty alue is treated as if the property is not specified, as opposed to using the default alue. To use default alues, you can comment out the property in the file. Passwords are in plain text. Properties and their alues are case-sensitie. Table 8 describes the properties that are aailable when unconfiguring the data collector in silent mode: Table 8. Aailable properties for running the unconfiguration utility in silent mode Property Comment WebSphere Application Serer connecting settings was.wsadmin.connection.host Specifies the name of the host to which the wsadmin tool is connecting. WebSphere Application Serer global security settings was.wsadmin.username Specifies the user ID of a user who is authorized to log on to the IBM WebSphere Application Serer administratie console. This user must hae the agent role on the application serer. was.wsadmin.password Specifies the password that corresponds to the user specified in the was.wsadmin.username property. Chapter 5. Installing your agents 59

66 Table 8. Aailable properties for running the unconfiguration utility in silent mode (continued) Property Comment WebSphere Application Serer settings was.appserer.profile.name was.appserer.home was.appserer.cell.name was.appserer.node.name Specifies the name of the application serer profile you want to unconfigure. Specifies the WebSphere Application Serer home directory. Specifies the WebSphere Application Serer cell name. Specifies the WebSphere Application Serer node name. Backup of the WebSphere Application Serer configuration was.backup.configuration was.backup.configuration.dir Specifies whether to back up the current configuration of the WebSphere Application Serer data collector configuration before unconfiguring the data collector. Valid alues are True and False. Specifies the location of the backup directory. WebSphere Application Serer runtime instance settings was.appserer.serer.name Specifies an application serer instance within the application serer profile for which you want to unconfigure the data collector. Tip: The silent response file can hae multiple instances of this property. Node.js agent: Remoing the monitoring plug-in Before you uninstall the Node.js agent, you must remoe the monitoring plug-in from your Node.js application. Procedure Remoe data collector plug-ins from the beginning of the Node.js application file. If you enabled resource data collection, remoe the following line from the beginning of the Node.js application file. require( install_dir/lx8266/nj/bin/plugin/knj_index.js );, where install_dir is the installation directory of Node.js agent. If you enabled resource data collection and deep-die data collection, remoe the following line from the beginning of the Node.js application file. require( install_dir/lx8266/nj/bin/plugin/knj_deepdie.js ); If you enabled resource data collection, deep-die data collection, and method traces collection, remoe the following line from the beginning of the Node.js application file. require( install_dir/lx8266/nj/bin/plugin/knj_methodtrace.js ); Restart your Node.js application to disable the data collector plug-ins. What to do next For more information about uninstalling the Node.js agent, see Uninstalling monitoring agents on page IBM Monitoring: Installation and Setup Guide

67 Microsoft.NET agent: Remoing the.net data collector Before you uninstall the Microsoft.NET agent, you must remoe the.net data collector from your.net applications. Procedure 1. Unregister the data collector. As an administrator, enter: cd install_dir\qe\bin configdc unregisterdc Where install_dir is the installation directory of the Microsoft.NET agent. 2. Stop all of your.net applications to disable the data collector. Enter net stop was /y What to do next Uninstall the Microsoft.NET agent. See Uninstalling monitoring agents on page 54. Chapter 5. Installing your agents 61

68 62 IBM Monitoring: Installation and Setup Guide

69 Chapter 6. Configuring your agents If your monitoring agent requires configuration or you want to reiew the default settings for an agent, follow the steps proided for your agent. Ensure agent prerequisites are met before configuring your monitoring agents. Reiew the prerequisite tasks proided in the following topics: Prerequisite tasks on page 50 Prerequisite tasks on page 42 Note: The Monitoring Agent for Linux OS and Monitoring Agent for Windows OS do not require additional configuration. Configuring the DataPower agent The DataPower agent proides a central point of monitoring for the DataPower Appliances in your enterprise enironment. You can identify and receie notifications about common problems with the appliances. Performance, resource, and workload information about the appliances is proided. Before you begin Before you use the Monitoring Agent for DataPower to monitor your DataPower appliances, you must complete some configuration steps. If the XML Management Interface of the DataPower Appliance has the SSL Proxy Profile enabled, before you configure the DataPower agent, you must export the public certificate that is used by the XML Management Interface of the DataPower Appliance. You must export the certificate to the temporary directory on the appliance, and then download it to the machine that runs the DataPower agent. To export the public certificate from the DataPower appliances, complete the following steps: 1. To download the crypto certificate that is used by the XML Management Interface of the DataPower Appliance, for example, pubcert:///mycert.pem, click Administration > Main > File Management and sae the certificate to the machine that runs the DataPower agent. 2. When you configure the DataPower agent, there is an option to specify the SSL Proxy Profile field. Enter the absolute path of the public certificate. About this task The DataPower agent is a multiple instance agent; you must create the first instance and start the agent manually. The Managed System Name includes the instance name that you specify, for example, instance_name:host_name:pc, where pc is your two character product code. The Managed System Name is limited to 32 characters. The instance name that you specify is limited to 28 characters, minus the length of your host name. For example, if you specify DataPower as your instance name, your managed system name is DataPower:hostname:BN. Copyright IBM Corp

70 Important: If you specify a long instance name, the Managed System name is truncated and the agent code does not display correctly. You can configure one instance to monitor all DataPower appliances in your system. You can run the configuration script to create an instance and change any configuration settings. You can edit the agent silent response file before you run the script to bypass the prompts and responses that are required. Procedure To configure the DataPower agent, complete one of the following procedures: To configure the agent by responding to prompts, complete the following steps: 1. Open the install_dir directory, where install_dir is the installation directory for the DataPower agent. 2. To check the names and settings of the configured agent instances, run the./cinfo -s bn command. 3. To configure the DataPower monitoring agent, run the./datapower-agent.sh config instance_name command. 4. Enter the SNMP properties for the receiing eents: Port Number Enter the destination UDP port for SNMP Traps and Notifications that are generated by the local SNMP agent or engine. By default, SNMP Traps and Notifications are sent to port 162. This port must be unique across all instances of this agent. For example, KQZ_SNMPEVENT_PORT= 162. Security Leel From the Security Leel list, select the security leel for notifications to this recipient. The alid alues include authpri, noauthnopri or authnopri. For example, KQZ_SNMPEVENT_SECURITY_LEVEL= authpri. SNMP User Name For SNMP User Name, enter the user name for connecting to the SNMP agent. The default is admin. For example, KQZ_SNMPEVENT_USER_NAME= admin. SNMP authentication protocol From the SNMP Authentication Protocol list, select the SNMP authentication protocol that is used to connect to the SNMP agent. The default is SHA. The alid alues include SHA or MD5. For example, KQZ_SNMPEVENT_AUTH_PROTOCOL=SHA. SNMP Authentication Secret For SNMP Authentication Secret, enter the authentication pass phrase for connecting to the SNMP agent. For example, KQZ_SNMPEVENT_AUTH_PASSWORD= password. SNMP Priacy Protocol For SNMP Priacy Protocol, enter the priacy protocol that is used to connect to the SNMP agent. The default is DES. For example, KQZ_SNMPEVENT_PRIV_PROTOCOL= DES. a. If you select Authentication or Priacy as the SNMP security leel, in the SNMP Priacy Secret field, enter the priacy pass phrase to connect to the SNMP agent. 64 IBM Monitoring: Installation and Setup Guide

71 b. If you enter the priacy pass phrase as the SNMP Priacy Protocol, re enter the same priacy pass phrase in the Confirm SNMP Priacy Secret field. c. Press Enter. 5. Enter information about the DataPower Appliance that you want to monitor: a. To add one monitored DataPower Appliance, type 1. b. Enter the managed system name of the agent. Note: This name is displayed in the Application instance list of APM UI. It must be unique for all instances of the agent and it must consist of only alphanumeric characters. 6. Enter the properties for the DataPower Appliance: Deice Host For Deice Host, enter the IP address of the monitored DataPower Appliance and then confirm the password. XML Management Interface Port For XML Management Interface Port, enter the port number for the XML Management Interface. The default number is For example, DP_PORT.ManageSystemName= User ID For User ID, enter the User ID to log in to the monitored DataPower Appliance. The default alue is admin. For example, DP_UID.ManageSystemName= admin. Password For Password, enter the password to log in to the monitored DataPower Appliance and then confirm the password. For example, DP_PASSWORD.ManageSystemName= password. System Log For System Log, type the system log file name. Note: The file name must be fully qualified. The file name can also be a dynamic file name. For more information about the dynamic file names syntax, see Dynamic file name syntax SSL Proxy Profile For SSL Proxy Profile, enter the absolute path of the public certificate for your SSL proxy profile, if the XML management interface of the deice is configured to use the profile. For example, DP_SSL_PROFILE.ManageSystemName= the location of the.pem file exported from datapower appliances >/mycert.pem. 7. To add the multiple DataPower appliances that you want to monitor, repeat step 6. Otherwise, type 5 and press Enter to complete the configuration. Silent configuration 1. To configure the agent by editing the silent response file and running the script with no interaction, complete the following steps: Open install_dir/samples/ datapower_silent_config.txt in a text editor. Open install_dir/samples/datapower_silent_config.txt in a text editor. 2. To configure SNMP Eents for the DataPower agent, enter the following properties: Chapter 6. Configuring your agents 65

72 Port Number Enter the Destination UDP port for SNMP Traps and Notifications that are generated by the local SNMP agent or engine. By default, SNMP Traps and Notifications are sent to port 162. This port must be different across all instances of this agent. For example, KQZ_SNMPEVENT_PORT=162. Security Leel Enter the name of the local SNMP3 user to use for Notifications to this recipient. This alue determines the authentication and priacy (encryption) or protocols and keys that are used. The alid alues include Authentication Priacy, No Authentication No Priacy, and Authentication No Priacy. For example, KQZ_SNMPEVENT_SECURITY_LEVEL= authpri. SNMP User Name Enter the user name for connecting to the SNMP agent. The default alue is admin. For example, KQZ_SNMPEVENT_USER_NAME= admin. SNMP Authentication Protocol Enter the authorization protocol that is used to connect to the SNMP agent. The alid alues include SHA, and MD5. For example, KQZ_SNMPEVENT_AUTH_PROTOCOL=SHA. SNMP Authentication Secret Enter the authentication pass phrase for connecting to the SNMP agent. For example, KQZ_SNMPEVENT_AUTH_PASSWORD= DES. SNMP Priacy Protocol Enter the priacy protocol that is used to connect to the SNMP agent. The default alue is DES. For example, KQZ_SNMPEVENT_PRIV_PROTOCOL= DES. SNMP Priacy Secret Enter the priacy pass phrase for connecting to the SNMP agent. For example, KQZ_SNMPEVENT_PRIV_PASSWORD= password. 3. To configure the DataPower agent to monitor an appliance, enter the following properties: Deice Host Enter the host name or IP address of the deice. For example, SOAP_HOST.ManageSystemName= datapower01. XML Management Interface Port Enter the port number for the XML Management Interface. The default alue is For example, DP_PORT.ManageSystemName= User ID Enter the User ID that is used to connect to the deice. The default alue is admin. For example, DP_UID.ManageSystemName= admin. Password Enter the password of the User ID. For example, DP_PASSWORD.ManageSystemName= password. System Log Enter the system log file name. For example, KBN_LOG_FILE.ManageSystemName= logtemp:/test_la/default-log. The file name must be fully qualified. You can also use a dynamic file name. For more information about dynamic file names, see IBM Agent Builder User's Guide. 66 IBM Monitoring: Installation and Setup Guide

73 SSL Proxy Profile Enter the absolute path of the public certificate for your SSL proxy profile, if the XML management interface of the deice is configured to use the profile. For example, DP_SSL_PROFILE.ManageSystemName= install_dir/config/mycert.pub. Important: ManageSystemName is unique. You must replace it with your own system name in all entries. If you want to monitor multiple appliances, copy and repeat the steps that are shown to monitor an appliance. Remember to set the appropriate ManageSystemName and DataPower Appliance parameters. What to do next To complete the configuration steps on the DataPower appliances, see Configuring DataPower Appliances. Configuring DataPower Appliances Before you can use the Monitoring Agent for DataPower to monitor your appliances, you must complete some configuration tasks on your appliances. Table 1 contains a list of the DataPower Appliances that are supported. Table 9. Supported DataPower Appliances Type Name Version B2B XB60 V 3.8 and later B2B XB62 V Edge XE82 V 1.0 Integration XI50 V 4.0 and later Integration XI and later Low Latency XM70 V 3.8 and later XML Accelerator XA35 V or V XML Security Gateway XS40 V and later Important: The DataPower XC10 Appliance is not supported in SaaS. Configuring SOAP settings If you want the DataPower agent to collect data from DataPower Appliances, you must ensure that the SOAP settings are enabled. Procedure 1. Log on to the WebGUI for the DataPower Appliance that you want to monitor. 2. Click Objects > Deice Management > XML Management Interface. Note: Ensure that the Administratie state is enabled. 3. For Port Number, enter the port number on which the DataPower agent listens for notification reports. The port number is 5550 by default. 4. For Enabled Serices, ensure that SOAP Management is selected. Chapter 6. Configuring your agents 67

74 Configuring SNMP settings If you want to use SNMP as the communication protocol between the DataPower agent and the DataPower Appliance, you must configure SNMP settings on the DataPower Appliance. Procedure 1. Log on to the WebGUI for the DataPower Appliance that you want to monitor. 2. Click Administration > Access > SNMP Settings. 3. For Admin State, select enabled. 4. For Local Port, enter the UDP port number that is monitored by the SNMP agent or engine for incoming SNMP requests. The port number that is resered for the SNMP agent is To use SNMP3 as the communication protocol between the agent and the monitored DataPower Appliance, complete the following steps: a. From the SNMP3 Users list, select a user ID and click Add. b. To configure the user credentials, click Edit item. c. On the SNMP V3 User Credentials page, click Add. d. For Authentication Protocol, select MD5 or SHA. The MD5 option indicates that the user ID uses the HMAC-MD5-96 authentication protocol. The SHA option indicates that the user ID uses the HMAC-SHA-96 authentication protocol. Ensure that you do not select None. e. For Authentication Secret Type, select Password. f. For Authentication Secret, enter a plain text password that is at least 8 characters long. You must enter the same password in the text boxes that relate to this field. g. For Priacy Protocol, select DES. h. For Priacy Secret Type, select Password. i. Click Apply. j. On the SNMP V3 User Credentials page, click Apply. k. On the Configure SNMP Settings page, for SNMP3 Security Leel select the minimum security leel for incoming SNMP3 Get and Set requests. Then, for SNMP3 Access Leel, select read-only or read/write, and then click Apply. 6. To apply SNMP1 or SNMP2c as the communication protocol between the agent and the monitored DataPower Appliance, complete the following steps: a. To open the SNMP1/2c Communities page, click SNMP1/2c Communities. b. For Associated Domain, select the application domain that is isible to the SNMP managers who belong to this community. The default alue is the default application domain. c. For Mode, select read-only or read/write. d. Click Apply. 7. Click Sae Config. Configuring trap eent subscriptions If you want traps to be sent to the DataPower Appliance, you must complete steps to specify which traps are sent to the agent. 68 IBM Monitoring: Installation and Setup Guide

75 Procedure 1. Log on to the WebGUI for the DataPower Appliance that you want to monitor. 2. Click Administration > Access > SNMP Settings. 3. Click Trap Eent Subscriptions. 4. For Minimum Priority, select the minimum trap eent priority. Note: The priorities are hierarchical and the lowest priority is at the end of the list. The trap eents that relate to the selected priority and beyond are sent to the agent. For example, if you select alert, trap eents that relate to alert and emergency are sent to the agent. If you select debug, which is the lowest priority, all trap eents are sent to the agent. 5. For Eent Subscriptions, click Add if you want to add eent codes that trigger traps that are sent to the configured trap targets. 6. Click Apply. 7. Click Sae Config. Configuring trap and notification targets If you want traps to be sent to the DataPower Appliance, you must specify traps and notification targets. Procedure 1. Log on to the WebGUI of the DataPower Appliance that you want to monitor. 2. Click Administration > Access > SNMP Settings. 3. Click Trap and Notification Targets. 4. Click Add. 5. For Remote Host Address, enter the host name or IP address of the computer that hosts the DataPower agent Appliance. 6. For Remote Port, enter the port number on which the DataPower agent listens for trap information. 7. For Version, select the SNMP ersion that you want to use for trap monitoring on the agent side. 8. If you select ersion 1 or ersion 2 in step 7, for Community Name enter the community name and then click Apply. If you select ersion 3 in step 7, for Security Name enter an SNMP V3 user ID, for Security Leel select the security leel, and then click Apply. 9. Click Apply. 10. Click Sae Config. Setting up syslog You can set up the DataPower agent to monitor the system logs of the DataPower Appliance. Before you begin If the DataPower agent is installed on a Windows operating system, you must first install a system log daemon on the computer. The system log daemon collects the system logs or system logs files on a shared disk and ensures that the agent has the authority to read the system log files on that disk. Chapter 6. Configuring your agents 69

76 Procedure 1. Log on to the WebGUI of the DataPower Appliance that you want to monitor. 2. Click Administration > Miscellaneous > Manage Log Targets. 3. Click Add. a. For Name, enter the name of the log target. b. Select Enabled. c. From the Target Type list, select syslog or syslog-ng. d. In step c, if you selected syslog-ng for SSL Proxy Profile you can specify the name of the SSL proxy profile object that defines the configuration for secure communication. The default option is none. For more information about configuring SSL proxy profiles on a DataPower Appliance, see the Defining an SSL profile procedure. e. For Local Identifier, enter a local identifier. A local identifier is a descriptie string that identifies the log target to remote recipients. f. For Remote Host, enter the host name or IP address of the computer that hosts the DataPower agent Appliance. g. For Remote Port, enter a port number. The port number that is resered for syslog is 514. Syslog-ng has no resered port number. You can use any unused UDP or TCP port number. h. From the Syslog Facility list, select the appropriate syslog facility. Syslog facility is included in messages that are sent to the syslog log target. 4. Click Eent Subscriptions. 5. On the Eent Subscriptions page, complete the following steps: a. Click Add. b. From the Eent Category list, select the eent category that you want to monitor. c. From the Minimum Eent Priority list, select the minimum eent priority. d. Click Apply. Defining an SSL profile You must define an SSL profile. Procedure 1. Select OBJECTS > Crypto > SSL Proxy Profile. 2. On the Configure SSL Proxy Profile page, enter the following information: a. For Direction, select one of the following options: Forward specifies a mode in which the SSL Proxy functions as an SSL client. In client mode, SSL is used oer the deice-to-serer connection. Reerse specifies a mode in which the SSL Proxy functions as an SSL serer. In serer mode, SSL is used oer the deice-to-client connection. Two-way specifies a mode in which the SSL proxy functions both as an SSL client and as an SSL serer. In two-way mode, SSL is used oer both the deice-to-serer connection and oer the deice-to-client connection. b. For Reerse (Serer) Crypto Profile, from the list, select the crypto profile that defines the SSL serice leel between the deice that acts as an SSL serer and the front-end SSL clients. This setting is releant when the SSL Proxy Profile operational mode is either reerse or two-way. Select the crypto profile that defines the SSL serice to front-end clients. Retain the default alue (none) if the operational mode is forward. You can use + and... to create a new crypto profile or to edit a crypto profile. 70 IBM Monitoring: Installation and Setup Guide

77 c. For Serer-side Session Caching, select On to enable serer-side caching or Off to disable serer-side caching. By default, SSL serer implementations cache SSL session-specific state data, such as the session ID, the peer certificate, compression method, and crypto specs and secrets. d. For Client Authentication is Optional, this property is meaningful when the SSL client authentication is enabled in the serer cryptographic profile. When both properties are enabled, SSL client authentication is optional (a setting of yes). The request does not fail when there is no client certificate. When disabled (the default setting of no), SSL client authentication is required by the application serer. Enabling syslog If you want the DataPower agent to monitor the system logs of the DataPower Appliance, in addition to setting up the syslog on the appliance, you must also enable syslog on the computer that hosts the DataPower agent. Before you begin If the DataPower agent is installed on a Windows operating system, you must first install a system log daemon on the computer to collect the system logs. Alternatiely, you can sae the system log files on a shared disk and ensure that the agent has the authority to read the system log files on that disk. Procedure To enable syslog, depending on the operating system that hosts the DataPower agent, complete one of the following procedures: On Red Hat Enterprise Linux 6, to open the syslog.conf file, run the i /etc/syslog.conf command. 1. Append the Syslog_fac.* /ar/log/filename command to the end of the syslog.conf file and sae it. Syslog_fac is the syslog facility and file name is the name of the file where you sae the syslog. 2. To open the syslog.conf file, run the i /etc/syslog.conf command. 3. Change the alue of the SYSLOGD_OPTIONS parameter to the following alue: SYSLOGD_OPTIONS = "-m 0 -r" Note: Depending on the Linux distribution, this ariable might also be named SYSLOGD_PARAMS. 4. To restart the syslog serer, run the serice syslog restart command. On SUSE Linux Enterprise Serer 11, to enable syslog-ng, complete the following steps: 1. To open the syslog file, run the i /etc/sysconfig/syslog command. 2. Verify that the alue of the SYSLOG_DAEMON parameter is syslog-ng. 3. In the syslog-ng.conf file, append the following line to the definition of the src source: tcp(ip("ip_address") port(port_number) keep-alie(yes)); Where ip_address is the IP address of the computer that hosts the DataPower agent and port_number is the port number that is used for receiing syslog-ng messages. 4. To filter messages from the DataPower appliances, in the syslog-ng.conf file, create a filter. For example, the filter f_dp {leel(debug..emerg) and facility(user);}; Chapter 6. Configuring your agents 71

78 Configuring the DB2 agent filter statement defines a filter that accepts messages from the debug leel to the emergency leel that specify the user as the syslog facility. 5. In the syslog-ng.conf file, use a destination statement to define where the messages are written as shown in the following example: dplog {file("/ar/log/dpsyslog.log");}; This destination statement specifies that messages are written to the dpsyslog.log file in the /ar/log directory. 6. In the syslog-ng.conf file, use a log statement to connect sources and destinations. For example, the {source(src);filter(f_dp);destination(dplog);}; log statement connects the src source and the dplog destination. 7. Sae the syslog-ng.conf file. 8. To restart the syslog serer, run the /etc/init.d/syslog restart command. The Monitoring Agent for DB2 monitors the aailability and performance of the DB2 serer. You can monitor multiple serers from the Performance Management console; each serer is monitored by a DB2 agent instance. For example, you can analyze the applications or the databases with the highest percentage of failed SQL statements. You can gather information to detect problems early that helps you to preent the problems from occurring again. About this task The DB2 agent is a multiple instance agent; you must create the first instance and start the agent manually. The Managed System Name includes the instance name that you specify, for example, instance_name:host_name:pc, where pc is your two character product code. The Managed System Name is limited to 32 characters. The instance name that you specify is limited to 28 characters, minus the length of your host name. For example, if you specify DB2inst1 as your instance name, your managed system name is DB2inst1:hostname:ud. Important: If you specify a long instance name, the Managed System name is truncated and the agent code does not display correctly. Use the same root user or non-root user ID to configure a DB2 agent instance as was used to install the agent. Run the configuration script to create an instance and change the configuration settings. You can edit the DB2 silent response file before you run the configuration script to bypass the prompts and responses that are required. After you configure the DB2 agent, be sure to start the agent with a user ID that has DB2 SYSADM authority for the monitored instance. SYSADM authority is required in order for the agent to turn on all monitor switches. The instance owner user, for example: DB2inst1 must be used. 72 IBM Monitoring: Installation and Setup Guide

79 Note: The DB2 agent can be configured on Windows systems by using the silent mode only. Procedure To configure the agent with the default settings, not responding to prompts, complete the following steps: 1. Enter the following command where instance_name is the name you want to gie to the instance: install_dir/bin/db2-agent.sh config instance_name install_dir/samples/db2_silent_config.txt 2. Enter the following command to start the DB2 agent agent: install_dir/bin/db2-agent.sh start instance_name To configure the agent by editing the silent response file and running the script with no interaction, complete the following steps: 1. Open the DB2_silent_config.txt file in a text editor: install_dir/samples/db2_silent_config.txt install_dir\tmaitm6_x64\samples\db2_silent_config.txt 2. For DB2 SQL Path, you can leae this field blank because the dialog path is specified in the next step. The default files are in the following locations: CANDLEHOME/config/kudcussql.properties CANDLEHOME\TMAITM6_x64\kudcussql.properties 3. For dialog path, ifthedb2diag log file is in the default directory, you can leae this field blank. If the file is not in the default directory, enter the path of the directory. The following directories are the defaults: /home/db2owner_home_dir/sqllib/db2dump You must specify the path to the directory of the DB2 diagnostics log file, for example, KUD_DIAGLOG_PATH= /home/db2inst1/sqllib/db2dump. Windows Install_Drier:\Documents and Settings\All Users\Application Data\IBM\DB2\DB 2COPYNAME\DB2INSTANCENAME For example, C:\Documents and Settings\All Users\Application Data\IBM\DB2\DB 2COPY1\DB2 4. For dialog message ID filter, you must specify the MSGID to filter the Diagnostic log. The MSGID is a combination of the message type, message number, and seerity leel. You can also use a regular expression, for example, KUD_DIAGLOG_MSGID_FILTER= ADM1\d*1E ADM222\d2W. 5. For monitor remote partitions, you must specify whether the DB2 agent monitors partitions in remote hosts, for example, KUD_MONITOR_REMOTE_PARTITIONS= Yes. 6. For monitor all databases, you must specify whether you want the DB2 agent to monitor all databases, for example, KUD_MONITOR_ALL_DATABASES= Yes. 7. Sae and close the DB2_silent_config.txt file, and enter the following command where instance_name is the name that you want to gie to the instance: install_dir/bin/db2-agent.sh config instance_name install_dir/samples/ DB2_silent_config.txt install_dir\tmaitm6_x64\samples\db2_silent_config.txt Important: Ensure that you include the absolute path to the silent response file. Otherwise, agent data is not shown in the dashboards. Chapter 6. Configuring your agents 73

80 8. Enter the following command to start the agent: install_dir/bin/db2-agent.sh start instance_name install_dir\bin\db2-agent.bat start instance_name To configure the agent by running the script and responding to prompts, complete the following steps: 1. Enter the following command where instance_name is the name that you want to gie to the instance: install_dir/bin/db2-agent.sh config instance_name 2. Respond to the prompts by using the descriptions of the parameters that are proided in steps 2 to 6 of the To configure the agent by editing the silent response file and running the script with no interaction procedure. 3. Enter the following command to start the agent: install_dir/bin/db2-agent.sh start instance_name Configuring the HMC Base agent The HMC Base agent proides you with the capability to monitor the Hardware Management Console (HMC). The agent monitors the aailability and health of the HMC resources: CPU, memory, storage, and network. The agent also reports on the HMC inentory and configuration of Power serers, CPU pools, and LPARs. The CPU utilization of the Power serers, LPARs, and pools are monitored by using HMC performance sample data. Before you begin Before you configure the HMC Base agent, you must run the "perl install_dir/aix526/ph/bin/setup_hmc_key.pl" command. Then, to create the rsa key pair for the HMC user and authorize the agent to set up an ssh connection with the HMC, you must complete the following steps: 1. Open the install_dir/aix526/ph/bin directory, where install_dir is the installation directory for the HMC Base agent. 2. Run the "perl setup_hmc_key.pl" command. 3. To create the rsa key pair for HMC user, complete the following steps: a. When prompted for the name of the HMC, type the host name or IP address of the HMC serer and press Enter. b. When prompted for the HMC user name, type the HMC user name and press Enter. c. When prompted for the password that is associated with the HMC user name, type the password and press Enter. Procedure To configure the agent by editing the silent response file and running the script with no interaction, complete the following steps: 1. Open the hmc_base_silent_config.txt file in a text editor: install_dir/samples/hmc_base_silent_config.txt. 2. For HMC Hostname, you can specify the IP address or host name. 3. For HMC Username, you must enter the logon user name for the HMC, for example, HMC_USERNAME= hscroot. 74 IBM Monitoring: Installation and Setup Guide

81 Note: The logon user name that you assign to the HMC requires hsciewer authority at a minimum. 4. For Maximum Number of Data Proider Log Files:, you must specify the maximum number of data proider log files that are created. for example, KPH_LOG_FILE_MAX_COUNT= For Maximum Size in KB of Each Data Proider Log, you must enter the maximum size in KB that a data proider log file might reach before a new log file is created, for example, KPH_LOG_FILE_MAX_SIZE= For Leel of Detail in Data Proider Log, you must enter the amount of detail that the data proider includes in the data proider log files, for example, KPH_LOG_LEVEL=Fine. You must specify one of the following alues: 1= Off 2=Seere 3=Warning 4=Info 5=Fine 6=Finer 7=Finest 8=All Important: The default alue is Sae and close the hmc_base_silent_config.txt file, then enter:./hmc_base-agent.sh config instance_name install_dir/samples/ hmc_base_silent_config.txt where instance_name is the name you want to gie the instance and install_dir is the HMC Base agent installation directory. The default installation directory is /opt/ibm/apm/agent. To configure the agent by responding to prompts, complete the following steps: 1. Open the install_dir/bin directory, where install_dir is the installation directory for the HMC Base agent. 2. To configure the HMC Base agent, run the following command:./hmc_base-agent.sh config instance_name. 3. When prompted to edit the Monitoring Agent for HMC Base settings, press Enter. The default alue is Yes. 4. To enter the HMC configuration information, complete the following steps. a. When prompted for the HMC Hostname, type the host name or IP address and press Enter. b. When prompted for HMC Username, type the logon user name that is associated with the HMC, and press Enter. 5. To enter the data proider information, complete the following steps: a. When prompted for the maximum number of data proider log files, type the amount of log files and press Enter. The default maximum number of data proider log files is 10. b. When prompted for the maximum size in KB of each data proider log, type the size and press Enter. The default maximum size in KB is c. When prompted for the Leel of detail in data proider log, type one of the following leels and press Enter: 1= Off Chapter 6. Configuring your agents 75

82 2=Seere 3=Warning 4=Info 5=Fine 6=Finer 7=Finest 8=All What to do next To start the agent, enter:./hmc_base-agent.sh start InstanceName. Configuring the HTTP Serer agent The Monitoring Agent for HTTP Serer starts automatically. You must reiew the configuration file that the agent creates for the IBM HTTP Serer. Then, you must add the data collector configuration manually to the serer configuration file. Reiewing the data collector configuration You must start the HTTP Serer when the HTTP Serer agent is running. Then the HTTP Serer agent discoers the serer and generates a httpd configuration file in the install_dir/tmp/khu directory for the serer. About this task The name of the generated configuration file contains a short ersion of the host name and the lowest port number on which this HTTP Serer listens, as shown here: short host name-lowest port number.conf This file includes the following information about the data collector: Details about the path of the httpd.conf file that the HTTP Serer uses, for example, KhuShmemPath "/IBM/HTTPSerer/conf/httpd.conf". Location of the library to load Permissions that are associated with the shared memory This httpd configuration file must be included by the main configuration file for the HTTP Serer. Procedure 1. To reiew the generated configuration file, check that the location for the library (LoadModule) is correct and that the correct file name is proided for KhuShmemPath to calculate shared memory ID, as shown in the following example: For IBM HTTP Serer ersion 8 and aboe, 64-bit, the configuration file contains this information: # # Settings for Monitoring Agent for HTTP Serer module. # LoadModule khu_module "install_dir/lx8266/hu/lib/khuapache22dc_64.so" <IfModule mod_khu.c> KhuShmemPerm 660 KhuShmemPath "/opt/ibm/httpserer/conf/httpd.conf" <IfModule> 76 IBM Monitoring: Installation and Setup Guide

83 For IBM HTTP Serer ersion 7, 32-bit, the configuration file contains this information: # # Settings for Monitoring Agent for HTTP Serer module. # LoadModule khu_module "install_dir/lx8266/hu/lib/khuapache22dc_32.so" <IfModule mod_khu.c> KhuShmemPerm 660 KhuShmemPath "/opt/ibm/httpserer/conf/httpd.conf" <IfModule> For Apache ersion 2.4, 64-bit, the configuration file contains this information: # # Settings for Monitoring Agent for HTTP Serer module. LoadModule khu_module "install_dir/lx8266/hu/lib/khuapache24dc_64.so" <IfModule mod_khu.c> KhuShmemPerm 660 KhuShmemPath "apache_dir/conf/httpd.conf" <IfModule> Note: If you hae multiple HTTP Serers that are installed and running, you might see multiple configuration files generated. 2. You distinguish multiple configuration files according to their lowest port numbers. 3. You must include the correct files in the main configuration files for multiple HTTP Serers. Otherwise, the shared memory does not work and the agent does not receie the correct monitoring data. Actiating the data collector To actiate the data collector, you must include the generated data collector configuration file in the main configuration file for the HTTP serer by using the Include statement. Procedure 1. If you hae an IBM HTTP Serer that is installed in the /opt/ibm/httpserer directory and the generated data collector configuration file is install_dir/tmp/khu/short host name_lowest port number.conf, you can change the /opt/ibm/httpserer/conf/httpd.conf web serer main configuration file. Append the following statement to the end of the main configuration file: Include install_dir/tmp/khu/short host name_lowest port number.conf 2. If you hae multiple HTTP Serers that are installed but you do not want to monitor any of them, you skip step 1 and the procedure to restart the HTTP Serer. Then, the agent ignores the HTTP Serer that does not include the data collector configuration file. Restarting the HTTP Serer You must restart the HTTP Serer so that the serer loads the data collector. Then the HTTP Serer agent starts to receie monitoring data from the data collector. If you do not restart the serer, the monitoring data is not aailable. The serer acts only as a registered managed system. Procedure 1. For example, to restart the IBM HTTP Serer, open the bin directory for IBM HTTP serer home. Chapter 6. Configuring your agents 77

84 2. Run the following commands:./apachectl -k stop./apachectl -k start Configuring the JBoss agent The JBoss agent monitors the resources of JBoss application serers and the JBoss Enterprise Application platform. Use the dashboards that are proided with JBoss agent to identify the slowest applications, slowest requests, thread pool bottlenecks, JVM heap memory and garbage collection issues, the busiest sessions and other bottlenecks on the JBoss application serer. This agent is a multiple instance agent; you must create the instance first and then start the agent manually. Before you begin Before you use the JBoss agent to monitor the JBoss Application Serer 5.1 and 6.0, you must enable the Jaa Management Extensions (JMX) serice on the serer. You must also add the following parameter to the JBOSS_HOME/bin/run.sh script: "JAVA_OPTS="-Djboss.platform.mbeanserer $JAVA_OPTS"". About this task The Managed System Name includes the instance name that you specify, for example, instance_name:host_name:pc, where pc is your two character product code. The Managed System Name is limited to 32 characters. The instance name that you specify is limited to 28 characters minus the length of your host name. For example, if you specify JBoss as your instance name, your managed system name is JBoss:hostname:JE. Important: If you specify a long instance name, the Managed System name is truncated and the agent code does not display correctly. You can run the configuration script to create an instance and change any configuration settings. You can edit the agent silent response file before you run the script to bypass the prompts and responses that are required. Procedure To configure the agent by editing the silent response file and running the script with no interaction, complete the following steps: 1. Open install_dir/samples/jboss_silent_config.txt in a text editor. 2. Enter the following Jaa parameters: Serer Name The name of the JBoss Application Serer. For example, KJE_SERVER=jboss1. Jaa Home The path to where Jaa is installed. The default path is: JAVA_HOME=/opt/ibm/apm/agent/JRE/lx8266/jre. JMX user ID The user id to connect to the MBean serer. For example, KQZ_JMX_JSR160_JSR160_USER_ID= Admin. 78 IBM Monitoring: Installation and Setup Guide

85 Note: This setting is required if JMX authorization is enabled in JBoss. JMX Password The password to connect to the MBean serer. For example, KQZ_JMX_JSR160_JSR160_PASSWORD = password. Note: This setting is required if JMX authorization is enabled in JBoss. JMX serice URL The serice URL to connect to the MBean serer. For JBoss EAP 6, you specify the URL as KQZ_JMX_JSR160_JSR160_SERVICE_URL = serice:jmx:remoting-jmx:// ip:9999. For JBoss AS 5.1 and JBoss AS 6.0, you specify the URL as KQZ_JMX_JSR160_JSR160_SERVICE_URL = serice:jmx:rmi://ip/jndi/ rmi://ip:1090/jmxconnector. Important: You must substitute the ip address proided with the real ip address. JMX class path For JBoss EAP 6.0 or later, the JAR files that are searched to find information about a Jaa class or Jaa resource, for example, KQZ_JMX_JSR160_JSR160_JAR_FILES =/opt/eap-6.3.0/jboss-eap-6.3/bin/ client/jboss-cli-client.jar. Important: For JBoss AS 5.1 and AS 6.0, you must leae this parameter blank. 3. Sae and close the jboss_silent_config.txt file, and enter the following command where instance_name is the name that you want to gie to the instance: install_dir/bin/jboss-agent.sh config instance_name install_dir/samples/ jboss_silent_config.txt Important: Ensure that you include the absolute path to the silent response file. Otherwise, agent data is not shown in the dashboards. 4. Enter the following command to start the agent: install_dir/bin/jboss-agent.sh start instance_name To configure the agent by running the script and responding to prompts, complete the following steps: 1. Enter the following command where instance_name is the name that you want to gie to the instance: install_dir/bin/jboss-agent.sh config instance_name 2. Respond to the prompts by using the descriptions of the parameters that are proided in step 2 of the To configure the agent by editing the silent response file and running the script with no interaction procedure. 3. Enter the following command to start the agent: install_dir/bin/jboss-agent.sh start instance_name Chapter 6. Configuring your agents 79

86 Configuring the Linux KVM agent The Monitoring Agent for Linux KVM supports connection to both the Enterprise Linux based KVM hyperisor and Red Hat Enterprise Virtualization Manager (RHEVM) enironments. You can use the same configuration script to configure instances for these enironments. Before you begin Before you run the configuration script, you must complete one of the following procedures: For the RHEVM configuration, complete the following steps: 1. Download the security certificate by browsing to the following location: where RHEVM-HOST is the name of the host and RHEVM-PORT is the name of the port that you use in your RHEVM enironment. Note: The url contains the host and port from the RHEV-M enironment. 2. Import the certificate file to generate a local keystore by using the following keytool command: keytool -import -alias ALIAS -file CERTIFICATE_FILE -keystore KEYSTORE_FILE Note: The keytool utility is aailable with Jaa Runtime Enironment (JRE). 3. In the agent configuration steps, specify the path for this KEYSTORE_FILE for the KEYSTORE_PATH parameter and include the file name in the path. 4. Create a user account with read-only access to the REST API of the Red Hat Enterprise Virtualization Manager (RHEV-M) to collect information about clusters, hosts, and irtual machines that RHEV-M manages. If there is no user domain, such as an LDAP or an Actie Directory, configured, then use the default "admin" user and "internal" domain in the configuration steps to connect to RHEVM, or complete the following steps: a. Open the Red Hat Enterprise Virtualization Manager Web Administration portal. b. Click Configure. c. In the Configuration window, select Roles. 1) To create a role, click New. 2) In the New Role window, add the name of the role and select Admin as the account type. Then, in the Check boxes to Allow Action pane, leae the check boxes clear. Click OK. d. In the Configuration window, select System Permission. 1) To grant a user permission, click Add. 2) In the Add System Permission to User window, select the user to whom you want to grant the permission. 3) From the Assign role to user list, select the role that you created in step 4 (c) and click OK. For the Linux based KVM hyperisor configuration, complete the following steps: 1. For the Linux based KVM Hyperisor, the Linux KVM agent collects metrics by connecting remotely to each hyperisor by using libirt that manages your QEMU-KVM irtual machines. The libirt client on the agent 80 IBM Monitoring: Installation and Setup Guide

87 enironment uses seeral different remote transport protocols, as shown on this Remote support page. Choose one of the following protocols for monitoring purposes: SSH protocol For the SSH agent, assume that you install the Linux KVM agent on Host A and you want to monitor the hyperisor on Host B remotely. First, you must configure the SSH agent so that the SSH agent makes a connection from Host A to Host B without requesting a password. a. Log on to Host A with the same ID that runs the Linux KVM agent process, for example, the root user ID. Tip: Ensure that you know the ID on Host B that accepts the SSH connection, and the root user ID on Host A. b. Generate the id_rsa and id_rsa.pub keys on Host A by using the ssh-keygen utility in Linux to generate the keys. Note: The keys are saed in~/.ssh: $ ssh-keygen -t rsa. c. Copy the authorized keys from Host B so that you can add the public key for Host A to it: $ scp Id on Host B@name or IP address of Host B:~/.ssh/authorized_keys ~/.ssh/authorized_keys_from_b. d. Append the public key for Host A to the end of the authorized keys for Host B: cat ~/.ssh/id_rsa.pub >> ~/.ssh/ authorized_keys_from_b. e. Copy the authorized keys back to Host B: $ scp ~/.ssh/ authorized_keys_from_b Id on Host B@name or IP address of Host B:~/.ssh/authorizede_keys Note: If you are monitoring multiple hosts, repeat steps c, d, and e for each host. f. Now, you can remoe ~/.ssh/authorized_keys_from_b. g. Add the following command to the ~/.bash_ profile of the current ID on Host A: $ eal `ssh-agent`. Note: Ensure you use the single back quotation mark (`), located under the tilde (~) on US keyboards, rather than the single quotation mark ('). h. Add the identity to Host A by using the $ ssh-add ~/.ssh/id_rsa command and enter the password that you used when you created the ID. If you receie the following message: Could not open a connection to your authentication agent you must run the exec ssh-agent bash command. Note: You can replace the bash with the shell that you are using and then run the following ssh-add command again: $ ssh-add ~/.ssh/id_rsa. i. Test the SSH agent to ensure that it connects from Host A to Host B without haing to enter the SSH password. If you are monitoring multiple hosts, use the following command to test the connection for each host:$ ssh Id on Host B@name or IP address of Host B Chapter 6. Configuring your agents 81

88 Post-configuration erification a. Use the following irsh command to check your work: irsh -c qemu+ssh://id on Host or IP address of Host B:port/system. b. If you hae not changed the default SSH port, omit the :port section of the command. Note: If the irsh command succeeds, the Linux KVM agent connects. c. You must restart Host A before you restart the Linux KVM agent on Host A. To restart, you must rerun the ssh-add command and supply the password each time. Note: You can use SSH keychains to aoid reentering the password. TLS protocol a. Log in to Host B and confirm that you installed the gnutls and gnutls-utils packages. b. Edit /etc/libirt/libirtd.conf to ensure that listen_tls is enabled and that the tls_port is specified with the default port number. c. Open Remote support and follow the instructions to set up a certificate authority between Host A and Host B. Note: See the sections to Set up a certificate authority (CA), Issue serer certificates, and Issue client certificates. d. To restart the libirt daemon on Host B in listening mode, you either run it with the --listen flag or edit /etc/sysconfig/libirtd and uncomment LIBVIRTD_ARGS="--listen". Post-configuration erification To check your configuration, use the irsh command and enter irsh -c qemu+tls://name or the IP address of the Host B:port/system. If you did not change the default TLS port, you can omit the :port section of the command. If the irsh command succeeds, the Linux KVM agent connects. About this task The Linux KVM agent is a multiple instance and multi-connection agent. Multi-instance means that each instance can make multiple connections to one or more RHEV-M or KVM hyperisor enironments. It is recommended to hae separate instances for the KVM hyperisor and the RHEV-M enironments. After you install the agent software either on a physical host or VM, you configure the agent instance by using the configuration steps. You can create multiple instances. RHEV-H is the hyperisor from Red Hat that enables irtualization management, and it is not related to the agent directly. You could use the RHEV-H hyperisor to configure hyperisor hosts from the RHEV-M management console, for example, KVM hyperisors from Red Hat or SUSE. Important: The RHEVM ID or the HYPERVISOR_ID is the unique ID that distinguishes connection A from connection B. These IDs are supplied during configuration. 82 IBM Monitoring: Installation and Setup Guide

89 Procedure You can use one of the following types of configuration procedure to configure the agent: RHEVM: Running the script by responding to prompts 1. Enter:./linux_km-agent.sh config RHEVM_INSTANCE_NAME where RHEVM_INSTANCE_NAME is the name that you want to gie to the instance. 2. When prompted to Edit Monitoring Agent for Linux_KVM settings, enter 1 to continue. 3. When prompted to Edit Data Proider settings, enter 1 to continue. 4. When prompted for Maximum Number Of Data Proider Log Files, press Enter to accept the default alue (10) or to specify a numeric alue. 5. When prompted for Maximum Size in KB of Each Data Proider Log, press Enter to accept the default alue (5190) or to specify a numeric alue. 6. When prompted for Leel of Detail in Data Proider Log, press Enter to accept the default alue (4) or to specify one of the following numeric options; [ 1=Off, 2=Seere, 3=Warning, 4=Info, 5=Fine, 6=Finer, 7=Finest, 8=All ]. 7. When prompted to Edit 'Hyperisor' settings, enter 2 to continue. 8. When prompted to Edit 'Hyperisor' settings, enter 5(Next) to continue, as you are not configuring a hyperisor connection. 9. When prompted to Edit 'RHEVM Connection Details' settings, enter 1 (Yes) to continue. 10. When prompted to Edit 'RHEVM Connection Details' settings, enter 1 (Add) to continue. 11. When prompted for RHEVM ID, enter the ID alue. 12. When prompted for Host, specify the host name of the RHEVM serer. 13. When prompted for User, specify the user name to connect to the RHEVM serer. 14. When prompted for Password, enter the password for the user. 15. When prompted for re-typing password, enter the password alue again. 16. When prompted for Port, specify the port number. 17. When prompted for Domain, enter the user domain name. 18. When prompted for KeyStorePath, specify the path of the local keystore file that has the RHEVM serer security certificate that is imported already. 19. When prompted to Edit 'RHEVM Connection Details' settings, enter 5 to select default option (5), to exit. 20. To start the agent, enter./linux_km-agent.sh startrhevm_instance_name. Hyperisor: Running the script by responding to prompts 1. Enter:./linux_km-agent.sh config HYPERVISOR_INSTANCE_NAME where HYPERVISOR_INSTANCE_NAME is the name you want to gie to the instance. 2. When prompted to Edit Monitoring Agent for Linux_KVM settings, enter 1 to continue. 3. When prompted to Edit Data Proider settings, enter 1 to continue. 4. When prompted for Maximum Number Of Data Proider Log Files, press Enter to accept the default alue (10) or to specify a numeric alue. 5. When prompted for Maximum Size in KB of Each Data Proider Log, press Enter to accept the default alue (5190) or to specify a numeric alue. Chapter 6. Configuring your agents 83

90 6. When prompted for Leel of Detail in Data Proider Log, press Enter to accept the default alue (4) or to specify one of the following numeric options; [ 1=Off, 2=Seere, 3=Warning, 4=Info, 5=Fine, 6=Finer, 7=Finest, 8=All ]. 7. When prompted to Edit 'Hyperisor' settings, enter 1 (Yes) to continue. 8. When prompted to Edit 'Hyperisor' settings, enter 1 (Add) to continue. 9. When prompted for Hyperisor ID, enter the ID alue. 10. When prompted for Host, specify the host name of the KVM host. 11. When prompted for User, specify the user name. 12. When prompted for Remote Transport, enter 1 for default alue (SSH), or select one of the following alues; 2=TLS, 3-TCP (Unencrypted-- not recommended for production use). 13. When prompted for Port, specify the port number for the SSH and TLS ports for the transport protocol. 14. When prompted for Connection Instance Type, enter one of the following alues; 1 for default alue system, or 2 for session. Note: After you configure the hyperisor connection, you hae the option to add, edit, delete connections or to exit completely. 15. When prompted for Edit 'Hyperisor' settings, enter 5 to select default option (5) to exit, or one of the following alues; 1=Add, 2=Edit, 3=Del, or 4=Next When prompted to Edit 'RHEVM Connection Details' settings, enter 2 to exit. 17. To start the agent, enter: install_dir/bin/linux_km-agent.sh start HYPERVISOR_INSTANCE_NAME. Configuring the Microsoft Exchange Serer agent You must configure the Monitoring Agent for Microsoft Exchange Serer to monitor the aailability and performance of Exchange Serers. You can monitor multiple serers from the Performance Management console by using multiple agent instances. Before you begin Before you configure the agent, ensure that you complete the following tasks: Creating users on page 85 Assigning administrator rights to the Exchange Serer user on page 88 Making the Exchange Serer user a local administrator on page 90 Configuring the Exchange Serer for reachability on page 91 Configuring the agent to run under the domain user on page 92 About this task To configure the agent locally, see Configuring the agent locally on page 93. To configure the agent by using the silent response file, see Configuring the agent by using the silent response file on page IBM Monitoring: Installation and Setup Guide

91 Creating users You can create a user for the agent on the Exchange Serer manually or by running the New User utility. You must create the user on each Exchange Serer that you want to monitor. Before you begin Install the Microsoft Exchange Serer agent. To create a user, you must be a domain administrator with full administrator rights on the Microsoft Exchange Serer. About this task Use one of the following procedures to create users: Creating users on Exchange Serer 2007 and 2010 Creating users on Exchange Serer 2013 Creating users by running the New User utility Creating users on Exchange Serer 2007 and 2010 You must create a user for the agent on Exchange Serer 2007 and 2010 so that the agent can communicate and authenticate with the Exchange Serer that you want to monitor. Procedure To create a user, complete the following steps: 1. Click Start > Programs > Microsoft Exchange Serer 2007 > Exchange Management Console. The Exchange Management Console window opens. 2. In the Console tree, click Mailbox in Recipient Configuration. 3. In the Action pane, click New Mailbox. The New Mailbox wizard opens. 4. On the Introduction page, click User Mailbox. 5. On the User Type page, click New User. 6. On the User Information page, specify the following information: Organizational unit By default, the users container in the Actie Directory is displayed. Click Browse to change the default organizational unit. First name Type the first name of the user. Initials Type the initials of the user. Last name Type the last name of the user. Name By default, the user's first name, initials, and last name are displayed in this field. You can modify the name. User logon name (User Principal Name) Type the name that the user must use to log on to the mailbox. User logon name (pre-windows 2000, or earlier) Type the user name that is compatible with Microsoft Windows 2000 Serer, or earlier. Chapter 6. Configuring your agents 85

92 Password Type the password that the user must use to log on to the mailbox. Confirm password Retype the password that you entered in the Password field. User must change password at next logon Select this check box if you want the user to reset the password. 7. On the Mailbox Settings page, specify the following information: Alias By default, the alue for this field is identical to the alue that you specified in the User logon name (User Principal Name) field. Mailbox database Click Browse to open the Select Mailbox Database window. Select the mailbox database that you want to use and click OK. Managed folder mailbox policy Select this check box to specify a messaging records management (MRM) policy. Click Browse to select the MRM mailbox policy that you want to associate with this mailbox. Exchange ActieSync mailbox policy Select this check box to specify an Exchange ActieSync mailbox policy. Click Browse to select the Exchange ActieSync mailbox policy that you want to associate with this mailbox. 8. On the New Mailbox page, reiew the configuration summary. Click New to create a mailbox. On the Completion page, the Summary section shows whether the mailbox was created. 9. Click Finish. What to do next Assign administrator rights to the Exchange user that you created. Creating users on Exchange Serer 2013 You must create a user for the agent on Exchange Serer 2013 so that the agent can communicate and authenticate with the Exchange Serer that you want to monitor. Procedure To create a user on Exchange Serer 2013, complete the following steps: 1. Log in to the Exchange Admin Center with administrator credentials. 2. On the Exchange admin center, click recipients on the upper-left corner of the page, and then click mailboxes in the right pane. 3. Click the down arrow next to the plus sign (+) that is located below the mailboxes option, and then click User mailbox. 4. On the new user mailbox page, click New user, and specify alues for the other fields. 5. Click Sae. What to do next Assign administrator rights to the Exchange user that you created. 86 IBM Monitoring: Installation and Setup Guide

93 Creating users by running the New User utility You can run the New User utility to create users on Exchange Serer 2007, or later. The user that is created by running this utility has all the required permissions to run the agent. This utility is installed when you install the agent. Before you begin Ensure that the agent is installed. To run the New User utility, you must be a domain administrator with full administrator rights on the Exchange Serer. About this task When you run this utility, the user is created in the Users group of the Actie Directory, and has the following permissions: On Exchange Serer 2007: Local administrator Remote desktop user Exchange recipient administrator Exchange iew-only administrator On Exchange Serer 2010, or later: Local administrator Remote desktop user Recipient management Organization management Procedure To run the New User utility, complete the following steps: 1. Double-click the kexnewuser.exe file that is aailable at the following location: install_dir\tmaitm6_x64 where install_dir is the path where the agent is installed. 2. In the New User window, complete the following steps: a. Enter the first name and the last name of the user in the appropriate fields. Restriction: The length of the first and the last name must not exceed 28 characters. b. In the User Logon Name field, enter the name that the user must type wheneer the user logs in. Restriction: The length of the user logon name must not exceed 256 characters. c. In the Password field, enter your password. d. In the Confirm Password field, enter the password again. e. Select User Must Change Password at Next Logon if you want the specified password to be reset the next time when the user logs on. f. Click Next. The configuration alues that you specify are alidated, and error messages are displayed for incorrect alues. 3. From the list of mailbox databases, select the required mailbox database, and click Next. A summary of configuration alues is displayed. Chapter 6. Configuring your agents 87

94 4. Click Finish. Results The settings are saed, and the user is created. Assigning administrator rights to the Exchange Serer user The user that you created for the Microsoft Exchange Serer agent must be a domain administrator with full administrator rights on Microsoft Exchange Serer. The administrator rights are required to access the Microsoft Exchange Serer components. Before you begin Create an Exchange Serer user who has the mailbox on the Exchange Serer that is being monitored. About this task Use one of the following procedures to assign administrator rights to the user: Assigning administrator rights on Exchange Serer 2007 Assigning administrator rights on Exchange Serer 2010 Assigning administrator rights on Exchange Serer 2010 Assigning administrator rights on Exchange Serer 2007 You must assign Exchange Recipient Administrator rights to the user on Exchange Serer Procedure To assign Exchange Recipient Administrator rights to the user on Exchange Serer 2007, complete the following steps: 1. Click Start > Programs > Microsoft Exchange Serer 2007 > Exchange Management Console. The Exchange Management Console window opens. 2. In the Console tree, click Organization Configuration. 3. In the Action pane, click Add Exchange Administrator. 4. On the Add Exchange Administrator page, click Browse. Select the new user that you created, and then select Exchange Recipient Administrator role. 5. Click Add. 6. On the Completion page, click Finish. What to do next Make the user a local administrator of the computer where the Exchange Serer is installed. Assigning administrator rights on Exchange Serer 2010 You must proide Exchange Recipient Management rights to the user on Exchange Serer IBM Monitoring: Installation and Setup Guide

95 Procedure To assign Exchange Recipient Management rights to the user on Exchange Serer 2010, complete the following steps: 1. Click Start > Programs > Microsoft Exchange Serer 2010 > Exchange Management Console. The Exchange Management Console window opens. 2. In the Console tree, click Toolbox. 3. In the Work pane, double-click the Role Based Access Control (RBAC) User Editor tool. The Exchange Control Panel window opens. 4. Enter the user credentials for the account with permissions to open the user editor in the Exchange Control Panel. Click Sign in. 5. Click the Administrator Roles tab. 6. Select the Recipient Management role group, and then click Details. 7. In the Members area, click Add. 8. Select the user that you want to add to the role group, and then click OK. 9. Click Sae to sae the changes to the role group. What to do next Make the user a local administrator of the computer where the Exchange Serer is installed. Assigning administrator rights on Exchange Serer 2013 You must proide Exchange Recipient Management rights to the user on Exchange Serer Procedure To assign Exchange Recipient Management rights to the user on Exchange Serer 2013, complete the following steps: 1. Log in to the Exchange Admin Center with administrator credentials. 2. Click Mails > Options > Manage My Organization. 3. In the left naigation pane, click Roles & Auditing. 4. In the right pane, double-click Recipient Management. 5. On the Recipient Management page, click Add. 6. From the list of users, select the user that you want to add to the group, and click OK. 7. Click Sae. Results The user is added to the Recipient Management group. All the members of the Recipient Management group hae administrator rights. What to do next Make the user a local administrator of the computer where the Exchange Serer is installed. Chapter 6. Configuring your agents 89

96 Making the Exchange Serer user a local administrator To access the Exchange Serer data, the user that you created for the Microsoft Exchange Serer agent must be a local administrator of the computer where the Exchange Serer is installed. Before you begin Create an Exchange Serer user. About this task Use one of the following procedures to make the user a local administrator: Making the user a local administrator on Windows 2003 computer Making the user a local administrator on Windows 2008 computer Making the user a local administrator on Windows 2012 computer Making the user a local administrator on Windows 2003 computer You must make the user that you created for the Exchange Serer a local administrator of the computer that runs on the Windows 2003 operating system, and where the Exchange Serer is installed. Procedure To make the user a local administrator on the computer that runs on the Windows 2003 operating system, complete the following steps: 1. Right-click My Computer on the computer desktop and click Manage. 2. Expand Local Users and Groups. 3. Click Groups. 4. Double-click Administrators to display the Administrators Properties window. 5. Click Add. 6. Select Entire Directory from the Look in list. 7. Select the name of the user that you created and click Add. 8. Click OK. 9. Click OK. Making the user a local administrator on Windows 2008 computer You must make the user that you created for the Exchange Serer a local administrator of the computer that runs on the Windows Serer 2008 operating system, and where the Exchange Serer is installed. Procedure To make the user a local administrator on the computer that runs on the Windows Serer 2008 operating system, complete the following steps: 1. Click Start > Administratie Tools > Serer Manager. 2. In the left pane, expand Configuration. 3. Double-click Local Users and Groups. 4. Click Groups. 90 IBM Monitoring: Installation and Setup Guide

97 5. Right-click the group to which you want to add the user account, and then click Add to Group. 6. Click Add and type the name of the user account. 7. Click Check Names and then click OK. Making the user a local administrator on Windows 2012 computer You must make the user that you created for the Exchange Serer a local administrator of the computer that runs on the Windows Serer 2012 operating system and where the Exchange Serer is installed. Procedure To make the user a local administrator on the computer that runs on the Windows Serer 2012 system, complete the following steps: 1. Click Start > Serer Manager. 2. On the upper-right corner of the Serer Manager dashboard page, click Tools > Computer Management. 3. In the left naigation pane of the Computer Management page, expand Local Users and Groups, and then click Users. 4. From the users list in the right pane, right-click the user to which you want to assign administrator rights, and click Properties. 5. Click the Member Of tab, and click Add. 6. On the Select Group page, type Administrators, and then click OK. 7. Click Apply and OK. Configuring the Exchange Serer for reachability To erify reachability, the Microsoft Exchange Serer agent sends an message to the serer, and measures the amount of time to receie an automated response. Before you start the agent, you must configure the Exchange Serer to automatically respond to messages. Before you begin Before you configure the Exchange Serer, ensure that: A mailbox is created for the user on the Exchange Serer that you want to monitor. The user that you created for the agent is a domain user. The serers in your Microsoft Exchange organization are configured for mail flow between serers. Procedure Complete the following steps for each Exchange Serer for which you want to erify reachability: 1. Log in to Microsoft Outlook by specifying credentials of the user that you created. 2. Click Next on the Startup window. 3. Select Yes and click Next. 4. In the Microsoft Exchange Serer field, type the name of the Exchange Serer. 5. In the Mailbox field, type the name of the user that you created. Chapter 6. Configuring your agents 91

98 6. Click Finish. 7. Click OK. 8. Click Tools > Rules and Alerts > New Rule. 9. Select Start from a blank rule. 10. Select Check messages when they arrie and click Next. 11. Select the following options: Where my name is in the To: box With specific words in the subject or body 12. Under Step 2 in the window, click Specific words. 13. In the Specify words or phrases to search for in the subject or body field, type AVAILABILITY CHECK. 14. Click Add. 15. Click OK and then click Next. 16. Select Hae the serer reply using a specific message and click a specific message. 17. In the message editor, type the following text in the subject field of the message: CHECK RECEIVED: MAILBOX AVAILABLE. 18. Close the message editor and click Yes to sae these changes. 19. Click Next. 20. When you are asked about exceptions, do not specify any restrictions. 21. Click Next. 22. Click Finish and then click OK. What to do next Configure the Microsoft Exchange Serer agent. Configuring the agent to run under the domain user By default, the Microsoft Exchange Serer agent is configured to run under the local user. The agent must be run under the domain user that you created. Before you begin Ensure that: The user that you created is a domain user with local administrator rights. The user has administrator rights on the serer where the agent is installed. About this task When the agent is run under the domain user, the agent can monitor all the components of the Exchange Serer. Procedure To change the user under which the agent runs, complete the following steps: 1. Run the following command to erify which user ID is being used for starting the agent. install_dir\installitm\kincinfo.exe r 2. If the monitoring agent was started with a user ID that does not belong to the Administrator group, stop the agent. 92 IBM Monitoring: Installation and Setup Guide

99 3. Open the Manage Monitoring Serices window. 4. Right-click the agent instance, and click Change Startup. 5. Specify the fully qualified user ID as <Domain\Userid>, and then specify the password. 6. Start the monitoring agent. Configuring the agent locally You can configure the agent locally by using the Manage Monitoring Serices window. Procedure To configure the agent locally, complete the following steps: 1. Click Start > All Programs > IBM Tioli Monitoring. 2. Click Manage Monitoring Serices. 3. In the Manage Monitoring Serices window, right-click Monitoring Agent for Microsoft Exchange Serer, and then click Reconfigure. 4. In the Monitoring Agent for Microsoft Exchange Serer: Agent Adanced Configuration window, click OK. 5. In the Agent Configuration window, complete the following steps: a. Click the Exchange Serer Properties tab, and specify alues for the configuration parameters. When you click OK, the specified alues are alidated. b. Click the Exchange Serices Monitoring tab, and specify alues for the configuration parameters. When you click OK, the specified alues are alidated. c. Click the Adanced Configuration Properties tab, and specify alues for the configuration parameters. When you click OK, the specified alues are alidated. For information about the configuration parameters in each tab of the Agent Configuration window, see the following topics: Configuration parameters for the Exchange Serer properties Configuration parameters for Exchange Serices on page 94 Configuration parameters for reachability on page 95 For information about the alidation of configuration alues, see Validation of configuration alues on page Recycle the agent. Configuration parameters for the Exchange Serer properties In the Exchange Serer Properties tab of the Agent Configuration window, you can configure the Exchange Serer properties, such as serer name, domain name, and user name. Table 10 on page 94 contains detailed descriptions of the configuration settings in the Exchange Serer Properties tab. Chapter 6. Configuring your agents 93

100 Table 10. Names and descriptions of configuration settings in the Exchange Serer Properties tab Parameter name Exchange Serer Name Exchange Domain Name Exchange User Name Exchange User Password Confirm Password Exchange MAPI Profile Name Configuration in cluster Cluster Serer Name Exchange Subsystem ID Exchange Agent Historical Data Directory Description The name of the Exchange Serer. During installation of the Exchange Serer, the default Exchange Serer name is the Windows Serer host name. If you change the default Exchange Serer name, you must use the changed name when you configure the Exchange Serer agent. Remember: In clustered and distributed enironments, specify the Mailbox Serer name for Exchange Serer The name of the domain where the Exchange Serer is installed. The name of the user who is configured to access the Exchange Serer. Remember: The user must hae a mailbox on the same Exchange Serer. The password of the user who is configured to access the Exchange Serer. The same password that you specified for the Exchange Serer user. MAPI profiles are the primary configuration settings that are required for accessing the Exchange Serer. This field is disabled if you are using a 64-bit Microsoft Exchange Serer agent to monitor Exchange Serer 2007, or later. Select this check box if you want to configure the Microsoft Exchange Serer agent in a cluster enironment. The name of the Cluster Serer. This field is enabled when you select the Configuration in cluster check box. The name of the Cluster Serer node. This field is enabled when you select the Configuration in cluster check box. The location on the disk where the historical data is stored. This field is enabled when you select the Configuration in cluster check box. Mandatory field Yes Important: Do not specify a alue if the agent is installed on a serer that has a single copy cluster with more than two nodes. Yes Yes Yes Yes No Not applicable Yes, if the field is enabled. Yes, if the field is enabled. Yes, if the field is enabled. Examples If the Exchange Serer name is popcorn, enter popcorn in the Exchange Serer Name field. If the Exchange Serer is in the LAB.XYZ.com domain, enter the name that is at the left of the first dot, for example, LAB. SCCCluster node1 c:\history Configuration parameters for Exchange Serices In the Exchange Serices Monitoring tab of the Agent Configuration window, you can select the Exchange serices to know the Exchange Serer status. 94 IBM Monitoring: Installation and Setup Guide

101 Table 11 contains detailed descriptions of the configuration settings in the Exchange Serices Monitoring tab. Table 11. Names and descriptions of configuration settings in the Exchange Serices Monitoring tab Parameter name Exchange Serices Serices Configured for Serer Status Description Select the Exchange serices that the Microsoft Exchange Serer agent must monitor from the list of aailable Exchange serices. Remember: The list of aailable serices changes according to the Exchange Serer ersion and the roles that are installed. The selected serices are displayed in this list. These serices determine the status of the Exchange Serer. Mandatory field Not applicable Not applicable Configuration parameters for reachability In the Adanced Configuration Properties tab of the Agent Configuration window, you can configure the parameters that are related to reachability, such as target address and reachability interal. Table 12 contains detailed descriptions of the configuration settings in the Adanced Configuration Properties tab. Table 12. Names and descriptions of configuration settings in the Adanced Configuration Properties tab Parameter name Enable Mailbox Reachability Monitoring Target Address Transmission Interal (seconds) Transmission Timeout (seconds) Enable Mailbox Detail Monitoring Mailbox Detail Collection Start time Mailbox Detail Collection Interal (seconds) Eent Logs Collection Time (minutes) Maximum Number of Eents Description Select this check box if you want the agent to capture the reachability metrics data. An address to erify reachability. Separate multiple addresses with a semicolon (;). Restriction: The total number of characters in this field must not exceed The waiting time (in seconds) of the Exchange Serer agent between sending s. The interal (in seconds) for which the agent waits for a response to the that was sent to test whether the Mailbox Serer is reachable. Select this check box to collect data for the mailbox detail metrics. The time (in hh:mm:ss format) when mailbox detail metrics are collected. The interal (in seconds) between collections of mailbox detail metrics. The duration (in minutes) for which the agent collects eent records. The maximum count up to which eent records are collected. The collection of eent records stops when the number of collected eent records exceeds the maximum count. Mandatory field Not applicable Yes, if this field is enabled. Yes, if this field is enabled. No Not applicable No No No No Chapter 6. Configuring your agents 95

102 Table 12. Names and descriptions of configuration settings in the Adanced Configuration Properties tab (continued) Parameter name Collection Interal (seconds) Exchange Topology Interal (seconds) Message Tracking Collection Interal (hours) Description The interal (in seconds) between the agent cycles. The interal (in seconds) between collections of topology detail information. The interal (in hours) for which the message tracking logs are collected. Restriction: The interal alue must be in the range If you specify the interal alue that is greater than 12, the alue is saed as 12. If you enter an inalid alue that contains alphabets or special characters, the alue is saed as 0, which indicates that the message tracking collection is disabled. This field is disabled if any of the following conditions is true: The Mailbox Serer role or the Hub Transport role is not installed on the Exchange Serer. The message tracking feature is disabled on the Exchange Serer. Mandatory field No No No Validation of configuration alues The alues that you specify while configuring the agent locally are alidated. The alidation ensures that the alues are specified for all mandatory parameters and certain conditions are met, such as local administrator rights for the user. Table 13 shows the alidation tests that are performed on the specified configuration alues. Table 13. Validation tests Validation test Verifies whether Exchange Serer Name Exchange Serer Rights Local Admin Agent Serice Logon The Mailbox Serer name of the user matches the specified Exchange Serer name. The user has the required Exchange Serer rights. On Exchange Serer 2007, the user must hae recipient administrator rights, and on Exchange Serer 2010, or later, the user must hae recipient management rights. The user has local administrator rights. The agent serice is configured to run with the specified user account. If one or more alidation tests fail, an error message is generated. You must specify alues for all mandatory parameters. Otherwise, you cannot sae the configured alues. Configuring the agent by using the silent response file The silent response file contains the agent configuration parameters with default alues defined for some parameters. You can edit the silent response file to specify different alues for the configuration parameters. 96 IBM Monitoring: Installation and Setup Guide

103 About this task You run the configuration script to update the agent configuration settings. Before you run the configuration script, ensure that the silent response file is updated with the required configuration alues. Procedure To configure the agent, complete the following steps: 1. Open the msex_silent_config.txt file that is located at install_dir\samples, and specify alues for all mandatory parameters. You can also modify the default alues of other parameters. 2. Open the command prompt, and enter the following command: install_dir\bin\msexch-agent.bat config install_dir\samples\ msex_silent_config.txt Configuring the Microsoft Hyper-V Serer agent When you install the Monitoring Agent for Microsoft Hyper-V Serer, the agent is automatically configured with the default configuration settings. Use the silent response file to modify the default configuration settings. Before you begin If you want to modify the default configuration parameters, edit the response file. To iew the irtual machine data on the Virtual Machine detail page, ensure that you install the integration component and the OS agent on each irtual machine. For irtual machines that run on the Linux system, ensure that you complete the following tasks: Upgrade the Linux system. Install the updated hyperkpd or hyper-daemons rpm package on the irtual machine. Procedure To configure the agent, complete the following steps: 1. Open the HV_Silent_Config.txt file that is at install_dir\samples, and specify alues for all mandatory parameters. You can also modify the default alues of other parameters. 2. Open the command prompt, and enter the following command: install_dir\bin\mshyper-agent.bat config install_dir\samples\ HV_Silent_Config.txt The response file contains the following parameters: KHV_DIRECTOR_PORT KHV_DIRECTOR_SERVER Remember: The agent configuration is organized into the following groups: IBM Systems Director configuration (IBM_DIRECTOR_CONFIGURATION) The configuration elements that are defined in this group are always present in the agent's configuration. This group defines information that applies to the entire agent. Chapter 6. Configuring your agents 97

104 IBM Systems Director Serer Port Number (KHV_DIRECTOR_PORT) The port number for the IBM Systems Director Serer. The default alue is none. IBM Systems Director Serer Host Name (KHV_DIRECTOR_SERVER) Host name or IP address of the IBM Systems Director Serer that is managing the enironment. The default alue is none. Configuring the Microsoft IIS agent When you install the Monitoring Agent for Microsoft Internet Information Serices, the agent is automatically configured with the default configuration settings. Use the silent response file to modify the default configuration settings. Before you begin If you want to modify the default configuration parameters, edit the response file. Procedure To configure the Microsoft IIS agent, complete the following steps: 1. Open the command prompt. 2. Change the path to the directory that contains the msiis-agent.bat file. 3. Enter the msiis-agent.bat config absolute path to the response file command. The response file contains the following parameters: [KQ7_AGENT_CONFIG] KQ7_SITE_LOG_FILE C:\inetpub\logs\LogFiles KQ7_HTTP_ERROR_LOG_FILE C:\WINDOWS\system32\LogFiles\HTTPERR Remember: The agent configuration is organized into the following groups: HTTP Error Log Configuration (HTTP_ERROR_LOG) This group contains the configuration parameters that are related to the HTTP error log file (KQ7_HTTP_ERROR_LOG_FILE). An administrator can specify a location to sae the log file. By default, this log file is saed at C:\WINDOWS\system32\LogFiles\HTTPERR. Site Log Configuration (SITE_LOG) This group contains the configuration parameters that are related to the site log file (KQ7_SITE_LOG_FILE). An administrator can specify a location to sae the log file. By default, this log file is saed at C:\inetpub\logs\LogFiles. Configuring the Microsoft.NET agent To collect transactions tracking and diagnostics data, you must register the data collector and complete some adanced tasks for the data collector. To collect resource monitoring data, no specific configuration is required. Before you begin To iew data in the Slow Requests - Top 10 group widget, ensure that you complete the following tasks on the IIS Serer: 98 IBM Monitoring: Installation and Setup Guide

105 Enable logging for websites. Select all W3C fields to include in log files. Retain the default path where log files are saed. Important: If you schedule a daily or hourly frequency for creating log files, the number of log files increases oer time. This increase in the number of log files increases the total handle count and priate bytes that affect the agent performance. To improe the agent performance, ensure that you regularly back up the log files and delete them from the default log file path at least once a week. To collect diagnostics data, you might need to increase the maximum heap size of the data collector: 1. From a command prompt, enter cd install_dir\tmaitm6_x64 where install_dir is the installation directory of the Microsoft.NET agent. 2. Open the rundotnetagent.bat script in a text editor. 3. Increase the alue of the -Xmx parameter in the following line. %JAVA_HOME%\bin\jaa" -classpath %CLASSPATH% -Dkqe.cache.interal=%KQE_CACHE_INTERVAL% -Xmx384m -Djlog.propertyFileDir.CYN=%KQE_LOG_CONFIG% -Dattributegroup.def.jar=%ATTRIBUTE_DEF% -Ddc.runtime.dir=%DC_RUNTIME_DIR% com.ibm.tioli.monitoring.annotation.cpci.commonagentcustomclient > %STDOUT_LOG% 2>&1 Important: The default alue of -Xmx384m is proided for an enironment where only request data is collected. If you want to collect all types of data, increase the alue to -Xmx1024m or higher. About this task The Microsoft.NET agent consists of two components; the monitoring agent and the data collector. The monitoring agent collects data of Microsoft.NET Framework resources directly. The data collector gathers transaction tracking and diagnostics data and passes the data to the monitoring agent. The diagnostics data is processed by the monitoring agent directly. The transaction tracking data is processed within the Transaction Framework Extension, which is a subcomponent of the monitoring agent. The data collector consists of the following four modules: httpmodule Performs ASP.NET transaction monitoring. The http module also collects request data for diagnostics. profiler Performs ADO.NET transaction monitoring. The profiler also collects method, stack trace, and request context data for diagnostics. isapi Performs Microsoft IIS Serer transaction monitoring. soap Performs ASMX or WCF serice transaction monitoring. You must register the data collector to collect transaction tracking and diagnostics data. Procedure 1. Enter the following command as an administrator: Chapter 6. Configuring your agents 99

106 cd install_dir\qe\bin configdc.exe registerdc [ all isapi isapi32 profiler httpmodule soap ] The command configdc.exe registerdc registers the http module only. Tip: Use isapi32 to filter 32-bit applications on a 64-bit Microsoft IIS Serer. If you register the http module only, ADO calls to databases are not aailable in the topology iew on the Performance Management console. No method trace, stack trace, or request context data is displayed for the agent in the diagnostic dashboards. 2. Restart the agent. From the install_dir\bin directory, enter the following commands: dotnet-agent.bat stop dotnet-agent.bat start 3. Restart the.net application. Microsoft.NET agent: Adanced configuration You can modify the configuration of the data collector using the configdc command. Tip: If you want to iew the configuration alues of the data collector, naigate to the install_dir\qe\config directory where install_dir is the installation directory of the Microsoft.NET agent. Open the dotnetdcconfig.properties file in a text editor. Registering and unregistering the data collector If you want to stop monitoring.net applications, unregister the data collector. Register the data collector again to restart monitoring. You must also unregister the data collector before you uninstall the agent. Before you begin If you plan to collect diagnostics data, increase the maximum heap size of the data collector, if required. 1. From a command prompt, enter cd install_dir\tmaitm6_x64 where install_dir is the installation directory of the Microsoft.NET agent. 2. Open the rundotnetagent.bat script in a text editor. 3. Increase the alue of the -Xmx parameter in the following line. Important: The default alue of -Xmx384m is proided for an enironment where only request data is collected. If you want to collect all types of data, increase the alue to -Xmx1024m or higher. %JAVA_HOME%\bin\jaa" -classpath %CLASSPATH% -Dkqe.cache.interal=%KQE_CACHE_INTERVAL% -Xmx384m -Djlog.propertyFileDir.CYN=%KQE_LOG_CONFIG% -Dattributegroup.def.jar=%ATTRIBUTE_DEF% -Ddc.runtime.dir=%DC_RUNTIME_DIR% com.ibm.tioli.monitoring.annotation.cpci.commonagentcustomclient > %STDOUT_LOG% 2>&1 About this task You can register and unregister all modules or indiidual modules of the data collector. 100 IBM Monitoring: Installation and Setup Guide

107 The data collector consists of the following four modules: httpmodule Performs ASP.NET transaction monitoring. The http module also collects request data for diagnostics. profiler Performs ADO.NET transaction monitoring. The profiler also collects method, stack trace, and request context data for diagnostics. isapi soap Performs Microsoft IIS Serer transaction monitoring. Performs ASMX or WCF serice transaction monitoring. Procedure To register the data collector, complete the following steps: 1. Enter the following command as an administrator: cd install_dir\qe\bin configdc.exe registerdc [-f] [ all isapi isapi32 profiler httpmodule soap ] Where [-f] oerrides any existing.net profiler. The command configdc.exe registerdc registers the http module only. Tip: Use isapi32 to filter 32-bit applications on a 64-bit Microsoft IIS Serer. If you register the http module only, ADO calls to databases are not aailable in the topology iew on the Performance Management console. No method trace, stack trace, or request context data is displayed for the agent in the diagnostic dashboards. 2. Restart the agent. From the install_dir\bin directory, enter the following commands: dotnet-agent.bat stop dotnet-agent.bat start 3. Restart the.net application. To unregister the data collector, complete the following steps: 1. Enter the following command as an administrator: cd install_dir\qe\bin unconfigdc.exe unregisterdc [ all isapi profiler httpmodule soap ] The command configdc.exe unregisterdc unregisters all modules of the data collector. 2. Restart the.net application. Selecting ADO.NET interfaces for monitoring You can specify the ADO.NET client interfaces that you want to enable for transaction tracking. Before you begin You might want to iew the ADO.NET interfaces that are supported by.net Data Collector. For information about supported ADO.NET interfaces, see Functions of namespaces supported by the data collector. To iew the configuration alues of the.net Data Collector, see the dotnetdcconfig.properties file in the install_dir\qe\config directory, where install_dir is the installation directory of the Microsoft.NET agent. Chapter 6. Configuring your agents 101

108 About this task By default, all supported ADO.NET interfaces are enabled for transaction tracking during the installation of the agent. To select the interfaces that must be monitored by the data collector, enable or disable monitoring for specific interfaces. If you disable monitoring of an interface, the settings of any associated application domain filter remain in the data collector configuration file. The filter is retained when the interface is enabled again. For more information about using the configdc command, see Using the configdc command on page 104. Procedure To enable monitoring of an ADO.NET interface, complete these steps: 1. From the install_dir\qe\bin directory, run the configdc enablemonitor command: configdc enablemonitor all adsi db2 ldap odbc oledb oracle sql http web [-appdomain appdomain filter list] 2. If your configuration changes are complete, actiate the configuration changes. See Actiating the configuration on page 104 for more information. To disable monitoring of an ADO.NET interface, complete these steps: 1. From the install_dir\qe\bin directory, run the configdc disablemonitor command: configdc disablemonitor all adsi db2 ldap odbc oledb oracle sql http web 2. If your configuration changes are complete, actiate the configuration changes. See Actiating the configuration on page 104 for more information. Configuring the collection of diagnostics data The collection of diagnostics data is enabled in the data collector configuration by default. You can limit the amount of diagnostic data that is collected by the data collector using the configdc command. Procedure 1. To set the leel of trace data that is collected, enter: cd install_dir\qe\bin configdc deepdiedc -traceleel trace_leel Where install_dir The installation directory of the Microsoft.NET agent. trace_leel The diagnostics trace leel of the.net Data Collector. Valid alues are 0, 1, 2, and 3, where: 0 The collection of diagnostics data is disabled. 1 The collection diagnostics data is enabled. The HTTP module collects request summary and request instance data. 2 The collection diagnostics data is enabled. The HTTP module 102 IBM Monitoring: Installation and Setup Guide

109 collects request summary and request instance data. The profiler collects method data and stack trace data. When you configure the data collector initially, leel 2 is set by default. Tip: Setting the trace leel using the configdc.exe deepdiedc -traceleel command, sets the alue of the bci_dc.diagnose.leel parameter in the dotnetdcconfig.properties file. 2. If your configuration changes are complete, actiate the configuration changes. See Actiating the configuration on page 104 for more information. Configuring transaction tracking The interface to the Transaction Framework Extension is configured in the data collector configuration by default. You can modify the interface settings using the configdc command. About this task Procedure 1. From the install_dir\qe\bin directory, run the following command to specify the host name or IP address and port of the Transaction Framework Extension: configdc ttserer -name [host name/ip address] -port [port number] where install_dir is the installation directory of the Microsoft.NET agent. If the Transactions Framework Extension is on the same host, use the local host address ( ). The default port is Actiate the configuration changes. See Actiating the configuration on page 104 for more information. What to do next For information about enabling transaction tracking, see Enabling and disabling Transaction Tracking. Enabling and disabling Transaction Tracking Transaction tracking is enabled in the data collector configuration by default. You can enable and disable Transaction Tracking using the command line. Before you begin The connection to the Transaction Framework Extension must be specified. It is configured in the default configuration. To modify the default configuration, see Configuring transaction tracking. About this task Transaction tracking data is isible in topology iews if topology iews are aailable on the Performance Management console. Procedure To enable Transaction Tracking for a.net Data Collector: 1. Naigate to the install_dir\qe\config directory, where install_dir is the installation directory of the Microsoft.NET agent. 2. Open the dotnetdcconfig.properties.inactie file in a text editor. Chapter 6. Configuring your agents 103

110 3. Set TTDC.enabled=true and set TTAS.enabled=true 4. Actiate the change. Run the following command: install_dir\qe\bin\configdc.exe actiateconfig 5. Restart the.net application for the change to take effect. What to do next To disable Transaction Tracking for a.net Data Collector, repeat the procedure, instead setting TTDC.enabled=false and TTAS.enabled=false in the configuration file. Actiating the configuration Actiate the updated configuration for the changes to take effect. Procedure 1. Naigate to install_dir\qe\bin, where install_dir is the installation directory of the Microsoft.NET agent. 2. Enter configdc actiateconfig What to do next If the Internet Information Serice (IIS) transactions are monitored and the data collector configuration is updated, restart the IIS to actiate the configuration. If ASMX or WCF web serices are monitored and the data collector configuration is updated, complete one of the following steps: Restart the process that hosts the web serice. Unregister the data collector by running the configdc unregisterdc command, and then register it again by running the configdc registerdc command. Configuring logging for the data collector Logging is separately configured for each component of data collector. Performance of data collector might be affected when tracing is enabled. Disable tracing after the required trace logs are gathered. For the.net profiler component, configure logging by using the configdc command. For more information about using the command, see Using the configdc command. The settings for ASMX/WCF trace and operation logging are set in the dotnetdcconfig.properties file in the install_dir\qe\config directory, where install_dir is the installation directory of the Microsoft.NET agent. Using the configdc command You can use the command-line configuration tool of.net Data Collector to perform the configuration tasks, such as registering the data collector, alidating and storing the connectiity information, enabling and disabling trace logging, and so on. Run all commands that are mentioned in Table 14 on page 105 from the install_dir\qe\bin directory, where install_dir is the installation directory of the Microsoft.NET agent. 104 IBM Monitoring: Installation and Setup Guide

111 Table 14. Data collector configuration commands Command syntax Description configdc registerdc [-f][all isapi isapi32 profiler httpmodule soap] configdc unregisterdc [all isapi profiler httpmodule soap] Registers the.net Data Collector. Run this command as an administrator. For more information, see Registering and unregistering the data collector on page 100. Unregisters the.net Data Collector. Run this command as an administrator. configdc ttserer -name name -port port configdc logging [-leel ERROR DEBUG WARNING INFO] [-size #] [-files #] [-tracing on off] configdc enablemonitor [all adsi db2 ldap odbc oledb oracle sql http web] [-appdomain app domain list] For more information, see Registering and unregistering the data collector on page 100. Validates and sets the connectiity information of the Transaction Framework Extension to which the agents sends the tracking data. Enables or disables trace logging for the.net profiler. Sets tracing attributes, for example, the leel of trace detail, the maximum trace log file size, and the maximum number of trace log files. For alid alues, see the dotnetdcconfig.properties file in the install_dir\qe\config directory. The settings for ASMX/WCF trace and operation logging are specified in the dotnetdcconfig.properties file. Enables transaction monitoring of an ADO.NET interface. After installation, all interfaces are enabled for monitoring by default. Use all to enable all the supported ADO.NET interfaces for transaction tracking. Use http to enable interception of supporting APIs for http monitoring. The -appdomain command restricts the ADO.NET interface monitoring to one or more.net application domain names. If you specify more than one application domain name, separate each name with a semicolon (;). Use an asterisk (*) to enable all application domains. All application domains are enabled by default during the installation. When an application domain list is assigned to an ADO.NET interface, the list remains unchanged in the configuration unless it is set to another alue. If an interface is enabled for monitoring without specifying an application domain, the last application domain alue that you specified or that was specified by default for the interface is used. Chapter 6. Configuring your agents 105

112 Table 14. Data collector configuration commands (continued) Command syntax configdc disablemonitor [all adsi db2 ldap odbc oledb oracle sql http web] Description Disables transaction monitoring of an ADO.NET interface. Use all to disable all supported ADO.NET interfaces for transaction tracking. Use http to intercept GetResponse (System.Net) and use web to disable the monitoring of http requests. configdc getconfig [-actie] configdc deepdiedc -traceleel trace_leel Displays the properties file where you can add or remoe.net API calls to be intercepted by the data collector. When the changes are complete, actiate the edited file by using the configdc actiateconfig command. Configures the leel of diagnostics data to be collected by the data collector. For more information, see Configuring the collection of diagnostics data on page 102. configdc actiateconfig Actiates the updated configuration. For information about what to do after you actiate the configuration, see Actiating the configuration on page 104. Configuring the Microsoft SQL Serer agent You must configure the Monitoring Agent for Microsoft SQL Serer so that the agent can collect data from the application that is being monitored. Before you begin You can install and configure the Microsoft SQL Serer agent locally by using the command - line interface. Ensure that the agent is installed on the serer that is being monitored. About this task To configure the agent, complete the following tasks: Granting permissions for SQL Serer databases Selecting the databases for monitoring on page 107 Configuring local enironment ariables on page 108 Granting permissions for SQL Serer databases Before you configure the Microsoft SQL Serer agent, you must grant permissions for the Microsoft SQL Serer databases that you want to monitor. The process of granting permissions to databases is the same for SQL Serer 2005, or later. Before you begin Ensure that you hae the database administrator authorization role to grant permissions. The Microsoft SQL Serer agent uses SQL Serer authentication or Windows authentication to access the SQL Serer. For SQL Serer authentication, the agent uses the configured SQL Serer ID. For Windows authentication, the agent uses the run-as user ID. The SQL Serer ID that the agent uses must hae 106 IBM Monitoring: Installation and Setup Guide

113 public access for each SQL Serer database that you want to monitor. About this task You grant permissions to SQL Serer databases so the agent can access and monitor these databases. For configuring the agent locally, complete this task after you install the agent and before you configure the agent. For configuring the agent remotely, complete this task after you install and configure the agent. Procedure 1. Click Start > Programs > Microsoft SQL Serer 2005 > SQL Serer Management Studio. 2. In the Tree tab, select Logins in the Security folder (Console Root > WindowsName > Security > Logins) 3. Right-click Logins and select New Login. 4. Select the General Folder option and type one of the following options: SQL Serer user ID If you are using SQL Serer authentication. Windows user ID If you are using Windows authentication. 5. Select one of the following authentication methods: SQL Serer Windows 6. In the Password field, type a password if you are using the SQL Serer authentication method. 7. Select the User Mapping option. 8. In the Specify which databases can be accessed by this login area, select the check box corresponding to each database for which you want to grant permissions. 9. Select the Serer Roles option. 10. Click OK to display the Confirm Password window. 11. Retype the password that you typed for the user ID. 12. Click OK to display the new user ID in the Logins list. Selecting the databases for monitoring You can select the database that you want to monitor by using the Configure Database Agents window. Procedure 1. In the Configure Database Agents window, select the database serer that you want to monitor from the Database Serers Aailable list, and moe the serer to the Serer to Monitor list. 2. In the Database Serer Properties window, specify alues for the following fields: Serer Name Database Version Home Directory Error Log File The following fields in the Database Serer Properties window are optional: Chapter 6. Configuring your agents 107

114 Windows Authentication Support Long Lied Database Connections Extended Parms Include Day(s) Frequency Weekly Frequency Monthly Frequency Collection Start Time Table Detail Continuous Collection 3. If you do not select the Windows Authentication field, you must enter your login and password in the Login and Password fields by using only ASCII characters. You can use the Extended Parms field to enable or disable the data collection for the Table Detail data set. 4. To disable data collection, type one of the following options in the Extended Parms field: koqtbld for the Table Detail data set. koqdbd for the Database Detail data set. 5. Click OK. 6. In the Configure Database Agents window, click OK to complete the configuration process. 7. Specify a daily, weekly, or monthly frequency for the collection of the MS SQL Table Detail data set. 8. Select the Table Detail Continuous Collection check box to enable continuous collection of the MS SQL Table Detail data set. If you select the Table Detail Continuous Collection check box, enter a alue in the Interal Between Two Continuous Collection (in minutes) field. Configuring local enironment ariables You can configure local enironment ariables to change the behaior of the Microsoft SQL Serer agent. Procedure 1. In the Manage Monitoring Serices window, from the Actions menu, click Adanced > Edit Variables. 2. In the Tioli Enterprise Monitoring Serer: Oerride Local Variable Settings window, click Add. 3. In the Add Enironment Setting Oerride window, enter the ariable and the corresponding alue. To iew the list of enironment ariables that you can configure, see Local enironment ariables. Local enironment ariables You can change the behaior of the Microsoft SQL Serer agent by configuring the local enironment ariables. Variables for checking SQL Serer serice aailability To check the aailability of the SQL Serer serice, add the following enironment ariables: 108 IBM Monitoring: Installation and Setup Guide

115 COLL_MSSQL_RETRY_INTERVAL: This ariable proides the retry interal in minutes to check the SQL Serer serice status. If the alue is less than or equal to zero, then the ariable takes the default alue of 1 minute. COLL_MSSQL_RETRY_CNT: This ariable proides the number of retries that the SQL Serer agent makes to check whether the SQL Serer serice is started or not. If the SQL Serer serice is not started after the number of retries, then collector stops working. If the alue is less than or equal to zero, then the ariable takes the default alue of infinity. Variables for monitoring the SQL Serer error log file To monitor the MS SQL Error Eent Details data set, add the following enironment ariables: COLL_ERRORLOG_STARTUP_MAX_TIME: This ariable proides the time interal (T) for error collection before the agent startup. The default alue is 0 minutes. This ariable can take the following alues: T=0 The agent starts monitoring the error log file from the time the agent starts or is restarted. The agent does not read the errors that were logged in the error log file before the agent was started. T=1 The agent monitors the error log file according to the following alues that are set for the COLL_ERRORLOG_STARTUP_MAX_EVENT_ROW ariable, which is represented by R: IfR < 0,theagent starts monitoring the error log file from the time the agent starts or is restarted. IfR=1,theagent monitors all the errors that are logged in the error log file. IfR>1andtheagent is installed for the first time, the agent monitors the error log file until R errors are monitored. If R>1and the agent is restarted, the agent monitors all the preiously missed R errors. T>1 The agent monitors all preious errors that were logged up to T minutes from the time that the agent starts or restarts. The agent monitoring also depends on the following alues that you set for the COLL_ERRORLOG_STARTUP_MAX_EVENT_ROW ariable: If R 0, the agent starts monitoring the error log file from the time the agent is started or the agent is restarted. IfR=1,theagent monitors the error log file for all the errors that are logged up to T minutes. IfR>1,theagent does not monitor more than R errors that are logged in last T minutes. COLL_ERRORLOG_STARTUP_MAX_EVENT_ROW: This ariable proides the maximum number of errors that must be processed at agent startup. The default alue is 0. You can assign following alues to this ariable: R=0 The agent starts monitoring the error log file from the time that the agent starts or restarts. The agent does not read errors that were created in the error log file before the agent was started. R=1 The agent monitors the errors that were logged in the last T minutes from the time that the agent starts or restarts. R>1 The agent monitors R errors that are logged in the last T minutes. Chapter 6. Configuring your agents 109

116 COLL_ERRORLOG_MAX_EVENT_ROW: This ariable proides the number of error rows. The default alue is 50. You can assign following alues to this ariable: X=0 The agent does not display the error logs. X>0 The agent displays the X error rows. Variable for query timeout interal To set the query timeout interal for the SQL Serer agent, you must use the QUERY_TIMEOUT ariable. This enironment ariable defines the maximum amount of time (in seconds) that the SQL Serer agent waits to receie a response for a query that is sent to the SQL Serer. The alue for this ariable must be less than 45 seconds. Howeer, if you set the alue for this ariable as 0 seconds, the SQL Serer agent waits indefinitely to receie a response from the SQL Serer. If the SQL Serer agent accesses many locked databases, you must assign the alue to this ariable in the range of seconds. If the query is not processed within the set timeout interal, the SQL Serer agent skips the timed out query and moes to the next query in the queue. The agent does not display data for the query that timed out. Variable for iewing information about enabled jobs To iew the information about enabled jobs in the MS SQL Job Detail data set, use the COLL_JOB_DISABLED enironment ariable. If you set the alue of this ariable as 1, the Microsoft SQL Serer agent does not display information about disabled jobs. If you do not specify this ariable, you can iew information about enabled and disabled jobs. Configuring the agent by using the silent response file You can use the silent response file for configuring the agent. You can also configure multiple instances of the agent by using the silent response file. Before you begin To configure multiple instances of the agent, ensure that the configuration details of all the agent instances are specified in the silent response file. If the configuration details for any of the instances are not defined in the silent response file, the instance is remoed after you run the agent batch script. About this task Run the configuration script to change the configuration settings. You can edit the silent response file before you run the configuration script. Procedure To configure the agent, complete the following steps: 1. Open the mssql_silent_config.txt file that is located at install_dir\samples, and specify alues for all mandatory parameters. You can also modify the default alues of other parameters. 2. Open the command prompt, and enter the following command: install_dir\bin\mssql-agent.bat config install_dir\samples\ mssql_silent_config.txt 110 IBM Monitoring: Installation and Setup Guide

117 Configuring the MongoDB agent The Monitoring Agent for MongoDB requires an instance name. You must create the first instance and start the agent manually. About this task The Managed System Name includes the instance name that you specify, for example, instance_name:host_name:pc, where pc is your two character product code. The Managed System Name is limited to 32 characters. The instance name is limited to 28 characters, minus the length of your host name. For example, if you specify Mongo2 as your instance name, your managed system name is Mongo2:hostname:KJ. Important: If you specify a long instance name, the Managed System name is truncated and the agent code does not display correctly. In a typical enironment, where MongoDB is running as a cluster and there is a single router on the system where you installed the agent, the only configuration information you need to proide is the new instance name. For a typical enironment, configure the agent with the default settings. To change the type, port, or router IP address, configure the agent with customized settings. Procedure To configure the agent with the default settings not responding to prompts, complete the following steps: 1. Enter: install_dir/bin/mongodb-agent.sh config instance_name install_dir/samples/mongodb_silent_config.txt Where instance_name is the name you want to gie to the unique application instance, and install_dir is the installation directory of MongoDB agent. The default installation directory is /opt/ibm/apm/agent. 2. To start the agent, enter: install_dir/bin/mongodb-agent.sh start instance_name To configure the agent by editing the silent response file and running the script with no interaction, complete the following steps: 1. Open install_dir/samples/mongodb_silent_config.txt in a text editor. 2. For TYPE, you can specify whether the systems are a cluster (1), a single replication set (2), or a stand-alone instance (3). By default, the agent monitors a cluster (1). 3. For PORT, to oerride the automatic discoery of a cluster or to monitor a specific replication set, set the port number for the router of a MongoDB cluster or a mongod (primary daemon process) instance of a MongoDB replication set being monitored. If this alue is blank, the agent automatically discoers the appropriate MongoDB process ports. Leaing the port alue empty proides more reliable monitoring if there is only one cluster or replication set on the system. 4. For HOST, you can set the IP address for the MongoDB host system, or leae this parameter blank to hae the installer discoer the default IP address. The host IP address is used to select a particular interface on a system where MongoDB is bound to only one of seeral addresses. Chapter 6. Configuring your agents 111

118 5. Sae and close the mongodb_silent_config.txt file, then enter: install_dir/bin/mongodb-agent.sh config instance_name install_dir/samples/mongodb_silent_config.txt Where instance_name is the name that you want to gie to the instance, and install_dir is the installation directory of MongoDB agent. 6. To start the agent, enter: install_dir/bin/mongodb-agent.sh start instance_name To configure the agent by running the script and responding to prompts, complete the following steps: 1. Enter: install_dir/bin/mongodb-agent.sh config instance_name Where instance_name is the name you want to gie to the instance, and install_dir is the installation directory of MongoDB agent. 2. Respond to the prompts by using the description of the parameters that were proided earlier for reference. 3. To start the agent, enter: install_dir/bin/mongodb-agent.sh start instance_name Configuring the MySQL agent The Monitoring Agent for MySQL requires an instance name and the MySQL serer user credentials. You must create the first instance and start the agent manually. Run the configuration script to create an instance and change any configuration settings. You can edit the MySQL silent response file before you run the script to bypass the prompting and responses that are otherwise required. About this task The managed system name includes the instance name that you specify, for example, instance_name:host_name:pc, where pc is your two character product code. The managed system name is limited to 32 characters. The instance name that you specify is limited to 28 characters, minus the length of your host name. For example, if you specify MySQL2 as your instance name, your managed system name is MySQL2:hostname:SE. Important: If you specify a long instance name, the managed system name is truncated and the agent code does not display correctly. This procedure assumes the default C:\IBM\APM\ installation path. If you installed to a different path, substitute the path in the instructions, and edit the AGENT_HOME parameter in the silent response file for the path where you installed the monitoring agent. Procedure To configure the agent by editing the silent response file and running the script with no interaction, complete the following steps: 1. To configure the agent, open the response file in a text editor: install_dir/samples/mysql_silent_config.txt install_dir\samples\mysql_silent_config.txt Where install_dir is the installation directory of MySQL agent. 112 IBM Monitoring: Installation and Setup Guide

119 2. For JDBC user name, leae it set to root or change to a user with priileges to iew the INFORMATION_SCHEMA tables. 3. For JDBC password, enter the JDBC user password. 4. For JDBC home, leae it at the default, if this path is where Jaa is installed; otherwise, enter the correct path. Default path: /opt/ibm/jaa-x86_64-70/jre C:\IBM\APM\jaa\jaa70_x64\jre 5. For JDBC Jar File, leae it at the default, if this is the path to the MySQL connector for the Jaa jar file; otherwise, enter the correct path. Default path: /usr/share/jaa/mysql-connector-jaa.jar C:\Program Files (x86)\mysql\connector J \mysql-connector-jaa bin.jar 6. For JDBC port number, leae it at the default 3306 or specify the port number if it is different. 7. For Jaa trace leel, leae it at the default leel Error or change it to the leel instructed by IBM Support. 8. Sae the response file. 9. To configure the agent, enter: install_dir/bin/mysql-agent.sh config instance_name install_dir/samples/mysql_silent_config.txt install_dir\bin\mysql-agent.bat config instance_name install_dir\samples\mysql_silent_config.txt Where instance_name is the name that you want to gie to the instance, and install_dir is the installation directory of MySQL agent. Be sure to include the absolute path to the silent response file. Otherwise, no agent data is aailable in the dashboards. To configure the agent by running the script and responding to prompts, complete these steps: 1. To configure the agent, enter the following command: install_dir/bin/mysql-agent.sh config instance_name Where instance_name is the name you want to gie to the instance, and install_dir is the installation directory for the MySQL agent. 2. Respond to the prompts by using the description of the parameters that were proided earlier for reference. What to do next Start the agent with the following command: install_dir/bin/mysql-agent.sh start instance_name Configuring the Node.js agent install_dir\bin\mysql-agent.bat start instance_name You must add one or more plug-ins to your Node.js application and restart it before the agent can begin monitoring your application. Chapter 6. Configuring your agents 113

120 About this task Node.js is a software platform that employs JaaScript for serer-side solutions, these solutions are often used for receiing and responding to HTTP requests. The Node.js agent can be used to measure and collect data about the performance of Node.js applications. For example, throughput and response times for HTTP requests, and other measurements that relate to resource usage, are monitored and stored for display and analysis. The Node.js agent is a single instance agent. It registers subnodes for each monitored Node.js application. Subnode name structure: NJ:hostname_port:NJA Tip: If one Node.js application listens on multiple port numbers, then the lowest port number is used. You must add one or more plug-ins to your Node.js application and restart it before the agent can begin monitoring your application. These plug-ins, which are known as data collector plug-ins, collect data that is forwarded to the Node.js agent. Currently, there are three data collector plug-ins: The resource data collector plug-in collects resource monitoring data from your Node.js applications. The deep-die data collector plug-in collects diagnostic data from your Node.js applications. The method trace data collector plug-in collects method traces from your Node.js applications. No actual agent configuration is required. The agent starts automatically after installation. Procedure Add one of the following lines to your Node.js application file to add data collector plug-ins. To add resource data collector plug-in, add the following line to the beginning of the Node.js application file: require( install_dir/lx8266/nj/bin/plugin/knj_index.js ); where install_dir is the installation directory of Node.js agent. If the agent is installed in the default directory /opt/ibm/apm/agent, the line is: require( /opt/ibm/apm/agent/lx8266/nj/bin/plugin/knj_index.js ); To add resource data collector plug-in and deep-die data collector plug-in, add the following line to the beginning of the Node.js application file. require( install_dir/lx8266/nj/bin/plugin/knj_deepdie.js ); To add resource data collector plug-in, deep-die data collector plug-in, and method trace data collector plug-in, add the following line to the beginning of the Node.js application file. require( install_dir/lx8266/nj/bin/plugin/knj_methodtrace.js ); Verify that the Node.js agent is running. This step is only needed the first time that the agent is started as it creates a plug-in folder when it first starts. Normally the agent starts automatically 1 or 2 minutes after installation. Restart your Node.js application to enable the monitoring plug-ins. What to do next You can erify the Node.js agent data is displayed in the Performance Management console. 114 IBM Monitoring: Installation and Setup Guide

121 You can change the runtime behaior of Node.js monitoring plug-ins. For more information, see Node.js agent monitoring plug-in: Runtime configuration file Node.js agent monitoring plug-in: Runtime configuration file You can change the behaior of each Node.js monitoring plug-in by changing its runtime configuration in its configuration file. Runtime configuration file The Node.js monitoring plug-in code is in the plug-in folder at: install_dir/lx8266/nj/bin/plugin, where install_dir is the agent installation directory. There is a runtime configuration file for each monitoring plug-in in the install_dir/lx8266/nj/bin/plugin/lib folder. The monitoring plug-in reads the configuration file eery 2 minutes. When you change the content of the configuration file, the behaior of the associated plug-in changes. Tip: The runtime configuration file is named as follows plugin_application port number_conf.json. If a Node.js application is listening on multiple port numbers, the lowest port number is used. There are two types of information in the configuration file: URL filtering rules Plug-in logging parameters URL filtering rules Regular expressions are used to map the URL path name to a user customized path name. Mapping the URL to a customized path name can be used to satisfy the following requirements: When you want to ignore URL paths to static files. For example, if a web page includes images that generate separate serer download requests, you might not be interested in seeing response times for these types of requests. When you want to aggregate URLs with similar paths. For example, for similar URL paths as shown in the following example. /demo/poll/1 /demo/poll/2 /demo/poll/3... On the web serer, requests for these paths are likely sered by a common routine. In this case, you might aggregate the paths to a single URL type by using a filter as shown in the following example. "filters": [ { "pattern": "/demo/poll/.+", "to": "/demo/poll/" } This filter results in all requests to URL paths like "/demo/poll/xxx" being mapped to a URL path type of "/demo/poll". The response times for all requests to URL paths of this type are then aeraged to a single alue. Aggregating in this way can help you make more efficient use of aailable resources. Chapter 6. Configuring your agents 115

122 In the configuration file, there is a JSON array named filters. This array contains the URL filter rules, for example: "filters": [ { "pattern": ".+\\.png$", "to": "" }, { "pattern": ".+\\.jpg$", "to": "" }, { "pattern": "GET /js/.+\\.js$", "to": "" }, { "pattern": "GET /css/.+\\.css$", "to": "" } ] Each member in the array is a filtering rule. When an HTTP request is receied by the plug-in, the plug-in extracts the URL path name from the request and compares it with each "pattern". If the path name matches a particular pattern, the "to" alue for that pattern is used as a URL path name. When the "to" alue is empty, the plug-in ignores the request. If the path name does not match a "pattern", the original URL path name is kept and used for measurements. Plug-in logging parameters In the configuration file, there are three logging parameters The trace log file name The trace leel The trace size rotate The entries in the log file are as follows: "tracefile": "/tmp/app.log", "traceleel": "error", "tracesizerotate": "10", You can specify the log file name by changing the alue of "tracefile". The default alue is "/tmp/app.log". You can set the log file trace leel by changing the alue of "traceleel". The default alue is "error". Two trace leel alues are supported, "info" and "error". If you set the trace leel to the alue "info", messages are logged when the plug-in is running normally, the raw monitoring data sent to the agent is also logged. If you set the trace leel to the alue "error", messages are only logged on an error condition. You can specify rotation size of the log file by changing the alue of "tracesizerotate" in megabytes. The default alue is 10, which means the log file is deleted when its size reaches 10 megabytes. An empty log file with the same name is created for new logs. Configuring the Oracle Database agent The Oracle Database agent proides monitoring capabilities for the aailability, performance, and resource usage of the Oracle database. You can configure more than one Oracle Database instance to monitor different Oracle databases. The remote monitoring capability is also proided by this agent. 116 IBM Monitoring: Installation and Setup Guide

123 Before you begin Before you configure the Oracle Database agent, you must grant priileges to the Oracle user account that is used by the Oracle Database agent. For more information about priileges, see Granting priileges to users for RDBMS instances. About this task For general Oracle database performance monitoring, the Oracle Database agent proides monitoring for the aailability, performance, resource usage, and actiities of the Oracle database, for example: Aailability of instances in the monitored Oracle database. Resource information such as memory, caches, segments, resource limitation, tablespace, undo (rollback), system metric, and system statistics. Actiity information, such as OS statistics, sessions, contention, and alert log. The Oracle Database agent is a multiple instance agent; you must create the first instance and start the agent manually. The Managed System Name includes the instance name that you specify, for example,pc:connection_name-instance_name-host_name:rdb, where pc is your two character product code. The Managed System Name is limited to 32 characters. The instance name that you specify is limited to 28 characters, minus the length of your host name. For example, if you specify Oracle as your instance name, dbconn as your connection name, your managed system name is RZ:dbconn-oraclehostname:RDB. If you specify a long instance name, the Managed System name is truncated and the agent code does not display correctly. The length of the connection_name, instance_name, and hostname_name ariable is truncated when it exceeds 28 characters. To aoid a subnode name that is truncated, change the subnode naming conention by setting the following enironment ariables: KRZ_SUBNODE_INCLUDING_AGENTNAME, KRZ_SUBNODE_INCLUDING_HOSTNAME, and KRZ_MAX_SUBNODE_ID_LENGTH. If you set KRZ_SUBNODE_INCLUDING_AGENTNAME to NO, the subnode ID part of the subnode name does not include the agent instance name. For example: Default subnode name: DBConnection-Instance-Hostname Subnode name with enironment ariable set to NO: DBConnection-Hostname If you set KRZ_SUBNODE_INCLUDING_HOSTNAME to NO, the subnode ID part of the subnode name does not include the host name. For example: Default subnode name: DBConnection-Instance-Hostname Subnode name with enironment ariable set to NO: DBConnection-Instance Procedure To configure the agent by editing the silent response file and running the script with no interaction, complete the following steps: 1. Open the oracle_silent_config.txt file in a text editor: Chapter 6. Configuring your agents 117

124 install_dir/samples/ oracle_database_silent_config.txt. install_dir\samples\oracle_database_silent_config.txt 2. For Default Username, you can specify the name of the default database user for the connection, for example KRZ_CONN_USERID= user1. Note: This user must hae sufficient priileges to complete the tasks that this agent completes while it is connected to the database, such as querying tables. If the user name is not entered for the database connection, the default user name is used. 3. For Default Password, you must enter the password that is associated with the specified default database user, for example, KRZ_CONN_PASSWORD= Password. Note: If the password is not entered for the database connection, the default password is used. 4. For Oracle Home directory, you must complete the following steps: Leae this field empty if you do not hae an Oracle database installed. Complete one of the following steps: - Define only the Oracle Home directory now. - Define the Oracle Home directory now and then define the Oracle Instant Client Installation directory in the next step. - Define only the Oracle Instant Client Installation directory in the next step. - Do not define the Oracle Home directory or the Oracle Instant Client Installation directory in the next step. Then, before you start the agent, you must set the ORACLE_HOME system enironment ariable as shown here: #KRZ_ORACLE_HOME=home_path. 5. For Oracle Instant Client Installation directory, you must complete the following steps: Leae this field empty if you do not hae an Oracle instant client installed. Complete one of the following steps: - Download the Oracle instant client now. Note: If you define both the Oracle home directory and the Oracle instant client installation directory, the Oracle home directory is used for the configuration. - Define the full folder path of the Oracle Home directory that contains the Oracle Call Interface (OCI) library files. If the full path of the oci.dll file is C:\instantclient_10_2\oci.dll you must define this C:\instantclient_10_2 path. - Define the full folder path of the Oracle Home directory that contains the Oracle Call Interface (OCI) library files. If the full path of the libocci.so.10.1 file is /home/tioli/oci/libocci.so.10.1, you must define this /home/tioli/oci path. Note: The Oracle instant client installation directory is on the system where the agent is installed. The attribute does not support the Oracle instant client that is in a network drie. 118 IBM Monitoring: Installation and Setup Guide

125 6. You specify the directory that contains the Oracle database net configuration file. The Oracle Database agent uses this file path to obtain the tnsnames.ora file. This directory is defined by the TNS_ADMIN enironment ariable for each Oracle database instance. The default directory is ORACLE_HOME/network/admin on UNIX or Linux systems, and ORACLE_HOME\NETWORK\ADMIN on Windows systems. ORACLE_HOME is the installation directory for the Oracle database. If you hae multiple net configuration file directories, separate the directories by using a semicolon (;) If you hae multiple net configuration file directories, separate the directories by using a colon (:) If you are monitoring Oracle databases remotely, you can copy net configuration files from the remote system to the system where the agent is installed. Also, you can merge the content of net configuration files on the remote system to the net configuration files on the system where the agent is installed. 7. For Dynamic listener, check if the default dynamic listener is configured. The default dynamic listener is (PROTOCOL=TCP)(HOST=localhost)(PORT=1521). If the default dynamic listener is configured, set this alue to TRUE as shown here; KRZ_DYNAMIC_LISTENER = TRUE. The alid alues are TRUE and FALSE. 8. For Customized SQL definition file name, set one of the following file names: The default file name is install_dir\tmaitm6\ krzcussql.properties. x64 systems, the default file name is install_dir\ TMAITM6_x64\krzcussql.properties. The default file name is install_dir/config/ krzcussql.properties. The customized SQL definition file name is the full file path name of the customized SQL definition file. 9. For Connection Type, specify one of the following connection types: Basic, TNS, oradanced. For example, KRZ_CONN_TYPE.config1=Basic. 10. For the connection type that you selected in Step 9, specify the required parameters: Basic For Hostname, specify the host name or the IP address of the Oracle database, for example: KRZ_CONN_HOST.config1= hostname. For Port, specify the Listener port for the Oracle database, for example: #KRZ_CONN_PORT.config1= For Serice Name, specify the logical representation of the database by using a string for the global database name, for example: KRZ_CONN_SERVICE.config1= orcl. Important: If you do not define the Serice Name, you must specify the Oracle System Identifier (SID). For the Oracle System Identifier (SID), specify an SID that identifies a specific instance of a running database, for example: KRZ_CONN_SID.config1= sid. Chapter 6. Configuring your agents 119

126 TNS For TNS alias, specify the Network alias name from the tnsnames.ora file. For example, KRZ_CONN_TNS.config1= tnsalias. Adanced For Oracle Connection String, specify the database connection string for OCI. For example, KRZ_CONN_STR.connection1= //host:port/serice This string supports all Oracle net naming methods as shown here: For an SQL Connect URL string of the form; //host:[port][/serice name] For an Oracle Net keyword-alue pair: "(DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=dlsun242) (PORT=1521)) (CONNECT_DATA=(SERVICE_NAME=bjaa21)))" This string also supports TNSNAMES entries, for example, inst1 where the TNS_ADMIN or the ORACLE_HOME enironment ariable is set and the configuration files are configured. Important: This attribute applies only to the adanced type of connection. 11. For Database Username, you can specify the name of the database user for the connection, for example: KRZ_CONN_USERID= UserID. This user must hae sufficient priileges to complete the tasks that the agent requires while it is connected to the database, for example, creating, editing, and deleting tables. If this field is empty, the agent uses the default user name in the default database configuration section. If Database Username was not configured, the default user name is used for this connection. 12. For Database Password, you can specify the password that is associated with the specified database user, for example: KRZ_CONN_PASSWORD= Passsword. If this field is empty, the agent uses the default password in the default database configuration section. If Database Password was not configured, the default password is used for this connection. 13. For Role, you can specify the set of priileges that are associated with the connection, for example: KRZ_CONN_MODE.connection1=DEFAULT. The alid alues include; SYSDBA, SYSOPER, SYSASM, and DEFAULT. For a user that is granted the SYSDBA system priilege, you can specify a connection that includes this priilege. If this item is not defined, you can assign the DEFAULT role to the user. 14. For Oracle Alert Log File Paths, that includes the alert log file name, you can specify the absolute file path of the mapped alert log files for the remote database instances in this database connection. For example, KRZ_LOG_PATHS.connection1= AlertLogPath. You use a semicolon (;) to separate the multiple files. You use a colon (:) to separate the multiple files. Each file is matched to a database instance by the alert_instance.log file name pattern. Alternatiely, it is ignored if it is not matched. The local database instance alert log files are discoered automatically. If Oracle Alert Log File Paths was not configured, The Alert Log is not aailable. 15. For Oracle Alert Log File Charset, you can specify the code page of the mapped alert log files. For example, KRZ_LOG_CHARSET.connection1= CharSet 120 IBM Monitoring: Installation and Setup Guide

127 If this field is empty, the system current locale is used as shown here: ISO8859_1: ISO Western European encoding UTF-8: UTF-8 encoding of Unicode GB18030: Simplified Chinese GB18030 encoding CP950: Traditional Chinese encoding EUC_JP: Japanese encoding 16. Sae and close the oracle_database_silent_config.txt file. Then, enter: install_dir/bin/oracle_database-agent.sh config instance_name install_dir/samples/oracle_database_silent_config.txt Where instance_name is the name that you want to gie to the instance. 17. To start the agent, enter: /bin/oracle_database-agent.sh start instance_name. To configure the agent by responding to prompts, complete the following steps: 1. Open the install_dir/bin directory, where install_dir is the installation directory for the Oracle Database agent. 2. (Optional) To check the names and settings for the configured agent instances, run the following command:./cinfo -s rz. 3. To configure the Oracle Database agent, run the following command:./oracle_database-agent.sh config instance_name. 4. When prompted to edit the Oracle Database agent settings, press Enter. The default alue is Yes. 5. When prompted to edit the Default Database Configuration settings, press Enter. The default alue is Yes. 6. To enter the default database configuration information, complete the following steps. a. When prompted for the default user name, type the default database user ID for the connection and press Enter. This user ID is the one that the agent uses to access the connected database instance. This user ID must hae select priileges on the dynamic performance iews and tables that are required by the agent. b. For default password, type the password that is associated with the specified default database user ID, and press Enter. Then, confirm the password. c. If you hae the Oracle database that is installed, type the Oracle home directory, and press Enter. If you want to clear the alue for the Oracle home directory, press the space bar, and then press Enter. If you do not press Enter, complete the next step. d. Type the Oracle instant client installation directory, and press Enter. If you entered the Oracle home directory, this alue is ignored. e. Type the file path of the directory that contains the Oracle database net configuration file, and press Enter. f. Choose whether the default dynamic listener is configured at this workstation, and press Enter. g. Type the full file path of the customized SQL definition file, and press Enter. 7. When prompted to edit the Database Connection settings, press Enter. The default alue is Yes. 8. To add a database connection, type 1, and press Enter. 9. To enter the database connection information, complete the following steps: Chapter 6. Configuring your agents 121

128 a. When prompted for the connection name, type the alias for the connection to the database and press Enter. Only letters, Arabic numerals, the underline character, and the minus character can be used in the connection name. The maximum length of a connection name is 25 characters. b. When prompted for the connection type, select one of the following types of connection: Basic The default connection type is Basic. Select the Basic connection type when the target monitored database is a single instance, such as RDBMS, ASM single instance, DataGuard Primary Node single instance, or DataGuard standby node single instance. 1) When prompted for the Hostname, type the host name or IP address for the Oracle database, and press Enter. 2) When prompted for the port, type the port number, and press Enter. 3) (Optional) When prompted for the serice name, type the name of the serice that is a logical representation of a database, a string that is the global database serice name, and press Enter. 4) (Optional) When prompted for the SID, type the Oracle System Identifier that identifies a specific instance of a running database, and press Enter. TNS Select the TNS connection type when the ORACLE HOME directory is specified and the TNS alias for the target monitored database is defined in the $ORACLE_HOME/network/admin/tnsnames.ora file. 1) Type the TNS Alias name, and press Enter. Adanced Select the Adanced connection type when there is more than one Oracle Instance across multiple physical nodes for the target monitored database. For example, the Real Applications Cluster (RAC) database or the ASM cluster database. 1) Type the Oracle connection string, and press Enter. This attribute supports all Oracle net naming methods as follows: - SQL Connect URL string of the form://host:port/serice name. For example, //dlsun242:1521/bjaa21. - Oracle Net keyword-alue pair. For example, (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp) (HOST=dlsun242) (PORT=1521)) (CONNECT_DATA=(SERVICE_NAME=bjaa21))) - TNSNAMES entries, such as inst1, with the TNS_ADMIN or ORACLE_HOME enironment ariable set and the configuration files configured. c. When prompted for the database user name type the database user ID for the connection, and press Enter. For RDBMS instances, this user ID must hae select priileges on the dynamic performance iews and tables that are required by the agent. For ASM instances, use an account with the SYSDBA or SYSASM role. For example, the sys account. d. When prompted for the database password, type the password that is associated with the specified database user ID. 122 IBM Monitoring: Installation and Setup Guide

129 e. When prompted for Role, type the role name, and press Enter. The role is the set of priileges to be associated with the connection. For a user that was granted the SYSDBA system priilege, you can specify a connection that includes that priilege. For ASM instances, use the SYSDBA role for the Oracle database 10 g, and the SYSDBA or SYSASM role for the Oracle database 11 g. f. When prompted for Oracle alert log file paths, type the Alert Log paths, and press Enter. The absolute file paths of mapped alert log files for remote database instances in this database connection. The agent monitors alert logs by reading these files. If the Oracle Database agent runs and reads the alert log files through the network, the remote file path must follow the uniersal naming conention for Windows systems. For example, \\tix015\path\alert_orcl.log. Important: Enter the path and alert log file name together. A mapped network drier is not supported for the alert log path. If the Oracle Database agent runs, a locally mounted file system is required for remote alert logs. Multiple files are separated by a semicolon (;). Multiple files are separated by a colon (:). Each file is matched to a database instance by using the alert_instance.log file name pattern or if it is unmatched, it is ignored. Local database instance alert log files can be discoered automatically. g. When prompted for oracle alert log file charset, type the code page of the mapped alert log files, and press Enter If this field is blank, the system current locale is used, for example: ISO8859_1, ISO Western European encoding UTF-8, UTF-8 encoding of Unicode GB18030, Simplified Chinese GB18030 encoding CP950, Traditional Chinese encoding EUC_JP, Japanese encoding EUC_KR, Korean encoding For the full list of all the supported code pages, see the ICU supported code pages. 10. (Optional) To add multiple database connections to monitor multiple database instances, type 1 and press Enter. Then, select one of the following options: a. 2 Edit, to edit a database connection b. 3 Del, to delete a database connection c. 4 Next, to change to next database connection d. 5 Exit, to exit the database connection section 11. Type 5, and press Enter. Chapter 6. Configuring your agents 123

130 What to do next For adanced configuration only, the Oracle database administrator must enable the Oracle user to run the krzgrant.sql script to access the database, see Running the krzgrant.sql script. Granting priileges After installing the agent, you must grant priileges to the Oracle user account that is used by the Monitoring Agent for Oracle Database. You can grant priileges for the following users: RDBMS instance users ASM instances Non-SYS users Oracle Data Guard users Granting priileges to users for RDBMS instances For RDBMS instances, the Oracle user ID that the Oracle Database agent uses must hae select priileges on the dynamic performance iews, tables, and data dictionary iews that are required by the agent, and must hae other Oracle object priileges and system priileges that are necessary to run Take Action commands. About this task The procedure for granting priileges includes the following actions: Procedure If an Oracle database user ID does not exist, create this ID by using Oracle facilities and running the following command: create user UserName identified by Password Grant select priileges on the dynamic performance iews, tables, and data dictionary iews to the Oracle user ID that you created by running the krzgrant.sql script that is proided with the Oracle Database agent. Disclaimer: The select priileges for the dynamic performance iews, tables, and data dictionary iews rely on the capabilities of Oracle database in specific application enironments. You may grant authorized Oracle priileges to the Oracle database user ID only for the dynamic performance iews, tables, and data dictionary iews that are used by the Oracle Database agent. Grant select priileges before you configure the Oracle Database agent. For directions about how to customize and run the krzgrant.sql script, see Customizing the krzgrant.sql script and Running the krzgrant.sql script on page 125. Grant other Oracle object priileges and system priileges to the Oracle user ID that the Oracle Database agent uses by using Oracle facilities. Before you run Take Action commands, make sure that the Oracle user ID has the necessary priileges. Customizing the krzgrant.sql script: If you do not hae Oracle authorized select priileges on some dynamic performance iews, tables, and data dictionary iews in the krzgrant.sql script, you can customize the krzgrant.sql script before running it. Note: The: agent instance checks all default priileges in the krzgrant.sql script and reports an agent eent with a lack of priileges when the agent starts. You can 124 IBM Monitoring: Installation and Setup Guide

131 disable priilege checking by using the following ariable setting: KRZ_CHECK_ORACLE_PRIVILEGE=FALSE. The test connection step of GUI configuration checks all Oracle priileges defined in the krzgrant.sql file. If you confirm that the Oracle user has the correct priileges, ignore that checking priileges fails in the test connection step. Edit the krzgrant.sql file in a plain text editor to remoe or add the '--' prefix at the beginning of grant statements to skip the granting execution for those unauthorized Oracle tables or iews. For example, change the following lines: execute immediate grant select on DBA_HIST_SNAPSHOT to username; execute immediate grant select on DBA_HIST_SQLSTAT to username; execute immediate grant select on DBA_HIST_SQLTEXT to username; execute immediate grant select on DBA_HIST_SQL_PLAN to username; execute immediate grant select on DBA_HIST_SYSMETRIC_SUMMARY to username; to these lines: -- execute immediate grant select on DBA_HIST_SNAPSHOT to username; -- execute immediate grant select on DBA_HIST_SQLSTAT to username; -- execute immediate grant select on DBA_HIST_SQLTEXT to username; -- execute immediate grant select on DBA_HIST_SQL_PLAN to username; -- execute immediate grant select on DBA_HIST_SYSMETRIC_SUMMARY to username; Running the krzgrant.sql script: About this task Important: The krzgrant.sql is not applicable for ASM instances. Run the krzgrant.sql script for RDBMS instances. For logical standby databases, grant permissions on the primary database, and the permissions are replicated to standby databases. If you do not run the krzgrant.sql script, an eent is issued in the agent eent workspace. Before beginning this procedure, perform the appropriate installation procedures in the IBM Tioli Monitoring Installation and Setup Guide. After the installation, you can find the krzgrant.sql script in the following directory: Windows x86 systems: install_dir\tmaitm6 Windows x64 systems: install_dir\tmaitm6_x64 UNIX and Linux systems: install_dir/arch/rz/bin Where: install_dir Installation directory for the Oracle Database agent. arch IBM Tioli Monitoring system architecture identifier. For example, li6263 represents Linux Intel 2.6 (32 bit). The krzgrant.sql script has the following usage: krzgrant.sql user_id temporary_directory Where: user_id The ID of the Oracle user. This user ID must be created before running this sql file. Example alue: tioli. Chapter 6. Configuring your agents 125

132 temporary_directory The name of the temporary directory that contains the krzagent.log output file of the krzgrant.sql script. This directory must exist before running this SQL script. Example alue: /opt/ibm/itm/tmp. You must hae the Oracle database administrator (DBA) authorization role and write permission to the temporary directory to perform the following procedure. Procedure 1. From the command line, run the commands to set enironment ariables. Windows systems: SET ORACLE_SID= sid SET ORACLE_HOME= home UNIX or Linux systems ORACLE_SID = sid export ORACLE_SID ORACLE_HOME = home export ORACLE_HOME Where: sid Oracle system identifier, which is case-sensitie. home Home directory for the monitored Oracle instance. 2. From the same command-line window where you set enironment ariables, start the Oracle SQL Plus or an alternatie tool that you use to issue SQL statements. 3. Log on to the Oracle database as a user that has Oracle DBA priileges. 4. Naigate to the directory that contains the krzgrant.sql script and run the following command to grant select user_id temporary_directory The output is logged in the krzagent.log file in the temporary directory. This log records the iews and tables to which the Oracle Database agent is granted select priileges. After the priileges are successfully granted, you can configure and start the Oracle Database agent. Granting priileges to non-sys users for ASM instances About this task You must connect to ASM instances that are using the SYSDBA and SYSASM roles for users. If you do not want to use the SYS account to connect to ASM instances, create a user account and grant the SYSDBA and SYSASM roles to the account. Procedure 1. Run the following commands to create a user account and grant roles: For Oracle 10g Important: Oracle 10g does not hae the SYSASM role and does not support creating a new database user in the ASM instance directly using sqlplus. When you create the ASM connection in the configuration panel, specify the UserName user and the SYSDBA role for Oracle Database 10g. Use only the SYSDBA role. The UserName must be created first. a. Set the ORACLE_HOME and ORACLE_SID enironment ariables as RDBMS home/sid: 126 IBM Monitoring: Installation and Setup Guide

133 Configuring the PHP agent Windows systems: SET ORACLE_SID= sid SET ORACLE_HOME= home UNIX or Linux systems: export ORACLE_SID = sid export ORACLE_HOME = home b. Create the database user by logging in to RDBMS in sqlplus, and creating a new user: create user UserName identified by Password connect / as sysdba grant sysdba to UserName c. Rename the original ASM password file: 1) Back up the ASM password file: m password file for asm instance password file for asm instance.orig 2) Copy the RDBMS password file and rename the file with the ASM password file name: cp password file for database instance password file for asm instance d. Verify the connection to ASM on a separate computer with UserName in sqlplus SQL> connect UserName/Password as sysdba. For Oracle 11g For Oracle 11g, you must log in to the ASM database with the SYSASM role to create a new user for an agent and grant the SYSDBA role or SYSASM role: create user UserName identified by Password grant sysdba to UserName or grant sysasm to UserName 2. When you create the ASM connection in the configuration panel, specify the UserName user and the SYSDBA role for Oracle Database 10g, and the UserName user and the SYSDBA or SYSASM role for Oracle 11g. Note: If you choose the SYSASM role to access the Oracle 11g ASM database, you must configure the agent instance by using Oracle 11g Oracle home or Oracle instant client to connect to the Oracle database. Granting priileges to users for Oracle Data Guard For logical standby databases, grant permissions on the primary database, and the permissions are replicated to standby databases. For instructions on granting permissions for the primary database, see Granting priileges to users for RDBMS instances on page 124. The physical standby database is a read-only database, and cannot be modified. You can use only the SYS user to monitor the physical standby database. You must configure the Monitoring Agent for PHP so that the agent can collect data from the PHP application that is being monitored. Before you begin Ensure that the Apache HTTPD serer is started before you configure the agent. Chapter 6. Configuring your agents 127

134 Open the Apache HTTP Serer httpd.conf configuration file and ensure that both the mod_status and ExtendedStatus On options are enabled. For example: ExtendedStatus On <Location /serer-status> SetHandler serer-status Order deny,allow Allow from all Allow from </Location> In the gien example, must work fine for the agent to work properly. Note: You must hae Lynx or Links installed on Linux for the agent to get monitoring data. Make sure that the command apachectl status works fine in the monitored Apache serer with no code changes to the apachectl command. Lynx must be installed for the command apachectl status to work properly. About this task If you deployed the PHP application by using a non-root user, you must use root or the same non-root user who deployed the PHP application to configure, start, or stop the agent. The PHP agent is a multiple instance agent; you must create the first instance and start the agent manually. The Managed System Name includes the instance name that you specify, for example, instance_name:host_name:pc, where pc is your two character product code. The Managed System Name is limited to 32 characters. The instance name that you specify is limited to 28 characters, minus the length of your host name. For example, if you specify PHP2 as your instance name, your managed system name is PHP2:hostname:PJ. Important: If you specify a long instance name, the Managed System name is truncated and the agent code does not display correctly. Procedure If your enironment is the same as the default settings, you can use the default execution binary path, default php.ini file path, and default port to configure the agent: 1. Enter: install_dir/bin/php-agent.sh config instance_name install_dir/samples/ php_silent_config.txt Where instance_name is the name you want to gie to the instance, and install_dir is the PHP agent installation directory. The default installation directory is /opt/ibm/apm/agent. 2. To start the agent, enter: install_dir/bin/php-agent.sh start instance_name To configure the agent by editing the silent response file and running the script with no interaction, complete the following steps: 1. Open install_dir/samples/php_silent_config.txt in a text editor. 2. For Location of PHP execution binary, you can specify the directory where the PHP execution is located. The default location is /usr/local/bin. 128 IBM Monitoring: Installation and Setup Guide

135 3. For Location of PHP INI file, you can specify the directory where the php.ini file is located. The default location is /etc. 4. For Web serer port, you can specify the port number of the web serer that is running WordPress. The default is For Application DocumentRoot, you can specify the DocumentRoot of the PHP WordPress application. Use a colon to separate multiple records. To allow the agent to find all the records for you, use the default alue of ALL. 6. Sae and close the php_silent_config.txt file, then enter: install_dir/bin/php-agent.sh config instance_name install_dir/samples/ php_silent_config.txt Where instance_name is the name that you want to gie to the instance, and install_dir is the PHP agent installation directory. The default installation directory is /opt/ibm/apm/agent. 7. To start the agent, enter: install_dir/bin/php-agent.sh start instance_name To configure the agent by running the script and responding to prompts, complete the following steps: 1. Enter: install_dir/bin/php-agent.sh config instance_name Where instance_name is the name you want to gie to the instance, and install_dir is the PHP agent installation directory. 2. When prompted to Edit Monitoring Agent for PHP settings, enter 1 to continue. 3. When prompted for Location of PHP execution binary, press Enter to accept the default location or specify your own location. 4. When prompted for Location of PHP INI file, press Enter to accept the default location or specify your own location. 5. When prompted for Web serer port, press Enter to accept the default port or specify a different port number. 6. When prompted for Application DocumentRoot, press Enter to accept the default or specify the DocumentRoot of the PHP WordPress application. You can use a colon to separate multiple records. 7. To start the agent, enter: install_dir/bin/php-agent.sh start instance_name What to do next You can erify the PHP agent data is displayed in the Performance Management console. You must ensure that the WordPress plugin-in for the agent is actiated. To ensure actiation, complete the following steps: 1. In a web browser, enter the following URL 2. Access the administratie page by naigating to Plugins > Installed Plugins. 3. Ensure that the PHP agent plug-in is actiated. The PHP agent plug-in is listed as WordPress Agent. Typically, the plug-in is already actiated. If it is not already actiated, click on Actiate. Configuring the PostgreSQL agent You must configure the Monitoring Agent for PostgreSQL so that the agent can collect data from the PostgreSQL database that is being monitored. Chapter 6. Configuring your agents 129

136 Before you begin If the authentications settings are not correct in the PostgreSQL database pg_hba.conf file, the PostgreSQL agent cannot connect to the PostgreSQL database. If auth-method is set to ident, the PostgreSQL agent cannot connect. Ensure that the PostgreSQL pg_hba.conf authentication file has the correct auth-method settings. For example, you might set auth-method to md5, trust, or password. About this task The PostgreSQL agent is a multiple instance agent; you must create the first instance and start the agent manually. The Managed System Name includes the instance name that you specify, for example, instance_name:host_name:pc, where pc is your two character product code. The Managed System Name is limited to 32 characters. The instance name that you specify is limited to 28 characters, minus the length of your host name. For example, if you specify PostgreSQL2 as your instance name, your managed system name is PostgreSQL2:hostname:PN. Important: If you specify a long instance name, the Managed System name is truncated and the agent code does not display correctly. Procedure To configure the agent by editing the silent response file and running the script with no interaction, complete the following steps: 1. Open install_dir/samples/postgresql_silent_config.txt in a text editor, where install_dir is the installation directory of PostgreSQL agent. The default installation directory is /opt/ibm/apm/agent. 2. For JDBC database name, leae it set to postgres or specify the database name. 3. For JDBC user name, leae it set to postgres or change to a different user name. 4. For JDBC password, enter the JDBC user password. 5. For JDBC port number, leae it at the default 5432 or specify the port number if it is different. 6. For JDBC JAR file, leae the path to the PostgreSQL connector for the Jaa JAR file at the default if it is correct; otherwise, enter the correct path. Default path: /opt/postgresql/lib/postgresql jdbc4.jar. 7. For Jaa trace leel, leae it at the default leel Error or change it to the leel instructed by IBM Support. 8. Sae and close the postgresql_silent_config.txt file, and enter: install_dir/bin/postgresql-agent.sh config instance_name install_dir/samples/postgresql_silent_config.txt Where instance_name is the name that you want to gie to the instance, and where install_dir is the installation directory of PostgreSQL agent. 9. To start the agent, enter: install_dir/bin/postgresql-agent.sh start instance_name To configure the agent by running the script and responding to prompts, complete the following steps: 1. Enter: install_dir/bin/postgresql-agent.sh config instance_name Where instance_name is the name you want to gie to the instance, and where install_dir is the installation directory of PostgreSQL agent. 130 IBM Monitoring: Installation and Setup Guide

137 Configuring the Python agent 2. When prompted to Edit Monitoring Agent for PostgreSQL settings, enter 1 to continue. 3. When prompted for JDBC database name, press Enter to accept the default or specify a database name. 4. When prompted for JDBC user name, press Enter to accept the default or specify a user name. 5. When prompted for JDBC password, enter the JDBC user password. 6. When prompted for JDBC port number, press Enter to accept the default or specify a port number. 7. When prompted for JDBC JAR file, press Enter to accept the default or specify the file. 8. When prompted for Jaa trace leel, enter 2 to accept the default or specify the trace. 9. To start the agent, enter: install_dir/bin/postgresql-agent.sh start instance_name You must configure the Monitoring Agent for Python so that the agent can collect data from the Python application that is being monitored. Before you begin Ensure that the Apache HTTPD serer is started before you configure the agent. Open the Apache HTTPD serer httpd.conf configuration files and ensure that mod_status is loaded. Make sure the command apachectl status works properly in the monitored Apache serer with no code changes to the httpd.conf configuration file. If it doesn't work fine you might not be able to see some metrics in the dashboards, for example, Busy worker and Idle worker. Note: You must hae Lynx installed for the command apachectl status work properly. For more information about enabling the command, see apachectl - Apache HTTP Serer Control Interface. If this is not the first time you configure the agent instance, follow the steps: 1. Stop the agent instance. 2. Follow one of the procedures to configure the agent instance: Configure the agent by editing the silent response file. Configure the agent by responding to prompts. 3. Make sure that the new middleware is deployed to the Django setting folder. To do that, make sure the kpg_numeric_string.py file in the Django setting folder is updated. 4. Restart the Apache serer. About this task If you deployed the Python application by using a non-root user, you must use root or the same non-root user who deployed the Python application to start, stop, or configure the agent. Chapter 6. Configuring your agents 131

138 The Python agent is a multiple instance agent; you must create the first instance and start the agent manually. The Managed System Name includes the instance name that you specify, for example, instance_name:host_name:pc, where pc is your two character product code. The Managed System Name is limited to 32 characters. The instance name that you specify is limited to 28 characters, minus the length of your host name. For example, if you specify Python2 as your instance name, your managed system name is Python2:hostname:PG. Important: If you specify a long instance name, the Managed System name is truncated and the agent code does not display correctly. Procedure To configure the agent by editing the silent response file and running the script with no interaction, complete the following steps: 1. Open install_dir/samples/python_silent_config.txt in a text editor, where install_dir is the Python agent installation directory. The default installation directory is /opt/ibm/apm/agent. 2. For HTTPD listening port, specify the port number to distinguish one group of HTTPD processes from others. The default is 80. Note: If your Apache serer is listening on multiple ports, you can specify any one of them for this parameter. If you hae more than one Apache serer running on the same system, you must specify a port from the serer in which the Django applications are running. If you want to use multiple agent instances to monitor Python application instances that are using different ports on the same Apache serer, besides specifying the ports, you must also specify different Django WSGI entry points in the next step. If you only specify the ports, the agent instances monitor the same serer and the data is the same. 3. For Is Python 3, if the alue of this field is false, your Python enironment is regarded as Python ersion 2.x. If your Python ersion is 3.x, change the alue to be not false, for example, true. The default alue is false. 4. For Django WSGI entry points, specify the Django WSGI entry points. Use a colon to separate multiple entry points. For example, in an Apache configuration file, you might see the following configuration line: WSGIScriptAlias / /ar/www/html/mysite/mysite/wsgi.py In this example, /ar/www/html/mysite/mysite/wsgi.py is proided as the entry point. To include all the entry points that are discoered in the Apache configuration files, leae this parameter blank. Note: Do not specify the same Django WSGI entry point for different agent instances. If you use the default option to configure one agent instance to monitor an Apache serer, do not configure other agent instances to monitor the same serer. 5. For Django settings for the monitored application, specify the Django settings for the monitored application, for example, my_project.settings. If you are using default alues, leae this field empty. 132 IBM Monitoring: Installation and Setup Guide

139 6. For Minimum recorded response time, set the aerage response time in milliseconds. Requests that are faster or equal to this number are not recorded. The default is For Slow request threshold, set the slow request threshold in milliseconds. The default is For Extreme slow request threshold, set the extreme slow request threshold in milliseconds. The default alue is For Profiler report interal, set the interal in minutes, at which the agent generates the profiler report for slow requests. The minimum setting for this alue is 10, which ensures your applications are not slowed down because of excessie profiling. Typical users set this alue greater than 10. The default is 10. This parameter also tells the agent script how to aggregate the monitoring data. At the beginning of each minute, the monitoring middleware resets its data, which is collected from the preious minute and starts to write a new raw data file. The agent script summarizes raw data based on this parameter and returns the result. For example, if this number is 10 minutes, agent scripts aggregate all raw data for the preious 10 minutes and return the results. The final result might be an aerage, such as response time for one particular URL, or the result might be a sum, such as total requests or traffic bytes. 10. Sae and close the python_silent_config.txt file, then enter: install_dir/bin/python-agent.sh config instance_name install_dir/samples/python_silent_config.txt Where instance_name is the name that you want to gie to the instance, and install_dir is the Python agent installation directory. The default installation directory is /opt/ibm/apm/agent. 11. To start the agent, enter: install_dir/bin/python-agent.sh start instance_name To configure the agent by running the script and responding to prompts, complete the following steps: 1. Enter: install_dir/bin/python-agent.sh config instance_name Where instance_name is the name you want to gie to the instance, and install_dir is the Python agent installation directory. The default installation directory is /opt/ibm/apm/agent. 2. When prompted to Edit Monitoring Agent for Python settings, enter 1 to continue. 3. When prompted for HTTP listening port, press Enter to accept the default or specify a port number. Note: If your Apache serer is listening on multiple ports, you can specify any one of them for this parameter. If you hae more than one Apache serer running on the same system, you must specify a port from the serer in which the Django applications are running. If you want to use multiple agent instances to monitor Python application instances that are using different ports on the same Apache serer, besides specifying the ports, you must also specify different Django WSGI entry points in the next step. If you only specify the ports, the agent instances monitor the same serer and the data is the same. Chapter 6. Configuring your agents 133

140 4. When prompted for Is Python 3, type false if your Python ersion is not 3. If your Python ersion is 3.x, specify a alue that is not false, for example, true. The default alue is false. 5. When prompted for Django WSGI entry points, leae this parameter blank or specify the entry points. Note: Do not specify the same Django WSGI entry point for different agent instances. If you use the default option to configure one agent instance to monitor an Apache serer, do not configure other agent instances to monitor the same serer. 6. When prompted for Django settings for the monitored application, specify the Django settings for the monitored application, for example, my_project.settings. If you are using default alues, leae this field empty and press Enter. 7. When prompted for Minimum recorded response time, press Enter to accept the default or specify the time. 8. When prompted for Slow request threshold, press Enter to accept the default or specify a threshold. 9. When prompted for Extreme slow request threshold, press Enter to accept the default or specify a threshold. 10. When prompted for Profiler report interal, press Enter to accept the default or specify an interal. 11. To start the agent, enter: install_dir/bin/python-agent.sh start instance_name What to do next After you start the agent instance, an injection script to customize your monitoring middleware is generated and proided in a temporary directory. The injection shell script runs automatically after the agent starts. If you want to make sure that this step was correctly executed, you can make sure that the following files exist: install_dir/tmp/kpg/inject_numeric_string.sh Django_setting_folder/kpg_numeric_string.py Important: The suffix numeric string identifies a Django application. If you hae multiple injection scripts that were generated in that temp folder, you see the same number of kpg_numeric_string.py files. Generally, an injection script does the following jobs: Backs up the original WSGI setting file for each Django application. Copies the customized WSGI setting file to oerride the original file Moes the customized middleware to the Django application folder. Enables module status for Apache serer. The injection script also generates the uninstallation scripts to help you uninstall the middleware from each Django application. Note: Multiple injection scripts might include the enablement of the Apache status module, howeer, when executing the scripts the module is only added once. For your reference, you can use the following stop and restart commands for the Apache serer: 134 IBM Monitoring: Installation and Setup Guide

141 Stop: apache_bin_directory/httpd -k graceful-stop Restart: apache_bin_directory/httpd -k graceful Python agent: Runtime configuration You can change the behaior of each Python agent by changing its runtime configuration in its configuration file. Runtime configuration file Each Django application has its own runtime configuration file, which is in the temporary folder for the agent: install_dir/tmp/kpg/ plugin_conf_numeric_string.json where install_dir is the Python agent installation directory. The default installation directory is /opt/ibm/apm/agent. Eery minute, eery monitoring middleware component reads its own runtime configuration and changes its behaior accordingly. A runtime configuration file includes the following items: "filters": [ { "pattern" : "GET/polls/get_infinite/.*", "to" : "GET/polls/infinite/123" } 7 ], "maxrequestsize": 200, "logleel": "error" URL filters A URL filter aggregates different URLs into one URL. Some websites implement the same function with different or unique URL paths. For example, the following requests might be answered by the same back end routine on the serer side: /polls/1/ /polls/2/ /polls/45/ From the resource monitoring or performance diagnosis iew, you are not required to distinguish among those requests. You can write a JSON format regular expression and assign the expression to a filter as its pattern. Usually, a pattern for a filter includes an HTTP method and a regular expression for matching a particular URL path name. Then, you can assign a uniform string as its new URL path. Similarly, in this uniform string, include the same method and a static string to identify this kind of request. The following example shows a sample filter for the requests in URL filters : { pattern : GET/polls/[09]+/, to : GET/polls/n/ } With this filter, the sample requests are aggregated as one. The response time, count, and traffic are calculated together. The profiler report is generated for one request and for a collection interal. You can define as many filters as you require and put them in the array. The first matched filter is used for one request. Chapter 6. Configuring your agents 135

142 Note: Configure the URL filters to map multiple requests with the same patterns to one request to aoid the issue where some requests with the same pattern cannot find matching profile information. Max Request Size In each Apache working process, for 1 minute, the monitoring middleware remembers as many kinds of URLs as designated by Max Request Size. Trace Leel Each monitoring middleware component can log messages to its own log file. You can find the messages in the following temp folder: /tmp/kpglogs/ kpg_parentprocessid_processid.log These log files are rotated if their size reaches 10 MB. One rotation is saed. If you hae multiple Django projects, the log file contains messages for all projects. Configuring the Response Time Monitoring agent You can customize the data that is displayed by the Response Time Monitoring agent in the End User Transactions dashboards. The following process is for configuring the Response Time Monitoring agent. 1. Install the agent. 2. Configure the agent by running one of the following commands and proiding alues when prompted. install_dir/bin/rt-agent.sh config install_dir\bin\rt-agent.bat config For more information about the configuration options, see Configuration defaults on page To monitor HTTPS transactions, see Monitoring HTTPS transactions on page 144 for more information, including how to import certificates. 4. Optional: to enable data collection from the browser, see Enabling collection of data from the browser. 5. Optional: to enable resource timing monitoring, see Enabling resource timing monitoring 6. Optional: if you are operating a high transaction load enironment and you want to limit the monitoring oerhead of the Response Time Monitoring agent, see Configuring CPU oerhead limit on page Start the agent. 8. After the agent is connected to the monitoring serer, go to the Agent Configuration page in the UI and customize the agent to monitor HTTP transactions. See Monitoring HTTP transactions on page 141 for more information. Adding applications After you install the Response Time Monitoring agent, you might need to add the applications that you want to monitor to the Application Performance Dashboard. 136 IBM Monitoring: Installation and Setup Guide

143 Procedure To add applications to the Application Performance Dashboard: 1. In the Application Performance Dashboard, select Add Application. 2. Select Read to open a list of discoered applications. 3. Select the application that you want to monitor. Response Time is displayed as the source repository in the Application read from field, and any components are listed in Application components. Chapter 6. Configuring your agents 137

144 4. No further configuration is required to display applications monitored by the Response Time Monitoring agent. Click Sae in the Add Application window. Results Applications detected by the Response Time Monitoring agent are listed in All My Applications in the Application Performance Dashboard. See Managing applications ( SSMKFH/com.ibm.apmaas.doc/install/min/min_admin_managing_apps.htm) for more information. Customizing data collected by Response Time Monitoring agent You can customize what data is collected by the Response Time Monitoring agent, such as which IP address to monitor, the type of transactions to monitor, and on which port. You can also configure whether Transaction Tracking is to be enabled or not. Before you begin Tip: Data from the Response Time Monitoring agent is used for the following dashboards: End User Transactions Authenticated Users Mobile Deices Data from the Response Time Monitoring agent is also used in the Application > Status Oeriew in the following widgets: Requests and Response Time Users Aggregate Transaction Topology 138 IBM Monitoring: Installation and Setup Guide

145 Response Time Monitoring agents must be installed and configured for data to be displayed in these widgets. About this task Response Time Monitoring agents report data in the APM UI in the local time of the user. You cannot monitor different web serers that host the same application, across different timezones. For example, if your website has load balancers that sere traffic from serers in New York, Rome, and Sydney, monitor only one of the 3 locations with the Response Time Monitoring agent. If the 3 locations host different applications, such as files.example.com:80, shop.example.com:80, and pages.example.com:80, monitor all 3 locations with the Response Time Monitoring agent. Procedure You can configure the Response Time Monitoring agent in one of the following ways. Configuration properties are applied in the priority order listed. Agent Configuration, which enables you to set whether HTTP traffic is monitored by the Response Time Monitoring agent and on which ports. To access the Agent Configurationpage, in the APM UI select System Configuration > Agent Configuration, then select the Response Time tab. See Monitoring HTTP transactions on page 141 for more information. Local configuration Use the rt-agent configuration command or Manage Monitoring Serices on the agent computer to customize most options. Use local configuration to customize all Response Time Monitoring agents earlier than V Defaults, which are used if there is no custom configuration The defaults used for Response Time Monitoring are listed in Table 15 on page 140. Chapter 6. Configuring your agents 139

146 Configuration defaults The defaults used for Response Time Monitoring are listed here. Before you begin If there are no other higher priority customizations, the Response Time Monitoring agent uses the defaults listed in Table 15. Table 15. Response Time Monitoring configuration defaults Configuration Name Setting Default Description KT5HTTPPORTS HTTP ports to monitor 80 Ports monitored by Response Time Monitoring agents. Tip: Use one of the following methods to configure this setting. KT5MONITORHTTPSAPP Monitor HTTPS transactions? No For Response Time Monitoring agent V and earlier, use the rt-agent configuration command, or Manage Monitoring Serices on the agent computer to configure this setting. For Response Time Monitoring agent V and later, set the HTTP ports that are monitored on the Agent Configuration page in the Performance Management console. The settings on the Agent Configuration page take priority oer defaults or alues specified in Manage Monitoring Serices or with the rt-agent configuration command. Sets whether HTTPS transactions are monitored or not. Set to Yes to monitor HTTPS transactions. Restriction: If you enable monitoring for HTTPS transactions, ensure that you specify a keystore file and certificate. See Enabling Appliance Mode for HTTPS transactions, in the ITCAM for Transactions documentation for more information. Use the rt-agent configuration command, or Manage Monitoring Serices on the agent computer to configure this setting. KT5KEYSTORE HTTPS keystore Contains the certificates for the remote HTTPS websites that are being monitored. For example, /opt/ibm/httpserer/keys/key.kdb Use the rt-agent configuration command, or Manage Monitoring Serices on the agent computer to configure this setting. This setting is optional. If HTTPS transactions are not monitored, skip this option. 140 IBM Monitoring: Installation and Setup Guide

147 Table 15. Response Time Monitoring configuration defaults (continued) Configuration Name Setting Default Description KT5SERVERMAP HTTPS serer certificate map Maps HTTPS serers to their certificates. For example, certalias, ,443;... Use the rt-agent configuration command, or Manage Monitoring Serices on the agent computer to configure this setting. This setting is optional. If HTTPS transactions are not monitored, skip this option. KT5MONITORIP IP address of the NIC to be monitored If you are monitoring a Network Interface Card, specify its IP address here. You can specify only one IP address. Use the rt-agent configuration command, or Manage Monitoring Serices on the agent computer to configure this setting. Note: If you do not specify any alue for this option, all NICs are monitored. KT5ENABLEINSTANCE DATAANALYTICS Enable Instance Data Analytics? Yes for IBM Performance Management (SaaS) No for IBM Monitoring (SaaS) and IBM Monitoring (On Premises) Causes the Response Time Monitoring agent to push granular transaction data to the monitoring serice that enables adanced analytics. Use the rt-agent configuration command, or Manage Monitoring Serices on the agent computer to configure this setting. Set to Yes to send tracking instance data to the monitoring serice. Use this option after you upgrade from IBM Monitoring (SaaS) to IBM Performance Management (SaaS) to start sending tracking instance data to the Monitoring Infrastructure Node. This option enables Transaction Tracking. Set to No to stop sending tracking instances to the monitoring serice. Use this option to stop sending tracking instances for scale, network, or performance reasons, or if you change to IBM Monitoring (SaaS). This option disables Transaction Tracking. Monitoring HTTP transactions Response Time Monitoring monitors HTTP transactions on port 80 by default. For Response Time Monitoring V1.2.6 (V ) and later, you can use the Agent Configuration page in the Performance Management console to disable or enable HTTP transaction monitoring and set the ports that are monitored by Response Time Monitoring agents. Chapter 6. Configuring your agents 141

148 Before you begin Any Response Time Monitoring agent that is upgraded to Response Time Monitoring V and later can also use the Agent Configuration page. Earlier agents cannot use this feature. If you hae upgraded to Response Time Monitoring V or later, or you configured the agent silently, you must manually edit the following configuration files and properties before you can use the Agent Configuration page for future configuration. In the following examples, the default port, port 80 is used. If you monitored HTTP traffic on a different port, customize for your enironment. Remoe {KT5MONITORHTTP=YES} {KT5HTTPPORTS=80} from /opt/ibm/apm/agent/ config/hostname_t5.cfg Remoe KFC_HTTP_PORT=80 from /opt/ibm/apm/agent/tmaitm6/wrm/kfcmen Remoe {KT5MONITORHTTP=YES} {KT5HTTPPORTS=80} from C:\IBM\ITM\ TMAITM6_x64\HOSTNAME_t5.cfg Remoe KFC_HTTP_PORT=80 from C:\IBM\ITM\TMAITM6_x64\wrm\Analyzer Restriction: Do not remoe these configuration parameters from Response Time Monitoring agent V or earlier. These agents cannot use the Agent Configuration page, so the configuration parameters cannot be easily restored. If you are running the Response Time Monitoring agent behind a load balancer, you can configure the load balancer to forward the IP address of the client to optimize monitoring performance. See the following steps as an example: 1. In the HTTP header, set the IP address of the client in the X-Forwarded-For field. 2. Configure the Response Time Monitoring agent to use the IP address header of the client. Set the IP address header of the client in the KFC_OVERRIDE_SOURCE_ADDR_HEADER field in one of the following files depending on your operating system: /opt/ibm/apm/agent/tmaitm6/wrm/kfcmen C:\IBM\ITM\TMAITM6_x64\wrm\Analyzer\kfcmen For example: KFC_OVERRIDE_SOURCE_ADDR_HEADER=x-forwarded-for or if using WebSEAL: KFC_OVERRIDE_SOURCE_ADDR_HEADER=i-remote-address To access the Response Time Monitoring Agent Configuration page, in the APM UI, select System Configuration > Agent Configuration, then select the Response Time tab. 142 IBM Monitoring: Installation and Setup Guide

149 The Agent Configuration page lists the systems in your enironment on which Response Time Monitoring is installed. For each system it shows: Whether the system is online (checkmark with green background) or offline (exclamation mark with red background) Version of the Response Time Monitoring agent that is installed If the ersion of the agent is earlier than , you cannot configure it using the Agent Configuration page. Earlier agent ersions that you cannot configure using this tool are struck through and if you select them an error is displayed. Whether the system uses the default configuration alues or has some custom alues set Select an agent to display its configuration settings. To find a particular agent, enter part or all of the name of the system on which it is installed in the Filter field. About this task Customizations made on the Agent Configuration page take precedence oer any other customization and oer default alues. If you change your mind about the settings you changed, click Undo Changes to reert to the last settings that were saed, or click Reert to Default to reert to the default alues. See Table 15 on page 140 for information about default alues. Procedure To monitor HTTP traffic for a particular system: 1. Select the system or systems that you want to update. Select multiple systems if you want to use the same HTTP settings for each of those systems. If the systems you select hae different HTTP alues set, Multiple Values or Multiple Lists is displayed instead of indiidual alues. You cannot update systems with different alues at the same time. 2. In the Monitor HTTP traffic? field, double-click the alue and select Yes from the list. Chapter 6. Configuring your agents 143

150 3. In the HTTP Ports to monitor field, double-click the alue and enter any additional ports you want to monitor, other than the default port 80 and any other ports already listed. To stop monitoring a port, select the port you no longer want to monitor and click Remoe. 4. Click Apply Changes. Results The new configuration alues are sent to Central Configuration Serices and then online agents are automatically reconfigured without haing to be restarted. If the agent is offline, it downloads the new configuration settings when it comes online. Data from the new ports are displayed in the dashboards associated with Response Time Monitoring when the data is refreshed. Monitoring HTTPS transactions Response Time Monitoring monitors HTTPS transactions by default. Howeer, to decrypt SSL traffic from your remote web serers, Response Time Monitoring requires access to the SSL Certificates. Import keys into the KT5Keystore for all web serers that you want to monitor. Before you begin Identify the HTTPS web serers that you want to monitor, including their IP addresses and configured ports. For example, , port 443. For each HTTPS web serer, check that Response Time Monitoring can read its ciphers. Response Time Monitoring supports the ciphers supported by IBM Jaa, including the following ciphers. RSA_WITH_RC4_40_MD5 RSA_WITH_RC4_128_MD5 RSA_WITH_RC4_128_SHA RSA_WITH_RC4_40_SHA RSA_WITH_DES40_CBC_SHA RSA_WITH_DESC_CBC_SHA RSA_WITH_3DES_EDE_CBC_SHA RSA_WITH_AES_128_CBC_SHA RSA_WITH_AES_256_CBC_SHA RSA_EXPORT1024_WITH_RC4_56_MD5 RSA_EXPORT1024_WITH_RC2_CBC_56_MD5 RSA_EXPORT1024_WITH_DES_CBC_SHA RSA_EXPORT1024_WITH_RC4_56_SHA TLS_RSA_WITH_AES_128_CBC_SHA256 TLS_RSA_WITH_AES_256_CBC_SHA256 Restriction: Response Time Monitoring cannot decrypt traffic using Diffie-Hellman key exchange. Also, check that the CMS Proider is enabled in your Jaa ersion: 1. Naigate to the install_dir\ibm-jre\jre\lib\security directory. For example: /opt/ibm/lotus/notes/latest/linux/ibm-jre/jre/lib/security/ C:\Program Files\IBM\Domino\ibm-jre\jre\lib\security 144 IBM Monitoring: Installation and Setup Guide

151 2. In the jaa.security file, add the following statement to the list of security proiders as shown, where number is the last sequence number in the list. security.proider.number=com.ibm.security.cmskeystore.cmsproider The list of proiders looks like the following example: ## List of proiders and their preference orders # security.proider.1=com.ibm.jsse.ibmjsseproider security.proider.2=com.ibm.crypto.proider.ibmjce security.proider.3=com.ibm.security.jgss.ibmjgssproider security.proider.4=com.ibm.security.cert.ibmcertpath security.proider.5=com.ibm.security.cmskeystore.cmsproider... # 3. Sae and close the file. About this task For HTTPS transaction monitoring, Response Time Monitoring has the following defaults: Table 16. HTTPS transaction monitoring defaults Configuration Name Setting Default Description KT5MONITORHTTPSAPP Monitor HTTPS transactions? No Sets whether HTTPS transactions are monitored or not. Set to Yes to monitor HTTPS transactions. KT5KEYSTORE HTTPS keystore Contains the certificates for the remote HTTPS websites that are being monitored. For example, /opt/ibm/httpserer/keys/key.kdb The password to keys.kdb is stored in an encrypted stash file, keys.sth. Response Time Monitoring assumes that the stash file is in the same directory as the key database and has the same suffix. KT5SERVERMAP HTTPS serer certificate map Maps HTTPS serers to their certificates. For example, certalias, ,443;... Import keys into the HTTPS Keystore for all web serers that you want to monitor. You can either export the SSL certificates from the web serers that you are monitoring and import them to the HTTPS Keystore using IBM Key Management (ikeyman), or specify the web serer's.kdb file in the HTTPS Keystore. When you install or configure Response Time Monitoring, you are prompted for the location of the keys.kdb file. Procedure To enable HTTPS transaction monitoring, collect the SSL certificates from the web serers that you want to monitor and import the certificates and keystore stash files into the HTTPS Keystore using ikeyman. The following example uses ikeyman to export the certificates from an IBM HTTP Serer, and import them to HTTPS Keystore: 1. Install a Response Time Monitoring agent on each HTTPS web serer that you want to monitor. 2. Run IBM Key Management (ikeyman) from within the IBM Jaa bin directory by running one of the following commands depending on your operating system. Chapter 6. Configuring your agents 145

152 /opt/ibm/apm/agent/jre/lx8266/bin/ikeyman Note: You must hae X-Window on the enironment for ikeyman to work properly. c:\ibm\apm\jaa\jaa70_x64\jre\bin\ikeyman 3. Create a new Keystore database. In the New dialog box: a. From the Key database type list, select CMS. If CMS is not aailable in the list, the CMS Proider might not be enabled. Enable the CMS Proider in the Jaa security file. b. In the File Name field, enter the name of the HTTPS Keystore file, for example keys.kdb, and click OK. 4. In the Password Prompt dialog box: a. In the Password and Confirm Password fields, enter and confirm the password to access keys.kdb. Do not set an expiration time unless you want to recreate the keystore database and restart the Response Time Monitoring agent periodically. b. Select Stash the password to a file? to store the password for keys.kdb in an encrypted form in a stash file, keys.sth. 5. In the Key database content section of the ikeyman window: a. Select Personal Certificates. b. Click Import. c. In the Import Key dialog box, from the Keyfile type list, select CMS. d. Browse to the keystore file and click Open, and then click OK. e. In the Password Prompt dialog box, enter the keystore password. f. Select the key from the list and click OK. g. In the Change Labels dialog box, select the key label name. In the Enter a new label field, specify the host name of the serer and click Apply. Note: This alue is required when configuring Response Time Monitoring, so make a note of it. h. Click OK. 6. Sae the HTTPS Keystore. Customizing local configuration files Use the rt-agent configuration command or Manage Tioli Enterprise Monitoring Serices to customize most options. About this task These steps assume the following installation paths: /opt/ibm/ccm/agent /opt/ibm/apm/agent C:\IBM\APM\ If you installed to a different path, substitute the path in the instructions, and edit the AGENT_HOME parameter in the silent response file for the path where you installed the monitoring agent. Note: For Linux and AIX systems, use the same root user that you used to install the agent to start, stop, and configure the agent. 146 IBM Monitoring: Installation and Setup Guide

153 Tip: If you want to deploy a customized configuration silently, a sample silent configuration file is installed in the following locations for you to copy and customize by using a text editor: /opt/ibm/ccm/agent/samples/rt_silent_config.txt /opt/ibm/apm/agent/samples/rt_silent_config.txt C:\IBM\APM\samples\rt_silent_config.txt Procedure To customize your data settings: 1. On the computer on which the Response Time Monitoring agent is installed, stop the agent: /opt/ibm/ccm/agent/bin/rt-agent.sh stop /opt/ibm/apm/agent/bin/rt-agent.sh stop C:\IBM\APM\BIN\rt-agent.bat stop. 2. Use either of the following methods to configure the agent, entering the alues that you require, by using thetable 15 on page 140 as a reference: Interactie configuration, where you configure the agent by running a script or user interface and respond to prompts: /opt/ibm/ccm/agent/bin/rt-agent.sh config /opt/ibm/apm/agent/bin/rt-agent.sh config use the Manage Tioli Enterprise Monitoring Serices: a. Right-click Response Time Monitoring Agent, and select Configure. b. Step through the windows, configuring the settings you require. Silent configuration, where you first edit the response file and then run it with no further interaction required: /opt/ibm/ccm/agent/bin/rt-agent.sh config path-to-silentinstallation-file /opt/ibm/apm/agent/bin/rt-agent.sh config path-to-silent-installation-file C:\IBM\APM\BIN\rt-agent.bat config path-to-silentinstallation-file 3. Restart the Response Time Monitoring agent for the changes to take effect: /opt/ibm/ccm/agent/bin/rt-agent.sh start /opt/ibm/apm/agent/bin/rt-agent.sh start C:\IBM\APM\BIN\rt-agent.bat start. Results Data from the new source is displayed in the dashboards that are associated with Response Time Monitoring. Configuring CPU oerhead limit If you are operating a high transaction load enironment and you want to limit the monitoring oerhead of the Response Time Monitoring agent, you can use this function to limit the CPU oerhead of the Response Time Monitoring agent. Chapter 6. Configuring your agents 147

154 About this task This function limits the CPU oerhead of the Response Time Monitoring agent by monitoring and reporting only a portion of the web traffic using sampling. CPU oerhead limit is not configured by default. You must configure the CPU oerhead limit on the serer where the agent is installed. Procedure To configure CPU oerhead limit: 1. Open one of the following files depending on your operating system: /opt/ibm/apm/agent/tmaitm6/wrm/kfcmen C:\IBM\ITM\TMAITM6_x64\wrm\Analyzer\kfcmen 2. Configure the alues for the following parameters: KFC_MAX_PROTOCOL_PACKETRATE The initial maximum packet rate. For example, if you set the parameter as KFC_MAX_PROTOCOL_PACKETRATE=2000, the maximum packet rate is 2000 packets per second. This rate aries dynamically based on the alue for KFC_CPUTHROTTLE_TARGET and the current CPU usage. KFC_CPUTHROTTLE_TARGET The percentage of the oerall CPU resource that can be used by the kfcmserer process. For example, if you set the parameter as KFC_CPUTHROTTLE_TARGET=10.0, the kfcmserer process can use up to 10% of the oerall CPU resource. Results Note: The alue for parameter KFC_CPUTHROTTLE_TARGET is the percentage of the oerall CPU resource that is aailable for the kfcmserer process. For example, if you hae 4 CPU cores and KFC_CPUTHROTTLE_TARGET is set to 10, the Resource Monitor in Windows measures CPU resource as 400%. As a result, the kfcmserer process can use up to 40% of the total 400% CPU resources aailable. The CPU oerhead limit is configured for the Response Time Monitoring agent. Using the IBM HTTP Serer Response Time module Install the IBM HTTP Serer Response Time module to easily monitor the performance of HTTP pages and embedded objects for web pages sered by IBM HTTP Serer without haing to further configure the Response Time Monitoring agent. Using JaaScript, IBM HTTP Serer Response Time module inserts a header into web pages sered by an IBM HTTP Serer so that Response Time Monitoring can monitor those pages. To display client-side and network data, monitored web browsers must support JaaScript and W3C performance and naigation timing ( Embedded objects loaded by the page are tracked using cookies. Transaction information from web pages sered by IBM HTTP Serer is then included in End User Transactions dashboards. For example: End User Transactions workspace showing data collected from the IBM HTTP Serer Response Time module in the Transactions - Top 10: 148 IBM Monitoring: Installation and Setup Guide

155 End User Transactions workspace showing data collected from the IBM HTTP Serer Response Time module in the Subtransactions table IBM HTTP Serer Response Time module monitors the web serer port used by IBM HTTP Serer. Use either the IBM HTTP Serer Response Time module or Web Response Monitor (kfcm120) to monitor IBM HTTP Serer, not both. Note: Enhanced Resource Timing information, new in Fix Pack 8, is not aailable with IBM HTTP Serer Response Time module. If you require this information, use the Packet Analyzer to monitor IBM HTTP Serer. The following table shows the features aailable with the different monitors. Transactions Top 10 Packet Analyzer Response Time Monitoring with Client Time (JaaScript Instrumentation) IBM HTTP Serer Response Time module Chapter 6. Configuring your agents 149

156 Serer Time Render Time Breakdown AJAX Subtransactions Resource Timing data in Subtransactions table Transaction Instances (Top 10) Transaction Instance Topology Application Topology Packet Analyzer Response Time Monitoring with Client Time (JaaScript Instrumentation) N/A IBM HTTP Serer Response Time module Automatic instrumentation of JaaScript Injection N/A Supported ersions The IBM HTTP Serer Response Time module is aailable with Response Time Monitoring Agent V and later, for IBM HTTP Serer V8.0 and V8.5. IBM HTTP Serer Response Time module can be installed on the following operating systems: AIX V6.1 and later Red Hat Enterprise Linux V5.6 and later SUSE Linux Enterprise Serer V10 and later Installing IBM HTTP Serer Response Time module IBM HTTP Serer Response Time module is installed with the Response Time Monitoring agent in IBM Performance Management (SaaS) Fix Pack 8. To use IBM HTTP Serer Response Time module, you must first disable the Packet Analyzer used to monitor IBM HTTP Serer in earlier ersions. Enabling IBM HTTP Serer Response Time module To enable IBM HTTP Serer Response Time module to easily monitor the performance of HTTP pages and embedded objects for web pages sered by IBM HTTP Serer: 1. Disable the Packet Analyzer. Run $AGENT_HOME/bin/rt-agent.sh stop where $AGENT_HOME is /opt/ibm/apm/agent on Linux systems and /opt/ibm/ccm/agent on AIX systems 150 IBM Monitoring: Installation and Setup Guide

157 2. Load IBM HTTP Serer Response Time module into IBM HTTP Serer. Add the following LoadModule line to the web serer configuration file. If you hae installed the agent to a different location, substitute the installation path. LoadModule wrt_module/opt/ibm/ccm/agent/tmaitm6/wrm/modules/ mod_wrt.so LoadModule wrt_module/opt/ibm/apm/agent/tmaitm6/wrm/ modules/mod_wrt.so 3. Restart IBM HTTP Serer Response Time module. 4. Switch the Response Time Monitoring agent to process web plugin transactions and start without the Packet Analyzer. In $AGENT_HOME/config/hostname_t5.cfg, set the following parameters: KT5DISABLEANALYZER=YES KT5ENABLEWEBPLUGIN=YES 5. Restart the Response Time Monitoring agent. Disabling the IBM HTTP Serer Response Time module To disable the IBM HTTP Serer Response Time module, reconfigure the agent and turn IBM HTTP Serer Response Time module monitoring off: 1. Either: Reconfigure the agent interactiely, run $INSTALLPATH/bin/rt-agent.sh config Open $AGENT_HOME/config/hostname_t5.cfg 2. Set the following parameters: KT5DISABLEANALYZER=NO KT5ENABLEWEBPLUGIN=NO Configuring the Ruby agent The Monitoring Agent for Ruby is a multiple instance agent; you must create the first instance and start the agent manually. The following web serers are supported by Ruby agent: WEBrick, Thin, Puma, Unicorn, and Passenger. About this task For a typical enironment, in which you want to monitor all the Ruby on Rails applications on the system automatically, you do not hae to proide more configuration information other than the new instance name. For a typical enironment, configure the agent with the default settings. The Managed System Name includes the instance name that you specify, for example, instance_name:host_name:pc, where pc is your two character product code. The Managed System Name is limited to 32 characters. The instance name that you specify is limited to 28 characters, minus the length of your host name. For example, if you specify Ruby2 as your instance name, your managed system name is Ruby2:hostname:KM. Important: If you specify a long instance name, the Managed System name is truncated and the agent code does not display correctly. If you hae multiple Ruby runtimes installed on the system, you must specify the runtime to use to gather data from your Ruby applications. The chosen Ruby Chapter 6. Configuring your agents 151

158 runtime must be compatible with the ersion of Ruby on Rails that is used in the application. To specify the runtime to use, configure the agent with customized settings. If you prefer to monitor a subset of your Ruby applications, edit each Ruby application that you want to monitor separately. Procedure Complete these steps to configure the agent with the default settings: 1. To configure the agent, enter: install_dir/bin/ruby-agent.sh config instance_name install_dir/ samples/ruby_silent_config.txt Where instance_name is the name you want to gie to the instance, and install_dir is the installation directory of Ruby agent. The default installation directory is /opt/ibm/apm/agent. Before you run the config command, ensure that the ruby_silent_config.txt file, especially the KKM_RUBY_RUNTIME_BIN_LOCATION parameter, is correctly configured. The alue for the KKM_AUTO_DETECT_RUBY_APPLICATIONS parameter can be set as Y for only one agent instance. For other instances, set the alue as N. 2. To start the agent, enter: install_dir/bin/ruby-agent.sh start instance_name Complete these steps to configure the agent with customized settings: 1. To configure the agent, enter: install_dir/bin/ruby-agent.sh config instance_name Where instance_name is the name you want to gie to the instance, and install_dir is the installation directory of Ruby agent. The default installation directory is /opt/ibm/apm/agent. 2. When prompted to Edit Monitoring Agent for Ruby settings, enter 1 to continue. 3. When prompted for Ruby Runtime Bin Location, specify the binary directory. For example, /usr/local/rm/rubies/ruby p247/bin if you use Ruby Version Manager (RVM). 4. When prompted with Allow the Ruby agent to auto-detect all current running Ruby on Rails applications, enter Y to continue. Note: This function can be enabled on only one agent instance. When you configure other instances, enter N to disable this function and continue. 5. When prompted for Rails Application Serer, press Enter to accept the default of ruby or specify a name. 6. When prompted for Socket Data Source, press Enter to accept the default of 0 to use the ephemeral port. 7. When prompted to Edit 'Ruby_Application' settings, enter 5 to exit. 8. To start the agent, enter: install_dir/bin/ruby-agent.sh start instance_name Complete these steps to edit each Ruby application that you want to monitor separately: 1. To configure the agent, enter: install_dir/bin/ruby-agent.sh config instance_name Where instance_name is the name you want to gie to the instance, and install_dir is the installation directory of Ruby agent. The default installation directory is /opt/ibm/apm/agent. 152 IBM Monitoring: Installation and Setup Guide

159 2. When prompted to Edit Monitoring Agent for Ruby settings, enter 1 to continue. 3. When prompted for Ruby Runtime Bin Location, press Enter to continue. 4. When prompted with Allow the Ruby agent to auto-detect all current running Ruby on Rails applications, enter N to continue. 5. When prompted for Rails Application Serer, press Enter to accept the default of ruby or specify a name. 6. When prompted for Socket Data Source, press Enter to accept the default of 0 to use the ephemeral port. 7. When prompted to Edit 'Ruby_Application' settings, enter 1 to specify an application. 8. When prompted, enter the Ruby application name. 9. When prompted, enter the Ruby application home directory, for example: /root/ruby/myapp. 10. For the last prompt, Adanced (select a section to oerride alues), you can enter q to exit. 11. To start the agent, enter: install_dir/bin/ruby-agent.sh start instance_name Note: If you hae multiple Ruby runtimes installed and you want to monitor specific Ruby applications, you can set a runtime oerride on the Ruby application or subnode. As an example, assume that you hae two runtimes installed and four applications, three of which use one runtime and one of which uses the other runtime. In this case, set the runtime most commonly used at the agent leel, and set the runtime oerride for the application that uses a different runtime. Results You created a Ruby agent instance for one or more of your Ruby on Rails applications and started the monitoring agent to begin collecting data samples for resource monitoring. What to do next You must install the data collector for the Ruby agent to work properly. 1. Stop your Ruby on Rails application. 2. Optional: If you are upgrading the Ruby data collector to a new ersion, you must first uninstall the old ersion data collector by running the command: gem uninstall stacktracer. 3. Install the data collector. Enter gem install install_dir/lx8266/km/bin/ stacktracer-ersion.gem where ersion is the ersion number, and install_dir is the installation directory of Ruby agent. The default installation directory is /opt/ibm/apm/agent. Important: Install the data collector as the user you used to install and run the Ruby on Rails application. 4. Naigate to the home directory of your application, open its Gemfile, and add the following line to the end of the file: gem stacktracer, ersion Where ersion is the ersion number of the Ruby agent. Ensure that the ersion is correctly configured. For example, if you install Ruby agent Version 1.0 Fix Pack 8, the line is: gem stacktracer, Chapter 6. Configuring your agents 153

160 Note: If there is only one ersion of stacktracer in the enironment, add the line gem stacktracer to the end of the file. Do not specify the ersion number in the line. 5. In the home directory of your application, enter: bundle install 6. Restart your Ruby on Rails application. If you are not logged in, follow the instructions in Starting the Performance Management console on page 205. Click Performance > Application Performance Dashboard to open the All My Applications dashboard, and drill down to the Ruby App resource monitoring dashboards to obsere your Ruby on Rails applications from the status summary down to request and resource details. Configuring the Tomcat agent Before you begin Enable JMX remote for the monitored Tomcat serer. Set the port For instructions, see monitoring.html#enabling_jmx_remote. About this task The Tomcat agent is a multiple instance agent; you must create the first instance and start the agent manually. The Managed System Name includes the instance name that you specify, for example, instance_name:host_name:pc, where pc is your two character product code. The Managed System Name is limited to 32 characters. The instance name that you specify is limited to 28 characters, minus the length of your host name. For example, if you specify TOMCAT2 as your instance name, your managed system name is TOMCAT2:hostname:OT. If you specify a long instance name, the Managed System name is truncated and the agent code does not display correctly. Remember: Use the same root user or non-root user ID to configure the agent that was you used to install the agent. Procedure To configure the agent with the default settings, not responding to prompts, complete the following steps: 1. Enter: install_dir/bin/tomcat-agent.sh config instance_name install_dir/samples/tomcat_silent_config.txt where install_dir The installation directory of the Tomcat agent. instance_name The name you want to gie to the instance. 2. To start the agent, enter: install_dir/bin/tomcat-agent.sh start instance_name Remember: This configuration works when the following requirements are fulfilled: The agent is installed in the default directory. 154 IBM Monitoring: Installation and Setup Guide

161 The Tomcat serer uses the port The Tomcat serer is configured without JMX authorization. To configure the agent by editing the silent response file and running the script with no interaction, complete the following steps: 1. Open install_dir/samples/tomcat_silent_config.txt in a text editor. 2. For Jaa home, you can specify the path where the Jaa irtual machine is installed. The default location is /opt/ibm/apm/agent/jre/lx8266/jre. Ifthe agent is not installed in the default directory, specify install_dir/jre/ lx8266/jre. 3. For JMX user ID, you can specify the ID of the user that you are using to connect to the Tomcat MBean serer. This setting is required if JMX authorization is enabled in Tomcat. 4. For JMX password, you can specify the password of the JMX user. This setting is required if JMX authorization is enabled in Tomcat. 5. For JMX serice URL, you can specify the serice URL for connecting to the Tomcat MBean serer. The format of the URL is serice:jmx:rmi:///jndi/ rmi://host_name:port_number/jmxrmi. The default URL is alid if the serer is on the local host and uses the port You can modify the host name and the port number in the URL, keeping the same format. 6. Sae and close the tomcat_silent_config.txt file, then enter: install_dir/bin/tomcat-agent.sh config instance_name install_dir/samples/tomcat_silent_config.txt Where instance_name is the name that you want to gie to the instance. 7. To start the agent, enter: install_dir/bin/tomcat-agent.sh start instance_name To configure the agent by running the script and responding to prompts, complete the following steps: 1. Enter: install_dir/bin/tomcat-agent.sh config instance_name Where instance_name is the name you want to gie to the instance. 2. When prompted for SERVER, press Enter to accept the default serer name or specify your own serer name. 3. When prompted for Jaa home, press Enter to accept the default location where the Jaa irtual machine is installed. The default location is /opt/ibm/apm/agent/jre/lx8266/jre. If the agent is not installed in the default directory, specify install_dir/jre/lx8266/jre. 4. When prompted for JMX user ID, specify the ID of the user that you are using to connect to the Tomcat MBean serer. If JMX authorization is not enabled, press Enter. 5. When prompted for JMX password, specify the password of the JMX user and confirm it. If JMX authorization is not enabled, press Enter. 6. When prompted for JMX serice URL, press Enter to accept the URL or specify another serice URL for connecting to the Tomcat MBean serer. The format of the URL is serice:jmx:rmi:///jndi/rmi:// host_name:port_number/jmxrmi. The default URL is alid if the serer is on the local host and uses the port You can modify the host name and the port in the URL, keeping the same format. 7. To start the agent, enter: install_dir/bin/tomcat-agent.sh start instance_name Chapter 6. Configuring your agents 155

162 What to do next You can erify the Tomcat agent data is displayed in the Performance Management console. Configuring the VMware VI agent The Monitoring Agent for VMware VI monitors the VMware Virtual Infrastructure by connecting to the VMware Virtual Center. Use the agent-specific configuration information to configure the VMware VI agent. Before you begin 1. Reiew the hardware and software prerequisites. 2. Create a user ID in your VMware Virtual Infrastructure. Ensure that you hae the System.View and System.Read priileges on all the data source objects that are being monitored. 3. If the VMware VI agent is configured to communicate with its VMware VI data sources that are using the SSL agent, it is necessary to add the SSL certificate of the data source to the certificate truststore of the agent. For more information about enabling SSL communication with VMware VI data sources, see Enabling SSL communication with VMware VI data sources on page 159. About this task The VMware VI agent is a multiple instance agent. You must create the first instance, and start the agent manually. The configuration attributes define which VMware VI data sources are monitored. The attributes define a connection to VMware Virtual Center Multiple data sources can be defined for each VMware VI agent instance. More than one instance of the monitoring agent can be configured on a remote monitoring host system. One instance can monitor all VMware Virtual Infrastructure, or separate instances can be defined to monitor specific groups of VMware Virtual Infrastructure. Monitor the VMware Virtual Center that manages the VMware Virtual Infrastructure instead of managing indiidual ESX Serers. Run the configuration script to create an instance and change the configuration settings. Before you run the configuration script to bypass the prompts and responses that are required, you can edit the VMware VI agent silent response file. This mode of configuration is also known as configuring the agent by using the silent mode. Note: The VMware VI agent can be configured on Windows systems by using the silent mode only. Important: For more information about the additional configuration for VMware VI agent, see Increasing the Jaa heap size on page 160. Procedure To configure the VMware VI agent in silent mode, by editing the silent response file and running the script with no interaction, complete the following steps: 1. Open the mware_i_silent_config.txt file in a text editor. 156 IBM Monitoring: Installation and Setup Guide

163 The mware_i_silent_config.txt is aailable in the following paths: install_dir/samples/mware_i_silent_config.txt For example, /opt/ibm/apm/agent/samples/mware_i_silent_config.txt install_dir\samples\mware_i_silent_config.txt For example, C:\IBM\APM\samples\mware_i_silent_config.txt 2. In the mware_i_silent_config.txt file, complete the following tasks: For Validate SSL Certificates, uncomment the parameter KVM_SSL_VALIDATE_CERTIFICATES by remoing the # symbol at the beginning of the parameter, and set the alue to Yes if the agent is to alidate SSL certificates when using SSL to communicate oer the network. Set the alue to No if the agent is not to alidate SSL certificate. For more information about enabling SSL communication with VMware VI data sources, see Enabling SSL communication with VMware VI data sources on page 159. For Maximum Number of Data Proider Log Files, uncomment the parameter KVM_LOG_FILE_MAX_COUNT, and set the alue to the maximum number of log files the data proider produces before you oerwrite preious log files. For Maximum Size in KB of Each Data Proider Log, uncomment the parameter KVM_LOG_FILE_MAX_SIZE, and set the alue to the maximum size in KB that a data proider log file must reach before a new log file is created. For Leel of Detail in Data Proider Log, uncomment the parameter KVM_LOG_LEVEL, and set to the leel of logging required, usually set to INFO. The alid alues are OFF, SEVERE, WARNING, INFO, FINE, FINER, FINEST, and ALL. For IBM Systems Director Serer Address, leae the parameter KVM_DIRECTOR_HOST_ADDRESS commented. This parameter is not used by SaaS agent and would be ignored. For IBM Systems Director Serer Port Number, leae the parameter KVM_DIRECTOR_PORT_NUMBER commented. This parameter is not used by SaaS agent and would be ignored. For KVM_DIRECTOR_AUTHENTICATION, leae the parameter KVM_DIRECTOR_AUTHENTICATION commented. This parameter is not used by SaaS agent and would be ignored. For ITM MSN of Storage Agent, leae the parameter KVM_STORAGE_AGENT_MSN commented. This parameter is not used by SaaS agent and would be ignored. For Data Source Address, uncomment the parameter HOST_ADDRESS.datasource1. If the agent is not to alidate the SSL certificates, set the alue to the host name or IP address of the VMware Virtual Center or ESX serer that is being monitored. If the agent is to alidate the SSL certificates when using SSL to communicate oer the network, configure agent by using the Subject Alternatie Name that is proided in the certificate. To iew the Subject Alternatie Name of the data center, complete the following steps: a. Open the certificate. b. In the Certificate window, click the Details tab. Chapter 6. Configuring your agents 157

164 c. Select Subject Alternatie Name, and use the alue of DNS Name. For example, if the alue of DNS Name is ibmesx33c.itmfvs.com, then use the ibmesx33c.itmfvs.com alue for the host name. For Use SSL Connection to Data Source, uncomment the parameter USES_SSL.datasource1, and set the alue to Yes if the connection type to the data source is SSL connection. Set the alue to No if the connection type to the data source is not an SSL connection. For Data Source User ID, uncomment the parameter USERNAME.datasource1, and set the alue to the user ID that is known to the data source that has sufficient priileges to collect monitoring data. For Data Source Password, uncomment the parameter PASSWORD.datasource1, and set the alue to the password of the user ID that is configured for Data Source User ID. 3. Sae and close the mware_i_silent_config.txt file, and enter the following command: install_dir/bin/mware_i-agent.sh config instance_name install_dir/samples/mware_i_silent_config.txt Example: /opt/ibm/apm/agent/bin/mware_i-agent.sh config instance_name /opt/ibm/apm/agent/samples/ mware_i_silent_config.txt install_dir\bin\mware_i-agent.bat config instance_name install_dir\samples\mware_i_silent_config.txt Example: C:\IBM\APM\bin\ mware_i-agent.bat config instance_name C:\IBM\APM\samples\mware_i_silent_config.txt Where instance_name The name that you want to gie to the instance. install_dir The path where the agent is installed. Important: Ensure that you include the absolute path to the silent response file. Otherwise, the agent data is not shown in the dashboards. 4. To start the agent, enter the following command: install_dir/bin/mware_i-agent.sh start instance_name Example: /opt/ibm/apm/agent/bin/mware_i-agent.sh start instance_name install_dir\bin\mware_i-agent.bat start instance_name Example: C:\IBM\APM\bin\mware_i-agent.bat start instance_name To configure the agent by running the script and responding to prompts (only applicable for agent configuration on the Linux operating system), complete the following steps: 1. Enter the following command: install_dir/bin/mware_i-agent.sh config instance_name Example: /opt/ibm/apm/agent/bin/mware_i-agent.sh config instance_name Where instance_name The name that you want to gie to the instance. 158 IBM Monitoring: Installation and Setup Guide

165 install_dir The path where the agent is installed. 2. Respond to the prompts by using the descriptions of the parameters that are proided in Step 2 of the To configure the VMware VI agent in silent mode, by editing the silent response file and running the script with no interaction procedure. 3. To start the agent, enter the following command: install_dir/bin/mware_i-agent.sh start instance_name Example: /opt/ibm/apm/agent/bin/mware_i-agent.sh start instance_name Enabling SSL communication with VMware VI data sources The VMware VI agent can be configured to securely communicate with its VMware data sources by using SSL. In this configuration, you must add a data source SSL certificate to the certificate truststore of the agent. About this task Important: The following information applies only if the agent is configured to alidate SSL certificates. If SSL certificate alidation is turned off, the VMware VI agent connects to VMware data sources een if their SSL certificates are expired, untrusted, or inalid. Howeer, turning off SSL certificate alidation is potentially not secure and must be done with care. If a VMware data source uses an SSL certificate that is signed by a common Certificate Authority (for example, Verisign, Entrust, or Thawte), then it is not necessary to add certificates to the VMware VI agent certificate truststore. Howeer, if the data source uses a certificate that is not signed by a common Certificate Authority, as is the case by default, the certificate must be added to the truststore to allow the agent to successfully connect and collect data. Note: 1. The default VMware certificate file is named rui.crt. 2. For a Virtual Center, the SSL certificate file is located by default in the following path: C:\Documents and Settings\All Users\Application Data\VMware\VMware VirtualCenter\SSL 3. For an ESX serer, the SSL certificate file is located by default in the /etc/mware/ssl directory. Procedure 1. Copy the certificate file from your data source to the agent computer. 2. Place the certificate file in a directory of your choosing on the agent computer. Do not oerlay certificate files. Use unique file names for each certificate. Use a unique label for each certificate that you add. 3. Use the keytool command to add the data source certificate to the certificate truststore of the agent: keytool -import -noprompt -trustcacerts -alias CertificateAlias -file CertificateFile -keystore Truststore -storepass TruststorePassword Where CertificateAlias Chapter 6. Configuring your agents 159

166 A unique reference for each certificate added to the certificate truststore of the agent, for example, an appropriate alias for the certificate from datasource.example.com is datasource. CertificateFile The complete path and file name to the VMware data source certificate to add to the truststore. Truststore Complete path and file name to the VMware VI agent certificate database. Use the following path and file name: (64 bit): install_dir\tmaitm6_x64\km.truststore (64 bit): install_dir/lx8266/m/etc/km.truststore TruststorePassword ITMVMWAREVI is the default password for the VMware VI agent truststore. To change this password, consult the Jaa Runtime documentation for information about the tools to use. Important: To use the keytool command, the Jaa Runtime bin directory must be in your path. Use the following commands: (64 bit): set PATH=%PATH%;install_dir\jaa\jaa70_x64\jre\bin (64 bit): PATH="$PATH":/opt/ibm/apm/agent/JRE/lx8266/bin 4. After all data source certificates hae been added, you can start the monitoring agent. Increasing the Jaa heap size The default heap size for the Jaa data proider is 256 megabytes. In large VMware enironments, you might need to increase the heap size. If the Jaa data proider stops due to a jaacore problem, and creates a file that is named jaacore.date.time.number.txt in the CANDLEHOME\tmaitm6 directory, and this file contains the string jaa/lang/outofmemoryerror, then increase the heap size for the Jaa data proider. Use the heap size alue -Xmx2048m (2 GB) for enironments with around 100 ESX hosts, -Xmx4096m (4 GB) for enironments with around 250 ESX hosts and -Xmx8192m (8 GB) for enironments with around 500 ESX hosts. Procedure Complete the following steps to set a alue of 1 GB as heap size: 1. Open the %CANDLE_HOME%\TMAITM6_x64\km_data_proider.bat file. 2. Add the following line before the line that starts with KVM_JVM_ARGS="$KVM_CUSTOM_JVM_ARGS...: SET KVM_CUSTOM_JVM_ARGS=-Xmx1024m 3. Restart the agent. Complete the following steps to set a alue of 1 GB as heap size: 1. Open the $CANDLEHOME/lx8266/m/bin/km_data_proider.sh file. 2. Add the following line before the line that starts with KVM_JVM_ARGS="$KVM_CUSTOM_JVM_ARGS...: KVM_CUSTOM_JVM_ARGS=-Xmx1024m 3. Restart the agent. 160 IBM Monitoring: Installation and Setup Guide

167 Configuring the WebSphere Applications agent To monitor application serer instances, you must configure the data collector, a component of the agent. Before you begin If you installed the WebSphere Application Serer or WebSphere Portal Serer using a non-root user account, before you run the configuration utilities, erify that the non-root user has read and write priileges to the following agent directories in install_dir/yndchome/ , where install_dir is the installation directory of the WebSphere Applications agent: data bin runtime logs Proide read and write permissions using the chmod 777 command, if required. Also, log in as the user that was used to install the application serer. If you plan to monitor application serers within a cluster, erify that the cluster does not contain a white space. If you are configuring WebSphere Application Serer Liberty, make sure the JAVA_HOME enironment ariable points to the ersion of the JRE that is used by the application serer. About this task For the WebSphere Applications agent, the dc_home ariables refers to the home directory of the data collector. The location of the dc_home ariable on each platform is as follows: install_dir\dchome\ install_dir/yndchome/ To monitor WebSphere Portal Serer instances, use the adanced configuration procedure. For instructions, see Configuring and reconfiguring the data collector with the adanced utilities on page 163. Procedure To monitor WebSphere Application Serer instances, complete the basic configuration procedure: 1. Log in as the user that was used to install the application serer. 2. Change to the dc_home\bin directory on Windows systems or the dc_home/bin directory on Linux and AIX systems. 3. Run the simpleconfig command: Run the command simpleconfig.bat as the administrator who installed the WebSphere Application Serer. priileges. Run the./simpleconfig.sh command with root user Tip: If the wsadmin user was used to install the application serer, run the simpleconfig utility either as the wsadmin user or with root user priileges. Chapter 6. Configuring your agents 161

168 4. When prompted, select the application serer home directory or enter the full path to this directory. Important: To monitor WebSphere Application Serer Liberty, you must enter the full path to its home directory. The configuration utility can not detect the home directory for WebSphere Application Serer Liberty. 5. If prompted, select an application serer profile to monitor. For WebSphere Application Serer Liberty, if prompted, select an application serer instance to monitor. 6. If prompted, enter the user name and password for a WebSphere Application Serer console user with administrator priileges. 7. If possible, restart the application serer instance when the configuration utility exits. Full monitoring capabilities become aailable. If you do not restart the application serer instance, some metrics are displayed using Performance Monitoring Infrastructure (PMI) resource monitoring. If the monitoring user interface shows no information for the application serer instance, restart the monitoring agent component of the WebSphere Applications agent by completing the following steps: cd install_dir\bin was-agent.bat stop was-agent.bat start cd install_dir/bin./was-agent.sh stop./was-agent.sh start Results The data collector is configured to monitor the application serer instance. The data collector is configured within the serer instances, proiding maximum possible monitoring. Diagnostic data collection is enabled; howeer, to iew diagnostic data, you must hae diagnostic dashboard support in your monitoring infrastructure. Support for transaction tracking is enabled. To iew transaction tracking information, you must hae topology iews aailable in the Performance Management console. Also, you must enable transaction tracking in theagent Configuration page. Important: This basic process configures the data collector to monitor all instances in a profile, or, for WebSphere Application Serer Liberty, a single instance or multiple instances in the same directory. To monitor more profiles or instances, repeat the configuration. If you want to configure the data collector only for resource monitoring or to set additional options, use the adanced configuration procedure. For instructions, see Configuring and reconfiguring the data collector with the adanced utilities on page 163. If you want to change the name of the serer in the monitoring user interface or if, after configuring the data collector, you hae changed the administrator 162 IBM Monitoring: Installation and Setup Guide

169 password for the application serer console, reconfigure the data collector. For instructions, see Configuring and reconfiguring the data collector with the adanced utilities. Configuring and reconfiguring the data collector with the adanced utilities To set additional configuration options, you can use the adanced configuration utilities (interactie or silent) to configure the data collector instead of the standard utility. You can also use adanced utilities to reconfigure the data collector when it is already configured. Also, you need to use the adanced configuration utility to configure monitoring for WebSphere Portal Serer instances. You might need to use the adanced interactie or silent configuration utility if you want to use only resource monitoring. When the data collector is already configured to monitor an application serer instance, you can reconfigure it. You might need to reconfigure the data collector in the following cases: You want to change the name of the serer in the monitoring user interface, known as the serer alias. The administrator password for the application serer console is changed. You initially configured the data collector without enabling collection of diagnostic data, and then want to iew diagnostic data. (The simple configuration process does enable collection of diagnostic data, so this situation arises if you used the interactie or silent configuration utility). Run the configuration and reconfiguration utilities from the dc_home/bin directory. If the data collector is configured within the application serer instance, use the interactie reconfiguration script to reconfigure it. If the data collector is configured for resource monitoring, the reconfiguration script does not list the application serer instance; in this case, use the interactie configuration script. For silent reconfiguration, always use the same procedure as for silent configuration. If you installed the WebSphere Application Serer or WebSphere Portal Serer using a non-root user account, before you run the configuration utilities, erify that the non-root user has read and write priileges to the following agent directories in install_dir/yndchome/ where install_dir is the installation directory of the WebSphere Applications agent: data bin runtime logs Proide read and write permissions using the chmod 777 command, if required. Also, log in as the user that was used to install the application serer. If you plan to monitoring application serers within a cluster, erify that the cluster does not contain a white space. Chapter 6. Configuring your agents 163

170 Configuring the data collector interactiely You can use the interactie configuration utility (config.sh/bat) to configure the data collector for each application serer instance that you want to monitor. About this task If you already configured the data collector within an application serer and you want to reconfigure it, start the reconfig utility. Howeer, to reconfigure a data collector configured for resource monitoring, use the config utility. Procedure To configure the data collector by responding to prompts, complete these steps: 1. Naigate to the DC_home\bin directory. 2. Optionally, set the location of the Jaa home directory before you start the utility. For example: export JAVA_HOME=/opt/IBM/AppSerer80/jaa set JAVA_HOME=C:\Progra~1\IBM\WebSphere\AppSerer80\jaa Important: If you are configuring monitoring for WebSphere Application Serer Liberty, you must use the same JVM ersion as the one used for the application serer. Otherwise, the monitoring might fail. 3. Start the script. Run the command config.sh with root user priilege. Tip: If the wsadmin user was used to install the application serer, run the utility either as the wsadmin user or with root user priileges. Run the command config.bat as the administrator who installed the WebSphere Application Serer. 4. The utility displays the IP addresses of all network cards that are found on the local computer system. Enter the number that corresponds to the IP address to use. 5. The utility displays the WebSphere Application Serer home directories on the computer system. Enter the number that corresponds to a WebSphere Application Serer home directory or a full path to an application serer home directory. Important: The utility cannot find the directory for a WebSphere Application Serer Liberty installation automatically. To monitor WebSphere Application Serer Liberty, enter the full path to the WebSphere Application Serer Liberty home directory, for example /home/user/wlp. 6. The utility displays all profiles under the specified home directory. Enter the number that corresponds to the WebSphere Application Serer profile that you want to configure. 7. The utility indicates whether WebSphere Global Security is enabled for the WebSphere Application profile that you specified. If global security is not enabled, or if you are configuring the data collector for a WebSphere Application Serer Liberty instance, skip to step 9 on page Specify whether to retriee security settings from a client properties file. Enter 1 to allow the utility to retriee the user name and password from the appropriate client properties file. Otherwise, enter 2 to enter the user name and password. 164 IBM Monitoring: Installation and Setup Guide

171 The data collector communicates with the WebSphere Administratie Serices using the Remote Method Inocation (RMI) or the Simple Object Access Protocol (SOAP) protocol. If global security is enabled for a profile, you must specify the user ID and password of a user who is authorized to log in to the IBM WebSphere Application Serer administratie console for the profile. Alternatiely, you can encrypt the user name and password and store them in client properties files before configuring the data collector. You must use the sas.client.props file for an RMI connection, or the soap.client.props file for an SOAP connection. 9. The utility displays all application serer instances that are not configured yet for data collection and all serer instances that are configured to use the current ersion of the data collector. Select one or more application serer instances from the list. Remember: For a stand-alone enironment, application serer instances must be running during the configuration. (A WebSphere Application Serer Liberty instance does not need to be running). For a Network Deployment enironment, the Node Agent and Deployment Manager must be running. Ensure that the application serer instances that you select are the actual serers that host the applications or serices that you want to monitor. Enter the number that corresponds to the application serer instance to configure for data collection or enter an asterisk (*) to configure all application serer instances for data collection. To specify a subset of serers, enter the numbers, separated by commas, that represent the serers. For example: 1,2, Specify that you do not want to integrate the data collector with ITCAM for SOA. Enter 2 for no. 11. Specify that you want to integrate the data collector with the ITCAM Agent for WebSphere Applications. Enter 1 for yes. The selected serer will be registered for resource (PMI) monitoring. This monitoring option proides limited metrics and works only with Monitoring Agent for WebSphere Applications, but does not require restarting the application serer and can not affect performance. Important: You must select this integration option. 12. Specify whether you want to configure the data collector within the application serer instance. Configuring the data collector within the serer instance is required for the full range of operational monitoring and diagnostics data collection. Howeer, configuring the data collector within the application serer requires restarting the application serer. Also, the data collector might affect serer performance. Enter 1 to configure the data collector within the application serer. Otherwise, enter 2 and skip to step 16 on page Specify whether to enable support for the collection of diagnostics data in the data collector. To enable support for diagnostics data, enter You are prompted for the host name of the monitoring agent component of the Monitoring Agent for WebSphere Applications. The monitoring agent is on the local host, so you do not hae to change the default. 15. You are prompted for the port number of the monitoring agent. Press Enter; do not change the default alue. Chapter 6. Configuring your agents 165

172 16. Enter the serer alias. The alias is the name of the node in the monitoring user interface that contains the monitoring information for this application serer instance. The default is the node name combined with the serer name. Accept the default or enter another alias. If you are configuring seeral application serer instances, the utility prompts you for an alias for eery instance. Important: The alias can contain only the following characters: A-Z, a-z, underbar (_), dash (-), and period (.). Do not use other characters in the alias. 17. Enter a TCP/IP port number for resource monitoring. The port is used for internal communication between components running on the same host. The default port is 63355; if this port is in use, you can set a different number. Enter a new number or press Enter to accept the default. 18. Specify that you do not want to integrate the data collector with a Managing Serer. Enter 2 for no. 19. Specify whether to enable support for transaction tracking. Enter 1 to enable support for transaction tracking. Otherwise, enter 2 and skip to step 23. To iew transaction tracking information, you need to hae topology iews aailable in the Performance Management console and to enable transaction tracking in the agent configuration window of the console. 20. Accept the default the host name or IP address of the Transaction Framework Extension, which is the component of the Monitoring Agent for WebSphere Applications that gathers metrics from the data collector. 21. Accept the default port number that the data collector uses to connect to the Transaction Framework Extension. 22. Specify that you do not want to integrate with Tioli Performance Viewer. Enter 2 for no. 23. Specify whether to integrate the data collector with Application Performance Diagnostics Lite. Application Performance Diagnostics Lite is a tool for diagnostic inestigation of applications running on WebSphere Application Serer and WebSphere Portal Serer. Using this tool, you can analyze data in real time or you can sae diagnostic information to a file for later analysis. For more information about installing and using Application Performance Diagnostics Lite, see the Application Performance Diagnostics Lite product documentation. Enter 1 to integrate the data collector with the Application Performance Diagnostics Lite. Otherwise, enter 2. Important: If you hae enabled collection of diagnostic data for Application Performance Diagnostics, the data collector is also configured to support Application Performance Diagnostics lite. In this case the configuration utility skips this prompt. Application performance Diagnostics Lite (in lie connection mode) is not supported for WebSphere Application Serer Liberty. 24. Specify whether to change the garbage collection log path. Enter 1 to select a garbage collection log path. Otherwise, enter 2 and skip to step 26 on page Specify the garbage collection log path. Enter a file name with its full path. The data collector automatically modifies the log file name, adding the serer instance information to it. For example, if you specify gc.log as the file name, 166 IBM Monitoring: Installation and Setup Guide

173 the actual name is set to profile_name.cell_name.node_name.serer_name.gc.log for eery configured application serer instance. Important: In the garbage collection log path, you can use WebSphere ariables such as ${SERVER_LOG_ROOT}. Howeer, do not use templates, such as %pid. For WebSphere Application Serer Liberty, do not use ariables in the path. 26. Reiew the summary of the data collector configuration that is to be applied to the specified application serer instances. Reconfigure parts of the data collector configuration before applying the changes, if required. 27. Enter a to accept your changes. 28. Specify whether you want to create a backup of your current WebSphere Application Serer configuration. Enter 1 to create a backup of the current configuration. Otherwise, enter 2. Tip: If you are configuring PMI resource monitoring, this prompt is skipped. What to do next After configuring the data collector to monitor application serer instances, if you hae enabled the data collector within the application serer, you must restart the instances as directed by the utility. The data collector configuration takes effect when the application serer instances are restarted. If you hae enabled PMI resource monitoring without enabling the data collector within the application serer, you might need to restart the monitoring agent component of the Monitoring Agent for WebSphere Applications to start the monitoring. If monitoring data is not aailable immediately, restart the monitoring agent by running the following commands: cd install_dir\bin was-agent.bat stop was-agent.bat start cd install_dir/bin./was-agent.sh stop./was-agent.sh start Reconfiguring the data collector interactiely If you configured the data collector to monitor one or more application serer instances, you can reconfigure the data collector using the reconfiguration utility (reconfig.sh/bat). About this task If PMI resource monitoring is used for an application serer instance and the data collector is not set up to integrate with any other product, reconfiguration is not aailable for the instance. Use the configuration utility to configure the data collector for it. Tip: In the prompts asking for agent configuration settings, the utility offers the currently configured alues as defaults. Chapter 6. Configuring your agents 167

174 Important: Do not use the reconfiguration utility to change settings for a WebSphere Portal serer. Instead, use the configuration utility (config.sh/bat). This utility warns that the serer is already configured, but still makes any required changes. Procedure To reconfigure the data collector by responding to prompts, complete these steps: 1. Naigate to the dc_home\bin directory. 2. Optionally, set the location of the Jaa home directory before you start the utility. For example: export JAVA_HOME=/opt/IBM/AppSerer80/jaa set JAVA_HOME=C:\Progra~1\IBM\WebSphere\AppSerer80\jaa Important: If you are configuring monitoring for WebSphere Application Serer Liberty, you must use the same JVM ersion as the one used for the application serer. Otherwise, the monitoring might fail. 3. Start the script. priilege. Run the command reconfig.sh with root user Tip: If the wsadmin user was used to install the application serer, run the utility either as the wsadmin user or with root user priileges. Run the command reconfig.bat as the administrator who installed the WebSphere Application Serer.Running this utility has the same effect as running the config.bat script with the -reconfig argument on Windows systems or the config.sh script with the -reconfig argument on Linux or AIX systems. 4. The utility displays the IP addresses of all network cards that are found on the local computer system. Enter the number that corresponds to the IP address to use. 5. The utility displays all application serer instances for which the data collector is configured on this host, and prompts you to select one or more application serer instances from the list. Select one or more application serer instances from the list. Remember: For a stand-alone enironment, application serer instances must be running during the configuration. For a Network Deployment enironment, the Node Agent and Deployment Manager must be running. Ensure that the application serer instances that you select are the actual serers that host the applications or serices that you want to monitor. Enter the number that corresponds to the application serer instance to reconfigure for data collection or enter an asterisk (*) to reconfigure all application serer instances for data collection. To specify a subset of serers, enter the numbers, separated by commas, that represent the serers. For example: 1,2,3 6. Specify that you do not want to integrate the data collector with ITCAM for SOA. Enter 2 for no. 168 IBM Monitoring: Installation and Setup Guide

175 7. Specify that you want to integrate the data collector with the ITCAM Agent for WebSphere Applications. Enter 1 for yes. The selected serer will be registered for resource (PMI) monitoring. This monitoring option proides limited metrics and works only with Monitoring Agent for WebSphere Applications, but does not require restarting the application serer and can not affect performance. Important: You must select this integration option. 8. Specify whether you want to configure the data collector within the application serer instance. Configuring the data collector within the serer instance is required for the full range of operational monitoring and diagnostics data collection. Howeer, configuring the data collector within the application serer requires restarting the application serer. Also, the data collector might affect serer performance. Enter 1 to configure the data collector within the application serer. Otherwise, enter 2 and skip to step Specify whether to enable support for the collection of diagnostics data in the data collector. To enable support for diagnostics data, enter You are prompted for the host name of the monitoring agent component of the Monitoring Agent for WebSphere Applications. The monitoring agent is on the local host, so you do not hae to change the default. 11. You are prompted for the port number of the monitoring agent. Press Enter; do not change the default alue. 12. Enter the serer alias. The alias is the name of the node in the monitoring user interface that contains the monitoring information for this application serer instance. The default is the node name combined with the serer name. Accept the default or enter another alias. If you are configuring seeral application serer instances, the utility prompts you for an alias for eery instance. Important: The alias can contain only the following characters: A-Z, a-z, underbar (_), dash (-), and period (.). Do not use other characters in the alias. 13. Enter a TCP/IP port number for resource monitoring. The port is used for internal communication between components running on the same host. The default port is 63355; if this port is in use, you can set a different number. Enter a new number or press Enter to accept the default. 14. Specify that you do not want to integrate the data collector with a Managing Serer. Enter 2 for no. 15. Specify whether to enable support for transaction tracking. Enter 1 to enable support for transaction tracking. Otherwise, enter 2 and skip to step 19 on page 170. To iew transaction tracking information, you need to hae topology iews aailable in the Performance Management console and to enable transaction tracking in the agent configuration window of the console. 16. Accept the default the host name or IP address of the Transaction Framework Extension, which is the component of the Monitoring Agent for WebSphere Applications that gathers metrics from the data collector. 17. Accept the default port number that the data collector uses to connect to the Transaction Framework Extension. 18. Specify that you do not want to integrate with Tioli Performance Viewer. Enter 2 for no. Chapter 6. Configuring your agents 169

176 19. Specify whether to integrate the data collector with Application Performance Diagnostics Lite. Application Performance Diagnostics Lite is a tool for diagnostic inestigation of applications running on WebSphere Application Serer and WebSphere Portal Serer. Using this tool, you can analyze data in real time or you can sae diagnostic information to a file for later analysis. For more information about installing and using Application Performance Diagnostics Lite, see the Application Performance Diagnostics Lite product documentation. Enter 1 to integrate the data collector with the Application Performance Diagnostics Lite. Otherwise, enter 2. Important: If you hae enabled collection of diagnostic data for Application Performance Diagnostics, the data collector is also configured to support Application Performance Diagnostics lite. In this case the configuration utility skips this prompt. Application Performance Diagnostics Lite (in lie connection mode) is not supported for WebSphere Application Serer Liberty. 20. Specify whether to change the garbage collection log path. Enter 1 to select a garbage collection log path. Otherwise, enter 2 and skip to step Specify the garbage collection log path. Enter a file name with its full path. The data collector automatically modifies the log file name, adding the serer instance information to it. For example, if you specify gc.log as the file name, the actual name is set to profile_name.cell_name.node_name.serer_name.gc.log for eery configured application serer instance. Important: In the garbage collection log path, you can use WebSphere ariables such as ${SERVER_LOG_ROOT}. Howeer, do not use templates, such as %pid. For WebSphere Application Serer Liberty, do not use ariables in the path. 22. Reiew the summary of the data collector configuration that is to be applied to the specified application serer instances. Reconfigure parts of the data collector configuration before applying the changes, if required. 23. Enter a to accept your changes. 24. Specify whether you want to create a backup of your current WebSphere Application Serer configuration. Enter 1 to create a backup of the current configuration. Otherwise, enter 2. Tip: If you are configuring PMI resource monitoring, this prompt is skipped. What to do next After reconfiguring the data collector to monitor application serer instances, you must restart the instances as directed by the utility. The data collector configuration takes effect when the application serer instances are restarted. Configuring or reconfiguring the data collector in silent mode If you want to configure or reconfigure many application serer instances, it might be more conenient to configure the data collector in silent mode. Use the same procedure for configuration and reconfiguration. 170 IBM Monitoring: Installation and Setup Guide

177 When you configure the data collector in silent mode, you first specify configuration options in a properties file. A sample properties file, sample_silent_config.txt, is packaged with the configuration utility. The file is aailable in the following directories: dc_home\bin dc_home/bin The DC_home ariable is the location where the data collector is installed. Complete the following steps to perform a silent configuration: 1. Specify configuration options in the properties file. You can copy the sample properties file and change the required options. 2. Set the location of the Jaa home directory before you run the utility. For example: set JAVA_HOME=C:\Progra~1\IBM\WebSphere\AppSerer80\jaa export JAVA_HOME=/opt/IBM/AppSerer80/jaa Important: If you are configuring monitoring for WebSphere Application Serer Liberty, you must use same JVM ersion as the one used for the application serer. Otherwise, the monitoring might fail. 3. Go to the following directory: dc_home\bin dc_home/bin 4. Run the command to configure the data collector in silent mode. Run the following command as the administrator who installed the WebSphere Application Serer. config.bat -silent [dir_path]\silent file Run the following command with root user priileges. config.sh -silent [dir_path]/silent file Tip: If the wsadmin user was used to install the application serer, run the config utility either as the wsadmin user or with root user priileges. 5. After configuring the data collector to monitor application serer instances, if you hae enabled the data collector within the application serer, you must restart the instances. The data collector configuration takes effect when the application serer instances are restarted. If you hae enabled PMI resource monitoring without enabling the data collector within the application serer, you might need to restart the monitoring agent component of the Agent for WebSphere Applications to start the monitoring. If monitoring data is not aailable immediately, restart the monitoring agent by running the following commands: 6. cd install_dir\bin was-agent.bat stop was-agent.bat start 7. Chapter 6. Configuring your agents 171

178 cd install_dir/bin./was-agent.sh stop./was-agent.sh start Properties file When you create your properties file, keep in mind the following considerations: A line in the file that starts with a number sign (#) is treated as a comment, and is not processed. If the number sign is used elsewhere in the line, it is not considered to be the start of a comment. Each property is described on a separate line, in the following format: property = alue. property Name of property. The list of alid properties that you can configure is shown in Table 17. alue Value of the property. Default alues for some properties are already proided. You can delete default alues to leae property alues blank or empty. An empty alue is treated as if the property is not specified, as opposed to using the default alue. If you want to use default alues, you can comment out the property in the file. Passwords are in plain text. Properties and their alues are case-sensitie. Table 17 describes the properties that are aailable when configuring the data collector in silent mode. Important: If you are configuring the data collector for a WebSphere Application Serer Liberty instance, some of the properties are not used. Table 17. Aailable properties for running the configuration utility in silent mode Property Comment default.hostip If the computer system uses multiple IP addresses, specify the IP address for the data collector to use. Integration of the data collector with the ITCAM for Application Diagnostics Managing Serer Important: The Managing Serer is only aailable if you hae ITCAM for Application Diagnostics. For a WebSphere Application Serer Liberty instance or in a Performance Management (SaaS) enironment, these properties are not used. ms.connect ms.kernel.host ms.kernel.codebase.port ms.am.home ms.am.socket.bindip ms.firewall.enabled Specifies whether the data collector is configured to connect to the managing serer in an ITCAM for Application Diagnostics enironment. Valid alues are True and False. Specifies the fully qualified host name of the managing serer. Specifies the codebase port on which the managing serer is listening. Specifies the managing serer home directory. Specifies the IP address or host name to be used by the data collector to communicate with the managing serer. If more than one network interface or IP address is configured on data collector computer system, choose one of them. Specifies whether a firewall is enabled on the data collector host or you hae special requirements to change the RMI ports for the data collector. Valid alues are True and False. 172 IBM Monitoring: Installation and Setup Guide

179 Table 17. Aailable properties for running the configuration utility in silent mode (continued) Property Comment ms.probe.controller.rmi.port If the data collector is behind a firewall or you hae special requirements to change the Controller RMI port of data collector, set this port number range. Configure this port number as permitted by the firewall for the data collector host. For example: ms.probe.controller.rmi.port= or ms.probe.controller.rmi.port=8300. ms.probe.rmi.port If the data collector is behind a firewall, or you hae special requirements to change the RMI port of data collector, set this port number range. Configure this port number as permitted by the firewall for the data collector host. For example: ms.probe.rmi.port= or ms.probe.rmi.port=8200. Support for transaction tracking To iew transaction tracking information, you need to hae topology iews aailable in the Performance Management console and to enable transaction tracking in the agent configuration window. ttapi.enable Specifies whether the data collector supports transaction tracking. Valid alues are True and False. ttapi.host Specifies the host of the Transaction Framework Extension, which is the component of the Monitoring Agent for WebSphere Applications that gathers metrics from the data collector. use the local host alue, ttapi.port Specifies the port of the Transaction Framework Extension. Use Integration of the data collector with ITCAM for SOA Important: For a WebSphere Application Serer Liberty instance or in a Performance Management (SaaS) enironment, this property is not used. soa.enable Specifies whether to integrate the data collector with ITCAM for SOA. The ITCAM for SOA agent must be installed to complete the configuration. Integration of the data collector with the Tioli Performance Monitoring Important: For a WebSphere Application Serer Liberty instance or in a Performance Management (SaaS) enironment, this property is not used. tp.enable Specifies whether to integrate the data collector with the Tioli Performance Monitoring when the data collector is included as part of ITCAM for WebSphere Application Serer ersion 8.5. Tioli Performance Monitoring is accessed with the WebSphere Application Serer administratie console. Valid alues are True and False. Integration of the data collector with Application Performance Diagnostics Lite Important: For a WebSphere Application Serer Liberty instance, this property is not used. de.enable Specifies whether to collect diagnostics data, required for Application Performance Diagnostics and Application Performance Diagnostics Lite. Enable this integration if you hae Application Performance Diagnostics or might hae it in the future. Valid alues are True and False. Application Performance Diagnostics Lite is a tool for diagnostic inestigation of applications running on WebSphere Application Serer and WebSphere Portal Serer. Using this tool, you can analyze data in real time or you can sae diagnostic information to a file for later analysis. PMI resource and data collector monitoring The selected serer is always configured for resource (PMI) monitoring, without any changes to the application serer. This monitoring option proides limited metrics and works only with ITCAM Agent for WebSphere Applications, but does not require restarting the application serer and can not affect performance. Chapter 6. Configuring your agents 173

180 Table 17. Aailable properties for running the configuration utility in silent mode (continued) Property Comment tema.appserer Specifies whether you want to configure the data collector within the application serer instance. The data collector is required for the full range of metrics in ITCAM Agent for WebSphere Applications and for integration with any other products. Howeer, configuring the data collector requires restarting the application serer. Also, the data collector might affect serer performance. Valid alues are True and False. If this parameter is set to False, data collector configuration parameters for integrating with products other than ITCAM Agent for WebSphere Applications are disregarded. jmx.admin.port TCP/IP port number for resource monitoring. The port is used for internal communication between components running on the same host. The default port is 63355; if this port is in use, you can set a different number. Integration of the data collector with the Monitoring Agent for WebSphere Applications monitoring agent and with Application Performance Diagnostics Lite tema.connect Specifies whether the data collector connects to the Agent for WebSphere Applications monitoring agent. Valid alues are True and False. Important: You must use the True alue to use the Agent for WebSphere Applications tema.appserer Specifies whether you want to configure the data collector within the application serer instance. This configuration required for the full range of metrics in the Agent for WebSphere Applications and for integration with any other products. Howeer, it requires restarting the application serer. Also, the data collector might affect serer performance. Valid alues are True and False. jmx.admin.port tema.host tema.port de.enable If this parameter is set to False, data collector configuration parameters for integrating with products other than ITCAM Agent for WebSphere Applications are disregarded, as well as the tema.host and tema.port parameters. TCP/IP port number for resource monitoring. The port is used for internal communication between components running on the same host. The default port is 63355; if this port is in use, you can set a different number. Specifies the fully qualified host name or IP address of the ITCAM Agent for WebSphere Applications monitoring agent. Us ethe local host address ( ). Specifies the port number of the ITCAM Agent for WebSphere Applications monitoring agent. Do not change the default alue of Specifies whether to collect diagnostics data, required for Application Performance Diagnostics and Application Performance Diagnostics Lite. Valid alues are True and False. Enable this integration if you hae Application Performance Diagnostics or might hae it in the future. In this case, collection of diagnostic data is enabled at serer startup. Otherwise, it is disabled at startup; you can enable it using the Agent Configuration page in the user interface, but if the serer is restarted, collection of diagnostic data is disabled again. was.backup.configuration was.backup.configuration.dir This setting also enables integration with Application Performance Diagnostics Lite, a tool for diagnostic inestigation of applications running on WebSphere Application Serer and WebSphere Portal Serer. Using this tool, you can analyze data in real time or you can sae diagnostic information to a file for later analysis. WebSphere Application Serer backup Specifies whether to back up the current configuration of the WebSphere Application Serer configuration before applying the new configuration. Valid alues are True and False. Specifies the location of the backup directory. Adanced configuration settings 174 IBM Monitoring: Installation and Setup Guide

181 Table 17. Aailable properties for running the configuration utility in silent mode (continued) Property Comment was.gc.custom.path Specifies whether to set a custom path for the Garbage Collection log. was.gc.file Specifies the path to the custom Garbage Collection log. Set this alue to a file name with its full path. The data collector automatically modifies the log file name, adding the serer instance information to it. For example, if you specify gc.log as the file name, the actual name is set to profile_name.cell_name.node_name.serer_name.gc.log for eery configured application serer instance. Important: In the Garbage Collection log path, you can use WebSphere ariables, such as ${SERVER_LOG_ROOT}. Howeer, do not use templates, such as %pid. WebSphere Application Serer connection settings was.wsadmin.connection.host Specifies the name of the host to which the wsadmin tool is connecting. In a Network Deployment enironment, specify the wsadmin connection to the Deployment Manger. In a stand-alone enironment, specify the wsadmin connection to the serer. was.wsadmin.connection.type Specifies the connection protocol for the wsadmin tool to use. was.wsadmin.connection.port Specifies the port that the wsadmin tool must use to connect to the WebSphere Application Serer. WebSphere Application Serer global security settings was.wsadmin.username Specifies the user ID of a user who is authorized to log in to the IBM WebSphere Application Serer administratie console. This user must hae the agent role on the application serer. was.wsadmin.password Specifies the password that corresponds to the user specified in the was.wsadmin.username property. was.client.props Specifies whether to retriee security settings from a client properties file. Possible alues are True and False. WebSphere Application Serer settings was.appserer.profile.name Specifies the name of the application serer profile that you want to configure. Not used for WebSphere Application Serer Liberty. was.appserer.home Specifies the WebSphere Application Serer home directory. was.appserer.cell.name Specifies the WebSphere Application Serer cell name. Not used for WebSphere Application Serer Liberty. was.appserer.node.name Specifies the WebSphere Application Serer node name. Not used for WebSphere Application Serer Liberty. WebSphere Application Serer runtime instance settings was.appserer.serer.name Specifies the application serer instance within the application serer profile to configure. Tip: The silent response file can hae multiple instances of this property When adding a second serer, uncomment the second serer (this is, #[SERVER]) and add the serer name. tema.sereralias Specifies the name of the node in monitoring user interface that contains the monitoring information for this application serer instance. The default is the node name combined with the serer name. Important: The alias can contain only the following characters: A-Z, a-z, underbar (_), dash (-), and period (.). Do not use other characters in the alias. Tip: The silent response file can hae multiple instances of this property. Chapter 6. Configuring your agents 175

182 Additional data collector settings You can modify data collector configuration files to change additional monitoring settings. Properties files for the Data Collector Seeral properties files control data collector configuration and behaior. The properties files, and other files that are used by the data collector, are located under the data collector home directory (dc_home). The location of the dc_home ariable on each platform is as follows: install_dir\dchome\dc_ersion install_dir/yndchome/dc_ersion where install_dir is the installation directory of the WebSphere Applications agent. For most common changes to this configuration, you must edit the data collector properties file and the toolkit properties file. To change the configuration for collecting detailed diagnostic information, change the gdc.properties file. For details about this file, see Configuring collection of detailed diagnostic information on page 184. Important: After changing a configuration file, restart the monitored application serer instance. Then the changes will take effect. The Data Collector properties file Each application serer instance that is monitored by the data collector has its own properties file. The data collector automatically creates the properties file. The name of the file is dc_home/runtime/ appserer_ersion.node_name.profile_name.serer_name/ datacollector.properties. Howeer, to facilitate future upgrades, do not change this file. Instead, add the settings that you want to modify to the data collector custom properties file. This file is named dc_home/runtime/ app_serer_ersion.node_name.profile_name.serer_name/custom/ datacollector_custom.properties. Settings in the data collector custom properties file oerride the alues that are in the data collector properties file. Important: If the dc_home/runtime/ app_serer_ersion.node_name.profile_name.serer_name/custom/ datacollector_custom.properties file does not exist, create it when you want to make changes. You might also hae to create the custom directory. The toolkit properties file The toolkit properties file is automatically created by the data collector at startup, using arious input files. It is unique for eery application serer instance monitored by the data collector. Its name is dc_home/runtime/ appserer_ersion.node_name.profile_name.serer_name/toolkit.properties. Because this file is re-created at each data collector startup, do not make any changes to this file; if you do, they will be oerwritten. 176 IBM Monitoring: Installation and Setup Guide

183 Instead, add the settings that you want to modify to the toolkit custom properties file. This file is named dc_home/runtime/ app_serer_ersion.node_name.profile_name.serer_name/custom/ toolkit_custom.properties. Settings in the toolkit custom properties file oerride the alues in the toolkit properties file. You can also set toolkit properties for all the application serer instances that are monitored by this installation of the data collector. To do this, add the settings to the global toolkit custom properties file: dc_home/runtime/custom/ toolkit_global_custom.properties. Howeer, if a property is set in the instance-specific toolkit_custom.properties file, it oerrides the alue in the global file for this instance. Important: If the dc_home/runtime/ app_serer_ersion.node_name.profile_name.serer_name/custom/ toolkit_custom.properties or dc_home/runtime/custom/ toolkit_custom.properties file does not exist, create it when you want to make changes. You might also hae to create the custom directory. Other properties files The following properties files are unique for eery application serer instance monitored by the data collector: dc_home/runtime/appserer_ersion.node_name.profile_name.serer_name/ custom/gdc/gdc_custom.properties defines the details for collecting diagnostic and method trace data. For information about changing this file, see Configuring collection of detailed diagnostic information on page 184. dc_home/runtime/app_serer_ersion.node_name.profile_name.serer_name/ cynlogging.properties defines the log file names and logging details for the Jaa portion of the data collector. dc_home/runtime/app_serer_ersion.node_name.profile_name.serer_name/ cyn-cclog.properties defines the log file names and logging details for the C++ portion of the data collector. dc_home/runtime/appserer_ersion.node_name.serer_name/kwjdc.properties defines communication with the monitoring agent, including the host name and port for the monitoring agent host. Data collector log files The default location for the log files generated by the data collector configuration utility is dc_home\data dc_home/data The following table describes log files generated before and during the configuration process Table 18. Log files generated before and during the configuration process Full path name dc_home/data/config-console.log dc_home/data/config-message.log Description User input while the config or reconfig script is running. Messages generated while the config or reconfig script is running. Chapter 6. Configuring your agents 177

184 Table 18. Log files generated before and during the configuration process (continued) Full path name dc_home/data/config-trace.log dc_home/data/reconfig.log dc_home/data/unconfig-console.log dc_home/data/unconfig-message.log dc_home/data/unconfig-trace.log dc_home/data/ profile.cell.node.configdatacollector.log For example: default.beta85.tt6080. configdatacollector.log dc_home/data/ profile.cell.node.unconfigdatacollector.log For example: default.beta85.tt6080. unconfigdatacollector.log dc_home/data/profile.findserers.log For example: default.findserers.log dc_home/data/node.serer_alcheck.log For example: tt6080_rd-test_alcheck.log Description Debug messages generate while the config or reconfig script is running. Log written during the reconfiguration of data collector for application serers. User input while the unconfig script is running. Messages generated while the unconfig script is running. Debug messages generated while the unconfig script is running. Log written by the wsadmin script (configdatacollector.py) during configuration updates to WebSphere Application Serer. Log written by the wsadmin script (unconfigdatacollector.py ) during unconfiguration updates to WebSphere Application Serer. Log generated by findserers.py. The file is used for diagnosing problems with the find serers process. Log generated by WebSphere Application Serer alidity checking. The data collector trace files are stored by default in the following locations: dc_home\logs\cyn\logs. dc_home/logs/cyn/logs. Restriction: For log and trace file names that include profile, cell, node, or serer ariables, when any of these ariables includes non-ascii characters, the non-ascii characters are conerted to ascii characters. Disabling arious types of Byte Code Instrumentation for JEE APIs In Byte Code Instrumentation (BCI), the data collector intercepts method entry and exit calls for arious types of Jaa Platform Enterprise Edition (JEE) APIs in order to create an execution flow of each application request. Some resources are used for the monitoring. You can tune the data collector so that some of the APIs are not monitored, reducing resource use. To disable BCI monitoring for JEE APIs, add the following properties to the toolkit custom properties file. For more information about this file, see The toolkit properties file on page 176. Table 19. Adding lines to the toolkit custom properties file Type of JEE API Enterprise JaaBeans (EJB) Line to add to toolkit_custom.properties file com.ibm.tioli.itcam.toolkit.ai.enableejb=false 178 IBM Monitoring: Installation and Setup Guide

185 Table 19. Adding lines to the toolkit custom properties file (continued) Type of JEE API Line to add to toolkit_custom.properties file Jaa Connector com.ibm.tioli.itcam.toolkit.ai.enablejca=false Architecture (JCA) Jaa Database com.ibm.tioli.itcam.toolkit.ai.enablejdbc=false Connectiity (JDBC) Jaa Naming and Directory Interface (JNDI) Jaa Message Serice (JMS) Web containers for Serlets/ JaaSerer Pages (JSP) HTTP session count tracking CICS Transaction Gateway (CTG) IMS Jaa Data Objects (JDO) Message Queue Interface (MQI) Axis web serice Remote Method Inocation (RMI) WebSphere Application Serer EJB container com.ibm.tioli.itcam.toolkit.ai.enablejndi=false com.ibm.tioli.itcam.toolkit.ai.enablejms=false com.ibm.tioli.itcam.dc.was.webcontainer=false com.ibm.tioli.itcam.toolkit.ai.enablesessioncount=false com.ibm.tioli.itcam.dc.ctg.enablectg=false com.ibm.tioli.itcam.dc.mqi.enableims=false com.ibm.tioli.itcam.dc.mqi.enablejdo=false com.ibm.tioli.itcam.dc.mqi.enablemqi=false com.ibm.tioli.itcam.toolkit.ai.axis.enablewebserice=false am.ejb.rmilistener.enable=false com.ibm.tioli.itcam.dc.was.enableejbcontainer=false Configuring the PMI To iew data in the operational monitoring dashboards, the Performance Monitoring Infrastructure (PMI) on the WebSphere Application Serer must be configured to gather performance data. Enabling the PMI To enable the PMI on the application serer, complete these steps: 1. In the WebSphere administratie console, expand Monitoring and Tuning, and then select Performance Monitoring Infrastructure (PMI). 2. From the list of serers, click the name of your serer. 3. Select the Configuration tab, and then select the Enable Performance Monitoring Infrastructure (PMI) check box. 4. Click Apply or OK. 5. Click Sae to enable the PMI. Chapter 6. Configuring your agents 179

186 Setting the PMI leel The Performance Monitoring Infrastructure (PMI) proides four predefined leels: 1. None 2. Basic 3. Extended 4. All You can use a custom option to selectiely enable or disable indiidual statistics. Each leel includes the statistics from the leel below it. To display data in the operational monitoring dashboards, the attributes that are used in the dashboard calculations must be included in selected leel. By default, the WebSphere Applications monitoring agent sets the PMI leel high enough to collect the required attributes. Restriction: To see data in some of the Process Serer and Transaction Manager group widgets, you must manually set the PMI leel. For more information, see the fly-oer help on the group widgets. If you modify the PMI leel through the administratie console, you must erify that the leel is high enough to collect the required data. To set the PMI leel on the application serer, complete these steps: 1. In the WebSphere administratie console, expand Monitoring and Tuning, and then select Performance Monitoring Infrastructure (PMI). 2. From the list of serers, click the name of your serer. 3. Select the Configuration tab, and then select the statistics set to use; Basic, Extended, All, or Custom. 4. Click Apply or OK. 5. Click Sae to set the PMI leel. For information about the PMI leel that is required for each attribute, see the Dashboard attributes section in the Monitoring Agent for WebSphere Applications Reference on the Performance Management (SaaS) wiki. The monitoring oerhead that is incurred when you turn on the collection of each attribute is displayed. For information about customizing the PMI leel, see Customizing PMI settings. Customizing PMI settings The data collector modifies the leel of instrumentation for Performance Monitoring Infrastructure (PMI) on the monitored application serer instance. The default configuration is sufficient to supply the iewable monitoring data. You can customize this setting. Restriction: To see data in some of the Process Serer and Transaction Manager group widgets, you must manually set the PMI leel. For more information, see the fly-oer help on the group widgets. To customize these settings, in the data collector custom properties file (for more information about this file, see The Data Collector properties file on page 176), modify the following properties: 180 IBM Monitoring: Installation and Setup Guide

187 To change the settings to a leel predefined in the application serer, use the am.was6pmi.settings.2 property. Set it to basic, extended, or all. For fine-grained customization of the instrumentation for a particular PMI module, use the am.was6custompmi.settings.2 property. It has the format module_type=number1,number2,..., for example: am.was6custompmi.settings.2=beanmodule=1,2,3,4,5,6,7,8,9,10,14,15,19,20,21,22,23 Use * to monitor all IDs in the module, or none to monitor none. In particular, to configure the data collector to collect Serice Integration Bus (SIB) data, use the following setting: am.was6custompmi.settings.2=sib Serice=* If you do not want the data collector to modify the leel of instrumentation for PMI, add the following line to the data collector custom properties file (see The Data Collector properties file on page 176): am.pmi.settings.nochange=true Tip: The am.was6pmi.* property names are also alid for monitoring ersion 7, ersion 8, and ersion 8.5 application serers. Tip: Ignore the properties named am.was6pmi.1, am.was6pmi.3, am.was6custompmi.settings.1, am.was6custompmi.settings.3. They are not in use for the Monitoring Agent for WebSphere Applications. Important: To apply changes to PMI settings, restart the application serer instance. Configuring transaction tracking for remote EJBs To collect transaction tracking eents for remote Enterprise Jaa Beans (EJBs), you must ensure that the tracking of these eents is enabled in the Toolkit custom properties file of the applications serers you are monitoring. To enable transaction tracking of remote EJBs, in the toolkit custom properties file of each application serer, add or uncomment the following property: org.omg.portableinterceptor.orbinitializerclass.com.ibm.tioli.itcam.toolkit. ai.orbinterceptor.initializer=true This file is named DC_home/runtime/ app_serer_ersion.node_name.profile_name.serer_name/custom/ toolkit_custom.properties. For more information about the toolkit properties files, see Properties files for the Data Collector on page 176. Enabling and disabling data collector memory monitoring The data collector can monitor the amount of natie memory that the data collector itself uses. You can iew the results in a log file on the serer. This capability is disabled by default; you can use it to diagnose performance of the data collector. If you enable data collector memory monitoring, the data collector saes memory usage statistics to the dc_home/logs/cyn/logs/trace-dc-natie.log trace log file. The statistics reflect data collector memory consumption on the natie side. The Jaa side memory consumption is not reflected in the logged numbers. Chapter 6. Configuring your agents 181

188 To enable memory monitoring, set the following property in the data collector custom properties file : log.statistics=true For more information about the data collector custom properties file, see The Data Collector properties file on page 176. By default, the statistics are logged once eery 30 seconds. You can set a different period, in milliseconds, in the log.statistics.frequency property in the data collector custom properties file. For example, to log memory usage statistics once eery 10 seconds, use the following setting: log.statistics.frequency=10000 To disable memory monitoring, set the following property in the data collector custom properties file: log.statistics=false Settings for the data collector if Jaa 2 security is enabled By default, data collector configuration enables Jaa 2 security on the application serer, and sets a permissie policy. This policy ensures that the data collector can run properly, and proides no other security protection. If you need a more restrictie policy, ensure that the policy becomes actie and the data collector can still work properly. The data collector sets the Jaa security policy file location for all monitored application serer instances (jaa.security.policy system property) to dc_home/itcamdc/etc/datacollector.policy. You must edit this file in the following way: 1. Remoe all existing content. 2. Copy the sample security policy for the data collector from the dc_home/itcamdc/etc/datacollector.security.policy file. 3. If ITCAM for Transactions is installed on the serer, add a grant statement for the ITCAM for Transactions code base to the security policy file. Follow the model for the grant statements proided in the sample datacollector.security.policy file, but use the ITCAM for Transactions installation root directory in the codebase statement. 4. Add your required security policy settings. 5. Sae the file, and create a backup copy. Important: Each time you configure or reconfigure the data collector for an application serer instance, the file dc_home/itcamdc/etc/datacollector.policy might be oerwritten. To ensure that your security policy remains actie, restore this file from the backup copy after configuring or reconfiguring the data collector for any application serer instance. Defining custom requests By default, only certain types of Jaa classes and methods are monitored as requests by the data collector. Serlets, JSPs, EJB business methods, and certain standard J2EE APIs are recognized as requests. You can designate additional classes and methods as custom requests. For example, the data collector does not recognize Struts Action classes as requests by default. Howeer, you can set up custom request definitions and cause the actions to be recognized as Nested Requests. 182 IBM Monitoring: Installation and Setup Guide

189 Complete the following procedure to enable monitoring of custom requests and designate one or more methods as custom requests: 1. Make a copy of the dc_home/itcamdc/etc/custom_requests.xml file in a temporary location. Then, open the copy in a text editor. 2. Modify the parameters in the file. The following table describes the parameters that you can modify: Table 20. Parameters for the custom requests configuration file Tag name edgerequest Description Identifies one or more application methods that are to be Byte-Code-Instrumented for custom request processing. By modifying the requestname, Matches, type, and methodname tags within the edgerequest tag, you can customize the selection. Each edgerequest tag must contain exactly one methodname tag, and one or more Matches tags. Multiple edgerequest tags can be specified. requestname Matches type methodname requestmapper Defines a unique name for this request. The request name is displayed to the user when the method entry and exit are traced. Identifies a class or classes that contain the methods that are to be Byte-Code-Instrumented for custom request processing. Multiple Matches tags can be present within a single edgerequest tag. Indicates whether a class must be a system or application class in order to match the edgerequest tag. Identifies the names of the methods within one of the classes identified by the Matches tag that are to be Byte-Code-Instrumented for custom request processing. Exactly one methodname tag can be specified in each edgerequest tag. Optional. If this tag is specified, the data collector uses a request mapper to determine information that identifies the request. You can define nonstandard ways of extracting this information. For more information about enabling and defining request mappers, see the Agent for WebSphere Applications reference in IBM Performance Management Wiki - Documentation. The Matches and methodname tags can include wildcard characters. The following section describes how the wildcard characters works: Asterisk (*) stands for zero or more occurrences of any character when used by itself. When embedded within a sequence of characters (for example, jaa.*.string), it matches zero or more occurrences of any character except the package separator (.). Two periods (..) can be used to specify all subpackages. It matches any sequence of characters that starts and ends with the package separator (.). For example, jaa..string matches jaa.lang.string and com.ibm..* matches any declaration beginning with com.ibm. For example, an application with a package name of com.mycompany.myapp has the following requirements: Within the Customer class, the creditcheck() method must be treated as a custom request called CreditCheck. Within the Supplier class, the inentorycheck() method must be treated as a custom request called SupplyCheck. The following example shows the contents of the customized custom_requests.xml file that accomplishes this: <customedgerequests> <edgerequest> <requestname>creditcheck</requestname> <Matches>com.mycompany.myapp.Customer</Matches> Chapter 6. Configuring your agents 183

190 <type>application</type> <methodname>creditcheck</methodname> </edgerequest> <edgerequest> <requestname>supplycheck</requestname> <Matches>com.mycompany.myapp.Supplier</Matches> <type>application</type> <methodname>inentorycheck</methodname> </edgerequest> </customedgerequests> 3. Complete one of the following steps: Sae the file in the dc_home/runtime/ app_serer_ersion.node_name.serer_name/custom directory. Then, in the toolkit custom properties file, set the property am.camtoolkit.gpe.customxml.custom to the name (without path) of the file that you modified in Step 2 on page 183. For more information about the toolkit custom properties file, see The toolkit properties file on page 176. Sae the file in any directory on your computer. Then, in the toolkit custom properties file, set the property am.camtoolkit.gpe.customxml.custom to the path and name for the file that you modified in Step 2 on page 183. For more information about the toolkit custom properties file, see The toolkit properties file on page 176. Configuring collection of detailed diagnostic information If you hae Application Diagnostics, use the data collector collects detailed diagnostic information on the monitored application serer instance. This information can be displayed in the diagnostic dashboards. Use the Agent Configuration page on the Performance Management console to enable and disable collection of diagnostic and method trace information. To configure the behaiour of the diagnostic data collection, including the amount of diagnostic information that the data collector stores, change the gdc_custom.properties configuration file. Setting limits for the size and number of detailed information files The data collector stores diagnostic information in a number of files. By default, it stores 100 files; if 100 files are already stored and a new file is created, the oldest file is deleted. The data collector creates a new file eery 15 minutes, or when the size of the current file exceeds 200 megabytes. When the total size of the directory containing the files exceeds 2 gigabytes, the data collector deletes the oldest file. You can change the following settings in the dc_home/runtime/ appserer_ersion.node_name.profile_name.serer_name/custom/gdc/ gdc_custom.properties file: To set the maximum amount of files with diagnostic information, set the com.ibm.itcam.gdc.dfe.filelimit property, for example: com.ibm.itcam.gdc.dfe.filelimit=100 To set the time, in minutes, after which the data collector creates a new diagnostic data file, set the com.ibm.itcam.gdc.dfe.frequency property, for example: com.ibm.itcam.gdc.dfe.frequency=15 To set the maximum diagnostic data file size, in megabytes, set the dfe.file.maxlimit property, for example: dfe.file.maxlimit= IBM Monitoring: Installation and Setup Guide If the current diagnostic data file reaches this size, the data collector creates a new diagnostic data file.

191 To set the maximum total size of all data files, in bytes, set the trace.dir.size.limit property, for example: trace.dir.size.limit= If the sum of the sizes of all the diagnostic data files exceeds this alue, the data collector deletes the oldest data file. The minimum total size is 25 megabytes. Setting full or partial collection of request and method diagnostic data The data collector has the following default settings: The data collector collects diagnostic data only for selected requests. The selection (sampling) of the requests aims to include all errors and some good requests. Method data collection is disabled at serer startup. You can use the Agent Configuration page in the user interface to enable it. When method data collection is enabled, the data collector gathers method data only for some requests (of those for which diagnostic data is collected). This further selection (sampling) again aims to include all errors and some good requests. You can change these settings using properties in the dc_home/runtime/ appserer_ersion.node_name.profile_name.serer_name/custom/gdc/ gdc_custom.properties file. Important: Changing these settings affects performance of the application serer. On production serers, the performance degradation might be critical To collect diagnostic data for eery request, set the property: dc.sampling.enable=false To enable collecting method data for eery request for which diagnostic data is collected, set the property: dc.sampling.methsampler.enabled=false Tip: The dc.sampling.methsampler.enabled property has effect only when method data collection is enabled. To enable method data collection, use the Agent Configuration page or the dfe.enable.methoddata property. You can set other properties in the dc_home/runtime/ appserer_ersion.node_name.profile_name.serer_name/custom/gdc/ gdc_custom.properties file to customize collection of diagnostic data. The comments in the file describe the properties. Important: After changing the configuration file, restart the monitored application serer instance. Then the changes will take effect. Dynamically configuring data collection on Agent Configuration page After you enable the support for transaction tracking or diagnostic data collection in the data collector, use the Agent Configuration page to dynamically enable or disable the data collection. Chapter 6. Configuring your agents 185

192 Before you begin You must install and configure the Monitoring Agent for WebSphere Applications. Topology iews must be aailable in the Performance Management console. To enable or disable transaction tracking for the monitored application serers, you must install Transaction Tracking. You must also enable support for transaction tracking in the agent as described in Configuring the data collector interactiely on page 164. If you follow the simple configuration procedure, the data collector is automatically configured with support for transaction tracking. To enable or disable the collection of diagnostic data including method trace, you must hae IBM Application Diagnostics (SaaS). You must also enable support for the collection of diagnostic and method trace information in the data collector as described in Configuring the data collector interactiely on page 164. (Not aailable for IBM Monitoring). Tip: The Agent Configuration page displays all the serers that are monitored by the agent. If any serer is missing, it might not be correctly monitored. Check the agent log files on the monitored system for error messages, for example, connection errors. About this task To display data in the topology dashboards, transaction tracking or diagnostic data collection must be enabled for each serer that you are monitoring. Take these steps to configure data collection for each serer. Procedure 1. From the naigation bar, click System Configuration > Agent Configuration. The Agent Configuration page is displayed. 2. Go to the WebSphere tab. 3. To enable transaction tracking or diagnostic data collection for one or seeral serers, complete these steps: a. Select the check boxes of the serers on which you want to configure data collection. b. From the Actions list, take one of the following actions: To enable transaction tracking, click Enable Transaction Tracking. The status in the Current Transaction Tracking column is updated to Yes for each selected serer. To enable only the diagnostic data collection, click Enable Diagnostic Mode. The status in the Current Diagnostic Mode column is updated to Yes for each selected serer. To collect both the diagnostic data and method trace information, click Enable Diagnostic Mode and Method Trace. The status in the Current Diagnostic Mode and Current Method Trace columns is updated to Yes for each selected serer. Remember: Unless support for transaction tracking or diagnostic data collection is configured in the data collector, operations on the Agent Configuration page does not enable data collection and the column alue is set to No. 4. To disable transaction tracking or diagnostic data collection for one or seeral serers, complete these steps: 186 IBM Monitoring: Installation and Setup Guide

193 a. Select the check boxes of the serers on which you want to disable data collection. b. From the Actions list, take one of the following actions: Results To disable transaction tracking for the selected serer, click Disable Transaction Tracking. The status in the Current Transaction Tracking column is updated to No for each selected serer. If only the diagnostic data collection is enabled for the selected serer, to disable the data collection, click Disable Diagnostic Mode. The status in the Current Diagnostic Mode column is updated to No for each selected serer. If both the diagnostic data and method trace data are enabled for the selected serer, to disable the data collection, click Disable Diagnostic Mode and Method Trace. The status in the Current Diagnostic Mode and Current Method Trace columns is updated to No for each selected serer. You hae configured data collection for each selected serer. Important: If an application serer restarts, you might need to enable transaction tracking or diagnostic data collection for the serer again. What to do next After you enable diagnostic data collection, you can control the behaiour of data collection with a configuration file. For instructions, see Configuring collection of detailed diagnostic information on page 184. Configuring the WebSphere Infrastructure Manager agent Configure the WebSphere Infrastructure Manager agent to monitor the performance of WebSphere Deployment Manager and Node Agent. About this task The WebSphere Infrastructure Manager agent is a multiple instance agent. You must create the first instance and start the agent manually. Procedure 1. To configure the agent, run the following command. install_dir/bin/wim-agent.sh config instance_name Where instance_name is the name you want to gie to the instance, and install_dir is the installation directory of WebSphere Infrastructure Manager agent. The default installation directory is /opt/ibm/apm/agent. 2. When prompted to Edit 'Monitoring Agent for WebSphere Infrastructure Manager' settings, enter 1 to continue. 3. When prompted for Jaa home, specify the directory where Jaa is installed. The default alue is /opt/ibm/apm/agent/jre/lx8266/jre. 4. When prompted for DMGR Profile Home, specify the home directory of the Deployment Manager profile. The default directory is /opt/ibm/websphere/ AppSerer/profiles/Dmgr01. Chapter 6. Configuring your agents 187

194 5. When prompted for JMX user ID, specify the user ID that is used to connect to the MBean serer. 6. When prompted to Enter JMX password, specify the password for the user. 7. When prompted to Re-type JMX password, enter the password again. 8. To start the agent, run the following command. install_dir/bin/wim-agent.sh start instance_name Results You created a WebSphere Infrastructure Manager agent instance and started the monitoring agent to begin collecting data samples for resource monitoring. Configuring certificates between the serer and agents To enable communication between the Performance Management serer and agents, you can configure default, custom, or self-signed certificates. Configuring a default certificate If you use the HTTPS protocol to communicate between the Performance Management serer and the agents, the Performance Management serer allows connections from the agents that authenticate themseles with a alid certificate. You can configure HTTPS communication that is based on default certificates that are generated during the installation of the Performance Management serer Before you begin The following certificates are generated during the Performance Management serer installation: The local root certificate authority (CA) agent and serer certificates that are signed by that local root CA are always generated unless the /opt/ibm/ccm/keyfiles directory exists before starting installation. The local root certificate authority (CA) is established and two keystores are generated. One keystore contains the key that is used by the serer and the other keystore contains the keys that are used by the agents. The keys from the keystores are signed by the local root CA. The public key certificates are exchanged between those keystores, for example, the signed serer public key is added to the agent keystore and the signed agent public key is added to the serer keystore. The Local root CA public key is added to both keystores so that both the agent and the serer can trust their certificates. The HTTPS protocol uses Elliptic Cure ciphers that are 256 bits and it conforms to the Suite-B FIPS standard. About this task The following scenarios apply: If you preconfigured the agents during the serer installation and set APM_SECURE_COMMUNICATION=y that turns on the HTTPS communication, you do not hae to complete any additional steps now to use the HTTPS communication protocol. 188 IBM Monitoring: Installation and Setup Guide

195 If you preconfigured the agents during the serer installation with the default HTTP protocol, now you must reconfigure the agent images to create new preconfiguration packages to use the HTTPS communication protocol. For more information, see step 1 in the procedure. If you did not preconfigure the agents during the Performance Management serer installation, you must preconfigure the agents with the HTTPS communication enabled between the serer and the agents as shown in the procedure. To enable communication between the serer and agents by using the default certificates that were generated during the Performance Management serer installation, complete the following steps: Procedure 1. To preconfigure the agent images manually, see Preconfiguring the agent images on page 39. Ensure that you select HTTPS communication when you run the make_configuration_packages.sh script to create the preconfiguration packages. 2. Modify the /opt/ibm/wlp/usr/serers/asfrest/serer.xml file. In the ssl section, after the enabledciphers="tls_ecdhe_ecdsa_with_aes_128_gcm_sha256" property, add the following entry: clientauthentication="true" 3. To change the communication protocol for the Agent Central Configuration to https, complete the following steps: a. Log in to the Performance Management console. b. Select System Configuration > Adanced Configuration. c. Click Agent Central Configuration. d. Set the Protocol to include https, and click Sae. 4. Install the agents using the agent images that are preconfigured in step 1. Configuring a self-signed certificate You might want to use your own certificate instead of the certificate that is generated by the (CA) certificate authority or the default cert that is generated by the serer. Before you begin Ensure that the firewalls or network filtering deices that are located between the Performance Management serer and the agents enable communication on port 443. You must prepare two passwords: one for serer keystore and another for the agent keystore. About this task If you want to use a certificate that is signed by you, complete the following steps: Procedure 1. Log in to the operating system of the serer machine and to the KEYFILES_DIR that is set to the /opt/ibm/ccm/keystore directory. 2. To generate a local root (CA) certificate authority to sign the certificate signing requests (CSRs) for the serer and the agent certificates, you must choose a password. The password enciphers the root CA priate key and keystore. Chapter 6. Configuring your agents 189

196 Then, you must set the password as an enironment ariable. The security tool that is used for certificate management uses the password: export ROOTCAPASS="put_your_password_here" /opt/ibm/ccm/create_security_artifacts.sh -genrootca -workdir "${KEYFILES_DIR}" -keyalg EC -hostname APM_MIN_serer -dname "APM_Root_CA" -label "Root_CA_Cert" Important: For step 2, 3, and 4 you can replace the key label with a different label. The following labels are used as an example only in these steps: Root_CA_Cert APM_Agent_Certificate serer_key You can replace the hostname with a user-defined hostname. When you are finished, you remoe the password from the enironment ariable: enter export -n ROOTCAPASS. The Root CA is created in the "${KEYFILES_DIR}"/apmCA directory. It contains two subdirectories: keyfiles and exports. The keyfiles/ subdirectory contains the root CA keystore and the exports/ subdirectory contains the root CA public certificate. 3. To create the agent keystore and a CSR, you must set the host name to a generic name. You do not hae to use the default.agent hostname. The certificate is used by all agents that communicate with a specific serer. You must create a password for the agent keystore and a priate key to export to the enironment before you run the script: export APMPASS="put_your_agent_keystore_password_here" /opt/ibm/ccm/create_security_artifacts.sh -gencsr -workdir "${KEYFILES_DIR}" -keyalg EC -hostname default.agent -dname "APM_Root_CA" -label "APM_Agent_Certificate" A message is printed on the console that contains the path to the CSR file. After you are finished, you must remoe the password from the enironment ariable: export -n APMPASS. 4. To create a serer keystore and a CSR you must proide the host name to -hostname option. It might be a generic host name or a real host name of the serer. You must set the password for the serer keystore and the priate key: export APMPASS="put_your_serer_keystore_password_here" /opt/ibm/ccm/create_security_artifacts.sh -gencsr -workdir "${KEYFILES_DIR}" -keyalg EC -hostname default.serer -dname "APM_Root_CA" -label "serer_key" A message is printed on the console with the path to the CSR file. After you are finished, you must remoe the password from the enironment ariable: export -n APMPASS. 5. Sign the agent CSR by using the root CA that you created in step 2. Then, the agent keystore signed agent certificate and the root CA public certificate is added automatically to the agent keystore: /opt/ibm/ccm/create_security_artifacts.sh -signcsr -keyalg EC -rootcakdb "${KEYFILES_DIR}"/apmCA/keyfiles/keyfile.kdb -rootcalabel "Root_CA_Cert" -csrfile "${KEYFILES_DIR}"/default.agent/exports/default.agent.arm Important: In step 5 and 6, -rootcalabel must match the label that is specified in step Sign the serer CSR. Then, the signed serer certificate and the root CA public certificate are added automatically to the serer keystore: /opt/ibm/ccm/create_security_artifacts.sh -signcsr -keyalg EC -rootcakdb "${KEYFILES_DIR}"/apmCA/keyfiles/keyfile.kdb -rootcalabel "Root_CA_Cert" -csrfile "${KEYFILES_DIR}"/default.serer/exports/default.serer.arm 190 IBM Monitoring: Installation and Setup Guide

197 7. Add the agent public key to the serer keystore. The ASFREST serer is configured to accept connections only from clients or agents that authenticate themseles with a known certificate. /opt/ibm/ccm/create_security_artifacts.sh -addkeytodb -destkdb "${KEYFILES_DIR}"/default.serer/keyfiles/keyfile.kdb -importfile "${KEYFILES_DIR}"/default.agent/exports/default.agent.cer -label "APM_Agent_Certificate 8. Add the serer public key to the agent keystore so that the agent is able to authenticate serer: /opt/ibm/ccm/create_security_artifacts.sh -addkeytodb -destkdb "${KEYFILES_DIR}"/default.agent/keyfiles/keyfile.kdb -importfile "${KEYFILES_DIR}"/default.serer/exports/default.serer.cer -label "serer_key" 9. Conert the serer keystore from the GSKit format (*.kdb) to the Jaa keystore format (*.jks). You must set the serer keystore password: export APMPASS="put_your_serer_keystore_password_here" /opt/ibm/ccm/create_security_artifacts.sh -kdb2jks -sourcekdb "${KEYFILES_DIR}"/default.serer/keyfiles/keyfile.kdb The ${KEYFILES_DIR}"/default.serer/keyfiles/keyfile.jks" file is created. When you are finished you must remoe the password from the enironment: export -n APMPASS. 10. Conert the agent keystore from the GSKit format (*.kdb) to the Jaa keystore format (*.jks). You must set the agent keystore password: export APMPASS= "put_your_agent_keystore_password_here" /opt/ibm/ccm/create_security_artifacts.sh -kdb2jks -sourcekdb "${KEYFILES_DIR}"/default.agent/keyfiles/keyfile.kdb When you are finished, you must remoe the password from the enironment: export -n APMPASS. 11. Copy the created keyfiles to the main keyfiles directory: /bin/cp "${KEYFILES_DIR}"/default.agent/keyfiles/keyfile.* /opt/ibm/ccm/keyfiles/ /bin/cp "${KEYFILES_DIR}"/default.agent/keyfiles /KAES256.ser /opt/ibm/ccm/keyfiles/ /bin/cp "${KEYFILES_DIR}"/default.serer/keyfiles/keyfile.jks /opt/ibm/ccm/keyfiles/serer 12. Copy the serer.jks file to the Liberty serer location. To ensure secure agent communication, use the asfrest serer: /bin/cp /opt/ibm/ccm/keyfiles/serer.jks /opt/ibm/wlp/usr/serers/asfrest/resources/security/ 13. Encode the (xor) serer keystore password: /opt/ibm/wlp/bin/securityutility encode 14. Replace the password entry in the serer configuration with the newly encoded password from step 12. Open the /opt/ibm/wlp/usr/serers/ asfrest/serer.xml file in a text editor. Find the line that contains the "defaultkeystore" definition of the keystore and replace the password entry. 15. If you changed key labels in steps 3 and 4 (from an argument to a -label option), you need to edit the following properties in the /opt/ibm/wlp/usr/ serers/asfrest/serer.xml: sererkeyalias="put_serer_key_label_here" clientkeyalias="put_agent_key_label_here" Note: If the "sererkeyalias" and the "clientkeyalias" key alias entries do not exist in the serer.xml then you must add the entries to the <ssl> section after the "enabledciphers="tls_ecdhe_ecdsa_with_aes_128_gcm_sha256" property. 16. Restart the asfrest serer: Chapter 6. Configuring your agents 191

198 apm stop asfrest apm start asfrest 17. If the IBM Performance Management Hybrid Gateway is installed in your Tioli Monitoring enironment, copy the JKS agent keystore to the Hybrid Gateway location: cp /opt/ibm/ccm/keyfiles/keyfile.* /opt/ibm/wlp/usr/serers /hybridgateway/resources/security/ 18. Select one of the following steps: If you installed agents, then copy the keystore files to the agent installation directory: cp "/opt/ibm/ccm/keyfiles/keyfile.* path_to_agent_images/ keyfiles.". Modify the agent configuration file to show which certificate should be used by the agent. The following ariable must be modified or added to the configuration file: KDEBE_KEY_LABEL="agent_key_label" For example, KDEBE_KEY_LABEL="APM_Agent_Certificate" - For Windows 64-bit installation, modify the ariable in the \TMAITM6_x64\KPCENV file. - For Windows 32-bit installation, modify the ariable in the \TMAITM6\KPCENV file. Note: You must replace PC with the alid product code. For example, for an agent that is installed to C:\IBM\APM, to modify the OS agent configuration on a 64-bit installation, you must change the following file: C:\IBM\APM\TMAITM6_x64\KNTENV. - On Linux/AIX, modify the ariable in the following file: agent_installation_path/config/global.enironment. Restart the agents. If you did not install agents, use the agent pre-configuration tool to modify the agent images to contain the new certificates. a. To create the configuration packages, use the /opt/ibm/ccm/ make_configuration_packages.sh tool. b. To pre-configure the agent images, use the /opt/ibm/ccm/ configure_agent_images script. c. Modify the configuration file to show which certificate should be used by the agents: The KDEBE_KEY_LABEL = agent_key_label ariable must be added to the configuration files in an unpacked agent image: For example, KDEBE_KEY_LABEL="APM_Agent_Certificate". On Linux/AIX, modify the ariable in the following file: unpacked_agent_image_path/.apm_config/agent_global.enironment. For example, APM_Agent_Install_8.1.0/.apm_config/ agent_global.enironment. On Windows, modify the ariable in the [CMA_CONFIG_VARIABLES] section of the following file: unpacked_agent_image_path\apm_config\ framework_silent_install.txt. The agent configuration package that you create by using the make_configuration_packages.sh script also contain the Windows package with the pre-configuration data and the Windows script. 192 IBM Monitoring: Installation and Setup Guide

199 Chapter 7. Integrating with other products You can integrate other products with IBM Monitoring to proide you with a robust solution. Integrating with Tioli Monitoring In an enironment that includes both IBM Tioli Monitoring and IBM Performance Management products, you can install the IBM Performance Management Hybrid Gateway to proide a consolidated iew of managed systems from both domains. Background information To iew your hybrid enironment in the Performance Management console, you must create a managed system group, install the Hybrid Gateway, and configure communications. Reiew the background information to help you plan for installing and configuring the IBM Performance Management Hybrid Gateway in your IBM Tioli Monitoring and IBM Performance Management enironments. Where to install the Hybrid Gateway The Hybrid Gateway must be installed on a Red Hat Enterprise Linux 6.2 (or later) system that has a network connection with IBM Tioli Monitoring and IBM Performance Management. The Hybrid Gateway can be installed on the same system as your Tioli Enterprise Portal Serer if it is running on Red Hat Enterprise Linux. Howeer, the Hybrid Gateway cannot be installed on the same system as your Performance Management serer. The IBM Tioli Monitoring dashboard data proider must be enabled on the Tioli Enterprise Portal Serer. For details, see Verifying the dashboard data proider is enabled in the IBM Tioli Monitoring Knowledge Center. Supported Tioli Monitoring agents For a Tioli Monitoring agent to be aailable for the Hybrid Gateway, it must also be supported in IBM Performance Management. For a list of aailable Tioli Monitoring agents and ersions, see IBM Performance Management Wiki - Supported IBM Tioli Monitoring agents. Tioli Monitoring agents in the Performance Management console After selecting the My Components application or another application in the Application Performance Dashboard that includes Tioli Monitoring managed systems, you can see a summary status dashboard of all managed systems and you can see a detailed dashboard of a single managed system instance. You can also create a line chart and table in the Attribute Details tab. Howeer, you cannot see situation eents in the Eents tab nor can you create eenting thresholds. View up to 200 managed systems from your Tioli Monitoring domain The maximum number of managed systems, including subnodes, that you can iew from your Tioli Monitoring domain is 200. That limit can be extended to 400 by increasing the alue of the Tioli Enterprise Portal Copyright IBM Corp

200 Serer KFW_REPORT_NODE_LIMIT enironment ariable (see Tioli Enterprise Portal Serer configuration settings). If the managed system group goes beyond 400, performance degrades. Tioli Authorization Policy Serer affects the aailability of Tioli Monitoring managed systems For Tioli Monitoring enironments that include the Tioli Authorization Policy Serer, the managed systems that are aailable through the Hybrid Gateway are affected by the authorization policies. For more information, see Using role-based authorization policies in the Tioli Monitoring Knowledge Center. For a ideo demonstration, see Installing and configuring the Hybrid Gateway in the Performance Management ideo library on IBM Serice Engage. Preconfiguring the Hybrid Gateway image Before you can install the IBM Performance Management Hybrid Gateway, you must preconfigure the downloaded image for communications with the Performance Management serer. If you selected the option to preconfigure the Hybrid Gateway image when you installed the serer, and that configuration completed successfully, you can skip these steps. Before you begin To preconfigure the Hybrid Gateway image, you run two scripts: The make_configuration_packages is run on the system where the Performance Management serer is installed. The script creates a configuration package tar file with the serer address and the communications protocol in the current directory or in a directory that you specify. The configure_agent_images script is run on the directory where the configuration package is located. The script applies information from the configuration package to the Hybrid Gateway image file that you downloaded for installation. About this task Complete the following steps to create the Hybrid Gateway configuration package and to download and preconfigure the Hybrid Gateway: Procedure 1. Download the Hybrid Gateway image to a Red Hat Enterprise Linux system in your Tioli Monitoring enironment (see Chapter 3, Download instructions, on page 27) and unpack it. Alternatiely, you can download the image archie file to another system and leae it unpacked. Later, you can preconfigure the Hybrid Gateway image archie file and copy the archie file to the Red Hat Enterprise Linux system in your Tioli Monitoring enironment where it will be installed. Important: Do not change the installation image file name for Hybrid Gateway during or after download. If the image file name is changed, it is not recognized by preconfiguration tools and preconfiguration fails. 2. To create the configuration package tar file, run the make configuration package script and respond to the prompts: 194 IBM Monitoring: Installation and Setup Guide

201 a. On the system where the Performance Management serer is installed, naigate to /opt/ibm/ccm and enter the following command:./make_configuration_packages.sh b. Enter the IP address or fully qualified host name of the Performance Management serer or accept the default alue. c. Enter the directory where you want to store the configuration package after you create it or accept the default alue of /tmp/ mkcustpkg_workdir.process_id_of_script. d. Select the HTTPS protocol if you want secure communications between the serer and Hybrid Gateway; select the HTTP protocol for non-secure communications. The communications protocol between serer and agents must be the same. For more information, see Setting HTTP or HTTPS communications on page Copy the configuration package tar file that you created to the system where you downloaded the Hybrid Gateway image and, optionally, unpack the configuration package. 4. If you unpacked the configuration package, naigate to the directory where you unpacked the configuration package. 5. To preconfigure the Hybrid Gateway image in interactie mode, run the configure agent image script and respond to the prompts. Otherwise, skip to step 6 to use batch mode: a. On the system where the Performance Management serer is installed, naigate to /opt/ibm/ccm and enter the following command:./configure_agent_images.sh b. If you did not unpack the configuration package, enter the path to the directory where you stored the package. c. Enter the path to the directory where you unpacked the Hybrid Gateway image or, if you did not unpack the Hybrid Gateway image, take the following steps: 1) Enter the path to the directory where you downloaded the Hybrid Gateway image archie fle. 2) Enter the path to the directory where you want to store the preconfigured Hybrid Gateway image archie file (default is /opt/ibm/ccm/depot). 6. To preconfigure the Hybrid Gateway image archie file in batch mode, follow these steps: a. If you unpacked the configuration package, naigate to the directory where the unpacked configuration files are located. b. Enter the following command:./configure_agent_images.sh [-p configuration_package_dir] [-s hybrid_image_dir] [-d preconfigured_image_dir] Where: configuration_package_dir If you did not unpack the configuration package, enter the path to the directory where the configuration package is located. hybrid_images_dir Path to the directory where you downloaded the Hybrid Gateway image archie file. preconfigured_image_dir If you did not unpack the Hybrid Gateway image archie file that Chapter 7. Integrating with other products 195

202 you downloaded, enter the path to the directory where you want to store the preconfigured Hybrid Gateway image archie file. Results The installer preconfigures the Hybrid Gateway image archie file. A status message is displayed to indicate that the Hybrid Gateway image or the Hybrid Gateway image archie file is preconfigured and proides the location of the file. What to do next Complete one of the following steps: If you preconfigured the unpacked image on the Red Hat Enterprise Linux system in your Tioli Monitoring network where you want to install the Hybrid Gateway, install now. If you preconfigured the Hybrid Gateway image archie file on another system, copy the preconfigured image archie file to the system in your Tioli Monitoring network where you want to install the Hybrid Gateway. Continue to Installing the Hybrid Gateway. Installing the Hybrid Gateway Download and install the IBM Performance Management Hybrid Gateway to iew managed systems from your IBM Tioli Monitoring domain in the Performance Management console. Before you begin The Hybrid Gateway must be installed on a Red Hat Enterprise Linux 6.2 (or later) system that has a network connection with IBM Tioli Monitoring and IBM Performance Management. The installation script must be run with root user priileges. For a complete list of supported operating systems, see the IBM Performance Management Wiki - System requirements. The Hybrid Gateway can be installed on the same system as your Tioli Enterprise Portal Serer but it cannot be installed on the same system as your Performance Management serer. The Tioli Enterprise Portal Serer must be at or higher. To support agent backward compatibility (IV65941), enhancements were made in For more information, see dociew.wss?uid=swg Before installing the Hybrid Gateway, preconfigure the Hybrid Gateway images with the connection details for the Performance Management serer. For instructions, see Preconfiguring the Hybrid Gateway image on page 194. About this task Take the following steps to install the Hybrid Gateway in your Tioli Monitoring enironment: Procedure 1. Naigate to the directory where your preconfigured Hybrid Gateway image is located. 2. Enter the following command to extract the files: 196 IBM Monitoring: Installation and Setup Guide

203 tar -xf ibm-monitoring-hybrid-gateway.tar The archie file contains a script that is used to deploy the Hybrid Gateway. The installation script is extracted into the top-leel directory and Hybrid Gateway files are extracted into subdirectories. 3. Change to the Hybrid Gateway directory and run the installation script with root user priileges: cd Hybrid_Gateway_Install_ersion./install.sh where ersion is the current ersion, such as A prerequisite scan of your enironment starts and takes a few moments to complete. If any requirements are missing, a message directs you to a log file with the reason for the failure. A prerequisite, such as insufficient disk space, stops the installation. You must address the failure, and start the installation again. You can also turn off the prerequisite check as described in Bypassing the prerequisite scanner. 4. After the system passes the prerequisite scan, respond to the prompt to accept the license agreement by selecting 1 for yes. Results The Hybrid Gateway is installed in the /opt/ibm/hybridgateway directory and starts automatically. Be aware that until the connection to the Tioli Enterprise Portal Serer is configured, connection failures are logged. What to do next You can check the status of the Hybrid Gateway with the following command: install_dir/hybridgateway/bin/hybridgateway.sh status. For other options, see Managing the Hybrid Gateway on page 201. If you haen't already created the managed system group for the Hybrid Gateway, follow the instructions in Creating the managed system group. The last step for setting up the Hybrid Gateway is to configure it in the Performance Management console. Follow the instructions in Configuring the Hybrid Gateway on page 199. Creating the managed system group Use the Object group editor in the Tioli Enterprise Portal client to create a managed system group of managed systems that you want to iew in the Performance Management console. Before you begin The types of IBM Tioli Monitoring agents that you can include in the managed system group must be among the IBM Monitoring supported agents, such as Monitoring Agent for Oracle Database or Monitoring Agent for Linux OS. For the current list of supported Tioli Monitoring agents, see IBM Performance Management Wiki - Supported IBM Tioli Monitoring agents. You can add up to 200 managed systems to the managed system group for iewing in the Application Performance Dashboards. You can increase the limit to 400 managed systems by setting the Tioli Enterprise Portal Serer KFW_REPORT_NODE_LIMIT enironment ariable in the /opt/ibm/config/cq.ini file on Linux or AIX, or the \ibm\itm\cnps\kfwen file on Windows. For more information, see Tioli Enterprise Portal Serer configuration settings. Chapter 7. Integrating with other products 197

204 For applications with subnodes, such as Monitoring Agent for WebSphere Applications, you must assign the managing node to the managed system group. Although you are assigning one managing node to the managed system group, any subnodes are included in the count towards the managed system maximum. Some monitoring agents hae subnodes, such as Monitoring Agent for WebSphere Applications. If you assign a managing node to the managed system group, any subnodes associated with that managing node are discoered automatically. You do not need to assign the subnodes if you intend for all the subnodes to be iewable in the dashboards. If you assign any subnodes to the managed system group, you must also assign the managing node; otherwise, the assigned subnodes are not isible in the Performance Management console.for apps inoling subnodes, you must assign the managing node to the group. Een though you're adding one managed node to the group, any subnodes are included in the count. If you prefer to create the managed system group with the tacmd creategroup command, log in to the hub Tioli Enterprise Monitoring Serer with tacmd login, and enter tacmd creategroup -g hybrid_systems -t collection -l managedsystem,managedsystem,managedsystem where hybrid_systems is the new managed system group name, which must consist of only letters, numbers, and underscores (_), and managedsystem is the managed system name, with each name separated by a comma (,), such as MyLinux01:LZ,MyLinux02:LZ,MyWAS01:KYNA,Primary:mysystem:NT. For a list of the managed systems for an agent type, enter tacmd iewsystemlist -l "*LINUX_SYSTEM" where *LINUX_SYSTEM is the predefined managed system group for the agent, such as *NT_SYSTEM. About this task Complete these steps to create a managed system group in the Tioli Enterprise Portal client. Procedure 1. Start the Tioli Enterprise Portal client with a user ID and password that has full access to all the managed system types (Allowed Applications is set to All Applications for the user ID.) 2. Click Object group editor. 3. Expand the Managed system object and select All Managed Systems to combine multiple agent types (such as Windows OS and Oracle) in the managed system group. If you prefer that the managed system group contain only one monitoring agent type, such as Linux OS or WebSphere Applications, select the agent type. 4. Click Create new group and enter a name for the managed system group. The name can consist of letters and numbers, and must hae no spaces, punctuation, or special characters other than the underscore (_). After you click OK, the new managed system group is displayed in the managed system folder. 5. Select the managed systems from the Aailable Managed Systems list and to moe them to the Assigned list. You can select multiple managed systems by holding down Ctrl while clicking each managed system. After selection a managed system, you can use Shift+click to select all managed systems between this and the first selection. 6. After adding managed systems to the group, click OK to sae your changes and close the Object group editor. 198 IBM Monitoring: Installation and Setup Guide

205 What to do next After creating the managed system group and installing the Hybrid Gateway, you must configure the Hybrid Gateway in the Performance Management console. For the configuration, specify the managed system group name that you created, the Tioli Enterprise Portal user ID that is allowed access to all agent types, and the host name and port of the Tioli Enterprise Portal Serer. For installation instructions, see Installing the Hybrid Gateway on page 196. For configuration instructions, see Configuring the Hybrid Gateway. Configuring the Hybrid Gateway Use the Adanced Configuration page in the Performance Management console to configure the IBM Performance Management Hybrid Gateway to connect to the Tioli Enterprise Portal Serer and to specify the managed system group. About this task Take these steps to configure the Hybrid Gateway in the Performance Management console. Procedure 1. If you are not already logged in to the Performance Management console, log in now. (See Starting the Performance Management console on page 205.) 2. Click System Configuration > Adanced Configuration and click Hybrid Gateway. 3. In the Managed System Group Name field, enter the name of the manage system group for the Hybrid Gateway. This is the name that you used in Creating the managed system group on page Specify the address, port, and web communications protocol of the Tioli Enterprise Portal Serer: Option Portal Serer Host Name Portal Serer Port Portal Serer Protocol Description Enter the portal serer host IP address or fully qualified host or domain name. Enter the port number that is used by the portal serer for web communications. The default port is for HTTP or for HTTPS. A alue of 0 sets the port to the default for HTTP or for HTTPS. Select the HTTP Internet Protocol or the secure HTTPS Internet Protocol to connect to the portal serer. Important: The IBM Tioli Monitoring dashboard data proider must be enabled on the Tioli Enterprise Portal Serer. For details, see Verifying the dashboard data proider is enabled in the IBM Tioli Monitoring Knowledge Center. 5. Complete the Portal Serer User Name and Portal Serer Password fields with the logon user name and corresponding password for starting the Tioli Enterprise Portal client. The user ID must hae access to all monitoring agent Chapter 7. Integrating with other products 199

206 types (Allowed Applications is set to All Applications), such as the sysadmin ID. For more information, see Administer Users in the Tioli Monitoring IBM Knowledge Center. 6. If access to the portal serer goes through a proxy serer, specify the address, port, and web protocol: Option Pass-Through Proxy Host Name Pass-Through Proxy Port Pass-Through Proxy Protocol Description Enter the IP address or fully qualified name of the proxy host system. Enter the port number of the proxy host system. Select the protocol that is used for communications through the proxy: HTTP or HTTPS Results After you click Sae, a connection is established with the Hybrid Gateway serice and the managed systems from your Tioli Monitoring domain are discoered. The managed system group is polled eery 5 minutes for resource monitoring data. What to do next Reiew the Application Performance Dashboard to confirm that the managed systems from your Tioli Monitoring domain are passed through the Hybrid Gateway: 1. Click Performance > Application Performance Dashboard to open the All My Applications dashboard. 2. In the summary box for My Components, click Components to open the status summary dashboard for all component managed systems (except for the WebSphere Applications agent). If you don't hae a My Components application, add an application as described in Managing applications on page Look for managed systems from your Tioli Monitoring domain, indicated by an ITM (IBM Tioli Monitoring) domain icon in the status summary group widget title. If any managed systems are missing, download the IBM Performance Management (SaaS) Troubleshooting PDF from IBM Performance Management Wiki - Documentation and search on Hybrid Gateway. You can create applications with managed systems from your Tioli Monitoring domain and include managed systems from your Performance Management (SaaS) domain. For details, see Managing applications on page 206. Uninstalling the Hybrid Gateway If you no longer want to iew the IBM Tioli Monitoring managed systems in the Performance Management console, uninstall the IBM Performance Management Hybrid Gateway. Procedure In the Hybrid Gateway install_dir/hybridgateway/bin directory (such as /opt/ibm/hybridgateway/bin), run the following command:./hybridgateway.sh uninstall 200 IBM Monitoring: Installation and Setup Guide

207 Results The Hybrid Gateway is remoed and a message confirms that it was uninstalled successfully. If you hae any applications in the Performance Management console that include hybrid agents, the hybrid agents continue to appear until the monitoring infrastructure processes their remoal. What to do next To remoe any hybrid agent managed systems from an application in the Performance Management console, follow the instructions in Managing applications on page 206 for editing an application. If instead of successful remoal of the software you get an error message similar to the one shown in this example, reiew the log file for the possible causes: error: Failed dependencies: ibm-jaa-x86_64-jre is needed by (installed) smai-kafka el6.x86_64 Uninstallation failed. The uninstaller was unable to remoe some of the components, please inspe log file ("/tmp/hybridgateway/logs/uninstall-hybridgateway log") for more inform The error that is shown in the example occurred because the ibm-jaa-x86_64-jre is required by an externally installed package on the system. The installer does not remoe the JRE because it would likely render the other package nonfunctional. As a workaround, uninstall the products with the dependency on ibm-jaa-x86-64-jre before you uninstall the Hybrid Gateway. Managing the Hybrid Gateway Use the commands aailable for the IBM Performance Management Hybrid Gateway serice to start or stop it, to check the status, to uninstall the Hybrid Gateway, and to collect the log files if instructed by IBM Support. About this task These steps assume that the Hybrid Gateway installation directory is /opt/ibm/. On the system where the Hybrid Gateway is installed, take any of the following steps from the command prompt: Procedure To start the Hybrid Gateway serice, enter /opt/ibm/hybridgateway/bin/ hybridgateway.sh start. To stop the Hybrid Gateway serice, enter /opt/ibm/hybridgateway/bin/ hybridgateway.sh stop. To check the status of the Hybrid Gateway serice, enter /opt/ibm/ hybridgateway/bin/hybridgateway.sh status. To uninstall the Hybrid Gateway, enter /opt/ibm/hybridgateway/bin/ hybridgateway.sh uninstall. See also Uninstalling the Hybrid Gateway on page 200. To check the Hybrid Gateway log files, go to /opt/ibm/wlp/usr/serers/ hybridgateway/logs. To collect the Hybrid Gateway log files for IBM Support, enter /opt/ibm/hybridgateway/bin/collectlogs.sh. The log files are collected and a message shows the location of the compressed log files and asks you to return them to IBM Support. Chapter 7. Integrating with other products 201

208 Integrating with Netcool/OMNIbus You can forward eents from IBM Application Performance Management into your on-premises IBM Tioli Netcool/OMNIbus eent manager. Configuring the integration for Netcool/OMNIbus To enable integration with Netcool/OMNIbus, you must copy the eent rules to the Probe for Tioli EIF and modify them, update the Netcool/OMNIbus ObjectSerer and the database schema, and configure the Performance Management serer to forward eents. About this task After installation of the Performance Management serer, the required configuration files are in the install_dir/omnibus directory: itm_apm_db_update.sql itm_eent.rules itm_apm_eent.rules 202 IBM Monitoring: Installation and Setup Guide Important: You must complete these steps een if your Probe for Tioli EIF and Netcool/OMNIbus ObjectSerer is already integrated with IBM Tioli Monitoring, IBM SmartCloud Monitoring - Application Insight, IBM SmartCloud Application Performance Management, or a preious fix pack of Performance Management (SaaS). In this procedure, when you follow links to the IBM Tioli Monitoring documentation, complete only the steps that are proided at the linked page. Procedure 1. Copy the itm_eent.rules and itm saas_eent.rules files to the Probe for Tioli EIF installation directory. By default, this directory is: /opt/ibm/tioli/netcool/omnibus/probes/linux2x86 C:\IBM\Tioli\Netcool\omnibus\probes\win32 2. Open the Probe for Tioli EIF tioli_eif.rules file in a text editor, then uncomment the line that references the itm_eent.rules file. For detailed steps, see Updating the rules files of the EIF probe in the IBM Tioli Monitoring documentation. 3. If you are using a multitier OMNIbus solution, complete all the tasks as described in the Updating the Netcool/OMNIbus ObjectSerer with IBM Tioli Monitoring attributes, tables, and triggers section. 4. Update the Netcool/OMNIbus ObjectSerer database schema by loading the itm_saas_db_update.sql file into the database by using one of the following commands: nco_sql For example: $OMNIHOME/bin/nco_sql -user username -password password -serer serer_name path_to_file/itm_saas_db_update.sql isql For example: type path_to_file\itm_saas_db_update.sql %OMNIHOME%\..\bin\isql -U username -P password -S serer_name Important: The following error messages might be displayed when running the scripts:

209 Object exists and Attempt to insert duplicate row, if the scripts were run preiously (for example, for integration with an earlier ersion of IBM Performance Management or with Tioli Monitoring). ERROR=Object not found on line 4 of statement "-- A workspace table for the ITM eent clear automation..." at or near itm_eent_clear. ERROR=Object not found on line 1 of statement "delete from alerts.itm_problem_eents;..." at or near itm_problem_eents. ERROR=Object not found on line 1 of statement "drop table alerts.itm_problem_eents;..." at or near itm_problem_eents. These error messages are harmless; no action is required for any of them. 5. Repeat the preious step so that the file has been loaded into the Object Serer two times to ensure all dependencies were loaded correctly. 6. Start (or restart) the Probe for Tioli EIF. 7. Configure the Performance Management serer to forward eents to Netcool/OMNIbus: a. Log in to the Performance Management console. b. Select System Configuration > Adanced Configuration. c. In the Eent Manager category, set the EIF Eent Target(s) field to include the host name or IP address of the host where Netcool/OMNIbus is installed. d. If necessary, change the EIF Port setting to match your enironment. e. Click Sae. Results Your Netcool/OMNIbus integration is now complete. If your Probe for Tioli EIF and Netcool/OMNIbus ObjectSerer are already integrated with IBM Tioli Monitoring, IBM SmartCloud Monitoring - Application Insight, IBM SmartCloud Application Performance Management, or Performance Management (SaaS), this configuration enables new fields. Integrating with Operations Analytics - Log Analysis When your enironment includes IBM Operations Analytics - Log Analysis (SCALA), you can integrate it to enable searching through application logs in the Performance Management console. About this task Integrating with your installed Log Analysis application inoles editing the search.properties file on the Performance Management serer and restarting the console backend components. For more information about SCALA, see the IBM Operations Analytics - Log Analysis Community ( deeloperworks/sericemanagement/ioa/log/index.html) on deeloperworks. Procedure 1. On the system where the Performance Management serer is installed, open the following file in a text editor: /opt/ibm/wlp/usr/serers/apmui/apps/customcfg/search.properties 2. Set the hide search box parameter to false: itp.hidesearchbox=false Chapter 7. Integrating with other products 203

210 If the line starts with a # (pound) symbol, delete it and any spaces before itp.hidesearchbox. 3. Set the URL parameter: unity_url= where IP_address is the fully qualified host name or IP address of the Log Analysis application and port is the port number. If the line starts with a # (pound) symbol, delete it and any spaces before unity_url. 4. After saing search.properties, change to the /usr/bin/ directory and enter the following commands to restart the components that support the Performance Management console: apm restart serer1 apm restart apmui Results The Log Analysis application is integrated and the search feature is enabled. What to do next Log in to the Performance Management console and select Performance > Application Performance Dashboard. For instructions and tips on using the search feature, click Help and open the Searching log files help topic. Related tasks: Starting and stopping serer components on page 228 Use the commands for checking the status or for starting, stopping, and recycling the Performance Management serer components when necessary for maintenance and troubleshooting tasks. 204 IBM Monitoring: Installation and Setup Guide

211 Chapter 8. Administering Administering the Performance Management infrastructure and agents inoles maintenance tasks such as changing passwords and customization tasks such as adding and editing applications. Starting the Performance Management console Log in to the Performance Management console from your browser to reiew the health status of your applications in the dashboards. Before you begin The URL for the login is the IP address of the Performance Management serer. To ensure the user interface is not truncated, use a minimum resolution of 1280 x Procedure 1. Open a browser window and enter the following URL where serer_host is the IP address of the serer: You can also enter although the URL is changed to the secure https and port number 9443 automatically. 2. After you are prompted for a logon ID, enter the following credentials for the default user or enter the credentials that were assigned by your administrator: a. User name apmadmin b. Password apmpass The initial user credentials after Performance Management serer installation are apmadmin with password apmpass. Results After you log in, the Getting Started page is displayed with learning options for User Tasks and Administrator Tasks, and links to Community Resources. What to do next Add applications for iewing dashboards of your resources in logical groupings such as Online Ordering. For instructions, see Managing applications on page 206. Create eenting thresholds to test for conditions that, when met, cause an eent to open. For example, you can hae a threshold that opens an eent after storage capacity reaches 90%. For instructions, see Threshold Manager on page 208. Add and assign users to user groups and roles to control access to the Performance Management console features and managed resources. If, instead of the Getting Started page or Application Performance Dashboard, your browser goes to the IBM website, your user ID has no permissions to the Performance Management console. Copyright IBM Corp

212 Managing applications If no metrics are shown for a data source, download the IBM Performance Management Troubleshooting Guide from IBM Performance Management Wiki - Documentation on deeloperworks to learn more about the possible causes and resolutions. Before you can open the Application Performance Dashboards for iewing KPIs from your managed systems, you must organize your managed resources into applications. Use the tools in the naigator Applications toolbar to add or edit applications and their supporting software resources, or to remoe an application. When you add an application, you can create a new application and apply the managed resources that are aailable, or select one from any discoered applications. The Add Application dialog box displays instead of the Application Performance Dashboard if your enironment has no defined applications or My Components predefined application. Before you begin You must hae administrator role priileges to use the Edit tools in the naigator. Add, Remoe, and If you see a My Components application in the naigator, it is a predefined application that includes the managed systems that were discoered by the Performance Management infrastructure. My Components cannot be edited or deleted. To see a ideo demonstration about adding an application, watch Application Performance Management - Define Application. About this task Complete the following steps to add, edit, or remoe an application from the Application Performance Dashboard using the tools in the Applications section of the naigator. If the Add Application dialog box is displayed instead of the Application Performance Dashboard, start at step 3 on page 207. Procedure 1. If the Application Performance Dashboard is not displayed, select it from the Performance menu or, if you are in the Getting Started page, click View Application Status > Start Now. 2. In the Applications section of the naigator, use the tools to add, remoe, or modify an application: To add an application, click. The Add Application window is displayed. To modify an application, select it from the All My Applications list and click. The Edit Application window is displayed. To remoe an application, select it from the All My Applications list and click. After you click OK to confirm, the application is deleted. Repeat 206 IBM Monitoring: Installation and Setup Guide

213 this step for any other applications that you want to delete. This method does not uninstall the supporting components; only their appearance in the Application Dashboard. 3. Optional: If you are adding an application, you can click Read to open the Read Application window with a list of any discoered applications, and take one or more of the following steps. Click Detail to see the components of an application. Select the radio button for the application that you want to use, and click Sae. The Read Application window closes, the source repository is displayed in the Application read from: field, and the components are listed in Application components. Click Cancel to close the window without making a choice. A discoered application can sae you the effort of defining an application. 4. Optional: Enter or edit the name of your application in the Application name field. You can add a description in the Description field. Do not use the!"% & *?<>}{symbols in the name or description: 5. In the Template field, keep the Custom Application template or select a different template using the button, and click Sae. Any associated component types and instances are shown in the Application components list. If you are editing an application, you cannot specify a different template, except for Custom Application. 6. To add components and instances to the application, take the following steps. a. Click and, in the Select Component window that opens, select a component from the list. The Component Editor is displayed. b. Click an instance to select it or use the toolbar to search for instances that contain the text in the search text box, select all instances, or clear all instances. You can also edit the component name, which is used as the display name in the naigator for this application. c. Click Add to add the instance or instances, and click Back. d. You can select another component to add instances to, or click Close. The Application components list is updated with the new component names. A number in parentheses after the name indicates how many instances are associated with the component. 7. To edit a component name or change the instance that is associated with it, select the component from the Application components list and click : a. To associate a different instance with the component, search for and select the instance that you want. b. To change the component name that is used as the display name in the naigator for this application, edit the Component name field. c. Click Sae. The Application components list is updated with the changes that you made. 8. To remoe a component or instance from the application, select it and click. Click OK to confirm that you want to remoe it. 9. If other instances are related to the components in the Application components list, a button that shows the number of related instances is displayed and you can take the following steps: a. Click the button to see the related instances in the Updated Details window. A bar is shown for each type of update, with the name of the instance below the bar. For example, if one of the components was remoed, it shows below the Deleted components bar. Chapter 8. Administering 207

214 b. Select one or more instances and click Sae to update the Application resources list. 10. Select from the Roles to access this application list and click Sae. Only users with the assigned roles can iew the application data in the dashboard. 11. When you are finished creating or editing the application, close the application editor by clicking Sae to sae your changes, or Cancel to undo the changes. Results Threshold Manager The new or edited application is displayed in the Application Dashboard and the naigator Applications section. When the application is selected, the components are displayed in the Groups section. If you deleted an application, it is no longer displayed. Use the Threshold Manager to reiew the predefined thresholds for a monitoring agent and to create and edit thresholds. Thresholds are used to compare the sampled alue of an attribute with the alue set in the threshold. If the sampled alue satisfies the comparison, an eent is opened. The eent closes automatically when the threshold comparison is no longer true. After you click System Configuration > Threshold Manager, the page is displayed with a table of the thresholds that were defined for the selected data source type. The data types that display when you click the Data Source Type list box are the types of monitoring agents that are installed in your managed enironment. Select the data type for which you want to create or iew thresholds. The table lists all the thresholds that were created for the selected data type, and has tools for managing thresholds: New opens the Threshold Editor for defining a threshold for the selected data type. Select a threshold and click Edit to open the Threshold Editor for editing the definition. Select a threshold that you no longer want and click Delete. After you confirm that you want to delete the threshold, it is remoed from the list and from any resource groups that it was assigned to. Any open eents for the threshold are closed. For a long list, you can click inside the filter text box and type the beginning of the alue to filter by. As you type, the rows that do not fit the criteria are filtered out. To clear the filter, click the x in the filter box or press the Backspace key. Restriction: Any managed systems in your enironment that are in the IBM Tioli Monitoring domain are not aailable for inclusion in resource groups nor can you create eenting thresholds for them. 208 IBM Monitoring: Installation and Setup Guide

215 Threshold Editor After you click New or select a threshold and click Edit, the Threshold Editor is displayed with the following fields: Name Enter a name for the threshold that users can see in the dashboards. The name must begin with a letter and can be up to 31 letters, numbers, and underscores, such as Aerage_Processor_Speed_Warning. All thresholds must hae unique names. Category Select the category for grouping eents in the dashboard. Description Optional. A description is useful for recording the purpose of the threshold that users can see in the Threshold Manager. Seerity Select the appropriate eent seerity from the list: Fatal, Critical, Minor, Warning, or Unknown. Note that the Eents tab of the Application Performance Dashboard consolidates the seerities: Fatal and Critical eents show as ; Minor and Warning eents show as ; and Unknown eents show as. Interal Enter or select the time to wait between taking data samples in HHMMSS format, such as for 15 minutes. For sampled-eent thresholds, the minimum interal is (30 seconds) and the maximum is (23 hours, 59 minutes, and 59 seconds). A alue of (six zeros) indicates a pure eent threshold. Pure eents are unsolicited notifications. Thresholds for pure eents hae no sampling interal, thus they hae no constant metric that can be monitored for current alues. (See also System Configuration > Adanced Configuration > Eent Manager > Pure Eent Close Time.) Required consecutie samples Specify how many consecutie threshold samples must ealuate to true before an eent is generated: For any threshold with a setting of 1 and a sample that ealuates to true, an eent is generated immediately; a setting of 2 means that two consecutie threshold samples must ealuate to true before an eent is opened. Data set Select the data set (attribute group) for the type of data to be sampled. The attributes that are aailable for inclusion in the condition are from the chosen data set. If the threshold has multiple conditions, they must all be from the same data set. Be aware that some data sets for the monitoring agent might be unaailable for selection. To get a short description of a data set, hoer the mouse oer the name. You can get the complete description of the data set and attributes by clicking the Learn more link in the hoer help. You can also click Help > Help Contents or Help > Documentation in the naigation bar, and open the help or download the reference for the monitoring agent. Display item Optional. For multiple row data sets only. After a row ealuation causes an Chapter 8. Administering 209

216 eent to open, no more eents can be opened for this threshold on the monitored system until the eent is closed. By selecting a display item, you enable the threshold to continue ealuating the other rows in the data sampling and open more eents if other rows qualify. As well, the display item is shown in the Eents tab of the Application Performance Dashboard so that you can easily distinguish among the rows for which eents were opened. Only certain key attributes can be designated as display items, and are displayed in the list. Logical Operator Ignore this field if your threshold has only one condition. If you are measuring multiple conditions, select one of the following operators before you click New to add a second (or third, and so on) condition: And (&) if the preious condition and the next condition must be met for the threshold to be breached Or ( ) if either of them can be met for the threshold to be breached A mix of logical operators is not supported; use either all And operators or all Or operators. The threshold can hae up to nine conditions when the Or operator is used; up to 10 conditions when the And operator is used. Conditions The threshold definition can logically include multiple simultaneous thresholds or conditions. Click New to add a condition. Select a condition and click Edit to modify the expression, or click Delete to remoe the expression. After you click New or Edit, complete the fields in the Add Condition or Edit Condition dialog box that opens: Count For data sets that return multiple rows for each data sample, you can hae each row that meets the criteria of the condition counted. An eent is opened after the count Value has been reached and any other conditions in the formula hae been met. For example, if the number of zombie processes exceeds 10, issue an alert. In the following example, the condition is true when more than 10 rows hae been counted: Attribute Timestamp, Operator Greater Than, Value 10. Select the Count check box, the Attribute to be counted, the relational Operator, and count Value. If the formula has multiple conditions, they must use the And Boolean operator. Count and Time Delta are mutually exclusie: If you select the check box for one function, the other function is disabled. The attribute cannot be a system identifier, such as Serer Name or ORIGINNODE, be specified as the Display Item, orbe from a data set for which the threshold opens pure eents. Time Delta Use the Time Delta function in a condition to compare the sampled time stamp (such as recording time) with the specified time difference. After you select the Time Delta check box, the Time Delta field is displayed for you to combine + (plus) or - (minus) with the number of Days, Hours, Minutes, or Seconds. Select Sampled Time or Specific Time as the Value to use in the comparison. 210 IBM Monitoring: Installation and Setup Guide

217 In the following Eent Log example, the formula compares the time the eent was logged with the time stamp from the data sampling. If the eent occurred seen days earlier, the comparison is true. If the relational operator were changed to Less Than or Equal, the comparison would be true after 8 days, 9 days, and so on: Attribute Timestamp, Time Delta -7 Days, Operator Equal, Value Entry Time. Attribute Select the attribute that you want to compare in this condition. To see a short description of the attribute, hoer the mouse oer the name in the dropdown list. Operator Select the relational operator for the type of comparison: Equal, Not Equal, Greater than, Greater than or Equal, Less than, Less than or equal, Regular expression equals, orregular expression not equals. You can also select the Missing function, which compares the alue of the specified metric with a list of alues that you supply. The condition is true when the alue does not match any in the list. This function is useful when you want notification that something is not present in your system. Requirements and restrictions: The selected metric must be a text attribute: time and numeric attributes cannot be used Separate each alue with a comma (,), for example, fred,mary,jean You can hae only one Missing condition in a threshold Missing must be the last condition in the formula. If other conditions are required, enter them before adding the Missing function. Otherwise, all subsequent rows are disabled Value Enter the alue to compare by using the format that is allowed for the metric, such as 20 for 20% or 120 for 2 minutes. Group assignment Assign a resource group to hae the threshold distributed to the monitored systems of the same type within the resource group. All the resource groups that are aailable for adding to the group are shown in the list. If you want to distribute the threshold to all monitored systems of the same agent type, assign the My Components group to this threshold. A threshold with no group assigned is distributed to no monitored systems and remains stopped until it is distributed to a resource group. To assign groups to the threshold, select the check box of one or more resource groups. If the list of assigned groups is long, you can select Show only selected groups. If no resource groups are aailable, create one in the Resource Group Manager. You can also assign a threshold to a resource group from the Resource Group Manager. For more information, see Resource Group Manager on page 212. Execute command After an eent is opened for a threshold that ealuates to true, you can hae a command or script of commands run automatically on the Chapter 8. Administering 211

218 Resource Group Manager monitored system for which the eent was opened. For example, you might want to log information, trigger an audible beep, or stop a job that is oerusing resources. The following options control how often the command is run: Select On first eent only if the data set returns multiple rows and you want to run the command for only the first eent occurrence in the data sample. Clear the check box to run the command for eery row that causes an eent. Select For eery consecutie true interal to run the command eery time the threshold ealuates to true. Clear the check box to run the command when the threshold is true, but not again until the threshold ealuates to false, followed by another true ealuation in a subsequent interal. After you click Sae, the threshold is applied to all monitored systems of the same data type within the assigned resource groups. Tip: You can control eent behaior and eent forwarding through the Eent Manager options in the Adanced Configuration page. Your monitored enironment might hae multiple monitored systems that can be categorized by their purpose. Such systems often hae the same threshold requirements. Use the Resource Group Manager to organize monitored systems into groups that you can assign eenting thresholds to. After you click System Configuration > Resource Group Manager, the page opens with a table of defined resource groups. Initially, only one group is shown: My Components, which contains all the monitoring agents that are installed in your monitored enironment. The table has tools for managing resource groups: New opens the Resource Group Editor for assigning managed systems and thresholds. Select a resource group and click Edit to open the Resource Group Editor for changing the managed system and threshold assignments. Select a resource group that you no longer want and click Delete. After you confirm the deletion, any thresholds that were assigned to the group must be assigned to another group if you want them to continue to run on your managed systems. You can click inside the filter text box and type the alue to filter by. As you type, the rows that do not fit the criteria are filtered out. To clear the filter, click the x in the filter box or press the Backspace key. Resource Group Editor After you click New to add a group or you select a resource group and click Edit, the Resource Group Editor is displayed with the following fields: Group name This is the name of the group and is required. You can change an existing name, and all references to the group are updated automatically after you sae your changes. 212 IBM Monitoring: Installation and Setup Guide

219 Group description Optional. Add a description of the group organization. The description is displayed in the Resource Group Manager. Agent assignment All the managed systems that are aailable for adding to the group are shown in the agent list by their managed system names and two-character product code. You can click a column heading to sort the list by agent name or type. To populate the group, select the check box of one or more managed systems. You can select Show only selected groups to hide the unassigned managed systems. Restriction: Any managed systems in your enironment that are in the IBM Tioli Monitoring domain are not aailable for inclusion in resource groups nor can you create eenting thresholds for them. Threshold assignment All the thresholds that were predefined or added through the Threshold Manager are shown in the threshold list by their name and two-character product code. You can click a column heading to sort the list by threshold name or agent type. To add a defined threshold to the group, select the check box next to the name; to remoe a threshold from the group, clear the check box. The thresholds that you assign to the group are distributed to eery managed system in the group of the same agent type. Although you can assign thresholds of any monitoring agent type to a group, the assigned thresholds are distributed only to managed systems of the same type that are members of the group. For example, if you assign the MySQL_Process_Down threshold to the group, it is included in the group, but is distributed only to the Monitoring Agent for MySQL managed systems that belong to the group. You can also assign a resource group to a threshold from the Threshold Manager. Configure notification Aailable with IBM Performance Management (SaaS): Click Configure notification to open the IBM IT Alert Notification application in a new browser tab or window. Use IT Alert Notification to create users and associate their addresses with resource groups for receiing eent notifications by . For more information, see Integrating with IT Alert Notification. After you click Sae, the resource group is saed with the list of resource groups. If your enironment includes the My Components predefined application, be aware that the application is maintained automatically: each discoered managed system is added to it. You cannot add or remoe managed systems manually, nor can you delete the application. If you upgraded from the preious product ersion, any thresholds and custom charts and tables that were created are added to My Components. You can also assign custom thresholds to My Components. Chapter 8. Administering 213

220 Managing user access Use the Role Based Access Control feature in IBM Performance Management to grant users the access priileges they require for their role. Security in Performance Management is based on roles. A role is a group of permissions that control the actions you can perform in Performance Management. You can create customized roles in Performance Management. You can assign users and user groups to existing default roles or to customized roles. You can assign permissions to customized roles, or you can assign more permissions to existing default roles. You can assign users and user groups to multiple roles. If a user who is not assigned to a role logs in, they are directed to the ibm.com page where the Getting Started icon is isible. The user gets a Not Authorized message if they click the Getting Started icon. Permissions are cumulatie, a user or user group is assigned all the permissions for all the roles they are assigned to. Performance Management uses the WebSphere Application Serer Liberty profile basic registry as the default method for user authentication. Alternatiely, you can use an LDAP registry for user authentication. Using WebSphere Application Serer Liberty profile basic registry for user authentication Complete the following steps if you are using WebSphere Application Serer Liberty profile basic registry for user authentication: 1. Create users and user groups in the basic user registry. The basicregistry.xml file is aailable in the /opt/ibm/wlp/usr/shared/config directory. For more information on configuring basic user registry with Liberty profile, see com.ibm.websphere.wlp.core.doc/ae/twlp_sec_basic_registry.html 2. In Performance Management, use the Role Based Access Control page to assign users and user groups to default and customized roles. For more information on working with roles, see Roles and Permissions on page 215. Note: By default, for Liberty profile basic registry, the default user is apmadmin, by default this user is a member of the Role Administrator role. Using LDAP registry for user authentication 1. Configure Performance Management to integrate with your LDAP repository. For more information, see Integrating LDAP with Performance Management on page Create users and user groups in your LDAP repository. For more information on configuring LDAP registry with Liberty profile, see Configuring LDAP user registries with the Liberty profile in the Liberty Profile knowledge center. 3. Change the default user to an LDAP user. For more information, see Changing the default user on page In Performance Management, use the Role Based Access Control page to assign users and user groups to default and customized roles. For more information on working with roles, see Roles and Permissions on page IBM Monitoring: Installation and Setup Guide

221 Note: If a user who is not assigned to a role logs in, they are directed to the ibm.com page where the Getting Started icon is isible. The user gets a Not Authorized message if they click the Getting Started icon. Roles and Permissions A role is a group of permissions that control the actions you can perform in Performance Management. Use the Role Based Access Control page to manage users and roles. There are four default roles aailable in Performance Management: Role Administrator This role is intended for users whose primary job function is to create access control policies for Performance Management. This role has all permissions. If you change the default user, the new default user is automatically a member of the Role Administrator role. This role cannot be edited. Role Administrators are preented from remoing themseles from the Role Administrator role. This restriction remoes the risk of accidentally remoing all users from the Role Administrator role. Monitoring Administrator This role is intended for users whose primary job function is to use Performance Management to monitor systems. Monitoring Administrators perform tasks such as adding monitoring applications, creating thresholds, adding groups of resources, and distributing the thresholds to these resource groups. This role can be edited. System Administrator This role is intended for users whose primary job function is to perform administration tasks for the Performance Management system. System Administrators perform tasks such as configuring the Eent Manager, or configuring the Hybrid Gateway. This role can be edited. Monitoring User This role is intended for users whose primary job function is to configure and maintain the health and state of systems that are monitored by Performance Management. This role can be edited. The following table describes the permissions that you can assign to roles, and the four aailable default roles and associated permissions: Table 21. Roles and permissions Role Administrator Monitoring Administrator System Administrator Monitoring User CreateView ModifyCreateView ModifyCreateView ModifyCreateView Modify System configuration permissions Adanced N/A U N/A N/A Χ N/A N/A U N/A N/A Χ N/A Configuration Agent N/A U N/A N/A U N/A N/A Χ N/A N/A Χ N/A Configuration Informational N/A U N/A N/A U N/A N/A U N/A N/A U N/A Pages Search Proider N/A U N/A N/A U N/A N/A Χ N/A N/A Χ N/A Usage Statistics N/A U N/A N/A U N/A N/A Χ N/A N/A Χ N/A Chapter 8. Administering 215

222 Table 21. Roles and permissions (continued) Role Administrator Monitoring Administrator System Administrator Monitoring User CreateView ModifyCreateView ModifyCreateView ModifyCreateView Modify Role Based Access Control N/A U N/A N/A Χ Χ N/A Χ N/A N/A Χ N/A Resource permissions Performance Management Dashboard N/A U U N/A U U N/A Χ Χ N/A U Χ Applications U U N/A U U N/A Χ Χ N/A Χ U N/A Resource Group Manager N/A U N/A N/A U N/A N/A Χ N/A N/A Χ N/A Resource Groups U U N/A U U N/A Χ Χ N/A Χ Χ N/A Threshold Manager N/A U N/A N/A U N/A N/A Χ N/A N/A Χ N/A Where U indicates that members of this role hae this permission Χ indicates that members of this role do not hae this permission N/A indicates that this permission does not exist For more information on how to work with roles, users and permissions, see Working with roles, users, and permissions. The following table describes the actions that are associated with each permission: Table 22. Permissions Permission Adanced Configuration Description If you hae iew permission, when you click, Adanced Configuration is isible. You can make and sae changes in the Adanced Configuration page. Agent Configuration If you hae iew permission, when you click, Agent Configuration is isible. You can make and sae changes in the Agent Configuration page. Informational Pages If you hae iew permission, the and icons are isible in the menu bar. Note: If a user clears Show this page at startup when the Getting Started page appears, they get a "Permission Denied" message upon subsequent logins. They are still able to naigate to the Getting Started page and any other areas that they hae permission to. Search Proider If you hae iew permission, when you click, System Configuration, Configure Search Proiders is isible. You can make and sae changes in the Configure Search Proiders page. Usage Statistics If you hae iew permission, when you click, Usage Statistics is isible. In the Usage Statistics, you can analyze VM usage. Role Based Access If you hae iew permission, when you click, Role Based Control Access Control is isible. 216 IBM Monitoring: Installation and Setup Guide

223 Table 22. Permissions (continued) Permission Description Performance Management Dashboard If you hae iew permission the icon is isible on the menu bar, and you can access the Performance Management Dashboard. You can create custom iews in Attribute Viewer and sae them for your own use. Applications Resource Group Manager Resource Groups If you hae modify permission, you can change content in the Performance Management Dashboard, for example, you can create custom iews in Attribute Viewer and share them with others. Also, if you hae modify permission, the Actions>Edit option is aailable in component pages, but you also need the create permission for applications to see Actions>Edit in component pages. If you hae create permission, you can create, modify, and delete applications. the icons appears in the Application Dashboard. If you hae iew permission, in the Application Dashboard, you can iew applications, but the icons are not isible. If you hae iew permission, when you click, Resource Group Manager is isible. If you hae create permission, you can create, modify, and delete resource groups, the icons are isible in the Resource Group Manager. Note: Resource Group Manager is used to organize monitored systems into groups, so that eenting thresholds can be assigned to these groups. Therefore, it is important if you are assigning the create permission for Resource Groups to a role, that in conjunction you assign the iew permission for Threshold Manager. If you hae iew permissions, in the Resource Group Manager page, you can iew resource groups and the systems in them, but the icons are not isible. Note: If you do not hae iew permission to Threshold Manager, then, you will not be able to see the thresholds that are assigned to Resource Groups. Threshold Manager If you hae iew permission, when you click, Threshold Manager is isible. Working with roles, users, and permissions Use the Role Based Access Control page to work with roles, users, and permissions. Procedure To filter the list of roles, users or user groups showing in the Role Based Access Control page, complete the following steps: 1. Select System Configuration> Role Based Access Control. 2. Click inside the Filter text box and type the partial or full text to filter by. As you type, any rows that do not contain what you typed in the filter box are remoed from the table. 3. To remoe the quick filter, delete the alue or click the x. 4. To apply the filter, click. Chapter 8. Administering 217

224 To create a new customized role, complete the following steps: 1. Select System Configuration> Role Based Access Control. 2. In the Roles tab, click. The Role Editor page is displayed. 3. In the Assign Users to Roles tab, select the User Groups tab, or the Indiidual Users tab and select the users and user groups you want to add to the role. 4. In the Assign Permissions to Roles tab, select the System Configuration Permissions or the Resource Permissions tab, and select the permissions that you want to assign to the role. 5. Click Sae. To edit an existing default or customized role, complete the following steps: 1. Select System Configuration> Role Based Access Control. 2. In the Roles tab, click. The Role Editor page is displayed. 3. In the Assign Users to Roles tab, click the User Groups tab, or the Indiidual Users tab and select the users or user groups you want to add to the role. 4. In the Assign Permissions to Roles tab, select the System Configuration Permissions or the Resource Permissions tab, and select the permissions that you want to assign to the role. 5. Click Sae. To delete a role, complete the following steps: 1. Select System Configuration> Role Based Access Control. 2. In the Roles tab, select the role that you want to delete and click.a confirmation message is displayed, click OK. Note: When you delete a role, the users that are members of that role are not deleted. They are still aailable in the Indiidual Users tab, and can be assigned to another role by a Role Administrator. To edit the permissions for an indiidual user or user group, complete the following steps: 1. Select System Configuration> Role Based Access Control. 2. In the Indiidual User or User Groups tab, select the user or user group you want to edit, and click. The Indiidual User Editor page is opened. 3. Select the role or roles you want to assign to the user. 4. Click Sae. To create a cs file that summarizes the permissions for a user or user group, complete the following steps: 1. In the Indiidual User or User Groups tab, select the required user or user group, and click. The Indiidual User Editor or User Group Editor page is opened. 2. Click Export Summary. 3. Select Sae File, click OK. A cs file that summarizes the permission for the user or user group is saed to the specified location. Results Role and permission assignment takes effect immediately when you click Sae. 218 IBM Monitoring: Installation and Setup Guide

225 Integrating LDAP with Performance Management To configure Performance Management to use LDAP for user authentication, update the ldapregistry.xml file with your LDAP serer information and then update the serer.xml to reference ldapregistry.xml. Procedure 1. Update the ldapregistry.xml in the /opt/ibm/wlp/usr/shared/config/ directory. The following examples show how to update the ldapregistry.xml file for IBM Tioli Directory Serer and Microsoft Actie Directory: Example for IBM Tioli Directory Serer <ldapregistry id="ldap" realm="sampleldapidsrealm" host="ldapserer.mycity.mycompany.com" port="389" ignorecase="true" basedn="o=mycompany,c=us" ldaptype="ibm Tioli Directory Serer" sslenabled="true" sslref="ldapsslsettings"> <idsfilters userfilter="(&(uid=%)(objectclass=eperson))" groupfilter="(&(cn=%)( (objectclass=groupofnames) (objectclass=groupofuniquenames)(objectclass=groupofurls)))" useridmap="*:uid" groupidmap="*:cn" groupmemberidmap="mycompany-allgroups:member;mycompany-allgroups:uniquemember; groupofnames:member;groupofuniquenames:uniquemember"> </idsfilters> </ldapregistry> <ssldefault sslref="ldapsslsettings" /> <ssl id="ldapsslsettings" keystoreref="ldapkeystore" truststoreref="ldaptruststore" /> <keystore id="ldapkeystore" location="${serer.config.dir}/ldapsslkeystore.jks" type="jks" password="{xor}cdo9hgw=" /> <keystore id="ldaptruststore" location="${serer.config.dir}/ldapssltruststore.jks" type="jks" password="{xor}cdo9hgw=" /> Example for Microsoft Actie Directory <ldapregistry id="ldap" realm="sampleldapadrealm" host="ldapserer.mycity.mycompany.com" port="389" ignorecase="true" basedn="cn=users,dc=adtest,dc=mycity,dc=mycompany,dc=com" binddn="cn=testuser,cn=users,dc=adtest,dc=mycity,dc=mycompany,dc=com" bindpassword="testuserpwd" ldaptype="microsoft Actie Directory" sslenabled="true" sslref="ldapsslsettings"> <actiedfilters userfilter="(&(samaccountname=%)(objectcategory=user))"&(samaccountname=%)(object groupfilter="(&(cn=%)(objectcategory=group))" useridmap="user:samaccountname" groupidmap="*:cn" groupmemberidmap="memberof:member" > </actiedfilters> </ldapregistry> <ssldefault sslref="ldapsslsettings" /> <ssl id="ldapsslsettings" keystoreref="ldapkeystore" truststoreref="ldaptruststore" /> <keystore id="ldapkeystore" location="${serer.config.dir}/ldapsslkeystore.jks" type="jks" password="{xor}cdo9hgw=" /> <keystore id="ldaptruststore" location="${serer.config.dir}/ldapssltruststore.jks" type="jks" password="{xor}cdo9hgw=" /> 2. Update the serer.xml file in the /opt/ibm/wlp/usr/serers/apmui/ directory to use ldapregistry.xml. Complete the following steps: Chapter 8. Administering 219

226 a. Comment out the line that refers to the basic registry as follows: <!--include optional="false" location="${shared.config.dir}/basicregistry.xml"/--> b. Uncomment the file the refers to the LDAP registry as follows: <include optional="false" location="${shared.config.dir}/ldapregistry.xml"/> c. Sae the serer.xml file. Results The LDAP repository users and user groups are now aailable in the Role Based Access Control page, where you can assign them to default and customized roles. Note: When you change user registry, old policies are presered. Users from the old user registry who were assigned to roles but who do not exist in the new user registry are shown as a url in Role Based Access Control page. You can remoe these users from a role. What to do next After you change user authentication to LDAP, you will need to change the default user, for information on changing the default user, see Changing the default user. Changing the default user About this task The default user for Performance Management is apmadmin, and the default realm is customrealm. By default apmadmin is a member of the Role Administrator role. This default user is defined in the basicregistry.xml file in the /opt/ibm/wlp/usr/shared/config/ folder. You might need to change the default user for one of the following reasons: You want to use a different user who is defined in the user registry. You want to use a different realm name in the user registry. You are changing user authentication from basic registry to LDAP, or you are switching to a different LDAP registry. Note: When you change the user registry, old policies are presered. Users from the old user registry who were assigned to roles but who do not exist in the new user registry are shown as a url in the Role Based Access Control page. You can remoe these users from a role. Procedure 1. Naigate to the opt/ibm/wlp/usr/serers/serer1/cscs/conf directory. 2. Create a file called cscsroleadmin.new. 3. Add a new default user to cscsroleadmin.new, for example, user:myrealmname/ uid=myuser,cn=myrealmname,ou=marketing,o=mycompany,c=us Where user is a prefix MyRealmName is the realm specified in the registry configuration file (basicregistry.xml or ldapregistry.xml) myuser is the user defined in the specified registry prefixed with "/" 220 IBM Monitoring: Installation and Setup Guide

227 4. Sae cscsroleadmin.new. 5. Restart the Performance Management serer using the following commands: apm stop_all apm start_all For more information about how to change user authentication from basic registry to LDAP, see Integrating LDAP with Performance Management on page 219. Configure audit logging for role based access control actiity The audit logging feature in Performance Management logs significant eents relating to role based access control actiity. The output of the audit logging feature helps you to determine the following information: Who (user, serice, or process) initiated the action? What actiity occurred and what was the result? When did the actiity occur? Where was the actiity obsered? What resource did the actiity target? Where did the actiity get initiated? Where was the target of the actiity? Note: The audit logging feature does not capture eents relating to user authentication, for example, it does not capture if a user is created or deleted, but it does capture if a user is added to a role, or deleted from a role. All actiity within the Role Based Access Control page conducted by a role administrator is captured. Each audit log eent is written as a single line in the audit log file, a single audit log eent has the following general structure: <AuditEent...> <Who... /> <What.../> <When.../> <OnWhat.../> <Where.../> <WhereFrom.../> <WhereTo.../> </AuditEent> <AuditEent...> The PD Collector tool is the problem determination collection tool, used to gather required logs and other problem determination information. The output of the PD Collector tool is requested by IBM Support if you open a support ticket. The audit log and trace log files are collected when you run the PD collector tool. For more information, see the Chapter 11, Troubleshooting and support, on page 249. Configuring audit logging The location of the audit log files, the number of log files that are maintained, and the maximum size of log files is controlled in the w7auditconfig.properties file that is located in the install_dir/wlp/usr/serers/serer1/cscs/conf directory. Procedure 1. Open the w7auditconfig.properties file that is located in the install_dir/wlp/usr/serers/serer1/cscs/conf directory. Chapter 8. Administering 221

228 Where install_dir is the directory where IBM Monitoring is installed 2. To specify the maximum size in bytes for a single audit log file, edit the following property: AUDIT_LIMIT_BYTES= The default is The audit logging feature supports a generational log file approach. New audit log files are created when an audit log file reaches the maximum size as specified in the AUDIT_LIMIT_BYTES property. 3. To specify the maximum number of unique audit log files that are created before wrapping occurs, edit the following property: AUDIT_COUNT=10 The default is To specify the directory where audit log files are saed, edit the following property. AUDIT_PATH=install_dir/wlp/usr/serers/serer1/logs Where install_dir is the directory where IBM Monitoring is installed The audit log files hae the following naming conention: hostname_timestamp.w7_audit.log Where hostname is the short host name of the machine where the audit logging is occurring timestamp is the time stamp when the audit log file is created Configuring trace logging for audit logging If more detailed audit logging is required, enable the tracespecification attribute in the install_dir/wlp/usr/serers/serer1/serer.xml file. Procedure 1. Open install_dir/wlp/usr/serers/serer1/serer.xml file. Where install_dir is the directory where IBM Monitoring is installed 2. Add the following trace options to the tracespecification attribute: com.ibm.smai.cscs.serice=finest com.ibm.apm.cscs.audit.impl=finest com.ibm.tioli.audit.w7.*=finest Ensure that each option is delimited by a colon Results The trace statements are written to the install_dir/wlp/usr/serers/serer1/ logs/trace*.log file. Where install_dir is the directory where IBM Monitoring is installed 222 IBM Monitoring: Installation and Setup Guide

229 Administering agents Use the IBM Performance Management features and functions that are aailable for managing your monitoring agents. Using agent commands The same scripts that you use to install monitoring agents on the monitoring agent can also be used to check the status of an installed agent, stop or start it, or uninstall the agent. About this task The agent name and agent codes are proided for your reference. Use the agent name in the following commands: name-agent.sh name-agent.bat Where name is the name of the agent that is specified in Table 23. Table 23. Agent names and agent codes Monitoring agent name Two letter agent code Monitoring Agent for DataPower datapower qz Monitoring Agent for DB2 db2 ud Monitoring Agent for Microsoft Exchange msexch ex Serer Monitoring Agent for HMC Base hmc_base ph Monitoring Agent for HTTP Serer http_serer hu Monitoring Agent for Microsoft Hyper-V mshyper h Serer Monitoring Agent for Microsoft Internet msiis q7 Information Serices Monitoring Agent for JBoss jboss je Monitoring Agent for Linux KVM linux_km 1 Monitoring Agent for Linux OS os lz Monitoring Agent for Microsoft.NET dotnet qe Monitoring Agent for Microsoft SQL Serer mssql oq Monitoring Agent for MongoDB mongodb kj Monitoring Agent for MySQL mysql se Monitoring Agent for Node.js nodejs nj Monitoring Agent for Oracle Database oracle_database rz Monitoring Agent for PHP php pj Monitoring Agent for PostgreSQL postgresql pn Monitoring Agent for Python python pg Monitoring Agent for Ruby ruby km Monitoring Agent for Tomcat tomcat ot Monitoring Agent for UNIX OS os ux Chapter 8. Administering 223

230 Table 23. Agent names and agent codes (continued) Monitoring agent name Two letter agent code Monitoring Agent for VMware VI mware_i m Monitoring Agent for WebSphere was yn Applications Monitoring Agent for WebSphere wim d0 Infrastructure Manager Monitoring Agent for Windows OS os nt Response Time Monitoring Agent rt t5 Procedure On the system or VM where you want to send a command to the monitoring agent, change to the install_dir/bin directory. Enter any of the following commands where name is the agent name that is specified in Table 23 on page 223. Command./name-agent.sh status./name-agent.sh start./name-agent.sh stop./name-agent.sh prereqcheck./name-agent.sh install./name-agent.sh config instance_name path_to_silent_config_file Description Checks the monitoring agent status. Starts the monitoring agent. If the agent has instances, enter an instance name after the command. Stops the agent. If the agent has instances, enter an instance name after the command. Runs a prerequisite scan. Installs the monitoring agent. For more information, see Installing agents on page 45. Configures the monitoring agent. Run the command from the install_dir/bin directory and add the response file path if required. If the agent has instances, enter an instance name. For more information, see the information about multiple instance agents in Installing agents on Linux and AIX systems, Installing agents, About this task../name-agent.sh uninstall./smai-agent.sh uninstall_all./name-agent.sh The silent_config_file is optional. If you do not specify a file for silent configuration, you can configure the monitoring agent interactiely by following the prompts. Uninstalls the monitoring agent. For more information, see Uninstalling monitoring agents on page 54 Uninstalls all the monitoring agents on the managed system. View a description of the functions that are aailable with the script. 224 IBM Monitoring: Installation and Setup Guide

231 On the system or VM where you want to send a command to the monitoring agent, change to the install_dir\bin directory at the command prompt, for example: C:\IBM\APM\bin. Enter any of the following commands where name is the agent name that is specified in Table 23 on page 223. Command name-agent.bat status name-agent.bat start name-agent.bat stop name-agent.bat prereqcheck name-agent.bat install name-agent.bat config instance_name path_to_silent_config_file Description Checks the monitoring agent status. Starts the monitoring agent. If the agent has instances, enter an instance name after the command. Stops the agent. If the agent has instances, enter an instance name after the command. Runs a prerequisite scan. Installs the monitoring agent. For more information, see Installing agents on page 51. Configures the monitoring agent. Run the command from install_dir\bin directory and add the response file path if required. If the agent has instances, enter an instance name. For more information, see the information about multiple instance agents in Installing agents on Windows systems, Installing agents, About this task. name-agent.bat uninstall smai-agent.bat uninstall_all name-agent.bat The silent_config_file is optional. If you do not specify a file for silent configuration, you can configure the monitoring agent interactiely by following the prompts. Uninstalls the monitoring agent. For more information, see Uninstalling monitoring agents on page 54 Uninstalls all monitoring agents on the managed system. View a description of the functions that are aailable with the script. Agent Configuration page Use the Agent Configuration page to centrally configure settings for the Response Time Monitoring Agent, Ruby agent, and WebSphere Applications agent. For agents in an on-premises enironment, only the configuration settings for resource monitoring are supported and any application diagnostics or transaction tracking settings must not be changed. For agents in a SaaS enironment, some configuration settings require the Application Performance Management subscription leel and others require the Application Diagnostics subscription leel for the settings to be applied. These settings are identified in the agent-specific configuration information at the links proided in "Agent-specific usage." Chapter 8. Administering 225

232 Agent-specific usage For more information about the settings for the specific agents, see the following topics: Response Time agent: Monitoring HTTP transactions on page 141 Ruby agent: The settings for diagnostics data enablement for Ruby applications are not applicable to IBM Monitoring. WebSphere Applications agent: Dynamically configuring data collection on Agent Configuration page on page 185 Starting Manage Monitoring Serices on Windows systems The agents for applications that run on Windows systems hae a Manage Monitoring Serices utility that you can use to reiew the ersion of each installed agent and to perform administratie functions such as starting or stopping the agent, or as specified in the agent configuration instructions. Restriction: The supported method for configuring agents is through the command prompt or as instructed in the agent configuration task. Do not use Manage Monitoring Serices to configure custom agents from IBM Agent Builder or to configure other agents unless specified in the agent configuration instructions. If you choose to configure the agent, you will be prompted for Tioli Enterprise Monitoring Serer information, which is not suitable for agents in the Performance Management enironment. About this task Complete one of the following steps to start Manage Monitoring Serices: Procedure Click Start > All Programs > IBM Monitoring agents > Manage Monitoring Serices. At the command prompt, enter kinconfig.exe This is the command that is combined with parameters to configure an agent in silent mode. Be sure not to enter any parameters with this command. Results The Manage Monitoring Serices window is displayed, along with the aailability status and the release number of each agent component. What to do next You can start or stop an agent or configure the parameters by right-clicking the agent, and selecting an option. Administering serer components The Performance Management serer requires some ongoing maintenance such as changing passwords and backing up the components. Use the aailable functions for serer administration tasks. Passwords and user IDs for components Various components require user IDs and passwords for access. 226 IBM Monitoring: Installation and Setup Guide

233 Table 24. Default users and passwords Default users and passwords Default user IDs and passwords are aailable for accessing some components. The following table contains a list of default user IDs, the purpose of each ID, the default password for each user ID, and the script that can be used to change the default password after the installation: Default user ID gaiandb apmadmin smadmin itmuser db2apm db2fenc1 dasusr1 Purpose Used to access the Performance Management embedded Derby configuration database Used to log in to the Performance Management console Used to authenticate with serer1 Liberty process Used to access the Prefetch data store and SCR database DB2 instance users Default password gian08pw0rd apmpass apmpass Directory and script that can be used to change the default password after the installation none /opt/ibm/ccm/apmpasswd.sh /opt/ibm/ccm/tools/smapasswd.sh db2usrpasswd@08 /opt/ibm/ccm/ db2_users_passwd.sh user_name Where user_name is itmuser db2usrpasswd@08 /opt/ibm/ccm/ db2_users_passwd.sh user_name Where user_name is db2apm, db2fenc1, ordasusr1 Changing a password You can run a script to change the password for the following users: apmadmin, smadmin, itmuser, db2apm, db2fenc1, and dausr1. About this task The Performance Management serer creates a smadmin user ID with a default password of apmpass for communication between the Performance Management components. You might need to change the password, for example, to comply with your organization's security requirements or if you changed the password but forgot it when IBM Support asked you to run the data collection tool. If you change the default password for the apmadmin user during the Performance Management serer installation, the password for the smadmin user is also changed to use the same password. Use this procedure if you want the smadmin user to use a different password from the apmadmin user password or if you want to change its password after the serer installation. Procedure Complete the procedure on the system where the Performance Management serer is installed to change the password for one of the default user IDs. 1. Open the directory where the script is located and run the script for the password you want to change: Chapter 8. Administering 227

234 Table 25. Scripts for default user passwords Default user ID Default password Directory and script for password you want to change apmadmin apmpass /opt/ibm/ccm/apmpasswd.sh smadmin apmpass /opt/ibm/ccm/tools/smapasswd.sh itmuser /opt/ibm/ccm/db2_users_passwd.sh user_name Where user_name is itmuser db2apm db2fenc1 dasusr1 /opt/ibm/ccm/db2_users_passwd.sh user_name Where user_name is db2apm, db2fenc1, or dasusr1 2. After you are prompted to proide a new password, type the password, press Enter, and retype the new password as prompted. 3. If you are changing the smadmin password, after you are prompted for the apmadmin password, type the password and press Enter. The apmadmin password is required for updating the serer connection with the new smadmin password. Results The Performance Management serer is recycled and the new password for the user is recorded. Starting and stopping serer components Use the commands for checking the status or for starting, stopping, and recycling the Performance Management serer components when necessary for maintenance and troubleshooting tasks. About this task Run any of the apm commands in the /usr/bin/ directory on the system where the Performance Management serer is installed. For each command, a short ersion is aailable and shown as Short command. Procedure Complete any of these steps: To list the aailable commands and see the syntax, enter the following command: apm --help To start or stop all serer components, enter one of the following commands: apm start_all apm stop_all Short commands: sta and spa To check whether a Performance Management serice is running or stopped, enter the following command: apm status serice_name where serice_name is one of the following serices: 228 IBM Monitoring: Installation and Setup Guide

235 Option apmui asfrest db2 kafka ksy min oslc scr serer1 Description Performance Management console component that handles incoming user interface requests. Agent interface component that includes the agent REST interface and central configuration serices HTTP serer. The REST interface is used by agents to send monitoring data that is persisted in the DB2 serer and threshold eents. The central configuration serice HTTP serer handles requests from agents for their configuration files, for example, threshold definitions. DB2 serer used to persist monitoring data and applications that are displayed in the Performance Management console. Message bus component for internal communication between components. Summarization and Pruning Agent for maintaining database partitions and pruning monitoring data in the DB2 serer. Monitoring Infrastructure Node component that maintains the list of connected agents, adanced configuration data, and threshold eents. Open Serices for Lifecycle Collaboration serice proider that registers the computer system, software serer, and application resources that are monitored by agents in the serice component registry. Serice component registry that persists application definitions and their relationships to agent resources in the DB2 serer. Performance Management console backend component that retriees monitoring data and applications from the DB2 serer and persists threshold definitions, resource group definitions, and role based access control definitions. Be aware that if you restart serer1, you must also restart the apmui serice after restarting the serer1 serice. Short command: ss If you were directed by IBM Support or a Knowledge Center topic to start, stop, or restart a particular serice, enter the command using the following syntax: apm command serice_name where command is one of the following apm commands: Option start Description Start the specified serice_name. Short command: st Chapter 8. Administering 229

236 Option stop restart Description Stop the specified serice_name. To do a force stop, insert -f or --force between apm and stop. For example, apm -f stop apmui, stops the Performance Management console immediately. Short command: sp Restart the running serice_name. Be aware that after restarting the serer1 serice, you must also restart the apmui serice. Short command: rt and serice_name is one of the serices listed in the preious step (apmui, asfrest, db2, kafka, ksy, min, oslc, scr, or serer1). Managing the JVM heap size and DB2 bufferpool Read and modify the JVM heap size and DB2 bufferpool size using the serer_size.sh command. Procedure 1. To read the recommended serer size, run the following command located in the /opt/ibm/ccm/ folder: serer_size.sh. The ouput describes the number of CPUs, memory size, and free disk space in the serer. Based on this a recommended serer size is gien, for example: Number of CPUs: 2 Memory size: 8.00 GB Free disk space: 65 GB Recommended serer size: extra_small 2. To change the serer size and DB2 bufferpool, run the serer_size.sh command again followed by the recommended size, for example, serer_size.sh small. Note, this command stops and restarts the four Liberty serers. The JVM heap size is adjusted according to the alues in the following table: Table 26. JVM heap size setting.. System size Performance Management serer) Serer1 application serer APMUI serice Asfrest (Liberty serer instance) Medium 768 MB 2048 MB 4096 MB 768 MB Small 768 MB 1536 MB 3072 MB 512 MB Extra small 512 MB 1024 MB 2048 MB 512 MB The buffer pool is adjusted according to the alues in the following table: Table 27. Medium Small Extra small Here is an example of the output: # /opt/ibm/ccm/serer_size.sh small Setting 768MB heap size for serice min. Setting 1536MB heap size for serice serer1. Setting 3072MB heap size for serice apmui. Setting 512MB heap size for serice asfrest. 230 IBM Monitoring: Installation and Setup Guide

237 Setting ENABLE_MY_COMPONENTS to false for serice apmui. Setting WAREHOUS_IBMDEFAULTBP alue to Database Connection Information Database serer = DB2/LINUXX SQL authorization ID = DB2APM Local database alias = WAREHOUS DB20000I The SQL command completed successfully. Stopping serice min (PID 305). Serice min stopped. Starting serice min Serice min started (PID 26461). Stopping serice serer1 (PID 748). Serice serer1 stopped. Starting serice serer1 Serice serer1 started (PID 26783). Stopping serice asfrest (PID 1742). Serice asfrest stopped. Starting serice asfrest Serice asfrest started (PID 29311). Stopping serice apmui (PID 1483). Serice apmui stopped. Starting serice apmui Serice apmui started (PID 27833). Backing up and restoring components Backup and recoery of data files and databases is an essential operation for any business system, particularly for data and applications that are running in production enironments. Create and follow a plan for backing up and recoering the data for all components of your Performance Management infrastructure. For disaster recoery plans, consider backing up on one serer and restoring to a second serer if the serers are at the same fix pack leel. If you switch to a different host name on the second serer, you must update the agent configurations to point to this new serer. Determining the ersion of the Performance Management serer The ersion of the Performance Management serer is required for some of the backup and restore procedures. About this task Example of ersion format: Procedure Use one of the following steps to determine the ersion number of the release: In the Performance Management console, click Help > About. Run the following command and reiew the contents of the properties file, which contains the ersion number of the serer: cat /opt/ibm/ccm/ersion_product.properties Example of file contents: #(C) Copyright IBM Corporation All rights resered. #Wed, 28 Jan :23: build= smaiversion= Chapter 8. Administering 231

238 What to do next When you enter commands for backing up or restoring some components, you use the following parameters to specify ersion: -s from_ersion In backup and restore commands, the ersion you want to back up, for example, t to_ersion In restore commands, the ersion to which you want to restore the component that was backed up, for example, Backing up components Backups are safe to perform when the Monitoring Infrastructure Node is online; there is no disruption of serice. You must back up components in order. There are interdependencies among the components, so you must schedule all backups to run in the same maintenance window. Before you back up the Performance Management infrastructure installation, ensure that you created a location on your file system, such as a mounted NFS drie, to store the output of the backup commands. Each component produces a single compressed file as the result of its backup command. If you want to maintain multiple ersions of a backup, plan to establish separate directories, because subsequent backups oerwrite the preious backup file. Back up components in the order that is listed in the table: Table 28. Backup order and descriptions of components Order to back up Component Description 1. OSLC The Open Serices for Lifecycle Collaboration serice proider registers computer system, software serer, and application resources that are monitored by agents in the serice registry. 2. CCS The agent configuration serice maintains threshold definitions, resource group definitions, and agent configuration information and is responsible for distributing this configuration to agents. 3. APM UI The Performance Management console displays monitoring information so you can understand the health of your enironment. It also proides administratie and configuration user interfaces for the monitoring infrastructure. 4. MIN The monitoring infrastructure component maintains the list of connected agents, system configuration data, and alarms or eents. 5. CSCS The security configuration serice maintains policies and role definitions and is responsible for enforcing access control to monitoring infrastructure components. 232 IBM Monitoring: Installation and Setup Guide

239 Table 28. Backup order and descriptions of components (continued) Order to back up Component Description 6. Prefetch data store This DB2 database contains the current and last 7 days of data samples from the monitoring agents. This information is used primarily to populate the Performance Management console dashboards. 7. SCR database This DB2 database is used by the Serice Component Registry component to persist application definitions and their relationships to agent resources. Note: The Serice Component Registry component does not require backup, but can be restored. The Serice Component Registry component maintains application definitions and their relationships to agent resources. Backing up the OSLC component: Before you begin Obtain the following information: Output directory where you want the backup files to be stored Optional: Version of the Performance Management serer About this task If the OSLC Proider Serice component is one of the components that you plan to back up, complete this backup first. Procedure To fully back up the OSLC component online, run the following command: /opt/ibm/ccm/oslc_pm/bin/oslc_pm_backup.sh -d output_directory [-s ersion] Backing up the CCS component: Before you begin Obtain the following information that is required to back up the Central Configuration Serices component: Output directory where you want the backup files to be stored Version of the Performance Management serer User name and password of a user with administratie rights in the Performance Management configuration database Optional: Directory where you want a log of the backup procedures to be written About this task Back up the CCS component in the correct backup order. Procedure To fully backup the CCS component online, run the following command: Chapter 8. Administering 233

240 /opt/ibm/wlp/usr/serers/serer1/configserices/backup_restore/ccs_backup.sh -d output_directory -s ersion -u dbuser -p dbpassword [-l logfilepath] Backing up the APM UI component: Before you begin Obtain the following information: Output directory where you want the backup files to be stored User name and password of a user with administratie rights in the APM UI Port on which the APM UI is running About this task Back up the APM UI component in the correct backup order. Procedure To fully back up the APM UI component online, run the following command: /opt/ibm/wlp/usr/serers/apmui/apps/customcfg/apm_backup.sh -d output_directory -o port -u username -p password Backing up the MIN component: Before you begin Obtain the following information: Output directory where you want the backup files to be stored Optional: Version of the Performance Management serer About this task Back up the MIN component in the correct backup order. Procedure To fully backup the MIN component online, run the following command: /opt/ibm/ccm/min_backup.sh -d output_directory [-s ersion] Backing up the CSCS component: Before you begin Obtain the following information: Output directory where you want the backup files to be stored Version of the Performance Management serer Optional: Directory where you want a log of the backup procedures to be written About this task Back up the CSCS component in the correct backup order. Procedure To fully back up the CSCS component online, run the following command: 234 IBM Monitoring: Installation and Setup Guide

241 /opt/ibm/wlp/usr/serers/apmui/cscs/backup_restore/cscs_backup.sh -d output_directory -s ersion [-l logfilepath] Backing up the Prefetch data store: Before you begin Obtain the following information: Output directory where you want the backup files to be stored DB2 instance name: The default DB2 instance name is db2apm. DB2 database name: The default DB2 database name is WAREHOUS. About this task Back up the Prefetch data store in the correct backup order. Procedure Run the following command: su - DB2 instance name -c db2 - BACKUP DATABASE DB2 database name ONLINE TO output_directory WITH 2 BUFFERS BUFFER 1024 PARALLELISM 1 COMPRESS INCLUDE LOGS WITHOUT PROMPTING Backing up the SCR database: Before you begin Obtain the following information: Output directory where you want the backup files to be stored DB2 instance name: The default DB2 instance name is db2apm. DB2 database name: The default DB2 database name is SCR32. About this task Back up the SCR database in the correct backup order. Procedure Run the following command: su - DB2 instance name -c db2 - BACKUP DATABASE DB2 database name ONLINE TO output_directory WITH 2 BUFFERS BUFFER 1024 PARALLELISM 1 COMPRESS INCLUDE LOGS WITHOUT PROMPTING Restoring components Restoration is a disruptie action that is typically used for emergencies such as disaster recoery. All components must be offline to begin, and components must be restored in order. For disaster recoery, if the backup and restore serers are at the same fix pack leel, consider restoring to a serer that is different from the serer that the components were backed up on. If you switch to a different host name on the serer that you are restoring to, you must update the agent configurations to point to this new serer. The current installation must be intact with all files in place. If the installation is not intact, complete a fresh installation of the Performance Management serer and then run the restoration steps. Chapter 8. Administering 235

242 Restore components and databases in the following order: 1. Prefetch data store 2. SCR database 3. MIN 4. APM UI 5. CCS 6. OSLC 7. SCR 8. CSCS Stopping all components: Before restoring the components, stop all components that were backed up. About this task All components must be stopped before restoring components. Procedure Run the following command: apm stop_all Restoring the Prefetch Data store: Before you begin Obtain the following information: Directory where the backup file is stored DB2 instance name: The default DB2 instance name is db2apm. DB2 database name: The default Prefetch data store database name is WAREHOUS. About this task Restore the Prefetch data store in the correct restoration order. Procedure To fully restore the Prefetch data store, complete the following steps: 1. Run the command: su - DB2 instance name -c db2stop force; db2 terminate 2. Run the command: su - DB2 instance name -c db2start; db2 actiate db DB2 database name; db2 terminate 3. Run the command: su - DB2 instance name -c db2 DROP DB DB2 database name 4. Run the command: su - DB2 instance name -c db2 RESTORE DB DB2 database name FROM input_directory WITH 2 BUFFERS BUFFER 1024 WITHOUT PROMPTING 5. Run the command: su - DB2 instance name -c "db2 rollforward db DB2 database name to end of logs" 6. Run the command: 236 IBM Monitoring: Installation and Setup Guide

243 su - DB2 instance name -c "db2 rollforward db DB2 database name complete" Restoring the SCR database: Before you begin Obtain the following information: Directory where the backup file is stored DB2 instance name: The default DB2 instance name is db2apm. DB2 database name: The default Prefetch data store database name is SCR32. About this task Restore the SCR database in the correct restoration order. Procedure To fully restore the SCR database, complete the following steps: 1. Run the command: su - DB2 instance name -c db2stop force; db2 terminate 2. Run the command: su - DB2 instance name -c db2start; db2 actiate db DB2 database name; db2 terminate 3. Run the command: su - DB2 instance name -c db2 DROP DB DB2 database name 4. Run the command: su - DB2 instance name -c db2 RESTORE DB DB2 database name FROM input_directory WITH 2 BUFFERS BUFFER 1024 WITHOUT PROMPTING 5. Run the command: su - DB2 instance name -c "db2 rollforward db DB2 database name to end of logs 6. Run the command: su - DB2 instance name -c "db2 rollforward db DB2 database name complete" Restoring the MIN component: Before you begin Obtain the following information: Directory where the backup file is stored Optional: Version of the Monitoring Infrastructure Node that was used during backup Version of the Performance Management serer to which the MIN component is to be restored User name and password of a user with administratie rights in the Performance Management configuration database Optional: Expected wait time, in minutes, for the restoration to complete. The default is 10 minutes. About this task Restore the MIN component in the correct restoration order. Chapter 8. Administering 237

244 Procedure To fully restore the MIN component, complete the following steps: 1. Run the following command: /opt/ibm/ccm/min_restore.sh -d input_directory -s from_ersion -t to_ersion -U username -p password [-w wait_time_minutes] 2. Run the following command: /usr/bin/apm stop min What to do next Stop the Monitoring Infrastructure Node component after restoration completes. Restoring the APM UI component: Before you begin Obtain the following information: Directory where the backup file is stored User name and password of a user with administratie rights in the APM UI Port on which the APM UI is running Start the APM UI component before you start restoration. About this task Restore the APM UI component in the correct restoration order. Procedure To fully restore the APM UI component, complete the following steps: 1. Run the following command: /usr/bin/apm start apmui 2. Run the following command: /opt/ibm/wlp/usr/serers/apmui/apps/customcfg/apm_restore.sh -d input_directory -o port -u username -p password 3. Run the following command: /usr/bin/apm stop apmui Results A message reminding you to restart The APM UI serer is displayed. If you are restoring more than one component, you can ignore this message and use the command to start all components. What to do next Stop the APM UI component after restoration completes. Restoring the CCS component: Before you begin Obtain the following information: Directory where the backup file is stored 238 IBM Monitoring: Installation and Setup Guide

245 Version of the Performance Management serer that was used during backup, for example Version of the Performance Management serer to which the CCS component is to be restored, for example User name and password of a user with administratie rights in the Performance Management configuration database Optional: Directory where you want a log of the backup procedures to be written About this task Restore the CCS component in the correct restoration order. Procedure To fully restore the CCS component, run the following command: /opt/ibm/wlp/usr/serers/serer1/configserices/backup_restore/ccs_backup.sh -d input_directory -s from_ersion -t to_ersion -u dbuser -p dbpassword [-l logfilepath] Restoring the OSLC component: Before you begin Obtain the following information: Directory where the backup file is stored Optional: Version of the Performance Management serer that was used during backup Version of the Performance Management serer to which the OSLC component is to be restored About this task Restore the OSLC component in the correct restoration order. Procedure To fully restore the OSLC component, run the following command: /opt/ibm/ccm/oslc_pm/bin/oslc_pm_restore.sh -d input_directory -s from_ersion -t to_ersion Restoring the SCR component: Before you begin Obtain the following information: Directory where the backup file is stored Optional: Version of the Performance Management serer that was used during backup Version of the Performance Management serer to which the SCR component is to be restored User name and password of a user with administratie rights in the Performance Management configuration database About this task Restore the SCR component in the correct restoration order. Chapter 8. Administering 239

246 The SCR restoration script modifies the database to bring it up to the latest schema and to remap the data to the new OSLC proider. If the script is run before the database is restored, the database restoration leaes the system back-leeled. Procedure To fully restore the SCR component, run the following command: /opt/ibm/ccm/scr/xmltoolkit/bin/scr_restore.sh [-s from_ersion -t to_ersion] -Uusername -P password Restoring the CSCS component: Before you begin Obtain the following information: Directory where the backup file is stored Version of the Performance Management serer that was used during backup Version of the Performance Management serer to which the CSCS component is to be restored Optional: Directory where you want a log of the restoration procedures to be written About this task Restore the CSCS component in the correct restoration order. Procedure To fully restore the CSCS component, run the following command: /opt/ibm/wlp/usr/serers/apmui/cscs/backup_restore/cscs_restore.sh -d input_directory -s from_ersion -t to_ersion [-l logfilepath] Starting all components: After restoring the indiidual components, start all components that were restored. About this task If the process has started, ignore the message that it was preiously started. Procedure Adanced Configuration Run the following command: apm start_all Use the Adanced Configuration page to control communications settings and adanced features such as eent forwarding. After you click System Configuration > Adanced Configuration, the following configuration categories are displayed in the Adanced Configuration page. Agent Subscription Facility The Agent Subscription Facility includes the agent REST (Representatie 240 IBM Monitoring: Installation and Setup Guide

247 State Transfer) interface and Central Configuration Serices HTTP serer. The REST interface is used by agents to send monitoring data that is persisted in the DB2 serer and threshold eents. The Central Configuration Serices HTTP serer handles requests from agents for their configuration files, such as threshold definitions. Use these parameters for configuring the communications between the Agent Subscription Facility and the Performance Management serer. Missed Poll Limit (Fast Heart Beat) The maximum number of times that a monitoring agent does not respond to a poll before it is marked offline. The default alue is 15 interals. Missed Poll Limit (Slow Heart Beat) The maximum number of times that a monitoring agent does not respond to a poll before it is marked offline. The default alue is 5 interals. Transaction Time Out The amount of time, in seconds, that the serer waits for a response to a request. The default alue is 120 seconds. Pacing Count The number of times that the serer makes a request to the monitoring agent to call back after a short delay before allowing it to close the connection. The default alue is 5. Pacing Delay The amount of time, in milliseconds, that a monitoring agent waits before making a request to the serer for more work. (Default is 250.) Agent Central Configuration The settings here are required information that is used by the Performance Management serer in an on-premises enironment to configure the Central Configuration Serices. The Central Configuration Serices are used to distribute eents and thresholds, and historical data settings to the monitoring agents. Each agent of the same type is gien the same thresholds and settings. Host Name Oerride is an optional oerride for the host name or IP address of Central Configuration Serices if the alue of the serer is not correct. By default, the IP address or host name that you proided when you preconfigured the agent packages is used. Change Check Interal controls the frequency, in minutes, that the monitoring agents use to query configuration details from the serer. Default: 5 minutes. Protocol establishes whether HTTP or HTTPS is the protocol to communicate with the monitoring agent. If the APM_SECURE_COMMUNICATION ariable was set to Y before serer installation, this field is set to HTTPS for a secure connection. For more information, see Setting HTTP or HTTPS communications on page 33. Default: HTTP. Hybrid Gateway Configure the IBM Performance Management Hybrid Gateway for iewing monitoring data from your IBM Tioli Monitoring enironment in the Performance Management console. Managed System Group Name is the Tioli Enterprise Portal Serer managed system group that you created for iewing supported monitoring agents in the Performance Management console. Any monitoring agent types that are not supported by your Performance Management product are not shown in the console regardless of their Chapter 8. Administering 241

248 242 IBM Monitoring: Installation and Setup Guide inclusion in the managed system group. For guidance and limitations when creating the managed system group for hybrid enablement, see. Portal Serer Host name is the Tioli Enterprise Portal Serer host IP address or fully qualified domain name. Portal Serer Port is the port number used by the Tioli Enterprise Portal Serer for HTTP communications. The default port is for HTTP or for HTTPS. A alue of 0 sets the port to the default for HTTP or for HTTPS. Portal Serer Protocol determines whether to use the HTTP Internet protocol or the secure HTTPS protocol to connect to the Tioli Enterprise Portal Serer. Portal Serer User Name is the logon user name for starting the Tioli Enterprise Portal client. This user ID must hae access to all monitoring agent types (Allowed Applications is set to All Applications). For more information, see Administer Users in the Tioli Monitoring Knowledge Center.) Portal Serer User Password is the password that is associated with the Tioli Enterprise Portal logon user name. Pass-Through Proxy Host Name is used if the Tioli Enterprise Portal Serer communicates through a pass-through proxy serer. Enter the IP address or fully qualified name of the proxy host system. Pass-Through Proxy Port is used if the Tioli Enterprise Portal Serer communicates through a pass-through proxy serer. Enter the port number for communicating with the proxy. Pass-Through Proxy Protocol is used if the Tioli Enterprise Portal Serer communicates through a pass-through proxy serer. Enter the protocol used for communications through the proxy. The Tioli monitoring agents that you are iewing in the Performance Management console are in your IBM Tioli Monitoring domain. You can iew them in the application dashboards, but you cannot see situation eents from nor can you create eenting thresholds for these monitoring agents. Eent Manager The Eent Manager controls the flow through (forwarding to Simple Mail Transfer Protocol) and storage of receied eents, and notification setup. EIF Port is the port to use for Eent Integration Facility operations. Default: Eent Cache Time determines the number of hours that eents are retained in the local cache, up to 96 hours. If the Eent list is long, consider reducing the number of hours that are kept. Or, to see eents oer a weekend period, increase the number of hours. Default: 24 hours. Pure Eent Close Time determines how long to leae a pure eent open before closing it. Default: 24 hours. Master Reset Eent controls whether to send a master reset eent to clear preiously receied sampled eents after the monitoring agent is restarted. If you hae notifications configured, you also receie an . Default: True. EIF Eent Target(s) specifies the list of host names or IP addresses and port numbers to which all receied Eent Integration Facility eents are forwarded. For example, if you are forwarding eents to the

249 Netcool/OMNIbus Probe for Tioli EIF, enter the fully qualified host name or IP address of the computer where the probe is installed, followed by the receier port number. Separate the host name and port number with a colon (:), and separate each host name with a comma (,), such as :8989,localhost:9090,myhostname.en.ibm.com. If you do not include a port number, the default EIF port 9998 for the host name is used. IP6 addresses are not supported for EIF transmission. Target Addresses specifies the addresses that eents are forwarded to. Separate each address with a comma (,), such as annette@ibm.com,jim@ibm.com,owen@ibm.com. Subject Line is the text to use in the subject line of the forwarded SMTP eent . Default: Performance Management Eent. Sending Account is the address to use when sending an SMTP eent. Sending Account Password is the password that is associated with the sending account. SMTP Serer Address is the fully qualified host name of the SMTP serer that is used for sending eents as s, such as smtp.gmail.com. Use SSL determines whether to use SSL as the SMTP (Simple Mail Transfer Protocol) transport mechanism. Default: False. SMTP Port is the port number to use for sending SMTP . Default: 25. SSL SMTP Port is the port number to use for sending SMTP using the SSL (Secure Socket Layer) protocol. Default: 465. For information about forwarding your eents to the IBM Netcool/OMNIbus eent manager, see Integrating with Netcool/OMNIbus on page 202. Kafka Configuration The Kafka message broker has predefined configuration settings. Leae these settings at their defaults unless instructed to change them by IBM Support. Producer Batch Size The number of messages batched at the producer before dispatch to the eent handler. Default: 200 messages. Producer Batch Wait The producer wait time. Default: 5 seconds. Consumer Thread Count The consumer thread count. Default: 2 threads. Consumer Batch Size The consumer batch size is the number of records to include in a single database transaction. Default: 100 records. Consumer Batch Wait is the wait time between sending data batches to the database to allow for batch insertions. If the Consumer Batch size is not reached in this interal the data is flushed. Default: 10 seconds. UI Integration For products that integrate with the Performance Management console, you can add or edit the URL for launching the integrated application. The fields are populated with any URLs that were set during the integration configuration procedure. Cognos Reporting URL is used to launch the IBM Cognos Viewer for iewing the Performance Management reports through Reporting > Work with Reports and Actions > Launch to Reports. For more information, see Reporting. Chapter 8. Administering 243

250 Log Analysis URL is used to launch IBM Operations Analytics - Log Analysis for searching through application logs from the Application Performance Dashboard. For more information, see Searching log files. Predictie Insights URL is used to launch IBM Operations Analytics - Predictie Insights for iewing eents that were opened from detected anomalies in the Eents tab of the Application Performance Dashboard. For more information, see Inestigating anomalies with Operations Analytics - Predictie Insights. 244 IBM Monitoring: Installation and Setup Guide

251 Chapter 9. Agent reference Reference PDFs are aailable for each agent. The monitoring agent reference documentation is aailable through. See IBM Performance Management Wiki - Documentation in deeloperworks for Reference PDFs for each agent. The PDFs proide information about dashboards, group widgets, eenting thresholds, data sets, and attributes. Additionally, when you are logged in to the Performance Management console, you can access the online help by clicking Help > Help Contents. Copyright IBM Corp

252 246 IBM Monitoring: Installation and Setup Guide

253 Chapter 10. Agent Builder The IBM Agent Builder tool proides a graphical user interface to help you create, modify, debug, and package agents for monitoring data sources in IBM Performance Management. For instructions on installing the Agent Builder software and creating custom agents, download the IBM Agent Builder User's Guide PDF from deeloperworks. Copyright IBM Corp