Configuring the Gateway

Edit online

Configure two or more faspio Gateway servers to connect to each other.

The Gateway configuration file

The IBM Aspera faspio Gateway configuration file, gateway.toml, is located here:

Linux, macOS:
/usr/local/etc/faspio/gateway.toml
Windows:
C:\Program Files\IBM\faspio Gateway\config\gateway.toml

The gateway.toml file that is included in the installation is provided as a template. Modify this file to specify your ports, hostnames, and so on.

Every time that you modify gateway.toml to make changes for your configuration, you must restart the IBM Aspera faspio Gateway service. For more information on starting and stopping the Gateway service, see Starting faspio Gateway.
Note: The version of the FASP protocol that is included in faspio Gateway uses a single UDP port. Whatever port you configure for your FASP connection over the WAN must have the same UDP port open on any firewalls along the connection path.

Configuration examples

Important: For simplicity, the examples in the following section do not include security settings. After understanding how to configure the connection between servers, make sure to understand how to secure your servers. Security is enabled by default and you need to properly configure security settings before you can use your Gateway servers.

Example: Client to Server

In this configuration, two Gateways are used to establish a FASP bridge between two TCP/UDP connections, a TCP/UDP client, and a TCP/UDP server:

Note: UDP supports only one connection at a time. For some use cases, such as video or streaming services, the client side must establish communication.
Client to server example

Given a server listening on port 12345, configure your client to point to Gateway 1 (GW1 IP) and port 12345:

GW1 Configuration GW2 Configuration 
[[bridge]]
   [bridge.local]
       protocol = "tcp"
           host = "0.0.0.0"
           port = 12345
http_proxy_enabled = true
tls_enabled = false

   [bridge.forward]
       protocol = "fasp"
           host = "GW2"
           port = 12345
 
[[bridge]]
   [bridge.local]
       protocol = "fasp"
           host = "0.0.0.0"
           port = 12345

   [bridge.forward]
       protocol = "tcp"
           host = "Server"
           port = 12345
protocol
The transfer protocol type, either "tcp" or "fasp". The protocol type must be quoted.
host
The hostname or IP address, always quoted.
port
Either of these:
  • Port number (quoting optional, except for the port range).
  • Known port/service name (quoting required), such as "http" or "ftp-data".

You can specify a range or a list of numbered ports.

Port range:
  • Use a hyphen and quotation marks; for example, "100-110".
  • The range of port numbers must be ascending (low to high); for example, "100-110", but not "100-90".
  • The size of the range cannot exceed 50 ports.
  • If a port range is used, the range for the local port and the forward port must be the same size.
  • The ranges do not need to consist of the same ports. For example, the local range might be "501-509" and the forward range might be "511-519"; however, the forward range might not be "511-520".
List of ports:
  • Use commas and quotation marks; for example, "12345, 12347, 12349, 12351".
http_proxy_enabled
When set to true GW1 acts as an HTTP proxy.
tls_enabled
When set to true TLS is enabled for the bridge communication.
Port range configuration: Many to one port

You can now define a range of ports in the configuration file (toml) on the local interface, and a single port on the forward interface. This configuration allows you to add connections on a port range to a single port when forwarded.

Example: Many to one port

[[bridge]]
        name = "Bridge-many2one"
        [bridge.local]
                protocol = "fasp"
                port = "4142-4144"
                host = "0.0.0.0"
                tls_enabled = false

        [bridge.forward]
                protocol = "tcp"
                port = "12346"
                host = "127.0.0.1"
                tls_enabled = false

Example: List of ports

[[bridge]]
        name = "Bridge-port-list"
        [bridge.local]
                protocol = "fasp"
                port = "4142,4144"
                host = "0.0.0.0"
                tls_enabled = false

        [bridge.forward]
                protocol = "tcp"
                port = "12346,12348"
                host = "127.0.0.1"
                tls_enabled = false

Example: Port range

[[bridge]]
        name = "Bridge-port-range"
        [bridge.local]
                protocol = "fasp"
                port = "4142-4144"
                host = "0.0.0.0"
                tls_enabled = false

        [bridge.forward]
                protocol = "tcp"
                port = "12346-12348"
                host = "127.0.0.1"
                tls_enabled = false

Example: Forwarding to the first available host

For bridge.forward, Gateway can loop through an array of specified hostnames or IP addresses and forward to the first available host it finds. For example,

[bridge.forward]
       protocol = "fasp"
           host = ["GW2", "10.0.0.2"]
           port = 12345

A hostname can resolve to multiple IP addresses. If a hostname is specified, either as a single entry or as an entry within the array, each of its IP addresses are tried until a connection is established.

Example: Server to Server

For some use cases, such as DB replication or messaging services (like MQ or Event Streams), communication must be established by both sides. In this mode, each server initiates a connection to the other:

Server to server example
GW1 configuration GW2 configuration 
[[bridge]]
   name = "Outbound"
   [bridge.local]
       protocol = "tcp"
           host = "0.0.0.0"
           port = 12345

   [bridge.forward]
       protocol = "fasp"
           host = "GW2"
           port = 12345

[[bridge]]
   name = "Inbound"
   [bridge.local]
       protocol = "fasp"
           host = "0.0.0.0"
           port = 54321

   [bridge.forward]
       protocol = "tcp"
           host = "Server1"
           port = 54321
 
[[bridge]]
   name = "Outbound"
   [bridge.local]
       protocol = "tcp"
           host = "0.0.0.0"
           port = 54321

   [bridge.forward]
       protocol = "fasp"
           host = "GW1"
           port = 54321

[[bridge]]
   name = "Inbound"
   [bridge.local]
       protocol = "fasp"
           host = "0.0.0.0"
           port = 12345

   [bridge.forward]
       protocol = "tcp"
           host = "Server2"
           port = 12345



Gateway configuration options

Gateway can also be configured with multiple bridges, multiple ports, multiple destinations, and multiple services. The following image shows a single gateway that is configured with examples of these combinations.
Gateway configuration options
Bridge: HTTP-Out Bridge: Smtp-Out Bridge: MQ-In 
[[bridge]]
   name = "Http-Out"
   [bridge.local]
      protocol = "tcp"
        host = "0.0.0.0"
        port = "http"

   [bridge.forward]
      protocol = "fasp"
        host = "GW2"
        port = "http"

[[bridge]]
   name = "Smtp-Out"
   [bridge.local]
      protocol = "tcp"
        host = "0.0.0.0"
        port = 25

   [bridge.forward]
      protocol = "fasp"
        host = "GW3"
        port = 25

[[bridge]]
   name = "MQ-In"
   [bridge.local]
      protocol = "fasp"
        host = "0.0.0.0"
        port = 8414

   [bridge.forward]
      protocol = "tcp"
        host = "Server1"
        port = 8414
Binding to a specific address

This configuration lets you bind the forwarding connection to a specific NIC on the machine. To achieve this, add the option bind_address in the config file.

Local parameters:

host

Deprecated and replaced with bind_address.

protocol

This is a required field.

bind_address

This is a required field. It can be an IP address or a hostname, and it specifies which interface to listen on. 127.0.0.1 for the loopback interface, 0.0.0.0 to listen on all interfaces.

port

This is a required field.

Forward parameters:

host

This is a required field. Represents the remote host to connect to. It can either be a single IP address or hostname, and an array of IP addresses or hostnames. The hostname can also resolve to multiple IP addresses and the system attempts to connect to the first IP address and then the other ones if that fails.

protocol

This is a required field.

bind_address

This is an optional field. It can be an IP address or a hostname and it specifies which interface to connect to.

port

This is a required field.

Example: Binding to a specific address

[bridge.local]
           protocol = "tcp"
       bind_address = "127.0.0.1"
               port = 12345
        tls_enabled = false
    [bridge.forward]
           protocol = "fasp"
               host = "localhost"
               port = 12345
        tls_enabled = false

Configuring Prometheus for monitoring

Prometheus gathers and saves its measurements as time series data. The information about the metrics is kept along with the timestamp at which it was captured. To enable Prometheus, update the configuration to enabled = true. To disable Prometheus, keep the default value enabled = false.

To monitor the faspio Gateway by using Prometheus, use the following configuration:

[admin]
               host = "127.0.0.1"
               port = "8081"
        tls_enabled = true    # Set this to false to disable TLS
         cert_chain = "tls/gw1_cert_chain.pem"

 prometheus_enabled = true
    prometheus_auth = "basic"

[admin.basic_auth]
           username = "test"
    password_digest = "$sha-512$esJ0jf7Jc4D8jvjjRauf0ExWrHXG6jvzGx4mIe6X3dh4A87bQEuLRJnY4md+l4teeMaubIK85EFUFoqdmak4Ig==$Rhhk3CrSSyemgrBP"

Configure the parameters that Prometheus uses to receive the data for the monitoring metrics. The following are the parameters:

host
IP address or hostname of the interface to listen on. Default: 127.0.0.1.
port
Port number to listen on. Default: 8080.
tls_enabled
Secure Prometheus endpoint with TLS. Default: true.
cert_chain
Path to the SSL certificate file. The file must be in PEM format and it must have both the private key and the certificate. Default: ' '.
prometheus_enabled
Enable or disable displaying metrics through Prometheus. Default: false.
prometheus_auth
Specify the authentication type. Set it to "basic" or "none". Default: basic.
username
The name of the user that must be authenticated.
password_digest
The password digest of the user that must be authenticated.
Note: If TLS is enabled for a bridge and cert_key is not defined, the gateway defaults to certificate and cert_chain for the private key. For example, this allows the same cert_chain path to be used for both bridges and Prometheus.

Password digest

To generate the password digest, run the following command:

faspio-gateway digest

Follow the prompts so the output gives the password digest that you need to add to the gateway.toml along with the wanted username. Add the values under the [admin.basic_auth] section as in the following example,

Note: Create the [admin.basic_auth] section if it does not exist in the gateway.toml file.
[admin.basic_auth]
           username = "test"
           password_digest = "$sha-512$BPd2kBmlW+f7pTc/pFPiSwBCOMYqpPqzyWN9VVPyY/JssqdO0J5f6Zie6+MIbv9r8ntTPUv/mWHmbiRUYnwJmg==$EcsNAKGiEWTMbQwI"

For more information, see Starting faspio Gateway.