9.

Installing and migrating IBM MQ

IBM
 Note
Before using this information and the product it supports, read the information in “Notices” on page
481.

This edition applies to version 9 release 4 of IBM® MQ and to all subsequent releases and modifications until otherwise
indicated in new editions.
When you send information to IBM, you grant IBM a nonexclusive right to use or distribute the information in any way it
believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 2007, 2024.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with
IBM Corp.
Contents

Installing and migrating.........................................................................................5

Installing and uninstalling........................................................................................................................... 5
IBM MQ installation overview................................................................................................................ 6
Installing and uninstalling IBM MQ on AIX..........................................................................................32
Installing and uninstalling IBM MQ on IBM i....................................................................................... 61
Installing and uninstalling IBM MQ on Linux....................................................................................... 93
Installing and uninstalling IBM MQ on Windows.............................................................................. 158
Installing IBM MQ Advanced for Multiplatforms...............................................................................236
Installing and uninstalling IBM MQ Explorer as a stand-alone application on Linux and Windows268
Installing and uninstalling IBM MQ Internet Pass-Thru................................................................... 272
Installing the stand-alone IBM MQ Web Server................................................................................275
Maintaining and migrating....................................................................................................................... 275
Where to find more information about maintaining and migrating.................................................. 276
Characteristics of upgrades and fixes............................................................................................... 277
Applying maintenance to IBM MQ..................................................................................................... 278
Upgrading IBM MQ............................................................................................................................. 320
Migrating IBM MQ...............................................................................................................................336
Migrating IBM MQ Managed File Transfer ........................................................................................ 475
Migrating IBM MQ Internet Pass-Thru...............................................................................................478

Notices..............................................................................................................481
Programming interface information........................................................................................................ 482
Trademarks.............................................................................................................................................. 482

iii
iv
Installing and migrating
You perform a range of tasks to install, uninstall, maintain, and migrate IBM MQ. These tasks are
platform-specific where needed.

About this task

To get started with installing and migrating IBM MQ, see the following topics.

Procedure
• “Installing and uninstalling IBM MQ” on page 5
• “Maintaining and migrating IBM MQ” on page 275

Installing and uninstalling IBM MQ

Before you start installing IBM MQ, consider how you want to use it. Use these topics to help you to
prepare for installation, install the product, and verify the installation. There is also information to help
you to uninstall the product.

About this task

To get started with installing IBM MQ, see the topics for the platforms that your enterprise uses. For
concepts and considerations relating to installation, see “IBM MQ installation overview” on page 6.
You can also apply and remove maintenance to IBM MQ. See “Applying maintenance to IBM MQ” on page
278.
Attention: The information in this section applies to both Continuous Delivery (CD) and Long Term
Support (LTS) releases.
Any information that applies specifically to an LTS or CD release is marked with the appropriate
icon.

For tutorials to help you with installing and upgrading, see A

collection of tutorials for installing and upgrading IBM MQ on AIX®, Linux®, and Windows. The tutorials
cover:
• Preparing a host for IBM MQ.
• Downloading the IBM MQ code.
• Installing and uninstalling the IBM MQ code, and applying fix packs.
• Upgrading from one version of IBM MQ to another, and moving a queue manager from one host to
another.

Procedure
1. To find information on installing IBM MQ, see the appropriate sections for the platform, or platforms,
that your enterprise uses:

• “Installing and uninstalling IBM MQ on AIX” on page 32

• “Installing IBM MQ on Linux using rpm” on page 107

• “Installing and uninstalling IBM MQ on Windows” on page 158

2. To find out about concepts and considerations relating to installation, see “IBM MQ installation
overview” on page 6.

© Copyright IBM Corp. 2007, 2024 5

IBM MQ installation overview
An overview of concepts and considerations for installing IBM MQ, with links to instructions on how to
install, verify, and uninstall IBM MQ on each of the supported platforms.

Related concepts
“Multiple installations on AIX, Linux, and Windows” on page 17
On AIX, Linux, and Windows, it is possible to have more than one copy of IBM MQ on a system.
“Installation considerations for MQ Telemetry” on page 250
MQ Telemetry is a component of the main IBM MQ product. You can choose to install MQ Telemetry when
you first install IBM MQ, or when you modify an existing IBM MQ installation.
“Managed File Transfer product options” on page 244
Managed File Transfer can be installed as four different options, depending on your operating system and
overall setup. These options are Managed File Transfer Agent, Managed File Transfer Service, Managed
File Transfer Logger, or Managed File Transfer Tools.
Related tasks
“Maintaining and migrating IBM MQ” on page 275
Maintenance, upgrade, and migration have three distinct meanings for IBM MQ. The definitions are
described here. The following sections describe the various concepts associated with migration, followed
by the various tasks needed; these tasks are platform-specific where needed.
Installing Advanced Message Security
Use the information for your platform to guide you through installing the Advanced Message Security
(AMS) component.

IBM MQ components and features

You can select the components or features that you require when you install IBM MQ.
Important: Ensure that your enterprise has the correct license, or licenses, for the components that you
are going to install. For more information, see “License requirements” on page 8 and IBM MQ license
information.
Also review the information on hardware and software requirements for the platform on which you are
planning to install IBM MQ. For more information, see “Where to find product requirements and support
information” on page 9.

Installation of IBM MQ on Multiplatforms

IBM MQ can be installed as a server or a client. The installation images can be downloaded. See “Where
to find downloadable installation images” on page 9.
Separate client eImages are no longer available for downloading from Passport Advantage. Instead, you
can either get the client eImage from inside the main IBM MQ server eImage, which includes the server
and client, or you can download the IBM MQ client components from Fix Central. Follow the links in
Resource adapter, clients and other resources.
An IBM MQ server is an installation of one or more queue managers that provide queuing services to one
or more clients. All the IBM MQ objects, for example queues, exist only on the queue manager machine
(the IBM MQ server machine), and not the client. An IBM MQ server can also support local IBM MQ
applications.
An IBM MQ MQI client is a component that allows an application running on one system to communicate
with a queue manager running on another system. The output from the call is sent back to the client,
which passes it back to the application.
For detailed explanations of all the components that you can install, see:

• “IBM MQ components for AIX systems” on page 32

6 Installing and migrating IBM MQ

• “IBM MQ components for IBM i” on page 62

• “IBM MQ rpm components for Linux systems” on page 107

• “IBM MQ Debian components for Linux Ubuntu systems” on page 125

• “IBM MQ features for Windows systems” on page 158

For information about how to install IBM MQ on each supported platform, see the links in the following
table:

Table 1. Where to find IBM MQ installation information for each platform

Platform IBM MQ server IBM MQ client
“Installing IBM MQ server on “Installing an IBM MQ client on
AIX
AIX” on page 42 AIX” on page 47
“Installing IBM MQ server on IBM “Installing an IBM MQ client on
IBM i
i” on page 65 IBM i” on page 78
“Installing the first IBM MQ “Installing an IBM MQ client on
Linux
installation on Linux using the Linux using rpm” on page 118
rpm command” on page 111
“Installing an IBM MQ server “Installing an IBM MQ client
Linux
on Linux Ubuntu using Debian on Linux Ubuntu using Debian
packages” on page 128 packages ” on page 134
“Installing IBM MQ server on “Installing an IBM MQ client on
Windows
Windows” on page 176 Windows” on page 203

For more information about installing IBM MQ Advanced for Multiplatforms, see “Installing
IBM MQ Advanced for Multiplatforms” on page 236.

Note: Up to and including IBM MQ 8.0, IBM WebSphere® MQ for HP NonStop Server
was also a component platform. Since then, this component has been supplied and supported separately
as IBM MQ for HPE NonStop V8.1, which provides IBM MQ on HPE NonStop L-series and J-series
platforms. The documentation is here: IBM MQ for HPE NonStop V8.1.

Installing IBM MQ clients and servers

A client can be installed on its own, on a separate machine from the base product and server. It is also
possible to have both a server and a client installation on the same system.
To install an IBM MQ client on a system that is already running an IBM MQ server, you must use the
appropriate Server eImage downloaded from Passport Advantage. See “Where to find downloadable
installation images” on page 9.
Separate client eImages are no longer available for downloading from Passport Advantage. Instead, you
can either get the client eImage from inside the main IBM MQ server eImage, which includes the server
and client, or you can download the IBM MQ client components from Fix Central. Follow the links in
Resource adapter, clients and other resources.
Even if your client and server are installed on the same system, you must still define the MQI channel
between them. See Defining MQI channels for details.

Installing and migrating 7

 Advanced Message Security, Managed File Transfer, MQ Telemetry, and Replicated
data queue managers (RDQM)
Advanced Message Security, Managed File Transfer, MQ Telemetry, and RDQM are separately installed
components of IBM MQ. Make sure that you purchase a license for using IBM MQ Advanced before
installing any of these components (see IBM MQ license information). See “Installing IBM MQ Advanced
for Multiplatforms” on page 236 for installation instructions.
Related concepts
“Planning considerations for installation on Multiplatforms” on page 14
Before you install IBM MQ, you must choose which components to install and where to install them. You
must also make some platform-specific choices.
“Where to find downloadable installation images” on page 9
You download installation images for IBM MQ from Passport Advantage, Fix Central. A number of IBM
MQ components including fix packs, CSUs, clients, and the resource adapter are also available for
downloading from Fix Central and elsewhere.

License requirements
You must have purchased sufficient licenses for your installation. The details of the license agreement
is stored on your system at installation time so that you can read it at any time. IBM MQ supports IBM
License Metric Tool (ILMT).
Important: Ensure that your enterprise has the correct license, or licenses, for the components that you
are going to install. See IBM MQ license information for more details.

License files
At installation, the license agreement files are copied into the /licenses directory under the
MQ_INSTALLATION_PATH. You can read them at any time.

If you have installed a trial license, follow the instructions for converting a trial license on
the platform, or platforms, your enterprise uses.

On IBM i, you can use the WRKSFWAGR command to view the software licenses.

ILMT
ILMT automatically detects IBM MQ, if you are using it, and checks with it each time a queue manager is
started. You do not need to take any further action. You can install ILMT before or after IBM MQ.
The automatic detection applies to both the IBM MQ server and IBM MQ Java products.
Related concepts
“Hardware and software requirements on Linux systems” on page 94
Before you install IBM MQ, check that your system meets the hardware and operating system software
requirements for the particular components you intend to install.
“Hardware and software requirements on IBM i systems” on page 62
Check that the server environment meets the prerequisites for installing IBM MQ for IBM i.
“Hardware and software requirements on Windows systems” on page 168
Check that the server environment meets the prerequisites for installing IBM MQ for Windows and install
any prerequisite software that is missing from your system.
Related tasks
“Checking requirements on Windows” on page 168

8 Installing and migrating IBM MQ

Before you install IBM MQ on Windows, you must check for the latest information and system
requirements.

Where to find product requirements and support information

Before you install IBM MQ, you must check for the latest information and system requirements.
You can consult the following sources to check that you have the information that you need to help you
with planning your installation, including information on hardware and software requirements:
IBM MQ System Requirements website
For details of the supported operating systems, and the prerequisites, supported software, and
hardware requirements for each supported operating system, go to the System Requirements for
IBM MQ website and follow the links to the Detailed System Requirements report for the version of
IBM MQ that you are installing. You can select a report for a specific operating system or for a specific
component. In both cases, there are separate reports for Long Term Support and Continuous Delivery.
Product readme file
The product readme file includes information about last minute changes and known problems and
workarounds. The latest version is available at the IBM MQ, WebSphere MQ, and MQSeries® product
readmes web page. Always check to see that you have the latest version of the product readme file.
Support information
The IBM MQ support web page is regularly updated with the latest product support information. For
example, if you are migrating from an earlier version, look under the heading Solve a problem for the
document Problems and solutions when migrating.
Related concepts
“IBM MQ installation overview” on page 6
An overview of concepts and considerations for installing IBM MQ, with links to instructions on how to
install, verify, and uninstall IBM MQ on each of the supported platforms.
“Hardware and software requirements on AIX systems” on page 36
Before you install IBM MQ, check that your system meets the hardware and operating system software
requirements for the particular components you intend to install.
“Hardware and software requirements on IBM i systems” on page 62
Check that the server environment meets the prerequisites for installing IBM MQ for IBM i.
“Hardware and software requirements on Linux systems” on page 94
Before you install IBM MQ, check that your system meets the hardware and operating system software
requirements for the particular components you intend to install.
“Hardware and software requirements on Windows systems” on page 168
Check that the server environment meets the prerequisites for installing IBM MQ for Windows and install
any prerequisite software that is missing from your system.
Related tasks
“Applying maintenance to IBM MQ” on page 278
Maintenance is the application of a reversible fix. Any changes to queue manager data are compatible
with the previous code level.

Where to find downloadable installation images

You download installation images for IBM MQ from Passport Advantage, Fix Central. A number of IBM
MQ components including fix packs, CSUs, clients, and the resource adapter are also available for
downloading from Fix Central and elsewhere.
Note: This topic gives background information on the various types of downloadable images, and the
various sites from which you can download them. If you are already familiar with this information, and are
ready to download the latest images, go to Downloading IBM MQ 9.4 then click the CD tab for the latest
Continuous Delivery release or Cumulative Security Update (CSU), or the LTS tab for the latest Long Term
Support fix pack or CSU.

Installing and migrating 9

 Passport Advantage (for multiplatforms releases)
There are two Passport Advantage offerings. Passport Advantage is designed for larger
enterprises and enterprises with multiple sites. Passport Advantage Express® is designed for smaller
enterprises and single-site enterprises.
See the Passport Advantage and Passport Advantage Express website for further information on how you:
• Acquire new IBM software licenses.
• Renew Software Subscription and Support and Fixed Term Licenses.
• Buy and renew technical support for some Selected Open Source and other non-warranted applications.
• Subscribe to IBM SaaS offerings and acquire IBM Appliances.
You download IBM MQ Server eAssemblies for the full release on all supported platforms from Passport
Advantage. The eImages that make up the full release can be downloaded individually if you do not need
the full release.
The initial release is IBM MQ 9.4.0. For LTS users, it brings you up to date with the new functions that
were incrementally added into IBM MQ 9.3 by the CD releases. For CD users, it is the next CD release after
IBM MQ 9.3.5.
A free 90-day trial version of the LTS release, for each of the last two IBM MQ major versions, is available
for download here: https://www.ibm.biz/ibmmqtrial. This is useful if you want to try out IBM MQ, or if you
are waiting for a full version purchase to complete. When your purchase completes, you can convert your
trial installation to a full production copy.
Separate client eImages are no longer available for downloading from Passport Advantage. Instead, you
can either get the client eImage from inside the main IBM MQ server eImage, which includes the server
and client, or you can download the IBM MQ client components from Fix Central. Follow the links in
Resource adapter, clients and other resources.

Also available from Passport Advantage (subject to entitlement)

is the IBM Aspera faspio Gateway.

Note: Prior to 1Q 2023, non-install images for building your own

IBM MQ queue manager container images were available from Passport Advantage. These images are
now available on Fix Central. Follow the link in Resource adapter, clients and other resources.
For more information and download links, go to Downloading IBM MQ 9.4 then select the CD or LTS tab.

Fix Central (for Multiplatforms Fix Packs and CSUs)

You download IBM MQ for Multiplatforms Fix Packs and CSUs from Fix Central. For more
information and download links, go to Downloading IBM MQ 9.4, then select the CD or LTS tab.

Resource adapter, clients and other resources

A number of IBM MQ resources are also made available on Fix Central and elsewhere.
Clients:
• IBM MQ C and .NET clients
• IBM MQ Java / JMS client
• IBM MQ Java client components (on Maven)
• IBM MQ redistributable clients
• IBM MQ Resource Adapter - For use with any Java EE 7 or Jakarta EE compliant application server
• IBM MQ redistributable Managed File Transfer (MFT) Agents
• IBM MQ classes for .NET Standard (on NuGet)

10 Installing and migrating IBM MQ

• IBM MQ classes for XMS .NET Standard (on NuGet)
Components:
• IBM MQ Internet Pass-Thru (MQIPT)
• IBM MQ Explorer stand-alone install image - CD only, but can be used to perform administration on any
supported release of IBM MQ.
• IBM MQ Native HA on AWS
• IBM MQ Kafka Connectors

• IBM MQ Web Server stand-alone install image

Containers:
• Prebuilt: IBM MQ Advanced container (subject to entitlement).
• Build your own: https://github.com/ibm-messaging/mq-container. This works in conjunction with the
non-install (unzippable) IBM MQ images to build an IBM MQ container image that can run under the Red
Hat® OpenShift® anyuid security context constraint (SCC).
– For production environments the three non-install images for Linux (subject to entitlement) are
available here:
- IBM MQ Advanced non-install images for Linux
Note that each version of these non-install images is supported for one year only when used as part
of an IBM MQ CD release, or two years (with an optional extension for another year) when used as
part of an IBM Cloud Pak® for Integration LTS release.
– For development environments the non-install packages can be found at the following locations:
- IBM MQ Advanced for Developers non-install image for Linux x86-64
- IBM MQ Advanced for Developers non-install image for Linux PPCLE
- IBM MQ Advanced for Developers non-install image for Linux systemZ

- IBM MQ Advanced for Developers non-install image for Linux ARM64

– A sample helm chart is available here: https://github.com/ibm-messaging/mq-helm
Development:
• IBM MQ Advanced for Developers is available for the Windows and Linux platforms listed in the IBM
MQ 9.4 system requirements, running on x86-64 architectures. Also available (as-is, see the readme)
is a 32-bit version for Raspberry Pi. Download from the following locations: Windows / Linux / Ubuntu /
Raspberry Pi
• The IBM MQ Mac Toolkit for Development allows the execution of IBM MQ commands (for example
MQSC commands) on macOS devices (both ARM64 and x86-64). It also contains client libraries that
facilitate the development of macOS client applications that are executed on macOS devices (both
ARM64 and x86-64). The client is used in the Get started with IBM MQ tutorials.
• A pre-built IBM MQ Advanced for Developers container image is available from the IBM Container
Registry. It runs on Linux/x86-64. Or you can build your own container image to run on ARM64 and
x86-64 architectures.

SupportPacs
IBM MQ SupportPacs provide downloadable code and documentation that complements the IBM MQ
family of products. Each SupportPac supplies a particular function or service that can be used with one or
more of the IBM MQ products.
• SupportPacs for IBM MQ and other project areas
• IBM MQ - SupportPacs by Product

Installing and migrating 11

 Related concepts
“IBM MQ code signatures” on page 12
For IBM MQ 9.4, downloadable .zip, and .tar.gz files are signed. Installable .rpm and .deb files are
also signed. Where possible the signature is embedded in the file. For file formats that do not allow this, a
separate .sig file is made available containing the signatures and the public keys to verify them.
“IBM MQ components and features” on page 6
You can select the components or features that you require when you install IBM MQ.
Related tasks
Downloading IBM MQ classes for .NET Standard from the NuGet repository
Downloading IBM MQ classes for XMS .NET Standard from the NuGet repository
Related reference
IBM MQ license information
Related information
IBM MQ downloads for developers

IBM MQ code signatures

For IBM MQ 9.4, downloadable .zip, and .tar.gz files are signed. Installable .rpm and .deb files are
also signed. Where possible the signature is embedded in the file. For file formats that do not allow this, a
separate .sig file is made available containing the signatures and the public keys to verify them.
IBM MQ public certificates, checksums, pgp key and .sig files can be downloaded from the extra
download packages at https://ibm.biz/mq94signatures.

*.zip files
IBM MQ deliverables in .zip file form contain an embedded digital signature that can be verified by using
a recent Java Development Kit (JDK) as shown in the following example:

jarsigner -certs -verify 9.4.0.0-IBM-MQC-Redist-Java.zip

jar verified.

Note: More details, including the signer, can be found by running with the verbose option.

*.tar.gz files
IBM MQ deliverables in *.tar.gz file form are signed by IBM MQ and their digital signatures are
provided in the extra downloadable package. To verify a file's signature, use openssl as shown in the
following example for 9.4.0.0-IBM-MQC-Redist-LinuxX64.tar.gz:

openssl dgst -sha256 -verify ibm_mq_public.pem -signature 9.4.0.0-IBM-MQC-Redist-

LinuxX64.tar.gz.sig 9.3.0.0-IBM-MQC-Redist-LinuxX64.tar.gz
Verified OK

*.rpm
The IBM-provided RPMs are signed with a digital signature, and systems will not recognize the signing
key without it being authorized. Obtain the IBM MQ public signing gpg key from the extra downloadable
package and install it into rpm. This only needs to be done once per system.

rpm --import ibm_mq_public.pgp

The validity of any of the IBM MQ RPMs can then be verified, for example:

# rpm -Kv MQSeriesRuntime-9.4.0-0.x86_64.rpm

MQSeriesRuntime-9.4.0-0.x86_64.rpm:
Header V3 RSA/SHA256 Signature, key ID 0209b828: OK
Header SHA1 digest: OK

12 Installing and migrating IBM MQ

 V3 RSA/SHA256 Signature, key ID 0209b828: OK
MD5 digest: OK

Note: If you skip this step, then a harmless warning might be issued during RPM installation to indicate
there is a signature but the system does not recognize the signing key, for example:
warning: MQSeriesRuntime-9.4.0-0.x86_64.rpm: Header V3 RSA/SHA256 Signature, key ID 0209b828:
NOKEY

*.deb
The IBM provided debian type packages are signed with an embedded digital signature. To verify a
package you will need the IBM MQ public signing gpg key from the additional package, and the "debsigs"
operating system package installed.
1. Import the gpg key and identify its gpg key value:

# gpg --import ibm_mq_public.pgp

gpg: keybox '/root/.gnupg/pubring.kbx' created
gpg: /root/.gnupg/trustdb.gpg: trustdb created
gpg: key D2D53B4E0209B828: public key "IBM MQ signing key <[email protected]>" imported
gpg: Total number processed: 1
gpg: imported: 1

From this, the key value would be D2D53B4E0209B828 and the certificate alias would be "IBM MQ
signing key <[email protected]>". The following instructions use those values – replace them
with the ones calculated from your import.
2. Export the certificate alias into the system keyrings:

mkdir /usr/share/debsig/keyrings/D2D53B4E0209B828/
cd /usr/share/debsig/keyrings/D2D53B4E0209B828/
gpg --output IBMMQ.bin --export "IBM MQ signing key <[email protected]>"

3. Set up the system to enable a signing policy for this key:

mkdir /etc/debsig/policies/D2D53B4E0209B828/
cd /etc/debsig/policies/D2D53B4E0209B828/

Create a file called IBM-MQ.pol in this directory with the following contents. Note that only the 'id'
fields need changing to the key value from step 1.

<?xml version="1.0"?>
<!DOCTYPE Policy SYSTEM "https://www.debian.org/debsig/1.0/policy.dtd">
<Policy xmlns="https://www.debian.org/debsig/1.0/">
<Origin Name="IBM MQ signing key" id="D2D53B4E0209B828" Description="IBM MQ signing key"/>
<Selection>
<Required Type="origin" File="IBMMQ.bin" id="D2D53B4E0209B828"/>
</Selection>
<Verification MinOptional="0">
<Required Type="origin" File="IBMMQ.bin" id="D2D53B4E0209B828"/>
</Verification>
</Policy>

4. Validate packages individually using the debsig-verify utility:

# debsig-verify ibmmq-runtime_9.4.0.0_amd64.deb
debsig: Verified package from 'IBM MQ signing key' (IBM MQ signing key)

Note: Whilst it is possible to configure dpkg to verify signatures during installation, this is not advisable as
it will cause dpkg to reject the installation of unsigned Debian files.
Related tasks
“Installing the first IBM MQ installation on Linux using the rpm command” on page 111
You can install an IBM MQ server on a 64-bit Linux system using rpm. The instructions in this topic are for
the first installation of IBM MQ on a Linux system.
“Installing an IBM MQ client on Linux using rpm” on page 118

Installing and migrating 13

 Installing an IBM MQ client on a 64 bit Linux system.
“Installing IBM MQ on Linux Red Hat using yum” on page 121
You can install IBM MQ on Linux Red Hat by using the yum installer.

Planning considerations for installation on Multiplatforms

Before you install IBM MQ, you must choose which components to install and where to install them. You
must also make some platform-specific choices.
Before you start installing, consider how you want to use IBM MQ and review the information in this
section, and also the information in the general Planning section.
When planning your installation, make sure that you check the hardware and software requirements for
your system. For more information, see “Where to find product requirements and support information” on
page 9.

Installation name on AIX, Linux, and Windows

Each installation of IBM MQ on AIX, Linux, and Windows, has a unique identifier known as an installation
name. The installation name is used to associate things such as queue managers and configuration files
with an installation.
You can choose the installation name and make it meaningful to you. For example, you might call a test
system testMQ.
If you do not specify an installation name when the product is installed, a default installation name is
automatically assigned. For the first installation, this name is Installation1. For the second installation, the
name is Installation2, and so on. The installation name cannot be changed after the product is installed.

On AIX and Linux systems, the first IBM MQ installation is automatically given
an installation name of Installation1.
Note: For subsequent installations, you can use the crtmqinst command to set the installation name
before installing the product.

On Windows systems, you can choose the installation name during the installation process.
The installation name can be up to 16 bytes and must be a combination of alphabetic and numeric
characters in the ranges a-z, A-Z, and 0-9. You cannot use blank characters. The installation name must
be unique, regardless of whether uppercase or lowercase characters are used. For example, the names
INSTALLATIONNAME and InstallationName are not unique.
You can find out what installation name is assigned to an installation in a particular location using the
dspmqinst command.

Installation descriptions
Each installation can also have an installation description. This description can give more detailed
information about an installation in cases where the installation name cannot provide enough information.
These descriptions can be up to 64 single-byte characters, or 32 double-byte characters. The default
installation description is blank. You can set the installation description using the setmqinst command.
Related concepts
“Planning considerations for installation on Multiplatforms” on page 14
Before you install IBM MQ, you must choose which components to install and where to install them. You
must also make some platform-specific choices.
“Primary installation on AIX, Linux, and Windows” on page 18
On systems that support multiple installations of IBM MQ ( AIX, Linux, and Windows ), the primary
installation is the one to which IBM MQ system-wide locations refer. Having a primary installation is
optional, but convenient.
“Installation location on Multiplatforms” on page 15

14 Installing and migrating IBM MQ

You can install IBM MQ into the default location. Alternatively, you can install into a custom
location during the installation process. The location where IBM MQ is installed is known as the
MQ_INSTALLATION_PATH.
“IBM MQ components and features” on page 6
You can select the components or features that you require when you install IBM MQ.
Related reference
dspmqinst
setmqinst
crtmqinst

Installation location on Multiplatforms

You can install IBM MQ into the default location. Alternatively, you can install into a custom
location during the installation process. The location where IBM MQ is installed is known as the
MQ_INSTALLATION_PATH.

Default location
The default location for the IBM MQ product code is shown in the following table:

Table 2. Installation location of IBM MQ

Platform Installation location
/usr/mqm
AIX
/QIBM/ProdData/mqm
IBM i
/opt/mqm
Linux
C:\Program Files\IBM\MQ
Windows systems
C:\ProgramData\IBM\MQ
Windows data directories

Important: For Windows installations, the directories are as stated, unless there is a
previous installation of the product that still contains registry entries or queue managers, or both. In
this situation, the new installation uses the old data directory location. For more information, see Program
and data directory locations.

On IBM i, IBM MQ can only be installed in the default location. For more information about
the directory structure of IBM i, see Directory structure on IBM i

On AIX and Linux systems, working data is stored in /var/mqm, but you
cannot change this location. For more information about the directory structure of AIX and Linux systems,
see Directory structure on AIX and Linux systems.

Custom location installation

For an installation into a custom location, the path specified must either be an empty directory, or a path
that does not exist. The length of the path is limited to 256 bytes. Permissions on the path must be such
that the user mqm and users in the mqm group can access the directories.

• On AIX and Linux systems, the path must not contain spaces.

• On AIX, the product is installed into a User Specified Installation Location (USIL), which
can be either an existing USIL or a new USIL that is automatically created by the installation process. If

Installing and migrating 15

 a custom location is specified, the product location is the path specified during installation, plus /usr/
mqm.
For example, the path specified is /usr/custom_location. The MQ_INSTALLATION_PATH is /usr/
custom_location/usr/mqm.
Access permissions for the USIL directory should be set to rwx for user and r-x for group and others
(755).
• On the following platforms, the product location is the same path as specified during installation:

– Linux

– Windows
For example, on Linux, the path specified is /opt/custom_location. The MQ_INSTALLATION_PATH
is /opt/custom_location.
Note: Use rpm --prefix to specify the value of MQ_INSTALLATION_PATH. See step “6” on page 113
in Installing the first IBM MQ installation on Linux using the rpm command for an example of using rpm
--prefix.
• On the following platforms, you can install IBM MQ into a non empty MQ_INSTALLATION_PATH
directory:

– Linux
On Linux, you do this by setting the environment variable AMQ_OVERRIDE_EMPTY_INSTALL_PATH to 1
before starting the installation.
Note, that a non empty directory in this context, indicates a directory which contains system files and
directories.
For each installation, all of the IBM MQ components that you require must be installed in the same
location.
For more information about how to install to a custom location, see the installation topics for the
appropriate platform.

Additional location restrictions

New IBM MQ installations should not be located in the following paths:
• In a path that is a subdirectory of another existing installation.
• In a path that is part of the direct path to an existing installation.
If IBM MQ is installed in /opt/IBM/MQ/installations/1, you cannot install in /opt/IBM/MQ/
installations/1/a. Additionally, you should not install a new installation to /opt/IBM/MQ.
However, you can install a new installation in /opt/IBM/MQ/installations/2 or /opt/IBM/
MQnew because neither of these is a part of the direct path /opt/IBM/MQ/installations/1.
• In a path that is a subdirectory of the default location, for example:

– /usr/mqm on AIX.

– /opt/mqm on Linux.
The reason an installation should not be located in a path that is a subdirectory of the default location
is to avoid the risk if you later decide to install IBM MQ into the default location, and cannot then do so.
If you do subsequently install into the default location, because IBM MQ has full access rights over the
installation directory, existing files might be replaced or deleted. Scripts that you might subsequently
run to uninstall IBM MQ might remove the installation directory at the end of the script.
• In a directory or subdirectory that is, or might later be used by another product, for example, an IBM
Db2® installation, or operating system component.

16 Installing and migrating IBM MQ

 You must not install to any directory located under /opt/IBM/db2 where /opt/IBM/db2 is an
example.
• In a directory or subdirectory that the mqm user or mqm group does not have authority to write to.
Related concepts
“Planning considerations for installation on Multiplatforms” on page 14
Before you install IBM MQ, you must choose which components to install and where to install them. You
must also make some platform-specific choices.
“Installation name on AIX, Linux, and Windows” on page 14
Each installation of IBM MQ on AIX, Linux, and Windows, has a unique identifier known as an installation
name. The installation name is used to associate things such as queue managers and configuration files
with an installation.
“Primary installation on AIX, Linux, and Windows” on page 18
On systems that support multiple installations of IBM MQ ( AIX, Linux, and Windows ), the primary
installation is the one to which IBM MQ system-wide locations refer. Having a primary installation is
optional, but convenient.
“IBM MQ components and features” on page 6
You can select the components or features that you require when you install IBM MQ.

Multiple installations on AIX, Linux, and Windows

On AIX, Linux, and Windows, it is possible to have more than one copy of IBM MQ on a system.
You can choose where each copy of IBM MQ is installed, but each copy must be in a separate installation
location. A maximum of 128 installations of IBM MQ can exist on a single machine at a time. You have a
choice:
• Keep the simplicity of maintaining and managing a single installation of IBM MQ on a machine.
• Take advantage of the flexibility that is offered by enabling multiple IBM MQ installations.

Decisions to make before installing

Before you install multiple copies of IBM MQ, you must make several decisions:
Where will you install each copy of IBM MQ?
You can choose the installation location for your installations in IBM MQ. For more information, see
“Installation location on Multiplatforms” on page 15.
Do you need a primary installation?
A primary installation is an installation to which system-wide locations refer.
For more information, see “Primary installation on AIX, Linux, and Windows” on page 18.
How will your applications connect?
You need to consider how your applications locate the appropriate IBM MQ libraries. For more
information, see Connecting applications in a multiple installation environment, and Connecting .NET
applications in a multiple installation environment.
Do your existing exits need changing?
If IBM MQ is not installed in the default location, your exits need to be updated. For more information,
see Writing exits and installable services on AIX, Linux, and Windows .
Which queue manager will be associated with which installation?
Each queue manager is associated with a particular installation. The installation that a queue manager
is associated with limits that queue manager so that it can be administered only by commands from
that installation. For more information, see Associating a queue manager with an installation.
How will you set up your environment to work with each installation?
With multiple installations on a system, you need to consider how you will work with particular
installations, and how you will issue commands from that installation. You can either specify the full
path to the command, or you can use the setmqenv or crtmqenv command to set environment

Installing and migrating 17

 variables. Setting the environment variables allows you to omit the path to the commands for that
installation. For more information, see setmqenv, and crtmqenv.
When you have answered these questions, you can install IBM MQ after you have read “IBM MQ
installation overview” on page 6.
If you have existing installations of IBM MQ and you want to use the multiple installation capability
to migrate from one version of IBM MQ to another version, see “Multi-installation queue manager
coexistence on AIX, Linux, and Windows” on page 357.

The IBM message service client for .NET support pack and multiple installations
For multiple version support, on IBM MQ, the "Java and .NET Messaging and Web Services" feature
must be installed with the IBM MQ product. For more information about installing the .NET feature, see
Installing IBM MQ classes for .NET.
Related tasks
Configuring multiple installations
Finding installations of IBM MQ on a system
“Migrating on AIX and Linux: side-by-side” on page 411
“Migrating on AIX and Linux: multi-stage” on page 415
“Choosing MSI Instance IDs for multiple server installations” on page 180
For multiple silent installations, for each version that is installed you must find an MSI instance ID that is
available to use for that installation.
“Choosing MSI Instance IDs for multiple client installations” on page 205
For multiple silent installations, for each version that is installed you must find an MSI instance ID that is
available to use for that installation.

Primary installation on AIX, Linux, and Windows

On systems that support multiple installations of IBM MQ ( AIX, Linux, and Windows ), the primary
installation is the one to which IBM MQ system-wide locations refer. Having a primary installation is
optional, but convenient.
You can install multiple versions of IBM MQ on AIX, Linux, and Windows. You can have more than one
installation of IBM MQ on one of these systems at any time and, optionally, configure one of these
installations as the primary installation. Environment variables and symbolic links pointing to a single
installation are less meaningful when multiple versions exist. However, some functions require these
system-wide locations to work. For example, custom user scripts for administering IBM MQ, and third
party products. These functions work only on the primary installation.

On AIX and Linux systems, if you set an installation as the primary installation,
symbolic links to the external libraries and control commands of that installation are added into /usr/
lib, and /usr/bin. If you do not have a primary installation, the symbolic links are not created. For a list
of the symbolic links that are made to the primary installation, see “External library and control command
links to primary installation on AIX and Linux” on page 22.

On Windows systems, the global environmental variables point to the directories into which
the primary installation is installed. These environment variables are used to locate IBM MQ libraries,
control commands, and header files. Additionally, on Windows systems, some features of the operating
system require the central registration of interface libraries that are then loaded into a single process.
With multiple versions of IBM MQ, there would be conflicting sets of IBM MQ libraries. The features would
try to load these conflicting sets of libraries into a single process. Therefore, such features can be used
only with the primary installation. For more information, see “Features that can be used only with the
primary installation on Windows” on page 25.

18 Installing and migrating IBM MQ

Table 3. Primary installation options
Valid installation
Options configurations More information
Primar Non-
y primary
Single Versio None If you want to continue working with a single installation in
installation n 7.1 the same way as previous releases, configure your installation
or as the primary installation. For more information, see “Single
later installation of IBM MQ configured as the primary installation”
on page 20.
None Version 7.1 If you want to continue working with a single installation, but
or later do not want symbolic links or global environment variables
created for you, configure your installation as non-primary.
For more information,, see “Single installation of IBM MQ
configured as non-primary” on page 20.

Multiple Versio Version 7.1 If you want to have multiple installations of IBM MQ, you can
installations n 7.1 or later choose whether to make one of the installations primary. For
or more information, see “Multiple installations of IBM MQ” on
later page 21.
None Version 7.1
or later.

Related concepts
“Single installation of IBM MQ configured as the primary installation” on page 20
Marking an IBM MQ installation as primary adds symbolic links, or global environment variables to the
system so that the IBM MQ commands and libraries used by applications are automatically available with
minimum system setup required.
“Single installation of IBM MQ configured as non-primary” on page 20
If you install IBM MQ as non-primary you might have to configure a library path for applications to load
IBM MQ libraries. On Windows, some product capabilities are available only when IBM MQ is configured
as primary.
“Multiple installations of IBM MQ” on page 21
You can choose to have one of the IBM MQ installations configured as the primary installation. Your choice
depends on how applications locate libraries.
“Installation location on Multiplatforms” on page 15
You can install IBM MQ into the default location. Alternatively, you can install into a custom
location during the installation process. The location where IBM MQ is installed is known as the
MQ_INSTALLATION_PATH.
“Planning considerations for installation on Multiplatforms” on page 14
Before you install IBM MQ, you must choose which components to install and where to install them. You
must also make some platform-specific choices.
“Installation name on AIX, Linux, and Windows” on page 14
Each installation of IBM MQ on AIX, Linux, and Windows, has a unique identifier known as an installation
name. The installation name is used to associate things such as queue managers and configuration files
with an installation.
Related tasks
Changing the primary installation

Installing and migrating 19

 Single installation of IBM MQ configured as the primary installation
Marking an IBM MQ installation as primary adds symbolic links, or global environment variables to the
system so that the IBM MQ commands and libraries used by applications are automatically available with
minimum system setup required.
You decide where to install IBM MQ.
Where possible, configure applications and scripts to use the system search path to find the IBM MQ
control commands or IBM MQ libraries. This configuration of applications and scripts provides maximum
flexibility for undertaking future tasks such as migrating to the next release of IBM MQ, or installing a
second installation. For more information about options for connecting your applications, see Connecting
applications in a multiple installation environment.

On AIX and Linux, the first installation onto a system must be manually
configured to be the primary installation.

On Windows, the first installation is automatically configured as the primary installation.

Set the primary installation using the setmqinst command. For more information, see “Uninstalling,
upgrading, and maintaining the primary installation” on page 25.
Related concepts
“Installation location on Multiplatforms” on page 15
You can install IBM MQ into the default location. Alternatively, you can install into a custom
location during the installation process. The location where IBM MQ is installed is known as the
MQ_INSTALLATION_PATH.
“Planning considerations for installation on Multiplatforms” on page 14
Before you install IBM MQ, you must choose which components to install and where to install them. You
must also make some platform-specific choices.
“Installation name on AIX, Linux, and Windows” on page 14
Each installation of IBM MQ on AIX, Linux, and Windows, has a unique identifier known as an installation
name. The installation name is used to associate things such as queue managers and configuration files
with an installation.
Related tasks
Changing the primary installation

Single installation of IBM MQ configured as non-primary

If you install IBM MQ as non-primary you might have to configure a library path for applications to load
IBM MQ libraries. On Windows, some product capabilities are available only when IBM MQ is configured
as primary.

AIX and Linux systems

The implications of running a non-primary installation on AIX and Linux systems are as follows:
• Applications that locate their IBM MQ libraries using an embedded library path, for example, RPATH,
cannot find those libraries if the following conditions are true:
– IBM MQ is installed in a different directory from the directory specified in the RPATH
– There are no symbolic links in /usr
• Where applications locate their libraries using an external library path, for example, LD_LIBRARY_PATH,
you must configure the external library path to include the MQ_INSTALLATION_PATH/lib or
MQ_INSTALLATION_PATH/lib64 directory. The setmqenv and crtmqenv commands can configure a
number of environment variables in the current shell, including the external library path.
• Most IBM MQ processes run as setuid/setgid. As a result, when loading user exits they ignore the
external library path. User exits that reference IBM MQ libraries can find those libraries only if they are

20 Installing and migrating IBM MQ

 found in the library path embedded within them. They would be resolved if there were a symbolic link
in /usr. User exits that are intended to be run on IBM WebSphere MQ 7.1, or later, can now be built
so that they do not refer to IBM MQ libraries at all. Instead they rely on IBM MQ to pass in function
pointers to the IBM MQ functions that the exit can then use. For more information, see Writing exits and
installable services on AIX, Linux, and Windows .
For more information about options for connecting your applications, see Connecting applications in a
multiple installation environment.
On AIX and Linux platforms, the first installation onto a system is not automatically configured as the
primary installation. However, a single symbolic link is included in /usr/bin to locate the dspmqver
command. If you do not want any symbolic links, you must remove this link using the following command:

setmqinst -x -p MQ_INSTALLATION_PATH

Windows systems

The implications of running a non-primary installation on Windows are:

• Applications normally find their libraries using the external library path, PATH. There is no concept of
an embedded library path or explicit library location. If the installation is non-primary, the global PATH
environment variable does not contain the IBM MQ installation directory. For applications to find IBM
MQ libraries, update the PATH environment variable to reference the IBM MQ installation directory. The
setmqenv and crtmqenv commands can configure a number of environment variables in the current
shell, including the external library path.
• Some product capabilities are available only when an installation is configured as the primary
installation; see “Features that can be used only with the primary installation on Windows” on page
25.
By default, on Windows, the first installation is automatically configured as primary. You must manually
deselect it as the primary installation.
Related concepts
“Installation location on Multiplatforms” on page 15
You can install IBM MQ into the default location. Alternatively, you can install into a custom
location during the installation process. The location where IBM MQ is installed is known as the
MQ_INSTALLATION_PATH.
“Planning considerations for installation on Multiplatforms” on page 14
Before you install IBM MQ, you must choose which components to install and where to install them. You
must also make some platform-specific choices.
“Installation name on AIX, Linux, and Windows” on page 14
Each installation of IBM MQ on AIX, Linux, and Windows, has a unique identifier known as an installation
name. The installation name is used to associate things such as queue managers and configuration files
with an installation.
Related tasks
Changing the primary installation
Related reference
setmqenv
crtmqenv

Multiple installations of IBM MQ

You can choose to have one of the IBM MQ installations configured as the primary installation. Your choice
depends on how applications locate libraries.
The IBM MQ libraries, such as mqm, which ship with the product automatically use libraries of the level
required by the queue manager to which they are connecting. This means that provided an application

Installing and migrating 21

 locates its IBM MQ libraries from an IBM MQ installation, it can connect to any queue manager on that
system. Having one installation configured as primary ensures that if the application finds its IBM MQ
interface library, the application can connect to any queue manager.
For more information about connecting applications in a multiple installation environment, see
Connecting applications in a multiple installation environment.
The primary installation is not automatically changed when you uninstall the primary installation. If you
want another installation to be the primary installation, you must manually set the primary installation
using the setmqinst command. For more information, see “Uninstalling, upgrading, and maintaining the
primary installation” on page 25.
Related concepts
“Installation location on Multiplatforms” on page 15
You can install IBM MQ into the default location. Alternatively, you can install into a custom
location during the installation process. The location where IBM MQ is installed is known as the
MQ_INSTALLATION_PATH.
“Multiple installations on AIX, Linux, and Windows” on page 17
On AIX, Linux, and Windows, it is possible to have more than one copy of IBM MQ on a system.
“Planning considerations for installation on Multiplatforms” on page 14
Before you install IBM MQ, you must choose which components to install and where to install them. You
must also make some platform-specific choices.
“Installation name on AIX, Linux, and Windows” on page 14
Each installation of IBM MQ on AIX, Linux, and Windows, has a unique identifier known as an installation
name. The installation name is used to associate things such as queue managers and configuration files
with an installation.
Related tasks
Changing the primary installation

External library and control command links to primary installation on AIX and
Linux
On AIX and Linux platforms the primary installation is the one to which links from the /usr file system are
made. However, only a subset of those links created with previous releases are now made.
No links are created from /usr/include to any installation and only links to external libraries
and documented control commands are made from /usr/lib, and where appropriate, /usr/lib64
(external libraries) and /usr/bin (control commands).
In order to run these commands you must complete the following steps:
1. provide a full path to the command in an available IBM MQ installation,
2. use the setmqenv script to update your shell environment,
3. manually add the bin directory from an IBM MQ installation directory to your PATH,
4. run the setmqinst command as root to make one of your existing IBM MQ installations the primary
installation.

External libraries
Links are made to the following external libraries, both 32-bit and 64-bit:
• libmqm
• libmqm_r
• libmqmxa
• libmqmxa_r
• libmqmax
• libmqmax_r

22 Installing and migrating IBM MQ

• libmqmcb
• libmqmcb_r
• libmqic
• libmqic_r
• libmqcxa
• libmqcxa_r
• libmqicb
• libmqicb_r
• libimqb23ia
• libimqb23ia_r
• libimqc23ia
• libimqc23ia_r
• libimqs23ia
• libimqs23ia_r
• libmqmzf
• libmqmzf_r

• libimqb23ca

• libimqb23ca_r

• libimqc23ca

• libimqc23ca_r

• libimqs23ca

• libimqs23ca_r

Libraries containing "ia" have been built with the XLC 16 compiler, whilst libraries with "ca"
in the name have been built with the XLC 17 compiler.
The following 64-bit only libraries are also linked to:
• libmqmxa64
• libmqmxa64_r
• libmqcxa64
• libmqcxa64_r

Control commands
The following control commands are linked to from /usr/bin:
• addmqinf
• amqcrs6a
• amqcrsta
• amqmfsck
• crtmqinst
• dltmqinst
• dspmqinst
• setmqinst
• crtmqcvx

Installing and migrating 23

 • crtmqm
• dltmqm
• dmpmqaut
• dmpmqlog
• dspmq
• dspmqaut
• dspmqcsv
• dspmqfls
• dspmqinf
• dspmqrte
• dspmqtrc
• dspmqtrn
• dspmqver
• endmqcsv
• endmqlsr
• endmqm
• endmqtrc
• rcdmqimg
• rcrmqobj
• rmvmqinf
• rsvmqtrn
• runmqchi
• runmqchl
• runmqdlq

• runmqktool
• runmqlsr
• runmqsc
• runmqtmc
• runmqtrm
• setmqaut
• setmqenv
• setmqm
• setmqprd
• strmqcsv
• strmqm
• strmqtrc
Related concepts
“Primary installation on AIX, Linux, and Windows” on page 18
On systems that support multiple installations of IBM MQ ( AIX, Linux, and Windows ), the primary
installation is the one to which IBM MQ system-wide locations refer. Having a primary installation is
optional, but convenient.
“Features that can be used only with the primary installation on Windows” on page 25

24 Installing and migrating IBM MQ

Some Windows operating-system features can be used only with the primary installation. This restriction
is due to the central registration of interface libraries, which might conflict as a result of multiple versions
of IBM MQ being installed.

Features that can be used only with the primary installation on Windows
Some Windows operating-system features can be used only with the primary installation. This restriction
is due to the central registration of interface libraries, which might conflict as a result of multiple versions
of IBM MQ being installed.

The .NET monitor

The IBM MQ .NET monitor can run in two different modes: transactional and non-transactional. The
transactional mode uses MSDTC transaction coordination and requires that the .NET monitor is registered
with COM+. The .NET monitor from the primary installation is the only .NET monitor that is registered with
COM+.
Any attempt to run the .NET monitor in transactional mode with a non-primary installation
results in the failure of the .NET monitor to enlist with MSDTC. The .NET monitor receives an
MQRC_INSTALLATION_MISMATCH error, which in turn results in an AMQ8377 error message on the
console.
Related concepts
“Primary installation on AIX, Linux, and Windows” on page 18
On systems that support multiple installations of IBM MQ ( AIX, Linux, and Windows ), the primary
installation is the one to which IBM MQ system-wide locations refer. Having a primary installation is
optional, but convenient.
“External library and control command links to primary installation on AIX and Linux” on page 22
On AIX and Linux platforms the primary installation is the one to which links from the /usr file system are
made. However, only a subset of those links created with previous releases are now made.

Uninstalling, upgrading, and maintaining the primary installation

On all platforms, if you uninstall the primary installation, it ceases to be the primary installation. You must
run the setmqinst command to select a new primary installation. On Windows, if you update the primary
installation, it continues to be the primary installation. If you apply a fix pack to the primary installation, it
continues to be the primary installation.
Be cautious about the effect uninstalling or upgrading the primary installation has on applications.
Applications might be using the linkage library of the primary installation to switch to the linkage library
of another installation. If such an application is running, you might not be able to uninstall the primary
installation. The operating system might have locked the link library of the primary installation on behalf
of the application. If the primary installation has been uninstalled, an application that loads the IBM MQ
libraries it requires by linking to the primary installation is not able to start.
The solution is to switch the primary installation to another installation before uninstalling. Stop, and
restart applications that are linked through the previous primary installation before uninstalling it.

Windows

If you update the primary installation, it stops being the primary installation at the beginning of the
update procedure. If, by the end of the update procedure, you have not made another installation primary,
the upgraded installation is made primary again.

Maintenance
If you apply a fix pack to the primary installation, it stops being the primary installation at the beginning
of the maintenance procedure. If, by the end of the maintenance procedure, you have not made another
installation primary, the upgraded installation is made primary again.

Installing and migrating 25

 Related concepts
“Primary installation on AIX, Linux, and Windows” on page 18
On systems that support multiple installations of IBM MQ ( AIX, Linux, and Windows ), the primary
installation is the one to which IBM MQ system-wide locations refer. Having a primary installation is
optional, but convenient.
Related tasks
Changing the primary installation
“Applying maintenance to IBM MQ” on page 278
Maintenance is the application of a reversible fix. Any changes to queue manager data are compatible
with the previous code level.

Server-to-server links on AIX, Linux, and Windows

For verifying a server-to-server verification, the communication links between the two systems must
be checked. Before you can do the verification, you must ensure that the communications protocol is
installed and configured on both systems.
The examples used in the verification tasks listed in this topic for AIX, Linux, and Windows use TCP/IP.
The various communication protocols used by the supported platforms are as follows.

AIX
IBM MQ supports both TCP and SNA. If you do not use TCP, see Setting up communication on AIX and
Linux systems.

Linux
IBM MQ for Linux supports TCP on all Linux platforms. On x86 platforms and Power platforms, SNA
is also supported. If you want to use the SNA LU6.2 support on these platforms, you need the IBM
Communications Server for Linux 6.2. The Communications Server is available as a PRPQ product
from IBM. For more details, see Communications Server.
If you do not use TCP, see Setting up communication on AIX and Linux systems.

Windows
IBM MQ for Windows supports TCP, SNA, NetBios, and SPX. If you do not use TCP, see Setting up
communication for Windows .
Related tasks
“Verifying an IBM MQ installation on AIX” on page 50
The topics in this section provide instructions on how to verify a server or a client installation of IBM MQ
on AIX systems.
“Verifying an IBM MQ installation on Linux” on page 139
The topics in this section provide instructions on how to verify a server or a client installation of IBM MQ
on Linux systems.
“Verifying an IBM MQ installation on Windows” on page 220
The topics in this section provide instructions on how to verify a server or a client installation of IBM MQ
on Windows systems.

Redistributable IBM MQ clients

The IBM MQ redistributable client is a collection of runtime files that are provided in a .zip or .tar file
that can be redistributed to third parties under redistributable license terms. This provides a simple way
of distributing applications and the runtime files that they require in a single package.
For information about redistributable license terms for the redistributable IBM MQ clients, see IBM MQ
Redistributable Components.

26 Installing and migrating IBM MQ

What are the IBM MQ redistributable clients?
The redistributable client that is supplied with IBM MQ is also a non-installed and relocatable image.
Maintenance of a redistributable, non-installed image, is achieved through replacement; that is, you
download newer versions of the runtime components when they are shipped.
• A redistributable client implies distributing the required run time with an application both inside and
outside of your environment.
• A relocatable client implies putting the files somewhere else other than a fixed default location. For
example, instead of installing into /opt/ installing into /usr/local.
• A non-installed client implies that you are not required to lay down client files, and that these files can
be copied as required.
From IBM MQ 8.0.0 Fix Pack 4, native redistributable client runtime libraries are provided for Linux
x86-64 and Windows 64-bit platforms to make it simple to distribute both applications and the required
IBM MQ runtime libraries. A third package, which is not platform-specific, contains the runtime files that
are required for the Java/JMS applications, including the IBM MQ resource adapter for JMS applications
that are running under an application server.
Note: For important considerations about bundling the relocatable JAR files for IBM MQ classes for JMS,
see What is installed for IBM MQ classes for JMS.
You can use the files that are contained in the redistributable images to run the following client
applications:
• Native IBM MQ applications using the MQI written in C, C++, and COBOL.
• IBM MQ applications using the IBM MQ classes for Java and IBM MQ classes for JMS.

• IBM MQ using fully managed and unmanaged .NET classes.

XMS .NET is shipped as part of the redistributable client. XMS .NET requires the IBM MQ .NET client
(amqmdnet.dll). If unmanaged mode is to be used, then the IBM MQ C client libraries are also needed
along with amqmdnet.dll.
Managed File Transfer Agent is optionally provided as an individual redistributable component, available
to be downloaded as a tar package on Linux, or as zip package on Windows. This option enables
developers to download, configure and test a Managed File Transfer Agent, to ensure it connects to an
existing Managed File Transfer configuration and then make the configured agent bundle available to
many users within their organization. Users who are unfamiliar with how Managed File Transfer works, can
easily set up the pre-configured agent on their local environment and quickly connect to the relevant IBM
MQ network. The users do not have to install IBM MQ to be able to transfer files. For more information,
see Configuring the Redistributable Managed File Transfer Agent.

Downloading the redistributable client packages

You can download the redistributable client packages from Fix Central:
• IBM MQ redistributable clients
• IBM MQ redistributable Managed File Transfer Agents
The file names describe the file contents and equivalent maintenance levels.
For V9R4M0, the downloadable packages for the native redistributable client runtime libraries and JMS
and Java runtime files are available under the following file names:

Long Term Support: 9.4.0 IBM MQ C redistributable client for Linux x86-64
9.4.0.0-IBM-MQC-Redist-LinuxX64.tar.gz

Long Term Support: 9.4.0 IBM MQ C and .NET redistributable client for Windows x64
9.4.0.0-IBM-MQC-Redist-Win64.zip
Long Term Support: 9.3.0 IBM MQ JMS and Java redistributable client
9.4.0.0-IBM-MQC-Redist-Java.zip

Installing and migrating 27

 For IBM MQ 9.4, the downloadable packages for the Redistributable Managed File Transfer Agent are
available under the following file names:

Long Term Support: 9.4.0 Redistributable IBM MQ Managed File Transfer Agent for
Linux X86-64
9.4.0.0-IBM-MQFA-Redist-LinuxX64

Long Term Support: 9.4.0 Redistributable IBM MQ Managed File Transfer Agent for
Linux on z Systems
9.4.0.0-IBM-MQFA-Redist-LinuxS390X

Long Term Support: 9.4.0 Redistributable IBM MQ Managed File Transfer Agent for
Linux PPC (Little Endian)
9.4.0.0-IBM-MQFA-Redist-LinuxPPC64LE

Long Term Support: 9.4.0 Redistributable IBM MQ Managed File Transfer Agent for
Windows x64
9.4.0.0-IBM-MQFA-Redist-Win64
The IBM IPLA license agreement is extended for IBM MQ to enable you to download a number of
additional runtime files from Fix Central.
Note: See Downloading and configuring Redistributable Managed File Transfer components for details on
upgrading those components.
Related concepts
“Planning considerations for installation on Multiplatforms” on page 14
Before you install IBM MQ, you must choose which components to install and where to install them. You
must also make some platform-specific choices.
“Installation location on Multiplatforms” on page 15
You can install IBM MQ into the default location. Alternatively, you can install into a custom
location during the installation process. The location where IBM MQ is installed is known as the
MQ_INSTALLATION_PATH.
“Redistributable clients on Linux” on page 136
The Linux x86-64 image is shipped in a LinuxX64.tar.gz file.
“Redistributable clients on Windows” on page 218
The Windows 64-bit image is shipped in a Win64.zip file.
“.NET application runtime - Windows only” on page 219
Considerations when using the .NET application.
Related tasks
Configuring the Redistributable Managed File Transfer Agent
Upgrading Redistributable Managed File Transfer components

Limitations and other considerations for redistributable clients

There are a number of points to consider when installing the IBM MQ C redistributable client for Linux
x86-64 and the IBM MQ C and .NET redistributable client for Windows x64 packages.

Limitations
IBM Global Security Kit (GSKit) objects
No new GSKit objects are shipped. Only the runtime files are shipped, both in a regular installation
and with the redistributable client.
IBM JREs
No IBM JREs are provided with the redistributable client.

28 Installing and migrating IBM MQ

 If you want to run Java/JMS applications, you must provide your own runtime environment. Your
JRE, that applications run under, must meet the current SOE requirements and are bound by any
restrictions or limitations that apply.
Developing applications
Before IBM MQ 9.2.0, all other files that support the development and distribution of applications
(including copybooks, header files, and sample source code) are not available in any of the
redistributable client packages, including the IBM MQ C redistributable client packages, and are not
licensed for redistribution. If you need to develop IBM MQ applications, you still need to perform a
traditional installation so that you obtain the SDK files that are required to build client applications.
From IBM MQ 9.2.0, this limitation no longer applies to the IBM MQ C redistributable client packages.
From IBM MQ 9.2.0, the IBM MQ C redistributable client packages include the elements required to
build the application, that is the header files and copybooks. However, the sample source code is still
not included in these packages.

Windows C runtime libraries

You might have these libraries on your machine already, but if you do not, you need to download and
install the following Microsoft C/C++ runtime libraries:
• Microsoft Visual C++ Redistributable 2008
• Microsoft Visual C++ Redistributable 2012
The download links for the redistributable downloads for each of these libraries can be found at The
latest supported Visual C++ downloads.
The redistributable Java client does not include any of the files related to the JMSAdmin tool
A client installed by unpacking the redistributable Java client does not contain the JMSAdmin tool,
or its prerequisite JAR files fscontext.jar and providerutil.jar. This means that the client
cannot connect to any file system contexts (.bindings files) created by a different installation that
does have the JMSAdmin tool.
If you want to use a pre-existing file system context (.bindings file) with the redistributable Java
client, you can obtain these pre-requisite JAR files from Maven:
• https://mvnrepository.com/artifact/com.sun.jndi/providerutil/1.2
• https://mvnrepository.com/artifact/com.sun.jndi/fscontext
From IBM MQ 9.2.0 Fix Pack 2 for Long Term Support and IBM MQ 9.2.2 for Continuous Delivery, the
self-extracting JAR file version-IBM-MQ-Install-Java-All.jar includes all of the files related
to the JMSAdmin tool. For more information, see Obtaining the IBM MQ classes for JMS separately.

Choosing the files to distribute with an application

A script file named genmqpkg is provided by the redistributable client under the bin directory. You
can use the genmqpkg script to generate a smaller subset of files that are tailored to the needs of the
application for which the files are intended to be distributed.
When you run the script, you are asked a series of interactive Yes or No questions to determine the
runtime requirements for an IBM MQ application. Finally, genmqpkg asks you to supply a new target
directory, where the script duplicates the required directories and files.
The genmqpkg script that is shipped with the IBM MQ C redistributable client packages includes an
additional question asking whether the runtime requires the SDK to compile applications. For the IBM MQ
C redistributable client packages, responses can be given programmatically. All the interactive prompts
can be bypassed by setting environment variables and executing the command with a -b flag to indicate a
batch mode.
Important: IBM support is only able to provide assistance with the full, unmodified set of files contained
within the redistributable client packages.

Installing and migrating 29

 Home directory
A ${HOME}/.mqm directory is created when using an unregistered or non-installed version of IBM MQ,
such as the redistributable client.
The directory is created so that IBM MQ has a reliable way of accessing its socket files using a path that
fits within the sun_path length. If IBM MQ cannot write to the HOME directory you receive an error
message.

Classpath changes
The classpath used by dspmqver, setmqenv, and crtmqenv commands adds the
com.ibm.mq.allclient.jar and com.ibm.mq.jakarta.client.jar to the environment,
immediately following the com.ibm.mq.jar, and com.ibm.mqjms.jar.

Modular applications using IBM MQ classes for JMS or IBM MQ classes for Jakarta
Messaging

You can configure modular applications to use IBM MQ classes for JMS and IBM MQ classes for Jakarta
Messaging by requiring the appropriate module within your application, and including the appropriate
directory in the module-path. For more information, see Configuring your modular application to use IBM
MQ classes for JMS or IBM MQ classes for Jakarta Messaging.

Other considerations
The default data path of a non-installed client is:

Linux x86-64
$HOME/IBM/MQ/data

Windows
%HOMEDRIVE%\%HOMEPATH%\IBM\MQ\data
On AIX and Linux systems, the length of the path must not contain spaces.
Important: A redistributable client runtime co-exists with a full IBM MQ client or server installation,
provided that they are installed in different locations. However, unpacking a redistributable image into the
same location as a full IBM MQ installation is not supported.
On Linux the ccsid.tbl used to define the supported CCSID conversions is traditionally expected to be
found in the UserData directory structure, along with error logs, trace files, and so on. The UserData
directory structure is populated by unpacking the redistributable client, and so, if the file is not found in
its usual location, the redistributable client falls back to locate the file in the /lib subdirectory of the
installation.

dspmqver output examples

An example of dspmqver output from the redistributable client on Linux:

Name: IBM MQ
Version: 8.0.0.4
Level: p800-804-L150909
BuildType: IKAP - (Production)
Platform: IBM MQ for Linux (x86-64 platform)
Mode: 64-bit
O/S: Linux 2.6.32.59-0.7-default
InstName: MQNI08000004
InstDesc: IBM MQ V8.0.0.4 (Redistributable)
Primary: No
InstPath: /Development/johndoe/unzip/unpack
DataPath: /u/johndoe/IBM/MQ/data
MaxCmdLevel: 802

30 Installing and migrating IBM MQ

 An example of dspmqver output from the redistributable client on Windows:

Name: IBM MQ
Version: 8.0.0.4
Level: p800-804-L150909
BuildType: IKAP - (Production)
Platform: IBM MQ for Windows (x64 platform)
Mode: 64-bit
O/S: Windows 7 Professional x64 Edition, Build 7601: SP1
InstName: MQNI08000004
InstDesc: IBM MQ V8.0.0.4 (Redistributable)
Primary: No
InstPath: C:\Users\johndoe\Desktop\Redist
DataPath: C:\Users\johndoe\IBM\MQ\data
MaxCmdLevel: 802

Related concepts
“Redistributable IBM MQ clients” on page 26
The IBM MQ redistributable client is a collection of runtime files that are provided in a .zip or .tar file
that can be redistributed to third parties under redistributable license terms. This provides a simple way
of distributing applications and the runtime files that they require in a single package.
“.NET application runtime - Windows only” on page 219
Considerations when using the .NET application.

IBM MQ non-install images

IBM MQ non-install images provide the IBM MQ product in a tar.gz format that can be unzipped and has
no further installation steps. The purpose of this packaging of IBM MQ is to deliver the IBM MQ product in
a format that can be used for building container images.
Note: These packages are provided only for building container images and are not supported for any other
use cases.
Copies of these packages are provided with Developer, Non-Production and Production license terms for
Linux x86-64, Linux on IBM Z and Linux on PPCLE. The Github mq-container project is a working example
with documentation on how to build a container image using these packages. It is made available under
an Apache V2 license and may be copied and customized for your own purposes.
To download the packages, go to IBM MQ downloads and follow the link to the IBM MQ release specific
download document. Production and Non-Production packages are on IBM Fix Central and the Developer
packages are on IBM Downloads.
The main differences between the installable and non-install IBM MQ packages are as follows:
Security
• The user that starts the queue manager will be the user that the queue manager is running as.
• The primary group of the user starting the queue manager will be considered the administrative
group rather than "mqm".
• No setuid on any IBM MQ executables. IBM MQ executables are required to run as a non-root user.
• It is no longer possible to authenticate incoming IBM MQ client users using local user credentials.
IBM MQ is not authorized to access this operating system information, so only LDAP/UserExternal
authorization can be used.
Install
(If you using the IBM MQ Operator on OpenShift, this is handled transparently by the IBM MQ
Operator.)
As no installer technology is used:
• The installation is not registered with the operating system.
• Initial data directory structures do not exist and should be created with
<MQ_INSTALLATION_PATH>/bin/crtmqdir -a -f.

Installing and migrating 31

 The product data directory is within the running user's home directory rather than /var/mqm. You can
change the default directory of the data path by using the MQ_OVERRIDE_DATA_PATH environment
variable.
Note: You must create the directory first, as the directory is not created automatically.
The setmqenv command can be used to initialize the current command environment, making it easier
to work with the package.
Related reference
setmqenv (set IBM MQ environment)

Installing and uninstalling IBM MQ on AIX

Installation tasks that are associated with installing IBM MQ on AIX systems are grouped in this section.

About this task

To prepare for installation and to install the IBM MQ components, complete the following tasks.
For information about how to uninstall IBM MQ, see “Uninstalling or modifying IBM MQ on AIX” on page
59.
If product fixes or updates are made available, see “Applying maintenance to IBM MQ” on page 278.

Procedure
1. Check the system requirements.
See “Checking requirements on AIX” on page 35.
2. Plan your installation.
• As part of the planning process, you must choose which components to install and where to install
them. See “IBM MQ components for AIX systems” on page 32.
• You must also make some platform-specific choices. See “Planning to install IBM MQ on AIX” on
page 37.
3. Prepare your system for installation of IBM MQ.
See “Preparing the system on AIX” on page 37.
4. Install IBM MQ server.
See “Installing IBM MQ server on AIX” on page 42.
5. Optional: Install an IBM MQ client.
See “Installing an IBM MQ client on AIX” on page 47.
6. Verify your installation. See “Verifying an IBM MQ installation on AIX” on page 50.

IBM MQ components for AIX systems

You can select the components that you require when you install IBM MQ.
Important: For details of what each purchase of IBM MQ entitles you to install, see IBM MQ license
information.
On AIX each component of IBM MQ is represented by a fileset. Table 4 on page 33 shows the filesets
that are available when installing an IBM MQ server or client on an AIX system:

32 Installing and migrating IBM MQ

Table 4. IBM MQ filesets for AIX systems
Component Description Serve Client Fileset name
r medi
medi a
a
Runtime Contains files that are common to both server mqm.base.runtime
and client installations.
Note: This component must be installed.

Server You can use the server to run queue mqm.server.rte

managers on your system and connect to
other systems over a network. Provides
messaging and queuing services to
applications, and support for IBM MQ client
connections.
Standard Client The IBM MQ MQI client is a small subset of mqm.client.rte
IBM MQ, without a queue manager, that uses
the queue manager and queues on other
(server) systems. It can be used only when
the system it is on is connected to another
system that is running a full server version of
IBM MQ. The client and the server can be on
the same system if required.
SDK The SDK is required for compiling mqm.base.sdk
applications. It includes sample source
files, and the bindings (files .H, .LIB, .DLL,
and others), that you need to develop
applications to run on IBM MQ.
Sample The sample application programs are needed mqm.base.samples
programs if you want to check your IBM MQ installation
using the verification procedures.
Java messaging The files needed for messaging using Java mqm.java.rte
(includes Java Message Service).
Man pages AIX man pages, in U.S. English, for: mqm.man.en_US.data
control commands
MQI calls
MQSC commands

Java JRE A Java Runtime Environment that is used by mqm.jre.rte

those parts of IBM MQ that are written in
Java.
Message For available languages, see the table of
Catalogs message catalogs that follows.
IBM Global IBM Global Security Kit (GSKit) V8 Certificate mqm.gskit.rte
Security Kit and TLS, Base Runtime.
(GSKit)

Installing and migrating 33

 Table 4. IBM MQ filesets for AIX systems (continued)
Component Description Serve Client Fileset name
r medi
medi a
a
Telemetry MQ Telemetry supports the connection of mqm.xr.service
Service Internet Of Things (IOT) devices (that is,
remote sensors, actuators and telemetry
devices) that use the IBM MQ Telemetry
Transport (MQTT) protocol. The telemetry
(MQXR) service enables a queue manager
to act as an MQTT server, and communicate
with MQTT client apps.
A set of MQTT clients is available from the
Eclipse Paho downloads page. These sample
clients help you write your own MQTT client
apps that IOT devices use to communicate
with MQTT servers.
See also “Installation considerations for MQ
Telemetry” on page 250.

Managed File MQ Managed File Transfer transfers files mqm.ft.agent

Transfer between systems in a managed and mqm.ft.base
auditable way, regardless of file size or mqm.ft.logger
the operating systems used. For information mqm.ft.service
about the function of each component, see mqm.ft.tools
“Managed File Transfer product options” on
page 244.
Advanced Provides a high level of protection for mqm.ams.rte
Message sensitive data flowing through the IBM
Security MQ network, while not impacting the end
applications. You must install this component
on all IBM MQ installations that host queues
you want to protect.
You must install the IBM Global Security
Kit (GSKit) component on any IBM MQ
installation that is used by a program that
puts or gets messages to or from a protected
queue, unless you are using only Java client
connections.
You must install the Java JRE component to
install this component.

AMQP Service Install this component to make AMQP mqm.amqp.rte

channels available. AMQP channels support
AMQP 1.0 APIs. You can use AMQP channels
to give AMQP applications access to the
enterprise-level messaging facilities provided
by IBM MQ.
REST API and Adds HTTP based administration for IBM MQ mqm.web.rte
Console through the REST API and IBM MQ Console.

34 Installing and migrating IBM MQ

Table 5. IBM MQ message catalogs for AIX systems
Message catalog language Component name
Brazilian Portuguese mqm.msg.pt_BR
Czech mqm.msg.cs_CZ
French mqm.msg.fr_FR
German mqm.msg.de_DE
Hungarian mqm.msg.hu_HU
Italian mqm.msg.it_IT
Japanese mqm.msg.ja_JP, mqm.msg.Ja_JP
Korean mqm.msg.ko_KR
Polish mqm.msg.pl_PL
Russian mqm.msg.ru_RU
Spanish mqm.msg.es_ES
Simplified Chinese mqm.msg.zh_CN, mqm.msg.Zh_CN
Traditional Chinese mqm.msg.zh_TW, mqm.msg.Zh_TW
U.S. English mqm.msg.en_US

Related concepts
“IBM MQ components and features” on page 6
You can select the components or features that you require when you install IBM MQ.
“Planning considerations for installation on Multiplatforms” on page 14
Before you install IBM MQ, you must choose which components to install and where to install them. You
must also make some platform-specific choices.

Checking requirements on AIX

Before you install IBM MQ on AIX, you must check for the latest information and system requirements.

About this task

A summary of the tasks that you must complete to check system requirements is listed here with links to
further information.

Procedure
1. Check that you have the latest information, including information on hardware and software
requirements.
See “Where to find product requirements and support information” on page 9.
2. Check that your systems meet the initial hardware and software requirements for AIX.
See “Hardware and software requirements on AIX systems” on page 36.
3. Check that your systems have sufficient disk space for the installation.
See Disk space requirements.
4. Check that you have the correct licenses.
See “License requirements” on page 8 and IBM MQ license information.

Installing and migrating 35

 What to do next
When you have completed these tasks, you are ready to start preparing your system for installation. For
the next steps in installing IBM MQ, see “Preparing the system on AIX” on page 37.
Related concepts
“IBM MQ installation overview” on page 6
An overview of concepts and considerations for installing IBM MQ, with links to instructions on how to
install, verify, and uninstall IBM MQ on each of the supported platforms.
Related tasks
“Applying maintenance to IBM MQ” on page 278
Maintenance is the application of a reversible fix. Any changes to queue manager data are compatible
with the previous code level.

Hardware and software requirements on AIX systems

Before you install IBM MQ, check that your system meets the hardware and operating system software
requirements for the particular components you intend to install.
For hardware and software requirements, see System Requirements for IBM MQ.

Host names
IBM MQ does not support host names that contain spaces. If you install IBM MQ on a system with a host
name that contains spaces, you are unable to create any queue managers.

32-bit client support

Attention: There is no separate 32-bit client installation package. The client installation package
and redistributable client contain both 32-bit and 64-bit IBM MQ client libraries. The included
32-bit libraries can be used by 32-bit applications on supported platforms where 32-bit support is
offered by the operating system.

Java Message Service

From IBM MQ 9.3.0, Jakarta Messaging 3.0 is supported for developing new applications.
IBM MQ 9.3.0 and later continue to support JMS 2.0 for existing applications. It is not supported to use
both the Jakarta Messaging 3.0 API and the JMS 2.0 API in the same application. For more information,
see Using IBM MQ classes for JMS/Jakarta Messaging.
Java 8 is bundled with IBM MQ 9.0, but client components are built with Java 7 compatibility flags on.
For development, a JDK is required, and a JRE is required for running. The JRE does not need to be the
JRE installed with IBM MQ, but has to be one from the supported list.
For a list of supported JDKs, see System Requirements for IBM MQ.
You can check the version installed using the following command:

java -version

Transport Layer Security (TLS)

If you want to use the TLS support, you need the IBM Global Security Kit (GSKit) version 8 package. This
package is supplied with IBM MQ as one of the components available for installation.

Unicode support on AIX

If you need to convert data to and from Unicode on your system, you must install the following file sets:

36 Installing and migrating IBM MQ

 bos.iconv.ucs.com Unicode converters for AIX sets
bos.iconv.ucs.ebcdic Unicode converters for EBCDIC sets
bos.iconv.ucs.pc Unicode converters for PC sets

Planning to install IBM MQ on AIX

Before you install IBM MQ on AIX, you must choose which components to install and where to install
them. You must also make some platform-specific choices.

About this task

The following steps provide links to additional information to help you with planning your installation of
IBM MQ on AIX.
As part of your planning activities, make sure that you review the information on hardware and software
requirements for the platform on which you are planning to install IBM MQ. For more information, see
“Checking requirements on AIX” on page 35.

Procedure
• Decide which IBM MQ components and features to install.
See “IBM MQ components and features” on page 6 and “Where to find downloadable installation
images” on page 9.
Important: Ensure that your enterprise has the correct license, or licenses, for the components that
you are going to install. For more information, see “License requirements” on page 8 and IBM MQ
license information.
• Review the options for naming your installation.
In some cases, you can choose an installation name to use instead of the default name. See
“Installation name on AIX, Linux, and Windows” on page 14.
• Review the options and restrictions for choosing an installation location for IBM MQ.
For more information, see “Installation location on Multiplatforms” on page 15.
• If you plan to install multiple copies of IBM MQ, see “Multiple installations on AIX, Linux, and
Windows” on page 17.
• If you already have a primary installation, or plan to have one, see “Primary installation on AIX, Linux,
and Windows” on page 18.
• Make sure that the communications protocol needed for server-to-server verification is installed and
configured on both systems that you plan to use.
For more information, see “Server-to-server links on AIX, Linux, and Windows” on page 26.

Preparing the system on AIX

On AIX systems, you might have to complete several tasks before you install IBM MQ. You might also
want to complete other tasks, depending on your installation intentions.

About this task

The tasks that you perform to prepare your systems for installation are listed here. Complete the
appropriate tasks for your platform before installing.

Procedure
1. Set up a user ID of the name mqm, with a primary group of mqm.
See “Setting up the user and group on AIX” on page 38.

Installing and migrating 37

 Note: If the group mqm and/or user mqm do not exist, during the installation of the product, the installer
creates group mqm and user mqm with a home directory of /var/mqm.
2. Create file systems for both the product code and working data to be stored. See “Creating file systems
on AIX” on page 39.
3. Configure any additional settings needed for your AIX system.
See “Configuring and tuning the operating system on AIX” on page 41.

What to do next
When you have completed the tasks to prepare the system, you are ready to start installing IBM MQ. To
install a server, see “Installing IBM MQ server on AIX” on page 42. To install a client, see “Installing an
IBM MQ client on AIX” on page 47.
Related tasks
Planning
“Maintaining and migrating IBM MQ” on page 275
Maintenance, upgrade, and migration have three distinct meanings for IBM MQ. The definitions are
described here. The following sections describe the various concepts associated with migration, followed
by the various tasks needed; these tasks are platform-specific where needed.
“Applying maintenance to IBM MQ” on page 278
Maintenance is the application of a reversible fix. Any changes to queue manager data are compatible
with the previous code level.

Setting up the user and group on AIX

On AIX systems, IBM MQ requires a user ID of the name mqm, with a primary group of mqm. The mqm user
ID owns the directories and files that contain the resources associated with the product.

Creating the user ID and group

Set the primary group of the mqm user to the group mqm.
Note: If the group mqm and/or user mqm do not exist, during the installation of the product, the installer
creates group mqm and user mqm with a home directory of /var/mqm
If you are installing IBM MQ on multiple systems you might want to ensure each UID and GID of mqm
has the same value on all systems. If you are planning to configure multi-instance queue managers, it is
essential the UID and GID are the same from system to system. It is also important to have the same UID
and GID values in virtualization scenarios.
You can use the System Management Interface Tool ( smit ), for which you require root authority.
1. To create the mqm group, display the required window using this sequence:

Security & Users

Groups
Add a Group

Set the group name field to mqm.

2. To create the user mqm, display the required window using this sequence:

Security & Users

Users
Add a User

Set the user name field to mqm.

3. To add a password to the new user ID, display the required window using this sequence:

Security & Users

38 Installing and migrating IBM MQ

 Passwords
Change a User's Password

Set the password as required.

Adding existing user IDs to the group

If you want to run administration commands, for example crtmqm (create queue manager) or strmqm
(start queue manager), your user ID must be a member of the mqm group. This user ID must not be longer
than 12 characters.
Users do not need mqm group authority to run applications that use the queue manager; it is needed only
for the administration commands.
You can use smit to add an existing user ID to the mqm group. Display the required menu using this
sequence:

Security & Users

Users
Change / Show Characteristics of a User

Type the name of the user in the User Name field and press Enter. Add mqm to the Group SET field,
which is a comma-separated list of the groups to which the user belongs. Users do not need to have their
primary group set to mqm. If mqm is in their set of groups, they can use the administration commands.

Log files created by MQ Telemetry service

The umask setting of the user ID that creates a queue manager will determine the permissions of the
Telemetry log files generated for that queue manager. Even though the ownership of the log files will be
set to mqm.
Related concepts
“Creating file systems on AIX” on page 39
Before installing IBM MQ, you might need to create file systems for both the product code and working
data to be stored. There are minimum storage requirements for these file systems. The default installation
directory for the product code can be changed at installation time, but the working data location cannot
be changed.
“Configuring and tuning the operating system on Linux” on page 101
Use this topic when you are configuring IBM MQ on Linux systems.
Related tasks
“Configuring and tuning the operating system on AIX” on page 41
When installing IBM MQ on AIX systems, there are some additional settings that must be configured.

Creating file systems on AIX

Before installing IBM MQ, you might need to create file systems for both the product code and working
data to be stored. There are minimum storage requirements for these file systems. The default installation
directory for the product code can be changed at installation time, but the working data location cannot
be changed.

Determining the size of a server installations file system

To determine the size of the /var/mqm file system for a server installation, consider:
• The maximum number of messages in the system at one time.
• Contingency for message buildups, if there is a system problem.
• The average size of the message data, plus 500 bytes for the message header.
• The number of queues.
• The size of log files and error messages.

Installing and migrating 39

 • The amount of trace that is written to the /var/mqm/trace directory.
Storage requirements for IBM MQ also depend on which components you install, and how much working
space you need. For more details, see Disk space requirements.

Creating a file system for the working data

Before you install IBM MQ, create and mount a file system called /var/mqm which is owned by the user
mqm in the group mqm; see “Setting up the user and group on AIX” on page 38. This file system is used
by all installations of IBM MQ on a system. If possible, use a partition strategy with a separate volume
for the IBM MQ data. This means that other system activity is not affected if a large amount of IBM
MQ work builds up. Configure the directory permissions to permit the mqm user to have full control, for
example, file mode 755. These permissions will then be updated during the IBM MQ installation to match
the permissions required by the queue manager.

Creating separate file systems for errors and logs

You can also create separate file systems for your log data ( /var/mqm/log ) and error files ( /var/mqm/
errors ). If possible, place these directories on different physical disks from the queue manager data
( /var/mqm/qmgrs ) and from each other.
If you create separate file systems the /var/mqm/errors directory can be NFS mounted. However, if
you choose to NFS-mount /var/mqm/errors, the error logs might be lost if the network fails.
You can protect the stability of your queue manager by having separate file systems for:
• /var/mqm/errors
• /var/mqm/trace
• /var/mqm/qmgrs
• /var/mqm/log
In the case of /var/mqm/errors, it is rare that this directory receives large quantities of data. But it
is sometimes seen, particularly if there is a severe system problem leading to IBM MQ writing a lot of
diagnostic information in to .FDC files. In the case of /var/mqm/trace, files are only written here when
you use strmqtrc to start tracing IBM MQ.
You can obtain better performance of normal IBM MQ operations (for example, syncpoints, MQPUT,
MQGET of persistent messages) by placing the following on separate disks:
• /var/mqm/qmgrs
• /var/mqm/log
In the rare event that you need to trace an IBM MQ system for problem determination, you can reduce
performance impact by placing the /var/mqm/trace file system on a separate disk.
If you are creating separate file systems, allow a minimum of 30 MB of storage for /var/mqm, 100 MB
of storage for /var/mqm/log, and 10 MB of storage for /var/mqm/errors. The 100 MB minimum
allowance of storage for /var/mqm/log is the absolute minimum required for a single queue manager
and is not a recommended value. The size of a file system must be scaled according to the number of
queue managers that you intend to use, the number of pages per log file, and the number of log files per
queue manager.
For more information about file systems, see File system support.
The size of the log file depends on the log settings that you use. The minimum sizes are for circular logging
using the default settings. For more information about log sizes, see Calculating the size of the log.
Related concepts
“Setting up the user and group on AIX” on page 38

40 Installing and migrating IBM MQ

On AIX systems, IBM MQ requires a user ID of the name mqm, with a primary group of mqm. The mqm user
ID owns the directories and files that contain the resources associated with the product.
Related tasks
“Configuring and tuning the operating system on AIX” on page 41
When installing IBM MQ on AIX systems, there are some additional settings that must be configured.

Configuring and tuning the operating system on AIX

When installing IBM MQ on AIX systems, there are some additional settings that must be configured.

About this task

When you install IBM MQ on AIX systems, you must configure the following operating system settings:
• File descriptors
• System resource limits

Procedure
• Increase the process limit for the number of file descriptors.
When running a multi-threaded process such as the agent process, you might reach the soft limit for
file descriptors. This limit gives you the IBM MQ reason code MQRC_UNEXPECTED_ERROR (2195)
and, if there are enough file descriptors, an IBM MQ FFST file.
To avoid this problem, increase the process limit for the number of file descriptors. You must alter
the nofiles attribute in /etc/security/limits to 10,000 for the mqm user ID, or in the default
stanza. To alter the number of file descriptors, complete the following steps:
a) Check the maximum number of file descriptors available to a process running as mqm:

lsuser -a nofiles mqm

b) Set the value to at least 10240:

chuser nofiles=10240 mqm

chuser nofiles_hard=10240 mqm

• Set the system resource limit for data segment and stack segment to unlimited using the following
commands in a command prompt:

ulimit -d unlimited
ulimit -s unlimited

Attention: For an mqm user ID other than root, the value unlimited might not be permitted.

What to do next
You can check your system configuration using the mqconfig command.
During high load IBM MQ can use virtual memory (swap space). If virtual memory becomes full it could
cause IBM MQ processes to fail or become unstable, affecting the system.
To prevent this situation your IBM MQ administrator should ensure that the system has been allocated
enough virtual memory as specified in the operating system guidelines.
For more information on configuring your system, see How to configure AIX and Linux systems for IBM
MQ.
Related concepts
“Setting up the user and group on AIX” on page 38

Installing and migrating 41

 On AIX systems, IBM MQ requires a user ID of the name mqm, with a primary group of mqm. The mqm user
ID owns the directories and files that contain the resources associated with the product.
“Creating file systems on AIX” on page 39
Before installing IBM MQ, you might need to create file systems for both the product code and working
data to be stored. There are minimum storage requirements for these file systems. The default installation
directory for the product code can be changed at installation time, but the working data location cannot
be changed.

Installing IBM MQ server on AIX

You can install an IBM MQ server on AIX either interactively or silently.

Before you begin

• Before you start the installation procedure, make sure that you complete the necessary steps that are
outlined in “Preparing the system on AIX” on page 37.
• IBM MQ can be installed into System Workload Partitions (WPARs) with both shared and private file
systems. For installation into private file systems, IBM MQ can be installed directly into the System
WPAR by using the procedure that is outlined in this topic. There are some limitations for shared /usr
file systems:
– The dspmqinst and dspmqver commands might report the primary installation incorrectly when
compared with the symbolic links in /usr/bin. To synchronize the reporting of the primary
installation in a System WPAR and the global environment, run setmqinst with the -i or -x
parameter, on the individual zones.
– You cannot change the primary installation within a WPAR. You must change the primary installation
through the global environment, which has appropriate write access to /usr/bin.
Note: During installation to a non-default location, ATTENTION messages that relate to errupdate or
trcupdate are produced. These messages are not errors. However, AIX system trace for IBM MQ is
not supported for installations in a non-default location, and IBM MQ trace must be used for problem
determination.
• If you install a copy of IBM MQ server for AIX by using a downloadable installation image, obtained from
Passport Advantage, you need to:
1. Decompress the tar file, by using the following command:

uncompress IBM_MQ_9.4.0_AIX.tar.Z

2. Extract the installation files from the tar file, by using the following command:

tar -xvf IBM_MQ_9.4.0_AIX.tar

3. Use the installation tools installp or smit to install the IBM MQ server for AIX.
Tip: If you find that the Function keys do not work in SMIT, try pressing Esc and the Function key number
to emulate the required Function key.

About this task

IBM MQ is supplied as a set of filesets that are installed by using the standard AIX installation tools. The
procedure uses the system management interface tool (SMIT), but you can choose to use installp,
geninstall or the web-based System Manager. You can select which components you want to install.
The components and file sets are listed in “IBM MQ components for AIX systems” on page 32.
This procedure installs IBM MQ into the default location of /usr/mqm.
Use the procedure that is described in “Installing the IBM MQ server silently on AIX” on page 44 if you
want to install IBM MQ in any one of the following situations:
• As the first installation on your system by using installp

42 Installing and migrating IBM MQ

• As the first installation on your system, and you are installing the product to a location that is not the
default location
• Alongside an existing installation
If you want to carry out a side-by-side installation, alongside an existing installation of IBM MQ in the
default location, you must install the second version of the product in a location that is not the default. To
create the non-default installation location you must use the mkusil command, which is available only
from the command line.
You can then use installp (see “Installing the IBM MQ server silently on AIX” on page 44), or SMIT if
you select the Relocatable Software Installation menu item.
If you want to carry out a single stage migration, refer to “Migrating on AIX and Linux: single-stage” on
page 407.

Procedure
1. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux. This information also applies to UNIX systems in general.
2. Set your current directory to the location of the installation packages.
The location might be a network location, or a local file system directory. See Where to find
downloadable installation images.
3. Select the required smit window by using the following sequence:

Software Installation and Maintenance

Install and Update Software
Install and Update from ALL Available Software

4. Specify the input directory in the INPUT device / directory for software field.
a) Enter a period character .
b) Press the Enter key
5. List the software in the SOFTWARE to install field:
a) Enter .
b) Press F4
6. Select the file sets to install from the list. If you require messages in a language different from the
language that is specified by the locale that is selected on your system, ensure that you include the
appropriate message catalog. Enter ALL to install all applicable filesets.
7. View the license agreement:
a) Change Preview new LICENSE agreements? to yes
b) Press Enter
8. Accept the license agreements and install IBM MQ:
a) Change ACCEPT new license agreements? to yes
b) Change Preview new LICENSE agreements? to no
c) Press Enter

What to do next
• If you chose this installation to be the primary installation on the system, you must now set it as the
primary installation. Enter the following command at the command prompt:

MQ_INSTALLATION_PATH/bin/setmqinst -i -p MQ_INSTALLATION_PATH

where MQ_INSTALLATION_PATH represents the directory where IBM MQ is installed.

Installing and migrating 43

 You can have only one primary installation on a system. If there is already a primary installation on the
system, you must unset it before you can set another installation as the primary installation. For more
information, see Changing the primary installation.
• You might want to set up the environment to work with this installation. You can use the setmqenv or
crtmqenv command to set various environment variables for a particular installation of IBM MQ. For
more information, see setmqenv and crtmqenv.
• If you want to confirm that the installation was successful, you can verify your installation. For more
information, see “Verifying an IBM MQ installation on AIX” on page 50.
Related concepts
“Installation location on Multiplatforms” on page 15
You can install IBM MQ into the default location. Alternatively, you can install into a custom
location during the installation process. The location where IBM MQ is installed is known as the
MQ_INSTALLATION_PATH.
“Multiple installations on AIX, Linux, and Windows” on page 17
On AIX, Linux, and Windows, it is possible to have more than one copy of IBM MQ on a system.
“Primary installation on AIX, Linux, and Windows” on page 18
On systems that support multiple installations of IBM MQ ( AIX, Linux, and Windows ), the primary
installation is the one to which IBM MQ system-wide locations refer. Having a primary installation is
optional, but convenient.
Related tasks
“Installing the IBM MQ server silently on AIX” on page 44
You can carry out a non-interactive installation of the IBM MQ server from the command line using
the AIX installp command. A non-interactive installation is also known as a silent, or unattended
installation.
“Uninstalling or modifying IBM MQ on AIX” on page 59
On AIX, you can uninstall the IBM MQ server or client using the System Management Interface Tool
(SMIT) or the installp command. You can also modify an installation by uninstalling a subset of the file
sets.
Changing the primary installation
Related reference
setmqinst

Installing the IBM MQ server silently on AIX

You can carry out a non-interactive installation of the IBM MQ server from the command line using
the AIX installp command. A non-interactive installation is also known as a silent, or unattended
installation.

Before you begin

Before you start the installation procedure, make sure that you have completed the necessary steps
outlined in “Preparing the system on AIX” on page 37.
Note: During installation, errors relating to errupdate or trcupdate might occur. This can caused by
installing to a non-default location, if so these errors can be safely ignored. However, native trace for IBM
MQ is only supported when installed in the default location.

About this task

You can use this method to install to a non-default location, and can select which components you want
to install. The components and filesets are listed in “IBM MQ components and features” on page 6.

Procedure
1. Log in as root, or with sufficient authority to run the following commands.

44 Installing and migrating IBM MQ

 You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux. This information also applies to UNIX systems in general.
2. Set your current directory to the location of the installation packages.
The location might be a network location, or a local file system directory. See Where to find
downloadable installation images.
3. Install the product in one of the following ways:
• Install the whole product in the default location:

installp -acgXYd . all

• Install selected file sets in the default location:

installp -acgXYd . list of file sets

• Install the whole product in a non-default location using the -R flag:

installp -R USIL_Directory -acgXYd . all

• Install selected file sets in a non-default location using the -R flag:

installp -R USIL_Directory -acgXYd . list of file sets

where USIL_Directory is a directory which exists before the command is run; it must not contain
any spaces or usr/mqm. IBM MQ is installed underneath the directory specified. For example, if /
USIL1 is specified, the IBM MQ product files are located in /USIL1/usr/mqm. This location is known
as the MQ_INSTALLATION_PATH.

What to do next
• If you have chosen this installation to be the primary installation on the system, you must now set it as
the primary installation. Enter the following command at the command prompt:

MQ_INSTALLATION_PATH/bin/setmqinst -i -p MQ_INSTALLATION_PATH

where MQ_INSTALLATION_PATH represents the directory where IBM MQ is installed.

You can have only one primary installation on a system. If there is already a primary installation on the
system, you must unset it before you can set another installation as the primary installation. For more
information, see Changing the primary installation.
• You might want to set up the environment to work with this installation. You can use the setmqenv or
crtmqenv command to set various environment variables for a particular installation of IBM MQ . For
more information, see setmqenv and crtmqenv.
• If you want to confirm that the installation was successful, you can verify your installation. See
“Verifying an IBM MQ installation on AIX” on page 50, for more information.
Related concepts
“Multiple installations on AIX, Linux, and Windows” on page 17
On AIX, Linux, and Windows, it is possible to have more than one copy of IBM MQ on a system.
“Primary installation on AIX, Linux, and Windows” on page 18
On systems that support multiple installations of IBM MQ ( AIX, Linux, and Windows ), the primary
installation is the one to which IBM MQ system-wide locations refer. Having a primary installation is
optional, but convenient.
Related tasks
“Installing IBM MQ server on AIX” on page 42
You can install an IBM MQ server on AIX either interactively or silently.
“Uninstalling or modifying IBM MQ on AIX” on page 59

Installing and migrating 45

 On AIX, you can uninstall the IBM MQ server or client using the System Management Interface Tool
(SMIT) or the installp command. You can also modify an installation by uninstalling a subset of the file
sets.
Changing the primary installation
Related reference
setmqinst
User Specified Installation Location (USIL)

Converting a trial license on AIX

Convert a trial license to a full license without reinstalling IBM MQ.
When the trial license expires, the "count-down" displayed by the strmqm command informs you the
license has expired, and the command does not run.

Before you begin

1. IBM MQ is installed with a trial license.
2. You have access to the installation media of a fully licensed copy of IBM MQ.

About this task

Run the setmqprd command to convert a trial license to a full license.
If you do not want to apply a full license to your trial copy of IBM MQ, you can uninstall it at any time.

Procedure
1. Obtain the full license from the fully licensed installation media.
The full license file is amqpcert.lic. On AIX, it is in the /MediaRoot/licenses directory on the
installation media.
2. Run the setmqprd command from the installation that you are upgrading:

MQ_INSTALLATION_PATH/bin/setmqprd /MediaRoot/licenses/amqpcert.lic

Related reference
setmqprd

Displaying messages in your national language on AIX

To display messages from a different national language message catalog, you must install the appropriate
catalog and set the LANG environment variable.

About this task

Messages in the language specified by the locale selected on your machine at installation time are
installed by default.
To find out which language is currently in use, run the locale command.
If this returns a language which is not one of the national languages provided by IBM MQ, you must select
a national language, otherwise you will not get a message catalog installed on your system.

Message catalogs for all languages are installed in MQ_INSTALLATION_PATH/msg/language

identifier, where language identifier is one of the identifiers in Table 6 on page 47. If you require
messages in a different language, perform the following steps:

46 Installing and migrating IBM MQ

Procedure
1. Install the appropriate message catalog (see “IBM MQ components and features” on page 6 ).
2. To select messages in a different language, ensure the LANG environment variable is set to the
identifier for the language you want to install:

Table 6. Language identifiers

Identifier Language
cs_CZ Czech
de_DE German
es_ES Spanish
fr_FR French
hu_HU Hungarian
it_IT Italian
ja_JP Japanese
ko_KR Korean
pl_PL Polish
pt_BR Brazilian Portuguese
ru_RU Russian
zh_CN Simplified Chinese
zh_TW Traditional Chinese

AIX has some additional message catalogs:

Table 7. AIX specific language identifiers

Identifier Language
Ja_JP Japanese
Zh_CN Simplified Chinese
Zh_TW Traditional Chinese

Installing an IBM MQ client on AIX

You can interactively install the IBM MQ client for AIX using smit.

Before you begin

Before you start the installation procedure, make sure that you have completed the necessary steps
outlined in “Preparing the system on AIX” on page 37.

About this task

IBM MQ is supplied as a set of filesets that are installed using the standard AIX installation tools. The
procedure uses the System Management Interface Tool ( smit ), but you can choose to use installp,
geninstall or the web-based System Manager. You can select which components you want to install.
The components and filesets are listed in “IBM MQ components for AIX systems” on page 32. You must
install at least the Runtime and Client components.

Installing and migrating 47

 This procedure installs IBM MQ into the default location. If you want to install to a non-default location,
you must use installp, see “Installing an IBM MQ client silently on AIX” on page 49.

Procedure
1. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux. This information also applies to UNIX systems in general.
2. Set your current directory to the location of the installation packages.
The location might be a network location, or a local file system directory. See Where to find
downloadable installation images.
3. Select the required smit window using the following sequence:

Software Installation and Maintenance

Install and Update Software
Install and Update from ALL Available Software

4. Click List to display the input device or directory for the software and select the location that contains
the installation images.
5. Select the SOFTWARE to install field to obtain a list of available filesets, and select the filesets you
want to install. Ensure that you include the appropriate message catalog if you require messages in
a language different from the language specified by the locale specified on your system. Enter ALL to
install all applicable filesets.
6. Change Preview new LICENSE agreements? to yes and press Enter to view the license agreements.
7. If you have a previous version of the product on your system, change the Automatically install
requisite software to no.
8. Change ACCEPT new license agreements? to yes and press Enter to accept the license agreements.
9. Change Preview new LICENSE agreements? to no and press Enter to install IBM MQ.

What to do next
• If you have chosen this installation to be the primary installation on the system, you must now set it as
the primary installation. Enter the following command at the command prompt:

MQ_INSTALLATION_PATH/bin/setmqinst -i -p MQ_INSTALLATION_PATH

You can have only one primary installation on a system. If there is already a primary installation on the
system, you must unset it before you can set another installation as the primary installation. For more
information, see Changing the primary installation.
• You might want to set up the environment to work with this installation. You can use the setmqenv or
crtmqenv command to set various environment variables for a particular installation of IBM MQ. For
more information, see setmqenv and crtmqenv.
• For instructions on how to verify your installation, see “Testing communication between a client and a
server on AIX” on page 58.
Related tasks
“Uninstalling or modifying IBM MQ on AIX” on page 59

48 Installing and migrating IBM MQ

On AIX, you can uninstall the IBM MQ server or client using the System Management Interface Tool
(SMIT) or the installp command. You can also modify an installation by uninstalling a subset of the file
sets.

Installing an IBM MQ client silently on AIX

You can carry out a non-interactive, or silent, installation of an IBM MQ client from the command line
using the AIX installp command.

Before you begin

Before you start the installation procedure, make sure that you have completed the necessary steps
outlined in “Preparing the system on AIX” on page 37.
Note: Installation to a non-default location is not supported on systems that have the AIX Trusted
Computing Base (TCB) enabled.

About this task

You can use this method to install to a non-default location, and can select which components you want
to install. The components and filesets are listed in “IBM MQ components and features” on page 6. You
must install at least the Runtime and Client components.

Procedure
1. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux. This information also applies to UNIX systems in general.
2. Set your current directory to the location of the installation packages.
The location might be a network location, or a local file system directory. See Where to find
downloadable installation images.
3. Install the product in one of the following ways:
• Install the whole product in the default location:

installp -acgXYd . all

• Install selected filesets in the default location:

installp -acgXYd . list of file sets

• Install the whole product in a non-default location using the -R flag:

installp -R USIL_Directory -acgXYd . all

• Install selected filesets in a non-default location using the -R flag:

installp -R USIL_Directory -acgXYd . list of file sets

where the directory specified with the -R flag is an AIX User Specified Installation Location (USIL)
directory which exists before the command is run; it must not contain any spaces or usr/mqm.
IBM MQ is installed underneath the directory specified. For example, if /USIL1 is specified,
the IBM MQ product files are located in /USIL1/usr/mqm. This location is known as the
MQ_INSTALLATION_PATH.

What to do next
• If you have chosen this installation to be the primary installation on the system, you must now set it as
the primary installation. Enter the following command at the command prompt:

Installing and migrating 49

 MQ_INSTALLATION_PATH/bin/setmqinst -i -p MQ_INSTALLATION_PATH

You can have only one primary installation on a system. If there is already a primary installation on the
system, you must unset it before you can set another installation as the primary installation. For more
information, see Changing the primary installation.
• You might want to set up the environment to work with this installation. You can use the setmqenv or
crtmqenv command to set various environment variables for a particular installation of IBM MQ. For
more information, see setmqenv and crtmqenv.
• For instructions on how to verify your installation, see “Testing communication between a client and a
server on AIX” on page 58.

Verifying an IBM MQ installation on AIX

The topics in this section provide instructions on how to verify a server or a client installation of IBM MQ
on AIX systems.

About this task

You can verify a local (stand-alone) server installation or a server-to-server installation of the IBM MQ
server:
• A local server installation has no communication links with other IBM MQ installations.
• A server-to-server installation does have links to other installations.
You can also verify that your IBM MQ MQI client installation completed successfully and that the
communication link is working.

Procedure
• To verify a local server installation, see “Verifying a local server installation using the command line on
AIX” on page 50.
• To verify a server-to-server installation, see “Verifying a server-to-server installation using the
command line on AIX” on page 52.
• To verify a client installation, see “Verifying a client installation using the command line on AIX” on
page 55.

Verifying a local server installation using the command line on AIX

On AIX systems, you can verify a local server installation by using the command line to create a simple
configuration of one queue manager and one queue.

Before you begin

To verify the installation, you must first install the samples package.
Before beginning the verification procedure, you might want to check that you have the latest fixes for
your system. For more information about where to find the latest updates, see “Checking requirements on
AIX” on page 35.

About this task

Use the following steps to configure your default queue manager from the command line. After the queue
manager is configured, use the amqsput sample program to put a message on the queue. You then use
the amqsget sample program to get the message back from the queue.
IBM MQ object definitions are case-sensitive. Any text entered as an MQSC command in lowercase is
converted automatically to uppercase unless you enclose it in single quotation marks. Make sure that you
type the examples exactly as shown.

50 Installing and migrating IBM MQ

Procedure
1. On an AIX system, log in as a user in the mqm group.
2. Set up your environment:
a) Set up environment variables for use with a particular installation by entering one the following
command:

. MQ_INSTALLATION_PATH/bin/setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

b) Check that the environment is set up correctly by entering the following command:

dspmqver

If the command completes successfully, and the expected version number and installation name
are returned, the environment is set up correctly.
3. Create a queue manager called QMA by entering the following command:

crtmqm QMA

Messages indicate when the queue manager is created, and when the default IBM MQ objects are
created.
4. Start the queue manager by entering the following command:

strmqm QMA

A message indicates when the queue manager starts.

5. Start MQSC by entering the following command:

runmqsc QMA

A message indicates when MQSC starts. MQSC has no command prompt.

6. Define a local queue called QUEUE1 by entering the following command:

DEFINE QLOCAL (QUEUE1)

A message indicates when the queue is created.

7. Stop MQSC by entering the following command:

end

Messages are shown, followed by the command prompt.

Note: Subsequent steps require that the samples package is installed.
8. Change into the MQ_INSTALLATION_PATH/samp/bin directory, which contains the sample
programs.
MQ_INSTALLATION_PATH represents the high-level directory in which IBM MQ is installed.
9. Put a message on the queue by entering the following commands

./amqsput QUEUE1 QMA

The following messages are shown:

Sample AMQSPUT0 start

target queue is QUEUE1

10. Type some message text on one or more lines, where each line is a different message. Enter a blank
line to end the message input.
The following message is shown:

Installing and migrating 51

 Sample AMQSPUT0 end

Your messages are now on the queue and the command prompt is shown.
11. Get the messages from the queue, by entering the following command:

./amqsget QUEUE1 QMA

The sample program starts, and your messages are displayed.

Results
You have successfully verified your local installation.

Verifying a server-to-server installation using the command line on AIX

You can verify a server-to-server installation using two servers, one as a sender and one as a receiver.

Before you begin

• On AIX, IBM MQ supports both TCP and SNA.
The examples in this task use TCP/IP. If you do not use TCP, see Setting up communication on AIX and
Linux.
• If you are using TCP/IP, make sure that TCP/IP and IBM MQ are installed on both servers.
• Make sure that you are a member of the IBM MQ administrators group (mqm) on each server.
• Decide which installation is the sender server and which installation is the receiver server. The
installations might be on the same system, or on different systems.

About this task

IBM MQ object definitions are case-sensitive. Any text entered as an MQSC command in lowercase is
converted automatically to uppercase unless you enclose it in single quotation marks. Make sure that you
type the examples exactly as shown.

Procedure
1. On the receiver server:
a) On AIX, log in as a user in the mqm group.
b) Check which ports are free, for example by running netstat. For more information about this
command, see the documentation of your operating system.
If port 1414 is not in use, make a note of 1414 to use as the port number in step 2 h. Use the same
number for the port for your listener later in the verification. If it is in use, note a port that is not in
use; for example 1415.
c) Set up the environment for the installation you are using by entering the following command at the
command prompt:

. MQ_INSTALLATION_PATH/bin/setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

d) Create a queue manager called QMB by entering the following command at the command prompt:

crtmqm QMB

Messages tell you that the queue manager has been created, and that the default IBM MQ objects
have been created.
e) Start the queue manager by entering the following command:

52 Installing and migrating IBM MQ

 strmqm QMB

A message tells you when the queue manager has started.

f) Start MQSC by entering the following command:

runmqsc QMB

A message tells you that MQSC has started. MQSC has no command prompt.
g) Define a local queue called RECEIVER.Q by entering the following command:

DEFINE QLOCAL (RECEIVER.Q)

A message tells you the queue has been created.

h) Define a listener by entering the following command:
DEFINE LISTENER (LISTENER1) TRPTYPE (TCP) CONTROL (QMGR) PORT ( PORT_NUMBER )

Where port_number is the name of the port the listener runs on. This number must be the same as
the number used when defining your sender channel.
i) Start the listener by entering the following command:

START LISTENER (LISTENER1)

Note: Do not start the listener in the background from any shell that automatically lowers the
priority of background processes.
j) Define a receiver channel by entering the following command:

DEFINE CHANNEL (QMA.QMB) CHLTYPE (RCVR) TRPTYPE (TCP)

A message tells you when the channel has been created.

k) End MQSC by typing:

end

Some messages are displayed, followed by the command prompt.

2. On the sender server:
a) As the sender server is an AIX system, log in as a user in the mqm group.
b) Set up the environment for the installation you are using by entering the following command at the
command prompt:

. MQ_INSTALLATION_PATH/bin/setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

c) Create a queue manager called QMA by entering the following command at the command prompt:

crtmqm QMA

Messages tell you that the queue manager has been created, and that the default IBM MQ objects
have been created.
d) Start the queue manager, by entering the following command:

strmqm QMA

A message tells you when the queue manager has started.

e) Start MQSC by entering the following command:

runmqsc QMA

Installing and migrating 53

 A message tells you that an MQSC session has started. MQSC had no command prompt.
f) Define a local queue called QMB (to be used as a transmission queue) by entering the following
command:

DEFINE QLOCAL (QMB) USAGE (XMITQ)

A message tells you when the queue has been created.

g) Define a local definition of the remote queue with by entering the following command:
DEFINE QREMOTE (LOCAL.DEF.OF.REMOTE.QUEUE) RNAME (RECEIVER.Q) RQMNAME ('QMB') XMITQ (QMB)

h) Define a sender channel by entering one of the following commands:

con-name is the TCP/IP address of the receiver system. If both installations are on the same
system, the con-name is localhost. port is the port you noted in 1 b. If you do not specify a port,
the default value of 1414 is used.
DEFINE CHANNEL (QMA.QMB) CHLTYPE (SDR) CONNAME ('CON-NAME(PORT)') XMITQ (QMB) TRPTYPE (TCP)

i) Start the sender channel by entering the following command:

START CHANNEL(QMA.QMB)

The receiver channel on the receiver server starts automatically when the sender channel starts.
j) Stop MQSC by entering the following command:

end

Some messages are displayed, followed by the command prompt.

k) If the sender server is a Linux or AIX system, change into the MQ_INSTALLATION_PATH/
samp/bin directory. This directory contains the sample programs. MQ_INSTALLATION_PATH
represents the high-level directory in which IBM MQ is installed.
l) If both the sender server and receiver server are installations on the same system, check that the
queue managers have been created on different installations by entering the following command:

dspmq -o installation

If the queue managers are on the same installation, move either QMA to the sender installation
or QMB to the receiver installation by using the setmqm command. For more information, see
setmqm.
m) Put a message on the local definition of the remote queue, which in turn specifies the name of the
remote queue. Enter one of the following commands:
• On AIX and Linux:

./amqsput LOCAL.DEF.OF.REMOTE.QUEUE QMA

• On Windows:

amqsput LOCAL.DEF.OF.REMOTE.QUEUE QMA

A message tells you that amqsput has started.

n) Type some message text on one or more lines, followed by a blank line.
A message tells you that amqsput has ended. Your message is now on the queue and the
command prompt is displayed again.
3. On the receiver server:
a) As your receiver server is an AIX system, change into the MQ_INSTALLATION_PATH/samp/bin
directory.

54 Installing and migrating IBM MQ

 This directory contains the sample programs. MQ_INSTALLATION_PATH represents the high-level
directory in which IBM MQ is installed.
b) Get the message from the queue on the receiver by entering the following command:

./amqsget RECEIVER.Q QMB

The sample program starts, and your message is displayed. After a pause, the sample ends. Then
the command prompt is displayed.

Results
You have now successfully verified the server-to-server installation.

Verifying a client installation using the command line on AIX

You can verify a client installation using the command line. On the server you create a queue manager,
a local queue, a listener, and a server-connection channel. You must also apply security rules to allow
the client to connect and make use of the queue defined. On the client you create a client-connection
channel, and then use the sample PUT and GET programs to complete the verification procedure.

About this task

The verification procedure shows how to create a queue manager called queue.manager.1, a local
queue called QUEUE1, and a server-connection channel called CHANNEL1 on the server.
It shows how to create the client-connection channel on the IBM MQ MQI client workstation. It then
shows how to use the sample programs to put a message onto a queue, and get the message from the
queue.
The example does not address any client security issues. See Setting up IBM MQ MQI client security for
details if you are concerned with IBM MQ MQI client security issues.
The verification procedure assumes that:
• The full IBM MQ server product has been installed on a server.
• The server installation is accessible on your network.
• The IBM MQ MQI client software has been installed on a client system.
• The IBM MQ sample programs have been installed.
• TCP/IP has been configured on the server and client systems. For more information, see Configuring
connections between the server and client.

Procedure
1. Set up the server using the command line, using the instructions in “Setting up the server using the
command line on AIX” on page 55.
2. Set up the client, using the instructions in “Connecting to a queue manager, using the MQSERVER
environment variable on AIX” on page 57.
3. Test the communications between client and server, using the instructions in “Testing communication
between a client and a server on AIX” on page 58.

Setting up the server using the command line on AIX

Follow these instructions to create a queue manager, queue, and channel on the server. You can then use
these objects to verify the installation.

About this task

These instructions assume that no queue manager or other IBM MQ objects have been defined.

Installing and migrating 55

 IBM MQ object definitions are case-sensitive. Any text entered as an MQSC command in lowercase is
converted automatically to uppercase unless you enclose it in single quotation marks. Make sure that you
type the examples exactly as shown.

Procedure
1. Create a user ID on the server that is not in the mqm group.
This user ID must exist on the server and client. This is the user ID that the sample applications must
be run as, otherwise a 2035 error is returned.
2. Log in as a user in the mqm group.
3. You must set various environment variables so that the installation can be used in the current shell.
You can set the environment variables by entering the following command:

. MQ_INSTALLATION_PATH/bin/setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

4. Create a queue manager called QUEUE.MANAGER.1 by entering the following command:

crtmqm QUEUE.MANAGER.1

You see messages telling you that the queue manager has been created.
5. Start the queue manager by entering the following command:

strmqm QUEUE.MANAGER.1

A message tells you when the queue manager has started.

6. Start MQSC by entering the following command:

runmqsc QUEUE.MANAGER.1

A message tells you that an MQSC session has started. MQSC has no command prompt.
7. Define a local queue called QUEUE1 by entering the following command:

DEFINE QLOCAL(QUEUE1)

A message tells you when the queue has been created.

8. Allow the user ID that you created in step 1 to use QUEUE1 by entering the following command:

SET AUTHREC PROFILE(QUEUE1) OBJTYPE(QUEUE) PRINCIPAL(' non_mqm_user ') AUTHADD(PUT,GET)

where non_mqm_user is the user ID created in step 1. A message tells you when the authorization
has been set. You must also run the following command to give the user ID authority to connect:

SET AUTHREC OBJTYPE(QMGR) PRINCIPAL(' non_mqm_user ') AUTHADD(CONNECT)

If this command is not run, a 2305 stop error is returned.

9. Define a server-connection channel by entering the following command:

DEFINE CHANNEL (CHANNEL1) CHLTYPE (SVRCONN) TRPTYPE (TCP)

A message tells you when the channel has been created.

10. Allow your client channel to connect to the queue manager and run under the user ID that you
created in step 1, by entering the following MQSC command:

SET CHLAUTH(CHANNEL1) TYPE(ADDRESSMAP) ADDRESS(' client_ipaddr ') MCAUSER(' non_mqm_user ')

where client_ipaddr is the IP address of the client system, and non_mqm_user is the user ID created
in step 1. A message tells you when the rule has been set.
11. Define a listener by entering the following command:

56 Installing and migrating IBM MQ

 DEFINE LISTENER (LISTENER1) TRPTYPE (TCP) CONTROL (QMGR) PORT (port_number)

where port_number is the number of the port the listener is to run on. This number must be the same
as the number used when defining your client-connection channel in “Installing an IBM MQ client on
AIX” on page 47.
Note: If you omit the port parameter from the command, a default value of 1414 is used for the
listener port. If you want to specify a port other than 1414, you must include the port parameter in
the command, as shown.
12. Start the listener by entering the following command:

START LISTENER (LISTENER1)

13. Stop MQSC by entering:

end

You see some messages, followed by the command prompt.

What to do next
Follow the instructions to set up the client. See “Connecting to a queue manager, using the MQSERVER
environment variable on AIX” on page 57.

Connecting to a queue manager, using the MQSERVER environment variable on AIX

When an IBM MQ application is run on the IBM MQ MQI client, it requires the name of the MQI channel,
the communication type, and the address of the server to be used. Provide these parameters by defining
the MQSERVER environment variable.

Before you begin

Before you start this task, you must complete the task, “Setting up the server using the command line on
AIX” on page 55, and save the following information:
• The host name or IP address of the server and port number that you specified when creating the
listener.
• The channel name of the server-connection channel.

About this task

This task describes how to connect an IBM MQ MQI client, by defining the MQSERVER environment
variable on the client.
You can give the client access to the generated client channel definition table, amqclchl.tab instead;
see Accessing client-connection channel definitions.

Procedure
1. Log in as the userid that you created in Step 1 of “Verifying a client installation using the command line
on AIX” on page 55.
2. Check the TCP/IP connection. From the client, enter one of the following commands:
• ping server-hostname
• ping n.n.n.n
n.n.n.n represents the network address. You can set the network address in IPv4 dotted decimal
form, for example, 192.0.2.0. Alternatively, set the address in IPv6 hexadecimal form, for
example 2001:0DB8:0204:acff:fe97:2c34:fde0:3485.
If the ping command fails, correct your TCP/IP configuration.
3. Set the MQSERVER environment variable. From the client, enter the following command:

Installing and migrating 57

 export MQSERVER=CHANNEL1/TCP/'server-address (port)'

Where:
• CHANNEL1 is the server-connection channel name.
• server-address is the TCP/IP host name of the server.
• port is the TCP/IP port number the server is listening on.
If you do not give a port number, IBM MQ uses the one specified in the qm.ini file, or the client
configuration file. If no value is specified in these files, IBM MQ uses the port number identified in the
TCP/IP services file for the service name MQSeries. If an MQSeries entry in the services file does not
exist, a default value of 1414 is used. It is important that the port number used by the client and the
port number used by the server listener program are the same.

What to do next
Use the sample programs to test communication between the client and server; see “Testing
communication between a client and a server on AIX” on page 58.

Testing communication between a client and a server on AIX

On the IBM MQ MQI client workstation, use the amqsputc sample program to put a message on the
queue at the server workstation. Use the amqsgetc sample program to get the message from the queue
back to the client.

Before you begin

Complete the previous topics in this section:
• Set up a queue manager, channels, and queue.
• Open a command window.
• Set system environment variables.

About this task

Note that IBM MQ object definitions are case-sensitive. Text entered as an MQSC command in lowercase
is converted automatically to uppercase unless you enclose it in single quotation marks. Make sure that
you type the examples exactly as shown.

Procedure
1. Change to the MQ_INSTALLATION_PATH/samp/bin directory, which contains the sample
programs.
MQ_INSTALLATION_PATH represents the high-level directory in which IBM MQ is installed.
2. You must set certain environment variables so that the installation can be used in the current shell.
You can set the environment variables by entering the following command:

. MQ_INSTALLATION_PATH/bin/setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

3. Start the PUT program for QUEUE1 on QUEUE.MANAGER.1 by entering the following command:

./amqsputc QUEUE1 QUEUE.MANAGER.1

If the command is successful, the following messages are displayed:

Sample AMQSPUT0 start target queue is QUEUE1

Tip: You might get the error, MQRC_NOT_AUTHORIZED (2035). By default, channel authentication
is enabled when a queue manager is created. Channel authentication prevents privileged users
accessing a queue manager as an IBM MQ MQI client. For verifying the installation, you can either

58 Installing and migrating IBM MQ

 change the MCA user ID to a non-privileged user, or disable channel authentication. To disable channel
authentication run the following MQSC command:

ALTER QMGR CHLAUTH(DISABLED)

When you finish the test, if you do not delete the queue manager, re-enable channel authentication:

ALTER QMGR CHLAUTH(ENABLED)

4. Type some message text, then press Enter twice.

The following message is displayed:
Sample AMQSPUT0 end
Your message is now on the queue that is on the server queue manager.
5. Start the GET program for QUEUE1 on QUEUE.MANAGER.1 by entering the following command:

./amqsgetc QUEUE1 QUEUE.MANAGER.1

The sample program starts, and your message is displayed. After a short pause (approximately 30
seconds), the sample ends and the command prompt is displayed again.

Results
You have now successfully verified the client installation.

What to do next
1. You must set various environment variables on the server so that the installation can be used in the
current shell. You can set the environment variables by entering the following command:

. MQ_INSTALLATION_PATH/bin/setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

2. On the server, stop the queue manager by entering the following command:

endmqm QUEUE.MANAGER.1

3. On the server, delete the queue manager by entering the following command:

dltmqm QUEUE.MANAGER.1

Uninstalling or modifying IBM MQ on AIX

On AIX, you can uninstall the IBM MQ server or client using the System Management Interface Tool
(SMIT) or the installp command. You can also modify an installation by uninstalling a subset of the file
sets.

Before you begin

If any updates have been applied, remove them before starting the uninstallation or modification
procedure. For more information, see “Reverting to the previous maintenance level on AIX” on page
283.
Important: You must stop all IBM MQ queue managers, other objects, and applications, before you begin
the process to uninstall or modify IBM MQ.

Procedure
1. Stop all IBM MQ applications associated with the installation you are uninstalling or modifying, if you
have not already done so.

Installing and migrating 59

 2. For a server installation, end any IBM MQ activity associated with the installation you are uninstalling
or modifying:
a) Log in as a user in the group mqm.
b) Set up your environment to work with the installation you want to uninstall or modify. Enter the
following command:

. MQ_INSTALLATION_PATH/bin/setmqenv

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

c) Display the state of all queue managers on the system. Enter the following command:

dspmq -o installation

d) Stop all running queue managers associated with the installation you want to uninstall or modify.
Enter the following command for each queue manager:

endmqm QMgrName

e) Stop any listeners associated with the queue managers. Enter the following command for each
queue manager:

endmqlsr -m QMgrName

3. Log in as root.
4. Uninstall or modify IBM MQ using either installp or smit. If IBM MQ was installed in a non-default
location, you must use installp.
• To uninstall or modify IBM MQ by using installp, enter one of the following commands:
– To uninstall an installation in the default location /usr/mqm:

installp -u mqm

– To uninstall an installation in a non-default location:

installp -R usil -u mqm

where usil is the path of the User Specified Installation Location (USIL) specified when the
product was installed.
– To modify an installation in a non-default location:

installp -R usil -u list of file sets

where usil is the path of the User Specified Installation Location (USIL) specified when the
product was installed.
• To uninstall or modify IBM MQ by using smit, complete the following steps:
a. Select the required smit window using the following sequence:

Software Installation and Maintenance

Software Maintenance and Utilities
Remove Installed Software

b. List the software in the SOFTWARE name field:

i) Enter .
ii) Press F4
c. Select the file sets to uninstall from the list (those beginning with mqm):
– For a complete uninstall, select all file sets.
– To modify the installation, select a subset of the file sets.

60 Installing and migrating IBM MQ

 After selecting the file sets, press Enter. There is an option at this stage to do a preview. Leave
the option set to the default value of Yes to preview the file sets you are uninstalling, or select
No to not preview these file sets.
d. Press Enter on the Remove Installed Software panel, it asks whether you are sure, press Enter.

Results
After uninstallation, certain files under the directory trees /var/mqm and /etc/opt/mqm are not
removed. These files contain user data and remain so subsequent installations can reuse the data.
Most of the remaining files contain text, such as INI files, error logs, and FDC files. The directory
tree /var/mqm/shared contains files that are shared across installations, including the executable
shared libraries libmqzsd.a and libmqzsd_r.a.

What to do next
• If the product successfully uninstalled, you can delete any files and directories contained in
the /usr/mqm directory under the User Specified Installation Location (USIL) specified in the
installp uninstallation command.
• Use the lslpp command to check for other products installed in the USIL. If there are no other
products installed in the USIL and you do not intend to use it again, you can delete the USIL using the
rmusil command.
• If there are no other IBM MQ installations on the system, and you are not planning to reinstall
or migrate, you can delete the /var/mqm and /etc/opt/mqm directory trees, including the files
libmqzsd.a and libmqzsd_r.a. Deleting these directories destroys all queue managers and their
associated data.
• You can optionally remove installations, once IBM MQ is uninstalled, from the Installation configuration
file, mqinst.ini using the commands listed.
Note: If you are not going to install another version of IBM MQ, you can delete the existing installations
using the dltmqinst command. Otherwise, if you install IBM MQ to the same location, the old
installation name is applied.

Installing and uninstalling IBM MQ on IBM i

Installation tasks that are associated with installing IBM MQ on IBM i systems are grouped in this section.

About this task

To prepare for installation and to install the IBM MQ components, complete the following tasks.
For information about how to uninstall IBM MQ, see “Uninstalling IBM MQ for IBM i” on page 88.
If product fixes or updates are made available, see “Applying maintenance to IBM MQ” on page 278.

Procedure
1. Check the system requirements.
See “Hardware and software requirements on IBM i systems” on page 62.
2. Plan your installation.
• As part of the planning process, you must choose which components to install and where to install
them. See “IBM MQ components for IBM i” on page 62.
• You must also make some platform-specific choices. See “Planning to install IBM MQ on IBM i” on
page 63.
3. Prepare your system for installation of IBM MQ.
See “Preparing the system on IBM i” on page 64.
4. Install IBM MQ server.

Installing and migrating 61

 See “Installing IBM MQ server on IBM i” on page 65.
5. Optional: Install an IBM MQ client.
See “Installing an IBM MQ client on IBM i” on page 78.
6. Verify your installation. See “Verifying an IBM MQ installation on IBM i” on page 83.

IBM MQ components for IBM i

The IBM MQ components that are available for IBM i.
Important: For details of what each purchase of IBM MQ entitles you to install, see IBM MQ license
information.
The components are as follows:
Server (Base)
Support to enable you to create and support your own applications. This includes the runtime
component that provides support for external applications. It also includes support for client
connections from IBM MQ installations on other computers.
Samples (Option 1)
Sample application programs. The source is supplied in the QMQMSAMP library and executable files
are supplied in the QMQM library.
AMS (Option 2)
The AMS component.
IBM MQ Console and REST API (Option 3)
Adds HTTP based administration for IBM MQ through the REST API and IBM MQ Console.
To use this feature, you must install the following prerequisites:
• 5724L26 IBM MQ Java Messaging and Web Services
• 5770JV1 Java SE 8
Managed File Transfer (MFT) components
*BASE
Support to enable you to create and support your own MFT applications. It also includes support
for client connections from IBM MQ MFT installations on other computers.
2
Tools support
3
Agent
4
Services
You must install *BASE first because the other three options depend on *BASE. Note that option 4
requires that option 3 is installed.
Related concepts
“IBM MQ components and features” on page 6
You can select the components or features that you require when you install IBM MQ.

Hardware and software requirements on IBM i systems

Check that the server environment meets the prerequisites for installing IBM MQ for IBM i.
Before installation, you must check that your system meets the hardware and software requirements set
out in the IBM MQ system requirements page. See System Requirements for IBM MQ.

62 Installing and migrating IBM MQ

Storage requirements for IBM MQ server
The storage requirements for IBM i depend on which components you install, and how much working
space you need. The storage requirements also depend on the number of queues that you use, the
number and size of the messages on the queues, and whether the messages are persistent. You also
require archiving capacity on disk, tape, or other media. For more information, see System Requirements
for IBM MQ.
Disk storage is also required:
• Prerequisite software
• Optional software
• Your application programs

Installing prerequisite software

To install the prerequisite software that is provided in the IBM MQ server installation image, choose one of
the following options:
• Navigate to the root of the server installation image, then double-click setup.exe. The IBM MQ
Installation Launchpad window is displayed. From this window, click the Software Prerequisites
option. Use this option to check what prerequisite software is already installed, then install any missing
software.
• Navigate to the Prereqs folder of the server installation image. Select the folder for the software item
to be installed, then start the installation program.

Prerequisite PTFs for multiple certificate support

You are not limited to a single certificate for TLS channels. To use multiple certificates on IBM i platforms,
you must install the following program temporary fixes (PTFs):
MF57749
MF57889
SI52214
MF58003
See Digital certificate labels: understanding the requirements for details about how to select certificates
by using certificate labels.
Related concepts
“License requirements” on page 8
You must have purchased sufficient licenses for your installation. The details of the license agreement
is stored on your system at installation time so that you can read it at any time. IBM MQ supports IBM
License Metric Tool (ILMT).
“Where to find product requirements and support information” on page 9
Before you install IBM MQ, you must check for the latest information and system requirements.

Planning to install IBM MQ on IBM i

Before you install IBM MQ on IBM i, you must choose which components to install and where to install
them. You must also make some platform-specific choices.

About this task

The following steps provide links to additional information to help you with planning your installation of
IBM MQ on IBM i.

Installing and migrating 63

 Procedure
1. As part of your planning activities, make sure that you review the information on hardware and
software requirements for the platform on which you are planning to install IBM MQ.
For more information, see “Hardware and software requirements on IBM i systems” on page 62.
2. Decide which IBM MQ components and features to install.
See “IBM MQ components and features” on page 6 and “Where to find downloadable installation
images” on page 9.
Important: Ensure that your enterprise has the correct license, or licenses, for the components that
you are going to install. For more information, see “License requirements” on page 8 and IBM MQ
license information.

Preparing the system on IBM i

On IBM i systems, you might have to complete several tasks before you install IBM MQ. You might also
want to complete other tasks, depending on your installation intentions.

About this task

The tasks that you perform to prepare your systems for installation are listed here. Complete the
appropriate tasks for your platform before installing.

Procedure
Configure any additional settings needed for your IBM i system.
See “Configuring and tuning the operating system on IBM i” on page 64.

What to do next
When you have completed the tasks to prepare the system, you are ready to start installing IBM MQ. To
install a server, see “Installing IBM MQ server on IBM i” on page 65. To install a client, see “Installing an
IBM MQ client on IBM i” on page 78.
Related tasks
Planning
“Maintaining and migrating IBM MQ” on page 275
Maintenance, upgrade, and migration have three distinct meanings for IBM MQ. The definitions are
described here. The following sections describe the various concepts associated with migration, followed
by the various tasks needed; these tasks are platform-specific where needed.
“Applying maintenance to IBM MQ” on page 278
Maintenance is the application of a reversible fix. Any changes to queue manager data are compatible
with the previous code level.

Configuring and tuning the operating system on IBM i

Before installing IBM MQ for IBM i, there are several system values which need to be checked using the
DSPSYSVAL command. If necessary, reset the values using the CHGSYSVAL command.
Check the following values and change if required:
QCCSID
Every message has a coded-character set identifier (CCSID) in its header. The CCSID tag identifies the
code page and character set of the source.
A queue manager obtains its CCSID from the job that created it. If the job CCSID is not a valid value
in the range 1-65534, the queue manager uses the default CCSID value (65535) instead. You can
change the CCSID used by the IBM MQ queue manager by using the CL command CHGMQM.
Note: The CCSID must be either single-byte character set (SBCS), or mixed, that is SBCS and DBCS. It
must not be DBCS only.

64 Installing and migrating IBM MQ

QSYSLIBL
Ensure that QSYS2 is included in the list of libraries that make up the system part of the library list.
IBM MQ uses programs in this library for data conversion and SNA LU 6.2 communication.
Note: Do not have QMQM as part of the system or user portion of the library list.
QALWOBJRST
Ensure that the QALWOBJRST system value is set to *ALL or *ALWPGMADP before you install MQ. If it
is set to *NONE, installation fails.
After installation, reset QALWOBJRST to its original value to maintain system security.
QSHRMEMCTL
Ensure that the QSHRMEMCTL system value is set to 1 (Allowed).
A value of 1 is used in environments where pointers can be shared amongst programs between
different jobs.
IBM MQ requires this setting to use the shared memory APIs shmat and shmget and to share its
pointers across jobs.
If it is not set correctly, initialization of IBM MQ fails with system return code "3401" (Permission
denied), and commands such as CRTMQM, STRMQM, ENDMQM, TRCMQM fail.
QFRCCVNRST
Ensure that the QFRCCVNRST system value is set to 0 (Restore all objects without conversion), or 1
(Objects with validation errors are converted), before you install MQ. If it is not set, installation fails.
QMLTTHDACN
Optionally set this to control the generation of messages into joblogs. Set QMLTTHDACN to 2 to
get messages generated in a joblog; set it to 1 to avoid the messages. For example, the message
CPD000D is an informational message that is generated when a command that is not thread-safe is
issued from a multi-threaded application. Setting QMLTTHDACN to 1 avoids the message.
Related concepts
“Hardware and software requirements on IBM i systems” on page 62
Check that the server environment meets the prerequisites for installing IBM MQ for IBM i.
“License requirements” on page 8
You must have purchased sufficient licenses for your installation. The details of the license agreement
is stored on your system at installation time so that you can read it at any time. IBM MQ supports IBM
License Metric Tool (ILMT).
Related tasks
“Installing IBM MQ server on IBM i” on page 65
You install IBM MQ for IBM i by installing the IBM MQ server in its primary language, installing samples
and installing additional languages.

Installing IBM MQ server on IBM i

You install IBM MQ for IBM i by installing the IBM MQ server in its primary language, installing samples
and installing additional languages.

Before you begin

Note: Installing the latest version of the IBM MQ server includes client capabilities. Only install the
stand-alone client if you do not need the server capabilities.
You have completed planning the installation, downloaded the installation eImage, and set the system
values. See “Configuring and tuning the operating system on IBM i” on page 64.
For a complete list of IBM MQ installable services and components for IBM i systems, see Installable
services and components for IBM i

Installing and migrating 65

 About this task
How to install the base IBM MQ server in its primary language, install samples, and install translated
versions from a choice of national-languages.
You can install only one instance of IBM MQ for IBM i in each partition of your server.

Procedure
1. Sign on to the system with a user profile that has *ALLOBJ special authority, for example QSECOFR.
2. Install the IBM MQ for IBM i base product, and primary language.

RSTLICPGM LICPGM (5724H72) DEV (installation device) OPTION (*BASE) OUTPUT (*PRINT)

where the parameters of RSTLICPGM are,

LICPGM(5724H72)
The product identifier for IBM i.
DEV(installation device)
The device from which the product is to be loaded, typically an optical drive, for example, OPT01.
OPTION (*BASE)
Install the IBM MQ for IBM i base product.
Unspecified parameters
Unspecified parameters, such as RSTOBJ (*ALL), revert to defaults. The command installs both
IBM MQ and the language files for the primary language of your system. For installing additional
languages, see step 4.
3. Optional: Install the samples using the command:

RSTLICPGM LICPGM (5724H72) DEV (installation device) OPTION (1) OUTPUT (*PRINT)

Where the parameters of RSTLICPGM are,

LICPGM (5724H72)
The product identifier for IBM i.
DEV (installation device)
The device from which the product is to be loaded, typically an optical drive, for example, OPT01.
OPTION (1)
Install the samples for IBM i.
OUTPUT (*PRINT)
The output is printed with the spooled output of the job.
4. Optional: Install the AMS component by using the following command:

RSTLICPGM LICPGM (5724H72) DEV (installation device) OPTION (2) OUTPUT (*PRINT)

Where the parameters of RSTLICPGM are,

LICPGM (5724H72)
The product identifier for IBM i.
DEV (installation device)
The device from which the product is to be loaded, typically an optical drive, for example, OPT01.
OPTION (2)
Install AMS for IBM i.
OUTPUT (*PRINT)
The output is printed with the spooled output of the job.
5. Optional: Install the WEB component by using the following command:

66 Installing and migrating IBM MQ

 RSTLICPGM LICPGM (5724H72) DEV (installation device) OPTION (3) OUTPUT (*PRINT)

Where the parameters of RSTLICPGM are,

LICPGM (5724H72)
The product identifier for IBM i.
DEV (installation device)
The device from which the product is to be loaded, typically an optical drive, for example, OPT01.
OPTION (3)
Install the WEB component for IBM i.
OUTPUT (*PRINT)
The output is printed with the spooled output of the job.
Note: To use this feature, you must install the following prerequisites:
• 5724L26 IBM MQ Java Messaging and Web Services
• 5770JV1 Java SE 8
6. Optional: To install additional languages, sign on to the system with a user profile that has *ALLOBJ
special authority. Choose a language code from the table.

Table 8. Globalizations of IBM MQ for IBM i.

Language ID Language
2909 Belgian English
2966 Belgian French MNCS (Multi-National Character Set)
2980 Brazilian Portuguese
2981 Canadian French MNCS
2975 Czech
2924 English uppercase and lowercase
2984 English US DBCS
2938 English US uppercase DBCS
2928 French
2940 French MNCS
2929 German
2939 German MNCS
2976 Hungarian
2932 Italian
2942 Italian MNCS
2962 Japanese
2930 Japanese Universal
2986 Korean
2978 Polish
2979 Russian
2989 Simplified Chinese
2931 Spanish

Installing and migrating 67

 • If installing Japanese language feature code 2962, ensure the CCSID of the job installing the
product is set to 939 and not 930. Do this to avoid problems with invariant lowercase characters
in CCSID 930

CHGJOB CCSID(939)

• If the language feature code is not in the table then the product has not been translated into your
language. You must choose one of the available language feature codes and install that version
instead. You must manually change the system library list to use IBM MQ in that language load.

CHGSYSLIBL LIB(QSYS2924)

See also How a language of your choice is displayed for licensed programs in How a language is
displayed for IBM i functions in the IBM i product documentation.
• If you are using Korean DBCS and you configure your terminal emulators to 24*80 sessions you
might find that EDTF incorrectly displays DBCS characters in MQ error log messages that extend
beyond 80 columns. To avoid this, configure your terminal emulators to use sessions capable of
displaying 132 columns, for example 27*132.
• Issue the following command specifying the appropriate language ID:

RSTLICPGM LICPGM(5724H72) DEV( installation device ) RSTOBJ(*LNG) LNG( language ID )

This installs the commands, message file, and panel groups into the relevant QSYS library for the
language. For example, library QSYS2928 is used for French. If this QSYS29nn library does not
exist, it is created by the RSTLICPGM command.
7. To ensure that the product has loaded correctly, issue the Display Software Resources (DSPSFWRSC)
command and check that the licensed program 5724H72 is listed. If you have installed the base and
the optional samples, you see:

Resource
ID Option Feature Description
5724H72 *BASE 5050 IBM MQ for IBM i
5724H72 *BASE 2924 IBM MQ for IBM i
5724H72 1 5050 IBM MQ for IBM i - Samples

8. Press F11, while viewing the Display Software Resources screen, and you see the library and version
number of the products installed:

Resource Feature
ID Option Feature Type Library Release
5724H72 *BASE 5050 *CODE QMQM V9R4M0
5724H72 *BASE 2924 *LNG QMQM V9R4M0
5724H72 1 5050 *CODE QMQMSAMP V9R4M0

9. If you have installed additional language versions, you also see entries for these versions. For
example, if you have installed the French version, for which the language ID is 2928, you see:
a)
Resource
ID Option Feature Description
5724H72 *BASE 2928 IBM MQ for IBM i

b) and when you press F11:

Resource Feature
ID Option Feature Type Library Release
5724H72 *BASE 2928 *LNG QSYS2928 V9R4M0

10. Use the command DSPMQMVER to check exactly what version you have installed. For V9R4M0, it
reports:

68 Installing and migrating IBM MQ

 Version: 9.3.0.0

11. Do the post installation tasks of checking for updates, checking program authorities and starting the
IBM MQ subsystem, see “Performing post installation tasks for IBM MQ on IBM i” on page 76.

What to do next
If you want to see how the installation went in more detail, perform one or more of the following tasks:
• View the log file using the DSPJOBLOG command.
• View the spoolfile generated from the RSTLICPGM command.
If the installation of IBM MQ fails, see “Handling installation failures for IBM i” on page 77.
Related concepts
“Uninstalling IBM MQ for IBM i” on page 88
There are two ways of uninstalling IBM MQ for IBM i.

Installing IBM MQ server silently on IBM i

You can perform a non-interactive installation of IBM MQ using the CALL PGM(QSYS/QLPACAGR)
command. A non-interactive installation is also known as a silent, or unattended installation.

Before you begin

Before you start the installation procedure, make sure that you have completed the necessary steps
outlined in “Preparing the system on IBM i” on page 64.

About this task

This topic describes the non-interactive installation of a server.

Procedure
1. Pre-agree the license terms and conditions for the base by running the command,

CALL PGM ( QSYS/QLPACAGR) PARM ('5724H72' 'V9R2M0' '0000' 0)

Where the parameters of PARM are,

5724H72
The product identifier for IBM i.
V9R4M0
The version, release, and modification level.
0000
The option number for the IBM MQ product.
0
Unused error structure.
2. Optionally pre-agree the license terms and conditions for the samples by running the command,

CALL PGM (QSYS/QLPACAGR) PARM ('5724H72' 'V9R2M0' '0001' 0)

Where the parameters of PARM are,

5724H72
The product identifier for IBM i.
V9R4M0
The version, release, and modification level.

Installing and migrating 69

 0001
The option number for the IBM MQ product.
0
Unused error structure.
3. Install the IBM MQ for IBM i base product, and primary language.

RSTLICPGM LICPGM (5724H72) DEV (installation device) OPTION (*BASE) OUTPUT (*PRINT)

where the parameters of RSTLICPGM are,

LICPGM(5724H72)
The product identifier for IBM i.
DEV(installation device)
The device from which the product is to be loaded, typically an optical drive, for example, OPT01.
OPTION (*BASE)
Install the IBM MQ for IBM i base product.
Unspecified parameters
Unspecified parameters, such as RSTOBJ (*ALL), revert to defaults. The command installs both
IBM MQ and the language files for the primary language of your system. For installing additional
languages, see step 4.
4. Optional: Install the samples using the command:

RSTLICPGM LICPGM (5724H72) DEV (installation device) OPTION (1) OUTPUT (*PRINT)

Where the parameters of RSTLICPGM are,

LICPGM (5724H72)
The product identifier for IBM i.
DEV (installation device)
The device from which the product is to be loaded, typically an optical drive, for example, OPT01.
OPTION (1)
Install the samples for IBM i.
OUTPUT (*PRINT)
The output is printed with the spooled output of the job.
5. Optional: To install additional languages, sign on to the system with a user profile that has *ALLOBJ
special authority. Choose a language code from the table.

Table 9. Globalizations of IBM MQ for IBM i.

Language ID Language
2909 Belgian English
2966 Belgian French MNCS (Multi-National Character Set)
2980 Brazilian Portuguese
2981 Canadian French MNCS
2975 Czech
2924 English uppercase and lowercase
2984 English US DBCS
2938 English US uppercase DBCS
2928 French
2940 French MNCS

70 Installing and migrating IBM MQ

 Table 9. Globalizations of IBM MQ for IBM i. (continued)
Language ID Language
2929 German
2939 German MNCS
2976 Hungarian
2932 Italian
2942 Italian MNCS
2962 Japanese
2930 Japanese Universal
2986 Korean
2978 Polish
2979 Russian
2989 Simplified Chinese
2931 Spanish

• If installing Japanese language feature code 2962, ensure the CCSID of the job installing the
product is set to 939 and not 930. Do this to avoid problems with invariant lowercase characters
in CCSID 930

CHGJOB CCSID(939)

• If the language feature code is not in the table then the product has not been translated into your
language. You must choose one of the available language feature codes and install that version
instead. You must manually change the system library list to use IBM MQ in that language load.

CHGSYSLIBL LIB(QSYS2924)

See also How a language of your choice is displayed for licensed programs in How a language is
displayed for IBM i functions in the IBM i product documentation.
• If you are using Korean DBCS and you configure your terminal emulators to 24*80 sessions you
might find that EDTF incorrectly displays DBCS characters in MQ error log messages that extend
beyond 80 columns. To avoid this, configure your terminal emulators to use sessions capable of
displaying 132 columns, for example 27*132.
• Issue the following command specifying the appropriate language ID:

RSTLICPGM LICPGM(5724H72) DEV( installation device ) RSTOBJ(*LNG) LNG( language ID )

This installs the commands, message file, and panel groups into the relevant QSYS library for the
language. For example, library QSYS2928 is used for French. If this QSYS29nn library does not
exist, it is created by the RSTLICPGM command.
6. To ensure that the product has loaded correctly, issue the Display Software Resources (DSPSFWRSC)
command and check that the licensed program 5724H72 is listed. If you have installed the base and
the optional samples, you see:

Installing and migrating 71

 Resource
ID Option Feature Description
5724H72 *BASE 5050 IBM MQ for IBM i
5724H72 *BASE 2924 IBM MQ for IBM i
5724H72 1 5050 IBM MQ for IBM i - Samples

7. Press F11, while viewing the Display Software Resources screen, and you see the library and version
number of the products installed:

Resource Feature
ID Option Feature Type Library Release
5724H72 *BASE 5050 *CODE QMQM V9R4M0
5724H72 *BASE 2924 *LNG QMQM V9R4M0
5724H72 1 5050 *CODE QMQMSAMP V9R4M0

8. If you have installed additional language versions, you also see entries for these versions. For
example, if you have installed the French version, for which the language ID is 2928, you see:
a)
Resource
ID Option Feature Description
5724H72 *BASE 2928 IBM MQ for IBM i

b) and when you press F11:

Resource Feature
ID Option Feature Type Library Release
5724H72 *BASE 2928 *LNG QSYS2928 V9R4M0

9. Use the command DSPMQMVER to check exactly what version you have installed. For V9R4M0, it
reports:

Version: 9.3.0.0

10. Do the post installation tasks of checking for updates, checking program authorities and starting the
IBM MQ subsystem, see “Performing post installation tasks for IBM MQ on IBM i” on page 76.

What to do next
If you want to see how the installation went in more detail, perform one or more of the following tasks:
• View the log file using the DSPJOBLOG command.
• View the spoolfile generated from the RSTLICPGM command.
If the installation of IBM MQ fails, see “Handling installation failures for IBM i” on page 77.

Installing Managed File Transfer on IBM i

Install IBM MQ Managed File Transfer for IBM i by installing IBM MQ Java Messaging and Web Services
server in its primary language, and installing additional options.

Before you begin

Note: Installing the latest version of IBM MQ Managed File Transfer includes client capabilities.
You have completed planning the installation, downloaded the installation image, and set the system
values. See “Configuring and tuning the operating system on IBM i” on page 64.
You have installed the following components:

Table 10. Software requirements for IBM MQ Managed File Transfer

Program Option Description
5761JV1 14 or 15 Java SE 7 32 bit or Java SE 7 64 bit

72 Installing and migrating IBM MQ

Table 10. Software requirements for IBM MQ Managed File Transfer (continued)
Program Option Description
5770SS1 39 International Components for Unicode
5724L26 *BASE IBM MQ Java Messaging and Web Services

About this task

How to install base Managed File Transfer in its primary language, and install the other options.
You can install only one instance of Managed File Transfer for IBM i in each partition of your server.

Procedure
1. Sign on to the system with a user profile that has *ALLOBJ special authority, for example QSECOFR.
2. Install Managed File Transfer for IBM i, base product.

RSTLICPGM LICPGM (5725M50) DEV (installation device) OPTION (*BASE) OUTPUT (*PRINT)

where the parameters of RSTLICPGM are,

LICPGM (5725M50)
The product identifier for Managed File Transfer for IBM i.
DEV (installation device)
The device from which the product is to be loaded, typically an optical drive, for example, OPT01.
OPTION (*BASE)
Install Managed File Transfer for IBM i for the IBM MQ base product.
Unspecified parameters
Unspecified parameters such as RSTOBJ (*ALL), revert to defaults. The command installs both
IBM MQ and the language files for the primary language of your system.
3. Optional: Install the tools using the command:

RSTLICPGM LICPGM(5725M50) DEV(installation device) OPTION(2) OUTPUT(*PRINT)

Where the parameters of RSTLICPGM are,

LICPGM (5725M50)
The product identifier for Managed File Transfer for IBM i.
DEV (installation device)
The device from which the product is to be loaded, typically an optical drive, for example, OPT01.
OPTION (2)
Install the tools for Managed File Transfer for IBM i.
OUTPUT (*PRINT)
The output is printed with the spooled output of the job.
Repeat step “3” on page 73 for options 3 (agent) and 4 (services)
4. To ensure that the product has loaded correctly, issue the Display Software Resources (DSPSFWRSC)
command and check that the licensed program 5725M50 is listed. If you have installed the base and
the optional tools, you see:

Resource
ID Option Feature Description
5725M50 *BASE 5050 Managed File Transfer for IBM i
5725M50 *BASE 2924 Managed File Transfer for IBM i
5725M50 2 5050 Managed File Transfer for IBM i - Tools

Installing and migrating 73

 5. Press F11, while viewing the Display Software Resources screen, and you see the library and version
number of the products installed:

Resource
ID Option Feature Type Library Release
5725M50 *BASE 5050 *CODE QMQMMFT V9R4M0
5725M50 *BASE 2924 *LNG QMQMMFT V9R4M0
5725M50 2 5050 *CODE MFTTOOL V9R4M0

6. Do the post installation tasks of checking for updates, checking program authorities, and starting the
Managed File Transfer subsystem.

What to do next
If you want to see how the installation went in more detail, perform one or more of the following tasks:
• View the log file using the DSPJOBLOG command.
• View the spoolfile generated from the RSTLICPGM command.
If the installation of IBM MQ fails, see “Handling installation failures for IBM i” on page 77.

Installing IBM MQ for IBM i from a downloaded installation image

You can perform an installation of IBM MQ for IBM i from an installation image downloaded from IBM.

Before you begin

Before you start the installation procedure, make sure that you have completed the necessary steps
outlined in “Preparing the system on IBM i” on page 64.

About this task

Two installation images are provided as zip files, a client and server image. These images contain all the
licensed programs, and a client only image for the clients only.
The client and server image contains all seven compressed IBM i save files ( SAVF ), while the client
image contains four save files. The save files are:
• MQ92BASE - IBM MQ client and server base program objects
• MQ92SAMP - IBM MQ client & server samples
• MQ92EN24 - IBM MQ client and server English US (2924) language objects
plus the client only images:
• MQ92CBASE - IBM MQ client
• MQ92CSAMP - IBM MQ client samples
• MQ92JBASE - IBM MQ Java
• MQ92JSAMP - IBM MQ Java samples

Procedure
1. Download one of the installation images and extract it to a temporary directory.
2. On IBM i, create a library containing sufficient empty save files to hold the uploaded files by using the
commands:

74 Installing and migrating IBM MQ

 CRTLIB LIB(MQ92PROD)
CRTSAVF FILE(MQ92PROD/MQ92BASE) /* Server and Client */
CRTSAVF FILE(MQ92PROD/MQ92SAMP) /* Server and Client Samples */
CRTSAVF FILE(MQ92PROD/MQ92EN24) /* 2924 English */
CRTSAVF FILE(MQ92PROD/MQ92CBASE) /* Standalone Client */
CRTSAVF FILE(MQ92PROD/MQ92CSAMP) /* Standalone Client Samples */
CRTSAVF FILE(MQ92PROD/MQ92JBASE) /* Java and JMS Classes */
CRTSAVF FILE(MQ92PROD/MQ92JSAMP) /* Java and JMS Samples */

For additional languages

CRTSAVF FILE(MQ92PROD/MQ92EN09) /* 2929 Belgian English */

CRTSAVF FILE(MQ92PROD/MQ92FR28) /* 2928 French */
CRTSAVF FILE(MQ92PROD/MQ92JA30) /* 2930 Japanese */
CRTSAVF FILE(MQ92PROD/MQ92ES31) /* 2931 Spanish */
CRTSAVF FILE(MQ92PROD/MQ92IT32) /* 2932 Italian */
CRTSAVF FILE(MQ92PROD/MQ92EN38) /* 2938 English DBCS UPPERCASE */
CRTSAVF FILE(MQ92PROD/MQ92FR40) /* 2940 French MNCS */
CRTSAVF FILE(MQ92PROD/MQ92IT42) /* 2942 Italian MNCS */
CRTSAVF FILE(MQ92PROD/MQ92FR66) /* 2966 French MNCS */
CRTSAVF FILE(MQ92PROD/MQ92FR81) /* 2981 French MNCS */
CRTSAVF FILE(MQ92PROD/MQ92EN84) /* 2984 English DBCS */
CRTSAVF FILE(MQ92PROD/MQ92CZ75) /* 2975 Czech */
CRTSAVF FILE(MQ92PROD/MQ92HU76) /* 2976 Hungarian */
CRTSAVF FILE(MQ92PROD/MQ92PL78) /* 2978 Polish */
CRTSAVF FILE(MQ92PROD/MQ92RU79) /* 2979 Russian */
CRTSAVF FILE(MQ92PROD/MQ92PT80) /* 2980 Portugese/Brazilian */
CRTSAVF FILE(MQ92PROD/MQ92JA62) /* 2962 Japanese */
CRTSAVF FILE(MQ92PROD/MQ92KO86) /* 2986 Korean */
CRTSAVF FILE(MQ92PROD/MQ92ZH89) /* 2989 Chinese */
CRTSAVF FILE(MQ92PROD/MQ92DE29) /* 2929 German */
CRTSAVF FILE(MQ92PROD/MQ92DE39) /* 2939 German */

3. Start an ftp session to your IBM i machine and upload the required save files with the commands:

ftp (your_ibmi_hostname)
bin
put MQ92BASE MQ92PROD/MQ92BASE
put MQ92SAMP MQ92PROD/MQ92SAMP
put MQ92EN24 MQ92PROD/MQ92EN24
put MQ92CBASE MQ92PROD/MQ92CBASE
put MQ92CSAMP MQ92PROD/MQ92CSAMP
put MQ92JBASE MQ92PROD/MQ92JBASE
put MQ92JSAMP MQ92PROD/MQ92JSAMP

For additional language loads:

put MQ92EN09 MQ92PROD/MQ92EN09

put MQ92FR28 MQ92PROD/MQ92FR28
put MQ92JA30 MQ92PROD/MQ92JA30
put MQ92ES31 MQ92PROD/MQ92ES31
put MQ92IT32 MQ92PROD/MQ92IT32
put MQ92EN38 MQ92PROD/MQ92EN38
put MQ92FR40 MQ92PROD/MQ92FR40
put MQ92IT42 MQ92PROD/MQ92IT42
put MQ92FR66 MQ92PROD/MQ92FR66
put MQ92FR81 MQ92PROD/MQ92FR81
put MQ92EN84 MQ92PROD/MQ92EN84
put MQ92CZ75 MQ92PROD/MQ92CZ75
put MQ92HU76 MQ92PROD/MQ92HU76
put MQ92PL78 MQ92PROD/MQ92PL78
put MQ92RU79 MQ92PROD/MQ92RU79
put MQ92PT80 MQ92PROD/MQ92PT80
put MQ92JA62 MQ92PROD/MQ92JA62
put MQ92KO86 MQ92PROD/MQ92KO86
put MQ92ZH89 MQ92PROD/MQ92ZH89
put MQ92DE29 MQ92PROD/MQ92DE29
put MQ92DE39 MQ92PROD/MQ92DE39

4. To prepare for installation of IBM MQ for IBM i, sign on to your IBM i machine and ensure that you have
followed the instructions detailed in “Preparing the system on IBM i” on page 64.
5. Enter the RSTLICPGM commands, specifying the installation device as *SAVF and naming the save file
containing the options that you want to install.

Installing and migrating 75

 The IBM MQ Java licensed program can be installed stand-alone or can coexist with any of the other
licensed programs.
The IBM MQ client can be installed standalone, but it can only coexist with the IBM MQ Java on the
same system.
Attempting to install the IBM MQ server on a system where the IBM MQ client is already installed
performs a slip installation upgrade, replacing the client with the server licensed program.
Attempting to install the IBM MQ client stand-alone over the top of an existing server licensed program
is not possible, and the installation fails.
For example:

/* IBM MQ Client and Server program objects */

RSTLICPGM LICPGM(5724H72) DEV(*SAVF) SAVF(MQ92PROD/MQ92BASE) +
RSTOBJ(*PGM) OPTION(*BASE) OUTPUT(*PRINT)

/* IBM MQ Client & Server English 2924 Language Load */

RSTLICPGM LICPGM(5724H72) DEV(*SAVF) SAVF(MQ92PROD/MQ92EN24) +
RSTOBJ(*LNG) LNG(2924) OUTPUT(*PRINT)

/* Additional languages - alter SAVF and LNG parameters... */

/* IBM MQ Client & Server Japanese 2930 Language Load */
RSTLICPGM LICPGM(5724H72) DEV(*SAVF) SAVF(MQ92PROD/MQ92JA30) +
RSTOBJ(*LNG) LNG(2930) OUTPUT(*PRINT)

/* IBM MQ Client & Server Samples */

RSTLICPGM LICPGM(5724H72) DEV(*SAVF) SAVF(MQ92PROD/MQ92SAMP) +
OPTION(1) OUTPUT(*PRINT)

/* IBM MQ Java */
RSTLICPGM LICPGM(5724L26) DEV(*SAVF) SAVF(MQ92PROD/MQ92JBASE) +
OPTION(*BASE) OUTPUT(*PRINT)

/* IBM MQ Java Samples */

RSTLICPGM LICPGM(5724L26) DEV(*SAVF) SAVF(MQ92PROD/MQ92JSAMP) +
OPTION(1) OUTPUT(*PRINT)

/* IBM MQ Client */
RSTLICPGM LICPGM(5725A49) DEV(*SAVF) SAVF(MQ92PROD/MQ92CBASE) +
OPTION(*BASE) OUTPUT(*PRINT)

/* IBM MQ Client Samples */

RSTLICPGM LICPGM(5725A49) DEV(*SAVF) SAVF(MQ92PROD/MQ92CSAMP) +
OPTION(1) OUTPUT(*PRINT)

6. Do the post installation tasks of checking for updates, checking program authorities and starting the
IBM MQ subsystem, see “Performing post installation tasks for IBM MQ on IBM i” on page 76.

What to do next
If you want to see how the installation went in more detail, perform one or more of the following tasks:
• View the log file using the DSPJOBLOG command.
• View the spoolfile generated from the RSTLICPGM command.
If the installation of IBM MQ fails, see “Handling installation failures for IBM i” on page 77.

Performing post installation tasks for IBM MQ on IBM i

Tasks to perform after you have installed IBM MQ for IBM i, and before using it.

About this task

When you have correctly installed IBM MQ for IBM i on your system:

Procedure
1. See the IBM MQ website at IBM MQ product page for the latest product information.
2. Install and apply all fix packs.

76 Installing and migrating IBM MQ

3. Where you have more than one system and a mixture of releases of OS/400 or IBM i, and IBM MQ, you
must take care when compiling CL programs. You must compile CL programs either on the system they
are to run on, or on one with an identical combination of releases of OS/400 or IBM i, and IBM MQ.
When you install later versions of IBM MQ, delete all IBM MQ commands from previous releases in any
QSYSVvRrMm libraries using the QSYS/DLTCMD command.
4. If you have not installed IBM MQ on your system before, you must add user profiles to the QMQMADM
group profile. Make all user profiles that are to be used for creating and administering queue managers
members of the QMQMADM group profile, using the command CHGUSRPRF.
a) Start the IBM MQ subsystem, by issuing the command:

STRSBS SBSD(QMQM/QMQM)

Note: The subsystem must be started after each IPL of the system, so you might choose to start it
as part of your system startup process.

5. Create the system-default objects. The system-default objects are created automatically
when you issue the CRTMQM command to create a queue manager. For example: CRTMQM
MQMNAME(QMGRNAME) ASP(*SYSTEM). You can refresh them using the STRMQM command
(Warning: this command will replace any existing default objects). For example: STRMQM
MQMNAME(QMGRNAME) RDEFSYS(*YES). Refer to the onscreen help for information about using this
command.
Note: on the command STRMQM MQMNAME(QMGRNAME) RDEFSYS(*YES):
• The command does not re-create the objects, it performs a CRTxxxx REPLACE(*YES) for all of the
SYSTEM.* objects.
• This means that it refreshes the parameters on the objects back to their defaults. So if, for example,
on the SYSTEM.DEFAULT.LOCAL.QUEUE object, TRGENBL had previously been changed to *YES,
then, when the command is run, it is changed back to TRGENBL(*NO).
• If any messages exist on a queue, they are not removed, because the queues are not physically
deleted.
• The contents of the SYSTEM.AUTH.DATA.QUEUE are untouched when this command is run.
• So, if the contents of this (or any other significant queue) become corrupt, it must be physically
deleted and re-created either from scratch, or from a backup.

Results
You are now ready to start using IBM MQ for IBM i.
Note: When you install IBM MQ for IBM i, two user profiles are created:
• QMQM
• QMQMADM
These two objects are central to the correct running of IBM MQ for IBM i. Do not alter or delete them. If
you do, IBM cannot guarantee correct behavior of your product.
If you uninstall IBM MQ and data, these profiles are deleted. If you uninstall IBM MQ only, these profiles
are retained.

Handling installation failures for IBM i

If the installation of IBM MQ Server or Client for IBM i fails, you must remove the installed and partially
installed objects before attempting reinstallation.

Procedure
1. Delete installed options using DLTLICPGM LICPGM(5725A49)OPTION(*ALL).

Installing and migrating 77

 2. Delete partially installed options by deleting the QMQM library (and the QMQMSAMP libraries if
necessary).
3. Delete the IFS directory /QIBM/ProdData/mqm and its subdirectories using the EDTF command, for
example: EDTF STMF('/QIBM/ProdData') and select option 9 for the mqm directory.
If the installation of IBM MQ Java fails, remove the partly installed objects before attempting
reinstallation:
a. Delete the QMQMJAVA library.
b. Delete the IFS directory /QIBM/ProdData/mqm/java and its subdirectories using the EDTF
command, for example:

EDTF STMF ('/QIBM/ProdData/mqm')

Select option 9 against the Java directory.

Converting a trial license on IBM i

Convert a trial license to a full license without reinstalling IBM MQ.
When the trial license expires, the "count-down" displayed by the strmqm command informs you the
license has expired, and the command does not run.

Before you begin

1. IBM MQ is installed with a trial license.
2. You have access to the installation media of a fully licensed copy of IBM MQ.

About this task

Run the setmqprd command to convert a trial license to a full license.
If you do not want to apply a full license to your trial copy of IBM MQ, you can uninstall it at any time.

Procedure
1. Obtain the full license from the fully licensed installation media.
The full license file is amqpcert.lic.
2. Run the setmqprd command from the installation that you are upgrading:

CALL PGM(QMQM/SETMQPRD) PARM('LICENSE_PATH/amqpcert.lic')

where LICENSE_PATH is the path to the amqpcert.lic file that you obtained.
Related reference
setmqprd

Installing an IBM MQ client on IBM i

The IBM MQ client for IBM i is a part of the IBM MQ product.

Before you begin

Attention: If you have already installed the IBM MQ server, you already have a client and must not
attempt to install the stand-alone client.
You can install only one instance of IBM MQ client for IBM i in each partition of your server.
When you install IBM MQ client for IBM i two user profiles are created:

78 Installing and migrating IBM MQ

• QMQM
• QMQMADM
These two objects are central to the correct running of IBM MQ for IBM i. Do not alter or delete them.
If you do, IBM cannot guarantee correct behavior of your product. These profiles are retained when the
product is deleted.

About this task

This procedure covers the installation of both the client and the client samples. If you do not want to
install the client samples, then do not complete the steps specific to the samples.
After following the optional step to pre-agree the license, and then issuing the RSTLICPGM command, the
installation runs without requiring any interactive input.

Procedure
1. Sign on to the system with a user profile that has *ALLOBJ special authority, for example QSECOFR.
2. Optional: Pre-agree the license terms and conditions. If you do not choose to pre-agree the license,
the license agreement is displayed for you to accept. Run the following commands to pre-agree the
license terms and conditions:
a) For the client:

CALL PGM (QSYS/QLPACAGR) PARM ('5725A49' 'V9R2M0' '0000' 0)

The parameters of PARM are:

5725A49
The product identifier for IBM MQ client for IBM i
V9R4M0
The version, release, and modification level
0000
The option number for the base IBM MQ client for IBM i product
0
Unused error structure
b) For the client samples:

CALL PGM (QSYS/QLPACAGR) PARM ('5725A49' 'V9R2M0' '0001' 0)

The parameters of PARM are:

5725A49
The product identifier for IBM MQ client for IBM i
V9R4M0
The version, release, and modification level
0001
The option number for the samples
0
Unused error structure
3. Issue the installation command to run the installation without requiring any interactive input:
a) Install the client by issuing the following command:

RSTLICPGM LICPGM (5725A49) DEV (installation device) OPTION (*BASE) OUTPUT (*PRINT)

The parameters of RSTLICPGM are:

Installing and migrating 79

 LICPGM (5725A49)
The product identifier for IBM MQ client for IBM i
DEV (installation device)
The device from which the product is to be loaded, typically an optical drive, for example,
OPT01
OPTION (*BASE)
The level of IBM MQ client for IBM i product installed
OUTPUT (*PRINT)
Whether the spooled output of the job is printed
b) Install the samples by issuing the following command:

RSTLICPGM LICPGM (5725A49) DEV (installation device) OPTION (1) OUTPUT (*PRINT)

The parameters of RSTLICPGM are:

LICPGM (5725A49)
The product identifier for IBM MQ client for IBM i
DEV (installation device)
The device from which the product is to be loaded, typically an optical drive, for example,
OPT01
OPTION (1)
The samples option
OUTPUT (*PRINT)
Whether the spooled output of the job is printed
4. To ensure that the product has loaded correctly, issue the Display Software Resources ( DSPSFWRSC )
command and check that the licensed program 5725A49 is listed. If you have installed the base and
the optional samples, you see:

Resource
ID Option Feature Description
5725A49 *BASE 5050 IBM MQ client for IBM i
5725A49 1 5050 IBM MQ client for IBM i -Samples

5. To see the library and version number of the products installed, press F11, while viewing the Display
Software Resources screen. The following screen is displayed:

Resource Feature
ID Option Feature Type Library Release
5725A49 *BASE 5050 *CODE QMQM V9R4M0
5725A49 1 5050 *CODE QMQMSAMP V9R4M0

6. To check exactly what version you have installed, use the DSPMQMVER program.
For example, /QSYS.LIB/QMQM.LIB/DSPMQVER.PGM -a in a qshell.

What to do next
If you want to see how the installation went in more detail, perform one or more of the following tasks:
• View the log file using the DSPJOBLOG command.
• View the spoolfile generated from the RSTLICPGM command.
If the installation of IBM MQ client for IBM i failed, see “Handling installation failures for IBM i” on page
77
Related concepts
“Uninstalling IBM MQ for IBM i” on page 88

80 Installing and migrating IBM MQ

There are two ways of uninstalling IBM MQ for IBM i.

Installation of IBM MQ client and IBM MQ server for IBM i

When you install an IBM MQ server on an IBM i system, the client is also automatically installed.
The installed version of the IBM MQ client for IBM i can be refreshed by using a "slip installation" which
replaces an existing installation with a fresh image.
Installing a client over an existing client results in a successful installation.
Installing a client over an existing server results in a failure with a CPDB6A4 error.
Installing a server over an existing client results in a successful upgrade of the client to both server and
client capabilities.

Installing IBM MQ Java messaging and web services for IBM i

Install IBM MQ Java messaging and web services for IBM i, using the RSTLICPGM command.

Before you begin

From IBM MQ 9.3.0, Jakarta Messaging 3.0 is supported for developing new applications.
IBM MQ 9.3.0 and later continue to support JMS 2.0 for existing applications. It is not supported to use
both the Jakarta Messaging 3.0 API and the JMS 2.0 API in the same application. For more information,
see Using IBM MQ classes for JMS/Jakarta Messaging.
You can install only one instance of IBM MQ Client for IBM i in each partition of your server.
If you have an older version of Java messaging and web services (5724L26) installed and want to install a
newer version, you can install the new version without uninstalling the older one.
If you have MA88 installed (5648C60), and try to install anyway, the installation fails with a warning
requesting you to uninstall the old client. To uninstall MA88, issue the following command:

DLTLICPGM LICPGM(5648C60) OPTION(*ALL)

If this command fails to delete the IFS directory /QIBM/ProdData/mqm/java and its subdirectories,
use the EDTF command and select option 9 against the Java directory. For example:

EDTF STMF('/QIBM/ProdData/mqm')

About this task

This procedure covers the installation of both the Java messaging and web services, and the Java
messaging and web services samples. If you do not want to install the samples, then do not complete the
steps specific to the samples.
After following the optional step to pre-agree the license, and then issuing the RSTLICPGM command, the
installation runs without requiring any interactive input.

Procedure
1. Sign on to the system with a user profile that has *ALLOBJ special authority, for example QSECOFR.
2. Optional: Pre-agree the license terms and conditions. If you do not choose to pre-agree the license,
the license agreement is displayed for you to accept. Run the following commands to pre-agree the
license terms and conditions:
a) For Java messaging and web services:

CALL PGM (QSYS/QLPACAGR) PARM ('5724L26' 'V9R2M0' '0000' 0)

Installing and migrating 81

 The parameters of PARM are:
5724L26
The product identifier for IBM MQ Java messaging and web services for IBM i
V9R4M0
The version, release, and modification level
0000
The option number for the base IBM MQ Java messaging and web services product.
0
Unused error structure
b) For the samples:

CALL PGM (QSYS/QLPACAGR) PARM ('5724L26' 'V9R2M0' '0001' 0)

The parameters of PARM are:

5724L26
The product identifier for IBM MQ Java messaging and web services for IBM i
V9R4M0
The version, release, and modification level
0001
The option number for the samples.
0
Unused error structure
3. Issue the installation command to run the installation without requiring any interactive input:
a) Install the IBM MQ Java messaging and web services by issuing the following command:

RSTLICPGM LICPGM (5724L26) DEV (installation device) OPTION (*BASE) OUTPUT (*PRINT)

The parameters of RSTLICPGM are:

LICPGM (5724L26)
The product identifier for IBM MQ Java messaging and web services for IBM i
DEV (installation device)
The device from which the product is to be loaded, typically an optical drive, for example,
OPT01
OPTION (*BASE)
Install the base IBM MQ Java messaging and web services for IBM i
OUTPUT (*PRINT)
Whether the spooled output of the job is printed
b) Install the samples by issuing the following command:

RSTLICPGM LICPGM (5724L26) DEV (installation device) OPTION (1) OUTPUT (*PRINT)

The parameters of RSTLICPGM are:

LICPGM (5724L26)
The product identifier for IBM MQ Java messaging and web services for IBM i
DEV (installation device)
The device from which the product is to be loaded, typically an optical drive, for example,
OPT01
OPTION (1)
Install the samples

82 Installing and migrating IBM MQ

 OUTPUT (*PRINT)
Whether the spooled output of the job is printed
4. To ensure that the product has loaded correctly, issue the Display Software Resources (DSPSFWRSC)
command and check that the licensed program 5724L26 is listed. If you have installed the base and
the optional samples, you see:

Resource
ID Option Feature Description
5724L26 *BASE 5050 IBM MQ Java Messaging and Web Services
5724L26 1 5050 IBM MQ Java Messaging and Web Services - Samp

5. Press F11 while viewing the Display Software Resources screen, and you see the library and version
number of the products installed:

Resource Feature
ID Option Feature Type Library Release
5724L26 *BASE 5050 *CODE QMQMJAVA V9R4M0
5724L26 1 5050 *CODE QMQMJAVA V9R4M0

6. Check what versions you have installed by using the following commands:
IBM MQ Classes for Java:

java com.ibm.mq.MQJavaLevel

Note: For this command to work, you might have to set your environment classpath to:
• /QIBM/ProdData/mqm/java/lib/com.ibm.mq.jar
IBM MQ Classes for Java Message Service:

java com.ibm.mq.jms.MQJMSLevel

Note: For this command to work, you might need to set your environment classpath to:
• /QIBM/ProdData/mqm/java/lib/com.ibm.mq.jakarta.client.jar (Jakarta Messaging
3.0) or /QIBM/ProdData/mqm/java/lib/com.ibm.mq.allclient.jar (JMS 2.0)
See Environment variables relevant to IBM MQ classes for Java and Environment variables used by
IBM MQ classes for JMS.
For IBM MQ for IBM i 9.2, both report:

Version: 9.2.0.0

Note: The command uses the Java classes, and so it reports the version and also performs some
verification that the classes are installed and working.
7. See the following topics for full details of verification of both:
• Using IBM MQ classes for Java
• Using IBM MQ classes for JMS

Verifying an IBM MQ installation on IBM i

The topics in this section provide instructions on how to verify a client installation of IBM MQ on IBM i
systems.

Verifying a client installation using the command line on IBM i

You can verify a client installation using the command line. On the server you create a queue manager,
a local queue, a listener, and a server-connection channel. You must also apply security rules to allow

Installing and migrating 83

 the client to connect and make use of the queue defined. On the client you create a client-connection
channel, and then use the sample PUT and GET programs to complete the verification procedure.
The verification procedure shows how to create a queue manager called queue.manager.1, a local
queue called QUEUE1, and a server-connection channel called CHANNEL1 on the server.
It shows how to create the client-connection channel on the IBM MQ MQI client workstation. It then
shows how to use the sample programs to put a message onto a queue, and get the message from the
queue.
The example does not address any client security issues. See Setting up IBM MQ MQI client security for
details if you are concerned with IBM MQ MQI client security issues.
The verification procedure assumes that:
• The full IBM MQ server product has been installed on a server.
• The server installation is accessible on your network.
• The IBM MQ MQI client software has been installed on a client system.
• The IBM MQ sample programs have been installed.
• TCP/IP has been configured on the server and client systems. For more information, see Configuring
connections between the server and client.
First, set up the server using the command line, using the instructions in “Setting up the server using the
command line IBM i” on page 84.
Once you have set up the server, you must set up the client, using the instructions in “Connecting to a
queue manager, using the MQSERVER environment variable on IBM i” on page 86.
Finally, you can test the communications between client and server, using the instructions in “Testing
communication between a client and a server on IBM i” on page 87.

Setting up the server using the command line IBM i

Follow these instructions to create a queue manager, queue, and channel on the server. You can then use
these objects to verify the installation.

About this task

These instructions assume that no queue manager or other IBM MQ objects have been defined.
IBM MQ object definitions are case-sensitive. Any text entered as an MQSC command in lowercase is
converted automatically to uppercase unless you enclose it in single quotation marks. Make sure that you
type the examples exactly as shown.

Procedure
1. Create a user ID on the server that is not in the mqm group.
This user ID must exist on the server and client. This is the user ID that the sample applications must
be run as, otherwise a 2035 error is returned.
2. Log in as a user in the MQM group.
3. Create a queue manager called QUEUE.MANAGER.1 by entering the following command:

crtmqm QUEUE.MANAGER.1

You see messages telling you that the queue manager has been created.
4. Start the queue manager by entering the following command:

strmqm QUEUE.MANAGER.1

A message tells you when the queue manager has started.

84 Installing and migrating IBM MQ

 5. Define a local queue called QUEUE1 by entering the following command:

CRTMQMQ QNAME(QUEUE1) QTYPE(*LCL)

A message tells you when the queue has been created.

6. Allow the user ID that you created in step 1 to use QUEUE1 by entering the following command:

SET AUTHREC PROFILE(QUEUE1) OBJTYPE(QUEUE) PRINCIPAL(' non_mqm_user ') AUTHADD(PUT,GET)

where non_mqm_user is the user ID created in step 1. A message tells you when the authorization
has been set. You must also run the following command to give the user ID authority to connect:

SET AUTHREC OBJTYPE(QMGR) PRINCIPAL(' non_mqm_user ') AUTHADD(CONNECT)

If this command is not run, a 2305 stop error is returned.

7. Define a server-connection channel by entering the following command:

CRTMQMCHL CHLNAME(CHANNEL1) CHLTYPE(*SVRCN) TRPTYPE(*TCP)

MCAUSRID('QMQM')

A message tells you when the channel has been created.

8. Allow your client channel to connect to the queue manager and run under the user ID that you
created in step 1, by entering the following MQSC command:

SET CHLAUTH(CHANNEL1) TYPE(ADDRESSMAP) ADDRESS(' client_ipaddr ') MCAUSER(' non_mqm_user ')

where client_ipaddr is the IP address of the client system, and non_mqm_user is the user ID created
in step 1. A message tells you when the rule has been set.
9. Define a listener by entering the following command:

DEFINE LISTENER (LISTENER1) TRPTYPE (TCP) CONTROL (QMGR) PORT (port_number)

where port_number is the number of the port the listener is to run on. This number must be the same
as the number used when defining your client-connection channel in “Installing an IBM MQ client on
IBM i” on page 78.
Note: If you omit the port parameter from the command, a default value of 1414 is used for the
listener port. If you want to specify a port other than 1414, you must include the port parameter in
the command, as shown.
10. Start the listener by entering the following command:

STRMQMLSR MQMNAME('QUEUE.MANAGER.1') PORT(1414)

11. Stop MQSC by entering:

end

You see some messages, followed by the command prompt.

What to do next
Follow the instructions to set up the client. See “Connecting to a queue manager, using the MQSERVER
environment variable on IBM i” on page 86.

Installing and migrating 85

 Connecting to a queue manager, using the MQSERVER environment variable on IBM i
When an IBM MQ application is run on the IBM MQ MQI client, it requires the name of the MQI channel,
the communication type, and the address of the server to be used. Provide these parameters by defining
the MQSERVER environment variable.

Before you begin

Before you start this task, you must complete the task, “Setting up the server using the command line
IBM i” on page 84, and save the following information:
• The host name or IP address of the server and port number that you specified when creating the
listener.
• The channel name of the server-connection channel.

About this task

This task describes how to connect an IBM MQ MQI client, by defining the MQSERVER environment
variable on the client.

Procedure
1. Log in as the userid that you created in Step 1 of “Setting up the server using the command line IBM i”
on page 84.
2. Check the TCP/IP connection. From the client, enter one of the following commands:
• ping server-hostname
• ping n.n.n.n
n.n.n.n represents the network address. You can set the network address in IPv4 dotted decimal
form, for example, 192.0.2.0. Alternatively, set the address in IPv6 hexadecimal form, for
example 2001:0DB8:0204:acff:fe97:2c34:fde0:3485.
If the ping command fails, correct your TCP/IP configuration.
3. Set the MQSERVER environment variable. From the client, enter one the following command:

ADDENVVAR ENVVAR(MQSERVER) VALUE('CHANNEL1/TCP/server-address (port)')

Where:
• CHANNEL1 is the server-connection channel name.
• server-address is the TCP/IP host name of the server.
• port is the TCP/IP port number the server is listening on.
If you do not give a port number, IBM MQ uses the one specified in the qm.ini file, or the client
configuration file. If no value is specified in these files, IBM MQ uses the port number identified in the
TCP/IP services file for the service name MQSeries. If an MQSeries entry in the services file does not
exist, a default value of 1414 is used. It is important that the port number used by the client and the
port number used by the server listener program are the same.

What to do next
Use the sample programs to test communication between the client and server; see “Testing
communication between a client and a server on IBM i” on page 87.

86 Installing and migrating IBM MQ

 Testing communication between a client and a server on IBM i
On the IBM MQ MQI client workstation, use the amqsputc sample program to put a message on the
queue at the server workstation. Use the amqsgetc sample program to get the message from the queue
back to the client.

Before you begin

Complete the previous topics in this section:
• Set up a queue manager, channels, and queue.
• Open a command window.
• Set system environment variables.

About this task

Note that IBM MQ object definitions are case-sensitive. Text entered as an MQSC command in lowercase
is converted automatically to uppercase unless you enclose it in single quotation marks. Make sure that
you type the examples exactly as shown.

Procedure
1. Start the PUT program for QUEUE1 on QUEUE.MANAGER.1 by entering the following command:

CALL PGM(QMQM/AMQSPUTC) PARM(QUEUE1 QUEUE.MANAGER.1)

If the command is successful, the following messages are displayed:

Sample AMQSPUT0 start target queue is QUEUE1

Tip: You might get the error, MQRC_NOT_AUTHORIZED ( 2035 ). By default, channel authentication
is enabled when a queue manager is created. Channel authentication prevents privileged users
accessing a queue manager as an IBM MQ MQI client. For verifying the installation, you can either
change the MCA user ID to a non-privileged user, or disable channel authentication. To disable channel
authentication run the following MQSC command:

ALTER QMGR CHLAUTH(DISABLED)

When you finish the test, if you do not delete the queue manager, re-enable channel authentication:

ALTER QMGR CHLAUTH(ENABLED)

2. Type some message text, then press Enter twice.

The following message is displayed:

Sample AMQSPUT0 end

Your message is now on the queue that is on the server queue manager.
3. Start the GET program for QUEUE1 on QUEUE.MANAGER.1 by entering the following command:

CALL PGM(QMQM/AMQSGETC) PARM(QUEUE1 QUEUE.MANAGER.1)

The sample program starts, and your message is displayed. After a short pause (approximately 30
seconds), the sample ends and the command prompt is displayed again.

Results
You have now successfully verified the client installation.

Installing and migrating 87

 What to do next
1. On the server, stop the queue manager by entering the following command:

ENDMQM MQMNAME(QUEUE.MANAGER.1)

2. On the server, delete the queue manager by entering the following command:

DLTMQM MQMNAME(QUEUE.MANAGER.1)

Uninstalling IBM MQ for IBM i

There are two ways of uninstalling IBM MQ for IBM i.
To uninstall IBM MQ for IBM i, perform one of the following tasks:
• A standard deletion removes IBM MQ product code but preserves user data.
• An entire deletion removes both IBM MQ product code and user data.
Both types of deletion require you to be signed on to the system with a user profile that has *ALLOBJ
special authority, for example, QSECOFR. Security administrator (*SECADM) special authority is also
required to delete the QMQM and QMQMADM user profiles.
Related concepts
“Reinstalling IBM MQ for IBM i” on page 93
You can reinstall IBM MQ for IBM i without losing any of your data.
Related tasks
“Uninstalling IBM MQ but retaining data on IBM i” on page 88
If you want to retain your user data, for example, because you intend to reinstall IBM MQ for IBM i at a
later date, you must perform a standard deletion of the product.
“Uninstalling IBM MQ and data on IBM i” on page 90
You can delete IBM MQ entirely, including all user data.
“Uninstalling IBM MQ Java Messaging and Web Services on IBM i” on page 91
Follow these instructions to uninstall IBM MQ Java.
“Uninstalling IBM MQ MQI client for IBM i” on page 92
If the IBM MQ MQI client for IBM i must be uninstalled, follow the correct procedure to ensure that all the
relevant directories and files are removed.

Uninstalling IBM MQ but retaining data on IBM i

If you want to retain your user data, for example, because you intend to reinstall IBM MQ for IBM i at a
later date, you must perform a standard deletion of the product.

About this task

To perform a standard deletion of IBM MQ for IBM i, so that your user data is retained, complete the
following steps:

Procedure
1. Quiesce IBM MQ for IBM i.
For more information, see Quiescing IBM MQ for IBM i .
2. End the IBM MQ subsystem, by issuing the command:

ENDSBS SBS(QMQM)

3. Ensure that no locks are held on the library QMQM, by issuing the command:

88 Installing and migrating IBM MQ

 WRKOBJLCK OBJ(QMQM) OBJTYPE(*LIB)

4. Use the Delete Licensed Program (DLTLICPGM) command to delete the base product (and also the
samples, AMS, and WEB components if you chose to install them).
To delete only the samples, issue the command:

DLTLICPGM LICPGM( 5724H72 ) OPTION(1)

To delete only the AMS component, issue the command:

DLTLICPGM LICPGM( 5724H72 ) OPTION(2)

To delete only the WEB component, issue the command:

DLTLICPGM LICPGM( 5724H72 ) OPTION(3)

To delete only extra language versions installed, issue the command:

DLTLICPGM LICPGM(5724H72) LNG(nnnn)

where nnnn is the language number, as in the list here:

Table 11. Globalizations of IBM MQ for IBM i.

Language ID Language
2909 Belgian English
2966 Belgian French MNCS (Multi-National Character Set)
2981 Canadian French MNCS
2975 Czech
2950 English uppercase
2924 English uppercase and lowercase
2984 English US DBCS
2938 English US uppercase DBCS
2928 French
2940 French MNCS
2929 German
2939 German MNCS
2976 Hungarian
2932 Italian
2942 Italian MNCS
2962 Japanese
2986 Korean
2978 Polish
2979 Russian

Installing and migrating 89

 Table 11. Globalizations of IBM MQ for IBM i. (continued)
Language ID Language
2989 Simplified Chinese
2931 Spanish

To delete the base product and all other installed components, issue the command:

DLTLICPGM LICPGM( 5724H72 ) OPTION(*ALL)

Results
Deleting IBM MQ for IBM i in this way deletes only the objects that belong to IBM MQ: the QMQM
library, the QMQM samp library, and the subdirectories that belong to IBM MQ server within the /QIBM/
ProdData/mqm directory.
If that leaves no other subdirectories (for example, if IBM MQ Java is installed it uses subdirectories
there) then the /QIBM/ProdData/mqm directory itself is deleted.
None of the queue manager journal libraries, or IFS directories based upon /QIBM/UserData are
removed.

Uninstalling IBM MQ and data on IBM i

You can delete IBM MQ entirely, including all user data.

About this task

Important: If you are going to delete IBM MQ entirely, including all user data, save your user data first. It
cannot be recovered.
To delete IBM MQ for IBM i entirely, complete the following steps:

Procedure
1. Quiesce IBM MQ for IBM i.
For more information, see Quiescing IBM MQ for IBM i .
2. Delete each queue manager in turn by using the command WRKMQM and selecting option 4.
3. End the IBM MQ subsystem, by issuing the command:

ENDSBS SBS(QMQM)

4. Ensure that no locks are held on the library QMQM, by issuing the command:

WRKOBJLCK OBJ(QMQM) OBJTYPE(*LIB)

5. Optional: If you want to also uninstall IBM MQ Java, you can do it now, using the command:

DLTLICPGM LICPGM( 5724L26 ) OPTION(*ALL)

This will also uninstall the Java Samples, if they were installed.
6. Use the Delete Licensed Program (DLTLICPGM) command to delete the base product (and also
the samples if you chose to install them). To delete the base product and the samples issue the
command:

90 Installing and migrating IBM MQ

 DLTLICPGM LICPGM( 5724H72 ) OPTION(*ALL)

7. Delete the directory /QIBM/UserData/mqm and its subdirectories. Do this using the EDTF command
and selecting option 9 (recursive delete) for the mqm directory, as follows,

Note: If you do this, you no longer have any information regarding your installation. Use this
command with extreme caution.
The format of the command is:

EDTF STMF('/QIBM/UserData')

Alternatively, you can delete the /QIBM/UserData/mqm directory and its subdirectories by repeated
use of the RMVLNK and RMVDIR commands.
8. Identify all the users who belong to the QMQMADM group. Use the DSPUSRPRF command to display
a list of them. You must remove the QMQMADM group profile from their user profiles before you can
delete the QMQMADM user profile. The format of the command is:

DSPUSRPRF USRPRF(QMQMADM) TYPE(*GRPMBR)

9. You must alter the ownership or delete the objects. For each of the user profiles QMQM and
QMQMADM, use the WRKOBJOWN command to list all the objects owned by the profile. The format
of the command is:

WRKOBJOWN USRPRF( PROFILE )

10. Delete the two user profiles. The format of the command is:

DLTUSRPRF USRPRF(QMQM) OWNOBJOPT(*DLT)

DLTUSRPRF USRPRF(QMQMADM) OWNOBJOPT(*DLT)

Uninstalling IBM MQ Java Messaging and Web Services on IBM i

Follow these instructions to uninstall IBM MQ Java.

About this task

To uninstall the IBM MQ Java product.

Procedure
1. Make sure you are signed on to the system with a user profile that has *ALLOBJ special authority, for
example QSECOFR.
2. Issue the command:

DLTLICPGM LICPGM(5724L26) OPTION(*ALL)

Results
Deleting IBM MQ Java for IBM i deletes the objects that belong to it: the QMQMJAVA library, and the
subdirectories that belong to IBM MQ Java within the /QIBM/ProdData/mqm directory.
If that leaves no other subdirectories (for example if the IBM MQ Server is installed it uses subdirectories
there) then the /QIBM/ProdData/mqm directory itself is deleted.

Installing and migrating 91

 Uninstalling IBM MQ MQI client for IBM i
If the IBM MQ MQI client for IBM i must be uninstalled, follow the correct procedure to ensure that all the
relevant directories and files are removed.

Procedure
1. Make sure you are signed on to the system with a user profile that has *ALLOBJ special authority, for
example QSECOFR.
2. Use the Delete Licensed Program ( DLTLICPGM ) command to delete the IBM MQ MQI client for IBM i
product (and also the samples if you chose to install them):
To delete only the samples, issue the command

DLTLICPGM LICPGM(5725A49) OPTION(1)

To delete IBM MQ MQI client and the samples, issue the command:

DLTLICPGM LICPGM(5725A49) OPTION(*ALL)

Results
Deleting IBM MQ MQI client for IBM i deletes the objects that belong to it - the QMQM library, and the
subdirectories that belong to IBM MQ MQI client for IBM i within the /QIBM/ProdData/mqm directory.
If that leaves no other subdirectories (for example if the IBM MQ Java Client for IBM i is installed it uses
subdirectories there) then the /QIBM/ProdData/mqm directory itself is deleted.

Uninstalling Managed File Transfer on IBM i

Follow these instructions to uninstall Managed File Transfer on IBM i.

Before you begin

To uninstall IBM MQ Managed File Transfer for IBM i, perform one of the following tasks:
• A standard deletion removes Managed File Transfer product code but preserves user data.
• An entire deletion removes both Managed File Transfer product code and user data.
Note that an entire deletion requires that you manually remove the configuration data in the /QIBM/
UserData/mqm/mqft directory.
Both types of deletion require you to be signed on to the system with a user profile that has *ALLOBJ
special authority, for example, QSECOFR.

About this task

To uninstall the Managed File Transfer product.

Procedure
1. Make sure you are signed on to the system with a user profile that has *ALLOBJ special authority, for
example QSECOFR.
2. Issue the command:

DLTLICPGM LICPGM(5725M50) OPTION(*ALL)

92 Installing and migrating IBM MQ

Results
Deleting Managed File Transfer for IBM i deletes the objects that belong to it: the QMQMMFT library, and
the subdirectories that belong to Managed File Transfer within the /QIBM/ProdData/mqm directory.
Note that licence files are copied to /QIBM/ProdData/mqm/properties/version, and an
uninstallation will delete files in this directory. However, files are left in /QIBM/ProdData/mqm/
properties/5725M50 as trash. For a clean uninstallation, you must delete the files in this directory.

Reinstalling IBM MQ for IBM i

You can reinstall IBM MQ for IBM i without losing any of your data.

When you reinstall IBM MQ for IBM i, the system checks whether the IBM MQ configuration file (mqs.ini)
exists. If the file exists, it is kept and used with the newly installed system. If the file does not exist, an
empty mqs.ini file is placed in the directory /QIBM/UserData/mqm.
All data that you have in the UserData directory is referenced by the newly installed system. In addition,
all the queue manager-associated libraries containing journal and receiver information are referenced by
the new system.
Related tasks
“Installing IBM MQ server on IBM i” on page 65
You install IBM MQ for IBM i by installing the IBM MQ server in its primary language, installing samples
and installing additional languages.

Installing and uninstalling IBM MQ on Linux

Installation tasks that are associated with installing IBM MQ on Linux are grouped in this section.

About this task

To prepare for installation and to install IBM MQ, complete the following tasks.
If product fixes or updates are made available, see “Applying maintenance to IBM MQ” on page 278.

Procedure
• To install IBM MQ on Linux using rpm, see “Installing IBM MQ on Linux using rpm” on page 107.
• To install IBM MQ on Linux Ubuntu using a Debian installer , see “Installing IBM MQ on Linux Ubuntu
using Debian” on page 124.

Checking requirements on Linux

Before you install IBM MQ on Linux, you must check for the latest information and system requirements.

About this task

A summary of the tasks that you must complete to check system requirements are listed here with links
to further information.

Procedure
1. Check that you have the latest information, including information on hardware and software
requirements.
See “Where to find product requirements and support information” on page 9.
2. Check that your systems meet the initial hardware and software requirements for Linux.
See “Hardware and software requirements on Linux systems” on page 94.

Installing and migrating 93

 3. Check that your systems have sufficient disk space for the installation.
See Disk space requirements.
4. Check that you have the correct licenses.
See “License requirements” on page 8 and IBM MQ license information.

What to do next
When you have completed these tasks, you are ready to start preparing your system for installation. For
the next steps in installing IBM MQ, see “Preparing the system on Linux” on page 97.
Related concepts
“IBM MQ installation overview” on page 6
An overview of concepts and considerations for installing IBM MQ, with links to instructions on how to
install, verify, and uninstall IBM MQ on each of the supported platforms.
Related tasks
“Applying maintenance to IBM MQ” on page 278
Maintenance is the application of a reversible fix. Any changes to queue manager data are compatible
with the previous code level.

Hardware and software requirements on Linux systems

Before you install IBM MQ, check that your system meets the hardware and operating system software
requirements for the particular components you intend to install.
For basic hardware and software requirements, see System Requirements for IBM MQ.

Host names
IBM MQ does not support host names that contain spaces. If you install IBM MQ on a system with a host
name that contains spaces, you are unable to create any queue managers.

64-bit Linux distributions might no longer support 32-bit applications by default

Attention: There is no separate 32-bit client installation package. The client installation package
and redistributable client contain both 32-bit and 64-bit IBM MQ client libraries. The included
32-bit libraries can be used by 32-bit applications on supported platforms where 32-bit support is
offered by the operating system.
If the 32-bit Linux support libraries are not installed, 32-bit applications will not run. If you need this
functionality, install the 32-bit support libraries. Here are the names of the packages that contain the
required libraries:
For Red Hat.

Red Hat Enterprise Linux for System x (64 bit):

glibc.i686
libstdc++.i686
Red Hat Enterprise Linux Server for IBM Z:
glibc.s390
libstdc++.s390

For Ubuntu.

Ubuntu Linux for System x (64 bit):

libc6:i386
libstdc++6:i386
Ubuntu Linux for IBM Z:
libc6-s390
lib32stdc++6

For SUSE Linux.

SUSE Linux Enterprise Server for System x (64 bit):

94 Installing and migrating IBM MQ

 glibc-32bit
libstdc++6-32bit
SUSE Linux Enterprise Server for IBM Z:
glibc-32bit
libstdc++6-32bit

Check the System Requirements for IBM MQ to see which Linux distributions are supported on IBM MQ.
For example there is no 32-bit support for SUSE Linux Enterprise Server 15 (all architectures), or for Red
Hat Enterprise Linux Server for IBM Z 8.

Java Message Service

From IBM MQ 9.3.0, Jakarta Messaging 3.0 is supported for developing new applications.
IBM MQ 9.3.0 and later continue to support JMS 2.0 for existing applications. It is not supported to use
both the Jakarta Messaging 3.0 API and the JMS 2.0 API in the same application. For more information,
see Using IBM MQ classes for JMS/Jakarta Messaging.
Java 8 is bundled with IBM MQ 9.0 but client components are built with Java 7 compatibility flags on.
For development, a JDK is required, and a JRE is required for running. The JRE does not need to be the
JRE installed with IBM MQ, but has to be one from the supported list.
For a list of supported JDKs, see System Requirements for IBM MQ.
On Linux: On the Power platform, the 32 bit and 64 bit JDKs are typically installed to different locations,
for example, the 32 bit JDK is located in /opt/IBMJava2-ppc-50 and the 64 bit JDK is located
in /opt/IBMJava2-ppc64-50. Ensure that the PATH variable is correctly set for your applications that
use Java.
You can check the version installed using the following command:

java -version

Transport Layer Security (TLS)

If you want to use the TLS support, you need the IBM Global Security Kit (GSKit) version 8 package. This
package is supplied with IBM MQ as one of the components available for installation.
Installing the g++ version runtime support
If you intend to run TLS channels then you must have the g++ runtime libraries installed. The GNU g++
libraries are called libgcc_s.so and libstdc++.so.6. On RPM based systems these are installed
as part of the libgcc and libstdc++ software packages.
The version of these libraries installed must be compatible with g++ version 3.4.
See System Requirements for IBM MQ for further details on the required packages for TLS support.
On 64 bit platforms, install both the 32 bit and the 64 bit versions of the package so that 32 bit and 64
bit processes can both use TLS functions.

IBM MQ Explorer requirements

On Linux, IBM MQ Explorer can be installed by downloading and installing the stand-alone IBM MQ
Explorer from Fix Central. See IBM MQ Explorer Requirements for the minimum requirements that your
system needs if you want to use IBM MQ Explorer.
Note: IBM MQ Explorer for Linux is available for use only with IBM MQ on x86-64 platforms.

RDQM (replicated data queue manager)

Pacemaker is one of the prerequisites for RDQM. Pacemaker requires that certain Linux packages are
installed on the system. The list for RHEL 8.2 assumes that a minimal set of system packages has been

Installing and migrating 95

 installed that includes the mandatory and default packages from the mandatory groups of the Server
environment group.
The prerequisites for supported levels of RHEL 8 (Pacemaker 2) are:
• cifs-utils
• libtool-ltdl
• libxslt
• net-snmp-libs
• nfs-utils
• perl-TimeDate
• psmisc
• python36
• python3-lxml

The prerequisites for supported levels of RHEL 9 (Pacemaker 2) are:

• libxslt
• net-snmp-libs
• nfs-utils
• nfs-utils-coreos
• perl-TimeDate
• python3-lxml
• python-unversioned-command
These packages in turn have their own requirements (which are not listed here). When Pacemaker is
installed, it reports any missing packages that also need to be installed before installation can complete
successfully.

Requirements for IBM MQ classes for .NET

See Prerequisites for .NET Core on Linux for the dependencies required to run .NET on Linux.

Planning to install IBM MQ on Linux

Before you install IBM MQ on Linux, you must choose which components to install and where to install
them. You must also make some platform-specific choices.

About this task

The following steps provide links to additional information to help you with planning your installation of
IBM MQ on Linux.
As part of your planning activities, make sure that you review the information on hardware and software
requirements for the platform on which you are planning to install IBM MQ. For more information, see
“Checking requirements on Linux” on page 93.

Procedure
1. Decide which IBM MQ components and features to install.
See “IBM MQ components and features” on page 6 and “Where to find downloadable installation
images” on page 9.
Important: Ensure that your enterprise has the correct license, or licenses, for the components that
you are going to install. For more information, see “License requirements” on page 8 and IBM MQ
license information.

96 Installing and migrating IBM MQ

2. Review the options for naming your installation.
In some cases, you can choose an installation name to use instead of the default name. See
“Installation name on AIX, Linux, and Windows” on page 14.
3. Review the options and restrictions for choosing an installation location for IBM MQ.
For more information, see “Installation location on Multiplatforms” on page 15.
4. If you plan to install multiple copies of IBM MQ, see “Multiple installations on AIX, Linux, and
Windows” on page 17.
5. If you already have a primary installation, or plan to have one, see “Primary installation on AIX, Linux,
and Windows” on page 18.
6. Make sure that the communications protocol needed for server-to-server verification is installed and
configured on both systems that you plan to use.
For more information, see “Server-to-server links on AIX, Linux, and Windows” on page 26.
7. Determine whether you need to install the Java runtime environment (JRE).
From IBM MQ 9.1.0, if you are not using Java in your messaging applications, and you are not using
portions of IBM MQ that are written in Java, you have the option to not install the JRE (or to remove the
JRE if it was already installed).

Attention: If you choose not to install the JRE, or to remove the JRE if it was already installed:
• You must use the runmqakm command to manage key repositories. The runmqktool
command is not available.
• Use of the runmqras command fails unless a JRE at version 7, or later, is available on the
system path.
On Linux, you can install IBM MQ without installing the MQSeriesJRE RPM, unless you are installing
the portions of the product that require the presence of the JRE, in which case the RPM prerequisites
test fails. You can also install the MQSeriesGSKit RPM without the JRE.
Upgrading from an earlier version of IBM MQ to IBM MQ 9.1.0 or later adds the separately installed
JRE feature to the installed product.
For more information, see runmqakm and runmqktool commands on AIX, Linux, and Windows.

Preparing the system on Linux

On Linux systems, you might have to complete several tasks before you install IBM MQ. You might also
want to complete other tasks, depending on your installation intentions.

About this task

The tasks that you perform to prepare your systems for installation are listed here. Complete the
appropriate tasks for your platform before installing.

Procedure
1. Set up a user ID of the name mqm, with a primary group of mqm.
See “Setting up the user and group on Linux” on page 98.
Note: If the group mqm and/or user mqm do not exist, during the installation of the product, the installer
creates group mqm and user mqm with a home directory of /var/mqm.
2. Create file systems for both the product code and working data to be stored. See “Creating file systems
on Linux” on page 99.
3. Configure any additional settings needed for your Linux system.
See “Configuring and tuning the operating system on Linux” on page 101.

Installing and migrating 97

 What to do next
When you have completed the tasks to prepare the system, you are ready to start installing IBM MQ. To
install a server using rpm , see “Installing the first IBM MQ installation on Linux using the rpm command”
on page 111. To install a client using rpm, see “Installing an IBM MQ client on Linux using rpm” on page
118.
To install a server using a Debian installer, see “Installing an IBM MQ server on Linux Ubuntu using Debian
packages” on page 128. To install a client using a Debian installer, see “Installing an IBM MQ client on
Linux Ubuntu using Debian packages ” on page 134
Important: Having both Debian and rpm installed versions of IBM MQ on the same system is not
supported.
Related tasks
Planning
“Maintaining and migrating IBM MQ” on page 275
Maintenance, upgrade, and migration have three distinct meanings for IBM MQ. The definitions are
described here. The following sections describe the various concepts associated with migration, followed
by the various tasks needed; these tasks are platform-specific where needed.
“Applying maintenance to IBM MQ” on page 278
Maintenance is the application of a reversible fix. Any changes to queue manager data are compatible
with the previous code level.

Setting up the user and group on Linux

On Linux systems, IBM MQ requires a user ID of the name mqm, with a primary group of mqm. The mqm user
ID owns the directories and files that contain the resources associated with the product.

Using Active Directory

If you are using Active Directory to provide centralized user and group definitions to your Linux system, it
is not possible to have both an mqm user and mqm group definition in Active Directory because that service
does not permit users and groups to have the same name.
You should:
• Put an mqm group definition in the Active Directory before installing IBM MQ, so that other users in the
directory can later be made part of the shared group definition.
• Create the mqm user locally, or allow it to be created during the installation process.

Creating the user ID and group

Set the primary group of the mqm user to the group mqm.
If you are installing IBM MQ on multiple systems you might want to ensure each UID and GID of mqm
has the same value on all systems. If you are planning to configure multi-instance queue managers, it is
essential the UID and GID are the same from system to system. It is also important to have the same UID
and GID values in virtualization scenarios.
RPM creates the mqm user ID and group mqm, with a home directory of /var/mqm, as part of the
installation procedure if they do not exist.
If you have special requirements for these IDs ( for example they need to have the same values as other
machines you are using, or your users and group ID are centrally managed) you should create the IDs
before running the installation procedure, using the groupadd and useradd commands to set the UID
and GID the same on each machine.
Note: The only IBM MQ requirement, is that the mqm user should have the mqm group as its primary group.

98 Installing and migrating IBM MQ

Adding existing user IDs to the group on Linux systems
If you want to run administration commands, for example crtmqm (create queue manager) or strmqm
(start queue manager), your user ID must be a member of the mqm group. This user ID must not be longer
than 12 characters.
Users do not need mqm group authority to run applications that use the queue manager; it is needed only
for the administration commands.

Log files created by MQ Telemetry service

The umask setting of the user ID that creates a queue manager will determine the permissions of the
Telemetry log files generated for that queue manager. Even though the ownership of the log files will be
set to mqm.
Related concepts
“Creating file systems on AIX” on page 39
Before installing IBM MQ, you might need to create file systems for both the product code and working
data to be stored. There are minimum storage requirements for these file systems. The default installation
directory for the product code can be changed at installation time, but the working data location cannot
be changed.
“Configuring and tuning the operating system on Linux” on page 101
Use this topic when you are configuring IBM MQ on Linux systems.
Related tasks
“Configuring and tuning the operating system on AIX” on page 41
When installing IBM MQ on AIX systems, there are some additional settings that must be configured.

Creating file systems on Linux

Before installing IBM MQ, you might need to create file systems for both the product code and working
data to be stored. There are minimum storage requirements for these file systems. The default installation
directory for the product code can be changed at installation time, but the working data location cannot
be changed.

Determining the size of a server installations file system

To determine the size of the /var/mqm file system for a server installation, consider:
• The maximum number of messages in the system at one time.
• Contingency for message buildups, if there is a system problem.
• The average size of the message data, plus 500 bytes for the message header.
• The number of queues.
• The size of log files and error messages.
• The amount of trace that is written to the /var/mqm/trace directory.
Storage requirements for IBM MQ also depend on which components you install, and how much working
space you need. For more details, see Disk space requirements.

Creating a file system for the working data

Before you install IBM MQ, create and mount a file system called /var/mqm which is owned by the user
mqm in the group mqm ; see “Setting up the user and group on Linux” on page 98. This file system is used
by all installations of IBM MQ on a system. If possible, use a partition strategy with a separate volume
for the IBM MQ data. This means that other system activity is not affected if a large amount of IBM
MQ work builds up. Configure the directory permissions to permit the mqm user to have full control, for
example, file mode 755. These permissions will then be updated during the IBM MQ installation to match
the permissions required by the queue manager.

Installing and migrating 99

 Creating separate file systems for errors and logs
You can also create separate file systems for your log data ( /var/mqm/log ) and error files ( /var/mqm/
errors ). If possible, place these directories on different physical disks from the queue manager data
( /var/mqm/qmgrs ) and from each other.
If you create separate file systems the /var/mqm/errors directory can be NFS mounted. However, if
you choose to NFS-mount /var/mqm/errors, the error logs might be lost if the network fails.
You can protect the stability of your queue manager by having separate file systems for:
• /var/mqm/errors
• /var/mqm/trace
• /var/mqm/qmgrs
• /var/mqm/log
In the case of /var/mqm/errors, it is rare that this directory receives large quantities of data. But it
is sometimes seen, particularly if there is a severe system problem leading to IBM MQ writing a lot of
diagnostic information in to .FDC files. In the case of /var/mqm/trace, files are only written here when
you use strmqtrc to start tracing IBM MQ.
You can obtain better performance of normal IBM MQ operations (for example, syncpoints, MQPUT,
MQGET of persistent messages) by placing the following on separate disks:
• /var/mqm/qmgrs
• /var/mqm/log
In the rare event that you need to trace an IBM MQ system for problem determination, you can reduce
performance impact by placing the /var/mqm/trace file system on a separate disk.
If you are creating separate file systems, allow a minimum of 30 MB of storage for /var/mqm, 100 MB
of storage for /var/mqm/log, and 10 MB of storage for /var/mqm/errors. The 100 MB minimum
allowance of storage for /var/mqm/log is the absolute minimum required for a single queue manager
and is not a recommended value. The size of a file system must be scaled according to the number of
queue managers that you intend to use, the number of pages per log file, and the number of log files per
queue manager.
For more information about file systems, see File system support.
The size of the log file depends on the log settings that you use. The minimum sizes are for circular logging
using the default settings. For more information about log sizes, see Calculating the size of the log.
Linux
For a client installation, the file system can be mounted on a remote network device, for example NFS.
If you are performing both a client and a server installation, the requirements of the server installation
take precedence over the requirements of the client installation.
Allow 15 MB as a minimum for an IBM MQ client.
A new sample IBM MQ MQI client configuration file is created in the var/mqm directory, by
the client package, during installation, but only if this file does not exist. This file contains
the ClientExitPath stanza. An example mqclient.ini file is shown in IBM MQ MQI client
configuration file, mqclient.ini.
If you are using a common configuration file for multiple clients, either in the IBM MQ installation
directory or in another location using the MQCLNTCF environment variable, you must grant read
access to all user identifiers under which the IBM MQ client applications run. If, for any reason, the file
cannot be read the failure is traced, and the search logic continues as if the file had not existed.
Related concepts
“Setting up the user and group on Linux” on page 98
On Linux systems, IBM MQ requires a user ID of the name mqm, with a primary group of mqm. The mqm user
ID owns the directories and files that contain the resources associated with the product.
“Configuring and tuning the operating system on Linux” on page 101

100 Installing and migrating IBM MQ

 Use this topic when you are configuring IBM MQ on Linux systems.

Configuring and tuning the operating system on Linux

Use this topic when you are configuring IBM MQ on Linux systems.
Note: The information in this topic principally concerns global kernel tuning parameters, and applies to all
Linux systems. The exception to this statement are the sections described in “Configuring the users who
start IBM MQ” on page 104, which are specific to the user.

Shell interpreter
Ensure that /bin/sh shell is a valid shell interpreter compatible with the Bourne shell, otherwise the
post-installation configuration of IBM MQ does not complete successfully. If the shell was not installed
using RPM, you might see a prerequisites failure of /bin/sh shell when you try to install IBM MQ . The
failure is because the RPM tables do not recognize that a valid shell interpreter is installed. If the failure
occurs, you can reinstall the /bin/sh shell by using RPM, or specify the RPM option --nodeps to disable
dependency checking during installation of IBM MQ .
Note: The --dbpath option is not supported when installing IBM MQ on Linux.

Swap space
During high load IBM MQ can use virtual memory (swap space). If virtual memory becomes full it could
cause IBM MQ processes to fail or become unstable, affecting the system.
To prevent this situation your IBM MQ administrator should ensure that the system has been allocated
enough virtual memory as specified in the operating system guidelines.

System V IPC kernel configuration

IBM MQ uses System V IPC resources, in particular shared memory. However, a limited number of
semaphores are also used.
The minimum configuration for IBM MQ for these resources is as follows:

Table 12. Minimum tunable kernel parameters values

Increa
Name Kernel-name Value se Description
shmmni kernel.shmmni 4096 Yes Maximum number of shared memory
segments
shmmax kernel.shmmax 268435456 No Maximum size of a shared-memory
segment (bytes)
shmall kernel.shmall 2097152 Yes Maximum amount of shared memory
(pages)
semmsl kernel.sem 32 No Maximum amount of semaphores
permitted per set
semmns kernel.sem 4096 Yes Maximum number of semaphores
semopm kernel.sem 32 No Maximum number of operations in single
operations
semmni kernel.sem 128 Yes Maximum number of semaphore sets
thrmax kernel.threads-max 32768 Yes Maximum number of threads
pidmax kernel.pid_max 32768 Yes Maximum number of process identifiers

Notes:

Installing and migrating 101

 1. These values are sufficient to run two moderate sized queue managers on the system. If you intend to
run more than two queue managers, or the queue managers are to process a significant workload, you
might need to increase the values displayed as Yes in the Increase column.
2. The kernel.sem values are contained within a single kernel parameter containing the four values in
order.
To view the current value of the parameter log on, as a user with root authority, and type:

sysctl Kernel-name

To add or alter these values, log on as a user with root authority. Open the file /etc/sysctl.conf with a
text editor, then add or change the following entries to your chosen values:

kernel.shmmni = 4096
kernel.shmall = 2097152
kernel.shmmax = 268435456
kernel.sem = 32 4096 32 128

Then save and close the file.

To load these sysctl values immediately, enter the following command sysctl -p.
If you do not issue the sysctl -p command, the new values are loaded when the system is rebooted.
By default the Linux kernel has a maximum process identifier, that can also be used with threads, and
might limit the allowed number of threads.
The operating system reports when the system lacks the necessary resources to create another thread, or
the system-imposed limit on the total number of threads in a process {PTHREAD_THREADS_MAX} would
be exceeded.
For more information on kernel.threads-max and kernel.pid-max, see Resource shortage in IBM
MQ queue manager when running a large number of clients

Setting RemoveIPC on IBM MQ

Attention: Leaving the setting of RemoveIPC on its default value of Yes in the login manager
configuration files (logind.con and logind.conf.d) might cause IBM MQ owned IPC resources
being removed outside the control of IBM MQ.
You should set the value to No. For more information on RemoveIPC see the login.conf man page.

TCP/IP configuration
If you want to use keepalive for IBM MQ channels, you can configure the operation of the KEEPALIVE
using the kernel parameters:

net.ipv4.tcp_keepalive_intvl
net.ipv4.tcp_keepalive_probes
net.ipv4.tcp_keepalive_time

See Using the TCP/IP SO_KEEPALIVE option for further information.

To view the current value of the parameter log on, as a user with root authority, and type sysctl
Kernel-name.
To add or alter these values, log on as a user with root authority. Open the file /etc/sysctl.conf with a
text editor, then add or change the following entries to your chosen values.
To load these sysctl values immediately, enter the following command sysctl -p.
If you do not issue the sysctl -p command, the new values are loaded when the system is rebooted.

102 Installing and migrating IBM MQ

RDQM - configuring resource limits and environment variables
For replicated data queue managers (RDQMs), configure the nproc and nofile values for the mqm user
in /etc/security/limits.conf. Alternatively set LimitNOFILE and LimitNPROC variables in the
Pacemaker systemd service unit file for RDQM, named rdqm.conf. If the resource limits (nproc and/or
nofile) are configured in both limits.conf and rdqm.conf, the higher value of the limits configured
is used by the RDQM queue manager. You can use rdqm.conf to configure other resource limits (for
example, stack size) and environment variables. Note that the rdqm.conf file is only read when the
queue manager is started automatically by Pacemaker. This might be at system startup, or when the
queue manager fails over to the node where the rdqm.conf file exists. If the queue manager is started
manually with the strmqm command, it will inherit the environment where strmqm is run.
The following steps create a sample configuration in rdqm.conf:
1. Log in as root on the RDQM node.
2. Create the directory /etc/systemd/system/pacemaker.service.d.
3. Create the file rdqm.conf in that directory. The rdqm.conf file contains the required environment
variables and resource limits in the following format:

[Service]
Environment="MQ_ENV_VAR=1"
LimitNOFILE=65536
LimitNPROC=32768
LimitSTACK=16777216

For more details on configuring the systemd unit file, consult your operating system documentation.
4. Restart the pacemaker service:

systemctl daemon-reload
systemctl restart pacemaker.service

Any RDQM queue managers running on this node move to another node while pacemaker is restarted.
5. Repeat the procedure on the other two RDQM nodes so that the same configuration is used by the
RDQM queue manager when it fails over or switches over to other nodes.
Note: You should use qm.ini attributes in preference to environment variables to control queue manager
behavior because the qm.ini file is replicated between RDQM nodes.

RDQM - configuring the kernel console log level

The DRBD kernel module (kmod-drbd) can sometimes write many messages at the KERN_ERR (3) log
level. To prevent these messages being copied to the system console, which can cause significant
processing delays affecting the entire system, reduce the first number of the kernel.printk parameter
to 3. For more information about kernel message priorities, see https://www.kernel.org/doc/html/latest/
core-api/printk-basics.html.
To view the current value of the parameter, log on as a user with root authority and type sysctl
kernel.printk.
To add or alter this value, log on as a user with root authority. Open the file /etc/sysctl.conf with a
text editor, then add or change the following entry to your chosen value:

kernel.printk = 3 4 1 7

To load these sysctl values immediately, enter the command sysctl -p. If you do not issue the
sysctl -p command, the new values are loaded when the system is rebooted.

32-bit support on 64-bit Linux platforms

Some 64-bit Linux distributions no longer support 32-bit applications by default. For details of affected
platforms, and guidance on enabling 32-bit applications to run on these platforms, see “Hardware and
software requirements on Linux systems” on page 94.

Installing and migrating 103

 Configuring the users who start IBM MQ
You must make the configuration changes described in Maximum open files and Maximum processes for
all users who start IBM MQ. This usually includes the mqm user ID, but the same changes must be made
for any other user IDs who start queue managers.
For queue managers started with systemd, specify equivalent NOFILE and NPROC values in the unit file
that contains the queue manager service configuration.

Maximum open files

The maximum number of open file-handles in the system is controlled by the parameter fs.file-max
The minimum value for this parameter for a system with two moderate sized queue managers is 524288.
Note: If the operating system default is higher, you should leave the higher setting, or consult your
operating system provider.
You are likely to need a higher value if you intend to run more than two queue managers, or the queue
managers are to process a significant workload.
To view the current value of a parameter, log on as a user with root authority, and type sysctl
fs.file-max.
To add or alter these values, log on as a user with root authority. Open the file /etc/sysctl.conf with a
text editor, then add or change the following entry to your chosen value:

fs.file-max = 524288

Then save and close the file.

To load these sysctl values immediately, enter the following command sysctl -p.
If you do not issue the sysctl -p command, the new values are loaded when the system is rebooted.
If you are using a pluggable security module such as PAM (Pluggable Authentication Module), ensure that
this module does not unduly restrict the number of open files for the mqm user. To report the maximum
number of open file descriptors per process for the mqm user, login as the mqm user and enter the following
values:

ulimit -n

For a standard IBM MQ queue manager, set the nofile value for the mqm user to 10240 or more. To set
the maximum number of open file descriptors for processes running under the mqm user, add the following
information to the /etc/security/limits.conf file:

mqm hard nofile 10240

mqm soft nofile 10240

The pluggable security module limits are not applied to queue managers started with systemd. To start
an IBM MQ queue manager with systemd set LimitNOFILE to 10240 or more in the unit file that
contains the queue manager service configuration.
For instructions on how to configure nofile for RDQM queue managers, see RDQM - configuring resource
limits and environment variables.

Maximum processes
A running IBM MQ queue manager consists of a number of thread programs. Each connected application
increases the number of threads running in the queue manager processes. It is normal for an operating
system to limit the maximum number of processes that a user runs. The limit prevents operating system
failures due to an individual user or subsystem creating too many processes. You must ensure that the

104 Installing and migrating IBM MQ

maximum number of processes that the mqm user is allowed to run is sufficient. The number of processes
must include the number of channels and applications that connect to the queue manager.
The following calculation is useful when determining the number of processes for the mqm user:

nproc = 2048 + clientConnections * 4 + qmgrChannels * 4 +

localBindingConnections

where:
• clientConnections is the maximum number of connections from clients on other machines connecting to
queue managers on this machine.
• qmgrChannels is the maximum number of running channels (as opposed to channel definitions) to other
queue managers. This includes cluster channels, sender/receiver channels, and so on.
• localBindingConnections does not include application threads.
The following assumptions are made in this algorithm:
• 2048 is a large enough contingency to cover the queue manager threads. This might need to be
increased if a lot of other applications are running.
• When setting nproc, take into account the maximum number of applications, connections, channels and
queue managers that might be run on the machine in the future.
• This algorithm takes a pessimistic view and the actual nproc needed might be slightly lower for later
versions of IBM MQ and fastpath channels.
• On Linux, each thread is implemented as a light-weight process (LWP) and each LWP is counted as one
process against nproc.
You can use the PAM_limits security module to control the number of processes that users run. You can
configure the maximum number of processes for the mqm user as follows:

mqm hard nproc 4096

mqm soft nproc 4096

For more details on how to configure the PAM_limits security module type, enter the following
command:

man limits.conf

The pluggable security module limits are not applied to queue managers started with systemd. To start
an IBM MQ queue manager with systemd set LimitNPROC to a suitable value in the unit file that
contains the queue manager service configuration.
For instructions on how to configure nproc for RDQM queue managers, see RDQM - configuring resource
limits and environment variables.
You can check your system configuration using the mqconfig command.
For more information on configuring your system, see How to configure AIX and Linux systems for IBM
MQ.
Related concepts
“Setting up the user and group on Linux” on page 98
On Linux systems, IBM MQ requires a user ID of the name mqm, with a primary group of mqm. The mqm user
ID owns the directories and files that contain the resources associated with the product.
“Creating file systems on Linux” on page 99
Before installing IBM MQ, you might need to create file systems for both the product code and working
data to be stored. There are minimum storage requirements for these file systems. The default installation

Installing and migrating 105

 directory for the product code can be changed at installation time, but the working data location cannot
be changed.
Related reference
mqconfig

Accepting the license on IBM MQ for Linux

You can choose to accept the license before or after installing the product on Linux platforms.

About this task

Accepting the IBM MQ license before you install the product causes the following issues for Linux users:
• It stops you adding the IBM MQ RPM to a yum repository.
• It does not fit well with working in the cloud, where the RPM is installed as part of building the image.
• It does not fit well with unzippable packages, where no code is run before installation.
Accepting the license after installation lets you set up your own repository to install from.
Notes:
• You still have to accept the license before you use the product.
• You must have the correct license, or licenses, for the components you want to install. See license
requirements.
• If you have installed a trial license, follow the instructions for converting a trial license. See “Converting
a trial license on Linux” on page 138.

Procedure
• Accept the license before installing the product
To accept the license before installing the product, follow the instructions for installing the server by
preparing your system, then follow the appropriate instructions for your operating system:
rpm
See “Installing the first IBM MQ installation on Linux using the rpm command” on page 111.
yum
See “Installing IBM MQ on Linux Red Hat using yum” on page 121.
Ubuntu using Debian
See “Installing IBM MQ on Linux Ubuntu using Debian” on page 124.
• Accept the license after installing the product
You can use the MQLICENSE environment variable to accept or view an IBM MQ license after you
install the product. MQLICENSE can be set to one of two values:
accept
Accept the license post-installation.
view
Display the license, if the license has been accepted.
To accept the license post-installation, use this command:

export MQLICENSE=accept

To view the license, use this command:

export MQLICENSE=view

106 Installing and migrating IBM MQ

 Alternatively, you can use the following commands to accept or view an IBM MQ license after you
install the product:
– mqlicense (accept license post installation)
– dspmqlic (display IBM MQ license)

Attention: Do not use the mqlicense.sh script from the installation media, because this
script can only be used to accept the license before installation.

Installing IBM MQ on Linux using rpm

Installation tasks that are associated with installing IBM MQ on Linux systems using rpm are grouped in
this section.

About this task

To install IBM MQ using rpm, complete the following tasks.
For information about how to uninstall IBM MQ, see “Uninstalling or modifying IBM MQ on Linux using
rpm” on page 150.
If product fixes or updates are made available, see “Applying maintenance to IBM MQ” on page 278.

Procedure
1. Check the system requirements.
See “Checking requirements on Linux” on page 93.
2. Plan your installation.
• As part of the planning process, you must choose which components to install and where to install
them. See “IBM MQ rpm components for Linux systems” on page 107.
• You must also make some platform-specific choices. See “Planning to install IBM MQ on Linux” on
page 96.
3. Prepare your system for installation of IBM MQ.
See “Preparing the system on Linux” on page 97.
4. Install IBM MQ server.
See “Installing the first IBM MQ installation on Linux using the rpm command” on page 111, and
“Installing additional IBM MQ installations on Linux using the rpm command” on page 115.
5. Optional: Install an IBM MQ client.
See “Installing an IBM MQ client on Linux using rpm” on page 118.
6. Verify your installation. See “Verifying an IBM MQ installation on Linux” on page 139.

IBM MQ rpm components for Linux systems

You can select the components that you require when you install IBM MQ.
Important:
1. For details of what each purchase of IBM MQ entitles you to install, see IBM MQ license information.
2. The RPM package MQSeriesGSKit file must be installed for server and client installation.
To display these components you can use, for example, the following command:

rpm -qa | grep MQ | xargs rpm -q --info

Table 13 on page 108 shows the components that are available when installing an IBM MQ server or
client on a Linux system:

Installing and migrating 107

 Table 13. IBM MQ components for Linux systems
Component Description Serve Client RPM package name
r media
media
Runtime Contains files that are common to both MQSeriesRuntime
server and client installations.
Note: MQSeriesRuntime component
must be installed.

Server You can use the server to run queue MQSeriesServer

managers on your system and connect
to other systems over a network.
Provides messaging and queuing
services to applications, and support
for IBM MQ client connections.
Standard The IBM MQ MQI client is a MQSeriesClient
Client small subset of IBM MQ, without a
queue manager, that uses the queue
manager and queues on other (server)
systems. It can be used only when the
system it is on is connected to another
system that is running a full server
version of IBM MQ. The client and the
server can be on the same system if
required.
SDK The SDK is required for compiling MQSeriesSDK
applications. It includes sample
source files, and the bindings
(files .H, .LIB, .DLL, and others), that
you need to develop applications to
run on IBM MQ.
Sample The sample application programs are MQSeriesSamples
programs needed if you want to check your IBM
MQ installation using the verification
procedures.
Java The files needed for messaging using MQSeriesJava
messaging Java (includes Java Message Service).
Man pages Linux man pages, in U.S. English, for: MQSeriesMan
control commands
MQI calls
MQSC commands

Java JRE A Java Runtime Environment that is MQSeriesJRE

used by those parts of IBM MQ that
are written in Java.
Message For available languages, see the table
Catalogs of message catalogs that follows.
IBM Global IBM Global Security Kit (GSKit) V8 MQSeriesGSKit
Security Kit Certificate and TLS, Base Runtime.
(GSKit)

108 Installing and migrating IBM MQ

Table 13. IBM MQ components for Linux systems (continued)
Component Description Serve Client RPM package name
r media
media
Telemetry MQ Telemetry supports the MQSeriesXRService
Service connection of Internet Of Things
(IOT) devices (that is, remote sensors,
actuators and telemetry devices) that
use the IBM MQ Telemetry Transport
(MQTT) protocol. The telemetry
(MQXR) service enables a queue
manager to act as an MQTT server, and
communicate with MQTT client apps.
Note: The telemetry service is only
available on Linux for x86-64 (64 bit)
and Linux for IBM Z.
A set of MQTT clients is available
from the Eclipse Paho downloads
page. These sample clients help you
write your own MQTT client apps that
IOT devices use to communicate with
MQTT servers.
See also “Installation considerations
for MQ Telemetry” on page 250.

Managed File MQ Managed File Transfer transfers MQSeriesFTAgent

Transfer files between systems in a managed MQSeriesFTBase
and auditable way, regardless of file MQSeriesFTLogger
size or the operating systems used. MQSeriesFTService
For information about the function of MQSeriesFTTools
each component, see “Managed File
Transfer product options” on page
244.
Advanced Provides a high level of protection for MQSeriesAMS
Message sensitive data flowing through the IBM
Security MQ network, while not impacting the
end applications. You must install this
component on all IBM MQ installations
that host queues you want to protect.
You must install the IBM Global
Security Kit (GSKit) component on any
IBM MQ installation that is used by a
program that puts or gets messages to
or from a protected queue, unless you
are using only Java client connections.
You must install the Java JRE
component to install this component.

Installing and migrating 109

 Table 13. IBM MQ components for Linux systems (continued)
Component Description Serve Client RPM package name
r media
media
AMQP Service Install this component to make AMQP MQSeriesAMQP
channels available. AMQP channels
support AMQP 1.0 APIs. You can
use AMQP channels to give AMQP
applications access to the enterprise-
level messaging facilities provided by
IBM MQ.
REST API and Adds HTTP based administration for MQSeriesWeb
IBM MQ IBM MQ through the REST API and
Console IBM MQ Console.
RDQM Install this component to make the MQSeriesRDQM
(replicated replicated data queue manager high
data queue availability configuration available. See
manager) “Installing RDQM (replicated data
queue managers)” on page 255 for
more information.
Note:
This component is available only on
Linux for x86-64 (64 bit), on RHEL 8.8
or later.
This component is not supported for
use with Docker.

Notes:

1. The IBM MQ Bridge to Salesforce is deprecated across all releases from November 22
2022 (see US Announcement letter 222-341).

2. The IBM MQ Bridge to Salesforce is removed from the

product at IBM MQ 9.4.0. Salesforce connectivity can be achieved with IBM App Connect Enterprise.
Salesforce Input and Salesforce Request nodes can be used to interact with Salesforce applications.
For more information, see Using Salesforce with IBM App Connect Enterprise.

3. For Continuous Delivery, the IBM MQ Bridge to blockchain is removed from the product
at IBM MQ 9.3.2.

For Long Term Support, IBM MQ Bridge to blockchain is removed at IBM MQ 9.3.0 Fix
Pack 15.
Blockchain connectivity can be achieved with IBM App Connect or through App Connect capabilities
available with IBM Cloud Pak for Integration.
4. From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ installation package. It
remains available as a separate download, and can be installed from the stand-alone IBM MQ Explorer
download available from Fix Central. For more information, see Installing and uninstalling IBM MQ
Explorer as a stand-alone application on Linux and Windows.

Table 14. IBM MQ message catalogs for Linux systems

Message catalog language RPM package name
Brazilian Portuguese MQSeriesMsg_pt

110 Installing and migrating IBM MQ

Table 14. IBM MQ message catalogs for Linux systems (continued)
Message catalog language RPM package name
Czech MQSeriesMsg_cs
French MQSeriesMsg_fr
German MQSeriesMsg_de
Hungarian MQSeriesMsg_hu
Italian MQSeriesMsg_it
Japanese MQSeriesMsg_ja
Korean MQSeriesMsg_ko
Polish MQSeriesMsg_pl
Russian MQSeriesMsg_ru
Spanish MQSeriesMsg_es
Simplified Chinese MQSeriesMsg_Zh_CN
Traditional Chinese MQSeriesMsg_Zh_TW
U.S. English not applicable

Related concepts
“IBM MQ components and features” on page 6
You can select the components or features that you require when you install IBM MQ.
“Planning considerations for installation on Multiplatforms” on page 14
Before you install IBM MQ, you must choose which components to install and where to install them. You
must also make some platform-specific choices.

Installing the first IBM MQ installation on Linux using the rpm command
You can install an IBM MQ server on a 64-bit Linux system using rpm. The instructions in this topic are for
the first installation of IBM MQ on a Linux system.

Before you begin

• The instructions in this topic are for the first installation of IBM MQ on a Linux system. For instructions
on how to install additional IBM MQ installations, see “Installing additional IBM MQ installations on
Linux using the rpm command” on page 115.
• Before you start the installation procedure, ensure that you have completed the necessary steps
outlined in “Preparing the system on Linux” on page 97.

About this task

Install the server by using the RPM Package Manager installer to select the components you want to
install. The components and package names are listed in “IBM MQ rpm components for Linux systems”
on page 107.
Attention: Unless you install all your required packages in the same operation, you must install the
packages in the following order:

MQSeriesRuntime
MQSeriesJRE
MQSeriesJava
MQSeriesGSKit
MQSeriesServer

Installing and migrating 111

 MQSeriesWeb
MQSeriesFTBase
MQSeriesFTAgent
MQSeriesFTService
MQSeriesFTLogger
MQSeriesFTTools
MQSeriesAMQP
MQSeriesAMS
MQSeriesXRService
MQSeriesClient
MQSeriesMan
MQSeriesMsg
MQSeriesSamples
MQSeriesSDK
Notes:

1. The IBM MQ Bridge to Salesforce is deprecated across all releases from November 22
2022 (see US Announcement letter 222-341).

2. The IBM MQ Bridge to Salesforce is removed from the

product at IBM MQ 9.4.0. Salesforce connectivity can be achieved with IBM App Connect Enterprise.
Salesforce Input and Salesforce Request nodes can be used to interact with Salesforce applications.
For more information, see Using Salesforce with IBM App Connect Enterprise.

3. For Continuous Delivery, the IBM MQ Bridge to blockchain is removed from the product
at IBM MQ 9.3.2.

For Long Term Support, IBM MQ Bridge to blockchain is removed at IBM MQ 9.3.0 Fix
Pack 15.
Blockchain connectivity can be achieved with IBM App Connect or through App Connect capabilities
available with IBM Cloud Pak for Integration.
4. From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ installation package. It
remains available as a separate download, and can be installed from the stand-alone IBM MQ Explorer
download available from Fix Central. For more information, see Installing and uninstalling IBM MQ
Explorer as a stand-alone application on Linux and Windows.

Procedure
1. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
2. Optional: If your installation media is a downloadable installation image, obtained from Passport
Advantage, you must decompress the tar.gz file and extract the installation files from the tar file:
a) For example, if you download part number CC7K6ML, you decompress the file by using the
following command:

gunzip CC7K6ML.tar.gz

b) Similarly, extract the installation files from the tar file by using the following command:

tar -xvf CC7K6ML.tar

Important: You must use GNU tar (also known as gtar) to unpack any tar images.
3. Set your current directory to the location of the installation packages.

112 Installing and migrating IBM MQ

 The location might be a network location, or a local file system directory. See Where to find
downloadable installation images.
4. You have the option of accepting the license before or after installing the product. To accept the
license before installing, run the mqlicense.sh script. The license agreement is displayed in a
language appropriate to your environment and you are prompted to accept or decline the terms of the
license:
• To display the license agreement in the default manner, which uses an X-window where possible,
use the following command:

./mqlicense.sh

• To display the license agreement as text in the current shell, which can be read by a screen reader,
use the following command:

./mqlicense.sh -text_only

See “Accepting the license on IBM MQ for Linux” on page 106 for more information about license
acceptance.
5. Optional: Obtain the IBM MQ public signing gpg key and install it into rpm.

rpm --import ibm_mq_public.pgp

The IBM-provided RPMs are signed with a digital signature, and your system will not recognize
that signature without further steps. This only needs to be done once for each system. For more
information, see “IBM MQ code signatures” on page 12.
The validity of any of the IBM MQ RPMs can then be verified, for example:

# rpm -Kv MQSeriesRuntime-9.4.0-0.x86_64.rpm

MQSeriesRuntime-9.4.0-0.x86_64.rpm:
Header V3 RSA/SHA256 Signature, key ID 0209b828: OK
Header SHA1 digest: OK
V3 RSA/SHA256 Signature, key ID 0209b828: OK
MD5 digest: OK

Note: If you skip this step, then a harmless warning might be issued during RPM installation to indicate
there is a signature but the system does not recognize the signing key, for example:
warning: MQSeriesRuntime-9.4.0-0.x86_64.rpm: Header V3 RSA/SHA256 Signature, key ID 0209b828:
NOKEY
6. Install IBM MQ.
To support the running of a queue manager, you must install at least the MQSeriesRuntime and the
MQSeriesServer components.
Important: The components that you need to install might not all be in the same folder on the
installation media. Some components might be under the /Advanced folder. For more information
about installing IBM MQ Advanced components, see “Installing IBM MQ Advanced for Multiplatforms”
on page 236.
• For IBM MQ 9.4, install IBM MQ in the default location /opt/mqm by using the rpm -Uvh
command:
For example, to install all components that are available in your current location on the installation
media to the default location, use the following command:

rpm -Uvh MQSeries*.rpm

To install the runtime and server components to the default location, use the following command:

rpm -Uvh MQSeriesRuntime-*.rpm MQSeriesServer-*.rpm MQSeriesGSKit-*.rpm

• Install IBM MQ in a non-default location by using the --prefix option. All of the IBM MQ
components that you require must be installed in the same location:

Installing and migrating 113

 The installation path specified must be either an empty directory, the root of an unused file system,
or a path that does not exist. The length of the path is limited to 256 bytes and must not contain
spaces.
For example, enter the following installation path to install the runtime and server components to
the /opt/customLocation directory on a 64-bit Linux system:

rpm --prefix /opt/customLocation -Uvh MQSeriesRuntime-*.rpm MQSeriesServer-*.rpm

Results
You installed IBM MQ on your Linux system.

What to do next
• If required, you can now set this installation to be the primary installation. Enter the following command
at the command prompt:

MQ_INSTALLATION_PATH/bin/setmqinst -i -p MQ_INSTALLATION_PATH

where MQ_INSTALLATION_PATH represents the directory where IBM MQ is installed.

You can have only one primary installation on a system. If there is already a primary installation on the
system, you must unset it before you can set another installation as the primary installation. For more
information, see Changing the primary installation.
• You might want to set up the environment to work with this installation. You can use the setmqenv or
crtmqenv command to set various environment variables for a particular installation of IBM MQ . For
more information, see setmqenv and crtmqenv.
• If you want to confirm that the installation was successful, you can verify your installation. See
“Verifying an IBM MQ installation on Linux” on page 139, for more information.
• Only a user with a UID that is a member of the mqm group can issue administration commands. If you
want to enable users to issue administration commands, they must be added to the mqm group. For
more information, see “Setting up the user and group on Linux” on page 98 and Authority to administer
IBM MQ on AIX, Linux, and Windows systems.
Related concepts
“Multiple installations on AIX, Linux, and Windows” on page 17
On AIX, Linux, and Windows, it is possible to have more than one copy of IBM MQ on a system.
“Primary installation on AIX, Linux, and Windows” on page 18
On systems that support multiple installations of IBM MQ ( AIX, Linux, and Windows ), the primary
installation is the one to which IBM MQ system-wide locations refer. Having a primary installation is
optional, but convenient.
Related tasks
“Uninstalling or modifying IBM MQ on Linux using rpm” on page 150
On Linux, you can uninstall the IBM MQ server or client by using the rpm command. You can also modify
an installation by removing selected packages (components) currently installed on your system.
Changing the primary installation
Related reference
setmqinst

114 Installing and migrating IBM MQ

 Installing additional IBM MQ installations on Linux using the rpm
command
You can install additional IBM MQ servers on a 64-bit Linux system by using the crtmqpkg command
during the installation process.

Before you begin

CAUTION: The instructions in this topic do not apply to Linux Ubuntu or Linux on Power® Systems -
Little Endian. For information about these platforms, see “Installing IBM MQ on Linux Ubuntu using
Debian” on page 124.
• The instructions in this topic are for additional installations of IBM MQ on a Linux system. For
instructions on how to install the first IBM MQ installation, see “Installing the first IBM MQ installation
on Linux using the rpm command” on page 111.
• Before you start the installation procedure, ensure that you have completed the necessary steps
outlined in “Preparing the system on Linux” on page 97.
• Before you can run the crtmqpkg command on Linux, you must have the pax and rpmbuild
commands installed. These commands are not supplied as part of the product. You must get them
from your Linux distribution supplier. The rpmbuild command is located in the rpm-build package.

About this task

Install the server by using the RPM Package Manager installer to select the components you want to
install. The components and package names are listed in “IBM MQ rpm components for Linux systems”
on page 107.
Attention: Unless you install all your required packages in the same operation, you must install the
packages in the following order:

MQSeriesRuntime
MQSeriesJRE
MQSeriesJava
MQSeriesGSKit
MQSeriesServer
MQSeriesWeb
MQSeriesFTBase
MQSeriesFTAgent
MQSeriesFTService
MQSeriesFTLogger
MQSeriesFTTools
MQSeriesAMQP
MQSeriesAMS
MQSeriesXRService
MQSeriesExplorer
MQSeriesClient
MQSeriesMan
MQSeriesMsg
MQSeriesSamples
MQSeriesSDK
Notes:

1. The IBM MQ Bridge to Salesforce is deprecated across all releases from November 22
2022 (see US Announcement letter 222-341).

2. The IBM MQ Bridge to Salesforce is removed from the

product at IBM MQ 9.4.0. Salesforce connectivity can be achieved with IBM App Connect Enterprise.

Installing and migrating 115

 Salesforce Input and Salesforce Request nodes can be used to interact with Salesforce applications.
For more information, see Using Salesforce with IBM App Connect Enterprise.

3. For Continuous Delivery, the IBM MQ Bridge to blockchain is removed from the product
at IBM MQ 9.3.2.

For Long Term Support, IBM MQ Bridge to blockchain is removed at IBM MQ 9.3.0 Fix
Pack 15.
Blockchain connectivity can be achieved with IBM App Connect or through App Connect capabilities
available with IBM Cloud Pak for Integration.
4. From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ installation package. It
remains available as a separate download, and can be installed from the stand-alone IBM MQ Explorer
download available from Fix Central. For more information, see Installing and uninstalling IBM MQ
Explorer as a stand-alone application on Linux and Windows.

Procedure
1. Optional: Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
2. Optional: If your installation media is a downloadable installation image, obtained from Passport
Advantage, you must decompress the tar.gz file and extract the installation files from the tar file:
a) For example, if you download part number CC7K6ML, you decompress the file by using the
following command:

gunzip CC7K6ML.tar.gz

b) Similarly, extract the installation files from the tar file by using the following command:

tar -xvf CC7K6ML.tar

Important: You must use GNU tar (also known as gtar) to unpack any tar images.
3. Set your current directory to the location of the installation files. The location might be a network
location, or a local file system directory.
4. Optional: Run the crtmqpkg command to create a unique set of packages to install on the system.
The crtmqpkg command is required only if this is not the first installation of IBM MQ on the system. If
you have earlier versions of IBM MQ installed on your system, then installing the latest version works
correctly if you install it in a different location.
Before you can run the crtmqpkg command on Linux, you must have the pax and rpmbuild
commands installed. For more information, see Before you begin.
To run the crtmqpkg command on a Linux system:
a) Enter the following command:

./crtmqpkg suffix

where suffix is a name of your choosing that uniquely identifies the installation packages on the
system. suffix is not the same as an installation name, although the names can be identical. suffix is
limited to 16 characters in the ranges A-Z, a-z, and 0-9.
Note: This command creates a full copy of the installation packages in a temporary directory. By
default, the temporary directory is located at /var/tmp. You must ensure that the system has

116 Installing and migrating IBM MQ

 enough free space before you run this command. To use a different location, you can set the
TMPDIR environment variable before you run the crtmqpkg command. For example:

$ TMPDIR=/test ./crtmqpkg suffix

b) Set your current directory to the location specified when the crtmqpkg command operation
completes successfully.
This directory is a subdirectory of the /var/tmp/mq_rpms directory, in which the unique set
of packages is created. The packages have the suffix value contained within the file name. For
example, using a suffix of "1":

./crtmqpkg 1

means there is a subdirectory named /var/tmp/mq_rpms/1/x86_64.

The packages are renamed according to the subdirectory, for example:

From: MQSeriesRuntime-9.4.0-0.x86_64.rpm
To: MQSeriesRuntime-1-9.4.0-0.x86_64.rpm

5. You have the option of accepting the license before or after installing the product. To accept the
license before installing, run the mqlicense.sh script. The license agreement is displayed in a
language appropriate to your environment and you are prompted to accept or decline the terms of the
license:
• To display the license agreement in the default manner, which uses an X-window where possible,
use the following command:

./mqlicense.sh

• To display the license agreement as text in the current shell, which can be read by a screen reader,
use the following command:

./mqlicense.sh -text_only

See “Accepting the license on IBM MQ for Linux” on page 106 for more information about license
acceptance.
6. Install IBM MQ.
To support the running of a queue manager, you must install at least the MQSeriesRuntime and the
MQSeriesServer components.
Important: The components that you need to install might not all be in the same folder on the
installation media. Some components might be under the /Advanced folder. For more information
about installing IBM MQ Advanced components, see “Installing IBM MQ Advanced for Multiplatforms”
on page 236.
• For IBM MQ 9.4, install IBM MQ in the default location /opt/mqm:
For example, to install all components that are available in your current location on the installation
media to the default location, use the following command:

rpm -Uvh MQSeries*.rpm

To install the runtime and server components to the default location, use the following command:

rpm -Uvh MQSeriesRuntime-*.rpm MQSeriesServer-*.rpm

• Install IBM MQ in a non-default location by using the --prefix option. For each installation, all of
the IBM MQ components that you require must be installed in the same location.
The installation path specified must be either an empty directory, the root of an unused file system,
or a path that does not exist. The length of the path is limited to 256 bytes and must not contain
spaces.

Installing and migrating 117

 For example, enter the following installation path to install the runtime and server components to
the /opt/customLocation directory on a 64-bit Linux system:

rpm --prefix /opt/customLocation -Uvh MQSeriesRuntime-*.rpm

MQSeriesServer-*.rpm

Results
You installed IBM MQ on your Linux system.

What to do next
• If required, you can now set this installation to be the primary installation. Enter the following command
at the command prompt:

MQ_INSTALLATION_PATH/bin/setmqinst -i -p MQ_INSTALLATION_PATH

where MQ_INSTALLATION_PATH represents the directory where IBM MQ is installed.

You can have only one primary installation on a system. If there is already a primary installation on the
system, you must unset it before you can set another installation as the primary installation. For more
information, see Changing the primary installation.
• You might want to set up the environment to work with this installation. You can use the setmqenv or
crtmqenv command to set various environment variables for a particular installation of IBM MQ . For
more information, see setmqenv and crtmqenv.
• If you want to confirm that the installation was successful, you can verify your installation. See
“Verifying an IBM MQ installation on Linux” on page 139, for more information.
• Only a user with a UID that is a member of the mqm group can issue administration commands. If you
want to enable users to issue administration commands, they must be added to the mqm group. For
more information, see “Setting up the user and group on Linux” on page 98 and Authority to administer
IBM MQ on AIX, Linux, and Windows systems.
Related concepts
“Multiple installations on AIX, Linux, and Windows” on page 17
On AIX, Linux, and Windows, it is possible to have more than one copy of IBM MQ on a system.
“Primary installation on AIX, Linux, and Windows” on page 18
On systems that support multiple installations of IBM MQ ( AIX, Linux, and Windows ), the primary
installation is the one to which IBM MQ system-wide locations refer. Having a primary installation is
optional, but convenient.
Related tasks
“Uninstalling or modifying IBM MQ on Linux using rpm” on page 150
On Linux, you can uninstall the IBM MQ server or client by using the rpm command. You can also modify
an installation by removing selected packages (components) currently installed on your system.
Changing the primary installation
Related reference
setmqinst

Installing an IBM MQ client on Linux using rpm

Installing an IBM MQ client on a 64 bit Linux system.

Before you begin

• Before you start the installation procedure, make sure that you have completed the necessary steps
outlined in “Preparing the system on Linux” on page 97.
• If this installation is not the only installation on the system, you must ensure that you have write access
to /var/tmp.

118 Installing and migrating IBM MQ

About this task
This task describes the installation of the client, using the RPM Package Manager installer to select
which components you want to install. You must install at least the Runtime and Client components. The
components are listed in “IBM MQ rpm components for Linux systems” on page 107.

Procedure
1. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
2. Set your current directory to the location of the installation packages.
The location might be a network location, or a local file system directory. See Where to find
downloadable installation images.
3. You have the option of accepting the license before or after installing the product. To accept the
license before installing, run the mqlicense.sh script:

./mqlicense.sh

The license agreement is displayed in a language appropriate to your environment and you are
prompted to accept or decline the terms of the license.
If possible, mqlicense.sh opens an X-window to display the license.
If you need the license to be presented as text in the current shell, which can be read by a screen
reader, type the following command:

./mqlicense.sh -text_only

See “Accepting the license on IBM MQ for Linux” on page 106 for more information about license
acceptance.
4. If you have multiple installations on this system, you must run crtmqpkg to create a unique set of
packages to install on the system:
a) Enter the following command:

./crtmqpkg suffix

where suffix is a name of your choosing, that will uniquely identify the installation packages on the
system. suffix is not the same as an installation name, although the names can be identical. suffix is
limited to 16 characters in the ranges A-Z, a-z, and 0-9.
b) Set your current directory to the location specified when the crtmqpkg command completes.
This directory is a sub-directory of /var/tmp/mq_rpms, in which the unique set of packages is
created. The packages have the suffix value contained within the filename.
5. Optional: Obtain the IBM MQ public signing gpg key and install it into rpm.

rpm --import ibm_mq_public.pgp

The IBM-provided RPMs are signed with a digital signature, and your system will not recognize
that signature without further steps. This only needs to be done once for each system. For more
information, see “IBM MQ code signatures” on page 12.
The validity of any of the IBM MQ RPMs can then be verified, for example:

# rpm -Kv MQSeriesRuntime-9.4.0-0.x86_64.rpm

MQSeriesRuntime-9.4.0-0.x86_64.rpm:
Header V3 RSA/SHA256 Signature, key ID 0209b828: OK
Header SHA1 digest: OK

Installing and migrating 119

 V3 RSA/SHA256 Signature, key ID 0209b828: OK
MD5 digest: OK

Note: If you skip this step, then a harmless warning might be issued during RPM installation to indicate
there is a signature but the system does not recognize the signing key, for example:
warning: MQSeriesRuntime-9.4.0-0.x86_64.rpm: Header V3 RSA/SHA256 Signature, key ID 0209b828:
NOKEY
6. Install IBM MQ.
The minimum components you must install are the MQSeriesRuntime, the MQSeriesClient, and the
MQSeriesGSKit.
• To install to the default location, /opt/mqm, use the rpm -ivh command to install each component
that you require.
For example, to install all components to the default location use the following command:

rpm -ivh MQSeries*.rpm

If you are using Ubuntu, add the --force-debian attribute. For example, to install all components
to the default location use the following command:

rpm --force-debian -ivh MQSeries*.rpm

You must include this option to prevent seeing warning messages from the version of RPM for your
platform, which indicates that the RPM packages are not intended to be directly installed using RPM.
• To install to a non-default location use the rpm --prefix option. For each installation, all of the
IBM MQ components that you require must be installed in the same location.
The installation path specified must either be an empty directory, the root of an unused file system,
or a path that does not exist. The length of the path is limited to 256 bytes and must not contain
spaces.
For example, to install the runtime and server components to /opt/customLocation on a 64-bit
Linux system:

rpm --prefix /opt/customLocation -ivh MQSeriesRuntime-V.R.M-F.x86_64.rpm MQSeriesClient-V.R.M-

F.x86_64.rpm

where:
V
Represents the version of the product that you are installing
R
Represents the release of the product that you are installing
M
Represents the modification of the product that you are installing
F
Represents the fix pack level of the product that you are installing

What to do next
• If you have chosen this installation to be the primary installation on the system, you must now set it as
the primary installation. Enter the following command at the command prompt:

MQ_INSTALLATION_PATH/bin/setmqinst -i -p MQ_INSTALLATION_PATH

120 Installing and migrating IBM MQ

 You can have only one primary installation on a system. If there is already a primary installation on the
system, you must unset it before you can set another installation as the primary installation. For more
information, see Changing the primary installation.
• You might want to set up the environment to work with this installation. You can use the setmqenv or
crtmqenv command to set various environment variables for a particular installation of IBM MQ. For
more information, see setmqenv and crtmqenv.
• For instructions on how to verify your installation, see “Testing communication between a client and a
server on Linux” on page 148
Related tasks
“Uninstalling or modifying IBM MQ on Linux using rpm” on page 150
On Linux, you can uninstall the IBM MQ server or client by using the rpm command. You can also modify
an installation by removing selected packages (components) currently installed on your system.

Installing IBM MQ on Linux Red Hat using yum

You can install IBM MQ on Linux Red Hat by using the yum installer.

About this task

• Before you start the installation procedure, ensure that you have completed the necessary steps
outlined in “Preparing the system on Linux” on page 97.
• To install IBM MQ in a non default location, you must run the crtmqpkg command. This command
requires that the system has the following commands installed:
– pax or rpmbuild
– createrepo
– yum-utils
These commands are not supplied as part of the product. You must get them from your Linux
distribution supplier. The rpmbuild command is located in the rpm-build package.

Procedure
1. Optional: Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
2. Optional: If your installation media is a downloadable installation image, obtained from Passport
Advantage, you must decompress the tar.gz file and extract the installation files from the tar file:
a) For example, if you download part number CC7K6ML, you decompress the file by using the
following command:

gunzip CC7K6ML.tar.gz

b) Similarly, extract the installation files from the tar file by using the following command:

tar -xvf CC7K6ML.tar

Important: You must use GNU tar (also known as gtar) to unpack any tar images.
3. Optional: If this is not the first installation on the system, or if you want to install IBM MQ to a non
default location, run the crtmqpkg to create a unique set of packages to install on the system:

./crtmqpkg suffix installationPath

where:

Installing and migrating 121

 • suffix specifies a name of your choosing that uniquely identifies the installation packages on the
system. suffix is not the same as an installation name, although the names can be identical. suffix is
limited to 16 characters in the ranges A-Z, a-z, and 0-9.
• installationPath specifies the path where you want to install IBM MQ.
Note: This command creates a full copy of the installation packages in a temporary directory. By
default, the temporary directory is located at /var/tmp. You must ensure that the system has
enough free space before you run this command. To use a different location, you can set the TMPDIR
environment variable before you run the crtmqpkg command. For example:

$ TMPDIR=/test ./crtmqpkg suffix installationPath

4. Set your current directory to the location of the installation packages. If you used the crtmqpkg
command, this directory is the location that is specified when the crtmqpkg command operation
completes successfully.
5. Configure the yum repository:
A sample repository file is available in the MQServer directory of the installation packages. You can
use this sample to assist you in configuring the yum repository.
a) Create or update the repository:
• If this is the first IBM MQ installation on the system, create a file with the suffix .repo, for
example, IBM_MQ.repo, in the /etc/yum.repos.d directory.
• If this is an additional IBM MQ installation on the system, append the details of the additional
installation to the appropriate .repo file in the /etc/yum.repos.d directory.
b) Add the following contents to the repository file:

[IBM-MQ-v.r.m-architecture]
name=IBM MQ v.r.m architecture
baseurl=file:///installationFilesLocation
enabled=1
gpgcheck=0

c) Replace the installationFilesLocation variable with the location of the installation files.
d) Replace the v.r.m variable with the version, release, and modification number for the version of IBM
MQ that you want to install.
e) Replace the architecture variable with the architecture of the system you are installing on. This
value is one of the following values:
• x86_64
• ppc64le
• s390x
f) Optional: Enable gpg key verification.
Replace gpgcheck=0 with gpgcheck=1 and add an additional gpgkey=<uri> line pointing to the
certificate provided, for example:

gpgcheck=1
gpgkey=file:///directory/to/ibm_mq_public.pgp

g) Optional: If you appended contents to the repository file, clear the repository cache by using the
following command:

yum clean all

h) Check that the IBM MQ repository is available by using the following command:

yum repolist

6. You have the option of accepting the license before or after installing the product. To accept the
license before installing, run the mqlicense.sh script. The license agreement is displayed in a

122 Installing and migrating IBM MQ

 language appropriate to your environment and you are prompted to accept or decline the terms of the
license:
• To display the license agreement in the default manner, which uses an X-window where possible,
use the following command:

./mqlicense.sh

• To display the license agreement as text in the current shell, which can be read by a screen reader,
use the following command:

./mqlicense.sh -text_only

See “Accepting the license on IBM MQ for Linux” on page 106 for more information about license
acceptance.
7. Install IBM MQ:
• To install all available components in the default location, use the following command:

yum -y install MQSeries*

• To install all available components in a non default location, use the following command:

yum -y install MQSeries*suffix*

where suffix specifies the suffix that was chosen when you ran crtmqpkg in step “3” on page 121.
• To install a subset of components, specify the components that you want to install. Any
dependencies are automatically installed. To support the running of a queue manager, you must
install at least the MQSeriesRuntime and the MQSeriesServer components. For example, to install
the server component in the default location, use the following command:

yum -y install MQSeriesServer*

• To install an older version of IBM MQ when multiple versions are available in the repository file, use
the following command:

yum -y install MQSeries*-v.r.m-f

where v.r.m-f specifies the version, release, modification, and fix pack level to install.

Results
You installed IBM MQ on your Linux system.

What to do next
• If required, you can now set this installation to be the primary installation. Enter the following command
at the command prompt:

MQ_INSTALLATION_PATH/bin/setmqinst -i -p MQ_INSTALLATION_PATH

where MQ_INSTALLATION_PATH represents the directory where IBM MQ is installed.

You can have only one primary installation on a system. If there is already a primary installation on the
system, you must unset it before you can set another installation as the primary installation. For more
information, see Changing the primary installation.
• You might want to set up the environment to work with this installation. You can use the setmqenv or
crtmqenv command to set various environment variables for a particular installation of IBM MQ . For
more information, see setmqenv and crtmqenv.
• If you want to confirm that the installation was successful, you can verify your installation. See
“Verifying an IBM MQ installation on Linux” on page 139, for more information.

Installing and migrating 123

 • Only a user with a UID that is a member of the mqm group can issue administration commands. If you
want to enable users to issue administration commands, they must be added to the mqm group. For
more information, see “Setting up the user and group on Linux” on page 98 and Authority to administer
IBM MQ on AIX, Linux, and Windows systems.
Related concepts
“Multiple installations on AIX, Linux, and Windows” on page 17
On AIX, Linux, and Windows, it is possible to have more than one copy of IBM MQ on a system.
“Primary installation on AIX, Linux, and Windows” on page 18
On systems that support multiple installations of IBM MQ ( AIX, Linux, and Windows ), the primary
installation is the one to which IBM MQ system-wide locations refer. Having a primary installation is
optional, but convenient.
Related tasks
“Uninstalling or modifying IBM MQ on Linux Red Hat using yum” on page 152
On Linux Red Hat, you can uninstall the IBM MQ server or client using the yum command. You can also
modify an installation by removing selected packages (components) currently installed on your system.
Changing the primary installation
Related reference
setmqinst

Installing IBM MQ on Linux Ubuntu using Debian

Installation tasks that are associated with installing IBM MQ on Linux systems using a Debian installer are
grouped in this section.

About this task

To install IBM MQ using a Debian installer, complete the following tasks.
If product fixes or updates are made available, see “Applying maintenance to IBM MQ” on page 278.

Procedure
1. Check the system requirements.
See “Checking requirements on Linux” on page 93.
2. Plan your installation.
As part of the planning process, you must choose which components to install and where to install
them. See “IBM MQ Debian components for Linux Ubuntu systems” on page 125.
3. Prepare your system for installation of IBM MQ.
See “Preparing the system on Linux” on page 97.
4. Install IBM MQ server.
See “Installing an IBM MQ server on Linux Ubuntu using Debian packages” on page 128.
5. Optional: Install an IBM MQ client.
See “Installing an IBM MQ client on Linux Ubuntu using Debian packages ” on page 134.
6. Verify your installation. See “Verifying an IBM MQ installation on Linux” on page 139.

Overview of the Debian installer for IBM MQ on Linux Ubuntu

An overview of the concepts and considerations for installing IBM MQ, on Linux Ubuntu, using the Debian
installer.

Installation tools
Use apt, dpkg, or a higher level installation tool, to install and uninstall the product. The installed product
on disk appears identical to an rpm-installed copy.

124 Installing and migrating IBM MQ

 Attention: The Debian installation tools have no provision for overriding the installation directory.
This means that there is no relocatable or multi-version support. Therefore the product will be
installed to /opt/mqm, but this can be set as the primary installation if you require.

Package names
The package names have been changed to use an IBM MQ derived name.
For example, the Debian equivalent of the existing rpm server component, MQSeriesServer, is ibmmq-
server.
On a single system, you can have a single version of IBM MQ installed by Debian, or you can achieve
multi-version installation with Debian through the use of container based technologies, such as Docker.

IBM MQ Debian components for Linux Ubuntu systems

You can select the components that you require when you install IBM MQ.
Important: For details of what each purchase of IBM MQ entitles you to install, see IBM MQ license
information.
Table 15 on page 125 shows the components that are available when installing an IBM MQ server or
client on a Linux Ubuntu system using the Debian installer:

Table 15. IBM MQ Debian components for Linux Ubuntu systems

Component Description Serve Client Debian package name
r media
media
Runtime Contains files that are common to both ibmmq-runtime
server and client installations.
Note: ibmmq-runtime component
must be installed.

Server You can use the server to run queue ibmmq-server

managers on your system and connect
to other systems over a network.
Provides messaging and queuing
services to applications, and support
for IBM MQ client connections.
Standard The IBM MQ MQI client is a ibmmq-client
Client small subset of IBM MQ, without a
queue manager, that uses the queue
manager and queues on other (server)
systems. It can be used only when the
system it is on is connected to another
system that is running a full server
version of IBM MQ. The client and the
server can be on the same system if
required.
SDK The SDK is required for compiling ibmmq-sdk
applications. It includes sample
source files, and the bindings
(files .H, .LIB, .DLL, and others), that
you need to develop applications to
run on IBM MQ.

Installing and migrating 125

 Table 15. IBM MQ Debian components for Linux Ubuntu systems (continued)
Component Description Serve Client Debian package name
r media
media
Sample The sample application programs are ibmmq-samples
programs needed if you want to check your IBM
MQ installation using the verification
procedures.
Java The files needed for messaging using ibmmq-java
messaging Java (includes Java Message Service).
Man pages AIX man pages, in U.S. English, for: ibmmq-man
control commands
MQI calls
MQSC commands

Java JRE A Java Runtime Environment that is ibmmq-jre

used by those parts of IBM MQ that
are written in Java.
Message For available languages, see the table
Catalogs of message catalogs that follows.
IBM Global IBM Global Security Kit (GSKit) V8 ibmmq-gskit
Security Kit Certificate and TLS, Base Runtime.
(GSKit)
Telemetry MQ Telemetry supports the ibmmq-xrservice
Service connection of Internet Of Things
(IOT) devices (that is, remote sensors,
actuators and telemetry devices) that
use the IBM MQ Telemetry Transport
(MQTT) protocol. The telemetry
service, which is also know as the
MQXR service, enables a queue
manager to act as an MQTT server, and
communicate with MQTT client apps.
Note: The telemetry service is only
available on Linux for x86-64 (64 bit)
and Linux for IBM Z.
The Eclipse Paho project, and
MQTT.org, have free downloads of the
latest telemetry clients and samples
for a range of programming languages.
Use these resources to help you
write the MQTT client apps that IOT
devices use to communicate with
MQTT servers.
See also “Installation considerations
for MQ Telemetry” on page 250.

126 Installing and migrating IBM MQ

Table 15. IBM MQ Debian components for Linux Ubuntu systems (continued)
Component Description Serve Client Debian package name
r media
media
Managed File MQ Managed File Transfer transfers ibmmq-ftagent
Transfer files between systems in a managed ibmmq-ftbase
and auditable way, regardless of file ibmmq-ftlogger
size or the operating systems used. ibmmq-ftservice
For information about the function of ibmmq-fttools
each component, see “Managed File
Transfer product options” on page
244.
Advanced Provides a high level of protection for ibmmq-ams
Message sensitive data flowing through the IBM
Security MQ network, while not impacting the
end applications. You must install this
component on all IBM MQ installations
that host queues you want to protect.
You must install the IBM Global
Security Kit (GSKit) component on any
IBM MQ installation that is used by a
program that puts or gets messages to
or from a protected queue, unless you
are using only Java client connections.
You must install the Java JRE
component to install this component.

AMQP Service Install this component to make AMQP ibmmq-amqp

channels available. AMQP channels
support AMQP 1.0 APIs. You can
use AMQP channels to give AMQP
applications access to the enterprise-
level messaging facilities provided by
IBM MQ.
REST API and Adds HTTP based administration for ibmmq-web
IBM MQ IBM MQ through the REST API and
Console IBM MQ Console.

Notes:

1. The IBM MQ Bridge to Salesforce is deprecated across all releases from November 22
2022 (see US Announcement letter 222-341).

2. The IBM MQ Bridge to Salesforce is removed from the

product at IBM MQ 9.4.0. Salesforce connectivity can be achieved with IBM App Connect Enterprise.
Salesforce Input and Salesforce Request nodes can be used to interact with Salesforce applications.
For more information, see Using Salesforce with IBM App Connect Enterprise.

3. For Continuous Delivery, the IBM MQ Bridge to blockchain is removed from the product
at IBM MQ 9.3.2.

For Long Term Support, IBM MQ Bridge to blockchain is removed at IBM MQ 9.3.0 Fix
Pack 15.

Installing and migrating 127

 Blockchain connectivity can be achieved with IBM App Connect or through App Connect capabilities
available with IBM Cloud Pak for Integration.
4. From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ installation package. It
remains available as a separate download, and can be installed from the stand-alone IBM MQ Explorer
download available from Fix Central. For more information, see Installing and uninstalling IBM MQ
Explorer as a stand-alone application on Linux and Windows.

Table 16. IBM MQ message catalogs for Linux systems

Message catalog language Component name
Brazilian Portuguese ibmmq-msg-pt
Czech ibmmq-msg-cs
French ibmmq-msg-fr
German ibmmq-msg-de
Hungarian ibmmq-msg-hu
Italian ibmmq-msg-it
Japanese ibmmq-msg-ja
Korean ibmmq-msg-ko
Polish ibmmq-msg-pl
Russian ibmmq-msg-ru
Spanish ibmmq-msg-es
Simplified Chinese ibmmq-msg-zh-cn
Traditional Chinese ibmmq-msg-zh-tw
U.S. English not applicable

Related concepts
“IBM MQ components and features” on page 6
You can select the components or features that you require when you install IBM MQ.

Installing an IBM MQ server on Linux Ubuntu using Debian packages

You can install an IBM MQ server on a Linux Ubuntu system, using a Debian installer, in accordance with
the system requirements web page.

Before you begin

See System Requirements for IBM MQ for details of the supported software levels.
Before you start the installation procedure, make sure that you first complete the necessary steps that are
outlined in “Preparing the system on Linux” on page 97.
If you have installed IBM MQ 9.0.2, or earlier, on Ubuntu using rpm, you must uninstall all rpm versions of
the product before installing the Debian version of the product.
You have the option to accept the license before or after product installation. See “Accepting the license
on IBM MQ for Linux” on page 106 for more information.

About this task

Install the server by using a Debian installer to select the components that you want to install. The
components and package names are listed in “IBM MQ Debian components for Linux Ubuntu systems” on
page 125.

128 Installing and migrating IBM MQ

 Attention: Ensure that you download the Ubuntu version of the tar.gz package, before you
install the product, as this version contains the deb files you need for the apt-get tool.
You can use various installers. This topic describes the use of the apt-get and dpkg installers.
apt-get
You can use apt-get to install packages, and you do not need to install any dependent packages.
apt-get installs dependency packages for the package that you require.
You must make your files accessible to apt-get, in order to use it.
To do this, issue the command, chmod -R a+rx DIRNAME, where DIRNAME is the directory into
which you unpacked the tar.gz package.
Attention: If you do not make your files accessible to apt-get, you receive the following
errors:
• N: Download is performed unsandboxed as root as file '/sw/9400deb/./InRelease' couldn't
be accessed by user '_apt'. - pkgAcquire::Run (13: Permission denied)
• E: Failed to fetch file:/sw/9400deb/./Packages File not found - /sw/9400deb/./Packages (2:
No such file or directory)
• E: Some index files failed to download. They have been ignored, or old ones used instead.
where /sw/9400deb is the directory from which you are installing IBM MQ.
dpkg
You can use dpkg to install individual packages, but you must ensure you install any dependencies as
dpkg does not install any dependent packages for the package you require. Refer to the Table 17 on
page 129 table for information about the dependencies of each package.
To support the running of a queue manager, you must install at least the ibmmq-runtime and the
ibmmq-server components.

Table 17. Package component dependencies

Package
Package Name Component Function Dependencies
ibmmq-runtime Common function for all other components None
ibmmq-server Queue Manager ibmmq-runtime
ibmmq-gskit

ibmmq-client C IBM MQ client libraries ibmmq-runtime

ibmmq-gskit

ibmmq-java Java and JMS IBM MQ APIs ibmmq-runtime

ibmmq-jre Java Runtime Environment ibmmq-runtime
ibmmq-sdk Header files and libraries for non-Java APIs ibmmq-runtime
ibmmq-man UNIX man pages for IBM MQ ibmmq-runtime
ibmmq-samples IBM MQ application samples ibmmq-runtime

Installing and migrating 129

 Table 17. Package component dependencies (continued)
Package
Package Name Component Function Dependencies

ibmmq-msg-cs Additional language message catalog files. English ibmmq-runtime

message catalog files are installed by default. For
ibmmq-msg-de more information about these message catalogs,
ibmmq-msg-es see “Displaying messages in your national
language on Linux” on page 138
ibmmq-msg-fr
ibmmq-msg-hu
ibmmq-msg-it
ibmmq-msg-ja
ibmmq-msg-ko
ibmmq-msg-pl
ibmmq-msg-pt
ibmmq-msg-ru
ibmmq-msg-zh-cn
ibmmq-msg-zh-tw

ibmmq-gskit IBM Global Security Kit (GSKit) ibmmq-runtime

ibmmq-web REST API and IBM MQ Console. ibmmq-runtime

ibmmq-server
ibmmq-java
ibmmq-jre

ibmmq-ftbase Managed File Transfer component ibmmq-runtime

ibmmq-java
ibmmq-jre

ibmmq-ftlogger Managed File Transfer component ibmmq-runtime

ibmmq-server
ibmmq-ftbase
ibmmq-java
ibmmq-jre

ibmmq-fttools Managed File Transfer components ibmmq-runtime

ibmmq-ftagent ibmmq-ftbase
ibmmq-java
ibmmq-jre

130 Installing and migrating IBM MQ

Table 17. Package component dependencies (continued)
Package
Package Name Component Function Dependencies
ibmmq-ftservice Managed File Transfer component ibmmq-runtime
ibmmq-server
ibmmq-ftagent
ibmmq-ftbase
ibmmq-java
ibmmq-jre

ibmmq-amqp Advanced Message Queuing Protocol component ibmmq-runtime

ibmmq-xrservice Telemetry Service component ibmmq-runtime

Note: The telemetry service is only available on
Linux for x86-64 (64 bit) and Linux for IBM Z.

ibmmq-ams Advanced Message Security component ibmmq-runtime

ibmmq-server

Notes:

1. The IBM MQ Bridge to Salesforce is deprecated across all releases from November 22
2022 (see US Announcement letter 222-341).

2. The IBM MQ Bridge to Salesforce is removed from the

product at IBM MQ 9.4.0. Salesforce connectivity can be achieved with IBM App Connect Enterprise.
Salesforce Input and Salesforce Request nodes can be used to interact with Salesforce applications.
For more information, see Using Salesforce with IBM App Connect Enterprise.

3. For Continuous Delivery, the IBM MQ Bridge to blockchain is removed from the product
at IBM MQ 9.3.2.

For Long Term Support, IBM MQ Bridge to blockchain is removed at IBM MQ 9.3.0 Fix
Pack 15.
Blockchain connectivity can be achieved with IBM App Connect or through App Connect capabilities
available with IBM Cloud Pak for Integration.
4. From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ installation package. It
remains available as a separate download, and can be installed from the stand-alone IBM MQ Explorer
download available from Fix Central. For more information, see Installing and uninstalling IBM MQ
Explorer as a stand-alone application on Linux and Windows.

Procedure
1. Open a shell terminal. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
2. Set your current directory to the location of the installation packages.
The location might be a network location, or a local file system directory. See Where to find
downloadable installation images.

Installing and migrating 131

 3. You have the option of accepting the license before or after installing the product. To accept the
license before installing, run the mqlicense.sh script:

./mqlicense.sh

The license agreement is displayed in a language appropriate to your environment and you are
prompted to accept or decline the terms of the license.
If possible, mqlicense.sh opens an X-window to display the license.
If you need the license to be presented as text in the current shell, which can be read by a screen
reader, type the following command:

./mqlicense.sh -text_only

See “Accepting the license on IBM MQ for Linux” on page 106 for more information about license
acceptance.
4. Choose how to install the IBM MQ packages:
Either use the apt management tool to install the IBM MQ packages that you want, or use the dpkg
command to install the IBM MQ packages that you want along with their dependency packages.
• To use the apt-get management tool to install the IBM MQ packages that you want along with
their dependency packages:
a. Create a file with the suffix .list, for example, IBM_MQ.list, in the /etc/apt/
sources.list.d directory.
This file should contain a deb entry for the location of the directory that contains the IBM MQ
packages.
For example:

# Local directory containing IBM MQ packages

deb [trusted=yes] file:/var/tmp/mq ./

The inclusion of the [trusted=yes] statement (including the brackets) is optional and
suppresses warnings and prompts during subsequent operations.
b. Run the command apt-get update to add this directory, and the list of packages the directory
contains, to the apt cache.
Refer to the Attention note in “apt-get” on page 129 for possible errors you might receive.
You can now use apt to install IBM MQ. For example, you can install the complete product by
issuing the following command:

apt-get install "ibmmq-*"

You can install the server package and all its dependencies by issuing the following command:

apt-get install ibmmq-server

Attention: Do not run the apt-get install ibmmq-* command in the directory
which holds the .deb files, unless you are using quotation characters in the shell.
If you are using tools such as aptitude or synaptic, the install packages can be found in the
misc\non-free category.
• To use the dpkg command to install the IBM MQ packages that you want, issue the dpkg command
for each IBM MQ package that you want to install. For example, issue the following command to
install the run time package:

dpkg -i ibmmq-runtime_9.4.0.0_amd64.deb

132 Installing and migrating IBM MQ

 Important: Although dpkg permits multiple package files in the same command, this will not
work as expected because of IBM MQ inter-package dependencies. You must install the packages
individually in the order shown below. You may find that using apt-get is a better option.
– ibmmq-runtime
– ibmmq-jre
– ibmmq-java
– ibmmq-gskit
– ibmmq-server
– ibmmq-web
– ibmmq-ftbase
– ibmmq-ftagent
– ibmmq-ftservice
– ibmmq-ftlogger
– ibmmq-fttools
– ibmmq-amqp
– ibmmq-ams
– ibmmq-xrservice
– ibmmq-client
– ibmmq-man
– ibmmq-msg_language
– ibmmq-samples
– ibmmq-sdk

Results
You have installed the packages you require.

What to do next
• If required, you can now set this installation to be the primary installation. Enter the following command
at the command prompt:

MQ_INSTALLATION_PATH/bin/setmqinst -i -p MQ_INSTALLATION_PATH

where MQ_INSTALLATION_PATH represents the directory where IBM MQ is installed.

• You might want to set up the environment to work with this installation. You can use the setmqenv or
crtmqenv command to set various environment variables for a particular installation of IBM MQ . For
more information, see setmqenv and crtmqenv.
• If you want to confirm that the installation was successful, you can verify your installation. See
“Verifying an IBM MQ installation on Linux” on page 139, for more information.
Related tasks
“Uninstalling or modifying IBM MQ on Linux Ubuntu using Debian packages” on page 154

Installing and migrating 133

 You can uninstall an IBM MQ server or client that was installed using the Debian package manager. You
can also modify an installation by removing selected packages (components) currently installed on your
system.

Installing an IBM MQ client on Linux Ubuntu using Debian packages

You can install an IBM MQ client on a Linux Ubuntu system, using a Debian package, in accordance with
the system requirements web page.

Before you begin

See System Requirements for IBM MQ for details of the supported software levels.
Before you start the installation procedure, make sure that you have completed the necessary steps
outlined in “Preparing the system on Linux” on page 97.

About this task

Install the client by using a Debian installer to select the components that you want to install. The
components and package names are listed in “IBM MQ Debian components for Linux Ubuntu systems” on
page 125.

Procedure
1. Open a shell terminal. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
2. Set your current directory to the location of the installation packages.
The location might be a network location, or a local file system directory. See Where to find
downloadable installation images.
3. You have the option of accepting the license before or after installing the product. To accept the
license before installing, run the mqlicense.sh script:

./mqlicense.sh

The license agreement is displayed in a language appropriate to your environment and you are
prompted to accept or decline the terms of the license.
If possible, mqlicense.sh opens an X-window to display the license.
If you need the license to be presented as text in the current shell, which can be read by a screen
reader, type the following command:

./mqlicense.sh -text_only

See “Accepting the license on IBM MQ for Linux” on page 106 for more information about license
acceptance.
4. Install the IBM MQ client.
You can use any Debian installer. “Installing an IBM MQ server on Linux Ubuntu using Debian
packages” on page 128 describes the use of the apt-get and dpkg packages to install a server.
At a minimum, you must install the ibmmq-runtime component.
If you are installing a subset of components, you must ensure that any dependencies are first installed,
as listed in Table 18 on page 135.
To install and use the package listed in the Package Name column, you must also install the
components listed in the Package Dependencies column.

134 Installing and migrating IBM MQ

Table 18. Package component dependencies
Package
Package Name Component Function Dependencies
ibmmq-runtime Common function for all other components None
ibmmq-client C IBM MQ client libraries ibmmq-gskit
ibmmq-runtime

ibmmq-java Java and JMS IBM MQ APIs ibmmq-runtime

ibmmq-jre Java Runtime Environment ibmmq-runtime
ibmmq-sdk Header files and libraries for non-Java APIs ibmmq-runtime
ibmmq-man UNIX man pages for IBM MQ ibmmq-runtime
ibmmq-samples IBM MQ application samples ibmmq-runtime

ibmmq-msg-cs Language specific message catalog files ibmmq-runtime

ibmmq-msg-de
ibmmq-msg-es
ibmmq-msg-fr
ibmmq-msg-hu
ibmmq-msg-it
ibmmq-msg-ja
ibmmq-msg-ko
ibmmq-msg-pl
ibmmq-msg-pt
ibmmq-msg-ru
ibmmq-msg-zh-cn
ibmmq-msg-zh-tw

ibmmq-gskit IBM Global Security Kit (GSKit) ibmmq-runtime

ibmmq-jre

Notes:

a. The IBM MQ Bridge to Salesforce is deprecated across all releases from November 22
2022 (see US Announcement letter 222-341).

b. The IBM MQ Bridge to Salesforce is removed from the

product at IBM MQ 9.4.0. Salesforce connectivity can be achieved with IBM App Connect
Enterprise. Salesforce Input and Salesforce Request nodes can be used to interact with Salesforce
applications. For more information, see Using Salesforce with IBM App Connect Enterprise.

c. For Continuous Delivery, the IBM MQ Bridge to blockchain is removed from the
product at IBM MQ 9.3.2.

For Long Term Support, IBM MQ Bridge to blockchain is removed at IBM MQ 9.3.0 Fix
Pack 15.

Installing and migrating 135

 Blockchain connectivity can be achieved with IBM App Connect or through App Connect
capabilities available with IBM Cloud Pak for Integration.

Results
You have installed the packages you require.

What to do next
• If you have chosen this installation to be the primary installation on the system, you must now set it as
the primary installation. Enter the following command at the command prompt:

MQ_INSTALLATION_PATH/bin/setmqinst -i -p MQ_INSTALLATION_PATH

• You might want to set up the environment to work with this installation. You can use the setmqenv or
crtmqenv command to set various environment variables for a particular installation of IBM MQ. For
more information, see setmqenv and crtmqenv.
• For instructions on how to verify your installation, see “Testing communication between a client and a
server on Linux” on page 148
Related concepts
“Multiple installations on AIX, Linux, and Windows” on page 17
On AIX, Linux, and Windows, it is possible to have more than one copy of IBM MQ on a system.
“Primary installation on AIX, Linux, and Windows” on page 18
On systems that support multiple installations of IBM MQ ( AIX, Linux, and Windows ), the primary
installation is the one to which IBM MQ system-wide locations refer. Having a primary installation is
optional, but convenient.
Related tasks
“Uninstalling or modifying IBM MQ on Linux using rpm” on page 150
On Linux, you can uninstall the IBM MQ server or client by using the rpm command. You can also modify
an installation by removing selected packages (components) currently installed on your system.
Changing the primary installation
Related reference
setmqinst

Redistributable clients on Linux

The Linux x86-64 image is shipped in a LinuxX64.tar.gz file.

File names
The archive or .zip file names describe the file contents and equivalent maintenance levels.
For IBM MQ 9.4 the client images are available under the following file names:
Long Term Support: 9.4.0 IBM MQ C redistributable client for Linux x86-64
9.4.0.0-IBM-MQC-Redist-LinuxX64.tar.gz
Long Term Support: 9.4.0 IBM MQ JMS and Java redistributable client
9.4.0.0-IBM-MQC-Redist-Java.zip

Choosing the runtime files to distribute with an application

A script file named genmqpkg is provided by the redistributable client under the bin directory.
You can use the genmqpkg script to generate a smaller subset of files that are tailored to the needs of the
application, for which the files are intended to be distributed.

136 Installing and migrating IBM MQ

 You are asked a series of interactive Yes or No questions to determine the runtime requirements for an
IBM MQ application.
Finally, genmqpkg asks you to supply a new target directory, where the script duplicates the required
directories and files.
Important: A fully qualified path should be supplied to genmqpkg, as genmqpkg will not expand or
evaluate shell variables.
Important: IBM support is only able to provide assistance with the full, unmodified set of files contained
within the redistributable client packages.

Other considerations
On Linux, the default data path of a non-installed client is:
Linux x86-64
$HOME/IBM/MQ/data
You can change the default directory of the data path, by using the MQ_OVERRIDE_DATA_PATH
environment variable.
Note: You must create the directory first, as the directory is not created automatically.
A redistributable client runtime co-exists with a full IBM MQ client or server installation, provided that
they are installed in different locations.
Important: Unpacking a redistributable image into the same location as a full IBM MQ installation is not
supported.
On Linux the ccsid.tbl used to define the supported CCSID conversions is traditionally expected to be
found in the UserData directory structure, along with error logs, trace files, and so on.
The UserData directory structure is populated by unpacking the redistributable client, and so, if the
file is not found in its usual location, the redistributable client falls back to locate the file in the /lib
subdirectory of the installation.

Classpath changes
The classpath used by dspmqver, setmqenv, and crtmqenv commands adds the
com.ibm.mq.allclient.jar and com.ibm.mq.jakarta.client.jar to the environment,
immediately following the com.ibm.mq.jar, and com.ibm.mqjms.jar.
An example of dspmqver output from the redistributable client on Linux:

Name: IBM MQ
Version: 9.4.0.0
Level: p940-940-L220415
BuildType: IKAP - (Production)
Platform: IBM MQ for Linux (x86-64 platform)
Mode: 64-bit
O/S: Linux 2.6.32.59-0.7-default
InstName: MQNI09200004
InstDesc: IBM MQ V9.4.0.0 (Redistributable)
Primary: No
InstPath: /Development/johndoe/unzip/unpack
DataPath: /u/johndoe/IBM/MQ/data
MaxCmdLevel: 940

Related concepts
“Redistributable IBM MQ clients” on page 26

Installing and migrating 137

 The IBM MQ redistributable client is a collection of runtime files that are provided in a .zip or .tar file
that can be redistributed to third parties under redistributable license terms. This provides a simple way
of distributing applications and the runtime files that they require in a single package.

Converting a trial license on Linux

Convert a trial license to a full license without reinstalling IBM MQ.
When the trial license expires, the "count-down" displayed by the strmqm command informs you the
license has expired, and the command does not run.

Before you begin

1. IBM MQ is installed with a trial license.
2. You have access to the installation media of a fully licensed copy of IBM MQ.

About this task

Run the setmqprd command to convert a trial license to a full license.
If you do not want to apply a full license to your trial copy of IBM MQ, you can uninstall it at any time.

Procedure
1. Obtain the full license from the fully licensed installation media.
The full license file is amqpcert.lic. On Linux, it is in the /MediaRoot/licenses directory on the
installation media.
2. Run the setmqprd command from the installation that you are upgrading:

MQ_INSTALLATION_PATH/bin/setmqprd /MediaRoot/licenses/amqpcert.lic

Related reference
setmqprd

Displaying messages in your national language on Linux

To display messages from a different national language message catalog, you must install the appropriate
catalog and set the LANG environment variable.

About this task

Messages in U.S. English are automatically installed with IBM MQ
Message catalogs for all languages are installed in MQ_INSTALLATION_PATH/msg/language
identifier, where language identifier is one of the identifiers in Table 19 on page 138.
If you require messages in a different language, perform the following steps:

Procedure
1. Install the appropriate message catalog (see “IBM MQ components and features” on page 6 ).
2. To select messages in a different language, ensure the LANG environment variable is set to the
identifier for the language you want to install:

Table 19. Language identifiers

Identifier Language
cs_CZ Czech

138 Installing and migrating IBM MQ

 Table 19. Language identifiers (continued)
Identifier Language
de_DE German
es_ES Spanish
fr_FR French
hu_HU Hungarian
it_IT Italian
ja_JP Japanese
ko_KR Korean
pl_PL Polish
pt_BR Brazilian Portuguese
ru_RU Russian
zh_CN Simplified Chinese
zh_TW Traditional Chinese

Verifying an IBM MQ installation on Linux

The topics in this section provide instructions on how to verify a server or a client installation of IBM MQ
on Linux systems.

About this task

You can verify a local (stand-alone) server installation or a server-to-server installation of the IBM MQ
server:
• A local server installation has no communication links with other IBM MQ installations.
• A server-to-server installation does have links to other installations.
You can also verify that your IBM MQ MQI client installation completed successfully and that the
communication link is working.

Procedure
• To verify a local server installation, see “Verifying a local server installation using the command line on
Linux” on page 139.
• To verify a server-to-server installation, see “Verifying a server-to-server installation using the
command line on Linux” on page 141.
• To verify a client installation, see “Verifying a client installation on Linux” on page 144.

Verifying a local server installation using the command line on Linux

On Linux systems, you can verify a local installation by using the command line to create a simple
configuration of one queue manager and one queue.

Before you begin

To verify the installation, you must first install the samples package.
Before beginning the verification procedure, you might want to check that you have the latest fixes for
your system. For more information about where to find the latest updates, see “Checking requirements on
Linux” on page 93.

Installing and migrating 139

 About this task
Use the following steps to configure your default queue manager from the command line. After the queue
manager is configured, use the amqsput sample program to put a message on the queue. You then use
the amqsget sample program to get the message back from the queue.
IBM MQ object definitions are case-sensitive. Any text entered as an MQSC command in lowercase is
converted automatically to uppercase unless you enclose it in single quotation marks. Make sure that you
type the examples exactly as shown.

Procedure
1. On a Linux system, log in as a user in the mqm group.
2. Set up your environment:
a) Set up environment variables for use with a particular installation by entering the following
command:

. MQ_INSTALLATION_PATH/bin/setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

b) Check that the environment is set up correctly by entering the following command:

dspmqver

If the command completes successfully, and the expected version number and installation name
are returned, the environment is set up correctly.
3. Create a queue manager called QMA by entering the following command:

crtmqm QMA

Messages indicate when the queue manager is created, and when the default IBM MQ objects are
created.
4. Start the queue manager by entering the following command:

strmqm QMA

A message indicates when the queue manager starts.

5. Start MQSC by entering the following command:

runmqsc QMA

A message indicates when MQSC starts. MQSC has no command prompt.

6. Define a local queue called QUEUE1 by entering the following command:

DEFINE QLOCAL (QUEUE1)

A message indicates when the queue is created.

7. Stop MQSC by entering the following command:

end

Messages are shown, followed by the command prompt.

Note: Subsequent steps require that the samples package is installed.

140 Installing and migrating IBM MQ

 8. Change into the MQ_INSTALLATION_PATH/samp/bin directory, which contains the sample
programs.
MQ_INSTALLATION_PATH represents the high-level directory in which IBM MQ is installed.
9. Put a message on the queue by entering the following commands

./amqsput QUEUE1 QMA

The following messages are shown:

Sample AMQSPUT0 start

target queue is QUEUE1

10. Type some message text on one or more lines, where each line is a different message. Enter a blank
line to end the message input.
The following message is shown:

Sample AMQSPUT0 end

Your messages are now on the queue and the command prompt is shown.
11. Get the messages from the queue, by entering the following command:

./amqsget QUEUE1 QMA

The sample program starts, and your messages are displayed.

Results
You have successfully verified your local installation.

Verifying a server-to-server installation using the command line on Linux

You can verify a server-to-server installation using two servers, one as a sender and one as a receiver.

Before you begin

• On Linux, IBM MQ supports TCP on all Linux platforms. On x86 platforms and Power platforms, SNA
is also supported. If you want to use the SNA LU6.2 support on these platforms, you need the IBM
Communications Server for Linux 6.2. The Communications Server is available as a PRPQ product from
IBM. For more details, see Communications Server.
If you are using TCP/IP, make sure that TCP/IP and IBM MQ are installed on both servers.
• The examples in this task use TCP/IP. If you do not use TCP, see Setting up communication on AIX and
Linux.
• Make sure that you are a member of the IBM MQ administrators group (mqm) on each server.
• Decide which installation is the sender server and which installation is the receiver server. The
installations might be on the same system, or on different systems.

About this task

IBM MQ object definitions are case-sensitive. Any text entered as an MQSC command in lowercase is
converted automatically to uppercase unless you enclose it in single quotation marks. Make sure that you
type the examples exactly as shown.

Procedure
1. On the receiver server:
a) On Linux, log in as a user in the mqm group.

Installing and migrating 141

 b) Check which ports are free, for example by running netstat. For more information about this
command, see the documentation of your operating system.
If port 1414 is not in use, make a note of 1414 to use as the port number in step 2 h. Use the same
number for the port for your listener later in the verification. If it is in use, note a port that is not in
use; for example 1415.
c) Set up the environment for the installation you are using by entering the following command at the
command prompt:

. MQ_INSTALLATION_PATH/bin/setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

d) Create a queue manager called QMB by entering the following command at the command prompt:

crtmqm QMB

Messages tell you that the queue manager has been created, and that the default IBM MQ objects
have been created.
e) Start the queue manager by entering the following command:

strmqm QMB

A message tells you when the queue manager has started.

f) Start MQSC by entering the following command:

runmqsc QMB

A message tells you that MQSC has started. MQSC has no command prompt.
g) Define a local queue called RECEIVER.Q by entering the following command:

DEFINE QLOCAL (RECEIVER.Q)

A message tells you the queue has been created.

h) Define a listener by entering the following command:
DEFINE LISTENER (LISTENER1) TRPTYPE (TCP) CONTROL (QMGR) PORT ( PORT_NUMBER )

Where port_number is the name of the port the listener runs on. This number must be the same as
the number used when defining your sender channel.
i) Start the listener by entering the following command:

START LISTENER (LISTENER1)

Note: Do not start the listener in the background from any shell that automatically lowers the
priority of background processes.
j) Define a receiver channel by entering the following command:

DEFINE CHANNEL (QMA.QMB) CHLTYPE (RCVR) TRPTYPE (TCP)

A message tells you when the channel has been created.

k) End MQSC by typing:

end

142 Installing and migrating IBM MQ

 Some messages are displayed, followed by the command prompt.
2. On the sender server:
a) As the sender server is an AIX system, log in as a user in the mqm group.
b) Set up the environment for the installation you are using by entering the following command at the
command prompt:

. MQ_INSTALLATION_PATH/bin/setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

c) Create a queue manager called QMA by entering the following command at the command prompt:

crtmqm QMA

Messages tell you that the queue manager has been created, and that the default IBM MQ objects
have been created.
d) Start the queue manager, by entering the following command:

strmqm QMA

A message tells you when the queue manager has started.

e) Start MQSC by entering the following command:

runmqsc QMA

A message tells you that an MQSC session has started. MQSC had no command prompt.
f) Define a local queue called QMB (to be used as a transmission queue) by entering the following
command:

DEFINE QLOCAL (QMB) USAGE (XMITQ)

A message tells you when the queue has been created.

g) Define a local definition of the remote queue with by entering the following command:

DEFINE QREMOTE (LOCAL.DEF.OF.REMOTE.QUEUE) RNAME (RECEIVER.Q) RQMNAME ('QMB') XMITQ (QMB)

h) Define a sender channel by entering one of the following commands:

con-name is the TCP/IP address of the receiver system. If both installations are on the same
system, the con-name is localhost. port is the port you noted in 1 b. If you do not specify a port,
the default value of 1414 is used.
DEFINE CHANNEL (QMA.QMB) CHLTYPE (SDR) CONNAME ('CON-NAME(PORT)') XMITQ (QMB) TRPTYPE (TCP)

i) Start the sender channel by entering the following command:

START CHANNEL(QMA.QMB)

The receiver channel on the receiver server starts automatically when the sender channel starts.
j) Stop MQSC by entering the following command:

end

Some messages are displayed, followed by the command prompt.

Installing and migrating 143

 k) Change into the MQ_INSTALLATION_PATH/samp/bin directory. This directory contains the
sample programs. MQ_INSTALLATION_PATH represents the high-level directory in which IBM MQ is
installed.
l) If both the sender server and receiver server are installations on the same system, check that the
queue managers have been created on different installations by entering the following command:

dspmq -o installation

If the queue managers are on the same installation, move either QMA to the sender installation
or QMB to the receiver installation by using the setmqm command. For more information, see
setmqm.
m) Put a message on the local definition of the remote queue, which in turn specifies the name of the
remote queue. Enter the following command:

./amqsput LOCAL.DEF.OF.REMOTE.QUEUE QMA

A message tells you that amqsput has started.

n) Type some message text on one or more lines, followed by a blank line.
A message tells you that amqsput has ended. Your message is now on the queue and the
command prompt is displayed again.
3. On the receiver server:
a) As your receiver server is an AIX system, change into the MQ_INSTALLATION_PATH/samp/bin
directory.
This directory contains the sample programs. MQ_INSTALLATION_PATH represents the high-level
directory in which IBM MQ is installed.
b) Get the message from the queue on the receiver by entering the following command:

./amqsget RECEIVER.Q QMB

The sample program starts, and your message is displayed. After a pause, the sample ends. Then
the command prompt is displayed.

Results
You have now successfully verified the server-to-server installation.

Verifying a client installation on Linux

You can verify that your IBM MQ MQI client installation completed successfully and that the
communication link is working.

About this task

The verification procedure shows how to create a queue manager called queue.manager.1, a local
queue called QUEUE1, and a server-connection channel called CHANNEL1 on the server.
It shows how to create the client-connection channel on the IBM MQ MQI client workstation. It then
shows how to use the sample programs to put a message onto a queue, and get the message from the
queue.
The example does not address any client security issues. See Setting up IBM MQ MQI client security for
details if you are concerned with IBM MQ MQI client security issues.
The verification procedure assumes that:
• The full IBM MQ server product has been installed on a server.
• The server installation is accessible on your network.

144 Installing and migrating IBM MQ

• The IBM MQ MQI client software has been installed on a client system.
• The IBM MQ sample programs have been installed.
• TCP/IP has been configured on the server and client systems. For more information, see Configuring
connections between the server and client.

Procedure
1. Set up the server and client by using the command line.
See “Setting up the server and client using the command line on Linux” on page 145.
2. Test the communications between client and server.
See “Testing communication between a client and a server on Linux” on page 148.
Related tasks
“Installing an IBM MQ client on Linux using rpm” on page 118
Installing an IBM MQ client on a 64 bit Linux system.

Setting up the server and client using the command line on Linux
You can use the command line to create the objects that you need to use to verify a client installation
on Linux. On the server you create a queue manager, a local queue, a listener, and a server-connection
channel. You must also apply security rules to allow the client to connect and make use of the queue
defined. On the client you create a client-connection channel. After setting up the server and client, you
can then use the sample programs to complete the verification procedure.

Before you begin

Before starting this task, review the information in “Verifying a client installation on Linux” on page 144.

About this task

This task explains how to use the command line to set up the server and client so that you can verify your
client installation.

Procedure
1. Set up the server by following the instructions in “Setting up the server using the command line on
Linux” on page 145.
2. Set up the client by following instructions in “Connecting to a queue manager, using the MQSERVER
environment variable on Linux” on page 147.

What to do next
Test the communications between client and server by following the instructions in “Testing
communication between a client and a server on Linux” on page 148.

Setting up the server using the command line on Linux

Follow these instructions to create a queue manager, queue, and channel on the server. You can then use
these objects to verify the installation.

About this task

These instructions assume that no queue manager or other IBM MQ objects have been defined.
IBM MQ object definitions are case-sensitive. Any text entered as an MQSC command in lowercase is
converted automatically to uppercase unless you enclose it in single quotation marks. Make sure that you
type the examples exactly as shown.

Installing and migrating 145

 Procedure
1. Create a user ID on the server that is not in the mqm group.
This user ID must exist on the server and client. This is the user ID that the sample applications must
be run as, otherwise a 2035 error is returned.
2. Log in as a user in the mqm group.
3. You must set various environment variables so that the installation can be used in the current shell.
You can set the environment variables by entering the following command:

. MQ_INSTALLATION_PATH/bin/setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

4. Create a queue manager called QUEUE.MANAGER.1 by entering the following command:

crtmqm QUEUE.MANAGER.1

You see messages telling you that the queue manager has been created.
5. Start the queue manager by entering the following command:

strmqm QUEUE.MANAGER.1

A message tells you when the queue manager has started.

6. Start MQSC by entering the following command:

runmqsc QUEUE.MANAGER.1

A message tells you that an MQSC session has started. MQSC has no command prompt.
7. Define a local queue called QUEUE1 by entering the following command:

DEFINE QLOCAL(QUEUE1)

A message tells you when the queue has been created.

8. Allow the user ID that you created in step 1 to use QUEUE1 by entering the following command:

SET AUTHREC PROFILE(QUEUE1) OBJTYPE(QUEUE) PRINCIPAL(' non_mqm_user ') AUTHADD(PUT,GET)

where non_mqm_user is the user ID created in step 1. A message tells you when the authorization
has been set. You must also run the following command to give the user ID authority to connect:

SET AUTHREC OBJTYPE(QMGR) PRINCIPAL(' non_mqm_user ') AUTHADD(CONNECT)

If this command is not run, a 2305 stop error is returned.

9. Define a server-connection channel by entering the following command:

DEFINE CHANNEL (CHANNEL1) CHLTYPE (SVRCONN) TRPTYPE (TCP)

A message tells you when the channel has been created.

10. Allow your client channel to connect to the queue manager and run under the user ID that you
created in step 1, by entering the following MQSC command:

SET CHLAUTH(CHANNEL1) TYPE(ADDRESSMAP) ADDRESS(' client_ipaddr ') MCAUSER(' non_mqm_user ')

146 Installing and migrating IBM MQ

 where client_ipaddr is the IP address of the client system, and non_mqm_user is the user ID created
in step 1. A message tells you when the rule has been set.
11. Define a listener by entering the following command:

DEFINE LISTENER (LISTENER1) TRPTYPE (TCP) CONTROL (QMGR) PORT (port_number)

where port_number is the number of the port the listener is to run on. This number must be the same
as the number used when defining your client-connection channel in “Installing an IBM MQ client on
Linux using rpm” on page 118.
Note: If you omit the port parameter from the command, a default value of 1414 is used for the
listener port. If you want to specify a port other than 1414, you must include the port parameter in
the command, as shown.
12. Start the listener by entering the following command:

START LISTENER (LISTENER1)

13. Stop MQSC by entering:

end

You see some messages, followed by the command prompt.

What to do next
Follow the instructions to set up the client. See “Connecting to a queue manager, using the MQSERVER
environment variable on Linux” on page 147.

Connecting to a queue manager, using the MQSERVER environment variable on Linux

When an IBM MQ application is run on the IBM MQ MQI client, it requires the name of the MQI channel,
the communication type, and the address of the server to be used. Provide these parameters by defining
the MQSERVER environment variable.

Before you begin

Before you start this task, you must complete the task, “Setting up the server using the command line on
Linux” on page 145, and save the following information:
• The host name or IP address of the server and port number that you specified when creating the
listener.
• The channel name of the server-connection channel.

About this task

This task describes how to connect an IBM MQ MQI client, by defining the MQSERVER environment
variable on the client.
You can give the client access to the generated client channel definition table, amqclchl.tab instead;
see Accessing client-connection channel definitions.

Procedure
1. Log in as the userid that you created in Step 1 of “Setting up the server using the command line on
Linux” on page 145.
2. Check the TCP/IP connection. From the client, enter one of the following commands:
• ping server-hostname
• ping n.n.n.n

Installing and migrating 147

 n.n.n.n represents the network address. You can set the network address in IPv4 dotted decimal
form, for example, 192.0.2.0. Alternatively, set the address in IPv6 hexadecimal form, for
example 2001:0DB8:0204:acff:fe97:2c34:fde0:3485.
If the ping command fails, correct your TCP/IP configuration.
3. Set the MQSERVER environment variable. From the client, enter the following command:

export MQSERVER=CHANNEL1/TCP/'server-address (port)'

Where:
• CHANNEL1 is the server-connection channel name.
• server-address is the TCP/IP host name of the server.
• port is the TCP/IP port number the server is listening on.
If you do not give a port number, IBM MQ uses the one specified in the qm.ini file, or the client
configuration file. If no value is specified in these files, IBM MQ uses the port number identified in the
TCP/IP services file for the service name MQSeries. If an MQSeries entry in the services file does not
exist, a default value of 1414 is used. It is important that the port number used by the client and the
port number used by the server listener program are the same.

What to do next
Use the sample programs to test communication between the client and server; see “Testing
communication between a client and a server on Linux” on page 148.

Testing communication between a client and a server on Linux

On the IBM MQ MQI client workstation, use the amqsputc sample program to put a message on the
queue at the server workstation. Use the amqsgetc sample program to get the message from the queue
back to the client.

Before you begin

Complete the previous topics in this section:
• Set up a queue manager, channels, and queue.
• Open a command window.
• Set system environment variables.

About this task

Note that IBM MQ object definitions are case-sensitive. Text entered as an MQSC command in lowercase
is converted automatically to uppercase unless you enclose it in single quotation marks. Make sure that
you type the examples exactly as shown.
You must be logged in with the appropriate authority. For example, user ivtid in the mqm group.

Procedure
1. Change to the MQ_INSTALLATION_PATH/samp/bin directory, which contains the sample
programs.
MQ_INSTALLATION_PATH represents the high-level directory in which IBM MQ is installed.
2. You must set certain environment variables so that the installation can be used in the current shell.
You can set the environment variables by entering the following command:

. MQ_INSTALLATION_PATH/bin/setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

3. Start the PUT program for QUEUE1 on QUEUE.MANAGER.1 by entering the following command:

148 Installing and migrating IBM MQ

 ./amqsputc QUEUE1 QUEUE.MANAGER.1

If the command is successful, the following messages are displayed:

Sample AMQSPUT0 start

target queue is QUEUE1

Tip: You might get the error, MQRC_NOT_AUTHORIZED (2035). By default, channel authentication
is enabled when a queue manager is created. Channel authentication prevents privileged users
accessing a queue manager as an IBM MQ MQI client. For verifying the installation, you can either
change the MCA user ID to a non-privileged user, or disable channel authentication. To disable channel
authentication run the following MQSC command:

ALTER QMGR CHLAUTH(DISABLED)

When you finish the test, if you do not delete the queue manager, re-enable channel authentication:

ALTER QMGR CHLAUTH(ENABLED)

4. Type some message text, then press Enter twice.

The following message is displayed:

Sample AMQSPUT0 end

Your message is now on the queue that is on the server queue manager.
5. Start the GET program for QUEUE1 on QUEUE.MANAGER.1 by entering the following command:

./amqsgetc QUEUE1 QUEUE.MANAGER.1

The sample program starts, and your message is displayed. After a short pause (approximately 30
seconds), the sample ends and the command prompt is displayed again.

Results
You have now successfully verified the client installation.

What to do next
1. You must set various environment variables on the server so that the installation can be used in the
current shell. You can set the environment variables by entering the following command:

. MQ_INSTALLATION_PATH/bin/setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

2. On the server, stop the queue manager by entering the following command:

endmqm QUEUE.MANAGER.1

3. On the server, delete the queue manager by entering the following command:

dltmqm QUEUE.MANAGER.1

Installing and migrating 149

 Uninstalling or modifying IBM MQ on Linux
You can uninstall an IBM MQ server or client. You can also modify an installation by removing selected
packages (components) currently installed on your system.

Procedure
• For information on how to uninstall or modify IBM MQ on Linux, see the following subtopics:
– “Uninstalling or modifying IBM MQ on Linux using rpm” on page 150
– “Uninstalling or modifying IBM MQ on Linux Ubuntu using Debian packages” on page 154

Uninstalling or modifying IBM MQ on Linux using rpm

On Linux, you can uninstall the IBM MQ server or client by using the rpm command. You can also modify
an installation by removing selected packages (components) currently installed on your system.

Before you begin

Depending on which version of IBM MQis installed, you might need to remove maintenance
before you uninstall the base packages:
• If you are uninstalling a version of IBM MQ at IBM MQ 9.4.0 or later, you do not need to remove
maintenance before you uninstall IBM MQ.
• If you are uninstalling a version of IBM MQ before IBM MQ 9.4.0, you must remove any maintenance
that is applied to IBM MQ before you can uninstall. The procedure for removing maintenance changed at
IBM MQ 9.4.0. Therefore, you must use the procedure that is detailed in earlier versions of the product
documentation to remove the maintenance.
Important: You must stop all IBM MQ queue managers, other objects, and applications, before you begin
the process to uninstall or modify IBM MQ.

Procedure
1. Stop all IBM MQ applications associated with the installation you are uninstalling or modifying, if you
have not already done so.
2. For a server installation, end any IBM MQ activity that is associated with the installation you are
uninstalling or modifying:
a) Log in as a user in the group mqm.
b) Set up your environment to work with the installation you want to uninstall or modify. Enter the
following command:

. MQ_INSTALLATION_PATH/bin/setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

c) Display the state of all queue managers on the system. Enter the following command:

dspmq -o installation

d) Stop all running queue managers that are associated with the installation that you want to uninstall
or modify. Enter the following command for each queue manager:

endmqm QMgrName

e) Stop any listeners associated with the queue managers. Enter the following command for each
queue manager:

150 Installing and migrating IBM MQ

 endmqlsr -m QMgrName

3. Log in as root.
4. Uninstall or modify IBM MQby using the rpm command:
a) On a system with a single installation:
• Find out the names of the packages (components) currently installed on your system, by entering
the following command:

rpm -qa | grep MQSeries

• Remove all components by appending all the package names to the rpm command arguments.
For example:

rpm -qa | grep MQSeries | xargs rpm -ev

• Modify your installation by appending individual package names to the rpm command arguments.
For example, to remove the runtime, Server and SDK components enter the following command:

rpm -ev MQSeriesRuntime MQSeriesServer MQSeriesSDK

• If you are using Ubuntu, add the --force-debian attribute. For example, to remove the
runtime, Server and SDK components enter the following command:

rpm --force-debian -ev MQSeriesRuntime MQSeriesServer MQSeriesSDK

b) On a system with multiple installations:

• Find out the names of the packages (components) currently installed on your system, by entering
the following command:

rpm -qa | grep suffix

where suffix is the unique name that is given to the packages when crtmqpkg was run at
installation time. suffix is included in each of the package names that belong to a particular
installation.
• Remove all components by appending all the package names to the rpm command arguments.
For example, to remove all components from an installation with the suffix MQ94 enter the
following command:

rpm -qa | grep '\<MQSeries.*MQ94\>' | xargs rpm -ev

• Modify your installation by appending individual package names to the rpm command arguments.
For example, to remove the runtime, Server and SDK components from an installation with the
suffix MQ94 enter the following command:

rpm -ev MQSeriesRuntime-MQ94 MQSeriesServer-MQ94 MQSeriesSDK-MQ94

• If you are using Ubuntu, add the --force-debian attribute. For example, to remove the
runtime, Server and SDK components for an installation with the suffix MQ94, enter the following
command:

rpm --force-debian -ev MQSeriesRuntime-MQ94 MQSeriesServer-MQ94 MQSeriesSDK-MQ94

Installing and migrating 151

 Results
After uninstallation, certain files under the directory trees /var/mqm and /etc/opt/mqm are not
removed. These files contain user data and remain so subsequent installations can reuse the data.
Most of the remaining files contain text, such as INI files, error logs, and FDC files. The directory
tree /var/mqm/shared contains files that are shared across installations, including the executable
shared libraries libmqzsd.so and libmqzsd_r.so.

What to do next
• If the product successfully uninstalled, you can delete any files and directories that are contained in the
installation directory.
• If no other IBM MQ installations exist on the system, and you are not planning to reinstall or migrate,
you can delete the /var/mqm and /etc/opt/mqm directory trees, including the files libmqzsd.so
and libmqzsd_r.so. Deleting these directories destroys all queue managers and their associated
data.

Uninstalling or modifying IBM MQ on Linux Red Hat using yum

On Linux Red Hat, you can uninstall the IBM MQ server or client using the yum command. You can also
modify an installation by removing selected packages (components) currently installed on your system.

Before you begin

Depending on which version of IBM MQis installed, you might need to remove maintenance
before you uninstall the base packages:
• If you are uninstalling a version of IBM MQ at IBM MQ 9.4.0 or later, you do not need to remove
maintenance before you uninstall IBM MQ.
• If you are uninstalling a version of IBM MQ before IBM MQ 9.4.0, you must remove any maintenance
that is applied to IBM MQ before you can uninstall. The procedure for removing maintenance changed at
IBM MQ 9.4.0. Therefore, you must use the procedure that is detailed in earlier versions of the product
documentation to remove the maintenance.
Important: You must stop all IBM MQ queue managers, other objects, and applications, before you begin
the process to uninstall or modify IBM MQ.

Procedure
1. Stop all IBM MQ applications associated with the installation you are uninstalling or modifying, if you
have not already done so.
2. For a server installation, end any IBM MQ activity associated with the installation you are uninstalling
or modifying:
a) Log in as a user in the group mqm.
b) Set up your environment to work with the installation you want to uninstall or modify. Enter the
following command:

. MQ_INSTALLATION_PATH/bin/setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

c) Display the state of all queue managers on the system. Enter the following command:

dspmq -o installation

d) Stop all running queue managers associated with the installation you want to uninstall or modify.
Enter the following command for each queue manager:

152 Installing and migrating IBM MQ

 endmqm QMgrName

e) Stop any listeners associated with the queue managers. Enter the following command for each
queue manager:

endmqlsr -m QMgrName

3. Log in as root.
4. Uninstall or modify IBM MQ using the yum remove command:
• On a system with a single installation:
– Remove the installation by using the following command:

yum remove MQSeries*

– Modify the installation to add a component by using the following command:

yum install packageName

where packageName specifies the component you want to add.

– Modify the installation to remove a component by using the following command:

yum remove packageName

where packageName specifies the component you want to remove.

• On a system with a multiple installations:
– Remove an installation by using the following command:

yum remove MQSeries*suffix*

where suffix specifies the suffix that uniquely identifies the installation.
– Modify the installation to add a component by using the following command:

yum install packageName*suffix*

where packageName specifies the component you want to add, and suffix specifies the suffix
that uniquely identifies the installation.
– Modify the installation to remove a component by using the following command:

yum remove packageName*suffix*

where packageName specifies the component you want to remove, and suffix specifies the suffix
that uniquely identifies the installation.

Results
After uninstallation, certain files under the directory trees /var/mqm and /etc/opt/mqm are not
removed. These files contain user data and remain so subsequent installations can reuse the data.
Most of the remaining files contain text, such as INI files, error logs, and FDC files. The directory
tree /var/mqm/shared contains files that are shared across installations, including the executable
shared libraries libmqzsd.so and libmqzsd_r.so.

What to do next
• If the product successfully uninstalled, you can delete any files and directories contained in the
installation directory.
• If there are no other IBM MQ installations on the system, and you are not planning to reinstall
or migrate, you can delete the /var/mqm and /etc/opt/mqm directory trees, including the files

Installing and migrating 153

 libmqzsd.so and libmqzsd_r.so. Deleting these directories destroys all queue managers and their
associated data.
Related tasks
“Installing IBM MQ on Linux Red Hat using yum” on page 121
You can install IBM MQ on Linux Red Hat by using the yum installer.
“Upgrading an IBM MQ installation on Linux” on page 321
You can upgrade an IBM MQ installation on Linux systems without uninstalling the earlier version.
“Uninstalling or modifying IBM MQ on Linux using rpm” on page 150
On Linux, you can uninstall the IBM MQ server or client by using the rpm command. You can also modify
an installation by removing selected packages (components) currently installed on your system.

Uninstalling or modifying IBM MQ on Linux Ubuntu using Debian packages

You can uninstall an IBM MQ server or client that was installed using the Debian package manager. You
can also modify an installation by removing selected packages (components) currently installed on your
system.

Before you begin

Depending on which version of IBM MQis installed, you might need to remove maintenance
before you uninstall the base packages:
• If you are uninstalling a version of IBM MQ at IBM MQ 9.4.0 or later, you do not need to remove
maintenance before you uninstall IBM MQ.
• If you are uninstalling a version of IBM MQ before IBM MQ 9.4.0, you must remove any maintenance
that is applied to IBM MQ before you can uninstall. The procedure for removing maintenance changed at
IBM MQ 9.4.0. Therefore, you must use the procedure that is detailed in earlier versions of the product
documentation to remove the maintenance.
Important: You must stop all IBM MQ queue managers, other objects, and applications, before you begin
the process to uninstall or modify IBM MQ.

Procedure
1. Stop all IBM MQ applications associated with the installation you are uninstalling or modifying, if you
have not already done so.
2. For a server installation, end any IBM MQ activity associated with the installation you are uninstalling
or modifying:
a) Log in as a user in the group mqm.
b) Set up your environment to work with the installation you want to uninstall or modify. Enter the
following command:

. MQ_INSTALLATION_PATH/bin/setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

c) Display the state of all queue managers on the system. Enter the following command:

dspmq -o installation

d) Stop all running queue managers associated with the installation you want to uninstall or modify.
Enter the following command for each queue manager:

endmqm QMgrName

154 Installing and migrating IBM MQ

 e) Stop any listeners associated with the queue managers. Enter the following command for each
queue manager:

endmqlsr -m QMgrName

3. Log in as root.
4. Uninstall or modify IBM MQ using a Debian installation command:
• Using apt.
Issuing the command:

apt-get remove "ibmmq-*"

removes the product but leaves the package definition cached.

Issuing the command:

apt-get purge "ibmmq-*"

purges the cached definition of the product.

• Using dpkg.
Issuing the command:

dpkg -r packagename

removes the product but leaves the package definition cached.

Issuing the command:

dpkg -P packagename

purges the cached definition of the product.

Results
After uninstallation, certain files under the directory trees /var/mqm and /etc/opt/mqm are not
removed. These files contain user data and remain so subsequent installations can reuse the data.
Most of the remaining files contain text, such as INI files, error logs, and FDC files. The directory
tree /var/mqm/shared contains files that are shared across installations, including the executable
shared libraries libmqzsd.so and libmqzsd_r.so.

What to do next
• If the product successfully uninstalled, you can delete any files and directories contained in the
installation directory.
• If there are no other IBM MQ installations on the system, and you are not planning to reinstall
or migrate, you can delete the /var/mqm and /etc/opt/mqm directory trees, including the files
libmqzsd.so and libmqzsd_r.so. Deleting these directories destroys all queue managers and their
associated data.
Related tasks
“Removing a fix pack from IBM MQ on Linux Ubuntu using Debian packages” on page 156

Installing and migrating 155

 Follow these instructions to remove a fix pack, for example IBM MQ 9.4.0 Fix Pack 1, on Linux Ubuntu
using Debian packages.

Removing a fix pack from IBM MQ on Linux Ubuntu using Debian packages
Follow these instructions to remove a fix pack, for example IBM MQ 9.4.0 Fix Pack 1, on Linux Ubuntu
using Debian packages.

Before you begin

Note: The following instructions apply to a Linux Ubuntu system.
Important: You must stop all IBM MQ queue managers, other objects, and applications, before you begin
the process of modifying IBM MQ.

About this task

IBM MQ for Linux platforms use two different directory trees that are mutually exclusive. The two trees
are for:
• The executable libraries and shared libraries,/opt/mqm .
• The data for the queue managers and other configuration files, var/mqm.
Because the directory trees are mutually exclusive, when you apply or remove maintenance only the files
in opt/mqm are affected.
You must uninstall IBM MQ in the reverse order of installation. That is, remove any fix pack you have
applied and then remove the base version of the product.

Procedure
1. Stop all IBM MQ queue managers and clients associated with the installation that you are modifying, if
you have not already done so.
For example, issue the following command:

$ endmqm -i TEST_94

You receive a message that the queue manager TEST_94 is ending (that is, shutting down), followed
by another message when shutdown has completed.
2. Issue the following command:

$ ps -ef | grep -i mq

You receive a message similar to this:

mqm 5492 5103 0 16:35 pts/0 00:00:00 ps -ef

Now that there is no IBM MQ activity on the system, you can uninstall the product.
3. Log in as root and issue the a command similar to the following, to find out the file sets for IBM MQ
9.4.0 Fix Pack 1.

+++ROOT+++ ubuntumq1.fyre.ibm.com: /root

# apt list "ibmmq-*-u9301*"
Listing... Done
ibmmq-amqp-u9301/unknown,now 9.4.0.1 amd64 [installed]
ibmmq-ams-u9301/unknown,now 9.4.0.1 amd64 [installed]
…
ibmmq-web-u9301/unknown,now 9.4.0.1 amd64 [installed]
ibmmq-xrservice-u9201/unknown,now 9.4.0.1 amd64 [installed]

Note the presence in each line of the following text, unknown, now.
4. Use the following Debian command to uninstall the product.

156 Installing and migrating IBM MQ

 This command removes the product, but leaves the package definition cached.

# apt remove "ibmmq-*-u9401*"

You receive messages similar to the following:

…
0 upgraded, 0 newly installed, 34 to remove and 78 not upgraded.
After this operation, 974 MB disk space will be freed.
Do you want to continue? [Y/n]
Y
…
Removing ibmmq-runtime-u9201 (9.4.0.1) ...
Entering prerm for "ibmmq-runtime-u9401" remove
Entering postrm for "ibmmq-runtime-u9401" remove

5. List the installed file sets again by issuing the command:

# apt list "ibmmq-*-u9401*"

You receive messages similar to the following:

ibmmq-amqp-u9201/unknown,now 9.4.0.1 amd64 [residual-config]

ibmmq-ams-u9201/unknown,now 9.4.0.1 amd64 [residual-config]
…
ibmmq-web-u9201/unknown,now 9.4.0.1 amd64 [residual-config]
ibmmq-xrservice-u9201/unknown,now 9.4.0.1 amd64 [residual-config]

Note the following statement at the end of each line, residual-config

6. Issue the following command to purge the cached definition of the product:

# apt purge "ibmmq-*-u9401*"

You receive messages similar to the following:

0 upgraded, 0 newly installed, 34 to remove and 78 not upgraded.

After this operation, 0 B of additional disk space will be used.
Do you want to continue? [Y/n]
Y
…
Purging configuration files for ibmmq-fttools-u9401 (9.4.0.1) ...
Entering postrm for "ibmmq-fttools-u9401" purge

7. List the installed file sets again by issuing the command:

# apt list "ibmmq-*-u9401*"

You receive messages similar to the following:

# apt list "ibmmq-*-u9401*"

Listing... Done
ibmmq-amqp-u9401/unknown 9.4.0.1 amd64
ibmmq-ams-u9401/unknown 9.4.0.1 amd64…
ibmmq-web-u9401/unknown 9.4.0.1 amd64
ibmmq-xrservice-u9401/unknown 9.4.0.1 amd64

Note the presence in each line of the following text, unknown instead of unknown, now.
8. Issue the command dspmqver and you see that the version is

# dspmqver
Name: IBM MQ
Version: 9.4.0.0

Installing and migrating 157

 Results
You have successfully uninstalled IBM MQ 9.4.0 Fix Pack 1.

What to do next
You can uninstall the base product if required. For more information, see “Uninstalling or modifying IBM
MQ on Linux Ubuntu using Debian packages” on page 154.
Related tasks
“Removing maintenance level updates on Windows” on page 318
From IBM MQ 9.4.0, you remove maintenance for server and client installations by uninstalling IBM MQ
and then reinstalling an earlier level.
Related reference
endmqm (end queue manager)
dspmqver (display version information)

Installing and uninstalling IBM MQ on Windows

Installation tasks that are associated with installing IBM MQ on Windows systems are grouped in this
section.

About this task

To prepare for installation and to install the IBM MQ components, complete the following tasks.
For information about how to uninstall IBM MQ, see “Uninstalling IBM MQ on Windows” on page 230.
If product fixes or updates are made available, see “Applying maintenance to IBM MQ” on page 278.

Procedure
1. Check the system requirements.
See “Checking requirements on Windows” on page 168.
2. Plan your installation.
• As part of the planning process, you must choose which components to install and where to install
them. See “IBM MQ features for Windows systems” on page 158.
• You must also make some platform-specific choices. See “Planning to install IBM MQ on Windows”
on page 170.
3. Install IBM MQ server.
See “Installing IBM MQ server on Windows” on page 176.
4. Optional: Install an IBM MQ client.
See “Installing an IBM MQ client on Windows” on page 203.
5. Verify your installation. See “Verifying an IBM MQ installation on Windows” on page 220.

IBM MQ features for Windows systems

You can select the features that you require when you install IBM MQ.
Important: For details of what each purchase of IBM MQ entitles you to install, see IBM MQ license
information.
If you choose an interactive installation, before you install, you must decide what type of installation you
require. For more information about the available types of installation and the features that are installed
with each option, see “Installation methods for Windows” on page 172.
The following table shows the features that are available when installing an IBM MQ server or client on a
Windows system.

158 Installing and migrating IBM MQ

Interactive Non-interactive
displayed name displayed name Description Server media Client media
Server Server You can use the
server to run
queue managers
on your system and
connect to other
systems over a
network. Provides
messaging and
queuing services
to applications,
and support for
IBM MQ client
connections.

From IBM MQ
9.1, additional
prerequisite
checking is
performed on
this option.
See Prerequisite
checking for more
information.

Managed File MFT Service The Managed File

Transfer Service Transfer Service
install option
installs a file
transfer agent that
has additional
capabilities beyond
those provided by
the file transfer
agent installed
using the Managed
File Transfer Agent
install option.
These additional
capabilities are:-
• Create protocol
bridge agents
which are used to
send and receive
files with legacy
FTP, FTPS or
SFTP servers
The Managed File
Transfer Service
install option must
be installed on
systems where the
IBM MQ Server
install option is
already installed.

Installing and migrating 159

 Interactive Non-interactive
displayed name displayed name Description Server media Client media
Managed File MFT Logger The Managed File
Transfer Logger Transfer Logger
install option
installs a file
transfer logger
which connects to
an IBM MQ queue
manager, often the
queue manager
designated as the
coordination queue
manager. It logs
file transfer audit
related data to
either a database
or a file. It must
be installed on
systems where the
IBM MQ Server
install option is
already installed.
Managed File MFT Agent The Managed File
Transfer Agent Transfer Agent
install option
installs a file
transfer agent
which connects to
an IBM MQ queue
manager and
transfers file data,
as messages, to
other file transfer
agents. These
must be installed
either as part
of the Managed
File Transfer Agent
or Managed File
Transfer Service
install options.

160 Installing and migrating IBM MQ

Interactive Non-interactive
displayed name displayed name Description Server media Client media
Managed File MFT Tools The Managed File
Transfer Tools Transfer Tools
install option
installs command
line tools that
are used to
interact with file
transfer agents.
You can use these
tools to start file
transfers, schedule
file transfers and
create resource
monitors from the
command line.
The Managed File
Transfer Tools can
be installed and
used on either a
system where file
transfer agents are
installed, or on a
system where no
file transfer agents
are installed.

IBM MQ MQI client Client The IBM MQ MQI

client is a small
subset of IBM MQ,
without a queue
manager, that uses
the queue manager
and queues on
other (server)
systems. It can be
used only when
the system it is
on is connected
to another system
that is running a
full server version
of IBM MQ. The
client and server
can be on the same
system if required.

Installing and migrating 161

 Interactive Non-interactive
displayed name displayed name Description Server media Client media
JavaMsg The files needed
Extended
for messaging
Messaging APIs
using Java. This
feature includes
support for JMS,
XMS, .NET, and
IBM MQ web
services.
From IBM MQ
9.1.0, this feature
is named Extended
Messaging APIs.
In earlier versions
of the product,
it was named
Java and .NET
Messaging and
Web Services.

Web Web Adds HTTP based

Administration administration for
IBM MQ through
the REST API and
IBM MQ Console.
This feature also
provides the
messaging REST
API, which you
can use to perform
simple point-to-
point and publish
messaging. You
can publish
messages to
a topic, send
messages to a
queue, browse
messages on
a queue, and
destructively get
messages from a
queue.
If you want to
install the Web
Administration
feature you
must also install
the Extended
Messaging APIs
(JavaMsg) feature.

162 Installing and migrating IBM MQ

Interactive Non-interactive
displayed name displayed name Description Server media Client media
Development Toolkit This feature
Toolkit includes sample
source files, and
the bindings
(files .H, .LIB, .DLL,
and others),
that you need
to develop
applications to
run on IBM
MQ. Bindings
and samples
are provided for
the following
languages: C, C++,
Visual Basic, Cobol,
and .NET (including
C#). Java and Java
Message Service
support is included
and samples
are provided for
MTS (COM+), and
MQSC.

Installing and migrating 163

 Interactive Non-interactive
displayed name displayed name Description Server media Client media
Telemetry Service XR Service MQ Telemetry
supports the
connection of
Internet Of Things
(IOT) devices (that
is, remote sensors,
actuators and
telemetry devices)
that use the
IBM MQ Telemetry
Transport (MQTT)
protocol. The
telemetry (MQXR)
service enables a
queue manager
to act as an
MQTT server, and
communicate with
MQTT client apps.
A set of MQTT
clients is available
from the Eclipse
Paho downloads
page. These
sample clients help
you write your
own MQTT client
apps that IOT
devices use to
communicate with
MQTT servers.
The XR Service
install option must
be installed on
systems where the
IBM MQ Server
install option is
already installed.
See also
“Installation
considerations for
MQ Telemetry” on
page 250.

164 Installing and migrating IBM MQ

Interactive Non-interactive
displayed name displayed name Description Server media Client media
Advanced Message AMS Provides a high
Security level of protection
for sensitive data
flowing through
the IBM MQ
network, while
not impacting the
end applications.
You must install
this component
on all IBM MQ
installations that
host queues you
want to protect.
You must install
the IBM Global
Security Kit (GSKit)
component on
any IBM MQ
installation that is
used by a program
that puts or gets
messages to or
from a protected
queue, unless you
are using only Java
client connections.
The AMS install
option must
be installed on
systems where the
IBM MQ Server
install option is
already installed.

Installing and migrating 165

 Interactive Non-interactive
displayed name displayed name Description Server media Client media
AMQP Service AMQP Install this
component to
make AMQP
channels available.
AMQP channels
support AMQP 1.0
APIs. You can use
AMQP channels
to give AMQP
applications access
to the enterprise-
level messaging
facilities provided
by IBM MQ.

The AMQP Service

install option must
be installed on
systems where the
IBM MQ Server
install option is
already installed.
The Java Runtime
Java Runtime JRE
Environment (JRE)
Environment
is a separate
feature.
The JRE feature
installs a JRE that
has been tailored
for IBM MQ use,
and is a required
feature for all other
features that use
Java. That is:
• IBM MQ Explorer
• Web
Administration
• Telemetry
Service
• AMQP Service
• Managed File
Transfer
Additional
prerequisite
checking is
performed on
this option.
See Prerequisite
checking for more
information.

166 Installing and migrating IBM MQ

Note: From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ installation package. It
remains available as a separate download, and can be installed from the stand-alone IBM MQ Explorer
download available from Fix Central. For more information, see Installing and uninstalling IBM MQ
Explorer as a stand-alone application on Linux and Windows.

Windows standard installation features

The following features are part of the Windows standard installation feature set. They are the features
installed by the GUI installer for a "typical installation".

Interactive displayed name Non-interactive Notes

displayed name
Server Server
Extended Messaging APIs JavaMsg Feature renamed at IBM MQ 9.1.0. It
was previously named Java and .NET
messaging and Web Services.
Web Administration Web Feature added at IBM MQ 9.1.0
Development Toolkit Toolkit
Java Runtime Environment JRE Feature added at IBM MQ 9.1.0. Prior
to IBM MQ 9.1.0, the JRE feature was
always installed.

When you install an IBM MQ server using msiexec, the features that are included in a typical installation
are added to the list of features that you specify in the ADDLOCAL directive.
If you specify ADDLOCAL="" all these features will be installed.
If you do not want specific features added, you must add those specific features to the REMOVE directive.
For example, suppose that you specify the following settings for an msiexec installation:

ADDLOCAL="Client"
REMOVE="Web,Toolkit"

This results in the following features being installed:

Server,JavaMsg,JRE,Client

Related concepts
“IBM MQ components and features” on page 6
You can select the components or features that you require when you install IBM MQ.
“Planning considerations for installation on Multiplatforms” on page 14
Before you install IBM MQ, you must choose which components to install and where to install them. You
must also make some platform-specific choices.
Related tasks
“Installing the server using the Launchpad” on page 177
You can install IBM MQ server on Windows systems by using the Launchpad. This procedure can be used
for installing a first or a subsequent installation.
“Installing the server using msiexec” on page 179

Installing and migrating 167

 IBM MQ on Windows uses the MSI technology to install software. MSI provides both an interactive
installation and a non interactive installation.

Checking requirements on Windows

Before you install IBM MQ on Windows, you must check for the latest information and system
requirements.

About this task

A summary of the tasks that you must complete to check system requirements are listed here with links
to further information.

Procedure
1. Check that you have the latest information, including information on hardware and software
requirements.
See “Where to find product requirements and support information” on page 9.
2. Check that your systems meet the initial hardware and software requirements for Windows.
See “Hardware and software requirements on Windows systems” on page 168.
3. Check that your systems have sufficient disk space for the installation.
See Disk space requirements.
4. Check that you have the correct licenses.
See “License requirements” on page 8 and IBM MQ license information.
Related concepts
“IBM MQ installation overview” on page 6
An overview of concepts and considerations for installing IBM MQ, with links to instructions on how to
install, verify, and uninstall IBM MQ on each of the supported platforms.
Related tasks
“Applying maintenance to IBM MQ” on page 278
Maintenance is the application of a reversible fix. Any changes to queue manager data are compatible
with the previous code level.

Hardware and software requirements on Windows systems

Check that the server environment meets the prerequisites for installing IBM MQ for Windows and install
any prerequisite software that is missing from your system.
Before you install IBM MQ, you must check that your system meets the hardware and software
requirements.
You must also review the product readme file, which includes information about last-minute changes and
known problems and workarounds. For the latest version of the product readme file, see the IBM MQ,
WebSphere MQ, and MQSeries product readmes web page.

Supported versions of Windows

For a list of the supported versions of the Windows operating system, see the System Requirements for
IBM MQ website and follow the links to the Detailed System Requirements report for Windows. There are
separate reports for Long Term Support and Continuous Delivery.
Although IBM MQ 9.1, and later, no longer supports some earlier versions of the Windows operating
system referred to in the documentation, these earlier versions of Windows might still be supported for an
earlier version of IBM MQ installed in the same domain as an IBM MQ 9.1 or later installation.

168 Installing and migrating IBM MQ

Changes to Windows features in Windows 10
The names of some of the Windows features have changed in Windows 10:
• Windows Explorer is File Explorer
• My Computer is called This PC
• The way in which you start the Control Panel is different
• The default browser is Microsoft Edge.
Note: The IBM MQ Console supports only the following browsers:
– Microsoft Edge
– Google Chrome
– Mozilla Firefox

Storage requirements for IBM MQ server

The storage requirements depend on which components you install, and how much working space you
need. The storage requirements also depend on the number of queues that you use, the number and
size of the messages on the queues, and whether the messages are persistent. You also require archiving
capacity on disk, tape, or other media. For more information, see System Requirements for IBM MQ.
Disk storage is also required:
• Prerequisite software
• Optional software
• Your application programs

Requirements for IBM MQ Explorer

From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ installation package. It
remains available as a separate download, and can be installed from the stand-alone IBM MQ Explorer
download available from Fix Central. For more information, see Installing and uninstalling IBM MQ
Explorer as a stand-alone application on Linux and Windows.
For more information about the requirements for the stand-alone IBM MQ Explorer, see IBM MQ Explorer
installation requirements.
For further information about Windows requirements, see IBM MQ Explorer Requirements.

Requirements for IBM MQ classes for .NET

The following prerequisites apply to IBM MQ classes for .NET:
• .NET Core 2.1 is a prerequisite to use IBM MQ classes for .NET Standard, for developing .NET Core
applications.
• .NET Framework V4.7.1 is a prerequisite to use IBM MQ classes for .NET Standard, for developing .NET
Framework applications.

• From IBM MQ 9.4.0, for .NET 6 IBM MQ client libraries, that is libraries built using .NET 6
as the target framework, .NET 6 is a prerequisite.

Installation directories used for Windows operating systems

The 64-bit IBM MQ server or client, by default, installs its program directories into the 64-bit installation
location: C:\Program Files\IBM\MQ.
Attention: There is no separate 32-bit client installation package. The client installation package
and redistributable client contain both 32-bit and 64-bit IBM MQ client libraries. The included

Installing and migrating 169

 32-bit libraries can be used by 32-bit applications on supported platforms where 32-bit support is
offered by the operating system.
The default data directory that is used by IBM MQ changed in IBM MQ 8.0 to C:\ProgramData\IBM\MQ.
This change affects both servers, in 32 and 64 bits and clients in 64 bits. However, if there has been
a previous installation of IBM MQ on the machine on which you are installing, the new installation
continues to use the existing data directory location. For more information, see “Program and data
directory locations on Windows” on page 376.

Installing prerequisite software

To install the prerequisite software that is provided in the IBM MQ server installation image, choose one of
the following options:
• Navivate to the root of the server installation image, then double-click setup.exe. The IBM MQ
Installation Launchpad window is displayed. From this window, click the Software Prerequisites
option. Use this option to check what prerequisite software is already installed, then install any missing
software.
• Navigate to the Prereqs folder of the server installation image. Select the folder for the software item
to be installed, then start the installation program.
Related concepts
“Hardware and software requirements on Linux systems” on page 94
Before you install IBM MQ, check that your system meets the hardware and operating system software
requirements for the particular components you intend to install.
“Hardware and software requirements on IBM i systems” on page 62
Check that the server environment meets the prerequisites for installing IBM MQ for IBM i.
Related tasks
“Checking requirements on Windows” on page 168
Before you install IBM MQ on Windows, you must check for the latest information and system
requirements.
Related reference
IBM MQ Explorer Requirements

Planning to install IBM MQ on Windows

Before you install IBM MQ on Windows, you must choose which components to install and where to install
them. You must also make some platform-specific choices.

About this task

The following steps provide links to additional information to help you with planning your installation of
IBM MQ on Windows.
As part of your planning activities, make sure that you review the information on hardware and software
requirements for the platform on which you are planning to install IBM MQ. For more information, see
“Checking requirements on Windows” on page 168.

Procedure
1. Decide which IBM MQ components and features to install.
See “IBM MQ components and features” on page 6 and “Where to find downloadable installation
images” on page 9.
Important: Ensure that your enterprise has the correct license, or licenses, for the components that
you are going to install. For more information, see “License requirements” on page 8 and IBM MQ
license information.
2. Review the options for naming your installation.

170 Installing and migrating IBM MQ

 In some cases, you can choose an installation name to use instead of the default name. See
“Installation name on AIX, Linux, and Windows” on page 14.
3. Review the options and restrictions for choosing an installation location for IBM MQ.
For more information, see “Installation location on Multiplatforms” on page 15.
4. If you plan to install multiple copies of IBM MQ, see “Multiple installations on AIX, Linux, and
Windows” on page 17.
5. If you already have a primary installation, or plan to have one, see “Primary installation on AIX, Linux,
and Windows” on page 18.
6. Make sure that the communications protocol needed for server-to-server verification is installed and
configured on both systems that you plan to use.
For more information, see “Server-to-server links on AIX, Linux, and Windows” on page 26.
7. Determine whether you need to install the Java runtime environment (JRE).
If you are not using Java in your messaging applications, and you are not using portions of IBM MQ that
are written in Java, you have the option to not install the JRE (or to remove the JRE if it was already
installed).

Attention: If you choose not to install the JRE, or to remove the JRE if it was already installed:
• You must use the runmqakm command to manage key repositories. The runmqktool
command is not available.
• Use of the runmqras command fails unless a JRE at version 7, or later, is available on the
system path.
For more information, see runmqakm and runmqktool commands on AIX, Linux, and Windows.

Additional Windows features prerequisite checking

There are two Windows installation features that have additional prerequisite checking enabled in the
Windows IBM MQ installer from IBM MQ 9.1. These are the Server feature and the Java Runtime
Environment (JRE) feature. These features are required by other features and installing those features,
without these prerequisite checks, would cause those features to be unusable.
If you perform a Graphical User Interface installation, and select the custom install option, you can
deselect the JRE or Server features.
Attention: Dialog panels prevent you from completing the installation, until you have resolved any
issues.
If you perform a silent installation, and you elect to REMOVE the Server or JRE features while installing
any other features that require those features, the Server and JRE features, as appropriate, will be
added to your selected installation features.
Table 20 on page 171 describes how the selection of certain installation features requires the Server or
JRE to be added automatically.

Table 20. Installation features requiring either the Server or JRE feature
Feature Required by Non-interactive name
Server Web Administration Web

JRE Telemetry Service XR Service

Managed File Transfer Service MFT Service
Managed File Transfer Agent MFT Agent
Managed File Transfer Logger MFT Logger
Managed File Transfer Tools MFT Tools
AMQP Service AMQP Service
Web Administration Web

Installing and migrating 171

 To check whether the JRE or Server features have been installed, look in the [INSTALLDIR]\swidtag
directory. If the:
• ibm.com_IBM_MQ-9.0.x.swidtag file is present, the Server has been installed
• IBM_MQ_JRE-1.8.0.mqtag file is present, the JRE has been installed.
If this is not what you require, consult the installation log.
Important: Each of the JRE and Server features are part of the set of Windows standard IBM MQ
installation features. To remove the JRE (or the Server) when installing silently, add the feature to the
REMOVE directive, do not merely omit it from the ADDLOCAL directive. See “Windows standard installation
features” on page 167 for further details.

Installation methods for Windows

When you install IBM MQ on Windows, there are several different installation types to choose from. This
topic also describes how you can clear the installation settings of your enterprise, including the use of the
ResetMQ command script.
If you are migrating from an earlier version of IBM MQ, see “Planning to migrate IBM MQ to a later version
on Windows” on page 373. To modify an existing installation, see “Modifying a server installation” on page
201.

Interactive or non-interactive installation

IBM MQ for Windows is installed using the Microsoft Installer (MSI). You can use the Installation
Launchpad to invoke MSI, this process is called an attended or interactive installation. Alternatively, you
can invoke MSI directly for a silent installation, without using the IBM MQ Installation Launchpad. This
means that you can install IBM MQ on a system without interaction. This process is called unattended,
silent, or non-interactive installation, and is useful for installing IBM MQ over a network on a remote
system.
For a list of interactive and non-interactive features, see “IBM MQ features for Windows systems” on page
158.

Interactive installation
If you choose an interactive installation, before you install, you must decide what type of installation you
require. Table 21 on page 173 shows the installation types available, and the features that are installed
with each option. For the prerequisites required for each feature, see System Requirements for IBM MQ.
The installation types are:
• Typical installation
• Compact installation
• Custom Installation
You can also:
• Specify the installation location, name, and description.
• Have multiple installations on the same computer.
See “Primary installation on AIX, Linux, and Windows” on page 18 for important information about these
features, including whether to designate your installation as the primary installation.

172 Installing and migrating IBM MQ

Table 21. Features installed with each type of interactive installation
Installation Server Features installed Client Features installed Comments
type
Typical • Server • MQI Client The default option. Features
are installed to default
• Development Toolkit • Development Toolkit locations with a default
• Extended Messaging APIs • Extended Messaging APIs installation name.
• Web Administration Extended Messaging APIs
(known as Java and .NET
Messaging and Web Services
before IBM MQ 9.1) includes
IBM MQ classes for .NET,
support for the Microsoft
Windows Communication
Foundation (WCF) for use with
Microsoft.NET 3.

Compact • Server only • MQI Client only The feature is installed to the
default location with a default
installation name.
Custom By default, the following By default, the following A server custom installation
features are preselected: features are preselected: can be used if you want to
install the IBM MQ MQI client
• Server • MQI Client
from within the server image.
• Development Toolkit • Development Toolkit
All the available features are
• Extended Messaging APIs • Extended Messaging APIs listed and you can select
• Web Administration which ones to install, and
where to install them. You
A custom installation can also
can also name and provide a
install:
description for the installation.
• Telemetry Service
Use a custom installation when
• Advanced Message Security you want to specify that the
• Managed File Transfer installation is primary.
Service Extended Messaging APIs
• Managed File Transfer (known as Java and .NET
Logger Messaging and Web Services
• Managed File Transfer Agent before IBM MQ 9.1) includes
IBM MQ classes for .NET,
• Managed File Transfer Tools support for the Microsoft
• MQI Client Windows Communication
Foundation (WCF) for use with
Microsoft.NET 3 or later.

If Microsoft.NET is not installed before IBM MQ and you add it, rerun setmqinst -i -n
Installationname if this is a primary installation.
The following table describes which level of .NET is required for which function:

Table 22. Required levels of Microsoft.NET

IBM MQ function .NET version required
IBM MQ classes for .NET. For more information, Microsoft .NET 6.0
see: Installing IBM MQ classes for .NET

Installing and migrating 173

 Table 22. Required levels of Microsoft.NET (continued)
IBM MQ function .NET version required
The IBM MQ custom channel for WCF. For more .NET framework 4.7.2 or later
information, see Developing WCF applications with
IBM MQ.
To build the sample solution files, either the
Microsoft.NET 4.7.2 or later SDK, or Microsoft
Visual Studio 2015 is needed. For more
information, see: Software requirements for the
WCF custom channel for IBM MQ

For instructions on how to install IBM MQ on Windows systems, see Installing IBM MQ Server on Windows
systems and “Installing an IBM MQ client on Windows” on page 203.

Non-interactive installation
If you choose a non-interactive installation the system on which you want to install must be able to access
the IBM MQ image, or a copy of the files, and you must be able to access the system.
If you are running with User Account Control (UAC) enabled, you must invoke the non-interactive
installation from an elevated command prompt. Elevate a command prompt by using a right-click to start
the command prompt and choose Run as administrator. If you try to silently install from a non-elevated
command prompt, the installation fails with an error of AMQ4353 in the installation log.
There are several ways to invoke MSI:
• Using the msiexec command with command-line parameters.
• Using the msiexec command with a parameter that specifies a response file. The response file contains
the parameters that you normally supply during an interactive installation. See “Installing the server
using msiexec” on page 179.
• Use the MQParms command with command-line parameters, a parameter file, or both. The parameter
file can contain many more parameters than a response file. See “Installing the server using the
MQParms command” on page 188.

Special domain ID
If the system belongs to a Windows domain you may need a special domain ID for the IBM MQ service,
see “Considerations when installing IBM MQ server on Windows” on page 175 for more information.

Clearing IBM MQ installation settings

When you install IBM MQ on Windows, various values, such as the location of the data directory for IBM
MQ, are stored in the registry.
In addition, the data directory contains configuration files that are read at installation time. To provide
a trouble free re-installation experience, these values and files persist even after the last IBM MQ
installation has been removed from the machine.
This is designed to assist you, and
• Allows you to easily uninstall and reinstall
• Ensures that you do not lose any previously defined queue managers in the process.
However in some cases this feature can be an annoyance. For example, if you want to:
• Move the data directory
• Pick up the default data directory for the new release that you want to install. For more information, see
“Program and data directory locations on Windows” on page 376.

174 Installing and migrating IBM MQ

• Install as if installing on a new machine, for example, for test purposes.
• Remove IBM MQ permanently.
To assist you in these situations, IBM MQ supplies a Windows command file, on the root directory of the
installation media, called ResetMQ.cmd.
To run the command, enter the following:

ResetMQ.cmd [LOSEDATA] [NOPROMPT]

Attention: The parameters LOSEDATA and NOPROMPT are optional. If you supply either, or both, of
these parameters, the following action results:
LOSEDATA
Existing queue managers become unusable. However, the data remains on disk.
NOPROMPT
Configuration information is permanently removed without further prompting.
You can run this command only after the last IBM MQ installation has been removed.
Important: You should use this script with caution. The command, even without specifying the optional
parameter LOSEDATA, can irrecoverably remove queue manager configuration.
Related concepts
“Considerations when installing IBM MQ server on Windows” on page 175
There are some considerations relating to security that you should take into account when installing an
IBM MQ server on Windows. There are some additional considerations relating to the object naming rules
and logging.

Considerations when installing IBM MQ server on Windows

There are some considerations relating to security that you should take into account when installing an
IBM MQ server on Windows. There are some additional considerations relating to the object naming rules
and logging.

Security considerations when installing IBM MQ server on a Windows system

• If you are installing IBM MQ on a Windows domain network running Active Directory Server, you
probably need to obtain a special domain account from your domain administrator. For further
information, and the details that the domain administrator needs to set up this special account, see
“Configuring IBM MQ with the Prepare IBM MQ Wizard” on page 194 and “Creating and setting up
Windows domain accounts for IBM MQ” on page 198.
• When you are installing IBM MQ server on a Windows system you must have local administrator
authority. In order to administer any queue manager on that system, or to run any of the IBM MQ control
commands your user ID must belong to the local mqm or Administrators group . If the local mqm
group does not exist on the local system, it is created automatically when IBM MQ is installed. A user
ID can either belong to the local mqm group directly, or belong indirectly through the inclusion of global
groups in the local mqm group. For more information, see Authority to administer IBM MQ on UNIX,
Linux, and Windows.
• Windows versions with a User Account Control (UAC) feature restricts the actions users can perform on
certain operating system facilities, even if they are members of the Administrators group. If your user
ID is in the Administrators group but not the mqm group you must use an elevated command prompt to
issue IBM MQ admin commands such as crtmqm, otherwise the error AMQ7077 is generated. To open
an elevated command prompt, right-click the start menu item, or icon, for the command prompt, and
select Run as administrator.
• Some commands can be run without being a member of the mqm group (see Authority to administer IBM
MQ on UNIX, Linux, and Windows).

Installing and migrating 175

 • As with other versions of Windows, the object authority manager (OAM) gives members of the
Administrators group the authority to access all IBM MQ objects even when User Account Control is
enabled.
• If you intend to administer queue managers on a remote system, your user ID must be authorized
on the target system. If you need to perform any of these operations on a queue manager when
connected remotely to a Windows machine, you must have the Create global objects user
access. Administrators have the Create global objects user access by default, so if you are an
administrator you can create and start queue managers when connected remotely without altering your
user rights. For more information, see Authorizing users to use IBM MQ remotely.
• If you use the highly secure template, you must apply it before installing IBM MQ. If you apply the highly
secure template to a machine on which IBM MQ is already installed, all the permissions you have set on
the IBM MQ files and directories are removed (see Applying security template files on Windows).

Naming considerations
Windows has some rules regarding the naming of objects created and used by IBM MQ. These naming
considerations apply to IBM MQ 8.0 or later.
• Ensure that the machine name does not contain any spaces. IBM MQ does not support machine names
that include spaces. If you install IBM MQ on such a machine, you cannot create any queue managers.
• For IBM MQ authorizations, names of user IDs and groups must be no longer than 64 characters (spaces
are not allowed).
• An IBM MQ for Windows server does not support the connection of an IBM MQ MQI client if the client is
running under a user ID that contains the @ character, for example, abc@d. Similarly, the client user ID
should not be the same as local group.
• A user account that is used to run the IBM MQ Windows service is set up by default during the
installation process; the default user ID is MUSR_MQADMIN. This account is reserved for use by IBM
MQ. For more information, see Configuring user accounts for IBM MQ and Local and domain user
accounts for the IBM MQ Windows service.
• When an IBM MQ client connects to a queue manager on the server, the username under which the
client runs must not be same as the domain or machine name. If the user has the same name as the
domain or machine, the connection fails with return code 2035(MQRC_NOT_AUTHORIZED).

Logging
You can set up logging during installation which assists you in troubleshooting any problems you might
have with the installation.
Logging is enabled by default from the Launchpad. You can also enable complete logging, for more
information, see How to enable Windows Installer logging.

Digital signatures
The IBM MQ programs and installation image are digitally signed on Windows to confirm that they are
genuine and unmodified. The SHA-256 with RSA algorithm is used to sign the IBM MQ product.

Installing IBM MQ server on Windows

On Windows, IBM MQ is installed by using the Microsoft Installer (MSI). You can either use the
Installation Launchpad to invoke MSI or alternatively, you can invoke MSI directly.

About this task

To install IBM MQ server on Windows systems, you can choose either to install interactively with the
Launchpad or to install by using MSI technology directly. MSI provides both an interactive installation and
a non interactive installation.

176 Installing and migrating IBM MQ

For more information on installation options, see “Installation methods for Windows” on page 172.

Procedure
• To install IBM MQ server by using the Launchpad, see “Installing the server using the Launchpad” on
page 177.
• To install IBM MQ server on by using the MSI technology directly, see “Installing the server using
msiexec” on page 179.
Related concepts
“Modifying a server installation” on page 201
You can modify an IBM MQ server installation interactively using the launchpad or non-interactively using
msiexec.
Related tasks
“Configuring user accounts for IBM MQ” on page 194
After installing IBM MQ server, you must configure the IBM MQ service before you can start any queue
managers.
“Uninstalling IBM MQ on Windows” on page 230
You can uninstall the IBM MQ MQI clients and servers on Windows systems by using the control panel,
the command line ( msiexec ), MQParms, or by using the installation media, in which case you can
optionally remove queue managers as well.

Installing the server using the Launchpad

You can install IBM MQ server on Windows systems by using the Launchpad. This procedure can be used
for installing a first or a subsequent installation.

About this task

You can use the Launchpad to make a compact, typical, or custom installation of IBM MQ. You can reuse
the launchpad multiple times to install further installations. It automatically selects the next available
installation name, instance, and location to use. To view all the installation types and the features that are
installed with each option, see “Installation methods for Windows” on page 172.
Note that if you have previously uninstalled IBM MQ from your system (see “Uninstalling IBM MQ on
Windows” on page 230 ), some configuration information might remain, and some default values might be
changed.
From IBM MQ 9.3.0, a new Confirm License Entitlement panel in the Windows interactive installer
is presented after feature selection if you have chosen to install any IBM MQ Advanced features (MQ
Telemetry Service, Advanced Message Security, or Managed File Transfer Service), or if you are upgrading
from an installation that already has these features.
This panel simply warns you that these features are considered IBM MQ Advanced functionality and
should only be installed if you have entitlement to IBM MQ Advanced. This warning reduces the risk of
users installing IBM MQ Advanced features on a machine in error.
Note: The Confirm License Entitlement panel applies to production server builds and not to clients, beta
builds, trial builds or developer (non-warranty) builds.

Procedure
1. Access the IBM MQ installation image.
The location might be a network location, or a local file system directory. See Where to find
downloadable installation images.
2. Locate Setup.exe in the base directory of the IBM MQ installation image.
• From a network location, this location might be m:\instmqs\Setup.exe
• From a local file system directory, this location might be C:\instmqs\Setup.exe

Installing and migrating 177

 3. Start the installation process.
Either run Setup.exe from a command prompt, or double-click Setup.exe from Windows Explorer.
Note: If you are installing on a Windows system with UAC enabled, accept the Windows prompt to
allow the launchpad to run as elevated. During installation, you might also see Open File - Security
Warning dialog boxes that list International Business Machines Limited as the publisher. Click Run to
allow the installation to continue.
The IBM MQ Installation window is displayed.
4. Follow the instructions on screen. Review, and if necessary, modify the software requirements and
network configuration.
5. On the IBM MQ Installation tab of the Launchpad, select the installation language, and then click
Launch IBM MQ Installer to start the IBM MQ installation wizard.
6. Use the IBM MQ installation wizard to install the software.
If you select any IBM MQ Advanced features and the Confirm License Entitlement panel then
appears:
• If you do have an IBM MQ Advanced license, simply select Yes (I have an MQ Advanced license)
and Next to continue with the installation.
• If you do not have an IBM MQ Advanced license and do not intend to purchase one, click Back and
change your feature selections.
Depending on your system the installation process can take several minutes. At the end of the
installation process, the IBM MQ Setup window displays the message Installation Wizard
Completed Successfully.
When this message appears, click Finish.

Results
You have successfully installed IBM MQ. The Prepare IBM MQ wizard starts automatically, displaying the
Welcome to the Prepare IBM MQ Wizard page.

What to do next
Use the Prepare IBM MQ Wizard to configure IBM MQ with a user account for your network. You must
run the wizard to configure the IBM MQ Service before you can start any queue managers. For more
information, see “Configuring IBM MQ with the Prepare IBM MQ Wizard” on page 194.
• If you have chosen this installation to be the primary installation on the system, you must now set it as
the primary installation. Enter the following command at the command prompt:

MQ_INSTALLATION_PATH\bin\setmqinst -i -p MQ_INSTALLATION_PATH

You can have only one primary installation on a system. If there is already a primary installation on the
system, you must unset it before you can set another installation as the primary installation. For more
information, see Changing the primary installation.
• You might want to set up the environment to work with this installation. You can use the setmqenv or
crtmqenv command to set various environment variables for a particular installation of IBM MQ. For
more information, see setmqenv and crtmqenv.
• For instructions on how to verify your installation, see “Verifying an IBM MQ installation on Windows” on
page 220.
Related concepts
“Modifying a server installation” on page 201

178 Installing and migrating IBM MQ

You can modify an IBM MQ server installation interactively using the launchpad or non-interactively using
msiexec.
Related tasks
“Installing the server using msiexec” on page 179
IBM MQ on Windows uses the MSI technology to install software. MSI provides both an interactive
installation and a non interactive installation.
“Configuring user accounts for IBM MQ” on page 194
After installing IBM MQ server, you must configure the IBM MQ service before you can start any queue
managers.
“Uninstalling IBM MQ on Windows” on page 230
You can uninstall the IBM MQ MQI clients and servers on Windows systems by using the control panel,
the command line ( msiexec ), MQParms, or by using the installation media, in which case you can
optionally remove queue managers as well.

Installing the server using msiexec

IBM MQ on Windows uses the MSI technology to install software. MSI provides both an interactive
installation and a non interactive installation.

Before you begin

If you are running IBM MQ on Windows systems with User Account Control (UAC) enabled, you
must invoke the installation with elevated privileges. If you are using the Command prompt or IBM
MQ Explorer, you elevate privileges by using a right-click to start the program and selecting Run as
administrator. If you try to run msiexec without using elevated privileges, the installation fails with an
error of AMQ4353 in the installation log.

About this task

IBM MQ on Windows uses the MSI technology to install software. MSI provides both an interactive
installation and a non interactive installation. An interactive installation displays panels and ask
questions.
The msiexec command uses parameters to give MSI some or all of the information that can also be
specified through panels during an interactive installation. This means that a user can create a reusable
automated or semi-automated installation configuration. Parameters can be given through the command
line, a transform file, a response file, or a combination of the three.
Some parameters can only be provided on the command line and not in a response file. For more
information about these parameters, see Table 23 on page 181 in “Specifying command line parameters
for server installation with msiexec” on page 181.
There are also a number of parameters can be used either on the command line or in a response file. For
more information about these parameters, see Table 25 on page 184 in “Creating and using a response
file for server installation” on page 184. If a parameter is specified both on the command line and in a
response file, the setting on the command line takes precedence.

Procedure
1. For multiple silent installations, for each version that is to be installed, find an MSI instance ID that is
available to use for that installation.
For more information, see “Choosing MSI Instance IDs for multiple client installations” on page 205.
2. To install using msiexec, at the command line, enter the msiexec command in the following format:

msiexec parameters [USEINI="response-file"] [TRANSFORMS="transform_file"]

where:

Installing and migrating 179

 parameters
are either command-line parameters preceded by a / character, or property=value pairs. If you
are using both forms of parameter, always put the command-line parameters first. For more
information, see “Specifying command line parameters for server installation with msiexec” on
page 181, which contains a link to the website that lists all the command line parameters that are
available.
For an unattended installation, you must include the /q or /qn parameter in the command line.
Without this parameter, the installation is interactive.
Note: You must include the /i parameter and the file location of the IBM MQ installer package.
response-file
is the full path and file name of the file that contains the [Response] stanza and the
required property=value pairs, for example C:\MyResponseFile.ini. An example response file,
Response.ini, is supplied with IBM MQ. This file contains default installation parameters. For
more information, see “Creating and using a response file for server installation” on page 184.
transform_file
is the full path and file name of a transform file. For more information, see “Using transforms with
msiexec for server installation” on page 183 and “Choosing MSI Instance IDs for multiple server
installations” on page 180.
Note: For a silent installation to succeed, the AGREETOLICENSE="yes" property must be defined
either on the command line or in the response file.

Results
After the command has been entered, the command prompt immediately reappears. IBM MQ is installing
as a background process. If you have entered parameters to produce a log, check this file to see
how the installation is progressing. If the installation completes successfully, you see the message
Installation operation completed successfully in the log file.

Choosing MSI Instance IDs for multiple server installations

For multiple silent installations, for each version that is installed you must find an MSI instance ID that is
available to use for that installation.

About this task

In order to support silent, or non-interactive, multiple installations, you need to find out whether the
instance ID you want to use is already in use or not and choose the appropriate one. For each installation
media (for example, each client and server), Instance ID 1 is the default ID which is used for single
installations. If you want to install alongside Instance ID 1 you need to specify which instance you want
to use. If you have already installed instance 1, 2, and 3 then you need to find out what the next available
instance is, for instance, Instance ID 4. Similarly, if instance 2 has been removed, you need to find out
that there is a gap that can be reused. You can find out which Instance ID is currently in use by using the
dspmqinst command.

Procedure
1. Type dspmqinst to find a free MSI Instance in the media being installed by reviewing the MSIMedia
and MSIInstanceId values for the versions already installed. For example:

InstName: Installation1
InstDesc:
Identifier: 1
InstPath: C:\Program Files\IBM\MQ
Version: 9.0.0.0
Primary: Yes
State: Available
MSIProdCode: {74F6B169-7CE6-4EFB-8A03-2AA7B2DBB57C}
MSIMedia: 9.0 Server
MSIInstanceId: 1

180 Installing and migrating IBM MQ

2. If MSI Instance ID 1 is in use and you want to use MSI Instance ID 2, the following parameters must
be added to the msiexec call:

MSINEWINSTANCE=1 TRANSFORMS=":instanceId7.mst;1033.mst"

What to do next
For multiple installations, the INSTALLATIONNAME or PGMFOLDER must be supplied as an additional
parameter on any non-interactive installation command. Supplying the INSTALLATIONNAME or
PGMFOLDER ensures that you do not work with the wrong installation in case you omit or incorrectly
specify the TRANSFORMS parameter.

Specifying command line parameters for server installation with msiexec

You can specify either standard msiexec command line parameters preceded by a / character, or
property=value pairs, or a combination of both.

About this task

The msiexec command can accept the following types of parameter on the command line:
Standard command line parameters, preceded by a / character
For more information about the msiexec command line parameters, see the MSDN Command-Line
Options web page.
For an unattended installation, you must include the /q or /qn parameter in the command line.
Without this parameter, the installation is interactive.
Note: You must include the /i parameter and the file location of the IBM MQ installer package.
Property=value pair parameters entered on the command line
All the parameters that are available for use in a response file can also be used on the command line.
For more information about these parameters, see Table 25 on page 184 in “Creating and using a
response file for server installation” on page 184.
There are some extra property=value pair parameters, shown in the following table, that are only for
use on the command line:

Table 23. Parameters that can be used on the command line only (msiexec property=value
parameters)
Property Values Meaning
USEINI path \ file_name Use the specified response file. See “Creating
and using a response file for server installation”
on page 184
SAVEINI path \ file_name Generate a response file during installation. The
file contains those parameters selected for this
installation that a user might make during an
interactive installation.
ONLYINI 1|yes| "" 1, yes or any value other than null. End the
installation before updating the target system,
but after generating a response file, if this is
specified.
"". Continue the installation and update the
target system (the default).

Installing and migrating 181

 Table 23. Parameters that can be used on the command line only (msiexec property=value
parameters) (continued)
Property Values Meaning
TRANSFORMS :InstanceId x.mst| path \ The :InstanceId x.mst value is only required for
file_name | a subsequent installation of IBM MQ. The path
:InstanceId x.mst; path \ \ file_name specifies what transform (.mst) files
file_name must be applied to the product. For example,
"1033.mst" specifies the supplied U.S. English
transform file.
MSINEWINSTAN 1 This property is only required for subsequent
CE installations of IBM MQ

When using the property=value pair parameters note that:

• Property strings must be in uppercase.
• Value strings are not case-sensitive, except for feature names. You can enclose value strings in double
quotation marks. If a value string includes a blank, enclose the blank value string in double quotation
marks.
• For a property that can take more than one value, use the format:

ADDLOCAL="Server,Client"

• For properties taking paths and file names, for example, PGMFOLDER, you must supply the paths as
absolute paths and not relative paths; that is as C:\folder\file and not ".\folder\file".
When using property=value pair and command line parameters with the msiexec command, enter
command line parameters first.
If a parameter is specified both on the command line and in a response file, the setting on the command
line takes precedence.

Procedure
• For a single installation of IBM MQ, specify the msiexec command as shown in the following typical
example.
All parameters, separated by one or more spaces, must be typed on the same line as the msiexec
call.

msiexec
/i "path\MSI\IBM MQ.msi"
/l*v c:\install.log
/q
TRANSFORMS="1033.mst"
AGREETOLICENSE="yes"
ADDLOCAL="Server"

• If you are installing a second copy of IBM MQ, specify the msiexec command as shown in the
following typical example.
All parameters, separated by one or more spaces, must be typed on the same line as the msiexec
call.

msiexec
/i "path\MSI\IBM MQ.msi"
/l*v c:\install.log
/q
TRANSFORMS=":InstanceId2.mst;1033.mst"
AGREETOLICENSE="yes"

182 Installing and migrating IBM MQ

 ADDLOCAL="Server"
MSINEWINSTANCE=1

where /l*v c:\install.log writes installation log to file c:\install.log.

Using transforms with msiexec for server installation

MSI can use transforms to modify an installation. During IBM MQ installation, transforms can be used to
support different national languages.

About this task

IBM MQ is supplied with transform files in the \MSI folder of the Server image. These files are also
embedded in the IBM MQ Windows installer package, IBM MQ.msi.
Table 24 on page 183 shows the locale identifier, language, and the transform file name to use in the
msiexec command line.

Table 24. Supplied transform files for various language support

Language Transform File name Value
U.S. English 1033.mst 1033
German 1031.mst 1031
French 1036.mst 1036
Spanish 1034.mst 1034
Italian 1040.mst 1040
Brazilian Portuguese 1046.mst 1046
Japanese 1041.mst 1041
Korean 1042.mst 1042
Simplified Chinese 2052.mst 2052
Traditional Chinese 1028.mst 1028
Czech 1029.mst 1029
Russian 1049.mst 1049
Hungarian 1038.mst 1038
Polish 1045.mst 1045

You can also specify the required language by using the MQLANGUAGE property with the MQParms
command. For information about the msiexec property=value parameters, see “MQParms parameter file -
server installation” on page 189.

Procedure
On the msiexec command line, specify the required language by using the TRANSFORMS property in a
property=value pair as shown in the following example:

TRANSFORMS="1033.mst"

The quotation marks surrounding the value are optional.

You can also specify the full path and file name of the transform file. Again, the quotation marks
surrounding the value are optional. For example:

Installing and migrating 183

 TRANSFORMS="D:\Msi\1033.mst"

You might need to merge transforms to install multiple installations of the same version, for example:

TRANSFORMS=":InstanceId2.mst;D:\Msi\1033.mst"

Creating and using a response file for server installation

You can use the msiexec command with a parameter that specifies additional properties that are defined
in a response file. There are three ways of creating a response file for a server installation.

About this task

A response file is an ASCII text file with a format like a Windows .ini file, that contains the stanza
[Response]. The [Response] stanza contains some or all the parameters that would normally be specified
as part of an interactive installation. The parameters are given in a property=value pair format. Any other
stanzas in the response file are ignored by msiexec.
An example response file, Response.ini, is supplied with IBM MQ. It contains the default installation
parameters.
You can combine the use of a response file with msiexec command-line parameters described in
“Specifying command line parameters for server installation with msiexec” on page 181.
Table 25 on page 184 shows the parameters that are available for use in a response file. These
parameters can also be used on the command line. If a parameter is specified both on the command
line and in a response file, the setting on the command line takes precedence.

Table 25. Parameters that can be used in a response file

Property Values Meaning
PGMFOLDER“1” on page 186 path Folder for the IBM MQ program files. For
example, c:\mqm.
DATFOLDER path Folder for the IBM MQ data files. For example,
c:\mqm\data.
Note: Multiple installations of IBM MQ all use
the same DATFOLDER.

LOGFOLDER path Folder for the IBM MQ queue manager log files.
For example, c:\mqm\log.
Note: Multiple installations of IBM MQ all use
the same LOGFOLDER.

USERCHOICE 0|no If the command line or response file specifies

parameters to install features, a dialog can be
displayed to prompt the user to accept the
preselected options, or review and possibly
change them.
0 or no. Suppresses display of the dialog.
Anything else. Dialog is displayed.
Not used for a silent installation.

184 Installing and migrating IBM MQ

Table 25. Parameters that can be used in a response file (continued)
Property Values Meaning
AGREETOLICENSE “2” on yes Accept the terms of the license. Set to yes
page 187 before a silent installation.
If the installation is not silent, this parameter is
ignored.

KEEPQMDATA keep |delete If the Server feature is to be uninstalled,

whether to delete any existing queue managers.
delete removes any existing queue managers.
keep, or any other value, keeps them.
Note: This property is only valid on a final
server uninstallation. Otherwise this property is
ignored.

LAUNCHWIZ 0|1|yes|no| "" 0 or no. Do not launch the Prepare IBM MQ

Wizard after IBM MQ is installed.
1 or yes. Launch the Prepare IBM MQ Wizard if
the Server feature is installed.
"". Launch the Prepare IBM MQ Wizard to install
the Server (the default).
If this option is to launch the Prepare IBM
MQ Wizard, you can specify the WIZPARMFILE,
either in this file, or on the command line.
The Prepare IBM MQ Wizard must be run to
make your IBM MQ installation operational. If
you choose not to launch it here, you must run it
before using IBM MQ.

WIZPARMFILE path \ file_name When specified, the file that contains the
parameters to pass to the Prepare IBM MQ
Wizard when it is launched. These are in the
[Services].
ADDLOCAL feature, feature, All| "" A comma-separated list of features to install
locally. For a list of valid feature names, see
“IBM MQ features for Windows systems” on
page 158.
All installs all features
"" installs the typical features. If you do not want
a feature use REMOVE="feature"
Note: If this is a new installation, the typical
features “3” on page 187 are installed by default
irrespective of the feature list provided in the
ADDLOCAL property. If you do not want a
feature, use REMOVE="feature" to specify that
feature.

Installing and migrating 185

 Table 25. Parameters that can be used in a response file (continued)
Property Values Meaning
REMOVE feature, feature, |All| "" A comma-separated list of features to remove.
For a list of valid feature names, see “IBM MQ
features for Windows systems” on page 158. “4”
on page 187

All uninstalls all features

"" uninstalls no features (the default).

STARTSERVICE 0|no| "" 0 or no. Do not start the IBM MQ Service at the
end of installation.
"" (the default). Start the IBM MQ Service at the
end of installation if it was running at the start,
or if this is a new installation.
Anything else. Start the Service at the end of the
installation.
Ignored if the server feature is not installed.
If you do not start the IBM MQ Service, IBM
MQ will not be operational and queue managers
will not start. You must run the Prepare IBM MQ
Wizard for the service to be correctly configured.
This parameter is only valid if LAUNCHWIZ is set
to no.

STARTTASKBAR 0|no| "" 0 or no. Do not start the IBM MQ taskbar

application at the end of installation.
"" (the default). Start the IBM MQ taskbar
application at the end of installation if it
was running at the start, or if this is a new
installation.
Anything else. Start the taskbar application at
the end of the installation.
Ignored if the server feature is not installed.
This parameter is only valid if LAUNCHWIZ is set
to no.

INSTALLATIONDESC "Description of Sets the installation description from the

installation" command line. Subject to the documented
installation description length limitations
INSTALLATIONNAME “1” INSTALLATIONName Sets the installation name from the command
on page 186 line. Subject to the documented installation
name character and length limitations.
MAKEPRIMARY 0|1| "" Makes the installation primary, if possible, or
removes the primary flag. 1 = Make primary, 0
= Make non-primary, - use default algorithm

Notes:
1. For multiple installations, the INSTALLATIONNAME or PGMFOLDER must be supplied as an additional
parameter on any non-interactive installation command. Supplying the INSTALLATIONNAME or

186 Installing and migrating IBM MQ

 PGMFOLDER ensures that you do not work with the wrong installation in case you omit or incorrectly
specify the TRANSFORMS parameter.
2. For a silent installation to succeed, the AGREETOLICENSE="yes" property must be defined either on
the command line or in the response file.
3. For a new installation, the typical features that are installed by default, irrespective of the feature list
provided in the ADDLOCAL property, include the following features. If they are NOT required, they must
be added to the REMOVE list.
• Server
• MQ Explorer
• Extended Messaging APIs (was Java and .NET Messaging and Web Services before IBM MQ 9.1.0)
• Web Administration
• Development Toolkit
• Java Runtime Environment
4. When specifying which features to remove with the REMOVE parameter:
• If you want to silently uninstall the Server feature, and the Web Administration (Web) feature
is installed, you must also silently uninstall the Web feature at the same time by specifying
REMOVE="Web,Server".
• If you want to silently uninstall the Java Runtime Environment (JRE) feature, and the Web
Administration (Web) feature is installed, you must also silently uninstall the Web feature at the
same time by specifying REMOVE="Web,JRE".

Procedure
1. Create a response file for installation in one of the following ways:
• Copy and edit the file Response.ini that is supplied in the IBM MQ Windows Server install image,
using an ASCII file editor.
• Create your own response file using an ASCII file editor.
• Use the msiexec command with the SAVEINI (and optionally, the ONLYINI) command line
parameters to generate a response file that contains the same installation options as shown in
the following example:

msiexec /i "path\IBM MQ.msi" /q SAVEINI="response_file"

TRANSFORMS="1033.mst" AGREETOLICENSE="yes"

2. To run the msiexec command with a response file, specify the full path and file name of the response
file with the USEINI parameter as shown in the following example:

msiexec /i "path\MSI\IBM
MQ.msi" /l*v c:\install.log TRANSFORMS= "1033.mst" USEINI= "C:\MQ\Responsefile"

In the response file, all text is in English, and comments begin with a ; character.

Example
The following example shows a typical response file:

[Response]
PGMFOLDER="c:\mqm"
DATFOLDER="c:\mqm\data"
LOGFOLDER="c:\mqm\log"
AGREETOLICENSE="yes"
LAUNCHWIZ=""
WIZPARMFILE="d:\MQParms.ini"
ADDLOCAL="Server,Client"
REMOVE="Toolkit"

Installing and migrating 187

 Installing the server using the MQParms command
You can use the MQParms command to invoke installation or uninstallation of the IBM MQ server.

Before you begin

The MQParms command can use parameters on a command line, or those specified in a parameter file.
The parameter file is an ASCII text file that contains the parameter values that you want to set for the
installation. The MQParms command takes the specified parameters and generates the corresponding
msiexec command line.
This means that you can save all the parameters that you want to use with the msiexec command in a
single file.
If you are running IBM MQ on Windows systems with User Account Control (UAC) enabled, you must
invoke the installation with elevated privileges. If you are using the Command prompt or IBM MQ Explorer
elevate privileges by using a right-click to start the program and selecting Run as administrator. If you
try to run the MQParms program without using elevated privileges, the installation fails with an error of
AMQ4353 in the installation log.
For silent operations, this must include the /q or /qn parameter, either on the command line, or in the
[MSI] stanza of the parameter file. You must also set the AGREETOLICENSE parameter to "yes".
You can specify many more parameters in the parameter file that you use with the MQParms command
than you can in the response file that you use directly with the msiexec command. Also, as well as
parameters that the IBM MQ installation uses, you can specify parameters that can be used by the
Prepare IBM MQ Wizard.
If you do not complete the Prepare IBM MQ Wizard directly after IBM MQ installations or if for any reason
your machine is rebooted between completing IBM MQ installation and completing the Prepare IBM MQ
Wizard, ensure that the wizard is run with Administrator privilege afterward, otherwise the installation
is incomplete, and might fail. You might also see Open File - Security Warning dialog boxes that list
International Business Machines Limited as the publisher. Click Run to allow the wizard to continue
An example of the file MQParms.ini is supplied with IBM MQ. This file contains default installation
parameters.
There are two ways to create a parameter file for installation:
• Copy and edit the file MQParms.ini that is supplied with the product, using an ASCII file editor.
• Create your own parameter file using an ASCII file editor.

About this task

To invoke installation using the MQParms command:

Procedure
1. From a command line, change to the root folder of the IBM MQ Server install image (that is, the
location of the file MQParms.exe).
2. Enter the following command:

MQParms parameter_file parameters ]

where:
parameter_file
is the file that contains the required parameter values. If this file is not in the same folder as
MQParms.exe, specify the full path and file name. If you do not specify a parameter file, the default
is MQParms.ini. For silent installation, the MQParms_silent.ini parameter file can be used.
For further details, see “MQParms parameter file - server installation” on page 189.

188 Installing and migrating IBM MQ

 parameters
are one or more command-line parameters, for a list of these, see the MSDN Command-Line
Options web page.

Example
A typical example of an MQParms command is:

MQParms "c:\MyParamsFile.ini" /l*v c:\install.log

A typical example of an MQParms command when you are installing a second copy of IBM MQ is:

MQParms "c:\MyParamsFile.ini" /l*v c:\install.log TRANSFORMS=":InstanceId2.mst;1033.mst"

MSINEWINSTANCE=1

Alternatively, TRANSFORMS and MSINEWINSTANCE can be specified in the MSI stanza of the parameter
file.
If you specify a parameter both on the command line and in the parameter file, the setting on the
command line takes precedence.
If you specify a parameter file, you might want to run the encryption utility before you use the MQParms
command (see “Encrypting a parameter file” on page 192 ).
If you do not specify /i, /x, /a, or /j, MQParms defaults to standard installation using the IBM MQ
Windows Installer package, IBM MQ.msi. That is, it generates the following part of the command line:

/i " current_folder \MSI\IBM MQ.msi"

If you do not specify a WIZPARMFILE parameter, MQParms defaults to the current parameter file. That is,
it generates the following part of the command:

WIZPARMFILE=" current_folder \ current_parameter_file "

MQParms parameter file - server installation

A parameter file is an ASCII text file that contains sections (stanzas) with parameters that can be used by
the MQParms command. Typically, this is an initialization file such as MQParms.ini.
The MQParms command takes parameters from the following stanzas in the file:
[MSI]
Contains general properties related to how the MQParms command runs and to the installation of IBM
MQ.
The properties that you can set in this stanza are listed in “Installing the server using msiexec” on
page 179, and Table 26 on page 190.
[Services]
Contains properties related to IBM MQ account configuration, in particular, the user account required
for IBM MQ Services. If you are installing IBM MQ on a network where the domain controller is on
a Windows 2003 or later server, you probably need details of a special domain account. For more
information, see “Configuring IBM MQ with the Prepare IBM MQ Wizard” on page 194 and “Creating
and setting up Windows domain accounts for IBM MQ” on page 198.
The properties that you can set in this stanza are listed in Table 28 on page 191.
MQParms ignores any other stanzas in the file.
The stanza parameters are in the form property=value, where property is always interpreted as
uppercase, but value is case sensitive. If a value string includes a blank, it must be enclosed in double

Installing and migrating 189

 quotation marks. Most other values can be enclosed in double quotation marks. Some properties can take
more than one value, for example:

ADDLOCAL="Server,Client"

To clear a property, set its value to an empty string, for example:

REINSTALL=""

The following tables show the properties that you can set. The default is shown in bold.
For the [MSI] stanza, you can enter standard MSI command line options and properties. For example:

- /q
- ADDLOCAL="server"
- REBOOT=Suppress

Refer to Table 26 on page 190, Table 27 on page 191, and Table 28 on page 191 for the properties used
to install IBM MQ.
Table 26 on page 190 shows additional properties in the stanza that affect how the MQParms command
runs, but that do not affect the installation.

Table 26. Properties used by MQParms in the MSI stanza

Property Values Description
MQPLOG path | file_name MQParms generates a text log file with the
specified name and location.
MQPLANGUAGE The installation language.
system |user|
transform_value |existing system. Install using the language of the
default system locale (the default).
user. Install using the language of the default
locale of the user.
transform_value. Install using the language
specified by this value. See Table 27 on page
191.
existing. If IBM MQ already exists on the
system, the same language will be used by
default, otherwise system is used.

MQPSMS 0 |no 0 or no. MQParms does not wait for the

msiexec command to end (the default).
Any other value. MQParms waits for the
msiexec command to end.

MQPINUSE 0 |1 If MQPINUSE is set to 1, MQParms continues

installing even if IBM MQ files are in use. If
this option is used a reboot will be required to
complete the installation.

190 Installing and migrating IBM MQ

Table 27. Valid values for the MQPLANGUAGE property
Language Valid values
U.S. English English en_us 1033
German German de_de 1031
French French fr_fr 1036
Spanish Spanish es_es 1034
Italian Italian it_it 1040
Brazilian Portuguese Brazilian Portuguese pt_br 1046
Japanese Japanese ja_jp 1041
Korean Korean ko_kr 1042
Simplified Chinese Simplified Chinese zh_cn 2052
Traditional Chinese Traditional Chinese zh_tw 1028
Czech Czech cs_cz 1029
Russian Russian ru_ru 1049
Hungarian Hungarian hu_hu 1038
Polish Polish pl_pl 1045

For the [Services] stanza, you can enter parameters in property=value format. You might want to encrypt
the values in this stanza. See “Encrypting a parameter file” on page 192.

Table 28. Properties used in the Services stanza

Property Values Description
USERTYPE local | domain | The type of user account to use:
onlydomain local
Creates a local user account.
domain
Creates a local user account. If this
does not have the required security
authorities, it uses the domain user
account specified by DOMAINNAME,
USERNAME, and PASSWORD.
onlydomain
Does not create a local user account,
but immediately uses the domain user
account specified by DOMAINNAME,
USERNAME and PASSWORD. If any of
these three properties are missing, a
USERTYPE of local is assumed.
The properties DOMAINNAME, USERNAME,
and PASSWORD are required if USERTYPE is
set to onlydomain.

DOMAINNAME domain_name 1 The domain for the domain user account.

Required if USERTYPE is set to domain or
onlydomain.

Installing and migrating 191

 Table 28. Properties used in the Services stanza (continued)
Property Values Description
USERNAME user_name 1 The user name for the domain user account.
Required if USERTYPE is set to domain or
onlydomain..

PASSWORD password 1 The password for the domain user account.

Required if USERTYPE is set to domain or
onlydomain.

1. Do not enclose this value in double quotation marks.

A typical example of a parameter file is:

[MSI]
MQPLANGUAGE=1033
MQPLOG=%temp%\MQParms.log
MQPSMS=no
ADDLOCAL=Server
/m miffile
REMOVE=""
/l*v c:\install.log

[Services]
USERTYPE=domain
DOMAINNAME=mqm*df349edfcab12
USERNAME=mqm*a087ed4b9e9c
PASSWORD=mqm*d7eba3463bd0a3

Encrypting a parameter file

If the DOMAINNAME, USERNAME, and PASSWORD values in the [Services] stanza of a parameter file are
not already encrypted, you can encrypt them by running the setmqipw utility.

About this task

Use the setmqipw utility to encrypt the DOMAINNAME, USERNAME, and PASSWORD values in the
[Services] stanza of a parameter file, if they are not already encrypted. (These values might be
encrypted if you have run the utility before.) setmqipw will also encrypt the QMGRPASSWORD and
CLIENTPASSWORD values in the [SSLMigration] stanza of a parameter file.
This encryption means that, if you need a special domain account to configure IBM MQ (see “Configuring
IBM MQ with the Prepare IBM MQ Wizard” on page 194 and “Creating and setting up Windows domain
accounts for IBM MQ” on page 198), or you need to keep key database passwords secret, details are
kept secure. Otherwise, these values, including the domain account password, flow across the network as
clear text. You do not have to use this utility, but it is useful if security in your network is an issue.
To run the script:

Procedure
1. From a command line, change to the folder that contains your parameter file.
2. Enter the following command:

CD_drive:\setmqipw

192 Installing and migrating IBM MQ

 Note: You can run the command from a different folder, by entering the following command, where
parameter_file is the full path and file name of the parameter file:

CD_drive:\setmqipw parameter_file

Results
If you view the resulting parameter file, the encrypted values start with the string mqm*. Do not use this
prefix for any other values; passwords or names that begin with this prefix are not supported.
The utility creates a log file, setmqipw.log, in the current directory. This file contains messages related
to the encryption process. When encryption is successful, messages are similar to:

Encryption complete
Configuration file closed
Processing complete

What to do next
After you encrypt the parameter file, you can use it in the normal way with the MQParms command (see
“Installing the server using the MQParms command” on page 188 ).

Checking for problems after installing

There are some optional tasks that you can use to check the installation if you believe there was a
problem, or to verify installation messages after an unattended (silent) installation for example.

About this task

Use these steps as a guide to check the following files for messages:

Procedure
1. Check MSI nnnnn.LOG. This file is in your user Temp folder. It is an application log that contains
English messages written during installation. The log includes a message indicating whether the
installation was successful and complete.
This file is created if you have set up default logging.
2. If you used the launchpad to install IBM MQ, check MQv9_Install_YYYY-MM-DDTHH-MM-SS.log in
your user Temp folder, where:
YYYY
This is the year that you installed IBM MQ
MM
This is the month that you installed IBM MQ, for example this would be 09 if you installed in
September
DD
This is the day that you installed IBM MQ
HH-MM-SS
This is the time at which IBM MQ was installed
You can get to your user Temp directory by entering the following command at the command prompt:

cd %TEMP%

3. Check amqmjpse.txt. This file is in the IBM MQ data files folder (default
C:\ProgramData\IBM\MQ ). It is an application log that contains English messages written during
installation by the Prepare IBM MQ Wizard.

Installing and migrating 193

 What to do next
Verify your installation, as described in “Verifying an IBM MQ installation on Windows” on page 220.

Configuring user accounts for IBM MQ

After installing IBM MQ server, you must configure the IBM MQ service before you can start any queue
managers.

About this task

When you install IBM MQ using the graphical user interface, you are guided through several screens
that help you to apply the relevant options and settings. You use the Launchpad to check software
requirements, specify network information, and then start the IBM MQ installation wizard and use it to
install the software.
After the installation of IBM MQ completes, you can use the Prepare IBM MQ Wizard to configure IBM MQ
before starting any queue managers.
If you are setting up IBM MQ for use with the Microsoft Cluster Service (MSCS), see Supporting the
Microsoft Cluster Service (MSCS).

Configuring IBM MQ with the Prepare IBM MQ Wizard

The Prepare IBM MQ Wizard helps you to configure IBM MQ with a user account for your network. You
must run the wizard to configure the IBM MQ Service before you can start any queue managers.

Before you begin

When IBM MQ is running, it must check that only authorized users can access queue managers or queues.
Whenever any user attempts such access, IBM MQ uses its own local account to query information about
the user.
Most networked Windows systems are members of a Windows domain where user accounts, other
security principals, and security groups are maintained and managed by a directory service, Active
Directory, running on a number of domain controllers. IBM MQ checks that only authorized users can
access queue managers or queues.
In such networks, IBM MQ queue manager processes access the Active Directory information to find the
security group membership of any users attempting to use IBM MQ resources. The accounts under which
IBM MQ services run must be authorized to look up such information from the directory. In most Windows
domains, local accounts defined at individual Windows servers cannot access directory information, so
the IBM MQ services must run under a domain account that has the appropriate permission.
If the Windows server is not a member of a Windows domain or the domain has a reduced security
or functional level, then the IBM MQ services can run under a local account that was created during
installation.
If a special domain account is needed for your installation of IBM MQ, the Prepare IBM MQ Wizard asks
you to enter details of this account (domain, user name, and password), so make sure that you have
this information available before you start this task. Ask your domain administrator to set up an account,
if one does not already exist, and provide you with the necessary details. For more information about
configuring a domain account, see “Creating and setting up Windows domain accounts for IBM MQ” on
page 198.
Important: If a domain account is needed and you install IBM MQ without a special account (or without
entering its details), many or all parts of IBM MQ will not work, depending on the particular user accounts
involved. Also, IBM MQ connections to queue managers that run under domain accounts on other systems
might fail. The account can be changed by running the Prepare IBM MQ Wizard and specifying the details
of the account to be used.
For information about the user rights required to take advantage of the Active Directory support, see Local
and domain user accounts for the IBM MQ Windows service.

194 Installing and migrating IBM MQ

 For information about the user rights required to take advantage of the Kerberos authentication support,
see Securing.

About this task

The Prepare IBM MQ Wizard window is displayed when the IBM MQ installation completes. You can also
run the wizard at any time from the Start menu.
You can use the Prepare IBM MQ Wizard (AMQMJPSE.EXE) with the following parameters:

Table 29. Startup parameters that can be used for the Prepare IBM MQ Wizard
Parameter Parameter Default action if parameter not
Name description How parameter is used supplied
-l file Create log file The Prepare IBM MQ Wizard appends Append to log file amqmjpse.txt
to a log file with the program actions in IBM MQ Data directory.
and results.
This parameter specifies the file name
to use for this log. If the path is not
provided, the IBM MQ Data directory
is assumed. If the file name is not
provided, amqmjpse.txt is assumed.

-r Reset When the Prepare IBM MQ Wizard User account not reset.
MQSeriesService is first run it creates a local
user account user account MUSR_MQADMIN, with
specific settings and permissions.
The MQSeriesService component is
configured to run under this account.
Depending on the LAN configuration,
the wizard might reconfigure the
MQSeriesService component to run
under a domain user account instead.
When this parameter is specified, the
local user account MUSR_MQADMIN is
re-created with all the default settings
and permissions. The MQSeriesService
component is configured to run under
this account.

-s silent installation Process silently. Nothing is displayed Not silent mode.

mode and there is no user input.
-p file User parameters Load and use parameters from the When in silent mode, the
from file parameter file. If the path is not parameter file AMQMJPSE.INI
provided, the IBM MQ Data directory is loaded from IBM MQ Data
is assumed. If the file name is not directory.
provided, AMQMJPSE.INI is assumed.
When not in silent mode, a
The following stanzas are loaded: parameter file is not used.

[Services]
[SSLMigration]

Installing and migrating 195

Table 29. Startup parameters that can be used for the Prepare IBM MQ Wizard (continued)
Parameter Parameter Default action if parameter not
Name description How parameter is used supplied
-m file Generate a When the Prepare IBM MQ Wizard .MIF file not created.
Microsoft System closes, generate a status .MIF file
Management Server with the specified name. If the path
(SMS) status .MIF is not provided, the Data directory
file. is assumed. If the file name is not
provided, AMQMJPSE.MIF is assumed.
The file ISMIF32.DLL (installed as part
of SMS) must be in the path.
The InstallStatus field in the file will
contain either Success or Failed.

On Windows systems, you must carry out this task under a Windows administrator account, or domain
administrator account in case your workstation is a member of a Windows domain.
On Windows systems with User Account Control (UAC) enabled, if you do not complete the Prepare IBM
MQ Wizard directly after IBM MQ is installed, or if for any reason your machine is rebooted between
completing IBM MQ installation and completing the Prepare IBM MQ Wizard, you must accept the
Windows prompt when it appears to allow the wizard to run as elevated.

Procedure
1. When the IBM MQ installation completes, the Prepare IBM MQ Wizard window is displayed with a
welcome message.
To continue, click Next.
2. If you have run the Prepare IBM MQ Wizard before, this step is skipped. Otherwise, the Prepare IBM
MQ Wizard window displays a progress bar with the following message:
Status: Setting up IBM MQ Configuration

Wait until the progress bar completes.

3. The Prepare IBM MQ Wizard window displays a progress bar with the following message:
Status: Setting up the IBM MQ Service.

Wait until the progress bar completes.

4. IBM MQ attempts to detect whether you must configure IBM MQ for use with Windows Active
Directory Server or Windows domain users. Depending on the results of the detection, IBM MQ does
one of the following things:
• If IBM MQ detects that you need to configure IBM MQ for Windows Active Directory Server or
Windows domain users, the Prepare IBM MQ Wizard window displays a message that starts:

IBM MQ does not have the authority to query information about

your user account

Click Next, and go to step 5.

• If you are not installing on a Windows Active Directory Server or Windows domain server and IBM
MQ cannot detect whether you need to configure IBM MQ for Windows Active Directory Server or
Windows domain users, the Prepare IBM MQ Wizard window displays the following message:

Are any of the domain controllers in your network running

Windows 2000 or later domain server?

If you select Yes, click Next, then go to step 5.

If you select No, click Next, then go to step 9.

196 Installing and migrating IBM MQ

 If you select Don't know, you cannot continue. Select one of the other options, or click Cancel and
contact your domain administrator.
• If IBM MQ detects that you do not need to configure IBM MQ for Windows Active Directory Server
or Windows domain users, go to step 9.
5. The Prepare IBM MQ Wizard window displays the following message:
Do you need to configure IBM MQ for users defined on Windows 2000
or later domain controllers?

If you select Yes, click Next, then go to step 6.

If you select No, click Next, then go to step 9.
If you select Don't know, you cannot continue. Select one of the other options, or click Cancel and
contact your domain administrator. For more information about domain accounts, see “Creating and
setting up Windows domain accounts for IBM MQ” on page 198.
6. Give the domain user that you obtained from your domain administrator the access to run as a
service.
a) Click Start > Run..., type the command secpol.msc and click OK.
b) Open Security Settings > Local Policies > User Rights Assignments. In the list of policies,
right-click Log on as a service > Properties.
c) Click Add User or Group... and type the name of the user you obtained from your domain
administrator, then click Check Names
d) If prompted by a Windows Security window, type the user name and password of an account user
or administrator with sufficient authority, and click OK > Apply > OK. Close the Local Security
Policy window.
7. In the next window, enter the Domain and user ID of the domain user account that you obtained
from your domain administrator. Either enter the Password for this account, or select the option This
account does not have a password. Click Next.
8. The Prepare IBM MQ Wizard window displays a progress bar with the following message:
Status: Configuring IBM MQ with the special domain user account

Wait until the progress bar completes. If there are any problems with the domain user account,
a further window is displayed. Follow the advice on this window before you continue with this
procedure.
9. The Prepare IBM MQ Wizard window displays a progress bar with the following message:

Status: Starting IBM MQ services

Wait until the progress bar completes.

10. Next, select the options that you require.
The Prepare IBM MQ Wizard window displays the following message:

You have completed the Prepare IBM MQ Wizard

Select the options that you require, then click Finish. Select one or more from the following list:
• Remove the shortcut to this wizard from the desktop
This option is available only if you have previously attempted installation, but you canceled the
procedure from thePrepare IBM MQ Wizard and you created a desktop shortcut to this wizard.
Select this option to remove the shortcut. You do not need it now that you have completed the
Prepare IBM MQ Wizard.
• Launch IBM MQ Explorer
The IBM MQ Explorer allows you to view and administer your IBM MQ network. You can use the
items in the Welcome to IBM MQ Explorer Content view page to explore the facilities in IBM MQ.
This page is launched the first time that the IBM MQ Explorer is launched. The Welcome page can
be viewed at any time from the IBM MQ Explorer by clicking IBM MQ in the Navigator view.

Installing and migrating 197

 • Launch Notepad to view the release notes
The release notes contain information about installing IBM MQ and also late-breaking news that is
available after the published documentation is produced.

What to do next
Optionally, follow the procedure described in Checking for problems after installing.
For information on how to verify an installation, see Verifying an IBM MQ installation on Windows.
Related concepts
User rights required for an IBM MQ Windows Service
Related tasks
Creating and setting up Windows domain accounts for IBM MQ
This information is for Domain Administrators. Use this information to create and set up a special domain
account for the IBM MQ service. Do this if IBM MQ is to be installed on a Windows domain where local
accounts do not have the authority to query the group membership of the domain user accounts.

Creating and setting up Windows domain accounts for IBM MQ

This information is for Domain Administrators. Use this information to create and set up a special domain
account for the IBM MQ service. Do this if IBM MQ is to be installed on a Windows domain where local
accounts do not have the authority to query the group membership of the domain user accounts.

About this task

After you add a local user to the mqm group, that user can administer IBM MQ on the system. This task
describes how to do the same using Windows domain user IDs.
There is an IBM MQ component for checking Windows privileges. This component runs as a Windows
service under a local user account created by IBM MQ at installation. This component checks that the
account under which the IBM MQ services are run has the following privileges:
• The account has the ability to query group memberships of domain accounts.
• The account has the authority to administer IBM MQ.
If the account does not have the ability to query group memberships, the access checks made by the
services fail.
Windows domain controllers running Windows Active Directory can be set up so that local accounts do
not have the authority to query the group membership of the domain user accounts. This prevents IBM
MQ from completing its checks, and access fails. If you are using Windows on a domain controller that
has been set up in this way, you must instead use a special domain user account with the required
permissions.
Each installation of IBM MQ on the network must be configured to run its service under a domain
user account that has the required authority to check that users who are defined on the domains
are authorized to access queue managers or queues. Typically, this special account has the IBM MQ
administrator rights through membership of the domain group DOMAIN\Domain mqm. The domain group
is automatically nested by the installation program under the local mqm group of the system on which IBM
MQ is being installed.
Important:
1. By default, Windows 10 version 1607 or later, and Windows Server 2016 or later, are more restrictive
than earlier versions of Windows. These later versions restrict clients allowed to make remote calls
to the Security Accounts Manager (SAM), and could prevent IBM MQ queue managers from starting.
Access to SAM is critical for the functioning of IBM MQ when IBM MQ is configured as a domain
account.
2. The IBM MQ installer must be given the user ID and password details of the special domain user
account. The installer can then use this information to configure the IBM MQ service after the product

198 Installing and migrating IBM MQ

 is installed. If an installer continues and configures IBM MQ without a special account, many or all
parts of IBM MQ will not work, depending upon the particular user accounts involved, as follows:
• IBM MQ connections to queue managers running under Windows domain accounts on other
computers might fail.
• Typical errors include AMQ8066: Local mqm group not found and AMQ8079: Access was
denied when attempting to retrieve group membership information for user
'abc@xyz'.
You must repeat steps “1” on page 199 and “8” on page 200 of the following procedure for each domain
that has user names that will administer IBM MQ. This creates an account for IBM MQ on each domain.

Procedure
Create a domain group with a special name that is known to IBM MQ (see “4” on page 199) and give
members of this group the authority to query the group membership of any account.
1. Log on to the domain controller as an account with domain administrator authority.
2. From the Start menu, open Active Directory Users and Computers.
3. Find the domain name in the navigation pane, right-click it and select New Group.
4. Type a group name into the Group name field.
Note: The preferred group name is Domain mqm. Type it exactly as shown.
• Calling the group Domain mqm modifies the behavior of the Prepare IBM MQ Wizard on a domain
workstation or server. It causes the Prepare IBM MQ Wizard automatically to add the group Domain
mqm to the local mqm group on each new installation of IBM MQ in the domain.
• You can install workstations or servers in a domain with no Domain mqm global group. If you do
so, you must define a group with the same properties as Domain mqm group. You must make that
group, or the users that are members of it, members of the local mqm group wherever IBM MQ is
installed in a domain. You can place domain users into multiple groups. Create multiple domain
groups, each group corresponding to a set of installations that you want to manage separately. Split
domain users, according to the installations they manage, into different domain groups. Add each
domain group or groups to the local mqm group of different IBM MQ installations. Only domain users
in the domain groups that are members of a specific local mqm group can create, administer, and run
queue managers for that installation.
• The domain user that you nominate when installing IBM MQ on a workstation or server in a domain
must be a member of the Domain mqm group, or of an alternative group you defined with same
properties as the Domain mqm group.
5. Leave Global clicked as the Group scope, or change it to Universal. Leave Security clicked as the
Group type. Click OK.
6. Follow these steps to assign permissions to the group based on the Windows version of the domain
controller:
On Windows Server 2012, Windows Server 2012 R2, Windows Server 2016, Windows Server 2019,
and Windows Server 2022:
a. In the Server Manager, click Tools then select Active Directory Users and Computers from the
list box.
b. Select View > Advanced Features.
c. Expand your domain name, then click Users.
d. In the Users window, right-click Domain mqm > Properties.
e. On the Security tab, click Advanced > Add....
f. Click Select principle, then type Domain mqm and click Check names > OK.
The Name field is prefilled with the string Domain mqm (domain name\Domain mqm).
g. In the Applies to list, select Descendant User Objects.

Installing and migrating 199

 h. In the Permissions list, select the Read group membership and Read groupMembershipSAM
check boxes.
i. Click OK > Apply > OK > OK.
On Windows Server 2008 and Windows 2008 R2:
a. In the Server Manager navigation tree, click Users.
b. In the Server Manager action bar, click View > Advanced features.
c. In the Users window, right-click Domain mqm > Properties.
d. On the Security tab, click Advanced > Add, then type Domain mqm and click Check names > OK.
The Name field is prefilled with the string Domain mqm (domain name\Domain mqm)
e. Click Properties. In the Apply to list, select Descendant User Objects.
f. In the Permissions list, select the Read group membership and Read groupMembershipSAM
check boxes.
g. Click OK > Apply > OK > OK.
Create one or more accounts, and add them to the group.
7. Open Active Directory Users and Computers.
8. Create one or more user accounts with names of your choosing.
In the Server Manager navigation tree, right click Users to create a new user account.
9. Add each new account to the group Domain mqm or a group that is a member of the local mqm group.

Attention: You cannot use a user domain named mqm on Windows.

Create an account for IBM MQ on each domain.

10. Repeat step sections “1” on page 199 and “8” on page 200 for each domain that has user names that
will administer IBM MQ.
Use the accounts to configure each installation of IBM MQ.
11. Either use the same domain user account (as created in Step “1” on page 199 ) for each installation
of IBM MQ, or create a separate account for each one, adding each to the Domain mqm group (or a
group that is a member of the local mqm group).
12. When you have created the account or accounts, give one to each person configuring an installation
of IBM MQ. They must enter the account details (domain name, user name, and password) into the
Prepare IBM MQ Wizard. Give them the account that exists on the same domain as their installing
userid.
13. When you install IBM MQ on any system on the domain, the IBM MQ installation program detects the
existence of the Domain mqm group on the LAN, and automatically adds it to the local mqm group.
(The local mqm group is created during installation; all user accounts in it have authority to manage
IBM MQ ). Thus all members of the " Domain mqm " group will have authority to manage IBM MQ on
this system.
14. However, you do still need to provide a domain user account (as created in Step “1” on page 199 )
for each installation, and configure IBM MQ to use it when making its queries. The account details
must be entered into the Prepare IBM MQ Wizard that runs automatically at the end of installation
(the wizard can also be run at any time from the start menu).
Set the password expiry periods.
15. Choices:
• If you use just one account for all users of IBM MQ, consider making the password of the account
never expire, otherwise all instances of IBM MQ will stop working at the same time when the
password expires.
• If you give each user of IBM MQ their own user account you will have more user accounts to create
and manage, but only one instance of IBM MQ will stop working at a time when the password
expires.

200 Installing and migrating IBM MQ

 If you set the password to expire, warn the users that they will see a message from IBM MQ each
time it expires - the message warns that the password has expired, and describes how to reset it.
Use a Windows domain account as the user ID for the IBM MQ service.
16. Click Start > Run....
Type the command secpol.msc then click OK.
17. Open Security Settings > Local Policies > User Rights Assignments.
In the list of policies, right-click Log on as a service > Properties.
18. Click Add User or Group....
Type the name of the user you obtained from your domain administrator, and click Check Names.
19. If prompted by a Windows Security window, type the user name and password of an account user or
administrator with sufficient authority, then click OK > Apply > OK.
Close the Local Security Policy window.
Note: User Account Control (UAC) is enabled by default. The UAC feature restricts the actions users
can perform on certain operating system facilities, even if they are members of the Administrators
group. You must take appropriate steps to overcome this restriction.
Related tasks
Configuring IBM MQ with the Prepare IBM MQ Wizard
The Prepare IBM MQ Wizard helps you to configure IBM MQ with a user account for your network. You
must run the wizard to configure the IBM MQ Service before you can start any queue managers.

Modifying a server installation

You can modify an IBM MQ server installation interactively using the launchpad or non-interactively using
msiexec.
Related tasks
“Modifying a server installation using the Installation Launchpad” on page 201
You can interactively remove or install IBM MQ features on Windows by using IBM MQ Installation
Launchpad.
“Modifying a server installation silently using msiexec” on page 202
You can silently remove or install IBM MQ features on Windows by using msiexec.

Modifying a server installation using the Installation Launchpad

You can interactively remove or install IBM MQ features on Windows by using IBM MQ Installation
Launchpad.

Before you begin

To modify an installation, some features of IBM MQ must already be installed.

About this task

To use the IBM MQ Installation Launchpad to remove or install IBM MQ features, you download the
installation image for your version of IBM MQ then run the Setup.exe program.

Procedure
1. Download the compressed file that contains the installation image, then uncompress it into a
temporary directory.
2. Navigate to that directory, then double-click Setup.exe to start the installation process.
The IBM MQ Installation Launchpad window is displayed.
3. Click the IBM MQ Installation option.
4. Click Launch IBM MQ Installer. Wait until the IBM MQ Setup window is displayed with a welcome
message.

Installing and migrating 201

 5. If you have multiple installations on your system, you must choose the installation you want to
modify. Do this by selecting the Maintain or upgrade an existing instance option and choosing the
appropriate instance.
6. Click Next to continue. The Program Maintenance panel is displayed.
7. Select Modify, then click Next.
The Features panel is displayed.
8. Click the + symbol next to a feature to show any dependent features (subfeatures).
9. To change the installation of a feature:
a) Click the symbol next to the feature name to display a menu.
b) Select the required option from:
• Install this feature
• Install this feature and all its subfeatures (if any)
• Do not install this feature (remove if already installed)
The symbol next to the feature name changes to show the current installation option.
10. Stop the web server before removing the web feature.
If you do not do this, you receive an error message.
11. When your selections are complete, click Next. IBM MQ installation begins.

What to do next
After modifying the installation, you might need to run setmqenv again as described in What to do next in
“Installing IBM MQ server on Windows” on page 176.

Modifying a server installation silently using msiexec

You can silently remove or install IBM MQ features on Windows by using msiexec.

About this task

You can silently modify an installation by using the msiexec command with the ADDLOCAL and REMOVE
parameters.

Procedure
• To silently modify an installation using msiexec, set the ADDLOCAL parameter to include the features
you want to add, and set the REMOVE parameter to the features you want to remove.
For example, if you use ADDLOCAL="JavaMsg" and REMOVE="" it modifies the installation to include
the Extended Messaging and APIs (JavaMsg) feature but does not remove any currently installed
features.

msiexec /i {product code} /q ADDLOCAL="JavaMsg" REMOVE="" INSTALLATIONNAME="Installation1"

where product_code is the value shown for MSIProdCode in the output of the following command:

dspmqinst -n installation_name

An example of a product code is {0730749B-080D-4A2E-B63D-85CF09AE0EF0}.

Important: When specifying which features to remove with the REMOVE parameter:
– If you want to silently uninstall the Server feature, and the Web Administration (Web) feature
is installed, you must also silently uninstall the Web feature at the same time by specifying
REMOVE="Web,Server".

202 Installing and migrating IBM MQ

 – If you want to silently uninstall the Java Runtime Environment (JRE) feature, and the Web
Administration (Web) feature is installed, you must also silently uninstall the Web feature at the
same time by specifying REMOVE="Web,JRE".
Related concepts
“IBM MQ features for Windows systems” on page 158
You can select the features that you require when you install IBM MQ.
Related tasks
“Installing the server using msiexec” on page 179
IBM MQ on Windows uses the MSI technology to install software. MSI provides both an interactive
installation and a non interactive installation.
“Uninstalling IBM MQ using msiexec” on page 233
You can uninstall IBM MQ by running the msiexec command from the command line to remove all
currently installed features, or selected features.

Installing an IBM MQ client on Windows

This topic describes how to install IBM MQ client on Windows systems. This procedure can be used for
installing a first or a subsequent installation.

Before you begin

To install an IBM MQ client, you must be logged on to Windows as an administrator.

About this task

Follow these instructions to perform an interactive compact, typical, or custom installation of IBM MQ.
To view all the installation types and the features that are installed with each option consult Features
installed with each type of interactive installation.
Attention: If you are using msiexec to install the client, the installation is automatically set to be
the primary installation.

Procedure
1. Access the IBM MQ installation image.
The location might be a network location, or a local file system directory. See Where to find
downloadable installation images.
2. Locate Setup.exe in the Windows directory of the IBM MQ installation image.
• From a network location, this location might be m:\instmqs\Windows\Setup.exe
• From a local file system directory, this location might be C:\instmqs\Windows\Setup.exe
3. Start the installation process.
Either run Setup.exe from a command prompt, or double-click Setup.exe from Windows Explorer.
Note: If you are installing on a Windows system with UAC enabled, accept the Windows prompt to
allow the launchpad to run as elevated. During installation, you might also see Open File - Security
Warning dialog boxes that list International Business Machines Limited as the publisher. Click Run to
allow the installation to continue.
The IBM MQ Installation window is displayed.
4. Follow the instructions on screen.

Results
A new sample IBM MQ MQI client configuration file is created in the IBM MQ installation directory (for
example C:\Program Files\IBM\MQ\, by the IBM MQ MQI client package, during installation, but only

Installing and migrating 203

 if this file does not exist. This file contains the ClientExitPath stanza. An example mqclient.ini file
is shown in IBM MQ MQI client configuration file, mqclient.ini.
Note:
If you are using a common configuration file for multiple clients, either in the IBM MQ installation
directory or in another location using the MQCLNTCF environment variable, you must grant read access to
all user identifiers under which the IBM MQ client applications run. If the file cannot be read, the failure is
traced and the search logic continues as if the file had not existed.

What to do next
• If you have chosen this installation to be the primary installation on the system, when using
setup.exe, you must now set it as the primary installation. Enter the following command at the
command prompt:

MQ_INSTALLATION_PATH\bin\setmqinst -i -p MQ_INSTALLATION_PATH

You can have only one primary installation on a system. If there is already a primary installation on the
system, you must unset it before you can set another installation as the primary installation. For more
information, see Changing the primary installation.
• You might want to set up the environment to work with this installation. You can use the setmqenv or
crtmqenv command to set various environment variables for a particular installation of IBM MQ. For
more information, see setmqenv and crtmqenv.
• For instructions on how to verify your installation, see “Testing communication between a client and a
server on Windows” on page 229.
Related concepts
“Modifying a client installation using Add/Remove Programs” on page 215
On some versions of Windows, you can modify an installation by using Add/Remove Programs.
Related tasks
“Installing a client using msiexec” on page 204
IBM MQ on Windows uses the MSI technology to install software. MSI provides both an interactive
installation and a non interactive installation.
“Installing a client using the MQParms command” on page 211
You can use the MQParms command to invoke installation or uninstallation of an IBM MQ client.
“Uninstalling IBM MQ on Windows” on page 230
You can uninstall the IBM MQ MQI clients and servers on Windows systems by using the control panel,
the command line ( msiexec ), MQParms, or by using the installation media, in which case you can
optionally remove queue managers as well.

Installing a client using msiexec

IBM MQ on Windows uses the MSI technology to install software. MSI provides both an interactive
installation and a non interactive installation.

About this task

IBM MQ on Windows uses the MSI technology to install software. MSI provides both an interactive
installation and a non interactive installation. An interactive installation displays panels and ask
questions.
The msiexec command uses parameters to give MSI some or all of the information that can also be
specified through panels during an interactive installation. This means that a user can create a reusable
automated or semi-automated installation configuration. Parameters can be given through the command
line, a transform file, a response file, or a combination of the three.

204 Installing and migrating IBM MQ

Some parameters can only be provided on the command line and not in a response file. For more
information about these parameters, see Table 30 on page 207 in “Specifying command line parameters
for client installation with msiexec” on page 206.
There are also a number of parameters can be used either on the command line or in a response file. For
more information about these parameters, see Table 32 on page 209 in “Creating and using a response
file for client installation” on page 209. If a parameter is specified both on the command line and in a
response file, the setting on the command line takes precedence.

Procedure
1. For multiple silent installations, for each version that is to be installed, find an MSI instance ID that is
available to use for that installation.
For more information, see “Choosing MSI Instance IDs for multiple server installations” on page 180.
2. To install using msiexec, at the command line, enter the msiexec command in the following format:

msiexec parameters [USEINI="response-file"] [TRANSFORMS="transform_file"]

where:
parameters
are either command line parameters preceded by a / character, or property=value pairs (if using
both forms of parameter always put the command-line parameters first). For further information,
see “Specifying command line parameters for client installation with msiexec” on page 206.
For an unattended installation, you must include the /q or /qn parameter in the command line.
Without this parameter, the installation is interactive.
Note: You must include the /i parameter and the file location of the IBM MQ installer package.
response-file
is the full path and file name of the file that contains the [Response] stanza and the
required property=value pairs, for example C:\MyResponseFile.ini. An example response file,
Response.ini, is supplied with IBM MQ. This file contains default installation parameters. For
further information, see “Creating and using a response file for client installation” on page 209.
transform_file
is the full path and file name of a transform file. For further information, see “Using transforms with
msiexec for client installation” on page 208 and “Choosing MSI Instance IDs for multiple server
installations” on page 180.
Note: For a silent installation to succeed, the AGREETOLICENSE="yes" property must be defined
either on the command line or in the response file.

Results
After the command has been entered, the command prompt immediately reappears. IBM MQ is installing
as a background process. If you have entered parameters to produce a log, check this file to see
how the installation is progressing. If the installation completes successfully, you see the message
Installation operation completed successfully in the log file.

Choosing MSI Instance IDs for multiple client installations

For multiple silent installations, for each version that is installed you must find an MSI instance ID that is
available to use for that installation.

About this task

In order to support silent, or non-interactive, multiple installations, you need to find out whether the
instance ID you want to use is already in use or not and choose the appropriate one. For each installation
media (for example, each client and server), Instance ID 1 is the default ID which is used for single
installations. If you want to install alongside Instance ID 1 you need to specify which instance you want

Installing and migrating 205

 to use. If you have already installed instance 1, 2, and 3 then you need to find out what the next available
instance is, for instance, Instance ID 4. Similarly, if instance 2 has been removed, you need to find out
that there is a gap that can be reused. You can find out which Instance ID is currently in use by using the
dspmqinst command.

Procedure
1. Type dspmqinst to find a free MSI Instance in the media being installed by reviewing the MSIMedia
and MSIInstanceId values for the versions already installed. For example:

InstName: Installation1
InstDesc:
Identifier: 1
InstPath: C:\Program Files\IBM\MQ
Version: 9.0.0.0
Primary: Yes
State: Available
MSIProdCode: {74F6B169-7CE6-4EFB-8A03-2AA7B2DBB57C}
MSIMedia: 9.0 Server
MSIInstanceId: 1

2. If MSI Instance ID 1 is in use and you want to use MSI Instance ID 2, the following parameters must
be added to the msiexec call:

MSINEWINSTANCE=1 TRANSFORMS=":instanceId7.mst;1033.mst"

What to do next
For multiple installations, the INSTALLATIONNAME or PGMFOLDER must be supplied as an additional
parameter on any non-interactive installation command. Supplying the INSTALLATIONNAME or
PGMFOLDER ensures that you do not work with the wrong installation in case you omit or incorrectly
specify the TRANSFORMS parameter.

Specifying command line parameters for client installation with msiexec

You can specify either standard msiexec command line parameters preceded by a / character, or
property=value pairs, or a combination of both.

About this task

The msiexec command can accept the following types of parameters on the command line:
Standard command line parameters, preceded by a / character
For more information about the msiexec command line parameters, see the MSDN Command-Line
Options web page.
For an unattended installation, you must include the /q or /qn parameter in the command line.
Without this parameter, the installation is interactive.
Note: You must include the /i parameter and the file location of the IBM MQ installer package.
Property=value pair parameters on the command line
All the parameters that are available for use in a response file can be used on the command line.
For more information about these parameters, see Table 32 on page 209 in “Creating and using a
response file for client installation” on page 209.
There are some extra property=value pair parameters, shown in the following table that are only for
use on the command line:

206 Installing and migrating IBM MQ

 Table 30. Parameters that can be used on the command line only (msiexec property=value
parameters)
Property Values Meaning
USEINI path \ file_name Use the specified response file. See
“Creating and using a response file
for client installation” on page 209
SAVEINI path \ file_name Generate a response file during
installation. The file contains
those parameters selected for this
installation that a user might make
during an interactive installation.
ONLYINI 1|yes| "" 1, yes or any value other than
null. End the installation before
updating the target system, but after
generating a response file, if this is
specified.
"". Continue the installation and
update the target system (the
default).

TRANSFORMS :InstanceId x.mst| path \ file_name | The :InstanceId x.mst value is

:InstanceId x.mst; path \ file_name only required for a subsequent
installation of IBM MQ. The path \
file_name specifies what transform
(.mst) files must be applied to the
product. For example, "1033.mst"
specifies the supplied U.S. English
transform file.
MSINEWINSTAN 1 This property is only required for
CE subsequent installations of IBM MQ.
REMOVEFEATUR yes Required with value "yes" for a
ES silent installation, otherwise ignored.
Allows obsolete features, no longer
part of IBM MQ, to be deleted.

When using the property=value pair parameters note that:

• Property strings must be in uppercase.
• Value strings are not case-sensitive, except for feature names. You can enclose value strings in double
quotation marks. If a value string includes a blank, enclose the blank value string in double quotation
marks.
• For a property that can take more than one value, use the format:

ADDLOCAL="Server,Client"

• For properties taking paths and file names, for example PGMFOLDER, you must supply the paths as
absolute paths and not relative; that is, C:\folder\file and not .\folder\file.
When using property=value pair and command line parameters with the msiexec command, enter
command line parameters first.
If a parameter is specified both on the command line and in a response file, the setting on the command
line takes precedence.

Installing and migrating 207

 Procedure
• For a single installation of IBM MQ, specify the msiexec command as shown in the following typical
example.

msiexec /i "path\MSI\IBM MQ.msi" /l*v c:\install.log

/q TRANSFORMS="1033.mst" AGREETOLICENSE="yes" ADDLOCAL="Client"

• If you are installing a second copy of IBM MQ, specify the msiexec command as shown in the
following typical example.

msiexec /i "path\MSI\IBM MQ.msi" /l*v c:\install.log

/q TRANSFORMS=":InstanceId2.mst;1033.mst" AGREETOLICENSE="yes"
ADDLOCAL="Client" MSINEWINSTANCE=1

Using transforms with msiexec for client installation

MSI can use transforms to modify an installation. During IBM MQ installation, transforms can be used to
support different national languages.

About this task

IBM MQ is supplied with transform files in the \MSI folder of the client image. These files are also
embedded in the IBM MQ Windows installer package, IBM MQ.msi.
Table 31 on page 208 shows the locale identifier, language, and the transform file name to use in the
msiexec command line.

Table 31. Supplied transform files for various language support

Language Transform File name Value
U.S. English 1033.mst 1033
German 1031.mst 1031
French 1036.mst 1036
Spanish 1034.mst 1034
Italian 1040.mst 1040
Brazilian Portuguese 1046.mst 1046
Japanese 1041.mst 1041
Korean 1042.mst 1042
Simplified Chinese 2052.mst 2052
Traditional Chinese 1028.mst 1028
Czech 1029.mst 1029
Russian 1049.mst 1049
Hungarian 1038.mst 1038
Polish 1045.mst 1045

You can also specify the required language by using the MQLANGUAGE property with the MQParms
command. For information about the msiexec property=value parameters, see “MQParms parameter file -
client installation” on page 213.

208 Installing and migrating IBM MQ

Procedure
On the msiexec command line, you can specify the required language by using the TRANSFORMS
property in a property=value pair as shown in the following example:

TRANSFORMS="1033.mst"

The quotation marks surrounding the value are optional.

You can also specify the full path and file name of the transform file. Again, the quotation marks
surrounding the value are optional. For example:

TRANSFORMS="D:\Msi\1033.mst"

Table 31 on page 208 shows the locale identifier, language, and the transform file name to use in the
msiexec command line.
You might need to merge transforms to install multiple installations of the same version, for example:

TRANSFORMS=":InstanceId2.mst;D:\Msi\1033.mst"

Creating and using a response file for client installation

You can use the msiexec command with a parameter that specifies additional properties that are defined
in a response file. There are three ways of creating a response file for a client installation.

About this task

A response file is an ASCII text file, with a format like a Windows .ini file, that contains the stanza
[Response]. The [Response] stanza contains some or all the parameters that would normally be specified
as part of an interactive installation. The parameters are given in a property=value pair format. Any other
stanzas in the response file are ignored by msiexec.
An example response file, Response.ini, is supplied with IBM MQ. It contains the default installation
parameters.
You can combine the use of a response file with the msiexec command line parameters described in
“Specifying command line parameters for client installation with msiexec” on page 206.
Table 32 on page 209 shows the parameters that are available for use in a response file. These
parameters can also be used on the command line. If a parameter is specified both on the command
line and in a response file, the setting on the command line takes precedence.

Table 32. Parameters that can be used in a response file

Property Values Meaning
PGMFOLDER “1” on page path Folder for the IBM MQ program files. For example,
211 c:\mqm.
DATFOLDER path Folder for the IBM MQ data files. For example,
c:\mqm\data.

Installing and migrating 209

 Table 32. Parameters that can be used in a response file (continued)
Property Values Meaning
USERCHOICE 0|no If the command line or response file specifies
parameters to install features, a dialog can
be displayed to prompt you to accept the
preselected options, or review and possibly
change them.
0 or no. Suppresses display of the dialog.
Anything else. Dialog is displayed and you can
amend the options.
Not used for a silent installation.

AGREETOLICENSE “2” yes Accept the terms of the license. Set to yes before
on page 211 a silent installation.
If the installation is not silent, this parameter is
ignored.

ADDLOCAL feature, feature, All| "" A comma-separated list of features to install

locally. For a list of valid feature names, see “IBM
MQ features for Windows systems” on page 158.
All installs all features
"" installs the typical features. If you do not want
a feature use REMOVE="feature"
Note: If this is a new installation the typical
features (Client, Java, .NET Messaging, and
Development Toolkit) are installed by default
irrespective of the feature list provided in the
ADDLOCAL property. If you do not want a feature
use REMOVE="feature"

REMOVE feature, feature, |All| "" A comma-separated list of features to remove.

For a list of valid feature names, see “IBM MQ
features for Windows systems” on page 158.
All uninstalls all features
"" uninstalls no features (the default).

INSTALLATIONDESC "Description of Sets the installation description from the

installation" command line. Subject to the documented
installation description length limitations
INSTALLATIONNAME [INSTALLATION0,]Name Sets the installation name from the command
“1” on page 211 line. Subject to the documented installation name
character and length limitations.
MAKEPRIMARY 0|1| "" Makes the installation primary, if possible, or
removes the primary flag. 1 = Make primary, 0 =
Make non-primary, - use default algorithm
Note: This option is ignored if another IBM MQ
installation is present and set as the primary.

Notes:

210 Installing and migrating IBM MQ

1. For multiple installations, the INSTALLATIONNAME or PGMFOLDER must be supplied as an additional
parameter on any non-interactive installation command. Supplying the INSTALLATIONNAME or
PGMFOLDER ensures that you do not work with the wrong installation in case you omit or incorrectly
specify the TRANSFORMS parameter.
2. For a silent installation to succeed, the AGREETOLICENSE="yes" property must be defined either on
the command line or in the response file.

Procedure
1. Create a response file for installation in one of the following ways:
• Copy and edit the file Response.ini that is supplied on the IBM MQ Windows Server install
image, using an ASCII file editor.
• Create your own response file using an ASCII file editor.
• Use the msiexec command with the SAVEINI (and optionally, the ONLYINI ) command line
parameters to generate a response file that contains the same installation options as shown in the
following example:

msiexec /i "path\IBM MQ.msi" /q SAVEINI="response_file"

TRANSFORMS="1033.mst" AGREETOLICENSE="yes"

2. To run the msiexec command with a response file, specify the full path and file name of the response
file with the USEINI parameter as shown in the following example:

msiexec /i "path\MSI\IBM MQ.msi" /l*v c:\install.log

TRANSFORMS="1033.mst" USEINI="C:\MQ\Responsefile"

In the response file, all text is in English, and comments begin with a ; character.

Example
The following example shows a typical response file:

[Response]
PGMFOLDER="c:\mqm"
DATFOLDER="c:\mqm\data"
AGREETOLICENSE="yes"
ADDLOCAL="Client"
REMOVE="Toolkit"

Installing a client using the MQParms command

You can use the MQParms command to invoke installation or uninstallation of an IBM MQ client.

Before you begin

The MQParms command can use parameters on a command line, or those specified in a parameter file.
The parameter file is an ASCII text file that contains the parameter values that you want to set for the
installation. The MQParms command takes the specified parameters and generates the corresponding
msiexec command line.
This means that you can save all the parameters that you want to use with the msiexec command in a
single file.
If you are running IBM MQ on Windows systems with User Account Control (UAC) enabled, you must
invoke the installation with elevated privileges. If you are using the Command prompt or IBM MQ Explorer
elevate privileges by using a right-click to start the program and selecting Run as administrator. If you
try to run the MQParms program without using elevated privileges, the installation fails with an error of
AMQ4353 in the installation log.

Installing and migrating 211

 For silent operations, this must include the /q or /qn parameter, either on the command line, or in the
[MSI] stanza of the parameter file. You must also set the AGREETOLICENSE parameter to "yes".
You can specify many more parameters in the parameter file that you use with the MQParms command
than you can in the response file that you use directly with the msiexec command. Also, as well as
parameters that the IBM MQ installation uses, you can specify parameters that can be used by the
Prepare IBM MQ Wizard.
If you do not complete the Prepare IBM MQ Wizard directly after IBM MQ installations or if for any reason
your machine is rebooted between completing IBM MQ installation and completing the Prepare IBM MQ
Wizard, ensure that the wizard is run with Administrator privilege afterward, otherwise the installation
is incomplete, and might fail. You might also see Open File - Security Warning dialog boxes that list
International Business Machines Limited as the publisher. Click Run to allow the wizard to continue
An example of the file MQParms.ini is supplied with IBM MQ. This file contains default installation
parameters.
There are two ways to create a parameter file for installation:
• Copy and edit the file MQParms.ini that is supplied with the product, using an ASCII file editor.
• Create your own parameter file using an ASCII file editor.

About this task

To invoke installation using the MQParms command:

Procedure
1. From a command line, change to the root folder of the IBM MQ installation media (that is, the location
of the file MQParms.exe).
2. Enter the following command:

MQParms [ parameter_file ] [ parameters ]

where:
parameter_file
is the file that contains the required parameter values. If this file is not in the same folder as
MQParms.exe, specify the full path and file name. If you do not specify a parameter file, the default
is MQParms.ini. For further details, see “MQParms parameter file - client installation” on page 213.
parameters
are one or more command-line parameters, for a list of these, see the MSDN Command-Line
Options web page.

Example
A typical example of an MQParms command is:

MQParms "c:\MyParamsFile.ini" /l*v c:\install.log

If you specify a parameter both on the command line and in the parameter file, the setting on the
command line takes precedence.
If you do not specify /i, /x, /a, or /j, MQParms defaults to standard installation using the IBM MQ
Windows Installer package, IBM IBM MQ.msi. That is, it generates the following part of the command line:

/i " current_folder \MSI\IBM MQ.msi"

212 Installing and migrating IBM MQ

 MQParms parameter file - client installation
A parameter file is an ASCII text file that contains sections (stanzas) with parameters that can be used by
the MQParms command. Typically, this is an initialization file such as MQParms.ini.
The MQParms command takes parameters from the following stanzas in the file:
[MSI]
Contains general properties related to how the MQParms command runs and to the installation of IBM
MQ.
The properties that you can set in this stanza are listed in “Installing a client using msiexec” on page
204, and Table 33 on page 213.
MQParms ignores any other stanzas in the file.
The stanza parameters are in the form property=value, where property is always interpreted as
uppercase, but value is case sensitive. If a value string includes a blank, it must be enclosed in double
quotation marks. Most other values can be enclosed in double quotation marks. Some properties can take
more than one value, for example:

ADDLOCAL="Server,Client"

To clear a property, set its value to an empty string, for example:

REINSTALL=""

The following tables show the properties that you can set. The default is shown in bold.
For the [MSI] stanza, you can enter standard MSI command line options and properties. For example:

- /q
- ADDLOCAL="client"
- REBOOT=Suppress

Refer to Table 33 on page 213, and Table 34 on page 214 for the properties used to install IBM MQ.
Table 33 on page 213 shows additional properties in the stanza that affect how the MQParms command
runs, but that do not affect the installation.

Table 33. Properties used by MQParms in the MSI stanza

Property Values Description
MQPLOG path | file_name MQParms generates a text log file with the
specified name and location.
MQPLANGUAGE The installation language.
system |user|
transform_value |existing system. Install using the language of the
default system locale (the default).
user. Install using the language of the default
locale of the user.
transform_value. Install using the language
specified by this value. See Table 34 on page
214.
existing. If MQ already exists on the system,
the same language will be used by default,
otherwise system is used.

Installing and migrating 213

 Table 33. Properties used by MQParms in the MSI stanza (continued)
Property Values Description
MQPSMS 0 |no 0 or no. MQParms does not wait for the
msiexec command to end (the default).
Any other value. MQParms waits for the
msiexec command to end.

MQPINUSE 0 |1 If MQPINUSE is set to 1, MQParms continues

installing even if IBM MQ files are in use. If
this option is used a reboot will be required to
complete the installation.

Table 34. Valid values for the MQPLANGUAGE property

Language Valid values
U.S. English English en_us 1033
German German de_de 1031
French French fr_fr 1036
Spanish Spanish es_es 1034
Italian Italian it_it 1040
Brazilian Portuguese pt_br 1046
Japanese Japanese ja_jp 1041
Korean Korean ko_kr 1042
Simplified Chinese zh_cn 2052
Traditional Chinese zh_tw 1028
Czech Czech cs_cz 1029
Russian Russian ru_ru 1049
Hungarian Hungarian hu_hu 1038
Polish Polish pl_pl 1045

A typical example of a parameter file is:

[MSI]
MQPLANGUAGE=1033
MQPLOG=%temp%\MQParms.log
MQPSMS=no
ADDLOCAL=CLIENT
/m miffile
REMOVE=""
/l*v c:\install.log

214 Installing and migrating IBM MQ

 Modifying a client installation on Windows
You modify the installation when an IBM MQ for Windows client is installed and you want to remove or
install some IBM MQ client features.

Procedure
1. Access the IBM MQ installation image.
The location might be a network location, or a local file system directory. See Where to find
downloadable installation images.
2. Locate Setup.exe in the Windows directory of the IBM MQ installation image.
• From a network location, this location might be m:\instmqs\Windows\Setup.exe
• From a local file system directory, this location might be C:\instmqs\Windows\Setup.exe
3. Start the installation process.
Either run Setup.exe from a command prompt, or double-click Setup.exe from Windows Explorer.
Note: If you are installing on a Windows system with UAC enabled, accept the Windows prompt to
allow the launchpad to run as elevated. During installation, you might also see Open File - Security
Warning dialog boxes that list International Business Machines Limited as the publisher. Click Run to
allow the installation to continue.
The IBM MQ Installation window is displayed.
4. Click Next to continue.
5. Select Modify, then click Next.
The Features panel is displayed.
6. To change the installation of a feature, complete the following steps:
a) Click the symbol next to the feature name to display a menu.
b) Select the required option from:
• Install this feature
• Install this feature and all its subfeatures (if any)
• Do not install this feature (remove if already installed).
The symbol next to the feature name changes to show the current installation option.
7. When your selections are complete, click Next.
The IBM MQ Setup window displays a summary of the installation you selected.
8. To continue, click Modify then wait until the progress bar is complete.
When the IBM MQ client is successfully installed, the IBM MQ Setup window displays the following
message: Installation Wizard Completed Successfully
9. Click Finish to close the window.

Modifying a client installation using Add/Remove Programs

On some versions of Windows, you can modify an installation by using Add/Remove Programs.
For Windows 7 follow these steps.
1. From the Windows taskbar, select Start > Control Panel.
2. Select Add/Remove Programs.
3. Select IBM MQ.
4. Select Change.
The IBM MQ Setup window with the Program Maintenance panel is displayed.
5. Select Modify, then click Next.
The Features panel is displayed.

Installing and migrating 215

 6. To change the installation of a feature:
a. Click the symbol next to the feature name to display a menu.
b. Select the required option from:
• Install this feature
• Install this feature and all its subfeatures (if any)
• Do not install this feature (remove if already installed).
The symbol next to the feature name changes to show the current installation option.
7. When your selections are complete, click Next.
8. The IBM MQ Setup window displays a summary of the installation you selected.
To continue, click Modify.
9. Wait until the progress bar is complete.
When the IBM MQ client is successfully installed, the IBM MQ Setup window displays the following
message:
Installation Wizard Completed Successfully
Click Finish to close the window.
10. For Windows 8, the Add/Remove Programs option uninstalls the whole product.
You need to run the setup.exe file from the original installation media to make any modifications to
the installation.

Modifying a client installation silently using msiexec

You can use msiexec to modify an IBM MQ client installation.
To silently modify an IBM MQ client installation using msiexec, follow the instructions on the installation
pages, but set the ADDLOCAL parameter to include the features you want to add, and set the REMOVE
parameter to the features you want to remove.
For example if you used ADDLOCAL="JavaMsg" and REMOVE="" it would modify the installation to include
the Java Messaging and Web Services feature.
The instructions for msiexec begin here: “Installing a client using msiexec” on page 204

Modifying a client installation silently using MQParms

You can use the MQParms command to modify an IBM MQ client installation.
To silently modify an IBM MQ client installation using MQParms, follow the instructions on the installation
pages, but set the ADDLOCAL parameter to include the features you want to add, and set the REMOVE
parameter to the features you want to remove.
For example if you used ADDLOCAL="JavaMsg" and REMOVE="" it would modify the installation to include
the Java Messaging and Web Services feature.
For details of the MQParms command, see “Installing a client using the MQParms command” on page
211.

Converting a trial license on Windows

Convert a trial license to a full license without reinstalling IBM MQ.
When the trial license expires, the "count-down" displayed by the strmqm command informs you the
license has expired, and the command does not run.

Before you begin

1. IBM MQ is installed with a trial license.

216 Installing and migrating IBM MQ

2. You have access to the installation media of a fully licensed copy of IBM MQ.

About this task

Run the setmqprd command to convert a trial license to a full license.
If you do not want to apply a full license to your trial copy of IBM MQ, you can uninstall it at any time.

Procedure
1. Obtain the full license from the fully licensed installation media.
The full license file is amqpcert.lic. On Windows it is in the \MediaRoot\licenses directory on
the installation media. It is installed into the bin directory on the IBM MQ installation path.
2. Run the setmqprd command from the installation that you are upgrading:

MQ_INSTALLATION_PATH\bin\setmqprd \MediaRoot\licenses\amqpcert.lic

Related reference
setmqprd

Displaying messages in your national language on Windows

systems
To display messages from a different national language message catalog, you must either set the
MQS_FORCE_NTLANGID environment variable, or change a regional setting.

About this task

Messages in U.S. English are automatically installed with IBM MQ
Messages in the national languages that IBM MQ supports are automatically installed. Messages are
displayed in the national language, based on the following order:
1. The value of the MQS_FORCE_NTLANGID environment variable, if set.
2. The regional format of the user that is displaying the message, if the language specified by the regional
format is supported by IBM MQ.
3. The Administrative system locale if the language specified by the system locale is supported by IBM
MQ.
4. US English, if no other supported language can be determined.
Note: The queue manager is usually launched by a service on the machine, and hence is running under
its own user account (for example MUSR_MQADMIN) or a specific domain account provided during install
time. See Local and domain user accounts for the IBM MQ Windows service for more information.
If you require messages in a language other than the one associated with the regional format of a user
account, perform the following steps:

Procedure
1. Globally set the MQS_FORCE_NTLANGID environment variable, to the language identifier of the desired
language, for messages displayed by the queue manager.
You should set the MQS_FORCE_NTLANGID system wide. Otherwise, every user displaying messages
needs to have the environment variable set individually.
The language identifier values, represented in hexadecimal notation, are listed in the following
Microsoft document: Language Identifier Constants and Strings
2. Reboot machines where queue managers are running as a service, for the environment variable to take
effect.

Installing and migrating 217

 Redistributable clients on Windows
The Windows 64-bit image is shipped in a Win64.zip file.

File names
The archive or .zip file names describe the file contents and equivalent maintenance levels.
For IBM MQ 9.4 the client images are available under the following file names:
Long Term Support: 9.4.0 IBM MQ C and .NET redistributable client for Windows x64
9.4.0.0-IBM-MQC-Redist-Win64.zip
Long Term Support: 9.4.0 IBM MQ JMS and Java redistributable client
9.4.0.0-IBM-MQC-Redist-Java.zip

Choosing the runtime files to distribute with an application

A script file named genmqpkg is provided by the redistributable client under the bin directory.
You can use the genmqpkg script to generate a smaller subset of files that are tailored to the needs of the
application, for which the files are intended to be distributed. You are asked a series of interactive Yes or
No questions to determine the runtime requirements for an IBM MQ
application.
Finally, genmqpkg asks you to supply a new target directory, where the script duplicates the required
directories and files.
Important: IBM support is only able to provide assistance with the full, unmodified set of files contained
within the redistributable client packages.

Other considerations
On Windows, the default data path of a non-installed client is %HOMEDRIVE%%HOMEPATH%
\IBM\MQ\data.
You can change the default directory of the data path, by using the MQ_OVERRIDE_DATA_PATH
environment variable.
Note: You must create the directory first, as the directory is not created automatically.
A redistributable client runtime co-exists with a full IBM MQ client or server installation, provided that
they are installed in different locations.
Important: Unpacking a redistributable image into the same location as a full IBM MQ installation is not
supported.

Classpath changes
The classpath used by dspmqver, setmqenv, and crtmqenv commands adds the
com.ibm.mq.allclient.jar and com.ibm.mq.jakarta.client.jar to the environment,
immediately following the com.ibm.mq.jar, and com.ibm.mqjms.jar.
An example of dspmqver output from the redistributable client on Windows:

Name: IBM MQ
Version: 9.4.0.0
Level: p940-940-L220415
BuildType: IKAP - (Production)
Platform: IBM MQ for Windows (x64 platform)
Mode: 64-bit
O/S: Windows 10 Professional x64 Edition, Build 7601: SP1
InstName: MQNI09200004
InstDesc: IBM MQ V9.4.0.0 (Redistributable)
Primary: No
InstPath: C:\Users\johndoe\Desktop\Redist

218 Installing and migrating IBM MQ

DataPath: C:\Users\johndoe\IBM\MQ\data
MaxCmdLevel: 940

Related concepts
“Redistributable IBM MQ clients” on page 26
The IBM MQ redistributable client is a collection of runtime files that are provided in a .zip or .tar file
that can be redistributed to third parties under redistributable license terms. This provides a simple way
of distributing applications and the runtime files that they require in a single package.

.NET application runtime - Windows only

Considerations when using the .NET application.
The runtime DLL files laid down in the redistributable images on Windows for .NET applications are
normally registered with the global assembly cache (GAC) by a user with system administrator privileges,
when installing the primary installation. However, this severely limits the benefits of redistribution.
The redistributable package on the Windows platform does not provide any tooling to register DLLs with
the GAC, so .NET applications have to locate the appropriate assemblies by other means. There are two
options that work in this situation.

Probing
After checking the GAC, the .NET runtime attempts to locate required assemblies through probing. The
first location checked is the application base, which is the root location where the application is being
run. See the information on How the Runtime Locates Assemblies on the Microsoft Web site for more
information.
Note that when using this approach, the maintenance level of the assemblies used when building
the .NET application must match those used at runtime - for example an application built at IBM MQ
8.0.0 Fix Pack 4 must be run with the IBM MQ 8.0.0 Fix Pack 4 redistributable client runtime.
Using this approach, a .NET application placed in the \bin directory alongside the IBM MQ assemblies
picks up assemblies from a primary IBM MQ installation (if one exists), falling back to the redistributable
copies.
1. Compile the .NET application under a full IBM MQ installation, that is csc \t:exe \r:System.dll
\r:amqmdnet.dll \lib: \out:nmqwrld.exe nmqwrld.cs.
2. Copy the exe file in the redistributable client .zip file into the \bin directory.

DEVPATH environment variable

An alternative, that allows your application to be built, distributed, extracted and run as previously, is to
use DEVPATH to locate the required assemblies. Unlike with the probing approach, this option overrides
any matching assemblies from the GAC. However it is for this reason that Microsoft discourages its use in
a production environment.
This approach can be effective where there is a possibility that a full IBM MQ installation is installed on
the client. However, there is a good reason to always use the redistributable assemblies.
1. Compile the .NET application under a full IBM MQ installation, that is csc \t:exe \r:System.dll
\r:amqmdnet.dll \lib: \out:nmqwrld.exe nmqwrld.cs)
2. Copy the .exe file into, or alongside, the redistributable client .zip file.
3. In the same directory as the .exe file, create an application configuration file with the name of
the .exe file suffixed by .config, that is nmqwrld.exe.config with the following contents:

<configuration>
<runtime>
<developmentMode developerInstallation="true" />
</runtime>
</configuration>

Installing and migrating 219

 4. Call setmqenv -s and set the DEVPATH environment variable to specify the \bin directory from the
redistributable image before running the application, that is:

set DEVPATH=%MQ_INSTALLATION_PATH%\bin

Starting and stopping trace for the .NET redistributable managed client
There are several different ways to enable trace for IBM MQ .NET applications. For more information, see
Tracing IBM MQ .NET applications.
You normally need to use the trace facility only at the request of IBM Support.

More information on .NET

For more information on .NET, see Writing and deploying IBM MQ .NET programs.
Related concepts
“Redistributable IBM MQ clients” on page 26
The IBM MQ redistributable client is a collection of runtime files that are provided in a .zip or .tar file
that can be redistributed to third parties under redistributable license terms. This provides a simple way
of distributing applications and the runtime files that they require in a single package.

Verifying an IBM MQ installation on Windows

The topics in this section provide instructions on how to verify a server or a client installation of IBM MQ
on Windows systems.

About this task

You can verify a local (stand-alone) server installation or a server-to-server installation of the IBM MQ
server:
• A local server installation has no communication links with other IBM MQ installations.
• A server-to-server installation does have links to other installations.
You can also verify that your IBM MQ MQI client installation completed successfully and that the
communication link is working.

Procedure
• To verify a local server installation, see “Verifying a local server installation using the command line on
Windows” on page 220.
• To verify a server-to-server installation, see “Verifying a server-to-server installation using the
command line on Windows” on page 222.
• To verify a client installation, see “Verifying a client installation on Windows” on page 225.

Verifying a local server installation using the command line on Windows

On Windows systems, you can verify a local installation by using the command line to create a simple
configuration of one queue manager and one queue.

Before you begin

To verify the installation, you must first install the samples package.
Before beginning the verification procedure, you might want to check that you have the latest fixes for
your system. For more information about where to find the latest updates, see “Checking requirements on
Windows” on page 168.

220 Installing and migrating IBM MQ

About this task
Use the following steps to configure your default queue manager from the command line. After the queue
manager is configured, use the amqsput sample program to put a message on the queue. You then use
the amqsget sample program to get the message back from the queue.
IBM MQ object definitions are case-sensitive. Any text entered as an MQSC command in lowercase is
converted automatically to uppercase unless you enclose it in single quotation marks. Make sure that you
type the examples exactly as shown.

Procedure
1. Set up your environment:
a) Set up environment variables for use with a particular installation by entering the following
command:

MQ_INSTALLATION_PATH\bin\setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

b) Check that the environment is set up correctly by entering the following command:

dspmqver

If the command completes successfully, and the expected version number and installation name
are returned, the environment is set up correctly.
2. Create a queue manager called QMA by entering the following command:

crtmqm QMA

Messages indicate when the queue manager is created, and when the default IBM MQ objects are
created.
3. Start the queue manager by entering the following command:

strmqm QMA

A message indicates when the queue manager starts.

4. Start MQSC by entering the following command:

runmqsc QMA

A message indicates when MQSC starts. MQSC has no command prompt.

5. Define a local queue called QUEUE1 by entering the following command:

DEFINE QLOCAL (QUEUE1)

A message indicates when the queue is created.

6. Stop MQSC by entering the following command:

end

Messages are shown, followed by the command prompt.

Note: Subsequent steps require that the samples package is installed.
7. Put a message on the queue by entering the following command:

Installing and migrating 221

 amqsput QUEUE1 QMA

The following messages are shown:

Sample AMQSPUT0 start

target queue is QUEUE1

8. Type some message text on one or more lines, where each line is a different message. Enter a blank
line to end the message input.
The following message is shown:

Sample AMQSPUT0 end

Your messages are now on the queue and the command prompt is shown.
9. Get the messages from the queue, by entering the following command:

amqsget QUEUE1 QMA

The sample program starts, and your messages are displayed.

Results
You have successfully verified your local installation.

Verifying a server-to-server installation using the command line on

Windows
You can verify a server-to-server installation using two servers, one as a sender and one as a receiver.

Before you begin

• On Windows, IBM MQ supports TCP, SNA, NetBios, and SPX.
The examples in this task use TCP/IP. If you do not use TCP, see Setting up communication for Windows.
• Make sure that you are a member of the IBM MQ administrators group (mqm) on each server.
• Decide which installation is the sender server and which installation is the receiver server. The
installations might be on the same system, or on different systems.

About this task

IBM MQ object definitions are case-sensitive. Any text entered as an MQSC command in lowercase is
converted automatically to uppercase unless you enclose it in single quotation marks. Make sure that you
type the examples exactly as shown.

Procedure
1. On the receiver server:
a) Check which ports are free, for example by running netstat. For more information about this
command, see the documentation of your operating system.
If port 1414 is not in use, make a note of 1414 to use as the port number in step 2 g. Use the same
number for the port for your listener later in the verification. If it is in use, note a port that is not in
use; for example 1415.
b) Set up the environment for the installation you are using by entering the following command at the
command prompt:

222 Installing and migrating IBM MQ

 MQ_INSTALLATION_PATH\bin\setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

c) Create a queue manager called QMB by entering the following command at the command prompt:

crtmqm QMB

Messages tell you that the queue manager has been created, and that the default IBM MQ objects
have been created.
d) Start the queue manager by entering the following command:

strmqm QMB

A message tells you when the queue manager has started.

e) Start MQSC by entering the following command:

runmqsc QMB

A message tells you that MQSC has started. MQSC has no command prompt.
f) Define a local queue called RECEIVER.Q by entering the following command:

DEFINE QLOCAL (RECEIVER.Q)

A message tells you the queue has been created.

g) Define a listener by entering the following command:
DEFINE LISTENER (LISTENER1) TRPTYPE (TCP) CONTROL (QMGR) PORT ( PORT_NUMBER )

Where port_number is the name of the port the listener runs on. This number must be the same as
the number used when defining your sender channel.
h) Start the listener by entering the following command:

START LISTENER (LISTENER1)

Note: Do not start the listener in the background from any shell that automatically lowers the
priority of background processes.
i) Define a receiver channel by entering the following command:

DEFINE CHANNEL (QMA.QMB) CHLTYPE (RCVR) TRPTYPE (TCP)

A message tells you when the channel has been created.

j) End MQSC by typing:

end

Some messages are displayed, followed by the command prompt.

2. On the sender server:
a) Set up the environment for the installation you are using by entering the following command at the
command prompt:

MQ_INSTALLATION_PATH\bin\setmqenv -s

Installing and migrating 223

 where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.
b) Create a queue manager called QMA by entering the following command at the command prompt:

crtmqm QMA

Messages tell you that the queue manager has been created, and that the default IBM MQ objects
have been created.
c) Start the queue manager, by entering the following command:

strmqm QMA

A message tells you when the queue manager has started.

d) Start MQSC by entering the following command:

runmqsc QMA

A message tells you that an MQSC session has started. MQSC had no command prompt.
e) Define a local queue called QMB (to be used as a transmission queue) by entering the following
command:

DEFINE QLOCAL (QMB) USAGE (XMITQ)

A message tells you when the queue has been created.

f) Define a local definition of the remote queue by entering the following command:

DEFINE QREMOTE (LOCAL.DEF.OF.REMOTE.QUEUE) RNAME (RECEIVER.Q) RQMNAME ('QMB') XMITQ (QMB)

g) Define a sender channel by entering the following command:

DEFINE CHANNEL (QMA.QMB) CHLTYPE (SDR) CONNAME ('CON-NAME(PORT)') XMITQ (QMB) TRPTYPE (TCP)

con-name is the TCP/IP address of the receiver system. If both installations are on the same
system, the con-name is localhost. port is the port you noted in 1 a. If you do not specify a port,
the default value of 1414 is used.
h) Start the sender channel by entering the following command:

START CHANNEL(QMA.QMB)

The receiver channel on the receiver server starts automatically when the sender channel starts.
i) Stop MQSC by entering the following command:

end

Some messages are displayed, followed by the command prompt.

j) If both the sender server and receiver server are installations on the same system, check that the
queue managers have been created on different installations by entering the following command:

dspmq -o installation

If the queue managers are on the same installation, move either QMA to the sender installation
or QMB to the receiver installation by using the setmqm command. For more information, see
setmqm.
k) Put a message on the local definition of the remote queue, which in turn specifies the name of the
remote queue. Enter the following command:

224 Installing and migrating IBM MQ

 amqsput LOCAL.DEF.OF.REMOTE.QUEUE QMA

A message tells you that amqsput has started.

l) Type some message text on one or more lines, followed by a blank line.
A message tells you that amqsput has ended. Your message is now on the queue and the
command prompt is displayed again.
3. On the receiver server:
a) Get the message from the queue on the receiver by entering the following command:

amqsget RECEIVER.Q QMB

The sample program starts, and your message is displayed. After a pause, the sample ends. Then
the command prompt is displayed.

Results
You have now successfully verified the server-to-server installation.

Verifying a client installation on Windows

You can verify that your IBM MQ MQI client installation completed successfully and that the
communication link is working.

About this task

The verification procedure shows how to create a queue manager called queue.manager.1, a local
queue called QUEUE1, and a server-connection channel called CHANNEL1 on the server.
It shows how to create the client-connection channel on the IBM MQ MQI client workstation. It then
shows how to use the sample programs to put a message onto a queue, and get the message from the
queue.
The example does not address any client security issues. See Setting up IBM MQ MQI client security for
details if you are concerned with IBM MQ MQI client security issues.
The verification procedure assumes that:
• The full IBM MQ server product has been installed on a server.
• The server installation is accessible on your network.
• The IBM MQ MQI client software has been installed on a client system.
• The IBM MQ sample programs have been installed.
• TCP/IP has been configured on the server and client systems. For more information, see Configuring
connections between the server and client.

Procedure
1. Set up the server and client by using the command line.
For more information, see “Setting up the server and client using the command line on Windows” on
page 226.
2. Test the communications between client and server.
For more information, see “Testing communication between a client and a server on Windows” on
page 229.
Related tasks
“Installing an IBM MQ client on Windows” on page 203

Installing and migrating 225

 This topic describes how to install IBM MQ client on Windows systems. This procedure can be used for
installing a first or a subsequent installation.

Setting up the server and client using the command line on Windows
You can use the command line to create the objects that you need to use to verify a client installation
on Linux. On the server you create a queue manager, a local queue, a listener, and a server-connection
channel. You must also apply security rules to allow the client to connect and make use of the queue
defined. On the client you create a client-connection channel. After setting up the server and client, you
can then use the sample programs to complete the verification procedure.

Before you begin

Before starting this task, review the information in “Verifying a client installation on Windows” on page
225.

About this task

This task explains how to use the command line to set up the server and client so that you can verify your
client installation.

Procedure
1. Set up the server by following the instructions in “Setting up the server using the command line on
Windows” on page 226.
2. Set up the client by following instructions in “Connecting to a queue manager, using the MQSERVER
environment variable on Windows” on page 228.

What to do next
Test the communications between client and server by following the instructions in “Testing
communication between a client and a server on Windows” on page 229.

Setting up the server using the command line on Windows

Follow these instructions to create a queue manager, queue, and channel on the server. You can then use
these objects to verify the installation.

About this task

These instructions assume that no queue manager or other IBM MQ objects have been defined.
IBM MQ object definitions are case-sensitive. Any text entered as an MQSC command in lowercase is
converted automatically to uppercase unless you enclose it in single quotation marks. Make sure that you
type the examples exactly as shown.

Procedure
1. Create a user ID on the server that is not in the mqm group.
This user ID must exist on the server and client. This is the user ID that the sample applications must
be run as, otherwise a 2035 error is returned.
2. You must set various environment variables so that the installation can be used in the current shell.
You can set the environment variables by entering the following command:

MQ_INSTALLATION_PATH\bin\setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed

3. Create a queue manager called QUEUE.MANAGER.1 by entering the following command:

226 Installing and migrating IBM MQ

 crtmqm QUEUE.MANAGER.1

You see messages telling you that the queue manager has been created.
4. Start the queue manager by entering the following command:

strmqm QUEUE.MANAGER.1

A message tells you when the queue manager has started.

5. Start MQSC by entering the following command:

runmqsc QUEUE.MANAGER.1

A message tells you that an MQSC session has started. MQSC has no command prompt.
6. Define a local queue called QUEUE1 by entering the following command:

DEFINE QLOCAL(QUEUE1)

A message tells you when the queue has been created.

7. Allow the user ID that you created in step 1 to use QUEUE1 by entering the following command:

SET AUTHREC PROFILE(QUEUE1) OBJTYPE(QUEUE) PRINCIPAL(' non_mqm_user ') AUTHADD(PUT,GET)

where non_mqm_user is the user ID created in step 1. A message tells you when the authorization
has been set. You must also run the following command to give the user ID authority to connect:

SET AUTHREC OBJTYPE(QMGR) PRINCIPAL(' non_mqm_user ') AUTHADD(CONNECT)

If this command is not run, a 2305 stop error is returned.

8. Define a server-connection channel by entering the following command:

DEFINE CHANNEL (CHANNEL1) CHLTYPE (SVRCONN) TRPTYPE (TCP)

A message tells you when the channel has been created.

9. Allow your client channel to connect to the queue manager and run under the user ID that you
created in step 1, by entering the following MQSC command:

SET CHLAUTH(CHANNEL1) TYPE(ADDRESSMAP) ADDRESS(' client_ipaddr ') MCAUSER(' non_mqm_user ')

where client_ipaddr is the IP address of the client system, and non_mqm_user is the user ID created
in step 1. A message tells you when the rule has been set.
10. Define a listener by entering the following command:

DEFINE LISTENER (LISTENER1) TRPTYPE (TCP) CONTROL (QMGR) PORT (port_number)

where port_number is the number of the port the listener is to run on. This number must be the same
as the number used when defining your client-connection channel in “Installing an IBM MQ client on
Windows” on page 203.
Note: If you omit the port parameter from the command, a default value of 1414 is used for the
listener port. If you want to specify a port other than 1414, you must include the port parameter in
the command, as shown.
11. Start the listener by entering the following command:

Installing and migrating 227

 START LISTENER (LISTENER1)

12. Stop MQSC by entering:

end

You see some messages, followed by the command prompt.

What to do next
Follow the instructions to set up the client. See “Connecting to a queue manager, using the MQSERVER
environment variable on Windows” on page 228.

Connecting to a queue manager, using the MQSERVER environment variable on Windows

When an IBM MQ application is run on the IBM MQ MQI client, it requires the name of the MQI channel,
the communication type, and the address of the server to be used. Provide these parameters by defining
the MQSERVER environment variable.

Before you begin

Before you start this task, you must complete the task, “Setting up the server using the command line on
Windows” on page 226, and save the following information:
• The host name or IP address of the server and port number that you specified when creating the
listener.
• The channel name of the server-connection channel.

About this task

This task describes how to connect an IBM MQ MQI client, by defining the MQSERVER environment
variable on the client.
You can give the client access to the generated client channel definition table, amqclchl.tab instead;
see Accessing client-connection channel definitions.
Alternatively, on Windows, if Active Directory support is enabled, the client discovers the client-
connection information dynamically from the Active Directory.

Procedure
1. Log in as the userid that you created in Step 1 of “Setting up the server using the command line on
Windows” on page 226.
2. Check the TCP/IP connection. From the client, enter one of the following commands:
• ping server-hostname
• ping n.n.n.n
n.n.n.n represents the network address. You can set the network address in IPv4 dotted decimal
form, for example, 192.0.2.0. Alternatively, set the address in IPv6 hexadecimal form, for
example 2001:0DB8:0204:acff:fe97:2c34:fde0:3485.
If the ping command fails, correct your TCP/IP configuration.
3. Set the MQSERVER environment variable. From the client, enter the following command:

SET MQSERVER=CHANNEL1/TCP/server-address(port)

Where:
• CHANNEL1 is the server-connection channel name.

228 Installing and migrating IBM MQ

 • server-address is the TCP/IP host name of the server.
• port is the TCP/IP port number the server is listening on.
If you do not give a port number, IBM MQ uses the one specified in the qm.ini file, or the client
configuration file. If no value is specified in these files, IBM MQ uses the port number identified in the
TCP/IP services file for the service name MQSeries. If an MQSeries entry in the services file does not
exist, a default value of 1414 is used. It is important that the port number used by the client and the
port number used by the server listener program are the same.

What to do next
Use the sample programs to test communication between the client and server; see “Testing
communication between a client and a server on Windows” on page 229.

Testing communication between a client and a server on Windows

On the IBM MQ MQI client workstation, use the amqsputc sample program to put a message on the
queue at the server workstation. Use the amqsgetc sample program to get the message from the queue
back to the client.

Before you begin

Complete the previous topics in this section:
• Set up a queue manager, channels, and queue.
• Open a command window.
• Set system environment variables.

About this task

Note that IBM MQ object definitions are case-sensitive. Text entered as an MQSC command in lowercase
is converted automatically to uppercase unless you enclose it in single quotation marks. Make sure that
you type the examples exactly as shown.

Procedure
1. Change into the MQ_INSTALLATION_PATH\Tools\C\Samples\Bin directory for 32 bit systems or the
MQ_INSTALLATION_PATH\Tools\C\Samples\Bin64 directory for 64 bit systems.
MQ_INSTALLATION_PATH represents the high-level directory in which IBM MQ is installed.
2. You must set certain environment variables so that the installation can be used in the current shell.
You can set the environment variables by entering the following command:

MQ_INSTALLATION_PATH\bin\setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed

3. Start the PUT program for QUEUE1 on QUEUE.MANAGER.1 by entering the following command:

amqsputc QUEUE1 QUEUE.MANAGER.1

If the command is successful, the following messages are displayed:

Sample AMQSPUT0 start target queue is QUEUE1

Tip: You might get the error, MQRC_NOT_AUTHORIZED ( 2035 ). By default, channel authentication
is enabled when a queue manager is created. Channel authentication prevents privileged users
accessing a queue manager as an IBM MQ MQI client. For verifying the installation, you can either

Installing and migrating 229

 change the MCA user ID to a non-privileged user, or disable channel authentication. To disable channel
authentication run the following MQSC command:

ALTER QMGR CHLAUTH(DISABLED)

When you finish the test, if you do not delete the queue manager, re-enable channel authentication:

ALTER QMGR CHLAUTH(ENABLED)

4. Type some message text, then press Enter twice.

The following message is displayed:

Sample AMQSPUT0 end

Your message is now on the queue that is on the server queue manager.
5. Start the GET program for QUEUE1 on QUEUE.MANAGER.1 by entering the following command:

amqsgetc QUEUE1 QUEUE.MANAGER.1

The sample program starts, and your message is displayed. After a short pause (approximately 30
seconds), the sample ends and the command prompt is displayed again.

Results
You have now successfully verified the client installation.

What to do next
1. You must set various environment variables on the server so that the installation can be used in the
current shell. You can set the environment variables by entering the following command:

MQ_INSTALLATION_PATH\bin\setmqenv -s

where MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

2. On the server, stop the queue manager by entering the following command:

endmqm QUEUE.MANAGER.1

3. On the server, delete the queue manager by entering the following command:

dltmqm QUEUE.MANAGER.1

Uninstalling IBM MQ on Windows

You can uninstall the IBM MQ MQI clients and servers on Windows systems by using the control panel,
the command line ( msiexec ), MQParms, or by using the installation media, in which case you can
optionally remove queue managers as well.

Before you begin

By default, uninstallation logging is not enabled on Windows. To ensure that you receive an uninstallation
log, carry out the following procedure:
1. In a command prompt, open the registry editor by issuing the command regedit.
2. Create, or edit, the appropriate registry key:
HKEY_LOCAL_MACHINE\Software\Policies\Microsoft\Windows\Installer

230 Installing and migrating IBM MQ

3. Under this registry key add the following information:
Name
Logging
Data type
REG_SZ
Value
voicewarmup
4. Save the updated registry key.

Procedure
The first part of the procedure ensures that there are no IBM MQ programs or processes running:
1. If you are running IBM MQ with the Microsoft Cluster Service (MSCS), remove the queue managers
from MSCS control before uninstalling IBM MQ. Perform the following steps for each queue manager
currently under MSCS control :
a) Take the queue manager resource offline.
b) Destroy the resource instance.
c) Migrate the queue manager files back from shared drives. This step is shown as optional in
Removing a queue manager from MSCS control. However, it is mandatory in this case.
2. Stop all IBM MQ applications associated with the installation you are uninstalling.
3. Close all Managed File Transfer agents.
If you have a Managed File Transfer Agent running, close it by using the fteStopAgent command;
see fteStopAgent (stop a Managed File Transfer Agent).
4. For a server installation, end all IBM MQ activity:
a) Log in as a user in the group mqm.
b) Stop all running queue managers and listeners by using the IBM MQ Explorer, or by entering the
following commands:
i) Set up your environment to work with the installation you want to uninstall by entering the
following command:

MQ_INSTALLATION_PATH\bin\setmqenv -s

where MQ_INSTALLATION_PATH is the location where IBM MQ is installed.

ii) For each queue manager, enter the following command to stop the queue manager:

endmqm queue_manager_name

iii) For each queue manager, enter the following command to stop any listeners associated with
the queue manager:

endmqlsr -m queue_manager_name

5. Stop IBM MQ.

To do this right-click the IBM MQ icon in the system tray, then select Stop IBM MQ.
6. Close all IBM MQ windows.
7. Stop any monitoring service.
When all processes associated with IBM MQ are no longer running, you can uninstall IBM MQ:
8. Uninstall IBM MQ by using one of the following methods:
• Use the Windows Control Panel. This process is described in: “Uninstalling IBM MQ using the
control panel” on page 232. This method does not remove the queue manager data.

Installing and migrating 231

 • Use the command line by running the msiexec command as described in: “Uninstalling IBM MQ
using msiexec” on page 233. This method does not remove the queue manager data.
• Use the appropriate parameters with MQParms. This process is described in “Uninstalling IBM MQ
using MQParms” on page 235. This method does not remove the queue manager data.
• Use the installation media, by selecting the appropriate option as described in: “Uninstalling IBM
MQ on Windows using the installation media” on page 235. The option to remove queue manager
data is displayed in the Removing Server feature panel, if appropriate.
If you have to cancel the uninstallation process before it is finished, you might have to reconfigure
IBM MQ with the Prepare IBM MQ wizard because the rollback of the deletion of the IBM MQ service
is unable to set the service's user account password. Use the following command to reconfigure IBM
MQ:

MQ_INSTALLATION_PATH\bin\amqmjpse.exe -r

For more information about the Prepare IBM MQ Wizard, see “Configuring IBM MQ with the Prepare
IBM MQ Wizard” on page 194.
9. Check the Windows event log and restart the system if necessary.
If event ID 10005 is written to the Windows event log, you must restart the system to complete the
uninstallation process.
10. If you are uninstalling the last or only installation of IBM MQ, you can remove all the information
about previous installations that is retained on the system, if you want to. You should use the
ResetMQ.cmd for this purpose; see “Clearing IBM MQ installation settings” on page 174 for more
information.
The following registry values remain after uninstallation:
• My Computer\HKEY_LOCAL_MACHINE\SOFTWARE\IBM\WebSphere MQ\LogDefaultPath
• My Computer\HKEY_LOCAL_MACHINE\SOFTWARE\IBM\WebSphere MQ\WorkPath
• My Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\IBM\WebSphere
MQ\LogDefaultPath
• My Computer\HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\IBM\WebSphere
MQ\WorkPath
Data folders will also remain and are located at MQ_DATA_PATH\Config, where MQ_DATA_PATH is
the location of the IBM MQ data directory. Most of the remaining files contain text such as INI files,
error logs, and FDC files. The executable shared library mqzsd.dll also remains.
If a client is installed on a system where the LogDefaultPath registry value remains from a
previous server installation, a client installation will attempt to create this directory if it does
not already exist. If this behavior is not wanted, remove the LogDefaultPath registry value before
installing the client.

Uninstalling IBM MQ using the control panel

You can uninstall IBM MQ by using the control panel to remove all currently installed features.

Before you begin

Start the uninstalling process by following the steps described in “Uninstalling IBM MQ on Windows” on
page 230.
If you no longer require the queue managers that are on the system, delete them by using the IBM MQ
Explorer or the dltmqm command.

Procedure
1. From the Windows taskbar, open the control panel by clicking Start > Settings > Control Panel, or
Start > Control Panel.

232 Installing and migrating IBM MQ

2. Open Programs and Features.
3. Click IBM MQ (installation_name), where installation_name is the name of the installation you want to
remove.
4. Click Remove or Uninstall and click Yes to confirm.
If User Account Control (UAC) is enabled, accept the Windows prompt to allow the uninstallation to run
as elevated. The program then begins and runs to completion.

What to do next
Complete the steps that you started in “Uninstalling IBM MQ on Windows” on page 230.

Uninstalling IBM MQ using msiexec

You can uninstall IBM MQ by running the msiexec command from the command line to remove all
currently installed features, or selected features.

Before you begin

This task describes one of several uninstallation options that you can choose from when uninstalling IBM
MQ as described in “Uninstalling IBM MQ on Windows” on page 230. Before starting this task, refer to
“Uninstalling IBM MQ on Windows” on page 230 for more information.
If you no longer require the queue managers that are on the system, delete them by using the IBM MQ
Explorer or the dltmqm command.

About this task

You can use the msiexec command to uninstall IBM MQ either by running the msiexec command with
a parameter that calls a response file, or by entering the required msiexec parameters on the command
line.
Important: When specifying which features to remove with the REMOVE parameter:
• If you want to silently uninstall the Server feature, and the Web Administration (Web) feature
is installed, you must also silently uninstall the Web feature at the same time by specifying
REMOVE="Web,Server".
• If you want to silently uninstall the Java Runtime Environment (JRE) feature, and the Web
Administration (Web) feature is installed, you must also silently uninstall the Web feature at the same
time by specifying REMOVE="Web,JRE".
If you are running IBM MQ on Windows with User Account Control (UAC) enabled, you must invoke the
silent uninstallation from an elevated command prompt. Elevate a command prompt by using a right-click
to start the command prompt and choose Run as administrator.
In all of the examples of commands shown, the variable names used are as follows:
• installation_name is the name of the installation you want to remove.
• product_code is the value shown for MSIProdCode in the output of the following command:

dspmqinst -n installation_name

An example of a product code is {0730749B-080D-4A2E-B63D-85CF09AE0EF0}.

Procedure
• To silently uninstall IBM MQ by running the msiexec command with a parameter that calls a response
file:
a) Set which features to uninstall, and whether to keep existing queue managers in the response file.

Installing and migrating 233

 A response file is an ASCII text file that contains the parameter values that you want to set for
the uninstallation. The response file has a format similar to a Windows .ini file, and contains the
stanza [Response]. This stanza contains parameters that the msiexec command can use, in the
form of property = value pairs. The msiexec command ignores any other stanzas in the file.
This is an example of a simple uninstallation [Response] stanza:

[Response] REMOVE="ALL"

For more information about how to create a response file, including which parameters you can
specify, see “Creating and using a response file for server installation” on page 184.
b) To silently uninstall IBM MQ using the response file, enter the following
command: msiexec /x {product_code} /l*v "c:\removal.log" /q USEINI="response_file"
INSTALLATIONNAME="installation_name"
• To uninstall IBM MQ by entering the required msiexec parameters on the command line, enter one of
the following commands:
– To invoke an interactive uninstallation giving you the option to remove queue manager data
(providing there are no other IBM MQ installations remaining):

msiexec /x {product_code} /l*v "c:\removal.log" REMOVE="All"

INSTALLATIONNAME="installation_name"

If you are running IBM MQ on a Windows system with User Account Control (UAC) enabled, you
might see Open File - Security Warning dialog boxes during uninstallation that list International
Business Machines Limited as the publisher. Click Run to allow the uninstallation to continue.
– To invoke a silent uninstallation that does not remove any queue manager data:

msiexec /x {product_code} /l*v "c:\removal.log" /q REMOVE="All"

INSTALLATIONNAME="installation_name"

– To invoke a silent uninstallation and remove any queue manager data (only valid when removing the
final server installation):

msiexec /x {product_code} /l*v "c:\removal.log" /q REMOVE="All" KEEPQMDATA="delete"

INSTALLATIONNAME="installation_name"

– To monitor the progress of the uninstalling process and not remove any queue manager data:

msiexec /x {product_code} /l*v "c:\removal.log" INSTALLATIONNAME="installation_name"

If you are running IBM MQ on a Windows system with User Account Control (UAC) enabled, you
might see Open File - Security Warning dialog boxes during uninstallation that list International
Business Machines Limited as the publisher. Click Run to allow the uninstallation to continue.
– To invoke a silent uninstallation and not remove any queue manager data:

msiexec /x {product_code} /l*v "c:\removal.log" /q INSTALLATIONNAME="installation_name"

Results
After the command is entered, the command prompt immediately reappears and IBM MQ is uninstalled
as a background process. If you entered parameters to produce a log, check this file to see how the
uninstallation is progressing. If the uninstallation finishes successfully, you see the message Removal
completed successfully in the log file.

What to do next
Complete the steps that you started in “Uninstalling IBM MQ on Windows” on page 230.

234 Installing and migrating IBM MQ

Related concepts
“IBM MQ features for Windows systems” on page 158
You can select the features that you require when you install IBM MQ.
Related tasks
“Installing the server using msiexec” on page 179
IBM MQ on Windows uses the MSI technology to install software. MSI provides both an interactive
installation and a non interactive installation.
“Modifying a server installation silently using msiexec” on page 202
You can silently remove or install IBM MQ features on Windows by using msiexec.

Uninstalling IBM MQ using MQParms

You can uninstall IBM MQ by running the MQParms command from the command line to remove all
currently installed features.

Before you begin

Start the uninstalling process by following the steps described in “Uninstalling IBM MQ on Windows” on
page 230.

Procedure
1. Follow the instructions on the MQParms installation pages to uninstall IBM MQ non-interactively. See:
“Installing the server using the MQParms command” on page 188.
a) Set the ADDLOCAL parameter to empty (ADDLOCAL="").
b) Set the REMOVE parameter to "ALL" (REMOVE="ALL").
2. If you have multiple versions of IBM MQ installed on your system, specify the product code that
identifies the installation you want to remove.
Type the following command:

MQParms.exe parameter_file/i "{product_code}"

where
• parameter_file is the file that contains the required parameter values. If this file is not in the
same folder as MQParms.exe, specify the full path and file name. If you do not specify a parameter
file, the default is MQParms.ini.
• product_code is the value shown for MSIProdCode in the output of the following command:

dspmqinst -n installation_name

where installation_name is the name of the installation you want to remove. An example of a
product code is {0730749B-080D-4A2E-B63D-85CF09AE0EF0}.

What to do next
Complete the steps that you started in “Uninstalling IBM MQ on Windows” on page 230.

Uninstalling IBM MQ on Windows using the installation media

You can uninstall IBM MQ by using the installation media to remove all currently installed features and
optionally remove existing queue managers and their data.

Before you begin

Start the uninstalling process by following the steps described in “Uninstalling IBM MQ on Windows” on
page 230.

Installing and migrating 235

 Procedure
1. Download the compressed file that contains the installation image, then uncompress it into a
temporary directory.
2. Navigate to that directory, then double-click Setup.exe to start the installation process.
The IBM MQ Installation Launchpad window is displayed.
3. Click IBM MQ Installation.
4. Click Launch IBM MQ Installer and click Next until the IBM MQ Program Maintenance panel is
displayed with a welcome message.
If this panel is not displayed, IBM MQ for Windows is not currently installed.
5. Click Maintain or upgrade an existing instance and if there is more than one installation of IBM
MQ on the system, select which installation you want to remove. Click Next and in the Program
Maintenance panel, click Remove, then Next.
6. If you are uninstalling the last or only server, and there are any queue managers on the system, the
Removing Server feature panel is shown.
Click one of the following options:
• Keep: keep existing queue managers and their objects.
• Remove: remove existing queue managers and their objects.
Click Next.
The Remove IBM MQ panel is displayed, with a summary of the installation to be removed.
7. Click Remove to continue.
If there are any messages that state that locked files are found, ensure that there are no IBM MQ
programs running; see “Uninstalling IBM MQ on Windows” on page 230.
When IBM MQ has been uninstalled, a message indicates completion.
8. Click Finish.

What to do next
Complete the steps that you started in “Uninstalling IBM MQ on Windows” on page 230.

Installing IBM MQ Advanced for Multiplatforms

Installation tasks associated with IBM MQ Advanced for Multiplatforms are grouped in this section.

About this task

IBM MQ Advanced is a single license entitlement that, in addition to IBM MQ itself, provides entitlement
to:
• Advanced Message Security
• Managed File Transfer
• MQ Telemetry

• Replicated data queue managers (RDQM)

For more information, see IBM MQ license information.

Procedure
• “Installing and uninstalling AMS on Multiplatforms” on page 237.
• “Installing Managed File Transfer ” on page 243.
• “Installing MQ Telemetry” on page 249.

236 Installing and migrating IBM MQ

 “Installing RDQM (replicated data queue managers)” on page 255.
Related reference
DISPLAYQMGR ADVCAP
MQCMD_INQUIRE_Q_MGR MQIA_ADVANCED_CAPABILITY

Installing and uninstalling AMS on Multiplatforms

Installation and uninstallation, by platform, for Advanced Message Security (AMS) on Multiplatforms.

About this task

Advanced Message Security is a separately installed component of IBM MQ and is another option on
the IBM MQ installer. Make sure that you purchase a license for using IBM MQ Advanced before the
installation (see IBM MQ license information).

Procedure
• “Installing AMS on Multiplatforms” on page 237
• “Uninstalling AMS on Multiplatforms” on page 240

Installing AMS on Multiplatforms

Use the information for your platform to guide you through installing the Advanced Message Security
(AMS) component.

Before you begin

Make sure the following IBM MQ components are installed in your environment:
• MQSeriesRuntime
• MQSeriesServer

About this task

For information about installing Advanced Message Security follow the guidance for the appropriate
platform.

Procedure
• “Installing Advanced Message Security on AIX” on page 237
• “Installing Advanced Message Security on IBM i” on page 238
• “Installing Advanced Message Security on Linux” on page 239
• “Installing AMS on Windows using the Launchpad” on page 240

Installing Advanced Message Security on AIX

You can install Advanced Message Security component on AIX platforms using either system
management interface tool (SMIT) or the command line.

Installing using SMIT

Procedure
1. Log on as root.
2. Change the directory to the location of the installation packages.
3. Start the system management interface tool (SMIT).
The system management menu is displayed.
4. Select the required SMIT window using the following sequence:

Installing and migrating 237

 Software Installation and Maintenance
Install and Update Software
Install Software

5. Enter the directory location of the installation package.

6. Press F4 to list the software in the SOFTWARE name option.
7. Select the mqm.ams.rte and press Enter.
8. Accept the default setting for the remaining options and press Enter.

Results
Advanced Message Security has been installed successfully.

Installing using command line

Procedure
1. Log on as root.
2. Set your current directory to the location of the installation file. The location might be a network
location, or a local file system directory.
3. Run the following command:

installp -a -c -Y -d. mqm.ams.rte

Note the period, signifying the current directory, following the -d parameter.

Results
Advanced Message Security component has been installed successfully.

Installing Advanced Message Security on IBM i

You can install Advanced Message Security component on IBM i.

Procedure
Install AMS using the command:

RSTLICPGM LICPGM(5724H72) DEV(installation device) OPTION(2) OUTPUT(*PRINT)

where the parameters of RSTLICPGM are:

LICPGM(5724H72)
The product identifier for IBM MQ for IBM i.
DEV(installation device)
The device from which the product is to be loaded, typically an optical drive, for example, OPT01.
OPTION(2)
Install Advanced Message Security for IBM i
OUTPUT(*PRINT)
The output is printed with the spooled output of the job.

Results
The AMS component has been installed successfully.
Once AMS is installed on an IBM MQ server installation, any:
• Queue managers that are subsequently started enable security policy management features.

238 Installing and migrating IBM MQ

• Applications that connect to the queue manager enable interceptors.

What to do next
See Setting up certificates and the keystore configuration file on IBM i for details on setting up your
security policy.

Installing Advanced Message Security on Linux

You can install Advanced Message Security on Linux platforms.

Procedure
1. Log on as root.
2. Set your current directory to the location of the installation file. The location might be a network share,
or a local file system directory.
3. Optional: If this installation is not the first installation on the system, run the crtmqpkg command to
create a unique set of packages to install on the system.
Before you can run the crtmqpkg command on Linux, you must have the pax and rpmbuild
commands installed. These commands are not supplied as part of the product. You must get them
from your Linux distribution supplier. The rpmbuild command is located in the rpm-build package.
a) Enter the following command:

./crtmqpkg suffix

where suffix is a name of your choosing, that uniquely identifies the installation packages on the
system. suffix is not the same as an installation name, although the names can be identical. suffix is
limited to 16 characters in the ranges A-Z, a-z, and 0-9.
Note: This command creates a full copy of the installation packages in a subdirectory of /var/tmp.
You must ensure that the system has enough space before running the command.
b) Set your current directory to the location specified when the crtmqpkg command completes.
This directory is a subdirectory of /var/tmp/mq_rpms, in which the unique set of packages is
created. The packages have the suffix value contained within the filename. For example, using a
suffix of "1":

./crtmqpkg 1

there is a subdirectory named /var/tmp/mq_rpms/1/i386 and the packages are renamed, for
example:

From: MQSeriesAMS-V.R.M-F.i386.rpm
To: MQSeriesAMS_1-V.R.M-F.i386.rpm

where:
V
Represents the version of the product that you are installing
R
Represents the release of the product that you are installing
M
Represents the modification of the product that you are installing
F
Represents the fix pack level of the product that you are installing
4. In the command line, issue the following command:

Installing and migrating 239

 This example shows a minimum installation:

rpm -iv package_name

where package_name is one of the following:

• MQSeriesAMS-V.R.M-F.i386.rpm
• MQSeriesAMS-V.R.M-F.x86_64.rpm
• MQSeriesAMS-V.R.M-F.ppc.rpm
• MQSeriesAMS-V.R.M-F.s390.rpm

Results
Advanced Message Security has been installed successfully.

Installing AMS on Windows using the Launchpad

Access the IBM MQ installation image. Run the Launchpad. Follow the instructions on screen to install the
Advanced Message Security component (AMS) on Windows.

Procedure
1. Access the IBM MQ installation image.
The location might be a network location, or a local file system directory. See Where to find
downloadable installation images.
2. Locate Setup.exe in the base directory of the IBM MQ installation image.
• From a network location, this location might be m:\instmqs\Setup.exe
• From a local file system directory, this location might be C:\instmqs\Setup.exe
3. Start the installation process.
Either run Setup.exe from a command prompt, or double-click Setup.exe from Windows Explorer.
Note: If you are installing on a Windows system with UAC enabled, accept the Windows prompt to
allow the launchpad to run as elevated. During installation, you might also see Open File - Security
Warning dialog boxes that list International Business Machines Limited as the publisher. Click Run to
allow the installation to continue.
The IBM MQ Installation window is displayed.
4. Follow the instructions on screen.

Uninstalling AMS on Multiplatforms

Use the information for your platform to uninstall the Advanced Message Security (AMS) component.

Procedure
• “Uninstalling AMS on AIX” on page 241
• “Uninstalling AMS on Linux” on page 242
• “Uninstalling AMS on Windows” on page 243
Related tasks
“Installing AMS on Multiplatforms” on page 237

240 Installing and migrating IBM MQ

Use the information for your platform to guide you through installing the Advanced Message Security
(AMS) component.

Uninstalling AMS on AIX

On AIX platforms, you can remove Advanced Message Security component either using SMIT or the
command line.

Procedure
1. Stop all IBM MQ applications associated with the installation you are uninstalling.
2. For a server installation, end any IBM MQ activity associated with the installation you are uninstalling:
a) Log in as a user in the group mqm.
b) Set up your environment to work with the installation you want to uninstall. Enter the following
command:

. MQ_INSTALLATION_PATH/bin/setmqenv

where . MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

c) Display the state of all queue managers on the system. Enter the following command:

dspmq -o installation

d) Stop all running queue managers associated with the installation you want to uninstall. Enter the
following command for each queue manager:

endmqm QMgrName

e) Stop any listeners associated with the queue managers. Enter the following command for each
queue manager:

endmqlsr -m QMgrName

3. Log in as root.
4. Uninstall AMS component using either installp or smit. If AMS component was installed in a
non-default location, you must use installp to uninstall.
• Uninstall using installp by entering one of the following commands:
– For an installation in the default location /usr/mqm

installp -u mqm.ams.rte

– For an installation in a non-default location:

installp -R
usil -u mqm.ams.rte

where usil is the path of the User Specified Installation Location (USIL) specified when the
product was installed.
• Uninstall using smit:
a. Select the required smit window using the following sequence:

Software Installation and Maintenance

Software Maintenance and Utilities
Remove Installed Software

Installing and migrating 241

 b. List the software in the SOFTWARE name field:
i) Enter .
ii) Press F4
c. Select the file sets to uninstall from the list (those beginning with mqm), and press Enter. There
is an option at this stage to do a preview. Leave the option set to the default value of Yes to
preview the file sets you are uninstalling, or select No to not preview these file sets.
d. Press Enter on the Remove Installed Software panel, it asks whether you are sure, press Enter.

Results
The Advanced Message Security component has been uninstalled.

Uninstalling AMS on Linux

Use the rpm command to remove Advanced Message Security component on Linux platforms.

Procedure
1. Stop all IBM MQ applications associated with the installation you are uninstalling.
2. For a server installation, end any IBM MQ activity associated with the installation you are uninstalling:
a) Log in as a user in the group mqm.
b) Set up your environment to work with the installation you want to uninstall. Enter the following
command:

. MQ_INSTALLATION_PATH/bin/setmqenv

where . MQ_INSTALLATION_PATH refers to the location where IBM MQ is installed.

c) Display the state of all queue managers on the system. Enter the following command:

dspmq -o installation

d) Stop all running queue managers associated with the installation you want to uninstall. Enter the
following command for each queue manager:

endmqm QMgrName

e) Stop any listeners associated with the queue managers. Enter the following command for each
queue manager:

endmqlsr -m QMgrName

3. Log in as root.
4. Run the following command:

rpm -e package_name

where package_name is MQSeriesAMS-V.R.M-F

V
Represents the version of the product that you are uninstalling
R
Represents the release of the product that you are uninstalling
M
Represents the modification of the product that you are uninstalling

242 Installing and migrating IBM MQ

 F
Represents the fix pack level of the product that you are uninstalling

Results
The Advanced Message Security component has been uninstalled.

Uninstalling AMS on Windows

You can uninstall Advanced Message Security component using the GUI uninstallation wizard, or a
command-line interface.

Using the installation wizard

Procedure
1. Download the compressed file that contains the installation image, then uncompress it into a
temporary directory.
2. Navigate to that directory, then double-click setup.exe to start the installation process.
The IBM MQ Installation Launchpad window is displayed.
3. Click the IBM MQ Installation.
4. Click Launch IBM MQ Installer. Click Next until the IBM MQ Program Maintenance panel is displayed
with a welcome message.
If this panel is not displayed, IBM WebSphere MQ for Windows 7.5 is not installed on this machine.
When presented with the option, select to remove/maintain or upgrade.
5. Select Maintain or upgrade an existing instance, then click Next.
6. If there are any existing queue managers, the Removing Server feature panel is displayed.
Click one of the following options, then click Next:
• Keep - keep existing queue managers and their objects.
• Remove - remove existing queue managers and their objects.
The Program Maintenance panel is displayed, with a summary of the installation to be removed.
7. Click Modify and click Next.
8. On the list of available IBM MQ features, click Advanced Message Security, select Do not install this
feature (remove if already intalled), and click Next.
The Ready to modify IBM MQ panel appears with the summary of your changes.
9. Click Modify and Next on the following panel to continue.

Results
Selected features of Advanced Message Security component have been removed.

Installing Managed File Transfer

Managed File Transfer is installed as a component of IBM MQ on AIX, Linux, and Windows, and on z/OS.
Managed File Transfer remains as a separate product on IBM i.

Before you begin

Before you install Managed File Transfer, check that your system meets both the hardware and software
requirements of the product. See System Requirements for IBM MQ.
For all platforms, you must have one IBM MQ queue manager available in your Managed File Transfer
network to use as the coordination queue manager.

Installing and migrating 243

 Note: If you are migrating or upgrading an existing IBM MQ installation, you must update database logger
instances before other parts of the Managed File Transfer network so that these instances can correctly
process the latest versions of the transfer log messages that they receive.
The following steps describe installing Managed File Transfer as a component of IBM MQ on AIX, Linux,
and Windows. For the other platforms, see and “Installing Managed File Transfer on IBM i” on page 72.

Procedure
1. Decide which Managed File Transfer components to install.
Managed File Transfer can be installed as four different options, depending on your operating system
and overall setup. These options are Managed File Transfer Agent, Managed File Transfer Service,
Managed File Transfer Logger, or Managed File Transfer Tools.
To decide which components to install, review the product options and topology information in the
following topics:
• Managed File Transfer product options
• Managed File Transfer topology overview
2. Install IBM MQ, including Managed File Transfer components.
For information about which specific components to install for your platform, including Managed File
Transfer, see “IBM MQ components and features” on page 6.
For more information about installing IBM MQ on AIX, Linux, and Windows, see the appropriate
information for your platform:

• “Installing and uninstalling IBM MQ on AIX” on page 32

• “Installing and uninstalling IBM MQ on Linux” on page 93

• “Installing and uninstalling IBM MQ on Windows” on page 158

Related concepts
Managed File Transfer
Managed File Transfer topology overview
Related reference
“Installed MFT command sets” on page 247
The following table shows which Managed File Transfer commands are installed with each component.

Managed File Transfer product options

Managed File Transfer can be installed as four different options, depending on your operating system and
overall setup. These options are Managed File Transfer Agent, Managed File Transfer Service, Managed
File Transfer Logger, or Managed File Transfer Tools.

Managed File Transfer Agent

A file transfer agent connects to an IBM MQ queue manager, and transfers file data, as messages, to other
file transfer agents.
You install an agent through either the Managed File Transfer Agent or Managed File Transfer Service
installation options.
The Managed File Transfer Agent option installs an agent that has the following capabilities:
• Make client or bindings mode connections to queue managers.
Note: When the file transfer agent and queue manager are on the same system, consider using the
bindings mode connections.
• Transfer files to and from other Managed File Transfer agents.
• Transfer files to and from Connect:Direct® nodes.

244 Installing and migrating IBM MQ

The Managed File Transfer Service option, described in the next section, installs a file transfer agent that
also has additional capability to transfer files to and from legacy FTP, FTPS, or SFTP protocol servers.

Managed File Transfer Service

The Managed File Transfer Service option installs an agent that has the following capabilities:
• Make client or bindings mode connections to queue managers.
Note: When the file transfer agent and queue manager are on the same system, consider using the
bindings mode connections.
• Transfer files to and from other Managed File Transfer agents.
• Transfer files to and from Connect:Direct nodes.
• Create protocol bridge agents that transfer files to and from legacy SFTP, FTP, or FTPS protocol servers.
Some capabilities are available on only a subset of supported platforms. For more information, see IBM
MQ System Requirements.
A Managed File Transfer Service can only be installed on systems where the IBM MQ Server option is
already installed.

Managed File Transfer Logger

A file transfer logger connects to an MQ queue manager, often the queue manager that is designated as
the coordination queue manager, and logs audit-related file transfer data to either a database or a file. A
logger can only be installed on systems where the IBM MQ Server installation option is already installed.

Managed File Transfer Tools

The Managed File Transfer Tools are command line tools that you use to interact with file transfer agents.
The tools allow you to start file transfers, schedule file transfers and create resource monitors from the
command line. The Managed File Transfer Tools need not be installed on the same system as the file
transfer agents that they interact with.

Managed File Transfer Base

On AIX and Linux platforms, there is an additional Managed File Transfer Base installation component.
This component contains files common to all of the installation options. You must install the Managed File
Transfer Base component before installing any of the Agent, Logger, Service, or Tools components.
For more information about the IBM MQ components that are required for each product option on AIX and
Linux platforms, see the following topics:

• “Required MFT components on AIX” on page 245

• “Required MFT components on Linux” on page 246

Related concepts
Managed File Transfer introduction
Managed File Transfer topology overview

Required MFT components on AIX

Managed File Transfer can be installed as four different options, depending on your operating system and
overall setup. On AIX systems, these options are Managed File Transfer Agent, Managed File Transfer

Installing and migrating 245

 Logger, Managed File Transfer Service, and Managed File Transfer Tools, and each option requires specific
components.

Managed File Transfer Agent

mqm.base.runtime
mqm.java.rte
mqm.jre.rte
mqm.ft.base
mqm.ft.agent

Managed File Transfer Logger

mqm.base.runtime
mqm.server.rte
mqm.java.rte
mqm.jre.rte
mqm.ft.base
mqm.ft.logger

Managed File Transfer Service

mqm.base.runtime
mqm.server.rte
mqm.java.rte
mqm.jre.rte
mqm.ft.base
mqm.ft.agent
mqm.ft.service

Managed File Transfer Tools

mqm.base.runtime
mqm.java.rte
mqm.jre.rte
mqm.ft.base
mqm.ft.tools

Required MFT components on Linux

Managed File Transfer can be installed as four different options, depending on your operating system and
overall setup. On Linux systems, these options are Managed File Transfer Agent, Managed File Transfer
Logger, Managed File Transfer Service, and Managed File Transfer Tools, and each option requires specific
components.

Managed File Transfer Agent

MQSeriesRuntime

246 Installing and migrating IBM MQ

 MQSeriesJava
MQSeriesJRE
MQSeriesFTBase
MQSeriesFTAgent

Managed File Transfer Logger

MQSeriesRuntime
MQSeriesServer
MQSeriesJava
MQSeriesJRE
MQSeriesFTBase
MQSeriesFTLogger

Managed File Transfer Service

MQSeriesRuntime
MQSeriesServer
MQSeriesJava
MQSeriesJRE
MQSeriesFTBase
MQSeriesFTAgent
MQSeriesFTService

Managed File Transfer Tools

MQSeriesRuntime
MQSeriesJava
MQSeriesJRE
MQSeriesFTBase
MQSeriesFTTools

Installed MFT command sets

The following table shows which Managed File Transfer commands are installed with each component.
Table 35. Managed File Transfer commands available in each command set

Redistributable
Managed File
Agent command Service Tools command Logger command Transfer package
Command set command set set set set

fteAnt

fteBundleConfiguration (AIX, Linux,

and Windows
only)

fteCancelTransfer

fteChangeDefaultConfigurationOptio
ns

Installing and migrating 247

Table 35. Managed File Transfer commands available in each command set (continued)

Redistributable
Managed File
Agent command Service Tools command Logger command Transfer package
Command set command set set set set

fteCleanAgent

fteCreateAgent

fteCreateBridgeAgent

fteCreateCDAgent (AIX, Linux, (AIX, Linux,

and Windows and Windows
only) only)

fteCreateEnvironment

fteCreateLogger “1” on page

249

fteCreateMonitor

fteCreateTemplate

fteCreateTransfer

fteDefine (AIX, Linux,

and Windows
only)

fteDelete (AIX, Linux,

and Windows
only)

fteDeleteAgent

fteDeleteLogger “1” on page

249

fteDeleteMonitor

fteDeleteScheduledTransfer

fteDeleteTemplates

fteDisplayVersion

fteListAgents

fteListMonitors

fteListScheduledTransfers

fteListTemplates

fteModifyAgent (Windows (Windows

only) only)

fteModifyLogger (Windows “1” on page

only) 249

fteObfuscate

ftePingAgent

fteRAS

248 Installing and migrating IBM MQ

Table 35. Managed File Transfer commands available in each command set (continued)

Redistributable
Managed File
Agent command Service Tools command Logger command Transfer package
Command set command set set set set

fteSetAgentLogLevel

fteSetAgentTraceLevel

fteSetLoggerTraceLevel “1” on page

249

fteSetupCommands

fteSetupCoordination

fteShowAgentDetails

fteShowLoggerDetails “1” on page

249

fteStartAgent

fteStartLogger “1” on page

249

fteStopAgent

fteStopLogger “1” on page

249

Notes:
1. From IBM MQ 9.3.0, the Redistributable Managed File Transfer package also includes the
Redistributable Managed File Transfer Logger. For more information, see Downloading and configuring
Redistributable Managed File Transfer components.

Installing MQ Telemetry
Installation tasks associated with MQ Telemetry are grouped in this section.

About this task

MQ Telemetry is installed as part of the IBM MQ server installation.
MQ Telemetry is a separately installed component of IBM MQ and is another option on the IBM MQ
installer. Make sure that you purchase a license for using IBM MQ Advanced before the installation (see
IBM MQ license information).

Procedure
• Install IBM MQ, including MQ Telemetry.
For information about which specific components to install for your platform, including MQ Telemetry,
see “IBM MQ components and features” on page 6.
For more information about installing IBM MQ on AIX, Linux, or Windows, see the appropriate
information for your platform:

– “Installing and uninstalling IBM MQ on AIX” on page 32

– “Installing and uninstalling IBM MQ on Linux” on page 93

– “Installing and uninstalling IBM MQ on Windows” on page 158

Installing and migrating 249

 Installation considerations for MQ Telemetry
MQ Telemetry is a component of the main IBM MQ product. You can choose to install MQ Telemetry when
you first install IBM MQ, or when you modify an existing IBM MQ installation.

MQ Telemetry overview
See Introduction to MQ Telemetry for general details about MQ Telemetry.

Support for IBM MQ Explorer

You can use IBM MQ Explorer to configure and manage the MQ Telemetry runtime component. For a
queue manager to accept connections from a telemetry device, one or more telemetry channels are
needed. To enable MQTT, there is a define sample configuration wizard that can be run from
IBM MQ Explorer. The wizard runs through a series of steps including defining and starting the telemetry
(MQXR) service, setting up the default transmission queue, and configuring a telemetry channel. For
more information about using the define sample configuration wizard, and any implications, see
“Verifying the installation of MQ Telemetry by using IBM MQ Explorer” on page 251.
The IBM MQ Explorer support provides the following capabilities:
• Telemetry node and content panel - providing welcome information, define sample configuration
wizard, run MQTT client utility, Help on MQ Telemetry, and status information about the MQ Telemetry
Service.
• Define sample configuration wizard - quickly configures a queue manager to support MQTT.
• New Telemetry Channel wizard - gathers information required to create a telemetry channel object.
• Telemetry Channels node and content panel - displays telemetry channels in the IBM MQ Explorer
Content view.
• Telemetry Channel Status node and content panel - displays telemetry channel status in the IBM MQ
Explorer Content view.
• MQTT Client Utility - provides a simple GUI for publishing and subscribing to topics.
• Help on MQ Telemetry.
You can install the MQ Telemetry runtime component on one system and configure and manage it
using the IBM MQ Explorer installed on another system. However, the components can be installed only
on systems with the appropriate prerequisites. For information about these prerequisites, see System
Requirements for IBM MQ.

MQ Telemetry client libraries and SDK

To help you write messaging applications for MQTT networks, you can install and use a set of free
example MQTT clients from the Eclipse Paho downloads page.
Related concepts
MQ Telemetry
Telemetry use cases
Related tasks
Administering MQ Telemetry
Developing applications for MQ Telemetry
Troubleshooting MQ Telemetry problems
Related reference
MQ Telemetry reference

250 Installing and migrating IBM MQ

Verifying the installation of MQ Telemetry
There are three ways to verify the installation of MQ Telemetry. Any can be used, regardless of whether
MQ Telemetry was installed as a custom installation of IBM MQ, or added to an existing installation of IBM
MQ.

About this task

Within IBM MQ you can verify the installation of MQ Telemetry either by using IBM MQ Explorer, or by
using the command line.
You can also verify the installation by using the MQTT messaging client for JavaScript in a browser that
supports the RFC 6455 (WebSocket) standard. A version of this client is installed with MQ Telemetry, and
the latest version is freely available from the Eclipse Paho downloads page. To verify the MQ Telemetry
installation you do not need the latest version of the client.

Procedure
• Verify your installation in one of the following ways:
• By using IBM MQ Explorer as described in “Verifying the installation of MQ Telemetry by using IBM
MQ Explorer” on page 251.
• By using the command line as described in “Verifying the installation of MQ Telemetry using the
command line” on page 253.

Verifying the installation of MQ Telemetry by using IBM MQ Explorer

Use the Define sample configuration wizard and the MQTT client utility in IBM MQ Explorer to verify that
the MQ Telemetry components have installed. Also check that publish/subscribe works correctly.

Before you begin

The MQ Telemetry runtime and support for IBM MQ Explorer must be installed. The telemetry folder is
part of a queue manager. To view the telemetry folder, you must start a queue manager.
Before running the define sample configuration wizard on an existing queue manager, review the
information provided by the wizard about the configuration changes that are made. The changes might
have implications for the configuration of the existing queue manager. Alternatively, run the sample
configuration wizard on a newly created queue manager to avoid changing any security settings.

About this task

To configure MQ Telemetry there is a define sample configuration wizard that can be run from IBM MQ
Explorer. The wizard runs through a series of steps, including defining and starting the telemetry (MQXR)
service, setting up the default transmission queue, and configuring a telemetry channel.
If you would prefer to do this manually, see Configuring a queue manager for telemetry on Linux and AIX .
For Windows, see Configuring a queue manager for telemetry on Windows .
You can open the define sample configuration wizard from the MQ Telemetry Welcome page in IBM MQ
Explorer. The wizard determines which steps are required based on the current configuration.
For example, the following actions might be specified by the wizard:
• Define the telemetry (MQXR) service.
• Start the telemetry (MQXR) service.
• Define the telemetry transmit queue.
• Set the default transmit queue of the queue manager to SYSTEM.MQTT.TRANSMIT.QUEUE.
If telemetry is already configured for this queue manager, the link to open the wizard is replaced with
static text. The text confirms that the sample configuration has been set up.

Installing and migrating 251

 After the configuration has finished, you can use IBM MQ Explorer to open the MQTT client utility. Use the
MQTT client utility to verify that MQ Telemetry is set up correctly.
The following items summarize the main goals that can be achieved using the MQTT client utility:
• Validation of a basic or custom MQ Telemetry configuration by connecting, subscribing to topics and
publishing messages.
• Showcases the main features of MQTT protocol.
• Provides a simple tool to aid in debugging MQ Telemetry applications.
You can find additional information within the IBM MQ Explorer by using the Help menu or pressing the F1
key.

Procedure
1. Start IBM MQ Explorer.
On Windows and Linux systems, you can start IBM MQ Explorer by using the system menu, the
MQExplorer executable file, the mqexplorer command, or the strmqcfg command.
2. Open the Welcome to MQ Telemetry page.
• To use an existing queue manager, click on IBM MQ\Queue Managers\qMgrName\Telemetry
folder to open the Welcome to MQ Telemetry page.
• If, for the reasons mentioned, you decide to use a new queue manager,
a. Click Queue Managers > New > Queue Manager.
b. Type MQTTVerification as the Queue manager name > Next > Next > Next.
c. Change the default port in Listen on port number, if the port is in use > Finish.
d. When the queue manager starts, click on IBM MQ\Queue
Managers\MQTTVerification\Telemetry folder to open the Welcome to MQ Telemetry
page.
3. From the Welcome to MQ Telemetry page in IBM MQ Explorer, click Define sample configuration.
If this link is not present, and instead you see the text, "The sample configuration has been set up for
this queue manager", then telemetry has already been configured. Proceed to step “6” on page 252.
If you clicked Define sample configuration, the page opens, and lists actions that are to be performed
as part of the sample configuration.
4. Leave Launch MQTT client utility checked, if you want to automatically start the MQTT client utility.
The check box is selected by default.
5. Click Finish.
6. Click Connect.
In the MQTT client utility panel, ensure that the host and port names are correct.
If you did not automatically start the MQTT client utility panel in step 4, you can start it either by using
a direct link from the Welcome to MQ Telemetry panel, or by right-clicking a NON-TLS channel, which
allows you to control the channel it runs on.
The client history records a Connected event.
7. Click Subscribe.
The client history records a Subscribed event.
8. Click Publish.
The client history records a Published and Received event.

Results
If the publish/subscribe finishes successfully, the MQ Telemetry installation is verified.

252 Installing and migrating IBM MQ

If you encounter problems during the installation process, view the error log:
• On Windows, the default location for this log is, IBM MQ data directory\qmgrs\qMgrName\mqxr
• On AIX and Linux, the default location for this log is, /var/mqm/qmgrs/qMgrName/mqxr/

Verifying the installation of MQ Telemetry using the command line

Follow these instructions to run scripts and a sample application to verify that the MQ Telemetry
components have installed, and are able to publish and subscribe.

Before you begin

Note:
This task uses the mqttv3app sample Java application, and the associated Java client library. These
resources were previously available in the IBM Messaging Telemetry Clients SupportPac, and the detailed
instructions in this task assume that you have a copy of this SupportPac.
The IBM Messaging Telemetry Clients SupportPac is no longer available. Free downloads of the latest
telemetry clients and samples, for a range of programming languages, continue to be available from the
Eclipse Paho project, and from MQTT.org.
The telemetry (MQXR) service must be started to run the sample programs. The user ID must be a
member of the mqm group.
The SampleMQM script creates and uses a queue manager called MQXR_SAMPLE_QM. Therefore, do not
run unaltered on a system that already has a MQXR_SAMPLE_QM queue manager. Any changes made might
have implications for the configuration of the existing queue manager.
There are two commands to run the mqttv3app sample Java application. The first command creates a
subscription, then waits for a message. The second command publishes to that subscription. Therefore
the commands must be entered into different command lines or shell windows.

About this task

To perform verification on a server or device without a GUI, scripts are provided in the samples
directory. The SampleMQM script performs the required steps to configure MQ Telemetry. The mqttv3app
sample Java application can then be run to validate the basic or custom MQ Telemetry configuration by
connecting, subscribing to topics, and publishing messages. The CleanupMQM sample script can be run to
delete the queue manager created by the SampleMQM script.
The following items summarize the main goals that can be achieved using this verification procedure:
• Validate a basic or custom MQ Telemetry configuration by connecting, subscribing to topics and
publishing messages.
• Showcase the main features of the MQTT protocol.
• Provide a simple tool to aid in debugging MQ Telemetry applications.

Procedure
1. Decompress the IBM Messaging Telemetry Clients SupportPac into a directory of your own choosing.
This task uses the mqttv3app sample Java application, and the associated mqttv3 Java client library.
If you have the earlier (MA9B) version of the SupportPac, the sample applications and client libraries
are in the CLIENTPACKDIR/SDK/clients/java directory, where CLIENTPACKDIR is the directory in
which you decompressed the client pack.
Note: The later (MA9C) version of the IBM Messaging Telemetry Clients SupportPac does not have
the /SDK/ directory, and does not include a compiled copy of the mqttv3app sample application. If
you have this version of the SupportPac, you need to compile the application manually, then create
the /SDK/ directory and contents. For the latest information about available clients and samples, see
IBM MQ Telemetry Transport sample programs.
2. Configure MQ Telemetry.

Installing and migrating 253

 The SampleMQM script runs through a series of steps, including creating the MQXR_SAMPLE_QM queue
manager, defining and starting the telemetry (MQXR) service, setting up the default transmission
queue, and configuring a telemetry channel.
For information about performing this manually, see Configuring a queue manager for telemetry on
Linux and AIX , or Configuring a queue manager for telemetry on Windows .
• On Windows systems, enter the following command in a command line:

MQINSTDIR\mqxr\samples\SampleMQM.bat

• On AIX or Linux systems, enter the following command in a shell window:

MQINSTDIR/mqxr/samples/SampleMQM.sh

where MQINSTDIR is the installation directory for this installation of IBM MQ.
A queue manager called MQXR_SAMPLE_QM is created, and MQ Telemetry is configured.
3. Run the mqttv3app sample Java application to create a subscription.
• On Windows systems, enter the following commands in a command line:

java -cp
"CLIENTPACKDIR\SDK\clients\java\org.eclipse.paho.sample.mqttv3app.jar;
CLIENTPACKDIR\SDK\clients\java\org.eclipse.paho.client.mqttv3.jar"
org.eclipse.paho.sample.mqttv3app.Sample -a subscribe

• On AIX or Linux systems, enter the following commands in a shell window:

java -cp
CLIENTPACKDIR/SDK/clients/java/org.eclipse.paho.sample.mqttv3app.jar:
CLIENTPACKDIR/SDK/clients/java/org.eclipse.paho.client.mqttv3.jar
org.eclipse.paho.sample.mqttv3app.Sample -a subscribe

The subscription is created, and waits to receive a message.

4. Run the mqttv3app sample Java application to publish to the subscription.
• On Windows systems, enter the following command in a second command line:

java -cp
"CLIENTPACKDIR\SDK\clients\java\org.eclipse.paho.sample.mqttv3app.jar;
CLIENTPACKDIR\SDK\clients\java\org.eclipse.paho.client.mqttv3.jar"
org.eclipse.paho.sample.mqttv3app.Sample -m "Hello from an MQTT v3 application"

• On AIX or Linux systems, enter the following command in a second shell window:

java -cp
CLIENTPACKDIR/SDK/clients/java/org.eclipse.paho.sample.mqttv3app.jar:
CLIENTPACKDIR/SDK/clients/java/org.eclipse.paho.client.mqttv3.jar
org.eclipse.paho.sample.mqttv3app.Sample -m "Hello from an MQTT v3 application"

The message Hello from an MQTT v3 application, that you typed into the second command
line or shell window, is published by that application and received by the application in the first
window. The application in the first window shows it on the screen.
5. Press Enter in the first command line or shell window to end the subscribing application.
6. Remove the queue manager created by the SampleMQM script.
• On Windows systems, enter the following command in a command line:

MQINSTDIR\mqxr\samples\CleanupMQM.bat

• On AIX or Linux systems, enter the following command in a shell window:

MQINSTDIR/mqxr/samples/CleanupMQM.sh

254 Installing and migrating IBM MQ

Results
If the scripts finished, and messages can be sent and received, the MQ Telemetry installation is verified.

What to do next
If you encounter any problems during the verification process, see MQ Telemetry troubleshooting. You
can also view the error log:
• On Windows systems, the default location for the queue manager log is
MQINSTDIR\qmgrs\MQXR_SAMPLE_QM\mqxr
• On AIX and Linux systems, the default location for the queue manager log is /var/mqm/qmgrs/
MQXR_SAMPLE_QM/mqxr/

Installing RDQM (replicated data queue managers)

Installation tasks associated with RDQM are grouped in this section. RDQM is available on x86-64 for
RHEL 8 (8.8 or later) and RHEL 9 (9.2 or later).

Before you begin

RDQM requires that the mqm user has the same UID on each node and that the mqm group has the same
GID on each node. You should create the mqm IDs before running the installation procedure, using the
groupadd and useradd commands to set the UID and GID the same on each node. See “Setting up the
user and group on Linux” on page 98.
Pacemaker is one of the prerequisites for RDQM. Pacemaker requires that certain Linux packages are
installed on the system. The list for supported levels of RHEL 8 and RHEL 9 assumes that a minimal
set of system packages has been installed that includes the mandatory and default packages from the
mandatory groups of the Server environment group.
The prerequisites for supported levels of RHEL 8 (Pacemaker 2) are:
• cifs-utils
• libtool-ltdl
• libxslt
• net-snmp-libs
• nfs-utils
• perl-TimeDate
• psmisc
• python36
• python3-lxml

The prerequisites for supported levels of RHEL 9 (Pacemaker 2) are:

• libxslt
• net-snmp-libs
• nfs-utils
• nfs-utils-coreos
• perl-TimeDate
• python3-lxml
• python-unversioned-command
These packages in turn have their own requirements (which are not listed here). When Pacemaker is
installed, it reports any missing packages that also need to be installed before installation can complete
successfully.

Installing and migrating 255

 Note: The Pacemaker component of RDQM requires a user named hacluster and a group named
haclient. By default, these use a uid and gid of 189, although it is possible to specify a different uid and
gid if required. The installation of Pacemaker creates the user and group if they do not exist.

About this task

To install support for RDQM (replicated data queue managers), you complete the following tasks:
1. Install DRBD on each node.
2. Install Pacemaker on each node.
3. Install IBM MQ on each node.
4. Install RDQM on each node.
The DRBD and Pacemaker RPM packages are supplied on the IBM MQ media. You should install the
versions supplied with IBM MQ. Do not download your own versions. To ensure that the packages
supplied with RDQM are used, add the following line to the definition of any yum repository that could
supply alternatives, such as the AppStream repository in RHEL 8 or RHEL 9:

exclude=cluster* corosync* drbd kmod-drbd libqb* pacemaker* resource-agents*

For supported levels of RHEL 8, components are found under the Advanced/RDQM/PreReqs/el8/
directory. For supported levels of RHEL 9, components are found under the Advanced/RDQM/
PreReqs/el9/ directory.
Attention: If you are using UEFI secure boot, you might need to enroll the key for the DRBD
kernel module. See https://linbit.com/drbd-user-guide/drbd-guide-9_0-en/#s-linbit-packages. If
UEFI secure boot is in use and the key is not enrolled, you will see the following error message.

modprobe: ERROR: could not insert 'drbd': Required key not available

The DRBD and Pacemaker packages are signed with the LINBIT GPG key. Use the following command to
import the public LINBIT GPG key:

rpm --import https://packages.linbit.com/package-signing-pubkey.asc

Without this step, an RPM install of these packages issues the following warnings:

warning: rpm-name: Header V4 DSA/SHA1 Signature, key ID 282b6e23: NOKEY"

You can have multiple IBM MQ installations on each server, but only one of these installations should be
an RDQM installation.
Attention: You should retain the installation media, in case there is a need to revert to this level,
after upgrading to a later level.

Procedure
Complete the following steps on each node:
1. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
2. Change into the directory containing the installation image.
3. Determine which DRBD kernel module is needed for the system on which RDQM is being installed.
See https://ibm.biz/mqrdqmkernelmods for up-to-date kernel module information. Helper scripts are
provided in the kmod-drbd-9 directories. For example, on a RHEL 8.10 system, running the helper
script Advanced/RDQM/PreReqs/el8/kmod-drbd-9/modver returns the following information,
identifying the kernel module that you need to install:

256 Installing and migrating IBM MQ

 kmod-drbd-9.0.23_4.18.0-553-1.x86_64.rpm

4. Install the appropriate DRBD kernel module that you identified in step 1. For example, for RHEL 8.10
you run the following command:

yum install Advanced/RDQM/PreReqs/el8/kmod-drbd-9/kmod-drbd-9.0.23_4.18.0-553-1.x86_64.rpm

5. Install the required DRBD utilities. For example, for RHEL 8.10 you run the following command:

yum install Advanced/RDQM/PreReqs/el8/drbd-utils-9/*

6. Install Pacemaker. For example, for RHEL 8.10 you run the following command:

yum install Advanced/RDQM/PreReqs/el8/pacemaker-2/*

The Pacemaker installer reports any missing packages that also need to be installed before the install
can complete successfully.
7. Accept the IBM MQ license:

./mqlicense.sh

8. Install IBM MQ. This is like a standard IBM MQ install. At the minimum, you must install the following:

yum install MQSeriesGSKit* MQSeriesServer* MQSeriesRuntime*

9. Install RDQM:

yum install Advanced/RDQM/MQSeriesRDQM*

What to do next
You can now configure the Pacemaker cluster and replicated data queue managers, or you can configure
disaster recovery replicated data queue managers. See RDQM high availability or RDQM disaster recovery.
Related concepts
“Migrating replicated data queue managers” on page 460
When you need to migrate replicated data queue managers (RDQMs), you must upgrade all nodes in a
sequence. Do not try to operate with the nodes at different levels.
Related tasks
“Applying maintenance level updates for RDQM” on page 301
There are different procedures for applying maintenance level updates to a high availability (HA)
configuration, a disaster recovery (DR) configuration, or a combined DR/HA configuration.
“Removing maintenance level updates for RDQM” on page 305
There are different procedures for removing maintenance level updates to a high availability (HA)
configuration, a disaster recovery (DR) configuration, or a combined DR/HA configuration.

Uninstalling RDQM (replicated data queue managers) if no

longer required
How to uninstall RDQM if it is no longer required.

Before you begin

Depending on which version of IBM MQis installed, you might need to remove maintenance
before you uninstall the base packages:
• If you are uninstalling a version of IBM MQ at IBM MQ 9.4.0 or later, you do not need to remove
maintenance before you uninstall IBM MQ.
• If you are uninstalling a version of IBM MQ before IBM MQ 9.4.0, you must remove any maintenance
that is applied to IBM MQ before you can uninstall. The procedure for removing maintenance changed at

Installing and migrating 257

 IBM MQ 9.4.0. Therefore, you must use the procedure that is detailed in earlier versions of the product
documentation to remove the maintenance.
Important: You must stop all IBM MQ queue managers, other objects, and applications, before you begin
the process to uninstall or modify IBM MQ.

About this task

There are different procedures for uninstalling a high availability (HA) configuration, a disaster recovery
(DR) configuration, or a combined DR/HA configuration.
Important: The following commands are intended as an example of those that would be issued on a
system with a single IBM MQ installation. On systems with multiple IBM MQ installations, or where
there are other packages installed whose name includes either "drbd" or "linbit", the commands must be
updated to ensure that only the packages associated with this IBM MQ installation are removed.
For details of how to uninstall IBM MQ on a system with multiple MQ installations please see “Uninstalling
or modifying IBM MQ on Linux using rpm” on page 150.

Procedure
• To uninstall HA RDQM support if it is no longer required:
a) Delete the RDQM HA queue managers in the HA group, see Deleting an HA RDQM.
b) Delete the RDQM HA group, see Deleting the Pacemaker cluster (HA group).
c) Log in as root or switch to superuser using the su command.
d) If you configured a firewall, run the script MQ_INSTALLATION_PATH/samp/rdqm/firewalld/
unconfigure.sh on each node to undo the firewall configuration. You must run this script as
root.
e) To uninstall IBM MQ and RDQM:

rpm -qa | grep MQSeries | xargs yum -y remove

Alternatively, to uninstall RDQM but leave the IBM MQ installation:

rpm -qa | grep MQSeriesRDQM | xargs yum -y remove

f) Uninstall Pacemaker:

rpm -qa | grep linbit | xargs yum -y remove

g) Uninstall DRBD:

rpm -qa | grep drbd | xargs yum -y remove

• To uninstall DR RDQM support if it is no longer required:

a) Delete all queue managers on all nodes, see Deleting a DR RDQM.
b) Log in as root or switch to superuser using the su command.
c) If you configured a firewall, run the script MQ_INSTALLATION_PATH/samp/rdqm/firewalld/
unconfigure.sh on each node to undo the firewall configuration. You must run this script as
root.
d) To uninstall IBM MQ and RDQM:

rpm -qa | grep MQSeries | xargs yum -y remove

Alternatively, to uninstall RDQM but leave the IBM MQ installation:

rpm -qa | grep MQSeriesRDQM | xargs yum -y remove

e) Uninstall Pacemaker:

258 Installing and migrating IBM MQ

 rpm -qa | grep linbit | xargs yum -y remove

f) Uninstall DRBD:

rpm -qa | grep drbd | xargs yum -y remove

• To uninstall DR/HA RDQM support if it is no longer required:

a) Delete the RDQM HA queue managers in both HA groups on main and recovery sites, see Deleting a
DR/HA RDQM.
b) Delete each RDQM HA group, see Deleting the Pacemaker cluster (HA group).
c) Log in as root or switch to superuser using the su command.
d) If you configured a firewall, run the script MQ_INSTALLATION_PATH/samp/rdqm/firewalld/
unconfigure.sh on each node to undo the firewall configuration. You must run this script as
root.
e) To uninstall IBM MQ and RDQM:

rpm -qa | grep MQSeries | xargs yum -y remove

Alternatively, to uninstall RDQM but leave the IBM MQ installation:

rpm -qa | grep MQSeriesRDQM | xargs yum -y remove

f) Uninstall Pacemaker:

rpm -qa | grep linbit | xargs yum -y remove

g) Uninstall DRBD:

rpm -qa | grep drbd | xargs yum -y remove

Related reference
rdqmadm (administer replicated data queue manager cluster)

Uninstalling RDQM (replicated data queue managers) and

upgrading
How to uninstall RDQM in preparation for upgrading IBM MQ and RDQM.

Before you begin

Depending on which version of IBM MQis installed, you might need to remove maintenance
before you uninstall the base packages:
• If you are uninstalling a version of IBM MQ at IBM MQ 9.4.0 or later, you do not need to remove
maintenance before you uninstall IBM MQ.
• If you are uninstalling a version of IBM MQ before IBM MQ 9.4.0, you must remove any maintenance
that is applied to IBM MQ before you can uninstall. The procedure for removing maintenance changed at
IBM MQ 9.4.0. Therefore, you must use the procedure that is detailed in earlier versions of the product
documentation to remove the maintenance.
Important: You must stop all IBM MQ queue managers, other objects, and applications, before you begin
the process to uninstall or modify IBM MQ.
Note: If you are upgrading the OS RHEL version, you need to follow a different upgrade procedure. See
“Applying OS updates with RDQM” on page 264 for upgrading RHEL within a version, or “Migrating an
RDQM configuration from RHEL 8 to RHEL 9” on page 460 for updating versions.

Installing and migrating 259

 About this task
This topic describes upgrading RDQM between versions. To apply maintenance level updates to RDQM,
see “Applying maintenance level updates for RDQM” on page 301. There are different procedures
for uninstalling and then upgrading a high availability (HA) configuration, a disaster recovery (DR)
configuration, or a combined DR/HA configuration.
For HA configurations, complete steps on each node in the HA group in turn. Processing can continue on
other nodes while this is in progress.
For all configurations, if the upgrade is to a level of IBM MQ that is at a higher command level then, after
a queue manager has been started at the higher level, it cannot run on a node that has not yet been
upgraded. You should plan the sequence of upgrades accordingly.
Important: The following commands are intended as an example of those that would be issued on a
system with a single IBM MQ installation. On systems with multiple IBM MQ installations, or where
there are other packages installed whose name includes either "drbd" or "linbit", the commands must be
updated to ensure that only the packages associated with this IBM MQ installation are removed.
For details of how to uninstall IBM MQ on a system with multiple MQ installations please see “Uninstalling
or modifying IBM MQ on Linux using rpm” on page 150.

Procedure
• Uninstall HA RDQM support and upgrade RDQM and IBM MQ.
a) Suspend the HA group on the node, by entering the following command:

rdqmadm -s

b) Log in as root or switch to superuser using the su command.

c) Uninstall IBM MQ (this step also uninstalls RDQM):

rpm -qa | grep MQSeries | xargs yum -y remove

d) Uninstall Pacemaker:

rpm -qa | grep linbit | xargs yum -y remove

e) Uninstall DRBD:

rpm -qa | grep drbd | xargs yum -y remove

f) Verify that the DRBD kernel was successfully unloaded:

lsmod | grep drbd

If either the drbd or drbd_transport_tcp kernel modules are still loaded, they can be unloaded with
the following commands:

modprobe -r drbd_transport_tcp
modprobe -r drbd

If the unload fails for any reason, reboot the node.

g) Install the new level of IBM MQ and dependent software, see Installing RDQM (replicated data
queue managers).
h) Resume the HA group on the node by entering the following command:

rdqmadm -r

You can now proceed to the next node in the group.

• Uninstall DR RDQM and IBM MQ and upgrade RDQM and IBM MQ.
a) Upgrade the DR secondary node:

260 Installing and migrating IBM MQ

 a. Log in as root or switch to superuser using the su command.
b. Uninstall IBM MQ (this step also uninstalls RDQM):

rpm -qa | grep MQSeries | xargs yum -y remove

c. Uninstall Pacemaker:

rpm -qa | grep linbit | xargs yum -y remove

d. Uninstall DRBD:

rpm -qa | grep drbd | xargs yum -y remove

e. Verify that the DRBD kernel was successfully unloaded:

lsmod | grep drbd

If either the drbd or drbd_transport_tcp kernel modules are still loaded, they can be unloaded
with the following commands:

modprobe -r drbd_transport_tcp
modprobe -r drbd

If the unload fails for any reason, reboot the node.

f. Install the new levels of IBM MQ and RDQM, see Installing RDQM (replicated data queue
managers).
b) On the DR primary node, do one of the following steps:
– End the DR queue managers, or
– Perform a managed failover of the DR queue managers to the DR secondary node.
c) Upgrade the DR primary node:
a. Log in as root or switch to superuser using the su command.
b. Uninstall IBM MQ (this step also uninstalls RDQM):

rpm -qa | grep MQSeries | xargs yum -y remove

c. Uninstall Pacemaker:

rpm -qa | grep linbit | xargs yum -y remove

d. Uninstall DRBD:

rpm -qa | grep drbd | xargs yum -y remove

e. Verify that the DRBD kernel was successfully unloaded:

lsmod | grep drbd

If either the drbd or drbd_transport_tcp kernel modules are still loaded, they can be unloaded
with the following commands:

modprobe -r drbd_transport_tcp
modprobe -r drbd

If the unload fails for any reason, reboot the node.

f. Install the new levels of IBM MQ and RDQM, see Installing RDQM (replicated data queue
managers).
d) On the DR primary node, do one of the following steps:
– Start the DR queue managers (if you previously ended them), or

Installing and migrating 261

 – Perform a managed failover of the DR queue managers back to the DR primary node.
• Uninstall DR/HA RDQM and IBM MQ and upgrade RDQM and IBM MQ.
a) Upgrade the HA group on your recovery site (presuming that the DR/HA RDQMs are running on the
main site). Complete the following steps on each node in the group in turn.
a. Log in as root or switch to superuser using the su command.
b. Suspend the HA group on the node, by entering the following command:

rdqmadm -s

c. Uninstall IBM MQ (this step also uninstalls RDQM):

rpm -qa | grep MQSeries | xargs yum -y remove

d. Uninstall Pacemaker:

rpm -qa | grep linbit | xargs yum -y remove

e. Uninstall DRBD:

rpm -qa | grep drbd | xargs yum -y remove

f. Verify that the DRBD kernel was successfully unloaded:

lsmod | grep drbd

If either the drbd or drbd_transport_tcp kernel modules are still loaded, they can be unloaded
with the following commands:

modprobe -r drbd_transport_tcp
modprobe -r drbd

If the unload fails for any reason, reboot the node.

g. Install the new level of IBM MQ and dependent software, see Installing RDQM (replicated data
queue managers).
h. Resume the HA group on the node by entering the following command:

rdqmadm -r

You can now proceed to the next node in the group.

b) On the HA group at the main site, either stop your queue managers, or perform a managed failover
to the HA group that you have just upgraded on the recovery site.
c) Upgrade the HA group on your main site. Complete the following steps on each node in the group in
turn.
a. Log in as root or switch to superuser using the su command.
b. Suspend the HA group on the node, by entering the following command:

rdqmadm -s

c. Uninstall IBM MQ (this step also uninstalls RDQM):

rpm -qa | grep MQSeries | xargs yum -y remove

d. Uninstall Pacemaker:

rpm -qa | grep linbit | xargs yum -y remove

e. Uninstall DRBD:

rpm -qa | grep drbd | xargs yum -y remove

262 Installing and migrating IBM MQ

 f. Verify that the DRBD kernel was successfully unloaded:

lsmod | grep drbd

If either the drbd or drbd_transport_tcp kernel modules are still loaded, they can be unloaded
with the following commands:

modprobe -r drbd_transport_tcp
modprobe -r drbd

If the unload fails for any reason, reboot the node.

g. Install the new level of IBM MQ and dependent software, see Installing RDQM (replicated data
queue managers).
h. Resume the HA group on the node by entering the following command:

rdqmadm -r

You can now proceed to the next node in the group.

d) You can now either start your queue managers (if you previously stopped them) or fail them back
over to the main site from the recovery site.
Related reference
rdqmadm (administer replicated data queue manager cluster)

Installing RDQM alongside other IBM MQ installations

You can install RDQM alongside other installations of IBM MQ although there can only be one RDQM
installation.

About this task

When installing multiple instances of IBM MQ on Linux with RPM, you must ensure that each installation is
made from packages with unique names. To create unique packages, you run the crtmqpkg command:

crtmqpkg PACKAGE_SUFFIX

Where PACKAGE_SUFFIX is a string added to package files to make them unique.

To install RDQM alongside existing IBM MQ installations, you must run crtmqpkg twice, once for the main
IBM MQ package and once for the RDQM component that has a separate rpm file under the Advanced/
RDQM subdirectory. For both commands, you should specify the same PACKAGE_SUFFIX. When you run
crtmqpkg for the RDQM package, you supply RPMDIR and SPECDIR arguments to specify where the
RDQM package files reside.
Note:
• By default, the crtmqpkg command writes to the /var/tmp directory. To use a different location, you
can set the TMPDIR environment variable before you run the crtmqpkg command.
• Before you can run the crtmqpkg command on Linux, you must have the pax and rpmbuild
commands installed. These commands are not supplied as part of the product. You must get them
from your Linux distribution supplier. The rpmbuild command is located in the rpm-build package.

Procedure
To create unique installation packages for RDQM:
1. Decompress the downloaded software to your installation directory, see “Installing the first IBM MQ
installation on Linux using the rpm command” on page 111.
2. From your installation directory, create unique packages for the IBM MQ components:

./crtmqpkg RDQM

Installing and migrating 263

 3. From your installation directory, create unique packages for the RDQM components:

RPMDIR=install_directory_path/MQServer/Advanced/RDQM SPECDIR=install_directory_path/MQServer/
Advanced/RDQM/repackage ./crtmqpkg RDQM

Where install_directory_path is the full path to your installation directory.

4. Install IBM MQ with RDQM using the packages you created in this task. Note that, as you are installing
an additional instance of IBM MQ, you will need to use the --prefix option with rpm to specify a
non-default installation location.
a) Change to the directory containing the unique packages that were created, for example:

cd /var/tmp/mq_rpms/RDQM/x86_64

b) Install IBM MQ and RDQM:

rpm -ivh --prefix /opt/customLocation MQSeriesGSKit* MQSeriesServer* MQSeriesRuntime*

MQSeriesRDQM*

Applying OS updates with RDQM

RDQM uses a DRBD kernel module which must be compatible with the current OS kernel level.
Note: You should only apply RHEL updates within a version, for example from 9.2 to 9.3. You should not
update versions, for example, from RHEL 8 to RHEL 9. For updating a version, see “Migrating an RDQM
configuration from RHEL 8 to RHEL 9” on page 460.
If OS updates are made which update the OS kernel level then a new DRBD kernel module might be
required. See https://ibm.biz/mqrdqmkernelmods for guidance on compatibility between DRBD kernels
and OS kernels.
Typically, a DRBD kernel update is required when the OS kernel branch is updated. For example, from
RHEL 9.2 (5.14.0-284.11.1) to RHEL 9.3 (5.14.0-362.18.1).
In this case, follow the procedure “Update DRBD kernel module before nodes are rebooted into a new
kernel” on page 264.
If you have already rebooted nodes into a new kernel, and find that RDQM does not run, follow the
procedure “Update DRBD kernel module after a node has rebooted into a new kernel” on page 267.
The rdqmstatus command gives information about the OS kernel level and DRBD kernel module level,
see Viewing RDQM and HA group status, Viewing DR RDQM status, and Viewing DR/HA RDQM and HA
group status.
Related tasks
“Applying maintenance level updates for RDQM” on page 301
There are different procedures for applying maintenance level updates to a high availability (HA)
configuration, a disaster recovery (DR) configuration, or a combined DR/HA configuration.

Update DRBD kernel module before nodes are rebooted into a new kernel
If an OS update requires a DRBD kernel update, you should follow this procedure before you reboot the
nodes into the new OS kernel.

About this task

Note: You should only apply RHEL updates within a version, for example from 9.2 to 9.3. You should not
update versions, for example, from RHEL 8 to RHEL 9.
There are different procedures for updating the DRBD kernel module for a high availability (HA)
configuration, a disaster recovery (DR) configuration, or a combined DR/HA configuration.
For HA configurations, complete the steps on each node in the HA group in turn. Processing can continue
on other nodes while the update is in progress.

264 Installing and migrating IBM MQ

Procedure
• To update the DRBD kernel module before a node is rebooted into a new kernel for RDQM HA:
a) Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux. This information also applies to UNIX systems in general.
b) Suspend the node from the HA group:

rdqmadm -s

c) Update the OS. For example:

yum update

d) Determine which DRBD kernel module is compatible with the new kernel level (see https://
ibm.biz/mqrdqmkernelmods for guidance on which kernel module is compatible). For example,
for moving to RHEL 9.2 (5.14.0-284.11.1) with IBM MQ 9.4, the required kernel module is kmod-
drbd-9.2.7+ptf.14.gdc5453714_5.14.0_284.11.1-1.x86_64.
e) Update the DRBD kernel module with the one you identified in step 4. For example:

yum install kmod-drbd-9.2.7+ptf.14.gdc5453714_5.14.0_284.11.1-1.x86_64.rpm

f) Reboot the node. This will reboot to the new kernel level:

sudo reboot

g) Resume the node in the HA group:

rdqmadm -r

You can now repeat this procedure for the next node in the HA group.
• To update the DRBD kernel module before nodes are rebooted into a new kernel for RDQM DR:
a) Update the OS and the DRBD kernel module on the DR secondary node:
a. Log in as root, or with sufficient authority to run the following commands.
b. Update the OS. For example:

yum update

c. Determine which DRBD kernel module is compatible with the new kernel level (see https://
ibm.biz/mqrdqmkernelmods for guidance on which kernel module is compatible). For example,
for moving to RHEL 9.2 (5.14.0-284.11.1) with IBM MQ 9.4, the required kernel module is
kmod-drbd-9.2.7+ptf.14.gdc5453714_5.14.0_284.11.1-1.x86_64.
d. Update the DRBD kernel module with the one you identified in step c. For example:

yum install kmod-drbd-9.2.7+ptf.14.gdc5453714_5.14.0_284.11.1-1.x86_64.rpm

e. Reboot the node. This will reboot to the new kernel level:

sudo reboot

b) On the DR primary node, complete one of the following steps:

– End the DR queue managers, or
– Perform a managed failover of the DR queue managers to the DR secondary node.
c) Update the OS and the DRBD kernel module on DR primary node:
a. Log in as root, or with sufficient authority to run the following commands.
b. Update the OS. For example:

Installing and migrating 265

 yum update

c. Determine which DRBD kernel module is compatible with the new kernel level (see https://
ibm.biz/mqrdqmkernelmods for guidance on which kernel module is compatible). For example,
for moving to RHEL 9.2 (5.14.0-284.11.1) with IBM MQ 9.4, the required kernel module is
kmod-drbd-9.2.7+ptf.14.gdc5453714_5.14.0_284.11.1-1.x86_64.
d. Update the DRBD kernel module with the one you identified in step c. For example:

yum install kmod-drbd-9.2.7+ptf.14.gdc5453714_5.14.0_284.11.1-1.x86_64.rpm

e. Reboot the node. This will reboot to the new kernel level:

sudo reboot

d) On the DR primary node, complete one of the following steps:

– Start the DR queue managers, or
– Perform a managed failover of the DR queue managers to the DR primary node.
• To update the DRBD kernel module before nodes are rebooted into a new kernel for RDQM DR/HA:
a) Update the OS and the DRBD kernel module on your recovery site. Complete the following steps on
each node in the group in turn.
a. Log in as root, or with sufficient authority to run the following commands.
b. Suspend the node from the HA group:

rdqmadm -s

c. Update the OS. For example:

yum update

d. Determine which DRBD kernel module is compatible with the new kernel level (see https://
ibm.biz/mqrdqmkernelmods for guidance on which kernel module is compatible). For example,
for moving to RHEL 9.2 (5.14.0-284.11.1) with IBM MQ 9.4, the required kernel module is
kmod-drbd-9.2.7+ptf.14.gdc5453714_5.14.0_284.11.1-1.x86_64.
e. Update the DRBD kernel module with the one you identified in step d. For example:

yum install kmod-drbd-9.2.7+ptf.14.gdc5453714_5.14.0_284.11.1-1.x86_64.rpm

f. Reboot the node. This will reboot to the new kernel level:

sudo reboot

g. Resume the node in the HA group:

rdqmadm -r

You can now repeat this procedure for the next node in the HA group.
b) Update the OS and the DRBD kernel module on your main site. Complete the following steps on
each node in the group in turn.
a. Log in as root, or with sufficient authority to run the following commands.
b. Suspend the node from the HA group:

rdqmadm -s

c. Update the OS. For example:

yum update

266 Installing and migrating IBM MQ

 d. Determine which DRBD kernel module is compatible with the new kernel level (see https://
ibm.biz/mqrdqmkernelmods for guidance on which kernel module is compatible). For example,
for moving to RHEL 9.2 (5.14.0-284.11.1) with IBM MQ 9.4, the required kernel module is
kmod-drbd-9.2.7+ptf.14.gdc5453714_5.14.0_284.11.1-1.x86_64.
e. Update the DRBD kernel module with the one you identified in step d. For example:

yum install kmod-drbd-9.2.7+ptf.14.gdc5453714_5.14.0_284.11.1-1.x86_64.rpm

f. Reboot the node. This will reboot to the new kernel level:

sudo reboot

g. Resume the node in the HA group:

rdqmadm -r

You can now repeat this procedure for the next node in the HA group.

Update DRBD kernel module after a node has rebooted into a new kernel
If a node was rebooted to a new OS kernel level and the DRBD kernel module is now incompatible with
the current OS kernel level then RDQM might fail to start correctly on the node.

About this task

Note: You should only apply RHEL updates within a version, for example from 9.2 to 9.3. You should not
update versions, for example, from RHEL 8 to RHEL 9.
For example, if a node was rebooted into a RHEL 9.3 (5.14.0-362.18.1) kernel with a RHEL 9.2
(5.14.0-284.11.1.) DRBD kernel module installed, RDQM does not start. The command rdqmstatus
-m qmname shows an HA status of Unknown for an HA or DR/HA queue manager, and a DR status of
Unknown for a DR queue manager.
The queue manager will not run on this node until the issue is resolved.
The kernel level of the OS and the installed DRBD kernel module level can be displayed by using the
following command:

$ rdqmstatus

The output includes kernel information as shown in the following example:

Node: mqhavm07.exampleco.com
OS kernel version: 5.14.0-362.18.1
DRBD OS kernel version: 5.14.0-362.18.1
DRBD version: 9.2.7
DRBD kernel module status: Loaded

To recover from this situation, complete the following procedure in turn on each node that has been
rebooted into a new kernel.

Procedure
1. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
2. Determine which DRBD kernel module is now needed for the system. See https://ibm.biz/
mqrdqmkernelmods for up-to-date kernel module information. Helper scripts are provided in the
kmod-drbd-9 directories.

Installing and migrating 267

 For example, on a RHEL 8.9 system, running the helper script Advanced/RDQM/PreReqs/el8/
kmod-drbd-9/modver returns the following information, identifying the kernel module that you need
to install:

kmod-drbd-9.2.7+ptf.14.gdc5453714_4.18.0_513.5.1-1.x86_64.rpm

3. Update the DRBD kernel module to the one that you identified in step 2. For example:

yum install kmod-drbd-9.2.7+ptf.14.gdc5453714_4.18.0_513.5.1-1.x86_64.rpm

4. Reboot the node:

sudo reboot

Installing and uninstalling IBM MQ Explorer as a stand-

alone application on Linux and Windows
You can install IBM MQ Explorer from a stand-alone download that is available from Fix Central.

About this task

You can download the stand-alone IBM MQ Explorer (formerly the MS0T SupportPac) from Fix Central
and install it as a stand-alone application, running on Linux x86_64 or Windows, on as many machines as
you require, either on its own or alongside an installation of IBM MQ of the same version. However, you
can only have a single installation of the stand-alone IBM MQ Explorer on a given machine, regardless of
version.
From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ installation package. It
remains available as a separate download, and can be installed from the stand-alone IBM MQ Explorer
download available from Fix Central.

Installing the stand-alone IBM MQ Explorer on Linux

On Linux, you can install the stand-alone IBM MQ Explorer by using the graphical user interface.
Alternatively, you can install with either a silent or a console installation.

Before you begin

Before you install the stand-alone IBM MQ Explorer, review the requirements information in IBM MQ
Explorer installation requirements.
If you already have a previous version of IBM MQ Explorer installed, uninstall that version with the
supplied uninstaller before installing the new version. For more information, see “Uninstalling the stand-
alone IBM MQ Explorer on Linux” on page 270.
If you try to reinstall IBM MQ Explorer and you previously uninstalled it by deleting the files rather than
by using the supplied uninstaller, the message IBM MQ Explorer is already installed appears.
If this situation occurs, you need to complete some additional steps to return to a clean system before
you can reinstall the stand-alone IBM MQ Explorer as described in “Uninstalling the stand-alone IBM MQ
Explorer on Linux” on page 270.
Note: In addition to the space used by the installed program, the installer uses space in the /tmp file
system. Allow at least 600 MB, which will be freed after the installation is complete.
To use somewhere other than /tmp, export the IATEMPDIR environment variable as shown in the
following example:

export IATEMPDIR=/var/tmp

You must export the environment variable before you run the ./Setup.bin command .

268 Installing and migrating IBM MQ

In addition, allow 400 MB on a file system of your choosing for the tar.gz installation image and the
contents of the image after the file is decompressed.

About this task

After you download the stand-alone IBM MQ Explorer from Fix Central and decompress the files, you can
install IBM MQ Explorer in any of the following ways:
• By using the installation wizard.
• By installing silently, with a response file.
• By installing with a console (text-based) installation.
If you require an accessible version of the installer, then use the silent installation mode to install
IBM MQ Explorer. A response file is used to configure a silent installation. An example response file,
silent_install.resp is provided in the same directory as the IBM MQ Explorer setup program. You
can modify this example file as required by using a text editor.

Procedure
1. Download the Linux version of stand-alone IBM MQ Explorer.
Follow this link to Fix Central, then select the Linux version of the download package.
2. Create an installation directory on the target system.
3. Decompress the tar.gz file that you downloaded, for example, 9.4.0.0-IBM-MQ-Explorer-
LinuxX64.tar.gz, to this directory.
4. Install IBM MQ Explorer in one of the following ways:
• To install by using the installation wizard:
a. Log in as root and navigate to the directory where you decompressed the files.
b. Run the command ./Setup.bin (as root) and follow the onscreen instructions.
c. Start IBM MQ Explorer either by using the system menu entry, or by using the MQExplorer
executable file in the installation directory.
• To install silently, by using a response file:
a. Use a text editor to modify the example response file, silent_install.resp, as required.
Make your changes in line with the comments in the file.
Note: Before running a silent install, the LICENSE_ACCEPTED property in the response file must
be set to TRUE to indicate that you agree to the terms of the product license. (The license can be
found in the license folder of the product .zip file).
b. Start the silent installation by using the following command:

./Setup.bin -f silent_install.resp

The installation then proceeds without any feedback.

• To install by using a console (text-based) installation, launch the installer by using the following
command:

./Setup.bin -i console

Note: If you see the following error message, this might be because you have the DISPLAY
environment variable set but do not have a valid X configuration:
Unable to load and to prepare the installer in console or silent mode.

If you do see this message, unset your DISPLAY environment variable and retry the operation in
console mode.

Installing and migrating 269

 What to do next
After IBM MQ Explorer has been installed, you can run it from the system menu or by using the
MQExplorer command. For more information, see Launching IBM MQ Explorer.
Related tasks
Launching IBM MQ Explorer

Uninstalling the stand-alone IBM MQ Explorer on Linux

On Linux, you uninstall the stand-alone IBM MQ Explorer by running the provided uninstaller.

About this task

On Linux, you uninstall the stand-alone IBM MQ Explorer by running the Change IBM MQ Explorer V9.4
Installation application.
If you remove the IBM MQ Explorer by deleting the files rather by than using the provided uninstaller, you
will be unable to reinstall the product at a later date unless you first carry out some additional steps to
return to a clean system. If you do try to reinstall IBM MQ Explorer after you previously uninstalled it by
deleting the files, the message IBM MQ Explorer is already installed appears.

Procedure
• To uninstall IBM MQ Explorer with the provided uninstaller, go to the installation directory and then
go in the directory named '_IBM MQ Explorer V9.4_installation', then run (as root) the
application named Change IBM MQ Explorer V9.4 Installation.
• If you need to get back to a clean system because you want to reinstall IBM MQ Explorer after
uninstalling it by deleting the files rather by than using the Change IBM MQ Explorer V9.4 Installation
application, complete the following steps:
a) Locate and edit the file .com.zerog.registry.xml.
The .com.zerog.registry.xml file is found either in the /var directory or alternatively in the
user's home directory. Make a backup of this file then edit it by deleting the section that begins with
the XML tag: '<product name="IBM MQ Explorer ' or '<product name="IBM WebSphere
MQ Explorer ' and ends with the next </product> tag. Save the file.
b) Delete the directory /etc/opt/ibm/MQ_Explorer and/or /etc/opt/ibm/
WebSphere_MQ_Explorer.
You should now be able to reinstall IBM MQ Explorer as described in “Installing the stand-alone IBM
MQ Explorer on Linux” on page 268.

Installing the stand-alone IBM MQ Explorer on Windows

On Windows, you can install the stand-alone IBM MQ Explorer by using the graphical user interface.
Alternatively, you can install IBM MQ Explorer with either a silent or a console installation.

Before you begin

Before you install the stand-alone IBM MQ Explorer, review the requirements information in IBM MQ
Explorer installation requirements.
If you already have a previous version of IBM MQ Explorer installed, uninstall that version before you
proceed with the installation of the new version.

About this task

After you download the stand-alone IBM MQ Explorer from Fix Central and decompress the files, you can
install IBM MQ Explorer in any of the following ways:
• By using the installation wizard.

270 Installing and migrating IBM MQ

• By installing silently, with a response file.
• By installing with a console (text-based) installation.
If you require an accessible version of the installer, then use the silent installation mode to install
IBM MQ Explorer. A response file is used to configure a silent installation. An example response file,
silent_install.resp is provided in the same directory as the IBM MQ Explorer setup program. You
can modify this example file as required by using a text editor.
Note: If you silently install the stand-alone IBM MQ Explorer on a Windows system with User Account
Control (UAC) enabled, you must also remove it silently and not by using Programs and Features in the
Control Panel.

Procedure
1. Download the Windows version of the stand-alone IBM MQ Explorer.
Follow this link to Fix Central and select the Windows version of the download package.
2. Create an installation directory on the target system.
3. Decompress the .zip file that you downloaded, for example, 9.4.0.0-IBM-MQ-Explorer-
Win64.zip, to this directory.
4. Install IBM MQ Explorer in one of the following ways:
• To install by using the installation wizard:
a. Double-click Setup.exe and follow the onscreen instructions.
b. Start the IBM MQ Explorer either by using the Start menu entry, or by using the MQExplorer
executable file in the installation directory.
• To install silently, by using a response file:
a. Use a text editor to modify the example response file, silent_install.resp, as required.
Make your changes in line with the comments in the file.
Note: Before installing silently, the LICENSE_ACCEPTED property in the response file must be
sent to TRUE to indicate that you agree to the terms of the product license. (The license can be
found in the license folder of the product .zip file).
b. Start the silent installation by using the following command:

Setup.exe -f silent_install.resp

The installation then proceeds without any feedback.

• To install by using a console (text-based) installation, start the installer by using the following
command:

Setup.exe -i console

What to do next
After IBM MQ Explorer has been installed, you can run it from the Windows start menu or by using the
MQExplorer command. For more information, see Launching IBM MQ Explorer.
Related tasks
Launching IBM MQ Explorer

Installing and migrating 271

 Uninstalling the stand-alone IBM MQ Explorer on Windows
On Windows, you can either uninstall the stand-alone IBM MQ Explorer by using the Control Panel or by
performing a silent uninstallation.

About this task

On Windows, you can uninstall the stand-alone IBM MQ Explorer by using either Add or Remove
Programs or Programs and Features, unless you installed IBM MQ Explorer silently on a Windows
system with User Account Control (UAC). On Windows UAC platforms, if you performed a silent
installation, you must also perform the uninstallation silently,
If you see the following error message it is most likely because you are trying to use Programs and
Features to uninstall an installation of the stand-alone IBM MQ Explorer that was installed silently
You do not have sufficient access to uninstall IBM MQ Explorer 9.4.
Please contact your system administrator.
.

Procedure
• To uninstall the stand-alone IBM MQ Explorer by using the Control Panel, use either Add or Remove
Programs or Programs and Features as appropriate.
• To perform a silent uninstallation, go to the directory named _IBM MQ Explorer
V9.4_installation in the installation directory and run the following command:

"Change IBM MQ Explorer V9.4 Installation.exe" -i silent

Installing and uninstalling IBM MQ Internet Pass-Thru

This section contains tasks to install any uninstall IBM MQ Internet Pass-Thru (MQIPT).

About this task

MQIPT is an optional component of IBM MQ that can be used to implement messaging solutions between
remote sites across the internet. For more information about MQIPT, see IBM MQ Internet Pass-Thru
If you are upgrading from a previous version of MQIPT, or applying maintenance to an MQIPT installation,
see “Migrating IBM MQ Internet Pass-Thru” on page 478.
Related tasks
Configuring IBM MQ Internet Pass-Thru

Installing MQIPT
IBM MQ Internet Pass-Thru (MQIPT) is available on AIX, Linux, and Windows. You can install MQIPT
wherever you want on your computer, and can have several installations on the same system.

About this task

Each installation can be used and maintained separately. For example, you can have different fix pack
levels of MQIPT installed in different locations if you choose.
The installation location is not fixed. MQIPT can be installed anywhere on the system. It is not necessary
to set the system PATH or CLASSPATH environment variables to refer to MQIPT.
You might choose to add the MQIPT bin directory to the PATH environment variable for convenience, but
it is not mandatory to do so.
You can also install MQIPT alongside previous versions of MQIPT.

272 Installing and migrating IBM MQ

Procedure
To install MQIPT, complete the following steps:
1. Download the MQIPT package for the platform that you require from IBM Fix Central for IBM MQ. The
MQIPT packages for IBM MQ 9.4.x are available under the following names:

Platform Archive file

AIX 9.4.x.0-IBM-MQIPT-AIXPPC64.tar.Z
Linux for x86-64 9.4.x.0-IBM-MQIPT-LinuxX64.tar.gz
Linux for IBM Z® 9.4.x.0-IBM-MQIPT-LinuxS390X.tar.gz
Linux on Power Systems - Little Endian 9.4.x.0-IBM-MQIPT-LinuxPPC64LE.tar.gz
Windows (64 bit) 9.4.x.0-IBM-MQIPT-Win64.zip
2. Choose the location where you want MQIPT to be installed.
Create a new directory where you want MQIPT to be installed.
For example, on AIX and Linux, you might use the following command:

mkdir /opt/mqipt/installation1

When you unpack the MQIPT installation archive file, a directory called mqipt is created, and the
installation files are placed in this directory. On Windows, the MQIPT installation archive file also
contains a directory called META-INF that contains files relating to code signature verification.
3. Unpack the installation archive file into the MQIPT directory by using an appropriate tool for your
platform.
Note: The tar command on AIX and Linux systems must be run as the root user when installing
MQIPT. Failure to run the tar command as root is likely to result in "permission denied" errors.
For example, on a Linux platform, you might use the following commands, if the archive file was
downloaded to the /tmp directory:

cd /opt/mqipt/installation1
su root
tar xzvf /tmp/9.4.0.0-IBM-MQIPT-LinuxX64.tar.gz

4. To increase security, set the file permissions for the installed files so that they are read-only:

• On AIX and Linux systems, you can use the chmod command. For
example:

chmod -R a-w /opt/mqipt/installation1/mqipt

• On Windows platforms, right-click the installation directory and select Properties.

You can change the file permissions on the Security tab.
5. If you subsequently receive error message MQCPE080 Unable to determine MQIPT
installation directory, set the MQIPT_PATH environment variable to the absolute path of the
MQIPT installation directory.
You do not normally have to set the PATH or CLASSPATH environment variables for MQIPT because
the installation includes a Java runtime environment (JRE). However, under some circumstances
(for example, if you use symbolic links), MQIPT commands are unable to determine the installation
directory. This can be corrected by setting the MQIPT_PATH environment variable.

Installing and migrating 273

 For example, if your installation directory is /opt/mqipt/installation1/mqipt, you might use
the following commands:

MQIPT_PATH=/opt/mqipt/installation1/mqipt
export MQIPT_PATH

6.
On Windows platforms, create MQIPT icons on the Start menu.
Run the following command from an administrator command prompt:

C:\mqipt_path\bin\mqiptIcons -install installation_name

where
• mqipt_path is the directory where MQIPT is installed.
• installation_name is a name that you choose to distinguish this installation from any other. The name
is appended to the name of the MQIPT icons.

What to do next
Follow the scenarios in Getting started with IBM MQ Internet Pass-Thru to verify that MQIPT is installed
correctly, and to configure MQIPT in simple scenarios.
For information on configuring and administering MQIPT, see Administering and configuring IBM MQ
Internet Pass-Thru.

Uninstalling MQIPT
Follow this procedure to uninstall MQIPT.

Procedure
1. Make appropriate backups in case you later have to restore any data. See Making backups for details.
2. Prevent the system from trying to start MQIPT automatically, if the MQIPT service has been installed.

• On AIX and Linux, remove the MQIPT service by changing to the bin
directory in the MQIPT installation path, and issuing the following command:

./mqiptService -remove

• On Windows, follow these steps to stop and remove the MQIPT service:
a. Stop MQIPT from the Windows services panel.
b. Open an administration command prompt, go to the bin directory in the MQIPT installation
path, and enter the command:

mqiptService -remove

Note: Only the installation of MQIPT that installed the service can be used to remove it. Attempting to
remove the service using a different installation causes error MQCPE083.

3. On Windows platforms, remove the MQIPT icons from the Start menu by clicking the
MQIPT icon, Remove these icons on the Start menu.
4. Delete the directory where MQIPT is currently installed.
You will need to have root access to the system in order to delete the MQIPT installation directory.

274 Installing and migrating IBM MQ

 Installing the stand-alone IBM MQ Web Server
From IBM MQ 9.4.0, you can install the stand-alone IBM MQ Web Server from a download that is available
from Fix Central.

About this task

The IBM MQ Web Server runs the IBM MQ Console and REST API. You can download the stand-alone IBM
MQ Web Server from Fix Central and install it as a stand-alone application on as many systems as you
require.
The stand-alone IBM MQ Web Server is available only on the following platforms:
• Linux for x86-64
• Linux on Power Systems - Little Endian
• Linux for IBM Z
Note: You can also install the IBM MQ Console and REST API as an optional component of an IBM MQ
installation. For more information about the installation options for the IBM MQ component that runs the
IBM MQ Console and REST API, see The IBM MQ Console and REST API.

Procedure
1. Download the stand-alone IBM MQ Web Server installation file.
Follow this link to Fix Central. Select the correct version of the download package for your
system. The download package is a tar.gz file, for example 9.4.0.0-IBM-MQ-Web-Server-
LinuxX64.tar.gz.
2. Create an installation directory on the target system.
3. Decompress the tar.gz file that you downloaded to the installation directory.

What to do next
Configure the mqweb server to run the IBM MQ Console and REST API. For more information, see
Configuring the stand-alone IBM MQ Web Server.

Maintaining and migrating IBM MQ

Maintenance, upgrade, and migration have three distinct meanings for IBM MQ. The definitions are
described here. The following sections describe the various concepts associated with migration, followed
by the various tasks needed; these tasks are platform-specific where needed.

About this task

Attention: The information in this section applies to both Continuous Delivery (CD) and Long Term
Support (LTS) releases.
Any information that applies specifically to an LTS or CD release is marked with the appropriate
icon.
IBM MQ uses the terms maintenance, upgrade and migration as follows:
Maintenance is the application of a fix pack, cumulative security update (CSU), interim fix or Program
Temporary Fix (PTF).
Maintenance has one main characteristic. Those fixes, whether they are applied by using a
maintenance installation tool, or installed by using a manufacturing refresh on top of an installation,
are at the same command level as the existing code. No migration is required after applying
maintenance. The installation can be restored to its previous level and any changed queue managers
or applications will continue to work at the restored code level. However, you should test applications
with the new level of IBM MQ code.

Installing and migrating 275

 For more information, see “Applying maintenance to IBM MQ” on page 278.
Upgrading is the process of taking an existing IBM MQ installation and upgrading to a new level of
code.
Unless you are upgrading the fix level of IBM MQ, but not its command level, an upgrade must be
followed by migration. Upgrades can be backed out, as long as no migration has taken place. The
process of removing an upgrade varies by platform and how the upgrade was applied. Upgrades
that change the command level of IBM MQ require queue manager migration before applications can
reconnect.
For more information, see “Upgrading IBM MQ” on page 320.
Migration is the process of updating queue manager data to match a newer level of code.
Migration occurs the first time a queue manager is started with the newer level of code, and always
follows an upgrade that changes the queue manager command level, both automatic and manual
changes. Migration is the transformation of queue manager data, applications, and the environment
that the queue manager runs in. Once migration has occurred, the queue manager can no longer be
started by an earlier code level. On most platforms, queue manager migration is not reversible:

• Migration cannot be reversed on IBM MQ for Multiplatforms. This restriction applies

whether your enterprise uses the Long Term Support (LTS) release or Continuous Delivery (CD)
release model.
For more information, see “Migrating IBM MQ” on page 336.
Related concepts
“Characteristics of upgrades and fixes” on page 277
For IBM MQ, the term upgrade applies to upgrading an existing installation of the product to a new level of
code. The term fix applies to a change the maintenance level of an existing installation.

Where to find more information about maintaining and migrating

Where to look for more information, for example if you are getting started with migrating and maintaining
IBM MQ.

Getting started with maintaining and migrating IBM MQ

If you are not familiar with IBM MQ migration, start by reading the “Migration concepts and methods” on
page 340 section. Use these topics to find out more about the concepts that you must understand before
planning migration tasks, including the difference between maintenance, migration, and upgrading and
which migration paths are supported.

For tutorials to help you with installing and upgrading, see A

collection of tutorials for installing and upgrading IBM MQ on AIX, Linux, and Windows. The tutorials
cover:
• Preparing a host for IBM MQ.
• Downloading the IBM MQ code.
• Installing and uninstalling the IBM MQ code, and applying fix packs.
• Upgrading from one version of IBM MQ to another, and moving a queue manager from one host to
another.

New features and changes in this release

For information about new features and changes in this release, see the following information:

• What's new and changed in IBM MQ 9.4.0

276 Installing and migrating IBM MQ

 New features and changes in earlier releases
Some new features and changes from earlier releases might have an impact on planning your migration
because they affect the behavior of existing applications or the automation of management tasks. For
information on where to find details of these changes in the product documentation for earlier releases,
see What was new and changed in earlier releases.

System requirements and prerequisites

You can use the Software Product Compatibility Reports (SPCR) tool to find information on supported
operating systems, system requirements, prerequisites, and optional supported software for IBM MQ. For
more information about the SPCR tool and links to reports for each supported platform, see the System
Requirements for IBM MQ web page.
For information about limitations and known problems for the current and earlier versions of IBM MQ, see
the appropriate product readme file, which is available from the IBM MQ, WebSphere MQ, and MQSeries
product readmes web page.
Related concepts
IBM MQ 9.4 in the IBM Documentation Offline app
IBM MQ 9.4 PDF files for product documentation and Program Directories

Characteristics of upgrades and fixes

For IBM MQ, the term upgrade applies to upgrading an existing installation of the product to a new level of
code. The term fix applies to a change the maintenance level of an existing installation.

Characteristics of fixes
The application of a fix pack, cumulative security update (CSU), or interim fix on Multiplatforms, or a
program temporary fix (PTF) on z/OS is called a fix. You apply fixes by using a maintenance installation
tool.
On the following platforms, fixes that are applied by using a maintenance installation tool can be rolled
back completely if no queue manager migration has taken place:

• AIX

• Windows
and IBM MQ is returned to its previous code level.
On all other platforms you must reinstall the product.

Characteristics of different types of upgrade

An upgrade can take one of three different forms:
1. Installation of new code on top of existing code. You might be able to roll back an upgrade applied
in this way; it depends on the platform. Generally speaking, you cannot roll back the installation of
new code. To restore the old code level, you must retain the old installation media, and any fixes you
applied.
2. Removal of the old level of code, followed by installation of the new level. The installers on very few
platforms require you to remove an old installation first. Needless to say, to restore the old code level,
you must reinstall it and any fixes.
3. Side by side installation.

• On AIX, Linux, and Windows, you associate a queue manager with an installation, and
start the queue manager. In IBM MQ, running multiple queue managers at different command levels
on the same server is termed queue manager coexistence.

Installing and migrating 277

 You must not infer from this, that you can select different installations to run a queue manager at
different times. Once a queue manager has been run, it is subject to the rules regarding reverting to
earlier or later command levels.
Note: The term upgrade does not imply that an IBM MQ installation can be directly upgraded from
one level to another. On some platforms, an upgrade requires that you remove the previous IBM MQ
installation. You can retain any queue managers that you have created.
The rules regarding the reversibility of an queue manager to run on a previous code level is dependent on
the platform.
On the following platforms, changes in version, release, or modification level are not fully reversible, but
changes in fix level are reversible under certain conditions.

• AIX

• Linux

• Windows

• IBM i
An irreversible upgrade implies that you must back up the queue managers, or your system, before
upgrading, to be able to restore your queue managers. Taking a backup of a queue manager requires you
to stop the queue manager. If you do not take a backup, you are not able to restore IBM MQ to its previous
level. Any changes you make on the new level cannot be restored onto the backup system. Changes
include the creation or deletion of persistent messages, and changes to queue managers, channels,
topics, and queues.
Related tasks
“Applying maintenance to IBM MQ” on page 278
Maintenance is the application of a reversible fix. Any changes to queue manager data are compatible
with the previous code level.
“Upgrading IBM MQ” on page 320
Upgrading is the process of taking an existing IBM MQ installation and upgrading to a new level of code.
“Migrating IBM MQ” on page 336
Migration is the conversion of programs and data to work with a new code level of IBM MQ. Some
types of migration are required, and some are optional. Queue manager migration is never required after
applying a maintenance level update, that does not change the command level. Some types of migration
are automatic, and some are manual. Queue manager migration is typically automatic and required after
releases and manual and optional after a maintenance level upgrade that introduces a new function.
Application migration is typically manual and optional.

Applying maintenance to IBM MQ

Maintenance is the application of a reversible fix. Any changes to queue manager data are compatible
with the previous code level.

Before you begin

This task assumes that you understand the difference between Long Term Support and Continuous
Delivery releases, and the maintenance delivery model that applies in each case. For more information,
see IBM MQ Release Types and versioning.

About this task

About applying maintenance
Maintenance deliveries for a particular version/release are cumulative, from the initial release. You can
apply any higher numbered fix pack or cumulative security update (CSU) of the same version/release to
upgrade directly to that version level. You do not have to apply the intervening fixes.

278 Installing and migrating IBM MQ

You can also refresh the full version of IBM MQ by installing a manufacturing refresh that is available
online or on physical media. The result of installing a manufacturing refresh is the same as applying a
maintenance delivery to an earlier fix level of IBM MQ. However, on platforms other than Windows and
Linux, there is one important difference: Fix packs and CSUs are applied using a maintenance procedure,
manufacturing refreshes are installed using an installation procedure. You can "unapply" a fix pack or CSU
to return to the previous fix level you had installed. You can only uninstall a manufacturing refresh, which
removes IBM MQ from your system.
In addition to manufacturing refreshes and maintenance deliveries, you might occasionally be directed by
the IBM Support team to apply an interim fix. Interim fixes are also known as emergency or test fixes,
and are used to apply urgent updates that cannot wait for the next maintenance delivery. Interim fixes
are known by a unique fix name, which will include the target version and platform, and other identifying
context, such as a support case reference or APAR number. When you apply a new CSU, fix pack, or
manufacturing refresh, all interim fixes are removed. The documentation with maintenance delivery or
manufacturing refresh includes a "fix list" page, stating which APAR fixes are included in the deliverable.
This list tells you if the APARs associated with the interim fixes that you have applied have been fixed
in the latest maintenance. If they have not, check to see if there are new interim fixes, at the new level,
for the APARs that concern you. If there are not, consult IBM Support. They might tell you to reapply the
interim fix, or they might supply a new interim fix.
You get manufacturing refreshes, maintenance deliveries and interim fixes through Passport Advantage
and Fix Central. See “Where to find downloadable installation images” on page 9.
• Manufacturing refreshes are available through Passport Advantage.
• Fix packs and CSUs are available through Fix Central.
• Interim fixes are typically provided directly by the IBM Support team through a support case, and
occasionally provided through Fix Central.
About removing maintenance
An important characteristic of applying maintenance is that it must be reversible. Reversibility implies two
things:
1. The previous level of code is fully restored.
2. Changes that are made to IBM MQ objects are compatible. Changes are things like the creation or
deletion of persistent messages, changes to queue managers, channels, topics, and queues. New and
modified objects continue to work correctly with the restored level of code.
The reversibility of a maintenance package limits the extent of functional changes that are included in a
maintenance package. No irreversible changes are included in a maintenance package. But, reversibility
has limits. A maintenance package might include new programming and administrative interfaces. If
you build new or modified applications to use the new interfaces, those applications do not work if the
maintenance package is removed.
On a smaller scale, a fix pack, CSU, or interim fix might introduce a new configuration parameter to solve
a problem. If you remove the fix pack, CSU, or interim fix, although the new interface introduced by
the change is not available any more, IBM MQ works with any objects that have been changed by the
configuration parameter. For example, a new Java system property might introduce a parameter to set
a code page for queue manager data conversion. The fix does not change any existing persistent queue
manager state information. It can be removed, and the queue manager continues to work as before, but
without the capability introduced in the fix.
On different platforms, you employ different mechanisms to install and maintain software releases.
Installing a release at a new maintenance level, and applying maintenance level updates to update an
earlier release to the same maintenance level, have different results.
When you update the maintenance or fix level of IBM MQ by applying a regular maintenance level update,
you can reverse the update by removing the fix. When you update the maintenance or fix level of IBM
MQ by applying a maintenance level update containing a new function, you can reverse that update and
all previously reversible updates until a queue manager associated with the installation enables the new
function.

Installing and migrating 279

 Maintenance levels and fix levels are both supplied from Fix Central. For information on where to
find direct links to specific fix packs, CSUs, and other IBM MQ resources on Fix Central, see IBM MQ
downloads.

Procedure
• To check the IBM MQ maintenance level:
– Type the command dspmqver, or DSPMQMVER on IBM i. The returned messages include the three-
digit VRM or, if maintenance has been applied, the four-digit VRMF.
– Use the REST API GET method.

– View the queue manager property panel in IBM MQ Explorer.

• To apply or remove maintenance level updates, follow the appropriate links for the platforms that your
enterprise uses.
Related concepts
“Multi-installation queue manager coexistence on AIX, Linux, and Windows” on page 357
You can install multiple copies of IBM MQ for AIX, Linux, and Windows on the same server. These IBM MQ
copies can be at the same or different version levels. This is called a multi-installation. Multi-installation is
particularly useful when you upgrade from one IBM MQ version to a later version, because it allows you to
run the earlier version alongside the later version.
“Queue manager coexistence” on page 355
Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations.
Related tasks
Backing up and restoring a queue manager

Applying and removing maintenance on AIX

Maintenance tasks associated with AIX are grouped in this section.
Related tasks
“Applying maintenance to IBM MQ” on page 278
Maintenance is the application of a reversible fix. Any changes to queue manager data are compatible
with the previous code level.

Applying maintenance level updates on AIX

You apply maintenance level updates to IBM MQ for AIX by using installp.

Before you begin

1. Ensure that you have enough disk space to apply maintenance level updates. A maintenance level
update requires hard disk space for installation. In addition, the installation process might require a
similar amount of disk space to save the previous level. For example, a 16 MB update might require 32
MB of space. The additional space allows a maintenance level update to be removed, and the previous
level to be restored automatically.
2. If you are running on a server with multiple IBM MQ installations, you must identify the installation.
Make sure that the commands you enter run against the correct installation; see setmqenv.

About this task

Stop applications using the installation and use the installp command, to install maintenance level
updates to clients and servers. Alternatively, if the installation is in the default installation location, you
can use the System Management Interface Tool, SMIT.

280 Installing and migrating IBM MQ

Important: You cannot go back from a later version of the product to a prior version of the product, for
example from IBM MQ 9.4 to IBM MQ 9.3.
You can apply and remove maintenance from an IBM MQ MQI client that is not installed on the same
server as a queue manager. You do not have to stop any queue managers or logon as administrator.
Because you do not have to stop any queue managers, do not do steps “1” on page 281 to “4” on page
281 in the following maintenance procedure.
Major full versions of the base product are COMMITTED by default. Fix packs on a full base version can be
in APPLIED state, and you can go back one release level.
If you need the ability to revert to an earlier version, you should perform a side-by-side migration,
and migrate your queue managers to the later version at any time. See “Migrating on AIX and Linux:
side-by-side” on page 411 for further information.
However, if you start a queue manager under IBM MQ 8.0 or later, that queue manager is automatically
migrated, and cannot be downgraded to the previous version.

Procedure
1. Log in as a user in group mqm.
2. Stop all applications using the IBM MQ installation.
If you use the Managed File Transfer (MFT) component, ensure that any MFT agents have finished all of
the file transfers that they were engaged in. There should be no incomplete transfers associated with
the agents, and their SYSTEM.FTE.STATE queues should contain no messages.
3. Stop the mqweb server that is associated with the IBM MQ installation:
a) Check whether the mqweb server is running by entering the following command:

dspmqweb status

b) Stop the mqweb server by entering the following command:

endmqweb

4. End all the activity of queue managers associated with the IBM MQ installation.
a) Run the dspmq command to list the state of all the queue managers on the system.
Run either of the following commands from the installation that you are updating:

dspmq -o installation -o status

dspmq -a

dspmq -o installation -o status displays the installation name and status of queue
managers associated with all installations of IBM MQ.
dspmq -a displays the status of active queue managers associated with the installation from
which the command is run.
b) Use the MQSC command DISPLAY LSSTATUS to list the status of listeners associated with a
queue manager, as shown in the following example:

echo "DISPLAY LSSTATUS(*) STATUS" | runmqsc QmgrName

c) Run the endmqm command to stop each running queue manager associated with this installation.
-c
endmqm -w QmgrName

-i
-p

Installing and migrating 281

 The endmqm command informs an application that the queue manager it is connected to is
stopping; see Stopping a queue manager.
For the maintenance to proceed, applications must respond to an endmqm command by
disconnecting from the queue manager and releasing any IBM MQ libraries they have loaded. If
they do not, you must find another way to force applications to release IBM MQ resources, such as
by stopping the applications.
You must also stop applications that are using the client libraries that are part of the installation.
Client applications might be connected to a different queue manager, running a different
installation of IBM MQ. The application is not informed about queue managers in the current
installation being shut down.
Any applications that continue to have IBM MQ shared libraries from the installation loaded prevent
you applying IBM MQ maintenance. An application might disconnect from a queue manager, or be
forcibly disconnected, but keep an IBM MQ shared library loaded.
Note: “Applying maintenance level updates to multi-instance queue managers on Linux” on page
299 describes how to apply maintenance to a multi-instance queue manager. A multi-instance
queue manager can continue to run on one server, while maintenance is applied to another server.
d) Stop any listeners associated with the queue managers, using the command:

endmqlsr -m QMgrName

5. Log in as root, or with sufficient authority to run the following commands.

You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux. This information also applies to UNIX systems in general.
6. Install the update in one of the following ways:
• Update the whole installation in the default location:

installp -agXYd . all

• Update selected filesets in the default location:

installp -agXYd . list of file sets

• Update the whole product in a non-default location using the -R flag:

installp -R USIL_Directory -agXYd . all

• Update selected filesets in a non-default location using the -R flag:

installp -R USIL_Directory -agXYd . list of file sets

USIL_Directory is the installation parent directory. IBM MQ is installed underneath the directory.
For example, if /USIL1 is specified, the IBM MQ product files are located in /USIL1/usr/mqm. /
USIL1/usr/mqm is known as the MQ_INSTALLATION_PATH.
Related tasks
Stopping a queue manager
Related reference
dspmq

282 Installing and migrating IBM MQ

 Reverting to the previous maintenance level on AIX
You can revert to a previous maintenance level by using the System Management Interface Tool (SMIT).

Before you begin

If you are running on a server with multiple IBM MQ installations, you must identify the installation. Make
sure that the commands you enter run against the correct installation; see setmqenv.

About this task

You can back out maintenance level updates and restore your system to the previous maintenance or
installation level, for any component of IBM MQ for AIX that is in the APPLIED state.
IBM MQ for AIX uses the following directory trees that are mutually exclusive, which are, for the :
• Executable libraries and shared libraries, is /usr/mqm
• Data for the queue managers and other configuration files, is var/mqm.
Because the directory trees are mutually exclusive, when you apply or remove maintenance only the files
in usr/mqm are affected.
The procedure detailed within this topic removes all the maintenance level updates installed. See
“Uninstalling a single maintenance level update on AIX” on page 285 for details on removing a single
maintenance level update from your system.
You can apply and remove maintenance from an IBM MQ MQI client that is not installed on the same
server as a queue manager. You do not have to stop any queue managers or logon as administrator.
Because you do not have to stop any queue managers, do not do steps “1” on page 283 to “3” on page
283 in the following maintenance procedure.
Use the following command to display the current state of the IBM MQ for AIX filesets:

lslpp [ -R usil ] -l "mqm*"

To back out a maintenance update, as the user root, issue the command:

installp [ -R usil ] -r "mqm*"

Otherwise:

Procedure
1. Log in as a user in group mqm.
2. Stop all applications using the IBM MQ installation.
If you use the Managed File Transfer (MFT) component, ensure that any MFT agents have finished all of
the file transfers that they were engaged in. There should be no incomplete transfers associated with
the agents, and their SYSTEM.FTE.STATE queues should contain no messages.
3. End all the activity of queue managers associated with the IBM MQ installation.
a) Run the dspmq command to list the state of all the queue managers on the system.
Run either of the following commands from the installation that you are updating:

dspmq -o installation -o status

dspmq -a

dspmq -o installation -o status displays the installation name and status of queue
managers associated with all installations of IBM MQ.
dspmq -a displays the status of active queue managers associated with the installation from
which the command is run.

Installing and migrating 283

 b) Use the MQSC command DISPLAY LSSTATUS to list the status of listeners associated with a
queue manager, as shown in the following example:

echo "DISPLAY LSSTATUS(*) STATUS" | runmqsc QmgrName

c) Run the endmqm command to stop each running queue manager associated with this installation.
-c
endmqm -w QmgrName

-i
-p

The endmqm command informs an application that the queue manager it is connected to is
stopping; see Stopping a queue manager.
For the maintenance to proceed, applications must respond to an endmqm command by
disconnecting from the queue manager and releasing any IBM MQ libraries they have loaded. If
they do not, you must find another way to force applications to release IBM MQ resources, such as
by stopping the applications.
You must also stop applications that are using the client libraries that are part of the installation.
Client applications might be connected to a different queue manager, running a different
installation of IBM MQ. The application is not informed about queue managers in the current
installation being shut down.
Any applications that continue to have IBM MQ shared libraries from the installation loaded prevent
you applying IBM MQ maintenance. An application might disconnect from a queue manager, or be
forcibly disconnected, but keep an IBM MQ shared library loaded.
Note: “Applying maintenance level updates to multi-instance queue managers on Linux” on page
299 describes how to apply maintenance to a multi-instance queue manager. A multi-instance
queue manager can continue to run on one server, while maintenance is applied to another server.
d) Stop any listeners associated with the queue managers, using the command:

endmqlsr -m QMgrName

4. Log in as root, or with sufficient authority to run the following commands.

You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux. This information also applies to UNIX systems in general.
5. Open the appropriate smit panel using this sequence:

Software Installation and Maintenance

Software Maintenance and Utilities
Reject Applied Software Updates (Use Previous Version)

Alternatively, use a fast path command, smit[ty] install_update.

6. Complete the SOFTWARE name field.
Enter mqm* to restore all applicable file set updates to your installation.
Note: If an option to restore only selected file set updates for IBM MQ for AIX appears, avoid it. The
option results in all applicable file set updates for the maintenance level update being restored.
7. Click Enter to reject the current maintenance level and reinstate the previous maintenance or
installation level.
a) Accept displayed default values for all other fields
b) Dismiss the confirmation message

284 Installing and migrating IBM MQ

 The reject process starts. While the command runs, it displays progress messages terminating with an
Install Summary table.
a) Check the table to see which components of IBM MQ for AIX have been rejected
Related tasks
Stopping a queue manager
“Applying maintenance level updates to multi-instance queue managers on AIX” on page 289
On AIX, you can use multi-instance queue managers to reduce the outage caused by applying
maintenance updates.
Related reference
dspmq
DISPLAY LSSTATUS
endmqm (end queue manager)
endmqlsr (end listener)

Uninstalling a single maintenance level update on AIX

You can remove a single maintenance level update by using the installp command.

About this task

For example, you have installed IBM MQ for AIX 9.1.0.0 base, the IBM MQ for AIX 9.1.0.7 fix pack and the
IBM MQ for AIX 9.1.0.8 fix pack.
You want to remove the 9.1.0.8 fix pack and leave the 9.1.0.7 fix pack.
Look at the installp command in the AIX manual, and specifically the information on the -r (reject)
parameter.
The AIX manual lists a number of options for the installp -r parameter, and the one that is relevant is
the -f ListFile option.
The description of the -f ListFile option includes the following statement: Output from the installp -l
command is suitable for input to this flag.
You need to obtain a text file using the installp -l command. The AIX manual shows the following
invocation for installp -l parameter:

installp { -l | -L } [ -eLogFile ] [ -d Device ] [ -B ] [ -I ] [ -q ] [-E ]

[ -zBlockSize ] [ -O { [ s ] [ u ] } ]

Note: The principles apply to a User Specified Installation Location (USIL) by using the -R usil-directory
option, and to other IBM MQ fix packs.
See Life cycle for a USIL in AIX for non-default installations of MQ for more information on a USIL.
Carry out the following procedure to remove the latest 9.1.0.8 fix pack, and leave the base IBM MQ for
AIX 9.1.0.0 and 9.1.0.7 fix packs in place.

Procedure
1. Issue the following command, # lslpp -la "mqm*":
You see the following output:

+-----------------------------------------------------------------------------+
INSTALL ROOT PATH = /
+-----------------------------------------------------------------------------+
Fileset Level State Description
----------------------------------------------------------------------------
Path: /usr/lib/objrepos
mqm.amqp.rte 9.1.0.0 COMMITTED IBM MQ AMQP Service
9.1.0.7 APPLIED IBM MQ AMQP Service
9.1.0.8 APPLIED IBM MQ AMQP Service

Installing and migrating 285

mqm.ams.rte 9.1.0.0 COMMITTED IBM MQ Advanced - Advanced Message Security
9.1.0.7 APPLIED IBM MQ Advanced - Advanced Message Security
9.1.0.8 APPLIED IBM MQ Advanced - Advanced Message Security
mqm.base.runtime 9.1.0.0 COMMITTED IBM MQ Runtime for Client and Server
9.1.0.7 APPLIED IBM MQ Runtime for Client and Server
9.1.0.8 APPLIED IBM MQ Runtime for Client and Server

2. Go to the original directory where the IBM MQ for AIX tar.Z file with the fix pack code, that was
downloaded, was stored in the machine and unpacked; for example, cd /downloads/mq9108.
Expand 9.1.0-IBM-MQ-AixPPC64-FP0008.tar.Z and you see:

+++ROOT+++ aglet: /downloads/mq9108

# ls
.toc mqm.msg.Zh_CN.9.1.0.8.U202341
9.1.0-IBM-MQ-AixPPC64-FP0008.tar mqm.msg.Zh_TW.9.1.0.8.U202343
mq9108.installpl.txt mqm.msg.cs_CZ.9.1.0.8.U202327
mqm.amqp.rte.9.1.0.8.U202313 mqm.msg.de_DE.9.1.0.8.U202328
mqm.ams.rte.9.1.0.8.U202312 mqm.msg.en_US.9.1.0.8.U202329
mqm.base.runtime.9.1.0.8.U202314 mqm.msg.es_ES.9.1.0.8.U202330
mqm.base.samples.9.1.0.8.U202315 mqm.msg.fr_FR.9.1.0.8.U202331
mqm.base.sdk.9.1.0.8.U202316 mqm.msg.hu_HU.9.1.0.8.U202332
mqm.client.rte.9.1.0.8.U202317 mqm.msg.it_IT.9.1.0.8.U202333
mqm.ft.agent.9.1.0.8.U202318 mqm.msg.ja_JP.9.1.0.8.U202334
mqm.ft.base.9.1.0.8.U202319 mqm.msg.ko_KR.9.1.0.8.U202336
mqm.ft.logger.9.1.0.8.U202320 mqm.msg.pl_PL.9.1.0.8.U202337
mqm.ft.service.9.1.0.8.U202321 mqm.msg.pt_BR.9.1.0.8.U202338
mqm.ft.tools.9.1.0.8.U202322 mqm.msg.ru_RU.9.1.0.8.U202339
mqm.gskit.rte.9.1.0.8.U202323 mqm.msg.zh_CN.9.1.0.8.U202340
mqm.java.rte.9.1.0.8.U202324 mqm.msg.zh_TW.9.1.0.8.U202342
mqm.jre.rte.9.1.0.8.U202325 mqm.server.rte.9.1.0.8.U202344
mqm.man.en_US.data.9.1.0.8.U202326 mqm.web.rte.9.1.0.8.U202346
mqm.msg.Ja_JP.9.1.0.8.U202335 mqm.xr.service.9.1.0.8.U202345

3. Issue the following command to obtain the text file mq9108.installpl.txt, to be used later in the
procedure: # installp -l -d /downloads/mq9108 > mq9108.installpl.txt
The output text file looks like the following text.
Note: Only the first few lines are shown here.

Fileset Name Level I/U Q Content

====================================================================
mqm.amqp.rte 9.1.0.8 S N usr (R)
# IBM MQ AMQP Service
mqm.ams.rte 9.1.0.8 S N usr (R)
# IBM MQ Advanced - Advanced Message Security
mqm.base.runtime 9.1.0.8 S N usr,root (R)
# IBM MQ Runtime for Client and Server
mqm.base.samples 9.1.0.8 S N usr (R)
# IBM MQ Samples

4. Use the output file from Step “3” on page 286 as input to the following command: # installp -r
-f mq9108.installpl.txt

Verifying selections...
done
Verifying requisites...done
Results...
SUCCESSES
---------
Filesets listed in this section passed pre-reject verification
and will be rejected.
Selected Filesets
-----------------Page 5 of 5
mqm.amqp.rte 9.1.0.8 # IBM MQ AMQP Service
mqm.ams.rte 9.1.0.8 # IBM MQ Advanced - Advanced M...
mqm.base.runtime 9.1.0.8 # IBM MQ Runtime for Client an...
...
+-----------------------------------------------------------------------------+
Installation Summary
--------------------
Name Level Part Event Result
-------------------------------------------------------------------------------
mqm.amqp.rte 9.1.0.8 USR REJECT SUCCESS

286 Installing and migrating IBM MQ

mqm.ams.rte 9.1.0.8 USR REJECT SUCCESS
mqm.base.runtime 9.1.0.8 ROOT REJECT SUCCESS

Attention: Note the following:

a. There will be around 30-40 blank lines following "Verifying selections..." and it took some
time. you need to wait until the command produces meaningful output.
b. The output in the preceding text shows only a few lines of the final summary at the end and
the result column shows SUCCESS.
5. Issue the command # lslpp -la "mqm*" again, and you see that the ones for 9.1.0.8 are no longer
included:
You see the following output:

+-----------------------------------------------------------------------------+
INSTALL ROOT PATH = /
+-----------------------------------------------------------------------------+
Fileset Level State Description
----------------------------------------------------------------------------
Path: /usr/lib/objrepos
mqm.amqp.rte 9.1.0.0 COMMITTED IBM MQ AMQP Service
9.1.0.7 APPLIED IBM MQ AMQP Service
mqm.ams.rte 9.1.0.0 COMMITTED IBM MQ Advanced - Advanced Message Security
9.1.0.7 APPLIED IBM MQ Advanced - Advanced Message Security
mqm.base.runtime 9.1.0.0 COMMITTED IBM MQ Runtime for Client and Server
9.1.0.7 APPLIED IBM MQ Runtime for Client and Server

Related tasks
“Reverting to the previous maintenance level on AIX” on page 283
You can revert to a previous maintenance level by using the System Management Interface Tool (SMIT).

Staging maintenance level updates on AIX

On AIX, you can use multiple installations of IBM MQ on the same server to control the release of
maintenance level updates.

Before you begin

The steps in this task are based on an example scenario in which it is assumed that you have two copies
of IBM MQ named Inst_1 and Inst_2, and a number of applications and two queue managers, QM1 and
QM2, running on a server. To set up your configuration for this scenario, complete the following steps:
1. Install two copies of IBM MQ. In this example, they are named Inst_1 and Inst_2.
2. Make Inst_1 primary by running setmqinst.
3. Associate all the queue managers on the server with Inst_1 by running setmqm.
4. Start all the queue managers on the server.
Note: From 1Q 2023, for Multiplatforms, there are two types of maintenance:
• Fix packs, which contain roll-ups of all defects fixed since the previous fix pack delivery (or GA).
Fix packs are produced exclusively for Long Term Support (LTS) releases during their normal support
lifecycle.
• Cumulative security updates (CSUs), which are smaller updates and contain security patches released
since the previous maintenance (GA). CSUs are produced for LTS releases (including releases in
extended support), and also for the latest IBM MQ Continuous Delivery (CD) release, as required to
deliver relevant security patches.
For maintenance releases in or after 1Q 2023, the fourth digit in the VRMF represents either a fix pack
number or a CSU number. Both types of maintenance are mutually cumulative (that is, they contain
everything included in older CSUs and fix packs), and both are installed using the same mechanisms for
applying maintenance. Both types of maintenance update the F-digit of the VRMF to a higher number than
any previous maintenance: fix packs use "F" values divisible by 5, CSUs use "F" values not divisible by 5.

Installing and migrating 287

 For maintenance releases before 1Q 2023, the fourth digit in the VRMF always represents the fix pack
level. For example, the first fix pack of the IBM MQ 9.3.0 LTS release is numbered 9.3.0.1.
For more information, see Changes to IBM MQ's maintenance delivery model.

About this task

You can install multiple copies of IBM MQ on a server to stage the release of IBM MQ maintenance level
updates. For example, as in the scenario that is described in the task steps, by using two installations
to roll out maintenance level updates, you maintain two maintenance levels on a server, with the aim of
getting all queue managers and applications to the production maintenance level before replacing the
previous level of maintenance with the next level.
Which installation an application uses is driven by the queue manager that an application connects to.
The setmqm command associates a queue manager with an installation. You can associate a queue
manager with a different installation as long as the installation is at the same or higher command level.
In this scenario, all the installations are at the same command level. You can associate or reassociate a
queue manager with either of the installations running any of the fix packs or cumulative security updates
(CSUs).
In this scenario, an application links to the primary installation. When it connects to a queue manager,
IBM MQ switches the linkage to the installation associated with the queue manager; see “Multi-
installation queue manager coexistence on AIX, Linux, and Windows” on page 357.
For applications built with the link options described in the product documentation, the simplest way to
configure the link library search path for IBM MQ applications is to make an installation primary. Only if it
is important to pick up a fix in the IBM MQ link library itself, must you review the search path. Either you
must make the installation with the IBM MQ link library fix primary, or make a local adjustment for the
application, perhaps by running the setmqenv command.
Running commands is a different matter. Commands are always run from the primary installation, or the
installation you have selected by running the setmqenv command. If you run a command from the wrong
installation, the command fails. For example, if QM1 is associated with Inst_1, running the command
Inst_2_Installation_path/bin/strmqm QM1 fails.

Procedure
Apply the first maintenance level update to Inst_2.
1. Download the first fix pack or cumulative security update (CSU) for the version of your product when
it is released.
See “Where to find downloadable installation images” on page 9.
2. Apply the fix pack or cumulative security update (CSU) that you downloaded to Inst_2.
For more information, see “Applying maintenance level updates on AIX” on page 280.
3. Verify Inst_2.
4. Transfer the queue managers to Inst_2 one at a time.
a) Stop QM1 and the applications connected to it.
The endmqm command informs an application that the queue manager it is connected to is
stopping; see Stopping a queue manager.
Note: “Applying maintenance level updates to multi-instance queue managers on AIX” on page
289 describes how to apply maintenance to a multi-instance queue manager. A multi-instance
queue manager can continue to run on one server, while maintenance is applied to another server.
b) Set up the local environment to the installation Inst_2.

. Inst_2_INSTALLATION_PATH/bin/setmqenv -s

c) Associate the queue manager with Inst_2.

setmqm -m QM1 -n Inst_2

288 Installing and migrating IBM MQ

 d) Start QM1.

strmqm QM1

e) Repeat substeps c and d for QM2.

5. Set Inst_2 primary.

Inst_2_INSTALLATION_PATH/bin/setmqinst -i -n Inst_2

Apply the second maintenance level update to Inst_1.

6. Download the next fix pack or cumulative security update (CSU), for the version of your product when
it is released.
For more information, see “Where to find downloadable installation images” on page 9.
7. Apply the fix pack or cumulative security update (CSU), that you have just downloaded to Inst_1.
8. Verify Inst_1.
9. Transfer the queue managers to Inst_1 one at a time.
Follow the procedure in step “4” on page 288, replacing Inst_2 by Inst_1 in the instructions.
10. Set Inst_1 primary.

Inst_1_INSTALLATION_PATH/bin/setmqinst -i -n Inst_1

For subsequent maintenance updates, alternate between Inst_2 and Inst_1.

11. Alternate between repeating steps “1” on page 288 to “5” on page 289 for Inst_2 and steps “6” on
page 289 to “10” on page 289 for Inst_1.
Related concepts
“Queue manager coexistence” on page 355
Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations.
“Multi-installation queue manager coexistence on AIX, Linux, and Windows” on page 357
You can install multiple copies of IBM MQ for AIX, Linux, and Windows on the same server. These IBM MQ
copies can be at the same or different version levels. This is called a multi-installation. Multi-installation is
particularly useful when you upgrade from one IBM MQ version to a later version, because it allows you to
run the earlier version alongside the later version.
Related tasks
Associating a queue manager with an installation
Changing the primary installation
Related reference
setmqenv
setmqinst
setmqm

Applying maintenance level updates to multi-instance queue managers on

AIX
On AIX, you can use multi-instance queue managers to reduce the outage caused by applying
maintenance updates.

Before you begin

Before starting this task, read through the prerequisites described in Before you begin in “Applying
maintenance level updates on AIX” on page 280.

Installing and migrating 289

 Before starting this task, see that the maintenance is applied to the IBM MQ installation on a server and
not to individual queue managers. Before you apply maintenance, you must stop all the queue managers,
and any IBM MQ service, on a server.
If you want a queue manager to keep running while maintenance is applied, you must configure it as
a multi-instance queue manager, and have a standby instance running on another server. If the queue
manager that you want to keep running is an existing single instance queue manager, you must convert it
to a multi-instance queue manager. For prerequisites and guidance how to create a multi-instance queue
manager, see Multi-instance queue managers.
If you are running multi-instance queue managers, you then can apply a maintenance update to a running
queue manager by switching the active instance to a different server.
Typically, active and standby installations are maintained at the same maintenance level. Consult the
maintenance instructions for each update. Consult the instructions to see if it is possible to run the active
and standby instances at different maintenance levels. Check whether fail over from higher to lower, or
only lower to higher maintenance level is possible.
The instructions for applying a maintenance update might require you to stop a multi-instance queue
manager completely.
If you have a primary server for running active queue manager instances, and a secondary server that
runs standby instances, you have a choice of updating the primary or secondary server first. If you update
the secondary server first, you must switch back to the primary server when both servers have been
updated.
If you have active and standby instances on several servers, you must plan in what order you update the
servers to minimize the disruption caused by ending the active instances on each server you update.

About this task

Combine the steps in this task with the maintenance update procedure for applying maintenance to an
IBM MQ server installation.

Procedure
1. Where the maintenance update procedure instructs you to stop all running queue managers, or
quiesce IBM MQ do the following instead:
See: “Applying and removing maintenance on AIX” on page 280
a) If the queue manager is running as standby:
• End the standby with the endmqm -x QMgrName command.
b) If the queue manager is running as the active instance:
End the instance and transfer control to the standby instance with the endmqm command. For
example, endmqm -shutdown_option -s QMgrName, where -shutdown_option is an optional
parameter specifying the type of shutdown. For more information, see endmqm.
If there is no standby instance running, the command fails, and you must start a standby instance
on a different server.
c) If a queue manager is running as a single instance queue manager, you have no alternative but to
stop the queue manager before applying the maintenance update.
When you complete this step, no queue manager instances are left running on the server you intend to
update.
2. Continue with the maintenance update procedure, following the step to issue the endmqm command,
or quiesce IBM MQ and apply maintenance to the IBM MQ server.
3. When you have completed the maintenance update, restart all the queue managers on the IBM MQ
server, permitting standby instances:
Use the following command:

290 Installing and migrating IBM MQ

 strmqm -x QmgrName

4. Repeat the procedure on the standby server, to update its maintenance level.
5. If necessary, switch the active instances back to the primary servers:
Use the endmqm -shutdown_option -s QMgrName command, and the restart the instances using
the strmqm -x QmgrName command.

Applying and removing maintenance on IBM i

Maintenance tasks associated with IBM i platforms are grouped in this section.

Procedure
• To apply maintenance level updates, see “Applying maintenance level updates on IBM i” on page 291.
• To restore a queue manager to the previous version of the product from the latest version, see
“Restoring a queue manager to a previous release on IBM i” on page 294.
• For information on how to use use multi-instance queue managers to reduce the outage caused by
applying maintenance updates, see “Applying maintenance updates to multi-instance queue managers
on IBM i” on page 295.
Related tasks
“Applying maintenance to IBM MQ” on page 278
Maintenance is the application of a reversible fix. Any changes to queue manager data are compatible
with the previous code level.

Applying maintenance level updates on IBM i

You apply maintenance level updates on the latest release by stopping IBM MQ and using the IBM i
standard maintenance procedure.

Before you begin

To find out what version you have currently installed, use the following commands:

Table 36. IBM MQ commands to display the installed versions

IBM MQ Product Version command
IBM MQ Server
DSPMQMVER

Installing and migrating 291

 Table 36. IBM MQ commands to display the installed versions (continued)
IBM MQ Product Version command
IBM MQ Java IBM MQ classes for Java:

java com.ibm.mq.MQJavaLevel

Note: For this command to work, you might need to set your environment
classpath to include:
• /QIBM/ProdData/mqm/java/lib/com.ibm.mq.jar
IBM MQ classes for Java Message Service:

java com.ibm.mq.jms.MQJMSLevel

Note: For this command to work, you might need to set your environment
classpath to include:
• /QIBM/ProdData/mqm/java/lib/
com.ibm.mq.jakarta.client.jar (Jakarta
Messaging 3.0) or /QIBM/
ProdData/mqm/java/lib/com.ibm.mq.allclient.jar (JMS 2.0)
See Environment variables relevant to IBM MQ classes for Java and
Environment variables relevant to IBM MQ classes for JMS.

IBM MQ Client
DSPMQMVER

About this task

Maintenance updates for IBM i are supplied as PTFs (Program Temporary Fixes). They are available for
download from the web as save files, which are normally stored in the QGPL library. IBM i PTF's can be
found in Fix Central.

Procedure
Prepare to quiesce queue managers:
1. Read the cover letter carefully to see if you need to take any special actions.
2. Sign on to a new interactive IBM i session, ensuring that you are not accessing any IBM MQ objects.
3. Ensure that you have the following authorities:
• *ALLOBJ authority, or object management authority for the QMQM library.
• Sufficient authority to use the ENDSBS command.
4. Warn all users that you are going to stop IBM MQ.
5. Stop the mqweb server by entering the following command:

ENDMQWEB

Quiesce all queue managers:

6. Run the ENDMQM command:

ENDMQM MQMNAME(*ALL) OPTION(*CNTRLD) ENDCCTJOB(*YES) RCDMQMIMG(*YES)

TIMEOUT( 15 )

Where 15 is a timeout value in seconds.

292 Installing and migrating IBM MQ

 If the ENDMQM command has not completed within a reasonable period (at least 10 minutes), use
the WRKMQM command. This command identifies the queue managers that are still ending. Then
force each one in turn to stop by running the following command:

ENDMQM MQMNAME( QMGRNAME ) OPTION(*IMMED)

Where QMGRNAME is the name of the queue manager.

Complete the tidying up of shared memory by running the following command:

ENDMQM MQMNAME(*ALL) OPTION(*IMMED) ENDCCTJOB(*YES) RCDMQMIMG(*NO)

TIMEOUT( 15 )

If the commands in the previous step do not complete, end the subsystem immediately:
7. Run the following command:

ENDSBS SBS(QMQM) OPTION(*IMMED)

If the command in the previous step also does not complete, use the operating system command
ENDJOB to end all jobs in the subsystem QMQM:
Note: Do not use ENDJOBABN unless you intend to perform an IPL on the machine before starting IBM
MQ. Ending IBM MQ jobs using ENDJOBABN can lead to damaged semaphores, which in turn can prevent
your queue manager from starting.
8. If a QMGR must be shut down manually, end the jobs (ENDJOB) in the following order. Wait a few
minutes for AMQA* or AMQZ* jobs to tidy up.
a. RUNMQLSR - TCP listener (multi-threaded)
b. AMQCLMAA - TCP listener (single-threaded)
c. AMQRMPPA - Channel process pooling job
d. RUNMQCHI - channel initiator
e. AMQCRSTA - receiving MCA jobs
f. RUNMQCHL - sending MCA jobs
g. AMQCRS6B - LU62 receiver channel
h. AMQPCSEA - command server
i. RUNMQTRM - Application trigger monitor
j. RUNMQDLQ - Dead letter queue handler
k. AMQFCXBA - IBM Integration Bus Worker Job
l. AMQFQPUB - Queued Publish/Subscribe Daemon
m. RUNMQBRK - IBM Integration Bus Control Job
n. AMQZMUC0 ('0' is a zero) - Utility Manager
o. AMQZMUF0 ('0' is a zero) - Utility Manager
p. AMQZMUR0 ('0' is a zero) - Utility Manager
q. AMQZMGR0 ('0' is a zero) - Process Controller
r. AMQRRMFA - cluster repository manager
s. AMQZDMAA - deferred message manager
t. AMQZFUMA - object authority manager
u. AMQZLSA0 ('0' is a zero) - LQM agents
v. AMQZLAA0 ('0' is a zero) - LQM agents
w. AMQZXMA0 ('0' is a zero) - Execution Controller
9. Run the following command:

Installing and migrating 293

 ENDMQM MQMNAME( QMGRNAME ) OPTION(*IMMED)

10. Run the following command:

ENDMQM MQMNAME(*ALL) OPTION(*CNTRLD) ENDCCTJOB(*YES) RCDMQMIMG(*NO)

TIMEOUT( 05 )

Where 05 is a timeout value in seconds.

11. Manually clean up shared memory.
Run the following command:

EDTF '/QIBM/UserData/mqm/qmgrs'

then:
a. Take option 5 for &SYSTEM and check that the following directories are empty: isem, esem,
msem, ssem, and shmem.
b. Take option 5 for QMGRNAME and check that the following directories are empty:- isem, esem,
msem, ssem, and shmem.
c. Take option 5 for &ipcc in the QMGRNAME directory and check that the following directories are
empty:- isem, esem, msem, ssem, and shmem.
d. Take option 5 for &qmpersist in the QMGRNAME directory and check that the following
directories are empty:- isem, esem, msem, ssem, and shmem.
e. Take option 5 for &app and check that the following directories are empty: isem, esem, msem,
ssem, and shmem.
Apply a PTF:
12. Load and apply a PTF.

Restoring a queue manager to a previous release on IBM i

On IBM i, you can restore a queue manager to the previous version of the product from the latest version,
if you have made a backup of the system or queue manager. If you have started the queue manager
and processed any messages, or changed the configuration, the task cannot give you any guidance on
restoring the current state of the queue manager.

Before you begin

1. You must have made a backup of the system or queue manager before you upgraded to the later
version. For more information see Backing up and restoring IBM MQ queue manager data
2. If any messages were processed after starting the queue manager, you cannot easily undo the effects
of processing the messages. You cannot revert the queue manager to the earlier version of the product
in its current state. The task cannot give you any guidance how to deal with subsequent changes that
have occurred. For example, messages that were indoubt in a channel, or in a transmission queue on
another queue manager, might have been processed. If the queue manager is part of a cluster, then
configuration messages and application messages might have been exchanged.

About this task

When you revert to a earlier version of a queue manager, you revert the queue manager to its earlier code
level. Queue manager data is reverted to the state it was in when the queue manager was backed up.
Important: If the queue manager is a member of one or more IBM MQ clusters, you should also review
and follow the steps described in Recovering a cluster queue manager.

294 Installing and migrating IBM MQ

Procedure
1. Stop the queue manager.
2. If you performed a slip installation, you must reinstall IBM MQ.
a) Uninstall the earlier installation.
b) Reinstall the product from a manufacturing refresh.
c) Apply the fix pack and interim fixes that restore IBM MQ to its previous level.
d) Restore the queue manager data from the backup taken before installing the later version.
3. Restart the earlier version queue manager.
Related tasks
Backing up and restoring a queue manager

Applying maintenance updates to multi-instance queue managers on IBM i

On IBM i, you can use multi-instance queue managers to reduce the outage caused by applying
maintenance updates.

Before you begin

Before starting this task, see that the maintenance is applied to the IBM MQ installation on a server and
not to individual queue managers. Before you apply maintenance, you must stop all the queue managers,
and any IBM MQ service, on a server.
If you want a queue manager to keep running while maintenance is applied, you must configure it as
a multi-instance queue manager, and have a standby instance running on another server. If the queue
manager that you want to keep running is an existing single instance queue manager, you must convert it
to a multi-instance queue manager. For prerequisites and guidance how to create a multi-instance queue
manager, see Multi-instance queue managers.
If you are running multi-instance queue managers, you then can apply a maintenance update to a running
queue manager by switching the active instance to a different server.
Typically, active and standby installations are maintained at the same maintenance level. Consult the
maintenance instructions for each update. Consult the instructions to see if it is possible to run the active
and standby instances at different maintenance levels. Check whether fail over from higher to lower, or
only lower to higher maintenance level is possible.
The instructions for applying a maintenance update might require you to stop a multi-instance queue
manager completely.
If you have a primary server for running active queue manager instances, and a secondary server that
runs standby instances, you have a choice of updating the primary or secondary server first. If you update
the secondary server first, you must switch back to the primary server when both servers have been
updated.
If you have active and standby instances on several servers, you must plan in what order you update the
servers to minimize the disruption caused by ending the active instances on each server you update.

About this task

Combine the steps in this task with the maintenance update procedure for applying maintenance to an
IBM MQ server installation.

Procedure
1. Where the maintenance update procedure instructs you to stop all running queue managers, or
quiesce IBM MQ do the following instead:
See: “Applying and removing maintenance on IBM i” on page 291.
a) If the queue manager is running as standby:

Installing and migrating 295

 End the standby by adding the INSTANCE(*STANDBY) option to the ENDMQM command.
b) If the queue manager is running as the active instance:
End the instance and transfer control to the standby instance by adding the ALWSWITCH(*YES)
option to the ENDMQM command.
If there is no standby instance running, the command fails, and you must start a standby instance
on a different server.
c) If a queue manager is running as a single instance queue manager, you have no alternative but to
stop the queue manager before applying the maintenance update.
When you complete this step, no queue manager instances are left running on the server you intend to
update.
2. Continue with the maintenance update procedure, following the step to issue the endmqm command,
or quiesce IBM MQ and apply maintenance to the IBM MQ server.
3. When you have completed the maintenance update, restart all the queue managers on the IBM MQ
server, permitting standby instances:
Add the STANDBY(*YES) option to the STRMQM command.
4. Repeat the procedure on the standby server, to update its maintenance level.
5. If necessary, switch the active instances back to the primary servers:
Use the ENDMQM command with the ALWSWITCH(*YES) option, and then restart the instances using
the STRMQM command with the STANDBY(*YES) option.

Applying and removing maintenance on Linux

Maintenance tasks associated with Linux are grouped in this section.
Related tasks
“Applying maintenance to IBM MQ” on page 278
Maintenance is the application of a reversible fix. Any changes to queue manager data are compatible
with the previous code level.

Applying maintenance on Linux

From IBM MQ 9.4.0, you apply maintenance by upgrading IBM MQ.

About this task

Maintenance updates are cumulative. You can apply your chosen update directly, without applying any
previous updates first. The maintenance level updates might contain updates for one or more packages.
Apply those parts of an update that correspond to the packages that are applied in your installation.

Procedure
• To upgrade by using rpm, follow the steps in “Upgrading an IBM MQ installation on Linux using the rpm
command” on page 322.
• To upgrade by using yum, follow the steps in “Upgrading an IBM MQ installation on Linux Red Hat
using yum” on page 325.
• To upgrade by using dpkg, follow the steps in “Upgrading an IBM MQ installation on Linux Ubuntu
using dpkg” on page 328.
• To upgrade by using apt, follow the steps in “Upgrading an IBM MQ installation on Linux Ubuntu using
apt” on page 330.

296 Installing and migrating IBM MQ

 Staging maintenance level updates on Linux
On Linux, you can use multiple installations of IBM MQ on the same server to control the release of
maintenance level updates.

Before you begin

The steps in this task are based on an example scenario in which it is assumed that you have two copies
of IBM MQ named Inst_1 and Inst_2, and a number of applications and two queue managers, QM1 and
QM2, running on a server. To set up your configuration for this scenario, complete the following steps:
1. Install two copies of IBM MQ. In this example, they are named Inst_1 and Inst_2.
2. Make Inst_1 primary by running setmqinst.
3. Associate all the queue managers on the server with Inst_1 by running setmqm.
4. Start all the queue managers on the server.
5. Show and connect all direct connections with the queue managers associated with Inst_1 in IBM MQ
Explorer.
6. Set up remote connections to all the queue managers in each instance of IBM MQ Explorer.
Note: From 1Q 2023, for Multiplatforms, there are two types of maintenance:
• Fix packs, which contain roll-ups of all defects fixed since the previous fix pack delivery (or GA).
Fix packs are produced exclusively for Long Term Support (LTS) releases during their normal support
lifecycle.
• Cumulative security updates (CSUs), which are smaller updates and contain security patches released
since the previous maintenance (GA). CSUs are produced for LTS releases (including releases in
extended support), and also for the latest IBM MQ Continuous Delivery (CD) release, as required to
deliver relevant security patches.
For maintenance releases in or after 1Q 2023, the fourth digit in the VRMF represents either a fix pack
number or a CSU number. Both types of maintenance are mutually cumulative (that is, they contain
everything included in older CSUs and fix packs), and both are installed using the same mechanisms for
applying maintenance. Both types of maintenance update the F-digit of the VRMF to a higher number than
any previous maintenance: fix packs use "F" values divisible by 5, CSUs use "F" values not divisible by 5.
For maintenance releases before 1Q 2023, the fourth digit in the VRMF always represents the fix pack
level. For example, the first fix pack of the IBM MQ 9.3.0 LTS release is numbered 9.3.0.1.
For more information, see Changes to IBM MQ's maintenance delivery model.

About this task

You can install multiple copies of IBM MQ on a server to stage the release of IBM MQ maintenance level
updates. For example, as in the scenario that is described in the task steps, by using two installations
to roll out maintenance level updates, you maintain two maintenance levels on a server, with the aim of
getting all queue managers and applications to the production maintenance level before replacing the
previous level of maintenance with the next level.
Which installation an application uses is driven by the queue manager that an application connects to.
The setmqm command associates a queue manager with an installation. You can associate a queue
manager with a different installation as long as the installation is at the same or higher command level.
In this scenario, all the installations are at the same command level. You can associate or reassociate a
queue manager with either of the installations running any of the fix packs or cumulative security updates
(CSUs).
In this scenario, an application links to the primary installation. When it connects to a queue manager,
IBM MQ switches the linkage to the installation associated with the queue manager; see “Multi-
installation queue manager coexistence on AIX, Linux, and Windows” on page 357.
For applications built with the link options described in the product documentation, the simplest way to
configure the link library search path for IBM MQ applications is to make an installation primary. Only if it

Installing and migrating 297

 is important to pick up a fix in the IBM MQ link library itself, must you review the search path. Either you
must make the installation with the IBM MQ link library fix primary, or make a local adjustment for the
application, perhaps by running the setmqenv command.
Running commands is a different matter. Commands are always run from the primary installation, or the
installation you have selected by running the setmqenv command. If you run a command from the wrong
installation, the command fails. For example, if QM1 is associated with Inst_1, running the command,
Inst_2_Installation_path/bin/strmqm QM1 fails.

If you are using IBM MQ Explorer and you have two installations, you also have two IBM
MQ Explorer instances. One linked to one installation, and one to the other. Each IBM MQ Explorer shows
locally connected queue managers that are associated with the same installation as the instance of IBM
MQ Explorer. To monitor all the queue managers on a server, set up remote connections to the queue
managers associated with the other installations.

Procedure
Apply the first maintenance level update to Inst_2.
1. Download the first fix pack or cumulative security update (CSU) when it is released.
For more information, see “Where to find downloadable installation images” on page 9.
2. Apply the fix pack or cumulative security update (CSU) you downloaded to Inst_2.
For more information, see “Applying maintenance on Linux” on page 296.
3. Verify Inst_2.
4. Transfer the queue managers to Inst_2 one at a time.
a) Stop QM1 and the applications connected to it.
The endmqm command informs an application that the queue manager it is connected to is
stopping; see Stopping a queue manager.
Note: “Applying maintenance level updates to multi-instance queue managers on Linux” on page
299 describes how to apply maintenance to a multi-instance queue manager. A multi-instance
queue manager can continue to run on one server, while maintenance is applied to another server.
b) Set up the local environment to the installation Inst_2.

. Inst_2_INSTALLATION_PATH/bin/setmqenv -s

c) Associate the queue manager with Inst_2.

setmqm -m QM1 -n Inst_2

d) Start QM1.

strmqm QM1

e) Repeat substeps c and d for QM2.

f)
Set up IBM MQ Explorer for Inst_2.
i) Start the Inst_2 instance of IBM MQ Explorer
ii) Click IBM MQ > Queue Managers > Show/Hide Queue Managers... >
iii) Click each directly connected queue manager listed in the Hidden Queue Managers list >
Show.
iv) Click Close.
5. Set Inst_2 primary.

Inst_2_INSTALLATION_PATH/bin/setmqinst -i -n Inst_2

298 Installing and migrating IBM MQ

Apply the second maintenance level update to Inst_1.
6. Download the next fix pack or cumulative security update (CSU), for the version of your product when
it is released.
For more information, see “Where to find downloadable installation images” on page 9.
7. Apply the fix pack or cumulative security update (CSU), that you have just downloaded to Inst_1.
For more information, see “Applying maintenance on Linux” on page 296.
8. Verify Inst_1.
9. Transfer queue managers to Inst_1 one at a time.
a) Follow the procedure in step “4” on page 298
Replacing Inst_2 by Inst_1 in the instructions.
10. Set Inst_1 primary.

Inst_1_INSTALLATION_PATH/bin/setmqinst -i -n Inst_1

For subsequent maintenance fixes, alternate between Inst_2 and Inst_1.

11. Alternate between repeating steps “1” on page 298 to “5” on page 298 for Inst_2 and steps “6” on
page 299 to “10” on page 299 for Inst_1.
Related concepts
“Queue manager coexistence” on page 355
Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations.
“Multi-installation queue manager coexistence on AIX, Linux, and Windows” on page 357
You can install multiple copies of IBM MQ for AIX, Linux, and Windows on the same server. These IBM MQ
copies can be at the same or different version levels. This is called a multi-installation. Multi-installation is
particularly useful when you upgrade from one IBM MQ version to a later version, because it allows you to
run the earlier version alongside the later version.
Related tasks
Associating a queue manager with an installation
Changing the primary installation
Related reference
setmqenv
setmqinst
setmqm

Applying maintenance level updates to multi-instance queue managers on Linux

On Linux, you can use multi-instance queue managers to reduce the outage caused by applying
maintenance updates.

Before you begin

Before starting this task, see that the maintenance is applied to the IBM MQ installation on a server and
not to individual queue managers. Before you apply maintenance, you must stop all the queue managers,
and any IBM MQ service, on a server.
If you want a queue manager to keep running while maintenance is applied, you must configure it as
a multi-instance queue manager, and have a standby instance running on another server. If the queue
manager that you want to keep running is an existing single instance queue manager, you must convert it
to a multi-instance queue manager. For prerequisites and guidance how to create a multi-instance queue
manager, see Multi-instance queue managers.
If you are running multi-instance queue managers, you then can apply a maintenance update to a running
queue manager by switching the active instance to a different server.

Installing and migrating 299

 Typically, active and standby installations are maintained at the same maintenance level. Consult the
maintenance instructions for each update. Consult the instructions to see if it is possible to run the active
and standby instances at different maintenance levels. Check whether fail over from higher to lower, or
only lower to higher maintenance level is possible.
The instructions for applying a maintenance update might require you to stop a multi-instance queue
manager completely.
If you have a primary server for running active queue manager instances, and a secondary server that
runs standby instances, you have a choice of updating the primary or secondary server first. If you update
the secondary server first, you must switch back to the primary server when both servers have been
updated.
If you have active and standby instances on several servers, you must plan in what order you update the
servers to minimize the disruption caused by ending the active instances on each server you update.

About this task

Combine the steps in this task with the maintenance update procedure for applying maintenance to an
IBM MQ server installation.

Procedure
1. Ensure that no queue manager instances are running on the server that you intend to apply
maintenance to:
• If the queue manager is running as standby, end the standby with the following command:

endmqm -x QMgrName

• If the queue manager is running as the active instance, end the instance and transfer control to the
standby instance with the endmqm command. For example:

endmqm -shutdown_option -s QMgrName

where -shutdown_option is an optional parameter specifying the type of shutdown. For more
information, see endmqm.
If there is no standby instance running, the command fails, and you must start a standby instance
on a different server.
• If a queue manager is running as a single instance queue manager, you have no alternative but to
stop the queue manager before applying the maintenance update.
When you complete this step, no queue manager instances are left running on the server you intend to
update.
2. From IBM MQ 9.4.0, you install the maintenance updates by upgrading IBM MQ. Follow the
appropriate steps outlined in one of the following topics to install the maintenance updates on the
server:
• To upgrade by using rpm, follow the steps in “Upgrading an IBM MQ installation on Linux using the
rpm command” on page 322.
• To upgrade by using yum, follow the steps in “Upgrading an IBM MQ installation on Linux Red Hat
using yum” on page 325.
• To upgrade by using dpkg, follow the steps in “Upgrading an IBM MQ installation on Linux Ubuntu
using dpkg” on page 328.
• To upgrade by using apt, follow the steps in “Upgrading an IBM MQ installation on Linux Ubuntu
using apt” on page 330.
3. When you have completed the maintenance update, restart all the queue managers on the IBM MQ
server, permitting standby instances:
Use the following command:

300 Installing and migrating IBM MQ

 strmqm -x QmgrName

4. Repeat the procedure on the standby server to update its maintenance level.
5. If necessary, switch the active instances back to the primary servers:
a) End the instances by using the following command:

endmqm -shutdown_option -s QMgrName

where -shutdown_option is an optional parameter specifying the type of shutdown. For more
information, see endmqm.
b) Restart the instances by using the following command:

strmqm -x QMgrName

Applying maintenance level updates for RDQM

There are different procedures for applying maintenance level updates to a high availability (HA)
configuration, a disaster recovery (DR) configuration, or a combined DR/HA configuration.

About this task

For RDQM HA configurations, complete the steps on each node in the HA group in turn. Processing can
then continue on the other nodes in the group while the update is in progress.

Procedure
• To apply maintenance level updates for HA RDQM:
a) Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
b) Change into the directory containing the maintenance packages.
c) Suspend the HA group on the node, by entering the following command:

rdqmadm -s

d) If DRBD has been updated in the Fix Pack, complete the following steps:
a. Determine which DRBD kernel module is needed for the system on which RDQM is being
installed. See https://ibm.biz/mqrdqmkernelmods for up-to-date kernel module information.
Helper scripts are provided in the kmod-drbd-9 directories. For example, on a RHEL 8.2
system, running the helper script Advanced/RDQM/PreReqs/el8/kmod-drbd-9/modver
returns the following information, identifying the kernel module that you need to install:

kmod-drbd-9.0.23_4.18.0_193-1.x86_64.rpm

b. Update the appropriate DRBD kernel module that you identified. For example, for RHEL 8.2 you
run the following command:

yum install Advanced/RDQM/PreReqs/el8/kmod-drbd-9/kmod-

drbd-9.0.23_4.18.0_193-1.x86_64.rpm

c. Update the DRBD utilities. For example, for RHEL 8.2 you run the following command:

yum install Advanced/RDQM/PreReqs/el8/drbd-utils-9/*

e) If Pacemaker has been updated in the Fix Pack, update it in RDQM. For example, for RHEL 8.2, run
the following command:

Installing and migrating 301

 yum install --allowerasing Advanced/RDQM/PreReqs/el8/pacemaker-2/*

f) Apply the FixPack by using the procedure for upgrading on Linux using yum, see “Upgrading an
IBM MQ installation on Linux Red Hat using yum” on page 325. For an RDQM install, the minimum
commands are:

yum install MQSeriesGSKit* MQSeriesServer* MQSeriesRuntime*

yum install Advanced/RDQM/MQSeriesRDQM*

g) If DRBD or Pacemaker have been updated in the Fix Pack, reboot the node, for example:

reboot

h) Resume the HA group on the node by entering the following command:

rdqmadm -r

Proceed to the next node in the HA group and repeat the procedure.
• To apply maintenance level updates for DR RDQM on the DR secondary node:
a) Apply maintenance level updates to the DR secondary node:
a. Log in as root, or with sufficient authority to run the following commands.
b. Change into the directory containing the maintenance packages.
c. If DRBD has been updated in the Fix Pack, complete the following steps:
i) Determine which DRBD kernel module is needed for the system on which RDQM is being
installed. See https://ibm.biz/mqrdqmkernelmods for up-to-date kernel module information.
Helper scripts are provided in the kmod-drbd-9 directories. For example, on a RHEL 8.2
system, running the helper script Advanced/RDQM/PreReqs/el8/kmod-drbd-9/modver
returns the following information, identifying the kernel module that you need to install:

kmod-drbd-9.0.23_4.18.0_193-1.x86_64.rpm

ii) Update the appropriate DRBD kernel module that you identified. For example, for RHEL 8.2
you run the following command:

yum install Advanced/RDQM/PreReqs/el8/kmod-drbd-9/kmod-

drbd-9.0.23_4.18.0_193-1.x86_64.rpm

iii) Update the DRBD utilities. For example, for RHEL 8.2 you run the following command:

yum install Advanced/RDQM/PreReqs/el8/drbd-utils-9/*

d. If Pacemaker has been updated in the Fix Pack, update it in RDQM. For example, for RHEL 8.2,
run the following command:

yum install --allowerasing Advanced/RDQM/PreReqs/el8/pacemaker-2/*

e. Apply the FixPack by using the procedure for upgrading on Linux using yum, see “Upgrading
an IBM MQ installation on Linux Red Hat using yum” on page 325. For an RDQM install, the
minimum commands are:

yum install MQSeriesGSKit* MQSeriesServer* MQSeriesRuntime*

yum install Advanced/RDQM/MQSeriesRDQM*

f. If DRBD or Pacemaker have been updated in the Fix Pack, reboot the node, for example:

reboot

b) On the DR primary node, either end the DR queue managers or perform a managed failover of the
DR queue managers to the DR secondary node.
c) Apply maintenance level updates to the DR primary node:

302 Installing and migrating IBM MQ

 a. Log in as root, or with sufficient authority to run the following commands.
b. Change into the directory containing the maintenance packages.
c. If DRBD has been updated in the Fix Pack, complete the following steps:
i) Determine which DRBD kernel module is needed for the system on which RDQM is being
installed. See https://ibm.biz/mqrdqmkernelmods for up-to-date kernel module information.
Helper scripts are provided in the kmod-drbd-9 directories. For example, on a RHEL 8.2
system, running the helper script Advanced/RDQM/PreReqs/el8/kmod-drbd-9/modver
returns the following information, identifying the kernel module that you need to install:

kmod-drbd-9.0.23_4.18.0_193-1.x86_64.rpm

ii) Update the appropriate DRBD kernel module that you identified. For example, for RHEL 8.2
you run the following command:

yum install Advanced/RDQM/PreReqs/el8/kmod-drbd-9/kmod-

drbd-9.0.23_4.18.0_193-1.x86_64.rpm

iii) Update the DRBD utilities. For example, for RHEL 8.2 you run the following command:

yum install Advanced/RDQM/PreReqs/el8/drbd-utils-9/*

d. If Pacemaker has been updated in the Fix Pack, update it in RDQM. For example, for RHEL 8.2,
run the following command:

yum install --allowerasing Advanced/RDQM/PreReqs/el8/pacemaker-2/*

e. Apply the FixPack by using the procedure for upgrading on Linux using yum, see “Upgrading
an IBM MQ installation on Linux Red Hat using yum” on page 325. For an RDQM install, the
minimum commands are:

yum install MQSeriesGSKit* MQSeriesServer* MQSeriesRuntime*

yum install Advanced/RDQM/MQSeriesRDQM*

f. If DRBD or Pacemaker have been updated in the Fix Pack, reboot the node, for example:

reboot

d) On the DR primary node, either start the DR queue managers or perform a managed failover of the
DR queue managers to the DR primary node.
• To apply maintenance level updates for HA/DR RDQM:
a) Apply maintenance to the HA group on your recovery site. Complete the following steps on each
node in the group in turn.
a. Log in as root, or with sufficient authority to run the following commands.
b. Change into the directory containing the maintenance packages.
c. Suspend the HA group on the node, by entering the following command:

rdqmadm -s

d. If DRBD has been updated in the Fix Pack, complete the following steps:
i) Determine which DRBD kernel module is needed for the system on which RDQM is being
installed. See https://ibm.biz/mqrdqmkernelmods for up-to-date kernel module information.
Helper scripts are provided in the kmod-drbd-9 directories. For example, on a RHEL 8.2
system, running the helper script Advanced/RDQM/PreReqs/el8/kmod-drbd-9/modver
returns the following information, identifying the kernel module that you need to install:

kmod-drbd-9.0.23_4.18.0_193-1.x86_64.rpm

ii) Update the appropriate DRBD kernel module that you identified. For example, for RHEL 8.2
you run the following command:

Installing and migrating 303

 yum install Advanced/RDQM/PreReqs/el8/kmod-drbd-9/kmod-
drbd-9.0.23_4.18.0_193-1.x86_64.rpm

iii) Update the DRBD utilities. For example, for RHEL 8.2 you run the following command:

yum install Advanced/RDQM/PreReqs/el8/drbd-utils-9/*

e. If Pacemaker has been updated in the Fix Pack, update it in RDQM. For example, for RHEL 8.2,
run the following command:

yum install --allowerasing Advanced/RDQM/PreReqs/el8/pacemaker-2/*

f. Apply the FixPack by using the procedure for upgrading on Linux using yum, see “Upgrading
an IBM MQ installation on Linux Red Hat using yum” on page 325. For an RDQM install, the
minimum commands are:

yum install MQSeriesGSKit* MQSeriesServer* MQSeriesRuntime*

yum install Advanced/RDQM/MQSeriesRDQM*

g. If DRBD or Pacemaker have been updated in the Fix Pack, reboot the node, for example:

reboot

h. Resume the HA group on the node by entering the following command:

rdqmadm -r

b) Apply maintenance to the HA group on your main site. Complete the following steps on each node
in the group in turn.
a. Log in as root, or with sufficient authority to run the following commands.
b. Change into the directory containing the maintenance packages.
c. Suspend the HA group on the node, by entering the following command:

rdqmadm -s

d. If DRBD has been updated in the Fix Pack, complete the following steps:
i) Determine which DRBD kernel module is needed for the system on which RDQM is being
installed. See https://ibm.biz/mqrdqmkernelmods for up-to-date kernel module information.
Helper scripts are provided in the kmod-drbd-9 directories. For example, on a RHEL 8.2
system, running the helper script Advanced/RDQM/PreReqs/el8/kmod-drbd-9/modver
returns the following information, identifying the kernel module that you need to install:

kmod-drbd-9.0.23_4.18.0_193-1.x86_64.rpm

ii) Update the appropriate DRBD kernel module that you identified. For example, for RHEL 8.2
you run the following command:

yum install Advanced/RDQM/PreReqs/el8/kmod-drbd-9/kmod-

drbd-9.0.23_4.18.0_193-1.x86_64.rpm

iii) Update the DRBD utilities. For example, for RHEL 8.2 you run the following command:

yum install Advanced/RDQM/PreReqs/el8/drbd-utils-9/*

e. If Pacemaker has been updated in the Fix Pack, update it in RDQM. For example, for RHEL 8.2,
run the following command:

yum install --allowerasing Advanced/RDQM/PreReqs/el8/pacemaker-2/*

304 Installing and migrating IBM MQ

 f. Apply the Fix Pack using the procedure for upgrading on Linux using yum, see “Upgrading
an IBM MQ installation on Linux Red Hat using yum” on page 325. For an RDQM install, the
minimum commands are:

yum install MQSeriesGSKit* MQSeriesServer* MQSeriesRuntime*

yum install Advanced/RDQM/MQSeriesRDQM*

g. If DRBD or Pacemaker have been updated in the Fix Pack, reboot the node, for example:

reboot

h. Resume the HA group on the node by entering the following command:

rdqmadm -r

Related tasks
“Installing RDQM (replicated data queue managers)” on page 255
Installation tasks associated with RDQM are grouped in this section. RDQM is available on x86-64 for
RHEL 8 (8.8 or later) and RHEL 9 (9.2 or later).

Removing maintenance level updates for RDQM

There are different procedures for removing maintenance level updates to a high availability (HA)
configuration, a disaster recovery (DR) configuration, or a combined DR/HA configuration.

About this task

For RDQM HA configurations, complete the steps on each node in the HA group in turn. Processing can
then continue on other the other nodes in the group while the update is in progress.

Procedure
• To remove maintenance level updates for HA RDQM:
a) Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
b) Suspend the HA group on the node, by entering the following command:

rdqmadm -s

c) Remove the Fix Pack using the procedure for removing maintenance level updates on Linux, see
“Removing maintenance on Linux using yum” on page 308. For example, to remove the 9.4.0.1 Fix
Pack:

yum -y downgrade pathToInstallationFiles/MQSeries*

d) Resume the node:

rdqmadm -r

Proceed to the next node in the HA group and repeat the procedure.
• To remove maintenance level updates for DR RDQM:
a) Remove maintenance level updates to the DR secondary node:
a. Log in as root, or with sufficient authority to run the following commands.

Installing and migrating 305

 b. Remove the Fix Pack using the procedure for removing maintenance level updates on Linux, see
“Removing maintenance on Linux using yum” on page 308. For example, to remove the 9.4.0.1
Fix Pack:

yum -y downgrade pathToInstallationFiles/MQSeries*

b) On the DR primary node, either end the DR queue managers or perform a managed failover of the
DR queue managers to the DR secondary node.
c) Remove maintenance level updates to the DR primary node:
a. Log in as root, or with sufficient authority to run the following commands.
b. Remove the Fix Pack using the procedure for removing maintenance level updates on Linux, see
“Removing maintenance on Linux using yum” on page 308. For example, to remove the 9.4.0.1
Fix Pack:

yum -y downgrade pathToInstallationFiles

d) On the DR primary node either start the DR queue managers or perform a managed failover of the
DR queue managers to the DR primary node.
• To remove maintenance level updates for DR/HA RDQM
a) Remove maintenance from the HA group on your recovery site. Complete the following steps on
each node in the group in turn:
a. Log in as root, or with sufficient authority to run the following commands.
b. Suspend the HA group on the node, by entering the following command:

rdqmadm -s

c. Log in as root, or with sufficient authority to run the following commands.

d. Remove the Fix Pack using the procedure for removing maintenance level updates on Linux, see
“Removing maintenance on Linux using yum” on page 308. For example, to remove the 9.4.0.1
Fix Pack:

yum -y downgrade pathToInstallationFiles

e. Resume the node:

rdqmadm -r

Proceed to the next node in the HA group and repeat the procedure.
b) Remove maintenance from the HA group on your main site. Complete the following steps on each
node in the group in turn.
a. Log in as root, or with sufficient authority to run the following commands.
b. Suspend the HA group on the node, by entering the following command:

rdqmadm -s

c. Log in as root, or with sufficient authority to run the following commands.

d. Remove the Fix Pack using the procedure for removing maintenance level updates on Linux, see
“Removing maintenance on Linux using yum” on page 308. For example, to remove the 9.4.0.1
Fix Pack:

yum -y downgrade pathToInstallationFiles

e. Resume the node:

rdqmadm -r

Proceed to the next node in the HA group and repeat the procedure.

306 Installing and migrating IBM MQ

 Removing maintenance on Linux using rpm
From IBM MQ 9.4.0, you can use the rpm command to remove maintenance from an IBM MQ installation
on Linux systems.

Before you begin

When you use rpm the IBM MQ installation that includes the maintenance level is replaced with an
installation at an earlier level of IBM MQ. Therefore, you must decide which level of IBM MQ you want to
revert to. Then you must ensure that the installation files for the earlier level of IBM MQ are available on
the system.

About this task

You can use rpm only to roll back the fix pack level. You cannot use the command to roll back the version,
release, or modification level of your IBM MQ installation. To roll back the version, release, or modification
level of your installation, you must uninstall the higher level and then install the earlier level that you
require. However, any queue managers that are running at a higher version or release of IBM MQ cannot
then be started on the earlier version or release. For more information, see “Queue manager migration”
on page 343.

Procedure
1. Complete the following tasks:
a) Stop all your IBM MQ applications.
If you use the Managed File Transfer (MFT) component, ensure that any file transfers that MFT
agents are engaged in are completed. The SYSTEM.FTE.STATE queues must contain no messages.
b) Stopped the mqweb server by using the endmqweb command.
c) Stopped your listeners by using the endmqlsr command.
d) Stopped all your queue managers by using the endmqm command.
e) Backed up your data.
For more information, see Backing up and restoring queue manager data.
2. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
3. Set your current directory to the location of the earlier level installation files. The location might be a
network location, or a local file system directory.
4. Optional: If there is more than one installation on the system, or if you want to remove maintenance
from an IBM MQ installation in a nondefault location, create a unique set of packages:
a) Run the crtmqpkg to create a unique set of packages:

./crtmqpkg suffix

where suffix specifies a name of your choosing that uniquely identifies the installation packages on
the system. suffix is not the same as an installation name, although the names can be identical.
suffix is limited to 16 characters in the ranges A-Z, a-z, and 0-9.
Note: This command creates a full copy of the installation packages in a temporary directory. By
default, the temporary directory is at /var/tmp. Ensure that the system has enough available
space before you run this command. To use a different location, you can set the TMPDIR
environment variable before you run the crtmqpkg command. For example:

$ TMPDIR=/test ./crtmqpkg suffix installationPath

Installing and migrating 307

 b) Set your current directory to the location that is specified when the crtmqpkg command operation
completes successfully.
5. Remove the IBM MQ maintenance level:
• To remove the maintenance level from all available components in the default location, use the
following command:

rpm --oldpackage -Uvh pathToInstallationFiles/MQSeries*

where pathToInstallationFiles specifies the path where the earlier level IBM MQ rpm installation
files are located.
• To remove the maintenance level from all available components in a nondefault location, use the
following command:

rpm --oldpackage --prefix installationPath -Uvh pathToInstallationFiles/MQSeries*

where installationPath specifies the path where IBM MQ is installed and pathToInstallationFiles
specifies the path where the earlier level IBM MQ rpm installation files are located.
6. Use the dspmqver command to verify that the level is as expected:

dspmqver

Removing maintenance on Linux using yum

From IBM MQ 9.4.0, you can use the yum command to remove maintenance from an IBM MQ installation
on Linux Red Hat systems.

Before you begin

When you use yum the IBM MQ installation that includes the maintenance level is replaced with an
installation at an earlier level of IBM MQ. Therefore, you must decide which level of IBM MQ you want to
revert to. Then you must ensure that the installation files for the earlier level of IBM MQ are available on
the system.

About this task

You can use yum only to roll back the fix pack level of your installation. You cannot use the command to
roll back the version, release, or modification level of your IBM MQ installation. To roll back the version,
release, or modification level of your installation, you must uninstall the higher level and then install the
earlier level that you require. However, any queue managers that are running at a higher version or release
of IBM MQ cannot then be started on the earlier version or release. For more information, see “Queue
manager migration” on page 343.

Procedure
1. Complete the following tasks:
a) Stop all your IBM MQ applications.
If you use the Managed File Transfer (MFT) component, ensure that any file transfers that MFT
agents are engaged in are completed. The SYSTEM.FTE.STATE queues must contain no messages.
b) Stopped the mqweb server by using the endmqweb command.
c) Stopped your listeners by using the endmqlsr command.
d) Stopped all your queue managers by using the endmqm command.
e) Backed up your data.
For more information, see Backing up and restoring queue manager data.
2. Log in as root, or with sufficient authority to run the following commands.

308 Installing and migrating IBM MQ

 You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
3. Set your current directory to the location of the earlier level installation files. The location might be a
network location, or a local file system directory.
4. Optional: If there is more than one installation on the system, or if you want to remove maintenance
from an IBM MQ installation in a nondefault location, create a unique set of packages:
a) Run the crtmqpkg to create a unique set of packages:

./crtmqpkg suffix

where suffix specifies a name of your choosing that uniquely identifies the installation packages on
the system. suffix is not the same as an installation name, although the names can be identical.
suffix is limited to 16 characters in the ranges A-Z, a-z, and 0-9.
Note: This command creates a full copy of the installation packages in a temporary directory. By
default, the temporary directory is at /var/tmp. Ensure that the system has enough available
space before you run this command. To use a different location, you can set the TMPDIR
environment variable before you run the crtmqpkg command. For example:

$ TMPDIR=/test ./crtmqpkg suffix installationPath

b) Set your current directory to the location that is specified when the crtmqpkg command operation
completes successfully.
5. Clear the repository cache by entering the following command:

yum clean all

6. Remove the IBM MQ maintenance level:

• To remove the maintenance level from all installed components in the default location, use the
following command:

yum -y downgrade pathToInstallationFiles/MQSeries*

where pathToInstallationFiles specifies the path where the earlier level IBM MQ installation files are
located.
• To remove the maintenance level from all installed components in a nondefault location, use the
following command:

yum -y downgrade pathToInstallationFiles/MQSeries*suffix*

where pathToInstallationFiles specifies the path where the earlier level IBM MQ rpm installation
files are located, and suffix specifies the suffix that was chosen when you ran the crtmqpkg
command.
7. Use the dspmqver command to verify that the level is as expected:

dspmqver

Removing maintenance on Linux Ubuntu using dpkg

From IBM MQ 9.4.0, you can use the dpkg command to remove maintenance from an IBM MQ installation
on Linux Ubuntu systems.

Before you begin

When you use dpkg to remove fix pack maintenance, the IBM MQ installation that includes the
maintenance level is replaced with an installation at an earlier level of IBM MQ. Therefore, you must
decide which level of IBM MQ you want to revert to. Then you must ensure that the installation files for
the earlier level of IBM MQ are available on the system.

Installing and migrating 309

 About this task
You can use dpkg only to roll back the fix pack level of your installation. You cannot use the command to
roll back the version, release, or modification level of your IBM MQ installation. To roll back the version,
release, or modification level of your installation, you must uninstall the higher level and then install the
earlier level that you require. However, any queue managers that are running at a higher version or release
of IBM MQ cannot then be started on the earlier version or release. For more information, see “Queue
manager migration” on page 343.

Procedure
1. Complete the following tasks:
a) Stop all your IBM MQ applications.
If you use the Managed File Transfer (MFT) component, ensure that any file transfers that MFT
agents are engaged in are completed. The SYSTEM.FTE.STATE queues must contain no messages.
b) Stopped the mqweb server by using the endmqweb command.
c) Stopped your listeners by using the endmqlsr command.
d) Stopped all your queue managers by using the endmqm command.
e) Backed up your data.
For more information, see Backing up and restoring queue manager data.
2. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
3. Set your current directory to the location of the earlier level installation files. The location might be a
network location, or a local file system directory.
4. Remove maintenance from each IBM MQ package by using the following command for each package:

dpkg -i pathToInstallationFiles/packageName

where pathToInstallationFiles specifies the path where the earlier level IBM MQ installation files are
located, and packageName specifies the name of the package to remove maintenance from.
Important: You cannot specify multiple package files in the same command because of inter-package
dependencies. Change the packages individually in the order shown. If you use apt to remove
maintenance, the inter-package dependencies are handled for you. For more information, see
“Removing maintenance on Linux Ubuntu using apt” on page 311.
• ibmmq-runtime
• ibmmq-jre
• ibmmq-java
• ibmmq-gskit
• ibmmq-server
• ibmmq-web
• ibmmq-ftbase
• ibmmq-ftagent
• ibmmq-ftservice
• ibmmq-ftlogger
• ibmmq-fttools
• ibmmq-amqp
• ibmmq-ams

310 Installing and migrating IBM MQ

 • ibmmq-xrservice
• ibmmq-explorer
• ibmmq-client
• ibmmq-man
• ibmmq-msg_language
• ibmmq-samples
• ibmmq-sdk
5. Use the dspmqver command to verify that the level is as expected:

dspmqver

Removing maintenance on Linux Ubuntu using apt

From IBM MQ 9.4.0, you can use the apt command to remove maintenance from an IBM MQ installation
on Linux Ubuntu systems.

Before you begin

When you use apt the IBM MQ installation that includes the maintenance level is replaced with an
installation at an earlier level of IBM MQ. Therefore, you must decide which level of IBM MQ you want to
revert to. Then you must ensure that the installation files for the earlier level of IBM MQ are available on
the system.

About this task

You can use apt only to roll back the fix pack level of your installation. You cannot use the command to
roll back the version, release, or modification level of your IBM MQ installation. To roll back the version,
release, or modification level of your installation, you must uninstall the higher level and then install the
earlier level that you require. However, any queue managers that are running at a higher version or release
of IBM MQ cannot then be started on the earlier version or release. For more information, see “Queue
manager migration” on page 343.

Procedure
1. Complete the following tasks:
a) Stop all your IBM MQ applications.
If you use the Managed File Transfer (MFT) component, ensure that any file transfers that MFT
agents are engaged in are completed. The SYSTEM.FTE.STATE queues must contain no messages.
b) Stopped the mqweb server by using the endmqweb command.
c) Stopped your listeners by using the endmqlsr command.
d) Stopped all your queue managers by using the endmqm command.
e) Backed up your data.
For more information, see Backing up and restoring queue manager data.
2. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
3. Set your current directory to the location of the earlier level installation files. The location might be a
network location, or a local file system directory.
4. Open the IBM_MQ.list file from the /etc/apt/sources.list.d directory.
5. Add the following line to the end of the IBM_MQ.list file:

Installing and migrating 311

 deb [trusted=yes] file:installationFileLocation ./

where installationFileLocation is the directory where the earlier level IBM MQ installation files are
located.
6. Refresh the repository index by using the following command:

apt-get update

7. Remove the IBM MQ maintenance level by using the following command:

apt-get -y --allow-downgrades install "ibmmq-*"=version

where version specifies the version of IBM MQ that matches the earlier level IBM MQ installation files
that are in the current directory.
8. Use the dspmqver command to verify that the level is as expected:

dspmqver

Applying and removing maintenance on Windows

Maintenance tasks associated with IBM MQ on Windows are grouped in this section.

Procedure
• To apply maintenance level updates, see “Applying maintenance level updates on Windows” on page
312.
• To remove updates and revert to the previous maintenance level, see “Removing maintenance level
updates on Windows” on page 318.
• For information on how to use multiple installations of IBM MQ on the same server to control the
release of maintenance fixes, see “Staging maintenance level updates on Windows” on page 313.
• For information on how to use use multi-instance queue managers to reduce the outage caused by
applying maintenance updates, see “Applying maintenance level updates to multi-instance queue
managers on Windows” on page 316.
Related tasks
“Applying maintenance to IBM MQ” on page 278
Maintenance is the application of a reversible fix. Any changes to queue manager data are compatible
with the previous code level.

Applying maintenance level updates on Windows

From IBM MQ 9.4.0, you apply maintenance for server and client installations by upgrading IBM MQ.

About this task

Note: From 1Q 2023, for Multiplatforms, there are two types of maintenance:
• Fix packs, which contain roll-ups of all defects fixed since the previous fix pack delivery (or GA).
Fix packs are produced exclusively for Long Term Support (LTS) releases during their normal support
lifecycle.
• Cumulative security updates (CSUs), which are smaller updates and contain security patches released
since the previous maintenance (GA). CSUs are produced for LTS releases (including releases in
extended support), and also for the latest IBM MQ Continuous Delivery (CD) release, as required to
deliver relevant security patches.
For maintenance releases in or after 1Q 2023, the fourth digit in the VRMF represents either a fix pack
number or a CSU number. Both types of maintenance are mutually cumulative (that is, they contain
everything included in older CSUs and fix packs), and both are installed using the same mechanisms for

312 Installing and migrating IBM MQ

applying maintenance. Both types of maintenance update the F-digit of the VRMF to a higher number than
any previous maintenance: fix packs use "F" values divisible by 5, CSUs use "F" values not divisible by 5.
For maintenance releases before 1Q 2023, the fourth digit in the VRMF always represents the fix pack
level. For example, the first fix pack of the IBM MQ 9.3.0 LTS release is numbered 9.3.0.1.
For more information, see Changes to IBM MQ's maintenance delivery model.

Procedure
• To upgrade a server installation by using the launchpad, follow the steps in “Upgrading an IBM MQ
server installation using the Launchpad” on page 332.
• To upgrade a server installation by using msiexec, follow the steps in “Upgrading an IBM MQ server
installation using msiexec” on page 333.
• To upgrade a client installation by using the GUI installer, follow the steps in “Upgrading an IBM MQ
client installation using the GUI installer” on page 334.
• To upgrade a client installation by using msiexec, follow the steps in “Upgrading an IBM MQ client
installation using msiexec” on page 335.

Staging maintenance level updates on Windows

On Windows systems, you can use multiple installations of IBM MQ on the same server to control the
release of maintenance level updates.

Before you begin

The steps in this task are based on an example scenario in which it is assumed that you have two copies
of IBM MQ named Inst_1 and Inst_2, and a number of applications and two queue managers, QM1 and
QM2, running on a server. To set up your configuration for this scenario, complete the following steps:
1. Install two copies of IBM MQ. In this example, they are named Inst_1 and Inst_2.
2. Make Inst_1 primary by running setmqinst.
3. Associate all the queue managers on the server with Inst_1 by running setmqm.
4. Start all the queue managers on the server.
5. Show and connect all direct connections with the queue managers associated with Inst_1 in IBM MQ
Explorer.
6. Set up remote connections to all the queue managers in each instance of IBM MQ Explorer.
Note: From 1Q 2023, for Multiplatforms, there are two types of maintenance:
• Fix packs, which contain roll-ups of all defects fixed since the previous fix pack delivery (or GA).
Fix packs are produced exclusively for Long Term Support (LTS) releases during their normal support
lifecycle.
• Cumulative security updates (CSUs), which are smaller updates and contain security patches released
since the previous maintenance (GA). CSUs are produced for LTS releases (including releases in
extended support), and also for the latest IBM MQ Continuous Delivery (CD) release, as required to
deliver relevant security patches.
For maintenance releases in or after 1Q 2023, the fourth digit in the VRMF represents either a fix pack
number or a CSU number. Both types of maintenance are mutually cumulative (that is, they contain
everything included in older CSUs and fix packs), and both are installed using the same mechanisms for
applying maintenance. Both types of maintenance update the F-digit of the VRMF to a higher number than
any previous maintenance: fix packs use "F" values divisible by 5, CSUs use "F" values not divisible by 5.
For maintenance releases before 1Q 2023, the fourth digit in the VRMF always represents the fix pack
level. For example, the first fix pack of the IBM MQ 9.3.0 LTS release is numbered 9.3.0.1.
For more information, see Changes to IBM MQ's maintenance delivery model.

Installing and migrating 313

 About this task
You can install multiple copies of IBM MQ on a server to stage the release of IBM MQ maintenance level
updates. For example, as in the scenario that is described in the task steps, by using two installations
to roll out maintenance level updates, you maintain two maintenance levels on a server, with the aim of
getting all queue managers and applications to the production maintenance level before replacing the
previous level of maintenance with the next level.
Which installation an application uses is driven by the queue manager that an application connects to.
The setmqm command associates a queue manager with an installation. You can associate a queue
manager with a different installation as long as the installation is at the same or higher command level.
In this scenario, all the installations are at the same command level. You can associate or reassociate a
queue manager with either of the installations running any of the fix packs or cumulative security updates
(CSUs).
In this scenario, an application links to the primary installation. When it connects to a queue manager,
IBM MQ switches the linkage to the installation associated with the queue manager; see “Multi-
installation queue manager coexistence on AIX, Linux, and Windows” on page 357.
For applications built with the link options described in the product documentation, the simplest way to
configure the link library search path for IBM MQ applications is to make an installation primary. Only if it
is important to pick up a fix in the IBM MQ link library itself, must you review the search path. Either you
must make the installation with the IBM MQ link library fix primary, or make a local adjustment for the
application, perhaps by running the setmqenv command. See “Migrating IBM MQ library loading to a later
version on Windows” on page 396.
Running commands is a different matter. Commands are always run from the primary installation, or the
installation you have selected by running the setmqenv command. If you run a command from the wrong
installation, the command fails. For example, if QM1 is associated with Inst_1, running the command
Inst_2_Installation_path/bin/strmqm QM1 fails.
If you are using IBM MQ Explorer and you have two installations, you also have two IBM MQ Explorer
instances. One linked to one installation, and one to the other. Each IBM MQ Explorer shows locally
connected queue managers that are associated with the same installation as the instance of IBM MQ
Explorer. To monitor all the queue managers on a server, set up remote connections to the queue
managers associated with the other installations.

Procedure
Apply the first maintenance level update to Inst_2.
1. Download the first fix pack or cumulative security update (CSU) when it is released.
For more information, see “Where to find downloadable installation images” on page 9.
2. Upgrade IBM MQ to apply the fix pack or cumulative security update (CSU) that you downloaded to
Inst_2.
For more information, see “Upgrading an IBM MQ installation on Windows” on page 332.
3. Verify Inst_2.
4. Transfer the queue managers to Inst_2 one at a time.
a) Stop QM1 and the applications connected to it.
The endmqm command informs an application that the queue manager it is connected to is
stopping; see Stopping a queue manager.
Note: “Applying maintenance level updates to multi-instance queue managers on Windows”
on page 316 describes how to apply maintenance to a multi-instance queue manager. A multi-
instance queue manager can continue to run on one server, while maintenance is applied to
another server.
b) Set up the local environment to the installation Inst_2 by using the setmqenv command

"Inst_2_INSTALLATION_PATH\bin\setmqenv" -s

314 Installing and migrating IBM MQ

 The -s option sets up the environment for the installation that runs the setmqenv command.
c) Associate the queue manager with Inst_2 by using the setmqm command:

setmqm -m QM1 -n Inst_2

d) Start QM1 by using the strmqm command:

strmqm QM1

e) Repeat substeps c and d for QM2.

f) Set up IBM MQ Explorer for Inst_2.
i) Start the Inst_2 instance of IBM MQ Explorer
Tip: On Windows, hover over the IBM MQ icon in the system tray. The hover help shows the
installation name associated with the IBM MQ Explorer instance.
ii) Click IBM MQ > Queue Managers > Show/Hide Queue Managers... >
iii) Click each directly connected queue manager listed in the Hidden Queue Managers list >
Show.
iv) Click Close.
5. Set Inst_2 primary by using the setmqinst command:

"Inst_2_INSTALLATION_PATH\bin\setmqinst" -i -n Inst_2

Apply the second maintenance level update to Inst_1.

6. Download the next fix pack or cumulative security update (CSU), for the version of your product when
it is released.
For more information, see “Where to find downloadable installation images” on page 9.
7. Upgrade IBM MQ to apply the fix pack or cumulative security update (CSU) that you downloaded to
Inst_1.
For more information, see “Upgrading an IBM MQ installation on Windows” on page 332.
8. Verify Inst_1.
9. Transfer queue managers to Inst_1 one at a time.
a) Follow the procedure in step “4” on page 314
Replacing Inst_2 by Inst_1 in the instructions.
10. Set Inst_1 primary by using the setmqinst command:

"Inst_1_INSTALLATION_PATH\bin\setmqinst" -i -n Inst_1

For subsequent maintenance fixes, alternate between Inst_2 and Inst_1.

11. Alternate between repeating steps “1” on page 314 to “5” on page 315 for Inst_2 and steps “6” on
page 315 to “10” on page 315 for Inst_1.
Related concepts
“Queue manager coexistence” on page 355
Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations.
“Multi-installation queue manager coexistence on AIX, Linux, and Windows” on page 357
You can install multiple copies of IBM MQ for AIX, Linux, and Windows on the same server. These IBM MQ
copies can be at the same or different version levels. This is called a multi-installation. Multi-installation is
particularly useful when you upgrade from one IBM MQ version to a later version, because it allows you to
run the earlier version alongside the later version.
Related tasks
“Installing IBM MQ server on Windows” on page 176

Installing and migrating 315

 On Windows, IBM MQ is installed by using the Microsoft Installer (MSI). You can either use the
Installation Launchpad to invoke MSI or alternatively, you can invoke MSI directly.
Associating a queue manager with an installation
Changing the primary installation
Related reference
setmqenv
setmqinst
setmqm

Applying maintenance level updates to multi-instance queue managers on Windows

On Windows platforms, you can use multi-instance queue managers to reduce the outage caused by
applying maintenance updates.

Before you begin

Before starting this task, see that the maintenance is applied to the IBM MQ installation on a server and
not to individual queue managers. Before you apply maintenance, you must stop all the queue managers,
and any IBM MQ service, on a server.
If you want a queue manager to keep running while maintenance is applied, you must configure it as
a multi-instance queue manager, and have a standby instance running on another server. If the queue
manager that you want to keep running is an existing single instance queue manager, you must convert it
to a multi-instance queue manager. For prerequisites and guidance how to create a multi-instance queue
manager, see Multi-instance queue managers.
If you are running multi-instance queue managers, you then can apply a maintenance update to a running
queue manager by switching the active instance to a different server.
Typically, active and standby installations are maintained at the same maintenance level. Consult the
maintenance instructions for each update. Consult the instructions to see if it is possible to run the active
and standby instances at different maintenance levels. Check whether fail over from higher to lower, or
only lower to higher maintenance level is possible.
The instructions for applying a maintenance update might require you to stop a multi-instance queue
manager completely.
If you have a primary server for running active queue manager instances, and a secondary server that
runs standby instances, you have a choice of updating the primary or secondary server first. If you update
the secondary server first, you must switch back to the primary server when both servers have been
updated.
If you have active and standby instances on several servers, you must plan in what order you update the
servers to minimize the disruption caused by ending the active instances on each server you update.

About this task

Follow these steps to apply maintenance to a multi-instance queue manager on Windows.

Procedure
1. Stop all applications using the IBM MQ installation.
If you use the Managed File Transfer (MFT) component, ensure that any MFT agents have finished all of
the file transfers that they were engaged in. There should be no incomplete transfers associated with
the agents, and their SYSTEM.FTE.STATE queues should contain no messages.
2. Find out the current state of the queue managers and their associated listeners associated with the
IBM MQ installation.
a) From the installation that you are updating, use the dspmq command to list the state of the queue
managers:

316 Installing and migrating IBM MQ

 • To display the installation name and status of queue managers associated with all installations of
IBM MQ, run the following command:

dspmq -o installation -o status

• To display the status of active queue managers associated with the installation from which you
are running the command, run the following command:

dspmq -a

b) Use the MQSC command DISPLAY LSSTATUS to list the status of listeners associated with a
queue manager, as shown in the following example:

echo "DISPLAY LSSTATUS(*) STATUS" | runmqsc QmgrName

3. Use the endmqm command to stop each running queue manager associated with this installation.
• If the queue manager is running as standby, run the endmqm command to end the standby as
shown in the following example:

endmqm -x QMgrName

• If the queue manager is running as the active instance, run the endmqm command to end the active
instance and transfer control to the standby instance as shown in the following example:

endmqm -shutdown_option -s QMgrName

where -shutdown_option is an optional parameter specifying the type of shutdown. For more
information about optional parameters for the endmqm command, see endmqm.
If there is no standby instance running, and the command fails, start a standby instance on a
different server.
• If a queue manager is running as a single instance queue manager, stop the queue manager. In
the case of a single queue manager you have no alternative but to stop the queue manager before
applying the maintenance update. For more information about how to stop a queue manager, see
Stopping a queue manager.
Stop any listeners associated with the queue managers by using the endmqlsr command as shown in
the following example:

endmqlsr -m QMgrName

After you complete this step, no queue manager instances are left running on the server that you
intend to update.
4. Upgrade IBM MQ to apply maintenance to the IBM MQ server.
Follow the instructions in “Upgrading an IBM MQ installation on Windows” on page 332.
5. When you have completed the maintenance update, use the strmqm command to restart all the queue
managers on the IBM MQ server, permitting standby instances, as shown in the following example:

strmqm -x QmgrName

6. Repeat the procedure on the standby server, to update its maintenance level.
7. If necessary, switch the active instances back to the primary servers:
a) Stop the instances by using the endmqm command as shown in the following example:

endmqm -shutdown_option -s QMgrName

b) Restart the instances by using the strmqm command as shown in the following example:

Installing and migrating 317

 strmqm -x QmgrName

Related tasks
Stopping a queue manager
Related reference
dspmq (display queue managers)
DISPLAYLSSTATUS
endmqm (end queue manager)
endmqlsr (end listener)
strmqm (start queue manager)

Removing maintenance level updates on Windows

From IBM MQ 9.4.0, you remove maintenance for server and client installations by uninstalling IBM MQ
and then reinstalling an earlier level.

About this task

Considerations for uninstalling and reinstalling IBM MQ at an earlier level:
• When you uninstall IBM MQ, your IBM MQ data is not removed. Therefore, when you reinstall the earlier
level, your queue managers are preserved.
• Any queue managers that are running at a higher version or release of IBM MQ cannot be started on an
earlier version or release. Therefore, when removing maintenance, ensure that you reinstall a version of
IBM MQ at the same version and release, but a different maintenance level. For more information, see
“Queue manager migration” on page 343.

Procedure
• To uninstall IBM MQ on Windows, see “Uninstalling IBM MQ on Windows” on page 230.
• To install an IBM MQ server on Windows, see “Installing IBM MQ server on Windows” on page 176.
• To install an IBM MQ client on Windows, see “Installing an IBM MQ client on Windows” on page 203.
Related tasks
“Applying maintenance level updates on Windows” on page 312
From IBM MQ 9.4.0, you apply maintenance for server and client installations by upgrading IBM MQ.
“Applying maintenance level updates to multi-instance queue managers on Windows” on page 316
On Windows platforms, you can use multi-instance queue managers to reduce the outage caused by
applying maintenance updates.

Applying WebSphere Liberty interim fixes to the mqweb server

You can apply WebSphere Liberty interim fixes to the WebSphere Liberty that runs the mqweb server.

About this task

This task applies to both IBM MQ Long Term Support and IBM MQ Continuous Delivery.
Important: If an interim fix is not available for the WebSphere Liberty version that is installed in the IBM
MQ installation, then you should contact IBM Support. You should NOT look to change the WebSphere
Liberty version that is used by the IBM MQ Console and REST API and should only look to apply a
WebSphere Liberty interim fix.
Note: This information does NOT apply to IBM MQ Appliance.

Procedure
1. Check the Liberty version.

318 Installing and migrating IBM MQ

 To do this, run the following command:

<MQ_INSTALLATION_PATH>/web/bin/productInfo version --ifixes

2. Use the security link or the information on the page for the Liberty APAR to locate the correct archive
interim fix (iFix) for the version that is installed.
Liberty archive interim fixes come in a JAR format, and have an associated readme file that you can
refer to for installation instructions. Download both files into a temporary directory.
3. After the interim fix has been downloaded, start a console and navigate to the directory that contains
the interim fix JAR file.
4. Stop the mqweb server by using the command:

<MQ_INSTALLATION_PATH>/bin/endmqweb

5.
As an administrative user, run the following command to set the umask for the user to 022:

umask 022

6. As an administrative user, run the following command to install the interim fix:

java -jar <iFix JAR> -installLocation <MQ_INSTALLATION_PATH>/web

7. Run the following command and check the output to confirm that the interim fix has been installed
correctly:

<MQ_INSTALLATION_PATH>/web/bin/productInfo version --ifixes

8. Restart the mqweb server by using the command:

<MQ_INSTALLATION_PATH>/bin/strmqweb

Results
When the mqweb server restarts, the interim fix should be loaded.

Example
The following example shows how to apply a WebSphere Liberty interim fix for APAR PH31442 to an IBM
MQ 9.1.0.8 installation on Linux.
1. Run the following command to check the version of Liberty installed with IBM MQ 9.1.0.8:

/opt/mqm/web/bin/productInfo version --ifixes

This command generates the following output, which indicates that the Liberty version is 21.0.0.3:
Product name: WebSphere Application Server
Product version: 21.0.0.3
Product edition: BASE
2. Go to the web page for APAR PH31442.
3. In the Download Package section of the web page, click the download link for the archive 21003-
wlp-archive-IFPH34122.
4. After you have been redirected to Fix Central, download the following files into a temporary directory:
• 21003-wlp-archive-IFPH34122-ReadMe.txt
• 21003-wlp-archive-ifph34122.jar
5. Start a console, and navigate to the temporary directory.
6. Stop the mqweb server by using the command:

/opt/mqm/bin/endmqweb

Installing and migrating 319

 7. Run the following command as a root user to set the umask to 022:

umask 022

8. Next, as the same root user, run the following command to install the interim fix:

java -jar 21003-wlp-archive-ifph34122.jar --installLocation /opt/mqm/web

All being well, you should see the following output:

Applying fix to Liberty install directory at /opt/mqm/web now.
lib/com.ibm.ws.ui.tool.javaBatch_1.0.50.cl210320210319-1444.jar
lib/com.ibm.ws.ui.tool.explore_1.0.50.cl210320210319-1444.jar
lib/com.ibm.ws.ui_1.0.50.cl210320210319-1444.jar
Fix has been applied successfully.
Successfully extracted all product files.
9. Run the following command to check that the interim fix has been installed correctly:

/opt/mqm/web/bin/productInfo version --ifixes

You should see the following output:

Product name: WebSphere Application Server
Product version: 21.0.0.3
Product edition: BASE

PH34122 in the iFix(es): [21003-wlp-archive-IFPH34122]

10. Restart the mqweb server by using the command:

/opt/mqm/bin/strmqweb

Related tasks
Contacting IBM Support
Related reference
endmqweb (end mqweb server)
strmqweb (start mqweb server)

Upgrading IBM MQ
Upgrading is the process of taking an existing IBM MQ installation and upgrading to a new level of code.

Before you begin

This task assumes that you understand the difference between Long Term Support and Continuous
Delivery releases, and the maintenance delivery model that applies in each case. For more information,
see IBM MQ Release Types and versioning.

About this task

When you upgrade from one release to another, or apply maintenance, including fix packs, cumulative
security updates (CSUs), or interim fixes, the impact of the change depends on the extent of the change in
the VRMF level:
• The term upgrade applies to increasing the version V, release R, or modification M level.
• The term fix applies to increasing the fix F level.
At each change of the V, R, or M level, the command level on the queue manager changes. On a change to
the F level, the command level does not change.

On Multiplatforms, after an upgrade has been applied, the only way to back out a VRM
change is by taking one of the following actions:
• Uninstalling the product code and reinstalling the code.

320 Installing and migrating IBM MQ

• Installing the old level of code alongside the existing code and using the setmqm command to associate
the queue manager with the other installation.
The general rule is that, if you have carried out an installation that causes the command level of the new
installation to be updated, and started the queue manager, you cannot back out the changes.

Procedure
1. Open Downloading IBM MQ 9.4.
2. To access the latest CD downloads, click the CD tab.
From this tab you can download the latest CD level and the latest CD CSU. If you are not running the
latest CD level, you must download and install it before you can apply the latest CSU.
The format of the download is platform-specific. For Multiplatforms you download one or more parts
from Passport Advantage or Fix Central. For IBM MQ Appliance you download firmware images from
Fix Central.
a) Find the download section for your platform. For example Downloading the CD release for
Multiplatforms.
b) To get the latest CD level, click Download the IBM MQ 9.4.x base install image. For example, for
Multiplatforms click Download the IBM MQ 9.4.x base install image from Passport Advantage.
c) To get the latest CSU, click Download the IBM MQ 9.4.x.x CSU from Fix Central.
3. To access the latest LTS downloads, click the LTS tab.
From this tab you can download the latest LTS base install level, and either an LTS fix pack or an LTS
CSU, whichever is the latest.
The format of the download is platform-specific. For Multiplatforms you download one or more parts
from Passport Advantage or Fix Central. For the Appliance you download firmware images from Fix
Central.
a) Find the download section for your platform. For example Downloading the LTS release for
Multiplatforms.
b) To get the latest LTS base install level, click Download the IBM MQ 9.4.0 LTS base install image.
For example, for Multiplatforms click Download the latest IBM MQ 9.4.0 LTS base install image
from Passport Advantage.
c) To get the latest fix pack or CSU, click Download the IBM MQ 9.4.0.xx fix pack/CSU.
Fix packs and CSUs are cumulative. Therefore you are only offered the latest fix, which might be
either a fix pack or a CSU.
Related tasks
“Applying maintenance to IBM MQ” on page 278
Maintenance is the application of a reversible fix. Any changes to queue manager data are compatible
with the previous code level.

Upgrading an IBM MQ installation on Linux

You can upgrade an IBM MQ installation on Linux systems without uninstalling the earlier version.

Before you begin

The version that you are upgrading from must be IBM MQ 9.2.0, or later.

If your current version is at IBM MQ 9.4.0 or higher, you can upgrade your installation with
fix packs installed. That is, the fix pack number in the version.release.modification.fixpack (V.R.M.F)
release identifier does not need to be 0.

Installing and migrating 321

 If your current version is earlier than IBM MQ 9.4.0, you can upgrade only if no fix packs are installed.
That is, the fix pack number in the version.release.modification.fixpack (V.R.M.F) release identifier must
be 0.

About this task

You can use rpm, a Debian installer on Linux Ubuntu, or the yum installer on Linux Red Hat.
Before you begin, ensure that you have backed up your data.
Note:

1. The IBM MQ Bridge to Salesforce is deprecated across all releases from November 22
2022 (see US Announcement letter 222-341).

2. The IBM MQ Bridge to Salesforce is removed from the

product at IBM MQ 9.4.0. Salesforce connectivity can be achieved with IBM App Connect Enterprise.
Salesforce Input and Salesforce Request nodes can be used to interact with Salesforce applications.
For more information, see Using Salesforce with IBM App Connect Enterprise.
On Linux for x86-64 only, if you are migrating from an installation where the IBM MQ Bridge to
Salesforce is present, you must remove it before you upgrade to IBM MQ 9.4.0 or later.

3. For Continuous Delivery, the IBM MQ Bridge to blockchain is removed from the product
at IBM MQ 9.3.2.

For Long Term Support, IBM MQ Bridge to blockchain is removed at IBM MQ 9.3.0 Fix
Pack 15.
Blockchain connectivity can be achieved with IBM App Connect or through App Connect capabilities
available with IBM Cloud Pak for Integration.
On Linux for x86-64 only, if you are migrating from an installation where the IBM MQ Bridge to
blockchain is present, you must remove it before you upgrade to IBM MQ 9.4.0 or later.
4. From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ install package. It remains
available as a separate download. For more information, see Installing and uninstalling IBM MQ
Explorer as a stand-alone application on Linux and Windows.
On Linux for x86-64 only, if you are migrating on an installation where the IBM MQ Explorer is present
as part of the IBM MQ installation, you must remove it before you upgrade to IBM MQ 9.3.0 or later.

Procedure
• To upgrade a server installation using rpm, see “Upgrading an IBM MQ installation on Linux using the
rpm command” on page 322
• To upgrade a server installation on Linux Red Hat using yum, see “Upgrading an IBM MQ installation on
Linux Red Hat using yum” on page 325
• To upgrade a server installation on Linux Ubuntu using a Debian installer, see “Upgrading an IBM MQ
installation on Linux Ubuntu using apt” on page 330

Upgrading an IBM MQ installation on Linux using the rpm command

You can use rpm to upgrade an IBM MQ installation on Linux systems.

Before you begin

The version that you are upgrading from must be IBM MQ 9.2.0, or later.

If your current version is at IBM MQ 9.4.0 or higher, you can upgrade your installation with
fix packs installed. That is, the fix pack number in the version.release.modification.fixpack (V.R.M.F)
release identifier does not need to be 0.

322 Installing and migrating IBM MQ

If your current version is earlier than IBM MQ 9.4.0, you can upgrade only if no fix packs are installed.
That is, the fix pack number in the version.release.modification.fixpack (V.R.M.F) release identifier must
be 0.
Important:

• The IBM MQ Bridge to Salesforce is deprecated across all releases from November 22
2022 (see US Announcement letter 222-341).

• The IBM MQ Bridge to Salesforce is removed from the product

at IBM MQ 9.4.0. Salesforce connectivity can be achieved with IBM App Connect Enterprise. Salesforce
Input and Salesforce Request nodes can be used to interact with Salesforce applications. For more
information, see Using Salesforce with IBM App Connect Enterprise.
On Linux for x86-64 only, if you are migrating from an installation where the IBM MQ Bridge to
Salesforce is present, you must remove it before you upgrade to IBM MQ 9.4.0 or later.

• For Continuous Delivery, the IBM MQ Bridge to blockchain is removed from the product at
IBM MQ 9.3.2.

For Long Term Support, IBM MQ Bridge to blockchain is removed at IBM MQ 9.3.0 Fix Pack
15.
Blockchain connectivity can be achieved with IBM App Connect or through App Connect capabilities
available with IBM Cloud Pak for Integration.
On Linux for x86-64 only, if you are migrating from an installation where the IBM MQ Bridge to
blockchain is present, you must remove it before you upgrade to IBM MQ 9.4.0 or later.
• From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ install package. On Linux for
x86-64 only, if you are migrating on an installation where the IBM MQ Explorer is present as part of the
IBM MQ installation, you must remove it before you upgrade to IBM MQ 9.3.0 or later.
For more information about modifying an IBM MQ installation using rpm, see “Uninstalling or modifying
IBM MQ on Linux using rpm” on page 150.

Procedure
1. Complete the following tasks:
a) Stop all your IBM MQ applications.
If you use the Managed File Transfer (MFT) component, ensure that any file transfers that MFT
agents are engaged in are completed. The SYSTEM.FTE.STATE queues must contain no messages.
b) Stopped the mqweb server by using the endmqweb command.
c) Stopped your listeners by using the endmqlsr command.
d) Stopped all your queue managers by using the endmqm command.
e) Backed up your data.
For more information, see Backing up and restoring queue manager data.
2. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
3. Optional: If your installation media is a downloadable installation image, obtained from Passport
Advantage, you must decompress the tar.gz file and extract the installation files from the file:
a) Decompress the file by using the following command:

gunzip partName.tar.gz

where partName is the name of the installation image file.

Installing and migrating 323

 b) Extract the installation files from the file by using the following command:

tar -xvf partName.tar

where partName is the name of the installation image file.

Important: You must use GNU tar (also known as gtar) to unpack any tar images.
4. Set your current directory to the location of the installation files. The location might be a network
location, or a local file system directory.
5. Optional: If this is not the only installation on the system, or if you want to upgrade an IBM MQ
installation in a non default location, run the crtmqpkg to create a unique set of packages to upgrade:

./crtmqpkg suffix

where suffix specifies a name of your choosing that uniquely identifies the installation packages on the
system. suffix is not the same as an installation name, although the names can be identical. suffix is
limited to 16 characters in the ranges A-Z, a-z, and 0-9.
Note: This command creates a full copy of the installation packages in a temporary directory. By
default, the temporary directory is located at /var/tmp. You must ensure that the system has
enough free space before you run this command. To use a different location, you can set the TMPDIR
environment variable before you run the crtmqpkg command. For example:

$ TMPDIR=/test ./crtmqpkg suffix installationPath

6. Set your current directory to the location of the installation packages. If you used the crtmqpkg
command, this directory is the location that is specified when the crtmqpkg command operation
completes successfully.
7. From IBM MQ 9.2.0, you have the option of accepting the license before or after you install the
product. To accept the license before installing, run the mqlicense.sh script. The license agreement
is displayed in a language appropriate to your environment and you are prompted to accept or decline
the terms of the license:
• To display the license agreement in the default manner, which uses an X-window where possible,
use the following command:

./mqlicense.sh

• To display the license agreement as text in the current shell, which can be read by a screen reader,
use the following command:

./mqlicense.sh -text_only

See “Accepting the license on IBM MQ for Linux” on page 106 for more information about license
acceptance.
8. Upgrade IBM MQ:
• To upgrade all available components in the default location, use the following command:

rpm -Uvh MQSeries*

• To upgrade specific components in the default location, use the following command:

rpm -Uvh packageName.rpm

where packageName.rpm is a list of one of more components to upgrade. For a full list of
components, see “IBM MQ rpm components for Linux systems” on page 107.
• To upgrade all available components in a non default location, use the following command:

rpm --prefix installationPath -Uvh MQSeries*

where installationPath specifies the path where IBM MQ is installed.

324 Installing and migrating IBM MQ

 • To upgrade specific components in a non default location, use the following command:

rpm --prefix installationPath -Uvh packageName.rpm

where installationPath specifies the path where IBM MQ is installed, and packageName.rpm is
a list of one of more components to upgrade. For a full list of components, see “IBM MQ rpm
components for Linux systems” on page 107.
9. Use the dspmqver command to verify that the version is as expected:

dspmqver

Related tasks
“Upgrading an IBM MQ installation on Linux Red Hat using yum” on page 325
You can use yum to upgrade an IBM MQ installation on Linux Red Hat systems.
“Upgrading an IBM MQ installation on Linux Ubuntu using apt” on page 330
You can use apt to upgrade an IBM MQ installation on Linux Ubuntu systems.

Upgrading an IBM MQ installation on Linux Red Hat using yum

You can use yum to upgrade an IBM MQ installation on Linux Red Hat systems.

Before you begin

The version that you are upgrading from must be IBM MQ 9.2.0, or later.

If your current version is at IBM MQ 9.4.0 or higher, you can upgrade your installation with
fix packs installed. That is, the fix pack number in the version.release.modification.fixpack (V.R.M.F)
release identifier does not need to be 0.
If your current version is earlier than IBM MQ 9.4.0, you can upgrade only if no fix packs are installed.
That is, the fix pack number in the version.release.modification.fixpack (V.R.M.F) release identifier must
be 0.
Important:

• The IBM MQ Bridge to Salesforce is deprecated across all releases from November 22
2022 (see US Announcement letter 222-341).

• The IBM MQ Bridge to Salesforce is removed from the product

at IBM MQ 9.4.0. Salesforce connectivity can be achieved with IBM App Connect Enterprise. Salesforce
Input and Salesforce Request nodes can be used to interact with Salesforce applications. For more
information, see Using Salesforce with IBM App Connect Enterprise.
On Linux for x86-64 only, if you are migrating from an installation where the IBM MQ Bridge to
Salesforce is present, you must remove it before you upgrade to IBM MQ 9.4.0 or later.

• For Continuous Delivery, the IBM MQ Bridge to blockchain is removed from the product at
IBM MQ 9.3.2.

For Long Term Support, IBM MQ Bridge to blockchain is removed at IBM MQ 9.3.0 Fix Pack
15.
Blockchain connectivity can be achieved with IBM App Connect or through App Connect capabilities
available with IBM Cloud Pak for Integration.
On Linux for x86-64 only, if you are migrating from an installation where the IBM MQ Bridge to
blockchain is present, you must remove it before you upgrade to IBM MQ 9.4.0 or later.
• From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ installation package. On
Linux for x86-64 only, if you are migrating on an installation where the IBM MQ Explorer is present as
part of the IBM MQ installation, you must remove it before you upgrade to IBM MQ 9.3.0 or later.

Installing and migrating 325

 For more information about modifying an IBM MQ installation by using yum, see “Uninstalling or
modifying IBM MQ on Linux Red Hat using yum” on page 152.

Procedure
1. Complete the following tasks:
a) Stop all your IBM MQ applications.
If you use the Managed File Transfer (MFT) component, ensure that any file transfers that MFT
agents are engaged in are completed. The SYSTEM.FTE.STATE queues must contain no messages.
b) Stopped the mqweb server by using the endmqweb command.
c) Stopped your listeners by using the endmqlsr command.
d) Stopped all your queue managers by using the endmqm command.
e) Backed up your data.
For more information, see Backing up and restoring queue manager data.
2. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
3. Optional: If your installation media is a downloadable installation image, obtained from Passport
Advantage, you must decompress the tar.gz file and extract the installation files from the file:
a) Decompress the file by using the following command:

gunzip partName.tar.gz

where partName is the name of the installation image file.

b) Extract the installation files from the file by using the following command:

tar -xvf partName.tar

where partName is the name of the installation image file.

Important: You must use GNU tar (also known as gtar) to unpack any tar images.
4. Set your current directory to the location of the installation packages.
The location might be a network location, or a local file system directory. See Where to find
downloadable installation images.
5. Optional: If this installation is not the only installation on the system, or if you want to upgrade an
IBM MQ installation in a non default location, run the crtmqpkg to create a unique set of packages to
upgrade:

./crtmqpkg suffix installationPath

where:
• suffix specifies a name of your choosing that uniquely identifies the installation packages on the
system. suffix is not the same as an installation name, although the names can be identical. suffix is
limited to 16 characters in the ranges A-Z, a-z, and 0-9.
• installationPath specifies the path where the installation that you want to upgrade is installed.
Note: This command creates a full copy of the installation packages in a temporary directory. By
default, the temporary directory is at /var/tmp. Ensure that the system has enough available space
before you run this command. To use a different location, you can set the TMPDIR environment
variable before you run the crtmqpkg command. For example:

$ TMPDIR=/test ./crtmqpkg suffix installationPath

6. Set your current directory to the location of the installation packages.

326 Installing and migrating IBM MQ

 If you used the crtmqpkg command, this directory is the location that is specified when the
crtmqpkg command operation completes successfully.
7. Update the yum repository file:
a) Open the repository file. The file is in the /etc/yum.repos.d directory, and has a suffix
of .repo. For example, IBM_MQ.repo.
b) Add the following contents to the repository file. Replace installationFilesLocation with the
location of the installation files for the version that you want to upgrade to. Replace v.r.m with
the version, release, and modification number for the version of IBM MQ that you want to upgrade
to:

[IBM-MQ-v.r.m-x86_64]
name=IBM MQ v.r.m x86_64
baseurl=file:///installationFilesLocation
enabled=1
gpgcheck=0

c) Clear the repository cache by using the following command:

yum clean all

d) Check that the IBM MQ repository is available by using the following command:

yum repolist

8. From IBM MQ 9.2.0, you have the option of accepting the license before or after you install
the product. To accept the license before installing, run the mqlicense.sh script. The license
agreement is displayed in a language appropriate to your environment and you are prompted to
accept or decline the terms of the license:
• To display the license agreement in the default manner, which uses an X-window where possible,
use the following command:

./mqlicense.sh

• To display the license agreement as text in the current shell, which can be read by a screen reader,
use the following command:

./mqlicense.sh -text_only

See “Accepting the license on IBM MQ for Linux” on page 106 for more information about license
acceptance.
9. Upgrade IBM MQ:
• To upgrade all installed components, use the following command:

yum -y upgrade MQSeries*

• To upgrade all installed components in a non default location, use the following command:

yum -y upgrade MQSeries*suffix*

where suffix specifies the suffix that was chosen when you ran crtmqpkg in step “5” on page 326.
10. Use the dspmqver command to verify that the version is as expected:

dspmqver

Related tasks
“Upgrading an IBM MQ installation on Linux using the rpm command” on page 322
You can use rpm to upgrade an IBM MQ installation on Linux systems.
“Upgrading an IBM MQ installation on Linux Ubuntu using apt” on page 330

Installing and migrating 327

 You can use apt to upgrade an IBM MQ installation on Linux Ubuntu systems.

Upgrading an IBM MQ installation on Linux Ubuntu using dpkg

You can use dpkg to upgrade an IBM MQ installation on Linux Ubuntu systems.

Before you begin

The version that you are upgrading from must be IBM MQ 9.2.0, or later.

If your current version is at IBM MQ 9.4.0 or higher, you can upgrade your installation with
fix packs installed. That is, the fix pack number in the version.release.modification.fixpack (V.R.M.F)
release identifier does not need to be 0.
If your current version is earlier than IBM MQ 9.4.0, you can upgrade only if no fix packs are installed.
That is, the fix pack number in the version.release.modification.fixpack (V.R.M.F) release identifier must
be 0.
Important:

1. The IBM MQ Bridge to Salesforce is deprecated across all releases from November 22
2022 (see US Announcement letter 222-341).

2. The IBM MQ Bridge to Salesforce is removed from the

product at IBM MQ 9.4.0. Salesforce connectivity can be achieved with IBM App Connect Enterprise.
Salesforce Input and Salesforce Request nodes can be used to interact with Salesforce applications.
For more information, see Using Salesforce with IBM App Connect Enterprise.
On Linux for x86-64 only, if you are migrating from an installation where the IBM MQ Bridge to
Salesforce is present, you must remove it before you upgrade to IBM MQ 9.4.0 or later.

3. For Continuous Delivery, the IBM MQ Bridge to blockchain is removed from the product
at IBM MQ 9.3.2.

For Long Term Support, IBM MQ Bridge to blockchain is removed at IBM MQ 9.3.0 Fix
Pack 15.
Blockchain connectivity can be achieved with IBM App Connect or through App Connect capabilities
available with IBM Cloud Pak for Integration.
On Linux for x86-64 only, if you are migrating from an installation where the IBM MQ Bridge to
blockchain is present, you must remove it before you upgrade to IBM MQ 9.4.0 or later.
4. From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ install package. On Linux
for x86-64 only, if you are migrating on an installation where the IBM MQ Explorer is present as part of
the IBM MQ installation, you must remove it before you upgrade to IBM MQ 9.3.0 or later.
For more information about modifying an IBM MQ installation on Ubuntu, see “Uninstalling or modifying
IBM MQ on Linux Ubuntu using Debian packages” on page 154.

Procedure
1. Complete the following tasks:
a) Stop all your IBM MQ applications.
If you use the Managed File Transfer (MFT) component, ensure that any file transfers that MFT
agents are engaged in are completed. The SYSTEM.FTE.STATE queues must contain no messages.
b) Stopped the mqweb server by using the endmqweb command.
c) Stopped your listeners by using the endmqlsr command.
d) Stopped all your queue managers by using the endmqm command.
e) Backed up your data.

328 Installing and migrating IBM MQ

 For more information, see Backing up and restoring queue manager data.
2. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
3. Optional: If your installation media is a downloadable installation image, obtained from Passport
Advantage, you must decompress the tar.gz file and extract the installation files from the file:
a) Decompress the file by using the following command:

gunzip partName.tar.gz

where partName is the name of the installation image file.

b) Extract the installation files from the file by using the following command:

tar -xvf partName.tar

where partName is the name of the installation image file.

Important: You must use GNU tar (also known as gtar) to unpack any tar images.
4. Set your current directory to the location of the installation files.
5. From IBM MQ 9.2.0, you have the option of accepting the license before or after you install the
product. To accept the license before installing, run the mqlicense.sh script. The license agreement
is displayed in a language appropriate to your environment and you are prompted to accept or decline
the terms of the license:
• To display the license agreement in the default manner, which uses an X-window where possible,
use the following command:

./mqlicense.sh

• To display the license agreement as text in the current shell, which can be read by a screen reader,
use the following command:

./mqlicense.sh -text_only

See “Accepting the license on IBM MQ for Linux” on page 106 for more information about license
acceptance.
6. Upgrade each IBM MQ package by using the following command for each package:

dpkg -i packageName

where packageName specifies the name of the package to upgrade.

Important: Although dpkg permits multiple package files in the same command, this does not work
for IBM MQ because of inter-package dependencies. You must upgrade the packages individually in
the order shown. If you use apt to upgrade, the inter-package dependencies are handled for you. For
more information, see “Upgrading an IBM MQ installation on Linux Ubuntu using apt” on page 330.
• ibmmq-runtime
• ibmmq-jre
• ibmmq-java
• ibmmq-gskit
• ibmmq-server
• ibmmq-web
• ibmmq-ftbase
• ibmmq-ftagent
• ibmmq-ftservice

Installing and migrating 329

 • ibmmq-ftlogger
• ibmmq-fttools
• ibmmq-amqp
• ibmmq-ams
• ibmmq-xrservice
• ibmmq-explorer
• ibmmq-client
• ibmmq-man
• ibmmq-msg_language
• ibmmq-samples
• ibmmq-sdk
7. Use the dspmqver command to verify that the version is as expected:

dspmqver

Upgrading an IBM MQ installation on Linux Ubuntu using apt

You can use apt to upgrade an IBM MQ installation on Linux Ubuntu systems.

Before you begin

The version that you are upgrading from must be IBM MQ 9.2.0, or later.

If your current version is at IBM MQ 9.4.0 or higher, you can upgrade your installation with
fix packs installed. That is, the fix pack number in the version.release.modification.fixpack (V.R.M.F)
release identifier does not need to be 0.
If your current version is earlier than IBM MQ 9.4.0, you can upgrade only if no fix packs are installed.
That is, the fix pack number in the version.release.modification.fixpack (V.R.M.F) release identifier must
be 0.
Important:

• The IBM MQ Bridge to Salesforce is deprecated across all releases from November 22
2022 (see US Announcement letter 222-341).

• The IBM MQ Bridge to Salesforce is removed from the product

at IBM MQ 9.4.0. Salesforce connectivity can be achieved with IBM App Connect Enterprise. Salesforce
Input and Salesforce Request nodes can be used to interact with Salesforce applications. For more
information, see Using Salesforce with IBM App Connect Enterprise.
On Linux for x86-64 only, if you are migrating from an installation where the IBM MQ Bridge to
Salesforce is present, you must remove it before you upgrade to IBM MQ 9.4.0 or later.

• For Continuous Delivery, the IBM MQ Bridge to blockchain is removed from the product at
IBM MQ 9.3.2.

For Long Term Support, IBM MQ Bridge to blockchain is removed at IBM MQ 9.3.0 Fix Pack
15.
Blockchain connectivity can be achieved with IBM App Connect or through App Connect capabilities
available with IBM Cloud Pak for Integration.
On Linux for x86-64 only, if you are migrating from an installation where the IBM MQ Bridge to
blockchain is present, you must remove it before you upgrade to IBM MQ 9.4.0 or later.
• From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ install package. On Linux for
x86-64 only, if you are migrating on an installation where the IBM MQ Explorer is present as part of the
IBM MQ installation, you must remove it before you upgrade to IBM MQ 9.3.0 or later.

330 Installing and migrating IBM MQ

For more information about modifying an IBM MQ installation on Ubuntu, see “Uninstalling or modifying
IBM MQ on Linux Ubuntu using Debian packages” on page 154.

Procedure
1. Complete the following tasks:
a) Stop all your IBM MQ applications.
If you use the Managed File Transfer (MFT) component, ensure that any file transfers that MFT
agents are engaged in are completed. The SYSTEM.FTE.STATE queues must contain no messages.
b) Stopped the mqweb server by using the endmqweb command.
c) Stopped your listeners by using the endmqlsr command.
d) Stopped all your queue managers by using the endmqm command.
e) Backed up your data.
For more information, see Backing up and restoring queue manager data.
2. Log in as root, or with sufficient authority to run the following commands.
You can do this by adding sudo before the commands, or by changing to the root user in the shell
with the su command. For more information, see Exploring the differences between sudo and su
commands in Linux.
3. Optional: If your installation media is a downloadable installation image, obtained from Passport
Advantage, you must decompress the tar.gz file and extract the installation files from the file:
a) Decompress the file by using the following command:

gunzip partName.tar.gz

where partName is the name of the installation image file.

b) Extract the installation files from the file by using the following command:

tar -xvf partName.tar

where partName is the name of the installation image file.

Important: You must use GNU tar (also known as gtar) to unpack any tar images.
4. Set your current directory to the location of the installation files.
5. From IBM MQ 9.2.0, you have the option of accepting the license before or after you install
the product. To accept the license before installing, run the mqlicense.sh script. The license
agreement is displayed in a language appropriate to your environment and you are prompted to
accept or decline the terms of the license:
• To display the license agreement in the default manner, which uses an X-window where possible,
use the following command:

./mqlicense.sh

• To display the license agreement as text in the current shell, which can be read by a screen reader,
use the following command:

./mqlicense.sh -text_only

See “Accepting the license on IBM MQ for Linux” on page 106 for more information about license
acceptance.
6. Open the IBM_MQ.list file from the /etc/apt/sources.list.d directory.
7. Add the following line to the end of the IBM_MQ.list file:

deb [trusted=yes] file:installationFileLocation ./

where installationFileLocation is the directory where the unpacked files are located.

Installing and migrating 331

 8. Refresh the repository index by using the following command:

apt-get update

9. Upgrade IBM MQ by using the following command:

apt-get upgrade "ibmmq-*"

10. Use the dspmqver command to verify that the version is as expected:

dspmqver

Related tasks
“Upgrading an IBM MQ installation on Linux using the rpm command” on page 322
You can use rpm to upgrade an IBM MQ installation on Linux systems.
“Upgrading an IBM MQ installation on Linux Red Hat using yum” on page 325
You can use yum to upgrade an IBM MQ installation on Linux Red Hat systems.

Upgrading an IBM MQ installation on Windows

To upgrade an IBM MQ server installation on Windows, from one version, release, and modification level
to a later one, you can use either the Launchpad or msiexec. To upgrade a client installation, you can use
either the GUI installer or msiexec.

About this task

Before you begin, ensure that you have backed up your data.

Procedure
• To upgrade a server installation, see “Upgrading an IBM MQ server installation using the Launchpad”
on page 332 or “Upgrading an IBM MQ server installation using msiexec” on page 333.
• To upgrade a client installation, see “Upgrading an IBM MQ client installation using the GUI installer”
on page 334 or “Upgrading an IBM MQ client installation using msiexec” on page 335.

Upgrading an IBM MQ server installation using the Launchpad

How you upgrade an IBM MQ server installation on Windows to a newer version, release, or modification,
using the Launchpad.

Before you begin

Ensure that you have:
1. Stopped all your IBM MQ applications
2. Shut down your listeners
3. Stopped all your queue managers
4. Backed up your data

Procedure
1. Access the IBM MQ installation image.
The location might be a network location, or a local file system directory. See Where to find
downloadable installation images.
2. Locate Setup.exe in the base directory of the IBM MQ installation image.
• From a network location, this location might be m:\instmqs\Setup.exe
• From a local file system directory, this location might be C:\instmqs\Setup.exe

332 Installing and migrating IBM MQ

3. Start the installation process.
Either run Setup.exe from a command prompt, or double-click Setup.exe from Windows Explorer.
Note: If you are installing on a Windows system with UAC enabled, accept the Windows prompt to
allow the launchpad to run as elevated. During installation, you might also see Open File - Security
Warning dialog boxes that list International Business Machines Limited as the publisher. Click Run to
allow the installation to continue.
The IBM MQ Installation window is displayed.
4. Follow the instructions on screen.
5. Select Installing a new instance, if you see a panel asking you to choose between installing a
new instance, or maintaining or upgrading an existing instance, when you click the Launch IBM MQ
Installer button.
You use the other option when adding or removing features from an already installed IBM MQ.
6. On the next panel, choose between Install leaving the existing installation(s) untouched or Upgrade
an existing named installation already on the machine, and click Next.

Attention: If you do not see this screen, it means that there was no IBM MQ server installation
on the machine that could be upgraded by this installer.
7. Follow the installer prompts to upgrade your IBM MQ server installation.
Related tasks
“Upgrading an IBM MQ server installation using msiexec” on page 333
How you upgrade an IBM MQ server installation on Windows to a newer version, release, or modification,
using msiexec.
“Upgrading an IBM MQ client installation using the GUI installer” on page 334
How you upgrade an IBM MQ client installation on Windows to a newer version, release, or modification,
using the GUI installer.
“Upgrading an IBM MQ client installation using msiexec” on page 335
How you upgrade an IBM MQ client installation on Windows to a newer version, release, or modification,
using msiexec.

Upgrading an IBM MQ server installation using msiexec

How you upgrade an IBM MQ server installation on Windows to a newer version, release, or modification,
using msiexec.

Before you begin

Ensure that you have:
1. Stopped all your IBM MQ applications
2. Shut down your listeners
3. Stopped all your queue managers
4. Backed up your data

Procedure
1. Access the IBM MQ installation image.
The location might be a network location, or a local file system directory. See Where to find
downloadable installation images.
2. Locate IBM MQ.msi in the MSI directory of the IBM MQ installation image.
• From a network location, this location might be m:\instmqs\MSI\IBM MQ.msi
• From a local file system directory, this location might be C:\instmqs\MSI\IBM MQ.msi

Installing and migrating 333

 3. Optional: If you are upgrading the only IBM MQ server installation, where the installation has the
default value Installation1 issue the following command:

msiexec /i "InstallationImage\MSI\IBM MQ.msi" /q AGREETOLICENSE=YES

INSTALLATIONNAME="Installation1"

4. Optional: If you are upgrading an installation on a machine that already has one or more IBM MQ
server installations of the level you are upgrading to, you must provide additional parameters to select
a free MSI instance ID.
See “Choosing MSI Instance IDs for multiple server installations” on page 180 for more information.
In this case, the command might look something like this:

msiexec /i "InstallationImage\MSI\IBM MQ.msi" /q AGREETOLICENSE=YES

INSTALLATIONNAME="Installation2" NEWINSTANCE=1
TRANSFORMS=":InstanceId2.mst;1033.mst"

Related tasks
“Upgrading an IBM MQ server installation using the Launchpad” on page 332
How you upgrade an IBM MQ server installation on Windows to a newer version, release, or modification,
using the Launchpad.
“Upgrading an IBM MQ client installation using the GUI installer” on page 334
How you upgrade an IBM MQ client installation on Windows to a newer version, release, or modification,
using the GUI installer.
“Upgrading an IBM MQ client installation using msiexec” on page 335
How you upgrade an IBM MQ client installation on Windows to a newer version, release, or modification,
using msiexec.

Upgrading an IBM MQ client installation using the GUI installer

How you upgrade an IBM MQ client installation on Windows to a newer version, release, or modification,
using the GUI installer.

Before you begin

Ensure that you have:
1. Stopped all your IBM MQ applications
2. Shut down your listeners
3. Stopped all your queue managers
4. Backed up your data

Procedure
1. Access the IBM MQ installation image.
See Where to find downloadable installation images.
2. Locate Setup.exe in the Windows directory of the IBM MQ installation image.
3. Start the installation process.
Either run Setup.exe from a command prompt, or double-click Setup.exe from Windows Explorer.
Note: If you are installing on a Windows system with UAC enabled, accept the Windows prompt to
allow the launchpad to run as elevated. During installation, you might also see Open File - Security
Warning dialog boxes that list International Business Machines Limited as the publisher. Click Run to
allow the installation to continue.
The IBM MQ Installation window is displayed.

334 Installing and migrating IBM MQ

4. Follow the instructions on screen. When you click the Launch IBM MQ Installer button, if you see a
panel asking you to choose between installing a new instance, or maintaining or upgrading an existing
instance, select Installing a new instance.
5. On the next panel, choose between Install leaving the existing installation(s) untouched or Upgrade
an existing named installation already on the machine, and click Next.

Attention: If you do not see this screen, it means that there was no IBM MQ client installation
on the machine that could be upgraded by this installer.
6. Follow the installer prompts to upgrade your IBM MQ client installation.
Related tasks
“Upgrading an IBM MQ client installation using msiexec” on page 335
How you upgrade an IBM MQ client installation on Windows to a newer version, release, or modification,
using msiexec.
“Upgrading an IBM MQ server installation using the Launchpad” on page 332
How you upgrade an IBM MQ server installation on Windows to a newer version, release, or modification,
using the Launchpad.
“Upgrading an IBM MQ server installation using msiexec” on page 333
How you upgrade an IBM MQ server installation on Windows to a newer version, release, or modification,
using msiexec.

Upgrading an IBM MQ client installation using msiexec

How you upgrade an IBM MQ client installation on Windows to a newer version, release, or modification,
using msiexec.

Before you begin

Ensure that you have:
1. Stopped all your IBM MQ applications
2. Shut down your listeners
3. Stopped all your queue managers
4. Backed up your data

Procedure
1. Access the IBM MQ installation image.
See Where to find downloadable installation images.
2. Locate IBM MQ.msi in the Windows\MSI directory of the IBM MQ installation image.
3. Optional: If you are upgrading the only IBM MQ client installation, where the installation has the
default value Installation1 issue the following command:

msiexec /i "InstallationImage\Windows\MSI\IBM MQ.msi" /l*v install_log_path

/q TRANSFORMS="1033.mst" REINSTALL=ALL REINSTALLMODE=vomus

4. Optional: If you are upgrading an installation on a machine that already has one or more IBM MQ client
installations of the level you are upgrading to, you must provide additional parameters to select a free
MSI instance ID.
See “Choosing MSI Instance IDs for multiple client installations” on page 205 for more information.
In this case, the command might look something like this:

msiexec /i "InstallationImage\MSI\IBM MQ.msi" /q AGREETOLICENSE=YES

INSTALLATIONNAME="Installation2" NEWINSTANCE=1
TRANSFORMS=":InstanceId2.mst;1033.mst"

Installing and migrating 335

 Related tasks
“Upgrading an IBM MQ client installation using the GUI installer” on page 334
How you upgrade an IBM MQ client installation on Windows to a newer version, release, or modification,
using the GUI installer.
“Upgrading an IBM MQ server installation using the Launchpad” on page 332
How you upgrade an IBM MQ server installation on Windows to a newer version, release, or modification,
using the Launchpad.
“Upgrading an IBM MQ server installation using msiexec” on page 333
How you upgrade an IBM MQ server installation on Windows to a newer version, release, or modification,
using msiexec.

Migrating IBM MQ
Migration is the conversion of programs and data to work with a new code level of IBM MQ. Some
types of migration are required, and some are optional. Queue manager migration is never required after
applying a maintenance level update, that does not change the command level. Some types of migration
are automatic, and some are manual. Queue manager migration is typically automatic and required after
releases and manual and optional after a maintenance level upgrade that introduces a new function.
Application migration is typically manual and optional.

Before you begin

Before upgrading your IBM MQ installation or migrating your queue managers, you must read “Changes
that affect migration” on page 337 to identify what migration tasks you must plan for.

About this task

Whenever you upgrade IBM MQ to a new release that changes its command level, migration is performed
by the queue manager. Whenever you upgrade IBM MQ to a new maintenance or fix level, which
introduces a new function using a new command level, you can migrate the queue manager to use the
new command level and thereby the new function.
If you start a queue manager running on a later release level, then migration of the queue manager to that
release level is required. .

On IBM MQ for Multiplatforms, you cannot easily revert to a previous level of IBM MQ after
installation. If you install a copy of IBM MQ obtained from Passport Advantage or from physical media,
the installer uninstalls IBM MQ, if it is present. It then installs the new level of IBM MQ. To revert to the
previous level of IBM MQ, you must keep the earlier installation image and any fixes you applied. Then
you must uninstall the new level, reinstall the previous release level, and reapply the required fixes. If
you have started any queue managers at the later level, they will not work with the restored level of
IBM MQ. (Unless you installed a later maintenance level upgrade, not a new release or version: then
you could revert to an earlier maintenance level by reinstalling the earlier maintenance level upgrade.
Queue manager data is compatible between maintenance levels.) To restore IBM MQ to its previous level,
after starting any queue managers, you must first back up the queue managers. You can then restore the
backup queue managers after restoring the previous level of IBM MQ.

Important: From IBM MQ 9.4.0, AMQP channels no longer support CMS key
repository files. If you are migrating a queue manager with an AMQP configuration to IBM MQ 9.4.0 or
later, and your queue manager is currently configured with a CMS keystore, you must convert it to PKCS12
format before proceeding with the migration. For more information on how to perform this conversion, see
SSL/TLS support in Securing AMQP Clients.
Related concepts
IBM MQ release types and versioning
“Multi-installation queue manager coexistence on AIX, Linux, and Windows” on page 357
You can install multiple copies of IBM MQ for AIX, Linux, and Windows on the same server. These IBM MQ
copies can be at the same or different version levels. This is called a multi-installation. Multi-installation is

336 Installing and migrating IBM MQ

particularly useful when you upgrade from one IBM MQ version to a later version, because it allows you to
run the earlier version alongside the later version.
“Queue manager coexistence” on page 355
Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations.
Related tasks
Backing up and restoring a queue manager

Changes that affect migration

Changes to the product might affect the migration of a queue manager from an earlier release to the
current release of IBM MQ, or affect existing applications or configurations. Review these changes before
upgrading queue managers to the latest product version and decide whether you must plan to make
changes to existing applications, scripts, and procedures before starting to migrate your systems.

Changes in the current release

For details of changes in the current release, including those that affect migration, see the following
information:

• What's new and changed in IBM MQ 9.4.0

• IBM MQ, WebSphere MQ, and MQSeries product readmes

Changes in earlier versions

For information about what changed in an earlier release of the product, see the What's new and What's
changed sections in the product documentation for that version of the product:
• IBM MQ 9.3
– What's new and changed in IBM MQ 9.3.0
– What's new and changed in IBM MQ 9.3.x Continuous Delivery
– What's changed in IBM MQ 9.3.0 Long Term Support

– IBM MQ, WebSphere MQ, and MQSeries product readmes

• IBM MQ 9.2
– What's new and changed in IBM MQ 9.2

– What's new and changed in IBM MQ 9.2.x Continuous Delivery

– What's changed in IBM MQ 9.2.0 Long Term Support

• IBM MQ 9.1
– What's new and changed in IBM MQ 9.1

– What's new and changed in IBM MQ 9.1.x Continuous Delivery

– What's changed in IBM MQ 9.1.0 Long Term Support

• IBM MQ 9.0
– What's new and changed in IBM MQ 9.0.0

– What's new and changed in IBM MQ 9.0.x Continuous Delivery

– What's changed in IBM MQ 9.0.0.x Long Term Support

• IBM MQ 8.0

Installing and migrating 337

 – What's new in IBM MQ 8.0
– What's changed in IBM MQ 8.00
– What's changed in IBM MQ 8.0 Fix Packs
• IBM WebSphere MQ 7.5
– What's new in IBM WebSphere MQ 7.5
– What's changed in IBM WebSphere MQ 7.5
– What's changed in IBM WebSphere MQ 7.5 Fix Packs
For older, out of support, versions of the product, the documentation is not available in the online
IBM Documentation, but is available for you to download for offline use. For more information, see
Documentation for older versions of IBM MQ.

Restrictions on reversing queue manager migration

Attention:

On IBM MQ for Multiplatforms, you cannot reverse queue manager migration to

remove the effect of changes. This restriction applies whether your enterprise uses the Long Term
Support (LTS) release or Continuous Delivery (CD) release model.
For more information, see IBM MQ release types: planning considerations.
Related concepts
“Migration concepts and methods” on page 340
An overview of the various concepts and methods for migrating from one release of the product to
another.
“Migration considerations for IBM MQ 8.0 or later on Windows” on page 374
“Program and data directory locations on Windows” on page 376
The installation location for IBM MQ program binary and data files on Windows depends on the IBM MQ
version you are installing, and whether this is the first time IBM MQ is being installed.

Considerations when migrating from Advanced Message Security 7.0.1

Advanced Message Security is a component of IBM MQ.
Important:
If you are migrating to IBM MQ 9.4 or later from IBM WebSphere MQ 7.5 or earlier, you must first migrate
to an interim version. See Migration paths.
Review the following list of changes carefully before upgrading queue managers to a later version of IBM
MQ. Decide whether you must plan to make changes to existing applications, scripts, and procedures
before starting to migrate systems:
• From IBM WebSphere MQ 7.5, AMS installation is a part of the IBM MQ installation process.
• The AMS security capabilities are enabled with its installation and controlled with security policies. You
do not need to enable interceptors to allow AMS to start intercepting data.
• AMS in IBM MQ does not require the use of the cfgmqs command as in the stand-alone version of
Advanced Message Security.

Migration paths
An overview of the migration paths between different IBM MQ versions.
Note: Before each new version of the product is released, it is tested for migration from earlier versions
that are in support at that time. Direct migration from a version that is out of support might also work, but
is neither tested nor supported. Therefore, to migrate to the latest version from a version that is out of
support, you should first migrate to an interim version that was released before the earlier version went
out of support.

338 Installing and migrating IBM MQ

• “Migration paths: IBM MQ for Multiplatforms” on page 339
• “Detailed migration information” on page 339

Migration paths: IBM MQ for Multiplatforms

You can migrate from IBM MQ 9.0 or later direct to IBM MQ 9.4 or later.
Direct migration from IBM MQ 8.0 to IBM MQ 9.4 is not supported. You must first migrate to IBM MQ 9.0,
IBM MQ 9.1, IBM MQ 9.2 or IBM MQ 9.3.

Table 37. Migration paths: IBM MQ for Multiplatforms

Migration To IBM MQ To IBM MQ To IBM MQ To IBM MQ To IBM MQ To IBM MQ
from 9.4 or later 9.3 9.2 9.1 9.0 8.0
IBM MQ 9.3 Yes - - - - -
or later
IBM MQ 9.2 Yes Yes - - - -
IBM MQ 9.1 Yes Yes Yes - - -
IBM MQ 9.0 Yes Yes Yes Yes - -
IBM MQ 8.0 No Yes Yes Yes Yes -

Note: For IBM MQ 9.0 and later, the version covers both LTS and CD releases.
For IBM MQ for Multiplatforms, you cannot easily revert to a previous release of the product. However, if a
queue manager has not been started, you can uninstall the current version and reinstall a different version
of IBM MQ. It does not matter what versions of IBM MQ are installed between when a queue manager
was last started and when it is next started.
After you have moved to a CD modification of the product, you must move to a higher version and release
level to return to the LTS track. For example, you cannot go from IBM MQ 9.3.1 CD to IBM MQ 9.3.0.n LTS.
Your next opportunity to return to the LTS track is at IBM MQ 9.4.0.

Detailed migration information

For detailed information about migrating to the current version, see the following links:

• “Planning to migrate IBM MQ to a later version on Windows” on page 373

• “Planning to migrate IBM MQ to a later version on AIX and Linux” on page

405

• “Planning to migrate IBM MQ to a later version on IBM i” on page 430

For migrating to an IBM MQ version other than the current version, see the documentation for the target
version:
• Migrating IBM MQ (IBM MQ 9.3)
• Migrating IBM MQ (IBM MQ 9.2)
• Migrating IBM MQ (IBM MQ 9.1)
• Migrating IBM MQ (IBM MQ 9.0)
• IBM MQ migration (IBM MQ 8.0)
For out of service IBM MQ versions, where the documentation is no longer available in the online IBM
Documentation, you can instead download the documentation for offline use. See Documentation for
older versions of IBM MQ.

Installing and migrating 339

 Related concepts
“Migration concepts and methods” on page 340
An overview of the various concepts and methods for migrating from one release of the product to
another.

Migration concepts and methods

An overview of the various concepts and methods for migrating from one release of the product to
another.

Objects to consider during migration

It is important to consider four types of object during migration:
Operating environment migration
Upgrading the operating environment, or components in the environment such as installing a new
level of JRE; see “ IBM MQ operating environment migration” on page 342.
Queue manager migration
Migrating a queue manager following an upgrade of the IBM MQ installation to a new command level;
see “Queue manager migration” on page 343.
When migrating queue managers that are members of a cluster, do full repositories before partial
repositories. This is because an older repository cannot store newer attributes introduced in a newer
release. It tolerates them, but does not store them.
IBM MQ MQI client migration
Migrating a client configuration following installation of a new version or release of the IBM MQ MQI
client ; see “IBM MQ MQI client migration” on page 344.
It is better to migrate the clients after the queue managers that they communicate with have been
migrated.
Application migration
Relinking, recompiling, or recoding an IBM MQ server or client application; see “Application migration
and interoperation” on page 345. Application migration also includes migrating any API or channel
exits.
Use the new version of the libraries to build the applications, once the queue managers have been
upgraded.

Impact of migration on other queue managers or clients

In addition, you must consider the impact of migrating one queue manager, or IBM MQ MQI client, on
other queue managers or clients:
Compatibility, coexistence, and interoperability
See “Coexistence, compatibility, and interoperability” on page 354 for information about the
compatibility of IBM MQ applications connected to queue managers and IBM MQ MQI client clients on
different command levels. The section also explains the concept of queue manager coexistence, and
the interoperability of IBM MQ JMS applications with WebSphere Application Server.
Queue manager clusters
Can a queue manager cluster contain queue managers at different command levels? See “Migrating a
queue manager cluster” on page 451 to answer this question, and how to migrate a cluster of queue
managers.
High-availability clusters
How do you migrate queue managers that are part of a high-availability cluster to a new command
level, and maintain continuous and reliable service? See “Migrating a queue manager in a high-
availability configuration” on page 457, which covers both migration of multi-instance queue
managers, and the migration of queue managers operating in high-availability clusters.

340 Installing and migrating IBM MQ

IBM MQ application migration model
Figure 1 on page 341 shows the various components of the application migration model.

Figure 1. IBM MQ application migration model

This diagram shows two runtime operating system environments, each of which contains a number of
software components, such as databases, application servers, and the language or subsystem run time
environment. One environment is called Server, and contains an IBM MQ server and server application.
The other environment is called Client, and contains an IBM MQ MQI client application.
The language or subsystem run time environment contains an IBM MQ application, the IBM MQ MQI client
or server library, and IBM MQ channel and API exit programs.
The server environment has one or more queue managers, represented in the diagram by QM, that are
using the installation of IBM MQ installed on the server. The components of the language or subsystem

Installing and migrating 341

 run time environment are connected to queue manager QM, either locally in the server, or remotely from
the client.
The application is linked to the IBM MQ library by the MQI. The libraries are shown linked to the queue
manager QM either by an SPI, which describes the connection between the process running the MQI and
the queue manager processes, or by an IBM MQ MQI client connection.
The diagram also shows two more queue managers:
• The queue manager labeled QM*, which represents queue managers of various levels installed on other
servers.
• The queue manager labeled QM-n?, which represents a number of queue managers that coexist on the
same server as queue manager QM, but are running at a different release level. The installations for
these different release levels are not shown in the diagram. The question-mark in the queue manager
name QM-n? indicates that this capability might not be present in your environment.
Multiple releases of IBM MQ installed in the same operating environment are called coexistent. It is not
necessary, but it is usual, for coexistent installations to be at different release levels. Queue manager
coexistence is important for migration in two respects:
1. It can be used to reduce the risk involved in migrating to a new command level, and reduce the
downtime during the migration process.
2. You must consider any configuration implications of running some applications or clusters on the same
server with queue managers at different command levels.
For more information, see “Queue manager coexistence” on page 355.

IBM MQ operating environment migration

You might need to perform some migration tasks for IBM MQ as a result of upgrading the operating
environment.
To find out what operating environment upgrades you must make before upgrading IBM MQ, compare
the requirements for different releases. For more information about system requirements, see System
Requirements for IBM MQ. By selecting the appropriate link on the web page, the SPCR tool enables
you to go directly to the following information for the specific operating system, or systems, that your
enterprise uses.
• Supported operating systems
• Prerequisites
• System requirements
• Optional supported software
For details about operating environment changes in the latest release that directly affect the migration to
a new version of IBM MQ, see the following information:
• What's new and changed in IBM MQ 9.4.0

• IBM MQ, WebSphere MQ, and MQSeries product readmes

Particular considerations apply when migrating an RDQM configuration, see “Applying OS updates with
RDQM” on page 264 and “Migrating replicated data queue managers” on page 460.
For information about what changed in an earlier release of the product, see the What's new and What's
changed sections in IBM Documentation for that version of the product:
• IBM MQ 9.3
– What's new and changed in IBM MQ 9.3.0
– What's new and changed in IBM MQ 9.3.x Continuous Delivery
– What's changed in IBM MQ 9.3.0 Long Term Support
• IBM MQ 9.2
– What's new and changed in IBM MQ 9.2

342 Installing and migrating IBM MQ

 – What's new and changed in IBM MQ 9.2.x Continuous Delivery

– What's changed in IBM MQ 9.2.0 Long Term Support

• IBM MQ 9.1
– What's new and changed in IBM MQ 9.1

– What's new and changed in IBM MQ 9.1.x Continuous Delivery

– What's changed in IBM MQ 9.1.0 Long Term Support

• IBM MQ 9.0
– What's new and changed in IBM MQ 9.0.0

– What's new and changed in IBM MQ 9.0.x Continuous Delivery

– What's changed in IBM MQ 9.0.0.x Long Term Support

• IBM MQ 8.0
– What's new in IBM MQ 8.0
– What's changed in IBM MQ 8.0
– What's changed in IBM MQ 8.0 Fix Packs
• IBM WebSphere MQ 7.5
– What's new in IBM WebSphere MQ 7.5
– What's changed in IBM WebSphere MQ 7.5
– What's changed in IBM WebSphere MQ 7.5 Fix Packs
• For IBM WebSphere MQ 7.1 and earlier, see Documentation for older versions of IBM MQ.
Some changes might affect IBM MQ migration indirectly. For example, the runtime linkage conventions for
applications, or the way memory is allocated, might change.

Queue manager migration

After upgrading an installation, queue manager migration might be required. Migration takes place when
you start a queue manager. You can remove an upgrade before you have started a queue manager.
However, if you remove the upgrade after a queue manager has been started, the queue manager will not
work.

Migrating a queue manager to a later release

On IBM MQ for Multiplatforms, queue manager migration is always required for changes
in the first two digits of the VRMF. Changes in the maintenance and fix level, M and F in the VRMF,
never cause automatic queue manager migration. A change in the command level always requires queue
manager migration, but if the change is shipped in a maintenance or fix pack, you have the choice of
whether to increase the command level, and cause queue manager migration.
Command level always increases with a change in version or release. If you decide to use new function
introduced in a maintenance level upgrade, you must change the command level. The converse is not the
case. You do not have to change the command level when the fix level changes. You can decide to install
the fix pack, but not use the new function. Whether or not you use the new function, the installation of
the fix pack increases the maximum command level supported by the installation. Run the dspmqver
command to display the current maximum supported command level.
Queue manager migration is the process of converting persistent queue manager data from one version
to another. Persistent queue manager data includes log files and data in the queue manager directory.
The data records changes to objects such as messages, subscriptions, publications, queue managers,
channels, queues, and topics.
Queue manager migration is required and largely automatic.

Installing and migrating 343

 You can reduce the downtime and risk caused by queue manager migration, by verifying the new version
first, using a different queue manager. Unless the platform supports queue manager coexistence, you
need to perform the verification on a different server, or in a virtualized environment on the same server.
If the platform you are upgrading supports queue manager coexistence, you can install the new version of
IBM MQ on the same server, verify it, and minimize downtime to the time required to stop, backup, and
restart the queue manager.
Note: If you are migrating a queue manager through multiple release levels, one level at a time, you must
start the queue manager after each upgrade to migrate it. You must also start all the channels, to ensure
they are migrated.
If you migrate from IBM MQ 8.0.0 Fix Pack 1, 2, or 3 directly to a version between IBM MQ 9.1.5 andIBM
MQ 9.2.0 Fix Pack 1 inclusive, channel objects are not migrated correctly when the queue manager is
started at the new code level. Channels continue to work normally, but channel names are not displayed
by the runmqsc command or IBM MQ Explorer. From IBM MQ 9.2.0 Fix Pack 2, channel definitions are
migrated correctly when the queue manager is started for the first time at the new code level.
When migrating queue managers that are members of a cluster, migrate full repositories before partial
repositories. This is because an older repository cannot store newer attributes introduced in a newer
release. It tolerates them, but does not store them.

Restoring a queue manager to an earlier release

For IBM MQ for Multiplatforms, you cannot restore a queue manager to an earlier release
level after you have migrated it to a new release. You must back up your system before starting backwards
migration. You can either back up queue manager data, or use a backup queue manager; see Backing up
and restoring IBM MQ. Before backing up, you must stop the queue manager.
Related concepts
IBM MQ release types and versioning
Related tasks
“Migrating a queue manager on AIX and Linux” on page 406
The procedures for migrating a queue manager to a later version of the product, and for restoring a queue
manager to an earlier version of the product are detailed in this section.
“Migrating a queue manager on Windows” on page 378
The procedures for migrating a queue manager to a later version of the product, and for restoring a queue
manager to an earlier version of the product are detailed in this section.
“Migrating a queue manager to the latest version on IBM i” on page 432
Follow these instructions to migrate a queue manager on IBM i to the latest MQ version.
Related information
Moving a queue manager to a different operating system

IBM MQ MQI client migration

IBM MQ MQI client migration is the process of converting IBM MQ MQI client configurations, and client
and server channels from one version to another. Client migration can take place after upgrading the IBM
MQ MQI client, and is reversible.
It is better to migrate the clients after the queue managers that they communicate with have been
migrated.
Client migration on the client workstation is optional and manual. Client migration on the server is
required and automatic. You must upgrade an IBM MQ MQI client before migrating a client workstation
to make use of new configuration options. You can make configuration changes to client and server
connection channels on the server, but they have no effect on a client workstation, until the client is
upgraded.
An example of client migration performed at the client workstation is to manually migrate configuration
settings to the mqclient.ini configuration file.

344 Installing and migrating IBM MQ

An example of combined client and server migration is the deployment of a new client connection
definition table (CCDT). To use a new version of the CCDT, generate the table on a queue manager that is
at the new code level. Deploy the table to clients that are going to use it. To deploy the table to a client,
you first must update the client to at least the same level as the queue manager that created the table.
An IBM MQ MQI client can interoperate with earlier and later versions of IBM MQ. Upgrading the IBM MQ
MQI client makes new function available to client applications, and is important to maintain the service
level. Migrating an IBM MQ MQI client gives it access to new configuration options.
The IBM MQ MQI client libraries, such as mqic.dll, are dynamic, and the application linkages to the
libraries do not normally change. You do not relink a client application to pick up new IBM MQ client
libraries. The client picks up the new library next time the library is loaded by the client application. Do
not move libraries from their installed directory. Linking to libraries in anything other than their installed
directory is an unsupported configuration.
Related concepts
“Application compatibility and interoperability with earlier versions of IBM MQ” on page 366
“Application compatibility and interoperability with later versions of IBM MQ” on page 367
IBM MQ applications run against later versions of a queue manager without recoding, recompiling, or
relinking. You can connect an application that is built against libraries shipped with an earlier version of
IBM MQ to a queue manager running at a later version of IBM MQ.
Related tasks
“Migrating an IBM MQ MQI client to the latest version on IBM i” on page 446
Before migrating an IBM MQ MQI client, create a migration plan. Stop all IBM MQ activity on the
client workstation. Upgrade the IBM MQ MQI client installation. Make any essential configuration and
application changes.
“Migrating an IBM MQ MQI client on AIX and Linux” on page 421
Before migrating an IBM MQ MQI client, create a migration plan. Stop all IBM MQ activity on the
client workstation. Upgrade the IBM MQ MQI client installation. Make any essential configuration and
application changes.
“Migrating an IBM MQ MQI client on Windows” on page 395
Before migrating an IBM MQ MQI client, create a migration plan. Stop all IBM MQ activity on the
client workstation. Upgrade the IBM MQ MQI client installation. Make any essential configuration and
application changes.
Related reference
“MQ clients: Client Channel Definition Table (CCDT)” on page 368
You can connect a supported IBM MQ client application to any supported level of queue manager. If a
client uses CCDT to connect to a queue manager, the CCDT can be at a version greater than, less than, or
equal to that of the client.
“Supported IBM MQ client: Default behavior of client-connection and server-connection channels” on
page 370

Application migration and interoperation

IBM MQ supports running applications compiled and linked against previous versions of IBM MQ, with
later levels of IBM MQ. Use the new version of the libraries to build the applications, once the queue
managers have been upgraded.
To migrate an application to run with a new level of IBM MQ, disconnect an application from the queue
manager. Reconnect it when the queue manager is running again. However, it takes only one small
difference in the interface between IBM MQ and the application to break an application, or make it behave
wrongly. Sometimes a problem does not show up for a long time. For this reason, you must always test
your applications against a new version of IBM MQ. The suggested extent of testing varies depending on
the extent of the changes in IBM MQ; see “Characteristics of different types of upgrade” on page 277.
Application migration refers to four kinds of changes.
1. Application changes that are consequent to upgrading the operating environment along with the queue
manager. Rarely, linkage conventions change. The most likely reason for a linkage change is switching

Installing and migrating 345

 from 32 bit to a 64 bit environment. If you are using SSL or TLS you might have to relink with a new
secure library.
2. Changes that you must make to the application in order to run an application against a new level of
queue manager. Changes of this sort are uncommon. However, you must check “Changes that affect
migration” on page 337 to see if any changes might affect your applications.
3. Changes that are not required, but that you might want to make in future, perhaps because you have a
business reason to modify an application.
4. Changes to applications that are supplied by IBM, or other vendors, that require you to run migration
utilities. The utilities convert the applications to running on the new version of IBM MQ.
Do not load IBM MQ libraries from an earlier level. IBM MQ does not support connecting server
applications loading libraries from the earlier level to connect to a later level of queue manager. On
AIX, Linux, and Windows platforms, the application load path must be set up to the location of the IBM
MQ server libraries. You do not have to recompile and relink an application. Applications compiled and
linked against an earlier version of IBM MQ can load libraries from a later version.

On Multiplatforms, the product loads the library from the installation the application is
connecting to. An application must initially load a library of at least the same level as the application
linked to. IBM MQ then loads the correct version of the library from the installation that the queue
manager is associated with. If you have two installations of the same version, but at different fix levels,
IBM MQ chooses which library to load. The choice is based on the queue manager the application is
connected to. If an application is connected to multiple queue managers, it is possible that multiple
libraries are loaded.
To help you write applications that can exchange messages with earlier versions of the product, IBM
MQ provides data type versioning. Data type versioning assists you in exchanging messages that are
compatible with target queue managers. A good programming practice is to set the version number of
a data structure explicitly. Do not assume that the default version is the one you require. By setting the
version explicitly, you are forced to look up what version to use. The description of the data type version
tells you what level of queue manager supports that version.
It is poor practice to set the data type version to the current version. If you recompile your program
against a new version of IBM MQ, the data type version might change with unexpected consequences.
Client applications are more likely to connect to different queue managers than applications written
for a specific server. Plan carefully when writing an application that is to connect to different versions
of a queue manager, and to queue managers on different platforms. The default values of some IBM
MQ constants, such as MQPMO_SYNCPOINT, MQPMO_NO_SYNCPOINT differ between platforms. Some
functions are not available on all platforms.
You must be aware of, and code to, the capabilities of all the queue managers the application interacts
with. It requires planning and design to write an application that works with different versions of a queue
manager. There is no API provided with IBM MQ to restrict an application to a function subset common
to the set of queue managers it interacts with. To improve interoperability, some developers choose to
provide an MQI wrapper layer, or use MQI API exits, to control the functions programs use.

Connection authentication
For a new IBM MQ 8.0, or later, installation, the CONNAUTH CHCKLOCL attribute will be set to OPTIONAL.
This means that user IDs and passwords are not required, but if they are provided they must be a valid
pair, or they will be rejected.
When you are migrating between a previous version of IBM MQ and the latest version, the CONNAUTH
CHCKLOCL attribute on each queue manager is set to NONE, ensuring version to version continuity, but
switching connection authentication off.
For more information see Connection authentication: Configuration.
Related concepts
“Application compatibility and interoperability with earlier versions of IBM MQ” on page 366

346 Installing and migrating IBM MQ

“Application compatibility and interoperability with later versions of IBM MQ” on page 367
IBM MQ applications run against later versions of a queue manager without recoding, recompiling, or
relinking. You can connect an application that is built against libraries shipped with an earlier version of
IBM MQ to a queue manager running at a later version of IBM MQ.
Related tasks
“Migrating IBM MQ library loading to a later version on AIX and Linux” on page 424
On AIX and Linux, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to a later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
“Migrating IBM MQ library loading to a later version on Windows” on page 396
On Windows, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to the later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.

Migration methods on IBM MQ for Multiplatforms

There are three main methods of migrating from one release to another: Single-stage migration (called a
slip installation on IBM i), side-by-side migration, and multi-stage migration. Multi-stage migration is not
an option for IBM i.
Important:
If you are migrating to IBM MQ 9.4 or later from IBM WebSphere MQ 7.5 or earlier, you must first migrate
to an interim version. See Migration paths.

Single-stage migration
Single-stage migration is the term that is used to describe replacing the only installation of IBM MQ on a
server, with a later release.
The advantage of single-stage migration is that it changes the configuration of a queue manager on the
earlier version as little as possible. Existing applications switch from loading the libraries from the earlier
version, to loading the libraries of the later version, automatically. Queue managers are automatically
associated with the installation on the later version. Administrative scripts and procedures are affected as
little as possible by setting the installation to be the primary installation. If you set the installation of the
later version to be the primary installation, commands such as strmqm work without providing an explicit
path to the command.
Of the three approaches, single-stage migration preserves the greatest number of existing scripts and
procedures for running IBM MQ. However, the other migration approaches support a gentler transition to
the new version, which can reduce the overall impact on users.

Installing and migrating 347

 Figure 2. Single_stage migration: earlier version installed with connected queue managers and associated
applications

Figure 3. Single_stage migration: later version installed but queue managers not yet connected and
applications not yet associated

348 Installing and migrating IBM MQ

Figure 4. Single_stage migration: migrated queue managers connected to and applications associated with
later version

For more information about single-stage migration, see:

• “Migrating on AIX and Linux: single-stage” on page 407

• “Migrating on Windows: single stage” on page 381

• “Installation methods on IBM i” on page 432 (on IBM i, a single-stage migration is called a
slip installation)

Side-by-side migration
On AIX, Linux, and Windows, side-by-side migration is the term that is used to describe installing a later
version of IBM MQ alongside an older version on the same server. The side-by-side migration scenario
sits half-way between the single-stage and multi-stage migration scenarios and is based on the following
premise:
• Install additional IBM MQ code alongside existing installation while queue managers are still running.
• Move queue managers one at a time to the new installation.
• Migrate and test applications one at a time.
During the installation and verification of the later version of IBM MQ, queue managers continue running,
and remain associated with the older version of IBM MQ.

Installing and migrating 349

 Figure 5. Side-by-side migration: later version installed but queue managers still connected to and
applications still associated with earlier version

When you decide to migrate queue managers to the later version of IBM MQ, you stop all queue
managers, migrate them all to the later version, and uninstall the earlier version of IBM MQ.

Figure 6. Side-by-side migration: migrated queue managers connected to and applications associated with
later version

The advantage that the side-by-side migration has over the single-stage migration is that you can install
and verify the later IBM MQ installation on the server before you switch over to it.
Although side-by-side migration is less flexible than multi-stage migration, it does have some advantages
over the multi-stage approach. With the side-by-side approach, you can assign a later version of IBM
MQ to be the primary installation. With the multistage approach, and one version of IBM MQ set as the

350 Installing and migrating IBM MQ

primary installation, many applications restart without having to reconfigure their environment, as IBM
MQ commands work without providing a local search path.
For more information about side-by-side migration, see:

• “Migrating on AIX and Linux: side-by-side” on page 411

• “Migrating on Windows: side-by-side” on page 386

Note: Side-by-side migration has a different meaning on IBM i. A side-by-side installation

upgrades IBM MQ on a different computer. For more information, see “Installation methods on IBM i” on
page 432. Multiple installations are not applicable to IBM i.

Multi-stage migration

Multi-stage migration is the term that is used to describe running a later version of IBM MQ alongside an
older version on the same server. Multi-stage migration is the most flexible approach.
After you install the later version alongside the earlier version, you can create new queue managers
to verify the installation of the later version, and develop new applications. At the same time, you can
migrate queue managers and their associated applications from the earlier version to the later version. By
migrating queue managers and applications one by one, you can reduce the peak workload on your staff
who are managing the migration.

Figure 7. Multi-stage migration: one queue manager and application migrated to later version, and another
queue manager and application still at earlier version

For more information about multi-stage migration, see:

• “Migrating on AIX and Linux: multi-stage” on page 415

• “Migrating on Windows: multi-stage” on page 389

Installing and migrating 351

 Multiple IBM MQ installations
Multiple IBM MQ installations are supported on AIX, Linux, and Windows. This gives you the option to
install and select between one or more IBM MQ installations.

Overview
You can select between:
• Simplicity of maintaining a single IBM MQ installation.
• Flexibility, by allowing up to a maximum of 128 IBM MQ installations on a system.
You can install multiple copies of the same code level; this is especially convenient for maintenance
purposes.

For example, if you want to upgrade IBM MQ 9.0.0.0 to IBM MQ 9.0.0 Fix Pack 1, you can
install a second copy of IBM MQ 9.0.0.0, apply the maintenance to bring it to IBM MQ 9.0.0 Fix Pack 1,
and then move the queue managers across to the new installation. You still have the original installation,
so it is a simple matter to move the queue managers back if you encounter any problems.
Note that you can only move the queue manager to an installation at the same or a higher version. That is,
you can move a queue manager in the following ways:
• From an earlier version to a later version, but not back. For example, from IBM MQ 9.0.0 to IBM MQ
9.1.0, but not from IBM MQ 9.1.0 to IBM MQ 9.0.0.
• From one fix pack level to another fix pack level at the same version, and back. For example, from IBM
MQ 9.0.0.0 to IBM MQ 9.0.0 Fix Pack 1, and back to IBM MQ 9.0.0.0.

Important considerations for multiple installations

1. On Linux you must ensure that each package installed has a unique name. You can use
the crtmqpkg command to create a unique set of packages. For more information, see “Installing
additional IBM MQ installations on Linux using the rpm command” on page 115.
2. All installations share a data directory; this is where mqs.ini is located for example.
3. All installations share the same namespace for queue managers. This means that you cannot create
several queue managers of the same name in different installations.
4. IBM MQ installations are fully relocatable. Each installation has a separate installation path. You can
choose where to install IBM MQ.
5. IBM MQ resources have installation-scope resource isolation, so operations on one installation do not
affect the others. This means that the resources created by one installation are isolated from those
created by other installations. It enables actions, such as removing an installation of IBM MQ, while
queue managers are running under another installation.
6. Queue managers are associated with an installation. You can move queue managers between
installations at the same or higher version of IBM MQ, but you cannot migrate back to earlier releases.

Locating installations on your system

To locate your installations, you can use the following methods:
• Use the platform installation tools to query what is installed and where on the system
• Use the dspmqver command to display IBM MQ version and build information.
• Use the dspmqinst command to display installation entries from mqinst.ini.

• On AIX and Linux, use the following command to list the installations:

cat /etc/opt/mqm/mqinst.ini

352 Installing and migrating IBM MQ

• On Windows, use the following command to query the registry:

reg.exe query "HKLM\Software\[Wow6432Node\]IBM\WebSphere MQ\Installation" /s

Working with multiple installations

To work with a queue manager, you need to use the commands from its installation. If you select the
wrong installation, you see:

AMQ5691: Queue manager 'MYQM' is associated with a different installation (Inst1)

To work with a queue manager, you have to use the control commands from its associated installation.
You have a choice of:
• Using the full path to the control commands, for example:

$ MQ_INSTALLATION_PATH\bin\strmqm MYQM

or
• Setting the environment variables for an installation with one of:

$ MQ_INSTALLATION_PATH/bin/setmqenv 's
$ setmqenv -m MYQM
$ setmqenv -n InstallationName
$ setmqenv -p MQ_INSTALLATION_PATH

You might consider using a shell script or batch file to set up the environment for each IBM MQ
installation. You can use the setmqenv or crtmqenv commands to help with this.
• setmqenv sets the values of the environment variables, such as PATH, CLASSPATH and
LD_LIBRARY_PATH, for use with an IBM MQ installation.
• crtmqenv creates a list of the environment variables and their values for use with a particular IBM MQ
installation. You can then use this list to incorporate into a shell script or batch file.

Commands
To run a command, the operating system must find the command in an IBM MQ installation. In general,
you must run a command from the installation that is associated with the correct queue manager. IBM MQ
does not switch commands to the correct installation. However, there are some exceptions, such as the
setmqinst command, where you can run the command from any installation that has the latest version
of the product installed.
Commands that work across installations
• dspmq (display queue managers)
• dspmqinst (display IBM MQ installation)
• dspmqver (display version information)
• setmqinst (set IBM MQ installation)
Other control commands for multiple installations
• crtmqenv (create IBM MQ environment)
• dspmqinst (display IBM MQ installation)
• setmqenv (set IBM MQ environment)
• setmqinst (set IBM MQ installation)
• setmqm (set queue manager)

Installing and migrating 353

 If an earlier version of the product is installed, the command that is run is the command for that version,
unless the search path is overridden by a local setting. You can override the search path by running
setmqenv. You must set the correct path to run a command. If you have set a primary installation, the
command that is run is the copy in the primary installation, unless you override the selection with a local
search path.
Related concepts
“Multiple installations on AIX, Linux, and Windows” on page 17
On AIX, Linux, and Windows, it is possible to have more than one copy of IBM MQ on a system.

Coexistence, compatibility, and interoperability

The definitions of the IBM MQ terms coexistence, compatibility, and interoperability.
Coexistence
Is being able to install and run two or more versions of the same program on the same server. For IBM
MQ, it normally means installing and running multiple versions of IBM MQ on a server.
Compatibility
Is the ability to run applications from one level of queue manager with an earlier, or previous level, of
the queue manager.
If you are using a message channel agent (MCA) channel, any version and release of an IBM MQ queue
manager can connect, using an MCA channel, to any version and release of another IBM MQ queue
manager.
The MCA channel is automatically configured to the latest version of protocol that is supported by
both ends of the channel.
Compatibility is also the ability to run client applications with different versions of the IBM MQ MQI
client, and different levels of the queue manager.
Interoperability
Is mainly the ability to exchange messages between different versions of IBM MQ. It can also
mean the interoperability between others things, such as publish/subscribe brokers, or between
components such as the IBM MQ classes for JMS and WebSphere Application Server.
Maintaining the compatibility, coexistence, and interoperability of IBM MQ is important in order to
preserve the investment you make in applications and administrative procedures.
Three areas to which this objective does not apply to as rigidly, are:
• GUI interfaces, such as IBM MQ Explorer.
• Information for service, such as FFST files and traces.
• Error messages. The text in an error message might change, to make the wording clearer or more
accurate.

Coexistence
Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations. In addition to queue managers coexisting on a server, objects,
and commands must work correctly with different queue managers running at different command levels.
The coexistence section lists restrictions in the use of objects and commands when they are used with
queue managers at multiple command levels. The queue managers might be running on a single server, or
in a cluster.
Related concepts
“Queue manager coexistence” on page 355
Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations.
“Multi-installation queue manager coexistence on AIX, Linux, and Windows” on page 357

354 Installing and migrating IBM MQ

 You can install multiple copies of IBM MQ for AIX, Linux, and Windows on the same server. These IBM MQ
copies can be at the same or different version levels. This is called a multi-installation. Multi-installation is
particularly useful when you upgrade from one IBM MQ version to a later version, because it allows you to
run the earlier version alongside the later version.
Related tasks
“Migrating IBM MQ library loading to a later version on AIX and Linux” on page 424
On AIX and Linux, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to a later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
“Migrating IBM MQ library loading to a later version on Windows” on page 396
On Windows, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to the later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.

Queue manager coexistence

Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations.

Single installation queue manager coexistence on all platforms

Single installation queue manager coexistence is useful in development and production environments. In
development environments, you can set up different queue manager configurations to support different
development activities. You can also work with multiple queue manager configurations on a single server,
connected by channels, as if deployed on a network.
In production environments configuring multiple queue managers on a single server is less common.
It has no performance or functional advantage over a single queue manager configuration. Sometimes,
you must deploy multiple queue managers on server. It might be essential to meet the requirements
of a particular software stack, governance, administration, or as a consequence of the consolidation of
servers.

Queue manager coexistence in a multi-installation

Multi-installation queue manager coexistence is supported on AIX, Linux, and Windows.1
With multi-installation queue manager coexistence on the same server, you can run queue managers at
different commands levels on the same server. You can also run multiple queue managers at the same
command level, but associate them with different installations.
Multi-installation adds more flexibility to the coexistence of queue managers using a single installation.
Any of the reasons behind running multiple queue managers, such as supporting different software
stacks, might require different versions of IBM MQ.
The biggest benefit of multi-installation identified by early users, is in upgrading from one version of IBM
MQ to another. Multi-installation makes upgrading less risky, less costly, and is more flexible in meeting
the migration needs of applications running on a server.

1 Do not confuse multi-installation queue manager coexistence with multi-instance queue managers. They
are completely different, though they sound similar in English.

Installing and migrating 355

 The key to migration flexibility is being able to install a new version alongside an existing installation; see
Figure 8 on page 356, which is extracted from “Migrating on AIX and Linux: side-by-side” on page 411 or
“Migrating on Windows: side-by-side” on page 386.

Figure 8. Side-by-side installation - step 2

When the installation is complete, and verified, migrate queue managers and applications to the new
installation; see Figure 9 on page 356. When migration is complete, uninstall the old installation.

Figure 9. Side-by-side installation - step 4

Think of multi-installation as being the basis for a range of migration strategies. At one end is single-stage,
in which you only have one installation on a server at a time. At the other end is multi-stage migration, in
which you continue to run multiple installations at the same time. In the middle is side-by-side migration.
Each of the three strategies is explained in the following tasks:

356 Installing and migrating IBM MQ

1. “Migrating on AIX and Linux: single-stage” on page 407 or “Migrating on Windows: single stage” on
page 381
2. “Migrating on AIX and Linux: side-by-side” on page 411 or “Migrating on Windows: side-by-side” on
page 386
3. “Migrating on AIX and Linux: multi-stage” on page 415 or or “Migrating on Windows: multi-stage” on
page 389

Updating queue managers to a new maintenance level

Another similar use of multi-installation is to support the updating of queue managers to a new
maintenance level. You maintain two installations, one of which has the latest maintenance level
update applied, and the other has the previous maintenance levels. When you have moved all queue
managers to the latest maintenance level, you can replace the previous maintenance level update with
the next maintenance level update to be released. The configuration allows you to stage the updating of
applications and queue managers to the latest maintenance level. You can switch the primary installation
designation to the latest maintenance level.
Related concepts
“Multi-installation queue manager coexistence on AIX, Linux, and Windows” on page 357
You can install multiple copies of IBM MQ for AIX, Linux, and Windows on the same server. These IBM MQ
copies can be at the same or different version levels. This is called a multi-installation. Multi-installation is
particularly useful when you upgrade from one IBM MQ version to a later version, because it allows you to
run the earlier version alongside the later version.
Related tasks
“Migrating IBM MQ library loading to a later version on AIX and Linux” on page 424
On AIX and Linux, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to a later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
“Staging maintenance level updates on AIX” on page 287
On AIX, you can use multiple installations of IBM MQ on the same server to control the release of
maintenance level updates.
“Staging maintenance level updates on Linux” on page 297
On Linux, you can use multiple installations of IBM MQ on the same server to control the release of
maintenance level updates.
“Staging maintenance level updates on Windows” on page 313
On Windows systems, you can use multiple installations of IBM MQ on the same server to control the
release of maintenance level updates.
“Migrating IBM MQ library loading to a later version on Windows” on page 396
On Windows, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to the later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.

Multi-installation queue manager coexistence on AIX, Linux, and Windows

You can install multiple copies of IBM MQ for AIX, Linux, and Windows on the same server. These IBM MQ
copies can be at the same or different version levels. This is called a multi-installation. Multi-installation is
particularly useful when you upgrade from one IBM MQ version to a later version, because it allows you to
run the earlier version alongside the later version.

Installing and migrating 357

 Note: On Linux, a multi-installation can only be created when using the RPM installation media. Multi-
installation is not supported on Ubuntu.
When you plan a multi-installation, you need only consider the major IBM MQ version number (for
example, IBM MQ 9.4). CD releases and fix pack levels are not a significant additional factor.
The following figure shows two IBM MQ installations at different versions (for example, versions 9.4 and
9.1), two queue managers, and three applications. In this figure, note that application 3 is configured to
load libraries from the Inst1 (IBM MQ 9.4) installation, even though it is connected to queue manager
QM2 (IBM MQ 9.1).

358 Installing and migrating IBM MQ

 Application
1

IBM MQ 9.4
QM1
Installation
(9.4)
“Inst1"

IBM MQ 9.1
Installation QM2
“Inst2" (9.1)

Application Application
2 3

Figure 10. Coexistence of two queue managers running at different IBM MQ versions
Installing and migrating 359
 If you run multiple installations of IBM MQ on a server you must consider three questions:
1. Which installation is a queue manager associated with? See “Queue manager association” on page
360.
2. Which installation does an application load? See “Loading IBM MQ libraries” on page 360.
3. Which installation is an IBM MQ command run from? See “Command association” on page 362.

Queue manager association

A queue manager is permanently associated with an installation, until you choose to change the
association with the setmqm command. You cannot associate a queue manager with an installation at
a lower command level than the current command level of the queue manager.
In Figure 10 on page 359, QM1 is associated with Inst1. The association is made by running setmqm
-m QM1 -n Inst1. When QM1 is first started, after running setmqm, if QM1 is running IBM MQ 9.1 it is
migrated to the later version. QM2 is associated with IBM MQ 9.1 because the association has not been
changed.

Loading IBM MQ libraries

The application connections to the queue managers are established by calling MQCONN or MQCONNX in the
normal way.
Which IBM MQ library an application loads depends on the configuration of the operating system loader,
and on the IBM MQ installation the queue manager is associated with. In Figure 10 on page 359, the
operating system loads the IBM MQ library from the Inst1 installation for applications 1 and 3. It
loads the IBM MQ 9.1 library for application 2. The operating system has loaded the wrong library for
application 3. Application 3 requires the IBM MQ 9.1 libraries.
Figure 11 on page 361 shows what happens to application 3. Application 3 is connecting to QM2, and QM2
is associated with the IBM MQ 9.1 installation. IBM MQ detects that the operating system has loaded the
wrong library to process calls from application 3 to QM2. IBM MQ loads the correct library from the IBM
MQ 9.1 installation. It transfers the MQCONN or MQCONNX call to the IBM MQ 9.1 library. Subsequent MQI
calls that use the connection handle returned by MQCONN or MQCONNX, call entry points in the IBM MQ 9.1
library.
If you attempt a connection to QM1 with application 2, IBM MQ returns an error; see 2059 (080B)
(RC2059): MQRC_Q_MGR_NOT_AVAILABLE.

360 Installing and migrating IBM MQ

 IBM MQ 9.1 IBM MQ 9.4
"Inst1" "Inst2"

Application Application
2 3

Load library Load library

QM2 QM1

Figure 11. Loading calls in a different library

Installing and migrating 361
 IBM MQ libraries include a routing capability that is based on the installation a queue manager is
associated with. The operating system can load a library from any IBM MQ installation, and IBM MQ
transfers MQI calls to the correct library.
The loading capability of IBM MQ libraries does not relax the restriction that an application compiled
and linked at a later release level must not directly load an IBM MQ library at an earlier release level. In
practice, as long as the operating system loads a library at the same or later level than the library the
application was compiled and linked with, IBM MQ can call any other level of IBM MQ on the same server.
For example, suppose you recompile and link an application that is to connect to an IBM MQ 9.1 queue
manager using the libraries shipped with IBM MQ 9.4. At run time the operating system must load the
IBM MQ 9.4 libraries for the application, even though the application connects to an IBM MQ 9.1 queue
manager. IBM MQ 9.4 detects the inconsistency and loads the IBM MQ 9.1 library for the application. The
same applies to any future release. If the application is recompiled and linked against a later release, then
the application must load an IBM MQ library that matches the later release, even if it continues to connect
to an IBM MQ 9.4 queue manager.
Your application might not be linked to an IBM MQ library, but instead call the operating system directly
to load an IBM MQ library. IBM MQ checks the library is from the installation that is associated with the
queue manager. If it is not, IBM MQ loads the correct library.

Special migration considerations involving loading IBM MQ libraries

You might have modified the installation of an early IBM MQ release to satisfy the requirements of a
build environment, or the IT standards in your organization. If you copied IBM MQ libraries to other
directories, or created symbolic links, you ended up with an unsupported configuration. A common IT
standard or build environment requirement is to include IBM MQ libraries in the default load path on AIX
and Linux systems. You can install IBM MQ into a directory of your own choosing, and IBM MQ can create
symbolic links in /usr and its subdirectories. If you make an IBM MQ installation primary by using the
setmqinst command, IBM MQ inserts symbolic links to the IBM MQ libraries into /usr/lib. As a result,
the operating system finds the IBM MQ libraries in the default load path, if that includes /usr/lib.
For more information, see Connecting applications in a multiple installation environment.

Command association
Examples of commands are dspmqver, setmqinst, runmqsc, and strmqm. The operating system
must find a command in an IBM MQ installation. Many commands also require a queue manager as
an argument, and assume the default queue manager if a queue manager name is not provided as a
parameter.
Unlike loading libraries, if a command includes a queue manager as a parameter, the command is not
switched to the installation that is associated with the queue manager. You must use the setmqenv
command to set up your environment correctly, so that any commands that you issue are run from
the correct installation. You can provide a queue manager as a parameter to setmqenv, to set up the
command environment for that queue manager. For more information, see Running setmqenv.
On Windows, the setmqinst command sets global environment variables, and setmqenv local
environment variables, including the PATH variable to find commands.
On AIX and Linux, the setmqinst command copies symbolic links for a subset of the commands
into /usr/bin. For more information, see “External library and control command links to primary
installation on AIX and Linux” on page 22. The setmqenv command sets up local environment variables,
including the search path to the binary folder in the installation directory.
The following code shows two examples of running setmqenv to set up the command environment for
the copy of IBM MQ that is associated with queue manager QM1.

362 Installing and migrating IBM MQ

IBM MQ for Windows.

"%MQ_INSTALLATION_PATH%\bin\setmqenv" -m QM1

IBM MQ for AIX or Linux.

. $MQ_INSTALLATION_PATH/bin/setmqenv -m QM1

Figure 12. Running setmqenv

Related concepts
Connecting applications in a multiple installation environment
“External library and control command links to primary installation on AIX and Linux” on page 22
On AIX and Linux platforms the primary installation is the one to which links from the /usr file system are
made. However, only a subset of those links created with previous releases are now made.
“Features that can be used only with the primary installation on Windows” on page 25
Some Windows operating-system features can be used only with the primary installation. This restriction
is due to the central registration of interface libraries, which might conflict as a result of multiple versions
of IBM MQ being installed.
Installation configuration file, mqinst.ini
Related tasks
“Migrating on AIX and Linux: single-stage” on page 407
Single-stage migration is the term used to describe replacing the only installation of IBM MQ on a server,
with a later release. Single stage migration is also known as upgrading in place or in place upgrade.
Single-stage migration preserves existing scripts and procedures for running IBM MQ the most. With other
migration scenarios you might change some scripts and procedures, but you can reduce the effect queue
manager migration has on users.
“Migrating on Windows: single stage” on page 381
Single-stage migration is the term used to describe replacing the only installation of IBM MQ on a server,
with a later version of the product. Single stage migration is also known as upgrading in place or in place
upgrade. Single-stage migration preserves existing scripts and procedures for running IBM MQ the most.
With other migration scenarios you might change some scripts and procedures, but you can reduce the
effect queue manager migration has on users.
Changing the primary installation
“Staging maintenance level updates on AIX” on page 287
On AIX, you can use multiple installations of IBM MQ on the same server to control the release of
maintenance level updates.
“Staging maintenance level updates on Linux” on page 297
On Linux, you can use multiple installations of IBM MQ on the same server to control the release of
maintenance level updates.
“Staging maintenance level updates on Windows” on page 313
On Windows systems, you can use multiple installations of IBM MQ on the same server to control the
release of maintenance level updates.
“Migrating IBM MQ library loading to a later version on AIX and Linux” on page 424
On AIX and Linux, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to a later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
“Migrating IBM MQ library loading to a later version on Windows” on page 396

Installing and migrating 363

 On Windows, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to the later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
Related reference
“Coexistence” on page 354
Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations. In addition to queue managers coexisting on a server, objects,
and commands must work correctly with different queue managers running at different command levels.
setmqenv
setmqinst
setmqm
strmqm -e CMDLEVEL
Related information
Dynamic-Link Library Search Order

Multiple installations and application programs

When a local application connects to a queue manager, the application needs to load the libraries from
the installation associated with the queue manager. Multiple installations introduce some complexity.

Using the setmqm command

When you use setmqm to change the installation associated with a queue manager, the libraries that need
to be loaded change.
When an application connects to multiple queue managers owned by different installations, multiple sets
of libraries need to be loaded.
Note: If you link your applications to IBM MQ libraries, the applications automatically load the appropriate
libraries when the application connects to a queue manager.

Loading IBM MQ libraries in a multi-version environment

How libraries are located depends upon your environment.
If IBM MQ is installed in the default location, existing applications continue to work as before. Otherwise,
you might need to rebuild the application or change your configuration.
The order in which libraries are searched, depends upon the platform you are using:
• Windows
– The application's directory
– The current directory
– The global and your PATH variables
• Other platforms
– LD_LIBRARY_PATH (or LIBPATH/SHLIB_PATH)
– An embedded search path (RPath)
– The default library path

364 Installing and migrating IBM MQ

Table 38. Options for loading libraries
Platform Option Benefits Drawbacks
AIX and Set/change the embedded The path is explicit in the You need to recompile and
Linux runtime search path (RPath) way the application is built link
If you move IBM MQ, you
must change RPath

AIX and Set LD_LIBRARY_PATH or Overrides RPath Depends on environment

Linux equivalent using setmqenv variables
No changes to existing
applications Possible impacts on other
applications
Easy to change if you move
IBM MQ

Windows Set PATH using setmqenv No changes to existing Depends on environment

applications variables
Easy to change if you move Possible impacts on other
IBM MQ applications

All Set the primary installation No changes to existing AIX and Linux: Relies
to IBM WebSphere MQ 7.1 applications on /usr/lib in the default
or later search path
Easy to change the primary
installation
Similar behavior to previous
versions of IBM MQ

Related concepts
“Multiple installations on AIX, Linux, and Windows” on page 17
On AIX, Linux, and Windows, it is possible to have more than one copy of IBM MQ on a system.

Mixed version cluster coexistence

A cluster can contain queue managers running at IBM MQ 9.4, and any currently supported earlier level of
the product. However new features cannot be exploited from queue managers at an earlier level.

Routing behavior in a mixed version publish/subscribe cluster

From IBM MQ 8.0, topic host routing is available for publish/subscribe clusters. The queue manager
where the object is defined, and the full repository queue managers, must be at a level that supports the
topic route hosting feature, that is IBM MQ 8.0 or later. Any queue manager in the cluster that is at an
earlier level does not adhere to the topic route hosting behavior.
When a clustered topic is defined for topic host routing (by setting the topic CLROUTE parameter to
TOPICHOST ), only queue managers at the new level are aware of the clustered topic. Older queue
managers do not receive the clustered topic definition and therefore behave as if the topic is not
clustered. This means that all queue managers that need to work in a routed publish/subscribe manner
must be at a version that supports this feature, not just the queue managers that host the routed topics.
Important notes:
• All full repositories must be at IBM MQ 8.0 or later to use this feature. If a full repository queue manager
is at an earlier version, the CLROUTE of TOPICHOST is not recognized by the full repository, and the
full repository propagates the topic definition to all queue managers in the cluster. Any pre-IBM MQ 8.0
queue managers then use the topic as if it is defined for DIRECT routing. This behavior is unsupported.

Installing and migrating 365

 • If an older queue manager defines a direct routed clustered topic with the same name as an existing
topic host routed clustered topic, the full repositories notice the conflicting definition and do not
propagate the definition.
To find out the version of each queue manager in the cluster, specify the VERSION parameter with the
DISPLAY CLUSQMGR command. If you issue this command from a queue manager with a full repository,
the information returned applies to every queue manager in the cluster. Otherwise the information
returned applies only to the queue managers in which it has an interest. That is, every queue manager to
which it has tried to send a message and every queue manager that holds a full repository.

Application compatibility and interoperability with earlier versions of IBM MQ

Connecting an application that is built against libraries shipped with a later version of IBM MQ to
an earlier version IBM MQ is not supported. Avoid building applications against a later version, and
redeploying them to a queue manager running at an earlier version, although some applications do work
in practice.
IBM MQ applications do interoperate with applications running on earlier versions of IBM MQ, as long as
they use no new function. IBM MQ clients can connect to queue managers running at an earlier version
than the client, as long as the client uses no new functions.
An IBM MQ application that uses only functions provided by an earlier version of a queue manager
can continue to send messages to the earlier version. It does not matter what version of IBM MQ an
application is built on and connected to. It can exchange messages with an application connected to an
earlier version of IBM MQ, as long as it does not use new function.
Consider these four cases; the first two cases are not supported though they might work in practice, the
last two cases are supported. The first two cases require compatibility with an earlier version of IBM MQ.
The last two cases rely on the interoperability between all versions of IBM MQ
1. Running an IBM MQ server application, built with a later version of IBM MQ, connecting to a queue
manager running on a server with an earlier version of IBM MQ installed.
2. Running an IBM MQ client application, built with a later version of IBM MQ, on a client platform with
an earlier client installation, connecting to a queue manager running on a server with a later version of
IBM MQ installed.
3. Running an IBM MQ client application, built with a later version of IBM MQ, on a client platform with
the later client installation, connecting to a queue manager running on a server with an earlier version
of IBM MQ installed.
4. Exchanging messages between an IBM MQ client or server application, connected to a queue manager
running on a server with a later version of IBM MQ installed, with applications connected to a queue
manager running on a server with an earlier version of IBM MQ installed.
Plan to avoid the first two cases, as they are not guaranteed to work all the time. If you are running an
incompatible configuration and you encounter a problem, you must rebuild your applications with the
correct level of IBM MQ. You can then continue with problem diagnosis.

Multi-installation and application loading

The loading capability of IBM MQ libraries does not relax the restriction that an application compiled
and linked at a later release level must not directly load an IBM MQ library at an earlier release level. In
practice, as long as the operating system loads a library at the same or later level than the library the
application was compiled and linked with, IBM MQ can call any other level of IBM MQ on the same server.
For example, suppose you recompile and link an application that is to connect to an IBM MQ 9.1 queue
manager using the libraries shipped with IBM MQ 9.4. At run time the operating system must load the
IBM MQ 9.4 libraries for the application, even though the application connects to an IBM MQ 9.1 queue
manager. IBM MQ 9.4 detects the inconsistency and loads the IBM MQ 9.1 library for the application. The
same applies to any future release. If the application is recompiled and linked against a later release, then
the application must load an IBM MQ library that matches the later release, even if it continues to connect
to an IBM MQ 9.4 queue manager.

366 Installing and migrating IBM MQ

Examples
1. You decide to rebuild a client application. Can you deploy it to your production environment that
contains some earlier versions of client and server platforms?
The answer is no, you must upgrade all the client workstations you deploy to, at least to the version of
the client you have built. The queue managers running on earlier versions of IBM MQ do not have to be
upgraded. In practice all the clients are likely to work, but for maintainability you must avoid running
incompatible levels of an application and the IBM MQ client.
2. You deploy some IBM MQ queue managers at a new version level. You have an existing IBM MQ
application that you use to send messages between the servers. Do you rebuild the application to
deploy it onto the new servers? Can you deploy the old version onto the new servers?
The answer is, either. You can continue to deploy the existing version of the application onto all
your servers, or you can deploy the rebuilt application onto the new servers. Either configuration
works. IBM MQ supports running the existing application on later servers and sending messages from
later application versions to earlier ones. What you must not do is to rebuild the application on the
later version and redeploy it onto both the earlier and newer servers. IBM MQ does not support
compatibility with earlier versions.

Application compatibility and interoperability with later versions of IBM MQ

IBM MQ applications run against later versions of a queue manager without recoding, recompiling, or
relinking. You can connect an application that is built against libraries shipped with an earlier version of
IBM MQ to a queue manager running at a later version of IBM MQ.
If you upgrade a queue manager to a later version, existing applications built against its earlier version
work without change. Exceptions are noted in “Changes that affect migration” on page 337. Likewise
applications connected to the IBM MQ Client, run against later versions of the client without recoding,
recompiling, or relinking. You can deploy client applications built against earlier versions of the IBM MQ
Client libraries to connect using later versions of the libraries.
Consider these four cases; the first two cases are not supported though they might work in practice, the
last two cases are supported. The first two cases rely on the compatibility of a later version of IBM MQ
with applications built against earlier versions. The last two cases rely on the interoperability between all
versions of IBM MQ.
1. Running an IBM MQ server application, built with a later version of IBM MQ, connecting to a queue
manager running on a server with an earlier version of IBM MQ installed.
2. Running an IBM MQ client application, built with a later version of IBM MQ, on a client platform with
an earlier client installation, connecting to a queue manager running on a server with a later version of
IBM MQ installed.
3. Running an IBM MQ client application, built with a later version of IBM MQ, on a client platform with
the later client installation, connecting to a queue manager running on a server with an earlier version
of IBM MQ installed.
4. Exchanging messages between an IBM MQ client or server application, connected to a queue manager
running on a server with a later version of IBM MQ installed, with applications connected to a queue
manager running on a server with an earlier version of IBM MQ installed.
You might change the operating environment as a prerequisite of migrating to a new level of queue
manager. The operating environment changes, rather than changes in IBM MQ itself, might require
application change, recompilation, or relinking. Sometime the operating environment change affects only
the development environment, and the operating environment supports applications built at an earlier
level. In which case, you might be able to run existing applications built at the older level of the operating
environment. You might not be able to build any new applications until the operating environment is
upgraded.
In the future, after you have migrated queue managers and clients to the latest release level, consider
changing your applications to take advantage of new capabilities.

Installing and migrating 367

 Compatibility between different versions of an IBM MQ client and a queue manager
Any supported version and release of an IBM MQ client can connect to any supported version and release
of an IBM MQ queue manager. Supported IBM MQ clients are all clients included with the main MQ
product. This includes IBM MQ Internet Pass-Thru (MQIPT). The MQI channel is automatically configured
to the latest version that both the client and server support. If the client and server are different versions,
the client application must use only the functions in the earlier version.
The compatibility between clients and queue managers applies only to the version and release (V.R) of
the product. The statement of compatibility does not necessarily apply to the modification and fix pack
level (M.F) of the product.
If there are known problems at a specific V.R.M.F of the product, upgrade to a more recent fix pack for
the same Version.Release.
When you upgrade a queue manager to a different version, you automatically upgrade IBM MQ libraries.
The libraries are used by IBM MQ client and server applications running on the same server as the
queue manager. To access new functions from remote clients, you must also upgrade the IBM MQ client
installation on remote workstations. The IBM MQ client includes the IBM MQ client libraries.
Remote clients that have not been upgraded continue to work with an upgraded queue manager. In rare
cases, the behavior of the client application might change. See “Changes that affect migration” on page
337.
Remote clients that are connected to upgraded queue managers can use the new functions in the release.
If an upgraded remote client is connected to a queue manager that has not been upgraded, it must
not use new functions. In rare cases, the behavior of the client might change. See “Changes that affect
migration” on page 337.
You can generally assume that upgrading the IBM MQ client does not require you to recompile or relink
the client application. You can also continue to use the same connection to the queue manager. If
changes are required, they are identified in “Migrating a queue manager on Windows” on page 378, for
the particular migration path and platform you are concerned with.
The Client Channel Definition Table (CCDT) is an interface to customize the connection between an IBM
MQ client and a queue manager. Entries in the tables are client connections, which are defined using a
queue manager. The version of a CCDT is the version of the queue manager used to define the client
connections. If an IBM MQ client uses CCDT to connect to a queue manager, the CCDT can be at a version
greater than, less than, or equal to that of the client.
You can connect to a queue manager with an earlier IBM MQ client or an earlier CCDT. If you are using
a CCDT, and you plan to use new client channel configuration options, such as shared conversations, you
must upgrade the CCDT, and therefore the IBM MQ client installation, to the new version.

MQ clients: Client Channel Definition Table (CCDT)

You can connect a supported IBM MQ client application to any supported level of queue manager. If a
client uses CCDT to connect to a queue manager, the CCDT can be at a version greater than, less than, or
equal to that of the client.
When a client uses a CCDT file that was generated using a newer version of IBM MQ, only channel
attributes within the CCDT that were available at the client's IBM MQ version are considered during
negotiation with the queue manager. Channel attributes present in the CCDT that were added in newer
versions of IBM MQ will be ignored by older clients.

Version of originating queue manager for a CCDT

Before IBM MQ 9.0, clients can use a CCDT built by the same or earlier version queue manager, but there
was previously a restriction on clients using a CCDT built by a later version queue manager. However, this
restriction is removed in IBM MQ 9.0.
From IBM MQ 9.0, if a client uses a CCDT, it can use a CCDT built by a later version queue manager, as well
as a CCDT built by the same, or earlier version of queue manager.

368 Installing and migrating IBM MQ

The same restriction on the use of CCDTs originating from later version queue managers is also removed
in IBM MQ 8.0, and earlier versions, by APARs IT10863 and IT11547. for more information, see the
technote MQ 7.x, MQ 8.0, MQ 9.0, MQ 9.1, MQ9.2, and MQ9.3 compatibility with previous versions -
including usage of CCDT files, JMS .bindings, SSL/TLS.

Common migration scenarios

If, for example, you upgrade a queue manager from an earlier release to a later release, and you do not
create new CCDTs for its clients, the clients connect to the later release queue manager without any
changes being required. Client behavior might change as a result of changes to the queue manager.
Another common migration scenario is to update some queue managers and some clients to a later
release, leaving other queue managers and clients at the earlier release. In this scenario, you want to
update the CCDT for the IBM MQ clients to the same release as the queue managers to which they
connect, so that those clients can fully use the function in the later release. The new clients can also
connect to the earlier release queue managers. Existing clients connect to queue managers in both
releases. In order that the clients in the later release can use the new function in that release, you must
deploy a CCDT that has been generated by a queue manager in that new release. Clients in the earlier
release can continue to use the CCDT for that earlier release. Both sets of clients can connect to both sets
of queue managers, regardless of the CCDT they are using.
Related concepts
Client channel definition table
Web addressable access to the client channel definition table
Related tasks
Accessing client-connection channel definitions

MQ clients: Client configuration stanzas moved into a different configuration file

Client configuration information is moved from existing configuration stanzas into a new configuration file,
mqclient.ini.
Moving client configuration information affects existing settings. For example:
• Set the TCP KeepAlive attribute for client connections in mqclient.ini. For example:

TCP:
KeepAlive = Yes

An existing setting in qm.ini is ignored.

• Set ClientExitPath in mqclient.ini. For example:

ClientExitPath:
ExitsDefaultPath=/var/mqm/exits
ExitsDefaultPath64=/var/mqm/exits64

An existing setting in mqs.ini is moved to the client configuration file when you upgrade the client. If
you add values to mqs.ini, they are ignored.
• Set JavaExitsClasspath in mqclient.ini.

Do not continue to use the Java system property com.ibm.mq.exitClasspath. Existing

settings continue to work, but they are deprecated. The setting in mqclient.ini has precedence over
the Java system property.
See Location of the client configuration file for information on the possible locations of this file.
Related tasks
Assigning channel exits for IBM MQ classes for JMS
IBM MQ MQI client configuration file, mqclient.ini
Related reference
The IBM MQ classes for JMS configuration file

Installing and migrating 369

 Supported IBM MQ client: Default behavior of client-connection and server-connection channels
The default for client and server connections is to share an MQI channel. You use the SHARECNV (share
conversations) parameter to specify the maximum number of conversations that can be shared over a
particular TCP/IP client channel instance.
The possible values are as follows:
SHARECNV(2) to SHARECNV(999999999)
Each of these values specifies the number of shared conversations. If the client-connection
SHARECNV value does not match the server-connection SHARECNV value, then the lowest value
is used. The default value is SHARECNV(10), which specifies 10 threads to run up to 10 client
conversations per channel instance. However, on distributed servers there are performance issues
with SHARECNV channels that can be eased by using SHARECNV(1). See Tuning client and server
connection channels.
SHARECNV(1)
This value specifies no sharing of conversations over a TCP/IP socket. Performance on distributed
servers is similar to that for a value of 0. Client heartbeating (whether in an MQGET call or not) and
read ahead are available, and channel quiescing is more controllable.
SHARECNV(0)
This value specifies no sharing of conversations over a TCP/IP socket. Only use a value of 0 if you have
existing client applications that do not run correctly when you set SHARECNV to 1 or greater.
For all SHARECNV values of 1 or greater, the channel supports the following features:
• Bi-directional heartbeats
• Administrator stop-quiesce
• Read-ahead
• Asynchronous-consume by client applications

Heartbeats
Heartbeats can flow across the channel at any time in either direction. If you use SHARECNV(0),
heartbeats flow only when an MQGET call is waiting.

Channel exits
The behavior of a client or server connection channel exit changes when the channel is sharing
conversations (that is, when you set SHARECNV to a value greater than 1). It is unlikely, but possible,
that the change affects the behavior of existing exits. The change is as follows:
• Send or receive exits can alter the MQCD structure on an MQXR_INIT call. The effect of these exits
differs, depending on whether the conversation is shared with other conversations on the same
channel:
– If the MQCXP SharingConversations field passed to the exit instance is set to FALSE, this exit
instance is the first, or only, conversation on the channel instance. No other exit can be changing the
MQCD at the same time, and changes that are made to the MQCD can affect the way that the channel
runs.
– If the MQCXP SharingConversations field passed to the exit instance is set to TRUE, this exit
instance is a subsequent conversation. It is sharing the channel instance with other conversations.
Changes made to the MQCD in the exit instance are retained in the MQCD but do not affect the way the
channel runs.
• Send, receive, and security exit instances can alter the MQCD, when the MQCXP
SharingConversations field is set to TRUE. Exit instances on other conversations might be changing
the MQCD at the same time. Updates written by one exit instance can be overwritten by another
instance. It might be necessary to serialize access to the MQCD across these different exit instances to
maintain the consistency of fields in MQCD.

370 Installing and migrating IBM MQ

Updating MQCD when the SharingConversations field is set to TRUE does not affect the way the
channel runs. Only alterations made when the MQCXP SharingConversations field is set to FALSE, on
an MQXR_INIT call, change channel behavior.
Related concepts
Channel-exit programs for MQI channels
Related tasks
Using sharing conversations
Using read ahead
Stopping MQI channels
Tuning client and server connection channels
Related reference
HeartbeatInterval (MQLONG)
SharingConversations (MQLONG)
ALTER CHANNEL
The Asynchronous consume sample program

GSKit version compatibility

The stash files that you generate with IBM MQ 9.0.0 Fix Pack 1, or later must be compatible with any
applications and other IBM MQ installations.
For the version of IBM Global Security Kit (GSKit) for IBM MQ 9.0.0 Fix Pack 1 or later, the stash file
format that is used when you generate an .sth file to stash the key database password is different from
earlier versions of GSKit. Stash files that are generated with this version of GSKit are not readable by
earlier versions of GSKit. To ensure that stash files that are generated with IBM MQ 9.0.0 Fix Pack 1, or
later, are compatible with your applications and other IBM MQ installations, you must update to a version
of IBM MQ that contains a compatible version of GSKit. The following fix packs contain a compatible
version of GSKit:
• 7.5.0.8
• 8.0.0.6
• 9.0.0.1
If you cannot update your applications or other IBM MQ installations, you can create a stash file that is
compatible with an earlier version with the runmqakm command. Specify the -v1stash parameter when
the runmqakm command is run with the -stash or -stashpw parameter to create a stash file that is
compatible with earlier versions of IBM MQ.

Migrating from one Continuous Delivery release to another

An overview of how you migrate from one Continuous Delivery (CD) release to another.

Before you begin

If you want to migrate replicated data queue managers, follow the instructions in “Migrating replicated
data queue managers” on page 460.
1. Back up your existing IBM MQ environment. This is required in case you need to revert to your current
CD release of IBM MQ.
Important: Once the new installation is started, all of the existing IBM MQ objects will be migrated to
the new modification level. If you do not back up your system, you cannot revert the objects to their
previous level without completely uninstalling, and restoring a backup you made before you carried
out the migration.

Copy the qm.ini file and the registry entries.

For more information about backing up your system, see Backing up and restoring IBM MQ queue
manager data.

Installing and migrating 371

 2. Use the dmpmqcfg command to save the current configuration details to a text file.

Procedure
1. Stop all of the IBM MQ processes for the installation being migrated.
2. Upgrade the existing CD installation by using one of the following methods:

• On Windows and AIX, upgrade IBM MQ by installing the new CD

installation in the same location as the existing installation.
For more information about upgrading your CD installation on Windows, see “Upgrading an IBM MQ
installation on Windows” on page 332.
For more information about upgrading your CD installation on AIX, see “Installing IBM MQ server on
AIX” on page 42.

• On Linux, if your existing CD installation is at IBM MQ 9.2.1 or later, you can upgrade
IBM MQ by installing the new CD installation in the same location as the existing installation.
For more information about upgrading your CD installation on Linux, see “Upgrading an IBM MQ
installation on Linux” on page 321.
• Uninstall the existing CD installation and then install the new CD modification level onto the same
system.
Note that uninstalling the existing installation does not remove the object definitions from the
system. The object definitions remain in place.
3. Start the queue manager.

strmqm QmgrName

When you first start a queue manager after migration to the new CD level:
• Any new attributes for existing objects are set to their default values.
• Any new default objects are created.
• Queue manager objects are migrated to the new modification level.
Note: If you have saved your current configuration details in a text file, that file can be used to
duplicate these objects in the newly created queue manager after it has been created, if you installed
the new version onto a different system.
See the runmqsc command for instructions on how you can do this.
Related concepts
IBM MQ release types and versioning

Migrating IBM MQ on Windows

IBM MQ migration tasks associated with Windows platforms are grouped in this section.

Before you begin

If you are migrating to IBM MQ 9.4 or later from IBM WebSphere MQ 7.5 or earlier, you must first migrate
to an interim version. See Migration paths.

Important: From IBM MQ 9.4.0, AMQP channels no longer support CMS key
repository files. If you are migrating a queue manager with an AMQP configuration to IBM MQ 9.4.0 or
later, and your queue manager is currently configured with a CMS keystore, you must convert it to PKCS12
format before proceeding with the migration. For more information on how to perform this conversion, see
SSL/TLS support in Securing AMQP Clients.

372 Installing and migrating IBM MQ

About this task
This topic lists the various steps you need to take to migrate to, or migrate from, the latest version of the
IBM MQ product.
See also “Migrating from one Continuous Delivery release to another” on page 371, if you are migrating a
Continuous Delivery release of the product.

Procedure
• For information about creating a migration plan, see “Planning to migrate IBM MQ to a later version on
Windows” on page 373.
• For information about migrating a queue manager from an earlier version to the latest version, see
“Migrating a queue manager to a later version on Windows” on page 378.
• For information about reverting a queue manager to an earlier version, see “Reverting a queue
manager to an earlier version on Windows” on page 393.
• For information about migrating an IBM MQ MQI client to the latest version, see “Migrating an IBM MQ
MQI client to a later version on Windows” on page 395.
• For information about converting a single instance queue manager to a multi-instance queue manager,
see Converting a single instance to a multi-instance queue manager on Windows.
• For information about reverting a multi-instance queue manager to a single instance queue manager,
see Reverting to a single-instance queue manager on Windows.
• For information about migrating IBM MQ library loading to the latest version, see “Migrating IBM MQ
library loading to a later version on Windows” on page 396.
• For information about migrating MQ Telemetry to the latest version, see “Migrating MQ Telemetry on
Windows” on page 400.
• For information about migrating an MSCS configuration to the latest version, see “Migrating an MSCS
configuration on Windows” on page 401.
• For information about Migrating logs to an Advanced Format disk, see “Migrating logs to an Advanced
Format disk on Windows” on page 403.
Related concepts
“Migration concepts and methods” on page 340
An overview of the various concepts and methods for migrating from one release of the product to
another.
Related tasks
“Migrating IBM MQ on AIX and Linux” on page 404
Migration tasks associated with AIX and Linux platforms are grouped in this section.
“Migrating IBM MQ on IBM i” on page 429
IBM MQ migration tasks associated with IBM i are grouped in this section.
Related reference
“Changes that affect migration” on page 337

Planning to migrate IBM MQ to a later version on Windows

Before migrating IBM MQ to a later version on Windows, review the system requirements information, and
the information about any changes that might affect migration, then create a migration plan.

Before you begin

If there are concepts about migration you do not understand, see “Migration concepts and methods” on
page 340.
If you are migrating to IBM MQ 9.4 or later from IBM WebSphere MQ 7.5 or earlier, you must first migrate
to an interim version. See Migration paths.

Installing and migrating 373

 About this task
Use the following steps as a guide to creating a migration plan.

Procedure
1. Review the IBM MQ system requirements for the later version of the product.
See System Requirements for IBM MQ.See “IBM MQ components and features” on page 6 and
“Where to find downloadable installation images” on page 9.
2. Decide whether to run the earlier version and the later version of the product on the same server, and
also which migration method you want to use.
Choices are single-stage migration, side-by-side migration, or multi-stage migration. See “Migration
methods on IBM MQ for Multiplatforms” on page 347.
3. Review all the changes in IBM MQ that affect you.
See “Changes that affect migration” on page 337.
4. Review performance changes.
See MQ Performance documents.
5. Review the readme file for the later version of IBM MQ.
See IBM MQ, WebSphere MQ, and MQSeries product readmes.
6. Plan the sequence and timing of queue manager migrations.
• If the queue manager is part of a queue manager cluster, you must migrate the queue managers
that are full repositories first.
• If the queue manager is part of a high availability cluster, plan the migration to minimize downtime
and maximize availability; see “Migrating a queue manager in a high-availability configuration” on
page 457.
7. Plan to migrate your queue manager to the later version.
See “Migrating a queue manager to a later version on Windows” on page 378.
Backing up queue manager data is part of the queue manager migration task. An alternative approach
is to install and configure a new server, then test the later version with a new queue manager on the
new server. When you are ready to go into production on the later version, copy the queue manager
configuration and data to the new server.
8. Plan to update any manual or automated procedures you have written with changes to messages and
codes.
A suffix letter, indicating the severity of a message (I, W, E, S or T) is appended to IBM MQ diagnostic
(AMQ) messages. Existing scripts looking for error codes without the severity will fail. For example,
existing scripts looking for error matching to AMQ7468 will fail. You must update the scripts to look
for error codes with the severity suffix added (for example, AMQ7468I). For more information, see
IBM MQ messages on Multiplatforms.
9. Decide on what regression tests to perform before putting the queue manager into production on
the later version. Include in your regression tests the procedures and applications you identified in
previous steps.
10. Plan to migrate your IBM MQ MQI client installations to the later version.
11. Plan to migrate your client and server applications to use new functions in the later version.
12. Decide which downloadable images you require for the migration.
For more information, see “Where to find downloadable installation images” on page 9.

Migration considerations for IBM MQ 8.0 or later on Windows

From IBM MQ 8.0, a number of changes were made for IBM MQ for Windows. You must understand these
changes before planning any migration tasks for IBM MQ 8.0 or later on Windows.

374 Installing and migrating IBM MQ

Installing a single copy of the product
If you have an existing previous version of the product on your system, and want to upgrade to the latest
version, you have various options. You can either:
• Uninstall the previous version and then install the latest version,
• Install the new copy alongside the currently installed one and uninstall the original at a later time. See
“Installing the product alongside an existing version” on page 375, or
• Perform a migration installation, electing to replace the currently installed version when prompted.
After you have installed the product, start each queue manager and its data migration takes place. This
includes the migration of queue managers from 32-bit to 64-bit.

Installing the product alongside an existing version

If you want to install another version of the product alongside your existing product you can do so. See
“Multiple IBM MQ installations” on page 352 and “Migrating on Windows: side-by-side” on page 386 for
further information.
When you install the new version of the product, run the setmqm command to associate the queue
managers with the new installation.
Start each queue manager in turn and its data migration takes place.

Upgrading one of a pair of (or more) installations

If you already have, for example, an IBM MQ 8.0 installation and an IBM MQ 9.0 installation on a machine,
upgrading the IBM MQ 8.0 installation to IBM MQ 9.0 requires the following additional step.
When you start the IBM MQ 9.0 installer, you are asked whether you want to Install a new instance or
Maintain or upgrade an existing instance.
However, only the other IBM MQ 9.0 installation, or installations, are displayed; not the IBM MQ 8.0
installation in the selection box. At this point, select Install a new instance.
After the splash screen has been displayed, a second panel appears, which lists any older installations
that you can upgrade to IBM MQ 9.0 using the IBM MQ 9.0 installer.
On this panel, select Upgrade 8.0.0.n Installation 'Installation m', then click Next.

Change of digital signature algorithm

The IBM MQ programs and installation image are digitally signed on Windows to confirm that they are
genuine and unmodified.
In older releases before IBM MQ 8.0, the product was signed using the SHA-1 with RSA algorithm.
From IBM MQ 8.0, the SHA-256 with RSA algorithm is used. Some older versions of Windows do not
support the new digital signature algorithm, but those versions are not supported by IBM MQ 8.0 or later.
See “Hardware and software requirements on Windows systems” on page 168, and ensure that you
install IBM MQ 8.0 or later on a supported version of Windows.

Existing applications
All applications that were built with previous versions of the product continue to work in IBM MQ 8.0 or
later with a 64 bit queue manager.
All applications using the C++ object interface need to be rebuilt; applications using the C interface are
not affected.

Installing and migrating 375

 Exits
Queue manager exits on Windows 64-bit operating systems must be compiled as 64-bit exits. Any 32-bit
queue manager exits must be recompiled before they can be used with a 64-bit queue manager. If you try
to use a 32-bit exit with a 64-bit queue manager on IBM MQ 8.0 or later, an AMQ9535 "invalid exit" error
message is issued.

Clients
32-bit client applications can connect transparently to queue managers from all supported versions of the
product. This includes 64-bit IBM MQ 8.0 or later.

Samples
From IBM MQ 8.0, the samples for the C and C++ languages are compiled as 64-bit.
Related concepts
“Hardware and software requirements on Windows systems” on page 168
Check that the server environment meets the prerequisites for installing IBM MQ for Windows and install
any prerequisite software that is missing from your system.
Related reference
Windows: changes from IBM MQ 8.0
Directory structure on Windows systems

Program and data directory locations on Windows

The installation location for IBM MQ program binary and data files on Windows depends on the IBM MQ
version you are installing, and whether this is the first time IBM MQ is being installed.

Windows program directory security permissions

From IBM MQ 9.1.0 Fix Pack 2 and IBM MQ 9.1.2, the IBM MQ installer on Windows sets additional
permission restrictions as part of the security configuration of the MQ installation directories. The logic
that does this is run at installation, upgrade, modification, and fix pack installation time.
You might find that, due to the increased security, you are unable to do certain things exactly the same
way you used to do them. For example:
• An MQ Administrator (who is not also a member of the Administrators group) can no longer edit or
recompile the sample programs in the Tools subdirectory. If you wish to do this, take a copy of the
directory (or the portions you are interested in) and change your copies of the build scripts to reflect the
new location.
In normal use, however, you should be unaware of the change, except for the little extra time required by
the installer to make the changes. During this period the message Initializing security... will be
displayed. A similar short pause will occur when installing the fix pack files or applying a patch.
The update of the security writes a log (amqidsec-<Installationname>.txt) to the TEMP directory
on the machine. If you see the main install failing in custom action 'iwiLaunchAmqidsec', you should
consult this file.

First-time installations
When you install IBM MQ for the first time, you can accept default installation locations. You can also
select the custom installation option by choosing the location for the IBM MQ binary files, and the location
for the IBM MQ data and logs.
From IBM MQ 8.0, the default location for the program binary files is different from the default location for
the data files.

376 Installing and migrating IBM MQ

Table 39. Default program and data directory locations on different versions of IBM MQ on Windows
IBM MQ version IBM MQ program binary files IBM MQ data files location
installation location
IBM WebSphere MQ 7.5 Program and data files are in one location: C:\Program Files
(x86)\IBM\WebSphere MQ
IBM MQ 8.0 C:\Program C:\ProgramData\IBM\MQ
Files\IBM\WebSphere MQ
IBM MQ 9.0 and later C:\Program Files\IBM\MQ C:\ProgramData\IBM\MQ

Subsequent installations and reinstallations

After the data directory is specified, during the installation process of any installation, it cannot be
changed for subsequent installations. IBM MQ is only installed as a 64-bit version when it is installed on a
64-bit operating system.
For IBM MQ 9.0 and later, the default data directory is C:\ProgramData\IBM\MQ, unless a version of
the product was previously installed, in which case the new installation continues to use the existing data
directory.

Existing IBM MQ 9.0 installation

The default program and data directory locations are the same for IBM MQ 9.0 and later versions.
Therefore you do not need to change the specification of the program and data directories when
upgrading from IBM MQ 9.0 to a later version.

Existing IBM MQ 8.0 installation

Three upgrade paths are possible:
• Uninstall IBM MQ 8.0 first and then install IBM MQ 9.0 or later.
• Upgrade IBM MQ 8.0 at the beginning of the IBM MQ 9.0 or later installation process, without first
uninstalling the earlier version.
• Install IBM MQ 9.0 or later alongside IBM MQ 8.0 and then uninstall IBM MQ 8.0.
When IBM MQ 8.0 is installed, the product binary files are put by default into C:\Program
Files\IBM\WebSphere MQ and the product data and logs are put by default into
C:\ProgramData\IBM\MQ.
When you uninstall IBM MQ 8.0, information about the location of the data directory is left in the registry.
After uninstalling IBM MQ 8.0 and before installing IBM MQ 9.0 or later, you can run the ResetMQ.cmd
script to tidy up files and data left behind by the uninstallation process.
Important: You should use this script with caution. ResetMQ.cmd can remove the existing queue
manager configuration. For more information, see Clearing IBM MQ installation settings.
Installing IBM MQ 9.0 or later after uninstalling IBM MQ 8.0
After uninstalling IBM MQ 8.0, IBM MQ 9.0 or later is installed using the same installation name but
using the IBM MQ 9.0 and later default program binary files location C:\Program Files\IBM\MQ.
That is, the program files change location after the upgrade.
Optional: You can use the custom installation option to modify the installation path, including
modifying it back to C:\Program Files (x86)\IBM\WebSphere MQ.
The default data path is C:\ProgramData\IBM\MQ.
Upgrading IBM MQ 8.0 at the beginning of the IBM MQ 9.0 or later installation process
If you install IBM MQ 9.0 or later without uninstalling IBM MQ 8.0 and choose to upgrade the IBM MQ
8.0 installation, the new program binary files replace the IBM MQ 8.0 binary files so, by default, the

Installing and migrating 377

 new binary files are in C:\Program Files (x86)\IBM\WebSphere MQ. The existing data path is
kept so, by default, the data path is C:\ProgramData\IBM\MQ.
Installing IBM MQ 9.0 or later to coexist with IBM MQ 8.0
If you install IBM MQ 9.0 or later alongside IBM MQ 8.0, a unique path is chosen, which by default
is C:\Program Files\IBM\MQ. The existing data path is kept so, by default, the data path is
C:\ProgramData\IBM\MQ.

Existing IBM WebSphere MQ 7.5 or IBM WebSphere MQ 7.1 installation

If you are migrating to IBM MQ 9.4 or later from IBM WebSphere MQ 7.5 or earlier, you must first migrate
to an interim version. See Migration paths.
For IBM WebSphere MQ 7.5 or IBM WebSphere MQ 7.1, the interim version you use can be either IBM MQ
9.0 or IBM MQ 8.0. For information about specifying program and data directories when upgrading, see
either of the following topics:
• Program and data directory locations on Windows in the IBM MQ 9.0 product documentation.
• Windows: Program and data directory locations in the IBM MQ 8.0 product documentation.
Related concepts
“Migration concepts and methods” on page 340
An overview of the various concepts and methods for migrating from one release of the product to
another.
“Hardware and software requirements on Windows systems” on page 168
Check that the server environment meets the prerequisites for installing IBM MQ for Windows and install
any prerequisite software that is missing from your system.
Related information
Clearing IBM MQ installation settings

Migrating a queue manager on Windows

The procedures for migrating a queue manager to a later version of the product, and for restoring a queue
manager to an earlier version of the product are detailed in this section.
Related tasks
“Migrating a queue manager on AIX and Linux” on page 406
The procedures for migrating a queue manager to a later version of the product, and for restoring a queue
manager to an earlier version of the product are detailed in this section.
“Migrating a queue manager to the latest version on IBM i” on page 432
Follow these instructions to migrate a queue manager on IBM i to the latest MQ version.

Migrating a queue manager to a later version on Windows

On Windows platforms, follow these instructions to migrate a queue manager from an earlier version to a
later version of IBM MQ.

Before you begin

If you have installed early support program code on the server, you must delete all the queue managers
created with the installation. Uninstall the code before proceeding with installing the production level
code.
1. Create a migration plan; see “Planning to migrate IBM MQ to a later version on Windows” on page 373.
2. Review the IBM MQ system requirements for the latest version, including information about the
versions of Windows that IBM MQ supports. See System Requirements for IBM MQ.
3. Back up your system before you install a later version of IBM MQ over an earlier version. Once you
have started a queue manager you cannot revert to the previous version. If you must restore the
system, you cannot recover any work, such as changes to messages and objects, performed by the

378 Installing and migrating IBM MQ

 later version of IBM MQ. For more information about backing up your system, see Backing up and
restoring IBM MQ queue manager data.
4. Review any other installed SupportPacs for their applicability to the later version.
5. If you are running on a server with multiple IBM MQ installations, you must identify the installation.
Make sure that the commands you enter run against the correct installation; see setmqenv.

About this task

To run a command, the operating system must find the command in an IBM MQ installation. For some
commands, you must run the command from the installation that is associated with the correct queue
manager. IBM MQ does not switch commands to the correct installation. For other commands, such as
setmqinst, you can run the command from any installation that has the later version of the product
installed.
If an earlier version of the product is installed, the command that is run is the command for that version,
unless the search path is overridden by a local setting. You can override the search path by running
setmqenv. You must set the correct path to run a command. If you have set a primary installation, the
command that is run is the copy in the primary installation, unless you override the selection with a local
search path.

Procedure
1. Log in as a user in group mqm.
2. Stop all applications using the IBM MQ installation.
If you use the Managed File Transfer (MFT) component, ensure that any MFT agents have finished all of
the file transfers that they were engaged in. There should be no incomplete transfers associated with
the agents, and their SYSTEM.FTE.STATE queues should contain no messages.
3. End all the activity of queue managers associated with the IBM MQ installation.
a) Run the dspmq command to list the state of all the queue managers on the system.
Run either of the following commands from the installation that you are updating:

dspmq -o installation -o status

dspmq -a

dspmq -o installation -o status displays the installation name and status of queue
managers associated with all installations of IBM MQ.
dspmq -a displays the status of active queue managers associated with the installation from
which the command is run.
b) Use the MQSC command DISPLAY LSSTATUS to list the status of listeners associated with a
queue manager, as shown in the following example:

echo "DISPLAY LSSTATUS(*) STATUS" | runmqsc QmgrName

c) Run the endmqm command to stop each running queue manager associated with this installation.
-c
endmqm -w QmgrName

-i
-p

The endmqm command informs an application that the queue manager it is connected to is
stopping; see Stopping a queue manager.
For the maintenance to proceed, applications must respond to an endmqm command by
disconnecting from the queue manager and releasing any IBM MQ libraries they have loaded. If

Installing and migrating 379

 they do not, you must find another way to force applications to release IBM MQ resources, such as
by stopping the applications.
You must also stop applications that are using the client libraries that are part of the installation.
Client applications might be connected to a different queue manager, running a different
installation of IBM MQ. The application is not informed about queue managers in the current
installation being shut down.
Any applications that continue to have IBM MQ shared libraries from the installation loaded prevent
you applying IBM MQ maintenance. An application might disconnect from a queue manager, or be
forcibly disconnected, but keep an IBM MQ shared library loaded.
Note: “Applying maintenance level updates to multi-instance queue managers on Windows” on
page 316 describes how to apply maintenance to a multi-instance queue manager. A multi-instance
queue manager can continue to run on one server, while maintenance is applied to another server.
d) Stop any listeners associated with the queue managers, using the command:

endmqlsr -m QMgrName

4. Back up the queue manager.

Take copies of all the queue manager's data and log file directories, including all subdirectories, and
also the qm.ini file and the registry entries. For more information, see Backing up and restoring IBM
MQ queue manager data.
5. Stop the IBM MQ Service and exit the Service icon application.
6. Optional: If you are doing a single stage migration, optionally uninstall the current version of the
product.
Note, that you carry out this step only if you are doing a single stage migration; see “Migrating on
Windows: single stage” on page 381.
7. Install the later version of IBM MQ.
On Windows, you can do this either by using the Installation Launchpad or by using the msiexec
command. For more information, see:
• “Modifying a server installation using the Installation Launchpad” on page 201
• “Modifying a server installation silently using msiexec” on page 202
8. Reenter domain, user ID, and password information
When the installation of the latest version completes, the Prepare IBM MQ Wizard starts automatically.
Where UAC is enabled: If you rerun the Prepare IBM MQ Wizard, ensure that the wizard is run with
Administrator privilege, otherwise the wizard might fail.
9. Start the queue manager.

strmqm QmgrName

When you first start a queue manager after migration:

• Any new attributes for existing objects are set to their default values.
• Any new default objects are created.
• Queue manager data is migrated.
Important: Do not use the -c option to start the queue manager, unless you explicitly want to reset or
re-create the default system objects.
You must start IBM MQ before you start any listeners.

380 Installing and migrating IBM MQ

What to do next
Complete the tasks in your migration plan, such as verifying the new code level and deploying new
functions such as automatically restarting client connections.
If you are using publish/subscribe, you must migrate the publish/subscribe broker.
If the queue manager is a member of a queue manager cluster, migrate the other members of the cluster.
Important: You must migrate the publish/subscribe broker state before you migrate your IBM MQ system
to IBM MQ 8.0 or later, because broker publish/subscribe migration is not supported in IBM MQ 8.0, or
later.
Related concepts
“Where to find downloadable installation images” on page 9
You download installation images for IBM MQ from Passport Advantage, Fix Central. A number of IBM
MQ components including fix packs, CSUs, clients, and the resource adapter are also available for
downloading from Fix Central and elsewhere.
“Queue manager migration” on page 343
After upgrading an installation, queue manager migration might be required. Migration takes place when
you start a queue manager. You can remove an upgrade before you have started a queue manager.
However, if you remove the upgrade after a queue manager has been started, the queue manager will not
work.
Related tasks
“Configuring IBM MQ with the Prepare IBM MQ Wizard” on page 194
The Prepare IBM MQ Wizard helps you to configure IBM MQ with a user account for your network. You
must run the wizard to configure the IBM MQ Service before you can start any queue managers.
“Migrating a queue manager in a high-availability configuration” on page 457
High-availability configurations of queue managers can increase the availability of IBM MQ applications. If
a queue manager, or server fails, it is restarted automatically on another server. You can arrange for IBM
MQ MQI client applications to automatically reconnect to the queue manager. Server applications can be
configured to start when the queue manager starts.
“Migrating a queue manager cluster” on page 451
You can migrate queue managers in a cluster all at once, or one at a time, which is called a staged
migration. Migrate full repository queue managers in a cluster before partial repository queue managers.
You must consider what the effect is of migrating some queue managers in a cluster, before all the queue
managers are migrated.
“Maintaining and migrating IBM MQ” on page 275
Maintenance, upgrade, and migration have three distinct meanings for IBM MQ. The definitions are
described here. The following sections describe the various concepts associated with migration, followed
by the various tasks needed; these tasks are platform-specific where needed.
“Migrating IBM MQ” on page 336
Migration is the conversion of programs and data to work with a new code level of IBM MQ. Some
types of migration are required, and some are optional. Queue manager migration is never required after
applying a maintenance level update, that does not change the command level. Some types of migration
are automatic, and some are manual. Queue manager migration is typically automatic and required after
releases and manual and optional after a maintenance level upgrade that introduces a new function.
Application migration is typically manual and optional.
“Upgrading IBM MQ” on page 320
Upgrading is the process of taking an existing IBM MQ installation and upgrading to a new level of code.
Related information
IBM MQ - SupportPacs by Product

Migrating on Windows: single stage

Single-stage migration is the term used to describe replacing the only installation of IBM MQ on a server,
with a later version of the product. Single stage migration is also known as upgrading in place or in place

Installing and migrating 381

 upgrade. Single-stage migration preserves existing scripts and procedures for running IBM MQ the most.
With other migration scenarios you might change some scripts and procedures, but you can reduce the
effect queue manager migration has on users.

Before you begin

These topics guide you in deciding what other tasks you must perform to migrate queue managers and
applications to the later version. For the precise sequence of commands to upgrade a queue manager to
the later version, do the migration task for the platform you are interested in. All the tasks are listed by
platform in the links at the end of this topic. As part of the queue manager migration task, back up your
existing queue manager data. Even on a multi-installation server, queue managers cannot be restored to a
previous command level after migration.
Attention: From IBM MQ 9.0, the ccsid_part2.tbl file replaces the existing ccsid.tbl file,
used in previous versions of the product, to supply additional CCSID information.
The ccsid_part2.tbl file takes precedence over the ccsid.tbl file and:
• Allows you to add or modify CCSID entries
• Specify default data conversion
• Specify data for different command levels
The ccsid_part2.tbl is applicable to the following platforms only:

• Linux - all versions

• Windows
If you have added any of your own CCSID information into your existing ccsid.tbl file, you
should copy this information into the new ccsid_part2.tbl file, if you want to take advantage of
the new formats in your customizations
You should copy the required information, rather than move the information, so that your existing
version of IBM MQ continues to work.

About this task

In the single-stage migration scenario, the installation of the later version of the product replaces an
earlier version in the same installation location.
The advantage of single-stage migration is that it changes the configuration of a queue manager on the
earlier version as little as possible. Existing applications switch from loading the libraries from the earlier
version, to loading the libraries of the later version, automatically. Queue managers are automatically
associated with the installation on the later version. Administrative scripts and procedures are affected as
little as possible by setting the installation to be the primary installation. If you set the installation of the
later version to be the primary installation, commands such as strmqm work without providing an explicit
path to the command.
When you upgrade the earlier version to the later version, all the objects that you previously created
are maintained. The components that were previously installed are preselected in the feature options
when you install the new level. If you leave these components selected, you can keep them or reinstall
them. If you clear any of these components, the installation process uninstalls them. By default, a typical
migration installs only the same features that were installed in the previous version installation.
For example, if IBM MQ Explorer was not installed in an earlier installation, it is not stored in a later
installation. If you want IBM MQ Explorer, select a custom installation, and select the IBM MQ Explorer
feature on the Features panel. If you do not want IBM MQ Explorer, uninstall the IBM MQ Explorer
feature by selecting a custom installation. Then clear the IBM MQ Explorer feature on the Features
panel. For more information about how to uninstall features, see “Modifying a server installation using the
Installation Launchpad” on page 201.

382 Installing and migrating IBM MQ

You can also migrate a queue manager to a later version of the product on a system where an earlier
version has been uninstalled. In this case, the queue manager data must have been retained, or restored
from a backup.

Procedure
1. Log in as a user in group mqm.
2. Stop all applications using the IBM MQ installation.
If you use the Managed File Transfer (MFT) component, ensure that any MFT agents have finished all
of the file transfers that they were engaged in. There should be no incomplete transfers associated
with the agents, and their SYSTEM.FTE.STATE queues should contain no messages.
3. End all the activity of queue managers associated with the IBM MQ installation.
a) Run the dspmq command to list the state of all the queue managers on the system.
Run either of the following commands from the installation that you are updating:

dspmq -o installation -o status

dspmq -a

dspmq -o installation -o status displays the installation name and status of queue
managers associated with all installations of IBM MQ.
dspmq -a displays the status of active queue managers associated with the installation from
which the command is run.
b) Use the MQSC command DISPLAY LSSTATUS to list the status of listeners associated with a
queue manager, as shown in the following example:

echo "DISPLAY LSSTATUS(*) STATUS" | runmqsc QmgrName

c) Run the endmqm command to stop each running queue manager associated with this installation.
-c
endmqm -w QmgrName

-i
-p

The endmqm command informs an application that the queue manager it is connected to is
stopping; see Stopping a queue manager.
For the maintenance to proceed, applications must respond to an endmqm command by
disconnecting from the queue manager and releasing any IBM MQ libraries they have loaded.
If they do not, you must find another way to force applications to release IBM MQ resources, such
as by stopping the applications.
You must also stop applications that are using the client libraries that are part of the installation.
Client applications might be connected to a different queue manager, running a different
installation of IBM MQ. The application is not informed about queue managers in the current
installation being shut down.
Any applications that continue to have IBM MQ shared libraries from the installation loaded
prevent you applying IBM MQ maintenance. An application might disconnect from a queue
manager, or be forcibly disconnected, but keep an IBM MQ shared library loaded.
Note: “Applying maintenance level updates to multi-instance queue managers on Windows”
on page 316 describes how to apply maintenance to a multi-instance queue manager. A multi-
instance queue manager can continue to run on one server, while maintenance is applied to
another server.
d) Stop any listeners associated with the queue managers, using the command:

Installing and migrating 383

 endmqlsr -m QMgrName

4. Back up the queue manager.

Take copies of all the queue manager's data and log file directories, including all subdirectories, and
also the qm.ini file and the registry entries. For more information, see Backing up and restoring IBM
MQ queue manager data.
5. Stop the IBM MQ Service and exit the Service icon application.
6. Optional: Optionally uninstall the current version of the product.
7. Upgrade the earlier version of the product to the later version in the same installation directory.
A reason for installing into the same location is to simplify application migration. If you change
the installation location, you might remove IBM MQ libraries from an application search path. To
migrate an application search path you must modify the application environment, or more rarely, the
application itself.
a) Decide on an installation naming convention. Give the installation a name of your choosing, or
accept the default installation name.
For the first installation, the default name is Installation1. For the second installation, the name is
Installation2, and so on.
b) Upgrade the earlier version of the product to the later version in place, or uninstall the earlier
version, without deleting any queue managers, and install the later version in the same default
location.
On Windows, you can do this either by using the Installation Launchpad or by using the msiexec
command. For more information, see:
• “Upgrading an IBM MQ server installation using the Launchpad” on page 332
• “Upgrading an IBM MQ server installation using msiexec” on page 333
On Windows, uninstalling the previous version of the product before you install the later version is
optional.
8. Reenter domain, user ID, and password information
When the installation of the latest version completes, the Prepare IBM MQ Wizard starts
automatically.
Where UAC is enabled: If you rerun the Prepare IBM MQ Wizard, ensure that the wizard is run with
Administrator privilege, otherwise the wizard might fail.
9. Optional: Make the later version of the installation the primary installation.
a) Run the setmqinst command

"Inst_1_INSTALLATION_PATH\bin\setmqinst" -i -n Inst_1

Make the installation primary to avoid specifying a search path to run IBM MQ commands
10. Start the queue managers and applications.
a) Run the setmqm command to associate the queue managers with Inst_1.

setmqm -m QM1 -n Inst_1

setmqm -m QM2 -n Inst_1

If you are migrating between any releases of the product, you must use setmqm to associate the
queue managers with the new installation manually.
b) Run the strmqm command to start the queue managers and migrate them to the later version of
the product.

384 Installing and migrating IBM MQ

 strmqm QM1
strmqm QM2

You must start IBM MQ before you start any listeners.

When you first start a queue manager after migration:
• Any new attributes for existing objects are set to their default values.
• Any new default objects are created.
• Queue manager data is migrated.
At this point, when the queue manager data is migrated, you cannot revert to a previous release.
Important: Do not use the -c option to start the queue manager, unless you explicitly want to
reset or re-create the default system objects.
• When an application connects to a queue manager, the operating system searches its load path to
load the IBM MQ library 2An IBM MQ library contains code that checks that the queue manager is
associated with an installation. If a queue manager is associated with a different installation, IBM
MQ loads the correct IBM MQ library for the installation the queue manager is associated with.

What to do next
You cannot reinstall an earlier version of the product on a system that has the latest, or any other, version
of IBM MQ installed.
Related concepts
“Migrating a queue manager to a later version on AIX and Linux” on page 406
On AIX and Linux, you can migrate a queue manager from an earlier version to a later version of IBM MQ
in one of three ways: single-stage, side-by-side, or multi-stage.
“Installation name on AIX, Linux, and Windows” on page 14
Each installation of IBM MQ on AIX, Linux, and Windows, has a unique identifier known as an installation
name. The installation name is used to associate things such as queue managers and configuration files
with an installation.
“Queue manager coexistence” on page 355
Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations.
“Multi-installation queue manager coexistence on AIX, Linux, and Windows” on page 357
You can install multiple copies of IBM MQ for AIX, Linux, and Windows on the same server. These IBM MQ
copies can be at the same or different version levels. This is called a multi-installation. Multi-installation is
particularly useful when you upgrade from one IBM MQ version to a later version, because it allows you to
run the earlier version alongside the later version.
Related tasks
Migrating on Windows: side-by-side
Migrating on Windows: multi-stage
“Planning to migrate IBM MQ to a later version on Windows” on page 373
“Migrating a queue manager to a later version on Windows” on page 378
On Windows platforms, follow these instructions to migrate a queue manager from an earlier version to a
later version of IBM MQ.
“Configuring IBM MQ with the Prepare IBM MQ Wizard” on page 194

2 On Windows, the IBM MQ library is a DLL. A DLL is sometimes called a load library or a shared library. The
entry points to a DLL are defined in a link library, with the file extension .lib32 or .lib. The .lib library
is linked at build-time and the DLL loaded at runtime.

Installing and migrating 385

 The Prepare IBM MQ Wizard helps you to configure IBM MQ with a user account for your network. You
must run the wizard to configure the IBM MQ Service before you can start any queue managers.
“Installing IBM MQ server on Windows” on page 176
On Windows, IBM MQ is installed by using the Microsoft Installer (MSI). You can either use the
Installation Launchpad to invoke MSI or alternatively, you can invoke MSI directly.
Associating a queue manager with an installation
Changing the primary installation
“Migrating IBM MQ library loading to a later version on AIX and Linux” on page 424
On AIX and Linux, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to a later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
“Migrating IBM MQ library loading to a later version on Windows” on page 396
On Windows, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to the later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
Related reference
setmqenv
setmqinst
setmqm

Migrating on Windows: side-by-side

Side-by-side migration is the term used to describe installing a later version of IBM MQ alongside
an earlier version on the same server. Queue managers remain running during the installation and
verification of the later version of IBM MQ. They remain associated with the earlier version of IBM
MQ. When you decide to migrate queue managers to the later version of IBM MQ, you stop all queue
managers, uninstall the earlier version, and migrate them all to the new version of IBM MQ.

Before you begin

From IBM MQ 9.0, the ccsid_part2.tbl file replaces the existing ccsid.tbl file, used in previous
versions of the product, to supply additional CCSID information.
Attention:
The ccsid_part2.tbl file takes precedence over the ccsid.tbl file and:
• Allows you to add or modify CCSID entries
• Specify default data conversion
• Specify data for different command levels
The ccsid_part2.tbl is applicable to the following platforms only:

• Linux - all versions

• Windows
If you have added any of your own CCSID information into your existing ccsid.tbl file, you
should copy this information into the new ccsid_part2.tbl file, if you want to take advantage of
the new formats in your customizations
Copy the required information, rather than move the information, so that your existing version of
IBM MQ continues to work.

386 Installing and migrating IBM MQ

 About this task
In the side-by-side migration scenario, you install the later version of IBM MQ alongside queue managers
that continue to be associated with the installation of the earlier version of the product.
When you are ready to migrate the queue managers, and applications, to the later version:
1. Stop all the queue managers.
2. Uninstall the earlier version of the product.
3. Migrate all the queue managers and applications to the later version.

Procedure
1. Install the later version in a different installation directory from the earlier version.
a) Decide on an installation naming convention. Give the installation a name of your choosing, or
accept the default installation name.
For the first installation, the default name is Installation1. For the second installation, the name is
Installation2, and so on.
b) Verify the installation.
Run the installation verification procedures and your own tests.
2. Uninstall the earlier version of the product.
When uninstalling the earlier product, you must stop all queue managers and applications that
have loaded an IBM MQ library on the server. For this reason, you might choose to postpone
uninstalling the earlier version of the product until a convenient maintenance window. When
an earlier version of the product is not installed on a server, it is sufficient to stop the queue
managers and applications that have loaded libraries from the installation that you are uninstalling
or updating. It is not necessary to stop applications and queue managers associated with other
installations.
a) Stop all applications that have loaded IBM MQ libraries on the server.
b) Stop the queue managers and listeners on the server.
c) Uninstall the earlier version of the product.
• Stop all local IBM MQ applications
• You do not need to stop all the queue managers at this point.
3. Make the later version of the installation the primary installation.
a) Run the setmqinst command

"Inst_1_INSTALLATION_PATH\bin\setmqinst" -i -n Inst_1

Make the installation primary to avoid specifying a search path to run IBM MQ commands
Use the dspmqinst command to discover the Installation name, or use the default value
Installation 1.
Doing this means that you do not have to specify a search path on IBM MQ commands.
4. Start the queue managers and applications.
• When an application connects to a queue manager, the operating system searches its load path to
load the IBM MQ library 3 . An IBM WebSphere MQ 7.1, or later, library contains code that checks
that the queue manager is associated with an installation. If a queue manager is associated with

3 On Windows, the IBM MQ library is a DLL. A DLL is sometimes called a load library or a shared library. The
entry points to a DLL are defined in a link library, with the file extension .lib32 or .lib. The .lib library
is linked at build-time and the DLL loaded at runtime.

Installing and migrating 387

 a different installation, IBM MQ loads the correct IBM MQ library for the installation the queue
manager is associated with.
During this process you continue to use queue manager QM2 while you upgrade queue manager QM1
and you use queue manager QM1 while you upgrade QM2.
Note that each queue manager needs to be stopped in order to be associated with the new installation.

What to do next
You cannot reinstall an earlier version of the product on a system that has the latest, or any other, version
of IBM MQ installed.
Related tasks
Migrating on Windows: single stage
Single-stage migration is the term used to describe replacing the only installation of IBM MQ on a server,
with a later version of the product. Single stage migration is also known as upgrading in place or in place
upgrade. Single-stage migration preserves existing scripts and procedures for running IBM MQ the most.
With other migration scenarios you might change some scripts and procedures, but you can reduce the
effect queue manager migration has on users.
Migrating on Windows: multi-stage
“Planning to migrate IBM MQ to a later version on Windows” on page 373
“Uninstalling IBM MQ on Windows” on page 230
You can uninstall the IBM MQ MQI clients and servers on Windows systems by using the control panel,
the command line ( msiexec ), MQParms, or by using the installation media, in which case you can
optionally remove queue managers as well.
“Installing IBM MQ server on Windows” on page 176
On Windows, IBM MQ is installed by using the Microsoft Installer (MSI). You can either use the
Installation Launchpad to invoke MSI or alternatively, you can invoke MSI directly.
Associating a queue manager with an installation
Changing the primary installation
“Installation name on AIX, Linux, and Windows” on page 14
Each installation of IBM MQ on AIX, Linux, and Windows, has a unique identifier known as an installation
name. The installation name is used to associate things such as queue managers and configuration files
with an installation.
“Queue manager coexistence” on page 355
Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations.
“Migrating IBM MQ library loading to a later version on AIX and Linux” on page 424
On AIX and Linux, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to a later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
“Migrating IBM MQ library loading to a later version on Windows” on page 396
On Windows, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to the later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
“Multi-installation queue manager coexistence on AIX, Linux, and Windows” on page 357

388 Installing and migrating IBM MQ

You can install multiple copies of IBM MQ for AIX, Linux, and Windows on the same server. These IBM MQ
copies can be at the same or different version levels. This is called a multi-installation. Multi-installation is
particularly useful when you upgrade from one IBM MQ version to a later version, because it allows you to
run the earlier version alongside the later version.
setmqenv
setmqinst
setmqm

Migrating on Windows: multi-stage

Multi-stage migration is the term used to describe running a later version of IBM MQ alongside an earlier
version on the same server. After installing the later version alongside the earlier version, you can create
new queue managers to verify the later installation, and develop new applications. At the same time,
you can migrate queue managers and their associated applications from the earlier version to the later
version. By migrating queue managers and applications one-by-one, you can reduce the peak workload on
staff managing the migration.

Before you begin

Attention:
The ccsid_part2.tbl file takes precedence over the ccsid.tbl file and:
• Allows you to add or modify CCSID entries
• Specify default data conversion
• Specify data for different command levels
The ccsid_part2.tbl is applicable to the following platforms only:

• Linux - all versions

• Windows
If you have added any of your own CCSID information into your existing ccsid.tbl file, you
should copy this information into the new ccsid_part2.tbl file, if you want to take advantage of
the new formats in your customizations
Copy the required information, rather than move the information, so that your existing version of
IBM MQ continues to work.
Note: If you are running the IBM MQ.NET monitor in transactional mode, the queue manager it connects
to must be the primary installation.

About this task

In the multi-stage migration scenario, you install the later version of the product alongside running queue
managers that continue to be associated with the earlier version. You can create queue managers and
run new applications using the later version installation. When you are ready to start migrating queue
managers and applications from the earlier, you can do so, one-by-one. When migration to the later
version is complete, you can uninstall the earlier version, and make the later version installation the
primary installation.
With the multi-stage approach, until you uninstall the earlier version , you must configure an environment
to run applications that connect to a queue manager to the later version. You must also provide a path to
run IBM MQ commands. Both these tasks are accomplished with the setmqenv command.
Note: When you have uninstalled the earlier version, and set the later version as a primary installation,
in most circumstances it is not necessary to run the setmqenv command to run applications. It is still
necessary to run setmqenv to set the environment for commands that connect to a queue manager
associated with an installation that is not primary.

Installing and migrating 389

 Procedure
1. Install the later version in a different installation directory from the earlier version and verify the
installation.
a) Decide on an installation naming convention. Give the installation a name of your choosing, or
accept the default installation name.
For the first installation, the default name is Installation1. For the second installation, the name is
Installation2, and so on.
b) Verify the installation.
Run the installation verification procedures and your own tests.
• You might create new queue managers running the later version, and start to develop new
applications before migrating applications from the earlier version.
2. Configure the operating system so that applications load the libraries for the later version of the
product.
a) Migrate queue managers one at a time.
The first set of applications to load the libraries for the later version of the product are the
applications that connect to the first queue manager you are going to migrate.
It does not matter if those applications also connect to other queue managers on the server. If the
applications load the later version libraries, IBM MQ automatically loads the libraries for the earlier
version for those applications that connect to that version.
You can either migrate the operating system environment of all applications, or just the applications
that connect to the first queue manager you are going to migrate.
b) Migrate IBM MQ MQI client applications
Some of the applications might be running as IBM MQ MQI client applications on another
workstation. When you migrate a queue manager, clients connected to it continue to run without
loading a client library for the later version.
You can migrate these clients later, when you need to do so.
Important: If any IBM MQ MQI client applications are using the library for the earlier version on the
server, you must eventually migrate the clients to use the later version of the product before you
uninstall the earlier version.
3. Migrate an application to load the new library for the later version:
• Run setmqenv to modify the local path that is searched for IBM MQ libraries.
• Relink applications with an additional runtime load path.
Consult operating system documentation about how to modify the global search path, or include a
fixed runtime load path in the application load module.
To run setmqenv using the -s option:

"Inst_1_INSTALLATION_PATH\bin\setmqenv" -s

The -s option sets up the environment for the installation that runs the setmqenv command.
4. Restart the queue manager and the applications that connect to it.
a) Set up the local environment to the installation Inst_1.

"Inst_1_INSTALLATION_PATH\bin\setmqenv" -s

The -s option sets up the environment for the installation that runs the setmqenv command.
b) Run the setmqm command to associate QM1 with Inst_1.

390 Installing and migrating IBM MQ

 setmqm -m QM1 -n Inst_1
setmqm -m QM2 -n Inst_1

c) Run the strmqm command to start QM1 and migrate it to the later version.

strmqm QM1
strmqm QM2

d) Restart application 1
The application loads the later version library and connects to QM1, which is associated with the
later version of the product.
5. Migrate all queue managers and applications to the later version.
Repeat steps “2” on page 390 and “4” on page 390, when required, until all the queue managers
and applications are migrated to the later version of the product.
6. Uninstall the earlier version of the product.
When uninstalling the earlier product, you must stop all queue managers and applications that
have loaded an IBM MQ library on the server. For this reason, you might choose to postpone
uninstalling the earlier version of the product until a convenient maintenance window. When
an earlier version of the product is not installed on a server, it is sufficient to stop the queue
managers and applications that have loaded libraries from the installation that you are uninstalling
or updating. It is not necessary to stop applications and queue managers associated with other
installations.
a) Log in as a user in group mqm.
b) Stop all applications using the IBM MQ installation.
If you use the Managed File Transfer (MFT) component, ensure that any MFT agents have finished
all of the file transfers that they were engaged in. There should be no incomplete transfers
associated with the agents, and their SYSTEM.FTE.STATE queues should contain no messages.
c) Stop the mqweb server that is associated with the IBM MQ installation by entering the following
command:

endmqweb

d) List the state of all the queue managers on the system by using the dspmq command:

dspmq -a

e) List the status of listeners associated with a queue manager by using the DISPLAY LSSTATUS
MQSC command:

echo "DISPLAY LSSTATUS(*) STATUS" | runmqsc QmgrName

f) Stop any listeners associated with the queue managers, using the endmqlsr command:

endmqlsr -m QMgrName

g) Stop each running queue manager that is associated with this installation by using the endmqm
command:

endmqm QMgrName

h) Uninstall the earlier version of the product. For more information, see “Uninstalling or modifying
IBM MQ on Linux” on page 150
7. Make Inst_1 the primary installation.

Installing and migrating 391

 a) Run the setmqinst command

"Inst_1_INSTALLATION_PATH\bin\setmqinst" -i -n Inst_1

Note: Use the dspmqinst command to discover the Installation name, or use the default value
Installation 1.
You do not have to set up a search path to run IBM MQ commands from the primary installation.

What to do next
You cannot reinstall an earlier version of the product on a system that has the latest, or any other, version
of IBM MQ installed.
Now that you have uninstalled the earlier version of the product, and made the later installation primary,
you can review how the application runtime environment is set. It is no longer necessary to run setmqenv
to set up the search path to load libraries for the later version. If you have only one installation of the later
version of the product installed, it is not necessary to run setmqenv to run commands.
Related concepts
“Installation name on AIX, Linux, and Windows” on page 14
Each installation of IBM MQ on AIX, Linux, and Windows, has a unique identifier known as an installation
name. The installation name is used to associate things such as queue managers and configuration files
with an installation.
“Queue manager coexistence” on page 355
Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations.
“Multi-installation queue manager coexistence on AIX, Linux, and Windows” on page 357
You can install multiple copies of IBM MQ for AIX, Linux, and Windows on the same server. These IBM MQ
copies can be at the same or different version levels. This is called a multi-installation. Multi-installation is
particularly useful when you upgrade from one IBM MQ version to a later version, because it allows you to
run the earlier version alongside the later version.
Related tasks
Migrating on Windows: single stage
Single-stage migration is the term used to describe replacing the only installation of IBM MQ on a server,
with a later version of the product. Single stage migration is also known as upgrading in place or in place
upgrade. Single-stage migration preserves existing scripts and procedures for running IBM MQ the most.
With other migration scenarios you might change some scripts and procedures, but you can reduce the
effect queue manager migration has on users.
Migrating on Windows: side-by-side
“Planning to migrate IBM MQ to a later version on Windows” on page 373
“Installing IBM MQ server on Windows” on page 176
On Windows, IBM MQ is installed by using the Microsoft Installer (MSI). You can either use the
Installation Launchpad to invoke MSI or alternatively, you can invoke MSI directly.
Associating a queue manager with an installation
Changing the primary installation
“Migrating IBM MQ library loading to a later version on AIX and Linux” on page 424
On AIX and Linux, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to a later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
“Migrating IBM MQ library loading to a later version on Windows” on page 396

392 Installing and migrating IBM MQ

On Windows, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to the later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
Related reference
setmqenv
setmqinst
setmqm

Reverting a queue manager to an earlier version on Windows

On Windows platforms, you can revert a queue manager to an earlier version of the product from a
later version, if you have made a backup of the system or queue manager. If you have started the
queue manager and processed any messages, or changed the configuration, the task cannot give you any
guidance on reverting the current state of the queue manager.

Before you begin

1. You must have made a backup of the system or queue manager before you upgraded to the later
version. For more information see Backing up and restoring IBM MQ queue manager data
2. If any messages were processed after starting the queue manager, you cannot easily undo the effects
of processing the messages. You cannot revert the queue manager to the earlier version of the product
in its current state. The task cannot give you any guidance how to deal with subsequent changes that
have occurred. For example, messages that were indoubt in a channel, or in a transmission queue on
another queue manager, might have been processed. If the queue manager is part of a cluster, then
configuration messages and application messages might have been exchanged.
3. If you are running on a server with multiple IBM MQ installations, you must identify the installation.
Make sure that the commands you enter run against the correct installation; see setmqenv.

About this task

When you revert to a earlier version of a queue manager, you revert the queue manager to its earlier code
level. Queue manager data is reverted to the state it was in when the queue manager was backed up.
Important: If the queue manager is a member of one or more IBM MQ clusters, you should also review
and follow the steps described in Recovering a cluster queue manager.

Procedure
1. Log in as a user in group mqm.
2. Stop all applications using the IBM MQ installation.
If you use the Managed File Transfer (MFT) component, ensure that any MFT agents have finished all of
the file transfers that they were engaged in. There should be no incomplete transfers associated with
the agents, and their SYSTEM.FTE.STATE queues should contain no messages.
3. End all the activity of queue managers associated with the IBM MQ installation.
a) Run the dspmq command to list the state of all the queue managers on the system.
Run either of the following commands from the installation that you are updating:

dspmq -o installation -o status

dspmq -a

dspmq -o installation -o status displays the installation name and status of queue
managers associated with all installations of IBM MQ.

Installing and migrating 393

 dspmq -a displays the status of active queue managers associated with the installation from
which the command is run.
b) Use the MQSC command DISPLAY LSSTATUS to list the status of listeners associated with a
queue manager, as shown in the following example:

echo "DISPLAY LSSTATUS(*) STATUS" | runmqsc QmgrName

c) Run the endmqm command to stop each running queue manager associated with this installation.
-c
endmqm -w QmgrName

-i
-p

The endmqm command informs an application that the queue manager it is connected to is
stopping; see Stopping a queue manager.
For the maintenance to proceed, applications must respond to an endmqm command by
disconnecting from the queue manager and releasing any IBM MQ libraries they have loaded. If
they do not, you must find another way to force applications to release IBM MQ resources, such as
by stopping the applications.
You must also stop applications that are using the client libraries that are part of the installation.
Client applications might be connected to a different queue manager, running a different
installation of IBM MQ. The application is not informed about queue managers in the current
installation being shut down.
Any applications that continue to have IBM MQ shared libraries from the installation loaded prevent
you applying IBM MQ maintenance. An application might disconnect from a queue manager, or be
forcibly disconnected, but keep an IBM MQ shared library loaded.
Note: “Applying maintenance level updates to multi-instance queue managers on Windows” on
page 316 describes how to apply maintenance to a multi-instance queue manager. A multi-instance
queue manager can continue to run on one server, while maintenance is applied to another server.
d) Stop any listeners associated with the queue managers, using the command:

endmqlsr -m QMgrName

4. Restore the system, or IBM MQ and the queue manager.

If your backup procedure was to save the queue manager data, you must reinstall IBM MQ:
a) Uninstall the earlier installation.
b) Reinstall the product from a manufacturing refresh.
c) Apply the fix pack and interim fixes that restore IBM MQ to its previous level.
d) Restore the queue manager data from the backup taken before installing the later version.
5. Restart the earlier version queue manager.

What to do next
You might be reverting to a earlier version on a server with multiple IBM MQ installations. If one of
the installations is primary, after reverting the earlier version that installation, by default, becomes the
primary installation.
You must review how applications connect to an installation. After reverting to the earlier version, some
applications might connect to the wrong installation.
Related concepts
Backing up and restoring a queue manager

394 Installing and migrating IBM MQ

Related reference
Avoiding BFGSS0023E errors when removing fix packs

Migrating an IBM MQ MQI client on Windows

Before migrating an IBM MQ MQI client, create a migration plan. Stop all IBM MQ activity on the
client workstation. Upgrade the IBM MQ MQI client installation. Make any essential configuration and
application changes.
Related concepts
“IBM MQ MQI client migration” on page 344
IBM MQ MQI client migration is the process of converting IBM MQ MQI client configurations, and client
and server channels from one version to another. Client migration can take place after upgrading the IBM
MQ MQI client, and is reversible.
Related tasks
“Migrating an IBM MQ MQI client to the latest version on IBM i” on page 446
Before migrating an IBM MQ MQI client, create a migration plan. Stop all IBM MQ activity on the
client workstation. Upgrade the IBM MQ MQI client installation. Make any essential configuration and
application changes.
“Migrating an IBM MQ MQI client on AIX and Linux” on page 421
Before migrating an IBM MQ MQI client, create a migration plan. Stop all IBM MQ activity on the
client workstation. Upgrade the IBM MQ MQI client installation. Make any essential configuration and
application changes.

Migrating an IBM MQ MQI client to a later version on Windows

Before migrating an IBM MQ MQI client on Windows platforms, create a migration plan. Stop all IBM
MQ activity on the client workstation. Upgrade the IBM MQ MQI client installation. Make any essential
configuration and application changes.

Before you begin

Before starting to migrate a client, create a migration plan. For guidance on what to include in the plan,
see “Planning to migrate IBM MQ to a later version on Windows” on page 373.

About this task

IBM MQ MQI client migration is the process of converting IBM MQ MQI client configurations, and client
and server channels from one version to another. Client migration is reversible. It is optional and manual
on a client workstation and is required and automatic on the IBM MQ server.
You must upgrade an IBM MQ MQI client before migrating a client workstation to make use of new
configuration options. You can make configuration changes to client and server connection channels on
the server, but they have no effect on a client workstation until the client is upgraded.

Procedure
1. Review the IBM MQ system requirements for the later version of the product.
See System Requirements for IBM MQ.See “IBM MQ components and features” on page 6 and “Where
to find downloadable installation images” on page 9.
2. Review all the changes in IBM MQ that affect you.
See “Changes that affect migration” on page 337.
3. End all IBM MQ activity on the workstation.
4. Upgrade the client.
Select the appropriate option for your enterprise.
• For a client installation on a workstation, see “Installing an IBM MQ client on Windows” on page 203.

Installing and migrating 395

 • For a client installation on an IBM MQ server, see Installing IBM MQ clients and servers on the same
system.

What to do next
After upgrading the IBM MQ MQI client, you must check the client channel configuration, and verify that
your IBM MQ MQI client applications work correctly with the later version of the product.
Related concepts
“IBM MQ MQI client migration” on page 344
IBM MQ MQI client migration is the process of converting IBM MQ MQI client configurations, and client
and server channels from one version to another. Client migration can take place after upgrading the IBM
MQ MQI client, and is reversible.
Related tasks
“Planning to migrate IBM MQ to a later version on Windows” on page 373

Restoring an IBM MQ MQI client to an earlier version on Windows

If you revert an IBM MQ MQI client from a later version of the product to an earlier version of the product,
you must undo the configuration changes manually.

About this task

It is unusual to revert earlier IBM MQ MQI client libraries to a workstation. The principal tasks are listed in
the following steps.

Procedure
1. End all IBM MQ activity on the workstation.
2. Uninstall the later version of the IBM MQ MQI client code.
3. Follow the client installation procedure for the platform to install the earlier version of the IBM MQ MQI
client code.
4. If you configured a Client Connection Definition Table (CCDT) for a queue manager on a later version of
the product, revert to using a table created by a queue manager on the earlier version.
The CCDT must always be created by a queue manager on the same, or earlier, release to the client.

Migrating IBM MQ library loading to a later version on Windows

On Windows, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to the later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.

Before you begin

To migrate applications from an earlier version of the product to the later version, you must know how
the operating system loads an IBM MQ library for an application. Is the load path fixed by the application,
and can you set the path in an environment variable? It is not essential to know the name of the IBM MQ
library that the application loads. The library name does not change from an earlier version of the product
to the later version, although the contents of the library do.
Read “Multi-installation queue manager coexistence on AIX, Linux, and Windows” on page 357 before
starting this task.
Plan and install the later version of IBM MQ, and remember the installation name and whether the
installation was set to primary.

396 Installing and migrating IBM MQ

 About this task
To migrate an application from an earlier version of the product to the later version, you do not have to
recompile or relink the application, because the IBM MQ libraries are compatible with later versions; see
“Application compatibility and interoperability with later versions of IBM MQ” on page 367.
Windows searches numerous directories for load libraries, called DLLs; see Dynamic-Link Library Search
Order. The build procedure for applications places the IBM MQ libraries to load before any other product
libraries in the cl command. The IBM MQ .lib libraries must be in the PATH environment variable that
you have specified at build time, and the DLL libraries at run time. The PATH variable is used by the
application process to find the libraries it must load.
If you have followed this build procedure in the earlier release, then the effect of installing the later
version of the product on the libraries that are loaded depends on which migration scenario that you are
following:
Single-stage scenario
If you are replacing an earlier version of the product with the later version, based on the single stage
scenario described in “Migrating on Windows: single stage” on page 381, you do not, in most cases,
need to make any changes to the way IBM MQ libraries are loaded. The possible exception to this is
if you changed the location of the libraries from the earlier version, or created symbolic links to the
libraries.
Side-by-side and Multi-stage scenarios
If you have chosen a multi-installation approach to installing the later version of the product, based
either on the side-by-side scenario described in “Migrating on Windows: side-by-side” on page 386,
or the multi-stage migration scenario described in “Migrating on Windows: multi-stage” on page 389,
you must investigate whether applications connecting to the later version of the product are linked
to, and load libraries from, the correct installation and then modify the environment for the operating
system to resolve IBM MQ dependencies for an application as appropriate. Typically, you can modify
the runtime environment, rather than relink the application. You can use the following two commands
to assist you in configuring the runtime environment:
• setmqinst sets the primary installation; see setmqinst.
• setmqenv initializes the command environment by setting environment variables; see setmqenv.
Table 40 on page 397 summarizes the actions needed for each of these scenarios.

Table 40. Windows configurations

Scenari Latest version replaces Latest version replaces Latest version alongside
Actio o earlier version in the same earlier version in a earlier version
n location different location
Multi-stage
Single-stage Side-by-side

setmqinst makes the later version installation primary. No. The later version
The global PATH is changed to point to the later version installation can be primary,
setmqinst
library and all Windows features work with the later because an earlier version is
version. installed.

Installing and migrating 397

Table 40. Windows configurations (continued)

Scenari Latest version replaces Latest version replaces Latest version alongside
Actio o earlier version in the same earlier version in a earlier version
n location different location
Multi-stage
Single-stage Side-by-side

No other Library loading works Library loading probably The library loading continues to
configuration correctly. works correctly. work with the earlier version
actions correctly, nothing works with
The global PATH contains the The library loading might
the later version.
location of the later version not work, if the application
libraries. process locally modified
the PATH to reference
Even if the later version
the location of the earlier
installation is not primary,
version libraries. A local
library loading works
setting of PATH might
correctly. The later version
override the global PATH
libraries are in the same
that is set by setmqinst.
location as the earlier
version libraries were.

setmqenv Library loading works correctly. Library loading works correctly,

both for the earlier version and
setmqenv sets the local PATH correctly.
the later version.
setmqenv sets the local PATH
correctly for the later version.
But the Windows features that
depend on the global path do
not work correctly with the
later version .
The correct earlier version
is loaded, because the later
version library loads the earlier
version library for queue
managers that have not been
migrated from the earlier
version.

Procedure
1. Consider which of the following questions apply to your configuration.
• Did you follow the build procedure documented in the product documentation for the earlier version
of the product? You might be following a different build procedure tailored to your development
environment, or adapted from a development tool such as Microsoft Visual Studio.
• How did you specify the load path for the earlier version?
• Is the application is loaded by another environment, such as Eclipse, or an application server? You
must modify the parameters that govern how the parent environment loads applications, not the way
the parent environment is loaded.
• Do the functions performed by an application require that the queue manager it connects to is
associated with the primary installation?
• What constraints and requirements do you have on how the load path is specified in the later
version? Security rules might restrict the use of LD_LIBRARY_PATH.
• Is the later version of the product installed alongside the earlier version?

398 Installing and migrating IBM MQ

2. Identify the installation of the later version of the product, from which the operating system is going to
load IBM MQ libraries:
• If you have a multiple installations of the later versions to load from a server, IBM MQ checks that
the installation the library was loaded from is the installation that is associated with any queue
manager the application calls. IBM MQ loads the correct library if the wrong library is loaded. It is
necessary to configure only one runtime environment for all IBM MQ applications.
• A typical choice is set the primary installation. Setting an installation to be primary places its library
path in the global PATH variable.
• If you upgraded an earlier version installation to the later version, a link path to the earlier version
installation now points to an installation containing the later version. Applications that have a fixed
linkage path to the earlier version installation now load the libraries for the later installation. They
are then switched to the installation that is associated with any queue manager they connect to.
• If you rebuild an application, it must link to an installation of the later version.
• If you are running the IBM MQ.NET monitor in transactional mode, the queue manager it connects
to must be the primary installation.

What to do next
If you add further installations of the later version of the product, you must decide which installation to
make primary, if you have chosen to make any primary. As long as applications load IBM MQ libraries
from one of the later version installations, such as the primary installation, they can connect to queue
managers associated with any other later version installation.
On Windows, you might build applications with different development tools. You must identify the
property of the development tool that sets the PATH of the application that is being built, and not the
properties of the tool itself. For example, if you are debugging with Microsoft Visual Studio, you can
insert a call to setmqenv in the Environment property of the debugging section of the Configuration
properties of a project.
A Windows application might call LoadLibrary and specify an explicit load path. You might build a side-
by-side assembly and configure an explicit load path. If an application uses either of these mechanisms,
and the later version IBM MQ library is not on the same path as the earlier release, you must recompile, or
configure and relink your application to load the later version libraries.
Related concepts
“Features that can be used only with the primary installation on Windows” on page 25
Some Windows operating-system features can be used only with the primary installation. This restriction
is due to the central registration of interface libraries, which might conflict as a result of multiple versions
of IBM MQ being installed.
Related tasks
Changing the primary installation
Connecting applications in a multiple installation environment
“Migrating IBM MQ library loading to a later version on AIX and Linux” on page 424
On AIX and Linux, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to a later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
Related reference
“Coexistence” on page 354
Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations. In addition to queue managers coexisting on a server, objects,
and commands must work correctly with different queue managers running at different command levels.

Installing and migrating 399

 setmqenv
setmqinst
setmqm

Migrating MQ Telemetry on Windows

Follow these instructions to migrate your existing installation of MQ Telemetry to a later version of the
product on Windows.

Before you begin

Before proceeding with this task, ensure that you back up your existing IBM MQ installation. You must
stop the MQ Telemetry service SYSTEM.MQXR.SERVICE before migrating.

About this task

The telemetry server is included in the product as an optional installation.
The Client Software Development Kit is no longer supplied as part of the product. Similar sample
applications continue to be freely available from Eclipse Paho and MQTT.org. See IBM MQ Telemetry
Transport sample programs.
Because MQ Telemetry is a component of IBM MQ, MQ Telemetry can either be installed with the main
product, or installed after the main product has been installed.
After the successful upgrade, Windows systems retain the telemetry data in the installation directory
of the product, for example: C:\Program Files (x86)\IBM\WebSphere MQ. Telemetry data is
migrated to the later version of the product when the queue manager is started again.

Procedure
1. Create a migration plan.
See “Planning to migrate IBM MQ to a later version on Windows” on page 373.
2. Migrate your queue managers to the later release.
3. “Installation considerations for MQ Telemetry” on page 250.
4. Verify that the MQ Telemetry installation was successful. See “Verifying the installation of MQ
Telemetry” on page 251.
5. If the passphrases for your MQTT TLS channels are stored in plain text, you should encrypt the
passphrases.
Before IBM MQ 9.3.0, passphrases for MQTT TLS channels were stored in plain text. From IBM MQ
9.3.0, support for the encryption of passphrases for MQTT TLS channels is provided.
Existing plain text passphrase are not changed to an encrypted form automatically. You must update
your plain text passphrases to an encrypted form. For more information on how to encrypt your
passphrases, see Encryption of passphrases for MQTT TLS channels.

Results
Message AMQ4616 indicates completion of the task. The existing MQTT channels and previous
subscriptions are still present.
Related concepts
“IBM MQ installation overview” on page 6
An overview of concepts and considerations for installing IBM MQ, with links to instructions on how to
install, verify, and uninstall IBM MQ on each of the supported platforms.
“Installation considerations for MQ Telemetry” on page 250

400 Installing and migrating IBM MQ

MQ Telemetry is a component of the main IBM MQ product. You can choose to install MQ Telemetry when
you first install IBM MQ, or when you modify an existing IBM MQ installation.
Related tasks
“Verifying the installation of MQ Telemetry” on page 251
There are three ways to verify the installation of MQ Telemetry. Any can be used, regardless of whether
MQ Telemetry was installed as a custom installation of IBM MQ, or added to an existing installation of IBM
MQ.
“Verifying the installation of MQ Telemetry by using IBM MQ Explorer” on page 251
Use the Define sample configuration wizard and the MQTT client utility in IBM MQ Explorer to verify that
the MQ Telemetry components have installed. Also check that publish/subscribe works correctly.

Migrating an MSCS configuration on Windows

Migrate queue managers in a Microsoft Cluster Service (MSCS) configuration one node at a time, following
these instructions.

About this task

These steps are required for a rolling upgrade with a minimum amount of downtime. You must always
upgrade an offline node with no online IBM MQ resources. In an Active/Passive configuration, if the node
is Passive, you must ensure it cannot be switched to Active during the upgrade process.
The example, “Migrating a four-node MSCS cluster from an earlier version of the product to the latest
version” on page 401, shows this procedure applied to a four-node cluster.

Procedure
1. Modify the possible owners of the IBM MQ resource to encompass only the Active node or nodes. With
no owners assigned to Passive nodes, the IBM MQ resource that is being migrated cannot be activated.
2. Ensure that the group containing the IBM MQ resource is currently on one of the nodes defined as a
possible owner. The group must include any applications connecting to the queue manager resource.
3. Stop the cluster service on the node being migrated. The MSCS cache is cleared of any IBM MQ DLLs
that have been registered.
4. Migrate the selected node by following the standard instructions in “Migrating a queue manager to a
later version on Windows” on page 378. Apply the required maintenance level.
5. Start the cluster service on the selected node.
6. On the next node to be migrated, ensure that the IBM MQ resources are offline.
7. Remove this node from the list of possible owners. For clusters with more than two nodes, see the
Additional considerations later in this topic.
8. Move the group containing the IBM MQ resource to one of the possible owners and bring it online.
9. Repeat steps 3-8 as necessary for any remaining nodes.

Migrating a four-node MSCS cluster from an earlier version of the product to the latest version
The example in Table 41 on page 402 illustrates the steps involved in migrating a four-node MSCS cluster.
In the example IBM MQ resources include queue managers, applications, and dependant MSCS
resources, such as an IP address defined an as MSCS resource. In each step, the changes are italicized.
Step 1
Select the node to migrate and prepare it for upgrading from an earlier version of the product to the
latest version.
1. Select node 1 to be migrated and convert it into a Passive node with no running IBM MQ resources.
2. Modify the possible owners of the group containing the IBM MQ resources, to encompass only the
required online nodes. Failover does not attempt to switch IBM MQ resources to the node that is
not a possible owner. It is safe to migrate that node.

Installing and migrating 401

 3. Move the group containing the IBM MQ resource to one of the nodes that is a possible owner, and
bring it online.
4. Stop the cluster service on the node being migrated. Stopping the service clears the MSCS cache of
any IBM MQ libraries that have been registered for MSCS. The node goes offline.
Step 2
Migrate IBM MQ from an earlier version of the product to the latest version
Step 3
Start the cluster service on the selected node. The node becomes online, but it is not a possible
owner, so no work is switched to it.
Step 4
Repeat steps 1 - 3 for node 2. Nodes 1 and 2 are now online, and you have migrated them to the latest
version. They are still doing no work, as they are not possible owners of any of the IBM MQ resource
groups.
Step 5
Migrate the cluster from running an earlier version of the product to the latest version. The number of
migrated nodes is now greater or equal to the number of unmigrated nodes.
1. Change the set of possible owners from 3,4 to 1,2.
2. Move the IBM MQ resource groups from nodes 3 and 4 to nodes 1 and 2 and bring online.
3. From this point onward, the list of possible owners must include migrated nodes only. The IBM MQ
resource must never failover to a node running a back level version of the product.
Note: If you must revert IBM MQ to an earlier version, the IBM MQ resources must be removed from
MSCS control, before performing an uninstallation of IBM MQ
Step 6
Migrate node 3 to the latest version.
1. Follow steps 1 - 3 for node 3.
2. Add node 3 to the list of possible owners.
3. Move the QMC resource group back from node 1 to node 3 and bring online again.
Step 7
Repeat step 6 for node 4.

Table 41. Migrating a four-node MSCS cluster

Steps 0 1 2 3 4 5 6 7
State Online Offline Offline Online Online Online Online Online
Version Earlier Earlier Latest Latest Latest Latest Latest Latest
Node 1 version version version version version version version version
Groups QMA QMC, QMA QMA
QMA
State Online Online Online Online Online Online Online Online
Version Earlier Earlier Earlier Earlier Latest Latest Latest Latest
Node 2 version version version version version version version version
Groups QMB QMB QMB QMB QMD, QMD, QMB
QMB QMB

402 Installing and migrating IBM MQ

Table 41. Migrating a four-node MSCS cluster (continued)
Steps 0 1 2 3 4 5 6 7
State Online Online Online Online Online Online Online Online
Version Earlier Earlier Earlier Earlier Earlier Earlier Latest Latest
Node 3 version version version version version version version version
Groups QMC QMC, QMC, QMC, QMC, QMC QMC
QMA QMA QMA QMA
State Online Online Online Online Online Online Online Online
Version Earlier Earlier Earlier Earlier Earlier Earlier Earlier Latest
Node 4 version version version version version version version version
Groups QMD QMD QMD QMD QMD, QMD
QMB
Possible Owners 1,2,3,4 2,3,4 2,3,4 2,3,4 3,4 1,2 1,2,3 1,2,3,4
Task Update 1 Update 2 Transfer Update 3 Update 4

What to do next
Additional considerations in an MSCS setup with more than 2 nodes: A cluster might contain enough
nodes for you to form a group of migrated queue managers and a group of unmigrated nodes. Switch to
the migrated group when it contains half the number of queue managers. Before you have reached the
half way point, the unmigrated group are possible owners. When you reach the half way point, switch the
possible owners to the migrated group.
Related concepts
Windows: MSCS restriction with multiple installations
Related tasks
“Migrating a queue manager in a high-availability configuration” on page 457
High-availability configurations of queue managers can increase the availability of IBM MQ applications. If
a queue manager, or server fails, it is restarted automatically on another server. You can arrange for IBM
MQ MQI client applications to automatically reconnect to the queue manager. Server applications can be
configured to start when the queue manager starts.

Migrating logs to an Advanced Format disk on Windows

An Advanced Format disk is one that has 4096 bytes per sector. The following is applicable only to the
Windows platform as Advanced Format disks can be used on other platforms without carrying out a
migration procedure.
Attention: On Windows, prior to IBM MQ 9.1.0, (or prior to IBM MQ 9.0.4 if you are a Continuous
Delivery user), IBM MQ does not support Advanced Format disks
Note the following:
• A migrated log can be used on any disk whether or not it is Advanced Format.
• If you are not using an Advanced Format disk, you do not need to migrate the log of your queue
manager.
• Queue managers that are created at IBM MQ 9.1.0 (or at IBM MQ 9.0.4 or later if you are a Continuous
Delivery user) can be used on an Advanced Format disk without being migrated.
• If you use a queue manager that was created before IBM MQ 9.1.0 (or before IBM MQ 9.0.4 if you are a
Continuous Delivery user) on a native Advanced Format disk, without migrating the queue manager first,
the queue manager will not start
• It is possible to start a queue manager on an Advanced Format disk in emulation mode without
migration. However IBM MQ log writes will not be on 4k boundaries and so the queue manager will not

Installing and migrating 403

 have data integrity. Once the logs have been migrated, an Advanced Format disk in emulation mode is
reliable.
• If you are not sure whether your disk is Advanced Format or not, use the Windows utility fsutil to find
out.
• The Advanced Format disks that require you to migrate your log, include 4k native disks and 512-byte
Emulation disks.
• Using migmqlog to change from linear logging to circular logging, or from circular logging to linear
logging, also migrates the log so that the log can be used on an Advanced Format disk.
Related information
Changing your queue manager log from linear to circular
Changing your queue manager log from circular to linear

Migrating IBM MQ on AIX and Linux

Migration tasks associated with AIX and Linux platforms are grouped in this section.

Before you begin

If you are migrating to IBM MQ 9.4 or later from IBM WebSphere MQ 7.5 or earlier, you must first migrate
to an interim version. See Migration paths.
Important:

• The IBM MQ Bridge to Salesforce is deprecated across all releases from November 22
2022 (see US Announcement letter 222-341).

• The IBM MQ Bridge to Salesforce is removed from the product

at IBM MQ 9.4.0. Salesforce connectivity can be achieved with IBM App Connect Enterprise. Salesforce
Input and Salesforce Request nodes can be used to interact with Salesforce applications. For more
information, see Using Salesforce with IBM App Connect Enterprise.
On Linux for x86-64 only, if you are migrating from an installation where the IBM MQ Bridge to
Salesforce is present, you must remove it before you upgrade to IBM MQ 9.4.0 or later.

• For Continuous Delivery, the IBM MQ Bridge to blockchain is removed from the product at
IBM MQ 9.3.2.

For Long Term Support, IBM MQ Bridge to blockchain is removed at IBM MQ 9.3.0 Fix Pack
15.
Blockchain connectivity can be achieved with IBM App Connect or through App Connect capabilities
available with IBM Cloud Pak for Integration.
On Linux for x86-64 only, if you are migrating from an installation where the IBM MQ Bridge to
blockchain is present, you must remove it before you upgrade to IBM MQ 9.4.0 or later.
• From IBM MQ 9.3.0, IBM MQ Explorer has been removed from the IBM MQ installation package. It
remains available as a separate download, and can be installed from the stand-alone IBM MQ Explorer
download available from Fix Central. On Linux for x86-64 only, if you are migrating from an installation
where the IBM MQ Explorer is present as part of the IBM MQ installation, you must remove it before you
upgrade to IBM MQ 9.3.0 or later.

Important: From IBM MQ 9.4.0, AMQP channels no longer support CMS key
repository files. If you are migrating a queue manager with an AMQP configuration to IBM MQ 9.4.0 or
later, and your queue manager is currently configured with a CMS keystore, you must convert it to PKCS12
format before proceeding with the migration. For more information on how to perform this conversion, see
SSL/TLS support in Securing AMQP Clients.

404 Installing and migrating IBM MQ

About this task
This topic lists the various steps you need to take to migrate to, or migrate from, the latest version of the
IBM MQ product.
If you are migrating a Continuous Delivery release of the product, see also “Migrating from one
Continuous Delivery release to another” on page 371.
If you want to migrate replicated data queue managers, follow the instructions in “Migrating replicated
data queue managers” on page 460.
Related concepts
“Migration concepts and methods” on page 340
An overview of the various concepts and methods for migrating from one release of the product to
another.
Related tasks
“Migrating IBM MQ on IBM i” on page 429
IBM MQ migration tasks associated with IBM i are grouped in this section.
“Migrating IBM MQ on Windows” on page 372
IBM MQ migration tasks associated with Windows platforms are grouped in this section.
Related reference
“Changes that affect migration” on page 337

Planning to migrate IBM MQ to a later version on AIX and Linux

Before migrating IBM MQ to a later version on AIX and Linux, review the system requirements
information, and the information about any changes that might affect migration, then create a migration
plan.

Before you begin

If there are concepts about migration you do not understand, see “Migration concepts and methods” on
page 340.
If you are migrating to IBM MQ 9.4 or later from IBM WebSphere MQ 7.5 or earlier, you must first migrate
to an interim version. See Migration paths.

About this task

Use the following steps as a guide to creating a migration plan.

Procedure
1. Review the IBM MQ system requirements for the later version of the product.
See System Requirements for IBM MQ.
2. Decide whether to run the earlier version and the later version of the product on the same server, and
also which migration method you want to use.
Choices are single-stage migration, side-by-side migration, or multi-stage migration. See “Migration
methods on IBM MQ for Multiplatforms” on page 347.
3. Review all the changes in IBM MQ that affect you.
See “Changes that affect migration” on page 337.
4. Review performance changes.
See MQ Performance documents.
5. Review the readme file for the later version of IBM MQ.
See IBM MQ, WebSphere MQ, and MQSeries product readmes.

Installing and migrating 405

 6. Plan the sequence and timing of queue manager migrations.
• If the queue manager is part of a queue manager cluster, you must migrate the queue managers
that are full repositories first.
• If the queue manager is part of a high availability cluster, plan the migration to minimize downtime
and maximize availability; see “Migrating a queue manager in a high-availability configuration” on
page 457.
7. Plan to migrate your queue manager to the later version.
See “Migrating a queue manager to a later version on AIX and Linux” on page 406.
Backing up queue manager data is part of the queue manager migration task. An alternative approach
is to install and configure a new server, then test the later version with a new queue manager on the
new server. When you are ready to go into production on the later version, copy the queue manager
configuration and data to the new server.
8. Plan to update any manual or automated procedures you have written with changes to messages and
codes.
A suffix letter, indicating the severity of a message (I, W, E, S or T) is appended to IBM MQ diagnostic
(AMQ) messages. Existing scripts looking for error codes without the severity will fail. For example,
existing scripts looking for error matching to AMQ7468 will fail. You must update the scripts to look
for error codes with the severity suffix added (for example, AMQ7468I). For more information, see
IBM MQ messages on Multiplatforms.
9. Decide on what regression tests to perform before putting the queue manager into production on
the later version. Include in your regression tests the procedures and applications you identified in
previous steps.
10. Plan to migrate your IBM MQ MQI client installations to the later version.
11. Plan to migrate your client and server applications to use new functions in the later version.
12. Decide which downloadable images you require for the migration.
For more information, see “Where to find downloadable installation images” on page 9.

Migrating a queue manager on AIX and Linux

The procedures for migrating a queue manager to a later version of the product, and for restoring a queue
manager to an earlier version of the product are detailed in this section.
Related tasks
“Migrating a queue manager to the latest version on IBM i” on page 432
Follow these instructions to migrate a queue manager on IBM i to the latest MQ version.
“Migrating a queue manager on Windows” on page 378
The procedures for migrating a queue manager to a later version of the product, and for restoring a queue
manager to an earlier version of the product are detailed in this section.

Migrating a queue manager to a later version on AIX and Linux

On AIX and Linux, you can migrate a queue manager from an earlier version to a later version of IBM MQ
in one of three ways: single-stage, side-by-side, or multi-stage.
If you have installed early support program code on the server, you must delete all the queue managers
created with the installation. Uninstall the code before proceeding with installing the production level
code.

Single-stage migration
Single-stage migration is the term used to describe replacing the only installation of IBM MQ on a server,
with a later release. Single stage migration is also known as upgrading in place or in place upgrade.
Single-stage migration preserves existing scripts and procedures for running IBM MQ the most. With other
migration scenarios you might change some scripts and procedures, but you can reduce the effect queue
manager migration has on users.

406 Installing and migrating IBM MQ

The advantage of single-stage migration is that it changes the configuration of a queue manager on the
earlier version as little as possible. Existing applications automatically switch from loading the libraries
from the earlier version to loading the libraries of the later version. Queue managers are automatically
associated with the installation on the later version. Administrative scripts and procedures are affected as
little as possible by setting the installation to be the primary installation. If you set the installation of the
later version to be the primary installation, commands such as strmqm work without providing an explicit
path to the command.
For more information about performing a single-stage migration, see “Migrating on AIX and Linux: single-
stage” on page 407.

Side-by-side migration
Side-by-side migration is the term used to describe installing a later version of IBM MQ alongside
an earlier version on the same server. Queue managers remain running during the installation and
verification of the later version of IBM MQ. They remain associated with the earlier version of IBM
MQ. When you decide to migrate queue managers to the later version of IBM MQ, you stop all queue
managers, uninstall the earlier version, and migrate them all to the later version of IBM MQ.
The advantage the side-by-side scenario has over the single-stage scenario is that you can install and
verify the installation of the later version of the product on the server before switching over to it.
The side-by-side migration scenario is less flexible than multi-stage migration, and might not seem to
have any advantages over it. However, side-by-side migration does have advantages over the multi-stage
and single-stage approaches. With the side-by-side approach, because you uninstall the earlier version
before starting any queue managers, you can assign an installation on the later version to be the primary
installation. In the multi-stage approach, you cannot set an installation of the later version to be the
primary installation while you continue to run the earlier version. With the later version having the primary
installation, many applications restart without reconfiguring their environment, making the migration
process simpler.
For more information about performing a side-by-side migration, see “Migrating on AIX and Linux: side-
by-side” on page 411.

Multi-stage migration
Multi-stage migration is the term used to describe running a later version of IBM MQ alongside an earlier
version on the same server. After installing the later version alongside the earlier version, you can create
new queue managers to verify the installation of the later version, and develop new applications. At the
same time, you can migrate queue managers and their associated applications from the earlier version
to the later version. By migrating queue managers and applications one-by-one, you can reduce the peak
workload on staff managing the migration. When migration to the later version is complete, you can
uninstall the earlier version, and make the later version installation the primary installation.
For more information about performing a multi-stage migration, see “Migrating on AIX and Linux: multi-
stage” on page 415.
Backing up and restoring a queue manager
IBM MQ release types and versioning

Migrating on AIX and Linux: single-stage

Single-stage migration is the term used to describe replacing the only installation of IBM MQ on a server,
with a later release. Single stage migration is also known as upgrading in place or in place upgrade.
Single-stage migration preserves existing scripts and procedures for running IBM MQ the most. With other
migration scenarios you might change some scripts and procedures, but you can reduce the effect queue
manager migration has on users.

Installing and migrating 407

 Before you begin
1. The upgrade from the earlier version to the latest version of the product requires a full migration of
queue managers. Create a migration plan. Use the planning task, “Planning to migrate IBM MQ to a
later version on AIX and Linux” on page 405, as a guide.
2. Review the IBM MQ system requirements for the later version; see System Requirements for IBM MQ.
3. Back up your system before you install a later version of IBM MQ over an earlier version. Once you
have started a queue manager you cannot revert to the previous version. If you must restore the
system, you cannot recover any work, such as changes to messages and objects, performed by the
later version of IBM MQ. For more information about backing up your system, see Backing up and
restoring IBM MQ queue manager data.
4. Review any other installed SupportPacs for their applicability to the later version.
5. If you are running on a server with multiple installations, you must identify the installation. Make sure
that the commands you enter run against the correct installation; see setmqenv.
6. From IBM MQ 9.0, the ccsid_part2.tbl file replaces the existing ccsid.tbl file, used in previous
versions of the product, to supply additional CCSID information.

Attention:
The ccsid_part2.tbl file takes precedence over the ccsid.tbl file and:
• Allows you to add or modify CCSID entries
• Specify default data conversion
• Specify data for different command levels
The ccsid_part2.tbl is applicable to the following platforms only:

• Linux - all versions

• Windows
If you have added any of your own CCSID information into your existing ccsid.tbl file,
you should copy this information into the new ccsid_part2.tbl file, if you want to take
advantage of the new formats in your customizations
Copy the required information, rather than move the information, so that your existing version
of IBM MQ continues to work.

About this task

In the single-stage migration scenario, the installation of the later version of the product replaces an
earlier version in the same installation location.
You can also migrate a queue manager to a later version of the product on a system where an earlier
version has been uninstalled. In this case, the queue manager data must have been retained, or restored
from a backup.

Procedure
1. Log in as a user in group mqm.
2. Stop all applications using the IBM MQ installation.
If you use the Managed File Transfer (MFT) component, ensure that any MFT agents have finished all
of the file transfers that they were engaged in. There should be no incomplete transfers associated
with the agents, and their SYSTEM.FTE.STATE queues should contain no messages.
3. Stop the mqweb server that is associated with the IBM MQ installation by entering the following
command:

endmqweb

408 Installing and migrating IBM MQ

4. End all the activity of queue managers associated with the IBM MQ installation.
a) List the state of all the queue managers on the system by using the dspmq command:

dspmq -a

b) List the status of listeners associated with a queue manager by using the DISPLAY LSSTATUS
MQSC command:

echo "DISPLAY LSSTATUS(*) STATUS" | runmqsc QmgrName

c) Stop any listeners associated with the queue managers, using the endmqlsr command:

endmqlsr -m QMgrName

d) Stop each running queue manager that is associated with this installation by using the endmqm
command:

endmqm QMgrName

The endmqm command informs an application that the queue manager it is connected to is
stopping; see Stopping a queue manager.
For the migration to proceed, applications must respond to an endmqm command by disconnecting
from the queue manager and releasing any IBM MQ libraries they have loaded. If they do not, you
must find another way to force applications to release IBM MQ resources, such as by stopping the
applications.
You must also stop applications that are using the client libraries that are part of the installation.
Client applications might be connected to a different queue manager, running a different
installation of IBM MQ. The application is not informed about queue managers in the current
installation being shut down.
Any applications that continue to have IBM MQ shared libraries from the installation loaded
prevent you upgrading IBM MQ. An application might disconnect from a queue manager, or be
forcibly disconnected, but keep an IBM MQ shared library loaded.
5. Back up the queue manager.
Take copies of all the queue manager's data and log file directories, including all subdirectories, and
also the qm.ini file. For more information, see Backing up and restoring IBM MQ queue manager
data.
6. Based on the version of IBM MQ that you want to migrate from, uninstall any fix packs:
• If you are migrating to IBM MQ 9.4, you must uninstall any fix packs that are installed on the
earlier IBM MQ version before you upgrade your installation.

• If you are migrating from IBM MQ 9.4 to a later version, you do not need to uninstall
fix packs before upgrading your installation.
7. Upgrade the earlier version of the product to the later version in the same installation directory.
• On AIX, upgrade to the later version in place. For more information, see “Installing IBM MQ server
on AIX” on page 42.
• On Linux, if the version that you are upgrading from is later than IBM MQ 9.2.1, upgrade to the
later version in place. For more information, see “Upgrading an IBM MQ installation on Linux” on
page 321.
• On Linux, if the version that you are upgrading from is earlier than IBM MQ 9.2.1, you must
uninstall the previous version before you install the later version. For more information, see
“Installing and uninstalling IBM MQ on Linux” on page 93.
8. Optional: Set the primary installation to avoid specifying a search path to run IBM MQ commands by
using the setmqinst command:

Installing and migrating 409

 INSTALLATION_PATH/bin/setmqinst -i -n installationName

Use the dspmqinst command to discover the InstallationName.

If there is a primary installation, AIX and Linux applications that expect to find the IBM MQ library
in /usr/lib, find a symbolic link to the library in /usr/lib/32 4 . /usr/lib/32 is normally in the
default search path. It is also specified as a load path in the IBM MQ build scripts for AIX and Linux.
It is sufficient to link applications only to /usr/lib. With a primary installation of the later version of
the product defined on the server, an application can connect to any queue manager associated with
any installation on the server. IBM MQ loads the correct library for the application.
9. Optional: Associate the queue managers with the installation by using the setmqm command:

setmqm -m qmgrName -n installationName

10. Start the queue managers and migrate them to the later version of the product by using the strmqm
command:

strmqm qmgrName

When you first start a queue manager after migration:

• Any new attributes for existing objects are set to their default values.
• Any new default objects are created.
• Queue manager data is migrated.
At this point, queue manager data is migrated and you cannot revert to a previous release.
Important: Do not use the -c option to start the queue manager, unless you explicitly want to reset
or re-create the default system objects.
You must start IBM MQ before you start any listeners.
11. Start your applications.

What to do next
You cannot reinstall an earlier version of the product on a system that has the latest, or any other, version
of IBM MQ installed.
Related concepts
“Migrating a queue manager to a later version on AIX and Linux” on page 406
On AIX and Linux, you can migrate a queue manager from an earlier version to a later version of IBM MQ
in one of three ways: single-stage, side-by-side, or multi-stage.
“Installation name on AIX, Linux, and Windows” on page 14
Each installation of IBM MQ on AIX, Linux, and Windows, has a unique identifier known as an installation
name. The installation name is used to associate things such as queue managers and configuration files
with an installation.
“Queue manager coexistence” on page 355
Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations.
“Multi-installation queue manager coexistence on AIX, Linux, and Windows” on page 357
You can install multiple copies of IBM MQ for AIX, Linux, and Windows on the same server. These IBM MQ
copies can be at the same or different version levels. This is called a multi-installation. Multi-installation is

4 /usr/lib for 64 bit applications.

410 Installing and migrating IBM MQ

particularly useful when you upgrade from one IBM MQ version to a later version, because it allows you to
run the earlier version alongside the later version.
Related tasks
Migrating on AIX and Linux: side-by-side
Migrating on AIX and Linux: multi-stage
“Planning to migrate IBM MQ to a later version on Windows” on page 373
“Migrating a queue manager to a later version on Windows” on page 378
On Windows platforms, follow these instructions to migrate a queue manager from an earlier version to a
later version of IBM MQ.
“Installing IBM MQ server on AIX” on page 42
You can install an IBM MQ server on AIX either interactively or silently.
“Installing the first IBM MQ installation on Linux using the rpm command” on page 111
You can install an IBM MQ server on a 64-bit Linux system using rpm. The instructions in this topic are for
the first installation of IBM MQ on a Linux system.
Associating a queue manager with an installation
Changing the primary installation
“Migrating IBM MQ library loading to a later version on AIX and Linux” on page 424
On AIX and Linux, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to a later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
“Migrating IBM MQ library loading to a later version on Windows” on page 396
On Windows, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to the later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
Related reference
setmqenv
setmqinst
setmqm

Migrating on AIX and Linux: side-by-side

Side-by-side migration is the term used to describe installing a later version of IBM MQ alongside
an earlier version on the same server. Queue managers remain running during the installation and
verification of the later version of IBM MQ. They remain associated with the earlier version of IBM
MQ. When you decide to migrate queue managers to the later version of IBM MQ, you stop all queue
managers, uninstall the earlier version, and migrate them all to the later version of IBM MQ.

Before you begin

1. The upgrade from the earlier version to the latest version of the product requires a full migration of
queue managers. Create a migration plan. Use the planning task, “Planning to migrate IBM MQ to a
later version on AIX and Linux” on page 405, as a guide.
2. Review the IBM MQ system requirements for the later version; see System Requirements for IBM MQ.
3. Back up your system before you install a later version of IBM MQ over an earlier version. Once you
have started a queue manager you cannot revert to the previous version. If you must restore the
system, you cannot recover any work, such as changes to messages and objects, performed by the
later version of IBM MQ. For more information about backing up your system, see Backing up and
restoring IBM MQ queue manager data.

Installing and migrating 411

 4. Review any other installed SupportPacs for their applicability to the later version.
5. If you are running on a server with multiple installations, you must identify the installation. Make sure
that the commands you enter run against the correct installation; see setmqenv.
6. From IBM MQ 9.0, the ccsid_part2.tbl file replaces the existing ccsid.tbl file, used in previous
versions of the product, to supply additional CCSID information.

Attention:
The ccsid_part2.tbl file takes precedence over the ccsid.tbl file and:
• Allows you to add or modify CCSID entries
• Specify default data conversion
• Specify data for different command levels
The ccsid_part2.tbl is applicable to the following platforms only:

• Linux - all versions

• Windows
If you have added any of your own CCSID information into your existing ccsid.tbl file,
you should copy this information into the new ccsid_part2.tbl file, if you want to take
advantage of the new formats in your customizations
Copy the required information, rather than move the information, so that your existing version
of IBM MQ continues to work.

About this task

In the side-by-side migration scenario, you install the later version of IBM MQ alongside queue managers
that continue to be associated with the installation of the earlier version of the product. When you are
ready to migrate the queue managers, and applications, to the later version:
1. Stop all the queue managers.
2. Uninstall the earlier version of the product.
3. Migrate all the queue managers and applications to the later version.

Procedure
1. Install the later version in a different installation directory from the earlier version.
a) Decide on an installation naming convention. Give the installation a name of your choosing, or
accept the default installation name.
For the first installation, the default name is Installation1. For the second installation, the name is
Installation2, and so on.

On AIX there is no option to set the installation name, Installation1 is set by default.
b) Install the later version. For more information see, “Installing IBM MQ server on AIX” on page 42 or
“Installing additional IBM MQ installations on Linux using the rpm command” on page 115.
c) Verify the installation.
Run the installation verification procedures and your own tests.
2. Uninstall the earlier version of the product.
When uninstalling the earlier product, you must stop all queue managers and applications that
have loaded an IBM MQ library on the server. For this reason, you might choose to postpone
uninstalling the earlier version of the product until a convenient maintenance window. When
an earlier version of the product is not installed on a server, it is sufficient to stop the queue
managers and applications that have loaded libraries from the installation that you are uninstalling

412 Installing and migrating IBM MQ

 or updating. It is not necessary to stop applications and queue managers associated with other
installations.
a) Log in as a user in group mqm.
b) Stop all applications using the IBM MQ installation.
If you use the Managed File Transfer (MFT) component, ensure that any MFT agents have finished
all of the file transfers that they were engaged in. There should be no incomplete transfers
associated with the agents, and their SYSTEM.FTE.STATE queues should contain no messages.
c) Stop the mqweb server that is associated with the IBM MQ installation by entering the following
command:

endmqweb

d) List the state of all the queue managers on the system by using the dspmq command:

dspmq -a

e) List the status of listeners associated with a queue manager by using the DISPLAY LSSTATUS
MQSC command:

echo "DISPLAY LSSTATUS(*) STATUS" | runmqsc QmgrName

f) Stop any listeners associated with the queue managers, using the endmqlsr command:

endmqlsr -m QMgrName

g) Stop each running queue manager that is associated with this installation by using the endmqm
command:

endmqm QMgrName

h) Uninstall the earlier version of the product. For more information, see “Uninstalling or modifying
IBM MQ on Linux” on page 150
3. Set the primary installation to avoid specifying a search path to run IBM MQ commands by using the
setmqinst command:

INSTALLATION_PATH/bin/setmqinst -i -n installationName

Use the dspmqinst command to discover the InstallationName.

If there is a primary installation, AIX and Linux applications that expect to find the IBM MQ library
in /usr/lib, find a symbolic link to the library in /usr/lib/32 5 . /usr/lib/32 is normally in the
default search path. It is also specified as a load path in the IBM MQ build scripts for AIX and Linux.
It is sufficient to link applications only to /usr/lib. With a primary installation of the later version of
the product defined on the server, an application can connect to any queue manager associated with
any installation on the server. IBM MQ loads the correct library for the application.
4. Optional: Associate the queue managers with the installation by using the setmqm command:

setmqm -m qmgrName -n installationName

5. Start the queue managers and migrate them to the later version of the product by using the strmqm
command:

strmqm qmgrName

5 /usr/lib for 64 bit applications.

Installing and migrating 413

 When you first start a queue manager after migration:
• Any new attributes for existing objects are set to their default values.
• Any new default objects are created.
• Queue manager data is migrated.
At this point, queue manager data is migrated and you cannot revert to a previous release.
Important: Do not use the -c option to start the queue manager, unless you explicitly want to reset or
re-create the default system objects.
You must start IBM MQ before you start any listeners.
6. Start your applications.

What to do next
You cannot reinstall an earlier version of the product on a system that has the latest, or any other, version
of IBM MQ installed.
Related tasks
Migrating on AIX and Linux: single-stage
Single-stage migration is the term used to describe replacing the only installation of IBM MQ on a server,
with a later release. Single stage migration is also known as upgrading in place or in place upgrade.
Single-stage migration preserves existing scripts and procedures for running IBM MQ the most. With other
migration scenarios you might change some scripts and procedures, but you can reduce the effect queue
manager migration has on users.
Migrating on AIX and Linux: multi-stage
“Planning to migrate IBM MQ to a later version on Windows” on page 373
“Installing IBM MQ server on AIX” on page 42
You can install an IBM MQ server on AIX either interactively or silently.
“Uninstalling or modifying IBM MQ on AIX” on page 59
On AIX, you can uninstall the IBM MQ server or client using the System Management Interface Tool
(SMIT) or the installp command. You can also modify an installation by uninstalling a subset of the file
sets.
“Installing the first IBM MQ installation on Linux using the rpm command” on page 111
You can install an IBM MQ server on a 64-bit Linux system using rpm. The instructions in this topic are for
the first installation of IBM MQ on a Linux system.
“Uninstalling or modifying IBM MQ on Linux using rpm” on page 150
On Linux, you can uninstall the IBM MQ server or client by using the rpm command. You can also modify
an installation by removing selected packages (components) currently installed on your system.
Associating a queue manager with an installation
Changing the primary installation
“Installation name on AIX, Linux, and Windows” on page 14
Each installation of IBM MQ on AIX, Linux, and Windows, has a unique identifier known as an installation
name. The installation name is used to associate things such as queue managers and configuration files
with an installation.
“Queue manager coexistence” on page 355
Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations.
“Migrating IBM MQ library loading to a later version on AIX and Linux” on page 424
On AIX and Linux, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to a later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration

414 Installing and migrating IBM MQ

scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
“Migrating IBM MQ library loading to a later version on Windows” on page 396
On Windows, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to the later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
“Multi-installation queue manager coexistence on AIX, Linux, and Windows” on page 357
You can install multiple copies of IBM MQ for AIX, Linux, and Windows on the same server. These IBM MQ
copies can be at the same or different version levels. This is called a multi-installation. Multi-installation is
particularly useful when you upgrade from one IBM MQ version to a later version, because it allows you to
run the earlier version alongside the later version.
setmqenv
setmqinst
setmqm

Migrating on AIX and Linux: multi-stage

Multi-stage migration is the term used to describe running a later version of IBM MQ alongside an earlier
version on the same server. After installing the later version alongside the earlier version, you can create
new queue managers to verify the installation of the later version, and develop new applications. At the
same time, you can migrate queue managers and their associated applications from the earlier version
to the later version. By migrating queue managers and applications one-by-one, you can reduce the peak
workload on staff managing the migration. When migration to the later version is complete, you can
uninstall the earlier version, and make the later version installation the primary installation.

Before you begin

1. The upgrade from the earlier version to the latest version of the product requires a full migration of
queue managers. Create a migration plan. Use the planning task, “Planning to migrate IBM MQ to a
later version on AIX and Linux” on page 405, as a guide.
2. Review the IBM MQ system requirements for the later version; see System Requirements for IBM MQ.
3. Back up your system before you install a later version of IBM MQ over an earlier version. Once you
have started a queue manager you cannot revert to the previous version. If you must restore the
system, you cannot recover any work, such as changes to messages and objects, performed by the
later version of IBM MQ. For more information about backing up your system, see Backing up and
restoring IBM MQ queue manager data.
4. Review any other installed SupportPacs for their applicability to the later version.
5. If you are running on a server with multiple installations, you must identify the installation. Make sure
that the commands you enter run against the correct installation; see setmqenv.
6. From IBM MQ 9.0, the ccsid_part2.tbl file replaces the existing ccsid.tbl file, used in previous
versions of the product, to supply additional CCSID information.

Attention:
The ccsid_part2.tbl file takes precedence over the ccsid.tbl file and:
• Allows you to add or modify CCSID entries
• Specify default data conversion
• Specify data for different command levels
The ccsid_part2.tbl is applicable to the following platforms only:

• Linux - all versions

Installing and migrating 415

 • Windows
If you have added any of your own CCSID information into your existing ccsid.tbl file,
you should copy this information into the new ccsid_part2.tbl file, if you want to take
advantage of the new formats in your customizations
Copy the required information, rather than move the information, so that your existing version
of IBM MQ continues to work.
Note: If you are running the IBM MQ.NET monitor in transactional mode, the queue manager it connects
to must be the primary installation.

About this task

With the multi-stage approach, until you uninstall the earlier version , you must configure an environment
to run applications that connect to a queue manager to the later version. You must also provide a path to
run IBM MQ commands. Both these tasks are accomplished with the setmqenv command.
Note: When you have uninstalled the earlier version, and set the later version as a primary installation,
in most circumstances it is not necessary to run the setmqenv command to run applications. It is still
necessary to run setmqenv to set the environment for commands that connect to a queue manager
associated with an installation that is not primary.

Procedure
1. Install the later version in a different installation directory from the earlier version and verify the
installation.
a) Decide on an installation naming convention. Give the installation a name of your choosing, or
accept the default installation name.
For the first installation, the default name is Installation1. For the second installation, the name is
Installation2, and so on.

On AIX there is no option to set the installation name, Installation1 is set by default.
b) Install the later version. For more information see, “Installing IBM MQ server on AIX” on page 42 or
“Installing additional IBM MQ installations on Linux using the rpm command” on page 115.
c) Verify the installation.
Run the installation verification procedures and your own tests.
2. Configure the operating system so that applications load the libraries for the later version of the
product.
a) Migrate queue managers one at a time.
The first set of applications to load the libraries for the later version of the product are the
applications that connect to the first queue manager you are going to migrate.
It does not matter if those applications also connect to other queue managers on the server. If the
applications load the later version libraries, IBM MQ automatically loads the libraries for the earlier
version for those applications that connect to that version.
You can either migrate the operating system environment of all applications, or just the applications
that connect to the first queue manager you are going to migrate.
b) Migrate IBM MQ MQI client applications
Some of the applications might be running as IBM MQ MQI client applications on another
workstation. When you migrate a queue manager, clients connected to it continue to run without
loading a client library for the later version.
You can migrate these clients later, when you need to do so.

416 Installing and migrating IBM MQ

 Important: If any IBM MQ MQI client applications are using the library for the earlier version on the
server, you must eventually migrate the clients to use the later version of the product before you
uninstall the earlier version.
3. Migrate an application to load the new library for the later version:
• Run setmqenv to modify the local path that is searched for IBM MQ libraries.
• Modify the global search path that is searched for IBM MQ libraries.
• Relink applications with an additional runtime load path.
Consult operating system documentation about how to modify the global search path, or include a
fixed runtime load path in the application load module.
To run setmqenv using the -s option:

.Inst_1_INSTALLATION_PATH/bin/setmqenv -s -k

The -s option sets up the environment for the installation that runs the setmqenv command.
The -k option inserts the path to the IBM MQ load libraries at the start of the LD_LIBRARY_PATH
environment variable, and adds the variable to the local environment; see “Loading IBM MQ libraries”
on page 360.
Note: On AIX the leading "." is critical. The dot followed by a space instructs the command shell run
setmqenv in the same command shell and inherit the environment set by setmqenv.

4. Restart the queue manager and the applications that connect to it.
a) Set up the local environment to the installation Inst_1.

.Inst_1_INSTALLATION_PATH/bin/setmqenv -s

The -s option sets up the environment for the installation that runs the setmqenv command.
b) Run the setmqm command to associate QM1 with Inst_1.

setmqm -m QM1 -n Inst_1

setmqm -m QM2 -n Inst_1

c) Run the strmqm command to start QM1 and migrate it to the later version.

strmqm QM1
strmqm QM2

d) Restart application 1
The application loads the later version library and connects to QM1, which is associated with the
later version of the product.
5. Migrate all queue managers and applications to the later version.
Repeat steps “2” on page 416 and “4” on page 417, when required, until all the queue managers
and applications are migrated to the later version of the product.
6. Uninstall the earlier version of the product.
When uninstalling the earlier product, you must stop all queue managers and applications that
have loaded an IBM MQ library on the server. For this reason, you might choose to postpone
uninstalling the earlier version of the product until a convenient maintenance window. When
an earlier version of the product is not installed on a server, it is sufficient to stop the queue
managers and applications that have loaded libraries from the installation that you are uninstalling
or updating. It is not necessary to stop applications and queue managers associated with other
installations.
a) Log in as a user in group mqm.

Installing and migrating 417

 b) Stop all applications using the IBM MQ installation.
If you use the Managed File Transfer (MFT) component, ensure that any MFT agents have finished
all of the file transfers that they were engaged in. There should be no incomplete transfers
associated with the agents, and their SYSTEM.FTE.STATE queues should contain no messages.
c) Stop the mqweb server that is associated with the IBM MQ installation by entering the following
command:

endmqweb

d) List the state of all the queue managers on the system by using the dspmq command:

dspmq -a

e) List the status of listeners associated with a queue manager by using the DISPLAY LSSTATUS
MQSC command:

echo "DISPLAY LSSTATUS(*) STATUS" | runmqsc QmgrName

f) Stop any listeners associated with the queue managers, using the endmqlsr command:

endmqlsr -m QMgrName

g) Stop each running queue manager that is associated with this installation by using the endmqm
command:

endmqm QMgrName

h) Uninstall the earlier version of the product. For more information, see “Uninstalling or modifying
IBM MQ on Linux” on page 150
7. Set the primary installation to avoid specifying a search path to run IBM MQ commands by using the
setmqinst command:

INSTALLATION_PATH/bin/setmqinst -i -n installationName

If you set an installation of the later version of the product as primary on AIX and Linux, you do
not have to set up LD_LIBRARY_PATH in most cases. You can remove calls to setmqenv to set
LD_LIBRARY_PATH.

What to do next
You cannot reinstall an earlier version of the product on a system that has the latest, or any other, version
of IBM MQ installed.
Now that you have uninstalled the earlier version of the product, and made the later installation primary,
you can review how the application runtime environment is set. It is no longer necessary to run setmqenv
to set up the search path to load libraries for the later version. If you have only one installation of the later
version of the product installed, it is not necessary to run setmqenv to run commands.
Related concepts
“Installation name on AIX, Linux, and Windows” on page 14
Each installation of IBM MQ on AIX, Linux, and Windows, has a unique identifier known as an installation
name. The installation name is used to associate things such as queue managers and configuration files
with an installation.
“Queue manager coexistence” on page 355

418 Installing and migrating IBM MQ

Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations.
“Multi-installation queue manager coexistence on AIX, Linux, and Windows” on page 357
You can install multiple copies of IBM MQ for AIX, Linux, and Windows on the same server. These IBM MQ
copies can be at the same or different version levels. This is called a multi-installation. Multi-installation is
particularly useful when you upgrade from one IBM MQ version to a later version, because it allows you to
run the earlier version alongside the later version.
Related tasks
Migrating on AIX and Linux: single-stage
Single-stage migration is the term used to describe replacing the only installation of IBM MQ on a server,
with a later release. Single stage migration is also known as upgrading in place or in place upgrade.
Single-stage migration preserves existing scripts and procedures for running IBM MQ the most. With other
migration scenarios you might change some scripts and procedures, but you can reduce the effect queue
manager migration has on users.
Migrating on AIX and Linux: side-by-side
“Planning to migrate IBM MQ to a later version on Windows” on page 373
“Installing IBM MQ server on AIX” on page 42
You can install an IBM MQ server on AIX either interactively or silently.
“Installing the first IBM MQ installation on Linux using the rpm command” on page 111
You can install an IBM MQ server on a 64-bit Linux system using rpm. The instructions in this topic are for
the first installation of IBM MQ on a Linux system.
Associating a queue manager with an installation
Changing the primary installation
“Migrating IBM MQ library loading to a later version on AIX and Linux” on page 424
On AIX and Linux, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to a later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
“Migrating IBM MQ library loading to a later version on Windows” on page 396
On Windows, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to the later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
Related reference
setmqenv
setmqinst
setmqm

Reverting a queue manager to an earlier version on AIX and Linux

On AIX and Linux, you can revert a queue manager to an earlier version of the product from a later
version, if you have made a backup of the system or queue manager. If you have started the queue
manager and processed any messages, or changed the configuration, the task cannot give you any
guidance on reverting the current state of the queue manager.

Before you begin

1. You must have made a backup of the system or queue manager before you upgraded to the later
version. For more information see Backing up and restoring IBM MQ queue manager data

Installing and migrating 419

 2. If any messages were processed after starting the queue manager, you cannot easily undo the effects
of processing the messages. You cannot revert the queue manager to the earlier version of the product
in its current state. The task cannot give you any guidance how to deal with subsequent changes that
have occurred. For example, messages that were indoubt in a channel, or in a transmission queue on
another queue manager, might have been processed. If the queue manager is part of a cluster, then
configuration messages and application messages might have been exchanged.
3. If you are running on a server with multiple IBM MQ installations, you must identify the installation.
Make sure that the commands you enter run against the correct installation; see setmqenv.

About this task

When you revert to a earlier version of a queue manager, you revert the queue manager to its earlier code
level. Queue manager data is reverted to the state it was in when the queue manager was backed up.
Important: If the queue manager is a member of one or more IBM MQ clusters, you should also review
and follow the steps described in Recovering a cluster queue manager.

Procedure
1. Log in as a user in group mqm.
2. Stop all applications using the IBM MQ installation.
If you use the Managed File Transfer (MFT) component, ensure that any MFT agents have finished all of
the file transfers that they were engaged in. There should be no incomplete transfers associated with
the agents, and their SYSTEM.FTE.STATE queues should contain no messages.
3. End all the activity of queue managers associated with the IBM MQ installation.
a) Run the dspmq command to list the state of all the queue managers on the system.
Run either of the following commands from the installation that you are updating:

dspmq -o installation -o status

dspmq -a

dspmq -o installation -o status displays the installation name and status of queue
managers associated with all installations of IBM MQ.
dspmq -a displays the status of active queue managers associated with the installation from
which the command is run.
b) Use the MQSC command DISPLAY LSSTATUS to list the status of listeners associated with a
queue manager, as shown in the following example:

echo "DISPLAY LSSTATUS(*) STATUS" | runmqsc QmgrName

c) Run the endmqm command to stop each running queue manager associated with this installation.
-c
endmqm -w QmgrName

-i
-p

The endmqm command informs an application that the queue manager it is connected to is
stopping; see Stopping a queue manager.
For the maintenance to proceed, applications must respond to an endmqm command by
disconnecting from the queue manager and releasing any IBM MQ libraries they have loaded. If
they do not, you must find another way to force applications to release IBM MQ resources, such as
by stopping the applications.

420 Installing and migrating IBM MQ

 You must also stop applications that are using the client libraries that are part of the installation.
Client applications might be connected to a different queue manager, running a different
installation of IBM MQ. The application is not informed about queue managers in the current
installation being shut down.
Any applications that continue to have IBM MQ shared libraries from the installation loaded prevent
you applying IBM MQ maintenance. An application might disconnect from a queue manager, or be
forcibly disconnected, but keep an IBM MQ shared library loaded.
Note: “Applying maintenance level updates to multi-instance queue managers on AIX” on page
289 and “Applying maintenance level updates to multi-instance queue managers on Linux” on
page 299 describe how to apply maintenance to a multi-instance queue manager. A multi-instance
queue manager can continue to run on one server, while maintenance is applied to another server.
d) Stop any listeners associated with the queue managers, using the command:

endmqlsr -m QMgrName

4. Restore the system, or IBM MQ and the queue manager.

If your backup procedure was to save the queue manager data, you must reinstall IBM MQ:
a) Uninstall the earlier installation.
b) Reinstall the product from a manufacturing refresh.
c) Apply the fix pack and interim fixes that restore IBM MQ to its previous level.
d) Restore the queue manager data from the backup taken before installing the later version.
5. Restart the earlier version queue manager.

What to do next
You might be reverting to a earlier version on a server with multiple IBM MQ installations. If one of
the installations is primary, after reverting the earlier version that installation, by default, becomes the
primary installation.
You must review how applications connect to an installation. After reverting to the earlier version, some
applications might connect to the wrong installation.
Related concepts
Backing up and restoring a queue manager
Related reference
Avoiding BFGSS0023E errors when removing fix packs

Migrating an IBM MQ MQI client on AIX and Linux

Before migrating an IBM MQ MQI client, create a migration plan. Stop all IBM MQ activity on the
client workstation. Upgrade the IBM MQ MQI client installation. Make any essential configuration and
application changes.
Related concepts
“IBM MQ MQI client migration” on page 344
IBM MQ MQI client migration is the process of converting IBM MQ MQI client configurations, and client
and server channels from one version to another. Client migration can take place after upgrading the IBM
MQ MQI client, and is reversible.
Related tasks
“Migrating an IBM MQ MQI client to the latest version on IBM i” on page 446
Before migrating an IBM MQ MQI client, create a migration plan. Stop all IBM MQ activity on the
client workstation. Upgrade the IBM MQ MQI client installation. Make any essential configuration and
application changes.
“Migrating an IBM MQ MQI client on Windows” on page 395

Installing and migrating 421

 Before migrating an IBM MQ MQI client, create a migration plan. Stop all IBM MQ activity on the
client workstation. Upgrade the IBM MQ MQI client installation. Make any essential configuration and
application changes.

Migrating an IBM MQ MQI client to a later version on AIX and Linux

To upgrade a client to a later version of the product on AIX and Linux, you must first stop all IBM MQ
activity on the workstation, then uninstall the earlier version and install the later version. After you have
upgraded the client, you can then make any essential configuration and application changes.

Before you begin

Before migrating an IBM MQ MQI client on AIX and Linux, first create a migration plan. For guidance on
what to include in the plan, see “Planning to migrate IBM MQ to a later version on AIX and Linux” on page
405, as a guide.

About this task

IBM MQ MQI client migration is the process of converting IBM MQ MQI client configurations, and client
and server channels from one version to another. Client migration is reversible. It is optional and manual
on a client workstation and is required and automatic on the IBM MQ server.
You must upgrade an IBM MQ MQI client before migrating a client workstation to make use of new
configuration options. You can make configuration changes to client and server connection channels on
the server, but they have no effect on a client workstation until the client is upgraded.

Procedure
1. Review the IBM MQ system requirements for the later version of the product.
See System Requirements for IBM MQ.See “IBM MQ components and features” on page 6 and “Where
to find downloadable installation images” on page 9.
2. Review all the changes in IBM MQ that affect you.
See “Changes that affect migration” on page 337.
3. End all IBM MQ activity on the workstation.
You are now ready to upgrade the client. Follow the instructions for the appropriate platform that your
enterprise uses.

4.
To upgrade the client on AIX:
a) Uninstall your existing IBM MQ client installation.
For more information, see “Uninstalling or modifying IBM MQ on AIX” on page 59.
b) Follow the client installation procedure to install the upgraded version of the IBM MQ client:
• For a client installation on a workstation, see “Installing an IBM MQ client on AIX” on page 47
• For a client installation on an IBM MQ server, see Installing IBM MQ clients and servers on the
same system.

5.
To upgrade the client on Linux:
a) Uninstall your existing IBM MQ client installation.
For more information, see “Uninstalling or modifying IBM MQ on Linux” on page 150.
b) Follow the client installation procedure to install the upgraded version of the IBM MQ client:
• For a client installation on a workstation, see “Installing an IBM MQ client on Linux using rpm” on
page 118.

422 Installing and migrating IBM MQ

 • For a client installation on an IBM MQ server, see Installing IBM MQ clients and servers on the
same system.

What to do next
After upgrading the IBM MQ MQI client, you must check the client channel configuration, and verify that
your IBM MQ MQI client applications work correctly with the later version of the product.
Related concepts
“IBM MQ MQI client migration” on page 344
IBM MQ MQI client migration is the process of converting IBM MQ MQI client configurations, and client
and server channels from one version to another. Client migration can take place after upgrading the IBM
MQ MQI client, and is reversible.
Related tasks
“Planning to migrate IBM MQ to a later version on AIX and Linux” on page 405

Restoring an IBM MQ MQI client to an earlier version on AIX and Linux

To revert a client to an earlier version of the product on AIX and Linux, you must uninstall the later
version, and then install the earlier version.

About this task

If you revert an IBM MQ MQI client and client connection to an earlier code level, you must undo the
configuration changes manually.
It is unusual to revert earlier IBM MQ MQI client libraries to a workstation.

Procedure
1. End all IBM MQ activity on the workstation.
You are now ready to restore the client to the earlier version. Follow the instructions for the
appropriate platform that your enterprise uses.

2.
To revert the client to the earlier version on AIX:
a) Uninstall the IBM MQ MQI client code for the later version.
For more information, see “Uninstalling or modifying IBM MQ on AIX” on page 59.
b) Follow the client installation procedure to install the IBM MQ MQI client for the earlier version.
For more information, see the client installation procedure for the earlier version that you want to
install.

3.
To revert the client to the earlier version on Linux:
a) Uninstall the IBM MQ MQI client code for the later version.
For more information, see “Uninstalling or modifying IBM MQ on Linux” on page 150.
b) Follow the client installation procedure to install the IBM MQ MQI client for the earlier version:
For more information, see the client installation procedure for the earlier version that you want to
install.
4. If you configured a Client Connection Definition Table (CCDT) for a queue manager using the later
version, revert to using a table created by a queue manager for the earlier version.
If a client uses CCDT to connect to a queue manager, the CCDT can be at a version greater than, less
than, or equal to that of the client. For more information, see MQI client: Client Channel Definition
Table (CCDT).

Installing and migrating 423

 Migrating IBM MQ library loading to a later version on AIX and
Linux
On AIX and Linux, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to a later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.

Before you begin

To migrate applications from an earlier version of the product to the later version, you must know how
the operating system loads an IBM MQ library for an application. Is the load path fixed by the application,
and can you set the path in an environment variable? It is not essential to know the name of the IBM MQ
library that the application loads. The library name does not change from an earlier version of the product
to the later version, although the contents of the library do.
Read “Multi-installation queue manager coexistence on AIX, Linux, and Windows” on page 357 before
starting this task.
Plan and install the later version of IBM MQ, and remember the installation name and whether the
installation was set to primary.

About this task

To migrate an application from an earlier version of the product to the later version, you do not have to
recompile or relink the application, because the IBM MQ libraries are compatible with later versions; see
“Application compatibility and interoperability with later versions of IBM MQ” on page 367.
The build procedure for IBM MQ applications is to include an explicit library path to the location of the
IBM MQ libraries, and to /usr/lib, in the link step of the compiler, as shown in Figure 13 on page 424.
The build procedure is the same for the later version of the product.

gcc -m32 -o amqsput_32_r amqsput0.c -I/opt/mqm/inc -L/opt/mqm/lib

-Wl,-rpath=/opt/mqm/lib -Wl,-rpath=/usr/lib -lmqm_r -lpthread

Figure 13. Linux C server application, 32 bit, threaded compile and link

The example shown in Figure 13 on page 424 is for Linux, but the build step for AIX is similar.
If you have followed this build procedure in the earlier release, then the effect of installing the later
version of the product on the libraries that are loaded depends on which migration scenario that you are
following:
Single-stage scenario
If you are replacing an earlier version of the product with the later version, based on the single stage
scenario described in “Migrating on AIX and Linux: single-stage” on page 407, you do not, in most
cases, need to make any changes to the way IBM MQ libraries are loaded. The possible exception to
this is if you changed the location of the libraries from the earlier version, or created symbolic links to
the libraries.
Side-by-side and Multi-stage scenarios
If you have chosen a multi-installation approach to installing the later version of the product, based
either on the side-by-side scenario described in “Migrating on AIX and Linux: side-by-side” on page
411, or the multi-stage migration scenario described in “Migrating on AIX and Linux: multi-stage” on
page 415, you must investigate whether applications connecting to the later version of the product
are linked to, and load libraries from, the correct installation and then modify the environment for the
operating system to resolve IBM MQ dependencies for an application as appropriate. Typically, you

424 Installing and migrating IBM MQ

 can modify the runtime environment, rather than relink the application. You can use the following two
commands to assist you in configuring the runtime environment:
• setmqinst sets the primary installation; see setmqinst.
• setmqenv initializes the command environment by setting environment variables; see setmqenv.
Table 42 on page 425 summarizes the actions needed for each of these scenarios. The examples in Table
42 on page 425 are all based on Linux, but the actions for AIX are similar.

Table 42. AIX and Linux configurations

Scenario Latest version replaces Latest version replaces Latest version alongside
Actio earlier version in the same earlier version in a earlier version
n location different location
Multi-stage
Single-stage Side-by-side

setmqinst makes the later version installation primary. No. The later version
Symbolic links to the IBM MQ link libraries are inserted installation can be primary,
setmqinst
into /usr/lib. because an earlier version is
installed.

No other Library loading works Library loading works The library loading continues
configuration correctly. correctly. to work with the earlier version
actions correctly, nothing works with
Library loading works, Library loading works,
the later version.
even without the later because the installation is
version installation being primary, and the application
made primary, because was built with the link
the libraries are installed option, -rpath=/usr/lib.
in /opt/mqm/lib and
the application was built
with the link option,
-rpath=/opt/mqm/lib

setmqenv, Library loading works Library loading works The library loading continues
without setting correctly. correctly. to work with the earlier version
the -k or -l correctly, nothing works with
setmqenv is unnecessary. setmqenv is unnecessary.
options. the later version.
Library loading works, Library loading works,
because the libraries are because the installation is
installed in /opt/mqm/lib primary, and the application
and the application was was built with the link
built with the link option, option, -rpath=/usr/lib.
-rpath=/opt/mqm/lib.

Installing and migrating 425

Table 42. AIX and Linux configurations (continued)

Scenario Latest version replaces Latest version replaces Latest version alongside
Actio earlier version in the same earlier version in a earlier version
n location different location
Multi-stage
Single-stage Side-by-side

setmqenv, with Library loading works correctly. Library loading works correctly,
the -k or -l both for the earlier version and
options set. the later version.
The correct earlier version
is loaded, because the later
version library loads the earlier
version library for queue
managers that have not been
migrated from the earlier
version.

The operating system finds the IBM MQ library location set by setmqenv. setmqenv adds
the location to LD_LIBRARY_PATH.

This is LIBPATH on AIX.

LD_LIBRARY_PATH is searched before paths set in the application or paths in the default
search path. Not all applications can load a library using LD_LIBRARY_PATH. In which case
the application works only if the library location is /opt/mqm/lib or /usr/lib

Procedure
1. Consider which of the following questions apply to your configuration.
• Did you follow the build procedure documented in the product documentation for the earlier version
of the product? You might be following a different build procedure tailored to your development
environment, or adapted from a development tool.
• How did you specify the load path for the earlier version?
• Is the application is loaded by another environment, such as Eclipse, or an application server? You
must modify the parameters that govern how the parent environment loads applications, not the way
the parent environment is loaded.
• What constraints and requirements do you have on how the load path is specified in the later
version? Security rules might restrict the use of LD_LIBRARY_PATH.
• Is the later version of the product installed alongside the earlier version?
2. Identify the installation of the later version of the product, from which the operating system is going to
load IBM MQ libraries:
• If you have a multiple installations of the later versions to load from a server, IBM MQ checks that
the installation the library was loaded from is the installation that is associated with any queue
manager the application calls. IBM MQ loads the correct library if the wrong library is loaded. It is
necessary to configure only one runtime environment for all IBM MQ applications.
• A typical choice is to set the primary installation. Setting an installation to be primary places
symbolic links to the IBM MQ libraries in /usr/lib. Applications built have an explicit link
to /usr/lib,and /usr/lib is also normally in the default library search path.
• If you upgraded an earlier version installation to the later version, a link path to the earlier version
installation now points to an installation containing the later version. Applications that have a fixed
linkage path to the earlier version installation now load the libraries for the later installation. They
are then switched to the installation that is associated with any queue manager they connect to.

426 Installing and migrating IBM MQ

 • If you rebuild an application, it must link to an installation of the later version.

• If you set LD_LIBRARY_PATH, or LIBPATH on AIX, you must check that the
application is able to use LD_LIBRARY_PATH. setuid or setgid, applications, or applications
built in other ways, might ignore LD_LIBRARY_PATH for security reasons.

What to do next
If you add further installations of the later version of the product, you must decide which installation to
make primary, if you have chosen to make any primary. As long as applications load IBM MQ libraries
from one of the later version installations, such as the primary installation, they can connect to queue
managers associated with any other later version installation.
Related concepts
“External library and control command links to primary installation on AIX and Linux” on page 22
On AIX and Linux platforms the primary installation is the one to which links from the /usr file system are
made. However, only a subset of those links created with previous releases are now made.
Related tasks
Connecting applications in a multiple installation environment
Changing the primary installation
Loading IBM MQ libraries
“Migrating IBM MQ library loading to a later version on Windows” on page 396
On Windows, no change in the way IBM MQ libraries are loaded is normally required if you upgrade
from an earlier version of the product to the later version by replacing an earlier version of the product
with the later version, based on the single stage scenario. However, if you choose to take advantage of
multi-installation in the later version of the product, based on the side-by-side or multi-stage migration
scenarios, you might have to configure the runtime environment differently, for the operating system to
load the later version of the IBM MQ library.
Related reference
“Coexistence” on page 354
Queue managers, with different names, can coexist on any server as long as they use the same IBM MQ
installation. On AIX, Linux, and Windows, different queue managers can coexist on the same server and
be associated with different installations. In addition to queue managers coexisting on a server, objects,
and commands must work correctly with different queue managers running at different command levels.
setmqenv
setmqinst
setmqm

Rebuilding a C++ application on Linux

C++ IBM MQ MQI client and server applications on Linux must be recompiled using GNU Compiler
Collection (GCC) 4.1.2, or later. Compilers older than GCC 4.1.2 are no longer supported. The C++ GCC
4.1.2 run time libraries, or later, must be installed in /usr/lib or /usr/lib64
If you are using one of the supported Linux distributions, the libraries are correctly installed; see System
Requirements for IBM MQ.
The GCC 4.1.2 libraries support SSL and TLS connections from an IBM MQ MQI client. SSL and TLS use
IBM Global Security Kit (GSKit) version 8, which depends on libstdc++.so.6. libstdc++.so.6 is
included in GCC 4.1.2.

Before you begin

1. Check the required level of GCC for your distribution of Linux; see System Requirements for IBM MQ.
2. If you are using SSL or TLS, also check the required level of libstdc++.so.

Installing and migrating 427

 3. Check whether the application requires rebuilding. Run the following command to display what version
of libstdc++.so the application depends upon. If the result is less than libstdc++.so.6, you
must rebuild your application.

ldd ApplicationPath

About this task

The task describes the steps required to rebuild a Linux C++ IBM MQ application. For more detailed
instructions about building Linux applications for IBM MQ ; see Building your procedural application on
Linux

Procedure
1. Check that the required GCC library is installed correctly.
Run one of the following commands:
• Check the 32 bit library on an x86 Linux system:

ls -l /usr/lib/libstdc++.so.6

• Check the 64 bit library on any other Linux system.

ls -l /usr/lib64/libstdc++.so.6

2. Check that the GCC compiler is at least at version 4.1.2

Run the following command to display the version of GCC.

gcc -v

3. Rebuild the application

The commands to compile and link Linux C++ applications are described in Building 32-bit
applications and Building 64-bit applications

What to do next
When you deploy your Linux C++ application, ensure that the same GCC runtime library is correctly
installed on the run time system.

Migrating MQ Telemetry on Linux

Follow these instructions to migrate your existing installation of MQ Telemetry on Linux to the latest
version of the product.

Before you begin

Before proceeding with this task, ensure that you back up your existing IBM MQ installation. You must
stop the MQ Telemetry service SYSTEM.MQXR.SERVICE before migrating.

About this task

The telemetry server is included in the product as an optional installation.
For IBM WebSphere MQ 7.5, the Client Software Development Kit (the telemetry clients) is also included
in the optional installation. From IBM MQ 8.0 onwards, the Client Software Development Kit is no longer
supplied as part of the product. Similar sample applications continue to be freely available from Eclipse
Paho and MQTT.org. See IBM MQ Telemetry Transport sample programs.

428 Installing and migrating IBM MQ

Because MQ Telemetry is a component of IBM MQ, MQ Telemetry can either be installed with the main
product, or installed after the main product has been installed. When you upgrade from a previous version
of the product, you must download and use the latest version of the Client Software Development Kit.
After the successful upgrade, Linux systems retain all telemetry data kept in /var/mqm. Telemetry data is
migrated to the later version of the product when the queue manager is started again.

Procedure
1. Create a migration plan.
See “Planning to migrate IBM MQ to a later version on AIX and Linux” on page 405.
2. Migrate your queue managers to the latest release.
3. “Installation considerations for MQ Telemetry” on page 250.
4. Verify that the MQ Telemetry installation was successful. See “Verifying the installation of MQ
Telemetry” on page 251.
5. If the passphrases for your MQTT TLS channels are stored in plain text, you should encrypt the
passphrases.
Before IBM MQ 9.3.0, passphrases for MQTT TLS channels were stored in plain text. From IBM MQ
9.3.0, support for the encryption of passphrases for MQTT TLS channels is provided.
Existing plain text passphrase are not changed to an encrypted form automatically. You must update
your plain text passphrases to an encrypted form. For more information on how to encrypt your
passphrases, see Encryption of passphrases for MQTT TLS channels.

Results
Message AMQ4616 indicates completion of the task. The existing MQTT channels and previous
subscriptions are still present.
Related concepts
“Installation considerations for MQ Telemetry” on page 250
MQ Telemetry is a component of the main IBM MQ product. You can choose to install MQ Telemetry when
you first install IBM MQ, or when you modify an existing IBM MQ installation.
Related tasks
“Verifying the installation of MQ Telemetry” on page 251
There are three ways to verify the installation of MQ Telemetry. Any can be used, regardless of whether
MQ Telemetry was installed as a custom installation of IBM MQ, or added to an existing installation of IBM
MQ.
“Verifying the installation of MQ Telemetry by using IBM MQ Explorer” on page 251
Use the Define sample configuration wizard and the MQTT client utility in IBM MQ Explorer to verify that
the MQ Telemetry components have installed. Also check that publish/subscribe works correctly.

Migrating IBM MQ on IBM i

IBM MQ migration tasks associated with IBM i are grouped in this section.

Procedure
• For information about creating a migration plan, see “Planning to migrate IBM MQ to a later version on
IBM i” on page 430.
• For information about migrating an IBM MQ classes for JMS and IBM MQ classes for Java client, see
“Migrating an IBM MQ classes for JMS and Java client on IBM i” on page 431.
• For information about migrating a queue manager from a previous release, see “Migrating a queue
manager to the latest version on IBM i” on page 432 and “Migrating a queue manager to a later version
on IBM i - alternative method” on page 443.

Installing and migrating 429

 • For information about upgrading an IBM MQ system, see “Upgrading an entire IBM MQ system on IBM
i” on page 445.
• For information about upgrading an IBM MQ MQI client installation, see “Migrating an IBM MQ MQI
client to the latest version on IBM i” on page 446.
• For information about converting a single instance queue manager to a multi-instance queue manager,
see “Migrating from a single instance to a multi-instance queue manager on IBM i” on page 446.
• For information about reverting a multi-instance queue manager to a single instance queue manager,
see “Reverting to a single-instance queue manager on IBM i” on page 450.
Related concepts
“Migration concepts and methods” on page 340
An overview of the various concepts and methods for migrating from one release of the product to
another.
Related tasks
“Migrating IBM MQ on AIX and Linux” on page 404
Migration tasks associated with AIX and Linux platforms are grouped in this section.
“Migrating IBM MQ on Windows” on page 372
IBM MQ migration tasks associated with Windows platforms are grouped in this section.
Related reference
“Changes that affect migration” on page 337

Planning to migrate IBM MQ to a later version on IBM i

Before migrating IBM MQ to a later version on IBM i, review the system requirements information, and the
information about any changes that might affect migration, then create a migration plan.

Before you begin

If there are concepts about migration you do not understand, see “Migration concepts and methods” on
page 340.
If you are migrating to IBM MQ 9.4 from IBM WebSphere MQ 7.1 or earlier, you must first migrate to an
interim version. See Migration paths.

About this task

Use the following steps as a guide to creating a migration plan.

Procedure
1. Review the IBM MQ system requirements for the later version of the product.
See System Requirements for IBM MQ.
2. Review all the changes in IBM MQ that affect you.
See “Changes that affect migration” on page 337.
3. Review performance changes.
See MQ Performance documents.
4. Review the readme file for the later version of IBM MQ.
See IBM MQ, WebSphere MQ, and MQSeries product readmes.
5. Plan the sequence and timing of queue manager migrations.
• If the queue manager is part of a queue manager cluster, you must migrate the queue managers
that are full repositories first.

430 Installing and migrating IBM MQ

 • If the queue manager is part of a high availability cluster, plan the migration to minimize downtime
and maximize availability; see “Migrating a queue manager in a high-availability configuration” on
page 457.
6. Plan to migrate your queue manager to the later version.
See IBM i - Migrating a queue manager to the later release or Migrating a queue manager to the later
release, alternative method
Backing up queue manager data is part of the queue manager migration task. An alternative approach
is to install and configure a new server, then test the later version with a new queue manager on the
new server. When you are ready to go into production on the later version, copy the queue manager
configuration and data to the new server.
7. Plan to update any manual or automated procedures you have written with changes to messages and
codes.
A suffix letter, indicating the severity of a message (I, W, E, S or T) is appended to IBM MQ diagnostic
(AMQ) messages. Existing scripts looking for error codes without the severity will fail. For example,
existing scripts looking for error matching to AMQ7468 will fail. You must update the scripts to look
for error codes with the severity suffix added (for example, AMQ7468I). For more information, see
IBM MQ messages on Multiplatforms.
8. Decide on what regression tests to perform before putting the queue manager into production on
the later version. Include the procedures and applications you identified in previous steps in your
regression tests.
9. Plan to migrate your IBM MQ MQI client installations to the later version.
10. Plan to migrate your client and server applications to use new functions in the later version.
11. Decide which downloadable images you require for the migration.
For more information, see “Where to find downloadable installation images” on page 9.

Migrating an IBM MQ classes for JMS and Java client on IBM i

If you have IBM MQ Java SupportPac MA88 installed, you must uninstall it first.

Before you begin

SupportPac MQ88 is installed.
If you try to install the latest version of IBM MQ classes for Java anyway, the installation fails with a
warning requesting you to uninstall the old client. You must follow the steps in this task to uninstall
IBM MQ classes for Java and IBM MQ classes for JMS.
A previous version of IBM MQ classes for Java is installed.
Installation of the latest version of IBM MQ classes for Java uninstalls the previous version
automatically. Do not follow the steps in this task.

About this task

The steps in this task uninstall the IBM MQ classes for JMS and Java.

Procedure
To uninstall the previous IBM MQ Java client:
1. Delete the QMQMJAVA library and the /QIBM/ProdData/mqm/java directory, by issuing the
command:

DLTLICPGM LICPGM(5648C60) OPTION(*ALL)

2. If the previous step failed to delete the IFS directory /QIBM/ProdData/mqm/java and its
subdirectories, use the EDTF command, for example:

Installing and migrating 431

 EDTF STMF('/QIBM/ProdData/mqm')

and select option 9 against the java directory.

Migrating a queue manager to the latest version on IBM i

Follow these instructions to migrate a queue manager on IBM i to the latest MQ version.

Before you begin

1. Create a migration plan. Use the planning task, Planning migration to the latest version, as a guide.
2. Review the IBM MQ system requirements for the latest version of the product; see System
Requirements for IBM MQ
3. Review any other installed SupportPacs for their applicability to the latest version of the product.

About this task

There are two types of migration:
• The migration takes place on the same machine, optionally accompanied by a hardware upgrade. This
migration is referred to as a slip installation. On IBM i, uninstalling the earlier version before you install
the later version is optional.
• The migration takes place on a different machine. This migration is referred to as a side-by-side
installation.
A side-by-side installation lets you prepare the new environment first, without interrupting the queue
manager. It also gives you the limited option of reverting to use the earlier version installation, if the
migration is unsuccessful. It is limited, because you cannot restore the queue manager data from the
later version. You must restart processing with the queue manager data at the point you stopped the
queue manager on the earlier release.
If you decide to do a side-by-side installation, you must prepare the new server first, installing the
prerequisite software.
If you want to add Advanced Message Security to your system, you must select Option (2) when you
install the product; see “Installing Advanced Message Security on IBM i” on page 238 for further
information.
Related tasks
“Migrating a queue manager on AIX and Linux” on page 406
The procedures for migrating a queue manager to a later version of the product, and for restoring a queue
manager to an earlier version of the product are detailed in this section.
“Migrating a queue manager on Windows” on page 378
The procedures for migrating a queue manager to a later version of the product, and for restoring a queue
manager to an earlier version of the product are detailed in this section.

Installation methods on IBM i

Select a slip installation or a side-by-side installation to upgrade IBM MQ for IBM i.

About this task

A slip installation upgrades IBM MQ for IBM i on a computer with an earlier version is installed.
A side-by-side installation upgrades IBM MQ for IBM i on a different computer. You must save your queue
managers before you start.
Follow the steps in the following tasks to carry out an upgrade.
The steps for both forms of upgrade are identical, except that you do not carry out the actions described
in “Restore queue managers after upgrading IBM MQ on IBM i” on page 441 for a slip installation.

432 Installing and migrating IBM MQ

 End IBM MQ activity on IBM i
End IBM MQ applications and connections, and remove any unwanted or indoubt messages.

About this task

Before performing a slip installation or side-by-side installation, carry out the following procedure:

Procedure
1. Sign on to the system with a user profile that has *ALLOBJ special authority, for example QSECOFR.
2. Stop all applications that are using the existing version of IBM MQ.
To identify applications using the queue manager, use the command WRKMQM, option 22, Work with
queue manager jobs, to help find them. Ignore jobs starting with AMQ* or RUN* and focus on your
application job names.
3. End all channels for all queue managers on the system. To do so, use the WRKMQMCHL command and
select option 15.
4. On each queue manager, end the command server. To do so, enter the command:

ENDMQMCSVR MQMNAME( QMGRNAME ) OPTION(*IMMED)

where QMGRNAME is the name of the queue manager.

5. Remove any unwanted messages from your queues.
6. Resolve any in-doubt messages that are held by sender or server channels. To do so, use the
WRKMQMCHST command and select option 17.
7. On each queue manager, save the latest media recovery checkpoint. To do so, enter the following
command:

RCDMQMIMG OBJ(*ALL) OBJTYPE(*ALL) MQMNAME( QMGRNAME ) DSPJRNDTA(*YES)

Quiesce IBM MQ on IBM i

Stop all queue managers. If necessary force all queue managers to stop, tidy up shared memory and end
all jobs in the QMQM subsystem.

About this task

The orderly shutdown of IBM MQ is called quiescing. You need to quiesce IBM MQ to upgrade to a newer
version.

Procedure
Prepare to quiesce queue managers:
1. Sign on to a new interactive IBM i session, ensuring that you are not accessing any IBM MQ objects.
2. Ensure that you have the following authorities:
• *ALLOBJ authority, or object management authority for the QMQM library.
• Sufficient authority to use the ENDSBS command.
3. Warn all users that you are going to stop IBM MQ.
4. Stop the mqweb server by entering the following command:

ENDMQWEB

Quiesce all queue managers:

5. Run the ENDMQM command:

Installing and migrating 433

 ENDMQM MQMNAME(*ALL) OPTION(*CNTRLD) ENDCCTJOB(*YES) RCDMQMIMG(*YES)
TIMEOUT( 15 )

Where 15 is a timeout value in seconds.

If the ENDMQM command has not completed within a reasonable period (at least 10 minutes), use
the WRKMQM command. This command identifies the queue managers that are still ending. Then
force each one in turn to stop by running the following command:

ENDMQM MQMNAME( QMGRNAME ) OPTION(*IMMED)

Where QMGRNAME is the name of the queue manager.

Complete the tidying up of shared memory by running the following command:

ENDMQM MQMNAME(*ALL) OPTION(*IMMED) ENDCCTJOB(*YES) RCDMQMIMG(*NO)

TIMEOUT( 15 )

If the commands in the previous step do not complete, end the subsystem immediately:
6. Run the following command:

ENDSBS SBS(QMQM) OPTION(*IMMED)

If the command in the previous step also does not complete, use the operating system command
ENDJOB to end all jobs in the subsystem QMQM:
Note: Do not use ENDJOBABN unless you intend to perform an IPL on the machine before starting IBM
MQ. Ending IBM MQ jobs using ENDJOBABN can lead to damaged semaphores, which in turn can prevent
your queue manager from starting.
7. If a QMGR must be shut down manually, end the jobs (ENDJOB) in the following order. Wait a few
minutes for AMQA* or AMQZ* jobs to tidy up.
a. RUNMQLSR - TCP listener (multi-threaded)
b. AMQCLMAA - TCP listener (single-threaded)
c. AMQRMPPA - Channel process pooling job
d. RUNMQCHI - channel initiator
e. AMQCRSTA - receiving MCA jobs
f. RUNMQCHL - sending MCA jobs
g. AMQCRS6B - LU62 receiver channel
h. AMQPCSEA - command server
i. RUNMQTRM - Application trigger monitor
j. RUNMQDLQ - Dead letter queue handler
k. AMQFCXBA - IBM Integration Bus Worker Job
l. AMQFQPUB - Queued Publish/Subscribe Daemon
m. RUNMQBRK - IBM Integration Bus Control Job
n. AMQZMUC0 ('0' is a zero) - Utility Manager
o. AMQZMUF0 ('0' is a zero) - Utility Manager
p. AMQZMUR0 ('0' is a zero) - Utility Manager
q. AMQZMGR0 ('0' is a zero) - Process Controller
r. AMQRRMFA - cluster repository manager
s. AMQZDMAA - deferred message manager
t. AMQZFUMA - object authority manager

434 Installing and migrating IBM MQ

 u. AMQZLSA0 ('0' is a zero) - LQM agents
v. AMQZLAA0 ('0' is a zero) - LQM agents
w. AMQZXMA0 ('0' is a zero) - Execution Controller
8. Run the following command:

ENDMQM MQMNAME( QMGRNAME ) OPTION(*IMMED)

9. Run the following command:

ENDMQM MQMNAME(*ALL) OPTION(*CNTRLD) ENDCCTJOB(*YES) RCDMQMIMG(*NO)

TIMEOUT( 05 )

Where 05 is a timeout value in seconds.

10. Manually clean up shared memory.
Run the following command:

EDTF '/QIBM/UserData/mqm/qmgrs'

then:
a. Take option 5 for &SYSTEM and check that the following directories are empty: isem, esem,
msem, ssem, and shmem.
b. Take option 5 for QMGRNAME and check that the following directories are empty:- isem, esem,
msem, ssem, and shmem.
c. Take option 5 for &ipcc in the QMGRNAME directory and check that the following directories are
empty:- isem, esem, msem, ssem, and shmem.
d. Take option 5 for &qmpersist in the QMGRNAME directory and check that the following
directories are empty:- isem, esem, msem, ssem, and shmem.
e. Take option 5 for &app and check that the following directories are empty: isem, esem, msem,
ssem, and shmem.

Save IBM MQ data on IBM i

Save IBM MQ data after removing unwanted FDC, trace, and JOB files.

Before you begin

You need to have completed the tasks to remove unwanted and indoubt messages and quiesced IBM MQ.

About this task

Procedure
1. Create a save file for every queue manager library on your system. To do so, issue the command:

CRTSAVF FILE(QGPL/ queue_manager_library )

where the queue_manager_library name consists of the name of the queue manager preceded
by QM.
2. Save your queue manager libraries into the save files. To do so, issue the commands:

SAVLIB LIB( queue_manager_library ) DEV(*SAVF)

SAVF(QGPL/ queue_manager_library )

3. Remove all unwanted FDC data from directory:

Installing and migrating 435

 QIBM/UserData/mqm/errors

4. Remove old FDC files with the command:

RMVLNK OBJLNK('/QIBM/UserData/mqm/errors/*.FDC')

This command cleans up all files with an extension of 'FDC' in the IFS.
5. Remove old JOB files with the command:

RMVLNK OBJLNK('/QIBM/UserData/mqm/errors/*.JOB')

This command cleans up all files with an extension of 'JOB' in the IFS.
6. Remove all unwanted trace data from directory, or remove the whole directory:

QIBM/UserData/mqm/trace

7. Remove all trace files with the command:

RMVLNK OBJLNK('/qibm/userdata/mqm/trace/*')

8. Create a save file for IBM MQ IFS data. To do so, issue the command:

CRTSAVF FILE(QGPL/QMUSERDATA)

9. Save your IBM MQ IFS data, using the command:

SAV DEV('/QSYS.LIB/QGPL.LIB/QMUSERDATA.FILE') OBJ('/QIBM/UserData/mqm')

10. If you are going to run IBM MQ on a new machine, transfer the save files to the new machine.

Install IBM MQ server on IBM i

Install the IBM MQ server in its primary language.

Before you begin

You have completed planning the installation, obtained the installation disks, and set the system values;
see “Configuring and tuning the operating system on IBM i” on page 64.

About this task

Install the IBM MQ server and force object conversion. Object conversion migrates objects from the older
to the newer version. By performing it now, rather than when an object is first used, you avoid slowing
down the first use of the upgraded product.
After following the optional step to pre-agree the license, the RSTLICPGM command runs without
requiring any interactive input. Otherwise the license agreement is displayed for you to accept. See
“License requirements” on page 8.

Procedure
1. Sign on to the system with a user profile that has *ALLOBJ special authority, for example QSECOFR.
2. Optionally pre-agree the license terms and conditions by running the command,

CALL PGM (QSYS/QLPACAGR) PARM ('5724H72' 'V8R0M0' '0000' 0)

Where the parameters of PARM are,

436 Installing and migrating IBM MQ

 5724H72
The product identifier for IBM i.
V9R4M0
The version, release, and modification level.
0000
The option number for the *BASE IBM MQ product option.
0
Unused error structure.
3. Install IBM MQ for IBM i, base product, and primary language.

RSTLICPGM LICPGM (5724H72) DEV (installation device) OPTION (*BASE) OUTPUT (*PRINT)

where the parameters of RSTLICPGM are,

LICPGM (5724H72)
The product identifier for IBM i.
DEV (installation device)
The device from which the product is to be loaded, typically an optical drive, for example, OPT01.
OPTION (*BASE)
Install the base IBM MQ for IBM i product.
Unspecified parameters
Unspecified parameters such as RSTOBJ (*ALL), revert to defaults. The command installs both
IBM MQ and the language files for the primary language of your system. For installing additional
languages see Installing translated versions.

What to do next
Install any Progam Temporary Fixes (PTF) that have been issued.

Install samples on IBM i

Install the IBM MQ samples

Before you begin

If you have not already done so, sign on to the system with a user profile that has *ALLOBJ special
authority, for example QSECOFR.

About this task

Install the samples.
After following the optional step to pre-agree the license, the RSTLICPGM command runs without
requiring any interactive input. Otherwise the license agreement is displayed for you to accept. See
“License requirements” on page 8.

Procedure
1. Optionally pre-agree the license terms and conditions by running the command,

CALL PGM (QSYS/QLPACAGR) PARM ('5724H72' 'V8R0M0' '0001' 0)

Where the parameters of PARM are,

5724H72
The product identifier for IBM i.
V9R4M0
The version, release, and modification level.

Installing and migrating 437

 0001
The option number for the samples.
0
Unused error structure.
2. Install the samples using the command:

RSTLICPGM LICPGM (5724H72) DEV (installation device) OPTION (1) OUTPUT (*PRINT)

Where the parameters of RSTLICPGM are,

LICPGM (5724H72)
The product identifier for IBM i.
DEV (installation device)
The device from which the product is to be loaded, typically an optical drive, for example, OPT01.
OPTION (1)
Install the samples for IBM i.
OUTPUT (*PRINT
The output is printed with the spooled output of the job.

Install translated versions on IBM i

Install translated versions of IBM MQ from a choice of national-languages.

About this task

The following language versions are available for IBM i:

Table 43. National-language versions of IBM MQ for IBM i

Language ID Language
2909 Belgian English
2966 Belgian French MNCS (Multi-National Character Set)
2981 Canadian French MNCS
2975 Czech
2950 English uppercase
2924 English uppercase and lowercase
2984 English US DBCS
2938 English US uppercase DBCS
2928 French
2940 French MNCS
2929 German
2939 German MNCS
2976 Hungarian
2932 Italian
2942 Italian MNCS
2962 Japanese
2986 Korean

438 Installing and migrating IBM MQ

Table 43. National-language versions of IBM MQ for IBM i (continued)
Language ID Language
2978 Polish
2979 Russian
2989 Simplified Chinese
2931 Spanish

IBM MQ for IBM i is installed in the language that is the primary language on your system.
You can install additional versions of the product in any of the languages shown in Table 43 on page 438.
To do so complete the following steps:

Procedure
1. Sign on to the system with a user profile that has *ALLOBJ special authority
2. Issue the following command specifying the appropriate language ID:

RSTLICPGM LICPGM(5724H72) DEV( installation device ) RSTOBJ(*LNG) LNG( language ID )

This installs the commands, message file, and panel groups into the relevant QSYS library for the
language. For example, library QSYS2928 is used for French. If this QSYS29nn library does not exist, it
is created by the RSTLICPGM command.

Results
Note:
1. To run the Japanese language version of IBM MQ for IBM i, the CCSID of the job must be 939 (5035)
rather than 930 (5026) because IBM MQ uses lowercase English characters.
2. If you are installing IBM MQ for IBM i onto a machine for which the primary language is not on the CD,
the installation program prompts you to load a CD containing the product in that language. If, however,
you have only one product CD, this means that the IBM MQ product has not been translated into your
language. To get around this issue, proceed as follows:
• Install the product in one of the supplied languages, and then add the corresponding QSYS29nn
library into the system library list (for example using command CHGSYSLIBL). At the same time,
check that there are no IBM MQ *CMD, *MENU, or *MSGF objects in libraries higher up the library list.
If some exist, then either delete these objects (because they refer to an earlier version of IBM MQ)
or reorder the System Library list (because the product has been installed in more than one of the
supplied languages).

Verify the installation on IBM i

How to check that your installation has been successful.

Procedure
1. To ensure that the product has loaded correctly, issue the Display Software Resources (DSPSFWRSC)
command and check that the licensed program 5724H72 is listed. If you have installed the base and
the optional samples, you see:

Resource
ID Option Feature Description
5724H72 *BASE 5050 IBM MQ for IBM i
5724H72 *BASE 2924 IBM MQ for IBM i
5724H72 1 5050 IBM MQ for IBM i - Samples

Installing and migrating 439

 2. Press F11, while viewing the Display Software Resources screen, and you see the library and version
number of the products installed:

Resource Feature
ID Option Feature Type Library Release
5724H72 *BASE 5050 *CODE QMQM V9R4M0 5724H72 *BASE 2924 *LNG QMQM V9R4M0
5724H72 1 5050 *CODE QMQMSAMP V9R4M0

3. If you have installed additional language versions, you also see entries for these versions. For example,
if you have installed the French version, for which the language ID is 2928, you see:
a)
Resource
ID Option Feature Description
5724H72 *BASE 2928 IBM MQ for IBM i

b) and when you press F11:

Resource Feature
ID Option Feature Type Library Release
5724H72 *BASE 2928 *LNG QSYS2928 V9R4M0

4. Use the command DSPMQMVER to check exactly what version you have installed. For example, for
V9R4M0, it reports:

Version: 9.2.0.0

Verify the upgrade on IBM i

After you have verified the installation, start the IBM MQ subsystem, check the queue managers, and take
a fresh media recovery checkpoint.

About this task

To verify that you have migrated to the latest version IBM MQ for IBM i, successfully:

Procedure
1. Make QMQMADM either the primary or a secondary group profile for your user profile. To do so, issue
one of the following commands:

CHGUSRPRF USRPRF( YOUR PROFILE ) GRPPRF(QMQMADM)

CHGUSRPRF USRPRF( YOUR PROFILE ) SUPGRPPRF(QMQMADM)

2. Start the IBM MQ subsystem with the command:

STRSBS SBSD(QMQM/QMQM)

(If it is already running, you get error message CPF1010 which you can safely ignore).
3. Check that your queue managers are accessible by issuing the command:

WRKMQM

Use option 14 against each queue manager to start it.

Use option 5 against each queue manager to check its attributes.
4. You can use the other options to check your queue manager objects. For example, check your queues
using option 18, check your channels using option 20, and so on.
5. Take a fresh media recovery checkpoint, using the following command:

440 Installing and migrating IBM MQ

 RCDMQMIMG OBJ(*ALL) OBJTYPE(*ALL) MQMNAME( QMGRNAME ) DSPJRNDTA(*YES)

Where QMGRNAME is the name of the queue manager.

Restore queue managers after upgrading IBM MQ on IBM i

Complete the side-by-side upgrade by restored the saved queue managers onto the server that you have
upgraded.

Before you begin

Note: Carry out this task only if you are performing a side-by-side upgrade.
Ensure that you have saved your queue manager data, see “End IBM MQ activity on IBM i” on page 433,
and installed and verified the upgrade.

About this task

Transfer the queue manager data, and journal receivers, onto the server that has been upgraded.

Procedure
1. Restore the queue manager libraries for every queue manager, using the command:

RSTLIB SAVLIB( queue_manager_library ) DEV(*SAVF) (*PRINT)

SAVF(QGPL/ queue_manager_library )

where the queue_manager_library name consists of the name of the queue manager preceded by
QM.
2. Restore the IBM MQ IFS data, using the command:

RST DEV('/QSYS.LIB/QGPL.LIB/QMUSERDATA.FILE') OBJ('/QIBM/UserData/mqm') (*PRINT)

3. To associate the journal receivers, issue the command WRKJRN on the journal AMQAJRN in each queue
manager library, by pressing PF4 and selecting option 9.
4. If you want to set up your work management environment, job descriptions, and pools, see the
Administering IBMi for guidance. Otherwise, use the default setup.

After Upgrading on IBM MQ for IBM i

Tasks to perform after you have upgraded IBM MQ for IBM i.

About this task

Satisfy yourself the upgrade has completed successfully.

Procedure
Delete the saved data in the save files in QGPL. This data was saved in “Save IBM MQ data on IBM i” on
page 435.

Post installation tasks for IBM i

Tasks to perform after you have installed IBM MQ for IBM i, and before using it.

About this task

When you have correctly installed IBM MQ for IBM i on your system:

Installing and migrating 441

 Procedure
1. For the latest product information for IBM i, see System requirements for IBM MQ .
2. To install and apply all fix packs, see “Applying maintenance level updates on IBM i” on page 291.
3. Where you have more than one system and a mixture of releases of OS/400 or IBM i, and IBM MQ, you
must take care when compiling CL programs. You must compile CL programs either on the system they
are to run on, or on one with an identical combination of releases of OS/400 or IBM i, and IBM MQ.
When you install later versions of IBM MQ, delete all IBM MQ commands from previous releases in any
QSYSVvRrMm libraries using the QSYS/DLTCMD command.
4. If you have not installed IBM MQ on your system before, you must add user profiles to the QMQMADM
group profile. Make all user profiles that are to be used for creating and administering queue managers
members of the QMQMADM group profile, using the command CHGUSRPRF.
a) Start the IBM MQ subsystem, by issuing the command:

STRSBS SBSD(QMQM/QMQM)

Note: The subsystem must be started after each IPL of the system, so you might choose to start it
as part of your system startup process.

5. Create the system-default objects. The system-default objects are created automatically
when you issue the CRTMQM command to create a queue manager. For example: CRTMQM
MQMNAME(QMGRNAME) ASP(*SYSTEM). You can refresh them using the STRMQM command
(Warning: this command will replace any existing default objects). For example: STRMQM
MQMNAME(QMGRNAME) RDEFSYS(*YES). Refer to the onscreen help for information about using this
command.
Note: on the command STRMQM MQMNAME(QMGRNAME) RDEFSYS(*YES):
• The command does not re-create the objects, it performs a CRTxxxx REPLACE(*YES) for all of the
SYSTEM.* objects.
• This means that it refreshes the parameters on the objects back to their defaults. So if, for example,
on the SYSTEM.DEFAULT.LOCAL.QUEUE object, TRGENBL had previously been changed to *YES,
then, when the command is run, it is changed back to TRGENBL(*NO).
• If any messages exist on a queue, they are left intact, because the queues are not physically deleted.
• The contents of the SYSTEM.AUTH.DATA.QUEUE are untouched when this command is run.
• So, if the contents of this (or any other significant queue) become corrupt, it must be physically
deleted and re-created either from scratch, or from a backup.

Results
You are now ready to start using IBM MQ for IBM i.
Note: When you install IBM MQ for IBM i, two user profiles are created:
• QMQM
• QMQMADM
These two objects are central to the correct running of IBM MQ for IBM i. Do not alter or delete them. If
you do, IBM cannot guarantee correct behavior of your product.
If you uninstall IBM MQ and data, these profiles are deleted. If you uninstall IBM MQ only, these profiles
are retained.

442 Installing and migrating IBM MQ

 Migrating a queue manager to a later version on IBM i - alternative method
An alternative method of migrating a queue manager from an earlier version to a later version

Before you begin

1. Review the IBM MQ system requirements for the later version of the product; see System
Requirements for IBM MQ
2. Review any other installed SupportPacs for their applicability to the later version of IBM MQ.

About this task

There are various parts to this form of migration:
1. As part of upgrading the IBM MQ product, carry out the following tasks:
a. “Preparing to install IBM MQ on IBM i” on page 443
b. “Install IBM MQ server on IBM i” on page 444
2. Following the IBM MQ product upgrade, carry out the following task:
a. “Post installation tasks” on page 445

Preparing to install IBM MQ on IBM i

Carry out the following tasks to prepare your system for an upgrade.

Procedure
1. Stop the IBM MQ queue managers by issuing the following command:

ENDMQM MQMNAME(*ALL) OPTION(*IMMED) ENDCCTJOB(*YES) RCDMQMIMG(*YES)

TIMEOUT(30)

Ensure that the user profile issuing this command has *ALLOBJ authority.
2. Create a save file for every queue manager library on your system. To do so, issue the command:

CRTSAVF FILE(QGPL/ queue_manager_library )

where the queue_manager_library name consists of the name of the queue manager preceded by
QM.
3. Save your queue manager libraries into the save files. To do so, issue the commands:

SAVLIB LIB( queue_manager_library ) DEV(*SAVF)

SAVF(QGPL/ queue_manager_library )

4. Create a save file for IBM MQ IFS data. To do so, issue the command:

CRTSAVF FILE(QGPL/QMUSERDATA)

5. Save your IBM MQ IFS data, using the command:

SAV DEV('/QSYS.LIB/QGPL.LIB/QMUSERDATA.FILE') OBJ('/QIBM/UserData/mqm')

6. If you are going to run IBM MQ on a new machine, transfer the save files to the new machine.
7. Issue the following command before you upgrade your IBM MQ product, only if the upgrade is required
on the same machine.
a) DLTMQM QMgrName
b) ENDSBS SBS(QMQM) OPTION(*IMMED)

Installing and migrating 443

 c) WRKOBJLCK OBJ(QMQM) OBJTYPE(*LIB)
Relinquish any locks on the system.

Install IBM MQ server on IBM i

Install the IBM MQ server in its primary language and force object conversion.

Before you begin

In either of the following cases, ensure that you have completed the planning and set the system values;
see “Configuring and tuning the operating system on IBM i” on page 64
• If you have obtained the product through the Passport Advantage and Passport Advantage Express
website, follow the instructions in the EGA.README.txt file.
• If you have obtained the product on disk, follow the instructions within this topic.

About this task

Install the IBM MQ server and force object conversion. Object conversion migrates objects from the older
to the newer version. By performing it now, rather than when an object is first used, you avoid slowing
down the first use of the upgraded product.
After following the optional step to pre-agree the license, the RSTLICPGM command runs without
requiring any interactive input. Otherwise the license agreement is displayed for you to accept. See
“License requirements” on page 8.

Procedure
1. Sign on to the system with a user profile that has *ALLOBJ special authority, for example QSECOFR.
2. Optionally pre-agree the license terms and conditions by running the command,

CALL PGM (QSYS/QLPACAGR) PARM ('5724H72' 'V8R0M0' '0000' 0)

Where the parameters of PARM are,

5724H72
The product identifier for IBM i.
V9R4M0
The version, release, and modification level.
0000
The option number for the *BASE IBM MQ product option.
0
Unused error structure.
3. Install IBM MQ for IBM i, base product, and primary language.

RSTLICPGM LICPGM (5724H72) DEV (installation device) OPTION (*BASE) OUTPUT (*PRINT)

where the parameters of RSTLICPGM are,

LICPGM (5724H72)
The product identifier for IBM i.
DEV (installation device)
The device from which the product is to be loaded, typically an optical drive, for example, OPT01.
OPTION (*BASE)
Install the base IBM MQ for IBM i product.

444 Installing and migrating IBM MQ

 Unspecified parameters
Unspecified parameters such as RSTOBJ (*ALL), revert to defaults. The command installs both
IBM MQ and the language files for the primary language of your system. For installing additional
languages see Installing translated versions.

What to do next
Install any Progam Temporary Fixes (PTF) that have been issued.
To install the IBM MQ samples, see: “Install samples on IBM i” on page 437.

Post installation tasks

Actions required after upgrading IBM MQ.

About this task

Install the samples.
Carry out these steps after installing the product.

Procedure
1. Issue the following commands:
a) STRSBS SBSD(QMQM/QMQM)
b) CRTMQM MQMNAME(QMgrName) DFTQMGR(*YES)
You receive the message " IBM MQ queue manager created."
c) STRMQM MQMNAME(QMgrName)
You receive the message " IBM MQ queue manager 'QMgrName' started."
2. Issue the following command:

STRMQMMQSC SRCMBR(QMgrName) SRCFILE(*CURLIB/QMQSC) OPTION(*RUN)

MQMNAME(QMgrName)

3. Reapply IBM MQ Authorities by issuing the command: CALL PGM(*CURLIB/QMgrName)

a) You must compile the CLP as follows:

CRTCLPGM PGM(*CURLIB/QMgrName) SRCFILE(*CURLIB/QMAUT) SRCMBR(*PGM)

Upgrading an entire IBM MQ system on IBM i

How to upgrade an IBM MQ system on IBM i

Before you begin

Ensure that you have backed up your entire system.

About this task

To upgrade an IBM MQ system on IBM i you carry out a slip installation.
See “Installation methods on IBM i” on page 432 for further information.
Related tasks
“Migrating a queue manager on Windows” on page 378

Installing and migrating 445

 The procedures for migrating a queue manager to a later version of the product, and for restoring a queue
manager to an earlier version of the product are detailed in this section.

Migrating an IBM MQ MQI client to the latest version on IBM i

Before migrating an IBM MQ MQI client, create a migration plan. Stop all IBM MQ activity on the
client workstation. Upgrade the IBM MQ MQI client installation. Make any essential configuration and
application changes.

Before you begin

1. Create a migration plan. Use the planning task, “Planning to migrate IBM MQ to a later version on IBM
i” on page 430, as a guide.

Procedure
1. Review the IBM MQ system requirements for the later version of the product.
See System Requirements for IBM MQ.See “IBM MQ components and features” on page 6 and “Where
to find downloadable installation images” on page 9.
2. Review all the changes in IBM MQ that affect you.
See “Changes that affect migration” on page 337.
3. End all IBM MQ activity on the workstation.
4. Upgrade the client.
To upgrade an IBM MQ MQI client for IBM i installation on a workstation; see “Installing an IBM MQ
client on IBM i” on page 78.

What to do next
Complete the tasks in your migration plan, such as verifying IBM MQ MQI client applications work
correctly with the latest version.
Related concepts
“IBM MQ MQI client migration” on page 344
IBM MQ MQI client migration is the process of converting IBM MQ MQI client configurations, and client
and server channels from one version to another. Client migration can take place after upgrading the IBM
MQ MQI client, and is reversible.
Related tasks
“Installing an IBM MQ client on IBM i” on page 78
The IBM MQ client for IBM i is a part of the IBM MQ product.
“Migrating an IBM MQ MQI client on AIX and Linux” on page 421
Before migrating an IBM MQ MQI client, create a migration plan. Stop all IBM MQ activity on the
client workstation. Upgrade the IBM MQ MQI client installation. Make any essential configuration and
application changes.
“Migrating an IBM MQ MQI client on Windows” on page 395
Before migrating an IBM MQ MQI client, create a migration plan. Stop all IBM MQ activity on the
client workstation. Upgrade the IBM MQ MQI client installation. Make any essential configuration and
application changes.
Installing IBM MQ MQI clients on the same machine as the server

Migrating from a single instance to a multi-instance queue manager on IBM

i
To migrate a single instance queue manager to a multi-instance queue manager, on IBM i, you must move
the queue manager data to a shared directory, and reconfigure the queue manager on two other servers.

446 Installing and migrating IBM MQ

Before you begin
You must check the prerequisites for running a multi-instance queue manager as part of this task. Some
environments have been tested with multi-instance queue managers, and are known to work. IBM i has
been tested with multi-instance queue managers and is known to work. For a list of tested environments,
see Testing statement for IBM MQ multi-instance queue manager file systems. The support statement
has detailed version and prerequisite information for each environment it lists. Other environments might
work; a test tool is provided with IBM MQ to assist you in qualifying other environments.
You must have three servers to run a multi-instance queue manager. One server has a shared file system
to store the queue manager data and logs. The other servers run the active and standby instances of the
queue manager.

About this task

You have a single-instance queue manager that you want to convert to a multi-instance queue manager.
The queue manager conversion itself is straightforward, but you must do other tasks to create a fully
automated production environment.
You must check the prerequisites for a multi-instance queue manager, set up the environment and check
it. You must set up a monitoring and management system to detect if the multi-instance queue manager
has failed and been automatically restarted. You can then find out what caused the restart, remedy it,
and restart the standby. You must also modify applications, or the way applications are connected to the
queue manager, so that they can resume processing after a queue manager restart.

Procedure
1. Check the operating system that you are going to run the queue manager on, and the file system
on which the queue manager data and logs are stored on. Check that they can run a multi-instance
queue manager.
a) Consult Testing statement for IBM MQ multi-instance queue manager file systems. See whether
the combination of operating system and file system is tested and capable of running a multi-
instance queue manager.
A shared file system must provide lease-based locking to be adequate to run multi-instance
queue managers. Lease-based locking is a recent feature of some shared file systems, and
in some case fixes are required. The support statement provides you with the essential
information.
b) Run amqmfsck to verify that the file system is configured correctly.
File systems are sometimes configured with performance at a premium over data integrity. It
is important to check the file system configuration. A negative report from the amqmfsck tool
tells you the settings are not adequate. A positive result is an indication that the file system is
adequate, but the result is not a definitive statement that the file system is adequate. It is a
good indication.
c) Run the integrity checking application provided in the technote, Testing a shared file system for
compatibility with IBM MQ Multi-instance Queue Managers.
The checking application tests that the queue manager is restarting correctly.
2. Configure a user and group to be able to access a share on the networked file system from each
server that is running a queue manager instance.
On IBM i, QMQM, QMQMADM, and any other user profiles that are granted access to the share must have
the same passwords on all the servers
3. Set up a directory for the share on the networked file system with the correct access permissions.
A typical configuration is to set up a single shared directory that contains all data and log
directories for all queue managers that use the shared disk; see Share named qmgrs and log
directories .

Installing and migrating 447

 For example, create a root directory on the share called MQHA that has subdirectories data and
logs. Each queue manager creates its own data and log directories under data and logs. Create
MQHA with the following properties:
On IBM i, follow the instructions to create a network share using NetServer.
4. Copy the queue manager data and the logs to the share.
You can choose to copy files manually, by following the procedure to back up the queue manager.
elect one of these methods:
• Follow the instructions in Backups of IBM MQ for IBM i data, copying the queue manager data to
the share. You must use this method if the DataPath configuration attribute is specified for this
queue manager.
• Stop the queue manager, and then type the command,

hamvmqm /m /dd share\data /dd share\logs

Where share is to be the location of the data and logs that you created in step “3” on page 447.
5. Update the queue manager configuration information stored on the current queue manager server.
If you moved the queue manager data and logs by running the hamvmqm command, the command
has already modified the configuration information correctly for you.
If you moved the queue manager data and logs manually, you must complete the following steps.
• On IBM i,
a. Modify the Log: stanza in the queue manager qm.ini file, which is on the share:

LogPath= share/logs/QMgrName

b. Modify the QueueManager: stanza in the IBM MQ mqs.ini file, which is typically in the /
QIBM/UserData/mqm directory on IBM i:

DataPath= share/data/QMgrName

Where, QMgrName is the Directory name in the QueueManager: stanza in the mqs.ini file on
IBM i. share is share where the data and logs are moved to.
6. Add the queue manager configuration information to the new queue manager server.
a) Run the dspmqinf command to display the queue manager information on the server that ran the
queue manager in the previous release.

dspmqinf -o command QMgrName

The command output is formatted ready to create a queue manager configuration.

addmqinf -s QueueManager -v Name= QMgrName -v Directory= QMgrName -v
Prefix=d:\var\mqm Datapath= \share\data\QMgrName
b) Create a queue manager configuration on the other server.
Run the addmqinf command copied from the previous output
7. Add the network address of the new server to the connection name in client and channel definitions.
a) Find all the client, sender, and requester TCPIP settings that refer to the server.
Client settings might be in Client Definition Tables (CCDT), in environment variables, in Java
properties files, or in client code.
Cluster channels automatically discover the connection name of a queue manager from its
cluster receiver channel. As long as the cluster receiver channel name is blank or omitted,
TCPIP discovers the IP address of the server hosting the queue manager.

448 Installing and migrating IBM MQ

 b) Modify the connection name for each of these connections to include the TCPIP addresses of both
servers that are hosting the multi-instance queue manager.
For example, change:

echo DISPLAY CHANNEL(ENGLAND) CONNAME | runmqsc QM1

5724-H72 (C) Copyright IBM Corp. 1994, 2024. ALL RIGHTS RESERVED.

Starting MQSC for queue manager QM1.

1: DISPLAY CHANNEL(ENGLAND) CONNAME

AMQ8414: Display Channel details.

CHANNEL(ENGLAND) CHLTYPE(SDR)

CONNAME(LONDON)

Into:

echo ALTER CHANNEL(ENGLAND) CHLTYPE(SDR) CONNAME('LONDON, BRISTOL') | runmqsc QM1

8. Update your monitoring and management procedures to detect the queue manager restarting.
9. Update client applications to be automatically reconnectable, if appropriate.
10. Update the start procedure for your IBM MQ applications to be started as queue manager services.
11. Start each instance of the queue manager, permitting them to be highly available.
The first instance of the queue manager that is started becomes the active instance.
Issue the command twice, once on each server.

strmqm -x QMgrName

What to do next
To get the highest availability out of multi-instance queue managers, you must design client applications
to be reconnectable and server applications to be restartable; see Application recovery.
Related concepts
Application recovery
Automatic client reconnection
Channel and client reconnection
Multi-instance queue managers
Multi-instance queue managers on IBM i
Shared file system
Related tasks
Backing up queue manager data
Verifying shared file system locking
Related reference
amqmfsck (file system check)
Changing IBM MQ configuration information on Multiplatforms

Installing and migrating 449

 Related information
Testing a shared file system for compatibility with IBM MQ Multi-instance Queue Managers
Testing statement for IBM MQ multi-instance queue manager file systems

Reverting to a single-instance queue manager on IBM i

Revert a multi-instance queue manager to a single instance queue manager, on IBM i, by stopping the
standby instance. Then restart the active instance and do not set the flag that permits standby instances.

Before you begin

You have at least three servers configured to run a queue manager as a multi-instance queue manager.
The queue manager is currently running as a multi-instance queue manager, with one standby instance
active.

About this task

The task involves deactivating the active standby so that only the running multi-instance queue manager
remains active. To prevent a standby instance being started in the future, you must stop the active
instance and restart it. When you restart it, you start it as a single instance queue manager that prevents
standby instances being started. The standby instance is stopped as a separate step, to give you the
option of restarting the active instance at a later date. You can stop both instances by running the
standard endmqm QMgrName command on the server running the active queue manager.

Procedure
1. Stop the standby queue manager instance.
On the server running the standby instance:

ENDMQM MQMNAME (QMgrName) *WAIT

2. Stop the active queue manager instance.

On the server running the active instance:

ENDMQM MQMNAME (QMgrName) *WAIT

3. Restart the queue manager, preventing standbys.

On the server that is going to run the queue manager:

STRMQM MQMNAME (QMgrName)

What to do next
You might want to run the queue manager as a single instance on the same server as the queue manager
data.
When the queue manager is stopped move the queue manager data back to the server that is running the
queue manager. Alternatively install IBM MQ, and then move the queue manager configuration definition
onto the server with the queue manager data. Both tasks are variations of steps in “Migrating from a
single instance to a multi-instance queue manager on IBM i” on page 446 to create a multi-instance
queue manager.

450 Installing and migrating IBM MQ

 Migrating IBM MQ to a CP4I container
The key steps to migrate an existing IBM MQ queue manager into a container environment using the IBM
Cloud Pak for Integration container for IBM MQ.

About this task

This scenario is documented here: Migrating IBM MQ to a CP4I container scenario

Migrating a queue manager cluster

You can migrate queue managers in a cluster all at once, or one at a time, which is called a staged
migration. Migrate full repository queue managers in a cluster before partial repository queue managers.
You must consider what the effect is of migrating some queue managers in a cluster, before all the queue
managers are migrated.

Before you begin

Before starting the migration, check that no cluster-specific migration issues are identified for the
migration you are intending to perform.
Consider the following issues that relate to migrating a queue manager cluster:
• Minimizing application outages.
• Measuring and verifying migration success and planning for backward migration if there are any
migration problems.
• Taking advantage of new IBM MQ features
• Managing the migration of a cluster in the context of the wider IBM MQ network and the systems
architecture of your organization.

About this task

Cluster queue managers can participate in clusters with other queue managers running at different
versions, which is why a staged migration is possible. Being able to stage a migration is important, as
migrating each queue manager in a cluster takes time. By staging the migration, which leaves other
queue managers that are in the cluster running, you reduce the effect of queue manager downtime on
applications.
Migrate queue managers with full repositories first. Then migrate the other queue managers, which have
partial repositories, one at a time. Complete migration of the entire cluster before starting to use new
functions.
If you do have to start using new functions before completing migration of the entire cluster, you might
need to refresh the partial repositories. After each migration of a queue manager with a partial repository,
issue the REFRESH CLUSTER command on the newly migrated queue manager. The command updates
the cluster records in the newly migrated queue manager, potentially receiving updates for any new
attributes. Do not do this step if you migrated the entire cluster before using new function. The REFRESH
CLUSTER command takes a long time for all the changes to work through the cluster.
Note: For large clusters, use of the REFRESH CLUSTER command can be disruptive to the cluster while it
is in progress, and again at 27 day intervals thereafter when the cluster objects automatically send status
updates to all interested queue managers. See Refreshing in a large cluster can affect performance and
availability of the cluster.
If full repositories are not migrated before partial repositories, the cluster continues to work, but without
all the new features in a version working as expected. To work predictably, the full repository queue
managers must be running the latest IBM MQ major version (for LTS users) or CD version (for CD users).
This ensures that the full repositories can store information from the rest of the cluster that arises from
using new features.

Installing and migrating 451

 A repository stores a record it receives in its own version. If the record it receives is at a later version, the
later version attributes are discarded when the record is stored. An IBM MQ 9.3 queue manager receiving
information about an IBM MQ 9.4 queue manager stores only IBM MQ 9.3 information. An IBM MQ 9.4
repository receiving an IBM MQ 9.3 record stores default values for attributes introduced in the later
version. The defaults define the values for the attributes that are not included in the record it receives. For
more information, see “How mixed version cluster repositories are updated” on page 452.
Note: In exceptional circumstances, it might be necessary to upgrade some of your partial repositories
before your full repositories.
While the product supports this configuration, in this situation be very careful to avoid use of any new
clustering function on the partial repositories, until your full repositories have been upgraded, to avoid
unexpected results.

Procedure
• For information about creating a migration plan for a queue manager cluster, see “Creating a migration
plan for a queue manager cluster” on page 453.
• For information about creating a backout plan for the migration of a queue manager cluster, see
“Creating a backout plan for queue manager cluster migration” on page 454.
• For information about how to migrate one queue manager in a queue manager cluster, see “Migrating
one cluster queue manager” on page 455.

How mixed version cluster repositories are updated

Repositories store records for an object in a cluster in the version of the record format that matches the
version of the queue manager hosting the repository. Repository queue managers forward object records,
before they are stored, in the format that they are received in. The recipient ignores fields from a newer
version, and uses default values for fields that are not present in the record.
Cluster repositories hold records that represent objects, for example, a queue record represents a cluster
queue. A full repository holds records for all objects in the cluster. Partial repositories hold records for
local objects and remote objects that are used locally. A repository record can hold information only about
attributes at the same command level as the queue manager holding that repository. So for example, an
IBM MQ 9.3 repository contains only IBM MQ 9.3 level attribute information. An IBM MQ 9.4 repository
contains all IBM MQ 9.3 records, plus IBM MQ 9.4 records containing additional IBM MQ 9.4 attributes.
A repository stores a record it receives in its own version. If the record it receives is at a later version, the
later version attributes are discarded when the record is stored. An IBM MQ 9.3 queue manager receiving
information about an IBM MQ 9.4 queue manager stores only IBM MQ 9.3 information. An IBM MQ 9.4
repository receiving an IBM MQ 9.3 record stores default values for attributes introduced in the later
version. The defaults define the values for the attributes that are not included in the record it receives.
A repository normally sends records in its own version format, which is the same as the format it has
stored them in. There is one exception to this rule. When a full repository receives a record from a partial
repository, it is immediately forwarded in the same format. So if an IBM MQ 9.3 full repository were to
receive a record from an IBM MQ 9.4 partial repository, it would forward the IBM MQ 9.4 record. It sends
the record to any other full repositories, and any other partial repositories that have subscriptions that
match the record.
A partial repository reflects whichever full repository sent it the latest update to a record. As a
consequence, you might see the information held by an IBM MQ 9.4 partial repository for new IBM MQ
9.4 attributes changing unexpectedly. The values might change from actual IBM MQ 9.4 information to
default values. The changes occur if the full repositories in the cluster are at different levels. Migrate full
repositories first to avoid instability.
A partial repository sends information about its objects to a full repository periodically at least once every
27 days. Information is sent about any object when it is altered or defined. See How long do the queue
manager repositories retain information?

452 Installing and migrating IBM MQ

After migrating all full repositories to IBM MQ 9.4, some attributes might hold default values. The
attributes might hold default values in place of actual values, if a repository has not received an update.
You can refresh the repository in either of two ways:
• Alter the object which the record containing default values represents, for example, using ALTER QL for
a local queue. The alteration forces the local repository to send the record again.
• Issue the REFRESH CLUSTER command on the partial repository which holds the record containing
default values. REFRESH CLUSTER forces the partial repository to discard the record containing default
values and get a new record as required.
Note: For large clusters, use of the REFRESH CLUSTER command can be disruptive to the cluster
while it is in progress, and again at 27 day intervals thereafter when the cluster objects automatically
send status updates to all interested queue managers. See Refreshing in a large cluster can affect
performance and availability of the cluster.
In summary, for the most predictable, and fastest migration, when you stage cluster migration do these
steps in the following order:
1. Migrate the queue managers with full repositories.
2. Migrate the queue managers with partial repositories.
3. Start using new function in the cluster.
Note: In exceptional circumstances, it might be necessary to upgrade some of your partial repositories
before your full repositories.
While the product supports this configuration, in this situation be very careful to avoid use of any new
clustering function on the partial repositories, until your full repositories have been upgraded, to avoid
unexpected results.
Related concepts
How long do the queue manager repositories retain information?

Creating a migration plan for a queue manager cluster

Before carrying out the migration of a queue manager cluster, plan what you are going to do. Identify the
roles that different queue managers play in the cluster, and decide in what order to migrate the queue
managers.

Procedure
• What queue manager and application migration issues must be dealt with between the old and new
versions?
• What system architecture and change control procedures must you consider?
• Consider migration questions specific to clusters, such as migrating full repositories first, and
migrating overlapping clusters.
• Are any of the queue managers in a queue sharing group, or part of a high-availability solution?
• Is the cluster a publish/subscribe cluster? Which queue manager is a cluster topic host?
• Decide whether to carry out a staged migration, or migrate all queue managers at the same time.
• Do you have a test system to migrate , and a production system?
• Document and test the plan before migrating production queue managers.
Related concepts
“Application migration and interoperation” on page 345
IBM MQ supports running applications compiled and linked against previous versions of IBM MQ, with
later levels of IBM MQ. Use the new version of the libraries to build the applications, once the queue
managers have been upgraded.
Availability of cluster topic host queue managers
“How mixed version cluster repositories are updated” on page 452

Installing and migrating 453

 Repositories store records for an object in a cluster in the version of the record format that matches the
version of the queue manager hosting the repository. Repository queue managers forward object records,
before they are stored, in the format that they are received in. The recipient ignores fields from a newer
version, and uses default values for fields that are not present in the record.
“Queue manager migration” on page 343
After upgrading an installation, queue manager migration might be required. Migration takes place when
you start a queue manager. You can remove an upgrade before you have started a queue manager.
However, if you remove the upgrade after a queue manager has been started, the queue manager will not
work.
Related tasks
“Migrating a queue manager in a high-availability configuration” on page 457
High-availability configurations of queue managers can increase the availability of IBM MQ applications. If
a queue manager, or server fails, it is restarted automatically on another server. You can arrange for IBM
MQ MQI client applications to automatically reconnect to the queue manager. Server applications can be
configured to start when the queue manager starts.

Creating a backout plan for queue manager cluster migration

Before performing a migration, decide on a backout plan in case of failure.

Before you begin

What backout capabilities do the queue managers in the cluster support?
On other platforms, the only backout option is to restore a queue manager to a previous state. In restoring
a queue manager, you lose any persistent changes since the queue manager started running at the new
level.

About this task

The backout plan must consider how to maintain the availability of the cluster. It must deal with any
issues arising from migrating a queue manager in the cluster.

Procedure
The backout plan must describe the following points:
• What constitutes a successful migration.
• The conditions that trigger the backout procedure.
• Alternative backout actions, such as:
a) Suspending a queue manager from the cluster.
b) Backward migration
c) Keeping a queue manager offline until an external issue is resolved.
Related concepts
“Queue manager migration” on page 343
After upgrading an installation, queue manager migration might be required. Migration takes place when
you start a queue manager. You can remove an upgrade before you have started a queue manager.

454 Installing and migrating IBM MQ

However, if you remove the upgrade after a queue manager has been started, the queue manager will not
work.

Migrating one cluster queue manager

Follow these steps to migrate a single queue manager in a cluster, starting with a queue manager in your
test system. Base these steps on your cluster migration plan.

Procedure
1. Suspend the queue manager that you want to migrate from the cluster:
a) Issue the MQSC command:

SUSPEND QMGR CLUSTER(cluster name)

b) Check that no messages are sent to the queue manager.

You must close any application that continues to send messages to this queue manager. The
cluster workload algorithm might choose the suspended queue manager. If there are no other
valid destinations, or if an application has an affinity with the queue manager, it might select the
queue manager.
2. Save a record of all cluster objects known by this queue manager. This data is used after migration to
check that objects have been migrated successfully.
a) Issue the command to view cluster queue managers.

DISPLAY CLUSQMGR(*)

b) Issue the command to view cluster queues.

DISPLAY QC(*)

c) Issue the command to view cluster topics.

DISPLAY TCLUSTER(*)

3. Save a record from the full repository of its view of the cluster objects owned by this queue manager.
The record is used after migration to check that objects have been migrated successfully.
a) Issue the command on the full repositories to display this queue manager.

DISPLAY CLUSQMGR(migrated queue manager name)

b) Issue the command on the full repositories to display the cluster queues for this queue manager

DISPLAY QC(*) WHERE(CLUSQMGR EQ migrated queue manager name)

c) Issue the command on the full repositories to display the cluster topics for this queue manager.

DISPLAY TCLUSTER(*) WHERE(CLUSQMGR EQ migrated queue manager name)

4. Migrate the queue manager.

Do one of the queue manager migration tasks, depending on the platform; see “Migrating a queue
manager on Windows” on page 378.
The queue manager migration process is, in outline:
a) Stop the queue manager.
b) Take a backup of the queue manager.

Installing and migrating 455

 c) Install the new version of IBM MQ.
d) Restart the queue manager.
5. Ensure that all cluster objects have been migrated successfully.
a) Issue the command to view cluster queue managers and check the output against the data saved
before migration.

DISPLAY CLUSQMGR(*)

b) Issue the command to view cluster queues and check the output against the data saved before
migration.

DISPLAY QC(*)

c) Issue the command to view cluster topics and check the output against the data saved before
migration.

DISPLAY TCLUSTER(*)

6. Check that the queue manager is communicating with the full repositories correctly.
7. Check that cluster channels to full repositories can start.
8. Check that the full repositories still have information about the migrated cluster queue manager, its
cluster queues, and its cluster topics.
a) Issue the command on the full repositories and check the output against the data saved before
migration.

DISPLAY CLUSQMGR(migrated_queue_manager_name)

b) Issue the command on the full repositories and check the output against the data saved before
migration.

DISPLAY QC(*) WHERE(CLUSQMGR EQ migrated_queue_manager_name)

c) Issue the command on the full repositories and check the output against the data saved before
migration.

DISPLAY TCLUSTER(*) WHERE(CLUSQMGR EQ migrated_queue_manager_name)

9. Test that applications on other queue managers can put messages to queues owned by the migrated
cluster queue manager.
10. Test that applications on the migrated queue manager can put messages to the queues owned by
other cluster queue managers.
11. Resume the queue manager by issuing the following command:

RESUME QMGR CLUSTER(cluster name)

12. Closely monitor the queue manager and applications in the cluster for a while.

What to do next
When you have completed the migration of one queue manager in a cluster, on your test system, complete
the migration of the other queue managers in each cluster on the test system.
When you have competed the migration of all of the queue managers on your test system, migrate each of
the queue managers on your production system.

456 Installing and migrating IBM MQ

Related concepts
“Queue manager migration” on page 343
After upgrading an installation, queue manager migration might be required. Migration takes place when
you start a queue manager. You can remove an upgrade before you have started a queue manager.
However, if you remove the upgrade after a queue manager has been started, the queue manager will not
work.
Related reference
DISPLAYCLUSQMGR
DISPLAYQUEUE
RESUME QMGR
SUSPEND QMGR

Migrating a queue manager in a high-availability configuration

High-availability configurations of queue managers can increase the availability of IBM MQ applications. If
a queue manager, or server fails, it is restarted automatically on another server. You can arrange for IBM
MQ MQI client applications to automatically reconnect to the queue manager. Server applications can be
configured to start when the queue manager starts.

About this task

For IBM MQ for Multiplatforms, high-availability configurations can be implemented by using
a high-availability cluster solution or by using multi-instance queue managers. Red Hat Cluster Suite or
Microsoft Cluster Service (MSCS) are examples of high-availability cluster solutions.

For Linux platforms, you can implement high availability by using replicated data queue
managers (RDQMs). For migrating RDQMs, see “Migrating replicated data queue managers” on page 460.

Another solution is to configure a high availability group on a pair of IBM MQ Appliances. See
the Appliance documentation for details of migrating HA queue managers.
The overall principles involved in queue manager migration in a high availability configuration based
on multi-instance queue managers or on a high-availability cluster are the same. In either case, the
principles are as follows:
1. You must not restart a queue manager at a lower command level than the one it was previously
running.
2. You cannot upgrade the code if an active queue manager is running.
3. You cannot back up an active queue manager.

Procedure
• To migrate a multi-instance queue manager, see “Migrating a multi-instance queue manager” on page
458.
• To migrate a high availability cluster queue manager, see “Migrating a high-availability cluster queue
manager” on page 459.
Related tasks
“Migrating an MSCS configuration on Windows” on page 401

Installing and migrating 457

 Migrate queue managers in a Microsoft Cluster Service (MSCS) configuration one node at a time, following
these instructions.

Migrating a multi-instance queue manager

Follow the steps listed to migrate a queue manager in a multi-instance queue manager configuration.

Before you begin

The following terms are relevant:
active queue manager instance
A queue manager instance that has been started permitting standby instances, and is running.
standby queue manager instance
A queue manager instance that has been started permitting standby instances, and is in standby. It is
ready to take over from the active instance automatically.

Procedure
Base your migration procedure on the following steps:
1. Before you start the migration process, create a different queue manager on a server, on which you
have installed the upgrade.
2. Test the upgrade by performing whatever verification checks that your organization requires.
3. If you have a pool of servers that you pick from, when starting a queue manager instance, upgrade
IBM MQ on the servers that are in the pool and are neither active or acting as a standby.
4. Stop the standby queue manager instance.
Ensure that you have no system management procedure running that restarts the instance
automatically.
5. If you do not have a pool of servers, upgrade IBM MQ on the server that was running the standby
instance
6. Decide whether downtime or recoverability is more important in the migration.
7. Optional: Follow this procedure if recoverability is more important, and you must take a backup:
a) Stop the active queue manager instance, without switching to any standby.
b) Back up the queue manager
c) Start a queue manager instance, permitting standbys, on one of the upgraded servers.
d) If you have a pool of upgraded servers, start another one, permitting standbys.
8. Optional: Follow this procedure if availability is more important. You do not need to take a backup.
a) Start a queue manager instance as a standby on one of the upgraded servers.
b) Stop the active queue manager instance, switching to the standby.
c) If you have a pool of upgraded servers, start another one, permitting standbys.
9. Upgrade the IBM MQ code on the server that was the active queue manager instance.
10. Start the server as the standby instance if you have not already started a standby.
“Migrating a queue manager in a high-availability configuration” on page 457
High-availability configurations of queue managers can increase the availability of IBM MQ applications. If
a queue manager, or server fails, it is restarted automatically on another server. You can arrange for IBM
MQ MQI client applications to automatically reconnect to the queue manager. Server applications can be
configured to start when the queue manager starts.
“Migrating a high-availability cluster queue manager” on page 459

458 Installing and migrating IBM MQ

Follow the steps listed to migrate a queue manager in a high-availability queue manager configuration.

Migrating a high-availability cluster queue manager

Follow the steps listed to migrate a queue manager in a high-availability queue manager configuration.

Before you begin

The following terms are relevant:
active server
The running server or active queue manager instance
passive server
A server that is ready to take over from the active server automatically.
inactive server
A server that is not prepared to take over automatically. The server might have been removed from the
cluster, or taken offline in some way.

Procedure
Base your migration procedure on the following steps. The details depend on the specific commands in
the cluster concerned.
1. Before you start the migration process, create a different queue manager on a server on which you
have installed the upgrade.
2. Test the upgrade by performing whatever verification checks that your enterprise requires.
3. Form two cluster pairs if you have four servers available.
With two pairs, the queue manager can continue to run in a cluster-pair at the old command level.
When you are ready, you can transfer the queue manager to the pair of servers at the new command
level.
4. Remove a passive server from the cluster.
Ensure that the cluster cannot automatically restart the server. The server is made inactive.
5. Create a second location for the upgraded code, if a high-availability cluster is using a common
location for IBM MQ code.
6. Install, or upgrade, IBM MQ code using the server that is not now running the queue manager.
7. Verify the upgrade by creating a different queue manager on the server, and performing whatever
verification checks that your organization requires.
8. If more than half the servers remain in the cluster, remove a server, upgrade IBM MQ, and verify the
upgrade.
Each server is made inactive as part of the process. Continue until half the servers are upgraded.
9. If your active server is part of a remaining cluster, deactivate the passive servers so that the cluster
cannot reactivate them automatically.
10. Decide whether downtime or recoverability is more important in the migration.
11. Optional: Follow this procedure if recoverability is more important:
a) Stop the queue manager and remove the server from the cluster.
b) Back up the queue manager.
12. Optional: Follow this procedure if downtime is more important:
a) Add the migrated servers back into the cluster, as passive servers.
b) Switch the remaining server in the high-availability server cluster over to one of the passive
servers.
The switch causes the running queue manager to stop, and restarts it on one of the passive
servers.
13. Upgrade any remaining high-availability servers, and add them back into the cluster.

Installing and migrating 459

 “Migrating a queue manager in a high-availability configuration” on page 457
High-availability configurations of queue managers can increase the availability of IBM MQ applications. If
a queue manager, or server fails, it is restarted automatically on another server. You can arrange for IBM
MQ MQI client applications to automatically reconnect to the queue manager. Server applications can be
configured to start when the queue manager starts.
“Migrating a multi-instance queue manager” on page 458
Follow the steps listed to migrate a queue manager in a multi-instance queue manager configuration.

Migrating an RDQM configuration from RHEL 8 to RHEL 9

If you upgrade from RHEL 8 to RHEL 9, you must create a new Pacemaker cluster and migrate your
replicated data queue managers (RDQMs) to the new cluster.

About this task

You must set up a separate RHEL 9 cluster and migrate each RDQM HA queue manager to it, using a
backup and restore procedure. If you use a floating IP address to connect to an RDQM queue manager
then you must recreate that floating IP address on the RHEL 9 cluster.

Procedure
1. Configure three RHEL 9 nodes.
2. Install IBM MQ Advanced on each of them, see “Installing IBM MQ Advanced for Multiplatforms” on
page 236.
3. Configure a new Pacemaker cluster to create a new HA group, see Defining the Pacemaker cluster (HA
group).
4. Recreate each queue manager that you want to from the existing RHEL 8 HA Group, see Creating an HA
RDQM.
5. For each RDQM queue manager to be moved, complete the following actions:
a) End the RDQM queue manager on the RHEL 9 node.
b) End the RDQM queue manager on the RHEL 8 node.
c) Take a backup of the RDQM queue manager, its config and its data as required, on the RHEL 8 node,
see Backing up and restoring IBM MQ queue manager data.
d) Restore the backup on the RHEL 9 node.
6. Start the RDQM queue manager on the RHEL 9 node.
7. If required, configure the floating IP address on the RHEL 9 HA group, see Creating and deleting a
floating IP address.
8. After you confirm that the RDQM queue manager is working correctly on the RHEL 9 HA group, delete
the queue manager from the RHEL 8 HA group, see Deleting an HA RDQM.

Migrating replicated data queue managers

When you need to migrate replicated data queue managers (RDQMs), you must upgrade all nodes in a
sequence. Do not try to operate with the nodes at different levels.
This guidance is appropriate for moving between major releases, or CD releases, but not for applying (fix
pack) maintenance. (See “Applying maintenance level updates for RDQM” on page 301.)
Note: RHEL 7 is not supported on 9.4. If you were using RHEL 7 you must upgrade to RHEL 8 or RHEL 9 as
part of this migration. You must set up a separate RHEL 9 or RHEL 8 cluster and migrate each RDQM HA
queue manager to it, using a backup and restore procedure. If you use a floating IP address to connect to
an RDQM queue manager then you must recreate that floating IP address on the new cluster.
The upgrade sequence for HA RDQM configurations consists of suspending a node, uninstalling IBM MQ
and RDQM support, installing the newer version of IBM MQ and RDQM support, then resuming the node.
You then move on and repeat this sequence on the next node. Following this sequence ensures that your
queue managers continue to run on one of the nodes in the HA group while the migration is in progress.

460 Installing and migrating IBM MQ

The upgrade sequence for DR RDQM configurations consists of upgrading the recovery node, running the
DR queue managers on the newly upgraded recovery node, upgrading the primary node, switching the DR
queue managers back to running on the primary node.
The upgrade sequence for DR/HA RDQM configurations consists of upgrading the HA group on the
recovery site, performing a managed failover from the main site to the recovery site, and then upgrading
the HA group on the main site before failing the queue managers back to the main site.
You can back up a replicated data queue manager before migration.
Related tasks
“Installing RDQM (replicated data queue managers)” on page 255
Installation tasks associated with RDQM are grouped in this section. RDQM is available on x86-64 for
RHEL 8 (8.8 or later) and RHEL 9 (9.2 or later).

Migrating HA RDQMs
Follow this sequence of steps to upgrade all the RDQM nodes in an HA group and so migrate the
replicated data queue managers (RDQMs).

About this task

You should upgrade all the nodes in an HA group in the same sequence to avoid operating with the nodes
in the group at different levels.
Note: RHEL 7 is not supported on 9.4. If you were using RHEL 7 you must upgrade to RHEL 8 or RHEL 9 as
part of this migration. You must set up a separate RHEL 9 or RHEL 8 cluster and migrate each RDQM HA
queue manager to it, using a backup and restore procedure. If you use a floating IP address to connect to
an RDQM queue manager then you must recreate that floating IP address on the new cluster.
If you have configured your HA group such that one node acts as a primary for all RDQMs, with the other
two nodes as secondaries, you should upgrade the secondary nodes first and leave the primary node until
last.
The sequence in which you upgrade, and the nodes that are marked as preferred and second preferred
locations for RDQMs, affect where the RDQMs fail over to as you upgrade. During the migration sequence,
while nodes are running different levels, the options for failing over are limited. An RDQM running on
a lower level node can fail over to a higher level node but, once a queue manager has been started at
the new level, it cannot fail over to a lower level node. You should choose an upgrade sequence and
use preferred and second preferred locations settings to keep queue managers running on the lower
level nodes for as long as possible. You should make changes to preferred and second preferred location
settings before you suspend nodes, to ensure that the changes are effective immediately.
If you are also running DR RDQMs on any of the nodes, you should deal with these queue managers at the
same time by following the instructions in “Migrating DR RDQMs” on page 462.

Procedure
• Uninstall HA RDQM support and upgrade RDQM and IBM MQ.
a) Suspend the HA group on the node, by entering the following command:

rdqmadm -s

b) Log in as root or switch to superuser using the su command.

c) Uninstall IBM MQ (this step also uninstalls RDQM):

rpm -qa | grep MQSeries | xargs yum -y remove

d) Uninstall Pacemaker:

rpm -qa | grep linbit | xargs yum -y remove

e) Uninstall DRBD:

Installing and migrating 461

 rpm -qa | grep drbd | xargs yum -y remove

f) Verify that the DRBD kernel was successfully unloaded:

lsmod | grep drbd

If either the drbd or drbd_transport_tcp kernel modules are still loaded, they can be unloaded with
the following commands:

modprobe -r drbd_transport_tcp
modprobe -r drbd

If the unload fails for any reason, reboot the node.

g) Install the new level of IBM MQ and dependent software, see Installing RDQM (replicated data
queue managers).
h) Resume the HA group on the node by entering the following command:

rdqmadm -r

You can now proceed to the next node in the group.

• Repeat the steps for the second node in the HA group. (Use the same path as you did on the first
node.)
• Repeat the steps for the third node in the HA group. (Use the same path as you did on the first node.)
Related reference
rdqmadm (administer replicated data queue manager cluster)

Migrating DR RDQMs
Follow this sequence of steps to upgrade the primary and recovery nodes in a disaster recover replicated
data queue manager (DR RDQM) configuration.

About this task

The suggested sequence for upgrading your nodes is to upgrade your recovery node, then run your DR
queue managers there while you then upgrade your primary node. When both nodes are upgraded you
can restore the original primary and recovery roles.
Note: RHEL 7 is not supported on 9.4. If you were using RHEL 7 you must upgrade to RHEL 8 or RHEL 9
as part of this migration. You must set up a separate RHEL 9 or RHEL 8 cluster and migrate each RDQM
queue manager to it, using a backup and restore procedure.
If you do not require to run your DR queue managers during the upgrade procedure, then you can omit the
steps for failing over to the recovery node. You can just stop your DR queue managers and restart them
after you have upgraded both nodes.
If you are also running HA RDQMs on either of the nodes, you should deal with these queue managers at
the same time by following the instructions in “Migrating HA RDQMs” on page 461.

Procedure
• Uninstall DR RDQM and IBM MQ and upgrade RDQM and IBM MQ.
a) Upgrade the DR secondary node:
a. Log in as root or switch to superuser using the su command.
b. Uninstall IBM MQ (this step also uninstalls RDQM):

rpm -qa | grep MQSeries | xargs yum -y remove

462 Installing and migrating IBM MQ

 c. Uninstall Pacemaker:

rpm -qa | grep linbit | xargs yum -y remove

d. Uninstall DRBD:

rpm -qa | grep drbd | xargs yum -y remove

e. Verify that the DRBD kernel was successfully unloaded:

lsmod | grep drbd

If either the drbd or drbd_transport_tcp kernel modules are still loaded, they can be unloaded
with the following commands:

modprobe -r drbd_transport_tcp
modprobe -r drbd

If the unload fails for any reason, reboot the node.

f. Install the new levels of IBM MQ and RDQM, see Installing RDQM (replicated data queue
managers).
b) On the DR primary node, do one of the following steps:
– End the DR queue managers, or
– Perform a managed failover of the DR queue managers to the DR secondary node.
c) Upgrade the DR primary node:
a. Log in as root or switch to superuser using the su command.
b. Uninstall IBM MQ (this step also uninstalls RDQM):

rpm -qa | grep MQSeries | xargs yum -y remove

c. Uninstall Pacemaker:

rpm -qa | grep linbit | xargs yum -y remove

d. Uninstall DRBD:

rpm -qa | grep drbd | xargs yum -y remove

e. Verify that the DRBD kernel was successfully unloaded:

lsmod | grep drbd

If either the drbd or drbd_transport_tcp kernel modules are still loaded, they can be unloaded
with the following commands:

modprobe -r drbd_transport_tcp
modprobe -r drbd

If the unload fails for any reason, reboot the node.

f. Install the new levels of IBM MQ and RDQM, see Installing RDQM (replicated data queue
managers).
d) On the DR primary node, do one of the following steps:
– Start the DR queue managers (if you previously ended them), or
– Perform a managed failover of the DR queue managers back to the DR primary node.

Installing and migrating 463

 Migrating DR/HA RDQMs
Follow these steps to upgrade all the RDQM nodes in both HA groups in a DR/HA configuration, and so
migrate the replicated data queue managers (RDQMs).

About this task

The suggested sequence for upgrading your nodes is to upgrade the HA group at your recovery site, then
run your DR/HA queue managers there while you upgrade the HA group at your main site. When both HA
groups are upgraded you can restore the original main and recovery roles.
Note: RHEL 7 is not supported on 9.4. If you were using RHEL 7 you must upgrade to RHEL 8 or RHEL 9 as
part of this migration. You must set up a separate RHEL 9 or RHEL 8 cluster and migrate each RDQM HA
queue manager to it, using a backup and restore procedure. If you use a floating IP address to connect to
an RDQM queue manager then you must recreate that floating IP address on the new cluster.

Procedure
• Uninstall DR/HA RDQM and IBM MQ and upgrade RDQM and IBM MQ.
a) Upgrade the HA group on your recovery site (presuming that the DR/HA RDQMs are running on the
main site). Complete the following steps on each node in the group in turn.
a. Log in as root or switch to superuser using the su command.
b. Suspend the HA group on the node, by entering the following command:

rdqmadm -s

c. Uninstall IBM MQ (this step also uninstalls RDQM):

rpm -qa | grep MQSeries | xargs yum -y remove

d. Uninstall Pacemaker:

rpm -qa | grep linbit | xargs yum -y remove

e. Uninstall DRBD:

rpm -qa | grep drbd | xargs yum -y remove

f. Verify that the DRBD kernel was successfully unloaded:

lsmod | grep drbd

If either the drbd or drbd_transport_tcp kernel modules are still loaded, they can be unloaded
with the following commands:

modprobe -r drbd_transport_tcp
modprobe -r drbd

If the unload fails for any reason, reboot the node.

g. Install the new level of IBM MQ and dependent software, see Installing RDQM (replicated data
queue managers).
h. Resume the HA group on the node by entering the following command:

rdqmadm -r

You can now proceed to the next node in the group.

b) On the HA group at the main site, either stop your queue managers, or perform a managed failover
to the HA group that you have just upgraded on the recovery site.
c) Upgrade the HA group on your main site. Complete the following steps on each node in the group in
turn.

464 Installing and migrating IBM MQ

 a. Log in as root or switch to superuser using the su command.
b. Suspend the HA group on the node, by entering the following command:

rdqmadm -s

c. Uninstall IBM MQ (this step also uninstalls RDQM):

rpm -qa | grep MQSeries | xargs yum -y remove

d. Uninstall Pacemaker:

rpm -qa | grep linbit | xargs yum -y remove

e. Uninstall DRBD:

rpm -qa | grep drbd | xargs yum -y remove

f. Verify that the DRBD kernel was successfully unloaded:

lsmod | grep drbd

If either the drbd or drbd_transport_tcp kernel modules are still loaded, they can be unloaded
with the following commands:

modprobe -r drbd_transport_tcp
modprobe -r drbd

If the unload fails for any reason, reboot the node.

g. Install the new level of IBM MQ and dependent software, see Installing RDQM (replicated data
queue managers).
h. Resume the HA group on the node by entering the following command:

rdqmadm -r

You can now proceed to the next node in the group.

d) You can now either start your queue managers (if you previously stopped them) or fail them back
over to the main site from the recovery site.
Related tasks
“Migrating HA RDQMs” on page 461
Follow this sequence of steps to upgrade all the RDQM nodes in an HA group and so migrate the
replicated data queue managers (RDQMs).
“Migrating DR RDQMs” on page 462
Follow this sequence of steps to upgrade the primary and recovery nodes in a disaster recover replicated
data queue manager (DR RDQM) configuration.

Migrating to Internet Protocol version 6 (IPv6)

IBM MQ lets queue managers communicate using IPv6 in addition to IPv4. This simplifies migration from
IPv4 to IPv6.

Before you begin

When you are thinking of installing IBM MQ and using IPv6, bear in mind the following key points:
• IBM MQ recognizes IPv6 hexadecimal addresses (for example
fe80:43e4:0204:acff:fe97:2c34:fde0:3485) as well as IPv4 dotted decimal addresses (for example
9.20.9.30).
• For a system running both IPv4 and IPv6 system, the connection name (CONNAME) you specify for a
given channel determines the IP protocol for the channel making a connection.

Installing and migrating 465

 • To ensure consistency across the network, you should plan the introduction of IPv6 for the whole
network, especially where clusters are involved. For example, although a queue manager is now IPv6
capable, this doesn't imply that the queue managers it can communicate with are also IPv6 capable.
• When setting the domain name server (DNS) or equivalent, consider whether the system on which the
target queue manager is running can resolve to an IPv4 address, an IPv6 address or a dual IPv4 and
IPv6 address.
• If the system that you are installing IBM MQ on does not support IPv6, IBM MQ will only be able to
connect using IPv4.
• For a queue manager running on an IPv6 enabled system to be able to communicate with a queue
manager running on an IPv4 enabled system, the IPv4 enabled system must have a host name that
resolves to an IPv4 address only.
• If there are multiple domain name servers in an IBM MQ network, each host name used in a channel
definition must resolve to the same address (or addresses), regardless of which DNS is used.

About this task

Internet Protocol version 6 (IPv6) is designed by the Internet Engineering Task Force (IETF) to replace
Internet Protocol version 4 (IPv4). IPv4 has been in use for over 20 years and is one of the primary
methods for machines to communicate with each other over the internet. IPv4 is limited to 32-bit
addressing for internet addresses. These addresses are needed by all new machines added to the internet
and they are beginning to run out. The IETF is the controlling standards body for the Internet and to meet
the growing demand for internet addresses the IETF has increased the number of digits used for Internet
addresses from 32 to 128 bits. IPv6 offers a far larger number (2 128 ) of internet addresses and should
solve the address shortage for the foreseeable future. IPv6 is expected to gradually replace IPv4, with
the two protocols coexisting for a number of years. IPv6 also simplifies header formats and improves
support for extensions and options, flow labeling capability, and consolidated authentication and privacy
capabilities.
IPv6 is supported on the following IBM MQ platforms:

• AIX

• IBM i

• Linux

• Windows
For more information about IPv6, see IPv6.

Migrating a queue manager to IPv6

This section deals with migrating a queue manager when you are thinking of installing IBM MQ on an IPv6
network.

The IPv6 protocol can only be used by IBM WebSphere MQ 6.0 or later. In order to make use of the IPv6
protocol, IBM MQ must be installed on a system that is IPv6 capable.
The preferred IP version that two systems use for communicating (if both IPv4 and IPv6 are available)
is determined by a new queue manager attribute IPADDRV. This parameter only has an effect if the host
name resolves ambiguously to both an IPv4 address and an IPv6 address.
To migrate a queue manager to use the IPv6 protocol:
1. Configure dual IPv4 and IPv6 protocols on the system where the queue manager to be migrated
resides.
2. Install IBM MQ.
3. Add an entry to the DNS to resolve the host name of the system that is to be migrated, to both an IPv4
address and an IPv6 address.

466 Installing and migrating IBM MQ

4. Set the IPADDRV parameter to IPv6 (or set the LOCLADDR parameter to resolve to an IPv6 address).

CAUTION: Not all IPv6 software can interpret an IPv4 mapped IPv6 address. If the
combination of CONNAME and LOCLADDR results in an IPv4 mapped IPv6 address, ensure
that the system hosting the target queue manager is capable of handling this.
Using mapped addresses can require protocol translators in the IP network.

Migration scenarios (non-cluster topology)

It is possible to come up with a number of different interconnection possibilities, and the following
sections aim to help you understand how IBM MQ will work in each case.
Non-cluster migration scenario 1
Three systems exist that are IPv4 only capable. Each system hosts a queue manager (QM1, QM2,
and QM3) and each queue manager connects to the other two. All CONNAMEs in the cluster channel
definitions are made using DNS names rather than IP addresses.
Enable QM1 to be able to use channels running over IPv6 as follows
1. Upgrade the host system to have dual IPv4 and IPv6 stacks.
Important: A listener is required for each IP stack.
2. Install the latest version of IBM MQ.
3. Update the DNS table so that it has two entries for the system running QM1; one entry for its IPv4
address and one for its IPv6 address. This enables a DNS name request to return both IPv4 and
IPv6 addresses for this host.
4. Set the queue manager IPADDRV attribute to IPv6.
Note: Even with these changes made to support IPv6 addressing, QM1 will still be able to
communicate with queue managers (both existing and new ones) that are only IPv4 capable.
Enable QM2 to be able to use channels running over IPv6 as for QM1 above.
• Communications between QM1 and QM2 will now be over IPv6.
• Communications between QM1 and QM3 will still be over IPv4.
• Communications between QM2 and QM3 will still be over IPv4.
With the queue manager IPADDRV attribute set to IPv6, the preference has been set for the queue
manager to connect using the IPv6 protocol. If a channel from QM1 to QM3 has LOCLADDR set to a
host name which resolves to an IPv6 address, or both IPv4 and IPv6 addresses (with the IPADDRV
attribute set to IPv6, the IPv6 address will be returned as that is the preference), this channel will
attempt to use the IPv6 protocol. If the IPv6 protocol installed on the QM1 host system is capable of
using a mapped address then QM1 will communicate with QM3 over IPv6. Otherwise, the channel will
fail to resolve CONNAME.
While QM3 remains a queue manager on an earlier version of the product, you will need to check that
all CONNAMEs used to start a channel to QM3 do not resolve to an IPv6 address or dual IPv4 and IPv6
addresses where the IPv6 address could be returned. This would cause QM1 to attempt to start the
channel over IPv6 which would fail, as it would be unable to resolve the CONNAME.
It is possible to upgrade a system to have dual IPv4 and IPv6 capability and still run a queue manager
on an earlier version of the product, on the system. While it is not recommended to run this type of
configuration, as long as the addresses that are returned to this level of queue manager are either
IPv4 or an IPv4 mapped version of an IPv6 address, this should work.
Non-cluster migration scenario 2
Three systems exist that are IPv4 only capable. Each system hosts a queue manager (QM1, QM2,
and QM3) and each queue manager connects to the other two. All CONNAMEs in the cluster channel
definitions are made using IP addresses.

Installing and migrating 467

 Because addresses have been specified instead of DNS names, to allow a queue manager to connect
to another using the IPv6 protocol you will need to duplicate the definitions that use IPv4 addresses
between them and provide them with IPv6 addresses instead. The original definitions that use IPv4
addresses will continue to work, but if you intend to take advantage of the IPv6 protocol, you will need
to connect using the new definitions.
Enable QM1 to be able to use channels running over IPv6 as follows
1. Upgrade the host system to have dual IPv4 and IPv6 stacks.
Important: A listener is required for each IP stack.
2. Install IBM MQ.
3. Duplicate the channel, transmission queue and, where applicable, any process definitions using
IPv6 addresses where required.
Note: Even with these changes made to support IPv6 addressing, QM1 will still be able to
communicate with existing queue managers that are only IPv4 capable.
Enable QM2 to be able to use channels running over IPv6 as for QM1 above.
1. Upgrade the host system to have dual IPv4 and IPv6 stacks.
Important: A listener is required for each IP stack.
2. Install IBM MQ.
3. Where necessary amend applications to write to the new remote queue (created above for QM1
with the IPv6 addresses).
4. Verify the channels can be started.
The queue managers can now connect as follows:
• QM1 can now connect with QM2 over either IPv4 or IPv6 depending on the channel the application
writes its messages to.
• QM1 still connects with QM3 over IPv4 using the original definitions.

Migrating a cluster to IPv6

This section deals with migrating clusters when you are thinking of installing IBM MQ on an IPv6 capable
network.
The following gives an overview of approaches that can be taken when migrating a cluster to the latest
version of IBM MQ. Due to the variations that can occur within a cluster, the detail is deliberately general
and should only be seen as a guide to the likely course of action you will need to take.

Migration scenarios (cluster topology)

Where an IPv6 capable system is to be added to an IBM MQ cluster, all full repository systems in that
cluster must be IPv6 capable.
The following scenarios are seen as the ones most likely to occur in customer installations. They describe
the changes that are likely to be required.
Scenario 1
A cluster from an earlier version of the product is installed on IPv4 only capable, systems and you
need to connect an IPv6 only capable system into the cluster. All CONNAMEs in cluster channel
definitions are made using DNS names rather than IP addresses.
When adding a new IPv6 only system to the cluster, identify those queue managers that your new
system will communicate with. These include:
• The queue managers your new system will send messages to.
• The queue managers your new system will receive messages from.
• The full repository queue managers

468 Installing and migrating IBM MQ

 The systems that you have identified must be upgraded before introducing the new system.
Recommended migration procedure:
• Upgrade each of the systems hosting a full repository queue manager as shown in "Migrating a
queue manager to IPv6" non-cluster scenario 1.
• Upgrade the remaining cluster systems which need to be IPv6 capable as shown in "Migrating a
queue manager to IPv6" non-cluster scenario 1.
With this configuration:
• The new IPv6 only capable system will communicate with the cluster using IPv6 addressing
• All other IPv4 systems that connect into the cluster will continue to communicate using IPv4
addressing
• The systems in the cluster will be able to connect to each other using either IPv4 or IPv6
addressing. The decision as to which address is used depends on whether you have set IPADDRV to
specify IPv4 or IPv6 connections.
Scenario 2
A cluster from an earlier version of the product is installed on IPv4 only capable systems and you need
to connect an IPv6 only capable system into the cluster. Your network does not support adding both
IPv6 and IPv4 addresses using the same host name or you are using IP addresses rather than DNS
names in the cluster channel CONNAMEs.
The problem here is likely to be that all of the systems cannot be switched to IPv6 simultaneously
and some at least must remain only IPv4 capable. The systems that your new IPv6 only system
communicates with must be IPv4 and IPv6 capable. We do not recommend simply adding a new set
of IPv6 channels into the cluster for the IPv6 system to use, as the IPv4 system would also try to use
them, resulting in communication errors.
The recommended approach is:
• Define a new cluster which contains the IPv6 only capable system or systems with new IPv6
addresses and channel definitions. The existing cluster remains, and contains the IPv4 only system
definitions. The image below gives a pictorial representation of this. QM1, QM2, and QM3 represent
the original IPv4 cluster. QM2, QM3, and QM4 represent the new cluster created to allow the IPv6
only capable system (QM4) to connect into your configuration.
• If you are using DNS names, you can give each of the systems separate DNS names for IPv4 and
IPv6 (for example system1_ip4.ibm.com and system1_ip6.ibm.com).
• Define a new CLUSRCVR channel and any corresponding CLUSSDR channels using the new IPv6
names or IP addresses on each system in the new cluster. In this way the systems with only IPv4 or
IPv6 capability do not see channels which they are not able to use and no communications error will
result.

Note: There are both IPv4 and IPv6 definitions connecting the full repositories so that definitions
for both new and existing cluster definitions are replicated between them. Also be aware that the
queue managers QM1 and QM4 cannot communicate directly because they do not share a common

Installing and migrating 469

 network. They could communicate indirectly, for example by using ALIAS queues defined in the queue
managers QM2 and QM3. In the configuration shown above you would need to pay attention to the
ordering of application messages flowing between QM2 and QM3 because multiple routes exist, if this
is relevant you could use BIND_OPEN to fix the route.

Abbreviated migration scenarios

This section gives some abbreviated scenarios for when you are thinking of installing clusters on IBM MQ

Abbreviated scenarios: Effects of CONNAME and LOCLADDR settings

The following table provides an overview of what will occur for the different TCP/IP stacks (IPv4 only, IPv6
only and dual IPv4 and IPv6 stacks) and given the settings for CONNAME and LOCLADDR the expected
connection result.
Note: Using mapped addresses can require protocol translators in the IP network.

Table 44. Effects of CONNAME and LOCLADDR settings

Stack Type CONNAME setting LOCLADDR setting Connection result
IPv4 only stack IPv4 address Channel binds to IPv4 stack
IPv6 address Channel fails to resolve
CONNAME
Host name resolves to both Channel binds to IPv4 stack
IPv4 and IPv6 addresses
IPv4 address IPv4 address Channel binds to IPv4 stack
IPv6 address IPv4 address Channel fails to resolve
CONNAME
Host name resolves to both IPv4 address Channel binds to IPv4 stack
IPv4 and IPv6 addresses
Any address IPv6 address Channel fails to resolve
LOCLADDR
IPv4 address Host name resolves to both Channel binds to IPv4 stack
IPv4 and IPv6 addresses
IPv6 address Host name resolves to both Channel fails to resolve
IPv4 and IPv6 addresses CONNAME
Host name resolves to both Host name resolves to both Channel binds to IPv4 stack
IPv4 and IPv6 addresses IPv4 and IPv6 addresses

Dual IPv4 and IPv4 address Channel binds to IPv4 stack

IPv6 stack
IPv6 address Channel binds to IPv6 stack
Host name resolves to both Channel binds to stack
IPv4 and IPv6 addresses determined by IPADDRV
IPv4 address IPv4 address Channel binds to IPv4 stack
IPv6 address IPv4 address Channel fails to resolve
CONNAME
Host name resolves to both IPv4 address Channel binds to IPv4 stack
IPv4 and IPv6 addresses

470 Installing and migrating IBM MQ

Table 44. Effects of CONNAME and LOCLADDR settings (continued)
Stack Type CONNAME setting LOCLADDR setting Connection result
IPv4 address IPv6 address Maps an IPv4 CONNAME
to an IPv4 mapped
IPv6 address. IPv6
implementations that do not
support IPv4 mapped IPv6
addressing fail to resolve
CONNAME
IPv6 address IPv6 address Channel binds to IPv6 stack
Host name resolves to both IPv6 address Channel binds to IPv6 stack
IPv4 and IPv6 addresses
IPv4 address Host name resolves to both Maps an IPv4 CONNAME
IPv4 and IPv6 addresses to an IPv4 mapped
IPv6 address. IPv6
implementations that do not
support IPv4 mapped IPv6
addressing fail to resolve
CONNAME
IPv6 address Host name resolves to both Channel binds to IPv6 stack
IPv4 and IPv6 addresses
Host name resolves to both Host name resolves to both Channel binds to IPv6 stack
IPv4 and IPv6 addresses IPv4 and IPv6 addresses

IPv6 only stack IPv4 address Maps an IPv4 CONNAME

to an IPv4 mapped
IPv6 address. IPv6
implementations that do not
support IPv4 mapped IPv6
addressing fail to resolve
CONNAME
IPv6 address Channel binds to IPv6 stack
Host name resolves to both Channel binds to IPv6 stack
IPv4 and IPv6 addresses
Any address IPv4 address Channel fails to resolve
LOCLADDR
IPv4 address IPv6 address Maps an IPv4 CONNAME
to an IPv4 mapped
IPv6 address. IPv6
implementations that do not
support IPv4 mapped IPv6
addressing fail to resolve
CONNAME
IPv6 address IPv6 address Channel binds to IPv6 stack
Host name resolves to both IPv6 address Channel binds to IPv6 stack
IPv4 and IPv6 addresses

Installing and migrating 471

Table 44. Effects of CONNAME and LOCLADDR settings (continued)
Stack Type CONNAME setting LOCLADDR setting Connection result
IPv4 address Host name resolves to both Maps an IPv4 CONNAME
IPv4 and IPv6 addresses to an IPv4 mapped
IPv6 address. IPv6
implementations that do not
support IPv4 mapped IPv6
addressing fail to resolve
CONNAME
IPv6 address Host name resolves to both Channel binds to IPv6 stack
IPv4 and IPv6 addresses
Host name resolves to both Host name resolves to both Channel binds to IPv6 stack
IPv4 and IPv6 addresses IPv4 and IPv6 addresses

Abbreviated scenarios: System configurations

Table 46 on page 473 gives a number of abbreviated scenarios based on the configuration of the installed
queue managers and the IP configuration they are running on. The list is not intended to be exhaustive,
but to give a number of examples of what to expect based on the configurations shown.
The abbreviations are combined in Table 46 on page 473 to give the configuration of the systems involved
in trying to establish communication. For example:
• v71 + IPv6: Represents a queue manager from an earlier version of the product on a system with a
TCP/IP 6 stack
• v8 + Dual: Represents a queue manager from the latest version of the product on system with a dual
TCP/IP 4 and 6 stack

Table 45. Abbreviations used in system configurations

Abbreviation Meaning
v71 queue manager from an earlier version of the product
v8 queue manager from the latest version of the product

IPv4 a system using an IPv4 only stack

IPv6 a system using an IPv6 only stack
Dual a system using both an IPv4 and an IPv6 stack

IPv4DNS DNS returns an IPv4 address only for host name of system holding the responding queue
manager
IPv6DNS DNS returns an IPv6 address only for host name of system holding the responding queue
manager
DualDNS DNS returns an IPv4 and IPv6 address for host name of system holding the responding
queue manager

LOCLADDR4 The LOCLADDR parameter is set to IPv4 addressing

LOCLADDR6 The LOCLADDR parameter is set to IPv6 addressing

IPADDR4 IPADDRV is set to IPv4 addressing

IPADDR6 IPADDRV is set to IPv6 addressing

472 Installing and migrating IBM MQ

Table 46. System configurations
Originating queue manager Responding queue manager Result
Queue LOCLADDR IPADDRV Queue DNS Return
manager and Manager and
Stack Stack

v71 + IPv6 Any Not IP Error

applicable

v71 + IPv4 or Both Not v71 + IPv4 or IPv4DNS or IPv4 connection can be
v71 + Dual LOCLADDR4 applicable v71 + Dual DualDNS established
&
LOCLADDR6

v71 + IPv4 or Blank or Not v71 + IPv4 or IPv4DNS or IPv4 connection can be
v71 + Dual LOCLADDR4 applicable v71 + Dual DualDNS established

v71 + IPv4 or Blank or Not v71 + Dual IPv6DNS Unable to resolve

v71 + Dual LOCLADDR4 applicable CONNAME

v71 + IPv4 or Blank or Not v71 + Dual or IPv4DNS or IPv4 connection can be
v71 + Dual LOCLADDR4 applicable v8 + Dual DualDNS established
v8 + IPv4

v71 + IPv4 or LOCLADDR6 Not IP Error

v71 + Dual applicable

v71 + IPv4 or Blank or Not v8 + IPv6 IPv6DNS Unable to resolve

v71 + Dual LOCLADDR4 applicable CONNAME
or both
LOCLADDR4
&
LOCLADDR6

v8 + IPv4 Blank or Not specified v71 + IPv4 or IPv4DNS or IPv4 connection can be
LOCLADDR4 v71 + Dual or DualDNS established
v8 + IPv4

v8 + IPv4 LOCADD6 Not specified Unable to resolve

LOCLADDR

v8 + IPv4 Blank or Not specified v8 + IPv6 IPv6DNS Unable to resolve

LOCLADDR4 CONNAME

v8 + IPv6 Blank or Not specified v71 + Dual DualDNS Attempts to start IPv6
LOCLADDR6 channel and fails as there
will be no IPv6 listener
available

Installing and migrating 473

Table 46. System configurations (continued)
Originating queue manager Responding queue manager Result
Queue LOCLADDR IPADDRV Queue DNS Return
manager and Manager and
Stack Stack

v8 + IPv6 Blank or Not specified v71 + IPv4 IPv4DNS Attempts to start IPv6
LOCLADDR6 channel and fails as there
will be no IPv6 listener
available

v8 + IPv6 or LOCLADDR6 Blank or v8 + IPv6 or IPv6DNS or IPv6 connection can be

v8 + Dual IPADDR6 v8 + Dual DualDNS established

v8 + Dual LOCLADDR6 IPADDR4 v8 + Dual IPv4DNS or IPv6 connection can be

DualDNS established where
mapped addressing can
be used

v8 + Dual Blank or IPADDR4 v71 + Dual IPv4DNS or IPv4 connection can be

LOCLADDR4 DualDNS established

v8 + Dual Both Blank or v71 + Dual IPv4DNS or IPv4 connection can be

LOCLADDR4 IPADDR4 DualDNS established
&
LOCLADDR6

v8 + Dual LOCLADDR4 IPADDR4 Unable to resolve

LOCLADDR

v8 + Dual LOCLADDR6 Blank or v8 + IPv6 or IPv6DNS or IPv6 connection can be

or both IPADDR6 v8 + Dual DualDNS established
LOCLADDR4
&
LOCLADDR6

Migrating existing security configurations to use an alias CipherSpec

Migrating existing secure channel definitions to use an alias CipherSpec, for example,
ANY_TLS12_OR_HIGHER, ANY_TLS13_OR_HIGHER, and so on, means that your enterprise can adapt
to cipher additions and deprecations without needing to make further invasive configuration changes in
the future.
In general terms, the migration step to use an alias CipherSpec is no different from the process you use
to change any CipherSpec. That is, change the value of the CipherSpec for the channel definition at each
end, and then restart the channels for the change to take effect.
The procedure described in the preceding text can be particularly challenging in clustering environments.
Typically, you need to update manually defined channel definitions to a full repository one at a time.
To simplify migration, you make the change to specify an alias CipherSpec on a channel definition pairing
on the responding message channel agent (that is SVRCONN, RCVR, and so on) first. For example, if the
channel definition currently uses a specific TLS 1.2 CipherSpec, then modifying the responding message
channel agent to use ANY_TLS12_OR_HIGHER allows the sending message channel agent to continue
using the specific TLS 1.2 cipher.

474 Installing and migrating IBM MQ

 If you plan to change an existing cluster to use alias CipherSpecs, you first need to ensure that all
members of the cluster are at IBM MQ 9.1.4, or higher, and if there are z/OS queue managers in the
cluster, these need to be at IBM MQ 9.2.0 or later, in order to understand the new CipherSpec value. The
procedure for migration is the same as migrating from plaintext to SSL or TLS. See Upgrading clustered
queue managers and channels to SSL/TLS for more information.
Once both initiating and responding channel definitions use an alias CipherSpec, the negotiation of the
TLS cipher varies, based on the availability of different algorithms on platform and maintenance levels.
Note, that although no assurance can be made on the exact CipherSpec that is chosen, the channel
will only use the TLS protocol allowed by the alias CipherSpec considering FIPS, SUITEB, and weak
CipherSpec deprecations and re-enablement on both peers.
Attention: Alias CipherSpecs do not guarantee that a specific CipherSpec will be used on a running
channel, only that the negotiated CipherSpec is enabled and acceptable to IBM MQ on both ends
of the channel. To request that a specific CipherSpec is used by a channel, you must specify that
specific value on both ends of the channel.
If you add support for a new CipherSpec to the IBM MQ installations on the initiating and responding
ends of the channel, the alias CipherSpec will allow this new CipherSpec to be used automatically without
making any configuration changes.
Related tasks
Enabling CipherSpecs
Related reference
ALTER CHANNEL

Migrating IBM MQ Managed File Transfer

Use the following topics to guide you through various migration scenarios for IBM MQ Managed File
Transfer.

Migrating Managed File Transfer agents from an earlier version

Agents migrated from versions of IBM MQ prior to IBM MQ 9.1.4 run as non highly available. You can
make them run in high availability mode by carrying out the following procedure.

Procedure
1. Create the SYSTEM.FTE.HA.<agent name> queue in the agent queue manager using the following
sample definition:

DEFINE QLOCAL(SYSTEM.FTE.HA.SRC) +
DEFPRTY(0) +
DEFSOPT(SHARED) +
GET(ENABLED) +
MAXDEPTH(0) +
MAXMSGL(0) +
MSGDLVSQ(PRIORITY) +
PUT(ENABLED) +
RETINTVL(999999999) +
SHARE +
NOTRIGGER +
USAGE(NORMAL) +
REPLACE

2. Provide the required authorities on the queue for the agent to open the queue for GET.
3. Create a replica of the agent configuration on another machine
4. Add the highlyAvailable property, and set the property to true, in the agent.properties file for both
agent configurations.
Related concepts
Maintenance in highly available agents

Installing and migrating 475

 Migrating MFT to a new machine with a different operating system
The core steps required to successfully achieve a migration of MFT configurations to a new system or
platform. The task is primarily focused on MFT configuration migration, but also discusses queue manager
migration where appropriate.

Before you begin

Ensure that any agents you are going to migrate have completed any in-progress or pending transfers, and
that you have taken a back up of:
• The coordination queue manager
• Agent queue managers
• Agents
• Resource Monitors
• Transfer Templates
• Scheduled Transfers
Important: IBM MQ installation names on one system are unlikely to match the installation names on
the new system unless the old and new systems only have one installation, or you specify an installation
name as part of the IBM MQ installation process.

About this task

The following migration procedure is based on the scenario where QMA is both the coordination queue
manager for topology, and the agent queue manager for an agent called Agent1.
Agent1 has a monitor, transfer template and scheduled transfer. QMA also connects to a queue manager
called QMB running on another system using their sender and receiver channels for file transfers.

Figure 14. Migrating the MFT configuration on System 1

Attention: The following procedure explains only how to backup and restore MFT configurations.
If you are migrating MFT to a new machine with the same operating system, queue manager data
and log files can be backed up and restored by copying all the data files from the old system to the
appropriate directories on the new system.
However, if the new machine has a different operating system, it is not possible to migrate the data
files, because they are created platform specific.

Procedure
1. Backup procedure

476 Installing and migrating IBM MQ

 a) Save the queue manager configuration using the dmpmqcfg command to rebuild it later from its
definition.
For example:

dmpmqcfg -m QMA -a > /mq/backups/QMA.mqsc

b) Back up the configuration files for the agent that are stored under the IBM MQ data directory /
MQ_DATA_PATH/mqft
The mqft directory normally has three sub-directories, which are config, installation, and
logs. These contain agent installation data, configuration, and database logger files respectively.
If the agent is Protocol Bridge Agent, the ProtocolBridgeCredentials.xml file in the agent
configuration directory also needs to backed up. This file defines the user names and credential
information that the protocol bridge agent uses to authorize itself with the protocol server.
c) Export the configuration of the resource monitor to an XML file using the MFT ftelistMonitors
command with the -ox option.
For example:

fteListMonitors -ma Agent1 -mn Monitor -ox Monitor1Definition.xml

d) Export transfer templates to XML files using the MFT fteListTemplates command with the -x
and -o options.
For example, the following command creates TransferTemplate1.xml in the current directory:

fteListTemplates -x -o . TransferTemplate1

e) Manually back up the scheduled transfer definitions.

It is not possible to export the definitions to XML files, but you can list scheduled transfers using
the MFT fteListScheduledTransfers command and backing up the definitions manually.
2. Recreate procedure
a) Recreate queue manager QMA after installing IBM MQ and MFT on the new system.
b) Restore the QMA configuration by running the runmqsc command to parse in the queue manager
configuration saved in Step “1.a” on page 477
For example:

runmqsc QMA< /mq/backups/QMA.mqsc

c) Recreate the sender and receiver channels that connect to QMB on System two.
d) On the QMB queue manager side, update the connections details, such as host name and port
number of the sender channel that connects to QMA.
e) Recreate Agent1 by copying all of the backed up agent configuration files to the new system, and
start the agent.
f) Import the XML file for Monitor1 using the MFT fteCreateMonitor command with the -ix and -f
options.
For example:

fteCreateMonitor -ix Monitor1Definition.xml -f

g) Publish a message containing the contents of TransferTemplate1.xml in the message body to the
SYSTEM.FTE topic on the coordination queue manager.
Use a stand-alone application, and specify the topic string:

SYSTEM.FTE/Templates/<template_id>

where <template_id> is the transfer template ID that can be found inside the
TransferTemplate1.xml file.
For example, if the xml contains:

Installing and migrating 477

 <?xml version="1.0" encoding="UTF-8"?><transferTemplateid="a7838085-0f2a-4980-
b958-2dbbdfb22702"
version="6.00">

, the topic string should be:

SYSTEM.FTE/Templates/a7838085-0f2a-4980-b958-2dbbdfb22702

h) Recreate the scheduled transfers manually using the MFT fteCreateTransfers command.

Migrating IBM MQ Internet Pass-Thru

Follow this procedure to upgrade to a new version of IBM MQ Internet Pass-Thru (MQIPT), or to apply fix
pack maintenance to your MQIPT installation. You can also use this procedure to upgrade from MQIPT
support pack 2.1 to MQIPT in IBM MQ 9.1.

Procedure
1. Make backups of your data.
See Making backups for details.
2. Install the new version of MQIPT.
You can install the new version of MQIPT before uninstalling any versions of MQIPT that are currently
installed. See “Installing MQIPT” on page 272 for details.
3. Restore the backed-up data files to the MQIPT home directory to be used by the new installation.
If the MQIPT installation directory is used as the home directory, then overwrite any newly installed
copies of data files with the backed-up files.
4. Ensure that any properties that contain file names in the new mqipt.conf configuration file, refer to
files to be used by the new installation of MQIPT.
5. Review the list of changes and new features in the new version or fix pack of MQIPT.
If you need to make any changes to the MQIPT configuration for the new version, make the necessary
changes to the new copies of the data files.
6. Stop the current version of MQIPT by issuing the following command:

mqiptAdmin -stop

7. Start MQIPT at the latest version by issuing the following command:

• On AIX and Linux systems:

MQIPT_INSTALLATION_PATH/bin/mqipt MQIPT_HOME_DIR

• On Windows systems:

MQIPT_INSTALLATION_PATH\bin\mqipt MQIPT_HOME_DIR

where
• MQIPT_INSTALLATION_PATH is the directory where that latest version of MQIPT is installed.
• MQIPT_HOME_DIR is the MQIPT home directory containing the data files to be used by the latest
installation of MQIPT.
8. Test that MQIPT works correctly at the latest version.
After you confirm that the latest version of MQIPT is configured correctly, you can uninstall the
previous version. See “Uninstalling MQIPT” on page 274 for details.

478 Installing and migrating IBM MQ

9. If there are any passwords in your MQIPT configuration that have not been encrypted, or passwords
that were encrypted prior to MQIPT in IBM MQ 9.1.5, encrypt these passwords using the latest
protection method by following the procedure in Encrypting stored passwords.

Installing and migrating 479

480 Installing and migrating IBM MQ
Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently available in
your area. Any reference to an IBM product, program, or service is not intended to state or imply that
only that IBM product, program, or service may be used. Any functionally equivalent product, program, or
service that does not infringe any IBM intellectual property right may be used instead. However, it is the
user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents. You can
send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property
Department in your country or send inquiries, in writing, to:

Intellectual Property Licensing

Legal and Intellectual Property Law
IBM Japan, Ltd.
19-21, Nihonbashi-Hakozakicho, Chuo-ku
Tokyo 103-8510, Japan

The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM websites are provided for convenience only and do not in
any manner serve as an endorsement of those websites. The materials at those websites are not part of
the materials for this IBM product and use of those websites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of enabling: (i) the
exchange of information between independently created programs and other programs (including this
one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Corporation
Software Interoperability Coordinator, Department 49XA
3605 Highway 52 N
Rochester, MN 55901
U.S.A.

© Copyright IBM Corp. 2007, 2024 481

 Such information may be available, subject to appropriate terms and conditions, including in some cases,
payment of a fee.
The licensed program described in this information and all licensed material available for it are provided
by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or
any equivalent agreement between us.
Any performance data contained herein was determined in a controlled environment. Therefore, the
results obtained in other operating environments may vary significantly. Some measurements may have
been made on development-level systems and there is no guarantee that these measurements will be
the same on generally available systems. Furthermore, some measurements may have been estimated
through extrapolation. Actual results may vary. Users of this document should verify the applicable data
for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.
All statements regarding IBM's future direction or intent are subject to change or withdrawal without
notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the names and addresses used by an
actual business enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs
in any form without payment to IBM, for the purposes of developing, using, marketing or distributing
application programs conforming to the application programming interface for the operating platform
for which the sample programs are written. These examples have not been thoroughly tested under
all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these
programs.
If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Programming interface information

Programming interface information, if provided, is intended to help you create application software for
use with this program.
This book contains information on intended programming interfaces that allow the customer to write
programs to obtain the services of IBM MQ.
However, this information may also contain diagnosis, modification, and tuning information. Diagnosis,
modification and tuning information is provided to help you debug your application software.
Important: Do not use this diagnosis, modification, and tuning information as a programming interface
because it is subject to change.

Trademarks
IBM, the IBM logo, ibm.com®, are trademarks of IBM Corporation, registered in many jurisdictions
worldwide. A current list of IBM trademarks is available on the Web at "Copyright and trademark
information"www.ibm.com/legal/copytrade.shtml. Other product and service names might be trademarks
of IBM or other companies.
Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other countries, or
both.

482 Notices
UNIX is a registered trademark of The Open Group in the United States and other countries.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
This product includes software developed by the Eclipse Project (https://www.eclipse.org/).
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or
its affiliates.

Notices 483
484 Installing and migrating IBM MQ
IBM®

Part Number:

(1P) P/N: