Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide

Transcription

1 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide

2 2012 Quest Software, Inc. ALL RIGHTS RESERVED. This guide contains proprietary information protected by copyright. The software described in this guide is furnished under a software license or nondisclosure agreement. This software may be used or copied only in accordance with the terms of the applicable agreement. No part of this guide may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying and recording for any purpose other than the purchaser s personal use without the written permission of Quest Software, Inc. The information in this document is provided in connection with Quest products. No license, express or implied, by estoppel or otherwise, to any intellectual property right is granted by this document or in connection with the sale of Quest products. EXCEPT AS SET FORTH IN QUEST'S TERMS AND CONDITIONS AS SPECIFIED IN THE LICENSE AGREEMENT FOR THIS PRODUCT, QUEST ASSUMES NO LIABILITY WHATSOEVER AND DISCLAIMS ANY EXPRESS, IMPLIED OR STATUTORY WARRANTY RELATING TO ITS PRODUCTS INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. IN NO EVENT SHALL QUEST BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL, PUNITIVE, SPECIAL OR INCIDENTAL DAMAGES (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION OR LOSS OF INFORMATION) ARISING OUT OF THE USE OR INABILITY TO USE THIS DOCUMENT, EVEN IF QUEST HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. Quest makes no representations or warranties with respect to the accuracy or completeness of the contents of this document and reserves the right to make changes to specifications and product descriptions at any time without notice. Quest does not make any commitment to update the information contained in this document. If you have any questions regarding your potential use of this material, contact: Quest Software World Headquarters LEGAL Dept 5 Polaris Way Aliso Viejo, CA legal@quest.com Refer to our Web site for regional and international office information. Trademarks Quest, Quest Software, the Quest Software logo, Foglight, IntelliProfile, PerformaSure, Spotlight, StealthCollect, TOAD, Tag and Follow, Vintela Single Sign-on for Java, and vfoglight are trademarks and registered trademarks of Quest Software, Inc in the United States of America and other countries. For a complete list of Quest Software s trademarks, please see Other trademarks and registered trademarks are property of their respective owners. Third Party Contributions Foglight contains some third party components. For a complete list, see the License Credits page in Foglight online help. Installation and Configuration Guide February 2012 Version

3 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 3 Table of Contents Introduction to this Guide...4 About Quest Software, Inc Contacting Quest Software... 4 Contacting Quest Support... 5 Installing the Foglight Cartridge for IBM WebSphere MQ Server...6 Configuring the Queue Manager for Monitoring... 7 Event Configuration... 7 Queue Statistics Configuration... 8 Online Monitoring Level... 8 Authorization for MQ Objects... 8 Installing and Enabling the Cartridge for IBM WebSphere MQ Server Deploying the MQ Agent Package to Monitored Hosts Creating MQ Agent Instances Upgrading the Cartridge for IBM WebSphere MQ Server Setting MQ Agent Properties...13 Setting the Identity Properties Setting the Connection Properties Setting the SSL Properties Setting the Discovery Properties Setting the Monitor Lists Properties Setting the Event Properties Setting the Statistics Events Properties Setting the Listener Monitoring Property Setting the Advanced (Batch) Properties Setting the Data Collection Scheduler Property Activating MQ Agent Instances and Starting Data Collection Index...31

4 Introduction to this Guide Welcome to the Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide. This guide is intended for any user who wants to install and configure the Cartridge for IBM WebSphere MQ Server. It contains information on how to enable your IBM WebSphere MQ system for Foglight monitoring, describes the process of installing the cartridge and enabling its data collection, and contains instructions for configuring the MQAgent, used by the cartridge to monitor the entire distributed-messaging environment. About Quest Software, Inc. Quest Software (Nasdaq: QSFT) simplifies and reduces the cost of managing IT for more than 100,000 customers worldwide. Our innovative solutions make solving the toughest IT management problems easier, enabling customers to save time and money across physical, virtual and cloud environments. For more information about Quest solutions for administration and automation, data protection, development and optimization, identity and access management, migration and consolidation, and performance monitoring, go to Contacting Quest Software Mail Web site Quest Software, Inc. World Headquarters 5 Polaris Way Aliso Viejo, CA USA Refer to our Web site for regional and international office information.

5 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 5 Introduction to this Guide Contacting Quest Support Quest Support is available to customers who have a trial version of a Quest product or who have purchased a Quest product and have a valid maintenance contract. Quest Support provides unlimited 24x7 access to our support portal. Visit our support portal at support. From our support portal, you can do the following: Retrieve thousands of solutions from our Knowledge Base Download the latest releases and service packs Create, update, and review Support cases View the Global Support Guide for a detailed explanation of support programs, online services, contact information, policies, and procedures. The guide is available at: support.

