IBM Support

How to configure UNIX and Linux systems for IBM MQ

Technote (troubleshooting)


Problem(Abstract)

You are planning to install or upgrade an IBM MQ server on a UNIX or Linux system and need to know how to tune the operating system, including user limits and kernel parameters for resources like shared memory and semaphores.

Cause

If you do not configure your operating system parameters properly, your IBM MQ queue managers may run out of system resources while handling your production workload. Depending on the resource which was exhausted, MQ may return an error to the application (like MQRC_RESOURCE_PROBLEM, reason code 2012), write a message to its error logs, create FDC files in the /var/mqm/errors directory, or even terminate.

Resolving the problem



IBM MQ Tuning Recommendations

The IBM MQ documentation provides the IBM recommended default values for a number of operating system tuning parameters:





Do not assume that an "all clear" report from mqconfig means you cannot run out of resources. Run the mqconfig script when your system is processing its peak volume to ensure that the actual resource usage, shown as a percentage, is not excessively high.

If you need to increase your parameters beyond the IBM defaults, bear in mind that modern systems have comparatively vast resources. The UNIX IPC interface was designed in the late 1970s on a 16-bit DEC PDP-11 computer, similar to this system used by UNIX designers Dennis Ritchie and Ken Thompson. Modern systems may have a hundred thousand to a million times more memory, so doubling or quadrupling IPC resource settings in order to handle your workload will not stress them. Be generous with your settings and refer to the section on IPC Tuning Parameters for more information on specific settings.




Checking IBM MQ V8.0, WebSphere MQ V7.5, V7.1 and V7.0 Settings with mqconfig

IBM provides the mqconfig script to simplify the task of configuring your system. If you are running IBM MQ V8.0, WebSphere MQ V7.5.0.2 or later, or V7.1.0.3 or later, the mqconfig script is included with MQ. For earlier versions and fix pack levels, you must download the script to your system and make it executable, for example by running: chmod a+x mqconfig


    Syntax


    [.] mqconfig -?

    [.] mqconfig -v Version

    [.] mqconfig -v Version [-p Project]...   (Only on Solaris 10 and later versions)


                    Version: 8.0, 7.5, 7.1 or 7.0



    Options


    .

      Source the mqconfig script by using a dot (i.e. period, or full stop) at the beginning of the command. Sourcing the mqconfig script allows it to more reliably confirm that the limits and settings in your current shell are correct for MQ. This feature is available only for POSIX compliant shells.



        Using the MQ_CONFIG_OPTIONS variable to pass command line arguments


        sh> MQ_CONFIG_OPTIONS="-v 8.0 -p group.mqm"
        sh> . ./mqconfig



        Using the MQ_CONFIG_OPTIONS variable to pass no command line arguments


        sh> MQ_CONFIG_OPTIONS=
        sh> . ./mqconfig



    -?
      Prints detailed help information about mqconfig.

    -v Version
      In addition to checking that your system limits are sufficient for MQ, confirm that the operating system and hardware meet the basic system requirements for a particular MQ version.

    -p Project
      On Solaris 10 and later versions only, system resources are configured using projects. You can provide one or more project names to analyze; otherwise, the mqconfig script will analyze the group.mqm project and any other projects showing MQ queue manager activity, or your current project.



    Sample Output

    Here is sample output from mqconfig showing a Linux system with three tuning issues:


    • The IPC semaphore setting 'semmni' failed because it is one quarter the IBM recommended value, even though current semaphore set usage is only at 5%.
    • The system file limit 'file-max' is below the IBM recommended value, but because usage is only at 2% and the value is not that far off the IBM default, mqconfig only gave a warning.
    • The soft file limit 'nofile' for the user who ran mqconfig is one tenth what it should be. If this user (mqm) starts a queue manager without increasing the soft limit, the queue manager may fail when the system prevents it from opening files.



    Notes on mqconfig output

    Where possible, mqconfig will try to show your system's current usage as a percentage. If your usage of any resource is nearing the limit, typically 75% or more, then mqconfig may flag it as a warning, even if your value meets or exceeds the IBM default. If your usage is higher still, typically 95% or more, mqconfig may flag it as a failure.

    Any values listed in the "Current User Limits" section are resource limits for the user who ran mqconfig. If you normally start your queue managers as the mqm user, then you should switch to mqm and run mqconfig there. If other members of the mqm group (and perhaps root) also start queue managers, they should all run mqconfig to ensure their limits are suitable for MQ.

    The mqconfig script may also recommend changing a shell option in order to avoid a known performance problem when running MQ commands in the background. If mqconfig suggests a change, you can modify your profile and log back in again. For example, Korn shell users can add the following line to their .kshrc (or similar) file:

      set +o bgnice


    The mqconfig script cannot check shell options like bgnice reliably, so run "set -o" in your shell to check the option when mqconfig gives a warning. If the option matches the IBM recommendation you can ignore that mqconfig warning; Otherwise, you should update your login files (like .profile or .kshrc) to set the shell option properly.

    If you note a discrepancy between mqconfig and the MQ documentation, or if the mqconfig script fails, please submit a comment using the link a the bottom of the page.



