Using the WebSphere MQ runmqras Command to Collect Diagnostic Data

WebSphere MQ V7.0.1 and later includes a tool called runmqras which automates the task of collecting diagnostic information. The runmqras tool collects some files from WebSphere MQ and saves the output from select WebSphere MQ and system commands to a zip archive. The WebSphere MQ Information Center describes all of the runmqras options:

• WebSphere MQ V7.5 runmqras command
• WebSphere MQ V7.1 runmqras command

Please update your WebSphere MQ installation to V7.0.1.8 or later, V7.1.0.1 or later, or V7.5.0.0 before using the runmqras command. Follow the manual instructions in the WebSphere MQ MustGather technotes if you are using older WebSphere MQ versions or maintenance levels.

Starting runmqras

Unless otherwise directed by IBM support, you should issue the runmqras command as a user with WebSphere MQ administrator authority, for example someone in the local mqm group. If your system has multiple WebSphere MQ installations, use the setmqenv command to choose your installation before using runmqras. For example:

• IBM i Q Shell
      ===> /QIBM/ProdData/mqm/bin/runmqras -help

• Linux & UNIX
      sh> . /opt/mqm/bin/setmqenv -n Installation1
      sh> runmqras -help

• Windows
      C:\> C:\Program Files (x86)\IBM\WebSphere MQ\bin\setmqenv -s
      C:\> runmqras -help
  
  
  
  

Choosing Data Using Sections

The runmqras command relies on a configuration file which describes the files to collect and the commands to run. This file is organized into sections, each one collecting information about a different aspect of WebSphere MQ:

Section	Information collected
default	WebSphere MQ logs, FDC files, and basic configuration and status
cluster	WebSphere MQ cluster configuration and queue information
dap	WebSphere MQ transaction and persistence information
defs	WebSphere MQ object definitions and status information
kernel	WebSphere MQ queue manager kernel information
logger	WebSphere MQ recovery logging information
topic	WebSphere MQ topic tree information
trace	WebSphere MQ trace files (if any)

The WebSphere MQ MustGather technotes offer advice on which sections to choose for different problems. You can choose sections by using the runmqras -section option with a comma-separated list or by repeating the -section option. For example, these commands are equivalent:

runmqras -section cluster,defs,trace

runmqras -section cluster -section defs -section trace

Please note that the trace section does not enable WebSphere MQ tracing. It merely gathers any trace files you previously generated to the trace directory.

The runmqras tool always gathers the default section unless you use the special nodefault section name. You can also use the section name all to collect data from all sections.

Choosing Queue Managers

By default, the runmqras tool will try to collect information from all queue managers on the machine. If you are having a problem with only one or two queue managers, you can use the -qmlist option to prevent runmqras from examining the others:

runmqras -qmlist QMA,QMB

If your queue managers are in different installations, you should use setmqenv to switch installations in order to use the correct runmqras with each queue manager. For example:

sh> . /usr/mqm/bin/setmqenv -n Installation1
sh> runmqras -qmlist QM_V71
sh> . /usr/mqm/bin/setmqenv -n Installation2
sh> runmqras -qmlist QM_V75

Some of the data runmqras collects requires the target queue managers to be running. If possible, start those queue managers prior to using runmqras. If you cannot start a queue manager, or if the queue manager is offline for a reason, runmqras will gather what data it can.

Collecting Data for IBM

If you are gathering data for IBM, you can use the -pmrno option to include your IBM Problem Management Record (PMR) number in the archive file name. When you send the file to IBM, your PMR will be updated automatically to alert WebSphere MQ support:

runmqras -pmrno 12345,67R,890

When you use the -pmrno option, you can direct runmqras to send your file to IBM using standard FTP (non-SSL). Your system must be connected to the internet, and FTP traffic must be allowed by your firewall for this option to work:

runmqras -pmrno 12345,67R,890 -ftp IBM

Collecting Large Data

In most cases the data gathered by runmqras will be rather small. However, the runmqras archive file can grow large when your system has many FDC files or when you use runmqras to collect a large set of trace files.

If you have a lot of FDC or trace data, you may need to use the -workdirectory option to point to a location with lots of free space. Otherwise, runmqras may fill up the /tmp filesystem on IBM i, Linux and UNIX, or the %TEMP% directory on Windows. For example:

sh> runmqras -workdirectory /var/bigdata/feb19 -pmrno 12345,67R,890
java version "1.6.0"
Java(TM) SE Runtime Environment (build pap6460sr10fp1-20120214_01(SR10 FP1))
IBM J9 VM (build 2.4, JRE 1.6.0 IBM J9 2.4 AIX ppc64-64 jvmap6460sr10fp1-20120202_101568 (JIT enabled, AOT enabled)
J9VM - 20120202_101568
JIT  - r9_20111107_21307ifx1
GC   - 20120202_AA)
JCL  - 20120201_01
/usr/IBM/WMQ-7.5-A/usr/mqm/java/jre64/jre/bin/java -cp /usr/IBM/WMQ-7.5-A/usr/mqm/java/lib/com.ibm.mq.commonservices.jar:/usr/IBM/WMQ-7.5-A/usr/mqm/java/lib/com.ibm.mq.tools.ras.jar -Djava.library.path=/usr/IBM/WMQ-7.5-A/usr/mqm/lib64:/usr/IBM/WMQ-7.5-A/usr/mqm/java/lib64 -DdefaultRasInput=/usr/IBM/WMQ-7.5-A/usr/mqm/bin/isa.xml -DdefaultRasWork=/tmp/runmqras_130219_130335 crtmqras.Zipper -section cluster,defs,trace -qmlist QMA -pmrno 12345,67R,890 -workdirectory /var/tmp/feb07 -ftp IBM
crtmqras v%I% starts...
Using default Input path:
/usr/IBM/WMQ-7.5-A/usr/mqm/bin/isa.xml
Using Work path:
/var/bigdata/feb19
Using default output path:
/var/bigdata/feb19
Using Zip File path:
/var/bigdata/feb19/12345.67R.890.runmqras_201302191303.zip
Running on AIX
crtmqras has successfully finished
The zip file can be found at /var/bigdata/feb19/12345.67R.890.runmqras_201302191303.zip

Cleaning Up Files

The runmqras command never deletes files from your system. After collecting data, be sure clean up certain files so that you don't send them again the next time you use runmqras:

• Trace files: Archive and delete trace files after they have been collected and sent
• FDC files: Archive or delete FDC files periodically to keep them from building up
  
  
  
  

Examples

1. To collect your object definitions and logger data from queue managers QMA and QMB:
   
   runmqras -section defs,logger -qmlist QMA,QMB
   
   
   
2. To collect all possible data from all queue managers on Windows, saving the output to an alternate disk with plenty of free space:
   
   runmqras -section all -workdirectory D:\TEMP\RUNMQRAS\FEB19
   
   
   
3. To collect cluster and object definitions from queue manager QMC, including your trace files, and FTP the output directly to IBM for PMR 12345,67R,890:
   
   runmqras -section cluster,defs,trace -qmlist QMC -pmrno 12345,67R,890 -ftp IBM
   
   
   
   

   Back to top