6 1 Installing the Foglight Cartridge for IBM WebSphere MQ Server The Foglight Cartridge for IBM WebSphere MQ Server provides an effective monitoring solution for the distributed IBM WebSphere MQ infrastructure. The solution enables systems managers to better manage the delivery of services by alerting them to messaging infrastructure problems before end users are affected, ensuring consistent application performance at established service levels. The Cartridge for IBM WebSphere MQ Server monitors the health of the messaging system by tracking MQ objects, such as queue managers, queues, channels, and processes. There are two methods for monitoring WebSphere MQ Servers using the MQ Agent included in the Cartridge for IBM WebSphere MQ Server: remote and local (bindings mode). Remote monitoring is the recommended method, and involves deploying both a Foglight Agent Manager and an MQ Agent to each WebSphere MQ Queue Manager that you want to monitor. Bindings mode monitoring is only supported in limited situations. For details, see the Foglight Cartridge for IBM WebSphere MQ Server Release Notes. The agent may be enabled for local monitoring if remote monitoring is not a suitable option. The following table summarizes the differences between local monitoring, when the agent collects data in bindings mode, and remote monitoring. Remote monitoring Results in fewer monitored objects which increases the performance Can report non-availability when the target server is down Local moniotring (Bindings mode) No network communication involved No listeners or channels are required Less security configuration involved and more secure Installing the Cartridge for IBM WebSphere MQ Server is a multi-step process. First, you must configure the queue manager for monitoring. Next, install the Cartridge for IBM WebSphere MQ Server on the Foglight Management Server and deploy the MQ Agent package. Then you create MQ Agent instances and configure their properties. Finally, you activate the agents, and start their data collection. For details, see the following sections: Configuring the Queue Manager for Monitoring on page 7 Installing and Enabling the Cartridge for IBM WebSphere MQ Server on page 10 Deploying the MQ Agent Package to Monitored Hosts on page 10 Creating MQ Agent Instances on page 11

7 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 7 Chapter 1 Installing the Foglight Cartridge for IBM WebSphere MQ Server Setting MQ Agent Properties on page 13 Activating MQ Agent Instances and Starting Data Collection on page 30 Configuring the Queue Manager for Monitoring This section contains information on the values you need to set on your IBM WebSphere MQ Server to enable the Cartridge for IBM WebSphere MQ Server to collect data from that environment. Note For instructions on how to set these values, consult your IBM WebSphere MQ Server documentation. Generic examples are provided in the following sections, but these examples should not be considered recommendations for configuration. Configuration of each queue manager involves setting the values for the following: Event Configuration Queue Statistics Configuration Online Monitoring Level Authorization for MQ Objects System Objects User-Defined (Application) Objects Event Configuration To maximize the data available to the MQ Agent, enable the following events on the monitored queue manager: Authority Inhibit Local Channel Start stop Performance Channel auto definition SSL These values can be set using the MQ Explorer, the MQSeries commands (MQSC), or the Programmable Command Format (PCF) commands. For example: To set the event configuration using MQSC: alt qmgr AUTHOREV(ENABLED) CHADEV(ENABLED) CHLEV(ENABLED) INHIBTEV(ENABLED) PERFMEV(ENABLED) LOCALEV(ENABLED) SSLEV(ENABLED) REMOTEEV(ENABLED)

8 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 8 Chapter 1 Installing the Foglight Cartridge for IBM WebSphere MQ Server Queue Statistics Configuration Queue statistics for the monitored queue manager must be enabled. To enable the statistics configuration using MQSC: alt qmgr STATQ(ON OFF) Note The queue statistics collection should be at least as frequent as the statistics collection configured for the monitoring agent. For example: To set the statistics interval to the default of 1800 seconds using MQSC: alt qmgr STATINT(1800) Values in the range 1 through are valid. Online Monitoring Level The oldest message age metric of a queue depends on its online monitoring settings. In MQ Explorer, in queue properties, the Statistics section contains the Queue Monitoring setting. It can be set to different levels of reporting, including OFF, LOW, MEDIUM, HIGH, and others. Setting this value to LOW or a higher value enables the MQ Agent to report the oldest message age. Alternatively, you can also inherit the queue manager s monitoring level by setting the Queue Monitoring value to QMGR, when that value is set to LOW, MEDIUM, or HIGH (found in the Online Monitoring section, Queue Monitoring value). To set the online monitoring level using MQSC: alt qmgr MONQ(LOW MEDIUM HIGH) When queue monitoring is disabled for a queue, the MQ Agent generates an alarm, triggered by the Queue Monitoring rule. For more information about this rule, see the User and Reference Guide. Authorization for MQ Objects The MQ Agent connects to the monitored queue manager as a particular user (defined in your configuration). IBM WebSphere MQ uses the Message Channel Agent (MCA) User account to authorize users. This is always a user account on the local OS. IBM WebSphere MQ supports group-based authorization and this user account can be included in one of the user groups on the local OS. In remote data collection mode, the MQ Agent runs under the MCA user ID, specified in the server connection channel in the WebSphere MQ system. If the MCA user ID is left blank, the MQ Agent uses the mqm user account, which grants access permissions to all MQ Agent instances connected through that channel. In bindings mode, the MQ Agent runs under the MCA user ID that starts the Agent Manager process.

9 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 9 Chapter 1 Installing the Foglight Cartridge for IBM WebSphere MQ Server Appropriate access authorization is required for this user and can be configured either through MQ Explorer or using command-line utility, setmqaut. The simplest configuration method is to connect as an mqm user (or a member of the mqm group). In this case, no specific changes to permissions are required. To set the authority settings: Refer to the IBM documentation for the Websphere MQ Server version you are using. For example, for MQ 6: com.ibm.mq.amqzag.doc/fa13160_.htm System Objects The following table lists the objects monitored by the MQ Agent instances and the required permissions associated with these objects: Object Ideal Permissions Minimal Permissions SYSTEM.ADMIN.CHANNEL.EVENT Browse, Get, Inquire Browse, Inquire SYSTEM.ADMIN.COMMAND.QUEUE Put, Inquire Put, Inquire SYSTEM.ADMIN.PERFM.EVENT Browse, Get, Inquire Browse, Inquire SYSTEM.ADMIN.QMGR.EVENT Browse, Get, Inquire Browse, Inquire SYSTEM.ADMIN.STATISTICS.QUEUE Browse, Get, Inquire Browse, Inquire SYSTEM.CHANNEL.INITQ Inquire Inquire SYSTEM.CLUSTER.COMMAND.QUEUE Display, Inquire Display, Inquire SYSTEM.CLUSTER.REPOSITORY.QUEUE Display, Inquire Display, Inquire SYSTEM.CLUSTER.TRANSMIT.QUEUE Display, Inquire Display, Inquire SYSTEM.DEFAULT.MODEL.QUEUE Display, Get Display, Get User-Defined (Application) Objects For user-defined objects (such as application queues) the following permissions are required: Object Ideal Permissions Minimal Permissions Any listener Display Display Dead-letter queue Inquire Inquire Queue manager Connect, Inquire, Display Connect, Inquire, Display User-defined channel Display Display

10 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 10 Chapter 1 Installing the Foglight Cartridge for IBM WebSphere MQ Server Object Ideal Permissions Minimal Permissions User-defined queue Display Display Installing and Enabling the Cartridge for IBM WebSphere MQ Server The installation process is common to all Foglight cartridges. You must first install the cartridge *.car file and then deploy one or more MQ Agents before using the Cartridge for IBM WebSphere MQ Server. Note If you are uprading from a previous version of the Cartridge for IBM WebSphere MQ Server, see Upgrading the Cartridge for IBM WebSphere MQ Server on page 12. The Cartridge for IBM WebSphere MQ Server is distributed in a.car file, MQ-<version>.car. Installing the cartridge file on the Management Server adds the capabilities for monitoring IBM WebSphere MQ Server systems to your Foglight environment. Next, the cartridge must be enabled. Enabling the cartridge causes its components to be available for use by Foglight. When the cartridge is installed and enabled, all of its components become part of the Management Server. For instructions for installing and enabling the cartridge, see Installing Foglight cartridges in the Foglight Administration and Configuration Help. To view the Cartridge for IBM WebSphere MQ Server: On the navigation panel, under Dashboards, click Administration > Cartridges > Cartridge Inventory. After installing and enabling the cartridge, you must deploy the MQ Agent package to each host that you want to monitor. Note When considering a group of IBM WebSphere MQ Servers that you want to monitor, even if the servers host clustered queues, you must configure a separate MQ Agent instance for each server. For more information, see Deploying the MQ Agent Package to Monitored Hosts. Deploying the MQ Agent Package to Monitored Hosts The MQ Agent collects data from monitored hosts. After installing and enabling the cartridge on the Management Server, you must deploy the MQ Agent package to each host that you want to monitor. The MQ Agent uses the Foglight Agent Manager to communicate with the Foglight Management Server. Each monitored host must have an Agent Manager installed before the MQ Agent package can be deployed to that host. For more information about installing the Agent Manager on monitored hosts, see the Foglight Agent Manager Installation Guide.

11 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 11 Chapter 1 Installing the Foglight Cartridge for IBM WebSphere MQ Server The following procedure describes the process of deploying the MQ Agent package using the Agent Status dashboard in the Foglight browser interface. This dashboard is useful for deploying the agent package one host at a time. Alternatively, to deploy the MQ Agent package to multiple hosts, you can use the Agent Hosts dashboard. For more information, see the Foglight Administration and Configuration Guide. You can also deploy agent packages through the fglcmd command-line interface. For information about the available fglcmd commands, see the Command-Line Reference Guide. To deploy the MQ Agent package: 1 On the navigation panel, under Dashboards, click Administration > Agents > Agent Status. 2 On the Agent Status dashboard, click Deploy Agent Package (in the lower-left corner). The Deploy Agent Package dialog box opens. Note An Agent Manager must be installed and running on the host in order for you to deploy an agent package to that host. 3 In the Deploy Agent Package dialog box, select the host that you want the MQ Agent to monitor in the Host list. 4 From the Package list, select MQ.gar. 5 Click Deploy. The Deploy Agent Package dialog box refreshes. A green check mark in the Status column indicates a successful deployment. If agent deployment is not successful, see the online help for the Agent Status dashboard for troubleshooting information. 6 Click OK to close the Deploy Agent Package dialog box. From here, you can proceed to create one or more MQ Agent instances. For more information, see Creating MQ Agent Instances on page 11. Creating MQ Agent Instances The Cartridge for IBM WebSphere MQ Server uses the MQ Agent to collect information from monitored hosts. Creating an MQ Agent instance creates the agent process. The following procedure describes the process of creating MQ Agent instances using the Agent Status dashboard in the Foglight browser interface. This dashboard is useful for creating agent instances one host at a time. Alternatively, for creating MQ Agent instances on multiple hosts, you can use the Agent Hosts dashboard. For more information, see the Administration and Configuration Guide. Another way to create agent instances is using the fglcmd command-line interface. For more information about the available fglcmd commands, see the Command-Line Reference Guide.

12 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 12 Chapter 1 Installing the Foglight Cartridge for IBM WebSphere MQ Server To create an MQ Agent instance: 1 On the navigation panel, under Dashboards, click Administration > Agents > Agent Status. 2 On the Agent Status dashboard, click Create Agent (in the lower-left corner). 3 In the Create Agent dialog box, click Host and select the host that you want to monitor. The Agent Type list refreshes. If you have deployed the MQ Agent package to that host, the MQAgent appears in the list. 4 In the Agent Type list, select MQAgent. 5 In the Instance Name box, type a name for the MQ Agent instance. Tip 6 Click Create. Each MQ queue manager that you want to monitor must have its own agent instance, so consider using queue manager names in agent instance names to emphasis that relationship. For example: MQAgent_QueueManager_on_HostName. The Create Agent dialog box closes and the Create Agent Results dialog box opens, showing the status of the agent creation. A green check mark in the Status column indicates that the agent was created successfully. 7 Click OK to close the Create Agent Results dialog box. The Agent Status dashboard refreshes, and the newly-created MQ Agent instance appears in the list. Next, edit the MQ Agent properties. For more information, see Chapter 2, Setting MQ Agent Properties. Upgrading the Cartridge for IBM WebSphere MQ Server If you have been using version or later of the Cartridge for IBM WebSphere MQ Server, you can upgrade to the latest version instead of performing a completely new installation. To upgrade the Cartridge for IBM WebSphere MQ Server, you must first deactivate any existing agents, and then install version of the cartridge as you would a new Cartridge for IBM WebSphere MQ Server. Do not delete the older version of the.car file. To upgrade the Cartridge for IBM WebSphere MQ Server 1 On the Agent Status page, deactivate all existing MQ Agent instances. 2 Install and enable the new cartridge. 3 Deploy the new MQ Agent package to each monitored host. 4 Activate the MQ Agent instances and start data collection. For detailed information on upgrade compatibility, see the Cartridge for IBM WebSphere MQ Server Release Notes.

13 2 Setting MQ Agent Properties The MQ Agent provides an effective monitoring solution for the distributed IBM WebSphere MQ infrastructure. It collects data from the distributed IBM WebSphere MQ infrastructure and sends it to Foglight. The agent keeps track of MQ objects such as queue managers, queues, channels and listeners. This solution uses a messaging infrastructure to alert you before end-users are affected. When an agent connects to Foglight, it is provided with sets of properties that it uses to configure its correct running state. Each agent is provided with a combination of two types of properties: agent properties and shareable properties. Default versions of these properties are installed with the Cartridge for IBM WebSphere MQ Server. However, you can edit the default shareable and agent properties, configure agent properties that apply only to a specific agent instance, and create edited clones of shareable properties that are used by a subset of agents of a certain type. For more information about working with agent properties, see the Foglight Administration and Configuration Guide. Each queue manager that you want to monitor requires its own MQ Agent instance. Caution A technical limitation currently restricts the number of monitored queues for each Agent Manager to Ensure that this limit is adhered to when monitoring multiple queue managers from the same Foglight Agent Manager. The configuration of agent properties described in this section include: Setting the Identity Properties on page 15 Setting the Connection Properties on page 15 Setting the SSL Properties on page 17 Setting the Discovery Properties on page 18 Setting the Monitor Lists Properties on page 19 Setting the Event Properties on page 22 Setting the Statistics Events Properties on page 28 Setting the Listener Monitoring Property on page 28 Setting the Advanced (Batch) Properties on page 29 Setting the Data Collection Scheduler Property on page 29

14 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 14 Modify the properties for each MQ Agent instance. An MQ Agent instance can have a combination of global and private properties. Global properties apply to all instances of the agent type while private properties apply only to specific agent instances. To modify agent properties: 1 On the navigation panel, under Dashboards, click Administration > Agents > Agent Status. 2 On the Agent Status dashboard, select the instance of the MQ Agent whose properties you want to modify and click Edit Properties. Caution Another way of editing MQ Agent properties is through the Agent Properties dashboard. However, keep in mind that the properties you specify on this dashboard apply to all instances of the MQ Agent type. To ensure that you are editing properties for a particular agent instance, without overwriting any properties for other MQ Agent instances, use the Agent Status dashboard instead of the Agent Properties dashboard. 3 Click Modify the private properties for this agent. A list of agent properties appears in the display area.

15 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 15 Setting the Identity Properties Use the Identity properties to assign an identity to the monitored queue manager. To set the connection profile: Note This procedure continues from To modify agent properties: on page Locate the Identity properties. 2 In the Queue Manager Name box, type the name of the queue manager instance that you want to monitor. Queue manager names can be located by doing any of the following: Running the IBM WebSphere MQ dspmq program on the monitored host. Using the IBM WebSphere MQ runmqsc program. Using the IBM WebSphere MQ Explorer. Contact your IBM WebSphere MQ administrator if you are unsure of the queue manager name. Caution Leaving this property blank causes the MQ Agent to fail and log a warning message. Ensure that the queue manager name you enter here is valid. The name is case sensitive. 3 In the MQ Group Name box, type the name of the queue manager group that you want to monitor. The MQ group name can be used to group related queue managers together in the dashboards. You can assign any name to the queue manager for this purpose (for example, Payroll). 4 Click Save. 5 To specify the type of connection, see Setting the Connection Properties. Otherwise, click Back to Agent Status and activate the MQ Agent, as described in Activating MQ Agent Instances and Starting Data Collection on page 30. Setting the Connection Properties Use the Connection MQ Agent properties to specify the type of connection. The MQ Agent can connect to a queue manager either as a remote client or in Bindings mode. It is possible to have the agent running on the same host as your MQ system, and to operate as a remote client. To set the connection properties: Note This procedure continues from To modify agent properties: on page Locate the Connection properties.

16 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 16 2 Select the applicable Remote Connection option: True or False. Select True if you want to instruct the MQ Agent to remotely monitor the queue manager client. This is the default mode. or Select False if you want to instruct the MQ Agent to locally monitor the queue manager using a bindings (local) connection. Caution Support for the Bindings mode is limited. Consult the Release Notes to confirm that your platform is supported before using this feature. If you choose the bindings mode, the path to the IBM MQ Java libraries must be defined in an environment variable before starting the Agent Manager, as specified in the following table: Platform Variable Path AIX LIBPATH 64-bit libraries: /usr/mqm/java/lib64 32-bit libraries: /usr/mqm/java/lib HP-UX LD_LIBRARY_PATH 64-bit libraries: /opt/mqm/java/lib64 Linux (POWER, x86-64 and 32-bit libraries: zseries s390x platforms) /opt/mqm/java/lib Solaris (x86-64 and Sparc platforms) Linux (x86 and zseries platforms) LD_LIBRARY_PATH /opt/mqm/java/lib Windows PATH 64-bit libraries: install_dir\java\lib64 32-bit libraries: install_dir\java\lib Caution When using Bindings mode on a 64-bit Windows monitored system, modify the PATH system variable to first point to the 64-bit libraries (install_dir\java\lib64), and then to the 32-bit libraries (install_dir\java\lib). For additional information about connecting the queue manager in bindings mode, see your IBM MQ documentation or visit v7r0/index.jsp?topic=/com.ibm.mq.csqzaw.doc/jm10340_.htm. 3 For Remote monitoring only: Configure the MQ Agent to allow the creation of remote connections. a In the Host Name box, type the fully qualified name or IP address of the host machine on which the remote queue manager is running.

17 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 17 b c In the Server Channel box, type the name of the server connection channel on the remote queue manager. In the Port Number box, type the listener port number of the remote queue manager. 4 Click Save at the bottom of the window to save the entries. 5 To set the Secure Sockets Layer (SSL) agent properties, see Setting the SSL Properties. Otherwise, click Back to Agent Status and activate the MQ Agent, as described in Activating MQ Agent Instances and Starting Data Collection on page 30. Setting the SSL Properties If you want to enable the transmission of secure data over an insecure network, use the Secure Sockets Layer (SSL) set of agent properties The MQ Agent supports connection to an MQ Server over a server connection channel enabled with SSL. Once the appropriate keys have been created and exchanged, the MQ Agent must be configured using the agent properties. Important Prior to SSL agent property configuration, the MQ system parameter Authentication of parties initiating connections must be set to Optional. To set the Secure Sockets Layer properties: Note This procedure continues from To modify agent properties: on page Locate the SSL properties. 2 Select a cipher suite from the Cipher Spec list. Note After changing the cipher suite for an MQ Agent, it may be necessary to restart the Agent Manager for that MQ Agent. Cipher Spec Connection Possible if SFIPS (No) Connection Possible if SFIPS (Yes) DES_SHA_EXPORT Yes No NONE N/A N/A NULL_MD5 Yes No NULL_SHA Yes No RC4_MD5_EXPORT Yes No RC4_MD5_US Yes No RC4_SHA_US Yes No

18 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 18 Cipher Spec TLS_RSA_WITH_AES_256_CBC_SHA (MQ ) Connection Possible if SFIPS (No) No Connection Possible if SFIPS (Yes) Yes TRIPLE_DES_SHA_US Yes No 3 In the truststore Location box, type the path to the MQ Agent's trust store. The path must include the name of the file itself. For example: C:\Documents and Settings\foglight\.keystore Caution Only one trust store location may be used for all MQ Agent instances running under a single Agent Manager. Important If you select a cipher spec from the Cipher Spec list, this value is mandatory. 4 In the truststore Password box, type the password for accessing the agent's trust store. Important If you select a cipher spec from the Cipher Spec list, this value is mandatory. 5 Click Save. 6 To enable or disable monitoring of auto-discovered queues and channels, see Setting the Discovery Properties. Otherwise, click Back to Agent Status and activate the MQ Agent, as described in Activating MQ Agent Instances and Starting Data Collection on page 30. Setting the Discovery Properties Use the Discovery Settings agent properties to enable the MQ Agent to automatically discover and monitor user-defined queues and channels for a queue manager. A useful approach during an initial configuration is to enable auto-discovery, but disable the monitoring of discovered properties for queues and channels. When the agent starts, you can then manually edit the queue and channel lists, to enable the monitoring of only those queues and channels that are of interest to you. After the installation, consider re-enabling the monitoring of discovered properties, so that the MQ Agent starts automatically monitoring any new queues that become available. To set the Discovery Settings properties: Note This procedure continues from To modify agent properties: on page Locate the Discovery Settings properties. 2 Select the applicable Auto-discovery option: True or False. Auto-discovery is a scheduled collection which occurs by default once an hour. Select True if you want the MQ Agent to automatically populate the queue and channel lists. Otherwise, select False.

19 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 19 3 Select the applicable Monitor Discovered Queues option: True or False. Note This setting can be adjusted for each queue in the queue list at a later time. Setting it to False prevents the agent from monitoring discovered queues. A discovered queue that is not being monitored can later be added to the list of monitored queues, as described in Setting the Monitor Lists Properties on page 19 Select True if you want the MQ Agent to immediately start monitoring all auto-discovered queues. Otherwise, select False. 4 Select the applicable Monitor Discovered Channels option: True or False. Note This setting can be adjusted for each channel in the channel list at a later time. Setting it to False prevents the agent from monitoring discovered channels. A discovered channel that is not being monitored can later be added to the list of monitored channels, as described in Setting the Monitor Lists Properties on page 19. Select True if you want the MQ Agent to immediately start monitoring all auto-discovered channels. Otherwise, select False. 5 Select the applicable Monitor MQ System Objects option: True or False. Select True if you want the MQ dashboards to display the metrics associated with system queues and channels (that is, SYSTEM.*). Otherwise, select False. It is possible to manually add a subset of these objects to the queue or channel lists when only specific SYSTEM objects are useful. To do that, you can add entries to the queue list, each containing a desired SYSTEM object, for example, SYSTEM.ADMIN.PERFM.EVENT. For information about editing queue lists, see Setting the Monitor Lists Properties on page Click Save. 7 To set the items in the Queue and Channel lists, see Setting the Monitor Lists Properties. Otherwise, click Back to Agent Status and activate the MQ Agent, as described in Activating MQ Agent Instances and Starting Data Collection on page 30. Setting the Monitor Lists Properties These secondary agent properties maintain a list of which queues and channels are to be monitored for a particular queue manager. Monitoring of each item in a list can be enabled or disabled. Caution It is essential that each agent have its own queue and channel lists. Ensure that you clone a new list when you are first configuring your agent. To set the monitor lists properties: Note This procedure continues from To modify agent properties: on page Locate the Monitor Lists properties. 2 Clone the defaultqueuelist list. a From the Queue List, select defaultqueuelist. Caution This is a default, empty queue list. Selecting other, pre-populated queue lists (if available) and cloning them (as described in step b) results in their list entries being copied to the

20 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 20 b destination list and requires their removal. For the same reason, you should not clone any queue lists populated by the auto-discovery process, unless the second list is expected to have the same queue names as the first list. Click the Clone button to the right of Queue List to create a clone of the selected defaultqueuelist. In the dialog box that opens, type a name for the cloned list. Caution Failing to clone the defaultqueuelist causes it to be populated with entries that are carried over to the subsequent queue lists created by cloning this default list, and requires you to remove them manually from each cloned instance. 3 Update the newly-cloned list. You can add alias queues, and cluster queues on the monitored queue manager. When auto-discovery is enabled, the MQ Agent needs some time to update the queue and channel lists. Changing the auto-discovery or editing these lists during the update is not recommended. Instead, you can make these changes either on deactivated MQ Agent instances, or on running agent instances that have a discovery collection frequency of five minutes or higher. a Click the Edit button to the right of Queue List. b In the dialog box that opens, click Add Row to add an entry. For each row, define the following values: Note If auto-discovery is enabled, the queue and channel lists are automatically populated. Queue Name: Type the name of this queue. Monitor: Select the check box to enable the monitoring of the queue, or clear the check box to disable monitoring. c Save your changes to the queue list by clicking Save Changes in the dialog box. The dialog box closes. 4 Repeat step 2 and step 3 to create as many queue lists as necessary. Note You must add a queue list for each MQ Agent instance. 5 Clone the defaultchannellist list. a From the Channel List, select defaultchannellist. Caution This is a default, empty channel list. Selecting other, pre-populated channel lists (if available) and cloning them (as described in step b) results in their list entries being copied to the destination list and requires their removal. For the same reason, you should not clone any channel lists populated by the auto-discovery process, unless the second list is expected to have the same channel names as the first list. b Click the Clone button to the right of Channel List to create a clone of the defaultchannellist. In the dialog box that opens, type a name for the cloned list. Caution Failing to clone the defaultchannellist causes it to be populated with entries that are carried over to the subsequent channel lists created by cloning this default list, and requires you to remove them manually from each cloned instance. 6 Update the newly-cloned list.

21 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 21 When auto-discovery is enabled, the MQ Agent needs some time to update the queue and channel lists. Changing the auto-discovery or editing these lists during the update is not recommended. Instead, you can make these changes either on deactivated MQ Agent instances, or on running agent instances that have a discovery collection frequency of five minutes or higher. a b Click the Edit button to the right of Channel List. In the dialog box that opens, click Add Row to add an entry. For each row, define the following values: Note If auto-discovery is enabled, the queue and channel lists are automatically populated. Channel Name: Type the name of this channel. Monitor: Select the check box to enable the monitoring of the channel, or clear the check box to disable monitoring. c Save your changes to the channel list by clicking Save Changes in the dialog box. The dialog box closes. 7 Repeat step 5 and step 6 to create as many channel lists as necessary. Note You must add a channel list for each MQ Agent instance. 8 Ensure that temporary objects are ignored during monitoring. In the Exclude Objects Regex box, type a regular expression that selects temporary objects. Use this property to specify a regular expression that selects temporary objects. The MQ Agent ignores any queue or channel objects whose names match the regular expression during auto-discovery. In the regular expression \., the backslash \ is the escape character, and the period. matches any single character. Additionally,.* matches any strings, while the pipe character is a separator. The expression should follow the syntax for Java regular expressions. For more information about this syntax, see the Foglight Command-Line Reference Guide. The default expression, AMQ\..* MQMON\..* CSQ\..*, matches any objects whose names start with AMQ., MQMON., or CSQ.. For example: To expand the expression to select objects whose names start with TEMP., edit the expression as follows: AMQ\..* MQMON\..* CSQ\..* TEMP\..* To monitor only objects whose names start with QUEST (that is, to exclude all objects not beginning with QUEST): a Deactivate the MQ Agent. b Set the Exclude Objects Regex value to: ^(?!QUEST).* and save your changes. c Clear the queue and the channel list. d Start the MQ Agent. 9 In the display area, click Save.

22 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide To set the performance, channel, queue manager, and configuration events, see Setting the Event Properties. Otherwise, click Back to Agent Status and activate the MQ Agent, as described in Activating MQ Agent Instances and Starting Data Collection on page 30. Setting the Event Properties Use the Event Settings agent properties for an MQ Agent to configure the monitoring of the following event types: Performance Events Channel Events Queue Manager Events Performance Events To set performance event properties: Note This procedure continues from To modify agent properties: on page Locate the Event Settings properties. 2 Select the Performance Events option: True or False. Select True if you want the MQ Agent to monitor performance events. Otherwise, select False. 3 Select the Consume Performance Event Message option: True or False. Note This agent property requires a get permission on this queue. This permission is set on the IBM WebSphere MQ Server. Select True if you want the MQ Agent to remove performance events from the SYSTEM.ADMIN.PERFM.EVENT queue as they are read. or Select False if you want the MQ Agent to retain performance events in the SYSTEM.ADMIN.PERFM.EVENT queue as they are read. When this option is set to False, the MQ Agent does not consume any events in event queues. With no other means to remove event messages from the event queues, the event queues become full, and the corresponding event collection does not work. 4 Click Performance Event List, and select the performance event list that you want to use. 5 Optional Clone the selected performance event list. a b Click the Clone button to the right of Performance Event List. In the dialog box that opens, type a name for the cloned list. 6 Update the performance event list. a Click the Edit button to the right of Performance Event List.

23 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 23 A dialog box opens, listing the available performance events, and indicating if they are enabled. The MQ Agent includes the following performance events: Performance Event Queue Depth High Queue Depth Low Queue Depth Full Queue Service Interval High Queue Service Interval OK Description The queue depth is incremented to or above the specified limit. The queue depth is decremented to or below the specified limit. The queue contains the maximum number of messages. No successful get operations or MQPUT calls have been detected within an interval greater than the specified limit. A successful get operation has been detected within an interval less than or equal to the specified limit. b c In the dialog box, click Add Row to add an entry. For each row, define the following values: Performance Event: Type the name of the performance event. Monitor: Select the check box to enable the monitoring of this event, or clear the check box to disable monitoring. Click Save Changes in the dialog box. The dialog box closes. 7 In the display area, click Save. Channel Events To set channel event properties: Note This procedure continues from To modify agent properties: on page Locate the Event Settings properties. 2 Select the Channel Events option: True or False. Select True if you want the MQ Agent to monitor channel events. Otherwise, select False. 3 Select the Consume Channel Event Message option: True or False. Note This agent property requires a get permission on this queue. This permission is set on the IBM WebSphere MQ Server. Select True if you want the MQ Agent to remove channel events from the SYSTEM.ADMIN.CHANNEL.EVENT queue as they are read. or Select False if you want the MQ Agent to retain channel events in the SYSTEM.ADMIN.CHANNEL.EVENT queue as they are read.

24 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 24 When this option is set to False, the MQ Agent does not consume any events in event queues. With no other means to remove event messages from the event queues, the event queues become full, and the corresponding event collection does not work. 4 Click Channel Event List, and select the channel event list that you want to use. 5 Optional Clone the selected channel event list. a b Click the Clone button to the right of Channel Event List. In the dialog box that opens, type a name for the cloned list. 6 Update the newly-selected channel event list. a Click the Edit button to the right of Channel Event List. A dialog box opens, listing the available channel events, and indicating if they are enabled. The MQ Agent includes the following channel events: Channel Event Bridge Started (z/os only) Bridge Stopped (z/os only) Channel Activated Channel Auto Definition Error Channel Auto Definition OK Channel Conversion Error Channel Not Activated Channel SSL Error Channel Started Channel Stopped Channel Stopped By User Description The IMS bridge is started. The IMS bridge is stopped. A channel that is waiting to become active, and for which a Channel Not Activated event is generated, can become active, because an active slot has been released by another channel. The automatic definition of a channel failed. The automatic definition of a channel is successful. A channel is unable to carry out data conversion. A channel is required to become active, either because it is starting, or because it is about to make another attempt to establish connection with its partner. However, the limit on the number of active channels is reached, which prevents the channel from becoming activated. A channel using Secure Sockets Layer (SSL) or Transport Layer Security (TLS) fails to establish a connection. Either an operator issued a Start Channel command, or a channel is successfully established. A channel is stopped. A channel is stopped when a user issues a STOP CHL command. b In the dialog box, click Add Row to add an entry. For each row, define the following values:

25 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 25 c Channel Event: Type the name of the channel event. Monitor: Select the check box to enable the monitoring of this event, or clear the check box to disable monitoring. Click Save Changes in the dialog box. The dialog box closes. 7 In the display area, click Save. Queue Manager Events To set queue manager event properties: Note This procedure continues from To modify agent properties: on page Locate the Event Settings properties. 2 Select the Queue Manager Events option: True or False. Select True if you want the MQ Agent to monitor queue manager events. Otherwise, select False. 3 Select the Consume Queue Manager Event Message option: True or False. Note This agent property requires a get permission on this queue. This permission is set on the IBM WebSphere MQ Server. Select True if you want the MQ Agent to remove events from the SYSTEM.ADMIN.QMGR.EVENT queue as they are read. or Select False if you want the MQ Agent to retain queue manager events in the SYSTEM.ADMIN.QMGR.EVENT queue as they are read. When this option is set to False, the MQ Agent does not consume any events in event queues. With no other means to remove event messages from the event queues, the event queues become full, and the corresponding event collection does not work. 4 Select the queue manager event list that you want to use from the Queue Manager Event List. 5 Optional Clone the selected queue manager event list. a b Click the Clone button to the right of Queue Manager Event List. In the dialog box that opens, type a name for the cloned list. 6 Update the cloned list. a Click the Edit button to the right of Queue Manager Event List.

26 Foglight Cartridge for IBM WebSphere MQ Server Installation and Configuration Guide 26 A dialog box opens, listing the available queue manager events, and indicating if they are enabled. The MQ Agent includes the following queue manager events: Queue Manager Event Alias Base Queue Type Error Default Transmission Queue Type Error Default Transmission Queue Usage Error Get Inhibited Not Authorized Put Inhibited Queue Manager Active Queue Manager Not Active Queue Type Error Remote Queue Name Error Transmission Queue Type Error Description The specified alias queue is not a local queue, or in a local definition of a remote queue. The specified remote queue cannot be found on the destination queue manager, so the local queue manager attempted to use the default transmission queue. However, although there is a queue defined by the DefXmitQName queue-manager attribute, it is not a local queue. The specified remote queue cannot be found on the destination queue manager, so the local queue manager attempted to use the default transmission queue. However, the queue defined by the DefXmitQName queue-manager attribute does not have a Usage attribute of MQUS_TRANSMISSION. MQGET calls are currently inhibited for the queue. Indicates unauthorized access to application resources, such as an application trying to open a queue for which it does not have the required authority, or a command being issued from a user ID that does not have the required authority. MQPUT and MQPUT1 calls are currently inhibited for the queue. A queue manager became active. A queue manager was requested to stop. The ObjectQMgrName field specifies the local definition of a remote queue (in order to specify a queue-manager alias). In that local definition, the RemoteQMgrName attribute is the name of the local queue manager. However, the ObjectName field specifies the name of a model queue on the local queue manager. A local definition of a remote queue (or an alias to one) was specified, but the RemoteQName attribute in the remote queue definition is blank, or the ObjectQMgrName field in the object descriptor is not blank and does not contain the name of the local queue manager, but the ObjectName field is blank. The ObjectName or ObjectQMgrName field in the object descriptor specifies the name of a local definition of a remote queue but either XmitQName is not blank and specifies a remote queue, or it is blank and RemoteQMgrName specifies a remote queue.