IBM Support

PowerHA: How To Use QMGTOOLS MustGather Data Capture Tool (for High Availability Only)

Troubleshooting


Problem

This document demonstrates how to use QMGTOOLS properly for High Availability.

Resolving The Problem

This document demonstrates how to use QMGTOOLS to properly collect data for High Availability.
*****************************************************************************************************************************************************

READ THIS FIRST

Important Note: The MustGather Data Capture tool is provided as-is. The iGSC HAS team assists users having difficulty that uses the tool for HA data capture. It is recommended to keep current on build versions as they become available!  Use QMGTOOLS/CMPVER command, or GO MG menu option 13 to check for a current build.  Also, use a profile such as QSECOFR (or equivalent) when collecting the data to avoid conflicts by lack of authority.


The MustGather Data Capture tool was created by IBM Support to help automatically collect the many pieces of debug data that is critical to fixing complexed High Availability problems more quickly. For instructions on how to obtain and install QMGTOOLS, refer to the document  MustGather: How To Obtain and Install QMGTOOLS and keep it current

What does the tool collect? It collects close to everything needed to help determine root cause. There are a few exceptions; however, the tool evolves and items are added as needed. When there are pieces that cannot be collected by the tool automatically, Support will ask for those specific pieces outside of the data collected by the tool.

Important Note 1: Currently, there are no special requirements to use this tool. There are no PTFs required for HA data collection.

Important Note 2: If QMGTOOLS is not currently installed with the latest build, some functions could be missing and critical debug data may not be gathered.

****************************************************************************************************************************************************

With the QMGTOOLS library successfully restored, now the data capture can begin. There are some things to make note of.  If the user profile being used to collect data resides on all nodes in the environment with the same password and has access to all objects, data collection will work much better.  It is recommended to use a user profile with high authority to avoid problems during data collection with regard to not being authorized.  Using QSECOFR is desirable.  Also ensure that QSECOFR is in good standing with being able to access Start Service Tools (SST), and not expired or disabled.
***Command Method (Preferred)***
Collecting data for a single node using a command:
There is an easy shortcut that can be used without going through menu options by using the following command(s) on each node in a cluster.
Ensure that the latest build of QMGTOOLS is installed first:
If able to connect to IBM, use QMGTOOLS/CMPVER
If unable to connect to IBM, refer to the following doc use Method 3 in the following doc: QMGTOOLS: How to check and update QMGTOOLS
Once updated on all nodes, from each node sign on as QSECOFR or equivalent user profile
Ensure that SST (STRSST) can be accessed with QSECOFR.  If QSECOFR is unable to log into SST, critical debug data will be missing.  
To start the data capture, issue command - QMGTOOLS/SYSSNAP COLHA(Y) 
This will generate a zip file to be uploaded to IBM.
Detailed information on how to upload data to IBM Support can be found here: MustGather: Instructions for Sending Data to IBM i Support
                                            
*Note - The QMGTOOLS/SYSSNAP command above is assuming that data is being collected shortly after an incident, the parameter for "DAYSPRV" can be adjusted if more days data is needed.
***Menu Driven Method***
Using the QMGTOOLS menu to collect for a single node:
To start using the tool in all cases, ensure that the latest QMGTOOLS build is installed, use QSECOFR or equivalent user profile, ensure QSECOFR can access SST.
Issue the ADDLIBLE LIB(QMGTOOLS) command, followed by GO MG. This will bring the user to the main MustGather Data Capture menu to select the following options.
1.  ADDLIBLE LIB(QMGTOOLS)
2.  GO MG
3.  From the main MG menu, select option 2 -HA (High Availability) data collection
4.  Select option 1 or 3 - Dump cluster data on local node only
*Note - at this time there is no difference between options, but may change in the future.
5.  On the DMPCLUINF screen, leave the defaults.  Support will instruct if the system snapshot is not needed (default option is Y).
Data collection starts as soon as the user presses Enter, because it is a local data capture only. There is no need for user profiles and passwords to be entered. 
The data collection will generate a zip file to be uploaded to IBM and the location will be displayed on the screen when completed. 
Pressing Enter will take the user back to the collection menu and posts the completion message at the bottom of the screen. The .zip file will reside in the directory /tmp/HA_DATA.
After all of the data has been collected, a Case needs to be opened and the data can be uploaded IBM.
Additional Information

There are additional options listed for the HA data capture:

 
5. Cluster Debug Tool (Internal IBM only) This is to be used by Support representatives only and requires additional licensing which most users will not have on their systems.
7. Dump SST macros XSM/Cluster This is typically used by Support when only certain AA macros are needed.
8. Collect GUI data This is typically only needed after general HA data has been collected and IBM Support has requested this collection.
9. Node Status Trap This is used to start a LIC trace while nodes are active and this monitors for when a node becomes partition and will capture the LIC trace for analysis. Needs to be started on each independent node. Refer to the below link for information: 

QMGTOOLS: Node Status Trap (NODESTSTRP) In QMGTOOLS
11. Additional XSM tools This is used by Support only.
12. Compare HA PTFs from IBM public FTP site. If the user's system can connect to public FTP site, this option will compare all PTFs on user's system to most currently known and complete Recommended Fixes PTF listing and then will provide a report back to the user with the missing PTFs, along with the complete listing.
13. QHASTOOLS help menu This option provides the link to this same document 

PowerHA: How To Use QMGTOOLS MustGather Data Capture Tool (for High Availability Only)
14. Collect admin domain debug data Refer to this link for additional information: 

QMGTOOLS: Administrative Domain Debug Data

 

[{"Type":"MASTER","Line of Business":{"code":"LOB68","label":"Power HW"},"Business Unit":{"code":"BU070","label":"IBM Infrastructure"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m0z0000000CGgAAM","label":"High Availability"}],"ARM Case Number":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"All Versions"}]

Historical Number

670936263

Document Information

Modified date:
19 August 2025

UID

nas8N1010374

Page Feedback