Checking WebSphere MQ V6.0 Settings with mqconfig-old

If you are running WebSphere MQ V6.0 or V5.3, you may use the mqconfig-old script to help configure your system. To use mqconfig-old, you must first download the script to your system and make it executable, for example by running: chmod a+x mqconfig-old


    Syntax


    mqconfig-old -?

    mqconfig-old -v Version

    mqconfig-old -v Version [-p Project]...   (Only on Solaris 10 and later versions)


                    Version: 6.0 or 5.3



    Options


    -?

      Prints detailed help information about mqconfig-old.

    -v Version
      Check your system settings for a specific version of WebSphere MQ (either 6.0 or 5.3).

    -p Project
      On Solaris 10 and later versions only, system resources are configured using projects. You can provide one or more project names to analyze; otherwise, the mqconfig-old script will analyze any project owning a WebSphere MQ IPC object, or the group.mqm project, or your current project.


WebSphere MQ V6.0 for AIX, HP-UX, Linux and Solaris went out of support on September 30, 2012. This script is provided as a courtesy to users with extended support contracts and will be withdrawn in the future.


Operating System Notes

Each operating system has its own parameters and tuning methods.


    AIX

    The AIX kernel requires no tuning for IPC parameters. Other system settings can be changed using SMIT (System Management Interface Tool).

    The mqconfig script will ensure that any relevant AIX operating system HIPER APARs are installed, and it will also check that AIX Unicode data conversion filesets are installed so that MQ can convert data successfully. The mqconfig script will check the resource limits and shell settings for the current user.


    HP-UX

    HP-UX kernel parameters can be viewed and modified using the System Management Homepage tool (smh) or with the kctune command. The kctune command can also show whether a parameter change will take effect immediately, or whether you must restart the system. On HP-UX 11.23 and older levels, you may use the System Administration Manager tool (sam) instead of smh.

    The mqconfig script will verify all of the kernel parameters required by MQ and confirm that PHCO_36900, an important HP-UX patch to libc, is installed on the system. Finally, the mqconfig script will check the resource limits and shell settings for the current user.


    Linux

    Linux kernel parameters can be changed dynamically using the sysctl command or via files under the /proc filesystem. In order to change parameters permanently, you can add your settings to the /etc/sysctl.conf file or use a system startup script to change the values on each boot.

    One oddity is that all semaphore tuning parameters are held in a single parameter called sem, rather than four separate files. All four values must be set at the same time, even if you only wish to change one value.

    The mqconfig script will verify all of the kernel parameters for MQ and check the resource limits and shell settings for the current user.


    Solaris 9

    Solaris 9 kernel parameters can be checked by running the command 'sysdef -i'. To change parameters you must edit the /etc/system file and restart the system.

    MQ V7.1 and later versions do not support Solaris 9.


    Solaris

    Solaris 10 and later versions allow multiple projects, each with their own set of resource limits, rather than relying on a single system-wide set of tuning values. The MQ documentation describes how to use the 'projects', 'projadd' and 'projmod' commands to list, create, and modify projects. The old Solaris 9 kernel parameters have different names, but please note that some begin with "project" and others with "process", as shown here:

    • semmni  ▸  project.max-sem-ids
    • semmsl  ▸  process.max-sem-nsems
    • semopm  ▸  process.max-sem-ops
    • shmmax  ▸  project.max-shm-memory
    • shmmni  ▸  project.max-shm-ids



    In order to use the resource limits recommended by IBM, you should configure a project (for example, 'group.mqm') and make sure you start your queue managers in that project. You can use the 'id' command to check your current project and the 'newtask' command to run a command in a different project, or to start a shell to run multiple commands in a different project:

      Using newtask to run one command in a different project


      solaris> id -p
      uid=500(justinf) gid=501(dev) projid=3(default)

      solaris> newtask -p group.mqm strmqm SOHO
      WebSphere MQ queue manager 'SOHO' starting.
      The queue manager is associated with installation 'MQ75'.
      5 log records accessed on queue manager 'SOHO' during the log reply phase.
      Log reply for queue manager 'SOHO' complete.
      Transaction manager state recovered for queue manager 'SOHO'.
      WebSphere MQ queue manager 'SOHO' started using V7.5.0.2.

      solaris> id -p
      uid=500(justinf) gid=501(dev) projid=3(default)




      Using newtask to run multiple commands in a different project


      solaris> id -p
      uid=500(justinf) gid=501(dev) projid=3(default)

      solaris> newtask -p group.mqm

      solaris> id -p
      uid=500(justinf) gid=501(dev) projid=100(group.mqm)

      solaris> strmqm TRIBECA
      WebSphere MQ queue manager 'TRIBECA' starting.
      The queue manager is associated with installation 'MQ75'.
      5 log records accessed on queue manager 'TRIBECA' during the log reply phase.
      Log reply for queue manager 'TRIBECA' complete.
      Transaction manager state recovered for queue manager 'TRIBECA'.
      WebSphere MQ queue manager 'TRIBECA' started using V7.5.0.2.

      solaris> runmqlsr -m TRIBECA -t tcp -p 1422 1>/dev/null 2>&1 &

      solaris> id -p
      uid=500(justinf) gid=501(dev) projid=100(group.mqm)

      solaris> exit

      solaris> id -p
      uid=500(justinf) gid=501(dev) projid=3(default)



    If you forget to use the newtask command and start a queue manager in the wrong project (typically the default project), then mqconfig may generate a report which shows lots of warnings and failures for that project. There are two possible solutions:

    1. Change the settings for the other project to meet the MQ requirements. This will prevent MQ from failing, even if you forget to use newtask to start your queue managers.
    2. Ignore the mqconfig warnings and leave the settings as they are on the other project. Stop any MQ queue managers running in the wrong project and use the newtask command to restart them in the correct project. If you follow this approach, you must be careful about using newtask to start MQ in future.


IPC Tuning Parameters

The following parameters control the limits on System V IPC semaphore and shared memory resources used by MQ. Not all parameters exist on every system; AIX notably does not use any of them. Parameters relating to System V IPC message queues are not listed since MQ does not use them.

If you are installing MQ on a system with other products that recommend specific IPC settings, you will need to know how to combine the recommendations. For example, if MQ recommends 1024, DB2 recommends 512, and CICS recommends 512, you need to know whether to use the lowest value (512), the highest value (1024), or the sum of all the values (2048).

In the list below, you should take the highest value for parameters marked > and sum up the values for parameters marked . Only for the shmmin parameter should you take the lowest recommended value, and since this parameter only applies to Solaris 9 you aren't likely to encounter it:


System V IPC Semaphore Parameters


    >  semaem
      The maximum adjustment value the operating system can apply when processing an undo request. MQ uses binary rather than counting semaphores, so this parameter does not affect it.

      semmni  or   project.max-sem-ids
      The maximum number of semaphore sets on the system. MQ V7.1 and later use fewer semaphore sets than before, and are less likely to run out.

    ∑  semmns
      The total number of semaphores in the system. The theoretical maximum is semmni × semmsl, though in practice some sets will be smaller than the maximum allowed size.

    ∑  semmnu
      The maximum number of semaphore undo requests in the system. When a program ends or crashes, the operating system will automatically adjust semaphores for which undo support was requested. MQ uses this option with some semaphores to ensure they are unlocked even if a process ends abnormally.

    >  semmsl  or   process.max-sem-nsems
      The maximum number of semaphores in a single set.

    ∑  semume
      The maximum number of semaphore undo requests a single process can have outstanding.

    >  semvmx
      The maximum value of a semaphore. MQ uses binary rather than counting semaphores, so this parameter does not affect it.


    System V IPC Shared Memory Parameters

    ∑  shmall

      The maximum number of pages available for shared memory on Linux systems.

    >  shmmax  or   project.max-shm-memory
      The maximum size of a shared memory set. Setting a very large value will not waste memory since MQ starts by allocating small sets, increasing the size only when processing a heavy workload.

    <  shmmin
      The minimum size of a shared memory set. There is no particularly compelling reason to use any value other than 1.

    ∑  shmmni  or   project.max-shm-ids
      The maximum number of shared memory sets on the system. MQ queue managers add shared memory sets based on workload, so it is worth checking this parameter when the system is under load to see how many sets you are using.

    ∑  shmseg
      The maximum number of shared memory sets a single process can attach. This value should match shmmni so that MQ can attach all of the sets it creates.

Related information

A Japanese translation is available

DISCLAIMER: All source code and/or binaries attached to this document are referred to here as "the Program". IBM is not providing program services of any kind for the Program. IBM is providing the Program on an "AS IS" basis without warranty of any kind. IBM WILL NOT BE LIABLE FOR ANY ACTUAL, DIRECT, SPECIAL, INCIDENTAL, OR INDIRECT DAMAGES OR FOR ANY ECONOMIC CONSEQUENTIAL DAMAGES (INCLUDING LOST PROFITS OR SAVINGS), EVEN IF IBM, OR ITS RESELLER, HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Product Alias/Synonym

WebSphere MQ WMQ

Document information

More support for: WebSphere MQ
Configuration

Software version: 6.0, 7.0, 7.1, 7.5, 8.0

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

Software edition: All Editions

Reference #: 1271236

Modified date: 09 April 2015


Translate this page: