runmqras (collect IBM MQ troubleshooting
information)
Use the runmqras command to gather IBM® MQ troubleshooting information (MustGather data) together into
a single archive, for example to submit to IBM
Support.
Purpose
The runmqras command is used to gather troubeshooting information from a
machine into a single archive. You can use this command to gather information about an application
or IBM MQ failure, possibly for submitting to IBM when you report a problem.
The runmqras command requires a Java 7, or later, Java runtime environment (JRE) in order to run. If the IBM MQ JRE component (on Linux®) or feature (on Windows) is not installed, then runmqras
searches the system path for an alternative JRE and attempts to use that.
If no alternative could be found, error message AMQ8599 is output. In this case:
Install the IBM MQ JRE component, or install an
alternative Java 7 JRE
Add the JRE to the system path
Rerun the command
By default, runmqras gathers information such as:
IBM MQ FDC files
Error logs (from all queue managers as well as the machine-wide IBM MQ error logs)
Product versioning, status information, and output from various other operating system commands.
Note, for example, the runmqras command does not gather user information that
is contained in messages on queues.
Running without requesting more sections is intended as a starting point for general problem
diagnosis, however, you can request more sections through the command line.
These additional sections gather more detailed information, depending on the
type of problem being diagnosed. If non-default sections are needed by IBM support personnel, they will tell you.
The runmqras command can be run under any user ID, but the command gathers
only information that the user ID can gather manually. In general, when debugging IBM MQ problems, run the command under:
The mqm user ID
A user ID in the mqm group.
to allow the command to gather queue manager files and command outputs.
The
runmqras command, by default, retrieves the environment variable information.
This applies to Linux and AIX®.
The runmqras
command retrieves a listing of the queue manager's data directory by default. This applies to
Multiplatforms. The userdata directory under the data directory is
excluded.
Syntax
Keywords and parameters
All parameters are required unless the description states they are optional.
In every case, QMgrName is the name of the queue manager to which the command
applies.
-inputfile InputFileName
Fully qualified name of the XML input file
-custominputfile CustomInputFileName
Fully qualified name of an additional XML input file
-zipfile ZipFileName
Supply the file name of the resulting archive.
runmqras appends the hostname to the name of the archive
file. For example, if you run the following
command:
runmqras -zipFile diagnostics.zip
the resulting archive file is
called diagnostics-hostname.zip.
By default, the name of the archive file is
runmqras-hostname.zip where hostname is
the hostname that runmqras appends to the file name.
-outputdir path
The directory in which the resulting output file is placed.
By default, the output directory is the same as the work directory.
-workdirectory path
The directory that is used for storing the output from commands that are run during the
processing of the tool. If supplied, this directory must either not exist, in which case it is
created, or must be empty.
If you do not supply the path, a directory whose name starts with runmqras
and is suffixed by the date and time is used:
On AIX and Linux, the
directory is under /tmp.
On Windows, the directory is under
%temp%.
-section SectionA,SectionB
The optional sections about which to gather more specific information. You must use a comma as
the separator character between sections, with no spaces. For
example:
By default, a generic section of documentation is collected, whereas more specific information
can be gathered for a specified problem type; for example, a section name of
trace gathers all of the contents of the trace directory.
The default collections can be avoided by supplying a section name of
nodefault.
IBM support generally supplies you with the sections
to use. Example available sections are:
all
Gathers all possible information, including all trace files, and diagnostics for many different
types of problems. You must use this option only in certain circumstances and this option is not
intended for general use.
default
IBM MQ logs, FDC files, basic configuration, and
status.
Note: Always gathered unless you use the section name
nodefault. Some information about the current environment (saved in
env.stdout on Linux, AIX and IBM i, and in set.stdout on Windows)
and current user limits (saved in mqconfig.stdout on Linux and AIX) might be altered by the runmqras command. If necessary, run the
env, set, or mqconfig commands manually in
your environment to check the actual values.
On the IBM MQ Appliance, any files
other than queue manager trace files present in the mqtrace: filesystem are now
captured in the default section.
Note: You should continue to specify the
trace section if you need to obtain any queue manager trace files present in the
mqtrace: filesystem.
nodefault
Prevents the default collections from occurring, but other explicitly requested sections are
still collected.
trace
Gathers all the trace file information plus the default information.
Note: Does not enable
tracing.
defs
Gathers the queue manager definitions and status information.
cluster
Gathers cluster configuration and queue information.
dap
Gathers transaction and persistence information.
kernel
Gathers queue manager kernel information.
logger
Gathers recovery logging information.
topic
Gathers topic tree information.
QMGR
Gathers all queue manager files: queues, logs, and configuration files.
leak
Gathers IBM MQ process resource usage
information.
Note:-section
mft only collects information for the default coordination queue manager
topology.
mqweb
Gathers trace and configuration data for the mqweb server.
For more information, see Choosing sections to gather, in the IBM technote on using the IBM MQrunmqras command to collect
data.
-qmlist QMA[,QMB]
A list of queue manager names on which the runmqras command is to be run.
This parameter does not apply to a client product because there are no queue managers from which
to request direct output.
By supplying a comma-separated list, you can restrict the iteration across queue managers to a
specific list of queue managers. By default, iteration of commands is across all queue managers.
-noqmdata
For Long Term Support from IBM MQ 9.2.0 Fix Pack 3 and for Continuous Delivery from IBM MQ 9.2.4, setting -noqmdata captures
installation-level diagnostics only, skipping any queue manager-specific diagnostics.
The -qmlist parameter and the -noqmdata parameter
cannot be used together. If both parameters are specified, the following error is returned:
Argument error: At most one of -noqmdata or -qmlist may be supplied
-timeout secs
The default timeout to give an individual command before the command stops waiting for
completion.
By default, a timeout of 10 seconds is used. A value of zero means wait indefinitely.
-demo
Run in demonstration mode where no commands are processed, and no files gathered.
By running in demonstration mode, you can see exactly which commands would have been processed,
and what files would have been gathered. The output .zip file contains a
console.log file that documents exactly what would have been processed and
gathered, should the command be run normally.
-v
Extends the amount of information that is logged in the console.log file,
contained in the output .zip file.
-ftp ibm|custom
Allows the collected archive to be sent through basic FTP to a remote destination.
At the end of processing, the resultant archive can be sent through basic
FTP, either directly into IBM, or to a site of
your choosing.
If you select the ibm option, anonymous FTP is used to deliver the archive into the IBM ECuRep server. This process is identical to submitting the file manually using FTP.
Note if you select the ibm option, you must also provide the pmrno option, and all other FTP* options are ignored.
Important: For Long Term Support from IBM MQ 9.2.0 Fix Pack 3 and for Continuous Delivery from IBM MQ 9.2.4, the -ftpIBM option is no longer available. If you select this option, the following message
is
generated:
The FTP IBM option will no longer work as the IBM FTP servers have been disabled
-ftpserver server
An FTP server name to connect to, when an FTP custom option is used.
-ftpusername userid
The user ID to log in to the FTP server with, when an FTP custom option is
used.
-ftppassword password
The password to log in to the FTP server with, when an FTP custom option is
used.
-ftpdirectory path
The directory on the FTP server to place the resulting .zip file into, used
when an FTP custom option is used.
-pmrno 12345,678,9AB
A valid IBM PMR number (problem record number)
against which to associate the documentation.
Use this option to ensure that the output is prefixed with your PMR number, so that when the
information is sent to IBM, the information is
automatically associated with that problem record.
Note: If you want to specify a Salesforce case number, use the -caseno
parameter, not the -pmrno parameter.
It is not permitted to supply both the
-caseno and -pmrno parameters together.
-caseno caseNo
A valid Salesforce case number.
Use this option to
ensure that the output is prefixed with your case number, so that when the information is sent to
IBM, the information is automatically associated with
that case number.
Note: If you want to specify a PMR number, use the -pmrno
parameter, not the -caseno parameter.
It is not permitted to supply both the
-caseno and -pmrno parameters
together.
-application application
Collects information about valid applications.
-help
Provide simple help.
-sub
Shows the keywords that will be substituted in the xml.
Examples
This command gathers the default documentation from the IBM MQ installation, and all queue managers on a machine:
runmqras
This command gathers the default documentation from the IBM MQ installation on a machine into an output file with a name
that starts with the appropriate case number:
runmqras ‑caseno TS123456789
This command gathers the default documentation from a machine, plus all trace files, the queue
manager definitions, and status for all queue managers on the machine: