Configuring the Gateway
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:
/usr/local/etc/faspio/gateway.toml
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.Configuration examples
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:
Given a server listening on port
12345
, configure your client to point to Gateway 1 (GW1
IP) and
port 12345
:
GW1 Configuration | GW2 Configuration |
---|---|
|
|
- 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.
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:
GW1 configuration | GW2 configuration |
---|---|
|
|
Gateway configuration options
Bridge: HTTP-Out | Bridge: Smtp-Out | Bridge: MQ-In |
---|---|---|
|
|
|
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:
hostDeprecated and replaced with
bind_address
.
This is a required field.
bind_addressThis 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.
This is a required field.
Forward parameters:
hostThis 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.
protocolThis is a required field.
bind_addressThis is an optional field. It can be an IP address or a hostname and it specifies which interface to connect to.
portThis 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.
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,
[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.