IBM Support

Using the IBM MQ runmqras command to collect MustGather data

Technote (FAQ)


How do I use runmqras to collect MustGather data for an IBM MQ problem?


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

Please update your WebSphere MQ installation to IBM MQ V8.0, WebSphere V7.5, V7.1.0.1 or later, or V7.0.1.8 before using the runmqras command. Follow the manual instructions in the IBM MQ MustGathers if you are using older WebSphere MQ versions or maintenance levels.

First steps

The runmqras command never deletes files from your system. Therefore, you should ensure that you clean up IBM MQ FFST and trace files periodically to ensure they do not build up. Follow these instructions before using runmqras to avoid sending excessively old files to IBM:

Keep a copy of the runmqras archive file for your records as long as you are working with IBM support on a problem. After sending the runmqras file to IBM, clean up your IBM MQ files again to avoid sending duplicates if you need to use runmqras again in the future.

Starting runmqras

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

    Linux and UNIX

    sh> . /opt/mqm/bin/setmqenv -n Installation1
    sh> runmqras -help


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

    IBM i Qshell

    On IBM i the runmqras command is located in /QIBM/ProdData/mqm/bin. Unless you update your PATH to include this directory, you will need to type out the full path to runmqras when running it in the Qshell.

    ===> /QIBM/ProdData/mqm/bin/runmqras -inputfile /QIBM/ProdData/mqm/bin/isa.xml -help

The runmqras command may take anywhere from thirty seconds to several minutes to collect all of the data, depending on the speed of your system, the number of queue managers, and the number and size of files to collect. If there is a system problem which causes commands to hang, runmqras will complete more slowly since it defaults to waiting ten seconds for each command it issues to complete.

Choosing which data to gather

The runmqras command relies on a configuration file called isa.xml which describes the files to collect and the commands to run. This file is organized into sections, with each section collecting information about a different aspect of IBM MQ. New sections are sometimes added by fix packs:

    Sections names and descriptions


      Gathers all sections known to runmqras

      IBM MQ logs, FDC files, and basic configuration and status
      Always gathered unless you use the section name 'nodefault'

      IBM MQ cluster configuration and queue information

      IBM MQ object definitions and status information

      IBM MQ trace files, if any (does not enable tracing)

    Sections added in V8.0, V7.5.0.1, V7.1.0.1 and V7.0.1.9


      IBM MQ transaction and persistence information

      IBM MQ queue manager kernel information

      IBM MQ recovery logging information

      IBM MQ topic tree information

    Sections added in V8.0, V7.5.0.2, V7.1.0.3 and V7.0.1.11


      All queue manager files (queues, logs and configuration files)

    IBM MQ for IBM i supports the default, cluster, defs and trace sections, while the WebSphere MQ V7.1 client for HP Integrity NonStop Server supports the default, QMGR and trace sections. Both systems support the all and nodefault sections as well. Section names which are not recognized on a given platform are ignored by runmqras.

The IBM MQ MustGathers 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 runmqras commands are equivalent:

    Gathering multiple sections

    runmqras -section cluster,defs,trace

    runmqras -section cluster -section defs -section trace

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. for example:

    The qmlist option

    sh> 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:

    Using runmqras in different installations

    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 a PMR

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 a href="">send the file to the IBM ECuRep repository , your PMR will be updated automatically to alert the IBM MQ support team:

    Tagging data for a PMR

    C:\> 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:

    Automatically uploading data to a PMR

    C:\> runmqras -pmrno 12345,67R,890 -ftp IBM

    Automatically uploading data to a PMR using custom FTP options

    C:\> runmqras -pmrno 12345,67R,890 -ftp custom -ftpserver -ftpusername anonymous -ftpdirectory "toibm/websphere"

Handling large files

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. Be sure to a href="">clean up MQ files before using runmqras to reduce the amount of data collected.

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 Window.

    Using a custom work directory

    sh> runmqras -section cluster,defs,trace,QMGR -qmlist QMA -pmrno 12345,67R,890 -workdirectory /var/bigdata/nov19
    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/ -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,QMGR -qmlist QMA -pmrno 12345,67R,890 -workdirectory /var/tmp/nov19 -ftp IBM
    crtmqras v%I% starts...
    Using default Input path:
    Using Work path:
    Using default output path:
    Using Zip File path:
    Running on AIX
    crtmqras has successfully finished
    The zip file can be found at /var/bigdata/nov19/


    Example 1

    To collect your object definitions and logger data from queue managers QMA and QMB on IBM i using the Qshell:

    ===> /QIBM/ProdData/mqm/bin/runmqras -inputfile /QIBM/ProdData/mqm/bin/isa.xml -section defs,logger -qmlist QMA,QMB

    Example 2

    To collect all possible data from all queue managers on Windows, saving the output to an alternate directory with plenty of free space:

    C:\> runmqras -section all -workdirectory D:\TEMP\RUNMQRAS\AUG05

    Example 3

    To collect cluster and object definitions and trace files from queue manager QMC on Linux or UNIX and send the data directly to IBM for PMR 12345,67R,890, if your MQ system has direct access to the internet:

    sh> runmqras -section cluster,defs,trace -qmlist QMC -pmrno 12345,67R,890 -ftp custom -ftpserver -ftpusername anonymous -ftpdirectory "toibm/websphere"

Additional Information


WebSphere MQ V7.5

WebSphere MQ V7.1

WebSphere MQ V7.0.1

Product Alias/Synonym

WebSphere MQ WMQ

Document information

More support for: WebSphere MQ
Problem Determination

Software version: 7.0.1, 7.1, 7.5, 8.0

Operating system(s): AIX, HP-UX, IBM i, Linux, Solaris, Windows

Software edition: All Editions

Reference #: 1624944

Modified date: 02 July 2015

Translate this page: