[IBM MQ Advanced VUE][Windows][IBM MQ Advanced][Linux][MQ 9.2.0 Jul 2020]

Defining an Aspera gateway connection on Linux or Windows

The IBM® Aspera fasp.io Gateway provides a fast TCP/IP tunnel that can significantly increase network throughput for IBM MQ. A queue manager running on any entitled platform can connect through an Aspera gateway. The gateway itself is deployed on Red Hat® or Ubuntu Linux®, or Windows.

About this task

The Aspera gateway can be used to improve the performance of queue manager channels. It is especially effective if the network has high latency or tends to lose packets, and it is typically used to speed up the connection between queue managers in different data centers.

Note: For a fast network that does not lose packets there is a decrease in performance when using the Aspera gateway, so it is important to check network performance before and after defining an Aspera gateway connection.

You define an Aspera gateway at each end of the IP network connection, then use TCP/IP to connect queue manager channels to each gateway. A queue manager does not need to be running on the same machine as the Aspera gateway that it uses, and multiple queue managers can use the same gateway. The only restrictions are as follows:

To use the Aspera gateway, you must have one or more of the following entitlements:
  • IBM MQ Advanced for Multiplatforms
  • IBM MQ Appliance
  • IBM MQ Advanced for z/OS® VUE
You can deploy the Aspera gateway on any of the following Linux (Red Hat or Ubuntu) platforms, or on Windows: Use of the Aspera gateway is limited to IBM MQ messages unless the gateway is separately entitled.

Queue managers that use the Aspera gateway can be running on any supported platform. For a complete list of supported platforms, see Release and platform icons in the product documentation.

For each queue manager that is not on the same machine as the Aspera gateway that it uses, check that you have a fast network connection between the queue manager and the Aspera gateway.

You use a toml file to create a gateway definition that defines the inbound and outbound ports that the gateway uses. A sample toml file is shipped with the Aspera gateway. The outbound gateway definition defines the connection from the local queue manager to the gateway, and from the local gateway to the remote gateway. The inbound gateway definition defines the connection from the remote gateway to the local gateway, and from the local gateway to the local queue manager.

The following steps provide a basic guide to getting up and running. For more detailed information, see the IBM Aspera fasp.io Gateway documentation.

Procedure

  1. Get the Aspera gateway installation image.

    [UNIX, Linux, Windows, IBM i]For Multiplatforms, you download the Aspera gateway from Passport Advantage. The download is labeled IBM Aspera fasp.io Continuous Delivery Release for IBM MQ V9.2.x Multiplatform Multilingual eAssembly. It is delivered as a Continuous Delivery (CD) image only because of the pace of change in this area, which means that updates are needed at the frequency of the CD releases, and you can install it on any IBM MQ system that has IBM MQ Advanced for Multiplatforms or IBM MQ Appliance entitlement. To download this eAssembly, go to Downloading IBM MQ 9.2 then click the tab for the latest release. The eAssembly contains installation images for all platforms on which the gateway is available.

    [z/OS][MQ 9.2.0 Jul 2020]If your IBM MQ system has IBM MQ Advanced for z/OS VUE entitlement, you get the Aspera gateway from the Connector Pack component that is part of the SMP/E installation. See the IBM MQ Advanced for z/OS VUE program directory (IBM MQ for z/OS Program Directory PDF files) for more information. When the Connector Pack is installed, it creates a fasp directory in z/OS UNIX System Services that contains a set of compressed files. The files contain installation images for all platforms on which the gateway is available.

    [z/OS]The files for IBM MQ Advanced for z/OS VUE are as follows:
    Table 1. File names for Long Term Support and Continuous Delivery
    Platform Long Term Support Continuous Delivery
    File name fasp.io version number File name fasp.io version number
    Linux for x86-64

    [MQ 9.2.0 Jul 2020]CC6UIEN.zip

    1.1.0

    [MQ 9.2.0 Jul 2020]CC6UIEN.zip

    [MQ 9.2.2 Mar 2021]CC8R1EN.zip

    [MQ 9.2.3 Jul 2021]G01WVEN.zip

    1.1.0

    1.1.1

    1.2.0

    Linux on POWER Systems - Little Endian

    [MQ 9.2.0 Jul 2020]CC6UKEN.zip

    1.1.0

    [MQ 9.2.0 Jul 2020]CC6UKEN.zip

    [MQ 9.2.2 Mar 2021]CC8R2EN.zip

    [MQ 9.2.3 Jul 2021]G01WWEN.zip

    1.1.0

    1.1.1

    1.2.0

    Linux for IBM Z

    [MQ 9.2.0 Jul 2020]CC6ULEN.zip

    1.1.0

    [MQ 9.2.0 Jul 2020]CC6ULEN.zip

    [MQ 9.2.2 Mar 2021]CC8R3EN.zip

    [MQ 9.2.3 Jul 2021]G01WXEN.zip

    1.1.0

    1.1.1

    1.2.0

    Windows

    [MQ 9.2.0 Jul 2020]CC6UMEN.zip

    1.1.0

    [MQ 9.2.0 Jul 2020]CC6UMEN.zip

    [MQ 9.2.2 Mar 2021]CC8R4EN.zip

    [MQ 9.2.3 Jul 2021]G01WYEN.zip

    1.1.0

    1.1.1

    1.2.0

    [Continuous Delivery][MQ 9.2.0 Jul 2020]Note that the Aspera gateway cannot run natively on z/OS.

    [Long Term Support]Notes:
    • fasp.io version 1.1.1 is provided by APAR PH35485 on IBM MQ 9.2.0.
    • fasp.io version 1.2.0 is provided by APAR PH38832 on IBM MQ 9.2.0.
  2. Copy the Aspera gateway installation image onto the two machines that will run the gateway, then extract and install the gateway.
    [Linux]
    Install using RPM Package Manager (RPM):
    rpm -ivh ibm-fasp.io-gateway-<version>.x86_64.rpm
    To install using RPM on Ubuntu, you have two options:
    [Windows][MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]
    To install the Aspera gateway on Windows:
    1. Ensure that you are on a supported Windows machine, and are logged in with an account that has administrator privileges.
    2. Download the installer. The default location is the Downloads folder: ibm-fasp.io-gateway_<version>_win64.msi.
    3. Open the .msi file. When the installation wizard launches, follow the prompts to complete the installation.
  3. Configure each gateway.
    Modify the gateway.toml and logging.toml files in the directory that was created by the install:
    Linux
    [MQ 9.2.3 Jul 2021]From IBM Aspera fasp.io Gateway 1.2, the location is /usr/local/etc/faspio/.
    [MQ 9.2.2 Mar 2021]From IBM Aspera fasp.io Gateway 1.1, the location is /usr/local/etc/fasp.io/.
    For earlier versions of the Aspera gateway, the location is /etc/fasp.io/.
    Windows
    [MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]C:\Program Files\IBM\fasp.io Gateway\config\

    Use the gateway.toml file to define the inbound and outbound ports that the gateway uses, and the logging.toml file to define the level of logging that you require. An example of editing gateway.toml files is given later in this topic.

  4. At each end of the network connection, change the channel definition to connect to the port that the local gateway is listening on.
  5. Start each gateway service.
    From a command prompt, run the following command:
    • [Linux]
      systemctl start fasp.io-gateway
    • [Windows][MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]
      net start fasp.io-gateway
  6. Restart the channels.

    Your queue managers are now communicating across an Aspera gateway connection.

Example

This example defines an Aspera gateway connection on two machines running Linux. The configuration is as follows:
  • The IP address of the local gateway machine is 9.20.193.107. The IP address of the remote gateway machine is 9.20.192.115.
  • The local queue manager is running on a machine with IP address 9.20.121.5. The remote queue manager is running on a machine with IP address 9.20.121.25. Both queue managers are listening on port 1414.
  • The queue manager channel on the local queue manager is changed to connect to the local Aspera gateway using conname 9.20.193.107(1500). The queue manager channel on the remote queue manager is changed to connect to the remote Aspera gateway using conname 9.20.192.115(1500).
  • [MQ 9.2.3 Jul 2021]IBM Aspera fasp.io Gateway 1.2 enables TLS by default. In this example TLS has been disabled by setting tls_enabled=false in the gateway definitions. If running with an earlier version of the gateway, delete the tls_enabled=false lines. If you want to configure TLS with the gateway, see Securing the Gateway in the IBM Aspera fasp.io Gateway documentation.
  1. Define an Aspera gateway connection on the local gateway machine:
    • Install the Aspera gateway:
      • [Linux]On Linux, use the following command:
        rpm -ivh ibm-fasp.io-gateway-<version>.x86_64.rpm
      • [Windows][MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]On Windows, open the .msi file to run the installation wizard.
    • Modify the gateway.toml file in the directory that was created by the install:
      Linux
      [MQ 9.2.3 Jul 2021]From IBM Aspera fasp.io Gateway 1.2, the location is /usr/local/etc/faspio/.
      [MQ 9.2.2 Mar 2021]From IBM Aspera fasp.io Gateway 1.1, the directory is /usr/local/etc/fasp.io/.
      For earlier versions of the Aspera gateway, the directory is /etc/fasp.io/.
      Windows
      [MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]C:\Program Files\IBM\fasp.io Gateway\config\
      Edit the file to set the local gateway definitions.
      [[bridge]]
          name = "Outbound"
          [bridge.local]
                 protocol = "tcp"
                     host = "9.20.193.107"
                     port = 1500
          tls_enabled = false
      
          [bridge.forward]
                 protocol = "fasp"
                     host = "9.20.192.115"
                     port = 1600
          tls_enabled = false
      
      [[bridge]]
          name = "Inbound"
          [bridge.local]
                 protocol = "fasp"
                     host = "9.20.193.107"
                     port = 1600
          tls_enabled = false
      
          [bridge.forward]
                 protocol = "tcp"
                     host = "9.20.121.5"
                     port = 1414
          tls_enabled = false
      
  2. Repeat the previous step to define an Aspera gateway connection on the remote gateway machine. Modify the gateway.toml file in the directory that was created by the install:
    Linux
    [MQ 9.2.2 Mar 2021]From IBM Aspera fasp.io Gateway 1.1, the directory is /usr/local/etc/fasp.io/.
    For earlier versions of the Aspera gateway, the directory is /etc/fasp.io/.
    Windows
    [MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]C:\Program Files\IBM\fasp.io Gateway\config\
    Edit the file to set the remote gateway definitions:
    [[bridge]]
        name = "Outbound"
        [bridge.local]
               protocol = "tcp"
                   host = "9.20.193.107"
                   port = 1500
        tls_enabled = false
    
        [bridge.forward]
               protocol = "fasp"
                   host = "9.20.192.115"
                   port = 1600
        tls_enabled = false
    
    [[bridge]]
        name = "Inbound"
        [bridge.local]
               protocol = "fasp"
                   host = "9.20.193.107"
                   port = 1600
        tls_enabled = false
    
        [bridge.forward]
               protocol = "tcp"
                   host = "9.20.121.5"
                   port = 1414
        tls_enabled = false
    
  3. At each end of the connection, change the channel definition to connect to the port that the local gateway is listening on.
    • Change the queue manager channel on the local queue manager to connect to the local Aspera gateway using conname 9.20.193.107(1500).
    • Change the queue manager channel on the remote queue manager to connect to the remote Aspera gateway using conname 9.20.192.115(1500).
  4. Start the local gateway by running the following command on the local gateway machine:
    • [Linux]
      systemctl start fasp.io-gateway
    • [Windows][MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]
      net start fasp.io-gateway
  5. Start the remote gateway by running the following command on the remote gateway machine:
    • [Linux]
      systemctl start fasp.io-gateway
    • [Windows][MQ 9.2.0 Jul 2020][MQ 9.2.0 Jul 2020]
      net start fasp.io-gateway
  6. Restart the channels.

What to do next

The Aspera gateway passes on the data it receives, without interpreting it in any way. This means that you can configure TLS between the queue manager channels that are using the Aspera gateway because the gateway connection is unaware of the TLS handshaking. This also means that queue managers on any supported IBM MQ platform can use the Aspera gateway.

To use a multi-instance queue manager with the gateway, configure gateway definitions for each instance of the queue manager.

Note: The Aspera gateway has only been tested with queue manager channels. It has not been tested with client channels. This is because the envisaged use for the Aspera gateway is to connect remote queue managers over a slow network, whereas client applications typically connect to queue managers in a local datacenter over a fast network.