runmqras (collect IBM MQ diagnostic information)

Use the runmqras command to gather IBM MQ diagnostic information together into a single archive, for example to submit to IBM Support.


Purpose

The runmqras command is used to gather diagnostic information from a machine, into a single archive. We 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:
  1. Install the IBM MQ JRE component, or install an alternative Java 7 JRE
  2. Add the JRE to the system path
  3. 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, we 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

runmqras -zipfile ZipFileName -inputfile InputFileName -custominputfile CustomInputFileName -outputdir path-workdirectory path -section SectionA, SectionB -qmlist QMA[, QMB] -timeout secs -demo  -v  -ftp IBM -ftp custom -ftpserver server -ftpusername userid -ftppassword password -ftpdirectory path -pmrno 12345,678,9AB -caseno caseNo -help  -sub


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 we do not supply the path, a directory whose name starts with runmqras and is suffixed by the date and time is used:

    • On UNIX, 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.

    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. We 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 we use the section name nodefault. 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: We should continue to specify the trace section if we 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.
      This section applies to Linux, and AIX.

      mft
      Captures the data obtained by the fteRas command.

      mqweb
      Gathers trace and configuration data for the mqweb server.

    For more information, see Choose sections to gather, in the IBM technote on using the IBM MQ runmqras 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, we can restrict the iteration across queue managers to a specific list of queue managers. By default, iteration of commands is across all queue managers.

    -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, we 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 our 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, we must also provide the pmrno option, and all other FTP* options are ignored.

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

    -caseno caseNo
    A valid Salesforce Case number. Note: -caseno is equivalent to -pmrno and both are optional parameters, but it is not permitted to supply both together.

    -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, and sends it directly into IBM to be associated with PMR number 11111,222,333 using the basic FTP capability: 
runmqras -ftp ibm -pmrno 11111,222,333
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: 
runmqras -section trace,defs


Return codes

A non zero return code indicates failure.

Parent topic: IBM MQ control commands reference