I recently received a query from a customer who wanted to move some of their queue managers from one TCP/IP subnet to another. These queue managers were gateways to external partners so as well as changing the subnet they also had to update their firewall, their DNS servers and various remote endpoints that use fixed IP addresses to connect. Coordinating all of these updates to occur within a single change window would have been challenging at best. The customer’s query was therefore asking what features are available in IBM MQ that allow them to gradually apply the necessary changes instead. This blog post describes the features that the customer in question could use to achieve their goal, and which anyone else can also use if they wish to exploit multiple TCP/IP stacks, such as when employing network isolation for different queue managers or business applications.
Inbound queue manager connections
All inbound connections to a queue manager must connect to a process known as a listener. Listeners accept network requests from either remote queue managers or clients and start channels as necessary to allow messages and API requests to flow between endpoints. As such, it is the listener definition that we must look at to see how inbound connections can be tailored. The important listener attributes we need to consider are TRPTYPE, PORT and IPADDR.
The TRPTYPE attribute specifies the transmission protocol the listener must use to communicate. Depending on the platform, there are various values that can be specified for this attribute, but the only value we consider in this blog post is TCP, which indicates that TCP/IP is to be used. If a queue manager must accept connections over multiple protocols then at least one listener must be defined for each protocol. For more information about the different transmission protocols that are supported see the IBM KnowledgeCenter topic Which communication type to use.
The PORT attribute specifies the TCP/IP port to which the listener must bind to accept incoming connections. Multiple listeners can be defined using different ports to isolate inbound connections from each other.
The IPADDR attribute specifies the IP address the listener must use, which can be specified as either an IPv4 dotted decimal value, an IPv6 hexadecimal string, or an alphanumeric host name. It is this attribute that is the most significant for systems with multiple TCP/IP stacks. If a value is specified then the listener uses the TCP/IP stack that is associated with the IP address or host name. If a value is not specified then the listener accepts connections from all configured IPv4 and IPv6 stacks.
On z/OS the queue manager attributes TCPSTACK and TCPNAME can be used to restrict which TCP/IP stacks can be used by the channel initiator and its listeners. If TCPSTACK is set to SINGLE instead of MULTIPLE then only the TCP/IP stack specified to TCPNAME is used. These attributes are not available on other platforms.
Some useful topics in IBM KnowledgeCenter about listeners are:
- Listeners (concepts)
- The DEFINE LISTENER command (distributed)
- The START LISTENER command (z/OS)
- The runmqlsr control command (distributed)
Outbound queue manager connections
Outbound connections from a queue manager are established by channel processes so it is the channel definition that we must look at to see how outbound connections can be tailored. The important channel attributes we need to consider are TRPTYPE, LOCLADDR and CONNAME, although TCPSTACK and TCPNAME also apply on z/OS.
As per for listeners, the TRPTYPE attribute specifies the transmission protocol the channel must use to communicate. Once again, the only value we consider in this blog post is TCP, which indicates that TCP/IP is to be used. If a queue manager must establish outbound connections over multiple protocols then at least one channel must be defined for each protocol.
By default the local IP address and port allocated to an outbound connection is automatically assigned by the system on which MQ is running using local routing preferences. The LOCLADDR attribute can be used to configure the channel to use a specific port range and/or a list of possible IP addresses. The ability to restrict these values is important if the channel needs to communicate through a firewall or if the remote endpoint has specific requirements, such as only accepting IPv4 connections. If multiple values are specified then the channel establishes a connection using any of the ports and IP addresses that are defined, dependent on their availability. This behaviour is particularly useful for a multi-instance queue manager, which can be started on different servers, each with their own unique identity on the network.
If a value is not specified for LOCLADDR, or a host name is specified that resolves to both an IPv4 and an IPv6 address then the value of the CONNAME attribute is used to determine which TCP/IP protocol to use. If the value of CONNAME is also a host name that is available for both IPv4 and IPv6 then the IPADDRV queue manager attribute is used to identify which TCP/IP stack should be used.
On distributed platforms it is possible to set a default local address value to be used for all outbound channels that do not have a value specified for LOCLADDR. The default value has the same syntax as the channel attribute and is defined by setting the environment variable MQ_LCLADDR before the queue manager is started. Note that the spelling is slightly different. This environment variable is described in the Integrating the IBM MQ Appliance into your IBM MQ Infrastructure RedBook, but it is not specific to the appliance.
The ability to set a default local address was particularly useful for the customer to which I referred above because they could continue to use their existing subnet as the default until they had gradually migrated all of their channels to the new one. Specifying a default local address for MQ is also particularly important for cluster sender channels on hosts where using the system’s default TCP/IP stack and port range is not sufficient. Each cluster sender channel definition is based on the values that are specified for its corresponding cluster receiver channel. Specifying an IP address or host name via LOCLADDR on a cluster receiver channel is rarely appropriate because the corresponding cluster sender channels are not usually active on the same host. The attribute can be used to restrict the local port range, but care must be taken to ensure this is valid throughout the cluster. If you don’t want to set the environment variable, or your queue managers are running on a platform such as z/OS, then you can alternatively use a channel auto-definition exit to set the attribute instead.
Some useful topics in IBM KnowledgeCenter about channels are:
Client connections can also be customized to use a specific TCP/IP stack when establishing communication with a queue manager. The following options are available:
- The MQIPADDRV environment variable can be set to either MQIPADDR_IPv4 or MQIPADDR_IPv6 to specify that a specific TCP/IP protocol should be used.
- The IPAddressVersion attribute can be specified in the TCP stanza of the client configuration file, which is usually called mqclient.ini.
- The LocalAddress field can be set in the MQ Channel Definition (MQCD) structure that is provided to MQCONNX - see the client connection parameter in the MQCNO.
- The connection factory method setLocalAddress() can be called to set the local address to use for a JMS client.
- A Client Channel Definition Table (CCDT) can be used with client-connection channels that have a value specified for LOCLADDR.
This blog post has described some of the features that are available to customize TCP/IP communication in IBM MQ. It is not intended to be an exhaustive list of every available option you can use, but hopefully it provides a useful overview and starting point for anyone that needs to tune the settings used by queue managers and clients.