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
IBM MQ Advanced for z/OS (Long Term Support only)

You can deploy the Aspera gateway on any of the following Linux (Red Hat or Ubuntu) platforms, or on Windows:

Linux for x86-64
Linux on POWER® Systems - Little Endian
Linux for IBM Z
Windows - for more information about platform support on Windows, see the IBM Aspera fasp.io Gateway documentation.

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

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.

[IBM MQ Advanced VUE] [IBM MQ Advanced for z/OS] If your IBM MQ system has IBM MQ Advanced for z/OS VUE entitlement, or Long Term Support IBM MQ Advanced for z/OS entitlement, you get the Aspera gateway from the Connector Pack component that is part of the SMP/E installation. For more information, see the IBM MQ Advanced for z/OS VUE or IBM MQ Advanced for z/OS Program Directories (IBM MQ for z/OS Program Directory PDF files). 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.

The files for IBM MQ Advanced for z/OS VUE and IBM MQ Advanced for z/OS are as follows:

Table 1. File names for Long Term Support and Continuous Delivery
Platform	Long Term Support		Continuous Delivery
Platform	File name	fasp.io version number	File name	fasp.io version number
Linux for x86-64	CC6UIEN.zip	1.1.0	CC6UIEN.zip CC8R1EN.zip G01WVEN.zip	1.1.0 1.1.1 1.2.0
Linux on POWER Systems - Little Endian	CC6UKEN.zip	1.1.0	CC6UKEN.zip CC8R2EN.zip G01WWEN.zip	1.1.0 1.1.1 1.2.0
Linux for IBM Z	CC6ULEN.zip	1.1.0	CC6ULEN.zip CC8R3EN.zip G01WXEN.zip	1.1.0 1.1.1 1.2.0
Windows	CC6UMEN.zip	1.1.0	CC6UMEN.zip CC8R4EN.zip 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.

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.

Copy the Aspera gateway installation image onto the two machines that will run the gateway, then extract and install the gateway.
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:
- Add the --force-debian attribute to the Aspera gateway install command, as explained in Installing an IBM MQ client on Linux using rpm.
- Use the apt-get command:
```
sudo apt-get install ./ibm-fasp.io-gateway_<version>_amd64.deb
```
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.
Configure each gateway.

Modify the gateway.toml and logging.toml files in the directory that was created by the install:

Linux

From IBM Aspera fasp.io Gateway 1.2, the location is /usr/local/etc/faspio/.

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

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.
At each end of the network connection, change the channel definition to connect to the port that the local gateway is listening on.
Start each gateway service.
From a command prompt, run the following command:
- ```
systemctl start fasp.io-gateway
```
- ```
net start fasp.io-gateway
```
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).
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.

Define an Aspera gateway connection on the local gateway machine:

Install the Aspera gateway:
- On Linux, use the following command:
```
rpm -ivh ibm-fasp.io-gateway-<version>.x86_64.rpm
```
- 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: From IBM Aspera fasp.io Gateway 1.2, the location is /usr/local/etc/faspio/.; 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: 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

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

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).
Start the local gateway by running the following command on the local gateway machine:
- ```
systemctl start fasp.io-gateway
```
- ```
net start fasp.io-gateway
```
Start the remote gateway by running the following command on the remote gateway machine:
- ```
systemctl start fasp.io-gateway
```
- ```
net start fasp.io-gateway
```
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.